textmode.js 0.4.1-beta.1 → 0.6.0-beta.2

package/dist/types/textmode/AnimationController.d.ts

@@ -3,7 +3,6 @@
  * Provides precise frame rate limiting and smooth animation timing.
  */
 export declare class AnimationController {
-    private _frameRateLimit;
     private _frameInterval;
     private _animationFrameId;
     private _lastFrameTime;
@@ -22,60 +21,51 @@ export declare class AnimationController {
      * Start the animation loop with the provided render callback.
      * @param renderCallback Function to call for each frame render
      */
-    start(renderCallback: () => void): void;
+    $start(renderCallback: () => void): void;
     /**
      * Stop the animation loop.
      */
-    stop(): void;
+    $stop(): void;
     /**
      * Pause the animation loop without stopping it completely.
      */
-    pause(): void;
+    $pause(): void;
     /**
      * Resume the animation loop if it was paused.
      * @param renderCallback Function to call for each frame render
      */
-    resume(renderCallback: () => void): void;
+    $resume(renderCallback: () => void): void;
     /**
      * Set or get the frame rate limit.
      * @param fps Optional new frame rate limit. If not provided, returns current measured frame rate.
      * @param renderCallback Required when setting new frame rate and animation is running
      * @returns Current measured frame rate when getting, void when setting
      */
-    frameRate(fps?: number, renderCallback?: () => void): number | void;
+    $frameRate(fps?: number, renderCallback?: () => void): number | void;
     /**
      * Update frame rate measurement. Should be called on each render.
      * Uses a rolling average for smoother frame rate reporting.
      */
-    measureFrameRate(): void;
+    $measureFrameRate(): void;
     /**
      * Check if the animation loop is currently active.
      */
-    get isLooping(): boolean;
-    /**
-     * Get the current frame rate limit.
-     */
-    get frameRateLimit(): number;
+    get $isLooping(): boolean;
     /**
      * Get the current measured frame rate.
      */
-    get currentFrameRate(): number;
+    get $currentFrameRate(): number;
     /**
      * Get the current frame count.
      */
-    get frameCount(): number;
+    get $frameCount(): number;
     /**
      * Set the current frame count.
      */
-    set frameCount(value: number);
+    set $frameCount(value: number);
     /**
      * Increment the frame count by one.
      * Should be called on each render to track total frames rendered.
      */
-    incrementFrame(): void;
-    /**
-     * Reset the frame count to zero.
-     * Useful when restarting animations or resetting state.
-     */
-    resetFrameCount(): void;
+    $incrementFrame(): void;
 }

package/dist/types/textmode/Canvas.d.ts

@@ -1,4 +1,5 @@
-import type { TextmodeOptions } from "./Textmodifier";
+import type { TextmodeOptions } from "./types";
+import { type RGBA } from "./utils/cssColor";
 /**
  * Manages a `HTMLCanvasElement` for textmode rendering.
  * @ignore
@@ -7,7 +8,6 @@ export declare class TextmodeCanvas {
     private _canvas;
     private _targetCanvas;
     private _isOverlay;
-    private _resizeObserver?;
     private _canvasCreatedByUs;
     /**
      * Creates a new TextmodeCanvas instance.
@@ -18,6 +18,13 @@ export declare class TextmodeCanvas {
     private _createCanvas;
     private _createOverlayCanvas;
     private _setupOverlayPositioning;
+    private _collectBackgroundSources;
+    /**
+     * Attempts to detect the background color behind the textmode canvas.
+     * Used internally for theming transparent UI elements like the loading screen.
+     * @ignore
+     */
+    $sampleBackgroundColor(): RGBA | null;
     private _positionOverlayCanvas;
     /**
      * Resize the canvas to the specified width and height.
@@ -38,6 +45,7 @@ export declare class TextmodeCanvas {
      * @ignore
      */
     $dispose(): void;
+    /** Getters */
     get canvas(): HTMLCanvasElement;
     get targetCanvas(): HTMLCanvasElement | HTMLVideoElement | null;
     get width(): number;

package/dist/types/textmode/Grid.d.ts

@@ -1,5 +1,7 @@
 /**
  * Manages the grid of a {@link Textmodifier} instance.
+ *
+ * Can be accessed via {@link Textmodifier.grid}.
  */
 export declare class TextmodeGrid {
     /** The number of columns in the grid. */

package/dist/types/textmode/TextmodeColor.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Represents a color in the `textmode.js` rendering system.
+ *
+ * Values are stored as `0-255` integers for compatibility with public APIs,
+ * while normalized versions are derived on demand for shader uploads.
+ *
+ * Use {@link Textmodifier.color} to create colors.
+ */
+export declare class TextmodeColor {
+    private readonly _rgba;
+    private readonly _normalized;
+    private readonly _character?;
+    /** Red component *(0-255)* */
+    readonly r: number;
+    /** Green component *(0-255)* */
+    readonly g: number;
+    /** Blue component *(0-255)* */
+    readonly b: number;
+    /** Alpha component *(0-255)* */
+    readonly a: number;
+    private constructor();
+    /**
+     * Create a color from RGB or RGBA components (0-255 range).
+     * @ignore
+     */
+    static $fromRGBA(r: number, g: number, b: number, a?: number): TextmodeColor;
+    /**
+     * Create a grayscale color. Optional alpha can be provided.
+     * @ignore
+     */
+    static $fromGray(gray: number, alpha?: number): TextmodeColor;
+    /**
+     * Create a color from a CSS-style hex string.
+     * @ignore
+     */
+    static $fromHex(hex: string): TextmodeColor;
+    /**
+     * Create a color representing a textmode character encoded as RGB triplet
+     * (values already normalized 0-1 for shader usage).
+     * @ignore
+     */
+    static $fromCharacter(characterColor: [number, number, number]): TextmodeColor;
+    /** Returns a plain RGB array with integer components. */
+    get rgb(): [number, number, number];
+    /** Returns a plain RGBA array with integer components. */
+    get rgba(): [number, number, number, number];
+    /** Returns the normalized *(0-1)* RGBA array. */
+    get normalized(): [number, number, number, number];
+    /** Returns the character encoding *(0-1 range)* if this color was created from a glyph. */
+    get character(): [number, number, number] | undefined;
+    /**
+     * Runtime type guard.
+     * @ignore
+     */
+    static $isColor(value: unknown): value is TextmodeColor;
+}
+export type ColorLike = TextmodeColor | [number, number, number] | [number, number, number, number];

package/dist/types/textmode/Textmodifier.d.ts

@@ -1,70 +1,34 @@
-import { GLRenderer } from '../rendering/webgl/Renderer';
-import { TextmodeFont } from './font';
+import { GLRenderer } from '../rendering/webgl/core/Renderer';
+import { TextmodeFont } from './loadables/font';
 import { TextmodeGrid } from './Grid';
 import { TextmodeCanvas } from './Canvas';
-import { TextmodeImage } from './TextmodeImage';
+import { TextmodeImage } from './loadables/TextmodeImage';
 import { AnimationController } from './AnimationController';
 import { MouseManager } from './managers/MouseManager';
 import { KeyboardManager } from './managers/KeyboardManager';
 import { TouchManager } from './managers/TouchManager';
-import { type TextmodifierContext } from './mixins';
-import { type TextmodePlugin, type TextmodePluginContext } from './plugins/PluginManager';
-import type { RenderingCapabilities } from './mixins/RenderingMixin';
-import type { FontCapabilities } from './mixins/FontMixin';
-import type { AnimationCapabilities } from './mixins/AnimationMixin';
-import type { MouseCapabilities } from './mixins/MouseMixin';
-import type { TouchCapabilities } from './mixins/TouchMixin';
-import type { KeyboardCapabilities } from './mixins/KeyboardMixin';
+import type { ITextmodifier } from './interfaces';
 import type { GLFramebuffer, Shader } from '../rendering';
-/**
- * Options for creating a {@link Textmodifier} instance.
- */
-export type TextmodeOptions = {
-    /**
-     * An existing [HTMLCanvasElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) to use instead of creating a new one.
-     *
-     * **Note:**
-     * If using `overlay` mode, this should be the target canvas or video element to overlay on.
-     * `textmode.js` will create its own canvas applied on top of the target element, always matching its size and position.
-     */
-    canvas?: HTMLCanvasElement;
-    /** The font size to use for text rendering. Defaults to 16. */
-    fontSize?: number;
-    /** Maximum frames per second for auto rendering. Defaults to 60. */
-    frameRate?: number;
-    /** The width of the canvas when creating a new canvas. Defaults to 800. */
-    width?: number;
-    /** The height of the canvas when creating a new canvas. Defaults to 600. */
-    height?: number;
-    /**
-     * URL or path to a custom font file *(.otf/.ttf)*.
-     *
-     * Required when using minified builds that don't include a default font.
-     *
-     * Optional for full builds *(will override embedded font if provided)*.
-     */
-    fontSource?: string;
-    /**
-     * Use `textmode.js` in overlay mode,
-     * which sets up the textmode `<canvas>` on top of an existing HTMLCanvasElement or HTMLVideoElement,
-     * automatically resizing and positioning it to match the target element.
-     *
-     * In this mode `textmode.js` fetches the content of the target element and applies it with adjustable textmode conversion
-     * as a first layer to the textmode canvas.
-     *
-     * Useful for applying textmode conversion to p5.js sketches, YouTube videos, and sooo much more.
-     *
-     * All functionality of `textmode.js` remains available, including drawing additional content on top of the converted source.
-     *
-     */
-    overlay?: boolean;
-    /** List of plugins to install when the Textmodifier instance is created. */
-    plugins?: TextmodePlugin[];
+import type { TextmodeOptions } from './types';
+import type { IAnimationMixin } from './mixins/interfaces/IAnimationMixin';
+import type { IFontMixin } from './mixins/interfaces/IFontMixin';
+import type { IRenderingMixin } from './mixins/interfaces/IRenderingMixin';
+import type { IKeyboardMixin } from './mixins/interfaces/IKeyboardMixin';
+import type { ITouchMixin } from './mixins/interfaces/ITouchMixin';
+import type { IMouseMixin } from './mixins/interfaces/IMouseMixin';
+import { LoadingScreenManager } from './loading/LoadingScreenManager';
+declare const Textmodifier_base: {
+    new (): {};
 };
 /**
- * Base class for mixin application.
+ * Manages textmode rendering on a [`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) and provides methods for drawing,
+ * font management, event handling, and animation control.
+ *
+ * If the `Textmodifier` instance is created without a canvas parameter,
+ * it creates a new `HTMLCanvasElement` to draw on using the `textmode.js` drawing API.
+ * If a canvas is provided, it will use that canvas instead.
  */
-declare class TextmodifierCore implements TextmodifierContext {
+export declare class Textmodifier extends Textmodifier_base implements ITextmodifier {
     _renderer: GLRenderer;
     _font: TextmodeFont;
     _canvas: TextmodeCanvas;
@@ -73,27 +37,16 @@ declare class TextmodifierCore implements TextmodifierContext {
     _mouseManager: MouseManager;
     _touchManager: TouchManager;
     _keyboardManager: KeyboardManager;
-    _textmodeDrawShader: Shader;
+    _loading: LoadingScreenManager;
     _textmodeDrawFramebuffer: GLFramebuffer;
     _textmodeConversionShader: Shader;
-    _asciiColorFramebuffer: GLFramebuffer;
+    _textmodeFramebuffer: GLFramebuffer;
     _presentShader: Shader;
-    $render(): void;
-}
-declare const Textmodifier_base: typeof TextmodifierCore;
-/**
- * Manages textmode rendering on a [`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) and provides methods for drawing,
- * exporting, font management, event handling, and animation control.
- *
- * If the `Textmodifier` instance is created without a canvas parameter,
- * it creates a new `HTMLCanvasElement` to draw on using the `textmode.js` drawing API.
- * If a canvas is provided, it will use that canvas instead.
- */
-export declare class Textmodifier extends Textmodifier_base {
     private _pluginManager;
     private _destroyRequested;
     private _isRenderingFrame;
     private _isDisposed;
+    private _setupComplete;
     private _setupCallback;
     private _drawCallback;
     private _resizedCallback;
@@ -102,168 +55,34 @@ export declare class Textmodifier extends Textmodifier_base {
     private _isOverlay;
     private _targetCanvasImage?;
     /**
-     * Creates an instance of Textmodifier.
-     * @param opts Optional configuration options for the Textmodifier instance.
+     * Create a new Textmodifier instance.
+     * @param opts Configuration options for the Textmodifier instance.
      * @ignore
      */
     constructor(opts?: TextmodeOptions);
-    /**
-     * Internal async initialization method.
-     * @param opts Configuration options
-     */
     private _initialize;
     /**
-     * Provide plugins with a minimal API surface so they can interact with the renderer safely.
-     * @ignore
-     */
-    $getPluginContext(): TextmodePluginContext;
-    /**
-     * Setup event listeners for resize handling.
+     * Setup event listeners for window resize and input handling.
      * @ignore
      */
     $setupEventListeners(): void;
-    /**
-     * Renders the current frame.
-     * @returns void
-     * @ignore
-     */
     $render(): void;
-    /**
-     * Set a setup callback function that will be executed once when initialization is complete.
-     *
-     * This callback is called after font loading and grid initialization, allowing access to
-     * properties like `textmodifier.grid.cols` for calculating layout or setup variables.
-     *
-     * @param callback The function to call when setup is complete
-     *
-     * @example
-     * ```javascript
-     * const textmodifier = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     *   fontSize: 16
-     * });
-     *
-     * // Setup callback - called once when ready
-     * textmodifier.setup(() => {
-     *   // Now you can access grid properties
-     *   const cols = textmodifier.grid.cols;
-     *   const rows = textmodifier.grid.rows;
-     *
-     *   // Initialize any variables that depend on grid size
-     *   cellWidth = Math.floor(cols / 3);
-     *   cellHeight = Math.floor(rows / 2);
-     * });
-     *
-     * // Draw callback - called every frame
-     * textmodifier.draw(() => {
-     *   textmodifier.background(128);
-     *   textmodifier.rect(0, 0, cellWidth, cellHeight);
-     * });
-     * ```
-     */
-    setup(callback: () => void): void;
-    /**
-     * Set a draw callback function that will be executed before each render.
-     *
-     * This callback function is where all drawing commands should be placed for textmode rendering.
-     *
-     * @param callback The function to call before each render
-     *
-     * @example
-     * ```javascript
-     * // Create a standalone textmodifier instance
-     * const t = textmode.create({
-     *  width: 800,
-     *  height: 600,
-     * });
-     *
-     * // Set up draw callback
-     * t.draw(() => {
-     *   // Set background color
-     *   t.background(128);
-     *
-     *   // Draw a textmode rectangle with default settings
-     *   t.rect(0, 0, 16, 16);
-     * });
-     * ```
-     */
-    draw(callback: () => void): void;
-    /**
-     * Set a callback function that will be called when the window is resized.
-     * @param callback The function to call when the window is resized.
-     *
-     * @example
-     * ```javascript
-     * // Create a standalone textmodifier instance
-     * const t = textmode.create({
-     *  width: window.innerWidth,
-     *  height: window.innerHeight,
-     * });
-     *
-     * // Draw callback to update content
-     * t.draw(() => {
-     *   // Set background color
-     *   t.background(128);
-     *
-     *   t.rect(0, 0, t.grid.cols, t.grid.rows);
-     * });
-     *
-     * // Set up window resize callback
-     * t.windowResized(() => {
-     *   // Resize the canvas to match window size
-     *   t.resizeCanvas(window.innerWidth, window.innerHeight);
-     * });
-     *
-     */
-    windowResized(callback: () => void): void;
-    /**
-     * Resize the canvas and adjust all related components accordingly.
-     *
-     * @param width The new width of the canvas.
-     * @param height The new height of the canvas.
-     */
     resizeCanvas(width: number, height: number): void;
-    /**
-     * Completely destroy this Textmodifier instance and free all associated resources.
-     *
-     * After calling this method, the instance should not be used and will be eligible for garbage collection.
-     *
-     * @example
-     * ```javascript
-     * // Create a textmodifier instance
-     * const textmodifier = textmode.create();
-     *
-     * // ...
-     *
-     * // When done, completely clean up
-     * textmodifier.destroy();
-     *
-     * // Instance is now safely disposed and ready for garbage collection
-     * ```
-     */
     destroy(): void;
     private _performDestroy;
-    /** Get the current grid object used for rendering. */
+    setup(callback: () => void | Promise<void>): void;
+    draw(callback: () => void): void;
+    windowResized(callback: () => void): void;
     get grid(): TextmodeGrid;
-    /** Get the current font object used for rendering. */
     get font(): TextmodeFont;
-    /** Get the width of the canvas. */
     get width(): number;
-    /** Get the height of the canvas. */
     get height(): number;
-    /** Get the textmodifier canvas containing the rendered output. */
     get canvas(): HTMLCanvasElement;
-    /** Get the WebGL framebuffer used for drawing operations. */
     get drawFramebuffer(): GLFramebuffer;
-    /** Check if the instance has been disposed/destroyed. */
     get isDisposed(): boolean;
-    /**
-     * If in overlay mode, returns the {@link TextmodeImage} instance capturing the target canvas/video content,
-     * allowing further configuration of the conversion parameters.
-     */
     get overlay(): TextmodeImage | undefined;
+    get loading(): LoadingScreenManager;
 }
-export interface Textmodifier extends RenderingCapabilities, FontCapabilities, AnimationCapabilities, MouseCapabilities, TouchCapabilities, KeyboardCapabilities {
+export interface Textmodifier extends IRenderingMixin, IFontMixin, IAnimationMixin, IMouseMixin, ITouchMixin, IKeyboardMixin {
 }
 export {};