@certrev/cert-block 1.2.0-canary.6 → 1.2.0

package/dist/builder/ssr-seed.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The server render's envelope seed (1.2.0): what lets a hydrated delivery card paint with NO browser read.
+ *
+ * Through 1.1.1 the browser re-read the Delivery API for every card it hydrated, because nothing handed the server's
+ * read to it. A storefront whose Content-Security-Policy `connect-src` does not name the CertREV origin (e.l.f.'s
+ * Hydrogen store is one) blocked that read, the read settled as a suppress, and the card the server had painted
+ * vanished. So the painted face now carries the envelope it was painted from, as one attribute on its wrapper:
+ * `data-certrev-envelope` = `{ v: 1, baseUrl, externalId, design?, payload, signature?, renderDef }`. `payload` is the
+ * signed envelope's payload as the Delivery API served it, less the fields the def hides (below); `renderDef` is the
+ * def the face was painted with; `design` is the design pin the read was made with (the canary replica's `?design=N`),
+ * present only on a pinned read. React escapes the attribute like any other, so no `<script>` and no CSP `script-src`
+ * are involved.
+ *
+ * HIDDEN FIELDS ARE ABSENT FROM THE PAGE, NOT JUST FROM THE FACE. A def's `hidden` set (`reviewerPhoto`, `memo`) is the
+ * brand's statement that the page does not show those fields; a seed that carried them would put the reviewer's photo
+ * URL or the memo text in the page source all the same. So `withoutHiddenContent` removes them from the payload
+ * BEFORE the card paints and before it serializes, and both the server's face and the browser's are painted from the
+ * stripped payload (so they are identical, and a hidden memo is not on the page in either place):
+ *  - `reviewerPhoto` hides `content.expert.photoUrl` and the author's `content.author.photoUrl` (the reader face paints
+ *    the author's photo under the same switch);
+ *  - `memo` hides `content.memo`.
+ * `display.showExpertPhoto: false` is the payload's own switch for the same photos and is stripped the same way (the
+ * portal never writes the URL for it either): both photo URLs go, as for `reviewerPhoto`, whatever the def hides.
+ * `content.expert.compensationCue` is NEVER touched: the cue is a locked disclosure no def can hide, and the face
+ * paints "Compensated expert" from it in the banner, the memo and the sidebar (the floating pill's own markup has
+ * no disclosure line, as in the portal's snippets; its modal paints the cue from the same field).
+ *
+ * THE SIGNATURE IS LEFT OUT WHENEVER ANYTHING WAS STRIPPED. The signature signs the full payload, so a payload with a
+ * field removed no longer verifies against it, and a seed that carried both would hand a verifier a pair that fails.
+ * Leaving it out costs nothing: the browser never re-checks a seed's signature (next paragraph), it re-runs only
+ * `renderVerdict` (lifecycle and subject) at its own clock, and neither reads a field the strip removes. A seed whose
+ * payload was not stripped keeps the signature, so a verifier can still check the page's HTML against the issuer key.
+ *
+ * The browser trusts a seed as far as it trusts the server HTML the seed sits in: whoever can write that HTML can
+ * already write any card they like, so the signature is NOT re-verified here (which would make hydration async, and
+ * Ed25519 in WebCrypto is not in every browser). The client still re-runs the lifecycle and subject policy
+ * (`renderVerdict`) at its own clock once hydration is done; `cert-review-card.tsx` does that.
+ *
+ * A PINNED CARD TAKES ONLY A SEED WITH THE SAME PIN (and an unpinned card only an unpinned one): the pin is part of
+ * the seed's key, as it is part of the read's, so the canary replica's `?design=7` card never paints the design the
+ * page carried for another version.
+ *
+ * WHEN THE SERVER HAD NO ENVELOPE TO PAINT (1.2.0) the same attribute carries a fallback record instead of a seed:
+ * `{ v: 1, baseUrl, externalId, design?, face }`, where `face` is `'options'` (CertREV could not be reached, so the
+ * server painted the block's own options face) or `'none'` (the server painted nothing: revoked, expired, unverifiable,
+ * for another entry). A browser that renders the card again (hydration, or React's client re-render after a hydration
+ * error elsewhere on the page) paints what the record says, so it neither reads the Delivery API nor shows a card the
+ * server withheld. A record holds no payload, so `parseSeed` never takes one for a seed. A `'none'` record sits on a
+ * `hidden` element with nothing in it.
+ *
+ * React-free and browser-only in effect: with no `document` (a server) `pageSeedFor` finds nothing, so a server never
+ * reads or keeps a seed and a multi-tenant render process holds nothing per page.
+ */
+import type { CertPayload, CertSignature } from '../contract/kernel.js';
+import { type DesignPin } from '../verify/get-verified-delivery.js';
+import type { CertChromeRenderDef } from './cert-chrome-data.js';
+export declare const SEED_ATTRIBUTE = "data-certrev-envelope";
+export interface DeliverySeed {
+    readonly baseUrl: string;
+    readonly externalId: string;
+    /** The design pin the read was made with; absent on an unpinned read (every production brand). */
+    readonly design?: DesignPin;
+    /** The payload as painted: with every field the def hides removed (`withoutHiddenContent`). */
+    readonly payload: CertPayload;
+    /**
+     * The envelope's signature as served; absent when the payload was stripped (it no longer verifies), and when a
+     * cache was filled by hand (a test, a custom cache).
+     */
+    readonly signature?: CertSignature;
+    readonly renderDef: CertChromeRenderDef | null;
+}
+/** A seed as read from the page: the parsed seed and the attribute's exact text (re-rendered verbatim on hydration). */
+export interface PageSeed {
+    readonly seed: DeliverySeed;
+    readonly raw: string;
+}
+/** What the server painted with no verified envelope: the block's options face, or nothing. */
+export type FallbackFace = 'options' | 'none';
+/** The record a server writes where it had no envelope to paint (the file header). */
+export interface DeliveryFallback {
+    readonly baseUrl: string;
+    readonly externalId: string;
+    readonly design?: DesignPin;
+    readonly face: FallbackFace;
+}
+/** A fallback record as read from the page, with the attribute's exact text. */
+export interface PageFallback {
+    readonly fallback: DeliveryFallback;
+    readonly raw: string;
+}
+/** Whatever the server wrote for one placement: a seed or a fallback record. */
+export type PageRecord = PageSeed | PageFallback;
+/**
+ * The payload with the named people's photo URLs removed (`null`); the same object when neither had one. The card uses
+ * it for a photo the browser could not load (a brand's CSP `img-src`, a 404), so the face repaints with the initials.
+ */
+export declare function withoutPhotos(payload: CertPayload, people: readonly ('expert' | 'author')[]): CertPayload;
+/**
+ * The payload with every content field the def's `hidden` set controls removed, and whether anything was; the two
+ * photo URLs go as well when the payload's own `display.showExpertPhoto` is `false` (exactly `false`, as the reader
+ * face reads it: absent or `null` shows the photo).
+ *
+ * Only the ids in `HIDEABLE_FIELDS` count (a def may list others; the faces ignore them, so they hide nothing). A
+ * removed text field becomes `null`, so the content keeps the shape the contract types give it and every face reads it
+ * as absent. Nothing but those fields changes: the subject and lifecycle (what `renderVerdict` reads), the cue, the
+ * dates, the links and the names are the payload's own. Never throws on a hostile shape: a payload whose `expert` or
+ * `author` is not an object has no photo to strip.
+ */
+export declare function withoutHiddenContent(payload: CertPayload, renderDef: CertChromeRenderDef | null): {
+    readonly payload: CertPayload;
+    readonly stripped: boolean;
+};
+/**
+ * The seed for a verified read: the payload stripped of what the def hides, and the signature only when nothing was
+ * stripped. The card paints from this seed's payload, on the server and in the browser alike.
+ */
+export declare function seedFor(read: {
+    readonly baseUrl: string;
+    readonly externalId: string;
+    readonly design?: DesignPin;
+    readonly payload: CertPayload;
+    readonly signature?: CertSignature;
+    readonly renderDef: CertChromeRenderDef | null;
+}): DeliverySeed;
+export declare function serializeSeed(seed: DeliverySeed): string;
+export declare function serializeFallback(fallback: DeliveryFallback): string;
+/** The seed in one attribute value, or null for anything that is not one (never throws). */
+export declare function parseSeed(raw: string): DeliverySeed | null;
+/** A fallback record in one attribute value, or null for anything that is not one (a seed included; never throws). */
+export declare function parseFallback(raw: string): DeliveryFallback | null;
+/**
+ * The record the server wrote for this placement and pin: its seed, or its fallback record. By default: from the map,
+ * else from one scan of the document (which also records every other one on the page). With `live`, the map is not
+ * consulted: the document is scanned and decides, so what a hydrating card learns is what the server HTML in front of
+ * it carries, not what an earlier page in this process left behind. `undefined` when the page carries none, and always
+ * on a server.
+ */
+export declare function pageRecordFor(baseUrl: string, externalId: string, design?: DesignPin, options?: {
+    readonly live?: boolean;
+}): PageRecord | undefined;
+/** `pageRecordFor`, seeds only: the seed the server painted for this placement and pin. */
+export declare function pageSeedFor(baseUrl: string, externalId: string, design?: DesignPin, options?: {
+    readonly live?: boolean;
+}): PageSeed | undefined;
+/**
+ * Whether the live document holds server-rendered React HTML: any Suspense boundary marker. The delivery card sits in
+ * a `<Suspense>` of its own, so a server render of one always leaves a marker, a card the server painted nothing for
+ * (revoked, expired, unreachable) included, and a client render never does. This is how a card that is hydrating tells
+ * a browser hydrating server HTML (the document holds it) from a server render that merely runs where a `document`
+ * exists (a test's jsdom, a shim): there the document does not hold the HTML being produced.
+ */
+export declare function pageHoldsServerHtml(): boolean;
+/** Test seam: forget every seed (a new page). */
+export declare function forgetPageSeedsForTests(): void;
+//# sourceMappingURL=ssr-seed.d.ts.map

package/dist/builder/ssr-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-seed.d.ts","sourceRoot":"","sources":["../../src/builder/ssr-seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAGH,OAAO,KAAK,EAAe,WAAW,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACpF,OAAO,EAAE,KAAK,SAAS,EAAkC,MAAM,oCAAoC,CAAA;AACnG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,eAAO,MAAM,cAAc,0BAA0B,CAAA;AAErD,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,kGAAkG;IAClG,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;IAC3B,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,mBAAmB,GAAG,IAAI,CAAA;CAC9C;AAED,wHAAwH;AACxH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACpB;AAED,+FAA+F;AAC/F,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,CAAA;AAE7C,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAC3B;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACpB;AAED,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,YAAY,CAAA;AAOhD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,QAAQ,GAAG,QAAQ,CAAC,EAAE,GAAG,WAAW,CAWzG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,mBAAmB,GAAG,IAAI,GACnC;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAU/D;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,mBAAmB,GAAG,IAAI,CAAA;CAC9C,GAAG,YAAY,CAUf;AAKD,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAUxD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAQpE;AAWD,4FAA4F;AAC5F,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAwB1D;AAED,sHAAsH;AACtH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAclE;AAiCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,SAAS,EAClB,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GACvC,UAAU,GAAG,SAAS,CAaxB;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAC1B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,SAAS,EAClB,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GACvC,QAAQ,GAAG,SAAS,CAGtB;AAKD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAO7C;AAED,iDAAiD;AACjD,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/dist/builder/ssr-seed.js

@@ -0,0 +1,278 @@
+/**
+ * The server render's envelope seed (1.2.0): what lets a hydrated delivery card paint with NO browser read.
+ *
+ * Through 1.1.1 the browser re-read the Delivery API for every card it hydrated, because nothing handed the server's
+ * read to it. A storefront whose Content-Security-Policy `connect-src` does not name the CertREV origin (e.l.f.'s
+ * Hydrogen store is one) blocked that read, the read settled as a suppress, and the card the server had painted
+ * vanished. So the painted face now carries the envelope it was painted from, as one attribute on its wrapper:
+ * `data-certrev-envelope` = `{ v: 1, baseUrl, externalId, design?, payload, signature?, renderDef }`. `payload` is the
+ * signed envelope's payload as the Delivery API served it, less the fields the def hides (below); `renderDef` is the
+ * def the face was painted with; `design` is the design pin the read was made with (the canary replica's `?design=N`),
+ * present only on a pinned read. React escapes the attribute like any other, so no `<script>` and no CSP `script-src`
+ * are involved.
+ *
+ * HIDDEN FIELDS ARE ABSENT FROM THE PAGE, NOT JUST FROM THE FACE. A def's `hidden` set (`reviewerPhoto`, `memo`) is the
+ * brand's statement that the page does not show those fields; a seed that carried them would put the reviewer's photo
+ * URL or the memo text in the page source all the same. So `withoutHiddenContent` removes them from the payload
+ * BEFORE the card paints and before it serializes, and both the server's face and the browser's are painted from the
+ * stripped payload (so they are identical, and a hidden memo is not on the page in either place):
+ *  - `reviewerPhoto` hides `content.expert.photoUrl` and the author's `content.author.photoUrl` (the reader face paints
+ *    the author's photo under the same switch);
+ *  - `memo` hides `content.memo`.
+ * `display.showExpertPhoto: false` is the payload's own switch for the same photos and is stripped the same way (the
+ * portal never writes the URL for it either): both photo URLs go, as for `reviewerPhoto`, whatever the def hides.
+ * `content.expert.compensationCue` is NEVER touched: the cue is a locked disclosure no def can hide, and the face
+ * paints "Compensated expert" from it in the banner, the memo and the sidebar (the floating pill's own markup has
+ * no disclosure line, as in the portal's snippets; its modal paints the cue from the same field).
+ *
+ * THE SIGNATURE IS LEFT OUT WHENEVER ANYTHING WAS STRIPPED. The signature signs the full payload, so a payload with a
+ * field removed no longer verifies against it, and a seed that carried both would hand a verifier a pair that fails.
+ * Leaving it out costs nothing: the browser never re-checks a seed's signature (next paragraph), it re-runs only
+ * `renderVerdict` (lifecycle and subject) at its own clock, and neither reads a field the strip removes. A seed whose
+ * payload was not stripped keeps the signature, so a verifier can still check the page's HTML against the issuer key.
+ *
+ * The browser trusts a seed as far as it trusts the server HTML the seed sits in: whoever can write that HTML can
+ * already write any card they like, so the signature is NOT re-verified here (which would make hydration async, and
+ * Ed25519 in WebCrypto is not in every browser). The client still re-runs the lifecycle and subject policy
+ * (`renderVerdict`) at its own clock once hydration is done; `cert-review-card.tsx` does that.
+ *
+ * A PINNED CARD TAKES ONLY A SEED WITH THE SAME PIN (and an unpinned card only an unpinned one): the pin is part of
+ * the seed's key, as it is part of the read's, so the canary replica's `?design=7` card never paints the design the
+ * page carried for another version.
+ *
+ * WHEN THE SERVER HAD NO ENVELOPE TO PAINT (1.2.0) the same attribute carries a fallback record instead of a seed:
+ * `{ v: 1, baseUrl, externalId, design?, face }`, where `face` is `'options'` (CertREV could not be reached, so the
+ * server painted the block's own options face) or `'none'` (the server painted nothing: revoked, expired, unverifiable,
+ * for another entry). A browser that renders the card again (hydration, or React's client re-render after a hydration
+ * error elsewhere on the page) paints what the record says, so it neither reads the Delivery API nor shows a card the
+ * server withheld. A record holds no payload, so `parseSeed` never takes one for a seed. A `'none'` record sits on a
+ * `hidden` element with nothing in it.
+ *
+ * React-free and browser-only in effect: with no `document` (a server) `pageSeedFor` finds nothing, so a server never
+ * reads or keeps a seed and a multi-tenant render process holds nothing per page.
+ */
+import { HIDEABLE_FIELDS } from '../components/render-def.js';
+import { parseDesignPin, parseRenderDef } from '../verify/get-verified-delivery.js';
+export const SEED_ATTRIBUTE = 'data-certrev-envelope';
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** A value worth hiding: anything but nothing (absent, null, the empty string). */
+const hasValue = (v) => v !== undefined && v !== null && v !== '';
+/**
+ * The payload with the named people's photo URLs removed (`null`); the same object when neither had one. The card uses
+ * it for a photo the browser could not load (a brand's CSP `img-src`, a 404), so the face repaints with the initials.
+ */
+export function withoutPhotos(payload, people) {
+    let content = { ...payload.content };
+    let stripped = false;
+    for (const person of people) {
+        const fields = content[person];
+        if (isRecord(fields) && hasValue(fields.photoUrl)) {
+            content = { ...content, [person]: { ...fields, photoUrl: null } };
+            stripped = true;
+        }
+    }
+    return stripped ? { ...payload, content: content } : payload;
+}
+/**
+ * The payload with every content field the def's `hidden` set controls removed, and whether anything was; the two
+ * photo URLs go as well when the payload's own `display.showExpertPhoto` is `false` (exactly `false`, as the reader
+ * face reads it: absent or `null` shows the photo).
+ *
+ * Only the ids in `HIDEABLE_FIELDS` count (a def may list others; the faces ignore them, so they hide nothing). A
+ * removed text field becomes `null`, so the content keeps the shape the contract types give it and every face reads it
+ * as absent. Nothing but those fields changes: the subject and lifecycle (what `renderVerdict` reads), the cue, the
+ * dates, the links and the names are the payload's own. Never throws on a hostile shape: a payload whose `expert` or
+ * `author` is not an object has no photo to strip.
+ */
+export function withoutHiddenContent(payload, renderDef) {
+    const hidden = (renderDef?.hidden ?? []).filter((id) => HIDEABLE_FIELDS.includes(id));
+    const display = payload.content?.display;
+    const photoOff = isRecord(display) && display.showExpertPhoto === false;
+    if (hidden.length === 0 && !photoOff)
+        return { payload, stripped: false };
+    let next = photoOff || hidden.includes('reviewerPhoto') ? withoutPhotos(payload, ['expert', 'author']) : payload;
+    if (hidden.includes('memo') && hasValue(next.content.memo)) {
+        next = { ...next, content: { ...next.content, memo: null } };
+    }
+    return { payload: next, stripped: next !== payload };
+}
+/**
+ * The seed for a verified read: the payload stripped of what the def hides, and the signature only when nothing was
+ * stripped. The card paints from this seed's payload, on the server and in the browser alike.
+ */
+export function seedFor(read) {
+    const { payload, stripped } = withoutHiddenContent(read.payload, read.renderDef);
+    return {
+        baseUrl: read.baseUrl,
+        externalId: read.externalId,
+        ...(read.design ? { design: read.design } : {}),
+        payload,
+        ...(read.signature && !stripped ? { signature: read.signature } : {}),
+        renderDef: read.renderDef,
+    };
+}
+const serializedPin = (design) => design ? { design: { version: design.version, ...(design.brand === undefined ? {} : { brand: design.brand }) } } : {};
+export function serializeSeed(seed) {
+    return JSON.stringify({
+        v: 1,
+        baseUrl: seed.baseUrl,
+        externalId: seed.externalId,
+        ...serializedPin(seed.design),
+        payload: seed.payload,
+        ...(seed.signature ? { signature: seed.signature } : {}),
+        renderDef: seed.renderDef,
+    });
+}
+export function serializeFallback(fallback) {
+    return JSON.stringify({
+        v: 1,
+        baseUrl: fallback.baseUrl,
+        externalId: fallback.externalId,
+        ...serializedPin(fallback.design),
+        face: fallback.face,
+    });
+}
+/** A pin a record names, judged by the same grammar the card's own pin is: undefined when absent, null when bad. */
+function parsedPin(design) {
+    if (design === undefined)
+        return undefined;
+    const judged = isRecord(design)
+        ? parseDesignPin({ design: design.version, ...(design.brand === undefined ? {} : { designBrand: design.brand }) })
+        : 'invalid';
+    return judged === 'invalid' || judged === undefined ? null : judged;
+}
+/** The seed in one attribute value, or null for anything that is not one (never throws). */
+export function parseSeed(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(value) || value.v !== 1)
+        return null;
+    const { baseUrl, externalId, design, payload, signature, renderDef } = value;
+    if (typeof baseUrl !== 'string' || typeof externalId !== 'string')
+        return null;
+    if (!isRecord(payload) || !isRecord(payload.subject) || !isRecord(payload.lifecycle) || !isRecord(payload.content)) {
+        return null;
+    }
+    // A pin the seed names is judged by the same grammar the card's own pin is; one that fails it is not a seed.
+    const pin = parsedPin(design);
+    if (pin === null)
+        return null;
+    return {
+        baseUrl,
+        externalId,
+        ...(pin ? { design: pin } : {}),
+        payload: payload,
+        ...(isRecord(signature) ? { signature: signature } : {}),
+        renderDef: parseRenderDef(renderDef),
+    };
+}
+/** A fallback record in one attribute value, or null for anything that is not one (a seed included; never throws). */
+export function parseFallback(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(value) || value.v !== 1 || 'payload' in value)
+        return null;
+    const { baseUrl, externalId, design, face } = value;
+    if (typeof baseUrl !== 'string' || typeof externalId !== 'string')
+        return null;
+    if (face !== 'options' && face !== 'none')
+        return null;
+    const pin = parsedPin(design);
+    if (pin === null)
+        return null;
+    return { baseUrl, externalId, ...(pin ? { design: pin } : {}), face };
+}
+/** One placement's key: the origin, the entry and the pin (the read's own key, so a pin never shares a seed). */
+function seedKey(baseUrl, externalId, design) {
+    return design ? `${baseUrl}|${externalId}|design=${design.version}|${design.brand ?? ''}` : `${baseUrl}|${externalId}`;
+}
+/**
+ * The seeds (and fallback records) this page's server HTML carried, by placement, for the page's lifetime: a card
+ * mounted later by a client-side render (an in-app navigation back to a server-rendered article, or React's client
+ * re-render after a hydration error) paints what the server painted, as the hydrated card it replaces would have.
+ */
+const pageSeeds = new Map();
+const recordKey = (record) => {
+    const r = 'seed' in record ? record.seed : record.fallback;
+    return seedKey(r.baseUrl, r.externalId, r.design);
+};
+/** Every seed and fallback record the live document carries, in document order. */
+function scanDocument() {
+    const found = [];
+    for (const el of Array.from(document.querySelectorAll(`[${SEED_ATTRIBUTE}]`))) {
+        const raw = el.getAttribute(SEED_ATTRIBUTE);
+        if (!raw)
+            continue;
+        const seed = parseSeed(raw);
+        const fallback = seed ? null : parseFallback(raw);
+        if (seed)
+            found.push({ seed, raw });
+        else if (fallback)
+            found.push({ fallback, raw });
+    }
+    return found;
+}
+/**
+ * The record the server wrote for this placement and pin: its seed, or its fallback record. By default: from the map,
+ * else from one scan of the document (which also records every other one on the page). With `live`, the map is not
+ * consulted: the document is scanned and decides, so what a hydrating card learns is what the server HTML in front of
+ * it carries, not what an earlier page in this process left behind. `undefined` when the page carries none, and always
+ * on a server.
+ */
+export function pageRecordFor(baseUrl, externalId, design, options = {}) {
+    const key = seedKey(baseUrl, externalId, design);
+    if (typeof document === 'undefined')
+        return undefined;
+    const known = options.live ? undefined : pageSeeds.get(key);
+    if (known)
+        return known;
+    let inDocument = false;
+    for (const found of scanDocument()) {
+        const k = recordKey(found);
+        if (k === key)
+            inDocument = true;
+        if (options.live || !pageSeeds.has(k))
+            pageSeeds.set(k, found);
+    }
+    // A live read answers for the document alone: a record an earlier page left in the map is not one this page carries.
+    return options.live && !inDocument ? undefined : pageSeeds.get(key);
+}
+/** `pageRecordFor`, seeds only: the seed the server painted for this placement and pin. */
+export function pageSeedFor(baseUrl, externalId, design, options = {}) {
+    const record = pageRecordFor(baseUrl, externalId, design, options);
+    return record && 'seed' in record ? record : undefined;
+}
+/** A Suspense boundary's comment marker as React's server render writes it: `$` (done), `$?` (pending), `$!`, `$~`. */
+const BOUNDARY_MARKER = /^\$[?!~]?$/;
+/**
+ * Whether the live document holds server-rendered React HTML: any Suspense boundary marker. The delivery card sits in
+ * a `<Suspense>` of its own, so a server render of one always leaves a marker, a card the server painted nothing for
+ * (revoked, expired, unreachable) included, and a client render never does. This is how a card that is hydrating tells
+ * a browser hydrating server HTML (the document holds it) from a server render that merely runs where a `document`
+ * exists (a test's jsdom, a shim): there the document does not hold the HTML being produced.
+ */
+export function pageHoldsServerHtml() {
+    if (typeof document === 'undefined' || !document.documentElement)
+        return false;
+    const walker = document.createTreeWalker(document.documentElement, 128 /* NodeFilter.SHOW_COMMENT */);
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        if (BOUNDARY_MARKER.test(node.data))
+            return true;
+    }
+    return false;
+}
+/** Test seam: forget every seed (a new page). */
+export function forgetPageSeedsForTests() {
+    pageSeeds.clear();
+}
+//# sourceMappingURL=ssr-seed.js.map

package/dist/builder/ssr-seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-seed.js","sourceRoot":"","sources":["../../src/builder/ssr-seed.ts"],"names":[],"mappings":"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"}

package/dist/reader/face.d.ts

@@ -2,11 +2,15 @@ export type ReaderFaceSize = '' | 'sm' | 'lg';
 export interface ReaderFaceInput {
     /** The photo URL on the envelope. */
     readonly photo: unknown;
-    /** Whether to ATTEMPT the photo: false never reads the URL (the silhouette shows). */
+    /** Whether to ATTEMPT the photo: false never reads the URL (the initials show). */
     readonly show: boolean;
+    /** The person's display name, the initials' source; a hostile type reads as no name. */
+    readonly name: unknown;
     readonly size: ReaderFaceSize;
     /** The pixel width the resizer is asked for. */
     readonly width: number;
 }
-export declare function readerFace({ photo, show, size, width }: ReaderFaceInput): string;
+/** The initials of a display name by the spec above: '' when the name leaves no first character to take. */
+export declare function initialsOf(name: unknown): string;
+export declare function readerFace({ photo, show, name, size, width }: ReaderFaceInput): string;
 //# sourceMappingURL=face.d.ts.map

package/dist/reader/face.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"face.d.ts","sourceRoot":"","sources":["../../src/reader/face.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;AAE7C,MAAM,WAAW,eAAe;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACtB;AAOD,wBAAgB,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,eAAe,GAAG,MAAM,CAUhF"}
+{"version":3,"file":"face.d.ts","sourceRoot":"","sources":["../../src/reader/face.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;AAE7C,MAAM,WAAW,eAAe;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACtB;AAoBD,4GAA4G;AAC5G,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAWhD;AAQD,wBAAgB,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,eAAe,GAAG,MAAM,CAatF"}

package/dist/reader/face.js

@@ -1,19 +1,67 @@
 /**
- * `certrev-reader-face`: the round avatar on a reader byline: the person's photo when there is one to show, the
- * silhouette when there is not. The span carries a size class (`sm` for the author, none for the banner reviewer,
- * `lg` for the memo and sidebar reviewer); the image is requested at `width` square through the asset resizer.
+ * `certrev-reader-face`: the round avatar on a reader byline: the person's photo when there is one to paint, else their
+ * initials, else (a person with no name to take them from) the silhouette. The span carries a size class (`sm` for the
+ * author, none for the banner reviewer, `lg` for the memo and sidebar reviewer); the image is requested at `width`
+ * square through the asset resizer.
+ *
+ * THE INITIALS ARE A BYTE SPEC the portal's Liquid snippets and the WordPress renderer repeat, so all three print the
+ * same bytes: trim the name and split it on single spaces (`' '`) SKIPPING empty parts (two spaces in a row are one
+ * gap: "Jane  Doe" gives "JD"); drop the FIRST part when, lowercased, it is one of the honorifics dr, mr, mrs, ms,
+ * prof, mx (each with or without its trailing dot); take the first character, by code point, of each of the first two
+ * parts left; uppercase them. Non-empty initials paint exactly
+ * `<svg viewBox="0 0 40 40" aria-hidden="true" focusable="false"><text x="20" y="20" text-anchor="middle"
+ * dominant-baseline="central" font-size="15" font-weight="700">JD</text></svg>` (one line, the initials escaped);
+ * empty ones paint the silhouette as before.
+ *
+ * "A photo to paint" is `show` with a URL that passes `safeUrl`. A def that hides `reviewerPhoto`, or
+ * `display.showExpertPhoto: false`, passes `show: false`: the URL is never read, so it never reaches the page, and the
+ * avatar is the initials (a hidden photo used to remove the avatar altogether; it removes the photo now).
  */
+import { asText } from '../components/escape.js';
 import { avatarUrl, cleaned, esc, safeUrl } from './helpers.js';
 const SILHOUETTE = '<svg viewBox="0 0 40 40" aria-hidden="true" focusable="false"><circle cx="20" cy="14.8" r="7"/><path d="M20 23.4c-6.9 0-12.6 4.8-13.8 11.2a20 20 0 0 0 27.6 0C32.6 28.2 26.9 23.4 20 23.4Z"/></svg>';
+const HONORIFICS = new Set([
+    'dr',
+    'dr.',
+    'mr',
+    'mr.',
+    'mrs',
+    'mrs.',
+    'ms',
+    'ms.',
+    'prof',
+    'prof.',
+    'mx',
+    'mx.',
+]);
+/** The initials of a display name by the spec above: '' when the name leaves no first character to take. */
+export function initialsOf(name) {
+    const parts = asText(name)
+        .trim()
+        .split(' ')
+        .filter((part) => part !== '');
+    if (HONORIFICS.has((parts[0] ?? '').toLowerCase()))
+        parts.shift();
+    return parts
+        .slice(0, 2)
+        .map((part) => Array.from(part)[0] ?? '')
+        .join('')
+        .toUpperCase();
+}
+const initialsSvg = (initials) => '<svg viewBox="0 0 40 40" aria-hidden="true" focusable="false"><text x="20" y="20" text-anchor="middle" ' +
+    `dominant-baseline="central" font-size="15" font-weight="700">${esc(initials)}</text></svg>`;
 const DIMENSION = { '': 42, sm: 36, lg: 46 };
-export function readerFace({ photo, show, size, width }) {
+export function readerFace({ photo, show, name, size, width }) {
     const safe = show ? cleaned(safeUrl(photo)) : '';
     const src = cleaned(avatarUrl(safe, width));
     const dim = DIMENSION[size];
     const cls = size === '' ? 'certrev-r-face' : `certrev-r-face ${esc(size)}`;
+    const initials = src !== '' ? '' : initialsOf(name);
     const inner = src !== ''
         ? `<img src="${esc(src)}" alt="" width="${dim}" height="${dim}" loading="lazy" decoding="async">`
-        : SILHOUETTE;
+        : initials !== ''
+            ? initialsSvg(initials)
+            : SILHOUETTE;
     return `<span class="${cls}">${inner}</span>`;
 }
 //# sourceMappingURL=face.js.map

package/dist/reader/face.js.map

@@ -1 +1 @@
-{"version":3,"file":"face.js","sourceRoot":"","sources":["../../src/reader/face.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAc/D,MAAM,UAAU,GACf,qMAAqM,CAAA;AAEtM,MAAM,SAAS,GAA6C,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAA;AAEtF,MAAM,UAAU,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAmB;IACvE,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;IAC3C,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAC3B,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,kBAAkB,GAAG,CAAC,IAAI,CAAC,EAAE,CAAA;IAC1E,MAAM,KAAK,GACV,GAAG,KAAK,EAAE;QACT,CAAC,CAAC,aAAa,GAAG,CAAC,GAAG,CAAC,mBAAmB,GAAG,aAAa,GAAG,oCAAoC;QACjG,CAAC,CAAC,UAAU,CAAA;IACd,OAAO,gBAAgB,GAAG,KAAK,KAAK,SAAS,CAAA;AAC9C,CAAC"}
+{"version":3,"file":"face.js","sourceRoot":"","sources":["../../src/reader/face.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAChD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAgB/D,MAAM,UAAU,GACf,qMAAqM,CAAA;AAEtM,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC;IAC/C,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,KAAK;IACL,KAAK;IACL,MAAM;IACN,IAAI;IACJ,KAAK;IACL,MAAM;IACN,OAAO;IACP,IAAI;IACJ,KAAK;CACL,CAAC,CAAA;AAEF,4GAA4G;AAC5G,MAAM,UAAU,UAAU,CAAC,IAAa;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC;SACxB,IAAI,EAAE;SACN,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,CAAA;IAC/B,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAAE,KAAK,CAAC,KAAK,EAAE,CAAA;IACjE,OAAO,KAAK;SACV,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACxC,IAAI,CAAC,EAAE,CAAC;SACR,WAAW,EAAE,CAAA;AAChB,CAAC;AAED,MAAM,WAAW,GAAG,CAAC,QAAgB,EAAU,EAAE,CAChD,yGAAyG;IACzG,gEAAgE,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAA;AAE7F,MAAM,SAAS,GAA6C,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAA;AAEtF,MAAM,UAAU,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAmB;IAC7E,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;IAC3C,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAC3B,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,kBAAkB,GAAG,CAAC,IAAI,CAAC,EAAE,CAAA;IAC1E,MAAM,QAAQ,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;IACnD,MAAM,KAAK,GACV,GAAG,KAAK,EAAE;QACT,CAAC,CAAC,aAAa,GAAG,CAAC,GAAG,CAAC,mBAAmB,GAAG,aAAa,GAAG,oCAAoC;QACjG,CAAC,CAAC,QAAQ,KAAK,EAAE;YAChB,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC;YACvB,CAAC,CAAC,UAAU,CAAA;IACf,OAAO,gBAAgB,GAAG,KAAK,KAAK,SAAS,CAAA;AAC9C,CAAC"}

package/dist/reader/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/reader/render.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAmBxD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAA;AAE5D,wHAAwH;AACxH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEnD,MAAM,WAAW,eAAe;IAC/B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,sGAAsG;IACtG,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;IAC1B,2GAA2G;IAC3G,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAC/B;AAiQD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAQ/D"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/reader/render.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAmBxD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAA;AAE5D,wHAAwH;AACxH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEnD,MAAM,WAAW,eAAe;IAC/B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,sGAAsG;IACtG,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;IAC1B,2GAA2G;IAC3G,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAC/B;AA+PD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAQ/D"}