@glw907/cairn-cms 0.60.0 → 0.62.1

package/src/lib/env.ts

@@ -7,7 +7,6 @@ import type { DeliveryBucket } from './media/delivery-bucket.js';
  *
  * The origin is always config-derived, never read from a request header, so a
  * forged Host header cannot redirect a magic link (spec 7.1, risk H3).
- *
  * @throws CairnError (`config.public-origin-invalid`) when `PUBLIC_ORIGIN` is unset or
  * empty, fails to parse as a URL, or uses http on a non-local host.
  */
@@ -41,7 +40,6 @@ export function requireOrigin(env: { PUBLIC_ORIGIN?: string }): string {
  *
  * The handlers read D1 off `event.platform.env`; without this a misconfigured binding
  * surfaces as a raw `TypeError` deep in a store call. This gives the failure a name.
- *
  * @throws CairnError (`config.bindings-missing`) when `AUTH_DB` is missing.
  */
 export function requireDb(env: { AUTH_DB?: D1Database }): D1Database {
@@ -65,7 +63,6 @@ export function requireDb(env: { AUTH_DB?: D1Database }): D1Database {
  * which is truthy but carries no callable `get`. Without that check the cast would succeed and the
  * first `bucket.get(...)` would throw an uncaught 500 rather than the drained 503 a missing binding
  * earns.
- *
  * @throws CairnError (`config.bindings-missing`) when the named binding is absent or not an R2 bucket.
  */
 export function requireBucket(env: Record<string, unknown>, bindingName: string): DeliveryBucket {

package/src/lib/github/branches.ts

@@ -66,9 +66,11 @@ function nextPageUrl(link: string | null): string | null {
   return null;
 }
 
-/** Branch names under `prefix`, sorted. The matching-refs API paginates at 30 by default, so a
+/**
+ * Branch names under `prefix`, sorted. The matching-refs API paginates at 30 by default, so a
  *  site with 31+ pending entries would silently truncate; request the 100-per-page maximum and
- *  follow the Link rel="next" chain until exhausted. */
+ *  follow the Link rel="next" chain until exhausted.
+ */
 export async function listBranches(repo: RepoRef, prefix: string, token: string): Promise<string[]> {
   const names: string[] = [];
   let url: string | null = `${gitUrl(repo, `matching-refs/heads/${prefix}`)}?per_page=100`;

package/src/lib/github/signing.ts

@@ -20,7 +20,7 @@ function buf(bytes: Uint8Array): ArrayBuffer {
   return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
 }
 
-/** DER length octets for a value of `n` bytes (short form < 128, else long form). */
+/** DER length octets for a value of `n` bytes (short form `< 128`, else long form). */
 function derLength(n: number): number[] {
   if (n < 0x80) return [n];
   const out: number[] = [];
@@ -87,7 +87,7 @@ interface CachedToken {
  * Build an installation-token cache. A module-global instance memoizes the minted token per
  * installation for most of its one-hour life, so a warm Worker isolate reuses it across requests
  * instead of re-signing and re-calling GitHub on every list and commit. A cold isolate re-mints,
- * which is always safe. This mirrors the default of @octokit/auth-app, which caches installation
+ * which is always safe. This mirrors the default of `@octokit/auth-app`, which caches installation
  * tokens in memory and returns them until expiry. The TTL stays under GitHub's documented one-hour
  * lifetime, so a fixed margin avoids parsing the API expiry. The cache holds the in-flight
  * promise, not the resolved token, so a cold isolate's parallel loads coalesce into one mint;

package/src/lib/log/events.ts

@@ -14,6 +14,7 @@ export type CairnLogEvent =
   | 'entry.published'
   | 'entry.discarded'
   | 'publish.failed'
+  | 'publish.address_collision'
   | 'github.unreachable'
   | 'guard.rejected'
   | 'media.uploaded'

package/src/lib/media/bulk-delete-plan.ts

@@ -8,16 +8,20 @@
 import type { UsageEntry, UsageIndex } from './usage.js';
 import type { MediaManifest } from './manifest.js';
 
-/** One selected hash that is not deleted, with why and (for the where-used) its usage rows. The rows
- *  are present only for 'still-referenced'; an 'uncommitted' skip carries an empty list. */
+/**
+ * One selected hash that is not deleted, with why and (for the where-used) its usage rows. The rows
+ *  are present only for 'still-referenced'; an 'uncommitted' skip carries an empty list.
+ */
 export interface BulkDeleteSkip {
   hash: string;
   reason: 'still-referenced' | 'uncommitted';
   usage: UsageEntry[];
 }
 
-/** The partitioned selection: the hashes safe to purge and the hashes held back. Both arrays keep the
- *  input order of `selected` so the screen reports them in the order the user picked. */
+/**
+ * The partitioned selection: the hashes safe to purge and the hashes held back. Both arrays keep the
+ *  input order of `selected` so the screen reports them in the order the user picked.
+ */
 export interface BulkDeletePlan {
   deletable: string[];
   skipped: BulkDeleteSkip[];

package/src/lib/media/config.ts

@@ -7,9 +7,11 @@
 import type { AssetConfig } from '../content/types.js';
 import type { VariantSpec } from './transform-url.js';
 
-/** The resolved media config the engine serves from. When a site declares no assets block, media is
+/**
+ * The resolved media config the engine serves from. When a site declares no assets block, media is
  *  off and the value is `{ enabled: false }`; otherwise every field is filled from the AssetConfig
- *  or its default. */
+ *  or its default.
+ */
 export type ResolvedAssetConfig =
   | { enabled: false }
   | {
@@ -20,8 +22,10 @@ export type ResolvedAssetConfig =
       maxUploadBytes: number;
       allowedTypes: string[];
       variants: Record<string, VariantSpec>;
-      /** Whether Cloudflare Image Transformations are enabled for the zone. With it false, the media
-       *  resolver serves the bare full-size delivery path and ignores any preset. */
+      /**
+       * Whether Cloudflare Image Transformations are enabled for the zone. With it false, the media
+       *  resolver serves the bare full-size delivery path and ignores any preset.
+       */
       transformations: boolean;
     };
 
@@ -32,8 +36,10 @@ const DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
 /** The default accepted upload MIME types: the common web image formats. */
 const DEFAULT_ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp', 'image/gif', 'image/avif'];
 
-/** The built-in named transform presets. A site's `variants` merge over these, so a caller preset of
- *  the same name overrides the built-in. */
+/**
+ * The built-in named transform presets. A site's `variants` merge over these, so a caller preset of
+ *  the same name overrides the built-in.
+ */
 const BUILT_IN_PRESETS: Record<string, VariantSpec> = {
   thumb: { width: 320, height: 320, fit: 'cover' },
   inline: { width: 800 },
@@ -43,8 +49,10 @@ const BUILT_IN_PRESETS: Record<string, VariantSpec> = {
 
 /** The fit values Cloudflare Images accepts. A variant whose fit is set to anything else is rejected. */
 const FIT_VALUES: ReadonlySet<string> = new Set(['scale-down', 'contain', 'cover', 'crop', 'pad']);
-/** The named gravity keywords Cloudflare Images accepts. A gravity is also valid as a coordinate
- *  string; everything else is rejected. */
+/**
+ * The named gravity keywords Cloudflare Images accepts. A gravity is also valid as a coordinate
+ *  string; everything else is rejected.
+ */
 const GRAVITY_KEYWORDS: ReadonlySet<string> = new Set([
   'auto',
   'face',
@@ -57,9 +65,11 @@ const GRAVITY_KEYWORDS: ReadonlySet<string> = new Set([
 /** A gravity coordinate string, e.g. "0.5x0.5". */
 const GRAVITY_COORD_RE = /^\d+(\.\d+)?x\d+(\.\d+)?$/;
 
-/** Validate one variant's fit and gravity, throwing a cairn:-prefixed error naming the offending
+/**
+ * Validate one variant's fit and gravity, throwing a cairn:-prefixed error naming the offending
  *  preset and value. The type system collapses VariantSpec.gravity to string, so the gravity check
- *  is the only guard against a bogus value reaching the transform URL. */
+ *  is the only guard against a bogus value reaching the transform URL.
+ */
 function validateVariant(name: string, spec: VariantSpec): void {
   if (spec.fit !== undefined && !FIT_VALUES.has(spec.fit)) {
     throw new Error(`cairn: media variant "${name}" has an unknown fit "${spec.fit}"`);
@@ -73,10 +83,12 @@ function validateVariant(name: string, spec: VariantSpec): void {
   }
 }
 
-/** Validate a site's AssetConfig and resolve it into a ResolvedAssetConfig. An undefined block leaves
+/**
+ * Validate a site's AssetConfig and resolve it into a ResolvedAssetConfig. An undefined block leaves
  *  media off and returns `{ enabled: false }` rather than throwing. A declared block must name its R2
  *  bucket and carry a known urlForm and valid variant fit and gravity values; each failure throws a
- *  cairn:-prefixed error. The named variants merge over the built-in presets. */
+ *  cairn:-prefixed error. The named variants merge over the built-in presets.
+ */
 export function normalizeAssets(assets: AssetConfig | undefined): ResolvedAssetConfig {
   if (assets === undefined) return { enabled: false };
 

package/src/lib/media/delivery-bucket.ts

@@ -16,9 +16,11 @@ export interface DeliveryObject {
   httpEtag: string;
   /** The full object size in bytes, the denominator of a `Content-Range`. */
   size: number;
-  /** Present only on a ranged read: the served window, used to build the `Content-Range`. R2 fills
+  /**
+   * Present only on a ranged read: the served window, used to build the `Content-Range`. R2 fills
    *  both fields for a `bytes=start-end` request; each is typed optional so the route derives the
-   *  range bounds defensively against `size`. */
+   *  range bounds defensively against `size`.
+   */
   range?: { offset?: number; length?: number };
 }
 

package/src/lib/media/library-entry.ts

@@ -39,9 +39,11 @@ export interface MediaLibraryEntry {
 /** The projected library keyed by the 16-hex content hash, exactly EditData's `mediaLibrary`. */
 export type MediaLibrary = Record<string, MediaLibraryEntry>;
 
-/** Project a stored MediaEntry to the picker's MediaLibraryEntry, copying every display field and
+/**
+ * Project a stored MediaEntry to the picker's MediaLibraryEntry, copying every display field and
  *  dropping the source-only sha256 and original filename. The single projection editLoad and
- *  mediaLibraryLoad both call, so the popover and the Library never diverge on the shared shape. */
+ *  mediaLibraryLoad both call, so the popover and the Library never diverge on the shared shape.
+ */
 export function mediaLibraryEntry(entry: MediaEntry): MediaLibraryEntry {
   return {
     hash: entry.hash,

package/src/lib/media/manifest.ts

@@ -4,10 +4,12 @@
 // are never stored twice. It mirrors the content manifest in ../content/manifest.ts, keyed by the
 // 16-hex content-hash prefix rather than concept and id.
 
-/** One stored asset's row: its content hash, its human layer, and its byte and pixel facts. The
+/**
+ * One stored asset's row: its content hash, its human layer, and its byte and pixel facts. The
  *  `contentType` is the stored MIME type, so the delivery route serves it verbatim rather than
  *  guessing from the extension. `width` and `height` are null when no dimensions are known (the
- *  client is the only dimension source and a Worker cannot re-derive them). */
+ *  client is the only dimension source and a Worker cannot re-derive them).
+ */
 export interface MediaEntry {
   hash: string;
   sha256: string;
@@ -26,19 +28,22 @@ export interface MediaEntry {
 /** The whole stored-asset record, keyed by the 16-hex content-hash prefix. */
 export type MediaManifest = Record<string, MediaEntry>;
 
-/** Parse a committed media manifest. Tolerant: an empty, missing, null, or non-object input yields
- *  an empty manifest, so a first ingest into a site with no manifest file reads a clean {}. A valid
- *  object is returned as the manifest. */
+/**
+ * Parse a committed media manifest. Tolerant: an empty, missing, null, or non-object input yields
+ *  an empty manifest, so a first ingest into a site with no manifest file reads a clean `{}`. A valid
+ *  object is returned as the manifest.
+ */
 export function parseMediaManifest(json: unknown): MediaManifest {
   if (!json || typeof json !== 'object' || Array.isArray(json)) return {};
   return json as MediaManifest;
 }
 
-/** Validate one posted value as a MediaEntry, returning it narrowed or undefined. The trust boundary
+/**
+ * Validate one posted value as a MediaEntry, returning it narrowed or undefined. The trust boundary
  *  for an optimistic record the client re-posts: the upload action server-owned each field at
  *  creation, but a re-post is untrusted, so every field is re-checked. A `hash` must be the 16-hex
- *  content-hash prefix; the string fields must be strings; `bytes` must be finite; `width`/`height`
- *  must each be a number or null; `createdAt` must be a string. */
+ *  content-hash prefix.
+ */
 function validateMediaEntry(value: unknown): MediaEntry | undefined {
   if (!value || typeof value !== 'object') return undefined;
   const e = value as Record<string, unknown>;
@@ -67,12 +72,14 @@ function validateMediaEntry(value: unknown): MediaEntry | undefined {
   };
 }
 
-/** Parse the posted `media` field into a validated list of MediaEntry rows. The field arrives as a
+/**
+ * Parse the posted `media` field into a validated list of MediaEntry rows. The field arrives as a
  *  JSON string (the usual form-post shape), an already-parsed array, or junk. A string is JSON-parsed
  *  inside a try/catch that yields `[]` on a parse failure; a non-string array is taken directly;
  *  anything else yields `[]`. Each element is validated and a failing element is dropped, so a partly
  *  malformed post still lands its good rows. This is the trust boundary for the client's optimistic
- *  records. */
+ *  records.
+ */
 export function parseMediaEntries(value: unknown): MediaEntry[] {
   let raw: unknown = value;
   if (typeof value === 'string') {
@@ -91,28 +98,36 @@ export function parseMediaEntries(value: unknown): MediaEntry[] {
   return entries;
 }
 
-/** The dedup lookup: the entry stored under the content-hash prefix, or undefined when no bytes with
- *  that hash are stored yet. */
+/**
+ * The dedup lookup: the entry stored under the content-hash prefix, or undefined when no bytes with
+ *  that hash are stored yet.
+ */
 export function findByHash(manifest: MediaManifest, hash: string): MediaEntry | undefined {
   return manifest[hash];
 }
 
-/** Set the entry under its own hash, replacing any same-hash row. Returns a new manifest and leaves
- *  the input untouched, so a caller's prior manifest reference stays valid. The ingest path's patch. */
+/**
+ * Set the entry under its own hash, replacing any same-hash row. Returns a new manifest and leaves
+ *  the input untouched, so a caller's prior manifest reference stays valid. The ingest path's patch.
+ */
 export function upsertMediaEntry(manifest: MediaManifest, entry: MediaEntry): MediaManifest {
   return { ...manifest, [entry.hash]: entry };
 }
 
-/** Drop the entry under the given hash, returning a new manifest and leaving the input untouched.
+/**
+ * Drop the entry under the given hash, returning a new manifest and leaving the input untouched.
  *  Removing an absent hash is a no-op that still returns an equivalent new manifest. The safe-delete
- *  path's patch. */
+ *  path's patch.
+ */
 export function removeMediaEntry(manifest: MediaManifest, hash: string): MediaManifest {
   const { [hash]: _removed, ...rest } = manifest;
   return rest;
 }
 
-/** Serialize canonically: the top-level hash keys sorted ascending, two-space pretty, and a trailing
- *  newline, so the committed file diffs cleanly in a PR and a re-serialization is byte-identical. */
+/**
+ * Serialize canonically: the top-level hash keys sorted ascending, two-space pretty, and a trailing
+ *  newline, so the committed file diffs cleanly in a PR and a re-serialization is byte-identical.
+ */
 export function serializeMediaManifest(manifest: MediaManifest): string {
   const sorted: MediaManifest = {};
   for (const hash of Object.keys(manifest).sort()) {

package/src/lib/media/naming.ts

@@ -7,13 +7,17 @@
 // slugifyFilename output always satisfies parseMediaToken's grammar (lowercase alphanumerics joined
 // by single internal hyphens, no leading or trailing hyphen), or is the literal `file`.
 
-/** Combining marks (Unicode block U+0300 to U+036F), left over after an NFD decompose, stripped to
+/**
+ * Combining marks (Unicode block U+0300 to U+036F), left over after an NFD decompose, stripped to
  *  fold an accented letter down to its ASCII base. Written as escapes because the literal marks are
- *  invisible in source. */
+ *  invisible in source.
+ */
 const COMBINING_MARKS = /[\u0300-\u036f]/g;
 
-/** Windows reserved device names. A bare match (case-insensitive) cannot survive as the slug, since
- *  it names a device rather than a file on that platform. */
+/**
+ * Windows reserved device names. A bare match (case-insensitive) cannot survive as the slug, since
+ *  it names a device rather than a file on that platform.
+ */
 const RESERVED = new Set([
   'con',
   'prn',
@@ -42,8 +46,10 @@ const RESERVED = new Set([
 /** The maximum slug length, applied before the reserved-name and empty fallbacks. */
 const MAX_SLUG = 80;
 
-/** A 16-character lowercase hex content-hash prefix, the bare-hash reference form. A slug that
- *  matches this shape would collide with `media:<hash>`, so slugifyFilename screens it. */
+/**
+ * A 16-character lowercase hex content-hash prefix, the bare-hash reference form. A slug that
+ *  matches this shape would collide with `media:<hash>`, so slugifyFilename screens it.
+ */
 const HASH_RE = /^[0-9a-f]{16}$/;
 
 /** A short alphanumeric extension (no dot), the only shape r2Key accepts, for example `webp`. */
@@ -69,10 +75,12 @@ export function shortHash(full: string): string {
   return full.slice(0, 16);
 }
 
-/** The strict ingest transform from a raw filename to a slug that satisfies the media: slug grammar,
+/**
+ * The strict ingest transform from a raw filename to a slug that satisfies the media: slug grammar,
  *  or the literal `file`. Drops the extension, lowercases, transliterates accents, collapses non-alphanumeric runs
  *  to a single hyphen, trims, caps at 80 chars, screens Windows reserved names, and falls back to
- *  `file` when nothing usable is left. */
+ *  `file` when nothing usable is left.
+ */
 export function slugifyFilename(name: string): string {
   const dot = name.lastIndexOf('.');
   const stem = dot === -1 ? name : name.slice(0, dot);
@@ -97,9 +105,11 @@ export function slugifyFilename(name: string): string {
   return slug;
 }
 
-/** The content-addressed R2 object key `media/<aa>/<shortHash>.<ext>`, fanned out on the first two
+/**
+ * The content-addressed R2 object key `media/<aa>/<shortHash>.<ext>`, fanned out on the first two
  *  hex chars of the short hash. No leading slash: this is an object key, not a URL. `ext` is bare
- *  (no dot), for example `webp`. */
+ *  (no dot), for example `webp`.
+ */
 export function r2Key(shortHash: string, ext: string): string {
   if (!HASH_RE.test(shortHash)) {
     throw new Error(`r2Key: hash must be 16 lowercase hex chars, got "${shortHash}"`);
@@ -110,10 +120,12 @@ export function r2Key(shortHash: string, ext: string): string {
   return `media/${shortHash.slice(0, 2)}/${shortHash}.${ext}`;
 }
 
-/** The public delivery URL path, with a leading slash, under the delivery base (`publicBase`,
+/**
+ * The public delivery URL path, with a leading slash, under the delivery base (`publicBase`,
  *  default `/media`). The `slug` form is human-readable (`<base>/<slug>.<shortHash>.<ext>`, or
  *  `<base>/<shortHash>.<ext>` when the slug is null); the `opaque` form mirrors the R2 fan-out
- *  (`<base>/<aa>/<shortHash>.<ext>`) and ignores the slug. */
+ *  (`<base>/<aa>/<shortHash>.<ext>`) and ignores the slug.
+ */
 export function publicPath(
   slug: string | null,
   shortHash: string,

package/src/lib/media/orphan-scan.ts

@@ -23,8 +23,10 @@ export interface OrphanByteRow {
   hash: string;
 }
 
-/** A broken reference: a manifest row whose bytes are gone. Read-only, since purging it would drop a
- *  still-referenced asset's record; the screen shows where it is used so an operator can re-ingest. */
+/**
+ * A broken reference: a manifest row whose bytes are gone. Read-only, since purging it would drop a
+ *  still-referenced asset's record; the screen shows where it is used so an operator can re-ingest.
+ */
 export interface BrokenRefRow {
   /** The 16-hex content hash of the manifest row whose bytes are missing. */
   hash: string;

package/src/lib/media/reconcile.ts

@@ -8,12 +8,16 @@
 import type { MediaManifest } from './manifest.js';
 import { log } from '../log/index.js';
 
-/** A stored media object key parses to its short hash via `media/<aa>/<shortHash>.<ext>`. Exported so
- *  the orphan-scan projection derives the same hash from an orphaned key without a second grammar. */
+/**
+ * A stored media object key parses to its short hash via `media/<aa>/<shortHash>.<ext>`. Exported so
+ *  the orphan-scan projection derives the same hash from an orphaned key without a second grammar.
+ */
 export const MEDIA_KEY_RE = /^media\/[0-9a-f]{2}\/([0-9a-f]{16})\.[a-z0-9]{1,5}$/;
 
-/** What a reconcile read found in either direction. `orphanedObjects` are stored R2 keys whose hash
- *  has no manifest row; `missingObjects` are manifest hashes with no stored object. */
+/**
+ * What a reconcile read found in either direction. `orphanedObjects` are stored R2 keys whose hash
+ *  has no manifest row; `missingObjects` are manifest hashes with no stored object.
+ */
 export interface ReconcileResult {
   /** Stored keys (full R2 keys) whose content hash is absent from the manifest. */
   orphanedObjects: string[];
@@ -21,9 +25,11 @@ export interface ReconcileResult {
   missingObjects: string[];
 }
 
-/** The pure core: compare the stored R2 keys against the manifest's content-hash keys and report
+/**
+ * The pure core: compare the stored R2 keys against the manifest's content-hash keys and report
  *  both orphan directions. A stored key that does not match the media-key grammar is ignored, since
- *  it is not a content-addressed media object this reconcile owns. */
+ *  it is not a content-addressed media object this reconcile owns.
+ */
 export function reconcileMedia(storedKeys: string[], manifest: MediaManifest): ReconcileResult {
   const manifestHashes = new Set(Object.keys(manifest));
   const storedHashes = new Set<string>();
@@ -48,17 +54,21 @@ interface ReconcileListPage {
   cursor?: string;
 }
 
-/** The R2 bucket surface the reconcile read needs: a single prefixed, paginated list. A local
- *  structural interface so no @cloudflare/workers-types name is imported (the module is internal and
- *  on no public subpath, but the narrow seam keeps the build self-contained either way). */
+/**
+ * The R2 bucket surface the reconcile read needs: a single prefixed, paginated list. A local
+ *  structural interface so no `@cloudflare/workers-types` name is imported (the module is internal and
+ *  on no public subpath, but the narrow seam keeps the build self-contained either way).
+ */
 export interface ReconcileBucket {
   list(opts?: { prefix?: string; cursor?: string }): Promise<ReconcileListPage>;
 }
 
-/** The glue runner: list every stored key under the media/ prefix (paginating through R2's
+/**
+ * The glue runner: list every stored key under the media/ prefix (paginating through R2's
  *  cursor/truncated), reconcile against the manifest, log the count summary, and return the result.
  *  The log record carries counts only, never bytes or a key list; the keys are content hashes and so
- *  carry no PII, but the count summary is all an operator needs to size the orphan state. */
+ *  carry no PII, but the count summary is all an operator needs to size the orphan state.
+ */
 export async function runReconcile(
   bucket: ReconcileBucket,
   manifest: MediaManifest,

package/src/lib/media/reference.ts

@@ -14,14 +14,18 @@ export interface MediaRef {
 /** A 16-character lowercase hex content-hash prefix. */
 const HASH_RE = /^[0-9a-f]{16}$/;
 
-/** The slug grammar from the Task 2 slugify transform: lowercase alphanumerics joined by single
+/**
+ * The slug grammar from the Task 2 slugify transform: lowercase alphanumerics joined by single
  *  internal hyphens, with no leading or trailing hyphen and no dot (the dot is the slug/hash
- *  separator). */
+ *  separator).
+ */
 const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
-/** Parse a `media:<slug>.<hash>` href (or the bare `media:<hash>` form), or null for any other
+/**
+ * Parse a `media:<slug>.<hash>` href (or the bare `media:<hash>` form), or null for any other
  *  href or a malformed token. Splits on the last dot, so a slug that illegally contains a dot fails
- *  the slug grammar and returns null. */
+ *  the slug grammar and returns null.
+ */
 export function parseMediaToken(href: string): MediaRef | null {
   if (!href.startsWith('media:')) return null;
   const rest = href.slice('media:'.length);
@@ -33,8 +37,10 @@ export function parseMediaToken(href: string): MediaRef | null {
   return { slug, hash };
 }
 
-/** Write the canonical media: token for a ref. The inverse of parseMediaToken, so a parse then
- *  write round trip is stable: `media:<slug>.<hash>` when the slug is present, else `media:<hash>`. */
+/**
+ * Write the canonical media: token for a ref. The inverse of parseMediaToken, so a parse then
+ *  write round trip is stable: `media:<slug>.<hash>` when the slug is present, else `media:<hash>`.
+ */
 export function mediaToken(ref: MediaRef): string {
   return ref.slug === null ? `media:${ref.hash}` : `media:${ref.slug}.${ref.hash}`;
 }

package/src/lib/media/rewrite-plan.ts

@@ -23,9 +23,11 @@ import { filenameFromId } from '../content/ids.js';
 import { readRaw } from '../github/repo.js';
 import { buildUsageIndex } from './usage.js';
 
-/** One main entry the rewrite will touch: its identity, its file path, the transform's per-placement
+/**
+ * One main entry the rewrite will touch: its identity, its file path, the transform's per-placement
  *  diff, and the rewritten markdown a later apply commits. `P` is the transform's placement type
- *  (a RepointPlacement for replace, an AltPlacement for fill-alt). */
+ *  (a RepointPlacement for replace, an AltPlacement for fill-alt).
+ */
 export interface PlannedEntry<P = unknown> {
   /** The concept id, e.g. "posts". */
   concept: string;
@@ -39,9 +41,11 @@ export interface PlannedEntry<P = unknown> {
   newMarkdown: string;
 }
 
-/** One open edit branch that also references the asset, with the entries on it. Report-only: an apply
+/**
+ * One open edit branch that also references the asset, with the entries on it. Report-only: an apply
  *  rewrites main, never a branch, so the screen surfaces these as a delta the editor handles by
- *  republishing the draft. */
+ *  republishing the draft.
+ */
 export interface BranchRef {
   /** The cairn/* branch name. */
   branch: string;
@@ -49,8 +53,10 @@ export interface BranchRef {
   entries: { concept: string; id: string }[];
 }
 
-/** The preview plan: the main entries to rewrite, the report-only branch delta, and the distinct
- *  count of affected main entries (the entries the transform actually changed). */
+/**
+ * The preview plan: the main entries to rewrite, the report-only branch delta, and the distinct
+ *  count of affected main entries (the entries the transform actually changed).
+ */
 export interface RewritePlan<P = unknown> {
   entries: PlannedEntry<P>[];
   branchDelta: BranchRef[];

package/src/lib/media/sniff.ts

@@ -8,16 +8,22 @@
 // nosniff, Content-Disposition: inline, a restrictive Content-Security-Policy) are the real XSS control
 // for the served bytes; sniffing here is the ingest gate, not the served-bytes defense.
 
-/** The leading ASCII whitespace bytes skipped before the deny-list's first-byte-is-`<` check:
- *  tab (0x09), newline (0x0A), carriage return (0x0D), and space (0x20). */
+/**
+ * The leading ASCII whitespace bytes skipped before the deny-list's first-byte-is-`<` check:
+ *  tab (0x09), newline (0x0A), carriage return (0x0D), and space (0x20).
+ */
 const WHITESPACE = new Set([0x09, 0x0a, 0x0d, 0x20]);
 
-/** The single byte `<` (0x3C). A payload whose first non-whitespace byte is `<` is markup (SVG, HTML,
- *  XML) and is denied regardless of its declared type or any site `allowedTypes`. */
+/**
+ * The single byte `<` (0x3C). A payload whose first non-whitespace byte is `<` is markup (SVG, HTML,
+ *  XML) and is denied regardless of its declared type or any site `allowedTypes`.
+ */
 const LT = 0x3c;
 
-/** Declared content types denied at the engine level, independent of any site `allowedTypes`. SVG and
- *  the markup types carry active content (script, foreignObject), so they never ingest as media. */
+/**
+ * Declared content types denied at the engine level, independent of any site `allowedTypes`. SVG and
+ *  the markup types carry active content (script, foreignObject), so they never ingest as media.
+ */
 const DENIED_TYPES = new Set(['image/svg+xml', 'image/svg', 'text/html', 'application/xml']);
 
 /** The ISO-BMFF major-brand codes (at bytes 8..11 of an `ftyp` box) that mean an AVIF image. */
@@ -26,8 +32,10 @@ const AVIF_BRANDS = new Set(['avif', 'avis']);
 /** The ISO-BMFF major-brand codes that mean a HEIF/HEIC image. */
 const HEIC_BRANDS = new Set(['heic', 'heix', 'heif', 'hevc', 'hevx', 'mif1', 'msf1']);
 
-/** True when every byte of `magic` matches `bytes` starting at `offset`. False if `bytes` is too
- *  short to hold the whole magic. */
+/**
+ * True when every byte of `magic` matches `bytes` starting at `offset`. False if `bytes` is too
+ *  short to hold the whole magic.
+ */
 function matches(bytes: Uint8Array, offset: number, magic: number[]): boolean {
   if (bytes.length < offset + magic.length) return false;
   for (let i = 0; i < magic.length; i++) {
@@ -36,8 +44,10 @@ function matches(bytes: Uint8Array, offset: number, magic: number[]): boolean {
   return true;
 }
 
-/** The four ASCII characters at bytes `offset..offset+3`, or null when the input is too short. Used to
- *  read an ISO-BMFF brand code as a string. */
+/**
+ * The four ASCII characters at bytes `offset..offset+3`, or null when the input is too short. Used to
+ *  read an ISO-BMFF brand code as a string.
+ */
 function ascii4(bytes: Uint8Array, offset: number): string | null {
   if (bytes.length < offset + 4) return null;
   return String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
@@ -77,9 +87,11 @@ export function sniffMediaType(bytes: Uint8Array): string | null {
   return null;
 }
 
-/** The bare file extension (no dot) for each sniffed media type the upload path stores. The ext is
+/**
+ * The bare file extension (no dot) for each sniffed media type the upload path stores. The ext is
  *  derived from the server-sniffed type, never the client filename, so the stored key and the
- *  delivery extension allow-list always agree. An unmappable type returns null (the upload 415s). */
+ *  delivery extension allow-list always agree. An unmappable type returns null (the upload 415s).
+ */
 const EXT_BY_TYPE: Record<string, string> = {
   'image/jpeg': 'jpg',
   'image/png': 'png',
@@ -88,8 +100,10 @@ const EXT_BY_TYPE: Record<string, string> = {
   'image/avif': 'avif',
 };
 
-/** The storage extension for a sniffed media type, or null for a type the upload path does not store
- *  (HEIC, an unknown type). Driven by the sniffed type, so the key's ext is server-owned. */
+/**
+ * The storage extension for a sniffed media type, or null for a type the upload path does not store
+ *  (HEIC, an unknown type). Driven by the sniffed type, so the key's ext is server-owned.
+ */
 export function extForMediaType(type: string): string | null {
   return EXT_BY_TYPE[type] ?? null;
 }