@velumo/renderer-dom 0.1.0-beta.0

package/src/dom-renderer.ts

@@ -0,0 +1,486 @@
+import type {
+  JsonValue,
+  Layer,
+  Manifest,
+  SlideEntry,
+  Theme,
+  ThemeTokens,
+} from "@velumo/core";
+import {
+  ActionDispatcher,
+  dispatchControlAction,
+  type ActionContext,
+  type ActionHandler,
+  type LayerRenderer,
+  type RuntimeController,
+} from "@velumo/runtime";
+import { defaultTheme } from "./default-theme.js";
+import { compileFontFaceCss, escapeCssString } from "./theme-fonts.js";
+import { tokensToCssProperties } from "./theme-tokens.js";
+import { renderBackground } from "./background-renderer.js";
+import { renderLayoutNode } from "./layout-renderer.js";
+import { renderSafeHtml } from "./html-sanitize.js";
+
+interface DomDocumentLike {
+  createElement(tagName: string): DomElementLike;
+  createElementNS(namespace: string, tagName: string): DomElementLike;
+  createTextNode(text: string): DomNodeLike;
+  readonly head?: DomElementLike;
+  querySelector?(selectors: string): DomElementLike | null;
+}
+
+type DomNodeChild = DomElementLike | DomNodeLike;
+type DomChild = DomNodeChild | string;
+type DomLayerRenderResult = DomChild | readonly DomChild[] | null | undefined;
+
+interface DomNodeLike {
+  parentNode?: unknown;
+  textContent: string;
+}
+
+interface DomElementLike extends DomNodeLike {
+  readonly ownerDocument: DomDocumentLike;
+  readonly style?: DomStyleLike;
+  append(...children: DomChild[]): void;
+  appendChild(child: DomNodeChild): DomNodeChild;
+  removeAttribute(name: string): void;
+  replaceChildren(...children: DomChild[]): void;
+  setAttribute(name: string, value: string): void;
+}
+
+interface DomStyleLike {
+  removeProperty(name: string): string;
+  setProperty(name: string, value: string): void;
+}
+
+export interface DomLayerRendererContext {
+  readonly layer: Layer;
+  readonly slide: SlideEntry;
+  readonly manifest: Manifest;
+  readonly runtime: RuntimeController;
+  createElement(tagName: string): DomElementLike;
+  createText(text: string): DomNodeLike;
+  // Imperative control (click) dispatch. Always bound; routes to a registered
+  // action handler via the Ward 042 ActionDispatcher with source:"control".
+  // A no-op when the registry has no matching handler (or no action handlers
+  // at all), never throws.
+  dispatch(action: { type: string; payload?: JsonValue }): void;
+}
+
+interface DomRuntimeRegistry {
+  getLayerRenderer(
+    type: string,
+  ): LayerRenderer<DomLayerRendererContext, DomLayerRenderResult> | undefined;
+  // Control-path handler lookup. Typed to the control context (ActionContext);
+  // the real generic RuntimeRegistry's ActionHandler<unknown> is assignable
+  // here. IMPORTANT: handlers reached this way are invoked with
+  // source:"control" and NO cue/cueIndex/timeMs. A handler shared with the
+  // timeline cue path must guard `if (context.source === "cue")` before
+  // touching cue-only fields (gate-3).
+  getActionHandler?(type: string): ActionHandler<ActionContext> | undefined;
+}
+
+export interface DomRendererOptions {
+  readonly root: DomElementLike;
+  readonly manifest: Manifest;
+  readonly runtime: RuntimeController;
+  readonly registry?: DomRuntimeRegistry;
+}
+
+export class DomRenderer {
+  readonly #root: DomElementLike;
+  readonly #manifest: Manifest;
+  readonly #runtime: RuntimeController;
+  readonly #registry: DomRuntimeRegistry | undefined;
+  readonly #actionDispatcher: ActionDispatcher<ActionContext> | undefined;
+  readonly #themeTokenProperties = new Set<string>();
+
+  constructor(options: DomRendererOptions) {
+    this.#root = options.root;
+    this.#manifest = options.manifest;
+    this.#runtime = options.runtime;
+    this.#registry = options.registry;
+    // One dispatcher over the active registry, reused by every layer context's
+    // dispatch. Absent when the registry has no action-handler seam (a minimal
+    // host) — control clicks then render inert.
+    const registry = options.registry;
+    this.#actionDispatcher =
+      registry?.getActionHandler !== undefined
+        ? new ActionDispatcher<ActionContext>({
+            registry: {
+              getActionHandler: (type) => registry.getActionHandler?.(type),
+            },
+          })
+        : undefined;
+  }
+
+  getRoot(): DomElementLike {
+    return this.#root;
+  }
+
+  mount(): void {
+    this.#root.setAttribute("data-velumo-renderer", "dom");
+    this.render();
+  }
+
+  render(): void {
+    this.#applyTheme();
+    this.#root.replaceChildren(this.#renderSlide(this.#currentSlide()));
+  }
+
+  unmount(): void {
+    this.#root.replaceChildren();
+    this.#root.removeAttribute("data-velumo-renderer");
+    this.#root.removeAttribute("data-velumo-theme");
+    this.#clearThemeTokenProperties();
+  }
+
+  dispose(): void {
+    this.unmount();
+  }
+
+  #applyTheme(): void {
+    const theme = this.#manifest.theme ?? defaultTheme;
+    const themeId = theme.id;
+
+    this.#root.setAttribute("data-velumo-theme", themeId);
+    this.#applyThemeTokenProperties(theme.tokens);
+    this.#applyThemeCss(theme);
+    this.#applyThemeFonts(theme);
+  }
+
+  // Injects the active theme's own CSS into document.head once per
+  // (document, theme id). The injected <style> is intentionally NOT removed on
+  // unmount: it is document-level and may be shared by other live renderers
+  // (e.g. the presenter mounts several). This is only safe because every rule a
+  // theme ships in `theme.css` is expected to be scoped to
+  // `[data-velumo-theme="<id>"]`, so a lingering style for an inactive theme
+  // matches nothing. A theme shipping unscoped rules here would leak across the page.
+  #applyThemeCss(theme: Theme): void {
+    const css = typeof theme.css === "string" ? theme.css : undefined;
+    if (css === undefined || css === "") {
+      return;
+    }
+    const doc = this.#root.ownerDocument;
+    const head = doc.head;
+    if (head === undefined || typeof doc.querySelector !== "function") {
+      return;
+    }
+    const marker = "data-velumo-theme-style";
+    if (
+      doc.querySelector(`[${marker}="${escapeCssString(theme.id)}"]`) !== null
+    ) {
+      return;
+    }
+    const style = doc.createElement("style");
+    style.setAttribute(marker, theme.id);
+    style.textContent = css;
+    head.appendChild(style);
+  }
+
+  // Injects the active theme's declared font faces into document.head as a
+  // single `<style>`, deduped per (document, theme id), no-op when there are no
+  // fonts or the host lacks head/querySelector. The injected text is exactly
+  // `compileFontFaceCss(theme.fonts)` — there is no second, hand-rolled code
+  // path. Like the theme-css style it is NOT removed on unmount: it is
+  // document-level and may be shared by other live renderers (the presenter
+  // mounts several of the same theme).
+  //
+  // The safety argument differs from `#applyThemeCss`. Theme CSS is selector-
+  // scoped to `[data-velumo-theme="<id>"]`, so a lingering style for an
+  // inactive theme matches nothing. `@font-face` is NOT selector-scoped — it
+  // registers a font family document-globally. Deduping per theme id keeps each
+  // theme's faces under their own marker so they coexist without clobbering, and
+  // a lingering face for an inactive theme is mostly inert (nothing references
+  // the family; a data-URI triggers no network fetch). The one residual edge:
+  // two themes declaring the SAME `family` with different bytes in one document
+  // resolve by cascade/head order. Not reachable today (a document carries one
+  // theme id); themes should namespace family names.
+  #applyThemeFonts(theme: Theme): void {
+    const fonts = theme.fonts;
+    if (fonts === undefined || fonts.length === 0) {
+      return;
+    }
+    const doc = this.#root.ownerDocument;
+    const head = doc.head;
+    if (head === undefined || typeof doc.querySelector !== "function") {
+      return;
+    }
+    const marker = "data-velumo-theme-fonts";
+    if (
+      doc.querySelector(`[${marker}="${escapeCssString(theme.id)}"]`) !== null
+    ) {
+      return;
+    }
+    const style = doc.createElement("style");
+    style.setAttribute(marker, theme.id);
+    style.textContent = compileFontFaceCss(fonts);
+    head.appendChild(style);
+  }
+
+  #currentSlide(): SlideEntry {
+    const state = this.#runtime.getState();
+    return (
+      this.#manifest.slides.find((slide) => slide.id === state.slideId) ??
+      this.#manifest.slides[0]
+    );
+  }
+
+  #renderSlide(slide: SlideEntry): DomElementLike {
+    const slideElement = this.#createElement("section");
+    slideElement.setAttribute("data-velumo-slide-id", slide.id);
+    slideElement.setAttribute("data-velumo-slide-kind", slide.kind);
+    slideElement.setAttribute(
+      "aria-label",
+      `${this.#manifest.deck.title} ${slide.id}`,
+    );
+
+    if (slide.transition !== undefined) {
+      slideElement.setAttribute("data-velumo-transition", slide.transition);
+    }
+
+    const watermark = this.#manifest.deck.watermark;
+    const hasWatermark =
+      typeof watermark === "string" &&
+      watermark.trim().length > 0 &&
+      slide.chrome !== false;
+
+    const needsPositioning =
+      slide.background !== undefined ||
+      slide.layout?.kind === "canvas" ||
+      hasWatermark;
+    if (needsPositioning) {
+      this.#setStyleProperty(slideElement, "position", "relative");
+    }
+
+    if (slide.background !== undefined) {
+      this.#setStyleProperty(slideElement, "z-index", "0");
+      slideElement.appendChild(
+        renderBackground(slide.background, {
+          createElement: (tag) => this.#createElement(tag),
+          setStyleProperty: (el, prop, val) =>
+            this.#setStyleProperty(el, prop, val),
+        }),
+      );
+    }
+
+    if (slide.layout !== undefined) {
+      const layoutRoot = this.#createElement("div");
+      layoutRoot.setAttribute("data-velumo-layout-root", "");
+      layoutRoot.appendChild(
+        renderLayoutNode(slide.layout, {
+          createElement: (tag) => this.#createElement(tag),
+          createElementNS: (ns, tag) => this.#createElementNS(ns, tag),
+          setStyleProperty: (el, prop, val) =>
+            this.#setStyleProperty(el, prop, val),
+        }),
+      );
+      slideElement.appendChild(layoutRoot);
+    }
+
+    for (const layer of slide.layers ?? []) {
+      slideElement.appendChild(this.#renderLayer(slide, layer));
+    }
+
+    if (hasWatermark) {
+      const mark = this.#createElement("div");
+      mark.setAttribute("data-velumo-watermark", "");
+      mark.setAttribute("aria-hidden", "true");
+      mark.textContent = watermark;
+      slideElement.appendChild(mark);
+    }
+
+    return slideElement;
+  }
+
+  #renderLayer(slide: SlideEntry, layer: Layer): DomElementLike {
+    const layerElement = this.#createElement("div");
+    layerElement.setAttribute("data-velumo-layer-type", layer.type);
+
+    if (layer.id !== undefined) {
+      layerElement.setAttribute("data-velumo-layer-id", layer.id);
+    }
+
+    this.#applyFragmentState(slide, layer, layerElement);
+
+    const customRenderer = this.#registry?.getLayerRenderer(layer.type);
+    if (customRenderer !== undefined) {
+      this.#appendCustomLayerResult(
+        layerElement,
+        customRenderer(this.#createLayerContext(slide, layer)),
+      );
+      return layerElement;
+    }
+
+    switch (layer.type) {
+      case "markdown":
+        layerElement.append(
+          ...this.#renderMarkdown(String(layer.content ?? "")),
+        );
+        return layerElement;
+      case "html":
+        layerElement.append(
+          ...renderSafeHtml(String(layer.content ?? ""), {
+            createElement: (tag) => this.#createElement(tag),
+            createText: (text) => this.#createText(text),
+            textElement: (tag, text) => this.#textElement(tag, text),
+          }),
+        );
+        return layerElement;
+      default:
+        layerElement.textContent = layer.type;
+        return layerElement;
+    }
+  }
+
+  #createLayerContext(
+    slide: SlideEntry,
+    layer: Layer,
+  ): DomLayerRendererContext {
+    const dispatcher = this.#actionDispatcher;
+    const runtime = this.#runtime;
+    return {
+      layer,
+      slide,
+      manifest: this.#manifest,
+      runtime,
+      createElement: (tagName) => this.#createElement(tagName),
+      createText: (text) => this.#createText(text),
+      dispatch: (action) => {
+        if (dispatcher === undefined) {
+          return; // inert on a minimal / no-action-handler host
+        }
+        dispatchControlAction(
+          dispatcher,
+          {
+            type: action.type,
+            ...(action.payload === undefined
+              ? {}
+              : { payload: action.payload }),
+          },
+          runtime,
+        );
+      },
+    };
+  }
+
+  #appendCustomLayerResult(
+    layerElement: DomElementLike,
+    result: DomLayerRenderResult,
+  ): void {
+    if (result === null || result === undefined) {
+      return;
+    }
+
+    const children = Array.isArray(result) ? result : [result];
+    layerElement.append(...children);
+  }
+
+  #applyFragmentState(
+    slide: SlideEntry,
+    layer: Layer,
+    layerElement: DomElementLike,
+  ): void {
+    const fragmentIndex = this.#fragmentIndexForLayer(slide, layer);
+
+    if (fragmentIndex === undefined) {
+      return;
+    }
+
+    const visible = fragmentIndex + 1 <= this.#runtime.getState().fragmentIndex;
+    layerElement.setAttribute(
+      "data-velumo-fragment",
+      visible ? "visible" : "hidden",
+    );
+  }
+
+  #fragmentIndexForLayer(slide: SlideEntry, layer: Layer): number | undefined {
+    if (layer.id === undefined) {
+      return undefined;
+    }
+
+    const fragmentIndex = slide.fragments?.findIndex(
+      (fragment) => fragment.layerId === layer.id,
+    );
+
+    return fragmentIndex === undefined || fragmentIndex === -1
+      ? undefined
+      : fragmentIndex;
+  }
+
+  #renderMarkdown(source: string): DomElementLike[] {
+    const elements: DomElementLike[] = [];
+
+    for (const block of source.split(/\n{2,}/)) {
+      const lines = block.split(/\n/).filter((line) => line.length > 0);
+
+      for (const line of lines) {
+        if (line.startsWith("## ")) {
+          elements.push(this.#textElement("h2", line.slice(3)));
+          continue;
+        }
+
+        if (line.startsWith("# ")) {
+          elements.push(this.#textElement("h1", line.slice(2)));
+          continue;
+        }
+
+        elements.push(this.#textElement("p", line));
+      }
+    }
+
+    return elements;
+  }
+
+  #textElement(tagName: string, text: string): DomElementLike {
+    const element = this.#createElement(tagName);
+    element.textContent = text;
+    return element;
+  }
+
+  #createElement(tagName: string): DomElementLike {
+    return this.#root.ownerDocument.createElement(tagName);
+  }
+
+  #createElementNS(namespace: string, tagName: string): DomElementLike {
+    return this.#root.ownerDocument.createElementNS(namespace, tagName);
+  }
+
+  #createText(text: string): DomNodeLike {
+    return this.#root.ownerDocument.createTextNode(text);
+  }
+
+  #applyThemeTokenProperties(tokens: ThemeTokens | undefined): void {
+    const nextProperties = tokensToCssProperties(tokens);
+
+    for (const property of this.#themeTokenProperties) {
+      if (!nextProperties.has(property)) {
+        this.#root.style?.removeProperty(property);
+        this.#themeTokenProperties.delete(property);
+      }
+    }
+
+    for (const [property, value] of nextProperties) {
+      this.#setStyleProperty(this.#root, property, value);
+      this.#themeTokenProperties.add(property);
+    }
+  }
+
+  #clearThemeTokenProperties(): void {
+    for (const property of this.#themeTokenProperties) {
+      this.#root.style?.removeProperty(property);
+    }
+
+    this.#themeTokenProperties.clear();
+  }
+
+  #setStyleProperty(
+    element: {
+      readonly style?: { setProperty(name: string, value: string): void };
+    },
+    property: string,
+    value: string,
+  ): void {
+    element.style?.setProperty(property, value);
+  }
+}