@panphora/hyper-cms 0.6.2 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/hyper-cms",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Live edit-in-place CMS sidebar for HTML pages with a hyper-html-api rules tag",
   "keywords": [
     "HTML",
@@ -35,6 +35,7 @@
     "build": "npm run build:theme && npx esbuild src/hypercms-bundle.js --bundle --minify --format=iife --global-name=hypercms --loader:.css=text --outfile=dist/hypercms.min.js",
     "prepublishOnly": "npm run build",
     "copy-to-hyperclayjs": "npm run build && node scripts/copy-to-hyperclayjs.js",
+    "copy-to-clayjs": "npm run build && node scripts/copy-to-clayjs.js",
     "test:node": "node --test 'test-node/**/*.test.js'",
     "test": "npm run test:node",
     "demo": "http-server . -p 5694 -c-1 -o /demo/",
@@ -43,7 +44,7 @@
     "test:all": "npm run test:node && npm run test:browser"
   },
   "dependencies": {
-    "hyper-html-api": "^0.5.2",
+    "hyper-html-api": "^0.6.1",
     "hyper-morph": "^0.4.0"
   },
   "devDependencies": {

package/src/enhance.js

@@ -9,6 +9,9 @@
 // whose element holds only text are left untouched. Hosts opt out with
 // cms.open({ richText: false }).
 
+import { platform } from './platform.js'
+import { ruleAttrIndex } from 'hyper-html-api/engine'
+
 export function upgradeRichTextRules(rules, pageRoot) {
   if (!pageRoot || rules == null) return rules
   return walk(rules)
@@ -16,7 +19,7 @@ export function upgradeRichTextRules(rules, pageRoot) {
   function walk(rule) {
     if (typeof rule === 'string') {
       if (rule.endsWith('[]')) return rule
-      if (rule.lastIndexOf('@') >= 0) return rule
+      if (ruleAttrIndex(rule) !== -1) return rule
       let el = null
       try {
         el = pageRoot.querySelector(rule)
@@ -61,7 +64,7 @@ export function enhanceFields(root, doc) {
   const win = (doc && doc.defaultView) || (typeof window !== 'undefined' ? window : null)
   const RichClay =
     (win && win.richclay && win.richclay.RichClay) ||
-    (win && win.hyperclay && win.hyperclay.RichClay) ||
+    platform('RichClay', win) ||
     (win && typeof win.RichClay === 'function' ? win.RichClay : null)
   if (!RichClay) return
 

package/src/events.js

@@ -4,6 +4,7 @@ import { fromString as pathFromString, getRuleAtPath } from './path.js'
 import { buildItem, fileNameFromUrl, radioGroupName } from './form-builder.js'
 import { scaffold } from './scaffold.js'
 import { autosizeTextarea, enhanceFields } from './enhance.js'
+import { platform } from './platform.js'
 
 const BOUND = new WeakSet()
 
@@ -15,7 +16,7 @@ const BOUND = new WeakSet()
 //
 // 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
+  const u = platform('undo')
   if (!u) return fn()
   u.pause()
   try {
@@ -36,7 +37,7 @@ export function commitWithUndo(label, fn) {
 // 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
+  const u = platform('undo')
   if (!u) return fn()
   u.pause()
   try {
@@ -148,7 +149,7 @@ function resolveUnobservedProjection(ctx, pathStr) {
   if (fullPath.some((seg) => typeof seg === 'number' || seg === '*')) return null
   const rule = getRuleAtPath(ctx.pageRules, fullPath)
   if (typeof rule !== 'string') return null
-  const at = rule.lastIndexOf('@')
+  const at = engine.ruleAttrIndex(rule)
   if (at === -1) return null                       // text projection — observed
   const prop = rule.slice(at + 1)
   if (!UNOBSERVED_FIELD_PROPS.has(prop)) return null
@@ -167,7 +168,7 @@ export function onScalarChange(target, ctx) {
   const proj = resolveUnobservedProjection(ctx, pathStr)
   commit(extractFormData(ctx), { path: pathStr, structural: false }, ctx)
   if (proj) {
-    const u = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.undo) || null
+    const u = platform('undo')
     if (u && typeof u.recordValue === 'function') {
       u.recordValue(proj.el, { prop: proj.prop, oldValue: proj.oldValue, newValue: proj.el[proj.prop] })
     }
@@ -186,7 +187,7 @@ const CROP_OUTPUT = { type: 'image/webp', quality: 0.85, maxWidth: 2048, maxHeig
 async function maybeCrop(file, fieldEl) {
   const attr = fieldEl && fieldEl.getAttribute ? fieldEl.getAttribute('data-hcms-crop') : null
   if (attr == null) return { file }
-  const crop = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.quickcrop) || null
+  const crop = platform('quickcrop')
   if (typeof crop !== 'function') return { file }
   try {
     const r = await crop(file, { aspect: parseCropAspect(attr), ...CROP_OUTPUT })
@@ -245,7 +246,7 @@ export async function onUploadChange(inputEl, ctx) {
   const fileLike = cropped.file
   const previewDataUrl = cropped.dataURL || null
 
-  const upload = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.uploadFileBasic) || null
+  const upload = platform('uploadFileBasic')
   let url = null
   if (typeof upload === 'function') {
     try {
@@ -440,7 +441,7 @@ export function requestRemove(itemEl, ctx) {
   const arrayEl = itemEl.closest('[data-hcms-shape="object-array"], [data-hcms-shape="scalar-array"]')
   const message = resolveRemoveConfirm(arrayEl, ctx)
   if (message == null) return onRemove(itemEl, ctx)
-  const consent = typeof window !== 'undefined' && (window.hyperclay?.consent || window.consent)
+  const consent = platform('consent') || (typeof window !== 'undefined' && window.consent)
   if (typeof consent === 'function') {
     Promise.resolve(consent(message)).then(() => onRemove(itemEl, ctx), () => {})
   } else if (typeof window !== 'undefined' && typeof window.confirm === 'function') {

package/src/hypercms.js

@@ -20,8 +20,10 @@ import {
 import { mountShell, setShellStyles, markStylesBundled } from './shell.js'
 import { refreshForm, installObserver } from './refresh.js'
 import { warnUnmatchedTemplates } from './diagnostics.js'
+import { findUnresolved, applyUnresolvedState } from './unresolved.js'
 import { enhanceFields, upgradeRichTextRules } from './enhance.js'
 import { maybeInjectToggle } from './toggle.js'
+import { platform, onPlatformEvent, MUTATION_READY, LIVESYNC_APPLIED } from './platform.js'
 
 export function installStyles(text) {
   setShellStyles(text)
@@ -72,8 +74,7 @@ function resyncForm(ctx, reason) {
 let prepareHookInstalled = false
 function installSavePrepareHook() {
   if (prepareHookInstalled) return
-  const onPrepareForSave =
-    (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.onPrepareForSave) || null
+  const onPrepareForSave = platform('onPrepareForSave')
   if (typeof onPrepareForSave !== 'function') return
   onPrepareForSave((clonedDocEl) => {
     const b = clonedDocEl && clonedDocEl.querySelector && clonedDocEl.querySelector('body')
@@ -114,6 +115,9 @@ export function open(opts = {}) {
   injectComponents(doc, pageRules)
   warnUnmatchedTemplates(doc, pageRules)
   const formRules = deriveFormRules(pageRules, doc)
+  // Runs before the first extract so a rule with invalid CSS names its field
+  // instead of throwing a bare SyntaxError out of querySelectorAll.
+  const unresolved = findUnresolved(pageRoot, pageRules)
   const data = coerceBooleans(engine.extract(pageRoot, pageRules, { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }), pageRules)
 
   // Suppress undo around mountShell: it toggles chrome-only classes on
@@ -141,6 +145,9 @@ export function open(opts = {}) {
     formRoot: shell.formRoot,
     shellRoot: shell.root,
     errorEl: shell.errorEl,
+    noticeEl: shell.noticeEl,
+    unresolved,
+    lastTwinSignature: null,
     lastFingerprint: null,
     lastData: null,
     observerHandle: null,
@@ -174,6 +181,7 @@ export function open(opts = {}) {
   const fragment = buildForm({ pageRules, formRules, data, doc })
   shell.formRoot.appendChild(fragment)
   enhanceFields(shell.formRoot, doc)
+  applyUnresolvedState(ctx)
 
   bindEvents(ctx)
   ctx.updateFingerprint()
@@ -187,7 +195,7 @@ export function open(opts = {}) {
   // is source-blind, so subscribe to the undo scope and force a non-ignoring refresh.
   // Fires synchronously before the debounced observer refresh, which then no-ops on
   // 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
+  const u = platform('undo')
   if (u && typeof u.on === 'function') {
     const onRevert = () => {
       if (state.ctx !== ctx) return
@@ -222,8 +230,7 @@ export function open(opts = {}) {
   // with ignoreActiveValue:true (preserve the user's in-progress field). Same
   // document live-sync dispatches on; unsubscribed in close().
   const onLivesync = () => resyncForm(ctx, 'livesync')
-  doc.addEventListener('hyperclay:livesync-applied', onLivesync)
-  ctx.livesyncUnsub = () => doc.removeEventListener('hyperclay:livesync-applied', onLivesync)
+  ctx.livesyncUnsub = onPlatformEvent(doc, LIVESYNC_APPLIED, onLivesync)
 
   // Wire global sortable callback to current ctx (replaced by close()).
   globalCommitTarget.ctx = ctx
@@ -507,17 +514,19 @@ export function maybeAutoOpen() {
 // 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)
+  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: 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.
+//   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
@@ -536,11 +545,12 @@ function whenReady(fn) {
   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)
-    document.removeEventListener('hyperclay:mutation-ready', onMutationReady)
+    if (offMutationReady) offMutationReady()
   }
   function onMutationReady() {
     if (state.isOpen) {
@@ -551,10 +561,11 @@ function whenReady(fn) {
       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.
+    // 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.
   }
-  document.addEventListener('hyperclay:mutation-ready', onMutationReady, { once: true })
+  offMutationReady = onPlatformEvent(document, MUTATION_READY, onMutationReady)
   timer = setInterval(() => {
     if (state.isOpen) {
       finish()
@@ -568,8 +579,8 @@ function whenReady(fn) {
     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.'
+        '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)

package/src/platform.js

@@ -0,0 +1,68 @@
+// The optional platform hypercms rides: the mutation hub, undo, the save-prepare
+// hook, rich text, and the two upload helpers. Every one degrades to null, so the
+// CMS still runs in a bare HTML file with no client at all.
+//
+// TWO clients provide this and they disagree on names. hyperclayjs owns
+// window.hyperclay; clayjs owns window.clay and renamed things on the way past
+// (onPrepareForSave -> addDocumentTransform, consent -> confirm). clay.RichClay exists,
+// but quickcrop and uploadFileBasic have no clay equivalent at all, so image crop and
+// file upload silently degrade under clayjs. So this is a capability table
+// rather than a namespace pointer: `window.clay ?? window.hyperclay` would resolve
+// to clay, find no onPrepareForSave, and silently stop stripping the CMS's own
+// chrome out of every save.
+//
+// Reads happen per call, never cached. A client can install a capability after
+// hypercms evaluates — that is the whole reason whenReady() below exists.
+const CAPABILITIES = {
+  Mutation:         (clay, hyperclay) => clay?.Mutation ?? hyperclay?.Mutation,
+  undo:             (clay, hyperclay) => clay?.undo ?? hyperclay?.undo,
+  onPrepareForSave: (clay, hyperclay) => clay?.addDocumentTransform ?? hyperclay?.onPrepareForSave,
+  consent:          (clay, hyperclay) => clay?.confirm ?? hyperclay?.consent,
+  RichClay:         (clay, hyperclay) => clay?.RichClay ?? hyperclay?.RichClay,
+  quickcrop:        (clay, hyperclay) => clay?.quickcrop ?? hyperclay?.quickcrop,
+  uploadFileBasic:  (clay, hyperclay) => clay?.uploadFileBasic ?? hyperclay?.uploadFileBasic,
+}
+
+// Pass `win` when the caller already holds a realm (a doc.defaultView from a form
+// mounted into another document); it defaults to the ambient one.
+export function platform(name, win) {
+  const read = CAPABILITIES[name]
+  if (!read) throw new Error(`hypercms: unknown platform capability "${name}"`)
+  const scope = win || (typeof window !== 'undefined' ? window : null)
+  if (!scope) return null
+  return read(scope.clay, scope.hyperclay) || null
+}
+
+// Both spellings of the same signal. Each client fires exactly one name: clayjs
+// its own, hyperclayjs the legacy one. Listening for both is what lets one build
+// of hypercms ride either client. The name-keyed guard below stays regardless, so
+// a listener on both names still can't double-fire if a client ever dispatches
+// the pair again.
+export const MUTATION_READY = ['clay:mutation-ready', 'hyperclay:mutation-ready']
+export const LIVESYNC_APPLIED = ['clay:sync-applied', 'hyperclay:livesync-applied']
+
+// Subscribe to every spelling of one signal, delivering the handler ONCE per
+// occurrence. No client dispatches the pair today, but one that did would make a
+// plain listener on each name fire the handler twice for one event: two form
+// re-extracts, or two open() calls.
+//
+// The first name to arrive claims the tick, and only a DIFFERENT name is suppressed
+// while it holds the claim. That distinction is what makes this exact rather than a
+// heuristic: no client dispatches one name twice for one occurrence, so a repeat of
+// the claiming name is always a second occurrence and always gets through — even
+// when it lands in the same tick, which is precisely what a caller doing two
+// synchronous applies looks like. Guarding on "have I run at all this tick" would
+// swallow that.
+//
+// Returns an unsubscribe that removes every name.
+export function onPlatformEvent(target, names, handler) {
+  let claimedBy = null
+  const wrapped = (event) => {
+    if (claimedBy !== null && claimedBy !== event.type) return
+    claimedBy = event.type
+    queueMicrotask(() => { claimedBy = null })
+    handler(event)
+  }
+  for (const name of names) target.addEventListener(name, wrapped)
+  return () => { for (const name of names) target.removeEventListener(name, wrapped) }
+}

package/src/refresh.js

@@ -4,7 +4,9 @@ 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 { platform } from './platform.js'
 
 const ENGINE_OPTS = { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }
 
@@ -24,6 +26,8 @@ export function refreshForm(ctx, { ignoreActiveValue } = {}) {
   injectDefaults(ctx.doc)
   injectComponents(ctx.doc, ctx.pageRules)
   ctx.formRules = deriveFormRules(ctx.pageRules, ctx.doc)
+  // Before the extract below, for the same readable-failure reason as open().
+  ctx.unresolved = findUnresolved(ctx.pageRoot, ctx.pageRules)
 
   const newData = coerceBooleans(
     engine.extract(ctx.pageRoot, ctx.pageRules, ENGINE_OPTS),
@@ -43,14 +47,15 @@ export function refreshForm(ctx, { ignoreActiveValue } = {}) {
   // the last error state so error messages survive across observer-driven refreshes
   // (e.g., the rollback after a failed add).
   applyErrorState(ctx)
+  applyUnresolvedState(ctx)
   // Update fingerprint so subsequent commits against the new page state compare correctly.
   if (ctx.updateFingerprint) ctx.updateFingerprint()
 }
 
 export function installObserver({ debounce = 100, onRefresh }) {
-  const M = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.Mutation) || null
+  const M = platform('Mutation')
   if (!M || typeof M.onAnyChange !== 'function') {
-    throw new Error('hypercms: window.hyperclay.Mutation is required. Load hyperclayjs (or just the mutation utility) before initializing hypercms.')
+    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 }, () => {

package/src/shell.js

@@ -79,6 +79,7 @@ export function mountShell({
           <span class="mirk-button__label">×</span>
         </button>
       </header>
+      <div class="hcms-shell-notice" role="status" hidden></div>
       <div class="hcms-shell-error" role="alert" hidden></div>
       <div data-hcms-form-root class="hcms-form"></div>
       <footer class="hcms-shell-footer"${showSaveButton ? '' : ' hidden'}>
@@ -106,6 +107,7 @@ export function mountShell({
   return {
     root,
     formRoot: root.querySelector('[data-hcms-form-root]'),
+    noticeEl: root.querySelector('.hcms-shell-notice'),
     errorEl: root.querySelector('.hcms-shell-error'),
     saveButton: root.querySelector('.hcms-shell-save'),
     destroy() {

package/src/templates.js

@@ -1,3 +1,4 @@
+import { ruleAttrIndex } from 'hyper-html-api/engine'
 import { getRuleAtPath } from './path.js'
 
 export function humanize(key) {
@@ -245,7 +246,7 @@ export function injectComponentTemplate(doc, key) {
 // workflow) and @checked means checkbox (a text input showing the literal word
 // "true" helps nobody). @href is NOT inferred: editing a link/URL is far more
 // common than uploading a file, so an a@href rule stays a plain URL field and
-// the file upload is opt-in. Suffix is split like the engine (lastIndexOf('@'),
+// the file upload is opt-in. Suffix is split like the engine (ruleAttrIndex,
 // see engine/extract.js). Returns a DEFAULT_TEMPLATES key.
 const PROP_TO_COMPONENT = { src: '@image', checked: '@checkbox', innerHTML: '@richtext' }
 // data-hcms-component values for scalar rules. "chips" is array-only (below).
@@ -270,7 +271,7 @@ const ON_DEMAND_COMPONENT_KEYS = new Set([
 
 export function componentForScalarRule(rule, doc, pathArr) {
   if (typeof rule !== 'string') return '@scalar'
-  const at = rule.lastIndexOf('@')
+  const at = ruleAttrIndex(rule)
   const override = readElementAttr(scalarSelectorOf(rule, at), doc, 'data-hcms-component')
   if (override && SCALAR_COMPONENT_BY_NAME[override]) {
     const key = SCALAR_COMPONENT_BY_NAME[override]
@@ -304,7 +305,7 @@ export function componentForScalarRule(rule, doc, pathArr) {
 // logging shadowing notices.
 export function declaredComponentKey(rule, doc) {
   if (typeof rule !== 'string') return null
-  const at = rule.lastIndexOf('@')
+  const at = ruleAttrIndex(rule)
   const name = readElementAttr(scalarSelectorOf(rule, at), doc, 'data-hcms-component')
   return (name && SCALAR_COMPONENT_BY_NAME[name]) || null
 }
@@ -414,7 +415,7 @@ export function winningScalarArrayComponent(rule, pathArr, doc) {
 // data-rules-name idiom); labels derive via humanize() like every other label.
 export function readOptionsOverride(rule, doc) {
   if (typeof rule !== 'string') return null
-  const at = rule.lastIndexOf('@')
+  const at = ruleAttrIndex(rule)
   const raw = readElementAttr(scalarSelectorOf(rule, at), doc, 'data-hcms-options')
   if (raw == null) return null
   const tokens = raw.trim().split(/\s+/).filter(Boolean)
@@ -426,7 +427,7 @@ export function readOptionsOverride(rule, doc) {
 // reads it without a second page lookup.
 export function readCropOverride(rule, doc) {
   if (typeof rule !== 'string') return null
-  const at = rule.lastIndexOf('@')
+  const at = ruleAttrIndex(rule)
   return readElementAttr(scalarSelectorOf(rule, at), doc, 'data-hcms-crop')
 }
 

package/src/theme/pixel-quiet.overrides.css

@@ -484,6 +484,18 @@ body.hcms-open.hcms-overlay { overflow: hidden; }
 .hcms-upload-clear--badge:hover { color: var(--mirk-destructive); border-color: var(--mirk-destructive); }
 .hcms-upload-clear--badge .hcms-x { width: 10px; height: 10px; }
 
+/* ---------- UNRESOLVED-FIELDS NOTICE ---------- */
+.hcms-shell-notice {
+  font-size: 12px;
+  line-height: 1.45;
+  color: var(--mirk-mark-fg);
+  background: var(--mirk-bevel-bg);
+  border: 1px solid var(--mirk-input-border);
+  padding: 8px 12px;
+  margin: 0 24px 8px;
+}
+.hcms-shell-notice[hidden] { display: none; }
+
 /* ---------- ERROR BANNER + inline errors ---------- */
 .hcms-shell-error,
 .hcms-error {

package/src/theme.generated.css

@@ -1495,6 +1495,18 @@ body.hcms-open.hcms-overlay { overflow: hidden; }
 .hcms-upload-clear--badge:hover { color: var(--mirk-destructive); border-color: var(--mirk-destructive); }
 .hcms-upload-clear--badge .hcms-x { width: 10px; height: 10px; }
 
+/* ---------- UNRESOLVED-FIELDS NOTICE ---------- */
+.hcms-shell-notice {
+  font-size: 12px;
+  line-height: 1.45;
+  color: var(--mirk-mark-fg);
+  background: var(--mirk-bevel-bg);
+  border: 1px solid var(--mirk-input-border);
+  padding: 8px 12px;
+  margin: 0 24px 8px;
+}
+.hcms-shell-notice[hidden] { display: none; }
+
 /* ---------- ERROR BANNER + inline errors ---------- */
 .hcms-shell-error,
 .hcms-error {

package/src/unresolved.js

@@ -0,0 +1,142 @@
+import domAdapter from 'hyper-html-api/dom'
+import { ruleAttrIndex } from 'hyper-html-api/engine'
+
+const PREFIX = '[hypercms]'
+
+// The opts every other engine call in hypercms uses: never traverse into the
+// sidebar's own form, never count a [cms-template] seed as content.
+const FIND_OPTS = { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }
+// templateAttr:null includes seeds. An empty list still holding its seed can be
+// grown back from it, so it is not dead.
+const SEED_OPTS = { skip: '[data-hcms-shell]', templateAttr: null }
+
+export class InvalidRuleSelector extends Error {
+  constructor(path, selector, cause) {
+    super(`hypercms: rule at "${path}" has an invalid CSS selector: "${selector}"`)
+    this.name = 'InvalidRuleSelector'
+    this.path = path
+    this.selector = selector
+    this.cause = cause
+  }
+}
+
+// Report a field only when writing to it would be silently discarded, which is
+// exactly when apply() finds no element and returns having done nothing.
+// An extracted null is NOT that test: a present-but-empty attribute reads null
+// too (extract.js readPropOrAttr), and that field saves perfectly. So this
+// resolves each rule's selector and counts matches instead of reading values.
+export function findUnresolved(root, rules) {
+  const missing = []
+  const twins = []
+  walk(root, rules, [], missing, twins)
+  return { missing: unique(missing), twins: uniqueTwins(twins) }
+}
+
+function walk(ctx, rule, path, missing, twins) {
+  if (typeof rule === 'string') {
+    const selector = selectorOf(rule)
+    if (!selector) return
+    const matches = find(ctx, selector, FIND_OPTS, path)
+    if (rule.endsWith('[]')) {
+      if (matches.length === 0 && find(ctx, selector, SEED_OPTS, path).length === 0) {
+        missing.push(pathStr(path))
+      }
+      return
+    }
+    if (matches.length === 0) missing.push(pathStr(path))
+    else if (matches.length > 1) twins.push({ path: pathStr(path), count: matches.length })
+    return
+  }
+
+  if (Array.isArray(rule)) {
+    const [selector, shape] = rule
+    if (typeof selector !== 'string' || !selector) return
+    const matches = find(ctx, selector, FIND_OPTS, path)
+    if (matches.length === 0) {
+      if (find(ctx, selector, SEED_OPTS, path).length === 0) missing.push(pathStr(path))
+      return
+    }
+    // Rows collapse to one '*' segment, so a field broken on every row is
+    // reported once rather than once per row.
+    for (const node of matches) walk(node, shape, [...path, '*'], missing, twins)
+    return
+  }
+
+  if (rule && typeof rule === 'object') {
+    for (const [key, sub] of Object.entries(rule)) walk(ctx, sub, [...path, key], missing, twins)
+  }
+}
+
+function find(ctx, selector, opts, path) {
+  try {
+    return domAdapter.find(ctx, selector, opts)
+  } catch (err) {
+    throw new InvalidRuleSelector(pathStr(path), selector, err)
+  }
+}
+
+// Mirrors the engine's scalar parsing: a trailing [] strips, "." and a leading
+// @ read the context node itself so they can never fail to resolve, and
+// otherwise the selector is the part before the separator @ (the last one that
+// is not inside brackets or quotes, so a mailto address stays in the selector).
+function selectorOf(rule) {
+  if (rule === '.' || rule.startsWith('@')) return null
+  if (rule.endsWith('[]')) return rule.slice(0, -2) || null
+  const at = ruleAttrIndex(rule)
+  return (at === -1 ? rule : rule.slice(0, at)) || null
+}
+
+export function applyUnresolvedState(ctx) {
+  renderNotice(ctx)
+  warnTwins(ctx)
+}
+
+// States the fact and stops. Regenerating a CMS replaces the rules tag
+// wholesale, so a notice that reads as a repair prompt would walk anyone with a
+// hand-edited config into losing it.
+function renderNotice(ctx) {
+  const el = ctx.noticeEl
+  if (!el) return
+  const missing = (ctx.unresolved && ctx.unresolved.missing) || []
+  if (missing.length === 0) {
+    el.textContent = ''
+    el.hidden = true
+    return
+  }
+  const count = missing.length === 1
+    ? '1 field no longer matches this page'
+    : `${missing.length} fields no longer match this page`
+  el.textContent = `${count}: ${missing.join(', ')}`
+  el.hidden = false
+}
+
+// Two elements matching one scalar rule still works, since the write lands on
+// the first, so this is a console note rather than a notice. Runtime duplicates
+// (a carousel cloning slides, a dialog holding a second copy) are ordinary.
+// Signature-gated because the walk reruns on every refresh.
+function warnTwins(ctx) {
+  const twins = (ctx.unresolved && ctx.unresolved.twins) || []
+  const signature = twins.map((t) => `${t.path}:${t.count}`).join('|')
+  if (signature === ctx.lastTwinSignature) return
+  ctx.lastTwinSignature = signature
+  for (const { path, count } of twins) {
+    console.warn(`${PREFIX} "${path}" matches ${count} elements; edits go to the first one.`)
+  }
+}
+
+function unique(list) {
+  return [...new Set(list)]
+}
+
+function uniqueTwins(list) {
+  const byPath = new Map()
+  for (const twin of list) {
+    const seen = byPath.get(twin.path)
+    if (!seen || twin.count > seen.count) byPath.set(twin.path, twin)
+  }
+  return [...byPath.values()]
+}
+
+function pathStr(path) {
+  return path.length ? path.join('.') : '(whole page)'
+}