@vived/component-pneumatic-panel

A 3D interactive pneumatic control panel for VIVED slide applications. Features a rotatable exhaust valve, safety lock mechanism with ghost-lock preview, and a pressure gauge — all with enforced interlocking business rules.

Features

• Exhaust Valve — Click to toggle open/closed with smooth animated rotation. Automatically manages pressure (0 PSI when open, 60 PSI when closed).
• Safety Lock — Engage when the exhaust is open to prevent toggling. Ghost-lock preview appears on hover. Clicking a locked exhaust knob triggers a shake animation and red flash on the lock.
• Pressure Gauge — Click to display current pressure via alert dialog.
• Multi-instance — Create multiple independent panels in the same scene.

Quick Start

npm install @vived/component-pneumatic-panel @vived/core @babylonjs/core

The host-facing surface is the PneumaticPanelFacade — a single typed object (Smart Component Facade Contract v1) that drives an instance through commands, typed events, lifecycle, and persisted state.

import { makeAppObjectRepo, makeDomainFactoryRepo } from "@vived/core";
import {
  makePneumaticPanelFeatureFactory,
  PneumaticPanelFacade,
} from "@vived/component-pneumatic-panel";

const appObjects = makeAppObjectRepo();
const factoryRepo = makeDomainFactoryRepo(appObjects);
makePneumaticPanelFeatureFactory(appObjects);
factoryRepo.setupDomain();

const panel = new PneumaticPanelFacade("panel-1", appObjects); // wires the domain stack (sync)
await panel.load(); // attaches and loads the Babylon view

panel.toggleExhaust(); // open exhaust
panel.toggleLock(); // engage lock
panel.toggleExhaust(); // false — blocked by lock

const unsubscribe = panel.onEvent("exhaustOpened", () => console.log("opened"));

Need the raw AppObject (e.g. to parent the root node or register shadow casters)? Use the createBabylonPneumaticPanel(id, appObjects) composition entry point, which creates the same domain stack and view and returns the AppObject.

API

PneumaticPanelFacade implements Contract v1 — eight mandatory members shared by every VIVED smart component, plus component-specific commands and a typed event catalog.

Contract members

| Member | Signature | Description | | ------------------ | ------------------------------------------ | -------------------------------------------------------- | | id | readonly string | Instance identifier. | | interfaceVersion | readonly number | Contract version implemented (1). | | onEvent | (event, cb) => () => void | Subscribe to a typed event; returns unsubscribe. | | onViewModel | (cb) => () => void | Subscribe to the reactive VM (emits immediately). | | load | (variant?) => Promise<void> | Attach and load the Babylon view. | | destroy | () => void | Tear down and release resources. | | getState | () => PneumaticPanelState | Versioned state snapshot. | | applyState | (state) => void | Restore a snapshot. |

Commands

| Command | Returns | Description | | ----------------------------- | --------- | --------------------------------------------------------- | | toggleExhaust() | boolean | Toggle exhaust valve. Returns false if locked. | | toggleLock() | boolean | Toggle safety lock. Returns false if exhaust is closed. | | checkPressure() | void | Show current pressure in an alert dialog. | | setShowGhostLockHint(show) | void | Toggle always-visible ghost-lock hint. | | enableHitbox() / disableHitbox() | void | Toggle whole-panel selection mode. |

Events (onEvent)

exhaustOpened, exhaustClosed, exhaustCloseBlockedByLock, panelLocked, panelUnlocked, panelSelected, pressureChecked. All callbacks are () => void — read current state from getState() or onViewModel.

Hover/hint/selection feedback is the Host's responsibility (ADR-0009). The component is presentation-free for interaction state — read view.highlightGroupsByObjectId to outline the panel from the invisible hitbox.

Reactive view model

const unsubscribe = panel.onViewModel((vm) => {
  console.log(vm.exhaustOpen, vm.isLocked, vm.pressure, vm.panelHitboxEnabled);
});

The flat controllers and pneumaticPanelPMAdapter remain exported as the underlying mechanism the facade delegates to (and which the Babylon view boundary calls directly), but the facade is the canonical host-facing surface. See COMPONENT_KNOWLEDGE.md for the full API reference, recipes, and the complete export list.

Development

npm install
npm run dev        # playground
npm run test       # run tests
npm run build      # production build

Architecture

See COMPONENT_ARCHITECTURE.md for internal design details.

License

Proprietary — VIVED Learning