webgl-gate 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+# webgl-gate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skip your WebGL bundle when the page is drawn by the CPU.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Alexkutsenko95/webgl-gate/main/assets/webgl-gate-card.png" width="600" alt="Probe time in headless Chrome: 10 to 24 ms on a real GPU, so the scene loads; 1.4 to 1.7 s on SwiftShader, the CPU rasterizer PageSpeed uses, so the scene bundle is never downloaded.">
+</p>
+
+Lighthouse and PageSpeed Insights measure mobile pages on **SwiftShader**, a software rasterizer. So do many
+virtual machines and remote desktops, and so does any browser with hardware acceleration switched off. There a
+PixiJS or three.js scene doesn't just run slowly. Downloading and parsing its bundle alone costs main-thread time,
+and your Total Blocking Time goes with it. `webgl-gate` answers one question before you load that bundle: **is
+there a real GPU behind this page?**
+
+- **Under 1 kB:** 745 B gzip for the core, 223 B for the React hook.
+- **No network, no benchmark tables, no dependencies.**
+- **Checks the renderer name, not only `failIfMajorPerformanceCaveat`.** Headless Chrome on SwiftShader still hands
+  out a context with that flag set.
+- **Off the critical path:** probes after `load`, when the browser is idle.
+
+## Install
+
+```bash
+npm install webgl-gate
+```
+
+## Use
+
+Load the scene only on a real GPU. On the CPU the import is never called, so the bundle is never downloaded:
+
+```ts
+import { loadIfFastWebGL } from 'webgl-gate';
+
+const scene = await loadIfFastWebGL(() => import('./scene'));
+if (scene) scene.mount(canvas);
+// otherwise keep the static image that is already on the page
+```
+
+With React (SSR-safe: `null` on the server and on the first client render, so hydration matches):
+
+```tsx
+import { useFastWebGL } from 'webgl-gate/react';
+
+export function Hero() {
+  const fast = useFastWebGL();
+  return fast ? <LiveScene /> : <img src="/hero.avif" alt="" width={1200} height={630} />;
+}
+```
+
+`LiveScene` should itself be lazy (`next/dynamic`, `React.lazy`), so its WebGL code stays in a separate chunk.
+
+## Where it helps
+
+Anything heavy that only looks good on a GPU and has a cheap static fallback:
+
+- **Hero and background effects:** shaders, particles, animated gradients. Show the poster frame instead.
+- **Game covers and playable demos** on a landing page (where this gate came from). Show a screenshot.
+- **3D product viewers and configurators** (three.js, Babylon.js). Show product photos.
+- **WebGL maps** (MapLibre GL, Mapbox GL). Show a static map image with a "open map" link.
+- **GPU data visualisation** (deck.gl, regl). Show a pre-rendered chart.
+
+## Recipes
+
+### PixiJS or three.js, any framework
+
+Keep the engine import inside the scene module, so the bundler puts it in its own chunk:
+
+```ts
+// scene.ts
+import { Application } from 'pixi.js'; // or: import * as THREE from 'three'
+export async function mount(host: HTMLElement) { /* create the app, append its canvas to host */ }
+```
+
+```ts
+// main.ts
+import { loadIfFastWebGL } from 'webgl-gate';
+
+const scene = await loadIfFastWebGL(() => import('./scene'));
+if (scene) await scene.mount(document.querySelector('#hero')!);
+```
+
+### Next.js (App Router)
+
+```tsx
+'use client';
+import dynamic from 'next/dynamic';
+import Image from 'next/image';
+import { useFastWebGL } from 'webgl-gate/react';
+
+const LiveCover = dynamic(() => import('./LiveCover'), { ssr: false });
+
+export function Cover() {
+  const fast = useFastWebGL();
+  return fast ? <LiveCover /> : <Image src="/cover.avif" alt="" width={1200} height={630} priority />;
+}
+```
+
+The static image is the Largest Contentful Paint on every device; the live cover replaces it only on a real GPU,
+after the page has loaded.
+
+### React Three Fiber
+
+```tsx
+import { lazy, Suspense } from 'react';
+import { useFastWebGL } from 'webgl-gate/react';
+
+const Scene3D = lazy(() => import('./Scene3D')); // the file that imports @react-three/fiber
+
+export function Viewer() {
+  const fast = useFastWebGL();
+  const poster = <img src="/product.avif" alt="Product" width={800} height={800} />;
+  return fast ? <Suspense fallback={poster}><Scene3D /></Suspense> : poster;
+}
+```
+
+### Vue 3
+
+```vue
+<script setup lang="ts">
+import { defineAsyncComponent, onMounted, ref } from 'vue';
+import { probeWebGLWhenIdle } from 'webgl-gate';
+
+const LiveScene = defineAsyncComponent(() => import('./LiveScene.vue'));
+const fast = ref(false);
+onMounted(async () => { fast.value = (await probeWebGLWhenIdle()).fast; });
+</script>
+
+<template>
+  <LiveScene v-if="fast" />
+  <img v-else src="/hero.avif" alt="" width="1200" height="630" />
+</template>
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  import { loadIfFastWebGL } from 'webgl-gate';
+
+  let Scene = null;
+  onMount(async () => { Scene = (await loadIfFastWebGL(() => import('./Scene.svelte')))?.default ?? null; });
+</script>
+
+{#if Scene}<svelte:component this={Scene} />{:else}<img src="/hero.avif" alt="" width="1200" height="630" />{/if}
+```
+
+### MapLibre GL
+
+```ts
+import { loadIfFastWebGL } from 'webgl-gate';
+
+const maplibre = (await loadIfFastWebGL(() => import('maplibre-gl')))?.default;
+if (maplibre) new maplibre.Map({ container: 'map', style: '/style.json', center: [30.52, 50.45], zoom: 11 });
+// otherwise the <img> of the static map stays in #map
+```
+
+### API
+
+| Export | What it does |
+|---|---|
+| `loadIfFastWebGL(load)` | Waits for an idle moment after `load`, then calls `load()` only on a real GPU. Returns the module or `null`. |
+| `probeWebGLWhenIdle(timeout?)` | The verdict, `{ fast, reason, renderer }`, probed after `load` in `requestIdleCallback`. |
+| `probeWebGL()` | The same verdict, synchronously. Memoized: one probe per page. On the server returns `fast: false` without caching. |
+| `hasFastWebGL()` | `probeWebGL().fast`. |
+| `isSoftwareRenderer(gl)`, `rendererName(gl)` | For a context you already have. |
+| `SOFTWARE_RENDERER` | The regular expression: SwiftShader, llvmpipe, softpipe, "Software", "Basic Render". |
+| `resetWebGLProbe()` | Forget the memoized verdict. |
+
+`reason` is one of `gpu`, `software` (a context exists but the CPU draws it), `no-context` (WebGL is off or blocked,
+or the browser reported a major performance caveat), `error`, `no-dom` (server).
+
+## What it costs, measured
+
+The same page in headless Chrome 155 on an Apple M2 Pro, three runs each:
+
+| Renderer | Verdict | Probe time | Scene bundle requested |
+|---|---|---|---|
+| ANGLE Metal (Apple M2 Pro) | `gpu` | 10–24 ms | yes |
+| ANGLE SwiftShader (`--use-angle=swiftshader`) | `software` | 1.41–1.73 s | **no** |
+
+Read the second row carefully. On a CPU rasterizer, creating even one WebGL context is expensive, and that is
+exactly where the answer is "no". That is why the default entry points wait for `load` and an idle callback
+instead of probing during page load. If you call the synchronous `probeWebGL()` yourself, keep it off the critical
+path too.
+
+## Where it came from
+
+This is the gate from [kutsikgames.com](https://kutsikgames.com), a game studio site with live PixiJS covers.
+Together with inlined critical CSS and responsive AVIF covers, it took the site's mobile PageSpeed score from 78
+(LCP 4.2 s) to 100 (LCP 1.7 s, TBT 0 ms). The gate is one of those changes, not all of them.
+
+## When to use something else
+
+`webgl-gate` answers "GPU or not". If you need to know *how strong* the GPU is, to pick quality tiers,
+use [`detect-gpu`](https://github.com/pmndrs/detect-gpu): it classifies GPUs by benchmark scores and is much larger.
+
+Browsers that hide the real renderer name (fingerprinting protection) may report a generic one,
+so the gate sees a GPU. If that matters to you, time a real frame of your scene after mounting and fall back when
+it is too slow.
+
+## Not yet
+
+The verdict is not cached across visits. A cached "software" answer can outlive the hardware it describes: the
+user turns hardware acceleration back on, or a driver leaves a blocklist. Audit tools always start with a clean
+profile anyway.
+
+## License
+
+MIT © Oleksandr Kutsenko

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * webgl-gate: decide, before you download a WebGL bundle, whether this page is drawn by a real GPU.
+ *
+ * Software rasterizers (SwiftShader, llvmpipe, softpipe, "Microsoft Basic Render Driver") run WebGL on the CPU.
+ * Lighthouse and PageSpeed Insights measure mobile pages on exactly that kind of renderer, and so do many
+ * virtual machines, remote desktops and browsers with hardware acceleration turned off. There a WebGL scene
+ * costs main-thread time and Total Blocking Time, and the user gets a slideshow instead of an effect.
+ *
+ * `failIfMajorPerformanceCaveat` is not enough on its own: headless Chrome with SwiftShader still hands out a
+ * context with that flag set. So the verdict also reads the renderer name.
+ */
+/** Renderer names of known CPU rasterizers. */
+export declare const SOFTWARE_RENDERER: RegExp;
+type TGL = WebGLRenderingContext | WebGL2RenderingContext;
+/** The most specific renderer name the browser exposes: unmasked when allowed, otherwise `RENDERER`. */
+export declare function rendererName(gl: TGL): string;
+/** True when this context is rasterized on the CPU. */
+export declare function isSoftwareRenderer(gl: TGL): boolean;
+/**
+ * Why the gate decided as it did. `no-context`: WebGL is off or blocked, or the browser itself reported a major
+ * performance caveat. `software`: a context exists, but a CPU rasterizer draws it.
+ */
+export type TGateReason = 'no-dom' | 'no-context' | 'software' | 'error' | 'gpu';
+export interface IGateResult {
+    /** A real GPU draws this page: loading the WebGL bundle is worth it. */
+    readonly fast: boolean;
+    readonly reason: TGateReason;
+    /** Renderer name, when a context was created. */
+    readonly renderer: string;
+}
+/**
+ * Probe once per page with a throwaway canvas and release the context right away. The result is memoized:
+ * call it from as many components as you like. On the server (no `document`) it answers `fast: false`
+ * without caching, so the client still gets its own probe.
+ */
+export declare function probeWebGL(): IGateResult;
+/**
+ * The probe is cheap on a GPU (10–25 ms in headless Chrome on Apple M2 Pro) but expensive exactly where it
+ * answers "no": creating the first context on SwiftShader took 1.4–1.7 s of main thread in the same Chrome.
+ * So run it off the critical path: after `load`, when the browser is idle. This is what the React hook and
+ * `loadIfFastWebGL` do.
+ */
+export declare function probeWebGLWhenIdle(timeout?: number): Promise<IGateResult>;
+/** Shorthand: `true` when a real GPU draws this page. Probes synchronously; prefer the idle form on load. */
+export declare const hasFastWebGL: () => boolean;
+/**
+ * Load a module only on a real GPU, after the page has loaded. Pass a dynamic import so the bundler splits it out:
+ *
+ *   const scene = await loadIfFastWebGL(() => import('./scene'));
+ *   if (scene) scene.mount(canvas); else keepStaticImage();
+ *
+ * On the CPU the import is never called, so the bundle is never downloaded or parsed.
+ */
+export declare function loadIfFastWebGL<T>(load: () => Promise<T>): Promise<T | null>;
+/** Forget the memoized verdict (tests, or after the user toggles a quality setting). */
+export declare function resetWebGLProbe(): void;
+export {};

package/dist/index.js

@@ -0,0 +1,87 @@
+/**
+ * webgl-gate: decide, before you download a WebGL bundle, whether this page is drawn by a real GPU.
+ *
+ * Software rasterizers (SwiftShader, llvmpipe, softpipe, "Microsoft Basic Render Driver") run WebGL on the CPU.
+ * Lighthouse and PageSpeed Insights measure mobile pages on exactly that kind of renderer, and so do many
+ * virtual machines, remote desktops and browsers with hardware acceleration turned off. There a WebGL scene
+ * costs main-thread time and Total Blocking Time, and the user gets a slideshow instead of an effect.
+ *
+ * `failIfMajorPerformanceCaveat` is not enough on its own: headless Chrome with SwiftShader still hands out a
+ * context with that flag set. So the verdict also reads the renderer name.
+ */
+/** Renderer names of known CPU rasterizers. */
+export const SOFTWARE_RENDERER = /swiftshader|llvmpipe|softpipe|software|basic render/i;
+/** The most specific renderer name the browser exposes: unmasked when allowed, otherwise `RENDERER`. */
+export function rendererName(gl) {
+    const info = gl.getExtension('WEBGL_debug_renderer_info');
+    return String(gl.getParameter(info ? info.UNMASKED_RENDERER_WEBGL : gl.RENDERER) ?? '');
+}
+/** True when this context is rasterized on the CPU. */
+export function isSoftwareRenderer(gl) {
+    return SOFTWARE_RENDERER.test(rendererName(gl));
+}
+let cached;
+/**
+ * Probe once per page with a throwaway canvas and release the context right away. The result is memoized:
+ * call it from as many components as you like. On the server (no `document`) it answers `fast: false`
+ * without caching, so the client still gets its own probe.
+ */
+export function probeWebGL() {
+    if (cached)
+        return cached;
+    if (typeof document === 'undefined')
+        return { fast: false, reason: 'no-dom', renderer: '' };
+    try {
+        const canvas = document.createElement('canvas');
+        const gl = canvas.getContext('webgl', { failIfMajorPerformanceCaveat: true });
+        if (!gl)
+            return (cached = { fast: false, reason: 'no-context', renderer: '' });
+        const renderer = rendererName(gl);
+        gl.getExtension('WEBGL_lose_context')?.loseContext();
+        const software = SOFTWARE_RENDERER.test(renderer);
+        return (cached = { fast: !software, reason: software ? 'software' : 'gpu', renderer });
+    }
+    catch {
+        return (cached = { fast: false, reason: 'error', renderer: '' });
+    }
+}
+/**
+ * The probe is cheap on a GPU (10–25 ms in headless Chrome on Apple M2 Pro) but expensive exactly where it
+ * answers "no": creating the first context on SwiftShader took 1.4–1.7 s of main thread in the same Chrome.
+ * So run it off the critical path: after `load`, when the browser is idle. This is what the React hook and
+ * `loadIfFastWebGL` do.
+ */
+export function probeWebGLWhenIdle(timeout = 3000) {
+    if (cached || typeof window === 'undefined' || typeof document === 'undefined')
+        return Promise.resolve(probeWebGL());
+    return new Promise((done) => {
+        const run = () => done(probeWebGL());
+        const idle = () => {
+            if (typeof window.requestIdleCallback === 'function')
+                window.requestIdleCallback(run, { timeout });
+            else
+                setTimeout(run, 1);
+        };
+        if (document.readyState === 'complete')
+            idle();
+        else
+            window.addEventListener('load', idle, { once: true });
+    });
+}
+/** Shorthand: `true` when a real GPU draws this page. Probes synchronously; prefer the idle form on load. */
+export const hasFastWebGL = () => probeWebGL().fast;
+/**
+ * Load a module only on a real GPU, after the page has loaded. Pass a dynamic import so the bundler splits it out:
+ *
+ *   const scene = await loadIfFastWebGL(() => import('./scene'));
+ *   if (scene) scene.mount(canvas); else keepStaticImage();
+ *
+ * On the CPU the import is never called, so the bundle is never downloaded or parsed.
+ */
+export async function loadIfFastWebGL(load) {
+    return (await probeWebGLWhenIdle()).fast ? load() : null;
+}
+/** Forget the memoized verdict (tests, or after the user toggles a quality setting). */
+export function resetWebGLProbe() {
+    cached = undefined;
+}

package/dist/react.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `null` during server rendering, the first client render (so hydration matches) and until the page has loaded
+ * and the browser is idle; then `true` on a real GPU and `false` on a CPU rasterizer or without WebGL. Render your
+ * static fallback while it is not `true`.
+ *
+ *   const fast = useFastWebGL();
+ *   return fast ? <LiveScene /> : <img src="/cover.avif" alt="" />;
+ */
+export declare function useFastWebGL(): boolean | null;

package/dist/react.js

@@ -0,0 +1,20 @@
+import { useEffect, useState } from 'react';
+import { probeWebGLWhenIdle } from './index.js';
+/**
+ * `null` during server rendering, the first client render (so hydration matches) and until the page has loaded
+ * and the browser is idle; then `true` on a real GPU and `false` on a CPU rasterizer or without WebGL. Render your
+ * static fallback while it is not `true`.
+ *
+ *   const fast = useFastWebGL();
+ *   return fast ? <LiveScene /> : <img src="/cover.avif" alt="" />;
+ */
+export function useFastWebGL() {
+    const [fast, setFast] = useState(null);
+    useEffect(() => {
+        let alive = true;
+        void probeWebGLWhenIdle().then((result) => { if (alive)
+            setFast(result.fast); });
+        return () => { alive = false; };
+    }, []);
+    return fast;
+}

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "webgl-gate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Skip your WebGL bundle when the page is rendered by the CPU (SwiftShader, llvmpipe, Basic Render). Under 1 kB, no network, no benchmark tables.",
+  "keywords": [
+    "webgl",
+    "webgl2",
+    "gpu",
+    "gpu-detection",
+    "software-rendering",
+    "swiftshader",
+    "llvmpipe",
+    "lighthouse",
+    "pagespeed",
+    "core-web-vitals",
+    "total-blocking-time",
+    "web-performance",
+    "lazy-loading",
+    "pixijs",
+    "threejs",
+    "react-three-fiber",
+    "babylonjs",
+    "maplibre",
+    "nextjs",
+    "react",
+    "vue",
+    "svelte"
+  ],
+  "license": "MIT",
+  "author": "Oleksandr Kutsenko (https://kutsikgames.com)",
+  "homepage": "https://github.com/Alexkutsenko95/webgl-gate#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alexkutsenko95/webgl-gate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Alexkutsenko95/webgl-gate/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "size": "node scripts/size.mjs",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run size"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
+  }
+}