@avatar-platform/avatar-render 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# Avatar Render
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@avatar-platform/avatar-render` 是独立的浏览器端 TypeScript / ESM npm 包，用于完整 GLB 模型预览和 HDR / EXR 摄影棚环境照明。不依赖 Vue、React、仓库内部包、后端或业务 API。导入模块不会创建 WebGL；在浏览器挂载后创建实例。
+
+## 构建与安装
+
+在仓库根目录运行：
+
+```sh
+pnpm --filter @avatar-platform/avatar-render build
+pnpm --filter @avatar-platform/avatar-render test
+pnpm --filter @avatar-platform/avatar-render pack --pack-destination ./tmp/avatar-render
+```
+
+生成的 `.tgz` 可在其他项目通过 `npm install /path/to/avatar-platform-avatar-render-0.1.0.tgz three@^0.180.0` 安装。本包未发布到 npm registry；正式发布前由维护者确认包名、访问级别和许可证。`three` 为 peer dependency，不重复打包；仅提供 ESM，TypeScript 声明随包分发。包的 tsconfig 独立于仓库，可复制整个目录单独开发。
+
+## 最小接入
+
+容器必须有实际宽高，例如 `width: 100%; height: 600px`。
+
+```ts
+import { AvatarRenderer } from '@avatar-platform/avatar-render';
+
+const viewer = new AvatarRenderer({
+  container: document.querySelector<HTMLElement>('#viewer')!,
+  config: { intensity: 1, exposure: 1, rotation: 35 }
+});
+
+// 模型和环境独立加载；任何失败均通过 Promise reject 返回。
+const results = await Promise.allSettled([
+  viewer.loadModel('/assets/avatar.glb'),
+  viewer.loadEnvironment('/assets/studio.hdr')
+]);
+for (const result of results) {
+  if (result.status === 'rejected') console.error(result.reason);
+}
+
+// 将你自己的滑块、颜色选择器、开关绑定到这些参数。
+viewer.setConfig({ exposure: 0.8, rotation: 60, autoRotate: true });
+const config = viewer.getConfig(); // 独立副本，可自行保存成 JSON
+viewer.setConfig(config);         // 恢复已保存的配置
+viewer.fit();                    // 正面取景，显示完整模型
+viewer.reset();                  // 恢复库默认配置并重新取景
+
+// 页面/组件卸载时调用。
+viewer.dispose();
+```
+
+Vue 在 `onMounted` 创建，`onBeforeUnmount` 销毁；React 在 effect 创建并在 cleanup 销毁。现有 Web `/render-lab` 是完整 Vue 接入示例，面板属于宿主 UI，包提供全部控制接口。
+
+## 模型和环境输入
+
+```ts
+await viewer.loadModel(fileInput.files![0]); // 本地 .glb File
+await viewer.loadEnvironment(hdrInput.files![0]); // 本地 .hdr / .exr File
+await viewer.loadEnvironment('/signed-download?id=123', 'exr');
+```
+
+- URL 可以是相对路径、同源地址、CORS 允许的远端地址或宿主创建的 blob URL。URL 不要求以 `.glb` 结尾；环境格式按去掉 query/hash 的后缀推断，无后缀时显式传 `hdr` / `exr`。
+- 本地 File 自动创建并回收 object URL，不上传服务器。GLB 应为完整、自包含文件；不支持通过单个 File 寻找外部贴图或 `.gltf` 依赖目录。
+- 模型只在显示层居中、统一尺寸，保留模型原始节点变换、骨骼及 PBR 材质。不拼装/导出模型，不播放动画。Y 轴向上、默认面向 +Z，其他朝向可用 `modelRotation` 调整。
+- 同一类资源连续加载采用最后一次调用优先；旧请求完成后释放资源并抛 `AbortError`，不覆盖新请求。替换失败保留先前有效资源。`dispose()` 后的迟到加载同样释放并抛 `AbortError`。底层请求不保证中途停止下载。
+- Draco / KTX2 压缩模型可通过构造参数 `configureModelLoader(loader, renderer)` 配置 Three.js 解码器；解码器地址、加载及解码器自身销毁由宿主负责。默认 GLTFLoader 不配置远端解码设施。
+- 包内置原摄影棚和三套柔光 HDR（合计约 4.34 MB）；模型、其他 HDR / EXR、凭据、业务地址不打包。PNG 全景预览图不作为 HDR 环境输入。
+
+## 内置 HDR 场景
+
+```ts
+import { ENVIRONMENT_PRESETS } from '@avatar-platform/avatar-render';
+
+await viewer.loadEnvironmentPreset(); // studio：原默认摄影棚
+await viewer.loadEnvironmentPreset('overcast'); // 阴天户外 · 柔和天空
+await viewer.loadEnvironmentPreset('window'); // 室内大窗 · 柔光
+await viewer.loadEnvironmentPreset('soft-studio'); // 均匀展示棚 · 低反差
+// ENVIRONMENT_PRESETS 的只读 id / name / url 可用于创建宿主下拉菜单。
+```
+
+构造器仍不自动加载环境；需要默认摄影棚时显式调用 `loadEnvironmentPreset()`。切换只替换环境照明，保留曝光、强度、旋转及模型材质，加载失败保留当前环境。`reset()` 只重置渲染配置和视角，不切换 HDR。`/render-lab` 默认使用原摄影棚，提供四个场景及自定义文件入口。
+
+HDR 随 npm 包的 `assets/` 分发，通过相对模块的 `new URL(..., import.meta.url)` 解析；Vite 等支持此写法的构建器会复制资源。直接以原生 ESM 部署时，保留 `dist/` 与 `assets/` 的相对目录；其他构建器需配置 HDR 静态资源处理，或部署 assets 后使用 `loadEnvironment(url, 'hdr')`。按选择加载一套，不会预加载全部 HDR。
+
+新增三套为建模师提供的原创程序化 2048×1024 Radiance RGBE、线性光环境，分别为微冷天空、暖中性侧窗和中性低反差棚光；名称描述照明风格，不是真实场景照片。可保持强度 1 对比，过亮时尝试 0.7；不覆盖原模型 roughness / metalness。包仅包含 HDR，不包含材质球测试或全景预览 PNG。
+
+## 配置
+
+`config` 和 `setConfig()` 都接受 `Partial<RenderConfig>`。角度单位为度；无效值抛错，整次更新不生效，不静默截断。
+
+| 字段 | 默认值 | 支持范围 / 含义 |
+| --- | --- | --- |
+| intensity | 1 | 0–3，环境照明与全景背景强度 |
+| exposure | 1 | 0.1–3，色彩映射曝光 |
+| rotation | 35 | -180–180，环境照明和全景同步绕 Y 轴旋转 |
+| modelRotation | 0 | -180–180，模型绕 Y 轴旋转 |
+| background | #24262b | #RRGGBB 背景颜色 |
+| panorama | false | 显示 HDR/EXR 全景；无环境时仍显示背景色 |
+| autoRotate | false | 相机自动环绕模型 |
+| wireframe | false | 线框检查 |
+| toneMapping | aces | aces / neutral |
+
+额外构造参数 `pixelRatioCap` 默认 2，必须为正有限数。HDR / EXR 经 PMREM 预过滤绑定 scene.environment，sRGB 输出，默认不增加补光灯、SSAO 或地面阴影。`getConfig()` 返回当前完整配置；`DEFAULT_RENDER_CONFIG` 是只读默认值。
+
+`resize()` 自动跟踪容器尺寸，也可手动调用；不重置用户旋转/缩放，需要重新取景时调用 `fit()`。页面隐藏或 WebGL context 丢失时暂停渲染循环，恢复后继续。
+
+## 验证边界
+
+单元测试使用真实 Three.js 几何体和材质、模拟 WebGL/加载器，覆盖配置校验、替换与失败保留、迟到结果隔离、PMREM 生命周期、本地 URL 回收及卸载。它们不等同于 GPU 视觉验收；模型的具体材质效果、压缩解码、设备兼容与上下文恢复后的画面仍需实际浏览器验证。

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export interface RenderConfig {
+    /** Environment lighting strength, 0–3. */
+    intensity: number;
+    /** Tone mapping exposure, 0.1–3. */
+    exposure: number;
+    /** Environment yaw in degrees, -180–180. */
+    rotation: number;
+    /** Model yaw in degrees, -180–180. */
+    modelRotation: number;
+    /** Opaque background color in #RRGGBB format. */
+    background: string;
+    panorama: boolean;
+    autoRotate: boolean;
+    wireframe: boolean;
+    toneMapping: 'aces' | 'neutral';
+}
+export declare const DEFAULT_RENDER_CONFIG: Readonly<RenderConfig>;
+/** Reject invalid patches atomically, without changing the current configuration. */
+export declare function resolveConfig(patch: Partial<RenderConfig>, current?: Readonly<RenderConfig>): RenderConfig;

package/dist/config.js

@@ -0,0 +1,30 @@
+export const DEFAULT_RENDER_CONFIG = Object.freeze({
+    intensity: 1, exposure: 1, rotation: 35, modelRotation: 0,
+    background: '#24262b', panorama: false, autoRotate: false,
+    wireframe: false, toneMapping: 'aces'
+});
+/** Reject invalid patches atomically, without changing the current configuration. */
+export function resolveConfig(patch, current = DEFAULT_RENDER_CONFIG) {
+    for (const key of Object.keys(patch)) {
+        if (!Object.hasOwn(DEFAULT_RENDER_CONFIG, key))
+            throw new TypeError(`Unknown render option: ${key}`);
+    }
+    const result = { ...current, ...patch };
+    for (const [key, min, max] of [
+        ['intensity', 0, 3], ['exposure', 0.1, 3], ['rotation', -180, 180], ['modelRotation', -180, 180]
+    ]) {
+        const value = result[key];
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+            throw new RangeError(`${key} must be a finite number between ${min} and ${max}`);
+        }
+    }
+    for (const key of ['panorama', 'autoRotate', 'wireframe']) {
+        if (typeof result[key] !== 'boolean')
+            throw new TypeError(`${key} must be a boolean`);
+    }
+    if (typeof result.background !== 'string' || !/^#[\da-f]{6}$/i.test(result.background))
+        throw new TypeError('background must be #RRGGBB');
+    if (!['aces', 'neutral'].includes(result.toneMapping))
+        throw new TypeError('toneMapping must be aces or neutral');
+    return result;
+}

package/dist/environments.d.ts

@@ -0,0 +1,20 @@
+/** Bundled HDR assets, resolved relative to this module by browser bundlers. */
+export declare const ENVIRONMENT_PRESETS: readonly [Readonly<{
+    id: "studio";
+    name: "默认摄影棚";
+    url: string;
+}>, Readonly<{
+    id: "overcast";
+    name: "阴天户外 · 柔和天空";
+    url: string;
+}>, Readonly<{
+    id: "window";
+    name: "室内大窗 · 柔光";
+    url: string;
+}>, Readonly<{
+    id: "soft-studio";
+    name: "均匀展示棚 · 低反差";
+    url: string;
+}>];
+export type EnvironmentPresetId = typeof ENVIRONMENT_PRESETS[number]['id'];
+export declare const DEFAULT_ENVIRONMENT_PRESET: EnvironmentPresetId;

package/dist/environments.js

@@ -0,0 +1,8 @@
+/** Bundled HDR assets, resolved relative to this module by browser bundlers. */
+export const ENVIRONMENT_PRESETS = Object.freeze([
+    Object.freeze({ id: 'studio', name: '默认摄影棚', url: new URL('../assets/studio.hdr', import.meta.url).href }),
+    Object.freeze({ id: 'overcast', name: '阴天户外 · 柔和天空', url: new URL('../assets/overcast.hdr', import.meta.url).href }),
+    Object.freeze({ id: 'window', name: '室内大窗 · 柔光', url: new URL('../assets/window.hdr', import.meta.url).href }),
+    Object.freeze({ id: 'soft-studio', name: '均匀展示棚 · 低反差', url: new URL('../assets/soft-studio.hdr', import.meta.url).href })
+]);
+export const DEFAULT_ENVIRONMENT_PRESET = 'studio';

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { type RenderConfig } from './config.js';
+import { type EnvironmentPresetId } from './environments.js';
+export { DEFAULT_ENVIRONMENT_PRESET, ENVIRONMENT_PRESETS, type EnvironmentPresetId } from './environments.js';
+export { DEFAULT_RENDER_CONFIG, type RenderConfig } from './config.js';
+export type AssetSource = string | File;
+export type EnvironmentFormat = 'hdr' | 'exr';
+export interface AvatarRendererOptions {
+    /** Must have a non-zero width and height. Only this container is observed. */
+    container: HTMLElement;
+    config?: Partial<RenderConfig>;
+    /** Cap device pixel ratio; defaults to 2. */
+    pixelRatioCap?: number;
+    /** Configure optional Draco/KTX2 decoders on the SDK-owned loader. */
+    configureModelLoader?: (loader: GLTFLoader, renderer: THREE.WebGLRenderer) => void;
+}
+/** Browser-only renderer; importing this module does not create a canvas. */
+export declare class AvatarRenderer {
+    private readonly container;
+    private readonly scene;
+    private readonly camera;
+    private readonly renderer;
+    private readonly controls;
+    private readonly observer;
+    private readonly loader;
+    private config;
+    private model?;
+    private environment?;
+    private environmentTarget?;
+    private disposed;
+    private contextLost;
+    private frame;
+    private lastTime;
+    private modelRequest;
+    private environmentRequest;
+    constructor(options: AvatarRendererOptions);
+    getConfig(): RenderConfig;
+    setConfig(patch: Partial<RenderConfig>): void;
+    /** Restore library defaults and the front-facing camera. */
+    reset(): void;
+    /** Latest request wins. Failed replacements preserve the last valid model. */
+    loadModel(source: AssetSource): Promise<void>;
+    /** Load bundled lighting without changing render settings. Defaults to the original studio. */
+    loadEnvironmentPreset(id?: EnvironmentPresetId): Promise<void>;
+    /** Format is inferred from file name or URL path; pass it explicitly for opaque URLs. */
+    loadEnvironment(source: AssetSource, format?: EnvironmentFormat): Promise<void>;
+    /** Fit the entire model and return the camera to the front. */
+    fit(): void;
+    /** Resize without changing the user's orbit/zoom. Called automatically by ResizeObserver. */
+    resize(): void;
+    /** Idempotent. In-flight results will be discarded and their resources released. */
+    dispose(): void;
+    private assertActive;
+    private assertCurrent;
+    private applyConfig;
+    private onContextLost;
+    private onContextRestored;
+    private syncLoop;
+    private render;
+}

package/dist/index.js

@@ -0,0 +1,324 @@
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
+import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import { DEFAULT_RENDER_CONFIG, resolveConfig } from './config.js';
+import { DEFAULT_ENVIRONMENT_PRESET, ENVIRONMENT_PRESETS } from './environments.js';
+export { DEFAULT_ENVIRONMENT_PRESET, ENVIRONMENT_PRESETS } from './environments.js';
+export { DEFAULT_RENDER_CONFIG } from './config.js';
+function disposeModel(root) {
+    const geometries = new Set();
+    const materials = new Set();
+    const textures = new Set();
+    const skeletons = new Set();
+    root.traverse((node) => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        if (mesh.geometry)
+            geometries.add(mesh.geometry);
+        if (mesh.isSkinnedMesh)
+            skeletons.add(mesh.skeleton);
+        for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
+            materials.add(material);
+            for (const value of Object.values(material))
+                if (value instanceof THREE.Texture)
+                    textures.add(value);
+        }
+    });
+    textures.forEach((texture) => texture.dispose());
+    materials.forEach((material) => material.dispose());
+    geometries.forEach((geometry) => geometry.dispose());
+    skeletons.forEach((skeleton) => skeleton.dispose());
+}
+function assetUrl(source) {
+    if (typeof source === 'string') {
+        if (!source.trim())
+            throw new TypeError('Asset URL cannot be empty');
+        return { url: source, release: () => { } };
+    }
+    const url = URL.createObjectURL(source);
+    return { url, release: () => URL.revokeObjectURL(url) };
+}
+/** Browser-only renderer; importing this module does not create a canvas. */
+export class AvatarRenderer {
+    container;
+    scene = new THREE.Scene();
+    camera = new THREE.PerspectiveCamera(35, 1, 0.01, 1000);
+    renderer;
+    controls;
+    observer;
+    loader = new GLTFLoader();
+    config;
+    model;
+    environment;
+    environmentTarget;
+    disposed = false;
+    contextLost = false;
+    frame;
+    lastTime = 0;
+    modelRequest = 0;
+    environmentRequest = 0;
+    constructor(options) {
+        this.config = resolveConfig(options.config ?? {});
+        const ratio = options.pixelRatioCap ?? 2;
+        if (!Number.isFinite(ratio) || ratio <= 0)
+            throw new RangeError('pixelRatioCap must be positive');
+        this.container = options.container;
+        this.renderer = new THREE.WebGLRenderer({ antialias: true });
+        try {
+            options.configureModelLoader?.(this.loader, this.renderer);
+        }
+        catch (error) {
+            this.renderer.dispose();
+            this.renderer.forceContextLoss();
+            throw error;
+        }
+        this.renderer.outputColorSpace = THREE.SRGBColorSpace;
+        this.renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, ratio));
+        this.renderer.domElement.style.cssText = 'display:block;width:100%;height:100%';
+        this.renderer.domElement.setAttribute('aria-label', '3D model preview');
+        this.container.appendChild(this.renderer.domElement);
+        this.controls = new OrbitControls(this.camera, this.renderer.domElement);
+        this.controls.enableDamping = true;
+        this.observer = new ResizeObserver(() => this.resize());
+        this.observer.observe(this.container);
+        this.renderer.domElement.addEventListener('webglcontextlost', this.onContextLost);
+        this.renderer.domElement.addEventListener('webglcontextrestored', this.onContextRestored);
+        document.addEventListener('visibilitychange', this.syncLoop);
+        this.applyConfig();
+        this.resize();
+        this.syncLoop();
+    }
+    getConfig() { return { ...this.config }; }
+    setConfig(patch) {
+        this.assertActive();
+        this.config = resolveConfig(patch, this.config);
+        this.applyConfig();
+    }
+    /** Restore library defaults and the front-facing camera. */
+    reset() {
+        this.setConfig({ ...DEFAULT_RENDER_CONFIG });
+        this.fit();
+    }
+    /** Latest request wins. Failed replacements preserve the last valid model. */
+    async loadModel(source) {
+        this.assertActive();
+        const request = ++this.modelRequest;
+        if (typeof source !== 'string' && !/\.glb$/i.test(source.name))
+            throw new TypeError('Select a .glb file');
+        const asset = assetUrl(source);
+        let loaded;
+        try {
+            loaded = (await this.loader.loadAsync(asset.url)).scene;
+            this.assertCurrent(request, 'model');
+            const bounds = new THREE.Box3().setFromObject(loaded);
+            const size = bounds.getSize(new THREE.Vector3());
+            const extent = Math.max(size.x, size.y, size.z);
+            if (!Number.isFinite(extent) || extent <= 0)
+                throw new Error('Model has no renderable bounds');
+            // Center and normalize through wrappers, keeping authored root transforms intact.
+            const centered = new THREE.Group();
+            centered.position.copy(bounds.getCenter(new THREE.Vector3())).negate();
+            centered.add(loaded);
+            const wrapper = new THREE.Group();
+            wrapper.scale.setScalar(2 / extent);
+            wrapper.add(centered);
+            const old = this.model;
+            this.model = wrapper;
+            this.scene.add(wrapper);
+            if (old) {
+                this.scene.remove(old);
+                disposeModel(old);
+            }
+            loaded = undefined;
+            this.applyConfig();
+            this.fit();
+        }
+        catch (error) {
+            if (loaded)
+                disposeModel(loaded);
+            this.assertCurrent(request, 'model');
+            throw error;
+        }
+        finally {
+            asset.release();
+        }
+    }
+    /** Load bundled lighting without changing render settings. Defaults to the original studio. */
+    async loadEnvironmentPreset(id = DEFAULT_ENVIRONMENT_PRESET) {
+        this.assertActive();
+        const preset = ENVIRONMENT_PRESETS.find((entry) => entry.id === id);
+        if (!preset)
+            throw new TypeError(`Unknown environment preset: ${id}`);
+        await this.loadEnvironment(preset.url, 'hdr');
+    }
+    /** Format is inferred from file name or URL path; pass it explicitly for opaque URLs. */
+    async loadEnvironment(source, format) {
+        this.assertActive();
+        const request = ++this.environmentRequest;
+        const name = typeof source === 'string' ? source.split(/[?#]/)[0] : source.name;
+        const selected = format ?? (/\.exr$/i.test(name) ? 'exr' : /\.hdr$/i.test(name) ? 'hdr' : undefined);
+        if (selected !== 'hdr' && selected !== 'exr')
+            throw new TypeError('Environment format must be hdr or exr');
+        const asset = assetUrl(source);
+        let texture;
+        let target;
+        try {
+            texture = await (selected === 'exr' ? new EXRLoader() : new RGBELoader()).loadAsync(asset.url);
+            this.assertCurrent(request, 'environment');
+            texture.mapping = THREE.EquirectangularReflectionMapping;
+            const pmrem = new THREE.PMREMGenerator(this.renderer);
+            try {
+                target = pmrem.fromEquirectangular(texture);
+            }
+            finally {
+                pmrem.dispose();
+            }
+            const oldTexture = this.environment;
+            const oldTarget = this.environmentTarget;
+            this.environment = texture;
+            this.environmentTarget = target;
+            this.scene.environment = target.texture;
+            this.applyConfig();
+            texture = undefined;
+            target = undefined;
+            oldTarget?.dispose();
+            oldTexture?.dispose();
+        }
+        catch (error) {
+            target?.dispose();
+            texture?.dispose();
+            this.assertCurrent(request, 'environment');
+            throw error;
+        }
+        finally {
+            asset.release();
+        }
+    }
+    /** Fit the entire model and return the camera to the front. */
+    fit() {
+        this.assertActive();
+        if (!this.model)
+            return;
+        const bounds = new THREE.Box3().setFromObject(this.model);
+        const size = bounds.getSize(new THREE.Vector3());
+        const target = bounds.getCenter(new THREE.Vector3());
+        const verticalFov = THREE.MathUtils.degToRad(this.camera.fov);
+        const horizontalFov = 2 * Math.atan(Math.tan(verticalFov / 2) * this.camera.aspect);
+        const distance = Math.max(size.y / (2 * Math.tan(verticalFov / 2)), size.x / (2 * Math.tan(horizontalFov / 2)), size.z) * 1.15;
+        this.controls.target.copy(target);
+        this.camera.position.copy(target).add(new THREE.Vector3(0, 0.08, 1).normalize().multiplyScalar(distance));
+        this.camera.near = Math.max(distance / 100, 0.001);
+        this.camera.far = Math.max(distance * 100, 100);
+        this.controls.minDistance = distance * 0.2;
+        this.controls.maxDistance = distance * 5;
+        this.camera.updateProjectionMatrix();
+        this.controls.update();
+    }
+    /** Resize without changing the user's orbit/zoom. Called automatically by ResizeObserver. */
+    resize() {
+        this.assertActive();
+        const width = Math.max(this.container.clientWidth, 1);
+        const height = Math.max(this.container.clientHeight, 1);
+        this.renderer.setSize(width, height, false);
+        this.camera.aspect = width / height;
+        this.camera.updateProjectionMatrix();
+    }
+    /** Idempotent. In-flight results will be discarded and their resources released. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.frame !== undefined)
+            cancelAnimationFrame(this.frame);
+        this.observer.disconnect();
+        document.removeEventListener('visibilitychange', this.syncLoop);
+        this.renderer.domElement.removeEventListener('webglcontextlost', this.onContextLost);
+        this.renderer.domElement.removeEventListener('webglcontextrestored', this.onContextRestored);
+        this.controls.dispose();
+        this.scene.environment = null;
+        this.scene.background = null;
+        this.scene.clear();
+        if (this.model)
+            disposeModel(this.model);
+        this.environmentTarget?.dispose();
+        this.environment?.dispose();
+        this.model = undefined;
+        this.environment = undefined;
+        this.environmentTarget = undefined;
+        this.renderer.dispose();
+        this.renderer.forceContextLoss();
+        this.renderer.domElement.remove();
+    }
+    assertActive() {
+        if (this.disposed)
+            throw new Error('AvatarRenderer has been disposed');
+    }
+    assertCurrent(request, kind) {
+        if (this.disposed || request !== (kind === 'model' ? this.modelRequest : this.environmentRequest)) {
+            throw new DOMException('Loading was superseded or renderer was disposed', 'AbortError');
+        }
+    }
+    applyConfig() {
+        const config = this.config;
+        this.scene.environmentIntensity = config.intensity;
+        this.scene.backgroundIntensity = config.intensity;
+        this.scene.environmentRotation.y = THREE.MathUtils.degToRad(config.rotation);
+        this.scene.backgroundRotation.y = THREE.MathUtils.degToRad(config.rotation);
+        this.scene.background = config.panorama && this.environment ? this.environment : new THREE.Color(config.background);
+        this.renderer.toneMappingExposure = config.exposure;
+        this.renderer.toneMapping = config.toneMapping === 'aces' ? THREE.ACESFilmicToneMapping : THREE.NeutralToneMapping;
+        this.controls.autoRotate = config.autoRotate;
+        if (this.model) {
+            this.model.rotation.y = THREE.MathUtils.degToRad(config.modelRotation);
+            this.model.traverse((node) => {
+                const mesh = node;
+                if (!mesh.isMesh)
+                    return;
+                for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
+                    if ('wireframe' in material)
+                        material.wireframe = config.wireframe;
+                }
+            });
+        }
+    }
+    onContextLost = (event) => { event.preventDefault(); this.contextLost = true; this.syncLoop(); };
+    onContextRestored = () => {
+        if (this.disposed)
+            return;
+        // Render-target contents are lost with the context; rebuild filtered IBL.
+        if (this.environment) {
+            const pmrem = new THREE.PMREMGenerator(this.renderer);
+            try {
+                const target = pmrem.fromEquirectangular(this.environment);
+                this.scene.environment = target.texture;
+                this.environmentTarget?.dispose();
+                this.environmentTarget = target;
+            }
+            finally {
+                pmrem.dispose();
+            }
+        }
+        this.contextLost = false;
+        this.syncLoop();
+    };
+    syncLoop = () => {
+        if (this.frame !== undefined)
+            cancelAnimationFrame(this.frame);
+        this.frame = undefined;
+        this.lastTime = 0;
+        if (!this.disposed && !document.hidden && !this.contextLost)
+            this.frame = requestAnimationFrame(this.render);
+    };
+    render = (time) => {
+        if (this.disposed)
+            return;
+        const delta = this.lastTime ? Math.min((time - this.lastTime) / 1000, 0.05) : 0;
+        this.lastTime = time;
+        this.controls.update(delta);
+        this.renderer.render(this.scene, this.camera);
+        this.frame = requestAnimationFrame(this.render);
+    };
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@avatar-platform/avatar-render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Framework-independent GLB viewer with configurable HDR/EXR studio lighting",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "assets",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepack": "pnpm build"
+  },
+  "peerDependencies": {
+    "three": "^0.180.0"
+  },
+  "devDependencies": {
+    "three": "^0.180.0",
+    "@types/three": "^0.180.0",
+    "typescript": "~5.6.2",
+    "vitest": "^2.1.9",
+    "jsdom": "^25.0.1"
+  }
+}