@fusion.dev/helix-theme 0.0.0-dev → 0.0.3

package/dist/index.d.ts

@@ -14,9 +14,9 @@ export interface ThemeEngine {
     /**
      * Reads a hex color into its OKLCH components.
      *
-     * @throws when the string is not a hex color. **The TypeScript engine
-     * returned a `NaN` triple**, which every comparison is false against, so a
-     * color that could not be read traveled onward looking like one.
+     * @throws when the string is not a hex color. Returning a `NaN` triple
+     * instead is worse: every comparison against it is false, so a color that
+     * could not be read travels onward looking like one.
      */
     hexToOklch(hex: string): Oklch;
 }

package/dist/types.d.ts

@@ -1,15 +1,11 @@
 /**
  * The shapes a consumer writes and the shapes they get back.
  *
- * **Declarations only, and that is what is left of the TypeScript engine.** The
- * derivation is Rust now, reached through WebAssembly, so what a JavaScript
- * consumer needs from this package is the vocabulary rather than the solver. A
- * type is erased at build time, so nothing here is a second implementation of
- * anything: it cannot drift into disagreeing with the engine about an *answer*,
- * only about a *field name*, which is what `check:wasm` compares.
- *
- * The prose is kept whole from the files it came from. It is the argument for
- * why each field exists, and it was never about how any of them was computed.
+ * **Declarations only.** The derivation is Rust, reached through WebAssembly, so
+ * what a JavaScript consumer needs from this package is the vocabulary rather
+ * than the solver. A type is erased at build time, so nothing here is a second
+ * implementation of anything: it cannot drift into disagreeing with the engine
+ * about an *answer*, only about a *field name*, which is what is compared.
  */
 /** A color in OKLCH. Lightness 0 to 1, chroma from 0, hue in degrees. */
 export interface Oklch {
@@ -24,7 +20,7 @@ export type Color = Oklch | string;
  *
  * Written as a relationship rather than a second color because a literal
  * drifts out of relation the moment anybody rethemes, which is the failure of
- * every palette with two hardcoded colours in it.
+ * every palette with two hardcoded colors in it.
  */
 export interface Relation {
     /**
@@ -126,10 +122,6 @@ export interface ThemeIntent {
      * **The one material choice that can invalidate the guarantee.** Contrast is
      * measured against a known ground and a translucent surface does not have
      * one, so a pair over it comes back `unverifiable` rather than measured.
-     *
-     * The audit found this half nearly done already: six declarations across two
-     * families, both already behind hooks, so material needed a policy token to
-     * default to and nothing else.
      */
     material?: {
         blur?: number;
@@ -138,12 +130,8 @@ export interface ThemeIntent {
     /**
      * The faces the theme is set in.
      *
-     * **Type is part of a theme and had no input at all.** Twenty tokens across
-     * five categories, families, sizes, weights, leading and tracking, were
-     * unreachable from intent while every color in the palette was one field
-     * away. Families are the half a consumer actually chooses; the size scale,
-     * the weights and the spacing are the half that is a system, and they are
-     * still fixed.
+     * **Families are the half a consumer chooses**; the size scale, the weights
+     * and the spacing are the half that is a system, and they stay fixed.
      *
      * `display` falls back to `body`, which is what the stylesheet already does:
      * a theme with one face is the common case and should not have to say so
@@ -190,12 +178,7 @@ export interface ThemeIntent {
      */
     namespace?: string;
     /**
-     * How the theme's motion feels.
-     *
-     * **The other axis with no input at all**, alongside the half of type that is
-     * a system: nine tokens, four durations and five curves, and a brand with a
-     * snappy voice and one with a gentle one reached them the same way, which is
-     * to say not at all.
+     * How the theme's motion feels: nine tokens, four durations and five curves.
      *
      * `character` sets the curve every component reaches for by default and
      * carries a duration multiplier with it, because the two are one decision: a
@@ -204,8 +187,7 @@ export interface ThemeIntent {
      *
      * `instant` is not scaled. It is 0 and means "do not animate", which is a
      * statement rather than a duration, and it emits no curves at all: three
-     * easings for transitions of zero length is a contradiction the type used to
-     * allow through `scale: 0`.
+     * easings for transitions of zero length is a contradiction.
      *
      * `precise` is the one character that is not physical. The other three
      * accelerate, settle or overshoot; linear reads as moved by a mechanism, and
@@ -222,8 +204,7 @@ export interface ThemeIntent {
      * Chroma 0 is a dead gray and is the default, matching `primitives.css`,
      * which records why: a fixed chroma is a rising *saturation* as a surface
      * darkens, so a trace that looks right on a light page reads navy across a
-     * dark one. The engine used to hardcode 0.008, the exact value the
-     * stylesheet had already rejected for that reason.
+     * dark one.
      */
     neutral?: {
         chroma?: number;
@@ -245,9 +226,8 @@ export interface ThemeIntent {
      * rather than a comment asking nicely.
      *
      * `fill` and `space` produce the same edge and lift, which is none of
-     * either: the difference between them lives in the surface colours and in
-     * `density`, not here. Said out loud because two values with one output
-     * looks like a bug until it is explained.
+     * either: the difference between them lives in the surface colors and in
+     * `density`, not here. Two values with one output reads as a bug and is not.
      */
     separation?: {
         floating?: 'border' | 'fill' | 'shadow';
@@ -352,10 +332,10 @@ export interface Pairing {
      * measured and passed. Folding the two together is how a guarantee decays
      * into a claim about the pairs that happened to be easy.
      *
-     * One producer today: a pairing naming a token this theme does not emit,
-     * which a caller supplying their own `pairings` will legitimately do.
-     * Translucent grounds are the second, when `material` lands: what sits
-     * behind a glass surface is whatever the reader scrolled under it.
+     * Two producers: a pairing naming a token this theme does not emit, which a
+     * caller supplying their own `pairings` will legitimately do, and a ground
+     * the model marks unbounded, where what sits behind the surface is whatever
+     * the reader scrolled under it.
      */
     status: 'fail' | 'pass' | 'unverifiable';
     /**
@@ -369,13 +349,9 @@ export interface Pairing {
 /**
  * What a derivation produced.
  *
- * **No `intent`, which the TypeScript engine carried and nothing read.** It held
- * the resolved intent so a consumer could see what they got rather than what
- * they asked for, which is a real thing to want and was never used, never dumped
- * by the oracle, and therefore never checked. Serialising it across the boundary
- * means a `Serialize` on every shape in the vocabulary including three unions
- * with hand-written readers, which is a day of work for a field with no caller.
- * It goes back the moment one appears.
+ * **No resolved `intent` field.** Carrying one across the WebAssembly boundary
+ * means a `Serialize` on every shape in the vocabulary, three hand-read unions
+ * included, and no consumer has asked for it. It goes back when one does.
  */
 export interface DerivedTheme {
     /**
@@ -406,20 +382,19 @@ export interface DerivedTheme {
     pairings: Pairing[];
     /**
      * The seed values a consumer must write for `helix/styles` to re-derive the
-     * halves this engine does not compute: the twenty-four series colours, the
+     * halves this engine does not compute: the twenty-four series colors, the
      * spacing scale and the corner radii.
      *
      * **Data rather than only a line of CSS**, because the two consumers apply it
      * differently. `toCss` renders a block; a page theming one panel writes the
      * properties onto that element. Both read this, so neither can hold a
-     * different opinion about what the seed is, which is exactly what the
-     * marketing site's hand-written bridge had become.
+     * different opinion about what the seed is.
      */
     seeds: Record<string, string>;
     tokens: DerivedToken[];
     /**
      * Pairings that failed their contrast target, pinned values included.
-     * Rendered from `pairings`, and no longer the only record of a result.
+     * Rendered from `pairings`.
      */
     violations: string[];
 }

package/dist/types.js

@@ -1,14 +1,10 @@
 /**
  * The shapes a consumer writes and the shapes they get back.
  *
- * **Declarations only, and that is what is left of the TypeScript engine.** The
- * derivation is Rust now, reached through WebAssembly, so what a JavaScript
- * consumer needs from this package is the vocabulary rather than the solver. A
- * type is erased at build time, so nothing here is a second implementation of
- * anything: it cannot drift into disagreeing with the engine about an *answer*,
- * only about a *field name*, which is what `check:wasm` compares.
- *
- * The prose is kept whole from the files it came from. It is the argument for
- * why each field exists, and it was never about how any of them was computed.
+ * **Declarations only.** The derivation is Rust, reached through WebAssembly, so
+ * what a JavaScript consumer needs from this package is the vocabulary rather
+ * than the solver. A type is erased at build time, so nothing here is a second
+ * implementation of anything: it cannot drift into disagreeing with the engine
+ * about an *answer*, only about a *field name*, which is what is compared.
  */
 export {};

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.0.0-dev",
+  "version": "0.0.3",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -26,9 +26,14 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "cargo test -p fusion-helix-theme --manifest-path ../../Cargo.toml",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "wasm": "node scripts/build-wasm.mjs",
+    "wasm-check": "bun scripts/check-wasm.mjs"
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
+  "devDependencies": {
+    "@fusion.dev/scripts": "0.0.0-dev"
+  },
   "homepage": "https://fusion.dev",
   "keywords": [
     "theming",

package/wasm/fusion_helix_theme.d.ts

@@ -11,9 +11,6 @@
  * intent-in-CSS-out function would have it deriving twice for one keystroke.
  * The result carries `css` keyed by selector, empty when none were asked for.
  *
- * For reference, the TypeScript engine this replaces took 39ms for the
- * derivation alone, so the builder does less work than it did rather than more.
- *
  * `selectors` is a JSON array, keeping the boundary uniformly JSON in and JSON
  * out rather than mixing in a bound array type for one argument.
  *
@@ -27,11 +24,10 @@ export function derive(intent: string, selectors: string): string;
 /**
  * Reads a hex color into its OKLCH components, as JSON.
  *
- * **Throws where the TypeScript returned `NaN`**, which is a deliberate change
- * and the same one `resolve` makes for a brand: `Number.parseInt` of something
- * that is not hex gives `NaN`, every comparison against which is false, so a
- * color that could not be read traveled onward looking like a color. A
- * caller passing the value of a color input never sees this.
+ * **Throws rather than returning a `NaN` triple**, which is the decision
+ * `resolve` makes for a brand: every comparison against `NaN` is false, so a
+ * color that could not be read travels onward looking like a color. A caller
+ * passing the value of a color input never sees this.
  *
  * # Errors
  *

package/wasm/fusion_helix_theme.js

@@ -10,9 +10,6 @@
  * intent-in-CSS-out function would have it deriving twice for one keystroke.
  * The result carries `css` keyed by selector, empty when none were asked for.
  *
- * For reference, the TypeScript engine this replaces took 39ms for the
- * derivation alone, so the builder does less work than it did rather than more.
- *
  * `selectors` is a JSON array, keeping the boundary uniformly JSON in and JSON
  * out rather than mixing in a bound array type for one argument.
  *
@@ -50,11 +47,10 @@ export function derive(intent, selectors) {
 /**
  * Reads a hex color into its OKLCH components, as JSON.
  *
- * **Throws where the TypeScript returned `NaN`**, which is a deliberate change
- * and the same one `resolve` makes for a brand: `Number.parseInt` of something
- * that is not hex gives `NaN`, every comparison against which is false, so a
- * color that could not be read traveled onward looking like a color. A
- * caller passing the value of a color input never sees this.
+ * **Throws rather than returning a `NaN` triple**, which is the decision
+ * `resolve` makes for a brand: every comparison against `NaN` is false, so a
+ * color that could not be read travels onward looking like a color. A caller
+ * passing the value of a color input never sees this.
  *
  * # Errors
  *