@panphora/bevel 0.1.0

package/examples/components/reference/sources/hypercms/src/path.js

@@ -0,0 +1,61 @@
+export function toString(path) {
+  return path.map(String).join('.')
+}
+
+export function fromString(str) {
+  if (str === '') return []
+  return str.split('.').map((seg) => (/^\d+$/.test(seg) ? Number(seg) : seg))
+}
+
+export function getRuleAtPath(rules, path) {
+  let node = rules
+  for (const seg of path) {
+    if (node == null) return undefined
+    if (typeof node === 'string') {
+      // Scalar-array rules like 'li[]' contain leaf scalars at integer indices.
+      // Descend by stripping the trailing []; the leaf is treated as a plain
+      // scalar string for path queries.
+      if (node.endsWith('[]') && (typeof seg === 'number' || seg === '*')) {
+        node = node.slice(0, -2)
+        continue
+      }
+      return undefined
+    }
+    if (Array.isArray(node)) {
+      if (typeof seg !== 'number' && seg !== '*') return undefined
+      node = node[1]
+      continue
+    }
+    if (typeof node === 'object') {
+      if (typeof seg === 'number') return undefined
+      if (!(seg in node)) return undefined
+      node = node[seg]
+      continue
+    }
+    return undefined
+  }
+  return node
+}
+
+export function getValueAtPath(data, path) {
+  let node = data
+  for (const seg of path) {
+    if (node == null) return undefined
+    node = node[seg]
+  }
+  return node
+}
+
+export function setAtPath(obj, path, value) {
+  if (path.length === 0) return value
+  const [k, ...rest] = path
+  if (typeof k === 'number') {
+    const next = Array.isArray(obj) ? [...obj] : []
+    next[k] = setAtPath(next[k], rest, value)
+    return next
+  }
+  return {
+    ...(obj && typeof obj === 'object' ? obj : {}),
+    [k]: setAtPath((obj || {})[k], rest, value),
+  }
+}

package/examples/components/reference/sources/hypercms/src/place.js

@@ -0,0 +1,131 @@
+// Where to put a floating thing next to a page element.
+//
+// COPIED, deliberately, from richclay/src/toolbar-float.js:1-59. Not imported:
+// hypercms must not gain a hard richclay dependency to lay out a popover on a
+// page that contains no rich text at all. The ladder is the same one richclay's
+// floating toolbar has been using in production, and the copy is verbatim apart
+// from the two notes below, so a fix on either side can be read across.
+//
+// Two differences from the original, both because a popover is not a toolbar:
+//
+//  1. A popover has ONE size. richclay measures a horizontal bar and a vertical
+//     rail because its toolbar reflows between them; ours does not. Callers pass
+//     the same box as both `bar` and `rail`, which collapses the side-rail rung
+//     of the ladder into a plain "put it beside the anchor" without changing a
+//     line of the math.
+//
+//  2. The `hidden` rung is a backstop here, not the visibility test. It compares
+//     the anchor to the viewport, which cannot see an anchor clipped by an
+//     overflow: hidden ancestor while still inside the viewport — the case that
+//     floats a control over whatever is visible in its place. The inline view
+//     decides visibility from an IntersectionObserver, which accounts for
+//     ancestor clipping by construction (measured, plan §3.1.2), and only asks
+//     for a placement once it knows the anchor is showing.
+
+export const GAP = 16
+export const GAP_LADDER = [16, 8, 0]
+export const VIEWPORT_INSET = 8
+export const PLACEMENT_SLACK = 4
+
+// Pure placement ladder: above -> below -> beside -> pinned to viewport top.
+// All coords are viewport-relative (the host is position: fixed). `current` gets
+// PLACEMENT_SLACK of hysteresis so the mode doesn't flip-flop at exact
+// boundaries while the page scrolls.
+export function place({ anchor, bar, rail = bar, viewport, current = null }) {
+  const slack = (mode) => (current === mode ? PLACEMENT_SLACK : 0)
+
+  if (
+    anchor.bottom <= 0 ||
+    anchor.top >= viewport.height ||
+    anchor.right <= 0 ||
+    anchor.left >= viewport.width
+  ) {
+    return { mode: 'hidden', x: 0, y: 0 }
+  }
+
+  const clampX = (width) =>
+    Math.max(VIEWPORT_INSET, Math.min(anchor.left, viewport.width - width - VIEWPORT_INSET))
+
+  const aboveY = anchor.top - GAP - bar.height
+  if (aboveY >= VIEWPORT_INSET - slack('above')) {
+    return { mode: 'above', x: clampX(bar.width), y: aboveY }
+  }
+
+  const belowY = anchor.bottom + GAP
+  if (belowY + bar.height <= viewport.height - VIEWPORT_INSET + slack('below')) {
+    return { mode: 'below', x: clampX(bar.width), y: belowY }
+  }
+
+  const rightSpace = viewport.width - anchor.right - VIEWPORT_INSET
+  const leftSpace = anchor.left - VIEWPORT_INSET
+  const sides =
+    rightSpace >= leftSpace
+      ? [['rail-right', rightSpace], ['rail-left', leftSpace]]
+      : [['rail-left', leftSpace], ['rail-right', rightSpace]]
+
+  for (const [mode, space] of sides) {
+    for (const gap of GAP_LADDER) {
+      if (rail.width + gap > space + slack(mode)) continue
+      const x =
+        mode === 'rail-right'
+          ? Math.min(anchor.right + gap, viewport.width - rail.width - VIEWPORT_INSET)
+          : Math.max(anchor.left - gap - rail.width, VIEWPORT_INSET)
+      const maxY = Math.min(anchor.bottom, viewport.height - VIEWPORT_INSET) - rail.height
+      const y = Math.max(VIEWPORT_INSET, Math.min(Math.max(anchor.top, VIEWPORT_INSET), maxY))
+      return { mode, x, y, gap }
+    }
+  }
+
+  return { mode: 'pinned', x: clampX(bar.width), y: VIEWPORT_INSET }
+}
+
+// A handle sits ON its anchor's top-right corner, overlapping it, so it reads as
+// belonging to that element rather than floating near it. No ladder: a handle is
+// small enough that it always fits, and moving it around the anchor would make
+// the page feel like it was shuffling under the pointer.
+//
+// The one thing it does need is the viewport clamp. A card flush against the
+// right edge would otherwise put its handle half off-screen, and a heading at
+// the very top of the document would put it above the fold.
+//
+// `prefer` picks which of the two placements below the caller wants:
+// 'auto' adapts to the anchor's size, 'corner' always takes the corner.
+export function placeHandle({ anchor, handle, viewport, inset = 6, prefer = 'auto' }) {
+  // Overlapping only reads as "belongs to this" when there is something left to
+  // belong to. On a 108x18 link a 36x31 handle covered 28% of it, including the
+  // last word — measured in a real browser. So a small anchor gets its handle
+  // set BESIDE it instead: still adjacent, nothing hidden.
+  //
+  // That rule is about a handle floating near a link. A control that BELONGS to
+  // a list row wants the opposite and asks for 'corner': measured in Chrome, a
+  // 31px strip beside a 36px card row landed wholly outside the row, and beside
+  // a run of 60px-pitch pills the strips covered each other. Such a caller pins
+  // the control to the corner and decides for itself whether the row is big
+  // enough to carry one at all. The clamp below is shared either way.
+  const roomy = anchor.height >= handle.height * 1.5 && anchor.width >= handle.width * 2
+  if (prefer === 'corner' || roomy) {
+    const x = Math.max(
+      VIEWPORT_INSET,
+      Math.min(anchor.right - handle.width + inset, viewport.width - handle.width - VIEWPORT_INSET)
+    )
+    const y = Math.max(
+      VIEWPORT_INSET,
+      Math.min(anchor.top - inset, viewport.height - handle.height - VIEWPORT_INSET)
+    )
+    return { x, y, mode: 'over' }
+  }
+
+  // Beside: to the right when it fits, otherwise to the left, vertically
+  // centred on the anchor. Both are clamped, so a handle never leaves the
+  // viewport even for an anchor flush against an edge.
+  const gap = 4
+  const fitsRight = anchor.right + gap + handle.width <= viewport.width - VIEWPORT_INSET
+  const rawX = fitsRight ? anchor.right + gap : anchor.left - gap - handle.width
+  // Only the left edge needs clamping. fitsRight is the test for "the right
+  // placement is inside the viewport", so the right branch is already in bounds
+  // by construction; the left branch can run off a narrow anchor's left side.
+  const x = Math.max(VIEWPORT_INSET, rawX)
+  const centred = anchor.top + anchor.height / 2 - handle.height / 2
+  const y = Math.max(VIEWPORT_INSET, Math.min(centred, viewport.height - handle.height - VIEWPORT_INSET))
+  return { x, y, mode: fitsRight ? 'beside-right' : 'beside-left' }
+}

package/examples/components/reference/sources/hypercms/src/platform.js

@@ -0,0 +1,131 @@
+// The optional platform hypercms rides: the mutation hub, undo, the save-prepare
+// hook, rich text, and the two upload helpers. Every one degrades to null, so the
+// CMS still runs in a bare HTML file with no client at all.
+//
+// TWO clients provide this and they disagree on names. hyperclayjs owns
+// window.hyperclay; clayjs owns window.clay and renamed things on the way past
+// (onPrepareForSave -> addDocumentTransform, consent -> confirm, uploadFileBasic ->
+// upload). So this is a capability table rather than a namespace pointer:
+// `window.clay ?? window.hyperclay` would resolve to clay, find no
+// onPrepareForSave, and silently stop stripping the CMS's own chrome out of every
+// save.
+//
+// Reads happen per call, never cached. A client can install a capability after
+// hypercms evaluates — that is the whole reason whenReady() below exists.
+const CAPABILITIES = {
+  Mutation:         (clay, hyperclay) => clay?.Mutation ?? hyperclay?.Mutation,
+  undo:             (clay, hyperclay) => clay?.undo ?? hyperclay?.undo,
+  onPrepareForSave: (clay, hyperclay) => clay?.addDocumentTransform ?? hyperclay?.onPrepareForSave,
+  // Distinct from onPrepareForSave above, and the difference is the whole point:
+  // onPrepareForSave is save-only, so a hook there runs AFTER live sync has
+  // already broadcast the document. onSnapshot runs on every snapshot, save and
+  // sync alike, which is the only place a cleanup can sit and be seen by both.
+  onSnapshot:       (clay, hyperclay) => clay?.onSnapshot ?? hyperclay?.onSnapshot,
+  consent:          (clay, hyperclay) => clay?.confirm ?? hyperclay?.consent,
+  RichClay:         (clay, hyperclay) => clay?.RichClay ?? hyperclay?.RichClay,
+  quickcrop:        (clay, hyperclay) => clay?.quickcrop ?? hyperclay?.quickcrop,
+  upload:           (clay, hyperclay) =>
+    clay?.upload ?? (hyperclay?.uploadFileBasic ? adaptLegacyUpload(hyperclay.uploadFileBasic) : null),
+}
+
+// The one capability where the two clients differ in SHAPE and not just in name,
+// so it is normalized here rather than at the call site. clay.upload answers one
+// envelope for every outcome and never rejects; uploadFileBasic resolves on
+// success and rejects on failure. A pick handler that had to know which client it
+// was riding would grow two of every branch, and the branch that matters most is
+// the one a rejection reads wrong: "this host does not store files" is not a
+// failure, and a caller that catches it as one stops when it should have embedded.
+//
+// The legacy client has no cancellation, so `signal` is honored on the near side
+// only: an upload already in flight runs to completion, and its result is
+// discarded rather than written. That is the same outcome the caller's own
+// ctx.closed check produces, one branch earlier.
+const LEGACY_STATUS_CODES = {
+  402: 'payment-required',
+  413: 'too-large',
+  415: 'unsupported-type',
+  401: 'unauthorized',
+  403: 'forbidden',
+  404: 'not-found',
+}
+
+const aborted = () => ({ ok: false, msg: 'Upload cancelled', msgType: 'skipped', code: 'aborted', uploads: [] })
+
+function adaptLegacyUpload(uploadFileBasic) {
+  return async function upload(file, { onProgress, signal } = {}) {
+    if (signal?.aborted) return aborted()
+    try {
+      // uploadFileBasic reports a bare percent; clay reports {loaded,total,percent}.
+      // Callers draw from `percent`, which is the only field both can supply.
+      const res = await uploadFileBasic(file, {
+        onProgress: (percent) => { onProgress?.({ loaded: null, total: null, percent }) },
+      })
+      if (signal?.aborted) return aborted()
+      const uploads = (res && res.uploads) || []
+      if (typeof uploads[0]?.url !== 'string') {
+        return { ok: false, msg: 'The host accepted the file but did not say where it put it', msgType: 'error', code: 'bad-response', uploads: [] }
+      }
+      return { ok: true, msg: res.msg || 'Uploaded', msgType: res.msgType || 'success', code: res.code || null, uploads }
+    } catch (err) {
+      if (signal?.aborted) return aborted()
+      // The rejection carries the HTTP status and the raw body, so the host's own
+      // code survives the round trip and the caller branches on the reason rather
+      // than pattern-matching a message.
+      let body = {}
+      try { body = JSON.parse(err?.response || '{}') } catch { body = {} }
+      const code = body.code || LEGACY_STATUS_CODES[err?.status] || 'error'
+      return { ok: false, msg: (err && err.message) || 'Upload failed', msgType: 'error', code, uploads: [] }
+    }
+  }
+}
+
+// Pass `win` when the caller already holds a realm (a doc.defaultView from a form
+// mounted into another document); it defaults to the ambient one.
+export function platform(name, win) {
+  const read = CAPABILITIES[name]
+  if (!read) throw new Error(`hypercms: unknown platform capability "${name}"`)
+  const scope = win || (typeof window !== 'undefined' ? window : null)
+  if (!scope) return null
+  return read(scope.clay, scope.hyperclay) || null
+}
+
+// Both spellings of the same signal. Each client fires exactly one name: clayjs
+// its own, hyperclayjs the legacy one. Listening for both is what lets one build
+// of hypercms ride either client. The name-keyed guard below stays regardless, so
+// a listener on both names still can't double-fire if a client ever dispatches
+// the pair again.
+export const MUTATION_READY = ['clay:mutation-ready', 'hyperclay:mutation-ready']
+export const LIVESYNC_APPLIED = ['clay:sync-applied', 'hyperclay:livesync-applied']
+
+// The readiness pair both clients publish once their public surface is
+// assembled. clayjs fires clay:ready from its loader; hyperclayjs fires
+// hyperclay:ready from exportToWindow. This is the handshake richclay uses for
+// the same race, and it is the only reliable retry signal for a hook whose
+// capability arrives later than hypercms does.
+export const PLATFORM_READY = ['clay:ready', 'hyperclay:ready']
+
+// Subscribe to every spelling of one signal, delivering the handler ONCE per
+// occurrence. No client dispatches the pair today, but one that did would make a
+// plain listener on each name fire the handler twice for one event: two form
+// re-extracts, or two open() calls.
+//
+// The first name to arrive claims the tick, and only a DIFFERENT name is suppressed
+// while it holds the claim. That distinction is what makes this exact rather than a
+// heuristic: no client dispatches one name twice for one occurrence, so a repeat of
+// the claiming name is always a second occurrence and always gets through — even
+// when it lands in the same tick, which is precisely what a caller doing two
+// synchronous applies looks like. Guarding on "have I run at all this tick" would
+// swallow that.
+//
+// Returns an unsubscribe that removes every name.
+export function onPlatformEvent(target, names, handler) {
+  let claimedBy = null
+  const wrapped = (event) => {
+    if (claimedBy !== null && claimedBy !== event.type) return
+    claimedBy = event.type
+    queueMicrotask(() => { claimedBy = null })
+    handler(event)
+  }
+  for (const name of names) target.addEventListener(name, wrapped)
+  return () => { for (const name of names) target.removeEventListener(name, wrapped) }
+}

package/examples/components/reference/sources/hypercms/src/refresh.js

@@ -0,0 +1,87 @@
+import { engine } from 'hyper-html-api'
+import { buildForm } from './form-builder.js'
+import { morphForm } from './morph.js'
+import { injectDefaults, injectComponents } from './templates.js'
+import { deriveFormRules } from './form-rules.js'
+import { coerceBooleans, applyErrorState } from './events.js'
+import { findUnresolved, applyUnresolvedState, stripReadOnly } from './unresolved.js'
+import { enhanceFields } from './enhance.js'
+import { platform } from './platform.js'
+import { rowIdentitySeeder } from './row-identity.js'
+
+const ENGINE_OPTS = { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }
+
+export function refreshForm(ctx, { ignoreActiveValue } = {}) {
+  // Re-resolve rules every refresh, source-aware: an object source returns the
+  // same literal (tagNode null); a token source re-resolves the tag so a
+  // livesync-replaced rules tag is picked up. Document-scoped via ctx.doc.
+  const found = engine.findRules(ctx.doc, ctx.rulesSource || 'cms')
+  if (found) {
+    // Re-apply the rule upgrade open() performed: the tag holds the author's
+    // bare rules, and using them raw would rebind upgraded fields back to
+    // textContent mid-session. Route it through the SAME seam open() used
+    // (session.js hands found.rules to view.prepareRules) rather than
+    // hardcoding one view's upgrade here — that undid a wider upgrade on the
+    // first refresh, silently flattening rich text back to plain.
+    ctx.pageRules = ctx.view.prepareRules(found.rules)
+    ctx.rulesTagNode = found.tagNode
+  }
+  // Re-derive formRules so schema changes (rule shape, template overrides) flow through.
+  injectDefaults(ctx.doc)
+  injectComponents(ctx.doc, ctx.pageRules)
+  ctx.formRules = deriveFormRules(ctx.pageRules, ctx.doc)
+  ctx.writeRules = stripReadOnly(ctx.pageRules)
+  // Before the extract below, for the same readable-failure reason as open().
+  ctx.unresolved = findUnresolved(ctx.pageRoot, ctx.pageRules)
+
+  // The morph below can rebuild a form row, which drops its binding to the page
+  // row it stood for. Read the pairing off this extract and re-establish it once
+  // the morph has settled, so the first operation after a refresh is not left
+  // guessing.
+  const seeder = rowIdentitySeeder()
+  const newData = coerceBooleans(
+    engine.extract(ctx.pageRoot, ctx.pageRules, { ...ENGINE_OPTS, ...seeder.hooks }),
+    ctx.pageRules
+  )
+  const fragment = buildForm({
+    pageRules: ctx.pageRules,
+    formRules: ctx.formRules,
+    data: newData,
+    doc: ctx.doc,
+  })
+  morphForm(ctx.formRoot, fragment, { ignoreActiveValue })
+  seeder.seed(ctx.formRoot)
+  // The morph can rebuild field nodes, dropping autosize heights and richclay
+  // instances (instances are per-element); re-enhance whatever is new.
+  enhanceFields(ctx.formRoot, ctx.doc, ctx.view?.enhanceFormRichText !== false)
+  // morphForm rebuilds the form structure; inline error slots get wiped. Re-apply
+  // the last error state so error messages survive across observer-driven refreshes
+  // (e.g., the rollback after a failed add).
+  applyErrorState(ctx)
+  applyUnresolvedState(ctx)
+  // Update fingerprint so subsequent commits against the new page state compare correctly.
+  if (ctx.updateFingerprint) ctx.updateFingerprint()
+}
+
+export function installObserver({ debounce = 100, onRefresh }) {
+  const M = platform('Mutation')
+  if (!M || typeof M.onAnyChange !== 'function') {
+    throw new Error('hypercms: a mutation hub is required (clay.Mutation or hyperclay.Mutation). Load clayjs or hyperclayjs, or just the mutation utility, before initializing hypercms.')
+  }
+  let paused = 0
+  // The hub hands every subscriber the batch of changes it collected
+  // ({ type: 'add' | 'remove' | 'attribute', element, parent, attribute,
+  // oldValue, newValue }, see clayjs/src/lib/mutation.js). Discarding them was
+  // fine while the only view was the sidebar, which refreshes wholesale. A view
+  // that edits the page in place needs to know whether a batch is its own doing,
+  // so pass them on and let the view decide.
+  const unsub = M.onAnyChange({ debounce }, (changes) => {
+    if (paused > 0) return
+    onRefresh(changes)
+  })
+  return {
+    unsubscribe: typeof unsub === 'function' ? unsub : () => {},
+    pause() { paused++ },
+    resume() { paused = Math.max(0, paused - 1) },
+  }
+}

package/examples/components/reference/sources/hypercms/src/richclay-bridge.js

@@ -0,0 +1,140 @@
+// hypercms's bridge to richclay: how it finds the class, and how it cleans up
+// after the instances it creates.
+//
+// The cleanup exists because hypercms constructs `new RichClay(el, { hyperclay:
+// false })`, and richclay installs its own save bridge only when that option is
+// true (`richclay/src/richclay.js:135`). So on a page whose only richclay usage
+// is hypercms's, NOTHING strips the editor's runtime state out of the document:
+// a contenteditable heading reaches the file and stays editable forever.
+// hypercms created those instances, so hypercms cleans them up.
+
+import { platform } from './platform.js'
+
+// Written on the live page element at bind time, removed from the snapshot
+// clone. It is the only way to tell an element hypercms made rich from one the
+// author marked up themselves: element identity does not survive cloneNode, so
+// an in-memory Set cannot answer the question on the clone the hook receives.
+//
+// Its VALUE is whether the element held markup before richclay touched it:
+// 'rich' or 'plain'. That has to be frozen here, because Squire wraps the
+// content of a block it binds in a <div>, so from the first click the live DOM
+// can no longer answer whether the author wrote markup in this element.
+export const BOUND_ATTR = 'data-hcms-bound'
+
+// The binding's own id, written on the live element and carried into the clone
+// by cloneNode. It is how the save hook, holding a clone, finds the live binding
+// that knows what the author's markup was before richclay rewrote it. Identity
+// cannot cross cloneNode, and the markup is far too big to ride in an attribute.
+export const BOUND_ID_ATTR = 'data-hcms-bound-id'
+
+// id -> the live binding. Populated at bind, dropped at unbind, read only by the
+// save hook. Holding the binding rather than a copy of its markup is deliberate:
+// whether the restore should happen at all is a question about the binding's
+// state right now, not about its state when it was created.
+const boundById = new Map()
+
+export function registerBinding(id, binding) {
+  boundById.set(id, binding)
+}
+
+export function releaseBinding(id) {
+  boundById.delete(id)
+}
+
+// The author's markup for a clone element, or null when the clone must be left
+// exactly as it stands. Null covers all three reasons: no live binding behind
+// it, an editor the author owns, and any content this session has actually
+// changed. See restorable() in inline.js, which asks the same question of the
+// live element at teardown.
+export function pristineMarkupFor(cloneEl) {
+  const id = cloneEl.getAttribute(BOUND_ID_ATTR)
+  if (!id) return null
+  const binding = boundById.get(id)
+  if (!binding || !binding.restorable()) return null
+  return binding.originalHTML
+}
+
+// Written beside the marker when hypercms's own construct call is what put
+// data-richclay on the element. richclay 0.5.0 tracks the same provenance in
+// data-richclay-runtime-marker and strips the attribute for us, but clayjs and
+// hyperclayjs both vendor 0.4.0, which has no marker and leaves it in the file.
+// data-richclay is richclay's mount selector, so left there it turns every
+// heading anyone clicked into a permanent richclay region. hypercms knew the
+// answer before it touched the element; it does not need to ask.
+export const RC_OWNED_ATTR = 'data-hcms-owns-richclay'
+
+export function resolveRichClay(win) {
+  return (
+    (win && win.richclay && win.richclay.RichClay) ||
+    platform('RichClay', win) ||
+    (win && typeof win.RichClay === 'function' ? win.RichClay : null)
+  )
+}
+
+export function markBound(el, heldMarkup, richClayIsOurs) {
+  if (!el || typeof el.setAttribute !== 'function') return
+  el.setAttribute(BOUND_ATTR, heldMarkup ? 'rich' : 'plain')
+  if (richClayIsOurs) el.setAttribute(RC_OWNED_ATTR, 'true')
+}
+
+// ⚠ THE ORDER IS LOAD-BEARING. richclay's strip iterates
+// "[data-richclay], [richclay], [editable], [clay-editable]". Remove
+// data-richclay first and a bare <h1> stops matching that selector, the strip
+// skips it, and every runtime attribute richclay wrote reaches the file. Strip
+// FIRST, unmark second. Both orders were run and the bytes compared; the other
+// one ships a permanently contenteditable heading.
+export function cleanRichClayFromSnapshot(cloneDocEl, win) {
+  if (!cloneDocEl || typeof cloneDocEl.querySelectorAll !== 'function') return
+  const bound = cloneDocEl.querySelectorAll(`[${BOUND_ATTR}]`)
+  if (!bound.length) return
+
+  const RichClay = resolveRichClay(win)
+  if (RichClay && typeof RichClay.stripFromClone === 'function') {
+    try {
+      // A second pass over an already-stripped clone is string-identical, so
+      // this stays correct on a page that also uses richclay directly and has
+      // richclay's own bridge installed.
+      RichClay.stripFromClone(cloneDocEl)
+    } catch (err) {
+      console.warn('[hypercms] richclay strip failed; editor state may reach the save', err)
+    }
+  }
+  for (const el of bound) {
+    // Whether data-richclay comes off is decided by who put it there, not by
+    // which richclay is loaded. On 0.5.0 stripFromClone has already removed it
+    // and this is a no-op; on the 0.4.0 copies clayjs and hyperclayjs vendor,
+    // this is the only thing that removes it. An author's own opt-in never
+    // carries the marker, so it is never touched.
+    if (el.getAttribute(RC_OWNED_ATTR) === 'true') el.removeAttribute('data-richclay')
+    el.removeAttribute(RC_OWNED_ATTR)
+    el.removeAttribute(BOUND_ATTR)
+  }
+}
+
+// A page element that carries the CMS marker but has no binding behind it: a
+// clone the engine made of a bound row, or of a bound element it replaced while
+// rolling back a failed apply. destroy() cannot reach it — destroy belongs to an
+// instance and a clone has none — so it is left permanently editable with page
+// undo switched off for it. The snapshot hook still cleans the saved file; this
+// is the live page.
+export function stripOrphanEditorState(el, win) {
+  if (!el || typeof el.removeAttribute !== 'function') return
+  const RichClay = resolveRichClay(win)
+  if (RichClay && typeof RichClay.stripElement === 'function') {
+    try {
+      RichClay.stripElement(el)
+    } catch (err) {
+      console.warn('[hypercms] richclay element strip failed; the clone stays editable', err)
+    }
+  } else {
+    // An older richclay with no per-element strip. These two are what actually
+    // harm the live page; the rest is cosmetic and the snapshot hook removes it
+    // from the file either way.
+    el.removeAttribute('contenteditable')
+    el.removeAttribute('no-undo')
+  }
+  if (el.getAttribute(RC_OWNED_ATTR) === 'true') el.removeAttribute('data-richclay')
+  el.removeAttribute(RC_OWNED_ATTR)
+  el.removeAttribute(BOUND_ATTR)
+  el.removeAttribute(BOUND_ID_ATTR)
+}

package/examples/components/reference/sources/hypercms/src/row-identity.js

@@ -0,0 +1,111 @@
+/**
+ * Row identity supplied to the engine, so two byte-identical rows can still be
+ * told apart on a remove or a reorder.
+ *
+ * The engine matches rows by content, which is exact for every operation the
+ * form emits except one: when two rows read identically, "remove row 0" and
+ * "remove row 1" produce the same array, and no score can separate them. The
+ * form can, because it holds a handle the engine never sees, its own row
+ * elements.
+ *
+ * Those elements are stable across the operations that matter. A keystroke
+ * never rebuilds the form (applyWithRollback pauses the mutation observer
+ * around apply), and add, remove and move mutate the form DOM in place rather
+ * than re-rendering it. By the time commit() runs the form is already in its
+ * new shape, so walking its rows in order gives the new item order with each
+ * row still carrying the page node it came from. The permutation falls out.
+ *
+ * refreshForm does re-render the form, through hyper-morph, when the page
+ * changes underneath us (livesync, undo, another session). Rows rebuilt there
+ * have no entry, identifyRows returns null for them, and the engine's matcher
+ * takes over. onRowsApplied re-establishes the pairing on the next apply. That
+ * is correct rather than merely tolerable: the form was just built from a fresh
+ * read of the page, so index correspondence is exact at that instant.
+ */
+const boundNode = new WeakMap()
+
+// The engine's trace path as the form writes it in data-hcms-path.
+const pathKey = (path) => path.map(String).join('.')
+
+// Rule keys reach the selector verbatim, and a key holding a quote makes
+// querySelector throw. Every other path-into-selector site in this package
+// escapes the same way; this is that function, kept module-local like the rest.
+function cssEscape(value) {
+  if (typeof CSS !== 'undefined' && CSS.escape) return CSS.escape(value)
+  return String(value).replace(/[^a-zA-Z0-9_\-.*]/g, (c) => '\\' + c)
+}
+
+// The form rows for one list, in document order, or null when the form has no
+// such list. Keys look like "products" or "products.0.variants".
+function formRowsAt(formRoot, key) {
+  if (!formRoot || !formRoot.querySelector) return null
+  const container = formRoot.querySelector(`[data-hcms-path="${cssEscape(key)}"]`)
+  const slot = container && container.querySelector('.hcms-array-items')
+  if (!slot) return null
+  // Direct children, filtered, rather than `:scope > ...`. jsdom's selector
+  // engine resolves `:scope >` against the document rather than the slot and
+  // returns descendants, so a page with nested lists reported the inner rows as
+  // rows of the outer list. The count then failed to match and identity silently
+  // fell back to content matching in exactly the shape this exists for.
+  return Array.from(slot.children).filter(
+    (el) => el.matches && el.matches('[data-hcms-card], [data-hcms-array-item]'),
+  )
+}
+
+function bind(formRoot, key, nodes) {
+  const rows = formRowsAt(formRoot, key)
+  if (!rows || rows.length !== nodes.length) return
+  rows.forEach((row, i) => {
+    if (nodes[i]) boundNode.set(row, nodes[i])
+  })
+}
+
+/**
+ * Establish identity from the extract the form is built from, before any apply
+ * has happened.
+ *
+ * Without this the map is populated only by onRowsApplied, so the FIRST
+ * structural operation of a session has nothing to go on and falls back to
+ * content matching. Pass `hooks` to the top-level `engine.extract` that feeds
+ * buildForm, then call `seed(formRoot)` once the form rows exist. At that
+ * moment row i of the form is row i of the page by construction, because the
+ * form was built from exactly this read.
+ *
+ * Never pass these hooks to `apply`: listDiff re-extracts each existing row
+ * with a fresh path, which would report nested lists under a truncated one.
+ */
+export function rowIdentitySeeder() {
+  const readNodes = new Map()
+  return {
+    hooks: {
+      onRowsRead(path, nodes) {
+        readNodes.set(pathKey(path), nodes)
+      },
+    },
+    seed(formRoot) {
+      for (const [key, nodes] of readNodes) bind(formRoot, key, nodes)
+      readNodes.clear()
+    },
+  }
+}
+
+export function rowIdentityHooks(formRoot) {
+  return {
+    identifyRows(path, items) {
+      const rows = formRowsAt(formRoot, pathKey(path))
+      // A count mismatch means the form and the data disagree about this list,
+      // so the form is not a trustworthy witness for it. Say nothing and let
+      // the engine match.
+      if (!rows || rows.length !== items.length) return null
+      return rows.map((row) => boundNode.get(row) || null)
+    },
+    onRowsApplied(path, nodes) {
+      bind(formRoot, pathKey(path), nodes)
+    },
+  }
+}
+
+// Testing seam only: the WeakMap is module state and a test needs to observe it.
+export function boundNodeFor(formRow) {
+  return boundNode.get(formRow) || null
+}