@wave3d/core 0.5.0 → 0.6.0

package/README.md

@@ -40,9 +40,7 @@ const blob = await handle.snapshot(); // resolves null until running. options: {
 ```html
 <script type="module">
   import { mountWave } from "https://esm.sh/@wave3d/core/standalone";
-  mountWave(document.getElementById("wave"), {
-    /* your exported config */
-  });
+  mountWave(document.getElementById("wave"), {/* your exported config */});
 </script>
 ```
 
@@ -76,9 +74,7 @@ createWave(el, {
     touch: false, // follow touch pointers too
     bindings: [{ source: "scroll", target: "timeOffset", to: 40 }], // scrub the whole wave with scroll
   },
-  waves: [
-    /* each wave carries its own `interaction` (hover / press / bindings) */
-  ],
+  waves: [/* each wave carries its own `interaction` (hover / press / bindings) */],
 });
 ```
 

package/dist/config/model.d.ts

@@ -148,10 +148,34 @@ interface WaveConfig {
   twistFrequency: Vec3;
   twistPower: Vec3;
   twistMotion?: boolean;
+  /** Helix: sweep the ribbon around its OWN length axis, `helixTurns` full turns from end to end.
+   *  The three twists above can't express this — their axes sit 45°/90° off the length, and
+   *  `expStep` is a monotone falloff, so nothing they do ever repeats. This angle is periodic in the
+   *  length coordinate instead, which is what makes a helix (and a DNA ladder) reachable.
+   *  0 turns still leaves the block inert unless radius or roll is non-zero. */
+  helixTurns?: number;
+  /** Carries the WHOLE ribbon around the axis at this radius (world units, pre-scale), keeping its
+   *  orientation. A narrow ribbon then reads as a single strand — two waves half a turn apart in
+   *  `helixPhase` are the two strands of a double helix. 0 = off. */
+  helixRadius?: number;
+  /** Rolls the ribbon's own cross-section about the axis as it advances, as a fraction of
+   *  `helixTurns` (1 = rolls exactly in step, a rigid twisted ribbon). That swings the ribbon's two
+   *  long edges onto opposite sides of the axis, so ONE wave becomes a ladder whose edges are both
+   *  strands — pair it with `rungAmount` for the rungs between them. 0 = off. */
+  helixRoll?: number;
+  /** Phase offset in degrees — where along the turn the ribbon starts. The per-wave knob that puts
+   *  a second wave on the opposite side of the same helix (180). */
+  helixPhase?: number;
   theme?: "solid" | "wireframe";
   lineAmount?: number;
   lineThickness?: number;
   lineDerivativePower?: number;
+  /** Wireframe RUNGS: a second line family carved at constant uv.y, so these run ACROSS the ribbon
+   *  where `lineAmount`'s run along it — the two cross into a ladder. Frequency, like `lineAmount`
+   *  (rungs ≈ amount / π). 0 = off, and the cross-wise path isn't compiled. */
+  rungAmount?: number;
+  /** Rung line width, in pixels (screen-space, so it holds at any zoom). */
+  rungThickness?: number;
   maxWidth?: number;
   position: Vec3;
   rotation: Vec3;
@@ -174,7 +198,7 @@ interface WaveConfig {
 type InteractionSource = "scroll" | "hover" | "pointerX" | "pointerY" | "pointerSpeed" | "press" | "scrollVelocity" | "appear" | `custom:${string}`;
 /** Per-WAVE params a binding may drive. Single source of truth for WAVE_APPLIERS in
  *  renderer/interaction.ts (checked via `satisfies`) and validated by normalizeWaveInteraction. */
-declare const WAVE_TARGET_NAMES: readonly ["displaceAmount", "detailAmount", "twistPowerX", "twistPowerY", "twistPowerZ", "twistFrequencyX", "twistFrequencyY", "twistFrequencyZ", "hueShift", "gradientShift", "colorSaturation", "opacity", "lineThickness", "lineAmount", "fiberStrength", "sheen", "iridescence", "positionX", "positionY"];
+declare const WAVE_TARGET_NAMES: readonly ["displaceAmount", "detailAmount", "twistPowerX", "twistPowerY", "twistPowerZ", "twistFrequencyX", "twistFrequencyY", "twistFrequencyZ", "helixPhase", "helixTurns", "helixRadius", "hueShift", "gradientShift", "colorSaturation", "opacity", "lineThickness", "lineAmount", "fiberStrength", "sheen", "iridescence", "positionX", "positionY"];
 /** A per-wave param a {@link WaveInteractionBinding} can drive. */
 type WaveInteractionTarget = (typeof WAVE_TARGET_NAMES)[number];
 /** SCENE params a binding may drive (post / camera / time — shared, not per wave). Single source of

package/dist/config/model.js

@@ -119,6 +119,9 @@ const WAVE_TARGET_NAMES = [
 	"twistFrequencyX",
 	"twistFrequencyY",
 	"twistFrequencyZ",
+	"helixPhase",
+	"helixTurns",
+	"helixRadius",
 	"hueShift",
 	"gradientShift",
 	"colorSaturation",
@@ -263,10 +266,16 @@ function defaultWave() {
 			z: 6.33
 		},
 		twistMotion: false,
+		helixTurns: 0,
+		helixRadius: 0,
+		helixRoll: 0,
+		helixPhase: 0,
 		theme: "solid",
 		lineAmount: 425,
 		lineThickness: 1,
 		lineDerivativePower: .95,
+		rungAmount: 0,
+		rungThickness: 1,
 		maxWidth: 1232,
 		position: {
 			x: -24.3,
@@ -377,7 +386,8 @@ function createDefaultConfig() {
 *  ColorStop[]; mesh points + texture transform are clamped). */
 function normalizeWaveColour(config) {
 	const p = config.palette;
-	if (p.length > 0 && typeof p[0] === "string") config.palette = makeStops(p);
+	if (!Array.isArray(p) || p.length === 0) config.palette = defaultWave().palette;
+	else if (typeof p[0] === "string") config.palette = makeStops(p);
 	if (config.gradientType !== "radial" && config.gradientType !== "conic" && config.gradientType !== "mesh" && config.gradientType !== "linear") config.gradientType = "linear";
 	const rawMeshPoints = config.meshGradientPoints;
 	if (!Array.isArray(rawMeshPoints) || rawMeshPoints.length < 2) config.meshGradientPoints = createDefaultMeshPoints();
@@ -414,6 +424,8 @@ function normalizeWaveColour(config) {
 }
 /** Backfill background styling for states saved before gradient/image backgrounds existed. */
 function normalizeBackground(config) {
+	if (typeof config.background !== "string") config.background = "#ffffff";
+	if (typeof config.transparentBackground !== "boolean") config.transparentBackground = true;
 	if (config.backgroundMode !== "gradient" && config.backgroundMode !== "image" && config.backgroundMode !== "color") config.backgroundMode = "color";
 	const palette = config.backgroundPalette;
 	if (!palette || palette.length < 2) config.backgroundPalette = makeStops([
@@ -428,11 +440,11 @@ function normalizeBackground(config) {
 	if (!Array.isArray(bgMesh) || bgMesh.length < 2) config.backgroundMeshPoints = createDefaultMeshPoints();
 	if (!Number.isFinite(config.backgroundMeshSoftness)) config.backgroundMeshSoftness = .62;
 	config.backgroundMeshSoftness = clamp01(config.backgroundMeshSoftness);
-	if (typeof config.backgroundGradientAngle !== "number") config.backgroundGradientAngle = 135;
+	if (!Number.isFinite(config.backgroundGradientAngle)) config.backgroundGradientAngle = 135;
 	if (typeof config.backgroundGradientSource !== "string") config.backgroundGradientSource = "stops";
 	if (typeof config.backgroundImageSource !== "string") config.backgroundImageSource = "vaporwave";
 	if (config.backgroundImageFit !== "contain" && config.backgroundImageFit !== "stretch" && config.backgroundImageFit !== "cover") config.backgroundImageFit = "cover";
-	if (typeof config.backgroundImageZoom !== "number") config.backgroundImageZoom = 1;
+	if (!Number.isFinite(config.backgroundImageZoom)) config.backgroundImageZoom = 1;
 	config.backgroundImageZoom = clamp(config.backgroundImageZoom, .1, 8);
 	if (!config.backgroundImagePosition) config.backgroundImagePosition = {
 		x: 0,
@@ -455,45 +467,46 @@ function ensureCamera(config) {
 		y: 0,
 		z: 0
 	};
-	if (typeof config.cameraZoom !== "number") config.cameraZoom = 1;
+	if (!Number.isFinite(config.cameraZoom)) config.cameraZoom = 1;
 	if (!CAMERA_FITS.includes(config.cameraFit)) config.cameraFit = "cover";
 	config.cameraMinVisibleWidth = typeof config.cameraMinVisibleWidth === "number" ? clamp(config.cameraMinVisibleWidth, 0, 1) : 0;
 }
 /** Backfill/repair a wave so the renderer can consume it (covers partial wave-model JSON). */
 function normalizeWave(s) {
 	normalizeWaveColour(s);
-	if (typeof s.gradientAngle !== "number") s.gradientAngle = 90;
-	if (typeof s.gradientShift !== "number") s.gradientShift = .15;
+	if (!Number.isFinite(s.gradientAngle)) s.gradientAngle = 90;
+	if (!Number.isFinite(s.gradientShift)) s.gradientShift = .15;
 	if (typeof s.usePaletteTexture !== "boolean") s.usePaletteTexture = true;
 	if (typeof s.paletteSource !== "string") s.paletteSource = "hero";
 	if (typeof s.paletteEdgeColor !== "string") s.paletteEdgeColor = "#8e9dff";
-	if (typeof s.paletteEdgeAmount !== "number") s.paletteEdgeAmount = .3;
-	if (typeof s.paletteDriftX !== "number") s.paletteDriftX = 0;
-	if (typeof s.paletteDriftY !== "number") s.paletteDriftY = 0;
-	if (typeof s.hueShift !== "number") s.hueShift = 0;
-	if (typeof s.colorContrast !== "number") s.colorContrast = 1;
-	if (typeof s.colorSaturation !== "number") s.colorSaturation = 1;
-	if (typeof s.fiberCount !== "number") s.fiberCount = 600;
-	if (typeof s.fiberStrength !== "number") s.fiberStrength = .2;
+	if (!Number.isFinite(s.paletteEdgeAmount)) s.paletteEdgeAmount = .3;
+	if (!Number.isFinite(s.paletteDriftX)) s.paletteDriftX = 0;
+	if (!Number.isFinite(s.paletteDriftY)) s.paletteDriftY = 0;
+	if (!Number.isFinite(s.hueShift)) s.hueShift = 0;
+	if (!Number.isFinite(s.colorContrast)) s.colorContrast = 1;
+	if (!Number.isFinite(s.colorSaturation)) s.colorSaturation = 1;
+	if (!Number.isFinite(s.fiberCount)) s.fiberCount = 600;
+	if (!Number.isFinite(s.fiberStrength)) s.fiberStrength = .2;
 	if (!Array.isArray(s.noiseBands)) s.noiseBands = [];
-	if (typeof s.texture !== "number") s.texture = 0;
-	if (typeof s.creaseLight !== "number") s.creaseLight = .6;
-	if (typeof s.creaseSharpness !== "number") s.creaseSharpness = .589;
-	if (typeof s.creaseSoftness !== "number") s.creaseSoftness = 1;
-	if (typeof s.sheen !== "number") s.sheen = 0;
-	if (typeof s.roundness !== "number") s.roundness = 0;
-	if (typeof s.iridescence !== "number") s.iridescence = 0;
-	if (typeof s.edgeFade !== "number") s.edgeFade = .04;
-	if (typeof s.edgeFeather !== "number") s.edgeFeather = .1;
-	if (typeof s.depthTint !== "number") s.depthTint = 0;
+	normalizeNoiseBands(s);
+	if (!Number.isFinite(s.texture)) s.texture = 0;
+	if (!Number.isFinite(s.creaseLight)) s.creaseLight = .6;
+	if (!Number.isFinite(s.creaseSharpness)) s.creaseSharpness = .589;
+	if (!Number.isFinite(s.creaseSoftness)) s.creaseSoftness = 1;
+	if (!Number.isFinite(s.sheen)) s.sheen = 0;
+	if (!Number.isFinite(s.roundness)) s.roundness = 0;
+	if (!Number.isFinite(s.iridescence)) s.iridescence = 0;
+	if (!Number.isFinite(s.edgeFade)) s.edgeFade = .04;
+	if (!Number.isFinite(s.edgeFeather)) s.edgeFeather = .1;
+	if (!Number.isFinite(s.depthTint)) s.depthTint = 0;
 	if (typeof s.depthTintColor !== "string") s.depthTintColor = "#0a2540";
 	if (!s.displaceFrequency) s.displaceFrequency = {
 		x: .003234,
 		y: .00799
 	};
-	if (typeof s.displaceAmount !== "number") s.displaceAmount = 6.051;
-	if (typeof s.detailFrequency !== "number") s.detailFrequency = .04;
-	if (typeof s.detailAmount !== "number") s.detailAmount = 0;
+	if (!Number.isFinite(s.displaceAmount)) s.displaceAmount = 6.051;
+	if (!Number.isFinite(s.detailFrequency)) s.detailFrequency = .04;
+	if (!Number.isFinite(s.detailAmount)) s.detailAmount = 0;
 	if (!s.twistFrequency) s.twistFrequency = {
 		x: -.055,
 		y: .077,
@@ -504,11 +517,18 @@ function normalizeWave(s) {
 		y: 5.85,
 		z: 6.33
 	};
+	if (typeof s.twistMotion !== "boolean") s.twistMotion = false;
+	if (!Number.isFinite(s.helixTurns)) s.helixTurns = 0;
+	if (!Number.isFinite(s.helixRadius)) s.helixRadius = 0;
+	if (!Number.isFinite(s.helixRoll)) s.helixRoll = 0;
+	if (!Number.isFinite(s.helixPhase)) s.helixPhase = 0;
 	if (typeof s.theme !== "string") s.theme = "solid";
-	if (typeof s.lineAmount !== "number") s.lineAmount = 425;
-	if (typeof s.lineThickness !== "number") s.lineThickness = 1;
-	if (typeof s.lineDerivativePower !== "number") s.lineDerivativePower = .95;
-	if (typeof s.maxWidth !== "number") s.maxWidth = 1232;
+	if (!Number.isFinite(s.lineAmount)) s.lineAmount = 425;
+	if (!Number.isFinite(s.lineThickness)) s.lineThickness = 1;
+	if (!Number.isFinite(s.lineDerivativePower)) s.lineDerivativePower = .95;
+	if (!Number.isFinite(s.rungAmount)) s.rungAmount = 0;
+	if (!Number.isFinite(s.rungThickness)) s.rungThickness = 1;
+	if (!Number.isFinite(s.maxWidth)) s.maxWidth = 1232;
 	if (!s.position) s.position = {
 		x: 0,
 		y: 0,
@@ -525,44 +545,46 @@ function normalizeWave(s) {
 		z: 7
 	};
 	if (typeof s.blendMode !== "string") s.blendMode = "squared";
-	if (typeof s.speed !== "number") s.speed = .04;
-	if (typeof s.opacity !== "number") s.opacity = 1;
-	if (typeof s.seed !== "number") s.seed = 0;
+	if (!Number.isFinite(s.speed)) s.speed = .04;
+	if (!Number.isFinite(s.opacity)) s.opacity = 1;
+	if (!Number.isFinite(s.seed)) s.seed = 0;
 	if (s.interaction) normalizeWaveInteraction(s);
 }
 /** Backfill scene-level defaults (background/camera/post/lights/quality/mirror). */
 function ensureSceneDefaults(config) {
 	normalizeBackground(config);
 	ensureCamera(config);
-	if (typeof config.ambient !== "number") config.ambient = .45;
+	if (!Number.isFinite(config.ambient)) config.ambient = .45;
 	if (!Array.isArray(config.lights)) config.lights = [];
-	if (typeof config.quality !== "number") config.quality = 1;
-	if (typeof config.dprMax !== "number") config.dprMax = 2;
-	if (typeof config.grain !== "number") config.grain = 1.1;
-	if (typeof config.blur !== "number") config.blur = .02;
-	if (typeof config.blurSamples !== "number") config.blurSamples = 6;
-	if (typeof config.bloomStrength !== "number") config.bloomStrength = 0;
-	if (typeof config.bloomRadius !== "number") config.bloomRadius = .4;
-	if (typeof config.bloomThreshold !== "number") config.bloomThreshold = .85;
-	if (typeof config.dither !== "number") config.dither = 0;
-	if (typeof config.ditherScale !== "number") config.ditherScale = 2;
-	if (typeof config.ditherSteps !== "number") config.ditherSteps = 4;
-	if (typeof config.innerLight !== "number") config.innerLight = 0;
-	if (typeof config.innerLightDensity !== "number") config.innerLightDensity = .5;
-	if (typeof config.innerLightDecay !== "number") config.innerLightDecay = .95;
-	if (typeof config.innerLightX !== "number") config.innerLightX = .5;
-	if (typeof config.innerLightY !== "number") config.innerLightY = .15;
-	if (typeof config.halftone !== "number") config.halftone = 0;
-	if (typeof config.halftoneCell !== "number") config.halftoneCell = 6;
-	if (typeof config.halftoneAngle !== "number") config.halftoneAngle = .4;
-	if (typeof config.heatmap !== "number") config.heatmap = 0;
-	if (typeof config.paperTexture !== "number") config.paperTexture = 0;
-	if (typeof config.paperTextureScale !== "number") config.paperTextureScale = 2;
-	if (typeof config.halftoneCmyk !== "number") config.halftoneCmyk = 0;
-	if (typeof config.halftoneCmykCell !== "number") config.halftoneCmykCell = 6;
+	normalizeLights(config);
+	if (!Number.isFinite(config.quality)) config.quality = 1;
+	if (!Number.isFinite(config.dprMax)) config.dprMax = 2;
+	if (!Number.isFinite(config.grain)) config.grain = 1.1;
+	if (!Number.isFinite(config.blur)) config.blur = .02;
+	if (!Number.isFinite(config.blurSamples)) config.blurSamples = 6;
+	if (!Number.isFinite(config.bloomStrength)) config.bloomStrength = 0;
+	if (!Number.isFinite(config.bloomRadius)) config.bloomRadius = .4;
+	if (!Number.isFinite(config.bloomThreshold)) config.bloomThreshold = .85;
+	if (!Number.isFinite(config.dither)) config.dither = 0;
+	if (!Number.isFinite(config.ditherScale)) config.ditherScale = 2;
+	if (!Number.isFinite(config.ditherSteps)) config.ditherSteps = 4;
+	if (!Number.isFinite(config.innerLight)) config.innerLight = 0;
+	if (!Number.isFinite(config.innerLightDensity)) config.innerLightDensity = .5;
+	if (!Number.isFinite(config.innerLightDecay)) config.innerLightDecay = .95;
+	if (!Number.isFinite(config.innerLightX)) config.innerLightX = .5;
+	if (!Number.isFinite(config.innerLightY)) config.innerLightY = .15;
+	if (!Number.isFinite(config.halftone)) config.halftone = 0;
+	if (!Number.isFinite(config.halftoneCell)) config.halftoneCell = 6;
+	if (!Number.isFinite(config.halftoneAngle)) config.halftoneAngle = .4;
+	if (!Number.isFinite(config.heatmap)) config.heatmap = 0;
+	if (!Number.isFinite(config.paperTexture)) config.paperTexture = 0;
+	if (!Number.isFinite(config.paperTextureScale)) config.paperTextureScale = 2;
+	if (!Number.isFinite(config.halftoneCmyk)) config.halftoneCmyk = 0;
+	if (!Number.isFinite(config.halftoneCmykCell)) config.halftoneCmykCell = 6;
 	if (typeof config.showCameraRig !== "boolean") config.showCameraRig = false;
 	if (typeof config.paused !== "boolean") config.paused = false;
-	if (typeof config.loopSeconds !== "number") config.loopSeconds = 0;
+	if (!Number.isFinite(config.timeOffset)) config.timeOffset = 0;
+	if (!Number.isFinite(config.loopSeconds)) config.loopSeconds = 0;
 	if (typeof config.mirrorH !== "boolean") config.mirrorH = false;
 	if (typeof config.mirrorV !== "boolean") config.mirrorV = false;
 }
@@ -571,6 +593,45 @@ function clampNumber(v, min, max, dflt) {
 	const n = Number(v);
 	return Number.isFinite(n) ? clamp(n, min, max) : dflt;
 }
+/** Coerce an untrusted field to a finite number, falling back to `dflt`. Deliberately does NOT
+*  clamp — it repairs broken values without reinterpreting out-of-range ones that a saved config
+*  may legitimately rely on. */
+function num(v, dflt) {
+	const n = Number(v);
+	return Number.isFinite(n) ? n : dflt;
+}
+/**
+* Repair the ELEMENTS of the scene's `lights` and a wave's `noiseBands`. Both arrays are
+* type-checked where they're backfilled, but their entries never were — and the studio binds every
+* field below directly, so one hand-authored `"lights": [{}]` was enough to make the whole control
+* panel unbuildable. Entries that aren't objects at all are dropped.
+*/
+function normalizeLights(config) {
+	config.lights = config.lights.filter((l) => typeof l === "object" && l !== null);
+	for (const l of config.lights) {
+		if (typeof l.position !== "object" || l.position === null) l.position = { ...DEFAULT_LIGHT_POSITION };
+		l.position.x = num(l.position.x, DEFAULT_LIGHT_POSITION.x);
+		l.position.y = num(l.position.y, DEFAULT_LIGHT_POSITION.y);
+		l.position.z = num(l.position.z, DEFAULT_LIGHT_POSITION.z);
+		if (typeof l.color !== "string") l.color = "#ffffff";
+		l.intensity = num(l.intensity, 1);
+	}
+}
+function normalizeNoiseBands(s) {
+	s.noiseBands = s.noiseBands.filter((b) => typeof b === "object" && b !== null);
+	const d = createNoiseBand();
+	for (const b of s.noiseBands) {
+		b.startX = num(b.startX, d.startX);
+		b.endX = num(b.endX, d.endX);
+		b.startY = num(b.startY, d.startY);
+		b.endY = num(b.endY, d.endY);
+		b.feather = num(b.feather, d.feather);
+		b.strength = num(b.strength, d.strength);
+		b.frequency = num(b.frequency, d.frequency);
+		b.colorAttenuation = num(b.colorAttenuation, d.colorAttenuation);
+		b.parabolaPower = num(b.parabolaPower, d.parabolaPower);
+	}
+}
 /** True for a valid interaction source string: a built-in name or a non-empty `custom:<name>`. */
 function isInteractionSource(v) {
 	return typeof v === "string" && (INTERACTION_SOURCE_NAMES.includes(v) || v.startsWith("custom:") && v.length > 7);