textmode.js 0.4.0 → 0.6.0-beta.1

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

@@ -0,0 +1,170 @@
+import type { Textmodifier } from '../Textmodifier';
+import type { RGBA } from '../utils/cssColor';
+import type { LoadingPhaseHandle, LoadingScreenOptions } from './types';
+/**
+ * Manages the loading screen display and state. Can be accessed via {@link Textmodifier.loading}.
+ */
+export declare class LoadingScreenManager {
+    private readonly _textmodifier;
+    private readonly _options;
+    private readonly _stateMachine;
+    private readonly _phaseTracker;
+    private readonly _transition;
+    private _renderer;
+    private _palette;
+    private _theme;
+    private _startTime;
+    /**
+     * Initializes a new LoadingScreenManager.
+     * @param textmodifier Textmodifier instance to render on.
+     * @param opts Loading screen options.
+     * @param canvasBackground Background color of the canvas.
+     * @ignore
+     */
+    constructor(textmodifier: Textmodifier, opts: LoadingScreenOptions | undefined, canvasBackground: RGBA | null);
+    /**
+     * Indicates whether the loading screen should render this frame.
+     * @ignore
+     */
+    get shouldRender(): boolean;
+    /**
+     * Get the current overall loading progress (0-1).
+    *
+    * @example
+    * ```ts
+    * const t = textmode.create({
+    *   width: 800,
+    *   height: 600,
+    *   loadingScreen: { message: 'starting...' }
+    * });
+    *
+    * // In setup we can start a phase and read the overall progress
+    * t.setup(async () => {
+    *   const phase = t.loading.beginPhase('assets', 1);
+    *   phase.report(0.5); // half complete for the phase
+    *
+    *   // The `progress` accessor reports the global progress across all phases
+    *   console.log(`Loading: ${Math.round(t.loading.progress * 100)}%`);
+    * });
+    * ```
+     */
+    get progress(): number;
+    /**
+     * Get or set the loading screen message.
+     * @param next Optional new message to set.
+     * @returns The current loading screen message.
+    *
+    * @example
+    * ```ts
+    * const t = textmode.create({
+    *   width: 800,
+    *   height: 600,
+    *   loadingScreen: { message: 'loading...' }
+    * });
+    *
+    * t.setup(() => {
+    *   // Update the message visible on the loading screen
+    *   t.loading.message('preloading video...');
+    *
+    *   // Read the current message (useful in custom renderers)
+    *   const msg = t.loading.message();
+    *   console.log(msg);
+    * });
+    * ```
+     */
+    message(next?: string): string | undefined;
+    /**
+     * Begin a new loading phase.
+     *
+     * With the returned {@link LoadingPhaseHandle} you can report progress,
+     * track asynchronous work, and manage the phase lifecycle.
+     *
+     * @param label Label for the loading phase.
+     * @param weight Weight of the loading phase (default is 1).
+     * @returns A handle to the created loading phase.
+    *
+    * @example
+    * ```ts
+    * const t = textmode.create({
+    *   width: 800,
+    *   height: 600,
+    *   loadingScreen: { message: 'preparing...' }
+    * });
+    *
+    * // In setup we start a phase and then track work in that phase
+    * t.setup(async () => {
+    *   const phase = t.loading.beginPhase('video preload', 2);
+    *
+    *   // Example: report progress from a loader callback
+    *   await phase.track(async () => {
+    *     // Simulated work
+    *     for (let i = 0; i <= 10; i++) {
+    *       phase.report(i / 10);
+    *       await new Promise((r) => setTimeout(r, 30));
+    *     }
+    *   });
+    * });
+    * ```
+     */
+    addPhase(label: string, weight?: number): LoadingPhaseHandle;
+    /**
+     * Finish the loading process.
+     * @ignore
+     */
+    finish(): void;
+    private _notifyComplete;
+    private _onCompleteCallback?;
+    /**
+     * Set a callback to be invoked when loading is complete.
+     * @param callback The callback function to invoke.
+     * @ignore
+     */
+    setOnComplete(callback: () => void): void;
+    /**
+     * Report an error that occurred during loading.
+     * @param error The error message or `Error` object.
+    *
+    * @example
+    * ```ts
+    * const t = textmode.create({
+    *   width: 800,
+    *   height: 600,
+    *   loadingScreen: { message: 'starting...' }
+    * });
+    *
+    * t.setup(async () => {
+    *   const phase = t.loading.beginPhase('remote fetch', 1);
+    *   try {
+    *     await phase.track(async () => {
+    *       // Failing call
+    *       throw new Error('server down');
+    *     });
+    *   } catch (err) {
+    *     // This will put the loading manager into an error state
+    *     t.loading.error(err instanceof Error ? err : String(err));
+    *   }
+    * });
+    * ```
+     */
+    error(error: Error | string): void;
+    /**
+     * Render a frame of the loading screen.
+     * @param frameCount Current frame count.
+     * @returns void
+     * @ignore
+     */
+    renderFrame(frameCount: number): void;
+    /**
+     * Update the background color used in the loading screen theme.
+     * @param color The new background color.
+     * @ignore
+     */
+    updateBackgroundColor(color: RGBA | null): void;
+    private _resolveRenderer;
+    /**
+     * Renders the library branding tag at the bottom left of the loading screen.
+     * Uses obfuscation techniques to make removal more difficult.
+     * @ignore
+     */
+    private _renderBrandingTag;
+}

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

@@ -0,0 +1,22 @@
+import type { LoadingScreenState } from './types';
+/**
+ * Manages the state of the loading screen.
+ * @ignore
+ */
+export declare class LoadingScreenStateMachine {
+    private _state;
+    private _errorMessage;
+    private _errorDetails;
+    constructor(initialState?: LoadingScreenState);
+    get state(): LoadingScreenState;
+    get isEnabled(): boolean;
+    get shouldRender(): boolean;
+    get errorMessage(): string;
+    get errorDetails(): string;
+    activate(): void;
+    finish(): void;
+    startTransition(): void;
+    completeTransition(): void;
+    setError(error: Error | string): void;
+    disable(): void;
+}

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

@@ -0,0 +1,26 @@
+import type { LoadingScreenTheme, LoadingScreenOptions } from './types';
+import type { Textmodifier } from '../Textmodifier';
+import type { TextmodeColor } from '../TextmodeColor';
+/**
+ * Resolves the loading screen theme based on options and background color.
+ * @param options Loading screen options.
+ * @param background Background color as RGBA or null.
+ * @returns The resolved loading screen theme.
+ * @ignore
+ */
+export declare function resolveTheme(options: LoadingScreenOptions, background: [number, number, number, number] | null): LoadingScreenTheme;
+/**
+ * Resolves the default color palette based on the theme mode.
+ * @param theme The loading screen theme.
+ * @returns An array of color strings representing the default palette.
+ * @ignore
+ */
+export declare function resolveDefaultPalette(theme: LoadingScreenTheme): string[];
+/**
+ * Resolves an array of color inputs into TextmodeColor instances.
+ * @param inputs Input colors as numbers, strings, or TextmodeColor instances.
+ * @param textmodifier The Textmodifier instance used to create TextmodeColor objects.
+ * @returns An array of TextmodeColor instances.
+ * @ignore
+ */
+export declare function resolveColorInputs(inputs: (number | string | TextmodeColor)[], textmodifier: Textmodifier): TextmodeColor[];

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

@@ -0,0 +1,17 @@
+export type TransitionType = 'none' | 'fade';
+/**
+ * Handles loading screen transitions.
+ * @ignore
+ */
+export declare class LoadingScreenTransition {
+    private _transitionStartTime;
+    private _transitionOpacity;
+    private _transitionType;
+    private _transitionDuration;
+    constructor(transitionType: TransitionType, transitionDuration: number);
+    get opacity(): number;
+    get isTransitioning(): boolean;
+    start(): void;
+    update(): boolean;
+    reset(): void;
+}

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, resolveDefaultPalette, 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. */
@@ -16,21 +19,15 @@ export interface TextmodePluginContext {
     canvas: TextmodeCanvas;
     /** The framebuffer the user draws to. */
     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;
 }
@@ -66,8 +63,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;
 }