@lumencast/runtime 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumencast/runtime",
-  "version": "0.5.0",
+  "version": "0.7.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.5.0"
+    "@lumencast/protocol": "0.7.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.5.0",
-    "@lumencast/server": "0.5.0"
+    "@lumencast/dev-server": "0.7.0",
+    "@lumencast/server": "0.7.0"
   },
   "scripts": {
     "dev": "vite",

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/mount.ts

@@ -20,9 +20,14 @@ export function mount(options: MountOptions): LumencastHandle {
 
   const store = createStore();
   const baseUrl = deriveBaseUrl(options.serverUrl);
+  // The render-bundle endpoint is auth-gated like the LSDP/1 WS. Resolve the
+  // current session token per fetch (mirrors `setToken`) so each bundle GET
+  // carries `Authorization: Bearer <token>`. `ws` is assigned below; the
+  // closure runs only at fetch time, after assignment.
   const bundleFetcher = createBundleFetcher({
     baseUrl,
     ...(options.resolveBundleUrl !== undefined ? { resolveUrl: options.resolveBundleUrl } : {}),
+    getAuthToken: () => ws.resolveCurrentToken(),
   });
 
   const bundleSignal = signal<RenderBundle | null>(null);

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/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
@@ -251,6 +256,14 @@ export interface BundleFetcherOptions {
    *  Lets a gateway-prefixed server be addressed without changing the
    *  host-root default. */
   resolveUrl?: BundleUrlResolver;
+  /** Resolve the bearer token used to authenticate each bundle GET. The
+   *  render-bundle endpoint is auth-gated identically to the LSDP/1 WS
+   *  subscription, so the fetch carries the same session token as
+   *  `Authorization: Bearer <token>`. Resolved per request so a token swap
+   *  (`setToken`) takes effect on the next fetch ; a `LumencastTokenProvider`
+   *  is awaited. When omitted — or when it resolves to an empty/undefined
+   *  value — no `Authorization` header is sent (v0.5.0 behaviour). */
+  getAuthToken?: () => string | undefined | Promise<string | undefined>;
   fetchImpl?: typeof fetch;
 }
 
@@ -259,15 +272,27 @@ class FetcherImpl implements BundleFetcher {
   private readonly baseUrl: string;
   private readonly pathPrefix: string;
   private readonly resolveUrl: BundleUrlResolver | undefined;
+  private readonly getAuthToken: BundleFetcherOptions["getAuthToken"];
   private readonly fetchImpl: typeof fetch;
 
   constructor(opts: BundleFetcherOptions) {
     this.baseUrl = opts.baseUrl.replace(/\/$/, "");
     this.pathPrefix = (opts.pathPrefix ?? "/lsdp/v1/scenes").replace(/\/$/, "");
     this.resolveUrl = opts.resolveUrl;
+    this.getAuthToken = opts.getAuthToken;
     this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
   }
 
+  /** Build the request init carrying the bearer token, if any. Returns
+   *  `undefined` when no token is available — the fetch stays header-less,
+   *  preserving v0.5.0 behaviour. */
+  private async buildInit(): Promise<RequestInit | undefined> {
+    if (!this.getAuthToken) return undefined;
+    const token = await this.getAuthToken();
+    if (!token) return undefined;
+    return { headers: { Authorization: `Bearer ${token}` } };
+  }
+
   private buildUrl(sceneId: string, sceneVersion: string): string {
     if (this.resolveUrl) {
       return this.resolveUrl(sceneId, sceneVersion);
@@ -287,7 +312,8 @@ class FetcherImpl implements BundleFetcher {
     const cached = this.cache.get(sceneVersion);
     if (cached) return cached;
     const url = this.buildUrl(sceneId, sceneVersion);
-    const response = await this.fetchImpl(url);
+    const init = await this.buildInit();
+    const response = init ? await this.fetchImpl(url, init) : await this.fetchImpl(url);
     if (!response.ok) {
       throw new Error(`bundle fetch failed: ${response.status} ${response.statusText}`);
     }