@commonpub/layer 0.23.3 → 0.25.0

package/composables/autoFormSchema.ts

@@ -0,0 +1,319 @@
+/**
+ * autoFormSchema — pure Zod → form-field descriptor engine (Phase 3e).
+ *
+ * Converts a section's `configSchema` (a `z.ZodType`) into a normalized
+ * `AutoFormField[]` that `<AdminLayoutsInspectorSection>` /
+ * `<AdminLayoutsInspectorRow>` render as native inputs reusing the
+ * `cpub-inspector-page-*` design language.
+ *
+ * ## Why hand-rolled, not FormKit (session 167 decision)
+ *
+ * The Phase 3 plan + `feedback-phase-3-hybrid-libraries` prescribed
+ * `@formkit/zod` for this. Verified against source at session 167:
+ *   1. `@formkit/zod`'s `createZodPlugin` adds VALIDATION ONLY to a form
+ *      whose inputs you hand-author — it does NOT generate fields from a
+ *      schema (formkit.com/plugins/zod). It delivers none of Phase 3e's
+ *      auto-gen goal.
+ *   2. `@formkit/zod@2.0.0` peer-deps `zod@^3`; the monorepo is on
+ *      `zod@4.3.6` everywhere. FormKit has not shipped Zod 4 support.
+ * The plan's risk register pre-authorized this exact fallback ("fall back
+ * to a hand-rolled <AutoForm> — Phase 3e decision"). See
+ * `project-session-167-formkit-pivot` memory.
+ *
+ * ## How it works
+ *
+ * Zod 4 ships a native `z.toJSONSchema()` that emits a complete, stable
+ * JSON Schema (type/enum/minLength/maxLength/pattern/minimum/maximum/
+ * minItems/maxItems/default/nested items+properties/required). We walk
+ * THAT (a well-specified format) rather than poking Zod internals, so the
+ * engine is resilient to Zod's internal churn. The §7.10 input-mapping
+ * table maps 1:1 onto JSON Schema node kinds.
+ *
+ * The engine is intentionally framework-free (no Vue imports) so it is
+ * unit-testable in isolation — per `feedback-css-cascade-unit-test-blind-spot`,
+ * keeping the LOGIC pure means the only place a CSS-cascade bug can hide
+ * is the `.vue` view, which gets the fresh-eyes pass.
+ */
+import { z, type ZodType } from 'zod';
+
+/** The native input control a field maps to. */
+export type AutoFormControl =
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'select'
+  | 'toggle'
+  | 'array'
+  | 'group'
+  | 'unsupported';
+
+export interface AutoFormOption {
+  value: string | number;
+  label: string;
+}
+
+export interface AutoFormField {
+  /** Object key in the config blob (also the `name` for refs / labels). */
+  key: string;
+  /** Humanized label derived from `key` (e.g. `customTitle` → "Custom title"). */
+  label: string;
+  /** The control to render. */
+  control: AutoFormControl;
+  /**
+   * Whether the field is required IN FORM TERMS — i.e. present in the
+   * schema's `required` array AND has no `default`. A field with a default
+   * is pre-filled, so it never blocks the user; we don't asterisk it.
+   */
+  required: boolean;
+  /**
+   * True when the field can legitimately be ABSENT — not in `required` AND
+   * no `default` (e.g. the optional row-config enums). Selects use this to
+   * offer a leading "default/unset" option so a `undefined` value doesn't
+   * masquerade as the first real choice being selected.
+   */
+  optional: boolean;
+  /** JSON Schema `description` — reserved for the §7.10 `keyword:arg`
+   *  rich-field extension (rich/content-picker/image/color). Unused in v1. */
+  description?: string;
+  /** Schema default, if any. */
+  defaultValue?: unknown;
+  // --- string constraints ---
+  minLength?: number;
+  maxLength?: number;
+  /** Regex source string (e.g. URL guards). Carried for inline validation. */
+  pattern?: string;
+  // --- number constraints ---
+  min?: number;
+  max?: number;
+  /** Step granularity — 1 for integers, undefined (any) for floats. */
+  step?: number;
+  // --- select (enum + union-of-const) ---
+  options?: AutoFormOption[];
+  // --- array (repeater) ---
+  /** For `array<object>`: the per-item sub-fields. */
+  itemFields?: AutoFormField[];
+  /** A blank item to append when the user clicks "+ Add". */
+  itemDefault?: unknown;
+  minItems?: number;
+  maxItems?: number;
+  // --- group (nested object) ---
+  fields?: AutoFormField[];
+}
+
+export interface AutoFormModel {
+  fields: AutoFormField[];
+  /** True when the schema exposes no editable properties (e.g. `stats`). */
+  isEmpty: boolean;
+}
+
+/**
+ * maxLength at/above which a string renders as a multi-line textarea
+ * instead of a single-line input. Tuned against the real section schemas:
+ * caption(480)/subtitle(500)/body(800)/markdown(100k)/html(8k,50k) become
+ * textareas; title(240)/heading(240)/name(255)/alt(240) stay single-line.
+ * URL-pattern strings bypass this (see the `string` branch) — they're
+ * single-line regardless of their 2048 cap.
+ */
+const LONG_TEXT_THRESHOLD = 480;
+
+type JsonNode = Record<string, unknown>;
+
+/** `#/$defs/Foo` → root.$defs.Foo. Zod inlines single-use subschemas but
+ *  emits $ref/$defs when one is reused; resolve defensively either way. */
+function resolveRef(node: JsonNode | undefined, root: JsonNode): JsonNode {
+  if (!node) return {};
+  const ref = node['$ref'];
+  if (typeof ref !== 'string') return node;
+  // Only the local "#/$defs/Name" form is produced by z.toJSONSchema.
+  const m = /^#\/\$defs\/(.+)$/.exec(ref);
+  if (!m) return node;
+  const defs = root['$defs'] as Record<string, JsonNode> | undefined;
+  const target = defs?.[m[1]!];
+  // Merge so sibling keywords on the $ref node (rare) aren't lost.
+  return target ? { ...target, ...stripRef(node) } : node;
+}
+
+function stripRef(node: JsonNode): JsonNode {
+  const { ['$ref']: _ref, ...rest } = node;
+  return rest;
+}
+
+/** `customTitle` → "Custom title"; `paddingY` → "Padding y"; `categorySlug` → "Category slug". */
+export function humanizeKey(key: string): string {
+  const spaced = key
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .trim()
+    .toLowerCase();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+/** Enum value → display label. Keeps short slugs as-is (they're already
+ *  terse design tokens like "sm"/"primary"); just trims. Numbers stringify. */
+function optionLabel(value: string | number): string {
+  return String(value);
+}
+
+function isConstUnion(node: JsonNode): node is JsonNode & { anyOf: JsonNode[] } {
+  const anyOf = node['anyOf'];
+  return Array.isArray(anyOf) && anyOf.length > 0 && anyOf.every((o) => o && typeof o === 'object' && 'const' in o);
+}
+
+/** Walk one object node's `properties` into fields. */
+function objectToFields(node: JsonNode, root: JsonNode): AutoFormField[] {
+  const properties = (node['properties'] as Record<string, JsonNode> | undefined) ?? {};
+  const required = Array.isArray(node['required']) ? (node['required'] as string[]) : [];
+  return Object.entries(properties).map(([key, raw]) => nodeToField(key, raw, root, required.includes(key)));
+}
+
+function nodeToField(
+  key: string,
+  rawNode: JsonNode,
+  root: JsonNode,
+  inRequiredArray: boolean,
+): AutoFormField {
+  const node = resolveRef(rawNode, root);
+  const defaultValue = node['default'];
+  // Form-required: in the required list AND no default to pre-fill it.
+  const required = inRequiredArray && defaultValue === undefined;
+  // Optional: absent-allowed (not required) AND no default to fall back to.
+  const optional = !inRequiredArray && defaultValue === undefined;
+  const base: AutoFormField = {
+    key,
+    label: humanizeKey(key),
+    control: 'unsupported',
+    required,
+    optional,
+    defaultValue,
+  };
+  const description = node['description'];
+  if (typeof description === 'string') base.description = description;
+
+  // 1. Union of literal consts (heading.level, content-feed.columns,
+  //    learning.columns) — z.union([z.literal(1), …]) → anyOf:[{const}].
+  if (isConstUnion(node)) {
+    base.control = 'select';
+    base.options = node.anyOf.map((o) => {
+      const v = o['const'] as string | number;
+      return { value: v, label: optionLabel(v) };
+    });
+    return base;
+  }
+
+  // 2. String enum → select.
+  if (Array.isArray(node['enum'])) {
+    base.control = 'select';
+    base.options = (node['enum'] as Array<string | number>).map((v) => ({ value: v, label: optionLabel(v) }));
+    return base;
+  }
+
+  const type = node['type'];
+  switch (type) {
+    case 'boolean':
+      base.control = 'toggle';
+      return base;
+
+    case 'integer':
+    case 'number':
+      base.control = 'number';
+      if (typeof node['minimum'] === 'number') base.min = node['minimum'] as number;
+      if (typeof node['maximum'] === 'number') base.max = node['maximum'] as number;
+      base.step = type === 'integer' ? 1 : undefined;
+      return base;
+
+    case 'string': {
+      if (typeof node['maxLength'] === 'number') base.maxLength = node['maxLength'] as number;
+      if (typeof node['minLength'] === 'number') base.minLength = node['minLength'] as number;
+      // Pattern strings are URLs/paths in our schemas — single-line text,
+      // NOT <input type=url> (which would reject valid root-relative paths
+      // like `/about`). Carry the pattern for our own inline validation.
+      if (typeof node['pattern'] === 'string') {
+        base.control = 'text';
+        base.pattern = node['pattern'] as string;
+        return base;
+      }
+      base.control = base.maxLength !== undefined && base.maxLength >= LONG_TEXT_THRESHOLD ? 'textarea' : 'text';
+      return base;
+    }
+
+    case 'array': {
+      base.control = 'array';
+      if (typeof node['minItems'] === 'number') base.minItems = node['minItems'] as number;
+      if (typeof node['maxItems'] === 'number') base.maxItems = node['maxItems'] as number;
+      const items = resolveRef(node['items'] as JsonNode | undefined, root);
+      if (items['type'] === 'object' || items['properties']) {
+        base.itemFields = objectToFields(items, root);
+        base.itemDefault = buildDefaults(base.itemFields);
+      } else {
+        // Scalar array (none in v1 builtins, but handle generically).
+        const itemField = nodeToField('item', items, root, false);
+        base.itemFields = [itemField];
+        base.itemDefault = blankFor(itemField);
+      }
+      return base;
+    }
+
+    case 'object': {
+      base.control = 'group';
+      base.fields = objectToFields(node, root);
+      return base;
+    }
+
+    default:
+      // Unknown / unrepresentable — render read-only so the admin sees the
+      // field exists but can't corrupt it. R3 ops: forward-compat for new
+      // Zod kinds a future schema introduces.
+      base.control = 'unsupported';
+      return base;
+  }
+}
+
+/** A sensible blank value for a freshly-added array item / group. */
+function blankFor(field: AutoFormField): unknown {
+  if (field.defaultValue !== undefined) return field.defaultValue;
+  switch (field.control) {
+    case 'text':
+    case 'textarea':
+      return '';
+    case 'number':
+      return field.min ?? 0;
+    case 'toggle':
+      return false;
+    case 'select':
+      return field.options?.[0]?.value ?? '';
+    case 'array':
+      return [];
+    case 'group':
+      return field.fields ? buildDefaults(field.fields) : {};
+    default:
+      return undefined;
+  }
+}
+
+/** Build a default object from a field list (for new array items / groups). */
+export function buildDefaults(fields: AutoFormField[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const f of fields) out[f.key] = blankFor(f);
+  return out;
+}
+
+/**
+ * Convert a Zod schema to a normalized form model. Returns `{ fields: [],
+ * isEmpty: true }` if the schema is not an object or can't be represented
+ * (degrades gracefully — never throws into the render path).
+ */
+export function buildAutoForm(schema: ZodType): AutoFormModel {
+  let json: JsonNode;
+  try {
+    json = z.toJSONSchema(schema) as JsonNode;
+  } catch {
+    // Unrepresentable schema (z.toJSONSchema throws by default). Degrade to
+    // an empty model; the view shows the "no options" state.
+    return { fields: [], isEmpty: true };
+  }
+  if (json['type'] !== 'object' && !json['properties']) {
+    return { fields: [], isEmpty: true };
+  }
+  const fields = objectToFields(json, json);
+  return { fields, isEmpty: fields.length === 0 };
+}

package/composables/useAdminSidebar.ts

@@ -0,0 +1,116 @@
+/**
+ * useAdminSidebar — state machine for the admin chrome's left sidebar.
+ *
+ * Two independent surfaces:
+ *   1. Desktop (≥768px): width can collapse from 200px to ~56px (icons-only).
+ *      The user's preference is persisted to a cookie. Editor routes
+ *      (`/admin/layouts/[id]`, `/admin/theme/edit/[id]`) auto-collapse to
+ *      give the canvas more room; the user can override that for the
+ *      current page visit only.
+ *   2. Mobile (<768px): drawer that slides in from the left, independent
+ *      of the desktop collapse state. Closes when a nav link is clicked.
+ *
+ * Design (mirrors Linear/Figma/Notion editor-mode patterns):
+ *   - userPref       — persisted boolean (cookie); the user's "default"
+ *                      collapsed state. Cookie chosen over localStorage
+ *                      so SSR renders correctly first time — no
+ *                      hydration flash where the sidebar starts expanded
+ *                      and then snaps to collapsed once the client tick
+ *                      reads storage. Matches `useTheme`'s pattern.
+ *   - sessionOverride — null | boolean; non-null only when the user manually
+ *                       toggled while on an editor route. Resets on route
+ *                       change so leaving the editor returns to userPref.
+ *   - desktopCollapsed (computed):
+ *       sessionOverride ?? (isEditorRoute ? true : userPref)
+ *
+ * Tests live in `__tests__/useAdminSidebar.test.ts` — cover SSR-safe
+ * hydration via mocked cookie, route-aware override, toggle persistence,
+ * and the mobile/desktop split.
+ *
+ * Wired into `layers/base/layouts/admin.vue` only.
+ *
+ * Sub-route caveat: `EDITOR_ROUTE_PATTERNS` use `$` end-anchors so
+ * `/admin/layouts/abc/preview` would NOT auto-collapse. Today no editor
+ * has sub-routes; if Phase 3b+ adds them, extend the regexes or use
+ * `startsWith` semantics.
+ */
+
+const COOKIE_KEY = 'cpub-admin-sidebar-collapsed';
+
+const EDITOR_ROUTE_PATTERNS: RegExp[] = [
+  /^\/admin\/layouts\/[^/]+$/, // /admin/layouts/[id] — Phase 3a layout editor
+  /^\/admin\/theme\/edit\/[^/]+$/, // /admin/theme/edit/[id] — session 154+156 theme editor
+];
+
+export interface AdminSidebarApi {
+  /** Final computed: is the desktop sidebar collapsed right now? */
+  desktopCollapsed: ComputedRef<boolean>;
+  /** Mobile drawer open state. Independent of desktop. */
+  mobileOpen: Ref<boolean>;
+  /** Whether the current route is one we auto-collapse for. Exposed for callers that want to label things. */
+  isEditorRoute: ComputedRef<boolean>;
+  /** Toggle desktop collapse. On editor routes: session-only. Off editor routes: persists to localStorage. */
+  toggleDesktop: () => void;
+  /** Toggle mobile drawer. */
+  toggleMobile: () => void;
+  /** Close mobile drawer (used by nav link click handlers). */
+  closeMobile: () => void;
+}
+
+export function useAdminSidebar(): AdminSidebarApi {
+  const route = useRoute();
+
+  // Persistent user pref: cookie (server-readable → no hydration flash).
+  // `useCookie` returns a Ref bound bidirectionally to the cookie; setting
+  // `.value` writes Set-Cookie on the next SSR response or updates
+  // document.cookie on the client. Default = false (expanded). The cookie
+  // is only created when the user actually toggles (Nuxt useCookie doesn't
+  // emit Set-Cookie for unchanged default values).
+  const userPref = useCookie<boolean>(COOKIE_KEY, {
+    default: () => false,
+    maxAge: 60 * 60 * 24 * 365, // 1 year — sidebar pref is "forever"
+    path: '/',
+    sameSite: 'lax',
+  });
+
+  // Transient: useState so it survives in-layout navigation but doesn't
+  // persist across page reloads (it's a per-visit override).
+  const sessionOverride = useState<boolean | null>('cpub-admin-sidebar-override', () => null);
+  const mobileOpen = useState<boolean>('cpub-admin-sidebar-mobile-open', () => false);
+
+  const isEditorRoute = computed<boolean>(() =>
+    EDITOR_ROUTE_PATTERNS.some((p) => p.test(route.path))
+  );
+
+  const desktopCollapsed = computed<boolean>(() => {
+    if (sessionOverride.value !== null) return sessionOverride.value;
+    return isEditorRoute.value ? true : userPref.value;
+  });
+
+  // Route change clears the session override so leaving the editor route
+  // returns the sidebar to the user's persistent preference.
+  watch(() => route.path, () => {
+    sessionOverride.value = null;
+  });
+
+  function toggleDesktop(): void {
+    const next = !desktopCollapsed.value;
+    if (isEditorRoute.value) {
+      sessionOverride.value = next;
+      return;
+    }
+    userPref.value = next;
+    sessionOverride.value = null;
+    // No explicit storage write — `useCookie` syncs automatically.
+  }
+
+  function toggleMobile(): void {
+    mobileOpen.value = !mobileOpen.value;
+  }
+
+  function closeMobile(): void {
+    mobileOpen.value = false;
+  }
+
+  return { desktopCollapsed, mobileOpen, isEditorRoute, toggleDesktop, toggleMobile, closeMobile };
+}

package/composables/useEditorChrome.ts

@@ -0,0 +1,56 @@
+/**
+ * useEditorChrome — palette + inspector visibility for the layout editor.
+ *
+ * User-reported: the editor's 3-column shell (palette ~280px / canvas /
+ * inspector ~320px) squishes the canvas to ~tablet width even on a wide
+ * desktop. Content cards in the preview clipped mid-word ("VIDEO/AYBACK
+ * SYSTE"). Fix is to let the admin hide either pane independently.
+ *
+ * Each visibility flag persists via cookie (matches `useAdminSidebar` +
+ * `useTheme` — no SSR/CSR hydration flash; Nuxt's `useCookie` reads the
+ * cookie on the server). Cookie is only emitted when the user toggles —
+ * Nuxt skips Set-Cookie for unchanged defaults.
+ *
+ * Wired into `pages/admin/layouts/[id].vue` (the editor shell) + the
+ * toggle buttons in `components/admin/layouts/AdminLayoutsToolbar.vue`.
+ *
+ * Pattern: v-show on the panels themselves (preserves component state +
+ * scroll/focus across toggles) + a `cpub-admin-layouts-editor-body--*`
+ * class on the parent grid (re-flows `grid-template-columns`).
+ */
+
+const PALETTE_COOKIE = 'cpub-editor-palette-hidden';
+const INSPECTOR_COOKIE = 'cpub-editor-inspector-hidden';
+
+export interface EditorChromeApi {
+  paletteHidden: Ref<boolean>;
+  inspectorHidden: Ref<boolean>;
+  togglePalette: () => void;
+  toggleInspector: () => void;
+}
+
+export function useEditorChrome(): EditorChromeApi {
+  const paletteHidden = useCookie<boolean>(PALETTE_COOKIE, {
+    default: () => false,
+    maxAge: 60 * 60 * 24 * 365, // 1 year
+    path: '/',
+    sameSite: 'lax',
+  });
+
+  const inspectorHidden = useCookie<boolean>(INSPECTOR_COOKIE, {
+    default: () => false,
+    maxAge: 60 * 60 * 24 * 365,
+    path: '/',
+    sameSite: 'lax',
+  });
+
+  function togglePalette(): void {
+    paletteHidden.value = !paletteHidden.value;
+  }
+
+  function toggleInspector(): void {
+    inspectorHidden.value = !inspectorHidden.value;
+  }
+
+  return { paletteHidden, inspectorHidden, togglePalette, toggleInspector };
+}

package/composables/useFeatures.ts

@@ -64,14 +64,41 @@ export const DEFAULT_FLAGS: FeatureFlags = {
   },
 };
 
-/** Build the initial flags by merging the layer's runtime config over defaults. */
+/**
+ * Build the initial flags. Two sources, in priority order:
+ *
+ *   1. **Server-side, request-scoped**: `event.context.cpubFeatureFlags` —
+ *      DB-merged values set by the Nitro `feature-flags-prime` plugin
+ *      (apps/reference/server/plugins/feature-flags-prime.ts). This is
+ *      how admin-UI flag overrides take effect at SSR time. Without it,
+ *      SSR would render with stale build-time defaults until client
+ *      hydration replaced them — visible flash + broken curl-based canary.
+ *
+ *   2. **Build-time runtime config**: `useRuntimeConfig().public.features` —
+ *      the legacy initialisation. Fallback for client-side, for early
+ *      startup before the plugin's hook can fire, and for thin apps
+ *      that haven't installed the prime plugin yet.
+ *
+ * Either way, defaults fill any unmentioned flags + identity is deep-
+ * merged so a partial override (e.g. `{ identity: { actingAs: true } }`)
+ * lands on top of the defaulted sub-flags rather than replacing the
+ * whole nested object.
+ */
 export function getInitialFlags(): FeatureFlags {
+  if (import.meta.server) {
+    // useRequestEvent is auto-imported on Nuxt server-side
+    const event = (typeof useRequestEvent === 'function') ? useRequestEvent() : null;
+    const ctxFlags = event?.context?.cpubFeatureFlags as Partial<FeatureFlags> | undefined;
+    if (ctxFlags && typeof ctxFlags === 'object') {
+      return {
+        ...DEFAULT_FLAGS,
+        ...ctxFlags,
+        identity: { ...DEFAULT_FLAGS.identity, ...(ctxFlags.identity ?? {}) },
+      };
+    }
+  }
   const config = useRuntimeConfig();
   const buildFlags = (config.public.features as unknown as Partial<FeatureFlags> | undefined) ?? {};
-  // Merge top-level booleans, but deep-merge `identity` so a partial
-  // runtime override (e.g., `{ identity: { actingAs: true } }`) lands on
-  // top of the defaulted sub-flags rather than replacing the whole
-  // nested object.
   return {
     ...DEFAULT_FLAGS,
     ...buildFlags,

package/composables/useLayout.ts

@@ -17,50 +17,44 @@
  * The `<LayoutSlot>` component is the only intended caller in v1; other
  * consumers should use that instead.
  */
+import { computed } from 'vue';
 import type { Ref } from 'vue';
+import type {
+  LayoutRecord,
+  LayoutSectionResolved,
+  LayoutRowResolved,
+  LayoutZone,
+} from '@commonpub/server';
 
-export interface LayoutSection {
-  id: string;
-  order: number;
-  type: string;
-  config: Record<string, unknown>;
-  colSpan: number;
-  responsive: { sm?: number; md?: number; lg?: number } | null;
-  enabled: boolean;
-  visibility: { roles?: string[]; features?: string[]; hideAt?: ('sm' | 'md' | 'lg')[] } | null;
-  schemaVersion: number;
-}
-
-export interface LayoutRow {
-  id: string;
-  order: number;
-  config: {
-    gap?: 'none' | 'sm' | 'md' | 'lg';
-    align?: 'start' | 'center' | 'stretch';
-    background?: string;
-    paddingY?: 'none' | 'sm' | 'md' | 'lg' | 'xl';
-  } | null;
-  sections: LayoutSection[];
-}
-
-export interface LayoutZoneClient {
-  zone: string;
-  rows: LayoutRow[];
-}
+// Re-export the server-side resolved types under the existing client-
+// facing names. Until session 162 these were locally-declared duplicates
+// (manually kept in sync) — the R2 audit caught that AdminLayoutsCanvas
+// hand-mapped LayoutRecord → LayoutPayload field-by-field, silently
+// dropping any newly-added section field (e.g. a future `pinned` flag).
+// Same-named single source of truth fixes that bug class.
+export type LayoutSection = LayoutSectionResolved;
+export type LayoutRow = LayoutRowResolved;
+export type LayoutZoneClient = LayoutZone;
 
-export interface LayoutPayload {
-  zones: LayoutZoneClient[];
-  pageMeta: {
-    title: string;
-    description?: string;
-    ogImage?: string;
-    noindex?: boolean;
-    ogType?: 'website' | 'article' | 'profile';
-    access?: 'public' | 'members' | 'admin';
-    frame?: 'narrow' | 'wide' | 'two-column' | 'three-column' | 'sidebar-left' | 'sidebar-right';
-  } | null;
-  state: 'draft' | 'published';
-}
+/**
+ * The leaner client-facing view of a layout — only the fields the
+ * renderer needs (state for draft-gate, pageMeta for SEO, zones for
+ * structure). Structurally a `Pick` of the full server LayoutRecord
+ * so any LayoutRecord is assignable to LayoutPayload without
+ * transformation (session 162 P2.4 R2 audit fix).
+ *
+ * IMPORTANT CAVEAT — because the row/section types are re-exports of
+ * the server's resolved types (above), any new field added to
+ * LayoutSectionResolved or LayoutRowResolved on the server will
+ * automatically flow through to the public render path here. That's
+ * usually what you want for genuinely public fields (e.g. a future
+ * `pinned: boolean` should be visible). But fields that should be
+ * admin-only (e.g. internal moderation tags) MUST be added to a
+ * separate server-side type, never to LayoutSectionResolved /
+ * LayoutRowResolved — otherwise they leak via /api/layouts/by-route.
+ * Session 162 audit note.
+ */
+export type LayoutPayload = Pick<LayoutRecord, 'state' | 'pageMeta' | 'zones'>;
 
 export interface UseLayoutResult {
   /** The layout payload, or null if none exists / feature off. */
@@ -96,6 +90,16 @@ export function useLayout(path: string | Ref<string> | (() => string)): UseLayou
         : path.value
   );
 
+  // Resolve query as a reactive computed — passing `{ path: pathGetter }`
+  // (a raw function value) made useFetch serialise the function reference,
+  // turning the request URL into ?path=undefined → 400 → null layout. The
+  // bug was load-bearing for the canary on commonpub.io (session 159): SSR
+  // saw `homepageLayout.value === null` despite a published layout existing,
+  // so layoutEngineActive resolved to false and pages/index.vue fell
+  // through to the legacy renderer. Fix: always pass a Ref/computed so
+  // useFetch reads the resolved value AND re-evaluates on dep change.
+  const queryRef = computed(() => ({ path: pathGetter() }));
+
   const { data, pending, error, refresh } = useFetch<LayoutPayload | null>(
     '/api/layouts/by-route',
     {
@@ -103,8 +107,7 @@ export function useLayout(path: string | Ref<string> | (() => string)): UseLayou
       // can dedupe across components on the same nav). For the reactive
       // case, omit key so useFetch derives one from the query Ref.
       key: typeof path === 'string' ? `layout:${path}` : undefined,
-      // Functional query — useFetch re-evaluates on watched deps change.
-      query: { path: pathGetter },
+      query: queryRef,
       // Watch the path getter so reactive callers refetch on change.
       // For string callers this is empty array → no extra reactivity.
       watch: typeof path === 'string' ? [] : [pathGetter],