@unitninety/site-kit 1.6.4 → 1.6.6

package/README.md

@@ -5,7 +5,7 @@ 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.4 --version
+npx --yes @unitninety/u90@1.0.6 --version
 ```
 
 UnitNinety imports packages made for that version only, so keep the version the tool names.
@@ -37,6 +37,37 @@ The form uses each field's label, default and text constraints. The list must co
 
 Creation saves a draft with the normal schema defaults and approved template. Routed entries open Canvas for images and sections; collections without pages keep their content editor in the CMS. The matching platform/Site Kit implementation must be deployed together before using this new metadata in an uploaded package.
 
+### Immediate authored-list previews
+
+Client components inside a draft block can opt in with `useDraftContent`:
+
+```tsx
+'use client'
+import { useDraftContent } from '@unitninety/site-kit/bridge'
+
+export function Header({ navigation }) {
+  const draft = useDraftContent(navigation, 'navigation')
+  return <nav>{draft.menuItems.map(item => <a key={item._id} href={item.href.href ?? '#'}>{item.label.text}</a>)}</nav>
+}
+```
+
+Call the hook on native reads before converting them for a presentation component. `renderBlocks` supplies the draft block path automatically; custom `DraftBlocks` renderers must supply each item's native `path`. Key rows by `_id`, not their editable label, URL or position. Existing server-only published content is unchanged.
+
+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
@@ -54,3 +85,75 @@ pending order/removal through slow refreshes; rejected saves reconcile to the se
 Published output is an ordinary div and server-rendered cards. Newly added entries whose markup
 is not already present appear when the save's server refresh arrives. Query results rendered
 with a plain `.map()` still work, but wait for that refresh to change their order or membership.
+
+### Shared blocks with page-only copies
+
+A shared block uses one content group whose declaration matches a Single:
+
+```tsx
+const enquiryContent = group({ heading: text(), contact: link() })
+const singles = defineSingles({ enquiry: enquiryContent })
+const enquiry = block('enquiry', {
+  label: 'Enquiry',
+  fields: { content: enquiryContent },
+  shared: { single: 'enquiry', field: 'content' },
+  component: Enquiry,
+})
+// Include enquiry in a normal zone's allow/default lists.
+```
+
+A shared block may retain additional design fields only when every leaf is locked with `lock: ['$']`. Optional `shared.previewFields` lists the content keys this placement actually renders (1–30 unique existing keys); it filters both linked and page-specific trees without deleting stored data. Shared content uses the same accordion and selected-field editor as ordinary blocks.
+
+The default `content: null` follows the Single. A content object is an independent copy owned by that block instance. Both render through the same component and retain the same block ID and controls. The Inspector labels the scope and offers shared editing or “Customise for this page”; customising copies the latest saved shared value. Templates seed the initial blocks, while an authored empty zone remains empty. Converting an existing hardcoded placement requires migrating its documents and renderer together.
+
+### Inspector-only canvas editing
+
+Pass `inlineEditing={false}` to `U90Bridge` in the root layout when clients should type only in the inspector. Canvas clicks still select and highlight fields; inspector text, rich-text and link-label previews remain immediate. The bridge keeps the `data-u90-edit` metadata for previews but does not add `contenteditable` or send canvas input edits. The option defaults to `true` for existing sites.
+
+### Featured-entry fields in the block tree
+
+Selections, relations and queries can declare the collection fields that their component displays:
+
+```ts
+selection('projects', {
+  many: true,
+  depth: 2,
+  previewFields: ['title', 'heroMedia', 'industry', 'client', 'date', 'location'],
+})
+```
+
+`previewFields` is optional editor metadata: unique top-level field keys (1–20). It does not change stored references, query rules, ordering or read shapes. The same expandable rows work on pages, collection entries and layouts. A referenced entry expands inside its block; choosing a leaf opens its primitive editor above the tree. A referenced field can itself declare `previewFields` to expose a nested list. Cycles and deep chains fall back to the ordinary reference editor. Derived relations retain their existing read-only editor.
+
+For example, KAW's Home declares `query('industries', { previewFields: ['name', 'description', 'capabilities'] })`. The Industries collection declares `relation('capabilities', { many: true, previewFields: ['name', 'heroMedia'] })`. Industry names, introductions, capability names and images still write to their original entry paths and update everywhere. Membership edits only change the owning reference. Queries preserve their rules and use pin/exclude/order controls; the plus control uses the existing tenant-scoped picker.
+
+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.4",
+  "version": "1.6.6",
   "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,6 +60,7 @@
     "access": "public"
   },
   "dependencies": {
+    "parse5": "7.3.0",
     "zod": "4.4.3"
   },
   "peerDependencies": {

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/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 = {
@@ -249,7 +250,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 +387,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
@@ -571,7 +567,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 +590,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()) {

package/src/bridge/index.ts

@@ -13,3 +13,4 @@ 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'

package/src/bridge/nativeDraft.ts

@@ -4,6 +4,7 @@ import { expandField } from '../elements/ops/expand'
 import { applyQueryPicks, type QueryStored } from '../elements/leaves/query'
 import type { EntriesRead } from '../elements/leaves/selection'
 import type { DraftSnapshot } from './protocol'
+import { reorderNativeDraft, type DraftOrder } from './nativeOrder'
 
 const unsafe = new Set(['__proto__', 'constructor', 'prototype'])
 const object = (value: unknown): value is Record<string, any> => !!value && typeof value === 'object' && !Array.isArray(value)
@@ -51,7 +52,7 @@ export function applyNativeDraft<T>(source: T, path: string, replacement: unknow
 /** 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>()
@@ -101,16 +102,33 @@ export class NativeDraftReferences {
       }
     }
     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 {

package/src/bridge/nativeOrder.ts

@@ -0,0 +1,68 @@
+import { nativePath, safeDraftPath } from './nativeDraft'
+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>()): unknown => {
+    if (!value || typeof value !== 'object' || seen.has(value) || '$$typeof' in value) return value
+    const at = nativePath(value) ?? parent
+    if (Array.isArray(value) && at === order.path) {
+      matched = true
+      return ordered(value, order.ids, item => {
+        const path = nativePath(item)
+        return path?.startsWith(`${order.path}/`) ? path.slice(order.path.length + 1)
+          : typeof item?._id === 'string' ? item._id : 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)
+      if (next !== child) {
+        if (result === value) result = Array.isArray(value) ? [...value] : { ...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
+}

package/src/bridge/registry.ts

@@ -1,6 +1,7 @@
 import type { EntryPicks } from './DraftEntries'
 import type { DraftSnapshot } from './protocol'
 import type { Bridge } from './createBridge'
+import type { DraftOrder } from './nativeOrder'
 
 /**
  * The one shared, module-level handle onto the live bridge instance and its reveal listeners.
@@ -22,9 +23,9 @@ export const registry: {
   current: Bridge | null
   reveals: Set<{ prefix: string; fn: () => void }>
   entryLists: Set<{ document: Document; beforeRefresh(): void; pick(path: string, picks: EntryPicks): boolean }>
-  draftValues: Set<{ document: Document; beforeRefresh(): void; afterRefresh(): void; preview(snapshot: DraftSnapshot): boolean }>
+  draftValues: Set<{ document: Document; beforeRefresh(): void; afterRefresh(): void; preview(snapshot: DraftSnapshot, order?: DraftOrder): boolean }>
   draftContents: Set<{ document: Document; beforeRefresh(): void; preview(path: string, value: unknown[]): boolean }>
-  blockOrders: Set<{ document: Document; beforeRefresh(): void; needsReload(): boolean; remove?(path: string): boolean; move(path: string, before: string | null): boolean }>
+  blockOrders: Set<{ document: Document; beforeRefresh(): void; needsReload(): boolean; remove?(path: string): boolean; reorder?(order: DraftOrder): boolean; move(path: string, before: string | null): boolean }>
 } = {
   current: null,
   reveals: new Set(),

package/src/bridge/selection.ts

@@ -1,3 +1,21 @@
+/** Explicit references win; a directly rendered Single otherwise belongs to its enclosing block. */
+function selectionContext(element: Element | null, path: string | null): { via?: string[]; block?: string } {
+  const references: string[] = []
+  let block: string | undefined
+  for (let node = element; node; node = node.parentElement) {
+    const reference = node.getAttribute('data-u90-reference')
+    if (reference && reference !== path) references.unshift(reference)
+    if (!block && path?.startsWith('single:')) {
+      const placement = node.getAttribute('data-u90-block')
+      if (placement && placement.length <= 512 && /^(page|entry|layout):[^/\s]+\/blocks\/[^/\s]+(?:\/[^/\s]+)*$/.test(placement)) block = placement
+    }
+  }
+  if (references.length) return { via: references.length <= 5 ? references : undefined }
+  return block ? { via: [block], block } : {}
+}
+
+export const selectionVia = (element: Element | null, path: string | null): string[] | undefined => selectionContext(element, path).via
+
 /** Draft-only selection geometry. Contents wrappers have no CSS box of their own. */
 export function createSelection(win: Window) {
   const doc = win.document
@@ -6,16 +24,46 @@ export function createSelection(win: Window) {
   overlay.setAttribute('aria-hidden', 'true')
   overlay.hidden = true
   let path: string | null = null
+  let via: readonly string[] = []
   let shouldReveal = false
   let frame: number | null = null
   let observer: MutationObserver | null = null
+  let selectedElement: HTMLElement | null = null
   const escaped = (value: string) => value.replace(/["\\]/g, '\\$&')
-  const target = () =>
-    path
-      ? doc.querySelector<HTMLElement>(
-          `[data-u90-field="${escaped(path)}"], [data-u90-block="${escaped(path)}"]`,
-        )
-      : null
+  const target = () => {
+    if (!path) return null
+    const selector = `[data-u90-field="${escaped(path)}"], [data-u90-block="${escaped(path)}"]`
+    if (!path.startsWith('single:') || !via.length) return doc.querySelector<HTMLElement>(selector)
+    // Re-resolve after React commits, but never silently select a different occurrence if the
+    // requested placement has disappeared. Context-free selections retain their old behavior.
+    const exact: HTMLElement[] = []
+    const fallback: HTMLElement[] = []
+    let fallbackBlockLength = 0
+    for (const element of doc.querySelectorAll<HTMLElement>(selector)) {
+      const context = selectionContext(element, path)
+      if (context.via?.length === via.length && context.via.every((ancestor, index) => ancestor === via[index])) exact.push(element)
+      // Older markup names only the enclosing block, while the inspector can name its Single
+      // field. Explicit references must still match exactly and take precedence over fallback.
+      else if (context.block && via.length === 1 && via[0]!.startsWith(`${context.block}/`) && via[0]!.length > context.block.length + 1) {
+        // A nested block and its outer block can both render this Single. Use the nearest
+        // placement named by the inspector, not another occurrence higher in that subtree.
+        if (context.block.length > fallbackBlockLength) {
+          fallback.length = 0
+          fallbackBlockLength = context.block.length
+        }
+        if (context.block.length === fallbackBlockLength) fallback.push(element)
+      }
+    }
+    const candidates = exact.length ? exact : fallback
+    return candidates.find((element) => bounds(element) !== null) ?? candidates[0] ?? null
+  }
+  const markTarget = () => {
+    const element = target()
+    if (selectedElement !== element) selectedElement?.removeAttribute('data-u90-selected')
+    selectedElement = element
+    element?.setAttribute('data-u90-selected', '')
+    return element
+  }
   type Box = {
     left: number
     top: number
@@ -42,9 +90,8 @@ export function createSelection(win: Window) {
   }
   const paint = () => {
     frame = null
-    const element = target()
     // Server refreshes can replace the selected node without changing its path.
-    element?.setAttribute('data-u90-selected', '')
+    const element = markTarget()
     let box = element ? bounds(element) : null
     if (!element || !box) {
       overlay.hidden = true
@@ -81,13 +128,14 @@ export function createSelection(win: Window) {
     if (path && frame === null) frame = win.requestAnimationFrame(paint)
   }
   return {
-    select(next: string | null, reveal = false) {
+    select(next: string | null, reveal = false, nextVia?: readonly string[]) {
       doc
         .querySelectorAll('[data-u90-selected]')
         .forEach((element) => element.removeAttribute('data-u90-selected'))
       path = next
+      via = nextVia ? [...nextVia] : []
       shouldReveal = reveal
-      target()?.setAttribute('data-u90-selected', '')
+      markTarget()
       overlay.hidden = true
       schedule()
     },
@@ -125,6 +173,7 @@ export function createSelection(win: Window) {
       if (frame !== null) win.cancelAnimationFrame(frame)
       frame = null
       path = null
+      selectedElement = null
       doc
         .querySelectorAll('[data-u90-selected]')
         .forEach((element) => element.removeAttribute('data-u90-selected'))

package/src/bridge/useDraftContent.tsx

@@ -4,6 +4,7 @@ import { createContext, useContext, useLayoutEffect, useMemo, useRef, useState,
 import { applyNativeDraft, NativeDraftReferences, safeDraftPath } from './nativeDraft'
 import type { DraftSnapshot } from './protocol'
 import { registry } from './registry'
+import { applyNativeOrder, reorderNativeDraft, type DraftOrder } from './nativeOrder'
 
 /** Set by draft block rendering; published components have no editing owner. */
 export const DraftContentPath = createContext<string | undefined>(undefined)
@@ -81,6 +82,9 @@ 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 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)
 const hasNativePath = (value: unknown, seen = new Set<object>()): boolean => {
   if (!value || typeof value !== 'object' || seen.has(value)) return false
@@ -90,29 +94,32 @@ const hasNativePath = (value: unknown, seen = new Set<object>()): boolean => {
 }
 
 /** React owns native previews throughout saving; a later refresh settles the server's result.
- * The optional adapter maps a native patch into a site's existing plain presentation props. */
-export function useDraftPreview<T>(source: T, apply: (source: T, patch: NativeDraftPatch) => T = applyPatch): T {
+ * The optional adapter maps a native patch into a site's existing plain presentation props.
+ * Custom adapters keep receiving complete snapshots unless they supply a third, order-only
+ * adapter. Use reorderNativeDraft for collections retaining native block $path values. */
+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 [cache] = useState(() => new NativeDraftReferences())
-  const indexed = useRef<{ source: T; references: readonly unknown[] } | null>(null)
-  if (!indexed.current || !sameSource(indexed.current.source, source) || indexed.current.references !== references) {
-    cache.add(references)
-    cache.add(source)
-    indexed.current = { source, references }
-  }
   const enabled = !!owner || hasNativePath(source)
-  const [shown, setShown] = useState({ source, value: source, owner, overrides: new Map<string, NativeDraftPatch>() })
+  const [shown, setShown] = useState({ source, value: source, owner, overrides: 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, NativeDraftPatch>()
+    const overrides = shown.owner === owner ? shown.overrides : new Map<string, PreviewPatch>()
     current = source
-    for (const patch of overrides.values()) current = apply(current, patch)
+    for (const patch of overrides.values()) current = applyPreviewPatch(current, patch, apply, reorder)
     setShown({ source, value: current, owner, overrides })
   }
-  for (const patch of shown.overrides.values()) cache.patch(patch.path, patch.value)
-  const latest = useRef({ current, source, references, apply })
-  latest.current = { current, source, references, apply }
+  const latest = useRef({ current, source, references, apply, reorder })
+  useLayoutEffect(() => {
+    cache.add(references)
+    cache.add(source)
+    for (const patch of shown.overrides.values()) {
+      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])
   useLayoutEffect(() => {
     if (!enabled) return
     const handler = {
@@ -124,21 +131,27 @@ export function useDraftPreview<T>(source: T, apply: (source: T, patch: NativeDr
       afterRefresh: () => setShown(previous => {
         cache.settle([latest.current.references, latest.current.source])
         let value = latest.current.source
-        for (const patch of previous.overrides.values()) value = latest.current.apply(value, patch)
+        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 }
       }),
-      preview: (snapshot: DraftSnapshot) => {
+      preview: (snapshot: DraftSnapshot, order?: DraftOrder) => {
         if (!safeDraftPath(snapshot.path)) return false
-        const patch = { path: snapshot.path, value: cache.expand(snapshot) }
-        cache.patch(patch.path, patch.value)
-        const next = latest.current.apply(latest.current.current, patch)
-        if (next === latest.current.current) return false
+        const useOrder = order && latest.current.reorder
+        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
         latest.current.current = next
         setShown(previous => {
           const overrides = new Map(previous.overrides)
-          for (const key of overrides.keys()) if (key === patch.path || key.startsWith(`${patch.path}/`)) overrides.delete(key)
-          overrides.set(patch.path, patch)
+          // 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 }
         })
         return true

package/src/components/BlockLink.tsx

@@ -0,0 +1,28 @@
+'use client'
+
+import NextLink from 'next/link'
+import { type ComponentProps } from 'react'
+import { clearBlockNavigation, requestBlockNavigation } from './block-navigation'
+
+/** Only generated SDK destinations need cooperation with NextLink's navigation lifecycle. */
+export function BlockLink({ onNavigate, href, replace, scroll, ...props }: ComponentProps<typeof NextLink>) {
+  return <NextLink {...props} href={href} replace={replace} scroll={scroll} onNavigate={event => {
+    let cancelled = false
+    onNavigate?.({ preventDefault: () => { cancelled = true; event.preventDefault() } })
+    if (cancelled || typeof href !== 'string') return
+    const url = new URL(href, window.location.href)
+    if (url.origin !== window.location.origin) return
+    if (url.pathname !== window.location.pathname || url.search !== window.location.search) {
+      requestBlockNavigation(window, url, scroll !== false)
+      return
+    }
+    clearBlockNavigation(window)
+    // NextLink has already honored onClick, modifiers, download and target; the
+    // caller's onNavigate also ran before committing generated same-page navigation.
+    event.preventDefault()
+    // Next's native history integration copies its own router state. Passing that
+    // private state back would mark this as an internal update and skip URL sync.
+    if (replace || url.href !== window.location.href) window.history[replace ? 'replaceState' : 'pushState'](null, '', url.href)
+    if (scroll !== false) window.document.dispatchEvent(new window.CustomEvent('u90:block-navigate'))
+  }} />
+}