@unitninety/site-kit 1.6.5 → 1.6.6

package/README.md

@@ -5,19 +5,13 @@ 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.0.6 --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
-
-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.
-
-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.
-
 ### 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.
@@ -61,6 +55,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 +129,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.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,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/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'))
+  }} />
+}

package/src/components/Link.tsx

@@ -2,6 +2,8 @@ import NextLink from 'next/link'
 import { Children, createElement, type ReactNode } from 'react'
 import type { LinkRead } from '../elements'
 import { draftAttrs } from './draft'
+import { BlockLink } from './BlockLink'
+import { ID_RE } from '../elements/ids'
 export const isInternal = (href: string) => href.startsWith('/') && !href.startsWith('//')
 export function Link({ value, children, ...rest }: { value: LinkRead | null | undefined; children?: ReactNode } & Record<string, unknown>) {
   if (!value) return null
@@ -20,5 +22,10 @@ export function Link({ value, children, ...rest }: { value: LinkRead | null | un
   // element's props pass through). The href is always the value's.
   const tab: Record<string, unknown> = value.newTab ? { target: '_blank', rel: 'noopener' } : {}
   for (const key of ['target', 'rel'] as const) if (rest[key] !== undefined) tab[key] = rest[key]
-  return isInternal(value.href) && !(value.to && 'file' in value.to) ? createElement(NextLink, { ...attrs, href: value.href, ...tab } as never, label) : createElement('a', { ...attrs, href: value.href, ...tab }, label)
+  let generated = false
+  try {
+    const hash = decodeURIComponent(new URL(value.href, 'https://u90.invalid').hash.slice(1))
+    generated = hash.startsWith('u90-block-') && ID_RE.test(hash.slice(10))
+  } catch { /* malformed legacy fragments remain ordinary links */ }
+  return isInternal(value.href) && !(value.to && 'file' in value.to) ? createElement(generated ? BlockLink : NextLink, { ...attrs, href: value.href, ...tab } as never, label) : createElement('a', { ...attrs, href: value.href, ...tab }, label)
 }

package/src/components/block-navigation.ts

@@ -0,0 +1,24 @@
+/** A generated link's accepted navigation, shared with the destination renderer. */
+type BlockNavigation = { url: URL; scroll: boolean; expires: number }
+const pending = new WeakMap<Window, BlockNavigation>()
+
+export function requestBlockNavigation(win: Window, url: URL, scroll: boolean) {
+  pending.set(win, { url, scroll, expires: Date.now() + 10_000 })
+}
+
+export function clearBlockNavigation(win: Window) {
+  pending.delete(win)
+}
+
+export function arrivingBlockNavigation(win: Window): BlockNavigation | undefined {
+  const request = pending.get(win)
+  if (!request) return
+  if (Date.now() >= request.expires) { pending.delete(win); return }
+  const actual = new URL(win.location.href)
+  const expected = request.url
+  if (actual.origin !== expected.origin || actual.pathname !== expected.pathname || actual.search !== expected.search) return
+  // Next 16.4 caches the initial document fragment in its canonical route URL,
+  // then appends the requested fragment on a return navigation. Correct only a
+  // still-pending explicit request, never arbitrary fragment-containing URLs.
+  if (actual.hash === expected.hash || actual.hash.endsWith(expected.hash)) return request
+}