textmode.js 0.4.1-beta.1 → 0.6.0-beta.1

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

@@ -0,0 +1,1085 @@
+import type { GLFramebuffer, GLShader, TextmodeFramebufferOptions, UniformValue } from "../../../rendering/webgl";
+import type { TextmodeImage } from "../../loadables/TextmodeImage";
+import type { TextmodeVideo, TextmodeVideoOptions } from "../../loadables/TextmodeVideo";
+import type { TextmodeColor } from "../../TextmodeColor";
+/**
+ * Interface for rendering capabilities that will be mixed into Textmodifier
+ */
+export interface IRenderingMixin {
+    /**
+     * Set a custom shader for subsequent rendering operations.
+     * @param shader The custom shader to use
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * // Create a custom filter shader
+     * const customShader = t.createFilterShader('
+     *   // ... fragment shader code ...
+     * ');
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Use custom shader
+     *   t.shader(customShader);
+     *   t.setUniform('u_frameCount', t.frameCount);
+     *   t.rect(0, 0, t.grid.cols, t.grid.rows);
+     * });
+     * ```
+     */
+    shader(shader: GLShader): void;
+    /**
+     * Create a new framebuffer for offscreen rendering.
+     *
+    * The framebuffer uses the same MRT structure as the main rendering pipeline.
+    * By default it allocates 4 attachments (character + color data).
+     *
+     * @param options Configuration options for the framebuffer.
+     * @returns A new Framebuffer instance.
+     *
+    * @example
+    * ```javascript
+    * const t = textmode.create({
+    *   width: 800,
+    *   height: 600,
+    * });
+    *
+    * // Create a framebuffer with 50x30 grid cells
+    * const fb = t.createFramebuffer({
+    *   width: 50,
+    *   height: 30
+    * });
+    *
+    * t.draw(() => {
+    *   // Render to framebuffer
+    *   fb.begin();
+    *   t.background(255, 0, 0);
+    *   t.charColor(255);
+    *   t.char('A');
+    *   t.rect(20, 10);
+    *   fb.end();
+    *
+    *   // Render framebuffer to main canvas
+    *   t.background(0);
+    *   t.rotateZ(t.frameCount * 2);
+    *   t.image(fb);
+    * });
+    * ```
+     */
+    createFramebuffer(options: TextmodeFramebufferOptions): GLFramebuffer;
+    /**
+     * Draw a TextmodeFramebuffer or TextmodeImage to the current render target.
+     *
+     * @param source The TextmodeFramebuffer or TextmodeImage 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
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * });
+     *
+     * const fb = t.createFramebuffer({width: 30, height: 20});
+     *
+     * t.draw(() => {
+     *   // Draw something to the framebuffer
+     *   fb.begin();
+     *   t.clear();
+     *   t.charColor(255, 0, 0);
+     *   t.char('A');
+     *   t.rect(20, 10);
+     *   fb.end();
+     *
+     *   // Clear main canvas and render framebuffer content
+     *   t.background(0);
+     *
+     *   // Render at original size
+     *   t.image(fb);
+     *
+     *   // Render scaled version
+     *   // t.image(fb, 60, 40);
+     * });
+     * ```
+     */
+    image(source: GLFramebuffer | TextmodeImage, width?: number, height?: number): void;
+    /**
+     * Load an image and return a TextmodeImage that can be drawn with image().
+     *
+     * The loaded image can be rendered to the canvas using the {@link image} method.
+     * This function returns a Promise that resolves when the image has loaded.
+     *
+     * @param src URL or existing HTMLImageElement
+     * @returns A Promise that resolves to a TextmodeImage object
+     *
+    * @example
+    * ```javascript
+    * const t = textmode.create({
+    *     width: 800,
+    *     height: 600,
+    * });
+    *
+    * let img;
+    *
+    * t.setup(async () => {
+    *     img = await t.loadImage('https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800&q=80');
+    *     img.characters(" .:-=+*#%@");
+    * });
+    *
+    * t.draw(() => {
+    *     t.background(0);
+    *
+    *     if (img) {
+    *         // Draw the loaded image
+    *         t.image(img);
+    *     }
+    * });
+    * ```
+     */
+    loadImage(src: string | HTMLImageElement): Promise<TextmodeImage>;
+    /**
+     * Load a video and return a TextmodeVideo that can be drawn with image().
+     * @param src URL or existing HTMLVideoElement
+     * @param options Optional configuration for preloading behavior. Provide `frameRate` to preload frames, `onProgress` to observe preload progress, `onComplete` to know when preloading finished, and `onError` to catch preload failures.
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *     width: 800,
+     *     height: 600,
+     * });
+     *
+     * let video;
+     *
+     * t.setup(async () => {
+     *     video = await t.loadVideo('https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4');
+     *     // Start playback and enable looping so the video keeps playing
+     *     video.play();
+     *     video.loop();
+     *
+     *     video.characters(" .:-=+*#%@");
+     * });
+     *
+     * t.draw(() => {
+     *     t.background(0);
+     *
+     *     if (video) {
+     *         // Draw the loaded video
+     *         t.image(video);
+     *     }
+     * });
+     * ```
+     */
+    loadVideo(src: string | HTMLVideoElement, options?: TextmodeVideoOptions): Promise<TextmodeVideo>;
+    /**
+     * Set a uniform value for the current custom shader.
+     * @param name The name of the uniform variable
+     * @param value The value to set
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * const shader = t.createFilterShader(`
+     *   uniform float u_time;
+     *   // ... rest of shader ...
+     * `);
+     *
+     * t.draw(() => {
+     *   t.shader(shader);
+     *   t.setUniform('u_time', t.frameCount * 0.02);
+     *   t.rect(0, 0, t.grid.cols, t.grid.rows);
+     * });
+     * ```
+     */
+    setUniform(name: string, value: UniformValue): void;
+    /**
+     * Set multiple uniform values for the current custom shader.
+     * @param uniforms Object containing uniform name-value pairs
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * const shader = t.createFilterShader(`
+     *   uniform float u_time;
+     *   uniform vec2 u_resolution;
+     *   // ... rest of shader ...
+     * `);
+     *
+     * t.draw(() => {
+     *   t.shader(shader);
+     *   t.setUniforms({
+     *     u_time: t.frameCount * 0.02,
+     *     u_resolution: [t.grid.cols, t.grid.rows]
+     *   });
+     *   t.rect(0, 0, t.grid.cols, t.grid.rows);
+     * });
+     * ```
+     */
+    setUniforms(uniforms: Record<string, UniformValue>): void;
+    /**
+     * Create a custom filter shader from fragment shader source code.
+     * The fragment shader automatically receives the standard vertex shader inputs
+     * and must output to the 3 MRT attachments (character/transform, primary color, secondary color).
+     * @param fragmentSource The fragment shader source code
+     * @returns A compiled shader ready for use with {@link shader}
+     *
+    * @example
+    * ```javascript
+    * const t = textmode.create({
+    *   width: 800,
+    *   height: 600,
+    * })
+    *
+    * const waveShader = t.createFilterShader(`#version 300 es
+    *   precision highp float;
+    *
+    *   in vec2 v_uv;
+    *   in vec3 v_character;
+    *   in vec4 v_primaryColor;
+    *   in vec4 v_secondaryColor;
+    *
+    *   uniform float u_time;
+    *
+    *   layout(location = 0) out vec4 o_character;
+    *   layout(location = 1) out vec4 o_primaryColor;
+    *   layout(location = 2) out vec4 o_secondaryColor;
+    *
+    *   float luma(vec3 c) {
+    *     return dot(c, vec3(0.2126, 0.7152, 0.0722));
+    *   }
+    *
+    *   void main() {
+    *     vec2 uv = v_uv * 2.0 - 1.0;
+    *     float time = u_time * 0.4;
+    *     float radial = length(uv);
+    *     float swirl = sin(radial * 9.0 - time) + cos(uv.x * 6.0 + time * 1.3);
+    *     float ripple = sin((uv.x + uv.y) * 10.0 + time * 2.0) * 0.5;
+    *
+    *     // Palette that shifts through warm→cool hues
+    *     vec3 color = vec3(
+    *       0.55 + 0.45 * sin(time + radial * 4.0),
+    *       0.55 + 0.45 * sin(time * 1.3 + uv.y * 5.0 + ripple),
+    *       0.55 + 0.45 * sin(time * 0.9 + uv.x * 5.0 - ripple)
+    *     );
+    *
+    *     float glyphIndex = fract(0.5 + 0.5 * swirl);
+    *     float rotation = fract(0.5 + swirl * 0.25);
+    *     int invertFlag = luma(color) > 0.6 ? 1 : 0;
+    *     float packedFlags = float(invertFlag) / 255.0;
+    *
+    *     o_character = vec4(glyphIndex, 0.0, packedFlags, 0.0);
+    *     o_primaryColor = vec4(color, 1.0);
+    *     o_secondaryColor = vec4(mix(vec3(0.1), color, 0.35), 1.0);
+    *   }
+    * `);
+    *
+    * t.draw(() => {
+    *   t.shader(waveShader);
+    *   t.setUniform('u_time', t.frameCount * 0.003);
+    *   t.rect(t.grid.cols, t.grid.rows);
+    * });
+    * ```
+     */
+    createFilterShader(fragmentSource: string): GLShader;
+    /**
+     * Sets the rotation angles for subsequent shape rendering operations.
+     *
+     * All geometries rotate around the center of the shape.
+     *
+     * @param degreesX The rotation angle in degrees around the X-axis (optional, defaults to 0)
+     * @param degreesY The rotation angle in degrees around the Y-axis (optional, defaults to 0)
+     * @param degreesZ The rotation angle in degrees around the Z-axis (optional, defaults to 0)
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Rotate only around Z-axis (backward compatible)
+     *   t.rotate(0, 0, 45);
+     *
+     *   // Rotate around all three axes
+     *   t.rotate(30, 45, 60);
+     *
+     *   t.rect(10, 10, 5, 5);
+     * });
+     * ```
+     */
+    rotate(degreesX?: number, degreesY?: number, degreesZ?: number): void;
+    /**
+     * Sets the X-axis rotation angle for subsequent shape rendering operations.
+     *
+     * All geometries rotate around the center of the shape.
+     *
+     * @param degrees The rotation angle in degrees around the X-axis
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.rotateX(45); // Rotate around X-axis
+     *   t.rect(10, 10, 5, 5);
+     * });
+     * ```
+     */
+    rotateX(degrees: number): void;
+    /**
+     * Sets the Y-axis rotation angle for subsequent shape rendering operations.
+     *
+     * All geometries rotate around the center of the shape.
+     *
+     * @param degrees The rotation angle in degrees around the Y-axis
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.rotateY(45); // Rotate around Y-axis
+     *   t.rect(10, 10, 5, 5);
+     * });
+     * ```
+     */
+    rotateY(degrees: number): void;
+    /**
+     * Sets the Z-axis rotation angle for subsequent shape rendering operations.
+     *
+     * All geometries rotate around the center of the shape.
+     *
+     * @param degrees The rotation angle in degrees around the Z-axis
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.rotateZ(45); // Rotate around Z-axis
+     *   t.rect(10, 10, 5, 5);
+     * });
+     * ```
+     */
+    rotateZ(degrees: number): void;
+    /**
+     * Sets the translation offsets for subsequent shape rendering operations.
+     *
+     * All geometries are displaced by the specified amounts. Similar to p5.js translate().
+     *
+     * @param x Translation along the X-axis in pixels (optional, defaults to 0)
+     * @param y Translation along the Y-axis in pixels (optional, defaults to 0)
+     * @param z Translation along the Z-axis in pixels (optional, defaults to 0)
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   // Translate in 2D
+     *   t.translate(10, 5);
+     *
+     *   // Translate in 3D
+     *   t.translate(10, 5, 2);
+     *
+     *   t.rect(0, 0, 5, 5); // Drawn at (10, 5) with Z offset
+     * });
+     * ```
+     */
+    translate(x?: number, y?: number, z?: number): void;
+    /**
+     * Sets the X-axis translation offset for subsequent shape rendering operations.
+     *
+     * @param pixels The translation offset in pixels along the X-axis
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.translateX(10); // Translate 10 pixels to the right
+     *   t.rect(0, 0, 5, 5); // Drawn at (10, 0)
+     * });
+     * ```
+     */
+    translateX(pixels: number): void;
+    /**
+     * Sets the Y-axis translation offset for subsequent shape rendering operations.
+     *
+     * @param pixels The translation offset in pixels along the Y-axis
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.translateY(10); // Translate 10 pixels down
+     *   t.rect(0, 0, 5, 5); // Drawn at (0, 10)
+     * });
+     * ```
+     */
+    translateY(pixels: number): void;
+    /**
+     * Sets the Z-axis translation offset for subsequent shape rendering operations.
+     *
+     * @param pixels The translation offset in pixels along the Z-axis
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.translateZ(5); // Move 5 pixels forward in 3D space
+     *   t.rect(10, 10, 5, 5);
+     * });
+     * ```
+     */
+    translateZ(pixels: number): void;
+    /**
+     * Save the current rendering state to the state stack.
+     * Use with {@link pop} to isolate style changes within a block.
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   t.push(); // Save current state
+     *   t.charColor(255, 0, 0); // Red characters
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.char('A');
+     *   t.rect(16, 16);
+     *   t.pop(); // Restore previous state
+     * });
+     * ```
+     */
+    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 = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   t.push(); // Save current state
+     *   t.charColor(0, 255, 0); // Green characters
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.char('A');
+     *   t.rect(16, 16);
+     *   t.pop(); // Restore previous state
+     * });
+     * ```
+     */
+    pop(): void;
+    /**
+     * Create a reusable color object compatible with textmode drawing APIs.
+     *
+     * Accepts grayscale, RGB, RGBA, hex string values as arguments, and
+     * single characters that resolve to their encoded glyph color. Returned
+     * {@link TextmodeColor} instances can be passed to {@link background},
+     * {@link char}, {@link charColor}, {@link cellColor}, and more.
+     *
+     * @param value Grayscale value, hex string, single character, or an existing color
+     * @param g Optional green component, or `value` when using grayscale form
+     * @param b Optional blue component, or `value` when using grayscale form
+    * @param a Optional alpha component when using RGB form
+    *
+    * Example usage of the {@link color} helper.
+    *
+    * @example
+    * ```javascript
+    * const t = textmode.create({ width: 800, height: 600 });
+    *
+    * // Grayscale (0 = black, 255 = white)
+    * const gray = t.color(128);
+    *
+    * // RGB
+    * const hotPink = t.color(255, 105, 180);
+    *
+    * // RGBA (alpha 0-255)
+    * const semiTransparentRed = t.color(255, 0, 0, 128);
+    *
+    * // Hex string
+    * const dusk = t.color('#203040');
+    *
+    * // Single character: resolves to a TextmodeColor that may encode a glyph
+    * let glyphColor;
+    *
+    * t.setup(() => {
+    *     glyphColor = t.color('B'); // Color based on 'B' character glyph
+    * });
+    *
+    * t.draw(() => {
+    *     // Using colors with other drawing APIs
+    *     t.background(gray);
+    *     t.charColor(hotPink);
+    *     t.char('A');
+    *     t.rect(5, 5);
+    *
+    *     t.translate(5, 0);
+    *     t.cellColor(dusk);
+    *     t.char('*');
+    *     t.rect(5, 5);
+    *
+    *     t.translate(5, 0);
+    *     t.charColor("#FF00FF");
+    *     t.char(glyphColor);
+    *     t.rect(5, 5);
+    * });
+    * ```
+    */
+    color(value: number | string | TextmodeColor, g?: number, b?: number, a?: number): TextmodeColor;
+    /**
+     * Draw a rectangle with the current settings.
+     * Position is controlled via {@link translate}, {@link push}, and {@link pop}.
+     * @param width Width of the rectangle
+     * @param height Height of the rectangle
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   // Set the background color to black
+     *   t.background(0);
+     *
+     *   // Position and draw a filled rectangle
+     *   t.char('A');
+     *   t.charColor(255, 255, 255); // White
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.rect(16, 16);
+     * });
+     * ```
+     */
+    rect(width?: number, height?: number): void;
+    /**
+     * Draw a single point at (x, y) with the current settings.
+     * @param x X-coordinate of the point
+     * @param y Y-coordinate of the point
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *
+     *   t.char('*');
+     *   t.point();
+     * });
+     * ```
+     */
+    point(x: number, y: number): void;
+    /**
+     * Draw a line from point (x1, y1) to point (x2, y2) with the settings.
+     * @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 = textmode.create({
+    *   width: 800,
+    *   height: 600,
+    * })
+    *
+    * t.draw(() => {
+    *   t.background(0);
+    *
+    *   t.char('*');
+    *   t.charColor(255, 100, 255); // Magenta
+    *   t.lineWeight(2);
+    *
+    *   const halfWidth = 5;
+    *   const halfHeight = 7.5;
+    *
+    *   t.push();
+    *   t.rotateZ(t.frameCount * 2);
+    *   t.line(-halfWidth, halfHeight, halfWidth, -halfHeight);
+    *   t.pop();
+    * });
+    * ```
+     */
+    line(x1: number, y1: number, x2: number, y2: number): void;
+    /**
+     * Set the background color for the canvas.
+     * @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
+     * @param a Optional alpha component (0-255)
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * });
+     *
+     * const midnight = t.color('#0b1d3a');
+     *
+     * t.draw(() => {
+     *   // Set the background using a reusable color
+     *   t.background(midnight);
+     *
+     *   // Or inline RGB(A) notation
+     *   //t.background(32, 48, 64);
+     *
+     *   // Or hex string
+     *   //t.background('#203040');
+     *
+     *   t.char('M');
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.rect(12, 12);
+     * });
+     * ```
+     */
+    background(value: number | string | TextmodeColor, g?: number, b?: number, a?: number): void;
+    /**
+     * Clear the canvas.
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *  width: 800,
+     *  height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *  // Clear the canvas
+     *  t.clear();
+     * });
+     * ```
+     */
+    clear(): void;
+    /**
+     * Update the line weight (thickness) for subsequent {@link line} and {@link bezierCurve} calls.
+     * @param weight The line weight (thickness) to set.
+     *
+    * @example
+    * ```javascript
+    * const t = textmode.create({
+    *     width: 800,
+    *     height: 600,
+    * })
+    *
+    * t.draw(() => {
+    *     t.background('#050810');
+    *
+    *     // Animate the weight so every line breathes differently
+    *     const layers = 6;
+    *     const halfCols = t.grid.cols / 2;
+    *     const spacing = 4;
+    *
+    *     for (let i = 0; i < layers; i++) {
+    *         const phase = t.frameCount * 0.03 + i * 0.8;
+    *         const pulse = 0.75 + 3.25 * (0.5 + 0.5 * Math.sin(phase));
+    *         const wobble = Math.sin(phase * 1.6) * 4;
+    *         const centeredRow = (i - (layers - 1) / 2) * spacing;
+    *
+    *         t.lineWeight(Math.round(pulse));
+    *         t.charColor(160 + i * 12, 200 - i * 8, 255);
+    *         t.char('-');
+    *         t.line(
+    *             -halfCols + 2,
+    *             centeredRow + wobble,
+    *             halfCols - 2,
+    *             centeredRow - wobble,
+    *         );
+    *     }
+    * });
+    * ```
+     */
+    lineWeight(weight: number): void;
+    /**
+     * Draw a smooth cubic bezier curve between two points with two control points.
+     * The curve thickness is controlled by the current {@link lineWeight} setting.
+     * @param x1 Start point X coordinate
+     * @param y1 Start point Y coordinate
+     * @param cp1x First control point X coordinate
+     * @param cp1y First control point Y coordinate
+     * @param cp2x Second control point X coordinate
+     * @param cp2y Second control point Y coordinate
+     * @param x2 End point X coordinate
+     * @param y2 End point Y coordinate
+     *
+    * @example
+    * ```javascript
+    * const t = textmode.create({
+    *   width: 800,
+    *   height: 600,
+    * })
+    *
+    * t.draw(() => {
+    *   t.background(0);
+    *   t.translate(-t.grid.cols / 2, -t.grid.rows / 2);
+    *
+    *   // Draw a smooth S-curve
+    *   t.char('*');
+    *   t.charColor(255, 100, 255); // Magenta
+    *   t.lineWeight(2);
+    *
+    *   // Rotate the curve around its geometric center
+    *   // The bezier's control points: (5,20), (15,5), (25,35), (35,20)
+    *   // Center = average of points; translate to center then draw with local coordinates
+    *   const cx = (5 + 15 + 25 + 35) / 4;
+    *   const cy = (20 + 5 + 35 + 20) / 4;
+    *
+    *   t.translate(cx, cy);
+    *   t.rotateZ(t.frameCount * 2);
+    *   t.bezierCurve(5 - cx, 20 - cy, 15 - cx, 5 - cy, 25 - cx, 35 - cy, 35 - cx, 20 - cy);
+    * });
+    * ```
+     */
+    bezierCurve(x1: number, y1: number, cp1x: number, cp1y: number, cp2x: number, cp2y: number, x2: number, y2: number): void;
+    /**
+     * Set the character to be used for subsequent rendering operations.
+     * Accepts a single character string or a
+     * {@link TextmodeColor} produced via {@link color}. When a color is provided,
+     * the encoded glyph information is applied if available.
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * let semicolon;
+     *
+     * t.setup(() => {
+     *  semicolon = t.color(';');
+     * });
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.char('A');
+     *   t.rect(10, 10);
+     *
+     *   t.char(semicolon);
+     *   t.translate(15, 0);
+     *   t.rect(10, 10);
+     * });
+     * ```
+     */
+    char(character: string | TextmodeColor): void;
+    /**
+     * Set the character color for subsequent rendering operations.
+     * Accepts channel values, hex strings, or a {@link TextmodeColor} instance.
+     * @param value Color object, hex string, or grayscale value (0-255)
+     * @param g Optional green component when providing RGB values or alpha when using grayscale form
+     * @param b Optional blue component when providing RGB values
+     * @param a Optional alpha component (0-255)
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * const hotPink = t.color(255, 105, 180);
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.char('A');
+     *   t.charColor(hotPink);
+     *   t.rect(10, 10);
+     * });
+     * ```
+     */
+    charColor(value: number | string | TextmodeColor, g?: number, b?: number, a?: number): void;
+    /**
+     * Set the cell background color for subsequent rendering operations.
+     * Accepts channel values, hex strings, or a {@link TextmodeColor} instance.
+     * @param value Color object, hex string, or grayscale value (0-255)
+     * @param g Optional green component when providing RGB values or alpha when using grayscale form
+     * @param b Optional blue component when providing RGB values
+     * @param a Optional alpha component (0-255)
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * const dusk = t.color('#203040');
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.cellColor(dusk);
+     *   t.char('A');
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.rect(10, 10);
+     * });
+     * ```
+     */
+    cellColor(value: number | string | TextmodeColor, g?: number, b?: number, a?: number): void;
+    /**
+     * Toggle horizontal flipping for subsequent character rendering.
+     * @param toggle Whether to flip horizontally
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.flipX(true);
+     *   t.rect(5, 5);
+     * });
+     * ```
+     */
+    flipX(toggle: boolean): void;
+    /**
+     * Toggle vertical flipping for subsequent character rendering.
+     * @param toggle Whether to flip vertically
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.flipY(true);
+     *   t.rect(5, 5);
+     * });
+     * ```
+     */
+    flipY(toggle: boolean): void;
+    /**
+     * Set the character rotation angle for subsequent character rendering.
+     * @param degrees The rotation angle in degrees
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.char('A');
+     *   t.charRotation(90); // Rotate character 90 degrees
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.rect(10, 10);
+     * });
+     * ```
+     */
+    charRotation(degrees: number): void;
+    /**
+     * Toggle color inversion for subsequent character rendering.
+     * @param toggle Whether to invert colors
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.invert(true);
+     *   t.char('A');
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.rect(5, 5);
+     * });
+     * ```
+     */
+    invert(toggle: boolean): void;
+    /**
+     * Draw an ellipse with the current settings.
+     * Position is controlled via {@link translate}, {@link push}, and {@link pop}.
+     * @param width Width of the ellipse
+     * @param height Height of the ellipse
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.char('O');
+     *   t.rotateZ(t.frameCount * 2);
+     *   t.ellipse(10, 8);
+     * });
+     * ```
+     */
+    ellipse(width: number, height: number): void;
+    /**
+     * Draw a triangle with the current settings.
+     * @param x1 X-coordinate of the first vertex
+     * @param y1 Y-coordinate of the first vertex
+     * @param x2 X-coordinate of the second vertex
+     * @param y2 Y-coordinate of the second vertex
+     * @param x3 X-coordinate of the third vertex
+     * @param y3 Y-coordinate of the third vertex
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.triangle(10, 10, 20, 10, 15, 20);
+     * });
+     * ```
+     */
+    triangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number): void;
+    /**
+     * Draw an arc with the current settings.
+     * Position is controlled via {@link translate}, {@link push}, and {@link pop}.
+     * @param width Width of the arc
+     * @param height Height of the arc
+     * @param startAngle Starting angle in degrees
+     * @param endAngle Ending angle in degrees
+     *
+     * @example
+     * ```javascript
+     * const t = textmode.create({
+     *   width: 800,
+     *   height: 600,
+     * })
+     *
+     * t.draw(() => {
+     *   t.background(0);
+     *   t.rotateZ(t.frameCount);
+     *   t.char('A');
+     *   t.arc(10, 10, 0, 90);
+     * });
+     * ```
+     */
+    arc(width: number, height: number, startAngle: number, endAngle: number): void;
+    /**
+     * Enable orthographic projection for the current frame.
+     *
+     * By default, textmode.js uses perspective projection. Calling this function
+     * switches to orthographic projection for all geometries drawn in the current frame.
+     * Orthographic projection renders objects without perspective distortion - parallel
+     * lines remain parallel regardless of depth, and objects don't appear smaller as
+     * they move away from the camera.
+     *
+     * **Note**: The projection mode resets to perspective at the start of each frame,
+     * so `ortho()` must be called in every frame where you want orthographic projection.
+     *
+    * @example
+    * ```javascript
+    * const t = textmode.create({
+    *   width: 800,
+    *   height: 600,
+    * });
+    *
+    * let useOrtho = false;
+    *
+    * // Toggle between ortho and perspective with spacebar
+    * t.keyPressed((data) => {
+    *   if (data.key === ' ') {
+    *     useOrtho = !useOrtho;
+    *   }
+    * });
+    *
+    * t.draw(() => {
+    *   t.background(0);
+    *
+    *   // Enable orthographic projection if toggled on
+    *   if (useOrtho) {
+    *     t.ortho();
+    *   }
+    *
+    *   // Animate the rectangle back and forth on the z-axis
+    *   const zPos = Math.sin(t.frameCount * 0.01) * 50;
+    *
+    *   t.push();
+    *   t.translate(0, 0, zPos);
+    *   t.rotateZ(t.frameCount * 2);
+    *   t.rotateX(t.frameCount * 1.5);
+    *   t.char('A');
+    *   t.charColor(255, 100, 200);
+    *   t.rect(16, 16);
+    *   t.pop();
+    * });
+    * ```
+     */
+    ortho(): void;
+}