textmode.js 0.1.6-beta.5 → 0.1.6-beta.6

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

@@ -1,6 +1,6 @@
 import type { Framebuffer } from "../rendering/webgl/Framebuffer";
 import type { GLRenderer } from "../rendering/webgl/Renderer";
-import { TextmodeConverter } from "./converters";
+import { TextmodeBrightnessConverter, TextmodeConverter } from "./converters";
 import type { TextmodeFont } from "./font";
 import type { TextmodeGrid } from "./Grid";
 /**
@@ -15,6 +15,10 @@ export declare class TextmodeConversionPipeline {
     private font;
     private grid;
     private converters;
+    /** Pre-configured brightness converter for easy access */
+    readonly brightness: TextmodeBrightnessConverter;
+    /** Pre-configured custom converter for easy access */
+    readonly custom: TextmodeConverter;
     private _resultFramebuffer;
     private _asciiShader;
     private _characterFramebuffer;
@@ -37,23 +41,22 @@ export declare class TextmodeConversionPipeline {
      */
     render(sourceFramebuffer: Framebuffer): void;
     /**
-     * Get a specific converter by name.
-     * @param name The name of the converter to retrieve.
-     * @returns The requested `TextmodeConverter` instance.
+     * Adds a new converter to the pipeline.
+     * @param converter The converter instance to add.
+     * @returns The added {@link TextmodeConverter} instance.
      */
-    get(name: string): TextmodeConverter | void;
     /**
      * Adds a new converter to the pipeline.
      * @param name A unique name for the converter.
      * @param type The type of converter to add. Can be either "brightness" or "custom".
      * @returns The newly created {@link TextmodeConverter} instance or `void` if the addition failed.
      */
-    add(name: string, type: "brightness" | "custom"): TextmodeConverter | void;
+    add(type: "brightness" | "custom"): TextmodeConverter | void;
     /**
-     * Removes a converter from the pipeline by name or instance.
-     * @param nameOrInstance The unique name of the converter or the converter instance to remove.
+     * Removes a converter from the pipeline.
+     * @param converter The converter instance to remove.
      */
-    remove(nameOrInstance: string | TextmodeConverter): void;
+    remove(converter: TextmodeConverter): void;
     /**
      * Returns the framebuffer containing the textmode conversion result.
      */

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

@@ -38,7 +38,7 @@ export declare class TextmodeGrid {
     /**
      * Reset the total grid width & height, and the offset to the outer canvas.
      */
-    private _resizeGrid;
+    private _updateDimensions;
     /**
      * Re-assign the grid cell dimensions and `reset()` the grid.
      * @param newCellWidth The new cell width.
@@ -77,11 +77,6 @@ export declare class TextmodeGrid {
     get cellWidth(): number;
     /** Returns the height of each cell in the grid. */
     get cellHeight(): number;
-    /**
-     * Dispose of this TextmodeGrid and clean up references.
-     * This method is idempotent and safe to call multiple times.
-     */
-    dispose(): void;
     /** Returns the number of columns in the grid. */
     get cols(): number;
     /** Returns the number of rows in the grid. */

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

@@ -3,11 +3,11 @@ import { TextmodeFont } from './font';
 import { TextmodeGrid } from './Grid';
 import { TextmodeCanvas } from './Canvas';
 import { TextmodeConversionPipeline } from './ConversionPipeline';
-import type { TextmodeConverter } from './converters';
-import { type TextmodifierCore } from './mixins';
+import { type TextmodifierContext } from './mixins';
 import type { RenderingCapabilities } from './mixins/RenderingMixin';
 import type { ExportCapabilities } from './mixins/ExportMixin';
 import type { FontCapabilities } from './mixins/FontMixin';
+import type { ConversionCapabilities } from './mixins/ConversionMixin';
 /**
  * Supported capture sources for textmode rendering
  */
@@ -40,14 +40,14 @@ export type TextmodeOptions = {
 /**
  * Base class for mixin application
  */
-declare class TextmodifierBase implements TextmodifierCore {
+declare class TextmodifierCore implements TextmodifierContext {
     _renderer: GLRenderer;
     _font: TextmodeFont;
     _pipeline: TextmodeConversionPipeline;
     textmodeCanvas: TextmodeCanvas;
     _grid: TextmodeGrid;
 }
-declare const Textmodifier_base: typeof TextmodifierBase;
+declare const Textmodifier_base: typeof TextmodifierCore;
 /**
  * Manages textmode rendering on a canvas or video element.
  *
@@ -359,26 +359,6 @@ export declare class Textmodifier extends Textmodifier_base {
      * @param height The new height of the canvas.
      */
     resizeCanvas(width: number, height: number): void;
-    /**
-     * @inheritDoc TextmodeConversionPipeline.get
-     *
-     * @example
-     * ```javascript
-     * // Fetch a canvas element to apply textmode rendering to
-     * const canvas = document.querySelector('canvas#myCanvas');
-     *
-     * // Create a Textmodifier instance
-     * const textmodifier = await textmode.create(canvas);
-     *
-     * // Get the pre-defined brightness converter from the pipeline
-     * const brightnessConverter = textmodifier.converter('brightness');
-     *
-     * // Update properties of the brightness converter
-     * brightnessConverter.invert(true);
-     * brightnessConverter.characters(" .,;:*");
-     * ```
-     */
-    converter(name: string): TextmodeConverter | void;
     /**
      * Completely destroy this Textmodifier instance and free all associated resources.
      *
@@ -427,6 +407,6 @@ export declare class Textmodifier extends Textmodifier_base {
     /** Check if the instance has been disposed/destroyed. */
     get isDisposed(): boolean;
 }
-export interface Textmodifier extends RenderingCapabilities, ExportCapabilities, FontCapabilities {
+export interface Textmodifier extends RenderingCapabilities, ExportCapabilities, FontCapabilities, ConversionCapabilities {
 }
 export {};

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

@@ -73,6 +73,30 @@ export declare abstract class TextmodeFeatureConverter extends TextmodeConverter
      * @param flip If `true`, characters are flipped vertically. If `false`, no flip is applied.
      */
     flipVertically(flip: boolean | number): void;
+    /**
+     * Helper method to parse color values from either hex string or RGB(A) parameters.
+     * @param r Red component (0-255) or hex string.
+     * @param methodName The name of the calling method for error reporting.
+     * @param g Green component (0-255).
+     * @param b Blue component (0-255).
+     * @param a Alpha component (0-255).
+     * @returns Normalized RGBA array [r, g, b, a] (0-1 range) or null if invalid.
+     */
+    private parseColor;
+    /**
+     * Helper method to set color mode with validation.
+     * @param mode The color mode to set.
+     * @param optionKey The option key to set in _options.
+     * @param errorMessage The error message to show if validation fails.
+     */
+    private setColorMode;
+    /**
+     * Helper method to set boolean options with validation.
+     * @param value The boolean or number value to set.
+     * @param optionKey The option key to set in _options.
+     * @param displayName The display name for error messages.
+     */
+    private setBooleanOption;
     /**
      * Parses a hex color string and returns RGBA values.
      * @param hex Hex color string (e.g., '#FF0000', '#F00', 'FF0000', 'F00').

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

@@ -0,0 +1,63 @@
+import type { Mixin } from './TextmodifierMixin';
+import type { TextmodeConverter } from '../converters';
+/**
+ * Interface for conversion pipeline capabilities that will be mixed into Textmodifier
+ */
+export interface ConversionCapabilities {
+    /**
+     * Adds a new converter to the pipeline.
+     * @param name A unique name for the converter.
+     * @param type The type of converter to add. Can be either "brightness" or "custom".
+     * @returns The newly created {@link TextmodeConverter} instance or `void` if the addition failed.
+     *
+     * @example
+     * ```javascript
+     * // Fetch a canvas element to apply textmode rendering to
+     * const canvas = document.querySelector('canvas#myCanvas');
+     *
+     * // Create a Textmodifier instance
+     * const textmodifier = await textmode.create(canvas);
+     *
+     * // Add a new brightness converter
+     * const myConverter = textmodifier.addConverter('my-brightness', 'brightness');
+     *
+     * // Configure the new converter
+     * myConverter.characters("▓▒░ ");
+     * myConverter.enabled(true);
+     *
+     * // Add a custom converter
+     * const customConverter = textmodifier.addConverter('my-custom', 'custom');
+     * ```
+     */
+    addConverter(name: string, type: 'brightness' | 'custom'): TextmodeConverter | void;
+    /**
+     * Removes a converter from the pipeline by name or instance.
+     * @param nameOrInstance The unique name of the converter or the converter instance to remove.
+     *
+     * @example
+     * ```javascript
+     * // Fetch a canvas element to apply textmode rendering to
+     * const canvas = document.querySelector('canvas#myCanvas');
+     *
+     * // Create a Textmodifier instance
+     * const textmodifier = await textmode.create(canvas);
+     *
+     * // Add a converter
+     * const myConverter = textmodifier.addConverter('temp-converter', 'brightness');
+     *
+     * // Remove by name
+     * textmodifier.removeConverter('temp-converter');
+     *
+     * // Or remove by instance
+     * const anotherConverter = textmodifier.addConverter('another', 'custom');
+     * textmodifier.removeConverter(anotherConverter);
+     * ```
+     */
+    removeConverter(nameOrInstance: string | TextmodeConverter): void;
+}
+/**
+ * Mixin that adds conversion pipeline capabilities to a class by delegating to TextmodeConversionPipeline
+ * @param Base The base class to extend
+ * @returns Extended class with conversion capabilities
+ */
+export declare const ConversionMixin: Mixin<ConversionCapabilities>;

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

@@ -1,4 +1,4 @@
-import type { Mixin } from './MixinBase';
+import type { Mixin } from './TextmodifierMixin';
 import { type SVGExportOptions } from '../../export/svg';
 import { type TXTExportOptions } from '../../export/txt';
 import { type ImageExportOptions, type ImageFormat } from '../../export/image';
@@ -10,22 +10,111 @@ export interface ExportCapabilities {
      * Generate the current textmode rendering as a text string.
      * @param options Options for text generation *(excluding filename)*
      * @returns Textmode grid content as a string.
+     *
+     * @example
+     * ```javascript
+     * // Fetch a canvas element to apply textmode rendering to
+     * const canvas = document.querySelector('canvas#myCanvas');
+     *
+     * // Create a Textmodifier instance
+     * const textmodifier = await textmode.create(canvas, {renderMode: 'manual'});
+     *
+     * // Render a single frame
+     * textmodifier.render();
+     *
+     * // Get the current rendering as a text string
+     * const textString = textmodifier.toString({
+     *   preserveTrailingSpaces: false,
+     *   lineEnding: 'lf'
+     * });
+     *
+     * // Print to console or use otherwise
+     * console.log(textString);
+     *
+     * ////////
+     *
+     * // Example with video element
+     * const video = document.querySelector('video#myVideo');
+     * const videoTextmodifier = await textmode.create(video);
+     *
+     * // The textmode overlay will automatically update as the video plays
+     * video.play();
+     *
+     * // Get current frame as ASCII
+     * const videoFrame = videoTextmodifier.toString();
+     * ```
      */
     toString(options?: Omit<TXTExportOptions, 'filename'>): string;
     /**
      * Export the current textmode rendering to a TXT file.
      * @param options Options for TXT export
+     *
+     * @example
+     * ```javascript
+     * // Fetch a canvas element to apply textmode rendering to
+     * const canvas = document.querySelector('canvas#myCanvas');
+     *
+     * // Create a Textmodifier instance
+     * const textmodifier = await textmode.create(canvas, {renderMode: 'manual'});
+     *
+     * // Render a single frame
+     * textmodifier.render();
+     *
+     * // Export the current rendering to a TXT file
+     * textmodifier.saveStrings({
+     *   filename: 'my_textmode_rendering',
+     *   preserveTrailingSpaces: false
+     * });
+     * ```
      */
     saveStrings(options?: TXTExportOptions): void;
     /**
      * Generate the current textmode rendering as an SVG string.
      * @param options Options for SVG generation *(excluding filename)*
      * @returns SVG content as a string.
+     *
+     * @example
+     * ```javascript
+     * // Fetch a canvas element to apply textmode rendering to
+     * const canvas = document.querySelector('canvas#myCanvas');
+     *
+     * // Create a Textmodifier instance
+     * const textmodifier = await textmode.create(canvas, {renderMode: 'manual'});
+     *
+     * // Render a single frame
+     * textmodifier.render();
+     *
+     * // Get the current rendering as an SVG string
+     * const svgString = textmodifier.toSVG({
+     *   includeBackgroundRectangles: true,
+     *   drawMode: 'fill'
+     * });
+     *
+     * // Print to console or use otherwise
+     * console.log(svgString);
+     * ```
      */
     toSVG(options?: Omit<SVGExportOptions, 'filename'>): string;
     /**
      * Export the current textmode rendering to an SVG file.
      * @param options Options for SVG export
+     *
+     * @example
+     * ```javascript
+     * // Fetch a canvas element to apply textmode rendering to
+     * const canvas = document.querySelector('canvas#myCanvas');
+     *
+     * // Create a Textmodifier instance
+     * const textmodifier = await textmode.create(canvas, {renderMode: 'manual'});
+     *
+     * // Render a single frame
+     * textmodifier.render();
+     *
+     * // Export the current rendering to an SVG file
+     * textmodifier.saveSVG({
+     *   filename: 'my_textmode_rendering',
+     * });
+     * ```
      */
     saveSVG(options?: SVGExportOptions): void;
     /**
@@ -33,6 +122,28 @@ export interface ExportCapabilities {
      * @param filename The filename (without extension) to save the image as
      * @param format The image format ('png', 'jpg', or 'webp')
      * @param options Additional options for image export
+     *
+     * @example
+     * ```javascript
+     * // Fetch a canvas element to apply textmode rendering to
+     * const canvas = document.querySelector('canvas#myCanvas');
+     *
+     * // Create a Textmodifier instance
+     * const textmodifier = await textmode.create(canvas, {renderMode: 'manual'});
+     *
+     * // Render a single frame
+     * textmodifier.render();
+     *
+     * // Export the current rendering to a PNG file
+     * textmodifier.saveCanvas('my_textmode_rendering', 'png');
+     *
+     * // Export with custom options
+     * textmodifier.saveCanvas('my_textmode_rendering', 'jpg', {
+     *   quality: 0.8,
+     *   scale: 2.0,
+     *   backgroundColor: 'white'
+     * });
+     * ```
      */
     saveCanvas(filename: string, format?: ImageFormat, options?: Omit<ImageExportOptions, 'filename' | 'format'>): Promise<void>;
 }

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

@@ -1,4 +1,4 @@
-import type { Mixin } from './MixinBase';
+import type { Mixin } from './TextmodifierMixin';
 /**
  * Interface for font capabilities that will be mixed into Textmodifier
  */