@glw907/cairn-cms 0.56.1 → 0.57.0

package/src/lib/components/client-ingest.ts

@@ -0,0 +1,380 @@
+// 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: Uint8Array): boolean {
+  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: Uint8Array): { width: number; height: number } | null {
+  // '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: RegExp[] = [
+  /^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: string): string | null {
+  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: {
+  files?: ArrayLike<File>;
+  items?: ArrayLike<DataTransferItem>;
+}): File[] {
+  const files = dt.files;
+  if (!files) return [];
+  const out: File[] = [];
+  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: {
+  files?: ArrayLike<File>;
+  items?: ArrayLike<DataTransferItem>;
+}): File | null {
+  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: number,
+  height: number,
+): { width: number; height: number } {
+  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 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;
+
+/** The human message per failure kind, plain and specific so an author knows whether to retry. */
+const FAILURE_MESSAGE: Record<IngestFailureKind, string> = {
+  '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: IngestFailureKind): IngestFailureCard {
+  return { status: 'failed', kind, message: FAILURE_MESSAGE[kind] };
+}
+
+/** 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 function buildUploadRequest(opts: UploadRequestOpts): { url: string; init: RequestInit } {
+  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: Record<string, string> = {
+    '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: RequestInit = {
+    method: 'POST',
+    redirect: 'manual',
+    headers,
+    body: opts.bytes as BodyInit,
+  };
+  return { url, init };
+}
+
+// ---------------------------------------------------------------------------
+// Browser-coupled glue (wired, proven live at 2b/site, not unit-tested here)
+// ---------------------------------------------------------------------------
+
+/** The structural shape of the heic-to module's `heicTo`, typed here so the dynamic import stays
+ *  lazy. A HEIC blob in, a decoded image blob out (PNG, with the HEIF orientation already applied). */
+type HeicTo = (args: { blob: Blob; type: 'image/png' }) => Promise<Blob>;
+
+/** A decoded source plus its dimensions, the input to the upload step. */
+interface IngestResult {
+  blob: Blob;
+  contentType: string;
+  width: number | null;
+  height: number | null;
+}
+
+/** Thrown inside the orchestration so a kind maps cleanly to a failure card at the boundary. */
+class IngestError extends Error {
+  constructor(readonly kind: IngestFailureKind) {
+    super(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: File): Promise<IngestResult> {
+  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: ImageBitmap;
+    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: Blob;
+    try {
+      const mod = (await import('heic-to')) as { heicTo: HeicTo };
+      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: Blob): Promise<IngestResult> {
+  let bitmap: ImageBitmap;
+  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<Blob | null>((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: unknown): IngestFailureKind {
+  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: string, init: RequestInit): Promise<Response> {
+  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: DragEvent): void {
+  event.preventDefault();
+}

package/src/lib/components/editor-media.ts

@@ -0,0 +1,248 @@
+// 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,
+  type DecorationSet,
+  type ViewUpdate,
+} from '@codemirror/view';
+import { RangeSetBuilder, type Extension, type Range } from '@codemirror/state';
+import { parseMediaToken } from '../media/reference.js';
+import { publicPath } from '../media/naming.js';
+import { fenceScan, figureRoleAtLine } from './markdown-directives.js';
+// The decoration reads MediaLibrary/MediaLibraryEntry (the shared node-safe projection) for the
+// thumbnail path, the display name, and the alt-empty test.
+import type { MediaLibrary, MediaLibraryEntry } from '../media/library-entry.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;
+
+/** A matched media image in a line: the alt text and the URL token's character offsets within the
+ *  whole document, plus the parsed reference and the library entry (null when the hash is unknown).
+ *  figureRole carries the enclosing `:::figure` placement (the closed-set role, or `'figure'` for
+ *  the measure default), or null when the token is not in a figure: a bare token shows no role pill. */
+interface MediaImageMatch {
+  alt: string;
+  from: number;
+  to: number;
+  token: string;
+  slug: string | null;
+  hash: string;
+  entry: MediaLibraryEntry | null;
+  figureRole: 'center' | 'wide' | 'full' | 'figure' | null;
+}
+
+// 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 {
+  constructor(readonly match: MediaImageMatch) {
+    super();
+  }
+
+  eq(other: WidgetType): boolean {
+    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(): HTMLElement {
+    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(): boolean {
+    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: string, lineFrom: number, library: MediaLibrary): MediaImageMatch[] {
+  const out: MediaImageMatch[] = [];
+  MEDIA_IMAGE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  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: EditorView, library: MediaLibrary): MediaImageMatch[] {
+  const lines = view.state.doc.toString().split('\n');
+  const scan = fenceScan(lines);
+  const out: MediaImageMatch[] = [];
+  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: EditorView, library: MediaLibrary): DecorationSet {
+  const builder = new RangeSetBuilder<Decoration>();
+  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: EditorView, library: MediaLibrary): DecorationSet {
+  const ranges: Range<Decoration>[] = [];
+  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: MediaLibrary): Extension {
+  const plugin = ViewPlugin.fromClass(
+    class {
+      decorations: DecorationSet;
+      atomic: DecorationSet;
+      constructor(view: EditorView) {
+        this.decorations = buildMediaDecorations(view, library);
+        this.atomic = buildAtomicRanges(view, library);
+      }
+      update(update: ViewUpdate) {
+        // 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;
+}