@wave3d/core 0.2.0 → 0.2.2

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";
@@ -25,41 +27,45 @@ const handle = createWave(document.getElementById("wave"), config, {
 // handle.set(nextConfig) · handle.pause() · handle.play() · handle.snapshot() · handle.destroy()
 ```
 
-Capture the live frame as an image — a poster you can host and reuse for reduced-motion / no-WebGL / Save-Data visitors — with `handle.snapshot()` (resolves `null` until running):
+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(); // options: { type?, quality?, transparent? } — WebP, transparent
+const blob = await handle.snapshot(); // resolves null until running. options: { type?, quality?, transparent? }
 ```
 
-## Single `<script>` from a CDN (three bundled)
+## 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/studio/index.d.ts

@@ -1,3 +1,4 @@
 import { randomizeBackground, randomizeColor, randomizeConfig, randomizeFinish, randomizeGlobal, randomizeGradient, randomizeLights, randomizeSpine, randomizeTransform, randomizeTwist, randomizeWave } from "./randomize.js";
 import { StudioWaveRenderer } from "./StudioWaveRenderer.js";
-export { StudioWaveRenderer, randomizeBackground, randomizeColor, randomizeConfig, randomizeFinish, randomizeGlobal, randomizeGradient, randomizeLights, randomizeSpine, randomizeTransform, randomizeTwist, randomizeWave };
+import { createThumbHost, prepThumbConfig, renderThumbFrame } from "./thumbnail.js";
+export { StudioWaveRenderer, createThumbHost, prepThumbConfig, randomizeBackground, randomizeColor, randomizeConfig, randomizeFinish, randomizeGlobal, randomizeGradient, randomizeLights, randomizeSpine, randomizeTransform, randomizeTwist, randomizeWave, renderThumbFrame };

package/dist/studio/index.js

@@ -1,3 +1,4 @@
 import { randomizeBackground, randomizeColor, randomizeConfig, randomizeFinish, randomizeGlobal, randomizeGradient, randomizeLights, randomizeSpine, randomizeTransform, randomizeTwist, randomizeWave } from "./randomize.js";
 import { StudioWaveRenderer } from "./StudioWaveRenderer.js";
-export { StudioWaveRenderer, randomizeBackground, randomizeColor, randomizeConfig, randomizeFinish, randomizeGlobal, randomizeGradient, randomizeLights, randomizeSpine, randomizeTransform, randomizeTwist, randomizeWave };
+import { createThumbHost, prepThumbConfig, renderThumbFrame } from "./thumbnail.js";
+export { StudioWaveRenderer, createThumbHost, prepThumbConfig, randomizeBackground, randomizeColor, randomizeConfig, randomizeFinish, randomizeGlobal, randomizeGradient, randomizeLights, randomizeSpine, randomizeTransform, randomizeTwist, randomizeWave, renderThumbFrame };

package/dist/studio/thumbnail.d.ts

@@ -0,0 +1,14 @@
+import { StudioConfig } from "../config/model.js";
+import { WaveRenderer } from "../renderer/WaveRenderer.js";
+
+//#region src/studio/thumbnail.d.ts
+/** A hidden host div that is in layout (so clientWidth/Height are real) but off-screen. */
+declare function createThumbHost(width: number, height: number): HTMLDivElement;
+/** Mutate `cfg` for a thumbnail still: static frame, opaque, white page behind solid themes
+ *  (wireframe keys its between-line colour off the dark page background, so keep it). */
+declare function prepThumbConfig(cfg: StudioConfig): void;
+/** Render the current config to a fresh 2D canvas (null if the WebGL canvas is missing). */
+declare function renderThumbFrame(renderer: WaveRenderer, host: HTMLElement): HTMLCanvasElement | null;
+//#endregion
+export { createThumbHost, prepThumbConfig, renderThumbFrame };
+//# sourceMappingURL=thumbnail.d.ts.map

package/dist/studio/thumbnail.js

@@ -0,0 +1,32 @@
+//#region src/studio/thumbnail.ts
+/** A hidden host div that is in layout (so clientWidth/Height are real) but off-screen. */
+function createThumbHost(width, height) {
+	const host = document.createElement("div");
+	host.style.cssText = `position:fixed;left:-10000px;top:0;width:${width}px;height:${height}px;opacity:0;pointer-events:none;`;
+	document.body.appendChild(host);
+	return host;
+}
+/** Mutate `cfg` for a thumbnail still: static frame, opaque, white page behind solid themes
+*  (wireframe keys its between-line colour off the dark page background, so keep it). */
+function prepThumbConfig(cfg) {
+	cfg.paused = true;
+	cfg.transparentBackground = false;
+	if (cfg.waves[0]?.theme !== "wireframe") cfg.background = "#ffffff";
+}
+/** Render the current config to a fresh 2D canvas (null if the WebGL canvas is missing). */
+function renderThumbFrame(renderer, host) {
+	renderer.resize();
+	renderer.renderOnce();
+	renderer.renderOnce();
+	const gl = host.querySelector("canvas");
+	if (!gl) return null;
+	const out = document.createElement("canvas");
+	out.width = gl.width;
+	out.height = gl.height;
+	out.getContext("2d")?.drawImage(gl, 0, 0);
+	return out;
+}
+//#endregion
+export { createThumbHost, prepThumbConfig, renderThumbFrame };
+
+//# sourceMappingURL=thumbnail.js.map

package/dist/studio/thumbnail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail.js","names":[],"sources":["../../src/studio/thumbnail.ts"],"sourcesContent":["/**\n * Offscreen thumbnail rendering: turn a config into a still frame with one hidden, reused\n * WaveRenderer. Used by the studio's preset + history thumbnails and by the wave gallery grid.\n */\nimport type { WaveRenderer } from \"../renderer/WaveRenderer\";\nimport type { StudioConfig } from \"../config/model\";\n\n/** A hidden host div that is in layout (so clientWidth/Height are real) but off-screen. */\nexport function createThumbHost(width: number, height: number): HTMLDivElement {\n  const host = document.createElement(\"div\");\n  host.style.cssText = `position:fixed;left:-10000px;top:0;width:${width}px;height:${height}px;opacity:0;pointer-events:none;`;\n  document.body.appendChild(host);\n  return host;\n}\n\n/** Mutate `cfg` for a thumbnail still: static frame, opaque, white page behind solid themes\n *  (wireframe keys its between-line colour off the dark page background, so keep it). */\nexport function prepThumbConfig(cfg: StudioConfig): void {\n  cfg.paused = true;\n  cfg.transparentBackground = false;\n  if (cfg.waves[0]?.theme !== \"wireframe\") cfg.background = \"#ffffff\";\n}\n\n/** Render the current config to a fresh 2D canvas (null if the WebGL canvas is missing). */\nexport function renderThumbFrame(\n  renderer: WaveRenderer,\n  host: HTMLElement,\n): HTMLCanvasElement | null {\n  renderer.resize();\n  renderer.renderOnce();\n  renderer.renderOnce(); // 2nd pass so any shader recompile (theme/blend variant) is applied\n  const gl = host.querySelector(\"canvas\");\n  if (!gl) return null;\n  // Copy to a 2D canvas before encoding (reliable read of the WebGL drawing buffer).\n  const out = document.createElement(\"canvas\");\n  out.width = gl.width;\n  out.height = gl.height;\n  out.getContext(\"2d\")?.drawImage(gl, 0, 0);\n  return out;\n}\n"],"mappings":";;AAQA,SAAgB,gBAAgB,OAAe,QAAgC;CAC7E,MAAM,OAAO,SAAS,cAAc,KAAK;CACzC,KAAK,MAAM,UAAU,4CAA4C,MAAM,YAAY,OAAO;CAC1F,SAAS,KAAK,YAAY,IAAI;CAC9B,OAAO;AACT;;;AAIA,SAAgB,gBAAgB,KAAyB;CACvD,IAAI,SAAS;CACb,IAAI,wBAAwB;CAC5B,IAAI,IAAI,MAAM,EAAE,EAAE,UAAU,aAAa,IAAI,aAAa;AAC5D;;AAGA,SAAgB,iBACd,UACA,MAC0B;CAC1B,SAAS,OAAO;CAChB,SAAS,WAAW;CACpB,SAAS,WAAW;CACpB,MAAM,KAAK,KAAK,cAAc,QAAQ;CACtC,IAAI,CAAC,IAAI,OAAO;CAEhB,MAAM,MAAM,SAAS,cAAc,QAAQ;CAC3C,IAAI,QAAQ,GAAG;CACf,IAAI,SAAS,GAAG;CAChB,IAAI,WAAW,IAAI,CAAC,EAAE,UAAU,IAAI,GAAG,CAAC;CACxC,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wave3d/core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Framework-agnostic 3D gradient-wave renderer + config model (the engine behind Wave Studio)",
   "keywords": [
     "animation",