@velumo/renderer-dom 0.1.0-beta.0

package/src/slide-thumbnail.ts

@@ -0,0 +1,146 @@
+import type { Manifest } from "@velumo/core";
+import { RuntimeController } from "@velumo/runtime";
+import { DomRenderer, type DomRendererOptions } from "./dom-renderer.js";
+
+// Default reference dimensions for a 16:9 slide stage.
+const DEFAULT_REFERENCE = { width: 1280, height: 720 };
+
+export interface SlideThumbnailOptions {
+  /** The host element that will contain the thumbnail. The HOST is responsible
+   * for sizing this element's width; the thumbnail fills it via aspect-ratio. */
+  readonly root: {
+    readonly ownerDocument: {
+      createElement(tagName: string): any;
+      createElementNS?(ns: string, tagName: string): any;
+      createTextNode(text: string): any;
+      readonly head?: any;
+      querySelector?(selectors: string): any;
+      readonly defaultView?: {
+        ResizeObserver?: new (cb: ResizeObserverCallback) => ResizeObserver;
+      } | null;
+    };
+    replaceChildren(...children: any[]): void;
+    querySelector(selector: string): any;
+    getBoundingClientRect?(): {
+      width: number;
+      height: number;
+      top: number;
+      left: number;
+      right: number;
+      bottom: number;
+    };
+  };
+  readonly manifest: Manifest;
+  readonly slideId: string;
+  /** Override the canonical reference dimensions (default: 1280x720). */
+  readonly reference?: { width: number; height: number };
+  /** The runtime registry, so plugin-registered layer renderers (e.g. `fx:*`)
+   * render real content in the thumbnail instead of fallback layer-type text. */
+  readonly registry?: DomRendererOptions["registry"];
+}
+
+export interface SlideThumbnailHandle {
+  dispose(): void;
+}
+
+/**
+ * Mounts a slide thumbnail into `options.root`.
+ *
+ * DOM structure:
+ *   root
+ *   └── box [data-velumo-thumbnail]       (overflow:hidden, aspect-ratio:16/9)
+ *       └── stage [data-velumo-thumbnail-stage]  (1280×720, container-type:size)
+ *           └── surface [data-velumo-renderer="dom"]  (DomRenderer root)
+ *
+ * The HOST sizes box's width. The stage is always 1280px wide (reference.width)
+ * so that cqw units resolve canonically. A CSS transform scales the stage to fit
+ * the host-sized box (transform-origin: top left).
+ *
+ * ResizeObserver (when available) keeps the scale updated. A synchronous
+ * initial measure is taken at mount time; a zero width falls back to reference.width.
+ *
+ * The [data-velumo-thumbnail] marker on the box causes the defaultThemeCss rule
+ *   [data-velumo-thumbnail] [data-velumo-animation] { animation: none !important; }
+ * to suppress entry animations, keeping thumbnails visually settled.
+ */
+export function mountSlideThumbnail(
+  options: SlideThumbnailOptions,
+): SlideThumbnailHandle {
+  const reference = options.reference ?? DEFAULT_REFERENCE;
+  const doc = options.root.ownerDocument;
+
+  // Build DOM: box > stage > surface
+  const box = doc.createElement("div");
+  box.setAttribute("data-velumo-thumbnail", "");
+  box.style.overflow = "hidden";
+  box.style.aspectRatio = "16 / 9";
+
+  const stage = doc.createElement("div");
+  stage.setAttribute("data-velumo-thumbnail-stage", "");
+  stage.style.width = `${reference.width}px`;
+  stage.style.height = `${reference.height}px`;
+  stage.style.containerType = "size";
+  stage.style.transformOrigin = "top left";
+
+  const surface = doc.createElement("div");
+  // Fill the stage so the renderer root has a DEFINITE 1280x720 size. Without an
+  // explicit height the surface shrink-wraps its content, so its `container-type:
+  // size` would resolve `cqh` to the content height instead of 720px and the
+  // slide's `cqh`-based frame padding would be wrong (gate-3 finding 1).
+  surface.style.width = "100%";
+  surface.style.height = "100%";
+
+  stage.appendChild(surface);
+  box.appendChild(stage);
+  options.root.replaceChildren(box);
+
+  // Wire up runtime + renderer
+  const runtime = new RuntimeController(options.manifest, {
+    initialSlideId: options.slideId,
+  });
+  const renderer = new DomRenderer({
+    root: surface,
+    manifest: options.manifest,
+    runtime,
+    registry: options.registry,
+  });
+  renderer.mount();
+
+  // Scale helpers
+  function applyScale(boxWidth: number): void {
+    stage.style.transform = `scale(${boxWidth / reference.width})`;
+  }
+
+  // Synchronous initial measure
+  const initialWidth = box.getBoundingClientRect?.()?.width ?? 0;
+  applyScale(initialWidth > 0 ? initialWidth : reference.width);
+
+  // ResizeObserver (observe the BOX — a test asserts this)
+  let disposed = false;
+  const ROCtor:
+    | (new (cb: ResizeObserverCallback) => ResizeObserver)
+    | undefined =
+    (globalThis as any).ResizeObserver ?? doc.defaultView?.ResizeObserver;
+
+  let observer: ResizeObserver | undefined;
+  if (ROCtor !== undefined) {
+    observer = new ROCtor((entries) => {
+      if (disposed) return;
+      const width = entries[0]?.contentRect?.width;
+      if (typeof width === "number") {
+        applyScale(width);
+      }
+    });
+    observer.observe(box);
+  }
+
+  return {
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      observer?.disconnect();
+      renderer.dispose();
+      options.root.replaceChildren();
+    },
+  };
+}

package/src/spatial-renderer.ts

@@ -0,0 +1,62 @@
+import type { CameraEasing, Scene } from "@velumo/core";
+import {
+  type LayoutRendererElement,
+  type LayoutRendererFactories,
+  renderLayoutNode,
+} from "./layout-renderer.js";
+
+export interface SpatialWorldElements {
+  readonly viewport: LayoutRendererElement;
+  readonly world: LayoutRendererElement;
+}
+
+/**
+ * Build a clipping viewport + an inner world layer for a spatial scene.
+ * The world layer carries the scene's `layout` (the world canvas) and is the
+ * element the camera transform is applied to.
+ */
+export function renderSpatialWorld(
+  scene: Scene,
+  factories: LayoutRendererFactories,
+): SpatialWorldElements {
+  const viewport = factories.createElement("div");
+  viewport.setAttribute("data-velumo-spatial", "viewport");
+  factories.setStyleProperty(viewport, "position", "absolute");
+  factories.setStyleProperty(viewport, "inset", "0");
+  factories.setStyleProperty(viewport, "overflow", "hidden");
+
+  const world = factories.createElement("div");
+  world.setAttribute("data-velumo-spatial", "world");
+  factories.setStyleProperty(world, "position", "absolute");
+  factories.setStyleProperty(world, "inset", "0");
+  // A flex column so a flowing canvas layout (flex: 1) fills the world; the
+  // canvas's percent-positioned items then map onto the full world box.
+  factories.setStyleProperty(world, "display", "flex");
+  factories.setStyleProperty(world, "flex-direction", "column");
+  factories.setStyleProperty(world, "transform-origin", "0 0");
+  factories.setStyleProperty(world, "will-change", "transform");
+
+  if (scene.layout !== undefined) {
+    world.appendChild(renderLayoutNode(scene.layout, factories));
+  }
+
+  viewport.appendChild(world);
+  return { viewport, world };
+}
+
+/**
+ * Set the CSS transition that animates the next camera move. A zero duration
+ * (e.g. reduced motion) disables the transition so the move is an instant cut.
+ */
+export function applyCameraTransition(
+  world: LayoutRendererElement,
+  durationMs: number,
+  easing: CameraEasing,
+  factories: LayoutRendererFactories,
+): void {
+  factories.setStyleProperty(
+    world,
+    "transition",
+    durationMs <= 0 ? "none" : `transform ${durationMs}ms ${easing}`,
+  );
+}

package/src/theme-fonts.ts

@@ -0,0 +1,75 @@
+import type { ThemeFontFace } from "@velumo/core";
+
+// Escape a value for safe interpolation inside a double-quoted CSS string
+// (a `"..."` literal, a `url("...")` descriptor, or a `[attr="..."]` selector
+// value). Backslash and double-quote are escaped; a literal newline becomes the
+// CSS `\A ` escape. `ThemeFontFace`/`Theme.id` are validated only as non-empty
+// strings, so a `"` in a family/source/id must not be able to break out of the
+// string (invalid CSS, a dropped @font-face, or a `querySelector` SyntaxError).
+export function escapeCssString(value: string): string {
+  return value.replace(/[\\"]/g, "\\$&").replace(/\n/g, "\\A ");
+}
+
+// Resolve the `format()` hint for a face's `src` descriptor. An explicit
+// `format` wins; otherwise we sniff `woff2` from a `data:font/woff2` URI or a
+// `.woff2` path (ignoring any query suffix). For anything else we emit no
+// `format()` at all and let the browser sniff the bytes — keeping the contract
+// format-agnostic while defaulting correctly for the self-contained woff2
+// data-URIs the themes ship.
+function resolveFormat(face: ThemeFontFace): string | undefined {
+  if (face.format !== undefined) {
+    return face.format;
+  }
+  if (/^data:font\/woff2[;,]/.test(face.source)) {
+    return "woff2";
+  }
+  const pathOnly = face.source.split("?")[0];
+  if (/\.woff2$/i.test(pathOnly)) {
+    return "woff2";
+  }
+  return undefined;
+}
+
+// Compile one `ThemeFontFace` into a single `@font-face` block. The family is
+// always quoted; the source is a single combined descriptor; every optional
+// descriptor is emitted only when present (a string `weight` such as the
+// variable range "100 900" passes through verbatim).
+function compileFontFace(face: ThemeFontFace): string {
+  const format = resolveFormat(face);
+  // Always quote the url() so sources with spaces or other characters that are
+  // invalid in an unquoted url() token (e.g. "/fonts/Bebas Neue.woff2") still
+  // parse — a quoted data-URI is equally valid.
+  const url = `url("${escapeCssString(face.source)}")`;
+  const src =
+    format === undefined ? url : `${url} format("${escapeCssString(format)}")`;
+
+  const lines = [
+    `  font-family: "${escapeCssString(face.family)}";`,
+    `  src: ${src};`,
+  ];
+  if (face.weight !== undefined) {
+    lines.push(`  font-weight: ${face.weight};`);
+  }
+  if (face.style !== undefined) {
+    lines.push(`  font-style: ${face.style};`);
+  }
+  if (face.display !== undefined) {
+    lines.push(`  font-display: ${face.display};`);
+  }
+  if (face.unicodeRange !== undefined) {
+    lines.push(`  unicode-range: ${face.unicodeRange};`);
+  }
+  if (face.stretch !== undefined) {
+    lines.push(`  font-stretch: ${face.stretch};`);
+  }
+
+  return `@font-face {\n${lines.join("\n")}\n}`;
+}
+
+/**
+ * Compile a theme's declared font faces into `@font-face` CSS — one block per
+ * face. Pure and DOM-free; the DOM renderer injects the result at mount.
+ */
+export function compileFontFaceCss(fonts: readonly ThemeFontFace[]): string {
+  return fonts.map(compileFontFace).join("\n\n");
+}

package/src/theme-tokens.ts

@@ -0,0 +1,66 @@
+import type { ThemeTokens } from "@velumo/core";
+
+export function tokensToCssProperties(
+  tokens: ThemeTokens | undefined,
+): Map<string, string> {
+  const properties = new Map<string, string>();
+
+  if (tokens === undefined) {
+    return properties;
+  }
+
+  addStringRecord(properties, "color", tokens.colors);
+  addNestedTokenRecord(properties, "typography", tokens.typography);
+  addStringRecord(properties, "spacing", tokens.spacing);
+  addStringRecord(properties, "radius", tokens.radii);
+  addStringRecord(properties, "shadow", tokens.shadows);
+  addNestedTokenRecord(properties, "motion", tokens.motion);
+  addStringRecord(properties, "surface", tokens.surfaces);
+  addStringRecord(properties, "text", tokens.text);
+
+  return properties;
+}
+
+function addStringRecord(
+  properties: Map<string, string>,
+  family: string,
+  tokens: Record<string, string | number> | undefined,
+): void {
+  if (tokens === undefined) {
+    return;
+  }
+
+  for (const [name, value] of Object.entries(tokens)) {
+    properties.set(`--velumo-${family}-${toKebabCase(name)}`, String(value));
+  }
+}
+
+function addNestedTokenRecord(
+  properties: Map<string, string>,
+  family: string,
+  tokens: Record<string, object> | undefined,
+): void {
+  if (tokens === undefined) {
+    return;
+  }
+
+  for (const [name, values] of Object.entries(tokens)) {
+    for (const [field, value] of Object.entries(values)) {
+      if (typeof value !== "string" && typeof value !== "number") {
+        continue;
+      }
+
+      properties.set(
+        `--velumo-${family}-${toKebabCase(name)}-${toKebabCase(field)}`,
+        String(value),
+      );
+    }
+  }
+}
+
+function toKebabCase(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[_\s.]+/g, "-")
+    .toLowerCase();
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts"],
+  "references": [{ "path": "../core" }, { "path": "../runtime" }]
+}