@cosmicdrift/kumiko-renderer 0.374.0 → 0.377.0

package/dist/headless/apex/index.js

@@ -0,0 +1,377 @@
+// Apex marketing-surface renderer — turns a typed page description into a
+// complete static HTML string. The shared structure (header/hero/feature-grid/
+// pricing-grid/info-grid/final-cta/footer) lives here; apps pass only their data,
+// brand tokens (brand.tokensCss) and content. Server-side, zero React, one
+// cacheable HTTP response. See APEX_STRUCTURAL_CSS for the CSS contract.
+import { escapeHtml } from "../format/index.js";
+import { APEX_STRUCTURAL_CSS } from "./css.js";
+import { APEX_LIGHTBOX_HTML, APEX_LIGHTBOX_SCRIPT } from "./lightbox.js";
+export { APEX_NAV_MENU_CSS, APEX_NAV_TOGGLE_RESPONSIVE_CSS, APEX_STRUCTURAL_CSS } from "./css.js";
+export { APEX_LIGHTBOX_HTML, APEX_LIGHTBOX_SCRIPT, APEX_LIGHTBOX_SCRIPT_CSP_HASH, } from "./lightbox.js";
+// JSON in <script>-Kontext: `<` als < serialisieren, damit weder
+// `</script>` noch `<!--` aus dem Block ausbrechen kann (JSON bleibt valide).
+function scriptSafeJsonHtml(value) {
+    return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+function dim(img) {
+    return `${img.width !== undefined ? ` width="${img.width}"` : ""}${img.height !== undefined ? ` height="${img.height}"` : ""}`;
+}
+function svgIcon(innerHtml) {
+    return `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${innerHtml}</svg>`;
+}
+function renderCta(cta) {
+    const variant = cta.variant ?? "primary";
+    const cls = variant === "link" ? "" : ` class="btn btn-${variant}"`;
+    return `<a${cls} href="${escapeHtml(cta.href)}">${escapeHtml(cta.label)}</a>`;
+}
+function renderSectionHead(s) {
+    if (s.eyebrow === undefined && s.heading === undefined && s.sub === undefined)
+        return "";
+    const eyebrow = s.eyebrow !== undefined ? `<span class="eyebrow">${escapeHtml(s.eyebrow)}</span>` : "";
+    const heading = s.heading !== undefined ? `<h2>${escapeHtml(s.heading)}</h2>` : "";
+    const sub = s.sub !== undefined ? `<p>${escapeHtml(s.sub)}</p>` : "";
+    return `<div class="section-head">${eyebrow}${heading}${sub}</div>`;
+}
+function bandAttrs(muted, id) {
+    const cls = muted === false ? "" : ` class="features"`;
+    const idAttr = id !== undefined ? ` id="${escapeHtml(id)}"` : "";
+    return cls + idAttr;
+}
+function renderHero(s) {
+    const logo = s.logo !== undefined
+        ? `<img class="hero-pony" src="${escapeHtml(s.logo.src)}" alt="${escapeHtml(s.logo.alt)}"${dim(s.logo)} />`
+        : "";
+    const ctasHtml = (s.ctas ?? []).map(renderCta).join("\n            ");
+    const meta = s.metaHtml !== undefined ? `<p class="hero-meta">${s.metaHtml}</p>` : "";
+    const visual = s.screenshot !== undefined
+        ? `<div class="hero-visual"><div class="shot-frame"><div class="shot-bar"><span></span><span></span><span></span></div><img src="${escapeHtml(s.screenshot.src)}" alt="${escapeHtml(s.screenshot.alt)}"${dim(s.screenshot)} loading="eager" /></div></div>`
+        : "";
+    return `<section class="hero">
+      <div class="container hero-grid">
+        <div class="hero-copy">
+          ${logo}<h1>${escapeHtml(s.title)}</h1>
+          <p class="tagline">${escapeHtml(s.tagline)}</p>
+          ${ctasHtml !== "" ? `<div class="hero-cta">${ctasHtml}</div>` : ""}
+          ${meta}
+        </div>
+        ${visual}
+      </div>
+    </section>`;
+}
+function renderFeatureGrid(s) {
+    const cardsHtml = s.items
+        .map((f) => `<article class="feature">
+            ${f.icon !== undefined ? `<div class="feature-icon">${svgIcon(f.icon)}</div>` : ""}<h3>${escapeHtml(f.title)}</h3>
+            <p>${escapeHtml(f.desc)}</p>
+          </article>`)
+        .join("\n          ");
+    return `<section${bandAttrs(s.muted, s.id)}>
+      <div class="container">
+        ${renderSectionHead(s)}
+        <div class="feature-grid">
+          ${cardsHtml}
+        </div>
+      </div>
+    </section>`;
+}
+function renderPricingCard(t) {
+    const featured = t.featured === true;
+    const badge = t.badge !== undefined ? `<span class="price-badge">${escapeHtml(t.badge)}</span>` : "";
+    const cap = t.capLine !== undefined ? [`<li class="price-cap">${escapeHtml(t.capLine)}</li>`] : [];
+    const benefits = t.benefits.map((b) => `<li>${escapeHtml(b)}</li>`);
+    const itemsHtml = [...cap, ...benefits].join("\n            ");
+    const per = t.priceSuffix !== undefined ? `<span>${escapeHtml(t.priceSuffix)}</span>` : "";
+    const tagline = t.tagline !== undefined ? `<p class="price-tagline">${escapeHtml(t.tagline)}</p>` : "";
+    // Delegates to renderCta so a `variant: "link"` tier CTA gets the same
+    // class-free anchor as everywhere else instead of re-deriving the class
+    // string here (a prior inline duplicate had no "link" case, always
+    // emitting `.btn-link`, which the structural CSS never defines).
+    const cta = t.cta.variant === undefined
+        ? renderCta({ ...t.cta, variant: featured ? "primary" : "secondary" })
+        : renderCta(t.cta);
+    return `<article class="price-card${featured ? " price-card--featured" : ""}">
+          ${badge}<h3>${escapeHtml(t.name)}</h3>
+          ${tagline}<div class="price-amount">${escapeHtml(t.amount)}${per}</div>
+          <ul class="price-list">
+            ${itemsHtml}
+          </ul>
+          ${cta}
+        </article>`;
+}
+function renderPricingGrid(s) {
+    const cardsHtml = s.tiers.map(renderPricingCard).join("\n          ");
+    const idAttr = s.id !== undefined ? ` id="${escapeHtml(s.id)}"` : "";
+    return `<section${idAttr}>
+      <div class="container">
+        ${renderSectionHead(s)}
+        <div class="price-grid">
+          ${cardsHtml}
+        </div>
+      </div>
+    </section>`;
+}
+function renderInfoGrid(s) {
+    const itemsHtml = s.items
+        .map((i) => `<div class="trust-item">
+            <h3>${escapeHtml(i.title)}</h3>
+            <p>${escapeHtml(i.desc)}</p>
+          </div>`)
+        .join("\n          ");
+    return `<section${bandAttrs(s.muted, s.id)}>
+      <div class="container">
+        ${renderSectionHead(s)}
+        <div class="trust-grid">
+          ${itemsHtml}
+        </div>
+      </div>
+    </section>`;
+}
+function renderFinalCta(s) {
+    const img = s.image !== undefined
+        ? `<img class="final-cta-pony" src="${escapeHtml(s.image.src)}" alt="${escapeHtml(s.image.alt)}"${dim(s.image)} />`
+        : "";
+    const sub = s.sub !== undefined ? `<p>${escapeHtml(s.sub)}</p>` : "";
+    return `<section class="final-cta">
+      <div class="container">
+        ${img}<h2>${escapeHtml(s.heading)}</h2>
+        ${sub}${renderCta(s.cta)}
+      </div>
+    </section>`;
+}
+function renderSection(s) {
+    switch (s.kind) {
+        case "hero":
+            return renderHero(s);
+        case "feature-grid":
+            return renderFeatureGrid(s);
+        case "pricing-grid":
+            return renderPricingGrid(s);
+        case "info-grid":
+            return renderInfoGrid(s);
+        case "final-cta":
+            return renderFinalCta(s);
+        case "html":
+            return s.html;
+    }
+}
+function renderNavMenu(m) {
+    const itemsHtml = m.items
+        .map((it) => `<a class="nav-menu__item" href="${escapeHtml(it.href)}">${it.icon !== undefined ? `<span class="nav-menu__icon">${svgIcon(it.icon)}</span>` : ""}<span class="nav-menu__text"><span class="nav-menu__title">${escapeHtml(it.title)}</span>${it.desc !== undefined ? `<span class="nav-menu__desc">${escapeHtml(it.desc)}</span>` : ""}</span></a>`)
+        .join("");
+    const footer = m.footer !== undefined
+        ? `<div class="nav-menu__sep"></div><a class="nav-menu__more" href="${escapeHtml(m.footer.href)}">${escapeHtml(m.footer.label)}</a>`
+        : "";
+    return `<details class="nav-menu"><summary class="nav-menu__trigger">${escapeHtml(m.label)}<span class="nav-menu__chev">${svgIcon('<path d="m6 9 6 6 6-6"/>')}</span></summary><div class="nav-menu__panel">${itemsHtml}${footer}</div></details>`;
+}
+function renderNavEntry(entry) {
+    return entry.kind === "menu"
+        ? renderNavMenu(entry)
+        : `<a href="${escapeHtml(entry.href)}">${escapeHtml(entry.label)}</a>`;
+}
+/** Render just the apex header chrome (brand + nav + actions). Exported so a
+ *  consumer that composes its own page shell (not a full apex page) can reuse
+ *  the identical header — markup stays single-source. */
+export function renderApexHeader(h) {
+    const logo = h.brand.logoSrc !== undefined ? `<img src="${escapeHtml(h.brand.logoSrc)}" alt="" /> ` : "";
+    const navLinksHtml = (h.navLinks ?? []).map(renderNavEntry).join("\n      ");
+    const actionsHtml = (h.actions ?? []).map(renderCta).join("\n      ");
+    return `<header>
+    <div class="container nav">
+      <div class="brand"><a href="${escapeHtml(h.brand.href)}">${logo}${escapeHtml(h.brand.label)}</a></div>
+      ${navLinksHtml !== "" ? `<nav class="nav-links">${navLinksHtml}</nav><details class="nav-toggle"><summary class="nav-toggle__trigger" aria-label="${escapeHtml(h.menuLabel ?? "Menu")}">${svgIcon('<path d="M4 6h16M4 12h16M4 18h16"/>')}</summary><nav class="nav-links">${navLinksHtml}</nav></details>` : ""}
+      ${actionsHtml !== "" ? `<div class="nav-actions">${actionsHtml}</div>` : ""}
+    </div>
+  </header>`;
+}
+function renderFooter(f) {
+    const cols = f.columns ?? [];
+    const logo = f.brand.logoSrc !== undefined ? `<img src="${escapeHtml(f.brand.logoSrc)}" alt="" /> ` : "";
+    const colHtml = cols
+        .map((c) => `<div class="footer-col">
+        <h4>${escapeHtml(c.heading)}</h4>
+        ${c.links.map((l) => `<a href="${escapeHtml(l.href)}">${escapeHtml(l.label)}</a>`).join("\n        ")}
+      </div>`)
+        .join("\n      ");
+    const bottom = f.bottomLeft !== undefined || f.bottomRight !== undefined
+        ? `<div class="footer-bottom">
+      ${f.bottomLeft !== undefined ? `<span>${escapeHtml(f.bottomLeft)}</span>` : ""}
+      ${f.bottomRight !== undefined ? `<span>${escapeHtml(f.bottomRight)}</span>` : ""}
+    </div>`
+        : "";
+    return `<footer>
+    <div class="container">
+      <div class="footer-grid" style="--footer-cols:${Math.max(1, cols.length)}">
+        <div>
+          <div class="footer-brand">${logo}${escapeHtml(f.brand.label)}</div>
+          ${f.tagline !== undefined ? `<p class="footer-tagline">${escapeHtml(f.tagline)}</p>` : ""}
+        </div>
+        ${colHtml}
+      </div>
+      ${bottom}
+    </div>
+  </footer>`;
+}
+// All <title>/meta/link/script tags for an ApexHead — the single source both
+// renderApexPage and any other head (e.g. page-render's wrapInLayout) splice
+// into their own <head>. Extracted verbatim from renderApexPage so existing
+// output stays byte-identical (see render.test.ts regression coverage).
+export function renderApexHeadTags(head) {
+    const ogUrl = head.canonicalUrl !== undefined
+        ? `\n    <meta property="og:url" content="${escapeHtml(head.canonicalUrl)}" />`
+        : "";
+    const ogImage = head.ogImage !== undefined
+        ? `\n    <meta property="og:image" content="${escapeHtml(head.ogImage)}" />`
+        : "";
+    const favicon = head.faviconHref !== undefined
+        ? `\n    <link rel="icon" href="${escapeHtml(head.faviconHref)}" />`
+        : "";
+    const canonical = head.canonicalUrl !== undefined
+        ? `\n    <link rel="canonical" href="${escapeHtml(head.canonicalUrl)}" />`
+        : "";
+    const alternates = (head.alternates ?? [])
+        .map((a) => `\n    <link rel="alternate" hreflang="${escapeHtml(a.hreflang)}" href="${escapeHtml(a.href)}" />`)
+        .join("");
+    const robots = head.robots !== undefined
+        ? `\n    <meta name="robots" content="${escapeHtml(head.robots)}" />`
+        : "";
+    const siteName = head.siteName !== undefined
+        ? `\n    <meta property="og:site_name" content="${escapeHtml(head.siteName)}" />`
+        : "";
+    const locale = head.locale !== undefined
+        ? `\n    <meta property="og:locale" content="${escapeHtml(head.locale)}" />`
+        : "";
+    const twitterCard = head.ogImage !== undefined
+        ? `\n    <meta name="twitter:card" content="summary_large_image" />`
+        : "";
+    const twitterSite = head.twitterSite !== undefined
+        ? `\n    <meta name="twitter:site" content="${escapeHtml(head.twitterSite)}" />`
+        : "";
+    const preconnects = (head.preconnects ?? [])
+        .map((url) => `\n    <link rel="preconnect" href="${escapeHtml(url)}" />`)
+        .join("");
+    const schema = head.schemaJson !== undefined
+        ? `\n    <script type="application/ld+json">${scriptSafeJsonHtml(head.schemaJson)}</script>`
+        : "";
+    const metaDescription = head.description
+        ? `\n    <meta name="description" content="${escapeHtml(head.description)}" />`
+        : "";
+    const ogDescription = head.description
+        ? `\n    <meta property="og:description" content="${escapeHtml(head.description)}" />`
+        : "";
+    return `<title>${escapeHtml(head.title)}</title>${metaDescription}
+    <meta property="og:title" content="${escapeHtml(head.title)}" />${ogDescription}
+    <meta property="og:type" content="website" />${ogUrl}${ogImage}${siteName}${locale}${twitterCard}${twitterSite}${favicon}${canonical}${alternates}${robots}${preconnects}${schema}`;
+}
+export function renderApexPage(page) {
+    const { head, brand } = page;
+    const theme = page.theme ?? "light";
+    // Brand-CSS ist app-authored (Trust-Boundary siehe Datei-Header), kein Tenant-Input.
+    const cssHtml = (brand.fontFaceCss ?? "") + brand.tokensCss + APEX_STRUCTURAL_CSS;
+    const sectionsHtml = page.sections.map(renderSection).join("\n\n    ");
+    // interactive-widget is ignored by iOS Safari; apex pages have no fixed bottom bars, so
+    // the key only matters for Chromium/Android and needs no visualViewport fallback here.
+    return `<!doctype html>
+<html lang="${escapeHtml(head.lang)}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1,interactive-widget=resizes-content" />
+    ${renderApexHeadTags(head)}
+    <style>${cssHtml}</style>
+  </head>
+  <body${theme === "dark" ? ` class="apex-dark"` : ""}>
+    ${renderApexHeader(page.header)}
+
+    ${sectionsHtml}
+
+    ${renderFooter(page.footer)}
+
+    ${APEX_LIGHTBOX_HTML}
+    ${APEX_LIGHTBOX_SCRIPT}
+  </body>
+</html>`;
+}
+const HEAD_TAGS_MARKER = "<!-- kumiko-page-head -->";
+const TITLE_TAG_RE = /<title\b[^>]*>[\s\S]*?<\/title>/i;
+// Idempotent by marker (repeated calls, e.g. hostDispatch + default path
+// both hitting the same request, never double-inject) and safe on a
+// head-less document (nothing to splice into). `tagsHtml` is pre-rendered
+// HTML from a caller (renderApexHeadTags) — this function only owns
+// placement + the original <title> removal, not escaping.
+export function injectPageHead(html, tagsHtml) {
+    if (html.includes(HEAD_TAGS_MARKER))
+        return html;
+    if (!html.includes("</head>"))
+        return html;
+    const withoutTitle = html.replace(TITLE_TAG_RE, "");
+    return withoutTitle.replace("</head>", () => `${HEAD_TAGS_MARKER}\n${tagsHtml}\n</head>`);
+}
+// Resolver runs alongside the request, never gates it: a slow, throwing, or
+// null-returning resolver must never turn a 200 shell into a 500 or a
+// stall. One constant shared by runProdApp and runDevApp so both time out
+// on the same value (kumiko-framework#3026).
+const PAGE_HEAD_TIMEOUT_MS = 300;
+async function resolvePageHeadWithTimeout(resolvePageHead, input) {
+    let timer;
+    // Winning the race alone would leave the resolver's queries running; the abort stops them.
+    const timeout = new AbortController();
+    const signal = input.requestSignal
+        ? AbortSignal.any([input.requestSignal, timeout.signal])
+        : timeout.signal;
+    const { systemQuery } = input;
+    try {
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                timeout.abort();
+                resolve(null);
+            }, PAGE_HEAD_TIMEOUT_MS);
+        });
+        // .catch on the resolver's own promise (not just the outer try/catch)
+        // so a rejection arriving AFTER the timeout already won the race
+        // doesn't surface as an unhandled rejection.
+        const resolved = resolvePageHead({
+            path: input.path,
+            host: input.host,
+            preferredLocales: input.preferredLocales,
+            signal,
+            systemQuery: (type, payload, tenantId) => systemQuery(type, payload, tenantId, { signal }),
+        }).catch(() => null);
+        return await Promise.race([resolved, timedOut]);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+// ApexHead.lang is required (html lang="..."); PageHeadMeta only carries
+// og:locale-shaped strings ("de_DE", "en-US") since that's all og:locale
+// needs. Take the language subtag before the region separator; default to
+// "en" when there's no locale to derive one from.
+function apexLangFromLocale(locale) {
+    return locale?.split(/[_-]/)[0]?.toLowerCase() || "en";
+}
+function toApexHead(meta) {
+    return {
+        lang: apexLangFromLocale(meta.locale),
+        title: meta.title,
+        description: meta.description ?? "",
+        ...(meta.canonicalUrl !== undefined ? { canonicalUrl: meta.canonicalUrl } : {}),
+        ...(meta.ogImage !== undefined ? { ogImage: meta.ogImage } : {}),
+        ...(meta.siteName !== undefined ? { siteName: meta.siteName } : {}),
+        ...(meta.locale !== undefined ? { locale: meta.locale } : {}),
+    };
+}
+/** Resolves per-request head metadata and splices it into `html`, capped at
+ *  the shared timeout. Never throws and never changes `html` on a resolver
+ *  error, a `null` resolve, or a timeout — the caller's shell always ships
+ *  unchanged. runProdApp and runDevApp both call this single function, so a
+ *  future change to timeout or fallback semantics has one place to land
+ *  (kumiko-framework#3026). */
+export async function resolveAndInjectPageHead(html, resolvePageHead, input) {
+    const meta = await resolvePageHeadWithTimeout(resolvePageHead, input);
+    if (!meta)
+        return html;
+    return injectPageHead(html, renderApexHeadTags(toApexHead(meta)));
+}

package/dist/headless/apex/lightbox.d.ts

@@ -0,0 +1,4 @@
+export declare const APEX_LIGHTBOX_HTML = "<dialog id=\"apex-lightbox\" class=\"apex-lightbox\" aria-label=\"Screenshot preview\">\n  <button type=\"button\" class=\"apex-lightbox__close\" aria-label=\"Close\">&times;</button>\n  <button type=\"button\" class=\"apex-lightbox__prev\" aria-label=\"Previous screenshot\">&lsaquo;</button>\n  <button type=\"button\" class=\"apex-lightbox__next\" aria-label=\"Next screenshot\">&rsaquo;</button>\n  <img class=\"apex-lightbox__img\" alt=\"\" />\n</dialog>";
+/** ponytail: one delegated listener; no-op when no .shot-frame on the page. */
+export declare const APEX_LIGHTBOX_SCRIPT = "<script>\n(function () {\n  var dlg = document.getElementById(\"apex-lightbox\");\n  if (!dlg) return;\n  var img = dlg.querySelector(\".apex-lightbox__img\");\n  var closeBtn = dlg.querySelector(\".apex-lightbox__close\");\n  var prevBtn = dlg.querySelector(\".apex-lightbox__prev\");\n  var nextBtn = dlg.querySelector(\".apex-lightbox__next\");\n  if (!img || !closeBtn || !prevBtn || !nextBtn) return;\n  var shots = [];\n  var current = 0;\n  function show(i) {\n    var shot = shots[i];\n    current = i;\n    img.src = shot.currentSrc || shot.src;\n    img.alt = shot.alt || \"\";\n  }\n  function step(delta) {\n    if (shots.length < 2) return;\n    show((current + delta + shots.length) % shots.length);\n  }\n  function open(target) {\n    shots = Array.prototype.slice.call(document.querySelectorAll(\".shot-frame img\"));\n    var start = shots.indexOf(target);\n    if (start < 0) {\n      shots = [target];\n      start = 0;\n    }\n    show(start);\n    prevBtn.hidden = nextBtn.hidden = shots.length < 2;\n    if (typeof dlg.showModal === \"function\") dlg.showModal();\n  }\n  function close() {\n    if (dlg.open) dlg.close();\n  }\n  document.addEventListener(\"click\", function (e) {\n    var t = e.target;\n    if (!(t instanceof HTMLImageElement)) return;\n    if (!t.closest(\".shot-frame\")) return;\n    e.preventDefault();\n    open(t);\n  });\n  closeBtn.addEventListener(\"click\", close);\n  prevBtn.addEventListener(\"click\", function () { step(-1); });\n  nextBtn.addEventListener(\"click\", function () { step(1); });\n  document.addEventListener(\"keydown\", function (e) {\n    if (!dlg.open) return;\n    if (e.key === \"ArrowLeft\") {\n      e.preventDefault();\n      step(-1);\n    } else if (e.key === \"ArrowRight\") {\n      e.preventDefault();\n      step(1);\n    }\n  });\n  dlg.addEventListener(\"click\", function (e) {\n    if (e.target === dlg) close();\n  });\n  dlg.addEventListener(\"cancel\", function (e) {\n    e.preventDefault();\n    close();\n  });\n})();\n</script>";
+export declare const APEX_LIGHTBOX_SCRIPT_CSP_HASH = "sha256-CLZlqZx0zShYKXq1Qg6+VYMTEC6tqiIlNf6JPA1nLck=";

package/dist/headless/apex/lightbox.js

@@ -0,0 +1,81 @@
+// Vanilla lightbox for Apex marketing pages — click .shot-frame img to enlarge,
+// prev/next (buttons or arrow keys) walks all .shot-frame images on the page.
+// Injected by renderApexPage; no React, no per-app wiring.
+export const APEX_LIGHTBOX_HTML = `<dialog id="apex-lightbox" class="apex-lightbox" aria-label="Screenshot preview">
+  <button type="button" class="apex-lightbox__close" aria-label="Close">&times;</button>
+  <button type="button" class="apex-lightbox__prev" aria-label="Previous screenshot">&lsaquo;</button>
+  <button type="button" class="apex-lightbox__next" aria-label="Next screenshot">&rsaquo;</button>
+  <img class="apex-lightbox__img" alt="" />
+</dialog>`;
+// Split from APEX_LIGHTBOX_SCRIPT so APEX_LIGHTBOX_SCRIPT_CSP_HASH hashes
+// exactly the bytes the browser executes — CSP's script-src hash-source
+// covers the content between <script> and </script>, nothing more/less.
+const APEX_LIGHTBOX_SCRIPT_BODY = `
+(function () {
+  var dlg = document.getElementById("apex-lightbox");
+  if (!dlg) return;
+  var img = dlg.querySelector(".apex-lightbox__img");
+  var closeBtn = dlg.querySelector(".apex-lightbox__close");
+  var prevBtn = dlg.querySelector(".apex-lightbox__prev");
+  var nextBtn = dlg.querySelector(".apex-lightbox__next");
+  if (!img || !closeBtn || !prevBtn || !nextBtn) return;
+  var shots = [];
+  var current = 0;
+  function show(i) {
+    var shot = shots[i];
+    current = i;
+    img.src = shot.currentSrc || shot.src;
+    img.alt = shot.alt || "";
+  }
+  function step(delta) {
+    if (shots.length < 2) return;
+    show((current + delta + shots.length) % shots.length);
+  }
+  function open(target) {
+    shots = Array.prototype.slice.call(document.querySelectorAll(".shot-frame img"));
+    var start = shots.indexOf(target);
+    if (start < 0) {
+      shots = [target];
+      start = 0;
+    }
+    show(start);
+    prevBtn.hidden = nextBtn.hidden = shots.length < 2;
+    if (typeof dlg.showModal === "function") dlg.showModal();
+  }
+  function close() {
+    if (dlg.open) dlg.close();
+  }
+  document.addEventListener("click", function (e) {
+    var t = e.target;
+    if (!(t instanceof HTMLImageElement)) return;
+    if (!t.closest(".shot-frame")) return;
+    e.preventDefault();
+    open(t);
+  });
+  closeBtn.addEventListener("click", close);
+  prevBtn.addEventListener("click", function () { step(-1); });
+  nextBtn.addEventListener("click", function () { step(1); });
+  document.addEventListener("keydown", function (e) {
+    if (!dlg.open) return;
+    if (e.key === "ArrowLeft") {
+      e.preventDefault();
+      step(-1);
+    } else if (e.key === "ArrowRight") {
+      e.preventDefault();
+      step(1);
+    }
+  });
+  dlg.addEventListener("click", function (e) {
+    if (e.target === dlg) close();
+  });
+  dlg.addEventListener("cancel", function (e) {
+    e.preventDefault();
+    close();
+  });
+})();
+`;
+/** ponytail: one delegated listener; no-op when no .shot-frame on the page. */
+export const APEX_LIGHTBOX_SCRIPT = `<script>${APEX_LIGHTBOX_SCRIPT_BODY}</script>`;
+// CSP hash-source for the inline script above; apex output is often
+// pre-rendered, so a per-request nonce can't work. Guarded by lightbox.test.ts.
+export const APEX_LIGHTBOX_SCRIPT_CSP_HASH = "sha256-CLZlqZx0zShYKXq1Qg6+VYMTEC6tqiIlNf6JPA1nLck=";

package/dist/headless/contracts/asset.d.ts

@@ -0,0 +1,15 @@
+export type AssetResolveContext = {
+    readonly tenantId?: string;
+    readonly theme?: "light" | "dark";
+    readonly platform?: "web" | "ios" | "android";
+    readonly locale?: string;
+};
+export type AssetResolution = {
+    readonly uri: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly alt?: string;
+};
+export type AssetResolver = {
+    resolve(qn: string, ctx?: AssetResolveContext): AssetResolution | null;
+};

package/dist/headless/contracts/asset.js

@@ -0,0 +1,17 @@
+// Asset-Resolver — the layer between "qualified asset name" and "URL the
+// renderer can point an <img>/<Image> at". An asset (logo, illustration,
+// icon bundle) is declared by a feature with a qualified name
+// ("admin:asset:hero-logo") and resolved at render-time against the
+// current tenant / theme / platform.
+//
+// Why a resolver indirection:
+//   - Tenant-theming (different logo per tenant) without the feature
+//     knowing what tenant it's rendering for.
+//   - Dark-mode / light-mode variants picked up from the current theme
+//     context.
+//   - Web vs mobile different asset bundles (e.g. PNG vs SVG).
+//
+// The app registers a concrete resolver on startup and hands it to the
+// renderer via context. Feature code calls `useAsset("admin:asset:logo")`
+// (renderer-side hook) → internally `AssetResolver.resolve(qn)`.
+export {};

package/dist/headless/contracts/index.d.ts

@@ -0,0 +1,3 @@
+export type { AssetResolution, AssetResolveContext, AssetResolver, } from "./asset.ts";
+export type { LocaleResolver } from "./locale.ts";
+export type { BadgeProps, ButtonProps, CardProps, DatePickerProps, IconProps, ModalProps, NumberInputProps, PrimitiveCommonProps, PrimitivesContract, SelectOption, SelectProps, TextInputProps, ToastIntent, ToastProps, ToggleProps, } from "./primitives.ts";

package/dist/headless/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/headless/contracts/locale.d.ts

@@ -0,0 +1,7 @@
+export type LocaleResolver = {
+    translate(key: string, params?: Readonly<Record<string, unknown>>): string;
+    locale(): string;
+    timeZone(): string;
+    subscribe(listener: () => void): () => void;
+    setLocale?(locale: string): void;
+};

package/dist/headless/contracts/locale.js

@@ -0,0 +1,11 @@
+// Locale-Resolver — translation lookup + language/region info the
+// renderer needs. Sits in front of i18next (or whatever i18n library
+// the app wires up). ui-core calls it generically so form-controller,
+// view-model, and nav-resolver all produce already-translated strings
+// to hand to the renderer.
+//
+// The framework already has an i18n layer (@cosmicdrift/kumiko-framework/i18n) that
+// features register translations against. This contract is what ui-core
+// consumes — the app's entrypoint instantiates the resolver from a
+// framework i18next instance and passes it to the renderer via context.
+export {};

package/dist/headless/contracts/primitives.d.ts

@@ -0,0 +1,93 @@
+export type PrimitiveCommonProps = {
+    readonly id?: string;
+    readonly name?: string;
+    readonly disabled?: boolean;
+    readonly readOnly?: boolean;
+    readonly required?: boolean;
+    readonly label?: string;
+    readonly placeholder?: string;
+    readonly helperText?: string;
+    readonly errors?: readonly string[];
+};
+export type TextInputProps = PrimitiveCommonProps & {
+    readonly value: string;
+    readonly onChange: (next: string) => void;
+    readonly onBlur?: () => void;
+    readonly type?: "text" | "email" | "url" | "tel" | "password";
+    readonly maxLength?: number;
+    readonly autoComplete?: string;
+};
+export type NumberInputProps = PrimitiveCommonProps & {
+    readonly value: number | null;
+    readonly onChange: (next: number | null) => void;
+    readonly onBlur?: () => void;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+};
+export type SelectOption<TValue extends string = string> = {
+    readonly value: TValue;
+    readonly label: string;
+};
+export type SelectProps<TValue extends string = string> = PrimitiveCommonProps & {
+    readonly value: TValue | null;
+    readonly onChange: (next: TValue | null) => void;
+    readonly options: readonly SelectOption<TValue>[];
+};
+export type ToggleProps = PrimitiveCommonProps & {
+    readonly value: boolean;
+    readonly onChange: (next: boolean) => void;
+};
+export type DatePickerProps = PrimitiveCommonProps & {
+    readonly value: string | null;
+    readonly onChange: (next: string | null) => void;
+    readonly minDate?: string;
+    readonly maxDate?: string;
+};
+export type ButtonProps = {
+    readonly onPress: () => void;
+    readonly label: string;
+    readonly variant?: "primary" | "secondary" | "destructive" | "ghost";
+    readonly disabled?: boolean;
+    readonly loading?: boolean;
+    readonly leftIcon?: string;
+    readonly rightIcon?: string;
+};
+export type ModalProps = {
+    readonly open: boolean;
+    readonly onClose: () => void;
+    readonly title?: string;
+    readonly description?: string;
+};
+export type ToastIntent = "info" | "success" | "warning" | "error";
+export type ToastProps = {
+    readonly intent: ToastIntent;
+    readonly title: string;
+    readonly description?: string;
+    readonly onDismiss?: () => void;
+};
+export type BadgeProps = {
+    readonly label: string;
+    readonly intent?: ToastIntent;
+};
+export type CardProps = {
+    readonly title?: string;
+    readonly description?: string;
+};
+export type IconProps = {
+    readonly name: string;
+    readonly size?: number;
+};
+export type PrimitivesContract<TPrimitive = unknown> = {
+    readonly TextInput: TPrimitive;
+    readonly NumberInput: TPrimitive;
+    readonly Select: TPrimitive;
+    readonly Toggle: TPrimitive;
+    readonly DatePicker: TPrimitive;
+    readonly Button: TPrimitive;
+    readonly Modal: TPrimitive;
+    readonly Toast: TPrimitive;
+    readonly Badge: TPrimitive;
+    readonly Card: TPrimitive;
+    readonly Icon: TPrimitive;
+};

package/dist/headless/contracts/primitives.js

@@ -0,0 +1,21 @@
+// Primitives-Contract — the minimal set of UI building blocks every
+// renderer must provide. A "primitive" is a unit the standard-renderers
+// (entityList, entityEdit, etc.) call into without knowing which library
+// implements it. On web that's shadcn; on mobile it's react-native-paper;
+// both packages (primitives-shadcn, primitives-paper) implement this
+// contract and the app wires one of them into the renderer via context.
+//
+// Why a contract here (in ui-core) instead of in each renderer:
+// ui-core's view-model builder and form-controller produce metadata
+// (field-type, validation-state, label, placeholder) that the renderer
+// translates into primitive invocations. Having the contract shape in
+// ui-core means the metadata can carry references to primitives by name
+// ("text-input", "select") and the translation is a pure map-lookup on
+// the renderer side, not a switch statement that re-derives UI intent
+// from entity-schema.
+//
+// Runtime-free: every primitive is expressed as its input contract only
+// (what props it takes). Concrete components live in each primitives-*
+// package and depend on React / React Native / etc.; ui-core never
+// imports them.
+export {};

package/dist/headless/dispatcher/index.d.ts

@@ -0,0 +1,2 @@
+export type { BatchResult, Command, Dispatcher, DispatcherError, DispatcherStatus, FieldIssue, PendingFile, PendingWrite, QueryOpts, QueryResult, StreamOpts, WriteOpts, WriteResult, } from "./types.ts";
+export { StreamFrame, type StreamFrameEvent } from "./types.ts";

package/dist/headless/dispatcher/index.js

@@ -0,0 +1 @@
+export { StreamFrame } from "./types.js";