@unitninety/site-kit 1.6.6 → 1.8.0

package/README.md

@@ -5,13 +5,42 @@ 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.6 --version
+npx --yes @unitninety/u90@1.2.0 --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).
 
+### Keep cleared fields editable
+
+Site Kit 1.7.0 preserves real draft addresses on groups and block props. Nullable images still read as `null`; pass their owner address separately so Canvas can select them after a clear or reload:
+
+```tsx
+import { Image, Text, draftFieldPath } from '@unitninety/site-kit/components'
+
+export function Hero(props) {
+  return <section>
+    <Text as="h1" value={props.title} />
+    <div style={{ position: 'relative', aspectRatio: '4 / 3' }}>
+      <Image value={props.image} draftPath={draftFieldPath(props, 'image')} fill />
+    </div>
+  </section>
+}
+```
+
+For a nested group or list row, pass that group or row to `draftFieldPath`. For a collection image, pass `entry.fields`. Keep the complete native object, including reserved `$` metadata, when handing it to another component. Iterate declared fields rather than every group property. A null leaf has no identity of its own: prefer `list(group({ image: image() }))` for editable image lists so each row retains its stable address, including when its image is empty.
+
+For an existing `list(image())`, use `draftListItemPath(props, 'photos', index)` as the image's `draftPath`. This reads the original stable item ID from the owner's draft metadata, including after clearing and reloading; the index only identifies the current rendered item, not its saved address. Keep the owner metadata with the list. A detached array of null values alone cannot identify its fields. Shared Single aliases likewise retain their canonical addresses separately from null image values.
+
+The standard image renderer keeps a bounded missing-image target only when it has a real draft address. Published empty images render nothing. Custom image components must preserve the same target, respect literal clearing, and never reintroduce a seed image as fallback for an explicitly empty field. The bridge also allows blank declared text, rich-text and link-label fields to resume direct editing. Formatted dates and derived values can remain inspector-only.
+
+Use the real root `U90Bridge`; inline editing is enabled by default. Deliberate inspector-only integrations may set `inlineEditing={false}` and verify with `u90 check --canvas-mode inspector`. Ordinary checks require inline mode. The bridge exposes only its effective mode booleans in a draft-only diagnostic marker; no session or credentials are included.
+
+The local checker verifies the actual root mode, exact field bindings, and observed image replacement → literal clear → restore against isolated content. New packages must record these checks. This does not prove client hydration or CSS hit targets: in a browser, click and type into real headings, clear and replace images, and repeat on mobile and inactive tabs/carousels. Decorative overlays must not intercept editable images; enable pointer events only on their actual interactive content. Preserve test content and report untested states explicitly.
+
+For a custom integration's browser diagnostics, `inspectCanvas(document)` from `@unitninety/site-kit/bridge` reads the existing frame without starting another bridge or editing content. It reports the root mode, mounted bridge stylesheet, sampled click targets and blockers. Hidden, offscreen and zero-size fields are reported separately; a reachable sample does not prove typing, saving, or another viewport. Run it inside the site frame, not the outer dashboard.
+
 ### 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.
@@ -55,9 +84,43 @@ Call the hook on native reads before converting them for a presentation componen
 
 Canvas prepares locally resolvable list defaults with a stable random item ID, previews the same list in both inspector and site, then saves through the normal validated queue. Nested lists, empty lists and duplicate responsive renderings work without DOM cloning. Later edits survive older refresh responses; rejected or ambiguous structural saves reconcile with an authoritative read. Draft IDs cannot collide with an existing item. Media/reference defaults requiring resolution still use the server path, and references continue using their existing entry previews. This opt-in requires the updated Site Kit; older bridges retain their ordinary DOM previews and refresh behavior.
 
+### Immediate ordinary-list reordering
+
+Use `List` for repeated content such as service lines, navigation links and FAQ rows. It
+keeps existing rows and their media mounted while their order changes, before saving finishes:
+
+```tsx
+import { List, Text, draftFieldPath } from '@unitninety/site-kit/components'
+
+export function Services(props) {
+  return <List as="ul" value={props.lines} draftPath={draftFieldPath(props, 'lines')}>
+    {line => <li><Text value={line.name} as="h3" /></li>}
+  </List>
+}
+```
+
+The callback runs in the component that renders `List`; only rendered slots cross the client
+boundary. Server-only imports and async card children can stay on the server. `List` replaces the existing container: set `as` to its original tag and keep its attributes.
+It adds no extra DOM wrapper, so list, table and grid markup retain their structure. Published
+lists remain ordinary server markup. Group rows retain their native `_id` and `$path`; nullable
+leaf lists can pass `itemPaths={props.$listPaths?.photos}` when their paths live on the owner.
+Never use a row's label or array index as its draft identity.
+
+`List` immediately reorders existing items. New items and content replacements still arrive
+from the authoritative server render. For immediate additions and full field previews, use a
+client component with `useDraftPreview(props)` before reading its fields. Use `Entries` for
+collection placements. A plain server-side `.map()` has no live list owner and waits for the
+save/refresh even with the latest Site Kit installed. If row content depends on the current
+array index (such as a numbered label), use `useDraftPreview` so it recomputes immediately.
+
+Verify with the response held back: move a row, confirm the visible order immediately, move
+another row during the pending save, then release the response and confirm the saved order.
+Retain image nodes and dimensions throughout. Failed saves must restore the saved order.
+Server HTML checks alone cannot establish hydration or immediate browser updates.
+
 ### Stable block reorder previews
 
-Site Kit 1.6.6 keeps existing block content mounted while Canvas changes its order, including hidden destinations and repeated responsive views. The default `useDraftPreview(source)` preserves native field objects and pending edits instead of expanding a whole zone snapshot again.
+Site Kit keeps existing block content mounted while Canvas changes its order, including hidden destinations and repeated responsive views. Since 1.8.0, the same order-only path covers ordinary and nested lists, preserving resolved images and presentation values. The default `useDraftPreview(source)` preserves native field objects and pending edits instead of expanding a whole structural snapshot again.
 
 Custom presentation adapters retain their existing snapshot behavior. If every rendered block collection keeps its native `$path` values, opt into the shared order adapter:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unitninety/site-kit",
-  "version": "1.6.6",
+  "version": "1.8.0",
   "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/DraftList.tsx

@@ -0,0 +1,46 @@
+'use client'
+
+import { createElement, Fragment, useCallback, useLayoutEffect, useMemo, useRef, type JSX, type ReactNode } from 'react'
+import { useDraftPreview } from './useDraftContent'
+import { applyNativeOrder, type DraftOrder } from './nativeOrder'
+import { PreviewCommitBoundary } from './PreviewCommitBoundary'
+import { needsEmbedReload, preserveBlockMoves } from './preserveBlockMoves'
+import { registry } from './registry'
+
+type Item = { id: string; $path: string; content: ReactNode }
+type Slots = { $path: string; $fieldPaths: { items: string }; items: Item[] }
+export type ListTag = keyof HTMLElementTagNameMap & keyof JSX.IntrinsicElements
+// Server-rendered slots have no client renderer for new values. Only a pure order
+// changes locally; membership and content continue to arrive from the saved render.
+const keepSlots = <T,>(source: T): T => source
+
+export function DraftList({ as, attributes, path, items }: { as: ListTag; attributes: Record<string, unknown>; path: string; items: Item[] }) {
+  const host = useRef<HTMLElement | null>(null)
+  const reload = useRef(false)
+  const attach = useCallback((element: HTMLElement | null) => {
+    host.current = element
+    const cleanup = preserveBlockMoves(element)
+    return () => { cleanup?.(); if (host.current === element) host.current = null }
+  }, [])
+  const reorder = useCallback((source: Slots, order: DraftOrder): Slots => {
+    const result = applyNativeOrder(source, order)
+    if (!result.matched) return source
+    if (result.value !== source && host.current && needsEmbedReload(host.current)) {
+      reload.current = true
+      // Acknowledge this order without moving a live iframe. The bridge reloads
+      // the saved page instead of allowing its legacy DOM fallback to move it.
+      return { ...source }
+    }
+    // Custom adapters signal ownership by returning a new value, even if the
+    // requested order is already visible (for example a duplicate snapshot).
+    return result.value === source ? { ...source } : result.value
+  }, [])
+  const source = useMemo(() => ({ $path: path, $fieldPaths: { items: path }, items }), [path, items])
+  const live = useDraftPreview(source, keepSlots, reorder)
+  useLayoutEffect(() => {
+    const owner = { document: host.current?.ownerDocument ?? document, beforeRefresh() {}, needsReload: () => reload.current, move: () => false }
+    registry.blockOrders.add(owner)
+    return () => { registry.blockOrders.delete(owner) }
+  }, [])
+  return <PreviewCommitBoundary source={items}>{createElement(as, { ...attributes, ref: attach }, live.items.map(item => <Fragment key={item.id}>{item.content}</Fragment>))}</PreviewCommitBoundary>
+}

package/src/bridge/U90Bridge.tsx

@@ -22,8 +22,10 @@ import { EditingProvider } from './hooks'
 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} inlineEditing={inlineEditing}>{children}</EditingProvider>
+  const state = await draft()
+  const props = await resolveBridgePreview({ platformOrigin, draft: async () => state, resolve: testPreview ? () => testPreview() : token => runtime.resolve(token) })
+  const diagnostic = state.enabled || props.testPreview ? { version: 1, editing: props.editing, inlineEditing: inlineEditing !== false, testPreview: props.testPreview } : null
+  return <>{diagnostic ? <span hidden data-u90-bridge={JSON.stringify(diagnostic)} /> : null}<EditingProvider {...props} inlineEditing={inlineEditing}>{children}</EditingProvider></>
 }
 
 /**

package/src/bridge/caret.ts

@@ -89,12 +89,13 @@ export const MEDIA_SELECTOR = `[${FIELD_ATTR}]:is(${MEDIA})`
  */
 export const isEditableLeaf = (element: HTMLElement): boolean => {
   if (element.matches(MEDIA)) return false
-  if (element.getAttribute('data-u90-edit') === 'rich') return Boolean(element.textContent?.trim())
+  const kind = element.getAttribute('data-u90-edit')
+  if (kind === 'rich') return true
 
   return (
     !element.querySelector(`[${FIELD_ATTR}]`) &&
     !element.querySelector(NON_TEXT) &&
-    Boolean(element.textContent?.trim())
+    (Boolean(element.textContent?.trim()) || kind === 'text' || kind === 'link-label')
   )
 }
 
@@ -110,10 +111,8 @@ export const isEditableLeaf = (element: HTMLElement): boolean => {
  * `:not(:is(${MEDIA}))` still runs unconditionally, outside that `:is()` — a marked image is
  * a picture, rich or not, and the caret has no business there either.
  *
- * The one clause CSS still cannot express is "and it has some text in it" — an empty marked
- * element therefore offers an I-beam and does nothing when clicked, which is the least
- * interesting way for the two to fall out of step and beats making every site component
- * carry a class.
+ * Explicit native edit kinds remain editable when blank. The bridge marks those empty
+ * surfaces so draft CSS can give them a clickable box without adding saved placeholder text.
  *
  * v4 change: `[${RICH_ATTR}]` (legacy's presence selector for the standalone rich attribute)
  * becomes the value selector `[data-u90-edit="rich"]`.
@@ -235,8 +234,8 @@ const endOf = (element: HTMLElement): Range => {
   const last = lastWordsIn(element)
 
   if (!last) {
-    // No text at all. `isEditableLeaf` rules this out for the click path; a direct caller
-    // gets the old behaviour, which is the only thing available.
+    // An empty native field has no text node yet. Place the caret in its element;
+    // the browser creates the first text node when the person types.
     range.selectNodeContents(element)
     range.collapse(false)
     return range

package/src/bridge/createBridge.ts

@@ -99,6 +99,15 @@ export function createBridge(win: Window, opts: BridgeOptions) {
 
   let pending: { path: string; kind: 'text' | 'rich' | 'link-label'; el: HTMLElement } | null = null
   let timer: ReturnType<typeof setTimeout> | null = null
+  let emptyFields: MutationObserver | null = null
+  const markEmptyField = (el: HTMLElement) => {
+    const kind = el.getAttribute('data-u90-edit')
+    const empty = (kind === 'text' || kind === 'rich' || kind === 'link-label') && !el.textContent?.trim() && isEditableLeaf(el)
+    el.toggleAttribute('data-u90-empty', empty)
+  }
+  const markEmptyFields = () => {
+    for (const el of doc.querySelectorAll<HTMLElement>('[data-u90-field][data-u90-edit], [data-u90-empty]')) markEmptyField(el)
+  }
   const valueOf = (el: HTMLElement, kind: 'text' | 'rich' | 'link-label') => (kind === 'rich' ? toRichText(asDomLike(el)) : textWithTokens(el))
   const flush = () => {
     if (timer) clearTimeout(timer)
@@ -404,6 +413,7 @@ export function createBridge(win: Window, opts: BridgeOptions) {
     if (opts.inlineEditing === false) return
     const el = (e.target as Element | null)?.closest<HTMLElement>('[data-u90-edit]')
     if (el) {
+      markEmptyField(el)
       schedule(el)
       // The Canvas owns save debouncing. Its inspector needs each input immediately, including
       // during continuous typing and just before focus crosses into the parent document.
@@ -963,6 +973,12 @@ export function createBridge(win: Window, opts: BridgeOptions) {
 
       doc.head.appendChild(style)
       if (opts.inlineEditing === false) doc.documentElement.setAttribute('data-u90-inspector-only', '')
+      markEmptyFields()
+      const Observer = (win as Window & typeof globalThis).MutationObserver
+      if (Observer) {
+        emptyFields = new Observer(markEmptyFields)
+        emptyFields.observe(doc.body, { subtree: true, childList: true, characterData: true, attributes: true, attributeFilter: ['data-u90-field', 'data-u90-edit'] })
+      }
       selection.start()
       applyDraftLanguage()
       doc.addEventListener('click', onClick, true)
@@ -997,6 +1013,9 @@ export function createBridge(win: Window, opts: BridgeOptions) {
       stopped = true
       endEditing() // what was typed goes out, and no element is left contenteditable
       flush()
+      emptyFields?.disconnect()
+      emptyFields = null
+      doc.querySelectorAll('[data-u90-empty]').forEach(el => el.removeAttribute('data-u90-empty'))
       releaseViewport()
       style.remove()
       if (opts.inlineEditing === false) doc.documentElement.removeAttribute('data-u90-inspector-only')

package/src/bridge/diagnostics.ts

@@ -0,0 +1,61 @@
+type Runtime = { version: 1; editing: boolean; inlineEditing: boolean; testPreview: boolean }
+export type CanvasFieldDiagnostic = {
+  path: string
+  status: 'reachable' | 'occluded' | 'hidden' | 'no-box' | 'offscreen' | 'untested'
+  samples: number
+  hits: number
+  blockers: string[]
+}
+export type CanvasDiagnostic = {
+  runtime: Runtime | null
+  bridgeMounted: boolean
+  viewport: { width: number; height: number }
+  fields: CanvasFieldDiagnostic[]
+}
+
+/** Read-only snapshot of the existing frame. It neither starts a bridge nor changes selection.
+ * Reachability samples only the current viewport/state, not typing, saving or hidden slides. */
+export function inspectCanvas(doc: Document = document): CanvasDiagnostic {
+  const win = doc.defaultView
+  const viewport = { width: win?.innerWidth ?? 0, height: win?.innerHeight ?? 0 }
+  let runtime: Runtime | null = null
+  const markers = doc.querySelectorAll('[data-u90-bridge]')
+  if (markers.length === 1) try {
+    const value = JSON.parse(markers[0].getAttribute('data-u90-bridge') ?? '')
+    if (value.version === 1 && ['editing', 'inlineEditing', 'testPreview'].every(key => typeof value[key] === 'boolean'))
+      runtime = { version: 1, editing: value.editing, inlineEditing: value.inlineEditing, testPreview: value.testPreview }
+  } catch { /* An absent or invalid root is not a verified runtime. */ }
+  const fields = Array.from(doc.querySelectorAll<HTMLElement>('[data-u90-field]'), el => {
+    const path = el.getAttribute('data-u90-field') ?? ''
+    const result: CanvasFieldDiagnostic = { path, status: 'untested', samples: 0, hits: 0, blockers: [] }
+    // Visibility is inherited but can be overridden by a visible descendant.
+    const visibility = win?.getComputedStyle(el).visibility
+    if (visibility === 'hidden' || visibility === 'collapse') return { ...result, status: 'hidden' as const }
+    for (let node: HTMLElement | null = el; node; node = node.parentElement) {
+      const style = win?.getComputedStyle(node)
+      if (node.hidden || style?.display === 'none' || style?.opacity === '0') return { ...result, status: 'hidden' as const }
+    }
+    let rects = Array.from(el.getClientRects()).filter(rect => rect.width > 0 && rect.height > 0)
+    if (!rects.length && win?.getComputedStyle(el).display === 'contents') {
+      rects = Array.from(el.querySelectorAll('*')).filter(child => child.closest('[data-u90-field]') === el)
+        .flatMap(child => Array.from(child.getClientRects())).filter(rect => rect.width > 0 && rect.height > 0)
+    }
+    if (!rects.length) return { ...result, status: 'no-box' as const }
+    const visible = rects.map(rect => ({ left: Math.max(0, rect.left), right: Math.min(viewport.width, rect.right), top: Math.max(0, rect.top), bottom: Math.min(viewport.height, rect.bottom) })).filter(rect => rect.right > rect.left && rect.bottom > rect.top)
+    if (!visible.length) return { ...result, status: 'offscreen' as const }
+    if (typeof doc.elementFromPoint !== 'function') return result
+    const blockers = new Set<string>()
+    for (const rect of visible.slice(0, 3)) for (const x of [.2, .5, .8]) for (const y of [.2, .5, .8]) {
+      result.samples++
+      const hit = doc.elementFromPoint(rect.left + (rect.right - rect.left) * x, rect.top + (rect.bottom - rect.top) * y)
+      const selected = hit?.closest('[data-u90-field], [data-u90-block]')
+      if (selected?.getAttribute('data-u90-field') === path) result.hits++
+      else if (hit) blockers.add(`${hit.tagName.toLowerCase()}${Array.from(hit.classList).slice(0, 3).map(name => `.${name}`).join('')}`)
+      else blockers.add('(no element)')
+    }
+    result.blockers = [...blockers].slice(0, 8)
+    result.status = result.hits ? 'reachable' : 'occluded'
+    return result
+  })
+  return { runtime, bridgeMounted: !!doc.querySelector('head style[data-u90-editing]'), viewport, fields }
+}

package/src/bridge/index.ts

@@ -14,3 +14,5 @@ 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'
 export { reorderNativeDraft, type NativeDraftOrder } from './nativeOrder'
+/** Read-only diagnostics for the current frame; hidden/offscreen states remain untested. */
+export { inspectCanvas, type CanvasDiagnostic, type CanvasFieldDiagnostic } from './diagnostics'

package/src/bridge/nativeDraft.ts

@@ -1,52 +1,38 @@
 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 { draftGroupMetadata, rememberDraftList } from '../elements/ops/draftPaths'
 import { applyQueryPicks, type QueryStored } from '../elements/leaves/query'
 import type { EntriesRead } from '../elements/leaves/selection'
 import type { DraftSnapshot } from './protocol'
 import { reorderNativeDraft, type DraftOrder } from './nativeOrder'
+import { nativeChildPath, nativeListItemPath, nativeListPaths, nativePath, safeDraftPath } from './nativePath'
+export { nativePath, safeDraftPath } from './nativePath'
 
 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 {
+export function applyNativeDraft<T>(source: T, path: string, replacement: unknown, rootPath?: string): T {
   if (!safeDraftPath(path)) return source
-  const visit = (value: unknown, parent?: string, seen = new Set<object>()): unknown => {
+  const visit = (value: unknown, parent?: string, seen = new Set<object>(), inheritedListPaths?: readonly string[]): 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)
+    const paths = Array.isArray(value) ? nativeListPaths(value) ?? inheritedListPaths : undefined
     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)
+      const childPath = Array.isArray(value) ? nativeListItemPath(value, Number(key), paths, at) : nativeChildPath(value, key, at)
+      const next = visit(child, childPath, nextSeen, Array.isArray(child) ? nativeListPaths(child, value, key) : undefined)
       if (next !== child) {
-        if (result === value) result = Array.isArray(value) ? [...value] : { ...value }
+        if (result === value) result = Array.isArray(value) ? rememberDraftList([...value], paths) : { ...value }
         result[key] = next
       }
     }
     return result
   }
-  return visit(source) as T
+  return visit(source, nativePath(source) ?? (rootPath && safeDraftPath(rootPath) ? rootPath : undefined)) as T
 }
 
 /** A local index of real native reads. Missing references remain missing until the server answers. */
@@ -61,11 +47,14 @@ export class NativeDraftReferences {
 
   add(values: unknown): void {
     const seen = new Set<object>()
-    const visit = (value: unknown, parent?: string) => {
+    const visit = (value: unknown, parent?: string, inheritedListPaths?: readonly string[]) => {
       if (parent) this.reads.set(parent, value)
+      if (parent?.startsWith('single:') && !parent.includes('/')) this.singles.set(parent.slice(7), value)
       if (!value || typeof value !== 'object' || seen.has(value)) return
       seen.add(value)
       const at = nativePath(value) ?? parent
+      const paths = Array.isArray(value) ? nativeListPaths(value) ?? inheritedListPaths : undefined
+      if (Array.isArray(value)) rememberDraftList(value, paths)
       if (at) this.reads.set(at, value)
       if (object(value)) {
         if (at?.startsWith('single:') && !at.includes('/')) this.singles.set(at.slice(7), value)
@@ -97,8 +86,8 @@ export class NativeDraftReferences {
       }
       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)
+        const childPath = Array.isArray(value) ? nativeListItemPath(value, Number(key), paths, at) : nativeChildPath(value, key, at)
+        visit(child, childPath, Array.isArray(child) ? nativeListPaths(child, value, key) : undefined)
       }
     }
     visit(values)
@@ -142,9 +131,9 @@ export class NativeDraftReferences {
   }
 
   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, read] of this.reads) this.reads.set(key, key === path ? value : applyNativeDraft(read, path, value, key))
+    for (const [key, entry] of this.entries) this.entries.set(key, applyNativeDraft(entry, path, value, `entry:${entry.id}`))
+    for (const [key, single] of this.singles) this.singles.set(key, applyNativeDraft(single, path, value, `single:${key}`))
     for (const [key, query] of this.queries) this.queries.set(key, applyNativeDraft(query, path, value))
   }
 
@@ -180,8 +169,11 @@ export class NativeDraftReferences {
         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) => {
+      if (field.container === 'u90/group') {
+        const fields = Object.fromEntries(children.map(child => [child.key, expand(child.decl, child.value, `${at}/${child.key}`)]))
+        return { ...draftGroupMetadata(field.fields, at, fields), ...fields }
+      }
+      const expanded = 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 }
@@ -189,6 +181,7 @@ export class NativeDraftReferences {
         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 field.container === 'u90/list' ? rememberDraftList(expanded, children.map(child => `${at}/${child.key}`)) : expanded
     }
     return expand(snapshot.field, snapshot.value, snapshot.path)
   }

package/src/bridge/nativeOrder.ts

@@ -1,22 +1,36 @@
-import { nativePath, safeDraftPath } from './nativeDraft'
+import { rememberDraftList } from '../elements/ops/draftPaths'
+import { nativeChildPath, nativeListItemPath, nativeListPaths, nativePath, safeDraftPath } from './nativePath'
 import type { DraftSnapshot } from './protocol'
+import type { FieldDecl } from '../elements/define'
 
 export type DraftOrder = { path: string; ids: string[] }
 export type NativeDraftOrder = DraftOrder
 const unsafe = new Set(['__proto__', 'constructor', 'prototype'])
 
-/** A move's snapshot may start above its zone (for example a zone inside a group).
- * Read only the target's IDs; reconstructing its fields would discard site adapters. */
+/** A move's snapshot may start above its list/zone. Read only stable IDs:
+ * expanding a reorder would replace already-resolved media and presentation values. */
 export function snapshotOrder(snapshot: DraftSnapshot, movedPath: string): DraftOrder | undefined {
   const path = movedPath.slice(0, movedPath.lastIndexOf('/'))
   if (!safeDraftPath(path) || (path !== snapshot.path && !path.startsWith(`${snapshot.path}/`))) return
   let value: unknown = snapshot.value
+  let field: FieldDecl | undefined = snapshot.field
   for (const key of path.slice(snapshot.path.length).split('/').filter(Boolean)) {
     if (unsafe.has(key)) return
-    value = Array.isArray(value) ? value.find(item => item?._id === key)
-      : value && typeof value === 'object' && Object.hasOwn(value, key) ? (value as Record<string, unknown>)[key] : undefined
+    if (Array.isArray(value)) {
+      value = value.find(item => item?._id === key)
+      if (field && 'container' in field && field.container === 'u90/list') {
+        field = field.item
+      } else if (field && 'container' in field && field.container === 'u90/zone') {
+        const block = value && typeof value === 'object' && '_block' in value ? snapshot.blocks?.[String(value._block)] : undefined
+        field = block ? { container: 'u90/group', fields: block.fields } : undefined
+      } else field = undefined
+    } else {
+      value = value && typeof value === 'object' && Object.hasOwn(value, key) ? (value as Record<string, unknown>)[key] : undefined
+      field = field && 'container' in field && field.container === 'u90/group' && Object.hasOwn(field.fields, key) ? field.fields[key] : undefined
+    }
   }
-  if (!Array.isArray(value) || !value.every(item => item && typeof item._id === 'string' && typeof item._block === 'string')) return
+  const list = field && 'container' in field && field.container === 'u90/list'
+  if (!Array.isArray(value) || !value.every(item => item && typeof item._id === 'string' && (list || typeof item._block === 'string'))) return
   const ids = value.map(item => item._id as string)
   if (new Set(ids).size !== ids.length || !ids.includes(movedPath.slice(path.length + 1))) return
   return { path, ids }
@@ -35,25 +49,28 @@ export function ordered<T>(items: T[], ids: string[], id: (item: T) => string |
 export function applyNativeOrder<T>(source: T, order: DraftOrder): { value: T; matched: boolean } {
   if (!safeDraftPath(order.path)) return { value: source, matched: false }
   let matched = false
-  const visit = (value: unknown, parent?: string, seen = new Set<object>()): unknown => {
+  const visit = (value: unknown, parent?: string, seen = new Set<object>(), inheritedListPaths?: readonly string[]): unknown => {
     if (!value || typeof value !== 'object' || seen.has(value) || '$$typeof' in value) return value
     const at = nativePath(value) ?? parent
+    const paths = Array.isArray(value) ? nativeListPaths(value) ?? inheritedListPaths : undefined
     if (Array.isArray(value) && at === order.path) {
       matched = true
-      return ordered(value, order.ids, item => {
-        const path = nativePath(item)
+      const indexed = value.map((item, index) => ({ item, index }))
+      const sorted = ordered(indexed, order.ids, ({ item, index }) => {
+        const path = paths?.[index] ?? nativePath(item)
         return path?.startsWith(`${order.path}/`) ? path.slice(order.path.length + 1)
           : typeof item?._id === 'string' ? item._id : undefined
       })
+      return sorted === indexed ? value : rememberDraftList(sorted.map(({ item }) => item), paths ? sorted.map(({ index }) => paths[index]!) : undefined)
     }
     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) ? child?._id : key
-      const next = visit(child, at && typeof id === 'string' ? `${at}/${id}` : undefined, nextSeen)
+      const childPath = Array.isArray(value) ? nativeListItemPath(value, Number(key), paths, at) : nativeChildPath(value, key, at)
+      const next = visit(child, childPath, nextSeen, Array.isArray(child) ? nativeListPaths(child, value, key) : undefined)
       if (next !== child) {
-        if (result === value) result = Array.isArray(value) ? [...value] : { ...value }
+        if (result === value) result = Array.isArray(value) ? rememberDraftList([...value], paths) : { ...value }
         result[key] = next
       }
     }

package/src/bridge/nativePath.ts

@@ -0,0 +1,45 @@
+import { draftListPaths } from '../elements/ops/draftPaths'
+
+const unsafe = new Set(['__proto__', 'constructor', 'prototype'])
+export const safeDraftPath = (path: string) => /^(page|entry|layout|single):[^/]+(?:\/[^/]+)*$/.test(path) && !path.split('/').some(key => unsafe.has(key))
+
+/** Older native groups carry only child paths. Infer their parent only when those paths agree. */
+export function nativePath(value: unknown, seen = new Set<object>()): string | undefined {
+  if (!value || typeof value !== 'object' || seen.has(value)) return
+  seen.add(value)
+  const own = (value as { $path?: unknown }).$path
+  if (typeof own === 'string') return safeDraftPath(own) ? own : 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
+}
+
+/** A declared Single remains canonical even while its scalar read is null. */
+export function nativeChildPath(value: object, key: string, at = nativePath(value)): string | undefined {
+  const aliases = (value as { $fieldPaths?: unknown }).$fieldPaths
+  const alias = aliases && typeof aliases === 'object' && Object.hasOwn(aliases, key) ? (aliases as Record<string, unknown>)[key] : undefined
+  return typeof alias === 'string' && safeDraftPath(alias) ? alias : at ? `${at}/${key}` : undefined
+}
+/** Snapshot metadata supersedes older owner metadata after a list replacement. */
+export function nativeListPaths(value: unknown[], owner?: object, key?: string): readonly string[] | undefined {
+  const own = draftListPaths(value)
+  const lists = (owner as { $listPaths?: unknown } | undefined)?.$listPaths
+  const stored = lists && typeof lists === 'object' && key !== undefined && Object.hasOwn(lists, key) ? (lists as Record<string, unknown>)[key] : undefined
+  const paths = own ?? stored
+  return Array.isArray(paths) && paths.length === value.length && paths.every(path => typeof path === 'string' && safeDraftPath(path)) ? paths : undefined
+}
+
+export function nativeListItemPath(value: unknown[], index: number, paths = nativeListPaths(value), at = nativePath(value)): string | undefined {
+  const child = value[index]
+  const own = nativePath(child)
+  if (own) return own
+  if (paths?.[index]) return paths[index]
+  const id = child && typeof child === 'object' ? (child as { _id?: unknown })._id : undefined
+  return typeof id === 'string' && at && safeDraftPath(`${at}/${id}`) ? `${at}/${id}` : undefined
+}

package/src/bridge/preserveBlockMoves.ts

@@ -53,7 +53,7 @@ function restoreSheets(snapshots: SheetSnapshot[]) {
  * prototype changes. Atomic moves keep iframes/focus alive where supported. Both
  * kinds of move need the CSSOM safeguard for styles in an embedded shadow root.
  */
-export function preserveBlockMoves(host: HTMLDivElement | null): void | (() => void) {
+export function preserveBlockMoves(host: HTMLElement | null): void | (() => void) {
   if (!host) return
   const atomic = host as AtomicHost
   const insert = host.insertBefore

package/src/bridge/styles.ts

@@ -46,6 +46,18 @@ export const EDITING_CSS = `
   outline-offset: 4px;
 }
 
+/* An empty native value stays empty; this draft-only box is never saved as copy. */
+[data-u90-field][data-u90-empty] {
+  min-width: 1.5em;
+  min-height: 1em;
+}
+[data-u90-field][data-u90-empty]::before {
+  display: inline-block;
+  min-width: 1.5em;
+  min-height: 1em;
+  content: '\\00a0';
+}
+
 /* a Single inside editable copy: one chip the caret skips, saved back as its {key} (R38) */
 [data-u90-field] [data-single-key] {
   border-radius: 4px;

package/src/bridge/useDraftContent.tsx

@@ -2,6 +2,7 @@
 
 import { createContext, useContext, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import { applyNativeDraft, NativeDraftReferences, safeDraftPath } from './nativeDraft'
+import { nativePath } from './nativePath'
 import type { DraftSnapshot } from './protocol'
 import { registry } from './registry'
 import { applyNativeOrder, reorderNativeDraft, type DraftOrder } from './nativeOrder'
@@ -83,6 +84,14 @@ const sameSource = (a: unknown, b: unknown): boolean => {
 
 export type NativeDraftPatch = { path: string; value: unknown }
 type PreviewPatch = { kind: 'value'; path: string; value: unknown } | { kind: 'order'; path: string; ids: string[] }
+const supersede = (patches: Map<string, PreviewPatch>, patch: PreviewPatch) => {
+  if (patch.kind === 'value') for (const [key, previous] of patches) if (previous.path === patch.path || previous.path.startsWith(`${patch.path}/`)) patches.delete(key)
+  patches.delete(`${patch.kind}:${patch.path}`)
+}
+const remember = (patches: Map<string, PreviewPatch>, patch: PreviewPatch) => {
+  supersede(patches, patch)
+  patches.set(`${patch.kind}:${patch.path}`, patch)
+}
 const applyPreviewPatch = <T,>(source: T, patch: PreviewPatch, apply: (source: T, patch: NativeDraftPatch) => T, reorder: (source: T, order: DraftOrder) => T = reorderNativeDraft): T =>
   patch.kind === 'order' ? reorder(source, patch) : apply(source, patch)
 const applyPatch = <T,>(source: T, patch: NativeDraftPatch): T => applyNativeDraft(source, patch.path, patch.value)
@@ -100,17 +109,20 @@ const hasNativePath = (value: unknown, seen = new Set<object>()): boolean => {
 export function useDraftPreview<T>(source: T, apply: (source: T, patch: NativeDraftPatch) => T = applyPatch, reorder = apply === applyPatch ? reorderNativeDraft<T> : undefined): T {
   const owner = useContext(DraftContentPath)
   const references = useContext(ReferenceValues)
+  const native = apply === applyPatch
+  const rootPath = nativePath(source) ?? owner
+  const applyValue = useMemo(() => native ? (value: T, patch: NativeDraftPatch) => applyNativeDraft(value, patch.path, patch.value, rootPath) : apply, [native, rootPath, apply])
   const [cache] = useState(() => new NativeDraftReferences())
   const enabled = !!owner || hasNativePath(source)
-  const [shown, setShown] = useState({ source, value: source, owner, overrides: new Map<string, PreviewPatch>() })
+  const [shown, setShown] = useState({ source, value: source, owner, overrides: new Map<string, PreviewPatch>(), settling: new Map<string, PreviewPatch>() })
   let current = shown.value
   if (!sameSource(shown.source, source) || shown.owner !== owner) {
     const overrides = shown.owner === owner ? shown.overrides : new Map<string, PreviewPatch>()
     current = source
-    for (const patch of overrides.values()) current = applyPreviewPatch(current, patch, apply, reorder)
-    setShown({ source, value: current, owner, overrides })
+    for (const patch of overrides.values()) current = applyPreviewPatch(current, patch, applyValue, reorder)
+    setShown({ source, value: current, owner, overrides, settling: new Map() })
   }
-  const latest = useRef({ current, source, references, apply, reorder })
+  const latest = useRef({ current, source, references, apply: applyValue, reorder, native, overrides: shown.overrides, settling: shown.settling })
   useLayoutEffect(() => {
     cache.add(references)
     cache.add(source)
@@ -118,22 +130,29 @@ export function useDraftPreview<T>(source: T, apply: (source: T, patch: NativeDr
       if (patch.kind === 'value') cache.patch(patch.path, patch.value)
       else cache.order(patch)
     }
-    latest.current = { current, source, references, apply, reorder }
-  }, [cache, current, source, references, apply, reorder, shown.overrides])
+    latest.current = { current, source, references, apply: applyValue, reorder, native, overrides: shown.overrides, settling: shown.settling }
+  }, [cache, current, source, references, applyValue, reorder, native, shown.overrides, shown.settling])
   useLayoutEffect(() => {
     if (!enabled) return
     const handler = {
       document,
       beforeRefresh: () => {
         cache.beforeRefresh()
-        setShown(value => ({ ...value, overrides: new Map() }))
+        // Keep the optimistic baseline visible while this request is pending. It is
+        // discarded on a new source/commit, never replayed over the server's answer.
+        const settling = new Map(latest.current.settling)
+        for (const patch of latest.current.overrides.values()) remember(settling, patch)
+        latest.current.overrides = new Map()
+        latest.current.settling = settling
+        setShown(value => ({ ...value, overrides: new Map(), settling }))
       },
       afterRefresh: () => setShown(previous => {
         cache.settle([latest.current.references, latest.current.source])
         let value = latest.current.source
         for (const patch of previous.overrides.values()) value = applyPreviewPatch(value, patch, latest.current.apply, latest.current.reorder)
         latest.current.current = value
-        return { ...previous, source: latest.current.source, value }
+        latest.current.settling = new Map()
+        return { ...previous, source: latest.current.source, value, settling: new Map() }
       }),
       preview: (snapshot: DraftSnapshot, order?: DraftOrder) => {
         if (!safeDraftPath(snapshot.path)) return false
@@ -141,19 +160,26 @@ export function useDraftPreview<T>(source: T, apply: (source: T, patch: NativeDr
         const patch: PreviewPatch = useOrder ? { kind: 'order', ...order } : { kind: 'value', path: snapshot.path, value: cache.expand(snapshot) }
         if (patch.kind === 'value') cache.patch(patch.path, patch.value)
         else cache.order(patch)
-        const result = useOrder === reorderNativeDraft ? applyNativeOrder(latest.current.current, order!) : undefined
-        const next = result ? result.value : applyPreviewPatch(latest.current.current, patch, latest.current.apply, latest.current.reorder)
-        if (result ? !result.matched : next === latest.current.current) return false
+        const overrides = new Map(latest.current.overrides)
+        // A replacement supersedes its earlier clear. Replay native values from the real
+        // source so a null leaf never has to invent the image/list identity it just lost.
+        supersede(overrides, patch)
+        const key = `${patch.kind}:${patch.path}`
+        let base = latest.current.current
+        if (latest.current.native) {
+          const history = new Map(latest.current.settling)
+          for (const previous of overrides.values()) remember(history, previous)
+          supersede(history, patch)
+          base = latest.current.source
+          for (const previous of history.values()) base = applyPreviewPatch(base, previous, latest.current.apply, latest.current.reorder)
+        }
+        const result = useOrder === reorderNativeDraft ? applyNativeOrder(base, order!) : undefined
+        const next = result ? result.value : applyPreviewPatch(base, patch, latest.current.apply, latest.current.reorder)
+        if (result ? !result.matched : next === base) return false
+        overrides.set(key, patch)
         latest.current.current = next
-        setShown(previous => {
-          const overrides = new Map(previous.overrides)
-          // A move changes only order: pending child edits and earlier inserts still apply.
-          if (patch.kind === 'value') for (const [key, previous] of overrides) if (previous.path === patch.path || previous.path.startsWith(`${patch.path}/`)) overrides.delete(key)
-          const key = `${patch.kind}:${patch.path}`
-          overrides.delete(key)
-          overrides.set(key, patch)
-          return { ...previous, value: next, overrides }
-        })
+        latest.current.overrides = overrides
+        setShown(previous => ({ ...previous, value: next, overrides }))
         return true
       },
     }

package/src/components/Image.tsx

@@ -2,6 +2,7 @@ import NextImage, { getImageProps } from 'next/image'
 import { createElement } from 'react'
 import type { ImageRead } from '../elements'
 import { draftAttrs } from './draft'
+import { safeDraftPath } from '../bridge/nativePath'
 import { imageProps, isGrantPath, pictureSources, type ImageProps } from './imageProps'
 /**
  * One declared variant's `<source>`, built with `next/image`'s own `getImageProps` so its `srcSet`
@@ -17,11 +18,14 @@ export const sourceProps = (props: ImageProps, s: ReturnType<typeof pictureSourc
   // An unoptimised image has no generated srcSet, so the raw path is the candidate.
   return { key: s.name, media: s.media, srcSet: p.srcSet ?? p.src, sizes: p.sizes }
 }
-export function Image({ value, sizes, fill, priority, className, figureClassName, variants }: { value: ImageRead | null | undefined; sizes?: string; fill?: boolean; priority?: boolean; className?: string; figureClassName?: string; variants?: Record<string, { media: string }> }) {
-  if (!value) return null
-  const attrs = draftAttrs(value)
+export function Image({ value, draftPath, sizes, fill, priority, className, figureClassName, variants }: { value: ImageRead | null | undefined; draftPath?: string; sizes?: string; fill?: boolean; priority?: boolean; className?: string; figureClassName?: string; variants?: Record<string, { media: string }> }) {
+  const explicit = draftPath && safeDraftPath(draftPath) ? draftPath : undefined
+  const path = value?.$path && safeDraftPath(value.$path) ? value.$path : explicit
+  const attrs = { ...draftAttrs(value), ...draftAttrs(path ? { $path: path } : null), ...(explicit ? { 'data-u90-empty-target': 'image' } : {}) }
+  const missing = () => path ? createElement('div', { ...attrs, className, 'data-u90-missing': 'image', style: { minWidth: 48, minHeight: 48, ...(fill ? { position: 'absolute' as const, inset: 0 } : {}) } }, 'Image missing') : null
+  if (!value) return missing()
   const props = imageProps(value, { sizes, fill, priority })
-  if (!props) return value.$path ? createElement('div', { ...attrs, className, 'data-u90-missing': 'image' }, 'Image missing') : null
+  if (!props) return missing()
   const sources = pictureSources(value, variants)
   const img = sources.length
     ? createElement('picture', null, ...sources.map((s) => createElement('source', sourceProps(props, s))), createElement(NextImage, { ...props, className, ...attrs }))

package/src/components/List.tsx

@@ -0,0 +1,26 @@
+import { createElement, Fragment, type ComponentPropsWithoutRef, type ReactNode } from 'react'
+import { DraftList, type ListTag } from '../bridge/DraftList'
+import { nativeListItemPath, nativeListPaths, nativePath, safeDraftPath } from '../bridge/nativePath'
+
+type Props<T, Tag extends ListTag> = { as: Tag; value: T[]; draftPath?: string; itemPaths?: readonly string[]; children: (item: T, index: number) => ReactNode }
+  & Omit<ComponentPropsWithoutRef<Tag>, 'as' | 'value' | 'children' | 'dangerouslySetInnerHTML'>
+
+/** Server-safe list rendering with immediate draft ordering. Replace the existing
+ * container with List as="ul" (or its original tag), preserving its attributes.
+ * The item renderer runs here; only rendered slots cross the client boundary. */
+export function List<T, Tag extends ListTag>({ as, value, draftPath, itemPaths, children, ...attributes }: Props<T, Tag>) {
+  const paths = itemPaths ?? nativeListPaths(value)
+  const first = paths?.[0]
+  const path = draftPath ?? (first ? first.slice(0, first.lastIndexOf('/')) : nativePath(value))
+  if (!path) return createElement(as, attributes, value.map((item, index) => <Fragment key={(item as { _id?: string } | null)?._id ?? index}>{children(item, index)}</Fragment>))
+  if (!safeDraftPath(path)) throw new Error('List requires a valid draft path.')
+  const seen = new Set<string>()
+  const items = value.map((item, index) => {
+    const at = nativeListItemPath(value, index, paths, path)
+    const id = at?.startsWith(`${path}/`) ? at.slice(path.length + 1) : undefined
+    if (!id || id.includes('/') || seen.has(id)) throw new Error('Draft List items require unique stable paths. Pass itemPaths for nullable leaf lists.')
+    seen.add(id)
+    return { id, $path: at!, content: children(item, index) }
+  })
+  return <DraftList key={path} as={as} attributes={attributes} path={path} items={items}/>
+}

package/src/components/draft.ts

@@ -7,3 +7,22 @@ export const draftAttrs = (value: Marked, edit?: 'text' | 'rich' | 'link-label')
   value && value.$path ? { 'data-u90-field': value.$path, ...(edit ? { 'data-u90-edit': edit } : {}), ...(value.$fallback ? { 'data-u90-fallback': '' as const } : {}) } : {}
 export const editable = (value: Marked): DraftAttrs => draftAttrs(value, value && 'text' in value ? 'text' : undefined)
 export const editableRich = (value: Marked): DraftAttrs => draftAttrs(value, 'rich')
+import { nativeChildPath, nativeListItemPath, nativeListPaths, safeDraftPath } from '../bridge/nativePath'
+
+
+/** An actual draft address for a declared child, including a nullable child with no own path. */
+export function draftFieldPath(parent: unknown, key: string): string | undefined {
+  if (!parent || typeof parent !== 'object' || Array.isArray(parent) || !Object.hasOwn(parent, key) || !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key) || ['__proto__', 'constructor', 'prototype'].includes(key)) return
+  const child = (parent as Record<string, unknown>)[key]
+  const own = child && typeof child === 'object' ? (child as { $path?: unknown }).$path : undefined
+  if (typeof own === 'string' && safeDraftPath(own)) return own
+  return nativeChildPath(parent, key)
+}
+
+/** A nullable leaf-list item's stable address, carried separately from its read value. */
+export function draftListItemPath(parent: unknown, key: string, index: number): string | undefined {
+  if (!parent || typeof parent !== 'object' || Array.isArray(parent) || !Object.hasOwn(parent, key) || ['__proto__', 'constructor', 'prototype'].includes(key) || !Number.isInteger(index) || index < 0) return
+  const values = (parent as Record<string, unknown>)[key]
+  if (!Array.isArray(values) || index >= values.length) return
+  return nativeListItemPath(values, index, nativeListPaths(values, parent, key), draftFieldPath(parent, key))
+}

package/src/components/index.ts

@@ -1,4 +1,5 @@
 export { Entries } from './Entries'
+export { List } from './List'
 export { Text } from './Text'
 export { RichText, richTextNodes } from './RichText'
 export { Link, isInternal } from './Link'
@@ -9,5 +10,5 @@ export { Image } from './Image'
 export { imageProps, isGrantPath, objectPosition, pictureSources, type ImageProps } from './imageProps'
 export { Video } from './Video'
 export { videoProps, type VideoHTMLProps } from './videoProps'
-export { draftAttrs, editable, editableRich, type DraftAttrs } from './draft'
+export { draftAttrs, draftFieldPath, draftListItemPath, editable, editableRich, type DraftAttrs } from './draft'
 export { LanguageSwitcher, useLanguage, rememberLanguage } from '../switcher/LanguageSwitcher'

package/src/elements/ops/draftPaths.ts

@@ -0,0 +1,23 @@
+import type { FieldDecl } from '../define'
+
+// Arrays keep their ordinary leaf values, including null. Live snapshots retain IDs
+// separately; enclosing groups serialize the same paths across the RSC boundary.
+const lists = new WeakMap<readonly unknown[], readonly string[]>()
+export const draftListPaths = (value: unknown): readonly string[] | undefined => Array.isArray(value) ? lists.get(value) : undefined
+export function rememberDraftList<T>(value: T[], paths: readonly string[] | undefined): T[] {
+  if (paths?.length === value.length) lists.set(value, paths)
+  return value
+}
+
+/** Real declaration addresses for nullable Single aliases, separate from their nullable values. */
+export function draftGroupMetadata(fields: Record<string, FieldDecl>, at: string, values: Record<string, unknown> = {}): { $path: string; $fieldPaths?: Record<string, string>; $listPaths?: Record<string, readonly string[]> } {
+  const aliases = Object.entries(fields).flatMap(([key, field]) => {
+    const single = 'element' in field && field.element === 'u90/single' ? field.options?.key : undefined
+    return typeof single === 'string' && /^[a-z][a-zA-Z0-9_-]*$/.test(single) ? [[key, `single:${single}`]] : []
+  })
+  const listPaths = Object.keys(fields).flatMap(key => {
+    const paths = draftListPaths(values[key])
+    return paths?.length ? [[key, paths]] : []
+  })
+  return { $path: at, ...(aliases.length ? { $fieldPaths: Object.fromEntries(aliases) } : {}), ...(listPaths.length ? { $listPaths: Object.fromEntries(listPaths) } : {}) }
+}

package/src/elements/ops/expand.ts

@@ -4,6 +4,7 @@ import { path } from '../path'
 import { getContainer, getElement } from '../registry'
 import { record } from '../containers/group'
 import { prefixedRoute } from '../prefix'
+import { draftGroupMetadata, rememberDraftList } from './draftPaths'
 
 export type Resolved = {
   media?: Map<string, MediaRecord>
@@ -53,9 +54,12 @@ export function expandField(schema: Schema, decl: FieldDecl, value: unknown, ctx
   if (isLeaf(decl)) return expandLeaf(getElement(decl.element), decl, value, ctx)
   const container = getContainer(decl.container)
   const children = container.children(decl, decl.container === 'u90/group' ? (record(value) ? value : {}) : value, schema)
-  if (decl.container === 'u90/group') return Object.fromEntries(children.map((c) => [c.key, expandField(schema, c.decl, c.value, withAt(ctx, path.child(ctx.at, c.key)))]))
+  if (decl.container === 'u90/group') {
+    const fields = Object.fromEntries(children.map((c) => [c.key, expandField(schema, c.decl, c.value, withAt(ctx, path.child(ctx.at, c.key)))]))
+    return { ...(ctx.draft ? draftGroupMetadata(decl.fields, ctx.at, fields) : {}), ...fields }
+  }
   const items = Array.isArray(value) ? value : []
-  return children.map((c, i) => {
+  const expanded = children.map((c, i) => {
     const inner = expandField(schema, c.decl, c.value, withAt(ctx, path.child(ctx.at, c.key)))
     // A leaf item reads as its element's value (which carries its own `$path`); a group item, like a zone item, carries the item's path in draft.
     if (decl.container === 'u90/list') return isLeaf(decl.item) ? inner : { _id: c.key, ...(ctx.draft ? { $path: path.child(ctx.at, c.key) } : {}), ...(inner as object) }
@@ -65,6 +69,7 @@ export function expandField(schema: Schema, decl: FieldDecl, value: unknown, ctx
     if (block === SLOT || !Object.hasOwn(schema.blocks, block)) return { _id: c.key, _block: block, ...metadata }
     return { _id: c.key, _block: block, ...metadata, ...(ctx.draft ? { $path: path.child(ctx.at, c.key) } : {}), ...(inner as object) }
   })
+  return ctx.draft && decl.container === 'u90/list' ? rememberDraftList(expanded, children.map(c => path.child(ctx.at, c.key))) : expanded
 }
 
 /**

package/src/legacy/cli.mjs

@@ -2,7 +2,7 @@
 import { readFile, writeFile } from 'node:fs/promises'
 
 /**
- * `npx --yes @unitninety/u90@1.0.6 pair <code>` — the one command an operator hands over. The u90 tool
+ * `npx --yes @unitninety/u90@1.2.0 pair <code>` — the one command an operator hands over. The u90 tool
  * runs this file for `u90 pair`. The command is scoped and pinned because an unscoped name, run in a
  * repository with no local bin, fetches whatever package npm holds under that name.
  *
@@ -115,7 +115,7 @@ const run = async () => {
   const args = process.argv.slice(2)
 
   if (args[0] !== 'pair' || !args[1]) {
-    fail('Usage: npx --yes @unitninety/u90@1.0.6 pair <code> --site https://example.com [--platform https://cms…]')
+    fail('Usage: npx --yes @unitninety/u90@1.2.0 pair <code> --site https://example.com [--platform https://cms…]')
   }
 
   const code = args[1]

package/src/legacy/content.ts

@@ -360,7 +360,7 @@ export const createContentClient = ({
             : !platformUrl
               ? 'PLATFORM_URL is unset'
               : 'PAYLOAD_API_KEY is unset'
-        }. Every page will render its committed fallback copy, and every collection route will 404. Set it in the site's environment — \`npx --yes @unitninety/u90@1.0.6 pair\` writes both.`,
+        }. Every page will render its committed fallback copy, and every collection route will 404. Set it in the site's environment — \`npx --yes @unitninety/u90@1.2.0 pair\` writes both.`,
       )
     }
     return true

package/src/server/render.tsx

@@ -21,7 +21,7 @@ export function createRender(site: Site) {
       if (!def) return item.$path ? createElement('div', { key: item._id, 'data-u90-block': item.$path, 'data-u90-missing': item._block }, `Block "${item._block}" was removed`) : null
       const { _id, _block, _hidden, $path, ...fields } = item
       // zones arrive rendered: replace each zone-typed field with <Blocks/>, threading `entry` through
-      const props: Record<string, unknown> = { ...fields }
+      const props: Record<string, unknown> = { ...fields, ...($path ? { $path } : {}) }
       for (const [name, decl] of Object.entries(def.fields)) if ('container' in (decl as object) && (decl as { container: string }).container === 'u90/zone') props[name] = createElement(Blocks, { value: fields[name], entry, anchors })
       // a block declared with `entry:` renders inside that collection's entry pages and receives the entry itself
       if (def.entry) props.entry = entry

package/src/site/fields.ts

@@ -1,5 +1,5 @@
 import type { BooleanRead, ChoiceReadValue, DateRead, EntriesRead, EntryRead, FileRead, ImageRead, LinkRead, NumberRead, RichTextRead, TextRead, VideoRead } from '../elements'
-import type { BlockDef, Decl, Fields, Read, SingleDef, Simplify, ZoneNode } from './types'
+import type { BlockDef, Decl, DraftReadMetadata, Fields, Read, SingleDef, Simplify, ZoneNode } from './types'
 
 type Common = { label?: string; description?: string; required?: boolean; translatable?: boolean; lock?: string[]; renamedFrom?: string }
 /** Options that are part of the field declaration itself go top-level; the rest is the element's `options`. */
@@ -35,7 +35,7 @@ export const selection = (to: string, o: Common & { default?: unknown; many?: bo
 export const query = (to: string, o: Common & { default?: unknown; previewFields?: string[] } = {}) => leaf<EntriesRead>('u90/query', o, { to, previewFields: o.previewFields })
 export const single = <R>(s: SingleDef<R>, o: Common = {}): Decl<R> => leaf<R>('u90/single', o, { key: s.key })
 
-export const group = <F extends Fields>(fields: F, o: { label?: string } = {}): Decl<{ [K in keyof F]: Read<F[K]> }> & { readonly __group: true } =>
+export const group = <F extends Fields>(fields: F, o: { label?: string } = {}): Decl<Simplify<{ [K in keyof F]: Read<F[K]> } & DraftReadMetadata>> & { readonly __group: true } =>
   ({ container: 'u90/group', ...(o.label ? { label: o.label } : {}), fields, order: Object.keys(fields) }) as never
 export const list = <D extends Decl<unknown>>(
   item: D,

package/src/site/types.ts

@@ -7,6 +7,8 @@ import type { BlockDecl, CollectionDecl, FieldDecl, GroupDecl, LeafDecl, ListDec
 export type Decl<R> = FieldDecl & { readonly __read?: R }
 export type Read<D> = D extends Decl<infer R> ? R : never
 export type Fields = Record<string, Decl<unknown>>
+/** Present only on native draft reads, never authored content or published props. */
+export type DraftReadMetadata = { $path?: string; $fieldPaths?: Record<string, string>; $listPaths?: Record<string, readonly string[]> }
 /**
  * Flattens an intersection into a single mapped object type. The strict `Equal` check used by
  * `types.test-d.ts` treats an intersection (`{ _id: string } & Read<D>`) as distinct from the
@@ -72,9 +74,9 @@ export type SiteManifest = {
  * collection's declaration. Not `EntryRead`: an entry page's entry has no `collection` or `status`
  * (finding 21).
  */
-export type EntryReadOf<C> = C extends CollectionDef<infer F> ? { id: string; slug: string; route?: string; fields: { [K in keyof F]: Read<F[K]> } } : never
+export type EntryReadOf<C> = C extends CollectionDef<infer F> ? { id: string; slug: string; route?: string; fields: { [K in keyof F]: Read<F[K]> } & DraftReadMetadata } : never
 export type BlockProps<B> = B extends BlockDef<infer F, infer C>
-  ? Simplify<{ [K in keyof F]: Read<F[K]> } & (C extends CollectionDef ? { entry: EntryReadOf<C> } : {})>
+  ? Simplify<{ [K in keyof F]: Read<F[K]> } & DraftReadMetadata & (C extends CollectionDef ? { entry: EntryReadOf<C> } : {})>
   : never
 export type { FieldDecl, LeafDecl, GroupDecl, ListDecl, ZoneDecl, BlockDecl, CollectionDecl, SingleDecl, Schema }
 export type { CollectionAuthoring, CollectionAuthoringAnchor, CollectionAuthoringSections } from '../elements'

package/src/site/version.ts

@@ -1 +1 @@
-export const SITE_KIT_VERSION = '1.6.6'
+export const SITE_KIT_VERSION = '1.8.0'