@lumencast/runtime 0.3.0 → 0.5.0

package/src/animate/transitions.ts

@@ -11,6 +11,8 @@
 // filter). Primitives enforce this at the DOM level by exposing those props as
 // motion-bindable values rather than raw CSS.
 
+import { sanitizeCssFilterString, warnRejectedFilter } from "../render/filter-clamp";
+
 export type TransitionKind = "none" | "tween" | "spring" | "crossfade";
 
 export interface TweenTransition {
@@ -23,6 +25,8 @@ export interface SpringTransition {
   kind: "spring";
   stiffness?: number;
   damping?: number;
+  /** LSML 1.1 §6.2 — spring mass (kg). Default 1 (framer default). */
+  mass?: number;
 }
 
 export interface CrossfadeTransition {
@@ -44,6 +48,7 @@ export interface FramerTransition {
   type?: "tween" | "spring";
   stiffness?: number;
   damping?: number;
+  mass?: number;
 }
 
 const NO_ANIMATION: FramerTransition = { duration: 0 };
@@ -69,6 +74,7 @@ export function toFramer(t: Transition | undefined): FramerTransition {
       type: "spring",
       ...(t.stiffness !== undefined ? { stiffness: t.stiffness } : {}),
       ...(t.damping !== undefined ? { damping: t.damping } : {}),
+      ...(t.mass !== undefined ? { mass: t.mass } : {}),
     };
   }
   // crossfade at the per-prop level degenerates into a tween on opacity.
@@ -85,12 +91,18 @@ export function toFramer(t: Transition | undefined): FramerTransition {
  *  may declare. A primitive that doesn't natively animate a given key
  *  still converges it to this neutral value on mount so the element ends
  *  up visually correct (e.g. a `from.scale: 0.85` settles at `scale: 1`). */
-const INITIAL_IDENTITY: Record<string, number> = {
+const INITIAL_IDENTITY: Record<string, number | string> = {
   opacity: 1,
   scale: 1,
+  scaleX: 1,
+  scaleY: 1,
   rotate: 0,
   x: 0,
   y: 0,
+  // LSML §6.1 filter identity — both functions are always present so
+  // framer interpolates between structurally-identical filter lists
+  // (the compiler emits the same two-function form, clamped per R8).
+  filter: "blur(0px) brightness(1)",
 };
 
 export interface MountPlay {
@@ -98,6 +110,58 @@ export interface MountPlay {
   animate: Record<string, number | string>;
 }
 
+/**
+ * Default mount-play timing — applies when a node carries an
+ * `animate_initial` (LSML 1.1 `animate.from`) but no per-prop
+ * `transitions` entry resolves for any animated key. The compiler
+ * documents that `from` without an explicit `transition` mount-plays
+ * "with the runtime's default timing" ; before this constant existed the
+ * fallback was `toFramer(undefined)` → `{ duration: 0 }`, which snapped
+ * the element straight to its settled state (the mount-play never
+ * visibly played). 400 ms ease-out matches the runtime's other implicit
+ * timings (crossfade fallback, scene-track fade).
+ */
+export const DEFAULT_MOUNT_PLAY_TRANSITION: Transition = {
+  kind: "tween",
+  duration_ms: 400,
+  ease: "cubic-out",
+};
+
+/**
+ * Resolve the transition a primitive should hand framer-motion.
+ *
+ * `keys` are the primitive's native animated prop keys, scanned in
+ * order (e.g. `["opacity", "src"]` for Image). When the node also
+ * carries an `animate_initial`, the lookup widens to the keys the
+ * mount-play actually moves (`from.scale` may have lowered a `scale`
+ * transition that an opacity-only primitive would otherwise never look
+ * up), and — critically — falls back to
+ * `DEFAULT_MOUNT_PLAY_TRANSITION` instead of "no animation" : a
+ * mount-play must tween, never complete in zero frames.
+ *
+ * Without `animate_initial` the prior behaviour is preserved exactly :
+ * first declared transition among `keys`, else `undefined` (deltas
+ * snap unless a transition is declared).
+ */
+export function resolveTransition(
+  transitionFor: (key: string) => Transition | undefined,
+  keys: string[],
+  animateInitial?: Record<string, number | string>,
+): Transition | undefined {
+  for (const key of keys) {
+    const t = transitionFor(key);
+    if (t !== undefined) return t;
+  }
+  if (animateInitial && Object.keys(animateInitial).length > 0) {
+    for (const key of Object.keys(animateInitial)) {
+      const t = transitionFor(key);
+      if (t !== undefined) return t;
+    }
+    return DEFAULT_MOUNT_PLAY_TRANSITION;
+  }
+  return undefined;
+}
+
 /**
  * Build framer-motion `initial` / `animate` props for a primitive that
  * may carry an LSML 1.1 `animate.from` initial state.
@@ -117,6 +181,7 @@ export interface MountPlay {
 export function mountPlay(
   base: Record<string, number | string>,
   initial: Record<string, number | string> | undefined,
+  nodeId?: string,
 ): MountPlay {
   if (!initial || Object.keys(initial).length === 0) {
     // No `from` → mount directly at target. Pinning `initial` to the
@@ -124,13 +189,28 @@ export function mountPlay(
     // preserves the existing "no jump, no mount-play" behaviour.
     return { initial: base, animate: base };
   }
+  // R8 runtime half (ADR 001 §5.1, issue #42) — `animate_initial` may
+  // come from a hand-crafted bundle that never went through the
+  // compiler clamps. Re-gate the filter string ; rejected → drop the
+  // key (the element mounts at the identity filter instead).
+  let from = initial;
+  if (initial["filter"] !== undefined) {
+    const safe = sanitizeCssFilterString(initial["filter"]);
+    from = { ...initial };
+    if (safe === null) {
+      warnRejectedFilter("animate_initial.filter", nodeId);
+      delete from["filter"];
+    } else {
+      from["filter"] = safe;
+    }
+  }
   const animate: Record<string, number | string> = { ...base };
-  for (const key of Object.keys(initial)) {
+  for (const key of Object.keys(from)) {
     if (!(key in animate)) {
       animate[key] = INITIAL_IDENTITY[key] ?? 0;
     }
   }
-  return { initial, animate };
+  return { initial: from, animate };
 }
 
 /**
@@ -157,6 +237,8 @@ export function parseWireTransition(value: unknown): Transition | undefined {
     const out: SpringTransition = { kind: "spring" };
     if (typeof v.stiffness === "number") out.stiffness = v.stiffness;
     if (typeof v.damping === "number") out.damping = v.damping;
+    // LSML §6.2 — mass rides the same wire spring shape.
+    if (typeof v.mass === "number") out.mass = v.mass;
     return out;
   }
   return undefined;

package/src/index.ts

@@ -10,9 +10,22 @@ export type {
   LumencastTokenProvider,
   LumencastError,
   LumencastMetric,
+  LumencastDiagnostic,
   ErrorCode,
 } from "./types.js";
 
+// Anti-silent-drop diagnostics channel (ADR 001 §3.4, issue #34) —
+// hosts that render outside `mount()` (embedding the tree directly,
+// tooling, tests) can subscribe here ; `mount()` wires
+// `MountOptions.onDiagnostic` to the same channel.
+export {
+  addDiagnosticsHandler,
+  ANON_NODE_ID,
+  type RenderDiagnostic,
+  type DiagnosticHandler,
+} from "./render/diagnostics.js";
+export { PRIMITIVE_PROP_ALLOWLIST } from "./render/prop-allowlist.js";
+
 // Bundle types are useful for hosts that want to typecheck pre-compiled scenes.
 export type {
   RenderBundle,
@@ -21,4 +34,15 @@ export type {
   OperatorInput,
   ExternalAdapter,
   Asset,
+  BundleUrlResolver,
+} from "./render/bundle.js";
+
+// Profile gating (LSML 1.1 §17.3.1 / §17.5.1) — exported so hosts and the
+// compiler-side tooling can apply the same rule outside the fetch path, and
+// so the runtime "publishes the list of profiles it supports" per §17.3.1.
+export {
+  SUPPORTED_PROFILES,
+  BundleIncompatibleError,
+  isAuthoringProfile,
+  validateBundleProfiles,
 } from "./render/bundle.js";

package/src/mount.ts

@@ -11,6 +11,7 @@ import { createStore } from "./state/store.js";
 import { createBundleFetcher, type BundleFetcher, type RenderBundle } from "./render/bundle.js";
 import { WsClient, type ConnectionStatus, type TransportError } from "./transport/ws.js";
 import { validateOptions } from "./internal/validate-options.js";
+import { addDiagnosticsHandler } from "./render/diagnostics.js";
 import type { LumencastError, LumencastHandle, LumencastToken, MountOptions } from "./types.js";
 
 export function mount(options: MountOptions): LumencastHandle {
@@ -19,7 +20,10 @@ export function mount(options: MountOptions): LumencastHandle {
 
   const store = createStore();
   const baseUrl = deriveBaseUrl(options.serverUrl);
-  const bundleFetcher = createBundleFetcher({ baseUrl });
+  const bundleFetcher = createBundleFetcher({
+    baseUrl,
+    ...(options.resolveBundleUrl !== undefined ? { resolveUrl: options.resolveBundleUrl } : {}),
+  });
 
   const bundleSignal = signal<RenderBundle | null>(null);
   const statusSignal = signal<ConnectionStatus>("disconnected");
@@ -36,6 +40,12 @@ export function mount(options: MountOptions): LumencastHandle {
 
   let active = true;
 
+  // ADR 001 §3.4 (issue #34) — anti-silent-drop diagnostics are events
+  // surfaced to the host, never console logs in `broadcast` mode.
+  const removeDiagnosticsHandler = options.onDiagnostic
+    ? addDiagnosticsHandler(options.onDiagnostic)
+    : undefined;
+
   const ws = new WsClient({
     url: options.serverUrl,
     token: options.token,
@@ -110,6 +120,7 @@ export function mount(options: MountOptions): LumencastHandle {
     disconnect() {
       if (!active) return;
       active = false;
+      removeDiagnosticsHandler?.();
       ws.close();
       root.unmount();
     },

package/src/render/bind-animate.tsx

@@ -0,0 +1,370 @@
+// LSML 1.1 §6.3 `bindAnimate` — continuous interpolation toward a live
+// leaf value (ADR 001 §3.3, issue #33).
+//
+// Per binding, the hook subscribes the existing leaf-grain signal and
+// retargets a Framer motion value on change — NO remount, the DOM node
+// is identical before/after (RC#6). Scalar channels (§6.1) ride motion
+// values attached to a wrapping `motion.div` ; colour channels (§6.5)
+// are interpolated component-wise in sRGB through the strict shared
+// parser and flow back into the primitive's resolved prop (which
+// re-validates them — RC#11 belt and braces).
+//
+// Anti-DoS (Bastion RC#13) : deltas are coalesced per frame — one
+// retarget max per rAF per binding, whatever the producer's rate
+// (1 kHz tested in E2E). Retargets interrupt in-flight springs with
+// velocity carry (§6.2/§6.4 — framer preserves a motion value's
+// velocity when a spring animation is replaced ; no snap).
+//
+// R8 runtime half (issue #42) : `filter.blur` / `filter.brightness`
+// values arriving live re-pass the same caps as the compiler before
+// they may touch the composed CSS filter (see filter-clamp.ts).
+//
+// Stagger (§6.7) : inside a `repeat` iteration the FIRST animated
+// retarget per binding is delayed by the ambient StaggerContext delay ;
+// steady-state retargets are never delayed (a permanently-lagging gauge
+// would defeat the purpose of a live binding). Documented hypothesis —
+// the spec only constrains animation *starts*.
+
+import {
+  animate,
+  useMotionValue,
+  useTransform,
+  type AnimationPlaybackControls,
+  type MotionValue,
+  type MotionStyle,
+} from "framer-motion";
+import { effect } from "@preact/signals-react";
+import { useContext, useEffect, useMemo, useRef, useState } from "react";
+import type { Store } from "../state/store";
+import type { RenderNode } from "./bundle";
+import { scopedPath } from "./scope";
+import { StaggerContext } from "./stagger-context";
+import { toFramer, type FramerTransition, type Transition } from "../animate/transitions";
+import { createFrameCoalescer } from "../animate/frame-coalescer";
+import { clampFilterChannel, warnRejectedFilter } from "./filter-clamp";
+import { warnRejectedColor } from "./css-color";
+import { emitDiagnostic } from "./diagnostics";
+import { cssColorToRgba, mixRgba, serializeRgba, type Rgba } from "./color-interp";
+
+/** §6.5 colour-typed bindAnimate keys → the runtime prop name the
+ *  primitive reads (and re-validates through `parseCssColor`). */
+export const BIND_ANIMATE_COLOR_PROPS: Readonly<Record<string, string>> = {
+  "style.color": "colour",
+  fill: "fill",
+  background: "background",
+};
+
+/** Scalar motion channels a bindAnimate key drives. */
+type ScalarChannel = "opacity" | "x" | "y" | "scaleX" | "scaleY" | "rotate" | "blur" | "brightness";
+
+/**
+ * Validate + normalise one live bindAnimate value into per-channel
+ * numeric targets. Returns `null` on rejection (wrong JSON shape per
+ * §6.3, non-finite numbers, filter values outside the R8 caps when the
+ * channel rejects rather than clamps). A `null` keeps the last
+ * known-good target — the raw input never reaches a style.
+ *
+ * Exported pure for the hostile-delta fixture suite (issue #42).
+ */
+export function resolveScalarTargets(
+  key: string,
+  raw: unknown,
+): Partial<Record<ScalarChannel, number>> | null {
+  switch (key) {
+    case "opacity": {
+      const v = toFiniteScalar(raw);
+      if (v === null) return null;
+      return { opacity: v < 0 ? 0 : v > 1 ? 1 : v };
+    }
+    case "transform.translate": {
+      if (!Array.isArray(raw) || raw.length !== 2) return null;
+      const tx = toFiniteScalar(raw[0]);
+      const ty = toFiniteScalar(raw[1]);
+      if (tx === null || ty === null) return null;
+      return { x: tx, y: ty };
+    }
+    case "transform.scale": {
+      const s = toFiniteScalar(raw);
+      if (s !== null) return { scaleX: s, scaleY: s };
+      if (Array.isArray(raw) && raw.length === 2) {
+        const sx = toFiniteScalar(raw[0]);
+        const sy = toFiniteScalar(raw[1]);
+        if (sx === null || sy === null) return null;
+        return { scaleX: sx, scaleY: sy };
+      }
+      return null;
+    }
+    case "transform.rotate": {
+      const v = toFiniteScalar(raw);
+      if (v === null) return null;
+      return { rotate: v };
+    }
+    case "filter.blur": {
+      const v = clampFilterChannel("blur", raw);
+      return v === null ? null : { blur: v };
+    }
+    case "filter.brightness": {
+      const v = clampFilterChannel("brightness", raw);
+      return v === null ? null : { brightness: v };
+    }
+    default:
+      return null;
+  }
+}
+
+// ── IEEE-754 `-0` policy (R8 / PR #39 coherence, issue #33) ───────────
+// `-0 < 0` is FALSE, so a plain sign clamp lets -0 through. Uniform
+// rule : no -0 ever reaches a motion value or a style. Per channel :
+//   · opacity — the negative case CLAMPS to 0 (`-5 → 0`), so -0 follows
+//     the same line and normalises to +0 (rejecting -0 while clamping
+//     -5 would be incoherent within the channel) ;
+//   · translate / scale / rotate — negatives are valid values and
+//     `-0 == 0` is mathematically neutral, so -0 normalises to +0 (a
+//     producer computing `-x` at x = 0 must not be rejected into a
+//     stale last-good) ;
+//   · filter.blur / filter.brightness — REJECTED (null → last-good) by
+//     `clampFilterChannel` : the R8 gate treats any negative sign,
+//     including -0, as hostile input (compiler mirror, issues #39/#41
+//     — do not relax here).
+/** Finite-number gate + `-0 → +0` normalisation for the generic scalar
+ *  channels (filter channels go through `clampFilterChannel` instead). */
+function toFiniteScalar(v: unknown): number | null {
+  if (typeof v !== "number" || !Number.isFinite(v)) return null;
+  return Object.is(v, -0) ? 0 : v;
+}
+
+/** Default retarget transition when neither a per-leaf wire directive
+ *  nor a compiled `transitions` entry resolves : the §6.2 default
+ *  spring (stiffness 170, damping 26, mass 1). A spring is the only
+ *  curve with well-defined retarget semantics (velocity carry) — a
+ *  documented hypothesis, see the PR for issue #33. */
+export const DEFAULT_BIND_ANIMATE_TRANSITION: Transition = {
+  kind: "spring",
+  stiffness: 170,
+  damping: 26,
+  mass: 1,
+};
+
+/** node.transitions lookup key for each bindAnimate key (mirrors the
+ *  compiler's `transitionKeysForBindAnimate`). */
+function transitionLookupKey(key: string): string {
+  switch (key) {
+    case "opacity":
+      return "opacity";
+    case "transform.translate":
+      return "x";
+    case "transform.scale":
+      return "scale";
+    case "transform.rotate":
+      return "rotate";
+    case "filter.blur":
+    case "filter.brightness":
+      return "filter";
+    default:
+      return BIND_ANIMATE_COLOR_PROPS[key] ?? key;
+  }
+}
+
+export interface BindAnimateHandle {
+  /** Motion-value style for the wrapping `motion.div` — `null` when no
+   *  scalar channel is bound (no wrapper needed). */
+  motionStyle: MotionStyle | null;
+  /** Live-interpolated colour values, keyed by the primitive prop name
+   *  (`colour` / `fill` / `background`). Merged over `resolved`. */
+  colorProps: Record<string, string>;
+}
+
+const NO_COLORS: Record<string, string> = {};
+
+/**
+ * Drive a node's `animateBindings`. Must be called unconditionally
+ * (hook) ; cheap no-op when the node has no bindings.
+ */
+export function useBindAnimate(node: RenderNode, store: Store, scope: string): BindAnimateHandle {
+  const bindings = node.animateBindings;
+  const staggerDelayMs = useContext(StaggerContext);
+
+  // Fixed channel set — created unconditionally so hook order is
+  // stable ; unbound channels stay at their identity value.
+  const opacity = useMotionValue(1);
+  const x = useMotionValue(0);
+  const y = useMotionValue(0);
+  const scaleX = useMotionValue(1);
+  const scaleY = useMotionValue(1);
+  const rotate = useMotionValue(0);
+  const blur = useMotionValue(0);
+  const brightness = useMotionValue(1);
+  // Composed CSS filter — both functions always present so framer
+  // interpolates structurally-identical lists (same form as the
+  // compiler emits, clamped per R8).
+  const filter = useTransform(
+    [blur, brightness] as [MotionValue<number>, MotionValue<number>],
+    ([b, br]: number[]) => `blur(${b}px) brightness(${br})`,
+  );
+
+  const [colorProps, setColorProps] = useState<Record<string, string>>(NO_COLORS);
+
+  const channels = useRef<Record<ScalarChannel, MotionValue<number>>>({
+    opacity,
+    x,
+    y,
+    scaleX,
+    scaleY,
+    rotate,
+    blur,
+    brightness,
+  });
+
+  useEffect(() => {
+    if (!bindings || Object.keys(bindings).length === 0) return;
+
+    const mvs = channels.current;
+    const controls = new Map<string, AnimationPlaybackControls>();
+    const colorState = new Map<string, { current: Rgba }>();
+    const animatedOnce = new Set<string>();
+    let mounted = false;
+
+    const transitionFor = (key: string, fullPath: string): FramerTransition => {
+      const live = store.transitionSignal(fullPath).peek();
+      const declared = live ?? node.transitions?.[transitionLookupKey(key)];
+      const base = toFramer(declared ?? DEFAULT_BIND_ANIMATE_TRANSITION);
+      // §6.7 — stagger delays only the first animated retarget.
+      if (staggerDelayMs > 0 && !animatedOnce.has(key)) {
+        return { ...base, delay: staggerDelayMs / 1000 } as FramerTransition;
+      }
+      return base;
+    };
+
+    const dispatch = (key: string, value: unknown, instant: boolean): void => {
+      const colorProp = BIND_ANIMATE_COLOR_PROPS[key];
+      const fullPath = scopedPath(scope, bindings[key] as string);
+
+      if (colorProp !== undefined) {
+        // §6.5 — canonicalise BOTH endpoints through the strict parser
+        // before interpolating ; never a raw string.
+        const end = cssColorToRgba(value);
+        if (end === null) {
+          warnRejectedColor(`bindAnimate.${key}`, node.id);
+          return;
+        }
+        const prev = colorState.get(key);
+        if (instant || prev === undefined) {
+          colorState.set(key, { current: end });
+          setColorProps((p) => ({ ...p, [colorProp]: serializeRgba(end) }));
+          return;
+        }
+        const start = prev.current;
+        const tx = transitionFor(key, fullPath);
+        animatedOnce.add(key);
+        controls.get(`color:${key}`)?.stop();
+        controls.set(
+          `color:${key}`,
+          animate(0, 1, {
+            ...tx,
+            onUpdate: (t) => {
+              const mixed = mixRgba(start, end, t);
+              prev.current = mixed;
+              setColorProps((p) => ({ ...p, [colorProp]: serializeRgba(mixed) }));
+            },
+          }),
+        );
+        return;
+      }
+
+      const targets = resolveScalarTargets(key, value);
+      if (targets === null) {
+        // R9 — the offending value is never logged.
+        if (key.startsWith("filter.")) warnRejectedFilter(`bindAnimate.${key}`, node.id);
+        else warnRejectedBindValue(key, node.id);
+        return;
+      }
+      if (instant) {
+        // §6.3.1 — on mount the rendered state initialises from the
+        // bound value instantly (there is no previous state).
+        for (const [ch, v] of Object.entries(targets)) {
+          mvs[ch as ScalarChannel].jump(v as number);
+        }
+        return;
+      }
+      const tx = transitionFor(key, fullPath);
+      animatedOnce.add(key);
+      for (const [ch, v] of Object.entries(targets)) {
+        // framer's animate() replaces any in-flight animation on the
+        // motion value and seeds the new spring with the value's
+        // current velocity — §6.2 velocity carry, no snap.
+        controls.set(ch, animate(mvs[ch as ScalarChannel], v as number, tx));
+      }
+    };
+
+    // RC#13 — one retarget max per rAF per binding.
+    const coalescer = createFrameCoalescer((key, value) => dispatch(key, value, false));
+
+    const disposers = Object.entries(bindings).map(([key, path]) =>
+      effect(() => {
+        const v = store.signal(scopedPath(scope, path)).value;
+        if (v === undefined) return;
+        if (!mounted) dispatch(key, v, true);
+        else coalescer.push(key, v);
+      }),
+    );
+    mounted = true;
+
+    return () => {
+      for (const d of disposers) d();
+      coalescer.dispose();
+      for (const c of controls.values()) c.stop();
+    };
+    // node/store/scope identity changes re-wire every subscription ;
+    // staggerDelayMs is stable per repeat iteration.
+  }, [node, bindings, store, scope, staggerDelayMs]);
+
+  const motionStyle = useMemo<MotionStyle | null>(() => {
+    if (!bindings) return null;
+    const style: MotionStyle = {};
+    let any = false;
+    for (const key of Object.keys(bindings)) {
+      switch (key) {
+        case "opacity":
+          style.opacity = opacity;
+          any = true;
+          break;
+        case "transform.translate":
+          style.x = x;
+          style.y = y;
+          any = true;
+          break;
+        case "transform.scale":
+          style.scaleX = scaleX;
+          style.scaleY = scaleY;
+          any = true;
+          break;
+        case "transform.rotate":
+          style.rotate = rotate;
+          any = true;
+          break;
+        case "filter.blur":
+        case "filter.brightness":
+          style.filter = filter;
+          any = true;
+          break;
+        default:
+          break; // colour keys flow through colorProps, not the wrapper
+      }
+    }
+    if (!any) return null;
+    style.willChange = "transform, opacity, filter";
+    return style;
+  }, [bindings, opacity, x, y, scaleX, scaleY, rotate, filter]);
+
+  return { motionStyle, colorProps };
+}
+
+/** R9 diagnostic — shape-invalid bindAnimate value (non-filter
+ *  channels). Structured event, value withheld. */
+function warnRejectedBindValue(key: string, nodeId?: string): void {
+  emitDiagnostic(
+    nodeId,
+    `bindAnimate.${key}`,
+    "rejected bound value : JSON shape does not match the property type (LSML §6.3)",
+  );
+}