@guinetik/gcanvas 1.0.5 → 2.0.0

package/types/physics.d.ts

@@ -0,0 +1,299 @@
+/**
+ * Physics module type definitions
+ */
+
+/**
+ * Collision result from checkCollision
+ */
+export interface CollisionResult {
+  /** Distance between particle centers */
+  dist: number;
+  /** Overlap amount (how much they're intersecting) */
+  overlap: number;
+  /** X component of distance vector */
+  dx: number;
+  /** Y component of distance vector */
+  dy: number;
+  /** Z component of distance vector */
+  dz: number;
+}
+
+/**
+ * Force vector result
+ */
+export interface ForceResult {
+  /** Force X component */
+  fx: number;
+  /** Force Y component */
+  fy: number;
+  /** Force Z component */
+  fz: number;
+  /** Distance between objects */
+  dist: number;
+}
+
+/**
+ * Velocity result from collision response
+ */
+export interface VelocityResult {
+  vx: number;
+  vy: number;
+  vz: number;
+}
+
+/**
+ * Elastic collision response result
+ */
+export interface ElasticCollisionResult {
+  /** New velocity for first particle */
+  v1: VelocityResult;
+  /** New velocity for second particle */
+  v2: VelocityResult;
+}
+
+/**
+ * 3D bounding box
+ */
+export interface Bounds3D {
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+  minZ?: number;
+  maxZ?: number;
+}
+
+/**
+ * Sphere definition
+ */
+export interface Sphere {
+  x: number;
+  y: number;
+  z?: number;
+  radius: number;
+}
+
+/**
+ * Position in 3D space
+ */
+export interface Position3D {
+  x: number;
+  y: number;
+  z?: number;
+}
+
+/**
+ * Particle with physics properties
+ */
+export interface PhysicsParticle extends Position3D {
+  vx: number;
+  vy: number;
+  vz?: number;
+  size?: number;
+  radius?: number;
+  mass?: number;
+  alive?: boolean;
+  custom?: {
+    mass?: number;
+    [key: string]: any;
+  };
+}
+
+/**
+ * Particle updater function signature
+ */
+export type ParticleUpdater = (
+  particle: PhysicsParticle,
+  dt: number,
+  system?: any
+) => void;
+
+/**
+ * Static physics calculations
+ */
+export class Physics {
+  /**
+   * Calculate attraction/repulsion force using inverse square law
+   */
+  static attract(
+    p1: Position3D,
+    p2: Position3D,
+    strength?: number,
+    minDist?: number
+  ): ForceResult;
+
+  /**
+   * Calculate linear attraction force (constant strength)
+   */
+  static attractLinear(
+    p1: Position3D,
+    p2: Position3D,
+    strength?: number
+  ): ForceResult;
+
+  /**
+   * Check if two particles are colliding
+   */
+  static checkCollision(
+    p1: PhysicsParticle,
+    p2: PhysicsParticle,
+    threshold?: number
+  ): CollisionResult | null;
+
+  /**
+   * Calculate elastic collision response
+   */
+  static elasticCollision(
+    p1: PhysicsParticle,
+    p2: PhysicsParticle,
+    collision: CollisionResult,
+    restitution?: number
+  ): ElasticCollisionResult | null;
+
+  /**
+   * Separate overlapping particles
+   */
+  static separate(
+    p1: PhysicsParticle,
+    p2: PhysicsParticle,
+    collision: CollisionResult,
+    separationFactor?: number
+  ): void;
+
+  /**
+   * Check and respond to 3D boundary collision
+   */
+  static boundsCollision(
+    p: PhysicsParticle,
+    bounds: Bounds3D,
+    restitution?: number
+  ): boolean;
+
+  /**
+   * Check collision with spherical boundary
+   */
+  static sphereBoundsCollision(
+    p: PhysicsParticle,
+    sphere: Sphere,
+    restitution?: number,
+    inside?: boolean
+  ): boolean;
+
+  /**
+   * Calculate kinetic energy
+   */
+  static kineticEnergy(p: PhysicsParticle): number;
+
+  /**
+   * Calculate speed (velocity magnitude)
+   */
+  static speed(p: PhysicsParticle): number;
+
+  /**
+   * Calculate distance between two positions
+   */
+  static distance(p1: Position3D, p2: Position3D): number;
+
+  /**
+   * Calculate squared distance (faster)
+   */
+  static distanceSquared(p1: Position3D, p2: Position3D): number;
+
+  /**
+   * Clamp velocity to maximum speed
+   */
+  static clampVelocity(p: PhysicsParticle, maxSpeed: number): void;
+
+  /**
+   * Apply force to particle
+   */
+  static applyForce(
+    p: PhysicsParticle,
+    fx: number,
+    fy: number,
+    fz: number,
+    dt: number
+  ): void;
+}
+
+/**
+ * Composable physics updaters for ParticleSystem
+ */
+export const PhysicsUpdaters: {
+  /**
+   * Apply mutual attraction/repulsion between particles
+   */
+  mutualAttraction(
+    strength?: number,
+    cutoffDistance?: number,
+    minDistance?: number
+  ): ParticleUpdater;
+
+  /**
+   * Apply linear mutual attraction
+   */
+  mutualAttractionLinear(
+    strength?: number,
+    cutoffDistance?: number
+  ): ParticleUpdater;
+
+  /**
+   * Handle particle-particle elastic collisions
+   */
+  particleCollisions(
+    restitution?: number,
+    threshold?: number
+  ): ParticleUpdater;
+
+  /**
+   * Bounce off 3D box boundaries
+   */
+  bounds3D(bounds: Bounds3D, restitution?: number): ParticleUpdater;
+
+  /**
+   * Bounce inside spherical boundary
+   */
+  sphereBounds(sphere: Sphere, restitution?: number): ParticleUpdater;
+
+  /**
+   * Attract toward a point
+   */
+  attractToPoint(
+    target: Position3D | (() => Position3D),
+    strength?: number,
+    minDist?: number
+  ): ParticleUpdater;
+
+  /**
+   * Apply uniform gravity
+   */
+  gravity(gx?: number, gy?: number, gz?: number): ParticleUpdater;
+
+  /**
+   * Limit maximum speed
+   */
+  maxSpeed(maxSpeed: number): ParticleUpdater;
+
+  /**
+   * Apply velocity drag
+   */
+  drag(coefficient?: number): ParticleUpdater;
+
+  /**
+   * Apply separation force to prevent overlap
+   */
+  separation(strength?: number, threshold?: number): ParticleUpdater;
+
+  /**
+   * Apply thermal motion (random jitter)
+   */
+  thermal(
+    temperature: number | (() => number),
+    scale?: number
+  ): ParticleUpdater;
+
+  /**
+   * Apply orbital motion around center
+   */
+  orbital(center: Position3D, strength?: number): ParticleUpdater;
+};

package/types/shapes.d.ts

@@ -684,6 +684,14 @@ export class BezierShape extends Shape {
  * SVG path shape.
  */
 export class SVGShape extends Shape {
+  /**
+   * Load an SVG file from a URL and create an SVGShape
+   * @param url - URL to the SVG file
+   * @param options - Shape options
+   * @returns Promise that resolves to the SVGShape instance
+   */
+  static fromURL(url: string, options?: ShapeOptions): Promise<SVGShape>;
+
   /**
    * @param svgPath - SVG path string (d attribute)
    * @param options - Shape options

package/types/webgl.d.ts

@@ -1,109 +1,188 @@
-/**
- * GCanvas WebGL Module
- * Optional WebGL rendering capabilities for enhanced visual effects.
- * @module webgl
- */
-
-// ==========================================================================
-// WebGL Renderer
-// ==========================================================================
-
-/** WebGL renderer options */
-export interface WebGLRendererOptions {
-  /** Canvas element */
-  canvas: HTMLCanvasElement;
-  /** Whether to preserve drawing buffer */
-  preserveDrawingBuffer?: boolean;
-  /** Enable antialiasing */
-  antialias?: boolean;
-  /** Enable alpha blending */
-  alpha?: boolean;
-  /** Enable depth testing */
-  depth?: boolean;
-  /** Enable stencil buffer */
-  stencil?: boolean;
-  /** Premultiplied alpha */
-  premultipliedAlpha?: boolean;
-}
-
-/**
- * WebGL renderer for enhanced visual effects.
- * Provides shader-based rendering for complex effects.
- */
-export class WebGLRenderer {
-  /** WebGL rendering context */
-  readonly gl: WebGLRenderingContext | WebGL2RenderingContext;
-  /** Canvas element */
-  readonly canvas: HTMLCanvasElement;
-  /** Whether WebGL is available */
-  readonly isAvailable: boolean;
-
-  constructor(options: WebGLRendererOptions);
-
-  /**
-   * Create and compile a shader program.
-   * @param vertexSource - Vertex shader GLSL source
-   * @param fragmentSource - Fragment shader GLSL source
-   * @returns Compiled shader program
-   */
-  createProgram(vertexSource: string, fragmentSource: string): WebGLProgram;
-
-  /**
-   * Set uniform value.
-   * @param program - Shader program
-   * @param name - Uniform name
-   * @param value - Uniform value
-   */
-  setUniform(program: WebGLProgram, name: string, value: number | number[] | Float32Array): void;
-
-  /**
-   * Create a texture from an image or canvas.
-   * @param source - Image or canvas source
-   * @returns WebGL texture
-   */
-  createTexture(source: HTMLImageElement | HTMLCanvasElement | ImageData): WebGLTexture;
-
-  /**
-   * Render a full-screen quad with a shader.
-   * @param program - Shader program to use
-   */
-  renderFullscreenQuad(program: WebGLProgram): void;
-
-  /**
-   * Clear the canvas.
-   * @param r - Red (0-1)
-   * @param g - Green (0-1)
-   * @param b - Blue (0-1)
-   * @param a - Alpha (0-1)
-   */
-  clear(r?: number, g?: number, b?: number, a?: number): void;
-
-  /**
-   * Resize the renderer to match canvas size.
-   */
-  resize(): void;
-
-  /**
-   * Dispose of WebGL resources.
-   */
-  dispose(): void;
-}
-
-// ==========================================================================
-// Shader Collections
-// ==========================================================================
-
-/**
- * Pre-built shaders for 3D sphere rendering.
- */
-export namespace SPHERE_SHADERS {
-  /** Basic sphere vertex shader */
-  const vertex: string;
-  /** Basic sphere fragment shader with lighting */
-  const fragment: string;
-  /** Glow effect fragment shader */
-  const glowFragment: string;
-  /** Atmosphere effect fragment shader */
-  const atmosphereFragment: string;
-}
-
+/**
+ * GCanvas WebGL Module
+ * Optional WebGL rendering capabilities for enhanced visual effects.
+ * @module webgl
+ */
+
+/**
+ * WebGL renderer for enhanced visual effects.
+ * Provides shader-based rendering for complex effects.
+ */
+export class WebGLRenderer {
+  constructor(width: number, height: number);
+
+  isAvailable(): boolean;
+  resize(width: number, height: number): void;
+  useProgram(name: string, vertexSource: string, fragmentSource: string): WebGLProgram | null;
+  setUniforms(uniforms: Record<string, number | number[] | Float32Array>): void;
+  setColorUniform(name: string, color: string): void;
+  clear(r?: number, g?: number, b?: number, a?: number): void;
+  render(): void;
+  compositeOnto(ctx: CanvasRenderingContext2D, x: number, y: number, width?: number, height?: number): void;
+  getCanvas(): HTMLCanvasElement;
+  destroy(): void;
+}
+
+export type WebGLBlendMode = "alpha" | "additive";
+export type PointSpriteShape = "circle" | "glow" | "square" | "softSquare";
+
+export class WebGLParticleRenderer {
+  constructor(
+    maxParticles?: number,
+    options?: {
+      width?: number;
+      height?: number;
+      shape?: PointSpriteShape;
+      blendMode?: WebGLBlendMode;
+    }
+  );
+
+  isAvailable(): boolean;
+  setBlendMode(mode: WebGLBlendMode): void;
+  setShape(shape: PointSpriteShape): void;
+  resize(width: number, height: number): void;
+  updateParticles(particles: Array<{ x: number; y: number; size: number; color: { r: number; g: number; b: number; a: number } }>): number;
+  clear(r?: number, g?: number, b?: number, a?: number): void;
+  render(count: number): void;
+  compositeOnto(ctx: CanvasRenderingContext2D, x?: number, y?: number, width?: number, height?: number): void;
+  destroy(): void;
+}
+
+export class WebGLLineRenderer {
+  constructor(
+    maxSegments?: number,
+    options?: {
+      width?: number;
+      height?: number;
+      blendMode?: WebGLBlendMode;
+    }
+  );
+
+  isAvailable(): boolean;
+  setBlendMode(mode: WebGLBlendMode): void;
+  resize(width: number, height: number): void;
+  updateLines(segments: any[]): number;
+  clear(r?: number, g?: number, b?: number, a?: number): void;
+  render(count: number): void;
+  compositeOnto(ctx: CanvasRenderingContext2D, x?: number, y?: number): void;
+  destroy(): void;
+}
+
+export const DEJONG_MAX_ITERATIONS: number;
+export const DEJONG_POINT_VERTEX: string;
+export const DEJONG_POINT_FRAGMENTS: Record<PointSpriteShape, string>;
+
+export const CLIFFORD_MAX_ITERATIONS: number;
+export const CLIFFORD_POINT_VERTEX: string;
+export const CLIFFORD_POINT_FRAGMENTS: Record<PointSpriteShape, string>;
+
+export class WebGLDeJongRenderer {
+  constructor(
+    seedCount?: number,
+    options?: {
+      width?: number;
+      height?: number;
+      shape?: PointSpriteShape;
+      blendMode?: WebGLBlendMode;
+      pointSize?: number;
+      pointScale?: number;
+      iterations?: number;
+      params?: { a: number; b: number; c: number; d: number };
+      color?: { r: number; g: number; b: number; a: number };
+      colorMode?: 0 | 1;
+      hueRange?: { minHue: number; maxHue: number };
+      maxSpeed?: number;
+      saturation?: number; // 0..1
+      lightness?: number; // 0..1
+      alpha?: number; // 0..1
+      hueShiftSpeed?: number; // degrees/sec
+    }
+  );
+
+  static identityMat3(): Float32Array;
+  static rotationMat3(angle: number): Float32Array;
+
+  isAvailable(): boolean;
+  resize(width: number, height: number): void;
+  setSeedCount(seedCount: number): void;
+  regenerateSeeds(): void;
+  setShape(shape: PointSpriteShape): void;
+  setBlendMode(mode: WebGLBlendMode): void;
+  setParams(params: { a?: number; b?: number; c?: number; d?: number }): void;
+  setIterations(iterations: number): void;
+  setZoom(zoom: number): void;
+  setTransform(mat3: Float32Array): void;
+  setPointSize(size: number): void;
+  setColor(color: { r?: number; g?: number; b?: number; a?: number }): void;
+  setColorMode(mode: 0 | 1): void;
+  setColorRamp(options: {
+    minHue?: number;
+    maxHue?: number;
+    maxSpeed?: number;
+    saturation?: number;
+    lightness?: number;
+    alpha?: number;
+    hueShiftSpeed?: number;
+  }): void;
+  clear(r?: number, g?: number, b?: number, a?: number): void;
+  render(timeSeconds?: number): void;
+  compositeOnto(ctx: CanvasRenderingContext2D, x?: number, y?: number, width?: number, height?: number): void;
+  destroy(): void;
+}
+
+export class WebGLCliffordRenderer {
+  constructor(
+    seedCount?: number,
+    options?: {
+      width?: number;
+      height?: number;
+      shape?: PointSpriteShape;
+      blendMode?: WebGLBlendMode;
+      pointSize?: number;
+      pointScale?: number;
+      iterations?: number;
+      params?: { a: number; b: number; c: number; d: number };
+      color?: { r: number; g: number; b: number; a: number };
+      colorMode?: 0 | 1;
+      hueRange?: { minHue: number; maxHue: number };
+      maxSpeed?: number;
+      saturation?: number; // 0..1
+      lightness?: number; // 0..1
+      alpha?: number; // 0..1
+      hueShiftSpeed?: number; // degrees/sec
+    }
+  );
+
+  static identityMat3(): Float32Array;
+  static rotationMat3(angle: number): Float32Array;
+
+  isAvailable(): boolean;
+  resize(width: number, height: number): void;
+  setSeedCount(seedCount: number): void;
+  regenerateSeeds(): void;
+  setShape(shape: PointSpriteShape): void;
+  setBlendMode(mode: WebGLBlendMode): void;
+  setParams(params: { a?: number; b?: number; c?: number; d?: number }): void;
+  setIterations(iterations: number): void;
+  setZoom(zoom: number): void;
+  setTransform(mat3: Float32Array): void;
+  setPointSize(size: number): void;
+  setColor(color: { r?: number; g?: number; b?: number; a?: number }): void;
+  setColorMode(mode: 0 | 1): void;
+  setColorRamp(options: {
+    minHue?: number;
+    maxHue?: number;
+    maxSpeed?: number;
+    saturation?: number;
+    lightness?: number;
+    alpha?: number;
+    hueShiftSpeed?: number;
+  }): void;
+  clear(r?: number, g?: number, b?: number, a?: number): void;
+  render(timeSeconds?: number): void;
+  compositeOnto(ctx: CanvasRenderingContext2D, x?: number, y?: number, width?: number, height?: number): void;
+  destroy(): void;
+}
+
+export const SPHERE_SHADERS: any;
+