@velumo/runtime 0.1.0-beta.0

package/src/registry.ts

@@ -0,0 +1,194 @@
+import type { Manifest } from "@velumo/core";
+
+export type LayerRenderer<TContext = unknown, TResult = unknown> = (
+  context: TContext,
+) => TResult;
+
+export type ActionHandler<TContext = unknown> = (context: TContext) => void;
+
+export type ManifestTransform = (manifest: Manifest) => Manifest;
+
+export interface PluginSetupContext<
+  TLayerContext = unknown,
+  TLayerResult = unknown,
+  TActionContext = unknown,
+> {
+  readonly registry: RuntimeRegistry<
+    TLayerContext,
+    TLayerResult,
+    TActionContext
+  >;
+  readonly manifest: Manifest;
+}
+
+export interface VelumoPlugin<
+  TLayerContext = unknown,
+  TLayerResult = unknown,
+  TActionContext = unknown,
+> {
+  readonly id: string;
+  setup?(
+    context: PluginSetupContext<TLayerContext, TLayerResult, TActionContext>,
+  ): void;
+}
+
+export interface InstallPluginsOptions<
+  TLayerContext = unknown,
+  TLayerResult = unknown,
+  TActionContext = unknown,
+> {
+  readonly registry: RuntimeRegistry<
+    TLayerContext,
+    TLayerResult,
+    TActionContext
+  >;
+  readonly manifest: Manifest;
+  readonly plugins: readonly VelumoPlugin<
+    TLayerContext,
+    TLayerResult,
+    TActionContext
+  >[];
+}
+
+export class RuntimeRegistry<
+  TLayerContext = unknown,
+  TLayerResult = unknown,
+  TActionContext = unknown,
+> {
+  readonly #layerRenderers = new Map<
+    string,
+    LayerRenderer<TLayerContext, TLayerResult>
+  >();
+  readonly #actionHandlers = new Map<string, ActionHandler<TActionContext>>();
+  readonly #manifestTransforms: ManifestTransform[] = [];
+  readonly #installedPluginIds = new Set<string>();
+
+  registerLayerRenderer(
+    type: string,
+    renderer: LayerRenderer<TLayerContext, TLayerResult>,
+  ): void {
+    if (this.#layerRenderers.has(type)) {
+      throw new Error(`Layer renderer already registered: ${type}`);
+    }
+
+    this.#layerRenderers.set(type, renderer);
+  }
+
+  hasLayerRenderer(type: string): boolean {
+    return this.#layerRenderers.has(type);
+  }
+
+  getLayerRenderer(
+    type: string,
+  ): LayerRenderer<TLayerContext, TLayerResult> | undefined {
+    return this.#layerRenderers.get(type);
+  }
+
+  registerActionHandler(
+    type: string,
+    handler: ActionHandler<TActionContext>,
+  ): void {
+    if (this.#actionHandlers.has(type)) {
+      throw new Error(`Action handler already registered: ${type}`);
+    }
+
+    this.#actionHandlers.set(type, handler);
+  }
+
+  hasActionHandler(type: string): boolean {
+    return this.#actionHandlers.has(type);
+  }
+
+  getActionHandler(type: string): ActionHandler<TActionContext> | undefined {
+    return this.#actionHandlers.get(type);
+  }
+
+  registerManifestTransform(transform: ManifestTransform): void {
+    this.#manifestTransforms.push(transform);
+  }
+
+  applyManifestTransforms(manifest: Manifest): Manifest {
+    return this.#manifestTransforms.reduce(
+      (current, transform) => transform(current),
+      cloneManifest(manifest),
+    );
+  }
+
+  installPlugins(
+    manifest: Manifest,
+    plugins: readonly VelumoPlugin<
+      TLayerContext,
+      TLayerResult,
+      TActionContext
+    >[],
+  ): void {
+    this.#assertPluginsCanInstall(plugins);
+
+    for (const plugin of plugins) {
+      plugin.setup?.({ registry: this, manifest });
+      this.#installedPluginIds.add(plugin.id);
+    }
+  }
+
+  #assertPluginsCanInstall(
+    plugins: readonly VelumoPlugin<
+      TLayerContext,
+      TLayerResult,
+      TActionContext
+    >[],
+  ): void {
+    const nextPluginIds = new Set<string>();
+
+    for (const plugin of plugins) {
+      if (
+        this.#installedPluginIds.has(plugin.id) ||
+        nextPluginIds.has(plugin.id)
+      ) {
+        throw new Error(`Plugin already installed: ${plugin.id}`);
+      }
+
+      nextPluginIds.add(plugin.id);
+    }
+  }
+}
+
+export function createRuntimeRegistry<
+  TLayerContext = unknown,
+  TLayerResult = unknown,
+  TActionContext = unknown,
+>(): RuntimeRegistry<TLayerContext, TLayerResult, TActionContext> {
+  return new RuntimeRegistry<TLayerContext, TLayerResult, TActionContext>();
+}
+
+export function installPlugins<
+  TLayerContext = unknown,
+  TLayerResult = unknown,
+  TActionContext = unknown,
+>(
+  options: InstallPluginsOptions<TLayerContext, TLayerResult, TActionContext>,
+): void {
+  options.registry.installPlugins(options.manifest, options.plugins);
+}
+
+function cloneManifest(manifest: Manifest): Manifest {
+  const slides =
+    manifest.slides === undefined ? {} : { slides: [...manifest.slides] };
+  const assets =
+    manifest.assets === undefined ? {} : { assets: [...manifest.assets] };
+  const plugins =
+    manifest.plugins === undefined ? {} : { plugins: [...manifest.plugins] };
+  const theme =
+    manifest.theme === undefined ? {} : { theme: { ...manifest.theme } };
+  const exportOptions =
+    manifest.export === undefined ? {} : { export: { ...manifest.export } };
+
+  return {
+    ...manifest,
+    deck: { ...manifest.deck },
+    ...slides,
+    ...assets,
+    ...plugins,
+    ...theme,
+    ...exportOptions,
+  };
+}

package/src/scene-player.ts

@@ -0,0 +1,244 @@
+import type { CameraEasing, CameraStop, CameraView, Cue } from "@velumo/core";
+import { type ResolvedView, resolveView } from "./spatial.js";
+import { TimelineScheduler } from "./timeline.js";
+
+const DEFAULT_DURATION_MS = 800;
+const DEFAULT_EASING: CameraEasing = "ease-in-out";
+const FINALIZE_SEEK_MS = Number.MAX_SAFE_INTEGER;
+
+export type ScenePlayerDirection = "forward" | "backward";
+export type ScenePlayerMove = "moved" | "exhausted";
+
+export type ScenePlayerEventName = "camera:move" | "cue:fired" | "stop:enter";
+
+export interface ScenePlayerCameraMoveEvent {
+  readonly type: "camera:move";
+  readonly view: ResolvedView;
+  readonly durationMs: number;
+  readonly easing: CameraEasing;
+}
+
+export interface ScenePlayerCueFiredEvent {
+  readonly type: "cue:fired";
+  readonly cue: Cue;
+  readonly stopIndex: number;
+}
+
+export interface ScenePlayerStopEnterEvent {
+  readonly type: "stop:enter";
+  readonly stopIndex: number;
+}
+
+export type ScenePlayerEvent =
+  | ScenePlayerCameraMoveEvent
+  | ScenePlayerCueFiredEvent
+  | ScenePlayerStopEnterEvent;
+
+export type ScenePlayerEventHandler = (event: ScenePlayerEvent) => void;
+
+export interface ScenePlayerOptions {
+  readonly stops: readonly CameraStop[];
+  readonly reducedMotion?: boolean;
+}
+
+function isCameraView(value: unknown): value is CameraView {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const v = value as { x?: unknown; y?: unknown; zoom?: unknown };
+  if (!Number.isFinite(v.x) || !Number.isFinite(v.y)) {
+    return false;
+  }
+  if (v.zoom !== undefined && !Number.isFinite(v.zoom)) {
+    return false;
+  }
+  return true;
+}
+
+export class ScenePlayer {
+  readonly #stops: readonly CameraStop[];
+  readonly #reducedMotion: boolean;
+  readonly #handlers = new Map<
+    ScenePlayerEventName,
+    Set<ScenePlayerEventHandler>
+  >();
+  #stopIndex = -1;
+  #view: ResolvedView = { x: 0, y: 0, zoom: 1 };
+  #timeline: TimelineScheduler | undefined;
+  #timelineCueCount = 0;
+  #elapsedSinceLand = 0;
+
+  constructor(options: ScenePlayerOptions) {
+    this.#stops = options.stops;
+    this.#reducedMotion = options.reducedMotion ?? false;
+  }
+
+  enter(direction: ScenePlayerDirection): void {
+    const index = direction === "forward" ? 0 : this.#stops.length - 1;
+    this.#land(index);
+    if (direction === "backward") {
+      this.#finalizeTimeline();
+    }
+  }
+
+  advance(): ScenePlayerMove {
+    if (this.#stopIndex >= this.#stops.length - 1) {
+      return "exhausted";
+    }
+    this.#finalizeTimeline();
+    this.#land(this.#stopIndex + 1);
+    return "moved";
+  }
+
+  back(): ScenePlayerMove {
+    if (this.#stopIndex <= 0) {
+      return "exhausted";
+    }
+    this.#land(this.#stopIndex - 1);
+    this.#finalizeTimeline();
+    return "moved";
+  }
+
+  tick(deltaMs: number): void {
+    if (this.#timeline !== undefined && deltaMs > 0) {
+      this.#timeline.advance(deltaMs);
+    }
+    this.#elapsedSinceLand += deltaMs;
+    const stop = this.#stops[this.#stopIndex];
+    if (
+      stop !== undefined &&
+      stop.hold !== undefined &&
+      this.#elapsedSinceLand >= stop.hold &&
+      this.#stopIndex < this.#stops.length - 1
+    ) {
+      this.advance();
+    }
+  }
+
+  getView(): ResolvedView {
+    return this.#view;
+  }
+
+  getStopIndex(): number {
+    return this.#stopIndex;
+  }
+
+  on(
+    eventName: ScenePlayerEventName,
+    handler: ScenePlayerEventHandler,
+  ): () => void {
+    let handlers = this.#handlers.get(eventName);
+    if (handlers === undefined) {
+      handlers = new Set();
+      this.#handlers.set(eventName, handlers);
+    }
+    handlers.add(handler);
+    return () => {
+      handlers.delete(handler);
+    };
+  }
+
+  #land(index: number): void {
+    const stop = this.#stops[index];
+    if (stop === undefined) {
+      return;
+    }
+    this.#stopIndex = index;
+    this.#elapsedSinceLand = 0;
+    this.#view = resolveView(stop.camera);
+    this.#emitCameraMove(stop.transition?.duration, stop.transition?.easing);
+    this.#emit({ type: "stop:enter", stopIndex: index });
+    this.#startTimeline(stop);
+    if (this.#reducedMotion) {
+      this.#finalizeTimeline();
+    }
+  }
+
+  isIdle(): boolean {
+    if (this.#stopIndex === -1) {
+      return true;
+    }
+    // Unfired cues remain: timeline exists and has not yet fired all cues.
+    if (this.#timeline !== undefined) {
+      const fired = this.#timeline.getState().firedCueIndices.length;
+      if (fired < this.#timelineCueCount) {
+        return false;
+      }
+    }
+    // Hold pending: not on the last stop and elapsed has not reached the hold.
+    const stop = this.#stops[this.#stopIndex];
+    if (
+      stop !== undefined &&
+      stop.hold !== undefined &&
+      this.#stopIndex < this.#stops.length - 1 &&
+      this.#elapsedSinceLand < stop.hold
+    ) {
+      return false;
+    }
+    return true;
+  }
+
+  #startTimeline(stop: CameraStop): void {
+    const cues = stop.cues ?? [];
+    if (cues.length === 0) {
+      this.#timeline = undefined;
+      this.#timelineCueCount = 0;
+      return;
+    }
+    const timeline = new TimelineScheduler({ cues, initialPlaying: true });
+    timeline.on("cue:fired", (event) => {
+      if (event.type !== "cue:fired") {
+        return;
+      }
+      this.#handleCue(event.cue);
+    });
+    this.#timeline = timeline;
+    this.#timelineCueCount = cues.length;
+  }
+
+  #finalizeTimeline(): void {
+    if (this.#timeline === undefined) {
+      return;
+    }
+    // Seek far beyond any cue time: every not-yet-fired cue fires now,
+    // applying its end-state, so a press mid-sequence leaves state consistent.
+    this.#timeline.advance(FINALIZE_SEEK_MS);
+    this.#timeline = undefined;
+    this.#timelineCueCount = 0;
+  }
+
+  #handleCue(cue: Cue): void {
+    if (cue.action.type === "camera" && isCameraView(cue.action.payload)) {
+      this.#view = resolveView(cue.action.payload);
+      this.#emitCameraMove(undefined, undefined);
+      return;
+    }
+    this.#emit({ type: "cue:fired", cue, stopIndex: this.#stopIndex });
+  }
+
+  #emitCameraMove(
+    duration: number | undefined,
+    easing: CameraEasing | undefined,
+  ): void {
+    this.#emit({
+      type: "camera:move",
+      view: this.#view,
+      durationMs: this.#reducedMotion ? 0 : (duration ?? DEFAULT_DURATION_MS),
+      easing: easing ?? DEFAULT_EASING,
+    });
+  }
+
+  #emit(event: ScenePlayerEvent): void {
+    const handlers = this.#handlers.get(event.type);
+    if (handlers === undefined) {
+      return;
+    }
+    for (const handler of [...handlers]) {
+      handler(event);
+    }
+  }
+}
+
+export function createScenePlayer(options: ScenePlayerOptions): ScenePlayer {
+  return new ScenePlayer(options);
+}

package/src/spatial.ts

@@ -0,0 +1,40 @@
+import type { CameraEasing, CameraView } from "@velumo/core";
+import { type EasingFunction, easeInOutCubic } from "./timeline.js";
+
+export const CAMERA_EASINGS: readonly CameraEasing[] = [
+  "linear",
+  "ease",
+  "ease-in",
+  "ease-out",
+  "ease-in-out",
+];
+
+function easeIn(t: number): number {
+  return t * t;
+}
+
+function easeOut(t: number): number {
+  return 1 - (1 - t) * (1 - t);
+}
+
+const EASING_MAP: Record<CameraEasing, EasingFunction> = {
+  linear: (t) => t,
+  ease: easeInOutCubic,
+  "ease-in": easeIn,
+  "ease-out": easeOut,
+  "ease-in-out": easeInOutCubic,
+};
+
+export function resolveEasing(name: CameraEasing | undefined): EasingFunction {
+  return name === undefined ? easeInOutCubic : EASING_MAP[name];
+}
+
+export interface ResolvedView {
+  readonly x: number;
+  readonly y: number;
+  readonly zoom: number;
+}
+
+export function resolveView(view: CameraView): ResolvedView {
+  return { x: view.x, y: view.y, zoom: view.zoom ?? 1 };
+}

package/src/theme-bundle.ts

@@ -0,0 +1,35 @@
+import type { Theme } from "@velumo/core";
+import type { VelumoPlugin } from "./registry.js";
+
+/**
+ * A theme bundle is a heterogeneous container: it carries plugin factories
+ * whose internal renderer/action context types it deliberately does not track.
+ * Plugins are loosely coupled at registration — the registry stores renderers
+ * keyed by layer type and enforces context-correctness there — so the bundle
+ * uses `any` for the plugin generics to stay ergonomic for any host.
+ */
+type AnyVelumoPlugin = VelumoPlugin<any, any, any>;
+
+/**
+ * A host-side convenience that pairs a theme with everything it needs to run:
+ * its theme tokens, its CSS, and a factory for the plugins it depends on. A
+ * theme package can export one `ThemeBundle` so an author wires a single import
+ * instead of three (theme + css + plugin).
+ *
+ * Plugins stay explicit and host-controlled: the bundle only *carries* a plugin
+ * factory — the host still calls it and registers the result. The runtime never
+ * auto-loads plugins from a manifest or config reference.
+ */
+export interface ThemeBundle {
+  readonly theme: Theme;
+  readonly css?: string;
+  readonly createPlugins?: () => readonly AnyVelumoPlugin[];
+}
+
+/**
+ * Resolve a bundle's plugins. Returns a fresh array (empty when the bundle
+ * brings no plugins) so the result is safe for the host to register directly.
+ */
+export function themePlugins(bundle: ThemeBundle): readonly AnyVelumoPlugin[] {
+  return bundle.createPlugins?.() ?? [];
+}