@wave3d/core 0.5.0 → 0.7.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

@@ -53,11 +53,14 @@ declare function createLight(position?: Vec3, intensity?: number): LightConfig;
  *  rig always shows the light — even before one has been explicitly added. */
 declare const DEFAULT_LIGHT_POSITION: Vec3;
 /**
- * A noise band: inside a rectangular uv region (startX..endX along the length,
- * startY..endY across the width, softened by `feather`), the fiber streaks are
- * overridden — strength, frequency (density), colourAttenuation (how much the local
- * colour suppresses them), and the end-weighting parabolaPower. Lets the fibers vary
+ * A noise band: inside a rectangular uv region, softened by `feather`, the fiber streaks
+ * are overridden — strength, frequency (density), colourAttenuation (how much the local
+ * colour suppresses them), and the edge-weighting parabolaPower. Lets the fibers vary
  * per region instead of uniform.
+ *
+ * Mind the axes, which are the reverse of what the names suggest: the bounds gate on uv,
+ * and uv.x is the folded WIDTH while uv.y is the LENGTH (see WaveGeometry's UV AXES note).
+ * So startX..endX span the SHORT axis and startY..endY run end to end.
  */
 interface NoiseBand {
   startX: number;
@@ -72,7 +75,8 @@ interface NoiseBand {
 }
 /** A default band: a strong, coarse streak region over the first half. */
 declare function createNoiseBand(): NoiseBand;
-/** One gradient stop: a colour at a normalized position (0–1) across the width. */
+/** One gradient stop: a colour at a normalized position (0–1) along the gradient ramp, whose
+ *  direction on the ribbon is set by `gradientType` / `gradientAngle`. */
 interface ColorStop {
   color: string;
   pos: number;
@@ -133,8 +137,9 @@ interface WaveConfig {
   /** Thin-film / holographic hue response that shifts with view angle (0 = off). */
   iridescence: number;
   edgeFade: number;
-  /** Softness of the ribbon's long edges (smoothstep width across uv.y). 0.1 = the original
-   *  hardcoded value; smaller = razor-crisp graphic ribbons, larger = soft vapor. */
+  /** Softness of the ribbon's two ENDS — it smoothsteps on uv.y, which is the length, not the
+   *  long edges. 0.1 = the original hardcoded value; smaller = razor-crisp graphic ribbons,
+   *  larger = soft vapor. */
   edgeFeather: number;
   /** Depth tint (solid theme): fade far fragments toward depthTintColor for atmospheric
    *  separation in multi-wave stacks (0 = off). */
@@ -148,10 +153,44 @@ 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;
+  /** Radial fan (optional): sweep the ribbon's length into a plume/peacock spread from the local
+   *  origin. The three twists and the helix can't reach it — this maps the ribbon to polar so the
+   *  combed fibers ({@link fiberCount}) read as the individual radial strands. Placement is the wave's
+   *  `position` transform (there is no separate pivot). Runs AFTER displace/helix/twist, behind
+   *  `#ifdef RADIAL`, so `radialAmount` 0 leaves the block uncompiled and the wave byte-identical. */
+  radialAmount?: number;
+  radialArc?: number;
+  radialSpread?: number;
+  radialRadius?: number;
+  radialCenter?: 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;
@@ -166,6 +205,9 @@ interface WaveConfig {
   /** Optional per-wave interactivity: how THIS wave reacts to the shared pointer + inputs (hover
    *  field, click ripples, param bindings). ABSENT = this wave is inert / byte-identical. */
   interaction?: WaveInteractionConfig;
+  /** Optional per-wave particle / dust field emitted off THIS wave's deformed surface / edge.
+   *  ABSENT ⇒ off (no THREE.Points for this wave, byte-identical). See {@link ParticlesConfig}. */
+  particles?: ParticlesConfig;
 }
 /**
  * An interaction INPUT: a normalized signal that can smoothly drive config params through an
@@ -174,7 +216,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
@@ -259,6 +301,46 @@ interface SceneInteractionConfig {
   /** Input→param bindings driving SCENE params (timeOffset, cameraZoom, blur, grain). */
   bindings?: SceneInteractionBinding[];
 }
+/**
+ * A WAVE's field of additive GPU sprites (dust / sparkle). Lives on {@link WaveConfig} — particles
+ * belong to a wave, not the scene. ABSENT ⇒ off: no THREE.Points node is created for that wave and its
+ * render is byte-identical; present ⇒ {@link normalizeParticles} clamps it. Every particle's motion is a
+ * pure function of `uTime` + a per-particle seed baked from `seed`, so it is deterministic (timeOffset
+ * scrub / loopSeconds / paused all hold). Particles spawn on the OWNING wave's DEFORMED surface / edge
+ * (via the shared waveShape) and drift outward from the wave centre.
+ */
+/** How each particle sprite is drawn (a per-field render style, not per-particle). */
+type ParticleShape = "glitter" | "soft" | "ring" | "star" | "streak";
+declare const PARTICLE_SHAPES: readonly ParticleShape[];
+interface ParticlesConfig {
+  count: number;
+  size: number;
+  seed: number;
+  sizeJitter?: number;
+  color?: string;
+  /** Second sprite colour — particles interpolate between `color` and this by their seed (two-tone dust). */
+  color2?: string;
+  life?: number;
+  /** Motion-speed multiplier for the dust: how fast particles cycle + drift (1 = default, 0 = frozen).
+   *  Independent of the wave's own `speed` (which animates the surface the dust rides). Under a seamless
+   *  `loopSeconds` it snaps to a whole number of cycles so the loop stays seamless. */
+  speed?: number;
+  twinkle?: number;
+  /** Where on the wave particles spawn: 0 = across the whole SURFACE, 1 = the outer rim / EDGE only. */
+  edgeBias?: number;
+  /** How far particles drift outward from the wave centre as they age (world units). */
+  drift?: number;
+  /** −1..1 skew of the spawn along the edge width toward one flank (0 = even, −1 → one side, +1 → other). */
+  bias?: number;
+  /** Screen-vertical buoyancy over a lifetime, world units: + rises (embers), − falls (snow / ash). */
+  rise?: number;
+  /** Orbit around the wave centre in the screen plane, turns per lifetime (swirls the dust). */
+  swirl?: number;
+  /** Curl-noise turbulence: particles meander (fireflies / motes) instead of moving in straight lines. */
+  wander?: number;
+  /** Sprite render style. Default "glitter" (the soft round additive disc). */
+  shape?: ParticleShape;
+}
 /**
  * Scene-level settings shared by every wave: output/background/camera/lights, the post-fx
  * pass (grain/blur), playback, quality, and the whole-composition mirror. Everything that
@@ -395,10 +477,16 @@ declare function normalizeWaveInteraction(wave: WaveConfig): void;
 /** Present-only normalizer for the SCENE interaction block: clamp the shared pointer inputs and drop
  *  invalid scene bindings. NEVER call when the block is absent. */
 declare function normalizeSceneInteraction(config: StudioConfig): void;
+/**
+ * Present-only normalizer for the scene PARTICLES block: clamp the numerics that are present and
+ * repair the required fields, leaving absent optionals absent (so the block stays lean). NEVER call
+ * when the block is absent — absence is off and byte-identical (ensureStudioConfig gates on presence).
+ */
+declare function normalizeParticles(wave: WaveConfig): void;
 /** Normalize an ingested config to the wave model: backfill the scene + every wave, and drop in
  *  a default wave if none are present. Idempotent, so it is safe on the renderer's own config as
  *  well as freshly loaded save-states / share links. */
 declare function ensureStudioConfig(input: StudioConfig): StudioConfig;
 //#endregion
-export { 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 };
+export { 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 };
 //# sourceMappingURL=model.d.ts.map

package/dist/config/model.js

@@ -119,6 +119,9 @@ const WAVE_TARGET_NAMES = [
 	"twistFrequencyX",
 	"twistFrequencyY",
 	"twistFrequencyZ",
+	"helixPhase",
+	"helixTurns",
+	"helixRadius",
 	"hueShift",
 	"gradientShift",
 	"colorSaturation",
@@ -139,6 +142,13 @@ const SCENE_TARGET_NAMES = [
 	"blur",
 	"grain"
 ];
+const PARTICLE_SHAPES = [
+	"glitter",
+	"soft",
+	"ring",
+	"star",
+	"streak"
+];
 /** Spread a base wave into `count` overlapping waves — each with a slightly varied hue, width,
 *  speed, phase, vertical offset and roll so a stack reads as one composition. `count === 1`
 *  returns the base unchanged. Used to author multi-wave presets. */
@@ -263,10 +273,21 @@ function defaultWave() {
 			z: 6.33
 		},
 		twistMotion: false,
+		helixTurns: 0,
+		helixRadius: 0,
+		helixRoll: 0,
+		helixPhase: 0,
+		radialAmount: 0,
+		radialArc: 160,
+		radialSpread: 1,
+		radialRadius: 40,
+		radialCenter: 0,
 		theme: "solid",
 		lineAmount: 425,
 		lineThickness: 1,
 		lineDerivativePower: .95,
+		rungAmount: 0,
+		rungThickness: 1,
 		maxWidth: 1232,
 		position: {
 			x: -24.3,
@@ -377,7 +398,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 +436,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 +452,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 +479,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 +529,23 @@ 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 (!Number.isFinite(s.radialAmount)) s.radialAmount = 0;
+	if (!Number.isFinite(s.radialArc)) s.radialArc = 160;
+	if (!Number.isFinite(s.radialSpread)) s.radialSpread = 1;
+	if (!Number.isFinite(s.radialRadius)) s.radialRadius = 40;
+	if (!Number.isFinite(s.radialCenter)) s.radialCenter = 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 +562,47 @@ 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);
+	if (s.particles) normalizeParticles(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 +611,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);
@@ -632,6 +711,31 @@ function normalizeSceneInteraction(config) {
 	if (it.ribbonFlow !== void 0) it.ribbonFlow = clampNumber(it.ribbonFlow, 0, 1, .8);
 	if (it.bindings !== void 0) it.bindings = cleanBindings(it.bindings, SCENE_TARGET_NAMES);
 }
+/**
+* Present-only normalizer for the scene PARTICLES block: clamp the numerics that are present and
+* repair the required fields, leaving absent optionals absent (so the block stays lean). NEVER call
+* when the block is absent — absence is off and byte-identical (ensureStudioConfig gates on presence).
+*/
+function normalizeParticles(wave) {
+	const p = wave.particles;
+	if (!p) return;
+	p.count = clampNumber(p.count, 0, 4e4, 0);
+	p.size = clampNumber(p.size, 0, 200, 2);
+	p.seed = num(p.seed, 0);
+	if (p.sizeJitter !== void 0) p.sizeJitter = clampNumber(p.sizeJitter, 0, 1, 0);
+	if (p.color !== void 0 && typeof p.color !== "string") p.color = "#ffcf8a";
+	if (p.life !== void 0) p.life = clampNumber(p.life, .1, 60, 6);
+	if (p.speed !== void 0) p.speed = clampNumber(p.speed, 0, 8, 1);
+	if (p.twinkle !== void 0) p.twinkle = clampNumber(p.twinkle, 0, 1, 0);
+	if (p.color2 !== void 0 && typeof p.color2 !== "string") p.color2 = "#ffcf8a";
+	if (p.edgeBias !== void 0) p.edgeBias = clampNumber(p.edgeBias, 0, 1, 1);
+	if (p.drift !== void 0) p.drift = num(p.drift, 0);
+	if (p.bias !== void 0) p.bias = clampNumber(p.bias, -1, 1, 0);
+	if (p.rise !== void 0) p.rise = num(p.rise, 0);
+	if (p.swirl !== void 0) p.swirl = num(p.swirl, 0);
+	if (p.wander !== void 0) p.wander = num(p.wander, 0);
+	if (p.shape !== void 0 && !PARTICLE_SHAPES.includes(p.shape)) p.shape = "glitter";
+}
 /** Normalize an ingested config to the wave model: backfill the scene + every wave, and drop in
 *  a default wave if none are present. Idempotent, so it is safe on the renderer's own config as
 *  well as freshly loaded save-states / share links. */
@@ -645,6 +749,6 @@ function ensureStudioConfig(input) {
 	return config;
 }
 //#endregion
-export { 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 };
+export { 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 };
 
 //# sourceMappingURL=model.js.map