@panphora/hyper-cms 0.8.1 → 0.11.0

package/src/lib/content-dom.js

@@ -0,0 +1,110 @@
+// GENERATED from clayjs/src/lib/content-dom.js. Edit ClayJS and run `npm run propagate:foundation`.
+
+import { capabilitySelector, hasCapability } from './region-capabilities.js'
+
+const UNSUPPORTED_SELECTOR = /:(?:focus(?:-within|-visible)?|hover|active|visited|defined)\b/i
+
+function copyControlState(source, copy) {
+  if (!/^(INPUT|TEXTAREA|SELECT|OPTION)$/.test(source.tagName || '')) return
+  const type = (source.getAttribute?.('type') || '').toLowerCase()
+  if ('value' in source && 'value' in copy && source.tagName !== 'OPTION' && type !== 'checkbox' && type !== 'radio') copy.value = source.value
+  if ('checked' in source && 'checked' in copy) copy.checked = source.checked
+  if ('selected' in source && 'selected' in copy) copy.selected = source.selected
+  if (source.tagName === 'SELECT') {
+    for (let i = 0; i < source.options.length; i++) copy.options[i].selected = source.options[i].selected
+  }
+  if ('indeterminate' in source && 'indeterminate' in copy) copy.indeterminate = source.indeterminate
+}
+
+function matchesWithin(node, selector, boundary, inherit) {
+  if (inherit) return !!node.closest?.(selector)
+  let current = node
+  while (current?.nodeType === 1) {
+    if (current.matches(selector)) return true
+    if (current === boundary) break
+    current = current.parentElement
+  }
+  return false
+}
+
+function importTree(source, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps) {
+  if (source.nodeType === 1 && (
+    (inherit ? hasCapability(source, capability) : matchesWithin(source, capabilityMatch, boundary, false)) ||
+    (exclude && matchesWithin(source, exclude, boundary, inherit))
+  )) return null
+  const copy = targetDocument.importNode(source, false)
+  maps.cloneToLive.set(copy, source)
+  maps.liveToClone.set(source, copy)
+  const sourceChildren = source.nodeType === 1 && source.tagName === 'TEMPLATE' ? source.content : source
+  const copyChildren = copy.nodeType === 1 && copy.tagName === 'TEMPLATE' ? copy.content : copy
+  if (sourceChildren !== source) {
+    maps.cloneToLive.set(copyChildren, sourceChildren)
+    maps.liveToClone.set(sourceChildren, copyChildren)
+  }
+  for (const child of sourceChildren.childNodes || []) {
+    const childCopy = importTree(child, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps)
+    if (childCopy) {
+      copyChildren.appendChild(childCopy)
+      if (child.nodeType === 1) copyControlState(child, childCopy)
+    }
+  }
+  if (source.nodeType === 1) copyControlState(source, copy)
+  return copy
+}
+
+export function createContentView(context, { capability = 'data', exclude = null, inherit = true } = {}) {
+  if (!context) throw new TypeError('createContentView requires a DOM context')
+  const sourceDocument = context.nodeType === 9 ? context : context.ownerDocument
+  if (!sourceDocument?.implementation?.createHTMLDocument) {
+    throw new TypeError('createContentView requires an HTML DOM implementation')
+  }
+  const inertDocument = sourceDocument.implementation.createHTMLDocument('')
+  const cloneToLive = new WeakMap()
+  const liveToClone = new WeakMap()
+  const sourceRoot = context.nodeType === 9 ? context.documentElement : context
+  if (exclude) inertDocument.documentElement.matches(exclude)
+  const capabilityMatch = capabilitySelector(capability)
+  const root = importTree(sourceRoot, inertDocument, capability, capabilityMatch, exclude, sourceRoot, inherit, { cloneToLive, liveToClone })
+  if (context.nodeType === 9 && root) {
+    inertDocument.replaceChild(root, inertDocument.documentElement)
+    liveToClone.set(context, inertDocument)
+    cloneToLive.set(inertDocument, context)
+  }
+
+  const assertSelector = selector => {
+    if (UNSUPPORTED_SELECTOR.test(selector)) {
+      throw new Error(`Filtered content queries do not support stateful selector: ${selector}`)
+    }
+  }
+
+  return {
+    root,
+    document: inertDocument,
+    capability,
+    selector: capabilitySelector(capability),
+    cloneToLive,
+    liveToClone,
+    original(node) { return cloneToLive.get(node) || null },
+    cloneOf(node) { return liveToClone.get(node) || null },
+    query(selector, queryRoot = root) {
+      assertSelector(selector)
+      return Array.from(queryRoot.querySelectorAll(selector), node => cloneToLive.get(node) || node)
+    },
+    text(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected?.textContent || ''
+    },
+    html(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected?.innerHTML ?? ''
+    },
+    clone(node = root) {
+      const projected = node === root ? root : liveToClone.get(node)
+      return projected ? inertDocument.importNode(projected, true) : null
+    },
+  }
+}
+
+export function cleanContentClone(node, options) {
+  return createContentView(node, options).root
+}

package/src/lib/region-capabilities.js

@@ -0,0 +1,71 @@
+// GENERATED from clayjs/src/lib/region-capabilities.js. Edit ClayJS and run `npm run propagate:foundation`.
+
+export const CAPABILITIES = Object.freeze({
+  data: Object.freeze({ tokens: ['no-data'], bundles: ['editor-ui'] }),
+  save: Object.freeze({ tokens: ['no-save'], bundles: ['editor-ui'] }),
+  snapshot: Object.freeze({ tokens: ['no-snapshot'], bundles: ['editor-ui'] }),
+  watch: Object.freeze({ tokens: ['no-watch'], bundles: ['editor-ui'] }),
+  undo: Object.freeze({ tokens: ['no-undo'], bundles: ['editor-ui'] }),
+  history: Object.freeze({ tokens: [], bundles: ['editor-ui'] }),
+})
+
+export const BUNDLES = Object.freeze({
+  'editor-ui': Object.freeze(['no-data', 'no-save', 'no-snapshot', 'no-watch', 'no-undo']),
+})
+
+export const POLICY_TOKENS = Object.freeze([
+  'no-save',
+  'no-snapshot',
+  'no-trigger-autosave',
+  'no-dirty',
+  'no-watch',
+  'no-undo',
+  'no-data',
+  'freeze',
+  'editor-ui',
+])
+
+export function hasPolicyToken(element, token) {
+  if (!element || element.nodeType !== 1) return false
+  const clay = element.getAttribute?.('clay')
+  return !!(
+    (clay && clay.split(/\s+/).includes(token)) ||
+    element.hasAttribute?.(token)
+  )
+}
+
+export function expandsTo(element, token) {
+  if (hasPolicyToken(element, token)) return true
+  for (const [bundle, members] of Object.entries(BUNDLES)) {
+    if (members.includes(token) && hasPolicyToken(element, bundle)) return true
+  }
+  return false
+}
+
+export function capabilitySelector(capability) {
+  const definition = CAPABILITIES[capability]
+  if (!definition) throw new Error(`Unknown region capability: ${capability}`)
+  return [...definition.tokens, ...definition.bundles]
+    .flatMap(token => [`[clay~="${token}"]`, `[${token}]`])
+    .join(', ')
+}
+
+export function closestWithCapability(node, capability) {
+  let element = node && node.nodeType === 1 ? node : node?.parentElement
+  while (element && element.nodeType === 1) {
+    const definition = CAPABILITIES[capability]
+    if (!definition) throw new Error(`Unknown region capability: ${capability}`)
+    if (definition.tokens.some(token => expandsTo(element, token)) ||
+        definition.bundles.some(bundle => hasPolicyToken(element, bundle))) return element
+    element = element.parentElement
+  }
+  return null
+}
+
+export function hasCapability(node, capability) {
+  return !!closestWithCapability(node, capability)
+}
+
+export function isPolicyAttribute(name) {
+  return name === 'clay' || POLICY_TOKENS.includes(name)
+}

package/src/morph.js

@@ -6,5 +6,6 @@ export function morphForm(formRoot, newFragment, { ignoreActiveValue = true } =
     ignoreActiveValue,
     restoreFocus: true,
     formStateSync: 'property',
+    policy: 'raw',
   })
 }

package/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/src/platform.js

@@ -16,6 +16,11 @@ 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,
@@ -92,6 +97,13 @@ export function platform(name, win) {
 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

package/src/refresh.js

@@ -4,33 +4,47 @@ 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 } from './unresolved.js'
-import { enhanceFields, upgradeRichTextRules } from './enhance.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 } = {}) {
+  return refreshPageForm(ctx, { ignoreActiveValue })
+}
+
+function refreshPageForm(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 rich-text upgrade open() performed: the tag holds the
-    // author's bare rules, and using them raw would rebind upgraded fields
-    // back to textContent mid-session.
-    ctx.pageRules = ctx.richText ? upgradeRichTextRules(found.rules, ctx.pageRoot) : found.rules
+    // 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),
+    engine.extract(ctx.pageRoot, ctx.pageRules, { ...ENGINE_OPTS, ...seeder.hooks }),
     ctx.pageRules
   )
   const fragment = buildForm({
@@ -40,9 +54,10 @@ export function refreshForm(ctx, { ignoreActiveValue } = {}) {
     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)
+  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).
@@ -57,14 +72,16 @@ export function installObserver({ debounce = 100, onRefresh }) {
   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
-  const unsub = M.onAnyChange({ debounce }, () => {
-    if (paused > 0) return
-    onRefresh()
+  // 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) => {
+    onRefresh(changes)
   })
   return {
     unsubscribe: typeof unsub === 'function' ? unsub : () => {},
-    pause() { paused++ },
-    resume() { paused = Math.max(0, paused - 1) },
   }
 }

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