@velumo/cli 0.1.0-beta.0

package/src/browser-spatial.ts

@@ -0,0 +1,292 @@
+import type { CueAction, JsonValue, Scene, SlideEntry } from "@velumo/core";
+import { createScenePlayer, type ScenePlayer } from "@velumo/runtime";
+import {
+  applyCameraToDomRoot,
+  applyCameraTransition,
+  renderSpatialWorld,
+  type LayoutRendererElement,
+  type LayoutRendererFactories,
+} from "@velumo/renderer-dom";
+
+interface SpatialRoot {
+  readonly ownerDocument: {
+    createElement(tag: string): SpatialElement;
+    createElementNS(namespace: string, tag: string): SpatialElement;
+  };
+  replaceChildren(...children: unknown[]): void;
+}
+
+interface SpatialElement extends LayoutRendererElement {
+  readonly ownerDocument: {
+    createElement(tag: string): SpatialElement;
+    createElementNS(namespace: string, tag: string): SpatialElement;
+  };
+}
+
+interface SpatialWindow {
+  matchMedia?: (query: string) => { matches: boolean } | undefined;
+  requestAnimationFrame?: (cb: (t: number) => void) => number;
+  cancelAnimationFrame?: (handle: number) => void;
+}
+
+export interface SpatialSessionOptions {
+  readonly root: SpatialRoot;
+  readonly slide: SlideEntry;
+  readonly window: SpatialWindow;
+  readonly direction?: "forward" | "backward";
+}
+
+export interface SpatialSession {
+  advance(): boolean;
+  back(): boolean;
+  dispose(): void;
+}
+
+function asSpatialScene(slide: SlideEntry): Scene | undefined {
+  if (slide.kind !== "scene") {
+    return undefined;
+  }
+  const scene = slide as Scene;
+  if (scene.cameraPath === undefined || scene.cameraPath.length === 0) {
+    return undefined;
+  }
+  return scene;
+}
+
+function readReducedMotion(window: SpatialWindow): boolean {
+  return (
+    window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches === true
+  );
+}
+
+function payloadTarget(payload: JsonValue | undefined): string | undefined {
+  if (
+    payload !== null &&
+    typeof payload === "object" &&
+    !Array.isArray(payload) &&
+    typeof (payload as { target?: unknown }).target === "string"
+  ) {
+    return (payload as { target: string }).target;
+  }
+  return undefined;
+}
+
+export function createSpatialSession(
+  options: SpatialSessionOptions,
+): SpatialSession | undefined {
+  const scene = asSpatialScene(options.slide);
+  if (scene === undefined) {
+    return undefined;
+  }
+
+  const factories: LayoutRendererFactories = {
+    createElement: (tag) =>
+      options.root.ownerDocument.createElement(tag) as SpatialElement,
+    createElementNS: (ns, tag) =>
+      options.root.ownerDocument.createElementNS(ns, tag) as SpatialElement,
+    setStyleProperty: (el, prop, value) => {
+      (el as SpatialElement).style?.setProperty(prop, value);
+    },
+  };
+
+  const { viewport, world } = renderSpatialWorld(scene, factories);
+  options.root.replaceChildren(viewport);
+
+  const reducedMotion = readReducedMotion(options.window);
+  const player = createScenePlayer({
+    stops: scene.cameraPath ?? [],
+    reducedMotion,
+  });
+
+  const disposers: Array<() => void> = [];
+  disposers.push(
+    player.on("camera:move", (event) => {
+      if (event.type !== "camera:move") {
+        return;
+      }
+      applyCameraTransition(world, event.durationMs, event.easing, factories);
+      applyCameraToDomRoot(
+        world as unknown as { style: { transform: string } },
+        event.view,
+      );
+    }),
+  );
+  disposers.push(
+    player.on("cue:fired", (event) => {
+      if (event.type !== "cue:fired") {
+        return;
+      }
+      handleDomCue(world, event.cue.action);
+    }),
+  );
+
+  let rafHandle: number | undefined;
+  let lastTime: number | undefined;
+  let disposed = false;
+  const raf = options.window.requestAnimationFrame;
+  const caf = options.window.cancelAnimationFrame;
+
+  function loop(time: number): void {
+    if (disposed) {
+      return;
+    }
+    const delta = lastTime === undefined ? 0 : time - lastTime;
+    lastTime = time;
+    try {
+      player.tick(delta);
+    } catch {
+      // A cue-handler fault must not kill the animation loop.
+    }
+    if (raf !== undefined && !player.isIdle()) {
+      rafHandle = raf(loop);
+    } else {
+      rafHandle = undefined;
+    }
+  }
+
+  function startLoop(): void {
+    if (raf === undefined || rafHandle !== undefined) {
+      return;
+    }
+    lastTime = undefined;
+    rafHandle = raf(loop);
+  }
+
+  player.enter(options.direction ?? "forward");
+  startLoop();
+
+  return {
+    advance() {
+      const moved = player.advance() === "moved";
+      if (moved) {
+        startLoop();
+      }
+      return moved;
+    },
+    back() {
+      const moved = player.back() === "moved";
+      if (moved) {
+        startLoop();
+      }
+      return moved;
+    },
+    dispose() {
+      disposed = true;
+      if (rafHandle !== undefined && caf !== undefined) {
+        caf(rafHandle);
+        rafHandle = undefined;
+      }
+      for (const dispose of disposers) {
+        dispose();
+      }
+    },
+  };
+}
+
+// Minimal structural type for cue-target traversal. Works in real browsers
+// (Element.getAttribute / Element.children as HTMLCollection) and in test stubs
+// (getAttribute method + children as array). Does not widen LayoutRendererElement.
+interface CueTargetNode {
+  getAttribute?(name: string): string | null;
+  setAttribute(name: string, value: string): void;
+  children?: ArrayLike<CueTargetNode> | CueTargetNode[];
+}
+
+function handleDomCue(world: LayoutRendererElement, action: CueAction): void {
+  const { type, payload } = action;
+  const target = action.target ?? payloadTarget(payload);
+  switch (type) {
+    case "show":
+    case "hide": {
+      if (target === undefined) {
+        return;
+      }
+      const el = findCueTarget(world as unknown as CueTargetNode, target);
+      el?.setAttribute(
+        "data-velumo-cue",
+        type === "show" ? "visible" : "hidden",
+      );
+      return;
+    }
+    case "fx": {
+      world.setAttribute("data-velumo-fx", "fired");
+      return;
+    }
+    case "setClass": {
+      if (target === undefined) {
+        return;
+      }
+      // Require payload to be a plain object to read className from it.
+      if (
+        payload === null ||
+        typeof payload !== "object" ||
+        Array.isArray(payload)
+      ) {
+        return;
+      }
+      const p = payload as { className?: unknown; mode?: unknown };
+      if (typeof p.className !== "string" || p.className === "") {
+        return;
+      }
+      const className = p.className;
+      const mode =
+        p.mode === "remove" || p.mode === "toggle"
+          ? (p.mode as "remove" | "toggle")
+          : "add";
+      const el = findCueTarget(world as unknown as CueTargetNode, target);
+      if (el === undefined) {
+        return;
+      }
+      // Read the existing class attribute via getAttribute so this works in
+      // both real browsers (Element.getAttribute) and test stubs.
+      const existing =
+        typeof el.getAttribute === "function"
+          ? (el.getAttribute("data-velumo-cue-class") ?? "")
+          : "";
+      const parts = existing.split(" ").filter((s: string) => s.length > 0);
+      const set = new Set(parts);
+      if (mode === "add") {
+        set.add(className);
+      } else if (mode === "remove") {
+        set.delete(className);
+      } else {
+        if (set.has(className)) {
+          set.delete(className);
+        } else {
+          set.add(className);
+        }
+      }
+      el.setAttribute("data-velumo-cue-class", [...set].sort().join(" "));
+      return;
+    }
+    default:
+      return;
+  }
+}
+
+export function findCueTarget(
+  world: CueTargetNode,
+  target: string,
+): CueTargetNode | undefined {
+  const id = target.startsWith("#") ? target.slice(1) : target;
+  const stack: CueTargetNode[] = [world];
+  while (stack.length > 0) {
+    const node = stack.pop() as CueTargetNode;
+    // Use getAttribute when available (real browsers + stubs that implement it).
+    const nodeId =
+      typeof node.getAttribute === "function"
+        ? node.getAttribute("id")
+        : undefined;
+    if (nodeId === id) {
+      return node;
+    }
+    // Array.from handles both HTMLCollection (real browser) and plain arrays (stubs).
+    const kids = node.children;
+    if (kids !== undefined) {
+      for (const k of Array.from(kids)) {
+        stack.push(k);
+      }
+    }
+  }
+  return undefined;
+}

package/src/browser-sync.ts

@@ -0,0 +1,151 @@
+import type { RuntimeState } from "@velumo/runtime";
+
+export type PresenterCommand = "next" | "previous" | "resetTimer";
+
+export type PresenterSyncMessage =
+  | {
+      readonly source: "audience";
+      readonly instanceId: string;
+      readonly type: "state";
+      readonly state: RuntimeState;
+    }
+  | {
+      readonly source: "presenter";
+      readonly instanceId: string;
+      readonly type: "command";
+      readonly command: PresenterCommand;
+    };
+
+interface PresenterSyncEvent {
+  readonly data: unknown;
+}
+
+export interface PresenterSyncChannel {
+  addEventListener(
+    type: "message",
+    listener: (event: PresenterSyncEvent) => void,
+  ): void;
+  close?(): void;
+  postMessage(message: PresenterSyncMessage): void;
+  unref?(): void;
+}
+
+export interface PresenterSyncOptions {
+  readonly channel: PresenterSyncChannel;
+  readonly instanceId: string;
+  readonly role: "audience" | "presenter";
+  readonly onCommand?: (command: PresenterCommand) => void;
+  readonly onState?: (state: RuntimeState) => void;
+}
+
+export interface PresenterSync {
+  dispose(): void;
+  publishCommand(command: PresenterCommand): void;
+  publishState(state: RuntimeState): void;
+}
+
+export function createPresenterSync(
+  options: PresenterSyncOptions,
+): PresenterSync {
+  options.channel.addEventListener("message", (event) => {
+    const message = parsePresenterSyncMessage(event.data);
+
+    if (message === undefined || message.instanceId === options.instanceId) {
+      return;
+    }
+
+    if (options.role === "audience" && message.type === "command") {
+      options.onCommand?.(message.command);
+      return;
+    }
+
+    if (options.role === "presenter" && message.type === "state") {
+      options.onState?.(message.state);
+    }
+  });
+
+  return {
+    dispose() {
+      options.channel.close?.();
+    },
+    publishCommand(command) {
+      options.channel.postMessage({
+        source: "presenter",
+        instanceId: options.instanceId,
+        type: "command",
+        command,
+      });
+    },
+    publishState(state) {
+      options.channel.postMessage({
+        source: "audience",
+        instanceId: options.instanceId,
+        type: "state",
+        state,
+      });
+    },
+  };
+}
+
+function parsePresenterSyncMessage(
+  message: unknown,
+): PresenterSyncMessage | undefined {
+  if (message === null || typeof message !== "object") {
+    return undefined;
+  }
+
+  const candidate = message as {
+    readonly command?: unknown;
+    readonly instanceId?: unknown;
+    readonly source?: unknown;
+    readonly state?: unknown;
+    readonly type?: unknown;
+  };
+
+  if (typeof candidate.instanceId !== "string") {
+    return undefined;
+  }
+
+  if (
+    candidate.source === "audience" &&
+    candidate.type === "state" &&
+    isRuntimeState(candidate.state)
+  ) {
+    return {
+      source: "audience",
+      instanceId: candidate.instanceId,
+      type: "state",
+      state: candidate.state,
+    };
+  }
+
+  if (
+    candidate.source === "presenter" &&
+    candidate.type === "command" &&
+    isPresenterCommand(candidate.command)
+  ) {
+    return {
+      source: "presenter",
+      instanceId: candidate.instanceId,
+      type: "command",
+      command: candidate.command,
+    };
+  }
+
+  return undefined;
+}
+
+function isPresenterCommand(command: unknown): command is PresenterCommand {
+  return (
+    command === "next" || command === "previous" || command === "resetTimer"
+  );
+}
+
+function isRuntimeState(state: unknown): state is RuntimeState {
+  if (state === null || typeof state !== "object") {
+    return false;
+  }
+
+  const candidate = state as { readonly slideId?: unknown };
+  return typeof candidate.slideId === "string";
+}

package/src/browser-timer.ts

@@ -0,0 +1,24 @@
+export interface PresenterTimerOptions {
+  readonly now?: () => number;
+}
+
+export interface PresenterTimer {
+  elapsedMs(): number;
+  reset(): void;
+}
+
+export function createPresenterTimer(
+  options: PresenterTimerOptions = {},
+): PresenterTimer {
+  const now = options.now ?? Date.now;
+  let startedAt = now();
+
+  return {
+    elapsedMs() {
+      return Math.max(0, now() - startedAt);
+    },
+    reset() {
+      startedAt = now();
+    },
+  };
+}