@vived/component-pneumatic-panel 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,212 @@
+# Changelog
+
+## [3.0.0] - 2026-09-02
+
+Smart Component conformance train. Three violations found in the conformance audit
+of `demo_automation_cell` on 2026-09-02, fixed together because each changes the
+consumer contract.
+
+### Changed
+
+- **BREAKING: `@vived/app` is now a required `peerDependency`** and is externalized
+  in the lib build instead of bundled. Its entire module graph was being inlined
+  into `dist/index.js` — 127 KB, 78% of the bundle — freezing a build-time copy
+  against which a host ran its own. Cross-copy resolution worked only because
+  `@vived/app` looks components up by string `type`; any `instanceof` check or
+  renamed `type` string would have failed silently. Hosts that relied on the
+  component carrying its own copy must install it; every VIVED host already
+  depends on it. `dist/index.js`: 163,144 → 34,714 bytes (gzip 29.58 → 7.29 kB).
+
+### Removed
+
+- **BREAKING: the pressure dialog moves to the Host (ADR-0010).** `checkPressure()`
+  no longer resolves `ShowAlertUC` and no longer renders anything — it fires
+  `pressureChecked` and returns. The Host subscribes and reads `pressure` from
+  `PneumaticPanelVM`, exactly as `@vived/component-abb-controller` does for
+  `voltageChecked`. Removed the `ShowAlertUC` / `ShowAlertDTO` local interfaces,
+  the `showAlertUC` getter and the "Missing ShowAlertUC" warning. The UC no longer
+  reads `PneumaticPanelEntity` at all. A Host that does not subscribe now shows
+  the learner nothing when the gauge is clicked.
+- **BREAKING: the ghost-lock hover reveal moves to the Host (ADR-0010).** Removed
+  `bindGhostHoverActions` and its `OnPointerOverTrigger` / `OnPointerOutTrigger`
+  actions from `PneumaticPanelLockView`. Ghost-lock visibility is now driven only
+  by authored domain state (`showGhostLockHint`); the mesh stays enabled and
+  pickable, and the Host reveals it on hover through the existing `ghost_lock`
+  entry in `highlightGroupsByObjectId`. This completes the hover removal that
+  ADR-0009 scoped to `PneumaticPanelHitboxView` only.
+
+### Unchanged
+
+- Every `OnPickTrigger` handler — cutoff knob, lock children, ghost lock, hitbox.
+  A pick is domain intent and stays with the component.
+- `setShowGhostLockHint()` and the `showGhostLockHint` VM field — authored domain
+  state, not interaction state.
+- The facade's TypeScript surface. `checkPressure()`, `pressureChecked`,
+  `setShowGhostLockHint()` and `showGhostLockHint` all keep their shapes, which is
+  exactly why this is a major bump: the type checker will not flag it for
+  consumers, but two features go quiet until the Host wires them.
+
+### Notes
+
+- Host companion work for `demo_automation_cell` is tracked at
+  vivedlearning/demo_automation_cell#320 and must land before this is consumed.
+- The dev playground (`dev/main.ts`) now wires both Host seams itself, so it
+  demonstrates the expected integration rather than relying on removed behaviour.
+- ADR-0010 records both boundary decisions and the options rejected.
+
+## [2.0.1] - 2026-09-02
+
+### Fixed
+
+- **The published package no longer ships 3D assets.** The lib build inherited Vite's
+  default `publicDir`, so `pneumaticPanel.glb` (406 KB) and `studio.env` (207 KB) were
+  copied into `dist/` on every build. Those files exist for the dev playground only —
+  at runtime the component fetches its asset by id via `getAssetBlobURL` — so
+  `vite.config.ts` now sets `publicDir: false`. Install footprint drops from 777 KB to
+  ~165 KB. No runtime behaviour changes; hosts never loaded these files from the package.
+- **Corrected the default asset id in `COMPONENT_KNOWLEDGE.md`.** The doc still carried
+  the pre-hitbox id `83790d2d-…`; the current GLB (which contains the `panel_hitbox`
+  mesh) is `db90a1dd-8cb9-4f56-954d-7a72610281a7`, as `src/component.config.ts` has had
+  since the hitbox feature landed.
+
+### Added
+
+- `publishConfig.access: "public"` in `package.json`, completing the Smart Component
+  Packaging & Distribution Convention checklist.
+- A note in `COMPONENT_KNOWLEDGE.md` recording that shipping no assets is deliberate.
+
+## [2.0.0] - 2026-07-07
+
+### Removed
+
+- **BREAKING: presentation-free interaction state (ADR-0009).** The component no longer
+  self-renders hover outlines or hint glows, or detects hover — the Host owns all
+  hover/hint/selection feedback. Removed the facade commands `setHighlightedObject()` /
+  `clearAllHighlights()`; the events `panelHoverEnter` / `panelHoverExit` and their
+  `onPanelHoverEnter` / `onPanelHoverExit` / `panelHitboxHoverEnter` /
+  `panelHitboxHoverExit` controllers; the `highlightedObject` field from
+  `PneumaticPanelState` and `PneumaticPanelVM`; the `PneumaticPanelHighlightedObject`
+  type; `PanelOutlineController`, `OverlayPulseController`, `OutlinePulseController`,
+  `ScreenSpaceOutlinePulseController`, and the `HighlightLayer` / glow config surface.
+
+### Added
+
+- **`highlightGroupsByObjectId`** on `PneumaticPanelBabylonView` — a
+  `ReadonlyMap<string, AbstractMesh[]>` from semantic `objectId` to the meshes the Host
+  should treat as one highlightable unit. The `panel_hitbox` entry maps to every visible
+  panel mesh, so the Host can outline the whole panel from the invisible hitbox.
+
+### Changed
+
+- `PNEUMATIC_PANEL_STATE_VERSION` bumped `1 → 2` (removed `highlightedObject`). Older v1
+  snapshots still restore cleanly via ADR-0008 best-effort apply.
+- The `panel_hitbox` mesh is now genuinely invisible (`visibility = 0`); the `0.001`
+  epsilon (ADR-0004, now superseded) is no longer needed.
+
+## [1.2.0] - 2026-06-26
+
+### Added
+
+- **`PneumaticPanelFacade`** — a host-facing `SmartComponent` class (Smart Component
+  Facade Contract v1), now exported from the package entry point. It is the canonical
+  way for a host to drive an instance and wraps the flat controllers behind one typed
+  object: `id`, `interfaceVersion`, `onEvent(event, cb)`, `onViewModel(cb)`,
+  `load(variant?)`, `destroy()`, `getState()`, `applyState(state)`, plus the
+  component-specific commands `toggleExhaust()`, `toggleLock()`, `checkPressure()`,
+  `setHighlightedObject()`, `clearAllHighlights()`, `setShowGhostLockHint()`,
+  `enableHitbox()`, and `disableHitbox()`. Construction is synchronous, headless, and
+  idempotent (constructing for an existing id returns a handle to the same instance).
+- Exported types `SmartComponent` (the structural contract) and `PneumaticPanelEvents`
+  (the typed event catalog).
+- **Versioned panel state snapshot/restore** — `PNEUMATIC_PANEL_STATE_VERSION`,
+  `PneumaticPanelState`, and the `getPanelState` / `applyPanelState` controllers
+  (surfaced on the facade as `getState()` / `applyState()`).
+- **Panel hover events** — `panelHoverEnter` / `panelHoverExit`, with
+  `onPanelHoverEnter` / `onPanelHoverExit` subscribe controllers and
+  `panelHitboxHoverEnter` / `panelHitboxHoverExit` notify controllers, wired through
+  `PneumaticPanelSelectUC` and the Babylon hitbox view.
+- `onCheckPressure` subscribe controller (gauge-click / pressure-check requests).
+
+### Changed
+
+- The reactive view model is now consumed through the facade's `onViewModel(cb)`. The
+  raw `pneumaticPanelPMAdapter` export remains for the framework/view boundary and
+  advanced use but is no longer the advertised consumer surface.
+- Panel hover highlight now uses a `SelectionOutlineLayer` for a pixel-space,
+  see-through silhouette (`PanelOutlineController`), replacing the earlier
+  inverted-hull outline, which itself replaced the original hitbox glow.
+- Panel construction is now idempotent (`getOrCreate` semantics in
+  `PneumaticPanelRepo`): creating an instance for an existing id returns the existing
+  entity instead of duplicating it.
+
+## [1.1.1] - 2026-06-15
+
+### Fixed
+
+- `onCheckPressure` subscribe controller was missing — gauge click events now appear in the dev panel event log.
+- Babylon Inspector is restored in the dev playground and opens automatically on load.
+
+### Added
+
+- Clear button in the dev panel Events header — clears the event log on click.
+
+## [1.1.0] - 2026-06-15
+
+### Added
+
+- **Panel hitbox** (`PneumaticPanelHitboxView`) — an invisible mesh covering the entire panel for whole-panel selection mode. When enabled, the panel acts as a single clickable target and all sub-component interactions are disabled.
+- `enablePanelHitbox(id, appObjects)` — enables the panel hitbox.
+- `disablePanelHitbox(id, appObjects)` — disables the hitbox and restores sub-component interactivity.
+- `onPanelSelected(id, appObjects, callback)` — subscribes to panel-hitbox click events; returns an unsubscribe function.
+- `panelHitboxEnabled` property on `PneumaticPanelEntity` and `PneumaticPanelVM`.
+- `subComponentsInteractive` derived property on `PneumaticPanelVM` (always `!panelHitboxEnabled`).
+- `"panelHitbox"` added as a valid value for `setHighlightedObject`.
+- `PneumaticPanelSelectUC` — new use case managing hitbox lifecycle and panel-selected events.
+- `MockPneumaticPanelSelectUC` — mock for consumer integration tests.
+- PRD-as-executable-spec tests for panel operation (`docs/prd/panel-operation.test.ts`).
+
+### Changed
+
+- Dev sandbox: replaced Babylon Inspector overlay with a lightweight HTML dev panel in the upper-right corner, exposing the three state controls and a live event log.
+- Removed `@babylonjs/inspector` from dev dependencies.
+
+## [1.0.1] - 2026-06-05
+
+### Fixed
+
+- Added `prepublishOnly` script to ensure the package is built before publishing, preventing accidental publishes of stale or missing `dist` output.
+
+## [1.0.0] - 2026-05-28
+
+### Added
+
+- **Lock View** (`PneumaticPanelLockView`) — Manages lock/ghost-lock visibility, click-to-toggle, and ghost-lock hover preview.
+- **Exhaust View** (`PneumaticPanelExhaustView`) — Manages exhaust knob interaction and rotation.
+- **Gauge View** (`PneumaticPanelGaugeView`) — Click the gauge to trigger `checkPressure`.
+- **Asset Cache** (`PneumaticPanelAssetCache`) — Caches loaded GLB assets to avoid redundant downloads across instances.
+- Smooth animated rotation for exhaust knob open/close (cubic ease-in-out, ~250ms).
+- Shake animation on the exhaust knob when toggling is blocked by a locked panel.
+- Red overlay flash on lock meshes when a locked exhaust toggle is attempted.
+- Ghost-lock hover preview: semi-transparent lock appears on pointer hover when exhaust is open and unlocked.
+- `showGhostLockHint` property on `PneumaticPanelEntity` — when `true`, the ghost lock is shown immediately without requiring hover (training mode); when `false` (default), the ghost lock is only revealed on hover (assessment mode).
+- Dev playground inspector setup (`setupInspector.ts`).
+- Direct subscription hooks on domain UCs for Slide integration without a global event bus:
+  - `PneumaticPanelToggleLockUC.subscribeOnPanelLocked`
+  - `PneumaticPanelToggleLockUC.subscribeOnPanelUnlocked`
+  - `PneumaticPanelToggleExhaustUC.subscribeOnExhaustOpened`
+  - `PneumaticPanelToggleExhaustUC.subscribeOnExhaustClosed`
+  - `PneumaticPanelToggleExhaustUC.subscribeOnExhaustCloseBlockedByLock`
+  - `PneumaticPanelCheckPressureUC.subscribeOnCheckPressure`
+- New dedicated UC test files:
+  - `PneumaticPanelToggleLockUC.test.ts`
+  - `PneumaticPanelToggleExhaustUC.test.ts`
+
+### Changed
+
+- `PneumaticPanelBabylonView` refactored to delegate per-element behavior to dedicated view components (`ExhaustView`, `LockView`, `GageView`).
+- `createBabylonPneumaticPanel` simplified; view composition now handled by `PneumaticPanelBabylonView`.
+- `PneumaticPanelToggleLockUC` — lock can only be engaged when exhaust is open.
+- `PneumaticPanelToggleLockUC` now dispatches subscribed callbacks after lock/unlock transitions.
+- `PneumaticPanelToggleExhaustUC` now dispatches subscribed callbacks for open/close and blocked-close attempts.
+- `PneumaticPanelCheckPressureUC` now dispatches subscribed callbacks after every `checkPressure()` invocation.
+- Updated `COMPONENT_KNOWLEDGE.md` with full API reference, recipes, and constraints.