@glw907/cairn-cms 0.56.2 → 0.57.1

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

@@ -127,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: 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/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)),