@velumo/cli 0.1.0-beta.0

package/src/browser-runtime.ts

@@ -0,0 +1,493 @@
+import {
+  createRuntimeRegistry,
+  installPlugins,
+  parseRuntimeHash,
+  RuntimeController,
+  serializeRuntimeHash,
+  type VelumoPlugin,
+  type RuntimeControllerOptions,
+  type RuntimeRegistry,
+} from "@velumo/runtime";
+import {
+  DomRenderer,
+  mountSlideThumbnail,
+  type DomRendererOptions,
+} from "@velumo/renderer-dom";
+import type { Manifest } from "@velumo/core";
+import {
+  createPresenterSync,
+  type PresenterCommand,
+  type PresenterSyncChannel,
+} from "./browser-sync.js";
+import {
+  setupOverviewMode,
+  type OverviewMountOptions,
+  type OverviewRootLike,
+  type OverviewWindowLike,
+} from "./browser-overview.js";
+import {
+  createSpatialSession,
+  type SpatialSession,
+} from "./browser-spatial.js";
+
+interface ManifestResponse {
+  readonly ok: boolean;
+  readonly status: number;
+  json(): Promise<Manifest>;
+}
+
+type BrowserRoot = DomRendererOptions["root"];
+type BrowserRenderer = Pick<DomRenderer, "mount"> &
+  Partial<Pick<DomRenderer, "render" | "getRoot">>;
+type RuntimeFactory = (
+  manifest: Manifest,
+  options?: RuntimeControllerOptions,
+) => RuntimeController;
+type RendererFactory = (options: DomRendererOptions) => BrowserRenderer;
+
+interface BrowserKeyboardEvent {
+  readonly key: string;
+  readonly target: unknown;
+  preventDefault(): void;
+}
+
+interface BrowserWindowLike {
+  readonly BroadcastChannel?: new (name: string) => PresenterSyncChannel;
+  readonly crypto?: { randomUUID?(): string };
+  readonly location: {
+    hash: string;
+  };
+  addEventListener(
+    type: "keydown",
+    handler: (event: BrowserKeyboardEvent) => void,
+  ): void;
+  removeEventListener(
+    type: "keydown",
+    handler: (event: BrowserKeyboardEvent) => void,
+  ): void;
+}
+
+interface BrowserRuntimeGlobals {
+  readonly BroadcastChannel?: new (name: string) => PresenterSyncChannel;
+}
+
+export interface BrowserRuntimeMountOptions {
+  readonly root: BrowserRoot | null | undefined;
+  readonly manifestUrl: string;
+  readonly keyboard?: boolean;
+  readonly urlState?: boolean;
+  readonly window?: BrowserWindowLike;
+  readonly createRuntime?: RuntimeFactory;
+  readonly createRenderer?: RendererFactory;
+  readonly plugins?: readonly VelumoPlugin<unknown, unknown, unknown>[];
+}
+
+export interface BrowserRuntimeMountResult {
+  readonly manifest: Manifest;
+  readonly runtime: RuntimeController;
+  readonly renderer: BrowserRenderer;
+  readonly registry?: RuntimeRegistry<unknown, unknown, unknown>;
+}
+
+export async function mountVelumoBrowserRuntime(
+  options: BrowserRuntimeMountOptions,
+): Promise<BrowserRuntimeMountResult | undefined> {
+  if (options.root === null || options.root === undefined) {
+    throw new Error("Velumo root element not found");
+  }
+
+  const root = options.root;
+
+  try {
+    const response = (await fetch(options.manifestUrl)) as ManifestResponse;
+
+    if (!response.ok) {
+      throw new Error(`manifest request failed with status ${response.status}`);
+    }
+
+    const manifest = await response.json();
+    const browserWindow = options.window ?? getGlobalWindow();
+    const runtimeOptions =
+      options.urlState === false || browserWindow === undefined
+        ? {}
+        : parseRuntimeHash(browserWindow.location.hash);
+    const runtime =
+      options.createRuntime?.(manifest, runtimeOptions) ??
+      new RuntimeController(manifest, runtimeOptions);
+
+    // Ward 033 contract alignment: install plugins (if provided) into a fresh
+    // runtime registry, then thread the registry into the DOM renderer so its
+    // custom-layer-renderer dispatch can resolve fx:* / custom layer types
+    // against the plugin-registered renderers. Type-erased handoff at this
+    // boundary: RuntimeRegistry<unknown,unknown,unknown> is structurally
+    // satisfied by DomRendererOptions["registry"].
+    const installedPlugins = options.plugins ?? [];
+    const registry =
+      installedPlugins.length > 0
+        ? createRuntimeRegistry<unknown, unknown, unknown>()
+        : undefined;
+    if (registry !== undefined) {
+      installPlugins({ registry, manifest, plugins: installedPlugins });
+    }
+    const rendererOptions: DomRendererOptions = {
+      root,
+      manifest,
+      runtime,
+      registry: registry as DomRendererOptions["registry"],
+    };
+    const renderer =
+      options.createRenderer?.(rendererOptions) ??
+      new DomRenderer(rendererOptions);
+
+    renderer.mount();
+    const urlState = options.urlState !== false;
+    setupBrowserControls({
+      keyboard: options.keyboard !== false,
+      urlState,
+      window: browserWindow,
+      manifest,
+      runtime,
+      renderer,
+    });
+    armSpatialForCurrentSlide(
+      {
+        urlState,
+        window: browserWindow,
+        manifest,
+        runtime,
+        renderer,
+      },
+      "forward",
+    );
+    setupPresenterAudienceSync({
+      urlState,
+      window: browserWindow,
+      manifest,
+      runtime,
+      renderer,
+    });
+
+    if (browserWindow !== undefined) {
+      setupOverviewMode({
+        root: root as unknown as OverviewRootLike,
+        runtime,
+        manifest,
+        window: browserWindow as unknown as OverviewWindowLike,
+        // Thread the plugin registry into overview thumbnails so plugin-
+        // registered layer renderers (e.g. fx:*) render real content, not
+        // fallback layer-type text.
+        mountThumbnail: ((opts: {
+          root: unknown;
+          manifest: unknown;
+          slideId: string;
+        }) =>
+          mountSlideThumbnail({
+            root: opts.root as Parameters<
+              typeof mountSlideThumbnail
+            >[0]["root"],
+            manifest: opts.manifest as Parameters<
+              typeof mountSlideThumbnail
+            >[0]["manifest"],
+            slideId: opts.slideId,
+            registry: registry as DomRendererOptions["registry"],
+          })) as unknown as OverviewMountOptions["mountThumbnail"],
+        onAfterJump: () => {
+          renderer.render?.();
+          armSpatialForCurrentSlide(
+            {
+              urlState,
+              window: browserWindow,
+              manifest,
+              runtime,
+              renderer,
+            },
+            "forward",
+          );
+          if (urlState) {
+            browserWindow.location.hash = serializeRuntimeHash(
+              runtime.getState(),
+            );
+          }
+        },
+      });
+    }
+
+    return { manifest, runtime, renderer, registry };
+  } catch (error) {
+    renderMountError(root, error);
+    return undefined;
+  }
+}
+
+function renderMountError(root: BrowserRoot, error: unknown): void {
+  const container = root.ownerDocument.createElement("section");
+  container.setAttribute("data-velumo-error", "mount");
+
+  const title = root.ownerDocument.createElement("h1");
+  title.textContent = "Velumo mount error";
+
+  const message = root.ownerDocument.createElement("p");
+  message.textContent =
+    error instanceof Error ? error.message : "Unknown browser runtime error";
+
+  container.append(title, message);
+  root.replaceChildren(container);
+  root.setAttribute("data-velumo-error", "mount");
+}
+
+interface BrowserControlsOptions {
+  readonly keyboard: boolean;
+  readonly urlState: boolean;
+  readonly window: BrowserWindowLike | undefined;
+  readonly manifest: Manifest;
+  readonly runtime: RuntimeController;
+  readonly renderer: BrowserRenderer;
+}
+
+type BrowserCommandOptions = Omit<BrowserControlsOptions, "keyboard">;
+
+function getGlobalWindow(): BrowserWindowLike | undefined {
+  return (globalThis as { window?: BrowserWindowLike }).window;
+}
+
+let activeSpatialSession: SpatialSession | undefined;
+
+function currentSlideEntry(options: BrowserCommandOptions) {
+  const state = options.runtime.getState();
+  return (
+    options.manifest.slides.find((slide) => slide.id === state.slideId) ??
+    options.manifest.slides[0]
+  );
+}
+
+function armSpatialForCurrentSlide(
+  options: BrowserCommandOptions,
+  direction: "forward" | "backward",
+): void {
+  activeSpatialSession?.dispose();
+  activeSpatialSession = undefined;
+  if (options.window === undefined) {
+    return;
+  }
+  const root = options.renderer.getRoot?.();
+  if (root === undefined) {
+    return;
+  }
+  activeSpatialSession = createSpatialSession({
+    root: root as unknown as Parameters<typeof createSpatialSession>[0]["root"],
+    slide: currentSlideEntry(options),
+    window: options.window as unknown as Parameters<
+      typeof createSpatialSession
+    >[0]["window"],
+    direction,
+  });
+}
+
+function setupBrowserControls(options: BrowserControlsOptions): void {
+  if (!options.keyboard || options.window === undefined) {
+    return;
+  }
+
+  const browserWindow = options.window;
+
+  browserWindow.addEventListener("keydown", (event) => {
+    if (isEditableTarget(event.target)) {
+      return;
+    }
+
+    const result = navigateWithKey(event.key, options);
+
+    if (result === undefined) {
+      return;
+    }
+
+    event.preventDefault();
+
+    if (result === "spatial") {
+      updateBrowserHash(options);
+      return;
+    }
+
+    if (result === "runtime-forward") {
+      applyRuntimeChange(options, "forward");
+      return;
+    }
+
+    if (result === "runtime-backward") {
+      applyRuntimeChange(options, "backward");
+    }
+    // "none" → preventDefault already called; nothing else
+  });
+}
+
+function setupPresenterAudienceSync(options: BrowserCommandOptions): void {
+  if (options.window === undefined) {
+    return;
+  }
+
+  const channel = createPresenterChannel(options.window);
+
+  if (channel === undefined) {
+    return;
+  }
+
+  const sync = createPresenterSync({
+    channel,
+    instanceId: createPresenterInstanceId(options.window),
+    role: "audience",
+    onCommand(command) {
+      applyPresenterCommand(command, options);
+    },
+  });
+
+  sync.publishState(options.runtime.getState());
+  options.runtime.on("state:change", (event) => {
+    sync.publishState(event.state);
+  });
+}
+
+function applyPresenterCommand(
+  command: PresenterCommand,
+  options: BrowserCommandOptions,
+): void {
+  const changed = runPresenterCommand(command, options.runtime);
+  if (!changed) {
+    return;
+  }
+  applyRuntimeChange(options, command === "previous" ? "backward" : "forward");
+}
+
+function applyRuntimeChange(
+  options: BrowserCommandOptions,
+  direction: "forward" | "backward",
+): void {
+  activeSpatialSession?.dispose();
+  activeSpatialSession = undefined;
+  options.renderer.render?.();
+  updateBrowserHash(options);
+  armSpatialForCurrentSlide(options, direction);
+}
+
+function updateBrowserHash(options: BrowserCommandOptions): void {
+  if (options.urlState && options.window !== undefined) {
+    options.window.location.hash = serializeRuntimeHash(
+      options.runtime.getState(),
+    );
+  }
+}
+
+function runPresenterCommand(
+  command: PresenterCommand,
+  runtime: RuntimeController,
+): boolean {
+  switch (command) {
+    case "next":
+      return runtime.next();
+    case "previous":
+      return runtime.previous();
+    case "resetTimer":
+      return false;
+  }
+}
+
+function createPresenterChannel(
+  browserWindow: BrowserWindowLike,
+): PresenterSyncChannel | undefined {
+  const BroadcastChannelCtor =
+    browserWindow.BroadcastChannel ??
+    (globalThis as BrowserRuntimeGlobals).BroadcastChannel;
+  if (BroadcastChannelCtor === undefined) {
+    return undefined;
+  }
+
+  const channel = new BroadcastChannelCtor("velumo-presenter");
+  channel.unref?.();
+  return channel;
+}
+
+function createPresenterInstanceId(browserWindow: BrowserWindowLike): string {
+  return (
+    browserWindow.crypto?.randomUUID?.() ??
+    `audience-${Math.random().toString(36).slice(2)}`
+  );
+}
+
+type NavigationResult =
+  | "spatial"
+  | "runtime-forward"
+  | "runtime-backward"
+  | "none"
+  | undefined;
+
+function navigateWithKey(
+  key: string,
+  options: BrowserControlsOptions,
+): NavigationResult {
+  switch (key) {
+    case " ":
+    case "Space":
+    case "Spacebar":
+    case "ArrowRight":
+    case "PageDown":
+    case "Enter": {
+      if (
+        activeSpatialSession !== undefined &&
+        activeSpatialSession.advance()
+      ) {
+        return "spatial";
+      }
+      return options.runtime.next() ? "runtime-forward" : "none";
+    }
+    case "ArrowLeft":
+    case "PageUp":
+    case "Backspace": {
+      if (activeSpatialSession !== undefined && activeSpatialSession.back()) {
+        return "spatial";
+      }
+      return options.runtime.previous() ? "runtime-backward" : "none";
+    }
+    case "Home": {
+      const firstSlide = options.manifest.slides[0];
+      if (firstSlide === undefined) {
+        return "none";
+      }
+      return options.runtime.jumpToSlide(firstSlide.id)
+        ? "runtime-forward"
+        : "none";
+    }
+    case "End": {
+      const lastSlide = options.manifest.slides.at(-1);
+      if (lastSlide === undefined) {
+        return "none";
+      }
+      return options.runtime.jumpToSlide(lastSlide.id)
+        ? "runtime-forward"
+        : "none";
+    }
+    default:
+      return undefined;
+  }
+}
+
+function isEditableTarget(target: unknown): boolean {
+  if (target === null || typeof target !== "object") {
+    return false;
+  }
+
+  const candidate = target as {
+    readonly isContentEditable?: boolean;
+    readonly tagName?: string;
+  };
+
+  if (candidate.isContentEditable === true) {
+    return true;
+  }
+
+  const tagName = candidate.tagName?.toLowerCase();
+  return (
+    tagName === "input" ||
+    tagName === "textarea" ||
+    tagName === "select" ||
+    tagName === "button"
+  );
+}