@commonpub/layer 0.22.1 → 0.23.0

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';
 

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

@@ -0,0 +1,87 @@
+/**
+ * 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).
+ *
+ * Cached server-side for `LAYOUT_CACHE_TTL_MS` per path (see
+ * `server/utils/layoutCache.ts`). Invalidated on any layout write —
+ * the admin POST/PUT/DELETE/publish/revert handlers each call
+ * `invalidateLayoutsByRouteCache()` before returning.
+ *
+ * Gated by `features.layoutEngine`. Returns 404 when off so the legacy
+ * homepage section renderer keeps working.
+ */
+import { getLayoutByScope, type LayoutRecord, type LayoutScope } from '@commonpub/server';
+import {
+  LAYOUT_CACHE_TTL_MS,
+  getLayoutCacheEntry,
+  setLayoutCacheEntry,
+} from '../../utils/layoutCache';
+
+// Re-export for callers that import the invalidator from this file
+// (kept for backwards compat after the session-158 refactor that moved
+// the cache into utils/). New code should import from utils/layoutCache.
+export { invalidateLayoutsByRouteCache } from '../../utils/layoutCache';
+
+interface PublicLayoutSlice {
+  /** Zones → rows → enabled+visible sections only. Strips draft metadata. */
+  zones: LayoutRecord['zones'];
+  /** Page meta for custom pages; null for routes. */
+  pageMeta: LayoutRecord['pageMeta'];
+  /** State so SSR can mark `noindex` on drafts. */
+  state: LayoutRecord['state'];
+}
+
+export default defineEventHandler(async (event): Promise<PublicLayoutSlice | null> => {
+  const config = useConfig();
+  if (!(config.features as unknown as Record<string, boolean>).layoutEngine) {
+    // Feature off — return 404 so the legacy renderer stays in charge
+    throw createError({ statusCode: 404, statusMessage: 'Layout engine not enabled' });
+  }
+
+  const { path } = parseQueryParams(event, layoutsByRoutePathSchema);
+  const cacheKey = path;
+  const hit = getLayoutCacheEntry<PublicLayoutSlice>(cacheKey);
+  const now = Date.now();
+  if (hit && now - hit.at < LAYOUT_CACHE_TTL_MS) {
+    return hit.value;
+  }
+
+  const db = useDB();
+  // Try route scope first, then custom-page (custom pages shadow routes)
+  const scope: LayoutScope = isCustomPagePath(path)
+    ? { type: 'custom-page', path }
+    : { type: 'route', path };
+
+  const layout = await getLayoutByScope(db, scope);
+  const value: PublicLayoutSlice | null = layout
+    ? {
+        zones: layout.zones,
+        pageMeta: layout.pageMeta,
+        state: layout.state,
+      }
+    : null;
+
+  setLayoutCacheEntry(cacheKey, value, now);
+  return value;
+});
+
+/**
+ * Heuristic: paths NOT in the file-routes manifest are candidate
+ * custom-page paths. For Phase 1, we leave this as `false` (always
+ * resolve as route scope) — custom-page support lands in Phase 2 once
+ * the catch-all + conflict detection is in.
+ */
+function isCustomPagePath(_path: string): boolean {
+  return false;
+}
+
+// Inline Zod since the public-API surface keeps validators close to handlers
+// (matches the pattern used elsewhere — e.g. /api/profile/theme.put.ts).
+import { z } from 'zod';
+const layoutsByRoutePathSchema = z.object({
+  path: z.string().min(1).max(512).regex(/^\/[a-zA-Z0-9._~/-]*$/, 'Path must start with /'),
+});

package/server/utils/layoutCache.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared layout-resolution cache.
+ *
+ * The `/api/layouts/by-route` endpoint reads from this; every admin
+ * layout write handler MUST invalidate after success (otherwise SSR
+ * serves stale data for up to TTL_MS after a save).
+ *
+ * Kept here (utils/) rather than inline in `api/layouts/by-route.get.ts`
+ * so the admin write routes can import the invalidator without
+ * cross-file-handler imports (nitro's route-discovery treats `*.get.ts`
+ * + `*.post.ts` as handlers, not regular modules — utility shared state
+ * belongs in `utils/`).
+ *
+ * Per-process map → 60s TTL bounds staleness across pods. The Phase 10
+ * 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.
+ */
+export interface LayoutCacheEntry<T> {
+  value: T | null;
+  at: number;
+}
+
+export const LAYOUT_CACHE_TTL_MS = 60_000;
+const cache = new Map<string, LayoutCacheEntry<unknown>>();
+
+export function getLayoutCacheEntry<T>(key: string): LayoutCacheEntry<T> | undefined {
+  return cache.get(key) as LayoutCacheEntry<T> | undefined;
+}
+
+export function setLayoutCacheEntry<T>(key: string, value: T | null, at: number = Date.now()): void {
+  cache.set(key, { value, at });
+}
+
+/**
+ * Drop every cached entry. Called from every admin layout write
+ * handler (POST/PUT/DELETE on layouts, publish, revert, seed) BEFORE
+ * the response is sent. A more selective `invalidate(scopeKey)` is
+ * possible — but the cache is tiny (one entry per ever-visited route)
+ * and full-clear is the safer default while the editor is still
+ * coalescing draft saves (Phase 7+).
+ */
+export function invalidateLayoutsByRouteCache(): void {
+  cache.clear();
+}
+
+/**
+ * Cache size — for test-only inspection (verify a write actually
+ * cleared the cache rather than just calling a no-op function).
+ */
+export function _layoutCacheSize(): number {
+  return cache.size;
+}