@commonpub/layer 0.24.0 → 0.25.1

package/sections/registry.ts

@@ -35,6 +35,11 @@ import { hubsSection } from './builtin/hubs';
 import { contestsSection } from './builtin/contests';
 import { learningSection } from './builtin/learning';
 import { customHtmlSection } from './builtin/custom-html';
+import { ctaSection } from './builtin/cta';
+import { markdownSection } from './builtin/markdown';
+import { gallerySection } from './builtin/gallery';
+import { videoSection } from './builtin/video';
+import { embedSection } from './builtin/embed';
 
 // Singleton — registered once at module load. Vue/Nuxt's setup() runs
 // per-component, but module load is once per app process. Safe.
@@ -69,6 +74,12 @@ registry.register(hubsSection);
 registry.register(contestsSection);
 registry.register(learningSection);
 registry.register(customHtmlSection);
+// Phase 6b additions (session 159)
+registry.register(ctaSection);
+registry.register(markdownSection);
+registry.register(gallerySection);
+registry.register(videoSection);
+registry.register(embedSection);
 
 /**
  * Read-only accessor — the layer's standard pattern for shared state.

package/server/api/admin/homepage/sections.put.ts

@@ -1,5 +1,6 @@
-import { setHomepageSections } from '@commonpub/server';
+import { setHomepageSections, migrateHomepageSectionsToLayout } from '@commonpub/server';
 import { z } from 'zod';
+import { invalidateLayoutsByRouteCache } from '../../../utils/layoutCache';
 
 const sectionConfigSchema = z.object({
   contentType: z.string().max(64).optional(),
@@ -48,5 +49,55 @@ export default defineEventHandler(async (event) => {
 
   await setHomepageSections(db, body.sections, user.id, getRequestIP(event) ?? undefined);
 
+  // When the layout engine is on, the legacy `homepage.sections` JSON
+  // is no longer what /pages/index.vue renders — the page reads from
+  // the `layouts` table. Without this sync, admin edits made via the
+  // existing homepage editor (which still writes homepage.sections,
+  // because the Phase 3 layout editor isn't built yet) would have
+  // ZERO visible effect on the live page.
+  //
+  // Fix: after the legacy save succeeds, if layoutEngine is on,
+  // **R4 audit P0 data-loss fix (session 160)**: previously this called
+  // migrateHomepageSectionsToLayout with force:true on every legacy save,
+  // which DELETES the existing layout (cascade → rows, sections,
+  // VERSIONS). If an admin had bespoke-edited the homepage via /admin/
+  // layouts, those edits + the entire publish history were silently
+  // destroyed the next time anyone touched /admin/homepage. Same data-
+  // loss path also hit the audit log if two admins were editing in
+  // parallel.
+  //
+  // New semantics: NON-DESTRUCTIVE auto-sync. If a layout doesn't yet
+  // exist for ('route','/'), create it from the legacy data so the
+  // first-time operator's legacy edits keep working. If a layout DOES
+  // exist, leave it alone — the new editor is the source of truth from
+  // that point forward. /admin/homepage now shows a deprecation banner
+  // (see the page itself) directing operators to /admin/layouts.
+  //
+  // History: original auto-sync added session 159 (per the comment
+  // above) to handle "I removed a section in /admin/homepage but it
+  // still renders" — that scenario still works on first-time admins
+  // since the layout gets created on first save. After the operator
+  // adopts the layout editor, /admin/homepage becomes effectively
+  // read-only with respect to the live homepage; the legacy data still
+  // saves into instance_settings for backward-compat but is no longer
+  // promoted.
+  const config = useConfig();
+  if (config.features.layoutEngine) {
+    try {
+      const result = await migrateHomepageSectionsToLayout(db, {
+        adminId: user.id,
+        force: false, // changed from true — see comment above
+      });
+      if (result.migrated) {
+        invalidateLayoutsByRouteCache();
+      }
+    } catch (err) {
+      // Don't fail the user's save just because the layout sync hit a
+      // hiccup. Log + return — they can re-trigger the migration via
+      // the dedicated /api/admin/layouts/migrate-homepage endpoint.
+      console.error('[admin:homepage.sections] post-save layout sync failed:', err);
+    }
+  }
+
   return { sections: body.sections, message: 'Homepage updated' };
 });

package/server/api/admin/layouts/[id]/publish.post.ts

@@ -28,6 +28,18 @@ export default defineEventHandler(async (event) => {
   }
 
   const version = await publishLayout(db, id, { publishedBy: admin.id });
+
+  // Audit log (round 3): publish changes what the public sees — highest-
+  // leverage action. layout_versions also stores publishedBy (durable trail);
+  // stdout adds incident-response greppability.
+  console.info('cpub.audit.layout.publish', JSON.stringify({
+    at: new Date().toISOString(),
+    adminId: admin.id,
+    layoutId: id,
+    scope: existing.scope,
+    versionId: (version as { id?: string } | null | undefined)?.id ?? null,
+  }));
+
   invalidateLayoutsByRouteCache();
   return version;
 });

package/server/api/admin/layouts/[id]/versions/[versionId]/revert.post.ts

@@ -31,6 +31,17 @@ export default defineEventHandler(async (event) => {
 
   try {
     const reverted = await revertToVersion(db, id, versionId, { userId: admin.id });
+
+    // Audit log (round 3): revert overwrites current state with a prior
+    // snapshot — destructive transformation, deserves forensic trail.
+    console.info('cpub.audit.layout.revert', JSON.stringify({
+      at: new Date().toISOString(),
+      adminId: admin.id,
+      layoutId: id,
+      scope: existing.scope,
+      versionId,
+    }));
+
     invalidateLayoutsByRouteCache();
     return reverted;
   } catch (e) {

package/server/api/admin/layouts/[id].delete.ts

@@ -15,7 +15,7 @@ import { invalidateLayoutsByRouteCache } from '../../../utils/layoutCache';
 export default defineEventHandler(async (event): Promise<{ ok: true; id: string }> => {
   requireFeature('admin');
   requireFeature('layoutEngine');
-  requireAdmin(event);
+  const admin = requireAdmin(event);
   const db = useDB();
 
   const id = getRouterParam(event, 'id');
@@ -28,6 +28,38 @@ export default defineEventHandler(async (event): Promise<{ ok: true; id: string
     throw createError({ statusCode: 404, statusMessage: 'Layout not found' });
   }
 
+  // R4 audit P1 fix: homepage scope special-case. Deleting the
+  // ('route', '/') layout nukes the homepage + its entire publish
+  // history. The list-page UI already confirm()s before DELETE, but
+  // the API can also be called directly — require an explicit
+  // X-Cpub-Confirm-Homepage-Delete: 1 header for the homepage scope
+  // as defense-in-depth. Surfaces operator footgun loudly + audit log
+  // still captures the action when the header is set.
+  const isHomepage =
+    existing.scope.type === 'route' && existing.scope.path === '/';
+  if (isHomepage && getHeader(event, 'x-cpub-confirm-homepage-delete') !== '1') {
+    throw createError({
+      statusCode: 409,
+      statusMessage: 'Refusing to delete the homepage layout without explicit confirmation',
+      data: {
+        code: 'HOMEPAGE_DELETE_NEEDS_CONFIRM',
+        hint: 'Set X-Cpub-Confirm-Homepage-Delete: 1 header to override.',
+      },
+    });
+  }
+
+  // Audit log (session 160 audit P2). Layout deletion is destructive +
+  // not recoverable; structured stdout line gives operators a forensic
+  // trail when an admin reports "the homepage layout disappeared".
+  console.info('cpub.audit.layout.delete', JSON.stringify({
+    at: new Date().toISOString(),
+    adminId: admin.id,
+    layoutId: id,
+    scope: existing.scope,
+    name: existing.name,
+    state: existing.state,
+  }));
+
   await deleteLayout(db, id);
   invalidateLayoutsByRouteCache();
   return { ok: true, id };

package/server/api/admin/layouts/[id].put.ts

@@ -8,12 +8,21 @@
  * Scope CANNOT be changed via PUT (it's immutable per layout). A scope
  * change would mean a new layout — POST instead.
  *
+ * Optimistic concurrency (Phase 3a.6): if the request includes an
+ * `If-Match` header, it must equal the layout's current `updatedAt`.
+ * Mismatch → 412 Precondition Failed (or 409 if we want to match
+ * the editor's existing handler — RFC 7232 says 412, but pragmatic
+ * web editors use 409. We follow editor convention: 409 conflict).
+ * Omit the header (or pass empty string) to force an unconditional
+ * write (the "overwrite" path from the conflict modal).
+ *
  * Admin + features.admin + features.layoutEngine.
  * Invalidates the layouts-by-route cache on success.
  */
 import { layoutCreateSchema } from '@commonpub/schema';
 import { getLayoutById, saveLayout } from '@commonpub/server';
 import { invalidateLayoutsByRouteCache } from '../../../utils/layoutCache';
+import { validateSectionConfigs } from '../../../utils/validateSectionConfigs';
 
 export default defineEventHandler(async (event) => {
   requireFeature('admin');
@@ -31,8 +40,59 @@ export default defineEventHandler(async (event) => {
     throw createError({ statusCode: 404, statusMessage: 'Layout not found' });
   }
 
+  // Optimistic concurrency check — client sends If-Match: <updatedAt>;
+  // mismatch means someone else saved in between. The client's auto-save
+  // catches the 409 and pops a conflict modal (3a.6).
+  const ifMatch = getHeader(event, 'if-match');
+  if (ifMatch && ifMatch.trim() !== '' && ifMatch !== existing.updatedAt) {
+    throw createError({
+      statusCode: 409,
+      statusMessage: 'Layout was modified by another session',
+      data: {
+        code: 'LAYOUT_CONFLICT',
+        clientUpdatedAt: ifMatch,
+        serverUpdatedAt: existing.updatedAt,
+      },
+    });
+  }
+
+  // Audit log: client signals deliberate force-save via X-Cpub-Force-Save
+  // when the user clicks "Overwrite their changes" in the conflict modal.
+  // Forensic trail captures who overwrote what + when (audit P2 from
+  // session 160). Structured for greppability — operators can `docker
+  // logs ... | grep cpub.audit.layout.force-save`.
+  if (getHeader(event, 'x-cpub-force-save') === '1') {
+    console.info('cpub.audit.layout.force-save', JSON.stringify({
+      at: new Date().toISOString(),
+      adminId: admin.id,
+      layoutId: id,
+      scope: existing.scope,
+      previousUpdatedAt: existing.updatedAt,
+    }));
+  }
+
   const body = await parseBody(event, layoutCreateSchema);
 
+  // Per-section configSchema enforcement (R2 P1 deferred → wired session 161
+  // once schemas moved to @commonpub/schema/sectionConfigs, removing the
+  // .vue transitive import that broke the Nitro bundle on the R2 attempt).
+  // On failure logs an audit event + re-throws the validator's 400.
+  try {
+    validateSectionConfigs(body.zones);
+  } catch (err) {
+    const e = err as { data?: { code?: string; sectionErrors?: unknown[] } };
+    if (e?.data?.code === 'SECTION_CONFIG_INVALID') {
+      console.info('cpub.audit.layout.config-rejected', JSON.stringify({
+        at: new Date().toISOString(),
+        adminId: admin.id,
+        layoutId: id,
+        scope: existing.scope,
+        errorCount: e.data.sectionErrors?.length ?? 0,
+      }));
+    }
+    throw err;
+  }
+
   // Scope is immutable — reject if the client tries to change it. This
   // catches an "edit the wrong layout" bug at the API surface rather
   // than silently moving sections to a new route.
@@ -59,6 +119,24 @@ export default defineEventHandler(async (event) => {
     { id, userId: admin.id },
   );
 
+  // Audit log: every successful update goes through cpub.audit.layout.update.
+  // Per session 163 deep audit: the gap between "5 mutations should log
+  // (create/update/publish/delete/migrate)" (session 160 R3 plan) and the
+  // current implementation (force-save + config-rejected only) was a
+  // forensic blind spot — regular auto-saves left zero trail. Operators
+  // can grep + filter; the `source` header lets them separate manual saves
+  // from auto-saves vs beacons vs force-saves. Default 'auto' for legacy
+  // clients that don't send the header.
+  const saveSource = getHeader(event, 'x-cpub-save-source') ?? 'auto';
+  console.info('cpub.audit.layout.update', JSON.stringify({
+    at: new Date().toISOString(),
+    adminId: admin.id,
+    layoutId: id,
+    scope: existing.scope,
+    source: saveSource,
+    savedUpdatedAt: saved.updatedAt,
+  }));
+
   invalidateLayoutsByRouteCache();
   return saved;
 });

package/server/api/admin/layouts/index.post.ts

@@ -12,8 +12,9 @@
  * Invalidates the layouts-by-route cache on success.
  */
 import { layoutCreateSchema } from '@commonpub/schema';
-import { getLayoutByScope, saveLayout } from '@commonpub/server';
+import { getLayoutByScope, saveLayout, validateCustomPageScope } from '@commonpub/server';
 import { invalidateLayoutsByRouteCache } from '../../../utils/layoutCache';
+import { validateSectionConfigs } from '../../../utils/validateSectionConfigs';
 
 export default defineEventHandler(async (event) => {
   requireFeature('admin');
@@ -23,18 +24,62 @@ export default defineEventHandler(async (event) => {
 
   const body = await parseBody(event, layoutCreateSchema);
 
-  const existing = await getLayoutByScope(db, body.scope);
+  // Per-section configSchema enforcement (R2 P1 deferred → wired session 161
+  // once schemas moved to @commonpub/schema/sectionConfigs). On failure logs
+  // an audit event + re-throws the validator's 400; otherwise no-ops.
+  try {
+    validateSectionConfigs(body.zones);
+  } catch (err) {
+    const e = err as { data?: { code?: string; sectionErrors?: unknown[] } };
+    if (e?.data?.code === 'SECTION_CONFIG_INVALID') {
+      console.info('cpub.audit.layout.config-rejected', JSON.stringify({
+        at: new Date().toISOString(),
+        adminId: admin.id,
+        layoutId: null, // POST = create; no id yet
+        scope: body.scope,
+        errorCount: e.data.sectionErrors?.length ?? 0,
+      }));
+    }
+    throw err;
+  }
+
+  // Custom-page paths get extra validation: pathNormalize + file-route
+  // conflict + duplicate detection (Phase 2). Returns 400 for malformed
+  // paths, 409 for collisions. The route-scope + virtual paths go
+  // straight to the existing exists-check below — those types aren't
+  // operator-creatable in v1 anyway.
+  let scopeToSave = body.scope;
+  if (body.scope.type === 'custom-page') {
+    const validation = await validateCustomPageScope(db, body.scope.path);
+    if (!validation.ok) {
+      // 'has-query', 'has-fragment', 'has-dot-segment', 'invalid-char',
+      // 'empty' → 400 (malformed)
+      // 'reserved-prefix', 'file-route-conflict',
+      // 'custom-page-already-exists' → 409 (collision)
+      const status = (validation.reason === 'reserved-prefix'
+        || validation.reason === 'file-route-conflict'
+        || validation.reason === 'custom-page-already-exists') ? 409 : 400;
+      throw createError({
+        statusCode: status,
+        statusMessage: validation.message,
+        data: { reason: validation.reason },
+      });
+    }
+    scopeToSave = validation.scope;
+  }
+
+  const existing = await getLayoutByScope(db, scopeToSave);
   if (existing) {
     throw createError({
       statusCode: 409,
-      statusMessage: `A layout already exists for scope ${JSON.stringify(body.scope)}; PUT to /api/admin/layouts/${existing.id} to update it`,
+      statusMessage: `A layout already exists for scope ${JSON.stringify(scopeToSave)}; PUT to /api/admin/layouts/${existing.id} to update it`,
     });
   }
 
   const saved = await saveLayout(
     db,
     {
-      scope: body.scope,
+      scope: scopeToSave,
       name: body.name,
       pageMeta: body.pageMeta,
       zones: body.zones,
@@ -43,6 +88,17 @@ export default defineEventHandler(async (event) => {
     { userId: admin.id },
   );
 
+  // Audit log (round 3): every new layout creation is forensically
+  // significant — admins creating routes/custom-pages from scratch.
+  console.info('cpub.audit.layout.create', JSON.stringify({
+    at: new Date().toISOString(),
+    adminId: admin.id,
+    layoutId: saved.id,
+    scope: saved.scope,
+    name: saved.name,
+    state: saved.state,
+  }));
+
   invalidateLayoutsByRouteCache();
   return saved;
 });

package/server/api/admin/layouts/migrate-homepage.post.ts

@@ -49,6 +49,18 @@ export default defineEventHandler(async (event) => {
     force,
   });
 
+  // Audit log (round 3): migrate-homepage is the one-time destructive
+  // transformation that lifts an instance from the legacy renderer to
+  // the layout engine. Forensic trail for "the migration ate my homepage".
+  console.info('cpub.audit.layout.migrate-homepage', JSON.stringify({
+    at: new Date().toISOString(),
+    adminId: admin.id,
+    migrated: result.migrated,
+    force,
+    layoutId: (result as { layoutId?: string }).layoutId ?? null,
+    reason: (result as { reason?: string }).reason ?? null,
+  }));
+
   if (result.migrated) {
     invalidateLayoutsByRouteCache();
   }

package/server/api/admin/layouts/seed-homepage.post.ts

@@ -28,7 +28,16 @@ export default defineEventHandler(async (event) => {
   const db = useDB();
 
   const result = await seedHomepageLayout(db, { adminId: admin.id });
+
+  // Audit log (round 3): seed is idempotent but the first-call creates
+  // the initial homepage layout — significant for "when did the layout
+  // engine first come online on this instance?".
   if (result.created) {
+    console.info('cpub.audit.layout.seed-homepage', JSON.stringify({
+      at: new Date().toISOString(),
+      adminId: admin.id,
+      layoutId: (result as { layoutId?: string }).layoutId ?? null,
+    }));
     invalidateLayoutsByRouteCache();
   }
   return result;

package/server/api/layouts/by-route.get.ts

@@ -2,9 +2,22 @@
  * GET /api/layouts/by-route?path=/some-path
  *
  * Public endpoint — resolves the active layout for a route, used by the
- * `<LayoutSlot>` renderer on every page request. Returns the published
- * version when available, otherwise the draft (during pre-publish
- * editing — admins see drafts, end users get a 404 until published).
+ * `<LayoutSlot>` renderer on every page request.
+ *
+ * **Admins-only drafts (session 160 audit — P0 fix)**: anonymous +
+ * non-admin authenticated requests see the layout ONLY when its
+ * `state === 'published'`. Drafts return null (404 in the cache, no
+ * layout in the response). Admins see the live draft state regardless
+ * — this is what enables WYSIWYG editing via `<LayoutSlot
+ * previewOverride>`.
+ *
+ * The check uses `getOptionalUser` (does not throw on unauthenticated)
+ * because the endpoint MUST stay public for published-state layouts;
+ * 401-ing anonymous users would break SSR for any logged-out visitor.
+ *
+ * Cache key includes the "admin?" boolean so admins + anonymous don't
+ * cross-contaminate (an admin's draft-aware response would leak to an
+ * anonymous hit on the same key).
  *
  * Cached server-side for `LAYOUT_CACHE_TTL_MS` per path (see
  * `server/utils/layoutCache.ts`). Invalidated on any layout write —
@@ -42,8 +55,26 @@ export default defineEventHandler(async (event): Promise<PublicLayoutSlice | nul
     throw createError({ statusCode: 404, statusMessage: 'Layout engine not enabled' });
   }
 
-  const { path } = parseQueryParams(event, layoutsByRoutePathSchema);
-  const cacheKey = path;
+  const { path: rawPath } = parseQueryParams(event, layoutsByRoutePathSchema);
+  // Session 163 deep audit: normalize trailing slash so `/blog` and
+  // `/blog/` hit the SAME cache entry + DB lookup. Without this, the
+  // cache stores both forms separately AND a layout saved under `/blog`
+  // is unreachable when requested as `/blog/`. Root is special-cased
+  // (no slash to strip). Future tightening: enforce canonical form at
+  // POST/PUT write time too — for now the read-side normalize covers
+  // the actual user-visible bug (cached duplication + accidental misses).
+  const path = rawPath === '/' ? '/' : rawPath.replace(/\/+$/, '');
+
+  // Session 160 audit: admins see drafts + admin-access layouts;
+  // members see published members-and-public layouts; anonymous only
+  // sees public published layouts. Cache key trifurcates on the
+  // requester's access tier so a layout served to a higher tier can't
+  // leak via cache to a lower tier on the same path.
+  const user = getOptionalUser(event);
+  const isAdmin = user?.role === 'admin';
+  const tier: 'admin' | 'members' | 'anon' = isAdmin ? 'admin' : user ? 'members' : 'anon';
+  const cacheKey = `${tier}:${path}`;
+
   const hit = getLayoutCacheEntry<PublicLayoutSlice>(cacheKey);
   const now = Date.now();
   if (hit && now - hit.at < LAYOUT_CACHE_TTL_MS) {
@@ -57,13 +88,34 @@ export default defineEventHandler(async (event): Promise<PublicLayoutSlice | nul
     : { type: 'route', path };
 
   const layout = await getLayoutByScope(db, scope);
-  const value: PublicLayoutSlice | null = layout
-    ? {
-        zones: layout.zones,
-        pageMeta: layout.pageMeta,
-        state: layout.state,
-      }
-    : null;
+
+  // Multi-guard returns null when ANY check fails:
+  //   1. Draft-leak guard (audit round 2 P0): a non-admin must NOT see
+  //      a layout whose state is 'draft'.
+  //   2. pageMeta.access guard (audit round 3): if pageMeta.access ===
+  //      'admin', only admins see the payload. The catch-all page does
+  //      a parallel client-side check, but the SERVER is the trust
+  //      boundary — a malicious authenticated user could hit this
+  //      endpoint directly and exfiltrate admin-only layout payloads.
+  //   3. pageMeta.access === 'members': any authenticated user passes;
+  //      anonymous see null (catch-all redirects to /auth/login).
+  // Returning null surfaces as "no layout for this route" to the
+  // catch-all + the homepage v-if fallback.
+  const access = layout?.pageMeta?.access ?? 'public';
+  const isAuthenticated = !!user;
+  const accessOk =
+    access === 'public' ||
+    (access === 'members' && isAuthenticated) ||
+    (access === 'admin' && isAdmin);
+
+  const value: PublicLayoutSlice | null =
+    layout && accessOk && (isAdmin || layout.state === 'published')
+      ? {
+          zones: layout.zones,
+          pageMeta: layout.pageMeta,
+          state: layout.state,
+        }
+      : null;
 
   setLayoutCacheEntry(cacheKey, value, now);
   return value;

package/server/utils/layoutCache.ts

@@ -15,6 +15,13 @@
  * performance pass (`docs/plans/layout-and-pages.md` §10) replaces this
  * with ETag-based revalidation; the in-memory cache is sufficient for
  * Phase 1c volumes.
+ *
+ * **R4 audit fix (session 160)**: bounded LRU. Previously the cache was
+ * an unbounded Map — an adversarial client (or a misbehaving crawler)
+ * hitting `/api/layouts/by-route?path=/<random>` thousands of times
+ * grew the map without limit. After the R3 cache-key trifurcation
+ * (admin/members/anon), each unique path could land 3 entries. Bounded
+ * here to MAX_CACHE_ENTRIES with LRU eviction.
  */
 export interface LayoutCacheEntry<T> {
   value: T | null;
@@ -22,14 +29,43 @@ export interface LayoutCacheEntry<T> {
 }
 
 export const LAYOUT_CACHE_TTL_MS = 60_000;
+
+/**
+ * Maximum entries the cache will hold. At ~512 bytes per key + value,
+ * this caps memory at ~512KB per pod — comfortably small. Past this
+ * cap, oldest-inserted entries are evicted.
+ *
+ * Map's natural insertion-order semantics make LRU-on-set trivial:
+ * delete + reinsert moves an entry to the "newest" end. Eviction
+ * iterates from the oldest end.
+ */
+export const MAX_CACHE_ENTRIES = 1000;
+
 const cache = new Map<string, LayoutCacheEntry<unknown>>();
 
 export function getLayoutCacheEntry<T>(key: string): LayoutCacheEntry<T> | undefined {
-  return cache.get(key) as LayoutCacheEntry<T> | undefined;
+  const entry = cache.get(key) as LayoutCacheEntry<T> | undefined;
+  if (entry !== undefined) {
+    // LRU touch: move this key to the "newest" end of insertion order.
+    // The cache stays in oldest-first iteration order so eviction is O(1).
+    cache.delete(key);
+    cache.set(key, entry);
+  }
+  return entry;
 }
 
 export function setLayoutCacheEntry<T>(key: string, value: T | null, at: number = Date.now()): void {
+  // If key exists, drop it first so the re-insert lands at the newest end.
+  if (cache.has(key)) cache.delete(key);
   cache.set(key, { value, at });
+
+  // Evict oldest entries past the cap. Map preserves insertion order, so
+  // the first key in iteration is the least-recently-touched.
+  while (cache.size > MAX_CACHE_ENTRIES) {
+    const oldestKey = cache.keys().next().value;
+    if (oldestKey === undefined) break;
+    cache.delete(oldestKey);
+  }
 }
 
 /**