@actis/core 26.3.0 → 26.9.0

package/dist/index.d.cts

@@ -1,84 +1,279 @@
-//#region src/types/renderer.d.ts
-type PassConfig = {
-  name: string;
-  fragmentShader: string;
-  vertexShader?: string;
-  offscreen?: boolean;
-  textures: string[];
-};
-type RendererConfig = {
-  passes: PassConfig[];
-};
+import { AttachmentOptions, BufferInfo, FramebufferInfo, ProgramInfo } from "twgl.js";
+
+//#region src/types/gl.d.ts
+type GL = WebGLRenderingContext | WebGL2RenderingContext;
+type GLContextCapabilities = Readonly<{
+  isWebGL2: boolean;
+  supportsFloatColorBuffer: boolean;
+  supportsFloatTexture: boolean;
+  supportsFloatTextureLinear: boolean;
+}>;
 //#endregion
-//#region src/types/shader.d.ts
-type ShaderError = {
-  passName: string;
-  coords: {
-    line: number;
-    message: string;
-  };
-};
-type UniformType = '1f' | '1i' | '2fv' | '3fv' | '4fv';
+//#region src/types/context.d.ts
+type GLContextVersion = 1 | 2;
+type RendererContext = Readonly<{
+  capabilities: GLContextCapabilities;
+  webglVersion: GLContextVersion;
+}>;
 //#endregion
 //#region src/shader/Shader.d.ts
 /**
- * Compiles and manages a WebGL shader program.
+ * Compiles and manages a WebGL shader program using twgl.js.
  * Responsible for compiling, linking, and providing access to uniforms and attributes.
  */
 declare class Shader {
   private gl;
-  private program;
-  private uniformLocations;
+  private readonly capabilities;
+  programInfo: ProgramInfo;
   private onError;
-  private passName;
-  constructor(gl: WebGLRenderingContext, vertexSource: string | undefined, fragmentSource: string, onError: (details: ShaderError) => void, passName: string);
-  private compileShader;
+  readonly passName: string;
+  constructor(gl: GL, capabilities: GLContextCapabilities, vertexSource: string | undefined, fragmentSource: string, onError: (details: ShaderError) => void, passName: string);
   private extractErrorCoords;
-  private linkProgram;
   use(): void;
-  setUniform(name: string, type: UniformType, ...values: any[]): void;
+  setUniforms(uniforms: ShaderUniformMap): void;
   getAttribLocation(name: string): number;
   private defaultVertexShader;
 }
 //#endregion
+//#region src/types/texture.d.ts
+type TextureWrapMode = number | 'clamp-to-edge' | 'repeat' | 'mirrored-repeat';
+type TextureFilterMode = number | 'nearest' | 'linear' | 'nearest-mipmap-nearest' | 'linear-mipmap-nearest' | 'nearest-mipmap-linear' | 'linear-mipmap-linear';
+type TextureOptions = Omit<AttachmentOptions, 'auto' | 'mag' | 'min' | 'minMag' | 'wrap' | 'wrapS' | 'wrapT'> & {
+  auto?: boolean;
+  generateMipmaps?: boolean;
+  mag?: TextureFilterMode;
+  magFilter?: TextureFilterMode;
+  min?: TextureFilterMode;
+  minFilter?: TextureFilterMode;
+  minMag?: TextureFilterMode;
+  wrap?: TextureWrapMode;
+  wrapS?: TextureWrapMode;
+  wrapT?: TextureWrapMode;
+};
+//#endregion
+//#region src/texture/TextureParameters.d.ts
+type TextureFramebufferAttachmentOptions = AttachmentOptions;
+//#endregion
+//#region src/texture/Texture.d.ts
+/**
+ * Minimal named wrapper around a WebGL texture handle.
+ * Used internally for pass outputs and texture bindings.
+ */
+declare class Texture {
+  readonly name: string;
+  private capabilities?;
+  private readonly options;
+  private handleValue;
+  constructor(name: string, options?: TextureOptions, handle?: WebGLTexture, capabilities?: GLContextCapabilities);
+  get handle(): WebGLTexture | undefined;
+  applyParameters(gl: GL): void;
+  generateMipmap(gl: GL, width: number, height: number): boolean;
+  getFramebufferAttachmentOptions(gl: GL): TextureFramebufferAttachmentOptions;
+  setHandle(handle?: WebGLTexture): this;
+  private getCapabilities;
+}
+//#endregion
+//#region src/fbo/FBO.d.ts
+/**
+ * Wrapper around a WebGL framebuffer and its color attachment texture.
+ */
+declare class FBO {
+  private gl;
+  private readonly capabilities;
+  private framebufferInfo;
+  width: number;
+  height: number;
+  readonly texture: Texture;
+  constructor(gl: GL, capabilities: GLContextCapabilities, width: number, height: number, texture: Texture);
+  private create;
+  get info(): FramebufferInfo;
+  bind(): void;
+  resize(width: number, height: number): void;
+  clear(framebufferInfo?: FramebufferInfo): void;
+  private getAttachmentOptions;
+  private ensureAttachmentSupport;
+  private assertFramebufferComplete;
+}
+//#endregion
 //#region src/pass/Pass.d.ts
 /**
  * Represents a render pass in the WebGL pipeline.
- * Responsible for managing framebuffer, texture, and draw calls for a single pass.
  */
 declare class Pass {
-  gl: WebGLRenderingContext;
+  gl: GL;
   shader: Shader;
   width: number;
   height: number;
-  texture: WebGLTexture;
-  framebuffer: WebGLFramebuffer;
-  next: Pass | null;
   offscreen: boolean;
-  textures: WebGLTexture[];
-  positionBuffer: WebGLBuffer;
-  positionAttributeLocation: number;
-  constructor(gl: WebGLRenderingContext, shader: Shader, width: number, height: number, offscreen?: boolean, textures?: WebGLTexture[]);
+  pingPong: boolean;
+  textures: Array<Texture | undefined>;
+  bufferInfo: BufferInfo;
+  private fbos;
+  private readBufferIndex;
+  constructor(gl: GL, capabilities: GLContextCapabilities, shader: Shader, geometry: BufferInfo, width: number, height: number, offscreen?: boolean, textures?: Array<Texture | undefined>, pingPong?: boolean, textureOptions?: TextureOptions);
+  get fbo(): FBO | null;
+  get texture(): Texture | undefined;
   use(): void;
   resize(width: number, height: number): void;
   draw(): void;
-  private createTexture;
-  private createFramebuffer;
-  private createPositionBuffer;
+  clear(): void;
+  private get readFBO();
+  private get writeFBO();
+  private swap;
 }
 //#endregion
-//#region src/engine/WebGLRenderer.d.ts
+//#region src/types/renderer.d.ts
+declare const TEXTURE_CHANNEL_COUNT = 4;
+type PassConfig = {
+  name: string;
+  fragmentShader: string;
+  texture?: TextureOptions;
+  vertexShader?: string;
+  pingPong?: boolean;
+  textures: string[];
+};
+type RendererConfig = {
+  passes: PassConfig[];
+};
+type RendererMetrics = {
+  paused: boolean;
+  time: number;
+  frameRate: number;
+  width: number;
+  height: number;
+};
+//#endregion
+//#region src/types/pipeline.d.ts
+type PipelineEntry = {
+  dependencies: string[];
+  name: string;
+  pass: Pass;
+};
+type PipelineRegistry = {
+  add: (entry: PipelineEntry) => void;
+  clear: () => void;
+  get: (name: string) => PipelineEntry | undefined;
+  getAll: () => PipelineEntry[];
+  has: (name: string) => boolean;
+};
+type PipelineSorter = {
+  sort: (registry: PipelineRegistry) => Pass[];
+};
+//#endregion
+//#region src/types/shader.d.ts
+type ShaderError = {
+  passName: string;
+  coords: {
+    line: number;
+    message: string;
+  };
+};
+//#endregion
+//#region src/types/uniform.d.ts
+type ShaderUniformMap = Record<string, unknown>;
+type UniformContextTarget = 'pass' | 'present';
+type UniformContext = Readonly<{
+  date: readonly [number, number, number, number];
+  frame: number;
+  frameRate: number;
+  mouse: readonly [number, number];
+  passName: string;
+  resolution: readonly [number, number];
+  target: UniformContextTarget;
+  textures: readonly (Texture | undefined)[];
+  time: number;
+  timeDelta: number;
+}>;
+type UniformProvider = Readonly<{
+  id: string;
+  resolve: (context: UniformContext) => ShaderUniformMap | undefined;
+}>;
 /**
- * Renderer class responsible for managing the WebGL context, render passes, and animation loop.
+ * Serializable uniform provider: static values resolved every frame without
+ * a function call. The only provider form that can cross into a worker.
+ * Values must be structured-cloneable (numbers, arrays, plain objects).
  */
-declare class WebGLRenderer {
+type StaticUniformProvider = Readonly<{
+  id: string;
+  values: ShaderUniformMap;
+}>;
+//#endregion
+//#region src/engine/FrameDriver.d.ts
+/**
+ * One-shot frame scheduler abstraction.
+ *
+ * The main thread drives frames with `requestAnimationFrame`, which does not
+ * exist inside workers. Decoupling the render loop from rAF lets the same
+ * renderer core run on either host with an appropriate driver.
+ */
+type FrameCallback = (time: number) => void;
+type FrameDriver = {
+  request: (callback: FrameCallback) => void;
+  cancel: () => void;
+};
+/**
+ * Main-thread driver backed by `requestAnimationFrame`. Safe to construct
+ * during SSR or in workers: scheduling becomes a no-op when rAF is missing.
+ */
+declare function rafFrameDriver(): FrameDriver;
+/**
+ * Host-agnostic driver backed by a timer. Used inside workers, where
+ * `requestAnimationFrame` is unavailable.
+ */
+declare function timerFrameDriver(intervalMs?: number): FrameDriver;
+//#endregion
+//#region src/engine/RendererCore.d.ts
+/** Canvas surface the core can render into on any host (main thread or worker). */
+type RenderSurface = HTMLCanvasElement | OffscreenCanvas;
+/** Downscaled raw pixels captured from a pass output (bottom-up row order). */
+type PassPixelData = {
+  data: Uint8Array;
+  width: number;
+  height: number;
+};
+type RendererCoreOptions = {
+  canvas: RenderSurface;
+  onError?: (details: {
+    passName: string;
+    coords: {
+      line: number;
+      message: string;
+    };
+  }) => void; /** Device pixels per CSS pixel. Defaults to 1; the DOM shell syncs it from `devicePixelRatio`. */
+  pixelRatio?: number; /** Frame scheduler. Defaults to a timer driver, which works on every host. */
+  frameDriver?: FrameDriver;
+};
+/**
+ * Host-agnostic WebGL renderer core: GL context, passes, uniforms, loop.
+ *
+ * Deliberately free of DOM APIs (`window`, `document`, listeners, rAF) so it
+ * can run inside a worker against an `OffscreenCanvas`. Hosts own the
+ * surrounding concerns and feed the core explicitly:
+ * - viewport size via {@link setDisplaySize}
+ * - pointer position via {@link setPointer} (device pixels, Y-up)
+ * - frame scheduling via the injected {@link FrameDriver}
+ */
+declare class RendererCore {
+  private static readonly presentFragmentShader;
   private gl;
-  private passes;
+  private readonly capabilities;
+  private pipeline;
   private canvas;
-  private animationRequestID;
+  private readonly frameDriver;
+  private frameScheduled;
+  private passConfigs;
   private textureMap;
   private now;
   private onError;
+  private readonly compiler;
+  private readonly presentShader;
+  private readonly screenTriangle;
+  private readonly uniformManager;
+  private thumbnailScratchFramebuffer;
+  private thumbnailScratchTexture;
+  private thumbnailScratchWidth;
+  private thumbnailScratchHeight;
+  private readonly boundRender;
   mouseX: number;
   mouseY: number;
   time: number;
@@ -91,27 +286,292 @@ declare class WebGLRenderer {
   currentFrame: number;
   currentTime: number;
   startTime: number;
-  constructor(canvas: HTMLCanvasElement, onError: (details: {
+  private pausedAt;
+  constructor(options: RendererCoreOptions);
+  private initializeWebGLContext;
+  /**
+   * Pointer position in device pixels, Y-up relative to the drawing buffer.
+   * Hosts compute this from DOM events; the core performs no layout reads.
+   */
+  setPointer(x: number, y: number): void;
+  setPixelRatio(ratio: number): void;
+  /**
+   * Explicit drawing-buffer size. Replaces the implicit
+   * `clientWidth`-based resize, which `OffscreenCanvas` cannot provide.
+   */
+  setDisplaySize(width: number, height: number): void;
+  addPass(pass: Pass): void;
+  getPass(name: string): Pass | undefined;
+  getPasses(): Pass[];
+  forEachPass(callback: (pass: Pass) => void): void;
+  getPassNames(): string[];
+  /**
+   * Capture downscaled raw pixels of a pass output. Hosts encode these for
+   * display (2D canvas on the main thread, `ImageBitmap` in a worker).
+   * Returns null when unavailable. Never throws.
+   */
+  capturePassPixels(name: string, maxSize?: number): PassPixelData | null;
+  private capturePassViaBlit;
+  private capturePassViaFullRead;
+  private ensureThumbnailScratch;
+  private disposeThumbnailScratch;
+  getMetrics(): RendererMetrics;
+  getContextState(): RendererContext;
+  clear(): void;
+  registerUniformProvider(provider: UniformProvider | StaticUniformProvider): void;
+  unregisterUniformProvider(providerId: string): boolean;
+  private updateTime;
+  render(currentTime: number): void;
+  setup(config: RendererConfig): void;
+  play(): void;
+  resume(): void;
+  pause(): void;
+  reset(): void;
+  /**
+   * Release loop scheduling and GL scratch resources. Passes keep their GL
+   * objects; hosts owning the context decide its lifetime.
+   */
+  dispose(): void;
+  private renderFrame;
+  private syncPassTextures;
+  private syncPassTexturesForPass;
+  private updateTextureMapForPass;
+  private presentTexture;
+  private getTextureBindings;
+  private cancelScheduledFrame;
+  private clearCanvas;
+  private resetPlaybackState;
+}
+//#endregion
+//#region src/engine/WebGLRenderer.d.ts
+/**
+ * Main-thread `WebGLRenderer`: {@link RendererCore} plus the DOM shell —
+ * pointer/resize listeners, `requestAnimationFrame` loop, and 2D-canvas
+ * thumbnail encoding.
+ *
+ * @deprecated Prefer `createRenderer(canvas)` — worker-first with automatic
+ * main-thread fallback and the same public surface. Direct construction
+ * always renders on the main thread; use `createRenderer(canvas,
+ * { mode: 'main' })` to pin that explicitly.
+ */
+declare class WebGLRenderer extends RendererCore {
+  private readonly displayCanvas;
+  private thumbnailCanvas;
+  private resizeObserver;
+  private readonly handleResize;
+  private readonly handleMouseMove;
+  private readonly handleTouchStart;
+  private readonly handleTouchMove;
+  constructor(canvas: HTMLCanvasElement, onError?: (details: {
     passName: string;
     coords: {
       line: number;
       message: string;
     };
   }) => void);
-  private initializeWebGLContext;
-  private initMouseEvents;
   private setMousePosition;
-  private handleTouchMove;
-  private preventDefault;
-  addPass(pass: Pass): void;
-  private resizeCanvasToDisplaySize;
-  private updateUniforms;
-  private updateTime;
-  render(currentTime: number): void;
+  private syncSizeToDisplay;
+  /**
+   * Capture a downscaled data-URL thumbnail of a pass output.
+   * Cheap by design: blits to a small scratch FBO (WebGL2) so only
+   * thumbnail-sized pixels are read back. Returns null when unavailable.
+   */
+  capturePassDataURL(name: string, maxSize?: number): string | null;
+  private thumbnailCanvasRef;
+  /** Encode bottom-up GL pixels to a data URL. Shared with worker hosts. */
+  static pixelsToDataURL(canvas: RenderSurface, pixels: Uint8Array, width: number, height: number): string | null;
+  dispose(): void;
+}
+//#endregion
+//#region src/pipeline/Pipeline.d.ts
+/**
+ * Orchestrates pass storage and dependency resolution for the render graph
+ */
+declare class Pipeline {
+  private readonly registry;
+  private readonly sorter;
+  private orderedPasses;
+  private dirty;
+  constructor(registry?: PipelineRegistry, sorter?: PipelineSorter);
+  add(name: string, pass: Pass, dependencies?: string[]): void;
+  clear(): void;
+  resize(width: number, height: number): void;
+  forEach(callback: (pass: Pass) => void): void;
+  get(name: string): Pass | undefined;
+  toArray(): Pass[];
+  private getOrderedPasses;
+}
+//#endregion
+//#region src/worker/protocol.d.ts
+type ErrorDetails = {
+  passName: string;
+  coords: {
+    line: number;
+    message: string;
+  };
+};
+/** Worker -> main thread. */
+type WorkerEvent = {
+  type: 'ready';
+  version: number;
+} | {
+  type: 'fatal';
+  reason: string;
+} | {
+  type: 'error';
+  details: ErrorDetails;
+} | {
+  type: 'context';
+  capabilities: GLContextCapabilities;
+  webglVersion: GLContextVersion;
+} | {
+  type: 'metrics';
+  metrics: RendererMetrics;
+} | {
+  type: 'passes';
+  names: string[];
+} | {
+  type: 'capture-result';
+  id: number;
+  name: string;
+  maxSize: number;
+  data: ArrayBuffer | null;
+  width: number;
+  height: number;
+};
+//#endregion
+//#region src/worker/OffscreenWebGLRenderer.d.ts
+/**
+ * Main-thread proxy for a worker-hosted {@link RendererCore}. Same public
+ * surface as {@link WebGLRenderer}: fire-and-forget commands cross the
+ * boundary, while synchronous reads (`getMetrics`, `getPassNames`,
+ * `capturePassDataURL`) are served from caches the worker pushes.
+ * Construct via {@link createRenderer}, never directly.
+ */
+declare class OffscreenWebGLRenderer {
+  readonly isOffscreenRenderer: true;
+  mouseX: number;
+  mouseY: number;
+  time: number;
+  timeDelta: number;
+  realToCSSPixels: number;
+  paused: boolean;
+  playbackTime: number;
+  lastTime: number;
+  frameRate: number;
+  currentFrame: number;
+  currentTime: number;
+  startTime: number;
+  private readonly worker;
+  private readonly displayCanvas;
+  private readonly onError;
+  private detachHost;
+  private readonly encodeCanvas;
+  private passNames;
+  private metrics;
+  private contextState;
+  private thumbnails;
+  private captureId;
+  private disposed;
+  constructor(canvas: HTMLCanvasElement, worker: Worker, options?: {
+    onError?: (details: ErrorDetails) => void;
+    detachHost?: (() => void) | null;
+  });
+  /**
+   * Take over the worker message stream. Called by the factory once the
+   * init handshake succeeds; replays the buffered first event.
+   */
+  connect(firstEvent?: WorkerEvent): void;
+  /** Late-bind host teardown (the host needs the proxy to exist first). */
+  setDetachHost(detach: (() => void) | null): void;
+  /** The visible canvas (transferred control; the browser composites it). */
+  get canvas(): HTMLCanvasElement;
+  private post;
+  private handleEvent;
+  private applyMetrics;
+  private applyCapture;
   setup(config: RendererConfig): void;
   play(): void;
+  resume(): void;
   pause(): void;
   reset(): void;
+  clear(): void;
+  setPointer(x: number, y: number): void;
+  setPixelRatio(ratio: number): void;
+  setDisplaySize(width: number, height: number): void;
+  registerUniformProvider(provider: UniformProvider | StaticUniformProvider): void;
+  unregisterUniformProvider(providerId: string): boolean;
+  getPassNames(): string[];
+  getMetrics(): RendererMetrics;
+  getContextState(): RendererContext;
+  /**
+   * Last encoded thumbnail for a pass, or null until the worker round-trip
+   * completes. Call {@link requestPassCapture} first (e.g. on a poll
+   * interval); the following read observes the fresh frame.
+   */
+  capturePassDataURL(name: string, maxSize?: number): string | null;
+  /** Ask the worker to capture and push a fresh thumbnail for `name`. */
+  requestPassCapture(name: string, maxSize?: number): void;
+  addPass(_pass: Pass): void;
+  getPass(_name: string): Pass | undefined;
+  getPasses(): Pass[];
+  forEachPass(_callback: (pass: Pass) => void): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/worker/createRenderer.d.ts
+/** Either renderer implementation. Both share the same public surface. */
+type Renderer = WebGLRenderer | OffscreenWebGLRenderer;
+/** Worker-first (`auto`), worker-only, or main-thread-only. */
+type RendererMode = 'auto' | 'worker' | 'main';
+type RendererFallbackReason = 'ssr-no-dom' | 'no-worker' | 'no-offscreen-canvas' | 'no-webgl' | 'worker-spawn-failed' | 'worker-handshake-timeout' | 'worker-version-mismatch' | 'worker-gl-unavailable' | 'worker-transferred-fatal' | 'canvas-already-bound';
+type CreateRendererOptions = {
+  /** Default `'auto'`: worker when supported, silent main-thread fallback. */mode?: RendererMode;
+  /**
+   * Pre-constructed worker running the engine worker entry. Preferred when
+   * the host bundler owns worker bundling (e.g. Vite `?worker` imports),
+   * which guarantees a correct URL in both dev and prod builds.
+   * Takes precedence over `workerUrl`.
+   */
+  worker?: Worker;
+  /**
+   * Worker script URL. Defaults to the sibling worker entry next to this
+   * module (`worker-entry.mjs` in dist, `worker-entry.ts` from source).
+   */
+  workerUrl?: string; /** Notified (auto mode) whenever the worker path is abandoned. */
+  onFallback?: (reason: RendererFallbackReason) => void;
+  onError?: (details: ErrorDetails) => void; /** Handshake deadline before falling back. Default 2000ms. */
+  handshakeTimeoutMs?: number; /** Skip host wiring (resize/pointer) when the caller owns it. Default true. */
+  attachHost?: boolean;
+};
+declare class WorkerUnsupportedError extends Error {
+  readonly reason: RendererFallbackReason;
+  constructor(reason: RendererFallbackReason, options?: {
+    cause?: unknown;
+  });
 }
+/**
+ * Whether this canvas was already transferred by {@link createRenderer}.
+ * A stamped canvas can never render on the main thread again — mount a
+ * fresh element and dispose the previous renderer first.
+ */
+declare function isCanvasAlreadyTransferred(canvas: HTMLCanvasElement): boolean;
+/**
+ * Create a renderer, worker-first by default.
+ *
+ * `auto` probes `Worker` -> `transferControlToOffscreen` -> WebGL ->
+ * handshake, falling back to the main-thread `WebGLRenderer` at the first
+ * failure (`onFallback` reports why). `worker` throws
+ * {@link WorkerUnsupportedError} instead of falling back; `main` always
+ * constructs {@link WebGLRenderer} directly.
+ *
+ * Note: transferring a canvas is irreversible. A GPU that works on the main
+ * thread is assumed to work in the worker; the pre-flight probe plus versioned
+ * handshake make a post-transfer failure unlikely. If the worker still dies
+ * after transfer, the canvas cannot be recovered on the main thread, so
+ * creation throws {@link WorkerUnsupportedError} (`worker-transferred-fatal`)
+ * even in `auto` mode.
+ */
+declare function createRenderer(canvas: HTMLCanvasElement, options?: CreateRendererOptions): Promise<Renderer>;
 //#endregion
-export { Pass, type PassConfig, type RendererConfig, Shader, WebGLRenderer };
+export { type CreateRendererOptions, FBO, type FrameCallback, type FrameDriver, type GL, type GLContextVersion, OffscreenWebGLRenderer, Pass, type PassConfig, type PassPixelData, Pipeline, type RenderSurface, type Renderer, type RendererConfig, type RendererContext, RendererCore, type RendererCoreOptions, type RendererFallbackReason, type RendererMetrics, type RendererMode, Shader, type ShaderUniformMap, type StaticUniformProvider, TEXTURE_CHANNEL_COUNT, Texture, type TextureFilterMode, type TextureOptions, type TextureWrapMode, type UniformContext, type UniformContextTarget, type UniformProvider, WebGLRenderer, WorkerUnsupportedError, createRenderer, isCanvasAlreadyTransferred, rafFrameDriver, timerFrameDriver };