@frapx/core 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,11 +1,45 @@
 # Changelog
 
+## 0.4.0 - 2026-10-13
+
+### Added
+
+- Shared program state for runtimes built on the host, moved here from `@frapx/fx-canvas` so `@frapx/fx-passes` can reuse it:
+  - Uniform helpers `normalizeUniform`, `applyUniform`, `applyProgramUniform`, `applyUniforms`, `collectUniformLocations` and `createUniformCache`, with the `NormalizedUniform` type and the uniform input types (`UniformInput`, `UniformInputMap`, `UniformRuntimeValue`, `ExplicitUniformInput`, `UniformType`, `UniformScalar`, `UniformVec2`–`UniformVec4`).
+  - `createTextureSet(inputs)`: named image textures with texture-unit allocation (`reserveUnit` also covers runtime-owned samplers), superseded-load handling, binding and disposal.
+  - `createFullscreenProgram(gl, fragment, vertex?)`: compiles a fragment shader with the matching fullscreen-quad vertex shader and exposes its uniform locations, `use()`, `draw()` and `dispose()`.
+- `rgba32f` render targets (`createRenderTarget` / `createPingPong`), with the same WebGL2 + `EXT_color_buffer_float` requirement as `rgba16f`. They sample with nearest filtering unless `OES_texture_float_linear` is available. `captureFrame({ format: "rgba16f" })` also reads an `rgba32f` capture source.
+- `onCaptureDraw(state, signal)` host option: draws the frame `captureFrame()` reads over several tasks (for example sample accumulation that waits for the GPU between draws). The host holds its render lock until it settles, so other frames do not interleave, and reads the result in the settling task. Resizes requested meanwhile apply after the frame is read, and a context lost (even if restored) meanwhile rejects the capture.
+- `signal` capture option: an aborted signal rejects `captureFrame()` before drawing and is passed to `onCaptureDraw`.
+- `waitForGpu(gl)`: resolves once the GPU has finished the submitted work by polling a fence between tasks, so long renders can yield and avoid the GPU watchdog. Resolves immediately on WebGL1.
+
+## 0.3.0 - 2026-10-10
+
+### Added
+
+- `clock: "manual"` option on `createRuntimeHost` and `setClock()` / `setTime()` on the instance. A manual clock never schedules frames: time changes only through `setTime()` (with `delta` the difference from the previous call) and frames are drawn only by `render()`, which ignores offscreen/hidden gating. The frame state reports a neutral pointer and `reducedMotion: false`, so identical time and uniforms produce identical pixels.
+- `resolution` option and `setResolution([w, h] | null)` to fix the internal render size independently of the target. The canvas is letterboxed with `object-fit: contain`, the viewport size still tracks the target, and `pixelRatio` is derived from the fit (`dpr` / `maxDpr` are ignored). Sizes beyond the GPU's viewport/renderbuffer limits fail with `UnsupportedError`.
+- Creating a host with neither `target` nor `canvas` now works when `resolution` is given: a detached canvas is created and no layout observers are attached.
+- `ClockMode` and `Resolution` types, and `SetupCanvasOptions.detached` / `DomSetup.detached`.
+- `createRenderTarget(gl, width, height, options)` and `createPingPong(...)`: texture-backed framebuffers with an explicit `format` (`"rgba8"` or `"rgba16f"`). `rgba16f` needs WebGL2 with `EXT_color_buffer_float`; otherwise it warns and allocates `rgba8`, or throws `UnsupportedError` with `formatFallback: false`. `supportsRenderTargetFormat` / `resolveRenderTargetFormat` expose the detection, and `isWebGL2Context` is now exported.
+- `captureFrame({ format })` on the host: draws a frame (bypassing pause gates) and reads it back in the same task as a PNG `Blob`, `Uint8Array` (`rgba8`) or `Float32Array` (`rgba16f`, from the new `captureSource` option), with rows top first.
+- Added the MIT `LICENSE` file to the published package.
+
+### Changed
+
+- An `UnsupportedError` thrown from `onInit` now sets status `"unsupported"` instead of `"error"`.
+- A throwing `onDraw` no longer leaves the host stuck in its in-render state.
+
 ## 0.2.0 - 2026-07-12
 
 ### Changed
 
 - **Breaking: package renamed from `@frapx/runtime` to `@frapx/core`.** No API changes — only the npm package name and import path change. `@frapx/runtime` is deprecated on npm and will not receive further updates.
 
+### Added
+
+- _Correction (noted after release):_ this version also shipped the `onResize` host option (called only when the measured size actually changes) and the `createBlitter(gl)` fullscreen-quad blit utility, which the entry above omitted.
+
 ## 0.1.0 - 2026-06-27
 
 Initial release. Shared WebGL runtime extracted from `@frapx/fx-canvas`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kramhash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,4 +8,4 @@ If you are building a WebGL experience, you most likely want [`@frapx/fx-canvas`
 
 ## License
 
-MIT
+MIT © 2026 kramhash. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -4,6 +4,14 @@ export { glsl, glslUtils } from './glsl.js';
 type GLContext = WebGLRenderingContext | WebGL2RenderingContext;
 type ShaderLayer = "background" | "overlay";
 type RenderMode = "always" | "demand";
+/**
+ * `"realtime"` advances time from requestAnimationFrame. `"manual"` never
+ * renders on its own: time only changes through `setTime()` and frames are
+ * drawn only by explicit `render()` calls, so output is deterministic.
+ */
+type ClockMode = "realtime" | "manual";
+/** Fixed internal render size in pixels: `[width, height]`. */
+type Resolution = readonly [number, number];
 type DprOption = "auto" | number | (() => number);
 type ShaderStatus = "idle" | "loading" | "ready" | "running" | "paused" | "error" | "unsupported" | "context-lost" | "destroyed";
 type TextureSource = string | HTMLImageElement | HTMLCanvasElement;
@@ -15,6 +23,78 @@ type TextureOptions = {
 };
 type TextureInput = TextureSource | TextureOptions;
 type TextureMap = Record<string, TextureInput>;
+type UniformScalar = number;
+type UniformVec2 = [number, number] | readonly [number, number];
+type UniformVec3 = [number, number, number] | readonly [number, number, number];
+type UniformVec4 = [number, number, number, number] | readonly [number, number, number, number];
+type UniformType = "float" | "vec2" | "vec3" | "vec4" | "mat3" | "mat4";
+type ExplicitUniformInput = {
+    type: UniformType;
+    value: number[] | Float32Array;
+};
+type UniformInput = UniformScalar | UniformVec2 | UniformVec3 | UniformVec4 | Float32Array | ExplicitUniformInput;
+type UniformInputMap = Record<string, UniformInput>;
+type UniformRuntimeValue<T> = T extends ExplicitUniformInput ? ExplicitUniformInput : T extends Float32Array ? Float32Array : T extends readonly [number, number] ? UniformVec2 : T extends readonly [number, number, number] ? UniformVec3 : T extends readonly [number, number, number, number] ? UniformVec4 : T extends number ? number : UniformInput;
+/**
+ * Storage format of a render target. `rgba16f` (half float) and `rgba32f`
+ * (float) need WebGL2 with `EXT_color_buffer_float`. `rgba32f` is sampled with
+ * nearest filtering unless `OES_texture_float_linear` is available.
+ */
+type RenderTargetFormat = "rgba8" | "rgba16f" | "rgba32f";
+type RenderTargetOptions = {
+    /** Defaults to `"rgba8"`. */
+    format?: RenderTargetFormat;
+    /**
+     * When the requested format is unsupported, `true` (default) warns and
+     * allocates `rgba8` instead; `false` throws `UnsupportedError`.
+     */
+    formatFallback?: boolean;
+    filter?: "nearest" | "linear";
+    wrap?: "clamp" | "repeat" | "mirror";
+    /** Color the storage is cleared to on creation, resize and `clear()`. */
+    clearColor?: readonly [number, number, number, number];
+};
+type RenderTarget = {
+    readonly texture: WebGLTexture;
+    readonly framebuffer: WebGLFramebuffer;
+    readonly width: number;
+    readonly height: number;
+    /** The format actually allocated, after any fallback. */
+    readonly format: RenderTargetFormat;
+    /** Reallocates (and clears) the storage when the size changes. */
+    resize(width: number, height: number): void;
+    /** Clears the storage to `clearColor`. Leaves the default framebuffer bound. */
+    clear(): void;
+    dispose(): void;
+};
+type PingPong = {
+    /** The target holding the last completed frame. */
+    readonly read: RenderTarget;
+    /** The target to draw the next frame into. */
+    readonly write: RenderTarget;
+    /** The format actually allocated, after any fallback. */
+    readonly format: RenderTargetFormat;
+    /** Exchanges `read` and `write`; call after drawing into `write`. */
+    swap(): void;
+    resize(width: number, height: number): void;
+    clear(): void;
+    dispose(): void;
+};
+/**
+ * `"png"` resolves to a `Blob`, `"rgba8"` to a `Uint8Array` and `"rgba16f"` to
+ * a `Float32Array`. Raw formats are RGBA, top row first.
+ */
+type CaptureFormat = "png" | "rgba8" | "rgba16f";
+type CaptureOptions<F extends CaptureFormat = CaptureFormat> = {
+    /** Defaults to `"png"`. */
+    format?: F;
+    /**
+     * Rejects the capture with the signal's reason when aborted before drawing,
+     * or between the steps of a capture that draws over several tasks.
+     */
+    signal?: AbortSignal;
+};
+type CaptureResult<F extends CaptureFormat> = F extends "rgba16f" ? Float32Array : F extends "rgba8" ? Uint8Array : Blob;
 type HostPointer = {
     x: number;
     y: number;
@@ -42,6 +122,11 @@ type SetupCanvasOptions = {
     layer?: ShaderLayer;
     canvasClass?: string;
     canvasStyle?: Partial<CSSStyleDeclaration>;
+    /**
+     * When neither `target` nor `canvas` is given, create a canvas that is not
+     * attached to the document instead of failing.
+     */
+    detached?: boolean;
 };
 type RuntimeHostOptions = {
     target?: string | Element;
@@ -57,12 +142,32 @@ type RuntimeHostOptions = {
     pauseWhenHidden?: boolean;
     respectReducedMotion?: boolean;
     renderMode?: RenderMode;
+    /** Defaults to `"realtime"`. See {@link ClockMode}. */
+    clock?: ClockMode;
+    /**
+     * Fixes the internal render size instead of following the target's size.
+     * Required when neither `target` nor `canvas` is given.
+     */
+    resolution?: Resolution;
     debug?: boolean;
     createContext: (canvas: HTMLCanvasElement) => GLContext | null;
     onInit: (gl: GLContext, width: number, height: number) => Promise<void> | void;
     onDraw: (state: HostFrameState) => void;
     /** Called whenever the observed size actually changes (not every frame). */
     onResize?: (state: HostFrameState) => void;
+    /**
+     * Returns the render target that holds the last drawn frame at full
+     * precision, if any. `captureFrame({ format: "rgba16f" })` reads from it.
+     */
+    captureSource?: () => RenderTarget | null;
+    /**
+     * Draws the frame `captureFrame()` reads, in place of `onDraw`, when drawing
+     * it takes more than one task (such as accumulating samples while waiting
+     * for the GPU). The host holds its render lock until the promise settles and
+     * reads the result in the task that settled it, so the final draw into the
+     * canvas must happen in that task. Receives the capture's abort signal.
+     */
+    onCaptureDraw?: (state: HostFrameState, signal: AbortSignal | undefined) => Promise<void>;
     onContextLost?: () => void;
     onContextRestored?: (gl: GLContext, width: number, height: number) => Promise<void> | void;
     onReady?: () => void;
@@ -74,15 +179,43 @@ type RuntimeHostInstance = {
     readonly status: ShaderStatus;
     readonly supported: boolean;
     readonly ready: Promise<void>;
+    readonly clock: ClockMode;
     start(): void;
     stop(): void;
     render(): void;
     resize(): void;
     destroy(): void;
+    /**
+     * Sets the clock to `seconds`. In manual mode `u_delta` becomes the
+     * difference from the previous `setTime()` value (0 the first time). In
+     * realtime mode this seeks the running clock. Does not render by itself.
+     */
+    setTime(seconds: number): void;
+    /** Switches between realtime and manual clocks after creation. */
+    setClock(clock: ClockMode): void;
+    /**
+     * Fixes the internal render size, or follows the target's size again when
+     * `null`. Throws `UnsupportedError` when the size exceeds the GPU limits.
+     */
+    setResolution(resolution: Resolution | null): void;
+    /**
+     * Draws a frame and reads it back in the same task, so it does not depend on
+     * `preserveDrawingBuffer`. Draws even while paused or hidden; waits for
+     * `ready` first. `"rgba16f"` needs a float `captureSource`.
+     */
+    captureFrame<F extends CaptureFormat = "png">(options?: CaptureOptions<F>): Promise<CaptureResult<F>>;
 };
 
 declare const createRuntimeHost: (options: RuntimeHostOptions) => RuntimeHostInstance;
 
+/**
+ * Resolves once the GPU has finished every command submitted so far, polling
+ * a fence between tasks. Waiting between heavy draws keeps each submission
+ * short, so a long render never trips the browser's GPU watchdog and loses
+ * the context. Resolves immediately on WebGL1.
+ */
+declare const waitForGpu: (gl: GLContext) => Promise<void>;
+
 declare class ShaderError extends Error {
     constructor(message: string);
 }
@@ -105,16 +238,19 @@ type DomSetup = {
     canvas: HTMLCanvasElement;
     createdCanvas: boolean;
     restoredPosition: string | null;
+    /** True when the canvas was created without being attached to the document. */
+    detached?: boolean;
 };
-declare const resolveElement: (target: string | Element | undefined) => Element | null;
-declare const setupCanvas: (options: SetupCanvasOptions) => DomSetup | null;
-declare const resolveDpr: (dpr: DprOption | undefined, maxDpr: number | undefined) => number;
-declare const resizeCanvasToTarget: (canvas: HTMLCanvasElement, target: Element, dpr: number) => {
+type CanvasSize = {
     width: number;
     height: number;
     viewportWidth: number;
     viewportHeight: number;
 };
+declare const resolveElement: (target: string | Element | undefined) => Element | null;
+declare const setupCanvas: (options: SetupCanvasOptions) => DomSetup | null;
+declare const resolveDpr: (dpr: DprOption | undefined, maxDpr: number | undefined) => number;
+declare const resizeCanvasToTarget: (canvas: HTMLCanvasElement, target: Element, dpr: number) => CanvasSize;
 
 type LoadedTexture = {
     name: string;
@@ -126,9 +262,82 @@ type LoadedTexture = {
 };
 declare const loadTexture: (gl: GLContext, name: string, input: TextureInput, unit: number) => Promise<LoadedTexture>;
 
+type TextureSet = {
+    /** The textures loaded so far, by name. */
+    readonly textures: ReadonlyMap<string, LoadedTexture>;
+    /** Whether `name` was given as an input, loaded or not. */
+    hasInput(name: string): boolean;
+    /**
+     * Returns the texture unit for `name`, taking the lowest free unit on first
+     * use. Runtimes reserve units for their own samplers (feedback, pass inputs)
+     * here too, so they never collide with image textures.
+     */
+    reserveUnit(gl: GLContext, name: string): number;
+    /**
+     * Loads every input, then replaces the previously loaded textures. Used for
+     * the initial load and after a context restore.
+     */
+    loadAll(gl: GLContext, isCancelled: () => boolean): Promise<void>;
+    /**
+     * Loads `input` as `name`. Resolves to the loaded texture, or `null` when a
+     * later `set()` for the same name or `isCancelled()` superseded it (its
+     * texture is deleted). On failure the unit is released if `name` is unused,
+     * and the error is rethrown.
+     */
+    set(gl: GLContext, name: string, input: TextureInput, isCancelled: () => boolean): Promise<LoadedTexture | null>;
+    /**
+     * Binds every loaded texture to its unit and points its sampler uniform at
+     * it. Calls `onMissing` with the uniform name when the program lacks it.
+     */
+    bind(gl: GLContext, locations: ReadonlyMap<string, WebGLUniformLocation>, onMissing?: (uniformName: string) => void): void;
+    /** Deletes every loaded texture. */
+    dispose(gl: GLContext): void;
+};
+/**
+ * Tracks named image textures and the texture units they occupy, for a
+ * runtime that binds them to one or more programs.
+ */
+declare const createTextureSet: (inputs?: TextureMap) => TextureSet;
+
+type NormalizedUniform = {
+    type: UniformType;
+    value: number[] | Float32Array;
+};
+declare const normalizeUniform: (input: UniformInput) => NormalizedUniform;
+declare const applyUniform: (gl: GLContext, location: WebGLUniformLocation, uniform: NormalizedUniform) => void;
+declare const applyProgramUniform: (gl: GLContext, program: WebGLProgram, location: WebGLUniformLocation, uniform: NormalizedUniform) => void;
+/**
+ * Uploads every cached uniform to the bound program. Calls `onMissing` with
+ * the name of each uniform the program lacks or optimized out.
+ */
+declare const applyUniforms: (gl: GLContext, locations: ReadonlyMap<string, WebGLUniformLocation>, cache: ReadonlyMap<string, NormalizedUniform>, onMissing?: (name: string) => void) => void;
+declare const collectUniformLocations: (gl: GLContext, program: WebGLProgram) => Map<string, WebGLUniformLocation>;
+declare const createUniformCache: (uniforms: Record<string, UniformInput> | undefined) => Map<string, NormalizedUniform>;
+
+type FullscreenProgram = {
+    readonly program: WebGLProgram;
+    /** Active uniform locations by name, array uniforms without `[0]`. */
+    readonly locations: ReadonlyMap<string, WebGLUniformLocation>;
+    /**
+     * Binds the program, its quad buffer and `a_position`, so a draw is correct
+     * whatever GL state user hooks left behind.
+     */
+    use(): void;
+    /** Draws the fullscreen quad with the current GL state. */
+    draw(): void;
+    dispose(): void;
+};
+/**
+ * Compiles `fragment` with a fullscreen-quad vertex shader (the GLSL ES 3.00
+ * one when `fragment` starts with `#version 300 es`, unless `vertex` is
+ * given) and leaves it bound.
+ */
+declare const createFullscreenProgram: (gl: GLContext, fragment: string, vertex?: string) => FullscreenProgram;
+
 declare const defaultVertexShader = "\nattribute vec2 a_position;\nvarying vec2 v_uv;\n\nvoid main() {\n  v_uv = a_position * 0.5 + 0.5;\n  gl_Position = vec4(a_position, 0.0, 1.0);\n}\n";
 declare const defaultVertexShader300 = "#version 300 es\nin vec2 a_position;\nout vec2 v_uv;\n\nvoid main() {\n  v_uv = a_position * 0.5 + 0.5;\n  gl_Position = vec4(a_position, 0.0, 1.0);\n}\n";
 declare const isGLSL300: (src: string) => boolean;
+declare const isWebGL2Context: (gl: GLContext) => gl is WebGL2RenderingContext;
 declare const createProgram: (gl: GLContext, vertexSource: string, fragmentSource: string) => WebGLProgram;
 declare const createFullscreenBuffer: (gl: GLContext, program: WebGLProgram) => WebGLBuffer;
 
@@ -150,4 +359,28 @@ type Blitter = {
  */
 declare const createBlitter: (gl: GLContext) => Blitter;
 
-export { type Blitter, DestroyedError, type DomSetup, type DprOption, type GLContext, type HostFrameState, type HostPointer, type LoadedTexture, type RenderMode, type RuntimeHostInstance, type RuntimeHostOptions, type SetupCanvasOptions, ShaderCompileError, ShaderError, type ShaderLayer, type ShaderStatus, TargetNotFoundError, type TextureInput, TextureLoadError, type TextureMap, type TextureOptions, type TextureSource, UnsupportedError, createBlitter, createFullscreenBuffer, createProgram, createRuntimeHost, defaultVertexShader, defaultVertexShader300, fromUniformName, isGLSL300, loadTexture, resizeCanvasToTarget, resolveDpr, resolveElement, setupCanvas, toUniformName };
+/**
+ * Whether `format` can be allocated as a color attachment on `gl`. `rgba8` is
+ * always available; `rgba16f` and `rgba32f` need WebGL2 and
+ * `EXT_color_buffer_float`.
+ * Enables the extension as a side effect when present.
+ */
+declare const supportsRenderTargetFormat: (gl: GLContext, format: RenderTargetFormat) => boolean;
+/**
+ * Resolves the format a render target will actually use. When `format` is not
+ * supported this warns and returns `rgba8`, or throws `UnsupportedError` when
+ * `formatFallback` is `false`.
+ */
+declare const resolveRenderTargetFormat: (gl: GLContext, format?: RenderTargetFormat, formatFallback?: boolean) => RenderTargetFormat;
+/**
+ * Creates a texture-backed framebuffer to render into and sample from. The
+ * storage is cleared to `clearColor` on creation and on every resize.
+ */
+declare const createRenderTarget: (gl: GLContext, width: number, height: number, options?: RenderTargetOptions) => RenderTarget;
+/**
+ * Creates two render targets of the same size and format for feedback-style
+ * rendering: draw into `write` while sampling `read`, then `swap()`.
+ */
+declare const createPingPong: (gl: GLContext, width: number, height: number, options?: RenderTargetOptions) => PingPong;
+
+export { type Blitter, type CaptureFormat, type CaptureOptions, type CaptureResult, type ClockMode, DestroyedError, type DomSetup, type DprOption, type ExplicitUniformInput, type FullscreenProgram, type GLContext, type HostFrameState, type HostPointer, type LoadedTexture, type NormalizedUniform, type PingPong, type RenderMode, type RenderTarget, type RenderTargetFormat, type RenderTargetOptions, type Resolution, type RuntimeHostInstance, type RuntimeHostOptions, type SetupCanvasOptions, ShaderCompileError, ShaderError, type ShaderLayer, type ShaderStatus, TargetNotFoundError, type TextureInput, TextureLoadError, type TextureMap, type TextureOptions, type TextureSet, type TextureSource, type UniformInput, type UniformInputMap, type UniformRuntimeValue, type UniformScalar, type UniformType, type UniformVec2, type UniformVec3, type UniformVec4, UnsupportedError, applyProgramUniform, applyUniform, applyUniforms, collectUniformLocations, createBlitter, createFullscreenBuffer, createFullscreenProgram, createPingPong, createProgram, createRenderTarget, createRuntimeHost, createTextureSet, createUniformCache, defaultVertexShader, defaultVertexShader300, fromUniformName, isGLSL300, isWebGL2Context, loadTexture, normalizeUniform, resizeCanvasToTarget, resolveDpr, resolveElement, resolveRenderTargetFormat, setupCanvas, supportsRenderTargetFormat, toUniformName, waitForGpu };