@panphora/hyper-cms 0.4.2 → 0.6.0

package/src/form-builder.js

@@ -3,9 +3,29 @@ import {
   isInlineTemplate,
   humanize,
   shapeKindOf,
+  componentForScalarRule,
+  componentForScalarArrayRule,
+  winningScalarArrayComponent,
+  resolveTemplate,
+  declaredComponentKey,
+  readOptionsOverride,
+  readCropOverride,
 } from './templates.js'
 import { fieldPropertyFor } from './form-rules.js'
 
+// The visible label for a file field is the basename of its URL value; the
+// bound leaf still carries the full URL in href so it round-trips byte-stable.
+export function fileNameFromUrl(url) {
+  if (!url) return ''
+  const clean = String(url).split(/[?#]/)[0]
+  const base = clean.split('/').pop() || clean
+  try {
+    return decodeURIComponent(base)
+  } catch {
+    return base
+  }
+}
+
 export function buildForm({ pageRules, formRules: _formRules, data, doc }) {
   const fragment = doc.createDocumentFragment()
   const root = buildNode(pageRules, [], data, doc)
@@ -13,30 +33,60 @@ export function buildForm({ pageRules, formRules: _formRules, data, doc }) {
   return fragment
 }
 
-export function buildItem({ shape, itemShape, pathArr, data, doc }) {
+export function buildItem({ shape, itemShape, pathArr, data, doc, itemKey }) {
   if (shape === 'object-array-item') {
     return buildObjectArrayItem(itemShape, pathArr, data, doc)
   }
   if (shape === 'scalar-array-item') {
-    return buildScalarArrayItem(pathArr, data, doc)
+    return buildScalarArrayItem(pathArr, data, doc, itemKey || null)
   }
   throw new Error(`hypercms: buildItem called with unknown shape "${shape}"`)
 }
 
 function buildNode(rule, pathArr, data, doc) {
   const kind = shapeKindOf(rule)
-  if (kind === 'scalar') return buildScalar(pathArr, data, doc)
+  if (kind === 'scalar') return buildScalar(rule, pathArr, data, doc)
   if (kind === 'object') return buildObject(rule, pathArr, data, doc)
   if (kind === 'object-array') return buildObjectArray(rule, pathArr, data, doc)
   if (kind === 'scalar-array') return buildScalarArray(rule, pathArr, data, doc)
   return null
 }
 
-function buildScalar(pathArr, data, doc) {
-  const tpl = resolveTemplate(pathArr, '@scalar', doc)
+function buildScalar(rule, pathArr, data, doc) {
+  // Opt-in components select a richer template off the bound rule (explicit
+  // data-hcms-component, then @prop inference); plain scalars stay @scalar.
+  // A path-bound template override still wins inside resolveTemplate.
+  const componentKey = componentForScalarRule(rule, doc, pathArr)
+  const tpl = resolveTemplate(pathArr, componentKey, doc)
   if (!tpl) throw new Error(`hypercms: missing template for scalar at "${pathArr.join('.')}"`)
+  const declaredKey = declaredComponentKey(rule, doc)
+  // A value-guard fell back to text: say so, or "where did my number input /
+  // checkbox go" has no answer.
+  if (declaredKey === '@number' && componentKey === '@scalar') {
+    console.info(
+      `[hypercms] field "${pathArr.join('.')}" declares component "@number" but its value isn't a plain number; rendering a text input so the value is preserved`
+    )
+  }
+  if ((declaredKey === '@checkbox' || declaredKey === '@toggle') && componentKey === '@scalar') {
+    console.info(
+      `[hypercms] field "${pathArr.join('.')}" declares component "${declaredKey}" but its value isn't true/false; rendering a text input so the value is preserved`
+    )
+  }
+  noteShadowedComponent(tpl, declaredKey === componentKey ? declaredKey : null, pathArr)
   const node = cloneTemplate(tpl, doc)
   stampPath(node, pathArr)
+  // Component-specific setup runs only when the component's own template won —
+  // a custom path/wildcard template that shadows it is the author's UI, and
+  // injecting options, dropping radio rows, or stamping crop into it would
+  // corrupt that UI.
+  const winnerKey = tpl.getAttribute?.('data-hcms-tpl')
+  if ((componentKey === '@select' || componentKey === '@radio') && winnerKey === componentKey) {
+    populateOptions(node, rule, pathArr, data, doc, componentKey)
+  }
+  if (componentKey === '@image' && winnerKey === '@image') {
+    const crop = readCropOverride(rule, doc)
+    if (crop != null && !node.hasAttribute('data-hcms-crop')) node.setAttribute('data-hcms-crop', crop)
+  }
   // Stamp leaf input(s) FIRST so the container's data-hcms-field doesn't
   // make stampScalarField early-return (which would leave the input without
   // a key).
@@ -45,9 +95,103 @@ function buildScalar(pathArr, data, doc) {
   stampContainerField(node, lastKey(pathArr))
   setLabel(node, lastKey(pathArr))
   populateScalarValue(node, data)
+  if (componentKey === '@file') syncFileLeafText(node)
   return node
 }
 
+// A custom template (exact or wildcard path) outranks a named component, by
+// design: the author's template is the stronger signal. Surface the shadowing
+// so "my data-hcms-component does nothing" has a visible answer — but only for
+// EXPLICITLY declared components (declaredKey non-null): a custom template
+// quietly outranking @src/@checked inference is unremarkable.
+function noteShadowedComponent(tpl, declaredKey, pathArr) {
+  if (!declaredKey) return
+  const winner = tpl.getAttribute?.('data-hcms-tpl')
+  if (winner && winner !== declaredKey) {
+    console.info(
+      `[hypercms] field "${pathArr.join('.')}" declares component "${declaredKey}" but custom template "${winner}" wins`
+    )
+  }
+}
+
+// Fill a @select's <select> with <option>s, or clone a @radio's prototype row
+// per option, from the page element's data-hcms-options tokens. The current
+// page value is prepended when it isn't in the list, so opening the editor
+// never silently changes data. Radio inputs get a per-field name derived from
+// the path so sibling fields (and array items) never cross-group.
+function populateOptions(node, rule, pathArr, data, doc, componentKey) {
+  const provided = readOptionsOverride(rule, doc)
+  const values = provided ? [...provided] : []
+  const current = data == null ? '' : String(data)
+  if (current !== '' && !values.includes(current)) values.unshift(current)
+  if (!provided) {
+    // Missing data-hcms-options is an authoring error: surface it ALWAYS, not
+    // just when the page value is empty too. When a value exists, fall through
+    // and render it as the single option so the data still round-trips while
+    // the attribute is missing.
+    setFieldError(node, 'data-hcms-options required (space-separated values)')
+    if (values.length === 0) {
+      // No options AND no value: drop the radio prototype so no phantom empty
+      // row renders. The null/'' extract this leaves behind applies as ''
+      // (writePropOrAttr), matching the already empty page value, so no data
+      // moves.
+      node.querySelector('.mirk-radio')?.remove()
+      return
+    }
+  }
+  if (componentKey === '@select') {
+    const select = node.querySelector('select[data-hcms-field]')
+    if (!select) return
+    for (const v of values) {
+      const opt = doc.createElement('option')
+      opt.value = v
+      opt.textContent = humanize(v)
+      select.appendChild(opt)
+    }
+    return
+  }
+  const proto = node.querySelector('.mirk-radio')
+  if (!proto || !proto.parentNode) return
+  const name = radioGroupName(pathArr.join('.'))
+  for (const v of values) {
+    const row = proto.cloneNode(true)
+    const input = row.querySelector('input[type="radio"]')
+    if (input) {
+      input.value = v
+      input.name = name
+    }
+    const label = row.querySelector('.mirk-radio__label')
+    if (label) label.textContent = humanize(v)
+    proto.parentNode.insertBefore(row, proto)
+  }
+  proto.remove()
+}
+
+// The radio group name a field at this dot-path gets. Shared with the restamp
+// machinery in events.js: names derive from paths, so when a remove/move
+// restamps paths, the names must be recomputed with the same formula or
+// sibling items end up sharing a group.
+export function radioGroupName(pathStr) {
+  return 'hcms-' + String(pathStr).replace(/[^A-Za-z0-9_-]/g, '-')
+}
+
+function setFieldError(node, message) {
+  const slot = node.querySelector ? node.querySelector('.hcms-error') : null
+  if (!slot) return
+  slot.textContent = message
+  slot.hidden = false
+}
+
+// The @file leaf is an <a> whose value is the href; populateScalarValue sets
+// href but not the visible text, so derive the filename here. Empty href leaves
+// the anchor empty, which the theme's :empty placeholder dresses as "No file
+// chosen". Scoped to the default chrome's .mirk-file__name so author overrides
+// keep their own text.
+function syncFileLeafText(node) {
+  const a = node.querySelector ? node.querySelector('a.mirk-file__name[data-hcms-field]') : null
+  if (a) a.textContent = fileNameFromUrl(a.getAttribute('href'))
+}
+
 function buildObject(rule, pathArr, data, doc) {
   const tpl = resolveTemplate(pathArr, '@object', doc)
   if (!tpl) throw new Error(`hypercms: missing template for object at "${pathArr.join('.')}"`)
@@ -120,27 +264,41 @@ function buildObjectArrayItem(itemShape, pathArr, data, doc) {
 }
 
 function buildScalarArray(rule, pathArr, data, doc) {
-  const tpl = resolveTemplate(pathArr, '@scalar-array', doc)
+  // The chips component swaps the scalar-array chrome (data-hcms-component=
+  // "chips" on the list container or an item ancestor). A path-bound template
+  // still wins inside resolveTemplate — and when it does, `comp` is null
+  // (winningScalarArrayComponent shares that verdict with deriveFormRules, so
+  // the item chrome and the derived item selector can never diverge) and the
+  // custom template's own UI is left untouched.
+  const declared = componentForScalarArrayRule(rule, doc)
+  const comp = winningScalarArrayComponent(rule, pathArr, doc)
+  const defaultKey = declared ? declared.array : '@scalar-array'
+  const tpl = resolveTemplate(pathArr, defaultKey, doc)
   if (!tpl) throw new Error(`hypercms: missing template for scalar-array at "${pathArr.join('.')}"`)
+  // chips is always an explicit declaration (attr-driven), so always notable.
+  noteShadowedComponent(tpl, declared ? declared.array : null, pathArr)
   const node = cloneTemplate(tpl, doc)
   stampPath(node, pathArr)
   stampContainerField(node, lastKey(pathArr))
   setLabel(node, lastKey(pathArr))
   copyArrayConstraintAttrs(node, tpl)
   wireSortable(node, tpl, pathArr)
+  // Record the resolved item-template key so onAdd (which has no rule context)
+  // builds new items with the same component chrome.
+  if (comp) node.setAttribute('data-hcms-item-tpl', comp.item)
 
   const slot = requireSlot(node, '.hcms-array-items', tpl, pathArr)
   const items = Array.isArray(data) ? data : []
   items.forEach((itemValue, i) => {
-    const itemNode = buildScalarArrayItem([...pathArr, i], itemValue, doc)
+    const itemNode = buildScalarArrayItem([...pathArr, i], itemValue, doc, comp ? comp.item : null)
     if (itemNode) slot.appendChild(itemNode)
   })
   applyConstraintVisibility(node)
   return node
 }
 
-function buildScalarArrayItem(pathArr, value, doc) {
-  const tpl = resolveItemTemplate(pathArr, 'scalar-array-item', doc)
+function buildScalarArrayItem(pathArr, value, doc, itemKey) {
+  const tpl = resolveItemTemplate(pathArr, 'scalar-array-item', doc, itemKey)
   if (!tpl) throw new Error(`hypercms: missing item template for "${pathArr.join('.')}"`)
   const node = cloneTemplate(tpl, doc)
   node.setAttribute('data-hcms-array-item', '')
@@ -151,21 +309,15 @@ function buildScalarArrayItem(pathArr, value, doc) {
   return node
 }
 
-function resolveTemplate(pathArr, defaultKey, doc) {
-  const pathStr = pathArr.join('.')
+function resolveItemTemplate(pathArr, defaultShape, doc, itemKey) {
   const wildcardKey = pathArr.map((s) => (typeof s === 'number' ? '*' : s)).join('.')
   return (
-    (pathStr && findTemplate(doc, pathStr)) ||
-    (wildcardKey && wildcardKey !== pathStr && findTemplate(doc, wildcardKey)) ||
-    findTemplate(doc, defaultKey)
+    findTemplate(doc, wildcardKey) ||
+    (itemKey && findTemplate(doc, itemKey)) ||
+    findTemplate(doc, '@' + defaultShape)
   )
 }
 
-function resolveItemTemplate(pathArr, defaultShape, doc) {
-  const wildcardKey = pathArr.map((s) => (typeof s === 'number' ? '*' : s)).join('.')
-  return findTemplate(doc, wildcardKey) || findTemplate(doc, '@' + defaultShape)
-}
-
 function cloneTemplate(tpl, doc) {
   const content = tpl.content || tpl
   const wrapper = doc.createElement('div')

package/src/form-rules.js

@@ -1,4 +1,10 @@
-import { shapeKindOf, findTemplate, isInlineTemplate } from './templates.js'
+import {
+  shapeKindOf,
+  findTemplate,
+  isInlineTemplate,
+  componentForScalarRule,
+  winningScalarArrayComponent,
+} from './templates.js'
 
 const TAG_PROP_MAP = {
   IMG: 'src',
@@ -79,7 +85,7 @@ export function deriveFormRules(pageRules, doc) {
   function derive(rule, pathArr) {
     const kind = shapeKindOf(rule)
     if (kind === 'scalar') return scalarRule(rule, pathArr)
-    if (kind === 'scalar-array') return scalarArrayRule(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)
@@ -99,21 +105,29 @@ export function deriveFormRules(pageRules, doc) {
     const fieldKey = typeof key === 'string' ? key : '__value'
     const inlineEl = findInlineFieldEl(pathArr, fieldKey)
     if (inlineEl) return fieldSelectorFor(inlineEl, fieldKey)
-    // No path-bound override: look up the actual @scalar template (which
-    // sites may override globally with e.g. <textarea>) and derive the
-    // selector from its leaf tag instead of assuming <input>.
-    const shapeEl = findShapeFieldEl('@scalar', 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), fieldKey)
     if (shapeEl) return fieldSelectorFor(shapeEl, fieldKey)
     return `input[data-hcms-field="${cssEscape(fieldKey)}"]@value`
   }
 
-  function scalarArrayRule(pathArr) {
+  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.
-    const shapeEl = findShapeFieldEl('@scalar-array-item', null)
+    // 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]
   }

package/src/hypercms-bundle.js

@@ -1,7 +1,10 @@
 import * as core from './hypercms.js'
-import stylesText from './styles.css'
+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(stylesText)
+core.installStyles(themeText)
 
 export const cms = core.cms
 export default { cms: core.cms }

package/src/hypercms.js

@@ -2,7 +2,7 @@ import { engine } from 'hyper-html-api'
 import * as pathUtil from './path.js'
 import { scaffold } from './scaffold.js'
 import { morphForm } from './morph.js'
-import { injectDefaults } from './templates.js'
+import { injectDefaults, injectComponents } from './templates.js'
 import { deriveFormRules } from './form-rules.js'
 import { buildForm } from './form-builder.js'
 import {
@@ -104,6 +104,7 @@ export function open(opts = {}) {
   const rulesTagNode = found.tagNode
 
   injectDefaults(doc)
+  injectComponents(doc, pageRules)
   warnUnmatchedTemplates(doc, pageRules)
   const formRules = deriveFormRules(pageRules, doc)
   const data = coerceBooleans(engine.extract(pageRoot, pageRules, { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }), pageRules)
@@ -116,6 +117,9 @@ export function open(opts = {}) {
     side: opts.side || 'right',
     overlay: !!opts.overlay,
     showSaveButton: !!opts.showSaveButton,
+    title: opts.title,
+    eyebrow: opts.eyebrow,
+    theme: opts.theme,
     doc,
   }))
 
@@ -136,12 +140,12 @@ export function open(opts = {}) {
     livesyncUnsub: null,
     onChange: opts.onChange,
     onError: opts.onError,
-    onSave: opts.onSave,
+    confirmRemove: opts.confirmRemove,
     previouslyFocused: doc.activeElement,
     dispatch(name, detail) {
       const Ctor = (doc.defaultView && doc.defaultView.CustomEvent) || (typeof CustomEvent !== 'undefined' ? CustomEvent : null)
       if (!Ctor) return
-      const ev = new Ctor(name, { bubbles: true, cancelable: name === 'hcms:change' || name === 'hcms:save', detail })
+      const ev = new Ctor(name, { bubbles: true, cancelable: name === 'hcms:change', detail })
       shell.root.dispatchEvent(ev)
     },
     onCloseRequested() {
@@ -152,6 +156,13 @@ export function open(opts = {}) {
     ctx.lastFingerprint = stableStringify(extractFormData(ctx))
   }
 
+  // Everything past the shell mount 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 shell in the DOM with no way to close it (close()
+  // early-returns while state.isOpen is false). Tear down whatever was wired,
+  // exactly as close() does, then rethrow so host misuse still fails loudly.
+  try {
   const fragment = buildForm({ pageRules, formRules, data, doc })
   shell.formRoot.appendChild(fragment)
 
@@ -169,7 +180,26 @@ export function open(opts = {}) {
   // the active field. Guarded so it degrades to today's behavior when undo isn't loaded.
   const u = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.undo) || null
   if (u && typeof u.on === 'function') {
-    const onRevert = () => resyncForm(ctx, 'undo')
+    const onRevert = () => {
+      if (state.ctx !== ctx) return
+      resyncForm(ctx, 'undo')
+      // A reverted change the consumer persists through onChange (e.g. the
+      // collection dashboard PUTs the record, not the page) would otherwise lag
+      // the undo: refreshForm re-syncs the form but never fires onChange, and a
+      // commit() here would be fingerprint-skipped (refreshForm already updated
+      // it). Extract the reverted state from the PAGE (the source of truth after
+      // an undo/redo; the form can lag a morph) and fire onChange directly, but
+      // only when it actually changed — guards spurious PUTs on undo/redo of
+      // unrelated edits elsewhere on the page.
+      const data = coerceBooleans(
+        engine.extract(ctx.pageRoot, ctx.pageRules, { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }),
+        ctx.pageRules
+      )
+      if (stableStringify(data) !== stableStringify(ctx.lastData)) {
+        ctx.lastData = data
+        ctx.onChange?.(data, { path: '', structural: false })
+      }
+    }
     u.on('undo', onRevert)
     u.on('redo', onRevert)
     ctx.undoUnsub = () => { u.off('undo', onRevert); u.off('redo', onRevert) }
@@ -199,6 +229,19 @@ export function open(opts = {}) {
   state.opts = opts
 
   ctx.dispatch('hcms:open', { pageRoot })
+  } catch (err) {
+    ctx.observerHandle?.unsubscribe?.()
+    ctx.undoUnsub?.()
+    ctx.livesyncUnsub?.()
+    ctx.detachEvents?.()
+    if (globalCommitTarget.ctx === ctx) globalCommitTarget.ctx = null
+    suppressUndo(() => shell.destroy())
+    state.isOpen = false
+    state.ctx = null
+    state.shell = null
+    state.opts = null
+    throw err
+  }
 }
 
 function focusFirstIn(root) {
@@ -232,11 +275,57 @@ function installGlobalSortableCommit(doc) {
   }
 }
 
+// The query param that drives ?cms=true auto-open. Closing the CMS rewrites it
+// to cms=false (param kept) so a refresh/share of the post-close URL does not
+// auto-reopen.
+const AUTO_OPEN_PARAM = 'cms'
+
+// Pure: given a location.search string, return the search string after a close.
+// Only rewrites when cms=true is present; every other param + ordering is
+// preserved, and a search without cms (or already cms=false) is returned
+// unchanged so we never inject the param into a page that never carried it.
+export function nextSearchAfterClose(search) {
+  const str = typeof search === 'string' ? search : ''
+  const qIndex = str.indexOf('?')
+  const query = qIndex === -1 ? str : str.slice(qIndex + 1)
+  if (!query) return str
+  const params = new URLSearchParams(query)
+  if (params.get(AUTO_OPEN_PARAM) !== 'true') return str
+  params.set(AUTO_OPEN_PARAM, 'false')
+  return '?' + params.toString()
+}
+
+// Pure: should the CMS auto-open for this location.search? Exactly 'true'.
+export function shouldAutoOpenFromSearch(search) {
+  const str = typeof search === 'string' ? search : ''
+  const qIndex = str.indexOf('?')
+  const query = qIndex === -1 ? str : str.slice(qIndex + 1)
+  if (!query) return false
+  return new URLSearchParams(query).get(AUTO_OPEN_PARAM) === 'true'
+}
+
+// Rewrite ?cms=true → ?cms=false via history.replaceState (no reload, hash and
+// every other param preserved). No-op when the param isn't present or the
+// History API is unavailable.
+function toggleCloseParam() {
+  if (typeof window === 'undefined' || !window.location || !window.history) return
+  if (typeof window.history.replaceState !== 'function') return
+  const current = window.location.search
+  const next = nextSearchAfterClose(current)
+  if (next === current) return
+  window.history.replaceState(window.history.state, '', next + window.location.hash)
+}
+
 export function close() {
   if (!state.isOpen) return
   const { ctx, shell } = state
+  // Mark this ctx dead so any in-flight async work (e.g. an upload awaiting the
+  // host uploader) bails instead of mutating the page / firing onChange after
+  // teardown. Mirrors the state.ctx !== ctx guards on the undo/livesync paths.
+  ctx.closed = true
   const previouslyFocused = ctx.previouslyFocused
   ctx.dispatch('hcms:close', null)
+  toggleCloseParam()
   ctx.observerHandle?.unsubscribe?.()
   ctx.undoUnsub?.()
   ctx.livesyncUnsub?.()
@@ -373,6 +462,110 @@ function writeFieldValue(el, value, formRoot, path) {
   el.textContent = value == null ? '' : String(value)
 }
 
+// ?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 warns + returns if 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 && !!(window.hyperclay && window.hyperclay.Mutation)
+}
+
+// Three layers, in order of preference:
+//   1. Sync fast-path: if <body> and Mutation are already here, fire now.
+//   2. Event: hyperclayjs's mutation.js dispatches 'hyperclay:mutation-ready' the
+//      instant it installs window.hyperclay.Mutation. 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
+  const finish = () => {
+    if (done) return
+    done = true
+    if (timer !== null) clearInterval(timer)
+    document.removeEventListener('hyperclay:mutation-ready', onMutationReady)
+  }
+  function onMutationReady() {
+    if (state.isOpen) {
+      finish()
+      return
+    }
+    if (autoOpenReady()) {
+      finish()
+      fn()
+    }
+    // Body may still be pending — the one-shot listener is already consumed,
+    // so only the backstop remains to catch it once body arrives.
+  }
+  document.addEventListener('hyperclay:mutation-ready', onMutationReady, { once: true })
+  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 — window.hyperclay.Mutation never appeared. ' +
+        'Load hyperclayjs (or 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()
+
 const cms = {
   open,
   close,

package/src/refresh.js

@@ -1,7 +1,7 @@
 import { engine } from 'hyper-html-api'
 import { buildForm } from './form-builder.js'
 import { morphForm } from './morph.js'
-import { injectDefaults } from './templates.js'
+import { injectDefaults, injectComponents } from './templates.js'
 import { deriveFormRules } from './form-rules.js'
 import { coerceBooleans, applyErrorState } from './events.js'
 
@@ -18,6 +18,7 @@ export function refreshForm(ctx, { ignoreActiveValue } = {}) {
   }
   // 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)
 
   const newData = coerceBooleans(