@vived/component-pneumatic-panel 1.2.0 → 3.0.0

package/COMPONENT_KNOWLEDGE.md

@@ -0,0 +1,642 @@
+# Pneumatic Panel — VIVED Smart Component
+
+## Summary
+
+A 3D pneumatic control panel for VIVED slide apps featuring an exhaust knob, safety lock, and pressure gauge. Developers can toggle exhaust and lock states, check pressure, and snapshot/restore panel state for guided training or assessment interactions. Use it when you need a compact industrial interaction model with built-in lockout/tagout constraints and pressure behavior. The component is presentation-free (ADR-0009, ADR-0010): it owns geometry, domain, and identity, while the Host owns all hover/hint/selection feedback and every dialog — reading `view.highlightGroupsByObjectId` to outline the panel itself, and rendering the pressure readout from the VM.
+
+The canonical host-facing surface is the **`PneumaticPanelFacade`** — a single typed object (conforming to the structural `SmartComponent` contract) that drives an instance through commands, typed events, lifecycle, and persisted state. The flat controllers and PM adapter remain available as the underlying mechanism the facade delegates to (and which the Babylon view boundary still calls directly).
+
+- **Package**: @vived/component-pneumatic-panel
+- **Version**: 3.0.0
+- **Interface version**: 1
+- **GitHub**: vivedlearning/component-pneumatic-panel
+
+## Discovery
+
+- **Category**: Industrial Equipment / Pneumatics
+- **Tags**: pneumatic, panel, exhaust, valve, lock, lockout, tagout, pressure, gauge, PSI, industrial controls, safety training, assessment interaction, babylon, smart component
+- **Visual description**: A compact pneumatic panel assembly with a rotatable exhaust knob, lock body, ghost-lock preview mesh, and circular pressure gauge. The lock and knob support click interactions, and visual guidance can be toggled for training or assessment.
+- **Multi-instance**: Yes
+
+## Quick Start
+
+1. **Install** — package and peer dependencies.
+
+```bash
+npm install @vived/component-pneumatic-panel @vived/core @babylonjs/core @vived/app
+```
+
+2. **Register the feature factory** — wire the domain layer into your app.
+
+```typescript
+import { makeAppObjectRepo, makeDomainFactoryRepo } from "@vived/core";
+import { makePneumaticPanelFeatureFactory } from "@vived/component-pneumatic-panel";
+
+const appObjects = makeAppObjectRepo();
+const factoryRepo = makeDomainFactoryRepo(appObjects);
+
+makePneumaticPanelFeatureFactory(appObjects);
+factoryRepo.setupDomain();
+```
+
+3. **Create an instance and load the 3D model** — use the facade, the canonical host-facing surface.
+
+```typescript
+import { PneumaticPanelFacade } from "@vived/component-pneumatic-panel";
+
+const panel = new PneumaticPanelFacade("panel-1", appObjects); // creates the domain stack
+await panel.load(); // attaches and loads the Babylon view
+```
+
+4. **Basic interaction** — drive the instance through facade methods and typed events.
+
+```typescript
+panel.toggleExhaust();
+panel.toggleLock();
+panel.checkPressure();
+
+const unsubscribe = panel.onEvent("exhaustOpened", () => {
+  console.log("exhaust opened");
+});
+```
+
+> Need the raw `AppObject` (e.g. to parent the root node or register shadow casters)? Use the
+> `createBabylonPneumaticPanel` composition entry point instead — it creates the same domain
+> stack and view and returns the `AppObject`. See the mounting recipe below.
+
+## Facade (host-facing surface)
+
+The **`PneumaticPanelFacade`** is the one surface a host uses to drive an instance — commands, events, reactive view model, lifecycle, and persisted state through a single typed object. The flat controllers and PM adapter are the underlying mechanism it delegates to (documented under Internal / Advanced); host code should not call them directly.
+
+### Structural contract (Contract v1)
+
+Every VIVED facade implements the same eight mandatory members with this exact shape, so a host can hold mixed component types behind one uniform `SmartComponent` reference. This facade's **`interfaceVersion` is `1`**.
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `id` | `readonly string` | The instance identifier (matches the AppObject id). |
+| `interfaceVersion` | `readonly number` | The `SmartComponent` contract version this facade implements (`1`). |
+| `onEvent` | `<K extends keyof PneumaticPanelEvents>(event: K, cb: PneumaticPanelEvents[K]) => () => void` | Subscribe to a typed event. Returns an unsubscribe function — there is no separate `off`. |
+| `onViewModel` | `(cb: (vm: PneumaticPanelVM) => void) => () => void` | Subscribe to the reactive VM; emits the current VM immediately, then on every change. Returns an unsubscribe function. |
+| `load` | `(variant?: string) => Promise<void>` | The only async member; the only place view/asset work happens. |
+| `destroy` | `() => void` | Tear down the component and release all resources. |
+| `getState` | `() => PneumaticPanelState` | Versioned snapshot of authored configuration. |
+| `applyState` | `(state: PneumaticPanelState) => void` | Restore authored configuration from a snapshot. |
+
+### Lifecycle (two-phase)
+
+- **Construction is synchronous and idempotent.** `new PneumaticPanelFacade(id, appObjects)` builds the entire domain stack (Entity, Use Cases, PM, adapter) with no Babylon dependency — it is headless-testable. It uses `getOrCreate` semantics: constructing a facade for an existing `id` returns a handle to the same instance, never a duplicate.
+- **`load(variant?)` is the only async phase** and the only step that touches the Babylon view / GLB asset.
+- **Everything else works before `load()`.** All command methods, `onEvent`, `onViewModel`, `getState`, and `applyState` are fully functional the moment the facade is constructed — `load()` is required only for the 3D model to render.
+
+### Command methods
+
+Return-value convention: a command a domain rule can **block** returns `boolean` (`true` = took effect, `false` = blocked); a fire-and-forget command returns `void`. Commands never return domain data — read state via `getState()` or `onViewModel`.
+
+| Command | Signature | Description |
+| --- | --- | --- |
+| `toggleExhaust` | `() => boolean` | Toggle exhaust open/closed. `false` if blocked by lock state. |
+| `toggleLock` | `() => boolean` | Toggle lock. Can only engage when exhaust is open; `false` if exhaust is closed. Always succeeds when unlocking. |
+| `checkPressure` | `() => void` | Register a pressure check. Fires `pressureChecked`; renders nothing — the Host shows any dialog, reading `pressure` from the VM (ADR-0010). |
+| `setShowGhostLockHint` | `(show: boolean) => void` | Enable/disable always-visible ghost-lock hint behavior. |
+| `enableHitbox` | `() => void` | Enable whole-panel selection mode. Sub-component clicks are disabled while active. |
+| `disableHitbox` | `() => void` | Disable whole-panel selection mode. Restore sub-component interactivity. |
+
+### Event catalog (`PneumaticPanelEvents`)
+
+All event callbacks are payload-free `() => void`; the host reacts by reading `getState()` or the VM. `onEvent` returns an unsubscribe function.
+
+| Event | Fires when |
+| --- | --- |
+| `exhaustOpened` | exhaust valve transitioned to open |
+| `exhaustClosed` | exhaust valve transitioned to closed |
+| `exhaustCloseBlockedByLock` | a close attempt was blocked because the panel is locked |
+| `panelLocked` | panel transitioned to locked |
+| `panelUnlocked` | panel transitioned to unlocked |
+| `panelSelected` | the whole-panel hitbox was clicked |
+| `pressureChecked` | a pressure check was triggered |
+
+### Reactive view model (`PneumaticPanelVM`)
+
+The live render picture streamed by `onViewModel`. **Distinct from the state snapshot** — the VM includes transient/derived fields (live `pressure`, derived `subComponentsInteractive`) and must not be merged with `PneumaticPanelState`.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `exhaustOpen` | `boolean` | |
+| `isLocked` | `boolean` | |
+| `pressure` | `number` | Live value — derived from exhaust state (0 open, 60 closed). |
+| `showGhostLockHint` | `boolean` | |
+| `panelHitboxEnabled` | `boolean` | |
+| `subComponentsInteractive` | `boolean` | Derived: always `!panelHitboxEnabled`. |
+
+### State snapshot (`PneumaticPanelState`)
+
+The versioned, persistable subset of **authored configuration** captured by `getState()` and restored by `applyState()`. Excludes transient/derived fields that live only in the VM (e.g. `pressure`). Current `version` is **`2`**.
+
+| Field | Type |
+| --- | --- |
+| `version` | `number` (currently `2`) |
+| `exhaustOpen` | `boolean` |
+| `isLocked` | `boolean` |
+| `showGhostLockHint` | `boolean` |
+| `panelHitboxEnabled` | `boolean` |
+
+`applyState` is **best-effort forward-compatible** (ADR-0008): it applies the fields present and falls back to entity defaults for absent ones; it never throws on version mismatch. Older v1 snapshots (which carried a since-removed `highlightedObject` field) still restore cleanly — the unknown field is ignored.
+
+### Variants and the objectId interaction map
+
+`load(variant?)` accepts an optional variant string; an omitted or unrecognized variant falls back to the default asset (best-effort — no variants are implemented yet). The real contract between the domain and a GLB is the **objectId interaction map** — the named interactive nodes the view binds to — so any asset honoring this map can serve as a variant:
+
+| objectId | Role |
+| --- | --- |
+| `exhaust_knob` | Click to toggle exhaust; rotates with exhaust state. |
+| `lock` | Lock transform and child meshes; click to toggle lock state. |
+| `ghost_lock` | Hover-reveal lock helper and click target for lock action. |
+| `gauge` | Click to invoke pressure check. |
+| `panel_hitbox` | Invisible full-panel bounding mesh; active only when `panelHitboxEnabled` is true. Keyed in `highlightGroupsByObjectId` to every visible panel mesh. |
+
+## API Reference
+
+### Public API (use these)
+
+The **`PneumaticPanelFacade`** is THE host-facing surface for driving an instance. Its constructor synchronously creates the full domain stack (Entity, Use Cases, PM, adapter); `load()` attaches the Babylon view. For scenarios that need the raw `AppObject`, `createBabylonPneumaticPanel` is the equivalent composition entry point. The controllers and PM adapter below are the underlying mechanism the facade delegates to, and remain exported for direct use (the framework/view boundary calls them directly).
+
+#### `PneumaticPanelFacade` (primary)
+
+**The facade is THE way to drive an instance — see the [Facade](#facade-host-facing-surface) section above for the full host-facing surface:** the eight-member Contract v1, two-phase lifecycle, command methods, event catalog, reactive VM, state snapshot, and variants, all with inline signatures. `makePneumaticPanelFeatureFactory` (below) is the only other Public API entry point — call it once at startup before `setupDomain()`.
+
+#### Composition entry point & controllers
+
+| Function                         | Signature                                                                                                                       | Description                                                                                                                   |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| createBabylonPneumaticPanel      | (id: string, appObjects: AppObjectRepo) => Promise\<AppObject \| undefined\>                                                    | Composition entry point. Creates the full domain stack and Babylon view, loads the asset, and returns the AppObject.          |
+| makePneumaticPanelFeatureFactory | (appObjects: AppObjectRepo) => PneumaticPanelFeatureFactory                                                                     | Registers the feature factory. Call once at app startup before `setupDomain()`.                                               |
+| tryToggleExhaust                 | (id: string, appObjects: AppObjectRepo) => boolean                                                                              | Toggles exhaust open/closed. Returns false if blocked by lock state.                                                          |
+| tryToggleLock                    | (id: string, appObjects: AppObjectRepo) => boolean                                                                              | Toggles lock state. Can only engage when exhaust is open; returns false if exhaust is closed. Always succeeds when unlocking. |
+| checkPressure                    | (id: string, appObjects: AppObjectRepo) => void                                                                                 | Registers a pressure check and notifies `pressureChecked` subscribers. Renders nothing.                                       |
+| setShowGhostLockHint             | (id: string, appObjects: AppObjectRepo, on: boolean) => void                                                                    | Enables/disables always-visible ghost-lock hint behavior.                                                                     |
+| enablePanelHitbox                | (id: string, appObjects: AppObjectRepo) => void                                                                                 | Enables whole-panel selection mode. Sub-component clicks are disabled while active.                                           |
+| disablePanelHitbox               | (id: string, appObjects: AppObjectRepo) => void                                                                                 | Disables whole-panel selection mode. Restores sub-component interactivity.                                                    |
+| getPanelState                    | (id: string, appObjects: AppObjectRepo, version: number) => PneumaticPanelState                                                 | Returns a versioned snapshot of panel state. (Facade: `getState()`.)                                                          |
+| applyPanelState                  | (id: string, appObjects: AppObjectRepo, state: PneumaticPanelState) => void                                                     | Restores panel state from a snapshot. (Facade: `applyState()`.)                                                               |
+| onExhaustOpened                  | (id: string, appObjects: AppObjectRepo, callback: () => void) => () => void                                                     | Subscribes to exhaust-opened transitions. Returns an unsubscribe function.                                                    |
+| onExhaustClosed                  | (id: string, appObjects: AppObjectRepo, callback: () => void) => () => void                                                     | Subscribes to exhaust-closed transitions. Returns an unsubscribe function.                                                    |
+| onExhaustCloseBlockedByLock      | (id: string, appObjects: AppObjectRepo, callback: () => void) => () => void                                                     | Subscribes to blocked exhaust-close attempts (exhaust is locked). Returns an unsubscribe function.                            |
+| onPanelLocked                    | (id: string, appObjects: AppObjectRepo, callback: () => void) => () => void                                                     | Subscribes to panel-locked transitions. Returns an unsubscribe function.                                                      |
+| onPanelUnlocked                  | (id: string, appObjects: AppObjectRepo, callback: () => void) => () => void                                                     | Subscribes to panel-unlocked transitions. Returns an unsubscribe function.                                                    |
+| onPanelSelected                  | (id: string, appObjects: AppObjectRepo, callback: () => void) => () => void                                                     | Subscribes to whole-panel hitbox clicks. Returns an unsubscribe function.                                                     |
+| onCheckPressure                  | (id: string, appObjects: AppObjectRepo, callback: () => void) => () => void                                                     | Subscribes to pressure-check requests (gauge click). Returns an unsubscribe function.                                         |
+
+> **Reactive view model:** subscribe via the facade's `onViewModel(cb)` — the
+> canonical host-facing surface for VM updates. The raw `pneumaticPanelPMAdapter`
+> export still exists for the framework/view boundary and advanced use, but is no
+> longer the advertised consumer path (see Internal / Advanced).
+
+### Accessors (read after creation)
+
+Use these to read state or retrieve the view from an already-created instance.
+
+| Accessor                              | Returns                                | Description                                                   |
+| ------------------------------------- | -------------------------------------- | ------------------------------------------------------------- |
+| PneumaticPanelBabylonView.get(appObj) | PneumaticPanelBabylonView \| undefined | Retrieve the Babylon view from an AppObject after creation.   |
+| view.rootTransformNode                | TransformNode \| undefined             | Root transform for positioning/parenting in scene.            |
+| view.shadowCasters                    | AbstractMesh[]                         | Meshes suitable for shadow registration.                      |
+| view.nodesByObjectId                  | ReadonlyMap\<string, Node\>            | Scene-node lookup keyed by lowercased glTF objectId metadata. |
+| view.highlightGroupsByObjectId        | ReadonlyMap\<string, AbstractMesh[]\>  | Highlight groups keyed by semantic objectId. `panel_hitbox` maps to every visible panel mesh (so the Host can outline the whole panel when the invisible hitbox is the pointer target); other objectIds map to a one-element array. Populated after `load()`. |
+
+### Internal / Advanced (do not call directly)
+
+> **Warning:** These are exported for extensibility and testing only. They are created automatically by `PneumaticPanelFacade` / `createBabylonPneumaticPanel`. Calling them directly without first creating the full domain stack will produce a partially-initialized object whose behavior silently does not work.
+
+| Export                            | Description                                                    |
+| --------------------------------- | -------------------------------------------------------------- |
+| pneumaticPanelPMAdapter           | Raw PM adapter (`subscribe`/`unsubscribe`). Used by the framework/view boundary; prefer the facade's `onViewModel(cb)` for host code. |
+| makePneumaticPanelSelectUC        | Creates panel-select UC only. No entity or view.               |
+| makePneumaticPanelBabylonView     | Creates the Babylon view only — no Entity/UC/PM. Testing only. |
+| makePneumaticPanelEntity          | Creates entity only. No UCs, PM, or view.                      |
+| makePneumaticPanelRepo            | Creates the entity repo singleton.                             |
+| makePneumaticPanelPM              | Creates PM only. No entity or UCs.                             |
+| makePneumaticPanelToggleExhaustUC | Creates exhaust UC only. No entity or view.                    |
+| makePneumaticPanelToggleLockUC    | Creates lock UC only. No entity or view.                       |
+| makePneumaticPanelCheckPressureUC | Creates pressure-check UC only. No entity or view.             |
+| panelHitboxClicked                | Internal boundary controller — called by the Babylon view on hitbox pick. |
+| MockPneumaticPanelPM              | Mock PM for consumer integration tests.                        |
+| MockPneumaticPanelToggleExhaustUC | Mock exhaust UC for consumer tests.                            |
+| MockPneumaticPanelToggleLockUC    | Mock lock UC for consumer tests.                               |
+| MockPneumaticPanelCheckPressureUC | Mock pressure-check UC for consumer tests.                     |
+| MockPneumaticPanelSelectUC        | Mock panel-select UC for consumer tests.                       |
+| componentConfig                   | Metadata constant (name, version, asset IDs).                  |
+
+### Types
+
+```typescript
+// SmartComponent structural contract the facade conforms to (Contract v1, per ADR-0006).
+// Eight mandatory members, shape-identical across every VIVED smart component.
+interface SmartComponent {
+  readonly id: string;
+  readonly interfaceVersion: number;
+  onEvent(event: string, cb: (...args: never[]) => void): () => void;
+  onViewModel(cb: (vm: PneumaticPanelVM) => void): () => void;
+  load(variant?: string): Promise<void>;
+  destroy(): void;
+  getState(): PneumaticPanelState;
+  applyState(state: PneumaticPanelState): void;
+}
+
+// Typed event catalog for the facade's onEvent(...) method
+type PneumaticPanelEvents = {
+  exhaustOpened: () => void;
+  exhaustClosed: () => void;
+  exhaustCloseBlockedByLock: () => void;
+  panelLocked: () => void;
+  panelUnlocked: () => void;
+  panelSelected: () => void;
+  pressureChecked: () => void;
+};
+
+// Versioned, persistable panel state snapshot.
+// Version 2 (per ADR-0009) removed the `highlightedObject` field; older v1
+// snapshots still restore cleanly via ADR-0008 best-effort apply (unknown
+// fields ignored, absent fields defaulted).
+const PNEUMATIC_PANEL_STATE_VERSION = 2;
+
+type PneumaticPanelState = {
+  version: number;
+  exhaustOpen: boolean;
+  isLocked: boolean;
+  showGhostLockHint: boolean;
+  panelHitboxEnabled: boolean;
+};
+
+interface PneumaticPanelVM {
+  exhaustOpen: boolean;
+  isLocked: boolean;
+  pressure: number;
+  showGhostLockHint: boolean;
+  panelHitboxEnabled: boolean;
+  subComponentsInteractive: boolean; // derived: always !panelHitboxEnabled
+}
+```
+
+> **Note:** `PneumaticPanelState` does not include `pressure` — pressure is derived
+> automatically from exhaust state on restore (0 when open, max when closed).
+
+## 3D View
+
+### Asset
+
+| Name    | Asset ID                             | File               |
+| ------- | ------------------------------------ | ------------------ |
+| default | db90a1dd-8cb9-4f56-954d-7a72610281a7 | pneumaticPanel.glb |
+
+**The published package ships no 3D assets.** The GLB is fetched at load time by asset id through `getAssetBlobURL`, so `dist/` contains code only. The `pneumaticPanel.glb` and `studio.env` files in the repo's `public/` directory exist for the dev playground and are deliberately excluded from the build (`publicDir: false` in `vite.config.ts`). A host does not need to serve or vendor either file.
+
+### Exposed Transform Nodes
+
+The facade does not expose scene nodes directly. To position, parent, or register shadow casters, retrieve the view from the AppObject (the facade's `id` matches the AppObject id):
+
+```typescript
+import {
+  PneumaticPanelFacade,
+  PneumaticPanelBabylonView,
+} from "@vived/component-pneumatic-panel";
+
+const panel = new PneumaticPanelFacade("panel-1", appObjects);
+await panel.load();
+
+const appObject = appObjects.get(panel.id);
+const view = appObject ? PneumaticPanelBabylonView.get(appObject) : undefined;
+if (view?.rootTransformNode) {
+  view.rootTransformNode.position.set(1, 0, -2);
+}
+```
+
+### Interactive objectId mapping
+
+The GLB includes these objectId metadata values:
+
+| objectId     | Role                                                                                              |
+| ------------ | ------------------------------------------------------------------------------------------------- |
+| exhaust_knob | Click to toggle exhaust; rotates with exhaust state.                                              |
+| lock         | Lock transform and child meshes; click to toggle lock state.                                      |
+| ghost_lock   | Hover-reveal lock helper and click target for lock action.                                        |
+| gauge        | Click to invoke pressure check.                                                                   |
+| panel_hitbox | Invisible full-panel bounding mesh; active only when `panelHitboxEnabled` is true.                |
+
+## Recipes
+
+### Mounting / parenting into a host scene
+
+The facade drives behavior but does not expose scene nodes. When you need the root transform
+node (to parent the panel into a host scene) or shadow casters, use the
+`createBabylonPneumaticPanel` composition entry point, which returns the `AppObject`:
+
+```typescript
+import {
+  createBabylonPneumaticPanel,
+  PneumaticPanelBabylonView,
+} from "@vived/component-pneumatic-panel";
+
+const appObject = await createBabylonPneumaticPanel("panel-1", appObjects);
+if (appObject) {
+  const view = PneumaticPanelBabylonView.get(appObject);
+  if (view?.rootTransformNode) {
+    // Parent to an existing scene node (e.g. a workbench or equipment mount)
+    view.rootTransformNode.parent = parentTransformNode;
+    view.rootTransformNode.position.set(0, 1.2, 0);
+  }
+
+  // Register shadow casters with a ShadowGenerator
+  for (const mesh of view?.shadowCasters ?? []) {
+    shadowGenerator.addShadowCaster(mesh);
+  }
+}
+```
+
+### Snapshot and restore panel state
+
+```typescript
+import { PneumaticPanelFacade } from "@vived/component-pneumatic-panel";
+
+const panel = new PneumaticPanelFacade("panel-1", appObjects);
+await panel.load();
+
+// Capture a versioned snapshot (e.g. to persist learner progress)
+const snapshot = panel.getState();
+localStorage.setItem("panel-1-state", JSON.stringify(snapshot));
+
+// Restore later — pressure is recomputed from exhaust state automatically
+const saved = JSON.parse(localStorage.getItem("panel-1-state")!);
+panel.applyState(saved);
+```
+
+### Training vs assessment lock hint mode
+
+```typescript
+// Training mode: ghost lock is visible when eligible.
+panel.setShowGhostLockHint(true);
+
+// Assessment mode: ghost lock is invisible unless the Host reveals it.
+panel.setShowGhostLockHint(false);
+```
+
+`showGhostLockHint` is authored domain state — the Activity deciding whether this
+learner is shown where the lock goes. It is not hover state: with the hint off the
+ghost lock stays enabled and pickable but invisible, and the Host reveals it on
+hover if it wants to (ADR-0010). A Host that wires nothing shows no reveal.
+
+### Host-owned highlighting (outline the panel from the hitbox)
+
+The component is presentation-free for interaction state (ADR-0009): it no longer
+renders its own hover outline or hint glow. Instead the Host reads
+`view.highlightGroupsByObjectId` and drives its own highlight system. The
+`panel_hitbox` entry maps to every visible panel mesh, so the Host can outline the
+whole visible panel even though the pointer target is the invisible hitbox.
+
+```typescript
+const appObject = appObjects.get(panel.id);
+const view = appObject ? PneumaticPanelBabylonView.get(appObject) : undefined;
+
+// Outline the whole panel when the invisible hitbox is hovered/selected.
+const panelMeshes = view?.highlightGroupsByObjectId.get("panel_hitbox") ?? [];
+for (const mesh of panelMeshes) {
+  hostHighlightManager.add(mesh);
+}
+
+// Every other objectId is registered as a single-mesh group, so the same map is
+// how the Host reaches the ghost lock to reveal it on hover (ADR-0010).
+const [ghostLock] = view?.highlightGroupsByObjectId.get("ghost_lock") ?? [];
+if (ghostLock) {
+  ghostLock.visibility = isHoveringGhostLock ? 1 : 0;
+}
+```
+
+### Subscribe to events (facade)
+
+```typescript
+import { PneumaticPanelFacade } from "@vived/component-pneumatic-panel";
+
+const panel = new PneumaticPanelFacade("panel-1", appObjects);
+await panel.load();
+
+const unsubscribeOpened = panel.onEvent("exhaustOpened", () => {
+  console.log("exhaust opened");
+});
+const unsubscribeLocked = panel.onEvent("panelLocked", () => {
+  console.log("panel locked");
+});
+// The component renders no dialog (ADR-0010). Track the VM, then present the
+// value however the Host wants. There is no getter — `onViewModel` emits the
+// current VM immediately on subscribe and on every change.
+let latestVM: PneumaticPanelVM | undefined;
+const unsubscribeVM = panel.onViewModel((vm) => {
+  latestVM = vm;
+});
+
+const unsubscribePressure = panel.onEvent("pressureChecked", () => {
+  hostShowAlertUC.showAlert({
+    title: "Pneumatic Panel Pressure",
+    message: `${latestVM?.pressure ?? 0} PSI`,
+    closeButtonLabel: "OK",
+    closeCallback: () => {},
+  });
+});
+
+// Later — clean up subscriptions
+unsubscribeOpened();
+unsubscribeLocked();
+unsubscribePressure();
+unsubscribeVM();
+```
+
+### Subscribe to VM state updates (facade)
+
+Use the facade's `onViewModel` — it emits the current VM immediately, then on every
+change, and returns an unsubscribe function. This is the canonical reactive surface
+(it wraps `pneumaticPanelPMAdapter`, which remains available for the view boundary /
+advanced use).
+
+```typescript
+import {
+  PneumaticPanelFacade,
+  type PneumaticPanelVM,
+} from "@vived/component-pneumatic-panel";
+
+const panel = new PneumaticPanelFacade("panel-1", appObjects);
+await panel.load();
+
+const unsubscribe = panel.onViewModel((vm: PneumaticPanelVM) => {
+  console.log(vm.exhaustOpen, vm.isLocked, vm.pressure, vm.panelHitboxEnabled);
+});
+
+// Later
+unsubscribe();
+```
+
+In React, `onViewModel` returns the unsubscribe directly, so `useEffect` consumes it:
+
+```tsx
+useEffect(() => panel.onViewModel(setVm), [panel]);
+```
+
+### Whole-panel selection mode
+
+Enable the panel hitbox to treat the whole panel as one clickable target (e.g. for a "select a panel" interaction in an activity). Hover feedback is the Host's responsibility (ADR-0009) — the component emits only the `panelSelected` click event.
+
+```typescript
+import { PneumaticPanelFacade } from "@vived/component-pneumatic-panel";
+
+const panel = new PneumaticPanelFacade("panel-1", appObjects);
+await panel.load();
+
+// Enable — panel becomes a single click target; sub-components deactivate
+panel.enableHitbox();
+
+const unsubscribe = panel.onEvent("panelSelected", () => {
+  console.log("panel was selected");
+  // Restore sub-component interactions when done
+  panel.disableHitbox();
+  unsubscribe();
+});
+```
+
+### Creating multiple instances
+
+```typescript
+import { PneumaticPanelFacade } from "@vived/component-pneumatic-panel";
+
+const panel1 = new PneumaticPanelFacade("panel-1", appObjects);
+const panel2 = new PneumaticPanelFacade("panel-2", appObjects);
+await Promise.all([panel1.load(), panel2.load()]);
+```
+
+## Common Mistakes
+
+### Calling `makePneumaticPanelBabylonView` directly
+
+❌ **Wrong** — creates the view only, with no Entity, Use Cases, or PM. Click interactions silently do nothing.
+
+```typescript
+import { makePneumaticPanelBabylonView } from "@vived/component-pneumatic-panel";
+
+const appObject = appObjects.getOrCreate("panel-1");
+const view = makePneumaticPanelBabylonView(appObject);
+await view.load(); // Renders, but toggling exhaust/lock silently fails
+```
+
+✅ **Correct** — use the `PneumaticPanelFacade` (or `createBabylonPneumaticPanel`), which create the full domain stack AND the view.
+
+```typescript
+import { PneumaticPanelFacade } from "@vived/component-pneumatic-panel";
+
+const panel = new PneumaticPanelFacade("panel-1", appObjects);
+await panel.load();
+```
+
+### Guessing an AppObject ID to grab an existing instance
+
+❌ **Wrong** — constructing IDs by naming convention to retrieve a pre-existing AppObject skips the factory and results in a missing domain stack.
+
+```typescript
+const appObject = appObjects.get("panel-1");
+const view = PneumaticPanelBabylonView.get(appObject!); // may be undefined or partial
+```
+
+✅ **Correct** — always create instances through the facade or `createBabylonPneumaticPanel`. After creation, the facade's `id` (or the returned AppObject) is the supported handle.
+
+### Reaching into view internals instead of using accessors
+
+❌ **Wrong** — accessing private meshes or nodes directly from sub-views.
+
+✅ **Correct** — use `PneumaticPanelBabylonView.get(appObject)` to access the public view surface (`rootTransformNode`, `shadowCasters`, `nodesByObjectId`, `highlightGroupsByObjectId`).
+
+## Constraints & Defaults
+
+### Default state
+
+| Property          | Default |
+| ----------------- | ------- |
+| exhaustOpen       | false   |
+| isLocked          | false   |
+| pressure          | 60      |
+| showGhostLockHint | false   |
+| panelHitboxEnabled | false  |
+
+### Automatic behaviors
+
+- **Pressure management**: Pressure is automatically set to 0 when exhaust opens and restored to max pressure (60) when exhaust closes. Developers do not need to manage pressure values manually — and `PneumaticPanelState` therefore omits `pressure`, recomputing it from exhaust state on restore.
+- **Lock constraint**: The lock can only be engaged when the exhaust is open (lockout/tagout safety). Attempting to lock with exhaust closed returns false.
+- **Exhaust constraint**: The exhaust cannot be toggled while locked. Attempting to toggle returns false.
+- **Ghost lock visibility**: In hint mode (`showGhostLockHint: true`), the ghost lock mesh is visible whenever eligible (exhaust open, not locked). With the hint off it is enabled and pickable but invisible — the component detects no hover and reveals nothing (ADR-0010).
+- **Panel hitbox / sub-component interactivity**: When `panelHitboxEnabled` is true, sub-component clicks (exhaust, lock, gauge) are disabled and the whole panel acts as a single target. `subComponentsInteractive` in the VM is always derived as `!panelHitboxEnabled`.
+- **Presentation-free interaction state (ADR-0009, ADR-0010)**: The component does not render hover outlines, hint glows, selection feedback, or dialogs, and detects no hover. The Host owns all of it, reading `view.highlightGroupsByObjectId` to map semantic objectIds to meshes.
+
+### Known limitations
+
+- `checkPressure` displays nothing. A Host that does not subscribe to `pressureChecked` gives the learner no feedback when the gauge is clicked.
+- The ghost lock does not reveal on hover. A Host that does not drive `ghost_lock` visibility gives the learner no hint affordance in non-hint mode.
+- The GLB asset must include `objectId` metadata on the expected nodes (`exhaust_knob`, `lock`, `ghost_lock`, `gauge`, `panel_hitbox`) for click interactions and highlight grouping to work.
+- `PneumaticPanelState` is versioned (`PNEUMATIC_PANEL_STATE_VERSION = 2`). Snapshots are restored best-effort (ADR-0008): unknown fields are ignored and absent fields default, so older v1 snapshots (which carried `highlightedObject`) still apply cleanly.
+
+## Repository
+
+| Field          | Value                                   |
+| -------------- | --------------------------------------- |
+| Package        | @vived/component-pneumatic-panel        |
+| GitHub         | vivedlearning/component-pneumatic-panel |
+| Version        | 3.0.0                                   |
+| Interface version | 1                                    |
+| State schema version | 2                                 |
+| Multi-instance | Yes                                     |
+
+### Full export list
+
+#### Public API (use these)
+
+- `PneumaticPanelFacade` — **primary host-facing surface** (class; drives commands, events, state, lifecycle)
+- `createBabylonPneumaticPanel` — composition entry point (full domain + view; returns AppObject)
+- `makePneumaticPanelFeatureFactory` — factory registration
+- `tryToggleExhaust` — controller
+- `tryToggleLock` — controller
+- `checkPressure` — controller
+- `setShowGhostLockHint` — controller
+- `enablePanelHitbox` — controller
+- `disablePanelHitbox` — controller
+- `getPanelState` — state snapshot controller (facade: `getState()`)
+- `applyPanelState` — state restore controller (facade: `applyState()`)
+- `onExhaustOpened` — event subscription controller
+- `onExhaustClosed` — event subscription controller
+- `onExhaustCloseBlockedByLock` — event subscription controller
+- `onPanelLocked` — event subscription controller
+- `onPanelUnlocked` — event subscription controller
+- `onPanelSelected` — event subscription controller
+- `onCheckPressure` — event subscription controller
+- `PNEUMATIC_PANEL_STATE_VERSION` — state version constant
+
+#### Accessors (read after creation)
+
+- `PneumaticPanelBabylonView` (class with static `.get()`) — retrieve the view from an AppObject
+- `PneumaticPanelVM` (type) — view model interface
+- `PneumaticPanelState` (type) — versioned state snapshot interface
+- `SmartComponent` (type) — structural facade contract
+- `PneumaticPanelEvents` (type) — facade event catalog
+
+#### Internal / Advanced (extensibility/testing only — not for normal use)
+
+- `PneumaticPanelEntity`, `makePneumaticPanelEntity`
+- `PneumaticPanelRepo`, `makePneumaticPanelRepo`, `PneumaticPanelEntityFactory` (type)
+- `PneumaticPanelToggleExhaustUC`, `makePneumaticPanelToggleExhaustUC`
+- `PneumaticPanelToggleLockUC`, `makePneumaticPanelToggleLockUC`
+- `PneumaticPanelCheckPressureUC`, `makePneumaticPanelCheckPressureUC`
+- `PneumaticPanelSelectUC`, `makePneumaticPanelSelectUC`
+- `PneumaticPanelPM`, `makePneumaticPanelPM`
+- `PneumaticPanelFeatureFactory` (class)
+- `makePneumaticPanelBabylonView` — creates view only, no domain stack
+- `pneumaticPanelPMAdapter` — raw PM adapter; used by the view boundary. Host code should prefer the facade's `onViewModel(cb)`.
+- `panelHitboxClicked` — internal boundary controller (called by Babylon view on hitbox pick)
+- `MockPneumaticPanelPM` — mock for consumer tests
+- `MockPneumaticPanelToggleExhaustUC` — mock for consumer tests
+- `MockPneumaticPanelToggleLockUC` — mock for consumer tests
+- `MockPneumaticPanelCheckPressureUC` — mock for consumer tests
+- `MockPneumaticPanelSelectUC` — mock for consumer tests
+- `componentConfig` — metadata constant

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright © 2026 VIVED Learning. All rights reserved.
+
+This software and its associated documentation (the "Software") are the
+proprietary and confidential property of VIVED Learning. The Software is
+intended for internal use with VIVED Learning's player and infrastructure only.
+
+No license, right, or permission is granted to any party to use, copy, modify,
+merge, publish, distribute, sublicense, or sell the Software, in whole or in
+part, except as expressly authorized in writing by VIVED Learning. Publication
+of this package to a public registry does not constitute such authorization or
+grant any license to it.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.