@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1,661 @@
+/**
+ * @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.
+ */
+export declare const MEDIA_CDN_ROUTE = "/api/media/cdn";
+/**
+ * The WebP variant widths generated at upload (AGL-175), and the widths a
+ * renderer may advertise in a `srcSet`.
+ *
+ * Here rather than beside the handler for the reason above: `serveMediaCdn`
+ * lives in a server-only lib that a plugin component cannot import, and the
+ * renderer needs the same list. It was duplicated as a bare `[320, 640, 1280]`
+ * literal in `libs/plugins/mui/.../image.tsx`, so a width added to the
+ * generator never reached the markup.
+ *
+ * ⚠️ 1920 EXISTS SO THE LARGEST CANDIDATE IS STILL A VARIANT (2026-08-26).
+ *
+ * The srcSet used to top out with the BARE url labelled `1920w` — the only
+ * candidate that is never WebP. With `sizes="100vw"` any retina desktop needs
+ * more effective pixels than 1280w offers, so that bare candidate is the one
+ * most desktop visitors actually download. Measured on aglyn.com's own
+ * assets: 335 KB / 305 KB / 164 KB PNG originals against 4 KB / 4 KB / 5 KB
+ * WebP at `?w=320` — and ~94% of a media serve is bandwidth (AGL-1442).
+ *
+ * `mediaVariantWidthsFor` names every width below the source, and for a JPEG
+ * or PNG the rest as WebP at the source's own width; `serveMediaCdn` serves
+ * the original for a width an asset does not have, so a missing variant
+ * degrades to exactly the bytes it served before.
+ *
+ * ⛔ EXISTING ASSETS KEEP THE VARIANTS THEY WERE UPLOADED WITH until a backfill
+ * runs — no regression, and no saving on them either. The backfill is a
+ * `sharp` pass over the corpus, a script and not a patch (AGL-1442 S7).
+ */
+export declare const MEDIA_CDN_VARIANT_WIDTHS: readonly [320, 640, 1280, 1920];
+/**
+ * The variant width a surface asks for when it can only ask for ONE.
+ *
+ * An `<img>` hands the browser {@link MEDIA_CDN_VARIANT_WIDTHS} and lets it
+ * choose. A `<video poster>` attribute and a `thumbnailUrl` in structured data
+ * each take a single url, so they have to name a width — and it has to be the
+ * SAME width, or a crawler fetching the thumbnail gets different bytes from
+ * the visitor looking at the poster. 1280 is the widest variant below a 1920
+ * original's own width.
+ */
+export declare const MEDIA_CDN_POSTER_WIDTH = 1280;
+/**
+ * Scheme of a stored media reference. Chosen so `startsWith` is a decision:
+ * no URL, path, or `{{binding}}` an author can type begins with it, and it
+ * is not a registered URL scheme, so a browser handed one by mistake fails
+ * loudly rather than fetching something.
+ */
+export declare const MEDIA_REF_PREFIX = "media:";
+/**
+ * What separates the media id from the optional content pin (AGL-2685).
+ *
+ * `@` because it cannot occur in either half: {@link SEGMENT_SOURCE} is
+ * `[A-Za-z0-9_-]`, so the FIRST `@` after the media id is unambiguously the
+ * boundary, and a reference written before pins existed contains none.
+ */
+export declare const MEDIA_REF_HASH_SEPARATOR = "@";
+/** A parsed reference. `scope` is the CDN scope segment, unencoded. */
+export interface MediaRef {
+    /** `{hostId}`, `org:{orgId}`, or `org:{orgId}:{hostId}`. */
+    scope: string;
+    mediaId: string;
+    /**
+     * The content pin, when the reference carries one (AGL-2685). Absent on
+     * every reference written before pins existed, which is the majority and
+     * stays correct forever.
+     */
+    contentHash?: string;
+}
+/** Whether a scope segment is one the CDN would accept. */
+export declare function isMediaCdnScope(scope: string): boolean;
+/**
+ * Mints the stored form. Returns undefined rather than emitting junk.
+ *
+ * A `contentHash` that does not fit the segment grammar is DROPPED rather
+ * than refused: the pin is an optimisation, and returning undefined for it
+ * would turn a bad hash into no reference at all — an image that stops
+ * rendering because a cache hint was malformed.
+ */
+export declare function formatMediaRef(scope: string | undefined | null, mediaId: string | undefined | null, contentHash?: string | undefined | null): string | undefined;
+/** Whether a persisted value is a media reference rather than a URL. */
+export declare function isMediaRef(value: unknown): value is string;
+/** Reads a stored reference apart; null when it isn't a well-formed one. */
+export declare function parseMediaRef(value: unknown): MediaRef | null;
+/**
+ * Whether a value is a media-library CDN **path** — exactly what the media
+ * picker writes (AGL-2286).
+ *
+ * `MediaUrlField`'s `onPick` hands back `media.cdnPath`, which is
+ * `/api/media/cdn/{scope}/{mediaId}` and is never absolute. Several save
+ * routes validated their URL field with a bare `^https://` test and so
+ * refused every asset their own Browse button could produce. AGL-2247 fixed
+ * that for the white-label branding profile with a private regex inside
+ * `apps/console/app/api/_lib/branding-url.ts`; this is that predicate
+ * promoted to the module that already owns the grammar, because the org
+ * profile logo and the member avatar had the same defect and live in a lib
+ * `apps/console` cannot be imported from.
+ *
+ * Deliberately NOT {@link isMediaCdnUrl}, which asks a different question
+ * with `includes()` and would answer yes to `https://evil.example/x/api/media/cdn/a/b`.
+ * A validator needs the strict form, so this mirrors {@link parseMediaRef}
+ * exactly — same first-slash boundary, same `isMediaCdnScope` and `SEGMENT`
+ * checks — rather than re-deriving a regex that could drift from the route
+ * the path is about to be served by.
+ */
+export declare function isMediaCdnPath(value: unknown): value is string;
+/**
+ * Rewrites an org scope so it names the site doing the rendering — the
+ * scope-segment twin of `hostQualifiedCdnPath` (AGL-1043).
+ *
+ * `org:{orgId}` serves ORG-WIDE assets only; an asset restricted to
+ * particular sites has to be asked for through `org:{orgId}:{hostId}`,
+ * because the CDN is unauthenticated and the URL is the only thing it can
+ * decide from. The qualified form is a superset — it also serves org-wide
+ * assets, since `visibleToHost` is true for `['org']` — so qualifying
+ * whenever a host is known is always safe and never needs `visibleTo`.
+ *
+ * It REPLACES an existing qualification rather than refusing to touch one.
+ * A baked-in host is the picker's best guess made where no site context
+ * existed; the site actually rendering the node is the better answer, and
+ * this is what lets one reference work in a reusable component or layout
+ * shared across several sites — the case a single stored URL can never
+ * cover.
+ */
+export declare function hostQualifiedScope(scope: string, hostId: string | undefined | null): string;
+export interface ResolveMediaSrcOptions {
+    /**
+     * Host doc id of the site being rendered. The tenant page has it on
+     * `SiteContext`; the besigner canvas and Preview do not, and pass nothing
+     * — which is exactly why the picker bakes its best guess into the stored
+     * scope (see {@link mediaNodeSrc}).
+     */
+    hostId?: string | null;
+}
+/**
+ * The render-time resolver every surface shares. Precedence, in order:
+ *
+ * 1. a **media reference** → the CDN URL for it, host-qualified if we know
+ *    which site is asking;
+ * 2. any other non-empty string → **itself, untouched**. That is the whole
+ *    back-compat story and it needs no migration to be correct: nodes
+ *    holding a raw `https://firebasestorage.googleapis.com/…` URL, nodes
+ *    holding an `/api/media/cdn/…` path written by the first pass,
+ *    and an author-typed external URL for a hotlinked image are all just
+ *    passed through;
+ * 3. empty/absent → undefined, so the caller shows its placeholder.
+ *
+ * A value that opens with `media:` but does not parse resolves to undefined
+ * rather than reaching an `<img src>`. There is no correct URL to emit for
+ * it, and a placeholder in the editor is a report; `src="media:junk"` is a
+ * console error nobody reads.
+ */
+export declare function resolveMediaSrc(value: string | undefined | null, options?: ResolveMediaSrcOptions): string | undefined;
+/**
+ * {@link resolveMediaSrc}, with an absolute FIRST-PARTY CDN URL folded back
+ * to the site-relative path that names the same bytes (AGL-1726).
+ *
+ * The resolver's pass-through branch is right for what it was written for —
+ * a raw storage URL and an author's hotlink are values we must not touch.
+ * But a stored `https://{subdomain}.aglyn.app/api/media/cdn/…` is neither.
+ * It is OUR route, addressed the long way round, and on a white-label
+ * storefront served from the customer's own domain it is:
+ *
+ * 1. a **brand leak** — the platform subdomain appears in page source and in
+ *    every visitor's request, on a site whose owner pays not to see it;
+ * 2. **cross-origin**, so `img-src 'self'` would blank it (this is the
+ *    AGL-1726 measurement, and fixing it unblocks that flip);
+ * 3. a dependency on `aglyn.app` resolving, on a page that otherwise has no
+ *    reason to need it.
+ *
+ * Dropping the origin is safe because `serveMediaCdn` decides from the URL
+ * and the document, never from the `Host` header — "the cache key IS the
+ * URL, one host's answer can never reach another" — and BOTH apps mount the
+ * route, so the console canvas and the tenant page each serve their own.
+ *
+ * ## Why this is a separate function and not a change to `resolveMediaSrc`
+ *
+ * Two consumers need the absolute form and would be harmed by folding this
+ * into the shared resolver:
+ *
+ * - {@link absoluteMediaSrc}'s out-of-band readers (`og:image`, the PWA
+ *   manifest, JSON-LD, an inbox). They re-absolutize against a stated
+ *   origin, so a value that no longer carries one returns undefined
+ *   wherever that origin is unknown.
+ * - `resolveEmailMediaSrc` in `shared-util-email`, a deliberate COPY of
+ *   `resolveMediaSrc` pinned by `apps/console/specs/email-media-src-drift.spec.ts`.
+ *   It cannot import this module (`scope:shared` is a leaf), so any change
+ *   to the authority has to be mirrored by hand — and a mirror of
+ *   {@link isFirstPartyHost}, which reads two environment variables, is the
+ *   AGL-2195 trap re-armed.
+ *
+ * So: the render-time resolver keeps its contract, and a surface that puts
+ * the result straight into an `<img src>` on a page asks for this instead.
+ */
+export declare function siteRelativeMediaSrc(value: string | undefined | null, options?: ResolveMediaSrcOptions): string | undefined;
+/**
+ * {@link resolveMediaSrc}, then made ABSOLUTE against a stated origin.
+ *
+ * Two of the three stored generations — a `media:` reference and the AGL-175
+ * relative CDN path — resolve site-RELATIVE, which is right for an `<img>` on
+ * a page and wrong for every consumer that reads the URL out of band: a
+ * crawler fetching `og:image` (AGL-1337), an inbox rendering a campaign
+ * (AGL-1224), an installer fetching a PWA manifest icon (AGL-1407). None of
+ * them has a page to resolve against, and the tenant app declares no
+ * `metadataBase`, so Next resolves nothing for us either.
+ *
+ * With no origin a relative value returns **undefined** rather than a
+ * relative URL — the rule the canonical and the RSS feed already follow
+ * (AGL-1160/AGL-1272): never interpolate an unknown origin, and never emit a
+ * URL that is well-formed but wrong. An absolute value is unaffected, so the
+ * author-typed external URL and the raw storage URL never depend on knowing
+ * the origin at all.
+ *
+ * A protocol-relative `//host/x.png` only lacks a scheme; it is given `https:`
+ * rather than an origin, which would corrupt it.
+ */
+export declare function absoluteMediaSrc(value: string | undefined | null, options?: ResolveMediaSrcOptions & {
+    origin?: string | null;
+}): string | undefined;
+/**
+ * Whether a resolved URL is served by our CDN, and therefore carries the
+ * generated WebP variants selected by `?w=`. Widths without a variant fall
+ * back to the original server-side, so a static srcSet is safe for any
+ * CDN-form URL — including the legacy stored paths, which is why this asks
+ * about the RESOLVED url rather than about the stored value.
+ */
+export declare function isMediaCdnUrl(url: string | undefined | null): boolean;
+/**
+ * One resolved URL at a chosen variant width (AGL-2741).
+ *
+ * `image.tsx` hands the browser the whole candidate list and lets it choose,
+ * which is right for an `<img>` and impossible everywhere else: a
+ * `<video poster>` attribute takes ONE url and no `srcset`, and so does a
+ * `thumbnailUrl` in structured data. Those callers still want the WebP variant
+ * rather than the 335 KB PNG original, and they have to name the width
+ * themselves.
+ *
+ * The width is only appended when the resolved url is a CDN one. A hotlinked
+ * image has no variants and no handler behind it, so a `?w=` there would be a
+ * query string on somebody else's server; a width the asset has no variant for
+ * falls back to the original server-side, so this is safe on any CDN-form url
+ * and on an asset whose variants were never generated.
+ *
+ * Shared rather than restated at each call site because a poster attribute and
+ * the `thumbnailUrl` describing it must name the SAME bytes — two spellings of
+ * "resolve the poster" is how those drift apart.
+ *
+ * The width MERGES into a query the url already carries (AGL-2958). A film's
+ * captured frame is `?poster=1` on the film's own url and a signed private
+ * asset carries `exp`/`sig`, and both are values an image or poster field can
+ * hold. A bare `?w=` append turns the first into `?poster=1?w=640`, which the
+ * CDN reads as a `poster` of `1?w=640` — not a request for the still, and no
+ * width either — so it answers with the master film. `image.tsx` builds every
+ * `srcSet` candidate through here for the same reason.
+ */
+export declare function mediaVariantSrc(value: unknown, options: ResolveMediaSrcOptions & {
+    width: number;
+}): string | undefined;
+/**
+ * The whole candidate list for an `<img>`: every width in
+ * {@link MEDIA_CDN_VARIANT_WIDTHS} as a `?w=` url, or `undefined` for a url
+ * that is not ours and therefore has no variants to offer.
+ *
+ * Takes the RESOLVED url, like {@link isMediaCdnUrl} and for the same reason:
+ * a `media:` reference and a legacy stored path both keep their WebP variants,
+ * while a hotlinked image gets nothing rather than a `?w=` on somebody else's
+ * server. Each candidate goes through {@link mediaVariantSrc} so the width
+ * MERGES into a query the url already carries (AGL-2958) instead of being
+ * appended after one.
+ *
+ * Shared rather than restated because three surfaces render a library image —
+ * the Image element, a Markdown body and a collection entry's body — and the
+ * two body renderers shipped with no `srcSet` at all for exactly as long as
+ * this list lived inside `image.tsx` (AGL-3149). A fourth copy is how the
+ * next one drifts.
+ *
+ * ⚠️ `srcSet` alone is not a delivery-only change. With `w` descriptors the
+ * browser derives the image's density-corrected intrinsic size from `sizes`,
+ * so an `<img>` carrying this list and no intrinsic `width`/`height` pair
+ * renders at `sizes` rather than at its own size — measured, a 320px asset in
+ * a 712px column jumped to 668px. Hand it the pair, or hand it an explicit CSS
+ * width, but do not hand it this list alone.
+ */
+export declare function mediaCdnSrcSet(src: string | undefined | null): string | undefined;
+/**
+ * Every sizing attribute an image inside authored PROSE should carry, given
+ * what the composition could learn about the asset (AGL-3149).
+ *
+ * A body image differs from an Image element in the one way that matters here:
+ * nobody sets its CSS width. It is laid out by `max-width: 100%` and its own
+ * intrinsic size, so the attributes below are what decide both its box and its
+ * bytes, and they only work as a set:
+ *
+ * - `width`/`height` map to presentational-hint CSS `width`, which
+ *   `max-width: 100%` then caps — so the rendered width is
+ *   `min(natural, column)`. That is the growth the issue asked for, and it is
+ *   also what stops `sizes` deciding the size (see {@link mediaCdnSrcSet}).
+ *   The renderer MUST pair them with `height: auto`, or the height hint
+ *   survives the width cap and the picture is squashed.
+ * - `sizes` is then only a delivery hint, and it is derived from the pair
+ *   rather than from the column: an image narrower than the column renders at
+ *   its own width, so describing the column would fetch a candidate several
+ *   times larger than the slot. Measured, a 320px asset under a fixed
+ *   `sizes="712px"` fetched `?w=1280`; under its own width it fetches `?w=320`.
+ *
+ * WITHOUT a pair this returns the resolved `src` and NOTHING else — today's
+ * markup exactly. That is deliberate: `srcSet` without the pair would upscale
+ * every image narrower than the column, so an asset the facts read cannot
+ * answer for (a hotlink, an SVG the upload could not measure, one past the
+ * composition's cap) must come out unchanged rather than half-improved.
+ */
+export declare function mediaBodyImageAttributes(options: {
+    /** The target as the body wrote it: a `media:` reference or a plain url. */
+    src: unknown;
+    hostId?: string;
+    /** The asset's pixel pair, when the composition could read one. */
+    size?: {
+        width: number;
+        height: number;
+    } | undefined;
+}): {
+    src: string | undefined;
+    srcSet?: string;
+    sizes?: string;
+    width?: number;
+    height?: number;
+};
+export declare function isFirstPartyHost(hostname: string): boolean;
+/**
+ * Whether a stored image `src` names media WE serve (AGL-1701).
+ *
+ * The predicate an authoring surface validates against when the person
+ * supplying the value is not the person who will render it. A marketplace
+ * publisher types a listing logo; every OTHER org's users load it. An `<img>`
+ * on a host the publisher controls is a beacon — it discloses each viewer's
+ * IP, user-agent and a `Referer` naming the console and the org, on every
+ * render, to a recipient who appears on no subprocessor register. That is a
+ * disclosure question, and the answer is not to name the host in a policy;
+ * it is to stop accepting the host.
+ *
+ * Three accepted forms, in descending order of how much we like them:
+ *
+ * 1. a `media:` reference — names the asset, survives a move or a replace;
+ * 2. a root-relative path under {@link MEDIA_CDN_ROUTE} — same-origin, so
+ *    `img-src 'self'` covers it with no allowlist entry at all;
+ * 3. an absolute `https:` URL on a first-party host. Two sub-cases, and both
+ *    are what the DAM picker actually emits today: `mediaSrc` prefixes
+ *    `window.location.origin` onto `cdnPath` because a listing renders
+ *    somewhere other than the console, and it falls back to the raw storage
+ *    download URL when the org has no CDN entitlement.
+ *
+ * `http:` is refused in every form, and so is protocol-relative `//host` —
+ * which `new URL` would resolve against a base we do not have here, and which
+ * on a page is simply the same egress with the scheme borrowed.
+ *
+ * KNOWN GAP, stated rather than papered over: an org with a white-label
+ * `customConsoleDomain` would have `mediaSrc` emit that domain, which this
+ * refuses. Inert today — AGL-743 leaves the claim `pending` and nothing
+ * routes on it — and the fix when it does route is to resolve the claim here,
+ * not to widen the apex list.
+ */
+export declare function isFirstPartyMediaSrc(value: unknown): value is string;
+/**
+ * Reads a reference back out of a CDN path — how the picker mints one from
+ * the `cdnPath` the server already wrote on the media doc, so nothing new
+ * has to be plumbed through the media APIs.
+ *
+ * A content-hashed path (`…/{mediaId}/{hash}`) yields the reference for the
+ * asset it names, and the hash is discarded: a reference names the ASSET, so
+ * that a replace reaches it (AGL-2798).
+ */
+export declare function mediaRefFromCdnPath(cdnPath: string | undefined | null): string | undefined;
+/**
+ * Matches every stored reference to ONE asset, whatever scope form it
+ * carries — host library, bare org, or host-qualified org.
+ *
+ * The where-used scan (AGL-833/AGL-1045) answers "what breaks if I move,
+ * restrict or delete this?" by looking for the asset's URL inside serialized
+ * documents. A reference contains neither the storage URL nor the CDN path,
+ * so without this it would report an asset as used nowhere — and the scope
+ * confirmation that quotes those results would tell an author it is safe to
+ * restrict an asset that is on a live page. Enumerating the org's hosts to
+ * build one needle per site would work and would silently under-report the
+ * moment a scan skipped a host; one pattern cannot.
+ *
+ * Deliberately not anchored to a quote: it must find a reference wherever it
+ * was serialized. The trailing guard stops `med1` matching `med12`.
+ *
+ * It matches a PINNED reference too (AGL-2685) and must keep doing so: `@` is
+ * outside `[A-Za-z0-9_-]`, so `media:h/med1@abc` satisfies the trailing guard
+ * on its own. Had it not, the where-used scan would have started reporting
+ * live assets as used nowhere the day pins shipped — a scan whose every error
+ * already points at "safe to delete".
+ *
+ * It matches the same asset spelled as a CDN PATH as well (AGL-2969), in the
+ * same scope forms. The scan's needles include the document's own `cdnPath`,
+ * but that is the bare org form, and two writers store the path with the site
+ * in its scope: a plugin page's picker, for an asset shared with one site
+ * (`hostQualifiedCdnPath`), and an entry cover filled from a film's frame
+ * (`mediaPosterSrc`, qualified for every org film). A query, a content-hash
+ * segment and an origin in front all leave the match intact, and the same
+ * trailing guard applies.
+ */
+export declare function mediaRefPattern(mediaId: string): RegExp;
+/**
+ * What the media picker writes into a node prop.
+ *
+ * The reference is derived from `cdnPath`, and that is load-bearing rather
+ * than convenient: `cdnPath` is only minted for orgs entitled to `mediaCdn`
+ * and is deleted for private assets (`mediaCdnPathUpdate`). Since the CDN
+ * handler itself checks neither, minting a reference from an id we happen to
+ * know would hand every free-tier org paid delivery. Deriving it means the
+ * entitlement gate keeps working with no second copy of the rule — and a
+ * free-tier org degrades to the raw storage URL, which is exactly what it
+ * got before the CDN-path pass.
+ *
+ * `media.cdnPath` is expected to be already host-qualified by the picker
+ * dialog (AGL-1043). That qualification is preserved in the stored scope so
+ * the besigner canvas, which has no site context, can still fetch a
+ * restricted asset; {@link resolveMediaSrc} overrides it wherever the real
+ * rendering host IS known.
+ *
+ * No content pin is written, even when `media.contentHash` is present
+ * (AGL-2798). A pin changes no URL a reference renders, so writing one would
+ * put a value into the document that nothing reads, and hand the next reader
+ * a reason to turn it back into the year-long URL no replace can reach. The
+ * field stays in the accepted shape because callers hand over the whole media
+ * document.
+ */
+export declare function mediaNodeSrc(media: {
+    url?: string | null;
+    cdnPath?: string | null;
+    contentHash?: string | null;
+}): string | undefined;
+/**
+ * The derived objects a VIDEO asset carries, and how a caller asks for one
+ * (AGL-2742 / AGL-2743).
+ *
+ * ## Why these are query parameters on the asset's own URL
+ *
+ * The alternative was a second media document — a poster with its own id,
+ * pointed at from the video's. It was refused for the reason the whole
+ * `media:` scheme exists: a reference names an ASSET so that replacing its
+ * bytes propagates everywhere without re-linking. Two documents are two
+ * lifecycles that can diverge, and the first replace of a video would leave
+ * the old poster live under an id no reader knows is stale. One id, one
+ * delete, one replace — and a DAM grid that shows the film rather than the
+ * film plus a mystery still.
+ *
+ * The parameters mirror `?w=`, which has selected a derived object since
+ * AGL-175. Nothing about the reference itself changes: the same stored
+ * `media:{scope}/{id}` yields the master, the poster and every rendition,
+ * because which representation you want is a rendering decision and the
+ * document records only which asset.
+ */
+export declare const MEDIA_CDN_POSTER_PARAM = "poster";
+/** Selects a video rendition by key. See {@link isMediaRenditionKey}. */
+export declare const MEDIA_CDN_RENDITION_PARAM = "r";
+/**
+ * The `?r=` value meaning "the best delivery copy you have" (AGL-2753).
+ *
+ * A key names ONE encoding, which a caller can only ask for if it knows the
+ * asset has it. Nothing that renders a page knows that: renditions are
+ * produced out of band by `tools/scripts/generate-video-renditions.mjs`,
+ * minutes or days after the upload, and a published page is cached HTML that
+ * neither regenerates when an encoding lands nor varies on a visitor's
+ * `Accept`. So a placement made today can never name a rendition made
+ * tomorrow, and the encodings would be produced and never served.
+ *
+ * This sentinel moves the choice to the one place that already holds the
+ * document: `serveMediaCdn` reads it on every asset request anyway. The page
+ * emits one URL that says what it WANTS rather than what exists, and an asset
+ * with no renditions answers it with the master — the same degradation an
+ * unknown `?r=` has always had, reached deliberately instead of by accident.
+ *
+ * ⚠️ Sentinel and key share a namespace, so {@link parseMediaRendition}
+ * refuses a stored entry keyed `auto`. Without that refusal a producer could
+ * mint one and make the sentinel unreachable — the negotiated form silently
+ * pinned to whichever encoding happened to claim the name.
+ */
+export declare const MEDIA_CDN_RENDITION_AUTO = "auto";
+/**
+ * Object-path suffix for a video's poster still. The width variants sit
+ * under it as `{objectPath}__poster__w{n}.webp`, which is exactly what
+ * `generateMediaVariants` produces when handed `{objectPath}__poster` — the
+ * poster reuses the image variant generator whole rather than teaching it
+ * about video.
+ */
+export declare const MEDIA_POSTER_OBJECT_SUFFIX = "__poster";
+/** Object-path prefix for a rendition: `{objectPath}__r{key}.{ext}`. */
+export declare const MEDIA_RENDITION_OBJECT_PREFIX = "__r";
+/** Whether a value may be used as a rendition key, minted or received. */
+export declare function isMediaRenditionKey(value: unknown): value is string;
+/**
+ * One encoded delivery copy of a video, as recorded on the media document.
+ *
+ * Richer than the image variants' bare `number[]`, and the difference is not
+ * incidental. An image variant is fully described by its width because every
+ * one of them is WebP at quality 80 — the width IS the identity. A rendition
+ * is a (resolution, container, codec) triple, and the whole point of having
+ * more than one is to offer a browser a choice between codecs at the SAME
+ * resolution. A `number[]` cannot express that, so the array carries the
+ * facts a `<source>` element needs instead of forcing the renderer to
+ * reconstruct them from a naming convention.
+ */
+export interface MediaVideoRendition {
+    /** Selector, unique per asset. Fits {@link isMediaRenditionKey}. */
+    key: string;
+    /** What the CDN serves it as, and what a `<source type>` should say. */
+    contentType: string;
+    /** Object-path extension, so the path is derivable from the doc alone. */
+    ext: string;
+    width: number;
+    height: number;
+    sizeBytes: number;
+}
+/**
+ * Read one stored rendition entry, or null.
+ *
+ * ⚠️ This is a SECURITY gate, not a convenience. `key` and `ext` are
+ * interpolated into a Cloud Storage object path by
+ * {@link mediaRenditionObjectPath}, and the media document they come from is
+ * writable by anyone with editor rights on the scope. An entry carrying
+ * `key: '../../../adminAudit-archive/x'` would otherwise walk straight out of
+ * the asset's prefix on an admin-SDK bucket read — the same class of hole
+ * `mediaStoragePathInScope` closes for `storagePath` (AGL-1881), reached by a
+ * different field.
+ *
+ * The two grammars admit no `/`, no `.` and no `..`, so a validated entry
+ * cannot leave the object it belongs to whatever the document says.
+ */
+export declare function parseMediaRendition(value: unknown): MediaVideoRendition | null;
+/**
+ * Every VALID rendition on a document, in stored order.
+ *
+ * Order is the document's, and it is meaningful: a renderer emits one
+ * `<source>` per entry and a browser takes the FIRST it can decode, so the
+ * producer writes the most efficient codec first. Dropping an invalid entry
+ * rather than refusing the list keeps one malformed row from costing an asset
+ * every rendition it has.
+ */
+export declare function parseMediaRenditions(value: unknown): MediaVideoRendition[];
+/** Storage object path of an asset's poster still. */
+export declare function mediaPosterObjectPath(objectPath: string): string;
+/**
+ * Storage object path of one rendition. The `.` before the extension is the
+ * only one in the suffix, so a path is unambiguous even when a key contains
+ * digits that look like a width.
+ */
+export declare function mediaRenditionObjectPath(objectPath: string, rendition: {
+    key: string;
+    ext: string;
+}): string;
+/**
+ * The poster URL for a stored media reference, or undefined when the value
+ * cannot have one.
+ *
+ * `width` narrows to a generated poster variant. An asset with no variant at
+ * that width still answers — `serveMediaCdn` falls back to the full poster,
+ * the same degradation `?w=` has always had — so a renderer may advertise
+ * the standard {@link MEDIA_CDN_VARIANT_WIDTHS} in a `srcSet` without
+ * consulting the document.
+ *
+ * ⚠️ Returning a URL is NOT a promise that a poster exists. Nothing here can
+ * read a media document, and a video uploaded before AGL-2742 — or by a
+ * browser that could not decode it — has none.
+ *
+ * That case answers **404**, deliberately and not as a gap: `serveMediaCdn`
+ * refuses a poster it does not have rather than falling back to the master,
+ * because answering a request for a 40 KB still with 60 MB of `video/mp4` is
+ * the exact cost this exists to remove. So a `<video poster>` built from this
+ * degrades to a `<video>` with no poster, which is what every video on the
+ * platform did before AGL-2742 — which is why this is allowed to answer
+ * without knowing. A caller putting the URL somewhere a 404 is NOT free (an
+ * `<img>`, an `og:image`) must read `poster` off the document first.
+ */
+export declare function mediaPosterSrc(value: string | undefined | null, options?: ResolveMediaSrcOptions & {
+    width?: number;
+}): string | undefined;
+/**
+ * The URL of one rendition. Undefined for a key that does not fit the
+ * grammar, so a malformed key never reaches a `<source src>` — an empty
+ * `src` makes a browser re-request the PAGE, which is a far more expensive
+ * mistake than a missing source element.
+ */
+export declare function mediaRenditionSrc(value: string | undefined | null, key: string, options?: ResolveMediaSrcOptions): string | undefined;
+/**
+ * The URL a player should actually load for a video (AGL-2753).
+ *
+ * This is {@link resolveMediaSrc} plus one query parameter, and the parameter
+ * is the entire feature: it asks the CDN for the best delivery copy it has
+ * rather than naming one, so a rendition encoded LONG after the video was
+ * placed on a page reaches that page with no re-pick, no node backfill and no
+ * document read on the render path. See {@link MEDIA_CDN_RENDITION_AUTO} for
+ * why the choice has to live at the CDN.
+ *
+ * ⚠️ Unlike {@link mediaPosterSrc} this NEVER returns undefined for a value
+ * that resolved. A poster may legitimately have no URL — the element simply
+ * renders without one — but a video with no URL is a dead player, so anything
+ * this cannot improve is passed through exactly as `resolveMediaSrc` left it.
+ * An author-typed hotlink and a raw Storage URL therefore come back untouched:
+ * they are not this platform's objects and have no renditions to ask for.
+ *
+ * Safe on an asset that has none. `?r=` degrades to the master by design —
+ * "the same video in more bytes" — which is precisely what every video served
+ * before this existed, so a page that adopts this URL cannot regress.
+ */
+export declare function videoDeliverySrc(value: string | undefined | null, options?: ResolveMediaSrcOptions): string | undefined;
+/**
+ * The still a Video element should show, from the two places one can come
+ * from (AGL-2749).
+ *
+ * A video placement has two candidate posters and they are not equal:
+ *
+ * 1. **The author's own**, a media reference or a URL in the element's
+ *    `poster` field. It wins outright wherever it is set — an author who went
+ *    and chose a frame meant that frame, and a generated one silently
+ *    replacing it would make re-picking the SOURCE a destructive edit.
+ * 2. **The one the DAM generated at upload** ({@link mediaPosterSrc}), which
+ *    is not a separate asset at all: it is `?poster=1` on the video's own
+ *    reference.
+ *
+ * ⚠️ `generated` is REQUIRED for the second, and it is the whole reason this
+ * function exists rather than a `??` at each call site. `mediaPosterSrc`
+ * answers for any CDN-form reference and its own documentation says plainly
+ * that a URL is **not a promise a poster exists** — a video uploaded before
+ * AGL-2742, or one the uploader's browser could not decode, answers 404. That
+ * degrades harmlessly behind `<video poster>` and NOT harmlessly in an
+ * `<img>` (a broken image) or in a `thumbnailUrl` (a rich result pointing at
+ * nothing). So the caller has to have read `poster` off the media document —
+ * which the pick does, once, and carries on the node.
+ *
+ * `width` narrows both candidates to a variant, for the surfaces that take one
+ * url and no `srcset`. Omit it to get the full-size still, which is what an
+ * `<img>` wants as its `src` beside a `srcSet` of widths.
+ */
+export declare function videoPosterSrc(options: ResolveMediaSrcOptions & {
+    /** The element's own `poster` field — a reference, a URL, or nothing. */
+    poster?: unknown;
+    /** The element's `src`, which the generated poster derives from. */
+    src?: unknown;
+    /** Whether the media document records a generated poster. */
+    generated?: unknown;
+    /** Narrow to a variant width; omit for the full-size still. */
+    width?: number;
+}): string | undefined;