textmode.js 0.8.0 → 0.8.1

package/dist/types/Textmode.d.ts

@@ -24,6 +24,18 @@ export declare class Textmode {
      *     t.rect(10, 10);
      * });
      * ```
+     * @exampleAuthor
+     * <div style="display:flex;align-items:center;gap:0.75rem;flex-wrap:wrap;">
+     *   <img src="https://github.com/humanbydefinition.png" alt="@humanbydefinition avatar" width="72" height="72" style="border-radius:12px;box-shadow:0 2px 6px rgba(0,0,0,0.35);" />
+     *   <div style="display:flex;flex-direction:column;gap:0.25rem;">
+     *     <strong><a href="https://github.com/humanbydefinition">@humanbydefinition</a></strong>
+     *     <span style="font-size:0.95em;">
+     *       📷 <a href="https://instagram.com/humanbydefinition">Instagram</a>
+     *       &nbsp;•&nbsp; 🐘 <a href="https://mastodon.social/@humanbydefinition">Mastodon</a>
+     *       &nbsp;•&nbsp; 🦋 <a href="https://bsky.app/profile/humanbydefinition.bsky.social">BlueSky</a>
+     *     </span>
+     *   </div>
+     * </div>
      */
     static create(opts?: TextmodeOptions): Textmodifier;
     /**
@@ -32,7 +44,7 @@ export declare class Textmode {
      * @param level The error handling level to set.
      *
      * @example
-     * ```javascript
+     * ```js
      * // Set error level to WARNING
      * textmode.setErrorLevel(TextmodeErrorLevel.WARNING);
      * ```
@@ -42,7 +54,7 @@ export declare class Textmode {
      * Returns the version of `textmode.js` being used.
      *
      * @example
-     * ```javascript
+     * ```js
      * console.log(textmode.version); // "1.0.0"
      * ```
      */

package/dist/types/errors/ErrorHandler.d.ts

@@ -9,7 +9,7 @@
  * and most `textmode.js` functions will still throw errors if used incorrectly.
  *
  * @example
- * ```javascript
+ * ```js
  * // Set to `WARNING` level to log errors without stopping execution
  * textmode.setErrorLevel(TextmodeErrorLevel.WARNING);
  * ```

package/dist/types/index.d.ts

@@ -9,7 +9,7 @@ export type { TextmodeFramebufferOptions } from './rendering/webgl';
 /**
  * All media conversion related modules and types.
  *
- * Responsible for converting images and videos into textmode-renderable formats,
+ * Responsible for converting images and videos into textmode-renderable formats
  * using various conversion strategies, like brightness- or edge-detection-based conversion.
  *
  * `textmode.js` only comes with a built-in `'brightness'`-based conversion strategy,
@@ -17,7 +17,15 @@ export type { TextmodeFramebufferOptions } from './rendering/webgl';
  */
 export * as conversion from './textmode/conversion';
 export type { TextmodePlugin, TextmodePluginAPI } from './textmode/managers/PluginManager';
-/** All filter related modules and types. */
+/**
+ * All filter related modules and types.
+ *
+ * Provides various image processing filters that can be applied in sequence on a layer's textmode-converted output,
+ * such as blur, sharpen, edge detection, and color adjustments. Filters can also be applied globally to all layers as post-processing effects.
+ *
+ * While `textmode.js` only offers a basic set of filters, additional filters can be implemented and registered via the {@link TextmodeFilterManager},
+ * which is accessible through {@link Textmodifier.filters}.
+ */
 export * as filters from './textmode/filters';
 export { TextmodeErrorLevel } from './errors/ErrorHandler';
 export { Textmode as textmode } from './Textmode';

package/dist/types/rendering/webgl/utils/hash.d.ts

@@ -17,7 +17,7 @@
  * @returns 32-bit integer hash
  *
  * @example
- * ```typescript
+ * ```ts
  * hashString("hello") // → 99162322
  * hashString("world") // → 113318802
  * ```
@@ -31,7 +31,7 @@ export declare function hashString(str: string): number;
  * @returns Integer hash
  *
  * @example
- * ```typescript
+ * ```ts
  * hashNumber(42)    // → 42
  * hashNumber(3.14)  // → 3
  * hashNumber(true)  // → 1
@@ -47,7 +47,7 @@ export declare function hashNumber(value: number | boolean): number;
  * @returns Combined hash of all elements
  *
  * @example
- * ```typescript
+ * ```ts
  * hashArray([1, 2, 3])           // → computed hash
  * hashArray([[1, 2], [3, 4]])    // → computed hash (flattened)
  * ```
@@ -61,7 +61,7 @@ export declare function hashArray(arr: number[] | number[][]): number;
  * @returns Combined hash
  *
  * @example
- * ```typescript
+ * ```ts
  * const arr = new Float32Array([1.0, 2.0, 3.0]);
  * hashTypedArray(arr) // → computed hash
  * ```
@@ -77,7 +77,7 @@ export declare function hashObject(obj: any): number;
  * @returns Combined hash
  *
  * @example
- * ```typescript
+ * ```ts
  * const h1 = hashString("hello");
  * const h2 = hashString("world");
  * const combined = combineHashes(h1, h2);
@@ -93,7 +93,7 @@ export declare function combineHashes(hash1: number, hash2: number): number;
  * @returns Combined hash of all key-value pairs
  *
  * @example
- * ```typescript
+ * ```ts
  * const obj = { b: 2, a: 1, c: 3 };
  * const hash = hashRecord(obj, hashNumber);
  * // Keys are sorted: a, b, c → consistent hash

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

@@ -9,7 +9,7 @@ import type { TextmodeConversionMode, TextmodeConversionStrategy } from './Conve
  * Used for image-to-ASCII conversion modes.
  *
  * @example
- * ```typescript
+ * ```ts
  * // Register a custom conversion strategy
  * t.conversions.register({
  *     id: 'custom',
@@ -35,7 +35,7 @@ export declare class TextmodeConversionManager {
      * @param strategy The conversion strategy to register
      *
      * @example
-     * ```typescript
+     * ```ts
      * t.conversions.register({
      *     id: 'custom',
      *     createShader: (ctx) => shader,

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

@@ -9,7 +9,7 @@ export type BuiltInConversionMode = 'brightness';
 /**
  * Type representing the available textmode conversion modes
  */
-export type TextmodeConversionMode = BuiltInConversionMode | (string & {});
+export type TextmodeConversionMode = BuiltInConversionMode | string;
 /**
  * Interface for the context provided to conversion strategies
  * @ignore
@@ -38,7 +38,7 @@ export interface TextmodeConversionStrategy {
  * conversion strategies to be scoped to a specific Textmodifier instance rather than registered globally.
  *
  * @example
- * ```typescript
+ * ```ts
  * // Register a custom conversion strategy
  * t.conversions.register(myCustomStrategy);
  *

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

@@ -3,15 +3,10 @@ import type { QueuedFilter, FilterName } from './types';
 /**
  * Manages filter registration, shader compilation, and filter chain application.
  *
- * This class provides:
- * - A registry for custom and built-in filter strategies
- * - Lazy shader compilation and caching
- * - Ping-pong rendering for efficient multi-filter chains
- *
  * Used both for layer-level filters and global post-processing filters.
  *
  * @example
- * ```typescript
+ * ```ts
  * // Register a custom filter
  * await t.filters.register('brightness', brightnessShader, {
  *     u_amount: ['amount', 1.0]
@@ -45,7 +40,7 @@ export declare class TextmodeFilterManager {
      * @param uniformDefs Maps uniform names to [paramName, defaultValue] tuples
      *
      * @example
-     * ```typescript
+     * ```ts
      * // Register with inline shader source
      * await t.filters.register('blur', blurFragSource, {
      *     u_radius: ['radius', 5.0],

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

@@ -7,7 +7,7 @@ import type { TextmodeFilterStrategy, FilterName } from './types';
  * filters to be scoped to a specific context rather than registered globally.
  *
  * @example
- * ```typescript
+ * ```ts
  * // Define a simple filter with the declarative API
  * t.filters.register('blur', blurShader, { radius: 5.0 });
  *
@@ -37,7 +37,7 @@ export declare class FilterRegistry {
      * @param uniforms Default uniform values. Keys map uniform names to [paramName, defaultValue] tuples.
      *
      * @example
-     * ```typescript
+     * ```ts
      * // With pre-compiled shader (recommended for add-ons)
      * const shader = await t.createShader(vertSrc, fragSrc);
      * t.filters.register('brightness', shader, { u_amount: ['amount', 1.0] });

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

@@ -189,7 +189,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      *
      * Calling this method is equivalent to setting the draw callback on the base layer,
      * while the direct layer callback has precedence if both are set.
-     * ```javascript
+     * ```js
      * textmodifier.layers.base.draw(callback);
      * ```
      *
@@ -282,7 +282,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * After calling this method, the instance should not be used and will be eligible for garbage collection.
      *
      * @example
-     * ```javascript
+     * ```js
      * // Create a textmodifier instance
      * const textmodifier = textmode.create();
      *
@@ -306,7 +306,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * @param params Optional parameters for the filter
      *
      * @example
-     * ```typescript
+     * ```ts
      * t.draw(() => {
      *     t.background(0);
      *     t.charColor(255);
@@ -350,7 +350,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * (via {@link filter}) and on individual layers (via {@link TextmodeLayer.filter}).
      *
      * @example
-     * ```typescript
+     * ```ts
      * // Register a custom filter once
      * await t.filters.register('vignette', vignetteShader, {
      *     u_intensity: ['intensity', 0.5]
@@ -389,7 +389,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * allowing further configuration of the conversion parameters.
      *
      * @example
-     * ```javascript
+     * ```js
      * // Create the textmode instance using the p5 canvas as input overlay
      * const t = textmode.create({ fontSize: 16, canvas: p.canvas, overlay: true });
      *

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

@@ -6,8 +6,8 @@ import type { ILayerManager } from './interfaces/ILayerManager';
 import type { TextmodeOptions } from '../types';
 import type { TextmodeGrid } from '../Grid';
 /**
- * Manages all user-defined layers within a Textmodifier in *
- * Th *
+ * Manages all user-defined layers within a Textmodifier in addition to the base layer.
+ *
  * This manager is responsible for:
  * - Managing the collection of user layers (add, remove, move, swap)
  * - Coordinating layer rendering and compositing

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

@@ -10,7 +10,7 @@ import type { ITextmodeLayer } from './interfaces/ITextmodeLayer';
  *
  * Layers are composited together using various blend modes
  * to create complex visual effects. Each layer can be independently
- * manipulated in terms of visibility, opacity, blend mode, and position.
+ * manipulated in terms of visibility, {@link opacity}, {@link blendMode}, {@link offset}, rotation, {@link TextmodeGrid}, and {@link TextmodeFont}.
  *
  * You can draw on each layer by providing a draw callback function,
  * like you would with the base layer's {@link Textmodifier.draw} method.
@@ -88,7 +88,7 @@ export declare class TextmodeLayer implements ITextmodeLayer {
      * @returns The loaded TextmodeFont instance.
      *
      * @example
-     * ```javascript
+     * ```js
      * const layer = t.layers.add();
      *
      * t.setup(async () => {

package/dist/types/textmode/layers/interfaces/ITextmodeLayer.d.ts

@@ -51,7 +51,7 @@ export interface ITextmodeLayer {
      * @param callback The function to call when drawing this layer.
      *
      * @example
-     * ```typescript
+     * ```javascript
      * const t = textmode.create();
      *
      * // Create layers with different blend modes
@@ -130,7 +130,7 @@ export interface ITextmodeLayer {
      * @returns The loaded TextmodeFont instance.
      *
      * @example
-     * ```javascript
+     * ```js
      * const layer = t.layers.add();
      *
      * t.setup(async () => {
@@ -176,7 +176,7 @@ export interface ITextmodeLayer {
      * - `'exclusion'` - Softer difference effect
      *
      * @example
-     * ```typescript
+     * ```javascript
      * const t = textmode.create();
      *
      * // Create 5 layers with different blend modes
@@ -219,7 +219,7 @@ export interface ITextmodeLayer {
      * @returns The current offset if no parameters are provided.
      *
      * @example
-     * ```typescript
+     * ```javascript
      * const t = textmode.create();
      *
      * const LAYER_COUNT = 32;
@@ -301,9 +301,7 @@ export interface ITextmodeLayer {
      * @returns The current rotation in degrees if no parameter is provided.
      *
      * @example
-     * ```typescript
-     * import { textmode } from 'textmode.js';
-     *
+     * ```javascript
      * const t = textmode.create();
      *
      * const rotatingLayer = t.layers.add({ blendMode: 'difference', opacity: 1.0 });
@@ -344,7 +342,7 @@ export interface ITextmodeLayer {
      * @param params Optional parameters for the filter
      *
      * @example
-     * ```typescript
+     * ```javascript
      * const t = textmode.create();
      *
      * // Create a layer with filters applied

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

@@ -3,13 +3,13 @@ import type { GLFramebuffer } from '../../../rendering/webgl/core/Framebuffer.ts
 import type { TextmodeCharacter } from './types.ts';
 import type { TyprFont } from './typr/types.ts';
 /**
- * Manages the font used for rendering characters via {@link Textmodifier.loadFont}.
+ * Manages the font used for rendering characters via {@link TextmodeLayer.loadFont}.
  *
  * 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.
+ * Each {@link TextmodeLayer} has its own instance of this class to allow for
+ * layer-specific font configurations.
  */
 export declare class TextmodeFont {
     private _font;

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

@@ -11,16 +11,18 @@ export declare class LoadingPhase implements ILoadingPhase {
     private readonly _phaseTracker;
     readonly id: string;
     readonly label: string;
+    private readonly _onError?;
     /**
      * 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
+     * @param _onError Callback to invoke when the phase fails
      * @ignore
      */
-    constructor(_phaseTracker: LoadingPhaseTracker, id: string, label: string);
+    constructor(_phaseTracker: LoadingPhaseTracker, id: string, label: string, _onError?: ((error: Error | string) => void) | undefined);
     report(progress: number): void;
     complete(): void;
-    fail(_error?: Error): void;
+    fail(error?: Error | string): void;
     track<T>(task: Promise<T> | (() => Promise<T> | T)): Promise<T>;
 }

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

@@ -75,7 +75,7 @@ export declare class LoadingScreenManager {
      *
      * // In setup we can start a phase and read the overall progress
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('assets', 1);
+     *   const phase = t.loading.addPhase('assets', 1);
      *   phase.report(0.5); // half complete for the phase
      *
      *   // The `progress` accessor reports the global progress across all phases
@@ -101,7 +101,7 @@ export declare class LoadingScreenManager {
      *   // Update the message visible on the loading screen
      *   t.loading.message('preloading video...');
      *
-     *   // Read the current message (useful in custom renderers)
+     *   // Read the current message (useful in custom loading screen implementations)
      *   const msg = t.loading.message();
      *   console.log(msg);
      * });
@@ -128,7 +128,7 @@ export declare class LoadingScreenManager {
      *
      * // In setup we start a phase and then track work in that phase
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('video preload', 2);
+     *   const phase = t.loading.addPhase('video preload', 2);
      *
      *   // Example: report progress from a loader callback
      *   await phase.track(async () => {
@@ -168,7 +168,7 @@ export declare class LoadingScreenManager {
      * });
      *
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('remote fetch', 1);
+     *   const phase = t.loading.addPhase('remote fetch', 1);
      *   try {
      *     await phase.track(async () => {
      *       // Failing call

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

@@ -164,7 +164,7 @@ export interface ILoadingPhase {
      *
      * // Create a phase and report progress as work proceeds
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('assets', 1);
+     *   const phase = t.loading.addPhase('assets', 1);
      *   phase.report(0.25);
      *   // ...load assets...
      *   phase.report(0.75);
@@ -181,7 +181,7 @@ export interface ILoadingPhase {
      * const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'prepping...' } });
      *
      * t.setup(() => {
-     *   const phase = t.loading.beginPhase('init', 1);
+     *   const phase = t.loading.addPhase('init', 1);
      *   // Finish phase when work is done
      *   phase.complete();
      * });
@@ -190,14 +190,18 @@ export interface ILoadingPhase {
     complete(): void;
     /**
      * Mark the loading phase as failed.
-     * @param error An optional error object describing the failure.
+     *
+     * This will put the loading manager into an error state, displaying the
+     * error on the loading screen.
+     *
+     * @param error An optional error object or message describing the failure.
      *
      * @example
      * ```ts
      * const t = textmode.create({ width: 800, height: 600 });
      *
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('fetch', 1);
+     *   const phase = t.loading.addPhase('fetch', 1);
      *   try {
      *     // simulate failure
      *     throw new Error('network error');
@@ -207,7 +211,7 @@ export interface ILoadingPhase {
      * });
      * ```
      */
-    fail(error?: Error): void;
+    fail(error?: Error | string): void;
     /**
      * Track a task within this loading phase.
      * @param task A promise or function representing the task to track.
@@ -218,7 +222,7 @@ export interface ILoadingPhase {
      * const t = textmode.create({ width: 800, height: 600, loadingScreen: { message: 'loading...' } });
      *
      * t.setup(async () => {
-     *   const phase = t.loading.beginPhase('video', 2);
+     *   const phase = t.loading.addPhase('video', 2);
      *   await phase.track(async () => {
      *     // do async work and report updates
      *     for (let i = 0; i <= 10; i++) {

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

@@ -142,7 +142,7 @@ export interface IAnimationMixin {
      * @returns True if the render loop is currently active, false otherwise.
      *
      * @example
-     * ```javascript
+     * ```js
      * const textmodifier = textmode.create(canvas);
      *
      * // Check loop status in different states

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

@@ -86,8 +86,6 @@ export interface IRenderingMixin {
      * Draw a TextmodeFramebuffer, TextmodeImage, or TextmodeVideo to the current render target.
      *
      * @param source The TextmodeFramebuffer or TextmodeSource to render
-     * @param x X position on the grid where to place the content *(top-left corner)*
-     * @param y Y position on the grid where to place the content *(top-left corner)*
      * @param width Width to potentially scale the content
      * @param height Height to potentially scale the content
      *

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

@@ -13,7 +13,7 @@ export interface ITouchMixin {
      * @param callback The function to call when a touch starts.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.touchStarted((data) => {
      *   console.log(`Touch ${data.touch.id} began at ${data.touch.x}, ${data.touch.y}`);
      * });
@@ -29,7 +29,7 @@ export interface ITouchMixin {
      * @param callback The function to call when a touch moves.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.touchMoved((data) => {
      *   const { touch, previousTouch } = data;
      *   if (previousTouch) {
@@ -48,7 +48,7 @@ export interface ITouchMixin {
      * @param callback The function to call when a touch ends.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.touchEnded((data) => {
      *   console.log(`Touch ${data.touch.id} finished at ${data.touch.x}, ${data.touch.y}`);
      * });
@@ -64,7 +64,7 @@ export interface ITouchMixin {
      * @param callback The function to call when a touch is cancelled.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.touchCancelled((data) => {
      *   console.warn(`Touch ${data.touch.id} cancelled by the browser`);
      * });
@@ -80,7 +80,7 @@ export interface ITouchMixin {
      * @param callback The function to call when a tap gesture is detected.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.tap((data) => {
      *   console.log(`Tapped at ${data.touch.x}, ${data.touch.y}`);
      * });
@@ -96,7 +96,7 @@ export interface ITouchMixin {
      * @param callback The function to call when a double tap is detected.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.doubleTap((data) => {
      *   console.log('Double tap detected', data.touch);
      * });
@@ -112,7 +112,7 @@ export interface ITouchMixin {
      * @param callback The function to call when a long press gesture is detected.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.longPress((data) => {
      *   console.log(`Long press for ${Math.round(data.duration)}ms`);
      * });
@@ -128,7 +128,7 @@ export interface ITouchMixin {
      * @param callback The function to call when a swipe gesture is detected.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.swipe((data) => {
      *   console.log(`Swipe ${data.direction} with distance ${data.distance}`);
      * });
@@ -144,7 +144,7 @@ export interface ITouchMixin {
      * @param callback The function to call when a pinch gesture is detected.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.pinch((data) => {
      *   console.log(`Pinch scale: ${data.scale.toFixed(2)}`);
      * });
@@ -160,7 +160,7 @@ export interface ITouchMixin {
      * @param callback The function to call when a rotation gesture is detected.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.rotateGesture((data) => {
      *   console.log(`Rotated ${data.deltaRotation.toFixed(1)}°`);
      * });
@@ -174,7 +174,7 @@ export interface ITouchMixin {
      * available. Use this inside a draw loop to react to active multi-touch scenarios.
      *
      * @example
-     * ```javascript
+     * ```js
      * t.draw(() => {
      *   for (const touch of t.touches) {
      *     t.point();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textmode.js",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "textmode.js is a lightweight creative coding library for creating real-time ASCII art on the web.",
   "type": "module",
   "types": "./dist/types/index.d.ts",