@plasius/gpu-demo-viewer 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -18,6 +18,54 @@ The format is based on Keep a Changelog and this project adheres to SemVer.
 - **Security**
   - (placeholder)
 
+## [0.1.6] - 2026-10-14
+
+- Bind fixed progressive/UHD model review to published renderer and shared inspection APIs; retain experimental adaptive controls in their qualification branch.
+
+- Add exact Full HD, QHD and 4K UHD model-review presets, one-sample inspection and aspect-preserving canvas presentation.
+
+- Model-library sample target, bounce, resolution and denoising controls with progressive still-camera refinement and completed-sample progress.
+
+- **Added**
+  - Local model-library review with eleven acquired fixtures, including the manually supplied Medieval house GLB, source credits, integrity manifests, shared camera inspection and explicit visual-defect/deferred states.
+
+- **Changed**
+  - Refreshed compatible @plasius/* lockfile resolutions to the latest published releases.
+ - Routed trusted validation through the organization-owned quarantined
+    self-hosted runner group while continuing to reject fork pull-request code.
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+## [0.1.5] - 2026-08-31
+
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - Restored exact-main npm publication on a GitHub-hosted runner through
+    short-lived OIDC, with an enforced Node/npm runtime and no long-lived
+    write-token fallback.
+  - Routed pull-request validation to isolated GitHub-hosted capacity while
+    retaining exact-main push validation on fixed self-hosted Linux runners.
+  - Refreshed GPU runtime dependencies to the currently published renderer,
+    shared-contract, and XR package versions so clean release installs remain
+    reproducible.
+  - Made cross-repository manifest validation compare against a committed GPU
+    demo target inventory in canonical checkouts, worktrees, and hosted CI.
+  - (placeholder)
+
+- **Fixed**
+  - Peeled existing annotated release tags to their target commits before
+    exact-main recovery comparisons.
+
+- **Security**
+  - (placeholder)
+
 ## [0.1.4] - 2026-08-30
 
 - **Added**
@@ -137,3 +185,5 @@ The format is based on Keep a Changelog and this project adheres to SemVer.
 [0.1.2]: https://github.com/Plasius-LTD/gpu-demo-viewer/releases/tag/v0.1.2
 [0.1.3]: https://github.com/Plasius-LTD/gpu-demo-viewer/releases/tag/v0.1.3
 [0.1.4]: https://github.com/Plasius-LTD/gpu-demo-viewer/releases/tag/v0.1.4
+[0.1.5]: https://github.com/Plasius-LTD/gpu-demo-viewer/releases/tag/v0.1.5
+[0.1.6]: https://github.com/Plasius-LTD/gpu-demo-viewer/releases/tag/v0.1.6

package/NFR.md

@@ -30,3 +30,7 @@ entry surfaces.
 - This viewer is intentionally non-user-facing runtime infrastructure.
 - Baseline operations are governed by the parent feature flag:
   `platform.repo-hardening-sweep.enabled`.
+
+## Model library review
+
+Inherits `gpu-demo.scene-fidelity.enabled` with a localhost-only fixture override. Model changes abort prior work and release its GPU resources. Downloads use trusted reviewed hosts, no redirects, strict byte/hash limits and bounded concurrency. Preserve source licences. Keep missing downloads and renderer defects visible. Keyboard, touch, reduced-motion and 320px layouts must remain usable.

package/README.md

@@ -1,5 +1,12 @@
 # @plasius/gpu-demo-viewer
 
+[![npm version](https://img.shields.io/npm/v/@plasius/gpu-demo-viewer.svg)](https://www.npmjs.com/package/@plasius/gpu-demo-viewer)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Plasius-LTD/gpu-demo-viewer/ci.yml?branch=main&label=build&style=flat)](https://github.com/Plasius-LTD/gpu-demo-viewer/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/Plasius-LTD/gpu-demo-viewer)](./LICENSE)
+[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-yes-blue.svg)](./CODE_OF_CONDUCT.md)
+[![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
+[![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)
+
 Static root-level launcher for validating the `gpu-*` package demos from one place.
 
 ## Purpose
@@ -126,3 +133,36 @@ npm test
 - Delivery workflow: [`WORKFLOW.md`](./WORKFLOW.md)
 - Feature flags and capabilities: [`FLAGS_AND_CAPABILITIES.md`](./FLAGS_AND_CAPABILITIES.md)
 - Architectural decision log: [`docs/adrs/index.md`](./docs/adrs/index.md)
+<!-- BEGIN PLASIUS RELEASE INTEGRITY -->
+## Release integrity
+
+Production package publication runs only from `.github/workflows/cd.yml` on
+protected `main`. The job verifies that the prepared commit is still the
+current main commit and has an exact successful `ci.yml` push result before it
+mutates release state. Same-repository pull requests and exact-main pushes use
+the organization-owned `Public CI - Quarantined` runner group with fixed
+self-hosted Linux labels; fork code is not admitted to that trusted runner
+boundary. npm publication runs on
+GitHub-hosted Node.js 24 with
+npm 11.5.1 or newer, uses the protected `production` environment and
+short-lived npm OIDC with provenance, and has no long-lived npm write-token
+fallback. Rollback disables CD; it never rewrites published package history.
+<!-- END PLASIUS RELEASE INTEGRITY -->
+
+## Model library review
+
+`npm run models:download` installs the ten reviewed, freely licensed Poly Haven and Khronos fixtures from `model-library/catalogue.json`, including all buffer/image dependencies. Downloads are bounded and SHA-256 checked; binaries are ignored by Git and npm. `npm run models:dev` opens the localhost server on port 5291. Visit `http://127.0.0.1:5291/?review=first-twelve`. The Medieval house is a manually supplied eleventh asset; only Gem remains deferred. Source links, creators and licences are available beside each model.
+
+For Medieval house, obtain the original GLB from its credited Sketchfab source and place it at `model-library/assets/sf-house/medieval_house.glb`, then run `npm run models:download` to verify its pinned size and SHA-256 and write its credits. This command never downloads manual assets; a missing file produces an explicit placement message. The catalogue stores no private local paths.
+
+This page consumes the shared model-inspection package entrypoint. While its upstream release is pending, development testing can set `PLASIUS_SHARED_INSPECTION_SOURCE` to an absolute path to the reviewed sibling `src/model-inspection.js`; this explicit source override is for localhost development only, not a released dependency or production deployment.
+
+Mouse/touch/keyboard inspection reuses the material-study camera. The view progressively refines while the camera is still, stopping at the selected sample target. `Home` restores framing and `?` displays a brief gesture reminder. Resizing updates resolution while preserving the camera. Fox is static here; its Survey, Walk and Run clips remain in the original download. Amber currently exposes a visible transmission/volume rendering defect. See `docs/model-library-review.md` for the initial findings; none of these fixtures is implicitly approved for the production showcase.
+
+Render-quality controls select 8–256 total samples, 2–12 light bounces, 480/800/1280px render width and denoising. Defaults are 64/6/800/on. The first pass is one sample; idle refinement adds up to four samples per batch. Camera and quality changes restart history. Hidden tabs pause further work; the progress bar reports completed samples and actual dimensions. Settings do not reload the source model.
+
+During upstream progressive-renderer development, also set `PLASIUS_RENDERER_SOURCE` to an absolute reviewed `src/index.js` or built `dist/index.js`. Both source overrides are development-only; PRs remain dependency-blocked until approved package CD and final released-version validation. To use another local port: `npm run models:dev -- --port 5292`.
+
+The model review includes native 1920 × 1080, 2560 × 1440 and 3840 × 2160 quality presets. These trace the exact selected pixel dimensions independently of viewport size; the canvas contains the image without stretching. A one-sample target supports quick full-resolution checks. See [UHD inspection design](docs/model-inspection-uhd.md).
+
+The released model review uses fixed progressive sampling with native UHD sizes and requires renderer0.2.49/shared1.1.7 or newer. Adaptive controls remain in a separate qualification branch. See [release scope](docs/model-review-release.md); the local inspection catalogue explicitly retains unresolved visual findings.

package/docs/adrs/adr-0002-hosted-oidc-package-publication.md

@@ -0,0 +1,53 @@
+# ADR-0002: Hosted OIDC package publication
+
+- Status: Accepted
+- Date: 2026-08-09
+
+## Context
+
+npm trusted publishing accepts GitHub Actions only from GitHub-hosted runners.
+The previous `gpu-demo-viewer` release job selected self-hosted infrastructure and
+required a long-lived npm write token. That prevented the package from using
+its configured trusted-publisher binding and left release availability coupled
+to a reusable credential.
+
+The parent rollout control is
+`platform.public-artifact-integrity.enabled`. It governs staged release
+restoration but cannot bypass source, CI, package, or publication integrity
+checks. No product capability is introduced.
+
+## Decision
+
+Publication is phase-isolated: dependency installation, package validation, SBOM generation, and immutable tarball packing run in `validate_and_pack` without the `production` environment or OIDC permission. The final hosted `publish` job downloads only that sealed artifact, explicitly installs npm 11.6.2, runs no repository dependency code, and publishes the tarball with lifecycle scripts disabled. It re-fetches current `main` immediately before the first release mutation and again immediately before npm publication. `.npmrc` contains no registry-auth placeholder, and release preparation returns the reviewed current `main` HEAD rather than package-file history.
+
+The final npm publication job in `.github/workflows/cd.yml`:
+
+1. runs on the literal `ubuntu-latest` GitHub-hosted runner;
+2. remains bound to protected `main` and the GitHub `production`
+   environment;
+3. verifies that the prepared commit still equals remote `main` and that an
+   exact-SHA `ci.yml` push run completed successfully;
+4. verifies Node.js 24 and npm 11.5.1 or newer before publication;
+5. receives least-privilege `id-token: write` and publishes only through npm
+   OIDC with provenance; and
+6. has no `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or long-lived write-token
+   fallback.
+
+The external npm trusted publisher is bound exactly to organization
+`Plasius-LTD`, repository `gpu-demo-viewer`, workflow `cd.yml`, environment
+`production`, and action `npm publish`.
+
+## Consequences
+
+- A moved main branch, absent exact-SHA CI result, unsupported runtime, missing
+  trusted-publisher binding, or OIDC failure stops publication before npm
+  mutation.
+- Same-repository pull-request and exact-main push validation use the
+  organization-owned `Public CI - Quarantined` runner group with fixed
+  self-hosted Linux labels and no caller-controlled runner selection. Fork code
+  is rejected before that boundary. The narrow npm publication boundary remains
+  hosted.
+- Releases use short-lived workflow identity and retain npm provenance without
+  a reusable write credential.
+- Rollback disables `cd.yml` or the release-integrity flag. Published package
+  history, tags, and registry versions are never rewritten or deleted.

package/docs/adrs/adr-0003-reviewed-model-library.md

@@ -0,0 +1,13 @@
+# ADR 0003: Reviewed model library
+
+Status: Accepted for local inspection.
+
+The viewer acquires the exact first-twelve shortlist with pinned provenance, file sizes and SHA-256 hashes. Eleven are available: ten automatic downloads and the user-supplied Medieval house GLB. Gem remains deferred. Asset binaries remain outside Git and npm. `models:download` retrieves only the reviewed Poly Haven and pinned Khronos URLs, with two workers, sixty-second requests, no redirects and a 200 MiB aggregate budget. Existing files must match the manifest. Credits travel with each installed model.
+
+Manual files have `acquisition: "manual"` and no download URL in the file record. Acquisition verifies their installed bytes and checksum exactly as it does automatic downloads; a missing manual file produces an actionable local destination message without a network request. User download paths are never stored in the catalogue. This supports supplied files without expanding the approved remote-source allowlist or attempting authenticated downloads.
+
+Rendering, glTF decoding, material projection and input gestures belong to the shared `model-inspection` package entry. The viewer owns selection, cancellation, readable errors, credits and review observations. It does not replace missing assets or apply the chest-specific ageing system indiscriminately. Only one model is active. Resize remounts a bounded render target; hidden/missing assets have explicit states.
+
+The parent control is `gpu-demo.scene-fidelity.enabled`. This validation surface uses the explicit localhost-only `?review=first-twelve` override. It adds no production route or entitlement. Product integration must use the remote flag and existing route capabilities. Rollback: omit the query override, stop the local server, or revert the viewer entry.
+
+Tests cover acquisition rejection/integrity, rapid selection races, cleanup, missing assets, source credits, static-animation caveats and disabled state. Browser screenshots and review notes distinguish files loaded from visual fidelity achieved.

package/docs/adrs/adr-0004-model-quality-controls.md

@@ -0,0 +1,13 @@
+# ADR 0004: Model-library quality controls
+
+Accepted for implementation, 2026-10-14. Parent Feature Plasius-LTD/plasius-ltd-site#1170, Story #2303, viewer Task #58. Inherited flag `gpu-demo.scene-fidelity.enabled`; the existing localhost review override remains the only exposure in this delivery.
+
+The viewer supplies semantic native controls for sample target, bounce depth, render width and denoising. gpu-shared owns camera/renderer lifecycle and idle scheduling; gpu-renderer accumulates linear samples before presentation. No duplicate rendering implementation lives here. The sample counter reflects GPU-completed work and the progress element has an accessible label. Controls reflow at 320px and inherit native keyboard/touch behavior. Quality changes retain the current camera and model; document visibility pauses refinement.
+
+Default: 64 samples, six bounces, 800px width and denoising. Width options 480/800/1280 preserve the visible canvas aspect ratio within the shared 1440px dimension bound. GPU work stops at the selected target. Source credits, deferred assets and known defects remain visible.
+
+`PLASIUS_RENDERER_SOURCE` permits an explicit absolute development entrypoint alongside the shared source override, only on the localhost development server. Published dependencies must replace both overrides after approved upstream CD. No production route or capability is added. Rollback removes the review query/overrides or disables the inherited remote flag in public hosts.
+
+## UHD extension (2026-10-14)
+
+Add exact HD/QHD/UHD presets alongside viewport-shaped widths. Fixed presets do not change on viewport resize. Use contained presentation to avoid stretching and retain exact traced dimensions in the progress label. Shared admission caps the total at UHD pixels. See [design](../model-inspection-uhd.md).

package/docs/adrs/index.md

@@ -3,3 +3,6 @@
 ## Scene and Governance ADRs
 
 - [ADR 0001: Define static viewer governance baseline and build checks](./adr-0001-gpu-demo-viewer-governance-baseline.md)
+- [ADR-0002: Hosted OIDC Package Publication](./adr-0002-hosted-oidc-package-publication.md)
+
+- [ADR 0003: Reviewed model library](adr-0003-reviewed-model-library.md)

package/docs/model-inspection-uhd.md

@@ -0,0 +1,11 @@
+# Model inspection at UHD resolution
+
+Parent Feature: Plasius-LTD/plasius-ltd-site#1170; Story #2303; shared Task #143; viewer Task #58. Inherited flag `gpu-demo.scene-fidelity.enabled`; explicit localhost review override only.
+
+Add exact 1920×1080, 2560×1440 and 3840×2160 render targets alongside existing viewport-shaped quick sizes. UHD is actual traced pixels, independent of browser DPR or CSS size. Preserve aspect using contained canvas presentation. Shared quality admission accepts dimensions up to 3840 with a total cap of 3840×2160 pixels. Reject oversized inputs before resource allocation; do not silently downscale. Existing renderer adapter/storage admission remains authoritative. At UHD, progressive float32 history is 132,710,400 bytes plus a 16-byte count uniform, below the default 128 MiB binding limit; other textures and scene resources are additional.
+
+Preserve single-flight scheduling, camera state, visible GPU errors, cancellation and cleanup. Expose a one-sample option for expensive full-resolution inspection. Test native dimensions, viewport independence of fixed presets, aspect-preserving display, pixel-budget admission and reset/cleanup. Validate a real 4K frame and changed-source LCOV before delivery.
+
+Adaptive per-pixel integration depends on renderer Task #173 (canonical configuration/statistics API), shared Task #118 (forwarding contract) and the experimental runtime in renderer PR #216. The current native adaptive runner is a diagnostic harness that intercepts GPU resource creation; the public compute renderer has no adaptive option. Do not import this test harness into the showcase, label uniform batches as per-pixel adaptive sampling, or enable the default-off `renderer.sampling.adaptivePerPixel.enabled` flag. Qualification and API integration remain open in the adaptive workstream; this resolution change is independent. Existing fixed SPP progressive rendering remains the available mode.
+
+Validation: requirements-first tests failed on the old size bounds/preset parsing and on redundant history resets. The corrected runtime preserves completed history when identical settings are reapplied (including fixed-preset viewport changes). Physical browser validation completed one and eight samples at actual canvas size 3840×2160, six bounces, denoising on; 320px layout retained native dimensions with no horizontal overflow. This is output/interaction validation, not a 60 Hz or image-quality qualification. No production rollout or upstream package release is claimed.

package/docs/model-library-review.md

@@ -0,0 +1,38 @@
+# First model review — 13 October 2026
+
+Eleven original assets are installed with 56 verified files (70,599,653 bytes, about 67.3 MiB). The first-twelve shortlist remains intact; the user supplied Medieval house after the initial ten-model review. Only Gem remains deferred. Files and credits remain in `model-library/assets/`; `catalogue.json` records their source URLs, exact sizes and SHA-256 checksums. Source files have not been altered.
+
+The initial review used the Plasius wavefront renderer at eight samples per pixel and six bounces, with shared glTF import and camera gestures. Geometry is uniformly normalized to the inspection frame. It has no model-specific ageing or environment staging. “Rendered” is not a visual-fidelity approval.
+
+| Model | Rendered triangles | Result / next improvement |
+|---|---:|---|
+| Large Castle Door | 12,640 | Geometry and weathered textures render. Improve separation of iron and wood under varied lighting. |
+| Medieval house | 83,046 | User-supplied original GLB renders with six mesh primitives and five materials. Roof, timber and stone textures are present; dark recesses and sampling noise need a lighting pass. Attribution to Vanuartw and CC BY 4.0 are retained. |
+| Fern 02 | 6,232 | Four clumps render. Source materials are opaque; this fixture alone does not prove alpha-mask support. Inspect backlighting and small-leaf shading. |
+| Quiver Tree 01 | 150,124 | Trunk and foliage render; the heaviest geometry in this pass. Review LOD selection, fine-leaf shading and responsiveness. |
+| Rock Moss Set 01 | 63,127 | Six rock primitives render. Need per-rock framing and ground-contact lighting for presentation. |
+| Garden Gloves 01 | 6,822 | Fabric/rubber colour and detail render. No fibre groom is authored; region masks and cloth shading need a later pass. |
+| Wooden Crate 02 | 5,176 | Wood and rope detail render. The original chest’s wear/fray masks are deliberately not applied to a different mesh. |
+| Bronze Whale Statue | 3,816 | Geometry and patina render, but metal reads too flat under this lighting. Needs reference comparisons and better reflected surroundings. |
+| Antique Ceramic Vase 01 | 9,408 | Pattern and silhouette render; glaze appearance and visible sampling noise need improvement. |
+| Mosquito In Amber | 14,349 | **Visual defect:** almost-black surface and horizontal bands. Investigate transmission, volume scaling and the renderer path before public use. |
+| Fox | 576 | Static textured mesh renders. Survey, Walk and Run clips are retained but not played by this importer. |
+
+## Priorities exposed
+
+1. Amber transmission/volume correctness and banding. Use this unchanged fixture as a regression case; do not replace its material to hide the defect.
+2. Cleaner sampling and controlled environment/reflection lighting. Noise and low material contrast are visible across several models.
+3. Skinning and source-animation playback for Fox; bone transforms must be verified before motion can be claimed.
+4. Per-object framing for sets, grounded presentation and model-specific ageing/fibre masks.
+
+## Validation and limits
+
+All eleven were selected and visually inspected in the local browser. Desktop, 320px reflow, visible load/deferred states and keyboard inspection are checked. Shared camera unit coverage exercises mouse and multitouch handling; physical touchscreen hardware and screen-reader speech were not tested. This is not a WCAG or visual-quality certification. Browser captures are retained with the local review output.
+
+Local validation passed: 33 viewer tests, 100% changed-source line coverage (97.7% overall measured branches), lint/type checks, build, package checks and a dependency audit with zero reported vulnerabilities. The shared runtime passed 177 tests; its two added source modules have 100% line coverage. The package dry run excludes downloaded asset binaries. Keyboard orbit, approach and Home reset were visually checked; the final browser error log was empty.
+
+No production route or entitlement was changed. The shared-package release and consumer final dependency pin remain blocked while the organisational runners are offline. The consumer PR must stay draft until the upstream package is published, its dependency is updated and the published runtime is revalidated. See ADR 0003 for the local-only rollout and rollback controls.
+
+## Progressive quality review (2026-10-14)
+
+The preview now defaults to a 64-sample target, six bounces, 800px width and denoising. Quality controls adjust all four, retain the camera and restart accumulation. It refines unfiltered linear radiance in bounded GPU batches while still and pauses when hidden. Existing model findings above describe the initial eight-sample review; higher sampling does not resolve importer, material or animation defects automatically. Upstream renderer/shared releases and final package-pin validation are still required before publication.

package/docs/model-review-release.md

@@ -0,0 +1,11 @@
+# Fixed progressive model review release
+
+Task #58 / Story Plasius-LTD/plasius-ltd-site#2303 / Feature #1170. Release the existing reviewed acquisition catalogue, static-model inspection journey and fixed quality controls (samples, bounces, denoising, native UHD). Use published renderer0.2.49 and shared1.1.7; no local source aliases are part of the package dependency contract.
+
+The localhost `?review=first-twelve` opt-in remains limited to local development. The website uses its separate server-side rollout and capability projection; the local viewer is not a production access-control mechanism. Adaptive controls from draftPR59 remain unreleased pending renderer qualification. This staged release does not close those open requirements.
+
+The catalogue retains eleven acquired assets and one deferred Gem with exact source/licence/hash records; binaries remain acquired separately and are excluded from npm. Known visual findings remain visible, including amber transport banding and static-only Fox. Do not label the local review catalogue a visual approval. Validate tests/coverage, changed-source LCOV, syntax/build/package integrity, exact-head CI and approved main/production CD before publication.
+
+## Acquisition review
+
+CodeQL alert 3 (`js/file-access-to-http`) traces the checked-in `model-library/catalogue.json` URL into the fixture downloader. This is intentional inbound asset acquisition, not transmission of local asset contents: the request is a GET without a body or file-derived headers, its HTTPS host is checked against `dl.polyhaven.org` and `raw.githubusercontent.com`, and redirects are rejected. Existing file contents are used only for local size/SHA-256 verification; manual assets never make network requests. The catalogue is public package content and contains reviewed source URLs, not credentials. Existing acquisition regressions cover rejected hosts/protocols, destination traversal, byte/hash bounds and manual-file network exclusion. The alert therefore does not demonstrate information disclosure. No scan rule or security gate is disabled.

package/model-library/acquire.js

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, relative, isAbsolute } from 'node:path';
+
+export function acquisitionPlan(assets, root) {
+  const plan=[];let total=0;
+  for(const asset of assets) {
+    if(!asset.entry) continue;
+    for(const file of asset.files) {
+      if(file.acquisition==='manual') {
+        if(file.url!==undefined)throw new Error('Manual asset must not specify a download URL.');
+      } else {
+        const url=new URL(file.url);
+        if(url.protocol!=='https:' || !['dl.polyhaven.org','raw.githubusercontent.com'].includes(url.hostname)) throw new Error('Unapproved asset source.');
+      }
+      const path=resolve(root,asset.key,file.path),rel=relative(resolve(root),path);
+      if(!rel || rel.startsWith('..') || isAbsolute(rel)) throw new Error('Unsafe asset destination.');
+      if(!Number.isSafeInteger(file.bytes)||file.bytes<1||file.bytes>100*1048576||!/^[a-f0-9]{64}$/.test(file.sha256)) throw new Error('Invalid asset bounds or hash.');
+      total+=file.bytes;
+      if(total>200*1048576) throw new Error('Fixture set exceeds the download budget.');
+      plan.push({...file,path,asset});
+    }
+  }
+  return plan;
+}
+export async function acquireFixtures({assets,root,fetch:request=globalThis.fetch}) {
+  const plan=acquisitionPlan(assets,root);
+  const verify=(file,data)=>data.length===file.bytes && createHash('sha256').update(data).digest('hex')===file.sha256;
+  // Two sequential workers keep network and memory use bounded.
+  let cursor=0;
+  async function worker() {
+    while(cursor<plan.length) {
+      const file=plan[cursor++];let existing;
+      try{existing=await readFile(file.path);}catch(error){if(error.code!=='ENOENT')throw error;}
+      if(existing){if(!verify(file,existing))throw new Error(`Existing file failed integrity: ${file.asset.key}`);continue;}
+      if(file.acquisition==='manual')throw new Error(`Manual asset required: ${file.asset.key}. Place the reviewed file at ${file.path} and retry.`);
+      const response=await request(file.url,{redirect:'error',signal:AbortSignal.timeout(60000),headers:{'User-Agent':'Plasius-Renderer-Asset-Research/1.0 (https://plasius.co.uk)'}});
+      if(!response.ok)throw new Error(`Asset download failed: ${response.status}`);
+      const reader=response.body.getReader(),chunks=[];let length=0;
+      try{while(true){const {done,value}=await reader.read();if(done)break;length+=value.length;
+        if(length>file.bytes)throw new Error('Downloaded file exceeds its reviewed byte size.');chunks.push(value);}}
+      finally{await reader.cancel();}
+      const data=Buffer.concat(chunks);
+      if(!verify(file,data))throw new Error(`Downloaded file failed integrity: ${file.asset.key}`);
+      await mkdir(resolve(file.path,'..'),{recursive:true});await writeFile(file.path,data,{flag:'wx'});
+    }
+  }
+  const results=await Promise.allSettled([worker(),worker()]);
+  const failure=results.find(r=>r.status==='rejected');if(failure)throw failure.reason;
+  for(const asset of assets.filter(a=>a.entry)) {
+    await writeFile(resolve(root,asset.key,'CREDITS.txt'),`${asset.name} — ${asset.authors}\n${asset.source_url}\n${asset.licence}\n${asset.licence_url}\nSource files unchanged; runtime framing only.\n`);
+  }
+  return {models:assets.filter(a=>a.entry).length,files:plan.length,bytes:plan.reduce((n,f)=>n+f.bytes,0)};
+}