@glw907/cairn-cms 0.56.1 → 0.57.0

package/src/lib/render/component-grammar.ts

@@ -76,7 +76,7 @@ function isContainer(node: RootContent): node is RootContent & DirectiveNode {
 
 // Pin the bullet to `-` so a markdown body or slot that uses dash bullets round-trips unchanged
 // rather than drifting to remark-stringify's default `*`, which would silently mutate author content.
-const toMd = unified().use(remarkStringify, { bullet: '-' });
+const toMd = unified().use(remarkDirective).use(remarkStringify, { bullet: '-' });
 
 /** Render mdast children back to trimmed markdown text. */
 function childrenToText(children: RootContent[]): string {
@@ -149,6 +149,48 @@ export function parseRawAttributeKeys(markdown: string, def: ComponentDef): stri
   return rawKeysFromRoot(findComponentRoot(markdown, def));
 }
 
+/** The result of {@link componentRoundTripSafety}: whether re-opening a placed block into the
+ *  guided form and re-serializing it is provably lossless. */
+export type RoundTripSafety =
+  | { safe: true }
+  | { safe: false; reason: 'unknown-attribute' | 'undeclared-child' | 'not-idempotent' | 'not-a-component' };
+
+/** Decide whether guided edit of this placed block is provably lossless. A block a person typed by
+ *  hand can carry more than the schema models (an attribute the def does not list, a child container
+ *  the def does not declare, slot content the form cannot represent stably), and parsing such a block
+ *  into the form then re-serializing would silently drop it. The edit affordance is offered only when
+ *  this returns `{ safe: true }`. Checks run in order and return the first failure:
+ *
+ *  1. `not-a-component`: the def's opening container is not present.
+ *  2. `unknown-attribute`: the block carries an attribute key the def does not declare.
+ *  3. `undeclared-child`: the root has a direct child container directive that is not a declared
+ *     nested slot. Such a child would otherwise fold into the body slot and move on re-serialize.
+ *  4. `not-idempotent`: `parse -> serialize -> parse` does not recover the same values. */
+export async function componentRoundTripSafety(markdown: string, def: ComponentDef): Promise<RoundTripSafety> {
+  const root = findComponentRoot(markdown, def);
+  if (!root) return { safe: false, reason: 'not-a-component' };
+
+  const declaredKeys = new Set((def.attributes ?? []).map((f) => f.key));
+  for (const key of parseRawAttributeKeys(markdown, def)) {
+    if (!declaredKeys.has(key)) return { safe: false, reason: 'unknown-attribute' };
+  }
+
+  const slotNames = new Set(nestedSlots(def).map((s) => s.name));
+  for (const child of root.children) {
+    if (isContainer(child) && !slotNames.has((child as DirectiveNode).name)) {
+      return { safe: false, reason: 'undeclared-child' };
+    }
+  }
+
+  // The values are plain strings, booleans, and string arrays in declared (object-key) order, so a
+  // stable JSON.stringify is a sufficient deep-equal.
+  const v1 = await parseComponent(markdown, def);
+  const v2 = await parseComponent(serializeComponent(def, v1), def);
+  if (JSON.stringify(v1) !== JSON.stringify(v2)) return { safe: false, reason: 'not-idempotent' };
+
+  return { safe: true };
+}
+
 /** Parse the component once and derive both the guided-form values and the raw attribute keys.
  *  Validation needs both, so this seam spares it the double parse that calling
  *  {@link parseComponent} and {@link parseRawAttributeKeys} separately would cost. */
@@ -178,8 +220,22 @@ function isDirectiveLabel(node: RootContent): boolean {
 
 function readLabel(root: DirectiveNode): string | undefined {
   for (const child of root.children) {
-    const p = child as { type: string; data?: { directiveLabel?: boolean }; children?: { value?: string }[] };
-    if (p.type === 'paragraph' && p.data?.directiveLabel) return (p.children ?? []).map((c) => c.value ?? '').join('');
+    const p = child as {
+      type: string;
+      data?: { directiveLabel?: boolean };
+      children?: RootContent[];
+    };
+    if (p.type !== 'paragraph' || !p.data?.directiveLabel) continue;
+    const kids = p.children ?? [];
+    // When every label child is a plain text node, join the raw `.value`s. That keeps the pure-text
+    // path identical to before, so a literal `[` or `]` in the title is not re-escaped by the
+    // stringifier (serializeComponent already escapes brackets, and remark un-escapes them on parse).
+    // When the label carries inline markdown (a link, bold, emphasis), the text-only join would drop
+    // the markup, so stringify the children to recover the full inline source losslessly.
+    if (kids.every((c) => (c as { type: string }).type === 'text')) {
+      return kids.map((c) => (c as { value?: string }).value ?? '').join('');
+    }
+    return childrenToText(kids);
   }
   return undefined;
 }

package/src/lib/render/component-validate.ts

@@ -1,5 +1,5 @@
 import { parseComponentWithRawKeys } from './component-grammar.js';
-import type { ComponentDef } from './registry.js';
+import type { ComponentDef, ComponentValues } from './registry.js';
 
 /** A validation verdict: ok, or field-keyed error messages. */
 export type ComponentValidation = { ok: true } | { ok: false; errors: Record<string, string> };
@@ -18,6 +18,15 @@ export async function validateComponent(markdown: string, def: ComponentDef): Pr
     }
     if (field.type === 'select' && typeof v === 'string' && v !== '' && !(field.options ?? []).includes(v)) {
       errors[field.key] = `${field.label} must be one of: ${(field.options ?? []).join(', ')}.`;
+      continue;
+    }
+    if (field.pattern && typeof v === 'string' && v !== '' && !new RegExp(field.pattern.source).test(v)) {
+      errors[field.key] = field.pattern.message;
+      continue;
+    }
+    if (field.validate) {
+      const message = runFieldValidator(def, field.key, () => field.validate!(v, values));
+      if (typeof message === 'string') errors[field.key] = message;
     }
   }
 
@@ -34,3 +43,15 @@ export async function validateComponent(markdown: string, def: ComponentDef): Pr
 
   return Object.keys(errors).length ? { ok: false, errors } : { ok: true };
 }
+
+// Run a site-supplied attribute validator. The validator is author code, so a throw is contained:
+// the field is treated as valid and a dev-time warning names the component and field so the author
+// can find the bug. A returned string is the field error; anything else (null) is clean.
+function runFieldValidator(def: ComponentDef, key: string, call: () => string | null): string | null {
+  try {
+    return call();
+  } catch (err) {
+    console.warn(`cairn: validate() for component "${def.name}" field "${key}" threw; treating the field as valid.`, err);
+    return null;
+  }
+}

package/src/lib/render/pipeline.ts

@@ -11,7 +11,9 @@ import type { Schema } from 'hast-util-sanitize';
 import { VFile } from 'vfile';
 import { buildSanitizeSchema, rehypeAnchorRel, rehypeSinkGuard } from './sanitize-schema.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
+import { remarkFigure } from './remark-figure.js';
 import { remarkResolveCairnLinks, CAIRN_RESOLVE } from './resolve-links.js';
+import { remarkResolveMedia, MEDIA_RESOLVE, type MediaResolve } from './resolve-media.js';
 import { rehypeDispatch } from './rehype-dispatch.js';
 import { defineRegistry, type ComponentRegistry } from './registry.js';
 import type { LinkResolve } from '../content/links.js';
@@ -43,7 +45,13 @@ export function createRenderer(
   registry: ComponentRegistry = defineRegistry({ components: [] }),
   options: RendererOptions = {},
 ) {
-  const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry], remarkResolveCairnLinks];
+  const remarkPlugins: PluggableList = [
+    remarkDirective,
+    [remarkDirectiveStamp, registry],
+    remarkResolveCairnLinks,
+    remarkFigure,
+    remarkResolveMedia,
+  ];
   // The sanitize floor runs after rehype-raw (so author raw HTML is parsed, then cleaned) and
   // before the dispatch (so the site's trusted build() output and its inline SVG icons are never
   // sanitized). The anchor-rel hardening runs last so it also covers component-built anchors.
@@ -71,8 +79,14 @@ export function createRenderer(
   return {
     remarkPlugins,
     rehypePlugins,
-    renderMarkdown: async (content: string, opts: { resolve?: LinkResolve } = {}): Promise<string> => {
-      const file = new VFile({ value: content, data: { [CAIRN_RESOLVE]: opts.resolve } });
+    renderMarkdown: async (
+      content: string,
+      opts: { resolve?: LinkResolve; resolveMedia?: MediaResolve } = {},
+    ): Promise<string> => {
+      const file = new VFile({
+        value: content,
+        data: { [CAIRN_RESOLVE]: opts.resolve, [MEDIA_RESOLVE]: opts.resolveMedia },
+      });
       return String(await processor.process(file));
     },
   };

package/src/lib/render/registry.ts

@@ -22,6 +22,12 @@ export interface AttributeField {
   options?: readonly string[];
   /** Helper text shown under the field. */
   help?: string;
+  /** A RegExp `source` to validate the value against, plus the message to show on a mismatch. */
+  pattern?: { source: string; message: string };
+  /** A pure, browser-safe cross-field validator. Returns an error string, or null when valid.
+   *  Receives the field's value and the full {@link ComponentValues} so a rule can read sibling
+   *  fields. The picker wraps the call in try/catch so an author's throw never crashes the form. */
+  validate?: (value: string | boolean, all: ComponentValues) => string | null;
 }
 
 export type SlotKind = 'markdown' | 'inline' | 'repeatable';
@@ -36,6 +42,9 @@ export interface SlotDef {
   help?: string;
   /** For `kind: 'repeatable'`: the fields composing each list item (v1 uses the first field). */
   itemFields?: AttributeField[];
+  /** For `kind: 'repeatable'`: derives a row's label from its item values and zero-based index.
+   *  When it returns nothing, the picker falls back to `${label} ${index + 1}`. */
+  itemLabel?: (item: Record<string, string | boolean>, index: number) => string;
 }
 
 /** The structured input a component's `build` receives. The engine stamps the component's
@@ -75,6 +84,18 @@ export interface ComponentDef {
   attributes?: AttributeField[];
   /** The named content regions this component accepts. */
   slots?: SlotDef[];
+  /** A glyph key from the site IconSet, shown beside the label in the picker. */
+  icon?: string;
+  /** A category heading for the picker. Components order by declaration within a group. */
+  group?: string;
+  /** Omit from the top-level picker (for a nested or round-trip-only component). */
+  hidden?: boolean;
+  /** A structured sample the picker seeds the form with and renders through the same path a real
+   *  insert takes. Declaring `preview` is what opts the component into the two-pane configure layout. */
+  preview?: {
+    attributes?: Record<string, string | boolean>;
+    slots?: Record<string, string | string[]>;
+  };
 }
 
 export interface ComponentRegistry {
@@ -106,6 +127,11 @@ function findIconField(def: ComponentDef): AttributeField | undefined {
  */
 export function defineRegistry({ components }: { components: ComponentDef[] }): ComponentRegistry {
   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',
+      );
+    }
     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`,
@@ -145,3 +171,15 @@ export function emptyValues(def: ComponentDef): ComponentValues {
   }
   return { attributes, slots };
 }
+
+/** Seed {@link ComponentValues} from a component's `preview` sample: the {@link emptyValues} base
+ *  with `def.preview.attributes` and `def.preview.slots` overlaid (a shallow merge per side). When
+ *  the def declares no `preview`, returns exactly the {@link emptyValues} output. */
+export function previewValues(def: ComponentDef): ComponentValues {
+  const base = emptyValues(def);
+  if (!def.preview) return base;
+  return {
+    attributes: { ...base.attributes, ...def.preview.attributes },
+    slots: { ...base.slots, ...def.preview.slots },
+  };
+}

package/src/lib/render/remark-figure.ts

@@ -0,0 +1,132 @@
+// cairn-cms: the figure render step, an mdast step in the shared render pipeline. It rewrites the
+// cairn-reserved `figure` container directive into a <figure><img><figcaption> structure. The
+// directive wraps a real media image (`![alt](media:slug.hash)`), so the image stays a child node
+// and remarkResolveMedia resolves it untouched, exactly as a bare inline image. The caption is the
+// directive's body text, and the placement role rides the directive's class attribute as a value
+// from a closed set. This step runs before remarkResolveMedia and before remark-rehype flattens the
+// tree. It is engine-internal and reserved, the sibling of resolveMedia and resolveLinks, exported
+// from no public subpath. A site cannot register a component named `figure`, so it cannot shadow it.
+import type { Root, Paragraph, PhrasingContent } from 'mdast';
+import type { ContainerDirective } from 'mdast-util-directive';
+import { visit } from 'unist-util-visit';
+import { parseMediaToken } from '../media/reference.js';
+
+// The directive's children are block content. The unwrap lifts the media image to a direct child of
+// the figure, which is a phrasing node in block position: legal in the rendered <figure> and handled
+// by mdast-util-to-hast, but outside mdast's block-content union. This alias names that child slot.
+type FigureChild = ContainerDirective['children'][number];
+
+/** The closed placement role set. A class outside this set is ignored, never passed through. */
+const ROLES = new Set(['center', 'wide', 'full']);
+
+// mdast-util-to-hast reads hName/hProperties off node.data to override the element. The shipped
+// mdast Data type does not carry them, so this mirrors the local cast idiom in remark-directives.ts.
+interface HastData {
+  hName?: string;
+  hProperties?: Record<string, unknown>;
+}
+
+function setData(node: { data?: unknown }, patch: HastData): void {
+  const data = (node.data ?? (node.data = {})) as HastData;
+  Object.assign(data, patch);
+}
+
+// A node whose subtree carries non-whitespace text is a caption candidate.
+function hasText(node: FigureChild): boolean {
+  let found = false;
+  visit(node, 'text', (text) => {
+    if (text.value.trim() !== '') found = true;
+  });
+  return found;
+}
+
+// Find the first descendant image node whose url is a media: reference, with its enclosing direct
+// child of the directive (the paragraph holding it) and that child's index.
+function findMediaImage(
+  directive: ContainerDirective,
+): { image: PhrasingContent; childIndex: number } | null {
+  for (let i = 0; i < directive.children.length; i++) {
+    const child = directive.children[i];
+    if (child.type !== 'paragraph') continue;
+    const image = child.children.find(
+      (n) => n.type === 'image' && parseMediaToken(n.url) !== null,
+    );
+    if (image) return { image, childIndex: i };
+  }
+  return null;
+}
+
+// Strip a leading newline or all-whitespace prefix from the first phrasing child, so a caption
+// split off the image line reads cleanly without a stray softbreak.
+function trimLeadingNewline(children: PhrasingContent[]): PhrasingContent[] {
+  if (children.length === 0) return children;
+  const [first, ...rest] = children;
+  if (first.type === 'text') {
+    const trimmed = first.value.replace(/^\s+/, '');
+    if (trimmed === '') return rest;
+    return [{ ...first, value: trimmed }, ...rest];
+  }
+  return children;
+}
+
+/** Rewrite the reserved `figure` container directive into a placed <figure>. Every other directive
+ *  is left to remarkDirectiveStamp, which already skips unregistered names. */
+export function remarkFigure() {
+  return (tree: Root): void => {
+    visit(tree, 'containerDirective', (node: ContainerDirective) => {
+      if (node.name !== 'figure') return;
+
+      // The role rides the class attribute, kept only when it is exactly one closed-set value.
+      const className = node.attributes?.class ?? undefined;
+      const role = className && ROLES.has(className) ? className : undefined;
+      setData(node, {
+        hName: 'figure',
+        ...(role ? { hProperties: { className: ['cairn-place-' + role] } } : {}),
+      });
+
+      const found = findMediaImage(node);
+      // A figure with no media image is a degraded authoring state: leave its children, invent no
+      // image, never throw. The hName is already set, so it still renders as a <figure>.
+      if (!found) return;
+
+      const { image, childIndex } = found;
+      const paragraph = node.children[childIndex] as Paragraph;
+
+      // The image lifts into block position (the unwrap), so it carries the FigureChild slot type.
+      const imageChild = image as FigureChild;
+
+      // Unwrap the image to a direct child of the directive, handling both paragraph forms.
+      let captionNode: FigureChild | undefined;
+      if (paragraph.children.length === 1) {
+        // Blank-line form: the image is alone in its paragraph. The bare image replaces it; a
+        // separate following text-bearing paragraph is the caption.
+        node.children.splice(childIndex, 1, imageChild);
+      } else {
+        // No-blank-line form: the image and the caption share one paragraph. Split it into the bare
+        // image followed by a paragraph holding the remaining children as the caption.
+        const imageIndex = paragraph.children.indexOf(image);
+        const rest = trimLeadingNewline(paragraph.children.slice(imageIndex + 1));
+        const replacement: FigureChild[] = [imageChild];
+        if (rest.length > 0) {
+          const captionParagraph: Paragraph = { type: 'paragraph', children: rest };
+          replacement.push(captionParagraph);
+          captionNode = captionParagraph;
+        }
+        node.children.splice(childIndex, 1, ...replacement);
+      }
+
+      // The caption is the first text-bearing block after the image. In the split case it is the
+      // paragraph just appended; otherwise scan the blocks following the image.
+      const imagePos = node.children.indexOf(imageChild);
+      if (!captionNode) {
+        for (let i = imagePos + 1; i < node.children.length; i++) {
+          if (hasText(node.children[i])) {
+            captionNode = node.children[i];
+            break;
+          }
+        }
+      }
+      if (captionNode) setData(captionNode, { hName: 'figcaption' });
+    });
+  };
+}

package/src/lib/render/resolve-media.ts

@@ -0,0 +1,96 @@
+// cairn-cms: the media: reference resolver, an mdast step in the render pipeline. It mirrors the
+// cairn: link resolver in ./resolve-links.ts: it runs before remark-rehype, so the rewritten src
+// passes through the sanitize floor exactly as any other image. The per-call resolver is read off
+// the VFile (set by renderMarkdown), so the processor is still built once. A miss either marks the
+// image broken (preview) or throws (build), decided by the injected resolver.
+import { visit } from 'unist-util-visit';
+import type { VFile } from 'vfile';
+import { parseMediaToken, type MediaRef } from '../media/reference.js';
+import { findByHash, type MediaManifest } from '../media/manifest.js';
+import { publicPath } from '../media/naming.js';
+import { presetUrl } from '../media/transform-url.js';
+import type { ResolvedAssetConfig } from '../media/config.js';
+import { log } from '../log/index.js';
+
+/** The VFile data key the renderer sets the per-call media resolver under. */
+export const MEDIA_RESOLVE = 'mediaResolve';
+
+/** Resolve a media reference to its delivery URL. `undefined` is a preview miss (the plugin marks
+ *  the image broken); a resolver that throws is the build backstop (the error propagates out of
+ *  render and fails the build), exactly like LinkResolve. */
+export type MediaResolve = (ref: MediaRef) => string | undefined;
+
+/** Build the per-call media resolver, closing over the manifest and the resolved config. The
+ *  returned resolver looks a ref's content hash up in the manifest and builds the canonical delivery
+ *  path from the manifest entry's slug and ext, not the token's, so a rename never breaks the
+ *  reference. With a preset and zone transformations on it returns the variant URL; without a preset,
+ *  or when transformations are off, it returns the bare full-size path so a fresh zone with Image
+ *  Transformations disabled serves correct thumbnails rather than dead /cdn-cgi/image URLs. It returns
+ *  undefined when media is off or no entry carries the hash (the preview-miss backstop). */
+export function makeMediaResolver(
+  manifest: MediaManifest,
+  resolved: ResolvedAssetConfig,
+  opts?: { preset?: string },
+): MediaResolve {
+  return (ref: MediaRef): string | undefined => {
+    if (!resolved.enabled) return undefined;
+    const entry = findByHash(manifest, ref.hash);
+    if (!entry) {
+      // A real miss: media is on but the hash has no manifest row, the broken-reference case. The
+      // media-off path above stays silent, since an unresolved token there is expected, not a fault.
+      log.warn('media.resolve_missing', { hash: ref.hash });
+      return undefined;
+    }
+    const path = publicPath(entry.slug, entry.hash, entry.ext, resolved.urlForm, resolved.publicBase);
+    if (opts?.preset && resolved.transformations) {
+      return presetUrl(path, opts.preset, resolved.variants);
+    }
+    return path;
+  };
+}
+
+/** A resolver backed by the lean `mediaTargets` projection, for the admin preview. It mirrors
+ *  manifestLinkResolver: a hash present in the projection builds the slug delivery path
+ *  (`/media/<slug>.<hash>.<ext>`); a miss returns undefined, so the render step marks the image
+ *  broken rather than throwing. Pure over the projection, with no manifest and no config, so the
+ *  edit page reaches it with the data it actually has. */
+export function manifestMediaResolver(
+  targets: Record<string, { slug: string; ext: string; contentType: string }>,
+): MediaResolve {
+  return (ref: MediaRef): string | undefined => {
+    const entry = targets[ref.hash];
+    if (!entry) return undefined;
+    return publicPath(entry.slug, ref.hash, entry.ext, 'slug');
+  };
+}
+
+interface ImageNode {
+  url: string;
+  data?: { hProperties?: Record<string, unknown> };
+}
+
+/** Resolve media: image nodes against the VFile's resolver. A non-media src and a malformed token
+ *  pass through. A missing target is marked with the cairn-broken-media class (the resolver returns
+ *  undefined) or, when the resolver throws, the error propagates and fails the build. */
+export function remarkResolveMedia() {
+  return (tree: unknown, file: VFile): void => {
+    const resolve = file.data[MEDIA_RESOLVE] as MediaResolve | undefined;
+    if (!resolve) return;
+    visit(tree as Parameters<typeof visit>[0], 'image', (node: ImageNode) => {
+      const ref = parseMediaToken(node.url);
+      if (!ref) return;
+      const url = resolve(ref); // may throw (build backstop); propagates out of render
+      if (url) {
+        node.url = url;
+        return;
+      }
+      // Missing asset in the preview: mark it broken and neutralize the src, keeping the alt.
+      node.url = '#';
+      node.data = node.data ?? {};
+      const props = (node.data.hProperties = node.data.hProperties ?? {});
+      const existing = Array.isArray(props.className) ? (props.className as string[]) : [];
+      props.className = [...existing, 'cairn-broken-media'];
+      props.title = 'Missing media asset';
+    });
+  };
+}

package/src/lib/render/sanitize-schema.ts

@@ -13,8 +13,10 @@ const FIXED_MARKERS = ['dataPrimitive', 'dataSlot', 'dataRole', 'dataRise'];
  * then adds exactly what cairn's render needs. The directive markers (the fixed ones plus the
  * dataAttr<Key> markers derived from the registry) survive so the dispatch reads its stamps after
  * the floor. The benign author tags real content uses (nav, details, summary) and class/target/rel
- * on anchors are admitted. A site extends the result through `extend`, always starting from this
- * safe base, so it can add to the allowlist but not weaken the core strip.
+ * on anchors are admitted. figure/figcaption join the base so the engine's placed figure survives
+ * the floor on every site, including one that supplies its own `sanitizeSchema` extension. A site
+ * extends the result through `extend`, always starting from this safe base, so it can add to the
+ * allowlist but not weaken the core strip.
  */
 export function buildSanitizeSchema(
   registry: ComponentRegistry,
@@ -36,7 +38,7 @@ export function buildSanitizeSchema(
   const protocols = defaultSchema.protocols ?? {};
   const schema: Schema = {
     ...defaultSchema,
-    tagNames: [...(defaultSchema.tagNames ?? []), 'nav', 'details', 'summary'],
+    tagNames: [...(defaultSchema.tagNames ?? []), 'nav', 'details', 'summary', 'figure', 'figcaption'],
     attributes: {
       ...attributes,
       '*': [...(attributes['*'] ?? []), 'className', ...markers],

package/src/lib/sveltekit/admin-dispatch.ts

@@ -15,7 +15,8 @@ export type AdminView =
   | { view: 'list'; concept: ConceptDescriptor }
   | { view: 'edit'; concept: ConceptDescriptor; id: string }
   | { view: 'editors' }
-  | { view: 'nav' };
+  | { view: 'nav' }
+  | { view: 'media' };
 
 /**
  * Fixed first segments that never resolve as concepts. The engine only allows posts and pages
@@ -57,6 +58,10 @@ export function parseAdminPath(
     if (head === 'login') return { view: 'login' };
     if (head === 'editors') return { view: 'editors' };
     if (head === 'nav') return { view: 'nav' };
+    // media is its own view, a peer of editors and nav, so it is decided here, not added to the
+    // reserved-no-view set. /admin/media/<anything> 404s naturally (media is not a configured
+    // concept), which is the correct shape.
+    if (head === 'media') return { view: 'media' };
     if (RESERVED_SEGMENTS.has(head)) return null;
     const concept = findConcept(concepts, head);
     return concept ? { view: 'list', concept } : null;

package/src/lib/sveltekit/cairn-admin.ts

@@ -14,6 +14,7 @@ import {
   type LayoutData,
   type ListData,
   type EditData,
+  type MediaLibraryData,
 } from './content-routes.js';
 import { createEditorRoutes } from './editors-routes.js';
 import { createNavRoutes, type NavLoadData } from './nav-routes.js';
@@ -53,7 +54,8 @@ export type AdminData =
   | { view: 'list'; layout: LayoutData; page: ListData }
   | { view: 'edit'; layout: LayoutData; page: EditData }
   | { view: 'editors'; layout: LayoutData; page: { editors: Editor[]; self: string } }
-  | { view: 'nav'; layout: LayoutData; page: NavLoadData };
+  | { view: 'nav'; layout: LayoutData; page: NavLoadData }
+  | { view: 'media'; layout: LayoutData; page: MediaLibraryData };
 
 export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {}) {
   // The runtime already composes the site name and the sender identity, so the magic-link
@@ -122,6 +124,11 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
         const [layout, page] = await Promise.all([content.layoutLoad(delegated), nav.navLoad(delegated)]);
         return { view: 'nav', layout, page };
       }
+      case 'media': {
+        const delegated = contentEvent(event, {});
+        const [layout, page] = await Promise.all([content.layoutLoad(delegated), content.mediaLibraryLoad(delegated)]);
+        return { view: 'media', layout, page };
+      }
     }
   }
 
@@ -141,9 +148,9 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
   }
 
   // The topbar posts publishAll from every authed admin page; login and confirm may not.
-  const authedViews = ['list', 'edit', 'editors', 'nav'] as const;
+  const authedViews = ['list', 'edit', 'editors', 'nav', 'media'] as const;
   // An editor signs out from wherever they are, so logout accepts any parsed view.
-  const anyView = ['index', 'login', 'confirm', 'list', 'edit', 'editors', 'nav'] as const;
+  const anyView = ['index', 'login', 'confirm', 'list', 'edit', 'editors', 'nav', 'media'] as const;
 
   /** The full admin action vocabulary, one named async function per action, so a site's
    *  catch-all route exports `admin.actions` directly. Each wrapper stays thin: parse,
@@ -159,6 +166,7 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
       if (!nav) throw error(404, 'Not found');
       return nav.navSave(contentEvent(event, {}));
     }),
+    upload: viewAction(['edit'], (event, view) => content.uploadAction(contentEvent(event, { concept: view.concept.id, id: view.id }))),
     publish: viewAction(['edit'], (event, view) => content.publishAction(contentEvent(event, { concept: view.concept.id, id: view.id }))),
     discard: viewAction(['edit'], (event, view) => content.discardAction(contentEvent(event, { concept: view.concept.id, id: view.id }))),
     rename: viewAction(['edit'], (event, view) => content.renameAction(contentEvent(event, { concept: view.concept.id, id: view.id }))),
@@ -167,6 +175,8 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
         ? content.deleteAction(contentEvent(event, { concept: view.concept.id, id: view.id }))
         : content.listDeleteAction(contentEvent(event, { concept: view.concept.id })),
     ),
+    mediaDelete: viewAction(['media'], (event) => content.mediaDeleteAction(contentEvent(event, {}))),
+    mediaUpdate: viewAction(['media'], (event) => content.mediaUpdateAction(contentEvent(event, {}))),
     publishAll: viewAction(authedViews, (event) => content.publishAllAction(contentEvent(event, {}))),
     addEditor: viewAction(['editors'], (event) => editors.addEditorAction(event)),
     removeEditor: viewAction(['editors'], (event) => editors.removeEditorAction(event)),