gputex 0.1.0 → 0.1.2

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

@@ -48,8 +48,9 @@ interface EncoderOptions {
 /**
  * Encoder quality level. 'fast' (default) uses the cheaper search paths in the
  * shaders — measured ~2–4× faster for ≤0.36 dB PSNR. 'high' runs the exhaustive
- * search, producing output byte-identical to the CPU reference encoders.
- * No effect on BC1 (already single-pass; both levels are identical).
+ * search, producing output byte-identical to the CPU reference encoders (BC5/
+ * BC7/ASTC). BC1's 'high' adds a principal-axis endpoint seed and iterative
+ * refit on top of the 'fast' bbox+refit path.
  */
 type EncodeQuality = 'fast' | 'high';
 interface EncodeCallOptions {
@@ -142,8 +143,8 @@ declare abstract class Encoder {
     get supportsSrgb(): boolean;
     /**
      * Whether the shader declares a `QUALITY_HIGH` pipeline-overridable constant
-     * (i.e. has distinct fast/high search paths). BC1 is already single-pass and
-     * leaves this false; BC5/BC7/ASTC override it to true.
+     * (i.e. has distinct fast/high search paths). Default false (e.g. a stub or a
+     * format with a single path); BC1/BC5/BC7/ASTC override it to true.
      */
     get supportsQuality(): boolean;
     /**
@@ -200,6 +201,7 @@ declare class BC1Encoder extends Encoder {
     get label(): string;
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
+    get supportsQuality(): boolean;
     wgslSource(): string;
     gpuTextureFormat({ colorSpace }: FormatVariant): GPUTextureFormat;
     threeTextureFormat(): CompressedPixelFormat;
@@ -244,6 +246,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 +428,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 +456,29 @@ 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; for BC1, a principal-axis seed + iterative
+     * refit). No effect 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 +553,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) {
@@ -189,8 +214,8 @@ var Encoder = class {
   }
   /**
    * Whether the shader declares a `QUALITY_HIGH` pipeline-overridable constant
-   * (i.e. has distinct fast/high search paths). BC1 is already single-pass and
-   * leaves this false; BC5/BC7/ASTC override it to true.
+   * (i.e. has distinct fast/high search paths). Default false (e.g. a stub or a
+   * format with a single path); BC1/BC5/BC7/ASTC override it to true.
    */
   get supportsQuality() {
     return false;
@@ -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);
   }
 };
 
@@ -365,7 +374,7 @@ var Encoder = class {
 import { RGBA_S3TC_DXT1_Format } from "three";
 
 // src/bc1.wgsl
-var bc1_default = "// BC1 (DXT1) compute shader encoder.\n//\n// Each invocation encodes one 4x4 pixel block into an 8-byte BC1 block\n// written as 2 x u32 into the destination storage buffer.\n//\n// BC1 block layout (little-endian):\n//   u32[0]: color0 (low 16) | color1 (high 16)   both in RGB565\n//   u32[1]: 16 x 2-bit indices, pixel 0 = bits 0..1, pixel 15 = bits 30..31\n//\n// When color0 > color1 (numeric 16-bit), the 4-color mode is used:\n//   idx 0 -> color0\n//   idx 1 -> color1\n//   idx 2 -> (2*color0 +   color1) / 3\n//   idx 3 -> (  color0 + 2*color1) / 3\n// We always force the 4-color mode here.\n//\n// Algorithm:\n//  1. Compute the bounding box (min/max RGB) of the block.\n//  2. Inset slightly to account for endpoint quantization rounding;\n//     this is a well-known heuristic from rygorous/stb_dxt that\n//     improves quality cheaply.\n//  3. Quantize endpoints to RGB565 and ensure color0 > color1.\n//  4. Reconstruct the 4-color palette in floating point and assign\n//     the closest palette entry to each pixel (full L2 search).\n\nstruct Params {\n  blocks_x: u32,\n  blocks_y: u32,\n  width:    u32,\n  height:   u32,\n};\n\n@group(0) @binding(0) var src_tex: texture_2d<f32>;\n@group(0) @binding(1) var<storage, read_write> dst: array<u32>;\n@group(0) @binding(2) var<uniform> params: Params;\n\nfn to565(c: vec3<f32>) -> u32 {\n  // Round-to-nearest quantization into 5-6-5.\n  let r = u32(clamp(floor(c.r * 31.0 + 0.5), 0.0, 31.0));\n  let g = u32(clamp(floor(c.g * 63.0 + 0.5), 0.0, 63.0));\n  let b = u32(clamp(floor(c.b * 31.0 + 0.5), 0.0, 31.0));\n  return (r << 11u) | (g << 5u) | b;\n}\n\nfn from565(c: u32) -> vec3<f32> {\n  let r = f32((c >> 11u) & 31u);\n  let g = f32((c >>  5u) & 63u);\n  let b = f32( c         & 31u);\n  // Expand to 8-bit then normalize, matching typical BC1 decoder behavior.\n  let r8 = (r * 527.0 + 23.0) / 256.0;   // = round(r * 255 / 31)\n  let g8 = (g * 259.0 + 33.0) / 256.0;   // = round(g * 255 / 63)\n  let b8 = (b * 527.0 + 23.0) / 256.0;\n  return vec3<f32>(r8, g8, b8) / 255.0;\n}\n\n@compute @workgroup_size(8, 8, 1)\nfn encode(@builtin(global_invocation_id) gid: vec3<u32>) {\n  if (gid.x >= params.blocks_x || gid.y >= params.blocks_y) {\n    return;\n  }\n\n  let bx = gid.x;\n  let by = gid.y;\n  let block_index = by * params.blocks_x + bx;\n\n  let base = vec2<i32>(i32(bx) * 4, i32(by) * 4);\n  let max_xy = vec2<i32>(i32(params.width) - 1, i32(params.height) - 1);\n\n  var pixels: array<vec3<f32>, 16>;\n  var bb_min = vec3<f32>(1.0, 1.0, 1.0);\n  var bb_max = vec3<f32>(0.0, 0.0, 0.0);\n\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    let lx = i32(i & 3u);\n    let ly = i32(i >> 2u);\n    // Clamp to edge for non-multiple-of-4 textures.\n    let p  = clamp(base + vec2<i32>(lx, ly), vec2<i32>(0, 0), max_xy);\n    let c  = textureLoad(src_tex, p, 0).rgb;\n    pixels[i] = c;\n    bb_min = min(bb_min, c);\n    bb_max = max(bb_max, c);\n  }\n\n  // Inset the bounding box. The magic constant 1/16 approximates half\n  // the width of an RGB565 quantization cell; insetting by that much\n  // moves the endpoints toward each other so the quantized 4-color\n  // palette covers the real data range more tightly.\n  let inset = (bb_max - bb_min) / 16.0;\n  var hi = clamp(bb_max - inset, vec3<f32>(0.0), vec3<f32>(1.0));\n  var lo = clamp(bb_min + inset, vec3<f32>(0.0), vec3<f32>(1.0));\n\n  var c0 = to565(hi);\n  var c1 = to565(lo);\n\n  // 4-color mode requires c0 > c1. If equal (flat block), we still use\n  // 4-color mode by nudging c1 down when possible; if c1 == 0 the block\n  // is truly black so all indices stay 0 and the decoded value is 0.\n  if (c0 == c1) {\n    if (c1 > 0u) {\n      c1 = c1 - 1u;\n    } else {\n      c0 = c0 + 1u;\n    }\n  } else if (c0 < c1) {\n    let tmp = c0;\n    c0 = c1;\n    c1 = tmp;\n  }\n\n  // Build the palette in the decoded colour space so index selection\n  // matches what the hardware decoder will produce.\n  let p0 = from565(c0);\n  let p1 = from565(c1);\n  let p2 = (2.0 * p0 + p1) * (1.0 / 3.0);\n  let p3 = (p0 + 2.0 * p1) * (1.0 / 3.0);\n\n  var indices: u32 = 0u;\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    let c = pixels[i];\n    let d0 = dot(c - p0, c - p0);\n    let d1 = dot(c - p1, c - p1);\n    let d2 = dot(c - p2, c - p2);\n    let d3 = dot(c - p3, c - p3);\n\n    var best_d: f32 = d0;\n    var best_i: u32 = 0u;\n    if (d1 < best_d) { best_d = d1; best_i = 1u; }\n    if (d2 < best_d) { best_d = d2; best_i = 2u; }\n    if (d3 < best_d) { best_d = d3; best_i = 3u; }\n\n    indices = indices | (best_i << (i * 2u));\n  }\n\n  let out = block_index * 2u;\n  dst[out]      = c0 | (c1 << 16u);\n  dst[out + 1u] = indices;\n}\n";
+var bc1_default = "// BC1 (DXT1) compute shader encoder.\n//\n// Each invocation encodes one 4x4 pixel block into an 8-byte BC1 block\n// written as 2 x u32 into the destination storage buffer.\n//\n// BC1 block layout (little-endian):\n//   u32[0]: color0 (low 16) | color1 (high 16)   both in RGB565\n//   u32[1]: 16 x 2-bit indices, pixel 0 = bits 0..1, pixel 15 = bits 30..31\n//\n// We always force the 4-color mode (color0 > color1, numeric 16-bit):\n//   idx 0 -> color0\n//   idx 1 -> color1\n//   idx 2 -> (2*color0 +   color1) / 3\n//   idx 3 -> (  color0 + 2*color1) / 3\n//\n// QUALITY LEVELS (pipeline-overridable constant `QUALITY_HIGH`)\n//   fast (0, default): bounding-box endpoints, inset by ~half a 565 cell, then\n//     a single least-squares endpoint refit (the refit is accepted only if it\n//     lowers the block's squared error). This is what the WebGL2 fragment\n//     fallback runs too.\n//   high (1): endpoints are seeded from the block's principal colour axis\n//     (covariance power-iteration) as well as the bbox diagonal, each refined by\n//     several least-squares passes; the lower-error family wins. Mirrors\n//     bc1_ref.ts. Strictly \u2265 fast in quality, at the cost of the eigen-solve.\n//\n// Algorithm per block:\n//  1. Load the 16 pixels; compute the bounding box (and, for high, the mean).\n//  2. Seed endpoints (bbox diagonal; high also tries the principal axis).\n//  3. Quantize to RGB565, force 4-color mode, assign each pixel its nearest\n//     palette entry (full 4-entry L2 search in the decoded colour space).\n//  4. Least-squares refit: re-solve the endpoints for the current indices,\n//     re-quantize, re-assign; keep the result only when error decreases.\n\n// 0 = fast (default), 1 = high-quality. Set via pipeline constants.\noverride QUALITY_HIGH: u32 = 0u;\n\nstruct Params {\n  blocks_x: u32,\n  blocks_y: u32,\n  width:    u32,\n  height:   u32,\n};\n\n@group(0) @binding(0) var src_tex: texture_2d<f32>;\n@group(0) @binding(1) var<storage, read_write> dst: array<u32>;\n@group(0) @binding(2) var<uniform> params: Params;\n\nfn to565(c: vec3<f32>) -> u32 {\n  // Round-to-nearest quantization into 5-6-5.\n  let r = u32(clamp(floor(c.r * 31.0 + 0.5), 0.0, 31.0));\n  let g = u32(clamp(floor(c.g * 63.0 + 0.5), 0.0, 63.0));\n  let b = u32(clamp(floor(c.b * 31.0 + 0.5), 0.0, 31.0));\n  return (r << 11u) | (g << 5u) | b;\n}\n\nfn from565(c: u32) -> vec3<f32> {\n  let r = f32((c >> 11u) & 31u);\n  let g = f32((c >>  5u) & 63u);\n  let b = f32( c         & 31u);\n  // 5/6-bit -> 8-bit. floor((x*527+23)/64) == (x<<3)|(x>>2), i.e. the exact\n  // bit-replication a BC1 decoder performs (white -> 255). The inputs are\n  // small integers and /64 is exact in f32, so this matches the hardware and\n  // is portable. Selecting indices against this palette is what makes the\n  // encoder agree with what the GPU will actually sample.\n  let r8 = floor((r * 527.0 + 23.0) / 64.0);\n  let g8 = floor((g * 259.0 + 33.0) / 64.0);\n  let b8 = floor((b * 527.0 + 23.0) / 64.0);\n  return vec3<f32>(r8, g8, b8) / 255.0;\n}\n\n// 4-color-mode interpolation weights: palette[j] = wa(j)*c0 + wb(j)*c1.\nfn wa(j: u32) -> f32 {\n  switch j {\n    case 0u:  { return 1.0; }\n    case 1u:  { return 0.0; }\n    case 2u:  { return 2.0 / 3.0; }\n    default:  { return 1.0 / 3.0; }   // case 3u\n  }\n}\nfn wb(j: u32) -> f32 {\n  switch j {\n    case 0u:  { return 0.0; }\n    case 1u:  { return 1.0; }\n    case 2u:  { return 1.0 / 3.0; }\n    default:  { return 2.0 / 3.0; }   // case 3u\n  }\n}\n\nfn build_palette(c0: u32, c1: u32, pal: ptr<function, array<vec3<f32>, 4>>) {\n  let p0 = from565(c0);\n  let p1 = from565(c1);\n  for (var j: u32 = 0u; j < 4u; j = j + 1u) {\n    (*pal)[j] = wa(j) * p0 + wb(j) * p1;\n  }\n}\n\n// Assign each of the 16 pixels its nearest palette entry (full 4-entry L2),\n// writing indices into `out_idx` and returning the total squared error.\nfn assign_indices(\n  pixels:  ptr<function, array<vec3<f32>, 16>>,\n  pal:     ptr<function, array<vec3<f32>, 4>>,\n  out_idx: ptr<function, array<u32, 16>>,\n) -> f32 {\n  var err: f32 = 0.0;\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let c = (*pixels)[k];\n    var best_j: u32 = 0u;\n    var best_d: f32 = 1e30;\n    for (var j: u32 = 0u; j < 4u; j = j + 1u) {\n      let d = (*pal)[j] - c;\n      let d2 = dot(d, d);\n      if (d2 < best_d) {\n        best_d = d2;\n        best_j = j;\n      }\n    }\n    (*out_idx)[k] = best_j;\n    err = err + best_d;\n  }\n  return err;\n}\n\n// One least-squares refit pass: solve the 2x2 normal equations for the endpoint\n// colours that minimise \u03A3\u2016wa\xB7e0 + wb\xB7e1 \u2212 c\u2016\xB2 under the current indices. The\n// three channels share the scalar sums, so it's one 2x2 solve with vec3 RHS.\nstruct RefitResult { e0: vec3<f32>, e1: vec3<f32>, valid: bool };\nfn refit(\n  pixels:  ptr<function, array<vec3<f32>, 16>>,\n  indices: ptr<function, array<u32, 16>>,\n) -> RefitResult {\n  var sAA: f32 = 0.0; var sBB: f32 = 0.0; var sAB: f32 = 0.0;\n  var sAV: vec3<f32> = vec3<f32>(0.0);\n  var sBV: vec3<f32> = vec3<f32>(0.0);\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let a = wa((*indices)[k]);\n    let b = wb((*indices)[k]);\n    let v = (*pixels)[k];\n    sAA = sAA + a * a;\n    sBB = sBB + b * b;\n    sAB = sAB + a * b;\n    sAV = sAV + a * v;\n    sBV = sBV + b * v;\n  }\n  var out: RefitResult;\n  let det = sAA * sBB - sAB * sAB;\n  if (abs(det) < 1e-9) {\n    out.valid = false;\n    return out;\n  }\n  out.e0 = clamp((sBB * sAV - sAB * sBV) / det, vec3<f32>(0.0), vec3<f32>(1.0));\n  out.e1 = clamp((sAA * sBV - sAB * sAV) / det, vec3<f32>(0.0), vec3<f32>(1.0));\n  out.valid = true;\n  return out;\n}\n\n// Candidate solution tracked across endpoint seeds / refit passes.\nstruct Best { c0: u32, c1: u32, indices: array<u32, 16>, err: f32 };\n\n// Quantize (hi, lo) to 565, force 4-color mode, assign indices, then refine with\n// up to `max_refits` least-squares passes. Commits to `*best` only on strict\n// improvement.\nfn fit_from_endpoints(\n  pixels: ptr<function, array<vec3<f32>, 16>>,\n  hi: vec3<f32>,\n  lo: vec3<f32>,\n  max_refits: u32,\n  best: ptr<function, Best>,\n) {\n  var c0 = to565(hi);\n  var c1 = to565(lo);\n  // 4-color mode requires color0 > color1.\n  if (c0 == c1) {\n    if (c1 > 0u) { c1 = c1 - 1u; } else { c0 = c0 + 1u; }\n  } else if (c0 < c1) {\n    let t = c0; c0 = c1; c1 = t;\n  }\n\n  var pal: array<vec3<f32>, 4>;\n  var idx: array<u32, 16>;\n  build_palette(c0, c1, &pal);\n  var err = assign_indices(pixels, &pal, &idx);\n  if (err < (*best).err) {\n    (*best).c0 = c0; (*best).c1 = c1; (*best).indices = idx; (*best).err = err;\n  }\n\n  for (var rp: u32 = 0u; rp < max_refits; rp = rp + 1u) {\n    let r = refit(pixels, &idx);\n    if (!r.valid) { break; }\n    var nc0 = to565(r.e0);\n    var nc1 = to565(r.e1);\n    // A refit that flips/equalises the endpoints would change decode mode;\n    // keep 4-color mode, and stop once it stops moving.\n    if (nc0 < nc1) { let t = nc0; nc0 = nc1; nc1 = t; }\n    if (nc0 == nc1) { break; }\n    if (nc0 == c0 && nc1 == c1) { break; }\n    build_palette(nc0, nc1, &pal);\n    let nerr = assign_indices(pixels, &pal, &idx);\n    c0 = nc0; c1 = nc1; err = nerr;\n    if (nerr < (*best).err) {\n      (*best).c0 = nc0; (*best).c1 = nc1; (*best).indices = idx; (*best).err = nerr;\n    }\n  }\n}\n\n// Principal colour axis via covariance power-iteration, seeded with the bbox\n// diagonal. Returns a unit axis, or vec3(0) for a degenerate (constant) block.\nfn principal_axis(\n  pixels: ptr<function, array<vec3<f32>, 16>>,\n  mean: vec3<f32>,\n  seed: vec3<f32>,\n) -> vec3<f32> {\n  // Symmetric 3x3 covariance, stored as its three rows.\n  var c0v = vec3<f32>(0.0);\n  var c1v = vec3<f32>(0.0);\n  var c2v = vec3<f32>(0.0);\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let d = (*pixels)[k] - mean;\n    c0v = c0v + d.x * d;\n    c1v = c1v + d.y * d;\n    c2v = c2v + d.z * d;\n  }\n  var v = seed;\n  var len = length(v);\n  if (len < 1e-9) { return vec3<f32>(0.0); }\n  v = v / len;\n  for (var iter: u32 = 0u; iter < 8u; iter = iter + 1u) {\n    let nv = vec3<f32>(dot(c0v, v), dot(c1v, v), dot(c2v, v));\n    len = length(nv);\n    if (len < 1e-12) { return vec3<f32>(0.0); }\n    v = nv / len;\n  }\n  return v;\n}\n\n@compute @workgroup_size(8, 8, 1)\nfn encode(@builtin(global_invocation_id) gid: vec3<u32>) {\n  if (gid.x >= params.blocks_x || gid.y >= params.blocks_y) {\n    return;\n  }\n\n  let bx = gid.x;\n  let by = gid.y;\n  let block_index = by * params.blocks_x + bx;\n\n  let base = vec2<i32>(i32(bx) * 4, i32(by) * 4);\n  let max_xy = vec2<i32>(i32(params.width) - 1, i32(params.height) - 1);\n\n  var pixels: array<vec3<f32>, 16>;\n  var bb_min = vec3<f32>(1.0, 1.0, 1.0);\n  var bb_max = vec3<f32>(0.0, 0.0, 0.0);\n  var mean = vec3<f32>(0.0);\n\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    let lx = i32(i & 3u);\n    let ly = i32(i >> 2u);\n    // Clamp to edge for non-multiple-of-4 textures.\n    let p  = clamp(base + vec2<i32>(lx, ly), vec2<i32>(0, 0), max_xy);\n    let c  = textureLoad(src_tex, p, 0).rgb;\n    pixels[i] = c;\n    bb_min = min(bb_min, c);\n    bb_max = max(bb_max, c);\n    mean = mean + c;\n  }\n  mean = mean * (1.0 / 16.0);\n\n  // Inset the bounding box by ~half an RGB565 cell (1/16) so the quantized\n  // 4-color palette covers the real data range more tightly (stb_dxt heuristic).\n  let inset = (bb_max - bb_min) / 16.0;\n  let bbox_hi = clamp(bb_max - inset, vec3<f32>(0.0), vec3<f32>(1.0));\n  let bbox_lo = clamp(bb_min + inset, vec3<f32>(0.0), vec3<f32>(1.0));\n\n  var best: Best;\n  best.err = 1e30;\n\n  if (QUALITY_HIGH != 0u) {\n    // Seed from the principal colour axis: project all texels onto it, take the\n    // extreme projections as endpoints, inset along the axis. Then also try the\n    // bbox seed and keep whichever family yields the lower error.\n    let axis = principal_axis(&pixels, mean, bb_max - bb_min);\n    if (dot(axis, axis) > 0.0) {\n      var t_min: f32 = 1e30;\n      var t_max: f32 = -1e30;\n      for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n        let t = dot(pixels[k] - mean, axis);\n        t_min = min(t_min, t);\n        t_max = max(t_max, t);\n      }\n      let pad = (t_max - t_min) / 16.0;\n      let pca_hi = clamp(mean + (t_max - pad) * axis, vec3<f32>(0.0), vec3<f32>(1.0));\n      let pca_lo = clamp(mean + (t_min + pad) * axis, vec3<f32>(0.0), vec3<f32>(1.0));\n      fit_from_endpoints(&pixels, pca_hi, pca_lo, 3u, &best);\n    }\n    fit_from_endpoints(&pixels, bbox_hi, bbox_lo, 3u, &best);\n  } else {\n    fit_from_endpoints(&pixels, bbox_hi, bbox_lo, 1u, &best);\n  }\n\n  var indices: u32 = 0u;\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    indices = indices | ((best.indices[k] & 3u) << (k * 2u));\n  }\n\n  let out = block_index * 2u;\n  dst[out]      = best.c0 | (best.c1 << 16u);\n  dst[out + 1u] = indices;\n}\n";
 
 // src/BC1Encoder.ts
 var BC1Encoder = class extends Encoder {
@@ -380,6 +389,9 @@ var BC1Encoder = class extends Encoder {
   get supportsSrgb() {
     return true;
   }
+  get supportsQuality() {
+    return true;
+  }
   wgslSource() {
     return bc1_default;
   }
@@ -585,6 +597,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 (fast path).\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. This is the *fast* path only (the WGSL\n// `QUALITY_HIGH == 0` branch): bbox endpoints, 1/16 inset, RGB565 quantisation,\n// forced 4-colour mode, full 4-entry L2 index search, then a single\n// least-squares endpoint refit accepted only when it lowers the block's error.\n// See bc1.wgsl for the full derivation.\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\n// 4-colour-mode interpolation weights: pal[j] = WA[j]*c0 + WB[j]*c1.\nconst float WA[4] = float[4](1.0, 0.0, 2.0 / 3.0, 1.0 / 3.0);\nconst float WB[4] = float[4](0.0, 1.0, 1.0 / 3.0, 2.0 / 3.0);\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  // 5/6-bit \u2192 8-bit. floor((x*527+23)/64) == (x<<3)|(x>>2): exact hardware\n  // bit-replication (white \u2192 255), so index selection matches the GPU decode.\n  float r8 = floor((r * 527.0 + 23.0) / 64.0);\n  float g8 = floor((g * 259.0 + 33.0) / 64.0);\n  float b8 = floor((b * 527.0 + 23.0) / 64.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 bbox by ~half an RGB565 cell (1/16) to tighten the quantised\n  // 4-colour 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  // 4-colour mode requires color0 > color1.\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  // Build the palette in decoded space, assign each pixel its nearest entry.\n  vec3 pal[4];\n  vec3 p0 = from565(c0);\n  vec3 p1 = from565(c1);\n  for (int j = 0; j < 4; j++) pal[j] = WA[j] * p0 + WB[j] * p1;\n\n  uint idx[16];\n  float err = 0.0;\n  for (int k = 0; k < 16; k++) {\n    vec3 c = pixels[k];\n    uint bestJ = 0u;\n    float bestD = 1e30;\n    for (int j = 0; j < 4; j++) {\n      vec3 d = pal[j] - c;\n      float d2 = dot(d, d);\n      if (d2 < bestD) { bestD = d2; bestJ = uint(j); }\n    }\n    idx[k] = bestJ;\n    err += bestD;\n  }\n\n  // One least-squares refit: re-solve the endpoints for the current indices,\n  // re-quantise, re-assign; keep it only if the squared error drops.\n  float sAA = 0.0, sBB = 0.0, sAB = 0.0;\n  vec3 sAV = vec3(0.0), sBV = vec3(0.0);\n  for (int k = 0; k < 16; k++) {\n    float a = WA[int(idx[k])];\n    float b = WB[int(idx[k])];\n    vec3 v = pixels[k];\n    sAA += a * a; sBB += b * b; sAB += a * b; sAV += a * v; sBV += b * v;\n  }\n  float det = sAA * sBB - sAB * sAB;\n  if (abs(det) > 1e-9) {\n    vec3 e0 = clamp((sBB * sAV - sAB * sBV) / det, vec3(0.0), vec3(1.0));\n    vec3 e1 = clamp((sAA * sBV - sAB * sAV) / det, vec3(0.0), vec3(1.0));\n    uint nc0 = to565(e0);\n    uint nc1 = to565(e1);\n    if (nc0 < nc1) { uint t = nc0; nc0 = nc1; nc1 = t; }\n    if (nc0 != nc1 && !(nc0 == c0 && nc1 == c1)) {\n      vec3 q0 = from565(nc0);\n      vec3 q1 = from565(nc1);\n      vec3 pal2[4];\n      for (int j = 0; j < 4; j++) pal2[j] = WA[j] * q0 + WB[j] * q1;\n      uint idx2[16];\n      float nerr = 0.0;\n      for (int k = 0; k < 16; k++) {\n        vec3 c = pixels[k];\n        uint bestJ = 0u;\n        float bestD = 1e30;\n        for (int j = 0; j < 4; j++) {\n          vec3 d = pal2[j] - c;\n          float d2 = dot(d, d);\n          if (d2 < bestD) { bestD = d2; bestJ = uint(j); }\n        }\n        idx2[k] = bestJ;\n        nerr += bestD;\n      }\n      if (nerr < err) {\n        c0 = nc0; c1 = nc1;\n        for (int k = 0; k < 16; k++) idx[k] = idx2[k];\n      }\n    }\n  }\n\n  uint indices = 0u;\n  for (int k = 0; k < 16; k++) indices |= (idx[k] & 3u) << (uint(k) * 2u);\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 +991,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 +1101,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 +1122,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 +1327,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 +1348,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.2",
   "license": "MIT",
   "files": [
     "dist"