@unitninety/site-kit 1.6.5 → 1.7.0

package/src/bridge/nativePath.ts

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

package/src/bridge/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/styles.ts

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

package/src/bridge/useDraftContent.tsx

@@ -2,8 +2,10 @@
 
 import { createContext, useContext, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import { applyNativeDraft, NativeDraftReferences, safeDraftPath } from './nativeDraft'
+import { nativePath } from './nativePath'
 import type { DraftSnapshot } from './protocol'
 import { registry } from './registry'
+import { applyNativeOrder, reorderNativeDraft, type DraftOrder } from './nativeOrder'
 
 /** Set by draft block rendering; published components have no editing owner. */
 export const DraftContentPath = createContext<string | undefined>(undefined)
@@ -81,6 +83,17 @@ const sameSource = (a: unknown, b: unknown): boolean => {
 }
 
 export type NativeDraftPatch = { path: string; value: unknown }
+type PreviewPatch = { kind: 'value'; path: string; value: unknown } | { kind: 'order'; path: string; ids: string[] }
+const supersede = (patches: Map<string, PreviewPatch>, patch: PreviewPatch) => {
+  if (patch.kind === 'value') for (const [key, previous] of patches) if (previous.path === patch.path || previous.path.startsWith(`${patch.path}/`)) patches.delete(key)
+  patches.delete(`${patch.kind}:${patch.path}`)
+}
+const remember = (patches: Map<string, PreviewPatch>, patch: PreviewPatch) => {
+  supersede(patches, patch)
+  patches.set(`${patch.kind}:${patch.path}`, patch)
+}
+const applyPreviewPatch = <T,>(source: T, patch: PreviewPatch, apply: (source: T, patch: NativeDraftPatch) => T, reorder: (source: T, order: DraftOrder) => T = reorderNativeDraft): T =>
+  patch.kind === 'order' ? reorder(source, patch) : apply(source, patch)
 const applyPatch = <T,>(source: T, patch: NativeDraftPatch): T => applyNativeDraft(source, patch.path, patch.value)
 const hasNativePath = (value: unknown, seen = new Set<object>()): boolean => {
   if (!value || typeof value !== 'object' || seen.has(value)) return false
@@ -90,57 +103,83 @@ 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 native = apply === applyPatch
+  const rootPath = nativePath(source) ?? owner
+  const applyValue = useMemo(() => native ? (value: T, patch: NativeDraftPatch) => applyNativeDraft(value, patch.path, patch.value, rootPath) : apply, [native, rootPath, apply])
   const [cache] = useState(() => new NativeDraftReferences())
-  const 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>(), settling: new Map<string, PreviewPatch>() })
   let current = shown.value
   if (!sameSource(shown.source, source) || shown.owner !== owner) {
-    const overrides = shown.owner === owner ? shown.overrides : new Map<string, NativeDraftPatch>()
+    const overrides = shown.owner === owner ? shown.overrides : new Map<string, PreviewPatch>()
     current = source
-    for (const patch of overrides.values()) current = apply(current, patch)
-    setShown({ source, value: current, owner, overrides })
+    for (const patch of overrides.values()) current = applyPreviewPatch(current, patch, applyValue, reorder)
+    setShown({ source, value: current, owner, overrides, settling: new Map() })
   }
-  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: applyValue, reorder, native, overrides: shown.overrides, settling: shown.settling })
+  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: applyValue, reorder, native, overrides: shown.overrides, settling: shown.settling }
+  }, [cache, current, source, references, applyValue, reorder, native, shown.overrides, shown.settling])
   useLayoutEffect(() => {
     if (!enabled) return
     const handler = {
       document,
       beforeRefresh: () => {
         cache.beforeRefresh()
-        setShown(value => ({ ...value, overrides: new Map() }))
+        // Keep the optimistic baseline visible while this request is pending. It is
+        // discarded on a new source/commit, never replayed over the server's answer.
+        const settling = new Map(latest.current.settling)
+        for (const patch of latest.current.overrides.values()) remember(settling, patch)
+        latest.current.overrides = new Map()
+        latest.current.settling = settling
+        setShown(value => ({ ...value, overrides: new Map(), settling }))
       },
       afterRefresh: () => setShown(previous => {
         cache.settle([latest.current.references, latest.current.source])
         let value = latest.current.source
-        for (const patch of previous.overrides.values()) value = 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 }
+        latest.current.settling = new Map()
+        return { ...previous, source: latest.current.source, value, settling: new Map() }
       }),
-      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 overrides = new Map(latest.current.overrides)
+        // A replacement supersedes its earlier clear. Replay native values from the real
+        // source so a null leaf never has to invent the image/list identity it just lost.
+        supersede(overrides, patch)
+        const key = `${patch.kind}:${patch.path}`
+        let base = latest.current.current
+        if (latest.current.native) {
+          const history = new Map(latest.current.settling)
+          for (const previous of overrides.values()) remember(history, previous)
+          supersede(history, patch)
+          base = latest.current.source
+          for (const previous of history.values()) base = applyPreviewPatch(base, previous, latest.current.apply, latest.current.reorder)
+        }
+        const result = useOrder === reorderNativeDraft ? applyNativeOrder(base, order!) : undefined
+        const next = result ? result.value : applyPreviewPatch(base, patch, latest.current.apply, latest.current.reorder)
+        if (result ? !result.matched : next === base) return false
+        overrides.set(key, patch)
         latest.current.current = next
-        setShown(previous => {
-          const overrides = new Map(previous.overrides)
-          for (const key of overrides.keys()) if (key === patch.path || key.startsWith(`${patch.path}/`)) overrides.delete(key)
-          overrides.set(patch.path, patch)
-          return { ...previous, value: next, overrides }
-        })
+        latest.current.overrides = overrides
+        setShown(previous => ({ ...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/Image.tsx

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

package/src/components/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
+}

package/src/components/draft.ts

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

package/src/components/index.ts

@@ -9,5 +9,5 @@ export { Image } from './Image'
 export { imageProps, isGrantPath, objectPosition, pictureSources, type ImageProps } from './imageProps'
 export { Video } from './Video'
 export { videoProps, type VideoHTMLProps } from './videoProps'
-export { draftAttrs, editable, editableRich, type DraftAttrs } from './draft'
+export { draftAttrs, draftFieldPath, draftListItemPath, editable, editableRich, type DraftAttrs } from './draft'
 export { LanguageSwitcher, useLanguage, rememberLanguage } from '../switcher/LanguageSwitcher'

package/src/custom-code/fragments.ts

@@ -0,0 +1,64 @@
+import { parseFragment, type DefaultTreeAdapterTypes } from 'parse5'
+import type { CustomCodePlacement } from './index'
+
+type Node = DefaultTreeAdapterTypes.ChildNode
+export type CustomCodeElement = DefaultTreeAdapterTypes.Element
+const headTags = new Set(['script', 'style', 'meta', 'link'])
+const bodyTags = new Set(['script', 'style', 'link', 'noscript'])
+const fallbackTags = new Set(['iframe', 'img', 'div', 'span', 'p'])
+const voidTags = new Set(['meta', 'link', 'img'])
+const reservedAttributes = new Set(['children', 'dangerouslysetinnerhtml', 'suppresshydrationwarning', 'suppresscontenteditablewarning', 'key', 'ref'])
+const urlAttributes = new Set(['src', 'href', 'action', 'formaction', 'poster', 'background', 'cite', 'data', 'longdesc', 'manifest', 'xlink:href'])
+
+/** parse5 supplies HTML tokenization, decoded attribute values, and source spans. In addition
+ * to parser errors we require complete contiguous spans: HTML's normal error recovery can
+ * silently drop document wrappers/end tags or insert missing closing tags without an error. */
+export function parseCustomCodeFragment(source: string, placement: CustomCodePlacement): CustomCodeElement[] {
+  const fail = (reason: string): never => { throw new Error(`${placement}: ${reason}`) }
+  const fragment = parseFragment(source, {
+    scriptingEnabled: false, sourceCodeLocationInfo: true,
+    onParseError: (error) => fail(`malformed HTML (${error.code})`),
+  })
+  const visit = (nodes: Node[], start: number, end: number, fallback: boolean, rawText = false) => {
+    let cursor = start
+    for (const node of nodes) {
+      const loc = node.sourceCodeLocation
+      if (!loc || loc.startOffset !== cursor) fail('unsupported or malformed HTML was discarded by the parser')
+      cursor = loc!.endOffset
+      if (node.nodeName === '#comment') continue
+      if ('value' in node) {
+        if (!fallback && !rawText && node.value.trim()) fail('ordinary text is only supported inside noscript fallbacks')
+        continue
+      }
+      if (!('tagName' in node)) fail('document declarations are not supported')
+      const element = node as CustomCodeElement
+      const tag = element.tagName
+      const allowed = fallback ? fallbackTags : placement === 'head' ? headTags : bodyTags
+      if (!allowed.has(tag)) fail(`<${tag}> is not supported in this placement${fallback ? ' inside noscript' : ''}`)
+      const location = element.sourceCodeLocation!
+      if (!location.startTag || (!voidTags.has(tag) && !location.endTag)) fail(`<${tag}> requires explicit opening and closing tags`)
+      for (const { name, value } of element.attrs) {
+        if (name.startsWith('on')) fail(`event attribute ${name} is not supported`)
+        if (reservedAttributes.has(name)) fail(`reserved attribute ${name} is not supported`)
+        if (name === 'srcdoc' || name === 'srcset' || name === 'imagesrcset') fail(`attribute ${name} is not supported`)
+        if (name === 'style' && !fallback) fail('inline style attributes on resource tags are not supported; use a style element')
+        if (tag === 'meta' && name === 'http-equiv' && value.trim().toLowerCase() === 'refresh') fail('meta refresh is not supported')
+        if (urlAttributes.has(name)) {
+          // Reject whitespace/control characters and backslashes before URL parsing can repair them.
+          if (/[\u0000-\u0020\u007f\\]/u.test(value) || !(value.startsWith('/') && !value.startsWith('//') || /^https:\/\//i.test(value))) fail(`${name} must be an HTTPS or root-relative resource URL`)
+          try { new URL(value, 'https://custom-code.invalid') } catch { fail(`${name} is not a valid resource URL`) }
+        }
+      }
+      if (!voidTags.has(tag)) visit(element.childNodes, location.startTag!.endOffset, location.endTag!.startOffset, fallback || tag === 'noscript', tag === 'script' || tag === 'style')
+    }
+    if (cursor !== end) fail('unsupported or malformed HTML was discarded by the parser')
+  }
+  visit(fragment.childNodes, 0, source.length, false)
+  return fragment.childNodes.filter((node): node is CustomCodeElement => 'tagName' in node)
+}
+
+/** Retain raw text and fallback markup exactly, including HTML entities and JS comments. */
+export function fragmentInnerHtml(source: string, element: CustomCodeElement): string {
+  const location = element.sourceCodeLocation!
+  return location.endTag ? source.slice(location.startTag!.endOffset, location.endTag.startOffset) : ''
+}

package/src/custom-code/index.ts

@@ -0,0 +1,30 @@
+import { parseCustomCodeFragment } from './fragments'
+
+export type CustomCodePlacement = 'head' | 'bodyStart' | 'bodyEnd'
+export type CustomCode = Record<CustomCodePlacement, string>
+export type PublishedCustomCode = { version: 1; revision: number } & CustomCode
+export const EMPTY_CUSTOM_CODE: CustomCode = Object.freeze({ head: '', bodyStart: '', bodyEnd: '' })
+
+/** Server-safe validation only: never executes scripts or retrieves submitted URLs.
+ * Client forms should import types only, keeping the HTML parser on the server. */
+export function validateCustomCode(input: unknown): CustomCode {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('custom code: expected head, bodyStart and bodyEnd strings')
+  const fields = Object.keys(EMPTY_CUSTOM_CODE) as CustomCodePlacement[]
+  for (const key of Object.keys(input)) {
+    if (!fields.includes(key as CustomCodePlacement)) throw new Error(`${key}: unsupported custom code field`)
+  }
+  const result = { ...EMPTY_CUSTOM_CODE }
+  let total = 0
+  for (const field of fields) {
+    const value = (input as Record<string, unknown>)[field]
+    if (!Object.hasOwn(input, field) || typeof value !== 'string') throw new Error(`${field}: expected a string`)
+    const normalized = value.replace(/\r\n?/g, '\n')
+    const size = new TextEncoder().encode(normalized).length
+    if (size > 64 * 1024) throw new Error(`${field}: exceeds the 64 KiB UTF-8 limit`)
+    total += size
+    if (total > 128 * 1024) throw new Error(`${field}: exceeds the 128 KiB total UTF-8 limit`)
+    parseCustomCodeFragment(normalized, field)
+    result[field] = normalized
+  }
+  return result
+}

package/src/elements/blockAnchor.ts

@@ -0,0 +1,7 @@
+import { ID_RE } from './ids'
+
+/** The public fragment for a stored block identity; names and ordering never enter its address. */
+export function blockAnchor(id: string): string {
+  if (!ID_RE.test(id)) throw new Error('Invalid stored block identity')
+  return `u90-block-${id}`
+}

package/src/elements/index.ts

@@ -33,3 +33,4 @@ export { translatableParts } from './ops/translatable'
 export { overlayKey, translatableLeaves, applyOverlay, type OverlayValues } from './ops/overlay'
 export { upgrade, UpgradeError, type UpgradeOptions } from './ops/upgrade'
 export { toJSONSchema } from './jsonSchema'
+export { blockAnchor } from './blockAnchor'

package/src/elements/ops/draftPaths.ts

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