@lumencast/runtime 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumencast/runtime",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Browser runtime for Lumencast — mount(), LSDP/1 transport, leaf-grain store, LSML render, animations, overlays.",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,7 +36,7 @@
     "framer-motion": "^12.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@lumencast/protocol": "0.6.0"
+    "@lumencast/protocol": "0.8.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
@@ -50,8 +50,8 @@
     "vite-plugin-dts": "^4.5.0",
     "vitest": "^4.1.5",
     "ws": "^8.18.0",
-    "@lumencast/dev-server": "0.6.0",
-    "@lumencast/server": "0.6.0"
+    "@lumencast/dev-server": "0.8.0",
+    "@lumencast/server": "0.8.0"
   },
   "scripts": {
     "dev": "vite",
@@ -60,6 +60,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
-    "check:bundle": "node scripts/check-bundle-size.mjs"
+    "check:bundle": "node scripts/check-bundle-size.mjs",
+    "check:no-fetch": "node scripts/check-no-fetch.mjs"
   }
 }

package/src/index.ts

@@ -46,3 +46,27 @@ export {
   isAuthoringProfile,
   validateBundleProfiles,
 } from "./render/bundle.js";
+
+// Headless render (ADR 003) — render an already-compiled RenderBundle into a
+// live DOM node, no WS, ready when layout + fonts settle. Hosts (Solar headless
+// entry, ZabCanvas render worker, the zero-loss harness) screenshot the target
+// once `ready` resolves. The runtime does DOM + readiness only — no fetch, no
+// screenshot. Dynamically pulls BroadcastMode so it adds no eager weight to the
+// `mount`/broadcast path (RC6).
+export { renderBundleHeadless } from "./render/headless.js";
+export type { HeadlessRenderOptions, HeadlessRenderHandle } from "./render/headless.js";
+
+// Asset / font resolution helpers for headless hosts (ADR 003 §3.2). No-fetch:
+// they only rewrite a bundle's `src`s against a caller table and load fonts
+// from caller-supplied `data:` URIs. The host-allow gate stays the sole
+// authority. (`FontFace` is the public type name per ADR 003 RC5; it is the
+// spec object — distinct from the DOM `FontFace` constructor.)
+export {
+  resolveSrc,
+  rewriteLayoutSrcs,
+  rewriteDefaultsSrcs,
+  injectFonts,
+  type AssetTable,
+  type FontFaceSpec,
+  type FontFaceSpec as FontFace,
+} from "./render/asset-resolve.js";

package/src/modes/broadcast.tsx

@@ -1,8 +1,19 @@
+import { useMemo } from "react";
 import { Tree } from "../render/tree";
+import { AllowedHostsProvider, readAllowedHosts } from "../render/allowed-hosts";
+import { ShapeIndexProvider, buildShapeIndex } from "../render/shape-index";
 import { useLumencastRuntime } from "../overlay/runtime-context";
 
 /** Broadcast mode : pure scene render, no UI chrome. */
 export function BroadcastMode() {
   const { store, bundle } = useLumencastRuntime();
-  return <Tree node={bundle.root} store={store} />;
+  // ADR 002 A2.1 (#K) — build the `id → shape` index once per bundle.
+  const shapeIndex = useMemo(() => buildShapeIndex(bundle.root), [bundle.root]);
+  return (
+    <AllowedHostsProvider hosts={readAllowedHosts(bundle)}>
+      <ShapeIndexProvider index={shapeIndex}>
+        <Tree node={bundle.root} store={store} />
+      </ShapeIndexProvider>
+    </AllowedHostsProvider>
+  );
 }

package/src/modes/control.tsx

@@ -1,4 +1,7 @@
+import { useMemo } from "react";
 import { Tree } from "../render/tree";
+import { AllowedHostsProvider, readAllowedHosts } from "../render/allowed-hosts";
+import { ShapeIndexProvider, buildShapeIndex } from "../render/shape-index";
 import { ControlPanel } from "../overlay/control";
 import { StatusPill } from "../overlay/status-pill";
 import { useLumencastRuntime } from "../overlay/runtime-context";
@@ -7,9 +10,15 @@ import { useLumencastRuntime } from "../overlay/runtime-context";
  *  panel from operator_inputs). */
 export function ControlMode() {
   const { store, bundle } = useLumencastRuntime();
+  // ADR 002 A2.1 (#K) — build the `id → shape` index once per bundle.
+  const shapeIndex = useMemo(() => buildShapeIndex(bundle.root), [bundle.root]);
   return (
     <>
-      <Tree node={bundle.root} store={store} />
+      <AllowedHostsProvider hosts={readAllowedHosts(bundle)}>
+        <ShapeIndexProvider index={shapeIndex}>
+          <Tree node={bundle.root} store={store} />
+        </ShapeIndexProvider>
+      </AllowedHostsProvider>
       <StatusPill />
       <ControlPanel />
     </>

package/src/modes/test.tsx

@@ -1,4 +1,5 @@
 import { Tree } from "../render/tree";
+import { AllowedHostsProvider, readAllowedHosts } from "../render/allowed-hosts";
 import { ControlPanel } from "../overlay/control";
 import { TestPanel } from "../overlay/test";
 import { StatusPill } from "../overlay/status-pill";
@@ -10,7 +11,9 @@ export function TestMode() {
   const { store, bundle } = useLumencastRuntime();
   return (
     <>
-      <Tree node={bundle.root} store={store} />
+      <AllowedHostsProvider hosts={readAllowedHosts(bundle)}>
+        <Tree node={bundle.root} store={store} />
+      </AllowedHostsProvider>
       <StatusPill />
       <ControlPanel />
       <TestPanel />

package/src/render/allowed-hosts.tsx

@@ -0,0 +1,100 @@
+// Render-side host-allowlist context (LSML 1.2, ADR 002 #E + #F ; Bastion T1/T2).
+//
+// CANONICAL host-gate module for the runtime. There is exactly ONE
+// `AllowedHostsProvider` and ONE allowlist context for the whole render
+// tree. The bundle's `assets.allowedHosts` rides this context from the
+// render root down to every consumer that places an untrusted asset URL
+// into the DOM :
+//
+//   - image-fill `src` on frame / shape backgrounds (#F, via `gateImageFills`
+//     / `gateSrc` in `fill.tsx`),
+//   - the `<img src>` of the `image` primitive (#F — closes the latent 1.1
+//     hole where `image.tsx` placed `src` with no host check at all),
+//   - a `mask.source`-image `href` (#E, via `checkHostAllowed` in
+//     `mask.tsx`, which reads the allowlist off this same context through
+//     `tree.tsx`).
+//
+// The underlying decision is ALWAYS delegated to `@lumencast/protocol`'s
+// `checkHostAllowed` / `isHostAllowed` (the #C foundation, single source of
+// truth for host + scheme matching). This module never re-implements that
+// logic ; it only threads the allowlist and adapts it for each call-site.
+//
+// Deny-by-default : a consumer rendered outside any provider, or one whose
+// bundle declares no `allowedHosts`, sees `undefined` — which
+// `checkHostAllowed` treats as "no allowlist → reject every remote host".
+// There is no path by which a missing provider silently re-opens the gate.
+//
+// The context value is a read-only, mount-stable `string[] | undefined`
+// (the allowlist is part of the content-addressed bundle), so a plain React
+// context is the right tool.
+
+import { createContext, useContext, type ReactNode } from "react";
+import { checkHostAllowed } from "@lumencast/protocol";
+import { emitDiagnostic } from "./diagnostics";
+
+const AllowedHostsCtx = createContext<readonly string[] | undefined>(undefined);
+
+/**
+ * Provide the bundle's host allowlist to the render subtree. Mounted ONCE at
+ * the render root by each mode (broadcast / control / test), wrapping
+ * `<Tree>`. The value should come from {@link readAllowedHosts} so the
+ * legacy `Asset[]` and the LSML 1.2 object `assets` shapes are both handled
+ * and non-string entries are dropped.
+ *
+ * Prop name is `hosts` (the canonical render-side spelling, #F).
+ */
+export function AllowedHostsProvider({
+  hosts,
+  children,
+}: {
+  hosts: readonly string[] | undefined;
+  children: ReactNode;
+}) {
+  return <AllowedHostsCtx.Provider value={hosts}>{children}</AllowedHostsCtx.Provider>;
+}
+
+/** Read the active host allowlist. `undefined` when no provider is mounted —
+ *  which `checkHostAllowed` treats as deny-by-default (never a passthrough). */
+export function useAllowedHosts(): readonly string[] | undefined {
+  return useContext(AllowedHostsCtx);
+}
+
+/** Read `assets.allowedHosts` defensively off a render bundle, for the mode
+ *  that provides the context. The LSML 1.2 compiler forwards `assets` in the
+ *  object form `{ allowedHosts?: string[] }` (see `RenderBundle.assets`) ;
+ *  a legacy bundle may still carry the old `Asset[]` form. Either way we
+ *  extract a `string[]` of hostnames, or `undefined` (deny-by-default). A
+ *  non-string entry is dropped — it can never match `new URL().hostname`. */
+export function readAllowedHosts(bundle: { assets?: unknown }): readonly string[] | undefined {
+  const assets = bundle.assets as { allowedHosts?: unknown } | undefined;
+  const list = assets?.allowedHosts;
+  if (!Array.isArray(list)) return undefined;
+  const hosts = list.filter((h): h is string => typeof h === "string");
+  return hosts.length > 0 ? hosts : undefined;
+}
+
+/**
+ * Gate an asset `src` against the host + scheme allowlist BEFORE it reaches
+ * the DOM (Bastion T1/T2). Returns the `src` unchanged when allowed, or
+ * `undefined` when rejected — in which case the caller MUST omit the asset
+ * (never passthrough). On rejection an R9-clean diagnostic is emitted : it
+ * carries only `{ nodeId, field, reason }`, never the URL itself.
+ *
+ * The decision is delegated to `checkHostAllowed` and is deny-by-default :
+ * an absent / empty `allowedHosts` rejects every remote host.
+ * `undefined`/non-string/empty `src` resolves to `undefined` (absent asset)
+ * WITHOUT a diagnostic — that is a primitive with no source, not a rejected
+ * one.
+ */
+export function gateSrc(
+  src: unknown,
+  allowedHosts: readonly string[] | undefined,
+  field: string,
+  nodeId?: string,
+): string | undefined {
+  if (typeof src !== "string" || src.length === 0) return undefined;
+  const decision = checkHostAllowed(src, allowedHosts);
+  if (decision.allowed) return src;
+  emitDiagnostic(nodeId, field, decision.reason ?? "asset host/scheme rejected");
+  return undefined;
+}

package/src/render/asset-resolve.ts

@@ -0,0 +1,97 @@
+// Public asset + font resolution helpers for headless / host render (ADR 003 §3.2).
+//
+// These utilities let a HOST (Solar headless entry, a ZabCanvas render worker,
+// the zero-loss harness) resolve a bundle's content-addressed asset references
+// to concrete `data:` URIs and inject brand `@font-face`s BEFORE the first
+// frame — exactly as the zero-loss harness has always done (ADR 002 #J). They
+// are promoted here verbatim so every host resolves identically and exercises
+// the SAME host-allow gate the runtime applies internally.
+//
+// ── No-fetch contract (ADR 003 §3.2, D3, Bastion R2) ────────────────────────
+// NONE of these helpers performs a network fetch. They only rewrite a bundle's
+// `src` values against a caller-supplied table (`resolveSrc` /
+// `rewriteLayoutSrcs` / `rewriteDefaultsSrcs`) and load `@font-face`s from
+// caller-supplied `data:`/same-document URLs (`injectFonts`). The runtime never
+// reaches the network; the host owns where bytes come from. Both the input
+// table values and the font `src`s are expected to be `data:` (or otherwise
+// already host-allowed) URIs — substituting one already-admitted scheme for
+// another, so the deny-by-default `allowedHosts` gate stays the sole authority.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A table mapping a bundle `src` reference to its resolved `data:` URI.
+ *  Keys may be either the full `assets/<hash>.ext` path or a bare `<hash>`. */
+export type AssetTable = Readonly<Record<string, string>>;
+
+/** Resolve a single `src` value against a table. Non-string or unmatched values
+ *  pass through unchanged. Matches both `assets/<hash>.ext` and bare `<hash>`. */
+export function resolveSrc(src: unknown, table: AssetTable): unknown {
+  if (typeof src !== "string") return src;
+  if (table[src]) return table[src];
+  const m = /^assets\/([A-Za-z0-9]+)\.[A-Za-z0-9]+$/.exec(src);
+  if (m && m[1] !== undefined && table[m[1]]) return table[m[1]];
+  return src;
+}
+
+/** Deep-rewrite every `src` (image-fill, mask source) in a layout subtree,
+ *  in place, against the supplied asset table. */
+export function rewriteLayoutSrcs(node: unknown, table: AssetTable): void {
+  if (node === null || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const n of node) rewriteLayoutSrcs(n, table);
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  if ("src" in obj) obj["src"] = resolveSrc(obj["src"], table);
+  for (const v of Object.values(obj)) {
+    if (v && typeof v === "object") rewriteLayoutSrcs(v, table);
+  }
+}
+
+/** Rewrite the `__lit.image.*` defaults (image-primitive `bind.src` targets)
+ *  against the asset table, returning a new defaults object. */
+export function rewriteDefaultsSrcs(
+  defaults: Record<string, unknown>,
+  table: AssetTable,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...defaults };
+  for (const [k, v] of Object.entries(out)) {
+    if (k.startsWith("__lit.image.")) out[k] = resolveSrc(v, table);
+  }
+  return out;
+}
+
+/** A brand `@font-face` to inject before render. `src` is a `data:` URI (or any
+ *  same-document URL) so no network/host-allow surface is involved. */
+export interface FontFaceSpec {
+  family: string;
+  weight: number | string;
+  style?: string;
+  /** `url(data:font/woff2;base64,…)` content (the value inside `src:`). */
+  src: string;
+}
+
+/** Inject `@font-face` rules and block until the faces are loaded, so the very
+ *  first painted frame already uses the brand glyphs (no fallback-font flash).
+ *  Returns the families that successfully loaded. Loads only from the supplied
+ *  `src` (expected `data:`); never fetches a remote host on its own behalf. */
+export async function injectFonts(faces: readonly FontFaceSpec[]): Promise<string[]> {
+  const loaded: string[] = [];
+  for (const f of faces) {
+    try {
+      const face = new FontFace(f.family, f.src, {
+        weight: String(f.weight),
+        style: f.style ?? "normal",
+      });
+      await face.load();
+      (document as Document & { fonts: FontFaceSet }).fonts.add(face);
+      loaded.push(f.family);
+    } catch {
+      // A font that fails to load is a documented gap, not a render-breaker:
+      // the fallback glyphs paint and the host can detect the missing family
+      // in the returned list. Never throw (would abort an otherwise-good
+      // render) and never log the value (R9) — the absent family name is in
+      // `f.family`, which the caller already holds.
+    }
+  }
+  return loaded;
+}

package/src/render/blend-mode.ts

@@ -0,0 +1,50 @@
+// Strict `mix-blend-mode` gate — the runtime half of the T4 double-gate
+// (Bastion conditions 1.2, ADR 002 §3.2 / #D).
+//
+// The compiler already validates `blendMode` against its closed enum
+// (`parseBlendMode`, @lumencast/compiler) before emitting the universal
+// prop. This module is the INDEPENDENT runtime gate : a bundle prop OR a
+// live LSDP delta value reaching the wrapper is re-validated here against
+// the same closed allowlist before it may touch an inline CSS style.
+// Anything outside the enum is omitted (never passthrough) — mirroring
+// the `css-color.ts` discipline (self-contained second gate, no untrusted
+// string ever interpolated into CSS).
+//
+// The allowlist is intentionally duplicated rather than imported from the
+// compiler : the runtime does not depend on @lumencast/compiler, and the
+// gate must hold even if a hand-rolled / tampered bundle bypasses the
+// compiler entirely. It is a fixed, finite set of CSS keywords (Figma
+// blend modes minus PASS_THROUGH) — the single source of truth for the
+// CSS value is this closed set.
+
+/** Closed `mix-blend-mode` allowlist (ADR 002 §3.2 — Figma minus
+ *  `PASS_THROUGH`). Mirrors the compiler's `BLEND_MODES`. */
+const BLEND_MODES: ReadonlySet<string> = new Set([
+  "normal",
+  "multiply",
+  "screen",
+  "overlay",
+  "darken",
+  "lighten",
+  "color-dodge",
+  "color-burn",
+  "hard-light",
+  "soft-light",
+  "difference",
+  "exclusion",
+  "hue",
+  "saturation",
+  "color",
+  "luminosity",
+  // Figma LINEAR_DODGE (add) — exact additive blend, gentler than color-dodge.
+  "plus-lighter",
+]);
+
+/**
+ * Re-validate a resolved `blendMode` against the closed enum. Returns the
+ * CSS `mix-blend-mode` keyword when recognised, else `undefined` (caller
+ * omits — the value never reaches the style). Never passthrough.
+ */
+export function parseBlendMode(value: unknown): string | undefined {
+  return typeof value === "string" && BLEND_MODES.has(value) ? value : undefined;
+}

package/src/render/bundle.ts

@@ -111,7 +111,12 @@ export interface RenderBundle {
   root: RenderNode;
   operator_inputs?: OperatorInput[];
   external_adapters?: ExternalAdapter[];
-  assets?: Asset[];
+  /** Bundle-level asset declarations. `allowedHosts` is the host
+   *  allowlist (LSML 1.2 §3.2, Bastion T1) every image / image-fill `src`
+   *  is gated against at render BEFORE reaching the DOM. Absent / empty =
+   *  deny every remote host (deny-by-default). Other keys (`fonts`,
+   *  `preload`) are forwarded opaquely by the compiler. */
+  assets?: { allowedHosts?: string[]; [key: string]: unknown };
   /** LSML 1.1 §17.3 — capability profiles required for correct rendering.
    * Each entry is an `x-<vendor>.<name>/<version>` string. The runtime
    * checks every behavioural entry against its supported list ; an