@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/measure-node-map.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/measure-node-map.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\nimport { encode } from '@msgpack/msgpack'\n\n/** Firestore's hard per-document ceiling. */\nexport const FIRESTORE_DOC_LIMIT_BYTES = 1_048_576\n\n/**\n * Refuse above this. Deliberately below the real limit: the encoded node\n * map is not the only thing in the document, and a save that squeaks under\n * 1 MiB today fails on the next small edit — which is a worse experience\n * than being told early.\n */\nexport const NODE_MAP_MAX_BYTES = 900_000\n\n/** Start warning here, while there is still room to act. */\nexport const NODE_MAP_WARN_BYTES = 700_000\n\nexport interface NodeMapSize {\n  bytes: number\n  /** Over the refuse threshold. */\n  tooLarge: boolean\n  /** Past the warn threshold but still saveable. */\n  nearLimit: boolean\n  /** Node ids by encoded size, largest first — the ones worth looking at. */\n  largest: Array<{ id: string; bytes: number }>\n}\n\n/**\n * Measure a node map the way it will actually be stored (AGL-678).\n *\n * Screen and layout versions are msgpack-encoded into a single `Bytes`\n * field, and nothing checked the result against Firestore's 1 MiB document\n * limit — so a large enough screen simply stopped saving, with a generic\n * write rejection, no indication that size was the problem, and no way to\n * find the offending content except by deleting things and retrying.\n *\n * Measures with the same encoder used at rest rather than `JSON.stringify`,\n * because msgpack is materially denser and a JSON estimate would refuse\n * documents that would have saved fine.\n *\n * Also reports the biggest individual nodes. In practice the cause is one\n * inlined image data URI rather than a thousand ordinary nodes, and naming\n * it turns \"your page is too big\" into something actionable.\n */\nexport function measureNodeMap(\n  nodes: Record<string, unknown> | undefined | null,\n): NodeMapSize {\n  if (!nodes) {\n    return { bytes: 0, tooLarge: false, nearLimit: false, largest: [] }\n  }\n  let bytes: number\n  try {\n    bytes = encode(nodes).length\n  } catch {\n    // Unencodable content is a different failure; let the write surface it\n    // rather than blocking the save on a measurement we could not take.\n    return { bytes: 0, tooLarge: false, nearLimit: false, largest: [] }\n  }\n\n  const largest: Array<{ id: string; bytes: number }> = []\n  for (const [id, node] of Object.entries(nodes)) {\n    try {\n      largest.push({ id, bytes: encode(node).length })\n    } catch {\n      // Skip nodes we cannot size; the total above is what gates the save.\n    }\n  }\n  largest.sort((a, b) => b.bytes - a.bytes)\n\n  return {\n    bytes,\n    tooLarge: bytes > NODE_MAP_MAX_BYTES,\n    nearLimit: bytes > NODE_MAP_WARN_BYTES && bytes <= NODE_MAP_MAX_BYTES,\n    largest: largest.slice(0, 3),\n  }\n}\n\n/**\n * Encoded size of a node map, and nothing else (AGL-1402).\n *\n * Same unit as {@link measureNodeMap} — msgpack bytes, the form the map is\n * actually stored in — so a total built out of this is directly comparable to\n * the per-document {@link NODE_MAP_MAX_BYTES} ceiling.\n *\n * Split out because the monthly usage rollup measures thousands of documents\n * and wants one number per document. `measureNodeMap` re-encodes every node\n * individually to build `largest`, which roughly doubles the work for a\n * diagnostic that only the save path reads.\n *\n * Returns 0 for absent AND for unencodable, matching `measureNodeMap`: a\n * measurement we could not take must not become a number somebody trusts.\n */\nexport function nodeMapBytes(\n  nodes: Record<string, unknown> | undefined | null,\n): number {\n  if (!nodes) return 0\n  try {\n    return encode(nodes).length\n  } catch {\n    return 0\n  }\n}\n\n/** Human-readable size, for messages that a person has to act on. */\nexport function formatBytes(bytes: number): string {\n  if (bytes >= 1_000_000) return `${(bytes / 1_048_576).toFixed(1)} MB`\n  if (bytes >= 1_000) return `${Math.round(bytes / 1024)} KB`\n  return `${bytes} bytes`\n}\n\nexport default measureNodeMap\n"],"names":["encode","FIRESTORE_DOC_LIMIT_BYTES","NODE_MAP_MAX_BYTES","NODE_MAP_WARN_BYTES","measureNodeMap","nodes","bytes","tooLarge","nearLimit","largest","length","id","node","Object","entries","push","sort","a","b","slice","nodeMapBytes","formatBytes","toFixed","Math","round"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,MAAM,QAAQ,mBAAkB;AAEzC,2CAA2C,GAC3C,OAAO,MAAMC,4BAA4B,QAAS;AAElD;;;;;CAKC,GACD,OAAO,MAAMC,qBAAqB,OAAO;AAEzC,0DAA0D,GAC1D,OAAO,MAAMC,sBAAsB,OAAO;AAY1C;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASC,eACdC,KAAiD;IAEjD,IAAI,CAACA,OAAO;QACV,OAAO;YAAEC,OAAO;YAAGC,UAAU;YAAOC,WAAW;YAAOC,SAAS,EAAE;QAAC;IACpE;IACA,IAAIH;IACJ,IAAI;QACFA,QAAQN,OAAOK,OAAOK,MAAM;IAC9B,EAAE,eAAM;QACN,uEAAuE;QACvE,oEAAoE;QACpE,OAAO;YAAEJ,OAAO;YAAGC,UAAU;YAAOC,WAAW;YAAOC,SAAS,EAAE;QAAC;IACpE;IAEA,MAAMA,UAAgD,EAAE;IACxD,KAAK,MAAM,CAACE,IAAIC,KAAK,IAAIC,OAAOC,OAAO,CAACT,OAAQ;QAC9C,IAAI;YACFI,QAAQM,IAAI,CAAC;gBAAEJ;gBAAIL,OAAON,OAAOY,MAAMF,MAAM;YAAC;QAChD,EAAE,eAAM;QACN,qEAAqE;QACvE;IACF;IACAD,QAAQO,IAAI,CAAC,CAACC,GAAGC,IAAMA,EAAEZ,KAAK,GAAGW,EAAEX,KAAK;IAExC,OAAO;QACLA;QACAC,UAAUD,QAAQJ;QAClBM,WAAWF,QAAQH,uBAAuBG,SAASJ;QACnDO,SAASA,QAAQU,KAAK,CAAC,GAAG;IAC5B;AACF;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,aACdf,KAAiD;IAEjD,IAAI,CAACA,OAAO,OAAO;IACnB,IAAI;QACF,OAAOL,OAAOK,OAAOK,MAAM;IAC7B,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA,mEAAmE,GACnE,OAAO,SAASW,YAAYf,KAAa;IACvC,IAAIA,SAAS,SAAW,OAAO,GAAG,AAACA,CAAAA,QAAQ,OAAQ,EAAGgB,OAAO,CAAC,GAAG,GAAG,CAAC;IACrE,IAAIhB,SAAS,MAAO,OAAO,GAAGiB,KAAKC,KAAK,CAAClB,QAAQ,MAAM,GAAG,CAAC;IAC3D,OAAO,GAAGA,MAAM,MAAM,CAAC;AACzB;AAEA,eAAeF,eAAc"}

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

@@ -0,0 +1,55 @@
+/**
+ * @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.
+ */
+/**
+ * The `alt` a rendered `<img>` carries, and the cap every author-typed one
+ * is trimmed to.
+ *
+ * Its own module because a published page reads only these two — every cover
+ * image on a site stamps its `alt` through them — while `media-metadata.ts`
+ * around it is pick-time and upload-time work: tag normalization, the
+ * inherited-alt decision, intrinsic sizing, and a byte-level image header
+ * parser for PNG, JPEG, GIF, WebP and AVIF. None of that runs to render an
+ * attribute, and a bundler cannot drop it around a single named import.
+ */
+/** Longest `alt` stored or emitted; anything longer is trimmed to it. */
+export declare const MEDIA_ALT_MAX_LENGTH = 300;
+/**
+ * The `alt` to put on a rendered `<img>` (AGL-2418).
+ *
+ * The render-time counterpart to `inheritedMediaAlt`, which decides what to
+ * STORE at pick time. This decides what to EMIT, and it always returns a
+ * string — never `undefined` — because the one thing a cover must not do is
+ * render without the attribute at all. `alt=""` and a missing `alt` are
+ * different announcements: the empty attribute tells a screen reader "skip
+ * this, the adjacent text names it", while an absent one makes it fall back
+ * to reading the file name aloud. Every entry and event authored before the
+ * field existed takes the empty branch, so that distinction is not an edge
+ * case here — it is the majority of real content.
+ *
+ * `fallback` is for the placements where the image IS the accessible name of
+ * its own link, and so cannot be silent — the related-entries cover, whose
+ * only text is the title it sits under. Placements where adjacent text
+ * already names the image (the entry hero directly beneath its `<h1>`, the
+ * 96×96 event thumbnail beside its title) pass no fallback and stay empty,
+ * because repeating the heading there is a double announcement. The two
+ * rules look inconsistent and are not; flattening them to one would make
+ * accessibility worse in whichever direction it flattened.
+ *
+ * Nothing is ever fabricated from a file name, for the reason
+ * `inheritedMediaAlt` gives: "IMG_4021.jpg" read aloud is worse than silence.
+ */
+export declare function renderedMediaAlt(authored?: unknown, fallback?: unknown): string;

package/src/lib/app-utils/media-alt.js

@@ -0,0 +1,58 @@
+/**
+ * @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.
+ */ /**
+ * The `alt` a rendered `<img>` carries, and the cap every author-typed one
+ * is trimmed to.
+ *
+ * Its own module because a published page reads only these two — every cover
+ * image on a site stamps its `alt` through them — while `media-metadata.ts`
+ * around it is pick-time and upload-time work: tag normalization, the
+ * inherited-alt decision, intrinsic sizing, and a byte-level image header
+ * parser for PNG, JPEG, GIF, WebP and AVIF. None of that runs to render an
+ * attribute, and a bundler cannot drop it around a single named import.
+ */ /** Longest `alt` stored or emitted; anything longer is trimmed to it. */ export const MEDIA_ALT_MAX_LENGTH = 300;
+/**
+ * The `alt` to put on a rendered `<img>` (AGL-2418).
+ *
+ * The render-time counterpart to `inheritedMediaAlt`, which decides what to
+ * STORE at pick time. This decides what to EMIT, and it always returns a
+ * string — never `undefined` — because the one thing a cover must not do is
+ * render without the attribute at all. `alt=""` and a missing `alt` are
+ * different announcements: the empty attribute tells a screen reader "skip
+ * this, the adjacent text names it", while an absent one makes it fall back
+ * to reading the file name aloud. Every entry and event authored before the
+ * field existed takes the empty branch, so that distinction is not an edge
+ * case here — it is the majority of real content.
+ *
+ * `fallback` is for the placements where the image IS the accessible name of
+ * its own link, and so cannot be silent — the related-entries cover, whose
+ * only text is the title it sits under. Placements where adjacent text
+ * already names the image (the entry hero directly beneath its `<h1>`, the
+ * 96×96 event thumbnail beside its title) pass no fallback and stay empty,
+ * because repeating the heading there is a double announcement. The two
+ * rules look inconsistent and are not; flattening them to one would make
+ * accessibility worse in whichever direction it flattened.
+ *
+ * Nothing is ever fabricated from a file name, for the reason
+ * `inheritedMediaAlt` gives: "IMG_4021.jpg" read aloud is worse than silence.
+ */ export function renderedMediaAlt(authored, fallback) {
+    const typed = typeof authored === 'string' ? authored.trim() : '';
+    if (typed) return typed.slice(0, MEDIA_ALT_MAX_LENGTH);
+    const named = typeof fallback === 'string' ? fallback.trim() : '';
+    return named ? named.slice(0, MEDIA_ALT_MAX_LENGTH) : '';
+}
+
+//# sourceMappingURL=media-alt.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/media-alt.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 * The `alt` a rendered `<img>` carries, and the cap every author-typed one\n * is trimmed to.\n *\n * Its own module because a published page reads only these two — every cover\n * image on a site stamps its `alt` through them — while `media-metadata.ts`\n * around it is pick-time and upload-time work: tag normalization, the\n * inherited-alt decision, intrinsic sizing, and a byte-level image header\n * parser for PNG, JPEG, GIF, WebP and AVIF. None of that runs to render an\n * attribute, and a bundler cannot drop it around a single named import.\n */\n\n/** Longest `alt` stored or emitted; anything longer is trimmed to it. */\nexport const MEDIA_ALT_MAX_LENGTH = 300\n\n/**\n * The `alt` to put on a rendered `<img>` (AGL-2418).\n *\n * The render-time counterpart to `inheritedMediaAlt`, which decides what to\n * STORE at pick time. This decides what to EMIT, and it always returns a\n * string — never `undefined` — because the one thing a cover must not do is\n * render without the attribute at all. `alt=\"\"` and a missing `alt` are\n * different announcements: the empty attribute tells a screen reader \"skip\n * this, the adjacent text names it\", while an absent one makes it fall back\n * to reading the file name aloud. Every entry and event authored before the\n * field existed takes the empty branch, so that distinction is not an edge\n * case here — it is the majority of real content.\n *\n * `fallback` is for the placements where the image IS the accessible name of\n * its own link, and so cannot be silent — the related-entries cover, whose\n * only text is the title it sits under. Placements where adjacent text\n * already names the image (the entry hero directly beneath its `<h1>`, the\n * 96×96 event thumbnail beside its title) pass no fallback and stay empty,\n * because repeating the heading there is a double announcement. The two\n * rules look inconsistent and are not; flattening them to one would make\n * accessibility worse in whichever direction it flattened.\n *\n * Nothing is ever fabricated from a file name, for the reason\n * `inheritedMediaAlt` gives: \"IMG_4021.jpg\" read aloud is worse than silence.\n */\nexport function renderedMediaAlt(authored?: unknown, fallback?: unknown) {\n  const typed = typeof authored === 'string' ? authored.trim() : ''\n  if (typed) return typed.slice(0, MEDIA_ALT_MAX_LENGTH)\n  const named = typeof fallback === 'string' ? fallback.trim() : ''\n  return named ? named.slice(0, MEDIA_ALT_MAX_LENGTH) : ''\n}\n"],"names":["MEDIA_ALT_MAX_LENGTH","renderedMediaAlt","authored","fallback","typed","trim","slice","named"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;CAUC,GAED,uEAAuE,GACvE,OAAO,MAAMA,uBAAuB,IAAG;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GACD,OAAO,SAASC,iBAAiBC,QAAkB,EAAEC,QAAkB;IACrE,MAAMC,QAAQ,OAAOF,aAAa,WAAWA,SAASG,IAAI,KAAK;IAC/D,IAAID,OAAO,OAAOA,MAAME,KAAK,CAAC,GAAGN;IACjC,MAAMO,QAAQ,OAAOJ,aAAa,WAAWA,SAASE,IAAI,KAAK;IAC/D,OAAOE,QAAQA,MAAMD,KAAK,CAAC,GAAGN,wBAAwB;AACxD"}

package/src/lib/app-utils/media-asset-facts.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @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.
+ */
+import { type MediaRef } from './media-ref';
+import { VIDEO_COMPONENT_ID } from './video-object';
+/** The Image element's persisted component id (`image.tsx`), never renamed. */
+export declare const IMAGE_COMPONENT_ID = "image";
+/**
+ * What a readable asset's media document records, as the overlay consumes it.
+ *
+ * Raw on purpose: {@link intrinsicMediaSize} and {@link videoMediaProps} are
+ * where a pair and a `video` record are bounded, and a second reading of the
+ * same numbers here is how two files come to disagree about what a partial
+ * record means.
+ */
+export interface MediaAssetFacts {
+    /** The document's `width`: an image's, read from its bytes at upload. */
+    width?: unknown;
+    /** The document's `height`, the other half of {@link width}. */
+    height?: unknown;
+    /** The document's `video` record: `durationMs`, `width` and `height`. */
+    video?: unknown;
+    /** The document's generated `poster` record, when it has one. */
+    poster?: unknown;
+}
+/**
+ * Every field an asset's facts are decided from, and the projection a reader
+ * asks Firestore for: ONE list, whichever surface reads. `width` and `height`
+ * (an image's) and `video` and `poster` (a film's) are the facts. The other
+ * three are the gates `serveMediaCdn` applies before it will serve an asset at
+ * all, so no surface shows the shape of a file its page's URL refuses.
+ */
+export declare const MEDIA_ASSET_FACT_FIELDS: readonly ["width", "height", "video", "poster", "deletedAt", "private", "visibleTo"];
+/** An asset's media document, as far as {@link MEDIA_ASSET_FACT_FIELDS} reach. */
+export type MediaAssetDocument = Partial<Record<(typeof MEDIA_ASSET_FACT_FIELDS)[number], unknown>>;
+/** The elements whose placements follow their file. */
+export type MediaAssetElement = typeof IMAGE_COMPONENT_ID | typeof VIDEO_COMPONENT_ID;
+export interface MediaAssetFactsOptions {
+    /**
+     * One element's placements only, by persisted component id. Absent means
+     * both, which is what the composition asks for.
+     */
+    only?: MediaAssetElement;
+}
+/**
+ * The key an asset's facts are filed under: the reference's own scope and id.
+ *
+ * Deliberately NOT the host-qualified scope a page renders. The document lives
+ * under the scope's owner whichever site places it, and which site may be
+ * shown it is the reader's question, answered once per page.
+ */
+export declare function mediaAssetFactsKey(ref: Pick<MediaRef, 'scope' | 'mediaId'>): string;
+/**
+ * Where an asset's media document lives: under the scope's OWNER, `orgs/` for
+ * the org library and `hosts/` for a site's own, whichever site places it.
+ * `null` for a scope the CDN would not parse, which no read can answer for.
+ */
+export declare function mediaAssetDocumentPath(ref: Pick<MediaRef, 'scope' | 'mediaId'>): string | null;
+/**
+ * The facts one read of an asset's document yields for a placement rendered
+ * on `hostId`'s pages, or `undefined` when the placement keeps its stored
+ * props.
+ *
+ * An answer exists only for a document that was read, is live, is not
+ * private, and is visible to that site under the host-qualified scope the page
+ * renders: the verdict the CDN reaches when the browser asks for the bytes.
+ * The URL a page renders names the site doing the rendering
+ * (`resolveMediaSrc`), so visibility is asked of THAT scope, not of the scope
+ * the reference was stored with.
+ */
+export declare function mediaAssetFactsFromDocument(document: MediaAssetDocument | null | undefined, ref: Pick<MediaRef, 'scope'>, hostId: string): MediaAssetFacts | undefined;
+/**
+ * Every distinct library asset the Image and Video nodes in a map place:
+ * films first, then images, each in document order.
+ *
+ * A read that is capped honors that order. A film goes first because its
+ * stale facts are the worse render (a player of the wrong shape and a
+ * thumbnail that 404s, against a reservation that corrects itself when an
+ * image decodes), and document order covers the top of the page before its
+ * footer.
+ *
+ * `[]` for a page that places none, so a caller that gates its read on the
+ * length spends nothing on it. A pinned and an unpinned reference to one
+ * asset are one entry: a pin names bytes, not a different asset.
+ */
+export declare function mediaAssetRefs(nodes: Record<string, unknown> | null | undefined, options?: MediaAssetFactsOptions): MediaRef[];
+/**
+ * The prop a markdown body carries its images' pixel pairs in, keyed by the
+ * target the body wrote (AGL-3149).
+ *
+ * A body image is not a node, so it cannot take `intrinsicWidth` and
+ * `intrinsicHeight` the way a placement does; the pairs travel together on the
+ * element that holds the document, and the renderer looks each one up by the
+ * parsed block's `src`.
+ */
+export declare const BODY_IMAGE_SIZES_PROP = "intrinsicSizes";
+/** One body image's pair, as {@link BODY_IMAGE_SIZES_PROP} carries it. */
+export interface BodyImageSize {
+    width: number;
+    height: number;
+}
+/**
+ * The composed map with each placed asset's facts laid over its node, and each
+ * markdown body's images' pairs laid over the element holding the body.
+ *
+ * `facts` is keyed by {@link mediaAssetFactsKey}. A placement with no entry,
+ * because the reader could not answer for its asset, keeps its stored props.
+ * The SAME map comes back when nothing changes, so a page with no library
+ * asset pays for one walk and no copy, and the input is never mutated either
+ * way.
+ */
+export declare function applyMediaAssetFacts<T extends Record<string, unknown>>(nodes: T, facts: ReadonlyMap<string, MediaAssetFacts>, options?: MediaAssetFactsOptions): T;