@lumencast/compiler 0.4.0 → 0.6.0

package/dist/compile.js

@@ -21,13 +21,160 @@
 // surfaces `BUNDLE_INCOMPATIBLE` per LSML §15.1 if it can't honour them).
 // Bundles tagged 2.x are rejected — major bumps require explicit support.
 const SUPPORTED_VERSIONS = new Set(["1.0", "1.1"]);
+// --- 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;
+/** 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, nodeId, field, reason) {
+    const diagnostic = { 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, field, reason) {
+    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 = 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 = new Set([
+    "kind",
+    "id",
+    "bind",
+    "scope",
+    "template",
+    "stagger_ms",
+]);
+/** Per-kind keys consumed by the `switch` in `compileNode`. */
+const KIND_NODE_KEYS = {
+    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 = new Set([
+    "fontSize",
+    "fontFamily",
+    "fontWeight",
+    "color",
+    "textAlign",
+    "lineHeight",
+    "letterSpacing",
+    "textTransform",
+    "textDecoration",
+    "fontStyle",
+]);
+/** Keys `compileBundle` consumes at the bundle level. */
+const BUNDLE_KEYS = 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, opts) {
+    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, opts) {
+    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, options = {}) {
     if (!SUPPORTED_VERSIONS.has(lsml.lsml)) {
         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) => ({
@@ -48,6 +195,10 @@ export function compileBundle(lsml, options = {}) {
     };
 }
 function compileNode(node, opts) {
+    // 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);
     }
@@ -98,9 +249,17 @@ function compileNode(node, opts) {
             }
             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)
@@ -119,14 +278,40 @@ function compileNode(node, opts) {
                 props["width"] = node.size.w;
                 props["height"] = node.size.h;
             }
-            if (node.pathData !== undefined)
+            // 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;
+            // 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["cornerRadius"] = node.cornerRadius;
+                props["radius"] = node.cornerRadius;
             if (node.ariaLabel !== undefined)
                 props["ariaLabel"] = node.ariaLabel;
             break;
@@ -204,14 +389,37 @@ function compileNode(node, opts) {
             const transitions = {};
             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.
@@ -225,27 +433,287 @@ function compileNode(node, opts) {
         // 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 = 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 = {
+    text: "style.color",
+    shape: "fill",
+    frame: "background",
+};
+function isBindAnimateKeyAllowed(key, kind) {
+    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, kind, nodeId) {
+    const out = {};
+    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, kind) {
+    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) {
+    return (ch >= "0" && ch <= "9") || ch === "." || ch === "+" || ch === "-" || ch === ",";
+}
+function isPathWhitespace(ch) {
+    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, nodeId, field) {
+    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];
+        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];
+            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, nodeId) {
+    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, nodeId, field, opts) {
+    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, nodeId, opts) {
+    const steps = kf.steps.map((s, i) => {
+        const step = { 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 = {};
+            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) {
+ *  `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, nodeId, opts) {
     const out = {};
     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;
@@ -254,6 +722,9 @@ function lowerAnimateState(s) {
             out["y"] = t.translate[1];
         }
     }
+    if (s.filter !== undefined) {
+        out["filter"] = lowerFilter(s.filter, nodeId, "animate.from.filter", opts);
+    }
     return out;
 }
 function compileRepeat(node, opts) {
@@ -268,12 +739,28 @@ function compileRepeat(node, opts) {
     };
     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, props) {
+function mapTextStyle(node, props, opts) {
     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;
@@ -287,6 +774,16 @@ function mapTextStyle(node, props) {
         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) {
     // LSML uses CSS-grid vocabulary; Solar's Stack consumes flexbox vocabulary.
@@ -330,11 +827,16 @@ function compileAnimate(a) {
     if (!t)
         return undefined;
     if (t.easing === "spring") {
-        const out = { kind: "spring" };
+        const out = {
+            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 {