@objectifthunes/react-three-book 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -385,13 +385,16 @@ export declare interface BookState {
 }
 
 /**
- * Creates a 512×512 `THREE.CanvasTexture` suitable for use as a book page.
+ * Creates a `THREE.CanvasTexture` suitable for use as a book page.
+ *
+ * When `pageWidth` and `pageHeight` are given the canvas matches the page
+ * aspect ratio (256 px per world unit).  Otherwise defaults to 512×512.
  *
  * - 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;
+export declare function createPageTexture(color: string, label: string, image: HTMLImageElement | null, fitMode: ImageFitMode, fullBleed: boolean, pageWidth?: number, pageHeight?: number): THREE.Texture;
 
 /**
  * Ported from Book.cs — Cylinder struct (lines ~3805-3902).
@@ -987,6 +990,9 @@ export declare class PaperUVMargin {
     clone(): PaperUVMargin;
 }
 
+/** Pixels per world unit — used to compute canvas size from page dimensions. */
+export declare const PX_PER_UNIT = 256;
+
 export declare class RendererFactory {
     private m_Root;
     private m_CreateMeshCollider;
@@ -1093,6 +1099,119 @@ export declare class StapleSetup {
     set quality(value: number);
 }
 
+export declare class TextBlock {
+    x: number;
+    y: number;
+    width: number;
+    text: string;
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: 'normal' | 'bold';
+    fontStyle: 'normal' | 'italic';
+    color: string;
+    lineHeight: number;
+    textAlign: 'left' | 'center' | 'right';
+    opacity: number;
+    shadowColor: string;
+    shadowBlur: number;
+    constructor(options?: TextBlockOptions);
+    private _font;
+    /**
+     * Word-wrap `text` into lines that fit within `width` pixels.
+     * Respects explicit newlines.
+     */
+    wrapLines(ctx: CanvasRenderingContext2D): string[];
+    /** Total rendered height in canvas pixels. */
+    measureHeight(ctx: CanvasRenderingContext2D): number;
+    /** Returns true if the point (px, py) is within the text bounding box. */
+    hitTest(ctx: CanvasRenderingContext2D, px: number, py: number): boolean;
+    private _maxLineWidth;
+    draw(ctx: CanvasRenderingContext2D): void;
+}
+
+/**
+ * A styled text block rendered onto a 2D canvas.
+ *
+ * Positions and dimensions are in canvas pixels.  Word-wrapping is handled
+ * manually via `ctx.measureText()` when `width` > 0.
+ */
+export declare interface TextBlockOptions {
+    /** Left edge of the text box in canvas pixels. */
+    x?: number;
+    /** Top edge of the text box in canvas pixels. */
+    y?: number;
+    /** Maximum width before wrapping.  0 = no wrapping (default 0). */
+    width?: number;
+    /** Text content. */
+    text?: string;
+    /** Font family (default 'Georgia'). */
+    fontFamily?: string;
+    /** Font size in canvas pixels (default 24). */
+    fontSize?: number;
+    /** Font weight (default 'normal'). */
+    fontWeight?: 'normal' | 'bold';
+    /** Font style (default 'normal'). */
+    fontStyle?: 'normal' | 'italic';
+    /** CSS fill colour (default '#222'). */
+    color?: string;
+    /** Line height multiplier (default 1.4). */
+    lineHeight?: number;
+    /** Text alignment within the box (default 'left'). */
+    textAlign?: 'left' | 'center' | 'right';
+    /** Opacity 0–1 (default 1). */
+    opacity?: number;
+    /** Optional text shadow colour for readability. */
+    shadowColor?: string;
+    /** Shadow blur radius in pixels (default 0). */
+    shadowBlur?: number;
+}
+
+export declare class TextOverlayContent implements IPageContent {
+    readonly canvas: HTMLCanvasElement;
+    readonly texts: TextBlock[];
+    private readonly ctx;
+    private readonly _texture;
+    private readonly _textureST;
+    private _source;
+    get texture(): THREE.Texture;
+    get textureST(): THREE.Vector4;
+    /** The base layer drawn beneath text blocks. */
+    get source(): HTMLCanvasElement | HTMLImageElement | null;
+    set source(v: HTMLCanvasElement | HTMLImageElement | null);
+    constructor(options?: TextOverlayContentOptions);
+    addText(options?: TextBlockOptions): TextBlock;
+    removeText(text: TextBlock): void;
+    /** Update a text block by index. Only provided fields are changed. */
+    updateText(index: number, options: Partial<TextBlockOptions>): void;
+    /**
+     * Re-composite the canvas: source layer + text blocks.
+     * Call every frame (or when content changes).
+     *
+     * @param root  Optional THREE.Object3D to traverse for texture sync
+     *              (same pattern as SpriteScene — needed because three-book
+     *              clones material textures).
+     */
+    update(root?: THREE.Object3D): void;
+    /**
+     * Traverse `root` and set `needsUpdate = true` on every material map whose
+     * source image is this overlay's canvas.
+     */
+    syncMaterials(root: THREE.Object3D): void;
+    isPointOverUI(_textureCoord: THREE.Vector2): boolean;
+    init(_bookContent: BookContent): void;
+    setActive(_active: boolean): void;
+    dispose(): void;
+}
+
+export declare interface TextOverlayContentOptions {
+    /** Canvas width in pixels (default 512). */
+    width?: number;
+    /** Canvas height in pixels (default 512). */
+    height?: number;
+    /** Source canvas or image to draw as the base layer. */
+    source?: HTMLCanvasElement | HTMLImageElement | null;
+}
+
 export declare class ThreeBook extends THREE.Group {
     private static s_Instances;
     static get instances(): ThreeBook[];
@@ -1263,4 +1382,15 @@ export declare interface UsePageTurningOptions {
 /** Returns the nearest ancestor Book instance. Throws outside a <Book> tree. */
 export declare function useRequiredBook(): ThreeBook;
 
+/**
+ * Creates and manages a TextOverlayContent instance with per-frame compositing.
+ *
+ * The returned overlay's canvas is re-composited every frame (source + text blocks).
+ * Material sync is performed automatically if inside a `<Book>` tree.
+ *
+ * @param options  Initial options (width, height, source).
+ * @returns The TextOverlayContent instance (stable ref).
+ */
+export declare function useTextOverlay(options?: TextOverlayContentOptions): TextOverlayContent;
+
 export { }