flowsvg 0.0.0-stage → 0.1.0

package/dist/player-controls.js

@@ -0,0 +1,80 @@
+const DEFAULT_SPEEDS = [0.5, 1, 1.5, 2];
+/**
+ * Persistent control DOM translates input to commands; render synchronizes labels, progress and disabled states.
+ * Own no clock or independent position; time-related controls are disabled for static documents.
+ */
+export class PlayerControls {
+    element;
+    play;
+    previous;
+    next;
+    progress;
+    scene;
+    speed;
+    sceneChoices;
+    constructor(owner, actions) {
+        this.element = owner.createElement("div");
+        this.element.className = "flowsvg-controls";
+        this.play = createButton(owner, "Play", actions.toggle);
+        this.previous = createButton(owner, "Previous step", () => actions.step(-1));
+        this.next = createButton(owner, "Next step", () => actions.step(1));
+        this.progress = owner.createElement("input");
+        this.progress.type = "range";
+        this.progress.min = "0";
+        this.progress.step = "any";
+        this.progress.setAttribute("aria-label", "Progress");
+        this.progress.addEventListener("input", () => actions.seek(Number(this.progress.value)));
+        this.scene = createSelect(owner, "Scene");
+        this.scene.addEventListener("change", () => {
+            const choice = this.sceneChoices?.find((scene) => scene.id === this.scene.value);
+            if (choice)
+                actions.seek(choice.startMs);
+        });
+        this.speed = createSelect(owner, "Speed");
+        this.speed.addEventListener("change", () => actions.setSpeed(Number(this.speed.value)));
+        this.element.append(this.previous, this.play, this.next, this.progress, this.scene, this.speed);
+    }
+    /** Update existing controls; scene choices change by reference and custom speeds are added as options. */
+    render(state) {
+        const isStatic = state.totalDuration === 0;
+        this.play.textContent = state.playing ? "Pause" : "Play";
+        this.play.setAttribute("aria-label", this.play.textContent);
+        this.play.disabled = isStatic || (!state.playing && state.timeMs >= state.totalDuration);
+        this.previous.disabled = isStatic || state.timeMs <= 0;
+        this.next.disabled = isStatic || state.timeMs >= state.totalDuration;
+        this.progress.disabled = isStatic;
+        this.progress.max = String(state.totalDuration);
+        this.progress.value = String(state.timeMs);
+        this.scene.disabled = isStatic;
+        this.speed.disabled = isStatic;
+        if (this.sceneChoices !== state.scenes) {
+            this.sceneChoices = state.scenes;
+            this.scene.replaceChildren(...state.scenes.map((scene) => createOption(this.scene.ownerDocument, scene.id, scene.label)));
+        }
+        this.scene.value = state.sceneId ?? "";
+        const speeds = [...new Set([...DEFAULT_SPEEDS, state.speed])].sort((left, right) => left - right);
+        if (!Array.from(this.speed.options).some((option) => Number(option.value) === state.speed)) {
+            this.speed.replaceChildren(...speeds.map((speed) => createOption(this.speed.ownerDocument, String(speed), `${speed}×`)));
+        }
+        this.speed.value = String(state.speed);
+    }
+}
+function createButton(owner, label, click) {
+    const button = owner.createElement("button");
+    button.type = "button";
+    button.textContent = label;
+    button.setAttribute("aria-label", label);
+    button.addEventListener("click", click);
+    return button;
+}
+function createSelect(owner, label) {
+    const select = owner.createElement("select");
+    select.setAttribute("aria-label", label);
+    return select;
+}
+function createOption(owner, value, label) {
+    const option = owner.createElement("option");
+    option.value = value;
+    option.textContent = label;
+    return option;
+}

package/dist/player-lifecycle.d.ts

@@ -0,0 +1,6 @@
+/** Player layout and page-visibility resources, scoped to the lifetime of one instance. */
+/**
+ * Set up flex/aspect-preserving SVG containment and pause on page hiding; restoring visibility does not resume.
+ * The returned cleanup removes owned styles/listeners and restores the host's display/flexDirection.
+ */
+export declare function attachPlayerLifecycle(host: HTMLElement, canvas: HTMLElement, pause: () => void): () => void;

package/dist/player-lifecycle.js

@@ -0,0 +1,31 @@
+/** Player layout and page-visibility resources, scoped to the lifetime of one instance. */
+/**
+ * Set up flex/aspect-preserving SVG containment and pause on page hiding; restoring visibility does not resume.
+ * The returned cleanup removes owned styles/listeners and restores the host's display/flexDirection.
+ */
+export function attachPlayerLifecycle(host, canvas, pause) {
+    const owner = host.ownerDocument;
+    const previousDisplay = host.style.display;
+    const previousDirection = host.style.flexDirection;
+    host.style.display = "flex";
+    host.style.flexDirection = "column";
+    // Native SVG scaling and flex layout respond to container changes without allocating a ResizeObserver.
+    canvas.style.flex = "1 1 auto";
+    canvas.style.minHeight = "0";
+    canvas.style.minWidth = "0";
+    canvas.style.overflow = "hidden";
+    const style = owner.createElement("style");
+    style.textContent = ".flowsvg-canvas > svg { display: block; width: 100%; height: 100%; }";
+    host.append(style);
+    const onVisibilityChange = () => {
+        if (owner.visibilityState === "hidden")
+            pause();
+    };
+    owner.addEventListener("visibilitychange", onVisibilityChange);
+    return () => {
+        owner.removeEventListener("visibilitychange", onVisibilityChange);
+        style.remove();
+        host.style.display = previousDisplay;
+        host.style.flexDirection = previousDirection;
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,48 @@
+/**
+ * React adapter for component lifecycle, props, events and imperative controls.
+ * Playback/rendering reuse browser; imports do not create DOM, and the player is created only on mount.
+ */
+import { type CSSProperties } from "react";
+import { type PlayerErrorDetail, type PlayerState } from "./browser.js";
+import type { DiagramDocument, ThemeName } from "./core.js";
+/** React document, visual options and callbacks; document reference changes trigger a reload. */
+export interface FlowPlayerProps {
+    document: DiagramDocument;
+    /** Positive playback multiplier; omit to use the player default. */
+    speed?: number;
+    theme?: ThemeName;
+    controls?: boolean;
+    /** Defaults to false: hover marks borders only. True also highlights backgrounds, including groups. */
+    hoverFill?: boolean;
+    reducedMotion?: boolean;
+    /** Initial position in milliseconds, applied once; use seek afterward, and document reloads reset to zero. */
+    initialTimeMs?: number;
+    className?: string;
+    style?: CSSProperties;
+    onStepChange?: (state: PlayerState) => void;
+    onTimeUpdate?: (state: PlayerState) => void;
+    onPlayStateChange?: (state: PlayerState) => void;
+    onError?: (detail: PlayerErrorDetail) => void;
+}
+/** Imperative controls for a mounted component; calls before mounting or after unmounting throw a not-mounted error. */
+export interface FlowPlayerHandle {
+    /** Resume from the current position when playback can advance. */
+    play(): void;
+    /** Pause while retaining the current frame. */
+    pause(): void;
+    /** Seek in milliseconds, clamping to the timeline; non-finite values become zero. */
+    seek(timeMs: number): void;
+    /** Pause and jump to a beat boundary; backward from inside a beat goes to that beat's start. */
+    step(direction: 1 | -1): void;
+    /** Set a finite positive multiplier; ignore invalid values. */
+    setSpeed(speed: number): void;
+    /** Reset/pause at zero on success; emit an error and retain playback state if validation fails. */
+    load(document: DiagramDocument): void;
+    /** Read the current browser-player snapshot. */
+    getState(): PlayerState;
+}
+/**
+ * SSR renders only a host container; an effect mounts the browser player and unmount cleanup releases it.
+ * Document reference changes call load; visual/control options rebuild the instance, with initial positioning applied once.
+ */
+export declare const FlowPlayer: import("react").ForwardRefExoticComponent<FlowPlayerProps & import("react").RefAttributes<FlowPlayerHandle>>;

package/dist/react.js

@@ -0,0 +1,126 @@
+/**
+ * React adapter for component lifecycle, props, events and imperative controls.
+ * Playback/rendering reuse browser; imports do not create DOM, and the player is created only on mount.
+ */
+import { createElement, forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { createPlayer } from "./browser.js";
+/**
+ * SSR renders only a host container; an effect mounts the browser player and unmount cleanup releases it.
+ * Document reference changes call load; visual/control options rebuild the instance, with initial positioning applied once.
+ */
+export const FlowPlayer = forwardRef(function FlowPlayer(props, ref) {
+    const hostRef = useRef(null);
+    const playerRef = useRef(null);
+    const eventCleanupRef = useRef(null);
+    const callbacksRef = useRef({});
+    const documentRef = useRef(null);
+    const optionsRef = useRef(null);
+    const initialTimeRef = useRef(props.initialTimeMs);
+    const initialAppliedRef = useRef(false);
+    // Listeners read current callbacks through a stable ref so callback identity changes do not rebuild the player.
+    callbacksRef.current = {
+        onStepChange: props.onStepChange,
+        onTimeUpdate: props.onTimeUpdate,
+        onPlayStateChange: props.onPlayStateChange,
+        onError: props.onError
+    };
+    useImperativeHandle(ref, () => ({
+        play: () => requirePlayer(playerRef).play(),
+        pause: () => requirePlayer(playerRef).pause(),
+        seek: (timeMs) => requirePlayer(playerRef).seek(timeMs),
+        step: (direction) => requirePlayer(playerRef).step(direction),
+        setSpeed: (speed) => requirePlayer(playerRef).setSpeed(speed),
+        load: (document) => requirePlayer(playerRef).load(document),
+        getState: () => requirePlayer(playerRef).getState()
+    }), []);
+    useEffect(() => {
+        const host = hostRef.current;
+        if (!host)
+            return;
+        const nextOptions = {
+            theme: props.theme,
+            controls: props.controls,
+            hoverFill: props.hoverFill,
+            reducedMotion: props.reducedMotion
+        };
+        const existing = playerRef.current;
+        const optionsChanged = !sameOptions(optionsRef.current, nextOptions);
+        if (existing && !optionsChanged && documentRef.current !== props.document) {
+            existing.load(props.document);
+            documentRef.current = props.document;
+        }
+        else if (!existing || optionsChanged) {
+            // Detach old callbacks before replacement so old lifecycle events cannot reach the new component state.
+            eventCleanupRef.current?.();
+            existing?.destroy();
+            const player = createPlayer(host, props.document, nextOptions);
+            // A new instance needs current props even when the separate speed effect has no changed dependency.
+            if (props.speed !== undefined)
+                player.setSpeed(props.speed);
+            eventCleanupRef.current = attachPlayerEvents(player, callbacksRef);
+            playerRef.current = player;
+            documentRef.current = props.document;
+            optionsRef.current = nextOptions;
+            if (!initialAppliedRef.current && initialTimeRef.current !== undefined) {
+                player.seek(initialTimeRef.current);
+            }
+            initialAppliedRef.current = true;
+            return;
+        }
+        optionsRef.current = nextOptions;
+    }, [props.document, props.theme, props.controls, props.reducedMotion, props.hoverFill]);
+    useEffect(() => {
+        const player = playerRef.current;
+        if (player && props.speed !== undefined)
+            player.setSpeed(props.speed);
+    }, [props.speed]);
+    useEffect(() => () => {
+        eventCleanupRef.current?.();
+        eventCleanupRef.current = null;
+        playerRef.current?.destroy();
+        playerRef.current = null;
+        documentRef.current = null;
+        optionsRef.current = null;
+        initialAppliedRef.current = false;
+    }, []);
+    const className = props.className ? `flowsvg ${props.className}` : "flowsvg";
+    return createElement("div", { ref: hostRef, className, style: props.style });
+});
+function requirePlayer(playerRef) {
+    if (!playerRef.current)
+        throw new Error("FlowPlayer is not mounted");
+    return playerRef.current;
+}
+function sameOptions(previous, next) {
+    if (!previous)
+        return false;
+    return previous.theme === next.theme
+        && previous.controls === next.controls
+        && previous.hoverFill === next.hoverFill
+        && previous.reducedMotion === next.reducedMotion;
+}
+/** Translate browser event details to component callbacks; share cleanup between replacement and unmount. */
+function attachPlayerEvents(player, callbacksRef) {
+    const onStepChange = (event) => {
+        callbacksRef.current.onStepChange?.(event.detail);
+    };
+    const onTimeUpdate = (event) => {
+        callbacksRef.current.onTimeUpdate?.(event.detail);
+    };
+    const onPlayStateChange = (event) => {
+        callbacksRef.current.onPlayStateChange?.(event.detail);
+    };
+    const onError = (event) => {
+        callbacksRef.current.onError?.(event.detail);
+    };
+    player.element.addEventListener("stepchange", onStepChange);
+    player.element.addEventListener("timeupdate", onTimeUpdate);
+    player.element.addEventListener("playstatechange", onPlayStateChange);
+    player.element.addEventListener("error", onError);
+    return () => {
+        player.element.removeEventListener("stepchange", onStepChange);
+        player.element.removeEventListener("timeupdate", onTimeUpdate);
+        player.element.removeEventListener("playstatechange", onPlayStateChange);
+        player.element.removeEventListener("error", onError);
+    };
+}

package/dist/styles.css

@@ -0,0 +1,47 @@
+/* Control and canvas focus styles; CSS variables customize controls only. The core theme resolves diagram colors. */
+.flowsvg-canvas:focus-visible {
+  outline: 3px solid #2563eb;
+  outline-offset: 3px;
+}
+
+.flowsvg-controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem;
+  color: var(--flowsvg-control-color, #172033);
+  background: var(--flowsvg-control-background, #ffffff);
+  font: 1rem/1.4 system-ui, sans-serif;
+}
+
+.flowsvg-controls :is(button, input, select) {
+  box-sizing: border-box;
+  min-height: 2.75rem;
+  max-width: 100%;
+  color: var(--flowsvg-control-color, #172033);
+  background: var(--flowsvg-control-background, #ffffff);
+  border: 1px solid var(--flowsvg-control-border, #64748b);
+  border-radius: 0.25rem;
+  font: inherit;
+  accent-color: var(--flowsvg-control-accent, #2563eb);
+}
+
+.flowsvg-controls :is(button, select) {
+  padding: 0.5rem 0.75rem;
+}
+
+.flowsvg-controls :is(button, input, select):focus-visible {
+  outline: 3px solid var(--flowsvg-control-focus, #2563eb);
+  outline-offset: 3px;
+}
+
+.flowsvg-controls :disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+
+.flowsvg-controls input[type="range"] {
+  flex: 1 1 10rem;
+  min-width: 4rem;
+}

package/dist/svg-dom.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SVG DOM synchronization: apply core-generated static SVG to existing elements and paint order.
+ * This layer stores no animation state and does not recalculate time, geometry or colors.
+ */
+/** Apply core serialization while retaining reusable SVG elements; accept only markup produced by the core. */
+export declare function updateSvgDom(host: HTMLElement, markup: string): void;

package/dist/svg-dom.js

@@ -0,0 +1,74 @@
+/**
+ * SVG DOM synchronization: apply core-generated static SVG to existing elements and paint order.
+ * This layer stores no animation state and does not recalculate time, geometry or colors.
+ */
+/** Apply core serialization while retaining reusable SVG elements; accept only markup produced by the core. */
+export function updateSvgDom(host, markup) {
+    const template = host.ownerDocument.createElement("template");
+    template.innerHTML = markup;
+    const next = template.content.firstElementChild;
+    if (!next)
+        throw new Error("Core SVG output is empty");
+    const current = host.firstElementChild;
+    if (!current || current.tagName !== next.tagName) {
+        host.replaceChildren(next);
+        return;
+    }
+    synchronizeElement(current, next);
+}
+/** Remove obsolete attributes before applying new ones so visibility/style changes leave no stale paint. */
+function synchronizeElement(current, next) {
+    for (const attribute of Array.from(current.attributes)) {
+        if (!next.hasAttribute(attribute.name))
+            current.removeAttribute(attribute.name);
+    }
+    for (const attribute of Array.from(next.attributes)) {
+        if (current.getAttribute(attribute.name) !== attribute.value)
+            current.setAttribute(attribute.name, attribute.value);
+    }
+    if (next.children.length === 0) {
+        if (current.textContent !== next.textContent)
+            current.textContent = next.textContent;
+        return;
+    }
+    synchronizeChildren(current, next);
+}
+/**
+ * Match object keys first, reuse unkeyed elements by tag, and synchronize paint order.
+ * Retain matching elements so per-frame updates preserve interactions attached by the host.
+ */
+function synchronizeChildren(current, next) {
+    const existing = Array.from(current.children);
+    const keyed = new Map();
+    for (const child of existing) {
+        const key = elementKey(child);
+        if (key !== undefined)
+            keyed.set(key, child);
+    }
+    const used = new Set();
+    let cursor = current.firstElementChild;
+    for (const child of Array.from(next.children)) {
+        const key = elementKey(child);
+        const match = key === undefined
+            ? existing.find((candidate) => !used.has(candidate) && elementKey(candidate) === undefined && candidate.tagName === child.tagName)
+            : keyed.get(key);
+        const target = match?.tagName === child.tagName ? match : child;
+        used.add(target);
+        if (target !== cursor)
+            current.insertBefore(target, cursor);
+        if (target === match)
+            synchronizeElement(target, child);
+        cursor = target.nextElementSibling;
+    }
+    for (const child of existing) {
+        if (!used.has(child))
+            child.remove();
+    }
+}
+function elementKey(element) {
+    const objectId = element.getAttribute("data-id");
+    if (objectId !== null)
+        return `object:${objectId}`;
+    const id = element.getAttribute("id");
+    return id === null ? undefined : `id:${id}`;
+}

package/dist/theme.d.ts

@@ -0,0 +1,15 @@
+/** Shared deterministic paint values for core rendering and browser-only interaction feedback. */
+export interface ThemePalette {
+    background: string;
+    fill: string;
+    stroke: string;
+    text: string;
+    mutedText: string;
+    tagText: string;
+    tagFill: string;
+    accentText: string;
+    edge: string;
+    highlight: string;
+}
+/** Select a palette without consulting browser preferences. */
+export declare function resolveThemePalette(theme: "light" | "dark" | undefined): ThemePalette;

package/dist/theme.js

@@ -0,0 +1,6 @@
+const LIGHT_PALETTE = { background: "#ffffff", fill: "#e8eef7", stroke: "#253858", text: "#172033", mutedText: "#5f6f86", tagText: "#164b9b", tagFill: "#eaf1ff", accentText: "#0864d7", edge: "#4b607d", highlight: "#f59e0b" };
+const DARK_PALETTE = { background: "#101828", fill: "#26344c", stroke: "#d9e2f2", text: "#f4f7fb", mutedText: "#b3c0d3", tagText: "#e8f1ff", tagFill: "#344e73", accentText: "#88bdff", edge: "#a9bad4", highlight: "#fbbf24" };
+/** Select a palette without consulting browser preferences. */
+export function resolveThemePalette(theme) {
+    return theme === "dark" ? DARK_PALETTE : LIGHT_PALETTE;
+}

package/dist/timeline.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Deterministic global timeline: compile actions/snapshots and evaluate base styles, visibility, highlights and focus.
+ * Spatial layout and SVG output belong to the core; theme defaults are supplied only during evaluation.
+ */
+import type { DiagramDocument, EvaluateOptions, FlowDirection, NodeVisualState, EdgeVisualState } from "./core.js";
+type VisualValues = NodeVisualState & EdgeVisualState;
+/** Evaluation-time theme defaults; unspecified snapshot colors remain unresolved so compilation does not fix a theme. */
+export interface TimelinePalette {
+    fill: string;
+    stroke: string;
+    edge: string;
+}
+/** One transfer in a synchronized beat-local group; no transfer persists in inherited snapshots. */
+export interface CompiledFlow {
+    target: string;
+    direction: FlowDirection;
+    text?: string;
+}
+/** Object transition result; highlight is the overlay weight, while highlighted is the target logical state. */
+export interface TimelineObject {
+    visible: boolean;
+    opacity: number;
+    highlight: number;
+    highlighted: boolean;
+    values: VisualValues;
+}
+/** Timeline state/progress only; the core adds absolute geometry, text, edge routing and camera bounds. */
+export interface TimelineFrame {
+    timeMs: number;
+    sceneId: string | null;
+    beatId: string | null;
+    beatProgress: number;
+    transitionProgress: number;
+    focusBefore: string | null;
+    focusAfter: string | null;
+    caption?: string;
+    objects: ReadonlyMap<string, TimelineObject>;
+    flows: readonly CompiledFlow[];
+}
+/**
+ * Flatten scenes into continuous beats and compile snapshots once; queries locate beats by binary search.
+ * Each beat inherits the previous final state; evaluation is independent of query order and clocks.
+ * See docs/adr/0002-continuous-global-timeline.md for time semantics.
+ */
+export declare class CompiledTimeline {
+    readonly totalDuration: number;
+    private readonly beats;
+    private readonly initial;
+    private readonly title?;
+    constructor(document: DiagramDocument);
+    /** Clamp finite times globally; reduced motion skips interpolation but preserves beat selection and total duration. */
+    evaluateAt(timeMs: number, options: EvaluateOptions, palette: TimelinePalette): TimelineFrame;
+    /** Select the next beat at endMs, retaining the last beat at total duration; static documents return undefined. */
+    private findBeat;
+}
+/** Interpolate validated hexadecimal RGB/RGBA channels; preserve endpoint strings and normalize intermediate colors. */
+export declare function mixColor(source: string, target: string, progress: number): string;
+export {};