@panphora/hyper-cms 0.4.2 → 0.5.0

package/src/hypercms.js

@@ -2,7 +2,7 @@ import { engine } from 'hyper-html-api'
 import * as pathUtil from './path.js'
 import { scaffold } from './scaffold.js'
 import { morphForm } from './morph.js'
-import { injectDefaults } from './templates.js'
+import { injectDefaults, injectUploadComponents } from './templates.js'
 import { deriveFormRules } from './form-rules.js'
 import { buildForm } from './form-builder.js'
 import {
@@ -104,6 +104,7 @@ export function open(opts = {}) {
   const rulesTagNode = found.tagNode
 
   injectDefaults(doc)
+  injectUploadComponents(doc, pageRules)
   warnUnmatchedTemplates(doc, pageRules)
   const formRules = deriveFormRules(pageRules, doc)
   const data = coerceBooleans(engine.extract(pageRoot, pageRules, { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }), pageRules)
@@ -116,6 +117,9 @@ export function open(opts = {}) {
     side: opts.side || 'right',
     overlay: !!opts.overlay,
     showSaveButton: !!opts.showSaveButton,
+    title: opts.title,
+    eyebrow: opts.eyebrow,
+    theme: opts.theme,
     doc,
   }))
 
@@ -136,12 +140,12 @@ export function open(opts = {}) {
     livesyncUnsub: null,
     onChange: opts.onChange,
     onError: opts.onError,
-    onSave: opts.onSave,
+    confirmRemove: opts.confirmRemove,
     previouslyFocused: doc.activeElement,
     dispatch(name, detail) {
       const Ctor = (doc.defaultView && doc.defaultView.CustomEvent) || (typeof CustomEvent !== 'undefined' ? CustomEvent : null)
       if (!Ctor) return
-      const ev = new Ctor(name, { bubbles: true, cancelable: name === 'hcms:change' || name === 'hcms:save', detail })
+      const ev = new Ctor(name, { bubbles: true, cancelable: name === 'hcms:change', detail })
       shell.root.dispatchEvent(ev)
     },
     onCloseRequested() {
@@ -152,6 +156,13 @@ export function open(opts = {}) {
     ctx.lastFingerprint = stableStringify(extractFormData(ctx))
   }
 
+  // Everything past the shell mount touches the live DOM, the module-level state,
+  // and external subscriptions (observer, undo, livesync). A throw in here — most
+  // notably installObserver when window.hyperclay.Mutation isn't loaded — would
+  // otherwise strand the mounted shell in the DOM with no way to close it (close()
+  // early-returns while state.isOpen is false). Tear down whatever was wired,
+  // exactly as close() does, then rethrow so host misuse still fails loudly.
+  try {
   const fragment = buildForm({ pageRules, formRules, data, doc })
   shell.formRoot.appendChild(fragment)
 
@@ -169,7 +180,26 @@ export function open(opts = {}) {
   // the active field. Guarded so it degrades to today's behavior when undo isn't loaded.
   const u = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.undo) || null
   if (u && typeof u.on === 'function') {
-    const onRevert = () => resyncForm(ctx, 'undo')
+    const onRevert = () => {
+      if (state.ctx !== ctx) return
+      resyncForm(ctx, 'undo')
+      // A reverted change the consumer persists through onChange (e.g. the
+      // collection dashboard PUTs the record, not the page) would otherwise lag
+      // the undo: refreshForm re-syncs the form but never fires onChange, and a
+      // commit() here would be fingerprint-skipped (refreshForm already updated
+      // it). Extract the reverted state from the PAGE (the source of truth after
+      // an undo/redo; the form can lag a morph) and fire onChange directly, but
+      // only when it actually changed — guards spurious PUTs on undo/redo of
+      // unrelated edits elsewhere on the page.
+      const data = coerceBooleans(
+        engine.extract(ctx.pageRoot, ctx.pageRules, { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }),
+        ctx.pageRules
+      )
+      if (stableStringify(data) !== stableStringify(ctx.lastData)) {
+        ctx.lastData = data
+        ctx.onChange?.(data, { path: '', structural: false })
+      }
+    }
     u.on('undo', onRevert)
     u.on('redo', onRevert)
     ctx.undoUnsub = () => { u.off('undo', onRevert); u.off('redo', onRevert) }
@@ -199,6 +229,19 @@ export function open(opts = {}) {
   state.opts = opts
 
   ctx.dispatch('hcms:open', { pageRoot })
+  } catch (err) {
+    ctx.observerHandle?.unsubscribe?.()
+    ctx.undoUnsub?.()
+    ctx.livesyncUnsub?.()
+    ctx.detachEvents?.()
+    if (globalCommitTarget.ctx === ctx) globalCommitTarget.ctx = null
+    suppressUndo(() => shell.destroy())
+    state.isOpen = false
+    state.ctx = null
+    state.shell = null
+    state.opts = null
+    throw err
+  }
 }
 
 function focusFirstIn(root) {
@@ -232,11 +275,57 @@ function installGlobalSortableCommit(doc) {
   }
 }
 
+// The query param that drives ?cms=true auto-open. Closing the CMS rewrites it
+// to cms=false (param kept) so a refresh/share of the post-close URL does not
+// auto-reopen.
+const AUTO_OPEN_PARAM = 'cms'
+
+// Pure: given a location.search string, return the search string after a close.
+// Only rewrites when cms=true is present; every other param + ordering is
+// preserved, and a search without cms (or already cms=false) is returned
+// unchanged so we never inject the param into a page that never carried it.
+export function nextSearchAfterClose(search) {
+  const str = typeof search === 'string' ? search : ''
+  const qIndex = str.indexOf('?')
+  const query = qIndex === -1 ? str : str.slice(qIndex + 1)
+  if (!query) return str
+  const params = new URLSearchParams(query)
+  if (params.get(AUTO_OPEN_PARAM) !== 'true') return str
+  params.set(AUTO_OPEN_PARAM, 'false')
+  return '?' + params.toString()
+}
+
+// Pure: should the CMS auto-open for this location.search? Exactly 'true'.
+export function shouldAutoOpenFromSearch(search) {
+  const str = typeof search === 'string' ? search : ''
+  const qIndex = str.indexOf('?')
+  const query = qIndex === -1 ? str : str.slice(qIndex + 1)
+  if (!query) return false
+  return new URLSearchParams(query).get(AUTO_OPEN_PARAM) === 'true'
+}
+
+// Rewrite ?cms=true → ?cms=false via history.replaceState (no reload, hash and
+// every other param preserved). No-op when the param isn't present or the
+// History API is unavailable.
+function toggleCloseParam() {
+  if (typeof window === 'undefined' || !window.location || !window.history) return
+  if (typeof window.history.replaceState !== 'function') return
+  const current = window.location.search
+  const next = nextSearchAfterClose(current)
+  if (next === current) return
+  window.history.replaceState(window.history.state, '', next + window.location.hash)
+}
+
 export function close() {
   if (!state.isOpen) return
   const { ctx, shell } = state
+  // Mark this ctx dead so any in-flight async work (e.g. an upload awaiting the
+  // host uploader) bails instead of mutating the page / firing onChange after
+  // teardown. Mirrors the state.ctx !== ctx guards on the undo/livesync paths.
+  ctx.closed = true
   const previouslyFocused = ctx.previouslyFocused
   ctx.dispatch('hcms:close', null)
+  toggleCloseParam()
   ctx.observerHandle?.unsubscribe?.()
   ctx.undoUnsub?.()
   ctx.livesyncUnsub?.()
@@ -373,6 +462,104 @@ function writeFieldValue(el, value, formRoot, path) {
   el.textContent = value == null ? '' : String(value)
 }
 
+// ?cms=true auto-open. When the page URL carries cms=true at load, open the CMS
+// for everyone (no gating — this is a feature showcase; a non-admin's edits stay
+// DOM-local and the host save path shows its view-mode notice). open() is
+// idempotent-safe (it warns + returns if already open), so a host that also calls
+// open() never double-mounts. No special opts — host defaults apply.
+//
+// Patience matters here: this runs at module load from the dist IIFE, which a
+// host typically loads BEFORE installing window.hyperclay.Mutation (the Mutation
+// install often sits behind an `await import(...)` that resumes after this script,
+// even after DOMContentLoaded). open() needs <body> AND Mutation, so we poll for
+// both rather than firing eagerly. Firing without Mutation would throw out of
+// installObserver, escape module evaluation, and abort esbuild's
+// window.hypercms assignment — taking the host's own wiring down with it.
+const SAFETY_POLL_MS = 250
+const AUTO_OPEN_DEADLINE_MS = 10000
+export function maybeAutoOpen() {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return
+  if (!shouldAutoOpenFromSearch(window.location ? window.location.search : '')) return
+  if (state.isOpen) return
+  whenReady(() => {
+    if (state.isOpen) return
+    try {
+      open()
+    } catch (err) {
+      console.warn('hypercms: auto-open failed', err)
+    }
+  })
+}
+
+// Auto-open is ready only once <body> is parsed AND window.hyperclay.Mutation is
+// installed (open() needs both). NEVER throw out of module scope.
+function autoOpenReady() {
+  return !!document.body && !!(window.hyperclay && window.hyperclay.Mutation)
+}
+
+// Three layers, in order of preference:
+//   1. Sync fast-path: if <body> and Mutation are already here, fire now.
+//   2. Event: hyperclayjs's mutation.js dispatches 'hyperclay:mutation-ready' the
+//      instant it installs window.hyperclay.Mutation. On loader pages this is
+//      moot — the loader's first wave evaluates mutation before hypercms, so the
+//      fast-path wins — but the event catches any late install (the deferred
+//      `await import()` ordering). The body gate is re-checked in the handler
+//      because the event can land before <body> is parsed.
+//   3. Backstop: a slow self-cancelling 250ms poll for exotic hosts that hand-roll
+//      window.hyperclay.Mutation by direct assignment WITHOUT dispatching the
+//      event. It cancels the moment the event fires, open succeeds, or the
+//      deadline is hit (warn, never throw).
+function whenReady(fn) {
+  if (autoOpenReady()) {
+    fn()
+    return
+  }
+  const deadline = Date.now() + AUTO_OPEN_DEADLINE_MS
+  let done = false
+  let timer = null
+  const finish = () => {
+    if (done) return
+    done = true
+    if (timer !== null) clearInterval(timer)
+    document.removeEventListener('hyperclay:mutation-ready', onMutationReady)
+  }
+  function onMutationReady() {
+    if (state.isOpen) {
+      finish()
+      return
+    }
+    if (autoOpenReady()) {
+      finish()
+      fn()
+    }
+    // Body may still be pending — the one-shot listener is already consumed,
+    // so only the backstop remains to catch it once body arrives.
+  }
+  document.addEventListener('hyperclay:mutation-ready', onMutationReady, { once: true })
+  timer = setInterval(() => {
+    if (state.isOpen) {
+      finish()
+      return
+    }
+    if (autoOpenReady()) {
+      finish()
+      fn()
+      return
+    }
+    if (Date.now() >= deadline) {
+      finish()
+      console.warn(
+        'hypercms: ?cms=true auto-open gave up — window.hyperclay.Mutation never appeared. ' +
+        'Load hyperclayjs (or the mutation utility) so the CMS can initialize.'
+      )
+    }
+  }, SAFETY_POLL_MS)
+}
+
+// Auto-open at module load (browser only — node tests import this without a real
+// window, and the guards above no-op there).
+maybeAutoOpen()
+
 const cms = {
   open,
   close,

package/src/refresh.js

@@ -1,7 +1,7 @@
 import { engine } from 'hyper-html-api'
 import { buildForm } from './form-builder.js'
 import { morphForm } from './morph.js'
-import { injectDefaults } from './templates.js'
+import { injectDefaults, injectUploadComponents } from './templates.js'
 import { deriveFormRules } from './form-rules.js'
 import { coerceBooleans, applyErrorState } from './events.js'
 
@@ -18,6 +18,7 @@ export function refreshForm(ctx, { ignoreActiveValue } = {}) {
   }
   // Re-derive formRules so schema changes (rule shape, template overrides) flow through.
   injectDefaults(ctx.doc)
+  injectUploadComponents(ctx.doc, ctx.pageRules)
   ctx.formRules = deriveFormRules(ctx.pageRules, ctx.doc)
 
   const newData = coerceBooleans(

package/src/shell.js

@@ -19,7 +19,22 @@ export function markStylesBundled(doc) {
 
 let titleIdCounter = 0
 
-export function mountShell({ mountTo, side = 'right', overlay = false, showSaveButton = false, doc }) {
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"]/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]
+  ))
+}
+
+export function mountShell({
+  mountTo,
+  side = 'right',
+  overlay = false,
+  showSaveButton = false,
+  title = 'Page content',
+  eyebrow = 'Edit',
+  theme = null,
+  doc,
+}) {
   ensureStyles(doc)
   const titleId = `hcms-shell-title-${++titleIdCounter}`
   const root = doc.createElement('div')
@@ -33,17 +48,45 @@ export function mountShell({ mountTo, side = 'right', overlay = false, showSaveB
   root.setAttribute('role', 'dialog')
   root.setAttribute('aria-modal', 'true')
   root.setAttribute('aria-labelledby', titleId)
-  root.className = 'hcms-shell hcms-side-' + side + (overlay ? ' hcms-overlay' : '')
+  // pixel-quiet is the baked-in look; an optional theme pins light/dark
+  // (otherwise the panel follows the OS via prefers-color-scheme).
+  const themeClass = theme === 'dark' ? ' dark' : theme === 'light' ? ' light' : ''
+  root.className =
+    'hcms-shell pixel-quiet hcms-side-' + side + (overlay ? ' hcms-overlay' : '') + themeClass
+  const titleHtml = escapeHtml(title)
+  const eyebrowHtml = escapeHtml(eyebrow)
+  // Pixel Quiet shell: a scroll-away header + in-flow Save inside .hcms-shell-body,
+  // with a condensed minibar pinned to the panel top once the header scrolls out.
+  // Close + Save are real mirk buttons. The .hcms-* hooks stay so the engine and
+  // events bind exactly as before; only the chrome shape changed.
+  // The Save button has no wiring here: [trigger-save] is the hyperclayjs save
+  // attribute — its save system (or its view-mode notice) handles the click.
+  // Standalone hosts delegate their own [trigger-save] click listener.
   root.innerHTML = `
-    <header class="hcms-shell-header">
-      <h2 class="hcms-shell-title" id="${titleId}">Edit</h2>
-      <button type="button" class="hcms-shell-close" data-hcms-action="close" aria-label="Close">×</button>
-    </header>
-    <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'}>
-      <button type="button" class="hcms-shell-save" data-hcms-action="save">Save</button>
-    </footer>
+    <div class="hcms-shell-minibar" aria-hidden="true">
+      <span class="hcms-shell-minibar-title">${titleHtml}</span>
+      <button type="button" class="hcms-shell-close mirk-button mirk-button--small" data-hcms-action="close" aria-label="Close">
+        <span class="mirk-button__label">×</span>
+      </button>
+    </div>
+    <div class="hcms-shell-body">
+      <header class="hcms-shell-header">
+        <div class="hcms-shell-heading">
+          <div class="hcms-shell-eyebrow">${eyebrowHtml}</div>
+          <h2 class="hcms-shell-title" id="${titleId}">${titleHtml}</h2>
+        </div>
+        <button type="button" class="hcms-shell-close mirk-button mirk-button--small" data-hcms-action="close" aria-label="Close">
+          <span class="mirk-button__label">×</span>
+        </button>
+      </header>
+      <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'}>
+        <button type="button" class="hcms-shell-save mirk-button" trigger-save>
+          <span class="mirk-button__label">Save</span>
+        </button>
+      </footer>
+    </div>
   `
 
   // mountTo may be a nested element inside pageRoot. Use it as-is for the
@@ -58,6 +101,7 @@ export function mountShell({ mountTo, side = 'right', overlay = false, showSaveB
   if (side === 'left') body.classList.add('hcms-side-left')
 
   const focusTrap = installFocusTrap(root, doc)
+  const condense = installCondenseOnScroll(root)
 
   return {
     root,
@@ -66,6 +110,7 @@ export function mountShell({ mountTo, side = 'right', overlay = false, showSaveB
     saveButton: root.querySelector('.hcms-shell-save'),
     destroy() {
       focusTrap.detach()
+      condense.detach()
       root.remove()
       body.classList.remove('hcms-open', 'hcms-overlay', 'hcms-side-left')
     },
@@ -115,12 +160,12 @@ function ensureStyles(doc) {
     styledDocs.add(doc)
     return
   }
-  // No bundled CSS — try resolving the sibling styles.css via import.meta.url.
-  // Browsers ESM-resolved imports place a co-located styles.css next to
-  // hypercms.js. Falls back silently if resolution fails (e.g., bundlers
-  // without an asset emitter).
+  // No bundled CSS — try resolving the sibling generated theme via
+  // import.meta.url. Browsers ESM-resolved imports place a co-located
+  // theme.generated.css next to hypercms.js. Falls back silently if resolution
+  // fails (e.g., bundlers without an asset emitter).
   try {
-    const href = new URL('./styles.css', import.meta.url).href
+    const href = new URL('./theme.generated.css', import.meta.url).href
     const link = doc.createElement('link')
     link.rel = 'stylesheet'
     link.id = SHELL_STYLE_ID
@@ -134,6 +179,25 @@ function ensureStyles(doc) {
   }
 }
 
+// Reveal the condensed minibar once the full header scrolls out of the body
+// (pixel-quiet decision 0003). Passive listener; toggles .is-condensed on the
+// shell root when scrollTop passes the header height. No-op if the body or
+// header is missing (e.g. a custom mount that omits them).
+function installCondenseOnScroll(root) {
+  const bodyEl = root.querySelector('.hcms-shell-body')
+  const header = root.querySelector('.hcms-shell-header')
+  if (!bodyEl || !header || typeof bodyEl.addEventListener !== 'function') {
+    return { detach() {} }
+  }
+  const reveal = () => {
+    const trigger = (header.offsetHeight || 0) - 12
+    root.classList.toggle('is-condensed', bodyEl.scrollTop > trigger)
+  }
+  bodyEl.addEventListener('scroll', reveal, { passive: true })
+  reveal()
+  return { detach() { bodyEl.removeEventListener('scroll', reveal) } }
+}
+
 function installFocusTrap(root, doc) {
   function onKeyDown(e) {
     if (e.key !== 'Tab') return

package/src/templates.js

@@ -10,11 +10,23 @@ export function humanize(key) {
     .replace(/^./, (c) => c.toUpperCase())
 }
 
+// The default templates emit real mirk-interface markup so the generated form
+// renders in the Pixel Quiet look out of the box. Every data-hcms-* hook
+// (shape, label, field, action, the .hcms-array-items / .hcms-card-fields slots,
+// the .hcms-error inline slots) is preserved exactly, so the engine, events,
+// add/remove/reorder, and inline-error placement bind unchanged. The CSS that
+// dresses these lives in src/theme.generated.css (scoped mirk + pixel-quiet).
+const SORTABLE_GRIP = `<div class="hcms-drag-handle mirk-sortable__grip" aria-hidden="true"><div class="mirk-sortable__dots"><span class="mirk-sortable__dot"></span><span class="mirk-sortable__dot"></span><span class="mirk-sortable__dot"></span><span class="mirk-sortable__dot"></span><span class="mirk-sortable__dot"></span><span class="mirk-sortable__dot"></span><span class="mirk-sortable__dot"></span><span class="mirk-sortable__dot"></span></div></div>`
+
+// Crisp-line × (square caps + crispEdges): a plain pixel-sharp close glyph that
+// stays hard-edged inside the small square corner button on object-array cards.
+const CLOSE_ICON = `<svg class="hcms-x" viewBox="0 0 16 16" shape-rendering="crispEdges" aria-hidden="true"><path d="M4 4 L12 12 M12 4 L4 12" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="square"></path></svg>`
+
 const DEFAULT_TEMPLATES = {
   '@scalar': `
     <label class="hcms-field" data-hcms-shape="scalar">
       <span class="hcms-label" data-hcms-label></span>
-      <input class="hcms-input" data-hcms-field />
+      <input class="mirk-input" data-hcms-field />
       <div class="hcms-error" hidden></div>
     </label>
   `,
@@ -32,56 +44,183 @@ const DEFAULT_TEMPLATES = {
       </header>
       <ul class="hcms-array-items"></ul>
       <div class="hcms-error" hidden></div>
-      <button type="button" class="hcms-add" data-hcms-action="add">+ Add</button>
+      <button type="button" class="hcms-add mirk-button mirk-button--small" data-hcms-action="add"><span class="mirk-button__label">+ Add</span></button>
     </section>
   `,
   '@scalar-array-item': `
     <li class="hcms-array-item" draggable="true">
-      <span class="hcms-drag-handle" aria-hidden="true">::</span>
-      <input class="hcms-input" data-hcms-field />
+      <input class="mirk-input" data-hcms-field />
       <button type="button" class="hcms-move hcms-move-up hcms-sr-only" data-hcms-action="move-up" aria-label="Move up">↑</button>
       <button type="button" class="hcms-move hcms-move-down hcms-sr-only" data-hcms-action="move-down" aria-label="Move down">↓</button>
-      <button type="button" class="hcms-remove" data-hcms-action="remove" aria-label="Remove">x</button>
+      <button type="button" class="hcms-remove" data-hcms-action="remove" aria-label="Remove">×</button>
       <div class="hcms-error" hidden></div>
     </li>
   `,
   '@object-array': `
-    <section class="hcms-array hcms-object-array" data-hcms-shape="object-array">
+    <section class="hcms-array hcms-object-array hcms-array--cards" data-hcms-shape="object-array">
       <header class="hcms-array-header">
         <h3 class="hcms-array-title" data-hcms-label></h3>
       </header>
       <div class="hcms-array-items"></div>
       <div class="hcms-error" hidden></div>
-      <button type="button" class="hcms-add" data-hcms-action="add">+ Add</button>
+      <button type="button" class="hcms-add mirk-button mirk-button--small" data-hcms-action="add"><span class="mirk-button__label">+ Add</span></button>
     </section>
   `,
   '@object-array-item': `
-    <article class="hcms-card" draggable="true">
-      <header class="hcms-card-header">
-        <span class="hcms-drag-handle" aria-hidden="true">::</span>
-        <button type="button" class="hcms-move hcms-move-up hcms-sr-only" data-hcms-action="move-up" aria-label="Move up">↑</button>
-        <button type="button" class="hcms-move hcms-move-down hcms-sr-only" data-hcms-action="move-down" aria-label="Move down">↓</button>
-        <button type="button" class="hcms-remove" data-hcms-action="remove" aria-label="Remove">x</button>
-      </header>
-      <div class="hcms-card-fields"></div>
+    <article class="hcms-card mirk-sortable__item" draggable="true">
+      ${SORTABLE_GRIP}
+      <div class="hcms-card-body mirk-sortable__body">
+        <div class="hcms-card-fields"></div>
+        <div class="hcms-card-controls">
+          <button type="button" class="hcms-move hcms-move-up hcms-sr-only" data-hcms-action="move-up" aria-label="Move up">↑</button>
+          <button type="button" class="hcms-move hcms-move-down hcms-sr-only" data-hcms-action="move-down" aria-label="Move down">↓</button>
+          <button type="button" class="hcms-remove hcms-remove--card" data-hcms-action="remove" aria-label="Remove">${CLOSE_ICON}</button>
+        </div>
+      </div>
       <div class="hcms-error" hidden></div>
     </article>
   `,
+  // Opt-in upload components. Built on the kit's consolidated mirk chrome (all
+  // themed in theme.generated.css), with interactive hooks kept on data-hcms-*
+  // so the vendored mirk runtime (which keys off .mirk-*__input / .mirk-*__remove)
+  // never double-handles a CMS field. The bound value is the leaf's URL: the
+  // <a href> for @file, the <img src> for @image. Empty/filled chrome is driven
+  // by that attribute in CSS (.hcms-upload* in pixel-quiet.overrides.css), no JS.
+  '@file': `
+    <div class="hcms-field hcms-upload hcms-upload--file" data-hcms-shape="scalar">
+      <span class="hcms-label" data-hcms-label></span>
+      <div class="mirk-file mirk-file--compact mirk-file--round">
+        <label class="mirk-button mirk-button--round mirk-button--small">
+          <input type="file" data-hcms-upload />
+          <span class="mirk-button__label">Choose</span>
+        </label>
+        <a class="mirk-file__name" data-hcms-field></a>
+        <button type="button" class="hcms-upload-clear" data-hcms-action="clear-upload" aria-label="Remove file">${CLOSE_ICON}</button>
+      </div>
+      <div class="hcms-error" hidden></div>
+    </div>
+  `,
+  '@image': `
+    <div class="hcms-field hcms-upload hcms-upload--image" data-hcms-shape="scalar">
+      <span class="hcms-label" data-hcms-label></span>
+      <div class="mirk-image mirk-image--compact mirk-image--rounded">
+        <label class="mirk-button mirk-button--small mirk-image__upload">
+          <input type="file" accept="image/*" data-hcms-upload />
+          <span class="mirk-button__label">Upload image</span>
+        </label>
+        <figure class="mirk-image__thumb">
+          <span class="mirk-image__frame"><img class="mirk-image__preview" data-hcms-field alt="" /></span>
+          <button type="button" class="hcms-upload-clear hcms-upload-clear--badge" data-hcms-action="clear-upload" aria-label="Remove image">${CLOSE_ICON}</button>
+        </figure>
+      </div>
+      <div class="hcms-error" hidden></div>
+    </div>
+  `,
 }
 
-const DEFAULT_KEYS = Object.keys(DEFAULT_TEMPLATES)
+// Shape templates fill-the-gaps on every managed page. The opt-in upload
+// components (@file/@image) are injected on demand the first time a field
+// selects them (the Slice-2 component seam), so pages using neither stay clean.
+const ALWAYS_INJECT_KEYS = [
+  '@scalar',
+  '@object',
+  '@scalar-array',
+  '@scalar-array-item',
+  '@object-array',
+  '@object-array-item',
+]
 
 export function injectDefaults(doc) {
   const head = doc.head || doc.documentElement
   if (!head) return
-  for (const key of DEFAULT_KEYS) {
-    if (findTemplate(doc, key)) continue
-    const tpl = doc.createElement('template')
-    tpl.setAttribute('data-hcms-tpl', key)
-    tpl.setAttribute('save-remove', '')
-    tpl.innerHTML = DEFAULT_TEMPLATES[key].trim()
-    head.appendChild(tpl)
+  for (const key of ALWAYS_INJECT_KEYS) injectTemplate(doc, head, key)
+}
+
+// Inject one opt-in component template (@file/@image) if the page hasn't
+// already defined its own. Called by the component-selection seam the first
+// time a field resolves to an upload component.
+export function injectComponentTemplate(doc, key) {
+  if (!DEFAULT_TEMPLATES[key]) return null
+  const head = doc && (doc.head || doc.documentElement)
+  if (!head) return null
+  return injectTemplate(doc, head, key)
+}
+
+// Opt-in upload-component selection. A scalar field upgrades from a plain text
+// input to an image-upload widget when its rule ends in @src (uploading is the
+// dominant image-CMS workflow). @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.
+// A file upload (and an image override) is opt-in via data-hcms-component on the
+// page element the rule points at — the only branch that reads the page DOM.
+// Suffix is split like the engine (lastIndexOf('@'), see engine/extract.js).
+// Returns a DEFAULT_TEMPLATES key.
+const PROP_TO_COMPONENT = { src: '@image' }
+const UPLOAD_COMPONENT_KEYS = new Set(['@image', '@file'])
+
+export function componentForScalarRule(rule, doc) {
+  if (typeof rule !== 'string') return '@scalar'
+  const at = rule.lastIndexOf('@')
+  if (at >= 0) {
+    const prop = rule.slice(at + 1)
+    if (PROP_TO_COMPONENT[prop]) return PROP_TO_COMPONENT[prop]
   }
+  const override = readComponentOverride(rule, at, doc)
+  if (override === 'image') return '@image'
+  if (override === 'file') return '@file'
+  return '@scalar'
+}
+
+function readComponentOverride(rule, at, doc) {
+  if (!doc || !doc.querySelector) return null
+  const selector = at >= 0 ? rule.slice(0, at) : rule
+  if (!selector || selector === '.') return null
+  let el = null
+  try {
+    el = doc.querySelector(selector)
+  } catch {
+    return null
+  }
+  return el && el.getAttribute ? el.getAttribute('data-hcms-component') : null
+}
+
+// Pre-inject the @file/@image templates this page's rules actually select, so
+// both deriveFormRules (selectors) and buildForm (DOM) resolve them. Walks the
+// same rule shapes as buildTemplateMap; idempotent and author-template-safe.
+export function injectUploadComponents(doc, pageRules) {
+  if (!doc || pageRules == null) return
+  walk(pageRules)
+
+  function walk(rule) {
+    const kind = shapeKindOf(rule)
+    if (kind === 'scalar') {
+      const key = componentForScalarRule(rule, doc)
+      if (UPLOAD_COMPONENT_KEYS.has(key)) injectComponentTemplate(doc, key)
+      return
+    }
+    if (kind === 'object') {
+      for (const child of Object.values(rule)) walk(child)
+      return
+    }
+    if (kind === 'object-array') {
+      const itemShape = rule[1]
+      if (itemShape && typeof itemShape === 'object' && !Array.isArray(itemShape)) {
+        for (const child of Object.values(itemShape)) walk(child)
+      } else {
+        walk(itemShape)
+      }
+    }
+  }
+}
+
+function injectTemplate(doc, head, key) {
+  const existing = findTemplate(doc, key)
+  if (existing) return existing
+  const tpl = doc.createElement('template')
+  tpl.setAttribute('data-hcms-tpl', key)
+  tpl.setAttribute('save-remove', '')
+  tpl.innerHTML = DEFAULT_TEMPLATES[key].trim()
+  head.appendChild(tpl)
+  return tpl
 }
 
 export function findTemplate(doc, key) {
@@ -136,11 +275,13 @@ export function buildTemplateMap(pageRules, doc) {
     const pathStr = pathArr.join('.')
     const wildcardKey = pathArr.map((s) => (typeof s === 'number' ? '*' : s)).join('.')
     const shape = shapeKindOf(rule)
+    const defaultKey =
+      shape === 'scalar' ? componentForScalarRule(rule, doc) : SHAPE_TO_DEFAULT_KEY[shape] || '@scalar'
 
     let tpl =
       (pathStr && findTemplate(doc, pathStr)) ||
       (wildcardKey && wildcardKey !== pathStr && findTemplate(doc, wildcardKey)) ||
-      findTemplate(doc, SHAPE_TO_DEFAULT_KEY[shape] || '@scalar')
+      findTemplate(doc, defaultKey)
 
     map.set(pathStr, tpl)