textmode.js 0.6.0-beta.1 → 0.6.0-beta.3

package/dist/types/rendering/webgl/batching/InstanceAttributeBinder.d.ts

@@ -33,11 +33,11 @@ export declare class InstanceAttributeBinder {
      *
      * @param newCapacity New capacity in number of instances
      */
-    recreateBuffer(newCapacity: number): void;
+    $recreateBuffer(newCapacity: number): void;
     /**
      * Get the current GPU buffer capacity in instances.
      */
-    get capacity(): number;
+    get $capacity(): number;
     /**
      * Upload instance data to GPU buffer.
      *
@@ -55,7 +55,7 @@ export declare class InstanceAttributeBinder {
      * @param data Float32Array containing instance data to upload
      * @param instanceCount Number of instances in the data
      */
-    upload(data: Float32Array, instanceCount: number): void;
+    $upload(data: Float32Array, instanceCount: number): void;
     /**
      * Get cached attribute locations for a shader program.
      * Queries locations once per program and caches them for performance.
@@ -73,15 +73,15 @@ export declare class InstanceAttributeBinder {
      *
      * @param shader The shader program to bind attributes for
      */
-    bindAttributes(shader: GLShader): void;
+    $bindAttributes(shader: GLShader): void;
     /**
      * Unbind instance attributes to clean up WebGL state.
      *
      * @param shader The shader program to unbind attributes for
      */
-    unbindAttributes(shader: GLShader): void;
+    $unbindAttributes(shader: GLShader): void;
     /**
      * Dispose of WebGL resources.
      */
-    dispose(): void;
+    $dispose(): void;
 }

package/dist/types/rendering/webgl/batching/InstanceBatch.d.ts

@@ -49,15 +49,15 @@ export declare class InstanceBatch {
     /**
      * Get the current number of instances in the batch.
      */
-    get count(): number;
+    get $count(): number;
     /**
      * Check if the batch is empty.
      */
-    get isEmpty(): boolean;
+    get $isEmpty(): boolean;
     /**
      * Clear all instances from the batch.
      */
-    clear(): void;
+    $clear(): void;
     /**
      * Bind instance buffer and configure vertex attributes for instanced rendering.
      * @param shader The shader program to bind attributes for

package/dist/types/rendering/webgl/batching/InstanceBuffer.d.ts

@@ -28,14 +28,14 @@ export declare class InstanceBuffer {
      *
      * @param requiredInstances Number of instances that need to fit
      */
-    ensureCapacity(requiredInstances: number): void;
+    $ensureCapacity(requiredInstances: number): void;
     /**
      * Get write pointer for direct buffer writing.
      * Returns the current buffer and offset for zero-allocation writes.
      *
      * @returns Object containing buffer reference and current write offset
      */
-    getWritePointer(): {
+    $getWritePointer(): {
         buffer: Float32Array;
         offset: number;
     };
@@ -45,12 +45,12 @@ export declare class InstanceBuffer {
      *
      * @param floatsWritten Number of floats written (should be FLOATS_PER_INSTANCE)
      */
-    commitWrite(floatsWritten: number): void;
+    $commitWrite(floatsWritten: number): void;
     /**
      * Reset buffer to empty state.
      * Does not deallocate memory, just resets write pointer.
      */
-    reset(): void;
+    $reset(): void;
     /**
      * Get a subarray of the buffer containing used data.
      *
@@ -58,21 +58,21 @@ export declare class InstanceBuffer {
      * @param end Ending float index (default: current write position)
      * @returns Float32Array view of the specified range
      */
-    subarray(start?: number, end?: number): Float32Array;
+    $subarray(start?: number, end?: number): Float32Array;
     /**
      * Get the number of instances currently in the buffer.
      */
-    get instanceCount(): number;
+    get $instanceCount(): number;
     /**
      * Get the current buffer capacity in instances.
      */
-    get capacity(): number;
+    get $capacity(): number;
     /**
      * Get the current write index in floats.
      */
-    get writeIndex(): number;
+    get $writeIndex(): number;
     /**
      * Check if buffer is empty.
      */
-    get isEmpty(): boolean;
+    get $isEmpty(): boolean;
 }

package/dist/types/rendering/webgl/batching/InstanceWriter.d.ts

@@ -62,9 +62,9 @@ export declare class InstanceWriter {
      * @param data Instance write data
      * @returns Index of the written instance
      */
-    writeInstance(data: InstanceWriteData): number;
+    $writeInstance(data: InstanceWriteData): number;
     /**
      * Get the current number of instances written.
      */
-    get instanceCount(): number;
+    get $instanceCount(): number;
 }

package/dist/types/rendering/webgl/core/Framebuffer.d.ts

@@ -14,13 +14,13 @@ export type FramebufferOptions = {
     depth?: boolean;
 };
 /**
- * Options for creating a framebuffer.
+ * Options for creating a framebuffer. If not specified, width and height default to the current textmode grid size.
  */
 export type TextmodeFramebufferOptions = {
     /** Width of the framebuffer in grid cells */
-    width: number;
+    width?: number;
     /** Height of the framebuffer in grid cells */
-    height: number;
+    height?: number;
 };
 /**
  * Framebuffer class for managing offscreen rendering targets initialized via {@link Textmodifier.createFramebuffer}.

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

@@ -31,22 +31,18 @@ declare const Textmodifier_base: {
 export declare class Textmodifier extends Textmodifier_base implements ITextmodifier {
     _renderer: GLRenderer;
     _font: TextmodeFont;
-    _loadingFont: TextmodeFont;
     _canvas: TextmodeCanvas;
     _grid: TextmodeGrid;
-    _loadingGrid: TextmodeGrid;
     _animationController: AnimationController;
     _mouseManager: MouseManager;
     _touchManager: TouchManager;
     _keyboardManager: KeyboardManager;
+    _loading: LoadingScreenManager;
     _textmodeDrawFramebuffer: GLFramebuffer;
-    _loadingDrawFramebuffer: GLFramebuffer;
     _textmodeConversionShader: Shader;
     _textmodeFramebuffer: GLFramebuffer;
-    _loadingFramebuffer: GLFramebuffer;
     _presentShader: Shader;
     private _pluginManager;
-    _loading: LoadingScreenManager;
     private _destroyRequested;
     private _isRenderingFrame;
     private _isDisposed;
@@ -74,7 +70,6 @@ export declare class Textmodifier extends Textmodifier_base implements ITextmodi
     resizeCanvas(width: number, height: number): void;
     destroy(): void;
     private _performDestroy;
-    /** Callbacks */
     setup(callback: () => void | Promise<void>): void;
     draw(callback: () => void): void;
     windowResized(callback: () => void): void;

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

@@ -75,14 +75,16 @@ export interface ITextmodifier extends IRenderingMixin, IFontMixin, IAnimationMi
      *   const rows = textmodifier.grid.rows;
      *
      *   // Initialize any variables that depend on grid size
-     *   cellWidth = Math.floor(cols / 3);
-     *   cellHeight = Math.floor(rows / 2);
+     *   rectWidth = Math.floor(cols / 3);
+     *   rectHeight = Math.floor(rows / 2);
      * });
      *
      * // Draw callback - called every frame
      * textmodifier.draw(() => {
      *   textmodifier.background(128);
-     *   textmodifier.rect(0, 0, cellWidth, cellHeight);
+     *   textmodifier.char('A');
+     *   textmodifier.rotateZ(textmodifier.frameCount * 2);
+     *   textmodifier.rect(rectWidth, rectHeight);
      * });
      * ```
      */
@@ -123,16 +125,17 @@ export interface ITextmodifier extends IRenderingMixin, IFontMixin, IAnimationMi
      * ```javascript
      * // Create a standalone textmodifier instance
      * const t = textmode.create({
-     *  width: window.innerWidth,
-     *  height: window.innerHeight,
+     *   width: window.innerWidth,
+     *   height: window.innerHeight,
      * });
      *
      * // Draw callback to update content
      * t.draw(() => {
-     *   // Set background color
-     *   t.background(128);
-     *
-     *   t.rect(0, 0, t.grid.cols, t.grid.rows);
+     *  // Set background color
+     *  t.background(128);
+     *  t.char('A');
+     *  t.rotateZ(t.frameCount * 2);
+     *  t.rect(16, 16);
      * });
      *
      * // Set up window resize callback
@@ -140,7 +143,7 @@ export interface ITextmodifier extends IRenderingMixin, IFontMixin, IAnimationMi
      *   // Resize the canvas to match window size
      *   t.resizeCanvas(window.innerWidth, window.innerHeight);
      * });
-     *
+     * ```
      */
     windowResized(callback: () => void): void;
     /**

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

@@ -8,6 +8,32 @@ import { TextmodeSource } from './TextmodeSource';
  * An image uploaded currently runs through an adjustable brightness-converter that converts
  * the original image into a textmode representation using characters.
  * Those adjustable options are available via chainable methods on this class.
+ *
+ * @example
+ * ```javascript
+ * const t = textmode.create({
+ *     width: 800,
+ *     height: 600,
+ * });
+ *
+ * let img;
+ *
+ * t.setup(async () => {
+ *     img = await t.loadImage('https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800&q=80');
+ *     img.characters(" .:-=+*#%@");
+ *     // ... other adjustments like img.flipX(boolean), img.cellColorMode('sampled' | 'fixed'), etc.
+ *     // (can also be chained or updated during runtime)
+ * });
+ *
+ * t.draw(() => {
+ *     t.background(0);
+ *
+ *     if (img) {
+ *         // Draw the loaded image
+ *         t.image(img);
+ *     }
+ * });
+ * ```
  */
 export declare class TextmodeImage extends TextmodeSource {
     private constructor();

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

@@ -32,7 +32,7 @@ export declare abstract class TextmodeSource {
      * Dispose of the underlying WebGL texture. Subclasses may extend for additional cleanup.
      * @ignore
      */
-    dispose(): void;
+    $dispose(): void;
     /**
      * Set the invert flag, swapping character and cell colors when enabled.
      * @param v Invert flag
@@ -71,31 +71,31 @@ export declare abstract class TextmodeSource {
     cellColorMode(mode: 'sampled' | 'fixed'): this;
     /**
      * Defines the character color when {@link charColorMode} is `'fixed'`.
-     * @param colorOrGray A grayscale value or TextmodeColor for the character
-     * @param g Additional green component if using RGB
-     * @param b Additional blue component if using RGB
-     * @param a Additional alpha component if using RGBA
+     * @param colorOrGray A grayscale value (0-255), hex string ('#RGB', '#RRGGBB', '#RRGGBBAA'), or TextmodeColor instance
+     * @param g Green component (0-255) if using RGB format
+     * @param b Blue component (0-255) if using RGB format
+     * @param a Alpha component (0-255) if using RGBA format
      * @returns This instance for chaining.
      */
     charColor(colorOrGray: number | string | TextmodeColor, g?: number, b?: number, a?: number): this;
     /**
      * Defines the cell color when {@link cellColorMode} is `'fixed'`.
-     * @param colorOrGray A grayscale value or TextmodeColor for the cell
-     * @param g Additional green component if using RGB
-     * @param b Additional blue component if using RGB
-     * @param a Additional alpha component if using RGBA
+     * @param colorOrGray A grayscale value (0-255), hex string ('#RGB', '#RRGGBB', '#RRGGBBAA'), or TextmodeColor instance
+     * @param g Green component (0-255) if using RGB format
+     * @param b Blue component (0-255) if using RGB format
+     * @param a Alpha component (0-255) if using RGBA format
      * @returns This instance for chaining.
      */
     cellColor(colorOrGray: number | string | TextmodeColor, g?: number, b?: number, a?: number): this;
     /**
      * Defines the background color used for transparent pixels.
-     * @param colorOrGray A grayscale value or TextmodeColor for the background
-     * @param g Additional green component if using RGB
-     * @param b Additional blue component if using RGB
-     * @param a Additional alpha component if using RGBA
+     * @param colorOrGray A grayscale value (0-255), hex string ('#RGB', '#RRGGBB', '#RRGGBBAA'), or TextmodeColor instance
+     * @param g Green component (0-255) if using RGB format
+     * @param b Blue component (0-255) if using RGB format
+     * @param a Alpha component (0-255) if using RGBA format
      * @returns This instance for chaining.
      */
-    background(colorOrGray: number | TextmodeColor, g?: number, b?: number, a?: number): this;
+    background(colorOrGray: number | TextmodeColor | string, g?: number, b?: number, a?: number): this;
     /**
      * Define the characters to use for brightness mapping as a string.
      * Maximum length is 64; excess characters are ignored.

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

@@ -47,6 +47,34 @@ export interface TextmodeVideoOptions {
  * 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.
+ * ```javascript
+ * const t = textmode.create({
+ *     width: 800,
+ *     height: 600,
+ * });
+ *
+ * let video;
+ *
+ * t.setup(async () => {
+ *     video = await t.loadVideo('https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4');
+ *     // Start playback and enable looping so the video keeps playing
+ *     video.play();
+ *     video.loop();
+ *
+ *     video.characters(" .:-=+*#%@");
+ *     // ... other adjustments like video.flipX(boolean), video.cellColorMode('sampled' | 'fixed'), etc.
+ *     // (can also be chained or updated during runtime)
+ * });
+ *
+ * t.draw(() => {
+ *     t.background(0);
+ *
+ *     if (video) {
+ *         // Draw the loaded video
+ *         t.image(video);
+ *     }
+ * });
+ * ```
  */
 export declare class TextmodeVideo extends TextmodeSource {
     private _videoElement;
@@ -74,7 +102,7 @@ export declare class TextmodeVideo extends TextmodeSource {
      * Dispose of GPU resources and cleanup video element.
      * @ignore
      */
-    dispose(): void;
+    $dispose(): void;
     /**
      * Update the texture with the current video frame if needed.
      * For preloaded videos, this returns the appropriate frame texture.

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

@@ -7,6 +7,9 @@ import type { TyprFont, GlyphData } from './typr/types.ts';
  *
  * 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.
  */
 export declare class TextmodeFont {
     private _font;

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

@@ -9,12 +9,12 @@ export declare class LoadingPhaseTracker {
     private _totalWeight;
     private _lastReportedProgress;
     private _onProgressChange?;
-    get totalWeight(): number;
-    get progress(): number;
-    setProgressChangeCallback(callback: (progress: number) => void): void;
-    createPhase(label: string, weight?: number): string;
-    updatePhaseProgress(id: string, progress: number): void;
-    completePhase(id: string): void;
-    failPhase(id: string): void;
-    snapshotPhases(): LoadingPhaseSnapshot[];
+    get $totalWeight(): number;
+    get $progress(): number;
+    $setProgressChangeCallback(callback: (progress: number) => void): void;
+    $createPhase(label: string, weight?: number): string;
+    $updatePhaseProgress(id: string, progress: number): void;
+    $completePhase(id: string): void;
+    $failPhase(id: string): void;
+    $snapshotPhases(): LoadingPhaseSnapshot[];
 }

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

@@ -10,10 +10,18 @@ export declare class LoadingScreenManager {
     private readonly _stateMachine;
     private readonly _phaseTracker;
     private readonly _transition;
+    private readonly _loadingAnimationController;
+    private _loadingFont;
+    private _loadingGrid;
+    private _loadingDrawFramebuffer;
+    private _loadingFramebuffer;
     private _renderer;
     private _palette;
     private _theme;
     private _startTime;
+    private _loadingFrameCount;
+    private _isRendering;
+    private _isInitialized;
     /**
      * Initializes a new LoadingScreenManager.
      * @param textmodifier Textmodifier instance to render on.
@@ -22,11 +30,40 @@ export declare class LoadingScreenManager {
      * @ignore
      */
     constructor(textmodifier: Textmodifier, opts: LoadingScreenOptions | undefined, canvasBackground: RGBA | null);
+    /**
+     * Initialize loading screen resources (font, grid, framebuffers).
+     * Must be called after the renderer is ready.
+     * @param fontSource Optional font source for the loading screen
+     * @ignore
+     */
+    $initialize(fontSource?: string): Promise<void>;
     /**
      * Indicates whether the loading screen should render this frame.
      * @ignore
      */
-    get shouldRender(): boolean;
+    get $shouldRender(): boolean;
+    /**
+     * Start the independent loading screen animation loop.
+     * This runs independently of the user's animation loop.
+     * @ignore
+     */
+    $start(): void;
+    /**
+     * Stop the independent loading screen animation loop.
+     * @ignore
+     */
+    $stop(): void;
+    /**
+     * Handle canvas resize during loading.
+     * Updates grid and framebuffers to match new canvas dimensions.
+     * @ignore
+     */
+    $resize(): void;
+    /**
+     * Dispose of the loading screen manager and clean up resources.
+     * @ignore
+     */
+    $dispose(): void;
     /**
      * Get the current overall loading progress (0-1).
     *
@@ -111,7 +148,7 @@ export declare class LoadingScreenManager {
      * Finish the loading process.
      * @ignore
      */
-    finish(): void;
+    $finish(): void;
     private _notifyComplete;
     private _onCompleteCallback?;
     /**
@@ -119,7 +156,7 @@ export declare class LoadingScreenManager {
      * @param callback The callback function to invoke.
      * @ignore
      */
-    setOnComplete(callback: () => void): void;
+    $setOnComplete(callback: () => void): void;
     /**
      * Report an error that occurred during loading.
      * @param error The error message or `Error` object.
@@ -148,18 +185,22 @@ export declare class LoadingScreenManager {
      */
     error(error: Error | string): void;
     /**
-     * Render a frame of the loading screen.
-     * @param frameCount Current frame count.
-     * @returns void
+     * Independent render loop for the loading screen.
+     * This runs on its own animation controller, separate from user animation.
+     * @ignore
+     */
+    private _renderLoadingFrame;
+    /**
+     * Performs the actual rendering of the loading screen.
      * @ignore
      */
-    renderFrame(frameCount: number): void;
+    private _performRender;
     /**
      * Update the background color used in the loading screen theme.
      * @param color The new background color.
      * @ignore
      */
-    updateBackgroundColor(color: RGBA | null): void;
+    $updateBackgroundColor(color: RGBA | null): void;
     private _resolveRenderer;
     /**
      * Renders the library branding tag at the bottom left of the loading screen.

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

@@ -8,15 +8,15 @@ export declare class LoadingScreenStateMachine {
     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;
+    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

@@ -8,14 +8,14 @@ import type { TextmodeColor } from '../TextmodeColor';
  * @returns The resolved loading screen theme.
  * @ignore
  */
-export declare function resolveTheme(options: LoadingScreenOptions, background: [number, number, number, number] | null): LoadingScreenTheme;
+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[];
+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.
@@ -23,4 +23,4 @@ export declare function resolveDefaultPalette(theme: LoadingScreenTheme): string
  * @returns An array of TextmodeColor instances.
  * @ignore
  */
-export declare function resolveColorInputs(inputs: (number | string | TextmodeColor)[], textmodifier: Textmodifier): TextmodeColor[];
+export declare function $resolveColorInputs(inputs: (number | string | TextmodeColor)[], textmodifier: Textmodifier): TextmodeColor[];

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

@@ -9,9 +9,9 @@ export declare class LoadingScreenTransition {
     private _transitionType;
     private _transitionDuration;
     constructor(transitionType: TransitionType, transitionDuration: number);
-    get opacity(): number;
-    get isTransitioning(): boolean;
-    start(): void;
-    update(): boolean;
-    reset(): void;
+    get $opacity(): number;
+    get $isTransitioning(): boolean;
+    $start(): void;
+    $update(): boolean;
+    $reset(): void;
 }

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

@@ -2,5 +2,5 @@ export { LoadingScreenManager } from './LoadingScreenManager';
 export { LoadingPhaseTracker } from './LoadingPhaseTracker';
 export { LoadingScreenStateMachine } from './LoadingScreenState';
 export { LoadingScreenTransition } from './LoadingScreenTransition';
-export { resolveTheme, resolveDefaultPalette, resolveColorInputs } from './LoadingScreenTheme';
+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/managers/PluginManager.d.ts

@@ -17,7 +17,7 @@ export interface TextmodePluginAPI {
     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.<br/>
      * This framebuffer only has a single render target. */
@@ -35,6 +35,11 @@ export interface TextmodePluginAPI {
  * 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. */