okno 1.0.0-alpha.2 → 1.0.0-alpha.21

package/src/runtime/wrap.ts

@@ -0,0 +1,684 @@
+/**
+ * Global listener registry for .on() callbacks.
+ * Keyed by content path (e.g. "home.title"), values are Sets of callbacks.
+ * The editor dispatches "okno:change" CustomEvents, which this module catches
+ * and forwards to registered callbacks.
+ */
+const listeners = new Map<string, Set<(value: unknown) => void>>()
+
+let listening = false
+function ensureListener() {
+	const g = globalThis as any
+	if (listening || typeof g.document === "undefined") return
+	listening = true
+	g.document.addEventListener("okno:change", (e: any) => {
+		const { path, value } = e.detail
+		listeners.get(path)?.forEach((cb) => cb(value))
+	})
+}
+
+/**
+ * Names that should never be humanized — they're typically used as HTML
+ * attributes where a humanized fallback would break rendering ("Src", "Alt").
+ */
+const TECHNICAL_LEAVES = new Set([
+	"src",
+	"href",
+	"alt",
+	"id",
+	"class",
+	"className",
+	"width",
+	"height",
+	"type",
+	"name",
+	"value",
+])
+
+function humanize(name: string): string {
+	return name
+		.replace(/[-_]+/g, " ")
+		.replace(/([a-z])([A-Z])/g, "$1 $2")
+		.trim()
+		.replace(/^./, (c) => c.toUpperCase())
+}
+
+/**
+ * Resolve raw data to its string representation. When raw is missing,
+ * humanize the leaf segment of the path so empty fields render as a
+ * readable placeholder ("Title" for `home.title`) instead of empty —
+ * makes a fresh page visually scannable before scaffolding fills it in.
+ */
+function rawToString(raw: unknown, path = ""): string {
+	if (raw === null || raw === undefined) {
+		if (!path) return ""
+		const leaf = path.split(".").pop() ?? ""
+		if (!leaf || TECHNICAL_LEAVES.has(leaf)) return ""
+		return humanize(leaf)
+	}
+	if (typeof raw !== "object") return String(raw)
+	// Link object → render its text (so `{home.link}` shows the label).
+	if (isLinkObject(raw)) return raw.text ?? ""
+	return ""
+}
+
+/** Files objects have a `src` key — groups never do. */
+function isMediaObject(raw: unknown): raw is Record<string, unknown> {
+	return typeof raw === "object" && raw !== null && !Array.isArray(raw) && "src" in raw
+}
+
+/** Link fields always carry exactly `text` + `url` + `external` — distinct from
+ *  media (`src`) and from generic groups. Lets `<a {...home.link}>{home.link}>`
+ *  spread `href`/`target`/`rel` and render the text. */
+function isLinkObject(raw: unknown): raw is { text?: string; url?: string; external?: boolean } {
+	return (
+		typeof raw === "object" &&
+		raw !== null &&
+		!Array.isArray(raw) &&
+		"url" in raw &&
+		"text" in raw &&
+		"external" in raw
+	)
+}
+
+/** Deep-merge `override` onto `base` (override leaves win; objects merge,
+ *  arrays/primitives replace). Used so a locale's leaf-level overrides inherit
+ *  every untouched field — including siblings inside a group. */
+function deepMerge(base: unknown, override: unknown): unknown {
+	if (override === undefined) return base
+	if (
+		base === null ||
+		typeof base !== "object" ||
+		Array.isArray(base) ||
+		override === null ||
+		typeof override !== "object" ||
+		Array.isArray(override)
+	) {
+		return override
+	}
+	const out: Record<string, unknown> = { ...(base as Record<string, unknown>) }
+	for (const k of Object.keys(override as Record<string, unknown>)) {
+		out[k] = deepMerge((base as Record<string, unknown>)[k], (override as Record<string, unknown>)[k])
+	}
+	return out
+}
+
+/**
+ * Compose a localized value from the default-locale `base` and a map of
+ * per-locale override objects: `{ ...base, <loc>: deepMerge(base, override) }`.
+ * The default stays flat at the root; each locale inherits the default then
+ * applies its overrides. Generated by the Vite plugin for localized content.
+ */
+export function __oknoLocalize(
+	base: Record<string, unknown>,
+	overrides: Record<string, Record<string, unknown>>,
+): Record<string, unknown> {
+	const out: Record<string, unknown> = { ...base }
+	for (const loc of Object.keys(overrides)) {
+		out[loc] = deepMerge(base, overrides[loc]) as Record<string, unknown>
+	}
+	return out
+}
+
+/**
+ * Wraps content data in a Proxy that:
+ * - Returns `data-okno` attribute when spread ({...value})
+ * - Returns string value when used in templates ({value})
+ * - Forwards native string/number methods (value.length, value.includes(), etc.)
+ * - Returns nested proxies for group access (value.child)
+ * - Returns empty proxies for non-existing fields
+ * - Supports .on(callback) for reactive change subscriptions
+ */
+export function __oknoWrap(data: unknown, prefix: string, slot?: string): any {
+	const wrapper = { __raw: data, __path: prefix, __slot: slot }
+
+	return new Proxy(wrapper, {
+		get(target, prop) {
+			// Spread reads this to get the attribute value
+			if (prop === "data-okno") return target.__path
+
+			// `{...item.slot}` — the array-membership boundary (which list + index),
+			// distinct from `data-okno` (content identity). Typed only on array items
+			// (so scalar `{...field}` spreads never carry it / collide with HTML attrs);
+			// `slot` is a reserved field key so no content field can shadow it. For a
+			// reference item the content lives at the collection path but its SLOT is the
+			// field array position, so structural edits (reorder/add/remove) hit the right list.
+			if (prop === "slot") return { "data-okno-item": target.__slot ?? target.__path }
+
+			// String coercion for template rendering: {value}
+			if (
+				prop === Symbol.toPrimitive ||
+				prop === "toString" ||
+				prop === "valueOf"
+			) {
+				return () => rawToString(target.__raw, target.__path)
+			}
+
+			// Symbol.iterator — Astro's renderer iterates children to render them.
+			// Yield the string value so {home.title} renders as text.
+			if (prop === Symbol.iterator) {
+				const str = rawToString(target.__raw, target.__path)
+				return function* () {
+					yield str
+				}
+			}
+
+			// Ignore other symbols
+			if (typeof prop === "symbol") return undefined
+
+			// JSON serialization
+			if (prop === "toJSON") return () => target.__raw
+
+			// .on(callback) — subscribe to live edits from the editor
+			if (prop === "on") {
+				return (callback: (value: unknown) => void) => {
+					ensureListener()
+					const path = target.__path
+					if (!listeners.has(path)) listeners.set(path, new Set())
+					listeners.get(path)!.add(callback)
+					// Return unsubscribe function
+					return () => {
+						listeners.get(path)?.delete(callback)
+						if (listeners.get(path)?.size === 0) listeners.delete(path)
+					}
+				}
+			}
+
+			// .locale(code) — re-root reads at a locale's data. The default
+			// locale lives flat at the root; other locales sit under their key
+			// (shaped by the build plugin, with default-locale fallback merged
+			// in). Returns the flat root when the code is the default, absent,
+			// or unset — so `.locale(Astro.currentLocale)` is a safe no-op on
+			// un-localized content. The path stays locale-agnostic so live edits
+			// resolve against the editor's active locale.
+			if (prop === "locale") {
+				return (code?: string | null) => {
+					const raw = target.__raw
+					if (
+						code &&
+						raw !== null &&
+						typeof raw === "object" &&
+						!Array.isArray(raw) &&
+						typeof (raw as Record<string, unknown>)[code] === "object" &&
+						(raw as Record<string, unknown>)[code] !== null
+					) {
+						return __oknoWrap(
+							(raw as Record<string, unknown>)[code],
+							target.__path,
+						)
+					}
+					return __oknoWrap(raw, target.__path)
+				}
+			}
+
+			const raw = target.__raw
+			const childPath = target.__path
+				? `${target.__path}.${String(prop)}`
+				: String(prop)
+
+			// Link object: expose mapped HTML attributes so `<a {...home.link}>`
+			// spreads them (object spread reads values via this Get trap, not via
+			// getOwnPropertyDescriptor). The real fields (url/text/external) stay
+			// reachable by their own names. `target`/`rel` only when external.
+			if (isLinkObject(raw) && typeof prop === "string") {
+				if (prop === "href") return raw.url ?? ""
+				if (prop === "target" && raw.external) return "_blank"
+				if (prop === "rel" && raw.external) return "noopener noreferrer"
+			}
+
+			// For primitive values (string, number, boolean), forward native method/property access
+			// This makes home.title.length, home.title.includes("x"), etc. work
+			if (raw !== null && raw !== undefined && typeof raw !== "object") {
+				const nativeValue = (raw as any)[prop]
+				if (nativeValue !== undefined) {
+					if (typeof nativeValue === "function") {
+						return (...args: unknown[]) =>
+							nativeValue.apply(raw, args)
+					}
+					return nativeValue
+				}
+				// Property doesn't exist on the primitive — return empty proxy
+				return __oknoWrap(null, childPath)
+			}
+
+			// For object values, do nested child access
+			if (
+				raw !== null &&
+				raw !== undefined &&
+				typeof raw === "object" &&
+				!Array.isArray(raw)
+			) {
+				const childValue = (raw as Record<string, unknown>)[String(prop)]
+
+				if (childValue === undefined || childValue === null) {
+					// Non-existing field — return empty proxy
+					return __oknoWrap(null, childPath)
+				}
+
+				// Groups, leaves, arrays (→ a real array of wrapped elements so
+				// `field.map(...)` works and each item carries its own data-okno
+				// path), and resolved-reference markers — see wrapValue.
+				return wrapValue(childValue, childPath)
+			}
+
+			// For null/undefined raw (non-existing parent), return empty proxy
+			return __oknoWrap(null, childPath)
+		},
+
+		// For spread: expose data-okno, plus all keys for file objects (src, alt, width, height, etc.)
+		ownKeys(target) {
+			const raw = target.__raw
+			if (isMediaObject(raw)) {
+				return [...Object.keys(raw), "data-okno"]
+			}
+			if (isLinkObject(raw)) {
+				return raw.external
+					? ["href", "target", "rel", "data-okno"]
+					: ["href", "data-okno"]
+			}
+			return ["data-okno"]
+		},
+
+		getOwnPropertyDescriptor(target, prop) {
+			if (prop === "data-okno") {
+				return {
+					value: target.__path,
+					enumerable: true,
+					configurable: true,
+				}
+			}
+			const raw = target.__raw
+			if (isMediaObject(raw) && typeof prop === "string" && prop in raw) {
+				return {
+					value: raw[prop],
+					enumerable: true,
+					configurable: true,
+				}
+			}
+			// Link's virtual attrs (value comes from the Get trap; this just marks
+			// them enumerable so the spread picks them up).
+			if (isLinkObject(raw) && (prop === "href" || (raw.external && (prop === "target" || prop === "rel")))) {
+				return { value: undefined, enumerable: true, configurable: true }
+			}
+			return undefined
+		},
+
+		has(target, prop) {
+			if (prop === "data-okno") return true
+			if (prop === Symbol.toPrimitive || prop === "toString") return true
+			const raw = target.__raw
+			if (typeof raw === "object" && raw !== null) {
+				return prop in (raw as object)
+			}
+			if (raw !== null && raw !== undefined) {
+				return prop in Object(raw)
+			}
+			return false
+		},
+	})
+}
+
+/** A resolved reference: the build plugin replaces a reference id with this
+ *  marker so the wrapped value's `data-okno` points at the referenced collection
+ *  item (`<collection>.<id>`), not at the field on the parent record — editing a
+ *  referenced item edits the item, not the page that references it. */
+interface OknoRef {
+	__oknoRef: { path: string; data: unknown }
+}
+
+function isOknoRef(value: unknown): value is OknoRef {
+	return (
+		value !== null &&
+		typeof value === "object" &&
+		!Array.isArray(value) &&
+		"__oknoRef" in (value as object)
+	)
+}
+
+/**
+ * Wrap a child value:
+ *  - a resolved-reference marker → wrap its data at the referenced item's path,
+ *    but keep `slot` = the array position (so reorder targets the field's list,
+ *    not the shared collection item);
+ *  - an array → a REAL array of wrapped elements (so `field.map(...)` works and
+ *    every element carries its own `data-okno` path + `slot` boundary);
+ *  - anything else → a normal nested proxy.
+ *
+ * `slot` is the array-membership path (`home.featuredArticles.0`); it equals the
+ * content path for plain/block arrays but differs for resolved references.
+ */
+function wrapValue(value: unknown, fallbackPath: string, slot?: string): any {
+	if (isOknoRef(value)) {
+		const { path, data } = value.__oknoRef
+		return __oknoWrap(data, path, slot ?? path)
+	}
+	if (Array.isArray(value)) {
+		const wrapped = value.map((el, i) => wrapValue(el, `${fallbackPath}.${i}`, `${fallbackPath}.${i}`))
+		// Keep the field API on array fields: `.toJSON()` yields the RAW items, the
+		// supported way to read a `multiple` block array (e.g. okno.build's homepage
+		// `headlines`). The wrapped value is a real array so `.map()`/iteration/spread
+		// keep working; `toJSON` is non-enumerable so it never leaks into those.
+		// Resolved references unwrap to their data so callers get clean raw items.
+		Object.defineProperty(wrapped, "toJSON", {
+			value: () => value.map((el) => (isOknoRef(el) ? el.__oknoRef.data : el)),
+			enumerable: false,
+		})
+		return wrapped
+	}
+	return __oknoWrap(value, fallbackPath, slot)
+}
+
+/**
+ * Replace reference fields (id or id[]) on a raw record with `__oknoRef` markers
+ * carrying the resolved collection item's RAW data + its `<collection>.<id>`
+ * path. Driven by the entry's schema `fields` (emitted by the build plugin);
+ * `collections` is the `okno:collections` namespace. Non-reference fields pass
+ * through untouched. Resolution is one level deep — a referenced item's own
+ * references are not re-resolved (avoids cycles).
+ */
+export function __oknoResolveRefs(
+	raw: unknown,
+	fields: Record<string, any> | undefined,
+	collections: Record<string, any>,
+): unknown {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw) || !fields) return raw
+
+	const out: Record<string, unknown> = { ...(raw as Record<string, unknown>) }
+
+	for (const key of Object.keys(fields)) {
+		const def = fields[key]
+		if (!def || def.type !== "reference" || typeof def.collection !== "string") continue
+
+		const list: any[] =
+			collections?.[def.collection] ?? collections?.[def.collection.replace(/-/g, "_")] ?? []
+
+		const bySlug = new Map<string, any>()
+		for (const it of list) {
+			const r = typeof it?.toJSON === "function" ? it.toJSON() : it
+			if (r && typeof r === "object" && typeof r.slug === "string") bySlug.set(r.slug, it)
+		}
+		const resolve = (id: unknown): OknoRef | null => {
+			if (typeof id !== "string" || !id) return null
+			const item = bySlug.get(id)
+			if (!item) return null
+			const data = typeof item.toJSON === "function" ? item.toJSON() : item
+			return { __oknoRef: { path: `${def.collection}.${id}`, data } }
+		}
+
+		const val = (raw as Record<string, unknown>)[key]
+		out[key] = Array.isArray(val) ? val.map(resolve).filter(Boolean) : resolve(val)
+	}
+
+	return out
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Live STRUCTURAL edits — reorder / remove / insert of array items, reflected
+ * on the page with no save and no reload, animated via the View Transitions API.
+ *
+ * The content channel above (`okno:change`) patches a single field's text/attrs
+ * in place by `data-okno`. This channel handles the orthogonal problem: the
+ * SHAPE of an array changed. The editor dispatches an `okno:structure` event
+ * carrying the list path and the op; we manipulate the served DOM directly.
+ *
+ * Item boundaries are marked by `data-okno-item="<list>.<index>"` (emitted by
+ * `{...item.slot}`). A list may be rendered in several places on one page
+ * (header + footer); we treat each parent that holds direct members of the list
+ * as an independent render location and apply the op to each.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+export interface OknoStructureDetail {
+	/** The array field path, e.g. "home.block" or "home.featuredArticles". */
+	list: string
+	op: "reorder" | "remove" | "insert"
+	/** reorder */
+	from?: number
+	to?: number
+	/** remove / insert — the affected index (insert position). */
+	index?: number
+	/** insert (references only): remap the cloned template's CONTENT paths
+	 *  (`data-okno`) from one collection-item prefix to another, since a
+	 *  reference item's content lives at `<collection>.<slug>`, not under the
+	 *  list. Slot boundaries (`data-okno-item`) are always renumbered by list. */
+	remap?: { from: string; to: string }
+	/** insert: absolute content path → string value, used to fill the cloned
+	 *  item's text leaves (so a new reference shows the linked item's content;
+	 *  block defaults are empty so the clone is just cleared). */
+	values?: Record<string, string>
+}
+
+const ITEM_ATTR = "data-okno-item"
+const CONTENT_ATTR = "data-okno"
+const PREFIX_ATTRS = [CONTENT_ATTR, ITEM_ATTR]
+
+/** A render location: one parent element holding direct members of the list,
+ *  with those member wrappers sorted by their array index. */
+interface ItemGroup {
+	parent: Element
+	wrappers: HTMLElement[]
+}
+
+/** Rewrite path attributes on `el` and its descendants whose value equals
+ *  `oldPrefix` or sits under it (`oldPrefix.` …) — swapping that prefix for
+ *  `newPrefix`. This is the renumbering primitive: it shifts an item's own
+ *  `data-okno-item` AND every descendant `data-okno`/`data-okno-item` that
+ *  begins with the same prefix (nested arrays included). For a reference item
+ *  the content `data-okno` (`articles.<slug>…`) doesn't share the list prefix,
+ *  so it's correctly left untouched when renumbering positions. */
+function rewritePrefix(
+	el: Element,
+	oldPrefix: string,
+	newPrefix: string,
+	attrs: string[] = PREFIX_ATTRS,
+): void {
+	if (oldPrefix === newPrefix) return
+	const apply = (node: Element) => {
+		for (const attr of attrs) {
+			const v = node.getAttribute(attr)
+			if (v == null) continue
+			if (v === oldPrefix) node.setAttribute(attr, newPrefix)
+			else if (v.startsWith(oldPrefix + ".")) node.setAttribute(attr, newPrefix + v.slice(oldPrefix.length))
+		}
+	}
+	apply(el)
+	for (const attr of attrs) el.querySelectorAll(`[${attr}]`).forEach(apply)
+}
+
+/** Collect the render locations of a list: every element whose `data-okno-item`
+ *  is a DIRECT member (`<list>.<integer>`, no deeper segment), grouped by parent
+ *  and sorted by index. Deeper nested members of a different sub-array are
+ *  excluded by the strict `^<list>\.\d+$` shape. */
+function collectGroups(list: string): ItemGroup[] {
+	if (typeof document === "undefined") return []
+	const re = new RegExp(`^${list.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\.(\\d+)$`)
+	const byParent = new Map<Element, HTMLElement[]>()
+	document.querySelectorAll(`[${ITEM_ATTR}]`).forEach((el) => {
+		const attr = el.getAttribute(ITEM_ATTR)
+		if (!attr || !re.test(attr) || !el.parentElement || !(el instanceof HTMLElement)) return
+		const arr = byParent.get(el.parentElement) ?? []
+		arr.push(el)
+		byParent.set(el.parentElement, arr)
+	})
+	const indexOf = (el: HTMLElement) => Number(el.getAttribute(ITEM_ATTR)!.match(re)![1])
+	return [...byParent.entries()].map(([parent, wrappers]) => ({
+		parent,
+		wrappers: wrappers.sort((a, b) => indexOf(a) - indexOf(b)),
+	}))
+}
+
+/** Clear visible text in a cloned item's leaf content nodes (a fresh item has
+ *  no content yet). Only touches `data-okno` leaves with no element children —
+ *  images / link spreads / richtext are left as-is (best-effort; they settle on
+ *  the next save+reload). */
+function clearLeaves(root: Element): void {
+	root.querySelectorAll(`[${CONTENT_ATTR}]`).forEach((el) => {
+		if (el.children.length === 0) el.textContent = ""
+	})
+}
+
+/** Fill a cloned item's text leaves from absolute-path → value pairs. */
+function fillLeaves(root: Element, values: Record<string, string>): void {
+	root.querySelectorAll(`[${CONTENT_ATTR}]`).forEach((el) => {
+		const path = el.getAttribute(CONTENT_ATTR)
+		if (path && path in values && el.children.length === 0) el.textContent = values[path] ?? ""
+	})
+}
+
+function prefersReducedMotion(): boolean {
+	return (
+		typeof window !== "undefined" &&
+		typeof window.matchMedia === "function" &&
+		window.matchMedia("(prefers-reduced-motion: reduce)").matches
+	)
+}
+
+/** Run a DOM mutation inside a View Transition when supported (so moved/added/
+ *  removed wrappers tween), falling back to a plain synchronous call. Returns a
+ *  promise that settles once any animation finishes — used to clear the
+ *  temporary `view-transition-name`s afterwards. */
+function withTransition(mutate: () => void): Promise<void> {
+	const doc = document as any
+	if (typeof doc.startViewTransition !== "function" || prefersReducedMotion()) {
+		mutate()
+		return Promise.resolve()
+	}
+	return doc.startViewTransition(mutate).finished.catch(() => {})
+}
+
+let vtSeq = 0
+
+/**
+ * Apply a structural op to the live DOM. Attached to `okno:structure` by
+ * `__oknoInitStructure()`. The editor calls `updateField` for its optimistic
+ * state in the same tick; this keeps the rendered page in sync without a reload.
+ */
+export function __oknoApplyStructure(detail: OknoStructureDetail): void {
+	if (typeof document === "undefined" || !detail?.list || !detail.op) return
+	const { list, op } = detail
+	const groups = collectGroups(list)
+
+	// Insert with no rendered item to clone — an empty list, OR a list that isn't
+	// on the page in view (e.g. a block field the current page doesn't render).
+	// Nothing to live-insert: no-op. The item is already in the editor's optimistic
+	// state and renders once saved + rebuilt. We must NOT reload — the add isn't
+	// persisted yet, so a reload would drop it (and needlessly reboot the editor).
+	if (op === "insert" && groups.every((g) => g.wrappers.length === 0)) return
+	if (groups.length === 0) return
+
+	// Tag the existing wrappers with a unique view-transition-name BEFORE the
+	// transition captures the old snapshot, so moves/removals animate. The clone
+	// (added during the mutation) gets its own name inside `mutate`.
+	const tagged: HTMLElement[] = []
+	const tag = (el: HTMLElement) => {
+		el.style.viewTransitionName = `okno-vt-${++vtSeq}`
+		tagged.push(el)
+	}
+	for (const g of groups) for (const w of g.wrappers) tag(w)
+
+	// Flag the document for the duration so the editor's CSS can scope the
+	// view-transition easing to OUR structural transitions only (not any
+	// page-nav transitions the host site runs). See `:root.okno-vt-active` in
+	// the editor global styles.
+	const docEl = document.documentElement
+	docEl.classList.add("okno-vt-active")
+
+	// Keep the editor above the animation. View-transition snapshots render in the
+	// browser TOP LAYER (above every z-index), so the moving page items would
+	// otherwise sweep OVER the editor window. Give the editor host its own group
+	// (`view-transition-name: okno-editor`) so it's captured and — being the last
+	// child of <body> — composited on top. The host is normally a 0-size box (its
+	// UI is `position:fixed` inside the shadow), which would snapshot empty, so we
+	// give it a real viewport box for the transition only and restore it after — no
+	// permanent layout/pointer-events change. The editor doesn't move, so its
+	// crossfade is suppressed in CSS (`::view-transition-*(okno-editor)`); it shows
+	// a frozen snapshot, so the temporary box never actually paints. Tradeoff: its
+	// backdrop-filter blur can't sample across snapshot groups, so the glass goes
+	// flat for the transition's duration (a View Transitions limitation).
+	const editorHost = document.getElementById("okno-shadow-root")
+	const prevHostCss = editorHost instanceof HTMLElement ? editorHost.style.cssText : null
+	if (editorHost instanceof HTMLElement) {
+		editorHost.style.cssText = `${prevHostCss};position:fixed;inset:0;pointer-events:none;view-transition-name:okno-editor`
+	}
+
+	const mutate = () => {
+		for (const g of groups) {
+			if (op === "reorder") applyReorder(g, list, detail.from!, detail.to!)
+			else if (op === "remove") applyRemove(g, list, detail.index!)
+			else if (op === "insert") applyInsert(g, list, detail, tag)
+		}
+	}
+
+	withTransition(mutate).finally(() => {
+		for (const w of tagged) w.style.viewTransitionName = ""
+		docEl.classList.remove("okno-vt-active")
+		if (editorHost instanceof HTMLElement && prevHostCss !== null) editorHost.style.cssText = prevHostCss
+	})
+}
+
+function applyReorder(g: ItemGroup, list: string, from: number, to: number): void {
+	const w = g.wrappers
+	const n = w.length
+	if (from < 0 || from >= n || to < 0 || to >= n || from === to) return
+	const order = w.slice()
+	const [moved] = order.splice(from, 1)
+	order.splice(to, 0, moved!)
+	// Capture current prefixes, then renumber each wrapper to its new index.
+	const olds = order.map((el) => el.getAttribute(ITEM_ATTR)!)
+	order.forEach((el, i) => rewritePrefix(el, olds[i]!, `${list}.${i}`))
+	// Reinsert in the new order, anchored to whatever followed the list (so the
+	// block keeps its place relative to surrounding, non-item siblings).
+	const anchor = w[n - 1]!.nextSibling
+	for (const el of order) g.parent.insertBefore(el, anchor)
+}
+
+function applyRemove(g: ItemGroup, list: string, index: number): void {
+	const w = g.wrappers
+	if (index < 0 || index >= w.length) return
+	w[index]!.remove()
+	for (let j = index + 1; j < w.length; j++) rewritePrefix(w[j]!, `${list}.${j}`, `${list}.${j - 1}`)
+}
+
+function applyInsert(
+	g: ItemGroup,
+	list: string,
+	detail: OknoStructureDetail,
+	tag: (el: HTMLElement) => void,
+): void {
+	const w = g.wrappers
+	const n = w.length
+	if (n === 0) return // empty handled by the reload guard above
+	const at = Math.max(0, Math.min(detail.index ?? n, n))
+
+	// Clone the item nearest the insertion point as a template (capture its
+	// prefix BEFORE we renumber the live siblings).
+	const tplIdx = at < n ? at : n - 1
+	const tplPrefix = w[tplIdx]!.getAttribute(ITEM_ATTR)!
+	const clone = w[tplIdx]!.cloneNode(true) as HTMLElement
+
+	// Shift existing members at/after the insertion point up by one (descending
+	// so a freshly-written prefix is never re-read as a source).
+	for (let j = n - 1; j >= at; j--) rewritePrefix(w[j]!, `${list}.${j}`, `${list}.${j + 1}`)
+
+	// Point the clone at the new index, then (references) remap its content paths.
+	rewritePrefix(clone, tplPrefix, `${list}.${at}`)
+	if (detail.remap) rewritePrefix(clone, detail.remap.from, detail.remap.to, [CONTENT_ATTR])
+
+	if (detail.values) fillLeaves(clone, detail.values)
+	else clearLeaves(clone)
+
+	clone.style.viewTransitionName = ""
+	tag(clone)
+	const anchor = at < n ? w[at]! : w[n - 1]!.nextSibling
+	g.parent.insertBefore(clone, anchor)
+}
+
+let structureListening = false
+
+/** Attach the `okno:structure` listener once. Called by the editor (which is
+ *  the reliable client-side presence) on scan; safe to call repeatedly. */
+export function __oknoInitStructure(): void {
+	const g = globalThis as any
+	if (structureListening || typeof g.document === "undefined") return
+	structureListening = true
+	g.document.addEventListener("okno:structure", (e: any) => __oknoApplyStructure(e.detail))
+}