@unitninety/site-kit 0.0.0-stage → 1.6.2

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @unitninety/site-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The library a UnitNinety site is built on. It reads the site's content from UnitNinety, renders its editable parts, and answers the platform at `/api/u90`, so the site's clients can edit it in UnitNinety's dashboard.
+
+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.1 --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).
+
+### Immediate collection-list previews
+
+Render a query's `EntriesRead` with `Entries` from `@unitninety/site-kit/components` when its
+cards should reorder and disappear immediately in Canvas. Pass the complete value, including
+its draft `$path`, and render one card per entry:
+
+```tsx
+<Entries value={projects} className="project-grid" empty={<p>No projects yet.</p>}>
+  {entry => <ProjectCard entry={entry} />}
+</Entries>
+```
+
+The card renderer runs on the server. In draft mode React owns the keyed cards and preserves
+pending order/removal through slow refreshes; rejected saves reconcile to the server result.
+Published output is an ordinary div and server-rendered cards. Newly added entries whose markup
+is not already present appear when the save's server refresh arrives. Query results rendered
+with a plain `.map()` still work, but wait for that refresh to change their order or membership.

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@unitninety/site-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.6.2",
+  "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",
+    "./features/server": "./src/features/server/index.ts",
+    "./features/contracts": "./src/features/contracts/index.ts",
+    "./preview-lock": "./src/preview-lock/index.ts",
+    "./preview-lock/server": "./src/preview-lock/server.ts",
+    "./preview-lock/screen": "./src/preview-lock/screen.tsx",
+    "./components": "./src/components/index.ts",
+    "./bridge": "./src/bridge/index.ts",
+    "./testing": "./src/testing/index.ts",
+    "./redirects": "./src/redirects/index.ts",
+    "./redirects/config": {
+      "types": "./src/redirects/config.d.mts",
+      "default": "./src/redirects/config.mjs"
+    },
+    "./elements": "./src/elements/index.ts",
+    "./languages": "./src/languages/index.ts",
+    "./languages/config": {
+      "types": "./src/languages/config.d.mts",
+      "default": "./src/languages/config.mjs"
+    },
+    "./legacy": "./src/legacy/index.ts",
+    "./legacy/bridge": "./src/legacy/bridge.tsx",
+    "./legacy/cli": "./src/legacy/cli.mjs",
+    "./legacy/draft": "./src/legacy/draft.tsx",
+    "./legacy/shape": "./src/legacy/shape.ts",
+    "./legacy/contract": "./src/legacy/contract.ts",
+    "./legacy/redirects": "./src/legacy/redirects.ts",
+    "./legacy/language-switcher": "./src/legacy/language-switcher.tsx",
+    "./features": "./src/features/client/index.ts",
+    "./features/styles.css": "./src/features/client/styles.css",
+    "./test-preview/server": "./src/test-preview/server.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "!src/**/*.test.mjs",
+    "!src/elements/fixtures",
+    "!src/elements/harness.ts",
+    "!src/site/fixtures",
+    "!src/test-preview/fixtures.ts",
+    "!src/features/consent/test-fixtures.ts"
+  ],
+  "license": "UNLICENSED",
+  "homepage": "https://unitninety.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UnitNinety/unitninety-run.git",
+    "directory": "packages/site-kit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "next": ">=16.3.8 <17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test 'src/**/*.test.ts' 'src/**/*.test.tsx' src/test-preview/protocol.test.mjs"
+  }
+}

package/src/bridge/DraftBlocks.tsx

@@ -0,0 +1,70 @@
+'use client'
+
+import { Fragment, useCallback, useLayoutEffect, useRef, useState, type ReactNode } from 'react'
+
+import { registry } from './registry'
+import { needsEmbedReload, preserveBlockMoves } from './preserveBlockMoves'
+import { PreviewCommitBoundary } from './PreviewCommitBoundary'
+
+type Item = { id: string; path?: string; content: ReactNode }
+type Move = { path: string; before: string | null }
+
+const moved = (items: Item[], { path, before }: Move): Item[] => {
+  const item = items.find((entry) => entry.path === path)
+  if (!item || before === path) return items
+  const next = items.filter((entry) => entry !== item)
+  const at = before === null ? next.length : next.findIndex((entry) => entry.path === before)
+  if (at < 0) return items
+  next.splice(at, 0, item)
+  return next
+}
+
+/**
+ * React owns draft block order, including the optimistic order. Moving its DOM nodes outside
+ * React required undoing the drag before a refresh, visibly restoring the old order while the
+ * server answered. The next server render reconciles these same keyed children instead.
+ * Only draft-marked zones use this component; published pages keep their server-only renderer.
+ */
+export function DraftBlocks({ items }: { items: Item[] }) {
+  const host = useRef<HTMLDivElement | null>(null)
+  const reload = useRef(false)
+  // A stable ref keeps the adapter installed through React's mutation phase.
+  const attachHost = useCallback((node: HTMLDivElement | null) => {
+    host.current = node
+    return preserveBlockMoves(node)
+  }, [])
+  const [shown, setShown] = useState({ source: items, items, order: null as string[] | null })
+  // Keep the desired order, not a log to replay: the server response may already
+  // contain later moves, and applying a sequence twice is not generally idempotent.
+  const ranks = new Map(shown.order?.map((id, index) => [id, index]))
+  const known = items.filter((item) => ranks.has(item.id)).sort((a, b) => ranks.get(a.id)! - ranks.get(b.id)!)
+  let knownIndex = 0
+  const current = shown.source === items ? shown.items : shown.order === null ? items
+    : items.map((item) => ranks.has(item.id) ? known[knownIndex++]! : item)
+  if (shown.source !== items) setShown({ ...shown, source: items, items: current })
+
+  useLayoutEffect(() => {
+    const handler = {
+      document,
+      needsReload: () => reload.current,
+      beforeRefresh: () => setShown((value) => ({ ...value, order: null })),
+      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
+        if (host.current && needsEmbedReload(host.current)) {
+          reload.current = true
+          return true
+        }
+        setShown((value) => {
+          const next = moved(value.items, { path, before })
+          return { ...value, items: next, order: next.map((item) => item.id) }
+        })
+        return true
+      },
+    }
+    registry.blockOrders.add(handler)
+    return () => { registry.blockOrders.delete(handler) }
+  }, [current])
+
+  return <PreviewCommitBoundary source={items}><div data-u90-draft-zone="" style={{ display: 'contents' }} ref={attachHost}>{current.map((item) => <Fragment key={item.id}>{item.content}</Fragment>)}</div></PreviewCommitBoundary>
+}

package/src/bridge/DraftEntries.tsx

@@ -0,0 +1,41 @@
+'use client'
+
+import { Fragment, useLayoutEffect, useRef, useState, type HTMLAttributes, type ReactNode } from 'react'
+import { PreviewCommitBoundary } from './PreviewCommitBoundary'
+import { registry } from './registry'
+
+export type EntryItem = { id: string; content: ReactNode }
+export type EntryPicks = { order: string[]; exclude: string[]; pin: string[] }
+
+function picked(items: EntryItem[], picks: EntryPicks, pins: readonly string[]): EntryItem[] {
+  const excluded = new Set([...picks.exclude, ...pins.filter(id => !picks.pin.includes(id))])
+  const ranks = new Map(picks.order.map((id, index) => [id, index]))
+  return items.filter(item => !excluded.has(item.id)).sort((a, b) =>
+    (ranks.get(a.id) ?? Infinity) - (ranks.get(b.id) ?? Infinity))
+}
+
+/** React owns the cards so pending picks survive a slow server refresh without a DOM undo flash. */
+export function DraftEntries({ path, items, pins, empty, ...props }: HTMLAttributes<HTMLDivElement> & { path: string; items: EntryItem[]; pins: string[]; empty?: ReactNode }) {
+  const host = useRef<HTMLDivElement>(null)
+  const [shown, setShown] = useState({ source: items, pins, items, picks: null as EntryPicks | null })
+  const current = shown.source === items ? shown.items : shown.picks === null ? items : picked(items, shown.picks, pins)
+  if (shown.source !== items) setShown({ ...shown, source: items, pins, items: current })
+
+  useLayoutEffect(() => {
+    const handler = {
+      document: host.current!.ownerDocument,
+      // Clear only the picks included when this refresh starts, retaining the visible cards
+      // until its response arrives. A subsequent edit remains active across that older response.
+      beforeRefresh: () => setShown(value => ({ ...value, picks: null })),
+      pick: (at: string, picks: EntryPicks) => {
+        if (at !== path) return false
+        setShown(value => ({ ...value, items: picked(value.source, picks, value.pins), picks }))
+        return true
+      },
+    }
+    registry.entryLists.add(handler)
+    return () => { registry.entryLists.delete(handler) }
+  }, [path])
+
+  return <PreviewCommitBoundary source={items}><div {...props} data-u90-field={path} ref={host}>{current.length ? current.map(item => <Fragment key={item.id}>{item.content}</Fragment>) : empty}</div></PreviewCommitBoundary>
+}

package/src/bridge/PreviewCommitBoundary.tsx

@@ -0,0 +1,19 @@
+'use client'
+
+import { Component, type ReactNode } from 'react'
+import { registry } from './registry'
+
+/** Rebase imperative field previews around the actual React mutation, not around
+ * the network request. A persistent Next layout need not render when its routed
+ * subtree changes, so each draft zone places this boundary around its server items. */
+export class PreviewCommitBoundary extends Component<{ source: unknown; children: ReactNode }> {
+  getSnapshotBeforeUpdate(previous: Readonly<{ source: unknown; children: ReactNode }>) {
+    return previous.source === this.props.source ? null : registry.current?.prepareCommit() ?? null
+  }
+
+  componentDidUpdate(_previous: unknown, _state: unknown, replay: null | (() => void)) {
+    replay?.()
+  }
+
+  render() { return this.props.children }
+}

package/src/bridge/U90Bridge.tsx

@@ -0,0 +1,54 @@
+import { nextAdapters, type NextAdapters } from '../server/adapters'
+import { createTestPreviewRuntime, type TestPreviewContext } from '../test-preview/runtime'
+import { resolveBridgePreview } from '../test-preview/bridge'
+import { Suspense, type ReactNode } from 'react'
+
+import { EditingProvider } from './hooks'
+
+/**
+ * `draftMode()` is a request-time API: under Cache Components, reading it must happen behind a
+ * `Suspense` boundary rather than at a layout's top level (a top-level `await` there would hold
+ * `children` — the whole segment — behind the request on every render). `Gate` is that boundary's
+ * one child, so the read is pushed down into the smallest component that needs it, per Next's
+ * documented pattern for authentication/session reads under Cache Components.
+ *
+ * `EditingProvider` renders `children` itself (see `hooks.tsx`) — it has to, since a Context
+ * provider must be an ancestor of the components calling `useEditing()`/`useReveal()`, which
+ * means `children` sits inside this Suspense boundary too. In practice this costs nothing visible:
+ * `draftMode()` reads a cookie already on the request, no I/O, so `Gate` resolves in the same tick
+ * Ordinary visitors perform no I/O here. Test previews additionally verify their session with the
+ * source trust response; pass `u90.testPreview` to share the connection's bounded trust cache.
+ */
+type BridgeProps = { platformOrigin: string; children: ReactNode; draft: NextAdapters['draft']; testPreview?: () => Promise<TestPreviewContext | null> }
+async function Gate({ platformOrigin, children, draft, testPreview }: BridgeProps) {
+  const runtime = createTestPreviewRuntime({ env: { PLATFORM_URL: process.env.PLATFORM_URL, PAYLOAD_API_KEY: process.env.PAYLOAD_API_KEY, SITE_URL: process.env.SITE_URL } })
+  const props = await resolveBridgePreview({ platformOrigin, draft, resolve: testPreview ? () => testPreview() : token => runtime.resolve(token) })
+  return <EditingProvider {...props}>{children}</EditingProvider>
+}
+
+/**
+ * Wraps `{children}` in `app/layout.tsx` (`<U90Bridge>{children}</U90Bridge>`): outside draft, or
+ * with no `platformOrigin` configured, this renders `children` through the provider but through the async
+ * `Gate` and its `EditingProvider` — `useEditing()` still works everywhere, always returning
+ * `{ editing: false, selected: null }` in that case. Only when `draftMode()` is enabled and a
+ * `platformOrigin` is known does the client bridge (`BridgeClient`, lazily imported from
+ * `EditingProvider`) actually mount.
+ *
+ * `platformOrigin` defaults to `PLATFORM_URL`'s origin (empty when that env var is unset, which
+ * `Gate` reads as "never enable the bridge" — a draft page with no platform to talk to is just a
+ * normal render).
+ */
+export function U90Bridge({
+  children,
+  draft = nextAdapters.draft,
+  testPreview,
+  platformOrigin = process.env.PLATFORM_URL ? new URL(process.env.PLATFORM_URL).origin : '',
+}: {
+  children: ReactNode
+  platformOrigin?: string
+  draft?: NextAdapters['draft']
+  /** Pass u90.testPreview to share its configured connection and injected adapters. */
+  testPreview?: () => Promise<TestPreviewContext | null>
+}) {
+  return <Suspense fallback={null}><Gate platformOrigin={platformOrigin} draft={draft} testPreview={testPreview}>{children}</Gate></Suspense>
+}

package/src/bridge/caret.ts

@@ -0,0 +1,317 @@
+/**
+ * Which marked elements take a caret, and where the caret goes.
+ *
+ * Split out of `bridge.tsx` for two reasons. It is the only part of the editing behaviour
+ * that is pure DOM — no React, no message protocol, no closure over the bridge's state — so
+ * it can be loaded and driven on its own, which is what `verify:caret` does: it runs these
+ * exact functions in a real browser against a real layout, rather than a transcription of
+ * them that could drift. And `bridge.tsx` was over a thousand lines.
+ *
+ * Ported from `legacy/caret.ts`, with one change throughout: v4 has no standalone `RICH_ATTR`
+ * boolean attribute or `SECTION_ATTR` — a field is `data-u90-field`, its edit kind (when it takes
+ * a caret at all) is `data-u90-edit="text" | "rich"`, and a block wrapper is `data-u90-block`
+ * rather than a digit-keyed `data-u90-section`. `FIELD_ATTR` is inlined below rather than
+ * imported from `./shape` (this v1 package has no `shape.ts`); every other line — the exported
+ * function bodies, the ordering, the comments — is unchanged from the legacy source.
+ */
+
+/** The v4 spelling of the legacy `FIELD_ATTR` (`'data-u90-field'`), inlined rather than imported. */
+const FIELD_ATTR = 'data-u90-field'
+
+/**
+ * What an annotated element must not contain if it is to be typed into.
+ *
+ * A marked element holding an image or a video is a media field or a card, not words: its
+ * value is an upload id, and the caret has no business there. A nested control or link is
+ * excluded for a different reason — its own text is a separate field, or markup a plain
+ * string cannot round-trip, so editing the parent as one blob would flatten it.
+ *
+ * **`svg` is deliberately absent.** Every button on these sites is `<a>Contact Us<svg/></a>`
+ * — the label and its chevron — and excluding icons would have made the most obviously
+ * editable thing on the page the one thing you could not edit. `innerText` ignores an svg's
+ * contents, so the value is the words alone; and if a client deletes the icon while typing,
+ * the re-render on blur puts it straight back, because the icon was never theirs to store.
+ *
+ * The check is on *descendants* — an `<a>` that is itself the marked element is fine.
+ */
+export const NON_TEXT = 'img, picture, video, canvas, iframe, input, textarea, select, button, a'
+
+/**
+ * The tags that are a picture rather than words — a deliberate *subset* of `NON_TEXT`.
+ *
+ * Two lists rather than one, and the difference is `a` and `button`. `NON_TEXT` answers "may
+ * this element *contain* something untypable", and a marked button label is both a control and
+ * a text leaf: with navigation off it takes a caret, which is how a client edits a button's
+ * words at all. Excluding every non-text tag from editability would therefore make every
+ * caption on every button uneditable in place — a far worse bug than the one this fixes.
+ *
+ * This list answers a different question: "*is* this element a picture". `NON_TEXT` could never
+ * answer it, because it is only ever asked about descendants — `querySelector`, `:has()` — and
+ * an `<img>` contains no `img`. So a marked image satisfied every editable-leaf test and
+ * offered an I-beam over a photograph.
+ */
+export const MEDIA = 'img, picture, video, canvas, iframe'
+
+/**
+ * A marked element that is itself a picture.
+ *
+ * Keyed on the element's own tag rather than on what it contains, because the two spellings a
+ * site uses want different treatment: a marker *on* the image needs its affordance drawn inside
+ * itself, while a marker on a wrapper is normally the clipping frame and its outline is already
+ * visible outside it.
+ */
+export const MEDIA_SELECTOR = `[${FIELD_ATTR}]:is(${MEDIA})`
+
+/**
+ * Whether this annotated element is a leaf holding text, and so directly editable.
+ *
+ * Leaf means it contains no other annotated element. A container — a card marked as a
+ * whole, a section wrapping four marked children — would otherwise become one editable
+ * blob whose text belongs to several fields at once, and the first keystroke would write
+ * all of them into one.
+ *
+ * **A rich field is accepted here early**, ahead of the nested-marker and `NON_TEXT`
+ * clauses below, and that ordering is the point: a real document contains `<a>` and `<ul>`,
+ * and both of those clauses exist to stop an *ordinary* field being edited as one blob —
+ * applied to a rich field they would reject it for exactly the structure it is allowed to
+ * hold. The requirement was never "a rich field must not be edited in place"; a client
+ * choosing to type into their own heading is the same client choosing to type into their
+ * own paragraph. The requirement is "a rich field must never be read back as plain words",
+ * and that guarantee is the bridge's job — see `createBridge`'s `valueOf`, keyed on the same
+ * `data-u90-edit="rich"` attribute — not this function's.
+ *
+ * The `MEDIA` clause still runs unconditionally, ahead of the rich check: a marker on an
+ * image is a picture whatever else it carries, and the caret has no business there.
+ *
+ * v4 change: the legacy `element.hasAttribute(RICH_ATTR)` (a standalone boolean attribute)
+ * becomes `element.getAttribute('data-u90-edit') === 'rich'`, since v4 has one edit-kind
+ * attribute rather than a separate rich marker.
+ */
+export const isEditableLeaf = (element: HTMLElement): boolean => {
+  if (element.matches(MEDIA)) return false
+  if (element.getAttribute('data-u90-edit') === 'rich') return Boolean(element.textContent?.trim())
+
+  return (
+    !element.querySelector(`[${FIELD_ATTR}]`) &&
+    !element.querySelector(NON_TEXT) &&
+    Boolean(element.textContent?.trim())
+  )
+}
+
+/**
+ * The CSS spelling of `isEditableLeaf`, for the hover affordance.
+ *
+ * Built from the same constants so the I-beam and the behaviour cannot disagree about what
+ * is typable. `:is([data-u90-edit="rich"], …)` is the OR that mirrors the early return above: a
+ * rich field takes the I-beam without also having to clear the nested-marker and `NON_TEXT`
+ * clauses, which exist to protect an ordinary field and would otherwise disqualify a real
+ * document for the very links and lists it is allowed to contain.
+ *
+ * `:not(:is(${MEDIA}))` still runs unconditionally, outside that `:is()` — a marked image is
+ * a picture, rich or not, and the caret has no business there either.
+ *
+ * The one clause CSS still cannot express is "and it has some text in it" — an empty marked
+ * element therefore offers an I-beam and does nothing when clicked, which is the least
+ * interesting way for the two to fall out of step and beats making every site component
+ * carry a class.
+ *
+ * v4 change: `[${RICH_ATTR}]` (legacy's presence selector for the standalone rich attribute)
+ * becomes the value selector `[data-u90-edit="rich"]`.
+ */
+export const EDITABLE_LEAF_SELECTOR = `[${FIELD_ATTR}]:not(:is(${MEDIA})):is([data-u90-edit="rich"], :not(:has([${FIELD_ATTR}])):not(:has(${NON_TEXT})))`
+
+/**
+ * A collapsed range at a viewport point, across both spellings of the same API.
+ *
+ * `caretPositionFromPoint` is the standard one and what Firefox has always had;
+ * `caretRangeFromPoint` is WebKit's older name for it, still what Safari ships. Chromium
+ * answers to both. Neither is guaranteed, hence the null.
+ */
+export const caretFromPoint = (x: number, y: number): null | Range => {
+  const doc = document as Document & {
+    caretPositionFromPoint?: (x: number, y: number) => null | { offset: number; offsetNode: Node }
+    caretRangeFromPoint?: (x: number, y: number) => null | Range
+  }
+
+  if (typeof doc.caretPositionFromPoint === 'function') {
+    const position = doc.caretPositionFromPoint(x, y)
+    if (!position) return null
+    const range = document.createRange()
+    range.setStart(position.offsetNode, position.offset)
+    range.collapse(true)
+    return range
+  }
+
+  if (typeof doc.caretRangeFromPoint === 'function') {
+    const range = doc.caretRangeFromPoint(x, y)
+    range?.collapse(true)
+    return range
+  }
+
+  return null
+}
+
+/**
+ * Where the caret should go for a click at this point — resolved, not yet applied.
+ *
+ * ## Call this *before* making the element editable
+ *
+ * The split into resolve-then-apply is the whole point of this pair, and it is not
+ * stylistic. Both inputs it reads are changed by `contenteditable`:
+ *
+ *  - The point lookup. Measured on Chromium against `<a>Contact Us<svg/></a>` laid out as
+ *    `inline-flex`: with the element inert, x-positions across the label resolve to text
+ *    offsets 9, 12, 13 as you would expect. Set `contenteditable` first and every one of
+ *    them comes back as offset 0 instead. The caret then lands at the front of the label
+ *    however carefully the client aimed — which was the original bug wearing a new hat.
+ *  - Any selection the browser has already made. `focus()` on a freshly editable element
+ *    can collapse it, and a double-click's word selection is exactly that.
+ *
+ * So: resolve here, make the element editable, then `applyCaret`. Both call sites in
+ * `createBridge`'s `onClick` do that in that order, and it is why they hold a `Range` across
+ * the two.
+ *
+ * An existing run of selected text wins over the point. A press-and-drag across three words
+ * *is* a selection and the click ending it must not collapse it to a caret; the same clause
+ * is what keeps a double-click meaning "replace this word".
+ */
+export const caretTargetIn = (element: HTMLElement, x: number, y: number): Range => {
+  const selection = window.getSelection()
+
+  if (selection && !selection.isCollapsed && selection.rangeCount > 0) {
+    const existing = selection.getRangeAt(0)
+    // Cloned: the live range would be mutated by the focus that happens in between.
+    if (element.contains(existing.commonAncestorContainer)) return existing.cloneRange()
+  }
+
+  const fromPoint = caretFromPoint(x, y)
+  return fromPoint && landsInText(element, fromPoint) ? fromPoint : endOf(element)
+}
+
+/** Apply a range resolved by `caretTargetIn`, after the element has been made editable. */
+export const applyCaret = (range: Range): void => {
+  const selection = window.getSelection()
+  if (!selection) return
+  selection.removeAllRanges()
+  selection.addRange(range)
+}
+
+/**
+ * Whether a point lookup found somewhere a caret can actually sit.
+ *
+ * Three things have to hold, and the third is why this is a function rather than a
+ * `contains` call. Every button on these sites is `<a>Contact Us<svg/></a>`, and clicking
+ * the chevron resolves to a `path` node — which *is* inside the marked element, so a
+ * containment check alone accepts it and the caret is placed inside the icon. Typing then
+ * goes nowhere the client can see. The svg check is belt-and-braces on top of the text-node
+ * one: an `<svg><text>` would satisfy both otherwise.
+ *
+ * Anything rejected falls back to the end of the words, which for a button label clicked on
+ * its icon is where you wanted the caret anyway.
+ */
+const landsInText = (element: HTMLElement, range: Range): boolean => {
+  const container = range.startContainer
+  if (container.nodeType !== Node.TEXT_NODE) return false
+  if (!element.contains(container)) return false
+  return !container.parentElement?.closest('svg')
+}
+
+/**
+ * A collapsed range after the element's last visible character.
+ *
+ * **Not `selectNodeContents` + `collapse(false)`**, which is the obvious spelling and is
+ * wrong here. That produces a position anchored to the *element* just past its last child,
+ * and for `<a>Contact Us<svg/> </a>` the last child is collapsible whitespace after an icon
+ * — no visible caret position at all. Chromium normalises it, and measurably normalises it
+ * to the *front* of the element: typing after clicking the chevron inserted at the start of
+ * the label, which is the exact failure the fallback exists to avoid.
+ *
+ * So it anchors to the last text node that actually holds words, at the end of those words
+ * rather than the end of the node — trailing whitespace inside a text node is no better a
+ * caret position than trailing whitespace between them.
+ */
+const endOf = (element: HTMLElement): Range => {
+  const range = document.createRange()
+  const last = lastWordsIn(element)
+
+  if (!last) {
+    // No text at all. `isEditableLeaf` rules this out for the click path; a direct caller
+    // gets the old behaviour, which is the only thing available.
+    range.selectNodeContents(element)
+    range.collapse(false)
+    return range
+  }
+
+  range.setStart(last, (last.textContent ?? '').replace(/\s+$/, '').length)
+  range.collapse(true)
+  return range
+}
+
+/** The last text node holding something other than whitespace, icons excluded. */
+const lastWordsIn = (element: HTMLElement): null | Text => {
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, {
+    acceptNode: (node) =>
+      node.textContent?.trim() && !node.parentElement?.closest('svg')
+        ? NodeFilter.FILTER_ACCEPT
+        : NodeFilter.FILTER_REJECT,
+  })
+
+  let last: null | Text = null
+  while (walker.nextNode()) last = walker.currentNode as Text
+  return last
+}
+
+/**
+ * Formatting tag → the mark name `u90:caret`'s `marks` reports it as (`protocol.ts`). Named to
+ * match `lexicalDom.ts`'s own `MARK_BITS` naming (`bold`, `italic`, `underline`, `strikethrough`,
+ * `code`) rather than the tags themselves, since both spellings a browser inserts (`strong`/`b`,
+ * `em`/`i`) collapse to the one mark the Canvas's toolbar highlights; `a` reports as `link`.
+ */
+const MARK_TAGS: Record<string, string> = {
+  a: 'link',
+  b: 'bold',
+  code: 'code',
+  em: 'italic',
+  i: 'italic',
+  s: 'strikethrough',
+  strong: 'bold',
+  u: 'underline',
+}
+
+/** Block tag → the `u90:caret`'s `block` name (`protocol.ts`). */
+const BLOCK_TAGS: Record<string, 'paragraph' | 'h2' | 'h3' | 'h4' | 'list' | 'quote'> = {
+  blockquote: 'quote',
+  h2: 'h2',
+  h3: 'h3',
+  h4: 'h4',
+  li: 'list',
+  p: 'paragraph',
+}
+
+/**
+ * The formatting elements between `node` (the selection's anchor) and `root` (the field element
+ * `u90:format` applies to, exclusive) — the caret's `marks`. Walking ancestors rather than
+ * inspecting Lexical state: there is none here, only the live DOM a `contenteditable` selection
+ * sits in, so this reads the same tags `lexicalDom.ts`'s `MARK_BITS` inverts back out of it.
+ */
+export const activeMarks = (node: Node, root: HTMLElement): string[] => {
+  const marks = new Set<string>()
+  let el: Element | null = node.nodeType === Node.TEXT_NODE ? node.parentElement : (node as Element)
+  while (el && el !== root && root.contains(el)) {
+    const mark = MARK_TAGS[el.tagName.toLowerCase()]
+    if (mark) marks.add(mark)
+    el = el.parentElement
+  }
+  return [...marks]
+}
+
+/** The nearest block element between `node` and `root` (exclusive) — the caret's `block`. */
+export const activeBlock = (node: Node, root: HTMLElement): 'paragraph' | 'h2' | 'h3' | 'h4' | 'list' | 'quote' | undefined => {
+  let el: Element | null = node.nodeType === Node.TEXT_NODE ? node.parentElement : (node as Element)
+  while (el && el !== root && root.contains(el)) {
+    const block = BLOCK_TAGS[el.tagName.toLowerCase()]
+    if (block) return block
+    el = el.parentElement
+  }
+  return undefined
+}