flowsvg 0.1.1 → 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

@@ -2,6 +2,10 @@ import type { DiagramDocument, DiagramFrameState, DiagramPoint, EvaluateOptions,
 /** 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;
 }
@@ -10,6 +14,7 @@ export interface PlayerState {
     timeMs: number;
     totalDuration: number;
     playing: boolean;
+    loop: boolean;
     speed: number;
     frame: DiagramFrameState;
 }
@@ -24,7 +29,7 @@ export interface PlayerInteractionDetail extends HitObject {
 export interface FlowPlayer {
     /** The supplied host, also used as the CustomEvent dispatch target. */
     readonly element: HTMLElement;
-    /** Play from the current position; do not start for static diagrams, at the end, or while the page is hidden. */
+    /** 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;
@@ -34,6 +39,8 @@ export interface FlowPlayer {
     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. */
@@ -54,6 +61,7 @@ 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>;

package/dist/browser/player.js

@@ -2,6 +2,7 @@
  * 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";
@@ -25,10 +26,14 @@ export function createPlayer(host, document, options = {}) {
 class BrowserPlayer {
     element;
     diagram;
+    sourceDocument;
+    gifControls;
     options;
     timeMs = 0;
     speed = 1;
     playing = false;
+    loop;
+    playbackIntent = 0;
     destroyed = false;
     frameHandle;
     lastTimestamp;
@@ -47,9 +52,11 @@ class BrowserPlayer {
     hoveredHit = null;
     constructor(host, diagram, document, options) {
         this.element = host;
+        this.loop = options.loop ?? false;
         this.diagram = diagram;
-        this.beatStarts = collectBeatStarts(document);
-        this.scenes = collectScenes(document);
+        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)
@@ -73,9 +80,16 @@ class BrowserPlayer {
                 toggle: this.togglePlayback,
                 step: (direction) => this.step(direction),
                 seek: (timeMs) => this.seek(timeMs),
-                setSpeed: (speed) => this.setSpeed(speed)
+                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, {
@@ -86,8 +100,18 @@ class BrowserPlayer {
         this.detachLifecycle = attachPlayerLifecycle(host, this.canvas, () => this.pause());
     }
     play() {
-        if (this.destroyed || this.playing || this.element.ownerDocument.visibilityState === "hidden" || this.diagram.totalDuration <= this.timeMs)
+        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();
@@ -95,7 +119,10 @@ class BrowserPlayer {
         this.scheduleFrame();
     }
     pause() {
-        if (this.destroyed || !this.playing)
+        if (this.destroyed)
+            return;
+        this.playbackIntent += 1;
+        if (!this.playing)
             return;
         this.playing = false;
         if (this.frameHandle !== undefined)
@@ -107,6 +134,7 @@ class BrowserPlayer {
     seek(timeMs) {
         if (this.destroyed)
             return;
+        this.playbackIntent += 1;
         this.timeMs = clamp(timeMs, 0, this.diagram.totalDuration);
         this.lastTimestamp = undefined;
         this.updateFrame();
@@ -127,6 +155,13 @@ class BrowserPlayer {
         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;
@@ -137,9 +172,10 @@ class BrowserPlayer {
             if (this.destroyed)
                 return;
             this.diagram = diagram;
+            this.sourceDocument = cloneSourceDocument(document);
             this.options = { ...this.options, theme: this.themeOverride ?? document.theme ?? "light" };
-            this.beatStarts = collectBeatStarts(document);
-            this.scenes = collectScenes(document);
+            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;
@@ -157,6 +193,8 @@ class BrowserPlayer {
             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);
@@ -177,8 +215,11 @@ class BrowserPlayer {
         this.frameHandle = undefined;
         const previous = this.lastTimestamp ?? timestamp;
         this.lastTimestamp = timestamp;
-        this.timeMs += (timestamp - previous) * this.speed;
-        if (this.timeMs >= this.diagram.totalDuration) {
+        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();
@@ -203,6 +244,9 @@ class BrowserPlayer {
             this.emit("stepchange");
         this.emit("timeupdate");
     }
+    isPageHidden() {
+        return this.element.ownerDocument.visibilityState === "hidden";
+    }
     togglePlayback = () => {
         if (this.playing)
             this.pause();
@@ -220,7 +264,7 @@ class BrowserPlayer {
         this.controls?.render({ ...this.state(), sceneId: this.frame.sceneId, scenes: this.scenes });
     }
     state() {
-        return { timeMs: this.timeMs, totalDuration: this.diagram.totalDuration, playing: this.playing, speed: this.speed, frame: this.frame };
+        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)
@@ -298,22 +342,13 @@ function paintHoveredContent(content, layout) {
 function clamp(value, min, max) {
     return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : min;
 }
-function collectBeatStarts(document) {
-    let startMs = 0;
-    return document.scenes.flatMap((scene) => scene.beats.map((beat) => {
-        const start = startMs;
-        startMs += beat.durationMs;
-        return start;
+/** 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 collectScenes(document) {
-    let startMs = 0;
-    return document.scenes.map((scene) => {
-        const choice = { id: scene.id, label: scene.label, startMs };
-        startMs += scene.beats.reduce((duration, beat) => duration + beat.durationMs, 0);
-        return choice;
-    });
-}
 function observePointer(canvas, handlers) {
     const onMove = (event) => handlers.move(event);
     const onLeave = () => handlers.leave();
@@ -351,3 +386,27 @@ function pointerToDiagramPoint(canvas, camera, event) {
         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;
+}

package/dist/browser/select-control.js

@@ -0,0 +1,171 @@
+let nextId = 0;
+/**
+ * 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 class SelectControl {
+    onChange;
+    element;
+    trigger;
+    list;
+    choices = [];
+    activeIndex = 0;
+    destroyed = false;
+    constructor(owner, label, onChange) {
+        this.onChange = onChange;
+        this.element = owner.createElement("div");
+        this.element.className = "flowsvg-select";
+        this.trigger = owner.createElement("button");
+        this.trigger.type = "button";
+        this.trigger.className = "flowsvg-select-trigger";
+        this.trigger.setAttribute("role", "combobox");
+        this.trigger.setAttribute("aria-label", label);
+        this.trigger.setAttribute("aria-haspopup", "listbox");
+        this.trigger.setAttribute("aria-expanded", "false");
+        this.list = owner.createElement("div");
+        this.list.id = `flowsvg-choices-${++nextId}`;
+        this.list.className = "flowsvg-select-options";
+        this.list.setAttribute("role", "listbox");
+        this.list.setAttribute("aria-label", label);
+        this.list.hidden = true;
+        this.trigger.setAttribute("aria-controls", this.list.id);
+        this.trigger.addEventListener("click", this.toggle);
+        this.trigger.addEventListener("keydown", this.onKey);
+        this.element.addEventListener("focusout", this.onBlur);
+        this.element.append(this.trigger, this.list);
+    }
+    /** Replace changed choices and reflect external state without committing a user action. */
+    render(choices, value, disabled = false) {
+        if (this.destroyed)
+            return;
+        const changed = choices.length !== this.choices.length || choices.some((choice, index) => choice.value !== this.choices[index]?.value || choice.label !== this.choices[index]?.label);
+        if (changed) {
+            this.close();
+            this.choices = choices;
+            this.list.replaceChildren(...choices.map((choice, index) => this.createOption(choice, index)));
+        }
+        this.trigger.value = value;
+        this.trigger.dataset.value = value;
+        this.trigger.textContent = choices.find((choice) => choice.value === value)?.label ?? "—";
+        this.trigger.disabled = disabled || choices.length === 0;
+        for (const option of Array.from(this.list.children)) {
+            option.setAttribute("aria-selected", String(option.getAttribute("data-value") === value));
+        }
+        if (this.trigger.disabled)
+            this.close();
+    }
+    /** Release outside-dismissal listeners and make detached controls inert. Idempotent. */
+    destroy() {
+        this.close();
+        this.destroyed = true;
+        this.trigger.removeEventListener("click", this.toggle);
+        this.trigger.removeEventListener("keydown", this.onKey);
+        this.element.removeEventListener("focusout", this.onBlur);
+        this.element.remove();
+    }
+    createOption(choice, index) {
+        const option = this.element.ownerDocument.createElement("div");
+        option.id = `${this.list.id}-${index}`;
+        option.setAttribute("role", "option");
+        option.dataset.value = choice.value;
+        option.textContent = choice.label;
+        // Pointer selection must retain trigger focus, including when the host synchronously replaces a player.
+        option.addEventListener("pointerdown", (event) => event.preventDefault());
+        option.addEventListener("click", () => this.commit(index));
+        return option;
+    }
+    toggle = () => {
+        if (this.list.hidden)
+            this.open();
+        else
+            this.close();
+    };
+    open() {
+        if (this.destroyed || this.trigger.disabled || !this.list.hidden)
+            return;
+        this.list.hidden = false;
+        this.trigger.setAttribute("aria-expanded", "true");
+        this.highlight(Math.max(0, this.choices.findIndex((choice) => choice.value === this.trigger.value)));
+        this.element.ownerDocument.addEventListener("pointerdown", this.onOutside);
+    }
+    close() {
+        this.list.hidden = true;
+        this.trigger.setAttribute("aria-expanded", "false");
+        this.trigger.removeAttribute("aria-activedescendant");
+        this.element.ownerDocument.removeEventListener("pointerdown", this.onOutside);
+    }
+    highlight(index) {
+        this.activeIndex = Math.max(0, Math.min(this.choices.length - 1, index));
+        Array.from(this.list.children).forEach((option, optionIndex) => {
+            option.toggleAttribute("data-active", optionIndex === this.activeIndex);
+        });
+        const active = this.list.children[this.activeIndex];
+        if (active) {
+            this.trigger.setAttribute("aria-activedescendant", active.id);
+            active.scrollIntoView({ block: "nearest" });
+        }
+    }
+    commit(index) {
+        if (this.destroyed || this.trigger.disabled || this.list.hidden)
+            return;
+        const choice = this.choices[index];
+        this.close();
+        if (choice && choice.value !== this.trigger.value)
+            this.onChange(choice.value);
+    }
+    onOutside = (event) => {
+        if (!event.composedPath().includes(this.element))
+            this.close();
+    };
+    onBlur = (event) => {
+        const target = event.relatedTarget;
+        if (!(target instanceof this.element.ownerDocument.defaultView.Node) || !this.element.contains(target))
+            this.close();
+    };
+    onKey = (event) => {
+        if (event.altKey || event.ctrlKey || event.metaKey || this.trigger.disabled)
+            return;
+        if (event.key === "Tab") {
+            this.close();
+            return;
+        }
+        if (event.key === "Escape") {
+            if (!this.list.hidden) {
+                event.preventDefault();
+                event.stopPropagation();
+                this.close();
+            }
+            return;
+        }
+        if (["Enter", " "].includes(event.key)) {
+            event.preventDefault();
+            if (this.list.hidden)
+                this.open();
+            else
+                this.commit(this.activeIndex);
+            return;
+        }
+        if (["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) {
+            event.preventDefault();
+            const wasOpen = !this.list.hidden;
+            this.open();
+            if (event.key === "Home")
+                this.highlight(0);
+            else if (event.key === "End")
+                this.highlight(this.choices.length - 1);
+            else if (wasOpen)
+                this.highlight(this.activeIndex + (event.key === "ArrowDown" ? 1 : -1));
+            return;
+        }
+        if (event.key.length === 1 && event.key.trim()) {
+            const start = this.list.hidden ? -1 : this.activeIndex;
+            this.open();
+            const indexes = this.choices.map((_, index) => (start + index + 1) % this.choices.length);
+            const match = indexes.find((index) => this.choices[index].label.toLocaleLowerCase().startsWith(event.key.toLocaleLowerCase()));
+            if (match !== undefined) {
+                event.preventDefault();
+                this.highlight(match);
+            }
+        }
+    };
+}

package/dist/browser.d.ts

@@ -1,4 +1,5 @@
-/** Public browser entry: expose the player contract while keeping its implementation under the browser module. */
+/** Public browser entry: expose the player and reusable choice control while keeping implementations under the browser module. */
 export { createPlayer } from "./browser/player.js";
 export type { FlowPlayer, PlayerErrorDetail, PlayerEventMap, PlayerInteractionDetail, PlayerOptions, PlayerState } from "./browser/player.js";
 export type { ThemeName } from "./core/model.js";
+export { SelectControl, type SelectChoice } from "./browser/select-control.js";

package/dist/browser.js

@@ -1,2 +1,3 @@
-/** Public browser entry: expose the player contract while keeping its implementation under the browser module. */
+/** Public browser entry: expose the player and reusable choice control while keeping implementations under the browser module. */
 export { createPlayer } from "./browser/player.js";
+export { SelectControl } from "./browser/select-control.js";

package/dist/core/diagram.d.ts

@@ -1,7 +1,7 @@
-import type { DiagramDocument, EvaluateOptions, HitObject, DiagramPoint, DiagramFrameState } from "./model.js";
+import type { DiagramDocument, DiagramBeat, EvaluateOptions, HitObject, DiagramPoint, DiagramFrameState } from "./model.js";
 /**
  * Validate and copy a document, then compile its timeline; later input mutations cannot affect evaluation.
- * @throws {DiagramValidationError} If document structure, values or references are invalid.
+ * @throws {DiagramValidationError} If document structure, values or references are invalid, or derived flow timing is non-finite.
  */
 export declare function createDiagram(input: DiagramDocument): Diagram;
 /** One-shot static SVG export; use createDiagram to reuse compilation across repeated evaluations or exports. */
@@ -10,6 +10,8 @@ export declare function renderSvg(document: DiagramDocument, timeMs?: number, op
 export interface Diagram {
     /** Global timeline duration in milliseconds; zero for static diagrams. */
     readonly totalDuration: number;
+    /** Frozen compiled intervals, including single-flow movement and arrival hold; use these for navigation and export scheduling. */
+    readonly beats: readonly DiagramBeat[];
     /**
      * Evaluate a frame; finite times clamp to [0, totalDuration], and non-finite times become zero.
      * Beat intervals include their start and exclude their end; totalDuration returns the completed final beat.