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

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

@@ -0,0 +1,155 @@
+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';
+/**
+ * Interface for export capabilities that will be mixed into Textmodifier
+ */
+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;
+    /**
+     * Export the current textmode rendering to an image file.
+     * @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>;
+}
+/**
+ * Mixin that adds export capabilities to a class
+ * @param Base The base class to extend
+ * @returns Extended class with export capabilities
+ */
+export declare const ExportMixin: Mixin<ExportCapabilities>;

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

@@ -0,0 +1,49 @@
+import type { Mixin } from './TextmodifierMixin';
+/**
+ * Interface for font capabilities that will be mixed into Textmodifier
+ */
+export interface FontCapabilities {
+    /**
+     * Update the font used for rendering.
+     * @param fontSource The URL of the font to load.
+     *
+     * @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);
+     *
+     * // Load a custom font from a URL
+     * await textmodifier.loadFont('https://example.com/fonts/myfont.ttf');
+     *
+     * // Local font example
+     * // await textmodifier.loadFont('./fonts/myfont.ttf');
+     * ```
+     */
+    loadFont(fontSource: string): Promise<void>;
+    /**
+     * Set the font size used for rendering.
+     * @param size The font size to set.
+     *
+     * @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);
+     *
+     * // Set the font size to 24
+     * textmodifier.fontSize(24);
+     * ```
+     */
+    fontSize(size: number): void;
+}
+/**
+ * Mixin that adds font capabilities to a class
+ * @param Base The base class to extend
+ * @returns Extended class with font capabilities
+ */
+export declare const FontMixin: Mixin<FontCapabilities>;

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

@@ -0,0 +1,409 @@
+import type { Mixin } from './TextmodifierMixin';
+import type { Shader } from '../../rendering';
+/**
+ * Interface for rendering capabilities that will be mixed into Textmodifier
+ */
+export interface RenderingCapabilities {
+    /**
+     * Sets the fill color for subsequent rendering operations
+     * @param r Red component (0-255)
+     * @param g Green component (0-255, optional)
+     * @param b Blue component (0-255, optional)
+     * @param a Alpha component (0-255, optional)
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   // Set the background color to black
+     *   t.background(0);
+     *
+     *   const centerX = t.width / 2;
+     *   const centerY = t.height / 2;
+     *   const radius = Math.min(t.width, t .height) / 3;
+     *   const speed = 0.02; // Adjust speed of rotation
+     *
+     *   const angle = t.frameCount * speed;
+     *   const x = centerX + Math.cos(angle) * radius - 100;
+     *   const y = centerY + Math.sin(angle) * radius - 50;
+     *
+     *   // Set the fill color to white
+     *   t.fill(255);
+     *
+     *   // Draw a rectangle with the fill color
+     *   t.rect(x, y, 200, 150);
+     * });
+     * ```
+     */
+    fill(r: number, g?: number, b?: number, a?: number): void;
+    /**
+     * Sets the stroke color for subsequent rendering operations
+     * @param r Red component (0-255)
+     * @param g Green component (0-255, optional)
+     * @param b Blue component (0-255, optional)
+     * @param a Alpha component (0-255, optional)
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   // Set the background color to black
+     *   t.background(0);
+     *
+     *   // Set stroke color to red and stroke weight to 4 pixels
+     *   t.stroke(255, 0, 0);
+     *   t.strokeWeight(4);
+     *
+     *   // Draw a rectangle with red stroke
+     *   t.rect(100, 100, 200, 150);
+     *
+     *   // Rectangle with both fill and stroke
+     *   t.fill(0, 255, 0);
+     *   t.stroke(0, 0, 255);
+     *   t.strokeWeight(2);
+     *   t.rect(350, 100, 200, 150);
+     * });
+     * ```
+     */
+    stroke(r: number, g?: number, b?: number, a?: number): void;
+    /**
+     * Sets the stroke weight (thickness) for subsequent stroke operations
+     * @param weight The stroke thickness in pixels
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Thin stroke
+     *   t.stroke(255);
+     *   t.strokeWeight(1);
+     *   t.rect(50, 50, 100, 100);
+     *
+     *   // Thick stroke
+     *   t.strokeWeight(8);
+     *   t.rect(200, 50, 100, 100);
+     * });
+     * ```
+     */
+    strokeWeight(weight: number): void;
+    /**
+     * Disables stroke rendering for subsequent operations
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Rectangle with stroke
+     *   t.fill(255, 0, 0);
+     *   t.stroke(0, 255, 0);
+     *   t.strokeWeight(4);
+     *   t.rect(100, 100, 150, 100);
+     *
+     *   // Rectangle without stroke (fill only)
+     *   t.noStroke();
+     *   t.rect(300, 100, 150, 100);
+     * });
+     * ```
+     */
+    noStroke(): void;
+    /**
+     * Disables fill rendering for subsequent operations
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Rectangle with fill
+     *   t.fill(255, 0, 0);
+     *   t.stroke(0, 255, 0);
+     *   t.strokeWeight(4);
+     *   t.rect(100, 100, 150, 100);
+     *
+     *   // Rectangle without fill (stroke only)
+     *   t.noFill();
+     *   t.rect(300, 100, 150, 100);
+     * });
+     * ```
+     */
+    noFill(): void;
+    /**
+     * Sets the rotation angle for subsequent rendering operations
+     * @param degrees The rotation angle in degrees
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Normal rectangle
+     *   t.fill(255, 0, 0);
+     *   t.rect(100, 100, 150, 100);
+     *
+     *   // Rotated rectangle
+     *   t.push(); // Save current state
+     *   t.rotate(45); // Rotate 45 degrees
+     *   t.fill(0, 255, 0);
+     *   t.rect(300, 100, 150, 100);
+     *   t.pop(); // Restore state (no rotation)
+     *
+     *   // Back to normal (no rotation)
+     *   t.fill(0, 0, 255);
+     *   t.rect(500, 100, 150, 100);
+     * });
+     * ```
+     */
+    rotate(degrees: number): void;
+    /**
+     * Save the current rendering state (fill, stroke, etc.) to the state stack.
+     * Use with {@link pop} to isolate style changes within a block.
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Set initial styles
+     *   t.fill(255, 0, 0);      // Red fill
+     *   t.stroke(0, 255, 0);    // Green stroke
+     *   t.strokeWeight(4);      // Thick stroke
+     *
+     *   t.push(); // Save current state
+     *
+     *   // Change styles temporarily
+     *   t.fill(0, 0, 255);      // Blue fill
+     *   t.stroke(255, 255, 0);  // Yellow stroke
+     *   t.strokeWeight(2);      // Thin stroke
+     *   t.rect(100, 100, 150, 100);
+     *
+     *   t.pop(); // Restore previous state
+     *
+     *   // Back to red fill, green stroke, thick stroke
+     *   t.rect(300, 100, 150, 100);
+     * });
+     * ```
+     */
+    push(): void;
+    /**
+     * Restore the most recently saved rendering state from the state stack.
+     * Use with {@link push} to isolate style changes within a block.
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Default styles
+     *   t.fill(255);           // White fill
+     *   t.stroke(0);           // Black stroke
+     *   t.strokeWeight(1);     // Thin stroke
+     *
+     *   t.push(); // Save current state
+     *
+     *   // Temporary style changes
+     *   t.fill(255, 0, 0);     // Red fill
+     *   t.strokeWeight(8);     // Thick stroke
+     *   t.rect(50, 50, 100, 100);
+     *
+     *   t.push(); // Save red style state
+     *
+     *   t.fill(0, 255, 0);     // Green fill
+     *   t.noStroke();          // No stroke
+     *   t.rect(200, 50, 100, 100);
+     *
+     *   t.pop(); // Back to red fill, thick stroke
+     *   t.rect(350, 50, 100, 100);
+     *
+     *   t.pop(); // Back to white fill, black stroke, thin stroke
+     *   t.rect(500, 50, 100, 100);
+     * });
+     * ```
+     */
+    pop(): void;
+    /**
+     * Draw a rectangle with the current shader or fill color.
+     * @param x X-coordinate of the rectangle
+     * @param y Y-coordinate of the rectangle
+     * @param width Width of the rectangle
+     * @param height Height of the rectangle
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   // Set the background color to black
+     *   t.background(0);
+     *
+     *   const centerX = t.width / 2;
+     *   const centerY = t.height / 2;
+     *   const radius = Math.min(t.width, t .height) / 3;
+     *   const speed = 0.02; // Adjust speed of rotation
+     *
+     *   const angle = t.frameCount * speed;
+     *   const x = centerX + Math.cos(angle) * radius - 100;
+     *   const y = centerY + Math.sin(angle) * radius - 50;
+     *
+     *   // Set the fill color to white
+     *   t.fill(255);
+     *
+     *   // Draw a rectangle with the fill color
+     *   t.rect(x, y, 200, 150);
+     * });
+     * ```
+     */
+    rect(x: number, y: number, width?: number, height?: number): void;
+    /**
+     * Draw a line from point (x1, y1) to point (x2, y2) with the current stroke settings.
+     * Lines respect stroke color, stroke weight, and rotation, but ignore fill properties.
+     * @param x1 X-coordinate of the line start point
+     * @param y1 Y-coordinate of the line start point
+     * @param x2 X-coordinate of the line end point
+     * @param y2 Y-coordinate of the line end point
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   // Set the background color to black
+     *   t.background(0);
+     *
+     *   // Draw a simple line
+     *   t.stroke(255, 0, 0); // Red stroke
+     *   t.strokeWeight(2);   // 2px thick
+     *   t.line(100, 100, 300, 200);
+     *
+     *   // Draw an animated rotating line
+     *   t.push();
+     *   t.stroke(0, 255, 0); // Green stroke
+     *   t.strokeWeight(4);   // 4px thick
+     *   t.rotate(t.frameCount * 2); // Rotate based on frame count
+     *   t.line(400, 300, 600, 300);
+     *   t.pop();
+     *
+     *   // Draw a thick yellow line
+     *   t.stroke(255, 255, 0); // Yellow stroke
+     *   t.strokeWeight(8);     // 8px thick
+     *   t.line(200, 400, 400, 500);
+     *
+     *   // Line with no stroke won't be visible
+     *   t.noStroke();
+     *   t.line(500, 100, 700, 200); // This won't render
+     * });
+     * ```
+     */
+    line(x1: number, y1: number, x2: number, y2: number): void;
+    /**
+     * Set the background color for the canvas.
+     * @param r Red component (0-255)
+     * @param g Green component (0-255, optional)
+     * @param b Blue component (0-255, optional)
+     * @param a Alpha component (0-255, optional)
+     *
+     * @example
+     * ```javascript
+     * const t = await textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   // Set the background color to black
+     *   t.background(0);
+     *
+     *   const centerX = t.width / 2;
+     *   const centerY = t.height / 2;
+     *   const radius = Math.min(t.width, t .height) / 3;
+     *   const speed = 0.02; // Adjust speed of rotation
+     *
+     *   const angle = t.frameCount * speed;
+     *   const x = centerX + Math.cos(angle) * radius - 100;
+     *   const y = centerY + Math.sin(angle) * radius - 50;
+     *
+     *   // Set the fill color to white
+     *   t.fill(255);
+     *
+     *   // Draw a rectangle with the fill color
+     *   t.rect(x, y, 200, 150);
+     * });
+     * ```
+     */
+    background(r: number, g?: number, b?: number, a?: number): void;
+    /**
+     * Create a shader program from vertex and fragment source code.
+     * @param vertexSource The GLSL source code for the vertex shader.
+     * @param fragmentSource The GLSL source code for the fragment shader.
+     * @returns The created shader program for use in `textmode.js`.
+     */
+    createShader(vertexSource: string, fragmentSource: string): Shader;
+    /**
+     * Create a filter shader program from a fragment source code.
+     * @param fragmentSource The GLSL source code for the fragment shader.
+     * @returns The created filter shader program for use in `textmode.js`.
+     */
+    createFilterShader(fragmentSource: string): Shader;
+    /**
+     * Set the current shader for rendering.
+     * @param shader The shader program to use for rendering.
+     */
+    shader(shader: Shader): void;
+    /**
+     * Set a uniform variable for the current shader.
+     * @param name The name of the uniform variable to set.
+     * @param value The value to set for the uniform variable.
+     */
+    setUniform(name: string, value: any): void;
+}
+/**
+ * Mixin that adds rendering capabilities to a class by delegating to GLRenderer
+ * @param Base The base class to extend
+ * @returns Extended class with rendering capabilities
+ */
+export declare const RenderingMixin: Mixin<RenderingCapabilities>;