@cosmicdrift/kumiko-renderer 0.374.0 → 0.378.0

package/dist/headless/apex/css.js

@@ -0,0 +1,298 @@
+// Structural CSS for the Apex marketing surface — shared by every app's static
+// landing. Brand TOKEN VALUES (:root custom properties) and @font-face stay
+// app-side (passed as brand.tokensCss / brand.fontFaceCss); this file owns only
+// the structure: layout, grids, cards, buttons, header/footer, responsive.
+//
+// Two themes ship together; the <body class> selects one (see renderApexPage):
+//   - light (default): chrome on light backgrounds — translucent blurred header.
+//   - .apex-dark: header/hero/final-cta/footer sit on --primary with --on-dark
+//     text + inverted buttons (the "dark sandwich"). Requires the app's tokens
+//     to define --on-dark / --on-dark-muted / --on-dark-border.
+//
+// Token divergence is absorbed by CSS fallbacks, not parameters:
+//   --font-mono unset        → .price-amount stays in body font (var(--font-mono, inherit))
+//   --accent-hover unset     → eyebrow falls back to --primary
+//   --hero-tagline-max unset → hero tagline runs full column (var(--hero-tagline-max, none))
+//   icon tint                → color-mix derives a faint --primary wash, no hardcoded rgba
+const BASE_LAYOUT = `
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  body {
+    font-family: var(--font-body, "Inter Variable", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif);
+    background: var(--bg); color: var(--fg); line-height: 1.6;
+    -webkit-font-smoothing: antialiased;
+    min-height: 100vh; display: flex; flex-direction: column;
+  }
+  main { flex: 1; }
+  a { color: var(--primary); text-decoration: none; }
+  a:hover { color: var(--primary-hover); }
+  h1, h2, h3 { letter-spacing: -0.02em; }
+  .container { max-width: 1120px; margin: 0 auto; padding: 0 1.5rem; width: 100%; }
+  .container-narrow { max-width: 760px; margin: 0 auto; padding: 0 1.5rem; width: 100%; }
+  .btn {
+    display: inline-block; padding: 0.6rem 1.15rem; border-radius: 0.5rem;
+    font-weight: 600; font-size: 0.9375rem; border: 1px solid transparent;
+    cursor: pointer; transition: background 0.15s, border-color 0.15s, transform 0.05s;
+  }
+  .btn:active { transform: translateY(1px); }
+  .btn-primary { background: var(--primary); color: var(--primary-fg); }
+  .btn-primary:hover { background: var(--primary-hover); color: var(--primary-fg); }
+  .btn-secondary { background: var(--bg-card); color: var(--fg); border-color: var(--border); }
+  .btn-secondary:hover { border-color: var(--fg-muted); color: var(--fg); }
+
+  section { padding: 5rem 0; }
+  .section-head { text-align: center; max-width: 640px; margin: 0 auto 3rem; }
+  .section-head h2 { font-size: clamp(1.6rem, 3.5vw, 2.25rem); margin: 0 0 0.75rem; }
+  .section-head p { color: var(--fg-muted); margin: 0; font-size: 1.0625rem; }
+  .eyebrow { display: inline-block; font-size: 0.8125rem; font-weight: 600; letter-spacing: 0.04em;
+    text-transform: uppercase; color: var(--accent-hover, var(--primary)); margin-bottom: 0.75rem; }
+`;
+const HERO = `
+  .hero { padding: 4.5rem 0 4rem; }
+  .hero-grid { display: grid; grid-template-columns: 1.05fr 1fr; gap: 3.5rem; align-items: center; }
+  .hero-pony { width: 88px; height: 88px; margin: 0 0 1.1rem; display: block; }
+  .hero h1 { font-size: clamp(2.1rem, 4.5vw, 3.4rem); line-height: 1.08; margin: 0 0 1.1rem; font-weight: 700; }
+  .hero .tagline { font-size: clamp(1.05rem, 1.6vw, 1.25rem); color: var(--fg-muted); margin: 0 0 1.75rem; max-width: var(--hero-tagline-max, none); }
+  .hero-cta { display: flex; gap: 0.75rem; flex-wrap: wrap; }
+  .hero-meta { margin-top: 1.5rem; font-size: 0.875rem; color: var(--fg-subtle); }
+  .hero-meta strong { color: var(--fg-muted); font-weight: 600; }
+  .shot-frame { border-radius: 0.75rem; border: 1px solid var(--border); background: var(--bg-card);
+    box-shadow: var(--shadow); overflow: hidden; cursor: zoom-in; }
+  .shot-bar { display: flex; gap: 0.4rem; padding: 0.6rem 0.85rem; border-bottom: 1px solid var(--border); background: var(--bg-muted); }
+  .shot-bar span { width: 0.65rem; height: 0.65rem; border-radius: 50%; background: var(--border); }
+  .shot-frame img { display: block; width: 100%; height: auto; }
+  .apex-lightbox { border: none; padding: 0; margin: auto; max-width: 95vw; max-height: 90vh;
+    background: transparent; overflow: visible; }
+  .apex-lightbox::backdrop { background: rgba(15, 23, 42, 0.72); }
+  .apex-lightbox__img { display: block; max-width: 90vw; max-height: 85vh; width: auto; height: auto;
+    border-radius: 0.75rem; border: 1px solid var(--border); box-shadow: var(--shadow); }
+  .apex-lightbox__close { position: fixed; top: 1rem; right: 1rem; z-index: 1; width: 2.5rem; height: 2.5rem;
+    border: 1px solid var(--border); border-radius: 0.5rem; background: var(--bg-card); color: var(--fg);
+    font-size: 1.5rem; line-height: 1; cursor: pointer; }
+  .apex-lightbox__close:hover { background: var(--bg-muted); }
+  .apex-lightbox__prev, .apex-lightbox__next { position: fixed; top: 50%; transform: translateY(-50%); z-index: 1;
+    width: 2.5rem; height: 2.5rem; border: 1px solid var(--border); border-radius: 0.5rem;
+    background: var(--bg-card); color: var(--fg); font-size: 1.75rem; line-height: 1; cursor: pointer; }
+  .apex-lightbox__prev { left: 1rem; }
+  .apex-lightbox__next { right: 1rem; }
+  .apex-lightbox__prev:hover, .apex-lightbox__next:hover { background: var(--bg-muted); }
+  .apex-lightbox__prev[hidden], .apex-lightbox__next[hidden] { display: none; }
+  .apex-dark .apex-lightbox__prev, .apex-dark .apex-lightbox__next { background: var(--on-dark); color: var(--primary); border-color: var(--on-dark-border); }
+  .apex-dark .apex-lightbox__close { background: var(--on-dark); color: var(--primary); border-color: var(--on-dark-border); }
+`;
+const FEATURES = `
+  .features { background: var(--bg-muted); }
+  .feature-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 1.5rem; }
+  .feature { background: var(--bg-card); border: 1px solid var(--border); border-radius: 0.75rem; padding: 1.75rem; }
+  .feature-icon { width: 2.5rem; height: 2.5rem; border-radius: 0.6rem; display: flex; align-items: center;
+    justify-content: center; background: color-mix(in srgb, var(--primary) 9%, transparent); color: var(--primary); margin-bottom: 1rem; }
+  .feature-icon svg { width: 1.35rem; height: 1.35rem; }
+  .feature h3 { font-size: 1.0625rem; margin: 0 0 0.4rem; }
+  .feature p { color: var(--fg-muted); margin: 0; font-size: 0.9375rem; }
+`;
+const PRICING = `
+  .price-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 1.25rem; align-items: stretch; }
+  .price-card { position: relative; background: var(--bg-card); border: 1px solid var(--border);
+    border-radius: 0.75rem; padding: 1.75rem 1.5rem; display: flex; flex-direction: column; gap: 0.85rem; }
+  .price-card--featured { border-color: var(--primary); box-shadow: var(--shadow); }
+  .price-badge { position: absolute; top: -0.7rem; left: 50%; transform: translateX(-50%);
+    background: var(--accent, var(--primary)); color: var(--accent-fg, var(--primary-fg)); font-size: 0.75rem; font-weight: 700;
+    padding: 0.2rem 0.7rem; border-radius: 999px; white-space: nowrap; }
+  .price-card h3 { margin: 0; font-size: 1.25rem; }
+  .price-tagline { margin: 0; color: var(--fg-subtle); font-size: 0.875rem; }
+  .price-amount { font-size: 2rem; font-weight: 700; font-family: var(--font-mono, inherit); }
+  .price-amount span { font-size: 0.9375rem; font-weight: 500; color: var(--fg-subtle); font-family: inherit; }
+  .price-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 0.55rem; flex: 1; }
+  .price-list li { position: relative; padding-left: 1.5rem; font-size: 0.9rem; color: var(--fg-muted); }
+  .price-list li::before { content: ""; position: absolute; left: 0; top: 0.45rem; width: 0.7rem; height: 0.4rem;
+    border-left: 2px solid var(--status-ok); border-bottom: 2px solid var(--status-ok); transform: rotate(-45deg); }
+  .price-list li.price-cap { font-weight: 600; color: var(--fg); }
+  .price-card .btn { text-align: center; margin-top: 0.5rem; }
+`;
+const TRUST = `
+  .trust-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 2rem; }
+  .trust-item h3 { font-size: 1.0625rem; margin: 0 0 0.4rem; }
+  .trust-item p { color: var(--fg-muted); margin: 0; font-size: 0.9375rem; }
+`;
+const FINAL_CTA = `
+  .final-cta { text-align: center; }
+  .final-cta-pony { width: 96px; height: auto; display: block; margin: 0 auto 1rem; }
+  .final-cta h2 { font-size: clamp(1.6rem, 3.5vw, 2.25rem); margin: 0 0 0.75rem; }
+  .final-cta p { color: var(--fg-muted); margin: 0 0 1.75rem; font-size: 1.0625rem; }
+`;
+// Light chrome (default). Header floats translucent over the page; footer is a
+// muted band. Dark theme overrides both below.
+const CHROME_LIGHT = `
+  header { position: sticky; top: 0; z-index: 10;
+    background: color-mix(in srgb, var(--bg) 85%, transparent);
+    backdrop-filter: saturate(140%) blur(8px);
+    border-bottom: 1px solid var(--border); }
+  .nav { position: relative; display: flex; align-items: center; justify-content: space-between; gap: 1rem; padding-block: 0.85rem; }
+  .brand { display: flex; align-items: center; gap: 0.55rem; font-weight: 700; font-size: 1.125rem; color: var(--fg); }
+  .brand a { color: var(--fg); display: inline-flex; align-items: center; gap: 0.55rem; }
+  .brand a:hover { color: var(--fg); }
+  .brand img { width: 1.7rem; height: 1.7rem; border-radius: 0.4rem; }
+  .nav-links { display: flex; gap: 1.5rem; align-items: center; font-size: 0.9375rem; }
+  .nav-links a { color: var(--fg-muted); }
+  .nav-links a:hover { color: var(--fg); }
+  .nav-actions { display: flex; gap: 0.75rem; align-items: center; font-size: 0.9375rem; }
+  .nav-actions > a:not(.btn) { color: var(--fg-muted); }
+  .nav-actions > a:not(.btn):hover { color: var(--fg); }
+  @media (max-width: 640px) { .nav-links { display: none; } }
+
+  footer { border-top: 1px solid var(--border); color: var(--fg-subtle); padding: 3.5rem 0 2.5rem; font-size: 0.9rem; }
+  .footer-grid { display: grid; gap: 2rem; grid-template-columns: 1.6fr repeat(var(--footer-cols, 2), 1fr); }
+  .footer-brand { display: flex; align-items: center; gap: 0.55rem; font-weight: 700; color: var(--fg); margin-bottom: 0.75rem; }
+  .footer-brand img { width: 1.6rem; height: 1.6rem; border-radius: 0.4rem; }
+  .footer-tagline { color: var(--fg-subtle); max-width: 34ch; margin: 0; }
+  .footer-col h4 { font-size: 0.8125rem; text-transform: uppercase; letter-spacing: 0.04em; color: var(--fg-subtle); margin: 0 0 0.85rem; }
+  .footer-col a { display: block; color: var(--fg-muted); margin-bottom: 0.5rem; }
+  .footer-col a:hover { color: var(--fg); }
+  .footer-bottom { margin-top: 2.5rem; padding-top: 1.5rem; border-top: 1px solid var(--border);
+    display: flex; flex-wrap: wrap; justify-content: space-between; gap: 0.75rem; }
+`;
+// Dark sandwich: header/hero/final-cta/footer ride on --primary. Buttons invert
+// (a --primary button on --primary would vanish) → light button, --primary text.
+const CHROME_DARK = `
+  .apex-dark header { background: var(--primary); backdrop-filter: none; border-bottom: 1px solid var(--on-dark-border); }
+  .apex-dark .brand, .apex-dark .brand a, .apex-dark .brand a:hover { color: var(--on-dark); }
+  .apex-dark .nav-links a { color: var(--on-dark-muted); }
+  .apex-dark .nav-links a:hover { color: var(--on-dark); }
+  .apex-dark .nav-actions > a:not(.btn) { color: var(--on-dark-muted); }
+  .apex-dark .nav-actions > a:not(.btn):hover { color: var(--on-dark); }
+  .apex-dark header .btn-primary { background: var(--on-dark); color: var(--primary); }
+  .apex-dark header .btn-primary:hover { background: rgba(255,255,255,0.85); color: var(--primary-hover); }
+
+  .apex-dark .hero { background: var(--primary); color: var(--on-dark); }
+  .apex-dark .hero h1 { color: var(--on-dark); }
+  .apex-dark .hero .tagline { color: var(--on-dark-muted); }
+  .apex-dark .hero .btn-primary, .apex-dark .final-cta .btn-primary { background: var(--on-dark); color: var(--primary); }
+  .apex-dark .hero .btn-primary:hover, .apex-dark .final-cta .btn-primary:hover { background: rgba(255,255,255,0.85); color: var(--primary-hover); }
+  .apex-dark .hero .btn-secondary { background: rgba(255,255,255,0.08); color: var(--on-dark); border-color: rgba(255,255,255,0.30); }
+  .apex-dark .hero .btn-secondary:hover { background: rgba(255,255,255,0.16); color: var(--on-dark); border-color: rgba(255,255,255,0.5); }
+  .apex-dark .hero-meta { color: rgba(255,255,255,0.55); }
+  .apex-dark .hero-meta strong { color: var(--on-dark-muted); }
+
+  .apex-dark .final-cta { background: var(--primary); color: var(--on-dark); }
+  .apex-dark .final-cta h2 { color: var(--on-dark); }
+  .apex-dark .final-cta p { color: var(--on-dark-muted); }
+
+  .apex-dark footer { background: var(--primary); color: var(--on-dark-muted); border-top: none; }
+  .apex-dark .footer-brand { color: var(--on-dark); }
+  .apex-dark .footer-tagline { color: var(--on-dark-muted); }
+  .apex-dark .footer-col h4 { color: var(--on-dark-muted); }
+  .apex-dark .footer-col a { color: var(--on-dark-muted); }
+  .apex-dark .footer-col a:hover { color: var(--on-dark); }
+  .apex-dark .footer-bottom { border-top: 1px solid var(--on-dark-border); }
+`;
+const RESPONSIVE = `
+  @media (max-width: 900px) {
+    .hero-grid { grid-template-columns: 1fr; gap: 2.5rem; }
+    .feature-grid { grid-template-columns: repeat(2, 1fr); }
+    .price-grid { grid-template-columns: repeat(2, 1fr); }
+    .footer-grid { grid-template-columns: 1fr 1fr; }
+  }
+  @media (max-width: 640px) {
+    section { padding: 3.5rem 0; }
+    .feature-grid, .price-grid, .trust-grid, .footer-grid { grid-template-columns: 1fr; }
+  }
+`;
+// header renders navLinks TWICE (renderApexHeader): a plain always-visible
+// .nav-links row, plus a copy nested in .nav-toggle for < 640px — a closed
+// <details> can't be forced "always open" on desktop via CSS (Chrome keeps
+// its content unpainted regardless of a child's own `display`), so two
+// copies sidestep that instead of fighting it. Exported standalone so a
+// consumer rendering its own header chrome can include just this. A
+// consumer using renderApexHeader() outside renderApexPage also needs
+// APEX_NAV_TOGGLE_RESPONSIVE_CSS below for the mobile toggle to open.
+export const APEX_NAV_MENU_CSS = `
+  .nav-toggle { display: none; }
+  .nav-toggle__trigger { display: none; align-items: center; justify-content: center;
+    width: 2.25rem; height: 2.25rem; border-radius: 0.5rem; cursor: pointer;
+    color: var(--fg-muted); list-style: none; }
+  .nav-toggle__trigger::-webkit-details-marker { display: none; }
+  .nav-toggle__trigger:hover { color: var(--fg); background: var(--bg-muted); }
+  .nav-toggle__trigger svg { width: 1.35rem; height: 1.35rem; }
+  .apex-dark .nav-toggle__trigger { color: var(--on-dark-muted); }
+  .apex-dark .nav-toggle__trigger:hover { color: var(--on-dark); background: rgba(255,255,255,0.08); }
+
+  .nav-menu { position: relative; display: inline-flex; }
+  .nav-menu__trigger { display: inline-flex; align-items: center; gap: 0.3rem;
+    font: inherit; font-size: 0.9375rem; color: var(--fg-muted);
+    cursor: pointer; list-style: none; }
+  .nav-menu__trigger::-webkit-details-marker { display: none; }
+  .nav-menu__trigger:hover { color: var(--fg); }
+  .nav-menu__chev { display: inline-flex; transition: transform 0.15s; opacity: 0.7; }
+  .nav-menu__chev svg { width: 0.95em; height: 0.95em; }
+  .nav-menu[open] .nav-menu__chev { transform: rotate(180deg); }
+  .nav-menu__panel { position: absolute; top: calc(100% + 0.5rem); left: 0; z-index: 20;
+    min-width: 21rem; padding: 0.5rem; background: var(--bg-card); color: var(--fg);
+    border: 1px solid var(--border); border-radius: 0.75rem; box-shadow: var(--shadow);
+    flex-direction: column; gap: 0.125rem; }
+  .nav-menu[open] .nav-menu__panel { display: flex; }
+  .nav-menu__item { display: flex; gap: 0.75rem; align-items: flex-start;
+    padding: 0.6rem 0.7rem; border-radius: 0.5rem; color: var(--fg); }
+  .nav-menu__item:hover { background: var(--bg-muted); color: var(--fg); }
+  .nav-menu__icon { flex: none; display: inline-flex; align-items: center; justify-content: center;
+    width: 2rem; height: 2rem; border-radius: 0.5rem;
+    background: color-mix(in srgb, var(--primary) 12%, transparent); color: var(--primary); }
+  .nav-menu__icon svg { width: 1.1rem; height: 1.1rem; }
+  .nav-menu__text { display: flex; flex-direction: column; gap: 0.1rem; }
+  .nav-menu__title { font-weight: 600; font-size: 0.9rem; line-height: 1.2; }
+  .nav-menu__desc { font-size: 0.8rem; color: var(--fg-muted); line-height: 1.35; }
+  .nav-menu__sep { height: 1px; background: var(--border); margin: 0.375rem 0.3rem; }
+  .nav-menu__more { display: inline-flex; padding: 0.4rem 0.7rem; font-size: 0.85rem; font-weight: 600; color: var(--primary); }
+  .nav-menu__more:hover { color: var(--primary-hover); }
+  .apex-dark .nav-menu__trigger { color: var(--on-dark-muted); }
+  .apex-dark .nav-menu__trigger:hover { color: var(--on-dark); }
+  /* The panel is a light popover; its links must NOT inherit the dark-chrome
+     nav-link color (.apex-dark .nav-links a, specificity 0,2,1) or a consumer's
+     own .nav-links a. Pin both link types with matching specificity (0,2,1) so
+     titles + the footer link stay readable in the dark theme. */
+  .nav-menu__panel a.nav-menu__item { color: var(--fg); }
+  .nav-menu__panel a.nav-menu__item:hover { color: var(--fg); }
+  .nav-menu__panel a.nav-menu__more { color: var(--primary); }
+  .nav-menu__panel a.nav-menu__more:hover { color: var(--primary-hover); }
+`;
+// Standalone mobile-open rules for .nav-toggle, split out of RESPONSIVE so a
+// consumer calling renderApexHeader() outside renderApexPage (money-horse,
+// show-pony, the docs sample) can include just this alongside
+// APEX_NAV_MENU_CSS, without pulling in the rest of RESPONSIVE's page-level
+// grid breakpoints. The two "show" rules use the `.nav ` prefix (matching
+// renderApexHeader's `<div class="container nav">` wrapper) to raise their
+// specificity above APEX_NAV_MENU_CSS's bare `.nav-toggle`/`.nav-toggle__trigger`
+// "display: none" defaults — that makes them win regardless of concatenation
+// order, since a standalone consumer controls the order, not this file.
+// Also declares `.nav { position: relative; }`: the open dropdown positions
+// itself against .nav (`top/left/right` below), and renderApexPage's own
+// CHROME_LIGHT already sets that, but a standalone consumer's own header CSS
+// generally doesn't — without it the dropdown would anchor to the viewport
+// instead of the header and open off-screen. Redeclaring it here is a no-op
+// inside APEX_STRUCTURAL_CSS (same value, harmless if repeated).
+export const APEX_NAV_TOGGLE_RESPONSIVE_CSS = `
+  @media (max-width: 640px) {
+    .nav { position: relative; }
+    .nav .nav-toggle { display: inline-flex; }
+    .nav .nav-toggle__trigger { display: inline-flex; }
+    .nav-toggle[open] > .nav-links { display: flex; flex-direction: column; align-items: stretch;
+      gap: 0.25rem; position: absolute; top: calc(100% + 0.5rem); left: 0; right: 0; z-index: 30;
+      background: var(--bg-card); border: 1px solid var(--border); border-radius: 0.75rem;
+      box-shadow: var(--shadow); padding: 0.75rem; }
+    .nav-toggle[open] > .nav-links > a { color: var(--fg); padding: 0.4rem 0.25rem; }
+    .nav-toggle[open] > .nav-links > a:hover { color: var(--fg); }
+    .nav-toggle .nav-menu { display: block; }
+    .nav-toggle .nav-menu__panel { position: static; min-width: 0;
+      margin-top: 0.375rem; box-shadow: none; }
+  }
+`;
+export const APEX_STRUCTURAL_CSS = BASE_LAYOUT +
+    HERO +
+    FEATURES +
+    PRICING +
+    TRUST +
+    FINAL_CTA +
+    CHROME_LIGHT +
+    CHROME_DARK +
+    APEX_NAV_MENU_CSS +
+    APEX_NAV_TOGGLE_RESPONSIVE_CSS +
+    RESPONSIVE;

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

@@ -0,0 +1,236 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+export { APEX_NAV_MENU_CSS, APEX_NAV_TOGGLE_RESPONSIVE_CSS, APEX_STRUCTURAL_CSS } from "./css.ts";
+export { APEX_LIGHTBOX_HTML, APEX_LIGHTBOX_SCRIPT, APEX_LIGHTBOX_SCRIPT_CSP_HASH, } from "./lightbox.ts";
+export type ApexTheme = "light" | "dark";
+/** Brand is raw CSS the app owns: the :root token block and optional @font-face.
+ *  Token names referenced by the structural CSS: --bg --bg-card --bg-muted
+ *  --border --fg --fg-muted --fg-subtle --primary --primary-hover --primary-fg
+ *  --status-ok --shadow. Optional: --accent --accent-fg --font-mono --font-body,
+ *  and (dark theme) --on-dark --on-dark-muted --on-dark-border. */
+export type ApexBrand = {
+    readonly tokensCss: string;
+    readonly fontFaceCss?: string;
+};
+export type ApexCtaVariant = "primary" | "secondary" | "link";
+export type ApexCta = {
+    readonly label: string;
+    /** App-authored only, no user input — escapeHtml encodes entities but does
+     *  NOT sanitize the URL scheme (a `javascript:`/`data:` URI survives it
+     *  unchanged). Trust boundary is the deploy-time apex config, not runtime. */
+    readonly href: string;
+    /** "link" renders a plain anchor (no .btn). Default "primary". */
+    readonly variant?: ApexCtaVariant;
+};
+export type ApexLink = {
+    readonly kind?: "link";
+    readonly label: string;
+    readonly href: string;
+};
+/** One entry inside a dropdown nav menu: icon + title + optional description. */
+export type ApexNavMenuItem = {
+    /** Inner SVG markup (paths), wrapped by the standard 24px icon <svg>.
+     *  ponytail: rendered verbatim, no sanitizer — trusted because it's
+     *  app-authored at deploy time, same trust boundary as ApexCta.href. If an
+     *  app ever sources this from tenant/user content, sanitize at that
+     *  construction boundary before it reaches here. */
+    readonly icon?: string;
+    readonly title: string;
+    readonly desc?: string;
+    readonly href: string;
+};
+/** A header nav entry that opens a dropdown (icon/title/desc rows) instead of
+ *  navigating. CSS-only: reveals on hover + keyboard focus. */
+export type ApexNavMenu = {
+    readonly kind: "menu";
+    readonly label: string;
+    readonly items: readonly ApexNavMenuItem[];
+    /** Optional link under a divider at the foot of the panel (e.g. "See all →"). */
+    readonly footer?: ApexLink;
+};
+/** A header nav entry: a plain link, or a dropdown menu. */
+export type ApexNavEntry = ApexLink | ApexNavMenu;
+export type ApexImage = {
+    readonly src: string;
+    readonly alt: string;
+    readonly width?: number;
+    readonly height?: number;
+};
+export type ApexHeader = {
+    readonly brand: {
+        readonly href: string;
+        readonly label: string;
+        readonly logoSrc?: string;
+    };
+    /** Plain links and/or dropdown menus, in order. */
+    readonly navLinks?: readonly ApexNavEntry[];
+    readonly actions?: readonly ApexCta[];
+    /** aria-label for the mobile hamburger trigger (< 640px). Default "Menu". */
+    readonly menuLabel?: string;
+};
+export type ApexFooterColumn = {
+    readonly heading: string;
+    readonly links: readonly ApexLink[];
+};
+export type ApexFooter = {
+    readonly brand: {
+        readonly label: string;
+        readonly logoSrc?: string;
+    };
+    readonly tagline?: string;
+    readonly columns?: readonly ApexFooterColumn[];
+    /** Plain text — use unicode (© ·), not HTML entities; rendered escaped. */
+    readonly bottomLeft?: string;
+    readonly bottomRight?: string;
+};
+export type ApexHeroSection = {
+    readonly kind: "hero";
+    readonly logo?: ApexImage;
+    readonly title: string;
+    readonly tagline: string;
+    readonly ctas?: readonly ApexCta[];
+    /** App-authored trusted HTML (e.g. <strong>…<br/>); rendered verbatim. */
+    readonly metaHtml?: string;
+    readonly screenshot?: ApexImage;
+};
+export type ApexFeature = {
+    /** Inner SVG markup (paths), wrapped by the standard 24px icon <svg>.
+     *  ponytail: rendered verbatim, no sanitizer — trusted because it's
+     *  app-authored at deploy time, same trust boundary as ApexCta.href. If an
+     *  app ever sources this from tenant/user content, sanitize at that
+     *  construction boundary before it reaches here. */
+    readonly icon?: string;
+    readonly title: string;
+    readonly desc: string;
+};
+export type ApexFeatureGridSection = {
+    readonly kind: "feature-grid";
+    readonly id?: string;
+    readonly eyebrow?: string;
+    readonly heading: string;
+    readonly sub?: string;
+    /** Sit on the muted band (.features). Default true. */
+    readonly muted?: boolean;
+    readonly items: readonly ApexFeature[];
+};
+export type ApexPricingTier = {
+    readonly name: string;
+    readonly tagline?: string;
+    /** App-formatted ("4,99 €", "0 €", "auf Anfrage"). */
+    readonly amount: string;
+    /** Localized suffix after the amount ("/Monat", "/month"). */
+    readonly priceSuffix?: string;
+    readonly featured?: boolean;
+    readonly badge?: string;
+    readonly capLine?: string;
+    readonly benefits: readonly string[];
+    readonly cta: ApexCta;
+};
+export type ApexPricingGridSection = {
+    readonly kind: "pricing-grid";
+    readonly id?: string;
+    readonly eyebrow?: string;
+    readonly heading: string;
+    readonly sub?: string;
+    readonly tiers: readonly ApexPricingTier[];
+};
+export type ApexInfoItem = {
+    readonly title: string;
+    readonly desc: string;
+};
+export type ApexInfoGridSection = {
+    readonly kind: "info-grid";
+    readonly id?: string;
+    readonly eyebrow?: string;
+    readonly heading?: string;
+    readonly sub?: string;
+    readonly muted?: boolean;
+    readonly items: readonly ApexInfoItem[];
+};
+export type ApexFinalCtaSection = {
+    readonly kind: "final-cta";
+    readonly image?: ApexImage;
+    readonly heading: string;
+    readonly sub?: string;
+    readonly cta: ApexCta;
+};
+/** Escape hatch for an app-specific section: raw, app-authored HTML. */
+export type ApexHtmlSection = {
+    readonly kind: "html";
+    readonly html: string;
+};
+export type ApexSection = ApexHeroSection | ApexFeatureGridSection | ApexPricingGridSection | ApexInfoGridSection | ApexFinalCtaSection | ApexHtmlSection;
+export type ApexHead = {
+    readonly lang: string;
+    readonly title: string;
+    readonly description: string;
+    readonly canonicalUrl?: string;
+    readonly faviconHref?: string;
+    readonly ogImage?: string;
+    /** hreflang alternates for multilingual SEO (e.g. the other language's URL). */
+    readonly alternates?: readonly {
+        readonly hreflang: string;
+        readonly href: string;
+    }[];
+    /** Robots meta content (e.g. "index, follow", "noindex, nofollow"). Omit = no tag. */
+    readonly robots?: string;
+    /** og:site_name — brand name for social shares. */
+    readonly siteName?: string;
+    /** og:locale — e.g. "de_DE", "en_US". */
+    readonly locale?: string;
+    /** twitter:site — @handle for X/Twitter card. */
+    readonly twitterSite?: string;
+    /** URLs for <link rel="preconnect"> hints (Core Web Vitals). */
+    readonly preconnects?: readonly string[];
+    /** Arbitrary JSON-LD structured data (Schema.org). Rendered as-is into <script type="application/ld+json">. */
+    readonly schemaJson?: Record<string, unknown>;
+};
+export type ApexPage = {
+    readonly theme?: ApexTheme;
+    readonly brand: ApexBrand;
+    readonly head: ApexHead;
+    readonly header: ApexHeader;
+    readonly sections: readonly ApexSection[];
+    readonly footer: ApexFooter;
+};
+/** 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 declare function renderApexHeader(h: ApexHeader): string;
+export declare function renderApexHeadTags(head: ApexHead): string;
+export declare function renderApexPage(page: ApexPage): string;
+/** Per-request head metadata (Open-Graph/title/description) for a
+ *  server-rendered HTML shell. Only `title` is required; everything else
+ *  falls back to no tag rather than a placeholder. */
+export type PageHeadMeta = {
+    readonly title: string;
+    readonly description?: string;
+    readonly ogImage?: string;
+    readonly canonicalUrl?: string;
+    readonly siteName?: string;
+    readonly locale?: string;
+};
+export type PageHeadSystemQuery = (type: string, payload: unknown, tenantId: TenantId, options?: {
+    readonly signal?: AbortSignal;
+}) => Promise<unknown>;
+export type PageHeadResolver = (input: {
+    readonly path: string;
+    readonly host: string;
+    readonly preferredLocales: readonly string[];
+    readonly systemQuery: PageHeadSystemQuery;
+    readonly signal: AbortSignal;
+}) => Promise<PageHeadMeta | null>;
+export type PageHeadResolveInput = {
+    readonly path: string;
+    readonly host: string;
+    readonly preferredLocales: readonly string[];
+    readonly systemQuery: PageHeadSystemQuery;
+    readonly requestSignal?: AbortSignal | undefined;
+};
+export declare function injectPageHead(html: string, tagsHtml: string): string;
+/** 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 declare function resolveAndInjectPageHead(html: string, resolvePageHead: PageHeadResolver, input: PageHeadResolveInput): Promise<string>;