fix(data): bound metadata version cache

spec.md

@@ -66,6 +66,7 @@ When `--version 4.3.5` is requested, `loadMetadataForVersion("4.3.5")` resolves
 ### Data Layer Notes
 
 - On load, component props are deduplicated by name (first entry wins).
+- Historical metadata is cached for up to 32 requested version keys per process; inserting another version evicts the oldest cached entry.
 - The extraction script handles `\|` (escaped pipes in markdown table cells) by replacing them with a placeholder before splitting. This ensures multi-value union types like `` `primary` \| `dashed` \| `link` `` are stored correctly as `` `primary` | `dashed` | `link` `` instead of being split across wrong columns.
 - Each version file contains both `en` and `zh` descriptions, keyed by language
 - `semantic` data extracted from `components/*/demo/_semantic.tsx` files

src/__tests__/version-loader.test.ts

@@ -237,6 +237,19 @@ describe('data/loader', () => {
     expect(a).toBe(b);
   });
 
+  it('evicts the oldest metadata cache entry after 32 unique versions', () => {
+    const versions = Array.from({ length: 33 }, (_, index) => `98.${1000 + index}.0`);
+    const oldest = loadMetadataForVersion(versions[0]);
+
+    for (const version of versions.slice(1, 32)) {
+      loadMetadataForVersion(version);
+    }
+    expect(loadMetadataForVersion(versions[0])).toBe(oldest);
+
+    loadMetadataForVersion(versions[32]);
+    expect(loadMetadataForVersion(versions[0])).not.toBe(oldest);
+  });
+
   it('findComponent is case-insensitive', () => {
     const store = loadMetadata('v5');
     expect(findComponent(store, 'BUTTON')?.name).toBe('Button');

src/data/loader.ts

@@ -94,6 +94,7 @@ export function loadMetadata(majorVersion: string): MetadataStore {
  * 2. Nearest earlier minor               (e.g. requested 4.2.5 but only 4.1.x exists → use 4.1.x)
  * 3. Fall back to loadMetadata(majorVersion) (i.e. data/v4.json)
  */
+const MAX_METADATA_CACHE_ENTRIES = 32;
 const metadataCache = new Map<string, MetadataStore>();
 
 export function loadMetadataForVersion(version: string): MetadataStore {
@@ -102,6 +103,11 @@ export function loadMetadataForVersion(version: string): MetadataStore {
 
   const result = loadMetadataForVersionUncached(version);
   metadataCache.set(version, result);
+  while (metadataCache.size > MAX_METADATA_CACHE_ENTRIES) {
+    const oldestKey = metadataCache.keys().next().value;
+    if (oldestKey === undefined) break;
+    metadataCache.delete(oldestKey);
+  }
   return result;
 }