@uiresponse/renderer-react 0.1.0

package/src/core/value.js

@@ -0,0 +1,211 @@
+/**
+ * OBL values and bindings — resolved against rows the resolver returned.
+ *
+ * A block prop holds one of four things (binding.schema.json#value):
+ *
+ *   42 | "Total" | true | null        a literal   (always a JSON scalar)
+ *   {"$bind": {...}}                  a binding   (always an object)
+ *   {"$param": "artist_id"}           a parameter
+ *   {"$now": {...}}                   a resolve-time date
+ *   {"$self": true}                   the value the user just entered  (input.on_change only)
+ *
+ * The union needs no discriminator because literals are scalars and the rest are objects (B3).
+ *
+ * A binding's ARITY falls out of which keys it carries (B4). We never guess:
+ *
+ *   {dataset}                          rows    a table's rows, a list's items
+ *   {dataset, field}                   column  a chart axis
+ *   {dataset, field, aggregate}        scalar  a metric's value
+ *   {dataset, aggregate: "count"}      scalar  the one fieldless scalar: a row count
+ *   {dataset, field, row}              scalar  the latest statement date
+ *   {dataset, field, scope: "row"}     scalar  THIS row's value, inside a repeating element
+ *
+ * `row: "only"` is an ASSERTION (B6): ≠1 row is a loud error, never a quietly-wrong number.
+ */
+
+export const isBinding = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "$bind" in v;
+export const isParamRef = (v) => v !== null && typeof v === "object" && typeof v.$param === "string";
+export const isNowRef = (v) => v !== null && typeof v === "object" && v.$now !== null && typeof v.$now === "object";
+export const isSelfRef = (v) => v !== null && typeof v === "object" && v.$self === true;
+
+/** A value that is present. `null` is absent; `0` and `""` and `false` are present. */
+export const isPresent = (v) => v !== null && v !== undefined;
+
+export class UIResponseResolveError extends Error {}
+
+export function bindingArity(bind) {
+  if (!bind.field) return bind.aggregate ? "scalar" : "rows";
+  if (bind.aggregate || bind.row || bind.scope === "row") return "scalar";
+  return "column";
+}
+
+// ---------------------------------------------------------------------------
+// $now
+// ---------------------------------------------------------------------------
+
+function truncate(d, unit) {
+  const out = new Date(d);
+  switch (unit) {
+    case "year": out.setMonth(0, 1); out.setHours(0, 0, 0, 0); break;
+    case "quarter": out.setMonth(Math.floor(out.getMonth() / 3) * 3, 1); out.setHours(0, 0, 0, 0); break;
+    case "month": out.setDate(1); out.setHours(0, 0, 0, 0); break;
+    case "week": { const dow = (out.getDay() + 6) % 7; out.setDate(out.getDate() - dow); out.setHours(0, 0, 0, 0); break; }
+    case "day": out.setHours(0, 0, 0, 0); break;
+    default: break;
+  }
+  return out;
+}
+
+/**
+ * `$now` on the READ path only. A `$now` inside a `mutate.set` is resolved SERVER-side by the
+ * resolver — a client's clock is untrusted input and "when was this chased" is an audit field
+ * (DECISIONS A10). The renderer never computes one for a write.
+ */
+export function resolveNow(nowRef, now) {
+  const spec = nowRef.$now ?? {};
+  let d = new Date(now);
+  if (spec.offset_days) d.setDate(d.getDate() + spec.offset_days);
+  if (spec.offset_months) d.setMonth(d.getMonth() + spec.offset_months);
+  if (spec.offset_years) d.setFullYear(d.getFullYear() + spec.offset_years);
+  if (spec.truncate) d = truncate(d, spec.truncate);
+  return d;
+}
+
+// ---------------------------------------------------------------------------
+// aggregates
+// ---------------------------------------------------------------------------
+
+const numeric = (xs) => xs.filter((x) => x !== null && x !== undefined && x !== "" && Number.isFinite(Number(x))).map(Number);
+
+function median(xs) {
+  if (!xs.length) return null;
+  const s = [...xs].sort((a, b) => a - b);
+  const mid = s.length >> 1;
+  return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+
+/**
+ * `count` has two spellings and they mean different things (binding.schema.json#aggregate):
+ * fieldless counts ROWS; with a field it counts rows where that field is non-null.
+ */
+export function aggregate(rows, field, fn) {
+  if (fn === "count") return field ? rows.filter((r) => isPresent(r[field])).length : rows.length;
+  if (fn === "count_distinct") return new Set(rows.map((r) => r[field]).filter(isPresent)).size;
+
+  const values = numeric(rows.map((r) => r[field]));
+  // An empty column is ABSENT, not zero. `sum` of nothing is not 0 — it is "no statements filed",
+  // and it must flow into the `empty` policy rather than render as £0.00 (DECISIONS B8).
+  if (!values.length) return null;
+
+  switch (fn) {
+    case "sum": return values.reduce((a, b) => a + b, 0);
+    case "avg": return values.reduce((a, b) => a + b, 0) / values.length;
+    case "min": return Math.min(...values);
+    case "max": return Math.max(...values);
+    case "median": return median(values);
+    default: throw new UIResponseResolveError(`unknown aggregate "${fn}"`);
+  }
+}
+
+function pickRow(rows, selector, bind) {
+  if (selector === "only") {
+    if (rows.length !== 1) {
+      // The assertion exists so a wrong number is loud rather than plausible.
+      throw new UIResponseResolveError(
+        `\`row: "only"\` on \`${bind.dataset}.${bind.field}\` requires exactly one row; the dataset resolved ${rows.length}.`,
+      );
+    }
+    return rows[0];
+  }
+  if (!rows.length) return null;
+  return selector === "last" ? rows[rows.length - 1] : rows[0];
+}
+
+// ---------------------------------------------------------------------------
+// resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} Scope
+ * @property {(name:string) => {rows: object[], columns: object[]}} dataset  resolved datasets
+ * @property {object} params    current page parameter values
+ * @property {object} [row]     the current row, inside a repeating element
+ * @property {Date}   now
+ */
+
+/** The column declaration a binding points at, or null. Drives format defaults and alignment. */
+export function boundColumn(bind, scope) {
+  if (!bind?.field) return null;
+  const ds = scope.dataset(bind.dataset);
+  return ds?.columns?.find((c) => c.name === bind.field) ?? null;
+}
+
+/** Resolve a `$bind` to its value, at whatever arity its keys declare. */
+export function resolveBinding(bind, scope) {
+  const ds = scope.dataset(bind.dataset);
+  if (!ds) throw new UIResponseResolveError(`dataset "${bind.dataset}" has not resolved`);
+  const rows = ds.rows ?? [];
+
+  switch (bindingArity(bind)) {
+    case "rows": return rows;
+    case "column": return rows.map((r) => r[bind.field]);
+    case "scalar": {
+      if (bind.scope === "row") {
+        // Row scope is explicit, never inferred from where the binding sits (DECISIONS R7).
+        if (!scope.row) throw new UIResponseResolveError(`\`scope: "row"\` used outside a repeating element`);
+        return scope.row[bind.field] ?? null;
+      }
+      if (bind.aggregate) return aggregate(rows, bind.field, bind.aggregate);
+      const picked = pickRow(rows, bind.row, bind);
+      return picked ? (picked[bind.field] ?? null) : null;
+    }
+    default: throw new UIResponseResolveError("unresolvable binding arity");
+  }
+}
+
+/**
+ * Resolve any member of the `value` union.
+ *
+ * `{"$self": true}` is the control's own value, and `scope.self` is how an `input` hands it in. A
+ * scope with no `self` is a scope with no control: the schema forbids `$self` there, so reaching this
+ * throw means the page was never validated. Guessing a value would be the renderer overriding the
+ * document, which is precisely the bug `$self` was added to end (DECISIONS B12).
+ *
+ * A control's value is never `undefined` — a cleared select is `null`, an empty field is `""`, an
+ * unticked toggle is `false` — so `undefined` unambiguously means "there is no control here".
+ */
+export function resolveValue(value, scope) {
+  if (isBinding(value)) return resolveBinding(value.$bind, scope);
+  if (isParamRef(value)) return scope.params?.[value.$param] ?? null;
+  if (isNowRef(value)) return resolveNow(value, scope.now);
+  if (isSelfRef(value)) {
+    if (scope.self === undefined) throw new UIResponseResolveError(`\`{"$self": true}\` used outside an input's \`on_change\``);
+    return scope.self;
+  }
+  return value; // literal
+}
+
+/** The `format` a value carries, if it is a binding. Literals carry none. */
+export const valueFormat = (value) => (isBinding(value) ? value.$bind.format : undefined);
+/** The `empty` policy a value carries. Omitted means `{show: "dash"}`. */
+export const valueEmpty = (value) => (isBinding(value) ? value.$bind.empty : undefined);
+/** The column a value is bound to, for format defaults. */
+export const valueColumn = (value, scope) => (isBinding(value) ? boundColumn(value.$bind, scope) : null);
+
+/** Which datasets does this subtree read? Used to build the load graph. */
+export function collectDatasets(node, out = new Set()) {
+  if (node === null || typeof node !== "object") return out;
+  if (Array.isArray(node)) { node.forEach((n) => collectDatasets(n, out)); return out; }
+  if (isBinding(node)) { if (node.$bind.dataset) out.add(node.$bind.dataset); return out; }
+  for (const v of Object.values(node)) collectDatasets(v, out);
+  return out;
+}
+
+/** Which parameters does this subtree read? Used to invalidate datasets on `set_param`. */
+export function collectParams(node, out = new Set()) {
+  if (node === null || typeof node !== "object") return out;
+  if (Array.isArray(node)) { node.forEach((n) => collectParams(n, out)); return out; }
+  if (isParamRef(node)) { out.add(node.$param); return out; }
+  for (const v of Object.values(node)) collectParams(v, out);
+  return out;
+}

package/src/index.js

@@ -0,0 +1,22 @@
+/**
+ * @uir/renderer-web — OBL's first-party React renderer.
+ *
+ * The public surface is deliberately small: one component, one theme helper, and the pure semantic
+ * functions a host might want (a chat surface that renders one metric inline, a test that asserts a
+ * currency formats correctly). Everything else is internal and may move.
+ */
+import "./theme/uir.css";
+
+export { UIResponsePage, default } from "./UIResponsePage.jsx";
+
+// Theme — the per-tenant brand story.
+export { defaultTheme, darkTheme, makeTheme, themeToCssVars, EMPHASIS_RANK } from "./theme/tokens.js";
+
+// Semantics, exported because they are the interesting part and they are pure.
+export { formatValue, isNumericFormat } from "./core/format.js";
+export { emptyRender, isEmptyValue, hidesBlock } from "./core/empty.js";
+export { evaluateCondition } from "./core/condition.js";
+export { resolveValue, resolveBinding, bindingArity, aggregate, collectDatasets, collectParams } from "./core/value.js";
+export { planDatasetOrder, flattenBlocks, overlayParams } from "./core/store.js";
+export { DISABLED_VERBS, isDisabledVerb, actionGate, verbReason } from "./core/actions.js";
+export { initialsFor, paginateRows, timelineLayout, formatAudioTime, isDestructiveAction, TABLE_PAGE_SIZE } from "./core/presentation.js";

package/src/theme/tokens.js

@@ -0,0 +1,364 @@
+/**
+ * The theme token layer.
+ *
+ * ── SOURCE OF TRUTH ───────────────────────────────────────────────────────────────────────────
+ *
+ * Every value below is extracted from `design/UIR-element-system.dc.html` — the element system Dan
+ * built and approved. That file, not this one, is the design authority. When they disagree, the
+ * design wins and this file changes.
+ *
+ * Extracted, not eyeballed: the sheets carry inline styles, and each number here was read out of
+ * them. The provenance is noted per group so the next person can re-derive it rather than trust me.
+ *
+ * ── WHAT THE RENDERER STILL OWNS ──────────────────────────────────────────────────────────────
+ *
+ * `@openuidev/react-ui`'s components keep their own styling — in the light theme we emit no
+ * `--openui-*` overrides at all. We remap them in dark only, because they ship a single light
+ * `:root` and their charts would otherwise sit white on a near-black ground. That is a repair, not
+ * a redecoration.
+ *
+ * Brand is not in the LLM's vocabulary: Principle 1 bans colour from the document. Every generated
+ * page is therefore on-brand by construction, because brand lives here and nowhere else.
+ */
+
+/** Blocks are ranked by `emphasis`; the renderer maps each rank to type scale and tile size. */
+export const EMPHASIS_RANK = { hero: 0, primary: 1, normal: 2, subtle: 3 };
+
+/**
+ * Streaming-arrival choreography. Lifted verbatim from the design's `<style>` block: `obFold`,
+ * `obShimmer`, `obTick`. A tile folds in when its data lands; the skeleton shimmers while it waits.
+ */
+export const motion = {
+  fold: "0.45s cubic-bezier(0.2, 0.7, 0.3, 1)",
+  shimmer: "1.4s linear infinite",
+  tick: "2.6s ease forwards",
+  // Sheet `2a · Chat to page prototype`. Extracted from its inline styles, not chosen.
+  slideIn: "0.32s cubic-bezier(0.2, 0.7, 0.3, 1)",
+  fade: "0.25s ease",
+  dot: "1.2s ease infinite",
+  barIn: "0.9s cubic-bezier(0.2, 0.7, 0.3, 1)",
+  // No count-up in the design. See `countUp` below and NOTES-designsync D7.
+  countUp: "0.62s cubic-bezier(0.2, 0.7, 0.3, 1)",
+};
+
+/** The overlay drawer, `2a`. A page presented, not a page navigated to (DECISIONS A13). */
+export const overlay = {
+  width: "372px",
+  scrim: "rgba(9, 9, 11, 0.18)",
+  shadow: "-16px 0 40px rgba(0, 0, 0, 0.1)",
+};
+
+export const defaultTheme = {
+  name: "OBL element system",
+  scheme: "light",
+
+  // Sheet light (`data-screen-label="Sheet light"`). Zinc neutrals.
+  color: {
+    ground: "#FFFFFF",
+    sheet: "#FFFFFF",
+    sunk: "#F4F4F5",        // segmented control track, row hover
+    sunkStrong: "#FAFAFA",  // shimmer highlight, button hover
+
+    ink: "#18181B",
+    muted: "#52525B",       // subtle metric value, legend labels
+    graphite: "#71717A",    // tile labels
+    faint: "#A1A1AA",       // column headers, captions, units
+
+    rule: "#E4E4E7",        // tile border
+    ruleSoft: "#F0F0F2",    // separators INSIDE a tile — lighter than its own border
+    ruleStrong: "#D4D4D8",
+
+    // The one accent. `#3B6FE6` is the design's default; its tweak offered teal and violet too.
+    brand: "#3B6FE6",
+    brandHover: "#2D5AC4",
+    brandSoft: "#EFF6FF",
+
+    // Status tones, from the design's `tones` map.
+    positive: "#177A3D",
+    positiveSoft: "#ECFDF3",
+    warning: "#B54708",
+    warningSoft: "#FFFAEB",
+    negative: "#B42318",
+    negativeSoft: "#FEF3F2",
+    info: "#175CD3",
+    infoSoft: "#EFF6FF",
+    neutral: "#52525B",
+    neutralSoft: "#F4F4F5",
+
+    /** The validation tick's check. Deliberately not `positive`: it is a mark, not a status. */
+    tick: "#16A34A",
+
+    focus: "#3B6FE6",
+  },
+
+  /** Only our own donut reads this. Their charts are handed no palette and keep their own. */
+  chart: ["#3B6FE6", "#A1A1AA", "#1F9E86", "#7A5AF0", "#B54708", "#B42318", "#175CD3", "#52525B"],
+  /** Sheet `02 · Chart`: one accent slice, then four desaturating neutrals. */
+  pie: ["#3B6FE6", "#A7BFF2", "#C9CDD4", "#A1A1AA", "#E4E4E7"],
+
+  font: {
+    body: `-apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", Roboto, system-ui, sans-serif`,
+    mono: `ui-monospace, Menlo, SFMono-Regular, Consolas, monospace`,
+    display: `-apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", Roboto, system-ui, sans-serif`,
+  },
+
+  /**
+   * The metric ladder, read off the four tiles in `01 · Metric`:
+   *   hero 44 / 600 / -0.02em    primary 30 / 600 / -0.015em
+   *   normal 22 / 600            subtle 17 / 500, in `muted`
+   * Emphasis is type scale and tile size. Never colour, never rule weight.
+   */
+  size: {
+    stamp: "0.625rem",     // 10px — the mono captions under each sheet tile
+    micro: "0.6875rem",    // 11px
+    small: "0.75rem",      // 12px — column headers, legend
+    label: "0.8125rem",    // 13px — a tile's label
+    base: "0.8125rem",     // 13px
+    large: "0.9375rem",    // 15px — a tile's title
+    heroValue: "2.75rem",     // 44px
+    primaryValue: "1.875rem", // 30px
+    normalValue: "1.375rem",  // 22px
+    subtleValue: "1.0625rem", // 17px
+    unit: "0.875rem",         // 14px
+  },
+
+  space: { xs: "4px", sm: "8px", md: "12px", lg: "16px", xl: "24px", xxl: "36px" },
+
+  /** Tile 12, inner element 8, control 6. */
+  radius: { sm: "6px", md: "8px", lg: "12px" },
+
+  /** Tile padding is asymmetric in the design: 18px vertical, 20px horizontal. */
+  tilePad: { y: "18px", x: "20px" },
+
+  shadow: "0 1px 2px rgba(0, 0, 0, 0.04)",
+
+  /** `rowPadY` in the design's table: 12 comfortable, 6 compact. */
+  density: { comfortable: "12px", compact: "6px" },
+
+  /** The skeleton's shimmer sweep. */
+  shimmer: { from: "#F0F0F2", to: "#FAFAFA" },
+
+  measure: "1260px", // the sheets are drawn at 1260px
+};
+
+/** Sheet dark (`data-screen-label="Sheet dark"`). The same system, inverted. */
+export const darkTheme = {
+  name: "OBL element system — dark",
+  scheme: "dark",
+  color: {
+    ground: "#0E0E10",
+    sheet: "#17171A",
+    sunk: "#232327",
+    sunkStrong: "#2A2A2F",
+
+    ink: "#F4F4F5",
+    muted: "#D4D4D8",
+    graphite: "#A1A1AA",
+    faint: "#6E6E78",
+
+    rule: "#2A2A2F",
+    ruleSoft: "#222227",
+    ruleStrong: "#34343B",
+
+    brand: "#6F95F2",       // the design's `accentDark` map for #3B6FE6
+    brandHover: "#8FAEF6",
+    brandSoft: "rgba(96, 165, 250, 0.14)",
+
+    positive: "#4ADE80",
+    positiveSoft: "rgba(74, 222, 128, 0.13)",
+    warning: "#FBBF24",
+    warningSoft: "rgba(251, 191, 36, 0.13)",
+    negative: "#F87171",
+    negativeSoft: "rgba(248, 113, 113, 0.14)",
+    info: "#60A5FA",
+    infoSoft: "rgba(96, 165, 250, 0.14)",
+    neutral: "#A1A1AA",
+    neutralSoft: "rgba(161, 161, 170, 0.16)",
+
+    tick: "#4ADE80",
+    focus: "#6F95F2",
+  },
+  chart: ["#6F95F2", "#A1A1AA", "#4CC5AE", "#A08CF5", "#FBBF24", "#F87171", "#60A5FA", "#D4D4D8"],
+  pie: ["#6F95F2", "#5372B8", "#52525B", "#3F3F46", "#2C2C31"],
+  shadow: "0 1px 2px rgba(0, 0, 0, 0.5)",
+  shimmer: { from: "#222227", to: "#2A2A2F" },
+};
+
+const kebab = (s) => s.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+
+/** Emit the token tree as CSS custom properties. */
+
+/**
+ * OPENUI'S SCHEME-DEPENDENT VARIABLES — the 50 custom properties whose value differs between
+ * `@openuidev/react-ui`'s light `:root` and its dark block. Extracted from their own
+ * `openui-defaults.css`, and guarded by a test that re-derives this exact set (`tests.mjs`).
+ *
+ * WHY THIS TABLE EXISTS. Their stylesheet ships its dark palette as a bare
+ * `@media (prefers-color-scheme: dark) { :root { … } }` with **no class or attribute opt-out**. So
+ * their components follow the OPERATING SYSTEM, not the document. This renderer used to emit nothing
+ * for OpenUI in light mode, on the reasoning that "their components keep their own styling exactly" —
+ * and that reasoning quietly assumed an unstyled OpenUI is light. **It is light only when the OS is.**
+ * On a dark-mode OS, an OBL page drawing its LIGHT theme got OpenUI's DARK palette underneath it:
+ * chart tick labels near-white on white, and any mark filled with `--openui-interactive-accent-default`
+ * (light `oklch(0.097…)`, dark `oklch(0.994…)`) invisible.
+ *
+ * The fix is to pin every scheme-dependent variable for whichever theme the DOCUMENT is drawing, in
+ * BOTH directions. Our vars land on `.uir-page`'s style attribute, which outranks `:root`, so pinning
+ * is sufficient — the media query still fires, and loses.
+ *
+ * The values are OpenUI's OWN, verbatim, so a light page on a light OS is pixel-identical to before
+ * this table existed. The dark half is then overridden by our neutrals below, exactly as it was.
+ *
+ * CAVEAT, stated because it will matter one day: our vars land on `.uir-page`, so anything OpenUI
+ * PORTALS outside that element (a popover mounted on `document.body`) still reads `:root` and still
+ * follows the OS. No component we use portals. If one ever does, the pin must move to a wrapper the
+ * portal inherits from, or to `:root` itself.
+ *
+ * Only 50 of the 213 properties their dark block redeclares actually change; the other 163 are
+ * restated identically and are none of our business. `tests.mjs` asserts that this table's keys are
+ * precisely the 50 that differ — so an OpenUI upgrade that adds a 51st fails the suite instead of
+ * silently reintroducing white-on-white.
+ */
+export const OPENUI_SCHEME_VARS = {
+  "--openui-background": { light: "oklch(0.97 0 89.876 / 1)", dark: "oklch(0.145 0 0 / 1)" },
+  "--openui-foreground": { light: "oklch(0.994 0 89.876 / 1)", dark: "oklch(0.205 0 0 / 1)" },
+  "--openui-popover-background": { light: "oklch(0.994 0 89.876 / 1)", dark: "oklch(0.205 0 0 / 1)" },
+  "--openui-sunk-light": { light: "oklch(0.097 0 0 / 0.02)", dark: "oklch(0.994 0 89.876 / 0.02)" },
+  "--openui-sunk": { light: "oklch(0.097 0 0 / 0.04)", dark: "oklch(0.994 0 89.876 / 0.04)" },
+  "--openui-sunk-deep": { light: "oklch(0.097 0 0 / 0.08)", dark: "oklch(0.994 0 89.876 / 0.08)" },
+  "--openui-elevated-light": { light: "oklch(0.097 0 0 / 0.04)", dark: "oklch(0.994 0 89.876 / 0.04)" },
+  "--openui-elevated": { light: "oklch(0.097 0 0 / 0.08)", dark: "oklch(0.994 0 89.876 / 0.08)" },
+  "--openui-elevated-strong": { light: "oklch(0.097 0 0 / 0.16)", dark: "oklch(0.994 0 89.876 / 0.16)" },
+  "--openui-elevated-intense": { light: "oklch(0.097 0 0 / 0.32)", dark: "oklch(0.994 0 89.876 / 0.32)" },
+  "--openui-overlay": { light: "oklch(0 0 0 / 0.4)", dark: "oklch(0 0 0 / 0.6)" },
+  "--openui-highlight-subtle": { light: "oklch(0.097 0 0 / 0.02)", dark: "oklch(0.994 0 89.876 / 0.02)" },
+  "--openui-highlight": { light: "oklch(0.097 0 0 / 0.04)", dark: "oklch(0.994 0 89.876 / 0.04)" },
+  "--openui-highlight-strong": { light: "oklch(0.097 0 0 / 0.08)", dark: "oklch(0.994 0 89.876 / 0.08)" },
+  "--openui-highlight-intense": { light: "oklch(0.097 0 0 / 0.32)", dark: "oklch(0.994 0 89.876 / 0.3)" },
+  "--openui-inverted-background": { light: "oklch(0.097 0 0 / 1)", dark: "oklch(0.994 0 89.876 / 1)" },
+  "--openui-text-neutral-primary": { light: "oklch(0.097 0 0 / 1)", dark: "oklch(0.985 0 89.876 / 1)" },
+  "--openui-text-neutral-secondary": { light: "oklch(0.097 0 0 / 0.5)", dark: "oklch(0.985 0 89.876 / 0.5)" },
+  "--openui-text-neutral-tertiary": { light: "oklch(0.097 0 0 / 0.2)", dark: "oklch(0.985 0 89.876 / 0.2)" },
+  "--openui-text-neutral-link": { light: "oklch(0.097 0 0 / 1)", dark: "oklch(0.985 0 89.876 / 1)" },
+  "--openui-text-brand": { light: "oklch(0.097 0 0 / 1)", dark: "oklch(0.994 0 89.876 / 1)" },
+  "--openui-text-accent-primary": { light: "oklch(0.994 0 89.876 / 1)", dark: "oklch(0.097 0 0 / 1)" },
+  "--openui-text-accent-secondary": { light: "oklch(0.994 0 89.876 / 0.5)", dark: "oklch(0.097 0 0 / 0.5)" },
+  "--openui-text-accent-tertiary": { light: "oklch(0.994 0 89.876 / 0.2)", dark: "oklch(0.097 0 0 / 0.2)" },
+  "--openui-text-success-primary": { light: "oklch(0.448 0.108 151.328 / 1)", dark: "oklch(0.871 0.136 154.449 / 1)" },
+  "--openui-text-alert-primary": { light: "oklch(0.476 0.103 61.907 / 1)", dark: "oklch(0.905 0.166 98.111 / 1)" },
+  "--openui-text-danger-primary": { light: "oklch(0.505 0.19 27.518 / 1)", dark: "oklch(0.808 0.103 19.571 / 1)" },
+  "--openui-text-danger-secondary": { light: "oklch(0.711 0.166 22.216 / 1)", dark: "oklch(0.885 0.059 18.334 / 1)" },
+  "--openui-text-danger-tertiary": { light: "oklch(0.808 0.103 19.571 / 1)", dark: "oklch(0.936 0.031 17.717 / 1)" },
+  "--openui-text-info-primary": { light: "oklch(0.424 0.181 265.638 / 1)", dark: "oklch(0.809 0.096 251.813 / 1)" },
+  "--openui-text-pink-primary": { light: "oklch(0.459 0.17 3.815 / 1)", dark: "oklch(0.823 0.11 346.018 / 1)" },
+  "--openui-text-purple-primary": { light: "oklch(0.438 0.198 303.724 / 1)", dark: "oklch(0.827 0.108 306.383 / 1)" },
+  "--openui-interactive-accent-default": { light: "oklch(0.097 0 0 / 1)", dark: "oklch(0.994 0 89.876 / 1)" },
+  "--openui-interactive-accent-hover": { light: "oklch(0.097 0 0 / 0.8)", dark: "oklch(0.994 0 89.876 / 0.8)" },
+  "--openui-interactive-accent-disabled": { light: "oklch(0.097 0 0 / 0.4)", dark: "oklch(0.994 0 89.876 / 0.4)" },
+  "--openui-interactive-accent-pressed": { light: "oklch(0.097 0 0 / 1)", dark: "oklch(0.994 0 89.876 / 1)" },
+  "--openui-chat-user-response-bg": { light: "oklch(0.097 0 0 / 0.08)", dark: "oklch(0.994 0 89.876 / 0.08)" },
+  "--openui-chat-user-response-text": { light: "oklch(0.097 0 0 / 1)", dark: "oklch(0.985 0 89.876 / 1)" },
+  "--openui-border-default": { light: "oklch(0.097 0 0 / 0.06)", dark: "oklch(0.994 0 89.876 / 0.06)" },
+  "--openui-border-interactive": { light: "oklch(0.097 0 0 / 0.12)", dark: "oklch(0.994 0 89.876 / 0.12)" },
+  "--openui-border-interactive-emphasis": { light: "oklch(0.097 0 0 / 0.3)", dark: "oklch(0.994 0 89.876 / 0.4)" },
+  "--openui-border-interactive-selected": { light: "oklch(0.097 0 0 / 1)", dark: "oklch(0.985 0 89.876 / 1)" },
+  "--openui-border-accent": { light: "oklch(0.097 0 0 / 0.08)", dark: "oklch(0.994 0 89.876 / 0.2)" },
+  "--openui-border-accent-emphasis": { light: "oklch(0.097 0 0 / 0.3)", dark: "oklch(0.994 0 89.876 / 0.4)" },
+  "--openui-shadow-s": { light: "0 1px 3px -2px oklch(0 0 0 / 0.02), 0 2px 5px -2px oklch(0 0 0 / 0.04)", dark: "0 1px 3px -2px oklch(0 0 0 / 0.06), 0 2px 5px -2px oklch(0 0 0 / 0.10)" },
+  "--openui-shadow-m": { light: "0 4px 6px -2px oklch(0 0 0 / 0.025), 0 2px 2px -2px oklch(0 0 0 / 0.05)", dark: "0 4px 6px -2px oklch(0 0 0 / 0.08), 0 2px 2px -2px oklch(0 0 0 / 0.12)" },
+  "--openui-shadow-l": { light: "0 4px 4px -2px oklch(0 0 0 / 0.05), 0 4px 8px -2px oklch(0 0 0 / 0.04)", dark: "0 4px 4px -2px oklch(0 0 0 / 0.12), 0 4px 8px -2px oklch(0 0 0 / 0.10)" },
+  "--openui-shadow-xl": { light: "0 8px 16px -4px oklch(0 0 0 / 0.08), 0 16px 32px -6px oklch(0 0 0 / 0.12)", dark: "0 8px 16px -4px oklch(0 0 0 / 0.16), 0 16px 32px -6px oklch(0 0 0 / 0.20)" },
+  "--openui-shadow-2xl": { light: "0 12px 24px -6px oklch(0 0 0 / 0.12), 0 24px 48px -8px oklch(0 0 0 / 0.16)", dark: "0 12px 24px -6px oklch(0 0 0 / 0.20), 0 24px 48px -8px oklch(0 0 0 / 0.24)" },
+  "--openui-shadow-3xl": { light: "0 16px 32px -8px oklch(0 0 0 / 0.16), 0 32px 64px -12px oklch(0 0 0 / 0.22)", dark: "0 16px 32px -8px oklch(0 0 0 / 0.24), 0 32px 64px -12px oklch(0 0 0 / 0.28)" },
+};
+
+export function themeToCssVars(theme = defaultTheme) {
+  const t = {
+    ...defaultTheme, ...theme,
+    color: { ...defaultTheme.color, ...(theme.color ?? {}) },
+    font: { ...defaultTheme.font, ...(theme.font ?? {}) },
+    size: { ...defaultTheme.size, ...(theme.size ?? {}) },
+    shimmer: { ...defaultTheme.shimmer, ...(theme.shimmer ?? {}) },
+    tilePad: { ...defaultTheme.tilePad, ...(theme.tilePad ?? {}) },
+  };
+  const vars = {};
+
+  for (const [k, v] of Object.entries(t.color)) vars[`--uir-color-${kebab(k)}`] = v;
+  for (const [k, v] of Object.entries(t.font)) vars[`--uir-font-${kebab(k)}`] = v;
+  for (const [k, v] of Object.entries(t.size)) vars[`--uir-size-${kebab(k)}`] = v;
+  for (const [k, v] of Object.entries(t.space)) vars[`--uir-space-${kebab(k)}`] = v;
+  for (const [k, v] of Object.entries(t.radius)) vars[`--uir-radius-${kebab(k)}`] = v;
+  for (const [k, v] of Object.entries(t.density)) vars[`--uir-density-${kebab(k)}`] = v;
+  vars["--uir-tile-pad-y"] = t.tilePad.y;
+  vars["--uir-tile-pad-x"] = t.tilePad.x;
+  vars["--uir-shimmer-from"] = t.shimmer.from;
+  vars["--uir-shimmer-to"] = t.shimmer.to;
+  vars["--uir-measure"] = t.measure;
+  vars["--uir-shadow"] = t.shadow ?? defaultTheme.shadow;
+  vars["--uir-motion-fold"] = motion.fold;
+  vars["--uir-motion-shimmer"] = motion.shimmer;
+  vars["--uir-motion-tick"] = motion.tick;
+  vars["--uir-motion-slide-in"] = motion.slideIn;
+  vars["--uir-motion-fade"] = motion.fade;
+  vars["--uir-motion-dot"] = motion.dot;
+  vars["--uir-motion-bar-in"] = motion.barIn;
+  vars["--uir-motion-count-up"] = motion.countUp;
+  vars["--uir-overlay-width"] = overlay.width;
+  vars["--uir-overlay-scrim"] = overlay.scrim;
+  vars["--uir-overlay-shadow"] = overlay.shadow;
+  (t.chart ?? defaultTheme.chart).forEach((c, i) => { vars[`--uir-chart-${i + 1}`] = c; });
+  const pieBase = t.scheme === "dark" ? darkTheme.pie : defaultTheme.pie;
+  (theme.pie ?? [t.color.brand, ...pieBase.slice(1)]).forEach((c, i) => { vars[`--uir-pie-${i + 1}`] = c; });
+
+  // Pin every scheme-dependent OpenUI variable to the theme the DOCUMENT chose, never the one the OS
+  // chose. Without this, a light OBL page on a dark-mode OS inherits OpenUI's dark palette from their
+  // media query and draws white on white. See `OPENUI_SCHEME_VARS`.
+  const scheme = t.scheme === "dark" ? "dark" : "light";
+  for (const [name, pair] of Object.entries(OPENUI_SCHEME_VARS)) vars[name] = pair[scheme];
+
+  // DARK: our own neutrals, layered over their dark values. None of these is a brand colour — the
+  // point is that their components sit on OUR ground, not that they wear our accent.
+  if (t.scheme === "dark") {
+    Object.assign(vars, {
+      "--openui-background": t.color.ground,
+      "--openui-foreground": t.color.sheet,
+      "--openui-popover-background": t.color.sheet,
+      "--openui-inverted-background": t.color.ink,
+      "--openui-sunk-light": "rgba(255,255,255,0.02)",
+      "--openui-sunk": "rgba(255,255,255,0.04)",
+      "--openui-sunk-deep": "rgba(255,255,255,0.08)",
+      "--openui-elevated-light": "rgba(255,255,255,0.04)",
+      "--openui-elevated": "rgba(255,255,255,0.08)",
+      "--openui-elevated-strong": "rgba(255,255,255,0.16)",
+      "--openui-highlight-subtle": "rgba(255,255,255,0.02)",
+      "--openui-highlight": "rgba(255,255,255,0.04)",
+      "--openui-highlight-strong": "rgba(255,255,255,0.08)",
+      "--openui-text-neutral-primary": t.color.ink,
+      "--openui-text-neutral-secondary": t.color.graphite,
+      "--openui-text-neutral-tertiary": t.color.faint,
+      "--openui-text-neutral-link": t.color.ink,
+      "--openui-text-brand": t.color.ink,
+      // `--openui-border-neutral` / `-strong` used to be here. OpenUI defines NEITHER and reads
+      // neither: two variables repairing nothing, for as long as the dark theme has existed. Their
+      // real border properties are these.
+      "--openui-border-default": t.color.rule,
+      "--openui-border-interactive": t.color.ruleStrong,
+    });
+  }
+
+  return vars;
+}
+
+/** Merge a partial tenant theme over the default. Tenants override colour and type, not structure. */
+export const makeTheme = (partial = {}) => {
+  const pieBase = partial.scheme === "dark" ? darkTheme.pie : defaultTheme.pie;
+  return {
+    ...defaultTheme,
+    ...partial,
+    color: { ...defaultTheme.color, ...(partial.color ?? {}) },
+    font: { ...defaultTheme.font, ...(partial.font ?? {}) },
+    size: { ...defaultTheme.size, ...(partial.size ?? {}) },
+    chart: partial.chart ?? defaultTheme.chart,
+    pie: partial.pie ?? [partial.color?.brand ?? pieBase[0], ...pieBase.slice(1)],
+  };
+};