flowsvg 0.1.0 → 0.2.0

package/dist/adapters/react.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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/player.js";
+import type { DiagramDocument, ThemeName } from "../core/model.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;
+    /** Defaults to false. Changes update live loop mode without rebuilding the player. */
+    loop?: boolean;
+    theme?: ThemeName;
+    controls?: boolean;
+    /** Defaults to false. Enable GIF downloads when controls are visible; export is independent of playback. */
+    gifExport?: 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;
+    onLoopChange?: (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;
+    /** Toggle whole-timeline playback without changing the current position or play state. */
+    setLoop(loop: boolean): 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/adapters/react.js

@@ -0,0 +1,138 @@
+/**
+ * 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/player.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,
+        onLoopChange: props.onLoopChange,
+        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),
+        setLoop: (loop) => requirePlayer(playerRef).setLoop(loop),
+        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,
+            gifExport: props.gifExport,
+            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, loop: props.loop ?? existing?.getState().loop });
+            // 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.gifExport, props.reducedMotion, props.hoverFill]);
+    useEffect(() => {
+        const player = playerRef.current;
+        if (player && props.speed !== undefined)
+            player.setSpeed(props.speed);
+    }, [props.speed]);
+    useEffect(() => {
+        playerRef.current?.setLoop(props.loop ?? false);
+    }, [props.loop]);
+    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.gifExport === next.gifExport
+        && 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 onLoopChange = (event) => {
+        callbacksRef.current.onLoopChange?.(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("loopchange", onLoopChange);
+    player.element.addEventListener("error", onError);
+    return () => {
+        player.element.removeEventListener("stepchange", onStepChange);
+        player.element.removeEventListener("timeupdate", onTimeUpdate);
+        player.element.removeEventListener("playstatechange", onPlayStateChange);
+        player.element.removeEventListener("loopchange", onLoopChange);
+        player.element.removeEventListener("error", onError);
+    };
+}

package/dist/adapters/vue.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Vue 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, type PropType } from "vue";
+import { type PlayerErrorDetail, type PlayerState } from "../browser/player.js";
+import type { DiagramDocument, ThemeName } from "../core/model.js";
+/** Vue 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;
+    /** Defaults to false. Changes update live loop mode without rebuilding the player. */
+    loop?: boolean;
+    theme?: ThemeName;
+    controls?: boolean;
+    /** Defaults to false. Enable GIF downloads when controls are visible; export is independent of playback. */
+    gifExport?: 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;
+    onLoopChange?: (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;
+    /** Toggle whole-timeline playback without changing the current position or play state. */
+    setLoop(loop: boolean): 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 the host; onMounted creates the player and onBeforeUnmount releases it.
+ * Document reference changes call load; option changes rebuild, and exposed methods delegate to the browser instance.
+ */
+export declare const FlowPlayer: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    readonly document: {
+        readonly type: PropType<DiagramDocument>;
+        readonly required: true;
+    };
+    readonly speed: {
+        readonly type: NumberConstructor;
+        readonly required: false;
+    };
+    readonly loop: {
+        readonly type: PropType<boolean | undefined>;
+        readonly default: undefined;
+    };
+    readonly theme: {
+        readonly type: PropType<ThemeName>;
+        readonly required: false;
+    };
+    readonly gifExport: {
+        readonly type: PropType<boolean | undefined>;
+        readonly default: undefined;
+    };
+    readonly controls: {
+        readonly type: PropType<boolean | undefined>;
+        readonly default: undefined;
+    };
+    readonly hoverFill: {
+        readonly type: PropType<boolean | undefined>;
+        readonly default: undefined;
+    };
+    readonly reducedMotion: {
+        readonly type: PropType<boolean | undefined>;
+        readonly default: undefined;
+    };
+    readonly initialTimeMs: {
+        readonly type: NumberConstructor;
+        readonly required: false;
+    };
+    readonly className: {
+        readonly type: StringConstructor;
+        readonly required: false;
+    };
+    readonly style: {
+        readonly type: PropType<CSSProperties>;
+        readonly required: false;
+    };
+    readonly onStepChange: {
+        readonly type: PropType<(state: PlayerState) => void>;
+        readonly required: false;
+    };
+    readonly onTimeUpdate: {
+        readonly type: PropType<(state: PlayerState) => void>;
+        readonly required: false;
+    };
+    readonly onPlayStateChange: {
+        readonly type: PropType<(state: PlayerState) => void>;
+        readonly required: false;
+    };
+    readonly onLoopChange: {
+        readonly type: PropType<(state: PlayerState) => void>;
+        readonly required: false;
+    };
+    readonly onError: {
+        readonly type: PropType<(detail: PlayerErrorDetail) => void>;
+        readonly required: false;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    stepchange: (_state: PlayerState) => true;
+    timeupdate: (_state: PlayerState) => true;
+    playstatechange: (_state: PlayerState) => true;
+    loopchange: (_state: PlayerState) => true;
+    error: (_detail: PlayerErrorDetail) => true;
+}, string, import("vue").PublicProps, Readonly<{
+    readonly document: DiagramDocument;
+} & {
+    readonly style?: CSSProperties | undefined;
+    readonly theme?: ThemeName | undefined;
+    readonly reducedMotion?: boolean | undefined;
+    readonly speed?: number | undefined;
+    readonly controls?: boolean | undefined;
+    readonly loop?: boolean | undefined;
+    readonly gifExport?: boolean | undefined;
+    readonly hoverFill?: boolean | undefined;
+    readonly initialTimeMs?: number | undefined;
+    readonly className?: string | undefined;
+    readonly onStepChange?: ((state: PlayerState) => void) | undefined;
+    readonly onTimeUpdate?: ((state: PlayerState) => void) | undefined;
+    readonly onPlayStateChange?: ((state: PlayerState) => void) | undefined;
+    readonly onLoopChange?: ((state: PlayerState) => void) | undefined;
+    readonly onError?: ((detail: PlayerErrorDetail) => void) | undefined;
+} & {
+    onError?: ((_detail: PlayerErrorDetail) => any) | undefined;
+    onTimeupdate?: ((_state: PlayerState) => any) | undefined;
+    onPlaystatechange?: ((_state: PlayerState) => any) | undefined;
+    onStepchange?: ((_state: PlayerState) => any) | undefined;
+    onLoopchange?: ((_state: PlayerState) => any) | undefined;
+}>, {
+    readonly reducedMotion: boolean | undefined;
+    readonly controls: boolean | undefined;
+    readonly loop: boolean | undefined;
+    readonly gifExport: boolean | undefined;
+    readonly hoverFill: boolean | undefined;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}>;

package/dist/adapters/vue.js

@@ -0,0 +1,177 @@
+/**
+ * Vue 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 { defineComponent, h, onBeforeUnmount, onMounted, ref, watch } from "vue";
+import { createPlayer } from "../browser/player.js";
+const propsOptions = {
+    document: { type: Object, required: true },
+    speed: { type: Number, required: false },
+    loop: { type: Boolean, default: undefined },
+    theme: { type: String, required: false },
+    gifExport: { type: Boolean, default: undefined },
+    controls: { type: Boolean, default: undefined },
+    hoverFill: { type: Boolean, default: undefined },
+    reducedMotion: { type: Boolean, default: undefined },
+    initialTimeMs: { type: Number, required: false },
+    className: { type: String, required: false },
+    style: { type: Object, required: false },
+    onStepChange: { type: Function, required: false },
+    onTimeUpdate: { type: Function, required: false },
+    onPlayStateChange: { type: Function, required: false },
+    onLoopChange: { type: Function, required: false },
+    onError: { type: Function, required: false }
+};
+/**
+ * SSR renders only the host; onMounted creates the player and onBeforeUnmount releases it.
+ * Document reference changes call load; option changes rebuild, and exposed methods delegate to the browser instance.
+ */
+export const FlowPlayer = defineComponent({
+    name: "FlowPlayer",
+    inheritAttrs: false,
+    props: propsOptions,
+    emits: {
+        stepchange: (_state) => true,
+        timeupdate: (_state) => true,
+        playstatechange: (_state) => true,
+        loopchange: (_state) => true,
+        error: (_detail) => true
+    },
+    setup(props, { attrs, emit, expose }) {
+        const hostRef = ref(null);
+        let player;
+        let cleanupEvents;
+        let optionsSnapshot;
+        let mounted = false;
+        let initialApplied = false;
+        const requirePlayer = () => {
+            if (!player)
+                throw new Error("FlowPlayer is not mounted");
+            return player;
+        };
+        expose({
+            play: () => requirePlayer().play(),
+            pause: () => requirePlayer().pause(),
+            seek: (timeMs) => requirePlayer().seek(timeMs),
+            step: (direction) => requirePlayer().step(direction),
+            setSpeed: (speed) => requirePlayer().setSpeed(speed),
+            setLoop: (loop) => requirePlayer().setLoop(loop),
+            load: (document) => requirePlayer().load(document),
+            getState: () => requirePlayer().getState()
+        });
+        const currentOptions = () => ({
+            theme: props.theme,
+            controls: props.controls,
+            gifExport: props.gifExport,
+            hoverFill: props.hoverFill,
+            reducedMotion: props.reducedMotion
+        });
+        const attachEvents = (next) => {
+            const onStepChange = (event) => {
+                const state = event.detail;
+                emit("stepchange", state);
+                props.onStepChange?.(state);
+            };
+            const onTimeUpdate = (event) => {
+                const state = event.detail;
+                emit("timeupdate", state);
+                props.onTimeUpdate?.(state);
+            };
+            const onPlayStateChange = (event) => {
+                const state = event.detail;
+                emit("playstatechange", state);
+                props.onPlayStateChange?.(state);
+            };
+            const onLoopChange = (event) => {
+                const state = event.detail;
+                emit("loopchange", state);
+                props.onLoopChange?.(state);
+            };
+            const onError = (event) => {
+                const detail = event.detail;
+                // Vue's error event already invokes the onError prop; an explicit callback would duplicate delivery.
+                emit("error", detail);
+            };
+            next.element.addEventListener("stepchange", onStepChange);
+            next.element.addEventListener("timeupdate", onTimeUpdate);
+            next.element.addEventListener("playstatechange", onPlayStateChange);
+            next.element.addEventListener("loopchange", onLoopChange);
+            next.element.addEventListener("error", onError);
+            return () => {
+                next.element.removeEventListener("stepchange", onStepChange);
+                next.element.removeEventListener("timeupdate", onTimeUpdate);
+                next.element.removeEventListener("playstatechange", onPlayStateChange);
+                next.element.removeEventListener("loopchange", onLoopChange);
+                next.element.removeEventListener("error", onError);
+            };
+        };
+        // Keep initialApplied across option rebuilds so initialTimeMs is not reapplied.
+        const mount = (previousLoop) => {
+            const host = hostRef.value;
+            if (!host || player)
+                return;
+            const next = createPlayer(host, props.document, { ...currentOptions(), loop: props.loop ?? previousLoop });
+            player = next;
+            optionsSnapshot = currentOptions();
+            cleanupEvents = attachEvents(next);
+            if (props.speed !== undefined)
+                next.setSpeed(props.speed);
+            if (!initialApplied && props.initialTimeMs !== undefined)
+                next.seek(props.initialTimeMs);
+            initialApplied = true;
+        };
+        // Detach event forwarding first so destruction does not call an unmounted component.
+        const unmount = () => {
+            cleanupEvents?.();
+            cleanupEvents = undefined;
+            player?.destroy();
+            player = undefined;
+            optionsSnapshot = undefined;
+        };
+        const rebuild = () => {
+            if (!mounted || !player)
+                return;
+            const previousLoop = player.getState().loop;
+            unmount();
+            mount(previousLoop);
+        };
+        onMounted(() => {
+            mounted = true;
+            mount();
+        });
+        watch(() => props.document, (next, previous) => {
+            if (!mounted || next === previous || !player)
+                return;
+            player.load(next);
+        });
+        watch(() => [props.theme, props.controls, props.gifExport, props.reducedMotion, props.hoverFill], () => {
+            const next = currentOptions();
+            if (!mounted || sameOptions(optionsSnapshot, next))
+                return;
+            rebuild();
+        });
+        watch(() => props.speed, (speed) => {
+            if (player && speed !== undefined)
+                player.setSpeed(speed);
+        });
+        watch(() => props.loop, (loop) => player?.setLoop(loop ?? false));
+        onBeforeUnmount(() => {
+            mounted = false;
+            unmount();
+        });
+        return () => h("div", {
+            ref: hostRef,
+            class: ["flowsvg", props.className, attrs.class],
+            style: [props.style, attrs.style]
+        });
+    }
+});
+function sameOptions(previous, next) {
+    if (!previous)
+        return false;
+    return previous.theme === next.theme
+        && previous.controls === next.controls
+        && previous.gifExport === next.gifExport
+        && previous.hoverFill === next.hoverFill
+        && previous.reducedMotion === next.reducedMotion;
+}

package/dist/adapters/web-component.d.ts

@@ -0,0 +1,111 @@
+import type { DiagramDocument, EvaluateOptions, ThemeName } from "../core/model.js";
+import { type PlayerErrorDetail, type PlayerState } from "../browser/player.js";
+/** Default custom-element name registered by {@link defineFlowPlayer}. */
+export declare const FLOW_PLAYER_TAG = "flowsvg-player";
+type ElementBase = typeof HTMLElement;
+declare const HTMLElementBase: ElementBase;
+/** Declarative options; autoplay defaults to false, speed to 1 and controls to true. */
+export interface FlowPlayerElementOptions extends EvaluateOptions {
+    autoplay?: boolean;
+    /** Defaults to false; loop is a live playback preference, independent of GIF loopCount. */
+    loop?: boolean;
+    controls?: boolean;
+    /** Defaults to false. Enable GIF download controls; ignored when controls is false. */
+    gifExport?: boolean;
+    /** Defaults to false; true enables background feedback as well as borders on hover. */
+    hoverFill?: boolean;
+    speed?: number;
+}
+/** Pre-mount errors may lack player state; mounted errors include available state and the Error. */
+export type FlowPlayerElementErrorDetail = Partial<PlayerErrorDetail> & {
+    error: Error;
+};
+/**
+ * Custom-element adapter for attribute conversion, URL requests and playback/error events.
+ * The document property may be assigned before connection; disconnect releases the player/requests but retains the document.
+ * Rendering/timeline behavior delegates to createPlayer; registration requires an explicit defineFlowPlayer call.
+ */
+export declare class FlowPlayerElement extends HTMLElementBase {
+    static readonly observedAttributes: readonly ["document", "src", "autoplay", "controls", "speed", "theme", "reduced-motion", "hover-fill", "gif-export", "loop"];
+    private player;
+    private playerHost;
+    private sourceAbort;
+    private requestToken;
+    private connected;
+    private manuallyDestroyed;
+    private currentDocument;
+    private controlsOverride;
+    private readonly forwardedEvents;
+    /** Current object document; assigning undefined clears it, cancels requests and unmounts the player. */
+    get document(): DiagramDocument | undefined;
+    set document(value: DiagramDocument | undefined);
+    /** Document URL resolved against ownerDocument.baseURI; changes cancel obsolete loads. */
+    get src(): string | undefined;
+    set src(value: string | undefined);
+    /** Whether to autoplay; false pauses a mounted player. */
+    get autoplay(): boolean;
+    set autoplay(value: boolean);
+    /** Live loop mode, reflected by the loop attribute; changes retain time and play state. */
+    get loop(): boolean;
+    set loop(value: boolean);
+    /** Controls default on; an explicit false is retained in HTML as controls="false". */
+    get controls(): boolean;
+    set controls(value: boolean);
+    /** Positive speed multiplier; invalid attribute text reads as 1, while invalid property assignments are ignored. */
+    get speed(): number;
+    set speed(value: number);
+    /** Explicit light/dark theme; the player falls back to the document theme or light when unset. */
+    get theme(): ThemeName | undefined;
+    set theme(value: ThemeName | undefined);
+    /** undefined follows the system preference; true/false explicitly override it via reduced-motion. */
+    get reducedMotion(): boolean | undefined;
+    set reducedMotion(value: boolean | undefined);
+    /** Hover paints only borders by default. The hover-fill attribute enables background and content feedback. */
+    get hoverFill(): boolean;
+    set hoverFill(value: boolean);
+    /** Opt-in GIF controls, reflected by the gif-export attribute; defaults to false. */
+    get gifExport(): boolean;
+    set gifExport(value: boolean);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, value: string | null): void;
+    /** Forward controls to the mounted player; calls are inert when no player is mounted. */
+    play(): void;
+    /** Pause the mounted player, retaining its current frame; do nothing before mounting. */
+    pause(): void;
+    /** Seek in milliseconds using browser-player clamping; do nothing before mounting. */
+    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 the speed property, retaining it for future mounts; ignore non-finite or non-positive values. */
+    setSpeed(value: number): void;
+    /** Set loop mode and retain it for future mounts. */
+    setLoop(value: boolean): void;
+    /** Return undefined before mounting or after destruction. */
+    getState(): PlayerState | undefined;
+    /** Explicitly release the player and requests; the manual-destruction flag resets on the next connection. */
+    destroy(): void;
+    private setDocument;
+    private loadDocumentAttribute;
+    /** AbortController cancels network work; the token also rejects obsolete results already received but not yet applied. */
+    private loadSource;
+    /** Restore an existing playback state during option rebuilds; autoplay applies only to a fresh mount. */
+    private mountPlayer;
+    /** Rebuild for option changes and restore time/playback; document replacement instead follows load's reset-to-zero rule. */
+    private rebuildForOptions;
+    /** Detach forwarding before destruction so teardown cannot forward events from the old instance. */
+    private unmountPlayer;
+    private forwardPlayerEvents;
+    private removeForwardedEvents;
+    private playerOptions;
+    private applyAutoplay;
+    private cancelSourceLoad;
+    private dispatchError;
+}
+/**
+ * Register explicitly; repeated calls for the default name return the existing constructor, or undefined without customElements.
+ * Load the module with a DOM for real registration, since the HTMLElement base is fixed at module evaluation.
+ * @throws {DOMException} From the registry for invalid names or reusing the constructor under another name.
+ */
+export declare function defineFlowPlayer(tagName?: string): CustomElementConstructor | undefined;
+export {};