textmode.js 0.8.0-beta.2 → 0.8.0

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

@@ -62,6 +62,7 @@ export declare class Textmodifier extends Textmodifier_base implements ITextmodi
     private _resizeObserver?;
     private _isOverlay;
     private _targetCanvasImage?;
+    private _inputGridOverride?;
     /**
      * Create a new Textmodifier instance.
      * @param opts Configuration options for the Textmodifier instance.
@@ -82,6 +83,13 @@ export declare class Textmodifier extends Textmodifier_base implements ITextmodi
     filter(name: FilterName, params?: unknown): void;
     loadFont(fontSource: string): Promise<TextmodeFont>;
     fontSize(size: number): void;
+    inputGrid(target?: 'topmost' | TextmodeGrid): 'topmost' | TextmodeGrid | void;
+    /**
+     * Get the grid used for input coordinate mapping.
+     * Returns the override grid/layer's grid if set, otherwise the topmost visible layer's grid.
+     * @ignore
+     */
+    private _getInputGrid;
     setup(callback: () => void | Promise<void>): Promise<void>;
     draw(callback: () => void): void;
     windowResized(callback: () => void): void;

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

@@ -71,6 +71,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * t.setup(async () => {
      *   // Load font for the base layer
      *   const font = await t.loadFont('./fonts/myfont.ttf');
+     *   // const font = await t.layers.base.loadFont('./fonts/myfont.ttf'); // Equivalent
      *
      *   // Use the same font on another layer
      *   const layer = t.layers.add();
@@ -104,6 +105,43 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * ```
      */
     fontSize(size: number): void;
+    /**
+     * Get or set the grid used for mouse and touch input coordinate mapping.
+     *
+     * By default, input coordinates are mapped to the topmost visible layer's grid,
+     * which changes dynamically as layers are shown/hidden. Use this method to lock
+     * input mapping to a specific grid or layer, or to return to responsive mode.
+     *
+     * When called without arguments, returns the current input grid mode:<br/>
+     * - `'topmost'` if using responsive mode (default)<br/>
+     * - The specific `TextmodeGrid` if locked
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create();
+     *
+     * // Add a UI layer on top
+     * const uiLayer = t.layers.add({ fontSize: 16 });
+     *
+     * t.setup(() => {
+     *   // Lock input to the base layer's grid for game controls
+     *   // even though the UI layer is rendered on top
+     *   t.inputGrid(t.layers.base.grid);
+     * });
+     *
+     * t.draw(() => {
+     *   // Mouse positions now always use base layer's grid
+     *   t.text(`Mouse: ${t.mouseX}, ${t.mouseY}`, 0, 0);
+     * });
+     *
+     * // Switch back to responsive mode
+     * // t.inputGrid('topmost');
+     *
+     * // Or check current mode
+     * // const current = t.inputGrid(); // 'topmost' or the locked grid
+     * ```
+     */
+    inputGrid(target?: 'topmost' | TextmodeGrid): 'topmost' | TextmodeGrid | void;
     /**
      * Set a setup callback function that will be executed once when initialization is complete.
      *
@@ -146,9 +184,15 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      *
      * This callback function is where all drawing commands should be placed for textmode rendering on the main layer.
      *
-     * If multiple layers are added via {@link Textmodifier.layers}, each layer can have its own draw callback set via {@link TextmodeLayer.draw}.
+     * If multiple layers are added via {@link Textmodifier.layers}, each layer has its own draw callback set via {@link TextmodeLayer.draw}.
      * This allows for complex multi-layered compositions with independent rendering logic per layer.
      *
+     * 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
+     * textmodifier.layers.base.draw(callback);
+     * ```
+     *
      * @param callback The function to call before each render
      *
      * @example
@@ -282,7 +326,12 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
     filter<T extends BuiltInFilterName>(name: T, params?: BuiltInFilterParams[T]): void;
     filter(name: FilterName, params?: unknown): void;
     filter(name: FilterName, params?: unknown): void;
-    /** Get the grid object used for rendering the base layer. */
+    /**
+     * Get the grid whose layer is currently being drawn to.
+     * If called outside of a layers draw callback, returns the base layer's grid.
+     *
+     * If no grid is set (e.g., before user setup()), returns `undefined`.
+     */
     readonly grid: TextmodeGrid | undefined;
     /** Get the current font object used for rendering the base layer. */
     readonly font: TextmodeFont;
@@ -299,7 +348,6 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      *
      * Use this to register custom filters that can be applied both globally
      * (via {@link filter}) and on individual layers (via {@link TextmodeLayer.filter}).
-     * Filters only need to be registered once and are available everywhere.
      *
      * @example
      * ```typescript
@@ -326,7 +374,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      * Access the layer manager for this Textmodifier instance.
      *
      * Use this to create and manage multiple layers within the textmode rendering context.
-     * Each layer can have its own grid, font, draw callback, and filters.
+     * Each layer has its own grid, font, draw callback, and filters.
      */
     readonly layers: TextmodeLayerManager;
     /**
@@ -379,7 +427,7 @@ export interface ITextmodifier extends IRenderingMixin, IAnimationMixin, IMouseM
      *   await phase1.track(async () => {
      *     for (let i = 0; i <= 5; i++) {
      *       phase1.report(i / 5);
-     *       // Small delay — increases visibility of the loading animation
+     *       // Small delay - increases visibility of the loading animation
      *       await new Promise((r) => setTimeout(r, 200));
      *     }
      *   });

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

@@ -73,8 +73,9 @@ export declare class LayerManager implements ILayerManager {
      * Get the grid of the topmost visible layer.
      * Returns the topmost user layer's grid if any are visible, otherwise returns the base layer's grid.
      * This is useful for input managers that need to map coordinates to the layer the user sees on top.
+     * @ignore
      */
-    getTopmostGrid(): TextmodeGrid | undefined;
+    $getTopmostGrid(): TextmodeGrid | undefined;
     /**
      * Register a callback to be invoked whenever ANY layer's grid dimensions change.
      * This includes the base layer and all user layers.

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

@@ -46,5 +46,5 @@ export interface ILayerManager {
      * Returns the topmost user layer's grid if any are visible, otherwise returns the base layer's grid.
      * This is useful for input managers that need to map coordinates to the layer the user sees on top.
      */
-    getTopmostGrid(): TextmodeGrid | undefined;
+    $getTopmostGrid(): TextmodeGrid | undefined;
 }

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

@@ -334,7 +334,7 @@ export interface ITextmodeLayer {
      * Filters are applied after ASCII conversion in the order they are called.
      * Call this method within your layer's draw callback to apply effects.
      *
-     * **Built-in Filters:**
+     * **Built-in filters:**
      * - `'invert'` - Inverts all colors
      * - `'grayscale'` - Converts to grayscale (param: amount 0-1, default 1)
      * - `'sepia'` - Applies sepia tone (param: amount 0-1, default 1)

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

@@ -47,9 +47,9 @@ export interface TextmodeLayerOptions {
      */
     offsetY?: number;
     /**
-     * The rotation of the layer in degrees around its center. Default is `0`.
+     * The z-rotation of the layer in degrees around its center. Default is `0`.
      */
-    rotation?: number;
+    rotationZ?: number;
     /**
      * The font size for the layer's text. Default is `16`.
      */

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

@@ -29,10 +29,8 @@ import type { TextmodeConversionManager } from '../conversion';
  * t.draw(() => {
  *     t.background(0);
  *
- *     if (img) {
- *         // Draw the loaded image
- *         t.image(img);
- *     }
+ *     // Draw the loaded image
+ *     t.image(img);
  * });
  * ```
  */

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

@@ -33,10 +33,8 @@ import type { TextmodeConversionManager } from '../../conversion';
  * t.draw(() => {
  *     t.background(0);
  *
- *     if (video) {
- *         // Draw the loaded video
- *         t.image(video);
- *     }
+ *      // Draw the loaded video
+ *      t.image(video);
  * });
  * ```
  */

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

@@ -1,5 +1,5 @@
-import type { LoadingPhaseTracker } from "./LoadingPhaseTracker";
-import type { ILoadingPhase } from "./types";
+import type { LoadingPhaseTracker } from './LoadingPhaseTracker';
+import type { ILoadingPhase } from './types';
 /**
  * Represents a loading phase tracked by a LoadingPhaseTracker.
  *

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

@@ -1,5 +1,4 @@
 import type { GLFramebuffer, GLShader, TextmodeFramebufferOptions, UniformValue } from '../../../rendering/webgl';
-import type { TextmodeSource } from '../../loadables/TextmodeSource';
 import type { TextmodeImage } from '../../loadables/TextmodeImage';
 import type { TextmodeColor } from '../../TextmodeColor';
 import type { TextmodeVideo } from '../../loadables';
@@ -84,7 +83,7 @@ export interface IRenderingMixin {
      */
     createFramebuffer(options: TextmodeFramebufferOptions): GLFramebuffer;
     /**
-     * Draw a TextmodeFramebuffer or TextmodeSource (TextmodeImage/TextmodeVideo) to the current render target.
+     * 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)*
@@ -121,7 +120,7 @@ export interface IRenderingMixin {
      * });
      * ```
      */
-    image(source: GLFramebuffer | TextmodeSource, width?: number, height?: number): void;
+    image(source: GLFramebuffer | TextmodeImage | TextmodeVideo, width?: number, height?: number): void;
     /**
      * Load an image and return a TextmodeImage that can be drawn with image().
      *
@@ -148,10 +147,8 @@ export interface IRenderingMixin {
      * t.draw(() => {
      *     t.background(0);
      *
-     *     if (img) {
-     *         // Draw the loaded image
-     *         t.image(img);
-     *     }
+     *     // Draw the loaded image
+     *     t.image(img);
      * });
      * ```
      */
@@ -182,10 +179,8 @@ export interface IRenderingMixin {
      * t.draw(() => {
      *     t.background(0);
      *
-     *     if (video) {
-     *         // Draw the loaded video
-     *         t.image(video);
-     *     }
+     *     // Draw the loaded video
+     *     t.image(video);
      * });
      * ```
      */
@@ -706,7 +701,10 @@ export interface IRenderingMixin {
      */
     line(x1: number, y1: number, x2: number, y2: number): void;
     /**
-     * Set the background color for the canvas.
+     * Set the background color of the layer currently drawing to.
+     *
+     * Used to clear the layer to a specific color at the start of its drawing cycle.
+     *
      * @param value A {@link TextmodeColor}, hex string, grayscale value, or single RGB channel
      * @param g Optional green component when providing RGB channels or alpha when used with grayscale
      * @param b Optional blue component when providing RGB channels
@@ -739,7 +737,9 @@ export interface IRenderingMixin {
      */
     background(value: number | string | TextmodeColor, g?: number, b?: number, a?: number): void;
     /**
-     * Clear the canvas.
+     * Clear the layer currently drawing to.
+     *
+     * Used to clear the layer at the start of its drawing cycle.
      *
      * @example
      * ```javascript
@@ -839,6 +839,8 @@ export interface IRenderingMixin {
      * Set the character to be used for subsequent rendering operations.
      * Accepts a single character string.
      *
+     * @param character The character to set for rendering
+     *
      * @example
      * ```javascript
      * const t = textmode.create({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textmode.js",
-  "version": "0.8.0-beta.2",
+  "version": "0.8.0",
   "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",