@wodzik/cubecore 0.1.0

package/render/renderer.d.ts

@@ -0,0 +1,165 @@
+/**
+ * CubeRenderer — a three.js view of a cubecore State.
+ *
+ * - Headless-first: no UI of its own; you drive it (setState / animate /
+ *   showPosition) and style/build controls however you like.
+ * - Renders on demand (nothing is drawn while nothing changes).
+ * - Animation: see layers.ts — colours of the state BEFORE the move, its layer
+ *   rotated by progress × angle.
+ * - Gyroscope-ready: `setOrientation(quaternion)` rotates the whole cube
+ *   (e.g. from a smart cube's gyro), independently of the camera.
+ */
+import { type CenterSpins, type Mask, type Move, type State, type TurnArrow } from "../core/index.js";
+import { type Skin, type Theme } from "../skin/index.js";
+import { type BackView } from "./viewports.js";
+import { type ArrowStyle } from "./arrows.js";
+export interface CameraOptions {
+    /** Degrees above the horizon. */
+    latitude: number;
+    /** Degrees around the vertical axis (0 = looking at F, positive = towards R). */
+    longitude: number;
+    /** Distance from the centre in cubie units, or "auto" to fit the cube (and back stickers) in view. */
+    distance: number | "auto";
+    /** Vertical field of view, degrees. */
+    fov: number;
+}
+export interface RendererOptions {
+    skin?: Skin;
+    /** Page theme the skin is adjusted for (skin.themes). Default "dark". */
+    theme?: Theme;
+    camera?: Partial<CameraOptions>;
+    /** Drag with mouse/touch to orbit the camera. Default true. */
+    dragToRotate?: boolean;
+    /** Quarter-turn animation length in ms. Default 120. */
+    quarterTurnMs?: number;
+    /** Second view from the opposite side showing the hidden faces. Default "none". */
+    backView?: BackView;
+}
+export interface Quat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+export declare class CubeRenderer {
+    private readonly container;
+    readonly canvas: HTMLCanvasElement;
+    private renderer;
+    private scene;
+    private camera;
+    /** Opposite the main camera — sees the three faces the main view hides. */
+    private backCamera;
+    private backView;
+    private size;
+    private root;
+    private cubieGroups;
+    private explode;
+    /** Meshes coloured as the sticker at each facelet position (a built-in tile, or a model's sticker-X meshes). */
+    private paintTargets;
+    /** Tile frame at each facelet position (z = 0 on the cubie face): where decals and features attach. */
+    private anchors;
+    /** Height of the sticker surface above the anchors. */
+    private surface;
+    private hintMeshes;
+    private kit;
+    private attachments;
+    /** Cubie group index holding each facelet position. */
+    private cubieOfFacelet;
+    private materials;
+    /** The skin as shown: the given one with its theme adjustments applied. */
+    private skin;
+    private baseSkin;
+    private theme;
+    private cam;
+    private state;
+    /** Centre spins, tracked through every move so a logo keeps its orientation. */
+    private spins;
+    private mask;
+    private partial;
+    private frameRequested;
+    private resizeObserver;
+    private queue;
+    private active;
+    private quarterMs;
+    private disposed;
+    /** Arrows were shown: the camera keeps room for them (so it doesn't jump each time they come and go). */
+    private arrowRoom;
+    private arrows;
+    private targetOrientation;
+    private orientationSmoothing;
+    constructor(container: HTMLElement, options?: RendererOptions);
+    /**
+     * Show a state immediately (cancels running and queued animations). A
+     * permutation can't say how centres are turned — pass `spins` (see
+     * `spinsAfter`) when a logo's orientation matters; default: all upright.
+     */
+    setState(state: State, spins?: CenterSpins): void;
+    /** Show `state` with `move` part-way (0..1) — for scrubbing / time-accurate replay. */
+    showPartial(state: State, move: Move | null, progress?: number, spins?: CenterSpins): void;
+    /**
+     * Animate a move from the current state. When moves come faster than they
+     * animate (smart cubes do), the running animation snaps to its end and any
+     * backlog is applied instantly — only the newest move animates, so the
+     * picture never lags behind the real cube. Awaiting each call instead plays
+     * an algorithm move by move.
+     */
+    animate(move: Move, ms?: number): Promise<void>;
+    get currentSpins(): CenterSpins;
+    get currentState(): State;
+    setMask(mask: Mask | null): void;
+    setSkin(skin: Skin): void;
+    /** Pull the pieces apart to show their shapes: 0 = assembled, ~0.5 = well apart. */
+    setExplode(amount: number): void;
+    setCamera(camera: Partial<CameraOptions>): void;
+    /** Show the hidden faces in a second view: side by side, as a corner inset, or not at all. */
+    setBackView(mode: BackView): void;
+    /** Light or dark page: applies the skin's theme adjustments (masked greys, back stickers, background). */
+    setTheme(theme: Theme): void;
+    get cameraOptions(): CameraOptions;
+    /**
+     * Orientation of the whole cube, e.g. from a smart cube's gyroscope.
+     * `smoothing` 0..1 eases towards the target each frame (0 = snap).
+     * Pass null to reset.
+     */
+    setOrientation(q: Quat | null, smoothing?: number): void;
+    /**
+     * Arrows for the next turn (core `turnArrow` / a tracker's `nextTurn`): one
+     * around each turning layer, on the side facing the camera — they follow
+     * the gyro and camera drags. Null to hide.
+     */
+    setTurnArrows(arrows: readonly TurnArrow[] | null, style?: ArrowStyle): void;
+    /** The picture as it is now, drawn right away (e.g. a PNG data URL for an <img>). */
+    snapshot(type?: string): string;
+    dispose(): void;
+    private material;
+    private envMap;
+    /** A soft room to reflect (UV-coated stickers), built once. */
+    private reflections;
+    private build;
+    private paint;
+    /** (Re)build the arrows when the side facing the camera changed. */
+    private placeArrows;
+    private applyCamera;
+    /** Distance at which a sphere around the cube (and its back stickers) fits the narrower field of view, with a margin. */
+    private fitDistance;
+    private resize;
+    requestRender(): void;
+    private frame;
+    private step;
+    private draw;
+    private completeActive;
+    private finishAll;
+    private enableDrag;
+}
+/**
+ * Show a replay position: `start` plus the first `applied` moves, with move
+ * `active.index` part-way — plug in `positionAt` / `ReplayClock` from
+ * @cubecore/timeline without this package depending on it.
+ */
+export declare function showPosition(renderer: CubeRenderer, start: State, moves: readonly Move[], position: {
+    applied: number;
+    active?: {
+        index: number;
+        progress: number;
+    };
+}, startSpins?: CenterSpins): void;