@wave3d/core 0.1.0

package/dist/renderer/WaveGeometry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaveGeometry.js","names":[],"sources":["../../src/renderer/WaveGeometry.ts"],"sourcesContent":["import * as THREE from \"three\";\n\n/** Native plane size for folded() — keep this exact (400) so the vertex\n *  shader's displace/twist frequencies (calibrated to this scale) stay faithful. */\nconst NATIVE = 400;\nconst FOLD_X = 16; // |x| < 16 is the semicircular hinge; outside it the two flat arms\nconst SHIFT = NATIVE / 4; // recentre the folded cross-section along x\n\nconst X_AXIS = new THREE.Vector3(1, 0, 0);\nconst Y_AXIS = new THREE.Vector3(0, 1, 0);\n\n/**\n * Base wave geometry — `folded()`: a flat PlaneGeometry folded into a hairpin\n * (sideways-U) cross-section, then stood up so the fold runs along the wave's length.\n *\n *   - Each vertex gets a half-thickness `r` (per-vertex math below): tight along the\n *     width centreline, flaring toward the long edges.\n *   - The strip |x| < FOLD_X becomes a semicircular hinge; the plane's two halves bend\n *     around it into parallel arms offset to +r and -r.\n *   - Two −90° rotations (about X then Y) orient the U upright and down its length.\n *\n * folded() leaves the U open along one side and hollow at both ends, so at oblique\n * camera angles you could see straight through it. We weld the open side and cap both\n * ends with extra triangles so the mesh is a watertight solid — welding/capping adds\n * faces only, no vertex positions move.\n *\n * All further deformation (displacement, twist, transform) happens in the vertex shader\n * on top of this base. UVs: u along the fold/length, v across the width.\n */\nexport class WaveGeometry {\n  readonly geometry: THREE.BufferGeometry;\n  private segments = -1;\n\n  constructor(segments: number) {\n    this.geometry = new THREE.BufferGeometry();\n    this.resize(segments);\n  }\n\n  resize(segments: number): void {\n    if (segments === this.segments) return;\n    this.segments = segments;\n\n    // subX along the fold, subY across the width (twice as dense).\n    const subX = THREE.MathUtils.clamp(Math.round(segments), 48, 200);\n    const subY = subX * 2;\n\n    const plane = new THREE.PlaneGeometry(NATIVE, NATIVE, subX, subY);\n    const pos = plane.attributes.position as THREE.BufferAttribute;\n    const uv = plane.attributes.uv as THREE.BufferAttribute;\n    const v = new THREE.Vector3();\n\n    for (let i = 0; i < pos.count; i++) {\n      v.fromBufferAttribute(pos, i);\n      const uy = uv.getY(i);\n      // r: cross-section half-thickness — tight (2) along the width centreline, flaring (4)\n      // toward the long edges. The pow() term is a sharp parabolic bump peaking at uv.y = 0.5.\n      const r = 4 - 2 * Math.pow(4 * uy * (1 - uy), 9.5);\n\n      if (v.x < -FOLD_X) {\n        v.z += r; // long arm, at +r\n      } else if (v.x < FOLD_X) {\n        // semicircular hinge: z sweeps +r → -r, x collapses to the bend\n        v.z = Math.cos(THREE.MathUtils.mapLinear(v.x, -FOLD_X, FOLD_X, 0, Math.PI)) * r;\n        v.x =\n          Math.cos(THREE.MathUtils.mapLinear(v.x, -FOLD_X, FOLD_X, -Math.PI / 2, Math.PI / 2)) * r -\n          FOLD_X;\n      } else {\n        v.z -= r; // folded-over arm, mirrored back at -r\n        v.x = -v.x;\n      }\n\n      v.x += SHIFT;\n      v.applyAxisAngle(X_AXIS, -Math.PI / 2);\n      v.applyAxisAngle(Y_AXIS, -Math.PI / 2);\n      pos.setXYZ(i, v.x, v.y, v.z);\n    }\n    pos.needsUpdate = true;\n\n    // Seal the hairpin's OPEN side. folded() leaves the two arm tips unconnected — the\n    // plane's u=0 and u=subX edges, which fold to adjacent tips at +r and -r — so at oblique\n    // camera angles you can see through the U to the background. Weld those two edges with a\n    // strip of triangles, closing the tube. No vertex positions move; this only adds faces\n    // over the previously-open seam.\n    const cols = subX + 1;\n    const srcIdx = plane.getIndex();\n    const merged = srcIdx ? Array.from(srcIdx.array as ArrayLike<number>) : [];\n    // (a) Weld the U's side opening: the u=0 and u=subX edges fold to adjacent tips at ±r.\n    for (let iy = 0; iy < subY; iy++) {\n      const a = iy * cols; // (row iy, col 0)  — arm-A tip\n      const b = (iy + 1) * cols; // (row iy+1, col 0)\n      const c = a + subX; // (row iy, col subX) — arm-B tip\n      const d = b + subX; // (row iy+1, col subX)\n      merged.push(a, c, b, b, c, d);\n    }\n    // (b) Cap the two length-ends (v=0 and v=subX rows): the folded sheet is a hollow channel\n    // open at both ends, so an edge-on camera sees straight through it. Fan-triangulate each\n    // end's U cross-section (apex = the col-0 tip) to close it — making the wave a closed solid.\n    for (const row of [0, subY]) {\n      const apex = row * cols;\n      for (let ix = 1; ix < subX; ix++) merged.push(apex, row * cols + ix, row * cols + ix + 1);\n    }\n    plane.setIndex(merged);\n\n    plane.computeVertexNormals();\n\n    // Move the baked attributes onto our reusable geometry, then drop the temp.\n    this.geometry.setIndex(plane.getIndex());\n    this.geometry.setAttribute(\"position\", plane.getAttribute(\"position\"));\n    this.geometry.setAttribute(\"uv\", plane.getAttribute(\"uv\"));\n    this.geometry.setAttribute(\"normal\", plane.getAttribute(\"normal\"));\n    this.geometry.computeBoundingSphere();\n    plane.dispose();\n  }\n\n  dispose(): void {\n    this.geometry.dispose();\n  }\n}\n"],"mappings":";;;;AAIA,MAAM,SAAS;AACf,MAAM,SAAS;AACf,MAAM,QAAQ,SAAS;AAEvB,MAAM,SAAS,IAAI,MAAM,QAAQ,GAAG,GAAG,CAAC;AACxC,MAAM,SAAS,IAAI,MAAM,QAAQ,GAAG,GAAG,CAAC;;;;;;;;;;;;;;;;;;;AAoBxC,IAAa,eAAb,MAA0B;CACxB;CACA,WAAmB;CAEnB,YAAY,UAAkB;EAC5B,KAAK,WAAW,IAAI,MAAM,eAAe;EACzC,KAAK,OAAO,QAAQ;CACtB;CAEA,OAAO,UAAwB;EAC7B,IAAI,aAAa,KAAK,UAAU;EAChC,KAAK,WAAW;EAGhB,MAAM,OAAO,MAAM,UAAU,MAAM,KAAK,MAAM,QAAQ,GAAG,IAAI,GAAG;EAChE,MAAM,OAAO,OAAO;EAEpB,MAAM,QAAQ,IAAI,MAAM,cAAc,QAAQ,QAAQ,MAAM,IAAI;EAChE,MAAM,MAAM,MAAM,WAAW;EAC7B,MAAM,KAAK,MAAM,WAAW;EAC5B,MAAM,IAAI,IAAI,MAAM,QAAQ;EAE5B,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,OAAO,KAAK;GAClC,EAAE,oBAAoB,KAAK,CAAC;GAC5B,MAAM,KAAK,GAAG,KAAK,CAAC;GAGpB,MAAM,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,GAAG;GAEjD,IAAI,EAAE,IAAI,KACR,EAAE,KAAK;QACF,IAAI,EAAE,IAAI,QAAQ;IAEvB,EAAE,IAAI,KAAK,IAAI,MAAM,UAAU,UAAU,EAAE,GAAG,KAAS,QAAQ,GAAG,KAAK,EAAE,CAAC,IAAI;IAC9E,EAAE,IACA,KAAK,IAAI,MAAM,UAAU,UAAU,EAAE,GAAG,KAAS,QAAQ,CAAC,KAAK,KAAK,GAAG,KAAK,KAAK,CAAC,CAAC,IAAI,IACvF;GACJ,OAAO;IACL,EAAE,KAAK;IACP,EAAE,IAAI,CAAC,EAAE;GACX;GAEA,EAAE,KAAK;GACP,EAAE,eAAe,QAAQ,CAAC,KAAK,KAAK,CAAC;GACrC,EAAE,eAAe,QAAQ,CAAC,KAAK,KAAK,CAAC;GACrC,IAAI,OAAO,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;EAC7B;EACA,IAAI,cAAc;EAOlB,MAAM,OAAO,OAAO;EACpB,MAAM,SAAS,MAAM,SAAS;EAC9B,MAAM,SAAS,SAAS,MAAM,KAAK,OAAO,KAA0B,IAAI,CAAC;EAEzE,KAAK,IAAI,KAAK,GAAG,KAAK,MAAM,MAAM;GAChC,MAAM,IAAI,KAAK;GACf,MAAM,KAAK,KAAK,KAAK;GACrB,MAAM,IAAI,IAAI;GACd,MAAM,IAAI,IAAI;GACd,OAAO,KAAK,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;EAC9B;EAIA,KAAK,MAAM,OAAO,CAAC,GAAG,IAAI,GAAG;GAC3B,MAAM,OAAO,MAAM;GACnB,KAAK,IAAI,KAAK,GAAG,KAAK,MAAM,MAAM,OAAO,KAAK,MAAM,MAAM,OAAO,IAAI,MAAM,OAAO,KAAK,CAAC;EAC1F;EACA,MAAM,SAAS,MAAM;EAErB,MAAM,qBAAqB;EAG3B,KAAK,SAAS,SAAS,MAAM,SAAS,CAAC;EACvC,KAAK,SAAS,aAAa,YAAY,MAAM,aAAa,UAAU,CAAC;EACrE,KAAK,SAAS,aAAa,MAAM,MAAM,aAAa,IAAI,CAAC;EACzD,KAAK,SAAS,aAAa,UAAU,MAAM,aAAa,QAAQ,CAAC;EACjE,KAAK,SAAS,sBAAsB;EACpC,MAAM,QAAQ;CAChB;CAEA,UAAgB;EACd,KAAK,SAAS,QAAQ;CACxB;AACF"}

package/dist/renderer/WaveRenderer.d.ts

@@ -0,0 +1,232 @@
+import { StudioConfig, WaveConfig } from "../config/model.js";
+import { WaveGeometry } from "./WaveGeometry.js";
+import * as THREE from "three";
+
+//#region src/renderer/WaveRenderer.d.ts
+/** Reference frame (world units) the orthographic camera fills at cameraZoom 1. The wave is
+ *  framed by COVERING this FRAME_W × FRAME_H rectangle (centred on cameraTarget) into the canvas
+ *  — scaled to fill both dimensions, cropping the aspect overflow — so a given cameraZoom /
+ *  cameraTarget frames the wave the SAME at any canvas size or aspect (only the cropped margin
+ *  differs). FRAME_H = FRAME_W / (16/9) makes the reference a 16:9 rectangle; for canvases wider
+ *  than that the width binds, narrower ones zoom in to fill instead of
+ *  showing empty bands. This is what makes a saved preset reproduce on anyone's screen. */
+declare const FRAME_W = 1333;
+declare const FRAME_H = 750;
+interface WaveRendererOptions {
+  /** Honor prefers-reduced-motion by freezing animation. Default true. */
+  respectReducedMotion?: boolean;
+  /**
+   * Skip the intro time-ramp (the ~1s ease-in of animation on load), rendering at full speed
+   * immediately. The studio passes `import.meta.env.DEV` here so a fresh renderer on every HMR
+   * hot-swap doesn't replay the ease-in (which reads as a "speed up" when you tab back). Default
+   * false — production embeds keep the ease-in. Ignored while paused (a paused frame is always the
+   * full frame). Default false.
+   */
+  skipIntroRamp?: boolean;
+}
+/**
+ * Per-wave 2D palette texture (+ optional looping video). One instance per wave, so each
+ * wave carries its own palette. Guarded by a signature so it only rebuilds when that wave's
+ * palette actually changes (not every refresh).
+ */
+declare class WavePalette {
+  private readonly makeVideo;
+  private readonly onVideoReady;
+  texture?: THREE.Texture;
+  private sig;
+  private video?;
+  private videoUrl;
+  private failedUrl;
+  constructor(makeVideo: (url: string) => HTMLVideoElement, onVideoReady: () => void);
+  /** Rebuild this wave's palette texture from its config (video / custom image / stops /
+   *  built-in map / hero LUT) and point the wave's palette uniforms at it. */
+  apply(cfg: WaveConfig, uniforms: Record<string, THREE.IUniform>): void;
+  /** Play/pause this wave's palette video with the render loop. */
+  syncPlayback(cfg: WaveConfig, running: boolean): void;
+  private ensureVideo;
+  private clearVideo;
+  dispose(): void;
+}
+type Wave = {
+  mesh: THREE.Mesh;
+  material: THREE.ShaderMaterial;
+  geometry: WaveGeometry; /** This wave's own 2D palette texture + optional video. */
+  palette: WavePalette;
+};
+/** Convert an sRGB hex string to a linear-space RGB vector (three's ColorManagement does the
+ *  sRGB→linear conversion on parse). Exported for the studio subclass's live light-uniform push. */
+declare function hexToLinearVec3(hex: string, target: THREE.Vector3): THREE.Vector3;
+/**
+ * Renders a gradient "wave of light" from a {@link StudioConfig}. Framework-agnostic:
+ * it needs only a DOM container and a config. The studio mutates the config in
+ * place and calls `refresh()` / `rebuild()`.
+ */
+declare class WaveRenderer {
+  readonly renderer: THREE.WebGLRenderer;
+  protected readonly scene: THREE.Scene<THREE.Object3DEventMap>;
+  protected readonly camera: THREE.OrthographicCamera;
+  protected readonly group: THREE.Group<THREE.Object3DEventMap>;
+  private readonly composer;
+  private readonly postPass;
+  /** Optional bloom pass — created lazily when bloomStrength first goes >0, removed at 0. */
+  private bloomPass?;
+  protected readonly container: HTMLElement;
+  private readonly respectReducedMotion;
+  private readonly skipIntroRamp;
+  protected config: StudioConfig;
+  protected waves: Wave[];
+  private backgroundTexture?;
+  private backgroundSig;
+  private backgroundImage?;
+  private backgroundImageUrl;
+  private failedBackgroundImageUrl;
+  private backgroundVideo?;
+  private backgroundVideoUrl;
+  private failedBackgroundVideoUrl;
+  private backgroundVideoCanvas?;
+  /** Authored default camera pose, for "Reset camera". */
+  protected readonly homeCamPos: THREE.Vector3;
+  protected readonly homeCamTarget: THREE.Vector3;
+  private readonly clipBox;
+  private readonly clipSphere;
+  private readonly clipTmpA;
+  private readonly clipTmpB;
+  private readonly clock;
+  private time;
+  private rafId;
+  protected running: boolean;
+  private started;
+  private visible;
+  private pageVisible;
+  private reducedMotion;
+  /** Intro ramp: eases animation time 0→1 over ~1s on load (when config.introRamp). */
+  private introTimeRamp;
+  private readonly resizeObserver;
+  private readonly intersectionObserver;
+  private readonly motionQuery;
+  protected capturing: boolean;
+  /** Fixed backing-buffer dimensions used by the studio's visible export frame. Embeds leave
+   *  this unset and continue to resize responsively with their container and device DPR. */
+  private outputSize?;
+  constructor(container: HTMLElement, config: StudioConfig, options?: WaveRendererOptions);
+  private get segments();
+  private makeUniforms;
+  /** Vertex-shader #defines for a wave: TWIST_MOTION (per-wave animated twist wobble) and
+   *  LOOP_MOTION (scene-level seamless loop). Both select #ifdef-gated code paths; an empty
+   *  object compiles the default (linear-time) program. */
+  private waveDefines;
+  private addWave;
+  /**
+   * Apply config.blendMode to a material. "squared" (the default) is the hero blend:
+   * CustomBlending with AddEquation, src = SrcColorFactor, dst = ZeroFactor, so the
+   * framebuffer result is fragColor² — the squaring deepens the colours into the vivid
+   * hero look (without it the wave reads pastel). "additive"/"normal"/"multiply" are
+   * authoring overrides. Multiply uses Three's premultiplied-alpha path; the custom
+   * fragment shaders premultiply their output when Three injects PREMULTIPLIED_ALPHA.
+   * Returns true if material state changed (caller flags needsUpdate).
+   */
+  private applyBlendMode;
+  private disposeWaves;
+  /**
+   * Reconcile the wave pool to `waveCount` WITHOUT tearing everything down:
+   * keep existing waves (so the compiled shader program is never deleted and
+   * re-compiled — that churn can crash some GPU drivers), add/remove only the
+   * delta, and resize each geometry to the current quality.
+   */
+  private buildWaves;
+  /** Re-read per-frame-independent values from the (mutated) config. */
+  refresh(): void;
+  /** Point every wave's palette sampler at its own WavePalette texture (each rebuilt only
+   *  when that wave's palette actually changes — see WavePalette.apply). */
+  private updatePaletteTextures;
+  /** Dev: 0 = normal, 1 = visualise the crease value, 2 = visualise derivative normal. */
+  setDebug(v: number): void;
+  /** Rebuild geometry + waves (call when waveCount or quality changes). */
+  rebuild(): void;
+  private applyBackground;
+  private applyColorBackground;
+  private applyGradientBackground;
+  /** Image mode: a live video, a user-loaded image, or a built-in map. `matte` shows while an
+   *  async source is still loading. */
+  private applyImageBackground;
+  private backgroundCanvasSize;
+  private loadBackgroundImage;
+  private ensureBackgroundVideo;
+  private clearBackgroundVideo;
+  private createLoopingVideo;
+  private syncVideoPlayback;
+  private updateBackgroundVideoFrame;
+  private applyPost;
+  /** Insert / tune / remove the bloom pass. strength 0 removes it from the composer entirely, so
+   *  cost and pixels are identical to bloom-off; the pass (and its mip-chain render targets) is
+   *  created lazily the first time bloom is enabled and disposed when turned back off. It sits
+   *  right after the scene RenderPass so it blooms the wave before the grain/blur pass. */
+  private applyBloom;
+  private onResize;
+  private onContextLost;
+  private onContextRestored;
+  resize(): void;
+  /** Set an exact output buffer while CSS scales the canvas into the on-screen export frame. */
+  setOutputSize(width: number, height: number): void;
+  start(): void;
+  stop(): void;
+  private onMotionChange;
+  private onVisibilityChange;
+  private updateRunning;
+  private loop;
+  /** Advance the per-frame clock uniforms (geometry itself is static). Time model:
+   *  time = elapsed·introTimeRamp + timeOffset — the ramp eases the animation in on load. */
+  private updateTime;
+  /** Render exactly one frame at the current time. */
+  renderOnce(): void;
+  /** Re-evaluate play/pause after `config.paused` changes. */
+  refreshPlayback(): void;
+  /** Jump the camera to the config's authored framing (cameraPosition / cameraTarget /
+   *  cameraZoom). Called on whole-config swaps (preset / reset / randomize / import). The base
+   *  applies the pose directly; the studio subclass overrides it to also drive the orbit target
+   *  and sync the panel. Hook ⑤. */
+  protected applyCameraFromConfig(): void;
+  /** Hook ①: true while orbit or an edit gizmo owns the camera, so refresh() won't reset it. */
+  protected isCameraExternallyDriven(): boolean;
+  /** Hook ②: called at the end of refresh(), before the trailing renderOnce(). */
+  protected onAfterRefresh(): void;
+  /** Hook ③: called at the end of renderOnce(), after the composed frame is drawn. */
+  protected onAfterRenderFrame(): void;
+  /** Hook ④: called at the end of resize(), before the trailing renderOnce(). */
+  protected onAfterResize(): void;
+  /** Responsive ortho zoom: COVER the FRAME_W × FRAME_H reference frame onto the canvas so the
+   *  wave frames the same at any size/aspect/dpr (only the cropped margin differs), times the
+   *  user's cameraZoom. `max(...)` = cover (fill both axes, crop overflow); `min(...)` would be
+   *  contain (fit with letterbox bands). Cover keeps the wave filling the frame on every screen. */
+  protected applyZoom(): void;
+  /** Fit the orthographic near/far planes to the scene before every render, so no part of a wave
+   *  is ever clipped as the camera orbits / dollies / pans (or when waves are added or scaled).
+   *
+   *  The camera is *constructed* with fixed 1..10000 planes that only suit the authored hero
+   *  framing; once the view moves, the wave's depth extent along the view axis easily crosses
+   *  them and the GPU hard-slices the geometry along a flat plane — chunks of the wave vanish.
+   *
+   *  The in-shader twist rotates each vertex about its LOCAL origin, so it can never move a vertex
+   *  further from that origin than the base geometry already sits. A sphere at each mesh's origin
+   *  (radius = base extent × the mesh's largest world scale, plus the Y displacement, ×1.2 slack)
+   *  therefore safely contains the fully-deformed wave. We union those, then bracket the union
+   *  along the view axis with a margin. Bracketing to the scene (rather than a fixed huge slab)
+   *  keeps clip-space depth scene-normalised — so the wireframe theme's depth fade, which reads
+   *  gl_Position.z, looks the same at any camera distance instead of washing out. Runs each frame;
+   *  it's a handful of vector ops over 1–8 meshes with no allocation. */
+  private updateClipPlanes;
+  /** A world-space position delta that drops a duplicated wave into open frame space beside the
+   *  one it was copied from — screen-left and a touch down, sized to the visible frame — instead
+   *  of hidden exactly on top of it or (for the hero, which fills the right of the frame) pushed
+   *  off-frame. Camera-relative: it's "left on screen" no matter how the view is rotated/zoomed,
+   *  because it's built from the camera's right/up axes and the frame's visible world size. */
+  captureImage(mime: string, transparent?: boolean, quality?: number): Promise<Blob>;
+  captureStream(fps?: number): MediaStream;
+  get canvas(): HTMLCanvasElement;
+  getConfig(): StudioConfig;
+  setConfig(config: StudioConfig): void;
+  dispose(): void;
+}
+//#endregion
+export { FRAME_H, FRAME_W, WaveRenderer, WaveRendererOptions, hexToLinearVec3 };
+//# sourceMappingURL=WaveRenderer.d.ts.map