textmode.js 0.8.1 → 0.9.0-beta.2

package/dist/types/textmode/mixins/interfaces/IAnimationMixin.d.ts

@@ -23,6 +23,139 @@ export interface IAnimationMixin {
      * ```
      */
     frameRate(fps?: number): number | void;
+    /**
+     * Get the number of milliseconds since the sketch started running.
+     *
+     * `millis` keeps track of how long a sketch has been running in milliseconds
+     * (thousandths of a second). This information is often helpful for timing events
+     * and animations.
+     *
+     * Time tracking begins before the code in {@link setup} runs. If loading screen is
+     * enabled, `millis` begins tracking as soon as the loading screen starts.
+     *
+     * This property is connected to {@link secs} - setting one will affect the other.
+     *
+     * @returns Number of milliseconds since starting the sketch.
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Get the number of seconds the sketch has run
+     *   const seconds = t.millis / 1000;
+     *
+     *   t.text(`Running time: ${seconds.toFixed(1)} sec`, 10, 10);
+     * });
+     * ```
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Use millis for smooth animation
+     *   const time = t.millis / 1000;
+     *   const x = Math.sin(time) * 20 + 40;
+     *
+     *   t.char('O', Math.floor(x), 10);
+     * });
+     * ```
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * // Seek to a specific time in the animation
+     * t.millis = 5000; // Jump to 5 seconds
+     * ```
+     */
+    get millis(): number;
+    /**
+     * Set the elapsed milliseconds by adjusting the internal start time.
+     *
+     * This allows seeking/scrubbing in animations. Setting `millis` will also
+     * affect the value returned by {@link secs} since they are connected.
+     *
+     * @param value The new elapsed time in milliseconds
+     */
+    set millis(value: number);
+    /**
+     * Get the number of seconds since the sketch started running.
+     *
+     * `secs` is a convenience property that returns the elapsed time in seconds
+     * instead of milliseconds. Equivalent to `millis / 1000`.
+     *
+     * Time tracking begins before the code in {@link setup} runs. If loading screen is
+     * enabled, `secs` begins tracking as soon as the loading screen starts.
+     *
+     * This property is connected to {@link millis} - setting one will affect the other.
+     *
+     * @returns Number of seconds since starting the sketch.
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Use secs for smooth time-based animations
+     *   const angle = t.secs * Math.PI;
+     *   const x = Math.sin(angle) * 10;
+     *
+     *   t.text(`X: ${x.toFixed(2)}`, 10, 10);
+     * });
+     * ```
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * // Seek to a specific time in the animation
+     * t.secs = 10; // Jump to 10 seconds (equivalent to t.millis = 10000)
+     * ```
+     */
+    get secs(): number;
+    /**
+     * Set the elapsed seconds by adjusting the internal start time.
+     *
+     * This allows seeking/scrubbing in animations. Setting `secs` will also
+     * affect the value returned by {@link millis} since they are connected.
+     *
+     * @param value The new elapsed time in seconds
+     */
+    set secs(value: number);
+    /**
+     * Returns the time in milliseconds between the current frame and the previous frame.
+     *
+     * `deltaTime()` is useful for creating frame-rate-independent animations. By multiplying
+     * velocities and movements by `deltaTime()`, animations will run at consistent speeds
+     * regardless of the actual frame rate.
+     *
+     * @returns Time elapsed between current and previous frame in milliseconds.
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     * let x = 0;
+     * const speed = 0.1; // units per millisecond
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Move at consistent speed regardless of frame rate
+     *   x += speed * t.deltaTime();
+     *
+     *   t.text(`X: ${x.toFixed(2)}`, 10, 10);
+     * });
+     * ```
+     */
+    deltaTime(): number;
     /**
      * Stop the automatic rendering loop.
      *

package/dist/types/textmode/mixins/interfaces/IRenderingMixin.d.ts

@@ -314,6 +314,14 @@ export interface IRenderingMixin {
      * ```
      */
     createFilterShader(fragmentSource: string): Promise<GLShader>;
+    /**
+     * Create a shader from vertex and fragment source code or file paths.
+     * Accepts inline shader source or file paths (e.g. './shader.frag', './shader.vert', '.frag', '.vert').
+     * @param vertexSource The vertex shader source code or a file path
+     * @param fragmentSource The fragment shader source code or a file path
+     * @returns A Promise that resolves to a compiled shader
+     */
+    createShader(vertexSource: string, fragmentSource: string): Promise<GLShader>;
     /**
      * Sets the rotation angles for subsequent shape rendering operations.
      *
@@ -1068,4 +1076,76 @@ export interface IRenderingMixin {
      * ```
      */
     arc(width: number, height: number, startAngle: number, endAngle: number): void;
+    /**
+     * Set the rendering mode to 2D (traditional ASCII compositing) or 3D (voxel raymarching).
+     *
+     * In 2D mode, each layer is individually converted to ASCII and then composited.
+     * In 3D mode, layer data is stacked in depth and rendered through a voxel raymarching shader.
+     *
+     * @param mode The rendering mode: '2d' or '3d'.
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * t.draw(() => {
+     *   t.renderMode('3d');
+     *   t.rotation3D(t.frameCount * 0.5, t.frameCount * 0.3, 0);
+     *
+     *   t.background(0);
+     *   t.char('@');
+     *   t.charColor(255, 100, 50);
+     *   t.rect(10, 10);
+     * });
+     * ```
+     */
+    renderMode(mode: '2d' | '3d'): void;
+    /**
+     * Set the 3D rotation angles for voxel rendering (only applies in '3d' mode).
+     *
+     * @param x Rotation around the X axis in degrees.
+     * @param y Rotation around the Y axis in degrees.
+     * @param z Rotation around the Z axis in degrees.
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * t.draw(() => {
+     *   t.renderMode('3d');
+     *   t.rotation3D(30, t.frameCount, 0); // Tilt and spin
+     *   t.background(0);
+     *   t.char('#');
+     *   t.rect(15, 15);
+     * });
+     * ```
+     */
+    rotation(x: number, y?: number, z?: number): void;
+    /**
+     * Set the 3D translation offset for voxel rendering (only applies in '3d' mode).
+     *
+     * @param x Translation along the X axis.
+     * @param y Translation along the Y axis.
+     * @param z Translation along the Z axis.
+     */
+    translation3D(x: number, y?: number, z?: number): void;
+    /**
+     * Set the 3D zoom level for voxel rendering (only applies in '3d' mode).
+     *
+     * @param zoom Zoom factor (1 = no zoom, >1 = zoom in, <1 = zoom out).
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * t.draw(() => {
+     *   t.renderMode('3d');
+     *   t.zoom3D(1.5 + Math.sin(t.frameCount * 0.02) * 0.5);
+     *   t.background(0);
+     *   t.char('*');
+     *   t.rect(10, 10);
+     * });
+     * ```
+     */
+    zoom3D(zoom: number): void;
 }

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

@@ -1,7 +1,7 @@
 import type { TextmodePlugin } from './managers/PluginManager';
 import type { LoadingScreenOptions } from './loading/';
 /**
- * Options for creating a {@link Textmodifier} instance.
+ * Options when creating a {@link Textmodifier} instance.
  */
 export type TextmodeOptions = {
     /**
@@ -34,8 +34,9 @@ export type TextmodeOptions = {
      *
      * Useful for applying textmode conversion to p5.js sketches, YouTube videos, and sooo much more.
      *
-     * All functionality of `textmode.js` remains available. Resizing the `textmode.js` canvas is not recommended though, since the overlay target defines the size.
-     *
+     * All functionality of `textmode.js` remains available.
+     * Resizing the `textmode.js` canvas is not recommended though,
+     * since the overlay target automatically updates the size.
      */
     overlay?: boolean;
     /** List of plugins to install when the Textmodifier instance is created. */

package/dist/types/utils/TextmodeCollection.d.ts

@@ -0,0 +1,262 @@
+/**
+ * A generic, managed collection for objects that require lifecycle management.
+ *
+ * This class provides CRUD operations (Create/Read/Update/Delete) with support for:
+ * - Adding and removing items
+ * - Reordering items (move, swap)
+ * - Deferred initialization via pending items
+ * - Automatic disposal of removed items
+ * - Event callbacks for lifecycle events
+ *
+ * @typeParam T - The type of items stored in the collection
+ *
+ * @example
+ * ```ts
+ * // Create a collection with a disposal callback
+ * const layers = new TextmodeCollection<TextmodeLayer>({
+ *   onDispose: (layer) => layer.$dispose(),
+ *   onAdd: (layer) => pluginManager.notifyLayerCreated(layer),
+ *   onRemove: (layer) => pluginManager.notifyLayerDisposed(layer),
+ * });
+ *
+ * // Add items
+ * const layer = new TextmodeLayer();
+ * layers.add(layer);
+ *
+ * // Iterate
+ * for (const layer of layers) {
+ *   layer.draw();
+ * }
+ *
+ * // Remove all
+ * layers.clear();
+ * ```
+ */
+export declare class TextmodeCollection<T> implements Iterable<T> {
+    private _items;
+    private _pendingItems;
+    private _isReady;
+    private readonly _options;
+    /**
+     * Create a new TextmodeCollection.
+     *
+     * @param options Configuration options for the collection
+     */
+    constructor(options?: TextmodeCollectionOptions<T>);
+    /**
+     * Mark the collection as ready and move all pending items to the active list.
+     *
+     * Call this after async initialization is complete. Any items added before
+     * this call will be moved from the pending queue to the active collection.
+     *
+     * @param initializeItem Optional async function to initialize each pending item
+     * @returns Promise that resolves when all pending items are initialized
+     */
+    initialize(initializeItem?: (item: T) => Promise<void>): Promise<void>;
+    /**
+     * Check if the collection has been initialized.
+     */
+    get isReady(): boolean;
+    /**
+     * Add an item to the collection.
+     *
+     * If the collection is not yet ready, the item is added to a pending queue.
+     * Once `initialize()` is called, pending items are moved to the active collection.
+     *
+     * @param item The item to add
+     * @returns The added item (for chaining)
+     */
+    add(item: T): T;
+    /**
+     * Add multiple items to the collection.
+     *
+     * @param items The items to add
+     * @returns The added items
+     */
+    addMany(items: T[]): T[];
+    /**
+     * Remove an item from the collection and dispose it.
+     *
+     * @param item The item to remove
+     * @returns true if the item was found and removed, false otherwise
+     */
+    remove(item: T): boolean;
+    /**
+     * Remove an item at a specific index.
+     *
+     * @param index The index of the item to remove
+     * @returns The removed item, or undefined if index is out of bounds
+     */
+    removeAt(index: number): T | undefined;
+    /**
+     * Move an item to a new index in the collection.
+     *
+     * @param item The item to move
+     * @param newIndex The target index
+     * @returns true if the item was found and moved, false otherwise
+     */
+    move(item: T, newIndex: number): boolean;
+    /**
+     * Swap the positions of two items in the collection.
+     *
+     * @param itemA The first item
+     * @param itemB The second item
+     * @returns true if both items were found and swapped, false otherwise
+     */
+    swap(itemA: T, itemB: T): boolean;
+    /**
+     * Remove and dispose all items from the collection.
+     *
+     * This clears both active and pending items.
+     */
+    clear(): void;
+    /**
+     * Dispose the collection and all its items.
+     *
+     * After calling this, the collection should not be used.
+     */
+    dispose(): void;
+    /**
+     * Get all active items as a readonly array.
+     */
+    get all(): readonly T[];
+    /**
+     * Get all pending items as a readonly array.
+     */
+    get pending(): readonly T[];
+    /**
+     * Get the number of active items.
+     */
+    get length(): number;
+    /**
+     * Get the total number of items (active + pending).
+     */
+    get totalLength(): number;
+    /**
+     * Check if the collection is empty (no active items).
+     */
+    get isEmpty(): boolean;
+    /**
+     * Get an item at a specific index.
+     *
+     * @param index The index of the item
+     * @returns The item, or undefined if index is out of bounds
+     */
+    get(index: number): T | undefined;
+    /**
+     * Get the first item in the collection.
+     */
+    get first(): T | undefined;
+    /**
+     * Get the last item in the collection.
+     */
+    get last(): T | undefined;
+    /**
+     * Get the index of an item.
+     *
+     * @param item The item to find
+     * @returns The index, or -1 if not found
+     */
+    indexOf(item: T): number;
+    /**
+     * Check if an item exists in the collection.
+     *
+     * @param item The item to check
+     * @returns true if the item exists (in active or pending)
+     */
+    has(item: T): boolean;
+    /**
+     * Iterate over all active items.
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Execute a callback for each active item.
+     *
+     * @param callback Function to execute for each item
+     */
+    forEach(callback: (item: T, index: number) => void): void;
+    /**
+     * Map active items to a new array.
+     *
+     * @param callback Function to transform each item
+     * @returns New array with transformed items
+     */
+    map<U>(callback: (item: T, index: number) => U): U[];
+    /**
+     * Filter active items.
+     *
+     * @param predicate Function to test each item
+     * @returns New array with items that pass the test
+     */
+    filter(predicate: (item: T, index: number) => boolean): T[];
+    /**
+     * Find an item matching a predicate.
+     *
+     * @param predicate Function to test each item
+     * @returns The first matching item, or undefined
+     */
+    find(predicate: (item: T, index: number) => boolean): T | undefined;
+    /**
+     * Find the index of an item matching a predicate.
+     *
+     * @param predicate Function to test each item
+     * @returns The index of the first matching item, or -1
+     */
+    findIndex(predicate: (item: T, index: number) => boolean): number;
+    /**
+     * Check if any item matches a predicate.
+     *
+     * @param predicate Function to test each item
+     * @returns true if any item matches
+     */
+    some(predicate: (item: T, index: number) => boolean): boolean;
+    /**
+     * Check if all items match a predicate.
+     *
+     * @param predicate Function to test each item
+     * @returns true if all items match
+     */
+    every(predicate: (item: T, index: number) => boolean): boolean;
+    /**
+     * Reduce active items to a single value.
+     *
+     * @param callback Reducer function
+     * @param initialValue Initial accumulator value
+     * @returns The final accumulated value
+     */
+    reduce<U>(callback: (accumulator: U, item: T, index: number) => U, initialValue: U): U;
+    /**
+     * Dispose a single item using the configured disposal callback.
+     */
+    private _disposeItem;
+}
+/**
+ * Configuration options for TextmodeCollection.
+ *
+ * @typeParam T - The type of items stored in the collection
+ */
+export interface TextmodeCollectionOptions<T> {
+    /**
+     * Called when an item is added to the active collection.
+     * Not called for pending items until they become active.
+     */
+    onAdd?: (item: T) => void;
+    /**
+     * Called when an item is about to be removed from the collection.
+     * This is called before `onDispose`.
+     */
+    onRemove?: (item: T) => void;
+    /**
+     * Called to dispose an item when it's removed from the collection.
+     * This is where you should clean up resources.
+     */
+    onDispose?: (item: T) => void;
+    /**
+     * Called when an item is moved to a new index.
+     */
+    onMove?: (item: T, oldIndex: number, newIndex: number) => void;
+    /**
+     * Called when two items are swapped.
+     */
+    onSwap?: (itemA: T, itemB: T, indexA: number, indexB: number) => void;
+}

package/dist/types/utils/mat3.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 3x3 Matrix utilities for 3D transformations.
+ *
+ * All matrices are stored in row-major order as flat arrays of 9 elements:
+ * ```
+ * [m00, m01, m02,
+ *  m10, m11, m12,
+ *  m20, m21, m22]
+ * ```
+ *
+ * @module utils/mat3
+ */
+/**
+ * A 3x3 matrix represented as a tuple of 9 numbers in row-major order.
+ */
+export type Mat3 = [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+/**
+ * Create an identity 3x3 matrix.
+ *
+ * @returns A new identity matrix
+ *
+ * @example
+ * ```ts
+ * const identity = mat3Identity();
+ * // [1, 0, 0, 0, 1, 0, 0, 0, 1]
+ * ```
+ */
+export declare function mat3Identity(): Mat3;
+/**
+ * Multiply two 3x3 matrices in row-major order.
+ *
+ * @param a First matrix (left operand)
+ * @param b Second matrix (right operand)
+ * @returns The product matrix (a × b)
+ *
+ * @example
+ * ```ts
+ * const result = mat3Multiply(rotationX, rotationY);
+ * ```
+ */
+export declare function mat3Multiply(a: Mat3, b: Mat3): Mat3;
+/**
+ * Transpose a 3x3 matrix (swap rows and columns).
+ *
+ * For orthonormal rotation matrices, the transpose equals the inverse.
+ *
+ * @param m The matrix to transpose
+ * @returns The transposed matrix
+ *
+ * @example
+ * ```ts
+ * const inverse = mat3Transpose(rotationMatrix);
+ * ```
+ */
+export declare function mat3Transpose(m: Mat3): Mat3;
+/**
+ * Create a rotation matrix around the X axis.
+ *
+ * @param radians Rotation angle in radians
+ * @returns Rotation matrix around X axis
+ *
+ * @example
+ * ```ts
+ * const rotX = mat3RotationX(Math.PI / 4); // 45° rotation
+ * ```
+ */
+export declare function mat3RotationX(radians: number): Mat3;
+/**
+ * Create a rotation matrix around the Y axis.
+ *
+ * @param radians Rotation angle in radians
+ * @returns Rotation matrix around Y axis
+ *
+ * @example
+ * ```ts
+ * const rotY = mat3RotationY(Math.PI / 2); // 90° rotation
+ * ```
+ */
+export declare function mat3RotationY(radians: number): Mat3;
+/**
+ * Create a rotation matrix around the Z axis.
+ *
+ * @param radians Rotation angle in radians
+ * @returns Rotation matrix around Z axis
+ *
+ * @example
+ * ```ts
+ * const rotZ = mat3RotationZ(Math.PI); // 180° rotation
+ * ```
+ */
+export declare function mat3RotationZ(radians: number): Mat3;
+/**
+ * Build a combined rotation matrix from Euler angles (in radians).
+ *
+ * The rotation order is: Z × Y × X (applied right-to-left,
+ * so X rotation is applied first to the vector).
+ *
+ * @param radiansX Rotation around X axis in radians
+ * @param radiansY Rotation around Y axis in radians
+ * @param radiansZ Rotation around Z axis in radians
+ * @returns Combined rotation matrix
+ *
+ * @example
+ * ```ts
+ * import { degToRad } from './math';
+ * const rotation = mat3FromEuler(
+ *   degToRad(45),
+ *   degToRad(30),
+ *   degToRad(0)
+ * );
+ * ```
+ */
+export declare function mat3FromEuler(radiansX: number, radiansY: number, radiansZ: number): Mat3;
+/**
+ * Build a rotation matrix from Euler angles in degrees.
+ *
+ * This is a convenience function that converts degrees to radians
+ * and returns the transposed (inverse) matrix, which is commonly
+ * needed for shader uniforms.
+ *
+ * @param degX Rotation around X axis in degrees
+ * @param degY Rotation around Y axis in degrees
+ * @param degZ Rotation around Z axis in degrees
+ * @returns Transposed rotation matrix as Float32Array (for GPU upload)
+ *
+ * @example
+ * ```ts
+ * const modelRotation = mat3FromEulerDegrees(45, 30, 0);
+ * shader.setUniform('u_modelRotation', modelRotation);
+ * ```
+ */
+export declare function mat3FromEulerDegrees(degX: number, degY: number, degZ: number): Float32Array;
+/**
+ * Convert a Mat3 to a Float32Array for GPU upload.
+ *
+ * @param m The matrix to convert
+ * @returns Float32Array containing the matrix data
+ */
+export declare function mat3ToFloat32Array(m: Mat3): Float32Array;

package/dist/types/utils/math.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Convert degrees to radians.
+ *
+ * @param degrees Angle in degrees
+ * @returns Angle in radians
+ *
+ * @example
+ * ```ts
+ * degToRad(180); // Math.PI
+ * degToRad(90);  // Math.PI / 2
+ * ```
+ */
+export declare function degToRad(degrees: number): number;
+/**
+ * Convert radians to degrees.
+ *
+ * @param radians Angle in radians
+ * @returns Angle in degrees
+ *
+ * @example
+ * ```ts
+ * radToDeg(Math.PI);     // 180
+ * radToDeg(Math.PI / 2); // 90
+ * ```
+ */
+export declare function radToDeg(radians: number): number;
 /**
  * Calculate the angle in degrees between two points.
  * @param x1 - X coordinate of the first point