flowsvg 0.1.0 → 0.2.0

package/dist/browser/export-controls.js

@@ -0,0 +1,151 @@
+const MAX_FILENAME_LENGTH = 120;
+/** Own the visible export state and one cancellable task; destroy silences asynchronous results and releases downloads. */
+export class GifExportControls {
+    owner;
+    captureInput;
+    element;
+    startButton;
+    cancelButton;
+    status;
+    progress;
+    task;
+    destroyed = false;
+    downloadUrls = new Map();
+    constructor(owner, captureInput) {
+        this.owner = owner;
+        this.captureInput = captureInput;
+        this.element = owner.createElement("span");
+        this.element.className = "flowsvg-export-controls";
+        this.startButton = owner.createElement("button");
+        this.startButton.type = "button";
+        this.startButton.textContent = "Export GIF";
+        this.startButton.setAttribute("aria-label", "Export GIF");
+        this.cancelButton = owner.createElement("button");
+        this.cancelButton.type = "button";
+        this.cancelButton.textContent = "Cancel export";
+        this.cancelButton.hidden = true;
+        this.progress = owner.createElement("progress");
+        this.progress.setAttribute("aria-label", "GIF export progress");
+        this.progress.hidden = true;
+        this.status = owner.createElement("span");
+        this.status.setAttribute("role", "status");
+        this.status.setAttribute("aria-live", "polite");
+        this.element.append(this.startButton, this.cancelButton, this.progress, this.status);
+        this.startButton.addEventListener("click", this.start);
+        this.cancelButton.addEventListener("click", this.cancel);
+    }
+    destroy() {
+        this.destroyed = true;
+        this.task?.abort();
+        this.startButton.removeEventListener("click", this.start);
+        this.cancelButton.removeEventListener("click", this.cancel);
+        for (const [url, timer] of this.downloadUrls) {
+            clearTimeout(timer);
+            URL.revokeObjectURL(url);
+        }
+        this.downloadUrls.clear();
+    }
+    /** Reserve the slot and capture input before loading code so repeated clicks and document loads cannot race the import. */
+    start = () => {
+        if (this.destroyed || this.task)
+            return;
+        const controller = new AbortController();
+        this.task = controller;
+        const input = this.captureInput();
+        this.startButton.disabled = true;
+        this.cancelButton.hidden = false;
+        this.progress.hidden = false;
+        this.progress.removeAttribute("value");
+        this.status.textContent = "Preparing GIF…";
+        void this.run(controller, input);
+    };
+    cancel = () => {
+        this.task?.abort();
+    };
+    async run(controller, input) {
+        try {
+            const { exportGif } = await loadExporter(controller.signal);
+            if (!this.isActive(controller))
+                return;
+            const bytes = await exportGif(input.document, {
+                theme: input.theme,
+                signal: controller.signal,
+                onProgress: (progress) => {
+                    if (this.isActive(controller))
+                        this.renderProgress(progress);
+                }
+            });
+            if (!this.isActive(controller))
+                return;
+            this.download(bytes, input.document.title);
+            this.status.textContent = "GIF export complete.";
+        }
+        catch (error) {
+            if (this.destroyed || this.task !== controller)
+                return;
+            this.status.textContent = controller.signal.aborted
+                ? "GIF export cancelled."
+                : `GIF export failed: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        finally {
+            // A cancelled import may return without throwing; always release its slot, but never update destroyed UI.
+            if (this.task === controller) {
+                this.task = undefined;
+                if (!this.destroyed) {
+                    if (controller.signal.aborted)
+                        this.status.textContent = "GIF export cancelled.";
+                    this.startButton.disabled = false;
+                    this.cancelButton.hidden = true;
+                    this.progress.hidden = true;
+                }
+            }
+        }
+    }
+    isActive(controller) {
+        return !this.destroyed && this.task === controller && !controller.signal.aborted;
+    }
+    renderProgress(progress) {
+        this.progress.max = Math.max(1, progress.total);
+        this.progress.value = progress.completed;
+        const labels = { preparing: "Preparing", sampling: "Sampling", encoding: "Encoding", complete: "Completing" };
+        this.status.textContent = `${labels[progress.phase]} GIF: ${progress.completed}/${progress.total}`;
+    }
+    download(bytes, title) {
+        const url = URL.createObjectURL(new Blob([new Uint8Array(bytes)], { type: "image/gif" }));
+        const link = this.owner.createElement("a");
+        link.href = url;
+        link.download = downloadFilename(title);
+        try {
+            this.owner.body.append(link);
+            link.click();
+        }
+        finally {
+            link.remove();
+            // Defer revocation until the browser consumes the click. Destruction also releases pending download URLs.
+            const timer = setTimeout(() => { URL.revokeObjectURL(url); this.downloadUrls.delete(url); }, 0);
+            this.downloadUrls.set(url, timer);
+        }
+    }
+}
+/** Keep titles as filename data, including on Windows, and retain the extension within a bounded name. */
+function downloadFilename(title) {
+    const name = (title ?? "").replace(/[<>:"/\\|?*\u0000-\u001f\u007f]/g, "_").replace(/^[.\s]+|[.\s]+$/g, "").slice(0, MAX_FILENAME_LENGTH);
+    const safeName = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name) ? `_${name}` : name;
+    return `${safeName || "FlowSVG"}.gif`;
+}
+/** Abort waiting for a module fetch as well as an active encoder; late module resolution cannot retain the task slot. */
+async function loadExporter(signal) {
+    signal.throwIfAborted();
+    let stopListening = () => { };
+    const cancelled = new Promise((_resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        stopListening = () => signal.removeEventListener("abort", onAbort);
+    });
+    try {
+        return await Promise.race([import("../export.js"), cancelled]);
+    }
+    finally {
+        stopListening();
+    }
+}

package/dist/browser/player.d.ts

@@ -0,0 +1,77 @@
+import type { DiagramDocument, DiagramFrameState, DiagramPoint, EvaluateOptions, HitObject, ThemeName } from "../core/model.js";
+/** Creation options: controls default on, motion follows browser preferences, and theme falls back to the document/light. */
+export interface PlayerOptions extends EvaluateOptions {
+    controls?: boolean;
+    /** Defaults to false. Wrap positive-duration playback; manual seek and step keep their explicit position. */
+    loop?: boolean;
+    /** Defaults to false. GIF controls require visible playback controls; exports use the full timeline at 1×. */
+    gifExport?: boolean;
+    /** Hover highlights borders by default; true also paints the background and adjusts content ink. Applies to groups too. */
+    hoverFill?: boolean;
+}
+/** Player snapshot: times are milliseconds, speed is a positive multiplier, and frame is the core result without hover. */
+export interface PlayerState {
+    timeMs: number;
+    totalDuration: number;
+    playing: boolean;
+    loop: boolean;
+    speed: number;
+    frame: DiagramFrameState;
+}
+/** Object interaction detail; point uses document coordinates and time/beat IDs reflect the event-time player state. */
+export interface PlayerInteractionDetail extends HitObject {
+    point: DiagramPoint;
+    timeMs: number;
+    sceneId: string | null;
+    beatId: string | null;
+}
+/** Imperative browser player; creation/successful load pause at zero, and controls become inert after destruction. */
+export interface FlowPlayer {
+    /** The supplied host, also used as the CustomEvent dispatch target. */
+    readonly element: HTMLElement;
+    /** Play from the current position; loop mode restarts at the end. Static or page-hidden players cannot start. */
+    play(): void;
+    /** Stop time advancement, retaining the current frame. */
+    pause(): void;
+    /** Seek to a clamped millisecond time; preserve playback except at the end. Non-finite times become zero. */
+    seek(timeMs: number): void;
+    /** Pause and jump to the adjacent start; backward goes to this beat's start from inside it, or the preceding start. */
+    step(direction: 1 | -1): void;
+    /** Set a finite positive speed multiplier; ignore invalid values. */
+    setSpeed(speed: number): void;
+    /** Change live loop mode without changing playback or position; emit loopchange only when the value changes. */
+    setLoop(loop: boolean): void;
+    /** Compile before replacing; reset/pause at zero on success, or emit error and retain the old document/time/playback. */
+    load(document: DiagramDocument): void;
+    /** Read current player state; the last state remains readable after destruction. */
+    getState(): PlayerState;
+    /** Silently and idempotently release frames/listeners/host content; no further player events are dispatched. */
+    destroy(): void;
+}
+/** Retained state and original load error; DiagramValidationError.issues provides field paths for validation failures. */
+export interface PlayerErrorDetail extends PlayerState {
+    error: Error;
+}
+/**
+ * Host events and their detail types. Frame updates emit stepchange when needed, then timeupdate.
+ * hover/click use null for no hit; objecthover/objectclick report the same interactions under alternate names.
+ * Hover also changes when a frame update changes the object under a stationary pointer.
+ */
+export type PlayerEventMap = {
+    stepchange: CustomEvent<PlayerState>;
+    timeupdate: CustomEvent<PlayerState>;
+    playstatechange: CustomEvent<PlayerState>;
+    loopchange: CustomEvent<PlayerState>;
+    error: CustomEvent<PlayerErrorDetail>;
+    hover: CustomEvent<PlayerInteractionDetail | null>;
+    click: CustomEvent<PlayerInteractionDetail | null>;
+    objecthover: CustomEvent<PlayerInteractionDetail | null>;
+    objectclick: CustomEvent<PlayerInteractionDetail | null>;
+};
+/**
+ * Mount a player using the host document and observe browser motion preferences unless explicitly overridden.
+ * Replaces host children; destroy an existing player before replacing it on the same host.
+ * @throws {DiagramValidationError} For an invalid initial document, before an instance exists to emit error.
+ */
+export declare function createPlayer(host: HTMLElement, document: DiagramDocument, options?: PlayerOptions): FlowPlayer;
+export type { ThemeName };

package/dist/browser/player.js

@@ -0,0 +1,412 @@
+/**
+ * Browser player: own the clock, DOM, controls and input, forwarding time and visual options to the core.
+ * Importing does not access the DOM; createPlayer allocates mount resources and destroy releases them.
+ */
+import { GifExportControls } from "./export-controls.js";
+import { paintContentHighlight } from "../core/node-content-paint.js";
+import { updateSvgDom } from "./svg-dom.js";
+import { attachPlayerLifecycle } from "./lifecycle.js";
+import { observeKeyboard, observeReducedMotion } from "./accessibility.js";
+import { PlayerControls } from "./controls.js";
+import { resolveThemePalette } from "../core/theme.js";
+import { createDiagram } from "../core/diagram.js";
+/**
+ * Mount a player using the host document and observe browser motion preferences unless explicitly overridden.
+ * Replaces host children; destroy an existing player before replacing it on the same host.
+ * @throws {DiagramValidationError} For an invalid initial document, before an instance exists to emit error.
+ */
+export function createPlayer(host, document, options = {}) {
+    const initial = createDiagram(document);
+    return new BrowserPlayer(host, initial, document, options);
+}
+/**
+ * Own one compiled Diagram and advance time with RAF; core results drive the canvas, caption and controls.
+ * Retain cleanup callbacks for lifecycle, media preferences and pointer listeners, releasing them on destroy.
+ */
+class BrowserPlayer {
+    element;
+    diagram;
+    sourceDocument;
+    gifControls;
+    options;
+    timeMs = 0;
+    speed = 1;
+    playing = false;
+    loop;
+    playbackIntent = 0;
+    destroyed = false;
+    frameHandle;
+    lastTimestamp;
+    frame;
+    canvas;
+    caption;
+    controls;
+    scenes;
+    beatStarts;
+    detachLifecycle;
+    stopKeyboard;
+    stopMotion;
+    stopPointer;
+    themeOverride;
+    pointerPosition;
+    hoveredHit = null;
+    constructor(host, diagram, document, options) {
+        this.element = host;
+        this.loop = options.loop ?? false;
+        this.diagram = diagram;
+        this.sourceDocument = cloneSourceDocument(document);
+        this.beatStarts = diagram.beats.map((beat) => beat.startMs);
+        this.scenes = collectScenes(document, diagram);
+        const owner = host.ownerDocument;
+        const motion = observeReducedMotion(owner, options.reducedMotion, (reducedMotion) => {
+            if (this.destroyed)
+                return;
+            this.options = { ...this.options, reducedMotion };
+            this.updateFrame();
+        });
+        this.stopMotion = motion.cleanup;
+        this.themeOverride = options.theme;
+        this.options = { ...options, theme: options.theme ?? document.theme ?? "light", reducedMotion: motion.value };
+        this.frame = diagram.evaluateAt(0, this.options);
+        this.canvas = owner.createElement("div");
+        this.canvas.className = "flowsvg-canvas";
+        this.stopKeyboard = observeKeyboard(this.canvas, { toggle: this.togglePlayback, step: (direction) => this.step(direction) });
+        this.caption = owner.createElement("p");
+        this.caption.className = "flowsvg-caption";
+        this.caption.setAttribute("aria-live", "polite");
+        this.caption.setAttribute("aria-atomic", "true");
+        if (options.controls !== false) {
+            this.controls = new PlayerControls(owner, {
+                toggle: this.togglePlayback,
+                step: (direction) => this.step(direction),
+                seek: (timeMs) => this.seek(timeMs),
+                setSpeed: (speed) => this.setSpeed(speed),
+                toggleLoop: () => this.setLoop(!this.loop)
+            });
+        }
+        if (options.gifExport && this.controls) {
+            this.gifControls = new GifExportControls(owner, () => ({
+                document: structuredClone(this.sourceDocument), theme: this.options.theme ?? "light"
+            }));
+            this.controls.element.append(this.gifControls.element);
+        }
+        host.replaceChildren(this.canvas, this.caption, ...(this.controls ? [this.controls.element] : []));
+        this.render();
+        this.stopPointer = observePointer(this.canvas, {
+            move: (event) => this.handlePointer("hover", event),
+            leave: () => this.clearPointer(),
+            click: (event) => this.handlePointer("click", event)
+        });
+        this.detachLifecycle = attachPlayerLifecycle(host, this.canvas, () => this.pause());
+    }
+    play() {
+        if (this.destroyed || this.playing || this.isPageHidden() || this.diagram.totalDuration <= 0)
+            return;
+        if (this.timeMs >= this.diagram.totalDuration) {
+            if (!this.loop)
+                return;
+            const intent = this.playbackIntent;
+            this.timeMs = 0;
+            this.updateFrame();
+            // Rendering dispatches events; a newer pause, seek or load must override this restart.
+            if (this.destroyed || this.playing || intent !== this.playbackIntent || this.isPageHidden())
+                return;
+        }
+        this.playing = true;
+        this.lastTimestamp = undefined;
+        this.renderControls();
+        this.emit("playstatechange");
+        this.scheduleFrame();
+    }
+    pause() {
+        if (this.destroyed)
+            return;
+        this.playbackIntent += 1;
+        if (!this.playing)
+            return;
+        this.playing = false;
+        if (this.frameHandle !== undefined)
+            cancelAnimationFrame(this.frameHandle);
+        this.frameHandle = undefined;
+        this.renderControls();
+        this.emit("playstatechange");
+    }
+    seek(timeMs) {
+        if (this.destroyed)
+            return;
+        this.playbackIntent += 1;
+        this.timeMs = clamp(timeMs, 0, this.diagram.totalDuration);
+        this.lastTimestamp = undefined;
+        this.updateFrame();
+        if (this.timeMs >= this.diagram.totalDuration)
+            this.pause();
+    }
+    step(direction) {
+        if (this.destroyed)
+            return;
+        this.pause();
+        const starts = direction > 0 ? this.beatStarts : [...this.beatStarts].reverse();
+        const target = starts.find((start) => direction > 0 ? start > this.timeMs : start < this.timeMs);
+        this.seek(target ?? (direction > 0 ? this.diagram.totalDuration : 0));
+    }
+    setSpeed(speed) {
+        if (this.destroyed || !Number.isFinite(speed) || speed <= 0)
+            return;
+        this.speed = speed;
+        this.renderControls();
+    }
+    setLoop(loop) {
+        if (this.destroyed || this.loop === loop)
+            return;
+        this.loop = loop;
+        this.renderControls();
+        this.emit("loopchange");
+    }
+    load(document) {
+        if (this.destroyed)
+            return;
+        try {
+            // Keep the old player intact until compilation succeeds so invalid loads do not interrupt valid playback.
+            const diagram = createDiagram(document);
+            this.pause();
+            if (this.destroyed)
+                return;
+            this.diagram = diagram;
+            this.sourceDocument = cloneSourceDocument(document);
+            this.options = { ...this.options, theme: this.themeOverride ?? document.theme ?? "light" };
+            this.beatStarts = diagram.beats.map((beat) => beat.startMs);
+            this.scenes = collectScenes(document, diagram);
+            this.timeMs = 0;
+            // A replacement document owns new interaction targets, even when it reuses the same node IDs.
+            this.pointerPosition = undefined;
+            this.updateFrame();
+        }
+        catch (error) {
+            this.emit("error", { ...this.state(), error: error instanceof Error ? error : new Error(String(error)) });
+        }
+    }
+    getState() {
+        return this.state();
+    }
+    destroy() {
+        if (this.destroyed)
+            return;
+        // Block dispatch/rescheduling before releasing resources; do not call pause, which would emit an event.
+        this.destroyed = true;
+        this.gifControls?.destroy();
+        this.controls?.destroy();
+        this.playing = false;
+        if (this.frameHandle !== undefined)
+            cancelAnimationFrame(this.frameHandle);
+        this.frameHandle = undefined;
+        this.lastTimestamp = undefined;
+        this.detachLifecycle();
+        this.stopKeyboard();
+        this.stopMotion();
+        this.stopPointer();
+        this.pointerPosition = undefined;
+        this.hoveredHit = null;
+        this.element.replaceChildren();
+    }
+    /** The first RAF establishes a baseline; seek clears it so elapsed time from the old position is not reused. */
+    tick = (timestamp) => {
+        if (!this.playing || this.destroyed)
+            return;
+        this.frameHandle = undefined;
+        const previous = this.lastTimestamp ?? timestamp;
+        this.lastTimestamp = timestamp;
+        const elapsed = timestamp - previous;
+        this.timeMs = this.loop
+            ? advanceLoopTime(this.timeMs, elapsed, this.speed, this.diagram.totalDuration)
+            : this.timeMs + elapsed * this.speed;
+        if (!this.loop && this.timeMs >= this.diagram.totalDuration) {
+            this.timeMs = this.diagram.totalDuration;
+            this.updateFrame();
+            this.pause();
+            return;
+        }
+        this.updateFrame();
+        this.scheduleFrame();
+    };
+    /** Event listeners may restart playback synchronously; never queue a second frame owned by the same player. */
+    scheduleFrame() {
+        if (this.destroyed || !this.playing || this.frameHandle !== undefined)
+            return;
+        this.frameHandle = requestAnimationFrame(this.tick);
+    }
+    /** Update the frame before notifying consumers so listeners observe the rendered position. */
+    updateFrame() {
+        const previousBeat = this.frame.beatId;
+        const previousScene = this.frame.sceneId;
+        this.frame = this.diagram.evaluateAt(this.timeMs, this.options);
+        this.render();
+        if (previousBeat !== this.frame.beatId || previousScene !== this.frame.sceneId)
+            this.emit("stepchange");
+        this.emit("timeupdate");
+    }
+    isPageHidden() {
+        return this.element.ownerDocument.visibilityState === "hidden";
+    }
+    togglePlayback = () => {
+        if (this.playing)
+            this.pause();
+        else
+            this.play();
+    };
+    render() {
+        updateSvgDom(this.canvas, this.diagram.renderSvg(this.timeMs, this.options));
+        this.canvas.style.aspectRatio = `${this.frame.camera.width} / ${this.frame.camera.height}`;
+        this.updateHover();
+        this.caption.textContent = this.frame.caption ?? "";
+        this.renderControls();
+    }
+    renderControls() {
+        this.controls?.render({ ...this.state(), sceneId: this.frame.sceneId, scenes: this.scenes });
+    }
+    state() {
+        return { timeMs: this.timeMs, totalDuration: this.diagram.totalDuration, playing: this.playing, loop: this.loop, speed: this.speed, frame: this.frame };
+    }
+    handlePointer(type, event) {
+        if (this.destroyed)
+            return;
+        if (type === "hover") {
+            this.pointerPosition = { clientX: event.clientX, clientY: event.clientY };
+            updateSvgDom(this.canvas, this.diagram.renderSvg(this.timeMs, this.options));
+            this.updateHover(true);
+            return;
+        }
+        if (type === "click")
+            event.stopPropagation();
+        const point = pointerToDiagramPoint(this.canvas, this.frame.camera, event);
+        const hit = this.diagram.hitTest(this.timeMs, point, this.options);
+        const detail = hit ? { ...hit, point, timeMs: this.timeMs, sceneId: this.frame.sceneId, beatId: this.frame.beatId } : null;
+        this.emit("click", detail);
+        this.emit("objectclick", detail);
+    }
+    /** Re-hit the saved screen position after camera/geometry updates; hover never changes the core hit geometry. */
+    updateHover(emitAlways = false) {
+        const point = this.pointerPosition ? pointerToDiagramPoint(this.canvas, this.frame.camera, this.pointerPosition) : undefined;
+        const hit = point ? this.diagram.hitTest(this.timeMs, point, this.options) : null;
+        if (hit?.type === "node") {
+            const shape = Array.from(this.canvas.querySelectorAll("[data-id]")).find((element) => element.getAttribute("data-id") === hit.id);
+            const palette = resolveThemePalette(this.options.theme);
+            const node = this.frame.nodes.find((candidate) => candidate.id === hit.id);
+            // Border-only hover preserves all current timeline and content paint unless fill feedback is explicitly enabled.
+            if (this.options.hoverFill)
+                shape?.setAttribute("fill", palette.highlightFill);
+            shape?.setAttribute("stroke", palette.highlight);
+            const layout = node?.contentLayout;
+            const content = Array.from(this.canvas.querySelectorAll("[data-content-id]")).find((element) => element.getAttribute("data-content-id") === hit.id);
+            if (this.options.hoverFill && content && layout)
+                paintHoveredContent(content, paintContentHighlight(layout, 1, palette.highlightFill));
+        }
+        const changed = hit?.id !== this.hoveredHit?.id || hit?.type !== this.hoveredHit?.type;
+        this.hoveredHit = hit;
+        if (!emitAlways && !changed)
+            return;
+        const detail = hit && point ? { ...hit, point, timeMs: this.timeMs, sceneId: this.frame.sceneId, beatId: this.frame.beatId } : null;
+        this.emit("hover", detail);
+        this.emit("objecthover", detail);
+    }
+    clearPointer() {
+        if (this.destroyed)
+            return;
+        this.pointerPosition = undefined;
+        updateSvgDom(this.canvas, this.diagram.renderSvg(this.timeMs, this.options));
+        this.updateHover(true);
+    }
+    emit(type, detail) {
+        if (!this.destroyed)
+            this.element.dispatchEvent(new CustomEvent(type, { detail: detail === undefined ? this.state() : detail }));
+    }
+}
+/** Apply the shared paint result to current decorative children; no child receives a separate interaction identity. */
+function paintHoveredContent(content, layout) {
+    const tags = content.querySelectorAll("rect");
+    layout.tags.forEach((tag, index) => tags[index]?.setAttribute("fill", tag.fill));
+    const texts = content.querySelectorAll("text");
+    layout.lines.forEach((line, index) => {
+        const text = texts[index];
+        text?.setAttribute("fill", line.color);
+        const spans = text?.querySelectorAll("tspan");
+        line.spans.forEach((span, spanIndex) => spans?.[spanIndex]?.setAttribute("fill", span.color));
+    });
+    const graphs = content.querySelectorAll("[data-content-graph]");
+    layout.graphs?.forEach((graph, index) => {
+        const circles = graphs[index]?.querySelectorAll("circle");
+        const edges = graphs[index]?.querySelectorAll("line");
+        graph.nodes.forEach((node, nodeIndex) => circles?.[nodeIndex]?.setAttribute("fill", node.fill));
+        graph.edges.forEach((edge, edgeIndex) => edges?.[edgeIndex]?.setAttribute("stroke", edge.color));
+    });
+}
+function clamp(value, min, max) {
+    return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : min;
+}
+/** Reuse effective starts from core; authored durations can be shorter than a single transfer. */
+function collectScenes(document, diagram) {
+    const labels = new Map(document.scenes.map((scene) => [scene.id, scene.label]));
+    return diagram.beats.filter((beat) => beat.beatIndex === 0).map((beat) => ({
+        id: beat.sceneId, label: labels.get(beat.sceneId), startMs: beat.startMs
+    }));
+}
+function observePointer(canvas, handlers) {
+    const onMove = (event) => handlers.move(event);
+    const onLeave = () => handlers.leave();
+    const onClick = (event) => handlers.click(event);
+    canvas.addEventListener("pointermove", onMove);
+    canvas.addEventListener("pointerleave", onLeave);
+    canvas.addEventListener("pointercancel", onLeave);
+    canvas.addEventListener("click", onClick);
+    return () => {
+        canvas.removeEventListener("pointermove", onMove);
+        canvas.removeEventListener("pointerleave", onLeave);
+        canvas.removeEventListener("pointercancel", onLeave);
+        canvas.removeEventListener("click", onClick);
+    };
+}
+/**
+ * Prefer the inverse SVG screen transform for scaling/letterboxing; otherwise map the element rectangle to the camera.
+ * The rectangle fallback lacks full SVG transform information and is only an approximation.
+ */
+function pointerToDiagramPoint(canvas, camera, event) {
+    const svg = canvas.querySelector("svg");
+    const matrix = svg?.getScreenCTM?.();
+    if (matrix) {
+        const inverse = matrix.inverse();
+        return {
+            x: event.clientX * inverse.a + event.clientY * inverse.c + inverse.e,
+            y: event.clientX * inverse.b + event.clientY * inverse.d + inverse.f
+        };
+    }
+    const bounds = svg?.getBoundingClientRect() ?? canvas.getBoundingClientRect();
+    const width = bounds.width || 1;
+    const height = bounds.height || 1;
+    return {
+        x: camera.x + ((event.clientX - bounds.left) / width) * camera.width,
+        y: camera.y + ((event.clientY - bounds.top) / height) * camera.height
+    };
+}
+/** Validation admits JSON documents; the same serialization as the core also handles reactive host document objects. */
+function cloneSourceDocument(document) {
+    return JSON.parse(JSON.stringify(document));
+}
+/** Preserve the modular elapsed result even when finite speed and elapsed values overflow their product. */
+function advanceLoopTime(timeMs, elapsedMs, speed, duration) {
+    let scaledSpeed = speed;
+    let elapsed = elapsedMs * scaledSpeed;
+    let doublings = 0;
+    while (!Number.isFinite(elapsed)) {
+        scaledSpeed /= 2;
+        doublings += 1;
+        elapsed = elapsedMs * scaledSpeed;
+    }
+    let remainder = elapsed % duration;
+    // Reducing before each doubling avoids overflow without discarding elapsed remainder.
+    for (let index = 0; index < doublings; index += 1)
+        remainder = addLoopRemainder(remainder, remainder, duration);
+    return addLoopRemainder(timeMs % duration, remainder, duration);
+}
+function addLoopRemainder(left, right, duration) {
+    const gap = duration - right;
+    return left >= gap ? left - gap : left + right;
+}

package/dist/browser/select-control.d.ts

@@ -0,0 +1,33 @@
+/** Shared select-only combobox for playback and host settings; the caller owns the committed value. */
+/** One non-editable choice. Values must be unique within a control. */
+export interface SelectChoice {
+    value: string;
+    label: string;
+}
+/**
+ * Styled choices keep focus on the trigger. Arrow keys preview; Enter/Space commit; Escape/Tab cancel.
+ * Append element before use, synchronize with render(), and call destroy() before removing the host.
+ */
+export declare class SelectControl {
+    private readonly onChange;
+    readonly element: HTMLDivElement;
+    private readonly trigger;
+    private readonly list;
+    private choices;
+    private activeIndex;
+    private destroyed;
+    constructor(owner: Document, label: string, onChange: (value: string) => void);
+    /** Replace changed choices and reflect external state without committing a user action. */
+    render(choices: readonly SelectChoice[], value: string, disabled?: boolean): void;
+    /** Release outside-dismissal listeners and make detached controls inert. Idempotent. */
+    destroy(): void;
+    private createOption;
+    private readonly toggle;
+    private open;
+    private close;
+    private highlight;
+    private commit;
+    private readonly onOutside;
+    private readonly onBlur;
+    private readonly onKey;
+}