@glw907/cairn-cms 0.56.2 → 0.57.0

package/dist/render/pipeline.d.ts

@@ -1,5 +1,6 @@
 import { type PluggableList } from 'unified';
 import type { Schema } from 'hast-util-sanitize';
+import { type MediaResolve } from './resolve-media.js';
 import { type ComponentRegistry } from './registry.js';
 import type { LinkResolve } from '../content/links.js';
 export interface RendererOptions {
@@ -29,5 +30,6 @@ export declare function createRenderer(registry?: ComponentRegistry, options?: R
     rehypePlugins: PluggableList;
     renderMarkdown: (content: string, opts?: {
         resolve?: LinkResolve;
+        resolveMedia?: MediaResolve;
     }) => Promise<string>;
 };

package/dist/render/pipeline.js

@@ -10,14 +10,22 @@ import rehypeSanitize from 'rehype-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 } from './resolve-media.js';
 import { rehypeDispatch } from './rehype-dispatch.js';
 import { defineRegistry } from './registry.js';
 /** Compose a site's render pipeline from its component registry: directive syntax to
  *  stamped markers to registry-built hast. Returns `renderMarkdown` plus the remark/
  *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
 export function createRenderer(registry = defineRegistry({ components: [] }), options = {}) {
-    const remarkPlugins = [remarkDirective, [remarkDirectiveStamp, registry], remarkResolveCairnLinks];
+    const remarkPlugins = [
+        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.
@@ -48,7 +56,10 @@ export function createRenderer(registry = defineRegistry({ components: [] }), op
         remarkPlugins,
         rehypePlugins,
         renderMarkdown: async (content, opts = {}) => {
-            const file = new VFile({ value: content, data: { [CAIRN_RESOLVE]: opts.resolve } });
+            const file = new VFile({
+                value: content,
+                data: { [CAIRN_RESOLVE]: opts.resolve, [MEDIA_RESOLVE]: opts.resolveMedia },
+            });
             return String(await processor.process(file));
         },
     };

package/dist/render/registry.js

@@ -16,6 +16,9 @@ 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');
+        }
         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/render/remark-figure.d.ts

@@ -0,0 +1,4 @@
+import type { Root } from 'mdast';
+/** Rewrite the reserved `figure` container directive into a placed <figure>. Every other directive
+ *  is left to remarkDirectiveStamp, which already skips unregistered names. */
+export declare function remarkFigure(): (tree: Root) => void;

package/dist/render/remark-figure.js

@@ -0,0 +1,103 @@
+import { visit } from 'unist-util-visit';
+import { parseMediaToken } from '../media/reference.js';
+/** The closed placement role set. A class outside this set is ignored, never passed through. */
+const ROLES = new Set(['center', 'wide', 'full']);
+function setData(node, patch) {
+    const data = (node.data ?? (node.data = {}));
+    Object.assign(data, patch);
+}
+// A node whose subtree carries non-whitespace text is a caption candidate.
+function hasText(node) {
+    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) {
+    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) {
+    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) => {
+        visit(tree, 'containerDirective', (node) => {
+            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];
+            // The image lifts into block position (the unwrap), so it carries the FigureChild slot type.
+            const imageChild = image;
+            // Unwrap the image to a direct child of the directive, handling both paragraph forms.
+            let captionNode;
+            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 = [imageChild];
+                if (rest.length > 0) {
+                    const captionParagraph = { 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/dist/render/resolve-media.d.ts

@@ -0,0 +1,34 @@
+import type { VFile } from 'vfile';
+import { type MediaRef } from '../media/reference.js';
+import { type MediaManifest } from '../media/manifest.js';
+import type { ResolvedAssetConfig } from '../media/config.js';
+/** The VFile data key the renderer sets the per-call media resolver under. */
+export declare 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 declare function makeMediaResolver(manifest: MediaManifest, resolved: ResolvedAssetConfig, opts?: {
+    preset?: string;
+}): MediaResolve;
+/** 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 declare function manifestMediaResolver(targets: Record<string, {
+    slug: string;
+    ext: string;
+    contentType: string;
+}>): MediaResolve;
+/** 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 declare function remarkResolveMedia(): (tree: unknown, file: VFile) => void;

package/dist/render/resolve-media.js

@@ -0,0 +1,78 @@
+// 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 { parseMediaToken } from '../media/reference.js';
+import { findByHash } from '../media/manifest.js';
+import { publicPath } from '../media/naming.js';
+import { presetUrl } from '../media/transform-url.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';
+/** 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, resolved, opts) {
+    return (ref) => {
+        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) {
+    return (ref) => {
+        const entry = targets[ref.hash];
+        if (!entry)
+            return undefined;
+        return publicPath(entry.slug, ref.hash, entry.ext, 'slug');
+    };
+}
+/** 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, file) => {
+        const resolve = file.data[MEDIA_RESOLVE];
+        if (!resolve)
+            return;
+        visit(tree, 'image', (node) => {
+            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 : [];
+            props.className = [...existing, 'cairn-broken-media'];
+            props.title = 'Missing media asset';
+        });
+    };
+}

package/dist/render/sanitize-schema.d.ts

@@ -7,8 +7,10 @@ import { type ComponentRegistry } from './registry.js';
  * 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 declare function buildSanitizeSchema(registry: ComponentRegistry, extend?: (defaults: Schema) => Schema): Schema;
 /**

package/dist/render/sanitize-schema.js

@@ -10,8 +10,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, extend) {
     const attrMarkers = registry.defs.flatMap((d) => (d.attributes ?? []).map((a) => dataAttrProp(a.key)));
@@ -28,7 +30,7 @@ export function buildSanitizeSchema(registry, extend) {
     const protocols = defaultSchema.protocols ?? {};
     const schema = {
         ...defaultSchema,
-        tagNames: [...(defaultSchema.tagNames ?? []), 'nav', 'details', 'summary'],
+        tagNames: [...(defaultSchema.tagNames ?? []), 'nav', 'details', 'summary', 'figure', 'figcaption'],
         attributes: {
             ...attributes,
             '*': [...(attributes['*'] ?? []), 'className', ...markers],

package/dist/sveltekit/admin-dispatch.d.ts

@@ -17,6 +17,8 @@ export type AdminView = {
     view: 'editors';
 } | {
     view: 'nav';
+} | {
+    view: 'media';
 };
 /**
  * Parse a raw `URL.pathname` (the caller passes `event.url.pathname`, never a SvelteKit rest

package/dist/sveltekit/admin-dispatch.js

@@ -42,6 +42,11 @@ export function parseAdminPath(pathname, concepts) {
             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);

package/dist/sveltekit/cairn-admin.d.ts

@@ -1,4 +1,4 @@
-import { type ContentRoutesDeps, type LayoutData, type ListData, type EditData } from './content-routes.js';
+import { type ContentRoutesDeps, type LayoutData, type ListData, type EditData, type MediaLibraryData } from './content-routes.js';
 import { type NavLoadData } from './nav-routes.js';
 import type { AuthBranding, SendMagicLink } from '../email.js';
 import type { AuthEnv, Editor } from '../auth/types.js';
@@ -61,6 +61,10 @@ export type AdminData = {
     view: 'nav';
     layout: LayoutData;
     page: NavLoadData;
+} | {
+    view: 'media';
+    layout: LayoutData;
+    page: MediaLibraryData;
 };
 export declare function createCairnAdmin(runtime: CairnRuntime, deps?: CairnAdminDeps): {
     load: (event: AdminEvent) => Promise<AdminData>;
@@ -70,10 +74,13 @@ export declare function createCairnAdmin(runtime: CairnRuntime, deps?: CairnAdmi
         logout: (event: AdminEvent) => Promise<never>;
         create: (event: AdminEvent) => Promise<never>;
         save: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
+        upload: (event: AdminEvent) => Promise<import("./content-routes.js").UploadResult | import("@sveltejs/kit").ActionFailure<unknown>>;
         publish: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
         discard: (event: AdminEvent) => Promise<never>;
         rename: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
         delete: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaDelete: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaUpdate: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
         publishAll: (event: AdminEvent) => Promise<never>;
         addEditor: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<{
             error: string;

package/dist/sveltekit/cairn-admin.js

@@ -77,6 +77,11 @@ export function createCairnAdmin(runtime, deps = {}) {
                 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 };
+            }
         }
     }
     /** Wrap a delegate in the parse-and-check every action shares: parse the pathname exactly
@@ -92,9 +97,9 @@ export function createCairnAdmin(runtime, deps = {}) {
         };
     }
     // The topbar posts publishAll from every authed admin page; login and confirm may not.
-    const authedViews = ['list', 'edit', 'editors', 'nav'];
+    const authedViews = ['list', 'edit', 'editors', 'nav', 'media'];
     // An editor signs out from wherever they are, so logout accepts any parsed view.
-    const anyView = ['index', 'login', 'confirm', 'list', 'edit', 'editors', 'nav'];
+    const anyView = ['index', 'login', 'confirm', 'list', 'edit', 'editors', 'nav', 'media'];
     /** 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,
      *  validate the view, synthesize the params the wrapped action reads, delegate. The
@@ -111,12 +116,15 @@ export function createCairnAdmin(runtime, deps = {}) {
                 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 }))),
         delete: viewAction(['edit', 'list'], (event, view) => view.view === 'edit'
             ? 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)),

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

@@ -1,6 +1,9 @@
 import { fail } from '@sveltejs/kit';
 import { type GithubKeyEnv } from '../github/credentials.js';
 import { type LinkTarget, type InboundLink } from '../content/manifest.js';
+import type { MediaEntry } from '../media/manifest.js';
+import type { MediaLibrary, MediaLibraryEntry } from '../media/library-entry.js';
+import type { UsageEntry } from '../media/usage.js';
 import type { CookieJar, EventBase } from './types.js';
 import type { CairnRuntime, FrontmatterField, ResolvedPreview } from '../content/types.js';
 import type { Role } from '../auth/types.js';
@@ -83,6 +86,18 @@ export interface EditData {
     slug: string;
     /** The site's link targets, for the preview resolver and the link picker; from the committed manifest. */
     linkTargets: LinkTarget[];
+    /** The minimal media-resolver input the edit page builds its preview `resolveMedia` from, keyed by
+     *  the 16-hex content hash and parallel to `linkTargets`. Empty when media is off or the read fails. */
+    mediaTargets: Record<string, {
+        slug: string;
+        ext: string;
+        contentType: string;
+    }>;
+    /** The picker's human layer for each stored asset, keyed by the 16-hex content hash and projected
+     *  from the same committed media manifest read that populates `mediaTargets`. The `hash` field
+     *  duplicates the key, so the picker can iterate `Object.values`. Empty when media is off or the
+     *  read fails (the same degradation path as `mediaTargets`). */
+    mediaLibrary: MediaLibrary;
     /** The entries that link to this one, for the delete guard. Empty when nothing links here. */
     inboundLinks: InboundLink[];
     /** True when the entry has a pending branch, so the body above came from that branch. */
@@ -98,6 +113,23 @@ export interface EditData {
      *  leaves the frame rendering unstyled markup behind a hint. */
     preview: ResolvedPreview | null;
 }
+/** One asset's where-used overlay, kept separate from MediaLibraryEntry so the picker's shared
+ *  projection stays decoupled from the Library-only usage facts. */
+export interface MediaUsageInfo {
+    /** Distinct content entries that reference the asset (count by distinct concept+id). */
+    count: number;
+    /** Every where-used row (published and edit-branch origins), for the detail's grouped list. */
+    entries: UsageEntry[];
+}
+/** The Media Library screen's data: the unioned assets, the per-hash usage overlay, and the
+ *  degraded-load error. The usage overlay is keyed by content hash; an asset with no references
+ *  simply has no key, which the screen renders as "no references found". */
+export interface MediaLibraryData {
+    assets: MediaLibraryEntry[];
+    /** Per-hash usage overlay, kept separate from MediaLibraryEntry so the popover stays decoupled. */
+    usage: Record<string, MediaUsageInfo>;
+    error: string | null;
+}
 /** The structural event the content routes read; a real SvelteKit RequestEvent satisfies it. */
 export interface ContentEvent extends EventBase<GithubKeyEnv> {
     params: Record<string, string>;
@@ -134,14 +166,45 @@ export interface RenameFailure {
     /** The one-line human summary every content action failure carries. */
     error: string;
 }
+/** A refused media delete: `fail(404)` for an asset not committed on the default branch, or
+ *  `fail(409)` when a fresh usage read finds the asset still in use and the typed-slug override
+ *  was not given. `fail(503)` covers media-off or a missing bucket binding. */
+export interface MediaDeleteRefusal {
+    /** The one-line human summary every action failure carries. */
+    error: string;
+    /** The refused asset's content hash, so the dialog marks the right asset. */
+    hash: string;
+    /** The where-used rows (published first, then by branch) the in-use face lists; empty otherwise. */
+    usage: UsageEntry[];
+    /** The distinct-entry count behind the refusal; zero when the asset is uncommitted. */
+    foundIn: number;
+}
+/** A refused media metadata edit: `fail(404)` for an asset not committed on the default branch, or
+ *  `fail(400)` for an invalid slug. */
+export interface MediaUpdateFailure {
+    /** The one-line human summary every action failure carries. */
+    error: string;
+}
 /** What a route's single `form` export presents to a view component: whichever content action
  *  last failed, merged with every field optional. `error` is always set on a failure; the richer
- *  keys identify which guard refused. */
-export type ContentFormFailure = Partial<SaveFailure & DeleteRefusal & RenameFailure>;
+ *  keys identify which guard refused. The media refusals ride here too, so the Media Library's one
+ *  `form` prop carries a `?/mediaDelete` or `?/mediaUpdate` refusal without a second type. */
+export type ContentFormFailure = Partial<SaveFailure & DeleteRefusal & RenameFailure & MediaDeleteRefusal & MediaUpdateFailure>;
+/** The successful upload's response (`uploadAction`). The server-owned `record` rides the editor's
+ *  optimistic client state and commits with the entry at Save (the upload itself commits nothing).
+ *  `reused` is true when identical bytes were already stored, so the second upload did no second put;
+ *  `mismatch` flags an existing object whose stored content type differs from this sniff. */
+export interface UploadResult {
+    reference: string;
+    record: MediaEntry;
+    reused: boolean;
+    mismatch: boolean;
+}
 export declare function createContentRoutes(runtime: CairnRuntime, deps?: ContentRoutesDeps): {
     layoutLoad: (event: ContentEvent) => Promise<LayoutData>;
     indexRedirect: () => never;
     listLoad: (event: ContentEvent) => Promise<ListData>;
+    mediaLibraryLoad: (event: ContentEvent) => Promise<MediaLibraryData>;
     createAction: (event: ContentEvent) => Promise<never>;
     editLoad: (event: ContentEvent) => Promise<EditData>;
     saveAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
@@ -151,5 +214,8 @@ export declare function createContentRoutes(runtime: CairnRuntime, deps?: Conten
     deleteAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
     listDeleteAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
     renameAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
+    uploadAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | UploadResult>;
+    mediaDeleteAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
+    mediaUpdateAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
     mintToken: (env: GithubKeyEnv) => string | Promise<string>;
 };