@frapx/core 0.2.0 → 0.4.0

package/dist/index.js

@@ -25,6 +25,134 @@ var TextureLoadError = class extends ShaderError {
 var DestroyedError = class extends ShaderError {
 };
 
+// src/internal/webgl.ts
+var defaultVertexShader = `
+attribute vec2 a_position;
+varying vec2 v_uv;
+
+void main() {
+  v_uv = a_position * 0.5 + 0.5;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}
+`;
+var defaultVertexShader300 = `#version 300 es
+in vec2 a_position;
+out vec2 v_uv;
+
+void main() {
+  v_uv = a_position * 0.5 + 0.5;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}
+`;
+var isGLSL300 = (src) => /^\s*#version\s+300\s+es\b/.test(src);
+var isWebGL2Context = (gl) => typeof gl.createVertexArray === "function";
+var createProgram = (gl, vertexSource, fragmentSource) => {
+  const vertex = compileShader(gl, gl.VERTEX_SHADER, vertexSource);
+  const fragment = compileShader(gl, gl.FRAGMENT_SHADER, fragmentSource);
+  const program = gl.createProgram();
+  if (!program) {
+    throw new ShaderCompileError("Failed to create WebGL program.");
+  }
+  gl.attachShader(program, vertex);
+  gl.attachShader(program, fragment);
+  gl.linkProgram(program);
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    const log = gl.getProgramInfoLog(program) ?? "Unknown program link error.";
+    gl.deleteProgram(program);
+    gl.deleteShader(vertex);
+    gl.deleteShader(fragment);
+    throw new ShaderCompileError(log);
+  }
+  gl.deleteShader(vertex);
+  gl.deleteShader(fragment);
+  return program;
+};
+var createFullscreenBuffer = (gl, program) => {
+  const buffer = gl.createBuffer();
+  if (!buffer) {
+    throw new ShaderCompileError("Failed to create fullscreen buffer.");
+  }
+  const location = gl.getAttribLocation(program, "a_position");
+  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+  gl.bufferData(
+    gl.ARRAY_BUFFER,
+    new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]),
+    gl.STATIC_DRAW
+  );
+  if (location >= 0) {
+    gl.enableVertexAttribArray(location);
+    gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0);
+  }
+  return buffer;
+};
+var compileShader = (gl, type, source) => {
+  const shader = gl.createShader(type);
+  if (!shader) {
+    throw new ShaderCompileError("Failed to create WebGL shader.");
+  }
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    const log = gl.getShaderInfoLog(shader) ?? "Unknown shader compile error.";
+    gl.deleteShader(shader);
+    throw new ShaderCompileError(log);
+  }
+  return shader;
+};
+
+// src/internal/capture.ts
+var waitForGpu = (gl) => {
+  if (!isWebGL2Context(gl)) return Promise.resolve();
+  const sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
+  if (!sync) return Promise.resolve();
+  gl.flush();
+  return new Promise((resolve) => {
+    const poll = () => {
+      const status = gl.clientWaitSync(sync, 0, 0);
+      if (status === gl.TIMEOUT_EXPIRED) {
+        setTimeout(poll, 4);
+        return;
+      }
+      gl.deleteSync(sync);
+      resolve();
+    };
+    poll();
+  });
+};
+var readPixels = (gl, framebuffer, width, height, format) => {
+  const length = width * height * 4;
+  const data = format === "rgba16f" ? new Float32Array(length) : new Uint8Array(length);
+  gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+  gl.readPixels(
+    0,
+    0,
+    width,
+    height,
+    gl.RGBA,
+    format === "rgba16f" ? gl.FLOAT : gl.UNSIGNED_BYTE,
+    data
+  );
+  gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  flipRows(data, width * 4, height);
+  return data;
+};
+var canvasToPng = (canvas) => new Promise((resolve, reject) => {
+  canvas.toBlob((blob) => {
+    if (blob) resolve(blob);
+    else reject(new Error("Failed to encode the canvas as PNG."));
+  }, "image/png");
+});
+var flipRows = (data, rowLength, rows) => {
+  const temp = data.slice(0, rowLength);
+  for (let top = 0, bottom = rows - 1; top < bottom; top++, bottom--) {
+    const topStart = top * rowLength;
+    const bottomStart = bottom * rowLength;
+    temp.set(data.subarray(topStart, topStart + rowLength));
+    data.copyWithin(topStart, bottomStart, bottomStart + rowLength);
+    data.set(temp, bottomStart);
+  }
+};
+
 // src/internal/dom.ts
 var resolveElement = (target) => {
   if (!target) return null;
@@ -35,7 +163,17 @@ var setupCanvas = (options) => {
   const target = resolveElement(options.target);
   const canvas = options.canvas ?? document.createElement("canvas");
   const measurementTarget = target ?? options.canvas;
-  if (!measurementTarget) return null;
+  if (!measurementTarget) {
+    if (!options.detached) return null;
+    canvas.dataset.frapxCanvas = "";
+    return {
+      target: canvas,
+      canvas,
+      createdCanvas: true,
+      restoredPosition: null,
+      detached: true
+    };
+  }
   const createdCanvas = !options.canvas;
   const restoredPosition = target && getComputedStyle(target).position === "static" ? target.style.position : null;
   if (target && restoredPosition !== null) {
@@ -76,6 +214,19 @@ var resizeCanvasToTarget = (canvas, target, dpr) => {
   if (canvas.height !== height) canvas.height = height;
   return { width, height, viewportWidth, viewportHeight };
 };
+var resizeCanvasToResolution = (canvas, target, resolution) => {
+  const [width, height] = resolution;
+  let viewportWidth = width;
+  let viewportHeight = height;
+  if (target) {
+    const rect = target.getBoundingClientRect();
+    viewportWidth = Math.max(1, rect.width || canvas.clientWidth || 1);
+    viewportHeight = Math.max(1, rect.height || canvas.clientHeight || 1);
+  }
+  if (canvas.width !== width) canvas.width = width;
+  if (canvas.height !== height) canvas.height = height;
+  return { width, height, viewportWidth, viewportHeight };
+};
 var applyCanvasStyle = (canvas, options, shouldPosition) => {
   canvas.dataset.frapxCanvas = "";
   if (!shouldPosition) return;
@@ -93,6 +244,7 @@ var applyCanvasStyle = (canvas, options, shouldPosition) => {
 
 // src/host.ts
 var MAX_DELTA_SECONDS = 0.1;
+var IDLE_POINTER = { x: 0, y: 0, uvX: 0, uvY: 0, active: 0 };
 var createRuntimeHost = (options) => {
   return new RuntimeHost(options);
 };
@@ -107,6 +259,8 @@ var RuntimeHost = class {
     this.rafId = 0;
     this.running = false;
     this.inRender = false;
+    this.captureDrawing = false;
+    this.resizePending = false;
     this.destroyed = false;
     this.gates = /* @__PURE__ */ new Set();
     this.reducedMotionActive = false;
@@ -122,7 +276,15 @@ var RuntimeHost = class {
     this.removeListeners = [];
     this.currentStatus = "idle";
     this.contextRestoredShouldRun = false;
+    this.manualDelta = 0;
+    this.lastManualTime = null;
+    this.objectFitRestore = null;
+    // Letterbox offset (CSS px) of the contained canvas content inside the target.
+    this.contentOffsetX = 0;
+    this.contentOffsetY = 0;
     this.options = options;
+    this.clockMode = options.clock ?? "realtime";
+    this.fixedResolution = options.resolution ? normalizeResolution(options.resolution) : null;
     this.ready = new Promise((resolve, reject) => {
       this.readyResolve = resolve;
       this.readyReject = reject;
@@ -143,6 +305,9 @@ var RuntimeHost = class {
   get supported() {
     return !["unsupported", "destroyed"].includes(this.currentStatus);
   }
+  get clock() {
+    return this.clockMode;
+  }
   start() {
     if (this.destroyed || this.currentStatus === "unsupported") return;
     this.running = true;
@@ -156,12 +321,94 @@ var RuntimeHost = class {
     }
   }
   render() {
-    if (this.destroyed || !this.dom || !this.context || this.currentStatus === "unsupported" || this.hasVisibilityBlock || this.inRender)
+    if (this.destroyed || !this.dom || !this.context || this.currentStatus === "unsupported" || this.inRender)
+      return;
+    if (this.isManual) {
+      this.renderInternal(this.elapsed, this.manualDelta);
       return;
+    }
+    if (this.hasVisibilityBlock) return;
     this.renderInternal(this.elapsed, 0);
   }
+  setTime(seconds) {
+    if (!Number.isFinite(seconds)) {
+      throw new RangeError(`setTime() expects a finite number, got ${seconds}`);
+    }
+    if (this.destroyed) return;
+    if (this.isManual) {
+      this.manualDelta = this.lastManualTime === null ? 0 : seconds - this.lastManualTime;
+      this.lastManualTime = seconds;
+    }
+    this.elapsed = seconds;
+  }
+  setClock(clock) {
+    if (this.destroyed || clock === this.clockMode) return;
+    this.clockMode = clock;
+    this.manualDelta = 0;
+    this.lastManualTime = null;
+    this.reconcile();
+  }
+  setResolution(resolution) {
+    if (this.destroyed) return;
+    if (resolution === null) {
+      if (this.isDetached) {
+        throw new TypeError(
+          "A canvas without a target needs a fixed resolution."
+        );
+      }
+      this.fixedResolution = null;
+    } else {
+      const next = normalizeResolution(resolution);
+      if (this.context) assertWithinLimits(this.context, next);
+      this.fixedResolution = next;
+    }
+    this.applyObjectFit();
+    this.resize();
+  }
+  async captureFrame(options = {}) {
+    const format = options.format ?? "png";
+    if (format !== "png" && format !== "rgba8" && format !== "rgba16f") {
+      throw new RangeError(`Unknown capture format: ${String(format)}`);
+    }
+    await this.ready;
+    if (this.destroyed) {
+      throw new DestroyedError("Runtime host was destroyed.");
+    }
+    if (!this.dom || !this.context) {
+      throw new UnsupportedError("Cannot capture without a WebGL context.");
+    }
+    if (this.inRender) {
+      throw new Error("captureFrame() cannot be called while a frame is drawing.");
+    }
+    const sourceFormat = this.options.captureSource?.()?.format;
+    if (format === "rgba16f" && sourceFormat !== "rgba16f" && sourceFormat !== "rgba32f") {
+      throw new UnsupportedError(
+        "rgba16f capture needs a float render target, such as feedback with format rgba16f."
+      );
+    }
+    options.signal?.throwIfAborted();
+    const delta = this.isManual ? this.manualDelta : 0;
+    const drawContext = this.context;
+    if (!this.options.onCaptureDraw) {
+      this.renderInternal(this.elapsed, delta);
+      return this.readCapture(format, drawContext);
+    }
+    try {
+      await this.renderForCapture(this.options.onCaptureDraw, delta, options.signal);
+      return this.readCapture(format, drawContext);
+    } finally {
+      if (this.resizePending) {
+        this.resizePending = false;
+        this.resize();
+      }
+    }
+  }
   resize() {
     if (this.destroyed || !this.dom) return;
+    if (this.captureDrawing) {
+      this.resizePending = true;
+      return;
+    }
     const prevWidth = this.width;
     const prevHeight = this.height;
     const prevViewportWidth = this.viewportWidth;
@@ -169,22 +416,9 @@ var RuntimeHost = class {
     this.measureSize();
     const sizeChanged = this.width !== prevWidth || this.height !== prevHeight || this.viewportWidth !== prevViewportWidth || this.viewportHeight !== prevViewportHeight;
     if (sizeChanged && this.context) {
-      this.options.onResize?.({
-        gl: this.context,
-        canvas: this.dom.canvas,
-        time: this.elapsed,
-        delta: 0,
-        frame: this.frame,
-        width: this.width,
-        height: this.height,
-        viewportWidth: this.viewportWidth,
-        viewportHeight: this.viewportHeight,
-        pixelRatio: this.pixelRatio,
-        reducedMotion: this.reducedMotionActive,
-        pointer: { ...this.pointer }
-      });
+      this.options.onResize?.(this.createFrameState(this.elapsed, 0));
     }
-    if (this.options.renderMode === "demand" && !this.inRender) {
+    if (this.shouldRenderOnDemand && !this.inRender) {
       this.render();
     }
   }
@@ -200,6 +434,8 @@ var RuntimeHost = class {
     this.context = null;
     if (this.dom?.createdCanvas) {
       this.dom.canvas.remove();
+    } else if (this.dom && this.objectFitRestore !== null) {
+      this.dom.canvas.style.objectFit = this.objectFitRestore;
     }
     const dom = this.dom;
     if (dom?.restoredPosition !== null && dom && this.options.target) {
@@ -208,6 +444,18 @@ var RuntimeHost = class {
     this.currentStatus = "destroyed";
     this.readyReject?.(new DestroyedError("Runtime host was destroyed."));
   }
+  get isManual() {
+    return this.clockMode === "manual";
+  }
+  get isDetached() {
+    if (this.dom) return this.dom.detached === true;
+    return this.options.target === void 0 && this.options.canvas === void 0;
+  }
+  // Demand mode re-renders on input changes, except under a manual clock where
+  // only explicit render() calls draw.
+  get shouldRenderOnDemand() {
+    return this.options.renderMode === "demand" && !this.isManual;
+  }
   get hasVisibilityBlock() {
     return this.gates.has("offscreen") || this.gates.has("hidden");
   }
@@ -224,6 +472,11 @@ var RuntimeHost = class {
     if (this.destroyed || this.currentStatus === "unsupported" || this.currentStatus === "error" || this.currentStatus === "context-lost") {
       return;
     }
+    if (this.isManual) {
+      this.cancelFrame();
+      this.currentStatus = "paused";
+      return;
+    }
     if (this.running) {
       if (this.hasVisibilityBlock) {
         this.cancelFrame();
@@ -248,11 +501,60 @@ var RuntimeHost = class {
     this.renderInternal(this.elapsed, 0);
   }
   renderInternal(time, delta) {
-    if (!this.dom || !this.context) return;
+    if (!this.dom || !this.context || this.inRender) return;
     const gl = this.context;
     this.inRender = true;
-    this.measureSize();
-    const state = {
+    try {
+      this.measureSize();
+      this.options.onDraw(this.createFrameState(time, delta, gl));
+      this.frame++;
+    } finally {
+      this.inRender = false;
+    }
+  }
+  // Holds the render lock across an asynchronous capture draw so no other
+  // frame interleaves with it.
+  async renderForCapture(draw, delta, signal) {
+    if (!this.dom || !this.context) return;
+    this.inRender = true;
+    this.captureDrawing = true;
+    try {
+      this.measureSize();
+      await draw(this.createFrameState(this.elapsed, delta, this.context), signal);
+      this.frame++;
+    } finally {
+      this.inRender = false;
+      this.captureDrawing = false;
+    }
+  }
+  // Reads the frame just drawn, in the task that drew it: the drawing buffer
+  // is not preserved. Fails if the context drawn into is gone, including when
+  // it was lost and restored while an asynchronous draw was pending.
+  readCapture(format, drawContext) {
+    if (this.destroyed) {
+      throw new DestroyedError("Runtime host was destroyed.");
+    }
+    const gl = this.context;
+    if (!gl || gl !== drawContext || !this.dom) {
+      throw new UnsupportedError("The WebGL context was lost while capturing.");
+    }
+    if (format === "png") {
+      return canvasToPng(this.dom.canvas);
+    }
+    if (format === "rgba8") {
+      return readPixels(gl, null, this.width, this.height, "rgba8");
+    }
+    const source = this.options.captureSource();
+    return readPixels(
+      gl,
+      source.framebuffer,
+      source.width,
+      source.height,
+      "rgba16f"
+    );
+  }
+  createFrameState(time, delta, gl = this.context) {
+    return {
       gl,
       canvas: this.dom.canvas,
       time,
@@ -263,15 +565,32 @@ var RuntimeHost = class {
       viewportWidth: this.viewportWidth,
       viewportHeight: this.viewportHeight,
       pixelRatio: this.pixelRatio,
-      reducedMotion: this.reducedMotionActive,
-      pointer: { ...this.pointer }
+      reducedMotion: this.isManual ? false : this.reducedMotionActive,
+      pointer: this.isManual ? { ...IDLE_POINTER } : { ...this.pointer }
     };
-    this.options.onDraw(state);
-    this.frame++;
-    this.inRender = false;
   }
   measureSize() {
     if (!this.dom) return;
+    if (this.fixedResolution) {
+      const size2 = resizeCanvasToResolution(
+        this.dom.canvas,
+        this.dom.detached ? null : this.dom.target,
+        this.fixedResolution
+      );
+      this.width = size2.width;
+      this.height = size2.height;
+      this.viewportWidth = size2.viewportWidth;
+      this.viewportHeight = size2.viewportHeight;
+      this.pixelRatio = Math.max(
+        size2.width / size2.viewportWidth,
+        size2.height / size2.viewportHeight
+      );
+      this.contentOffsetX = (size2.viewportWidth - size2.width / this.pixelRatio) / 2;
+      this.contentOffsetY = (size2.viewportHeight - size2.height / this.pixelRatio) / 2;
+      return;
+    }
+    this.contentOffsetX = 0;
+    this.contentOffsetY = 0;
     this.pixelRatio = resolveDpr(this.options.dpr, this.options.maxDpr);
     const size = resizeCanvasToTarget(
       this.dom.canvas,
@@ -283,8 +602,21 @@ var RuntimeHost = class {
     this.viewportWidth = size.viewportWidth;
     this.viewportHeight = size.viewportHeight;
   }
+  // Letterbox the fixed-resolution canvas instead of stretching it.
+  applyObjectFit() {
+    if (!this.dom) return;
+    const style = this.dom.canvas.style;
+    if (this.fixedResolution && this.objectFitRestore === null) {
+      this.objectFitRestore = style.objectFit ?? "";
+      style.objectFit = "contain";
+    } else if (!this.fixedResolution && this.objectFitRestore !== null) {
+      style.objectFit = this.objectFitRestore;
+      this.objectFitRestore = null;
+    }
+  }
   scheduleFrame() {
-    if (this.rafId || this.options.renderMode === "demand") return;
+    if (this.rafId || this.options.renderMode === "demand" || this.isManual)
+      return;
     this.rafId = requestAnimationFrame((timestamp) => {
       this.rafId = 0;
       if (!this.running || this.destroyed) return;
@@ -314,10 +646,17 @@ var RuntimeHost = class {
       ...this.options.canvas !== void 0 && { canvas: this.options.canvas },
       ...this.options.layer !== void 0 && { layer: this.options.layer },
       ...this.options.canvasClass !== void 0 && { canvasClass: this.options.canvasClass },
-      ...this.options.canvasStyle !== void 0 && { canvasStyle: this.options.canvasStyle }
+      ...this.options.canvasStyle !== void 0 && { canvasStyle: this.options.canvasStyle },
+      // Only a missing target/canvas may fall back to a detached canvas; a
+      // target that fails to resolve must still report TargetNotFoundError.
+      detached: this.fixedResolution !== null && this.options.target === void 0 && this.options.canvas === void 0
     });
     if (!this.dom) {
-      this.failUnsupported(new TargetNotFoundError("Target or canvas not found."));
+      this.failUnsupported(
+        new TargetNotFoundError(
+          "Target or canvas not found. Pass `resolution` to render without a target."
+        )
+      );
       return;
     }
     let gl;
@@ -333,9 +672,23 @@ var RuntimeHost = class {
       this.failUnsupported(new UnsupportedError("WebGL is not supported."));
       return;
     }
+    if (this.fixedResolution) {
+      try {
+        assertWithinLimits(gl, this.fixedResolution);
+      } catch (error) {
+        this.failUnsupported(
+          error instanceof Error ? error : new UnsupportedError(String(error))
+        );
+        return;
+      }
+      if (this.options.dpr !== void 0 || this.options.maxDpr !== void 0) {
+        this.debugWarn("`dpr` and `maxDpr` are ignored while `resolution` is set.");
+      }
+    }
     this.context = gl;
     this.currentStatus = "loading";
     try {
+      this.applyObjectFit();
       this.setupDomObservers();
       this.setupContextEvents();
       this.measureSize();
@@ -346,22 +699,24 @@ var RuntimeHost = class {
       this.options.onReady?.();
       if (this.running || (this.options.autoStart ?? true)) {
         this.start();
-      } else if (this.options.renderMode === "demand") {
+      } else if (this.shouldRenderOnDemand) {
         this.render();
       }
     } catch (error) {
-      this.fail(error instanceof Error ? error : new Error(String(error)));
+      if (error instanceof UnsupportedError) this.failUnsupported(error);
+      else this.fail(error instanceof Error ? error : new Error(String(error)));
     }
   }
   setupDomObservers() {
     if (!this.dom) return;
-    if (this.options.autoResize ?? true) {
+    const detached = this.dom.detached === true;
+    if (!detached && (this.options.autoResize ?? true)) {
       this.resizeObserver = new ResizeObserver(() => {
         this.resize();
       });
       this.resizeObserver.observe(this.dom.target);
     }
-    if (this.options.pauseWhenOffscreen ?? true) {
+    if (!detached && (this.options.pauseWhenOffscreen ?? true)) {
       this.intersectionObserver = new IntersectionObserver((entries) => {
         const entry = entries[0];
         this.setGate("offscreen", !entry?.isIntersecting);
@@ -379,22 +734,25 @@ var RuntimeHost = class {
       });
     }
     this.setupMotionObserver();
+    if (detached) return;
     const onPointerMove = (event) => {
       if (!this.dom) return;
       const pointerEvent = event;
       const rect = this.dom.target.getBoundingClientRect();
-      const x = pointerEvent.clientX - rect.left;
-      const y = pointerEvent.clientY - rect.top;
+      const x = pointerEvent.clientX - rect.left - this.contentOffsetX;
+      const y = pointerEvent.clientY - rect.top - this.contentOffsetY;
+      const contentWidth = this.fixedResolution ? this.width / this.pixelRatio : rect.width;
+      const contentHeight = this.fixedResolution ? this.height / this.pixelRatio : rect.height;
       this.pointer.x = x * this.pixelRatio;
-      this.pointer.y = (rect.height - y) * this.pixelRatio;
-      this.pointer.uvX = rect.width > 0 ? x / rect.width : 0;
-      this.pointer.uvY = rect.height > 0 ? 1 - y / rect.height : 0;
+      this.pointer.y = (contentHeight - y) * this.pixelRatio;
+      this.pointer.uvX = contentWidth > 0 ? x / contentWidth : 0;
+      this.pointer.uvY = contentHeight > 0 ? 1 - y / contentHeight : 0;
       this.pointer.active = 1;
-      if (this.options.renderMode === "demand") this.render();
+      if (this.shouldRenderOnDemand) this.render();
     };
     const onPointerLeave = () => {
       this.pointer.active = 0;
-      if (this.options.renderMode === "demand") this.render();
+      if (this.shouldRenderOnDemand) this.render();
     };
     this.dom.target.addEventListener("pointermove", onPointerMove);
     this.dom.target.addEventListener("pointerenter", onPointerMove);
@@ -416,7 +774,7 @@ var RuntimeHost = class {
       this.reducedMotionActive = event.matches;
       if (this.options.respectReducedMotion) {
         this.setGate("reducedMotion", event.matches);
-      } else if (this.options.renderMode === "demand") {
+      } else if (this.shouldRenderOnDemand) {
         this.render();
       }
     };
@@ -445,7 +803,7 @@ var RuntimeHost = class {
         try {
           await this.options.onContextRestored?.(gl, this.width, this.height);
           if (this.contextRestoredShouldRun) this.start();
-          else this.render();
+          else if (!this.isManual) this.render();
         } catch (error) {
           this.fail(error instanceof Error ? error : new Error(String(error)));
         }
@@ -477,6 +835,27 @@ var RuntimeHost = class {
     }
   }
 };
+var normalizeResolution = (resolution) => {
+  const [width, height] = resolution;
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width < 1 || height < 1) {
+    throw new RangeError(`Invalid resolution: ${width}x${height}`);
+  }
+  return [Math.round(width), Math.round(height)];
+};
+var assertWithinLimits = (gl, resolution) => {
+  const [width, height] = resolution;
+  const viewportDims = gl.getParameter(gl.MAX_VIEWPORT_DIMS);
+  const renderbufferSize = gl.getParameter(gl.MAX_RENDERBUFFER_SIZE);
+  const limit = (axis) => Math.min(
+    viewportDims?.[axis] ?? Number.POSITIVE_INFINITY,
+    typeof renderbufferSize === "number" ? renderbufferSize : Number.POSITIVE_INFINITY
+  );
+  if (width > limit(0) || height > limit(1)) {
+    throw new UnsupportedError(
+      `Resolution ${width}x${height} exceeds this GPU's limit of ${limit(0)}x${limit(1)}.`
+    );
+  }
+};
 
 // src/internal/names.ts
 var toUniformName = (name) => name.startsWith("u_") ? name : `u_${name}`;
@@ -539,78 +918,209 @@ var isTextureSource = (input) => typeof HTMLImageElement !== "undefined" && (inp
 var getSourceWidth = (source) => "naturalWidth" in source ? source.naturalWidth : source.width;
 var getSourceHeight = (source) => "naturalHeight" in source ? source.naturalHeight : source.height;
 
-// src/internal/webgl.ts
-var defaultVertexShader = `
-attribute vec2 a_position;
-varying vec2 v_uv;
-
-void main() {
-  v_uv = a_position * 0.5 + 0.5;
-  gl_Position = vec4(a_position, 0.0, 1.0);
-}
-`;
-var defaultVertexShader300 = `#version 300 es
-in vec2 a_position;
-out vec2 v_uv;
+// src/internal/textureSet.ts
+var createTextureSet = (inputs = {}) => {
+  const textureInputs = new Map(Object.entries(inputs));
+  let textures = /* @__PURE__ */ new Map();
+  const units = /* @__PURE__ */ new Map();
+  const versions = /* @__PURE__ */ new Map();
+  const reserveUnit = (gl, name) => {
+    const existing = units.get(name);
+    if (existing !== void 0) return existing;
+    const maxUnits = gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS);
+    const used = new Set(units.values());
+    for (let unit = 0; unit < maxUnits; unit += 1) {
+      if (!used.has(unit)) {
+        units.set(name, unit);
+        return unit;
+      }
+    }
+    throw new TextureLoadError(
+      `Texture unit limit exceeded while loading texture: ${name}`
+    );
+  };
+  return {
+    get textures() {
+      return textures;
+    },
+    hasInput(name) {
+      return textureInputs.has(name);
+    },
+    reserveUnit,
+    async loadAll(gl, isCancelled) {
+      const loaded = /* @__PURE__ */ new Map();
+      for (const [name, input] of textureInputs) {
+        if (isCancelled()) break;
+        const unit = reserveUnit(gl, name);
+        loaded.set(name, await loadTexture(gl, name, input, unit));
+      }
+      for (const texture of textures.values()) {
+        gl.deleteTexture(texture.texture);
+      }
+      textures = loaded;
+    },
+    async set(gl, name, input, isCancelled) {
+      const version = (versions.get(name) ?? 0) + 1;
+      versions.set(name, version);
+      try {
+        const unit = reserveUnit(gl, name);
+        const loaded = await loadTexture(gl, name, input, unit);
+        if (isCancelled() || versions.get(name) !== version) {
+          gl.deleteTexture(loaded.texture);
+          return null;
+        }
+        const previous = textures.get(name);
+        textureInputs.set(name, input);
+        textures.set(name, loaded);
+        if (previous) gl.deleteTexture(previous.texture);
+        return loaded;
+      } catch (error) {
+        if (!textures.has(name) && !textureInputs.has(name)) {
+          units.delete(name);
+        }
+        throw error;
+      }
+    },
+    bind(gl, locations, onMissing) {
+      for (const texture of textures.values()) {
+        const unit = units.get(texture.name);
+        if (unit === void 0) continue;
+        const location = locations.get(texture.uniformName);
+        if (!location) {
+          onMissing?.(texture.uniformName);
+          continue;
+        }
+        gl.activeTexture(gl.TEXTURE0 + unit);
+        gl.bindTexture(gl.TEXTURE_2D, texture.texture);
+        gl.uniform1i(location, unit);
+      }
+    },
+    dispose(gl) {
+      for (const texture of textures.values()) {
+        gl.deleteTexture(texture.texture);
+      }
+    }
+  };
+};
 
-void main() {
-  v_uv = a_position * 0.5 + 0.5;
-  gl_Position = vec4(a_position, 0.0, 1.0);
-}
-`;
-var isGLSL300 = (src) => /^\s*#version\s+300\s+es\b/.test(src);
-var createProgram = (gl, vertexSource, fragmentSource) => {
-  const vertex = compileShader(gl, gl.VERTEX_SHADER, vertexSource);
-  const fragment = compileShader(gl, gl.FRAGMENT_SHADER, fragmentSource);
-  const program = gl.createProgram();
-  if (!program) {
-    throw new ShaderCompileError("Failed to create WebGL program.");
+// src/internal/uniforms.ts
+var normalizeUniform = (input) => {
+  if (typeof input === "number") {
+    return { type: "float", value: [input] };
   }
-  gl.attachShader(program, vertex);
-  gl.attachShader(program, fragment);
-  gl.linkProgram(program);
-  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
-    const log = gl.getProgramInfoLog(program) ?? "Unknown program link error.";
-    gl.deleteProgram(program);
-    gl.deleteShader(vertex);
-    gl.deleteShader(fragment);
-    throw new ShaderCompileError(log);
+  if (input instanceof Float32Array) {
+    if (input.length === 9) return { type: "mat3", value: input };
+    if (input.length === 16) return { type: "mat4", value: input };
+    if (input.length === 2) return { type: "vec2", value: input };
+    if (input.length === 3) return { type: "vec3", value: input };
+    if (input.length === 4) return { type: "vec4", value: input };
   }
-  gl.deleteShader(vertex);
-  gl.deleteShader(fragment);
-  return program;
+  if (isExplicitUniform(input)) {
+    return { type: input.type, value: input.value };
+  }
+  if (Array.isArray(input)) {
+    if (input.length === 2) return { type: "vec2", value: input };
+    if (input.length === 3) return { type: "vec3", value: input };
+    if (input.length === 4) return { type: "vec4", value: input };
+  }
+  return { type: "float", value: [0] };
 };
-var createFullscreenBuffer = (gl, program) => {
-  const buffer = gl.createBuffer();
-  if (!buffer) {
-    throw new ShaderCompileError("Failed to create fullscreen buffer.");
+var applyUniform = (gl, location, uniform) => {
+  const value = uniform.value;
+  switch (uniform.type) {
+    case "float":
+      gl.uniform1f(location, value[0] ?? 0);
+      break;
+    case "vec2":
+      gl.uniform2f(location, value[0] ?? 0, value[1] ?? 0);
+      break;
+    case "vec3":
+      gl.uniform3f(location, value[0] ?? 0, value[1] ?? 0, value[2] ?? 0);
+      break;
+    case "vec4":
+      gl.uniform4f(
+        location,
+        value[0] ?? 0,
+        value[1] ?? 0,
+        value[2] ?? 0,
+        value[3] ?? 0
+      );
+      break;
+    case "mat3":
+      gl.uniformMatrix3fv(location, false, value);
+      break;
+    case "mat4":
+      gl.uniformMatrix4fv(location, false, value);
+      break;
   }
-  const location = gl.getAttribLocation(program, "a_position");
-  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
-  gl.bufferData(
-    gl.ARRAY_BUFFER,
-    new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]),
-    gl.STATIC_DRAW
-  );
-  if (location >= 0) {
-    gl.enableVertexAttribArray(location);
-    gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0);
+};
+var applyProgramUniform = (gl, program, location, uniform) => {
+  gl.useProgram(program);
+  applyUniform(gl, location, uniform);
+};
+var applyUniforms = (gl, locations, cache, onMissing) => {
+  for (const [name, uniform] of cache) {
+    const location = locations.get(name);
+    if (!location) {
+      onMissing?.(name);
+      continue;
+    }
+    applyUniform(gl, location, uniform);
   }
-  return buffer;
 };
-var compileShader = (gl, type, source) => {
-  const shader = gl.createShader(type);
-  if (!shader) {
-    throw new ShaderCompileError("Failed to create WebGL shader.");
+var collectUniformLocations = (gl, program) => {
+  const locations = /* @__PURE__ */ new Map();
+  const count = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);
+  for (let index = 0; index < count; index += 1) {
+    const active = gl.getActiveUniform(program, index);
+    if (!active) continue;
+    const name = active.name.replace(/\[0\]$/, "");
+    const location = gl.getUniformLocation(program, name);
+    if (location) {
+      locations.set(name, location);
+    }
   }
-  gl.shaderSource(shader, source);
-  gl.compileShader(shader);
-  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
-    const log = gl.getShaderInfoLog(shader) ?? "Unknown shader compile error.";
-    gl.deleteShader(shader);
-    throw new ShaderCompileError(log);
+  return locations;
+};
+var createUniformCache = (uniforms) => {
+  const cache = /* @__PURE__ */ new Map();
+  for (const [name, value] of Object.entries(uniforms ?? {})) {
+    cache.set(toUniformName(name), normalizeUniform(value));
   }
-  return shader;
+  return cache;
+};
+var isExplicitUniform = (input) => {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return false;
+  return "type" in input && "value" in input;
+};
+
+// src/internal/fullscreenProgram.ts
+var createFullscreenProgram = (gl, fragment, vertex) => {
+  const defaultVertex = isGLSL300(fragment) ? defaultVertexShader300 : defaultVertexShader;
+  const program = createProgram(gl, vertex ?? defaultVertex, fragment);
+  gl.useProgram(program);
+  const buffer = createFullscreenBuffer(gl, program);
+  const attribLocation = gl.getAttribLocation(program, "a_position");
+  const locations = collectUniformLocations(gl, program);
+  return {
+    program,
+    locations,
+    use() {
+      gl.useProgram(program);
+      gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+      if (attribLocation >= 0) {
+        gl.enableVertexAttribArray(attribLocation);
+        gl.vertexAttribPointer(attribLocation, 2, gl.FLOAT, false, 0, 0);
+      }
+    },
+    draw() {
+      gl.drawArrays(gl.TRIANGLES, 0, 6);
+    },
+    dispose() {
+      gl.deleteBuffer(buffer);
+      gl.deleteProgram(program);
+    }
+  };
 };
 
 // src/internal/blit.ts
@@ -633,7 +1143,6 @@ void main() {
   fragColor = texture(u_texture, v_uv);
 }
 `;
-var isWebGL2Context = (gl) => typeof gl.createVertexArray === "function";
 var createBlitter = (gl) => {
   const program = createProgram(
     gl,
@@ -666,6 +1175,173 @@ var createBlitter = (gl) => {
     }
   };
 };
+
+// src/internal/renderTarget.ts
+var DEFAULT_CLEAR_COLOR = [0, 0, 0, 0];
+var supportsRenderTargetFormat = (gl, format) => {
+  if (format === "rgba8") return true;
+  return isWebGL2Context(gl) && gl.getExtension("EXT_color_buffer_float") !== null;
+};
+var resolveRenderTargetFormat = (gl, format = "rgba8", formatFallback = true) => {
+  if (supportsRenderTargetFormat(gl, format)) return format;
+  const reason = `${format} render targets need WebGL2 with EXT_color_buffer_float.`;
+  if (!formatFallback) throw new UnsupportedError(reason);
+  console.warn(`[frapx] ${reason} Falling back to rgba8.`);
+  return "rgba8";
+};
+var createRenderTarget = (gl, width, height, options = {}) => {
+  const format = resolveRenderTargetFormat(
+    gl,
+    options.format,
+    options.formatFallback
+  );
+  return new Target(gl, width, height, format, options);
+};
+var createPingPong = (gl, width, height, options = {}) => {
+  const format = resolveRenderTargetFormat(
+    gl,
+    options.format,
+    options.formatFallback
+  );
+  let read = new Target(gl, width, height, format, options);
+  let write;
+  try {
+    write = new Target(gl, width, height, format, options);
+  } catch (error) {
+    read.dispose();
+    throw error;
+  }
+  return {
+    get read() {
+      return read;
+    },
+    get write() {
+      return write;
+    },
+    format,
+    swap() {
+      const previous = read;
+      read = write;
+      write = previous;
+    },
+    resize(nextWidth, nextHeight) {
+      read.resize(nextWidth, nextHeight);
+      write.resize(nextWidth, nextHeight);
+    },
+    clear() {
+      read.clear();
+      write.clear();
+    },
+    dispose() {
+      read.dispose();
+      write.dispose();
+    }
+  };
+};
+var Target = class {
+  constructor(gl, width, height, format, options) {
+    this.gl = gl;
+    this.format = format;
+    this.options = options;
+    this.width = width;
+    this.height = height;
+    this.allocate();
+  }
+  resize(width, height) {
+    if (width === this.width && height === this.height) return;
+    this.release();
+    this.width = width;
+    this.height = height;
+    this.allocate();
+  }
+  clear() {
+    const gl = this.gl;
+    const [r, g, b, a] = this.options.clearColor ?? DEFAULT_CLEAR_COLOR;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.viewport(0, 0, this.width, this.height);
+    gl.clearColor(r, g, b, a);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  }
+  dispose() {
+    this.release();
+  }
+  allocate() {
+    const gl = this.gl;
+    const texture = gl.createTexture();
+    if (!texture) {
+      throw new ShaderCompileError("Failed to create render target texture.");
+    }
+    const framebuffer = gl.createFramebuffer();
+    if (!framebuffer) {
+      gl.deleteTexture(texture);
+      throw new ShaderCompileError("Failed to create render target framebuffer.");
+    }
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    if (this.format !== "rgba8" && isWebGL2Context(gl)) {
+      const half = this.format === "rgba16f";
+      gl.texImage2D(
+        gl.TEXTURE_2D,
+        0,
+        half ? gl.RGBA16F : gl.RGBA32F,
+        this.width,
+        this.height,
+        0,
+        gl.RGBA,
+        half ? gl.HALF_FLOAT : gl.FLOAT,
+        null
+      );
+    } else {
+      gl.texImage2D(
+        gl.TEXTURE_2D,
+        0,
+        gl.RGBA,
+        this.width,
+        this.height,
+        0,
+        gl.RGBA,
+        gl.UNSIGNED_BYTE,
+        null
+      );
+    }
+    const wrap = getWrap2(gl, this.options.wrap ?? "clamp");
+    const linear = this.options.filter !== "nearest" && (this.format !== "rgba32f" || gl.getExtension("OES_texture_float_linear") !== null);
+    const filter = linear ? gl.LINEAR : gl.NEAREST;
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, wrap);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, wrap);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+    gl.framebufferTexture2D(
+      gl.FRAMEBUFFER,
+      gl.COLOR_ATTACHMENT0,
+      gl.TEXTURE_2D,
+      texture,
+      0
+    );
+    const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+    if (status !== gl.FRAMEBUFFER_COMPLETE) {
+      gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+      gl.deleteFramebuffer(framebuffer);
+      gl.deleteTexture(texture);
+      throw new ShaderCompileError(
+        `Render target framebuffer (${this.format}) is incomplete: ${status}`
+      );
+    }
+    this.texture = texture;
+    this.framebuffer = framebuffer;
+    this.clear();
+  }
+  release() {
+    this.gl.deleteFramebuffer(this.framebuffer);
+    this.gl.deleteTexture(this.texture);
+  }
+};
+var getWrap2 = (gl, wrap) => {
+  if (wrap === "repeat") return gl.REPEAT;
+  if (wrap === "mirror") return gl.MIRRORED_REPEAT;
+  return gl.CLAMP_TO_EDGE;
+};
 export {
   DestroyedError,
   ShaderCompileError,
@@ -673,10 +1349,19 @@ export {
   TargetNotFoundError,
   TextureLoadError,
   UnsupportedError,
+  applyProgramUniform,
+  applyUniform,
+  applyUniforms,
+  collectUniformLocations,
   createBlitter,
   createFullscreenBuffer,
+  createFullscreenProgram,
+  createPingPong,
   createProgram,
+  createRenderTarget,
   createRuntimeHost,
+  createTextureSet,
+  createUniformCache,
   defaultVertexShader,
   defaultVertexShader300,
   fromUniformName,
@@ -685,11 +1370,16 @@ export {
   hexToRgb,
   hexToRgba,
   isGLSL300,
+  isWebGL2Context,
   loadTexture,
+  normalizeUniform,
   resizeCanvasToTarget,
   resolveDpr,
   resolveElement,
+  resolveRenderTargetFormat,
   setupCanvas,
-  toUniformName
+  supportsRenderTargetFormat,
+  toUniformName,
+  waitForGpu
 };
 //# sourceMappingURL=index.js.map