@genart-dev/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,283 @@
+import { ParamDef, ColorDef, RendererType, SketchState, CanvasSpec, SketchDefinition } from '@genart-dev/format';
+export * from '@genart-dev/format';
+
+/** A design knowledge skill definition. */
+interface SkillDefinition {
+    /** Unique skill identifier (kebab-case). */
+    readonly id: string;
+    /** Human-readable skill name. */
+    readonly name: string;
+    /** Skill category. */
+    readonly category: "composition" | "color";
+    /** Complexity level. */
+    readonly complexity: "beginner" | "intermediate" | "advanced";
+    /** Brief description. */
+    readonly description: string;
+    /** Core design theory (markdown). */
+    readonly theory: string;
+    /** Key principles. */
+    readonly principles: readonly string[];
+    /** Academic references. */
+    readonly references: readonly SkillReference[];
+    /** Suggested parameters for sketches using this skill. */
+    readonly suggestedParameters?: readonly ParamDef[];
+    /** Suggested color definitions. */
+    readonly suggestedColors?: readonly ColorDef[];
+    /** Renderer-specific example algorithms. */
+    readonly examples?: Readonly<Partial<Record<RendererType, string>>>;
+}
+/** An academic reference for a skill. */
+interface SkillReference {
+    /** Book or paper title. */
+    readonly title: string;
+    /** Author name. */
+    readonly author: string;
+    /** Year of publication. */
+    readonly year?: number;
+}
+/** Result of validating an algorithm string. */
+interface ValidationResult {
+    /** Whether the algorithm is valid. */
+    readonly valid: boolean;
+    /** Validation error messages, if any. */
+    readonly errors: readonly string[];
+}
+/** Opaque compiled algorithm handle. */
+type CompiledAlgorithm = unknown;
+/** A runtime dependency required by a renderer. */
+interface RuntimeDependency {
+    /** Package or CDN name. */
+    readonly name: string;
+    /** Version constraint. */
+    readonly version: string;
+    /** CDN URL for standalone HTML export. */
+    readonly cdnUrl: string;
+}
+/** Options for frame capture. */
+interface CaptureOptions {
+    /** Output format. */
+    readonly format?: "png" | "jpeg" | "webp";
+    /** Quality (0-1) for lossy formats. */
+    readonly quality?: number;
+    /** Scale multiplier. */
+    readonly scale?: number;
+}
+/**
+ * Renderer adapter — pluggable rendering engine interface.
+ * Each renderer type (p5, Three.js, GLSL, Canvas 2D, SVG) implements this.
+ */
+interface RendererAdapter {
+    /** The renderer type this adapter handles. */
+    readonly type: RendererType;
+    /** Human-readable renderer name. */
+    readonly displayName: string;
+    /** Language used for the algorithm field. */
+    readonly algorithmLanguage: "javascript" | "glsl" | "typescript";
+    /** Validate algorithm source without executing it. */
+    validate(algorithm: string): ValidationResult;
+    /** Compile an algorithm string into a runnable form. */
+    compile(algorithm: string): Promise<CompiledAlgorithm>;
+    /** Create a live sketch instance from compiled algorithm + state. */
+    createInstance(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec): SketchInstance;
+    /** Render a single frame offscreen (for capture/export). */
+    renderOffscreen(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec, options?: CaptureOptions): Promise<Uint8Array | Blob>;
+    /** Generate a standalone HTML page embedding the sketch. */
+    generateStandaloneHTML(sketch: SketchDefinition): string;
+    /** Return a starter algorithm template for this renderer. */
+    getAlgorithmTemplate(): string;
+    /** List runtime dependencies needed for standalone export. */
+    getRuntimeDependencies(): RuntimeDependency[];
+}
+/**
+ * A live sketch instance mounted in the DOM.
+ * Created by RendererAdapter.createInstance().
+ */
+interface SketchInstance {
+    /** Mount the sketch into a DOM container. */
+    mount(container: HTMLElement): void;
+    /** Unmount and remove from DOM. */
+    unmount(): void;
+    /** Update runtime state (params, colors, seed). */
+    updateState(state: SketchState): void;
+    /** Trigger a redraw with current state. */
+    redraw(): void;
+    /** Pause animation/rendering. */
+    pause(): void;
+    /** Resume animation/rendering. */
+    resume(): void;
+    /** Whether the sketch is currently animating. */
+    readonly isAnimating: boolean;
+    /** Capture the current frame as a data URL. */
+    captureFrame(options?: CaptureOptions): Promise<string>;
+    /** Capture raw ImageData from the current frame. */
+    captureImageData(): Promise<ImageData>;
+    /** Dispose all resources (WebGL contexts, event listeners, etc.). */
+    dispose(): void;
+}
+
+/**
+ * P5 Renderer Adapter — full implementation.
+ *
+ * Validates algorithms for the `sketch(p, state)` instance-mode signature,
+ * compiles them into executable factories, and creates live sketch instances.
+ */
+declare class P5RendererAdapter implements RendererAdapter {
+    readonly type: RendererType;
+    readonly displayName = "p5.js";
+    readonly algorithmLanguage: "javascript";
+    validate(algorithm: string): ValidationResult;
+    compile(algorithm: string): Promise<CompiledAlgorithm>;
+    createInstance(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec): SketchInstance;
+    renderOffscreen(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec, options?: CaptureOptions): Promise<Uint8Array | Blob>;
+    generateStandaloneHTML(sketch: SketchDefinition): string;
+    getAlgorithmTemplate(): string;
+    getRuntimeDependencies(): RuntimeDependency[];
+}
+
+/**
+ * Canvas 2D Renderer Adapter — full implementation.
+ *
+ * Validates algorithms for the `sketch(ctx, state)` function signature,
+ * compiles them into executable factories, and creates live sketch instances.
+ */
+declare class Canvas2DRendererAdapter implements RendererAdapter {
+    readonly type: RendererType;
+    readonly displayName = "Canvas 2D";
+    readonly algorithmLanguage: "javascript";
+    validate(algorithm: string): ValidationResult;
+    compile(algorithm: string): Promise<CompiledAlgorithm>;
+    createInstance(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec): SketchInstance;
+    renderOffscreen(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec, options?: CaptureOptions): Promise<Uint8Array | Blob>;
+    generateStandaloneHTML(sketch: SketchDefinition): string;
+    getAlgorithmTemplate(): string;
+    getRuntimeDependencies(): RuntimeDependency[];
+}
+
+/**
+ * Three.js Renderer Adapter — full implementation.
+ *
+ * Validates algorithms for the `sketch(THREE, state, container)` signature,
+ * compiles them into executable factories, and creates live sketch instances.
+ */
+declare class ThreeRendererAdapter implements RendererAdapter {
+    readonly type: RendererType;
+    readonly displayName = "Three.js";
+    readonly algorithmLanguage: "javascript";
+    validate(algorithm: string): ValidationResult;
+    compile(algorithm: string): Promise<CompiledAlgorithm>;
+    createInstance(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec): SketchInstance;
+    renderOffscreen(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec, options?: CaptureOptions): Promise<Uint8Array | Blob>;
+    generateStandaloneHTML(sketch: SketchDefinition): string;
+    getAlgorithmTemplate(): string;
+    getRuntimeDependencies(): RuntimeDependency[];
+}
+
+/**
+ * Parse a hex color string to RGB floats in [0, 1] range.
+ * Accepts "#rrggbb" or "rrggbb" format.
+ */
+declare function hexToVec3(hex: string): [number, number, number];
+/**
+ * GLSL Renderer Adapter — full implementation.
+ *
+ * Validates GLSL fragment shaders, compiles them with a fullscreen quad
+ * vertex shader, and creates live sketch instances using WebGL2.
+ */
+declare class GLSLRendererAdapter implements RendererAdapter {
+    readonly type: RendererType;
+    readonly displayName = "GLSL Shader";
+    readonly algorithmLanguage: "glsl";
+    validate(algorithm: string): ValidationResult;
+    compile(algorithm: string): Promise<CompiledAlgorithm>;
+    createInstance(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec): SketchInstance;
+    renderOffscreen(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec, options?: CaptureOptions): Promise<Uint8Array | Blob>;
+    generateStandaloneHTML(sketch: SketchDefinition): string;
+    getAlgorithmTemplate(): string;
+    getRuntimeDependencies(): RuntimeDependency[];
+}
+
+/**
+ * SVG Renderer Adapter — full implementation.
+ *
+ * Validates algorithms for the `sketch(state)` function signature,
+ * compiles them into executable factories, and creates live sketch instances.
+ * SVG sketches are static — there is no animation loop.
+ */
+declare class SVGRendererAdapter implements RendererAdapter {
+    readonly type: RendererType;
+    readonly displayName = "SVG";
+    readonly algorithmLanguage: "javascript";
+    validate(algorithm: string): ValidationResult;
+    compile(algorithm: string): Promise<CompiledAlgorithm>;
+    createInstance(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec): SketchInstance;
+    renderOffscreen(compiled: CompiledAlgorithm, state: SketchState, canvas: CanvasSpec, _options?: CaptureOptions): Promise<Uint8Array | Blob>;
+    generateStandaloneHTML(sketch: SketchDefinition): string;
+    getAlgorithmTemplate(): string;
+    getRuntimeDependencies(): RuntimeDependency[];
+}
+
+/**
+ * Registry for renderer adapters. Manages registration and lookup
+ * of RendererAdapter implementations by renderer type.
+ */
+declare class RendererRegistry {
+    private readonly adapters;
+    private defaultType;
+    /**
+     * Register a renderer adapter. Replaces any existing adapter for the same type.
+     */
+    register(adapter: RendererAdapter): void;
+    /**
+     * Resolve a renderer adapter by type.
+     * If type is undefined, returns the default adapter (p5 — v1.0 compat).
+     *
+     * @throws Error if the type is not registered.
+     */
+    resolve(type?: RendererType): RendererAdapter;
+    /**
+     * List all registered renderer types.
+     */
+    list(): RendererType[];
+    /**
+     * Get the default renderer adapter (p5).
+     */
+    getDefault(): RendererAdapter;
+    /**
+     * Check if a renderer type is registered.
+     */
+    has(type: RendererType): boolean;
+}
+/**
+ * Create a RendererRegistry pre-loaded with all 5 renderer adapters.
+ * This is the standard way to get a registry instance.
+ */
+declare function createDefaultRegistry(): RendererRegistry;
+
+/**
+ * Registry for design knowledge skills.
+ * Mirrors the RendererRegistry pattern.
+ */
+declare class SkillRegistry {
+    private readonly skills;
+    /** Register a skill definition. */
+    register(skill: SkillDefinition): void;
+    /** Resolve a skill by ID. Throws if not found. */
+    resolve(id: string): SkillDefinition;
+    /** Get a skill by ID, or undefined if not found. */
+    get(id: string): SkillDefinition | undefined;
+    /** List all skills, optionally filtered by category. */
+    list(category?: string): SkillDefinition[];
+    /** Check if a skill ID is registered. */
+    has(id: string): boolean;
+    /** Return unique categories across all registered skills. */
+    categories(): string[];
+}
+/**
+ * Create a skill registry pre-loaded with all built-in skills.
+ */
+declare function createDefaultSkillRegistry(): SkillRegistry;
+
+declare const COMPOSITION_SKILLS: readonly SkillDefinition[];
+declare const COLOR_SKILLS: readonly SkillDefinition[];
+
+export { COLOR_SKILLS, COMPOSITION_SKILLS, Canvas2DRendererAdapter, type CaptureOptions, type CompiledAlgorithm, GLSLRendererAdapter, P5RendererAdapter, type RendererAdapter, RendererRegistry, type RuntimeDependency, SVGRendererAdapter, type SketchInstance, type SkillDefinition, type SkillReference, SkillRegistry, ThreeRendererAdapter, type ValidationResult, createDefaultRegistry, createDefaultSkillRegistry, hexToVec3 };