textmode.js 0.4.0 → 0.6.0-beta.1

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,97 +1,56 @@
-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;
+    _loadingFont: TextmodeFont;
     _canvas: TextmodeCanvas;
     _grid: TextmodeGrid;
+    _loadingGrid: TextmodeGrid;
     _animationController: AnimationController;
     _mouseManager: MouseManager;
     _touchManager: TouchManager;
     _keyboardManager: KeyboardManager;
-    _textmodeDrawShader: Shader;
     _textmodeDrawFramebuffer: GLFramebuffer;
+    _loadingDrawFramebuffer: GLFramebuffer;
     _textmodeConversionShader: Shader;
-    _asciiColorFramebuffer: GLFramebuffer;
+    _textmodeFramebuffer: GLFramebuffer;
+    _loadingFramebuffer: 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;
+    _loading: LoadingScreenManager;
+    private _destroyRequested;
+    private _isRenderingFrame;
     private _isDisposed;
+    private _setupComplete;
     private _setupCallback;
     private _drawCallback;
     private _resizedCallback;
@@ -100,166 +59,35 @@ 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.
-     */
-    $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;
-    /** Get the current grid object used for rendering. */
+    private _performDestroy;
+    /** Callbacks */
+    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 {};

package/dist/types/textmode/interfaces/ITextmodifier.d.ts

@@ -0,0 +1,272 @@
+import type { TextmodeGrid } from '../Grid';
+import type { TextmodeFont } from '../loadables/font';
+import type { TextmodeImage } from '../loadables/TextmodeImage';
+import type { TextmodeCanvas } from '../Canvas';
+import type { AnimationController } from '../AnimationController';
+import type { GLFramebuffer, Shader } from '../../rendering';
+import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
+import type { MouseManager } from '../managers/MouseManager';
+import type { KeyboardManager } from '../managers/KeyboardManager';
+import type { TouchManager } from '../managers/TouchManager';
+import type { IRenderingMixin } from '../mixins/interfaces/IRenderingMixin';
+import type { IFontMixin } from '../mixins/interfaces/IFontMixin';
+import type { IKeyboardMixin } from '../mixins/interfaces/IKeyboardMixin';
+import type { ITouchMixin } from '../mixins/interfaces/ITouchMixin';
+import type { IMouseMixin } from '../mixins/interfaces/IMouseMixin';
+import type { IAnimationMixin } from '../mixins/interfaces/IAnimationMixin';
+import type { LoadingScreenManager } from '../loading/LoadingScreenManager';
+/**
+ * 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 interface ITextmodifier extends IRenderingMixin, IFontMixin, IAnimationMixin, IMouseMixin, ITouchMixin, IKeyboardMixin {
+    /** Core WebGL renderer @ignore */
+    readonly _renderer: GLRenderer;
+    /** Font management @ignore */
+    readonly _font: TextmodeFont;
+    /** Canvas management @ignore */
+    readonly _canvas: TextmodeCanvas;
+    /** Grid management @ignore */
+    readonly _grid: TextmodeGrid;
+    /** Animation controller for managing rendering loop @ignore */
+    readonly _animationController: AnimationController;
+    /** Mouse interaction manager @ignore */
+    readonly _mouseManager: MouseManager;
+    /** Touch interaction manager @ignore */
+    readonly _touchManager: TouchManager;
+    /** Keyboard interaction manager @ignore */
+    readonly _keyboardManager: KeyboardManager;
+    /** Framebuffer used for offscreen rendering @ignore */
+    readonly _textmodeDrawFramebuffer: GLFramebuffer;
+    /** Shader used for converting pixels to textmode grid format @ignore */
+    readonly _textmodeConversionShader: Shader;
+    /** Framebuffer used for textmode conversion @ignore */
+    readonly _textmodeFramebuffer: GLFramebuffer;
+    /** Shader used for final presentation to the screen @ignore */
+    readonly _presentShader: Shader;
+    /** Loading screen manager for boot-time UX @ignore */
+    readonly _loading: LoadingScreenManager;
+    /** Main render method @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 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
+     *   t.char('A');
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.rect(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.
+     *
+     * @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.char('A');
+     *  t.rotateZ(t.frameCount * 2);
+     *  t.rect(16, 16);
+     * });
+     *
+     * // Set up window resize callback
+     * t.windowResized(() => {
+     *   // Resize the canvas to match window size
+     *   t.resizeCanvas(window.innerWidth, window.innerHeight);
+     * });
+     * ```
+     */
+    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;
+    /** Get the current grid object used for rendering. */
+    readonly grid: TextmodeGrid;
+    /** Get the current font object used for rendering. */
+    readonly font: TextmodeFont;
+    /** Get the width of the canvas in pixels. */
+    readonly width: number;
+    /** Get the height of the canvas in pixels. */
+    readonly height: number;
+    /** Get the textmodifier canvas containing the rendered output. */
+    readonly canvas: HTMLCanvasElement;
+    /** Get the WebGL framebuffer used for drawing operations in {@link Textmodifier.draw}. */
+    readonly drawFramebuffer: GLFramebuffer;
+    /** Check if the instance has been disposed/destroyed. */
+    readonly isDisposed: boolean;
+    /**
+     * If in overlay mode, returns the {@link TextmodeImage} instance capturing the target canvas/video content,
+     * allowing further configuration of the conversion parameters.
+     *
+     * @example
+     * ```javascript
+     * // Create the textmode instance using the p5 canvas as input overlay
+     * const t = textmode.create({ fontSize: 16, canvas: p.canvas, overlay: true });
+     *
+     * // Configure overlay conversion once fonts and grid are ready
+     * t.setup(() => {
+     *   t.overlay
+     *     .characters(' .:-=+*#%@')        // Character set for brightness mapping
+     *     .cellColorMode('fixed')          // Use fixed background cell color
+     *     .cellColor(0, 0, 0)              // Black background for each cell
+     *     .charColorMode('sampled')        // Sample the character color from the image
+     *     .background(0, 0, 0, 255);       // Black fallback for transparent pixels
+     * });
+     *
+     * // In the draw loop, pass the overlay into the text grid
+     * t.draw(() => {
+     *   t.clear();
+     *   t.image(t.overlay, t.grid.cols, t.grid.rows);
+     * });
+     *```
+     */
+    readonly overlay: TextmodeImage | undefined;
+    /**
+     * Provides access to the loading screen manager to control boot-time loading UX.
+     *
+     * @example
+    * ```javascript
+    * const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'loading...' } });
+    *
+    * t.setup(async () => {
+    *   // Initialize two loading phases
+    *   const phase1 = t.loading.addPhase('Loading assets');
+    *   const phase2 = t.loading.addPhase('Initializing game');
+    *
+    *   // Start the first phase and simulate asset loading
+    *   await phase1.track(async () => {
+    *     for (let i = 0; i <= 5; i++) {
+    *       phase1.report(i / 5);
+    *       // Small delay — increases visibility of the loading animation
+    *       await new Promise((r) => setTimeout(r, 200));
+    *     }
+    *   });
+    *
+    *   // Start the second phase and simulate initialization
+    *   await phase2.track(async () => {
+    *     for (let i = 0; i <= 5; i++) {
+    *       phase2.report(i / 5);
+    *       await new Promise((r) => setTimeout(r, 150));
+    *     }
+    *   });
+    *
+    *   // Optionally set a final message before the screen transitions away
+    *   t.loading.message('Ready - enjoy!');
+    * });
+    * ```
+     */
+    readonly loading: LoadingScreenManager;
+}

package/dist/types/textmode/interfaces/index.d.ts

@@ -0,0 +1 @@
+export type { ITextmodifier } from './ITextmodifier';