@vived/component-stacklight

Stack Light — VIVED Smart Component

A reusable 3D stack light component for VIVED slide apps. Provides domain logic (entities, use cases, presentation managers) and a Babylon.js view for a three-color (red, yellow, green) stack light with steady and blinking modes.

Installation

npm install @vived/component-stacklight

Peer dependencies:

• @babylonjs/core ^9.0.0
• @vived/core ^2.0.0

Usage

import {
  makeStackLightFeatureFactory,
  StackLightRepo,
  StackLightToggleActiveUC,
  StackLightBlinkLoopUC,
  makeStackLightBabylonView,
} from "@vived/component-stacklight";
import { makeAppObjectRepo, makeDomainFactoryRepo } from "@vived/core";

// Setup
const appObjects = makeAppObjectRepo();
const domainFactoryRepo = makeDomainFactoryRepo(appObjects);
makeStackLightFeatureFactory(appObjects);
domainFactoryRepo.setupDomain();

// Create an instance
const repo = StackLightRepo.get(appObjects)!;
repo.createStackLightEntity("light-1");

// Create and bind the Babylon.js view
const ao = appObjects.getOrCreate("light-1");
const view = makeStackLightBabylonView(ao);
await view.setupView();
view.bindMeshes(loadedMeshes); // meshes from your GLB loader

// Control lights
const uc = StackLightToggleActiveUC.getById("light-1", appObjects)!;
uc.setLightActive("red", true); // steady on
uc.setLightBlinking("yellow", true); // starts blinking automatically

// Configure blink speed (optional, default 500ms)
const blinkUc = StackLightBlinkLoopUC.getById("light-1", appObjects)!;
blinkUc.blinkIntervalMs = 1000; // 1 second blink cycle

Blinking

The StackLightBlinkLoopUC automatically manages the blink animation. When any light is set to blinking mode via setLightBlinking(), the UC starts an internal requestAnimationFrame loop that toggles the blink phase at the configured interval. When no lights are blinking, the loop stops automatically. No external timer management is needed.

Development

npm install
npm run dev              # Vite dev server with 3D playground
npm run dev:watch        # Watch mode library rebuild
npm run test             # Run unit tests
npm run lint             # ESLint
npm run build            # Production build

Asset Upload Script

A reusable CLI script for uploading asset files (GLB models, textures, etc.) to the VIVED Asset System. This script is package-agnostic and can be copied to any smart component repo.

Prerequisites

• Node.js 18+
• A VIVED account with API access

Commands

Create a new asset:

npm run upload-asset -- create <filePath>

Uploads the file and creates a new asset record. Prints the new asset ID to stdout.

Update an existing asset's file:

npm run upload-asset -- update <assetId> <filePath>

Uploads the file and updates the asset record to point to the new file.

Examples

# Upload the StackLight GLB as a new asset
npm run upload-asset -- create public/StackLight.glb

# Update an existing asset with a new version of the file
npm run upload-asset -- update 82ae4e17-ad8d-47e3-a3d5-dac8bf530d32 public/StackLight.glb

After uploading

After creating a new asset, add the returned asset ID to src/component.config.ts:

assets: [
  { name: "default", id: "<asset-id>", file: "StackLight.glb" },
  { name: "compact", id: "<asset-id>", file: "StackLight_Compact.glb" },
],

Consuming apps can then look up assets by name:

import { componentConfig } from "@vived/component-stacklight";
const glb = componentConfig.assets.find((a) => a.name === "default");

How it works

1. Reads the owner ID from package.json name field
2. Derives the asset name from the filename (e.g. StackLight.glb → StackLight)
3. Prompts interactively for VIVED credentials (email + password)
4. Authenticates via AWS Cognito
5. Uploads the file to VIVED storage via a signed URL
6. Creates or updates the asset metadata record via the VIVED API

Progress and status messages are printed to stderr. The asset ID (on create) is printed to stdout, making it easy to capture in scripts:

ASSET_ID=$(npm run upload-asset -- create public/StackLight.glb 2>/dev/null)