@unitninety/site-kit 1.6.5 → 1.7.0

package/README.md

@@ -5,18 +5,41 @@ 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.5 --version
+npx --yes @unitninety/u90@1.1.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).
 
-### Layout reordering in Canvas
+### Keep cleared fields editable
 
-Site Kit 1.6.5 gives every draft layout Slot its own preview address. Moving the Slot or placing a block before it updates immediately through the shared renderer, including nested layouts. The optimistic order stays visible while saving, and older responses cannot undo a newer move. Published output is unchanged.
+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:
 
-Use Site Kit 1.6.5 with `@unitninety/u90@1.0.5` for new sites. Existing sites must update their Site Kit dependency and redeploy to receive the fix; updating the platform alone does not update a site's bundled renderer.
+```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
 
@@ -61,6 +84,19 @@ 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.
 
+### 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.
+
+Custom presentation adapters retain their existing snapshot behavior. If every rendered block collection keeps its native `$path` values, opt into the shared order adapter:
+
+```tsx
+import { useDraftPreview, reorderNativeDraft } from '@unitninety/site-kit/bridge'
+const current = useDraftPreview(source, applyPresentationPatch, reorderNativeDraft)
+```
+
+For plain presentation arrays without native paths, provide a third callback `(source, { path, ids }) => source` that reorders the existing objects by stable block ID. Keep membership, content and unrelated arrays unchanged. Test both the instant preview and the later server refresh; a complete zone snapshot must never replace formatted presentation props with raw native blocks.
+
 ### Immediate collection-list previews
 
 Render a query's `EntriesRead` with `Entries` from `@unitninety/site-kit/components` when its
@@ -122,3 +158,31 @@ For example, KAW's Home declares `query('industries', { previewFields: ['name',
 The site component must reveal the selected entry in its own tabs/carousels, including when its data arrives after selection. `useEditing()` exposes `selected` and `selectedVia`: the latter contains outer-to-inner reference field paths, disambiguating an entry reused in several parents. Mark a displayed list container with `data-u90-reference={reference.$path}` in draft mode to preserve this context when selecting its content on the canvas. Keep `data-u90-field` on each entry's own fields and a root marker on the revealed entry for row highlighting. A relation's target entry path is not its parent relation field path. These attributes do not introduce visitor-facing editing controls.
 
 Deploy matching Site Kit/platform code before importing this metadata, and restart a running dev server after changing registry options so Payload validation hooks reload.
+## Site-wide custom code
+
+Settings → Custom code stores three embed fields as a draft. The workspace’s existing Publish control makes that draft live and revalidates the cached site read. Saving a snippet never rebuilds the website. Editing requires Code permission; disabling Code also hides these settings.
+
+Install the server renderer in each root layout, using one snapshot for all three placements. Keep the site’s existing head content, body attributes, providers, and children:
+
+```tsx
+import { U90Bridge, U90CustomCode } from '@unitninety/site-kit/server'
+import { u90 } from '@/u90'
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const customCode = await u90.read.customCode()
+  return (
+    <html lang="en">
+      <head><U90CustomCode code={customCode} placement="head" /></head>
+      <body>
+        <U90CustomCode code={customCode} placement="bodyStart" />
+        <U90Bridge>{children}</U90Bridge>
+        <U90CustomCode code={customCode} placement="bodyEnd" />
+      </body>
+    </html>
+  )
+}
+```
+
+Keep these slots as direct children of the native head and body; do not wrap them in an HTML container or load the code after hydration. `read.customCode()` returns only published code and suppresses output in authenticated draft and test previews, including Canvas. The website’s existing Content Security Policy continues to apply.
+
+Existing sites need one initial code deployment to install a compatible Site Kit and these slots in every root layout. Subsequent custom-code changes use Publish and on-demand revalidation, without another deployment. New converter output includes the installation automatically.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@unitninety/site-kit",
-  "version": "1.6.5",
+  "version": "1.7.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": {
     ".": "./src/site/index.ts",
     "./server": "./src/server/index.ts",
+    "./custom-code": "./src/custom-code/index.ts",
     "./features/server": "./src/features/server/index.ts",
     "./features/contracts": "./src/features/contracts/index.ts",
     "./preview-lock": "./src/preview-lock/index.ts",
@@ -46,8 +47,7 @@
     "!src/elements/fixtures",
     "!src/elements/harness.ts",
     "!src/site/fixtures",
-    "!src/test-preview/fixtures.ts",
-    "!src/features/consent/test-fixtures.ts"
+    "!src/test-preview/fixtures.ts"
   ],
   "license": "UNLICENSED",
   "homepage": "https://unitninety.com",
@@ -60,7 +60,8 @@
     "access": "public"
   },
   "dependencies": {
-    "zod": "4.6.6"
+    "parse5": "7.3.0",
+    "zod": "4.4.3"
   },
   "peerDependencies": {
     "react": ">=19",

package/src/bridge/DraftBlocks.tsx

@@ -6,6 +6,7 @@ import { DraftContentPath } from './useDraftContent'
 import { registry } from './registry'
 import { needsEmbedReload, preserveBlockMoves } from './preserveBlockMoves'
 import { PreviewCommitBoundary } from './PreviewCommitBoundary'
+import { ordered, type DraftOrder } from './nativeOrder'
 
 type Item = { id: string; path?: string; content: ReactNode }
 type Move = { path: string; before: string | null }
@@ -55,6 +56,15 @@ export function DraftBlocks({ items }: { items: Item[] }) {
         setShown(value => ({ ...value, items: value.items.filter(item => item.path !== path), removed: new Set([...value.removed, path]) }))
         return true
       },
+      reorder: ({ path, ids }: DraftOrder) => {
+        if (!current.some(item => item.path === `${path}/${item.id}`)) return false
+        if (host.current && needsEmbedReload(host.current)) {
+          reload.current = true
+          return true
+        }
+        setShown(value => ({ ...value, items: ordered(value.items, ids, item => item.id), order: ids }))
+        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

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

@@ -4,7 +4,8 @@ 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 { snapshotOrder } from './nativeOrder'
+import { createSelection, selectionVia } from './selection'
 import { EDITING_CSS } from './styles'
 
 export type BridgeOptions = {
@@ -98,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)
@@ -249,7 +259,7 @@ export function createBridge(win: Window, opts: BridgeOptions) {
   /** Outline the element at `path` (field or block) and clear any previous outline. */
   const selection = createSelection(win)
   const markSelected = (path: string | null, scroll = false, via?: string[]) => {
-    selection.select(path, scroll)
+    selection.select(path, scroll, via)
     opts.onSelect?.(path, via)
   }
 
@@ -386,12 +396,7 @@ export function createBridge(win: Window, opts: BridgeOptions) {
       // (a menu toggle) still works while the Canvas is open.
       e.preventDefault()
     }
-    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
+    const via = selectionVia(el ?? null, path)
     markSelected(path, false, via)
     send({ type: 'u90:select', path, ...(via ? {via} : {}) })
     const edit = el?.getAttribute('data-u90-edit') as 'text' | 'rich' | 'link-label' | null
@@ -408,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.
@@ -571,7 +577,10 @@ export function createBridge(win: Window, opts: BridgeOptions) {
     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
+      const order = instruction.kind === 'move' ? snapshotOrder(draft, instruction.path) : undefined
+      for (const owner of registry.draftValues) if (owner.document === doc) handled = owner.preview(draft, order) || handled
+      // Update every rendered instance; hidden destinations only exist in the full snapshot.
+      if (order) for (const owner of registry.blockOrders) if (owner.document === doc) handled = !!owner.reorder?.(order) || handled
       if (handled || instruction.kind === 'value') return
     }
     const list = instruction.kind === 'list' ? instruction : instruction.list
@@ -591,9 +600,11 @@ export function createBridge(win: Window, opts: BridgeOptions) {
       if (handled) return
     }
     if (instruction.kind === 'move') {
+      let handled = false
       for (const owner of registry.blockOrders) {
-        if (owner.document === doc && owner.move(instruction.path, instruction.before)) return
+        if (owner.document === doc) handled = owner.move(instruction.path, instruction.before) || handled
       }
+      if (handled) return
     }
     if (refreshing && MOVES_NODES.has(instruction.kind)) return
     if ((instruction.kind === 'text' || instruction.kind === 'rich' || instruction.kind === 'link-label') && editing?.getAttribute('data-u90-field') === instruction.path && !doc.hasFocus()) {
@@ -962,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)
@@ -996,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

@@ -13,3 +13,6 @@ 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,57 +1,44 @@
 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. */
 export class NativeDraftReferences {
   private reads = new Map<string, unknown>()
-  private pending = new Map<string, unknown>()
+  private pending = new Map<string, { kind: 'value'; path: string; value: unknown } | { kind: 'order'; path: string; ids: string[] }>()
   private media = new Map<string, MediaRecord>()
   private pages = new Map<string, PageRecord>()
   private entries = new Map<string, EntryRead>()
@@ -60,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)
@@ -96,21 +86,38 @@ 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)
-    for (const [path, value] of this.pending) this.applyPatch(path, value)
+    for (const patch of this.pending.values()) {
+      if (patch.kind === 'value') this.applyPatch(patch.path, patch.value)
+      else this.applyOrder(patch)
+    }
   }
 
   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)
+    for (const [key, patch] of this.pending) if (patch.path === path || patch.path.startsWith(`${path}/`)) this.pending.delete(key)
+    this.pending.set(`value:${path}`, { kind: 'value', path, value })
     this.applyPatch(path, value)
   }
 
+  order(order: DraftOrder): void {
+    const key = `order:${order.path}`
+    this.pending.delete(key)
+    this.pending.set(key, { kind: 'order', ...order })
+    this.applyOrder(order)
+  }
+
+  private applyOrder(order: DraftOrder): void {
+    for (const [key, read] of this.reads) this.reads.set(key, reorderNativeDraft(read, order))
+    for (const [key, entry] of this.entries) this.entries.set(key, reorderNativeDraft(entry, order))
+    for (const [key, single] of this.singles) this.singles.set(key, reorderNativeDraft(single, order))
+    for (const [key, query] of this.queries) this.queries.set(key, reorderNativeDraft(query, order))
+  }
+
   beforeRefresh(): void { this.pending.clear() }
 
   settle(values: unknown): void {
@@ -124,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))
   }
 
@@ -162,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 }
@@ -171,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

@@ -0,0 +1,72 @@
+import { rememberDraftList } from '../elements/ops/draftPaths'
+import { nativeChildPath, nativeListItemPath, nativeListPaths, nativePath, safeDraftPath } from './nativePath'
+import type { DraftSnapshot } from './protocol'
+
+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. */
+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
+  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.every(item => item && typeof item._id === 'string' && 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 }
+}
+
+/** Preserve membership and object identity, including items a newer render introduced. */
+export function ordered<T>(items: T[], ids: string[], id: (item: T) => string | undefined): T[] {
+  const ranks = new Map(ids.map((key, index) => [key, index]))
+  const known = items.filter(item => ranks.has(id(item)!)).sort((a, b) => ranks.get(id(a)!)! - ranks.get(id(b)!)!)
+  let index = 0
+  const next = items.map(item => ranks.has(id(item)!) ? known[index++]! : item)
+  return next.every((item, i) => item === items[i]) ? items : next
+}
+
+/** Reorder each native/presentation alias of a zone, leaving its content intact. */
+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>(), 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
+      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 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) ? rememberDraftList([...value], paths) : { ...value }
+        result[key] = next
+      }
+    }
+    return result
+  }
+  return { value: visit(source) as T, matched }
+}
+
+/** Opt-in reorder adapter for presentation collections whose blocks retain native $path values. */
+export function reorderNativeDraft<T>(source: T, order: NativeDraftOrder): T {
+  return applyNativeOrder(source, order).value
+}