@guinetik/gcanvas 1.0.0 → 1.0.2

package/types/index.d.ts

@@ -2,7 +2,7 @@
  * GCanvas - TypeScript Definitions
  * A minimalist 2D canvas rendering library with shapes, game engine, and animations.
  *
- * @version 0.0.3-alpha
+ * @version 1.0.1
  * @see https://github.com/guinetik/gcanvas
  * @license ISC
  */
@@ -100,6 +100,7 @@ export {
   PatternRectangleOptions,
   ImageShape,
   ImageShapeOptions,
+  BitmapSource,
 
   // 2.5D shapes
   Cube,
@@ -108,6 +109,8 @@ export {
   Cone,
   Prism,
   Sphere,
+  Sphere3D,
+  Sphere3DOptions,
 
   // Text shapes
   TextShape,
@@ -174,7 +177,22 @@ export {
   ToggleButton,
   Cursor,
   CursorOptions,
-  FPSCounter
+  FPSCounter,
+  Tooltip,
+  TooltipOptions,
+  Stepper,
+  StepperOptions,
+  UI_THEME,
+
+  // 3D and Isometric scenes
+  Scene3D,
+  Scene3DOptions,
+  IsometricScene,
+  IsometricSceneOptions,
+
+  // Fluid simulation
+  FluidSystem,
+  FluidSystemOptions
 } from './game';
 
 // ==========================================================================
@@ -188,7 +206,25 @@ export {
   TweenetikOptions,
   Motion,
   SpringParams,
-  PositionTarget
+  PositionTarget,
+
+  // Standalone motion functions (V1 API)
+  bezierV1,
+  bounceV1,
+  floatV1,
+  followPath,
+  orbitV1,
+  oscillateV1,
+  parabolicV1,
+  patrolV1,
+  pendulumV1,
+  pulseV1,
+  hopV1,
+  shakeV1,
+  spiralV1,
+  springV1,
+  swingV1,
+  waypointV1
 } from './motion';
 
 // ==========================================================================
@@ -201,7 +237,41 @@ export {
   Fractals,
   Patterns,
   Noise,
-  generatePenroseTilingPixels
+  generatePenroseTilingPixels,
+
+  // Tensor for GR calculations
+  Tensor,
+  TensorOptions,
+
+  // Physics modules (General Relativity)
+  gravitationalLensingAngle,
+  timeDilationFactor,
+  gravitationalRedshift,
+
+  // Orbital Mechanics
+  OrbitalState,
+  OrbitalElements,
+  orbitalVelocity,
+  orbitalPeriod,
+  elementsToState,
+  propagateOrbit,
+
+  // Quantum Mechanics
+  gaussianWavePacket,
+  probabilityDensity,
+  particleInBox,
+  harmonicOscillator,
+
+  // Heat Transfer
+  heatTransfer,
+  buoyancyForce,
+  temperatureDecay,
+
+  // Fluid Dynamics
+  viscosityDrag,
+  surfaceTension,
+  reynoldsNumber,
+  pressureGradient
 } from './math';
 
 // ==========================================================================
@@ -226,7 +296,19 @@ export {
   horizontalLayout,
   verticalLayout,
   tileLayout,
-  gridLayout
+  gridLayout,
+
+  // Camera3D
+  Camera3D,
+  Camera3DOptions,
+  ProjectedPoint,
+  MouseControlOptions,
+  FollowOptions,
+  MoveToOptions,
+
+  // IsometricCamera
+  IsometricCamera,
+  IsometricCameraOptions
 } from './util';
 
 // ==========================================================================
@@ -307,3 +389,60 @@ export {
   PhaseConfig,
   SequenceOptions
 } from './state';
+
+// ==========================================================================
+// Fluent API Module
+// ==========================================================================
+
+export {
+  // Entry points
+  gcanvas,
+  sketch,
+
+  // Builder classes
+  FluentGame,
+  FluentGameOptions,
+  FluentScene,
+  FluentSceneOptions,
+  FluentGO,
+  FluentLayer,
+
+  // Sketch API
+  SketchAPI,
+  SketchContext,
+
+  // Context
+  FluentContext,
+  TransitionOptions
+} from './fluent';
+
+// ==========================================================================
+// Particle System Module
+// ==========================================================================
+
+export {
+  // Core classes
+  Particle,
+  ParticleEmitter,
+  ParticleSystem,
+
+  // Types
+  ParticleColor,
+  ParticleShape,
+  ParticleEmitterOptions,
+  ParticleSystemOptions,
+  ParticleUpdater,
+
+  // Updaters namespace
+  Updaters
+} from './particle';
+
+// ==========================================================================
+// WebGL Module (Optional)
+// ==========================================================================
+
+export {
+  WebGLRenderer,
+  WebGLRendererOptions,
+  SPHERE_SHADERS
+} from './webgl';

package/types/math.d.ts

@@ -266,3 +266,364 @@ export function generatePenroseTilingPixels(
   height?: number,
   options?: PenroseTilingOptions
 ): Uint8ClampedArray;
+
+// ==========================================================================
+// Tensor (Rank-2 Tensor for General Relativity)
+// ==========================================================================
+
+/** Tensor creation options */
+export interface TensorOptions {
+  /** Name of the tensor (e.g., 'Schwarzschild') */
+  name?: string;
+  /** Metric signature (e.g., [-1, 1, 1, 1]) */
+  signature?: number[];
+  /** Coordinate names (e.g., ['t', 'r', 'θ', 'φ']) */
+  coordinates?: string[];
+}
+
+/**
+ * Rank-2 Tensor class for general relativity calculations.
+ * Provides immutable tensor operations following the Complex class pattern.
+ *
+ * @example
+ * const g = Tensor.schwarzschild(10, 2);
+ * console.log(g.get(0, 0)); // g_tt component
+ */
+export class Tensor {
+  /** Tensor dimension (n for n×n tensor) */
+  readonly dimension: number;
+  /** Tensor name */
+  readonly name: string;
+  /** Metric signature */
+  readonly signature: number[] | null;
+  /** Coordinate names */
+  readonly coordinates: string[] | null;
+
+  /**
+   * Create a new rank-2 tensor from a 2D array of components.
+   * @param components - 2D array of tensor components
+   * @param options - Optional metadata
+   */
+  constructor(components: number[][], options?: TensorOptions);
+
+  // Static Factory Methods
+  /** Create a Minkowski (flat spacetime) metric tensor */
+  static minkowski(): Tensor;
+
+  /**
+   * Create a Schwarzschild metric tensor at a given radial position.
+   * @param r - Radial coordinate (must be > rs)
+   * @param rs - Schwarzschild radius (2GM/c²)
+   * @param theta - Polar angle (default: equatorial plane)
+   */
+  static schwarzschild(r: number, rs: number, theta?: number): Tensor;
+
+  /** Create contravariant Schwarzschild metric */
+  static schwarzschildContravariant(r: number, rs: number, theta?: number): Tensor;
+
+  /**
+   * Create a Kerr metric tensor (rotating black hole).
+   * @param r - Radial coordinate
+   * @param theta - Polar angle
+   * @param M - Mass parameter
+   * @param a - Spin parameter (0 ≤ a ≤ M)
+   */
+  static kerr(r: number, theta: number, M: number, a: number): Tensor;
+
+  /** Create contravariant Kerr metric */
+  static kerrContravariant(r: number, theta: number, M: number, a: number): Tensor;
+
+  /** Calculate Kerr horizon radius */
+  static kerrHorizonRadius(M: number, a: number, inner?: boolean): number;
+
+  /** Calculate ergosphere radius */
+  static kerrErgosphereRadius(M: number, a: number, theta: number): number;
+
+  /** Calculate ISCO radius for Kerr metric */
+  static kerrISCO(M: number, a: number, prograde?: boolean): number;
+
+  /** Calculate frame-dragging angular velocity */
+  static kerrFrameDraggingOmega(r: number, theta: number, M: number, a: number): number;
+
+  /** Calculate Kerr effective potential */
+  static kerrEffectivePotential(M: number, a: number, E: number, L: number, r: number): number;
+
+  /** Create a diagonal tensor */
+  static diagonal(values: number[], options?: TensorOptions): Tensor;
+
+  /** Create an identity tensor */
+  static identity(n?: number): Tensor;
+
+  /** Create a zero tensor */
+  static zero(n?: number): Tensor;
+
+  // Component Access
+  /** Get a component at indices */
+  get(i: number, j: number): number;
+
+  /** Return new tensor with component changed */
+  set(i: number, j: number, value: number): Tensor;
+
+  /** Get diagonal components */
+  getDiagonal(): number[];
+
+  // Tensor Operations
+  /** Add another tensor */
+  add(other: Tensor): Tensor;
+
+  /** Subtract another tensor */
+  subtract(other: Tensor): Tensor;
+
+  /** Multiply by scalar */
+  scale(scalar: number): Tensor;
+
+  /** Matrix multiply with another tensor */
+  multiply(other: Tensor): Tensor;
+
+  /** Transpose tensor */
+  transpose(): Tensor;
+
+  /** Compute inverse */
+  inverse(): Tensor;
+
+  // Derived Quantities
+  /** Compute determinant */
+  determinant(): number;
+
+  /** Compute trace */
+  trace(): number;
+
+  /** Check if diagonal */
+  isDiagonal(tolerance?: number): boolean;
+
+  /** Check if symmetric */
+  isSymmetric(tolerance?: number): boolean;
+
+  // GR Utilities
+  /**
+   * Compute Christoffel symbols for a metric.
+   * @param metricFn - Function returning metric at position
+   * @param position - Position [t, r, θ, φ]
+   * @param delta - Step size for numerical differentiation
+   */
+  static christoffel(
+    metricFn: (position: number[]) => Tensor,
+    position: number[],
+    delta?: number
+  ): number[][][];
+
+  /** Analytical Christoffel symbols for Schwarzschild */
+  static schwarzschildChristoffel(r: number, rs: number, theta: number): number[][][];
+
+  /** Compute effective potential for Schwarzschild geodesics */
+  static effectivePotential(M: number, L: number, r: number): number;
+
+  /** ISCO radius for Schwarzschild */
+  static iscoRadius(rs: number): number;
+
+  /** Photon sphere radius */
+  static photonSphereRadius(rs: number): number;
+
+  // Display
+  /** Get flat array of components */
+  toArray(): number[];
+
+  /** Get 2D array copy */
+  toMatrix(): number[][];
+
+  /** String representation */
+  toString(precision?: number): string;
+
+  /** LaTeX representation */
+  toLatex(precision?: number): string;
+}
+
+// ==========================================================================
+// General Relativity (gr.js)
+// ==========================================================================
+
+/**
+ * Calculate gravitational lensing deflection.
+ * @param b - Impact parameter
+ * @param M - Mass
+ * @returns Deflection angle in radians
+ */
+export function gravitationalLensingAngle(b: number, M: number): number;
+
+/**
+ * Calculate time dilation factor.
+ * @param r - Radial coordinate
+ * @param rs - Schwarzschild radius
+ * @returns Time dilation factor (0-1)
+ */
+export function timeDilationFactor(r: number, rs: number): number;
+
+/**
+ * Calculate gravitational redshift.
+ * @param r - Radial coordinate
+ * @param rs - Schwarzschild radius
+ * @returns Redshift z
+ */
+export function gravitationalRedshift(r: number, rs: number): number;
+
+// ==========================================================================
+// Orbital Mechanics (orbital.js)
+// ==========================================================================
+
+/** Orbital state vector */
+export interface OrbitalState {
+  x: number;
+  y: number;
+  z: number;
+  vx: number;
+  vy: number;
+  vz: number;
+}
+
+/** Keplerian orbital elements */
+export interface OrbitalElements {
+  a: number;  // Semi-major axis
+  e: number;  // Eccentricity
+  i: number;  // Inclination
+  Omega: number;  // Right ascension of ascending node
+  omega: number;  // Argument of periapsis
+  nu: number;  // True anomaly
+}
+
+/**
+ * Calculate orbital velocity at radius.
+ * @param r - Orbital radius
+ * @param M - Central mass
+ * @returns Orbital velocity
+ */
+export function orbitalVelocity(r: number, M: number): number;
+
+/**
+ * Calculate orbital period.
+ * @param a - Semi-major axis
+ * @param M - Central mass
+ * @returns Orbital period
+ */
+export function orbitalPeriod(a: number, M: number): number;
+
+/**
+ * Convert Keplerian elements to state vector.
+ * @param elements - Orbital elements
+ * @param mu - Gravitational parameter
+ */
+export function elementsToState(elements: OrbitalElements, mu: number): OrbitalState;
+
+/**
+ * Propagate orbit using Runge-Kutta.
+ * @param state - Current state
+ * @param dt - Time step
+ * @param mu - Gravitational parameter
+ */
+export function propagateOrbit(state: OrbitalState, dt: number, mu: number): OrbitalState;
+
+// ==========================================================================
+// Quantum Mechanics (quantum.js)
+// ==========================================================================
+
+/**
+ * Gaussian wave packet.
+ * @param x - Position
+ * @param x0 - Center position
+ * @param k0 - Central wavenumber
+ * @param sigma - Width parameter
+ * @param t - Time
+ * @returns Complex amplitude {re, im}
+ */
+export function gaussianWavePacket(
+  x: number,
+  x0: number,
+  k0: number,
+  sigma: number,
+  t: number
+): { re: number; im: number };
+
+/**
+ * Probability density |Ψ|².
+ * @param psi - Wave function value {re, im}
+ */
+export function probabilityDensity(psi: { re: number; im: number }): number;
+
+/**
+ * Particle in a box wave function.
+ * @param x - Position (0 to L)
+ * @param L - Box length
+ * @param n - Quantum number
+ */
+export function particleInBox(x: number, L: number, n: number): number;
+
+/**
+ * Harmonic oscillator wave function.
+ * @param x - Position
+ * @param n - Energy level
+ * @param omega - Angular frequency
+ * @param m - Mass
+ */
+export function harmonicOscillator(x: number, n: number, omega: number, m: number): number;
+
+// ==========================================================================
+// Heat Transfer (heat.js)
+// ==========================================================================
+
+/**
+ * Calculate heat transfer between two objects.
+ * @param T1 - Temperature of object 1
+ * @param T2 - Temperature of object 2
+ * @param k - Thermal conductivity
+ * @param dt - Time step
+ */
+export function heatTransfer(T1: number, T2: number, k: number, dt: number): number;
+
+/**
+ * Calculate buoyancy force.
+ * @param temperature - Object temperature
+ * @param ambientTemp - Ambient temperature
+ * @param coefficient - Buoyancy coefficient
+ */
+export function buoyancyForce(temperature: number, ambientTemp: number, coefficient: number): number;
+
+/**
+ * Temperature decay toward ambient.
+ * @param temp - Current temperature
+ * @param ambientTemp - Ambient temperature
+ * @param rate - Decay rate
+ * @param dt - Time step
+ */
+export function temperatureDecay(temp: number, ambientTemp: number, rate: number, dt: number): number;
+
+// ==========================================================================
+// Fluid Dynamics (fluid.js)
+// ==========================================================================
+
+/**
+ * Calculate viscosity drag force.
+ * @param velocity - Velocity vector
+ * @param viscosity - Fluid viscosity
+ */
+export function viscosityDrag(velocity: { x: number; y: number }, viscosity: number): { x: number; y: number };
+
+/**
+ * Calculate surface tension force.
+ * @param curvature - Surface curvature
+ * @param tension - Surface tension coefficient
+ */
+export function surfaceTension(curvature: number, tension: number): number;
+
+/**
+ * Calculate Reynolds number.
+ * @param velocity - Flow velocity
+ * @param length - Characteristic length
+ * @param viscosity - Kinematic viscosity
+ */
+export function reynoldsNumber(velocity: number, length: number, viscosity: number): number;
+
+/**
+ * Navier-Stokes pressure term.
+ * @param density - Fluid density
+ * @param pressure - Pressure
+ */
+export function pressureGradient(density: number, pressure: number): number;