@materials3d/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amir Abushanab
+
+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,85 @@
+<a href="https://github.com/Amir-Abushanab/materials3d"><img src="https://raw.githubusercontent.com/Amir-Abushanab/materials3d/main/brand/icon-192.png" alt="" width="64" align="right"></a>
+
+# @materials3d/react
+
+The `<Materials3D>` component: a drop-in Materials3D scene for React.
+
+```bash
+pnpm add @materials3d/react three
+```
+
+```tsx
+import { Materials3D } from "@materials3d/react";
+
+export function Hero() {
+  return (
+    <Materials3D
+      preset="skewer"
+      poster="/hero.webp"
+      minSizeForWebGL={520}
+      style={{ width: "100%", height: "100vh" }}
+    />
+  );
+}
+```
+
+Renders a `<div>` and mounts the shell on the client: poster first, lazy, aware of WebGL, reduced
+motion and Save-Data, with three code-split out of the initial bundle.
+
+## Props
+
+Precedence: the defaults, then `preset`, then the flat props, then `config`.
+
+| prop                                                                                          | notes                                                                                                                                                                                                               |
+| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preset`                                                                                      | a name (`"skewer"`, `"assembly"`, `"staircase"`, `"slimes"`, `"reactions"`, `"materials"`, `"prism"`, `"orb"`) or a function returning a config. A name lazy-loads the presets chunk; a function is tree-shakeable. |
+| `config`                                                                                      | a full or partial config, applied last                                                                                                                                                                              |
+| `lamps`, `lampGain`, `background`, `transparentBackground`, `clearGlass`                      | the light field and the backdrop                                                                                                                                                                                    |
+| `post`, `motion`, `scatter`                                                                   | merged onto what the preset authored, so `scatter={{ count: 24 }}` re-scatters the reference scene; `motion` applies to every shape                                                                                 |
+| `orbit`, `quality`, `dprMax`, `paused`                                                        | live                                                                                                                                                                                                                |
+| `poster`, `posterFit`, `lazy`, `webgl`, `minSizeForWebGL`, `respectReducedMotion`, `renderer` | shell options, read at mount only. Changing one on a mounted component does nothing until it remounts.                                                                                                              |
+| `onReady(renderer)`, `onFallback(reason)`                                                     | callbacks; the latest ones are called without a remount                                                                                                                                                             |
+| `className`, `style`, `children`                                                              | the `<div>`                                                                                                                                                                                                         |
+
+Config-shaped props update the live scene through the handle. A changed shape list or scatter
+rebuilds geometry; everything else pushes uniforms.
+
+## The handle
+
+A `ref` receives a `MaterialHandle`: `snapshot({ time })`, `set(partial)`, `play()`, `pause()`,
+`destroy()`, `state` and `renderer`. The object is stable and delegates to whichever shell is live,
+so it survives StrictMode's remount.
+
+```tsx
+import { useRef } from "react";
+import { Materials3D, type MaterialHandle } from "@materials3d/react";
+
+export function Hero() {
+  const ref = useRef<MaterialHandle>(null);
+  return (
+    <>
+      <Materials3D ref={ref} preset="orb" poster="/orb.webp" style={{ height: 480 }} />
+      <button onClick={() => ref.current?.pause()}>Pause</button>
+    </>
+  );
+}
+```
+
+Before the shell exists `state` reads `"poster"` and the calls are no-ops. `snapshot` resolves
+`null` until the scene is running; wait for `onReady`.
+
+## SSR
+
+The component is SSR-safe. For a server-rendered poster with no hydration flash, pass the image as
+a child and the shell adopts it. The adopted image is put back on unmount, so it survives
+StrictMode's double mount:
+
+```tsx
+<Materials3D preset="skewer">
+  <img data-materials3d-poster src="/hero.webp" alt="" />
+</Materials3D>
+```
+
+Peer dependencies: `react >= 18`, `three >= 0.180 < 1`. `@types/three` is an optional peer.
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import { CSSProperties, ReactElement, ReactNode, Ref } from "react";
+import { EngineFor, FallbackReason, FallbackReason as FallbackReason$1, LampConfig, MaterialHandle, MaterialHandle as MaterialHandle$1, MotionConfig, PostConfig, PosterFit, RendererKind, ScatterConfig, SceneConfig, SceneConfig as SceneConfig$1, SnapshotOptions } from "@materials3d/core";
+//#region src/index.d.ts
+/** Flat props for the settings people actually reach for; anything else goes through `config`. */
+interface FlatProps {
+  /** The bounded field of light behind the glass. */
+  lamps?: LampConfig[];
+  lampGain?: number;
+  background?: string;
+  /** Drop the backdrop so the scene composites over the page behind it. */
+  transparentBackground?: boolean;
+  clearGlass?: string;
+  post?: Partial<PostConfig>;
+  /** Motion for the shapes a `scatter` generates. Per-shape motion on hand-authored `items` goes
+   *  through the `config` prop, a flat prop can only mean "all of them". */
+  motion?: Partial<MotionConfig>;
+  scatter?: Partial<ScatterConfig>;
+  orbit?: boolean;
+  quality?: number;
+  dprMax?: number;
+  paused?: boolean;
+}
+interface Materials3DProps<R extends RendererKind = "webgl"> extends FlatProps {
+  /** A preset: a function (tree-shakeable) or a name string (lazy-imports the presets chunk). */
+  preset?: string | (() => Partial<SceneConfig$1>);
+  /**
+   * Escape hatch: a full/partial config, applied last and merged one level deep, so
+   * `config={{ post: { bloom: 1 } }}` keeps the rest of the post block.
+   * Precedence: default ← preset ← flat props ← config.
+   */
+  config?: Partial<SceneConfig$1>;
+  poster?: string;
+  /** Poster `object-fit`. Default `"fill"` (matches the canvas → seamless handoff). */
+  posterFit?: PosterFit;
+  lazy?: boolean;
+  webgl?: "auto" | "force" | "off";
+  /**
+   * Which engine build to fetch. Default `"webgl"`.
+   *
+   * `"webgpu"` fetches a separate, larger bundle, three's node renderer and TSL, and is the only
+   * way to reach a WebGPU backend. It selects the ENGINE, not the backend: it still runs on WebGL
+   * where the browser has no WebGPU. See `MaterialOptions.renderer`.
+   */
+  renderer?: R;
+  respectReducedMotion?: boolean;
+  /** Stay a poster below this container size in CSS pixels. Four passes at phone DPR is real
+   *  work, and a still frame of glass loses less than a still frame of most things. */
+  minSizeForWebGL?: number;
+  className?: string;
+  style?: CSSProperties;
+  /** Custom SSR poster markup, e.g. `<img data-materials3d-poster src="…" />`, the shell adopts it. */
+  children?: ReactNode;
+  onReady?: (renderer: EngineFor<R>) => void;
+  onFallback?: (reason: FallbackReason$1) => void;
+}
+/**
+ * A drop-in, self-optimizing Materials3D scene. Renders a `<div>` (SSR-safe; pass an
+ * `<img data-materials3d-poster>` child for a server-rendered poster) and, on the client, mounts the
+ * shell: poster-first, lazy, WebGL/reduced-motion/save-data aware, with the engine code-split out.
+ *
+ * A `ref` receives the {@link MaterialHandle} (`state`, `renderer`, `snapshot()`, `set()`,
+ * `play()`, `pause()`), on React 18 and 19 alike. `forwardRef` keeps the generic engine parameter
+ * only through this cast, which is why the component is declared this way.
+ */
+declare const Materials3D: <R extends RendererKind = "webgl">(props: Materials3DProps<R> & {
+  ref?: Ref<MaterialHandle$1<R>>;
+}) => ReactElement;
+//#endregion
+export { type FallbackReason, type MaterialHandle, Materials3D, Materials3D as default, Materials3DProps, type SceneConfig, type SnapshotOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,194 @@
+"use client";
+import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef } from "react";
+import { createDefaultConfig, createMaterials, mergeSceneConfig } from "@materials3d/core";
+import { jsx } from "react/jsx-runtime";
+//#region src/index.tsx
+/** Resolve the base config: function preset (sync) → its config; string preset → lazy-load. */
+async function resolveBase(preset) {
+	if (typeof preset === "function") return {
+		...createDefaultConfig(),
+		...preset()
+	};
+	if (typeof preset === "string") {
+		const { PRESETS, isPresetName } = await import("@materials3d/core/presets");
+		if (isPresetName(preset)) return PRESETS[preset]();
+	}
+	return createDefaultConfig();
+}
+/** The base we can build synchronously (function preset / default); a string preset resolves later. */
+function syncBase(preset) {
+	return typeof preset === "function" ? {
+		...createDefaultConfig(),
+		...preset()
+	} : createDefaultConfig();
+}
+/** Apply the flat props (and the config escape hatch) onto a full base config. */
+function buildConfig(base, props) {
+	const out = structuredClone(base);
+	if (props.lamps !== void 0) out.lamps = props.lamps;
+	if (props.lampGain !== void 0) out.lampGain = props.lampGain;
+	if (props.background !== void 0) out.background = props.background;
+	if (props.transparentBackground !== void 0) out.transparentBackground = props.transparentBackground;
+	if (props.clearGlass !== void 0) out.clearGlass = props.clearGlass;
+	if (props.post !== void 0) out.post = {
+		...out.post,
+		...props.post
+	};
+	if (props.motion !== void 0) {
+		const motion = props.motion;
+		if (out.scatter) out.scatter.motion = {
+			...out.scatter.motion,
+			...motion
+		};
+		for (const item of out.items) item.motion = {
+			...item.motion,
+			...motion
+		};
+	}
+	if (props.scatter !== void 0 && out.scatter) out.scatter = {
+		...out.scatter,
+		...props.scatter
+	};
+	if (props.orbit !== void 0) out.orbit = props.orbit;
+	if (props.quality !== void 0) out.quality = props.quality;
+	if (props.dprMax !== void 0) out.dprMax = props.dprMax;
+	if (props.paused !== void 0) out.paused = props.paused;
+	return props.config ? mergeSceneConfig(out, props.config) : out;
+}
+/**
+* Function presets are keyed by identity: swapping one function for another must re-run the update
+* effect, and a single string cannot say which function it saw. An inline (per-render) function
+* gets a fresh id each render, which re-runs the effect, `setConfig`'s structural diff makes that
+* a no-op, but memoize the preset if you want the effect to skip entirely.
+*/
+const presetIds = /* @__PURE__ */ new WeakMap();
+let nextPresetId = 0;
+function presetKey(preset) {
+	if (typeof preset !== "function") return preset;
+	let id = presetIds.get(preset);
+	if (id === void 0) presetIds.set(preset, id = nextPresetId++);
+	return `fn#${id}`;
+}
+/** A stable string that changes whenever the resolved config would, keys the update effect. */
+function configKey(props) {
+	const flat = {};
+	for (const k of [
+		"lamps",
+		"lampGain",
+		"background",
+		"transparentBackground",
+		"clearGlass",
+		"post",
+		"motion",
+		"scatter",
+		"orbit",
+		"quality",
+		"dprMax",
+		"paused"
+	]) if (props[k] !== void 0) flat[k] = props[k];
+	return JSON.stringify({
+		preset: presetKey(props.preset),
+		flat,
+		config: props.config
+	});
+}
+/** The state the handle reports before the shell exists: what the server-rendered div shows. */
+const IDLE_STATE = "poster";
+function Materials3DInner(props, ref) {
+	const { className, style, children } = props;
+	const containerRef = useRef(null);
+	const handleRef = useRef(null);
+	const cbRef = useRef({});
+	cbRef.current.onReady = props.onReady;
+	cbRef.current.onFallback = props.onFallback;
+	const key = useMemo(() => configKey(props), [
+		props.preset,
+		props.lamps,
+		props.lampGain,
+		props.background,
+		props.transparentBackground,
+		props.clearGlass,
+		props.post,
+		props.motion,
+		props.scatter,
+		props.orbit,
+		props.quality,
+		props.dprMax,
+		props.paused,
+		props.config
+	]);
+	const appliedKeyRef = useRef(null);
+	useImperativeHandle(ref, () => ({
+		get state() {
+			return handleRef.current?.state ?? IDLE_STATE;
+		},
+		get renderer() {
+			return handleRef.current?.renderer ?? null;
+		},
+		snapshot: (opts) => handleRef.current?.snapshot(opts) ?? Promise.resolve(null),
+		set: (config) => handleRef.current?.set(config),
+		play: () => handleRef.current?.play(),
+		pause: () => handleRef.current?.pause(),
+		destroy: () => handleRef.current?.destroy()
+	}), []);
+	useEffect(() => {
+		const container = containerRef.current;
+		if (!container) return;
+		let cancelled = false;
+		const options = {
+			poster: props.poster,
+			posterFit: props.posterFit,
+			lazy: props.lazy,
+			webgl: props.webgl,
+			renderer: props.renderer,
+			respectReducedMotion: props.respectReducedMotion,
+			minSizeForWebGL: props.minSizeForWebGL,
+			onReady: (r) => cbRef.current.onReady?.(r),
+			onFallback: (reason) => cbRef.current.onFallback?.(reason)
+		};
+		const handle = createMaterials(container, buildConfig(syncBase(props.preset), props), options);
+		handleRef.current = handle;
+		appliedKeyRef.current = key;
+		if (typeof props.preset === "string") resolveBase(props.preset).then((base) => {
+			if (!cancelled && handleRef.current === handle) handle.set(buildConfig(base, props));
+		});
+		return () => {
+			cancelled = true;
+			handle.destroy();
+			handleRef.current = null;
+			appliedKeyRef.current = null;
+		};
+	}, []);
+	useEffect(() => {
+		const handle = handleRef.current;
+		if (!handle || appliedKeyRef.current === key) return;
+		appliedKeyRef.current = key;
+		const apply = (base) => {
+			if (handleRef.current === handle) handle.set(buildConfig(base, props));
+		};
+		if (typeof props.preset === "string") resolveBase(props.preset).then(apply);
+		else apply(syncBase(props.preset));
+	}, [key]);
+	return /* @__PURE__ */ jsx("div", {
+		ref: containerRef,
+		className,
+		style,
+		children
+	});
+}
+const Materials3DWithRef = forwardRef(Materials3DInner);
+Materials3DWithRef.displayName = "Materials3D";
+/**
+* A drop-in, self-optimizing Materials3D scene. Renders a `<div>` (SSR-safe; pass an
+* `<img data-materials3d-poster>` child for a server-rendered poster) and, on the client, mounts the
+* shell: poster-first, lazy, WebGL/reduced-motion/save-data aware, with the engine code-split out.
+*
+* A `ref` receives the {@link MaterialHandle} (`state`, `renderer`, `snapshot()`, `set()`,
+* `play()`, `pause()`), on React 18 and 19 alike. `forwardRef` keeps the generic engine parameter
+* only through this cast, which is why the component is declared this way.
+*/
+const Materials3D = Materials3DWithRef;
+//#endregion
+export { Materials3D, Materials3D as default };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.tsx"],"sourcesContent":["\"use client\";\n\nimport { forwardRef, useEffect, useImperativeHandle, useMemo, useRef } from \"react\";\nimport type { CSSProperties, ForwardedRef, ReactElement, ReactNode, Ref } from \"react\";\nimport { createDefaultConfig, createMaterials, mergeSceneConfig } from \"@materials3d/core\";\nimport type {\n  FallbackReason,\n  SceneConfig,\n  MaterialHandle,\n  MaterialOptions,\n  LampConfig,\n  MotionConfig,\n  PosterFit,\n  RendererKind,\n  EngineFor,\n  PostConfig,\n  ScatterConfig,\n} from \"@materials3d/core\";\n\n/** Flat props for the settings people actually reach for; anything else goes through `config`. */\ninterface FlatProps {\n  /** The bounded field of light behind the glass. */\n  lamps?: LampConfig[];\n  lampGain?: number;\n  background?: string;\n  /** Drop the backdrop so the scene composites over the page behind it. */\n  transparentBackground?: boolean;\n  clearGlass?: string;\n  post?: Partial<PostConfig>;\n  /** Motion for the shapes a `scatter` generates. Per-shape motion on hand-authored `items` goes\n   *  through the `config` prop, a flat prop can only mean \"all of them\". */\n  motion?: Partial<MotionConfig>;\n  scatter?: Partial<ScatterConfig>;\n  orbit?: boolean;\n  quality?: number;\n  dprMax?: number;\n  paused?: boolean;\n}\n\nexport interface Materials3DProps<R extends RendererKind = \"webgl\"> extends FlatProps {\n  /** A preset: a function (tree-shakeable) or a name string (lazy-imports the presets chunk). */\n  preset?: string | (() => Partial<SceneConfig>);\n  /**\n   * Escape hatch: a full/partial config, applied last and merged one level deep, so\n   * `config={{ post: { bloom: 1 } }}` keeps the rest of the post block.\n   * Precedence: default ← preset ← flat props ← config.\n   */\n  config?: Partial<SceneConfig>;\n  poster?: string;\n  /** Poster `object-fit`. Default `\"fill\"` (matches the canvas → seamless handoff). */\n  posterFit?: PosterFit;\n  lazy?: boolean;\n  webgl?: \"auto\" | \"force\" | \"off\";\n  /**\n   * Which engine build to fetch. Default `\"webgl\"`.\n   *\n   * `\"webgpu\"` fetches a separate, larger bundle, three's node renderer and TSL, and is the only\n   * way to reach a WebGPU backend. It selects the ENGINE, not the backend: it still runs on WebGL\n   * where the browser has no WebGPU. See `MaterialOptions.renderer`.\n   */\n  renderer?: R;\n  respectReducedMotion?: boolean;\n  /** Stay a poster below this container size in CSS pixels. Four passes at phone DPR is real\n   *  work, and a still frame of glass loses less than a still frame of most things. */\n  minSizeForWebGL?: number;\n  className?: string;\n  style?: CSSProperties;\n  /** Custom SSR poster markup, e.g. `<img data-materials3d-poster src=\"…\" />`, the shell adopts it. */\n  children?: ReactNode;\n  onReady?: (renderer: EngineFor<R>) => void;\n  onFallback?: (reason: FallbackReason) => void;\n}\n\n/** Resolve the base config: function preset (sync) → its config; string preset → lazy-load. */\nasync function resolveBase(preset: Materials3DProps[\"preset\"]): Promise<SceneConfig> {\n  if (typeof preset === \"function\") return { ...createDefaultConfig(), ...preset() };\n  if (typeof preset === \"string\") {\n    const { PRESETS, isPresetName } = await import(\"@materials3d/core/presets\");\n    if (isPresetName(preset)) return PRESETS[preset]();\n  }\n  return createDefaultConfig();\n}\n\n/** The base we can build synchronously (function preset / default); a string preset resolves later. */\nfunction syncBase(preset: Materials3DProps[\"preset\"]): SceneConfig {\n  return typeof preset === \"function\"\n    ? { ...createDefaultConfig(), ...preset() }\n    : createDefaultConfig();\n}\n\n/** Apply the flat props (and the config escape hatch) onto a full base config. */\nfunction buildConfig(\n  base: SceneConfig,\n  props: Materials3DProps<RendererKind>,\n): Partial<SceneConfig> {\n  // A function preset may hand back the same object on every call (a module-level constant, say),\n  // and the base is spread only one level deep from it, so copy before writing into any block.\n  const out = structuredClone(base);\n  if (props.lamps !== undefined) out.lamps = props.lamps;\n  if (props.lampGain !== undefined) out.lampGain = props.lampGain;\n  if (props.background !== undefined) out.background = props.background;\n  if (props.transparentBackground !== undefined) {\n    out.transparentBackground = props.transparentBackground;\n  }\n  if (props.clearGlass !== undefined) out.clearGlass = props.clearGlass;\n  if (props.post !== undefined) out.post = { ...out.post, ...props.post };\n  if (props.motion !== undefined) {\n    const motion = props.motion;\n    if (out.scatter) out.scatter.motion = { ...out.scatter.motion, ...motion };\n    for (const item of out.items) item.motion = { ...item.motion, ...motion };\n  }\n  // A partial scatter merges onto whatever the preset authored, so `scatter={{ count: 24 }}` is\n  // enough to re-scatter the reference scene.\n  if (props.scatter !== undefined && out.scatter) {\n    out.scatter = { ...out.scatter, ...props.scatter };\n  }\n  if (props.orbit !== undefined) out.orbit = props.orbit;\n  if (props.quality !== undefined) out.quality = props.quality;\n  if (props.dprMax !== undefined) out.dprMax = props.dprMax;\n  if (props.paused !== undefined) out.paused = props.paused;\n  return props.config ? mergeSceneConfig(out, props.config) : out;\n}\n\n/**\n * Function presets are keyed by identity: swapping one function for another must re-run the update\n * effect, and a single string cannot say which function it saw. An inline (per-render) function\n * gets a fresh id each render, which re-runs the effect, `setConfig`'s structural diff makes that\n * a no-op, but memoize the preset if you want the effect to skip entirely.\n */\nconst presetIds = new WeakMap<object, number>();\nlet nextPresetId = 0;\nfunction presetKey(preset: Materials3DProps[\"preset\"]): string | undefined {\n  if (typeof preset !== \"function\") return preset;\n  let id = presetIds.get(preset);\n  if (id === undefined) presetIds.set(preset, (id = nextPresetId++));\n  return `fn#${id}`;\n}\n\n/** A stable string that changes whenever the resolved config would, keys the update effect. */\nfunction configKey(props: Materials3DProps<RendererKind>): string {\n  const flat: Record<string, unknown> = {};\n  const keys = [\n    \"lamps\",\n    \"lampGain\",\n    \"background\",\n    \"transparentBackground\",\n    \"clearGlass\",\n    \"post\",\n    \"motion\",\n    \"scatter\",\n    \"orbit\",\n    \"quality\",\n    \"dprMax\",\n    \"paused\",\n  ] as const;\n  for (const k of keys) if (props[k] !== undefined) flat[k] = props[k];\n  return JSON.stringify({\n    preset: presetKey(props.preset),\n    flat,\n    config: props.config,\n  });\n}\n\n/** The state the handle reports before the shell exists: what the server-rendered div shows. */\nconst IDLE_STATE = \"poster\";\n\nfunction Materials3DInner(\n  props: Materials3DProps<RendererKind>,\n  ref: ForwardedRef<MaterialHandle<RendererKind>>,\n): ReactElement {\n  const { className, style, children } = props;\n  const containerRef = useRef<HTMLDivElement>(null);\n  const handleRef = useRef<MaterialHandle<RendererKind> | null>(null);\n  // Keep the latest callbacks in a ref so they never force a remount.\n  const cbRef = useRef<Pick<Materials3DProps<RendererKind>, \"onReady\" | \"onFallback\">>({});\n  cbRef.current.onReady = props.onReady;\n  cbRef.current.onFallback = props.onFallback;\n\n  // Serialising is not free (lamps, items, post), so it runs only when a flat prop changed.\n  const key = useMemo(\n    () => configKey(props),\n    [\n      props.preset,\n      props.lamps,\n      props.lampGain,\n      props.background,\n      props.transparentBackground,\n      props.clearGlass,\n      props.post,\n      props.motion,\n      props.scatter,\n      props.orbit,\n      props.quality,\n      props.dprMax,\n      props.paused,\n      props.config,\n    ],\n  );\n  // The key the live handle was last given, so the update effect can tell a real change from its\n  // own first run (and from StrictMode's replay), both of which the mount effect already covered.\n  const appliedKeyRef = useRef<string | null>(null);\n\n  // A stable object that delegates to whichever handle is live, so a ref taken before the shell\n  // mounted, or across a StrictMode remount, keeps working.\n  useImperativeHandle(\n    ref,\n    () => ({\n      get state() {\n        return handleRef.current?.state ?? IDLE_STATE;\n      },\n      get renderer() {\n        return handleRef.current?.renderer ?? null;\n      },\n      snapshot: (opts) => handleRef.current?.snapshot(opts) ?? Promise.resolve(null),\n      set: (config) => handleRef.current?.set(config),\n      play: () => handleRef.current?.play(),\n      pause: () => handleRef.current?.pause(),\n      destroy: () => handleRef.current?.destroy(),\n    }),\n    [],\n  );\n\n  // Mount once. StrictMode double-mount is safe: destroy() aborts a pending upgrade, and the\n  // pre-upgrade create/destroy is DOM-only (poster + IntersectionObserver).\n  useEffect(() => {\n    const container = containerRef.current;\n    if (!container) return;\n    let cancelled = false;\n    const options: MaterialOptions<RendererKind> = {\n      poster: props.poster,\n      posterFit: props.posterFit,\n      lazy: props.lazy,\n      webgl: props.webgl,\n      renderer: props.renderer,\n      respectReducedMotion: props.respectReducedMotion,\n      minSizeForWebGL: props.minSizeForWebGL,\n      onReady: (r) => cbRef.current.onReady?.(r),\n      onFallback: (reason) => cbRef.current.onFallback?.(reason),\n    };\n    const handle = createMaterials<RendererKind>(\n      container,\n      buildConfig(syncBase(props.preset), props),\n      options,\n    );\n    handleRef.current = handle;\n    appliedKeyRef.current = key;\n    // A string preset resolves asynchronously; stage the real config once it loads. This is the\n    // one set a mount makes: the update effect below sees the key it already applied and skips.\n    if (typeof props.preset === \"string\") {\n      void resolveBase(props.preset).then((base) => {\n        if (!cancelled && handleRef.current === handle) handle.set(buildConfig(base, props));\n      });\n    }\n    return () => {\n      cancelled = true;\n      handle.destroy();\n      handleRef.current = null;\n      appliedKeyRef.current = null;\n    };\n    // Mount-time only (options are captured once; config changes flow through the effect below).\n  }, []);\n\n  // Push config changes (flat props / config / preset) to the live handle.\n  useEffect(() => {\n    const handle = handleRef.current;\n    if (!handle || appliedKeyRef.current === key) return;\n    appliedKeyRef.current = key;\n    const apply = (base: SceneConfig): void => {\n      if (handleRef.current === handle) handle.set(buildConfig(base, props));\n    };\n    if (typeof props.preset === \"string\") void resolveBase(props.preset).then(apply);\n    else apply(syncBase(props.preset));\n    // Re-runs only when the serialized config (`key`) changes; `props` is read fresh inside.\n  }, [key]);\n\n  return (\n    <div ref={containerRef} className={className} style={style}>\n      {children}\n    </div>\n  );\n}\n\nconst Materials3DWithRef = forwardRef(Materials3DInner);\nMaterials3DWithRef.displayName = \"Materials3D\";\n\n/**\n * A drop-in, self-optimizing Materials3D scene. Renders a `<div>` (SSR-safe; pass an\n * `<img data-materials3d-poster>` child for a server-rendered poster) and, on the client, mounts the\n * shell: poster-first, lazy, WebGL/reduced-motion/save-data aware, with the engine code-split out.\n *\n * A `ref` receives the {@link MaterialHandle} (`state`, `renderer`, `snapshot()`, `set()`,\n * `play()`, `pause()`), on React 18 and 19 alike. `forwardRef` keeps the generic engine parameter\n * only through this cast, which is why the component is declared this way.\n */\nexport const Materials3D = Materials3DWithRef as unknown as <R extends RendererKind = \"webgl\">(\n  props: Materials3DProps<R> & { ref?: Ref<MaterialHandle<R>> },\n) => ReactElement;\n\nexport default Materials3D;\nexport type {\n  SceneConfig,\n  MaterialHandle,\n  FallbackReason,\n  SnapshotOptions,\n} from \"@materials3d/core\";\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@materials3d/react",
+  "version": "0.1.0",
+  "description": "Drop-in Materials3D scene for React: the <Materials3D> component",
+  "keywords": [
+    "background",
+    "component",
+    "glass",
+    "react",
+    "refraction",
+    "three",
+    "threejs",
+    "webgl"
+  ],
+  "homepage": "https://github.com/Amir-Abushanab/materials3d/tree/main/packages/react#readme",
+  "bugs": "https://github.com/Amir-Abushanab/materials3d/issues",
+  "license": "MIT",
+  "author": "Amir Abushanab (https://github.com/Amir-Abushanab)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Amir-Abushanab/materials3d.git",
+    "directory": "packages/react"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@materials3d/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0"
+  },
+  "peerDependencies": {
+    "@types/react": ">=18",
+    "@types/three": ">=0.180",
+    "react": ">=18",
+    "three": ">=0.180 <1"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "@types/three": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}