@plasius/gpu-demo-viewer 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -18,6 +18,34 @@ The format is based on Keep a Changelog and this project adheres to SemVer.
 - **Security**
   - (placeholder)
 
+## [0.3.0] - 2026-10-21
+
+- **Added**
+  - Typed, data-only composite study definitions for host applications, sharing the four workshop arrangements without copying placements.
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+## [0.2.3] - 2026-10-21
+
+- **Added**
+  - Relic collection and tool-chest composite studies using five credited originals each, with shared camera and render-quality controls.
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
 ## [0.2.2] - 2026-10-21
 
 - **Added**
@@ -323,3 +351,5 @@ The format is based on Keep a Changelog and this project adheres to SemVer.
 [0.2.0]: https://github.com/Plasius-LTD/gpu-demo-viewer/releases/tag/v0.2.0
 [0.2.1]: https://github.com/Plasius-LTD/gpu-demo-viewer/releases/tag/v0.2.1
 [0.2.2]: https://github.com/Plasius-LTD/gpu-demo-viewer/releases/tag/v0.2.2
+[0.2.3]: https://github.com/Plasius-LTD/gpu-demo-viewer/releases/tag/v0.2.3
+[0.3.0]: https://github.com/Plasius-LTD/gpu-demo-viewer/releases/tag/v0.3.0

package/README.md

@@ -12,7 +12,7 @@ plus a workspace launcher for the `gpu-*` package demos. The workshop provides
 camera gestures, progressive rendering, quality controls and model credits.
 
 The npm package includes the viewer source, manifest and build-time acquisition
-helper. Model binaries are downloaded separately; they are not bundled in npm.
+helper and typed composite layout definitions. Model binaries are downloaded separately; they are not bundled in npm.
 
 ## Run the model workshop
 
@@ -63,15 +63,19 @@ or enabled on the production site. The download helper admits only configured
 resources and keeps two workers, a 100 MiB per-file limit and a 200 MiB batch limit.
 Source, creator, licence and review notes appear beside each model.
 
-Two composite studies appear after the individual models in **Choose a model or
-study**: a furnished interior and a workshop still life. They arrange four and
-five credited originals under shared lighting and one camera. They are additional
+Four composite studies appear after the individual models in **Choose a model or
+study**: a furnished interior, workshop still life, relic collection and tool-chest
+arrangement. They arrange four or five credited originals under shared lighting
+and one camera. They are additional
 views of existing models rather than additional source assets. Each
 study lists its sources, licences and chosen dimensions; these are static review
 arrangements, not verified physical-scale scenes. See the
 [composite study guide](https://github.com/Plasius-LTD/gpu-demo-viewer/blob/main/docs/composite-model-studies.md).
 Keep `?review=first-twelve` in the local URL and append
-`&model=study-furnished-interior` or `&model=study-workshop` to bookmark a study.
+`&model=study-furnished-interior`, `&model=study-workshop`,
+`&model=study-relic-collection` or `&model=study-tool-chest` to bookmark a study.
+The [relic and tool study guide](https://github.com/Plasius-LTD/gpu-demo-viewer/blob/main/docs/relic-and-tool-composites.md)
+describes the newer arrangements and their qualification.
 
 ## Camera and render quality
 
@@ -198,3 +202,26 @@ 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 -->
+
+## Reuse composite layouts
+
+Import the small data-only subpath to offer the workshop's four arrangements in
+another application:
+
+```ts
+import { compositeStudyDefinitions } from '@plasius/gpu-demo-viewer/model-library/studies';
+
+const layouts = compositeStudyDefinitions();
+const interior = layouts.find(layout => layout.key === 'study-furnished-interior');
+// Each placement is [sourceKey, bottomCentreAnchor, longestDimension, yawRadians].
+console.log(interior?.placements);
+```
+
+Every call returns independent arrays. The import performs no asset requests,
+DOM work or GPU allocation. Resolve each source key against your admitted asset
+catalogue and pass its URL, complete integrity map and placement to
+`createSceneInspection` from `@plasius/gpu-shared/model-inspection`. Omit a layout
+if any source is unavailable. Keep source licences/credits, translate the supplied
+review copy as needed, and enforce the host application's access controls before
+loading models. Dimensions are illustrative scene units. See the
+[host integration contract](https://github.com/Plasius-LTD/gpu-demo-viewer/blob/main/docs/public-composite-definitions.md).

package/docs/adrs/adr-0006-composite-study-consumer.md

@@ -19,3 +19,12 @@ browser review with the registry package before release.
 The existing scene-fidelity feature flag and route capability continue to govern
 hosted product access. This local review does not add public-site navigation or
 change the existing localhost review gate.
+
+## Host-consumer contract — 21 October 2026
+
+Story site#2321 / viewer Task #83 adds the typed `model-library/studies` subpath.
+A pure function returns fresh copies of the same four layout definitions used by
+the workshop. This keeps placement ownership here without coupling host apps to
+the workshop UI, catalogue loading or its localhost gate. Hosts resolve their
+own admitted sources and retain capability/rollout ownership. Shared inspection
+still owns all rendering and resource limits. The local gate remains unchanged.

package/docs/public-composite-definitions.md

@@ -0,0 +1,30 @@
+# Composite definitions for host applications
+
+Tracked work: site Story #2321 and viewer Task #83.
+
+Expose the four existing qualified arrangements through the typed package
+subpath `@plasius/gpu-demo-viewer/model-library/studies`. A pure
+`compositeStudyDefinitions()` function returns fresh definitions containing the
+stable key, source keys, bottom-centre anchors, longest dimensions, yaw and review
+copy. Extract the existing definitions without changing any value. The workshop
+and website then share one owner for placement.
+
+The module must import no renderer, DOM, acquisition helper or local-review
+bootstrap, and perform no I/O. Return independent arrays so consumer edits do not
+alter another call or the workshop. Hosts resolve keys against their own admitted
+catalogue, translate display copy, retain every credit/integrity entry, and apply
+their capability/feature controls before calling released shared scene inspection.
+The definitions are layout data, not entitlement decisions or additional models.
+
+Parent Feature site#1170 / Epic site#2271 and inherited flag
+`gpu-demo.scene-fidelity.enabled` apply. The local review gate stays unchanged;
+public access is governed by the website's existing studio capability and GPU
+runtime. Rollback uses those stored rules or reverts the consuming package version.
+
+Before implementation, require tests for the supported export, its type/file
+contract, exact unchanged scene membership and placement, isolated return values,
+and continued workshop composition. Keep existing rendering/credit tests. Update
+consumer README, Unreleased changelog and ADR0006. Run all package validation and
+coverage with changed-source LCOV, publish only through approved main/production
+CD after CI, and compare npm contents to the attested release artifact before
+the site consumes the new export.

package/docs/relic-and-tool-composites.md

@@ -0,0 +1,59 @@
+# Relic collection and tool-chest studies
+
+Tracked work: site Story #2316 and viewer Task #80.
+
+Extend the local model workshop with two arrangements of qualified originals
+from the 61-model catalogue. Reuse `gpu-shared` 1.2.0 `createSceneInspection`
+and renderer 0.2.54; ADR 0006 continues to apply. No new renderer, material
+substitution, asset acquisition or architecture boundary is required.
+
+The relic collection brings Gothic Statue, Marble Bust, Chess Set, Kite Shield
+and Antique Estoc into shared light to compare stone, carved detail and metal.
+The tool-chest arrangement brings Metal Tool Chest, Hand Plane, Vintage Hand
+Drill, Rusted Spade and Rusted Can together to compare painted metal, rust,
+wood and small contact shadows. Chosen dimensions and placement are illustrative,
+not surveyed physical dimensions. Both arrangements use the shared neutral floor.
+
+Feature site#1170 and Epic site#2271 govern this work. Inherit the remotely
+controlled `gpu-demo.scene-fidelity.enabled` flag and existing localhost-only
+review override. No public-site navigation is introduced by these local studies.
+Rollback is selection of an individual model, disabling the existing review
+entry, or reverting this viewer release; source originals remain available.
+
+Before implementation, test both exact source sets, complete integrity manifests,
+source attribution, safe incomplete-catalogue exclusion, and continued existing
+scene selection. Keep shared six-source, geometry and texture budgets unchanged.
+Exercise the existing shared camera, sampling, denoising, cancellation and cleanup
+through the viewer tests and real WebGPU review. Require fixed64, camera reset
+and refinement, denoising off/on, native UHD1, and a 320px reflow check. Record
+failures honestly; completed UHD1 is not optical or real-time qualification.
+
+Update consumer README and Unreleased changelog, maintain >=80% coverage and
+changed-source LCOV, and pass tests, types/lint, build, package and audit checks.
+Publish only through main `cd.yml` with the production environment after CI.
+Verify the exact npm artifact before closing tracked work. The separate site
+61-model deployment and original-model holds remain tracked independently.
+
+## Registry-based review, 21 October 2026
+
+Both arrangements rendered with released shared 1.2.0 and renderer 0.2.54,
+without source overrides. The relic collection has 140,669 triangles, 44 mesh
+primitives and eight source materials; the tool scene has 44,876 triangles,
+16 primitives and five materials. Both totals include the shared ground.
+
+Both completed fixed64 at 800 × 282, keyboard camera movement followed by
+refinement, denoising off/on and native 3840 × 2160 at one sample. Both returned
+to balanced resolution. At a 320px viewport each completed fixed64 at 800 × 601,
+with all five originals visible and no horizontal document overflow, including
+expanded source credits. The viewport was reset afterwards. Mouse orbit and
+keyboard Home were also checked on the relic arrangement.
+
+One DOM keyboard action immediately after viewport restoration exceeded the
+automation input deadline; the page remained responsive, native Home input
+restarted sampling and refinement completed. Quality changes still rebuild the
+scene for several seconds. No renderer console warnings/errors were recorded.
+These are functional static-scene checks, not reference optical fidelity,
+animation playback, physical-touch or screen-reader-speech qualification.
+
+All 59 viewer tests pass; line coverage and changed `scenes.js` coverage are
+100%. Types/lint, build, package validation and the full dependency audit pass.

package/model-library/scenes.js

@@ -1,31 +1,8 @@
 import { fixtureRequest } from './controller.js';
-
-const definitions = [
-  { key: 'study-furnished-interior', name: 'Furnished interior',
-    renderer_target: 'Compare woven fabric, silk, leather, wicker and aged wood in one arrangement.',
-    preparation: 'Inspect relative scale, fabric response and contact shadows. Sizes are chosen scene units, not verified physical dimensions.',
-    placements: [
-      ['SheenWoodLeatherSofa', [0, 0, -.8], 2.4, 0],
-      ['vintage_cabinet_01', [-2.15, 0, -.8], 1.7, 0],
-      ['SpecularSilkPouf', [.55, 0, .85], .7, 0],
-      ['wicker_basket_01', [1.6, 0, -.3], .6, 0],
-    ] },
-  { key: 'study-workshop', name: 'Workshop still life',
-    renderer_target: 'Compare worked metal, rough timber and worn surfaces under shared light.',
-    preparation: 'Inspect object contact and the contrast between brass, painted metal and timber. These are static review arrangements.',
-    placements: [
-      ['spinning_wheel_01', [-1.1, 0, -.65], 1.8, 0],
-      ['wine_barrel_01', [1.15, 0, -.7], 1.25, 0],
-      ['wooden_crate_02', [0, 0, .7], 1.2, 0],
-      ['bench_vice_01', [-1.3, 0, 1.05], .55, .3],
-      // Crate lid height from the original accessor bounds and lid translation,
-      // uniformly scaled to its chosen 1.2-unit longest dimension.
-      ['brass_blowtorch', [0, .47735, .7], .55, 0],
-    ] },
-];
+import { compositeStudyDefinitions } from './studies.js';
 
 export function compositeStudies(assets) {
-  return definitions.flatMap(({ placements, ...definition }) => {
+  return compositeStudyDefinitions().flatMap(({ placements, ...definition }) => {
     const models = placements.map(([key, anchor, size, yaw]) => ({
       asset: assets.find(a => a.key === key), anchor: [...anchor], size, yaw,
     }));

package/model-library/studies.d.ts

@@ -0,0 +1,10 @@
+/** Layout data only. Host applications own assets, credits and access decisions. */
+export interface CompositeStudyDefinition {
+  key: string;
+  name: string;
+  renderer_target: string;
+  preparation: string;
+  /** Source key, bottom-centre anchor, longest dimension in scene units, Y rotation in radians. */
+  placements: [string, [number, number, number], number, number][];
+}
+export function compositeStudyDefinitions(): CompositeStudyDefinition[];

package/model-library/studies.js

@@ -0,0 +1,51 @@
+const definitions = [
+  { key: 'study-furnished-interior', name: 'Furnished interior',
+    renderer_target: 'Compare woven fabric, silk, leather, wicker and aged wood in one arrangement.',
+    preparation: 'Inspect relative scale, fabric response and contact shadows. Sizes are chosen scene units, not verified physical dimensions.',
+    placements: [
+      ['SheenWoodLeatherSofa', [0, 0, -.8], 2.4, 0],
+      ['vintage_cabinet_01', [-2.15, 0, -.8], 1.7, 0],
+      ['SpecularSilkPouf', [.55, 0, .85], .7, 0],
+      ['wicker_basket_01', [1.6, 0, -.3], .6, 0],
+    ] },
+  { key: 'study-workshop', name: 'Workshop still life',
+    renderer_target: 'Compare worked metal, rough timber and worn surfaces under shared light.',
+    preparation: 'Inspect object contact and the contrast between brass, painted metal and timber. These are static review arrangements.',
+    placements: [
+      ['spinning_wheel_01', [-1.1, 0, -.65], 1.8, 0],
+      ['wine_barrel_01', [1.15, 0, -.7], 1.25, 0],
+      ['wooden_crate_02', [0, 0, .7], 1.2, 0],
+      ['bench_vice_01', [-1.3, 0, 1.05], .55, .3],
+      // Crate lid height from the original accessor bounds and lid translation,
+      // uniformly scaled to its chosen 1.2-unit longest dimension.
+      ['brass_blowtorch', [0, .47735, .7], .55, 0],
+    ] },
+  { key: 'study-relic-collection', name: 'Relic collection',
+    renderer_target: 'Compare carved stone, chess pieces and aged metal under shared light.',
+    preparation: 'Inspect silhouette, surface detail and contact shadows across five originals. Dimensions are illustrative scene units.',
+    placements: [
+      ['gothic_statue', [-1.2, 0, -.7], 1.8, .15],
+      ['marble_bust_01', [.65, 0, -.7], .85, -.25],
+      ['chess_set', [0, 0, .8], 1.15, .1],
+      ['kite_shield', [1.5, 0, .15], 1.15, -.4],
+      ['antique_estoc', [-1.5, 0, .8], 1.25, .25],
+    ] },
+  { key: 'study-tool-chest', name: 'Tool-chest arrangement',
+    renderer_target: 'Compare painted metal, rust and wooden handles in one working collection.',
+    preparation: 'Inspect relative scale, worn surfaces and small contact shadows. These are static originals placed on a shared inspection floor.',
+    placements: [
+      ['metal_tool_chest', [0, 0, -.8], 1.7, 0],
+      ['hand_plane_no4', [-.65, 0, .8], .5, -.25],
+      ['vintage_hand_drill', [.25, 0, .9], .55, .3],
+      ['rusted_spade_01', [1.25, 0, .05], 1.5, -.3],
+      ['can_rusted', [-1.25, 0, .2], .4, 0],
+    ] },
+];
+
+/** Independent layout data; the host resolves sources and controls access. */
+export function compositeStudyDefinitions() {
+  return definitions.map(({ placements, ...definition }) => ({
+    ...definition,
+    placements: placements.map(([key, anchor, size, yaw]) => [key, [...anchor], size, yaw]),
+  }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-demo-viewer",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "Root validation viewer for Plasius gpu-* demos.",
   "license": "Apache-2.0",
@@ -19,7 +19,11 @@
     ".": "./viewer-manifest.js",
     "./viewer-manifest": "./viewer-manifest.js",
     "./package.json": "./package.json",
-    "./model-library/acquire": "./model-library/acquire.js"
+    "./model-library/acquire": "./model-library/acquire.js",
+    "./model-library/studies": {
+      "types": "./model-library/studies.d.ts",
+      "default": "./model-library/studies.js"
+    }
   },
   "files": [
     "assets/",
@@ -47,7 +51,7 @@
     "lint": "npm run typecheck",
     "pack:check": "node scripts/verify-public-package.cjs",
     "prepublishOnly": "npm run build && npm run pack:check",
-    "typecheck": "node --check index.js && node --check main.js && node --check viewer-manifest.js && node --check showcase/index.js && node --check showcase/main.js && node --check wavefront/main.js && node --check model-library/main.js && node --check model-library/controller.js && node --check model-library/scenes.js && node --check model-library/acquire.js && node --check model-library/rollout.js",
+    "typecheck": "node --check index.js && node --check main.js && node --check viewer-manifest.js && node --check showcase/index.js && node --check showcase/main.js && node --check wavefront/main.js && node --check model-library/main.js && node --check model-library/controller.js && node --check model-library/scenes.js && node --check model-library/acquire.js && node --check model-library/rollout.js && node --check model-library/studies.js",
     "test": "node --test",
     "models:download": "node scripts/acquire-model-library.mjs",
     "models:dev": "vite --config model-library/vite.config.js",