@plasius/gpu-demo-viewer 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -18,6 +18,20 @@ 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**
@@ -338,3 +352,4 @@ The format is based on Keep a Changelog and this project adheres to SemVer.
 [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
 
@@ -202,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/model-library/scenes.js

@@ -1,51 +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],
-    ] },
-  { 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],
-    ] },
-];
+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.3",
+  "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",