@wave3d/element 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,59 @@
+# @wave3d/element
+
+The `<wave-3d>` custom element — a framework-agnostic drop-in animated **3D gradient wave** for Vue, Svelte, or plain HTML.
+
+Poster-first and lazy: it shows a poster immediately, then upgrades to live WebGL only when the browser can run it (falling back to the poster on no-WebGL, Save-Data, reduced-motion, or context loss), with `three.js` code-split out of the initial load.
+
+## Install
+
+```sh
+pnpm add @wave3d/element @wave3d/core three
+```
+
+`@wave3d/core` and `three` are peer dependencies.
+
+## Usage
+
+Importing the package registers `<wave-3d>` automatically:
+
+```html
+<script type="module">
+  import "@wave3d/element";
+</script>
+
+<wave-3d preset="Hero" poster="/wave.png" style="width:480px;height:270px"></wave-3d>
+```
+
+## Attributes & properties
+
+| Attribute | What                                                  |
+| --------- | ----------------------------------------------------- |
+| `preset`  | a built-in preset name (lazy-loads the presets chunk) |
+| `config`  | an inline JSON config                                 |
+| `src`     | URL to a config JSON to fetch                         |
+| `poster`  | poster image shown before / instead of WebGL          |
+| `paused`  | pause / resume the animation                          |
+| `lazy`    | defer the upgrade until visible                       |
+| `webgl`   | `auto` \| `force` \| `off`                            |
+
+Also a `config` **property** (merged last, over the attributes) and a read-only `handle` getter. Config precedence: **default ← `preset` ← `src` ← `config` attribute ← `config` property**.
+
+## Events
+
+- `wave3d-ready` — `detail` is the live `WaveRenderer`.
+- `wave3d-fallback` — `detail` is the fallback reason.
+
+## Custom tag name
+
+```ts
+import { register } from "@wave3d/element";
+register("my-wave"); // instead of the default <wave-3d>
+```
+
+## Credits
+
+Created by [Amir Abushanab](https://github.com/Amir-Abushanab).
+
+## License
+
+[MIT](https://github.com/Amir-Abushanab/wave3d/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { FallbackReason, StudioConfig, StudioConfig as StudioConfig$1, WaveHandle, WaveHandle as WaveHandle$1, WaveRenderer } from "@wave3d/core";
+
+//#region src/index.d.ts
+declare const ElementBase: typeof HTMLElement;
+/**
+ * `<wave-3d>` — the framework-agnostic drop-in (Vue/Svelte/plain HTML). Light DOM, `display:block`.
+ * Attributes: `config` (JSON), `src` (URL to a config JSON), `preset` (name), `poster`, `paused`,
+ * `lazy`, `webgl`. Also a `config` property and a read-only `handle` getter. Emits `wave3d-ready`
+ * (detail = renderer) and `wave3d-fallback` (detail = reason) events.
+ */
+declare class Wave3DElement extends ElementBase {
+  #private;
+  static get observedAttributes(): string[];
+  /** The live shell handle (null before connect / after disconnect). */
+  get handle(): WaveHandle$1 | null;
+  /** Programmatic config, merged last (over the `preset`/`src`/`config` attributes). */
+  get config(): Partial<StudioConfig$1>;
+  set config(value: Partial<StudioConfig$1>);
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string): void;
+}
+/** Define the element (idempotent, SSR/Node-import-safe). */
+declare function register(tag?: string): void;
+//#endregion
+export { type FallbackReason, type StudioConfig, Wave3DElement, type WaveHandle, type WaveRenderer, register };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,123 @@
+import { createWave } from "@wave3d/core";
+//#region src/index.ts
+const OBSERVED = [
+	"config",
+	"src",
+	"preset",
+	"poster",
+	"paused",
+	"lazy",
+	"webgl"
+];
+const ElementBase = typeof HTMLElement !== "undefined" ? HTMLElement : function Wave3DElementBase() {};
+/**
+* `<wave-3d>` — the framework-agnostic drop-in (Vue/Svelte/plain HTML). Light DOM, `display:block`.
+* Attributes: `config` (JSON), `src` (URL to a config JSON), `preset` (name), `poster`, `paused`,
+* `lazy`, `webgl`. Also a `config` property and a read-only `handle` getter. Emits `wave3d-ready`
+* (detail = renderer) and `wave3d-fallback` (detail = reason) events.
+*/
+var Wave3DElement = class extends ElementBase {
+	static get observedAttributes() {
+		return [...OBSERVED];
+	}
+	#handle = null;
+	#config = {};
+	#debounce;
+	/** The live shell handle (null before connect / after disconnect). */
+	get handle() {
+		return this.#handle;
+	}
+	/** Programmatic config, merged last (over the `preset`/`src`/`config` attributes). */
+	get config() {
+		return this.#config;
+	}
+	set config(value) {
+		this.#config = value ?? {};
+		this.#scheduleUpdate();
+	}
+	connectedCallback() {
+		if (!this.style.display) this.style.display = "block";
+		this.#mount();
+	}
+	disconnectedCallback() {
+		clearTimeout(this.#debounce);
+		this.#handle?.destroy();
+		this.#handle = null;
+	}
+	attributeChangedCallback(name) {
+		if (!this.#handle) return;
+		if (name === "paused") if (this.#boolAttr("paused")) this.#handle.pause();
+		else this.#handle.play();
+		else this.#scheduleUpdate();
+	}
+	async #mount() {
+		const config = await this.#buildConfig();
+		if (!this.isConnected) return;
+		const options = {
+			poster: this.getAttribute("poster") ?? void 0,
+			lazy: this.#boolAttr("lazy"),
+			webgl: this.getAttribute("webgl") ?? void 0,
+			paused: this.#boolAttr("paused"),
+			onReady: (renderer) => this.dispatchEvent(new CustomEvent("wave3d-ready", { detail: renderer })),
+			onFallback: (reason) => this.dispatchEvent(new CustomEvent("wave3d-fallback", { detail: reason }))
+		};
+		this.#handle = createWave(this, config, options);
+	}
+	/** default ← preset ← src JSON ← config attribute ← config property. */
+	async #buildConfig() {
+		let base = {};
+		const presetName = this.getAttribute("preset");
+		if (presetName) {
+			const { PRESETS } = await import("@wave3d/core/presets");
+			base = PRESETS[presetName]?.() ?? {};
+		}
+		const src = this.getAttribute("src");
+		if (src) try {
+			base = {
+				...base,
+				...await fetch(src).then((r) => r.json())
+			};
+		} catch {}
+		base = {
+			...base,
+			...parseJson(this.getAttribute("config")),
+			...this.#config
+		};
+		return base;
+	}
+	#scheduleUpdate() {
+		clearTimeout(this.#debounce);
+		this.#debounce = setTimeout(() => {
+			this.#update();
+		}, 50);
+	}
+	async #update() {
+		const handle = this.#handle;
+		if (!handle) return;
+		handle.set(await this.#buildConfig());
+	}
+	/** Presence = true; `"false"`/`"0"` = false; absent = undefined (shell default). */
+	#boolAttr(name) {
+		if (!this.hasAttribute(name)) return void 0;
+		const value = this.getAttribute(name);
+		return value !== "false" && value !== "0";
+	}
+};
+function parseJson(json) {
+	if (!json) return {};
+	try {
+		return JSON.parse(json);
+	} catch {
+		return {};
+	}
+}
+/** Define the element (idempotent, SSR/Node-import-safe). */
+function register(tag = "wave-3d") {
+	if (typeof window === "undefined" || typeof customElements === "undefined") return;
+	if (!customElements.get(tag)) customElements.define(tag, Wave3DElement);
+}
+register();
+//#endregion
+export { Wave3DElement, register };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#handle","#config","#scheduleUpdate","#mount","#debounce","#boolAttr","#buildConfig","#update"],"sources":["../src/index.ts"],"sourcesContent":["import { createWave } from \"@wave3d/core\";\nimport type {\n  StudioConfig,\n  WaveHandle,\n  WaveOptions,\n  WaveRenderer,\n  FallbackReason,\n} from \"@wave3d/core\";\n\nconst OBSERVED = [\"config\", \"src\", \"preset\", \"poster\", \"paused\", \"lazy\", \"webgl\"] as const;\n\n// SSR-safe base: `class extends HTMLElement` evaluates HTMLElement at import time, which throws\n// under Node. Fall back to a dummy base there — the element is never instantiated server-side\n// (register() is guarded), so the missing DOM methods are never called.\nconst ElementBase: typeof HTMLElement =\n  typeof HTMLElement !== \"undefined\"\n    ? HTMLElement\n    : (function Wave3DElementBase() {} as unknown as typeof HTMLElement);\n\n/**\n * `<wave-3d>` — the framework-agnostic drop-in (Vue/Svelte/plain HTML). Light DOM, `display:block`.\n * Attributes: `config` (JSON), `src` (URL to a config JSON), `preset` (name), `poster`, `paused`,\n * `lazy`, `webgl`. Also a `config` property and a read-only `handle` getter. Emits `wave3d-ready`\n * (detail = renderer) and `wave3d-fallback` (detail = reason) events.\n */\nexport class Wave3DElement extends ElementBase {\n  static get observedAttributes(): string[] {\n    return [...OBSERVED];\n  }\n\n  #handle: WaveHandle | null = null;\n  #config: Partial<StudioConfig> = {};\n  #debounce?: ReturnType<typeof setTimeout>;\n\n  /** The live shell handle (null before connect / after disconnect). */\n  get handle(): WaveHandle | null {\n    return this.#handle;\n  }\n\n  /** Programmatic config, merged last (over the `preset`/`src`/`config` attributes). */\n  get config(): Partial<StudioConfig> {\n    return this.#config;\n  }\n  set config(value: Partial<StudioConfig>) {\n    this.#config = value ?? {};\n    this.#scheduleUpdate();\n  }\n\n  connectedCallback(): void {\n    if (!this.style.display) this.style.display = \"block\";\n    void this.#mount();\n  }\n\n  disconnectedCallback(): void {\n    clearTimeout(this.#debounce);\n    this.#handle?.destroy();\n    this.#handle = null;\n  }\n\n  attributeChangedCallback(name: string): void {\n    if (!this.#handle) return;\n    if (name === \"paused\") {\n      if (this.#boolAttr(\"paused\")) this.#handle.pause();\n      else this.#handle.play();\n    } else {\n      this.#scheduleUpdate();\n    }\n  }\n\n  async #mount(): Promise<void> {\n    const config = await this.#buildConfig();\n    if (!this.isConnected) return; // disconnected while the config resolved\n    const options: WaveOptions = {\n      poster: this.getAttribute(\"poster\") ?? undefined,\n      lazy: this.#boolAttr(\"lazy\"),\n      webgl: (this.getAttribute(\"webgl\") as WaveOptions[\"webgl\"]) ?? undefined,\n      paused: this.#boolAttr(\"paused\"),\n      onReady: (renderer: WaveRenderer) =>\n        this.dispatchEvent(new CustomEvent(\"wave3d-ready\", { detail: renderer })),\n      onFallback: (reason: FallbackReason) =>\n        this.dispatchEvent(new CustomEvent(\"wave3d-fallback\", { detail: reason })),\n    };\n    this.#handle = createWave(this, config, options);\n  }\n\n  /** default ← preset ← src JSON ← config attribute ← config property. */\n  async #buildConfig(): Promise<Partial<StudioConfig>> {\n    let base: Partial<StudioConfig> = {};\n    const presetName = this.getAttribute(\"preset\");\n    if (presetName) {\n      const { PRESETS } = await import(\"@wave3d/core/presets\");\n      base = PRESETS[presetName]?.() ?? {};\n    }\n    const src = this.getAttribute(\"src\");\n    if (src) {\n      try {\n        base = { ...base, ...(await fetch(src).then((r) => r.json())) };\n      } catch {\n        // ignore a failed/invalid config fetch — fall through to whatever we have\n      }\n    }\n    base = { ...base, ...parseJson(this.getAttribute(\"config\")), ...this.#config };\n    return base;\n  }\n\n  #scheduleUpdate(): void {\n    clearTimeout(this.#debounce);\n    this.#debounce = setTimeout(() => {\n      void this.#update();\n    }, 50);\n  }\n\n  async #update(): Promise<void> {\n    const handle = this.#handle;\n    if (!handle) return;\n    handle.set(await this.#buildConfig());\n  }\n\n  /** Presence = true; `\"false\"`/`\"0\"` = false; absent = undefined (shell default). */\n  #boolAttr(name: string): boolean | undefined {\n    if (!this.hasAttribute(name)) return undefined;\n    const value = this.getAttribute(name);\n    return value !== \"false\" && value !== \"0\";\n  }\n}\n\nfunction parseJson(json: string | null): Partial<StudioConfig> {\n  if (!json) return {};\n  try {\n    return JSON.parse(json) as Partial<StudioConfig>;\n  } catch {\n    return {};\n  }\n}\n\n/** Define the element (idempotent, SSR/Node-import-safe). */\nexport function register(tag = \"wave-3d\"): void {\n  if (typeof window === \"undefined\" || typeof customElements === \"undefined\") return;\n  if (!customElements.get(tag)) customElements.define(tag, Wave3DElement);\n}\n\n// Self-register on import so a bare `import \"@wave3d/element\"` makes <wave-3d> work. Guarded so\n// importing under Node (SSR) is a no-op rather than a ReferenceError.\nregister();\n\nexport type { StudioConfig, WaveHandle, WaveRenderer, FallbackReason } from \"@wave3d/core\";\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@wave3d/element",
+  "version": "0.1.0",
+  "description": "<wave-3d> custom element for @wave3d — a framework-agnostic drop-in animated gradient wave (the Vue/Svelte/plain-HTML story)",
+  "keywords": [
+    "background",
+    "custom-elements",
+    "gradient",
+    "svelte",
+    "three",
+    "vue",
+    "wave",
+    "web-components",
+    "webgl"
+  ],
+  "homepage": "https://github.com/Amir-Abushanab/wave3d/tree/main/packages/element#readme",
+  "bugs": "https://github.com/Amir-Abushanab/wave3d/issues",
+  "license": "MIT",
+  "author": "Amir Abushanab (https://github.com/Amir-Abushanab)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Amir-Abushanab/wave3d.git",
+    "directory": "packages/element"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./src/index.ts",
+    "./dist/index.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@wave3d/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@wave3d/core": "^0.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown"
+  }
+}