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

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

@@ -0,0 +1,6 @@
+export { LoadingScreenManager } from './LoadingScreenManager';
+export { LoadingPhaseTracker } from './LoadingPhaseTracker';
+export { LoadingScreenStateMachine } from './LoadingScreenState';
+export { LoadingScreenTransition } from './LoadingScreenTransition';
+export { $resolveTheme as resolveTheme, $resolveDefaultPalette as resolveDefaultPalette, $resolveColorInputs as resolveColorInputs } from './LoadingScreenTheme';
+export type { LoadingPhaseSnapshot, LoadingScreenOptions, LoadingScreenRendererContext, LoadingPhaseHandle, LoadingScreenTheme, LoadingScreenState } from './types';

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

@@ -0,0 +1,2 @@
+import type { LoadingScreenRendererContext } from '../types';
+export declare const spinnerTemplate: (context: LoadingScreenRendererContext) => void;

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

@@ -0,0 +1 @@
+export { spinnerTemplate } from './SpinnerTemplate';

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

@@ -0,0 +1,251 @@
+import type { TextmodeGrid } from '../Grid';
+import type { Textmodifier } from '../Textmodifier';
+import type { TextmodeColor } from '../TextmodeColor';
+/**
+ * Snapshot of a loading phase's state.
+ */
+export interface LoadingPhaseSnapshot {
+    /** The unique identifier of the loading phase. */
+    id: string;
+    /** The label or name of the loading phase. */
+    label: string;
+    /**
+     * The weight of this phase for calculating overall progress.
+     */
+    weight: number;
+    /** The progress of the loading phase, represented as a number between 0 and 1. */
+    progress: number;
+    /** The current status of the loading phase. */
+    status: 'pending' | 'running' | 'complete' | 'failed';
+}
+/**
+ * Options for configuring the loading screen.
+ *
+ * @example
+ * ```js
+ * const tm = textmode.create({
+ *  width: 800,
+ *  height: 600,
+ *  loadingScreen: {
+ *    message: 'booting...',
+ *  }
+ * });
+ * ```
+ */
+export interface LoadingScreenOptions {
+    /**
+     * Message to display on the loading screen.  Default is `'loading...'`.
+     */
+    message?: string;
+    /**
+     * Color tone of the loading screen. Can be 'auto', 'light', or 'dark'. Default is 'auto'.
+     * <br/><br/>
+     * Based on the background color the `textmode.js` canvas is rendered on, the loading screen
+     * will automatically choose a light or dark theme when set to `'auto'`.
+     */
+    tone?: 'auto' | 'light' | 'dark';
+    /**
+     * Provides a custom renderer function for the loading screen,
+     * overriding the default loading screen. The `context` parameter is a {@link LoadingScreenRendererContext} object.
+     */
+    renderer?: (context: LoadingScreenRendererContext) => void;
+    /**
+     * Type of transition effect. Default is `'fade'`.
+     */
+    transition?: 'none' | 'fade';
+    /**
+     * Duration of the transition effect in milliseconds. Default is `500`ms.
+     */
+    transitionDuration?: number;
+}
+/**
+ * Context object passed to a loading screen renderer function.
+ *
+ * Can be used to create a custom loading screen to fit your needs.
+ *
+ * @example
+ * ```ts
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   loadingScreen: {
+ *     message: 'loading...',
+ *     renderer: (ctx) => {
+ *       const { textmodifier: tm, grid, progress, message, transitionOpacity } = ctx;
+ *
+ *       // Clear the screen
+ *       tm.background(0, 0, 0, Math.floor(transitionOpacity * 255));
+ *
+ *       // Position at top-left corner
+ *       const x = -Math.floor(grid.cols / 2) + 2;
+ *       const y = -Math.floor(grid.rows / 2) + 2;
+ *
+ *       tm.push();
+ *       tm.translate(x, y, 0);
+ *       tm.charColor(255, 255, 255, transitionOpacity * 255);
+ *
+ *       // Display message
+ *       if (message) {
+ *         for (let i = 0; i < message.length; i++) {
+ *           tm.char(message[i]);
+ *           tm.rect(1, 1);
+ *           tm.translateX(1);
+ *         }
+ *       }
+ *
+ *       // Display progress bar
+ *       tm.translate(-message.length, 2, 0);
+ *       const barWidth = 20;
+ *       const filled = Math.floor(progress * barWidth);
+ *
+ *       for (let i = 0; i < barWidth; i++) {
+ *         tm.char(i < filled ? '=' : '-');
+ *         tm.rect(1, 1);
+ *         tm.translateX(1);
+ *       }
+ *
+ *       tm.pop();
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export interface LoadingScreenRendererContext {
+    /** The Textmodifier instance for rendering text and graphics. */
+    textmodifier: Textmodifier;
+    /** The TextmodeGrid representing the screen grid. */
+    grid: TextmodeGrid;
+    /** The current loading progress (0-1). */
+    progress: number;
+    /** The elapsed time since the loading started, in milliseconds. */
+    elapsedMs: number;
+    /** The number of frames rendered since the loading started. */
+    frameCount: number;
+    /** The current loading message, if any. */
+    message?: string;
+    /** The palette of colors available for rendering based on the `theme`. */
+    palette: TextmodeColor[];
+    /** The current theme of the loading screen. */
+    theme: LoadingScreenTheme;
+    /** The phases of the loading process. */
+    phases: LoadingPhaseSnapshot[];
+    /** The opacity level for transition effects. */
+    transitionOpacity: number;
+    /** Indicates if the loading screen is in an error state. */
+    isError: boolean;
+    /** The error message to display, if any. */
+    errorMessage?: string;
+    /** Detailed error information, if any. */
+    errorDetails?: string;
+}
+/**
+ * A function that renders the loading screen.
+ */
+export type LoadingScreenRenderer = (context: LoadingScreenRendererContext) => void;
+/**
+ * Handle for managing a loading phase.
+ */
+export interface LoadingPhaseHandle {
+    /**
+     * The unique identifier of the loading phase.
+     */
+    id: string;
+    /**
+     * The label or name of the loading phase.
+     */
+    label: string;
+    /**
+     * Update the progress of the loading phase.
+     * @param progress A number between 0 and 1 representing the phase's progress.
+    *
+    * @example
+    * ```ts
+    * const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'prepping...' } });
+    *
+    * // Create a phase and report progress as work proceeds
+    * t.setup(async () => {
+    *   const phase = t.loading.beginPhase('assets', 1);
+    *   phase.report(0.25);
+    *   // ...load assets...
+    *   phase.report(0.75);
+    *   phase.complete();
+    * });
+    * ```
+     */
+    report(progress: number): void;
+    /**
+     * Mark the loading phase as complete.
+    *
+    * @example
+    * ```ts
+    * const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'prepping...' } });
+    *
+    * t.setup(() => {
+    *   const phase = t.loading.beginPhase('init', 1);
+    *   // Finish phase when work is done
+    *   phase.complete();
+    * });
+    * ```
+     */
+    complete(): void;
+    /**
+     * Mark the loading phase as failed.
+     * @param error An optional error object describing the failure.
+    *
+    * @example
+    * ```ts
+    * const t = textmode.create({ width: 800, height: 600 });
+    *
+    * t.setup(async () => {
+    *   const phase = t.loading.beginPhase('fetch', 1);
+    *   try {
+    *     // simulate failure
+    *     throw new Error('network error');
+    *   } catch (err) {
+    *     phase.fail(err instanceof Error ? err : String(err));
+    *   }
+    * });
+    * ```
+     */
+    fail(error?: Error): void;
+    /**
+     * Track a task within this loading phase.
+     * @param task A promise or function representing the task to track.
+     * @returns A promise that resolves with the task's result.
+    *
+    * @example
+    * ```ts
+    * const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'loading...' } });
+    *
+    * t.setup(async () => {
+    *   const phase = t.loading.beginPhase('video', 2);
+    *   await phase.track(async () => {
+    *     // do async work and report updates
+    *     for (let i = 0; i <= 10; i++) {
+    *       phase.report(i / 10);
+    *       await new Promise((r) => setTimeout(r, 30));
+    *     }
+    *   });
+    * });
+    * ```
+     */
+    track<T>(task: Promise<T> | (() => Promise<T> | T)): Promise<T>;
+}
+/**
+ * Theme settings for the loading screen.
+ */
+export interface LoadingScreenTheme {
+    /** The color mode of the loading screen, either 'light' or 'dark'. */
+    mode: 'light' | 'dark';
+    /** The background color of the loading screen, or null for transparent. */
+    background: [number, number, number, number] | null;
+    /** The primary text color used on the loading screen. */
+    textColor: number | string | TextmodeColor;
+    /** The subtle text color used on the loading screen. */
+    subtleColor: number | string | TextmodeColor;
+}
+/**
+ * The state of the loading screen.
+ * @ignore
+ */
+export type LoadingScreenState = 'disabled' | 'active' | 'done' | 'transitioning' | 'error';

package/dist/types/textmode/managers/KeyboardManager.d.ts

@@ -39,7 +39,7 @@ export interface KeyState {
  * Manages all keyboard interaction for a Textmodifier instance.
  * Handles event listeners, key state tracking, and event dispatching.
  *
- * Provides p5.js-like keyboard functionality including:
+ * Provides keyboard functionality including:
  * - keyPressed() and keyReleased() callbacks
  * - Current key state tracking
  * - Special key handling (arrows, function keys, etc.)
@@ -56,7 +56,6 @@ export declare class KeyboardManager {
     private _keyPressedCallback?;
     private _keyReleasedCallback?;
     private readonly _specialKeyMap;
-    constructor();
     /**
      * Setup keyboard event listeners.
      */
@@ -119,7 +118,7 @@ export declare class KeyboardManager {
      */
     private _handleKeyUp;
     /**
-     * Normalize key names for consistency (map to p5.js-like constants where applicable)
+     * Normalize key names for consistency
      */
     private _normalizeKey;
 }

package/dist/types/textmode/managers/MouseManager.d.ts

@@ -89,7 +89,7 @@ export declare class MouseManager {
      * This is useful when grid dimensions change (font size, window resize, etc.)
      * and we need to recalculate the mouse coordinates without waiting for a mouse event.
      */
-    $updatePosition(): void;
+    $updatePositions(): void;
     /**
      * Set a callback function that will be called when the mouse is clicked.
      * @param callback The function to call when the mouse is clicked

package/dist/types/textmode/{plugins → managers}/PluginManager.d.ts

@@ -1,11 +1,14 @@
 import type { Textmodifier } from '../Textmodifier';
-import type { GLRenderer } from '../../rendering/webgl/Renderer';
+import type { GLRenderer } from '../../rendering/webgl/core/Renderer';
 import type { GLFramebuffer } from '../../rendering';
-import type { TextmodeFont } from '../font';
+import type { TextmodeFont } from '../loadables/font';
 import type { TextmodeGrid } from '../Grid';
 import type { TextmodeCanvas } from '../Canvas';
 export type TextmodePluginHook = () => void;
-export interface TextmodePluginContext {
+/**
+ * An extended API provided to plugins when they are installed on a {@link Textmodifier} instance.
+ */
+export interface TextmodePluginAPI {
     /** The WebGL renderer used by the Textmodifier instance. */
     renderer: GLRenderer;
     /** The font used by the Textmodifier instance. */
@@ -14,23 +17,17 @@ export interface TextmodePluginContext {
     grid: TextmodeGrid;
     /** The canvas used by the Textmodifier instance. */
     canvas: TextmodeCanvas;
-    /** The framebuffer the user draws to. */
+    /** The framebuffer the user draws to with 3 render targets. */
     drawFramebuffer: GLFramebuffer;
-    /** The framebuffer containing the ASCII representation. */
+    /** The framebuffer containing the ASCII representation.<br/>
+     * This framebuffer only has a single render target. */
     asciiFramebuffer: GLFramebuffer;
-    /** Immediately execute any pending draw commands. */
-    flushDrawCommands(): void;
-}
-/**
- * An extended API provided to plugins when they are installed on a {@link Textmodifier} instance.
- */
-export interface TextmodePluginAPI extends TextmodePluginContext {
     /**
-     * Register a callback to be invoked before each draw cycle. Happens outside of the draw framebuffer being bound.
+     * Register a callback to be invoked before each draw cycle. Happens just before the draw framebuffer is being bound.
      */
     registerPreDrawHook(callback: () => void): () => void;
     /**
-     * Register a callback to be invoked after each draw cycle. Happens outside of the draw framebuffer being bound.
+     * Register a callback to be invoked after each draw cycle. Happens outside of the draw framebuffer being bound after the final result is drawn to the screen.
      */
     registerPostDrawHook(callback: () => void): () => void;
 }
@@ -38,6 +35,11 @@ export interface TextmodePluginAPI extends TextmodePluginContext {
  * A plugin interface for extending the functionality of a {@link Textmodifier} instance.
  *
  * Users can create plugins by implementing this interface.
+ *
+ * @note
+ * Plugins are currently experimental and the API may change in future releases.
+ * For now, it has been integrated to outsource export features to `textmode.export.js`.
+ * Documentation and examples will be provided as the plugin system matures.
  */
 export interface TextmodePlugin {
     /** Unique name for the plugin. */
@@ -66,8 +68,8 @@ export declare class TextmodePluginManager {
     constructor(textmodifier: Textmodifier);
     $installMany(plugins: TextmodePlugin[]): Promise<void>;
     $unuse(pluginName: string): Promise<void>;
-    runPreDrawHooks(): void;
-    runPostDrawHooks(): void;
+    $runPreDrawHooks(): void;
+    $runPostDrawHooks(): void;
     $disposeAll(): Promise<void>;
     private _createAPI;
     private _registerHook;

package/dist/types/textmode/managers/TouchManager.d.ts

@@ -220,6 +220,4 @@ export declare class TouchManager {
     private _evaluateTapAndSwipe;
     private _detectDoubleTap;
     private _cloneTouchPosition;
-    private _distance;
-    private _angle;
 }

package/dist/types/textmode/mixins/AnimationMixin.d.ts

@@ -1,128 +1,8 @@
 import type { Mixin } from './TextmodifierMixin';
-/**
- * Interface for animation capabilities that will be mixed into Textmodifier
- */
-export interface AnimationCapabilities {
-    /**
-     * Set the maximum frame rate. If called without arguments, returns the current measured frame rate.
-     * @param fps The maximum frames per second for rendering.
-     *
-     * @example
-     * ```javascript
-     * // Create a Textmodifier instance
-     * const textmodifier = textmode.create();
-     *
-     * // Set the maximum frame rate to 30 FPS
-     * textmodifier.frameRate(30);
-     * ```
-     */
-    frameRate(fps?: number): number | void;
-    /**
-     * Stop the automatic rendering loop.
-     *
-     * This method pauses the render loop without, allowing
-     * it to be resumed later with {@link loop}. This is useful for temporarily pausing
-     * animation while maintaining the ability to continue it.
-     *
-     * @example
-     * ```javascript
-     * // Create a textmodifier instance in auto mode
-     * const textmodifier = textmode.create();
-     *
-     * // The render loop is running by default
-     * console.log(textmodifier.isLooping()); // true
-     *
-     * // Stop the automatic rendering loop
-     * textmodifier.noLoop();
-     * console.log(textmodifier.isLooping()); // false
-     *
-     * // Resume the rendering loop
-     * textmodifier.loop();
-     * console.log(textmodifier.isLooping()); // true
-     * ```
-     */
-    noLoop(): void;
-    /**
-     * Resume the rendering loop if it was stopped by {@link noLoop}.
-     *
-     * @example
-     * ```javascript
-     * // Create a textmodifier instance
-     * const textmodifier = textmode.create();
-     *
-     * // Stop the loop
-     * textmodifier.noLoop();
-     *
-     * // Resume the loop
-     * textmodifier.loop();
-     *
-     * // You can also use this pattern for conditional animation
-     * if (someCondition) {
-     *   textmodifier.loop();
-     * } else {
-     *   textmodifier.noLoop();
-     * }
-     * ```
-     */
-    loop(): void;
-    /**
-     * Execute the render function a specified number of times.
-     *
-     * This method is useful when the render loop has been stopped with {@link noLoop},
-     * allowing you to trigger rendering on demand.
-     *
-     * @param n The number of times to execute the render function. Defaults to 1.
-     *
-     * @example
-     * ```javascript
-     * // Create a textmodifier instance
-     * const textmodifier = textmode.create();
-     *
-     * // Set up drawing
-     * textmodifier.draw(() => {
-     *   textmodifier.background(0);
-     *
-     *   textmodifier.char("A");
-     *   textmodifier.charColor(255, 0, 0);
-     *   textmodifier.rect(10, 10, 50, 50);
-     * });
-     *
-     * textmodifier.noLoop();
-     * textmodifier.redraw(3); // Render 3 times despite loop being stopped
-     * ```
-     */
-    redraw(n?: number): void;
-    /**
-     * Check whether the textmodifier is currently running the automatic render loop.
-     * @returns True if the render loop is currently active, false otherwise.
-     *
-     * @example
-     * ```javascript
-     * const textmodifier = textmode.create(canvas);
-     *
-     * // Check loop status in different states
-     * console.log(textmodifier.isLooping()); // true (looping)
-     *
-     * textmodifier.noLoop();
-     * console.log(textmodifier.isLooping()); // false (not looping)
-     *
-     * textmodifier.loop();
-     * console.log(textmodifier.isLooping()); // true (alooping)
-     * ```
-     */
-    isLooping(): boolean;
-    /**
-     * Get the current frame count.
-     */
-    get frameCount(): number;
-    /**
-     * Set the current frame count.
-     */
-    set frameCount(value: number);
-}
+import type { IAnimationMixin } from './interfaces/IAnimationMixin';
 /**
  * Mixin that adds animation capabilities to a class
  * @param Base The base class to extend
  * @returns Extended class with animation capabilities
  */
-export declare const AnimationMixin: Mixin<AnimationCapabilities>;
+export declare const AnimationMixin: Mixin<IAnimationMixin>;

package/dist/types/textmode/mixins/FontMixin.d.ts

@@ -1,83 +1,8 @@
 import type { Mixin } from './TextmodifierMixin';
-/**
- * Interface for font capabilities that will be mixed into Textmodifier
- */
-export interface FontCapabilities {
-    /**
-     * Update the font used for rendering.
-     * @param fontSource The URL of the font to load.
-     *
-     * @example
-     * ```javascript
-     * // Create a Textmodifier instance
-     * const textmodifier = textmode.create();
-     *
-     * // Load a custom font from a URL
-     * await textmodifier.loadFont('https://example.com/fonts/myfont.ttf');
-     *
-     * // Local font example
-     * // await textmodifier.loadFont('./fonts/myfont.ttf');
-     * ```
-     */
-    loadFont(fontSource: string): Promise<void>;
-    /**
-     * Set the font size used for rendering.
-     * @param size The font size to set.
-     *
-     * @example
-     * ```javascript
-     * // Create a Textmodifier instance
-     * const textmodifier = textmode.create();
-     *
-     * // Set the font size to 32
-     * textmodifier.fontSize(32);
-     * ```
-     */
-    fontSize(size: number): void;
-    /**
-     * Get the RGB shader color of a specific character in the current font.
-     *
-     * Useful for custom shaders to control the character to render.
-     *
-     * @param char The character to get the color for.
-     * @returns An array representing the RGB color, or null if the character is not found.
-     * @example
-     * ```javascript
-     * // Create a Textmodifier instance
-     * const textmodifier = textmode.create();
-     *
-     * // Get the color of the character 'A'
-     * textmodifier.setup(() => {
-     *   const color = textmodifier.glyphColor('A');
-     *   console.log(color); // e.g., [1, 0, 0] for red
-     * });
-     * ```
-     */
-    glyphColor(char: string): [number, number, number] | null;
-    /**
-     * Get the RGB shader colors of all characters in a string for the current font.
-     *
-     * Useful for custom shaders to control the characters to render.
-     *
-     * @param str The string to get the colors for.
-     * @returns An array of RGB color arrays, or null if a character is not found.
-     * @example
-     * ```javascript
-     * // Create a Textmodifier instance
-     * const textmodifier = textmode.create();
-     *
-     * // Get the colors of the string 'Hello'
-     * textmodifier.setup(() => {
-     *   const colors = textmodifier.glyphColors('Hello');
-     *   console.log(colors); // e.g., [[0.1, 0, 0], ...]
-     * });
-     * ```
-     */
-    glyphColors(str: string): ([number, number, number] | null)[];
-}
+import type { IFontMixin } from './interfaces/IFontMixin';
 /**
  * Mixin that adds font capabilities to a class
  * @param Base The base class to extend
  * @returns Extended class with font capabilities
  */
-export declare const FontMixin: Mixin<FontCapabilities>;
+export declare const FontMixin: Mixin<IFontMixin>;

package/dist/types/textmode/mixins/KeyboardMixin.d.ts

@@ -1,95 +1,13 @@
 import type { Mixin } from './TextmodifierMixin';
-import type { KeyboardEventHandler } from '../managers/KeyboardManager';
-/**
- * Capabilities provided by the KeyboardMixin
- */
-export interface KeyboardCapabilities {
-    /**
-     * Check if a specific key is currently being pressed.
-     *
-     * @param key The key to check (e.g., 'a', 'Enter', 'ArrowLeft')
-     * @returns true if the key is currently pressed, false otherwise
-     *
-     * @example
-     * ```javascript
-     * const t = textmode.create({ width: 800, height: 600 });
-     *
-     * let playerX = 0;
-     * let playerY = 0;
-     *
-     * t.draw(() => {
-     *   t.background(0);
-     *
-     *   // Check for arrow keys to move a character
-     *   if (t.isKeyPressed('ArrowUp')) {
-     *     playerY -= 1;
-     *   }
-     *   if (t.isKeyPressed('ArrowDown')) {
-     *     playerY += 1;
-     *   }
-     *   if (t.isKeyPressed('ArrowLeft')) {
-     *     playerX -= 1;
-     *   }
-     *   if (t.isKeyPressed('ArrowRight')) {
-     *     playerX += 1;
-     *   }
-     *
-     *   // Draw player character
-     *   t.char('@');
-     *   t.charColor(255, 255, 0);
-     *   t.point(playerX, playerY);
-     * });
-     * ```
-     */
-    isKeyPressed(key: string): boolean;
-    /**
-     * Set a callback function that will be called when a key is pressed down.
-     *
-     * @param callback The function to call when a key is pressed
-     *
-     * @example
-     * ```javascript
-     * const t = textmode.create({ width: 800, height: 600 });
-     *
-     * t.keyPressed((data) => {
-     *   console.log(`Key pressed: ${data.key}`);
-     *   if (data.key === 'Enter') {
-     *     console.log('Enter key was pressed!');
-     *   }
-     *   if (data.ctrlKey && data.key === 's') {
-     *     console.log('Ctrl+S was pressed!');
-     *   }
-     * });
-     * ```
-     */
-    keyPressed(callback: KeyboardEventHandler): void;
-    /**
-     * Set a callback function that will be called when a key is released.
-     *
-     * @param callback The function to call when a key is released
-     *
-     * @example
-     * ```javascript
-     * const t = textmode.create({ width: 800, height: 600 });
-     *
-     * t.keyReleased((data) => {
-     *   console.log(`Key released: ${data.key}`);
-     *   if (data.key === ' ') {
-     *     console.log('Spacebar was released!');
-     *   }
-     * });
-     * ```
-     */
-    keyReleased(callback: KeyboardEventHandler): void;
-}
+import type { IKeyboardMixin } from './interfaces/IKeyboardMixin';
 /**
  * Mixin that adds keyboard interaction capabilities to Textmodifier.
  *
  * This is a thin wrapper around KeyboardManager that provides the public API
  * for keyboard interaction. All the actual implementation is handled by the
- * KeyboardManager instance in the TextmodifierContext.
+ * KeyboardManager instance in the ITextmodifier.
  *
  * Provides p5.js-like keyboard functionality including key state tracking,
  * event callbacks, and special key handling.
  */
-export declare const KeyboardMixin: Mixin<KeyboardCapabilities>;
+export declare const KeyboardMixin: Mixin<IKeyboardMixin>;