@konitif/viewer-3d 0.284.1 → 0.284.2

package/README.md

@@ -1,34 +1,61 @@
 # @konitif/viewer-3d
 
-Product-neutral 3D contracts and explicit-provider renderer for a reusable
-spatial projection. Scene state enters through a `Viewer3DPort`; selection,
-focus, camera and reset operations leave as intents.
-
-The amodal `ViewerSnapshot`, `ViewerIntent`, `ViewerPort` and Workflow source
-belong to `@konitif/viewer`. This package extends those contracts with vectors,
-transforms and camera intents. Historical `Viewer3DWorkflowCompositionSource`
-names remain compatibility aliases.
-
-The root entry contains the 3D scene and support contracts. The optional
-`@konitif/viewer-3d/renderer` entry contains the Three.js projection runtime.
-It requires explicit physics and experiment providers and does not construct a
-Workbench recorder or a product campaign.
-
-Robot model names, Behavior projection states, authored calibrations, product
-campaigns and product UI belong in specialization or host packages. The
-historical `@konitif/ui/robot-viewer/renderer` entry remains a compatibility
-facade; it is not the renderer authority.
-
-LED groups use model-local placement definitions and a product-provided
-calibration. The renderer supports circular and straight-strip layouts while
-remaining unaware of robot-specific frame names and default offsets.
-
-The standalone candidate consumes published Tools 0.284.3, Temporal 0.284.1,
-Physics 0.284.1 and Viewer 0.284.1. Composition 0.284.2 remains owned
-transitively by the amodal Viewer package. The distributable manifest and lock
-retain those public versions; no workspace alias is part of the release
-contract.
-
-`npm run verify:package` creates an isolated consumer for both public exports
-and checks their ESM runtime and strict NodeNext declarations. A successful
-local qualification proves the archive boundary, not its presence on npm.
+Three.js-based spatial projection contracts and an explicit-provider renderer
+for KONITIF Viewers.
+
+## Installation
+
+```sh
+npm install @konitif/viewer-3d
+```
+
+## What it provides
+
+- Three-dimensional vectors, transforms, scene snapshots and intents.
+- A Workbench tool declaration for a spatial projection.
+- Data-only definitions for joints, supports, contacts, balance, hands and LED
+  placement.
+- An optional renderer entry with explicit physics and experiment providers.
+
+## Authority boundary
+
+The amodal Viewer contract belongs to `@konitif/viewer`. This package owns only
+the state and lifecycle of its 3D projection. Robot identity, model loading,
+authored calibration, physics policy, product campaigns and Workbench shell
+state remain host responsibilities.
+
+## Quick start
+
+```ts
+import { createViewer3DSceneSnapshot } from '@konitif/viewer-3d';
+
+const scene = createViewer3DSceneSnapshot({
+  sourceId: 'subject:example',
+  transforms: [{
+    id: 'origin',
+    position: { x: 0, y: 0, z: 0 },
+    rotation: { x: 0, y: 0, z: 0, w: 1 },
+  }],
+});
+```
+
+Import `@konitif/viewer-3d/renderer` only when a Three.js renderer and its
+explicit providers are required.
+
+## Public entry points
+
+| Entry | Purpose |
+| --- | --- |
+| `@konitif/viewer-3d` | Spatial contracts, definitions and scene helpers. |
+| `@konitif/viewer-3d/renderer` | Three.js projection runtime and diagnostics. |
+
+## Reference
+
+See [`reference/`](reference/) for the machine-readable capability catalog and
+authority diagrams. Legacy 3D composition-source names are compatibility
+aliases; the amodal source remains owned by `@konitif/viewer`.
+
+## License
+
+Source-available under [PolyForm Noncommercial 1.0.0](LICENSE.md), not OSI open
+source. Commercial use requires separate written authorization.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@konitif/viewer-3d",
   "license": "PolyForm-Noncommercial-1.0.0",
-  "version": "0.284.1",
+  "version": "0.284.2",
   "private": false,
   "type": "module",
   "description": "Product-neutral Three.js projection contracts and explicit-provider renderer for KONITIF viewers.",
@@ -29,7 +29,8 @@
     "LICENSE.md",
     "dist",
     "README.md",
-    "package.json"
+    "package.json",
+    "reference"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/reference/README.md

@@ -0,0 +1,10 @@
+# Viewer 3D reference
+
+This directory contains authored, machine-readable documentation for
+`@konitif/viewer-3d`.
+
+- [`catalog.json`](catalog.json) groups spatial contracts and renderer responsibilities.
+- [`diagrams.json`](diagrams.json) describes the subject-to-scene boundary.
+
+These files support documentation tooling. They do not identify a robot,
+configure product physics or transfer subject authority to the renderer.

package/reference/catalog.json

@@ -0,0 +1,111 @@
+{
+  "schemaVersion": "1.0.0",
+  "package": "@konitif/viewer-3d",
+  "intent": "Project a subject into a 3D scene without granting the view authority over the subject.",
+  "clusters": [
+    {
+      "id": "spatial-contracts",
+      "title": "Spatial contracts",
+      "summary": "Geometric values for the 3D projection.",
+      "authority": "Spatial representation contracts.",
+      "owns": [
+        "vectors",
+        "rotations",
+        "transforms"
+      ],
+      "doesNotOwn": [
+        "subject identity"
+      ],
+      "workflow": [
+        "Describe",
+        "Transform",
+        "Project"
+      ],
+      "symbolNames": [
+        "Viewer3DVector",
+        "Viewer3DQuaternion",
+        "Viewer3DTransform"
+      ]
+    },
+    {
+      "id": "scene-projection",
+      "title": "Scene projection",
+      "summary": "Snapshots and ports that make a scene observable.",
+      "authority": "Derived scene state.",
+      "owns": [
+        "snapshot",
+        "port"
+      ],
+      "doesNotOwn": [
+        "domain state"
+      ],
+      "workflow": [
+        "Adapt",
+        "Project",
+        "Observe"
+      ],
+      "symbolNames": [
+        "Viewer3DSceneSnapshot",
+        "Viewer3DPort",
+        "createViewer3DSceneSnapshot"
+      ]
+    },
+    {
+      "id": "renderer-projection",
+      "title": "Renderer projection",
+      "summary": "Three.js runtime supplied through an explicit entry point and fed by borrowed ports.",
+      "authority": "State and lifecycle of the visual projection.",
+      "owns": [
+        "Three.js scene",
+        "projection camera",
+        "display cadence",
+        "renderer lifecycle"
+      ],
+      "doesNotOwn": [
+        "robot identity",
+        "physics policy",
+        "experimental campaign",
+        "Workbench shell"
+      ],
+      "workflow": [
+        "Receive",
+        "Project",
+        "Observe",
+        "Dispose"
+      ],
+      "symbolNames": [
+        "Viewer3D",
+        "Viewer3DOptions",
+        "normalizeConfiguredDisplayFrameRate"
+      ]
+    },
+    {
+      "id": "workflow-integration",
+      "title": "Workflow and tool",
+      "summary": "3D specialization of a composition source and a Workbench contribution.",
+      "authority": "Amodal Viewer contract specialized by the 3D incarnation.",
+      "owns": [
+        "workflow source",
+        "intent",
+        "module"
+      ],
+      "doesNotOwn": [
+        "host runtime",
+        "amodal Viewer contract"
+      ],
+      "workflow": [
+        "Declare",
+        "Connect",
+        "Use"
+      ],
+      "symbolNames": [
+        "Viewer3DIntent",
+        "ViewerWorkflowCompositionSource",
+        "createViewerWorkflowCompositionSource",
+        "Viewer3DWorkflowCompositionSource",
+        "createViewer3DWorkflowCompositionSource",
+        "viewer3DToolModule"
+      ]
+    }
+  ]
+}

package/reference/diagrams.json

@@ -0,0 +1,70 @@
+{
+  "schemaVersion": "1.0.0",
+  "package": "@konitif/viewer-3d",
+  "diagrams": [
+    {
+      "id": "subject-to-scene",
+      "title": "From subject to 3D scene",
+      "kind": "boundary",
+      "summary": "Viewer adapts a subject and its transforms into an observable scene without acquiring its identity.",
+      "nodes": [
+        {
+          "id": "subject",
+          "label": "Canonical subject",
+          "description": "The observed object remains owned by its domain."
+        },
+        {
+          "id": "source",
+          "label": "Composition source",
+          "description": "A compatible reading is prepared."
+        },
+        {
+          "id": "snapshot",
+          "label": "Scene snapshot",
+          "description": "Transforms and visible objects are derived."
+        },
+        {
+          "id": "port",
+          "label": "3D port",
+          "description": "The renderer receives a stable contract.",
+          "tone": "runtime"
+        },
+        {
+          "id": "renderer",
+          "label": "Explicit renderer",
+          "description": "Three.js projects the scene without acquiring authority over the subject.",
+          "tone": "runtime"
+        },
+        {
+          "id": "scene",
+          "label": "Perceptible scene",
+          "description": "The user observes the projection.",
+          "tone": "projection"
+        }
+      ],
+      "edges": [
+        {
+          "from": "subject",
+          "to": "source"
+        },
+        {
+          "from": "source",
+          "to": "snapshot"
+        },
+        {
+          "from": "snapshot",
+          "to": "port"
+        },
+        {
+          "from": "port",
+          "to": "renderer"
+        },
+        {
+          "from": "renderer",
+          "to": "scene"
+        }
+      ],
+      "caption": "Camera, framing, and view transforms remain projection state."
+    }
+  ]
+}