@lumencast/runtime 0.1.0

package/src/render/primitives/instance.tsx

@@ -0,0 +1,70 @@
+// LSML 1.1 §4.9 — `instance` primitive (composite-instance reuse).
+//
+// Mounts a sub-scene by `scene_id` + `scene_version`. The sub-scene's
+// state is exposed to its tree under the `__params.*` reserved
+// namespace ; resolution happens via the runtime's bundle fetcher.
+//
+// This implementation is a SCAFFOLD : the visual slot is rendered
+// (size/position honoured) but the sub-tree is replaced by a
+// "deferred load" placeholder until the async bundle-fetch path is
+// wired. The composite-reuse rendering is the next iteration's work.
+//
+// What this primitive does today :
+//   - parse scene_id, scene_version, params, fit, size, position
+//   - reserve the slot in the parent layout
+//   - log a one-time warning so authors know it's a scaffold
+//
+// What it does NOT do (yet) :
+//   - fetch the inner bundle via the runtime's bundle resolver
+//   - render the inner tree with __params.* injected into the store
+//   - cycle detection (LSML 1.1 §4.9.2) — depth-8 limit applied at the
+//     resolver layer rather than the renderer
+
+import type { ReactElement } from "react";
+import type { PrimitiveProps } from "./index";
+
+const warned = new Set<string>();
+
+export function Instance({ resolved }: 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);
+    }
+    return null;
+  }
+
+  // One-time DEV warning 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 size = resolved.size as { w?: number; h?: number } | undefined;
+  const position = resolved.position as { x?: number; y?: number } | undefined;
+
+  return (
+    <div
+      data-lumencast-instance={sceneId}
+      data-lumencast-version={sceneVersion}
+      style={{
+        position: position ? "absolute" : "relative",
+        left: position?.x,
+        top: position?.y,
+        width: size?.w,
+        height: size?.h,
+        outline: import.meta.env.DEV ? "1px dashed rgba(255,180,0,0.5)" : "none",
+        boxSizing: "border-box",
+      }}
+    />
+  );
+}

package/src/render/primitives/media.tsx

@@ -0,0 +1,28 @@
+import type { PrimitiveProps } from "./index";
+
+/** Embedded video. `src`, `loop`, `mute`, `autoplay`. Audio is muted
+ *  by default — broadcast audio is Pulsar-side, not from the browser
+ *  source. */
+export function Media({ resolved }: PrimitiveProps) {
+  const src = resolved.src as string | undefined;
+  if (!src) return null;
+  const loop = (resolved.loop as boolean | undefined) ?? true;
+  const mute = (resolved.mute as boolean | undefined) ?? true;
+  const autoplay = (resolved.autoplay as boolean | undefined) ?? true;
+  const fit = (resolved.fit as string | undefined) ?? "cover";
+
+  return (
+    <video
+      src={src}
+      autoPlay={autoplay}
+      loop={loop}
+      muted={mute}
+      playsInline
+      style={{
+        width: "100%",
+        height: "100%",
+        objectFit: fit as React.CSSProperties["objectFit"],
+      }}
+    />
+  );
+}

package/src/render/primitives/shape.tsx

@@ -0,0 +1,135 @@
+import { motion } from "framer-motion";
+import type { ReactElement } from "react";
+import type { PrimitiveProps } from "./index";
+import { toFramer } from "../../animate/transitions";
+import { parseFills, renderFill } from "../fill";
+
+interface StrokeSpec {
+  color?: string;
+  width?: number;
+}
+
+/** Rectangle / circle / line. Renders as SVG so stroke + fill behave
+ *  predictably across hosts. Opacity animatable.
+ *
+ *  LSML 1.1 §4.6 + §4.12 add `fills[]` / `strokes[]` arrays as the
+ *  preferred way to declare multi-layer fills with linear/radial
+ *  gradients. The legacy single `fill` / `stroke` props remain
+ *  accepted for 1.0 bundles ; when both are present the array form
+ *  wins (the spec forbids mixing, but we tolerate to ease migration).
+ */
+export function Shape({ resolved, transitionFor }: PrimitiveProps) {
+  const kind = (resolved.kind as string | undefined) ?? "rect";
+  const legacyFill = (resolved.fill as string | undefined) ?? "transparent";
+  const legacyStroke = (resolved.stroke as string | undefined) ?? "transparent";
+  const legacyStrokeWidth = numberOr(resolved.stroke_width, 0);
+  const width = numberOr(resolved.width, 100);
+  const height = numberOr(resolved.height, 100);
+  const radius = numberOr(resolved.radius, 0);
+  const opacity = numberOr(resolved.opacity, 1);
+
+  const tx = transitionFor("opacity");
+  const transition = toFramer(tx);
+
+  // LSML 1.1 §4.6 — `fills[]` is the preferred multi-fill form. Fall
+  // back to the singular `fill` for 1.0 bundles.
+  const fills = parseFills(resolved.fills);
+  const strokes = parseStrokes(resolved.strokes);
+
+  // Each fill compiles to a (defs, ref) pair. We render the shape
+  // outline once per fill, layered top-to-bottom (first entry → on
+  // top, per §4.12). The defs are aggregated for a single <defs>.
+  const fillRenders = fills.map(renderFill);
+  const allDefs = fillRenders.flatMap((r) => r.defs);
+  const fillRefs = fillRenders.length > 0 ? fillRenders.map((r) => r.ref) : [legacyFill];
+
+  // Strokes : same layered approach, but solid colours only (gradient
+  // strokes are out of scope for §4.6 1.1). Each stroke is rendered
+  // as an additional pass over the same shape outline.
+  const strokeLayers =
+    strokes.length > 0
+      ? strokes.map((s) => ({ color: s.color ?? "transparent", width: s.width ?? 0 }))
+      : [{ color: legacyStroke, width: legacyStrokeWidth }];
+
+  // Stack order : fillRefs are emitted top-to-bottom per §4.12. SVG
+  // paints later siblings on top, so we reverse here so the first
+  // entry in fills[] ends up rendered last (visually on top).
+  const stackedFills = [...fillRefs].reverse();
+  const stackedStrokes = [...strokeLayers].reverse();
+
+  const renderShape = (
+    fill: string,
+    stroke: { color: string; width: number },
+    keyPrefix: string,
+  ): ReactElement => {
+    if (kind === "circle") {
+      return (
+        <circle
+          key={keyPrefix}
+          cx={width / 2}
+          cy={height / 2}
+          r={Math.min(width, height) / 2 - stroke.width / 2}
+          fill={fill}
+          stroke={stroke.color}
+          strokeWidth={stroke.width}
+        />
+      );
+    }
+    if (kind === "line") {
+      return (
+        <line
+          key={keyPrefix}
+          x1="0"
+          y1={height / 2}
+          x2={width}
+          y2={height / 2}
+          stroke={stroke.color || fill}
+          strokeWidth={stroke.width || 1}
+        />
+      );
+    }
+    // rect default
+    return (
+      <rect
+        key={keyPrefix}
+        x={stroke.width / 2}
+        y={stroke.width / 2}
+        width={Math.max(0, width - stroke.width)}
+        height={Math.max(0, height - stroke.width)}
+        rx={radius}
+        ry={radius}
+        fill={fill}
+        stroke={stroke.color}
+        strokeWidth={stroke.width}
+      />
+    );
+  };
+
+  return (
+    <motion.svg
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      animate={{ opacity }}
+      transition={transition}
+      style={{ willChange: "opacity" }}
+    >
+      {allDefs.length > 0 && <defs>{allDefs}</defs>}
+      {stackedFills.map((ref, i) =>
+        renderShape(ref, { color: "transparent", width: 0 }, `fill-${i}`),
+      )}
+      {stackedStrokes.map((s, i) => renderShape("none", s, `stroke-${i}`))}
+    </motion.svg>
+  );
+}
+
+function parseStrokes(value: unknown): StrokeSpec[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter(
+    (v): v is StrokeSpec => typeof v === "object" && v !== null && ("color" in v || "width" in v),
+  );
+}
+
+function numberOr(v: unknown, fallback: number): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}

package/src/render/primitives/stack.tsx

@@ -0,0 +1,48 @@
+import type { CSSProperties } from "react";
+import type { PrimitiveProps } from "./index";
+
+/** Vertical or horizontal flex container. Layout-only — bindings
+ *  here are unusual but tolerated.
+ *
+ *  LSML 1.1 §4.1 adds `wrap` (boolean) and `crossGap` (number) :
+ *    - wrap: true sets `flex-wrap: wrap` so children flow onto the
+ *      next row / column when they overflow the main axis.
+ *    - crossGap is the spacing between rows / columns when wrapping.
+ *      Mapped to CSS `row-gap` (horizontal stack) or `column-gap`
+ *      (vertical stack). Ignored when `wrap` is false.
+ */
+export function Stack({ resolved, children }: PrimitiveProps) {
+  const direction = (resolved.direction as string) ?? "vertical";
+  const gap = numberOr(resolved.gap, 0);
+  const wrap = resolved.wrap === true;
+  const crossGap = numberOr(resolved.crossGap, 0);
+  const align = (resolved.align as string) ?? "stretch";
+  const justify = (resolved.justify as string) ?? "flex-start";
+  const isHorizontal = direction === "horizontal";
+
+  const style: CSSProperties = {
+    display: "flex",
+    flexDirection: isHorizontal ? "row" : "column",
+    alignItems: align,
+    justifyContent: justify,
+  };
+
+  if (wrap) {
+    style.flexWrap = "wrap";
+    if (isHorizontal) {
+      style.columnGap = gap;
+      style.rowGap = crossGap;
+    } else {
+      style.rowGap = gap;
+      style.columnGap = crossGap;
+    }
+  } else {
+    style.gap = gap;
+  }
+
+  return <div style={style}>{children}</div>;
+}
+
+function numberOr(v: unknown, fallback: number): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}

package/src/render/primitives/text.tsx

@@ -0,0 +1,38 @@
+import { motion } from "framer-motion";
+import type { PrimitiveProps } from "./index";
+import { toFramer } from "../../animate/transitions";
+
+/** Text leaf. Value renders as the displayed string ; style props
+ *  cover size / weight / colour / alignment. Opacity is animated when
+ *  a transition is declared on `opacity` or `value`. */
+export function Text({ resolved, transitionFor }: PrimitiveProps) {
+  const value = resolved.value === undefined ? "" : String(resolved.value);
+  const size = (resolved.size as string | number | undefined) ?? "1rem";
+  const weight = (resolved.weight as number | undefined) ?? 400;
+  const colour = (resolved.colour as string | undefined) ?? "currentColor";
+  const align = (resolved.align as string | undefined) ?? "start";
+  const opacity = numberOr(resolved.opacity, 1);
+
+  const tx = transitionFor("opacity") ?? transitionFor("value");
+
+  return (
+    <motion.span
+      style={{
+        display: "inline-block",
+        fontSize: size,
+        fontWeight: weight,
+        color: colour,
+        textAlign: align as React.CSSProperties["textAlign"],
+        willChange: "opacity",
+      }}
+      animate={{ opacity }}
+      transition={toFramer(tx)}
+    >
+      {value}
+    </motion.span>
+  );
+}
+
+function numberOr(v: unknown, fallback: number): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}

package/src/render/scope.tsx

@@ -0,0 +1,27 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+/** Path-scope context. Children inside a `repeat` get a `prefix` that
+ *  is prepended to their declared bindings, so a single template can
+ *  bind to per-item paths like `items.{i}.score`. */
+const PathScopeContext = createContext<string>("");
+
+export function PathScopeProvider({ prefix, children }: { prefix: string; children: ReactNode }) {
+  const parent = useContext(PathScopeContext);
+  const next = parent ? `${parent}.${prefix}` : prefix;
+  return <PathScopeContext.Provider value={next}>{children}</PathScopeContext.Provider>;
+}
+
+/** Returns the current path prefix, or "" if there is no scope. */
+export function usePathScope(): string {
+  return useContext(PathScopeContext);
+}
+
+/** Resolve a binding path under the current scope. */
+export function scopedPath(prefix: string, path: string): string {
+  if (!prefix) return path;
+  // Path may itself start with a literal prefix (e.g. `__system.*`),
+  // which should NOT be scoped — only paths that are clearly relative
+  // get prefixed.
+  if (path.startsWith("__")) return path;
+  return `${prefix}.${path}`;
+}

package/src/render/stagger-context.tsx

@@ -0,0 +1,24 @@
+// LSML 1.1 §6.7 — stagger context.
+//
+// `repeat.stagger_ms` produces wave-like reveals : iteration N's
+// animations start `N * stagger_ms` after iteration 0. The Repeat
+// renderer computes the per-iteration delay and threads it through
+// React context so KeyframePlayer (and future animate-aware primitives)
+// can pick it up without per-primitive wiring.
+
+import { createContext } from "react";
+
+/** Per-iteration stagger delay in milliseconds. `0` means no offset
+ *  (the implicit default outside a staggered repeat). */
+export const StaggerContext = createContext<number>(0);
+
+/** Spec hint : runtimes MAY cap effective stagger to avoid pathological
+ *  wait times on large lists. We cap at 2 s. */
+export const STAGGER_CAP_MS = 2000;
+
+/** Compute the effective per-iteration delay, applying the runtime cap. */
+export function computeStaggerDelayMs(index: number, staggerMs: number): number {
+  if (staggerMs <= 0) return 0;
+  const raw = index * staggerMs;
+  return raw > STAGGER_CAP_MS ? STAGGER_CAP_MS : raw;
+}

package/src/render/tree.tsx

@@ -0,0 +1,182 @@
+// Recursive tree renderer — resolves bindings, dispatches to
+// primitives, handles `repeat` specially.
+
+import { useSignals } from "@preact/signals-react/runtime";
+import { useMemo, type ReactNode } from "react";
+import type { Store } from "../state/store";
+import type { Transition } from "../animate/transitions";
+import { PRIMITIVES } from "./primitives";
+import { PathScopeProvider, scopedPath, usePathScope } from "./scope";
+import type { RenderNode } from "./bundle";
+import { UniversalWrapper, type SizingMode } from "./universal-wrapper";
+import { KeyframePlayer } from "./keyframe-player";
+import { StaggerContext, computeStaggerDelayMs } from "./stagger-context";
+
+export interface TreeProps {
+  node: RenderNode;
+  store: Store;
+}
+
+export function Tree({ node, store }: TreeProps): ReactNode {
+  if (node.kind === "repeat") {
+    return <Repeat node={node} store={store} />;
+  }
+  return <Node node={node} store={store} />;
+}
+
+function Node({ node, store }: TreeProps): ReactNode {
+  // useSignals() lets the surrounding component subscribe to any
+  // signal read during render. Each leaf path has its own signal so
+  // re-renders only fire on touched paths.
+  useSignals();
+  const scope = usePathScope();
+
+  // Hooks must run unconditionally — the early-return for unknown
+  // kinds happens *after* every hook has fired.
+  const resolved = useMemo(
+    () => resolveProps(node, store, scope),
+    // We re-build per render — signals re-render cheaply, and the
+    // resolution itself is O(bindings) which is small. The memo is a
+    // micro-optimisation to keep object identity stable across renders
+    // when the inputs haven't changed.
+    [node, store, scope, ...readBindingValues(node, store, scope)],
+  );
+
+  const Primitive = PRIMITIVES[node.kind as keyof typeof PRIMITIVES];
+  if (!Primitive) {
+    if (import.meta.env.DEV) {
+      console.warn(`[lumencast] unknown render kind : ${node.kind}`);
+    }
+    return null;
+  }
+
+  // LSDP/1.1 §3.2.2 — a per-leaf transition on the most recent delta
+  // takes precedence over the bundle-level default. Only bound props
+  // can carry a wire transition (a static prop never moves). Snapshots
+  // clear the directive, so the bundle default reapplies after a reset.
+  //
+  // We resolve here in the parent's render (useSignals() above tracks
+  // these reads) rather than inside the primitive's callback — that way
+  // a transition signal change re-renders this Node, which in turn re-
+  // renders the primitive with the new transition prop.
+  const liveTransitions: Record<string, Transition | undefined> = {};
+  if (node.bindings) {
+    for (const [key, path] of Object.entries(node.bindings)) {
+      const ts = store.transitionSignal(scopedPath(scope, path)).value;
+      if (ts !== undefined) liveTransitions[key] = ts;
+    }
+  }
+  const transitionFor = (key: string): Transition | undefined => {
+    if (key in liveTransitions) return liveTransitions[key];
+    return node.transitions?.[key];
+  };
+
+  const children = node.children?.map((child, idx) => (
+    <Tree key={child.id ?? idx} node={child} store={store} />
+  ));
+
+  // LSML 1.1 §5.4 — universal props applied uniformly across all
+  // primitives. Pulled out of `resolved` so primitives can ignore
+  // them ; the wrapper composes with whatever transform/opacity the
+  // primitive's own framer-motion may apply.
+  const universal = {
+    visible: typeof resolved.visible === "boolean" ? resolved.visible : undefined,
+    opacity:
+      typeof resolved.universal_opacity === "number" ? resolved.universal_opacity : undefined,
+    rotation: typeof resolved.rotation === "number" ? resolved.rotation : undefined,
+    sizing: extractSizing(resolved.sizing),
+  };
+
+  const body = (
+    <UniversalWrapper {...universal}>
+      <Primitive resolved={resolved} transitionFor={transitionFor}>
+        {children}
+      </Primitive>
+    </UniversalWrapper>
+  );
+
+  // LSML 1.1 §6.6 — when a primitive declares keyframes, wrap the
+  // rendered subtree in a player that drives framer-motion through the
+  // step path. The player handles replay-on-key-change and reads any
+  // ambient stagger delay from StaggerContext (§6.7).
+  if (node.keyframes) {
+    return (
+      <KeyframePlayer keyframes={node.keyframes} store={store}>
+        {body}
+      </KeyframePlayer>
+    );
+  }
+  return body;
+}
+
+function extractSizing(value: unknown): { x?: SizingMode; y?: SizingMode } | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const obj = value as { x?: unknown; y?: unknown };
+  const out: { x?: SizingMode; y?: SizingMode } = {};
+  if (obj.x === "fixed" || obj.x === "hug" || obj.x === "fill") out.x = obj.x;
+  if (obj.y === "fixed" || obj.y === "hug" || obj.y === "fill") out.y = obj.y;
+  return out.x !== undefined || out.y !== undefined ? out : undefined;
+}
+
+function Repeat({ node, store }: TreeProps): ReactNode {
+  useSignals();
+  const scope = usePathScope();
+
+  const itemsBinding = node.bindings?.items;
+  const items =
+    itemsBinding === undefined
+      ? []
+      : ((store.signal(scopedPath(scope, itemsBinding)).value as unknown[] | undefined) ?? []);
+  if (!Array.isArray(items)) return null;
+
+  const template = node.children?.[0];
+  if (!template) return null;
+
+  // LSML 1.1 §6.7 — `stagger_ms` produces wave-like reveals across
+  // iterations. We compute the per-iteration delay (capped) and feed
+  // it to descendants via StaggerContext so the KeyframePlayer (and
+  // future animate-aware primitives) can pick it up without per-
+  // iteration scripting. `stagger_ms: 0` (or unset) is a no-op.
+  const staggerMs = typeof node.stagger_ms === "number" ? node.stagger_ms : 0;
+
+  return (
+    <>
+      {items.map((_item, idx) => {
+        const delayMs = computeStaggerDelayMs(idx, staggerMs);
+        const tree = (
+          <PathScopeProvider key={idx} prefix={`${itemsBinding ?? ""}.${idx}`}>
+            <Tree node={template} store={store} />
+          </PathScopeProvider>
+        );
+        if (delayMs <= 0) return tree;
+        return (
+          <StaggerContext.Provider key={idx} value={delayMs}>
+            {tree}
+          </StaggerContext.Provider>
+        );
+      })}
+    </>
+  );
+}
+
+function resolveProps(node: RenderNode, store: Store, scope: string): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...(node.props ?? {}) };
+  if (node.bindings) {
+    for (const [propKey, path] of Object.entries(node.bindings)) {
+      const fullPath = scopedPath(scope, path);
+      out[propKey] = store.signal(fullPath).value;
+    }
+  }
+  return out;
+}
+
+/** Helper for the useMemo deps array — read each bound signal so the
+ *  memo invalidates when any binding moves. */
+function readBindingValues(node: RenderNode, store: Store, scope: string): unknown[] {
+  if (!node.bindings) return [];
+  const values: unknown[] = [];
+  for (const path of Object.values(node.bindings)) {
+    values.push(store.signal(scopedPath(scope, path)).value);
+  }
+  return values;
+}

package/src/render/universal-wrapper.tsx

@@ -0,0 +1,95 @@
+// Universal-props wrapper (LSML 1.1 §5.4).
+//
+// Every primitive renders inside this wrapper, which applies the four
+// universal props uniformly :
+//
+//   - `visible: false` → display: none (slot collapses in flex layouts)
+//   - `opacity` → CSS opacity, multiplicative with whatever animation
+//     a primitive may apply via framer-motion (browsers compose them)
+//   - `rotation` → CSS transform: rotate(<deg>)
+//   - `sizing.x`/`sizing.y` → flex shorthand on the wrapping div, lets
+//     a primitive participate in its parent flex layout's auto-sizing
+//
+// `bindUniversal` is resolved by the Tree renderer before the wrapper
+// sees its values, so this component only deals with concrete numbers
+// and booleans.
+
+import type { ReactNode, CSSProperties } from "react";
+
+export type SizingMode = "fixed" | "hug" | "fill";
+
+export interface UniversalProps {
+  visible?: boolean;
+  opacity?: number;
+  rotation?: number;
+  sizing?: { x?: SizingMode; y?: SizingMode };
+}
+
+export interface UniversalWrapperProps extends UniversalProps {
+  children: ReactNode;
+}
+
+/**
+ * Maps a SizingMode onto a flex shorthand. Per LSML 1.1 §5.4.1 :
+ *   - fixed : the primitive honours its declared size verbatim
+ *   - hug   : the primitive shrinks to its intrinsic content size
+ *   - fill  : the primitive grows to fill available space
+ */
+function flexFor(mode: SizingMode | undefined): string | undefined {
+  switch (mode) {
+    case "fixed":
+      return "0 0 auto";
+    case "hug":
+      return "0 1 auto";
+    case "fill":
+      return "1 1 auto";
+    default:
+      return undefined;
+  }
+}
+
+export function UniversalWrapper({
+  visible,
+  opacity,
+  rotation,
+  sizing,
+  children,
+}: UniversalWrapperProps) {
+  if (visible === false) {
+    return null; // slot collapses in flex/grid layouts (§5.4)
+  }
+
+  // No-op fast path — when no universal props are set, render children
+  // directly. Lets simple bundles avoid an extra DOM node per primitive.
+  const hasOpacity = typeof opacity === "number" && opacity !== 1;
+  const hasRotation = typeof rotation === "number" && rotation !== 0;
+  const hasSizing = sizing?.x !== undefined || sizing?.y !== undefined;
+  if (!hasOpacity && !hasRotation && !hasSizing) {
+    return <>{children}</>;
+  }
+
+  const style: CSSProperties = {};
+  if (hasOpacity) style.opacity = opacity;
+  if (hasRotation) style.transform = `rotate(${rotation}deg)`;
+
+  // sizing.x / sizing.y map to flex / row-flex behaviour. The
+  // x-axis applies along the main axis of a horizontal stack ; the
+  // y-axis along a vertical stack. We emit `flex` (covers both via
+  // CSS's flex-direction) and rely on the parent stack for orientation.
+  if (hasSizing) {
+    const x = flexFor(sizing?.x);
+    const y = flexFor(sizing?.y);
+    // Emit a single flex declaration when both axes agree, otherwise
+    // ship explicit grow/shrink/basis based on the dominant intent.
+    if (x === y && x !== undefined) {
+      style.flex = x;
+    } else {
+      // Heuristic : honour x for horizontal stacks (most common in
+      // broadcast UIs). Renderer doesn't know the parent's axis here ;
+      // a future iteration could thread that through context.
+      style.flex = x ?? y;
+    }
+  }
+
+  return <div style={style}>{children}</div>;
+}

package/src/state/apply-delta.ts

@@ -0,0 +1,24 @@
+import { batch } from "@preact/signals-react";
+import type { DeltaFrame } from "@lumencast/protocol";
+import type { Store } from "./store.js";
+import { parseWireTransition } from "../animate/transitions";
+
+/** Apply an LSDP/1 delta. All patches in the frame land in a single signals
+ *  batch — components reading multiple paths see them flip in one render pass.
+ *
+ *  LSDP/1.1 §3.2.2 — a patch may carry a `transition` directive overriding
+ *  the bundle-level default for the next animation cycle on that leaf. We
+ *  thread it through the store so the renderer reads the correct directive
+ *  alongside the new value. */
+export function applyDelta(store: Store, frame: DeltaFrame): void {
+  batch(() => {
+    for (const patch of frame.patches) {
+      const transition = parseWireTransition(patch.transition);
+      if (transition !== undefined) {
+        store.setWithTransition(patch.path, patch.value, transition);
+      } else {
+        store.set(patch.path, patch.value);
+      }
+    }
+  });
+}