@glw907/cairn-cms 0.56.2 → 0.57.0

package/dist/components/client-ingest.d.ts

@@ -0,0 +1,142 @@
+/**
+ * True when the leading bytes are a HEIC/HEIF `ftyp` box (the sniff returns `image/heic`). Driven by
+ * the magic bytes alone, never the filename extension or the browser-supplied MIME, since both lie on
+ * an iPhone share-sheet drop.
+ */
+export declare function detectHeic(bytes: Uint8Array): boolean;
+/**
+ * Read a GIF's pixel dimensions from its logical-screen-descriptor header (the 16-bit little-endian
+ * width and height at bytes 6..9), or null when the input is not a `GIF8` file or is too short to hold
+ * the descriptor. GIF passes through ingest untouched (never a canvas), so the animation survives, and
+ * its dimensions come from this header rather than a decode.
+ */
+export declare function gifDimensions(bytes: Uint8Array): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * The slug-versus-proposed-name split. A real, specific filename stem yields a proposed display name
+ * (the stem, extension dropped) that the capture card pre-fills and tags Suggested. A generic
+ * machine-assigned stem (`IMG_1234`, `DSC_0001`, `image`, `photo`, `untitled`, a bare number, a HEIC
+ * counter, a screenshot pattern) yields null, and the card leaves the name field empty and required
+ * with no Suggested tag, since pre-filling `IMG_4821` would only train the author to accept noise.
+ */
+export declare function proposedNameFor(filename: string): string | null;
+/**
+ * The image files in a drag-and-drop payload, in order, dropping every non-image. Filters by
+ * `type.startsWith('image/')`, so a `text/uri-list` or `text/html` item dragged in from a browser tab
+ * is ignored (those arrive as `items`, never as image `files`). Testable with a plain object mock, so
+ * it never requires a real `DataTransfer`.
+ */
+export declare function normalizeDataTransfer(dt: {
+    files?: ArrayLike<File>;
+    items?: ArrayLike<DataTransferItem>;
+}): File[];
+/**
+ * The paste/drop routing decision as a pure call: the first image File a DataTransfer-shaped object
+ * carries, or null when it carries none. The editor's paste and drop handlers route on this, handing
+ * the file to ingest when it is non-null and falling through to CodeMirror's default when it is null
+ * (a plain-text or markdown paste). 2b is single-file per gesture (open risk 3), so this returns one
+ * file, never the rest. A thin wrapper over normalizeDataTransfer, kept pure so the decision is unit
+ * tested without a real DataTransfer.
+ */
+export declare function firstImageFile(dt: {
+    files?: ArrayLike<File>;
+    items?: ArrayLike<DataTransferItem>;
+}): File | null;
+/** The conservative canvas area budget, about 16.7M px (4096 x 4096). A source over this is scaled
+ *  down before any `drawImage`, never clipped. */
+export declare const MAX_AREA = 16777216;
+/** The conservative short-side budget. A source whose smaller dimension exceeds this is scaled down so
+ *  the short side lands at the cap, even when its area is within MAX_AREA. */
+export declare const MAX_SHORT_SIDE = 4096;
+/**
+ * The canvas budget for a source of the given dimensions. When the source area exceeds MAX_AREA or its
+ * short side exceeds MAX_SHORT_SIDE, scale the whole image down proportionally so both bounds hold
+ * (aspect ratio preserved, never clipped, never upscaled); otherwise return the input unchanged. Pure
+ * math, so the budget is testable without a canvas.
+ */
+export declare function budgetForDimensions(width: number, height: number): {
+    width: number;
+    height: number;
+};
+/** The ingest failure taxonomy. `decode-unsupported` is a format the browser and the HEIC decoder both
+ *  refuse; `transcode-failed` is a HEIC decode or a canvas re-encode that threw; `too-large` is a
+ *  source still over budget after a transcode; `network` is the upload fetch rejecting. */
+export type IngestFailureKind = 'decode-unsupported' | 'transcode-failed' | 'too-large' | 'network';
+/** A failed ingest card: a stable discriminant plus a human message the capture card renders. */
+export interface IngestFailureCard {
+    status: 'failed';
+    kind: IngestFailureKind;
+    message: string;
+}
+/** A pending ingest card, shown while the bytes are decoded, transcoded, and uploaded. */
+export interface IngestPendingCard {
+    status: 'pending';
+}
+/** A ready ingest card: the upload succeeded and the server returned a reference. */
+export interface IngestReadyCard {
+    status: 'ready';
+    reference: string;
+    width: number | null;
+    height: number | null;
+}
+/** The card states the capture UI moves through for a single ingested file. */
+export type IngestCard = IngestPendingCard | IngestReadyCard | IngestFailureCard;
+/** Map a failure kind to its typed card state. */
+export declare function failureCard(kind: IngestFailureKind): IngestFailureCard;
+/** The fields the upload request carries, mirroring exactly what the Task 5 uploadAction reads back. */
+export interface UploadRequestOpts {
+    conceptId: string;
+    id: string;
+    bytes: Uint8Array | Blob;
+    contentType: string;
+    csrf: string;
+    filename: string;
+    alt?: string;
+    displayName?: string;
+    width?: number | null;
+    height?: number | null;
+}
+/**
+ * Construct the upload request the helper will `fetch`: a `POST` to the named SvelteKit form action
+ * `/admin/<conceptId>/<id>?/upload`, the raw bytes as the body, `redirect: 'manual'` so the guard's
+ * expired-session 303 surfaces as an opaque, status-0 response (which the caller detects by
+ * `response.type === 'opaqueredirect'`) instead of being silently followed, and the `X-Cairn-*`
+ * headers the
+ * uploadAction reads. The filename, alt, and display name are percent-encoded so a unicode value
+ * survives header transport; width and height ride only when present. Pure: it returns the request
+ * shape and never calls `fetch`, so a test can assert the URL, method, and headers.
+ */
+export declare function buildUploadRequest(opts: UploadRequestOpts): {
+    url: string;
+    init: RequestInit;
+};
+/** A decoded source plus its dimensions, the input to the upload step. */
+interface IngestResult {
+    blob: Blob;
+    contentType: string;
+    width: number | null;
+    height: number | null;
+}
+/**
+ * The three-tier ingest route for one file. Web-native types (JPEG, PNG, WebP) pass through with
+ * dimensions from `createImageBitmap`; GIF passes through with dimensions from `gifDimensions` (no
+ * canvas, so the animation survives); HEIC routes through the lazy-loaded heic-to decoder, is decoded
+ * to a PNG, then re-encoded to WebP through the canvas budget. Any forced re-encode targets WebP. This
+ * is thin glue over the pure helpers above and is proven live, not in this suite.
+ */
+export declare function ingestFile(file: File): Promise<IngestResult>;
+/** The failure kind for a thrown ingest error, defaulting an unknown throw to a decode failure. */
+export declare function ingestFailureKind(error: unknown): IngestFailureKind;
+/**
+ * Send a built upload request and return its raw `Response`, mapping a fetch rejection (the network
+ * down, the request aborted) to a `network` IngestError. The caller reads the SvelteKit action result
+ * from the response; this thin wrapper exists only so the tests can build a request without invoking
+ * `fetch`.
+ */
+export declare function sendUpload(url: string, init: RequestInit): Promise<Response>;
+/** Guard a drop target: cancel the browser's default open-the-file behavior on `dragover` and `drop`
+ *  so a dropped image stays inside the editor rather than navigating the page to the file. */
+export declare function guardDropTarget(event: DragEvent): void;
+export {};

package/dist/components/client-ingest.js

@@ -0,0 +1,297 @@
+// cairn-cms: the client-side ingest helper. Browser-only, behind the editor seam: the orchestration
+// touches createImageBitmap, a <canvas>, and a lazy-loaded heic-to WASM decoder, so this module lives
+// beside the other dynamically-imported editor modules (editor-folding, editor-highlight, editor-modes)
+// and is never re-exported from a node-safe subpath. The heic-to import is dynamic, so its WASM only
+// downloads when an author actually drops a HEIC; the static imports here are the pure node-safe
+// sniff/slug helpers, which keep this module loadable in a unit test.
+//
+// The split: the pure parts (HEIC magic detection, GIF header parse, the slug-versus-proposed-name
+// call, the DataTransfer normalizer, the canvas budget, the failure taxonomy, the upload request
+// shape) are exported and unit-tested. The browser-coupled orchestration (ingestFile, the drop guard)
+// is thin glue over them, wired here but proven live at Phase 2b and on a site, not in this suite.
+//
+// The client is untrusted. The server re-derives the type, the slug, the hash, and the size on every
+// upload (the Task 5 uploadAction), so this helper exists for UX (a correct preview, no dead wait),
+// never for security.
+import { sniffMediaType } from '../media/sniff.js';
+// ---------------------------------------------------------------------------
+// Pure exports (unit-tested below the seam)
+// ---------------------------------------------------------------------------
+/**
+ * True when the leading bytes are a HEIC/HEIF `ftyp` box (the sniff returns `image/heic`). Driven by
+ * the magic bytes alone, never the filename extension or the browser-supplied MIME, since both lie on
+ * an iPhone share-sheet drop.
+ */
+export function detectHeic(bytes) {
+    return sniffMediaType(bytes) === 'image/heic';
+}
+/**
+ * Read a GIF's pixel dimensions from its logical-screen-descriptor header (the 16-bit little-endian
+ * width and height at bytes 6..9), or null when the input is not a `GIF8` file or is too short to hold
+ * the descriptor. GIF passes through ingest untouched (never a canvas), so the animation survives, and
+ * its dimensions come from this header rather than a decode.
+ */
+export function gifDimensions(bytes) {
+    // 'GIF8' is the shared prefix of the 87a and 89a versions; the descriptor needs at least 10 bytes.
+    if (bytes.length < 10)
+        return null;
+    if (bytes[0] !== 0x47 || bytes[1] !== 0x49 || bytes[2] !== 0x46 || bytes[3] !== 0x38)
+        return null;
+    const width = bytes[6] | (bytes[7] << 8);
+    const height = bytes[8] | (bytes[9] << 8);
+    return { width, height };
+}
+/** A bare run of digits, the camera-counter stem of `1234.png` and friends. */
+const BARE_NUMBER = /^\d+$/;
+/** The fixed generic stems a phone or OS hands a file: the capture card treats these as no name. */
+const GENERIC_STEMS = new Set(['image', 'photo', 'untitled', 'unnamed', 'download']);
+/**
+ * The camera and OS counter patterns. `IMG_1234`, `DSC_0001`, `DSCN0001`, `P1010001`, the iPhone
+ * `IMG_E1234` edited form, a `Screenshot ...` stem, and a Windows/Android `Screenshot_...` stem are all
+ * machine-assigned and carry no authorial meaning, so they yield no proposed name.
+ */
+const GENERIC_PATTERNS = [
+    /^img[_-]?e?\d+$/i,
+    /^dsc[fn]?[_-]?\d+$/i,
+    /^p\d{7}$/i,
+    /^screenshot[ _-]/i,
+    /^screen shot /i,
+];
+/**
+ * The slug-versus-proposed-name split. A real, specific filename stem yields a proposed display name
+ * (the stem, extension dropped) that the capture card pre-fills and tags Suggested. A generic
+ * machine-assigned stem (`IMG_1234`, `DSC_0001`, `image`, `photo`, `untitled`, a bare number, a HEIC
+ * counter, a screenshot pattern) yields null, and the card leaves the name field empty and required
+ * with no Suggested tag, since pre-filling `IMG_4821` would only train the author to accept noise.
+ */
+export function proposedNameFor(filename) {
+    const dot = filename.lastIndexOf('.');
+    const stem = (dot === -1 ? filename : filename.slice(0, dot)).trim();
+    if (stem === '')
+        return null;
+    const lower = stem.toLowerCase();
+    if (GENERIC_STEMS.has(lower))
+        return null;
+    if (BARE_NUMBER.test(stem))
+        return null;
+    for (const pattern of GENERIC_PATTERNS) {
+        if (pattern.test(stem))
+            return null;
+    }
+    return stem;
+}
+/**
+ * The image files in a drag-and-drop payload, in order, dropping every non-image. Filters by
+ * `type.startsWith('image/')`, so a `text/uri-list` or `text/html` item dragged in from a browser tab
+ * is ignored (those arrive as `items`, never as image `files`). Testable with a plain object mock, so
+ * it never requires a real `DataTransfer`.
+ */
+export function normalizeDataTransfer(dt) {
+    const files = dt.files;
+    if (!files)
+        return [];
+    const out = [];
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i];
+        if (file && typeof file.type === 'string' && file.type.startsWith('image/'))
+            out.push(file);
+    }
+    return out;
+}
+/**
+ * The paste/drop routing decision as a pure call: the first image File a DataTransfer-shaped object
+ * carries, or null when it carries none. The editor's paste and drop handlers route on this, handing
+ * the file to ingest when it is non-null and falling through to CodeMirror's default when it is null
+ * (a plain-text or markdown paste). 2b is single-file per gesture (open risk 3), so this returns one
+ * file, never the rest. A thin wrapper over normalizeDataTransfer, kept pure so the decision is unit
+ * tested without a real DataTransfer.
+ */
+export function firstImageFile(dt) {
+    return normalizeDataTransfer(dt)[0] ?? null;
+}
+/** The conservative canvas area budget, about 16.7M px (4096 x 4096). A source over this is scaled
+ *  down before any `drawImage`, never clipped. */
+export const MAX_AREA = 16_777_216;
+/** The conservative short-side budget. A source whose smaller dimension exceeds this is scaled down so
+ *  the short side lands at the cap, even when its area is within MAX_AREA. */
+export const MAX_SHORT_SIDE = 4096;
+/**
+ * The canvas budget for a source of the given dimensions. When the source area exceeds MAX_AREA or its
+ * short side exceeds MAX_SHORT_SIDE, scale the whole image down proportionally so both bounds hold
+ * (aspect ratio preserved, never clipped, never upscaled); otherwise return the input unchanged. Pure
+ * math, so the budget is testable without a canvas.
+ */
+export function budgetForDimensions(width, height) {
+    const area = width * height;
+    const shortSide = Math.min(width, height);
+    if (area <= MAX_AREA && shortSide <= MAX_SHORT_SIDE)
+        return { width, height };
+    // One scale factor satisfies both bounds: the smaller of the area-fit and short-side-fit factors,
+    // capped at 1 so an already-small dimension is never upscaled.
+    const areaScale = Math.sqrt(MAX_AREA / area);
+    const shortScale = MAX_SHORT_SIDE / shortSide;
+    const scale = Math.min(areaScale, shortScale, 1);
+    return {
+        width: Math.max(1, Math.floor(width * scale)),
+        height: Math.max(1, Math.floor(height * scale)),
+    };
+}
+/** The human message per failure kind, plain and specific so an author knows whether to retry. */
+const FAILURE_MESSAGE = {
+    'decode-unsupported': 'This image format is not supported. Try a JPEG, PNG, WebP, or GIF.',
+    'transcode-failed': 'This image could not be converted. Try exporting it as a JPEG first.',
+    'too-large': 'This image is too large to add, even after shrinking it.',
+    network: 'The upload could not reach the server. Check your connection and try again.',
+};
+/** Map a failure kind to its typed card state. */
+export function failureCard(kind) {
+    return { status: 'failed', kind, message: FAILURE_MESSAGE[kind] };
+}
+/**
+ * Construct the upload request the helper will `fetch`: a `POST` to the named SvelteKit form action
+ * `/admin/<conceptId>/<id>?/upload`, the raw bytes as the body, `redirect: 'manual'` so the guard's
+ * expired-session 303 surfaces as an opaque, status-0 response (which the caller detects by
+ * `response.type === 'opaqueredirect'`) instead of being silently followed, and the `X-Cairn-*`
+ * headers the
+ * uploadAction reads. The filename, alt, and display name are percent-encoded so a unicode value
+ * survives header transport; width and height ride only when present. Pure: it returns the request
+ * shape and never calls `fetch`, so a test can assert the URL, method, and headers.
+ */
+export function buildUploadRequest(opts) {
+    const url = `/admin/${opts.conceptId}/${opts.id}?/upload`;
+    // The body rides as text/plain, not the image's real type. The upload is a SvelteKit form action
+    // (?/upload), and SvelteKit 415s a POST whose content type is not form-encoded before the action
+    // runs; text/plain is the one form content type that carries raw bytes without field encoding. The
+    // server ignores this label and sniffs the real type from the bytes. The CSRF token rides the
+    // X-Cairn-CSRF header so the guard clears the request without cloning the body.
+    const headers = {
+        'X-Cairn-CSRF': opts.csrf,
+        'Content-Type': 'text/plain',
+        'X-Cairn-Filename': encodeURIComponent(opts.filename),
+    };
+    if (opts.alt !== undefined && opts.alt !== '')
+        headers['X-Cairn-Alt'] = encodeURIComponent(opts.alt);
+    if (opts.displayName !== undefined && opts.displayName !== '') {
+        headers['X-Cairn-Display-Name'] = encodeURIComponent(opts.displayName);
+    }
+    if (opts.width !== undefined && opts.width !== null)
+        headers['X-Cairn-Width'] = String(opts.width);
+    if (opts.height !== undefined && opts.height !== null)
+        headers['X-Cairn-Height'] = String(opts.height);
+    // BodyInit accepts a Blob or a BufferSource; a Uint8Array is a BufferSource. The cast keeps the
+    // public BodyInit type while letting either input through.
+    const init = {
+        method: 'POST',
+        redirect: 'manual',
+        headers,
+        body: opts.bytes,
+    };
+    return { url, init };
+}
+/** Thrown inside the orchestration so a kind maps cleanly to a failure card at the boundary. */
+class IngestError extends Error {
+    kind;
+    constructor(kind) {
+        super(kind);
+        this.kind = kind;
+    }
+}
+/**
+ * The three-tier ingest route for one file. Web-native types (JPEG, PNG, WebP) pass through with
+ * dimensions from `createImageBitmap`; GIF passes through with dimensions from `gifDimensions` (no
+ * canvas, so the animation survives); HEIC routes through the lazy-loaded heic-to decoder, is decoded
+ * to a PNG, then re-encoded to WebP through the canvas budget. Any forced re-encode targets WebP. This
+ * is thin glue over the pure helpers above and is proven live, not in this suite.
+ */
+export async function ingestFile(file) {
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    const sniffed = sniffMediaType(bytes);
+    if (sniffed === 'image/gif') {
+        // GIF passes through untouched: dimensions from the header, never a canvas.
+        const dims = gifDimensions(bytes);
+        return { blob: file, contentType: 'image/gif', width: dims?.width ?? null, height: dims?.height ?? null };
+    }
+    if (sniffed === 'image/jpeg' || sniffed === 'image/png' || sniffed === 'image/webp') {
+        // Web-native passthrough: read the real pixel dimensions with the embedded orientation applied.
+        let bitmap;
+        try {
+            bitmap = await createImageBitmap(file, { imageOrientation: 'from-image' });
+        }
+        catch {
+            throw new IngestError('decode-unsupported');
+        }
+        const out = { blob: file, contentType: sniffed, width: bitmap.width, height: bitmap.height };
+        bitmap.close();
+        return out;
+    }
+    if (detectHeic(bytes)) {
+        // HEIC: lazy-load the decoder so its WASM downloads only on a real HEIC drop. heicTo applies the
+        // HEIF orientation when it produces the PNG.
+        let png;
+        try {
+            const mod = (await import('heic-to'));
+            png = await mod.heicTo({ blob: file, type: 'image/png' });
+        }
+        catch {
+            throw new IngestError('transcode-failed');
+        }
+        return reencodeToWebp(png);
+    }
+    throw new IngestError('decode-unsupported');
+}
+/**
+ * Re-encode a decoded blob to WebP through the conservative canvas budget: read its dimensions, size a
+ * canvas to `budgetForDimensions` (scaling down, never clipping), draw the bitmap into it, and export
+ * WebP. A source still over budget after the transcode is a `too-large` failure rather than a clip.
+ */
+async function reencodeToWebp(source) {
+    let bitmap;
+    try {
+        bitmap = await createImageBitmap(source, { imageOrientation: 'from-image' });
+    }
+    catch {
+        throw new IngestError('transcode-failed');
+    }
+    const budget = budgetForDimensions(bitmap.width, bitmap.height);
+    if (budget.width * budget.height > MAX_AREA) {
+        bitmap.close();
+        throw new IngestError('too-large');
+    }
+    const canvas = document.createElement('canvas');
+    canvas.width = budget.width;
+    canvas.height = budget.height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        bitmap.close();
+        throw new IngestError('transcode-failed');
+    }
+    ctx.drawImage(bitmap, 0, 0, budget.width, budget.height);
+    bitmap.close();
+    const webp = await new Promise((resolve) => canvas.toBlob(resolve, 'image/webp'));
+    if (!webp)
+        throw new IngestError('transcode-failed');
+    return { blob: webp, contentType: 'image/webp', width: budget.width, height: budget.height };
+}
+/** The failure kind for a thrown ingest error, defaulting an unknown throw to a decode failure. */
+export function ingestFailureKind(error) {
+    return error instanceof IngestError ? error.kind : 'decode-unsupported';
+}
+/**
+ * Send a built upload request and return its raw `Response`, mapping a fetch rejection (the network
+ * down, the request aborted) to a `network` IngestError. The caller reads the SvelteKit action result
+ * from the response; this thin wrapper exists only so the tests can build a request without invoking
+ * `fetch`.
+ */
+export async function sendUpload(url, init) {
+    try {
+        return await fetch(url, init);
+    }
+    catch {
+        throw new IngestError('network');
+    }
+}
+/** Guard a drop target: cancel the browser's default open-the-file behavior on `dragover` and `drop`
+ *  so a dropped image stays inside the editor rather than navigating the page to the file. */
+export function guardDropTarget(event) {
+    event.preventDefault();
+}

package/dist/components/editor-media.d.ts

@@ -0,0 +1,11 @@
+import { type Extension } from '@codemirror/state';
+import type { MediaLibrary } from '../media/library-entry.js';
+/**
+ * The media: source decoration extension over a projected library. Each `![alt](media:slug.hash)`
+ * token in the source shows the asset's thumbnail and display name in place of the reference, the
+ * reference is atomic, and an empty alt carries a persistent needs-alt marker. The library is the
+ * `mediaLibrary` projection EditData carries; MarkdownEditor holds it in a compartment and rebuilds
+ * this extension when the library changes, so a just-uploaded image decorates once it is in the
+ * library. An empty library is valid: nothing decorates.
+ */
+export declare function cairnMediaDecorations(library: MediaLibrary): Extension;

package/dist/components/editor-media.js

@@ -0,0 +1,206 @@
+// The media: source decoration. Each `![alt](media:slug.hash)` token in the source has its URL part
+// (the media: reference inside the parens, never the alt) replaced by an inline chip showing the
+// asset's thumbnail and display name, with a persistent needs-alt marker when the alt is empty. The
+// reference token is also made atomic, so a stray keystroke selects or replaces the whole reference
+// rather than corrupting a hex digit.
+//
+// Client-only like editor-highlight, editor-modes, and editor-folding: MarkdownEditor reaches this
+// module through a dynamic import, so the static @codemirror imports here never enter a server bundle
+// (guarded by the editor-boundary test, whose DYNAMIC_ONLY list names this file).
+//
+// The library is reactive: MarkdownEditor feeds it in through a compartment reconfigured on a prop
+// change, so a just-uploaded image decorates the moment it lands in the library. The chip reads the
+// library for the thumbnail src, the display name, and the dimensions; a hash absent from the library
+// renders a neutral fallback chip named from the token slug rather than throwing.
+import { Decoration, EditorView, ViewPlugin, WidgetType, } from '@codemirror/view';
+import { RangeSetBuilder } from '@codemirror/state';
+import { parseMediaToken } from '../media/reference.js';
+import { publicPath } from '../media/naming.js';
+import { fenceScan, figureRoleAtLine } from './markdown-directives.js';
+// Markdown image tokens whose URL is a media: reference. The capture groups split the alt (group 1,
+// author content that stays editable) from the URL token (group 2, the media: reference that becomes
+// the atomic chip). The alt body excludes a closing bracket so a following `![...]` cannot run into
+// it; the URL body excludes whitespace and the closing paren. parseMediaToken does the real
+// validation, so a non-media or malformed URL is dropped after the match.
+const MEDIA_IMAGE = /!\[([^\]]*)\]\((media:[^\s)]+)\)/g;
+// The chip widget: an inline element carrying the thumbnail and the display name, with a needs-alt
+// marker (a glyph plus a label, never hue alone) when the alt is empty. A library miss renders a
+// neutral fallback chip named from the token slug. The widget never throws on a missing entry.
+class MediaChipWidget extends WidgetType {
+    match;
+    constructor(match) {
+        super();
+        this.match = match;
+    }
+    eq(other) {
+        if (!(other instanceof MediaChipWidget))
+            return false;
+        const a = this.match;
+        const b = other.match;
+        // The chip's appearance depends on the token, the alt-empty state, and the resolved entry's
+        // identity (its slug/ext/hash drive the thumbnail src and the name). Comparing those keeps the
+        // widget stable across a rebuild that did not change the chip.
+        return (a.token === b.token &&
+            a.alt === b.alt &&
+            a.figureRole === b.figureRole &&
+            a.entry?.slug === b.entry?.slug &&
+            a.entry?.ext === b.entry?.ext &&
+            a.entry?.displayName === b.entry?.displayName);
+    }
+    toDOM() {
+        const { entry, slug, hash, alt, figureRole } = this.match;
+        const chip = document.createElement('span');
+        chip.className = 'cm-cairn-media-chip';
+        chip.setAttribute('aria-hidden', 'true');
+        if (entry) {
+            const img = document.createElement('img');
+            img.className = 'cm-cairn-media-thumb';
+            img.src = publicPath(entry.slug, entry.hash, entry.ext, 'slug');
+            img.alt = '';
+            img.setAttribute('aria-hidden', 'true');
+            chip.appendChild(img);
+        }
+        const name = document.createElement('span');
+        name.className = 'cm-cairn-media-name';
+        // The display name from the library, or the token slug as a neutral fallback when the hash is
+        // unknown to this entry's library (an image referenced from a branch whose manifest the read
+        // missed); the bare hash stands in when even the slug is absent.
+        name.textContent = entry?.displayName || slug || hash;
+        chip.appendChild(name);
+        if (figureRole !== null) {
+            // The figure/role pill: the role name (or "figure" for the measure default), in the directive
+            // accent language. It is present only inside a :::figure, so the visible chip and the source
+            // agree (the no-hidden-state rule). aria-hidden like the rest of the chip; the source `{.wide}`
+            // carries the meaning for assistive tech.
+            const pill = document.createElement('span');
+            pill.className = 'cm-cairn-media-role';
+            pill.setAttribute('aria-hidden', 'true');
+            pill.textContent = figureRole;
+            chip.appendChild(pill);
+        }
+        if (alt.trim() === '') {
+            // The needs-alt marker: a glyph and a label, never hue alone (the spec accessibility rule). The
+            // title gives the same words on hover, and the chip's name span already conveys which image.
+            const flag = document.createElement('span');
+            flag.className = 'cm-cairn-media-needs-alt';
+            flag.title = 'This image has no alt text. Add a description for screen readers.';
+            // A small warning glyph ahead of the label, marked decorative so the label carries the meaning.
+            const glyph = document.createElement('span');
+            glyph.className = 'cm-cairn-media-needs-alt-glyph';
+            glyph.setAttribute('aria-hidden', 'true');
+            glyph.textContent = '⚠'; // warning sign
+            const label = document.createElement('span');
+            label.textContent = 'Needs alt';
+            flag.appendChild(glyph);
+            flag.appendChild(label);
+            chip.appendChild(flag);
+        }
+        return chip;
+    }
+    // The chip carries its own interactive intent only through the surrounding atomic range; clicks on
+    // it should fall through to CodeMirror so the caret lands beside the atomic token.
+    ignoreEvent() {
+        return false;
+    }
+}
+/** Scan one line's text for media image tokens, mapping each to its document offsets and resolving its
+ *  library entry. lineFrom is the line's document start, so the match offsets become absolute. */
+function matchesInLine(text, lineFrom, library) {
+    const out = [];
+    MEDIA_IMAGE.lastIndex = 0;
+    let m;
+    while ((m = MEDIA_IMAGE.exec(text)) !== null) {
+        const alt = m[1] ?? '';
+        const token = m[2] ?? '';
+        const ref = parseMediaToken(token);
+        if (!ref)
+            continue; // a media:-prefixed but malformed token is left as plain source
+        // The URL token sits between the '(' after the alt's ']' and the closing ')'. The match starts
+        // at the '!', and the token's offset within the match is the index of the '(' plus one.
+        const tokenStart = m.index + m[0].indexOf('(' + token + ')') + 1;
+        const from = lineFrom + tokenStart;
+        const to = from + token.length;
+        out.push({
+            alt,
+            from,
+            to,
+            token,
+            slug: ref.slug,
+            hash: ref.hash,
+            entry: library[ref.hash] ?? null,
+            figureRole: null,
+        });
+    }
+    return out;
+}
+/** Every media image match across the editor's visible ranges, in document order, each carrying its
+ *  enclosing figure role. One {@link fenceScan} over the whole document feeds the cheap per-token
+ *  figure detection (no remark parse on the per-rebuild chip path); the visible lines are scanned
+ *  for tokens, then each token's line index drives {@link figureRoleAtLine}. */
+function visibleMatches(view, library) {
+    const lines = view.state.doc.toString().split('\n');
+    const scan = fenceScan(lines);
+    const out = [];
+    for (const { from, to } of view.visibleRanges) {
+        for (let pos = from; pos <= to;) {
+            const line = view.state.doc.lineAt(pos);
+            const role = figureRoleAtLine(scan, lines, line.number - 1);
+            for (const match of matchesInLine(line.text, line.from, library)) {
+                out.push({ ...match, figureRole: role });
+            }
+            pos = line.to + 1;
+        }
+    }
+    return out;
+}
+/** Replace decorations for each visible media image's reference token: the chip widget over the URL
+ *  token, the alt left untouched. The same spans seed the atomic-range set. */
+function buildMediaDecorations(view, library) {
+    const builder = new RangeSetBuilder();
+    for (const match of visibleMatches(view, library)) {
+        builder.add(match.from, match.to, Decoration.replace({ widget: new MediaChipWidget(match) }));
+    }
+    return builder.finish();
+}
+/** The atomic ranges for the visible media reference tokens: a caret or selection edit treats each
+ *  token as one unit, so a stray keystroke replaces the whole reference rather than corrupting a hex
+ *  digit. Built from the same matches the decorations use, so the two never disagree. */
+function buildAtomicRanges(view, library) {
+    const ranges = [];
+    for (const match of visibleMatches(view, library)) {
+        ranges.push(Decoration.replace({}).range(match.from, match.to));
+    }
+    return Decoration.set(ranges, true);
+}
+/**
+ * The media: source decoration extension over a projected library. Each `![alt](media:slug.hash)`
+ * token in the source shows the asset's thumbnail and display name in place of the reference, the
+ * reference is atomic, and an empty alt carries a persistent needs-alt marker. The library is the
+ * `mediaLibrary` projection EditData carries; MarkdownEditor holds it in a compartment and rebuilds
+ * this extension when the library changes, so a just-uploaded image decorates once it is in the
+ * library. An empty library is valid: nothing decorates.
+ */
+export function cairnMediaDecorations(library) {
+    const plugin = ViewPlugin.fromClass(class {
+        decorations;
+        atomic;
+        constructor(view) {
+            this.decorations = buildMediaDecorations(view, library);
+            this.atomic = buildAtomicRanges(view, library);
+        }
+        update(update) {
+            // A doc edit changes the tokens; a viewport change brings new lines into view. A caret move
+            // alone changes neither, so it is not a rebuild trigger here.
+            if (update.docChanged || update.viewportChanged) {
+                this.decorations = buildMediaDecorations(update.view, library);
+                this.atomic = buildAtomicRanges(update.view, library);
+            }
+        }
+    }, {
+        decorations: (v) => v.decorations,
+        // atomicRanges reads the plugin's own atomic set, so the unit the caret skips matches the
+        // decorated tokens exactly.
+        provide: (plugin) => EditorView.atomicRanges.of((view) => view.plugin(plugin)?.atomic ?? Decoration.none),
+    });
+    return plugin;
+}