@unitninety/site-kit 1.6.2 → 1.6.3

package/README.md

@@ -5,13 +5,38 @@ The library a UnitNinety site is built on. It reads the site's content from Unit
 You do not usually add it by hand. The `u90` tool adds it when it converts a Next.js App Router site, at the one version that release of the tool works with:
 
 ```bash
-npx --yes @unitninety/u90@1.0.1 --version
+npx --yes @unitninety/u90@1.0.3 --version
 ```
 
 UnitNinety imports packages made for that version only, so keep the version the tool names.
 
 Documentation: [converting a site](https://unitninety.com/docs/convert), [importing it](https://unitninety.com/docs/import) and [the U90 package](https://unitninety.com/docs/package).
 
+### Fixed field values
+
+Use `lock: ['$']` on a leaf such as `number({ lock: ['$'] })` to retain a site-owned value without offering a content editor for it. Updates cannot change, clear, or remove that field, including when its previous value was absent. The stored value remains available to site reads and exports. Existing locks such as `lock: ['to']` on a link continue to protect only that subpath.
+
+Initial document creation and imports may initialise locked values, as may a new block or list item. Once that item exists, its locked fields are fixed; removing the entire editable item still follows the containing zone or list's rules. A whole-field lock does not supply a value, so declare a default when new entries need one.
+
+### Short collection creation forms
+
+Choose the text fields a client fills in before opening a new entry in Canvas:
+
+```ts
+const capabilities = collection('capabilities', {
+  route: '/capabilities/:slug',
+  fields: {
+    name: text({ label: 'Capability name' }),
+    shortSummary: text({ label: 'Summary', multiline: true }),
+  },
+  authoring: { create: { fields: ['name', 'shortSummary'] } },
+})
+```
+
+The form uses each field's label, default and text constraints. The list must contain 1–8 unique, editable text fields and start with the collection's first declared text field (its title). Locked, unknown or non-text fields are rejected. Collections without this optional metadata keep their title-only creation form. The metadata survives templates and manifest/package round trips; it does not alter stored content or the page design.
+
+Creation saves a draft with the normal schema defaults and approved template. Routed entries open Canvas for images and sections; collections without pages keep their content editor in the CMS. The matching platform/Site Kit implementation must be deployed together before using this new metadata in an uploaded package.
+
 ### Immediate collection-list previews
 
 Render a query's `EntriesRead` with `Entries` from `@unitninety/site-kit/components` when its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unitninety/site-kit",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "The client-site half of the UnitNinety platform contract: schema authoring, content fetching, the editing bridge and the pairing CLI.",
   "type": "module",
   "exports": {

package/src/bridge/DraftBlocks.tsx

@@ -1,7 +1,8 @@
 'use client'
 
-import { Fragment, useCallback, useLayoutEffect, useRef, useState, type ReactNode } from 'react'
+import { useCallback, useLayoutEffect, useRef, useState, type ReactNode } from 'react'
 
+import { DraftContentPath } from './useDraftContent'
 import { registry } from './registry'
 import { needsEmbedReload, preserveBlockMoves } from './preserveBlockMoves'
 import { PreviewCommitBoundary } from './PreviewCommitBoundary'
@@ -33,21 +34,27 @@ export function DraftBlocks({ items }: { items: Item[] }) {
     host.current = node
     return preserveBlockMoves(node)
   }, [])
-  const [shown, setShown] = useState({ source: items, items, order: null as string[] | null })
+  const [shown, setShown] = useState({ source: items, items, order: null as string[] | null, removed: new Set<string>() })
   // Keep the desired order, not a log to replay: the server response may already
   // contain later moves, and applying a sequence twice is not generally idempotent.
   const ranks = new Map(shown.order?.map((id, index) => [id, index]))
-  const known = items.filter((item) => ranks.has(item.id)).sort((a, b) => ranks.get(a.id)! - ranks.get(b.id)!)
+  const available = items.filter(item => !item.path || !shown.removed.has(item.path))
+  const known = available.filter((item) => ranks.has(item.id)).sort((a, b) => ranks.get(a.id)! - ranks.get(b.id)!)
   let knownIndex = 0
-  const current = shown.source === items ? shown.items : shown.order === null ? items
-    : items.map((item) => ranks.has(item.id) ? known[knownIndex++]! : item)
+  const current = shown.source === items ? shown.items : shown.order === null ? available
+    : available.map((item) => ranks.has(item.id) ? known[knownIndex++]! : item)
   if (shown.source !== items) setShown({ ...shown, source: items, items: current })
 
   useLayoutEffect(() => {
     const handler = {
       document,
       needsReload: () => reload.current,
-      beforeRefresh: () => setShown((value) => ({ ...value, order: null })),
+      beforeRefresh: () => setShown((value) => ({ ...value, order: null, removed: new Set() })),
+      remove: (path: string) => {
+        if (!current.some(item => item.path === path)) return false
+        setShown(value => ({ ...value, items: value.items.filter(item => item.path !== path), removed: new Set([...value.removed, path]) }))
+        return true
+      },
       move: (path: string, before: string | null) => {
         if (!current.some((item) => item.path === path)) return false
         if (before !== null && !current.some((item) => item.path === before)) return false
@@ -66,5 +73,5 @@ export function DraftBlocks({ items }: { items: Item[] }) {
     return () => { registry.blockOrders.delete(handler) }
   }, [current])
 
-  return <PreviewCommitBoundary source={items}><div data-u90-draft-zone="" style={{ display: 'contents' }} ref={attachHost}>{current.map((item) => <Fragment key={item.id}>{item.content}</Fragment>)}</div></PreviewCommitBoundary>
+  return <PreviewCommitBoundary source={items}><div data-u90-draft-zone="" style={{ display: 'contents' }} ref={attachHost}>{current.map((item) => <DraftContentPath.Provider key={item.id} value={item.path}>{item.content}</DraftContentPath.Provider>)}</div></PreviewCommitBoundary>
 }

package/src/bridge/U90Bridge.tsx

@@ -19,11 +19,11 @@ import { EditingProvider } from './hooks'
  * Ordinary visitors perform no I/O here. Test previews additionally verify their session with the
  * source trust response; pass `u90.testPreview` to share the connection's bounded trust cache.
  */
-type BridgeProps = { platformOrigin: string; children: ReactNode; draft: NextAdapters['draft']; testPreview?: () => Promise<TestPreviewContext | null> }
-async function Gate({ platformOrigin, children, draft, testPreview }: BridgeProps) {
+type BridgeProps = { platformOrigin: string; children: ReactNode; draft: NextAdapters['draft']; inlineEditing?: boolean; testPreview?: () => Promise<TestPreviewContext | null> }
+async function Gate({ platformOrigin, children, draft, testPreview, inlineEditing }: BridgeProps) {
   const runtime = createTestPreviewRuntime({ env: { PLATFORM_URL: process.env.PLATFORM_URL, PAYLOAD_API_KEY: process.env.PAYLOAD_API_KEY, SITE_URL: process.env.SITE_URL } })
   const props = await resolveBridgePreview({ platformOrigin, draft, resolve: testPreview ? () => testPreview() : token => runtime.resolve(token) })
-  return <EditingProvider {...props}>{children}</EditingProvider>
+  return <EditingProvider {...props} inlineEditing={inlineEditing}>{children}</EditingProvider>
 }
 
 /**
@@ -42,13 +42,16 @@ export function U90Bridge({
   children,
   draft = nextAdapters.draft,
   testPreview,
+  inlineEditing = true,
   platformOrigin = process.env.PLATFORM_URL ? new URL(process.env.PLATFORM_URL).origin : '',
 }: {
   children: ReactNode
   platformOrigin?: string
+  /** Set false to edit through the inspector while canvas clicks only select fields. */
+  inlineEditing?: boolean
   draft?: NextAdapters['draft']
   /** Pass u90.testPreview to share its configured connection and injected adapters. */
   testPreview?: () => Promise<TestPreviewContext | null>
 }) {
-  return <Suspense fallback={null}><Gate platformOrigin={platformOrigin} draft={draft} testPreview={testPreview}>{children}</Gate></Suspense>
+  return <Suspense fallback={null}><Gate platformOrigin={platformOrigin} draft={draft} testPreview={testPreview} inlineEditing={inlineEditing}>{children}</Gate></Suspense>
 }

package/src/bridge/client.tsx

@@ -13,7 +13,7 @@ import { createBridge, type Bridge } from './createBridge'
  * Renders nothing; all of its work is the `createBridge` instance it starts and stops, plus the
  * `usePathname()` effect below that reports a client-side navigation as `u90:path`.
  */
-export function BridgeClient({ platformOrigin, onSelect }: { platformOrigin: string; onSelect?: (path: string | null) => void }) {
+export function BridgeClient({ platformOrigin, onSelect, inlineEditing = true }: { platformOrigin: string; onSelect?: (path: string | null, via?: string[]) => void; inlineEditing?: boolean }) {
   const router = useRouter()
   const bridgeRef = useRef<Bridge | null>(null)
   /*
@@ -32,6 +32,7 @@ export function BridgeClient({ platformOrigin, onSelect }: { platformOrigin: str
       parent: window.parent,
       refresh: () => startTransition(() => router.refresh()),
       onSelect,
+      inlineEditing,
     })
     bridgeRef.current = bridge
     bridge.start()
@@ -39,7 +40,7 @@ export function BridgeClient({ platformOrigin, onSelect }: { platformOrigin: str
       bridge.stop()
       bridgeRef.current = null
     }
-  }, [platformOrigin, router, onSelect])
+  }, [platformOrigin, router, onSelect, inlineEditing])
 
   // Only the end matters: the bridge marks the start itself. A slow refresh warns; only a real completion releases its boundary.
   useEffect(() => {

package/src/bridge/createBridge.ts

@@ -4,13 +4,16 @@ import { toRichText, type DomLike } from './lexicalDom'
 import { applyPreview, type Undo } from './preview'
 import { BRIDGE_VERSION, MAX_OFFENDER_LENGTH, MAX_OFFENDERS, parseCanvasMessage, type BridgeStamp, type PreviewInstruction, type SiteMessage } from './protocol'
 import { registry } from './registry'
+import { createSelection } from './selection'
 import { EDITING_CSS } from './styles'
 
 export type BridgeOptions = {
   platformOrigin: string
   parent: Pick<Window, 'postMessage'>
   refresh: () => void
-  onSelect?: (path: string | null) => void
+  onSelect?: (path: string | null, via?: string[]) => void
+  /** False selects canvas fields without enabling browser typing; inspector previews still apply. */
+  inlineEditing?: boolean
 }
 
 const DEBOUNCE = 150
@@ -244,10 +247,10 @@ export function createBridge(win: Window, opts: BridgeOptions) {
   }
 
   /** Outline the element at `path` (field or block) and clear any previous outline. */
-  const markSelected = (path: string | null) => {
-    doc.querySelectorAll('[data-u90-selected]').forEach((e) => e.removeAttribute('data-u90-selected'))
-    if (path) doc.querySelector(`[data-u90-field="${q(path)}"], [data-u90-block="${q(path)}"]`)?.setAttribute('data-u90-selected', '')
-    opts.onSelect?.(path)
+  const selection = createSelection(win)
+  const markSelected = (path: string | null, scroll = false, via?: string[]) => {
+    selection.select(path, scroll)
+    opts.onSelect?.(path, via)
   }
 
   /** `u90:select` from the Canvas also fires any `useReveal` listener whose prefix matches. */
@@ -383,10 +386,16 @@ export function createBridge(win: Window, opts: BridgeOptions) {
       // (a menu toggle) still works while the Canvas is open.
       e.preventDefault()
     }
-    markSelected(path)
-    send({ type: 'u90:select', path })
+    const ancestors: string[] = []
+    for (let node: Element | null = el ?? null; node; node = node.parentElement) {
+      const reference = node.getAttribute('data-u90-reference')
+      if (reference && reference !== path) ancestors.unshift(reference)
+    }
+    const via = ancestors.length > 0 && ancestors.length <= 5 ? ancestors : undefined
+    markSelected(path, false, via)
+    send({ type: 'u90:select', path, ...(via ? {via} : {}) })
     const edit = el?.getAttribute('data-u90-edit') as 'text' | 'rich' | 'link-label' | null
-    if (el && edit && isEditableLeaf(el)) {
+    if (opts.inlineEditing !== false && el && edit && isEditableLeaf(el)) {
       // Resolve the caret target before the element becomes editable, apply it after —
       // `contenteditable` changes hit-testing (see `caret.ts`'s `caretTargetIn` doc).
       const target = caretTargetIn(el, mouse.clientX, mouse.clientY)
@@ -396,6 +405,7 @@ export function createBridge(win: Window, opts: BridgeOptions) {
   }
 
   const onInput = (e: Event) => {
+    if (opts.inlineEditing === false) return
     const el = (e.target as Element | null)?.closest<HTMLElement>('[data-u90-edit]')
     if (el) {
       schedule(el)
@@ -515,6 +525,7 @@ export function createBridge(win: Window, opts: BridgeOptions) {
    */
   const REFRESH_CEILING_MS = 5000
   const setRefreshing = (value: boolean) => {
+    const committed = refreshing && !value
     refreshing = value
     if (refreshingTimer) clearTimeout(refreshingTimer)
     refreshingTimer = null
@@ -526,10 +537,13 @@ export function createBridge(win: Window, opts: BridgeOptions) {
       // A pending timer must not keep a Node process alive (tests); browsers return a number.
       ;(refreshingTimer as unknown as { unref?: () => void }).unref?.()
     }
-    else if (refreshAgain) requestRefresh()
+    else {
+      if (committed) for (const owner of registry.draftValues) if (owner.document === doc) owner.afterRefresh()
+      if (refreshAgain) requestRefresh()
+    }
   }
   function requestRefresh() {
-    if (refreshing && [...registry.blockOrders, ...registry.entryLists].some((owner) => owner.document === doc)) {
+    if (refreshing && [...registry.blockOrders, ...registry.entryLists, ...registry.draftContents, ...registry.draftValues].some((owner) => owner.document === doc)) {
       refreshAgain = true
       return
     }
@@ -540,7 +554,7 @@ export function createBridge(win: Window, opts: BridgeOptions) {
     }
     // One refresh boundary at a time: newer moves stay visible through the older render.
     // Clear only the moves included when THIS request starts, never when another is queued.
-    for (const owner of [...registry.blockOrders, ...registry.entryLists]) if (owner.document === doc) owner.beforeRefresh()
+    for (const owner of [...registry.blockOrders, ...registry.entryLists, ...registry.draftContents, ...registry.draftValues]) if (owner.document === doc) owner.beforeRefresh()
     const restoreEditing = preserveEditing()
     try {
       undoPreviews()
@@ -554,11 +568,28 @@ export function createBridge(win: Window, opts: BridgeOptions) {
   const preview = (instruction: PreviewInstruction) => {
     // React-owned order is safe even while a refresh is pending. Only legacy DOM moves
     // still need the guard below; they can disagree with React's tree during a commit.
+    const draft = instruction.kind === 'value' ? instruction : instruction.draft
+    if (draft) {
+      let handled = false
+      for (const owner of registry.draftValues) if (owner.document === doc) handled = owner.preview(draft) || handled
+      if (handled || instruction.kind === 'value') return
+    }
+    const list = instruction.kind === 'list' ? instruction : instruction.list
+    if (list) {
+      let handled = false
+      for (const owner of registry.draftContents) if (owner.document === doc) handled = owner.preview(list.path, list.value) || handled
+      if (handled || instruction.kind === 'list') return
+    }
     if (instruction.kind === 'entries') {
       // All renderings of this placement update, including duplicate responsive layouts.
       for (const owner of registry.entryLists) if (owner.document === doc) owner.pick(instruction.path, instruction)
       return
     }
+    if (instruction.kind === 'remove') {
+      let handled = false
+      for (const owner of registry.blockOrders) if (owner.document === doc) handled = !!owner.remove?.(instruction.path) || handled
+      if (handled) return
+    }
     if (instruction.kind === 'move') {
       for (const owner of registry.blockOrders) {
         if (owner.document === doc && owner.move(instruction.path, instruction.before)) return
@@ -658,8 +689,8 @@ export function createBridge(win: Window, opts: BridgeOptions) {
         if (!refreshing) void loadFragment(m.instruction)
       } else preview(m.instruction)
     } else if (m.type === 'u90:select') {
-      markSelected(m.path)
       reveal(m.path)
+      markSelected(m.path, m.reveal === true, m.via)
     } else if (m.type === 'u90:flush') {
       flush()
       send({ type: 'u90:flushed', requestId: m.requestId })
@@ -930,6 +961,8 @@ export function createBridge(win: Window, opts: BridgeOptions) {
       send({ type: 'u90:ready', path: win.location.pathname })
 
       doc.head.appendChild(style)
+      if (opts.inlineEditing === false) doc.documentElement.setAttribute('data-u90-inspector-only', '')
+      selection.start()
       applyDraftLanguage()
       doc.addEventListener('click', onClick, true)
       doc.addEventListener('input', onInput, true)
@@ -965,6 +998,8 @@ export function createBridge(win: Window, opts: BridgeOptions) {
       flush()
       releaseViewport()
       style.remove()
+      if (opts.inlineEditing === false) doc.documentElement.removeAttribute('data-u90-inspector-only')
+      selection.stop()
       doc.removeEventListener('click', onClick, true)
       doc.removeEventListener('input', onInput, true)
       doc.removeEventListener('focusout', onBlur, true)

package/src/bridge/hooks.tsx

@@ -1,14 +1,14 @@
 'use client'
 
-import { createContext, lazy, Suspense, useContext, useEffect, useState, type ReactNode } from 'react'
+import { createContext, lazy, Suspense, useCallback, useContext, useEffect, useState, type ReactNode } from 'react'
 
 import { registry } from './registry'
 
 const LazyBridgeClient = lazy(() => import('./client').then((m) => ({ default: m.BridgeClient })))
 
-type EditingContextValue = { editing: boolean; selected: string | null; testPreview: boolean }
+type EditingContextValue = { editing: boolean; selected: string | null; selectedVia: readonly string[]; testPreview: boolean }
 
-const Ctx = createContext<EditingContextValue>({ editing: false, selected: null, testPreview: false })
+const Ctx = createContext<EditingContextValue>({ editing: false, selected: null, selectedVia: [], testPreview: false })
 
 /**
  * Mounted once, at the root, by `U90Bridge` — always mounted so `useEditing()` works from
@@ -19,22 +19,23 @@ const Ctx = createContext<EditingContextValue>({ editing: false, selected: null,
  * `import('./client')` pulls in `next/navigation` and the whole DOM-level bridge, so a production
  * (non-draft) render never fetches that chunk at all.
  */
-export function EditingProvider({ editing, platformOrigin, testPreview = false, children }: { editing: boolean; platformOrigin: string; testPreview?: boolean; children: ReactNode }) {
-  const [selected, setSelected] = useState<string | null>(null)
+export function EditingProvider({ editing, platformOrigin, testPreview = false, inlineEditing = true, children }: { editing: boolean; platformOrigin: string; testPreview?: boolean; inlineEditing?: boolean; children: ReactNode }) {
+  const [selection, setSelection] = useState<{path: string | null; via: string[]}>({path: null, via: []})
+  const onSelect = useCallback((path: string | null, via?: string[]) => setSelection({path, via: via ?? []}), [])
 
   return (
-    <Ctx.Provider value={{ editing, selected, testPreview }}>
+    <Ctx.Provider value={{ editing, selected: selection.path, selectedVia: selection.via, testPreview }}>
       {children}
       {editing ? (
         <Suspense fallback={null}>
-          <LazyBridgeClient platformOrigin={platformOrigin} onSelect={setSelected} />
+          <LazyBridgeClient platformOrigin={platformOrigin} onSelect={onSelect} inlineEditing={inlineEditing} />
         </Suspense>
       ) : null}
     </Ctx.Provider>
   )
 }
 
-/** `{ editing, selected }` — `selected` is the path last reported by `u90:select`, either way. */
+/** `selectedVia` identifies the reference fields leading to the selected entry. `{ editing, selected }` — `selected` is the path last reported by `u90:select`, either way. */
 export const useEditing = (): EditingContextValue => useContext(Ctx)
 
 /**

package/src/bridge/index.ts

@@ -7,3 +7,9 @@
 export { BridgeClient } from './client'
 export { EditingProvider, useEditing, useReveal } from './hooks'
 export { BRIDGE_VERSION, isSiteMessage, parseCanvasMessage, type BridgeStamp, type CanvasMessage, type PreviewInstruction, type SiteMessage } from './protocol'
+
+/** Stable preview ordering for custom server-rendered sections with native block paths. */
+export { DraftBlocks } from './DraftBlocks'
+
+/** React-owned previews for client components reading list content inside a draft block. */
+export { useDraftContent, useDraftPreview, DraftReferences, applyNativeDraft, type NativeDraftPatch } from './useDraftContent'

package/src/bridge/nativeDraft.ts

@@ -0,0 +1,177 @@
+import { isLeaf, type EntryRead, type ExpandCtx, type FieldDecl, type Id, type MediaRecord, type PageRecord, type Schema } from '../elements/define'
+import { getContainer } from '../elements/registry'
+import { expandField } from '../elements/ops/expand'
+import { applyQueryPicks, type QueryStored } from '../elements/leaves/query'
+import type { EntriesRead } from '../elements/leaves/selection'
+import type { DraftSnapshot } from './protocol'
+
+const unsafe = new Set(['__proto__', 'constructor', 'prototype'])
+const object = (value: unknown): value is Record<string, any> => !!value && typeof value === 'object' && !Array.isArray(value)
+export const safeDraftPath = (path: string) => /^(page|entry|layout|single):[^/]+(?:\/[^/]+)*$/.test(path) && !path.split('/').some(key => unsafe.has(key))
+
+/** Native groups do not carry paths; their children do. Infer only when the children agree. */
+export function nativePath(value: unknown, seen = new Set<object>()): string | undefined {
+  if (!value || typeof value !== 'object' || seen.has(value)) return
+  seen.add(value)
+  if (object(value) && typeof value.$path === 'string') return safeDraftPath(value.$path) ? value.$path : undefined
+  const candidates = new Set<string>()
+  for (const [key, child] of Object.entries(value)) {
+    if (unsafe.has(key) || key.startsWith('$')) continue
+    const at = nativePath(child, seen)
+    if (!at) continue
+    if (Array.isArray(value) && at.includes('/')) candidates.add(at.slice(0, at.lastIndexOf('/')))
+    else if (at.endsWith(`/${key}`)) candidates.add(at.slice(0, -key.length - 1))
+  }
+  return candidates.size === 1 ? [...candidates][0] : undefined
+}
+
+/** Immutable path replacement across any mixture of native document, entry and field reads. */
+export function applyNativeDraft<T>(source: T, path: string, replacement: unknown): T {
+  if (!safeDraftPath(path)) return source
+  const visit = (value: unknown, parent?: string, seen = new Set<object>()): unknown => {
+    const at = nativePath(value) ?? parent
+    if (at === path || parent === path) return replacement
+    if (!value || typeof value !== 'object' || seen.has(value)) return value
+    const nextSeen = new Set(seen).add(value)
+    let result: any = value
+    for (const [key, child] of Object.entries(value)) {
+      if (unsafe.has(key) || key.startsWith('$')) continue
+      const id = Array.isArray(value) ? (object(child) ? child._id : undefined) : key
+      const next = visit(child, at && typeof id === 'string' ? `${at}/${id}` : undefined, nextSeen)
+      if (next !== child) {
+        if (result === value) result = Array.isArray(value) ? [...value] : { ...value }
+        result[key] = next
+      }
+    }
+    return result
+  }
+  return visit(source) as T
+}
+
+/** A local index of real native reads. Missing references remain missing until the server answers. */
+export class NativeDraftReferences {
+  private reads = new Map<string, unknown>()
+  private pending = new Map<string, unknown>()
+  private media = new Map<string, MediaRecord>()
+  private pages = new Map<string, PageRecord>()
+  private entries = new Map<string, EntryRead>()
+  private singles = new Map<string, unknown>()
+  private queries = new Map<string, EntriesRead>()
+
+  add(values: unknown): void {
+    const seen = new Set<object>()
+    const visit = (value: unknown, parent?: string) => {
+      if (parent) this.reads.set(parent, value)
+      if (!value || typeof value !== 'object' || seen.has(value)) return
+      seen.add(value)
+      const at = nativePath(value) ?? parent
+      if (at) this.reads.set(at, value)
+      if (object(value)) {
+        if (at?.startsWith('single:') && !at.includes('/')) this.singles.set(at.slice(7), value)
+        if (value.id !== undefined && typeof value.url === 'string' && typeof value.mimeType === 'string') {
+          const known = this.media.get(String(value.id))
+          this.media.set(String(value.id), { ...value, renditions: value.renditions ?? known?.renditions } as MediaRecord)
+        }
+        if (value.id !== undefined && typeof value.route === 'string' && typeof value.title === 'string') this.pages.set(String(value.id), value as PageRecord)
+        if (value.id !== undefined && typeof value.collection === 'string' && (value.status === 'ready' || value.status === 'missing')) {
+          const key = `${value.collection}:${value.id}`
+          const known = this.entries.get(key)
+          if (!known?.fields || value.fields) this.entries.set(key, value as EntryRead)
+        }
+        if (typeof value.$path === 'string' && Array.isArray(value.entries)) this.queries.set(value.$path, value as EntriesRead)
+        if (object(value.to) && typeof value.href === 'string' && value.href.startsWith('/')) {
+          const route = value.href.split(/[?#]/)[0]
+          if (value.to.page !== undefined) this.pages.set(String(value.to.page), { id: value.to.page, route, title: value.label ?? '' })
+          if (object(value.to.entry)) {
+            const key = `${value.to.entry.collection}:${value.to.entry.id}`
+            if (!this.entries.has(key)) this.entries.set(key, { ...value.to.entry, route, status: 'ready' } as EntryRead)
+          }
+        }
+        // Preserve the already produced crop rendition when all we have is a read asset.
+        if (object(value.asset) && object(value.rendition)) {
+          const asset = value.asset as MediaRecord
+          const previous = this.media.get(String(asset.id))
+          this.media.set(String(asset.id), { ...asset, renditions: [...(previous?.renditions ?? []), { url: value.rendition.url, width: value.rendition.width, height: value.rendition.height, ...(value.rendition.blurDataURL ? { blurDataURL: value.rendition.blurDataURL } : {}), crop: value.crop ?? null, status: 'ready' }] })
+        }
+      }
+      for (const [key, child] of Object.entries(value)) {
+        if (unsafe.has(key) || key.startsWith('$')) continue
+        const id = Array.isArray(value) ? (object(child) ? child._id : undefined) : key
+        visit(child, at && typeof id === 'string' ? `${at}/${id}` : undefined)
+      }
+    }
+    visit(values)
+    for (const [path, value] of this.pending) this.applyPatch(path, value)
+  }
+
+  patch(path: string, value: unknown): void {
+    if (!path.startsWith('entry:') && !path.startsWith('single:')) return
+    for (const key of this.pending.keys()) if (key === path || key.startsWith(`${path}/`)) this.pending.delete(key)
+    this.pending.set(path, value)
+    this.applyPatch(path, value)
+  }
+
+  beforeRefresh(): void { this.pending.clear() }
+
+  settle(values: unknown): void {
+    this.reads.clear()
+    this.entries.clear()
+    this.media.clear()
+    this.pages.clear()
+    this.singles.clear()
+    this.queries.clear()
+    this.add(values)
+  }
+
+  private applyPatch(path: string, value: unknown): void {
+    for (const [key, read] of this.reads) this.reads.set(key, key === path ? value : applyNativeDraft(read, path, value))
+    for (const [key, entry] of this.entries) this.entries.set(key, applyNativeDraft(entry, path, value))
+    for (const [key, single] of this.singles) this.singles.set(key, applyNativeDraft(single, path, value))
+    for (const [key, query] of this.queries) this.queries.set(key, applyNativeDraft(query, path, value))
+  }
+
+  expand(snapshot: DraftSnapshot): unknown {
+    for (const media of snapshot.media ?? []) this.media.set(String(media.id), { ...media, renditions: media.renditions ?? this.media.get(String(media.id))?.renditions })
+    this.add(snapshot.entries)
+    const entry = (collection: string, id: Id): EntryRead => this.entries.get(`${collection}:${id}`) ?? { id, collection, status: 'missing' }
+    const ctx = (at: string): ExpandCtx => ({
+      at, draft: true,
+      media: id => this.media.get(String(id)), page: id => this.pages.get(String(id)), single: key => this.singles.get(key),
+      entry,
+      query: (collection, query) => {
+        const source = this.queries.get(at)
+        // Old reads lack rule metadata. Preserve their known matches; never guess membership.
+        const matches = source?.$query?.matches ?? (source?.entries ?? []).map(item => item.id)
+        const picked = applyQueryPicks(matches, query as QueryStored, id => entry(collection, id).status === 'ready')
+        return { entries: picked.ids.map(id => entry(collection, id)), total: picked.total, ...(source?.$query ? { matches } : {}) }
+      },
+      inverse: () => {
+        const value = this.reads.get(at)
+        return (Array.isArray(value) ? value : value ? [value] : []).filter(item => object(item) && typeof item.collection === 'string' && item.id !== undefined) as EntryRead[]
+      },
+    })
+    const schema: Schema = { blocks: snapshot.blocks ?? {}, collections: {}, singles: {} }
+    const expand = (field: FieldDecl, value: unknown, at: string): unknown => {
+      if (isLeaf(field)) {
+        if (field.element === 'u90/query') {
+          const previous = this.queries.get(at)
+          const baseline = previous?.$query
+          const q = object(value) ? value : {}
+          if (baseline && (JSON.stringify(baseline.where) !== JSON.stringify(q.where ?? []) || JSON.stringify(baseline.sort) !== JSON.stringify(q.sort ?? null) || baseline.limit !== (q.limit ?? null))) return previous
+        }
+        return expandField(schema, field, value, ctx(at))
+      }
+      const children = getContainer(field.container).children(field, field.container === 'u90/group' && !object(value) ? {} : value, schema)
+      if (field.container === 'u90/group') return Object.fromEntries(children.map(child => [child.key, expand(child.decl, child.value, `${at}/${child.key}`)]))
+      return children.map((child, index) => {
+        const path = `${at}/${child.key}`
+        const inner = expand(child.decl, child.value, path)
+        if (field.container === 'u90/list') return isLeaf(field.item) ? inner : { _id: child.key, $path: path, ...inner as object }
+        const item = Array.isArray(value) && object(value[index]) ? value[index] : {}
+        const metadata = { _id: child.key, _block: item._block, ...(typeof item._hidden === 'boolean' ? { _hidden: item._hidden } : {}) }
+        return Object.hasOwn(schema.blocks, String(item._block)) ? { ...metadata, $path: path, ...inner as object } : metadata
+      })
+    }
+    return expand(snapshot.field, snapshot.value, snapshot.path)
+  }
+}