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

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

@@ -6,9 +6,9 @@ import type { TextmodeGrid } from "../Grid";
  * Base class for all textmode converters.
  */
 export declare class TextmodeConverter {
-    protected renderer: GLRenderer;
-    protected fontManager: TextmodeFont;
-    protected grid: TextmodeGrid;
+    protected _renderer: GLRenderer;
+    protected _fontManager: TextmodeFont;
+    protected _grid: TextmodeGrid;
     protected _characterFramebuffer: Framebuffer;
     protected _primaryColorFramebuffer: Framebuffer;
     protected _secondaryColorFramebuffer: Framebuffer;
@@ -28,7 +28,7 @@ export declare class TextmodeConverter {
      * Resizes all internal framebuffers to match the grid dimensions.
      * @ignore
      */
-    resize(): void;
+    $resize(): void;
     /**
      * Enables or disables the converter.
      * @param enabled Whether to enable or disable the converter.
@@ -46,7 +46,7 @@ export declare class TextmodeConverter {
      * Dispose of all framebuffers used by this converter.
      * This method is idempotent and safe to call multiple times.
      */
-    dispose(): void;
+    $dispose(): void;
     /** Returns the framebuffer containing character data. */
     get characterFramebuffer(): Framebuffer;
     /** Returns the framebuffer containing primary color data. */

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

@@ -8,14 +8,14 @@ import type { Framebuffer } from "../../rendering/webgl/Framebuffer";
  * Abstract base class for all feature-based textmode converters like `'brightness'`.
  */
 export declare abstract class TextmodeFeatureConverter extends TextmodeConverter {
-    protected palette: ColorPalette;
+    protected _palette: ColorPalette;
     protected constructor(renderer: GLRenderer, fontManager: TextmodeFont, grid: TextmodeGrid, options?: any);
     /**
      * Converts the source framebuffer to the target format.
      * @param sourceFramebuffer The source framebuffer to convert.
      * @ignore
      */
-    abstract convert(sourceFramebuffer: Framebuffer): void;
+    abstract $convert(sourceFramebuffer: Framebuffer): void;
     /**
      * Sets the characters used for mapping.
      * @param characters The characters to use for mapping, usually ordered from darkest to brightest.
@@ -73,10 +73,34 @@ 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').
      * @returns RGBA array [r, g, b, a] or null if invalid.
      */
-    private parseHexColor;
+    private _parseHexColor;
 }

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

@@ -34,20 +34,20 @@ export declare class TextmodeFont {
      * @returns Promise that resolves when initialization is complete
      * @ignore
      */
-    initialize(fontSource?: string | URL): Promise<void>;
+    $initialize(fontSource?: string | URL): Promise<void>;
     /**
      * Sets the font size for rendering.
      * @param size The font size to set. If undefined, returns the current font size.
      * @ignore
      */
-    setFontSize(size: number | undefined): void | number;
+    $setFontSize(size: number | undefined): void | number;
     /**
      * Loads a new font from a file path.
      * @param fontPath Path to the .otf or .ttf font file
      * @returns Promise that resolves when font loading is complete
      * @ignore
      */
-    loadFont(fontPath: string): Promise<void>;
+    $loadFont(fontPath: string): Promise<void>;
     /**
      * Loads a FontFace from a font buffer.
      * @param fontBuffer ArrayBuffer containing font data
@@ -76,6 +76,11 @@ export declare class TextmodeFont {
      * @returns `true` if all characters exist in the font, `false` otherwise.
      */
     hasAllCharacters(str: string): boolean;
+    /**
+     * Dispose of all resources used by this font manager.
+     * This method is idempotent and safe to call multiple times.
+     */
+    $dispose(): void;
     /**
      * Returns the WebGL framebuffer containing the font texture atlas.
      * @ignore
@@ -92,11 +97,6 @@ export declare class TextmodeFont {
         width: number;
         height: number;
     };
-    /**
-     * Dispose of all resources used by this font manager.
-     * This method is idempotent and safe to call multiple times.
-     */
-    dispose(): void;
     /** Returns the font size used for rendering. */
     get fontSize(): number;
     /** Returns the Typr.js font object. @ignore */

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
  */