@wave3d/core 0.5.0 → 0.7.0

package/dist/standalone.d.ts

@@ -1,13 +1,12 @@
-import { BackgroundImageFit, BackgroundMode, BasicGradientType, BlendMode, CAMERA_FITS, CameraFit, ColorStop, DEFAULT_LIGHT_POSITION, GradientType, InteractionSource, LightConfig, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, MeshGradientPoint, NoiseBand, PaletteSource, SceneConfig, SceneInteractionBinding, SceneInteractionConfig, SceneInteractionTarget, StudioConfig, Vec2, Vec3, WaveConfig, WaveHoverConfig, WaveInteractionBinding, WaveInteractionConfig, WaveInteractionTarget, WavePressConfig, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, normalizeBackground, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves } from "./config/model.js";
+import { BackgroundImageFit, BackgroundMode, BasicGradientType, BlendMode, CAMERA_FITS, CameraFit, ColorStop, DEFAULT_LIGHT_POSITION, GradientType, InteractionSource, LightConfig, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, MeshGradientPoint, NoiseBand, PARTICLE_SHAPES, PaletteSource, ParticleShape, ParticlesConfig, SceneConfig, SceneInteractionBinding, SceneInteractionConfig, SceneInteractionTarget, StudioConfig, Vec2, Vec3, WaveConfig, WaveHoverConfig, WaveInteractionBinding, WaveInteractionConfig, WaveInteractionTarget, WavePressConfig, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, normalizeBackground, normalizeParticles, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves } from "./config/model.js";
 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;
 /** The drop-in embed contract: an alias of {@link createWave}. */
 declare const mountWave: typeof createWave;
 //#endregion
-export { BackgroundImageFit, BackgroundMode, BasicGradientType, BlendMode, CAMERA_FITS, CameraFit, ColorStop, DEFAULT_LIGHT_POSITION, type FallbackReason, GradientType, InteractionSource, LightConfig, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, MeshGradientPoint, NoiseBand, PRESETS, PaletteSource, SceneConfig, SceneInteractionBinding, SceneInteractionConfig, SceneInteractionTarget, type SnapshotOptions, StudioConfig, Vec2, Vec3, WaveConfig, type WaveHandle, WaveHoverConfig, WaveInteractionBinding, WaveInteractionConfig, WaveInteractionTarget, type WaveOptions, WavePressConfig, WaveRenderer, type WaveState, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, createWave, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, mountWave, normalizeBackground, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves };
+export { BackgroundImageFit, BackgroundMode, BasicGradientType, BlendMode, CAMERA_FITS, CameraFit, ColorStop, DEFAULT_LIGHT_POSITION, type FallbackReason, GradientType, InteractionSource, LightConfig, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, MeshGradientPoint, NoiseBand, PARTICLE_SHAPES, PRESETS, PaletteSource, ParticleShape, ParticlesConfig, SceneConfig, SceneInteractionBinding, SceneInteractionConfig, SceneInteractionTarget, type SnapshotOptions, StudioConfig, Vec2, Vec3, WaveConfig, type WaveHandle, WaveHoverConfig, WaveInteractionBinding, WaveInteractionConfig, WaveInteractionTarget, type WaveOptions, WavePressConfig, WaveRenderer, type WaveState, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, createWave, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, mountWave, normalizeBackground, normalizeParticles, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves };
 //# sourceMappingURL=standalone.d.ts.map

package/dist/standalone.js

@@ -1,4 +1,4 @@
-import { CAMERA_FITS, DEFAULT_LIGHT_POSITION, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, normalizeBackground, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves } from "./config/model.js";
+import { CAMERA_FITS, DEFAULT_LIGHT_POSITION, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, PARTICLE_SHAPES, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, normalizeBackground, normalizeParticles, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves } from "./config/model.js";
 import { createWaveImpl } from "./shell/createWave.js";
 import { WaveRenderer } from "./renderer/WaveRenderer.js";
 import { PRESETS } from "./presets.js";
@@ -12,6 +12,6 @@ function createWave(container, config = {}, options = {}) {
 /** The drop-in embed contract: an alias of {@link createWave}. */
 const mountWave = createWave;
 //#endregion
-export { CAMERA_FITS, DEFAULT_LIGHT_POSITION, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, PRESETS, WaveRenderer, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, createWave, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, mountWave, normalizeBackground, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves };
+export { CAMERA_FITS, DEFAULT_LIGHT_POSITION, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, PARTICLE_SHAPES, PRESETS, WaveRenderer, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, createWave, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, mountWave, normalizeBackground, normalizeParticles, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves };
 
 //# sourceMappingURL=standalone.js.map

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,11 +1,10 @@
 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;
-/** Mutate `cfg` for a thumbnail still: static frame, opaque, white page behind solid themes
- *  (wireframe keys its between-line colour off the dark page background, so keep it). */
+/** Mutate `cfg` for a thumbnail still: static frame, opaque, and a background chosen to show the
+ *  wave off. */
 declare function prepThumbConfig(cfg: StudioConfig): void;
 /** Render the current config to a fresh 2D canvas (null if the WebGL canvas is missing). */
 declare function renderThumbFrame(renderer: WaveRenderer, host: HTMLElement): HTMLCanvasElement | null;

package/dist/studio/thumbnail.js

@@ -6,12 +6,25 @@ function createThumbHost(width, height) {
 	document.body.appendChild(host);
 	return host;
 }
-/** Mutate `cfg` for a thumbnail still: static frame, opaque, white page behind solid themes
-*  (wireframe keys its between-line colour off the dark page background, so keep it). */
+/** Luminance (0..1) of a solid `#rrggbb` background, or null if the background isn't a plain colour
+*  (gradient / image — no single swatch to judge). */
+function solidBgLuminance(cfg) {
+	if (cfg.backgroundMode !== "color") return null;
+	const m = /^#?([\da-f]{6})$/i.exec(cfg.background ?? "");
+	if (!m) return null;
+	const n = Number.parseInt(m[1], 16);
+	return (.2126 * (n >> 16 & 255) + .7152 * (n >> 8 & 255) + .0722 * (n & 255)) / 255;
+}
+/** Mutate `cfg` for a thumbnail still: static frame, opaque, and a background chosen to show the
+*  wave off. */
 function prepThumbConfig(cfg) {
 	cfg.paused = true;
 	cfg.transparentBackground = false;
-	if (cfg.waves[0]?.theme !== "wireframe") cfg.background = "#ffffff";
+	const lum = solidBgLuminance(cfg);
+	if (cfg.waves[0]?.theme === "wireframe" || lum !== null && lum < .22) return;
+	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/** Luminance (0..1) of a solid `#rrggbb` background, or null if the background isn't a plain colour\n *  (gradient / image — no single swatch to judge). */\nfunction solidBgLuminance(cfg: StudioConfig): number | null {\n  if (cfg.backgroundMode !== \"color\") return null;\n  const m = /^#?([\\da-f]{6})$/i.exec(cfg.background ?? \"\");\n  if (!m) return null;\n  const n = Number.parseInt(m[1], 16);\n  return (0.2126 * ((n >> 16) & 255) + 0.7152 * ((n >> 8) & 255) + 0.0722 * (n & 255)) / 255;\n}\n\n/** Mutate `cfg` for a thumbnail still: static frame, opaque, and a background chosen to show the\n *  wave off. */\nexport function prepThumbConfig(cfg: StudioConfig): void {\n  cfg.paused = true;\n  cfg.transparentBackground = false;\n  // Keep the authored background when the preset was designed on a dark ground: wireframe (its\n  // between-line colour keys off the dark page), or any solid theme on its own dark, opaque colour\n  // (e.g. Latte Ring — a warm ring that a white card just washes out). A bright wave reads fine\n  // against dark and bloom behaves there.\n  const lum = solidBgLuminance(cfg);\n  if (cfg.waves[0]?.theme === \"wireframe\" || (lum !== null && lum < 0.22)) return;\n  // Otherwise swap in a white card so the SHAPE stands out, and zero the light-scatter passes: they\n  // were tuned against the dark original, and white sits far above any sane threshold, so they'd\n  // bloom the card itself and wash the frame out (a bloomed preset rendered a blank white thumbnail\n  // — 0.3% non-white pixels — until this zeroed them).\n  cfg.background = \"#ffffff\";\n  cfg.bloomStrength = 0;\n  cfg.innerLight = 0;\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,SAAS,iBAAiB,KAAkC;CAC1D,IAAI,IAAI,mBAAmB,SAAS,OAAO;CAC3C,MAAM,IAAI,oBAAoB,KAAK,IAAI,cAAc,EAAE;CACvD,IAAI,CAAC,GAAG,OAAO;CACf,MAAM,IAAI,OAAO,SAAS,EAAE,IAAI,EAAE;CAClC,QAAQ,SAAW,KAAK,KAAM,OAAO,SAAW,KAAK,IAAK,OAAO,SAAU,IAAI,QAAQ;AACzF;;;AAIA,SAAgB,gBAAgB,KAAyB;CACvD,IAAI,SAAS;CACb,IAAI,wBAAwB;CAK5B,MAAM,MAAM,iBAAiB,GAAG;CAChC,IAAI,IAAI,MAAM,EAAE,EAAE,UAAU,eAAgB,QAAQ,QAAQ,MAAM,KAAO;CAKzE,IAAI,aAAa;CACjB,IAAI,gBAAgB;CACpB,IAAI,aAAa;AACnB;;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.7.0",
   "description": "Framework-agnostic 3D gradient-wave renderer + config model (the engine behind Wave Studio)",
   "keywords": [
     "animation",
@@ -54,10 +54,11 @@
     "access": "public"
   },
   "devDependencies": {
-    "@tanstack/intent": "^0.3.4",
+    "@tanstack/intent": "^0.3.6",
     "@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",
@@ -69,8 +70,11 @@
     }
   },
   "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",
+    "skill:stale": "intent stale skills",
+    "skill:validate": "intent validate skills",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
 }

package/skills/wave3d/SKILL.md

@@ -10,7 +10,7 @@ description: >
 metadata:
   type: core
   library: "@wave3d/core"
-  library_version: "0.5.0"
+  library_version: "0.7.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