@omrips/viewstl 2.0.0-rc.4 → 2.0.0-rc.6

package/docs/v2-usage.md

@@ -1,14 +1,14 @@
 # ViewSTL 2 — native WebGL2 plugin
 
-Version: `2.0.0-rc.4` (ViewSTL v2.00 release candidate). The npm package is
-`@omrips/viewstl`; install the candidate with `npm install @omrips/viewstl@2.0.0-rc.4`.
-The legacy plugin remains at its original repository paths and on the production
-website. The v2 website is available at https://preview.viewstl.com/.
+Version: `2.0.0-rc.5` (ViewSTL v2.00 release candidate, GitHub and npm).
+On `main`, the new plugin is in `src/` and `build/`; the legacy tree is in
+`legacy/v1/`. The unchanged `master` branch retains original legacy paths.
+The v2 website is available at https://preview.viewstl.com/.
 
 ## Quick start
 
-Install with `npm install @omrips/viewstl@2.0.0-rc.4`, then copy the complete
-`node_modules/@omrips/viewstl/build/v2/` folder to `/viewstl-v2/` on your website.
+Download the plugin ZIP from the [GitHub release](https://github.com/omrips/viewstl/releases/tag/v2.0.0-rc.5),
+then copy its complete `build/` folder to `/viewstl-v2/` on your website.
 Paste these three lines into your page's `<body>`:
 
 ```html
@@ -23,7 +23,7 @@ required so the viewer can find its worker and optional format assets.
 
 ## Browser script
 
-Copy the complete `build/v2/` directory to your server, including the
+Copy the complete `build/` directory to your server, including the
 worker, its `chunks/` and `cad/` directories and third-party notices. Then:
 
 ```html
@@ -58,11 +58,13 @@ The package contains ESM, CommonJS and TypeScript entry points. Importing
 the package is safe during server-side rendering; constructing a viewer
 requires a browser DOM and WebGL2.
 
-The package name is `@omrips/viewstl`, under the verified `omrips` npm account.
-Release candidates use the `next` dist-tag. Pin the version above for a
-repeatable installation; installing a local release tarball is also supported.
+Install with `npm install viewstl`. No version suffix is required: the `latest`
+tag selects the current release candidate. The established `@omrips/viewstl`
+package is also updated with the same plugin; `npm install @omrips/viewstl`
+works without a version suffix. Use either package name consistently in imports
+and asset-copy paths; there is no need to install both.
 
-With a bundler, copy the complete `node_modules/@omrips/viewstl/build/v2/`
+With a bundler, copy the complete `node_modules/viewstl/build/`
 directory to your app's public assets (for example `public/viewstl-v2/`), keeping
 the worker, `chunks/`, `cad/` and notices together. Set `worker_url` to its served
 URL, or provide your bundler's worker factory.
@@ -70,7 +72,7 @@ Do not assume a bundler copies a module worker's dynamic chunks merely
 because it sees a URL string.
 
 ```js
-import StlViewer from '@omrips/viewstl';
+import StlViewer from 'viewstl';
 
 const viewer = new StlViewer(container, {
   worker_url: '/viewstl-v2/viewstl.worker.js'
@@ -80,7 +82,7 @@ const viewer = new StlViewer(container, {
 For Vite, the optional factory form is:
 
 ```js
-import ViewerWorker from '@omrips/viewstl/worker?worker';
+import ViewerWorker from 'viewstl/worker?worker';
 const viewer = new StlViewer(container, {
   worker_factory: () => new ViewerWorker()
 });
@@ -96,17 +98,17 @@ The CommonJS entry point also requires
 
 ## Node.js model analysis
 
-Install `npm install @omrips/viewstl@2.0.0-rc.4`. Node.js 20+ resolves the analysis
+Run `npm install viewstl`. Node.js 20+ resolves the analysis
 worker and optional CAD WASM directly inside the package; there is no asset-copy
 step for server use.
 
 ```js
-import { analyzeFile } from '@omrips/viewstl/node';
+import { analyzeFile } from 'viewstl/node';
 const report = await analyzeFile('part.stl', { units: 'mm' });
 console.log(report.dimensions_mm, report.surface_area_mm2, report.volume_mm3);
 ```
 
-CommonJS is supported with `const { analyzeFile } = require('@omrips/viewstl/node')`.
+CommonJS is supported with `const { analyzeFile } = require('viewstl/node')`.
 The `/node` entry point is separate from the browser viewer and has no DOM,
 WebGL or Three.js dependency. It supports STL, OBJ, 3MF, STEP/STP and IGES/IGS.
 STEP/IGES measurements describe the tessellated mesh, not exact CAD surfaces.
@@ -119,7 +121,7 @@ object. `analyzeBuffer(data, options)` accepts a Node Buffer, Uint8Array or
 ArrayBuffer, and requires `filename` or `format` to identify the format:
 
 ```js
-import { analyzeBuffer } from '@omrips/viewstl/node';
+import { analyzeBuffer } from 'viewstl/node';
 const report = await analyzeBuffer(uploadBuffer, { filename: 'part.stl', units: 'mm' });
 ```
 
@@ -151,7 +153,7 @@ The convenience functions share an analyzer with two active workers, up to
 Create an independent analyzer when the host needs different concurrency:
 
 ```js
-import { createAnalyzer } from '@omrips/viewstl/node';
+import { createAnalyzer } from 'viewstl/node';
 const analyzer = createAnalyzer({ concurrency: 1, max_queue: 4 });
 try {
   const reports = await Promise.all(paths.map(path => analyzer.analyzeFile(path, {
@@ -220,7 +222,7 @@ app.dispose(); // cancels work and releases listeners, workers and WebGL
 
 This controller binds the preview's HTML control layout; the host supplies
 markup and CSS. The reference layout is `Viewstl/site/index.html` in the sibling
-website workspace. `requiredControls` in `src/v2/app.js` validates the control
+website workspace. `requiredControls` in `src/app.js` validates the control
 IDs before registering handlers. Missing controls and duplicate mounts produce
 a descriptive error. Custom integrations without that layout use `StlViewer`.
 Branding, page metadata, advertisements and static help/privacy text belong
@@ -269,7 +271,7 @@ internal geometry or retain its buffers.
   Use self-contained exports: external part files are not fetched, and native
   SolidWorks/Solid Edge formats, feature history, PMI and curve-only files are
   unsupported. Incomplete external-reference assemblies may lack parts.
-- Deploy the entire `build/v2/cad/` directory alongside `chunks/` and the worker.
+- Deploy the entire `build/cad/` directory alongside `chunks/` and the worker.
   CAD code/WASM is loaded only for CAD files; local input bytes are never uploaded.
   Each job's worker is terminated on completion, cancellation, error or timeout.
   CAD admission estimates 128 MiB plus 40 times the input size. The WASM heap
@@ -304,6 +306,109 @@ Transparency uses model-level back-to-front sorting; intersecting transparent
 surfaces can still have ordering artifacts. STL export stores face color,
 so a 3MF triangle's per-vertex gradient cannot survive STL/VSB export exactly.
 
+## Model animation
+
+Animation is included in `2.0.0-rc.5` on GitHub and in both npm packages.
+Playback remains inside the native WebGL2 plugin.
+
+After a model has loaded, one call starts continuous rotation:
+
+```js
+await viewer.when_idle();
+viewer.animate_model(0, {
+  delta: { rotationz: 2 * Math.PI, msec: 5000, loop: true },
+});
+```
+
+The legacy `animation` model option also works. `delta` adds a change to the
+starting pose; `exact` interpolates toward an absolute target. They can operate
+together on different properties and finish independently:
+
+```js
+viewer.animate_model(0, {
+  delta: { rotationx: 1, rotationy: 1.1, rotationz: 1.2, msec: 1000, loop: true },
+  exact: { x: 1000, y: 150, z: 200, scale: 5, msec: 3000 },
+});
+
+viewer.pause_model_animation(0);  // Keep the pose and elapsed time.
+viewer.resume_model_animation(0);
+console.log(viewer.get_model_animation_state(0));
+viewer.animate_model(0, null);    // Stop at the current pose; discard playback.
+```
+
+Supported properties are `x/y/z`, `rotationx/y/z` in radians and
+`scale` or `scalex/scaley/scalez`. Durations are positive milliseconds, defaulting
+to 300. Scale deltas are additive, as in the legacy API; all resulting scales
+must stay positive. Only delta tracks repeat, accumulating their change each
+cycle. A negative looping scale delta is rejected. Delta and exact may not claim
+the same property. Inputs must be finite and within JavaScript's safe numeric
+range. Invalid replacements leave the current animation intact.
+
+Starting a new animation replaces the old one from the current pose. Manual
+position, rotation, scale and unit setters stop that model's playback first.
+Camera interaction, color and viewing-mode changes remain usable. Completed
+tracks no longer write their properties. Removal, `clean()` and `dispose()`
+release playback; paused/completed models do not keep the render loop running.
+
+Timing follows elapsed frame timestamps, not frame count. Hidden documents and
+lost WebGL contexts suspend playback without including that gap on resumption.
+User pause is independent of this automatic suspension. State queries return
+`status`, `elapsed_ms`, `suspended` and active `tracks`; unknown IDs return null.
+
+Set callbacks in the viewer options:
+
+```js
+const viewer = new StlViewer(container, {
+  animation_state_callback(id, state, reason) {
+    console.log(id, state.status, reason);
+  },
+  animation_complete_callback(id, state) {
+    console.log('Finished', id, state.elapsed_ms);
+  },
+});
+```
+
+Callbacks describe transitions, not every frame, and are deferred until the
+current operation finishes. Completion fires once when every track finishes;
+an animation with a looping track does not complete. Call playback controls on
+loaded models, for example after `when_idle()`.
+
+VSB/VSJ preserve the animation definition, original pose, elapsed phase, rotation
+pivot and pause flag. Both scene-loading APIs start incoming animations together
+after all incoming models load. VSJ still needs its referenced model files.
+Animated VSB entries retain unscaled mesh data and explicit scale metadata;
+static entries retain the previous scale-baked convention. This prevents scale
+being applied twice. Older viewers may read the pose but cannot restore the new
+playback-state extension exactly.
+
+PNG and modern `export_models()` capture the current pose without stopping
+playback. Legacy `get_stl_bin()` keeps its documented scale/centering-only export
+convention. Regular model files do not store animation. Print checks should run
+while the affected models are paused; subsequent motion makes the report stale.
+
+A self-contained example is in `examples/v2/animation.html` in the source
+checkout (serve with `pnpm start`). It includes Play, Pause, Resume, Stop and Reset.
+
+The app controller also supports an optional `animation-*` group (see the new
+site's HTML template): `animation-details`, `animation-fields`, `animation-axis`,
+`animation-seconds`, `animation-direction`, `animation-play`, `animation-pause`,
+`animation-stop`, `animation-status` and `animation-error`. Supply the whole group
+or omit it. It exposes selected-model spin around the mesh center, duration
+(0.1–3,600 seconds per turn), direction and playback buttons. Other models keep
+playing when selection changes. Manual tools capture the current animated pose.
+Readouts update at most four times per second; geometry and GPU buffers are reused.
+
+`mountViewstlApp` composes `animation_state_callback` and
+`animation_complete_callback` options with its own UI behavior. `app.getState()`
+includes each model's current transform and `animation` state. Ordinary files
+never auto-spin. Imported running animations are paused when the browser reports
+`prefers-reduced-motion: reduce`; explicit user playback remains available.
+
+App print checks pause running target models. Optional `print-resume` and
+`print-animation-note` elements expose resumption; closing the panel does not
+silently restart motion. Resuming clears stale results and keeps the panel open.
+Scene saving includes playback; PNG and regular model saving capture a pose.
+
 ## Existing API and intentional differences
 
 The existing constructor, model options and documented method names are
@@ -609,6 +714,7 @@ pnpm install --frozen-lockfile
 pnpm build
 pnpm test
 pnpm check:types
+pnpm check:node-types
 pnpm check:legacy
 pnpm start
 pnpm pack
@@ -745,7 +851,8 @@ scene with many remote references can hit the relay's rate limit.
 Imports append models with new IDs and restore camera, background/grid, transforms,
 colors/opacity, view modes, smoothing and sections. Saved centering is converted
 to equivalent model positions without changing existing models' centering. Embed
-canvas size, resize/mouse controls and per-model animation are not imported.
+canvas size and resize/mouse controls are not imported. The development animation
+update also restores per-model animation and preserves its original pivot.
 Scene reading and mesh parsing use workers and the existing memory/triangle/archive
 limits. Models become visible together after all have loaded. Errors, cancellation,
 or a throwing progress callback remove the incoming models and retain the existing
@@ -842,3 +949,27 @@ Escape with focus inside the panel dismisses it. Reopening it from Info reveals
 and focuses the existing panel. Loading or changing the checked selection cancels
 an active check; stale results are cleared. Loading and empty scenes disable Run
 and show the current availability without closing the panel.
+
+## Model size, units, duplicates, cameras and measurements (rc.6)
+
+All operations below are implemented inside the plugin. The optional site controls remain a thin HTML/CSS host.
+
+`viewer.resize_model(id, [2, 2, 2])` doubles the model about its world-space bounds center, preserving rotation and placement. Positive finite XYZ factors are required; independent factors allow nonuniform scaling. It stops only that model's animation. `get_model_size(id)` returns dimensions and the reset baseline in millimetres. `reset_model_size(id)` restores that baseline while retaining file-unit corrections.
+
+`viewer.set_file_units(id, 'inch')` reinterprets a unitless STL/OBJ mesh (default mm) without moving its center. Switching back reverses the conversion. Explicit 3MF/STEP/IGES units are normalized to mm during parsing and cannot be reinterpreted. `set_display_units('inch')` changes the optional app's size/Info readouts only; scene coordinates, position controls and the grid remain in mm. Existing `set_model_units` and `set_scale` retain their legacy semantics.
+
+`const copy = viewer.duplicate_model(id)` returns a new ID at the same pose, with independent appearance, transforms and metadata. Immutable geometry and matching GPU buffers are shared; memory admission remains conservative. The source reference remains unchanged for VSJ, while `display_name` identifies the copy. Copied animation definitions and phase are retained but paused; the original keeps playing.
+
+`viewer.set_camera_view('top')` fits the scene from front/back/left/right/top/bottom/isometric using Z up and the existing perspective projection. It never rotates the models. Camera bookmarks are explicit data:
+
+`viewer.set_camera_bookmarks([{name: 'Detail', camera: viewer.get_camera_state()}])`
+
+Use `get_camera_bookmarks()` to obtain a defensive copy and `set_camera_state(bookmark.camera)` to restore one. Up to 32 uniquely named views (80 characters per name) are supported. They are kept in memory and in scene exports, not localStorage.
+
+`const {area_mm2, volume_mm3, volume_valid, volume_reason} = await viewer.measure_model(id)`
+
+Measurements use workers and support `signal`, `max_time_ms` (default 30 seconds) and `on_progress`. Area includes all triangles at current scale. Volume is nullable: detailed topology, intersections and shell-orientation checks must establish a closed volume. An open/invalid mesh or an inconclusive/time-limited check never becomes a plausible-looking volume. Results are cached by mesh and scale; position/rotation do not invalidate them and uniform resizing updates cached measurements algebraically. Nonuniform area is recalculated in the worker. Memory limits can reject the calculation before buffers are copied. This is a bounded mesh analysis, not a guarantee of printability.
+
+VSB/VSJ retain size baselines, file-unit interpretation, display units, duplicate labels and bookmarks. VSB still embeds geometry; VSJ still needs the referenced source files. No second unit conversion occurs during import. Appending scenes merges bookmark names with numbered suffixes; a combined total above 32 rejects the incoming scene. Old files without the new optional fields continue to load. The `size_state.unit_factor` serialization field preserves source-unit correction separately from resize factors for exports with `apply_transforms:false`.
+
+The optional app control group is listed in `src/app-tools.js` (`toolsControls`). Provide the whole group or omit it when embedding older markup. The preview's `site/index.html` is a complete example. Models contains collapsed Size & units and Duplicate; View contains collapsed Camera & saved views; Info contains area and the volume calculation. No server is involved for local files or measurements.

package/docs/v2-verification.md

@@ -3,6 +3,167 @@
 This file records dated checks. Older sections describe the alpha at the time
 of each check; release-candidate results are recorded separately below.
 
+## npm names and installation — 2026-11-07
+
+Published `viewstl@2.0.0-rc.5` and `@omrips/viewstl@2.0.0-rc.5` with `latest`
+pointing to rc.5. The existing scoped `next` tag was also advanced to rc.5.
+Both READMEs document `npm install viewstl` and retain the scoped alternative.
+All existing scoped versions remain available.
+
+All 136 unit tests, strict browser/Node type checks and 37 legacy integrity
+checks pass again. Both packed distributions pass Node ESM/CommonJS type checks
+and runtime checks for browser exports, worker/CAD assets and STL/OBJ/3MF/STEP/IGES
+analysis. Fresh public-registry installs without a version suffix pass those
+runtime checks for both package names. Public tarball bytes and SHA-512 integrity
+match the tested local archives; each package contains 40 files.
+
+All 31 files under `build/` match the previously tested GitHub rc.5 distribution
+byte for byte. No renderer changes were made and browser/device tests were not
+rerun for this packaging update. The GitHub browser evidence below still applies
+to those exact runtime bytes. Evidence: local `test-results/npm-stage.json` and
+its referenced staging directory. See [maintainer workflow](npm-releases.md).
+
+## GitHub root-layout release 2.0.0-rc.5 — 2026-11-07
+
+The release worktree places the v2 sources/distribution in `src/` and `build/`.
+The complete pre-v2 GitHub tree is archived under `legacy/v1/`; its 23 original
+Git blobs and the 14-file local v1.14 snapshot pass SHA-256/size verification.
+Historical sections below retain the paths and versions used at the time.
+
+All **136 unit tests** pass, along with strict browser and Node TypeScript
+consumers. Actual desktop Chrome 156, without device emulation, passes **46
+browser checks**: 15 compatibility, 11 animation, 11 scene and 9 export checks.
+These exercise the relocated classic/ESM entries, module workers, legacy mesh
+bridge, STL/OBJ/3MF/STEP/IGES export/reimport, scene playback, cancellation,
+context restoration and a responsive million-triangle STL export.
+
+The packed `@omrips/viewstl@2.0.0-rc.5` tarball installs into a clean consumer
+project. Browser ESM/CommonJS exports, version reporting, worker/CAD asset paths,
+and server analysis of STL, OBJ, 3MF, STEP and IGES pass. Node analysis also
+passes through the CommonJS entry. Archive contents exclude development fixtures,
+legacy runtime copies and site/server files; license notices and lazy assets are included.
+
+The layout update also corrects old harness references to the legacy parser and
+worker directory. The compatibility animation assertion now waits for the public
+completion callback and checks the public completed state, rather than assuming
+the old private animation representation or a fixed wall-clock delay.
+
+Evidence is retained locally in the original plugin checkout under
+`test-results/github-v2-20261107/`. Physical mobile, Safari and Firefox validation
+remain pending. This release does not update the preview website or npm registry.
+
+## Live animation save/open verification — 2026-11-02
+
+Verified the existing `20261102-f04f34e66b7c` release through the actual Save and
+Open controls on `https://preview.viewstl.com/`, in desktop in-app Chromium.
+No runtime changes or redeployment were needed. Two binary STL fixtures have
+offset geometry centers: one runs reverse X rotation at 3 seconds per turn and
+is paused; the other runs forward Z rotation at 7 seconds per turn.
+
+Both VSB and VSJ were downloaded, the page was freshly reloaded, and the downloaded
+files were opened and saved again. **40 checks pass** against the resulting files
+and visible controls: two models, camera, position/scale/appearance, animation
+definition, pivot/origin, pause state, exact paused time and pose, advancing running
+time and a pose consistent with that time. VSB mesh coordinates match both their
+original files and the re-saved archive. VSJ file references remain intact. The
+paused model's elapsed time stayed exactly `7400.434000000001` ms in both formats;
+the running model continued from each saved time instead of restarting.
+
+A second pair of files was saved with both models paused. PNGs downloaded before
+saving and after independently reopening each format are **byte-for-byte equal**.
+VSB opens alone; VSJ was opened together with its two referenced STL files. Paused
+models expose Resume with the restored axis, duration and direction. There were
+no console errors on the final restored page. This is desktop-browser evidence,
+not physical mobile or other-browser coverage.
+
+The website workspace retains actual downloads, UI-state records, PNGs and
+`verification.json` in `results/animation-roundtrip-20261102/`. Recheck those
+artifacts with `node site/qa/verify-animation-downloads.mjs --images`; regenerate
+the offset STL fixtures with `node site/qa/make-animation-fixtures.mjs`.
+
+## Preview-site animation integration — 2026-11-02
+
+Deployed to preview as `20261102-f04f34e66b7c`. The optional animation app binding
+is bundled inside viewstl.js; the site's initializer is unchanged. The site adds
+static controls under Models → Animation: axis, seconds per turn, direction and
+Play/Pause/Resume/Stop. Off-center models spin about their center without moving
+their visible pose. Editing uses current transforms, and adding/selecting files
+preserves other models' animation. Print checks pause their targets and offer
+explicit Resume while keeping the results panel open. Reduced-motion preference
+pauses restored playback. Stopped animations also retain an equivalent static
+VSJ pose with the original referenced mesh.
+
+All **136 unit tests**, both strict type checks and the legacy guard pass.
+Actual desktop Chromium 156 passes **25 new integration checks** and **96 existing
+site checks**. New coverage includes invalid speed, concurrent models, live-pose
+manual editing, drag entry, print pause/resume, VSB phase/pause restoration,
+stopped off-center VSJ reopening with an identical PNG, callback composition,
+clear/dispose/remount and simulated reduced motion. Keyboard Enter playback was
+also exercised. 320px and 390px viewport checks show no horizontal overflow and
+44px-high playback buttons; these are emulated widths, not physical touch tests.
+
+All 29 public HTTPS files match the local SHA-256 manifest. Live browser smoke
+checks cover loading, keyboard playback and print-check interaction. Nginx, relay
+and Certbot remain active; configuration/service/binary hashes match the previous
+release and SELinux remains enforcing. Initial gzip total is 57,897 bytes; the
+viewer entry is 42,150 bytes. No new million-triangle or total-memory benchmark
+was performed for the app controls; the earlier plugin measurement remains below.
+Physical mobile, Safari/Firefox and actual hidden-tab behavior remain unverified.
+
+Evidence: the site workspace's `results/animation-integration/` and
+`results/deploy-20261102-f04f34e66b7c/`. Reproduce the browser checks through the
+local-only `site/qa/animation.html` and `site/qa/index.html` pages. The QA harness
+is excluded from deployment. npm is unchanged (`2.0.0-rc.4`); no GitHub push.
+
+## Model animation — unreleased development update, 2026-11-02
+
+The local plugin now has validated legacy delta/exact playback, per-model
+pause/resume/state queries and transition/completion callbacks. Animation uses
+elapsed frame time, retires finished tracks independently, stops on manual
+transform edits and suspends on document hiding or context loss. VSJ and both
+VSB APIs preserve animation phase, pause state, units and rotation pivot; animated
+VSB meshes retain scale in metadata to avoid applying it twice on reopening.
+The native WebGL2 renderer and existing worker architecture remain in use.
+
+- All **132 Node tests pass** on Node.js 24.19.0, Windows. Nine new tests cover
+  mixed durations, frame cadence, pause/resume/suspension, manual changes,
+  replacement and copied state, scale/statistics invalidation, invalid numeric
+  inputs and overflow, scene validation, VSJ/VSB restoration and export snapshots.
+- Browser and server-only strict TypeScript checks pass. The legacy guard passes
+  for tracked legacy files and all 14 archived files.
+- **11 animation browser checks pass** in actual desktop Chromium 156 on Windows,
+  using workers and WebGL2. These cover constructor playback, concurrent models,
+  idle behavior, pause/resume/stop, modern and legacy scene restoration, group
+  starts, bad-scene rollback, print-check staleness, mesh/PNG snapshots, forced
+  context loss/restoration and resource cleanup. Context loss is deliberately
+  triggered with `WEBGL_lose_context`, not a hardware failure.
+- Existing browser compatibility (**15**) and scene/rendering (**11**) checks
+  also pass: **37 passing browser checks** in total.
+- A generated **1,000,000-triangle** model animated over 120 measured frame
+  intervals: median **16.7 ms**, p95 **16.8 ms**, maximum **16.9 ms**. Geometry
+  objects and GPU resources retained identity, with two GPU buffers and
+  72,375,000 bytes of resident geometry typed arrays. These are frame intervals
+  on one desktop, not GPU timings, allocation profiling or total process memory.
+- The interactive example at `examples/v2/animation.html` runs locally and exposes
+  Play, Pause, Resume, Stop and Reset. No models or external assets are fetched.
+
+Actual hidden-tab behavior remains unverified: automation tab changes in the
+in-app browser and Chrome did not produce a document `visibilitychange` event.
+The suspension/resumption code is covered by unit tests and the real WebGL
+context-loss check. Firefox, Safari, physical phones/tablets, touch, reduced-motion
+site integration and a total-memory profile have not been tested in this update.
+
+Reproduce with `pnpm build`, `pnpm test`, `pnpm check:types`,
+`pnpm check:node-types`, `pnpm check:legacy`, then `pnpm start`. Open
+`tests/v2/animation-browser.html`, `tests/v2/browser.html` and
+`tests/v2/scene-browser.html` and run their checks. The million-triangle and
+background-tab checks have separate buttons on the animation page.
+
+Evidence is retained locally in ignored `test-results/animation-*` files. The
+package version is still `2.0.0-rc.4`; this development update has **not** been
+published to npm or deployed. The proposed site work is described in
+[the preview integration plan](v2-animation-site-plan.md).
+
 ## Runnable server example 2.0.0-rc.4 — 2026-10-20
 
 The npm README now contains a clearly labeled server-only example, including
@@ -486,3 +647,11 @@ explicit close from an empty scene. The panel remains open throughout unrelated
 activity while stale reports and active jobs are handled safely. All 112 Node
 tests, strict types and 14 legacy hashes pass again. Evidence: sibling website
 `results/print-persistent/` and `results/deploy-20261017-5b21747c4c8f/`.
+
+## 2026-11-07 — rc.6 model tools
+
+146 unit tests pass, as do strict browser/Node TypeScript checks and the 37-file legacy hash guard. Actual Windows Chrome 156 runs against the site built from the candidate npm tarball: 25 new model-tools integration checks, 25 animation regressions and 96 existing site regressions pass. New coverage includes locked/nonuniform resize, invalid input recovery, mm/inch separation, copy animation isolation, source references, shared geometry/GPU cleanup, camera presets, bookmark validation/merge, static and animated VSB/VSJ round trips, reset baselines, explicit 3MF/CAD units, and malformed-scene rollback. Surface area and enclosed volume use known closed/open fixtures; source-unit corrections also survive untransformed mesh export.
+
+Manual desktop checks cover size inputs, keyboard Apply and on-demand measurements. Narrow widths are viewport emulation, not physical phone tests. No physical touch device, Safari/Firefox or broad large-CAD stress testing is claimed. The bounded detailed mesh checker may return an unavailable/inconclusive volume; source coordinates without units remain assumed mm until corrected.
+
+Website evidence is retained outside its public build in `Viewstl/results/rc6/`; local-only reproducible browser harnesses are `site/qa/model-tools.html`, `animation.html` and `index.html`. Generated assets and the whole npm distribution are packaged together.

package/legacy/README.md

@@ -1,20 +1,26 @@
 # Preserved legacy versions
 
-The existing `src/`, top-level `build/` files, and `dependencies/` remain
-the GitHub legacy implementation. Keep their existing download paths.
-New v2 output belongs under `build/v2/`.
+On the v2 `main` branch, [`v1/`](v1/) contains the complete legacy GitHub
+tree, including its original README, source, build, dependencies and license.
+Its manifest records the original bytes and SHA-256 hashes of all 23 files.
+
+The existing [`master` branch](https://github.com/omrips/viewstl/tree/master)
+remains unchanged at the baseline below, preserving explicit master download
+URLs. Existing tags are retained. New v2 source and output live at the root
+under `src/` and `build/` on `main`; callers following the default branch
+receive v2 and should review its migration notes.
 
 ## GitHub baseline
 
 - Repository: https://github.com/omrips/viewstl
-- Original default branch: `master`
+- Legacy branch: `master` (the default before v2)
 - Baseline commit: `fbb7f5c3894862778c3a6c5d2630573e2496d01f`
-- Local preservation tag: `legacy-before-v2-2026-09-30`
-- Latest published release when inspected: `v1.13`
+- Preservation tag: `legacy-before-v2-2026-09-30`
+- Latest legacy version tag: `v1.13`
 
 The baseline commit includes changes after the `v1.13` tag. Do not treat the
-release tag and the current legacy branch as identical. The preservation
-tag and development branch are local until explicitly pushed to GitHub.
+release tag and the legacy branch as identical. The v2 release preserves
+both that branch and the existing version tags.
 
 ## Local website snapshot
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omrips/viewstl",
-  "version": "2.0.0-rc.4",
+  "version": "2.0.0-rc.6",
   "description": "Local-first STL, OBJ, 3MF, STEP and IGES viewer with native WebGL2 and transferable worker geometry",
   "type": "module",
   "license": "MIT",
@@ -18,71 +18,54 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "next",
+    "tag": "latest",
     "registry": "https://registry.npmjs.org/"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/omrips/viewstl.git"
   },
-  "main": "./build/v2/viewstl.cjs",
-  "module": "./build/v2/viewstl.js",
-  "types": "./build/v2/viewstl.d.ts",
+  "main": "./build/viewstl.cjs",
+  "module": "./build/viewstl.js",
+  "types": "./build/viewstl.d.ts",
   "exports": {
     ".": {
       "import": {
-        "types": "./build/v2/viewstl.d.ts",
-        "default": "./build/v2/viewstl.js"
+        "types": "./build/viewstl.d.ts",
+        "default": "./build/viewstl.js"
       },
       "require": {
-        "types": "./build/v2/viewstl.d.cts",
-        "default": "./build/v2/viewstl.cjs"
+        "types": "./build/viewstl.d.cts",
+        "default": "./build/viewstl.cjs"
       }
     },
     "./node": {
       "node": {
         "import": {
-          "types": "./build/v2/node/index.d.ts",
-          "default": "./build/v2/node/index.js"
+          "types": "./build/node/index.d.ts",
+          "default": "./build/node/index.js"
         },
         "require": {
-          "types": "./build/v2/node/index.d.cts",
-          "default": "./build/v2/node/index.cjs"
+          "types": "./build/node/index.d.cts",
+          "default": "./build/node/index.cjs"
         }
       }
     },
-    "./worker": "./build/v2/viewstl.worker.js",
-    "./browser": "./build/v2/stl_viewer.min.js",
-    "./assets/*": "./build/v2/*",
+    "./worker": "./build/viewstl.worker.js",
+    "./browser": "./build/stl_viewer.min.js",
+    "./assets/*": "./build/*",
     "./package.json": "./package.json"
   },
   "files": [
-    "build/v2",
+    "build",
     "LICENSE",
     "docs/v2-usage.md",
     "docs/v2-compatibility.md",
     "docs/v2-verification.md",
+    "docs/releases/2.0.0-rc.6.md",
     "legacy/README.md",
     "THIRD-PARTY-NOTICES.txt"
   ],
-  "scripts": {
-    "build": "node scripts/build-v2.mjs",
-    "test": "node --test tests/v2/*.test.mjs",
-    "check:legacy": "node scripts/check-legacy.mjs",
-    "check:types": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 --lib ES2022,DOM tests/v2/types.ts",
-    "check:node-types": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 --lib ES2022 --types node tests/v2/node-types.mts tests/v2/node-types.cts",
-    "prepack": "node scripts/build-v2.mjs && node scripts/check-legacy.mjs",
-    "start": "node scripts/serve-v2.mjs"
-  },
-  "devDependencies": {
-    "@types/node": "^20.19.43",
-    "esbuild": "0.28.2",
-    "fflate": "0.8.3",
-    "occt-import-js": "0.0.23",
-    "prettier": "3.9.9",
-    "saxes": "6.0.0",
-    "typescript": "5.9.3"
-  },
   "engines": {
     "node": ">=20"
   }

package/build/v2/README.md

@@ -1,15 +0,0 @@
-# Native WebGL2 build
-
-Generated ViewSTL v2.00 release-candidate artifacts. `stl_viewer.min.js` and `viewstl.min.js` are
-classic scripts exposing `StlViewer`. `viewstl.js` is the ES module;
-`viewstl.cjs` is the CommonJS entry. Keep the module worker, `chunks/` and `cad/`
-directories and license notices beside these files when deploying. See [usage](../../docs/v2-usage.md).
-
-The existing `../stl_viewer.min.js` and its companion files remain the
-legacy distribution. A v2 build must never overwrite those files.
-
-See [the compatibility requirements](../../docs/v2-compatibility.md).
-
-`node/` contains the separate server analysis entry points and worker, exported
-as `@omrips/viewstl/node`. These resolve `cad/` inside the npm package; Node users
-do not need to copy assets to a website.

package/build/v2/chunks/archive-VGS4J4Z7.js

@@ -1 +0,0 @@
-import{a,b,c,d}from"./chunk-R3HNTB5A.js";import"./chunk-ZSV4PTIA.js";import"./chunk-JH3H3JWA.js";import"./chunk-JS56KC3I.js";import"./chunk-U33KANV7.js";export{d as parse3MF,a as safePath,b as unzipChecked,c as zipScene};

package/build/v2/chunks/chunk-JH3H3JWA.js

@@ -1 +0,0 @@
-import{a as k}from"./chunk-JS56KC3I.js";var z=Object.freeze({max_file_bytes:256*1024*1024,max_triangles:5e6,max_uncompressed_bytes:256*1024*1024,max_archive_entries:1024,max_memory_bytes:Number.MAX_SAFE_INTEGER});function O(e){if(typeof e!="string"||!/^#[\da-f]{6}$/i.test(e))throw new Error("Color must be #RRGGBB");return[1,3,5].map(i=>parseInt(e.slice(i,i+2),16)/255)}function U(e,i=null,I=z){if(!(e instanceof Float32Array)||!e.length||e.length%9)throw new Error("Geometry must contain complete triangles");if(e.length/9>I.max_triangles)throw new Error("Triangle limit exceeded");if(k(I,67108864+e.length/9*224),i&&(!(i instanceof Float32Array)||i.length!==e.length))throw new Error("Invalid vertex colors");let u={min:[1/0,1/0,1/0],max:[-1/0,-1/0,-1/0]};for(let r=0;r<e.length;r++){let f=e[r],t=r%3;if(!Number.isFinite(f))throw new Error("Non-finite vertex coordinate");if(u.min[t]=Math.min(u.min[t],f),u.max[t]=Math.max(u.max[t],f),i&&(!Number.isFinite(i[r])||i[r]<0||i[r]>1))throw new Error("Invalid vertex color")}let y=new Float32Array(e.length),b=new Float32Array(Math.ceil(e.length/9/64)*6),h=0,s=0,l=0;for(let r=0;r<e.length;r+=9){let f=e[r+3]-e[r],t=e[r+4]-e[r+1],c=e[r+5]-e[r+2],n=e[r+6]-e[r],o=e[r+7]-e[r+1],x=e[r+8]-e[r+2],w=t*x-c*o,M=c*n-f*x,g=f*o-t*n,E=Math.hypot(w,M,g);h+=E/2,s+=(e[r]*w+e[r+1]*M+e[r+2]*g)/6,E||l++;for(let a=0;a<9;a+=3)y[r+a]=w/(E||1),y[r+a+1]=M/(E||1),y[r+a+2]=g/(E||1);let m=Math.floor(r/9/64)*6;r/9%64===0&&b.set([1/0,1/0,1/0,-1/0,-1/0,-1/0],m);for(let a=0;a<9;a++){let d=a%3;b[m+d]=Math.min(b[m+d],e[r+a]),b[m+3+d]=Math.max(b[m+3+d],e[r+a])}}if(!Number.isFinite(h)||!Number.isFinite(s))throw new Error("Geometry magnitude exceeds numeric limits");return{positions:e,normals:y,colors:i,blocks:b,bounds:u,triangles:e.length/9,area:h,volume:Math.abs(s),degenerateTriangles:l}}function j(e,{smooth:i=!1,edges:I=!1,wire:u=!1,edgeAngle:y=1}={}){let b=new Map,h=new Uint32Array(e.length/3),s=[],l=[];for(let t=0;t<e.length;t+=3){let c=`${e[t]},${e[t+1]},${e[t+2]}`,n=b.get(c);n===void 0&&(n=s.length,b.set(c,n),s.push([e[t],e[t+1],e[t+2]]),l.push([0,0,0])),h[t/3]=n}let r=new Map;for(let t=0;t<e.length;t+=9){let c=e[t+3]-e[t],n=e[t+4]-e[t+1],o=e[t+5]-e[t+2],x=e[t+6]-e[t],w=e[t+7]-e[t+1],M=e[t+8]-e[t+2],g=[n*M-o*w,o*x-c*M,c*w-n*x],E=Math.hypot(...g)||1;for(let m=0;m<3;m++)if(i)for(let a=0;a<3;a++)l[h[t/3+m]][a]+=g[a];if(I||u)for(let m=0;m<3;m++){let a=h[t/3+m],d=h[t/3+(m+1)%3],A=a<d?`${a}:${d}`:`${d}:${a}`,F=g.map(v=>v/E),_=r.get(A);_?(_.count++,_.n.reduce((v,N,T)=>v+N*F[T],0)<Math.cos(y*Math.PI/180)&&(_.sharp=!0)):r.set(A,{a,b:d,n:F,count:1,sharp:!1})}}let f={};if(i){f.smoothNormals=new Float32Array(e.length);for(let t=0;t<h.length;t++){let c=l[h[t]],n=Math.hypot(...c)||1;f.smoothNormals.set(c.map(o=>o/n),t*3)}}for(let[t,c,n]of[[I,"edges",o=>o.count!==2||o.sharp],[u,"wire",()=>!0]])if(t){let o=[...r.values()].filter(n),x=new Float32Array(o.length*6);o.forEach((w,M)=>{x.set(s[w.a],M*6),x.set(s[w.b],M*6+3)}),f[c]=x,c==="edges"&&(f.edgeAngle=y)}return f}function D(e,i=[1,1,1],I=[0,0,0]){let u=new ArrayBuffer(84+e.triangles*50),y=new DataView(u),b=e.positions;new Uint8Array(u).set(new TextEncoder().encode("Binary STL by ViewSTL 2")),y.setUint32(80,e.triangles,!0);for(let h=0;h<e.triangles;h++){let s=84+h*50,l=Array.from({length:9},(n,o)=>(b[h*9+o]-I[o%3])*i[o%3]),r=[l[3]-l[0],l[4]-l[1],l[5]-l[2]],f=[l[6]-l[0],l[7]-l[1],l[8]-l[2]],t=[r[1]*f[2]-r[2]*f[1],r[2]*f[0]-r[0]*f[2],r[0]*f[1]-r[1]*f[0]],c=Math.hypot(...t)||1;for(let n=0;n<3;n++)y.setFloat32(s+n*4,t[n]/c,!0);for(let n=0;n<9;n++)y.setFloat32(s+12+n*4,l[n],!0);if(e.colors){let n=[0,1,2].map(o=>Math.round(e.colors[h*9+o]*31));y.setUint16(s+48,32768|n[0]<<10|n[1]<<5|n[2],!0)}}return u}export{z as a,O as b,U as c,j as d,D as e};

package/build/v2/chunks/chunk-U33KANV7.js

@@ -1 +0,0 @@
-var f=Object.create;var s=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var i=Object.getOwnPropertyNames;var l=Object.getPrototypeOf,u=Object.prototype.hasOwnProperty;var x=(t,r)=>()=>{try{return r||t((r={exports:{}}).exports,r),r.exports}catch(o){throw r=0,o}};var h=(t,r,o,e)=>{if(r&&typeof r=="object"||typeof r=="function")for(let n of i(r))!u.call(t,n)&&n!==o&&s(t,n,{get:()=>r[n],enumerable:!(e=c(r,n))||e.enumerable});return t};var M=(t,r,o)=>(o=t!=null?f(l(t)):{},h(r||!t||!t.__esModule?s(o,"default",{value:t,enumerable:!0}):o,t));var A=(t,r)=>t.map((o,e)=>o-r[e]),y=(t,r)=>t.map(o=>o*r);var w=(t,r)=>[t[1]*r[2]-t[2]*r[1],t[2]*r[0]-t[0]*r[2],t[0]*r[1]-t[1]*r[0]],F=t=>y(t,1/(Math.hypot(...t)||1)),I=()=>new Float64Array([1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]);function d(t,r){let o=new Float64Array(16);for(let e=0;e<4;e++)for(let n=0;n<4;n++)for(let a=0;a<4;a++)o[e*4+n]+=t[a*4+n]*r[e*4+a];return o}function _(t,r,o=1){let e=t[3]*r[0]+t[7]*r[1]+t[11]*r[2]+t[15]*o;return[0,1,2].map(n=>(t[n]*r[0]+t[4+n]*r[1]+t[8+n]*r[2]+t[12+n]*o)/(o&&e?e:1))}export{x as a,M as b,A as c,w as d,F as e,I as f,d as g,_ as h};