@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/media-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/media-metadata.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Asset metadata helpers (AGL-173): tag normalization shared by the\n * console editor and any future API validation, plus a dependency-free\n * image header parser so the upload route can stamp dimensions without\n * pulling in an image library.\n */\n\nimport { MEDIA_ALT_MAX_LENGTH } from './media-alt'\n\nexport * from './media-alt'\n\nexport const MEDIA_TAG_MAX_COUNT = 20\nexport const MEDIA_TAG_MAX_LENGTH = 40\n\n/**\n * Trim, lowercase, dedupe, and cap tags. Accepts a comma-separated string\n * or an array; empty and oversized entries are dropped.\n */\nexport function normalizeMediaTags(input: string | string[]): string[] {\n  const raw = Array.isArray(input) ? input : String(input ?? '').split(',')\n  const seen = new Set<string>()\n  const tags: string[] = []\n  for (const entry of raw) {\n    const tag = String(entry ?? '').trim().toLowerCase()\n    if (!tag || tag.length > MEDIA_TAG_MAX_LENGTH || seen.has(tag)) continue\n    seen.add(tag)\n    tags.push(tag)\n    if (tags.length >= MEDIA_TAG_MAX_COUNT) break\n  }\n  return tags\n}\n\n/**\n * What a placement should store for `alt` once the asset's own alt text is\n * taken into account (AGL-1896) — the DAM asset is the DEFAULT, the\n * placement keeps the override.\n *\n * `AglynHostMedia.alt` has existed since AGL-173 and the library drawer has\n * always been able to set it; what never existed is anybody READING it. Every\n * placement surface asked the author to type alt again from scratch, so the\n * same logo on eight pages needed its alt typed eight times and in practice\n * shipped blank — on a customer's published site.\n *\n * ONE function, called at pick time by every surface, rather than a rule\n * re-derived per surface. The three refusals are the whole contract:\n *\n * * **`decorative` wins outright.** It is the field AGL-1305 added to record\n *   \"screen readers should skip this\", and `image.tsx` already forces\n *   `alt=\"\"` over any alt text when it is on. Inheriting into a node that has\n *   declared itself decorative would put text on a node whose renderer\n *   discards it — invisible, and misleading to the next author who opens the\n *   panel.\n * * **A non-blank placement alt wins.** That is the per-placement override,\n *   and clobbering it is the one failure that would make this feature worse\n *   than not having it: the author's sentence about THIS placement is better\n *   than the asset's generic one by construction.\n * * **A blank asset alt yields nothing.** Never a fabricated default. The\n *   file name is not alt text (\"IMG_4021.jpg\" announced to a screen reader is\n *   worse than silence), and nothing here has seen the image. Returning\n *   `undefined` is what lets callers omit the key entirely rather than\n *   writing `alt: ''`, which on a besigner node is itself an authored value.\n *\n * A blank placement alt DOES inherit, deliberately. Presets ship `alt: ''`\n * (see `card.tsx`), so requiring an absent key would have skipped the single\n * commonest authoring path — dropping a preset and pointing its image at a\n * library asset — and left the issue open for the case it was filed about.\n *\n * @returns the alt to store, or `undefined` when the caller should write\n * nothing at all.\n */\nexport function inheritedMediaAlt(options: {\n  /** The alt already on the placement — a node prop, a config field. */\n  placementAlt?: unknown\n  /** The placement's explicit \"skip me\" intent, when it has one. */\n  decorative?: unknown\n  /** The chosen DAM asset's stored alt text. */\n  assetAlt?: unknown\n}): string | undefined {\n  const { placementAlt, decorative, assetAlt } = options ?? {}\n  if (decorative === true) return undefined\n  if (typeof placementAlt === 'string' && placementAlt.trim()) return undefined\n  const inherited = typeof assetAlt === 'string' ? assetAlt.trim() : ''\n  if (!inherited) return undefined\n  // Capped at the same length the library drawer saves through, so an alt\n  // that reaches a placement is one the DAM would also have stored.\n  return inherited.slice(0, MEDIA_ALT_MAX_LENGTH)\n}\n\n/**\n * Component ids whose renderer reads intrinsic pixel dimensions off the node.\n *\n * Component ids are persisted in screen documents and never renamed, which is\n * what makes matching on them safe. The list is the gate rather than a\n * decoration: a prop written onto an element that does not destructure it\n * reaches `...rest` and is spread onto the DOM, so an unlisted element would\n * gain an invalid `intrinsicwidth` attribute in its published HTML.\n *\n * ⛔ `video` is NOT here, and its absence is a decision rather than an\n * oversight (AGL-2749). A video needs the pair at least as badly as an image\n * does — `preload=\"none\"` means its metadata never arrives until someone\n * presses play, so the element is zero-height for the whole life of the page\n * without it — but it cannot get it from `width`/`height`. Those are read\n * from the bytes by the server and are absent on every video, deliberately:\n * AGL-2742 kept the client-measured triple in its own `video` record so a\n * reader can tell a server measurement from a browser's report.\n * {@link videoMediaProps} is where a video gets its pair.\n */\nconst INTRINSIC_SIZE_COMPONENT_IDS = new Set(['image'])\n\n/**\n * The intrinsic `width`/`height` to copy onto a node when an author picks a\n * library asset for it (AGL-2486).\n *\n * ## Why the copy happens at pick time, and why it is not the last word\n *\n * The pair rides on the node like every other prop, so the editor canvas, and\n * any page whose asset cannot be read, still reserve a box. It is not the last\n * word. A replace rewrites the asset's `width`/`height` and cannot reach the\n * nodes that copied them, so the tenant composition reads every placed\n * image's document, in one projected batch per page, and lays its current\n * pair over this one (`media-asset-facts.ts`, AGL-2833). What is written here\n * is what a page shows when that read cannot answer.\n *\n * ## Why it matters\n *\n * `image.tsx` lays images out with `width: 100%; height: auto`, under which an\n * `<img>` has NO height until its bytes decode. Without an intrinsic pair the\n * browser has no ratio to reserve a box from, so every image on the page\n * shifts the content below it as it lands.\n *\n * ## The rules\n *\n * * **Both or neither.** A browser derives an aspect-ratio only from the\n *   pair; a lone `width` is read as a real dimension and reserves a box of\n *   the wrong shape, which is worse than reserving none.\n * * **Only for renderers that read them**, see\n *   `INTRINSIC_SIZE_COMPONENT_IDS` — otherwise the prop lands on the DOM.\n * * **Finite and positive.** Upload capture is best-effort, so a media\n *   document may carry `0`, a partial capture, or nothing at all; `width=\"0\"`\n *   collapses the element.\n * * **`{}` when anything is unknown**, never `{ intrinsicWidth: undefined }`.\n *   Callers spread the result into a props object that `updateNodeProps`\n *   REPLACES wholesale, so a key present with an undefined value would strip\n *   a pair a previous pick had correctly stored.\n *\n * @returns the props to spread, or `{}` when the caller should write nothing.\n */\nexport function intrinsicMediaSize(options: {\n  /** The element being written to — its persisted component id. */\n  componentId?: unknown\n  /** The attribute the picker was opened for; only `src` carries an image. */\n  propName?: unknown\n  /** The chosen asset's stored pixel width. */\n  assetWidth?: unknown\n  /** The chosen asset's stored pixel height. */\n  assetHeight?: unknown\n}): { intrinsicWidth?: number; intrinsicHeight?: number } {\n  const { componentId, propName, assetWidth, assetHeight } = options ?? {}\n  if (propName !== 'src') return {}\n  if (!INTRINSIC_SIZE_COMPONENT_IDS.has(String(componentId ?? ''))) return {}\n  const usable = (value: unknown): value is number =>\n    typeof value === 'number' && Number.isFinite(value) && value > 0\n  if (!usable(assetWidth) || !usable(assetHeight)) return {}\n  return { intrinsicWidth: assetWidth, intrinsicHeight: assetHeight }\n}\n\n/** The one element that reads the props below off its node. */\nconst VIDEO_COMPONENT_ID = 'video'\n\n/**\n * The video-only companions to {@link intrinsicMediaSize}, copied onto the\n * node when an author picks a video asset (AGL-2741, rewritten against the\n * real document shape in AGL-2749).\n *\n * Same route as the image dimensions, and like theirs not the last word. A\n * replace rewrites the asset's `video` and `poster` records and cannot reach\n * the nodes that copied them, so the tenant composition reads each placed\n * film's document, in the same batch as the images', and lays its current\n * records over these (`media-asset-facts.ts`, AGL-2807). What is written here\n * is what a page shows when that read cannot answer.\n *\n * ## Why a video does not simply use {@link intrinsicMediaSize}\n *\n * A video's pixel dimensions are NOT in `media.width`/`media.height`. Those\n * are read from the bytes by the server and carry a stronger claim than a\n * browser's report, so AGL-2742 kept the client-measured triple in its own\n * `video` record rather than widening them — a reader that folded the two\n * together would lose the ability to tell which it had. A video therefore\n * reaches its intrinsic pair through here, and `intrinsicMediaSize` finds\n * nothing to copy for one.\n *\n * ## The three rules\n *\n * * **Only the `video` element, only its `src`.** A `durationSeconds` spread\n *   onto an element that does not destructure it becomes an invalid attribute\n *   in the published HTML.\n * * **The duration is stored in SECONDS**, because the author-facing field is\n *   in seconds and a person types 63, not 63000. `videoDurationIso8601` takes\n *   milliseconds, and the structured-data builder is the one place that\n *   converts back.\n * * **`{}` when unknown**, never a key with an `undefined` value: callers\n *   spread this into a props object `updateNodeProps` REPLACES wholesale, so\n *   a present-but-undefined key strips what an earlier pick stored.\n *\n * `posterFromSource` is a FLAG rather than a url, deliberately. The generated\n * poster is `?poster=1` on the video's own reference, which\n * {@link mediaPosterSrc} builds without reading anything — and that url is\n * explicitly not a promise the poster exists. This flag IS the promise: it is\n * written only when the document records one, which is what lets\n * `videoPosterSrc` offer the derived url to an `<img>` and to a\n * `thumbnailUrl`, where a 404 would be a broken image and a rich result\n * pointing at nothing.\n *\n * An author's own poster is never touched here. It wins at render time\n * instead (`videoPosterSrc`), so re-picking the SOURCE cannot quietly replace\n * a frame somebody chose.\n *\n * @returns the props to spread, or `{}` when the caller should write nothing.\n */\nexport function videoMediaProps(options: {\n  /** The element being written to — its persisted component id. */\n  componentId?: unknown\n  /** The attribute the picker was opened for; only `src` carries a video. */\n  propName?: unknown\n  /**\n   * The chosen asset's `video` record, as {@link normalizeVideoMetadata}\n   * bounds it — `durationMs`, `width` and `height`, all three or none.\n   */\n  assetVideo?: unknown\n  /** The chosen asset's generated `poster` record, when it has one. */\n  assetPoster?: unknown\n}): {\n  durationSeconds?: number\n  intrinsicWidth?: number\n  intrinsicHeight?: number\n  posterFromSource?: boolean\n} {\n  const { componentId, propName, assetVideo, assetPoster } = options ?? {}\n  if (propName !== 'src') return {}\n  if (String(componentId ?? '') !== VIDEO_COMPONENT_ID) return {}\n  const patch: {\n    durationSeconds?: number\n    intrinsicWidth?: number\n    intrinsicHeight?: number\n    posterFromSource?: boolean\n  } = {}\n  // Through the DAM's own validator rather than a second reading of the same\n  // three numbers: it is all-or-nothing by design, and re-deriving that rule\n  // here is how two files come to disagree about what a partial record means.\n  const video = normalizeVideoMetadata(assetVideo)\n  if (video) {\n    // Never rounds to zero: a sub-second clip is still a clip, and a stored\n    // `0` reads as \"no duration\" to everything downstream.\n    patch.durationSeconds = Math.max(1, Math.round(video.durationMs / 1000))\n    patch.intrinsicWidth = video.width\n    patch.intrinsicHeight = video.height\n  }\n  // A poster RECORD, not a poster url — see the note above. Its mere presence\n  // on the document is the whole fact being carried.\n  if (assetPoster && typeof assetPoster === 'object') {\n    patch.posterFromSource = true\n  }\n  return patch\n}\n\nexport interface ImageDimensions {\n  width: number\n  height: number\n}\n\nconst readU32BE = (bytes: Uint8Array, offset: number) =>\n  (bytes[offset] << 24) |\n  (bytes[offset + 1] << 16) |\n  (bytes[offset + 2] << 8) |\n  bytes[offset + 3]\n\nconst readU16BE = (bytes: Uint8Array, offset: number) =>\n  (bytes[offset] << 8) | bytes[offset + 1]\n\nconst readU16LE = (bytes: Uint8Array, offset: number) =>\n  bytes[offset] | (bytes[offset + 1] << 8)\n\n/**\n * Reads pixel dimensions from PNG, JPEG, GIF, and WebP headers. Returns\n * null for anything unrecognized or truncated — callers treat dimensions\n * as best-effort metadata, never a gate.\n */\nexport function readImageDimensions(\n  bytes: Uint8Array,\n): ImageDimensions | null {\n  if (bytes.length < 24) return null\n\n  // PNG: 8-byte signature, IHDR width/height at offsets 16/20.\n  if (\n    bytes[0] === 0x89 &&\n    bytes[1] === 0x50 &&\n    bytes[2] === 0x4e &&\n    bytes[3] === 0x47\n  ) {\n    const width = readU32BE(bytes, 16)\n    const height = readU32BE(bytes, 20)\n    return width > 0 && height > 0 ? { width, height } : null\n  }\n\n  // GIF87a/GIF89a: little-endian dimensions at offsets 6/8.\n  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) {\n    const width = readU16LE(bytes, 6)\n    const height = readU16LE(bytes, 8)\n    return width > 0 && height > 0 ? { width, height } : null\n  }\n\n  // JPEG: scan segments for a SOFn marker (C0–CF except C4/C8/CC).\n  if (bytes[0] === 0xff && bytes[1] === 0xd8) {\n    let offset = 2\n    while (offset + 9 < bytes.length) {\n      if (bytes[offset] !== 0xff) {\n        offset += 1\n        continue\n      }\n      const marker = bytes[offset + 1]\n      if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9)) {\n        offset += 2\n        continue\n      }\n      const length = readU16BE(bytes, offset + 2)\n      if (\n        marker >= 0xc0 &&\n        marker <= 0xcf &&\n        marker !== 0xc4 &&\n        marker !== 0xc8 &&\n        marker !== 0xcc\n      ) {\n        const height = readU16BE(bytes, offset + 5)\n        const width = readU16BE(bytes, offset + 7)\n        return width > 0 && height > 0 ? { width, height } : null\n      }\n      if (length < 2) return null\n      offset += 2 + length\n    }\n    return null\n  }\n\n  // WebP: RIFF....WEBP then VP8/VP8L/VP8X chunk.\n  if (\n    bytes[0] === 0x52 &&\n    bytes[1] === 0x49 &&\n    bytes[2] === 0x46 &&\n    bytes[3] === 0x46 &&\n    bytes[8] === 0x57 &&\n    bytes[9] === 0x45 &&\n    bytes[10] === 0x42 &&\n    bytes[11] === 0x50\n  ) {\n    const chunk = String.fromCharCode(\n      bytes[12],\n      bytes[13],\n      bytes[14],\n      bytes[15],\n    )\n    if (chunk === 'VP8X' && bytes.length >= 30) {\n      const width = 1 + (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16))\n      const height = 1 + (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16))\n      return { width, height }\n    }\n    if (chunk === 'VP8 ' && bytes.length >= 30) {\n      const width = readU16LE(bytes, 26) & 0x3fff\n      const height = readU16LE(bytes, 28) & 0x3fff\n      return width > 0 && height > 0 ? { width, height } : null\n    }\n    if (chunk === 'VP8L' && bytes.length >= 25) {\n      const bits =\n        bytes[21] | (bytes[22] << 8) | (bytes[23] << 16) | (bytes[24] << 24)\n      const width = (bits & 0x3fff) + 1\n      const height = ((bits >> 14) & 0x3fff) + 1\n      return { width, height }\n    }\n  }\n\n  return null\n}\n\n/**\n * What the platform knows about a VIDEO asset (AGL-2742).\n *\n * ## Why this is not `width`/`height` on the document beside an image's\n *\n * An image's dimensions are read from its own header by\n * {@link readImageDimensions}, server-side, from bytes the platform holds.\n * None of that is available for video: the dimensions live in a `moov` atom\n * that an MP4 is free to place at the END of the file, so reading them\n * server-side means fetching up to 200 MB back out of Storage to answer a\n * question worth twelve bytes — the exact download `generateStoredMediaVariants`\n * is written to avoid. So these numbers arrive from the BROWSER, which had\n * the file in hand and a decoder already loaded, and they are consequently\n * client data: every field is bounded here before it reaches a document.\n *\n * They live under their own key rather than widening `width`/`height`\n * because the provenance differs and a reader should be able to tell. A\n * `width` on a media document means \"measured from the bytes\"; a\n * `video.width` means \"reported by the uploader's browser\". Folding the two\n * together would make the weaker claim indistinguishable from the stronger\n * one on every asset in the library.\n */\nexport interface MediaVideoMetadata {\n  /** Duration in whole milliseconds. Always finite and positive. */\n  durationMs: number\n  /** Coded frame width in pixels, after any display-aspect correction. */\n  width: number\n  height: number\n  /**\n   * A short label for what produced the file, when the browser offered one\n   * (`video/mp4; codecs=\"avc1.640028\"` collapses to `avc1.640028`). Absent\n   * far more often than present — no browser API reports the codec of a\n   * local file, so this is only ever filled from a `MediaCapabilities` probe\n   * or a container sniff, and nothing depends on it.\n   */\n  codec?: string\n}\n\n/**\n * The upper bound on a stored duration: 24 hours.\n *\n * Not a policy about what may be uploaded — the DAM's ceiling is 200 MB of\n * bytes and says nothing about running time. This is the bound past which a\n * number stops being a duration and starts being a bug, and the specific\n * bug it exists for is real: `HTMLMediaElement.duration` is `Infinity` for a\n * stream and for some WebM files until the element has been seeked to the\n * end. `Infinity` fails the finite test below before it reaches this\n * constant, but a browser that reports a plausible-looking 10^12 instead\n * would otherwise write a document claiming a 31-year film.\n */\nexport const MEDIA_VIDEO_MAX_DURATION_MS = 24 * 60 * 60 * 1000\n\n/** The largest coded dimension accepted, matching the 8K ceiling encoders use. */\nexport const MEDIA_VIDEO_MAX_DIMENSION = 16384\n\n/**\n * Bound a browser's report into something safe to store, or refuse it whole.\n *\n * All-or-nothing on purpose. A partial record — a duration with no\n * dimensions — is worse than none: `VideoObject` JSON-LD would emit a\n * `duration` and omit `width`, and a renderer sizing its container from\n * `video.height` would find the key present and the value absent. The three\n * numbers are produced by one `loadedmetadata` event and are meaningful only\n * together, so they are accepted or rejected together.\n *\n * `codec` is the exception and is dropped rather than refused, for the same\n * reason `formatMediaRef` drops a malformed content pin: it is a label\n * nothing branches on, and losing the whole record over it would trade a\n * working poster and a correct aspect ratio for a cosmetic string.\n */\nexport function normalizeVideoMetadata(\n  input: unknown,\n): MediaVideoMetadata | null {\n  if (!input || typeof input !== 'object') return null\n  const source = input as Record<string, unknown>\n  const durationMs = Math.round(Number(source['durationMs']))\n  const width = Math.round(Number(source['width']))\n  const height = Math.round(Number(source['height']))\n  if (!Number.isFinite(durationMs) || durationMs <= 0) return null\n  if (durationMs > MEDIA_VIDEO_MAX_DURATION_MS) return null\n  if (!Number.isFinite(width) || width <= 0 || width > MEDIA_VIDEO_MAX_DIMENSION)\n    return null\n  if (\n    !Number.isFinite(height) ||\n    height <= 0 ||\n    height > MEDIA_VIDEO_MAX_DIMENSION\n  )\n    return null\n  const rawCodec = source['codec']\n  const codec =\n    typeof rawCodec === 'string' && /^[\\w.,\\- ]{1,64}$/.test(rawCodec.trim())\n      ? rawCodec.trim()\n      : undefined\n  return codec ? { durationMs, width, height, codec } : { durationMs, width, height }\n}\n\n/**\n * The `duration` a schema.org `VideoObject` wants: an ISO 8601 duration.\n *\n * Whole seconds, and never a fractional component. Google's structured-data\n * documentation accepts `PT1M30S` and treats sub-second precision as noise,\n * and a `PT1M30.437S` in a rich result is a number nobody asked for. A\n * duration under one second rounds UP to `PT1S` rather than to `PT0S`, which\n * would read as \"no duration\" to a consumer that tests for truthiness.\n */\nexport function videoDurationIso8601(\n  durationMs: number | undefined | null,\n): string | undefined {\n  const total = Math.max(1, Math.round(Number(durationMs) / 1000))\n  if (!Number.isFinite(total)) return undefined\n  if (!durationMs || Number(durationMs) <= 0) return undefined\n  const hours = Math.floor(total / 3600)\n  const minutes = Math.floor((total % 3600) / 60)\n  const seconds = total % 60\n  const parts = [\n    hours ? `${hours}H` : '',\n    minutes ? `${minutes}M` : '',\n    seconds ? `${seconds}S` : '',\n  ].join('')\n  return `PT${parts || '0S'}`\n}\n"],"names":["MEDIA_ALT_MAX_LENGTH","MEDIA_TAG_MAX_COUNT","MEDIA_TAG_MAX_LENGTH","normalizeMediaTags","input","raw","Array","isArray","String","split","seen","Set","tags","entry","tag","trim","toLowerCase","length","has","add","push","inheritedMediaAlt","options","placementAlt","decorative","assetAlt","undefined","inherited","slice","INTRINSIC_SIZE_COMPONENT_IDS","intrinsicMediaSize","componentId","propName","assetWidth","assetHeight","usable","value","Number","isFinite","intrinsicWidth","intrinsicHeight","VIDEO_COMPONENT_ID","videoMediaProps","assetVideo","assetPoster","patch","video","normalizeVideoMetadata","durationSeconds","Math","max","round","durationMs","width","height","posterFromSource","readU32BE","bytes","offset","readU16BE","readU16LE","readImageDimensions","marker","chunk","fromCharCode","bits","MEDIA_VIDEO_MAX_DURATION_MS","MEDIA_VIDEO_MAX_DIMENSION","source","rawCodec","codec","test","videoDurationIso8601","total","hours","floor","minutes","seconds","parts","join"],"mappings":"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"}

package/src/lib/app-utils/media-picker-context.d.ts

@@ -0,0 +1,93 @@
+export interface PickedMedia {
+    /**
+     * The chosen asset's URL — use for image `src` props.
+     *
+     * Already resolved by the provider, which prefers the media-id-keyed CDN
+     * path over the raw storage download URL (AGL-1215): the raw form names
+     * the object's current location and dies on a folder move.
+     */
+    url: string;
+    /** Original file name, when the source exposes it (e.g. digital files). */
+    fileName?: string;
+    /** MIME type, when known. */
+    contentType?: string;
+    /**
+     * The asset's own alt text, as authored in the media library (AGL-1896).
+     *
+     * Carried so a placement can DEFAULT from the asset instead of asking the
+     * author to retype it — the same logo on eight pages had its alt typed
+     * eight times, and in practice shipped blank on published customer sites.
+     * Absent for every asset whose alt has never been filled in; there is no
+     * fallback to {@link fileName}, deliberately. A file name is not a
+     * description, and "IMG_4021.jpg" read aloud by a screen reader is worse
+     * than the silence it replaces.
+     *
+     * Consumers must not read this directly into a stored field. Pass it to
+     * `inheritedMediaAlt` with whatever the placement already holds, so the
+     * per-placement override keeps winning.
+     */
+    alt?: string;
+    /**
+     * The chosen asset's media DOCUMENT id (AGL-2662).
+     *
+     * For the callers that store a reference rather than a placement: a CRM
+     * record's attachments are ids, so a file moved between folders keeps its
+     * attachment and a private asset is still served through the signed CDN
+     * door. Absent for a source that has no document behind it.
+     */
+    mediaId?: string;
+    /**
+     * The CDN scope the id resolves under — `org:{orgId}` for the shared
+     * library, a host id for a site's own. Carried beside {@link mediaId}
+     * because an id alone cannot be turned back into a URL.
+     */
+    mediaScope?: string;
+    /**
+     * Whether the chosen asset is PRIVATE (AGL-2814): fetchable only through a
+     * signed, expiring link, so {@link url} holds its media reference rather
+     * than an address a browser could load. Only a caller that opened the
+     * picker with `allowPrivate` ever receives one.
+     */
+    private?: boolean;
+}
+/**
+ * The one kind of file a picker can be narrowed to (AGL-2953).
+ *
+ * These are the values of the media library's own Type filter, not a second
+ * vocabulary: a narrowed picker is the library with that filter fixed, so the
+ * two cannot disagree about what counts as a video. `image` and `video` are
+ * whole families; `pdf` is PDF alone, as the filter offers it.
+ */
+export type MediaPickerKind = 'image' | 'video' | 'pdf';
+/** How a caller wants the picker to behave. */
+export interface PickMediaOptions {
+    /**
+     * Accept a PRIVATE asset instead of refusing it (AGL-2814).
+     *
+     * For a caller that delivers the file through a signed link it mints per
+     * request — a product's members video — and never places it on a page,
+     * which a private asset cannot be.
+     */
+    allowPrivate?: boolean;
+    /**
+     * List and upload only this kind of file (AGL-2953), for a field that can
+     * hold nothing else — a video source offers no images or PDFs to choose
+     * and takes no image as an upload. Absent, the picker offers every file
+     * the library holds.
+     */
+    kind?: MediaPickerKind;
+}
+/**
+ * Lets a relocated plugin console page open the console's media browser
+ * without importing it. The console app provides `pickMedia` (it owns the
+ * media library, which is coupled to the org/session context); plugin
+ * components call it and receive the chosen asset — or `null` if cancelled.
+ * Absent (undefined `pickMedia`) when no provider is mounted, so callers
+ * fall back to a plain URL input.
+ */
+export interface MediaPickerContextValue {
+    pickMedia?: (options?: PickMediaOptions) => Promise<PickedMedia | null>;
+}
+export declare const MediaPickerContext: import("react").Context<MediaPickerContextValue>;
+/** Hook form of {@link MediaPickerContext}. */
+export declare function useMediaPicker(): MediaPickerContextValue;

package/src/lib/app-utils/media-picker-context.js

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ // Same placement rationale as entity-picker-context.ts: lives in
+// @aglyn/aglyn without a 'use client' banner so both the console app and
+// relocated feature plugins share one context module.
+import { createContext, useContext } from "react";
+export const MediaPickerContext = createContext({});
+MediaPickerContext.displayName = 'MediaPickerContext';
+/** Hook form of {@link MediaPickerContext}. */ export function useMediaPicker() {
+    return useContext(MediaPickerContext);
+}
+
+//# sourceMappingURL=media-picker-context.js.map

package/src/lib/app-utils/media-picker-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/media-picker-context.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n// Same placement rationale as entity-picker-context.ts: lives in\n// @aglyn/aglyn without a 'use client' banner so both the console app and\n// relocated feature plugins share one context module.\nimport { createContext, useContext } from 'react'\n\nexport interface PickedMedia {\n  /**\n   * The chosen asset's URL — use for image `src` props.\n   *\n   * Already resolved by the provider, which prefers the media-id-keyed CDN\n   * path over the raw storage download URL (AGL-1215): the raw form names\n   * the object's current location and dies on a folder move.\n   */\n  url: string\n  /** Original file name, when the source exposes it (e.g. digital files). */\n  fileName?: string\n  /** MIME type, when known. */\n  contentType?: string\n  /**\n   * The asset's own alt text, as authored in the media library (AGL-1896).\n   *\n   * Carried so a placement can DEFAULT from the asset instead of asking the\n   * author to retype it — the same logo on eight pages had its alt typed\n   * eight times, and in practice shipped blank on published customer sites.\n   * Absent for every asset whose alt has never been filled in; there is no\n   * fallback to {@link fileName}, deliberately. A file name is not a\n   * description, and \"IMG_4021.jpg\" read aloud by a screen reader is worse\n   * than the silence it replaces.\n   *\n   * Consumers must not read this directly into a stored field. Pass it to\n   * `inheritedMediaAlt` with whatever the placement already holds, so the\n   * per-placement override keeps winning.\n   */\n  alt?: string\n  /**\n   * The chosen asset's media DOCUMENT id (AGL-2662).\n   *\n   * For the callers that store a reference rather than a placement: a CRM\n   * record's attachments are ids, so a file moved between folders keeps its\n   * attachment and a private asset is still served through the signed CDN\n   * door. Absent for a source that has no document behind it.\n   */\n  mediaId?: string\n  /**\n   * The CDN scope the id resolves under — `org:{orgId}` for the shared\n   * library, a host id for a site's own. Carried beside {@link mediaId}\n   * because an id alone cannot be turned back into a URL.\n   */\n  mediaScope?: string\n  /**\n   * Whether the chosen asset is PRIVATE (AGL-2814): fetchable only through a\n   * signed, expiring link, so {@link url} holds its media reference rather\n   * than an address a browser could load. Only a caller that opened the\n   * picker with `allowPrivate` ever receives one.\n   */\n  private?: boolean\n}\n\n/**\n * The one kind of file a picker can be narrowed to (AGL-2953).\n *\n * These are the values of the media library's own Type filter, not a second\n * vocabulary: a narrowed picker is the library with that filter fixed, so the\n * two cannot disagree about what counts as a video. `image` and `video` are\n * whole families; `pdf` is PDF alone, as the filter offers it.\n */\nexport type MediaPickerKind = 'image' | 'video' | 'pdf'\n\n/** How a caller wants the picker to behave. */\nexport interface PickMediaOptions {\n  /**\n   * Accept a PRIVATE asset instead of refusing it (AGL-2814).\n   *\n   * For a caller that delivers the file through a signed link it mints per\n   * request — a product's members video — and never places it on a page,\n   * which a private asset cannot be.\n   */\n  allowPrivate?: boolean\n  /**\n   * List and upload only this kind of file (AGL-2953), for a field that can\n   * hold nothing else — a video source offers no images or PDFs to choose\n   * and takes no image as an upload. Absent, the picker offers every file\n   * the library holds.\n   */\n  kind?: MediaPickerKind\n}\n\n/**\n * Lets a relocated plugin console page open the console's media browser\n * without importing it. The console app provides `pickMedia` (it owns the\n * media library, which is coupled to the org/session context); plugin\n * components call it and receive the chosen asset — or `null` if cancelled.\n * Absent (undefined `pickMedia`) when no provider is mounted, so callers\n * fall back to a plain URL input.\n */\nexport interface MediaPickerContextValue {\n  pickMedia?: (options?: PickMediaOptions) => Promise<PickedMedia | null>\n}\n\nexport const MediaPickerContext = createContext<MediaPickerContextValue>({})\nMediaPickerContext.displayName = 'MediaPickerContext'\n\n/** Hook form of {@link MediaPickerContext}. */\nexport function useMediaPicker(): MediaPickerContextValue {\n  return useContext(MediaPickerContext)\n}\n"],"names":["createContext","useContext","MediaPickerContext","displayName","useMediaPicker"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD,iEAAiE;AACjE,yEAAyE;AACzE,sDAAsD;AACtD,SAASA,aAAa,EAAEC,UAAU,QAAQ,QAAO;AAgGjD,OAAO,MAAMC,qBAAqBF,cAAuC,CAAC,GAAE;AAC5EE,mBAAmBC,WAAW,GAAG;AAEjC,6CAA6C,GAC7C,OAAO,SAASC;IACd,OAAOH,WAAWC;AACpB"}

package/src/lib/app-utils/media-quarantine.d.ts

@@ -0,0 +1,247 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Why a file was disabled. Deliberately NOT `LockdownReasonCode`: the
+ * lockdown vocabulary (security / billing / maintenance / manual) cannot
+ * say "DMCA", and a takedown recorded as "security" is a record that
+ * cannot answer the only question anyone asks about it a year later.
+ *
+ * The field FAMILY around it is AGL-1501's, unchanged — `reason`,
+ * `message`, `atMs`, `untilMs`, `actorUid` — so an operator reading an
+ * audit row is reading the same shape either way.
+ */
+export type MediaQuarantineReason = 'malware' | 'abuse' | 'dmca' | 'legal' | 'manual';
+export declare const MEDIA_QUARANTINE_REASONS: MediaQuarantineReason[];
+export declare function isMediaQuarantineReason(value: unknown): value is MediaQuarantineReason;
+/** Staff-surface labels; the key stays the wire/API identity. */
+export declare const MEDIA_QUARANTINE_REASON_LABELS: Record<MediaQuarantineReason, string>;
+export declare const MEDIA_QUARANTINES_COLLECTION = "mediaQuarantines";
+/**
+ * The single deny-list document. One document, one read, whole feature —
+ * see the read-cost argument in the module header.
+ */
+export declare const MEDIA_QUARANTINE_INDEX_DOC_ID = "index";
+/** The map field inside that document: quarantine key → entry. */
+export declare const MEDIA_QUARANTINE_ENTRIES_FIELD = "entries";
+/**
+ * How many entries one index document may hold.
+ *
+ * A Firestore document caps at 1 MiB and an entry is a few hundred bytes,
+ * so the real ceiling is thousands — this cap is far below it on purpose.
+ * The write path REFUSES past it rather than growing a document that would
+ * one day fail to write, because the failure mode of an over-full deny list
+ * is "a takedown silently did not land", which is the exact thing this
+ * mechanism exists to prevent. Sharding is a filed follow-up, not a
+ * surprise.
+ */
+export declare const MEDIA_QUARANTINE_MAX_ENTRIES = 2000;
+/** Staff-typed notice text is owner-facing; keep it bounded and plain. */
+export declare const MEDIA_QUARANTINE_MESSAGE_MAX = 500;
+/** Internal staff rationale — never shown to the customer. */
+export declare const MEDIA_QUARANTINE_NOTE_MAX = 1000;
+/**
+ * A quarantine key derived from a content digest — either the strong
+ * `contentSha256` or the legacy truncated `contentHash`. One key space on
+ * purpose: an entry set from either field is looked up by
+ * {@link mediaQuarantineKeys}, so widening the digest never stranded a
+ * takedown that was already in force.
+ *
+ * **What the LEGACY field promises, and what it does not** (AGL-1614).
+ * `contentHash` is a 16-hex character (64-bit) TRUNCATED digest, and it is
+ * produced by two different algorithms depending on which route ingested the
+ * bytes: sha256 for the server-side upload and replace routes, GCS's md5 for
+ * the signed-upload route. Two consequences, both stated rather than hidden:
+ *
+ *  1. The same bytes uploaded through DIFFERENT routes do not share a
+ *     `contentHash`, so "re-uploading the same file stays quarantined"
+ *     holds within an ingestion path, not across all of them. This is NOT
+ *     fixed by `contentSha256` and cannot be: the signed-upload route never
+ *     holds the bytes, and GCS computes only md5 and crc32c.
+ *  2. 64 truncated bits is collision-resistant by accident, not by design.
+ *     An unrelated asset colliding by chance is negligible at this scale;
+ *     an asset colliding by CONSTRUCTION is reachable — cheaply so on the
+ *     md5-derived half, where a chosen-prefix collision produces two files
+ *     with the same full digest and therefore the same truncation. The
+ *     consequence is bounded: a collision can only ever cause MORE refusal,
+ *     never less, so it is an availability bug and never a disclosure one.
+ *
+ * `contentSha256` has neither the truncation nor the md5 property, which is
+ * why {@link mediaQuarantineKeys} prefers it. The key is normalized to lower
+ * case so a hand-entered hash from a staff form cannot miss its own record.
+ */
+export declare function mediaQuarantineHashKey(contentHash: string): string;
+/**
+ * The per-asset fallback key, for documents that carry no `contentHash`.
+ * Scope-qualified because a media id is only unique within its own
+ * `orgs/{id}` or `hosts/{id}` library.
+ */
+export declare function mediaQuarantineAssetKey(scopeSegment: string, mediaId: string): string;
+/**
+ * THE key for one asset: its content hash when it has one, its identity
+ * when it does not. `null` is impossible in practice (a media id always
+ * exists) and returned anyway rather than emitting a key like
+ * `asset----`, which would be a deny-list entry matching nothing and
+ * looking like it matched everything.
+ */
+export declare function mediaQuarantineKey(asset: {
+    contentSha256?: string | null;
+    contentHash?: string | null;
+    scopeSegment?: string | null;
+    mediaId?: string | null;
+}): string | null;
+/**
+ * EVERY key that may refuse this asset, in preference order and without
+ * duplicates. Any one of them matching an active entry is a refusal.
+ *
+ * The list, rather than {@link mediaQuarantineKey}'s single answer, is what
+ * makes AGL-1614's stronger digest safe to introduce. A media document may
+ * now carry BOTH a `contentSha256` and the legacy truncated `contentHash`,
+ * and quarantine entries in force were keyed on whichever field existed when
+ * staff pressed the button. Checking only the preferred key would mean a
+ * live takedown, keyed on the legacy hash, silently stops biting the moment
+ * an asset gains a strong one — a takedown lifting itself is the single
+ * worst failure this lever can have, so the legacy key is never dropped.
+ *
+ * The per-asset key stays in the list for the same reason it was added in
+ * AGL-1512: an entry set while a document had no hash at all must keep
+ * biting after a replace gives it one. Checking all three costs nothing —
+ * the deny list is one already-in-memory map.
+ */
+export declare function mediaQuarantineKeys(asset: {
+    contentSha256?: string | null;
+    contentHash?: string | null;
+    scopeSegment?: string | null;
+    mediaId?: string | null;
+}): string[];
+/**
+ * One entry as stored in the index document's `entries` map.
+ *
+ * Every optional field is written as an explicit `null` rather than left
+ * off (the repo's standing Firestore rule — a converter or a partial write
+ * must never carry `undefined`), so a reader can distinguish "no expiry"
+ * from "this record predates expiry".
+ */
+export interface MediaQuarantineEntry {
+    reason: MediaQuarantineReason;
+    /** Owner-facing notice text; `null` uses the per-reason default copy. */
+    message?: string | null;
+    /** Staff-only rationale. NEVER rendered to the customer. */
+    note?: string | null;
+    atMs?: number | null;
+    /** Optional expiry — passing it restores delivery with no write. */
+    untilMs?: number | null;
+    actorUid?: string | null;
+    /**
+     * Where the quarantine was set FROM, for the audit trail only. A hash
+     * key can cover documents in many orgs; this records the one an operator
+     * was looking at, and is never used to decide whether to refuse.
+     */
+    originScopeSegment?: string | null;
+    originMediaId?: string | null;
+}
+/** The normalized, in-memory shape every consumer reads. */
+export interface MediaQuarantineState {
+    key: string;
+    reason: MediaQuarantineReason;
+    message?: string;
+    atMs?: number;
+    untilMs?: number;
+    actorUid?: string;
+}
+/**
+ * Entry → state. A malformed entry (no recognised reason) is refused
+ * WHOLE rather than defaulted, matching `normalizeLockdownDoc`: the
+ * takedown path does not guess, and a record nobody can explain is not a
+ * record anyone should enforce.
+ *
+ * `note` is deliberately not carried into the state — the staff rationale
+ * must not be able to reach a surface that renders `message`.
+ */
+export declare function normalizeMediaQuarantine(entry: Partial<MediaQuarantineEntry> | null | undefined, key: string): MediaQuarantineState | null;
+/**
+ * Active now? Expiry passing deactivates with no write — the same
+ * semantics as `isLockdownActive`, which this calls rather than restates
+ * so the two levers can never drift on what "expired" means.
+ */
+export declare function isMediaQuarantineActive(state: MediaQuarantineState | null | undefined, nowMs: number): boolean;
+export interface MediaQuarantineNotice {
+    title: string;
+    body: string;
+    contact?: string;
+}
+/**
+ * The address on the owner-facing quarantine notice, from operator
+ * configuration (AGL-2016).
+ *
+ * Was a `'support@aglyn.com'` literal. The notice is shown to the org that
+ * owns the asset, so on a self-host install it told the operator's OWN
+ * customer to write to Aglyn about a file Aglyn never stored — and only the
+ * operator's staff can lift the quarantine they applied.
+ */
+export declare function mediaQuarantineSupportEmail(): string | null;
+/**
+ * The OWNER-facing notice: "this file was disabled: {reason} — contact
+ * support". Shown in the console to the org that owns the asset, never on
+ * the CDN response (which stays a neutral 410 — see the refusal argument
+ * in `serve-media-cdn.ts`).
+ *
+ * A staff-typed `message` replaces the body; the title and the contact
+ * line stay per-reason so an operator cannot accidentally strip the "how
+ * do I get this back" affordance. Every body says the file still EXISTS —
+ * a customer whose asset is refused must not conclude their data was
+ * deleted, because for every reason here it was not.
+ */
+export declare function mediaQuarantineNotice(state: Pick<MediaQuarantineState, 'reason' | 'message'>): MediaQuarantineNotice;
+/**
+ * The status an INGESTION chokepoint refuses a quarantined upload with
+ * (AGL-1613).
+ *
+ * Deliberately NOT the CDN's 410 and NOT the lockdown's 423. The CDN answers
+ * an anonymous fetcher, so its refusal is neutral by design and says nothing
+ * about why. This caller is authenticated and is the OWNER of the bytes, so
+ * the AGL-1506 discipline applies in the other direction: they are told. And
+ * it is not 423, because 423 means "your workspace is locked" — a different
+ * lever with a different remedy, and a client that cannot tell them apart
+ * would send a customer to the wrong support conversation.
+ *
+ * 403 rather than 409: the request is understood, it is refused, and
+ * repeating it verbatim will not help. Nothing about the workspace state
+ * needs to change first.
+ */
+export declare const MEDIA_QUARANTINE_UPLOAD_STATUS = 403;
+/**
+ * The JSON an ingestion refusal answers with.
+ *
+ * `error` carries the notice BODY because that is the field every console
+ * upload surface already renders into its snackbar — a refusal whose
+ * explanation lands in a field nothing reads is a silent failure with extra
+ * steps. The structured fields ride alongside for a surface that wants to
+ * render the notice properly (AGL-1612).
+ *
+ * Built from {@link mediaQuarantineNotice}, which takes only `reason` and
+ * `message`. That is the containment for the staff `note`: it is dropped by
+ * `normalizeMediaQuarantine` before a state exists, and this function never
+ * sees a raw entry to reach past it into.
+ */
+export interface MediaQuarantineRefusalBody {
+    error: string;
+    quarantined: true;
+    title: string;
+    reason: MediaQuarantineReason;
+    contact: string | null;
+}
+export declare function mediaQuarantineRefusalBody(state: Pick<MediaQuarantineState, 'reason' | 'message'>): MediaQuarantineRefusalBody;