@unitninety/site-kit 1.6.2 → 1.6.3

package/src/bridge/protocol.ts

@@ -1,3 +1,7 @@
+import { z } from 'zod'
+import { Crop } from '../elements/leaves/image'
+import { BlockDeclSchema, FieldDeclSchema } from '../elements/declaration'
+import { EntryReadSchema, MediaAssetSchema, type EntryRead, type FieldDecl, type MediaRecord, type Schema } from '../elements/define'
 import { isDocumentId } from '../elements/ids'
 import { LinkTo } from '../elements/leaves/link'
 
@@ -7,7 +11,8 @@ import { LinkTo } from '../elements/leaves/link'
  *
  * The model: the page is server-rendered from draft content. Typing edits the DOM in place and
  * is sent as `edit`; the Canvas saves; after any structural save the Canvas sends `refresh` and
- * the site calls `router.refresh()`. No content push, no client-side merge, no `fields` message.
+ * the site calls `router.refresh()`. Opt-in client components can also render transient, path-scoped list snapshots before saving.
+ * Server renders remain authoritative; there is no persistent client content store or `fields` message.
  */
 export const BRIDGE_VERSION = 4 as const
 
@@ -46,8 +51,9 @@ const isBridgeLinkTarget = (to: unknown): to is LinkTo => {
  * A DOM-shaped instruction the Canvas asks a frame to apply to markup it has already rendered, so
  * an edit shows before the server has re-rendered the page.
  *
- * Deliberately presentational. It carries no fields, no sections and no content tree, which is what
- * keeps it from growing back into the client-side merge v4 removed: there is nothing here to merge.
+ * DOM previews are presentational. A list snapshot contains native reads for one declared list;
+ * only an opt-in draft component consumes it. An embedded `list` lets older bridges keep handling
+ * the accompanying DOM instruction, while new list owners render through React.
  * Every preview is transient. React owns draft block order and settles it from the next server render.
  * For other previews the frame records an undo and takes them back, newest
  * first, just before it asks for the `u90:refresh` that follows the save (`createBridge`'s journal), so
@@ -56,7 +62,11 @@ const isBridgeLinkTarget = (to: unknown): to is LinkTo => {
  *
  * `before` names the sibling to insert in front of; `null` appends.
  */
-export type PreviewInstruction =
+export type DraftSnapshot = { path: string; field: FieldDecl; value: unknown; media?: MediaRecord[]; entries?: EntryRead[]; blocks?: Schema['blocks'] }
+
+export type PreviewInstruction = (
+  | ({ kind: 'value' } & DraftSnapshot)
+  | { kind: 'list'; path: string; value: unknown[] }
   | { kind: 'entries'; path: string; order: string[]; exclude: string[]; pin: string[] }
   | { kind: 'move'; path: string; before: string | null }
   | { kind: 'remove'; path: string }
@@ -75,15 +85,39 @@ export type PreviewInstruction =
    * applied by `applyPreview`; `createBridge` handles it.
    */
   | { kind: 'fragment'; path: string; block: string }
+) & { list?: { path: string; value: unknown[] }; draft?: DraftSnapshot }
 
-const PREVIEW_KINDS = new Set(['entries', 'move', 'remove', 'media', 'text', 'link-label', 'rich', 'insert', 'replace', 'fragment'])
+const PREVIEW_KINDS = new Set(['value', 'list', 'entries', 'move', 'remove', 'media', 'text', 'link-label', 'rich', 'insert', 'replace', 'fragment'])
 const isBefore = (v: unknown): boolean => v === null || typeof v === 'string'
 
+const DraftMediaSchema = MediaAssetSchema.extend({ renditions: z.array(z.object({ crop: Crop.nullable(), url: z.string(), width: z.number().nullable(), height: z.number().nullable(), blurDataURL: z.string().optional(), status: z.enum(['ready', 'processing', 'error']) })).optional() })
+const unsafeKeys = new Set(['__proto__', 'constructor', 'prototype'])
+function safeSnapshotValue(value: unknown, ancestors = new Set<object>()): boolean {
+  if (!value || typeof value !== 'object') return true
+  if (ancestors.has(value) || ancestors.size > 64) return false
+  const next = new Set(ancestors).add(value)
+  return Object.entries(value).every(([key, child]) => !unsafeKeys.has(key) && safeSnapshotValue(child, next))
+}
+const isDraftSnapshot = (value: unknown): value is DraftSnapshot => {
+  if (!value || typeof value !== 'object' || !safeSnapshotValue(value)) return false
+  const r = value as Record<string, unknown>
+  return typeof r.path === 'string' && /^(page|entry|layout|single):[^/]+(?:\/[^/]+)*$/.test(r.path)
+    && !r.path.split('/').some(key => unsafeKeys.has(key)) && Object.hasOwn(r, 'value')
+    && FieldDeclSchema.safeParse(r.field).success
+    && (r.media === undefined || Array.isArray(r.media) && r.media.every(media => DraftMediaSchema.safeParse(media).success))
+    && (r.entries === undefined || Array.isArray(r.entries) && r.entries.every(entry => EntryReadSchema.safeParse(entry).success))
+    && (r.blocks === undefined || !!r.blocks && typeof r.blocks === 'object' && !Array.isArray(r.blocks) && Object.values(r.blocks).every(block => BlockDeclSchema.safeParse(block).success))
+}
+
 /** Whether a `u90:preview`'s instruction has a known kind and a well-formed payload. */
 const isPreviewInstruction = (value: unknown): value is PreviewInstruction => {
   if (!(value && typeof value === 'object')) return false
   const r = value as Record<string, unknown>
   if (typeof r.kind !== 'string' || !PREVIEW_KINDS.has(r.kind) || typeof r.path !== 'string') return false
+  if (r.list !== undefined && (!r.list || typeof r.list !== 'object' || typeof (r.list as Record<string, unknown>).path !== 'string' || !Array.isArray((r.list as Record<string, unknown>).value))) return false
+  if (r.draft !== undefined && !isDraftSnapshot(r.draft)) return false
+  if (r.kind === 'value') return isDraftSnapshot(r)
+  if (r.kind === 'list') return Array.isArray(r.value)
   if (r.kind === 'entries') return [r.order, r.exclude, r.pin].every(ids => Array.isArray(ids) && ids.every(id => typeof id === 'string'))
   if (r.kind === 'media') return typeof r.src === 'string'
   if (r.kind === 'text' || r.kind === 'link-label') return typeof r.value === 'string'
@@ -126,7 +160,7 @@ export type SiteMessage = Base &
   (
     | { type: 'u90:ready'; path: string }
     | { type: 'u90:path'; path: string }
-    | { type: 'u90:select'; path: string | null }
+    | { type: 'u90:select'; path: string | null; via?: string[] }
     | { type: 'u90:hover'; path: string | null }
     | { type: 'u90:edit'; path: string; kind: 'text' | 'rich' | 'link-label'; value: unknown }
     | {
@@ -158,7 +192,7 @@ export type SiteMessage = Base &
 export type CanvasMessage = Base &
   (
     | { type: 'u90:refresh' }
-    | { type: 'u90:select'; path: string | null }
+    | { type: 'u90:select'; path: string | null; reveal?: boolean; via?: string[] }
     | { type: 'u90:flush'; requestId: string }
     | { type: 'u90:format'; action: string; url?: string; to?: LinkTo; newTab?: boolean }
     | { type: 'u90:scroll'; to: 'top' | 'fraction'; fraction?: number }
@@ -209,12 +243,15 @@ const isValidFormat = (data: Record<string, unknown>): boolean => {
   return true
 }
 
+const validReferenceTrail = (via: unknown): boolean => via === undefined || (Array.isArray(via) && via.length <= 5 && via.every(path => typeof path === 'string' && path.length <= 512 && /^(page|entry|layout|single):[^/]+\//.test(path)))
+
 /** A message from the Canvas, accepted only at the current version and a known type. */
 export const parseCanvasMessage = (data: unknown): CanvasMessage | null => {
   if (!(data && typeof data === 'object' && (data as { version?: unknown }).version === 4)) return null
   const record = data as Record<string, unknown>
   if (!CANVAS_TYPES.has(String(record.type))) return null
   if (stampState(record) === 'malformed') return null
+  if (record.type === 'u90:select' && !validReferenceTrail(record.via)) return null
   if (record.type === 'u90:format' && !isValidFormat(record)) return null
   if (record.type === 'u90:preview' && !isPreviewInstruction(record.instruction)) return null
   return data as CanvasMessage
@@ -267,6 +304,7 @@ export const isSiteMessage = (data: unknown): data is SiteMessage => {
   const record = data as Record<string, unknown>
   if (!SITE_TYPES.has(String(record.type))) return false
   if (stampState(record) === 'malformed') return false
+  if (record.type === 'u90:select' && !validReferenceTrail(record.via)) return false
   if (record.type === 'u90:caret' && !isValidCaret(record)) return false
   if (record.type === 'u90:direction' && !isValidDirection(record)) return false
   return true

package/src/bridge/registry.ts

@@ -1,4 +1,5 @@
 import type { EntryPicks } from './DraftEntries'
+import type { DraftSnapshot } from './protocol'
 import type { Bridge } from './createBridge'
 
 /**
@@ -21,10 +22,14 @@ export const registry: {
   current: Bridge | null
   reveals: Set<{ prefix: string; fn: () => void }>
   entryLists: Set<{ document: Document; beforeRefresh(): void; pick(path: string, picks: EntryPicks): boolean }>
-  blockOrders: Set<{ document: Document; beforeRefresh(): void; needsReload(): boolean; move(path: string, before: string | null): boolean }>
+  draftValues: Set<{ document: Document; beforeRefresh(): void; afterRefresh(): void; preview(snapshot: DraftSnapshot): boolean }>
+  draftContents: Set<{ document: Document; beforeRefresh(): void; preview(path: string, value: unknown[]): boolean }>
+  blockOrders: Set<{ document: Document; beforeRefresh(): void; needsReload(): boolean; remove?(path: string): boolean; move(path: string, before: string | null): boolean }>
 } = {
   current: null,
   reveals: new Set(),
   blockOrders: new Set(),
+  draftContents: new Set(),
+  draftValues: new Set(),
   entryLists: new Set(),
 }

package/src/bridge/selection.ts

@@ -0,0 +1,134 @@
+/** Draft-only selection geometry. Contents wrappers have no CSS box of their own. */
+export function createSelection(win: Window) {
+  const doc = win.document
+  const overlay = doc.createElement('div')
+  overlay.setAttribute('data-u90-selection-overlay', '')
+  overlay.setAttribute('aria-hidden', 'true')
+  overlay.hidden = true
+  let path: string | null = null
+  let shouldReveal = false
+  let frame: number | null = null
+  let observer: MutationObserver | null = null
+  const escaped = (value: string) => value.replace(/["\\]/g, '\\$&')
+  const target = () =>
+    path
+      ? doc.querySelector<HTMLElement>(
+          `[data-u90-field="${escaped(path)}"], [data-u90-block="${escaped(path)}"]`,
+        )
+      : null
+  type Box = {
+    left: number
+    top: number
+    right: number
+    bottom: number
+    width: number
+    height: number
+  }
+  const bounds = (element: Element): Box | null => {
+    const style = win.getComputedStyle(element)
+    if (style.display === 'none' || style.visibility === 'hidden') return null
+    const rect = element.getBoundingClientRect()
+    if (style.display !== 'contents' && rect.width > 0 && rect.height > 0) return rect
+    const children = [...element.children].flatMap((child) => {
+      const box = bounds(child)
+      return box ? [box] : []
+    })
+    if (!children.length) return null
+    const left = Math.min(...children.map((box) => box.left))
+    const top = Math.min(...children.map((box) => box.top))
+    const right = Math.max(...children.map((box) => box.right))
+    const bottom = Math.max(...children.map((box) => box.bottom))
+    return { left, top, right, bottom, width: right - left, height: bottom - top }
+  }
+  const paint = () => {
+    frame = null
+    const element = target()
+    // Server refreshes can replace the selected node without changing its path.
+    element?.setAttribute('data-u90-selected', '')
+    let box = element ? bounds(element) : null
+    if (!element || !box) {
+      overlay.hidden = true
+      return
+    }
+    if (shouldReveal) {
+      shouldReveal = false
+      const margin = Math.min(80, win.innerHeight / 4)
+      if (
+        box.top < margin ||
+        box.top >= win.innerHeight - margin ||
+        (box.height <= win.innerHeight - margin * 2 && box.bottom > win.innerHeight - margin)
+      ) {
+        win.scrollTo({ top: Math.max(0, win.scrollY + box.top - margin), behavior: 'instant' })
+        box = bounds(element) ?? box
+      }
+    }
+    // Ordinary fields keep their existing CSS outline. A contents wrapper needs an overlay.
+    const own = element.getBoundingClientRect()
+    if (own.width > 0 && own.height > 0 && win.getComputedStyle(element).display !== 'contents') {
+      overlay.hidden = true
+      return
+    }
+    Object.assign(overlay.style, {
+      left: `${box.left}px`,
+      top: `${box.top}px`,
+      width: `${box.width}px`,
+      height: `${box.height}px`,
+    })
+    if (!overlay.isConnected) doc.body.appendChild(overlay)
+    overlay.hidden = false
+  }
+  const schedule = () => {
+    if (path && frame === null) frame = win.requestAnimationFrame(paint)
+  }
+  return {
+    select(next: string | null, reveal = false) {
+      doc
+        .querySelectorAll('[data-u90-selected]')
+        .forEach((element) => element.removeAttribute('data-u90-selected'))
+      path = next
+      shouldReveal = reveal
+      target()?.setAttribute('data-u90-selected', '')
+      overlay.hidden = true
+      schedule()
+    },
+    start() {
+      win.addEventListener('scroll', schedule, true)
+      win.addEventListener('resize', schedule)
+      doc.addEventListener('load', schedule, true)
+      const Observer = (win as Window & typeof globalThis).MutationObserver
+      if (Observer) {
+        observer = new Observer((records) => {
+          if (
+            records.some(
+              (record) =>
+                record.target !== overlay &&
+                (record.type !== 'childList' ||
+                  [...record.addedNodes, ...record.removedNodes].some((node) => node !== overlay)),
+            )
+          )
+            schedule()
+        })
+        observer.observe(doc.body, {
+          subtree: true,
+          childList: true,
+          attributes: true,
+          attributeFilter: ['class', 'style', 'hidden'],
+        })
+      }
+    },
+    stop() {
+      observer?.disconnect()
+      observer = null
+      win.removeEventListener('scroll', schedule, true)
+      win.removeEventListener('resize', schedule)
+      doc.removeEventListener('load', schedule, true)
+      if (frame !== null) win.cancelAnimationFrame(frame)
+      frame = null
+      path = null
+      doc
+        .querySelectorAll('[data-u90-selected]')
+        .forEach((element) => element.removeAttribute('data-u90-selected'))
+      overlay.remove()
+    },
+  }
+}

package/src/bridge/styles.ts

@@ -84,10 +84,19 @@ html:not([data-u90-navigation]) a[href]:has([data-u90-field]):hover {
   outline: 1px dashed #FF5D2E;
   outline-offset: 3px;
 }
-html:not([data-u90-navigation]) ${EDITABLE_LEAF_SELECTOR} {
+html:not([data-u90-navigation]):not([data-u90-inspector-only]) ${EDITABLE_LEAF_SELECTOR} {
   cursor: text;
 }
 
+[data-u90-selection-overlay] {
+  position: fixed;
+  pointer-events: none;
+  z-index: 2147483646;
+  box-sizing: border-box;
+  border: 3px solid #FF5D2E;
+}
+[data-u90-selection-overlay][hidden] { display: none; }
+
 [data-u90-selected] {
   outline: 2px solid #FF5D2E !important;
   outline-offset: 5px;

package/src/bridge/useDraftContent.tsx

@@ -0,0 +1,151 @@
+'use client'
+
+import { createContext, useContext, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { applyNativeDraft, NativeDraftReferences, safeDraftPath } from './nativeDraft'
+import type { DraftSnapshot } from './protocol'
+import { registry } from './registry'
+
+/** Set by draft block rendering; published components have no editing owner. */
+export const DraftContentPath = createContext<string | undefined>(undefined)
+
+const unsafe = new Set(['__proto__', 'constructor', 'prototype'])
+function replaceAt(value: unknown, segments: string[], replacement: unknown[]): unknown {
+  if (!segments.length) return replacement
+  const [key, ...rest] = segments
+  if (unsafe.has(key)) return value
+  if (Array.isArray(value)) {
+    const index = value.findIndex(item => item && (item._id === key || item.$path?.split('/').at(-1) === key))
+    if (index < 0) return value
+    return value.map((item, at) => at === index ? replaceAt(item, rest, replacement) : item)
+  }
+  if (!value || typeof value !== 'object' || (rest.length && !Object.hasOwn(value, key))) return value
+  return { ...value, [key]: replaceAt((value as Record<string, unknown>)[key], rest, replacement) }
+}
+
+/** Render native field reads immediately in a client component, before the save/refresh.
+ * Only declared list snapshots under this draft block are accepted. React retains ownership
+ * of its children, keys, animation state and markup; published values pass through unchanged. */
+export function useDraftContent<T>(source: T, field: string): T {
+  const block = useContext(DraftContentPath)
+  const path = block ? `${block}/${field}` : undefined
+  const [shown, setShown] = useState({ path, source, value: source, overrides: new Map<string, unknown[]>() })
+  let current = shown.value
+  if (shown.source !== source || shown.path !== path) {
+    current = source
+    const overrides = shown.path === path ? shown.overrides : new Map<string, unknown[]>()
+    for (const [at, value] of overrides) current = replaceAt(current, at ? at.split('/') : [], value) as T
+    setShown({ path, source, value: current, overrides })
+  }
+  useLayoutEffect(() => {
+    if (!path) return
+    const handler = {
+      document,
+      // Retain visible content until the response arrives. Only edits made AFTER this
+      // refresh starts override its response, including when refreshes overlap.
+      beforeRefresh: () => setShown(value => ({ ...value, overrides: new Map() })),
+      preview: (at: string, value: unknown[]) => {
+        if (at !== path && !at.startsWith(`${path}/`)) return false
+        const relative = at === path ? '' : at.slice(path.length + 1)
+        if (relative.split('/').some(segment => unsafe.has(segment))) return false
+        setShown(previous => {
+          const overrides = new Map(previous.overrides)
+          // A complete parent snapshot supersedes earlier child snapshots.
+          for (const key of overrides.keys()) if (!relative || key === relative || key.startsWith(`${relative}/`)) overrides.delete(key)
+          overrides.set(relative, value)
+          return { ...previous, overrides, value: replaceAt(previous.value, relative ? relative.split('/') : [], value) as T }
+        })
+        return true
+      },
+    }
+    registry.draftContents.add(handler)
+    return () => { registry.draftContents.delete(handler) }
+  }, [path])
+  return path ? current : source
+}
+
+export { applyNativeDraft, NativeDraftReferences } from './nativeDraft'
+
+/** Additional native reads available to this part of the preview, including off-screen entries. */
+const ReferenceValues = createContext<readonly unknown[]>([])
+export function DraftReferences({ values, children }: { values: readonly unknown[]; children: ReactNode }) {
+  const inherited = useContext(ReferenceValues)
+  const combined = useMemo(() => [...inherited, ...values], [inherited, values])
+  return <ReferenceValues.Provider value={combined}>{children}</ReferenceValues.Provider>
+}
+
+const sameSource = (a: unknown, b: unknown): boolean => {
+  if (Object.is(a, b)) return true
+  if (!a || !b || typeof a !== 'object' || typeof b !== 'object' || Array.isArray(a) !== Array.isArray(b)) return false
+  const keys = Object.keys(a)
+  return keys.length === Object.keys(b).length && keys.every(key => Object.hasOwn(b, key) && Object.is((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]))
+}
+
+export type NativeDraftPatch = { path: string; value: unknown }
+const applyPatch = <T,>(source: T, patch: NativeDraftPatch): T => applyNativeDraft(source, patch.path, patch.value)
+const hasNativePath = (value: unknown, seen = new Set<object>()): boolean => {
+  if (!value || typeof value !== 'object' || seen.has(value)) return false
+  seen.add(value)
+  if (typeof (value as { $path?: unknown }).$path === 'string') return true
+  return Object.values(value).some(child => hasNativePath(child, seen))
+}
+
+/** React owns native previews throughout saving; a later refresh settles the server's result.
+ * The optional adapter maps a native patch into a site's existing plain presentation props. */
+export function useDraftPreview<T>(source: T, apply: (source: T, patch: NativeDraftPatch) => T = applyPatch): T {
+  const owner = useContext(DraftContentPath)
+  const references = useContext(ReferenceValues)
+  const [cache] = useState(() => new NativeDraftReferences())
+  const indexed = useRef<{ source: T; references: readonly unknown[] } | null>(null)
+  if (!indexed.current || !sameSource(indexed.current.source, source) || indexed.current.references !== references) {
+    cache.add(references)
+    cache.add(source)
+    indexed.current = { source, references }
+  }
+  const enabled = !!owner || hasNativePath(source)
+  const [shown, setShown] = useState({ source, value: source, owner, overrides: new Map<string, NativeDraftPatch>() })
+  let current = shown.value
+  if (!sameSource(shown.source, source) || shown.owner !== owner) {
+    const overrides = shown.owner === owner ? shown.overrides : new Map<string, NativeDraftPatch>()
+    current = source
+    for (const patch of overrides.values()) current = apply(current, patch)
+    setShown({ source, value: current, owner, overrides })
+  }
+  for (const patch of shown.overrides.values()) cache.patch(patch.path, patch.value)
+  const latest = useRef({ current, source, references, apply })
+  latest.current = { current, source, references, apply }
+  useLayoutEffect(() => {
+    if (!enabled) return
+    const handler = {
+      document,
+      beforeRefresh: () => {
+        cache.beforeRefresh()
+        setShown(value => ({ ...value, overrides: new Map() }))
+      },
+      afterRefresh: () => setShown(previous => {
+        cache.settle([latest.current.references, latest.current.source])
+        let value = latest.current.source
+        for (const patch of previous.overrides.values()) value = latest.current.apply(value, patch)
+        latest.current.current = value
+        return { ...previous, source: latest.current.source, value }
+      }),
+      preview: (snapshot: DraftSnapshot) => {
+        if (!safeDraftPath(snapshot.path)) return false
+        const patch = { path: snapshot.path, value: cache.expand(snapshot) }
+        cache.patch(patch.path, patch.value)
+        const next = latest.current.apply(latest.current.current, patch)
+        if (next === latest.current.current) return false
+        latest.current.current = next
+        setShown(previous => {
+          const overrides = new Map(previous.overrides)
+          for (const key of overrides.keys()) if (key === patch.path || key.startsWith(`${patch.path}/`)) overrides.delete(key)
+          overrides.set(patch.path, patch)
+          return { ...previous, value: next, overrides }
+        })
+        return true
+      },
+    }
+    registry.draftValues.add(handler)
+    return () => { registry.draftValues.delete(handler) }
+  }, [enabled, owner, cache])
+  return enabled ? current : source
+}

package/src/elements/containers/group.ts

@@ -24,7 +24,7 @@ export const group = defineContainer<GroupDecl>({
   enter: (decl, value) => {
     if (value === undefined || value === null) return []
     if (!record(value)) return [{ path: [], code: 'invalid_type', message: 'Expected an object.' }]
-    const known = new Set(['_id', '_block', ...Object.keys(decl.fields), ...Object.values(decl.fields).flatMap((f) => (isLeaf(f) && f.renamedFrom ? [f.renamedFrom] : []))])
+    const known = new Set(['_id', '_block', '_hidden', ...Object.keys(decl.fields), ...Object.values(decl.fields).flatMap((f) => (isLeaf(f) && f.renamedFrom ? [f.renamedFrom] : []))])
     const issues: LeafIssue[] = []
     for (const key of Object.keys(value))
       if (!known.has(key)) issues.push({ path: [key], code: 'unknown-field', message: `No field "${key}" is declared here.`, severity: 'warning' })

package/src/elements/containers/zone.ts

@@ -1,7 +1,18 @@
-import { SLOT, defineContainer, type GroupDecl, type LeafIssue, type ZoneDecl } from '../define'
+import { SLOT, defineContainer, type BlockDecl, type GroupDecl, type LeafIssue, type ZoneDecl } from '../define'
 import { ID_RE } from '../path'
 import { record } from './group'
 
+/** Null content follows the shared Single; an object is an independent page copy. */
+export function blockFields(block: BlockDecl, value: unknown): GroupDecl {
+  const shared = block.shared
+  const linked = shared && (!record(value) || value[shared.field] == null)
+  return {
+    container: 'u90/group',
+    fields: linked ? { ...block.fields, [shared.field]: { element: 'u90/single', label: 'Content', options: { key: shared.single } } } : block.fields,
+    order: block.order,
+  }
+}
+
 /** Every item becomes a group child — a known block's fields, or no fields for SLOT and unknown blocks — so order is kept and nothing under SLOT is visited. */
 export const zone = defineContainer<ZoneDecl>({
   id: 'u90/zone',
@@ -11,7 +22,7 @@ export const zone = defineContainer<ZoneDecl>({
       const block = record(item) && typeof item._block === 'string' && item._block !== SLOT && Object.hasOwn(schema.blocks, item._block) ? schema.blocks[item._block] : undefined
       return {
         key: record(item) && typeof item._id === 'string' ? item._id : `#${i}`,
-        decl: { container: 'u90/group', fields: block?.fields ?? {}, order: block?.order } as GroupDecl,
+        decl: block ? blockFields(block, item) : { container: 'u90/group', fields: {} } as GroupDecl,
         value: item,
         set: (next: unknown) => { value[i] = next },
       }

package/src/elements/declaration.ts

@@ -1,3 +1,4 @@
+import { canonicalJson } from '../site/wire'
 import { z } from 'zod'
 import type { BlockDecl, CollectionDecl, FieldDecl, Issue, LeafDecl, Schema, SingleDecl, ZoneDecl } from './define'
 import { isLeaf } from './define'
@@ -48,19 +49,87 @@ export const FieldDeclSchema: z.ZodType<FieldDecl> = z.lazy(() =>
   ]),
 ) as z.ZodType<FieldDecl>
 const ZoneDeclSchema = z.strictObject({ container: z.literal('u90/zone'), label: z.string().optional(), allow: z.array(z.string().min(1)).min(1), default: z.array(z.string().min(1)).optional(), fixed: z.boolean().optional() })
-export const BlockDeclSchema = z.strictObject({ name: z.string().regex(NAME), label: z.string(), fields: nameRecord(FieldDeclSchema), entry: z.string().optional(), order: z.array(z.string()).optional() })
+export const BlockDeclSchema = z.strictObject({ name: z.string().regex(NAME), label: z.string(), fields: nameRecord(FieldDeclSchema), entry: z.string().optional(), order: z.array(z.string()).optional(), shared: z.strictObject({ single: z.string().regex(/^[a-z][a-zA-Z0-9_-]*$/), field: z.string().regex(NAME), previewFields: z.array(z.string().regex(NAME)).min(1).max(30).refine(keys => new Set(keys).size === keys.length).optional() }).optional() })
   .superRefine((obj, ctx) => checkOrder(obj.fields, obj.order, ctx))
+const AuthoringAnchorLabel = z.string().trim().min(1).max(80)
+const AuthoringAnchorSchema = z.union([
+  z.strictObject({ label: AuthoringAnchorLabel, fields: z.array(z.string().regex(NAME)).min(1) }),
+  z.strictObject({ label: AuthoringAnchorLabel, single: z.string().regex(/^[a-z][a-zA-Z0-9_-]*$/) }),
+])
 export const CollectionDeclSchema = z.strictObject({
   name: z.string().regex(NAME), label: z.string(), fields: nameRecord(FieldDeclSchema), template: ZoneDeclSchema.optional(),
   defaultSort: z.union([z.strictObject({ field: z.string(), dir: z.enum(['asc', 'desc']) }), z.literal('manual')]).optional(),
   order: z.array(z.string()).optional(),
-}).superRefine((obj, ctx) => checkOrder(obj.fields, obj.order, ctx))
+  authoring: z.strictObject({
+    create: z.strictObject({ fields: z.array(z.string().regex(NAME)).min(1).max(8) }).optional(),
+    sections: z.strictObject({
+      block: z.string().regex(NAME), field: z.string().regex(NAME),
+      before: z.array(AuthoringAnchorSchema).optional(), after: z.array(AuthoringAnchorSchema).optional(),
+    }).optional(),
+  }).optional(),
+}).superRefine((obj, ctx) => {
+  checkOrder(obj.fields, obj.order, ctx)
+  const names = obj.authoring?.create?.fields
+  if (!names) return
+  const title = [...(obj.order ?? []), ...Object.keys(obj.fields)].find((name) => {
+    const field = obj.fields[name]
+    return field && isLeaf(field) && field.element === 'u90/text'
+  })
+  if (title && names[0] !== title) ctx.addIssue({ code: 'custom', path: ['authoring', 'create', 'fields'], message: 'The creation form must start with the collection title field.' })
+  const seen = new Set<string>()
+  names.forEach((name, index) => {
+    const field = Object.hasOwn(obj.fields, name) ? obj.fields[name] : undefined
+    if (seen.has(name) || !field || !isLeaf(field) || field.element !== 'u90/text' || field.lock?.length)
+      ctx.addIssue({ code: 'custom', path: ['authoring', 'create', 'fields', index], message: 'Creation fields must be unique, declared, editable text fields.' })
+    seen.add(name)
+  })
+})
 export const SingleDeclSchema = z.strictObject({ key: z.string().regex(/^[a-z][a-zA-Z0-9_-]*$/), field: FieldDeclSchema })
 export const SchemaSchema = z.strictObject({ blocks: z.record(z.string(), BlockDeclSchema), collections: z.record(z.string(), CollectionDeclSchema), singles: z.record(z.string(), SingleDeclSchema) })
 
 type Where = 'block' | 'collection' | 'single'
 const issue = (path: string[], code: string, message: string): Issue => ({ path: path.join('.'), code, message, severity: 'error' })
 
+/** A section wrapper may be hidden only when its other content remains reachable or fixed. */
+const collectionSectionsIssues = (schema: Schema, collection: CollectionDecl, name: string): Issue[] => {
+  const sections = collection.authoring?.sections
+  if (!sections) return []
+  const at = ['collections', name, 'authoring', 'sections']
+  const issues: Issue[] = []
+  const template = collection.template
+  if (!template?.fixed || template.allow.length !== 1 || template.allow[0] !== sections.block || template.default?.length !== 1 || template.default[0] !== sections.block)
+    issues.push(issue(at, 'authoring-sections-template', 'Page sections require the named block to be the sole allowed and default block of a fixed collection template.'))
+  const wrapper = Object.hasOwn(schema.blocks, sections.block) ? schema.blocks[sections.block] : undefined
+  if (!wrapper || wrapper.entry !== name)
+    issues.push(issue([...at, 'block'], 'authoring-sections-block', 'The section wrapper must be a declared block whose entry is this collection.'))
+  if (wrapper) {
+    const zone = Object.hasOwn(wrapper.fields, sections.field) ? wrapper.fields[sections.field] : undefined
+    if (!zone || isLeaf(zone) || zone.container !== 'u90/zone')
+      issues.push(issue([...at, 'field'], 'authoring-sections-field', 'Page sections must name a direct zone field on the wrapper block.'))
+    if (Object.entries(wrapper.fields).some(([key, field]) => key !== sections.field && (!isLeaf(field) || !field.lock?.includes('$'))))
+      issues.push(issue([...at, 'block'], 'authoring-sections-block', 'The section wrapper may have no other editable fields; additional leaves must lock their whole value with "$".'))
+  }
+  const seenFields = new Set<string>()
+  const seenSingles = new Set<string>()
+  for (const position of ['before', 'after'] as const) {
+    for (const [index, anchor] of (sections[position] ?? []).entries()) {
+      const anchorAt = [...at, position, String(index)]
+      if ('fields' in anchor) {
+        anchor.fields.forEach((field, fieldIndex) => {
+          if (!Object.hasOwn(collection.fields, field) || seenFields.has(field))
+            issues.push(issue([...anchorAt, 'fields', String(fieldIndex)], 'authoring-anchor-field', 'Pinned fields must be declared collection fields and appear only once across section anchors.'))
+          seenFields.add(field)
+        })
+      } else {
+        if (!Object.hasOwn(schema.singles, anchor.single) || seenSingles.has(anchor.single))
+          issues.push(issue([...anchorAt, 'single'], 'authoring-anchor-single', 'Pinned singles must be declared singles and appear only once across section anchors.'))
+        seenSingles.add(anchor.single)
+      }
+    }
+  }
+  return issues
+}
+
 /** Parses, then checks everything the zod shape cannot: placement, cross-references, options, defaults, and fills query targetFields. */
 export function validateSchema(input: unknown): { ok: true; schema: Schema } | { ok: false; issues: Issue[] } {
   const parsed = SchemaSchema.safeParse(input)
@@ -105,13 +174,31 @@ export function validateSchema(input: unknown): { ok: true; schema: Schema } | {
     }
     zone(d, at)
   }
+  // Additional fields may retain code-owned design settings; the shared editor only
+  // presents the Single's content, so editable extras would be unreachable.
+  const lockedDesign = (decl: FieldDecl): boolean => isLeaf(decl)
+    ? !!decl.lock?.includes('$')
+    : decl.container === 'u90/group' && Object.values(decl.fields).every(lockedDesign)
   for (const [n, b] of Object.entries(schema.blocks)) {
+    if (b.shared) {
+      const source = schema.singles[b.shared.single]?.field
+      const local = b.fields[b.shared.field]
+      if (!source || Object.entries(b.fields).some(([key, value]) => key !== b.shared!.field && !lockedDesign(value)) || !local || isLeaf(local) || local.container !== 'u90/group' || canonicalJson(source) !== canonicalJson(local))
+        issues.push(issue(['blocks', n, 'shared'], 'invalid-shared-block', 'A shared block must have a content group matching its declared Single; additional fields must be locked design settings.'))
+    }
+
+    if (b.shared?.previewFields && b.shared.previewFields.some(key => {
+      const content = b.fields[b.shared!.field]
+      return !content || isLeaf(content) || content.container !== 'u90/group' || !Object.hasOwn(content.fields, key)
+    })) issues.push(issue(['blocks', n, 'shared', 'previewFields'], 'unknown-field', 'Shared preview fields must exist in the content group.'))
+
     if (b.entry && !schema.collections[b.entry]) issues.push(issue(['blocks', n, 'entry'], 'unknown-collection', `No collection named "${b.entry}".`))
     Object.entries(b.fields).forEach(([f, d]) => field(d, ['blocks', n, 'fields', f], 'block'))
   }
   for (const [n, c] of Object.entries(schema.collections)) {
     Object.entries(c.fields).forEach(([f, d]) => field(d, ['collections', n, 'fields', f], 'collection'))
     if (c.template) zone(c.template, ['collections', n, 'template'])
+    issues.push(...collectionSectionsIssues(schema, c, n))
   }
   for (const [n, s] of Object.entries(schema.singles)) field(s.field, ['singles', n, 'field'], 'single')
   return issues.length ? { ok: false, issues } : { ok: true, schema }