@commonpub/layer 0.22.0 → 0.23.0

package/pages/admin/theme/index.vue

@@ -244,6 +244,49 @@ function recheckDiscovery(): void {
   discovery.value = detectAppliedOverrides();
 }
 
+/**
+ * Only show the "your site has a custom theme" banner when the detected
+ * overrides are LIKELY from a CSS file shipped by the layer app — NOT from
+ * a custom theme the admin has already saved (which would also appear as
+ * :root token overrides because the SSR middleware injects them there).
+ *
+ * Gating rules:
+ *   - hide when the active default is already a cpub-custom-* theme
+ *   - hide when instance-wide token overrides are set (those tokens explain
+ *     the diff; the banner would confuse the admin into re-capturing them)
+ *   - hide when no overrides were detected
+ *
+ * If admins want to re-capture from a fresh :root state, they can revert
+ * to the base theme, clear overrides, then the banner will reappear.
+ */
+/**
+ * Show the "your site has a custom theme" banner ONLY when the detected
+ * overrides on :root are likely from a CSS file the thin layer app
+ * loaded (the deveco.io case) — NOT from the built-in theme itself or
+ * from a custom theme the admin already saved.
+ *
+ * Refined gate (5 conditions, all must pass):
+ *   - count > 0 (something to capture)
+ *   - active theme is NOT a custom theme (already captured)
+ *   - active theme IS 'base' (any non-base built-in's tokens would
+ *     dominate the diff, making "capture" produce a clone of that
+ *     theme — pointless. e.g. commonpub.io's active='agora' triggers
+ *     count > 0 from agora.css; banner would confuse the admin)
+ *   - no instance-wide token overrides set (those explain the diff)
+ *
+ * Caveat: a thin app that registers a `themes:` entry AND sets
+ * instanceDefault to the registered slug (e.g. 'deveco') would have
+ * the banner HIDDEN even though their CSS file overrides ARE the use
+ * case the banner targets. For that case the admin can use the Fork
+ * button on the registered theme's card instead. Document.
+ */
+const showDiscoveryBanner = computed<boolean>(() => {
+  if (discovery.value.count === 0) return false;
+  if (instanceDefault.value !== 'base') return false;  // hides built-in non-base + registered + custom
+  if (Object.keys(initialOverrides.value).length > 0) return false;
+  return true;
+});
+
 // --- Token overrides (legacy / quick tweaks) ---
 // State + UI live in <AdminThemeOverridesPanel>; this page only persists
 // what the panel emits.
@@ -304,9 +347,12 @@ async function saveOverrides(overrides: Record<string, string>): Promise<void> {
       {{ toast.msg }}
     </div>
 
-    <!-- Discovery banner -->
+    <!-- Discovery banner — only when the overrides are from CSS (not from
+         a custom theme this admin already saved or instance-wide overrides).
+         Without this gate, the banner would re-appear after capture since
+         the custom theme it created now appears as a token override on :root. -->
     <section
-      v-if="discovery.count > 0"
+      v-if="showDiscoveryBanner"
       class="admin-theme-discovery"
       role="region"
       aria-label="Discovered theme tokens"

package/pages/index.vue

@@ -14,7 +14,7 @@ const sortedSections = computed(() =>
 );
 
 const { user: authUser } = useAuth();
-const { hubs: hubsEnabled, contests: contestsEnabled, learning: learningEnabled, video: videoEnabled, docs: docsEnabled, editorial: editorialEnabled } = useFeatures();
+const { hubs: hubsEnabled, contests: contestsEnabled, learning: learningEnabled, video: videoEnabled, docs: docsEnabled, editorial: editorialEnabled, layoutEngine: layoutEngineEnabled } = useFeatures();
 const { enabledTypeMeta } = useContentTypes();
 
 const activeTab = ref(authUser.value ? 'foryou' : 'latest');
@@ -143,8 +143,29 @@ async function handleHubJoin(hubSlug: string): Promise<void> {
 
 <template>
   <div>
+    <!-- ═══ LAYOUT ENGINE (Phase 1c — feature-flagged) ═══
+         When `features.layoutEngine` is ON, render the homepage via
+         <LayoutSlot> zones backed by the layouts table. Operators flip
+         this on AFTER running POST /api/admin/layouts/seed-homepage so
+         a default layout exists at scope ('route', '/'). If the flag is
+         on but no layout exists, LayoutSlot renders nothing and the
+         user sees an empty page — documented at
+         docs/reference/guides/layout-engine.md. Falls through to the
+         configurable section renderer when the flag is OFF (default). -->
+    <template v-if="layoutEngineEnabled">
+      <LayoutSlot route="/" zone="full-width" />
+      <div class="cpub-main-layout">
+        <main class="cpub-feed-col">
+          <LayoutSlot route="/" zone="main" />
+        </main>
+        <aside class="cpub-sidebar">
+          <LayoutSlot route="/" zone="sidebar" />
+        </aside>
+      </div>
+    </template>
+
     <!-- ═══ CONFIGURABLE HOMEPAGE (section renderer) ═══ -->
-    <template v-if="hasCustomSections">
+    <template v-else-if="hasCustomSections">
       <!-- Full-width sections (hero) -->
       <HomepageSectionRenderer :sections="sortedSections" zone="full-width" />
 

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

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;
+}