@dilemmagx/orchestra 1.1.0 → 1.2.2

package/dist/core/nodes.d.ts

@@ -0,0 +1,431 @@
+import { ImageBuffer } from './image';
+import { ColorInput } from './color';
+import { ImageSource, Pixel, PixelLike } from './types';
+import { SeededRandom } from './random';
+import { ResizeOptions, type TextOptions } from './sources';
+export declare const DEFAULT_IMAGE_KEY = "image";
+/**
+ * Runtime context shared across nodes in a pipeline run.
+ */
+export type NodeContext = {
+    random: SeededRandom;
+    stash: Map<string, unknown>;
+};
+/**
+ * State passed between nodes in a pipeline run.
+ */
+export type NodeState = {
+    images: Record<string, ImageBuffer>;
+    data: Record<string, unknown>;
+};
+/**
+ * Result returned by a node execution.
+ */
+export type NodeResult = {
+    images?: Record<string, ImageBuffer>;
+    data?: Record<string, unknown>;
+};
+type NodeRunner<TParams> = {
+    bivarianceHack(context: NodeContext, state: NodeState, params: TParams): Promise<NodeResult> | NodeResult;
+}['bivarianceHack'];
+/**
+ * Pipeline node definition.
+ */
+export type NodeDefinition<TParams = unknown> = {
+    name: string;
+    params?: TParams;
+    inputs?: string[];
+    outputs?: string[];
+    run: NodeRunner<TParams>;
+};
+/**
+ * Alias for image-focused nodes.
+ */
+export type ImageNode<TParams = unknown> = NodeDefinition<TParams>;
+/**
+ * Image node with typed parameters metadata.
+ */
+export type ParametricNode<TParams> = ImageNode<TParams> & {
+    params: TParams;
+};
+/**
+ * Definition for a reusable node.
+ */
+export declare function defineNode<TParams>(definition: NodeDefinition<TParams>): NodeDefinition<TParams>;
+/**
+ * Image node input definition.
+ */
+export type ImageNodeOptions = {
+    input?: string;
+    output?: string;
+};
+/**
+ * 2D pixel matrix representation.
+ */
+export type PixelMatrix = Pixel[][];
+/**
+ * Context provided to pixel-based node handlers.
+ */
+export type PixelNodeInfo<TParams> = {
+    context: NodeContext;
+    image: ImageBuffer;
+    state: NodeState;
+    params: TParams;
+    width: number;
+    height: number;
+};
+/**
+ * Handler signature for pixel-based nodes.
+ */
+export type PixelNodeRunner<TParams> = (pixels: PixelMatrix, info: PixelNodeInfo<TParams>) => PixelMatrix | ImageBuffer | Promise<PixelMatrix | ImageBuffer>;
+/**
+ * Simplified node definition.
+ */
+export type SimpleNodeDefinition<TParams> = {
+    name?: string;
+    params?: TParams;
+    input?: string;
+    output?: string;
+    run: PixelNodeRunner<TParams>;
+};
+/**
+ * Creates a node that reads a single image key and writes a single image key.
+ */
+export declare function createImageNode<TParams>(name: string, params: TParams, run: (context: NodeContext, image: ImageBuffer, params: TParams, state: NodeState) => Promise<ImageBuffer> | ImageBuffer, options?: ImageNodeOptions): ImageNode<TParams>;
+/**
+ * Creates a node that operates on a 2D pixel matrix.
+ */
+export declare function createPixelNode<TParams>(name: string, params: TParams, run: PixelNodeRunner<TParams>, options?: ImageNodeOptions): ImageNode<TParams>;
+/**
+ * Creates a simplified pixel-based node with optional name and parameters.
+ */
+export declare function node<TParams>(definition: SimpleNodeDefinition<TParams>): ImageNode<TParams>;
+/**
+ * Returns the image associated with the given key.
+ */
+export declare function getImage(state: NodeState, key?: string): ImageBuffer;
+/**
+ * Merges a node result into a state snapshot.
+ */
+export declare function mergeNodeState(state: NodeState, result: NodeResult): NodeState;
+/**
+ * Runs a node and returns its raw result.
+ */
+export declare function runNode(node: ImageNode, context: NodeContext, state: NodeState): Promise<NodeResult>;
+/**
+ * Runs a node and returns a single image output.
+ */
+export declare function runNodeImage(node: ImageNode, context: NodeContext, state: NodeState, outputKey?: string): Promise<ImageBuffer>;
+/**
+ * Selector used to choose pixels for masked execution.
+ */
+export type PixelSelector = (pixel: Pixel, x: number, y: number, context: NodeContext) => boolean;
+/**
+ * Masking options for nodes.
+ */
+export type SelectionOptions = {
+    mode?: SelectionMode;
+    outsideColor?: ColorInput;
+};
+/**
+ * Masking mode for selection.
+ */
+export type SelectionMode = 'preserve' | 'clip';
+/**
+ * Image source input accepted by nodes.
+ */
+export type ImageInput = ImageSource | ImageBuffer | ImageNode;
+/**
+ * Mask source for color mapping.
+ */
+export type MaskMapSource = ImageInput;
+/**
+ * Color-to-source mapping entry.
+ */
+export type MaskMapEntry = {
+    color: ColorInput;
+    tolerance?: number;
+    source?: MaskMapSource;
+};
+/**
+ * Options for mask mapping nodes.
+ */
+export type MaskMapOptions = {
+    defaultColor?: ColorInput;
+    resize?: ResizeOptions;
+};
+/**
+ * Rectangle selector options.
+ */
+export type RectSelectorOptions = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Circle selector options.
+ */
+export type CircleSelectorOptions = {
+    cx: number;
+    cy: number;
+    radius: number;
+};
+/**
+ * Creates a rectangle selector.
+ */
+export declare function createRectSelector(options: RectSelectorOptions): PixelSelector;
+/**
+ * Creates a circle selector.
+ */
+export declare function createCircleSelector(options: CircleSelectorOptions): PixelSelector;
+/**
+ * Creates a luminance-based selector.
+ */
+export declare function createLumaSelector(threshold: number): PixelSelector;
+/**
+ * Creates an alpha-based selector.
+ */
+export declare function createAlphaSelector(threshold: number): PixelSelector;
+/**
+ * Creates a node with typed parameters stored in the node metadata.
+ */
+export declare function createParamNode<TParams>(name: string, params: TParams, run: (context: NodeContext, image: ImageBuffer, params: TParams) => ImageBuffer): ParametricNode<TParams>;
+/**
+ * Creates a masked node that only processes selected pixels.
+ */
+export declare function createMaskedNode(node: ImageNode, selector: PixelSelector, options?: SelectionOptions, io?: ImageNodeOptions): ImageNode;
+/**
+ * Creates a node that composites sources based on a color mask.
+ */
+export declare function createMaskMapNode(mask: MaskMapSource, entries: MaskMapEntry[], options?: MaskMapOptions): ImageNode;
+/**
+ * Creates a node that removes pixels outside the selection.
+ */
+export declare function createSelectionCropNode(selector: PixelSelector, options?: SelectionOptions): ImageNode;
+/**
+ * Creates a node that maps every pixel using a custom mapper.
+ */
+export declare function createMapNode(name: string, mapper: (pixel: Pixel, x: number, y: number, context: NodeContext) => PixelLike): ImageNode;
+/**
+ * Creates a node that fills the image with a single color.
+ */
+export declare function createFillNode(color: ColorInput): ImageNode;
+/**
+ * Options for creating a noise node.
+ */
+export type NoiseOptions = {
+    min?: number;
+    max?: number;
+    alpha?: number;
+    grayscale?: boolean;
+};
+/**
+ * Options for creating a value noise node.
+ */
+export type ValueNoiseOptions = {
+    scale?: number;
+    octaves?: number;
+    persistence?: number;
+    lacunarity?: number;
+    min?: number;
+    max?: number;
+    alpha?: number;
+};
+/**
+ * Options for creating a Voronoi noise node.
+ */
+export type VoronoiNoiseOptions = {
+    scale?: number;
+    jitter?: number;
+    min?: number;
+    max?: number;
+    alpha?: number;
+    mode?: 'distance' | 'edge';
+};
+/**
+ * Options for creating a fractal noise node.
+ */
+export type FractalNoiseOptions = {
+    scale?: number;
+    octaves?: number;
+    persistence?: number;
+    lacunarity?: number;
+    min?: number;
+    max?: number;
+    alpha?: number;
+};
+/**
+ * Options for creating a Perlin noise node.
+ */
+export type PerlinNoiseOptions = {
+    scale?: number;
+    octaves?: number;
+    persistence?: number;
+    lacunarity?: number;
+    min?: number;
+    max?: number;
+    alpha?: number;
+};
+/**
+ * Options for creating a turbulence noise node.
+ */
+export type TurbulenceNoiseOptions = {
+    scale?: number;
+    octaves?: number;
+    persistence?: number;
+    lacunarity?: number;
+    min?: number;
+    max?: number;
+    alpha?: number;
+};
+/**
+ * Options for creating a ridged noise node.
+ */
+export type RidgedNoiseOptions = {
+    scale?: number;
+    octaves?: number;
+    persistence?: number;
+    lacunarity?: number;
+    min?: number;
+    max?: number;
+    alpha?: number;
+};
+/**
+ * Creates a node that applies seeded noise to every pixel.
+ */
+export declare function createNoiseNode(options?: NoiseOptions): ImageNode;
+/**
+ * Creates a node that generates value noise.
+ */
+export declare function createValueNoiseNode(options?: ValueNoiseOptions): ImageNode;
+/**
+ * Creates a node that generates Voronoi noise.
+ */
+export declare function createVoronoiNoiseNode(options?: VoronoiNoiseOptions): ImageNode;
+/**
+ * Creates a node that generates fractal value noise.
+ */
+export declare function createFractalNoiseNode(options?: FractalNoiseOptions): ImageNode;
+/**
+ * Creates a node that generates Perlin noise.
+ */
+export declare function createPerlinNoiseNode(options?: PerlinNoiseOptions): ImageNode;
+/**
+ * Creates a node that generates turbulence noise.
+ */
+export declare function createTurbulenceNoiseNode(options?: TurbulenceNoiseOptions): ImageNode;
+/**
+ * Creates a node that generates ridged noise.
+ */
+export declare function createRidgedNoiseNode(options?: RidgedNoiseOptions): ImageNode;
+/**
+ * Options for convolution nodes.
+ */
+export type ConvolutionOptions = {
+    normalize?: boolean;
+};
+/**
+ * Creates a convolution node using an odd square kernel.
+ */
+export declare function createConvolutionNode(name: string, kernel: number[][], options?: ConvolutionOptions): ImageNode;
+/**
+ * Creates a node that inverts RGB values.
+ */
+export declare function createInvertNode(): ImageNode;
+/**
+ * Creates a node that converts RGB to grayscale.
+ */
+export declare function createGrayscaleNode(): ImageNode;
+/**
+ * Creates a node that applies gamma correction.
+ */
+export declare function createGammaNode(gamma: number): ImageNode;
+/**
+ * Creates a node that shifts brightness by a delta.
+ */
+export declare function createBrightnessNode(delta: number): ImageNode;
+/**
+ * Creates a node that adjusts contrast around the midtone.
+ */
+export declare function createContrastNode(factor: number): ImageNode;
+/**
+ * Creates a node that applies a binary threshold.
+ */
+export declare function createThresholdNode(threshold: number, low?: number, high?: number): ImageNode;
+/**
+ * Creates a node that fills the image with a random color.
+ */
+export declare function createRandomFillNode(alpha?: number): ImageNode;
+/**
+ * Creates a node that adds Gaussian noise.
+ */
+export declare function createGaussianNoiseNode(mean?: number, stdDev?: number, alpha?: number, grayscale?: boolean): ImageNode;
+/**
+ * Creates a node that applies salt and pepper noise.
+ */
+export declare function createSaltPepperNoiseNode(probability?: number, salt?: ColorInput, pepper?: ColorInput): ImageNode;
+/**
+ * Creates a checkerboard pattern node.
+ */
+export declare function createCheckerboardNode(tileSize: number, colorA: ColorInput, colorB: ColorInput): ImageNode;
+/**
+ * Options for drawing a rectangle.
+ */
+export type RectOptions = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color: ColorInput;
+};
+/**
+ * Creates a node that draws a rectangle.
+ */
+export declare function createRectNode(options: RectOptions): ImageNode;
+/**
+ * Options for drawing a circle.
+ */
+export type CircleOptions = {
+    cx: number;
+    cy: number;
+    radius: number;
+    color: ColorInput;
+};
+/**
+ * Creates a node that draws a circle.
+ */
+export declare function createCircleNode(options: CircleOptions): ImageNode;
+/**
+ * Creates a node that maps colors to the nearest palette entry.
+ */
+export declare function createPaletteMapNode(palette: ColorInput[]): ImageNode;
+/**
+ * Builds a normalized box kernel.
+ */
+export declare function buildBoxKernel(size: number): number[][];
+/**
+ * Builds a Gaussian kernel with the given size and sigma.
+ */
+export declare function buildGaussianKernel(size: number, sigma?: number): number[][];
+/**
+ * Creates a Gaussian blur node.
+ */
+export declare function createGaussianBlurNode(size?: number, sigma?: number): ImageNode;
+/**
+ * Creates a sharpening node.
+ */
+export declare function createSharpenNode(): ImageNode;
+/**
+ * Creates an edge detection node.
+ */
+export declare function createEdgeDetectNode(): ImageNode;
+/**
+ * Creates a node that resizes the image to the target dimensions.
+ */
+export declare function createResizeNode(width: number, height: number, options?: ResizeOptions): ImageNode;
+/**
+ * Creates a node that renders text onto an image.
+ */
+export declare function createTextNode(options: TextOptions): ImageNode<TextOptions>;
+export {};

package/dist/core/pipeline.d.ts

@@ -0,0 +1,46 @@
+import { ImageBuffer } from './image';
+import { ImageSource } from './types';
+import { SeededRandom } from './random';
+import { ImageNode, NodeState } from './nodes';
+/**
+ * Options for running a pipeline.
+ */
+export type PipelineOptions = {
+    seed?: number | string;
+    random?: SeededRandom;
+    data?: Record<string, unknown>;
+};
+/**
+ * Supported inputs for running a pipeline.
+ */
+export type PipelineInput = ImageSource | ImageBuffer | NodeState;
+/**
+ * Sequential pipeline that runs image nodes in order.
+ */
+export declare class Pipeline {
+    private nodes;
+    /**
+     * Creates a new pipeline with optional initial nodes.
+     */
+    constructor(nodes?: ImageNode[]);
+    /**
+     * Appends nodes to the pipeline.
+     */
+    add(...nodes: ImageNode[]): this;
+    /**
+     * Executes the pipeline against an input source or buffer.
+     */
+    run(input: PipelineInput, options?: PipelineOptions): Promise<ImageBuffer>;
+    /**
+     * Executes the pipeline and returns the full node state.
+     */
+    runState(input: PipelineInput, options?: PipelineOptions): Promise<NodeState>;
+}
+/**
+ * Creates a small example pipeline for quick sanity checks.
+ */
+export declare function createExamplePipeline(): Pipeline;
+/**
+ * Creates a pipeline with the provided nodes.
+ */
+export declare function pipeline(...nodes: ImageNode[]): Pipeline;

package/dist/core/random.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Deterministic RNG powered by a 32-bit seed.
+ */
+export declare class SeededRandom {
+    private state;
+    /**
+     * Creates a new RNG with a specific seed.
+     */
+    constructor(seed: number);
+    /**
+     * Returns a float in the range [0, 1).
+     */
+    next(): number;
+    /**
+     * Alias of next() for semantic clarity.
+     */
+    nextFloat(): number;
+    /**
+     * Returns an integer in the inclusive range [min, max].
+     */
+    nextInt(min: number, max: number): number;
+    /**
+     * Returns a float in the range [min, max).
+     */
+    nextRange(min: number, max: number): number;
+    /**
+     * Returns a normally distributed random number.
+     */
+    nextGaussian(mean?: number, stdDev?: number): number;
+}
+/**
+ * Creates a seeded RNG from a number or string seed.
+ * When omitted, the seed is derived from current time.
+ */
+export declare function createRandom(seed?: number | string): SeededRandom;

package/dist/core/sources.d.ts

@@ -0,0 +1,107 @@
+import { ImageBuffer } from './image';
+import { ColorInput } from './color';
+import { ImageSource, PixelLike, PixelFormat } from './types';
+/**
+ * Creates an ImageSource from a local file path.
+ */
+export declare function sourceFromPath(path: string): ImageSource;
+/**
+ * Creates an ImageSource from a remote URL.
+ */
+export declare function sourceFromUrl(url: string): ImageSource;
+/**
+ * Creates an ImageSource from a data URI.
+ */
+export declare function sourceFromDataUri(dataUri: string): ImageSource;
+/**
+ * Creates an ImageSource from a raw image buffer.
+ */
+export declare function sourceFromBuffer(buffer: Buffer): ImageSource;
+/**
+ * Creates an empty ImageSource with optional fill color.
+ */
+export declare function sourceFromEmpty(width: number, height: number, format?: PixelFormat, fill?: PixelLike): ImageSource;
+/**
+ * Loads an image source into an ImageBuffer.
+ */
+export declare function loadImage(source: ImageSource): Promise<ImageBuffer>;
+/**
+ * Output encoding options for image serialization.
+ */
+export type SaveImageOptions = {
+    format?: 'png' | 'jpeg' | 'webp';
+    quality?: number;
+};
+/**
+ * Resize options for image buffers.
+ */
+export type ResizeOptions = {
+    fit?: 'contain' | 'cover' | 'fill' | 'inside' | 'outside';
+    withoutEnlargement?: boolean;
+};
+/**
+ * Text font source configuration.
+ */
+export type TextFontSource = {
+    filePath?: string;
+    data?: Buffer;
+    mime?: string;
+};
+/**
+ * Text font configuration.
+ */
+export type TextFont = {
+    family: string;
+    source?: TextFontSource;
+    weight?: number | string;
+    style?: 'normal' | 'italic' | 'oblique';
+};
+/**
+ * Text layout options.
+ */
+export type TextLayout = {
+    x: number;
+    y: number;
+    maxWidth?: number;
+    maxLines?: number;
+    align?: 'left' | 'center' | 'right';
+    lineHeight?: number;
+    letterSpacing?: number;
+};
+/**
+ * Text style options.
+ */
+export type TextStyle = {
+    fontSize?: number;
+    color?: ColorInput;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    opacity?: number;
+};
+/**
+ * Text rendering options.
+ */
+export type TextOptions = {
+    text: string;
+    font: TextFont;
+    layout: TextLayout;
+    style?: TextStyle;
+};
+/**
+ * Serializes an ImageBuffer to an encoded image buffer.
+ */
+export declare function imageToBuffer(image: ImageBuffer, options?: SaveImageOptions): Promise<Buffer>;
+/**
+ * Saves an ImageBuffer to a local file.
+ */
+export declare function saveImage(image: ImageBuffer, outputPath: string, options?: SaveImageOptions): Promise<void>;
+/**
+ * Resizes an ImageBuffer and returns a new buffer.
+ */
+export declare function resizeImage(image: ImageBuffer, width: number, height: number, options?: ResizeOptions): Promise<ImageBuffer>;
+/**
+ * Renders text onto an ImageBuffer.
+ */
+export declare function renderText(image: ImageBuffer, options: TextOptions): Promise<ImageBuffer>;

package/dist/core/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pixel storage format for an ImageBuffer.
+ * - rgba8/rgb8/gray8 use 0-255 integer channels.
+ * - rgba32f uses 0-1 floating point channels.
+ */
+export type PixelFormat = 'rgba8' | 'rgb8' | 'gray8' | 'rgba32f';
+/**
+ * Fully expanded pixel with RGBA channels in 0-255 space.
+ */
+export type Pixel = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/**
+ * Pixel-like input that can omit alpha (defaults to 255).
+ */
+export type PixelLike = {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+};
+/**
+ * Supported image inputs for pipelines.
+ */
+export type ImageSource = {
+    type: 'path';
+    path: string;
+} | {
+    type: 'url';
+    url: string;
+} | {
+    type: 'datauri';
+    dataUri: string;
+} | {
+    type: 'buffer';
+    buffer: Buffer;
+} | {
+    type: 'empty';
+    width: number;
+    height: number;
+    format?: PixelFormat;
+    fill?: PixelLike;
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { ColorInput, HslColor, HslaColor, HsvColor, HsvaColor, RgbColor, RgbaColor, } from './core/color';
+export { colorDistance, hexToRgba, hslaToRgba, hsvaToRgba, rgbaToHex, rgbaToHsla, rgbaToHsva, toRgba, } from './core/color';
+export type { Pixel, PixelFormat, PixelLike, ImageSource } from './core/types';
+export { ImageBuffer } from './core/image';
+export { SeededRandom, createRandom } from './core/random';
+export type { ResizeOptions, SaveImageOptions, TextFont, TextFontSource, TextLayout, TextOptions, TextStyle, } from './core/sources';
+export { imageToBuffer, loadImage, renderText, resizeImage, saveImage, sourceFromBuffer, sourceFromDataUri, sourceFromEmpty, sourceFromPath, sourceFromUrl, } from './core/sources';
+export type { CircleSelectorOptions, ImageInput, ImageNode, ImageNodeOptions, MaskMapEntry, MaskMapOptions, MaskMapSource, NodeDefinition, NodeContext, NodeResult, NodeState, ParametricNode, PixelMatrix, PixelNodeInfo, PixelNodeRunner, PixelSelector, FractalNoiseOptions, PerlinNoiseOptions, RectSelectorOptions, SelectionMode, SelectionOptions, SimpleNodeDefinition, ValueNoiseOptions, RidgedNoiseOptions, TurbulenceNoiseOptions, VoronoiNoiseOptions, } from './core/nodes';
+export { DEFAULT_IMAGE_KEY, createBrightnessNode, createCircleSelector, createCheckerboardNode, createCircleNode, createConvolutionNode, createContrastNode, createAlphaSelector, createEdgeDetectNode, createFillNode, createGammaNode, createGaussianBlurNode, createGaussianNoiseNode, createGrayscaleNode, createInvertNode, createImageNode, createPixelNode, createLumaSelector, createMapNode, createMaskMapNode, createMaskedNode, createNoiseNode, createFractalNoiseNode, createPerlinNoiseNode, createRidgedNoiseNode, createTurbulenceNoiseNode, createValueNoiseNode, createVoronoiNoiseNode, createPaletteMapNode, createParamNode, createRandomFillNode, createRectSelector, createResizeNode, createSelectionCropNode, createRectNode, createSaltPepperNoiseNode, createSharpenNode, createThresholdNode, createTextNode, defineNode, getImage, mergeNodeState, node, runNode, runNodeImage, buildBoxKernel, buildGaussianKernel, } from './core/nodes';
+export type { PipelineInput, PipelineOptions } from './core/pipeline';
+export { Pipeline, createExamplePipeline, pipeline } from './core/pipeline';