@fusion.dev/helix-theme 0.206.0 → 0.207.1

package/README.md

@@ -1,32 +1,72 @@
 # @fusion.dev/helix-theme
 
-The theme derivation engine. Computes a complete, contrast-guaranteed token set
-from a small set of intent inputs.
+The theme derivation engine. Computes a complete token set from a small set of
+intent inputs, and measures every text and background pair in its surface model
+against its contrast target.
 
 ```sh
 npm install @fusion.dev/helix-theme
 ```
 
+Give it what you mean, a brand color and whatever else you have an opinion
+about, and it returns the tokens with each text color solved against the
+backgrounds it lands on. A pair that cannot meet its target, such as one with a
+color you pinned, is reported in `violations`. `foreground-subtle` is not
+solved: it is a fixed step of the stylesheet's gray ramp, and its contrast is
+not guaranteed. With no brand, the theme is ink: near-black on a light page and
+near-white on a dark one.
+
+## Load the engine
+
+The engine is WebAssembly. The module is in the package at
+`wasm/fusion_helix_theme_bg.wasm`, exported as
+`@fusion.dev/helix-theme/wasm/fusion_helix_theme_bg.wasm`. Serve that file from
+your app, and pass its URL to `initTheme`:
+
 ```js
 import { initTheme } from '@fusion.dev/helix-theme'
 
-const engine = await initTheme('/helix/theme.wasm')
-const theme = engine.derive({ brand: '#3b82f6' }, [':root'])
+const engine = await initTheme(wasmUrl)
+```
 
-document.head.append(Object.assign(document.createElement('style'), {
-  textContent: theme.css[':root'],
-}))
+With Vite, a `?url` import is one way to serve it. Vite copies the file into
+your build and gives you its URL:
+
+```js
+import wasmUrl from '@fusion.dev/helix-theme/wasm/fusion_helix_theme_bg.wasm?url'
 ```
 
-Give it what you mean, a brand color and whatever else you have an opinion
-about, and it returns every token the system needs with the contrast
-relationships already satisfied. With no brand, the theme is ink: near-black on
-a light page and near-white on a dark one.
+In Node, pass the file's bytes:
+
+```js
+import { readFile } from 'node:fs/promises'
+import { initTheme } from '@fusion.dev/helix-theme'
+
+const engine = await initTheme(
+  await readFile(new URL(import.meta.resolve('@fusion.dev/helix-theme/wasm/fusion_helix_theme_bg.wasm'))),
+)
+```
 
 **It has to be awaited and there is no way around that.** WebAssembly
 instantiates asynchronously, so the engine is handed back from `initTheme`
 rather than being importable: you cannot hold one without having waited for it.
 
+## Theme a page
+
+```js
+const { css, dark, light } = engine.deriveModes({ brand: '#3b82f6' }, [':root'])
+
+document.head.append(Object.assign(document.createElement('style'), {
+  textContent: css[':root'],
+}))
+```
+
+`deriveModes` derives the intent in light and dark mode and renders one block
+with each color as a `light-dark()` pair, so the page follows the reader's color
+mode. Each mode's theme comes back as well, as `light` and `dark`, with its own
+`violations`. `derive` derives one mode, for a theme that has only one, such as
+a section in a color of its own.
+
 The derivation is Rust and ships as WASM, so the same arithmetic runs in a
 browser, in a build step and in the CLI, rather than two implementations
 disagreeing by construction.

package/dist/index.d.ts

@@ -5,10 +5,15 @@ export interface ThemeEngine {
     /**
      * Derives a theme, and renders it under each selector asked for.
      *
+     * One mode, the intent's `scheme`, which is light when it names none. For a
+     * page with both modes, `deriveModes` derives each and renders them as one
+     * block.
+     *
      * @throws when the engine refuses the intent, which it does for anything that
-     * would produce a palette reporting itself clean without having been measured:
-     * an unreadable brand, accent or pinned status, a non-finite number, or one
-     * outside the range it is meaningful in.
+     * would produce a palette reporting itself clean without having been measured,
+     * or a block CSS cannot read: an unreadable brand, accent or pinned status, a
+     * non-finite number, one outside the range it is meaningful in, or a namespace
+     * that is not a token prefix.
      */
     derive(intent: ThemeIntent, selectors?: readonly string[]): DerivedTheme;
     /**
@@ -55,5 +60,9 @@ export type Source = BufferSource | Response | URL | string;
  * startup get one instantiation and both wait on it. Caching the resolved value
  * instead would let the second call start a second download before the first
  * finished.
+ *
+ * **A load that fails is not kept.** Every caller already waiting on it gets
+ * the failure, and the next call loads again, so a retry with the right source
+ * can succeed.
  */
 export declare function initTheme(source: Source): Promise<ThemeEngine>;

package/dist/index.js

@@ -1,10 +1,31 @@
 import initWasm, { derive, deriveModes, hexToOklch as readHex } from '../wasm/fusion_helix_theme.js';
 let loading;
+function finite(value, at) {
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        throw new Error(`${at} must be a finite number, received ${value}`);
+    }
+    if (typeof value !== 'object' || value === null) {
+        return;
+    }
+    const list = Array.isArray(value);
+    for (const [key, inner] of Object.entries(value)) {
+        finite(inner, list ? `${at}[${key}]` : at === '' ? key : `${at}.${key}`);
+    }
+}
+function written(intent) {
+    finite(intent, '');
+    return JSON.stringify(intent);
+}
 export function initTheme(source) {
-    loading ??= initWasm({ module_or_path: source }).then(() => ({
-        derive: (intent, selectors = []) => JSON.parse(derive(JSON.stringify(intent), JSON.stringify(selectors))),
-        deriveModes: (intent, selectors = []) => JSON.parse(deriveModes(JSON.stringify(intent), JSON.stringify(selectors))),
+    loading ??= initWasm({ module_or_path: source })
+        .then(() => ({
+        derive: (intent, selectors = []) => JSON.parse(derive(written(intent), JSON.stringify(selectors))),
+        deriveModes: (intent, selectors = []) => JSON.parse(deriveModes(written(intent), JSON.stringify(selectors))),
         hexToOklch: (hex) => JSON.parse(readHex(hex)),
-    }));
+    }))
+        .catch((failure) => {
+        loading = undefined;
+        throw failure;
+    });
     return loading;
 }

package/dist/types.d.ts

@@ -62,6 +62,14 @@ export type Seed = Color | Relation;
  * A status role. A color pins it outright; an object nudges its hue within
  * the meaning it already carries.
  *
+ * **A hue stays in its status's band**, in OKLCH degrees, and one outside it
+ * is refused with the band it missed:
+ *
+ * - `danger`: 15 to 40, the reds from crimson to red-orange
+ * - `warning`: 45 to 105, orange and amber to yellow
+ * - `success`: 125 to 180, the greens from yellow-green to teal-green
+ * - `info`: 200 to 280, cyan and blue to indigo
+ *
  * **Never a `Relation`**, which is the asymmetry with `accent` and is
  * deliberate: a `danger` that rotates with the brand is a warning a reader has
  * to re-learn per product.
@@ -71,6 +79,11 @@ export type StatusSeed = Color | {
 };
 /** One pair to measure, by token name, without the namespace prefix. */
 export interface PairingRequest {
+    /**
+     * The ground. `color-well over color-surface` names a field's well over the
+     * surface it sits on: 5% of the theme's `color-foreground` laid over that
+     * surface, as the stylesheet paints it.
+     */
     background: string;
     foreground: string;
     /**
@@ -210,7 +223,13 @@ export interface ThemeIntent {
         weight?: 'light' | 'regular' | 'strong';
     };
     /**
-     * The token prefix, without dashes. `helix` by default.
+     * The token prefix. `helix` by default, and `acme` emits
+     * `--acme-color-primary`.
+     *
+     * ASCII letters, digits, hyphens, and underscores, with no hyphen at either
+     * end, since the engine writes the hyphens around it. Any other namespace is
+     * refused with the value it received, such as an empty one, `--acme`, or
+     * `acme tokens`.
      *
      * **What makes the engine useful to somebody who has never heard of Helix.**
      * With this and `pairings`, a team on their own tokens gets the solver and
@@ -333,8 +352,15 @@ export interface ThemeIntent {
     };
     /**
      * Values that replace what derivation would have produced, keyed by token
-     * name without the namespace prefix. Verified like anything else: a pinned
-     * value that misses its target is a violation, not an exception.
+     * name without the namespace prefix.
+     *
+     * A pinned value is set after the derivation, so no other color is solved
+     * against it. Every pairing that names the token measures it, and a value
+     * that misses its target is a violation. A name the engine does not emit is
+     * appended as a token of your own, which no default pairing names, so only a
+     * pairing you list in `pairings` measures it. A value the engine cannot read
+     * is skipped: a token the engine emits keeps its derived value, and a name it
+     * does not emit is left out.
      */
     tokens?: Record<string, Color>;
 }
@@ -374,6 +400,10 @@ export interface DerivedToken {
 }
 /** One measured pair, whatever the outcome. */
 export interface Pairing {
+    /**
+     * The ground, as the request names it. `color-well over color-surface` is a
+     * field's well over that surface.
+     */
     background: string;
     foreground: string;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-theme",
-  "description": "Theme derivation engine. Computes a complete, contrast-guaranteed token set from intent inputs.",
-  "version": "0.206.0",
+  "description": "Theme derivation engine. Computes a complete token set from intent inputs, and measures every text and background pair it solves against its contrast target.",
+  "version": "0.207.1",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -17,6 +17,7 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./package.json": "./package.json",
     "./wasm/fusion_helix_theme_bg.wasm": "./wasm/fusion_helix_theme_bg.wasm"
   },
   "files": [
@@ -26,6 +27,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
+    "test": "bun test src",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "wasm": "bun scripts/build-wasm.mjs",
     "wasm-check": "bun scripts/check-wasm.mjs"

package/wasm/fusion_helix_theme.js

@@ -236,11 +236,15 @@ function __wbg_finalize_init(instance, module) {
 
 async function __wbg_load(module, imports) {
     if (typeof Response === 'function' && module instanceof Response) {
+        if (!module.ok) {
+            throw new Error(`failed to fetch Wasm: ${module.status} ${module.statusText} fetching '${module.url}'`);
+        }
+
         if (typeof WebAssembly.instantiateStreaming === 'function') {
             try {
                 return await WebAssembly.instantiateStreaming(module, imports);
             } catch (e) {
-                const validResponse = module.ok && expectedResponseType(module.type);
+                const validResponse = expectedResponseType(module.type);
 
                 if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
                     console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);