@vscada/cli 0.0.1

package/dist/.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/scene-path.ts","../src/scene-plugin.ts","../src/template-registry.ts","../src/bin/vscada.ts","../src/commands/preview.ts"],"version":"5.9.3"}

package/dist/bin/vscada.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { printReady, runPreview } from '../commands/preview.js';
+import { TEMPLATES } from '../template-registry.js';
+const USAGE = [
+    'Usage: vscada preview <scene-file> [--seed <n>] [--port <n>] [--theme <name>]',
+    '   or: vscada preview --template <name> [--seed <n>] [--port <n>] [--theme <name>]',
+    `Templates: ${TEMPLATES.map((t) => t.name).join(', ')}`,
+].join('\n');
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    if (command !== 'preview') {
+        console.error(command ? `Unknown command: "${command}"` : 'Missing command.');
+        console.error(USAGE);
+        process.exitCode = 1;
+        return;
+    }
+    const { values, positionals } = parseArgs({
+        args: rest,
+        options: {
+            seed: { type: 'string' },
+            port: { type: 'string' },
+            theme: { type: 'string' },
+            template: { type: 'string' },
+        },
+        allowPositionals: true,
+    });
+    const [sceneFile] = positionals;
+    // Story 5.4 Task 1 (AC1) — `--template <name>` is an alternative to
+    // <scene-file>, not an addition to it: exactly one source of truth for
+    // which scene gets served.
+    if (sceneFile && values.template !== undefined) {
+        console.error('Pass either <scene-file> or --template, not both.');
+        console.error(USAGE);
+        process.exitCode = 1;
+        return;
+    }
+    if (!sceneFile && values.template === undefined) {
+        console.error('Missing <scene-file> argument or --template.');
+        console.error(USAGE);
+        process.exitCode = 1;
+        return;
+    }
+    const options = {
+        sceneFile,
+        template: values.template,
+        cwd: process.cwd(),
+        seed: values.seed !== undefined ? Number(values.seed) : undefined,
+        port: values.port !== undefined ? Number(values.port) : undefined,
+        theme: values.theme,
+    };
+    const result = await runPreview(options);
+    printReady(options, result);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/commands/preview.js

@@ -0,0 +1,53 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createServer } from 'vite';
+import { resolveSceneFile } from '../scene-path.js';
+import { sceneLoaderPlugin } from '../scene-plugin.js';
+import { resolveTemplate } from '../template-registry.js';
+const here = dirname(fileURLToPath(import.meta.url));
+// From dist/commands/preview.js: up to dist/commands's parent (dist/), up to
+// the package root (packages/cli/), into the shipped-as-source preview app
+// (Task 2 Dev Notes — the preview page is a Vite ROOT, transformed on
+// request, never pre-bundled by this package's own build; see
+// package.json's "files").
+const PREVIEW_APP_ROOT = resolve(here, '../../preview-app');
+const DEFAULT_PORT = 5180;
+/**
+ * Task 1-3 (AC1, AC2) — resolves + validates the scene file, starts a
+ * programmatic Vite dev server rooted at the internal preview app, and
+ * returns the ready-to-open URL. The scene file itself is never imported
+ * here — only the browser (via `sceneLoaderPlugin`'s virtual module) ever
+ * executes it, so `.ts`/`.js`/builder-vs-JSON duck-typing all happen
+ * client-side (Dev Notes).
+ */
+export async function runPreview(options) {
+    const startedAt = Date.now();
+    const { absPath } = options.template !== undefined ? resolveTemplate(options.template) : resolveSceneFile(options.sceneFile, options.cwd);
+    const server = await createServer({
+        root: PREVIEW_APP_ROOT,
+        configFile: false,
+        logLevel: 'warn',
+        server: { port: options.port ?? DEFAULT_PORT },
+        plugins: [sceneLoaderPlugin(absPath)],
+    });
+    await server.listen();
+    const query = new URLSearchParams();
+    if (options.seed !== undefined)
+        query.set('seed', String(options.seed));
+    if (options.theme !== undefined)
+        query.set('theme', options.theme);
+    const resolvedUrls = server.resolvedUrls;
+    const base = resolvedUrls?.local[0] ?? `http://localhost:${options.port ?? DEFAULT_PORT}/`;
+    const url = query.size > 0 ? `${base}?${query.toString()}` : base;
+    return { server, url, elapsedMs: Date.now() - startedAt };
+}
+/** Task 3 (AC1) — the CLI's one-line usage hint, printed once the server is actually listening. */
+export function printReady(options, result) {
+    // eslint-disable-next-line no-console
+    console.log(`\n  vscada preview ready in ${result.elapsedMs}ms\n`);
+    // eslint-disable-next-line no-console
+    console.log(`  ➜  Local:  ${result.url}`);
+    const target = options.template !== undefined ? `templates/${options.template}/scene.ts` : options.sceneFile;
+    // eslint-disable-next-line no-console
+    console.log(`\n  Edit ${target} and save — the preview hot-reloads automatically.\n`);
+}

package/dist/scene-path.js

@@ -0,0 +1,22 @@
+import { existsSync, statSync } from 'node:fs';
+import { extname, resolve } from 'node:path';
+const SUPPORTED_EXTENSIONS = ['.ts', '.js', '.json'];
+/**
+ * Task 1 (AC1) — validates the user's `<scene-file>` argument before a Vite
+ * server is even started, so a typo'd path fails fast with a clear message
+ * instead of a blank browser tab. Duck-typing (builder vs. raw scene JSON,
+ * `.build()` detection) happens client-side in the preview app, which is
+ * the thing that actually executes the module (Dev Notes: "internal
+ * preview page ... loads the user's scene module").
+ */
+export function resolveSceneFile(inputPath, cwd) {
+    const absPath = resolve(cwd, inputPath);
+    if (!existsSync(absPath) || !statSync(absPath).isFile()) {
+        throw new Error(`Scene file not found: ${absPath}`);
+    }
+    const extension = extname(absPath);
+    if (!SUPPORTED_EXTENSIONS.includes(extension)) {
+        throw new Error(`Unsupported scene file type "${extension}" (expected .ts, .js, or .json): ${absPath}`);
+    }
+    return { absPath, extension: extension };
+}

package/dist/scene-plugin.js

@@ -0,0 +1,35 @@
+const VIRTUAL_MODULE_ID = 'virtual:vscada-scene';
+const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
+function toFsUrl(absPath) {
+    // Vite's `/@fs/` escape hatch serves any absolute path outside `root`
+    // (the user's scene file lives in their own project, never inside the
+    // preview app's own source tree) — always forward-slashed, including on
+    // Windows where `path.resolve` yields backslashes.
+    return `/@fs/${absPath.replace(/\\/g, '/')}`;
+}
+/**
+ * Task 2 (AC1, AC2) — bridges the user's own scene file into the preview
+ * app's Vite module graph as `import ... from 'virtual:vscada-scene'`. The
+ * re-export is a thin pass-through, but because Vite resolves the `from`
+ * specifier to the real file, that file becomes a real graph dependency of
+ * this virtual module: editing it on disk invalidates this module too, and
+ * the invalidation bubbles up to `main.ts`'s own
+ * `import.meta.hot.accept('virtual:vscada-scene', ...)` — real HMR, no
+ * process restart, no hand-rolled file watcher.
+ */
+export function sceneLoaderPlugin(sceneAbsPath) {
+    return {
+        name: 'vscada:scene-loader',
+        resolveId(id) {
+            if (id === VIRTUAL_MODULE_ID)
+                return RESOLVED_VIRTUAL_MODULE_ID;
+            return undefined;
+        },
+        load(id) {
+            if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+                return `export { default } from ${JSON.stringify(toFsUrl(sceneAbsPath))};`;
+            }
+            return undefined;
+        },
+    };
+}

package/dist/template-registry.js

@@ -0,0 +1,42 @@
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const here = dirname(fileURLToPath(import.meta.url));
+// From dist/template-registry.js: one level up is the package root
+// (packages/cli/), same relationship `commands/preview.ts` uses for
+// PREVIEW_APP_ROOT — the shipped templates are source (.ts), never
+// pre-bundled by this package's own `tsc -b` (they're outside `src/`, same
+// reasoning as `test-fixtures/builder-scene.ts`).
+const DEFAULT_TEMPLATES_ROOT = resolve(here, '../templates');
+/**
+ * Story 5.4 Task 1 (AC1) — the five templates decided in
+ * spec-amendments.md §C2. Order here is authoring/discovery order, not
+ * significance; `waste-to-energy` is the flagship (AC2) but ships second
+ * because `hello-tank` is deliberately the very first thing a new dev
+ * copies (Dev Notes: "the 10-minute quickstart").
+ */
+export const TEMPLATES = [
+    { name: 'hello-tank', title: 'Hello Tank — 10-minute quickstart' },
+    { name: 'waste-to-energy', title: 'Waste-to-Energy line (§16 reference scene)' },
+    { name: 'boiler-turbine-generator', title: 'Boiler → Turbine → Generator loop (power gen)' },
+    { name: 'substation-single-line', title: 'Substation single-line diagram (power gen)' },
+    { name: 'conveyor-batching', title: 'Conveyor / batching line (manufacturing)' },
+];
+const TEMPLATE_NAMES = new Set(TEMPLATES.map((t) => t.name));
+/**
+ * Resolves a `--template <name>` argument to its `scene.ts` on disk — the
+ * `--template` counterpart to `scene-path.ts#resolveSceneFile`. Unknown
+ * names fail fast with the full available list (discoverability, AC1)
+ * rather than a bare ENOENT.
+ */
+export function resolveTemplate(name, templatesRoot = DEFAULT_TEMPLATES_ROOT) {
+    if (!TEMPLATE_NAMES.has(name)) {
+        const available = TEMPLATES.map((t) => t.name).join(', ');
+        throw new Error(`Unknown template "${name}". Available templates: ${available}`);
+    }
+    const absPath = resolve(templatesRoot, name, 'scene.ts');
+    if (!existsSync(absPath)) {
+        throw new Error(`Template "${name}" is registered but its scene file is missing: ${absPath}`);
+    }
+    return { absPath, extension: '.ts' };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@vscada/cli",
+  "version": "0.0.1",
+  "description": "VScada preview CLI — `vscada preview <scene-file>`, hot-reloading scene authoring (Story 5.3)",
+  "type": "module",
+  "sideEffects": false,
+  "license": "UNLICENSED",
+  "bin": {
+    "vscada": "./dist/bin/vscada.js"
+  },
+  "files": [
+    "dist",
+    "preview-app",
+    "templates"
+  ],
+  "dependencies": {
+    "vite": "~8.1.5",
+    "@vscada/builder": "0.0.1",
+    "@vscada/core": "0.0.1",
+    "@vscada/primitives": "0.0.1",
+    "@vscada/sim": "0.0.1",
+    "@vscada/themes": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "~5.9.3",
+    "vitest": "~4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -b && chmod +x dist/bin/vscada.js",
+    "typecheck": "tsc -b && tsc --noEmit -p preview-app && tsc --noEmit -p templates",
+    "test": "vitest run"
+  }
+}

package/preview-app/index.html

@@ -0,0 +1,55 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>vscada preview</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+        background: #1e1f20;
+        color: #e8eaec;
+        font-family: system-ui, sans-serif;
+      }
+      #app {
+        position: fixed;
+        inset: 0;
+      }
+      scada-view {
+        display: block;
+        width: 100%;
+        height: 100%;
+      }
+      #vscada-error-overlay {
+        position: fixed;
+        inset: 0;
+        z-index: 9999;
+        display: none;
+        background: rgba(20, 8, 8, 0.94);
+        color: #ffb4b4;
+        font-family: ui-monospace, 'SF Mono', Menlo, monospace;
+        font-size: 14px;
+        line-height: 1.6;
+        padding: 32px;
+        overflow: auto;
+        box-sizing: border-box;
+      }
+      #vscada-error-overlay h1 {
+        color: #ff6b6b;
+        font-size: 16px;
+        margin: 0 0 16px;
+      }
+      #vscada-error-overlay ul {
+        margin: 0;
+        padding-left: 20px;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <div id="vscada-error-overlay" role="alert"></div>
+    <script type="module" src="/main.ts"></script>
+  </body>
+</html>

package/preview-app/main.ts

@@ -0,0 +1,149 @@
+import {
+  ScadaView,
+  defaultTimeSource,
+  defineScadaView,
+  registerConnectionRenderer,
+  registerPrimitives,
+  registerThemes,
+  type TimeSource,
+} from '@vscada/core';
+import { validateScene, type SceneValidationIssue } from '@vscada/core/scene-authoring';
+import { classicHmi } from '@vscada/themes';
+import { annotation } from '@vscada/primitives/annotation';
+import { conveyance, pipeConnectionRenderer } from '@vscada/primitives/conveyance';
+import { controls } from '@vscada/primitives/controls';
+import { electrical } from '@vscada/primitives/electrical';
+import { filtration } from '@vscada/primitives/filtration';
+import { heat } from '@vscada/primitives/heat';
+import { instruments } from '@vscada/primitives/instruments';
+import { readout } from '@vscada/primitives/readout';
+import { rotating } from '@vscada/primitives/rotating';
+import { valves } from '@vscada/primitives/valves';
+import { vapor } from '@vscada/primitives/vapor';
+import { vessels } from '@vscada/primitives/vessels';
+import { createSimulator, type Simulator } from '@vscada/sim';
+// The bridge to the user's own scene file — the CLI's Vite plugin resolves
+// this specifier to `export { default } from '/@fs/<absolute path>'`
+// (`../src/scene-plugin.ts`), so this import IS the "load the user's scene
+// module" step (Dev Notes, Task 2). Editing the real file on disk drives
+// this import through Vite's HMR graph into the `accept` call below.
+import sceneEntry from 'virtual:vscada-scene';
+
+declare global {
+  interface Window {
+    /**
+     * Story 5.4 Task 5 — same seam `apps/demo`'s visual-regression harness
+     * uses (Story 1.7 Task 3): Playwright's `page.addInitScript` injects
+     * this before this module runs, so a template baseline can tick the
+     * animation clock on demand instead of racing real time.
+     */
+    __VSCADA_TEST_TIME_SOURCE__?: TimeSource;
+    /**
+     * Only defined in test mode (i.e. when `__VSCADA_TEST_TIME_SOURCE__` is
+     * present) — advances `@vscada/sim` by `dtMs` and pushes the result,
+     * replacing `sim.start()`'s real-time `setInterval` loop so a baseline
+     * capture's pushed values are as deterministic as its animation frame.
+     */
+    __vscadaSimStep?: (dtMs: number) => void;
+  }
+}
+
+// Task 2 (AC1) — one full-kit registration, matching apps/demo/src/main.ts's
+// precedent: the preview app is a generic authoring surface that must
+// render ANY scene the user hands it, so (unlike a real product embed) it
+// cannot know ahead of time which primitive groups a given scene needs.
+defineScadaView();
+registerThemes(classicHmi);
+registerPrimitives(vessels, readout, conveyance, rotating, annotation, valves, instruments, heat, filtration, vapor, controls, electrical);
+registerConnectionRenderer(pipeConnectionRenderer);
+
+const params = new URLSearchParams(location.search);
+const seedParam = params.get('seed');
+const seed = seedParam !== null && seedParam !== '' ? Number(seedParam) : undefined;
+const requestedTheme = params.get('theme') ?? undefined;
+
+const testTimeSource = window.__VSCADA_TEST_TIME_SOURCE__;
+const view = new ScadaView(testTimeSource ?? defaultTimeSource);
+if (testTimeSource) view.stalenessTimeout = 3000; // apps/demo's own precedent — a watchable/testable timeline, not the 10s production default
+
+document.querySelector<HTMLDivElement>('#app')!.appendChild(view);
+
+const overlay = document.querySelector<HTMLDivElement>('#vscada-error-overlay')!;
+
+function showError(issues: SceneValidationIssue[]): void {
+  overlay.replaceChildren();
+  const heading = document.createElement('h1');
+  heading.textContent = `Scene validation failed (${issues.length} issue${issues.length === 1 ? '' : 's'})`;
+  overlay.appendChild(heading);
+  const list = document.createElement('ul');
+  for (const issue of issues) {
+    const item = document.createElement('li');
+    item.textContent = issue.path ? `${issue.path}: ${issue.message}` : issue.message;
+    list.appendChild(item);
+  }
+  overlay.appendChild(list);
+  overlay.style.display = 'block';
+}
+
+function hideError(): void {
+  overlay.style.display = 'none';
+}
+
+function buildSceneRaw(candidate: unknown): unknown {
+  // Dev Notes' duck-typed scene-module contract: default export = scene
+  // JSON | builder chain — "call `.build()` if it quacks like a builder".
+  if (candidate && typeof candidate === 'object' && typeof (candidate as { build?: unknown }).build === 'function') {
+    return (candidate as { build: () => unknown }).build();
+  }
+  return candidate;
+}
+
+let sim: Simulator | undefined;
+
+/**
+ * Task 2 (AC1, AC2) — the single entry point for both the first render and
+ * every hot-reload. Validation failures (bad shape, not JS/import errors —
+ * those are Vite's own overlay's job) render the full Zod diagnostic list
+ * IN the page and leave the previously-good scene/simulator running,
+ * exactly as Dev Notes specifies: "fixed on next save without restart".
+ */
+function applyScene(candidate: unknown): void {
+  let raw: unknown;
+  try {
+    raw = buildSceneRaw(candidate);
+  } catch (error) {
+    showError([{ path: '', message: error instanceof Error ? error.message : String(error) }]);
+    return;
+  }
+
+  if (requestedTheme && raw && typeof raw === 'object') {
+    raw = { ...(raw as Record<string, unknown>), theme: requestedTheme };
+  }
+
+  const result = validateScene(raw);
+  if (!result.success) {
+    showError(result.issues);
+    return;
+  }
+
+  hideError();
+  sim?.stop();
+  view.scene = result.data;
+  sim = createSimulator(result.data, seed !== undefined ? { seed } : {});
+  if (testTimeSource) {
+    // Deterministic path (Task 5): the caller drives ticks via `__vscadaSimStep`
+    // instead of the simulator's own real-time interval.
+    window.__vscadaSimStep = (dtMs: number) => view.setValues(sim!.step(dtMs));
+  } else {
+    sim.start((values) => view.setValues(values));
+  }
+}
+
+applyScene(sceneEntry);
+
+if (import.meta.hot) {
+  import.meta.hot.accept('virtual:vscada-scene', (mod) => {
+    if (!mod) return; // module removed from the graph — keep the last good render up
+    applyScene((mod as { default?: unknown }).default);
+  });
+}

package/preview-app/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "emitDeclarationOnly": false,
+    "noEmit": true
+  },
+  "include": ["."]
+}

package/preview-app/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+// `../src/scene-plugin.ts` resolves this specifier to
+// `export { default } from '/@fs/<the user's absolute scene path>'` — the
+// default export's real shape (scene JSON | builder chain) is unknown
+// until runtime duck-typing in `main.ts`'s `buildSceneRaw`.
+declare module 'virtual:vscada-scene' {
+  const sceneEntry: unknown;
+  export default sceneEntry;
+}

package/templates/boiler-turbine-generator/README.md

@@ -0,0 +1,9 @@
+# boiler-turbine-generator
+
+A condensed power-generation loop: boiler → steam control valve → turbine → condenser → feedwater pump → back to the boiler (the same recycle-loop shape as `waste-to-energy`, exercising topology cycle detection again in a much smaller scene), plus an electrical tie showing the turbine's generator feeding a breaker and busbar.
+
+Run it:
+
+```sh
+vscada preview --template boiler-turbine-generator
+```

package/templates/boiler-turbine-generator/scene.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { assertSchemaValid, assertSimCoversEveryBoundTag } from '../template-test-utils';
+import sceneBuilder from './scene';
+
+describe('boiler-turbine-generator template (Story 5.4 Task 4)', () => {
+  const scene = sceneBuilder.build();
+
+  it('builds a schema-valid scene', () => {
+    assertSchemaValid(scene);
+  });
+
+  it('has a steam loop and an electrical tie', () => {
+    const typesById = new Map(scene.elements.map((el) => [el.id, el.type]));
+    expect(typesById.get('BLR-01')).toBe('boiler');
+    expect(typesById.get('TRB-01')).toBe('turbine');
+    expect(typesById.get('GEN-01')).toBe('generator');
+    expect(typesById.get('BRK-01')).toBe('breaker');
+    expect(typesById.get('BUS-01')).toBe('busbar');
+    // The recycle loop closes back onto the boiler's own feedwater inlet.
+    expect(scene.connections.find((c) => c.id === 'C-FW')).toMatchObject({ from: 'PMP-01.discharge', to: 'BLR-01.feedwater-inlet' });
+  });
+
+  it('gives the simulator generator coverage for every bound tag', () => {
+    assertSimCoversEveryBoundTag(scene);
+  });
+});

package/templates/boiler-turbine-generator/scene.ts

@@ -0,0 +1,91 @@
+import { boiler, breaker, busbar, condenser, createScene, generator, pumpCentrifugal, turbine, valveControl } from '@vscada/builder';
+
+/**
+ * boiler-turbine-generator — a condensed power-generation loop (Story 5.4
+ * Task 4, spec-amendments §C2 item 3): the same steam/water recycle loop as
+ * `waste-to-energy` (boiler → valve → turbine → condenser → feedwater pump
+ * → back to the drum), plus an electrical tie (generator → breaker →
+ * busbar) showing the turbine's output leaving the plant. Deliberately
+ * sized much smaller than `waste-to-energy` — no gas train, no gauges, no
+ * status bar — this template's whole point is the steam loop + electrical
+ * tie, nothing else.
+ */
+const boilerDrum = boiler('BLR-01')
+  .at(40, 40)
+  .label('Boiler drum')
+  .bind(
+    { tag: 'BTG_BLR01.level', type: 'level', min: 0, max: 100, unit: '%' },
+    { tag: 'BTG_BLR01.pressure', type: 'readout', unit: 'bar', decimals: 1 },
+  );
+
+const steamValve = valveControl('VLV-01').at(200, 80).label('Steam control valve').bind({ tag: 'BTG_VLV01.pos', type: 'position', min: 0, max: 100 });
+
+const turbineEl = turbine('TRB-01')
+  .at(300, 60)
+  .label('Turbine')
+  .bind({ tag: 'BTG_TRB01.power', type: 'readout', unit: 'MW', decimals: 1 }, { tag: 'BTG_TRB01.rpm', type: 'rotate', min: 0, max: 3600 });
+
+const condenserEl = condenser('CND-01').at(450, 70).label('Condenser');
+
+const feedPump = pumpCentrifugal('PMP-01')
+  .at(620, 70)
+  .label('Feedwater pump')
+  .bind(
+    { tag: 'BTG_PMP01.state', type: 'state', map: { '0': 'stopped', '1': 'running' } },
+    { tag: 'BTG_PMP01.rpm', type: 'rotate', min: 0, max: 1800 },
+  );
+
+const generatorEl = generator('GEN-01')
+  .at(300, 200)
+  .label('Generator')
+  .bind(
+    { tag: 'BTG_GEN01.power', type: 'readout', unit: 'MW', decimals: 1 },
+    { tag: 'BTG_GEN01.state', type: 'state', map: { '0': 'offline', '1': 'online' } },
+  );
+
+const tieBreaker = breaker('BRK-01').at(420, 220).label('Generator breaker').bind({ tag: 'BTG_BRK01.state', type: 'state', map: { '0': 'open', '1': 'closed' } });
+
+const bus = busbar('BUS-01').at(520, 235).label('Plant bus').bind({ tag: 'BTG_BUS01.state', type: 'state', map: { '0': 'de-energized', '1': 'energized' } });
+
+export default createScene('boiler-turbine-generator', {
+  canvas: { width: 850, height: 320 },
+  title: 'Boiler → Turbine → Generator',
+  theme: 'classic-hmi',
+})
+  .add(boilerDrum)
+  .add(steamValve)
+  .add(turbineEl)
+  .add(condenserEl)
+  .add(feedPump)
+  .add(generatorEl)
+  .add(tieBreaker)
+  .add(bus)
+  .connect(boilerDrum.port('steam-outlet'), steamValve.port('inlet'), {
+    id: 'C-STM1',
+    medium: 'steam',
+    bindings: [{ tag: 'BTG_STM01.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(steamValve.port('outlet'), turbineEl.port('inlet'), {
+    id: 'C-STM2',
+    medium: 'steam',
+    bindings: [{ tag: 'BTG_STM02.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(turbineEl.port('outlet'), condenserEl.port('inlet'), {
+    id: 'C-STM3',
+    medium: 'steam',
+    bindings: [{ tag: 'BTG_STM03.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(condenserEl.port('outlet'), feedPump.port('suction'), {
+    id: 'C-COND',
+    medium: 'condensate',
+    bindings: [{ tag: 'BTG_COND01.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  // Recycle loop — same cycle-detection exercise as waste-to-energy's own loop.
+  .connect(feedPump.port('discharge'), boilerDrum.port('feedwater-inlet'), {
+    id: 'C-FW',
+    medium: 'feedwater',
+    bindings: [{ tag: 'BTG_FW01.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(generatorEl.port('output'), tieBreaker.port('line-in'), { id: 'C-ELEC1', medium: 'electricity' })
+  .connect(tieBreaker.port('line-out'), bus.port('line-in'), { id: 'C-ELEC2', medium: 'electricity' })
+  .inferTopology();

package/templates/conveyor-batching/README.md

@@ -0,0 +1,9 @@
+# conveyor-batching
+
+The manufacturing vertical: feed hopper → screw feeder → conveyor → batching vessel, with a small selector-switch/pushbutton control panel. The lightest of the five templates.
+
+Run it:
+
+```sh
+vscada preview --template conveyor-batching
+```

package/templates/conveyor-batching/scene.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { assertSchemaValid, assertSimCoversEveryBoundTag } from '../template-test-utils';
+import sceneBuilder from './scene';
+
+describe('conveyor-batching template (Story 5.4 Task 4)', () => {
+  const scene = sceneBuilder.build();
+
+  it('builds a schema-valid scene', () => {
+    assertSchemaValid(scene);
+  });
+
+  it('runs hopper → screw feeder → conveyor → batching vessel, with a selector/pushbutton panel', () => {
+    const typesById = new Map(scene.elements.map((el) => [el.id, el.type]));
+    expect(typesById.get('HPR-01')).toBe('hopper');
+    expect(typesById.get('SCF-01')).toBe('screw-feeder');
+    expect(typesById.get('CNV-01')).toBe('conveyor');
+    expect(typesById.get('DRM-01')).toBe('drum');
+    expect(typesById.get('SEL-01')).toBe('selector-switch');
+    expect(typesById.get('PB-01')).toBe('pushbutton');
+    expect(scene.connections.map((c) => `${c.from}->${c.to}`)).toEqual([
+      'HPR-01.outlet-bot->SCF-01.inlet-top',
+      'SCF-01.outlet->CNV-01.infeed',
+      'CNV-01.discharge->DRM-01.inlet-top',
+    ]);
+  });
+
+  it('gives the simulator generator coverage for every bound tag', () => {
+    assertSimCoversEveryBoundTag(scene);
+  });
+});