@lumencast/runtime 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumencast/runtime",
-  "version": "0.6.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.6.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.6.0",
-    "@lumencast/server": "0.6.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/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

package/src/render/fill.tsx

@@ -12,6 +12,8 @@
 import type { CSSProperties, ReactElement } from "react";
 import { parseCssColor, warnRejectedColor } from "./css-color";
 import { emitDiagnostic } from "./diagnostics";
+import { gateSrc } from "./allowed-hosts";
+import { parseBlendMode } from "./blend-mode";
 
 export interface FillStop {
   offset: number;
@@ -19,13 +21,36 @@ export interface FillStop {
   opacity?: number;
 }
 
+/** LSML 1.2 §3.2 closed `objectFit` enum, re-validated at the RUNTIME (the
+ *  compiler is the other arm of the double-gate, Bastion T4). These are
+ *  exactly the legal CSS `object-fit` / `background-size`-mappable values ;
+ *  anything else is omitted + diagnosed, never passed through to inline CSS.
+ *  Kept local to the runtime — the runtime must not import from the
+ *  compiler (the dependency edge points the other way). */
+const OBJECT_FITS = new Set(["cover", "contain", "fill", "none", "scale-down"]);
+
+export type ObjectFit = "cover" | "contain" | "fill" | "none" | "scale-down";
+
+/** Validate an `objectFit` against the closed enum at render. Returns the
+ *  value or `undefined` (caller falls back to the default + diagnoses).
+ *  Never passthrough. */
+export function parseObjectFitRuntime(value: unknown): ObjectFit | undefined {
+  return typeof value === "string" && OBJECT_FITS.has(value) ? (value as ObjectFit) : undefined;
+}
+
+// LSML 1.2 §3.2 (#L) — optional per-fill-layer blend mode. Re-validated at
+// the RUNTIME against the closed enum (`parseBlendMode` from blend-mode.ts,
+// the runtime arm of the T4 double-gate ; the runtime never imports the
+// compiler). Out-of-enum → omitted, never reaches inline CSS. Independent of
+// the node-level blend (#D, applied on the wrapper). Absent = `normal`.
 export type Fill =
-  | { kind: "solid"; color: string; opacity?: number }
+  | { kind: "solid"; color: string; opacity?: number; blendMode?: string }
   | {
       kind: "linear-gradient";
       angle_deg?: number;
       stops: FillStop[];
       opacity?: number;
+      blendMode?: string;
     }
   | {
       kind: "radial-gradient";
@@ -33,6 +58,18 @@ export type Fill =
       radius?: number;
       stops: FillStop[];
       opacity?: number;
+      blendMode?: string;
+    }
+  | {
+      // LSML 1.2 §3.2 — first-class image-fill. `src` is untrusted and is
+      // host/scheme-gated by `gateImageFills` BEFORE this fill is ever
+      // rendered (Bastion T1/T2). `objectFit` is the runtime-revalidated
+      // closed-enum value (T4).
+      kind: "image";
+      src: string;
+      objectFit?: ObjectFit;
+      opacity?: number;
+      blendMode?: string;
     };
 
 let gradientIdSeq = 0;
@@ -46,27 +83,68 @@ export interface FillRenderResult {
   defs: ReactElement[];
   /** Reference to use as the `fill` attribute on the shape. */
   ref: string;
+  /** #L — the per-fill-layer `mix-blend-mode` keyword, re-validated against
+   *  the closed enum at the runtime (T4) ; `undefined` when absent or
+   *  out-of-enum (caller omits — never reaches the style). Applied on the
+   *  fill layer element, independent of the node-level blend (#D). */
+  mixBlendMode?: string;
 }
 
 /** Compile a Fill into an SVG `<defs>` entry + a `fill="url(#…)"` ref.
  * Solid fills produce no defs and return the colour directly. */
 export function renderFill(fill: Fill): FillRenderResult {
+  // #L — re-validate the per-fill blend mode once (runtime T4 arm). An absent
+  // or out-of-enum value yields `undefined` → the layer renders `normal`.
+  const mixBlendMode = parseBlendMode(fill.blendMode);
   if (fill.kind === "solid") {
-    // Solid fill — no defs needed, just hand the colour to fill.
-    // SVG fill-opacity composes with element opacity multiplicatively
-    // so we apply both consistently.
-    return { defs: [], ref: fill.color };
+    // Solid fill — no defs needed, just hand the colour to fill. A solid fill
+    // carries its OWN opacity (Figma per-paint alpha, e.g. the bg-texture tiles
+    // at 6% white) ; fold it into the colour so the SVG path actually renders
+    // at that alpha instead of full-strength (the tiles came out 16× too bright
+    // pre-mask, near-black post-mask).
+    const ref = fill.opacity !== undefined ? cssWithOpacity(fill.color, fill.opacity) : fill.color;
+    return { defs: [], ref, mixBlendMode };
+  }
+  if (fill.kind === "image") {
+    // LSML 1.2 §3.2 — image-fill on a shape. Rendered as an SVG <pattern>
+    // holding a single <image> that fills the object bounding box ;
+    // `preserveAspectRatio` reproduces the closed-enum `objectFit`. `src`
+    // is pre-gated (T1/T2) by `gateImageFills`, so it is safe to place on
+    // the SVG <image href>. No bundle-derived markup is interpolated — only
+    // the URL string and closed-enum-derived attribute values.
+    const imgId = nextGradientId();
+    const par = objectFitToPreserveAspectRatio(fill.objectFit);
+    const defs = [
+      <pattern key={imgId} id={imgId} patternContentUnits="objectBoundingBox" width="1" height="1">
+        <image href={fill.src} width="1" height="1" preserveAspectRatio={par} />
+      </pattern>,
+    ];
+    return { defs, ref: `url(#${imgId})`, mixBlendMode };
   }
   const id = nextGradientId();
   if (fill.kind === "linear-gradient") {
-    // angle_deg : 0 = bottom-to-top per §4.12 (matches CSS `linear-gradient`)
-    const angle = fill.angle_deg ?? 0;
-    // Translate angle (degrees from up) to SVG x1/y1/x2/y2 in user space.
-    const rad = ((angle - 90) * Math.PI) / 180; // 0° → x1=0,y1=1 (bottom-up)
-    const x1 = 0.5 - 0.5 * Math.cos(rad);
-    const y1 = 0.5 - 0.5 * Math.sin(rad);
-    const x2 = 0.5 + 0.5 * Math.cos(rad);
-    const y2 = 0.5 + 0.5 * Math.sin(rad);
+    let x1: number, y1: number, x2: number, y2: number;
+    // Honour the Figma `gradientTransform` : the gradient axis (offset 0 → 1) is
+    // column 0 = (a, b) of the matrix, in the SVG's y-down space. `angle_deg`
+    // alone ignored it and mis-oriented the picto/caramel gradients (too red).
+    const t = (fill as { transform?: number[] }).transform;
+    if (Array.isArray(t) && t.length === 6 && Number.isFinite(t[0]) && Number.isFinite(t[1])) {
+      const len = Math.hypot(t[0], t[1]) || 1;
+      const an = t[0] / len;
+      const bn = t[1] / len;
+      x1 = 0.5 - 0.5 * an;
+      y1 = 0.5 - 0.5 * bn;
+      x2 = 0.5 + 0.5 * an;
+      y2 = 0.5 + 0.5 * bn;
+    } else {
+      // angle_deg : 0 = bottom-to-top per §4.12.
+      const angle = fill.angle_deg ?? 0;
+      const rad = ((angle - 90) * Math.PI) / 180; // 0° → x1=0,y1=1 (bottom-up)
+      x1 = 0.5 - 0.5 * Math.cos(rad);
+      y1 = 0.5 - 0.5 * Math.sin(rad);
+      x2 = 0.5 + 0.5 * Math.cos(rad);
+      y2 = 0.5 + 0.5 * Math.sin(rad);
+    }
     const defs = [
       <linearGradient
         key={id}
@@ -86,7 +164,7 @@ export function renderFill(fill: Fill): FillRenderResult {
         ))}
       </linearGradient>,
     ];
-    return { defs, ref: `url(#${id})` };
+    return { defs, ref: `url(#${id})`, mixBlendMode };
   }
   // radial-gradient
   const cx = fill.center?.x ?? 0.5;
@@ -104,21 +182,108 @@ export function renderFill(fill: Fill): FillRenderResult {
       ))}
     </radialGradient>,
   ];
-  return { defs, ref: `url(#${id})` };
+  return { defs, ref: `url(#${id})`, mixBlendMode };
+}
+
+/** Map a closed-enum `objectFit` to the CSS `background-size` keyword that
+ *  reproduces the same fit for a `background-image`. `fill`/`none`/`scale-
+ *  down` have no exact 1:1 `background-size` keyword — we approximate with
+ *  the nearest safe keyword (all from the closed enum, never free input). */
+function objectFitToBackgroundSize(fit: ObjectFit | undefined): string {
+  switch (fit) {
+    case "contain":
+    case "scale-down":
+      return "contain";
+    case "none":
+      return "auto";
+    case "fill":
+      return "100% 100%";
+    case "cover":
+    default:
+      return "cover";
+  }
 }
 
-/** Compile an array of Fill into a CSS `background-image` value usable
- * on a `<div>` (frame backgrounds — non-SVG context). Returns the CSS
- * string + opacity. Stops use percentages in CSS gradient syntax. */
+/** Map a closed-enum `objectFit` to the SVG `<image preserveAspectRatio>`
+ *  value that reproduces the same fit inside a pattern tile. Every returned
+ *  value is a fixed literal (closed enum → fixed mapping) — never free
+ *  input reaching an SVG attribute. */
+function objectFitToPreserveAspectRatio(fit: ObjectFit | undefined): string {
+  switch (fit) {
+    case "contain":
+    case "scale-down":
+      return "xMidYMid meet";
+    case "fill":
+      return "none";
+    case "none":
+      return "xMidYMid meet";
+    case "cover":
+    default:
+      return "xMidYMid slice";
+  }
+}
+
+/** Compile an array of Fill into background CSS usable on a `<div>` (frame
+ * backgrounds — non-SVG context). Returns `backgroundImage` plus, when an
+ * image-fill is present, the matching `backgroundSize`/`backgroundPosition`/
+ * `backgroundRepeat`. Stops use percentages in CSS gradient syntax.
+ *
+ * Image-fill `src` MUST already be host/scheme-gated (`gateImageFills`) —
+ * `backgroundsToCss` assumes the URL is trusted at this point and only
+ * CSS-escapes it for safe interpolation into `url("…")`. */
 export function backgroundsToCss(fills: Fill[], nodeId?: string): CSSProperties {
   // Per §4.12, fills[0] renders on top — CSS background-image stacks
   // first → top-most. Match by passing in the same order.
-  const layers = fills.map((f) => fillToCss(f, nodeId)).filter(Boolean) as string[];
+  // #L — keep each layer's validated blend keyword aligned with its CSS
+  // layer (a rejected colour drops the layer → drop its blend too), so
+  // `background-blend-mode` stays positionally correct.
+  const kept: Fill[] = [];
+  const layers: string[] = [];
+  for (const f of fills) {
+    const css = fillToCss(f, nodeId);
+    if (css) {
+      layers.push(css);
+      kept.push(f);
+    }
+  }
   if (layers.length === 0) return {};
-  return { backgroundImage: layers.join(", ") };
+  const css: CSSProperties = { backgroundImage: layers.join(", ") };
+  // #L — per-fill-layer blend on a frame background uses CSS
+  // `background-blend-mode` (one keyword per layer, same order). Each value is
+  // re-validated against the closed enum (runtime T4 arm) ; an absent/rejected
+  // value falls back to `normal`. Emitted only when at least one layer carries
+  // a non-`normal` blend, to keep pre-#L output byte-identical (rétro-compat).
+  const blends = kept.map((f) => parseBlendMode(f.blendMode) ?? "normal");
+  if (blends.some((b) => b !== "normal")) {
+    css.backgroundBlendMode = blends.join(", ");
+  }
+  // When any layer is an image-fill, drive its sizing from the (already
+  // validated) objectFit. A single image-fill is the common cover case ;
+  // for the first image-fill we set the background sizing for the whole box.
+  const firstImage = fills.find((f) => f.kind === "image") as
+    | Extract<Fill, { kind: "image" }>
+    | undefined;
+  if (firstImage) {
+    css.backgroundSize = objectFitToBackgroundSize(firstImage.objectFit);
+    css.backgroundPosition = "center";
+    css.backgroundRepeat = "no-repeat";
+  }
+  return css;
+}
+
+/** CSS-escape a (already host-gated) URL for safe interpolation into a
+ *  `url("…")` token — escape backslash and the double-quote that would
+ *  otherwise break out of the quoted string. */
+function cssUrl(src: string): string {
+  return `url("${src.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}")`;
 }
 
 function fillToCss(fill: Fill, nodeId?: string): string | null {
+  if (fill.kind === "image") {
+    // `src` is pre-gated (T1/T2) by `gateImageFills` ; only escape it for
+    // the CSS string context here.
+    return cssUrl(fill.src);
+  }
   // RC#11 — every colour interpolated into an inline CSS string MUST
   // pass the strict parser first (fills/stops arrive from untrusted
   // bundles AND live LSDP deltas). A rejected colour drops the whole
@@ -129,8 +294,12 @@ function fillToCss(fill: Fill, nodeId?: string): string | null {
       warnRejectedColor("fill.color", nodeId);
       return null;
     }
+    // A solid fill carries its OWN opacity (Figma layer-fill alpha, e.g. a 14%
+    // white pill) — apply it like a gradient stop's, else the layer renders
+    // fully opaque and hides whatever it overlays.
+    const c = fill.opacity !== undefined ? cssWithOpacity(color, fill.opacity) : color;
     // Wrap solid in linear-gradient so it can stack with other layers.
-    return `linear-gradient(${color}, ${color})`;
+    return `linear-gradient(${c}, ${c})`;
   }
   const safeStops: string[] = [];
   for (const s of fill.stops) {
@@ -144,7 +313,17 @@ function fillToCss(fill: Fill, nodeId?: string): string | null {
   }
   const stops = safeStops.join(", ");
   if (fill.kind === "linear-gradient") {
-    const angle = fill.angle_deg ?? 0;
+    let angle = fill.angle_deg ?? 0;
+    // Honour the Figma `gradientTransform` when present : the gradient's main
+    // axis (offset 0 → 1) is column 0 = (a, b) of the 2×3 matrix. CSS `Ndeg`
+    // measures clockwise from "up" and screen-y points down, so that direction
+    // maps to `atan2(a, -b)`. `angle_deg` alone ignored the matrix and rendered
+    // the Cover's warm base as a 270° (horizontal) wash instead of the real 180°
+    // (warm at top) — leaving the top-right black under the Ruby20 hard-light.
+    const t = (fill as { transform?: number[] }).transform;
+    if (Array.isArray(t) && t.length === 6 && Number.isFinite(t[0]) && Number.isFinite(t[1])) {
+      angle = ((Math.atan2(t[0], -t[1]) * 180) / Math.PI + 360) % 360;
+    }
     return `linear-gradient(${angle}deg, ${stops})`;
   }
   // radial-gradient
@@ -180,6 +359,13 @@ function cssWithOpacity(color: string, opacity: number): string {
 export function sanitizeFills(fills: Fill[], field: string, nodeId?: string): Fill[] {
   const out: Fill[] = [];
   for (const fill of fills) {
+    // Image-fills carry no colour — they are colour-clean by construction.
+    // Their `src` is gated separately (`gateImageFills`, T1/T2) ; pass them
+    // through here unchanged so `sanitizeFills` only owns colour validation.
+    if (fill.kind === "image") {
+      out.push(fill);
+      continue;
+    }
     if (fill.kind === "solid") {
       const color = parseCssColor(fill.color);
       if (color === null) {
@@ -224,11 +410,67 @@ export function parseFills(value: unknown, field?: string, nodeId?: string): Fil
       }
     }
   }
-  return value.filter(isFill) as Fill[];
+  // Image-fill `objectFit` is re-validated against the closed enum here
+  // (Bastion T4 runtime arm) : a hostile / unknown value is dropped with a
+  // diagnostic and the fill falls back to the default fit — never passed
+  // through to inline CSS. `src` is NOT gated here (it needs the host
+  // allowlist) — `gateImageFills` does that downstream, before render.
+  return value.filter(isFill).map((v) => {
+    let fill = v as Fill;
+    // #L — re-validate a per-fill `blendMode` against the closed enum (runtime
+    // T4 arm). An out-of-enum value is diagnosed + stripped (the layer falls
+    // back to `normal`), never passed through to inline CSS. Applies to every
+    // fill kind.
+    if (fill.blendMode !== undefined && parseBlendMode(fill.blendMode) === undefined) {
+      emitDiagnostic(
+        nodeId,
+        field !== undefined ? `${field}.blendMode` : "fill.blendMode",
+        "is not a recognised mix-blend-mode ; falling back to normal (ADR 002 §3.2)",
+      );
+      const { blendMode: _drop, ...rest } = fill;
+      fill = rest;
+    }
+    if (fill.kind !== "image") return fill;
+    if (fill.objectFit === undefined) return fill;
+    const fit = parseObjectFitRuntime(fill.objectFit);
+    if (fit === undefined) {
+      emitDiagnostic(
+        nodeId,
+        field !== undefined ? `${field}.objectFit` : "fill.objectFit",
+        "is not a recognised object-fit ; falling back to default (ADR 002 §3.2)",
+      );
+      const { objectFit: _drop, ...rest } = fill;
+      return rest;
+    }
+    return { ...fill, objectFit: fit };
+  });
 }
 
 function isFill(v: unknown): v is Fill {
   if (typeof v !== "object" || v === null) return false;
   const k = (v as { kind?: unknown }).kind;
-  return k === "solid" || k === "linear-gradient" || k === "radial-gradient";
+  if (k === "solid" || k === "linear-gradient" || k === "radial-gradient") return true;
+  // An image-fill must carry a string `src` to be structurally valid ; a
+  // malformed image entry is dropped like any other unrenderable fill.
+  return k === "image" && typeof (v as { src?: unknown }).src === "string";
+}
+
+/**
+ * Drop every image-fill whose `src` fails the host/scheme allowlist
+ * (Bastion T1/T2), BEFORE any image-fill reaches the DOM. A rejected
+ * image-fill is omitted entirely (never a passthrough URL) with an
+ * R9-clean diagnostic emitted by `gateSrc`. Non-image fills pass through
+ * untouched. Call this once, after `parseFills`, with the active
+ * `allowedHosts` from `useAllowedHosts()`.
+ */
+export function gateImageFills(
+  fills: Fill[],
+  allowedHosts: readonly string[] | undefined,
+  field: string,
+  nodeId?: string,
+): Fill[] {
+  return fills.filter((fill) => {
+    if (fill.kind !== "image") return true;
+    return gateSrc(fill.src, allowedHosts, `${field}.src`, nodeId) !== undefined;
+  });
 }