@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/bridge/hooks.tsx

@@ -0,0 +1,56 @@
+'use client'
+
+import { createContext, lazy, Suspense, useContext, useEffect, useState, type ReactNode } from 'react'
+
+import { registry } from './registry'
+
+const LazyBridgeClient = lazy(() => import('./client').then((m) => ({ default: m.BridgeClient })))
+
+type EditingContextValue = { editing: boolean; selected: string | null; testPreview: boolean }
+
+const Ctx = createContext<EditingContextValue>({ editing: false, selected: null, testPreview: false })
+
+/**
+ * Mounted once, at the root, by `U90Bridge` — always mounted so `useEditing()` works from
+ * anywhere in the tree, but only ever told `editing: true` when `draftMode()` is enabled.
+ *
+ * Renders `children` unconditionally; the client bridge itself (`LazyBridgeClient`, the lazy
+ * `BridgeClient`) is rendered only when `editing`, and only inside its own `Suspense` boundary —
+ * `import('./client')` pulls in `next/navigation` and the whole DOM-level bridge, so a production
+ * (non-draft) render never fetches that chunk at all.
+ */
+export function EditingProvider({ editing, platformOrigin, testPreview = false, children }: { editing: boolean; platformOrigin: string; testPreview?: boolean; children: ReactNode }) {
+  const [selected, setSelected] = useState<string | null>(null)
+
+  return (
+    <Ctx.Provider value={{ editing, selected, testPreview }}>
+      {children}
+      {editing ? (
+        <Suspense fallback={null}>
+          <LazyBridgeClient platformOrigin={platformOrigin} onSelect={setSelected} />
+        </Suspense>
+      ) : null}
+    </Ctx.Provider>
+  )
+}
+
+/** `{ editing, selected }` — `selected` is the path last reported by `u90:select`, either way. */
+export const useEditing = (): EditingContextValue => useContext(Ctx)
+
+/**
+ * Runs `fn` whenever the Canvas selects a path starting with `pathPrefix` — e.g. a header
+ * opening its own menu when one of its own fields is selected. Registers directly on the shared
+ * `registry`, not on any particular bridge instance, so it works whether the bridge has started
+ * yet or not, and needs no context of its own (usable outside `EditingProvider`, where it is
+ * simply never triggered). Imports `./registry` only — never `./client` or `./createBridge` — so
+ * a component calling this hook never pulls the bridge chunk in just by rendering.
+ */
+export function useReveal(pathPrefix: string, fn: () => void): void {
+  useEffect(() => {
+    const entry = { prefix: pathPrefix, fn }
+    registry.reveals.add(entry)
+    return () => {
+      registry.reveals.delete(entry)
+    }
+  }, [pathPrefix, fn])
+}

package/src/bridge/index.ts

@@ -0,0 +1,9 @@
+/**
+ * `@unitninety/site-kit/bridge`: client-safe only — no `next/headers`, so a `"use client"` site
+ * component (e.g. a header calling `useReveal`) can import this subpath without pulling in a
+ * server-only module. `U90Bridge` reads `draftMode()` and is exported from `@unitninety/site-kit/server`
+ * instead; import it from there.
+ */
+export { BridgeClient } from './client'
+export { EditingProvider, useEditing, useReveal } from './hooks'
+export { BRIDGE_VERSION, isSiteMessage, parseCanvasMessage, type BridgeStamp, type CanvasMessage, type PreviewInstruction, type SiteMessage } from './protocol'

package/src/bridge/lexical.ts

@@ -0,0 +1,177 @@
+/**
+ * The rich text vocabulary, and the only place it is spelled out.
+ *
+ * Lexical's serialised shape, narrowed to the nodes this kit renders and can serialise back.
+ * Closed on purpose: the DOM-to-Lexical inverse in `lexicalDom.ts` only has to invert what
+ * `richText.tsx` emits, and that argument holds only while both read from this list.
+ *
+ * **No `lexical` import.** This package is vendored into every client site, so a dependency
+ * here is a dependency in seven repositories. A builder for a documented JSON tree does not
+ * need the library that produced it.
+ *
+ * Ported from `legacy/lexical.ts`, with one deliberate divergence: the `link` node's `fields`
+ * carry v1's `LinkTo` (`elements/leaves/link.ts`) rather than legacy's `{ linkType: 'custom', url }`
+ * — the shape the `u90/rich-text` element's stored schema requires (`elements/leaves/rich-text.ts`).
+ * Everything else here references no marker attribute, so bridge v4's attribute rename touches
+ * nothing else in this file.
+ */
+import type { LinkTo } from '../elements/leaves/link'
+
+/** Lexical's inline format bitfield. */
+export const FORMAT = {
+  bold: 1,
+  code: 16,
+  italic: 2,
+  strikethrough: 4,
+  underline: 8,
+} as const
+
+export type RichTextNode = {
+  detail: number
+  format: number
+  mode: string
+  style: string
+  text: string
+  type: 'text'
+  version: number
+}
+
+export type RichLineBreak = { type: 'linebreak'; version: number }
+
+export type RichInline = RichLineBreak | RichLink | RichTextNode
+
+export type RichLink = {
+  children: (RichLineBreak | RichTextNode)[]
+  direction: 'ltr'
+  fields: { newTab: boolean; to: LinkTo }
+  format: ''
+  indent: number
+  type: 'link'
+  version: number
+}
+
+export type RichParagraph = {
+  children: RichInline[]
+  direction: 'ltr'
+  format: ''
+  indent: number
+  textFormat: number
+  type: 'paragraph'
+  version: number
+}
+
+export type RichHeading = {
+  children: RichInline[]
+  direction: 'ltr'
+  format: ''
+  indent: number
+  tag: 'h1' | 'h2' | 'h3'
+  type: 'heading'
+  version: number
+}
+
+export type RichListItem = {
+  children: RichInline[]
+  direction: 'ltr'
+  format: ''
+  indent: number
+  type: 'listitem'
+  value: number
+  version: number
+}
+
+export type RichList = {
+  children: RichListItem[]
+  direction: 'ltr'
+  format: ''
+  indent: number
+  listType: 'bullet' | 'number'
+  start: number
+  tag: 'ol' | 'ul'
+  type: 'list'
+  version: number
+}
+
+export type RichBlock = RichHeading | RichList | RichParagraph
+
+export type RichTextValue = {
+  root: {
+    children: RichBlock[]
+    direction: 'ltr'
+    format: ''
+    indent: number
+    type: 'root'
+    version: number
+  }
+}
+
+export const text = (value: string, format = 0): RichTextNode => ({
+  detail: 0,
+  format,
+  mode: 'normal',
+  style: '',
+  text: value,
+  type: 'text',
+  version: 1,
+})
+
+export const lineBreak = (): RichLineBreak => ({ type: 'linebreak', version: 1 })
+
+export const link = (to: LinkTo, newTab: boolean, ...children: (RichLineBreak | RichTextNode)[]): RichLink => ({
+  children,
+  direction: 'ltr',
+  fields: { newTab, to },
+  format: '',
+  indent: 0,
+  type: 'link',
+  version: 1,
+})
+
+export const paragraph = (...children: RichInline[]): RichParagraph => ({
+  children,
+  direction: 'ltr',
+  format: '',
+  indent: 0,
+  textFormat: 0,
+  type: 'paragraph',
+  version: 1,
+})
+
+export const heading = (tag: 'h1' | 'h2' | 'h3', ...children: RichInline[]): RichHeading => ({
+  children,
+  direction: 'ltr',
+  format: '',
+  indent: 0,
+  tag,
+  type: 'heading',
+  version: 1,
+})
+
+export const listItem = (...children: RichInline[]): RichListItem => ({
+  children,
+  direction: 'ltr',
+  format: '',
+  indent: 0,
+  type: 'listitem',
+  value: 1,
+  version: 1,
+})
+
+export const list = (
+  listType: 'bullet' | 'number',
+  ...children: RichListItem[]
+): RichList => ({
+  children: children.map((item, index) => ({ ...item, value: index + 1 })),
+  direction: 'ltr',
+  format: '',
+  indent: 0,
+  listType,
+  start: 1,
+  tag: listType === 'bullet' ? 'ul' : 'ol',
+  type: 'list',
+  version: 1,
+})
+
+export const doc = (...children: RichBlock[]): RichTextValue => ({
+  root: { children, direction: 'ltr', format: '', indent: 0, type: 'root', version: 1 },
+})

package/src/bridge/lexicalDom.ts

@@ -0,0 +1,212 @@
+import { LinkTo } from '../elements/leaves/link'
+import {
+  doc,
+  FORMAT,
+  heading,
+  lineBreak,
+  link,
+  list,
+  listItem,
+  paragraph,
+  type RichBlock,
+  type RichInline,
+  type RichListItem,
+  type RichTextValue,
+  text,
+} from './lexical'
+
+/**
+ * Edited markup, back to the document it came from.
+ *
+ * The inverse of `richText.tsx`, and only of that: it inverts the markup this kit emits, not
+ * HTML in general. That is what makes it tractable — the vocabulary is closed and the mark
+ * nesting is fixed, so every shape reaching here is one `richText.tsx` produced.
+ *
+ * **A structural node, not an `Element`.** `dashboard/sitemap/tree.ts` gives the reason: a pure
+ * function over hand-written input is one `verify` can exercise, and a serialiser only testable
+ * in a browser is one nobody tests. The frame feeds it a thin adapter over real nodes.
+ *
+ * **Accepted losses (confirmed in review, not bugs to chase).** The vocabulary this file inverts
+ * is `richText.tsx`'s, not arbitrary pasted HTML, so a few shapes a paste can introduce are
+ * deliberately not preserved:
+ *   - `<span style="font-weight:700">…</span>` (a Word/Google Docs bold) drops its formatting —
+ *     there is no inline-style parser, only the closed `MARK_BITS` tag vocabulary below.
+ *   - a `<ul>`/`<ol>` nested inside an `<li>` flattens into the parent item's inline run, rather
+ *     than nesting as its own list.
+ *   - `<div><br></div>` (a lone line break with no text) is dropped rather than producing an
+ *     empty paragraph.
+ *
+ * Ported from `legacy/lexicalDom.ts` — `FIELD_ATTR`, `RICH_ATTR` and `SECTION_ATTR` never appear
+ * here, so bridge v4's attribute rename touches nothing in this file. One shape does diverge from
+ * legacy on purpose: an anchor's link target is read as v1's `LinkTo`, not a bare `url` string —
+ * see `linkTarget` below; see `bridge/ports.test.ts` for the copied `toRichText` cases.
+ */
+export type DomLike = {
+  attributes?: Record<string, string>
+  children?: DomLike[]
+  tag?: string
+  text?: string
+}
+
+/**
+ * Wrapper tag to the bit it sets. The inverse of `MARKS` in `richText.tsx`.
+ *
+ * `b`, `i` and `strike` are here although the reader never emits them: in-frame formatting is
+ * the browser's native `contentEditable` behaviour, and browsers disagree about which spelling
+ * they insert. Accepting both is what stops a client's ⌘B coming back as plain text.
+ */
+const MARK_BITS: Record<string, number> = {
+  b: FORMAT.bold,
+  code: FORMAT.code,
+  em: FORMAT.italic,
+  i: FORMAT.italic,
+  s: FORMAT.strikethrough,
+  strike: FORMAT.strikethrough,
+  strong: FORMAT.bold,
+  u: FORMAT.underline,
+}
+
+/** Block-level tags `blocks()` recurses on structurally rather than flattening into a paragraph. */
+const BLOCK_TAGS = new Set(['h1', 'h2', 'h3', 'ol', 'p', 'ul'])
+
+/** Tags that signal "this is inline content", the browser's `<a>` plus every mark alias above. */
+const INLINE_TAGS = new Set([...Object.keys(MARK_BITS), 'a'])
+
+/**
+ * Where an anchor points, in v1's `LinkTo` shape.
+ *
+ * `RichText.tsx` stamps every link it renders in draft with `data-u90-link`, holding the
+ * exact `{ to, newTab }` the field stores — an edit that never touched the link comes back
+ * byte-for-byte. A pasted `<a>` carries no such attribute (or one that fails to parse or to
+ * validate), so its `href` is classified instead: `mailto:` and `tel:` become the matching
+ * `LinkTo` kind, anything else an `{ url }`, always with `newTab: false` — there is no attribute
+ * to read a paste's target tab from.
+ */
+const stampedTarget = (attributes?: Record<string, string>): { newTab: boolean; to: LinkTo } | null => {
+  const stamped = attributes?.['data-u90-link']
+  if (!stamped) return null
+  try {
+    const parsed = JSON.parse(stamped) as { newTab?: unknown; to?: unknown }
+    const to = LinkTo.safeParse(parsed.to)
+    return to.success ? { newTab: parsed.newTab === true, to: to.data } : null
+  } catch {
+    return null // Malformed JSON — the caller falls back to what the element itself carries.
+  }
+}
+
+const linkTarget = (attributes?: Record<string, string>): { newTab: boolean; to: LinkTo } => {
+  const stamped = stampedTarget(attributes)
+  if (stamped) return stamped
+  const href = attributes?.href ?? '#'
+  const to: LinkTo = href.startsWith('mailto:')
+    ? { email: href.slice('mailto:'.length) }
+    : href.startsWith('tel:')
+      ? { tel: href.slice('tel:'.length) }
+      : { url: href }
+  return { newTab: false, to }
+}
+
+const inlines = (nodes: DomLike[], format: number): RichInline[] =>
+  nodes.flatMap((node): RichInline[] => {
+    if (typeof node.text === 'string') {
+      // `&nbsp;` is what a browser inserts for a second consecutive space. Storing it means
+      // the words on record stop matching the words typed, so it is normalised here — the
+      // same thing `readEditedText` does on the plain-text path.
+      const value = node.text.replace(/\u00a0/g, ' ')
+      return value ? [text(value, format)] : []
+    }
+
+    const singleKey = node.attributes?.['data-single-key']
+    if (singleKey && /^[^{}\s]+$/.test(singleKey)) return [text(`{${singleKey}}`, format)]
+
+    const tag = (node.tag ?? '').toLowerCase()
+    if (tag === 'br') return [lineBreak()]
+
+    /*
+     * Any element carrying a valid `data-u90-link` is a link, not only an `<a>`: `RichText.tsx`
+     * draws a dead link (no href) as a stamped `<span>`. An `<a>` whose stamp fails falls back to
+     * its href; any other element with a bad stamp is only its words — it has no href to fall to.
+     */
+    const stamped = tag === 'a' ? null : stampedTarget(node.attributes)
+    if (tag === 'a' || stamped) {
+      const { to, newTab } = stamped ?? linkTarget(node.attributes)
+      const children = inlines(node.children ?? [], format).filter(
+        (child): child is Exclude<RichInline, ReturnType<typeof link>> => child.type !== 'link',
+      )
+      return [link(to, newTab, ...children)]
+    }
+
+    const bit = MARK_BITS[tag]
+    if (bit !== undefined) return inlines(node.children ?? [], format | bit)
+
+    return inlines(node.children ?? [], format)
+  })
+
+/**
+ * One block's inline content, with the browser's scaffolding removed.
+ *
+ * A `contentEditable` puts a filler `<br>` at the end of a block so an empty one stays
+ * selectable. It is not something the client typed, and storing it is how a document grows on
+ * every save: the reader draws the linebreak back, the browser pads the result again, and the
+ * next serialisation keeps both. Observed on a real privacy policy — 34 blocks became 43, with
+ * five linebreaks that appear nowhere in the source.
+ *
+ * Only the *last* one goes. A `<br>` between words is a line break the client asked for.
+ */
+const blockInlines = (kids: DomLike[]): RichInline[] => {
+  const content = inlines(kids, 0)
+  const last = content[content.length - 1]
+  return last && last.type === 'linebreak' ? content.slice(0, -1) : content
+}
+
+
+const blocks = (nodes: DomLike[]): RichBlock[] =>
+  nodes.flatMap((node): RichBlock[] => {
+    const tag = (node.tag ?? '').toLowerCase()
+    const kids = node.children ?? []
+    if (node.attributes?.['data-single-key']) return [paragraph(...inlines([node], 0))]
+
+    /*
+     * An empty block is kept. Stripping the filler `<br>` above is what stops the growth loop;
+     * dropping the block as well deleted the blank line a client had just made with Enter, and
+     * took their caret to the end of the document with it.
+     */
+    if (tag === 'p') return [paragraph(...blockInlines(kids))]
+    if (tag === 'h1' || tag === 'h2' || tag === 'h3') return [heading(tag, ...blockInlines(kids))]
+    if (tag === 'ul' || tag === 'ol') {
+      const items: RichListItem[] = kids
+        .filter((kid) => (kid.tag ?? '').toLowerCase() === 'li')
+        .map((kid) => listItem(...blockInlines(kid.children ?? [])))
+      return [list(tag === 'ol' ? 'number' : 'bullet', ...items)]
+    }
+
+    /*
+     * Anything else contributes its children rather than itself — the wrapper the frame puts
+     * around the field, and any element a paste survived.
+     *
+     * Chrome's `contentEditable` default block separator is a bare `<div>`, and pasted content
+     * arrives the same way, so a fallthrough node's own children are not necessarily further
+     * blocks — they are as likely to be the inline content of an unwrapped paragraph. If any
+     * *direct* child is itself a block tag, keep recursing block-wise (a wrapper around real
+     * blocks). Otherwise, if any direct child is text or one of the inline/mark tags, the whole
+     * node IS a paragraph's worth of inline content and must be routed through `inlines()` as
+     * one paragraph — recursing block-wise here would silently drop every mark and split one
+     * sentence into one paragraph per text run, which is exactly the data loss this file exists
+     * to prevent.
+     */
+    if (kids.some((kid) => BLOCK_TAGS.has((kid.tag ?? '').toLowerCase()))) {
+      return blocks(kids)
+    }
+    if (kids.some((kid) => typeof kid.text === 'string' || Boolean(kid.attributes?.['data-single-key']) || Boolean(kid.attributes?.['data-u90-link']) || INLINE_TAGS.has((kid.tag ?? '').toLowerCase()))) {
+      return [paragraph(...blockInlines(kids))]
+    }
+
+    // A stray run of text with no block around it becomes a paragraph, because dropping it
+    // would lose a client's words.
+    if (typeof node.text === 'string') {
+      return node.text.trim() ? [paragraph(text(node.text))] : []
+    }
+    return blocks(kids)
+  })
+
+export const toRichText = (node: DomLike): RichTextValue => doc(...blocks(node.children ?? []))

package/src/bridge/preserveBlockMoves.ts

@@ -0,0 +1,88 @@
+type AtomicHost = HTMLElement & { moveBefore?: (node: Node, before: Node | null) => void }
+type SheetSnapshot = { element: HTMLStyleElement; sheet: CSSStyleSheet; rules: string[] }
+
+/** Includes open shadow roots: embedded widgets commonly put CSSOM-only styles there. */
+function stylesWithin(node: Node): SheetSnapshot[] {
+  const found: SheetSnapshot[] = []
+  const visit = (root: Node) => {
+    if (root.nodeType === 1) {
+      const element = root as Element
+      if (element.tagName === 'STYLE') {
+        const style = element as HTMLStyleElement
+        const sheet = style.sheet
+        if (sheet) found.push({ element: style, sheet, rules: Array.from(sheet.cssRules, (rule) => rule.cssText) })
+      }
+      if (element.shadowRoot) visit(element.shadowRoot)
+    }
+    for (const child of root.childNodes) visit(child)
+  }
+  visit(node)
+  return found
+}
+
+/** A browser move can replace a style's stylesheet, including for an atomic move.
+ * Restore its rules and forward the widget's cached CSSOM handle to the live sheet.
+ * Styled-components, for example, keeps that handle and calls insertRule/deleteRule
+ * again when its carousel changes. Copying just the initial rules leaves it broken. */
+function restoreSheets(snapshots: SheetSnapshot[]) {
+  for (const { element, sheet, rules } of snapshots) {
+    const current = element.sheet
+    if (!current || current === sheet) continue
+    while (current.cssRules.length) current.deleteRule(current.cssRules.length - 1)
+    for (const rule of rules) current.insertRule(rule, current.cssRules.length)
+    current.disabled = sheet.disabled
+    const originalRules = sheet.cssRules
+    const insert = sheet.insertRule.bind(sheet)
+    const remove = sheet.deleteRule.bind(sheet)
+    sheet.insertRule = (rule, index) => element.sheet && element.sheet !== sheet
+      ? element.sheet.insertRule(rule, index)
+      : insert(rule, index)
+    sheet.deleteRule = (index) => element.sheet && element.sheet !== sheet
+      ? element.sheet.deleteRule(index)
+      : remove(index)
+    Object.defineProperty(sheet, 'cssRules', {
+      configurable: true,
+      get: () => element.sheet && element.sheet !== sheet ? element.sheet.cssRules : originalRules,
+    })
+  }
+}
+
+/**
+ * React 19 uses insertBefore/appendChild to reorder keyed children. Adapt only this
+ * draft zone's insertion methods; React still owns its tree and no global DOM
+ * prototype changes. Atomic moves keep iframes/focus alive where supported. Both
+ * kinds of move need the CSSOM safeguard for styles in an embedded shadow root.
+ */
+export function preserveBlockMoves(host: HTMLDivElement | null): void | (() => void) {
+  if (!host) return
+  const atomic = host as AtomicHost
+  const insert = host.insertBefore
+  const append = host.appendChild
+  const place = <T extends Node>(node: T, before: Node | null, native: () => T): T => {
+    if (node.parentNode !== host || !host.isConnected || node.nodeType !== 1) return native()
+    const styles = stylesWithin(node)
+    if (typeof atomic.moveBefore === 'function') atomic.moveBefore(node, before)
+    else native()
+    restoreSheets(styles)
+    return node
+  }
+  host.insertBefore = function <T extends Node>(node: T, before: Node | null): T {
+    return place(node, before, () => insert.call(this, node, before) as T)
+  }
+  host.appendChild = function <T extends Node>(node: T): T {
+    return place(node, null, () => append.call(this, node) as T)
+  }
+  return () => {
+    host.insertBefore = insert
+    host.appendChild = append
+  }
+}
+
+/** Older browsers cannot atomically move iframes. Leave a zone containing one in
+ * place until the saved page loads afresh, instead of resetting a live form mid-drag. */
+export function needsEmbedReload(host: HTMLElement): boolean {
+  if (typeof (host as AtomicHost).moveBefore === 'function') return false
+  const hasFrame = (root: Element | ShadowRoot): boolean => [...root.querySelectorAll('*')]
+    .some((node) => node.tagName === 'IFRAME' || (node.shadowRoot !== null && hasFrame(node.shadowRoot)))
+  return hasFrame(host)
+}