@wave3d/core 0.9.0 → 0.11.0

package/dist/standalone.d.ts

@@ -1,4 +1,4 @@
-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, TiltConfig, 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 { BackgroundImageFit, BackgroundMode, BasicGradientType, BlendMode, CAMERA_FITS, CameraFit, ColorStop, DEFAULT_LIGHT_POSITION, DISSOLVE_AXES, DissolveAxis, DissolveConfig, GradientType, InteractionSource, LightConfig, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, MeshGradientPoint, NoiseBand, PARTICLE_SHAPES, PaletteSource, ParticleShape, ParticlesConfig, PathPoint, SceneConfig, SceneInteractionBinding, SceneInteractionConfig, SceneInteractionTarget, StudioConfig, TiltConfig, Vec2, Vec3, WaveConfig, WaveHoverConfig, WaveInteractionBinding, WaveInteractionConfig, WaveInteractionTarget, WavePressConfig, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, normalizeBackground, normalizeDissolve, normalizeParticles, normalizePath, 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";
@@ -15,5 +15,5 @@ declare function createWave(container: HTMLElement, config?: Partial<StudioConfi
 /** 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, PARTICLE_SHAPES, PRESETS, PaletteSource, ParticleShape, ParticlesConfig, SceneConfig, SceneInteractionBinding, SceneInteractionConfig, SceneInteractionTarget, type SnapshotOptions, StudioConfig, TiltConfig, 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 };
+export { BackgroundImageFit, BackgroundMode, BasicGradientType, BlendMode, CAMERA_FITS, CameraFit, ColorStop, DEFAULT_LIGHT_POSITION, DISSOLVE_AXES, DissolveAxis, DissolveConfig, 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, PathPoint, SceneConfig, SceneInteractionBinding, SceneInteractionConfig, SceneInteractionTarget, type SnapshotOptions, StudioConfig, TiltConfig, 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, normalizeDissolve, normalizeParticles, normalizePath, 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, PARTICLE_SHAPES, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, normalizeBackground, normalizeParticles, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves } from "./config/model.js";
+import { CAMERA_FITS, DEFAULT_LIGHT_POSITION, DISSOLVE_AXES, 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, normalizeDissolve, normalizeParticles, normalizePath, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves } from "./config/model.js";
 import { createWaveImpl, noGpuBackend } from "./shell/createWave.js";
 import { WaveRenderer } from "./renderer/WaveRenderer.js";
 import { PRESETS } from "./presets.js";
@@ -19,6 +19,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, PARTICLE_SHAPES, PRESETS, WaveRenderer, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, createWave, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, mountWave, normalizeBackground, normalizeParticles, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves };
+export { CAMERA_FITS, DEFAULT_LIGHT_POSITION, DISSOLVE_AXES, 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, normalizeDissolve, normalizeParticles, normalizePath, normalizeSceneInteraction, normalizeWave, normalizeWaveInteraction, resizeWaves };
 
 //# sourceMappingURL=standalone.js.map

package/dist/studio/StudioWaveRenderer.d.ts

@@ -1,5 +1,7 @@
 import { WaveRenderer } from "../renderer/WaveRenderer.js";
 //#region src/studio/StudioWaveRenderer.d.ts
+/** What the 3D gizmo does to the selected wave. */
+type GizmoMode = "translate" | "rotate" | "scale";
 declare class StudioWaveRenderer extends WaveRenderer {
   /** Set while the panel drives the camera, so orbit's 'change' doesn't re-refresh the
    *  panel mid-drag (the panel already knows the new value). */
@@ -33,15 +35,39 @@ declare class StudioWaveRenderer extends WaveRenderer {
   /** Whether the main view orbit/zoom/pan is on (studio); off for the embed. */
   private mainOrbitOn;
   private lightHelpers;
-  /** Which 3D-editing gizmo is active: none, dragging lights, or dragging the wave/waves. */
+  /** Which 3D-editing gizmo is active: none, dragging lights, dragging the wave/waves, or dragging
+   *  one wave's PATH — the centreline it is swept along. */
   private editMode;
   private selectedLight;
   /** Wave/wave drag handles: index 0 = the whole-wave box (moves config.position); 1..N =
    *  per-wave spheres (move each layer's offset), shown only when there's >1 wave. */
   private waveHelpers;
   private selectedWave;
+  /** Path editing: one sphere per control point of `pathWave`'s centreline, plus the line through
+   *  them. The handles live in WORLD space (that is what the drag machinery and the gizmo speak);
+   *  the points they write are in the wave's local space, which is where a path is authored. */
+  private pathHelpers;
+  /** Each path dot's larger, invisible pick target (a child of the dot), so a point is comfortable
+   *  to land on without the dot itself growing into a boulder. */
+  private pathPicks;
+  /** The dots' current screen-constant scale, so a hover can grow one and put it back. */
+  private pathHandleScale;
+  private hoverPathPoint;
+  private pathLine?;
+  private pathWave;
+  private selectedPathPoint;
+  /** Invisible pick surface following the CURRENT path — the wave's own mesh cannot be used, because
+   *  its vertices are only deformed on the GPU, so a CPU raycast would hit the straight ribbon the
+   *  geometry was born as rather than the curve on screen. */
+  private pathProxy?;
+  /** An in-flight sculpt: where on the ribbon it started (0..1 along the length), the last drag
+   *  point, and how far along the ribbon the push reaches. */
+  private sculptState?;
   /** Gizmo operation: "translate" moves the handle, "rotate" spins the whole wave. */
   private gizmoMode;
+  /** Wave scale at the start of a scale drag, with the helper scale it started from, so the
+   *  drag applies as a RATIO — the helper is also resized every frame to stay screen-constant. */
+  private scaleDragStart?;
   /** Active free screen-plane drag of a handle (grab anywhere on the marker, camera locked). */
   private dragState?;
   private readonly dragPlane;
@@ -56,10 +82,25 @@ declare class StudioWaveRenderer extends WaveRenderer {
   /** Set by the panel: fired after orbit moves the camera so sliders can refresh. */
   onCameraChanged?: () => void;
   /** Set by the panel: fired after a wave/wave gizmo drag/selection so the position and
-   *  per-wave offset sliders can refresh. */
-  onWaveChanged?: () => void;
+   *  per-wave offset sliders can refresh. Carries the selected wave's index — the panel uses it to
+   *  reveal that wave's folder, the same way {@link onLightsChanged} drives the lights folder. */
+  onWaveChanged?: (selected: number) => void;
+  /** Fires when path editing starts (the wave's index) or ends (-1), so the app can put the gestures
+   *  on screen — none of them are discoverable from the canvas alone. */
+  onPathEditChanged?: (waveIndex: number) => void;
+  /** Set by the panel: fired when whole-wave transform editing starts/stops (-1 = off), so the
+   *  gestures can be shown and the panel's gizmo controls rebuilt. */
+  onWaveEditChanged?: (waveIndex: number) => void;
   /** True while any drag-in-3D gizmo owns the camera (light or wave). */
   private get editing();
+  /** Edit one wave's PATH: show a handle per control point, draggable like every other gizmo. The
+   *  wave takes a straight centreline first if it has none, so entering changes nothing on screen —
+   *  the ribbon only moves once a point does. Pass -1 to leave. */
+  setPathEditMode(waveIndex: number): Promise<void>;
+  /** Which wave's path is being edited, or -1. */
+  pathEditWave(): number;
+  /** Drop a wave's path — back to the straight centreline the geometry is born with. */
+  clearPath(waveIndex: number): void;
   isLightEditMode(): boolean;
   isWaveEditMode(): boolean;
   /** Toggle 3D light editing: show draggable light handles; off restores the prior view. */
@@ -74,10 +115,11 @@ declare class StudioWaveRenderer extends WaveRenderer {
    *  onPointerDown/Move pan the camera manually when a left-press misses every handle (so panning
    *  never fights the object drag). Right-drag still rotates the camera; scroll/middle zooms. */
   private setOrbitForEdit;
-  /** Switch the wave-edit gizmo between moving handles and rotating the whole wave. Rotate
-   *  targets the whole-wave box (config.rotation), so selecting it makes the intent obvious. */
-  setGizmoMode(mode: "translate" | "rotate"): void;
-  getGizmoMode(): "translate" | "rotate";
+  /** Switch the wave-edit gizmo between moving, rotating and resizing the whole wave. Rotate and
+   *  scale target the whole-wave box (config.rotation / config.scale), so selecting one makes the
+   *  intent obvious. */
+  setGizmoMode(mode: GizmoMode): void;
+  getGizmoMode(): GizmoMode;
   /** Snapshot the live camera so leaving edit mode returns exactly here (incl. ortho zoom). */
   private captureReturnCamera;
   /** Restore the snapshot from captureReturnCamera (falls back to the authored hero camera). */
@@ -163,6 +205,35 @@ declare class StudioWaveRenderer extends WaveRenderer {
   private writeCameraToConfig;
   /** Pointer position in normalized device coords (-1..1), from a canvas-relative event. */
   private pointerNdc;
+  /**
+   * Double-click is the whole entry point to path editing: hit a ribbon and you are dragging its
+   * centreline, with no mode to find first. Inside path mode it keeps editing the path — on a point
+   * it removes that point, on the ribbon it inserts one where you clicked — so adding and removing
+   * are the same gesture as entering, and neither needs a button.
+   */
+  private onDoubleClick;
+  /** Select a wave and show its transform gizmo — the first stop of a double-click, and what the
+   *  panel's "drag waves in 3D" toggle lands on. */
+  enterWaveEdit(waveIndex: number): Promise<void>;
+  /** Leave whichever edit level is active and tell the panel about both. */
+  leaveEditing(): Promise<void>;
+  /**
+   * Which wave a click meant. An exact hit on a wave's mesh wins, but that mesh is the UNDEFORMED
+   * ribbon — every twist, displacement, helix and path lives in the vertex shader — so on a deformed
+   * wave the exact test misses everything you can actually see. The fallback is the wave's bounding
+   * sphere, inflated the way the clip fit inflates it, which answers the only question entry really
+   * asks: which ribbon did they mean.
+   */
+  private pickWave;
+  /** Raycast one wave's ribbon. In path mode that means the proxy strip, which follows the curve
+   *  you can actually see; otherwise the wave's own (undeformed) mesh, which is enough to answer
+   *  "which ribbon did I double-click". */
+  private raycastWave;
+  /** Insert a control point where the ribbon was clicked, between the two points it falls between —
+   *  so a double-click on a straight stretch gives you something to bend, exactly there. */
+  private insertPathPointAt;
+  /** Shared tail of every structural path edit: rebake, re-handle, tell the app. */
+  private afterPathEdit;
   private onPointerDown;
   private onPointerMove;
   private onPointerUp;
@@ -170,6 +241,42 @@ declare class StudioWaveRenderer extends WaveRenderer {
   private selectWaveHandle;
   /** Gizmo drag → route to the active mode's writer. */
   private onGizmoMoved;
+  /** Path handle drag → write the point back in the wave's LOCAL space. The handles are dragged in
+   *  world space (that is what the gizmo and the screen-plane drag speak), so each one is pushed
+   *  back through the wave's own matrix — which is what keeps a path authored against the ribbon
+   *  rather than against the scene, so moving or rotating the wave carries its path along. */
+  private onPathGizmoMoved;
+  /**
+   * Start pushing the ribbon around from wherever it was grabbed.
+   *
+   * The path is DENSIFIED first: a three-point path can only be bent as a whole, and a push that
+   * moves the entire ribbon is not sculpting. Resampling to evenly spaced points along the current
+   * curve keeps the shape identical (the curve is unchanged) while giving the falloff something local
+   * to act on — the difference between dragging a wire and pressing a thumb into clay.
+   */
+  private beginSculpt;
+  /** Resample the path to `count` evenly spaced points along the curve it already describes — same
+   *  shape, more to grab. Width and twist ride along so a sculpted throat survives densifying. */
+  private densifyPath;
+  /** Move the path under an in-flight sculpt: every point near the grabbed spot follows the cursor,
+   *  falling off smoothly with distance ALONG the ribbon. */
+  private sculptTo;
+  /** True when the path's ends coincide — the same test the sampler uses to decide it is a ring. */
+  /** Select a path point (attach the gizmo to its handle and highlight it). */
+  /** Which path point the ray is over, through the enlarged pick targets — or -1. The raycaster
+   *  must already be aimed. */
+  private pickPathHandle;
+  /** The cursor for the pointer's current spot in path mode: what a click here would do. The
+   *  raycaster must already be aimed. */
+  private pathCursorAt;
+  private selectPathHandle;
+  /** Reconcile the path handles + the line through them with the wave's points. */
+  private syncPathHelpers;
+  /** Rebuild the pick surface: a strip two vertices wide per frame, carrying uv.y = position along
+   *  the ribbon — which is what a sculpt drag needs to know to push the right part of the path. It
+   *  belongs to no scene (nothing should draw it); raycasting only needs its world matrix. */
+  private syncPathProxy;
+  private clearPathHelpers;
   /** Light gizmo drag → write the moved handle back into the config + uniforms. */
   private onLightGizmoMoved;
   /** Wave gizmo drag → the whole-wave box writes config.position (and the wave handles
@@ -205,5 +312,5 @@ declare class StudioWaveRenderer extends WaveRenderer {
   dispose(): void;
 }
 //#endregion
-export { StudioWaveRenderer };
+export { GizmoMode, StudioWaveRenderer };
 //# sourceMappingURL=StudioWaveRenderer.d.ts.map