@panphora/bevel 0.1.0

package/examples/components/reference/sources/hypercms/src/form-rules.js

@@ -0,0 +1,208 @@
+import {
+  shapeKindOf,
+  findTemplate,
+  isInlineTemplate,
+  componentForScalarRule,
+  winningScalarArrayComponent,
+} from './templates.js'
+
+const TAG_PROP_MAP = {
+  IMG: 'src',
+  A: 'href',
+}
+
+export function fieldPropertyFor(el) {
+  if (!el) return 'value'
+  const tag = (el.tagName || '').toUpperCase()
+  if (tag === 'INPUT') {
+    const type = (el.getAttribute('type') || 'text').toLowerCase()
+    if (type === 'checkbox') return 'checked'
+    return 'value'
+  }
+  if (tag === 'TEXTAREA' || tag === 'SELECT') return 'value'
+  if (TAG_PROP_MAP[tag]) return TAG_PROP_MAP[tag]
+  // Rich-text surfaces (the @richtext component): the value IS the markup.
+  if (el.hasAttribute && el.hasAttribute('contenteditable')) return 'innerHTML'
+  return null
+}
+
+// Tag-specific scalar field selector. Returns a selector that uniquely
+// identifies the leaf input under data-hcms-field="key" — necessary because
+// data-hcms-field is now stamped on every keyed node (containers + leaves),
+// so a bare `[data-hcms-field="key"]` would match the wrapping container too.
+export function fieldSelectorFor(el, key) {
+  const tag = (el.tagName || '').toUpperCase()
+  const type = (el.getAttribute && el.getAttribute('type') || '').toLowerCase()
+  const prop = fieldPropertyFor(el)
+  const tagSel = tagSelectorFor(tag, type)
+  const fieldSel = `${tagSel}[data-hcms-field="${cssEscape(key)}"]`
+  if (tag === 'INPUT' && type === 'radio') {
+    return `${fieldSel}:checked@value`
+  }
+  if (prop) return `${fieldSel}@${prop}`
+  return fieldSel
+}
+
+// Build a per-item leaf selector with no key qualifier — used by scalar-array
+// rules where the leaf is scoped by the surrounding per-item context, so the
+// data-hcms-field key isn't needed (and items don't have a stable key anyway).
+function keylessFieldSelectorFor(el) {
+  const tag = (el.tagName || '').toUpperCase()
+  const type = (el.getAttribute && el.getAttribute('type') || '').toLowerCase()
+  const prop = fieldPropertyFor(el)
+  const tagSel = tagSelectorFor(tag, type)
+  const base = `${tagSel}[data-hcms-field]`
+  if (tag === 'INPUT' && type === 'radio') return `${base}:checked@value`
+  if (prop) return `${base}@${prop}`
+  return base
+}
+
+function tagSelectorFor(tag, type) {
+  if (tag === 'INPUT') {
+    if (type) return `input[type="${type}"]`
+    return 'input'
+  }
+  if (tag === 'TEXTAREA') return 'textarea'
+  if (tag === 'SELECT') return 'select'
+  if (tag === 'IMG') return 'img'
+  if (tag === 'A') return 'a'
+  // Custom/unknown element (e.g. contenteditable div) — match by attribute
+  // and exclude every container shape (scalar wrapper too) so the wrapping
+  // node never shadows the inner leaf. v0.3 stamps data-hcms-field on the
+  // scalar wrapper as well, so omitting `scalar` here would otherwise match
+  // the wrapper first and extract its full text instead of the leaf's.
+  return ':not([data-hcms-shape="scalar"]):not([data-hcms-shape="object"]):not([data-hcms-shape="object-array"]):not([data-hcms-shape="scalar-array"])'
+}
+
+function cssEscape(value) {
+  if (typeof CSS !== 'undefined' && CSS.escape) return CSS.escape(value)
+  return String(value).replace(/[^a-zA-Z0-9_\-.*]/g, (c) => '\\' + c)
+}
+
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+export function deriveFormRules(pageRules, doc) {
+  return derive(pageRules, [])
+
+  function derive(rule, pathArr) {
+    const kind = shapeKindOf(rule)
+    if (kind === 'scalar') return scalarRule(rule, pathArr)
+    if (kind === 'scalar-array') return scalarArrayRule(rule, pathArr)
+    if (kind === 'object-array') return objectArrayRule(rule, pathArr)
+    if (kind === 'object') {
+      const out = Object.create(null)
+      for (const [k, child] of Object.entries(rule)) {
+        if (FORBIDDEN_KEYS.has(k)) {
+          throw new Error(`hypercms: rule key "${k}" is forbidden at "${pathArr.join('.') || '<root>'}"`)
+        }
+        out[k] = derive(child, [...pathArr, k])
+      }
+      return out
+    }
+    return null
+  }
+
+  function scalarRule(rule, pathArr) {
+    const key = pathArr.length ? pathArr[pathArr.length - 1] : null
+    const fieldKey = typeof key === 'string' ? key : '__value'
+    const inlineEl = findInlineFieldEl(pathArr, fieldKey)
+    if (inlineEl) return fieldSelectorFor(inlineEl, fieldKey)
+    // No path-bound override: resolve the component this rule opts into
+    // (@scalar / @image / @file) and derive the selector from THAT template's
+    // leaf tag, so an @image field reads img@src and an @file field reads
+    // a@href, while a plain scalar still respects a global @scalar override
+    // (e.g. a <textarea>) instead of assuming <input>.
+    const shapeEl = findShapeFieldEl(componentForScalarRule(rule, doc, pathArr, pageRules), fieldKey)
+    if (shapeEl) return fieldSelectorFor(shapeEl, fieldKey)
+    return `input[data-hcms-field="${cssEscape(fieldKey)}"]@value`
+  }
+
+  function scalarArrayRule(rule, pathArr) {
+    // The engine's "selector[]" form is text-only; for an editable form we need
+    // per-item @value reads, so emit the [selector, shape] form with a scalar
+    // shape that targets the inner field's value property. If the site
+    // overrides @scalar-array-item with a non-<input> leaf (textarea, etc.),
+    // derive the inner-leaf selector from the override. A component array
+    // (chips) derives from its own item template first — but only when the
+    // chips template actually wins at this path (winningScalarArrayComponent
+    // is the same verdict buildScalarArray uses, so the derived item selector
+    // always matches the rendered item leaf).
+    const comp = winningScalarArrayComponent(rule, pathArr, doc)
+    const shapeEl =
+      (comp && findShapeFieldEl(comp.item, null)) || findShapeFieldEl('@scalar-array-item', null)
+    const itemSel = shapeEl ? keylessFieldSelectorFor(shapeEl) : 'input[data-hcms-field]@value'
+    return [itemSelectorFor(pathArr, '[data-hcms-array-item]'), itemSel]
+  }
+
+  function objectArrayRule(rule, pathArr) {
+    const [, itemShape] = rule
+    const itemPath = [...pathArr, '*']
+    const itemSelector = itemSelectorFor(pathArr, '[data-hcms-card]')
+    if (itemShape && typeof itemShape === 'object' && !Array.isArray(itemShape)) {
+      const obj = Object.create(null)
+      for (const [k, child] of Object.entries(itemShape)) {
+        if (FORBIDDEN_KEYS.has(k)) {
+          throw new Error(`hypercms: rule key "${k}" is forbidden at "${itemPath.join('.')}"`)
+        }
+        obj[k] = derive(child, [...itemPath, k])
+      }
+      return [itemSelector, obj]
+    }
+    return [itemSelector, derive(itemShape, [...itemPath, 0])]
+  }
+
+  // Build a selector that scopes item matching to the right array container.
+  // Top-level paths use exact data-hcms-path match. Nested paths use the
+  // stable data-hcms-field key (which the form-builder stamps on every keyed
+  // container) — this disambiguates sibling arrays that share a terminal key
+  // (e.g. products.*.primary.variants vs products.*.secondary.variants would
+  // both have a `variants` array with the same last segment).
+  function itemSelectorFor(pathArr, itemTag) {
+    const lastKey = pathArr.length ? pathArr[pathArr.length - 1] : ''
+    const hasWildcard = pathArr.some((s) => s === '*')
+    const pathStr = pathArr.join('.')
+    const containerSel = hasWildcard
+      ? `[data-hcms-field="${cssEscape(lastKey)}"]`
+      : `[data-hcms-path="${cssEscape(pathStr)}"]`
+    return `${containerSel} > .hcms-array-items > ${itemTag}`
+  }
+
+  // Look up the field leaf inside a shape-default template (@scalar,
+  // @scalar-array-item, etc.). Sites can override these globally, so the
+  // selector emitted must reflect the actual leaf tag/type, not assume input.
+  // Returns null if the template isn't found or has no [data-hcms-field].
+  function findShapeFieldEl(shapeKey, fieldKey) {
+    if (!doc) return null
+    const tpl = findTemplate(doc, shapeKey)
+    if (!tpl) return null
+    const content = tpl.content || tpl
+    if (fieldKey) {
+      const keyed = content.querySelector(`[data-hcms-field="${cssEscape(fieldKey)}"]`)
+      if (keyed) return keyed
+    }
+    return content.querySelector('[data-hcms-field]')
+  }
+
+  function findInlineFieldEl(pathArr, fieldKey) {
+    if (!doc) return null
+    const wildcardKey = pathArr.map((s) => (typeof s === 'number' ? '*' : s)).join('.')
+    const pathStr = pathArr.join('.')
+    const candidates = [pathStr, wildcardKey]
+    for (let i = pathArr.length - 1; i >= 0; i--) {
+      const slice = pathArr.slice(0, i).map((s) => (typeof s === 'number' ? '*' : s))
+      slice.push('*')
+      candidates.push(slice.join('.'))
+    }
+    for (const key of candidates) {
+      if (!key) continue
+      const tpl = findTemplate(doc, key)
+      if (!tpl || !isInlineTemplate(tpl)) continue
+      const content = tpl.content || tpl
+      const el =
+        content.querySelector(`[data-hcms-field="${cssEscape(fieldKey)}"]`) ||
+        content.querySelector('[data-hcms-field]')
+      if (el) return el
+    }
+    return null
+  }
+}

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

@@ -0,0 +1,100 @@
+// The two clone hooks hypercms installs on the host client, and the retry that
+// covers a client arriving after hypercms does.
+//
+// Their own module rather than private state inside hypercms.js, because the
+// inline view has to install the snapshot hook too: by the time someone clicks
+// a heading the client is certainly loaded, which makes the bind the reliable
+// second trigger for a page that lost the readiness race. Importing that back
+// out of the entry module would have made the entry module part of a cycle.
+
+import { platform, onPlatformEvent, PLATFORM_READY } from './platform.js'
+import { BOUND_ID_ATTR, cleanRichClayFromSnapshot, pristineMarkupFor } from './richclay-bridge.js'
+import { SESSION_OPEN_CLASS } from './shell.js'
+
+// Strip hypercms's own body chrome from the SAVE clone so it never reaches disk
+// (the shell element itself is [save-remove], but the hcms-open class lives on
+// <body>, outside the stripped subtree). Registered once at first open():
+// onPrepareForSave runs save-only, on a clone, so it never touches the live DOM,
+// and removing absent classes is a no-op when the shell is closed. Guarded so it
+// degrades cleanly when the host save pipeline (hyperclayjs) isn't present.
+let prepareHookInstalled = false
+export function installSavePrepareHook() {
+  if (prepareHookInstalled) return
+  const onPrepareForSave = platform('onPrepareForSave')
+  if (typeof onPrepareForSave !== 'function') return
+  onPrepareForSave((clonedDocEl) => {
+    restorePristineMarkup(clonedDocEl)
+    stripSessionChrome(clonedDocEl)
+  })
+  prepareHookInstalled = true
+}
+
+// hypercms's own chrome lives on <body>, outside the [save-remove] shell, so it
+// has to be taken off the clone by hand. Both hooks call this: the save hook
+// because a client may offer onPrepareForSave and no onSnapshot, and the
+// snapshot hook because that is the only one live sync reaches, and without it
+// the session's own classes are broadcast to every other browser. Removing an
+// absent class is a no-op, so running twice on a save costs nothing.
+function stripSessionChrome(clonedDocEl) {
+  const b = clonedDocEl && clonedDocEl.querySelector && clonedDocEl.querySelector('body')
+  if (b) b.classList.remove('hcms-open', 'hcms-overlay', 'hcms-side-left', SESSION_OPEN_CLASS)
+}
+
+// A save can land while somebody is mid-session with an editor open on a
+// heading. richclay rewrites a block's markup simply by being attached to it, so
+// without this the file records that rewriting as though the author had typed
+// it. The live editors are deliberately untouched: this is the clone, and the
+// person editing keeps their caret and their selection.
+function restorePristineMarkup(clonedDocEl) {
+  if (!clonedDocEl || typeof clonedDocEl.querySelectorAll !== 'function') return
+  for (const el of clonedDocEl.querySelectorAll(`[${BOUND_ID_ATTR}]`)) {
+    const html = pristineMarkupFor(el)
+    if (html !== null) el.innerHTML = html
+    el.removeAttribute(BOUND_ID_ATTR)
+  }
+}
+
+// Clean up after the richclay instances hypercms itself creates on page
+// elements. Installed once at first open, alongside the save-prepare hook above,
+// and for the same reason: the host client may not be loaded yet at module
+// evaluation. onSnapshot rather than onPrepareForSave, because this has to run
+// for live sync too — a hook on the save-only path fires after the editor's
+// leftovers have already been broadcast to every other browser.
+let snapshotHookInstalled = false
+export function installSnapshotHook() {
+  if (snapshotHookInstalled) return
+  const onSnapshot = platform('onSnapshot')
+  if (typeof onSnapshot !== 'function') return
+  onSnapshot((clonedDocEl) => {
+    restorePristineMarkup(clonedDocEl)
+    cleanRichClayFromSnapshot(clonedDocEl, typeof window !== 'undefined' ? window : null)
+    stripSessionChrome(clonedDocEl)
+  })
+  snapshotHookInstalled = true
+}
+
+// What open() calls: install both, and arm the retry when either could not be
+// installed yet.
+export function installHooks() {
+  installSavePrepareHook()
+  installSnapshotHook()
+  if (!prepareHookInstalled || !snapshotHookInstalled) armHookRetry()
+}
+
+// Both hooks read a capability that can arrive after hypercms does, and both
+// return without recording success when it is missing. Retry on the clients'
+// readiness pair and disarm once both are in, so a page that lost the import
+// race still gets its clone cleanup.
+let offPlatformReady = null
+function armHookRetry() {
+  if (offPlatformReady || typeof document === 'undefined') return
+  const retry = () => {
+    installSavePrepareHook()
+    installSnapshotHook()
+    if (prepareHookInstalled && snapshotHookInstalled) {
+      offPlatformReady?.()
+      offPlatformReady = null
+    }
+  }
+  offPlatformReady = onPlatformEvent(document, PLATFORM_READY, retry)
+}

package/examples/components/reference/sources/hypercms/src/hypercms-bundle.js

@@ -0,0 +1,10 @@
+import * as core from './hypercms.js'
+import themeText from './theme.generated.css'
+// Install mirk's delegated component runtime (tags chips, number stepper, etc.)
+// as a side effect. Idempotent + document-delegated, so safe to include once.
+import './vendor/mirk.vendor.js'
+
+core.installStyles(themeText)
+
+export const cms = core.cms
+export default { cms: core.cms }

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

@@ -0,0 +1,347 @@
+import { engine } from 'hyper-html-api'
+import * as pathUtil from './path.js'
+import { scaffold } from './scaffold.js'
+import { morphForm } from './morph.js'
+import {
+  commit,
+  commitWithUndo,
+  onAdd as evOnAdd,
+  onRemove as evOnRemove,
+  extractFormData,
+  restampAllSiblings,
+} from './events.js'
+import { setShellStyles, markStylesBundled } from './shell.js'
+import { createSidebarView } from './views/sidebar.js'
+import { createInlineView } from './views/inline.js'
+import {
+  state,
+  createSession,
+  startSession,
+  teardownSession,
+  nextSearchAfterClose,
+  shouldAutoOpenFromSearch,
+} from './session.js'
+import { findLeafField, writeFieldValue } from './events.js'
+import { maybeInjectToggle } from './toggle.js'
+import { platform, onPlatformEvent, MUTATION_READY } from './platform.js'
+import { installHooks } from './hooks.js'
+
+export { nextSearchAfterClose, shouldAutoOpenFromSearch }
+// The leaf-write pair api.setValue is built on. Exported because the inline
+// view's text commit writes the same form leaf from the page element, and a
+// second copy of this logic is how the two paths drift apart.
+export { findLeafField, writeFieldValue }
+
+export function installStyles(text) {
+  setShellStyles(text)
+}
+
+export function markBundledStyles(doc) {
+  markStylesBundled(doc)
+}
+
+// The views a session can be rendered through. A name that is not in here is a
+// caller error, never a fallback: silently opening a sidebar when someone asked
+// for the inline editor would read as the inline editor being broken.
+const VIEWS = {
+  sidebar: createSidebarView,
+  inline: createInlineView,
+}
+
+export function open(opts = {}) {
+  // Everything that can be rejected is rejected before anything is destroyed. A
+  // bad view name or a missing page must not leave a caller with the session
+  // they had already torn down.
+  // A bare open() means "make sure the editor is up", not "put it in the
+  // sidebar". Defaulting to sidebar turned every such call into a view switch.
+  const viewName = opts.view || (state.isOpen ? state.ctx.view.name : 'sidebar')
+  const makeView = VIEWS[viewName]
+  if (!makeView) {
+    throw new Error(`hypercms: unknown view "${viewName}" (expected ${Object.keys(VIEWS).join(' or ')})`)
+  }
+  // A switch changes the presentation of one session, not the session. Someone
+  // calling open({ view: 'sidebar' }) means "show me this in the sidebar"; they
+  // are not restating the pageRoot, the rules and the callbacks they opened
+  // with. Resolving those from this call alone silently retargets the CMS at
+  // document.body with the default rules tag and stops calling onChange.
+  // state.opts holds the active session's options and teardown clears it, so it
+  // has to be read here, before anything is torn down.
+  const effective = state.isOpen ? { ...state.opts, ...opts, view: viewName } : opts
+
+  const pageRoot = effective.pageRoot || (typeof document !== 'undefined' ? document.body : null)
+  if (!pageRoot) throw new Error('hypercms: no pageRoot available')
+  const doc = pageRoot.ownerDocument || (typeof document !== 'undefined' ? document : null)
+  if (!doc) throw new Error('hypercms: no document available')
+
+  // Reopening the view that is already up is a silent no-op, not a warning: a
+  // host wiring a button to open({ view }) should be able to call it without
+  // first asking what is open. Switching views tears the old one down WITHOUT
+  // the close-only side effects — no hcms:close URL rewrite, no focus restore —
+  // because a switch is one continuous session from the person's side, not a
+  // close followed by an open.
+  let carriedFocus = null
+  let previous = null
+  if (state.isOpen) {
+    if (state.ctx.view.name === viewName) return
+    carriedFocus = state.ctx.previouslyFocused
+    previous = state.ctx.view.name
+    teardownSession(state.ctx, { restoreFocus: false, updateUrl: false, reason: 'switch' })
+  }
+
+  installHooks()
+
+  const view = makeView({ doc, pageRoot, opts: effective })
+  const ctx = createSession({
+    view,
+    doc,
+    pageRoot,
+    opts: effective,
+    onCloseRequested: () => close(),
+    onViewRequested: (name) => open({ view: name }),
+  })
+  // Where focus was before the FIRST open, carried across the switch. Closing
+  // the second view should return the person where they started, not to
+  // whatever held focus after the first view was pulled out from under them.
+  if (carriedFocus) ctx.previouslyFocused = carriedFocus
+
+  // Everything past here touches the live DOM, the module-level state, and
+  // external subscriptions (observer, undo, livesync). A throw in here — most
+  // notably installObserver when window.hyperclay.Mutation isn't loaded — would
+  // otherwise strand the mounted view in the DOM with no way to close it (close()
+  // early-returns while state.isOpen is false). Tear down whatever was wired,
+  // without the close-only side effects (no hcms:close, no URL rewrite, no focus
+  // restore), then rethrow so host misuse still fails loudly.
+  try {
+    view.mount(ctx.initialData)
+    startSession(ctx)
+    view.focusOnOpen()
+
+    state.isOpen = true
+    state.ctx = ctx
+    state.opts = effective
+
+    ctx.dispatch('hcms:open', { pageRoot, previous })
+  } catch (err) {
+    // A failed switch already destroyed the view that was up, so nothing is
+    // mounted and nothing can be reopened; the least bad outcome is handing
+    // focus back where it started. On a first open focus never moved, so
+    // restoring it there would be a no-op either way.
+    teardownSession(ctx, { dispatch: false, restoreFocus: !!carriedFocus, updateUrl: false })
+    throw err
+  }
+}
+
+export function close() {
+  if (!state.isOpen) return
+  teardownSession(state.ctx)
+}
+
+export function refresh() {
+  if (!state.isOpen) return
+  state.ctx.view.refresh('api')
+}
+
+export function isOpen() {
+  return state.isOpen
+}
+
+// Which view owns the active session. Nothing may infer this from
+// body.hcms-open, which describes only the sidebar's page shift and says nothing
+// about an inline session.
+export function currentView() {
+  return state.isOpen && state.ctx ? state.ctx.view.name : null
+}
+
+export const api = {
+  getData() {
+    if (!state.isOpen) return null
+    return extractFormData(state.ctx)
+  },
+  setValue(path, value) {
+    if (!state.isOpen) throw new Error('hypercms: cms is not open')
+    const ctx = state.ctx
+    const pathArr = pathUtil.fromString(path)
+    const rule = pathUtil.getRuleAtPath(ctx.pageRules, pathArr)
+    if (rule === undefined) throw new Error(`hypercms: no rule at path "${path}"`)
+    if (typeof rule !== 'string' || rule.endsWith('[]')) {
+      throw new Error(`hypercms: setValue requires a leaf scalar path; "${path}" is not a leaf`)
+    }
+    const field = findLeafField(ctx.formRoot, path)
+    if (!field) throw new Error(`hypercms: no field element at path "${path}"`)
+    writeFieldValue(field, value, ctx.formRoot, path)
+    commit(extractFormData(ctx), { path, structural: false }, ctx)
+  },
+  addItem(arrayPath) {
+    if (!state.isOpen) throw new Error('hypercms: cms is not open')
+    evOnAdd(arrayPath, state.ctx)
+  },
+  removeItem(itemPath) {
+    if (!state.isOpen) throw new Error('hypercms: cms is not open')
+    const ctx = state.ctx
+    const pathArr = pathUtil.fromString(itemPath)
+    // Validate path: must be an array item — last segment is a non-negative
+    // integer, parent rule must be an array (object-array or scalar-array).
+    const lastSeg = pathArr[pathArr.length - 1]
+    if (typeof lastSeg !== 'number') {
+      throw new Error(`hypercms: removeItem requires an item path; "${itemPath}" is not an array index`)
+    }
+    const parentRule = pathUtil.getRuleAtPath(ctx.pageRules, pathArr.slice(0, -1))
+    const parentIsArray = Array.isArray(parentRule) || (typeof parentRule === 'string' && parentRule.endsWith('[]'))
+    if (!parentIsArray) {
+      throw new Error(`hypercms: removeItem requires an item path; parent of "${itemPath}" is not an array`)
+    }
+    const itemEl = ctx.formRoot.querySelector(`[data-hcms-path="${cssEscape(itemPath)}"]`)
+    if (!itemEl) throw new Error(`hypercms: no element at path "${itemPath}"`)
+    evOnRemove(itemEl, ctx)
+  },
+  refresh,
+  _commit() {
+    if (!state.isOpen) return
+    const ctx = state.ctx
+    restampAllSiblings(ctx.formRoot)
+    return commitWithUndo('Update', () =>
+      commit(extractFormData(ctx), { path: '', structural: true }, ctx)
+    )
+  },
+}
+
+// ?cms=true auto-open. When the page URL carries cms=true at load, open the CMS
+// for everyone (no gating — this is a feature showcase; a non-admin's edits stay
+// DOM-local and the host save path shows its view-mode notice). open() is
+// idempotent-safe (it returns quietly if the same view is already open), so a
+// host that also calls open() never double-mounts. No special opts — host
+// defaults apply.
+//
+// Patience matters here: this runs at module load from the dist IIFE, which a
+// host typically loads BEFORE installing window.hyperclay.Mutation (the Mutation
+// install often sits behind an `await import(...)` that resumes after this script,
+// even after DOMContentLoaded). open() needs <body> AND Mutation, so we poll for
+// both rather than firing eagerly. Firing without Mutation would throw out of
+// installObserver, escape module evaluation, and abort esbuild's
+// window.hypercms assignment — taking the host's own wiring down with it.
+const SAFETY_POLL_MS = 250
+const AUTO_OPEN_DEADLINE_MS = 10000
+export function maybeAutoOpen() {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return
+  if (!shouldAutoOpenFromSearch(window.location ? window.location.search : '')) return
+  if (state.isOpen) return
+  whenReady(() => {
+    if (state.isOpen) return
+    try {
+      open()
+    } catch (err) {
+      console.warn('hypercms: auto-open failed', err)
+    }
+  })
+}
+
+// Auto-open is ready only once <body> is parsed AND window.hyperclay.Mutation is
+// installed (open() needs both). NEVER throw out of module scope.
+function autoOpenReady() {
+  return !!document.body && !!platform('Mutation')
+}
+
+// Three layers, in order of preference:
+//   1. Sync fast-path: if <body> and Mutation are already here, fire now.
+//   2. Event: both clients dispatch a mutation-ready signal the instant they
+//      install the mutation hub, under two spellings ('clay:mutation-ready' and
+//      'hyperclay:mutation-ready'), so hypercms listens for both and dedups. On
+//      loader pages this is moot — the loader's first wave evaluates mutation
+//      before hypercms, so the fast-path wins — but the event catches any late
+//      install (the deferred `await import()` ordering). The body gate is
+//      re-checked in the handler because the event can land before <body> is
+//      parsed.
+//   3. Backstop: a slow self-cancelling 250ms poll for exotic hosts that hand-roll
+//      window.hyperclay.Mutation by direct assignment WITHOUT dispatching the
+//      event. It cancels the moment the event fires, open succeeds, or the
+//      deadline is hit (warn, never throw).
+function whenReady(fn) {
+  if (autoOpenReady()) {
+    // Defer one microtask. On the bundled entry (hypercms-bundle.js), installStyles()
+    // runs AFTER this module evaluates, so firing open() synchronously here would
+    // mount the shell with cssText still empty (an unstyled sidebar). A microtask
+    // runs only after the synchronous bundle evaluation completes, by which point
+    // styles are installed. The event/backstop paths below already fire post-eval,
+    // so only this fast path needed deferring.
+    queueMicrotask(fn)
+    return
+  }
+  const deadline = Date.now() + AUTO_OPEN_DEADLINE_MS
+  let done = false
+  let timer = null
+  let offMutationReady = null
+  const finish = () => {
+    if (done) return
+    done = true
+    if (timer !== null) clearInterval(timer)
+    if (offMutationReady) offMutationReady()
+  }
+  function onMutationReady() {
+    if (state.isOpen) {
+      finish()
+      return
+    }
+    if (autoOpenReady()) {
+      finish()
+      fn()
+    }
+    // Body may still be pending. Unlike the old one-shot listener this stays
+    // subscribed, so a later dispatch is still caught and the backstop is no
+    // longer the only remaining path.
+  }
+  offMutationReady = onPlatformEvent(document, MUTATION_READY, onMutationReady)
+  timer = setInterval(() => {
+    if (state.isOpen) {
+      finish()
+      return
+    }
+    if (autoOpenReady()) {
+      finish()
+      fn()
+      return
+    }
+    if (Date.now() >= deadline) {
+      finish()
+      console.warn(
+        'hypercms: ?cms=true auto-open gave up — no mutation hub appeared. ' +
+        'Load clayjs or hyperclayjs (or just the mutation utility) so the CMS can initialize.'
+      )
+    }
+  }, SAFETY_POLL_MS)
+}
+
+// Auto-open at module load (browser only — node tests import this without a real
+// window, and the guards above no-op there).
+maybeAutoOpen()
+
+// Floating edit-mode toggle at module load (same browser-only no-op in node).
+maybeInjectToggle({
+  open,
+  close,
+  isOpen,
+  // The same map open() resolves a view name against, so the split button
+  // offers exactly the views this build can actually render.
+  views: Object.keys(VIEWS),
+  hasRules: (doc) => !!engine.findRules(doc, 'cms'),
+})
+
+const cms = {
+  open,
+  close,
+  refresh,
+  api,
+  get isOpen() { return state.isOpen },
+  currentView,
+  // Power-user exports (mostly for testing + advanced integration)
+  path: pathUtil,
+  scaffold,
+  morphForm,
+}
+
+function cssEscape(value) {
+  if (typeof CSS !== 'undefined' && CSS.escape) return CSS.escape(value)
+  return String(value).replace(/[^a-zA-Z0-9_\-.*]/g, (c) => '\\' + c)
+}
+
+export { cms }
+export default { cms }

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

@@ -0,0 +1,10 @@
+import HyperMorph from 'hyper-morph'
+
+export function morphForm(formRoot, newFragment, { ignoreActiveValue = true } = {}) {
+  HyperMorph.morph(formRoot, newFragment, {
+    morphStyle: 'innerHTML',
+    ignoreActiveValue,
+    restoreFocus: true,
+    formStateSync: 'property',
+  })
+}