textmode.js 0.8.0-beta.3 → 0.8.1-beta.1

package/dist/types/Textmode.d.ts

@@ -24,6 +24,18 @@ export declare class Textmode {
      *     t.rect(10, 10);
      * });
      * ```
+     * @exampleAuthor
+     * <div style="display:flex;align-items:center;gap:0.75rem;flex-wrap:wrap;">
+     *   <img src="https://github.com/humanbydefinition.png" alt="@humanbydefinition avatar" width="72" height="72" style="border-radius:12px;box-shadow:0 2px 6px rgba(0,0,0,0.35);" />
+     *   <div style="display:flex;flex-direction:column;gap:0.25rem;">
+     *     <strong><a href="https://github.com/humanbydefinition">@humanbydefinition</a></strong>
+     *     <span style="font-size:0.95em;">
+     *       📷 <a href="https://instagram.com/humanbydefinition">Instagram</a>
+     *       &nbsp;•&nbsp; 🐘 <a href="https://mastodon.social/@humanbydefinition">Mastodon</a>
+     *       &nbsp;•&nbsp; 🦋 <a href="https://bsky.app/profile/humanbydefinition.bsky.social">BlueSky</a>
+     *     </span>
+     *   </div>
+     * </div>
      */
     static create(opts?: TextmodeOptions): Textmodifier;
     /**
@@ -32,7 +44,7 @@ export declare class Textmode {
      * @param level The error handling level to set.
      *
      * @example
-     * ```javascript
+     * ```js
      * // Set error level to WARNING
      * textmode.setErrorLevel(TextmodeErrorLevel.WARNING);
      * ```
@@ -42,7 +54,7 @@ export declare class Textmode {
      * Returns the version of `textmode.js` being used.
      *
      * @example
-     * ```javascript
+     * ```js
      * console.log(textmode.version); // "1.0.0"
      * ```
      */

package/dist/types/errors/ErrorHandler.d.ts

@@ -9,7 +9,7 @@
  * and most `textmode.js` functions will still throw errors if used incorrectly.
  *
  * @example
- * ```javascript
+ * ```js
  * // Set to `WARNING` level to log errors without stopping execution
  * textmode.setErrorLevel(TextmodeErrorLevel.WARNING);
  * ```

package/dist/types/index.d.ts

@@ -9,7 +9,7 @@ export type { TextmodeFramebufferOptions } from './rendering/webgl';
 /**
  * All media conversion related modules and types.
  *
- * Responsible for converting images and videos into textmode-renderable formats,
+ * Responsible for converting images and videos into textmode-renderable formats
  * using various conversion strategies, like brightness- or edge-detection-based conversion.
  *
  * `textmode.js` only comes with a built-in `'brightness'`-based conversion strategy,
@@ -17,7 +17,15 @@ export type { TextmodeFramebufferOptions } from './rendering/webgl';
  */
 export * as conversion from './textmode/conversion';
 export type { TextmodePlugin, TextmodePluginAPI } from './textmode/managers/PluginManager';
-/** All filter related modules and types. */
+/**
+ * All filter related modules and types.
+ *
+ * Provides various image processing filters that can be applied in sequence on a layer's textmode-converted output,
+ * such as blur, sharpen, edge detection, and color adjustments. Filters can also be applied globally to all layers as post-processing effects.
+ *
+ * While `textmode.js` only offers a basic set of filters, additional filters can be implemented and registered via the {@link TextmodeFilterManager},
+ * which is accessible through {@link Textmodifier.filters}.
+ */
 export * as filters from './textmode/filters';
 export { TextmodeErrorLevel } from './errors/ErrorHandler';
 export { Textmode as textmode } from './Textmode';

package/dist/types/rendering/webgl/utils/hash.d.ts

@@ -17,7 +17,7 @@
  * @returns 32-bit integer hash
  *
  * @example
- * ```typescript
+ * ```ts
  * hashString("hello") // → 99162322
  * hashString("world") // → 113318802
  * ```
@@ -31,7 +31,7 @@ export declare function hashString(str: string): number;
  * @returns Integer hash
  *
  * @example
- * ```typescript
+ * ```ts
  * hashNumber(42)    // → 42
  * hashNumber(3.14)  // → 3
  * hashNumber(true)  // → 1
@@ -47,7 +47,7 @@ export declare function hashNumber(value: number | boolean): number;
  * @returns Combined hash of all elements
  *
  * @example
- * ```typescript
+ * ```ts
  * hashArray([1, 2, 3])           // → computed hash
  * hashArray([[1, 2], [3, 4]])    // → computed hash (flattened)
  * ```
@@ -61,7 +61,7 @@ export declare function hashArray(arr: number[] | number[][]): number;
  * @returns Combined hash
  *
  * @example
- * ```typescript
+ * ```ts
  * const arr = new Float32Array([1.0, 2.0, 3.0]);
  * hashTypedArray(arr) // → computed hash
  * ```
@@ -77,7 +77,7 @@ export declare function hashObject(obj: any): number;
  * @returns Combined hash
  *
  * @example
- * ```typescript
+ * ```ts
  * const h1 = hashString("hello");
  * const h2 = hashString("world");
  * const combined = combineHashes(h1, h2);
@@ -93,7 +93,7 @@ export declare function combineHashes(hash1: number, hash2: number): number;
  * @returns Combined hash of all key-value pairs
  *
  * @example
- * ```typescript
+ * ```ts
  * const obj = { b: 2, a: 1, c: 3 };
  * const hash = hashRecord(obj, hashNumber);
  * // Keys are sorted: a, b, c → consistent hash

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

@@ -62,6 +62,7 @@ export declare class Textmodifier extends Textmodifier_base implements ITextmodi
     private _resizeObserver?;
     private _isOverlay;
     private _targetCanvasImage?;
+    private _inputGridOverride?;
     /**
      * Create a new Textmodifier instance.
      * @param opts Configuration options for the Textmodifier instance.
@@ -82,6 +83,13 @@ export declare class Textmodifier extends Textmodifier_base implements ITextmodi
     filter(name: FilterName, params?: unknown): void;
     loadFont(fontSource: string): Promise<TextmodeFont>;
     fontSize(size: number): void;
+    inputGrid(target?: 'topmost' | TextmodeGrid): 'topmost' | TextmodeGrid | void;
+    /**
+     * Get the grid used for input coordinate mapping.
+     * Returns the override grid/layer's grid if set, otherwise the topmost visible layer's grid.
+     * @ignore
+     */
+    private _getInputGrid;
     setup(callback: () => void | Promise<void>): Promise<void>;
     draw(callback: () => void): void;
     windowResized(callback: () => void): void;

package/dist/types/textmode/conversion/ConversionManager.d.ts

@@ -9,7 +9,7 @@ import type { TextmodeConversionMode, TextmodeConversionStrategy } from './Conve
  * Used for image-to-ASCII conversion modes.
  *
  * @example
- * ```typescript
+ * ```ts
  * // Register a custom conversion strategy
  * t.conversions.register({
  *     id: 'custom',
@@ -35,7 +35,7 @@ export declare class TextmodeConversionManager {
      * @param strategy The conversion strategy to register
      *
      * @example
-     * ```typescript
+     * ```ts
      * t.conversions.register({
      *     id: 'custom',
      *     createShader: (ctx) => shader,

package/dist/types/textmode/conversion/ConversionRegistry.d.ts

@@ -9,7 +9,7 @@ export type BuiltInConversionMode = 'brightness';
 /**
  * Type representing the available textmode conversion modes
  */
-export type TextmodeConversionMode = BuiltInConversionMode | (string & {});
+export type TextmodeConversionMode = BuiltInConversionMode | string;
 /**
  * Interface for the context provided to conversion strategies
  * @ignore
@@ -38,7 +38,7 @@ export interface TextmodeConversionStrategy {
  * conversion strategies to be scoped to a specific Textmodifier instance rather than registered globally.
  *
  * @example
- * ```typescript
+ * ```ts
  * // Register a custom conversion strategy
  * t.conversions.register(myCustomStrategy);
  *

package/dist/types/textmode/filters/FilterManager.d.ts

@@ -3,15 +3,10 @@ import type { QueuedFilter, FilterName } from './types';
 /**
  * Manages filter registration, shader compilation, and filter chain application.
  *
- * This class provides:
- * - A registry for custom and built-in filter strategies
- * - Lazy shader compilation and caching
- * - Ping-pong rendering for efficient multi-filter chains
- *
  * Used both for layer-level filters and global post-processing filters.
  *
  * @example
- * ```typescript
+ * ```ts
  * // Register a custom filter
  * await t.filters.register('brightness', brightnessShader, {
  *     u_amount: ['amount', 1.0]
@@ -45,7 +40,7 @@ export declare class TextmodeFilterManager {
      * @param uniformDefs Maps uniform names to [paramName, defaultValue] tuples
      *
      * @example
-     * ```typescript
+     * ```ts
      * // Register with inline shader source
      * await t.filters.register('blur', blurFragSource, {
      *     u_radius: ['radius', 5.0],

package/dist/types/textmode/filters/FilterRegistry.d.ts

@@ -7,7 +7,7 @@ import type { TextmodeFilterStrategy, FilterName } from './types';
  * filters to be scoped to a specific context rather than registered globally.
  *
  * @example
- * ```typescript
+ * ```ts
  * // Define a simple filter with the declarative API
  * t.filters.register('blur', blurShader, { radius: 5.0 });
  *
@@ -37,7 +37,7 @@ export declare class FilterRegistry {
      * @param uniforms Default uniform values. Keys map uniform names to [paramName, defaultValue] tuples.
      *
      * @example
-     * ```typescript
+     * ```ts
      * // With pre-compiled shader (recommended for add-ons)
      * const shader = await t.createShader(vertSrc, fragSrc);
      * t.filters.register('brightness', shader, { u_amount: ['amount', 1.0] });

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

@@ -71,6 +71,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * t.setup(async () => {
      *   // Load font for the base layer
      *   const font = await t.loadFont('./fonts/myfont.ttf');
+     *   // const font = await t.layers.base.loadFont('./fonts/myfont.ttf'); // Equivalent
      *
      *   // Use the same font on another layer
      *   const layer = t.layers.add();
@@ -104,6 +105,43 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * ```
      */
     fontSize(size: number): void;
+    /**
+     * Get or set the grid used for mouse and touch input coordinate mapping.
+     *
+     * By default, input coordinates are mapped to the topmost visible layer's grid,
+     * which changes dynamically as layers are shown/hidden. Use this method to lock
+     * input mapping to a specific grid or layer, or to return to responsive mode.
+     *
+     * When called without arguments, returns the current input grid mode:<br/>
+     * - `'topmost'` if using responsive mode (default)<br/>
+     * - The specific `TextmodeGrid` if locked
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create();
+     *
+     * // Add a UI layer on top
+     * const uiLayer = t.layers.add({ fontSize: 16 });
+     *
+     * t.setup(() => {
+     *   // Lock input to the base layer's grid for game controls
+     *   // even though the UI layer is rendered on top
+     *   t.inputGrid(t.layers.base.grid);
+     * });
+     *
+     * t.draw(() => {
+     *   // Mouse positions now always use base layer's grid
+     *   t.text(`Mouse: ${t.mouseX}, ${t.mouseY}`, 0, 0);
+     * });
+     *
+     * // Switch back to responsive mode
+     * // t.inputGrid('topmost');
+     *
+     * // Or check current mode
+     * // const current = t.inputGrid(); // 'topmost' or the locked grid
+     * ```
+     */
+    inputGrid(target?: 'topmost' | TextmodeGrid): 'topmost' | TextmodeGrid | void;
     /**
      * Set a setup callback function that will be executed once when initialization is complete.
      *
@@ -146,9 +184,15 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      *
      * This callback function is where all drawing commands should be placed for textmode rendering on the main layer.
      *
-     * If multiple layers are added via {@link Textmodifier.layers}, each layer can have its own draw callback set via {@link TextmodeLayer.draw}.
+     * If multiple layers are added via {@link Textmodifier.layers}, each layer has its own draw callback set via {@link TextmodeLayer.draw}.
      * This allows for complex multi-layered compositions with independent rendering logic per layer.
      *
+     * Calling this method is equivalent to setting the draw callback on the base layer,
+     * while the direct layer callback has precedence if both are set.
+     * ```js
+     * textmodifier.layers.base.draw(callback);
+     * ```
+     *
      * @param callback The function to call before each render
      *
      * @example
@@ -238,7 +282,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * After calling this method, the instance should not be used and will be eligible for garbage collection.
      *
      * @example
-     * ```javascript
+     * ```js
      * // Create a textmodifier instance
      * const textmodifier = textmode.create();
      *
@@ -262,7 +306,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * @param params Optional parameters for the filter
      *
      * @example
-     * ```typescript
+     * ```ts
      * t.draw(() => {
      *     t.background(0);
      *     t.charColor(255);
@@ -282,7 +326,12 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
     filter<T extends BuiltInFilterName>(name: T, params?: BuiltInFilterParams[T]): void;
     filter(name: FilterName, params?: unknown): void;
     filter(name: FilterName, params?: unknown): void;
-    /** Get the grid object used for rendering the base layer. */
+    /**
+     * Get the grid whose layer is currently being drawn to.
+     * If called outside of a layers draw callback, returns the base layer's grid.
+     *
+     * If no grid is set (e.g., before user setup()), returns `undefined`.
+     */
     readonly grid: TextmodeGrid | undefined;
     /** Get the current font object used for rendering the base layer. */
     readonly font: TextmodeFont;
@@ -299,10 +348,9 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      *
      * Use this to register custom filters that can be applied both globally
      * (via {@link filter}) and on individual layers (via {@link TextmodeLayer.filter}).
-     * Filters only need to be registered once and are available everywhere.
      *
      * @example
-     * ```typescript
+     * ```ts
      * // Register a custom filter once
      * await t.filters.register('vignette', vignetteShader, {
      *     u_intensity: ['intensity', 0.5]
@@ -326,7 +374,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * Access the layer manager for this Textmodifier instance.
      *
      * Use this to create and manage multiple layers within the textmode rendering context.
-     * Each layer can have its own grid, font, draw callback, and filters.
+     * Each layer has its own grid, font, draw callback, and filters.
      */
     readonly layers: TextmodeLayerManager;
     /**
@@ -341,7 +389,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * allowing further configuration of the conversion parameters.
      *
      * @example
-     * ```javascript
+     * ```js
      * // Create the textmode instance using the p5 canvas as input overlay
      * const t = textmode.create({ fontSize: 16, canvas: p.canvas, overlay: true });
      *
@@ -379,7 +427,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      *   await phase1.track(async () => {
      *     for (let i = 0; i <= 5; i++) {
      *       phase1.report(i / 5);
-     *       // Small delay — increases visibility of the loading animation
+     *       // Small delay - increases visibility of the loading animation
      *       await new Promise((r) => setTimeout(r, 200));
      *     }
      *   });

package/dist/types/textmode/layers/LayerManager.d.ts

@@ -6,8 +6,8 @@ import type { ILayerManager } from './interfaces/ILayerManager';
 import type { TextmodeOptions } from '../types';
 import type { TextmodeGrid } from '../Grid';
 /**
- * Manages all user-defined layers within a Textmodifier in *
- * Th *
+ * Manages all user-defined layers within a Textmodifier in addition to the base layer.
+ *
  * This manager is responsible for:
  * - Managing the collection of user layers (add, remove, move, swap)
  * - Coordinating layer rendering and compositing
@@ -73,8 +73,9 @@ export declare class LayerManager implements ILayerManager {
      * Get the grid of the topmost visible layer.
      * Returns the topmost user layer's grid if any are visible, otherwise returns the base layer's grid.
      * This is useful for input managers that need to map coordinates to the layer the user sees on top.
+     * @ignore
      */
-    getTopmostGrid(): TextmodeGrid | undefined;
+    $getTopmostGrid(): TextmodeGrid | undefined;
     /**
      * Register a callback to be invoked whenever ANY layer's grid dimensions change.
      * This includes the base layer and all user layers.

package/dist/types/textmode/layers/TextmodeLayer.d.ts

@@ -10,7 +10,7 @@ import type { ITextmodeLayer } from './interfaces/ITextmodeLayer';
  *
  * Layers are composited together using various blend modes
  * to create complex visual effects. Each layer can be independently
- * manipulated in terms of visibility, opacity, blend mode, and position.
+ * manipulated in terms of visibility, {@link opacity}, {@link blendMode}, {@link offset}, rotation, {@link TextmodeGrid}, and {@link TextmodeFont}.
  *
  * You can draw on each layer by providing a draw callback function,
  * like you would with the base layer's {@link Textmodifier.draw} method.
@@ -88,7 +88,7 @@ export declare class TextmodeLayer implements ITextmodeLayer {
      * @returns The loaded TextmodeFont instance.
      *
      * @example
-     * ```javascript
+     * ```js
      * const layer = t.layers.add();
      *
      * t.setup(async () => {

package/dist/types/textmode/layers/interfaces/ILayerManager.d.ts

@@ -46,5 +46,5 @@ export interface ILayerManager {
      * Returns the topmost user layer's grid if any are visible, otherwise returns the base layer's grid.
      * This is useful for input managers that need to map coordinates to the layer the user sees on top.
      */
-    getTopmostGrid(): TextmodeGrid | undefined;
+    $getTopmostGrid(): TextmodeGrid | undefined;
 }

package/dist/types/textmode/layers/interfaces/ITextmodeLayer.d.ts

@@ -51,7 +51,7 @@ export interface ITextmodeLayer {
      * @param callback The function to call when drawing this layer.
      *
      * @example
-     * ```typescript
+     * ```javascript
      * const t = textmode.create();
      *
      * // Create layers with different blend modes
@@ -130,7 +130,7 @@ export interface ITextmodeLayer {
      * @returns The loaded TextmodeFont instance.
      *
      * @example
-     * ```javascript
+     * ```js
      * const layer = t.layers.add();
      *
      * t.setup(async () => {
@@ -176,7 +176,7 @@ export interface ITextmodeLayer {
      * - `'exclusion'` - Softer difference effect
      *
      * @example
-     * ```typescript
+     * ```javascript
      * const t = textmode.create();
      *
      * // Create 5 layers with different blend modes
@@ -219,7 +219,7 @@ export interface ITextmodeLayer {
      * @returns The current offset if no parameters are provided.
      *
      * @example
-     * ```typescript
+     * ```javascript
      * const t = textmode.create();
      *
      * const LAYER_COUNT = 32;
@@ -301,9 +301,7 @@ export interface ITextmodeLayer {
      * @returns The current rotation in degrees if no parameter is provided.
      *
      * @example
-     * ```typescript
-     * import { textmode } from 'textmode.js';
-     *
+     * ```javascript
      * const t = textmode.create();
      *
      * const rotatingLayer = t.layers.add({ blendMode: 'difference', opacity: 1.0 });
@@ -334,7 +332,7 @@ export interface ITextmodeLayer {
      * Filters are applied after ASCII conversion in the order they are called.
      * Call this method within your layer's draw callback to apply effects.
      *
-     * **Built-in Filters:**
+     * **Built-in filters:**
      * - `'invert'` - Inverts all colors
      * - `'grayscale'` - Converts to grayscale (param: amount 0-1, default 1)
      * - `'sepia'` - Applies sepia tone (param: amount 0-1, default 1)
@@ -344,7 +342,7 @@ export interface ITextmodeLayer {
      * @param params Optional parameters for the filter
      *
      * @example
-     * ```typescript
+     * ```javascript
      * const t = textmode.create();
      *
      * // Create a layer with filters applied

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

@@ -47,9 +47,9 @@ export interface TextmodeLayerOptions {
      */
     offsetY?: number;
     /**
-     * The rotation of the layer in degrees around its center. Default is `0`.
+     * The z-rotation of the layer in degrees around its center. Default is `0`.
      */
-    rotation?: number;
+    rotationZ?: number;
     /**
      * The font size for the layer's text. Default is `16`.
      */

package/dist/types/textmode/loadables/TextmodeImage.d.ts

@@ -29,10 +29,8 @@ import type { TextmodeConversionManager } from '../conversion';
  * t.draw(() => {
  *     t.background(0);
  *
- *     if (img) {
- *         // Draw the loaded image
- *         t.image(img);
- *     }
+ *     // Draw the loaded image
+ *     t.image(img);
  * });
  * ```
  */

package/dist/types/textmode/loadables/font/TextmodeFont.d.ts

@@ -3,13 +3,13 @@ import type { GLFramebuffer } from '../../../rendering/webgl/core/Framebuffer.ts
 import type { TextmodeCharacter } from './types.ts';
 import type { TyprFont } from './typr/types.ts';
 /**
- * Manages the font used for rendering characters via {@link Textmodifier.loadFont}.
+ * Manages the font used for rendering characters via {@link TextmodeLayer.loadFont}.
  *
  * This class coordinates font loading, character extraction, texture atlas creation,
  * and provides character information.
  *
- * The font used by your {@link Textmodifier} instance is accessible via
- * the {@link Textmodifier.font} property.
+ * Each {@link TextmodeLayer} has its own instance of this class to allow for
+ * layer-specific font configurations.
  */
 export declare class TextmodeFont {
     private _font;

package/dist/types/textmode/loadables/video/TextmodeVideo.d.ts

@@ -33,10 +33,8 @@ import type { TextmodeConversionManager } from '../../conversion';
  * t.draw(() => {
  *     t.background(0);
  *
- *     if (video) {
- *         // Draw the loaded video
- *         t.image(video);
- *     }
+ *      // Draw the loaded video
+ *      t.image(video);
  * });
  * ```
  */

package/dist/types/textmode/loading/LoadingPhase.d.ts

@@ -1,5 +1,5 @@
-import type { LoadingPhaseTracker } from "./LoadingPhaseTracker";
-import type { ILoadingPhase } from "./types";
+import type { LoadingPhaseTracker } from './LoadingPhaseTracker';
+import type { ILoadingPhase } from './types';
 /**
  * Represents a loading phase tracked by a LoadingPhaseTracker.
  *
@@ -11,16 +11,18 @@ export declare class LoadingPhase implements ILoadingPhase {
     private readonly _phaseTracker;
     readonly id: string;
     readonly label: string;
+    private readonly _onError?;
     /**
      * Creates a new LoadingPhase.
      * @param _phaseTracker The LoadingPhaseTracker managing this phase
      * @param id The unique identifier for this loading phase
      * @param label The human-readable label for this loading phase
+     * @param _onError Callback to invoke when the phase fails
      * @ignore
      */
-    constructor(_phaseTracker: LoadingPhaseTracker, id: string, label: string);
+    constructor(_phaseTracker: LoadingPhaseTracker, id: string, label: string, _onError?: ((error: Error | string) => void) | undefined);
     report(progress: number): void;
     complete(): void;
-    fail(_error?: Error): void;
+    fail(error?: Error | string): void;
     track<T>(task: Promise<T> | (() => Promise<T> | T)): Promise<T>;
 }

package/dist/types/textmode/loading/LoadingScreenManager.d.ts

@@ -75,7 +75,7 @@ export declare class LoadingScreenManager {
      *
      * // In setup we can start a phase and read the overall progress
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('assets', 1);
+     *   const phase = t.loading.addPhase('assets', 1);
      *   phase.report(0.5); // half complete for the phase
      *
      *   // The `progress` accessor reports the global progress across all phases
@@ -101,7 +101,7 @@ export declare class LoadingScreenManager {
      *   // Update the message visible on the loading screen
      *   t.loading.message('preloading video...');
      *
-     *   // Read the current message (useful in custom renderers)
+     *   // Read the current message (useful in custom loading screen implementations)
      *   const msg = t.loading.message();
      *   console.log(msg);
      * });
@@ -128,7 +128,7 @@ export declare class LoadingScreenManager {
      *
      * // In setup we start a phase and then track work in that phase
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('video preload', 2);
+     *   const phase = t.loading.addPhase('video preload', 2);
      *
      *   // Example: report progress from a loader callback
      *   await phase.track(async () => {
@@ -168,7 +168,7 @@ export declare class LoadingScreenManager {
      * });
      *
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('remote fetch', 1);
+     *   const phase = t.loading.addPhase('remote fetch', 1);
      *   try {
      *     await phase.track(async () => {
      *       // Failing call

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

@@ -164,7 +164,7 @@ export interface ILoadingPhase {
      *
      * // Create a phase and report progress as work proceeds
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('assets', 1);
+     *   const phase = t.loading.addPhase('assets', 1);
      *   phase.report(0.25);
      *   // ...load assets...
      *   phase.report(0.75);
@@ -181,7 +181,7 @@ export interface ILoadingPhase {
      * const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'prepping...' } });
      *
      * t.setup(() => {
-     *   const phase = t.loading.beginPhase('init', 1);
+     *   const phase = t.loading.addPhase('init', 1);
      *   // Finish phase when work is done
      *   phase.complete();
      * });
@@ -190,14 +190,18 @@ export interface ILoadingPhase {
     complete(): void;
     /**
      * Mark the loading phase as failed.
-     * @param error An optional error object describing the failure.
+     *
+     * This will put the loading manager into an error state, displaying the
+     * error on the loading screen.
+     *
+     * @param error An optional error object or message describing the failure.
      *
      * @example
      * ```ts
      * const t = textmode.create({ width: 800, height: 600 });
      *
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('fetch', 1);
+     *   const phase = t.loading.addPhase('fetch', 1);
      *   try {
      *     // simulate failure
      *     throw new Error('network error');
@@ -207,7 +211,7 @@ export interface ILoadingPhase {
      * });
      * ```
      */
-    fail(error?: Error): void;
+    fail(error?: Error | string): void;
     /**
      * Track a task within this loading phase.
      * @param task A promise or function representing the task to track.
@@ -218,7 +222,7 @@ export interface ILoadingPhase {
      * const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'loading...' } });
      *
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('video', 2);
+     *   const phase = t.loading.addPhase('video', 2);
      *   await phase.track(async () => {
      *     // do async work and report updates
      *     for (let i = 0; i <= 10; i++) {