@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/sitemap.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @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.
+ */
+/** Where a site's sitemap index lives; what `robots.txt` advertises. */
+export declare const SITEMAP_INDEX_PATH = "/sitemap.xml";
+/**
+ * URLs per child sitemap.
+ *
+ * An order of magnitude under the protocol's 50,000 because the cap that
+ * binds first here is not the protocol's but Firestore's: a page of this file
+ * is a page of a query, and 5,000 keeps one crawler fetch to 5,000 document
+ * reads and a few hundred KB of XML. Raising it trades read cost for fewer
+ * files, and nothing in the format cares which side of that trade we take.
+ */
+export declare const SITEMAP_URLS_PER_FILE = 5000;
+/**
+ * A ceiling on how many pages one section may advertise, so a runaway
+ * collection cannot produce an index with tens of thousands of entries — the
+ * index has its own 50,000 limit, and a sweep that large is a bug long before
+ * it is a sitemap. 100 pages is 500,000 URLs in one section.
+ */
+export declare const SITEMAP_MAX_PAGES_PER_SECTION = 100;
+/** The fixed sections; a content collection adds one of its own. */
+export declare const SITEMAP_SECTION_PAGES = "pages";
+export declare const SITEMAP_SECTION_PRODUCTS = "products";
+export declare const SITEMAP_SECTION_CATALOG = "catalog";
+/**
+ * Author pages (AGL-2518) — `/author/{slug}`, one per author record.
+ *
+ * A fixed section rather than a per-collection one, because there is one
+ * author page per PERSON and it spans every collection they wrote in. A
+ * `content-…` section per collection would submit the same author several
+ * times over, at addresses that no longer exist.
+ */
+export declare const SITEMAP_SECTION_AUTHORS = "authors";
+/** The sitemap section a content collection's URLs live in. */
+export declare function contentSitemapSection(collectionSlug: string): string;
+/** The collection a `content-…` section names, or `undefined` for the rest. */
+export declare function contentSitemapSectionSlug(section: string): string | undefined;
+/**
+ * A child sitemap's path.
+ *
+ * The page is ALWAYS its own segment, including page 1. A one-file section is
+ * the common case and could have been the bare `/sitemaps/{section}.xml`, but
+ * then the page number would have to be encoded into the section name for
+ * every other page — and `content-blog-2` is ambiguous between page 2 of the
+ * collection `blog` and page 1 of the collection `blog-2`, which is a real
+ * slug someone can create. A separate segment cannot be ambiguous, and
+ * nothing but the index ever writes these URLs.
+ */
+export declare function sitemapSectionPath(section: string, page: number): string;
+/** The section and page a path addresses, or `undefined` if it addresses none. */
+export declare function parseSitemapSectionPath(pathname: string): {
+    section: string;
+    page: number;
+} | undefined;
+/**
+ * How many files a section of `urlCount` URLs needs. Zero URLs means zero
+ * files — a section with nothing in it is left out of the index rather than
+ * advertised as an empty document a crawler has to fetch to discover is empty.
+ */
+export declare function sitemapPageCount(urlCount: number): number;
+/** XML text escaping — a slug or a query string may carry any of these. */
+export declare function escapeSitemapXml(value: string): string;
+/**
+ * One address in a sitemap document. A bare string is an address with no
+ * known modification date; the object form carries a `lastmod` when the
+ * builder could derive one.
+ */
+export type SitemapLocation = string | {
+    loc: string;
+    lastmod?: string;
+};
+/**
+ * A `<lastmod>` value from whatever timestamp shape a document carries
+ * (AGL-2647): a Firestore `Timestamp` (`toMillis()`), the `{seconds}` object
+ * a serialized one decays into, epoch milliseconds, or an ISO string.
+ *
+ * The DAY only, in UTC. `YYYY-MM-DD` is a complete W3C datetime, and a date a
+ * crawler can compare is worth more than a time it cannot: a value that moved
+ * with every render would be a `lastmod` crawlers learn to discount, and the
+ * whole point of the element is to be believed.
+ *
+ * `undefined` for anything that does not decode, and the caller omits the
+ * element. Never "now": an invented date claims a change that did not
+ * happen, and a sitemap whose dates are consistently wrong is read as having
+ * none at all.
+ */
+export declare function sitemapLastmod(value: unknown): string | undefined;
+/** The `lastmod` a location carries, if any. */
+export declare function sitemapLocationLastmod(location: SitemapLocation): string | undefined;
+/**
+ * The newest of some `lastmod` values, or `undefined` when none is known.
+ *
+ * What a listing page and an index entry are dated by: a listing changed when
+ * its newest entry did, and a child sitemap changed when its newest URL did.
+ * Comparison is on the string, which is sound because every value is the
+ * fixed-width `YYYY-MM-DD` {@link sitemapLastmod} produces.
+ */
+export declare function newestSitemapLastmod(lastmods: Iterable<string | undefined>): string | undefined;
+/** A `<urlset>` document. */
+export declare function sitemapUrlsetXml(urls: readonly SitemapLocation[]): string;
+/** A `<sitemapindex>` document — the children of `/sitemap.xml`. */
+export declare function sitemapIndexXml(locs: readonly SitemapLocation[]): string;

package/src/lib/app-utils/sitemap.js

@@ -0,0 +1,183 @@
+/**
+ * @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.
+ */ /**
+ * Sitemap addressing and XML (AGL-2520).
+ *
+ * A site publishes ONE sitemap index at `/sitemap.xml` and a child sitemap per
+ * section — pages, products, the catalog, and one per content collection —
+ * each of which pages further at {@link SITEMAP_URLS_PER_FILE}.
+ *
+ * The split is what makes the sitemap survive a site growing. The protocol
+ * caps a single sitemap at 50,000 URLs and 50MB, and a flat file has no
+ * answer once a site crosses either: the URLs past the cap are simply not
+ * submitted, silently. It also makes the sweep behind each file bounded —
+ * a crawler asking for `/sitemaps/content-blog/2.xml` reads one page of one
+ * collection's entries instead of the whole site.
+ *
+ * These are pure functions on purpose: the tenant route handler that answers
+ * these URLs and the middleware that routes them to it must agree on the
+ * shape exactly, and so must the tests.
+ */ import { toEpochMs } from "./lockdown.js";
+/** Where a site's sitemap index lives; what `robots.txt` advertises. */ export const SITEMAP_INDEX_PATH = '/sitemap.xml';
+/**
+ * URLs per child sitemap.
+ *
+ * An order of magnitude under the protocol's 50,000 because the cap that
+ * binds first here is not the protocol's but Firestore's: a page of this file
+ * is a page of a query, and 5,000 keeps one crawler fetch to 5,000 document
+ * reads and a few hundred KB of XML. Raising it trades read cost for fewer
+ * files, and nothing in the format cares which side of that trade we take.
+ */ export const SITEMAP_URLS_PER_FILE = 5000;
+/**
+ * A ceiling on how many pages one section may advertise, so a runaway
+ * collection cannot produce an index with tens of thousands of entries — the
+ * index has its own 50,000 limit, and a sweep that large is a bug long before
+ * it is a sitemap. 100 pages is 500,000 URLs in one section.
+ */ export const SITEMAP_MAX_PAGES_PER_SECTION = 100;
+/** The fixed sections; a content collection adds one of its own. */ export const SITEMAP_SECTION_PAGES = 'pages';
+export const SITEMAP_SECTION_PRODUCTS = 'products';
+export const SITEMAP_SECTION_CATALOG = 'catalog';
+/**
+ * Author pages (AGL-2518) — `/author/{slug}`, one per author record.
+ *
+ * A fixed section rather than a per-collection one, because there is one
+ * author page per PERSON and it spans every collection they wrote in. A
+ * `content-…` section per collection would submit the same author several
+ * times over, at addresses that no longer exist.
+ */ export const SITEMAP_SECTION_AUTHORS = 'authors';
+/**
+ * The prefix a content collection's section carries.
+ *
+ * It exists so a collection slugged `products` cannot claim the commerce
+ * section, and it cannot itself collide: stripping happens ONCE, so a
+ * collection actually slugged `content-products` addresses
+ * `content-content-products` and stays distinct from `content-products`,
+ * which is the collection slugged `products`.
+ */ const CONTENT_SECTION_PREFIX = 'content-';
+/** The sitemap section a content collection's URLs live in. */ export function contentSitemapSection(collectionSlug) {
+    return `${CONTENT_SECTION_PREFIX}${collectionSlug}`;
+}
+/** The collection a `content-…` section names, or `undefined` for the rest. */ export function contentSitemapSectionSlug(section) {
+    if (!section.startsWith(CONTENT_SECTION_PREFIX)) return undefined;
+    const slug = section.slice(CONTENT_SECTION_PREFIX.length);
+    return slug || undefined;
+}
+/**
+ * A child sitemap's path.
+ *
+ * The page is ALWAYS its own segment, including page 1. A one-file section is
+ * the common case and could have been the bare `/sitemaps/{section}.xml`, but
+ * then the page number would have to be encoded into the section name for
+ * every other page — and `content-blog-2` is ambiguous between page 2 of the
+ * collection `blog` and page 1 of the collection `blog-2`, which is a real
+ * slug someone can create. A separate segment cannot be ambiguous, and
+ * nothing but the index ever writes these URLs.
+ */ export function sitemapSectionPath(section, page) {
+    return `/sitemaps/${section}/${Math.max(1, Math.floor(page))}.xml`;
+}
+/** Matches {@link sitemapSectionPath}; the one parser, shared with the middleware. */ const SITEMAP_SECTION_PATH = /^\/sitemaps\/([^/]+)\/([0-9]+)\.xml$/;
+/** The section and page a path addresses, or `undefined` if it addresses none. */ export function parseSitemapSectionPath(pathname) {
+    const match = SITEMAP_SECTION_PATH.exec(pathname);
+    if (!match) return undefined;
+    const page = Number(match[2]);
+    if (!Number.isFinite(page) || page < 1) return undefined;
+    return {
+        section: decodeURIComponent(match[1]),
+        page
+    };
+}
+/**
+ * How many files a section of `urlCount` URLs needs. Zero URLs means zero
+ * files — a section with nothing in it is left out of the index rather than
+ * advertised as an empty document a crawler has to fetch to discover is empty.
+ */ export function sitemapPageCount(urlCount) {
+    if (!Number.isFinite(urlCount) || urlCount <= 0) return 0;
+    return Math.min(SITEMAP_MAX_PAGES_PER_SECTION, Math.ceil(urlCount / SITEMAP_URLS_PER_FILE));
+}
+/** XML text escaping — a slug or a query string may carry any of these. */ export function escapeSitemapXml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/**
+ * A `<lastmod>` value from whatever timestamp shape a document carries
+ * (AGL-2647): a Firestore `Timestamp` (`toMillis()`), the `{seconds}` object
+ * a serialized one decays into, epoch milliseconds, or an ISO string.
+ *
+ * The DAY only, in UTC. `YYYY-MM-DD` is a complete W3C datetime, and a date a
+ * crawler can compare is worth more than a time it cannot: a value that moved
+ * with every render would be a `lastmod` crawlers learn to discount, and the
+ * whole point of the element is to be believed.
+ *
+ * `undefined` for anything that does not decode, and the caller omits the
+ * element. Never "now": an invented date claims a change that did not
+ * happen, and a sitemap whose dates are consistently wrong is read as having
+ * none at all.
+ */ export function sitemapLastmod(value) {
+    const ms = toEpochMs(value);
+    if (ms === undefined || ms <= 0) return undefined;
+    return new Date(ms).toISOString().slice(0, 10);
+}
+/** The `lastmod` a location carries, if any. */ export function sitemapLocationLastmod(location) {
+    return typeof location === 'string' ? undefined : location.lastmod;
+}
+/**
+ * The newest of some `lastmod` values, or `undefined` when none is known.
+ *
+ * What a listing page and an index entry are dated by: a listing changed when
+ * its newest entry did, and a child sitemap changed when its newest URL did.
+ * Comparison is on the string, which is sound because every value is the
+ * fixed-width `YYYY-MM-DD` {@link sitemapLastmod} produces.
+ */ export function newestSitemapLastmod(lastmods) {
+    let newest;
+    for (const lastmod of lastmods){
+        if (lastmod && (!newest || lastmod > newest)) newest = lastmod;
+    }
+    return newest;
+}
+/**
+ * De-duplicated (AGL-582): a collection slug can shadow a screen path, and
+ * the same URL twice in one sitemap is a submission of a duplicate, not a
+ * stronger signal. The FIRST occurrence keeps its date — the routing order
+ * that decides which page a shadowed URL serves is the order the builders
+ * emit in, so the first source is the one whose date describes the page.
+ */ function uniqueSitemapLocations(locations) {
+    const byLoc = new Map();
+    for (const location of locations){
+        const entry = typeof location === 'string' ? {
+            loc: location
+        } : location;
+        if (!byLoc.has(entry.loc)) {
+            byLoc.set(entry.loc, {
+                loc: entry.loc,
+                lastmod: entry.lastmod
+            });
+        }
+    }
+    return [
+        ...byLoc.values()
+    ];
+}
+/** `<url>` or `<sitemap>`; the `<lastmod>` child only when a date is known. */ function sitemapLocationXml(tag, { loc, lastmod }) {
+    const date = lastmod ? `<lastmod>${escapeSitemapXml(lastmod)}</lastmod>` : '';
+    return `  <${tag}><loc>${escapeSitemapXml(loc)}</loc>${date}</${tag}>`;
+}
+/** A `<urlset>` document. */ export function sitemapUrlsetXml(urls) {
+    return '<?xml version="1.0" encoding="UTF-8"?>\n' + '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' + uniqueSitemapLocations(urls).map((item)=>sitemapLocationXml('url', item)).join('\n') + '\n</urlset>\n';
+}
+/** A `<sitemapindex>` document — the children of `/sitemap.xml`. */ export function sitemapIndexXml(locs) {
+    return '<?xml version="1.0" encoding="UTF-8"?>\n' + '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' + uniqueSitemapLocations(locs).map((item)=>sitemapLocationXml('sitemap', item)).join('\n') + '\n</sitemapindex>\n';
+}
+
+//# sourceMappingURL=sitemap.js.map

package/src/lib/app-utils/sitemap.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/sitemap.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 * Sitemap addressing and XML (AGL-2520).\n *\n * A site publishes ONE sitemap index at `/sitemap.xml` and a child sitemap per\n * section — pages, products, the catalog, and one per content collection —\n * each of which pages further at {@link SITEMAP_URLS_PER_FILE}.\n *\n * The split is what makes the sitemap survive a site growing. The protocol\n * caps a single sitemap at 50,000 URLs and 50MB, and a flat file has no\n * answer once a site crosses either: the URLs past the cap are simply not\n * submitted, silently. It also makes the sweep behind each file bounded —\n * a crawler asking for `/sitemaps/content-blog/2.xml` reads one page of one\n * collection's entries instead of the whole site.\n *\n * These are pure functions on purpose: the tenant route handler that answers\n * these URLs and the middleware that routes them to it must agree on the\n * shape exactly, and so must the tests.\n */\n\nimport { toEpochMs } from './lockdown'\n\n/** Where a site's sitemap index lives; what `robots.txt` advertises. */\nexport const SITEMAP_INDEX_PATH = '/sitemap.xml'\n\n/**\n * URLs per child sitemap.\n *\n * An order of magnitude under the protocol's 50,000 because the cap that\n * binds first here is not the protocol's but Firestore's: a page of this file\n * is a page of a query, and 5,000 keeps one crawler fetch to 5,000 document\n * reads and a few hundred KB of XML. Raising it trades read cost for fewer\n * files, and nothing in the format cares which side of that trade we take.\n */\nexport const SITEMAP_URLS_PER_FILE = 5000\n\n/**\n * A ceiling on how many pages one section may advertise, so a runaway\n * collection cannot produce an index with tens of thousands of entries — the\n * index has its own 50,000 limit, and a sweep that large is a bug long before\n * it is a sitemap. 100 pages is 500,000 URLs in one section.\n */\nexport const SITEMAP_MAX_PAGES_PER_SECTION = 100\n\n/** The fixed sections; a content collection adds one of its own. */\nexport const SITEMAP_SECTION_PAGES = 'pages'\nexport const SITEMAP_SECTION_PRODUCTS = 'products'\nexport const SITEMAP_SECTION_CATALOG = 'catalog'\n/**\n * Author pages (AGL-2518) — `/author/{slug}`, one per author record.\n *\n * A fixed section rather than a per-collection one, because there is one\n * author page per PERSON and it spans every collection they wrote in. A\n * `content-…` section per collection would submit the same author several\n * times over, at addresses that no longer exist.\n */\nexport const SITEMAP_SECTION_AUTHORS = 'authors'\n\n/**\n * The prefix a content collection's section carries.\n *\n * It exists so a collection slugged `products` cannot claim the commerce\n * section, and it cannot itself collide: stripping happens ONCE, so a\n * collection actually slugged `content-products` addresses\n * `content-content-products` and stays distinct from `content-products`,\n * which is the collection slugged `products`.\n */\nconst CONTENT_SECTION_PREFIX = 'content-'\n\n/** The sitemap section a content collection's URLs live in. */\nexport function contentSitemapSection(collectionSlug: string): string {\n  return `${CONTENT_SECTION_PREFIX}${collectionSlug}`\n}\n\n/** The collection a `content-…` section names, or `undefined` for the rest. */\nexport function contentSitemapSectionSlug(\n  section: string,\n): string | undefined {\n  if (!section.startsWith(CONTENT_SECTION_PREFIX)) return undefined\n  const slug = section.slice(CONTENT_SECTION_PREFIX.length)\n  return slug || undefined\n}\n\n/**\n * A child sitemap's path.\n *\n * The page is ALWAYS its own segment, including page 1. A one-file section is\n * the common case and could have been the bare `/sitemaps/{section}.xml`, but\n * then the page number would have to be encoded into the section name for\n * every other page — and `content-blog-2` is ambiguous between page 2 of the\n * collection `blog` and page 1 of the collection `blog-2`, which is a real\n * slug someone can create. A separate segment cannot be ambiguous, and\n * nothing but the index ever writes these URLs.\n */\nexport function sitemapSectionPath(section: string, page: number): string {\n  return `/sitemaps/${section}/${Math.max(1, Math.floor(page))}.xml`\n}\n\n/** Matches {@link sitemapSectionPath}; the one parser, shared with the middleware. */\nconst SITEMAP_SECTION_PATH = /^\\/sitemaps\\/([^/]+)\\/([0-9]+)\\.xml$/\n\n/** The section and page a path addresses, or `undefined` if it addresses none. */\nexport function parseSitemapSectionPath(\n  pathname: string,\n): { section: string; page: number } | undefined {\n  const match = SITEMAP_SECTION_PATH.exec(pathname)\n  if (!match) return undefined\n  const page = Number(match[2])\n  if (!Number.isFinite(page) || page < 1) return undefined\n  return { section: decodeURIComponent(match[1]), page }\n}\n\n/**\n * How many files a section of `urlCount` URLs needs. Zero URLs means zero\n * files — a section with nothing in it is left out of the index rather than\n * advertised as an empty document a crawler has to fetch to discover is empty.\n */\nexport function sitemapPageCount(urlCount: number): number {\n  if (!Number.isFinite(urlCount) || urlCount <= 0) return 0\n  return Math.min(\n    SITEMAP_MAX_PAGES_PER_SECTION,\n    Math.ceil(urlCount / SITEMAP_URLS_PER_FILE),\n  )\n}\n\n/** XML text escaping — a slug or a query string may carry any of these. */\nexport function escapeSitemapXml(value: string): string {\n  return value\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;')\n}\n\n/**\n * One address in a sitemap document. A bare string is an address with no\n * known modification date; the object form carries a `lastmod` when the\n * builder could derive one.\n */\nexport type SitemapLocation = string | { loc: string; lastmod?: string }\n\n/**\n * A `<lastmod>` value from whatever timestamp shape a document carries\n * (AGL-2647): a Firestore `Timestamp` (`toMillis()`), the `{seconds}` object\n * a serialized one decays into, epoch milliseconds, or an ISO string.\n *\n * The DAY only, in UTC. `YYYY-MM-DD` is a complete W3C datetime, and a date a\n * crawler can compare is worth more than a time it cannot: a value that moved\n * with every render would be a `lastmod` crawlers learn to discount, and the\n * whole point of the element is to be believed.\n *\n * `undefined` for anything that does not decode, and the caller omits the\n * element. Never \"now\": an invented date claims a change that did not\n * happen, and a sitemap whose dates are consistently wrong is read as having\n * none at all.\n */\nexport function sitemapLastmod(value: unknown): string | undefined {\n  const ms = toEpochMs(value)\n  if (ms === undefined || ms <= 0) return undefined\n  return new Date(ms).toISOString().slice(0, 10)\n}\n\n/** The `lastmod` a location carries, if any. */\nexport function sitemapLocationLastmod(\n  location: SitemapLocation,\n): string | undefined {\n  return typeof location === 'string' ? undefined : location.lastmod\n}\n\n/**\n * The newest of some `lastmod` values, or `undefined` when none is known.\n *\n * What a listing page and an index entry are dated by: a listing changed when\n * its newest entry did, and a child sitemap changed when its newest URL did.\n * Comparison is on the string, which is sound because every value is the\n * fixed-width `YYYY-MM-DD` {@link sitemapLastmod} produces.\n */\nexport function newestSitemapLastmod(\n  lastmods: Iterable<string | undefined>,\n): string | undefined {\n  let newest: string | undefined\n  for (const lastmod of lastmods) {\n    if (lastmod && (!newest || lastmod > newest)) newest = lastmod\n  }\n  return newest\n}\n\n/**\n * De-duplicated (AGL-582): a collection slug can shadow a screen path, and\n * the same URL twice in one sitemap is a submission of a duplicate, not a\n * stronger signal. The FIRST occurrence keeps its date — the routing order\n * that decides which page a shadowed URL serves is the order the builders\n * emit in, so the first source is the one whose date describes the page.\n */\nfunction uniqueSitemapLocations(\n  locations: readonly SitemapLocation[],\n): Array<{ loc: string; lastmod?: string }> {\n  const byLoc = new Map<string, { loc: string; lastmod?: string }>()\n  for (const location of locations) {\n    const entry = typeof location === 'string' ? { loc: location } : location\n    if (!byLoc.has(entry.loc)) {\n      byLoc.set(entry.loc, { loc: entry.loc, lastmod: entry.lastmod })\n    }\n  }\n  return [...byLoc.values()]\n}\n\n/** `<url>` or `<sitemap>`; the `<lastmod>` child only when a date is known. */\nfunction sitemapLocationXml(\n  tag: 'url' | 'sitemap',\n  { loc, lastmod }: { loc: string; lastmod?: string },\n): string {\n  const date = lastmod ? `<lastmod>${escapeSitemapXml(lastmod)}</lastmod>` : ''\n  return `  <${tag}><loc>${escapeSitemapXml(loc)}</loc>${date}</${tag}>`\n}\n\n/** A `<urlset>` document. */\nexport function sitemapUrlsetXml(urls: readonly SitemapLocation[]): string {\n  return (\n    '<?xml version=\"1.0\" encoding=\"UTF-8\"?>\\n' +\n    '<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\\n' +\n    uniqueSitemapLocations(urls)\n      .map((item) => sitemapLocationXml('url', item))\n      .join('\\n') +\n    '\\n</urlset>\\n'\n  )\n}\n\n/** A `<sitemapindex>` document — the children of `/sitemap.xml`. */\nexport function sitemapIndexXml(locs: readonly SitemapLocation[]): string {\n  return (\n    '<?xml version=\"1.0\" encoding=\"UTF-8\"?>\\n' +\n    '<sitemapindex xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\\n' +\n    uniqueSitemapLocations(locs)\n      .map((item) => sitemapLocationXml('sitemap', item))\n      .join('\\n') +\n    '\\n</sitemapindex>\\n'\n  )\n}\n"],"names":["toEpochMs","SITEMAP_INDEX_PATH","SITEMAP_URLS_PER_FILE","SITEMAP_MAX_PAGES_PER_SECTION","SITEMAP_SECTION_PAGES","SITEMAP_SECTION_PRODUCTS","SITEMAP_SECTION_CATALOG","SITEMAP_SECTION_AUTHORS","CONTENT_SECTION_PREFIX","contentSitemapSection","collectionSlug","contentSitemapSectionSlug","section","startsWith","undefined","slug","slice","length","sitemapSectionPath","page","Math","max","floor","SITEMAP_SECTION_PATH","parseSitemapSectionPath","pathname","match","exec","Number","isFinite","decodeURIComponent","sitemapPageCount","urlCount","min","ceil","escapeSitemapXml","value","replace","sitemapLastmod","ms","Date","toISOString","sitemapLocationLastmod","location","lastmod","newestSitemapLastmod","lastmods","newest","uniqueSitemapLocations","locations","byLoc","Map","entry","loc","has","set","values","sitemapLocationXml","tag","date","sitemapUrlsetXml","urls","map","item","join","sitemapIndexXml","locs"],"mappings":"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"}

package/src/lib/app-utils/social-image.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @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.
+ */
+/**
+ * One candidate in the precedence list — the persisted shape of a social
+ * image on a host, a screen, or a template.
+ */
+export interface SocialImageSource {
+    /** A `media:` reference, a CDN path, or an author-supplied absolute URL. */
+    image?: string | null;
+    /**
+     * Pixel dimensions copied from the media record at pick time: the fallback
+     * when `assetFacts` records no usable pair for `image`.
+     */
+    imageWidth?: number | null;
+    imageHeight?: number | null;
+    /**
+     * What the card SHOWS, for `og:image:alt` (AGL-2417). Defaulted from the
+     * chosen asset's own alt at pick time and overridable per surface. Read off
+     * the same source as `image`, never mixed across the precedence list.
+     */
+    imageAlt?: string | null;
+}
+/**
+ * What the head emits. `width`/`height` are present only as a valid pair, and
+ * `alt` only when the winning source actually carries one.
+ *
+ * Next's OpenGraph/Twitter image DESCRIPTOR accepts exactly these keys, and
+ * both tenant branches already spread this object into `images: [ … ]` — so
+ * `og:image:alt` and `twitter:image:alt` start being emitted with no change
+ * at either emit site.
+ */
+export interface ResolvedSocialImage {
+    url: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+}
+/** The host fields the resolver needs: scope qualification and origin. */
+export interface SocialImageHost {
+    $id?: string | null;
+    cname?: string | null;
+    subdomain?: string | null;
+}
+/**
+ * What each library asset a card may name records NOW (AGL-2850): the pixel
+ * pair on its DAM document, keyed by the reference exactly as a source stores
+ * it (`media:{scope}/{mediaId}`, pinned or not).
+ *
+ * Built on the server from the batch the page's composition reads. A
+ * reference with no entry is one that read did not answer for, and its card
+ * keeps the pair stored beside it.
+ */
+export type SocialImageAssetFacts = Readonly<Record<string, {
+    width?: number | null;
+    height?: number | null;
+}>>;
+/**
+ * Resolves the social card image for a page.
+ *
+ * `sources` is the precedence list, most specific first — the tenant head
+ * passes `[entryCover, screen.seo, host.seo]` for a collection page and
+ * `[screen.seo, host.seo]` for a screen. The FIRST source carrying a
+ * non-empty `image` wins outright, together with its own dimensions.
+ *
+ * An empty string is a cleared field, not a value: it is how both pickers
+ * express "no image of my own" (the console writes it directly to Firestore
+ * rather than through the attributes form stack, which maps `''` to
+ * `undefined` and would make clearing impossible — AGL-1191). So clearing a
+ * screen's image means the host default applies again. There is deliberately
+ * no way for a screen to suppress the host default: the default exists so
+ * that every page has a card, and a page that wants none is not a case
+ * anyone has asked for. If one appears, add an explicit sentinel here — do
+ * not overload `''`, which cannot survive the form stack.
+ */
+export declare function resolveSocialImage(options: {
+    sources: Array<SocialImageSource | null | undefined>;
+    host?: SocialImageHost | null | undefined;
+    /**
+     * The origin to absolutize a site-relative URL against, for a surface that
+     * is not a tenant site and therefore has no host record to derive one from
+     * (AGL-876: the console's marketplace listing card).
+     *
+     * Takes precedence over the host, so a caller that has both is stating the
+     * origin it actually serves from rather than the one the host doc names.
+     * With neither, a relative URL still resolves to `undefined` — the rule in
+     * `absolutize` is unchanged, this only widens where the origin may come
+     * from.
+     */
+    origin?: string | null;
+    /**
+     * What the named assets' DAM documents record now (AGL-2850). The winning
+     * source's pair comes from here when its own reference has a usable one,
+     * and from the copy stored beside the reference otherwise. A surface that
+     * read no documents omits it and emits the stored copy, as every surface
+     * did before.
+     */
+    assetFacts?: SocialImageAssetFacts | null;
+}): ResolvedSocialImage | undefined;

package/src/lib/app-utils/social-image.js

@@ -0,0 +1,191 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 social card image (AGL-1337).
+ *
+ * ## The gap this closes
+ *
+ * `buildMetadata` already read `screen.seo.image || host.seo.image`, and the
+ * collection branch already read `entry.coverImage` — but nothing in the
+ * console could WRITE either screen or host field, so on a site whose pages
+ * are screens rather than collection entries every share fell back to
+ * `twitter:card: summary`: the small, image-less card. Meanwhile 44 designed
+ * 1200×630 assets sat in the DAM with nowhere to be bound.
+ *
+ * ## Why one function rather than a branch each
+ *
+ * There were already two half-answers in one file — the content branch took
+ * the entry cover, the screen branch took the screen/host fields — and
+ * neither did the two things a crawler actually requires:
+ *
+ * 1. **The URL must be absolute.** A picked asset is stored as
+ *    `media:{scope}/{mediaId}` and resolves to the site-RELATIVE path
+ *    `/api/media/cdn/{scope}/{mediaId}`. A browser has a page to resolve that
+ *    against; a crawler fetching `og:image` out of band does not. This is the
+ *    same problem `resolveEmailMediaSrc` solves for inboxes, and the tenant
+ *    app declares no `metadataBase`, so Next resolves nothing for us either.
+ *    Worse, before this the stored value was passed through UNTOUCHED, so a
+ *    `media:` reference reached `og:image` as the literal string `media:…`.
+ * 2. **`og:image:width`/`height` were emitted nowhere at all.** Both branches
+ *    passed a bare string, and Next only emits the dimension tags for an
+ *    object entry. Crawlers that pre-render a card without fetching the bytes
+ *    need them to reserve the right box.
+ *
+ * So both branches call this, and the resolution order is a LIST rather than
+ * a chain of `||` at each call site: whoever adds a third surface inherits
+ * the absolute-URL and dimension handling instead of writing a third copy
+ * that forgets one of them.
+ *
+ * ## Where the dimensions come from (AGL-2850)
+ *
+ * Each picker copies {@link AglynHostMedia.width}/`height` — auto-captured at
+ * upload (AGL-173) — beside the reference it writes, and that copy is the
+ * FALLBACK. A replace (AGL-2732) keeps an asset's id and URL and rewrites its
+ * pair. It cannot reach the copies stored beside the references to it, so a
+ * card replaced with a picture of another shape went on declaring the old
+ * shape to the crawlers that lay a card out before fetching its image, while
+ * its URL served the new bytes (AGL-2798).
+ *
+ * So the page's composition reads the document of each asset a card may name
+ * (a screen's and the host's `seo.image`, an entry's cover, an author's
+ * pictures) and hands their pairs here as `assetFacts`
+ * (`libs/tenant/runtime/src/lib/social-image-facts.ts`). The winning source
+ * takes its asset's pair when the document records a usable one, and its
+ * stored copy when it does not: an SVG the upload could not measure, a file
+ * older than AGL-173, an asset the CDN would not serve to this site, a failed
+ * read. Each of those renders the card every page rendered before.
+ *
+ * This reverses the tradeoff this note used to record. The pair was stored so
+ * that `generateMetadata`, on the ISR render path under a cold-start budget
+ * (AGL-1152), never read a media document for a number that changes only when
+ * someone replaces the asset. The composition already reads the documents of
+ * the images and films a page places, in one projected batch, so the card's
+ * documents join that read instead of adding one. The page that composes
+ * nothing, a password-protected screen, reads its card's documents on its own
+ * in one projected read.
+ *
+ * The pair travels WITH its image and is never mixed across sources — taking
+ * a screen's image and the host's dimensions would describe a card that does
+ * not exist, which is worse than emitting no dimensions at all. A current pair
+ * is looked up by the winning source's own reference, so it cannot cross
+ * sources either.
+ *
+ * ## `og:image:alt` (AGL-2417)
+ *
+ * `imageAlt` is stored and carried by exactly the same rule, and for a
+ * stronger version of the same reason. Until this, NO tenant page emitted an
+ * alt at all: the type had nowhere to hold one, so every shared card
+ * announced itself to a screen reader as an undescribed image.
+ *
+ * The alt is captured at PICK time from the chosen DAM asset
+ * (`inheritedMediaAlt`, AGL-1896) and is editable per surface, rather than
+ * looked up at render — the cold-start argument above applies unchanged, and
+ * a per-surface override is what lets "our logo" become "the Q3 report cover"
+ * on the one page where that is what the card shows.
+ *
+ * Defaulting at pick time on ONE of the three storage sites would NOT have
+ * been enough, and this is the objection worth recording: the resolver picks
+ * whichever source wins for a given page, so an alt stored only on the host
+ * default would be emitted beside a SCREEN's image — a description of a
+ * picture the card does not show, which is worse than no description. It is
+ * therefore stored beside the reference at all three sites and read off the
+ * SAME source the URL came from, exactly as the dimensions are.
+ */ import { hostPublicOrigin } from "./host-naming.js";
+import { MEDIA_ALT_MAX_LENGTH } from "./media-metadata.js";
+import { absoluteMediaSrc } from "./media-ref.js";
+/**
+ * The alt, trimmed, or nothing.
+ *
+ * Blank is never emitted. `og:image:alt=""` is a positive assertion that the
+ * image conveys nothing — the decorative case — and a share card is by
+ * definition not decorative, so an empty string here would be a worse claim
+ * than the absent tag it replaced. It is also capped at the same length the
+ * DAM saves through, so an alt that reaches a card is one the library would
+ * also have stored.
+ */ function alt(source) {
+    const value = typeof source.imageAlt === 'string' ? source.imageAlt.trim() : '';
+    return value ? {
+        alt: value.slice(0, MEDIA_ALT_MAX_LENGTH)
+    } : {};
+}
+/**
+ * A dimension pair is emitted only when BOTH sides are positive integers.
+ * Half a pair tells a crawler nothing and invites it to infer the other.
+ */ function dimensions(source) {
+    const width = Number(source.imageWidth);
+    const height = Number(source.imageHeight);
+    if (!Number.isFinite(width) || !Number.isFinite(height)) return {};
+    if (width <= 0 || height <= 0) return {};
+    return {
+        width: Math.round(width),
+        height: Math.round(height)
+    };
+}
+/**
+ * The pair a card emits: its asset's current one when `assetFacts` records a
+ * usable pair for the winning source's OWN reference, and otherwise the copy
+ * stored beside that reference. Both pass through {@link dimensions}, so the
+ * two cannot disagree about what a usable pair is.
+ */ function currentDimensions(source, assetFacts) {
+    var _source_image;
+    const image = (_source_image = source.image) != null ? _source_image : '';
+    const recorded = assetFacts && Object.prototype.hasOwnProperty.call(assetFacts, image) ? assetFacts[image] : undefined;
+    const current = recorded ? dimensions({
+        imageWidth: recorded.width,
+        imageHeight: recorded.height
+    }) : {};
+    return current.width === undefined ? dimensions(source) : current;
+}
+/**
+ * Resolves the social card image for a page.
+ *
+ * `sources` is the precedence list, most specific first — the tenant head
+ * passes `[entryCover, screen.seo, host.seo]` for a collection page and
+ * `[screen.seo, host.seo]` for a screen. The FIRST source carrying a
+ * non-empty `image` wins outright, together with its own dimensions.
+ *
+ * An empty string is a cleared field, not a value: it is how both pickers
+ * express "no image of my own" (the console writes it directly to Firestore
+ * rather than through the attributes form stack, which maps `''` to
+ * `undefined` and would make clearing impossible — AGL-1191). So clearing a
+ * screen's image means the host default applies again. There is deliberately
+ * no way for a screen to suppress the host default: the default exists so
+ * that every page has a card, and a page that wants none is not a case
+ * anyone has asked for. If one appears, add an explicit sentinel here — do
+ * not overload `''`, which cannot survive the form stack.
+ */ export function resolveSocialImage(options) {
+    const { sources, host, origin, assetFacts } = options;
+    const source = sources.find((candidate)=>Boolean(candidate == null ? void 0 : candidate.image));
+    if (!(source == null ? void 0 : source.image)) return undefined;
+    // A `media:` reference becomes the site-relative CDN path, host-qualified
+    // so a restricted org asset resolves for the site actually rendering, and is
+    // then absolutized because a crawler reads `og:image` out of band; any other
+    // string passes through untouched (back-compat with the raw storage URLs the
+    // content and favicon pickers have always written). Both halves live in
+    // `media-ref.ts` (AGL-1407) so the manifest and the inbox share this rule
+    // rather than each keeping a copy that can drift.
+    const url = absoluteMediaSrc(source.image, {
+        hostId: host == null ? void 0 : host.$id,
+        origin: origin || hostPublicOrigin(host)
+    });
+    if (!url) return undefined;
+    return _extends({
+        url
+    }, currentDimensions(source, assetFacts), alt(source));
+}
+
+//# sourceMappingURL=social-image.js.map