af-motion 0.0.0-stage → 1.0.0

package/dist/graphics/textures/generators.d.ts

@@ -0,0 +1,29 @@
+/**
+ * AF Motion Procedural Texture Generators
+ *
+ * 12 Deterministic procedural generators supporting Canvas2D, SVG/CSS fallbacks,
+ * and WebGL texture descriptors.
+ */
+import type { PRNG } from "./prng.js";
+import type { ProceduralTextureOptions, TextureGeneratorMetadata, TextureGeneratorName, WebGLTextureDescriptor } from "./types.js";
+export interface GeneratorOutput {
+    readonly canvas: HTMLCanvasElement | null;
+    readonly dataUrl: string;
+    readonly cssBackground: string;
+    readonly webglDescriptor: WebGLTextureDescriptor | null;
+}
+export type GeneratorFn = (options: ProceduralTextureOptions, prng: PRNG, width: number, height: number) => GeneratorOutput;
+export declare const generateNoise: GeneratorFn;
+export declare const generatePaper: GeneratorFn;
+export declare const generateFabric: GeneratorFn;
+export declare const generateMarble: GeneratorFn;
+export declare const generateWood: GeneratorFn;
+export declare const generateMetalBrush: GeneratorFn;
+export declare const generateHalftone: GeneratorFn;
+export declare const generateDots: GeneratorFn;
+export declare const generateStripes: GeneratorFn;
+export declare const generateOrganicGradient: GeneratorFn;
+export declare const generateTopographic: GeneratorFn;
+export declare const generateImperfections: GeneratorFn;
+export declare const TEXTURE_GENERATORS: Readonly<Record<TextureGeneratorName, GeneratorFn>>;
+export declare const TEXTURE_GENERATORS_METADATA: Readonly<Record<TextureGeneratorName, TextureGeneratorMetadata>>;

package/dist/graphics/textures/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion Procedural Textures & Patterns Entry Point
+ */
+export * from "./types.js";
+export * from "./prng.js";
+export * from "./canvas-utils.js";
+export * from "./generators.js";
+export * from "./cache.js";
+export * from "./engine.js";
+export * from "./material-integration.js";
+export * from "./schema.js";

package/dist/graphics/textures/material-integration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AF Motion Material & Texture Integration
+ *
+ * Connects procedural textures to Prompt 72 surfaces and materials,
+ * generating CSS background styles, texture mapping, and shader uniforms.
+ */
+import type { LightingConfig, SurfaceDefinition, SurfaceStyleResult } from "../materials/types.js";
+import type { GeneratedTexture, ProceduralTextureConfig, TextureMappingOptions } from "./types.js";
+/**
+ * Resolve texture input into a GeneratedTexture or image URL string.
+ */
+export declare function resolveTextureInput(texture: GeneratedTexture | ProceduralTextureConfig | string): {
+    dataUrl: string;
+    generated?: GeneratedTexture;
+};
+/**
+ * Connect a procedural texture to a surface definition, outputting merged CSS styles
+ * and shader uniform parameters.
+ */
+export declare function applyTextureToSurface(surface: SurfaceDefinition, texture: GeneratedTexture | ProceduralTextureConfig | string, mapping?: TextureMappingOptions, lighting?: LightingConfig): SurfaceStyleResult;

package/dist/graphics/textures/prng.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AF Motion Deterministic Pseudo-Random Number Generator (PRNG)
+ *
+ * Mulberry32-based deterministic random generator supporting numeric or string seeds.
+ */
+export interface PRNG {
+    /** Return a deterministic float in [0, 1) */
+    next(): number;
+    /** Return a deterministic float in [min, max) */
+    range(min: number, max: number): number;
+    /** Return a deterministic integer in [min, max] inclusive */
+    int(min: number, max: number): number;
+    /** Return a deterministic boolean with true probability p (default 0.5) */
+    boolean(p?: number): boolean;
+    /** Return a random element from an array */
+    pick<T>(array: readonly T[]): T;
+    /** Seed value used by this PRNG */
+    readonly seed: number;
+}
+/**
+ * Hash an arbitrary string into a deterministic 32-bit unsigned integer.
+ */
+export declare function hashSeed(seed: number | string | undefined): number;
+/**
+ * Create a Mulberry32 deterministic PRNG instance.
+ */
+export declare function createPRNG(seedInput?: number | string): PRNG;

package/dist/graphics/textures/schema.d.ts

@@ -0,0 +1,219 @@
+/**
+ * AF Motion Procedural Texture Validation Schemas
+ *
+ * Schemas, validators, configuration correction, and AI capability registration
+ * for procedural textures and pattern generators.
+ */
+import type { ValidationReport } from "../schema.js";
+import type { ProceduralTextureConfig, TextureGeneratorName } from "./types.js";
+export declare const TEXTURE_SCHEMA_VERSION = "1.0.0";
+export declare const VALID_TEXTURE_GENERATORS: readonly TextureGeneratorName[];
+export declare const TEXTURE_OPTIONS_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly seed: {
+            readonly type: readonly ["number", "string"];
+        };
+        readonly width: {
+            readonly type: "number";
+            readonly minimum: 8;
+            readonly maximum: 2048;
+        };
+        readonly height: {
+            readonly type: "number";
+            readonly minimum: 8;
+            readonly maximum: 2048;
+        };
+        readonly quality: {
+            readonly type: "string";
+            readonly enum: readonly ["low", "medium", "high"];
+        };
+        readonly dpr: {
+            readonly type: "number";
+            readonly minimum: 0.5;
+            readonly maximum: 4;
+        };
+        readonly color: {
+            readonly type: "string";
+        };
+        readonly secondaryColor: {
+            readonly type: "string";
+        };
+        readonly accentColor: {
+            readonly type: "string";
+        };
+        readonly opacity: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+        };
+        readonly intensity: {
+            readonly type: "number";
+            readonly minimum: 0;
+        };
+        readonly scale: {
+            readonly anyOf: readonly [{
+                readonly type: "number";
+            }, {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "number";
+                };
+                readonly minItems: 2;
+                readonly maxItems: 2;
+            }];
+        };
+        readonly contrast: {
+            readonly type: "number";
+            readonly minimum: 0;
+        };
+        readonly roughness: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+        };
+        readonly angle: {
+            readonly type: "number";
+        };
+        readonly frequency: {
+            readonly type: "number";
+            readonly minimum: 0;
+        };
+        readonly custom: {
+            readonly type: "object";
+        };
+    };
+};
+export declare const TEXTURE_CONFIG_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["generator"];
+    readonly properties: {
+        readonly generator: {
+            readonly type: "string";
+            readonly enum: readonly TextureGeneratorName[];
+        };
+        readonly options: {
+            readonly type: "object";
+            readonly properties: {
+                readonly seed: {
+                    readonly type: readonly ["number", "string"];
+                };
+                readonly width: {
+                    readonly type: "number";
+                    readonly minimum: 8;
+                    readonly maximum: 2048;
+                };
+                readonly height: {
+                    readonly type: "number";
+                    readonly minimum: 8;
+                    readonly maximum: 2048;
+                };
+                readonly quality: {
+                    readonly type: "string";
+                    readonly enum: readonly ["low", "medium", "high"];
+                };
+                readonly dpr: {
+                    readonly type: "number";
+                    readonly minimum: 0.5;
+                    readonly maximum: 4;
+                };
+                readonly color: {
+                    readonly type: "string";
+                };
+                readonly secondaryColor: {
+                    readonly type: "string";
+                };
+                readonly accentColor: {
+                    readonly type: "string";
+                };
+                readonly opacity: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly maximum: 1;
+                };
+                readonly intensity: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+                readonly scale: {
+                    readonly anyOf: readonly [{
+                        readonly type: "number";
+                    }, {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "number";
+                        };
+                        readonly minItems: 2;
+                        readonly maxItems: 2;
+                    }];
+                };
+                readonly contrast: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+                readonly roughness: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly maximum: 1;
+                };
+                readonly angle: {
+                    readonly type: "number";
+                };
+                readonly frequency: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+                readonly custom: {
+                    readonly type: "object";
+                };
+            };
+        };
+    };
+};
+export declare function validateTextureOptions(input: unknown): ValidationReport;
+export declare function validateTextureConfig(input: unknown): ValidationReport;
+export declare function correctTextureConfig(input: unknown): ProceduralTextureConfig;
+export declare const TEXTURE_GENERATION_CAPABILITY: {
+    id: string;
+    name: string;
+    category: "graphics";
+    description: string;
+    tags: string[];
+    version: string;
+    parameters: ({
+        name: string;
+        kind: "positional";
+        type: string;
+        required: boolean;
+        description: string;
+    } | {
+        name: string;
+        kind: "option";
+        type: string;
+        required: boolean;
+        description: string;
+    })[];
+    supportedTargets: string[];
+    signature: {
+        importStatement: string;
+        invocation: string;
+        exampleCode: string;
+    };
+    controls: string[];
+    callbacks: never[];
+    reducedMotion: "static-fallback";
+    compatibility: {
+        browser: boolean;
+        ssr: boolean;
+        requiresCanvas: boolean;
+    };
+    react: {
+        available: boolean;
+        componentName: string;
+        hookName: string;
+        importPath: string;
+    };
+};
+export declare function registerTextureCapability(registry: {
+    registerCapability: (cap: any, opts?: any) => void;
+}): void;

package/dist/graphics/textures/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * AF Motion Procedural Textures & Patterns Contracts
+ *
+ * Framework-independent definitions for procedural texture generation,
+ * deterministic seeds, multi-backend rendering, caching, and material mapping.
+ */
+import type { DisposableResource } from "../types.js";
+export type TextureGeneratorName = "noise" | "paper" | "fabric" | "marble" | "wood" | "metal-brush" | "halftone" | "dots" | "stripes" | "organic-gradient" | "topographic" | "imperfections";
+export type TextureQuality = "low" | "medium" | "high";
+export type TextureBlendMode = "normal" | "multiply" | "screen" | "overlay" | "soft-light";
+export type TextureRepeatMode = "repeat" | "no-repeat" | "repeat-x" | "repeat-y";
+export interface WebGLTextureDescriptor {
+    readonly width: number;
+    readonly height: number;
+    readonly format: "rgba8" | "rgb8" | "r8";
+    readonly minFilter: "linear" | "nearest" | "linear-mipmap-linear";
+    readonly magFilter: "linear" | "nearest";
+    readonly wrapS: "repeat" | "clamp-to-edge" | "mirrored-repeat";
+    readonly wrapT: "repeat" | "clamp-to-edge" | "mirrored-repeat";
+    readonly source: HTMLCanvasElement | ImageData | Uint8Array | null;
+}
+export interface ProceduralTextureOptions {
+    readonly seed?: number | string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly quality?: TextureQuality;
+    readonly dpr?: number;
+    readonly color?: string;
+    readonly secondaryColor?: string;
+    readonly accentColor?: string;
+    readonly opacity?: number;
+    readonly intensity?: number;
+    readonly scale?: number | readonly [number, number];
+    readonly contrast?: number;
+    readonly roughness?: number;
+    readonly angle?: number;
+    readonly frequency?: number;
+    readonly custom?: Readonly<Record<string, unknown>>;
+}
+export interface ProceduralTextureConfig {
+    readonly generator: TextureGeneratorName;
+    readonly options?: ProceduralTextureOptions;
+}
+export interface GeneratedTexture extends DisposableResource {
+    readonly id: string;
+    readonly type: "procedural-texture";
+    readonly generator: TextureGeneratorName;
+    readonly seed: number;
+    readonly width: number;
+    readonly height: number;
+    readonly canvas: HTMLCanvasElement | null;
+    readonly dataUrl: string;
+    readonly cssBackground: string;
+    readonly webglDescriptor: WebGLTextureDescriptor | null;
+    readonly estimatedSizeBytes: number;
+    dispose(): void;
+}
+export interface TextureCacheStats {
+    readonly hits: number;
+    readonly misses: number;
+    readonly size: number;
+    readonly maxSize: number;
+    readonly memoryBytes: number;
+    readonly maxMemoryBytes: number;
+}
+export interface TextureMappingOptions {
+    readonly scale?: number | readonly [number, number];
+    readonly offset?: readonly [number, number];
+    readonly repeat?: TextureRepeatMode;
+    readonly blendMode?: TextureBlendMode;
+    readonly opacity?: number;
+}
+export interface TextureGeneratorMetadata {
+    readonly name: TextureGeneratorName;
+    readonly displayName: string;
+    readonly description: string;
+    readonly category: "noise" | "organic" | "geometric" | "material" | "artistic";
+    readonly defaultOptions: ProceduralTextureOptions;
+    readonly tags: readonly string[];
+}

package/dist/graphics/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * AF Motion Graphics Rendering Engine Contracts
+ *
+ * Framework-independent foundation for rendering abstractions,
+ * shader infrastructure, capability detection, effect lifecycles,
+ * and deterministic resource management.
+ */
+export type RendererBackend = "canvas2d" | "webgl" | "webgl2" | "webgpu" | "null";
+export type GraphicsEngineState = "idle" | "running" | "paused" | "destroyed";
+export interface GraphicsCapabilities {
+    readonly supportedBackends: readonly RendererBackend[];
+    readonly activeBackend: RendererBackend;
+    readonly canvas: boolean;
+    readonly webgl: boolean;
+    readonly webgl2: boolean;
+    readonly webgpu: boolean;
+    readonly maxTextureSize: number;
+    readonly dpr: number;
+    readonly reducedMotion: boolean;
+    readonly colorSpace: "srgb" | "display-p3";
+    readonly antialias: boolean;
+    readonly floatTextures: boolean;
+    readonly instancedArrays: boolean;
+    readonly powerPreference?: "default" | "high-performance" | "low-power";
+}
+export interface CapabilityDetectionOptions {
+    readonly forceFallback?: boolean;
+    readonly preferredBackend?: RendererBackend;
+    readonly targetDpr?: number;
+    readonly testCanvas?: HTMLCanvasElement | null;
+}
+export interface RendererOptions {
+    readonly backend?: RendererBackend | "auto";
+    readonly alpha?: boolean;
+    readonly antialias?: boolean;
+    readonly powerPreference?: "default" | "high-performance" | "low-power";
+    readonly preserveDrawingBuffer?: boolean;
+    readonly dpr?: number;
+    readonly fallbackBackend?: RendererBackend;
+}
+export interface RenderFrameContext {
+    readonly time: number;
+    readonly deltaTime: number;
+    readonly elapsedTime: number;
+    readonly frameIndex: number;
+    readonly width: number;
+    readonly height: number;
+    readonly pixelWidth: number;
+    readonly pixelHeight: number;
+    readonly dpr: number;
+    readonly canvas: HTMLCanvasElement;
+    readonly backend: RendererBackend;
+    readonly rawContext: unknown;
+}
+export interface Renderer {
+    readonly backend: RendererBackend;
+    readonly isInitialized: boolean;
+    readonly canvas: HTMLCanvasElement | null;
+    init(canvas: HTMLCanvasElement, options?: RendererOptions): Promise<void> | void;
+    render(context: RenderFrameContext): void;
+    resize(width: number, height: number, dpr: number): void;
+    clear(color?: readonly [number, number, number, number]): void;
+    getCapabilities(): GraphicsCapabilities;
+    destroy(): void;
+    onContextLost(listener: () => void): () => void;
+    onContextRestored(listener: () => void): () => void;
+}
+export interface DisposableResource {
+    readonly id: string;
+    readonly type: string;
+    dispose(): void;
+}
+export interface ResourceManager {
+    readonly size: number;
+    register(resource: DisposableResource, ownerId?: string): string;
+    get(resourceId: string): DisposableResource | undefined;
+    has(resourceId: string): boolean;
+    dispose(resourceId: string): boolean;
+    disposeOwnedBy(ownerId: string): number;
+    disposeAll(): void;
+    trackOwner(resourceId: string, ownerId: string): void;
+    release(resourceId: string): boolean;
+    getResourcesOwnedBy(ownerId: string): readonly DisposableResource[];
+}
+export interface GraphicsEffectRequirement {
+    readonly backend?: RendererBackend | readonly RendererBackend[];
+    readonly minTextureSize?: number;
+    readonly requiresFloatTextures?: boolean;
+    readonly requiresInstancing?: boolean;
+}
+export interface GraphicsEffectAccessibility {
+    readonly supportsReducedMotion?: boolean;
+    readonly respectsReducedMotion?: boolean;
+    readonly staticFallback?: boolean;
+}
+export interface GraphicsEffectInitContext {
+    readonly canvas: HTMLCanvasElement;
+    readonly renderer: Renderer;
+    readonly capabilities: GraphicsCapabilities;
+    readonly resourceManager: ResourceManager;
+    readonly width: number;
+    readonly height: number;
+    readonly dpr: number;
+}
+export interface GraphicsEffectUpdateContext extends RenderFrameContext {
+    readonly renderer: Renderer;
+    readonly resourceManager: ResourceManager;
+}
+export interface GraphicsEffect<TConfig = unknown> {
+    readonly id: string;
+    readonly name: string;
+    readonly version?: string;
+    readonly config?: TConfig;
+    readonly requirements?: GraphicsEffectRequirement;
+    readonly accessibility?: GraphicsEffectAccessibility;
+    init?(context: GraphicsEffectInitContext): Promise<void> | void;
+    render(context: GraphicsEffectUpdateContext): void;
+    resize?(width: number, height: number, dpr: number): void;
+    pause?(): void;
+    resume?(): void;
+    dispose?(): void;
+}
+export interface GraphicsEngineOptions {
+    readonly renderer?: Renderer | RendererOptions;
+    readonly dpr?: number | "auto";
+    readonly autoStart?: boolean;
+    readonly pauseOnHidden?: boolean;
+    readonly respectReducedMotion?: boolean;
+    readonly fpsLimit?: number;
+}
+export interface GraphicsEngine {
+    readonly state: GraphicsEngineState;
+    readonly renderer: Renderer | null;
+    readonly capabilities: GraphicsCapabilities;
+    readonly canvas: HTMLCanvasElement | null;
+    readonly resourceManager: ResourceManager;
+    readonly effects: readonly GraphicsEffect[];
+    attach(canvas: HTMLCanvasElement): Promise<void> | void;
+    detach(): void;
+    registerEffect(effect: GraphicsEffect): void;
+    unregisterEffect(effectId: string): boolean;
+    getEffect(effectId: string): GraphicsEffect | undefined;
+    hasEffect(effectId: string): boolean;
+    start(): void;
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    requestFrame(): void;
+    resize(width?: number, height?: number, dpr?: number): void;
+    onStateChange(listener: (state: GraphicsEngineState) => void): () => void;
+    destroy(): void;
+}

package/dist/graphics/viewport.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Canvas and viewport sizing, high-DPI scaling, and responsive lifecycle observers.
+ */
+export interface CanvasDimensions {
+    readonly width: number;
+    readonly height: number;
+    readonly dpr: number;
+    readonly pixelWidth: number;
+    readonly pixelHeight: number;
+}
+/**
+ * Updates an HTML5 canvas's backing pixel buffer and inline display style
+ * according to logical CSS dimensions and device pixel ratio.
+ */
+export declare function updateCanvasDimensions(canvas: HTMLCanvasElement, width: number, height: number, dpr?: number): {
+    pixelWidth: number;
+    pixelHeight: number;
+};
+/**
+ * Extracts current logical and physical pixel dimensions from a canvas element.
+ */
+export declare function getCanvasDimensions(canvas: HTMLCanvasElement, customDpr?: number): CanvasDimensions;
+/**
+ * Attaches a ResizeObserver to a container or canvas element safely,
+ * returning a cleanup function.
+ */
+export declare function setupResizeObserver(element: HTMLElement | HTMLCanvasElement, onResize: (width: number, height: number) => void): () => void;
+/**
+ * Attaches a document visibilitychange listener safely,
+ * invoking the callback when tab visibility switches.
+ */
+export declare function setupVisibilityObserver(onVisibilityChange: (visible: boolean) => void): () => void;