react-native-revnix 1.4.0

package/dist/esm/blocks/color.js

@@ -0,0 +1,318 @@
+// Color handling for block paywalls.
+//
+// Two jobs the web renderer gets from CSS for free and React Native does not:
+//
+//  1. Palette TOKENS. Converted designs write `@accent`, `@text`, `@bg`,
+//     `@accentInk` (optionally with an alpha percentage: `@text/12`) so the
+//     four screen colors stay a single source of truth. The web renderer
+//     expands the percentage form with `color-mix()`; here we compute the
+//     rgba ourselves.
+//
+//  2. GRADIENTS. `background` is a CSS background string and may carry
+//     several gradient layers. React Native has no gradient primitive, so we
+//     parse the layers out: a host that supplies a gradient component renders
+//     them properly, and without one we fall back to the base layer's first
+//     color — a solid that keeps the screen on-palette instead of blank.
+import { backgroundBaseColor } from "./background.js";
+const TOKEN = /@(accentInk|accent|bg|text)(?:\/(\d{1,3}))?/g;
+/** Expands palette tokens in a color string and applies any `/pct` alpha. */
+export function resolveColor(value, doc) {
+    if (value === undefined)
+        return undefined;
+    if (!value.includes("@"))
+        return value;
+    return value.replace(TOKEN, (_match, name, pct) => {
+        const base = name === "accentInk"
+            ? doc.accentInk
+            : name === "accent"
+                ? doc.accent
+                : name === "bg"
+                    ? backgroundBaseColor(doc.background)
+                    : doc.textColor;
+        return pct === undefined ? base : withAlpha(base, Number(pct) / 100);
+    });
+}
+/** Multiplies a color's alpha. Understands #rgb/#rgba/#rrggbb/#rrggbbaa and
+ *  rgb()/rgba(); anything else (a named color, a gradient) is returned as-is
+ *  rather than guessed at. */
+export function withAlpha(color, alpha) {
+    const rgb = toRgb(color);
+    if (!rgb)
+        return color;
+    const a = Math.max(0, Math.min(1, rgb.a * alpha));
+    return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${round(a)})`;
+}
+function round(n) {
+    return Math.round(n * 1000) / 1000;
+}
+export function toRgb(color) {
+    const value = color.trim();
+    if (value.startsWith("#")) {
+        const hex = value.slice(1);
+        const expand = (c) => parseInt(c + c, 16);
+        if (!/^[0-9a-fA-F]+$/.test(hex))
+            return null;
+        if (hex.length === 3 || hex.length === 4) {
+            return {
+                r: expand(hex[0]),
+                g: expand(hex[1]),
+                b: expand(hex[2]),
+                a: hex.length === 4 ? expand(hex[3]) / 255 : 1,
+            };
+        }
+        if (hex.length === 6 || hex.length === 8) {
+            const byte = (i) => parseInt(hex.slice(i, i + 2), 16);
+            return {
+                r: byte(0),
+                g: byte(2),
+                b: byte(4),
+                a: hex.length === 8 ? byte(6) / 255 : 1,
+            };
+        }
+        return null;
+    }
+    const fn = value.match(/^rgba?\(([^)]+)\)$/i);
+    if (fn) {
+        const parts = fn[1].split(/[,/\s]+/).filter(Boolean).map(Number);
+        if (parts.length < 3 || parts.slice(0, 3).some(Number.isNaN))
+            return null;
+        return {
+            r: parts[0],
+            g: parts[1],
+            b: parts[2],
+            a: parts.length > 3 && !Number.isNaN(parts[3]) ? parts[3] : 1,
+        };
+    }
+    return null;
+}
+/**
+ * Whether a paint string's BOTTOM layer is a repeating pattern.
+ *
+ * A `repeating-*` gradient is a TEXTURE, and the colors inside it are stripe
+ * colors rather than the surface's. React Native cannot draw one, and painting
+ * a color lifted out of its arguments across the whole box is a WRONG answer
+ * rather than a degraded one — the library's hairline grid is one color every
+ * 26px, and as a solid fill it is a slab. Such a fill paints nothing instead.
+ *
+ * The bottom layer decides, so a pattern stacked over a real ground
+ * (`repeating-…(…), #FBF3E4`) still falls back to that ground.
+ */
+export function isRepeatingPattern(value) {
+    const s = value?.trim() ?? "";
+    if (!s)
+        return false;
+    const layers = splitLayers(s);
+    const bottom = layers.length > 0 ? layers[layers.length - 1] : s;
+    return /^repeating-/i.test(bottom);
+}
+/** True when the string is a CSS gradient rather than a plain color. */
+export function isGradient(value) {
+    return /gradient\s*\(/i.test(value);
+}
+/** Splits a CSS background into its gradient layers. Layers CSS paints last
+ *  (the base) come last in the returned array, matching source order. */
+export function parseGradient(value) {
+    const layers = [];
+    for (const raw of splitLayers(value)) {
+        const match = raw.match(/^(linear|radial)-gradient\s*\(([\s\S]*)\)$/i);
+        if (!match) {
+            // A plain color among the layers is the design's ground. Dropping it
+            // would leave the screen painted by a translucent glow instead.
+            //
+            // It has to LOOK like a color, though: any other layer — a
+            // `repeating-linear-gradient`, a `url()` — used to be accepted here and
+            // handed to the host's gradient component as a color string, which is not
+            // one. Dropping it instead is what lets the caller see there is nothing
+            // paintable and degrade to a flat color.
+            if (raw && hasColor(raw)) {
+                layers.push({ kind: "solid", angle: 180, colors: [raw] });
+            }
+            continue;
+        }
+        const kind = match[1].toLowerCase();
+        const args = splitTop(match[2]);
+        // A radial's center is dropped (RN has no radial gradient), so it is drawn
+        // as a top-down fade — 180deg, like every other default.
+        let angle = 180;
+        let start = 0;
+        let center;
+        const first = args[0]?.trim() ?? "";
+        if (kind === "linear" && /^-?[\d.]+deg$/i.test(first)) {
+            angle = parseFloat(first);
+            start = 1;
+        }
+        else if (kind === "linear" && /^to\s+/i.test(first)) {
+            angle = TO_ANGLE[first.trim().toLowerCase()] ?? 180;
+            start = 1;
+        }
+        else if (kind === "radial" && !hasColor(first)) {
+            // Radial shape/position prelude ("120% 90% at 85% 5%"). RN has no
+            // radial gradient, but the centre decides which way the stand-in fades,
+            // so it is kept rather than dropped with the rest.
+            center = readCenter(first);
+            start = 1;
+        }
+        const colors = [];
+        const locations = [];
+        let positioned = 0;
+        for (const arg of args.slice(start)) {
+            // CSS allows TWO positions on one stop — `@accent 0 22%` is the same
+            // color at both, the hard edge the library's progress bars and split
+            // panels are drawn with — and a unitless `0` is a valid position. Reading
+            // only the last one left those designs a smooth fade instead of an edge.
+            let body = arg.trim();
+            const positions = [];
+            while (positions.length < 2) {
+                const found = body.match(/\s(-?[\d.]+%|0)$/);
+                if (!found)
+                    break;
+                const text = found[1];
+                const value = parseFloat(text);
+                // The token comes off `body` either way. Leaving a position this build
+                // could not read attached to the color would make the color itself
+                // unparseable, dropping the whole stop — and a gradient left with one
+                // stop does not parse at all. A malformed position is worth losing; the
+                // stop is not, so it falls through to the interpolated position.
+                body = body.slice(0, body.length - found[0].length).trim();
+                if (Number.isNaN(value))
+                    break;
+                positions.unshift(Math.max(0, Math.min(1, text.endsWith("%") ? value / 100 : value)));
+            }
+            if (!body)
+                continue;
+            if (positions.length === 0) {
+                colors.push(body);
+                locations.push(colors.length === 1 ? 0 : 1);
+                continue;
+            }
+            for (const position of positions) {
+                colors.push(body);
+                locations.push(position);
+                positioned++;
+            }
+        }
+        if (colors.length === 0)
+            continue;
+        layers.push({
+            kind,
+            angle,
+            colors,
+            // Partial position data would place stops wrongly; only pass locations
+            // through when the source positioned every stop.
+            locations: positioned === colors.length ? locations : undefined,
+            center,
+        });
+    }
+    return layers;
+}
+const TO_ANGLE = {
+    "to top": 0,
+    "to right": 90,
+    "to bottom": 180,
+    "to left": 270,
+    "to top right": 45,
+    "to right top": 45,
+    "to bottom right": 135,
+    "to right bottom": 135,
+    "to bottom left": 225,
+    "to left bottom": 225,
+    "to top left": 315,
+    "to left top": 315,
+};
+/** The `at X% Y%` part of a radial's prelude, as 0–1. Defaults to the CSS
+ *  default centre when the prelude names none. */
+function readCenter(prelude) {
+    const at = prelude.split(/\bat\b/i)[1];
+    const pcts = at ? [...at.matchAll(/(-?[\d.]+)%/g)].map((m) => parseFloat(m[1])) : [];
+    return {
+        x: (pcts[0] ?? 50) / 100,
+        y: (pcts[1] ?? 50) / 100,
+    };
+}
+function hasColor(value) {
+    const s = value.trim();
+    return /^(#|rgb|hsl|@)/i.test(s) || s.toLowerCase() === "transparent";
+}
+/**
+ * A field that can only ever be ONE color — a border, text, an icon, a shadow.
+ *
+ * A gradient there has no native form (nor a CSS one: `border-color` takes no
+ * gradient, so the dashboard drops the declaration outright). Collapsing it to
+ * the color it stands for keeps the stroke or the glyph visible, which is
+ * nearer the design's intent than losing it — and, on React Native, avoids
+ * handing the platform a color string it cannot parse.
+ */
+export function flatColor(value, doc, onDiagnostic) {
+    const resolved = resolveColor(value, doc);
+    if (resolved === undefined || !isGradient(resolved))
+        return resolved;
+    onDiagnostic?.(`gradient flattened in a colour-only field: ${resolved}`);
+    return gradientFallbackColor(resolved);
+}
+/** The solid to paint when no gradient component is available: the base
+ *  layer's first stop, which is the design's ground color.
+ *
+ *  A value with no paintable layer at all — a `repeating-linear-gradient`, or
+ *  any other form this build does not read — falls through to the same colour
+ *  extraction the six SDKs share, so a box the design coloured still gets a
+ *  colour from the design rather than nothing. */
+export function gradientFallbackColor(value) {
+    // A pattern's colors are STRIPE colors; spreading one over the whole box is a
+    // wrong answer rather than a degraded one, so it paints nothing.
+    if (isRepeatingPattern(value))
+        return undefined;
+    const layers = parseGradient(value);
+    const base = layers[layers.length - 1];
+    return base?.colors[0] ?? backgroundBaseColor(value);
+}
+/**
+ * The solid a surface paints UNDER a fill — or nothing.
+ *
+ * The solid exists for one reason: an app that passes no gradient component
+ * still gets a colour instead of a hole. It was painted unconditionally, and
+ * for an opaque fill that never showed, because the real gradient covered it.
+ *
+ * A scrim showed it. A scrim is a gradient that is transparent at one end ON
+ * PURPOSE — that is how a photo stays visible above the copy. Its first stop
+ * is the dark end, so the "fallback" under it was a near-black sheet across
+ * the whole box, and the gradient's transparent half revealed that sheet
+ * instead of the photograph behind it. Every photo background looked like a
+ * black screen on React Native, while the dashboard's CSS painted it fine.
+ *
+ * So: when the gradient will actually be drawn, nothing goes under it. The
+ * solid is only for the degraded case — no gradient renderer, or a fill this
+ * build cannot read as a gradient at all.
+ */
+export function surfaceSolid(resolved, canPaintGradient) {
+    if (!resolved)
+        return undefined;
+    if (!isGradient(resolved))
+        return resolved;
+    if (canPaintGradient && parseGradient(resolved).length > 0)
+        return undefined;
+    return gradientFallbackColor(resolved);
+}
+/** Splits comma-separated background layers, ignoring commas inside parens. */
+function splitLayers(value) {
+    return splitTop(value).map((s) => s.trim());
+}
+function splitTop(value) {
+    const out = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of value) {
+        if (ch === "(")
+            depth++;
+        else if (ch === ")")
+            depth--;
+        if (ch === "," && depth === 0) {
+            out.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim())
+        out.push(current);
+    return out;
+}

package/dist/esm/blocks/locale.js

@@ -0,0 +1,255 @@
+// REV-271: paywall localization, SDK half. A designed paywall carries ONE
+// tree plus a side table of translated strings — never one tree per language
+// — so styles, layout and block ids are shared and only words differ.
+//
+// Selection happens HERE, at render, rather than server-side at resolve. The
+// resolution is cached on the device (REV-157), so a locale chosen by the
+// server would pin a cached paywall to whatever language it was fetched in:
+// change the phone's language and the old copy would keep rendering until the
+// cache expired, and offline it would never change at all. Choosing on the
+// device also keeps the server's fleet-wide placement cache one entry per
+// placement instead of one per language.
+//
+// Mirrored from the dashboard's src/lib/paywall-blocks/locale.ts and into the
+// five native SDKs. The key scheme, the fallback chain and the field list
+// must stay identical on every side — a paywall translated in the dashboard
+// has to resolve the same way on all six.
+/** BCP-47, hyphenated: "es_MX" and "es-mx" both normalize to "es-MX". Applied
+ *  to authored tags and to the device's reported locale alike, so the two can
+ *  never miss each other over punctuation or case. */
+export function normalizeLocale(tag) {
+    if (typeof tag !== "string")
+        return undefined;
+    const parts = tag.trim().replace(/_/g, "-").split("-").filter(Boolean);
+    const language = parts[0]?.toLowerCase();
+    if (language === undefined || !/^[a-z]{2,3}$/.test(language))
+        return undefined;
+    const rest = [];
+    for (const part of parts.slice(1)) {
+        // Region subtags are uppercase ("MX", "419"), scripts title case ("Hans").
+        // Anything else is a variant and stays lowercase. A subtag outside
+        // BCP-47's shapes makes the WHOLE tag junk rather than passing through —
+        // otherwise a device reporting "es-!!" would look up a language.
+        if (/^[A-Za-z]{2}$/.test(part) || /^\d{3}$/.test(part)) {
+            rest.push(part.toUpperCase());
+        }
+        else if (/^[A-Za-z]{4}$/.test(part)) {
+            rest.push(part.charAt(0).toUpperCase() + part.slice(1).toLowerCase());
+        }
+        else if (/^[A-Za-z0-9]{5,8}$/.test(part)) {
+            rest.push(part.toLowerCase());
+        }
+        else {
+            return undefined;
+        }
+    }
+    return [language, ...rest].join("-");
+}
+function baseLanguage(tag) {
+    return tag.split("-")[0] ?? tag;
+}
+/** Which tables to consult, most specific first.
+ *
+ *  "es-MX" on a paywall translated into "es" reads the "es" table: a regional
+ *  variant that was never authored falls back to its language rather than to
+ *  the source, which is the difference between a Mexican user reading Spanish
+ *  and reading English. The authored tree is the last resort and is NOT in
+ *  this chain — the lookup falls through to it. */
+export function localeChain(available, locale, defaultLocale) {
+    const chain = [];
+    const push = (tag) => {
+        if (tag !== undefined && available.includes(tag) && !chain.includes(tag)) {
+            chain.push(tag);
+        }
+    };
+    const wanted = normalizeLocale(locale);
+    if (wanted !== undefined) {
+        push(wanted);
+        push(baseLanguage(wanted));
+        // "es" asked for, only "es-MX" authored: one regional table beats the
+        // source language, and the first sorted match keeps the choice
+        // deterministic across devices rather than dependent on key order.
+        if (chain.length === 0) {
+            const language = baseLanguage(wanted);
+            const regional = available
+                .filter((tag) => baseLanguage(tag) === language)
+                .sort();
+            push(regional[0]);
+        }
+    }
+    push(normalizeLocale(defaultLocale));
+    return chain;
+}
+let localeOverride;
+/** Forces the paywall language regardless of the device's, for a host whose
+ *  in-app language picker differs from the OS locale. `undefined` clears it.
+ *  Only paywalls MOUNTED AFTER this call pick it up — `detectLocale()` is
+ *  read once per doc/locale in a `useMemo`. */
+export function setLocale(tag) {
+    localeOverride = tag || undefined;
+}
+/** The device's language, for hosts that do not pass one. Hermes without the
+ *  full ICU build has no `Intl`, and a React Native `navigator.language` is
+ *  the JS engine's, not the device's — so this is best effort and a host that
+ *  cares passes `locale` explicitly. */
+export function detectLocale() {
+    if (localeOverride !== undefined)
+        return localeOverride;
+    try {
+        const resolved = new Intl.DateTimeFormat().resolvedOptions().locale;
+        if (typeof resolved === "string" && resolved.length > 0)
+            return resolved;
+    }
+    catch {
+        // Falls through to navigator below.
+    }
+    const nav = globalThis.navigator;
+    return typeof nav?.language === "string" && nav.language.length > 0
+        ? nav.language
+        : undefined;
+}
+function localizeBlock(block, lookup) {
+    const at = (path, authored) => lookup(`${block.id}.${path}`, authored);
+    const opt = (path, authored) => authored === undefined ? undefined : at(path, authored);
+    switch (block.type) {
+        case "text":
+            return { ...block, text: at("text", block.text) };
+        case "button":
+            return { ...block, label: at("label", block.label) };
+        case "list":
+            return {
+                ...block,
+                items: block.items.map((item, i) => ({
+                    ...item,
+                    title: at(`items.${i}.title`, item.title),
+                    description: opt(`items.${i}.description`, item.description),
+                })),
+            };
+        case "products":
+            return {
+                ...block,
+                titleTpl: opt("titleTpl", block.titleTpl),
+                priceTpl: opt("priceTpl", block.priceTpl),
+                highlightSub: opt("highlightSub", block.highlightSub),
+                badgeText: opt("badgeText", block.badgeText),
+            };
+        case "card":
+            return {
+                ...block,
+                children: block.children.map((child) => localizeBlock(child, lookup)),
+            };
+        default:
+            return block;
+    }
+}
+/** Returns the document with every string swapped for `locale`'s.
+ *
+ *  Applied ONCE before rendering rather than at each text node: the renderer
+ *  then needs no localization awareness at all, and the six SDKs cannot drift
+ *  on which fields are translatable. Returns the input untouched when nothing
+ *  applies, so an untranslated paywall allocates nothing.
+ *
+ *  `{price}` and the other copy tags survive, because they are resolved AFTER
+ *  this on the localized string — "Solo {price} al mes" works. */
+export function localizeBlockDoc(doc, locale) {
+    const tables = doc.locales;
+    if (tables === undefined)
+        return doc;
+    const available = Object.keys(tables);
+    if (available.length === 0)
+        return doc;
+    const chain = localeChain(available, locale, doc.defaultLocale);
+    if (chain.length === 0)
+        return doc;
+    const lookup = (key, authored) => {
+        for (const tag of chain) {
+            const value = tables[tag]?.[key];
+            // An empty translation means "not translated", never "render nothing":
+            // a blank CTA is a dead paywall, and an export/import round-trip leaves
+            // empty cells behind for every untouched row.
+            if (typeof value === "string" && value !== "")
+                return value;
+        }
+        return authored;
+    };
+    return {
+        ...doc,
+        defaultLocale: chain[0],
+        blocks: doc.blocks.map((b) => localizeBlock(b, lookup)),
+    };
+}
+const LINK_LABEL_ALIASES = {
+    iw: "he",
+    in: "id",
+    no: "nb",
+    tl: "fil",
+};
+const LINK_LABELS = {
+    ar: ["استعادة", "الشروط", "الخصوصية"],
+    bg: ["Възстановяване", "Условия", "Поверителност"],
+    bn: ["পুনরুদ্ধার", "শর্তাবলী", "গোপনীয়তা"],
+    ca: ["Restaura", "Condicions", "Privadesa"],
+    cs: ["Obnovit", "Podmínky", "Soukromí"],
+    da: ["Gendan", "Vilkår", "Privatliv"],
+    de: ["Wiederherstellen", "AGB", "Datenschutz"],
+    el: ["Επαναφορά", "Όροι", "Απόρρητο"],
+    en: ["Restore", "Terms", "Privacy"],
+    es: ["Restaurar", "Términos", "Privacidad"],
+    et: ["Taasta", "Tingimused", "Privaatsus"],
+    fa: ["بازیابی", "شرایط", "حریم خصوصی"],
+    fi: ["Palauta", "Ehdot", "Tietosuoja"],
+    fil: ["I-restore", "Mga Tuntunin", "Privacy"],
+    fr: ["Restaurer", "Conditions", "Confidentialité"],
+    he: ["שחזור", "תנאים", "פרטיות"],
+    hi: ["पुनर्स्थापित करें", "शर्तें", "गोपनीयता"],
+    hr: ["Vrati", "Uvjeti", "Privatnost"],
+    hu: ["Visszaállítás", "Feltételek", "Adatvédelem"],
+    id: ["Pulihkan", "Ketentuan", "Privasi"],
+    it: ["Ripristina", "Termini", "Privacy"],
+    ja: ["購入を復元", "利用規約", "プライバシー"],
+    ko: ["구매 복원", "이용약관", "개인정보"],
+    lt: ["Atkurti", "Sąlygos", "Privatumas"],
+    lv: ["Atjaunot", "Noteikumi", "Privātums"],
+    ms: ["Pulihkan", "Terma", "Privasi"],
+    nb: ["Gjenopprett", "Vilkår", "Personvern"],
+    nl: ["Herstellen", "Voorwaarden", "Privacy"],
+    pl: ["Przywróć", "Regulamin", "Prywatność"],
+    pt: ["Restaurar", "Termos", "Privacidade"],
+    ro: ["Restaurează", "Termeni", "Confidențialitate"],
+    ru: ["Восстановить", "Условия", "Конфиденциальность"],
+    sk: ["Obnoviť", "Podmienky", "Súkromie"],
+    sl: ["Obnovi", "Pogoji", "Zasebnost"],
+    sr: ["Врати", "Услови", "Приватност"],
+    sv: ["Återställ", "Villkor", "Integritet"],
+    th: ["กู้คืน", "ข้อกำหนด", "ความเป็นส่วนตัว"],
+    tr: ["Geri Yükle", "Koşullar", "Gizlilik"],
+    uk: ["Відновити", "Умови", "Конфіденційність"],
+    ur: ["بحال کریں", "شرائط", "رازداری"],
+    vi: ["Khôi phục", "Điều khoản", "Quyền riêng tư"],
+    zh: ["恢复购买", "条款", "隐私"],
+    "zh-Hant": ["恢復購買", "條款", "隱私"],
+};
+/** The three built-in paywall footer labels (restore/terms/privacy), in the
+ *  language `locale` resolves to. Falls back to English for any language not
+ *  in the 43-entry table. Mandarin picks traditional script for Taiwan, Hong
+ *  Kong and Macau unless the tag is explicitly simplified. */
+export function linkLabels(locale) {
+    const [restore, terms, privacy] = LINK_LABELS[resolveLinkLabelTag(locale)];
+    return { restore, terms, privacy };
+}
+function resolveLinkLabelTag(locale) {
+    const tag = normalizeLocale(locale);
+    if (tag === undefined)
+        return "en";
+    const lang = baseLanguage(tag);
+    if (lang === "zh") {
+        const parts = tag.split("-").slice(1);
+        const hasHant = parts.includes("Hant");
+        const hasHans = parts.includes("Hans");
+        const region = parts.find((part) => /^[A-Z]{2}$/.test(part));
+        const isTraditionalRegion = region !== undefined && ["TW", "HK", "MO"].includes(region);
+        return hasHant || (!hasHans && isTraditionalRegion) ? "zh-Hant" : "zh";
+    }
+    const base = LINK_LABEL_ALIASES[lang] ?? lang;
+    return base in LINK_LABELS ? base : "en";
+}

package/dist/esm/blocks/selection.js

@@ -0,0 +1,100 @@
+// REV-262: the selection half of the designed-paywall render contract v2
+// (revnix/cto-review/2026-09-03-paywall-render-contract-v2.md), kept pure so
+// the wire fixture can be walked without React Native.
+//
+// Mirrors revnix-app's src/lib/paywall-blocks/selection.ts: the dashboard
+// preview and this renderer must agree on which package is "selected", what
+// a block looks like in that state and whether it is drawn at all.
+import { DESIGN_CANVAS } from "./types.js";
+import { resolveTags } from "./tags.js";
+/** The package a designed paywall is showing as chosen: the host's choice,
+ *  then the renderer's own after a tap, then the design's highlight, then the
+ *  first package — each only when the offering actually carries it. */
+export function selectedPackageId(packages, ...candidates) {
+    for (const id of candidates) {
+        if (id !== undefined && packages.some((p) => p.packageId === id))
+            return id;
+    }
+    return packages[0]?.packageId;
+}
+/** The context a package-bearing card opens for itself and its subtree. */
+export function packageContext(pkg, selectedId) {
+    if (pkg === undefined)
+        return undefined;
+    return pkg.packageId === selectedId ? "selected" : "unselected";
+}
+/** `selectedStyle` merged over `style` while selected; `style` otherwise. */
+export function effectiveStyle(block, context) {
+    if (context === "selected" && block.selectedStyle) {
+        return { ...block.style, ...block.selectedStyle };
+    }
+    return block.style;
+}
+/** Whether a block is drawn. Outside any plan card every block is drawn,
+ *  whatever `visibility` says — a root block can never disappear. */
+export function isVisible(block, context) {
+    if (block.visibility === undefined || context === undefined)
+        return true;
+    return (block.visibility === "selected") === (context === "selected");
+}
+/** Canvas designs are authored at 393×852 and scaled by width, capped so a
+ *  tablet or a landscape phone shows a centred phone-sized design instead of
+ *  a blown-up one. */
+export const CANVAS_MAX_WIDTH = 480;
+export function canvasMetrics(viewportWidth, viewportHeight) {
+    const scale = Math.min(viewportWidth, CANVAS_MAX_WIDTH) / DESIGN_CANVAS.width;
+    const left = (viewportWidth - DESIGN_CANVAS.width * scale) / 2;
+    const designHeight = viewportHeight === null
+        ? DESIGN_CANVAS.height
+        : Math.max(DESIGN_CANVAS.height, viewportHeight / scale);
+    const scaledHeight = designHeight * scale;
+    const overflows = viewportHeight !== null && DESIGN_CANVAS.height * scale > viewportHeight + 1;
+    return { scale, left, designHeight, scaledHeight, overflows };
+}
+/** Walk a document exactly the way the renderer does — pinned cards judge
+ *  their own context, repeat cards yield one entry per package (keyed
+ *  `id@packageId`), hidden subtrees are not entered — and report what every
+ *  block resolves to. The wire fixture test reads this. */
+export function resolveBlocks(doc, packages, selectedId) {
+    const out = new Map();
+    const root = packages.find((p) => p.packageId === selectedId) ?? packages[0];
+    const visit = (block, inherited, pkg, key) => {
+        if (block.type === "card" && block.repeat === "packages") {
+            const list = packages.length ? packages : [undefined];
+            for (const p of list) {
+                visitCard(block, packageContext(p, selectedId) ?? inherited, p ?? pkg, `${key}@${p?.packageId ?? "-"}`);
+            }
+            return;
+        }
+        if (block.type === "card" && block.packageIndex !== undefined) {
+            const own = packages[block.packageIndex];
+            if (own === undefined)
+                return; // dropped: the offering does not reach it
+            visitCard(block, packageContext(own, selectedId), own, key);
+            return;
+        }
+        const context = inherited;
+        const visible = isVisible(block, context);
+        const entry = { block, context, visible, style: effectiveStyle(block, context) };
+        if (block.type === "text")
+            entry.text = resolveTags(block.text, pkg, packages);
+        if (block.type === "button")
+            entry.text = resolveTags(block.label, pkg, packages);
+        out.set(key, entry);
+        if (visible && block.type === "card") {
+            for (const child of block.children)
+                visit(child, context, pkg, child.id);
+        }
+    };
+    const visitCard = (block, context, pkg, key) => {
+        const visible = isVisible(block, context);
+        out.set(key, { block, context, visible, style: effectiveStyle(block, context) });
+        if (!visible)
+            return;
+        for (const child of block.children)
+            visit(child, context, pkg, child.id);
+    };
+    for (const b of doc.blocks)
+        visit(b, undefined, root, b.id);
+    return out;
+}