@objectifthunes/react-three-book 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1266 @@
+import { Context } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
+import * as THREE from 'three';
+
+export 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;
+}
+
+export declare interface AutoTurnControls {
+    /** Turn one page forward. */
+    turnNext: (settings?: AutoTurnSettings) => boolean;
+    /** Turn one page backward. */
+    turnPrev: (settings?: AutoTurnSettings) => boolean;
+    /** Turn all remaining pages in the given direction. */
+    turnAll: (direction: AutoTurnDirection, settings?: AutoTurnSettings) => boolean;
+    /** Full control: queue `turnCount` auto-turns in one call. */
+    startAutoTurning: (direction: AutoTurnDirection, settings?: AutoTurnSettings, turnCount?: number, delayPerTurn?: number | AutoTurnSetting) => boolean;
+    /** Remove queued turns that haven't started yet. */
+    cancelPendingAutoTurns: () => void;
+}
+
+/**
+ * Ported from Book.cs — AutoTurn enums, settings, and value types (lines ~1076-1418).
+ *
+ * Faithful line-by-line port of:
+ *   - AutoTurnDirection enum
+ *   - AutoTurnMode enum
+ *   - AutoTurnSettings class
+ *   - AutoTurnSetting struct (→ class with clone())
+ *   - AutoTurnSettingMode enum
+ *   - AutoTurnSettingCurveTimeMode enum
+ *
+ * Unity `AnimationCurve` is approximated by a simple keyframe array
+ * with linear interpolation (evaluate).
+ */
+/**
+ * Defines the direction for auto page turning.
+ */
+export declare enum AutoTurnDirection {
+    /** Indicates the next page direction. */
+    Next = 0,
+    /** Indicates the previous page direction. */
+    Back = 1
+}
+
+/**
+ * Defines the mode for auto page turning.
+ */
+export 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
+}
+
+/** Mirrors C# AutoTurnMode enum */
+declare enum AutoTurnMode_2 {
+    Surface = 0,
+    Edge = 1
+}
+
+/**
+ * Represents an individual setting for auto page turning.
+ *
+ * C# struct — emulated with clone().
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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 */
+}
+
+/**
+ * R3F component that manages the complete lifecycle of a ThreeBook.
+ * Forward-refs to the underlying `ThreeBook` instance.
+ */
+export declare const Book: ForwardRefExoticComponent<BookProps & RefAttributes<ThreeBook>>;
+
+export declare abstract class BookBinding {
+    abstract createBound(book: ThreeBook, root: THREE.Object3D, rendererFactory: RendererFactory, meshFactory: MeshFactory): BookBound;
+}
+
+export declare abstract class BookBound {
+    protected m_Book: ThreeBook;
+    protected m_Root: THREE.Object3D;
+    abstract get useSharedMeshDataForLowpoly(): boolean;
+    abstract get binderRenderer(): BookRenderer;
+    constructor(book: ThreeBook, 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;
+}
+
+/**
+ * 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.
+ */
+export declare class BookContent {
+    private m_Direction;
+    private m_Covers;
+    private m_Pages;
+    private m_Book;
+    private get coverCount4();
+    private get pageCount4();
+    get book(): ThreeBook | null;
+    get covers(): (THREE.Texture | IPageContent | null)[];
+    get pages(): (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: ThreeBook): 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;
+}
+
+export declare const BookContext: Context<ThreeBook | null>;
+
+export declare interface BookControls {
+    /** Jump to open progress 0–1 (0 = closed, 1 = fully open). */
+    setOpenProgress: (progress: number) => void;
+    /** Jump to a specific paper-side index. */
+    setOpenProgressByIndex: (index: number) => void;
+    /** Cancel any in-progress interactive drag turn. */
+    stopTurning: () => void;
+}
+
+/**
+ * Ported from BookContent.cs — BookDirection enum.
+ */
+export declare enum BookDirection {
+    LeftToRight = 0,
+    RightToLeft = 1,
+    UpToDown = 2,
+    DownToUp = 3
+}
+
+export declare class BookHeightException extends Error {
+    constructor();
+}
+
+/**
+ * Wires pointer-drag events for interactive page turning. Renders nothing.
+ *
+ * Place inside `<Book>` to pick up the book automatically:
+ *   <Book ...><BookInteraction orbitControlsRef={orbitRef} /></Book>
+ *
+ * Or pass an explicit ref when used outside a `<Book>` tree:
+ *   <BookInteraction bookRef={bookRef} orbitControlsRef={orbitRef} />
+ */
+export declare function BookInteraction({ bookRef: externalRef, enabled, orbitControlsRef }: BookInteractionProps): null;
+
+export declare interface BookInteractionProps {
+    /** Explicit book ref. If omitted, the nearest `<Book>` context is used. */
+    bookRef?: React.RefObject<ThreeBook | null>;
+    /** Disable turning without unmounting. Default: true. */
+    enabled?: boolean;
+    /** OrbitControls ref — disabled during drag, re-enabled on release. */
+    orbitControlsRef?: React.RefObject<{
+        enabled: boolean;
+    } | null>;
+}
+
+export declare interface BookOptions {
+    content?: BookContent;
+    binding?: BookBinding;
+    initialOpenProgress?: number;
+    buildOnAwake?: boolean;
+    castShadows?: boolean;
+    alignToGround?: boolean;
+    hideBinder?: boolean;
+    createColliders?: boolean;
+    reduceShadows?: boolean;
+    reduceSubMeshes?: boolean;
+    reduceOverdraw?: boolean;
+    coverPaperSetup?: Partial<PaperSetupInit>;
+    pagePaperSetup?: Partial<PaperSetupInit>;
+}
+
+export declare interface BookProps extends BookOptions {
+    /** Called after `book.init()` succeeds. */
+    onBuilt?: (book: ThreeBook) => void;
+    /**
+     * Called if `book.init()` throws (e.g. BookHeightException when the stack
+     * is too tall for the given page dimensions).
+     */
+    onError?: (err: Error) => void;
+    /**
+     * Children are rendered inside the BookContext so they can call
+     * `useBook()`, `useBookControls()`, `useAutoTurn()`, etc. without a ref.
+     *
+     * Example: <BookInteraction> placed here automatically discovers the book.
+     */
+    children?: ReactNode;
+}
+
+export declare interface BookRaycastHit {
+    point: THREE.Vector3;
+    textureCoordinate: THREE.Vector2;
+    pageContent: IPageContent | null;
+    paperIndex: number;
+    pageIndex: number;
+}
+
+/** Mirrors C# BookRaycastHit struct */
+declare interface BookRaycastHit_2 {
+    point: THREE.Vector3;
+    textureCoordinate: THREE.Vector2;
+    pageContent: IPageContent_2 | null;
+    paperIndex: number;
+    pageIndex: number;
+}
+
+export declare class BookRenderer {
+    private m_Object3D;
+    private m_Mesh;
+    private m_Visibility;
+    private m_CreateCollider;
+    private m_Id;
+    private m_PropertyBlocks;
+    private m_MaterialTextures;
+    get createCollider(): boolean;
+    set createCollider(value: boolean);
+    get bounds(): THREE.Box3;
+    get id(): number;
+    get transform(): THREE.Object3D;
+    get visibility(): boolean;
+    set castShadows(value: boolean);
+    set mesh(value: THREE.BufferGeometry | null);
+    get meshObject(): THREE.Mesh;
+    constructor(root: THREE.Object3D, name: string, createCollider: boolean);
+    setMaterials(materials: THREE.Material | THREE.Material[]): void;
+    setPropertyBlock(properties: Record<string, unknown>, materialIndex: number): void;
+    reset(name: string): void;
+    clear(): void;
+    destroy(): void;
+    setVisibility(visibility: boolean): void;
+    updateCollider(): void;
+    private getMaterial;
+    private isMapCapable;
+    private isColorCapable;
+    private getSTKey;
+    private applyTextureProperty;
+    private clearMaterialTexture;
+    private clearManagedTexture;
+    private disposeManagedTextures;
+    private disposeCurrentMaterials;
+}
+
+export declare interface BookState {
+    /** True once `book.init()` has been called successfully. */
+    isBuilt: boolean;
+    /** True while the user is dragging a page. */
+    isTurning: boolean;
+    /** True while any page is in its falling/settling animation. */
+    isFalling: boolean;
+    /** True when no turning, falling, or auto-turning is happening. */
+    isIdle: boolean;
+    /** True while an auto-turn is currently playing. */
+    isAutoTurning: boolean;
+    /** True while there are queued auto-turns waiting to start. */
+    hasPendingAutoTurns: boolean;
+    /** Total number of papers (covers + pages). */
+    paperCount: number;
+    /** Number of cover papers (2 physical sheets = 4 surfaces). */
+    coverPaperCount: number;
+    /** Number of interior page papers. */
+    pagePaperCount: number;
+}
+
+/**
+ * Creates a 512×512 `THREE.CanvasTexture` suitable for use as a book page.
+ *
+ * - Fills the background with `color`.
+ * - If `image` is provided, draws it using `fitMode` and `fullBleed`.
+ * - Otherwise, renders `label` as centred text (useful for debugging).
+ */
+export declare function createPageTexture(color: string, label: string, image: HTMLImageElement | null, fitMode: ImageFitMode, fullBleed: boolean): 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.
+ */
+export declare class Cylinder {
+    private m_PositionX;
+    private m_PositionZ;
+    private m_DirectionX;
+    private m_DirectionZ;
+    private m_EulerY;
+    private m_Radius;
+    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.
+     */
+    private eulerRotateVector;
+    private roll;
+    private getOffset;
+    private getClosestPoint;
+    private getSide;
+    clone(): Cylinder;
+}
+
+/**
+ * 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;
+
+/** Minimal Book interface consumed by the binding. */
+declare interface IBook {
+    readonly totalThickness: number;
+    readonly minPaperWidth: number;
+    readonly minPaperHeight: number;
+    readonly maxPaperThickness: number;
+    readonly minPaperThickness: number;
+    readonly papers: IPaper[];
+    readonly hasCover: boolean;
+    readonly coverPaperCount: number;
+    readonly alignToGround: boolean;
+    readonly castShadows: boolean;
+    readonly direction: number;
+    readonly coverPaperSetup: {
+        thickness: number;
+        margin: number;
+    };
+    readonly pagePaperSetup: {
+        margin: number;
+    };
+}
+
+/** Minimal interface for BookBound as used by Paper */
+declare interface IBookBound {
+    resetPaperPosition(paper: Paper): void;
+    updatePaperPosition(paper: Paper): void;
+}
+
+/**
+ * Minimal interface the Paper class expects from the Book owner.
+ * Keeps the file self-contained without importing the full Book class.
+ */
+declare interface IBookOwner {
+    bound: IBookBound;
+    castShadows: boolean;
+    reduceShadows: boolean;
+    direction: BookDirection;
+}
+
+/** How an image is scaled to fit a rectangular area. */
+export declare type ImageFitMode = 'contain' | 'cover' | 'fill';
+
+export 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;
+}
+
+/** Mirrors C# IPageContent */
+declare interface IPageContent_2 {
+    texture: THREE.Texture | null;
+    textureST: THREE.Vector4;
+    isPointOverUI(textureCoord: THREE.Vector2): boolean;
+    init(bookContent: unknown): void;
+    setActive(active: boolean): void;
+}
+
+/** Minimal Paper interface consumed by the binding. */
+declare interface IPaper {
+    readonly index: number;
+    thickness: number;
+    size: THREE.Vector2;
+    sizeXOffset: number;
+    readonly margin: number;
+    readonly zTime: number;
+    readonly isFlipped: boolean;
+    readonly isTurning: boolean;
+    readonly isFalling: boolean;
+    readonly transform: THREE.Object3D;
+    readonly meshData: {
+        readonly pattern: {
+            baseXArray: number[];
+            baseZArray: number[];
+            xNoneSeamIndexes: number[];
+        };
+        baseVertices: THREE.Vector3[];
+    };
+    setMinTurningRadius(radius: number): void;
+    updateTurningRadius(): void;
+    updateTime(): void;
+    updateMesh(): void;
+    getDirection(z: number): THREE.Vector3;
+}
+
+/**
+ * Minimal wrapper mirroring the C# Renderer helper class used by Paper.
+ * In Three.js this maps to THREE.Mesh + THREE.Object3D.
+ */
+declare interface IPaperRenderer {
+    readonly transform: THREE.Object3D;
+    mesh: THREE.BufferGeometry | null;
+    castShadows: boolean;
+    setMaterials(materials: THREE.Material[]): void;
+    setPropertyBlock(props: Record<string, unknown>, 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;
+}
+export { Keyframe_2 as Keyframe }
+
+/** 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 class MeshFactory {
+    private m_UsedMeshs;
+    private m_FreeMeshs;
+    private m_Meshs;
+    get(): THREE.BufferGeometry;
+    recycle(): void;
+    destroy(): void;
+}
+
+export declare abstract class PageContent implements IPageContent {
+    private m_BookContent;
+    private m_IsActive;
+    get bookContent(): BookContent | null;
+    get isActive(): boolean;
+    abstract get texture(): THREE.Texture | null;
+    get textureST(): THREE.Vector4;
+    get isShareable(): boolean;
+    onActiveChangedCallback: (() => void) | null;
+    protected onInit(): void;
+    protected onActiveChanged(): void;
+    protected onIsPointOverUI(_textureCoord: THREE.Vector2): boolean;
+    isPointOverUI(textureCoord: THREE.Vector2): boolean;
+    init(bookContent: BookContent): void;
+    setActive(active: boolean): void;
+}
+
+export 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;
+    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_2;
+    get backContent(): IPageContent_2;
+    get currentContent(): IPageContent_2;
+    private get needHole();
+    set prev(value: Paper | null);
+    set next(value: Paper | null);
+    set noHole(value: boolean);
+    private get isIdle();
+    get isInMiddelOfStack(): boolean;
+    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_2, backContent: IPageContent_2, 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_2;
+    };
+    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;
+    drawWireframe(_color: unknown): void;
+    startAutoTurning(mode: AutoTurnMode_2, 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().
+ */
+export 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;
+}
+
+export declare class PaperMaterialData {
+    private m_Materials1;
+    private m_Materials3;
+    private m_Color;
+    private m_Texture;
+    private m_TextureST;
+    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.
+     */
+    get propertyBlock(): Record<string, unknown>;
+    updatePropertyBlock(texture: THREE.Texture | null, textureST: THREE.Vector4): void;
+}
+
+export 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;
+    /**
+     * Returns wireframe quad data for debug visualisation.
+     *
+     * Ported from lines ~2257-2262.
+     */
+    drawWireframe(matrix: THREE.Matrix4): Array<[THREE.Vector3, THREE.Vector3, THREE.Vector3, THREE.Vector3]>;
+}
+
+export 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 — PaperNode class (lines ~2292-2430).
+ *
+ * Doubly-linked-list node used during paper mesh tessellation.
+ * Each node stores a 1-D position `value` along an axis, plus flags
+ * that mark whether it sits on a hole or a seam.
+ */
+export declare class PaperNode {
+    prev: PaperNode | null;
+    next: PaperNode | null;
+    value: number;
+    index: number;
+    hole: boolean;
+    seam: boolean;
+    constructor(value: number, hole?: boolean, seam?: boolean);
+    get prevNoneSeam(): PaperNode;
+    get nextNoneSeam(): PaperNode;
+    get prevNoneHole(): PaperNode;
+    get nextNoneHole(): PaperNode;
+    createNext(value: number, hole?: boolean, seam?: boolean): PaperNode;
+    createNextFromDouble(value: number, hole?: boolean, seam?: boolean): PaperNode;
+    insert(node: PaperNode): boolean;
+    updateIndex(index: number): void;
+    getValues(): number[];
+    getValues(values: number[]): void;
+    private _getValuesRecursive;
+    getHoles(): boolean[];
+    getHoles(holes: boolean[]): void;
+    private _getHolesRecursive;
+}
+
+/**
+ * Creates four seam nodes (left, right, down, up) from a UV margin and
+ * inserts them into the existing X / Z linked-lists.
+ */
+export declare class PaperNodeMargin {
+    leftNode: PaperNode;
+    rightNode: PaperNode;
+    downNode: PaperNode;
+    upNode: PaperNode;
+    constructor(pattern: PaperPattern, margin: PaperUVMargin, hole: boolean);
+    insert(xRootNode: PaperNode, zRootNode: PaperNode, xSeamNodes: PaperNode[], zSeamNodes: PaperNode[]): 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.
+ */
+export 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().
+ */
+export 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.
+ */
+export 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;
+}
+
+export 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().
+ */
+export 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;
+}
+
+export declare class RendererFactory {
+    private m_Root;
+    private m_CreateMeshCollider;
+    private m_UsedRenderers;
+    private m_FreeRenderers;
+    private m_Renderers;
+    private m_Ids;
+    set createColliders(value: boolean);
+    get ids(): number[];
+    constructor(root: THREE.Object3D);
+    get(name: string): BookRenderer;
+    recycle(): void;
+    destroy(): void;
+    getBounds(): THREE.Box3;
+}
+
+export declare class SpritePageContent2 implements IPageContent {
+    private m_Texture;
+    private m_TextureST;
+    constructor(texture: THREE.Texture | null, textureST?: THREE.Vector4);
+    get texture(): THREE.Texture | null;
+    get textureST(): THREE.Vector4;
+    isPointOverUI(_textureCoord: THREE.Vector2): boolean;
+    init(_bookContent: BookContent): void;
+    setActive(_active: boolean): void;
+}
+
+export declare class StapleBookBinding extends BookBinding {
+    quality: number;
+    stapleSetup: StapleSetup;
+    createBound(book: ThreeBook, root: THREE.Object3D, _rendererFactory: RendererFactory, _meshFactory: MeshFactory): BookBound;
+}
+
+export declare class StapleBookBound {
+    private m_Book;
+    private m_Root;
+    /** The Three.js Mesh for the staple geometry. */
+    stapleMesh: THREE.Mesh;
+    private m_StapleMargin;
+    private m_StapleThickness;
+    private m_BindingRadius;
+    private m_BindingMidSpace;
+    private m_StackHeight;
+    private m_BindingVertexCount;
+    private m_Quality;
+    /** C#: `useSharedMeshDataForLowpoly => false` */
+    readonly useSharedMeshDataForLowpoly: boolean;
+    /** Adapter that wraps the THREE.Mesh in a BookRenderer-compatible shape. */
+    private _binderRendererAdapter;
+    get binderRenderer(): StapleRendererAdapter;
+    constructor(quality: number, stapleSetup: StapleSetup, book: IBook, root: THREE.Object3D, stapleMaterial?: THREE.Material);
+    private updateStapleMesh;
+    createPaperPattern(quality: number, size: THREE.Vector2, thickness: number, uvMargin: PaperUVMargin, reduceOverdraw: boolean, reduceSubMeshes: boolean): PaperPattern;
+    private updateRootPosition;
+    resetPaperPosition(paper: IPaper): void;
+    private getPX;
+    updatePaperPosition(paper: IPaper): void;
+    private getStackHeight;
+    private getStackZ;
+    onLateUpdate(): void;
+    private updateBindingVertices;
+    get bindingRadius(): number;
+    get bindingMidSpace(): number;
+    get stackHeight(): number;
+    get bindingVertexCount(): number;
+    get quality(): number;
+    get stapleMargin(): number;
+    get stapleThickness(): number;
+}
+
+declare class StapleRendererAdapter {
+    private mesh;
+    constructor(mesh: THREE.Mesh);
+    setVisibility(visible: boolean): void;
+    updateCollider(): void;
+    get castShadows(): boolean;
+    set castShadows(value: boolean);
+    get bounds(): THREE.Box3;
+    get transform(): THREE.Object3D;
+    get meshObject(): THREE.Mesh;
+}
+
+export declare class StapleSetup {
+    private _material;
+    private _color;
+    private _thickness;
+    private _crown;
+    private _margin;
+    private _count;
+    private _quality;
+    get material(): THREE.Material | null;
+    set material(value: THREE.Material | null);
+    get color(): THREE.Color;
+    set color(value: THREE.Color);
+    get thickness(): number;
+    set thickness(value: number);
+    get margin(): number;
+    set margin(value: number);
+    get crown(): number;
+    set crown(value: number);
+    get count(): number;
+    set count(value: number);
+    get quality(): number;
+    set quality(value: number);
+}
+
+export declare class ThreeBook extends THREE.Group {
+    private static s_Instances;
+    static get instances(): ThreeBook[];
+    private m_Content;
+    private m_Binding;
+    private m_InitialOpenProgress;
+    private m_BuildOnAwake;
+    private m_CastShadows;
+    private m_AlignToGround;
+    private m_HideBinder;
+    private m_CreateColliders;
+    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;
+    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;
+    get alignToGround(): boolean;
+    get reduceShadows(): boolean;
+    get coverPaperSetup(): PaperSetup;
+    get pagePaperSetup(): PaperSetup;
+    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;
+    constructor(options?: BookOptions);
+    startTurning(ray: THREE.Ray): boolean;
+    updateTurning(ray: THREE.Ray): void;
+    stopTurning(): void;
+    getActivePaperSideIndices(indices: number[]): void;
+    setOpenProgress(openProgress: number): void;
+    setOpenProgressByIndex(paperSideIndex: number): void;
+    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.
+     * Equivalent to Unity's LateUpdate.
+     */
+    update(dt: number): void;
+    dispose(): void;
+    build(): void;
+    clear(): this;
+    private hardClear;
+    private createPaperMeshDataPool;
+    private getFrontPapers;
+    getAverageTime(): number;
+    bookRaycast(ray: THREE.Ray): BookRaycastHit | null;
+    private updateLivePages;
+}
+
+/**
+ * Auto-turn controls. Reads from the nearest `<Book>` context, or from an explicit ref.
+ */
+export declare function useAutoTurn(bookRef?: React.RefObject<ThreeBook | null>): AutoTurnControls;
+
+/** Returns the nearest ancestor Book instance, or null if none. */
+export declare function useBook(): ThreeBook | null;
+
+/**
+ * @param factory  Pure function that creates a BookContent.  Treated as
+ *                 unstable — only called when `deps` change.
+ * @param deps     Dependency array, like useMemo.
+ */
+export declare function useBookContent(factory: () => BookContent, deps: React.DependencyList): BookContent;
+
+/**
+ * Stable imperative controls for open-progress and drag-turn management.
+ * Reads from the nearest `<Book>` context, or from an explicit ref.
+ */
+export declare function useBookControls(bookRef?: React.RefObject<ThreeBook | null>): BookControls;
+
+/**
+ * Creates and manages the lifecycle of a ThreeBook instance.
+ *
+ * @param options  Passed directly to `new Book(options)`.  Changes after
+ *                 mount are **ignored** — trigger a rebuild via `key` instead.
+ * @param onBuilt  Called after `book.init()` succeeds.
+ * @param onError  Called if `book.init()` throws.
+ */
+export declare function useBookRef(options: BookOptions, onBuilt?: (book: ThreeBook) => void, onError?: (err: Error) => void): UseBookRefResult;
+
+export declare interface UseBookRefResult {
+    /** Ref to the ThreeBook instance (null until init succeeds). */
+    bookRef: React.MutableRefObject<ThreeBook | null>;
+    /** True once init() has returned without error. */
+    ready: boolean;
+}
+
+/**
+ * Returns a reactive snapshot of the ThreeBook's runtime state.
+ *
+ * @param bookRef  Optional explicit ref.  If omitted, the nearest
+ *                 `<Book>` context is used.
+ */
+export declare function useBookState(bookRef?: React.RefObject<ThreeBook | null>): BookState;
+
+/**
+ * Attaches pointer-drag events on the R3F canvas for interactive page turning.
+ * Prefer the declarative `<BookInteraction>` component unless you need raw access.
+ */
+export declare function usePageTurning(bookRef: React.RefObject<ThreeBook | null>, { enabled, orbitControlsRef }?: UsePageTurningOptions): void;
+
+export declare interface UsePageTurningOptions {
+    /** Disable pointer events without unmounting. Default: true. */
+    enabled?: boolean;
+    /** OrbitControls ref — disabled during drag, re-enabled on release. */
+    orbitControlsRef?: React.RefObject<{
+        enabled: boolean;
+    } | null>;
+}
+
+/** Returns the nearest ancestor Book instance. Throws outside a <Book> tree. */
+export declare function useRequiredBook(): ThreeBook;
+
+export { }