textmode.js 0.7.1 → 0.8.0-beta.2

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

@@ -1,9 +1,8 @@
 import type { GLRenderer } from '../../../rendering/webgl/core/Renderer';
 import type { Material } from '../../../rendering/webgl/materials/Material';
-import type { TextmodeFont } from '../font/TextmodeFont';
 import { TextmodeSource } from '../TextmodeSource';
-import type { TextmodeVideoOptions } from './types';
-export type { TextmodeVideoOptions, TextmodeVideoPreloadStrategy, TextmodeVideoPreloadProgress, TextmodeVideoPreloadComplete, } from './types';
+import type { ITextmodeVideo } from './ITextmodeVideo';
+import type { TextmodeConversionManager } from '../../conversion';
 /**
  * Represents a video element for textmode rendering via {@link Textmodifier.loadVideo}.
  *
@@ -11,7 +10,7 @@ export type { TextmodeVideoOptions, TextmodeVideoPreloadStrategy, TextmodeVideoP
  *
  * A video uploaded currently runs through an adjustable brightness-converter that converts
  * the video frames into a textmode representation using characters.
- * Those adjustable options are available via chainable methods on this class.
+ * Those adjustable options are available via chainable methods on this interface.
  * ```javascript
  * const t = textmode.create({
  *     width: 800,
@@ -41,158 +40,56 @@ export type { TextmodeVideoOptions, TextmodeVideoPreloadStrategy, TextmodeVideoP
  * });
  * ```
  */
-export declare class TextmodeVideo extends TextmodeSource {
+export declare class TextmodeVideo extends TextmodeSource implements ITextmodeVideo {
     private _videoElement;
-    private _currentFrameIndex;
-    private _preloader;
     /**
-     * Create a new TextmodeVideo instance.
-     * @param gl WebGL2 rendering context
+     * Create a TextmodeVideo from an HTML video element.
+     * @param gl WebGL context
      * @param renderer GLRenderer instance
-     * @param texture WebGL texture for video frames
-     * @param videoElement The HTML video element
-     * @param originalWidth Original video width in pixels
-     * @param originalHeight Original video height in pixels
-     * @param gridCols Number of columns in the grid (for auto-sizing)
-     * @param gridRows Number of rows in the grid (for auto-sizing)
-     *
-     * @ignore
+     * @param texture WebGL texture
+     * @param conversionManager Conversion manager
+     * @param videoElement HTMLVideoElement source
+     * @param originalWidth Original width of the video
+     * @param originalHeight Original height of the video
+     * @param gridCols Grid columns
+     * @param gridRows Grid rows
      */
-    constructor(gl: WebGL2RenderingContext, renderer: GLRenderer, texture: WebGLTexture, font: TextmodeFont, videoElement: HTMLVideoElement, originalWidth: number, originalHeight: number, gridCols: number, gridRows: number);
+    private constructor();
     /**
-     * Dispose of GPU resources and cleanup video element.
+     * Dispose of this TextmodeVideo and free its resources.
      * @ignore
      */
     $dispose(): void;
-    /**
-     * Update the texture with the current video frame if needed.
-     * For preloaded videos, this returns the appropriate frame texture.
-     * For live videos, this updates the texture with current video data.
-     * @ignore
-     */
     $updateTexture(): void;
-    /**
-     * Get the active texture for the current frame.
-     * For preloaded videos, returns the texture at the current frame index.
-     * For live videos, returns the live texture.
-     * @ignore
-     */
     protected $getActiveTexture(): WebGLTexture;
     /**
      * Get or create the material for rendering this video.
      * Always updates the material to ensure the latest video frame is used.
+     * @returns Material
      * @ignore
      */
     $getMaterial(): Material;
     protected $beforeMaterialUpdate(): void;
     /**
-     * For preloaded videos, set or get the current frame index.
-     * When called without arguments, returns this video instance for use with t.image().
-     * When called with an index, sets the frame and returns this instance.
-     *
-     * The frame index automatically wraps using modulo, so you can pass t.frameCount directly
-     * and it will loop through the video frames seamlessly.
-     *
-     * For non-preloaded videos, this method does nothing and returns the instance.
-     *
-     * @param index Optional frame index to set (0-based, automatically wraps)
-     * @returns This instance for chaining.
-     *
-     * @example
-     * ```javascript
-     * // Draw specific frame
-     * t.image(video.frame(0), x, y);
-     *
-     * // Draw frame based on frameCount (automatically wraps)
-     * t.image(video.frame(t.frameCount), x, y);
-     *
-     * video.frame(t.frameCount);
-     * t.image(video, x, y);
-     * ```
-     */
-    frame(index?: number): this;
-    /**
-     * Create a TextmodeVideo instance from a video source (URL or HTMLVideoElement).
+     * Create a TextmodeVideo from a video URL.
      * @param renderer GLRenderer instance
-     * @param source Video URL string or HTMLVideoElement
-     * @param gridCols Number of columns in the grid
-     * @param gridRows Number of rows in the grid
-     * @param options Optional preload configuration (frameRate, onProgress, onComplete, onError).
-     * @returns Promise resolving to TextmodeVideo instance
+     * @param conversionManager Conversion manager
+     * @param source Video URL
+     * @param gridCols Number of grid columns
+     * @param gridRows Number of grid rows
+     * @returns Promise resolving to a TextmodeVideo instance
      * @ignore
      */
-    static $fromSource(renderer: GLRenderer, font: TextmodeFont, source: string, gridCols: number, gridRows: number, options?: TextmodeVideoOptions): Promise<TextmodeVideo>;
-    /**
-     * Play the video.
-     * @returns Promise that resolves when playback starts
-     */
+    static $fromSource(renderer: GLRenderer, conversionManager: TextmodeConversionManager, source: string, gridCols: number, gridRows: number): Promise<TextmodeVideo>;
     play(): Promise<void>;
-    /**
-     * Pause the video.
-     */
     pause(): void;
-    /**
-     * Stop the video and reset to beginning.
-     */
     stop(): void;
-    /**
-     * Set the playback speed.
-     * @param rate Playback rate (1.0 = normal speed)
-     */
     speed(rate: number): this;
-    /**
-     * Set whether the video should loop.
-     * @param shouldLoop Whether to loop (defaults to true)
-     */
     loop(shouldLoop?: boolean): this;
-    /**
-     * Set the current time position in the video.
-     * @param seconds Time in seconds
-     */
     time(seconds: number): this;
-    /**
-     * Set the volume.
-     * @param level Volume level (0.0-1.0)
-     */
     volume(level: number): this;
-    /**
-     * WebGL texture handle containing the current video frame.
-     */
-    get texture(): WebGLTexture;
-    /**
-     * Ideal width to draw the video at (in grid cells), calculated to fit the grid while preserving aspect ratio.
-     */
-    get width(): number;
-    /**
-     * Ideal height to draw the video at (in grid cells), calculated to fit the grid while preserving aspect ratio.
-     */
-    get height(): number;
-    /**
-     * Original pixel width of the video.
-     */
-    get originalWidth(): number;
-    /**
-     * Original pixel height of the video.
-     */
-    get originalHeight(): number;
-    /**
-     * The underlying HTML video element.
-     */
     get videoElement(): HTMLVideoElement;
-    /**
-     * Current playback time in seconds.
-     */
     get currentTime(): number;
-    /**
-     * Total duration of the video in seconds.
-     */
     get duration(): number;
-    /**
-     * Whether the video is currently playing.
-     */
     get isPlaying(): boolean;
-    /**
-     * Total number of preloaded frames. Returns 0 for non-preloaded videos.
-     */
-    get totalFrames(): number;
 }

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

@@ -0,0 +1,26 @@
+import type { LoadingPhaseTracker } from "./LoadingPhaseTracker";
+import type { ILoadingPhase } from "./types";
+/**
+ * Represents a loading phase tracked by a LoadingPhaseTracker.
+ *
+ * Allows reporting progress, completion, and failure of the phase.
+ *
+ * Also provides a method to track asynchronous tasks within the phase.
+ */
+export declare class LoadingPhase implements ILoadingPhase {
+    private readonly _phaseTracker;
+    readonly id: string;
+    readonly label: string;
+    /**
+     * 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
+     * @ignore
+     */
+    constructor(_phaseTracker: LoadingPhaseTracker, id: string, label: string);
+    report(progress: number): void;
+    complete(): void;
+    fail(_error?: Error): void;
+    track<T>(task: Promise<T> | (() => Promise<T> | T)): Promise<T>;
+}

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

@@ -1,6 +1,7 @@
 import type { Textmodifier } from '../Textmodifier';
 import type { RGBA } from '../utils/cssColor';
-import type { LoadingPhaseHandle, LoadingScreenOptions } from './types';
+import { LoadingPhase } from './LoadingPhase';
+import type { LoadingScreenOptions } from './types';
 /**
  * Manages the loading screen display and state. Can be accessed via {@link Textmodifier.loading}.
  */
@@ -11,11 +12,8 @@ export declare class LoadingScreenManager {
     private readonly _phaseTracker;
     private readonly _transition;
     private readonly _loadingAnimationController;
-    private _loadingFont;
-    private _loadingGrid;
-    private _loadingDrawFramebuffer;
-    private _loadingFramebuffer;
-    private _renderer;
+    private _loadingLayer;
+    private _customRenderer;
     private _palette;
     private _theme;
     private _startTime;
@@ -31,12 +29,12 @@ export declare class LoadingScreenManager {
      */
     constructor(textmodifier: Textmodifier, opts: LoadingScreenOptions | undefined, canvasBackground: RGBA | null);
     /**
-     * Initialize loading screen resources (font, grid, framebuffers).
+     * Initialize loading screen resources using a TextmodeLayer.
      * Must be called after the renderer is ready.
      * @param fontSource Optional font source for the loading screen
      * @ignore
      */
-    $initialize(fontSource?: string): Promise<void>;
+    $initialize(): Promise<void>;
     /**
      * Indicates whether the loading screen should render this frame.
      * @ignore
@@ -55,7 +53,7 @@ export declare class LoadingScreenManager {
     $stop(): void;
     /**
      * Handle canvas resize during loading.
-     * Updates grid and framebuffers to match new canvas dimensions.
+     * Delegates to the loading layer which handles grid and framebuffer resizing.
      * @ignore
      */
     $resize(): void;
@@ -66,84 +64,84 @@ export declare class LoadingScreenManager {
     $dispose(): void;
     /**
      * Get the current overall loading progress (0-1).
-    *
-    * @example
-    * ```javascript
-    * 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)}%`);
-    * });
-    * ```
+     *
+     * @example
+     * ```javascript
+     * 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
-    * ```javascript
-    * 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);
-    * });
-    * ```
+     *
+     * @example
+     * ```javascript
+     * 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,
+     * With the returned {@link LoadingPhase} 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
-    * ```javascript
-    * 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;
+     *
+     * @example
+     * ```javascript
+     * 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): LoadingPhase;
     /**
      * Finish the loading process.
      * @ignore
@@ -160,28 +158,28 @@ export declare class LoadingScreenManager {
     /**
      * Report an error that occurred during loading.
      * @param error The error message or `Error` object.
-    *
-    * @example
-    * ```javascript
-    * 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));
-    *   }
-    * });
-    * ```
+     *
+     * @example
+     * ```javascript
+     * 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;
     /**

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

@@ -2,5 +2,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';
+export { $resolveTheme as resolveTheme, $resolveDefaultPalette as resolveDefaultPalette, $resolveColorInputs as resolveColorInputs, } from './LoadingScreenTheme';
+export { LoadingPhase } from './LoadingPhase';
+export type { LoadingPhaseSnapshot, LoadingScreenOptions, LoadingScreenRendererContext, LoadingScreenTheme, LoadingScreenState, } from './types';

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

@@ -145,7 +145,7 @@ export type LoadingScreenRenderer = (context: LoadingScreenRendererContext) => v
 /**
  * Handle for managing a loading phase.
  */
-export interface LoadingPhaseHandle {
+export interface ILoadingPhase {
     /**
      * The unique identifier of the loading phase.
      */
@@ -157,77 +157,77 @@ export interface LoadingPhaseHandle {
     /**
      * 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();
-    * });
-    * ```
+     *
+     * @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();
-    * });
-    * ```
+     *
+     * @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));
-    *   }
-    * });
-    * ```
+     *
+     * @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));
-    *     }
-    *   });
-    * });
-    * ```
+     *
+     * @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>;
 }