@molecule/app-three-viewer-react 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,199 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-04T00:41:23.223Z
+-->
+
+# @molecule/app-three-viewer-react
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+3D model viewer wrapping three.js.
+
+Exports `<ThreeViewer>` — a React component that renders GLTF/GLB,
+OBJ, or STL models with orbit controls, lighting presets
+(`studio`/`sunset`/`flat`), auto-fit camera, and full GPU resource
+cleanup on unmount — plus the `resolveFormat()` and
+`disposeObject3D()` helpers and the prop types.
+
+## Quick Start
+
+```tsx
+import { ThreeViewer } from '@molecule/app-three-viewer-react'
+
+function ModelPage() {
+  // Inline callbacks/arrays are safe — they do not tear down WebGL.
+  return (
+    <div style={{ height: 480 }}>
+      <ThreeViewer
+        src="/models/duck.glb"
+        lighting="studio"
+        autoRotate
+        onLoad={() => console.log('loaded')}
+      />
+    </div>
+  )
+}
+```
+
+## Type
+
+`feature`
+
+## Installation
+
+```bash
+npm install @molecule/app-three-viewer-react @molecule/app-react @molecule/app-ui @molecule/app-ui-react react three
+npm install -D @types/react @types/three
+```
+
+## API
+
+### Interfaces
+
+#### `ThreeViewerProps`
+
+Props for the {@link ThreeViewer} component.
+
+```typescript
+interface ThreeViewerProps {
+  /** URL or path to the 3D model file. */
+  src: string
+  /**
+   * Model format. If omitted, inferred from the `src` extension. Falls back
+   * to `'gltf'` for unknown extensions.
+   */
+  format?: ThreeViewerFormat
+  /** Lighting preset. Defaults to `'studio'`. */
+  lighting?: ThreeViewerLighting
+  /** Optional CSS background colour for the canvas (CSS string or hex). */
+  background?: string
+  /** Slowly rotate the camera around the model. Defaults to `false`. */
+  autoRotate?: boolean
+  /**
+   * Override the orbit camera target (world-space x/y/z). When omitted, the
+   * target is automatically set to the centre of the model's bounding box.
+   */
+  cameraTarget?: [number, number, number]
+  /** Fired when the model has loaded into the scene. */
+  onLoad?: () => void
+  /** Fired when loading fails. */
+  onError?: (error: Error) => void
+  /** Extra classes merged onto the outer wrapper. */
+  className?: string
+}
+```
+
+### Types
+
+#### `ThreeViewerFormat`
+
+Supported 3D model formats.
+
+```typescript
+type ThreeViewerFormat = 'gltf' | 'glb' | 'obj' | 'stl'
+```
+
+#### `ThreeViewerLighting`
+
+Lighting presets — drive the scene's light rig.
+
+```typescript
+type ThreeViewerLighting = 'studio' | 'sunset' | 'flat'
+```
+
+### Functions
+
+#### `disposeObject3D(root)`
+
+Walk an Object3D tree and dispose every geometry, material, and texture so
+three.js does not leak GPU resources when the viewer unmounts or swaps
+models.
+
+```typescript
+function disposeObject3D(root: Object3D<Object3DEventMap>): void
+```
+
+- `root` — The root node to dispose.
+
+#### `resolveFormat(src, explicit)`
+
+Resolve a model format from an explicit prop or the file extension on `src`.
+
+```typescript
+function resolveFormat(src: string, explicit?: ThreeViewerFormat): ThreeViewerFormat
+```
+
+- `src` — The model URL.
+- `explicit` — The explicit `format` prop, if provided.
+
+**Returns:** The resolved format.
+
+#### `ThreeViewer(props)`
+
+3D model viewer wrapping three.js.
+
+Supports GLTF/GLB, OBJ, and STL inputs, orbit controls, and a small set of
+lighting presets. The camera auto-fits to the model's bounding box on
+load. All three.js GPU resources (geometry, materials, textures, the
+renderer itself) are disposed on unmount or when the model source
+(`src`/`format`) or scene structure (`lighting`/`background`) changes.
+
+The heavy setup (renderer creation + model download) depends ONLY on those
+inputs; `onLoad`, `onError`, `cameraTarget`, and `autoRotate` are routed
+through refs, so passing them inline (fresh arrows / `[x,y,z]` literals) does
+NOT tear down the WebGL context or re-download the model on a parent
+re-render.
+
+```typescript
+function ThreeViewer(props: ThreeViewerProps): JSX.Element
+```
+
+- `props` — Component props.
+
+**Returns:** The rendered viewer.
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-react` ^1.0.0
+- `@molecule/app-ui` ^1.0.0
+- `@molecule/app-ui-react` ^1.0.0
+- `react` ^18.0.0 || ^19.0.0
+
+### Runtime Dependencies
+
+- `@molecule/app-react`
+- `@molecule/app-ui`
+- `@molecule/app-ui-react`
+- `react`
+- `three`
+
+- Ships a REAL pinned `three` dependency — a substantial bundle-size
+  add. Lazy-load the importing route/component (`React.lazy` / dynamic
+  import) so non-3D pages do not pay for it.
+- The heavy setup effect (renderer creation + model download) depends
+  ONLY on `src`/`format` (and `lighting`/`background`, which restructure
+  the scene). `onLoad`, `onError`, `cameraTarget`, and `autoRotate` are
+  routed through refs + light sync effects, so passing them inline (fresh
+  arrows / `[x,y,z]` literals) does NOT tear down the WebGL context or
+  re-download the model on a parent re-render. Changing `src`/`format`
+  reloads the model; changing `cameraTarget`'s value re-aims the camera
+  in place.
+- The wrapper is `width/height: 100%` with `min-height: 240px` — give
+  the PARENT an explicit height or the canvas collapses to 240px.
+- Requires WebGL in a real browser: do not render during SSR and do
+  not expect it to work under jsdom tests. Model URLs must be
+  same-origin or CORS-enabled.
+- `format` is inferred from the `src` extension (unknown extensions
+  fall back to `gltf`); pass it explicitly for extension-less URLs.
+- Must render inside the app's i18n provider and with a ClassMap bond
+  wired (loading/error overlays use `useTranslation()`); translations
+  ship in `@molecule/app-locales-feature-three-viewer`.

package/dist/ThreeViewer.d.ts

@@ -0,0 +1,69 @@
+import { type JSX } from 'react';
+import { type Object3D } from 'three';
+/** Supported 3D model formats. */
+export type ThreeViewerFormat = 'gltf' | 'glb' | 'obj' | 'stl';
+/** Lighting presets — drive the scene's light rig. */
+export type ThreeViewerLighting = 'studio' | 'sunset' | 'flat';
+/** Props for the {@link ThreeViewer} component. */
+export interface ThreeViewerProps {
+    /** URL or path to the 3D model file. */
+    src: string;
+    /**
+     * Model format. If omitted, inferred from the `src` extension. Falls back
+     * to `'gltf'` for unknown extensions.
+     */
+    format?: ThreeViewerFormat;
+    /** Lighting preset. Defaults to `'studio'`. */
+    lighting?: ThreeViewerLighting;
+    /** Optional CSS background colour for the canvas (CSS string or hex). */
+    background?: string;
+    /** Slowly rotate the camera around the model. Defaults to `false`. */
+    autoRotate?: boolean;
+    /**
+     * Override the orbit camera target (world-space x/y/z). When omitted, the
+     * target is automatically set to the centre of the model's bounding box.
+     */
+    cameraTarget?: [number, number, number];
+    /** Fired when the model has loaded into the scene. */
+    onLoad?: () => void;
+    /** Fired when loading fails. */
+    onError?: (error: Error) => void;
+    /** Extra classes merged onto the outer wrapper. */
+    className?: string;
+}
+/**
+ * Resolve a model format from an explicit prop or the file extension on `src`.
+ *
+ * @param src - The model URL.
+ * @param explicit - The explicit `format` prop, if provided.
+ * @returns The resolved format.
+ */
+export declare function resolveFormat(src: string, explicit?: ThreeViewerFormat): ThreeViewerFormat;
+/**
+ * Walk an Object3D tree and dispose every geometry, material, and texture so
+ * three.js does not leak GPU resources when the viewer unmounts or swaps
+ * models.
+ *
+ * @param root - The root node to dispose.
+ */
+export declare function disposeObject3D(root: Object3D): void;
+/**
+ * 3D model viewer wrapping three.js.
+ *
+ * Supports GLTF/GLB, OBJ, and STL inputs, orbit controls, and a small set of
+ * lighting presets. The camera auto-fits to the model's bounding box on
+ * load. All three.js GPU resources (geometry, materials, textures, the
+ * renderer itself) are disposed on unmount or when the model source
+ * (`src`/`format`) or scene structure (`lighting`/`background`) changes.
+ *
+ * The heavy setup (renderer creation + model download) depends ONLY on those
+ * inputs; `onLoad`, `onError`, `cameraTarget`, and `autoRotate` are routed
+ * through refs, so passing them inline (fresh arrows / `[x,y,z]` literals) does
+ * NOT tear down the WebGL context or re-download the model on a parent
+ * re-render.
+ *
+ * @param props - Component props.
+ * @returns The rendered viewer.
+ */
+export declare function ThreeViewer(props: ThreeViewerProps): JSX.Element;
+//# sourceMappingURL=ThreeViewer.d.ts.map

package/dist/ThreeViewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThreeViewer.d.ts","sourceRoot":"","sources":["../src/ThreeViewer.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAA+B,MAAM,OAAO,CAAA;AAC7D,OAAO,EASL,KAAK,QAAQ,EAKd,MAAM,OAAO,CAAA;AAUd,kCAAkC;AAClC,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;AAE9D,sDAAsD;AACtD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE9D,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAA;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,gCAAgC;IAChC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAChC,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,CAK1F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAapD;AA4JD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,GAAG,CAAC,OAAO,CAyNhE"}

package/dist/ThreeViewer.js

@@ -0,0 +1,349 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { AmbientLight, Box3, Color, DirectionalLight, HemisphereLight, Mesh, MeshStandardMaterial, PerspectiveCamera, Scene, Vector3, WebGLRenderer, } from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader.js';
+import { STLLoader } from 'three/examples/jsm/loaders/STLLoader.js';
+import { useTranslation } from '@molecule/app-react';
+import { getClassMap } from '@molecule/app-ui';
+import { Spinner } from '@molecule/app-ui-react';
+/**
+ * Resolve a model format from an explicit prop or the file extension on `src`.
+ *
+ * @param src - The model URL.
+ * @param explicit - The explicit `format` prop, if provided.
+ * @returns The resolved format.
+ */
+export function resolveFormat(src, explicit) {
+    if (explicit)
+        return explicit;
+    const m = src.toLowerCase().match(/\.(gltf|glb|obj|stl)(?:\?|#|$)/);
+    if (m)
+        return m[1];
+    return 'gltf';
+}
+/**
+ * Walk an Object3D tree and dispose every geometry, material, and texture so
+ * three.js does not leak GPU resources when the viewer unmounts or swaps
+ * models.
+ *
+ * @param root - The root node to dispose.
+ */
+export function disposeObject3D(root) {
+    root.traverse((child) => {
+        const mesh = child;
+        if (mesh.geometry) {
+            mesh.geometry.dispose();
+        }
+        const mat = mesh.material;
+        if (Array.isArray(mat)) {
+            for (const m of mat)
+                disposeMaterial(m);
+        }
+        else if (mat) {
+            disposeMaterial(mat);
+        }
+    });
+}
+/**
+ * Dispose a material and any of its texture maps.
+ *
+ * @param material - The material to dispose.
+ */
+function disposeMaterial(material) {
+    const m = material;
+    for (const key of Object.keys(m)) {
+        const value = m[key];
+        if (value &&
+            typeof value === 'object' &&
+            'isTexture' in value &&
+            value.isTexture) {
+            ;
+            value.dispose();
+        }
+    }
+    material.dispose();
+}
+/**
+ * Configure a scene with one of the lighting presets.
+ *
+ * @param scene - The scene to add lights to.
+ * @param preset - The preset to apply.
+ * @returns The lights added (for cleanup).
+ */
+function applyLighting(scene, preset) {
+    const lights = [];
+    if (preset === 'flat') {
+        const ambient = new AmbientLight(0xffffff, 1.0);
+        scene.add(ambient);
+        lights.push(ambient);
+        return lights;
+    }
+    if (preset === 'sunset') {
+        const hemi = new HemisphereLight(0xffb37a, 0x2a1850, 0.7);
+        scene.add(hemi);
+        lights.push(hemi);
+        const sun = new DirectionalLight(0xff8a4a, 1.4);
+        sun.position.set(5, 3, 2);
+        scene.add(sun);
+        lights.push(sun);
+        const fill = new DirectionalLight(0x6688cc, 0.4);
+        fill.position.set(-4, 2, -3);
+        scene.add(fill);
+        lights.push(fill);
+        return lights;
+    }
+    // studio (default) — three-point rig
+    const ambient = new AmbientLight(0xffffff, 0.4);
+    scene.add(ambient);
+    lights.push(ambient);
+    const key = new DirectionalLight(0xffffff, 1.1);
+    key.position.set(5, 5, 5);
+    scene.add(key);
+    lights.push(key);
+    const fill = new DirectionalLight(0xffffff, 0.6);
+    fill.position.set(-5, 2, 3);
+    scene.add(fill);
+    lights.push(fill);
+    const back = new DirectionalLight(0xffffff, 0.4);
+    back.position.set(0, 4, -5);
+    scene.add(back);
+    lights.push(back);
+    return lights;
+}
+/**
+ * Fit a perspective camera so the entire bounding box is in view, and aim
+ * orbit controls at the box centre (or an explicit target).
+ *
+ * @param object - The loaded model root.
+ * @param camera - The camera to position.
+ * @param controls - The orbit controls to retarget.
+ * @param target - Optional explicit camera target.
+ */
+function fitCameraToObject(object, camera, controls, target) {
+    const box = new Box3().setFromObject(object);
+    const size = new Vector3();
+    const center = new Vector3();
+    box.getSize(size);
+    box.getCenter(center);
+    const maxDim = Math.max(size.x, size.y, size.z) || 1;
+    const fitOffset = 1.6;
+    const fovRad = (camera.fov * Math.PI) / 180;
+    const distance = (maxDim / (2 * Math.tan(fovRad / 2))) * fitOffset;
+    const dir = new Vector3(1, 0.6, 1).normalize();
+    camera.position.copy(center).addScaledVector(dir, distance);
+    camera.near = Math.max(distance / 1000, 0.01);
+    camera.far = distance * 100;
+    camera.updateProjectionMatrix();
+    controls.target.copy(target ? new Vector3(...target) : center);
+    controls.update();
+}
+/**
+ * Load a model from `src` using the appropriate loader for `format`.
+ *
+ * @param src - The model URL.
+ * @param format - The resolved format.
+ * @returns A promise that resolves to the loaded scene/mesh root.
+ */
+function loadModel(src, format) {
+    return new Promise((resolve, reject) => {
+        if (format === 'gltf' || format === 'glb') {
+            const loader = new GLTFLoader();
+            loader.load(src, (gltf) => resolve(gltf.scene), undefined, (err) => reject(err instanceof Error ? err : new Error(String(err))));
+            return;
+        }
+        if (format === 'obj') {
+            const loader = new OBJLoader();
+            loader.load(src, (obj) => resolve(obj), undefined, (err) => reject(err instanceof Error ? err : new Error(String(err))));
+            return;
+        }
+        if (format === 'stl') {
+            const loader = new STLLoader();
+            loader.load(src, (geometry) => {
+                const mesh = new Mesh(geometry, new MeshStandardMaterial({ color: 0xb0b0b0, roughness: 0.6, metalness: 0.1 }));
+                resolve(mesh);
+            }, undefined, (err) => reject(err instanceof Error ? err : new Error(String(err))));
+            return;
+        }
+        reject(new Error(`Unsupported three-viewer format: ${String(format)}`));
+    });
+}
+/**
+ * 3D model viewer wrapping three.js.
+ *
+ * Supports GLTF/GLB, OBJ, and STL inputs, orbit controls, and a small set of
+ * lighting presets. The camera auto-fits to the model's bounding box on
+ * load. All three.js GPU resources (geometry, materials, textures, the
+ * renderer itself) are disposed on unmount or when the model source
+ * (`src`/`format`) or scene structure (`lighting`/`background`) changes.
+ *
+ * The heavy setup (renderer creation + model download) depends ONLY on those
+ * inputs; `onLoad`, `onError`, `cameraTarget`, and `autoRotate` are routed
+ * through refs, so passing them inline (fresh arrows / `[x,y,z]` literals) does
+ * NOT tear down the WebGL context or re-download the model on a parent
+ * re-render.
+ *
+ * @param props - Component props.
+ * @returns The rendered viewer.
+ */
+export function ThreeViewer(props) {
+    const { src, format, lighting = 'studio', background, autoRotate = false, cameraTarget, onLoad, onError, className, } = props;
+    const cm = getClassMap();
+    const { t } = useTranslation();
+    const containerRef = useRef(null);
+    const [loading, setLoading] = useState(true);
+    const [errorMsg, setErrorMsg] = useState(null);
+    // Latest callback + option props kept in refs so the heavy setup effect below
+    // depends only on what genuinely forces a rebuild (the model source + scene
+    // structure) and never on inline arrows / fresh `[x,y,z]` literals — those get
+    // a new identity on every parent render. Routing them through refs stops an
+    // unrelated parent re-render from tearing down the WebGL context and
+    // re-downloading the model.
+    const onLoadRef = useRef(onLoad);
+    const onErrorRef = useRef(onError);
+    const cameraTargetRef = useRef(cameraTarget);
+    const autoRotateRef = useRef(autoRotate);
+    // Live handles to the running three.js objects so the cheap prop-sync effects
+    // can update them in place — no teardown.
+    const cameraRef = useRef(null);
+    const controlsRef = useRef(null);
+    const modelRef = useRef(null);
+    // Cheap sync: keep the callback refs current. Never touches the renderer, so a
+    // parent re-render with new inline `onLoad`/`onError` does not rebuild WebGL.
+    useEffect(() => {
+        onLoadRef.current = onLoad;
+        onErrorRef.current = onError;
+    }, [onLoad, onError]);
+    // Cheap sync: `autoRotate` toggles a live control flag in place.
+    useEffect(() => {
+        autoRotateRef.current = autoRotate;
+        if (controlsRef.current) {
+            controlsRef.current.autoRotate = autoRotate;
+        }
+    }, [autoRotate]);
+    // Cheap sync: keep the `cameraTarget` ref current on every identity change so
+    // the next model load / re-fit reads the latest value.
+    useEffect(() => {
+        cameraTargetRef.current = cameraTarget;
+    }, [cameraTarget]);
+    // Cheap sync: re-aim the camera when the target VALUE changes (identity churn
+    // from inline literals is ignored via the joined-value key) — no model reload.
+    const cameraTargetKey = cameraTarget ? cameraTarget.join(',') : '';
+    useEffect(() => {
+        const camera = cameraRef.current;
+        const controls = controlsRef.current;
+        const model = modelRef.current;
+        if (camera && controls && model) {
+            fitCameraToObject(model, camera, controls, cameraTargetRef.current);
+        }
+    }, [cameraTargetKey]);
+    // Heavy setup + teardown: creates the renderer/scene and downloads the model.
+    // Re-runs ONLY when the model source or scene structure changes.
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        let disposed = false;
+        const resolved = resolveFormat(src, format);
+        const width = container.clientWidth || 1;
+        const height = container.clientHeight || 1;
+        const scene = new Scene();
+        if (background) {
+            scene.background = new Color(background);
+        }
+        const camera = new PerspectiveCamera(45, width / height, 0.1, 1000);
+        camera.position.set(0, 0, 5);
+        const renderer = new WebGLRenderer({ antialias: true, alpha: !background });
+        renderer.setPixelRatio(typeof window !== 'undefined' ? window.devicePixelRatio : 1);
+        renderer.setSize(width, height);
+        container.appendChild(renderer.domElement);
+        const controls = new OrbitControls(camera, renderer.domElement);
+        controls.enableDamping = true;
+        controls.autoRotate = autoRotateRef.current;
+        cameraRef.current = camera;
+        controlsRef.current = controls;
+        const lights = applyLighting(scene, lighting);
+        let model = null;
+        let frameHandle = 0;
+        /**
+         * Per-frame animation loop.
+         */
+        function animate() {
+            if (disposed)
+                return;
+            controls.update();
+            renderer.render(scene, camera);
+            frameHandle = requestAnimationFrame(animate);
+        }
+        /**
+         * Handle window resize by adjusting the renderer + camera aspect.
+         */
+        function handleResize() {
+            if (!container || disposed)
+                return;
+            const w = container.clientWidth || 1;
+            const h = container.clientHeight || 1;
+            camera.aspect = w / h;
+            camera.updateProjectionMatrix();
+            renderer.setSize(w, h);
+        }
+        if (typeof window !== 'undefined') {
+            window.addEventListener('resize', handleResize);
+        }
+        setLoading(true);
+        setErrorMsg(null);
+        loadModel(src, resolved)
+            .then((obj) => {
+            if (disposed) {
+                disposeObject3D(obj);
+                return;
+            }
+            model = obj;
+            modelRef.current = obj;
+            scene.add(obj);
+            fitCameraToObject(obj, camera, controls, cameraTargetRef.current);
+            animate();
+            setLoading(false);
+            onLoadRef.current?.();
+        })
+            .catch((err) => {
+            if (disposed)
+                return;
+            const e = err instanceof Error ? err : new Error(String(err));
+            setErrorMsg(e.message);
+            setLoading(false);
+            onErrorRef.current?.(e);
+        });
+        return () => {
+            disposed = true;
+            if (typeof window !== 'undefined') {
+                window.removeEventListener('resize', handleResize);
+            }
+            if (frameHandle)
+                cancelAnimationFrame(frameHandle);
+            controls.dispose();
+            for (const light of lights)
+                scene.remove(light);
+            if (model) {
+                scene.remove(model);
+                disposeObject3D(model);
+            }
+            renderer.dispose();
+            if (renderer.domElement.parentNode === container) {
+                container.removeChild(renderer.domElement);
+            }
+            cameraRef.current = null;
+            controlsRef.current = null;
+            modelRef.current = null;
+        };
+    }, [src, format, lighting, background]);
+    const overlayStyle = {
+        position: 'absolute',
+        inset: 0,
+        display: 'grid',
+        placeItems: 'center',
+        pointerEvents: 'none',
+    };
+    return (_jsxs("div", { "data-mol-id": "three-viewer", className: cm.cn(className), style: { position: 'relative', width: '100%', height: '100%', minHeight: 240 }, children: [_jsx("div", { ref: containerRef, "data-mol-id": "three-viewer-canvas", "aria-label": t('threeViewer.aria.canvas', {}, { defaultValue: '3D model viewer' }), role: "img", style: { width: '100%', height: '100%' } }), loading && !errorMsg && (_jsx("div", { "data-mol-id": "three-viewer-loading", className: cm.cn(cm.flex({ align: 'center', justify: 'center' })), style: overlayStyle, children: _jsx(Spinner, { label: t('threeViewer.loading', {}, { defaultValue: 'Loading 3D model…' }) }) })), errorMsg && (_jsx("div", { "data-mol-id": "three-viewer-error", role: "alert", className: cm.cn(cm.flex({ align: 'center', justify: 'center' }), cm.sp('p', 3)), style: overlayStyle, children: _jsx("span", { className: cm.textSize('sm'), children: t('threeViewer.error', {}, { defaultValue: 'Failed to load 3D model.' }) }) }))] }));
+}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 3D model viewer wrapping three.js.
+ *
+ * Exports `<ThreeViewer>` — a React component that renders GLTF/GLB,
+ * OBJ, or STL models with orbit controls, lighting presets
+ * (`studio`/`sunset`/`flat`), auto-fit camera, and full GPU resource
+ * cleanup on unmount — plus the `resolveFormat()` and
+ * `disposeObject3D()` helpers and the prop types.
+ *
+ * @example
+ * ```tsx
+ * import { ThreeViewer } from '@molecule/app-three-viewer-react'
+ *
+ * function ModelPage() {
+ *   // Inline callbacks/arrays are safe — they do not tear down WebGL.
+ *   return (
+ *     <div style={{ height: 480 }}>
+ *       <ThreeViewer
+ *         src="/models/duck.glb"
+ *         lighting="studio"
+ *         autoRotate
+ *         onLoad={() => console.log('loaded')}
+ *       />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @remarks
+ * - Ships a REAL pinned `three` dependency — a substantial bundle-size
+ *   add. Lazy-load the importing route/component (`React.lazy` / dynamic
+ *   import) so non-3D pages do not pay for it.
+ * - The heavy setup effect (renderer creation + model download) depends
+ *   ONLY on `src`/`format` (and `lighting`/`background`, which restructure
+ *   the scene). `onLoad`, `onError`, `cameraTarget`, and `autoRotate` are
+ *   routed through refs + light sync effects, so passing them inline (fresh
+ *   arrows / `[x,y,z]` literals) does NOT tear down the WebGL context or
+ *   re-download the model on a parent re-render. Changing `src`/`format`
+ *   reloads the model; changing `cameraTarget`'s value re-aims the camera
+ *   in place.
+ * - The wrapper is `width/height: 100%` with `min-height: 240px` — give
+ *   the PARENT an explicit height or the canvas collapses to 240px.
+ * - Requires WebGL in a real browser: do not render during SSR and do
+ *   not expect it to work under jsdom tests. Model URLs must be
+ *   same-origin or CORS-enabled.
+ * - `format` is inferred from the `src` extension (unknown extensions
+ *   fall back to `gltf`); pass it explicitly for extension-less URLs.
+ * - Must render inside the app's i18n provider and with a ClassMap bond
+ *   wired (loading/error overlays use `useTranslation()`); translations
+ *   ship in `@molecule/app-locales-feature-three-viewer`.
+ *
+ * @module
+ */
+export * from './ThreeViewer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,cAAc,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,54 @@
+/**
+ * 3D model viewer wrapping three.js.
+ *
+ * Exports `<ThreeViewer>` — a React component that renders GLTF/GLB,
+ * OBJ, or STL models with orbit controls, lighting presets
+ * (`studio`/`sunset`/`flat`), auto-fit camera, and full GPU resource
+ * cleanup on unmount — plus the `resolveFormat()` and
+ * `disposeObject3D()` helpers and the prop types.
+ *
+ * @example
+ * ```tsx
+ * import { ThreeViewer } from '@molecule/app-three-viewer-react'
+ *
+ * function ModelPage() {
+ *   // Inline callbacks/arrays are safe — they do not tear down WebGL.
+ *   return (
+ *     <div style={{ height: 480 }}>
+ *       <ThreeViewer
+ *         src="/models/duck.glb"
+ *         lighting="studio"
+ *         autoRotate
+ *         onLoad={() => console.log('loaded')}
+ *       />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @remarks
+ * - Ships a REAL pinned `three` dependency — a substantial bundle-size
+ *   add. Lazy-load the importing route/component (`React.lazy` / dynamic
+ *   import) so non-3D pages do not pay for it.
+ * - The heavy setup effect (renderer creation + model download) depends
+ *   ONLY on `src`/`format` (and `lighting`/`background`, which restructure
+ *   the scene). `onLoad`, `onError`, `cameraTarget`, and `autoRotate` are
+ *   routed through refs + light sync effects, so passing them inline (fresh
+ *   arrows / `[x,y,z]` literals) does NOT tear down the WebGL context or
+ *   re-download the model on a parent re-render. Changing `src`/`format`
+ *   reloads the model; changing `cameraTarget`'s value re-aims the camera
+ *   in place.
+ * - The wrapper is `width/height: 100%` with `min-height: 240px` — give
+ *   the PARENT an explicit height or the canvas collapses to 240px.
+ * - Requires WebGL in a real browser: do not render during SSR and do
+ *   not expect it to work under jsdom tests. Model URLs must be
+ *   same-origin or CORS-enabled.
+ * - `format` is inferred from the `src` extension (unknown extensions
+ *   fall back to `gltf`); pass it explicitly for extension-less URLs.
+ * - Must render inside the app's i18n provider and with a ClassMap bond
+ *   wired (loading/error overlays use `useTranslation()`); translations
+ *   ship in `@molecule/app-locales-feature-three-viewer`.
+ *
+ * @module
+ */
+export * from './ThreeViewer.js';

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@molecule/app-three-viewer-react",
+  "version": "1.0.0",
+  "description": "WebGL 3D model viewer wrapping three.js — supports GLTF/GLB, OBJ, STL with orbit controls + lighting presets",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "molecule",
+    "three",
+    "viewer",
+    "3d",
+    "gltf",
+    "obj",
+    "stl",
+    "react"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "three": "0.185.1"
+  },
+  "peerDependencies": {
+    "@molecule/app-react": "^1.0.0",
+    "@molecule/app-ui": "^1.0.0",
+    "@molecule/app-ui-react": "^1.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@molecule/app-i18n": "1.0.0",
+    "@molecule/app-react": "1.0.0",
+    "@molecule/app-ui": "1.0.0",
+    "@molecule/app-ui-react": "1.0.0",
+    "@testing-library/react": "16.3.2",
+    "@types/node": "26.1.2",
+    "@types/react": "19.2.17",
+    "@types/three": "0.185.1",
+    "jsdom": "30.0.1",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  }
+}