@panphora/hyper-cms 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/hyper-cms",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Live edit-in-place CMS sidebar for HTML pages with a hyper-html-api rules tag",
   "keywords": [
     "HTML",

package/src/enhance.js

@@ -0,0 +1,97 @@
+// Post-mount field enhancements + the rich-text rule upgrade.
+//
+// Bare scalar rules bind textContent, which flattens inline HTML (links,
+// bold, code) on extract and destroys it on the first apply. When the bound
+// page element actually contains child elements, the rule is upgraded to
+// @innerHTML so the round-trip preserves markup and the form renders the
+// @richtext component (a contenteditable surface, richclay-powered when the
+// host page ships richclay). Explicit @prop rules, array rules, and rules
+// whose element holds only text are left untouched. Hosts opt out with
+// cms.open({ richText: false }).
+
+export function upgradeRichTextRules(rules, pageRoot) {
+  if (!pageRoot || rules == null) return rules
+  return walk(rules)
+
+  function walk(rule) {
+    if (typeof rule === 'string') {
+      if (rule.endsWith('[]')) return rule
+      if (rule.lastIndexOf('@') >= 0) return rule
+      let el = null
+      try {
+        el = pageRoot.querySelector(rule)
+      } catch (_) {
+        return rule
+      }
+      return el && el.children.length > 0 ? rule + '@innerHTML' : rule
+    }
+    // Array rules ([itemSelector, shape]) scope their inner selectors per
+    // item; a document-level querySelector can't answer "does THIS item's
+    // element hold markup", so array subtrees are never upgraded.
+    if (Array.isArray(rule)) return rule
+    if (rule && typeof rule === 'object') {
+      const out = Object.create(null)
+      for (const [k, v] of Object.entries(rule)) out[k] = walk(v)
+      return out
+    }
+    return rule
+  }
+}
+
+// Grow a form textarea to fit its content. Browsers with `field-sizing:
+// content` handle this in CSS (the theme sets it); everywhere else the
+// height is pinned to scrollHeight on populate and on every input.
+export function autosizeTextarea(el) {
+  if (!el || el.tagName !== 'TEXTAREA') return
+  const win = el.ownerDocument.defaultView || (typeof window !== 'undefined' ? window : null)
+  if (win && win.CSS && win.CSS.supports && win.CSS.supports('field-sizing: content')) return
+  el.style.height = 'auto'
+  el.style.height = el.scrollHeight + 'px'
+}
+
+// Runs after any form (or form fragment) lands in the live DOM: sizes the
+// autosize fallback and mounts richclay on rich-text surfaces when the host
+// page ships it (window.richclay / window.hyperclay.RichClay). Without
+// richclay the surface stays a plain contenteditable bound via @innerHTML,
+// which still round-trips markup — richclay only adds the editing chrome.
+export function enhanceFields(root, doc) {
+  if (!root || !root.querySelectorAll) return
+  root.querySelectorAll('textarea[data-hcms-field]').forEach(autosizeTextarea)
+
+  const win = (doc && doc.defaultView) || (typeof window !== 'undefined' ? window : null)
+  const RichClay =
+    (win && win.richclay && win.richclay.RichClay) ||
+    (win && win.hyperclay && win.hyperclay.RichClay) ||
+    (win && typeof win.RichClay === 'function' ? win.RichClay : null)
+  if (!RichClay) return
+
+  root.querySelectorAll('[contenteditable][data-hcms-field]').forEach((el) => {
+    if (el.__hcmsRichclay) return
+    let editor
+    try {
+      // hyperclay:false keeps the form field out of the page's save/undo
+      // machinery (page writes go through commit) and activates the editor
+      // regardless of the host's edit-mode signal.
+      editor = new RichClay(el, {
+        inline: true,
+        hyperclay: false,
+        toolbar: ['bold', 'italic', 'link', 'undo', 'redo'],
+      })
+    } catch (err) {
+      console.warn('[hypercms] richclay activation failed; field stays plain contenteditable', err)
+      return
+    }
+    el.__hcmsRichclay = editor
+    // Toolbar commands mutate the DOM through squire, which doesn't always
+    // fire a native input event; mirror squire's own input signal so the
+    // form's delegated listener commits the change. Duplicate events are
+    // harmless — commits are fingerprinted.
+    const squire = editor && editor.squire
+    if (squire && typeof squire.addEventListener === 'function') {
+      squire.addEventListener('input', () => {
+        const Ev = (win && win.Event) || Event
+        el.dispatchEvent(new Ev('input', { bubbles: true }))
+      })
+    }
+  })
+}

package/src/events.js

@@ -1,8 +1,9 @@
 import { engine } from 'hyper-html-api'
 import { applyWithRollback } from './apply-loop.js'
 import { fromString as pathFromString, getRuleAtPath } from './path.js'
-import { buildItem, fileNameFromUrl } from './form-builder.js'
+import { buildItem, fileNameFromUrl, radioGroupName } from './form-builder.js'
 import { scaffold } from './scaffold.js'
+import { autosizeTextarea, enhanceFields } from './enhance.js'
 
 const BOUND = new WeakSet()
 
@@ -55,7 +56,8 @@ export function bindEvents(ctx) {
     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.matches('input, textarea, select, [contenteditable][data-hcms-field]')) return
+    if (target.tagName === 'TEXTAREA') autosizeTextarea(target)
     // The upload picker fires `input` too, but its .value is the OS fake path
     // (C:\fakepath\…); it's handled on `change` via onUploadChange. The wrapper
     // carries data-hcms-field, so without this guard the closest() below would
@@ -172,13 +174,54 @@ export function onScalarChange(target, ctx) {
   }
 }
 
-// Crop adapter seam. A pass-through today; Slice 6 fills the body to route the
-// file through window.hyperclay.quickcrop before upload when the field opts in
-// via data-hcms-crop. Returns { file, dataURL? }, or null to abort (crop
-// cancelled). Keeping ALL crop coupling here means no other upload code changes
-// when crop lands.
-async function maybeCrop(file /*, fieldEl */) {
-  return { file }
+// Crop adapter seam: ALL crop coupling lives here, between the file pick and
+// the upload. A field opts in via data-hcms-crop on the page element (copied
+// onto the built @image field by the form-builder); absent attr or absent
+// quickcrop (standalone page) uploads raw. Returns { file, dataURL? }, or null
+// to abort (crop cancelled / failed) — the caller resets the picker and skips
+// the commit. quickcrop resolves null on cancel (it does NOT reject), so the
+// cancel branch is the null check, not the catch.
+const CROP_OUTPUT = { type: 'image/webp', quality: 0.85, maxWidth: 2048, maxHeight: 2048 }
+
+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
+  if (typeof crop !== 'function') return { file }
+  try {
+    const r = await crop(file, { aspect: parseCropAspect(attr), ...CROP_OUTPUT })
+    if (r === null) return null
+    return { file: blobToFile(r.blob, file.name), dataURL: r.dataURL }
+  } catch (err) {
+    showFieldUploadError(fieldEl, (err && err.message) || 'Crop failed')
+    return null
+  }
+}
+
+// "1:1" → 1, "16:9" → 16/9, "free" / "" / unparseable → null (freeform crop).
+// Exported for tests.
+export function parseCropAspect(value) {
+  const v = String(value ?? '').trim().toLowerCase()
+  if (v === '' || v === 'free') return null
+  const m = v.match(/^(\d+(?:\.\d+)?)\s*[:/]\s*(\d+(?:\.\d+)?)$/)
+  if (!m) return null
+  const w = parseFloat(m[1])
+  const h = parseFloat(m[2])
+  if (!w || !h) return null
+  return w / h
+}
+
+// quickcrop returns a nameless Blob; uploadFileBasic rejects raw Blobs and the
+// server keys content-type off the filename extension, so wrap it as a File
+// whose extension matches the encoded mime. Exported for tests.
+export function blobToFile(blob, originalName) {
+  const ext = blob.type === 'image/webp' ? '.webp' : blob.type === 'image/jpeg' ? '.jpg' : '.png'
+  const base = String(originalName || 'image').replace(/\.[^.]+$/, '')
+  try {
+    return new File([blob], base + ext, { type: blob.type })
+  } catch {
+    return blob
+  }
 }
 
 // A file was picked in an @file/@image widget. Optionally crop, upload via the
@@ -193,6 +236,10 @@ export async function onUploadChange(inputEl, ctx) {
   if (!fieldEl) return
   const pathStr = fieldEl.getAttribute('data-hcms-path') || ''
 
+  // A fresh pick is a fresh attempt: clear any stale inline error (e.g. a
+  // crop failure from a previous attempt) before running the new flow.
+  showFieldUploadError(fieldEl, null)
+
   const cropped = await maybeCrop(file, fieldEl)
   if (!cropped || ctx.closed) { resetPicker(inputEl); return }
   const fileLike = cropped.file
@@ -316,8 +363,12 @@ export function onAdd(arrayPath, ctx) {
     pathArr: [...pathArr, nextIndex],
     data: itemData,
     doc: ctx.doc,
+    // Component arrays (chips) record their item-template key at build time so
+    // added items keep the same chrome.
+    itemKey: arrayEl.getAttribute('data-hcms-item-tpl') || null,
   })
   slot.appendChild(itemNode)
+  enhanceFields(itemNode, ctx.doc)
   updateArrayButtonsVisibility(arrayEl)
   return commitWithUndo(`Add ${arrayPath}`, () =>
     commit(extractFormData(ctx), { path: arrayPath, structural: true }, ctx)
@@ -619,6 +670,16 @@ export function restampAllSiblings(formRoot) {
 }
 
 function restampSiblingPaths(parent) {
+  // Radio names are rewritten one item at a time below, so during a move or
+  // drag a just-renamed radio can transiently share a name with a
+  // not-yet-renamed sibling — and the browser enforces single-selection per
+  // group AT THAT INSTANT, permanently unchecking one of them (null extract →
+  // the whole-form commit clobbers that field's page value). Snapshot every
+  // radio's checked state and re-assert it once all names are final (and
+  // unique per field) again.
+  const radios = parent.querySelectorAll
+    ? Array.from(parent.querySelectorAll('input[type="radio"][data-hcms-field]'), (r) => [r, r.checked])
+    : []
   let i = 0
   for (const child of parent.children) {
     if (!child.matches?.('[data-hcms-card], [data-hcms-array-item]')) continue
@@ -630,6 +691,9 @@ function restampSiblingPaths(parent) {
     if (newPath !== path) restampSubtree(child, path, newPath)
     i++
   }
+  for (const [r, wasChecked] of radios) {
+    if (r.checked !== wasChecked) r.checked = wasChecked
+  }
 }
 
 function restampSubtree(root, oldPrefix, newPrefix) {
@@ -643,6 +707,22 @@ function restampSubtree(root, oldPrefix, newPrefix) {
       el.setAttribute('data-hcms-path', newPrefix + p.slice(oldPrefix.length))
     }
   }
+  syncRadioGroupNames(root)
+}
+
+// Radio group names derive from the field path at build time (populateOptions),
+// so a restamp that moves paths must recompute them. Otherwise a removed-then-
+// re-added sibling gets a fresh name that collides with this item's stale one:
+// the two fields share a browser radio group, checking one unchecks the other,
+// and the whole-form commit clobbers the unchecked field's page value. Only
+// names the builder minted ('hcms-' prefix) are touched — radios in inline or
+// custom templates keep whatever name the author gave them.
+function syncRadioGroupNames(root) {
+  for (const input of root.querySelectorAll('input[type="radio"][data-hcms-field]')) {
+    if (!input.name || !input.name.startsWith('hcms-')) continue
+    const host = input.closest('[data-hcms-path]')
+    if (host) input.name = radioGroupName(host.getAttribute('data-hcms-path'))
+  }
 }
 
 function stableStringify(value) {

package/src/form-builder.js

@@ -4,6 +4,12 @@ import {
   humanize,
   shapeKindOf,
   componentForScalarRule,
+  componentForScalarArrayRule,
+  winningScalarArrayComponent,
+  resolveTemplate,
+  declaredComponentKey,
+  readOptionsOverride,
+  readCropOverride,
 } from './templates.js'
 import { fieldPropertyFor } from './form-rules.js'
 
@@ -27,12 +33,12 @@ 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}"`)
 }
@@ -47,14 +53,40 @@ function buildNode(rule, pathArr, data, doc) {
 }
 
 function buildScalar(rule, pathArr, data, doc) {
-  // Opt-in upload components select a richer template (@image/@file) off the
-  // bound rule's @prop suffix; plain scalars stay @scalar. A path-bound
-  // template override still wins inside resolveTemplate.
-  const componentKey = componentForScalarRule(rule, 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).
@@ -67,6 +99,89 @@ function buildScalar(rule, pathArr, data, doc) {
   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
@@ -149,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', '')
@@ -180,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, componentForScalarRule } from './templates.js'
+import {
+  shapeKindOf,
+  findTemplate,
+  isInlineTemplate,
+  componentForScalarRule,
+  winningScalarArrayComponent,
+} from './templates.js'
 
 const TAG_PROP_MAP = {
   IMG: 'src',
@@ -15,6 +21,8 @@ export function fieldPropertyFor(el) {
   }
   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
 }
 
@@ -79,7 +87,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)
@@ -104,18 +112,24 @@ export function deriveFormRules(pageRules, doc) {
     // 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), fieldKey)
+    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.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, injectUploadComponents } from './templates.js'
+import { injectDefaults, injectComponents } from './templates.js'
 import { deriveFormRules } from './form-rules.js'
 import { buildForm } from './form-builder.js'
 import {
@@ -20,6 +20,8 @@ import {
 import { mountShell, setShellStyles, markStylesBundled } from './shell.js'
 import { refreshForm, installObserver } from './refresh.js'
 import { warnUnmatchedTemplates } from './diagnostics.js'
+import { enhanceFields, upgradeRichTextRules } from './enhance.js'
+import { maybeInjectToggle } from './toggle.js'
 
 export function installStyles(text) {
   setShellStyles(text)
@@ -100,11 +102,16 @@ export function open(opts = {}) {
     const what = typeof source === 'string' ? `data-rules-name~="${source}"` : 'the provided rules object'
     throw new Error(`hypercms: no rules found for ${what}`)
   }
-  const pageRules = found.rules
+  // Rich-text upgrade (default on): bare scalar rules whose page element
+  // contains child elements are rebound through @innerHTML so links and
+  // inline formatting survive the round-trip, and their form fields render
+  // the @richtext component. Opt out with cms.open({ richText: false }).
+  const richText = opts.richText !== false
+  const pageRules = richText ? upgradeRichTextRules(found.rules, pageRoot) : found.rules
   const rulesTagNode = found.tagNode
 
   injectDefaults(doc)
-  injectUploadComponents(doc, pageRules)
+  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)
@@ -130,6 +137,7 @@ export function open(opts = {}) {
     formRules,
     rulesTagNode,
     rulesSource: source,
+    richText,
     formRoot: shell.formRoot,
     shellRoot: shell.root,
     errorEl: shell.errorEl,
@@ -165,6 +173,7 @@ export function open(opts = {}) {
   try {
   const fragment = buildForm({ pageRules, formRules, data, doc })
   shell.formRoot.appendChild(fragment)
+  enhanceFields(shell.formRoot, doc)
 
   bindEvents(ctx)
   ctx.updateFingerprint()
@@ -455,6 +464,10 @@ function writeFieldValue(el, value, formRoot, path) {
     el.href = value == null ? '' : String(value)
     return
   }
+  if (el.hasAttribute && el.hasAttribute('contenteditable')) {
+    el.innerHTML = value == null ? '' : String(value)
+    return
+  }
   if ('value' in el) {
     el.value = value == null ? '' : String(value)
     return
@@ -511,7 +524,13 @@ function autoOpenReady() {
 //      deadline is hit (warn, never throw).
 function whenReady(fn) {
   if (autoOpenReady()) {
-    fn()
+    // 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
@@ -560,6 +579,14 @@ function whenReady(fn) {
 // 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,
+  hasRules: (doc) => !!engine.findRules(doc, 'cms'),
+})
+
 const cms = {
   open,
   close,