@wave3d/core 0.1.0 → 0.2.1

package/README.md

@@ -1,10 +1,12 @@
 # @wave3d/core
 
-Framework-agnostic **3D gradient-wave** renderer + config model — the engine behind [Wave Studio](https://github.com/Amir-Abushanab/wave3d).
+The framework-agnostic renderer and config model behind [Wave Studio](https://wave-studio.pages.dev): glossy, twisting 3D gradient waves driven by one JSON config.
 
-A glossy, twisting _wave of light_: a strip swept along a curve, with a gradient running along its length and a satin sheen. Everything is driven by a single JSON-serializable `WaveConfig`, so the renderer and every export read from one source of truth.
+A wave is a strip swept along a curve, with a gradient running down its length and a satin sheen. The renderer and every export read from the same `WaveConfig`, so what you design is exactly what ships.
 
-## Install
+> 💡 Fastest way in: design a wave in **[Wave Studio](https://wave-studio.pages.dev)**, hit **⟨⟩ Export code**, and copy the snippet. This package is what that snippet imports.
+
+## 📦 Install
 
 ```sh
 pnpm add @wave3d/core three   # three is a peer dependency
@@ -12,9 +14,9 @@ pnpm add @wave3d/core three   # three is a peer dependency
 
 `three` is a peer dependency (`>=0.180 <1`); add `@types/three` for TypeScript.
 
-## Drop-in wave (poster-first, self-optimizing)
+## Drop-in wave
 
-The `.` entry is a lightweight shell: it shows a poster immediately, then lazily upgrades to the live WebGL wave only when the browser can run it (falling back to the poster on no-WebGL, Save-Data, reduced-motion, or context loss). `three.js` is code-split out of the initial load.
+The default entry is poster-first: it shows a poster immediately, then upgrades to live WebGL only when the browser can run it. It falls back to the poster on no-WebGL, Save-Data, reduced motion, or a lost context, and `three.js` is code-split out of the initial load.
 
 ```ts
 import { createWave } from "@wave3d/core";
@@ -22,38 +24,48 @@ import { createWave } from "@wave3d/core";
 const handle = createWave(document.getElementById("wave"), config, {
   poster: "/wave.png",
 });
-// handle.set(nextConfig) · handle.pause() · handle.play() · handle.destroy()
+// handle.set(nextConfig) · handle.pause() · handle.play() · handle.snapshot() · handle.destroy()
 ```
 
-## Single `<script>` from a CDN (three bundled)
+Capture the live frame as an image you can host and reuse as the poster for reduced-motion, no-WebGL, and Save-Data visitors:
+
+```ts
+const blob = await handle.snapshot(); // resolves null until running. options: { type?, quality?, transparent? }
+```
+
+## Single `<script>` from a CDN
+
+`three` is bundled into the standalone build, so this needs nothing else:
 
 ```html
 <script type="module">
   import { mountWave } from "https://esm.sh/@wave3d/core/standalone";
   mountWave(document.getElementById("wave"), {
-    /* config */
+    /* your exported config */
   });
 </script>
 ```
 
 ## Entry points
 
-| Import                    | What                                                         |
-| ------------------------- | ------------------------------------------------------------ |
-| `@wave3d/core`            | poster-first shell (`createWave`/`mountWave`) + config model |
-| `@wave3d/core/renderer`   | the raw `WaveRenderer` + `WaveGeometry` (static three)       |
-| `@wave3d/core/presets`    | the built-in `PRESETS`                                       |
-| `@wave3d/core/studio`     | `StudioWaveRenderer` + randomizers                           |
-| `@wave3d/core/standalone` | single-file build with three bundled (the CDN entry)         |
+| Import                    | What                                                           |
+| ------------------------- | -------------------------------------------------------------- |
+| `@wave3d/core`            | poster-first shell (`createWave` / `mountWave`) + config model |
+| `@wave3d/core/renderer`   | the raw `WaveRenderer` and `WaveGeometry` (static three)       |
+| `@wave3d/core/presets`    | the built-in `PRESETS`                                         |
+| `@wave3d/core/studio`     | `StudioWaveRenderer` + randomizers                             |
+| `@wave3d/core/standalone` | single-file build with three bundled (the CDN entry)           |
 
 ## Framework wrappers
 
-- **React** — [`@wave3d/react`](https://www.npmjs.com/package/@wave3d/react): the `<Wave3D>` component.
-- **Vue / Svelte / plain HTML** — [`@wave3d/element`](https://www.npmjs.com/package/@wave3d/element): the `<wave-3d>` custom element.
+Prefer a component? Reach for the wrapper for your framework:
+
+- **React** → [`@wave3d/react`](https://www.npmjs.com/package/@wave3d/react): the `<Wave3D>` component.
+- **Vue, Svelte, or plain HTML** → [`@wave3d/element`](https://www.npmjs.com/package/@wave3d/element): the `<wave-3d>` custom element.
 
 ## Credits
 
-Created by [Amir Abushanab](https://github.com/Amir-Abushanab).
+Built by [Amir Abushanab](https://github.com/Amir-Abushanab).
 
 ## License
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 import { BackgroundImageFit, BackgroundMode, BasicGradientType, BlendMode, ColorStop, DEFAULT_LIGHT_POSITION, GradientType, LightConfig, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, MeshGradientPoint, NoiseBand, PaletteSource, SceneConfig, StudioConfig, Vec2, Vec3, WaveConfig, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, normalizeBackground, normalizeWave, resizeWaves } from "./config/model.js";
 import { WaveRenderer, WaveRendererOptions } from "./renderer/WaveRenderer.js";
-import { FallbackReason, WaveHandle, WaveOptions, WaveState, createWave, mountWave } from "./shell/createWave.js";
-export { BackgroundImageFit, BackgroundMode, BasicGradientType, BlendMode, ColorStop, DEFAULT_LIGHT_POSITION, type FallbackReason, GradientType, LightConfig, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, MeshGradientPoint, NoiseBand, PaletteSource, SceneConfig, StudioConfig, Vec2, Vec3, WaveConfig, type WaveHandle, type WaveOptions, type WaveRenderer, type WaveRendererOptions, type WaveState, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, createWave, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, mountWave, normalizeBackground, normalizeWave, resizeWaves };
+import { FallbackReason, SnapshotOptions, WaveHandle, WaveOptions, WaveState, createWave, mountWave } from "./shell/createWave.js";
+export { BackgroundImageFit, BackgroundMode, BasicGradientType, BlendMode, ColorStop, DEFAULT_LIGHT_POSITION, type FallbackReason, GradientType, LightConfig, MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS, MAX_WAVES, MeshGradientPoint, NoiseBand, PaletteSource, SceneConfig, type SnapshotOptions, StudioConfig, Vec2, Vec3, WaveConfig, type WaveHandle, type WaveOptions, type WaveRenderer, type WaveRendererOptions, type WaveState, createDefaultConfig, createDefaultMeshPoints, createLight, createNoiseBand, createWave, ensureCamera, ensureSceneDefaults, ensureStudioConfig, makeStops, makeWave, makeWaveSpread, mountWave, normalizeBackground, normalizeWave, resizeWaves };

package/dist/renderer/WaveRenderer.d.ts

@@ -91,7 +91,7 @@ declare class WaveRenderer {
   private readonly clipSphere;
   private readonly clipTmpA;
   private readonly clipTmpB;
-  private readonly clock;
+  private readonly timer;
   private time;
   private rafId;
   protected running: boolean;
@@ -174,7 +174,7 @@ declare class WaveRenderer {
   private onVisibilityChange;
   private updateRunning;
   private loop;
-  /** Advance the per-frame clock uniforms (geometry itself is static). Time model:
+  /** Advance the per-frame time 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. */
@@ -220,7 +220,7 @@ declare class WaveRenderer {
    *  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>;
+  captureImage(mime: string, transparent?: boolean, quality?: number, time?: number): Promise<Blob>;
   captureStream(fps?: number): MediaStream;
   get canvas(): HTMLCanvasElement;
   getConfig(): StudioConfig;

package/dist/renderer/WaveRenderer.js

@@ -169,7 +169,7 @@ var WaveRenderer = class {
 	clipSphere = new THREE.Sphere();
 	clipTmpA = new THREE.Vector3();
 	clipTmpB = new THREE.Vector3();
-	clock = new THREE.Clock();
+	timer = new THREE.Timer();
 	time = 0;
 	rafId = 0;
 	running = false;
@@ -925,8 +925,7 @@ var WaveRenderer = class {
 		const shouldAnimate = this.started && this.visible && this.pageVisible && !this.config.paused && !this.reducedMotion;
 		if (shouldAnimate && !this.running) {
 			this.running = true;
-			this.clock.start();
-			this.clock.getDelta();
+			this.timer.update();
 			this.rafId = requestAnimationFrame(this.loop);
 		} else if (!shouldAnimate && this.running) {
 			this.running = false;
@@ -940,12 +939,13 @@ var WaveRenderer = class {
 	}
 	loop = () => {
 		if (!this.running) return;
-		this.time += this.clock.getDelta();
+		this.timer.update();
+		this.time += this.timer.getDelta();
 		if (this.introTimeRamp < 1) this.introTimeRamp = Math.min(1, this.introTimeRamp + .016);
 		this.renderOnce();
 		this.rafId = requestAnimationFrame(this.loop);
 	};
-	/** Advance the per-frame clock uniforms (geometry itself is static). Time model:
+	/** Advance the per-frame time uniforms (geometry itself is static). Time model:
 	*  time = elapsed·introTimeRamp + timeOffset — the ramp eases the animation in on load. */
 	updateTime() {
 		const ramp = this.config.introRamp === false || this.skipIntroRamp ? 1 : this.introTimeRamp;
@@ -1051,12 +1051,19 @@ var WaveRenderer = class {
 	*  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. */
-	async captureImage(mime, transparent = true, quality) {
-		const prev = this.config.transparentBackground;
-		if (transparent !== prev) {
+	async captureImage(mime, transparent = true, quality, time) {
+		const prevBg = this.config.transparentBackground;
+		if (transparent !== prevBg) {
 			this.config.transparentBackground = transparent;
 			this.applyBackground();
 		}
+		const fixTime = time !== void 0;
+		const prevTime = this.time;
+		const prevRamp = this.introTimeRamp;
+		if (fixTime) {
+			this.time = time;
+			this.introTimeRamp = 1;
+		}
 		let blob = null;
 		try {
 			this.capturing = true;
@@ -1064,10 +1071,14 @@ var WaveRenderer = class {
 			blob = await new Promise((resolve) => this.canvas.toBlob(resolve, mime, quality));
 		} finally {
 			this.capturing = false;
-			if (transparent !== prev) {
-				this.config.transparentBackground = prev;
+			if (transparent !== prevBg) {
+				this.config.transparentBackground = prevBg;
 				this.applyBackground();
 			}
+			if (fixTime) {
+				this.time = prevTime;
+				this.introTimeRamp = prevRamp;
+			}
 			this.renderOnce();
 		}
 		if (!blob || blob.type !== mime) throw new Error(`Failed to capture ${mime}`);