beckhoff-xts-viewer-3d 5.2.0 → 5.2.2

package/docs/screenshots/README.md

@@ -1,63 +1,123 @@
 # Screenshots
 
-README + docs gallery, captured straight out of the playground via the
-viewer's own `exportScreenshot` ref method. No external CAD render or
-hand-edit involved — every PNG below was generated by automating the
-playground over `window.__viewer`.
+The README and docs-site image strip, captured straight out of the playground
+through the viewer's own `exportScreenshot()` ref method. No external CAD
+render and no hand-editing: every image below was produced by automating the
+playground over `window.__viewer` / `window.__playground`.
 
 ## How to refresh
 
-The playground exposes two devtools handles for scripted capture:
-`window.__viewer` (Proxy onto the live `XtsViewer3DRef`) and
-`window.__setDemo` (switches the active sample by `DemoKey`). It also
-ships a Vite dev middleware at `POST /__save-screenshot?path=...` that
-writes the body bytes to a whitelisted file under `docs/screenshots/`
-(see `vite.config.ts → capturedScreenshotSaver`).
+```bash
+npm i -g playwright && playwright install chromium   # once
+pnpm docs:capture-screenshots                        # the whole strip
+pnpm docs:capture-screenshots --only 07,12           # by number or filename
+pnpm docs:capture-screenshots --list
+```
 
-Two ways to refresh:
+[`scripts/capture-screenshots.mjs`](../../scripts/capture-screenshots.mjs)
+boots the playground's Vite dev server in-process, drives it in headless
+Chromium and writes the files here. Playwright is deliberately not a
+dependency of the repo — CI never runs this script and a browser download in
+every install would not pay for itself.
 
-**Manual** (one shot, hand-framed):
+What the script takes care of, and why each part is load-bearing:
 
-1. `npm run dev` — open the playground.
-2. Pick the demo from the sidebar (names match the filenames below).
-3. Frame the camera (ViewCube for clean isometric / top-down, or the
-   sidebar's **Reset camera** button for `zoomToFit`).
-4. Open devtools and:
+- **Framing** is computed, not hand-held. A first pass fits the scene AABB to
+  the frustum analytically; a second pass renders a 640 × 360 alpha probe,
+  measures the bounding box of the non-transparent pixels and dollies + pans
+  until the geometry fills 94 % of the frame. An XTS layout is a thin ribbon
+  inside a large box, so the box fit alone leaves half the frame empty.
+- **Readiness** is checked in pixels. `getBoundingBox()` goes non-empty as
+  soon as the config changes, while the GLBs are still streaming and the scene
+  subtree is a Suspense fallback — capturing then yields a blank frame with no
+  error. The script waits until an AABB-fit probe actually covers part of its
+  frame, and refuses to write a shot whose final frame is under 0.5 % covered.
+- **Fonts are proxied through Node.** Station, area, dimension and annotation
+  labels fetch a WOFF from jsDelivr, and the drive-status icons resolve a glyph
+  font through `unicode-font-resolver`. A failed label font suspends the whole
+  scene; a failed glyph resolve renders a warning icon's "!" as exploded
+  geometry. Both are silent, so every font request is served from the Node
+  process, which can reach the network through a proxy.
+- **Motion is stopped** before every capture: the mover drivers are switched
+  off and each shot sets its mover positions explicitly, so a re-run produces
+  the same image.
+
+## Format
+
+1920 × 1080 WebP at quality 0.92 on a solid `#eef0f3` ground, 4× MSAA. Full HD
+is what the README and the docs site actually display, and the whole strip
+weighs ~1.4 MB — it ships inside the npm tarball (`package.json#files`).
+
+The ground is deliberately opaque rather than the transparent alpha the old
+PNGs used: the AT2 housings are anodised anthracite (`#34383c`, see
+[`scripts/materialLibrary.mjs`](../../scripts/materialLibrary.mjs)) and
+disappear into a dark-mode README on a transparent canvas. `--background
+transparent`, `--format png`, `--width`, `--height`, `--samples`, `--quality`
+and `--fill` override the defaults for a one-off.
+
+## File map
+
+Every shot is taken from one of the machine layouts in
+[`playground/src/configs.ts`](../../playground/src/configs.ts) — closed,
+buildable tracks with the infeed modules, station stops and zones where a real
+line would have them, rather than the calibration chains that visit every
+module type in one run. A unit test pins that each layout closes.
+
+| File                        | Demo key          | Camera         | Shows                                             |
+| --------------------------- | ----------------- | -------------- | ------------------------------------------------- |
+| `01-packaging-line.webp`    | `line-standard`   | 3⁄4 isometric  | hero — 5 m racetrack, 10 movers                   |
+| `02-standard-at.webp`       | `line-standard`   | steep 3⁄4      | Standard AT: AT2001 / AT2000 / AT2050             |
+| `03-eco-at2200.webp`        | `line-eco`        | 3⁄4 isometric  | Eco AT2200 / AT2202                               |
+| `04-nct-tools.webp`         | `line-nct`        | 3⁄4 isometric  | NCT modules + AT8200 tool carriers                |
+| `05-hygienic-ath.webp`      | `line-hygienic`   | 3⁄4 isometric  | Hygienic ATH                                      |
+| `06-hepco-gfx.webp`         | `line-standard` ¹ | 3⁄4 isometric  | Hepco GFX2 rail and carriage                      |
+| `07-materials-closeup.webp` | `line-standard`   | close, low     | PBR materials, stator packs, type plate           |
+| `08-multi-track.webp`       | `line-dual`       | steep 3⁄4      | two lines placed with `trackTransform`            |
+| `09-stations-areas.webp`    | `line-standard`   | steep 3⁄4      | stations, stops, ghost movers, zones              |
+| `10-dimensions.webp`        | `line-standard`   | steep 3⁄4      | dimensions along the track                        |
+| `11-stator-heatmap.webp`    | `line-standard`   | steep 3⁄4      | green → red gradient along the centerline         |
+| `12-collision.webp`         | `line-standard`   | close 3⁄4      | two movers parked at a 1 mm overlap               |
+| `13-drive-status.webp`      | `drive-status`    | steep 3⁄4      | warning / error icons + tinted modules and movers |
+| `14-feed-segments.webp`     | `line-standard`   | steep 3⁄4      | one strand per infeed, wrapping the loop seam     |
+| `15-measurements.webp`      | `line-standard`   | steep 3⁄4      | distance with ΔX/ΔY guides + two annotations      |
+| `16-selection.webp`         | `line-standard`   | steep 3⁄4      | two modules and one mover selected                |
+| `17-plan-view.webp`         | `line-standard`   | top-down ortho | `exportScreenshot({ mode: 'top-down' })`          |
+| `18-shadows.webp`           | `line-standard`   | low 3⁄4        | PCF-soft shadows + IBL                            |
+| `19-perf-stress.webp`       | `perf-stress`     | steep 3⁄4      | 3 ovals × 250 movers = 750                        |
+
+¹ with `railSystem: 'HepcoGfx'` and a GFX2 1TC carriage.
+
+The shot list itself lives at the top of the capture script; adding an image
+means adding one entry there, not writing browser code.
+
+## Doing it by hand
+
+The playground still exposes the devtools handles the script drives, so a
+one-off shot needs no tooling:
+
+1. `pnpm dev`, pick the demo from the sidebar, frame the camera.
+2. In the console:
 
    ```js
    const r = await window.__viewer.exportScreenshot({
-     mode: 'current', // or 'top-down'
-     pixelRatio: 2,
-     format: 'png',
-     backgroundColor: null, // transparent
+     mode: 'current',
+     width: 1920,
+     height: 1080,
+     samples: 4,
+     format: 'webp',
+     quality: 0.92,
+     backgroundColor: '#eef0f3',
    });
-   await fetch('/__save-screenshot?path=docs/screenshots/02-multi-track.png', {
+   await fetch('/__save-screenshot?path=docs/screenshots/08-multi-track.webp', {
      method: 'POST',
      body: r.blob,
-     headers: { 'content-type': 'image/png' },
+     headers: { 'content-type': 'image/webp' },
    });
    ```
 
-**Automated** (re-shoot the whole gallery): drive the same loop over the
-demo keys below from any browser-automation tool (Claude Preview / in
-Chrome MCP, Playwright, …). Switch with `window.__setDemo('<key>')`,
-wait ~2 s for GLBs + initial frame, then call the eval above.
-
-## File map
-
-| File                       | Demo key                          | Camera         | Notes                                                                        |
-| -------------------------- | --------------------------------- | -------------- | ---------------------------------------------------------------------------- |
-| `01-oval-loop.png`         | `oval-loop`                       | 3⁄4 isometric  | hero shot, env reflections on                                                |
-| `02-multi-track.png`       | `multi-track`                     | 3⁄4 isometric  | shows `trackTransform` placement                                             |
-| `03-stations-areas.png`    | `areas`                           | 3⁄4 isometric  | cleanroom / safety-loop tubes                                                |
-| `04-stator-heatmap.png`    | `heatmap`                         | 3⁄4 isometric  | green → red gradient, `displacementMm: 35` lifts the tube above the rail     |
-| `05-collision.png`         | `collision`                       | 3⁄4 isometric  | two movers touching mid-track                                                |
-| `06-drive-status.png`      | `drive-status`                    | 3⁄4 isometric  | pulsing emissives + ▲ / ⊙ status icons                                       |
-| `07-perf-stress.png`       | `perf-stress`                     | wide isometric | 3 ovals × 250 movers = 750                                                   |
-| `08-shadows.png`           | `standard` + shadows on           | low-angle      | PCF-soft shadows + IBL                                                       |
-| `09-screenshot-export.png` | `oval-loop`                       | top-down ortho | demonstrates `exportScreenshot('top-down')` itself                           |
-| `10-feed-segments.png`     | `eco` + both feed segments ticked | 3⁄4 isometric  | `feedSegmentHighlights` — strand 0 blue, strand 1 pink (wraps the loop seam) |
-
-All PNGs are RGBA with a transparent alpha channel, captured at
-`pixelRatio: 2` (~3000 × 2400 px) so they stay crisp at 1× and shrink
-cleanly to the README's two-column gallery rendering.
+`window.__setDemo('<DemoKey>')` switches the sample, `window.__playground`
+holds the sidebar toggles the script uses (shadows, stations, dimensions,
+selection, feed-segment colours, …) and the dev-only `POST
+/__save-screenshot?path=…` middleware in
+[`vite.config.ts`](../../vite.config.ts) writes the body bytes to a
+whitelisted path under `docs/screenshots/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beckhoff-xts-viewer-3d",
-  "version": "5.2.0",
+  "version": "5.2.2",
   "description": "Reusable React component for rendering Beckhoff XTS linear-motor systems in 3D using Three.js",
   "keywords": [
     "xts",
@@ -38,7 +38,7 @@
   },
   "files": [
     "dist",
-    "docs/screenshots/*.png",
+    "docs/screenshots/*.webp",
     "README.md",
     "LICENSE"
   ],
@@ -57,6 +57,7 @@
     "sync-assets-cdn-version": "node scripts/sync-assets-cdn-version.mjs",
     "dev": "vite",
     "playground:build": "vite build",
+    "docs:capture-screenshots": "node scripts/capture-screenshots.mjs",
     "docs:copy-screenshots": "node scripts/docs-copy-screenshots.mjs",
     "docs:dev": "pnpm run docs:copy-screenshots && vitepress dev docs",
     "docs:build": "pnpm run docs:copy-screenshots && vitepress build docs",
@@ -175,6 +176,7 @@
       "esbuild"
     ],
     "//-overrides": "Transitive dev-only dependencies pinned forward to their patched releases so `pnpm audit` stays clean. None of these reach the published bundle — dist/ contains only src/ with the peer deps externalised. Keyed by major where several majors coexist in the tree. Drop an entry once every direct dependency has caught up on its own.",
+    "//-overrides-vite": "vite@5 is the one entry that crosses a major: vitepress 1.6.4 depends on vite ^5.4.14, and the fs.deny / path-traversal / launch-editor advisories are only fixed from 6.4.2 onward — the 5.x line ends at 5.4.21 with no patch. Verified against this combination: docs:dev serves, docs:build and docs:build:all both complete. Drop it for a plain vitepress bump as soon as vitepress 2 leaves alpha, since 2.x is on vite 6+ on its own.",
     "overrides": {
       "brace-expansion@2": "^2.1.4",
       "esbuild@0.21": "^0.25.12",
@@ -185,7 +187,8 @@
       "sharp": "^0.35.0",
       "tmp": "^0.2.7",
       "undici@6": "^6.27.0",
-      "undici@7": "^7.29.0"
+      "undici@7": "^7.29.0",
+      "vite@5": "^6.4.3"
     }
   }
 }