@lumencast/compiler 0.4.0 → 0.6.0

package/src/compile.ts

@@ -26,29 +26,214 @@ import type {
   LSMLAnimateDirective,
   LSMLAnimateState,
   LSMLBundle,
+  LSMLKeyframes,
   LSMLNode,
+  LSMLPath,
   LSMLRepeat,
   LSMLText,
 } from "./lsml-types.js";
 
+/** Structured compile diagnostic (ADR 001 §3.4, issue #34). Per
+ *  Bastion R9 it carries node identity + field + static reason and
+ *  NEVER the offending value. */
+export interface CompileDiagnostic {
+  /** `node.id` of the owning node, `"<anon>"` when absent, or
+   *  `"<bundle>"` for bundle-level fields. */
+  nodeId: string;
+  /** Field name (e.g. `effects`, `style.textShadow`, `keyframes.steps[0].filter.blur`). */
+  field: string;
+  /** Static reason — why the field warns. Never includes the value. */
+  reason: string;
+}
+
 export interface CompileOptions {
-  /** When true, throws on any unrecognized LSML extension. Default false (warn-only). */
+  /** When true, throws on any warning — unrecognized LSML extension,
+   *  spec'd-but-not-lowered field, clamped value. Default false (warn-only). */
   strict?: boolean;
-  /** Optional warn collector — receives each warning string. */
-  onWarn?: (message: string) => void;
+  /** Optional warn collector — receives the formatted message plus the
+   *  structured diagnostic (additive second argument, issue #34). */
+  onWarn?: (message: string, diagnostic: CompileDiagnostic) => void;
 }
 
 const SUPPORTED_VERSIONS = new Set(["1.0", "1.1"] as const);
 
+// --- hard caps (ADR 001 §5.1 R8 + §6 RC#10, threat model Bastion) ------
+//
+// Filter clamps — an unbounded `filter` is a compositing DoS in CEF.
+/** Max CSS `blur()` radius emitted by the compiler, in px. */
+export const MAX_FILTER_BLUR_PX = 100;
+/** Max CSS `brightness()` factor emitted by the compiler (spec §6.1
+ *  explicitly blesses clamping to 4). */
+export const MAX_FILTER_BRIGHTNESS = 4;
+// Path caps — `d` strings are untrusted author input rendered into SVG.
+/** Max size of a single subpath `d` string (8 KiB, RC#10). */
+export const MAX_PATH_SUBPATH_BYTES = 8192;
+/** Max number of subpaths on a single shape (RC#10). */
+export const MAX_PATH_SUBPATHS = 64;
+/** Max number of path commands per subpath (RC#10). Kept below the
+ *  densest possible command packing within the byte cap (single-letter
+ *  `Z` spam = 1 command/byte) so the cap is actually reachable. */
+export const MAX_PATH_COMMANDS = 4000;
+
+/** Runtime keyframes shape (`@lumencast/runtime` `Keyframes`), referenced
+ *  through `RenderNode` so the compiler stays a type-only consumer. */
+type RuntimeKeyframes = NonNullable<RenderNode["keyframes"]>;
+type RuntimeKeyframeStep = RuntimeKeyframes["steps"][number];
+
+/** Emit an anti-silent-drop diagnostic (ADR 001 §3.4). Per Bastion R9 the
+ *  message carries `node.id` + field + reason and NEVER the offending
+ *  value (leaf/prop values can carry sensitive on-air content). */
+function warn(
+  opts: CompileOptions,
+  nodeId: string | undefined,
+  field: string,
+  reason: string,
+): void {
+  const diagnostic: CompileDiagnostic = { nodeId: nodeId ?? "<anon>", field, reason };
+  const message = `compiler: node "${diagnostic.nodeId}": field "${field}" ${reason}`;
+  if (opts.strict) throw new Error(message);
+  opts.onWarn?.(message, diagnostic);
+}
+
+/** Hard compile error — invalid value. Per R9 the message names the node
+ *  and field but never echoes the value itself. */
+function invalid(nodeId: string | undefined, field: string, reason: string): Error {
+  return new Error(`compiler: node "${nodeId ?? "<anon>"}": field "${field}" ${reason}`);
+}
+
+// --- consumed-key accounting (ADR 001 §3.4 D4, issue #34) --------------
+//
+// Every key present on a source node (or the bundle) and NOT consumed by
+// the lowering below produces an `onWarn` diagnostic — whether the key is
+// spec'd-but-unsupported or an unknown extension. `strict: true` turns
+// every warning into a throw. Exemptions (advisory by construction,
+// §17.5.1) : `metadata` blocks at every level ; authoring profiles are
+// forwarded verbatim, never key-audited.
+//
+// The sets below mirror EXACTLY what `compileNode` / `compileRepeat` /
+// `mapTextStyle` read. When extending the lowering, add the new key here
+// in the same change — a forgotten entry shows up as a spurious warning
+// in the fixture suite, never as a silent drop.
+
+/** Advisory, never audited (LSML §17.4 / §17.5.1). */
+const EXEMPT_KEYS = new Set(["metadata"]);
+
+/** Keys the common (non-repeat) lowering path consumes on every node. */
+const COMMON_NODE_KEYS: ReadonlySet<string> = new Set([
+  "kind",
+  "id",
+  "bind",
+  "bindStyle",
+  "bindUniversal",
+  "bindAnimate",
+  "animate",
+  "keyframes",
+  "children",
+  "visible",
+  "opacity",
+  "rotation",
+  "sizing",
+  "position",
+]);
+
+/** Keys `compileRepeat` consumes. `scope` names the iteration scope the
+ *  template's bind paths reference — declarative, no lowering needed. */
+const REPEAT_NODE_KEYS: ReadonlySet<string> = new Set([
+  "kind",
+  "id",
+  "bind",
+  "scope",
+  "template",
+  "stagger_ms",
+]);
+
+/** Per-kind keys consumed by the `switch` in `compileNode`. */
+const KIND_NODE_KEYS: Readonly<Record<string, ReadonlySet<string>>> = {
+  stack: new Set(["direction", "gap", "align", "justify", "padding", "rtl"]),
+  grid: new Set(["columns", "rows", "gap", "padding"]),
+  frame: new Set(["size", "position", "background", "backgrounds", "clipsContent"]),
+  text: new Set(["style", "format", "maxLines"]),
+  image: new Set(["alt", "size", "fit"]),
+  shape: new Set([
+    "geometry",
+    "size",
+    "pathData",
+    "paths",
+    "fill",
+    "fills",
+    "stroke",
+    "strokes",
+    "cornerRadius",
+    "ariaLabel",
+  ]),
+  media: new Set(["kind_hint", "controls", "autoplay", "muted", "loop", "size"]),
+  instance: new Set(["scene_id", "scene_version", "size", "fit", "params", "bindParams"]),
+};
+
+/** Keys `mapTextStyle` consumes inside `text.style`. */
+const TEXT_STYLE_KEYS: ReadonlySet<string> = new Set([
+  "fontSize",
+  "fontFamily",
+  "fontWeight",
+  "color",
+  "textAlign",
+  "lineHeight",
+  "letterSpacing",
+  "textTransform",
+  "textDecoration",
+  "fontStyle",
+]);
+
+/** Keys `compileBundle` consumes at the bundle level. */
+const BUNDLE_KEYS: ReadonlySet<string> = new Set([
+  "lsml",
+  "$schema",
+  "scene_id",
+  "scene_version",
+  "profiles",
+  "layout",
+  "operator_inputs",
+  "external_adapters",
+]);
+
+const NOT_LOWERED =
+  "is not lowered by this compiler ; without this diagnostic the field would drop silently (ADR 001 §3.4)";
+
+/** Diff a node's present keys against the consumed sets. */
+function auditNodeKeys(node: LSMLNode, opts: CompileOptions): void {
+  const allowed = node.kind === "repeat" ? REPEAT_NODE_KEYS : COMMON_NODE_KEYS;
+  const kindKeys = node.kind === "repeat" ? undefined : KIND_NODE_KEYS[node.kind];
+  for (const key of Object.keys(node)) {
+    if (EXEMPT_KEYS.has(key) || allowed.has(key) || kindKeys?.has(key)) continue;
+    warn(opts, node.id, key, NOT_LOWERED);
+  }
+}
+
+/** Diff bundle-level keys (`defaults`, `assets`, `i18n` and unknown
+ *  extensions warn today — none of them lands in the RenderBundle). */
+function auditBundleKeys(lsml: LSMLBundle, opts: CompileOptions): void {
+  for (const key of Object.keys(lsml)) {
+    if (EXEMPT_KEYS.has(key) || BUNDLE_KEYS.has(key)) continue;
+    warn(opts, "<bundle>", key, NOT_LOWERED);
+  }
+}
+
 export function compileBundle(lsml: LSMLBundle, options: CompileOptions = {}): RenderBundle {
   if (!SUPPORTED_VERSIONS.has(lsml.lsml as "1.0" | "1.1")) {
     throw new Error(
       `compiler: LSML version "${lsml.lsml}" is not supported (supported: ${[...SUPPORTED_VERSIONS].join(", ")})`,
     );
   }
+  auditBundleKeys(lsml, options);
   return {
     scene_version: lsml.scene_version,
     root: compileNode(lsml.layout, options),
+    // LSML 1.1 §17.3 — forward `profiles[]` verbatim so the runtime applies
+    // the same gating rule (§17.3.1 hard rejection for unsupported
+    // behavioural profiles, §17.5.1 advisory pass-through for authoring
+    // profiles) on the compiled path as on the direct-fetch path (ADR 001
+    // §3.2.1, RC#1).
+    ...(lsml.profiles !== undefined ? { profiles: [...lsml.profiles] } : {}),
     ...(lsml.operator_inputs
       ? {
           operator_inputs: lsml.operator_inputs.map((oi) => ({
@@ -70,6 +255,11 @@ export function compileBundle(lsml: LSMLBundle, options: CompileOptions = {}): R
 }
 
 function compileNode(node: LSMLNode, opts: CompileOptions): RenderNode {
+  // ADR 001 §3.4 (issue #34) — every present key must be consumed by the
+  // lowering below, exempt (`metadata`), or diagnosed. Runs for repeat
+  // nodes too (their consumed set differs).
+  auditNodeKeys(node, opts);
+
   if (node.kind === "repeat") {
     return compileRepeat(node, opts);
   }
@@ -111,10 +301,16 @@ function compileNode(node: LSMLNode, opts: CompileOptions): RenderNode {
         props["y"] = node.position.y;
       }
       if (node.background !== undefined) props["background"] = node.background;
+      // 1.1 §4.3 + §4.12 — stacked backgrounds (frame.tsx reads
+      // `resolved.backgrounds`; array form wins over legacy `background`).
+      if (node.backgrounds !== undefined) props["backgrounds"] = node.backgrounds;
+      // 1.1 §4.3 — clip children to the frame bounds. The spec default
+      // (`true`) is applied runtime-side ; only explicit values forward.
+      if (node.clipsContent !== undefined) props["clipsContent"] = node.clipsContent;
       break;
 
     case "text":
-      mapTextStyle(node, props);
+      mapTextStyle(node, props, opts);
       if (node.format !== undefined) props["format"] = node.format;
       if (node.maxLines !== undefined) props["maxLines"] = node.maxLines;
       break;
@@ -132,10 +328,36 @@ function compileNode(node: LSMLNode, opts: CompileOptions): RenderNode {
         props["width"] = node.size.w;
         props["height"] = node.size.h;
       }
-      if (node.pathData !== undefined) props["pathData"] = node.pathData;
+      // Path geometry — every `d` string is untrusted author input that
+      // ends up in an SVG attribute. Validate at compile per RC#10 (the
+      // runtime re-validates live deltas in its own gate — issue #30).
+      if (node.pathData !== undefined) {
+        validatePathData(node.pathData, node.id, "pathData");
+        props["pathData"] = node.pathData;
+      }
+      if (node.paths !== undefined) {
+        props["paths"] = lowerPaths(node.paths, node.id);
+        if (node.pathData !== undefined) {
+          // §4.6 declares the two forms mutually exclusive ; we keep
+          // both forwarded (runtime prefers `paths`) but surface it.
+          warn(opts, node.id, "pathData", "is mutually exclusive with paths[] (LSML §4.6)");
+        }
+      }
       if (node.fill !== undefined) props["fill"] = node.fill;
-      if (node.stroke !== undefined) props["stroke"] = node.stroke;
-      if (node.cornerRadius !== undefined) props["cornerRadius"] = node.cornerRadius;
+      // 1.1 §4.6 + §4.12 — stacked fills (shape.tsx reads `resolved.fills`).
+      if (node.fills !== undefined) props["fills"] = node.fills;
+      // Single stroke lowers to the flat props shape.tsx consumes
+      // (`stroke` = colour string, `stroke_width` = number). The previous
+      // object forward was silently unrenderable.
+      if (node.stroke !== undefined) {
+        props["stroke"] = node.stroke.color;
+        props["stroke_width"] = node.stroke.width;
+      }
+      // 1.1 §4.6 — stacked strokes (shape.tsx reads `resolved.strokes`).
+      if (node.strokes !== undefined) props["strokes"] = node.strokes;
+      // Canonical RenderNode name is `radius` (what shape.tsx reads) ;
+      // the previous `cornerRadius` forward was silently dropped.
+      if (node.cornerRadius !== undefined) props["radius"] = node.cornerRadius;
       if (node.ariaLabel !== undefined) props["ariaLabel"] = node.ariaLabel;
       break;
 
@@ -202,12 +424,34 @@ function compileNode(node: LSMLNode, opts: CompileOptions): RenderNode {
     if (tx) {
       const transitions: Record<string, ReturnType<typeof compileAnimate>> = {};
       if (node.animate.opacity !== undefined) transitions["opacity"] = tx;
-      if (node.animate.transform?.scale !== undefined) transitions["scale"] = tx;
+      if (node.animate.transform?.scale !== undefined) {
+        // Per-axis `[sx, sy]` lowers to framer's `scaleX` / `scaleY`
+        // motion keys ; a scalar stays on uniform `scale`.
+        if (Array.isArray(node.animate.transform.scale)) {
+          transitions["scaleX"] = tx;
+          transitions["scaleY"] = tx;
+        } else {
+          transitions["scale"] = tx;
+        }
+      }
       if (node.animate.transform?.rotate !== undefined) transitions["rotate"] = tx;
       if (node.animate.transform?.translate !== undefined) {
         transitions["x"] = tx;
         transitions["y"] = tx;
       }
+      // §6.1 — `filter` is animatable ; previously dropped in silence.
+      if (node.animate.filter !== undefined) transitions["filter"] = tx;
+      // §6.3 — a bound animation channel must honour the declared
+      // `animate.transition` too : emit a per-prop transition entry for
+      // every bindAnimate key so the runtime retargets with the
+      // authored timing instead of its default spring.
+      if (node.bindAnimate) {
+        for (const key of Object.keys(node.bindAnimate)) {
+          for (const fk of transitionKeysForBindAnimate(key, node.kind)) {
+            transitions[fk] = tx;
+          }
+        }
+      }
       // Type assertion: RenderNode.transitions matches Transition shape; the
       // cast keeps the compiler self-contained without re-importing the runtime
       // Transition type.
@@ -222,28 +466,333 @@ function compileNode(node: LSMLNode, opts: CompileOptions): RenderNode {
     // timing). When no `from` is present, `animate_initial` is omitted
     // and the prior no-mount-play behaviour is preserved (rétro-compat).
     if (node.animate.from) {
-      const initial = lowerAnimateState(node.animate.from);
+      const initial = lowerAnimateState(node.animate.from, node.id, opts);
       if (Object.keys(initial).length > 0) {
         out.animate_initial = initial;
       }
     }
   }
 
+  // §6.3 `bindAnimate` → RenderNode `animateBindings` (ADR 001 §3.3,
+  // issue #33). Validation is HARD : any key outside the animatable set
+  // throws at compile (RC#13 — a malformed bindAnimate is an invalid
+  // directive, the warn-by-default policy §3.4 does not apply).
+  if (node.bindAnimate !== undefined) {
+    const lowered = lowerBindAnimate(node.bindAnimate, node.kind, node.id);
+    if (Object.keys(lowered).length > 0) out.animateBindings = lowered;
+  }
+
+  // LSML 1.1 §6.6 — keyframe sequence, lowered to the runtime
+  // `Keyframes` shape consumed by KeyframePlayer.
+  if (node.keyframes !== undefined) {
+    out.keyframes = lowerKeyframes(node.keyframes, node.id, opts);
+  }
+
+  return out;
+}
+
+// --- bindAnimate lowering (LSML §6.3 — ADR 001 §3.3, RC#13) ------------
+//
+// `bindAnimate` keys MUST reference animatable properties only : the
+// §6.1 GPU-composited list, plus the node kind's colour-typed property
+// blessed by §6.5 for continuous colour interpolation. Anything else
+// (layout properties, unknown channels) is a HARD compile error — never
+// a warning (RC#13, exception to the §3.4 warn-by-default policy : an
+// invalid directive is not a "spec'd field we don't support yet").
+
+/** §6.1 animatable property keys accepted on every primitive. */
+export const BIND_ANIMATE_SCALAR_KEYS: ReadonlySet<string> = new Set([
+  "opacity",
+  "transform.translate",
+  "transform.scale",
+  "transform.rotate",
+  "filter.blur",
+  "filter.brightness",
+]);
+
+/** §6.5 colour-typed properties reachable via bindAnimate, per node
+ *  kind. Kept to the single-colour core props for now ; `fills[].color`
+ *  / `backgrounds[]` entries are array-typed and stay out of scope
+ *  (documented in ADR 001 phase B). */
+export const BIND_ANIMATE_COLOR_KEYS: Readonly<Record<string, string>> = {
+  text: "style.color",
+  shape: "fill",
+  frame: "background",
+};
+
+function isBindAnimateKeyAllowed(key: string, kind: string): boolean {
+  if (BIND_ANIMATE_SCALAR_KEYS.has(key)) return true;
+  return BIND_ANIMATE_COLOR_KEYS[kind] === key;
+}
+
+/** Validate + lower a §6.3 `bindAnimate` map. Keys keep their spec
+ *  names verbatim (the runtime maps them onto motion channels) ; values
+ *  must be non-empty LeafPath strings. Throws on any violation (RC#13) ;
+ *  per R9 the error names the node + key, never the bound value. */
+function lowerBindAnimate(
+  bind: Record<string, string>,
+  kind: string,
+  nodeId: string | undefined,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, path] of Object.entries(bind)) {
+    if (!isBindAnimateKeyAllowed(key, kind)) {
+      throw invalid(
+        nodeId,
+        `bindAnimate.${key}`,
+        "is not an animatable property for this primitive (LSML §6.1/§6.5, RC#13)",
+      );
+    }
+    if (typeof path !== "string" || path.length === 0) {
+      throw invalid(nodeId, `bindAnimate.${key}`, "must bind a non-empty LeafPath string");
+    }
+    out[key] = path;
+  }
   return out;
 }
 
+/** The per-prop `transitions` entries a bound channel resolves at the
+ *  runtime (mirrors the static-target lowering above : translate drives
+ *  framer `x`/`y`, scale may be per-axis, filter channels share the
+ *  composed `filter` entry, colour channels use the runtime prop name). */
+function transitionKeysForBindAnimate(key: string, kind: string): string[] {
+  switch (key) {
+    case "opacity":
+      return ["opacity"];
+    case "transform.translate":
+      return ["x", "y"];
+    case "transform.scale":
+      return ["scale", "scaleX", "scaleY"];
+    case "transform.rotate":
+      return ["rotate"];
+    case "filter.blur":
+    case "filter.brightness":
+      return ["filter"];
+    default:
+      // Colour channel — the runtime looks the transition up under the
+      // primitive's prop name (text → `colour`, shape → `fill`,
+      // frame → `background`).
+      if (BIND_ANIMATE_COLOR_KEYS[kind] === key) {
+        return [kind === "text" ? "colour" : key];
+      }
+      return [];
+  }
+}
+
+// --- path validation (ADR 001 §6 RC#10 — compile-side gate) -----------
+//
+// SVG `d` strings are untrusted author input rendered into a DOM
+// attribute. The grammar is ALLOWLISTED : path command letters
+// `MmLlHhVvCcSsQqTtAaZz` plus number/separator characters only. This
+// rejects `url(`, `data:`, `<` and `&` by construction (none of their
+// characters are in the allowlist). Implemented as a single-pass manual
+// scanner — linear time, no regex, no backtracking (anti-ReDoS, RC#12).
+//
+// Known limitation (by design) : the scanner is CHAR-LEVEL, not a number
+// grammar. Malformed numerics built from allowlisted characters (`1.2.3`,
+// `+-+5`, overflow exponents like `1e9999`) pass validation. This is
+// accepted : a syntactically invalid `d` is simply ignored by the
+// browser's SVG path parser (the path does not render), so there is no
+// injection or DoS vector — only the author's own shape failing to draw.
+// Upgrading to a full number grammar would add parser complexity for no
+// security gain.
+const PATH_COMMANDS = new Set("MmLlHhVvCcSsQqTtAaZz");
+
+function isPathNumberChar(ch: string): boolean {
+  return (ch >= "0" && ch <= "9") || ch === "." || ch === "+" || ch === "-" || ch === ",";
+}
+
+function isPathWhitespace(ch: string): boolean {
+  return ch === " " || ch === "\t" || ch === "\n" || ch === "\r";
+}
+
+/** Validate one subpath `d` string. Throws on any violation (size cap,
+ *  command cap, character outside the allowlist). Error messages name
+ *  the node + field but never echo the string (R9). */
+export function validatePathData(d: string, nodeId: string | undefined, field: string): void {
+  if (typeof d !== "string" || d.length === 0) {
+    throw invalid(nodeId, field, "must be a non-empty SVG path string");
+  }
+  // Allowlisted grammar is ASCII-only, so UTF-16 length === byte length
+  // for any string that passes the scan ; checking the cap first keeps
+  // the scan itself bounded.
+  if (d.length > MAX_PATH_SUBPATH_BYTES) {
+    throw invalid(nodeId, field, `exceeds the ${MAX_PATH_SUBPATH_BYTES}-byte subpath cap (RC#10)`);
+  }
+  let commands = 0;
+  for (let i = 0; i < d.length; i++) {
+    const ch = d[i] as string;
+    if (PATH_COMMANDS.has(ch)) {
+      commands++;
+      if (commands > MAX_PATH_COMMANDS) {
+        throw invalid(
+          nodeId,
+          field,
+          `exceeds the ${MAX_PATH_COMMANDS}-command subpath cap (RC#10)`,
+        );
+      }
+      continue;
+    }
+    if (isPathNumberChar(ch) || isPathWhitespace(ch)) continue;
+    // Exponent marker — only valid immediately after a digit or dot
+    // (e.g. `1e3`, `1.5E-2`). A bare `e`/`E` is rejected.
+    if ((ch === "e" || ch === "E") && i > 0) {
+      const prev = d[i - 1] as string;
+      if ((prev >= "0" && prev <= "9") || prev === ".") continue;
+    }
+    throw invalid(nodeId, field, `contains a character outside the SVG path allowlist (RC#10)`);
+  }
+  if (commands === 0) {
+    throw invalid(nodeId, field, "contains no SVG path command");
+  }
+}
+
+/** Validate + forward `paths[]` (LSML §4.6). Caps the subpath count and
+ *  validates every `data` string. */
+function lowerPaths(
+  paths: LSMLPath[],
+  nodeId: string | undefined,
+): { data: string; windingRule?: "NONZERO" | "EVENODD" }[] {
+  if (paths.length === 0) {
+    throw invalid(nodeId, "paths", "must contain at least one subpath");
+  }
+  if (paths.length > MAX_PATH_SUBPATHS) {
+    throw invalid(nodeId, "paths", `exceeds the ${MAX_PATH_SUBPATHS}-subpath cap (RC#10)`);
+  }
+  return paths.map((p, i) => {
+    validatePathData(p.data, nodeId, `paths[${i}].data`);
+    return {
+      data: p.data,
+      ...(p.windingRule !== undefined ? { windingRule: p.windingRule } : {}),
+    };
+  });
+}
+
+// --- filter lowering (ADR 001 §5.1 R8 — hard clamps, non-optional) -----
+
+/** Lower an LSML `filter` state (`{ blur?, brightness? }`) to the CSS
+ *  filter string framer-motion animates. Values are HARD-clamped at
+ *  lowering : negative / non-finite values are rejected (compile error),
+ *  `blur` caps at MAX_FILTER_BLUR_PX, `brightness` caps at
+ *  MAX_FILTER_BRIGHTNESS. Both functions are always emitted so framer
+ *  can interpolate between structurally-identical filter lists. */
+function lowerFilter(
+  f: NonNullable<LSMLAnimateState["filter"]>,
+  nodeId: string | undefined,
+  field: string,
+  opts: CompileOptions,
+): string {
+  let blur = 0;
+  let brightness = 1;
+  if (f.blur !== undefined) {
+    // `-0 < 0` is false in IEEE-754 — Object.is closes the negative-zero hole.
+    if (
+      typeof f.blur !== "number" ||
+      !Number.isFinite(f.blur) ||
+      f.blur < 0 ||
+      Object.is(f.blur, -0)
+    ) {
+      throw invalid(nodeId, `${field}.blur`, "must be a finite number >= 0 (R8)");
+    }
+    blur = f.blur;
+    if (blur > MAX_FILTER_BLUR_PX) {
+      blur = MAX_FILTER_BLUR_PX;
+      warn(opts, nodeId, `${field}.blur`, `clamped to the ${MAX_FILTER_BLUR_PX}px cap (R8)`);
+    }
+  }
+  if (f.brightness !== undefined) {
+    // Same -0 gate as blur : `brightness(-0)` stringifies to `brightness(0)`,
+    // a fully black element slipping past the negative-value rejection (R8).
+    if (
+      typeof f.brightness !== "number" ||
+      !Number.isFinite(f.brightness) ||
+      f.brightness < 0 ||
+      Object.is(f.brightness, -0)
+    ) {
+      throw invalid(nodeId, `${field}.brightness`, "must be a finite number >= 0 (R8)");
+    }
+    brightness = f.brightness;
+    if (brightness > MAX_FILTER_BRIGHTNESS) {
+      brightness = MAX_FILTER_BRIGHTNESS;
+      warn(opts, nodeId, `${field}.brightness`, `clamped to the ${MAX_FILTER_BRIGHTNESS} cap (R8)`);
+    }
+  }
+  return `blur(${blur}px) brightness(${brightness})`;
+}
+
+// --- keyframes lowering (LSML §6.6 → runtime Keyframes shape) ----------
+
+/** Lower a §6.6 keyframe sequence into the shape KeyframePlayer /
+ *  compileForFramer consume : `transform.translate: [x, y]` →
+ *  `translateX` / `translateY`, `filter: { blur, brightness }` → clamped
+ *  CSS string. Per-axis step scale degrades to `sx` with a diagnostic
+ *  (the runtime keyframe channel is uniform-scale ; per-axis keyframe
+ *  scale lands with ADR 001 phase B/C). */
+function lowerKeyframes(
+  kf: LSMLKeyframes,
+  nodeId: string | undefined,
+  opts: CompileOptions,
+): RuntimeKeyframes {
+  const steps: RuntimeKeyframeStep[] = kf.steps.map((s, i) => {
+    const step: RuntimeKeyframeStep = { at: s.at };
+    if (s.opacity !== undefined) step.opacity = s.opacity;
+    if (s.filter !== undefined) {
+      step.filter = lowerFilter(s.filter, nodeId, `keyframes.steps[${i}].filter`, opts);
+    }
+    const t = s.transform;
+    if (t) {
+      const transform: NonNullable<RuntimeKeyframeStep["transform"]> = {};
+      if (t.scale !== undefined) {
+        if (Array.isArray(t.scale)) {
+          transform.scale = t.scale[0];
+          warn(
+            opts,
+            nodeId,
+            `keyframes.steps[${i}].transform.scale`,
+            "per-axis scale is not supported in keyframes yet ; lowered to the x-axis value",
+          );
+        } else {
+          transform.scale = t.scale;
+        }
+      }
+      if (t.rotate !== undefined) transform.rotate = t.rotate;
+      if (t.translate !== undefined) {
+        transform.translateX = t.translate[0];
+        transform.translateY = t.translate[1];
+      }
+      if (Object.keys(transform).length > 0) step.transform = transform;
+    }
+    return step;
+  });
+  return {
+    ...(kf.key !== undefined ? { key: kf.key } : {}),
+    steps,
+    duration_ms: kf.duration_ms,
+    ...(kf.easing !== undefined ? { easing: kf.easing } : {}),
+  };
+}
+
 /** Lower an `animate.from` (or any LSML animate state) into the flat
  *  framer-motion key space the runtime primitives consume: `opacity`,
- *  `scale`, `rotate`, `x`, `y`. A scalar `scale` applies uniformly ; a
- *  `[sx, sy]` pair is collapsed to `sx` (framer takes a single scale on
- *  the motion components used here). `translate: [x, y]` → `x` / `y`. */
-function lowerAnimateState(s: LSMLAnimateState): Record<string, number> {
-  const out: Record<string, number> = {};
+ *  `scale` (or `scaleX`/`scaleY` for a per-axis `[sx, sy]` pair),
+ *  `rotate`, `x`, `y`, `filter` (clamped CSS string, R8).
+ *  `translate: [x, y]` → `x` / `y`. */
+function lowerAnimateState(
+  s: LSMLAnimateState,
+  nodeId: string | undefined,
+  opts: CompileOptions,
+): Record<string, number | string> {
+  const out: Record<string, number | string> = {};
   if (typeof s.opacity === "number") out["opacity"] = s.opacity;
   const t = s.transform;
   if (t) {
     if (t.scale !== undefined) {
-      out["scale"] = Array.isArray(t.scale) ? t.scale[0] : t.scale;
+      if (Array.isArray(t.scale)) {
+        out["scaleX"] = t.scale[0];
+        out["scaleY"] = t.scale[1];
+      } else {
+        out["scale"] = t.scale;
+      }
     }
     if (typeof t.rotate === "number") out["rotate"] = t.rotate;
     if (t.translate !== undefined) {
@@ -251,6 +800,9 @@ function lowerAnimateState(s: LSMLAnimateState): Record<string, number> {
       out["y"] = t.translate[1];
     }
   }
+  if (s.filter !== undefined) {
+    out["filter"] = lowerFilter(s.filter, nodeId, "animate.from.filter", opts);
+  }
   return out;
 }
 
@@ -265,12 +817,29 @@ function compileRepeat(node: LSMLRepeat, opts: CompileOptions): RenderNode {
     children: [compiledTemplate],
   };
   if (node.id !== undefined) out.id = node.id;
+  // LSML 1.1 §6.7 — per-iteration stagger. Negative values are invalid ;
+  // the runtime caps the effective delay (STAGGER_CAP_MS) at render.
+  if (node.stagger_ms !== undefined) {
+    if (
+      typeof node.stagger_ms !== "number" ||
+      !Number.isFinite(node.stagger_ms) ||
+      node.stagger_ms < 0
+    ) {
+      throw invalid(node.id, "stagger_ms", "must be a finite number >= 0");
+    }
+    out.stagger_ms = node.stagger_ms;
+  }
   return out;
 }
 
-function mapTextStyle(node: LSMLText, props: Record<string, unknown>): void {
+function mapTextStyle(node: LSMLText, props: Record<string, unknown>, opts: CompileOptions): void {
   if (!node.style) return;
   const s = node.style;
+  // Nested consumed-key accounting (issue #34) : a `style.*` key outside
+  // the TextStyle grammar (e.g. `style.textShadow`) warns, never drops.
+  for (const key of Object.keys(s)) {
+    if (!TEXT_STYLE_KEYS.has(key)) warn(opts, node.id, `style.${key}`, NOT_LOWERED);
+  }
   // Solar's Text primitive consumes size/weight/colour (UK), not CSS-style names.
   if (s.fontSize !== undefined) props["size"] = s.fontSize;
   if (s.fontFamily !== undefined) props["font"] = s.fontFamily;
@@ -278,6 +847,12 @@ function mapTextStyle(node: LSMLText, props: Record<string, unknown>): void {
   if (s.color !== undefined) props["colour"] = s.color;
   if (s.textAlign !== undefined) props["align"] = mapTextAlign(s.textAlign);
   if (s.lineHeight !== undefined) props["lineHeight"] = s.lineHeight;
+  // TextStyle 1.1 typography — same names runtime-side (text.tsx
+  // validates each value against the field's grammar before render).
+  if (s.letterSpacing !== undefined) props["letterSpacing"] = s.letterSpacing;
+  if (s.textTransform !== undefined) props["textTransform"] = s.textTransform;
+  if (s.textDecoration !== undefined) props["textDecoration"] = s.textDecoration;
+  if (s.fontStyle !== undefined) props["fontStyle"] = s.fontStyle;
 }
 
 function mapAlign(a: NonNullable<Extract<LSMLNode, { kind: "stack" }>["align"]>): string {
@@ -326,14 +901,18 @@ function compileAnimate(a: LSMLAnimateDirective):
       duration_ms: number;
       ease?: "linear" | "cubic-in" | "cubic-out" | "cubic-in-out";
     }
-  | { kind: "spring"; stiffness?: number; damping?: number }
+  | { kind: "spring"; stiffness?: number; damping?: number; mass?: number }
   | undefined {
   const t = a.transition;
   if (!t) return undefined;
   if (t.easing === "spring") {
-    const out: { kind: "spring"; stiffness?: number; damping?: number } = { kind: "spring" };
+    const out: { kind: "spring"; stiffness?: number; damping?: number; mass?: number } = {
+      kind: "spring",
+    };
     if (t.stiffness !== undefined) out.stiffness = t.stiffness;
     if (t.damping !== undefined) out.damping = t.damping;
+    // §6.2 — spring mass (default 1 runtime-side, ADR 001 phase B).
+    if (t.mass !== undefined) out.mass = t.mass;
     return out;
   }
   return {