@panphora/hyper-cms 0.5.0 → 0.6.0

package/package.json

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

package/src/events.js

@@ -1,7 +1,7 @@
 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'
 
 const BOUND = new WeakSet()
@@ -172,13 +172,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 +234,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,6 +361,9 @@ 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)
   updateArrayButtonsVisibility(arrayEl)
@@ -619,6 +667,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 +688,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 +704,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',
@@ -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)
@@ -104,18 +110,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 {
@@ -104,7 +104,7 @@ export function open(opts = {}) {
   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)
@@ -511,7 +511,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

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, injectUploadComponents } from './templates.js'
+import { injectDefaults, injectComponents } from './templates.js'
 import { deriveFormRules } from './form-rules.js'
 import { coerceBooleans, applyErrorState } from './events.js'
 
@@ -18,7 +18,7 @@ export function refreshForm(ctx, { ignoreActiveValue } = {}) {
   }
   // Re-derive formRules so schema changes (rule shape, template overrides) flow through.
   injectDefaults(ctx.doc)
-  injectUploadComponents(ctx.doc, ctx.pageRules)
+  injectComponents(ctx.doc, ctx.pageRules)
   ctx.formRules = deriveFormRules(ctx.pageRules, ctx.doc)
 
   const newData = coerceBooleans(

package/src/shell.js

@@ -155,6 +155,10 @@ function ensureStyles(doc) {
     const style = doc.createElement('style')
     style.id = SHELL_STYLE_ID
     style.setAttribute('save-remove', '')
+    // save-ignore mirrors the shell root so a full-document morph (e.g. a live-sync
+    // head-merge) preserves the stylesheet instead of stripping it; without it the
+    // style survives only via restoreChrome's reactive re-injection.
+    style.setAttribute('save-ignore', '')
     style.textContent = cssText
     ;(doc.head || doc.documentElement).appendChild(style)
     styledDocs.add(doc)
@@ -170,12 +174,19 @@ function ensureStyles(doc) {
     link.rel = 'stylesheet'
     link.id = SHELL_STYLE_ID
     link.setAttribute('save-remove', '')
+    link.setAttribute('save-ignore', '')
     link.href = href
     ;(doc.head || doc.documentElement).appendChild(link)
     styledDocs.add(doc)
   } catch (_) {
-    // SSR or environments without import.meta.url — author can call
-    // installStyles(text) manually.
+    // No bundled CSS and no resolvable co-located theme (e.g. the IIFE bundle,
+    // where import.meta is undefined). Warn loudly rather than mount a silently
+    // unstyled shell — the host must call installStyles(themeText) before opening.
+    console.warn(
+      'hypercms: shell stylesheet not applied — cssText is empty and the ' +
+      'co-located theme fallback is unavailable. Call installStyles(themeText) ' +
+      'before opening the CMS.'
+    )
   }
 }