prophetk-3d-viewer/CHANGELOG.md

A Three.js r128 based GLB/GLTF model viewer for WeChat Mini Program and Web.

# Changelog

## 0.4.0 — 2026-10-23

### Added

- `models[].invisible` for core, Web and WeChat: hide a model and its descendants from color, depth and shadow rendering while preserving mesh-based picking, click events, selection and dragging.
- Invisible models retain picking occlusion and per-model `clickEvent` / `isMovable` rules. Manual `Object3D.visible = false` still disables interaction, and children waiting for missing parents remain unavailable.
- TypeScript declarations and English/Chinese documentation for invisible hotspots.

### Changed

- The default demo makes `box2` invisible and disables the drag grid; custom scenes retain the existing helper defaults.

### Validation

- Added four regression scenarios covering load paths, interaction and occlusion, parent visibility and reparenting, and visibility restoration after render failures.

## 0.3.0 — 2026-10-22

### Added

- Opt-in `clickEvent` model events, independent of `isMovable`, on core, Web and WeChat.
- Multi-level `models[].parent` relationships and synchronous `setParent()` / `SetParent()` APIs that preserve local transforms.
- Child-first loading, deferred display until ancestors are ready, cycle/duplicate-ID validation and retryable failed parent loads.
- Descendant removal, cancellation of pending model loads and disposal of late resources.
- `parent` in child transform snapshots and `parentchange` gesture cancellation events.

### Fixed

- Explicit `clearModel({ url })` selection no longer matches unrelated model or missing-parent IDs.
- Internal glTF `modelId` metadata no longer excludes meshes from picking, decals or resource cleanup.
- Decal size calculations exclude independently loaded descendants while preserving world transforms.
- The default `box3` child remains clickable and follows `box1`, but cannot be dragged independently, matching the demo instructions.

### Documentation and validation

- Updated the npm README, Chinese guide and TypeScript comments for clicks, parenting, deletion and snapshot persistence, including clearing a former parent when merging root snapshots.
- Added hierarchy checks and four regression scenarios for URL selection, model metadata, decal dimensions and default child interaction.
- Existing scenes without `parent` retain scene-root transforms. Loaded/loading model IDs must be unique; failed loads can be retried with the same ID.

## 0.2.1 — 2026-10-07

### Fixed

- Replaced npm README's relative guide/changelog links with absolute links to the published package files on UNPKG. The links follow the `latest` release and do not depend on unpublished GitHub files.

## 0.2.0 — 2026-10-07

### Added

- `isMovable` model configuration: single selection and direct dragging on a fixed-world-height XZ plane, with touch tolerance, occlusion-aware picking and low-angle protection.
- `camera.controlMode: 'orbit' | 'pan'`, `getCameraControlMode()` and `setCameraControlMode()` across core, Web and WeChat.
- Shared two-finger and wheel camera-distance zoom, including Ctrl+wheel and WeChat DevTools wheel event forwarding.
- Scene-wide world-anchored drag grid with antialiasing, distant-line fading and a WebGL 1 compatibility branch.
- Independent `environment.showDragGrid` and `environment.showBounds` switches, both enabled by default. Grid overlays model geometry; bounds retain depth occlusion; canvas UI remains on top.
- `getModelTransforms()` across all three APIs, returning a JSON string of every loaded model root's ID, current local position, Euler XYZ rotation in degrees and three-axis scale.
- Model interaction events, selection query/clear APIs, cancellation recovery and helper cleanup.
- WeChat packaged relative GLB loading, bypassing remote downloads and cache for local files.
- TypeScript declarations and a Chinese interaction/configuration guide.

### Compatibility and validation

- Existing scenes without `controlMode` continue to use orbit controls; unmarked models remain fixed.
- Gesture ownership prevents model, camera and UI input conflicts. Model selection remains separate from the decal target.
- Web uses pointer capture; WeChat refreshes canvas bounds before gestures and buffers input during its asynchronous query.
- Demo GLB assets are not included in the npm package. Supply your own scene/model resources when integrating.
- Automated checks cover scene transforms, gesture transitions, both camera modes, wheel behavior, helper visibility/depth/coverage, and Web/WeChat input adapters.