@velumo/runtime 0.1.0-beta.0

package/src/controller.ts

@@ -0,0 +1,171 @@
+import type { Manifest, SlideEntry, SlideKind } from "@velumo/core";
+
+export interface RuntimeState {
+  readonly deckTitle: string;
+  readonly slideIndex: number;
+  readonly slideId: string;
+  readonly slideKind: SlideKind;
+  readonly fragmentIndex: number;
+  readonly fragmentCount: number;
+  readonly isFirstSlide: boolean;
+  readonly isLastSlide: boolean;
+}
+
+export interface RuntimeControllerOptions {
+  readonly initialSlideId?: string;
+  readonly initialFragmentIndex?: number;
+}
+
+export type RuntimeEventName = "slide:enter" | "slide:leave" | "state:change";
+
+export interface RuntimeEvent {
+  readonly slideId: string;
+  readonly slideIndex: number;
+  readonly state: RuntimeState;
+}
+
+type RuntimeEventHandler = (event: RuntimeEvent) => void;
+
+function fragmentCountFor(slide: SlideEntry): number {
+  return slide.fragments?.length ?? 0;
+}
+
+function clampFragmentIndex(slide: SlideEntry, index: number): number {
+  return Math.max(0, Math.min(index, fragmentCountFor(slide)));
+}
+
+export class RuntimeController {
+  readonly #manifest: Manifest;
+  #slideIndex: number;
+  #fragmentIndex: number;
+  readonly #handlers = new Map<RuntimeEventName, Set<RuntimeEventHandler>>();
+
+  constructor(manifest: Manifest, options: RuntimeControllerOptions = {}) {
+    this.#manifest = manifest;
+    this.#slideIndex = this.#initialSlideIndex(options.initialSlideId);
+    this.#fragmentIndex = clampFragmentIndex(
+      this.#currentSlide(),
+      options.initialFragmentIndex ?? 0,
+    );
+  }
+
+  getState(): RuntimeState {
+    const slide = this.#currentSlide();
+
+    return {
+      deckTitle: this.#manifest.deck.title,
+      slideIndex: this.#slideIndex,
+      slideId: slide.id,
+      slideKind: slide.kind,
+      fragmentIndex: this.#fragmentIndex,
+      fragmentCount: fragmentCountFor(slide),
+      isFirstSlide: this.#slideIndex === 0,
+      isLastSlide: this.#slideIndex === this.#manifest.slides.length - 1,
+    };
+  }
+
+  next(): boolean {
+    const slide = this.#currentSlide();
+    const fragmentCount = fragmentCountFor(slide);
+
+    if (this.#fragmentIndex < fragmentCount) {
+      this.#fragmentIndex += 1;
+      this.#emit("state:change", slide);
+      return true;
+    }
+
+    if (this.#slideIndex >= this.#manifest.slides.length - 1) {
+      return false;
+    }
+
+    this.#moveToSlide(this.#slideIndex + 1, 0);
+    return true;
+  }
+
+  previous(): boolean {
+    const slide = this.#currentSlide();
+
+    if (this.#fragmentIndex > 0) {
+      this.#fragmentIndex -= 1;
+      this.#emit("state:change", slide);
+      return true;
+    }
+
+    if (this.#slideIndex <= 0) {
+      return false;
+    }
+
+    const targetIndex = this.#slideIndex - 1;
+    const targetSlide = this.#manifest.slides[targetIndex];
+    this.#moveToSlide(targetIndex, fragmentCountFor(targetSlide));
+    return true;
+  }
+
+  jumpToSlide(id: string): boolean {
+    const targetIndex = this.#manifest.slides.findIndex(
+      (slide) => slide.id === id,
+    );
+
+    if (targetIndex === -1 || targetIndex === this.#slideIndex) {
+      return false;
+    }
+
+    this.#moveToSlide(targetIndex, 0);
+    return true;
+  }
+
+  on(eventName: RuntimeEventName, handler: RuntimeEventHandler): () => void {
+    const handlers = this.#handlers.get(eventName) ?? new Set();
+    handlers.add(handler);
+    this.#handlers.set(eventName, handlers);
+
+    return () => {
+      handlers.delete(handler);
+    };
+  }
+
+  #initialSlideIndex(initialSlideId: string | undefined): number {
+    if (initialSlideId === undefined) {
+      return 0;
+    }
+
+    const index = this.#manifest.slides.findIndex(
+      (slide) => slide.id === initialSlideId,
+    );
+
+    return index === -1 ? 0 : index;
+  }
+
+  #currentSlide(): SlideEntry {
+    return this.#manifest.slides[this.#slideIndex];
+  }
+
+  #moveToSlide(targetIndex: number, fragmentIndex: number): void {
+    const previousSlide = this.#currentSlide();
+    const targetSlide = this.#manifest.slides[targetIndex];
+
+    this.#emit("slide:leave", previousSlide);
+    this.#slideIndex = targetIndex;
+    this.#fragmentIndex = clampFragmentIndex(targetSlide, fragmentIndex);
+    this.#emit("slide:enter", targetSlide);
+    this.#emit("state:change", targetSlide);
+  }
+
+  #emit(eventName: RuntimeEventName, slide: SlideEntry): void {
+    const handlers = this.#handlers.get(eventName);
+
+    if (handlers === undefined) {
+      return;
+    }
+
+    const event: RuntimeEvent = {
+      slideId: slide.id,
+      slideIndex: this.#slideIndex,
+      state: this.getState(),
+    };
+
+    for (const handler of handlers) {
+      handler(event);
+    }
+  }
+}

package/src/cue-dispatcher.ts

@@ -0,0 +1,299 @@
+import type { Cue, JsonValue } from "@velumo/core";
+import { ActionDispatcher, type ActionContext } from "./action-dispatcher.js";
+import type { ActionHandler, RuntimeRegistry } from "./registry.js";
+import type { TimelineScheduler } from "./timeline.js";
+
+const ERROR_PREFIX = "CueDispatcher: ";
+
+// The cue path's handler context. Extends the generalized ActionContext,
+// narrowing source to "cue" and making the cue-only fields required (they are
+// always populated when a timeline cue fires). Built-in action factories read
+// context.cue / cueIndex / timeMs, so they keep working unchanged.
+export interface CueDispatchEvent extends ActionContext {
+  readonly source: "cue";
+  readonly cue: Cue;
+  readonly cueIndex: number;
+  readonly timeMs: number;
+}
+
+export interface CueDispatcherOptions {
+  readonly scheduler: TimelineScheduler;
+  readonly registry: RuntimeRegistry<unknown, unknown, CueDispatchEvent>;
+}
+
+export interface CueDispatcherResult {
+  dispose(): void;
+}
+
+export class CueDispatcher implements CueDispatcherResult {
+  readonly #disposeFromScheduler: () => void;
+  #disposed = false;
+
+  constructor(options: CueDispatcherOptions) {
+    // Both the cue path (here) and the control path route lookup+invoke through
+    // the same ActionDispatcher. The dispatcher never throws for a missing
+    // handler; the cue path re-imposes its throw-on-unknown contract on false.
+    const dispatcher = new ActionDispatcher<CueDispatchEvent>({
+      registry: options.registry,
+    });
+    this.#disposeFromScheduler = options.scheduler.on("cue:fired", (event) => {
+      if (event.type !== "cue:fired") {
+        return;
+      }
+      const actionType = event.cue.action.type;
+      const context: CueDispatchEvent = {
+        action: event.cue.action,
+        payload: event.cue.action.payload,
+        source: "cue",
+        cue: event.cue,
+        cueIndex: event.cueIndex,
+        timeMs: event.timeMs,
+        // Thread the action's top-level target on the cue path too (the control
+        // path already does), so a handler branching on context.target sees the
+        // same value regardless of which path fired it.
+        ...(event.cue.action.target === undefined
+          ? {}
+          : { target: event.cue.action.target }),
+      };
+      const handled = dispatcher.dispatch(actionType, context);
+      if (!handled) {
+        throw new Error(
+          `${ERROR_PREFIX}no action handler registered for type '${actionType}'`,
+        );
+      }
+    });
+  }
+
+  dispose(): void {
+    if (this.#disposed) {
+      return;
+    }
+    this.#disposed = true;
+    this.#disposeFromScheduler();
+  }
+}
+
+export function createCueDispatcher(
+  options: CueDispatcherOptions,
+): CueDispatcher {
+  return new CueDispatcher(options);
+}
+
+export type BuiltInActionType =
+  | "show"
+  | "hide"
+  | "setClass"
+  | "emit"
+  | "camera"
+  | "fx";
+
+const _builtInActionTypeCheck: BuiltInActionType = "show";
+void _builtInActionTypeCheck;
+
+export interface ShowActionEvent {
+  readonly type: "show";
+  readonly target: string;
+  readonly cue: Cue;
+  readonly cueIndex: number;
+  readonly timeMs: number;
+}
+
+export interface HideActionEvent {
+  readonly type: "hide";
+  readonly target: string;
+  readonly cue: Cue;
+  readonly cueIndex: number;
+  readonly timeMs: number;
+}
+
+export interface SetClassActionEvent {
+  readonly type: "setClass";
+  readonly target: string;
+  readonly className: string;
+  readonly mode: "add" | "remove" | "toggle";
+  readonly cue: Cue;
+  readonly cueIndex: number;
+  readonly timeMs: number;
+}
+
+export interface EmitActionEvent {
+  readonly type: "emit";
+  readonly name: string;
+  readonly data: JsonValue | undefined;
+  readonly cue: Cue;
+  readonly cueIndex: number;
+  readonly timeMs: number;
+}
+
+export interface CameraActionEvent {
+  readonly type: "camera";
+  readonly payload: JsonValue | undefined;
+  readonly cue: Cue;
+  readonly cueIndex: number;
+  readonly timeMs: number;
+}
+
+export interface FxActionEvent {
+  readonly type: "fx";
+  readonly payload: JsonValue | undefined;
+  readonly cue: Cue;
+  readonly cueIndex: number;
+  readonly timeMs: number;
+}
+
+function requirePayloadObject(
+  payload: JsonValue | undefined,
+  actionType: BuiltInActionType,
+): Record<string, JsonValue> {
+  if (
+    payload === undefined ||
+    payload === null ||
+    typeof payload !== "object" ||
+    Array.isArray(payload)
+  ) {
+    const describe =
+      payload === undefined
+        ? "undefined"
+        : payload === null
+          ? "null"
+          : Array.isArray(payload)
+            ? "array"
+            : typeof payload;
+    throw new Error(
+      `${ERROR_PREFIX}${actionType} action requires payload object; got ${describe}`,
+    );
+  }
+  return payload as Record<string, JsonValue>;
+}
+
+function requireNonEmptyString(
+  payload: Record<string, JsonValue>,
+  field: string,
+  actionType: BuiltInActionType,
+): string {
+  const value = payload[field];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(
+      `${ERROR_PREFIX}${actionType} action payload.${field} must be a non-empty string; got ${
+        typeof value === "string" ? "''" : String(value)
+      }`,
+    );
+  }
+  return value;
+}
+
+function readSetClassMode(
+  payload: Record<string, JsonValue>,
+): "add" | "remove" | "toggle" {
+  const mode = payload.mode;
+  if (mode === undefined) {
+    return "add";
+  }
+  if (mode === "add" || mode === "remove" || mode === "toggle") {
+    return mode;
+  }
+  throw new Error(
+    `${ERROR_PREFIX}setClass action payload.mode must be 'add' | 'remove' | 'toggle' (or omitted); got ${String(mode)}`,
+  );
+}
+
+export function createShowAction(
+  callback: (event: ShowActionEvent) => void,
+): ActionHandler<CueDispatchEvent> {
+  return (context) => {
+    const payload = requirePayloadObject(context.cue.action.payload, "show");
+    const target = requireNonEmptyString(payload, "target", "show");
+    callback({
+      type: "show",
+      target,
+      cue: context.cue,
+      cueIndex: context.cueIndex,
+      timeMs: context.timeMs,
+    });
+  };
+}
+
+export function createHideAction(
+  callback: (event: HideActionEvent) => void,
+): ActionHandler<CueDispatchEvent> {
+  return (context) => {
+    const payload = requirePayloadObject(context.cue.action.payload, "hide");
+    const target = requireNonEmptyString(payload, "target", "hide");
+    callback({
+      type: "hide",
+      target,
+      cue: context.cue,
+      cueIndex: context.cueIndex,
+      timeMs: context.timeMs,
+    });
+  };
+}
+
+export function createSetClassAction(
+  callback: (event: SetClassActionEvent) => void,
+): ActionHandler<CueDispatchEvent> {
+  return (context) => {
+    const payload = requirePayloadObject(
+      context.cue.action.payload,
+      "setClass",
+    );
+    const target = requireNonEmptyString(payload, "target", "setClass");
+    const className = requireNonEmptyString(payload, "className", "setClass");
+    const mode = readSetClassMode(payload);
+    callback({
+      type: "setClass",
+      target,
+      className,
+      mode,
+      cue: context.cue,
+      cueIndex: context.cueIndex,
+      timeMs: context.timeMs,
+    });
+  };
+}
+
+export function createEmitAction(
+  callback: (event: EmitActionEvent) => void,
+): ActionHandler<CueDispatchEvent> {
+  return (context) => {
+    const payload = requirePayloadObject(context.cue.action.payload, "emit");
+    const name = requireNonEmptyString(payload, "name", "emit");
+    const data = payload.data;
+    callback({
+      type: "emit",
+      name,
+      data,
+      cue: context.cue,
+      cueIndex: context.cueIndex,
+      timeMs: context.timeMs,
+    });
+  };
+}
+
+export function createCameraAction(
+  callback: (event: CameraActionEvent) => void,
+): ActionHandler<CueDispatchEvent> {
+  return (context) => {
+    callback({
+      type: "camera",
+      payload: context.cue.action.payload,
+      cue: context.cue,
+      cueIndex: context.cueIndex,
+      timeMs: context.timeMs,
+    });
+  };
+}
+
+export function createFxAction(
+  callback: (event: FxActionEvent) => void,
+): ActionHandler<CueDispatchEvent> {
+  return (context) => {
+    callback({
+      type: "fx",
+      payload: context.cue.action.payload,
+      cue: context.cue,
+      cueIndex: context.cueIndex,
+      timeMs: context.timeMs,
+    });
+  };
+}

package/src/hash.ts

@@ -0,0 +1,39 @@
+import type { RuntimeState } from "./controller.js";
+
+export interface RuntimeHashOptions {
+  readonly initialSlideId?: string;
+  readonly initialFragmentIndex?: number;
+}
+
+export function serializeRuntimeHash(state: RuntimeState): string {
+  const params = new URLSearchParams({
+    slide: state.slideId,
+    fragment: String(state.fragmentIndex),
+  });
+
+  return `#${params.toString()}`;
+}
+
+export function parseRuntimeHash(hash: string): RuntimeHashOptions {
+  const source = hash.startsWith("#") ? hash.slice(1) : hash;
+  const params = new URLSearchParams(source);
+  const initialSlideId = params.get("slide") ?? undefined;
+  const initialFragmentIndex = parseFragmentIndex(params.get("fragment"));
+
+  return {
+    ...(initialSlideId === undefined ? {} : { initialSlideId }),
+    ...(initialFragmentIndex === undefined ? {} : { initialFragmentIndex }),
+  };
+}
+
+function parseFragmentIndex(fragment: string | null): number | undefined {
+  if (fragment === null) {
+    return undefined;
+  }
+
+  const parsedFragment = Number(fragment);
+
+  return Number.isInteger(parsedFragment) && parsedFragment >= 0
+    ? parsedFragment
+    : undefined;
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export const runtimePackageName = "@velumo/runtime";
+export * from "./controller.js";
+export * from "./hash.js";
+export * from "./notes.js";
+export * from "./registry.js";
+export * from "./timeline.js";
+export * from "./cue-dispatcher.js";
+export * from "./action-dispatcher.js";
+export * from "./camera.js";
+export * from "./spatial.js";
+export * from "./scene-player.js";
+export * from "./theme-bundle.js";

package/src/notes.ts

@@ -0,0 +1,194 @@
+import type { Manifest, SlideKind } from "@velumo/core";
+import type { RuntimeController, RuntimeState } from "./controller.js";
+
+export type SpeakerNoteBlock =
+  | {
+      readonly type: "heading";
+      readonly level: 1 | 2 | 3;
+      readonly text: string;
+    }
+  | { readonly type: "paragraph"; readonly text: string }
+  | { readonly type: "list"; readonly items: readonly string[] }
+  | { readonly type: "code"; readonly text: string };
+
+export interface SpeakerNotesEntry {
+  readonly slideId: string;
+  readonly slideIndex: number;
+  readonly slideKind: SlideKind;
+  readonly raw: string;
+  readonly plainText: string;
+  readonly hasNotes: boolean;
+  readonly blocks: readonly SpeakerNoteBlock[];
+}
+
+export interface SpeakerNotesModel {
+  getBySlideId(slideId: string): SpeakerNotesEntry;
+  getForState(state: RuntimeState): SpeakerNotesEntry;
+  getForRuntime(runtime: RuntimeController): SpeakerNotesEntry;
+}
+
+const speakerNoteCodeFence = "```";
+const speakerNoteHeadingPattern = /^(#{1,3})\s+(.+)$/;
+const speakerNoteListItemPattern = /^[-*]\s+/;
+
+export function createSpeakerNotesModel(manifest: Manifest): SpeakerNotesModel {
+  return {
+    getBySlideId(slideId) {
+      return notesForSlide(manifest, slideId);
+    },
+    getForState(state) {
+      return notesForSlide(manifest, state.slideId);
+    },
+    getForRuntime(runtime) {
+      return notesForSlide(manifest, runtime.getState().slideId);
+    },
+  };
+}
+
+function notesForSlide(manifest: Manifest, slideId: string): SpeakerNotesEntry {
+  const slideIndex = manifest.slides.findIndex((slide) => slide.id === slideId);
+  const slide = manifest.slides[slideIndex];
+
+  if (slide === undefined) {
+    return emptyNotes(slideId);
+  }
+
+  const raw = slide.notes ?? "";
+  const blocks = raw.trim().length === 0 ? [] : parseSpeakerNoteBlocks(raw);
+
+  return {
+    slideId: slide.id,
+    slideIndex,
+    slideKind: slide.kind,
+    raw,
+    plainText: blocksToPlainText(blocks),
+    hasNotes: raw.trim().length > 0,
+    blocks,
+  };
+}
+
+function emptyNotes(slideId: string): SpeakerNotesEntry {
+  return {
+    slideId,
+    slideIndex: -1,
+    slideKind: "slide",
+    raw: "",
+    plainText: "",
+    hasNotes: false,
+    blocks: [],
+  };
+}
+
+function parseSpeakerNoteBlocks(source: string): SpeakerNoteBlock[] {
+  const blocks: SpeakerNoteBlock[] = [];
+  const lines = source.replace(/\r\n?/g, "\n").split("\n");
+  let index = 0;
+
+  while (index < lines.length) {
+    const trimmedLine = lines[index].trim();
+
+    if (trimmedLine.length === 0) {
+      index += 1;
+      continue;
+    }
+
+    if (trimmedLine === speakerNoteCodeFence) {
+      const codeLines: string[] = [];
+      index += 1;
+
+      while (
+        index < lines.length &&
+        lines[index].trim() !== speakerNoteCodeFence
+      ) {
+        codeLines.push(lines[index]);
+        index += 1;
+      }
+
+      blocks.push({ type: "code", text: codeLines.join("\n") });
+      if (index < lines.length) {
+        index += 1;
+      }
+      continue;
+    }
+
+    const headingMatch = trimmedLine.match(speakerNoteHeadingPattern);
+    if (headingMatch !== null) {
+      blocks.push({
+        type: "heading",
+        level: headingMatch[1].length as 1 | 2 | 3,
+        text: cleanInlineText(headingMatch[2]),
+      });
+      index += 1;
+      continue;
+    }
+
+    if (speakerNoteListItemPattern.test(trimmedLine)) {
+      const items: string[] = [];
+
+      while (
+        index < lines.length &&
+        speakerNoteListItemPattern.test(lines[index].trim())
+      ) {
+        items.push(
+          cleanInlineText(
+            lines[index].trim().replace(speakerNoteListItemPattern, ""),
+          ),
+        );
+        index += 1;
+      }
+
+      blocks.push({ type: "list", items });
+      continue;
+    }
+
+    const paragraphLines: string[] = [];
+
+    while (index < lines.length && isSpeakerNoteParagraphLine(lines[index])) {
+      paragraphLines.push(lines[index].trim());
+      index += 1;
+    }
+
+    blocks.push({
+      type: "paragraph",
+      text: cleanInlineText(paragraphLines.join(" ")),
+    });
+  }
+
+  return blocks;
+}
+
+function isSpeakerNoteParagraphLine(line: string): boolean {
+  const trimmedLine = line.trim();
+
+  return (
+    trimmedLine.length > 0 &&
+    trimmedLine !== speakerNoteCodeFence &&
+    trimmedLine.match(speakerNoteHeadingPattern) === null &&
+    !speakerNoteListItemPattern.test(trimmedLine)
+  );
+}
+
+function cleanInlineText(source: string): string {
+  return source
+    .replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gi, "$1")
+    .replace(/<\/?[^>]+>/g, "")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/\*([^*]+)\*/g, "$1")
+    .trim();
+}
+
+function blocksToPlainText(blocks: readonly SpeakerNoteBlock[]): string {
+  return blocks
+    .map((block) => {
+      switch (block.type) {
+        case "heading":
+        case "paragraph":
+        case "code":
+          return block.text;
+        case "list":
+          return block.items.join("\n");
+      }
+    })
+    .join("\n\n");
+}