@wodzik/cubecore 0.1.0

package/element/player.d.ts

@@ -0,0 +1,196 @@
+/**
+ * <cube-player> — a cube that plays an algorithm or a recorded solve, with
+ * optional controls and progress bar. Three levels of customisation:
+ *
+ *   1. use it as is:           <cube-player alg="R U R' U'" progress></cube-player>
+ *   2. restyle it:             CSS variables (--cc-accent…) and ::part(button-play)… — see styles.ts
+ *   3. bring your own controls: <cube-player controls="none"> or a child with slot="controls",
+ *                               driven by play() / pause() / seek() / stepForward()… and events.
+ *
+ * Attributes: alg, setup, anchor ("start": play the algorithm from the
+ * (set-up) cube — default; "end": the algorithm SOLVES it, so the cube
+ * starts at setup + inverse of the algorithm), tempo (moves per second,
+ * default 2), skin (preset name), theme ("light" | "dark" | "auto" — the
+ * skin's adjustments for the page; auto follows the system), back-view, visualization ("3d" | "net" |
+ * "top" — the 2D views are SVG pictures from @cubecore/image), controls
+ * ("default" | "none"), max-pause (ms: recorded pauses longer than this are
+ * shortened in the replay), progress (show the bar), markers (ticks at section
+ * ends), segment-labels (section names under the bar — click one to jump to
+ * it), tooltips ("off" to hide the section popup).
+ *
+ * Sections: `segments` (any [{ start, end, label, id?, detail?, split?,
+ * moves?, color? }] — see @cubecore/timeline Segment), or `method`, which
+ * computes them from the recording (stageSegments: any Method, colour
+ * neutral). The bar colours each section (palette --cc-segment-1…8 or the
+ * segment's colour), hatches the recognition part (before `split`), and
+ * shows a popup over the section under the pointer / at the playhead
+ * (`formatSegment` for your own text). PageUp / PageDown jump between sections.
+ * Properties: recording (a timed solve — plays in real time), alg, setup,
+ * skin, mask, method (sections from it), segments, formatSegment, markers, speeds, rate,
+ * currentTime, duration, playing, renderer.
+ * Events: timeupdate {time, duration, applied}, play, pause, ended,
+ * error {message} (e.g. an algorithm that doesn't parse — the cube then shows the setup),
+ * segmentchange {index, segment} (the playhead entered another section),
+ * load (what plays changed — alg, setup, recording…).
+ *
+ * Live: `attach(session)` follows a smart cube (a @cubecore/bluetooth
+ * SmartCubeSession, or anything with the same events) — its moves animate,
+ * resyncs jump, the gyro turns the cube; replay controls hide (`live`
+ * attribute). `detach()` goes back to playback.
+ */
+/** What `attach` needs — SmartCubeSession fits; so does anything shaped like it. */
+export interface LiveSource {
+    readonly state: State;
+    /** A skin for this cube (SmartCubeSession has one); used with attach(…, { autoSkin: true }). */
+    readonly suggestedSkin?: Skin;
+    on(type: "move", listener: (e: {
+        move: Move;
+    }) => void): () => void;
+    on(type: "state", listener: (e: {
+        state: State;
+        reason: string;
+    }) => void): () => void;
+    on(type: "orientation", listener: (q: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    }) => void): () => void;
+}
+import { type Mask, type Method, type Move, type State, type TurnArrow } from "../core/index.js";
+import { type ArrowStyle, CubeRenderer } from "../render/index.js";
+import { type Skin } from "../skin/index.js";
+import { type Recording, type Segment } from "../timeline/index.js";
+import { type Marker } from "./model.js";
+import { ElementBase } from "./base.js";
+export declare class CubePlayer extends ElementBase {
+    static observedAttributes: string[];
+    private readonly darkQuery;
+    private readonly onScheme;
+    private readonly root;
+    private _renderer;
+    private connected;
+    /** The smart cube followed (attach), if any. */
+    private liveSource;
+    private turnArrows;
+    private clock;
+    private unsubscribe;
+    private rec;
+    private start;
+    private startMoves;
+    private _recording;
+    private _skin;
+    private _mask;
+    private _method;
+    private _markers;
+    private _segments;
+    private segs;
+    private currentSegment;
+    private tooltipHide;
+    /** Tooltip text of a section (default: label · detail · time (recognition · execution) · moves). */
+    formatSegment: (s: Segment) => string;
+    private _speeds;
+    private _rate;
+    private _setupState;
+    private liveOff;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * The WebGL renderer exists only while the 3D view is shown: a page with
+     * many 2D pictures (case lists) must not use up the browser's WebGL
+     * contexts (~16 — past that the oldest canvas goes blank).
+     */
+    private syncRenderer;
+    attributeChangedCallback(name: string): void;
+    /** A timed solve: plays in real time (pauses stay pauses). Takes precedence over `alg`. */
+    get recording(): Recording | null;
+    set recording(r: Recording | null);
+    get alg(): string;
+    set alg(v: string);
+    /** Moves (or a state) that set the cube up before it plays. */
+    get setup(): string;
+    set setup(v: string | State);
+    get skin(): Skin;
+    set skin(s: Skin | string);
+    get mask(): Mask | null;
+    set mask(m: Mask | null);
+    /** Sections come from this method's analysis of the recording (colour neutral), unless `segments` are given. */
+    get method(): Method | null;
+    set method(m: Method | null);
+    /** Explicit sections of the bar (override `method`). */
+    get segments(): Segment[];
+    set segments(s: Segment[] | null);
+    /** Explicit tick marks (default: the ends of the sections). */
+    get markers(): Marker[] | null;
+    set markers(m: Marker[] | null);
+    /** Speeds the speed button cycles through. */
+    get speeds(): number[];
+    set speeds(v: number[]);
+    /** The underlying renderer, for anything the element doesn't expose. */
+    get renderer(): CubeRenderer | null;
+    get playing(): boolean;
+    get currentTime(): number;
+    get duration(): number;
+    get rate(): number;
+    set rate(r: number);
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    seek(ms: number): void;
+    /** Jump to the moment `k` moves are done (0 = the start). */
+    seekToMove(k: number): void;
+    /** Moves done at the current time. */
+    get applied(): number;
+    /** The moves being played (the algorithm, or the recording's moves). */
+    get moves(): Move[];
+    stepForward(): void;
+    stepBack(): void;
+    toStart(): void;
+    toEnd(): void;
+    /** Follow a smart cube: its moves animate, resyncs jump, its gyro turns the cube. Returns detach. */
+    attach(source: LiveSource, options?: {
+        gyro?: boolean;
+        gyroSmoothing?: number;
+        autoSkin?: boolean;
+    }): () => void;
+    /** Stop following a live cube and go back to playback. */
+    detach(): void;
+    /**
+     * Arrows for the next turn on the 3D cube (a tracker's `nextTurn().arrows`).
+     * `owner` (e.g. the <cube-scramble> setting them): clearing with null only
+     * works for the one that set them last, so two elements can share a player.
+     */
+    showTurnArrows(arrows: readonly TurnArrow[] | null, style?: ArrowStyle, owner?: unknown): void;
+    /** Animate one move now (live input without a session). */
+    pushMove(move: Move | string): void;
+    private $;
+    private resolveSkin;
+    private load;
+    private lastPos;
+    /** Play / pause icon currently shown (null: not drawn yet). */
+    private shownPlaying;
+    private onTime;
+    /** "light" / "dark" from the theme attribute; "auto" (default) follows the system setting. */
+    private resolvedTheme;
+    private applyTheme;
+    /** 2D visualizations: an SVG of the position (moves applied so far) with the same skin and mask. */
+    private redraw;
+    private updateUi;
+    private renderSections;
+    private updateSections;
+    /** Show the popup of section `index` (−1 hides it). */
+    private showTooltip;
+    /** Start of the next (+1) / this-or-previous (−1) section. */
+    private jumpSection;
+    private onClick;
+    private onKey;
+    private wireProgress;
+}
+/** Register the element (idempotent). */
+export declare function defineCubePlayer(tag?: string): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        "cube-player": CubePlayer;
+    }
+}