gputex 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # GPUtex
 
-Runtime GPU texture compression via WebGPU compute shaders. Feed it a PNG/JPG/WebP/AVIF and get back a GPU-compressed texture (BC7, BC5, ASTC 4x4, or BC1) ready for Three.js or React Three Fiber.
+Runtime GPU texture compression via WebGPU compute shaders, with a WebGL2 fragment-shader fallback. Feed it a PNG/JPG/WebP/AVIF and get back a GPU-compressed texture (BC7, BC5, ASTC 4x4, or BC1) ready for Three.js or React Three Fiber.
 
 ⚠️: This is 100% vibe-coded. The code is completely unreviewed, under-tested, it will probably crash on many devices, and this library is very likely to go unmaintained. Do not use for anything important.
 
@@ -27,6 +27,18 @@ bun add gputex
 
 Format selection is automatic: BC7/BC5 on desktop, ASTC on mobile, uncompressed RGBA8 fallback otherwise.
 
+## WebGL fallback
+
+WebGPU is the primary path. When it's unavailable (older Safari, Firefox without WebGPU, locked-down environments) `compressTexture()` automatically falls back to a **WebGL2** path that runs the same block encoders as fragment shaders — each 4×4 block is computed in one fragment, written to an `RGBA32UI` render target, and read back. The output bytes are identical to the WebGPU encoders, so the resulting `CompressedTexture` looks the same under either renderer.
+
+The fallback chain is **WebGPU → WebGL2 → uncompressed RGBA8**. The `backend` field on the result (`'webgpu' | 'webgl' | 'none'`) tells you which path ran.
+
+Notes on the WebGL path:
+
+- It needs the matching WebGL2 compressed-texture extension to be sampleable: `EXT_texture_compression_bptc` (BC7), `EXT_texture_compression_rgtc` (BC5), `WEBGL_compressed_texture_astc` (ASTC), or `WEBGL_compressed_texture_s3tc` (BC1). Selection mirrors the WebGPU side, with BC1 added as a broadly-available last resort for **opaque** colour when neither BPTC nor ASTC is present.
+- It always uses the **fast** encoders — the `quality: 'high'` option and the `device` / `adapter` options apply to the WebGPU path only.
+- All encoding happens on one shared, off-screen WebGL2 context; nothing is drawn to a visible canvas.
+
 ## Usage
 
 ### `compressTexture` — direct API
@@ -171,9 +183,11 @@ encoder.destroy()
 
 ## Requirements
 
-- A browser with WebGPU support
-- `texture-compression-bc` (desktop) or `texture-compression-astc` (mobile) for compressed output
-- Falls back to uncompressed RGBA8 when neither is available
+- WebGPU (primary) **or** WebGL2 (fallback) — almost every current browser has at least one
+- A compressed-texture capability for compressed output:
+  - WebGPU: `texture-compression-bc` (desktop) or `texture-compression-astc` (mobile)
+  - WebGL2: `EXT_texture_compression_bptc` / `_rgtc`, `WEBGL_compressed_texture_astc`, or `WEBGL_compressed_texture_s3tc`
+- Falls back to uncompressed RGBA8 when no compressed format is available on either backend
 
 ## Device-specific workarounds
 

package/dist/index.d.ts

@@ -244,6 +244,163 @@ declare class ASTC4x4Encoder extends Encoder {
     threeTextureFormat(): CompressedPixelFormat;
 }
 
+/** One encoded mip level. The fields both encoder backends already produce. */
+interface EncodedLevel {
+    /** Logical (pre-padding) dimensions, surfaced on the texture's userData. */
+    width: number;
+    height: number;
+    /** Block-aligned dimensions the compressed `data` actually covers. */
+    paddedWidth: number;
+    paddedHeight: number;
+    data: Uint8Array;
+}
+
+/** Raw RGBA8 pixel data (e.g. a CPU-generated mip level). */
+interface RawPixelSource {
+    data: ArrayBufferView;
+    width: number;
+    height: number;
+}
+/** Anything the WebGL encoders can upload as the source image. */
+type WebGLEncoderImageSource = ImageBitmap | ImageData | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | RawPixelSource;
+interface WebGLEncodeBytesResult {
+    width: number;
+    height: number;
+    paddedWidth: number;
+    paddedHeight: number;
+    data: Uint8Array;
+    encodeMs: number;
+}
+interface WebGLEncoderOptions {
+    gl: WebGL2RenderingContext;
+}
+/**
+ * Constructor shape for the concrete subclasses; lets the static `create()`
+ * narrow its return type to the subclass (as the WebGPU `EncoderConstructor`
+ * does).
+ */
+type WebGLEncoderConstructor<T extends WebGLBlockEncoder = WebGLBlockEncoder> = {
+    new (opts: WebGLEncoderOptions): T;
+    create(gl?: WebGL2RenderingContext | null): T;
+};
+declare abstract class WebGLBlockEncoder {
+    /**
+     * Create an encoder on the shared process-wide context (or a caller-supplied
+     * one). Throws when WebGL2 is unavailable. The `this:` annotation lets
+     * `BC7WebGLEncoder.create()` return `BC7WebGLEncoder`.
+     */
+    static create<T extends WebGLBlockEncoder>(this: WebGLEncoderConstructor<T>, gl?: WebGL2RenderingContext | null): T;
+    readonly gl: WebGL2RenderingContext;
+    protected _program: WebGLProgram;
+    protected _vao: WebGLVertexArrayObject;
+    protected _uSrc: WebGLUniformLocation | null;
+    protected _uSrcSize: WebGLUniformLocation | null;
+    protected _uFlipY: WebGLUniformLocation | null;
+    constructor({ gl }: WebGLEncoderOptions);
+    /** Short lowercase identifier for labels / errors. */
+    abstract get label(): string;
+    /** 8 for BC1, 16 for BC5/BC7/ASTC 4×4. */
+    abstract get bytesPerBlock(): number;
+    /** Whether this format has an sRGB variant (false for BC5). */
+    abstract get supportsSrgb(): boolean;
+    /** GLSL ES 3.00 fragment-shader source. */
+    abstract fragSource(): string;
+    /** Three.js `CompressedPixelFormat` constant; sRGB is carried by colorSpace. */
+    abstract threeTextureFormat(): CompressedPixelFormat;
+    protected _buildProgram(): void;
+    /** Release the GL program + VAO. The shared context itself is left intact. */
+    destroy(): void;
+    /**
+     * Upload the source image to a freshly created RGBA8 texture bound on unit 0.
+     * Raw pixel sources (ImageData / mip levels) go through the typed-array
+     * overload; DOM sources (ImageBitmap / canvas / image) through the element
+     * overload. No flip / premultiply / colour conversion — flipY is applied in
+     * the shader so each mip level flips by its own height.
+     */
+    protected _uploadSource(source: WebGLEncoderImageSource, width: number, height: number): WebGLTexture;
+    /**
+     * Encode one image source to raw compressed bytes. `flipY` samples the source
+     * bottom-up (matching Three.js's convention) and is applied in the shader;
+     * the high-level mipped path bakes the flip into level 0 and passes false.
+     */
+    encodeToBytes(source: WebGLEncoderImageSource, { flipY }?: {
+        flipY?: boolean;
+    }): WebGLEncodeBytesResult;
+    /** Wrap pre-encoded levels into a CompressedTexture. Shared with the WebGPU path. */
+    buildMippedTexture(levels: readonly EncodedLevel[], { colorSpace }?: {
+        colorSpace?: 'srgb' | 'linear';
+    }): CompressedTexture;
+}
+
+declare class BC1WebGLEncoder extends WebGLBlockEncoder {
+    get label(): string;
+    get bytesPerBlock(): number;
+    get supportsSrgb(): boolean;
+    fragSource(): string;
+    threeTextureFormat(): CompressedPixelFormat;
+}
+
+declare class BC5WebGLEncoder extends WebGLBlockEncoder {
+    get label(): string;
+    get bytesPerBlock(): number;
+    get supportsSrgb(): boolean;
+    fragSource(): string;
+    threeTextureFormat(): CompressedPixelFormat;
+}
+
+declare class BC7WebGLEncoder extends WebGLBlockEncoder {
+    get label(): string;
+    get bytesPerBlock(): number;
+    get supportsSrgb(): boolean;
+    fragSource(): string;
+    threeTextureFormat(): CompressedPixelFormat;
+}
+
+declare class ASTC4x4WebGLEncoder extends WebGLBlockEncoder {
+    get label(): string;
+    get bytesPerBlock(): number;
+    get supportsSrgb(): boolean;
+    fragSource(): string;
+    threeTextureFormat(): CompressedPixelFormat;
+}
+
+/**
+ * Create a fresh WebGL2 context backed by an off-screen 1×1 canvas. Returns
+ * null when neither `OffscreenCanvas` nor `document` is available (e.g. a
+ * non-DOM worker without OffscreenCanvas) or when the platform has no WebGL2.
+ */
+declare function createWebGLContext(): WebGL2RenderingContext | null;
+/**
+ * Lazily-created context shared across the high-level fallback path. Re-created
+ * if the previous one was lost (tab backgrounding, GPU reset). Returns null
+ * when WebGL2 is unavailable on this platform.
+ */
+declare function getSharedWebGLContext(): WebGL2RenderingContext | null;
+/** True when a WebGL2 context can be created on this platform. */
+declare function isWebGLAvailable(): boolean;
+
+/**
+ * Minimal structural type for the extension source: only `getExtension` is
+ * touched, so tests can pass a `{ getExtension }` stub instead of a real
+ * `WebGL2RenderingContext`.
+ */
+interface ExtensionProvider {
+    getExtension(name: string): unknown;
+}
+interface WebGLCapabilities {
+    /** EXT_texture_compression_bptc → BC7 (BPTC). */
+    bptc: boolean;
+    /** EXT_texture_compression_rgtc → BC5 (RGTC2). */
+    rgtc: boolean;
+    /** WEBGL_compressed_texture_s3tc → BC1 (DXT1). */
+    s3tc: boolean;
+    /** WEBGL_compressed_texture_s3tc_srgb → sRGB DXT1 (separate extension). */
+    s3tcSrgb: boolean;
+    /** WEBGL_compressed_texture_astc → ASTC 4×4 (and other footprints). */
+    astc: boolean;
+}
+declare function detectWebGLCapabilities(gl: ExtensionProvider): WebGLCapabilities;
+
 /**
  * How the texture will be used in the renderer. Drives format choice.
  *   • 'color'          — RGB albedo-like data (alpha optional / ignored).
@@ -269,6 +426,16 @@ interface FormatSelection {
 }
 declare function selectFormat(adapter: FeatureProvider, hint: TextureHint, options?: SelectFormatOptions): FormatSelection;
 
+interface WebGLFormatSelection {
+    /** null = no compressed path available on this WebGL context. */
+    format: TextureFormat | null;
+    /** null when `format` is null. */
+    encoderClass: WebGLEncoderConstructor | null;
+    /** True when the chosen path is ASTC *and* the hint is 'normal' (caller must pre-swizzle). */
+    astcNormalRemap: boolean;
+}
+declare function selectWebGLFormat(caps: WebGLCapabilities, hint: TextureHint, options?: SelectFormatOptions): WebGLFormatSelection;
+
 /**
  * Everything `compressTexture()` can take as an image source. A superset
  * of `EncoderImageSource` (see Encoder.ts) that also accepts URL strings
@@ -287,21 +454,28 @@ interface CompressOptions {
     /**
      * Encode quality / speed trade-off. 'fast' (default) is ~2–4× faster for a
      * ≤0.36 dB PSNR cost; 'high' runs the exhaustive search (output identical to
-     * the CPU reference encoders). No effect on BC1.
+     * the CPU reference encoders). No effect on BC1 or on the WebGL fallback
+     * (which always uses the fast encoders).
      */
     quality?: EncodeQuality;
     /** Reuse an existing device (e.g. Three.js's renderer device) instead
-     *  of creating a new one. When provided, the encoder never destroys it. */
+     *  of creating a new one. WebGPU path only. When provided, the encoder
+     *  never destroys it. */
     device?: GPUDevice;
     adapter?: GPUAdapter;
 }
 interface CompressResult {
-    /** CompressedTexture on the compressed path; Texture on RGBA8 fallback. */
+    /** CompressedTexture on a compressed path; Texture on RGBA8 fallback. */
     texture: Texture | CompressedTexture;
     /** The compressed format selected, or null when we fell back to RGBA8. */
     format: TextureFormat | null;
     /** True iff we returned an uncompressed Texture because no encoder fit. */
     fallbackUncompressed: boolean;
+    /**
+     * Which backend produced the result. 'webgpu' = compute path, 'webgl' =
+     * fragment-shader fallback, 'none' = uncompressed RGBA8.
+     */
+    backend: 'webgpu' | 'webgl' | 'none';
     /**
      * True iff the chosen format is ASTC and the hint was 'normal'. The
      * caller must apply the (R, W) → (x, y) swizzle in the material — ASTC
@@ -376,4 +550,4 @@ declare function generateMipChain(level0: MipLevel): MipLevel[];
  */
 declare function padToBlockMultiple(level: MipLevel): MipLevel;
 
-export { ASTC4x4Encoder, BC1Encoder, BC5Encoder, BC7Encoder, type Capabilities, type CompressOptions, type CompressResult, type CompressTextureSource, type EncodeBytesResult, type EncodeCallOptions, type EncodeQuality, type EncodeResult, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type FeatureProvider, type FormatSelection, type FormatVariant, GputexLoader, type MipLevel, type SelectFormatOptions, TextureFormat, type TextureHint, WebGPUFeature, compressTexture, detectCapabilities, generateMipChain, padToBlockMultiple, selectFormat };
+export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, BC7WebGLEncoder, type Capabilities, type CompressOptions, type CompressResult, type CompressTextureSource, type EncodeBytesResult, type EncodeCallOptions, type EncodeQuality, type EncodeResult, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type ExtensionProvider, type FeatureProvider, type FormatSelection, type FormatVariant, GputexLoader, type MipLevel, type RawPixelSource, type SelectFormatOptions, TextureFormat, type TextureHint, WebGLBlockEncoder, type WebGLCapabilities, type WebGLEncodeBytesResult, type WebGLEncoderConstructor, type WebGLEncoderImageSource, type WebGLEncoderOptions, type WebGLFormatSelection, WebGPUFeature, compressTexture, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateMipChain, getSharedWebGLContext, isWebGLAvailable, padToBlockMultiple, selectFormat, selectWebGLFormat };

package/dist/index.js

@@ -42,14 +42,39 @@ function detectCapabilities(adapter) {
 }
 
 // src/Encoder.ts
+import { CompressedTexture as CompressedTexture2, LinearFilter as LinearFilter2, LinearSRGBColorSpace as LinearSRGBColorSpace2, SRGBColorSpace as SRGBColorSpace2, RepeatWrapping as RepeatWrapping2 } from "three";
+
+// src/textureAssembly.ts
 import {
   CompressedTexture,
   LinearFilter,
   LinearMipmapLinearFilter,
   LinearSRGBColorSpace,
-  SRGBColorSpace,
-  RepeatWrapping
+  RepeatWrapping,
+  SRGBColorSpace
 } from "three";
+function assembleCompressedTexture(levels, threeFormat, effectiveSrgb) {
+  if (levels.length === 0) {
+    throw new Error("assembleCompressedTexture: no levels provided");
+  }
+  const mipmaps = levels.map((l) => ({
+    data: l.data,
+    width: l.paddedWidth,
+    height: l.paddedHeight
+  }));
+  const base = levels[0];
+  const texture = new CompressedTexture(mipmaps, base.paddedWidth, base.paddedHeight, threeFormat);
+  texture.colorSpace = effectiveSrgb ? SRGBColorSpace : LinearSRGBColorSpace;
+  texture.magFilter = LinearFilter;
+  texture.minFilter = levels.length > 1 ? LinearMipmapLinearFilter : LinearFilter;
+  texture.generateMipmaps = false;
+  texture.wrapS = texture.wrapT = RepeatWrapping;
+  texture.needsUpdate = true;
+  texture.userData.logicalWidth = base.width;
+  texture.userData.logicalHeight = base.height;
+  texture.userData.mipLevels = levels.length;
+  return texture;
+}
 
 // src/workarounds.ts
 function needsWriteTextureWorkaround(adapter) {
@@ -228,12 +253,12 @@ var Encoder = class {
       width: bytes.paddedWidth,
       height: bytes.paddedHeight
     };
-    const texture = new CompressedTexture([mip], bytes.paddedWidth, bytes.paddedHeight, threeFormat);
-    texture.colorSpace = effectiveSrgb ? SRGBColorSpace : LinearSRGBColorSpace;
-    texture.magFilter = LinearFilter;
-    texture.minFilter = LinearFilter;
+    const texture = new CompressedTexture2([mip], bytes.paddedWidth, bytes.paddedHeight, threeFormat);
+    texture.colorSpace = effectiveSrgb ? SRGBColorSpace2 : LinearSRGBColorSpace2;
+    texture.magFilter = LinearFilter2;
+    texture.minFilter = LinearFilter2;
     texture.generateMipmaps = false;
-    texture.wrapS = texture.wrapT = RepeatWrapping;
+    texture.wrapS = texture.wrapT = RepeatWrapping2;
     texture.needsUpdate = true;
     texture.userData.logicalWidth = bytes.width;
     texture.userData.logicalHeight = bytes.height;
@@ -341,23 +366,7 @@ var Encoder = class {
     }
     const effectiveSrgb = colorSpace === "srgb" && this.supportsSrgb;
     const threeFormat = this.threeTextureFormat({ colorSpace: effectiveSrgb ? "srgb" : "linear" });
-    const mipmaps = levels.map((l) => ({
-      data: l.data,
-      width: l.paddedWidth,
-      height: l.paddedHeight
-    }));
-    const base = levels[0];
-    const texture = new CompressedTexture(mipmaps, base.paddedWidth, base.paddedHeight, threeFormat);
-    texture.colorSpace = effectiveSrgb ? SRGBColorSpace : LinearSRGBColorSpace;
-    texture.magFilter = LinearFilter;
-    texture.minFilter = levels.length > 1 ? LinearMipmapLinearFilter : LinearFilter;
-    texture.generateMipmaps = false;
-    texture.wrapS = texture.wrapT = RepeatWrapping;
-    texture.needsUpdate = true;
-    texture.userData.logicalWidth = base.width;
-    texture.userData.logicalHeight = base.height;
-    texture.userData.mipLevels = levels.length;
-    return texture;
+    return assembleCompressedTexture(levels, threeFormat, effectiveSrgb);
   }
 };
 
@@ -585,6 +594,373 @@ var ASTC4x4Encoder = class extends Encoder {
   }
 };
 
+// src/webgl/glsl/fullscreen.vert.glsl
+var fullscreen_vert_default = "#version 300 es\n// Fullscreen-triangle vertex shader for the WebGL block encoders.\n//\n// Draws a single oversized triangle covering the viewport from gl_VertexID\n// alone \u2014 no vertex buffers / attributes needed (drawArrays(TRIANGLES, 0, 3)).\n// The encoder sets the viewport to (blocks_x \xD7 blocks_y), so each rasterised\n// fragment corresponds to exactly one 4\xD74 output block.\n//\n//   id 0 -> (-1,-1)   id 1 -> ( 3,-1)   id 2 -> (-1, 3)\n\nvoid main() {\n  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));\n  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);\n}\n";
+
+// src/webgl/webglContext.ts
+var CONTEXT_ATTRS = {
+  alpha: false,
+  antialias: false,
+  depth: false,
+  stencil: false,
+  premultipliedAlpha: false,
+  preserveDrawingBuffer: false,
+  // Encoding is GPU-bound; prefer the discrete GPU when the browser exposes a
+  // choice. Ignored where unsupported.
+  powerPreference: "high-performance"
+};
+function createWebGLContext() {
+  if (typeof OffscreenCanvas !== "undefined") {
+    const gl = new OffscreenCanvas(1, 1).getContext("webgl2", CONTEXT_ATTRS);
+    return gl ?? null;
+  }
+  if (typeof document !== "undefined") {
+    return document.createElement("canvas").getContext("webgl2", CONTEXT_ATTRS);
+  }
+  return null;
+}
+var sharedContext;
+function getSharedWebGLContext() {
+  if (sharedContext === void 0 || sharedContext !== null && sharedContext.isContextLost()) {
+    sharedContext = createWebGLContext();
+  }
+  return sharedContext;
+}
+function isWebGLAvailable() {
+  return getSharedWebGLContext() !== null;
+}
+
+// src/webgl/WebGLBlockEncoder.ts
+function compileShader(gl, type, source, label) {
+  const shader = gl.createShader(type);
+  if (!shader) throw new Error(`${label}: gl.createShader failed`);
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    const log = gl.getShaderInfoLog(shader);
+    gl.deleteShader(shader);
+    const kind = type === gl.VERTEX_SHADER ? "vertex" : "fragment";
+    throw new Error(`${label}: ${kind} shader compile failed: ${log}`);
+  }
+  return shader;
+}
+var WebGLBlockEncoder = class {
+  /**
+   * Create an encoder on the shared process-wide context (or a caller-supplied
+   * one). Throws when WebGL2 is unavailable. The `this:` annotation lets
+   * `BC7WebGLEncoder.create()` return `BC7WebGLEncoder`.
+   */
+  static create(gl) {
+    const ctx = gl ?? getSharedWebGLContext();
+    if (!ctx) throw new Error("WebGL2 not available in this environment");
+    return new this({ gl: ctx });
+  }
+  gl;
+  // Set in _buildProgram(), which the constructor calls.
+  _program;
+  _vao;
+  _uSrc = null;
+  _uSrcSize = null;
+  _uFlipY = null;
+  constructor({ gl }) {
+    this.gl = gl;
+    this._buildProgram();
+  }
+  _buildProgram() {
+    const gl = this.gl;
+    const program = gl.createProgram();
+    const vao = gl.createVertexArray();
+    if (!program || !vao) throw new Error(`${this.label}: failed to allocate WebGL program/VAO`);
+    const vert = compileShader(gl, gl.VERTEX_SHADER, fullscreen_vert_default, this.label);
+    const frag = compileShader(gl, gl.FRAGMENT_SHADER, this.fragSource(), this.label);
+    gl.attachShader(program, vert);
+    gl.attachShader(program, frag);
+    gl.linkProgram(program);
+    gl.deleteShader(vert);
+    gl.deleteShader(frag);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+      const log = gl.getProgramInfoLog(program);
+      gl.deleteProgram(program);
+      throw new Error(`${this.label}: WebGL program link failed: ${log}`);
+    }
+    this._program = program;
+    this._vao = vao;
+    this._uSrc = gl.getUniformLocation(program, "uSrc");
+    this._uSrcSize = gl.getUniformLocation(program, "uSrcSize");
+    this._uFlipY = gl.getUniformLocation(program, "uFlipY");
+  }
+  /** Release the GL program + VAO. The shared context itself is left intact. */
+  destroy() {
+    const gl = this.gl;
+    if (gl.isContextLost()) return;
+    gl.deleteProgram(this._program);
+    gl.deleteVertexArray(this._vao);
+  }
+  /**
+   * Upload the source image to a freshly created RGBA8 texture bound on unit 0.
+   * Raw pixel sources (ImageData / mip levels) go through the typed-array
+   * overload; DOM sources (ImageBitmap / canvas / image) through the element
+   * overload. No flip / premultiply / colour conversion — flipY is applied in
+   * the shader so each mip level flips by its own height.
+   */
+  _uploadSource(source, width, height) {
+    const gl = this.gl;
+    const tex = gl.createTexture();
+    if (!tex) throw new Error(`${this.label}: gl.createTexture failed`);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+    gl.pixelStorei(gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.NONE);
+    gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+    const raw = source;
+    if (raw.data && ArrayBuffer.isView(raw.data)) {
+      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, raw.data);
+    } else {
+      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, gl.RGBA, gl.UNSIGNED_BYTE, source);
+    }
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    return tex;
+  }
+  /**
+   * Encode one image source to raw compressed bytes. `flipY` samples the source
+   * bottom-up (matching Three.js's convention) and is applied in the shader;
+   * the high-level mipped path bakes the flip into level 0 and passes false.
+   */
+  encodeToBytes(source, { flipY = false } = {}) {
+    const gl = this.gl;
+    if (gl.isContextLost()) throw new Error(`${this.label}WebGLEncoder: WebGL context lost`);
+    const width = source.width;
+    const height = source.height;
+    if (!width || !height) {
+      throw new Error(`${this.label}WebGLEncoder: source has no dimensions`);
+    }
+    const paddedWidth = width + 3 & ~3;
+    const paddedHeight = height + 3 & ~3;
+    const blocksX = paddedWidth >> 2;
+    const blocksY = paddedHeight >> 2;
+    const blockCount = blocksX * blocksY;
+    const outByteLen = blockCount * this.bytesPerBlock;
+    const t0 = performance.now();
+    const srcTex = this._uploadSource(source, width, height);
+    const outTex = gl.createTexture();
+    const fbo = gl.createFramebuffer();
+    if (!outTex || !fbo) {
+      gl.deleteTexture(srcTex);
+      if (outTex) gl.deleteTexture(outTex);
+      if (fbo) gl.deleteFramebuffer(fbo);
+      throw new Error(`${this.label}: failed to allocate output texture/framebuffer`);
+    }
+    gl.bindTexture(gl.TEXTURE_2D, outTex);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA32UI, blocksX, blocksY);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, outTex, 0);
+    const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+    if (status !== gl.FRAMEBUFFER_COMPLETE) {
+      gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+      gl.deleteFramebuffer(fbo);
+      gl.deleteTexture(outTex);
+      gl.deleteTexture(srcTex);
+      throw new Error(`${this.label}: integer framebuffer incomplete (0x${status.toString(16)})`);
+    }
+    gl.useProgram(this._program);
+    gl.bindVertexArray(this._vao);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, srcTex);
+    gl.uniform1i(this._uSrc, 0);
+    gl.uniform2i(this._uSrcSize, width, height);
+    gl.uniform1i(this._uFlipY, flipY ? 1 : 0);
+    gl.disable(gl.BLEND);
+    gl.disable(gl.DEPTH_TEST);
+    gl.disable(gl.SCISSOR_TEST);
+    gl.viewport(0, 0, blocksX, blocksY);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    const words = new Uint32Array(blockCount * 4);
+    gl.readPixels(0, 0, blocksX, blocksY, gl.RGBA_INTEGER, gl.UNSIGNED_INT, words);
+    let data;
+    if (this.bytesPerBlock === 16) {
+      data = new Uint8Array(words.buffer, 0, outByteLen);
+    } else {
+      const packed = new Uint32Array(blockCount * 2);
+      for (let k = 0; k < blockCount; k++) {
+        packed[k * 2] = words[k * 4];
+        packed[k * 2 + 1] = words[k * 4 + 1];
+      }
+      data = new Uint8Array(packed.buffer, 0, outByteLen);
+    }
+    const encodeMs = performance.now() - t0;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    gl.bindVertexArray(null);
+    gl.deleteFramebuffer(fbo);
+    gl.deleteTexture(outTex);
+    gl.deleteTexture(srcTex);
+    return { width, height, paddedWidth, paddedHeight, data, encodeMs };
+  }
+  /** Wrap pre-encoded levels into a CompressedTexture. Shared with the WebGPU path. */
+  buildMippedTexture(levels, { colorSpace = "srgb" } = {}) {
+    if (levels.length === 0) {
+      throw new Error(`${this.label}WebGLEncoder.buildMippedTexture: no levels provided`);
+    }
+    const effectiveSrgb = colorSpace === "srgb" && this.supportsSrgb;
+    return assembleCompressedTexture(levels, this.threeTextureFormat(), effectiveSrgb);
+  }
+};
+
+// src/webgl/BC1WebGLEncoder.ts
+import { RGBA_S3TC_DXT1_Format as RGBA_S3TC_DXT1_Format2 } from "three";
+
+// src/webgl/glsl/bc1.frag.glsl
+var bc1_frag_default = "#version 300 es\n// BC1 (DXT1) fragment-shader encoder \u2014 WebGL2 port of bc1.wgsl.\n//\n// One fragment per 4\xD74 block. Output is the 8-byte BC1 block as 2 \xD7 u32 in\n// outColor.rg (outColor.ba unused); the encoder reads back RGBA32UI and keeps\n// the low two words per block. Algorithm mirrors bc1.wgsl line-for-line:\n// bbox endpoints, 1/16 inset, RGB565 quantisation, forced 4-colour mode, full\n// L2 index search. See bc1.wgsl for the detailed rationale.\n\nprecision highp float;\nprecision highp int;\n\nuniform sampler2D uSrc;\nuniform ivec2 uSrcSize; // original (unpadded) width, height\nuniform int uFlipY;     // 1 = sample bottom-up (matches Three.js flipY)\n\nlayout(location = 0) out uvec4 outColor;\n\nuint to565(vec3 c) {\n  uint r = uint(clamp(floor(c.r * 31.0 + 0.5), 0.0, 31.0));\n  uint g = uint(clamp(floor(c.g * 63.0 + 0.5), 0.0, 63.0));\n  uint b = uint(clamp(floor(c.b * 31.0 + 0.5), 0.0, 31.0));\n  return (r << 11) | (g << 5) | b;\n}\n\nvec3 from565(uint c) {\n  float r = float((c >> 11) & 31u);\n  float g = float((c >> 5) & 63u);\n  float b = float(c & 31u);\n  float r8 = (r * 527.0 + 23.0) / 256.0;\n  float g8 = (g * 259.0 + 33.0) / 256.0;\n  float b8 = (b * 527.0 + 23.0) / 256.0;\n  return vec3(r8, g8, b8) / 255.0;\n}\n\nvoid main() {\n  ivec2 base = ivec2(gl_FragCoord.xy) * 4;\n  ivec2 maxXY = uSrcSize - ivec2(1);\n\n  vec3 pixels[16];\n  vec3 bbMin = vec3(1.0);\n  vec3 bbMax = vec3(0.0);\n  for (int i = 0; i < 16; i++) {\n    ivec2 p = clamp(base + ivec2(i & 3, i >> 2), ivec2(0), maxXY);\n    int sy = (uFlipY != 0) ? (uSrcSize.y - 1 - p.y) : p.y;\n    vec3 c = texelFetch(uSrc, ivec2(p.x, sy), 0).rgb;\n    pixels[i] = c;\n    bbMin = min(bbMin, c);\n    bbMax = max(bbMax, c);\n  }\n\n  // Inset the bounding box by ~half an RGB565 cell (1/16) to tighten the\n  // quantised palette around the real data range.\n  vec3 inset = (bbMax - bbMin) / 16.0;\n  vec3 hi = clamp(bbMax - inset, vec3(0.0), vec3(1.0));\n  vec3 lo = clamp(bbMin + inset, vec3(0.0), vec3(1.0));\n\n  uint c0 = to565(hi);\n  uint c1 = to565(lo);\n\n  // 4-colour mode requires c0 > c1.\n  if (c0 == c1) {\n    if (c1 > 0u) { c1 = c1 - 1u; } else { c0 = c0 + 1u; }\n  } else if (c0 < c1) {\n    uint tmp = c0; c0 = c1; c1 = tmp;\n  }\n\n  vec3 p0 = from565(c0);\n  vec3 p1 = from565(c1);\n  vec3 p2 = (2.0 * p0 + p1) * (1.0 / 3.0);\n  vec3 p3 = (p0 + 2.0 * p1) * (1.0 / 3.0);\n\n  uint indices = 0u;\n  for (int i = 0; i < 16; i++) {\n    vec3 c = pixels[i];\n    float d0 = dot(c - p0, c - p0);\n    float d1 = dot(c - p1, c - p1);\n    float d2 = dot(c - p2, c - p2);\n    float d3 = dot(c - p3, c - p3);\n\n    float bestD = d0;\n    uint bestI = 0u;\n    if (d1 < bestD) { bestD = d1; bestI = 1u; }\n    if (d2 < bestD) { bestD = d2; bestI = 2u; }\n    if (d3 < bestD) { bestD = d3; bestI = 3u; }\n\n    indices = indices | (bestI << (i * 2));\n  }\n\n  outColor = uvec4(c0 | (c1 << 16), indices, 0u, 0u);\n}\n";
+
+// src/webgl/BC1WebGLEncoder.ts
+var BC1WebGLEncoder = class extends WebGLBlockEncoder {
+  get label() {
+    return "bc1";
+  }
+  get bytesPerBlock() {
+    return 8;
+  }
+  get supportsSrgb() {
+    return true;
+  }
+  fragSource() {
+    return bc1_frag_default;
+  }
+  threeTextureFormat() {
+    return RGBA_S3TC_DXT1_Format2;
+  }
+};
+
+// src/webgl/BC5WebGLEncoder.ts
+import { RED_GREEN_RGTC2_Format as RED_GREEN_RGTC2_Format2 } from "three";
+
+// src/webgl/glsl/bc5.frag.glsl
+var bc5_frag_default = "#version 300 es\n// BC5 (RGTC2) fragment-shader encoder \u2014 WebGL2 port of bc5.wgsl (fast path).\n//\n// One fragment per 4\xD74 block \u2192 16-byte BC5 block as 4 \xD7 u32 in outColor.\n// BC5 = two BC4 halves (R then G). This is the *fast* path only: bbox\n// endpoints + a single full-L2 index assignment per channel, no LSQ refit\n// (the WGSL `QUALITY_HIGH` branch). Always emits 6-interpolation mode\n// (red0 > red1). See bc5.wgsl for the full derivation.\n\nprecision highp float;\nprecision highp int;\n\nuniform sampler2D uSrc;\nuniform ivec2 uSrcSize;\nuniform int uFlipY;\n\nlayout(location = 0) out uvec4 outColor;\n\n// 6-interpolation-mode palette weights: pal[j] = W0_6[j]*r0 + W1_6[j]*r1.\nconst float W0_6[8] = float[8](1.0, 0.0, 6.0 / 7.0, 5.0 / 7.0, 4.0 / 7.0, 3.0 / 7.0, 2.0 / 7.0, 1.0 / 7.0);\nconst float W1_6[8] = float[8](0.0, 1.0, 1.0 / 7.0, 2.0 / 7.0, 3.0 / 7.0, 4.0 / 7.0, 5.0 / 7.0, 6.0 / 7.0);\n\nuint quantize8(float v) {\n  return uint(clamp(floor(v * 255.0 + 0.5), 0.0, 255.0));\n}\n\n// Encode 16 single-channel values into an 8-byte BC4 block (two little-endian\n// u32s). Mirrors encode_bc4() in bc5.wgsl with the refit pass omitted.\nuvec2 encodeBC4(float values[16]) {\n  float vmin = 1.0;\n  float vmax = 0.0;\n  for (int k = 0; k < 16; k++) {\n    vmin = min(vmin, values[k]);\n    vmax = max(vmax, values[k]);\n  }\n  uint r0 = quantize8(vmax);\n  uint r1 = quantize8(vmin);\n  if (r0 == r1) {\n    if (r1 > 0u) { r1 = r1 - 1u; } else { r0 = r0 + 1u; }\n  }\n\n  float pal[8];\n  float r0f = float(r0) / 255.0;\n  float r1f = float(r1) / 255.0;\n  for (int j = 0; j < 8; j++) {\n    pal[j] = W0_6[j] * r0f + W1_6[j] * r1f;\n  }\n\n  uint indices[16];\n  for (int k = 0; k < 16; k++) {\n    float v = values[k];\n    uint bestJ = 0u;\n    float bestD = 1e20;\n    for (int j = 0; j < 8; j++) {\n      float d = pal[j] - v;\n      float d2 = d * d;\n      if (d2 < bestD) { bestD = d2; bestJ = uint(j); }\n    }\n    indices[k] = bestJ;\n  }\n\n  // Pack the 48-bit index field (bytes 2..7) split across two u32 halves.\n  uint idxLo = 0u;\n  uint idxHi = 0u;\n  for (int k = 0; k < 16; k++) {\n    uint bit = 3u * uint(k);\n    uint v = indices[k] & 7u;\n    if (bit + 3u <= 32u) {\n      idxLo = idxLo | (v << bit);\n    } else if (bit >= 32u) {\n      idxHi = idxHi | (v << (bit - 32u));\n    } else {\n      idxLo = idxLo | (v << bit);\n      idxHi = idxHi | (v >> (32u - bit));\n    }\n  }\n\n  uint outLo = r0 | (r1 << 8) | ((idxLo & 0xFFFFu) << 16);\n  uint outHi = (idxLo >> 16) | (idxHi << 16);\n  return uvec2(outLo, outHi);\n}\n\nvoid main() {\n  ivec2 base = ivec2(gl_FragCoord.xy) * 4;\n  ivec2 maxXY = uSrcSize - ivec2(1);\n\n  float rValues[16];\n  float gValues[16];\n  for (int i = 0; i < 16; i++) {\n    ivec2 p = clamp(base + ivec2(i & 3, i >> 2), ivec2(0), maxXY);\n    int sy = (uFlipY != 0) ? (uSrcSize.y - 1 - p.y) : p.y;\n    vec4 c = texelFetch(uSrc, ivec2(p.x, sy), 0);\n    rValues[i] = c.r;\n    gValues[i] = c.g;\n  }\n\n  uvec2 rBlock = encodeBC4(rValues);\n  uvec2 gBlock = encodeBC4(gValues);\n  outColor = uvec4(rBlock.x, rBlock.y, gBlock.x, gBlock.y);\n}\n";
+
+// src/webgl/BC5WebGLEncoder.ts
+var BC5WebGLEncoder = class extends WebGLBlockEncoder {
+  get label() {
+    return "bc5";
+  }
+  get bytesPerBlock() {
+    return 16;
+  }
+  get supportsSrgb() {
+    return false;
+  }
+  fragSource() {
+    return bc5_frag_default;
+  }
+  threeTextureFormat() {
+    return RED_GREEN_RGTC2_Format2;
+  }
+};
+
+// src/webgl/BC7WebGLEncoder.ts
+import { RGBA_BPTC_Format as RGBA_BPTC_Format2 } from "three";
+
+// src/webgl/glsl/bc7.frag.glsl
+var bc7_frag_default = "#version 300 es\n// BC7 (BPTC) mode-6 fragment-shader encoder \u2014 WebGL2 port of bc7.wgsl (fast).\n//\n// One fragment per 4\xD74 block \u2192 16-byte block as 4 \xD7 u32 in outColor. Fast path\n// only: O(N) bbox seed \u2192 endpoints fitted by a single least-squares pass whose\n// normal-equation sums are accumulated during a projection-based index\n// assignment (palette is colinear, so the nearest entry is found by projecting\n// onto the endpoint line \u2014 O(1) per pixel). Mirrors the `QUALITY_HIGH == 0`\n// branch of bc7.wgsl; see that file for the mode-6 bit layout and rationale.\n//\n// Determinism note: the WGSL refit uses round() (half-to-even); here we use\n// floor(x + 0.5) for portability. The two differ only at exact .5 ties, a\n// sub-LSB endpoint nudge that is visually identical.\n\nprecision highp float;\nprecision highp int;\n\nuniform sampler2D uSrc;\nuniform ivec2 uSrcSize;\nuniform int uFlipY;\n\nlayout(location = 0) out uvec4 outColor;\n\n// Per-invocation scratch (mirrors the WGSL function-scope arrays passed by ptr).\nivec4 gPixels[16];\nuint gIdx[16];\n\nstruct QuantPair { ivec4 seven; ivec4 eight; };\nstruct Ep { ivec4 seven; ivec4 eight; uint p; };\nstruct Fit { ivec4 e0; ivec4 e1; bool valid; };\n\nivec4 to8(vec4 v) {\n  return ivec4(clamp(floor(v * 255.0 + 0.5), vec4(0.0), vec4(255.0)));\n}\n\nint dist2(ivec4 a, ivec4 b) {\n  ivec4 d = a - b;\n  ivec4 e = d * d;\n  return e.x + e.y + e.z + e.w;\n}\n\n// Quantize an 8-bit ideal endpoint to (7-bit value, reconstructed 8-bit) under\n// a fixed p-bit, all four channels at once.\nQuantPair quantizeEndpoint(ivec4 ideal8, uint p) {\n  ivec4 q = ivec4(clamp(floor((vec4(ideal8) - float(p)) / 2.0 + 0.5), vec4(0.0), vec4(127.0)));\n  // eff = (q << 1) | p. q*2 is even and p \u2208 {0,1}, so q*2 + p is identical and\n  // avoids any vector-shift-by-scalar portability question.\n  ivec4 eff = q * 2 + ivec4(int(p));\n  return QuantPair(q, eff);\n}\n\n// Endpoint with its chosen p-bit, picked by minimum quantisation error.\nEp pickEp(ivec4 ideal) {\n  QuantPair a = quantizeEndpoint(ideal, 0u);\n  QuantPair b = quantizeEndpoint(ideal, 1u);\n  if (dist2(b.eight, ideal) < dist2(a.eight, ideal)) {\n    return Ep(b.seven, b.eight, 1u);\n  }\n  return Ep(a.seven, a.eight, 0u);\n}\n\n// Projection index assignment over gPixels \u2192 gIdx. When `fit`, accumulate the\n// LSQ normal-equation sums in the same pass and return refitted endpoints.\nFit projAssign(ivec4 pe0, ivec4 pe1, bool fit) {\n  Fit res;\n  res.e0 = ivec4(0);\n  res.e1 = ivec4(0);\n  res.valid = false;\n  ivec4 dir = pe1 - pe0;\n  int dd = dir.x * dir.x + dir.y * dir.y + dir.z * dir.z + dir.w * dir.w;\n  if (dd == 0) {\n    for (int k = 0; k < 16; k++) { gIdx[k] = 0u; }\n    return res;\n  }\n  float inv = 15.0 / float(dd);\n  float sAA = 0.0, sBB = 0.0, sAB = 0.0;\n  vec4 sAV = vec4(0.0), sBV = vec4(0.0);\n  for (int k = 0; k < 16; k++) {\n    ivec4 q = gPixels[k] - pe0;\n    float proj = float(q.x * dir.x + q.y * dir.y + q.z * dir.z + q.w * dir.w) * inv;\n    float s = clamp(floor(proj + 0.5), 0.0, 15.0);\n    gIdx[k] = uint(s);\n    if (fit) {\n      vec4 v = vec4(gPixels[k]);\n      float b = s / 15.0;\n      float a = 1.0 - b;\n      sAA += a * a; sBB += b * b; sAB += a * b; sAV += a * v; sBV += b * v;\n    }\n  }\n  if (!fit) { return res; }\n  float det = sAA * sBB - sAB * sAB;\n  if (abs(det) < 1e-9) { return res; }\n  res.e0 = ivec4(clamp(floor((sBB * sAV - sAB * sBV) / det + 0.5), vec4(0.0), vec4(255.0)));\n  res.e1 = ivec4(clamp(floor((sAA * sBV - sAB * sAV) / det + 0.5), vec4(0.0), vec4(255.0)));\n  res.valid = true;\n  return res;\n}\n\nvoid writeBits(inout uint block[4], uint pos, uint nbits, uint value) {\n  uint v = value & ((1u << nbits) - 1u);\n  uint wordLo = pos / 32u;\n  uint bitLo = pos % 32u;\n  uint bitsInLo = min(nbits, 32u - bitLo);\n  uint maskLo = ((1u << bitsInLo) - 1u) << bitLo;\n  block[wordLo] = (block[wordLo] & ~maskLo) | ((v << bitLo) & maskLo);\n  if (bitsInLo < nbits) {\n    uint bitsInHi = nbits - bitsInLo;\n    uint maskHi = (1u << bitsInHi) - 1u;\n    uint valHi = v >> bitsInLo;\n    block[wordLo + 1u] = (block[wordLo + 1u] & ~maskHi) | (valHi & maskHi);\n  }\n}\n\nvoid main() {\n  ivec2 base = ivec2(gl_FragCoord.xy) * 4;\n  ivec2 maxXY = uSrcSize - ivec2(1);\n\n  ivec4 lo = ivec4(255);\n  ivec4 hi = ivec4(0);\n  for (int i = 0; i < 16; i++) {\n    ivec2 p = clamp(base + ivec2(i & 3, i >> 2), ivec2(0), maxXY);\n    int sy = (uFlipY != 0) ? (uSrcSize.y - 1 - p.y) : p.y;\n    ivec4 px = to8(texelFetch(uSrc, ivec2(p.x, sy), 0));\n    gPixels[i] = px;\n    lo = min(lo, px);\n    hi = max(hi, px);\n  }\n\n  Ep ep0 = pickEp(lo);\n  Ep ep1 = pickEp(hi);\n  Fit r = projAssign(ep0.eight, ep1.eight, true);\n  if (r.valid) {\n    ep0 = pickEp(r.e0);\n    ep1 = pickEp(r.e1);\n    projAssign(ep0.eight, ep1.eight, false);\n  }\n  ivec4 e0_7 = ep0.seven;\n  ivec4 e1_7 = ep1.seven;\n  uint p0 = ep0.p;\n  uint p1 = ep1.p;\n\n  // Anchor rule \u2014 pixel 0's index MSB must be 0; otherwise swap endpoints and\n  // reflect every index (decoded image unchanged).\n  if ((gIdx[0] & 0x8u) != 0u) {\n    ivec4 t = e0_7; e0_7 = e1_7; e1_7 = t;\n    uint tp = p0; p0 = p1; p1 = tp;\n    for (int k = 0; k < 16; k++) { gIdx[k] = 15u - gIdx[k]; }\n  }\n\n  uint block[4];\n  block[0] = 0u; block[1] = 0u; block[2] = 0u; block[3] = 0u;\n  uint pos = 0u;\n  writeBits(block, pos, 7u, 0x40u); pos += 7u;\n  writeBits(block, pos, 7u, uint(e0_7.x)); pos += 7u;\n  writeBits(block, pos, 7u, uint(e1_7.x)); pos += 7u;\n  writeBits(block, pos, 7u, uint(e0_7.y)); pos += 7u;\n  writeBits(block, pos, 7u, uint(e1_7.y)); pos += 7u;\n  writeBits(block, pos, 7u, uint(e0_7.z)); pos += 7u;\n  writeBits(block, pos, 7u, uint(e1_7.z)); pos += 7u;\n  writeBits(block, pos, 7u, uint(e0_7.w)); pos += 7u;\n  writeBits(block, pos, 7u, uint(e1_7.w)); pos += 7u;\n  writeBits(block, pos, 1u, p0); pos += 1u;\n  writeBits(block, pos, 1u, p1); pos += 1u;\n  writeBits(block, pos, 3u, gIdx[0] & 0x7u); pos += 3u;\n  for (int k = 1; k < 16; k++) {\n    writeBits(block, pos, 4u, gIdx[k] & 0xFu);\n    pos += 4u;\n  }\n\n  outColor = uvec4(block[0], block[1], block[2], block[3]);\n}\n";
+
+// src/webgl/BC7WebGLEncoder.ts
+var BC7WebGLEncoder = class extends WebGLBlockEncoder {
+  get label() {
+    return "bc7";
+  }
+  get bytesPerBlock() {
+    return 16;
+  }
+  get supportsSrgb() {
+    return true;
+  }
+  fragSource() {
+    return bc7_frag_default;
+  }
+  threeTextureFormat() {
+    return RGBA_BPTC_Format2;
+  }
+};
+
+// src/webgl/ASTC4x4WebGLEncoder.ts
+import { RGBA_ASTC_4x4_Format as RGBA_ASTC_4x4_Format2 } from "three";
+
+// src/webgl/glsl/astc4x4.frag.glsl
+var astc4x4_frag_default = "#version 300 es\n// ASTC 4\xD74 LDR fragment-shader encoder \u2014 WebGL2 port of astc4x4.wgsl (fast).\n//\n// One fragment per 4\xD74 block \u2192 16-byte block as 4 \xD7 u32 in outColor. Restricted\n// subset: single partition, no dual-plane, CEM 12 (LDR RGBA direct), 4\xD74 weight\n// grid with 2-bit weights (QUANT_4), 8-bit endpoints (QUANT_256). Fast path:\n// bbox seed \u2192 one LSQ refit fused into a projection weight assignment (4 colinear\n// levels). Mirrors the `QUALITY_HIGH == 0` branch of astc4x4.wgsl; see that file\n// for the 128-bit block layout.\n//\n// Determinism note: floor(x + 0.5) replaces WGSL round() for the refit endpoints\n// (sub-LSB difference at exact .5 ties only).\n\nprecision highp float;\nprecision highp int;\n\nuniform sampler2D uSrc;\nuniform ivec2 uSrcSize;\nuniform int uFlipY;\n\nlayout(location = 0) out uvec4 outColor;\n\nivec4 gPixels[16];\nuint gIdx[16];\n\nstruct Fit { ivec4 e0; ivec4 e1; bool valid; };\n\nivec4 to8(vec4 v) {\n  return ivec4(clamp(floor(v * 255.0 + 0.5), vec4(0.0), vec4(255.0)));\n}\n\n// Projection weight assignment over 4 levels (QUANT_4 \u2248 thirds), with the LSQ\n// normal-equation sums accumulated in the same pass for a fused refit.\nFit projAssign(ivec4 pe0, ivec4 pe1, bool fit) {\n  Fit res;\n  res.e0 = ivec4(0);\n  res.e1 = ivec4(0);\n  res.valid = false;\n  ivec4 dir = pe1 - pe0;\n  int dd = dir.x * dir.x + dir.y * dir.y + dir.z * dir.z + dir.w * dir.w;\n  if (dd == 0) {\n    for (int k = 0; k < 16; k++) { gIdx[k] = 0u; }\n    return res;\n  }\n  float inv = 3.0 / float(dd);\n  float sAA = 0.0, sBB = 0.0, sAB = 0.0;\n  vec4 sAV = vec4(0.0), sBV = vec4(0.0);\n  for (int k = 0; k < 16; k++) {\n    ivec4 q = gPixels[k] - pe0;\n    float proj = float(q.x * dir.x + q.y * dir.y + q.z * dir.z + q.w * dir.w) * inv;\n    float s = clamp(floor(proj + 0.5), 0.0, 3.0);\n    gIdx[k] = uint(s);\n    if (fit) {\n      vec4 v = vec4(gPixels[k]);\n      float b = s / 3.0;\n      float a = 1.0 - b;\n      sAA += a * a; sBB += b * b; sAB += a * b; sAV += a * v; sBV += b * v;\n    }\n  }\n  if (!fit) { return res; }\n  float det = sAA * sBB - sAB * sAB;\n  if (abs(det) < 1e-9) { return res; }\n  res.e0 = ivec4(clamp(floor((sBB * sAV - sAB * sBV) / det + 0.5), vec4(0.0), vec4(255.0)));\n  res.e1 = ivec4(clamp(floor((sAA * sBV - sAB * sAV) / det + 0.5), vec4(0.0), vec4(255.0)));\n  res.valid = true;\n  return res;\n}\n\nvoid writeBits(inout uint block[4], uint pos, uint nbits, uint value) {\n  uint v = value & ((1u << nbits) - 1u);\n  uint wordLo = pos / 32u;\n  uint bitLo = pos % 32u;\n  uint bitsInLo = min(nbits, 32u - bitLo);\n  uint maskLo = ((1u << bitsInLo) - 1u) << bitLo;\n  block[wordLo] = (block[wordLo] & ~maskLo) | ((v << bitLo) & maskLo);\n  if (bitsInLo < nbits) {\n    uint bitsInHi = nbits - bitsInLo;\n    uint maskHi = (1u << bitsInHi) - 1u;\n    uint valHi = v >> bitsInLo;\n    block[wordLo + 1u] = (block[wordLo + 1u] & ~maskHi) | (valHi & maskHi);\n  }\n}\n\nvoid main() {\n  ivec2 base = ivec2(gl_FragCoord.xy) * 4;\n  ivec2 maxXY = uSrcSize - ivec2(1);\n\n  ivec4 lo = ivec4(255);\n  ivec4 hi = ivec4(0);\n  for (int i = 0; i < 16; i++) {\n    ivec2 p = clamp(base + ivec2(i & 3, i >> 2), ivec2(0), maxXY);\n    int sy = (uFlipY != 0) ? (uSrcSize.y - 1 - p.y) : p.y;\n    ivec4 px = to8(texelFetch(uSrc, ivec2(p.x, sy), 0));\n    gPixels[i] = px;\n    lo = min(lo, px);\n    hi = max(hi, px);\n  }\n\n  ivec4 e0 = lo;\n  ivec4 e1 = hi;\n  Fit r = projAssign(e0, e1, true);\n  if (r.valid) {\n    e0 = r.e0;\n    e1 = r.e1;\n    projAssign(e0, e1, false);\n  }\n\n  // Endpoint ordering so the decoder doesn't apply blue contraction.\n  if (e0.x + e0.y + e0.z > e1.x + e1.y + e1.z) {\n    ivec4 t = e0; e0 = e1; e1 = t;\n    for (int k = 0; k < 16; k++) { gIdx[k] = 3u - gIdx[k]; }\n  }\n\n  uint block[4];\n  block[0] = 0u; block[1] = 0u; block[2] = 0u; block[3] = 0u;\n  writeBits(block, 0u, 11u, 0x042u);\n  writeBits(block, 11u, 2u, 0u);\n  writeBits(block, 13u, 4u, 12u);\n  writeBits(block, 17u + 0u * 8u, 8u, uint(e0.x));\n  writeBits(block, 17u + 1u * 8u, 8u, uint(e1.x));\n  writeBits(block, 17u + 2u * 8u, 8u, uint(e0.y));\n  writeBits(block, 17u + 3u * 8u, 8u, uint(e1.y));\n  writeBits(block, 17u + 4u * 8u, 8u, uint(e0.z));\n  writeBits(block, 17u + 5u * 8u, 8u, uint(e1.z));\n  writeBits(block, 17u + 6u * 8u, 8u, uint(e0.w));\n  writeBits(block, 17u + 7u * 8u, 8u, uint(e1.w));\n\n  uint w3 = 0u;\n  for (int k = 0; k < 16; k++) {\n    uint w = gIdx[k] & 0x3u;\n    w3 = w3 | ((w & 1u) << (31u - 2u * uint(k))) | (((w >> 1u) & 1u) << (30u - 2u * uint(k)));\n  }\n  block[3] = w3;\n\n  outColor = uvec4(block[0], block[1], block[2], block[3]);\n}\n";
+
+// src/webgl/ASTC4x4WebGLEncoder.ts
+var ASTC4x4WebGLEncoder = class extends WebGLBlockEncoder {
+  get label() {
+    return "astc4x4";
+  }
+  get bytesPerBlock() {
+    return 16;
+  }
+  get supportsSrgb() {
+    return true;
+  }
+  fragSource() {
+    return astc4x4_frag_default;
+  }
+  threeTextureFormat() {
+    return RGBA_ASTC_4x4_Format2;
+  }
+};
+
+// src/webgl/webglCapabilities.ts
+function detectWebGLCapabilities(gl) {
+  if (!gl || typeof gl.getExtension !== "function") {
+    throw new TypeError("detectWebGLCapabilities: a WebGL2 context (or { getExtension }) is required");
+  }
+  const has = (name) => gl.getExtension(name) != null;
+  return {
+    bptc: has("EXT_texture_compression_bptc"),
+    rgtc: has("EXT_texture_compression_rgtc"),
+    s3tc: has("WEBGL_compressed_texture_s3tc"),
+    s3tcSrgb: has("WEBGL_compressed_texture_s3tc_srgb"),
+    astc: has("WEBGL_compressed_texture_astc")
+  };
+}
+
+// src/webgl/selectWebGLFormat.ts
+var NONE = { format: null, encoderClass: null, astcNormalRemap: false };
+function selectWebGLFormat(caps, hint, options = {}) {
+  const { colorSpace = "srgb" } = options;
+  const srgb = colorSpace === "srgb";
+  const astc = (astcNormalRemap) => ({
+    format: srgb ? TextureFormat.ASTC_4x4_SRGB : TextureFormat.ASTC_4x4,
+    encoderClass: ASTC4x4WebGLEncoder,
+    astcNormalRemap
+  });
+  if (hint === "normal") {
+    if (caps.rgtc) return { format: TextureFormat.BC5, encoderClass: BC5WebGLEncoder, astcNormalRemap: false };
+    if (caps.astc) return astc(true);
+    return NONE;
+  }
+  if (caps.bptc) {
+    return {
+      format: srgb ? TextureFormat.BC7_SRGB : TextureFormat.BC7,
+      encoderClass: BC7WebGLEncoder,
+      astcNormalRemap: false
+    };
+  }
+  if (caps.astc) return astc(false);
+  if (hint === "color") {
+    if (srgb && caps.s3tcSrgb) {
+      return { format: TextureFormat.BC1_SRGB, encoderClass: BC1WebGLEncoder, astcNormalRemap: false };
+    }
+    if (!srgb && caps.s3tc) {
+      return { format: TextureFormat.BC1, encoderClass: BC1WebGLEncoder, astcNormalRemap: false };
+    }
+  }
+  return NONE;
+}
+
 // src/selectFormat.ts
 function selectFormat(adapter, hint, options = {}) {
   const { colorSpace = "srgb" } = options;
@@ -612,7 +988,7 @@ function selectFormat(adapter, hint, options = {}) {
 }
 
 // src/compressTexture.ts
-import { LinearFilter as LinearFilter2, LinearSRGBColorSpace as LinearSRGBColorSpace2, RepeatWrapping as RepeatWrapping2, SRGBColorSpace as SRGBColorSpace2, Texture } from "three";
+import { LinearFilter as LinearFilter3, LinearSRGBColorSpace as LinearSRGBColorSpace3, RepeatWrapping as RepeatWrapping3, SRGBColorSpace as SRGBColorSpace3, Texture } from "three";
 
 // src/mipgen.ts
 function generateMipChain(level0) {
@@ -722,10 +1098,10 @@ function mipLevelToImageData(level) {
 }
 function wrapUncompressed(bitmap, srgb, flipY) {
   const tex = new Texture(bitmap);
-  tex.colorSpace = srgb ? SRGBColorSpace2 : LinearSRGBColorSpace2;
-  tex.magFilter = LinearFilter2;
-  tex.minFilter = LinearFilter2;
-  tex.wrapS = tex.wrapT = RepeatWrapping2;
+  tex.colorSpace = srgb ? SRGBColorSpace3 : LinearSRGBColorSpace3;
+  tex.magFilter = LinearFilter3;
+  tex.minFilter = LinearFilter3;
+  tex.wrapS = tex.wrapT = RepeatWrapping3;
   tex.generateMipmaps = false;
   tex.flipY = flipY;
   tex.needsUpdate = true;
@@ -743,124 +1119,159 @@ async function compressTexture(source, options = {}) {
   } = options;
   const srgb = colorSpace === "srgb";
   const bitmap = await sourceToBitmap(source);
-  if (!("gpu" in navigator)) {
-    console.warn("[compressTexture] WebGPU unavailable; returning uncompressed RGBA8.");
-    const tex = wrapUncompressed(bitmap, srgb, flipY);
-    return {
-      texture: tex,
-      format: null,
-      fallbackUncompressed: true,
-      astcNormalRemap: false,
-      width: bitmap.width,
-      height: bitmap.height,
-      mipLevels: 1,
-      encodeMs: 0,
-      destroy: () => {
-        tex.dispose();
+  const viaWebGPU = await encodeViaWebGPU();
+  if (viaWebGPU) return viaWebGPU;
+  const viaWebGL = encodeViaWebGL();
+  if (viaWebGL) return viaWebGL;
+  console.warn(
+    "[compressTexture] No compressed path available (WebGPU and WebGL2 both lack a usable compressed-texture format); returning uncompressed RGBA8."
+  );
+  const tex = wrapUncompressed(bitmap, srgb, flipY);
+  return {
+    texture: tex,
+    format: null,
+    fallbackUncompressed: true,
+    backend: "none",
+    astcNormalRemap: false,
+    width: bitmap.width,
+    height: bitmap.height,
+    mipLevels: 1,
+    encodeMs: 0,
+    destroy: () => {
+      tex.dispose();
+    }
+  };
+  async function encodeViaWebGPU() {
+    if (!("gpu" in navigator)) return null;
+    const adapter = providedAdapter ?? await navigator.gpu.requestAdapter();
+    if (!adapter) return null;
+    const selection = selectFormat(adapter, hint, { colorSpace });
+    if (!selection.format || !selection.encoderClass) return null;
+    let encoder;
+    if (providedDevice) {
+      const EncoderCtor = selection.encoderClass;
+      encoder = new EncoderCtor({ device: providedDevice, adapter, ownsDevice: false });
+    } else {
+      encoder = await selection.encoderClass.create();
+    }
+    try {
+      const needsWriteTexture = needsWriteTextureWorkaround(adapter);
+      if (!mipmaps) {
+        let bytes;
+        if (needsWriteTexture) {
+          const level02 = bitmapToMipLevel(bitmap, flipY);
+          const imageData = mipLevelToImageData(level02);
+          bytes = await encoder.encodeToBytes(imageData, { quality });
+        } else {
+          bytes = await encoder.encodeToBytes(bitmap, { flipY, quality });
+        }
+        const tex3 = encoder.buildMippedTexture([bytes], { colorSpace });
+        return {
+          texture: tex3,
+          format: selection.format,
+          fallbackUncompressed: false,
+          backend: "webgpu",
+          astcNormalRemap: selection.astcNormalRemap,
+          width: bytes.width,
+          height: bytes.height,
+          mipLevels: 1,
+          encodeMs: bytes.encodeMs,
+          destroy: () => {
+            tex3.dispose();
+            encoder.destroy();
+          }
+        };
       }
-    };
-  }
-  const adapter = providedAdapter ?? await navigator.gpu.requestAdapter();
-  if (!adapter) {
-    console.warn("[compressTexture] No WebGPU adapter; returning uncompressed RGBA8.");
-    const tex = wrapUncompressed(bitmap, srgb, flipY);
-    return {
-      texture: tex,
-      format: null,
-      fallbackUncompressed: true,
-      astcNormalRemap: false,
-      width: bitmap.width,
-      height: bitmap.height,
-      mipLevels: 1,
-      encodeMs: 0,
-      destroy: () => {
-        tex.dispose();
+      const level0 = bitmapToMipLevel(bitmap, flipY);
+      const chain = generateMipChain(level0);
+      const encodedLevels = [];
+      let totalEncodeMs = 0;
+      for (const level of chain) {
+        const padded = padToBlockMultiple(level);
+        const imageData = mipLevelToImageData(padded);
+        const bytes = await encoder.encodeToBytes(imageData, { quality });
+        encodedLevels.push(bytes);
+        totalEncodeMs += bytes.encodeMs;
       }
-    };
+      const tex2 = encoder.buildMippedTexture(encodedLevels, { colorSpace });
+      return {
+        texture: tex2,
+        format: selection.format,
+        fallbackUncompressed: false,
+        backend: "webgpu",
+        astcNormalRemap: selection.astcNormalRemap,
+        width: level0.width,
+        height: level0.height,
+        mipLevels: encodedLevels.length,
+        encodeMs: totalEncodeMs,
+        destroy: () => {
+          tex2.dispose();
+          encoder.destroy();
+        }
+      };
+    } catch (e) {
+      encoder.destroy();
+      throw e;
+    }
   }
-  const selection = selectFormat(adapter, hint, { colorSpace });
-  if (!selection.format || !selection.encoderClass) {
-    console.warn(
-      "[compressTexture] Adapter reports neither texture-compression-bc nor texture-compression-astc; returning uncompressed RGBA8."
-    );
-    const tex = wrapUncompressed(bitmap, srgb, flipY);
-    return {
-      texture: tex,
-      format: null,
-      fallbackUncompressed: true,
-      astcNormalRemap: false,
-      width: bitmap.width,
-      height: bitmap.height,
-      mipLevels: 1,
-      encodeMs: 0,
-      destroy: () => {
-        tex.dispose();
+  function encodeViaWebGL() {
+    const gl = getSharedWebGLContext();
+    if (!gl) return null;
+    const caps = detectWebGLCapabilities(gl);
+    const selection = selectWebGLFormat(caps, hint, { colorSpace });
+    if (!selection.format || !selection.encoderClass) return null;
+    const encoder = selection.encoderClass.create(gl);
+    try {
+      if (!mipmaps) {
+        const bytes = encoder.encodeToBytes(bitmap, { flipY });
+        const tex3 = encoder.buildMippedTexture([bytes], { colorSpace });
+        return {
+          texture: tex3,
+          format: selection.format,
+          fallbackUncompressed: false,
+          backend: "webgl",
+          astcNormalRemap: selection.astcNormalRemap,
+          width: bytes.width,
+          height: bytes.height,
+          mipLevels: 1,
+          encodeMs: bytes.encodeMs,
+          destroy: () => {
+            tex3.dispose();
+            encoder.destroy();
+          }
+        };
       }
-    };
-  }
-  let encoder;
-  if (providedDevice) {
-    const EncoderCtor = selection.encoderClass;
-    encoder = new EncoderCtor({ device: providedDevice, adapter, ownsDevice: false });
-  } else {
-    encoder = await selection.encoderClass.create();
-  }
-  try {
-    const needsWriteTexture = needsWriteTextureWorkaround(adapter);
-    if (!mipmaps) {
-      let bytes;
-      if (needsWriteTexture) {
-        const level02 = bitmapToMipLevel(bitmap, flipY);
-        const imageData = mipLevelToImageData(level02);
-        bytes = await encoder.encodeToBytes(imageData, { quality });
-      } else {
-        bytes = await encoder.encodeToBytes(bitmap, { flipY, quality });
+      const level0 = bitmapToMipLevel(bitmap, flipY);
+      const chain = generateMipChain(level0);
+      const encodedLevels = [];
+      let totalEncodeMs = 0;
+      for (const level of chain) {
+        const padded = padToBlockMultiple(level);
+        const bytes = encoder.encodeToBytes(padded);
+        encodedLevels.push(bytes);
+        totalEncodeMs += bytes.encodeMs;
       }
-      const tex2 = encoder.buildMippedTexture([bytes], { colorSpace });
+      const tex2 = encoder.buildMippedTexture(encodedLevels, { colorSpace });
       return {
         texture: tex2,
         format: selection.format,
         fallbackUncompressed: false,
+        backend: "webgl",
         astcNormalRemap: selection.astcNormalRemap,
-        width: bytes.width,
-        height: bytes.height,
-        mipLevels: 1,
-        encodeMs: bytes.encodeMs,
+        width: level0.width,
+        height: level0.height,
+        mipLevels: encodedLevels.length,
+        encodeMs: totalEncodeMs,
         destroy: () => {
           tex2.dispose();
           encoder.destroy();
         }
       };
+    } catch (e) {
+      encoder.destroy();
+      console.warn("[compressTexture] WebGL fallback encode failed; returning uncompressed RGBA8.", e);
+      return null;
     }
-    const level0 = bitmapToMipLevel(bitmap, flipY);
-    const chain = generateMipChain(level0);
-    const encodedLevels = [];
-    let totalEncodeMs = 0;
-    for (const level of chain) {
-      const padded = padToBlockMultiple(level);
-      const imageData = mipLevelToImageData(padded);
-      const bytes = await encoder.encodeToBytes(imageData, { quality });
-      encodedLevels.push(bytes);
-      totalEncodeMs += bytes.encodeMs;
-    }
-    const tex = encoder.buildMippedTexture(encodedLevels, { colorSpace });
-    return {
-      texture: tex,
-      format: selection.format,
-      fallbackUncompressed: false,
-      astcNormalRemap: selection.astcNormalRemap,
-      width: level0.width,
-      height: level0.height,
-      mipLevels: encodedLevels.length,
-      encodeMs: totalEncodeMs,
-      destroy: () => {
-        tex.dispose();
-        encoder.destroy();
-      }
-    };
-  } catch (e) {
-    encoder.destroy();
-    throw e;
   }
 }
 
@@ -913,6 +1324,7 @@ var GputexLoader = class extends Loader {
         result.texture.userData.gputex = {
           format: result.format,
           fallbackUncompressed: result.fallbackUncompressed,
+          backend: result.backend,
           astcNormalRemap: result.astcNormalRemap,
           width: result.width,
           height: result.height,
@@ -933,16 +1345,26 @@ var GputexLoader = class extends Loader {
 };
 export {
   ASTC4x4Encoder,
+  ASTC4x4WebGLEncoder,
   BC1Encoder,
+  BC1WebGLEncoder,
   BC5Encoder,
+  BC5WebGLEncoder,
   BC7Encoder,
+  BC7WebGLEncoder,
   Encoder,
   GputexLoader,
   TextureFormat,
+  WebGLBlockEncoder,
   WebGPUFeature,
   compressTexture,
+  createWebGLContext,
   detectCapabilities,
+  detectWebGLCapabilities,
   generateMipChain,
+  getSharedWebGLContext,
+  isWebGLAvailable,
   padToBlockMultiple,
-  selectFormat
+  selectFormat,
+  selectWebGLFormat
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gputex",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "files": [
     "dist"