textmode.synth.js 1.0.0-beta.1

package/dist/types/index.d.ts

@@ -0,0 +1,395 @@
+/**
+ * A `hydra`-inspired chainable visual synthesis system for `textmode.js`.
+ * Enables procedural generation of characters, colors, and visual effects
+ * through method chaining.
+ *
+ * @example
+ * ```ts
+ * import { textmode } from 'textmode.js';
+ * import { SynthPlugin, osc, noise } from 'textmode.synth.js';
+ *
+ * // Create textmode instance with SynthPlugin
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   fontSize: 16,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Create a synth chain with procedural characters and colors
+ * const synth = noise(10)
+ *   .rotate(0.1)
+ *   .scroll(0.1, 0)
+ *
+ *   .charColor(osc(5).kaleid(4))
+ *   .cellColor(osc(5).kaleid(4).invert())
+ *
+ *   .charMap('@#%*+=-:. ');
+ *
+ *
+ * // Apply synth to the base layer
+ * t.layers.base.synth(synth);
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { SynthSource } from './core/SynthSource';
+import type { SynthContext } from './core/types';
+/**
+ * Create a character source from any color/pattern source.
+ *
+ * This function converts any pattern (like `osc()`, `noise()`, `voronoi()`) into
+ * character indices. The pattern's luminance or color values are mapped to character indices.
+ *
+ * This is the recommended way to define character generation in textmode.synth.js,
+ * as it provides a unified, compositional API where the same patterns can drive
+ * characters, character colors, and cell colors.
+ *
+ * @param source - A SynthSource producing color values that will be mapped to characters
+ * @param charCount - Number of different characters to use (default: 256)
+ * @returns A new SynthSource configured for character generation
+ *
+ * @example
+ * ```typescript
+ * // Simple usage - same pattern for chars and colors
+ * const pattern = osc(1, 0.1);
+ * layer.synth(
+ *   char(pattern)
+ *     .charColor(pattern.clone())
+ * );
+ *
+ * // With limited character count
+ * layer.synth(
+ *   char(noise(10), 16)
+ *     .charMap('@#%*+=-:. ')
+ * );
+ * ```
+ */
+export declare const char: (source: SynthSource, charCount?: number) => SynthSource;
+/**
+ * Create a synth source with character foreground color defined.
+ *
+ * This function creates a SynthSource where the character foreground color
+ * is driven by the provided source pattern. This is compositional and can be
+ * combined with `char()` and `cellColor()`.
+ *
+ * @param source - A SynthSource producing color values for character foreground
+ * @returns A new SynthSource configured with character color
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Start with character color
+ * const pattern = osc(10, 0.1);
+ * t.layers.base.synth(
+ *   charColor(pattern)
+ *     .char(noise(10))
+ *     .cellColor(solid(0, 0, 0, 0.5))
+ * );
+ *
+ * // Using different patterns for each aspect
+ * t.layers.base.synth(
+ *   charColor(voronoi(5).mult(osc(20)))
+ *     .char(noise(10), 16)
+ *     .charMap('@#%*+=-:. ')
+ * );
+ * ```
+ */
+export declare const charColor: (source: SynthSource) => SynthSource;
+/**
+ * Create a synth source with cell background color defined.
+ *
+ * This function creates a SynthSource where the cell background color
+ * is driven by the provided source pattern. This is compositional and can be
+ * combined with `char()` and `charColor()`.
+ *
+ * @param source - A SynthSource producing color values for cell background
+ * @returns A new SynthSource configured with cell color
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Start with cell color
+ * t.layers.base.synth(
+ *   cellColor(solid(0, 0, 0, 0.5))
+ *     .char(noise(10))
+ *     .charColor(osc(5))
+ * );
+ *
+ * // Complete composition - all three defined
+ * const colorPattern = voronoi(5, 0.3);
+ * t.layers.base.synth(
+ *   cellColor(colorPattern.clone().invert())
+ *     .char(noise(10), 16)
+ *     .charMap('@#%*+=-:. ')
+ *     .charColor(colorPattern)
+ * );
+ * ```
+ */
+export declare const cellColor: (source: SynthSource) => SynthSource;
+/**
+ * Create a synth source with both character and cell colors defined.
+ *
+ * This function creates a SynthSource where both the character foreground color
+ * and the cell background color are driven by the same source pattern.
+ * This is a convenience function equivalent to calling both `charColor()` and
+ * `cellColor()` with the same source.
+ *
+ * @param source - A SynthSource producing color values for both character and cell colors
+ * @returns A new SynthSource configured with both color sources
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Use same pattern for both foreground and background colors
+ * const colorPattern = osc(10, 0.1).mult(voronoi(5));
+ * t.layers.base.synth(
+ *   paint(colorPattern)
+ *     .char(noise(10), 16)
+ *     .charMap('@#%*+=-:. ')
+ * );
+ *
+ * // Paint with gradient
+ * t.layers.base.synth(
+ *   paint(gradient(0.5))
+ * );
+ * ```
+ */
+export declare const paint: (source: SynthSource) => SynthSource;
+export { SynthPlugin } from './SynthPlugin';
+export type { SynthTransformType, SynthParameterValue, SynthContext, } from './core/types';
+export { SynthSource } from './core/SynthSource';
+/**
+ * Generate oscillating patterns using sine waves.
+ * @param frequency - Frequency of the oscillation (default: 60.0)
+ * @param sync - Synchronization offset (default: 0.1)
+ * @param offset - Phase offset (default: 0.0)
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Basic oscillating color pattern
+ * t.layers.base.synth(
+ *   osc(1, 0.1)
+ *     .charColor(osc(10, 0.1))
+ * );
+ *
+ * // Animated frequency using array modulation
+ * t.layers.base.synth(
+ *   osc([1, 10, 50, 100].fast(2), 0.001)
+ *     .charColor(osc([1, 10, 50, 100].fast(2), 0.001))
+ * );
+ * ```
+ */
+export declare const osc: (frequency?: number | number[] | ((ctx: SynthContext) => number), sync?: number | number[] | ((ctx: SynthContext) => number), offset?: number | number[] | ((ctx: SynthContext) => number)) => SynthSource;
+/**
+ * Generate Perlin noise patterns.
+ * @param scale - Scale of the noise pattern (default: 10.0)
+ * @param offset - Offset in noise space (default: 0.1)
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Basic noise pattern
+ * t.layers.base.synth(
+ *   noise(10, 0.1)
+ *     .charColor(noise(10, 0.1))
+ * );
+ * ```
+ */
+export declare const noise: (scale?: number | number[] | ((ctx: SynthContext) => number), offset?: number | number[] | ((ctx: SynthContext) => number)) => SynthSource;
+/**
+ * Generate Voronoi (cellular) patterns.
+ * @param scale - Scale of Voronoi cells (default: 5.0)
+ * @param speed - Animation speed (default: 0.3)
+ * @param blending - Blending between cell regions (default: 0.3)
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Animated Voronoi pattern
+ * t.layers.base.synth(
+ *   voronoi(5, 0.3, 0.3)
+ *     .charColor(voronoi(5, 0.3, 0.3))
+ * );
+ * ```
+ */
+export declare const voronoi: (scale?: number | number[] | ((ctx: SynthContext) => number), speed?: number | number[] | ((ctx: SynthContext) => number), blending?: number | number[] | ((ctx: SynthContext) => number)) => SynthSource;
+/**
+ * Generate a rotating radial gradient.
+ * @param speed - Rotation speed (default: 0.0)
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Animated gradient with array modulation
+ * t.layers.base.synth(
+ *   gradient([1, 2, 4])
+ *     .charColor(gradient([1, 2, 4]))
+ *     .cellColor(
+ *       gradient([1, 2, 4])
+ *         .invert((ctx) => Math.sin(ctx.time) * 2)
+ *     )
+ * );
+ * ```
+ */
+export declare const gradient: (speed?: number | number[] | ((ctx: SynthContext) => number)) => SynthSource;
+/**
+ * Generate geometric shapes (polygons).
+ * @param sides - Number of sides (default: 3)
+ * @param radius - Radius of the shape (default: 0.3)
+ * @param smoothing - Edge smoothing amount (default: 0.01)
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Triangle
+ * t.layers.base.synth(
+ *   shape(3)
+ *     .charMap('. ')
+ * );
+ *
+ * // High-sided polygon (circle-like)
+ * t.layers.base.synth(
+ *   shape(100)
+ *     .charMap('. ')
+ * );
+ * ```
+ */
+export declare const shape: (sides?: number | number[] | ((ctx: SynthContext) => number), radius?: number | number[] | ((ctx: SynthContext) => number), smoothing?: number | number[] | ((ctx: SynthContext) => number)) => SynthSource;
+/**
+ * Generate a solid color.
+ * @param r - Red channel (0-1, default: 0.0)
+ * @param g - Green channel (0-1, default: 0.0)
+ * @param b - Blue channel (0-1, default: 0.0)
+ * @param a - Alpha channel (0-1, default: 1.0)
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Solid colors with array modulation
+ * t.layers.base.synth(
+ *   solid(0.6, 0, 0, 1)
+ *     .charColor(solid([1, 0, 0], [0, 1, 0], [0, 0, 1], 1))
+ *     .cellColor(
+ *       solid([1, 0, 0], [0, 1, 0], [0, 0, 1], 1)
+ *         .invert()
+ *     )
+ * );
+ * ```
+ */
+export declare const solid: (r?: number | number[] | ((ctx: SynthContext) => number), g?: number | number[] | ((ctx: SynthContext) => number), b?: number | number[] | ((ctx: SynthContext) => number), a?: number | number[] | ((ctx: SynthContext) => number)) => SynthSource;
+/**
+ * Sample the previous frame's primary color output for feedback effects.
+ * This is the core of feedback loops - it reads from the previous frame's
+ * character foreground color, enabling effects like trails, motion blur,
+ * and recursive patterns.
+ *
+ * **Context-aware behavior:** When called without arguments, `src()` automatically
+ * samples the appropriate texture based on where it's used in the synth chain:
+ * - Inside `char(...)` → samples previous frame's character data
+ * - Inside `charColor(...)` → samples previous frame's primary color
+ * - Inside `cellColor(...)` → samples previous frame's cell color
+ *
+ * **Cross-layer sampling:** When called with a layer argument, `src(layer)` samples
+ * from another layer's output, enabling hydra-style multi-output compositions:
+ * - The sampled texture is still context-aware based on the current compilation target
+ *
+ * Equivalent to hydra's `src(o0)`.
+ *
+ * @param layer - Optional TextmodeLayer to sample from. If omitted, samples from self (feedback).
+ * @returns A new SynthSource that samples the specified layer or self
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Classic hydra-style feedback loop with noise modulation
+ * t.layers.base.synth(
+ *   src().modulate(noise(3), 0.005).blend(shape(4), 0.01)
+ * );
+ *
+ * // Cross-layer sampling (hydra-style o0, o1, etc.)
+ * const layer1 = t.layers.add();
+ * const layer2 = t.layers.add();
+ *
+ * layer1.synth(noise(10).mult(osc(20)));
+ *
+ * layer2.synth(
+ *   char(voronoi(5).diff(src(layer1)))  // Sample layer1's char texture
+ *     .charColor(osc(10).blend(src(layer1), 0.5))  // Sample layer1's primary color
+ * );
+ *
+ * // Complex multi-layer composition
+ * t.layers.base.synth(
+ *   noise(3, 0.3).thresh(0.3).diff(src(layer2), 0.3)
+ * );
+ * ```
+ */
+export declare const src: (layer?: {
+    id?: string;
+}) => SynthSource;
+export type { ModulatedArray, EasingFunction } from './lib/ArrayUtils';
+declare module 'textmode.js' {
+    interface TextmodeLayer {
+        /**
+         * Set a synth source for this layer.
+         *
+         * The synth will render procedurally generated characters and colors
+         * directly to the layer's MRT framebuffer before the draw callback runs.
+         *
+         * @param source A SynthSource chain defining the procedural generation
+         */
+        synth(source: SynthSource): void;
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types/lib/ArrayUtils.d.ts

@@ -0,0 +1,225 @@
+/**
+ * ArrayUtils - Hydra-style array modulation utilities.
+ *
+ * Provides methods for arrays to modulate values over time,
+ * similar to Hydra's array functionality.
+ */
+import type { SynthContext } from '../core/types';
+/**
+ * Easing functions from https://gist.github.com/gre/1650294
+ */
+export declare const EASING_FUNCTIONS: {
+    linear: (t: number) => number;
+    easeInQuad: (t: number) => number;
+    easeOutQuad: (t: number) => number;
+    easeInOutQuad: (t: number) => number;
+    easeInCubic: (t: number) => number;
+    easeOutCubic: (t: number) => number;
+    easeInOutCubic: (t: number) => number;
+    easeInQuart: (t: number) => number;
+    easeOutQuart: (t: number) => number;
+    easeInOutQuart: (t: number) => number;
+    easeInQuint: (t: number) => number;
+    easeOutQuint: (t: number) => number;
+    easeInOutQuint: (t: number) => number;
+    sin: (t: number) => number;
+};
+/**
+ * Easing functions from https://gist.github.com/gre/1650294
+ *
+ * Available easing functions: `'linear'`, `'easeInQuad'`, `'easeOutQuad'`, `'easeInOutQuad'`,
+ * `'easeInCubic'`, `'easeOutCubic'`, `'easeInOutCubic'`, `'easeInQuart'`, `'easeOutQuart'`,
+ * `'easeInOutQuart'`, `'easeInQuint'`, `'easeOutQuint'`, `'easeInOutQuint'`, `'sin'`
+ *
+ * @example
+ * ```typescript
+ * const t = textmode.create({
+ *   width: 800,
+ *   height: 600,
+ *   plugins: [SynthPlugin]
+ * });
+ *
+ * // Rotating shape with eased animation
+ * t.layers.base.synth(
+ *   shape(4)
+ *     .rotate([-3.14, 3.14].ease('easeInOutCubic'))
+ * );
+ * ```
+ */
+export type EasingFunction = keyof typeof EASING_FUNCTIONS | ((t: number) => number);
+/**
+ * Extended array interface with modulation methods.
+ *
+ * Arrays in textmode.synth.js behave like Hydra - they cycle through values over time,
+ * creating dynamic, time-varying parameters. This enables complex animations without
+ * manually tracking time or state.
+ */
+export interface ModulatedArray extends Array<number> {
+    /** Speed multiplier for array cycling */
+    _speed?: number;
+    /** Smoothing amount (0-1) for interpolation */
+    _smooth?: number;
+    /** Easing function for interpolation */
+    _ease?: (t: number) => number;
+    /** Time offset for array cycling */
+    _offset?: number;
+    /**
+     * Set speed multiplier for array cycling.
+     *
+     * Controls how fast the array cycles through its values over time.
+     * A speed of 1 is the default rate. Values > 1 cycle faster, values < 1 cycle slower.
+     *
+     * @param speed - Speed multiplier (default: 1)
+     * @returns The array for chaining
+     *
+     * @example
+     * ```typescript
+     * // Fast cycling through frequencies
+     * osc([1, 2, 4].fast(2), 0.1, 1.5)
+     *
+     * // Slow cycling through scroll positions
+     * shape(4).scrollX([-0.5, 0.5].fast(0.3))
+     *
+     * // Use same array for multiple parameters
+     * const speeds = [1, 3, 6].fast(2);
+     * osc(speeds, 0.1, 1.5, 16)
+     *   .charColor(osc(speeds, 0.1, 1.5))
+     * ```
+     */
+    fast(speed: number): this;
+    /**
+     * Enable smooth interpolation between array values.
+     *
+     * Instead of jumping from one value to the next, smooth() creates gradual
+     * transitions. The amount parameter controls the smoothing duration.
+     * When amount is 1 (default), smoothing is applied across the full transition.
+     *
+     * @param amount - Smoothing amount 0-1 (default: 1)
+     * @returns The array for chaining
+     *
+     * @example
+     * ```typescript
+     * // Smooth scrolling between positions
+     * shape(999).scrollX([-0.2, 0.2].smooth())
+     *
+     * // Gentle rotation animation
+     * shape(4).rotate([-3.14, 0, 3.14].smooth(0.8))
+     *
+     * // Smooth color transitions
+     * solid([0, 0.5, 1].smooth(), 0, 0)
+     * ```
+     */
+    smooth(amount?: number): this;
+    /**
+     * Apply easing function to interpolation between array values.
+     *
+     * Easing controls the acceleration curve of transitions between values.
+     * Automatically enables smoothing when applied. Use built-in easing names
+     * or provide a custom function that takes a value 0-1 and returns 0-1.
+     *
+     * Available easing functions: `'linear'`, `'easeInQuad'`, `'easeOutQuad'`,
+     * `'easeInOutQuad'`, `'easeInCubic'`, `'easeOutCubic'`, `'easeInOutCubic'`,
+     * `'easeInQuart'`, `'easeOutQuart'`, `'easeInOutQuart'`, `'easeInQuint'`,
+     * `'easeOutQuint'`, `'easeInOutQuint'`, `'sin'`
+     *
+     * @param ease - Easing function name or custom function (default: 'linear')
+     * @returns The array for chaining
+     *
+     * @example
+     * ```typescript
+     * // Smooth rotation with cubic easing
+     * shape(4).rotate([-3.14, 3.14].ease('easeInOutCubic'))
+     *
+     * // Sine wave easing for natural motion
+     * shape(3).scale([0.5, 1.5].ease('sin'))
+     *
+     * // Custom easing function (bounce effect)
+     * const bounce = (t) => {
+     *   const n1 = 7.5625;
+     *   const d1 = 2.75;
+     *   if (t < 1 / d1) return n1 * t * t;
+     *   if (t < 2 / d1) return n1 * (t -= 1.5 / d1) * t + 0.75;
+     *   if (t < 2.5 / d1) return n1 * (t -= 2.25 / d1) * t + 0.9375;
+     *   return n1 * (t -= 2.625 / d1) * t + 0.984375;
+     * };
+     * shape(5).scale([0.8, 1.2].ease(bounce))
+     * ```
+     */
+    ease(ease: EasingFunction): this;
+    /**
+     * Set time offset for array cycling.
+     *
+     * Shifts when the array starts cycling through its values.
+     * Useful for creating phase-shifted animations where multiple arrays
+     * cycle with the same speed but at different times.
+     *
+     * The offset wraps around at 1.0, so offset(0.5) starts halfway through
+     * the cycle, and offset(1.5) is equivalent to offset(0.5).
+     *
+     * @param offset - Time offset 0-1, wraps at 1.0 (default: 0)
+     * @returns The array for chaining
+     *
+     * @example
+     * ```typescript
+     * // Two shapes scrolling in opposite phase
+     * shape(999).scrollX([-0.2, 0.2])
+     *   .add(shape(4).scrollX([-0.2, 0.2].offset(0.5)))
+     *
+     * // Create layered animations with phase shifts
+     * const positions = [-0.3, 0.3];
+     * shape(3).scroll(positions, positions.offset(0.25))
+     *
+     * // Three oscillators with 120° phase difference
+     * osc([5, 10].offset(0)).add(
+     *   osc([5, 10].offset(0.33)), 0.5
+     * ).add(
+     *   osc([5, 10].offset(0.66)), 0.5
+     * )
+     * ```
+     */
+    offset(offset: number): this;
+    /**
+     * Fit (remap) array values to a new range.
+     *
+     * Takes the minimum and maximum values in the array and linearly maps them
+     * to the specified low and high values. All intermediate values are scaled
+     * proportionally. The original array is not modified.
+     *
+     * Preserves any modulation settings (speed, smooth, ease, offset) from the
+     * original array.
+     *
+     * @param low - New minimum value
+     * @param high - New maximum value
+     * @returns A new ModulatedArray with remapped values
+     *
+     * @example
+     * ```typescript
+     * // Remap 0-4 range to -0.2 to 0.2 for subtle scrolling
+     * shape(999).scrollX([0, 1, 2, 3, 4].fit(-0.2, 0.2))
+     *
+     * // Normalize arbitrary values to 0-1 range
+     * const values = [50, 100, 75, 125].fit(0, 1);
+     * solid(values, 0, 0)
+     *
+     * // Combine with other modulation
+     * shape(3).scale([0, 100].fit(0.5, 1.5).smooth().fast(0.5))
+     * ```
+     */
+    fit(low: number, high: number): ModulatedArray;
+}
+/**
+ * Initialize array utilities by extending Array prototype.
+ * This adds Hydra-style methods to arrays.
+ */
+export declare function initArrayUtils(): void;
+/**
+ * Get the current value from a modulated array based on context.
+ */
+export declare function getArrayValue(arr: ModulatedArray, ctx: SynthContext): number;
+/**
+ * Check if a value is a modulated array.
+ * In Hydra, ALL number arrays are treated as time-varying sequences,
+ * even without explicit .fast() or .smooth() modulation.
+ */
+export declare function isModulatedArray(value: unknown): value is ModulatedArray;
+//# sourceMappingURL=ArrayUtils.d.ts.map

package/dist/types/lib/ArrayUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArrayUtils.d.ts","sourceRoot":"","sources":["../../../src/lib/ArrayUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,gBAAgB;gBAChB,MAAM;oBACF,MAAM;qBACL,MAAM;uBACJ,MAAM;qBACR,MAAM;sBACL,MAAM;wBACJ,MAAM;qBACT,MAAM;sBACL,MAAM;wBACJ,MAAM;qBACT,MAAM;sBACL,MAAM;wBACJ,MAAM;aACjB,MAAM;CACf,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,gBAAgB,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;AAErF;;;;;;GAMG;AACH,MAAM,WAAW,cAAe,SAAQ,KAAK,CAAC,MAAM,CAAC;IACpD,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC;CAC/C;AAgBD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAuCrC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,YAAY,GAAG,MAAM,CAwB5E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAMxE"}

package/dist/types/transforms/TransformDefinition.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Transform definition types and interfaces.
+ *
+ * This module provides the base types and helper functions for defining
+ * synthesis transforms in a declarative way.
+ */
+import type { SynthTransformType, TransformInput } from '../core/types';
+export type { TransformInput };
+/**
+ * Definition of a synthesis transform function.
+ */
+export interface TransformDefinition {
+    /** Function name (used in JS API and GLSL) */
+    name: string;
+    /** Transform type determining composition behavior */
+    type: SynthTransformType;
+    /** Input parameters */
+    inputs: TransformInput[];
+    /** GLSL function body (without function signature) */
+    glsl: string;
+    /** Optional description for documentation */
+    description?: string;
+}
+/**
+ * A processed transform with complete GLSL function.
+ */
+export interface ProcessedTransform extends TransformDefinition {
+    /** Complete GLSL function code */
+    glslFunction: string;
+}
+/**
+ * Process a transform definition into a processed transform with complete GLSL function.
+ */
+export declare function processTransform(def: TransformDefinition): ProcessedTransform;
+/**
+ * Helper to define a transform with type inference.
+ * This makes transform definitions more concise and type-safe.
+ */
+export declare function defineTransform<T extends SynthTransformType>(definition: TransformDefinition & {
+    type: T;
+}): TransformDefinition;
+/**
+ * Get default values for a transform's inputs.
+ */
+export declare function getDefaultArgs(def: TransformDefinition): (number | number[] | null)[];
+/**
+ * Check if a transform type requires a nested source.
+ */
+export declare function requiresNestedSource(type: SynthTransformType): boolean;
+/**
+ * Check if a transform type is a source generator.
+ */
+export declare function isSourceType(type: SynthTransformType): boolean;
+//# sourceMappingURL=TransformDefinition.d.ts.map

package/dist/types/transforms/TransformDefinition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransformDefinition.d.ts","sourceRoot":"","sources":["../../../src/transforms/TransformDefinition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACxE,YAAY,EAAE,cAAc,EAAE,CAAC;AAG/B;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,IAAI,EAAE,kBAAkB,CAAC;IACzB,uBAAuB;IACvB,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC9D,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,mBAAmB,GAAG,kBAAkB,CAc7E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,kBAAkB,EAC3D,UAAU,EAAE,mBAAmB,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,GAC3C,mBAAmB,CAErB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,mBAAmB,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAErF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAEtE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAE9D"}