@wave3d/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wave Studio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @wave3d/core
+
+Framework-agnostic **3D gradient-wave** renderer + config model — the engine behind [Wave Studio](https://github.com/Amir-Abushanab/wave3d).
+
+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.
+
+## Install
+
+```sh
+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)
+
+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.
+
+```ts
+import { createWave } from "@wave3d/core";
+
+const handle = createWave(document.getElementById("wave"), config, {
+  poster: "/wave.png",
+});
+// handle.set(nextConfig) · handle.pause() · handle.play() · handle.destroy()
+```
+
+## Single `<script>` from a CDN (three bundled)
+
+```html
+<script type="module">
+  import { mountWave } from "https://esm.sh/@wave3d/core/standalone";
+  mountWave(document.getElementById("wave"), {
+    /* 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)         |
+
+## 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.
+
+## Credits
+
+Created by [Amir Abushanab](https://github.com/Amir-Abushanab).
+
+## License
+
+[MIT](https://github.com/Amir-Abushanab/wave3d/blob/main/LICENSE)

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/config/model.d.ts

@@ -0,0 +1,240 @@
+//#region src/config/model.d.ts
+/**
+ * Configuration schema for the wave: a flat sheet displaced by noise (X/Z frequency
+ * + amount) then twisted by three axis-rotations (twistFrequency + twistPower per
+ * axis), then scaled / rotated / positioned. Plain JSON — doubles as the save-state
+ * format.
+ */
+declare const MAX_COLORS = 8;
+declare const MAX_MESH_POINTS = 8;
+declare const MAX_LIGHTS = 8;
+declare const MAX_NOISE_BANDS = 4;
+/** Cap on stacked waves (keeps total geometry bounded — see WaveRenderer segment scaling). */
+declare const MAX_WAVES = 6;
+interface Vec2 {
+  x: number;
+  y: number;
+}
+interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+type BlendMode = "squared" | "normal" | "additive" | "multiply";
+/** How the palette is mapped across the surface. */
+type BasicGradientType = "linear" | "radial" | "conic";
+type GradientType = BasicGradientType | "mesh";
+type BackgroundMode = "color" | "gradient" | "image";
+type BackgroundImageFit = "cover" | "contain" | "stretch";
+/** What fills the 2D palette texture: the baked hero LUT, our editable stops, or
+ *  a named built-in map (see PALETTE_MAPS). Any string is allowed for forward-compat. */
+type PaletteSource = "hero" | "stops" | (string & {});
+/** A positionable light. `position` lives in the same 3D space as the wave. */
+interface LightConfig {
+  position: Vec3;
+  color: string;
+  intensity: number;
+}
+/** A default light; pass overrides for added fill lights. */
+declare function createLight(position?: Vec3, intensity?: number): LightConfig;
+/** Where the first light lands when you engage lights from an empty scene. Shared by the
+ *  "drag in 3D" control and the camera-rig minimap, which previews a light marker here so the
+ *  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
+ * per region instead of uniform.
+ */
+interface NoiseBand {
+  startX: number;
+  endX: number;
+  startY: number;
+  endY: number;
+  feather: number;
+  strength: number;
+  frequency: number;
+  colorAttenuation: number;
+  parabolaPower: number;
+}
+/** 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. */
+interface ColorStop {
+  color: string;
+  pos: number;
+}
+/** One colour influence point in the 2D mesh-gradient field. */
+interface MeshGradientPoint {
+  color: string;
+  /** Horizontal UV position (0–1). */
+  x: number;
+  /** Vertical UV position (0–1). */
+  y: number;
+  /** Relative reach of this point's colour field. */
+  influence: number;
+}
+/** Build evenly-spaced stops from a plain list of colours. */
+declare function makeStops(colors: string[]): ColorStop[];
+/** A balanced iOS-style field shown the first time Mesh is selected. */
+declare function createDefaultMeshPoints(): MeshGradientPoint[];
+/**
+ * A single wave: a COMPLETE, self-contained wave — its own shape, twist, colour, finish,
+ * transform and blend. Stacking waves composites independent waves; there is no shared
+ * "base wave" any more, so nothing is duplicated between a global section and the waves.
+ * Field names mirror the legacy top-level wave fields so migration + the per-section helpers
+ * (normalizeWaveColour, randomize*) map 1:1.
+ */
+interface WaveConfig {
+  palette: ColorStop[];
+  gradientType: GradientType;
+  gradientAngle: number;
+  gradientShift: number;
+  meshGradientPoints: MeshGradientPoint[];
+  meshGradientSoftness: number;
+  usePaletteTexture: boolean;
+  paletteSource: PaletteSource;
+  paletteImageUrl?: string;
+  paletteVideoUrl?: string;
+  paletteTextureScale: Vec2;
+  paletteTextureOffset: Vec2;
+  paletteTextureRotation: number;
+  /** Palette-offset drift per second (animates colour independently of the geometry; 0 = static).
+   *  Applies to any texture palette (not mesh / procedural stops). */
+  paletteDriftX: number;
+  paletteDriftY: number;
+  paletteEdgeColor: string;
+  paletteEdgeAmount: number;
+  hueShift: number;
+  colorContrast: number;
+  colorSaturation: number;
+  fiberCount: number;
+  fiberStrength: number;
+  noiseBands: NoiseBand[];
+  texture: number;
+  creaseLight: number;
+  creaseSharpness: number;
+  creaseSoftness: number;
+  sheen: number;
+  roundness: number;
+  /** 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. */
+  edgeFeather: number;
+  /** Depth tint (solid theme): fade far fragments toward depthTintColor for atmospheric
+   *  separation in multi-wave stacks (0 = off). */
+  depthTint: number;
+  depthTintColor: string;
+  displaceFrequency: Vec2;
+  displaceAmount: number;
+  /** Optional 2nd displacement octave: finer ripples riding on the broad swell (amount 0 = off). */
+  detailFrequency: number;
+  detailAmount: number;
+  twistFrequency: Vec3;
+  twistPower: Vec3;
+  twistMotion?: boolean;
+  theme?: "solid" | "wireframe";
+  lineAmount?: number;
+  lineThickness?: number;
+  lineDerivativePower?: number;
+  maxWidth?: number;
+  position: Vec3;
+  rotation: Vec3;
+  scale: Vec3;
+  blendMode: BlendMode;
+  /** Absolute animation speed for this wave (legacy global speed × per-layer multiplier). */
+  speed: number;
+  /** Overall opacity of this wave. */
+  opacity: number;
+  /** Phase/seed so waves don't move in lockstep. */
+  seed: number;
+}
+/**
+ * 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
+ * describes an individual wave lives on WaveConfig instead.
+ */
+interface SceneConfig {
+  background: string;
+  transparentBackground: boolean;
+  backgroundMode: BackgroundMode;
+  backgroundPalette: ColorStop[];
+  backgroundGradientType: GradientType;
+  backgroundGradientAngle: number;
+  backgroundGradientSource: PaletteSource;
+  backgroundMeshPoints: MeshGradientPoint[];
+  backgroundMeshSoftness: number;
+  backgroundImageSource: PaletteSource;
+  backgroundImageUrl?: string;
+  backgroundVideoUrl?: string;
+  backgroundImageFit: BackgroundImageFit;
+  backgroundImageZoom: number;
+  backgroundImagePosition: Vec2;
+  /** Number of stacked waves (kept in sync with waves.length). */
+  waveCount: number;
+  quality: number;
+  dprMax: number;
+  paused: boolean;
+  /** Noise phase offset — scrubs the noise pattern to pick a still frame. */
+  timeOffset?: number;
+  /** Seamless-loop period in seconds (0 = off). When >0, the motion is mapped onto a circle in
+   *  noise space so it repeats exactly every `loopSeconds` — scene-level so a multi-wave stack
+   *  shares one period and the whole composite loops. */
+  loopSeconds?: number;
+  introRamp?: boolean;
+  showCameraRig: boolean;
+  cameraDistance: number;
+  cameraZoom: number;
+  cameraPosition: Vec3;
+  cameraTarget: Vec3;
+  /** Film grain amount (post pass). */
+  grain: number;
+  /** Soft-focus / spin blur amount (post pass). */
+  blur: number;
+  blurSamples?: number;
+  /** Bloom (post pass, UnrealBloomPass). strength 0 removes the pass entirely, so cost and pixels
+   *  are identical to bloom-off; radius/threshold only take effect once strength > 0. */
+  bloomStrength?: number;
+  bloomRadius?: number;
+  bloomThreshold?: number;
+  /** Base ambient light level (0–1). */
+  ambient: number;
+  lights: LightConfig[];
+  /** Mirror the whole composition on screen (world-space flip). */
+  mirrorH: boolean;
+  mirrorV: boolean;
+}
+/** The full save-state: scene settings + one or more complete waves. */
+interface StudioConfig extends SceneConfig {
+  waves: WaveConfig[];
+}
+/** 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. */
+declare function makeWaveSpread(base: WaveConfig, count: number): WaveConfig[];
+/** A fresh default wave (the hero wave as one complete wave). */
+declare function makeWave(): WaveConfig;
+/** Resize `waves` to match `waveCount`. New waves CLONE the last one (inherit every
+ *  property of the preceding wave); extras are dropped. */
+declare function resizeWaves(config: StudioConfig): void;
+/** The default studio config: the hero wave + its scene, in the canonical wave model. */
+declare function createDefaultConfig(): StudioConfig;
+/** Backfill background styling for states saved before gradient/image backgrounds existed. */
+declare function normalizeBackground(config: StudioConfig): void;
+/** Backfill camera position/target for states saved before they existed. */
+declare function ensureCamera(config: StudioConfig): void;
+/** Backfill/repair a wave so the renderer can consume it (covers partial wave-model JSON). */
+declare function normalizeWave(s: WaveConfig): void;
+/** Backfill scene-level defaults (background/camera/post/lights/quality/mirror). */
+declare function ensureSceneDefaults(config: StudioConfig): 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, 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 };
+//# sourceMappingURL=model.d.ts.map