@lumencast/runtime 0.4.0 → 0.5.0

package/src/render/diagnostics.ts

@@ -0,0 +1,75 @@
+// Anti-silent-drop diagnostics channel (ADR 001 §3.4 D4, issue #34).
+//
+// Every render-side diagnostic — rejected colour/filter/path/typography
+// value, unknown prop, unrendered spec'd field — flows through
+// `emitDiagnostic`. The diagnostic is an EVENT, not a console.log :
+// hosts subscribe via `MountOptions.onDiagnostic` (wired by `mount()`)
+// and receive a structured `{ nodeId, field, reason }`. When no handler
+// is registered, the runtime falls back to a DEV-only `console.warn`
+// so authors still see drops during development — and `broadcast`
+// builds stay silent on the console, per the CLAUDE.md "no logs in
+// broadcast" rule.
+//
+// ── Hygiene contract (Bastion R9, ADR 001 §5.1) ─────────────────────
+// A diagnostic NEVER carries the value of a leaf or a prop — only the
+// node id, the field name and a STATIC reason string. Leaf values can
+// hold sensitive on-air content ; they must not transit any diagnostic
+// channel. Callers pass field names and literal reasons exclusively.
+// The R9 sentinel test (r9-sentinel.test.tsx) enforces this end to end,
+// and statically checks that `console.warn` only exists in this module.
+// ─────────────────────────────────────────────────────────────────────
+
+/** Placeholder id for nodes that don't declare an `id`. */
+export const ANON_NODE_ID = "<anon>";
+
+export interface RenderDiagnostic {
+  /** `RenderNode.id` of the node the field belongs to (RC#7), or
+   *  `ANON_NODE_ID` when the node has none. */
+  nodeId: string;
+  /** Name of the field/prop concerned (e.g. `text.colour`,
+   *  `shape.paths.data`, `bindAnimate.opacity`). Never its value (R9). */
+  field: string;
+  /** Static reason — why the field was rejected or not rendered. */
+  reason: string;
+}
+
+export type DiagnosticHandler = (diagnostic: RenderDiagnostic) => void;
+
+const handlers = new Set<DiagnosticHandler>();
+
+/**
+ * Register a diagnostics handler (one per `mount()`, plus tests).
+ * Returns the unregister function. Multiple concurrent mounts each
+ * receive every diagnostic — node ids are bundle-scoped, so a host
+ * running several mounts should disambiguate on its side.
+ */
+export function addDiagnosticsHandler(handler: DiagnosticHandler): () => void {
+  handlers.add(handler);
+  return () => {
+    handlers.delete(handler);
+  };
+}
+
+/**
+ * Emit one anti-drop diagnostic. `field` and `reason` MUST be static
+ * strings / field names — never interpolate a prop or leaf value (R9).
+ */
+export function emitDiagnostic(nodeId: string | undefined, field: string, reason: string): void {
+  const diagnostic: RenderDiagnostic = { nodeId: nodeId ?? ANON_NODE_ID, field, reason };
+  if (handlers.size > 0) {
+    for (const handler of handlers) {
+      try {
+        handler(diagnostic);
+      } catch {
+        // A host handler that throws must never break the render path.
+      }
+    }
+    return;
+  }
+  // DEV-only console fallback — broadcast builds log nothing.
+  if (import.meta.env.DEV) {
+    console.warn(
+      `[lumencast] node "${diagnostic.nodeId}": field "${field}" ${reason} (value withheld per R9)`,
+    );
+  }
+}

package/src/render/fill.tsx

@@ -10,6 +10,8 @@
 // renders on top per §4.12).
 
 import type { CSSProperties, ReactElement } from "react";
+import { parseCssColor, warnRejectedColor } from "./css-color";
+import { emitDiagnostic } from "./diagnostics";
 
 export interface FillStop {
   offset: number;
@@ -108,25 +110,39 @@ export function renderFill(fill: Fill): FillRenderResult {
 /** 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. */
-export function backgroundsToCss(fills: Fill[]): CSSProperties {
+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(fillToCss).filter(Boolean) as string[];
+  const layers = fills.map((f) => fillToCss(f, nodeId)).filter(Boolean) as string[];
   if (layers.length === 0) return {};
   return { backgroundImage: layers.join(", ") };
 }
 
-function fillToCss(fill: Fill): string | null {
+function fillToCss(fill: Fill, nodeId?: string): string | null {
+  // 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
+  // layer : never passthrough, never a half-built gradient.
   if (fill.kind === "solid") {
+    const color = parseCssColor(fill.color);
+    if (color === null) {
+      warnRejectedColor("fill.color", nodeId);
+      return null;
+    }
     // Wrap solid in linear-gradient so it can stack with other layers.
-    return `linear-gradient(${fill.color}, ${fill.color})`;
+    return `linear-gradient(${color}, ${color})`;
+  }
+  const safeStops: string[] = [];
+  for (const s of fill.stops) {
+    const color = parseCssColor(s.color);
+    if (color === null) {
+      warnRejectedColor("fill.stops.color", nodeId);
+      return null;
+    }
+    const c = s.opacity !== undefined ? cssWithOpacity(color, s.opacity) : color;
+    safeStops.push(`${c} ${(s.offset * 100).toFixed(2)}%`);
   }
-  const stops = fill.stops
-    .map((s) => {
-      const c = s.opacity !== undefined ? cssWithOpacity(s.color, s.opacity) : s.color;
-      return `${c} ${(s.offset * 100).toFixed(2)}%`;
-    })
-    .join(", ");
+  const stops = safeStops.join(", ");
   if (fill.kind === "linear-gradient") {
     const angle = fill.angle_deg ?? 0;
     return `linear-gradient(${angle}deg, ${stops})`;
@@ -137,9 +153,13 @@ function fillToCss(fill: Fill): string | null {
   return `radial-gradient(circle at ${cx}% ${cy}%, ${stops})`;
 }
 
+/** Apply a stop opacity to an ALREADY-VALIDATED colour (callers must
+ * have run `parseCssColor` first — fillToCss is the single entry).
+ * For 6-digit hex we append the alpha byte ; every other accepted
+ * form goes through color-mix, which is safe because the interpolated
+ * string can only be a strict-grammar colour (RC#11 fix : this used
+ * to interpolate the raw, unparsed input). */
 function cssWithOpacity(color: string, opacity: number): string {
-  // Best-effort wrapper — for hex/rgb we can append alpha. For
-  // unrecognised forms, fall back to color-mix.
   const hex = color.match(/^#([0-9a-f]{6})$/i);
   if (hex) {
     const a = Math.round(opacity * 255)
@@ -150,9 +170,60 @@ function cssWithOpacity(color: string, opacity: number): string {
   return `color-mix(in srgb, ${color} ${opacity * 100}%, transparent)`;
 }
 
-/** Coerce loose JSON into a Fill array. Returns [] for non-arrays. */
-export function parseFills(value: unknown): Fill[] {
+/** Validate every colour carried by a Fill array through the strict
+ * parser (RC#11 — issue #30 contractual comment : SVG `fill`/`stroke`
+ * attributes and `<stop stop-color>` are injection sites too, since
+ * fills arrive from untrusted bundles AND live LSDP deltas). A fill
+ * whose solid colour — or ANY gradient stop colour — is rejected drops
+ * the whole layer with a diagnostic : never passthrough, never a
+ * half-built gradient. Returned fills carry canonicalised colours. */
+export function sanitizeFills(fills: Fill[], field: string, nodeId?: string): Fill[] {
+  const out: Fill[] = [];
+  for (const fill of fills) {
+    if (fill.kind === "solid") {
+      const color = parseCssColor(fill.color);
+      if (color === null) {
+        warnRejectedColor(`${field}.color`, nodeId);
+        continue;
+      }
+      out.push({ ...fill, color });
+      continue;
+    }
+    const stops: FillStop[] = [];
+    let rejected = false;
+    for (const s of fill.stops ?? []) {
+      const color = parseCssColor(s.color);
+      if (color === null) {
+        warnRejectedColor(`${field}.stops.color`, nodeId);
+        rejected = true;
+        break;
+      }
+      stops.push({ ...s, color });
+    }
+    if (rejected) continue;
+    out.push({ ...fill, stops });
+  }
+  return out;
+}
+
+/** Coerce loose JSON into a Fill array. Returns [] for non-arrays.
+ * A structurally-valid fill entry whose `kind` is not renderable by
+ * this runtime (e.g. `angular-gradient` / `diamond-gradient`, promoted
+ * to core by the LSML 1.2 RFC) is dropped WITH a diagnostic — never
+ * silently (ADR 001 §3.4, issue #34). */
+export function parseFills(value: unknown, field?: string, nodeId?: string): Fill[] {
   if (!Array.isArray(value)) return [];
+  if (field !== undefined) {
+    for (const v of value) {
+      if (!isFill(v)) {
+        emitDiagnostic(
+          nodeId,
+          `${field}.kind`,
+          "fill kind is not renderable by this runtime ; layer dropped (angular/diamond gradients land with LSML 1.2)",
+        );
+      }
+    }
+  }
   return value.filter(isFill) as Fill[];
 }
 

package/src/render/filter-clamp.ts

@@ -0,0 +1,99 @@
+// Runtime half of the R8 filter gate (ADR 001 §5.1 R8, issue #42).
+//
+// The compiler clamps `filter` values at lowering (`lowerFilter`,
+// packages/compiler/src/compile.ts) — but a filter value pushed by a
+// LIVE LSDP delta reaches the runtime through `resolveProps` /
+// `animateBindings` without ever passing through the compiler. R8
+// requires the clamp at compile AND at runtime : an unbounded filter is
+// a compositing DoS in CEF. Every filter value that can reach an inline
+// style at render time MUST pass through this module.
+//
+// NOTE on duplication : these caps intentionally mirror the compiler's
+// `MAX_FILTER_BLUR_PX` / `MAX_FILTER_BRIGHTNESS` constants. Unifying
+// them behind a single shared module is tracked by issue #41 (same
+// model as the shared colour module) — do NOT change one side without
+// the other until #41 lands.
+//
+// ── Linear-time justification (RC#12) ────────────────────────────────
+// The string form is validated by a single ANCHORED regex made of
+// literals and bounded quantifiers ({1,7} / {1,4} digit runs, one
+// optional space run) — exactly one possible parse per input, no
+// backtracking blow-up. Inputs longer than MAX_FILTER_STRING_LEN are
+// rejected before the regex runs.
+// ─────────────────────────────────────────────────────────────────────
+
+import { emitDiagnostic } from "./diagnostics";
+
+/** Max CSS `blur()` radius accepted at runtime, in px (mirror of the
+ *  compiler cap — see issue #41). */
+export const MAX_FILTER_BLUR_PX = 100;
+/** Max CSS `brightness()` factor accepted at runtime (mirror of the
+ *  compiler cap — see issue #41 ; spec §6.1 blesses clamping to 4). */
+export const MAX_FILTER_BRIGHTNESS = 4;
+
+const MAX_FILTER_STRING_LEN = 64;
+
+const CAPS: Record<FilterChannel, number> = {
+  blur: MAX_FILTER_BLUR_PX,
+  brightness: MAX_FILTER_BRIGHTNESS,
+};
+
+export type FilterChannel = "blur" | "brightness";
+
+/**
+ * Gate one live numeric filter channel (R8 runtime half).
+ *
+ * Returns the clamped value, or `null` when the value is rejected
+ * (non-number, non-finite, negative — including `-0`, which would
+ * stringify to an accepted `0`). A `null` MUST be handled as "keep the
+ * last known-good value / identity" — never apply the raw input.
+ */
+export function clampFilterChannel(channel: FilterChannel, value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  if (value < 0 || Object.is(value, -0)) return null;
+  const cap = CAPS[channel];
+  return value > cap ? cap : value;
+}
+
+// The ONLY string form the compiler ever emits (`lowerFilter`) :
+// `blur(<n>px) brightness(<n>)`. Anything else — extra functions,
+// `url(`, negative signs, exponents — is rejected by construction
+// (the grammar has no `-`, no `e`, no second parenthesis pair).
+const FILTER_STRING_RE =
+  /^blur\((\d{1,7}(?:\.\d{1,4})?)px\) brightness\((\d{1,7}(?:\.\d{1,4})?)\)$/;
+
+/** Identity filter — matches the compiler's neutral emission and
+ *  `INITIAL_IDENTITY.filter` in transitions.ts. */
+export const FILTER_IDENTITY = "blur(0px) brightness(1)";
+
+/**
+ * Gate a CSS filter STRING reaching framer-motion at runtime
+ * (`animate_initial.filter`, keyframe `steps[].filter`). Hand-crafted
+ * bundles bypass the compiler clamps, so the runtime re-validates and
+ * re-clamps (R8). Returns the safe, clamped canonical string or `null`
+ * on rejection — never the raw input.
+ */
+export function sanitizeCssFilterString(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  if (value.length === 0 || value.length > MAX_FILTER_STRING_LEN) return null;
+  const m = FILTER_STRING_RE.exec(value);
+  if (!m) return null;
+  const blur = clampFilterChannel("blur", Number(m[1]));
+  const brightness = clampFilterChannel("brightness", Number(m[2]));
+  if (blur === null || brightness === null) return null;
+  return `blur(${blur}px) brightness(${brightness})`;
+}
+
+/**
+ * Diagnostic for a rejected filter value. Bastion R9 (ADR 001 §5.1) :
+ * the rejected VALUE is never logged nor forwarded — only `node.id`
+ * (RC#7, issue #34), the field name and a static reason. Routed through
+ * the structured diagnostics channel (events, no logs in `broadcast`).
+ */
+export function warnRejectedFilter(field: string, nodeId?: string): void {
+  emitDiagnostic(
+    nodeId,
+    field,
+    "rejected unsafe filter value : outside the R8 caps or not a finite number >= 0",
+  );
+}

package/src/render/keyframe-player.tsx

@@ -22,10 +22,18 @@ import { scopedPath, usePathScope } from "./scope";
 export interface KeyframePlayerProps {
   keyframes: Keyframes;
   store: Store;
+  /** `RenderNode.id` of the owning node — threaded into keyframe
+   *  diagnostics (ADR 001 RC#7, issue #34). */
+  nodeId?: string;
   children: ReactNode;
 }
 
-export function KeyframePlayer({ keyframes, store, children }: KeyframePlayerProps): ReactNode {
+export function KeyframePlayer({
+  keyframes,
+  store,
+  nodeId,
+  children,
+}: KeyframePlayerProps): ReactNode {
   useSignals();
   const scope = usePathScope();
   const staggerDelayMs = useContext(StaggerContext);
@@ -43,7 +51,7 @@ export function KeyframePlayer({ keyframes, store, children }: KeyframePlayerPro
     }
   }
 
-  const compiled = compileForFramer(keyframes);
+  const compiled = compileForFramer(keyframes, nodeId);
   if (!compiled) {
     return <>{children}</>;
   }

package/src/render/primitives/frame.tsx

@@ -3,6 +3,8 @@ import type { CSSProperties } from "react";
 import type { PrimitiveProps } from "./index";
 import { toFramer, mountPlay, resolveTransition } from "../../animate/transitions";
 import { backgroundsToCss, parseFills } from "../fill";
+import { parseCssColor, warnRejectedColor } from "../css-color";
+import { emitDiagnostic } from "../diagnostics";
 
 /** Absolute-positioned container with size + transform + opacity.
  *  Animatable on `transform` and `opacity` only — width/height/position
@@ -12,8 +14,17 @@ import { backgroundsToCss, parseFills } from "../fill";
  *  LSML 1.1 §4.3 + §4.12 add `backgrounds[]` as an alternative to the
  *  legacy `background` (single color). The array form supports stacked
  *  fills with linear / radial gradients ; first entry renders on top.
+ *
+ *  LSML 1.1 §4.3 `clipsContent` (default `true`) clips children outside
+ *  the frame's bounds via `overflow: hidden` (ADR 001 §3.2.5, RC#5).
  */
-export function Frame({ resolved, transitionFor, animateInitial, children }: PrimitiveProps) {
+export function Frame({
+  resolved,
+  nodeId,
+  transitionFor,
+  animateInitial,
+  children,
+}: PrimitiveProps) {
   const x = numberOr(resolved.x, 0);
   const y = numberOr(resolved.y, 0);
   const width = sizeProp(resolved.width);
@@ -23,9 +34,15 @@ export function Frame({ resolved, transitionFor, animateInitial, children }: Pri
   const rotate = numberOr(resolved.rotate, 0);
 
   // 1.0 single-fill prop — used as fallback when 1.1 `backgrounds[]`
-  // is empty.
-  const legacyBackground = (resolved.background as string | undefined) ?? undefined;
-  const backgrounds = parseFills(resolved.backgrounds);
+  // is empty. RC#11 : the value is untrusted (static prop OR live LSDP
+  // delta) and lands in inline CSS — strict-parse, never passthrough.
+  const rawBackground = resolved.background;
+  const legacyBackground = rawBackground === undefined ? undefined : parseCssColor(rawBackground);
+  if (rawBackground !== undefined && legacyBackground === null) {
+    warnRejectedColor("frame.background", nodeId);
+  }
+  const backgrounds = parseFills(resolved.backgrounds, "frame.backgrounds", nodeId);
+  const clipsContent = resolveClipsContent(resolved.clipsContent, nodeId);
 
   // Pick the most expressive declared transition among the animated
   // bindings (transform / opacity). If none, no animation.
@@ -42,14 +59,19 @@ export function Frame({ resolved, transitionFor, animateInitial, children }: Pri
     width,
     height,
     willChange: "transform, opacity",
+    // LSML 1.1 §4.3 `clipsContent` (default `true`) — children outside
+    // the frame's `size` are clipped. Static layout property : it never
+    // animates, so it stays off the 0-layout-event hot path (ADR 001
+    // §3.2.5). `false` => omit the declaration (CSS initial = visible).
+    ...(clipsContent ? { overflow: "hidden" } : {}),
   };
   if (backgrounds.length > 0) {
-    Object.assign(style, backgroundsToCss(backgrounds));
-  } else if (legacyBackground !== undefined) {
+    Object.assign(style, backgroundsToCss(backgrounds, nodeId));
+  } else if (legacyBackground !== undefined && legacyBackground !== null) {
     style.background = legacyBackground;
   }
 
-  const play = mountPlay({ opacity, x, y, scale, rotate }, animateInitial);
+  const play = mountPlay({ opacity, x, y, scale, rotate }, animateInitial, nodeId);
 
   return (
     <motion.div
@@ -63,6 +85,24 @@ export function Frame({ resolved, transitionFor, animateInitial, children }: Pri
   );
 }
 
+/**
+ * Resolve `clipsContent` (LSML 1.1 §4.3, schema default `true`).
+ *
+ * The prop is wire-drivable (static bundle prop OR live LSDP delta via
+ * `resolveProps`, tree.tsx), so a non-boolean is treated as hostile :
+ * R9 diagnostic (value withheld) + fall back to the spec default
+ * (`true`, i.e. clipped — the safe state for broadcast). The returned
+ * value only ever selects between two literal style fragments — no
+ * untrusted value can reach inline CSS through this path (RC#11 by
+ * construction). Exported for boundary testing.
+ */
+export function resolveClipsContent(v: unknown, nodeId?: string): boolean {
+  if (v === undefined) return true;
+  if (typeof v === "boolean") return v;
+  emitDiagnostic(nodeId, "frame.clipsContent", "rejected value : not a boolean");
+  return true;
+}
+
 function numberOr(v: unknown, fallback: number): number {
   return typeof v === "number" && Number.isFinite(v) ? v : fallback;
 }

package/src/render/primitives/image.tsx

@@ -6,9 +6,12 @@ import { toFramer, mountPlay, resolveTransition } from "../../animate/transition
  *  `opacity`. Opacity is animated when a transition is declared. When an
  *  `animate.from` is lowered onto the node, it mounts at that state and
  *  plays to its target on mount (mount-play). */
-export function Image({ resolved, transitionFor, animateInitial }: PrimitiveProps) {
+export function Image({ resolved, nodeId, transitionFor, animateInitial }: PrimitiveProps) {
   const src = resolved.src as string | undefined;
   if (!src) return null;
+  // LSML §4.5 `alt` is required and was silently unrendered until
+  // issue #34's allowlist audit surfaced it — now forwarded to the DOM.
+  const alt = typeof resolved.alt === "string" ? resolved.alt : "";
   const fit = (resolved.fit as string | undefined) ?? "contain";
   const position = (resolved.position as string | undefined) ?? "center";
   const opacity = numberOr(resolved.opacity, 1);
@@ -19,11 +22,12 @@ export function Image({ resolved, transitionFor, animateInitial }: PrimitiveProp
   const height = dimOr(resolved.height, "100%");
 
   const tx = resolveTransition(transitionFor, ["opacity", "src"], animateInitial);
-  const play = mountPlay({ opacity }, animateInitial);
+  const play = mountPlay({ opacity }, animateInitial, nodeId);
 
   return (
     <motion.img
       src={src}
+      alt={alt}
       style={{
         objectFit: fit as React.CSSProperties["objectFit"],
         objectPosition: position,

package/src/render/primitives/index.ts

@@ -19,6 +19,9 @@ import { Instance } from "./instance";
 
 export interface PrimitiveProps {
   resolved: Record<string, unknown>;
+  /** `RenderNode.id` of the node being rendered — threaded into every
+   *  diagnostic the primitive emits (ADR 001 RC#7, issue #34). */
+  nodeId?: string;
   transitionFor: (key: string) => Transition | undefined;
   /** LSML 1.1 `animate.from` lowered to a flat framer `initial` map
    *  (keys: `opacity`, `scale`, `rotate`, `x`, `y`). When present, a

package/src/render/primitives/instance.tsx

@@ -22,31 +22,30 @@
 
 import type { ReactElement } from "react";
 import type { PrimitiveProps } from "./index";
+import { emitDiagnostic } from "../diagnostics";
 
 const warned = new Set<string>();
 
-export function Instance({ resolved }: PrimitiveProps): ReactElement | null {
+export function Instance({ resolved, nodeId }: PrimitiveProps): ReactElement | null {
   const sceneId = resolved.scene_id as string | undefined;
   const sceneVersion = resolved.scene_version as string | undefined;
   if (!sceneId || !sceneVersion) {
-    if (import.meta.env.DEV) {
-      console.warn("[lumencast/instance] missing scene_id or scene_version", resolved);
-    }
+    // Structured diagnostic — never dump `resolved` (R9 : prop values,
+    // including bound params, must not transit a diagnostic channel).
+    emitDiagnostic(nodeId, "instance.scene_id", "missing scene_id or scene_version ; not rendered");
     return null;
   }
 
-  // One-time DEV warning per (sceneId,version) so authors know the
+  // One-time diagnostic per (sceneId,version) so authors know the
   // scaffold limitation.
-  if (import.meta.env.DEV) {
-    const key = `${sceneId}:${sceneVersion}`;
-    if (!warned.has(key)) {
-      warned.add(key);
-      console.warn(
-        `[lumencast/instance] scaffold render — async bundle fetch + ` +
-          `__params.* injection are not yet wired (LSML 1.1 §4.9). ` +
-          `scene_id=${sceneId}`,
-      );
-    }
+  const key = `${sceneId}:${sceneVersion}`;
+  if (!warned.has(key)) {
+    warned.add(key);
+    emitDiagnostic(
+      nodeId,
+      "instance",
+      "scaffold render — async bundle fetch + __params.* injection are not yet wired (LSML 1.1 §4.9)",
+    );
   }
 
   const size = resolved.size as { w?: number; h?: number } | undefined;