@commonpub/layer 0.22.1 → 0.23.1

package/sections/builtin/heading.ts

@@ -0,0 +1,36 @@
+/**
+ * Built-in section definition: heading.
+ *
+ * Phase 1c starter — single heading with optional eyebrow + subline.
+ * Drives the auto-form via the configSchema (Phase 3e maps Zod kinds to
+ * controls; level is a small enum → segmented control).
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionHeading from '../../components/sections/SectionHeading.vue';
+
+const configSchema = z.object({
+  text: z.string().min(1).max(240).default('Section heading'),
+  level: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]).default(2),
+  align: z.enum(['left', 'center']).default('left'),
+  eyebrow: z.string().max(120).default(''),
+  subline: z.string().max(480).default(''),
+});
+
+export const headingSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'heading',
+  name: 'Heading',
+  description: 'Single h1–h4 heading with optional eyebrow + subline',
+  icon: 'fa-heading',
+  category: 'content',
+  status: 'stable',
+  configSchema,
+  defaultConfig: { text: 'Section heading', level: 2, align: 'left', eyebrow: '', subline: '' },
+  schemaVersion: 1,
+  component: SectionHeading,
+  // Heading reads fine narrow; allow as small as quarter-width
+  minColSpan: 3,
+  maxColSpan: 12,
+  defaultColSpan: 12,
+  resizable: true,
+};

package/sections/builtin/hero.ts

@@ -0,0 +1,67 @@
+/**
+ * Built-in section definition: hero.
+ *
+ * Phase 1c starter. Three variants — `default` (left-aligned with grid
+ * backdrop), `compact` (narrow with no backdrop), `centered` (centered
+ * content). Up to two CTAs each with their own variant.
+ *
+ * NOT contest-aware (the existing HomepageHeroSection has dispatch
+ * logic for the live-contest hero — that responsibility moves to a
+ * future `contest-feature` data section in Phase 6b).
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionHero from '../../components/sections/SectionHero.vue';
+
+/**
+ * URL guard — accepts http(s), site-relative paths, hash links, mailto/tel.
+ * Rejects javascript:, data:, vbscript:, file:, etc. — admin-set fields
+ * render to ALL visitors, so a malicious admin (or DB corruption) could
+ * inject a clickable XSS via `<a href="javascript:...">` without this.
+ *
+ * Defense at the write boundary; the renderer doesn't re-validate
+ * (Vue's :href binding doesn't sanitize, so this IS the guard).
+ */
+const SAFE_LINK_URL = /^(https?:\/\/|\/|#|mailto:|tel:)/i;
+
+const ctaSchema = z.object({
+  label: z.string().min(1).max(80),
+  href: z.string().min(1).max(2048).regex(SAFE_LINK_URL, {
+    message: 'href must be http(s), relative (/), hash (#), mailto:, or tel:',
+  }),
+  variant: z.enum(['primary', 'secondary']).default('primary'),
+});
+
+const configSchema = z.object({
+  variant: z.enum(['default', 'compact', 'centered']).default('default'),
+  eyebrow: z.string().max(120).default(''),
+  title: z.string().min(1).max(240).default('Welcome'),
+  subtitle: z.string().max(800).default(''),
+  // Capped at 2 — visual + a11y guidance: more than two competing CTAs
+  // dilute the call-to-action and read as a button bar instead.
+  ctas: z.array(ctaSchema).max(2).default([]),
+});
+
+export const heroSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'hero',
+  name: 'Hero',
+  description: 'Banner with title, subtitle, and up to two CTAs',
+  icon: 'fa-bullhorn',
+  category: 'layout',
+  status: 'stable',
+  configSchema,
+  defaultConfig: {
+    variant: 'default',
+    eyebrow: '',
+    title: 'Welcome',
+    subtitle: '',
+    ctas: [],
+  },
+  schemaVersion: 1,
+  component: SectionHero,
+  // Hero breaks at <6 cols (CTA wrap looks awful); 12 is the canonical use
+  minColSpan: 6,
+  maxColSpan: 12,
+  defaultColSpan: 12,
+  resizable: true,
+};

package/sections/builtin/image.ts

@@ -0,0 +1,67 @@
+/**
+ * Built-in section definition: image.
+ *
+ * Phase 1c starter. Stores raw URL + alt + optional caption + optional
+ * href. The Phase 3e auto-form will swap `src` for an ImageUpload picker
+ * via `.describe('image')` — current Zod is a plain URL string so the
+ * form generator still produces a usable text input today.
+ *
+ * Security note: `src` is rendered as-is via `<img>` — sanitisation is
+ * caller responsibility (the URL is never reflected into a script
+ * context). Custom-HTML / iframe sections are the XSS surface and gate
+ * differently (admin-only addRoles in Phase 6b).
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionImage from '../../components/sections/SectionImage.vue';
+
+/**
+ * URL guards — separate for `src` (image fetch) vs `href` (click target).
+ *
+ * - `src`: http(s) or site-relative. data: rejected (large + tracking
+ *   surface; ImageUpload should be the path for inline data). javascript:
+ *   in <img src> doesn't execute in modern browsers, but disallow anyway
+ *   for consistency.
+ * - `href`: http(s), site-relative, hash, mailto:, tel:. javascript:
+ *   would execute on click — admin-set fields render to ALL visitors so
+ *   this is a stored XSS surface without the regex.
+ *
+ * Both allow EMPTY string (the section's "no image yet" / "no link"
+ * state). The `^(?:$|…)` shape matches empty-string only when the
+ * `$` end-of-string anchor immediately follows `^` — pinned by tests
+ * because the obvious `^(?:|…)` would have an empty alternation
+ * branch that matches ANY input (the empty match always succeeds at
+ * position 0).
+ */
+const SAFE_IMAGE_URL = /^(?:$|https?:\/\/|\/)/i;
+const SAFE_LINK_URL = /^(?:$|https?:\/\/|\/|#|mailto:|tel:)/i;
+
+const configSchema = z.object({
+  src: z.string().max(2048).regex(SAFE_IMAGE_URL, {
+    message: 'src must be http(s) or relative (/)',
+  }).default(''),
+  alt: z.string().max(240).default(''),
+  caption: z.string().max(480).default(''),
+  href: z.string().max(2048).regex(SAFE_LINK_URL, {
+    message: 'href must be http(s), relative (/), hash (#), mailto:, or tel:',
+  }).default(''),
+  fit: z.enum(['contain', 'cover']).default('contain'),
+  aspectRatio: z.enum(['16/9', '4/3', '1/1', 'auto']).default('auto'),
+});
+
+export const imageSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'image',
+  name: 'Image',
+  description: 'Single image with optional caption + link',
+  icon: 'fa-image',
+  category: 'content',
+  status: 'stable',
+  configSchema,
+  defaultConfig: { src: '', alt: '', caption: '', href: '', fit: 'contain', aspectRatio: 'auto' },
+  schemaVersion: 1,
+  component: SectionImage,
+  minColSpan: 3,
+  maxColSpan: 12,
+  defaultColSpan: 12,
+  resizable: true,
+};

package/sections/builtin/paragraph.ts

@@ -0,0 +1,34 @@
+/**
+ * Built-in section definition: paragraph.
+ *
+ * Phase 1c starter — plain prose, blank-line split into `<p>` tags.
+ * Upgrade to TipTap-driven rich text in Phase 3e via `.describe('rich')`
+ * + a v2 migration; this v1 keeps the storage simple so the editor work
+ * doesn't block on TipTap integration.
+ */
+import { z } from 'zod';
+import type { SectionDefinition } from '@commonpub/ui';
+import SectionParagraph from '../../components/sections/SectionParagraph.vue';
+
+const configSchema = z.object({
+  text: z.string().max(8000).default(''),
+  align: z.enum(['left', 'center']).default('left'),
+});
+
+export const paragraphSection: SectionDefinition<z.infer<typeof configSchema>> = {
+  type: 'paragraph',
+  name: 'Paragraph',
+  description: 'Plain prose body with blank-line paragraph breaks',
+  icon: 'fa-align-left',
+  category: 'content',
+  status: 'stable',
+  configSchema,
+  defaultConfig: { text: '', align: 'left' },
+  schemaVersion: 1,
+  component: SectionParagraph,
+  // Prose reads best at ~6/12; allow narrower for sidebars + full-width on landing pages
+  minColSpan: 3,
+  maxColSpan: 12,
+  defaultColSpan: 6,
+  resizable: true,
+};

package/sections/registry.ts

@@ -0,0 +1,61 @@
+/**
+ * Layer-level section registry — the Vue runtime catalog that
+ * `<LayoutSlot>` consults to render a section by its `type` slug.
+ *
+ * `SectionRegistry` (the class) lives in `@commonpub/ui` as Vue-aware
+ * types. This file:
+ *   1. Creates ONE shared registry instance per app process
+ *   2. Calls `register()` for every built-in section type the layer ships
+ *   3. Exports `useSectionRegistry()` so consumers (LayoutSlot + the
+ *      admin editor's palette) can read it without circular imports
+ *
+ * **Same instance on server + client.** Vue plugins instantiate at
+ * setup time; section registration is synchronous + idempotent (the
+ * `register()` method throws on duplicate slugs — fail-fast).
+ *
+ * Adding a built-in section is THREE files (see any of `./builtin/*` for
+ * the template):
+ *   1. `./builtin/{type}.ts` — Zod schema + SectionDefinition export
+ *   2. `../components/sections/Section{PascalType}.vue` — renderer
+ *   3. One `registry.register(...)` line here
+ *
+ * To add a CUSTOM section from a thin layer app (Phase 9 — not yet
+ * shipped): same pattern, registered from your `commonpub.config.ts`.
+ */
+import { SectionRegistry } from '@commonpub/ui';
+import { dividerSection } from './builtin/divider';
+import { headingSection } from './builtin/heading';
+import { paragraphSection } from './builtin/paragraph';
+import { imageSection } from './builtin/image';
+import { heroSection } from './builtin/hero';
+import { contentFeedSection } from './builtin/content-feed';
+
+// Singleton — registered once at module load. Vue/Nuxt's setup() runs
+// per-component, but module load is once per app process. Safe.
+const registry = new SectionRegistry();
+
+// --- Built-in registrations -----------------------------------------------
+// Phase 1c starter catalog: divider (proof-of-life) + 5 sections covering
+// the four leading categories — layout (hero, divider), content (heading,
+// paragraph, image), and data (content-feed).
+//
+// Phase 6b adds the remaining 20 types (gallery, video, embed, spacer,
+// cta, featured-content, content-card, contest-list, hub-list, event-list,
+// member-list, stats-grid, contact-form, newsletter, announcement,
+// markdown, custom-html, iframe, editorial). See docs/plans/layout-and-pages.md §3.4.
+registry.register(dividerSection);
+registry.register(heroSection);
+registry.register(headingSection);
+registry.register(paragraphSection);
+registry.register(imageSection);
+registry.register(contentFeedSection);
+
+/**
+ * Read-only accessor — the layer's standard pattern for shared state.
+ * Use this everywhere instead of importing `registry` directly so we
+ * can swap to a Nuxt-provided instance in Phase 9 (when thin apps
+ * register their own sections via `commonpub.config.ts`).
+ */
+export function useSectionRegistry(): SectionRegistry {
+  return registry;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * POST /api/admin/layouts/[id]/publish
+ *
+ * Snapshot the current layout into `layout_versions`, set
+ * `published_version_id`, transition `state` to 'published'. Returns
+ * the version record.
+ *
+ * Admin + features.admin + features.layoutEngine.
+ * Invalidates the layouts-by-route cache on success.
+ */
+import { getLayoutById, publishLayout } from '@commonpub/server';
+import { invalidateLayoutsByRouteCache } from '../../../../utils/layoutCache';
+
+export default defineEventHandler(async (event) => {
+  requireFeature('admin');
+  requireFeature('layoutEngine');
+  const admin = requireAdmin(event);
+  const db = useDB();
+
+  const id = getRouterParam(event, 'id');
+  if (!id) {
+    throw createError({ statusCode: 400, statusMessage: 'Missing id param' });
+  }
+
+  const existing = await getLayoutById(db, id);
+  if (!existing) {
+    throw createError({ statusCode: 404, statusMessage: 'Layout not found' });
+  }
+
+  const version = await publishLayout(db, id, { publishedBy: admin.id });
+  invalidateLayoutsByRouteCache();
+  return version;
+});

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

@@ -0,0 +1,43 @@
+/**
+ * POST /api/admin/layouts/[id]/versions/[versionId]/revert
+ *
+ * Restore a layout to a prior version snapshot. The original version
+ * row is NOT touched — snapshots are immutable. The layout's current
+ * rows + sections are rewritten from the snapshot, and the state
+ * transitions to 'draft' (admin can re-publish if desired).
+ *
+ * Admin + features.admin + features.layoutEngine.
+ * Invalidates the layouts-by-route cache on success.
+ */
+import { getLayoutById, revertToVersion } from '@commonpub/server';
+import { invalidateLayoutsByRouteCache } from '../../../../../../utils/layoutCache';
+
+export default defineEventHandler(async (event) => {
+  requireFeature('admin');
+  requireFeature('layoutEngine');
+  const admin = requireAdmin(event);
+  const db = useDB();
+
+  const id = getRouterParam(event, 'id');
+  const versionId = getRouterParam(event, 'versionId');
+  if (!id || !versionId) {
+    throw createError({ statusCode: 400, statusMessage: 'Missing id or versionId param' });
+  }
+
+  const existing = await getLayoutById(db, id);
+  if (!existing) {
+    throw createError({ statusCode: 404, statusMessage: 'Layout not found' });
+  }
+
+  try {
+    const reverted = await revertToVersion(db, id, versionId, { userId: admin.id });
+    invalidateLayoutsByRouteCache();
+    return reverted;
+  } catch (e) {
+    // revertToVersion throws on missing version — map to 404
+    if (e instanceof Error && e.message.includes('Version not found')) {
+      throw createError({ statusCode: 404, statusMessage: e.message });
+    }
+    throw e;
+  }
+});

package/server/api/admin/layouts/[id]/versions/index.get.ts

@@ -0,0 +1,29 @@
+/**
+ * GET /api/admin/layouts/[id]/versions
+ *
+ * List all immutable version snapshots for a layout, newest first.
+ * Each entry has the FULL snapshot embedded — useful for the version
+ * history UI to show a preview of "what this version looked like".
+ *
+ * Admin + features.admin + features.layoutEngine.
+ */
+import { getLayoutById, listLayoutVersions } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  requireFeature('admin');
+  requireFeature('layoutEngine');
+  requireAdmin(event);
+  const db = useDB();
+
+  const id = getRouterParam(event, 'id');
+  if (!id) {
+    throw createError({ statusCode: 400, statusMessage: 'Missing id param' });
+  }
+
+  const existing = await getLayoutById(db, id);
+  if (!existing) {
+    throw createError({ statusCode: 404, statusMessage: 'Layout not found' });
+  }
+
+  return listLayoutVersions(db, id);
+});

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

@@ -0,0 +1,34 @@
+/**
+ * DELETE /api/admin/layouts/[id]
+ *
+ * Permanently delete a layout. Cascades through rows + sections + versions.
+ *
+ * NOT recoverable. The editor's UI surfaces a confirm modal; this API
+ * trusts the caller.
+ *
+ * Admin + features.admin + features.layoutEngine.
+ * Invalidates the layouts-by-route cache on success.
+ */
+import { deleteLayout, getLayoutById } from '@commonpub/server';
+import { invalidateLayoutsByRouteCache } from '../../../utils/layoutCache';
+
+export default defineEventHandler(async (event): Promise<{ ok: true; id: string }> => {
+  requireFeature('admin');
+  requireFeature('layoutEngine');
+  requireAdmin(event);
+  const db = useDB();
+
+  const id = getRouterParam(event, 'id');
+  if (!id) {
+    throw createError({ statusCode: 400, statusMessage: 'Missing id param' });
+  }
+
+  const existing = await getLayoutById(db, id);
+  if (!existing) {
+    throw createError({ statusCode: 404, statusMessage: 'Layout not found' });
+  }
+
+  await deleteLayout(db, id);
+  invalidateLayoutsByRouteCache();
+  return { ok: true, id };
+});

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

@@ -0,0 +1,27 @@
+/**
+ * GET /api/admin/layouts/[id]
+ *
+ * Fetch a layout by id. Returns the full record including draft state +
+ * version pointer. 404 if not found.
+ *
+ * Admin + features.admin + features.layoutEngine.
+ */
+import { getLayoutById } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  requireFeature('admin');
+  requireFeature('layoutEngine');
+  requireAdmin(event);
+
+  const id = getRouterParam(event, 'id');
+  if (!id) {
+    throw createError({ statusCode: 400, statusMessage: 'Missing id param' });
+  }
+
+  const db = useDB();
+  const layout = await getLayoutById(db, id);
+  if (!layout) {
+    throw createError({ statusCode: 404, statusMessage: 'Layout not found' });
+  }
+  return layout;
+});

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

@@ -0,0 +1,64 @@
+/**
+ * PUT /api/admin/layouts/[id]
+ *
+ * Update a layout — auto-save target for the editor. Sends the WHOLE
+ * draft (zones → rows → sections); saveLayout diffs against current,
+ * renumbers positions, rewrites children in a transaction.
+ *
+ * Scope CANNOT be changed via PUT (it's immutable per layout). A scope
+ * change would mean a new layout — POST instead.
+ *
+ * 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';
+
+export default defineEventHandler(async (event) => {
+  requireFeature('admin');
+  requireFeature('layoutEngine');
+  const admin = requireAdmin(event);
+  const db = useDB();
+
+  const id = getRouterParam(event, 'id');
+  if (!id) {
+    throw createError({ statusCode: 400, statusMessage: 'Missing id param' });
+  }
+
+  const existing = await getLayoutById(db, id);
+  if (!existing) {
+    throw createError({ statusCode: 404, statusMessage: 'Layout not found' });
+  }
+
+  const body = await parseBody(event, layoutCreateSchema);
+
+  // 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.
+  if (
+    body.scope.type !== existing.scope.type ||
+    ('path' in body.scope ? body.scope.path : body.scope.key) !==
+      ('path' in existing.scope ? existing.scope.path : existing.scope.key)
+  ) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Cannot change layout scope via PUT — POST a new layout instead',
+    });
+  }
+
+  const saved = await saveLayout(
+    db,
+    {
+      scope: body.scope,
+      name: body.name,
+      pageMeta: body.pageMeta,
+      zones: body.zones,
+      state: body.state,
+    },
+    { id, userId: admin.id },
+  );
+
+  invalidateLayoutsByRouteCache();
+  return saved;
+});

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

@@ -0,0 +1,25 @@
+/**
+ * GET /api/admin/layouts
+ *
+ * List all layouts. Optional `?scope=route|virtual|custom-page` to
+ * filter by scope type. Returns the full LayoutRecord shape (nested
+ * zones → rows → sections + version + state).
+ *
+ * Admin + features.admin + features.layoutEngine.
+ */
+import { listLayouts } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  requireFeature('admin');
+  requireFeature('layoutEngine');
+  requireAdmin(event);
+
+  const db = useDB();
+  const query = getQuery(event) as { scope?: string };
+  const scopeFilter =
+    query.scope === 'route' || query.scope === 'virtual' || query.scope === 'custom-page'
+      ? query.scope
+      : undefined;
+
+  return listLayouts(db, scopeFilter ? { scopeType: scopeFilter } : undefined);
+});

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

@@ -0,0 +1,48 @@
+/**
+ * POST /api/admin/layouts
+ *
+ * Create a new layout for a scope. Body is the full layout payload
+ * (validated against `layoutCreateSchema`) with client-generated UUIDs
+ * for sections/rows. Returns the created LayoutRecord.
+ *
+ * Fails with 409 if a layout already exists at the given scope (the
+ * editor should PUT to the existing one instead).
+ *
+ * Admin + features.admin + features.layoutEngine.
+ * Invalidates the layouts-by-route cache on success.
+ */
+import { layoutCreateSchema } from '@commonpub/schema';
+import { getLayoutByScope, saveLayout } from '@commonpub/server';
+import { invalidateLayoutsByRouteCache } from '../../../utils/layoutCache';
+
+export default defineEventHandler(async (event) => {
+  requireFeature('admin');
+  requireFeature('layoutEngine');
+  const admin = requireAdmin(event);
+  const db = useDB();
+
+  const body = await parseBody(event, layoutCreateSchema);
+
+  const existing = await getLayoutByScope(db, body.scope);
+  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`,
+    });
+  }
+
+  const saved = await saveLayout(
+    db,
+    {
+      scope: body.scope,
+      name: body.name,
+      pageMeta: body.pageMeta,
+      zones: body.zones,
+      state: body.state,
+    },
+    { userId: admin.id },
+  );
+
+  invalidateLayoutsByRouteCache();
+  return saved;
+});

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

@@ -0,0 +1,35 @@
+/**
+ * POST /api/admin/layouts/seed-homepage
+ *
+ * Operator's bootstrap call: seeds + publishes a default homepage
+ * layout (hero + content-feed) at scope ('route', '/'). Idempotent —
+ * safe to call repeatedly.
+ *
+ * Intended flow for enabling the layout engine on the homepage:
+ *   1. Operator runs migration 0005 (if not already applied)
+ *   2. Operator POSTs to this endpoint → layout exists, published v1
+ *   3. Operator flips `features.layoutEngine` ON
+ *   4. Homepage renders via `<LayoutSlot>` (v-if branch in pages/index.vue)
+ *
+ * NOT the full legacy `homepage.sections` migration — that needs the
+ * remaining sections from Phase 6b. Doc'd at
+ * `docs/reference/guides/layout-engine.md`.
+ *
+ * Admin + features.admin + features.layoutEngine.
+ * Invalidates the layouts-by-route cache on success.
+ */
+import { seedHomepageLayout } from '@commonpub/server';
+import { invalidateLayoutsByRouteCache } from '../../../utils/layoutCache';
+
+export default defineEventHandler(async (event) => {
+  requireFeature('admin');
+  requireFeature('layoutEngine');
+  const admin = requireAdmin(event);
+  const db = useDB();
+
+  const result = await seedHomepageLayout(db, { adminId: admin.id });
+  if (result.created) {
+    invalidateLayoutsByRouteCache();
+  }
+  return result;
+});

package/server/api/admin/themes/discover.get.ts

@@ -1,12 +1,21 @@
 /**
  * GET /api/admin/themes/discover
  *
- * Returns the canonical default values for every known token. The client
- * uses this to diff against `getComputedStyle(:root)` and surface a
- * "your site has a custom theme — capture it?" CTA when the runtime values
- * differ from the built-in defaults.
+ * Returns the canonical default values for every known token.
  *
- * This is purely advisory; the client makes the decision based on the diff.
+ * **CURRENTLY UNUSED** (as of session 157). The client-side
+ * `detectAppliedOverrides()` in `utils/themeDiscovery.ts` uses
+ * `TOKEN_SPECS` directly (same data source, no HTTP). The endpoint is
+ * kept because:
+ *   1. It's documented in `docs/reference/guides/theme-editor.md` as
+ *      the source of truth for default values.
+ *   2. A future Phase (section registry adds new tokens at runtime, or
+ *      the layer wants to source defaults from the server rather than
+ *      the client bundle) may flip the client to use this endpoint.
+ *   3. Deleting would force a doc revision + breaking-change note for
+ *      anyone who scripted against it externally.
+ *
+ * Cost is zero (no DB hit, just returns a static map). Safe to keep.
  */
 import { TOKEN_SPECS } from '@commonpub/ui';