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

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

@@ -12,23 +12,30 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
-     *
-     * // Create a custom filter shader
-     * const customShader = t.createFilterShader('
-     *   // ... fragment shader code ...
-     * ');
+     * const t = textmode.create({ width: 800, height: 600 });
+     *
+     * const glitchShader = t.createFilterShader(`#version 300 es
+     *   precision highp float;
+     *   in vec2 v_uv;
+     *   uniform float u_intensity;
+     *   layout(location = 0) out vec4 o_character;
+     *   layout(location = 1) out vec4 o_primaryColor;
+     *   layout(location = 2) out vec4 o_secondaryColor;
+     *
+     *   void main() {
+     *     vec2 offset = vec2(sin(v_uv.y * 50.0) * u_intensity, 0.0);
+     *     float pattern = fract(v_uv.x * 20.0 + offset.x);
+     *     vec3 color = vec3(pattern, 1.0 - pattern, 0.5);
+     *     o_character = vec4(pattern, 0.0, 0.0, 0.0);
+     *     o_primaryColor = vec4(color, 1.0);
+     *     o_secondaryColor = vec4(color * 0.5, 1.0);
+     *   }
+     * `);
      *
      * 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);
+     *   t.shader(glitchShader);
+     *   t.setUniform('u_intensity', Math.sin(t.frameCount * 0.1) * 0.02);
+     *   t.rect(t.grid.cols, t.grid.rows);
      * });
      * ```
      */
@@ -186,20 +193,29 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * const t = textmode.create({ width: 800, height: 600 });
      *
-     * const shader = t.createFilterShader(`
+     * const pulseShader = t.createFilterShader(`#version 300 es
+     *   precision highp float;
+     *   in vec2 v_uv;
      *   uniform float u_time;
-     *   // ... rest of shader ...
+     *   layout(location = 0) out vec4 o_character;
+     *   layout(location = 1) out vec4 o_primaryColor;
+     *   layout(location = 2) out vec4 o_secondaryColor;
+     *
+     *   void main() {
+     *     float pulse = 0.5 + 0.5 * sin(u_time + length(v_uv - 0.5) * 8.0);
+     *     vec3 color = vec3(pulse * 0.3, pulse * 0.8, pulse);
+     *     o_character = vec4(pulse, 0.0, 0.0, 0.0);
+     *     o_primaryColor = vec4(color, 1.0);
+     *     o_secondaryColor = vec4(color * 0.3, 1.0);
+     *   }
      * `);
      *
      * t.draw(() => {
-     *   t.shader(shader);
-     *   t.setUniform('u_time', t.frameCount * 0.02);
-     *   t.rect(0, 0, t.grid.cols, t.grid.rows);
+     *   t.shader(pulseShader);
+     *   t.setUniform('u_time', t.frameCount * 0.005);
+     *   t.rect(t.grid.cols, t.grid.rows);
      * });
      * ```
      */
@@ -210,34 +226,44 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * const t = textmode.create({ width: 800, height: 600 });
      *
-     * const shader = t.createFilterShader(`
+     * const rippleShader = t.createFilterShader(`#version 300 es
+     *   precision highp float;
+     *   in vec2 v_uv;
      *   uniform float u_time;
-     *   uniform vec2 u_resolution;
-     *   // ... rest of shader ...
+     *   uniform vec2 u_center;
+     *   layout(location = 0) out vec4 o_character;
+     *   layout(location = 1) out vec4 o_primaryColor;
+     *   layout(location = 2) out vec4 o_secondaryColor;
+     *
+     *   void main() {
+     *     float dist = length(v_uv - u_center);
+     *     float wave = sin(dist * 20.0 - u_time * 2.0) * 0.5 + 0.5;
+     *     vec3 color = mix(vec3(0.2, 0.4, 0.8), vec3(0.9, 0.6, 0.3), wave);
+     *     o_character = vec4(wave, 0.0, 0.0, 0.0);
+     *     o_primaryColor = vec4(color, 1.0);
+     *     o_secondaryColor = vec4(color * 0.4, 1.0);
+     *   }
      * `);
      *
      * t.draw(() => {
-     *   t.shader(shader);
+     *   t.shader(rippleShader);
      *   t.setUniforms({
-     *     u_time: t.frameCount * 0.02,
-     *     u_resolution: [t.grid.cols, t.grid.rows]
+     *     u_time: t.frameCount * 0.0005,
+     *     u_center: [0.5, 0.5]
      *   });
-     *   t.rect(0, 0, t.grid.cols, t.grid.rows);
+     *   t.rect(t.grid.cols, t.grid.rows);
      * });
      * ```
      */
     setUniforms(uniforms: Record<string, UniformValue>): void;
     /**
-     * Create a custom filter shader from fragment shader source code.
+     * Create a custom filter shader from fragment shader source code or a file path.
      * 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}
+     * @param fragmentSource The fragment shader source code or a file path (e.g., './shader.frag')
+     * @returns A Promise that resolves to a compiled shader ready for use with {@link shader}
      *
     * @example
     * ```javascript
@@ -246,57 +272,43 @@ export interface IRenderingMixin {
     *   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;
+    * let waveShader;
     *
-    *     // 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;
+    * t.setup(async () => {
+    *   // Load shader from file
+    *   waveShader = await t.createFilterShader('./shader.frag');
     *
-    *     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);
-    *   }
-    * `);
+    *   // Or create from inline source
+    *   // waveShader = await 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;
+    *   //
+    *   //   void main() {
+    *   //     // Shader code here
+    *   //   }
+    *   // `);
+    * });
     *
     * t.draw(() => {
-    *   t.shader(waveShader);
-    *   t.setUniform('u_time', t.frameCount * 0.003);
-    *   t.rect(t.grid.cols, t.grid.rows);
+    *   if (waveShader) {
+    *     t.shader(waveShader);
+    *     t.setUniform('u_time', t.frameCount * 0.003);
+    *     t.rect(t.grid.cols, t.grid.rows);
+    *   }
     * });
     * ```
      */
-    createFilterShader(fragmentSource: string): GLShader;
+    createFilterShader(fragmentSource: string): Promise<GLShader>;
     /**
      * Sets the rotation angles for subsequent shape rendering operations.
      *
@@ -308,21 +320,25 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * 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);
+     *   // Draw three rectangles rotating in 3D space with different axes
+     *   for (let i = 0; i < 3; i++) {
+     *     t.push();
+     *     t.translate(i * 15 - 15, 0, 0);
      *
-     *   // Rotate around all three axes
-     *   t.rotate(30, 45, 60);
+     *     const angle = t.frameCount * (1.5 + i * 0.5);
+     *     // Each shape rotates around different combinations of axes
+     *     t.rotate(angle * 0.7, angle * 0.5, angle);
      *
-     *   t.rect(10, 10, 5, 5);
+     *     t.char(['T', 'X', 'T'][i]);
+     *     t.charColor(100 + i * 60, 200 - i * 40, 255);
+     *     t.rect(10, 10);
+     *     t.pop();
+     *   }
      * });
      * ```
      */
@@ -336,15 +352,14 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * 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);
+     *   t.char('A');
+     *   t.charColor(255, 150, 100);
+     *   t.rotateX(t.frameCount * 2); // Flip forward/backward
+     *   t.rect(12, 12);
      * });
      * ```
      */
@@ -358,15 +373,14 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * 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);
+     *   t.char('B');
+     *   t.charColor(100, 255, 200);
+     *   t.rotateY(t.frameCount * 2); // Spin left/right
+     *   t.rect(12, 12);
      * });
      * ```
      */
@@ -380,15 +394,14 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * 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);
+     *   t.char('C');
+     *   t.charColor(255, 220, 100);
+     *   t.rotateZ(t.frameCount * 2); // Spin clockwise
+     *   t.rect(12, 12);
      * });
      * ```
      */
@@ -404,21 +417,20 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * 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
+     *   // Draw a grid of shapes with different translations
+     *   for (let i = 0; i < 3; i++) {
+     *     t.push();
+     *     t.translate(i * 12 - 12, Math.sin(t.frameCount * 0.05 + i) * 3);
+     *     t.char('A');
+     *     t.charColor(100 + i * 70, 150, 255 - i * 50);
+     *     t.rect(8, 8);
+     *     t.pop();
+     *   }
      * });
      * ```
      */
@@ -430,15 +442,14 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * 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)
+     *   t.char('→');
+     *   t.charColor(255, 180, 100);
+     *   t.translateX(Math.sin(t.frameCount * 0.05) * 15); // Slide left/right
+     *   t.rect(10, 10);
      * });
      * ```
      */
@@ -450,15 +461,14 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * 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)
+     *   t.char('↓');
+     *   t.charColor(100, 255, 180);
+     *   t.translateY(Math.sin(t.frameCount * 0.05) * 10); // Bounce up/down
+     *   t.rect(10, 10);
      * });
      * ```
      */
@@ -470,15 +480,14 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * 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);
+     *   t.char('O');
+     *   t.charColor(180, 120, 255);
+     *   t.translateZ(Math.sin(t.frameCount * 0.05) * 20); // Pulse in/out
+     *   t.rect(12, 12);
      * });
      * ```
      */
@@ -489,20 +498,21 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * 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
+     *   // Draw three rotating shapes with isolated transformations and colors
+     *   for (let i = 0; i < 3; i++) {
+     *     t.push(); // Save state
+     *     t.translate(i * 12 - 12, 0);
+     *     t.rotateZ(t.frameCount * (1 + i * 0.5));
+     *     t.charColor(100 + i * 70, 255 - i * 50, 150);
+     *     t.char(['*', '@', '#'][i]);
+     *     t.rect(8, 8);
+     *     t.pop(); // Restore state - next iteration starts fresh
+     *   }
      * });
      * ```
      */
@@ -513,20 +523,21 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * 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
+     *   // Draw three rotating shapes with isolated transformations and colors
+     *   for (let i = 0; i < 3; i++) {
+     *     t.push(); // Save state
+     *     t.translate(i * 12 - 12, 0);
+     *     t.rotateZ(t.frameCount * (1 + i * 0.5));
+     *     t.charColor(100 + i * 70, 255 - i * 50, 150);
+     *     t.char(['*', '@', '#'][i]);
+     *     t.rect(8, 8);
+     *     t.pop(); // Restore state - next iteration starts fresh
+     *   }
      * });
      * ```
      */
@@ -616,26 +627,48 @@ export interface IRenderingMixin {
      */
     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
+     * Draw a 1x1 rectangle with the current settings.
      *
      * @example
-     * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
-     *
-     * t.draw(() => {
-     *   t.background(0);
-     *
-     *   t.char('*');
-     *   t.point();
-     * });
+    * ```javascript
+    * const t = textmode.create({ width: 800, height: 600 });
+    *
+    * t.draw(() => {
+    *   t.background(0);
+    *
+    *   const angle = t.frameCount * 0.06;
+    *   const radius = Math.min(t.grid.cols, t.grid.rows) * 0.35;
+    *
+    *   // Draw a short trail of points behind the leading point
+    *   for (let i = 0; i < 10; i++) {
+    *     const a = angle - i * 0.18;
+    *     const r = radius * (1 - i * 0.08);
+    *     const x = Math.round(Math.cos(a) * r);
+    *     const y = Math.round(Math.sin(a) * r);
+    *
+    *     // Color and brightness fade across the trail
+    *     const brightness = Math.max(40, 255 - i * 20);
+    *     const blue = Math.max(60, 255 - i * 25);
+    *     const green = 120 + i * 8;
+    *
+    *     t.push();
+    *     t.translate(x, y);
+    *     t.char('*');
+    *     t.charColor(brightness, green, blue);
+    *     t.point();
+    *
+    *     t.pop();
+    *   }
+    *
+    *   // Leading point drawn with highest brightness
+    *   t.char('@');
+    *   t.charColor(255, 255, 160);
+    *   t.translate(Math.round(Math.cos(angle) * radius), Math.round(Math.sin(angle) * radius));
+    *   t.point();
+    * });
      * ```
      */
-    point(x: number, y: number): void;
+    point(): void;
     /**
      * Draw a line from point (x1, y1) to point (x2, y2) with the settings.
      * @param x1 X-coordinate of the line start point
@@ -995,14 +1028,20 @@ export interface IRenderingMixin {
      *
      * @example
      * ```javascript
-     * const t = textmode.create({
-     *   width: 800,
-     *   height: 600,
-     * })
+     * const t = textmode.create({ width: 800, height: 600 });
      *
      * t.draw(() => {
      *   t.background(0);
-     *   t.triangle(10, 10, 20, 10, 15, 20);
+     *   t.char('*');
+     *   t.charColor(255, 100, 150);
+     *
+     *   const angle = t.frameCount * 0.02;
+     *   const size = 15;
+     *   t.triangle(
+     *     Math.cos(angle) * size, Math.sin(angle) * size,
+     *     Math.cos(angle + 2.09) * size, Math.sin(angle + 2.09) * size,
+     *     Math.cos(angle + 4.19) * size, Math.sin(angle + 4.19) * size
+     *   );
      * });
      * ```
      */

package/package.json

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