@glw907/cairn-cms 0.57.0 → 0.57.1

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project are recorded here, most recent first.
 
+## 0.57.1
+
+Media polish and cutover DX, the first follow-on after the `0.57.0` media stack. The Media Library
+gains the action feedback it lacked: a delete, a rename, and a commit conflict now land on a strip
+that confirms the result or shows the error, instead of a silent page. With the detail slide-over open
+and focus in the search box, Escape now clears the search and leaves the panel open, rather than doing
+both at once. A frontmatter hero marked decorative persists that choice as an additive `decorative` key
+on the `image` object, so a deliberately decorative hero stops reading as needs-alt after a reload (a
+decorative body image still cannot persist the choice, since markdown alt text has no slot for it). The
+reserved-`figure` build error now names the colliding component and points at the fix.
+
+The rest is documentation. The public media resolver wiring moved into the required media setup steps
+in both the upgrade guide and the wire-the-delivery guide, since a published `media:` token ships bare
+without it. The reserved-`figure` collision is now a prominent breaking callout. A new
+[content authoring syntax reference](docs/reference/authoring-syntax.md) documents the `cairn:` and
+`media:` token schemes together. The guides now show the `wrangler.toml` binding dialect, the
+`@glw907/cairn-cms/media` import path, the empty-`media.json` bootstrap, and the `.site-main` re-scope
+for the figure placement CSS.
+
+No consumer action is required. The `decorative` key is additive and optional, so existing content
+parses and builds unchanged, and the feedback strip, the Escape fix, and the registry error message
+are admin or build-time with no public surface change.
+
 ## 0.57.0
 
 Images become first-class. An editor can paste, drag, or insert an image straight into a post, and
@@ -93,6 +116,21 @@ default, so a site serves full-size bytes until it opts in. The wiring steps are
 in [the media reference](docs/reference/media.md) and
 [the sveltekit reference](docs/reference/sveltekit.md).
 
+Consumers must also wire the public media resolver for any public image. The bucket, route, and
+`assets` block make media work for the editor, but a published `![](media:...)` (a body image or a
+frontmatter hero) ships a bare token to the live page unless the site threads a resolver into the
+render path and `createPublicRoutes`. Build one with
+`makeMediaResolver(mediaManifest, normalizeAssets({ bucketBinding: 'MEDIA_BUCKET' }))` from
+`@glw907/cairn-cms/media`, where `mediaManifest` is the committed `src/content/.cairn/media.json`
+(create it as `{}` on a fresh site so the import resolves). The
+[upgrade guide](docs/guides/upgrade-cairn.md) gives the full snippet.
+
+Breaking: `figure` is now a reserved directive name. `defineRegistry` throws if a site registers a
+component named `figure`, which hard-fails both `cairn-manifest` and the build. A custom `figure` that
+the engine's built-in figure now covers should be removed so the site adopts the engine's; a `figure`
+that does something else should be renamed. Check too for any hand-authored `:::figure` block in your
+content, which now renders as an engine figure.
+
 Recommended, not required: regenerate the content manifest (`cairn-manifest`) and commit it so the
 Media Library's `main` where-used is accurate. The `mediaRefs` field is additive, so a site builds
 without it, but an un-regenerated manifest reads every published media reference as absent until it

package/dist/components/CairnMediaLibrary.svelte

@@ -62,6 +62,11 @@ projection and pulls in no editor module (the editor-boundary test bars a @codem
 
   let { data, form }: Props = $props();
 
+  // The success flash a redirected action carried back: a safe-delete or a metadata edit. The
+  // conflict error (data.flashError) renders in the inline error treatment below instead.
+  const FLASH_MESSAGE = { deleted: 'Asset deleted.', updated: 'Changes saved.' } as const;
+  const flashMessage = $derived(data.flash ? FLASH_MESSAGE[data.flash] : '');
+
   // --- the per-hash usage facts the screen joins onto each asset ---
   /** The distinct-entry usage count for an asset; zero when the asset has no usage key. */
   function usageCount(hash: string): number {
@@ -189,6 +194,7 @@ projection and pulls in no editor module (the editor-boundary test bars a @codem
   // The element that opened the slide-over (a tile or a row trigger), so focus returns to it on
   // close (the non-modal region recipe: focus moves in on open, back to the origin on close).
   let panelOrigin: HTMLElement | null = null;
+  let panelEl = $state<HTMLElement | null>(null);
   let closeButton = $state<HTMLButtonElement | null>(null);
   let deleteDialog = $state<HTMLDialogElement | null>(null);
 
@@ -210,8 +216,11 @@ projection and pulls in no editor module (the editor-boundary test bars a @codem
   // Escape closes the slide-over (the non-modal region recipe). A window listener carries it, the
   // way EditPage's details panel does, so the non-interactive region needs no keyboard handler. The
   // dialog (when open) claims Escape natively, so the panel handles it only when no dialog is up.
+  // Escape is also the native clear gesture for the toolbar's type="search" input, so the close
+  // fires only when focus is inside the panel: an Escape in the search box clears it and leaves the
+  // panel exactly as the user left it, while an Escape with focus in the panel still closes it.
   function onWindowKeydown(e: KeyboardEvent) {
-    if (e.key === 'Escape' && selected && !deleteDialog?.open) {
+    if (e.key === 'Escape' && selected && !deleteDialog?.open && panelEl?.contains(document.activeElement)) {
       e.preventDefault();
       closePanel();
     }
@@ -444,6 +453,16 @@ projection and pulls in no editor module (the editor-boundary test bars a @codem
   </button>
 </header>
 
+<!-- The action feedback strip (the office flash grammar). A persistent polite live region carries
+     the success message, so an inserted-fresh element is announced reliably; the visible alert below
+     keeps its styling without a role. The strip never steals focus. -->
+<div class="sr-only" aria-live="polite">{flashMessage}</div>
+{#if flashMessage}
+  <div class="alert alert-success mb-4 text-sm">{flashMessage}</div>
+{/if}
+{#if data.flashError}
+  <div role="alert" class="alert alert-error mb-4 text-sm">{data.flashError}</div>
+{/if}
 {#if data.error}
   <div role="alert" class="alert alert-warning mb-4 text-sm">{data.error}</div>
 {/if}
@@ -676,6 +695,7 @@ projection and pulls in no editor module (the editor-boundary test bars a @codem
        and focus returns to the originating tile or row (the region-with-focus-management recipe).
        Below the narrow breakpoint the same panel reads as a bottom sheet (the responsive treatment). -->
   <aside
+    bind:this={panelEl}
     role="region"
     aria-label="{asset.displayName} details"
     class="fixed inset-x-0 bottom-0 z-30 flex max-h-[85vh] flex-col rounded-t-2xl border-t border-[var(--cairn-card-border)] bg-base-100 shadow-[var(--cairn-shadow)] sm:inset-x-auto sm:bottom-0 sm:right-0 sm:top-16 sm:max-h-none sm:w-[22rem] sm:rounded-t-none sm:border-l sm:border-t-0"

package/dist/components/EditPage.svelte

@@ -1572,6 +1572,7 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
             bind:this={heroFieldRefs[field.name]}
             field={{ name: field.name, label: field.label }}
             value={heroValue}
+            decorative={heroValue?.decorative ?? false}
             mediaLibrary={mediaLibrary}
             conceptId={data.conceptId}
             id={data.id}

package/dist/components/MediaHeroField.svelte

@@ -2,14 +2,21 @@
 @component
 The hero image frontmatter field: the persistent details-panel field that sets a concept's lead
 picture, the one image that both leads the page and becomes the social card. It edits the structured
-value `{ src, alt, caption }` and writes it to three hidden form inputs the save path's decode arm
-reads. cairn stays markdown-first, so this is a structured-data form field, never a WYSIWYG canvas.
+value `{ src, alt, caption, decorative }` and writes it to four hidden form inputs the save path's
+decode arm reads. cairn stays markdown-first, so this is a structured-data form field, never a
+WYSIWYG canvas.
 
 The field renders inside the edit form (the EditPage details loop). A nested <form> would break SSR,
 so the field carries no <form> of its own: the working inputs in the dialog (the alt input, the
-caption input) carry no name and never submit, and the committed value rides three named hidden
-inputs (`<name>.src`, `<name>.alt`, `<name>.caption`). "Use this image" copies the dialog's working
-state into those hidden inputs; the form's own Save commits them.
+caption input) carry no name and never submit, and the committed value rides four named hidden
+inputs (`<name>.src`, `<name>.alt`, `<name>.caption`, `<name>.decorative`). "Use this image" copies
+the dialog's working state into those hidden inputs; the form's own Save commits them.
+
+The decorative choice persists for the frontmatter hero because the hero value is an object with a
+slot for it. A reload then tells a deliberately decorative hero apart from a left-blank alt, so a
+decorative hero no longer trips the needs-alt notice. A decorative body image (`![](media:...)`)
+cannot persist the same choice, since markdown alt has no slot for it, so a decorative body image
+still reads as needs-alt on reload.
 
 At rest, when a hero is set, the field is one row at sibling weight: the resolved thumbnail, the
 display name, an alt-status chip (Described, Needs alt, or Decorative, each a glyph plus a label,
@@ -49,7 +56,7 @@ popover's runUpload but resolves to this field, not an editor placeholder.
     /** The field descriptor: the form input name base and the visible label. */
     field: { name: string; label: string };
     /** The initial committed value, from `data.frontmatter[field.name]`. */
-    value?: { src: string; alt: string; caption?: string };
+    value?: { src: string; alt: string; caption?: string; decorative?: boolean };
     /** Whether the initial hero is an explicit decorative choice (an empty alt that is not debt).
      *  Defaults false; a fresh field with an empty alt reads as needs-alt. */
     decorative?: boolean;
@@ -444,12 +451,14 @@ popover's runUpload but resolves to this field, not an editor placeholder.
     </p>
   {/if}
 
-  <!-- The committed value rides three named hidden inputs the save path's decode arm reads. They sit
+  <!-- The committed value rides four named hidden inputs the save path's decode arm reads. They sit
        inside the edit form (this component renders in the detailFields loop), so they submit; the
-       dialog's working inputs carry no name and never submit. -->
+       dialog's working inputs carry no name and never submit. The decorative input persists the
+       explicit decorative choice so a reload tells it apart from a left-blank alt. -->
   <input type="hidden" name="{field.name}.src" value={committedSrc} />
   <input type="hidden" name="{field.name}.alt" value={committedAlt} />
   <input type="hidden" name="{field.name}.caption" value={committedCaption} />
+  <input type="hidden" name="{field.name}.decorative" value={committedDecorative ? 'true' : ''} />
 </div>
 
 <!-- The edit dialog: a native modal (focus trap and Escape for free). It sits at the end of the

package/dist/components/MediaHeroField.svelte.d.ts

@@ -11,6 +11,7 @@ interface Props {
         src: string;
         alt: string;
         caption?: string;
+        decorative?: boolean;
     };
     /** Whether the initial hero is an explicit decorative choice (an empty alt that is not debt).
      *  Defaults false; a fresh field with an empty alt reads as needs-alt. */
@@ -36,14 +37,21 @@ interface Props {
 /**
  * The hero image frontmatter field: the persistent details-panel field that sets a concept's lead
  * picture, the one image that both leads the page and becomes the social card. It edits the structured
- * value `{ src, alt, caption }` and writes it to three hidden form inputs the save path's decode arm
- * reads. cairn stays markdown-first, so this is a structured-data form field, never a WYSIWYG canvas.
+ * value `{ src, alt, caption, decorative }` and writes it to four hidden form inputs the save path's
+ * decode arm reads. cairn stays markdown-first, so this is a structured-data form field, never a
+ * WYSIWYG canvas.
  *
  * The field renders inside the edit form (the EditPage details loop). A nested <form> would break SSR,
  * so the field carries no <form> of its own: the working inputs in the dialog (the alt input, the
- * caption input) carry no name and never submit, and the committed value rides three named hidden
- * inputs (`<name>.src`, `<name>.alt`, `<name>.caption`). "Use this image" copies the dialog's working
- * state into those hidden inputs; the form's own Save commits them.
+ * caption input) carry no name and never submit, and the committed value rides four named hidden
+ * inputs (`<name>.src`, `<name>.alt`, `<name>.caption`, `<name>.decorative`). "Use this image" copies
+ * the dialog's working state into those hidden inputs; the form's own Save commits them.
+ *
+ * The decorative choice persists for the frontmatter hero because the hero value is an object with a
+ * slot for it. A reload then tells a deliberately decorative hero apart from a left-blank alt, so a
+ * decorative hero no longer trips the needs-alt notice. A decorative body image (`![](media:...)`)
+ * cannot persist the same choice, since markdown alt has no slot for it, so a decorative body image
+ * still reads as needs-alt on reload.
  *
  * At rest, when a hero is set, the field is one row at sibling weight: the resolved thumbnail, the
  * display name, an alt-status chip (Described, Needs alt, or Decorative, each a glyph plus a label,

package/dist/content/frontmatter.js

@@ -37,6 +37,11 @@ export function frontmatterFromForm(fields, form) {
                 const caption = String(form.get(`${field.name}.caption`) ?? '').trim();
                 if (caption !== '')
                     value.caption = caption;
+                // An explicit decorative choice persists so a reload tells it apart from a left-blank alt.
+                // The key is dropped otherwise to keep committed frontmatter minimal.
+                const decorative = String(form.get(`${field.name}.decorative`) ?? '');
+                if (decorative === 'true')
+                    value.decorative = true;
                 data[field.name] = value;
                 break;
             }

package/dist/content/types.d.ts

@@ -89,6 +89,8 @@ export interface ImageValue {
     src: string;
     alt: string;
     caption?: string;
+    /** An explicit decorative choice: an empty alt that is not debt. Omitted unless true. */
+    decorative?: boolean;
 }
 /**
  * A validator's verdict. On success it carries the normalized frontmatter to commit; on

package/dist/content/validate.js

@@ -56,6 +56,10 @@ export function validateFields(fields, frontmatter) {
                         const caption = typeof obj.caption === 'string' ? obj.caption.trim() : '';
                         if (caption !== '')
                             normalized.caption = caption;
+                        // An explicit decorative choice carries through; it is never required and never a save
+                        // block. A missing or non-boolean value drops the key, like a blank caption.
+                        if (obj.decorative === true)
+                            normalized.decorative = true;
                         data[field.name] = normalized;
                     }
                 }

package/dist/render/registry.js

@@ -17,7 +17,7 @@ function findIconField(def) {
 export function defineRegistry({ components }) {
     for (const c of components) {
         if (c.name === 'figure') {
-            throw new Error('cairn: "figure" is a reserved directive name handled by the engine render step; a component cannot use it');
+            throw new Error(`cairn: component "${c.name}" uses "figure", a reserved directive name handled by the engine render step: remove it if the engine's built-in figure now covers your use, or rename it otherwise`);
         }
         if (c.defaultIconByRole && Object.keys(c.defaultIconByRole).length > 0 && !findIconField(c)) {
             throw new Error(`cairn: component "${c.name}" sets defaultIconByRole but declares no type:'icon' attribute, so the default icon can never render`);

package/dist/sveltekit/content-routes.d.ts

@@ -128,7 +128,16 @@ export interface MediaLibraryData {
     assets: MediaLibraryEntry[];
     /** Per-hash usage overlay, kept separate from MediaLibraryEntry so the popover stays decoupled. */
     usage: Record<string, MediaUsageInfo>;
+    /** The degraded-load error: a failed token mint or media read. This slot is the failure of THIS
+     *  load, distinct from a prior action's conflict error (see `flashError`), so a read failure and a
+     *  redirected commit conflict never overwrite each other. */
     error: string | null;
+    /** The success flash a redirected action carries: `deleted` from `?deleted=1`, `updated` from
+     *  `?updated=1`, null otherwise. The component renders a polite success strip for each. */
+    flash: 'deleted' | 'updated' | null;
+    /** A redirected action's conflict error read from `?error=` (a commit-conflict bounce). Kept in
+     *  its own slot rather than the degraded-load `error` above, so the two never collide. */
+    flashError: string | null;
 }
 /** The structural event the content routes read; a real SvelteKit RequestEvent satisfies it. */
 export interface ContentEvent extends EventBase<GithubKeyEnv> {

package/dist/sveltekit/content-routes.js

@@ -219,12 +219,21 @@ export function createContentRoutes(runtime, deps = {}) {
      *  assets gathered so far rather than a thrown 500, mirroring listLoad's posture. */
     async function mediaLibraryLoad(event) {
         requireSession(event);
+        // Read the flash flags a redirected action carried back, mirroring listLoad's `?error`/
+        // `?publishedAll` grammar: a deleted/updated success flag and a commit-conflict error. The
+        // conflict error rides its own slot so it never collides with the degraded-load `error` below.
+        let flash = null;
+        if (event.url.searchParams.get('deleted') === '1')
+            flash = 'deleted';
+        else if (event.url.searchParams.get('updated') === '1')
+            flash = 'updated';
+        const flashError = event.url.searchParams.get('error');
         let token;
         try {
             token = await mintToken(event.platform?.env ?? {});
         }
         catch {
-            return { assets: [], usage: {}, error: 'Could not authenticate with GitHub.' };
+            return { assets: [], usage: {}, error: 'Could not authenticate with GitHub.', flash, flashError };
         }
         // Union the media manifest by hash: main's rows first, then any branch hash not already present.
         // Identical bytes share one row, so a hash on both branches prefers main's row. A failed or
@@ -253,7 +262,7 @@ export function createContentRoutes(runtime, deps = {}) {
         catch {
             // A wholesale read failure leaves whatever rows were already unioned; the screen lists them
             // with no usage overlay rather than failing.
-            return { assets: [...union.values()].map(mediaLibraryEntry), usage: {}, error: 'Could not load media.' };
+            return { assets: [...union.values()].map(mediaLibraryEntry), usage: {}, error: 'Could not load media.', flash, flashError };
         }
         const assets = [...union.values()].map(mediaLibraryEntry);
         // Build the where-used overlay from main's content manifest plus the open branches. A failure
@@ -272,7 +281,7 @@ export function createContentRoutes(runtime, deps = {}) {
         catch {
             usage = {};
         }
-        return { assets, usage, error: null };
+        return { assets, usage, error: null, flash, flashError };
     }
     /** Create a new entry: validate the slug, compose a dated id when the concept is dated, refuse to clobber. */
     async function createAction(event) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.57.0",
+  "version": "0.57.1",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [

package/src/lib/components/CairnMediaLibrary.svelte

@@ -62,6 +62,11 @@ projection and pulls in no editor module (the editor-boundary test bars a @codem
 
   let { data, form }: Props = $props();
 
+  // The success flash a redirected action carried back: a safe-delete or a metadata edit. The
+  // conflict error (data.flashError) renders in the inline error treatment below instead.
+  const FLASH_MESSAGE = { deleted: 'Asset deleted.', updated: 'Changes saved.' } as const;
+  const flashMessage = $derived(data.flash ? FLASH_MESSAGE[data.flash] : '');
+
   // --- the per-hash usage facts the screen joins onto each asset ---
   /** The distinct-entry usage count for an asset; zero when the asset has no usage key. */
   function usageCount(hash: string): number {
@@ -189,6 +194,7 @@ projection and pulls in no editor module (the editor-boundary test bars a @codem
   // The element that opened the slide-over (a tile or a row trigger), so focus returns to it on
   // close (the non-modal region recipe: focus moves in on open, back to the origin on close).
   let panelOrigin: HTMLElement | null = null;
+  let panelEl = $state<HTMLElement | null>(null);
   let closeButton = $state<HTMLButtonElement | null>(null);
   let deleteDialog = $state<HTMLDialogElement | null>(null);
 
@@ -210,8 +216,11 @@ projection and pulls in no editor module (the editor-boundary test bars a @codem
   // Escape closes the slide-over (the non-modal region recipe). A window listener carries it, the
   // way EditPage's details panel does, so the non-interactive region needs no keyboard handler. The
   // dialog (when open) claims Escape natively, so the panel handles it only when no dialog is up.
+  // Escape is also the native clear gesture for the toolbar's type="search" input, so the close
+  // fires only when focus is inside the panel: an Escape in the search box clears it and leaves the
+  // panel exactly as the user left it, while an Escape with focus in the panel still closes it.
   function onWindowKeydown(e: KeyboardEvent) {
-    if (e.key === 'Escape' && selected && !deleteDialog?.open) {
+    if (e.key === 'Escape' && selected && !deleteDialog?.open && panelEl?.contains(document.activeElement)) {
       e.preventDefault();
       closePanel();
     }
@@ -444,6 +453,16 @@ projection and pulls in no editor module (the editor-boundary test bars a @codem
   </button>
 </header>
 
+<!-- The action feedback strip (the office flash grammar). A persistent polite live region carries
+     the success message, so an inserted-fresh element is announced reliably; the visible alert below
+     keeps its styling without a role. The strip never steals focus. -->
+<div class="sr-only" aria-live="polite">{flashMessage}</div>
+{#if flashMessage}
+  <div class="alert alert-success mb-4 text-sm">{flashMessage}</div>
+{/if}
+{#if data.flashError}
+  <div role="alert" class="alert alert-error mb-4 text-sm">{data.flashError}</div>
+{/if}
 {#if data.error}
   <div role="alert" class="alert alert-warning mb-4 text-sm">{data.error}</div>
 {/if}
@@ -676,6 +695,7 @@ projection and pulls in no editor module (the editor-boundary test bars a @codem
        and focus returns to the originating tile or row (the region-with-focus-management recipe).
        Below the narrow breakpoint the same panel reads as a bottom sheet (the responsive treatment). -->
   <aside
+    bind:this={panelEl}
     role="region"
     aria-label="{asset.displayName} details"
     class="fixed inset-x-0 bottom-0 z-30 flex max-h-[85vh] flex-col rounded-t-2xl border-t border-[var(--cairn-card-border)] bg-base-100 shadow-[var(--cairn-shadow)] sm:inset-x-auto sm:bottom-0 sm:right-0 sm:top-16 sm:max-h-none sm:w-[22rem] sm:rounded-t-none sm:border-l sm:border-t-0"

package/src/lib/components/EditPage.svelte

@@ -1572,6 +1572,7 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
             bind:this={heroFieldRefs[field.name]}
             field={{ name: field.name, label: field.label }}
             value={heroValue}
+            decorative={heroValue?.decorative ?? false}
             mediaLibrary={mediaLibrary}
             conceptId={data.conceptId}
             id={data.id}

package/src/lib/components/MediaHeroField.svelte

@@ -2,14 +2,21 @@
 @component
 The hero image frontmatter field: the persistent details-panel field that sets a concept's lead
 picture, the one image that both leads the page and becomes the social card. It edits the structured
-value `{ src, alt, caption }` and writes it to three hidden form inputs the save path's decode arm
-reads. cairn stays markdown-first, so this is a structured-data form field, never a WYSIWYG canvas.
+value `{ src, alt, caption, decorative }` and writes it to four hidden form inputs the save path's
+decode arm reads. cairn stays markdown-first, so this is a structured-data form field, never a
+WYSIWYG canvas.
 
 The field renders inside the edit form (the EditPage details loop). A nested <form> would break SSR,
 so the field carries no <form> of its own: the working inputs in the dialog (the alt input, the
-caption input) carry no name and never submit, and the committed value rides three named hidden
-inputs (`<name>.src`, `<name>.alt`, `<name>.caption`). "Use this image" copies the dialog's working
-state into those hidden inputs; the form's own Save commits them.
+caption input) carry no name and never submit, and the committed value rides four named hidden
+inputs (`<name>.src`, `<name>.alt`, `<name>.caption`, `<name>.decorative`). "Use this image" copies
+the dialog's working state into those hidden inputs; the form's own Save commits them.
+
+The decorative choice persists for the frontmatter hero because the hero value is an object with a
+slot for it. A reload then tells a deliberately decorative hero apart from a left-blank alt, so a
+decorative hero no longer trips the needs-alt notice. A decorative body image (`![](media:...)`)
+cannot persist the same choice, since markdown alt has no slot for it, so a decorative body image
+still reads as needs-alt on reload.
 
 At rest, when a hero is set, the field is one row at sibling weight: the resolved thumbnail, the
 display name, an alt-status chip (Described, Needs alt, or Decorative, each a glyph plus a label,
@@ -49,7 +56,7 @@ popover's runUpload but resolves to this field, not an editor placeholder.
     /** The field descriptor: the form input name base and the visible label. */
     field: { name: string; label: string };
     /** The initial committed value, from `data.frontmatter[field.name]`. */
-    value?: { src: string; alt: string; caption?: string };
+    value?: { src: string; alt: string; caption?: string; decorative?: boolean };
     /** Whether the initial hero is an explicit decorative choice (an empty alt that is not debt).
      *  Defaults false; a fresh field with an empty alt reads as needs-alt. */
     decorative?: boolean;
@@ -444,12 +451,14 @@ popover's runUpload but resolves to this field, not an editor placeholder.
     </p>
   {/if}
 
-  <!-- The committed value rides three named hidden inputs the save path's decode arm reads. They sit
+  <!-- The committed value rides four named hidden inputs the save path's decode arm reads. They sit
        inside the edit form (this component renders in the detailFields loop), so they submit; the
-       dialog's working inputs carry no name and never submit. -->
+       dialog's working inputs carry no name and never submit. The decorative input persists the
+       explicit decorative choice so a reload tells it apart from a left-blank alt. -->
   <input type="hidden" name="{field.name}.src" value={committedSrc} />
   <input type="hidden" name="{field.name}.alt" value={committedAlt} />
   <input type="hidden" name="{field.name}.caption" value={committedCaption} />
+  <input type="hidden" name="{field.name}.decorative" value={committedDecorative ? 'true' : ''} />
 </div>
 
 <!-- The edit dialog: a native modal (focus trap and Escape for free). It sits at the end of the

package/src/lib/content/frontmatter.ts

@@ -42,6 +42,10 @@ export function frontmatterFromForm(
         };
         const caption = String(form.get(`${field.name}.caption`) ?? '').trim();
         if (caption !== '') value.caption = caption;
+        // An explicit decorative choice persists so a reload tells it apart from a left-blank alt.
+        // The key is dropped otherwise to keep committed frontmatter minimal.
+        const decorative = String(form.get(`${field.name}.decorative`) ?? '');
+        if (decorative === 'true') value.decorative = true;
         data[field.name] = value;
         break;
       }

package/src/lib/content/types.ts

@@ -109,6 +109,8 @@ export interface ImageValue {
   src: string;
   alt: string;
   caption?: string;
+  /** An explicit decorative choice: an empty alt that is not debt. Omitted unless true. */
+  decorative?: boolean;
 }
 
 /**

package/src/lib/content/validate.ts

@@ -60,6 +60,9 @@ export function validateFields(
             };
             const caption = typeof obj.caption === 'string' ? obj.caption.trim() : '';
             if (caption !== '') normalized.caption = caption;
+            // An explicit decorative choice carries through; it is never required and never a save
+            // block. A missing or non-boolean value drops the key, like a blank caption.
+            if (obj.decorative === true) normalized.decorative = true;
             data[field.name] = normalized;
           }
         }

package/src/lib/render/registry.ts

@@ -129,7 +129,7 @@ export function defineRegistry({ components }: { components: ComponentDef[] }):
   for (const c of components) {
     if (c.name === 'figure') {
       throw new Error(
-        'cairn: "figure" is a reserved directive name handled by the engine render step; a component cannot use it',
+        `cairn: component "${c.name}" uses "figure", a reserved directive name handled by the engine render step: remove it if the engine's built-in figure now covers your use, or rename it otherwise`,
       );
     }
     if (c.defaultIconByRole && Object.keys(c.defaultIconByRole).length > 0 && !findIconField(c)) {

package/src/lib/sveltekit/content-routes.ts

@@ -152,7 +152,16 @@ export interface MediaLibraryData {
   assets: MediaLibraryEntry[];
   /** Per-hash usage overlay, kept separate from MediaLibraryEntry so the popover stays decoupled. */
   usage: Record<string, MediaUsageInfo>;
+  /** The degraded-load error: a failed token mint or media read. This slot is the failure of THIS
+   *  load, distinct from a prior action's conflict error (see `flashError`), so a read failure and a
+   *  redirected commit conflict never overwrite each other. */
   error: string | null;
+  /** The success flash a redirected action carries: `deleted` from `?deleted=1`, `updated` from
+   *  `?updated=1`, null otherwise. The component renders a polite success strip for each. */
+  flash: 'deleted' | 'updated' | null;
+  /** A redirected action's conflict error read from `?error=` (a commit-conflict bounce). Kept in
+   *  its own slot rather than the degraded-load `error` above, so the two never collide. */
+  flashError: string | null;
 }
 
 /** The structural event the content routes read; a real SvelteKit RequestEvent satisfies it. */
@@ -448,11 +457,18 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
    *  assets gathered so far rather than a thrown 500, mirroring listLoad's posture. */
   async function mediaLibraryLoad(event: ContentEvent): Promise<MediaLibraryData> {
     requireSession(event);
+    // Read the flash flags a redirected action carried back, mirroring listLoad's `?error`/
+    // `?publishedAll` grammar: a deleted/updated success flag and a commit-conflict error. The
+    // conflict error rides its own slot so it never collides with the degraded-load `error` below.
+    let flash: MediaLibraryData['flash'] = null;
+    if (event.url.searchParams.get('deleted') === '1') flash = 'deleted';
+    else if (event.url.searchParams.get('updated') === '1') flash = 'updated';
+    const flashError = event.url.searchParams.get('error');
     let token: string;
     try {
       token = await mintToken(event.platform?.env ?? {});
     } catch {
-      return { assets: [], usage: {}, error: 'Could not authenticate with GitHub.' };
+      return { assets: [], usage: {}, error: 'Could not authenticate with GitHub.', flash, flashError };
     }
 
     // Union the media manifest by hash: main's rows first, then any branch hash not already present.
@@ -484,7 +500,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     } catch {
       // A wholesale read failure leaves whatever rows were already unioned; the screen lists them
       // with no usage overlay rather than failing.
-      return { assets: [...union.values()].map(mediaLibraryEntry), usage: {}, error: 'Could not load media.' };
+      return { assets: [...union.values()].map(mediaLibraryEntry), usage: {}, error: 'Could not load media.', flash, flashError };
     }
     const assets = [...union.values()].map(mediaLibraryEntry);
 
@@ -504,7 +520,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
       usage = {};
     }
 
-    return { assets, usage, error: null };
+    return { assets, usage, error: null, flash, flashError };
   }
 
   /** Create a new entry: validate the slug, compose a dated id when the concept is dated, refuse to clobber. */