@objectifthunes/three-book 0.5.6 → 0.5.7

package/demo-kit/dist/index.d.ts

@@ -0,0 +1,1144 @@
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import * as THREE from 'three';
+
+export declare function addCheckbox(container: HTMLElement, label: string, value: boolean, onChange: (v: boolean) => void): HTMLInputElement;
+
+/**
+ * DOM control builders for the demo panel.
+ * All styling via CSS classes from @objectifthunes/three-book/demo.css.
+ */
+export declare function addCollapseToggle(container: HTMLElement, label: string, initiallyOpen: boolean): {
+    header: HTMLElement;
+    body: HTMLElement;
+};
+
+export declare function addColor(container: HTMLElement, label: string, value: string, onChange: (v: string) => void): HTMLInputElement;
+
+export declare function addSectionTitle(container: HTMLElement, text: string): HTMLElement;
+
+export declare function addSelect(container: HTMLElement, label: string, value: string, options: Array<{
+    value: string;
+    label: string;
+}>, onChange: (v: string) => void): HTMLSelectElement;
+
+export declare function addSlider(container: HTMLElement, label: string, min: number, max: number, step: number, value: number, onChange: (v: number) => void): HTMLInputElement;
+
+declare class AnimationCurve {
+    keys: Keyframe_2[];
+    constructor(keys?: Keyframe_2[]);
+    /**
+     * Evaluate the curve at parameter `t`.
+     * Linear interpolation between keyframes (Unity default is cubic,
+     * but the exact tangent data is not available here).
+     */
+    evaluate(t: number): number;
+}
+
+/**
+ * Defines the direction for auto page turning.
+ */
+declare enum AutoTurnDirection {
+    /** Indicates the next page direction. */
+    Next = 0,
+    /** Indicates the previous page direction. */
+    Back = 1
+}
+
+declare enum AutoTurnMode {
+    /** This mode simulates swiping the paper surface to turn it. */
+    Surface = 0,
+    /** This mode simulates holding the paper edge and turning it. */
+    Edge = 1
+}
+
+/**
+ * Represents an individual setting for auto page turning.
+ *
+ * C# struct — emulated with clone().
+ */
+declare class AutoTurnSetting {
+    private m_Mode;
+    private m_Constant;
+    private m_ConstantMin;
+    private m_ConstantMax;
+    private m_Curve;
+    private m_CurveMin;
+    private m_CurveMax;
+    private m_CurveTimeMode;
+    get mode(): AutoTurnSettingMode;
+    set mode(value: AutoTurnSettingMode);
+    get constant(): number;
+    set constant(value: number);
+    get constantMin(): number;
+    set constantMin(value: number);
+    get constantMax(): number;
+    set constantMax(value: number);
+    get curve(): AnimationCurve | null;
+    set curve(value: AnimationCurve | null);
+    get curveMin(): AnimationCurve | null;
+    set curveMin(value: AnimationCurve | null);
+    get curveMax(): AnimationCurve | null;
+    set curveMax(value: AnimationCurve | null);
+    get curveTimeMode(): AutoTurnSettingCurveTimeMode;
+    set curveTimeMode(value: AutoTurnSettingCurveTimeMode);
+    constructor();
+    /** A constant value. */
+    constructor(constant: number);
+    /** A random value generated between two constant values. */
+    constructor(constantMin: number, constantMax: number);
+    /** A value based on a curve. */
+    static fromCurve(curve: AnimationCurve, curveTimeMode: AutoTurnSettingCurveTimeMode): AutoTurnSetting;
+    /** A random value generated between two curves. */
+    static fromCurveRange(curveMin: AnimationCurve, curveMax: AnimationCurve, curveTimeMode: AutoTurnSettingCurveTimeMode): AutoTurnSetting;
+    /* Excluded from this release type: getValue */
+    /* Excluded from this release type: clampValues */
+    private clampCurve;
+    clone(): AutoTurnSetting;
+}
+
+/**
+ * Defines the curve time mode of AutoTurnSetting when AutoTurnSettingMode is
+ * Curve or RandomBetweenTwoCurves.
+ */
+declare enum AutoTurnSettingCurveTimeMode {
+    /**
+     * Evaluates the curve based on the current paper index divided by the
+     * total paper count. This gives a time value proportional to the
+     * progression through the papers.
+     */
+    PaperIndexTime = 0,
+    /**
+     * Evaluates the curve based on the current turn index divided by the
+     * total turn count. This provides a time value proportional to the
+     * progression through the turns.
+     */
+    TurnIndexTime = 1
+}
+
+/**
+ * Defines the mode of AutoTurnSetting.
+ */
+declare enum AutoTurnSettingMode {
+    /** Specifies a constant value for the auto turn setting. */
+    Constant = 0,
+    /** Specifies a random value generated between two constant values for the auto turn setting. */
+    RandomBetweenTwoConstants = 1,
+    /** Specifies a value based on a curve for the auto turn setting. */
+    Curve = 2,
+    /** Specifies a random value generated between two curves for the auto turn setting. */
+    RandomBetweenTwoCurves = 3
+}
+
+/**
+ * Represents settings for auto page turning.
+ */
+declare class AutoTurnSettings {
+    /* Excluded from this release type: kMinTwist */
+    /* Excluded from this release type: kMaxTwist */
+    /* Excluded from this release type: kMinBend */
+    /* Excluded from this release type: kMaxBend */
+    /* Excluded from this release type: kMinDuration */
+    /* Excluded from this release type: kMaxDuration */
+    private m_Mode;
+    private m_Twist;
+    private m_Bend;
+    private m_Duration;
+    get mode(): AutoTurnMode;
+    set mode(value: AutoTurnMode);
+    get twist(): AutoTurnSetting;
+    set twist(value: AutoTurnSetting);
+    get bend(): AutoTurnSetting;
+    set bend(value: AutoTurnSetting);
+    get duration(): AutoTurnSetting;
+    set duration(value: AutoTurnSetting);
+    /* Excluded from this release type: getModeValue */
+    /* Excluded from this release type: getBendValue */
+    /* Excluded from this release type: getDurationValue */
+    /* Excluded from this release type: getTwistValue */
+}
+
+declare class Book extends THREE.Group implements IBookOwner {
+    private static s_Instances;
+    private static s_InstancesArray;
+    static get instances(): Book[];
+    private m_Content;
+    private m_Binding;
+    private m_InitialOpenProgress;
+    private m_BuildOnAwake;
+    private m_CastShadows;
+    private m_AlignToGround;
+    private m_HideBinder;
+    private m_ReduceShadows;
+    private m_ReduceSubMeshes;
+    private m_ReduceOverdraw;
+    private m_CoverPaperSetup;
+    private m_PagePaperSetup;
+    private m_Root;
+    private m_IsBuilt;
+    private m_HasCover;
+    private m_RendererFactory;
+    private m_MeshFactory;
+    private m_Bound;
+    private m_Papers;
+    private m_SelectedPaper;
+    private m_Direction;
+    private m_AutoTurnQueue;
+    private m_AutoTurnTimer;
+    private m_AutoTurningEndTime;
+    private m_CurrentTime;
+    private m_CoverPaperCount;
+    private m_PagePaperCount;
+    private m_TotalThickness;
+    private m_MinPaperWidth;
+    private m_MinPaperHeight;
+    private m_MinPaperThickness;
+    private m_MaxPaperThickness;
+    private m_RendererIds;
+    private m_WasIdle;
+    private m_ContentDirty;
+    private m_StructuralDirty;
+    private m_AppliedDirection;
+    private _frontPapersCache;
+    get minPaperWidth(): number;
+    get minPaperHeight(): number;
+    get minPaperThickness(): number;
+    get maxPaperThickness(): number;
+    get totalThickness(): number;
+    get hasCover(): boolean;
+    get castShadowsFlag(): boolean;
+    /** Alias matching IBookOwner interface expected by Paper.ts */
+    get castShadows(): boolean;
+    set castShadows(value: boolean);
+    get alignToGround(): boolean;
+    set alignToGround(value: boolean);
+    get hideBinder(): boolean;
+    set hideBinder(value: boolean);
+    get reduceShadows(): boolean;
+    set reduceShadows(value: boolean);
+    get reduceSubMeshes(): boolean;
+    set reduceSubMeshes(value: boolean);
+    get reduceOverdraw(): boolean;
+    set reduceOverdraw(value: boolean);
+    get coverPaperSetup(): PaperSetup;
+    set coverPaperSetup(value: Partial<PaperSetupInit>);
+    get pagePaperSetup(): PaperSetup;
+    set pagePaperSetup(value: Partial<PaperSetupInit>);
+    get bound(): BookBound | null;
+    get papers(): Paper[];
+    get rendererIds(): number[];
+    get direction(): BookDirection;
+    get binding(): BookBinding | null;
+    set binding(value: BookBinding | null);
+    get content(): BookContent | null;
+    set content(value: BookContent | null);
+    get initialOpenProgress(): number;
+    set initialOpenProgress(value: number);
+    get isBuilt(): boolean;
+    get paperCount(): number;
+    get coverPaperCount(): number;
+    get pagePaperCount(): number;
+    get isTurning(): boolean;
+    get isFalling(): boolean;
+    get isIdle(): boolean;
+    get isAutoTurning(): boolean;
+    get hasPendingAutoTurns(): boolean;
+    get autoTurningEndTime(): number;
+    /** Current open progress (0-1), read from actual paper positions. */
+    get openProgress(): number;
+    constructor(options?: BookOptions);
+    startTurning(ray: THREE.Ray): boolean;
+    updateTurning(ray: THREE.Ray): void;
+    stopTurning(): void;
+    getActivePaperSideIndices(indices: Set<number>): void;
+    /**
+     * Sets the book's open progress to a value between 0 (fully closed) and 1 (fully open).
+     * This cancels any pending auto turns and immediately moves all papers to match
+     * the requested progress.
+     */
+    setOpenProgress(openProgress: number): void;
+    setOpenProgressByIndex(paperSideIndex: number): void;
+    /**
+     * Starts auto-turning pages in the given direction.
+     * @param direction - Which direction to turn (Next or Back)
+     * @param settings - Turn animation settings (twist, bend, duration)
+     * @param turnCount - Number of pages to turn
+     * @param delayPerTurn - Delay between consecutive turns (number in seconds, or AutoTurnSetting)
+     * @returns true if at least one turn was queued
+     */
+    startAutoTurning(direction: AutoTurnDirection, settings: AutoTurnSettings, turnCount?: number, delayPerTurn?: number | AutoTurnSetting): boolean;
+    cancelPendingAutoTurns(): void;
+    private processAutoTurnQueue;
+    private getAutoTurnPaper;
+    private getMaxAutoTurnCount;
+    private canAutoTurn;
+    private getAutoTurnPaperIndexTime;
+    /**
+     * Initialize the book. Call this after adding to scene.
+     * Equivalent to Unity's Start/Awake.
+     */
+    init(): void;
+    /**
+     * Call every frame with delta time in seconds.
+     * Equivalent to Unity's LateUpdate.
+     * @param dt - Delta time in seconds since the last frame
+     */
+    update(dt: number): void;
+    /**
+     * Dispose the book and release all resources.
+     * MANDATORY: You must call dispose() when removing a Book to prevent memory leaks.
+     * The Book holds a reference in the static `s_Instances` set; without dispose(),
+     * it will never be garbage collected.
+     */
+    dispose(): void;
+    private build;
+    /**
+     * Clears the built state of the book.
+     * NOTE: This does NOT call super.clear() — it has different semantics from
+     * THREE.Group.clear(). It resets internal book state (papers, bound, flags)
+     * without removing children from the Three.js scene graph.
+     */
+    clear(): this;
+    private hardClear;
+    private createPaperMeshDataPool;
+    private getFrontPapers;
+    getAverageTime(): number;
+    bookRaycast(ray: THREE.Ray): BookRaycastHit | null;
+    /**
+     * Re-apply all page/cover textures from the current BookContent
+     * to existing papers without rebuilding geometry.
+     * Returns false if a structural rebuild is needed (page count changed).
+     */
+    private refreshContent;
+    private getCurrentOpenProgress;
+    private updateLivePages;
+}
+
+declare abstract class BookBinding {
+    abstract createBound(book: Book, root: THREE.Object3D, rendererFactory: RendererFactory, meshFactory: MeshFactory): BookBound;
+}
+
+declare abstract class BookBound {
+    protected m_Book: Book;
+    protected m_Root: THREE.Object3D;
+    /** Discriminant property for runtime type checks (avoids constructor.name). */
+    readonly bindingType: string;
+    abstract get useSharedMeshDataForLowpoly(): boolean;
+    abstract get binderRenderer(): IBinderRenderer;
+    constructor(book: Book, root: THREE.Object3D);
+    abstract createPaperPattern(quality: number, size: THREE.Vector2, thickness: number, uvMargin: PaperUVMargin, reduceOverdraw: boolean, reduceSubMeshes: boolean): PaperPattern;
+    abstract resetPaperPosition(paper: Paper): void;
+    abstract updatePaperPosition(paper: Paper): void;
+    abstract onLateUpdate(): void;
+    /** Release GPU resources. Override in subclasses. */
+    dispose(): void;
+}
+
+/**
+ * Content for the book: covers and pages.
+ *
+ * In Unity, list items can be Sprite, SpritePageContent, or LivePageContent.
+ * In Three.js, list items are either THREE.Texture or IPageContent instances.
+ */
+declare class BookContent {
+    private m_Direction;
+    private m_Covers;
+    private m_Pages;
+    private m_Book;
+    private _cachedCovers;
+    private _cachedPages;
+    private get coverCount4();
+    private get pageCount4();
+    get book(): Book | null;
+    get covers(): (THREE.Texture | IPageContent | null)[];
+    set covers(value: (THREE.Texture | IPageContent | null)[]);
+    get pages(): (THREE.Texture | IPageContent | null)[];
+    set pages(value: (THREE.Texture | IPageContent | null)[]);
+    get isEmpty(): boolean;
+    get direction(): BookDirection;
+    set direction(value: BookDirection);
+    get coverContents(): IPageContent[];
+    get pageContents(): IPageContent[];
+    private getContents;
+    private nextMultipleOf4;
+    private getContent;
+    init(book: Book): void;
+    convertCoverIndexToPaperSideIndex(coverIndex: number): number;
+    convertPageIndexToPaperSideIndex(pageIndex: number): number;
+    convertPaperSideIndexToCoverIndex(paperSideIndex: number): number;
+    convertPaperSideIndexToPageIndex(paperSideIndex: number): number;
+    convertPaperSideIndexToOpenProgress(paperSideIndex: number): number;
+    isCoverPaperSideIndex(paperSideIndex: number): boolean;
+    isPagePaperSideIndex(paperSideIndex: number): boolean;
+}
+
+/**
+ * Ported from BookContent.cs — BookDirection enum.
+ */
+declare enum BookDirection {
+    LeftToRight = 0,
+    RightToLeft = 1,
+    UpToDown = 2,
+    DownToUp = 3
+}
+
+declare interface BookOptions {
+    content?: BookContent;
+    binding?: BookBinding;
+    initialOpenProgress?: number;
+    buildOnAwake?: boolean;
+    castShadows?: boolean;
+    alignToGround?: boolean;
+    hideBinder?: boolean;
+    reduceShadows?: boolean;
+    reduceSubMeshes?: boolean;
+    reduceOverdraw?: boolean;
+    coverPaperSetup?: Partial<PaperSetupInit>;
+    pagePaperSetup?: Partial<PaperSetupInit>;
+}
+
+/**
+ * Wires pointer events on a DOM element to Book's interactive turning API.
+ *
+ * Usage:
+ *   const interaction = new BookPointerInteraction(camera, renderer.domElement);
+ *   interaction.onTurnStart = (book) => { controls.enabled = false; };
+ *   interaction.onTurnEnd   = (book) => { controls.enabled = true;  };
+ *   // Later: interaction.dispose();
+ */
+declare class BookPointerInteraction {
+    /** Set to false to temporarily disable interaction without disposing. */
+    enabled: boolean;
+    onTurnStart?: (book: Book) => void;
+    onTurnEnd?: (book: Book) => void;
+    private readonly m_Camera;
+    private readonly m_DomElement;
+    private readonly m_Raycaster;
+    private readonly m_Mouse;
+    private m_SelectedBook;
+    private m_IsPointerDown;
+    constructor(camera: THREE.Camera, domElement: HTMLElement);
+    dispose(): void;
+    private m_GetRay;
+    private m_OnPointerDown;
+    private m_OnPointerMove;
+    private m_OnPointerUp;
+}
+
+declare interface BookRaycastHit {
+    point: THREE.Vector3;
+    textureCoordinate: THREE.Vector2;
+    pageContent: IPageContent | null;
+    paperIndex: number;
+    pageIndex: number;
+}
+
+declare class BookRenderer implements IPaperRenderer {
+    private m_Object3D;
+    private m_Mesh;
+    private m_Visibility;
+    private m_Id;
+    private m_PropertyBlocks;
+    private m_MaterialTextures;
+    get bounds(): THREE.Box3;
+    get id(): number;
+    get transform(): THREE.Object3D;
+    get visibility(): boolean;
+    get castShadows(): boolean;
+    set castShadows(value: boolean);
+    get mesh(): THREE.BufferGeometry | null;
+    set mesh(value: THREE.BufferGeometry | null);
+    get meshObject(): THREE.Mesh;
+    constructor(root: THREE.Object3D, name: string);
+    setMaterials(materials: THREE.Material | THREE.Material[]): void;
+    setPropertyBlock(properties: PropertyBlock, materialIndex: number): void;
+    reset(name: string): void;
+    clear(): void;
+    destroy(): void;
+    setVisibility(visibility: boolean): void;
+    private getMaterial;
+    private isMapCapable;
+    private isColorCapable;
+    private getSTKey;
+    private applyTextureProperty;
+    private clearMaterialTexture;
+    private clearManagedTexture;
+    private disposeManagedTextures;
+    private disposeCurrentMaterials;
+}
+
+export declare function clearImageSlot(slot: ImageSlot): void;
+
+export declare function createDefaultTextBlock(canvasW: number, canvasH: number): PageTextBlock;
+
+export declare function createDemoInteraction(camera: THREE.PerspectiveCamera, domElement: HTMLElement, controls: OrbitControls, enabled: boolean): BookPointerInteraction;
+
+export declare function createDemoPanel(config: DemoPanelConfig): DemoPanel;
+
+export declare function createDemoScene(): DemoScene;
+
+export declare function createImageSlot(): ImageSlot;
+
+export declare function createImageSlotCard(config: ImageSlotCardConfig): HTMLElement;
+
+export declare function createPageNavigation(config: PageNavConfig): PageNav;
+
+/**
+ * Creates a `THREE.CanvasTexture` suitable for use as a book page.
+ *
+ * Wraps `createPageCanvas` in a THREE.CanvasTexture. If you only need the
+ * canvas (e.g. for TextOverlayContent.source), use `createPageCanvas` instead
+ * to avoid an extra texture allocation.
+ */
+export declare function createPageTexture(color: string, label: string, image: HTMLImageElement | null, fitMode: ImageFitMode, fullBleed: boolean, pageWidth?: number, pageHeight?: number, imageRect?: ImageRect | null): THREE.Texture;
+
+/**
+ * Ported from Book.cs — Cylinder struct (lines ~3805-3902).
+ *
+ * Rolling-deformation core used to curl paper around a cylindrical axis.
+ *
+ * C# value-type (struct) semantics are emulated with a clone() method.
+ *
+ * Unity's `Quaternion.Euler(0, eulerY, z) * Vector3(x, 0, 0)` is replaced
+ * with manual trig: first rotate by Z around the Z-axis, then rotate by Y
+ * around the Y-axis.
+ */
+declare class Cylinder {
+    private m_PositionX;
+    private m_PositionZ;
+    private m_DirectionX;
+    private m_DirectionZ;
+    private m_EulerY;
+    private m_Radius;
+    private readonly _positionOut;
+    private readonly _scratchRP1;
+    private readonly _scratchRP2;
+    private readonly _scratchRollClosest;
+    private readonly _scratchRollEuler;
+    private readonly _scratchOffsetRoll;
+    /** Returns internal vector — do NOT mutate. Copy if you need to store it. */
+    get position(): THREE.Vector3;
+    set position(value: THREE.Vector3);
+    set direction(value: THREE.Vector3);
+    set radius(value: number);
+    rollPoint(point: THREE.Vector3): THREE.Vector3;
+    /**
+     * Apply Quaternion.Euler(0, eulerY, z) * Vector3(x, 0, 0) manually.
+     *
+     * Unity Euler convention (ZXY intrinsic, i.e. applied Z then X then Y):
+     *   1. Rotate (x, 0, 0) by Z degrees around Z-axis.
+     *   2. Rotate by X degrees around X-axis (X = 0 here, so skip).
+     *   3. Rotate by Y degrees around Y-axis.
+     *
+     * Writes result into `out` and returns it.
+     */
+    private eulerRotateVector;
+    /**
+     * Rolls `point` in place around the cylinder. Mutates and returns `point`.
+     * Uses _scratchRollClosest for closest-point calculation and
+     * _scratchRollEuler for euler rotation result.
+     */
+    private roll;
+    /**
+     * Computes offset for `point`. Mutates and returns `point`.
+     * Offset = roll(point with x=0) with z adjusted.
+     * Uses _scratchOffsetRoll to hold a copy for rolling (avoids aliasing
+     * with `point` itself when roll() internally reads and writes).
+     */
+    private getOffset;
+    /**
+     * Projects `point` onto the cylinder axis, writing the result into `point`.
+     * Returns the mutated `point`.
+     */
+    private getClosestPointInto;
+    private getSide;
+    clone(): Cylinder;
+}
+
+export declare interface DemoPanel {
+    root: HTMLElement;
+    toggleBtn: HTMLElement;
+    statusEl: HTMLElement;
+    setStatus(msg: string): void;
+    switchTab(key: string): void;
+}
+
+export declare interface DemoPanelConfig {
+    title: string;
+    subtitle: string;
+    tabs: DemoPanelTab[];
+}
+
+export declare interface DemoPanelTab {
+    key: string;
+    label: string;
+    content: HTMLElement;
+}
+
+export declare interface DemoScene {
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    renderer: THREE.WebGLRenderer;
+    controls: OrbitControls;
+    ambientLight: THREE.AmbientLight;
+    dirLight: THREE.DirectionalLight;
+    syncLights(config: DemoSceneConfig): void;
+}
+
+export declare interface DemoSceneConfig {
+    ambientIntensity: number;
+    sunIntensity: number;
+    sunX: number;
+    sunY: number;
+    sunZ: number;
+}
+
+export declare type DirectionOption = 'left-to-right' | 'right-to-left' | 'up-to-down' | 'down-to-up';
+
+/**
+ * Draws `image` into a 2D canvas context within the rectangle
+ * (x, y, width, height) using the given fit mode.
+ *
+ * - `'fill'`    — stretches to fill exactly, ignoring aspect ratio
+ * - `'contain'` — scales uniformly to fit inside, letterboxed
+ * - `'cover'`   — scales uniformly to fill, cropping the overflow
+ */
+export declare function drawImageWithFit(ctx: CanvasRenderingContext2D, image: HTMLImageElement, x: number, y: number, width: number, height: number, fit: ImageFitMode): void;
+
+export declare const FONT_OPTIONS: string[];
+
+declare interface IBinderRenderer {
+    setVisibility(visible: boolean): void;
+}
+
+declare interface IBookBound {
+    resetPaperPosition(paper: Paper): void;
+    updatePaperPosition(paper: Paper): void;
+}
+
+declare interface IBookOwner {
+    readonly bound: IBookBound | null;
+    readonly castShadows: boolean;
+    readonly reduceShadows: boolean;
+    readonly direction: BookDirection;
+}
+
+/** How an image is scaled to fit a rectangular area. */
+export declare type ImageFitMode = 'contain' | 'cover' | 'fill';
+
+/** Custom image position and size in canvas pixels. */
+export declare interface ImageRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export declare interface ImageSlot {
+    image: HTMLImageElement | null;
+    objectUrl: string | null;
+    useImage: boolean;
+    fitMode: ImageFitMode;
+    fullBleed: boolean;
+    imageRect: ImageRect | null;
+}
+
+export declare interface ImageSlotCardConfig {
+    label: string;
+    slot: ImageSlot;
+    bgColor: string;
+    showFitControls?: boolean;
+    /** Canvas width in pixels for computing imageRect on upload. */
+    canvasWidth?: number;
+    /** Canvas height in pixels for computing imageRect on upload. */
+    canvasHeight?: number;
+    onChanged: () => void;
+}
+
+declare interface IPageContent {
+    readonly texture: THREE.Texture | null;
+    readonly textureST: THREE.Vector4;
+    isPointOverUI(textureCoord: THREE.Vector2): boolean;
+    init(bookContent: BookContent): void;
+    setActive(active: boolean): void;
+}
+
+declare interface IPaperRenderer {
+    readonly transform: THREE.Object3D;
+    mesh: THREE.BufferGeometry | null;
+    castShadows: boolean;
+    setMaterials(materials: THREE.Material[]): void;
+    setPropertyBlock(props: PropertyBlock, materialIndex: number): void;
+    readonly bounds: THREE.Box3;
+}
+
+/**
+ * Minimal replacement for Unity's AnimationCurve.
+ * Stores an array of { time, value } keyframes and evaluates them
+ * with linear interpolation (matches the most common Unity curve
+ * usage; tangent / bezier evaluation is omitted since the C# plugin
+ * only reads curve values via `Evaluate`).
+ */
+declare interface Keyframe_2 {
+    time: number;
+    value: number;
+}
+
+/** Resolved image ready to be passed to createPageTexture. */
+export declare interface LoadedImage {
+    image: HTMLImageElement;
+    /** Object URL created by URL.createObjectURL — revoke when no longer needed. */
+    objectUrl: string;
+}
+
+/**
+ * Loads a `File` into an `HTMLImageElement` and returns both the element
+ * and the object URL it was decoded from.
+ *
+ * The caller is responsible for calling `URL.revokeObjectURL(result.objectUrl)`
+ * when the image is no longer needed.
+ *
+ * Returns `null` if `file` is null/undefined or if decoding fails.
+ */
+export declare function loadImage(file: File | null | undefined): Promise<LoadedImage | null>;
+
+export declare function loadImageFromFile(slot: ImageSlot, file: File | null): Promise<void>;
+
+declare class MeshFactory {
+    private m_UsedMeshs;
+    private m_FreeMeshs;
+    private m_Meshs;
+    get(): THREE.BufferGeometry;
+    recycle(): void;
+    destroy(): void;
+}
+
+export declare interface PageNav {
+    root: HTMLElement;
+    update(config: PageNavConfig): void;
+}
+
+export declare interface PageNavConfig {
+    pageCount: number;
+    currentPage: number;
+    spreadPages: Set<number>;
+    onPageChange: (index: number) => void;
+    onSpreadToggle: (index: number, checked: boolean) => void;
+}
+
+export declare interface PageTextBlock {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: 'normal' | 'bold';
+    fontStyle: 'normal' | 'italic';
+    color: string;
+    textAlign: 'left' | 'center' | 'right';
+}
+
+declare class Paper {
+    private m_Index;
+    private m_Transform;
+    private m_FrontContent;
+    private m_BackContent;
+    private m_UseBackContentForSides;
+    private m_Book;
+    private m_Prev;
+    private m_Next;
+    private m_NoHole;
+    private m_MaterialData;
+    private m_Renderer;
+    private m_Size;
+    private m_Thickness;
+    private m_Stiffness;
+    private m_Margin;
+    private m_IsCover;
+    private m_UVMargin;
+    private m_MeshData;
+    private m_LowpolyMeshData;
+    private m_LowpolyHoleMeshData;
+    private m_HighpolyMeshDataPool;
+    private m_MeshDataType;
+    private m_Cylinder;
+    private m_IsRolling;
+    private m_IsAutoTurning;
+    private m_WorldPlane;
+    private m_StartHandle;
+    private m_CurrentHandle;
+    private m_EndHandle;
+    private m_PrevHandle;
+    private m_HandleOffset;
+    private m_HandleVelocity;
+    private m_HandleVelocities;
+    private m_SubMeshCount;
+    private m_MinTurningRadius;
+    private m_TurningRadius;
+    private m_FallDuration;
+    private m_FallTime;
+    private m_XTime;
+    private m_ZTime;
+    private m_IsTurning;
+    private m_IsFalling;
+    private m_IsFallingLeft;
+    private m_isMeshChanged;
+    sizeXOffset: number;
+    private readonly _ucStartHandle;
+    private readonly _ucCurrentHandle;
+    private readonly _ucHandleDir;
+    private readonly _ucA;
+    private readonly _ucB;
+    private readonly _ucMid;
+    private readonly _ucRollResult;
+    private readonly _ucCylDir;
+    private readonly _utV1;
+    private readonly _utV2;
+    private readonly _utV3;
+    private readonly _utV4;
+    private readonly _chP;
+    private readonly _chA;
+    private readonly _chC;
+    private readonly _chEllipseCenter1;
+    private readonly _chEllipseCenter2;
+    private readonly _chEllipseSize1;
+    private readonly _chEllipseSize2;
+    private readonly _chP2;
+    private readonly _dirResult;
+    private readonly _gdA;
+    private readonly _gdB;
+    private readonly _rlMatrix;
+    private readonly _rlPlane;
+    private readonly _rlTarget;
+    private readonly _rlNormal;
+    private readonly _utTarget;
+    private readonly _ufSmoothTime;
+    private readonly _umFrontST;
+    private readonly _umBackST;
+    private readonly _h2uResult;
+    get isMeshChanged(): boolean;
+    set isMeshChanged(value: boolean);
+    get isCover(): boolean;
+    get index(): number;
+    get transform(): THREE.Object3D;
+    get renderer(): IPaperRenderer;
+    get meshData(): PaperMeshData;
+    get size(): THREE.Vector2;
+    set size(value: THREE.Vector2);
+    get thickness(): number;
+    get margin(): number;
+    get zTime(): number;
+    get direction(): THREE.Vector3;
+    get isTurning(): boolean;
+    get isFalling(): boolean;
+    get isFlipped(): boolean;
+    get isOnRightStack(): boolean;
+    get frontContent(): IPageContent;
+    get backContent(): IPageContent;
+    get currentContent(): IPageContent;
+    private get needHole();
+    set prev(value: Paper | null);
+    set next(value: Paper | null);
+    set noHole(value: boolean);
+    private get isIdle();
+    constructor(isCover: boolean, index: number, book: IBookOwner, renderer: IPaperRenderer);
+    setTime(time: number): void;
+    setMeshData(lowpolyMeshData: PaperMeshData, lowpolyHoleMeshData: PaperMeshData | null, highpolyMeshDataPool: PaperMeshDataPool): void;
+    restState(rightStack: boolean): void;
+    restMesh(): void;
+    setMaterialData(data: PaperMaterialData): void;
+    setPaperSetup(settings: PaperSetup): void;
+    setContentData(frontContent: IPageContent, backContent: IPageContent, useBackContentForSides?: boolean): void;
+    setMinTurningRadius(min: number): void;
+    updateTurningRadius(bend?: number): void;
+    startTurning(ray: THREE.Ray): boolean;
+    stopTurning(): void;
+    /**
+     * Called each frame while the user is dragging.
+     * `dt` replaces Time.deltaTime.
+     */
+    updateTurning(ray: THREE.Ray, dt?: number): void;
+    /**
+     * Called each frame while the page is falling back into place.
+     * `dt` replaces Time.deltaTime.
+     */
+    updateFalling(dt?: number): void;
+    getTextureCoordinate(ray: THREE.Ray): THREE.Vector2;
+    raycast(ray: THREE.Ray): {
+        hit: boolean;
+        hitInfo: BookRaycastHit;
+    };
+    private hit2UV;
+    /**
+     * Internal raycast against the paper plane in local space.
+     * Returns the local-space hit point, or null if no hit / out of bounds.
+     */
+    raycastLocal(ray: THREE.Ray, noBoundsCheck?: boolean): THREE.Vector3 | null;
+    private trySwitchMeshData;
+    private switchMeshData;
+    updateMaterials(): void;
+    updateBaseVertices(): void;
+    updateMesh(): void;
+    getDirection(z: number): THREE.Vector3;
+    updateTime(): void;
+    private findTime;
+    private clampHandle;
+    private updateCylinder;
+    private rollPoint;
+    startAutoTurning(mode: AutoTurnMode, twist: number, bend: number, duration: number): void;
+    get cylinder(): Cylinder;
+}
+
+/**
+ * Rectangle defined by two corner indices (startX/Z, endX/Z) plus flip/left flags.
+ * C# struct — emulated with clone().
+ */
+declare class PaperBorder {
+    startX: number;
+    startZ: number;
+    endX: number;
+    endZ: number;
+    flip: boolean;
+    left: boolean;
+    constructor(startX: number, startZ: number, endX: number, endZ: number, flip: boolean, left?: boolean);
+    clone(): PaperBorder;
+}
+
+declare class PaperMaterialData {
+    private m_Materials1;
+    private m_Materials3;
+    private m_Color;
+    private m_Texture;
+    private m_TextureST;
+    private _cachedPropertyBlock;
+    private _propertyBlockDirty;
+    get materials1(): THREE.Material[];
+    get materials3(): THREE.Material[];
+    get color(): THREE.Color;
+    get texture(): THREE.Texture | null;
+    get textureST(): THREE.Vector4;
+    constructor(paperSetup: PaperSetup);
+    /**
+     * Mirrors Unity's MaterialPropertyBlock: stores color, texture, and textureST.
+     * Paper.ts reads this after calling updatePropertyBlock.
+     *
+     * Returns a cached object — callers must NOT mutate the returned values.
+     */
+    get propertyBlock(): PropertyBlock;
+    updatePropertyBlock(texture: THREE.Texture | null, textureST: THREE.Vector4): void;
+}
+
+declare class PaperMeshData {
+    private m_Geometry;
+    private m_Pattern;
+    private m_BaseVertices;
+    private m_Vertices;
+    private m_Normals;
+    get geometry(): THREE.BufferGeometry;
+    get pattern(): PaperPattern;
+    get baseVertices(): THREE.Vector3[];
+    constructor(geometry: THREE.BufferGeometry, pattern: PaperPattern);
+    /**
+     * Recalculates base vertex positions from the pattern's X/Z arrays
+     * and offset.
+     *
+     * Ported from lines ~2167-2183.
+     */
+    updateBaseVertices(): void;
+    /**
+     * Recomputes all vertex positions and normals.
+     *
+     * Algorithm:
+     * 1. Clear normals for all base vertices.
+     * 2. Interpolate seam positions in X and Z.
+     * 3. Accumulate face normals per quad onto each vertex.
+     * 4. Normalise by dividing by weight and re-normalising.
+     * 5. Interpolate seam normals (with slerp).
+     * 6. Offset front/back by +/- halfThickness along normal.
+     * 7. Update border vertex positions and normals.
+     * 8. Push data into BufferGeometry attributes.
+     *
+     * Ported from lines ~2185-2255.
+     */
+    updateMesh(): void;
+}
+
+declare class PaperMeshDataPool {
+    private m_Stack;
+    private m_MeshFactory;
+    private m_Pattern;
+    private m_SharedData;
+    private m_UseSharedData;
+    constructor(meshFactory: MeshFactory, pattern: PaperPattern, useSharedData?: boolean);
+    get(): PaperMeshData;
+    free(mesh: PaperMeshData): void;
+}
+
+/**
+ * Ported from Book.cs — PaperPattern class (lines ~2265-2290).
+ *
+ * Holds the tessellation layout of a single paper sheet: vertex arrays,
+ * seam information, triangle indices, UV coordinates and border definitions.
+ */
+declare class PaperPattern {
+    baseXArray: number[];
+    baseZArray: number[];
+    baseXOffset: number;
+    baseVertexCount: number;
+    xSeams: PaperSeam[];
+    zSeams: PaperSeam[];
+    xNoneSeamIndexes: number[];
+    borders: PaperBorder[];
+    texcoords: THREE.Vector2[];
+    weights: number[];
+    triangles: number[];
+    frontTriangles: number[];
+    backTriangles: number[];
+    borderTriangles: number[];
+    vertexCount: number;
+    subMeshCount: number;
+    size: THREE.Vector2;
+    thickness: number;
+}
+
+/**
+ * Describes a seam (extra split) in the paper mesh along one axis.
+ * C# struct — emulated with clone().
+ */
+declare class PaperSeam {
+    active: boolean;
+    prevIndex: number;
+    index: number;
+    nextIndex: number;
+    time: number;
+    constructor(prevIndex: number, index: number, nextIndex: number, time: number);
+    clone(): PaperSeam;
+}
+
+/**
+ * Ported from Book.cs — PaperSetup class (lines ~1617-1712).
+ *
+ * Holds the serialised configuration for a single paper sheet: material,
+ * colour, dimensions, stiffness, quality and UV margin.
+ */
+declare class PaperSetup {
+    private static readonly kMinSize;
+    private static readonly kMinThickness;
+    private static readonly kMinQuality;
+    private static readonly kMaxQuality;
+    private m_Material;
+    private m_Color;
+    private m_Width;
+    private m_Height;
+    private m_Thickness;
+    private m_Stiffness;
+    private m_Quality;
+    private m_UVMargin;
+    margin: number;
+    bookDirection: BookDirection;
+    constructor(opts?: {
+        color?: THREE.Color;
+        width?: number;
+        height?: number;
+        thickness?: number;
+        stiffness?: number;
+        quality?: number;
+        material?: THREE.Material | null;
+    });
+    get material(): THREE.Material | null;
+    set material(value: THREE.Material | null);
+    get color(): THREE.Color;
+    set color(value: THREE.Color);
+    get width(): number;
+    set width(value: number);
+    get height(): number;
+    set height(value: number);
+    get thickness(): number;
+    set thickness(value: number);
+    get stiffness(): number;
+    set stiffness(value: number);
+    get quality(): number;
+    set quality(value: number);
+    get uvMargin(): PaperUVMargin;
+    set uvMargin(value: PaperUVMargin);
+    get size(): THREE.Vector2;
+}
+
+declare interface PaperSetupInit {
+    color: THREE.Color;
+    width: number;
+    height: number;
+    thickness: number;
+    stiffness: number;
+    material: THREE.Material | null;
+}
+
+/**
+ * Ported from Book.cs — PaperUVMargin struct (lines ~1714-1796).
+ *
+ * Defines the blank space around content on each of the four sides.
+ * C# struct — emulated with clone().
+ */
+declare class PaperUVMargin {
+    /* Excluded from this release type: kMin */
+    /* Excluded from this release type: kMax */
+    private m_Left;
+    private m_Right;
+    private m_Down;
+    private m_Up;
+    get left(): number;
+    set left(value: number);
+    get right(): number;
+    set right(value: number);
+    get down(): number;
+    set down(value: number);
+    get up(): number;
+    set up(value: number);
+    private clamp;
+    /**
+     * Returns a new PaperUVMargin with margins remapped according to the
+     * book direction.
+     */
+    transform(direction: BookDirection): PaperUVMargin;
+    /**
+     * Remap a UV coordinate so that (0,0) and (1,1) correspond to the
+     * content area inside the margins.
+     *
+     * Unity's `Mathf.InverseLerp(a, b, v)` = `(v - a) / (b - a)` clamped to [0,1].
+     */
+    fixUV(uv: THREE.Vector2): THREE.Vector2;
+    private static inverseLerp;
+    clone(): PaperUVMargin;
+}
+
+declare interface PropertyBlock {
+    color: THREE.Color;
+    map: THREE.Texture | null;
+    textureST: THREE.Vector4;
+}
+
+/** Pixels per world unit — used to compute canvas size from page dimensions. */
+export declare const PX_PER_UNIT = 256;
+
+declare class RendererFactory {
+    private m_Root;
+    private m_UsedRenderers;
+    private m_FreeRenderers;
+    private m_Renderers;
+    private m_Ids;
+    get ids(): number[];
+    constructor(root: THREE.Object3D);
+    get(name: string): BookRenderer;
+    recycle(): void;
+    destroy(): void;
+    getBounds(): THREE.Box3;
+}
+
+export declare function resolvePageIndex(currentPage: number, spreadPages: Set<number>, pageCount: number): {
+    effectiveIdx: number;
+    isSpread: boolean;
+};
+
+export declare function toBookDirection(direction: DirectionOption): BookDirection;
+
+export { }