@panphora/hyper-cms 0.4.0

package/src/apply-loop.js

@@ -0,0 +1,161 @@
+import { engine } from 'hyper-html-api'
+import { fromString as pathFromString, getRuleAtPath } from './path.js'
+
+const ENGINE_OPTS = { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }
+
+// Engine reads/writes against pageRoot pass skip + templateAttr so the
+// engine never traverses into the form's own DOM, and so [cms-template]
+// nodes are treated as seed templates (not real data). Scalar applies skip
+// snapshot — string user input can't produce a ShapeMismatch and the focused
+// input must survive every keystroke.
+//
+// Structural applies (add/remove/reorder) can hit EmptyListInsert and other
+// engine errors. We snapshot just the affected array container's slot so
+// rollback restores only the failing subtree; listeners and state elsewhere
+// on the page survive.
+export function applyWithRollback(pageRoot, pageRules, newData, options = {}) {
+  const { observerHandle, shellRoot, structural, structuralPath } = options
+  observerHandle?.pause?.()
+  try {
+    if (!structural) {
+      try {
+        engine.apply(pageRoot, pageRules, newData, ENGINE_OPTS)
+        return { ok: true }
+      } catch (err) {
+        return { ok: false, error: err }
+      }
+    }
+
+    // Structural path: snapshot the smallest container that the change
+    // touches, falling back to non-shell page content if we can't resolve
+    // a specific container.
+    const target = resolveStructuralTarget(pageRoot, pageRules, structuralPath)
+    const subtreeSnapshot = target ? captureChildren(target) : null
+    const pageSnapshot = target ? null : captureNonShellSnapshot(pageRoot, shellRoot)
+    try {
+      engine.apply(pageRoot, pageRules, newData, ENGINE_OPTS)
+      return { ok: true }
+    } catch (err) {
+      if (subtreeSnapshot) {
+        restoreChildren(target, subtreeSnapshot)
+      } else if (pageSnapshot) {
+        restoreNonShellSnapshot(pageRoot, shellRoot, pageSnapshot)
+      }
+      return { ok: false, error: err }
+    }
+  } finally {
+    observerHandle?.resume?.()
+  }
+}
+
+// Walk pageRules along structuralPath to find the array rule that the change
+// targets, then ask the engine to locate its matching container in pageRoot.
+// Returns the live container element (so its child cards can be snapshotted),
+// or null if the path doesn't resolve to a single array container.
+function resolveStructuralTarget(pageRoot, pageRules, structuralPath) {
+  if (!structuralPath || !pageRoot) return null
+  const segs = pathFromString(structuralPath)
+  // Walk to the array rule. Add/remove paths can be either the array itself
+  // ("products") or an item path ("products.0"); both resolve to the same
+  // array container.
+  let arrPath = []
+  let node = pageRules
+  for (const seg of segs) {
+    if (typeof node === 'string' || node == null) break
+    if (Array.isArray(node)) {
+      // We're at an array — this segment is the index; stop walking, we have
+      // the container.
+      break
+    }
+    if (typeof node === 'object' && seg in node) {
+      arrPath.push(seg)
+      node = node[seg]
+      if (Array.isArray(node) || (typeof node === 'string' && node.endsWith('[]'))) break
+    } else {
+      return null
+    }
+  }
+  if (!Array.isArray(node) && !(typeof node === 'string' && node.endsWith('[]'))) return null
+  // arrPath is the prefix that leads to the array. Walk pageRoot via the
+  // engine using a stripped pageRules so we land on the container.
+  return resolveContainerByPath(pageRoot, pageRules, arrPath)
+}
+
+// Walk pageRoot by following each parent rule's selector until we reach the
+// array container. For paths with no parent (root-level array), use pageRoot
+// itself; otherwise descend through each named rule.
+function resolveContainerByPath(pageRoot, pageRules, arrPath) {
+  if (arrPath.length === 0) return null
+  let ctx = pageRoot
+  let rule = pageRules
+  for (let i = 0; i < arrPath.length; i++) {
+    const key = arrPath[i]
+    if (!rule || typeof rule !== 'object' || Array.isArray(rule)) return null
+    const sub = rule[key]
+    if (sub == null) return null
+    if (i === arrPath.length - 1) {
+      // Final step: the array's selector resolves to ITEMS, not the
+      // container. Walk to the items' shared parent so the snapshot covers
+      // the whole list (cards/scalars siblings). Without this, an object
+      // array's selector like `.product` returns the first item, and
+      // rollback restores only that item's children — leaving any earlier
+      // list-level insert/reorder mutated.
+      if (Array.isArray(sub)) {
+        const [selector] = sub
+        const first = ctx.querySelector?.(selector)
+        return first?.parentElement || null
+      }
+      if (typeof sub === 'string' && sub.endsWith('[]')) {
+        const selector = sub.slice(0, -2)
+        const first = ctx.querySelector?.(selector)
+        return first?.parentElement || null
+      }
+      return null
+    }
+    // Intermediate: must be an object subrule. Engine extract treats objects
+    // as same-ctx, so we don't narrow ctx.
+    rule = sub
+  }
+  return null
+}
+
+function captureChildren(parent) {
+  const clones = []
+  for (const child of Array.from(parent.childNodes)) {
+    clones.push(child.cloneNode(true))
+  }
+  return clones
+}
+
+function restoreChildren(parent, clones) {
+  while (parent.firstChild) parent.removeChild(parent.firstChild)
+  for (const clone of clones) parent.appendChild(clone)
+}
+
+function captureNonShellSnapshot(pageRoot, shellRoot) {
+  const clones = []
+  for (const child of Array.from(pageRoot.childNodes)) {
+    if (child === shellRoot || (shellRoot && child.contains?.(shellRoot))) continue
+    clones.push(child.cloneNode(true))
+  }
+  return clones
+}
+
+function restoreNonShellSnapshot(pageRoot, shellRoot, clones) {
+  for (const child of Array.from(pageRoot.childNodes)) {
+    if (child === shellRoot || (shellRoot && child.contains?.(shellRoot))) continue
+    pageRoot.removeChild(child)
+  }
+  const host = findShellHostChild(pageRoot, shellRoot)
+  for (const clone of clones) {
+    pageRoot.insertBefore(clone, host || null)
+  }
+}
+
+function findShellHostChild(pageRoot, shellRoot) {
+  if (!shellRoot) return null
+  for (const child of Array.from(pageRoot.childNodes)) {
+    if (child === shellRoot || child.contains?.(shellRoot)) return child
+  }
+  return null
+}

package/src/diagnostics.js

@@ -0,0 +1,44 @@
+import { shapeKindOf } from './templates.js'
+
+const PREFIX = '[hypercms]'
+
+export function warnUnmatchedTemplates(doc, pageRules) {
+  if (!doc || !doc.querySelectorAll || !pageRules) return
+  const validKeys = collectValidKeys(pageRules)
+  const tpls = doc.querySelectorAll('template[data-hcms-tpl]')
+  tpls.forEach((tpl) => {
+    const key = tpl.getAttribute('data-hcms-tpl')
+    if (!key) return
+    if (key.startsWith('@')) return
+    if (!validKeys.has(key)) {
+      console.warn(`${PREFIX} template "${key}" doesn't match any rule path; ignored`)
+    }
+  })
+}
+
+function collectValidKeys(pageRules) {
+  const keys = new Set()
+  walk([], pageRules)
+  return keys
+
+  function walk(pathArr, rule) {
+    const pathStr = pathArr.join('.')
+    const wildcardKey = pathArr.map((s) => (typeof s === 'number' ? '*' : s)).join('.')
+    if (pathStr) keys.add(pathStr)
+    if (wildcardKey) keys.add(wildcardKey)
+    const shape = shapeKindOf(rule)
+    if (shape === 'object') {
+      for (const [k, child] of Object.entries(rule)) walk([...pathArr, k], child)
+    } else if (shape === 'object-array' || shape === 'scalar-array') {
+      const itemPath = [...pathArr, '*']
+      const itemWildcardKey = itemPath.map((s) => (typeof s === 'number' ? '*' : s)).join('.')
+      keys.add(itemWildcardKey)
+      if (shape === 'object-array') {
+        const itemRule = rule[1]
+        if (itemRule && typeof itemRule === 'object' && !Array.isArray(itemRule)) {
+          for (const [k, child] of Object.entries(itemRule)) walk([...itemPath, k], child)
+        }
+      }
+    }
+  }
+}

package/src/events.js

@@ -0,0 +1,457 @@
+import { engine } from 'hyper-html-api'
+import { applyWithRollback } from './apply-loop.js'
+import { fromString as pathFromString } from './path.js'
+import { buildItem } from './form-builder.js'
+import { scaffold } from './scaffold.js'
+
+const BOUND = new WeakSet()
+
+// Wraps a structural apply in the pause-before / commit-on-success pattern.
+// Pauses the undo recorder, runs fn, then either commits the captured
+// records (if the apply succeeded) or discards them (if it failed). Either
+// way, the undo stack only ever contains successful applies — never an
+// apply+rollback no-op pair.
+//
+// No-op pass-through when window.hyperclay.undo isn't loaded.
+export function commitWithUndo(label, fn) {
+  const u = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.undo) || null
+  if (!u) return fn()
+  u.pause()
+  try {
+    const result = fn()
+    if (result && result.ok) {
+      u.commitCaptured(label)
+    } else {
+      u.discardCaptured()
+    }
+    return result
+  } finally {
+    u.resume()
+  }
+}
+
+// Runs fn with the undo recorder paused and its captured records discarded, so
+// editor-chrome-only DOM mutations (e.g. the body class toggles the shell adds
+// on mount/unmount) never enter the undo stack. No-op pass-through when undo
+// isn't loaded.
+export function suppressUndo(fn) {
+  const u = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.undo) || null
+  if (!u) return fn()
+  u.pause()
+  try {
+    return fn()
+  } finally {
+    u.discardCaptured()
+    u.resume()
+  }
+}
+
+export function bindEvents(ctx) {
+  const { formRoot } = ctx
+  if (!formRoot || BOUND.has(formRoot)) return
+  BOUND.add(formRoot)
+
+  const onInput = (e) => {
+    const target = e.target
+    if (!target || !target.closest) return
+    if (!target.closest('[data-hcms-form-root]')) return
+    if (!target.matches('input, textarea, select')) return
+    if (!target.closest('[data-hcms-field]') && !target.hasAttribute?.('data-hcms-field')) return
+    onScalarChange(target, ctx)
+  }
+
+  const onChange = (e) => {
+    const target = e.target
+    if (!target || !target.closest) return
+    if (!target.closest('[data-hcms-form-root]')) return
+    if (target.matches('input[type="checkbox"], input[type="radio"], select')) {
+      onScalarChange(target, ctx)
+    }
+  }
+
+  const onClick = (e) => {
+    const target = e.target
+    if (!target || !target.closest) return
+    const actionEl = target.closest('[data-hcms-action]')
+    if (!actionEl) return
+    const action = actionEl.getAttribute('data-hcms-action')
+    // add/remove/move must live inside the form root; close/save inside the shell.
+    // Ignore stray data-hcms-action attributes elsewhere on the page.
+    if (action === 'add' || action === 'remove' || action === 'move-up' || action === 'move-down') {
+      if (!actionEl.closest('[data-hcms-form-root]')) return
+    } else if (action === 'close' || action === 'save') {
+      if (!actionEl.closest('[data-hcms-shell]')) return
+    }
+    if (action === 'add') {
+      const arrayEl = actionEl.closest('[data-hcms-path]')
+      if (!arrayEl) return
+      const arrayPath = arrayEl.getAttribute('data-hcms-path')
+      onAdd(arrayPath, ctx)
+    } else if (action === 'remove') {
+      const itemEl = actionEl.closest('[data-hcms-card], [data-hcms-array-item]')
+      if (!itemEl) return
+      onRemove(itemEl, ctx)
+    } else if (action === 'move-up' || action === 'move-down') {
+      const itemEl = actionEl.closest('[data-hcms-card], [data-hcms-array-item]')
+      if (!itemEl) return
+      onMove(itemEl, action === 'move-up' ? -1 : 1, ctx)
+    } else if (action === 'close') {
+      ctx.onCloseRequested?.()
+    } else if (action === 'save') {
+      onSave(ctx)
+    }
+  }
+
+  const doc = formRoot.ownerDocument
+  doc.addEventListener('input', onInput, true)
+  doc.addEventListener('change', onChange, true)
+  doc.addEventListener('click', onClick, true)
+
+  ctx.detachEvents = () => {
+    doc.removeEventListener('input', onInput, true)
+    doc.removeEventListener('change', onChange, true)
+    doc.removeEventListener('click', onClick, true)
+    BOUND.delete(formRoot)
+  }
+}
+
+export function onScalarChange(target, ctx) {
+  const fieldEl = target.closest('[data-hcms-field]') || target
+  const pathStr = fieldEl.closest('[data-hcms-path]')?.getAttribute('data-hcms-path') || ''
+  commit(extractFormData(ctx), { path: pathStr, structural: false }, ctx)
+}
+
+export function onAdd(arrayPath, ctx) {
+  const { formRoot, pageRules } = ctx
+  const arrayEl = formRoot.querySelector(`[data-hcms-path="${cssEscape(arrayPath)}"]`)
+  if (!arrayEl) throw new Error(`hypercms: no element at path "${arrayPath}"`)
+  const slot = arrayEl.querySelector('.hcms-array-items')
+  if (!slot) throw new Error(`hypercms: array container missing .hcms-array-items at "${arrayPath}"`)
+
+  const pathArr = pathFromString(arrayPath)
+  const ruleAtPath = ruleAt(pageRules, pathArr)
+  const isObjectArray = Array.isArray(ruleAtPath)
+  const isScalarArray = typeof ruleAtPath === 'string' && ruleAtPath.endsWith('[]')
+  if (!isObjectArray && !isScalarArray) throw new Error(`hypercms: path "${arrayPath}" is not an array`)
+
+  const maxItems = readIntAttr(arrayEl, 'data-hcms-max-items')
+  const existingItems = slot.querySelectorAll(':scope > [data-hcms-card], :scope > [data-hcms-array-item]')
+  if (arrayEl.hasAttribute('data-hcms-no-add')) return
+  if (maxItems != null && existingItems.length >= maxItems) return
+  const nextIndex = existingItems.length
+
+  const itemShape = isObjectArray ? ruleAtPath[1] : ruleAtPath.replace(/\[\]$/, '')
+  const itemData = scaffold(isObjectArray ? itemShape : 'string')
+  const itemNode = buildItem({
+    shape: isObjectArray ? 'object-array-item' : 'scalar-array-item',
+    itemShape,
+    pathArr: [...pathArr, nextIndex],
+    data: itemData,
+    doc: ctx.doc,
+  })
+  slot.appendChild(itemNode)
+  updateArrayButtonsVisibility(arrayEl)
+  return commitWithUndo(`Add ${arrayPath}`, () =>
+    commit(extractFormData(ctx), { path: arrayPath, structural: true }, ctx)
+  )
+}
+
+export function onMove(itemEl, direction, ctx) {
+  const arrayEl = itemEl.closest('[data-hcms-shape="object-array"], [data-hcms-shape="scalar-array"]')
+  if (!arrayEl) return
+  if (arrayEl.hasAttribute('data-hcms-no-reorder')) return
+  const slot = arrayEl.querySelector('.hcms-array-items')
+  if (!slot) return
+  const siblings = Array.from(slot.querySelectorAll(':scope > [data-hcms-card], :scope > [data-hcms-array-item]'))
+  const idx = siblings.indexOf(itemEl)
+  if (idx < 0) return
+  const targetIdx = idx + direction
+  if (targetIdx < 0 || targetIdx >= siblings.length) return
+  const moveAction = itemEl.querySelector(`[data-hcms-action="${direction < 0 ? 'move-up' : 'move-down'}"]`)
+  if (direction < 0) {
+    slot.insertBefore(itemEl, siblings[targetIdx])
+  } else {
+    slot.insertBefore(itemEl, siblings[targetIdx].nextSibling)
+  }
+  restampSiblingPaths(slot)
+  updateArrayButtonsVisibility(arrayEl)
+  // Restore focus to the moved button so keyboard users can continue pressing
+  // the same button (now landed in its new position).
+  if (moveAction && typeof moveAction.focus === 'function') {
+    const newAction = itemEl.querySelector(`[data-hcms-action="${direction < 0 ? 'move-up' : 'move-down'}"]`)
+    newAction?.focus?.()
+  }
+  return commitWithUndo(`Reorder ${arrayEl.getAttribute('data-hcms-path') || ''}`, () =>
+    commit(extractFormData(ctx), { path: arrayEl.getAttribute('data-hcms-path') || '', structural: true }, ctx)
+  )
+}
+
+export function onRemove(itemEl, ctx) {
+  const path = itemEl.getAttribute('data-hcms-path') || ''
+  const parent = itemEl.parentElement
+  const arrayEl = itemEl.closest('[data-hcms-shape="object-array"], [data-hcms-shape="scalar-array"]')
+  if (arrayEl?.hasAttribute('data-hcms-no-remove')) return
+  if (arrayEl) {
+    const minItems = readIntAttr(arrayEl, 'data-hcms-min-items')
+    const slot = arrayEl.querySelector('.hcms-array-items')
+    const count = slot
+      ? slot.querySelectorAll(':scope > [data-hcms-card], :scope > [data-hcms-array-item]').length
+      : 0
+    if (minItems != null && count <= minItems) return
+  }
+  itemEl.remove()
+  // After removal, re-stamp sibling paths to keep indices contiguous.
+  if (parent) restampSiblingPaths(parent)
+  if (arrayEl) updateArrayButtonsVisibility(arrayEl)
+  return commitWithUndo(`Remove ${path}`, () =>
+    commit(extractFormData(ctx), { path, structural: true }, ctx)
+  )
+}
+
+export function onSave(ctx) {
+  const data = extractFormData(ctx)
+  ctx.dispatch?.('hcms:save', { data })
+  ctx.onSave?.(data)
+}
+
+export function commit(newData, info, ctx) {
+  const fingerprint = stableStringify(newData)
+  if (fingerprint === ctx.lastFingerprint) return { ok: true, skipped: true }
+
+  const result = applyWithRollback(ctx.pageRoot, ctx.pageRules, newData, {
+    observerHandle: ctx.observerHandle,
+    shellRoot: ctx.shellRoot,
+    structural: !!info.structural,
+    structuralPath: info.path || null,
+  })
+  if (result.ok) {
+    ctx.lastFingerprint = fingerprint
+    ctx.lastData = newData
+    setError(ctx, null)
+    ctx.dispatch?.('hcms:change', { data: newData, path: info.path, structural: !!info.structural })
+    ctx.onChange?.(newData, info)
+  } else {
+    setError(ctx, formatError(result.error, info.path))
+    ctx.dispatch?.('hcms:error', { error: result.error, attemptedData: newData })
+    ctx.onError?.(result.error)
+  }
+  return result
+}
+
+export function extractFormData(ctx) {
+  const raw = engine.extract(ctx.formRoot, ctx.formRules)
+  return coerceBooleans(raw, ctx.formRules)
+}
+
+// Walks either pageRules OR formRules (both use the same `endsWith('@checked')`
+// semantics) and coerces leaf strings "true" / "false" to booleans. Engine
+// extract stringifies @checked properties; the form layer wants real booleans
+// so writeValue's Boolean(value) doesn't flip "false" → true on hydration.
+export function coerceBooleans(data, rules) {
+  if (rules == null || data == null) return data
+  if (typeof rules === 'string') {
+    if (rules.endsWith('@checked')) {
+      return data === true || data === 'true'
+    }
+    return data
+  }
+  if (Array.isArray(rules)) {
+    if (!Array.isArray(data)) return data
+    const [, itemShape] = rules
+    return data.map((item) => coerceBooleans(item, itemShape))
+  }
+  if (typeof rules === 'object') {
+    if (typeof data !== 'object' || Array.isArray(data)) return data
+    const out = {}
+    for (const [k, child] of Object.entries(rules)) {
+      out[k] = coerceBooleans(data[k], child)
+    }
+    return out
+  }
+  return data
+}
+
+export { stableStringify }
+
+// Errors render inline when we can match a path to a slot in the form (a `.hcms-error`
+// direct child of the path's container — added by the default scalar / array templates).
+// A single commit can produce multiple mismatches (ShapeMismatch carries an array); each one
+// tries to land at its own path. Custom templates that omit the slot, and path-less errors,
+// fall back to the global banner (joined when there's more than one).
+function setError(ctx, errors) {
+  ctx.lastErrors = errors && errors.length ? errors : null
+  applyErrorState(ctx)
+}
+
+// Re-apply ctx.lastErrors to the DOM. Exported so refreshForm can call this
+// after morphForm rebuilds the form — the morph wipes inline error slots
+// (they're inside the form), so we restore them post-morph.
+export function applyErrorState(ctx) {
+  clearInlineErrors(ctx)
+  if (ctx.errorEl) {
+    ctx.errorEl.textContent = ''
+    ctx.errorEl.hidden = true
+  }
+  if (!ctx.lastErrors) return
+
+  const unplaced = []
+  for (const { message, path } of ctx.lastErrors) {
+    if (path != null && path !== '') {
+      const target = findInlineErrorSlot(ctx.formRoot, path)
+      if (target) {
+        // Two errors at the same path concatenate into one slot, separated by a newline.
+        target.textContent = target.textContent ? `${target.textContent}\n${message}` : message
+        target.hidden = false
+        continue
+      }
+    }
+    unplaced.push(message)
+  }
+
+  if (unplaced.length && ctx.errorEl) {
+    ctx.errorEl.textContent = unplaced.join('\n')
+    ctx.errorEl.hidden = false
+  }
+}
+
+function clearInlineErrors(ctx) {
+  if (!ctx.formRoot) return
+  for (const el of ctx.formRoot.querySelectorAll('.hcms-error')) {
+    el.textContent = ''
+    el.hidden = true
+  }
+}
+
+function findInlineErrorSlot(formRoot, path) {
+  if (!formRoot) return null
+  // Walk up the path: try the exact match first, then trim the last segment, etc.
+  // Lets deep-path errors land at the nearest ancestor that has a slot — useful when
+  // engine paths go deeper than the form's stamped structure (e.g., migration data).
+  const segs = path.split('.')
+  while (segs.length > 0) {
+    const candidate = segs.join('.')
+    const esc = (typeof CSS !== 'undefined' && CSS.escape) ? CSS.escape(candidate) : candidate.replace(/[^a-zA-Z0-9_\-.*]/g, (c) => '\\' + c)
+    const container = formRoot.querySelector(`[data-hcms-path="${esc}"]`)
+    if (container) {
+      for (const child of container.children) {
+        if (child.classList && child.classList.contains('hcms-error')) return child
+      }
+    }
+    segs.pop()
+  }
+  return null
+}
+
+function formatError(err, fallbackPath) {
+  if (!err) return [{ message: 'unknown error', path: fallbackPath }]
+  if (err.name === 'EmptyListInsert') {
+    return [{ message: 'Add a seed item in HTML first.', path: fallbackPath }]
+  }
+  if (err.name === 'ShapeMismatch' && Array.isArray(err.mismatches) && err.mismatches.length) {
+    return err.mismatches.map((m) => ({
+      message: `Shape mismatch: expected ${m.expected}, got ${m.got}`,
+      path: m.path,
+    }))
+  }
+  return [{ message: err.message || String(err), path: fallbackPath }]
+}
+
+function ruleAt(rules, pathArr) {
+  let node = rules
+  for (const seg of pathArr) {
+    if (node == null) return undefined
+    if (typeof node === 'string') 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
+}
+
+function readIntAttr(el, name) {
+  if (!el || !el.hasAttribute(name)) return null
+  const n = parseInt(el.getAttribute(name), 10)
+  return Number.isFinite(n) ? n : null
+}
+
+export function updateArrayButtonsVisibility(arrayEl) {
+  if (!arrayEl) return
+  const slot = arrayEl.querySelector('.hcms-array-items')
+  if (!slot) return
+  const items = Array.from(slot.querySelectorAll(':scope > [data-hcms-card], :scope > [data-hcms-array-item]'))
+  const count = items.length
+  const max = readIntAttr(arrayEl, 'data-hcms-max-items')
+  const min = readIntAttr(arrayEl, 'data-hcms-min-items')
+  const noAdd = arrayEl.hasAttribute('data-hcms-no-add')
+  const noRemove = arrayEl.hasAttribute('data-hcms-no-remove')
+  const noReorder = arrayEl.hasAttribute('data-hcms-no-reorder')
+  const addBtn = arrayEl.querySelector(':scope > .hcms-add, :scope > * > .hcms-add, :scope > [data-hcms-action="add"]')
+  if (addBtn) addBtn.hidden = noAdd || (max != null && count >= max)
+  items.forEach((item, i) => {
+    const rm = item.querySelector('[data-hcms-action="remove"]')
+    if (rm) rm.hidden = noRemove || (min != null && count <= min)
+    const up = item.querySelector('[data-hcms-action="move-up"]')
+    if (up) up.hidden = noReorder || i === 0
+    const dn = item.querySelector('[data-hcms-action="move-down"]')
+    if (dn) dn.hidden = noReorder || i === count - 1
+  })
+}
+
+export function restampAllSiblings(formRoot) {
+  if (!formRoot || !formRoot.querySelectorAll) return
+  formRoot.querySelectorAll('.hcms-array-items').forEach((slot) => restampSiblingPaths(slot))
+}
+
+function restampSiblingPaths(parent) {
+  let i = 0
+  for (const child of parent.children) {
+    if (!child.matches?.('[data-hcms-card], [data-hcms-array-item]')) continue
+    const path = child.getAttribute('data-hcms-path')
+    if (!path) continue
+    const segs = path.split('.')
+    segs[segs.length - 1] = String(i)
+    const newPath = segs.join('.')
+    if (newPath !== path) restampSubtree(child, path, newPath)
+    i++
+  }
+}
+
+function restampSubtree(root, oldPrefix, newPrefix) {
+  const all = root.querySelectorAll('[data-hcms-path]')
+  root.setAttribute('data-hcms-path', newPrefix)
+  for (const el of all) {
+    const p = el.getAttribute('data-hcms-path')
+    if (p === oldPrefix) {
+      el.setAttribute('data-hcms-path', newPrefix)
+    } else if (p && p.startsWith(oldPrefix + '.')) {
+      el.setAttribute('data-hcms-path', newPrefix + p.slice(oldPrefix.length))
+    }
+  }
+}
+
+function stableStringify(value) {
+  return JSON.stringify(value, (_, v) => {
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      // Use a null-prototype container so `__proto__` keys survive sorting and
+      // serialize as data rather than mutating object prototype.
+      const sorted = Object.create(null)
+      for (const k of Object.keys(v).sort()) sorted[k] = v[k]
+      return sorted
+    }
+    return v
+  })
+}
+
+function cssEscape(value) {
+  if (typeof CSS !== 'undefined' && CSS.escape) return CSS.escape(value)
+  return String(value).replace(/[^a-zA-Z0-9_\-.*]/g, (c) => '\\' + c)
+}