@lumencast/runtime 0.1.0

package/src/render/bundle.ts

@@ -0,0 +1,208 @@
+// Render bundle — the runtime's flat, pre-compiled representation of a scene.
+//
+// The bundle is content-addressed by `scene_version` (sha256 of the
+// canonical JSON form). Lumencast fetches it once per `scene_version` and
+// caches forever; the server serves it with long-TTL immutable cache headers.
+//
+// Note on shape: this `RenderBundle` is the flat, runtime-internal form. The
+// canonical *authoring* format (LSML 1.0, see lumencast-protocol/spec/LSML-1.md)
+// uses inline `bind: { value: "path" }` per primitive instead of a `bindings`
+// map. A compiler step (forthcoming `@lumencast/compiler`) will translate
+// LSML 1.0 → RenderBundle. For now, callers who want to feed an LSML 1.0
+// bundle pre-compile or use a hand-rolled adapter.
+
+import type { Transition } from "../animate/transitions.js";
+import type { Keyframes } from "../animate/keyframes.js";
+
+// --- bundle shape ----------------------------------------------------
+
+export type RenderKind =
+  | "stack"
+  | "grid"
+  | "frame"
+  | "text"
+  | "image"
+  | "shape"
+  | "media"
+  | "repeat"
+  | "instance";
+
+export interface RenderNode {
+  kind: RenderKind;
+  /** Stable identifier for keyed reconciliation. */
+  id?: string;
+  /** Static props (frozen at build/compile time). */
+  props?: Record<string, unknown>;
+  /** Prop name → state path. The render layer subscribes the path's signal
+   *  and applies the value to the named prop on each change. */
+  bindings?: Record<string, string>;
+  /** Default transition per bound prop. Aligns with LSML 1.0 §6 `animate`
+   *  directives. The runtime applies these as CSS transitions / Framer Motion
+   *  configs at render time. */
+  transitions?: Record<string, Transition>;
+  /** LSML 1.1 §6.6 — multi-step keyframe sequence played on mount or
+   *  whenever `keyframes.key` (LeafPath) changes. Coexists with
+   *  `transitions` ; the runtime applies whichever was last triggered
+   *  (no blending — see §6.6 last paragraph). */
+  keyframes?: Keyframes;
+  /** LSML 1.1 §6.7 — only meaningful on `repeat`. Each iteration's
+   *  animations start `index * stagger_ms` after iteration 0. */
+  stagger_ms?: number;
+  /** Children — already-inlined primitives only. */
+  children?: RenderNode[];
+}
+
+export type OperatorInputType =
+  | "boolean"
+  | "number"
+  | "text"
+  | "select"
+  | "enum"
+  | "path-ref"
+  | "colour"
+  | "duration";
+
+export interface OperatorInput {
+  path: string;
+  label: string;
+  type: OperatorInputType;
+  default?: unknown;
+  group?: string;
+  writable_by?: string[];
+  [extra: string]: unknown;
+}
+
+export interface ExternalAdapter {
+  key: string;
+  label: string;
+  kind: string;
+  target_paths: string[];
+  [extra: string]: unknown;
+}
+
+export interface Asset {
+  id: string;
+  url: string;
+  kind: string;
+  [extra: string]: unknown;
+}
+
+export interface RenderBundle {
+  scene_version: string;
+  root: RenderNode;
+  operator_inputs?: OperatorInput[];
+  external_adapters?: ExternalAdapter[];
+  assets?: Asset[];
+  /** LSML 1.1 §17.3 — capability profiles required for correct rendering.
+   * Each entry is a `<vendor>.<name>-<version>` string. The runtime
+   * checks every entry against its supported list ; an unrecognised
+   * profile raises BUNDLE_INCOMPATIBLE per §17.3.1. */
+  profiles?: string[];
+}
+
+/**
+ * Profiles the JS runtime advertises support for. Bundle authors who
+ * declare `profiles: [...]` get a hard `BUNDLE_INCOMPATIBLE` rejection
+ * when any entry is not in this set (LSML 1.1 §17.3.1).
+ *
+ * 1.1 ships with no standard profiles ; future minors / vendor specs
+ * register here. The `x-lumencast.color-srgb-1.0` entry is the
+ * default-color-space marker ; bundles that opt into a perceptual
+ * space (OKLCH) would request a different profile and currently
+ * reject.
+ */
+export const SUPPORTED_PROFILES: ReadonlySet<string> = new Set<string>([
+  "x-lumencast.color-srgb-1.0",
+]);
+
+export class BundleIncompatibleError extends Error {
+  public readonly code = "BUNDLE_INCOMPATIBLE" as const;
+  public readonly unsupportedProfiles: string[];
+  constructor(unsupportedProfiles: string[]) {
+    super(
+      `BUNDLE_INCOMPATIBLE: profile(s) not supported by this runtime: ${unsupportedProfiles.join(
+        ", ",
+      )}`,
+    );
+    this.name = "BundleIncompatibleError";
+    this.unsupportedProfiles = unsupportedProfiles;
+  }
+}
+
+/** Validate a bundle's `profiles[]` against the runtime's supported
+ * set. Throws `BundleIncompatibleError` listing every offending entry
+ * when at least one is not supported. */
+export function validateBundleProfiles(
+  bundle: { profiles?: string[] },
+  supported: ReadonlySet<string> = SUPPORTED_PROFILES,
+): void {
+  const profiles = bundle.profiles;
+  if (!profiles || profiles.length === 0) return;
+  const missing = profiles.filter((p) => !supported.has(p));
+  if (missing.length > 0) {
+    throw new BundleIncompatibleError(missing);
+  }
+}
+
+// --- fetch + cache ---------------------------------------------------
+
+export interface BundleFetcher {
+  /** Fetch the bundle for a scene version. Cached forever by hash. */
+  get(sceneId: string, sceneVersion: string): Promise<RenderBundle>;
+  /** Inject a bundle directly — used by tests and for the "scene already in
+   *  flight" handoff path. */
+  preload(bundle: RenderBundle): void;
+}
+
+export interface BundleFetcherOptions {
+  /** Base URL of the server. The fetcher constructs
+   *  `${baseUrl}/lsdp/v1/scenes/{id}/bundle?v={hash}`. */
+  baseUrl: string;
+  /** Path prefix for bundle resolution. Defaults to `/lsdp/v1/scenes`. */
+  pathPrefix?: string;
+  fetchImpl?: typeof fetch;
+}
+
+class FetcherImpl implements BundleFetcher {
+  private readonly cache = new Map<string, RenderBundle>();
+  private readonly baseUrl: string;
+  private readonly pathPrefix: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: BundleFetcherOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.pathPrefix = (opts.pathPrefix ?? "/lsdp/v1/scenes").replace(/\/$/, "");
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  }
+
+  preload(bundle: RenderBundle): void {
+    // LSML 1.1 §17.3.1 — reject early if any declared profile is
+    // unsupported by this runtime. Authors get an actionable error
+    // instead of a silent rendering glitch.
+    validateBundleProfiles(bundle);
+    this.cache.set(bundle.scene_version, bundle);
+  }
+
+  async get(sceneId: string, sceneVersion: string): Promise<RenderBundle> {
+    const cached = this.cache.get(sceneVersion);
+    if (cached) return cached;
+    const url = `${this.baseUrl}${this.pathPrefix}/${encodeURIComponent(sceneId)}/bundle?v=${encodeURIComponent(sceneVersion)}`;
+    const response = await this.fetchImpl(url);
+    if (!response.ok) {
+      throw new Error(`bundle fetch failed: ${response.status} ${response.statusText}`);
+    }
+    const json = (await response.json()) as RenderBundle;
+    if (json.scene_version !== sceneVersion) {
+      throw new Error(
+        `bundle scene_version mismatch: expected ${sceneVersion}, got ${json.scene_version}`,
+      );
+    }
+    validateBundleProfiles(json);
+    this.cache.set(sceneVersion, json);
+    return json;
+  }
+}
+
+export function createBundleFetcher(opts: BundleFetcherOptions): BundleFetcher {
+  return new FetcherImpl(opts);
+}

package/src/render/fill.tsx

@@ -0,0 +1,163 @@
+// Fill rendering helpers (LSML 1.1 §4.12).
+//
+// A Fill is a discriminated union :
+//   - solid           : { kind: "solid", color, opacity? }
+//   - linear-gradient : { kind: "linear-gradient", angle_deg?, stops, opacity? }
+//   - radial-gradient : { kind: "radial-gradient", center?, radius?, stops, opacity? }
+//
+// shape.fills[] and frame.backgrounds[] both use this shape. Each fill
+// renders as a separate SVG element layered top-to-bottom (first entry
+// renders on top per §4.12).
+
+import type { CSSProperties, ReactElement } from "react";
+
+export interface FillStop {
+  offset: number;
+  color: string;
+  opacity?: number;
+}
+
+export type Fill =
+  | { kind: "solid"; color: string; opacity?: number }
+  | {
+      kind: "linear-gradient";
+      angle_deg?: number;
+      stops: FillStop[];
+      opacity?: number;
+    }
+  | {
+      kind: "radial-gradient";
+      center?: { x: number; y: number };
+      radius?: number;
+      stops: FillStop[];
+      opacity?: number;
+    };
+
+let gradientIdSeq = 0;
+function nextGradientId(): string {
+  gradientIdSeq = (gradientIdSeq + 1) % 1_000_000;
+  return `lumen-grad-${gradientIdSeq.toString(36)}`;
+}
+
+export interface FillRenderResult {
+  /** SVG <defs> contributions (gradient definitions). */
+  defs: ReactElement[];
+  /** Reference to use as the `fill` attribute on the shape. */
+  ref: string;
+}
+
+/** Compile a Fill into an SVG `<defs>` entry + a `fill="url(#…)"` ref.
+ * Solid fills produce no defs and return the colour directly. */
+export function renderFill(fill: Fill): FillRenderResult {
+  if (fill.kind === "solid") {
+    // Solid fill — no defs needed, just hand the colour to fill.
+    // SVG fill-opacity composes with element opacity multiplicatively
+    // so we apply both consistently.
+    return { defs: [], ref: fill.color };
+  }
+  const id = nextGradientId();
+  if (fill.kind === "linear-gradient") {
+    // angle_deg : 0 = bottom-to-top per §4.12 (matches CSS `linear-gradient`)
+    const angle = fill.angle_deg ?? 0;
+    // Translate angle (degrees from up) to SVG x1/y1/x2/y2 in user space.
+    const rad = ((angle - 90) * Math.PI) / 180; // 0° → x1=0,y1=1 (bottom-up)
+    const x1 = 0.5 - 0.5 * Math.cos(rad);
+    const y1 = 0.5 - 0.5 * Math.sin(rad);
+    const x2 = 0.5 + 0.5 * Math.cos(rad);
+    const y2 = 0.5 + 0.5 * Math.sin(rad);
+    const defs = [
+      <linearGradient
+        key={id}
+        id={id}
+        x1={`${x1 * 100}%`}
+        y1={`${y1 * 100}%`}
+        x2={`${x2 * 100}%`}
+        y2={`${y2 * 100}%`}
+      >
+        {fill.stops.map((s, i) => (
+          <stop
+            key={i}
+            offset={s.offset}
+            stopColor={s.color}
+            {...(s.opacity !== undefined ? { stopOpacity: s.opacity } : {})}
+          />
+        ))}
+      </linearGradient>,
+    ];
+    return { defs, ref: `url(#${id})` };
+  }
+  // radial-gradient
+  const cx = fill.center?.x ?? 0.5;
+  const cy = fill.center?.y ?? 0.5;
+  const r = fill.radius ?? 0.5;
+  const defs = [
+    <radialGradient key={id} id={id} cx={`${cx * 100}%`} cy={`${cy * 100}%`} r={`${r * 100}%`}>
+      {fill.stops.map((s, i) => (
+        <stop
+          key={i}
+          offset={s.offset}
+          stopColor={s.color}
+          {...(s.opacity !== undefined ? { stopOpacity: s.opacity } : {})}
+        />
+      ))}
+    </radialGradient>,
+  ];
+  return { defs, ref: `url(#${id})` };
+}
+
+/** Compile an array of Fill into a CSS `background-image` value usable
+ * on a `<div>` (frame backgrounds — non-SVG context). Returns the CSS
+ * string + opacity. Stops use percentages in CSS gradient syntax. */
+export function backgroundsToCss(fills: Fill[]): CSSProperties {
+  // Per §4.12, fills[0] renders on top — CSS background-image stacks
+  // first → top-most. Match by passing in the same order.
+  const layers = fills.map(fillToCss).filter(Boolean) as string[];
+  if (layers.length === 0) return {};
+  return { backgroundImage: layers.join(", ") };
+}
+
+function fillToCss(fill: Fill): string | null {
+  if (fill.kind === "solid") {
+    // Wrap solid in linear-gradient so it can stack with other layers.
+    return `linear-gradient(${fill.color}, ${fill.color})`;
+  }
+  const stops = fill.stops
+    .map((s) => {
+      const c = s.opacity !== undefined ? cssWithOpacity(s.color, s.opacity) : s.color;
+      return `${c} ${(s.offset * 100).toFixed(2)}%`;
+    })
+    .join(", ");
+  if (fill.kind === "linear-gradient") {
+    const angle = fill.angle_deg ?? 0;
+    return `linear-gradient(${angle}deg, ${stops})`;
+  }
+  // radial-gradient
+  const cx = (fill.center?.x ?? 0.5) * 100;
+  const cy = (fill.center?.y ?? 0.5) * 100;
+  return `radial-gradient(circle at ${cx}% ${cy}%, ${stops})`;
+}
+
+function cssWithOpacity(color: string, opacity: number): string {
+  // Best-effort wrapper — for hex/rgb we can append alpha. For
+  // unrecognised forms, fall back to color-mix.
+  const hex = color.match(/^#([0-9a-f]{6})$/i);
+  if (hex) {
+    const a = Math.round(opacity * 255)
+      .toString(16)
+      .padStart(2, "0");
+    return `#${hex[1]}${a}`;
+  }
+  return `color-mix(in srgb, ${color} ${opacity * 100}%, transparent)`;
+}
+
+/** Coerce loose JSON into a Fill array. Returns [] for non-arrays. */
+export function parseFills(value: unknown): Fill[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter(isFill) as Fill[];
+}
+
+function isFill(v: unknown): v is Fill {
+  if (typeof v !== "object" || v === null) return false;
+  const k = (v as { kind?: unknown }).kind;
+  return k === "solid" || k === "linear-gradient" || k === "radial-gradient";
+}

package/src/render/keyframe-player.tsx

@@ -0,0 +1,89 @@
+// LSML 1.1 §6.6 — keyframe sequence playback wrapper.
+//
+// Wraps a primitive subtree in a framer-motion `motion.div` that plays
+// out the compiled keyframe arrays once on (re)mount, or whenever the
+// bound `key` LeafPath changes. We trigger replay via React's `key=`
+// reconciliation — bumping a counter when the keyframe key value flips
+// remounts the motion subtree, restarting the animation from `at: 0`.
+//
+// LSML 1.1 §6.7 — when this player runs inside a `repeat` iteration, a
+// `staggerDelay` (ms) is provided through `StaggerContext` and added to
+// framer's transition.delay so each iteration starts `index * stagger_ms`
+// after the previous one.
+
+import { motion } from "framer-motion";
+import { useContext, useEffect, useRef, type ReactNode } from "react";
+import { useSignals } from "@preact/signals-react/runtime";
+import type { Store } from "../state/store";
+import { compileForFramer, type Keyframes } from "../animate/keyframes";
+import { StaggerContext } from "./stagger-context";
+import { scopedPath, usePathScope } from "./scope";
+
+export interface KeyframePlayerProps {
+  keyframes: Keyframes;
+  store: Store;
+  children: ReactNode;
+}
+
+export function KeyframePlayer({ keyframes, store, children }: KeyframePlayerProps): ReactNode {
+  useSignals();
+  const scope = usePathScope();
+  const staggerDelayMs = useContext(StaggerContext);
+
+  // Pull the latest `key` LeafPath value and remount whenever it
+  // changes. We track via a ref + counter so React's reconciliation
+  // gives us a fresh motion.div (and thus a fresh animation pass).
+  const lastKeyValue = useRef<unknown>(undefined);
+  const replayTokenRef = useRef(0);
+  if (keyframes.key !== undefined) {
+    const v = store.signal(scopedPath(scope, keyframes.key)).value;
+    if (lastKeyValue.current !== v) {
+      lastKeyValue.current = v;
+      replayTokenRef.current += 1;
+    }
+  }
+
+  const compiled = compileForFramer(keyframes);
+  if (!compiled) {
+    return <>{children}</>;
+  }
+
+  const transition =
+    staggerDelayMs > 0
+      ? { ...compiled.transition, delay: staggerDelayMs / 1000 }
+      : compiled.transition;
+
+  return (
+    <motion.div
+      key={replayTokenRef.current}
+      style={{ display: "contents" }}
+      initial={firstFrame(compiled.animate)}
+      animate={compiled.animate}
+      transition={transition}
+    >
+      <ReplayOnMount />
+      {children}
+    </motion.div>
+  );
+}
+
+/** No-op effect placeholder — kept for symmetry / future hooks like
+ *  reporting playback completion to the renderer. */
+function ReplayOnMount(): null {
+  useEffect(() => {
+    // intentional no-op
+  }, []);
+  return null;
+}
+
+/** Pluck the `at: 0` waypoint values into a framer-motion `initial` prop
+ *  so the very first frame matches the start of the keyframe path. Without
+ *  this, framer interpolates from the element's current style which can
+ *  produce a visible jump on mount. */
+function firstFrame(animate: Record<string, (number | string)[]>): Record<string, number | string> {
+  const out: Record<string, number | string> = {};
+  for (const [k, arr] of Object.entries(animate)) {
+    if (arr.length > 0) out[k] = arr[0];
+  }
+  return out;
+}

package/src/render/primitives/frame.tsx

@@ -0,0 +1,78 @@
+import { motion } from "framer-motion";
+import type { CSSProperties } from "react";
+import type { PrimitiveProps } from "./index";
+import { toFramer } from "../../animate/transitions";
+import { backgroundsToCss, parseFills } from "../fill";
+
+/** Absolute-positioned container with size + transform + opacity.
+ *  Animatable on `transform` and `opacity` only — width/height/position
+ *  changes are intentionally *not* animatable to keep the broadcast
+ *  off the layout path.
+ *
+ *  LSML 1.1 §4.3 + §4.12 add `backgrounds[]` as an alternative to the
+ *  legacy `background` (single color). The array form supports stacked
+ *  fills with linear / radial gradients ; first entry renders on top.
+ */
+export function Frame({ resolved, transitionFor, children }: PrimitiveProps) {
+  const x = numberOr(resolved.x, 0);
+  const y = numberOr(resolved.y, 0);
+  const width = sizeProp(resolved.width);
+  const height = sizeProp(resolved.height);
+  const opacity = numberOr(resolved.opacity, 1);
+  const scale = numberOr(resolved.scale, 1);
+  const rotate = numberOr(resolved.rotate, 0);
+
+  // 1.0 single-fill prop — used as fallback when 1.1 `backgrounds[]`
+  // is empty.
+  const legacyBackground = (resolved.background as string | undefined) ?? undefined;
+  const backgrounds = parseFills(resolved.backgrounds);
+
+  // Pick the most expressive declared transition among the animated
+  // bindings (transform / opacity). If none, no animation.
+  const tx =
+    transitionFor("opacity") ??
+    transitionFor("scale") ??
+    transitionFor("rotate") ??
+    transitionFor("x") ??
+    transitionFor("y");
+
+  const style: CSSProperties = {
+    position: "absolute",
+    left: 0,
+    top: 0,
+    width,
+    height,
+    willChange: "transform, opacity",
+  };
+  if (backgrounds.length > 0) {
+    Object.assign(style, backgroundsToCss(backgrounds));
+  } else if (legacyBackground !== undefined) {
+    style.background = legacyBackground;
+  }
+
+  return (
+    <motion.div
+      style={style}
+      animate={{
+        opacity,
+        x,
+        y,
+        scale,
+        rotate,
+      }}
+      transition={toFramer(tx)}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+function numberOr(v: unknown, fallback: number): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+
+function sizeProp(v: unknown): number | string | undefined {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.length > 0) return v;
+  return undefined;
+}

package/src/render/primitives/grid.tsx

@@ -0,0 +1,20 @@
+import type { PrimitiveProps } from "./index";
+
+/** CSS Grid container with declared rows / cols. */
+export function Grid({ resolved, children }: PrimitiveProps) {
+  const cols = (resolved.cols as string) ?? "1fr";
+  const rows = (resolved.rows as string) ?? "auto";
+  const gap = (resolved.gap as number | string | undefined) ?? 0;
+  return (
+    <div
+      style={{
+        display: "grid",
+        gridTemplateColumns: cols,
+        gridTemplateRows: rows,
+        gap,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/render/primitives/image.tsx

@@ -0,0 +1,35 @@
+import { motion } from "framer-motion";
+import type { PrimitiveProps } from "./index";
+import { toFramer } from "../../animate/transitions";
+
+/** Image leaf. `src`, `fit` (cover/contain/fill), `position`,
+ *  `opacity`. Opacity is animated when a transition is declared. */
+export function Image({ resolved, transitionFor }: PrimitiveProps) {
+  const src = resolved.src as string | undefined;
+  if (!src) return null;
+  const fit = (resolved.fit as string | undefined) ?? "contain";
+  const position = (resolved.position as string | undefined) ?? "center";
+  const opacity = numberOr(resolved.opacity, 1);
+
+  const tx = transitionFor("opacity") ?? transitionFor("src");
+
+  return (
+    <motion.img
+      src={src}
+      style={{
+        objectFit: fit as React.CSSProperties["objectFit"],
+        objectPosition: position,
+        width: "100%",
+        height: "100%",
+        willChange: "opacity",
+      }}
+      animate={{ opacity }}
+      transition={toFramer(tx)}
+      draggable={false}
+    />
+  );
+}
+
+function numberOr(v: unknown, fallback: number): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}

package/src/render/primitives/index.ts

@@ -0,0 +1,35 @@
+// Primitive component registry. Tree dispatch uses this map to look
+// up the React component for each `kind` ; user components are inlined
+// at compile time so Lumencast's runtime never sees them.
+
+import type { ComponentType, ReactNode } from "react";
+import type { RenderKind } from "../bundle";
+import type { Transition } from "../../animate/transitions";
+import { Stack } from "./stack";
+import { Grid } from "./grid";
+import { Frame } from "./frame";
+import { Text } from "./text";
+import { Image } from "./image";
+import { Shape } from "./shape";
+import { Media } from "./media";
+import { Instance } from "./instance";
+// `repeat` is dispatched specially in the tree (it iterates a bound
+// array and provides a path scope to its children) ; it does not
+// appear here as a regular primitive.
+
+export interface PrimitiveProps {
+  resolved: Record<string, unknown>;
+  transitionFor: (key: string) => Transition | undefined;
+  children?: ReactNode;
+}
+
+export const PRIMITIVES: Partial<Record<RenderKind, ComponentType<PrimitiveProps>>> = {
+  stack: Stack,
+  grid: Grid,
+  frame: Frame,
+  text: Text,
+  image: Image,
+  shape: Shape,
+  media: Media,
+  instance: Instance,
+};