@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/social-image.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 social card image (AGL-1337).\n *\n * ## The gap this closes\n *\n * `buildMetadata` already read `screen.seo.image || host.seo.image`, and the\n * collection branch already read `entry.coverImage` — but nothing in the\n * console could WRITE either screen or host field, so on a site whose pages\n * are screens rather than collection entries every share fell back to\n * `twitter:card: summary`: the small, image-less card. Meanwhile 44 designed\n * 1200×630 assets sat in the DAM with nowhere to be bound.\n *\n * ## Why one function rather than a branch each\n *\n * There were already two half-answers in one file — the content branch took\n * the entry cover, the screen branch took the screen/host fields — and\n * neither did the two things a crawler actually requires:\n *\n * 1. **The URL must be absolute.** A picked asset is stored as\n *    `media:{scope}/{mediaId}` and resolves to the site-RELATIVE path\n *    `/api/media/cdn/{scope}/{mediaId}`. A browser has a page to resolve that\n *    against; a crawler fetching `og:image` out of band does not. This is the\n *    same problem `resolveEmailMediaSrc` solves for inboxes, and the tenant\n *    app declares no `metadataBase`, so Next resolves nothing for us either.\n *    Worse, before this the stored value was passed through UNTOUCHED, so a\n *    `media:` reference reached `og:image` as the literal string `media:…`.\n * 2. **`og:image:width`/`height` were emitted nowhere at all.** Both branches\n *    passed a bare string, and Next only emits the dimension tags for an\n *    object entry. Crawlers that pre-render a card without fetching the bytes\n *    need them to reserve the right box.\n *\n * So both branches call this, and the resolution order is a LIST rather than\n * a chain of `||` at each call site: whoever adds a third surface inherits\n * the absolute-URL and dimension handling instead of writing a third copy\n * that forgets one of them.\n *\n * ## Where the dimensions come from (AGL-2850)\n *\n * Each picker copies {@link AglynHostMedia.width}/`height` — auto-captured at\n * upload (AGL-173) — beside the reference it writes, and that copy is the\n * FALLBACK. A replace (AGL-2732) keeps an asset's id and URL and rewrites its\n * pair. It cannot reach the copies stored beside the references to it, so a\n * card replaced with a picture of another shape went on declaring the old\n * shape to the crawlers that lay a card out before fetching its image, while\n * its URL served the new bytes (AGL-2798).\n *\n * So the page's composition reads the document of each asset a card may name\n * (a screen's and the host's `seo.image`, an entry's cover, an author's\n * pictures) and hands their pairs here as `assetFacts`\n * (`libs/tenant/runtime/src/lib/social-image-facts.ts`). The winning source\n * takes its asset's pair when the document records a usable one, and its\n * stored copy when it does not: an SVG the upload could not measure, a file\n * older than AGL-173, an asset the CDN would not serve to this site, a failed\n * read. Each of those renders the card every page rendered before.\n *\n * This reverses the tradeoff this note used to record. The pair was stored so\n * that `generateMetadata`, on the ISR render path under a cold-start budget\n * (AGL-1152), never read a media document for a number that changes only when\n * someone replaces the asset. The composition already reads the documents of\n * the images and films a page places, in one projected batch, so the card's\n * documents join that read instead of adding one. The page that composes\n * nothing, a password-protected screen, reads its card's documents on its own\n * in one projected read.\n *\n * The pair travels WITH its image and is never mixed across sources — taking\n * a screen's image and the host's dimensions would describe a card that does\n * not exist, which is worse than emitting no dimensions at all. A current pair\n * is looked up by the winning source's own reference, so it cannot cross\n * sources either.\n *\n * ## `og:image:alt` (AGL-2417)\n *\n * `imageAlt` is stored and carried by exactly the same rule, and for a\n * stronger version of the same reason. Until this, NO tenant page emitted an\n * alt at all: the type had nowhere to hold one, so every shared card\n * announced itself to a screen reader as an undescribed image.\n *\n * The alt is captured at PICK time from the chosen DAM asset\n * (`inheritedMediaAlt`, AGL-1896) and is editable per surface, rather than\n * looked up at render — the cold-start argument above applies unchanged, and\n * a per-surface override is what lets \"our logo\" become \"the Q3 report cover\"\n * on the one page where that is what the card shows.\n *\n * Defaulting at pick time on ONE of the three storage sites would NOT have\n * been enough, and this is the objection worth recording: the resolver picks\n * whichever source wins for a given page, so an alt stored only on the host\n * default would be emitted beside a SCREEN's image — a description of a\n * picture the card does not show, which is worse than no description. It is\n * therefore stored beside the reference at all three sites and read off the\n * SAME source the URL came from, exactly as the dimensions are.\n */\n\nimport { hostPublicOrigin } from './host-naming'\nimport { MEDIA_ALT_MAX_LENGTH } from './media-metadata'\nimport { absoluteMediaSrc } from './media-ref'\n\n/**\n * One candidate in the precedence list — the persisted shape of a social\n * image on a host, a screen, or a template.\n */\nexport interface SocialImageSource {\n  /** A `media:` reference, a CDN path, or an author-supplied absolute URL. */\n  image?: string | null\n  /**\n   * Pixel dimensions copied from the media record at pick time: the fallback\n   * when `assetFacts` records no usable pair for `image`.\n   */\n  imageWidth?: number | null\n  imageHeight?: number | null\n  /**\n   * What the card SHOWS, for `og:image:alt` (AGL-2417). Defaulted from the\n   * chosen asset's own alt at pick time and overridable per surface. Read off\n   * the same source as `image`, never mixed across the precedence list.\n   */\n  imageAlt?: string | null\n}\n\n/**\n * What the head emits. `width`/`height` are present only as a valid pair, and\n * `alt` only when the winning source actually carries one.\n *\n * Next's OpenGraph/Twitter image DESCRIPTOR accepts exactly these keys, and\n * both tenant branches already spread this object into `images: [ … ]` — so\n * `og:image:alt` and `twitter:image:alt` start being emitted with no change\n * at either emit site.\n */\nexport interface ResolvedSocialImage {\n  url: string\n  width?: number\n  height?: number\n  alt?: string\n}\n\n/** The host fields the resolver needs: scope qualification and origin. */\nexport interface SocialImageHost {\n  $id?: string | null\n  cname?: string | null\n  subdomain?: string | null\n}\n\n/**\n * What each library asset a card may name records NOW (AGL-2850): the pixel\n * pair on its DAM document, keyed by the reference exactly as a source stores\n * it (`media:{scope}/{mediaId}`, pinned or not).\n *\n * Built on the server from the batch the page's composition reads. A\n * reference with no entry is one that read did not answer for, and its card\n * keeps the pair stored beside it.\n */\nexport type SocialImageAssetFacts = Readonly<\n  Record<string, { width?: number | null; height?: number | null }>\n>\n\n/**\n * The alt, trimmed, or nothing.\n *\n * Blank is never emitted. `og:image:alt=\"\"` is a positive assertion that the\n * image conveys nothing — the decorative case — and a share card is by\n * definition not decorative, so an empty string here would be a worse claim\n * than the absent tag it replaced. It is also capped at the same length the\n * DAM saves through, so an alt that reaches a card is one the library would\n * also have stored.\n */\nfunction alt(source: SocialImageSource) {\n  const value = typeof source.imageAlt === 'string' ? source.imageAlt.trim() : ''\n  return value ? { alt: value.slice(0, MEDIA_ALT_MAX_LENGTH) } : {}\n}\n\n/**\n * A dimension pair is emitted only when BOTH sides are positive integers.\n * Half a pair tells a crawler nothing and invites it to infer the other.\n */\nfunction dimensions(source: SocialImageSource): {\n  width?: number\n  height?: number\n} {\n  const width = Number(source.imageWidth)\n  const height = Number(source.imageHeight)\n  if (!Number.isFinite(width) || !Number.isFinite(height)) return {}\n  if (width <= 0 || height <= 0) return {}\n  return { width: Math.round(width), height: Math.round(height) }\n}\n\n/**\n * The pair a card emits: its asset's current one when `assetFacts` records a\n * usable pair for the winning source's OWN reference, and otherwise the copy\n * stored beside that reference. Both pass through {@link dimensions}, so the\n * two cannot disagree about what a usable pair is.\n */\nfunction currentDimensions(\n  source: SocialImageSource,\n  assetFacts: SocialImageAssetFacts | null | undefined,\n): { width?: number; height?: number } {\n  const image = source.image ?? ''\n  const recorded =\n    assetFacts && Object.prototype.hasOwnProperty.call(assetFacts, image)\n      ? assetFacts[image]\n      : undefined\n  const current: { width?: number; height?: number } = recorded\n    ? dimensions({ imageWidth: recorded.width, imageHeight: recorded.height })\n    : {}\n  return current.width === undefined ? dimensions(source) : current\n}\n\n/**\n * Resolves the social card image for a page.\n *\n * `sources` is the precedence list, most specific first — the tenant head\n * passes `[entryCover, screen.seo, host.seo]` for a collection page and\n * `[screen.seo, host.seo]` for a screen. The FIRST source carrying a\n * non-empty `image` wins outright, together with its own dimensions.\n *\n * An empty string is a cleared field, not a value: it is how both pickers\n * express \"no image of my own\" (the console writes it directly to Firestore\n * rather than through the attributes form stack, which maps `''` to\n * `undefined` and would make clearing impossible — AGL-1191). So clearing a\n * screen's image means the host default applies again. There is deliberately\n * no way for a screen to suppress the host default: the default exists so\n * that every page has a card, and a page that wants none is not a case\n * anyone has asked for. If one appears, add an explicit sentinel here — do\n * not overload `''`, which cannot survive the form stack.\n */\nexport function resolveSocialImage(options: {\n  sources: Array<SocialImageSource | null | undefined>\n  host?: SocialImageHost | null | undefined\n  /**\n   * The origin to absolutize a site-relative URL against, for a surface that\n   * is not a tenant site and therefore has no host record to derive one from\n   * (AGL-876: the console's marketplace listing card).\n   *\n   * Takes precedence over the host, so a caller that has both is stating the\n   * origin it actually serves from rather than the one the host doc names.\n   * With neither, a relative URL still resolves to `undefined` — the rule in\n   * `absolutize` is unchanged, this only widens where the origin may come\n   * from.\n   */\n  origin?: string | null\n  /**\n   * What the named assets' DAM documents record now (AGL-2850). The winning\n   * source's pair comes from here when its own reference has a usable one,\n   * and from the copy stored beside the reference otherwise. A surface that\n   * read no documents omits it and emits the stored copy, as every surface\n   * did before.\n   */\n  assetFacts?: SocialImageAssetFacts | null\n}): ResolvedSocialImage | undefined {\n  const { sources, host, origin, assetFacts } = options\n  const source = sources.find((candidate) => Boolean(candidate?.image))\n  if (!source?.image) return undefined\n  // A `media:` reference becomes the site-relative CDN path, host-qualified\n  // so a restricted org asset resolves for the site actually rendering, and is\n  // then absolutized because a crawler reads `og:image` out of band; any other\n  // string passes through untouched (back-compat with the raw storage URLs the\n  // content and favicon pickers have always written). Both halves live in\n  // `media-ref.ts` (AGL-1407) so the manifest and the inbox share this rule\n  // rather than each keeping a copy that can drift.\n  const url = absoluteMediaSrc(source.image, {\n    hostId: host?.$id,\n    origin: origin || hostPublicOrigin(host),\n  })\n  if (!url) return undefined\n  return { url, ...currentDimensions(source, assetFacts), ...alt(source) }\n}\n"],"names":["hostPublicOrigin","MEDIA_ALT_MAX_LENGTH","absoluteMediaSrc","alt","source","value","imageAlt","trim","slice","dimensions","width","Number","imageWidth","height","imageHeight","isFinite","Math","round","currentDimensions","assetFacts","image","recorded","Object","prototype","hasOwnProperty","call","undefined","current","resolveSocialImage","options","sources","host","origin","find","candidate","Boolean","url","hostId","$id"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0FC,GAED,SAASA,gBAAgB,QAAQ,mBAAe;AAChD,SAASC,oBAAoB,QAAQ,sBAAkB;AACvD,SAASC,gBAAgB,QAAQ,iBAAa;AA2D9C;;;;;;;;;CASC,GACD,SAASC,IAAIC,MAAyB;IACpC,MAAMC,QAAQ,OAAOD,OAAOE,QAAQ,KAAK,WAAWF,OAAOE,QAAQ,CAACC,IAAI,KAAK;IAC7E,OAAOF,QAAQ;QAAEF,KAAKE,MAAMG,KAAK,CAAC,GAAGP;IAAsB,IAAI,CAAC;AAClE;AAEA;;;CAGC,GACD,SAASQ,WAAWL,MAAyB;IAI3C,MAAMM,QAAQC,OAAOP,OAAOQ,UAAU;IACtC,MAAMC,SAASF,OAAOP,OAAOU,WAAW;IACxC,IAAI,CAACH,OAAOI,QAAQ,CAACL,UAAU,CAACC,OAAOI,QAAQ,CAACF,SAAS,OAAO,CAAC;IACjE,IAAIH,SAAS,KAAKG,UAAU,GAAG,OAAO,CAAC;IACvC,OAAO;QAAEH,OAAOM,KAAKC,KAAK,CAACP;QAAQG,QAAQG,KAAKC,KAAK,CAACJ;IAAQ;AAChE;AAEA;;;;;CAKC,GACD,SAASK,kBACPd,MAAyB,EACzBe,UAAoD;QAEtCf;IAAd,MAAMgB,SAAQhB,gBAAAA,OAAOgB,KAAK,YAAZhB,gBAAgB;IAC9B,MAAMiB,WACJF,cAAcG,OAAOC,SAAS,CAACC,cAAc,CAACC,IAAI,CAACN,YAAYC,SAC3DD,UAAU,CAACC,MAAM,GACjBM;IACN,MAAMC,UAA+CN,WACjDZ,WAAW;QAAEG,YAAYS,SAASX,KAAK;QAAEI,aAAaO,SAASR,MAAM;IAAC,KACtE,CAAC;IACL,OAAOc,QAAQjB,KAAK,KAAKgB,YAAYjB,WAAWL,UAAUuB;AAC5D;AAEA;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASC,mBAAmBC,OAuBlC;IACC,MAAM,EAAEC,OAAO,EAAEC,IAAI,EAAEC,MAAM,EAAEb,UAAU,EAAE,GAAGU;IAC9C,MAAMzB,SAAS0B,QAAQG,IAAI,CAAC,CAACC,YAAcC,QAAQD,6BAAAA,UAAWd,KAAK;IACnE,IAAI,EAAChB,0BAAAA,OAAQgB,KAAK,GAAE,OAAOM;IAC3B,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,wEAAwE;IACxE,0EAA0E;IAC1E,kDAAkD;IAClD,MAAMU,MAAMlC,iBAAiBE,OAAOgB,KAAK,EAAE;QACzCiB,MAAM,EAAEN,wBAAAA,KAAMO,GAAG;QACjBN,QAAQA,UAAUhC,iBAAiB+B;IACrC;IACA,IAAI,CAACK,KAAK,OAAOV;IACjB,OAAO;QAAEU;OAAQlB,kBAAkBd,QAAQe,aAAgBhB,IAAIC;AACjE"}

package/src/lib/app-utils/starter-templates.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @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.
+ */
+/**
+ * First-party starter definitions (AGL-78/79), SEED INPUT (AGL-687).
+ *
+ * These used to be rendered straight into the gallery and instantiated from
+ * code, which made a starter a second kind of template: no version history,
+ * no placeholders, no editor, changeable only by shipping a release. Now
+ * they are seeded into each host's own template library as ordinary
+ * `hosts/{hostId}/templates` documents (see the console's
+ * `utils/server/seed-starter-templates.ts` for why copy-on-use rather than a
+ * global read-only collection), and nothing reads this file at render time.
+ *
+ * They are also the page examples the AI plugin's template generator shows a
+ * model (AGL-2909), which is why they live in the core package rather than
+ * beside the console gallery that renders them.
+ *
+ * Node ids stay template-local (unique within each screen's version doc);
+ * `createPageFromTemplate` re-keys screen and version ids at instantiation.
+ *
+ * PERSISTED IDENTIFIERS: `StarterTemplate.id`, `StarterTemplateScreen.key`
+ * and every node id below appear in stored documents (seeded template doc
+ * ids are derived from the first two). They must never be renamed.
+ */
+export interface StarterTemplateScreen {
+    /**
+     * Stable, starter-local key. Part of the seeded document id, so it is a
+     * persisted identifier — never rename one.
+     */
+    key: string;
+    displayName: string;
+    description?: string;
+    /**
+     * Routing-map slug. `SCREEN_ROOT_PATH` (`'/'`) asks for the site root — the
+     * home page — and anything else is a single path segment.
+     *
+     * It used to be `''` that meant home, which no normalizer agreed with: both
+     * the apply path and the seed below read an empty string as "no address
+     * authored" and derived one from the display name, so the shop starters'
+     * home page was published at `/home` and the site 404'd at its own URL
+     * (AGL-1575).
+     */
+    slug: string;
+    seo?: {
+        title?: string;
+        description?: string;
+    };
+    /** Flat node map including the canvas root. */
+    nodes: Record<string, any>;
+}
+export interface StarterTemplate {
+    id: string;
+    displayName: string;
+    description: string;
+    category: string;
+    screens: StarterTemplateScreen[];
+}
+/** A materialized starter template document, keyed by its deterministic id. */
+export interface StarterTemplateDoc {
+    id: string;
+    /** Which starter this page belongs to — lets one starter be selected. */
+    starterId: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Deterministic document id for a seeded starter screen (AGL-687).
+ *
+ * Derived from the starter id and the screen key — never randomly generated
+ * — so re-running the seed addresses the same documents instead of stacking
+ * duplicate copies of every starter on every run.
+ */
+export declare function starterTemplateDocId(starterId: string, screenKey: string): string;
+/**
+ * Expands one starter into the template documents it seeds as.
+ *
+ * One page template per screen, matching what a marketplace install of a
+ * multi-screen site template already produces (AGL-669) — the alternative,
+ * a bespoke multi-page template shape, would be a third lifecycle on top of
+ * the two this issue exists to merge. The bundle's name/description/order
+ * ride `source` so the gallery can still present the starter as one card.
+ */
+export declare function buildStarterTemplateDocs(starter: StarterTemplate): StarterTemplateDoc[];
+/** Every document a starter COULD materialize as, in bundle order. */
+export declare function buildAllStarterTemplateDocs(): StarterTemplateDoc[];
+export declare const STARTER_TEMPLATES: StarterTemplate[];