@wave3d/core 0.5.0 → 0.6.0

package/dist/standalone.d.ts

@@ -2,7 +2,6 @@ import { BackgroundImageFit, BackgroundMode, BasicGradientType, BlendMode, CAMER
 import { WaveRenderer } from "./renderer/WaveRenderer.js";
 import { FallbackReason, SnapshotOptions, WaveHandle, WaveOptions, WaveState } from "./shell/createWave.js";
 import { PRESETS } from "./presets.js";
-
 //#region src/standalone.d.ts
 /** {@link createWaveImpl} with the engine already bundled in (synchronous upgrade). */
 declare function createWave(container: HTMLElement, config?: Partial<StudioConfig>, options?: WaveOptions): WaveHandle;

package/dist/studio/StudioWaveRenderer.d.ts

@@ -1,5 +1,4 @@
 import { WaveRenderer } from "../renderer/WaveRenderer.js";
-
 //#region src/studio/StudioWaveRenderer.d.ts
 declare class StudioWaveRenderer extends WaveRenderer {
   /** Set while the panel drives the camera, so orbit's 'change' doesn't re-refresh the

package/dist/studio/randomize.d.ts

@@ -1,5 +1,4 @@
 import { StudioConfig, WaveConfig } from "../config/model.js";
-
 //#region src/studio/randomize.d.ts
 /** "Tasteful Randomize": keep the scene (background, camera, lights, quality) and randomize the
  *  post-fx plus every wave independently — so a multi-wave stack becomes visibly varied.

package/dist/studio/thumbnail.d.ts

@@ -1,6 +1,5 @@
 import { StudioConfig } from "../config/model.js";
 import { WaveRenderer } from "../renderer/WaveRenderer.js";
-
 //#region src/studio/thumbnail.d.ts
 /** A hidden host div that is in layout (so clientWidth/Height are real) but off-screen. */
 declare function createThumbHost(width: number, height: number): HTMLDivElement;

package/dist/studio/thumbnail.js

@@ -11,7 +11,11 @@ function createThumbHost(width, height) {
 function prepThumbConfig(cfg) {
 	cfg.paused = true;
 	cfg.transparentBackground = false;
-	if (cfg.waves[0]?.theme !== "wireframe") cfg.background = "#ffffff";
+	if (cfg.waves[0]?.theme !== "wireframe") {
+		cfg.background = "#ffffff";
+		cfg.bloomStrength = 0;
+		cfg.innerLight = 0;
+	}
 }
 /** Render the current config to a fresh 2D canvas (null if the WebGL canvas is missing). */
 function renderThumbFrame(renderer, host) {

package/dist/studio/thumbnail.js.map

@@ -1 +1 @@
-{"version":3,"file":"thumbnail.js","names":[],"sources":["../../src/studio/thumbnail.ts"],"sourcesContent":["/**\n * Offscreen thumbnail rendering: turn a config into a still frame with one hidden, reused\n * WaveRenderer. Used by the studio's preset + history thumbnails and by the wave gallery grid.\n */\nimport type { WaveRenderer } from \"../renderer/WaveRenderer\";\nimport type { StudioConfig } from \"../config/model\";\n\n/** A hidden host div that is in layout (so clientWidth/Height are real) but off-screen. */\nexport function createThumbHost(width: number, height: number): HTMLDivElement {\n  const host = document.createElement(\"div\");\n  host.style.cssText = `position:fixed;left:-10000px;top:0;width:${width}px;height:${height}px;opacity:0;pointer-events:none;`;\n  document.body.appendChild(host);\n  return host;\n}\n\n/** Mutate `cfg` for a thumbnail still: static frame, opaque, white page behind solid themes\n *  (wireframe keys its between-line colour off the dark page background, so keep it). */\nexport function prepThumbConfig(cfg: StudioConfig): void {\n  cfg.paused = true;\n  cfg.transparentBackground = false;\n  if (cfg.waves[0]?.theme !== \"wireframe\") cfg.background = \"#ffffff\";\n}\n\n/** Render the current config to a fresh 2D canvas (null if the WebGL canvas is missing). */\nexport function renderThumbFrame(\n  renderer: WaveRenderer,\n  host: HTMLElement,\n): HTMLCanvasElement | null {\n  renderer.resize();\n  renderer.renderOnce();\n  renderer.renderOnce(); // 2nd pass so any shader recompile (theme/blend variant) is applied\n  const gl = host.querySelector(\"canvas\");\n  if (!gl) return null;\n  // Copy to a 2D canvas before encoding (reliable read of the WebGL drawing buffer).\n  const out = document.createElement(\"canvas\");\n  out.width = gl.width;\n  out.height = gl.height;\n  out.getContext(\"2d\")?.drawImage(gl, 0, 0);\n  return out;\n}\n"],"mappings":";;AAQA,SAAgB,gBAAgB,OAAe,QAAgC;CAC7E,MAAM,OAAO,SAAS,cAAc,KAAK;CACzC,KAAK,MAAM,UAAU,4CAA4C,MAAM,YAAY,OAAO;CAC1F,SAAS,KAAK,YAAY,IAAI;CAC9B,OAAO;AACT;;;AAIA,SAAgB,gBAAgB,KAAyB;CACvD,IAAI,SAAS;CACb,IAAI,wBAAwB;CAC5B,IAAI,IAAI,MAAM,EAAE,EAAE,UAAU,aAAa,IAAI,aAAa;AAC5D;;AAGA,SAAgB,iBACd,UACA,MAC0B;CAC1B,SAAS,OAAO;CAChB,SAAS,WAAW;CACpB,SAAS,WAAW;CACpB,MAAM,KAAK,KAAK,cAAc,QAAQ;CACtC,IAAI,CAAC,IAAI,OAAO;CAEhB,MAAM,MAAM,SAAS,cAAc,QAAQ;CAC3C,IAAI,QAAQ,GAAG;CACf,IAAI,SAAS,GAAG;CAChB,IAAI,WAAW,IAAI,CAAC,EAAE,UAAU,IAAI,GAAG,CAAC;CACxC,OAAO;AACT"}
+{"version":3,"file":"thumbnail.js","names":[],"sources":["../../src/studio/thumbnail.ts"],"sourcesContent":["/**\n * Offscreen thumbnail rendering: turn a config into a still frame with one hidden, reused\n * WaveRenderer. Used by the studio's preset + history thumbnails and by the wave gallery grid.\n */\nimport type { WaveRenderer } from \"../renderer/WaveRenderer\";\nimport type { StudioConfig } from \"../config/model\";\n\n/** A hidden host div that is in layout (so clientWidth/Height are real) but off-screen. */\nexport function createThumbHost(width: number, height: number): HTMLDivElement {\n  const host = document.createElement(\"div\");\n  host.style.cssText = `position:fixed;left:-10000px;top:0;width:${width}px;height:${height}px;opacity:0;pointer-events:none;`;\n  document.body.appendChild(host);\n  return host;\n}\n\n/** Mutate `cfg` for a thumbnail still: static frame, opaque, white page behind solid themes\n *  (wireframe keys its between-line colour off the dark page background, so keep it). */\nexport function prepThumbConfig(cfg: StudioConfig): void {\n  cfg.paused = true;\n  cfg.transparentBackground = false;\n  if (cfg.waves[0]?.theme !== \"wireframe\") {\n    cfg.background = \"#ffffff\";\n    // Swapping an authored dark background for the white card breaks the passes that SCATTER light\n    // out of bright pixels: they were tuned against the dark original, and white sits far above any\n    // sane threshold, so they bloom the card itself and wash the whole frame out. A preset with\n    // bloom rendered a blank white thumbnail — 0.3% non-white pixels — until this zeroed them.\n    cfg.bloomStrength = 0;\n    cfg.innerLight = 0;\n  }\n}\n\n/** Render the current config to a fresh 2D canvas (null if the WebGL canvas is missing). */\nexport function renderThumbFrame(\n  renderer: WaveRenderer,\n  host: HTMLElement,\n): HTMLCanvasElement | null {\n  renderer.resize();\n  renderer.renderOnce();\n  renderer.renderOnce(); // 2nd pass so any shader recompile (theme/blend variant) is applied\n  const gl = host.querySelector(\"canvas\");\n  if (!gl) return null;\n  // Copy to a 2D canvas before encoding (reliable read of the WebGL drawing buffer).\n  const out = document.createElement(\"canvas\");\n  out.width = gl.width;\n  out.height = gl.height;\n  out.getContext(\"2d\")?.drawImage(gl, 0, 0);\n  return out;\n}\n"],"mappings":";;AAQA,SAAgB,gBAAgB,OAAe,QAAgC;CAC7E,MAAM,OAAO,SAAS,cAAc,KAAK;CACzC,KAAK,MAAM,UAAU,4CAA4C,MAAM,YAAY,OAAO;CAC1F,SAAS,KAAK,YAAY,IAAI;CAC9B,OAAO;AACT;;;AAIA,SAAgB,gBAAgB,KAAyB;CACvD,IAAI,SAAS;CACb,IAAI,wBAAwB;CAC5B,IAAI,IAAI,MAAM,EAAE,EAAE,UAAU,aAAa;EACvC,IAAI,aAAa;EAKjB,IAAI,gBAAgB;EACpB,IAAI,aAAa;CACnB;AACF;;AAGA,SAAgB,iBACd,UACA,MAC0B;CAC1B,SAAS,OAAO;CAChB,SAAS,WAAW;CACpB,SAAS,WAAW;CACpB,MAAM,KAAK,KAAK,cAAc,QAAQ;CACtC,IAAI,CAAC,IAAI,OAAO;CAEhB,MAAM,MAAM,SAAS,cAAc,QAAQ;CAC3C,IAAI,QAAQ,GAAG;CACf,IAAI,SAAS,GAAG;CAChB,IAAI,WAAW,IAAI,CAAC,EAAE,UAAU,IAAI,GAAG,CAAC;CACxC,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wave3d/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Framework-agnostic 3D gradient-wave renderer + config model (the engine behind Wave Studio)",
   "keywords": [
     "animation",
@@ -57,7 +57,8 @@
     "@tanstack/intent": "^0.3.4",
     "@types/three": "^0.185.0",
     "three": "^0.185.0",
-    "vite": "^8.1.0"
+    "vite": "^8.1.0",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "@types/three": ">=0.180",
@@ -71,6 +72,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "tsdown && pnpm build:standalone",
-    "build:standalone": "vite build --config vite.standalone.config.ts"
+    "build:standalone": "vite build --config vite.standalone.config.ts",
+    "test": "vitest run"
   }
 }

package/skills/wave3d/SKILL.md

@@ -10,7 +10,7 @@ description: >
 metadata:
   type: core
   library: "@wave3d/core"
-  library_version: "0.5.0"
+  library_version: "0.6.0"
 sources:
   - "wave3d/wave3d:README.md"
   - "wave3d/wave3d:packages/core/src/config/model.ts"
@@ -87,13 +87,7 @@ import { Wave3D } from "@wave3d/react";
 ```ts
 import { createWave } from "@wave3d/core";
 
-const handle = createWave(
-  document.getElementById("wave"),
-  {
-    /* config */
-  },
-  { poster: "/wave.png" },
-);
+const handle = createWave(document.getElementById("wave"), {/* config */}, { poster: "/wave.png" });
 // handle: { state, renderer, set(config), play(), pause(), destroy() }
 ```
 
@@ -101,8 +95,22 @@ const handle = createWave(
 
 A wave is one JSON-serializable `StudioConfig`: scene fields (`background`, `quality`, `dprMax`,
 `loopSeconds`, `paused`, camera…) plus a `waves: WaveConfig[]` array (each wave has its own
-`palette`, `fiberCount`, `speed`, `displaceAmount`, `twist…`, `blendMode`, `theme`, transform…).
-Omitted fields fall back to `createDefaultConfig()`.
+`palette`, `fiberCount`, `speed`, `displaceAmount`, `twist…`, `helix…`, `blendMode`, `theme`,
+transform…). Omitted fields fall back to `createDefaultConfig()`.
+
+**Shape: twist vs helix.** `twistFrequency`/`twistPower` rotate by `freq * expStep(uv, power)`, a
+MONOTONE falloff — good for one dramatic ramp, but it can never repeat, so it cannot make a coil.
+`helixTurns` sweeps a _periodic_ angle along the ribbon's length instead, and is the only way to get
+a repeating helix:
+
+- `helixRadius` carries the whole ribbon around the axis (orientation intact). A narrow ribbon
+  (small `scale.z`) then reads as one strand — **two waves 180° apart in `helixPhase` are a double
+  helix**, and they genuinely swap depth at every crossing.
+- `helixRoll` rolls the ribbon's own cross-section in step (1 = rigid twisted ribbon), swinging its
+  two long edges onto opposite sides of the axis, so **one wave becomes a ladder whose edges are
+  both strands**. Add `rungAmount` (wireframe theme) for the rungs between them.
+- Both are off at 0, and the helix code path isn't compiled unless `helixRadius` or `helixRoll` is
+  non-zero — a wave without one renders byte-identically to before.
 
 **React flat props** are a shortcut mapped onto `waves[0]` and the scene:
 `palette` (`string[]` | `ColorStop[]`), `fiberCount`, `fiberStrength`, `sheen`, `iridescence`,
@@ -124,13 +132,23 @@ Sources: `scroll`, `hover`, `pointerX` / `pointerY`, `pointerSpeed`, `press`, `s
 `appear`, or a developer-fed `custom:*` (via `handle.setInteractionInput(name, value)` /
 `renderer.setInteractionInput`). Each binding rests at the authored value and moves toward `to` as
 its input rises 0→1 — `{ source: "hover", target: "displaceAmount", to: 12 }` grows the folds on
-hover. Each wave's `hover.smoothing` sets its own cursor-follow lag (vary it across a stack for a
-parallax drag). **Shared inputs** (one cursor + scroll: `radius`, `touch`) and **scene-param
+hover. `helixPhase` / `helixTurns` / `helixRadius` are bindable too, so
+`{ source: "scroll", target: "helixPhase", to: 360 }` spins a helix exactly one turn down the page
+(and the helix path is compiled for a wave that binds one but authors radius/roll at 0). Each wave's
+`hover.smoothing` sets its own cursor-follow lag (vary it across a stack for a parallax drag). **Shared inputs** (one cursor + scroll: `radius`, `touch`) and **scene-param
 bindings** (`timeOffset`, `cameraZoom`, `blur`, `grain` — e.g. `scroll → timeOffset` scrubs the whole
 wave with the page) live on `SceneConfig.interaction`. In React the flat `interaction` prop targets
 the first wave; the studio authors it per wave (Hover / Click & touch / Bindings) plus a global
 Interaction folder for the shared inputs and a scroll preview.
 
+**Touch is ignored unless you opt in.** `SceneConfig.interaction.touch` defaults to `false`, and
+coarse pointers are dropped before any handler runs — so on a phone, `hover`, `press`/`ripple` and
+the `hover` / `pointerX` / `pointerY` / `pointerSpeed` / `press` sources are all inert no matter what
+you tune. Set `interaction: { touch: true }` on the scene to follow the finger while it is down
+(listeners are passive, so this does **not** block page scrolling). Untouched by the gate: `scroll`,
+`scrollVelocity` and `appear` read container progress through the viewport, not pointer events, so
+they drive normally on mobile — scroll bindings are the way to stay reactive with `touch` off.
+
 ## Post effects (optional)
 
 Passes over the finished composite. Each is a plain **scene-level** `SceneConfig` field (a sibling of