@vived/component-hmi

HMI — VIVED Smart Component

An industrial Human-Machine Interface panel for VIVED slide applications. Provides programmatic power control, a safety-guarded cycle-start, a lit screen that tracks power state, and an optional whole-panel Equipment Hitbox — packaged as a self-contained domain plus a Babylon.js view.

Features

• Power control — powerOn / powerOff / togglePower, driven by the host. There is no power click target on the panel itself.
• Guarded cycle-start — clicking the green button starts a cycle only while the panel is powered. A blocked attempt is reported as its own event rather than failing silently.
• Powered screen visual — the screen mesh drives its emissive off isPoweredOn.
• Equipment Hitbox — off by default. Enabled, an invisible mesh makes the whole panel one pick target and the sub-components go inert; the component reports the click as hmiSelected and takes no view of what it should mean.
• Multi-instance — any number of independent panels in the same scene.

Quick Start

npm install @vived/component-hmi @vived/core @vived/app @babylonjs/core @babylonjs/loaders

Peer dependencies:

• @vived/core ^2.0.0
• @vived/app ^6.2.0 — supplies the host's shared asset system
• @babylonjs/core ^9.0.0
• @babylonjs/loaders ^9.0.0

The host-facing surface is the HMIFacade — 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 { HMIFacade, makeHMIFeatureFactory } from "@vived/component-hmi";

const appObjects = makeAppObjectRepo();
const factoryRepo = makeDomainFactoryRepo(appObjects);

makeHMIFeatureFactory(appObjects); // register the feature once
factoryRepo.setupDomain();

const facade = new HMIFacade("hmi-1", appObjects); // sync, Babylon-free
await facade.load(); // attaches the Babylon view

facade.powerOn();
facade.startCycle(); // true — the panel is powered

API

Commands

| Method | Returns | Description | | --- | --- | --- | | powerOn() | boolean | Power the panel on. | | powerOff() | boolean | Power the panel off. | | togglePower() | boolean | Toggle power. | | startCycle() | boolean | Attempt a cycle-start. false if blocked (unpowered). | | enableHitbox() | void | Make the whole panel one pick target. | | disableHitbox() | void | Hand interactivity back to the sub-components. |

Events (onEvent)

All five are payload-free; read current values off the view model.

| Key | Fires when | | --- | --- | | poweredOn | Panel transitioned off → on | | poweredOff | Panel transitioned on → off | | cycleStarted | Cycle-start succeeded | | cycleStartBlocked | Cycle-start was attempted while unpowered | | hmiSelected | The Equipment Hitbox was clicked |

import { HMIEventKeys } from "@vived/component-hmi";

const off = facade.onEvent(HMIEventKeys.cycleStartBlocked, () => {
  console.log("cycle blocked — panel is off");
});

Reactive view model

const unsubscribe = facade.onViewModel((vm) => {
  // { isPoweredOn, canCycleStart, isHitboxEnabled, areSubComponentsInteractive }
});

Persisted state

getState() returns a versioned snapshot of authored intent; applyState() restores it best-effort — present fields are applied, absent ones default, and version drift never throws.

const snapshot = facade.getState(); // { version: 2, isPoweredOn, isHitboxEnabled }
facade.applyState(snapshot);

The flat controllers and hmiPMAdapter 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, and docs/host-integration.md for wiring the component into a host scene.

Development

npm install
npm run dev            # playground
npm run test           # run tests
npm run test:watch     # watch mode
npm run test:coverage  # coverage report
npm run lint           # eslint over src
npm run build          # production build + type declarations

Architecture

See COMPONENT_ARCHITECTURE.md for internal design details.

License

Proprietary — VIVED Learning