@fusion.dev/helix 0.33.2 → 0.33.4

package/custom-elements.json

@@ -4025,7 +4025,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "One fragment shader over a full-screen triangle, with the palette read from\nthe tokens rather than given as colors. A background written with hex values\nis an asset that has to be re-cut when the brand moves; one written against\n`--helix-color-primary` is a consequence of it.\n\n**Every shape ramps through four token stops**, and the token layer inverts\neach: the page's background, `primary-subtle`, `primary`, then a peak. The\npeak is the foreground on a dark page and `primary-active` on a light one,\nbecause mixing a saturated hue toward near-black takes the chroma out of the\npixels carrying most of it. Which way the page runs is read off the ground's\nown luminance rather than asked of the mode, which is a private token.\n\n**No dependency, and no scene graph.** The geometry is three vertices derived\nfrom `gl_VertexID`, so there is no attribute, no buffer and no upload.\n\n**It stops when nobody is looking**, off screen and in a background tab, and\n`prefers-reduced-motion` gets one still frame rather than an empty box. A\ncontext the browser takes back, on a GPU reset or past its cap of about\nsixteen, stops it too, and the gradient shows until the context returns.\n\nStyled only, and with behavior, which the tier split does not otherwise\nallow: the behavior is drawing to a canvas, so there is no structure a\nconsumer could restyle and nothing for a headless twin to hold.",
+          "description": "One fragment shader over a full-screen triangle, with the palette read from\nthe tokens rather than given as colors. A background written with hex values\nis an asset that has to be re-cut when the brand moves; one written against\n`--helix-color-primary` is a consequence of it.\n\n**Every shape ramps through four token stops**, and the token layer inverts\neach: the page's background, `primary-subtle`, `primary`, then a peak. The\npeak is the foreground on a dark page and `primary-active` on a light one,\nbecause mixing a saturated hue toward near-black takes the chroma out of the\npixels carrying most of it. Which way the page runs is read off the ground's\nown luminance rather than asked of the mode, which is a private token.\n\n**No dependency, and no scene graph.** The geometry is three vertices derived\nfrom `gl_VertexID`, so there is no attribute, no buffer and no upload.\n\n**It stops when nobody is looking**, off screen and in a background tab, and\n`prefers-reduced-motion` gets one still frame rather than an empty box. A\ncontext the browser takes back, on a GPU reset or past its cap of about\nsixteen, stops it too, and the gradient shows until the context returns.\n\n**It declines a renderer that draws on the CPU**, which is a headless browser\nand a machine with no usable GPU, and shows the gradient instead. The shader\ncosts about 450ms of first frame per element there against 2ms on a GPU, for\na field drawn from the same tokens the gradient already ramps.\n\nStyled only, and with behavior, which the tier split does not otherwise\nallow: the behavior is drawing to a canvas, so there is no structure a\nconsumer could restyle and nothing for a headless twin to hold.",
           "name": "HelixAura",
           "cssParts": [
             {
@@ -4414,6 +4414,18 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "drawsInSoftware",
+              "privacy": "private",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "description": "Whether WebGL here is drawn on the CPU, asked before one is drawn into.\n\n**The shader costs what a GPU makes it cheap to ask for.** The note at the\ntop of this file measures it: on Metal the browser shares the compiled\nprogram and each aura after the first draws its opening frame in about 2ms,\nwhile under SwiftShader nothing is shared and each one compiles the pipeline\nagain for about 450ms. Measured again 15 Sep 2026 on a page of 720 pixel\nauras, SwiftShader against the same page with this check in place: the worst\nframe gap went 568ms to 50ms with one aura, 1626ms to 34ms with three and\n3200ms to 42ms with six, and a page of three or six ran at 13 frames a\nsecond before and at the display's own rate after. What that buys is a field\na reader barely sees behind content, against a gradient ramped from the same\ntokens. So the software path takes the fallback.\n\n**The unmasked name is the only one that answers.** `gl.RENDERER` is masked\nto `WebKit WebGL` on Chromium, the same string on SwiftShader and on Metal,\nand `WEBGL_debug_renderer_info` is what lifts the mask.\n\n**An unreadable renderer draws**, which is the safe direction and not the\ntidy one. The extension is optional and is withheld deliberately: Firefox's\n`privacy.resistFingerprinting` and Safari's equivalent both drop it, and a\nbrowser may drop it at any time, since a GPU name is a fingerprinting\nsurface. Treating \"we cannot tell\" as software would take the shader away\nfrom every reader on a machine that hides its hardware, which is a real GPU\nfar more often than not. Treating it as hardware costs a machine that hides\na software renderer the 450ms, which is the cost the component has today.\n\n**A probe context of its own, and given straight back.** Asking the\nelement's own canvas would spend it: `build` below is written around a\ncanvas whose context was force-lost never yielding a working one again, and\nthe probe has to release what it took or a page of auras runs the browser\ninto its cap of about sixteen. One pixel by one, and released through\n`WEBGL_lose_context` the same way `drop` does.\n\n**The same attributes the real context asks for**, because they are part of\nthe question: `powerPreference` can select a different adapter, so a probe\nasking for a high-performance context would name a GPU the drawing one is\nnever given.\n\n**Asked per context rather than once for the page.** The answer is not\nfixed: a GPU process that crashes takes the page down to SwiftShader for\nthe rest of its life, and an aura rebuilding after that should get the\ncurrent answer rather than the one from before. It costs a context creation\nand two calls, measured 15 Sep 2026 at about 2ms under SwiftShader and 2ms\non Metal, against the 450ms and 135ms first draws it stands in front of, and\nit happens once per context rather than once per frame."
+            },
             {
               "kind": "method",
               "name": "build",

package/dist/aura/root/aura-root.d.ts

@@ -24,6 +24,11 @@ import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
  * context the browser takes back, on a GPU reset or past its cap of about
  * sixteen, stops it too, and the gradient shows until the context returns.
  *
+ * **It declines a renderer that draws on the CPU**, which is a headless browser
+ * and a machine with no usable GPU, and shows the gradient instead. The shader
+ * costs about 450ms of first frame per element there against 2ms on a GPU, for
+ * a field drawn from the same tokens the gradient already ramps.
+ *
  * Styled only, and with behavior, which the tier split does not otherwise
  * allow: the behavior is drawing to a canvas, so there is no structure a
  * consumer could restyle and nothing for a headless twin to hold.
@@ -274,6 +279,55 @@ export declare class HelixAura extends HelixElement {
     protected render(): TemplateResult;
     protected firstUpdated(changed: PropertyValues): void;
     private start;
+    /**
+     * Whether WebGL here is drawn on the CPU, asked before one is drawn into.
+     *
+     * **The shader costs what a GPU makes it cheap to ask for.** The note at the
+     * top of this file measures it: on Metal the browser shares the compiled
+     * program and each aura after the first draws its opening frame in about 2ms,
+     * while under SwiftShader nothing is shared and each one compiles the pipeline
+     * again for about 450ms. Measured again 15 Sep 2026 on a page of 720 pixel
+     * auras, SwiftShader against the same page with this check in place: the worst
+     * frame gap went 568ms to 50ms with one aura, 1626ms to 34ms with three and
+     * 3200ms to 42ms with six, and a page of three or six ran at 13 frames a
+     * second before and at the display's own rate after. What that buys is a field
+     * a reader barely sees behind content, against a gradient ramped from the same
+     * tokens. So the software path takes the fallback.
+     *
+     * **The unmasked name is the only one that answers.** `gl.RENDERER` is masked
+     * to `WebKit WebGL` on Chromium, the same string on SwiftShader and on Metal,
+     * and `WEBGL_debug_renderer_info` is what lifts the mask.
+     *
+     * **An unreadable renderer draws**, which is the safe direction and not the
+     * tidy one. The extension is optional and is withheld deliberately: Firefox's
+     * `privacy.resistFingerprinting` and Safari's equivalent both drop it, and a
+     * browser may drop it at any time, since a GPU name is a fingerprinting
+     * surface. Treating "we cannot tell" as software would take the shader away
+     * from every reader on a machine that hides its hardware, which is a real GPU
+     * far more often than not. Treating it as hardware costs a machine that hides
+     * a software renderer the 450ms, which is the cost the component has today.
+     *
+     * **A probe context of its own, and given straight back.** Asking the
+     * element's own canvas would spend it: `build` below is written around a
+     * canvas whose context was force-lost never yielding a working one again, and
+     * the probe has to release what it took or a page of auras runs the browser
+     * into its cap of about sixteen. One pixel by one, and released through
+     * `WEBGL_lose_context` the same way `drop` does.
+     *
+     * **The same attributes the real context asks for**, because they are part of
+     * the question: `powerPreference` can select a different adapter, so a probe
+     * asking for a high-performance context would name a GPU the drawing one is
+     * never given.
+     *
+     * **Asked per context rather than once for the page.** The answer is not
+     * fixed: a GPU process that crashes takes the page down to SwiftShader for
+     * the rest of its life, and an aura rebuilding after that should get the
+     * current answer rather than the one from before. It costs a context creation
+     * and two calls, measured 15 Sep 2026 at about 2ms under SwiftShader and 2ms
+     * on Metal, against the 450ms and 135ms first draws it stands in front of, and
+     * it happens once per context rather than once per frame.
+     */
+    private static drawsInSoftware;
     /**
      * The context and the program, from whatever canvas can still give one.
      *

package/dist/aura/root/aura-root.js

@@ -14,6 +14,7 @@ import { styles } from './aura-root.css.js';
 const MAX_CANVAS_EDGE = 4096;
 const MAX_CANVAS_PIXELS = 4_194_304;
 const OPENING_PATIENCE = 500;
+const SOFTWARE_RENDERER = /swiftshader|llvmpipe|softpipe|software rasterizer|basic render/i;
 let HelixAura = class HelixAura extends HelixElement {
     constructor() {
         super(...arguments);
@@ -208,11 +209,27 @@ let HelixAura = class HelixAura extends HelixElement {
             this.open();
         }
     }
+    static drawsInSoftware() {
+        const probe = document.createElement('canvas');
+        probe.width = 1;
+        probe.height = 1;
+        const gl = probe.getContext('webgl2', HelixAura_1.CONTEXT);
+        if (!gl) {
+            return false;
+        }
+        const debug = gl.getExtension('WEBGL_debug_renderer_info');
+        const name = debug ? gl.getParameter(debug.UNMASKED_RENDERER_WEBGL) : null;
+        gl.getExtension('WEBGL_lose_context')?.loseContext();
+        return typeof name === 'string' && SOFTWARE_RENDERER.test(name);
+    }
     build() {
         let canvas = this.renderRoot.querySelector('canvas');
         if (!canvas) {
             return false;
         }
+        if (HelixAura_1.drawsInSoftware()) {
+            return false;
+        }
         let gl = canvas.getContext('webgl2', HelixAura_1.CONTEXT);
         if (gl?.isContextLost()) {
             const fresh = document.createElement('canvas');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix",
   "description": "Styled component tier. Extends the headless tier with token-driven presentation.",
-  "version": "0.33.2",
+  "version": "0.33.4",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -47,14 +47,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.33.2",
-    "@fusion.dev/helix-headless": "0.33.2",
-    "@fusion.dev/helix-styles": "0.33.2"
+    "@fusion.dev/helix-core": "0.33.4",
+    "@fusion.dev/helix-headless": "0.33.4",
+    "@fusion.dev/helix-styles": "0.33.4"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.33.2",
-    "@fusion.dev/helix-testing": "0.33.2",
+    "@fusion.dev/helix-cem": "0.33.4",
+    "@fusion.dev/helix-testing": "0.33.4",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -20395,6 +20395,11 @@ export type CustomElements = {
    * context the browser takes back, on a GPU reset or past its cap of about
    * sixteen, stops it too, and the gradient shows until the context returns.
    *
+   * **It declines a renderer that draws on the CPU**, which is a headless browser
+   * and a machine with no usable GPU, and shows the gradient instead. The shader
+   * costs about 450ms of first frame per element there against 2ms on a GPU, for
+   * a field drawn from the same tokens the gradient already ramps.
+   *
    * Styled only, and with behavior, which the tier split does not otherwise
    * allow: the behavior is drawing to a canvas, so there is no structure a
    * consumer could restyle and nothing for a headless twin to hold.
@@ -39175,6 +39180,11 @@ export type CustomElementsSolidJs = {
    * context the browser takes back, on a GPU reset or past its cap of about
    * sixteen, stops it too, and the gradient shows until the context returns.
    *
+   * **It declines a renderer that draws on the CPU**, which is a headless browser
+   * and a machine with no usable GPU, and shows the gradient instead. The shader
+   * costs about 450ms of first frame per element there against 2ms on a GPU, for
+   * a field drawn from the same tokens the gradient already ramps.
+   *
    * Styled only, and with behavior, which the tier split does not otherwise
    * allow: the behavior is drawing to a canvas, so there is no structure a
    * consumer could restyle and nothing for a headless twin to hold.

package/types/vue.d.ts

@@ -11197,7 +11197,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixAreaChartVueProps,
     HelixAreaChartVueEvents
   >;
-  /** One fragment shader over a full-screen triangle, with the palette read from the tokens rather than given as colors. A background written with hex values is an asset that has to be re-cut when the brand moves; one written against '--helix-color-primary' is a consequence of it.  **Every shape ramps through four token stops**, and the token layer inverts each: the page's background, 'primary-subtle', 'primary', then a peak. The peak is the foreground on a dark page and 'primary-active' on a light one, because mixing a saturated hue toward near-black takes the chroma out of the pixels carrying most of it. Which way the page runs is read off the ground's own luminance rather than asked of the mode, which is a private token.  **No dependency, and no scene graph.** The geometry is three vertices derived from 'gl_VertexID', so there is no attribute, no buffer and no upload.  **It stops when nobody is looking**, off screen and in a background tab, and 'prefers-reduced-motion' gets one still frame rather than an empty box. A context the browser takes back, on a GPU reset or past its cap of about sixteen, stops it too, and the gradient shows until the context returns.  Styled only, and with behavior, which the tier split does not otherwise allow: the behavior is drawing to a canvas, so there is no structure a consumer could restyle and nothing for a headless twin to hold. */
+  /** One fragment shader over a full-screen triangle, with the palette read from the tokens rather than given as colors. A background written with hex values is an asset that has to be re-cut when the brand moves; one written against '--helix-color-primary' is a consequence of it.  **Every shape ramps through four token stops**, and the token layer inverts each: the page's background, 'primary-subtle', 'primary', then a peak. The peak is the foreground on a dark page and 'primary-active' on a light one, because mixing a saturated hue toward near-black takes the chroma out of the pixels carrying most of it. Which way the page runs is read off the ground's own luminance rather than asked of the mode, which is a private token.  **No dependency, and no scene graph.** The geometry is three vertices derived from 'gl_VertexID', so there is no attribute, no buffer and no upload.  **It stops when nobody is looking**, off screen and in a background tab, and 'prefers-reduced-motion' gets one still frame rather than an empty box. A context the browser takes back, on a GPU reset or past its cap of about sixteen, stops it too, and the gradient shows until the context returns.  **It declines a renderer that draws on the CPU**, which is a headless browser and a machine with no usable GPU, and shows the gradient instead. The shader costs about 450ms of first frame per element there against 2ms on a GPU, for a field drawn from the same tokens the gradient already ramps.  Styled only, and with behavior, which the tier split does not otherwise allow: the behavior is drawing to a canvas, so there is no structure a consumer could restyle and nothing for a headless twin to hold. */
   "helix-aura": DefineCustomElement<
     HelixAura,
     HelixAuraVueProps,