@vscada/cli 0.0.1

package/templates/conveyor-batching/scene.ts

@@ -0,0 +1,68 @@
+import { conveyor, createScene, drum, hopper, pushbutton, screwFeeder, selectorSwitch } from '@vscada/builder';
+
+/**
+ * conveyor-batching — Story 5.4 Task 4 / spec-amendments §C2 item 5: the
+ * manufacturing vertical. Feed hopper → screw feeder → conveyor → batching
+ * vessel, with a small selector/pushbutton control panel alongside — much
+ * lighter than `waste-to-energy` by design (Dev Notes: "sized meaningfully
+ * smaller").
+ */
+const feedHopper = hopper('HPR-01')
+  .at(40, 40)
+  .label('Feed hopper')
+  .medium('solid')
+  .bind({ tag: 'CVB_HPR01.level', type: 'level', min: 0, max: 100, unit: '%' });
+
+const feeder = screwFeeder('SCF-01')
+  .at(200, 90)
+  .label('Screw feeder')
+  .bind(
+    { tag: 'CVB_SCF01.state', type: 'state', map: { '0': 'stopped', '1': 'running' } },
+    { tag: 'CVB_SCF01.rpm', type: 'rotate', min: 0, max: 100 },
+  );
+
+const conveyorEl = conveyor('CNV-01')
+  .at(340, 90)
+  .label('Conveyor')
+  .bind(
+    { tag: 'CVB_CNV01.state', type: 'state', map: { '0': 'stopped', '1': 'running' } },
+    { tag: 'CVB_CNV01.speed', type: 'rotate', min: 0, max: 100 }, // drives the belt-dash playback rate
+  );
+
+const batchVessel = drum('DRM-01').at(530, 60).label('Batching vessel').bind({ tag: 'CVB_DRM01.level', type: 'level', min: 0, max: 100, unit: '%' });
+
+const modeSelector = selectorSwitch('SEL-01')
+  .at(680, 60)
+  .label('Mode')
+  .bind({ tag: 'CVB_SEL01.pos', type: 'state', map: { '0': 'off', '1': 'manual', '2': 'auto' } });
+
+// Read-only display per base spec §1.2 (no write-back path — AD-1).
+const stopButton = pushbutton('PB-01').at(680, 110).label('STOP').bind({ tag: 'CVB_PLANT.stop', type: 'state', map: { '0': 'released', '1': 'pressed' } });
+
+export default createScene('conveyor-batching', {
+  canvas: { width: 800, height: 220 },
+  title: 'Conveyor / batching line',
+  theme: 'classic-hmi',
+})
+  .add(feedHopper)
+  .add(feeder)
+  .add(conveyorEl)
+  .add(batchVessel)
+  .add(modeSelector)
+  .add(stopButton)
+  .connect(feedHopper.port('outlet-bot'), feeder.port('inlet-top'), {
+    id: 'C-1',
+    medium: 'solid',
+    bindings: [{ tag: 'CVB_FEED01.flow', type: 'flow', min: 0, max: 50 }],
+  })
+  .connect(feeder.port('outlet'), conveyorEl.port('infeed'), {
+    id: 'C-2',
+    medium: 'solid',
+    bindings: [{ tag: 'CVB_FEED02.flow', type: 'flow', min: 0, max: 50 }],
+  })
+  .connect(conveyorEl.port('discharge'), batchVessel.port('inlet-top'), {
+    id: 'C-3',
+    medium: 'solid',
+    bindings: [{ tag: 'CVB_FEED03.flow', type: 'flow', min: 0, max: 50 }],
+  })
+  .inferTopology();

package/templates/hello-tank/README.md

@@ -0,0 +1,18 @@
+# hello-tank
+
+The 10-minute quickstart. One tank, one pipe, one pump, one gauge — about 20 lines of heavily-commented builder code.
+
+Run it:
+
+```sh
+vscada preview --template hello-tank
+```
+
+Copy it into your own project to start from a working scene instead of a blank canvas:
+
+```sh
+cp -r node_modules/@vscada/cli/templates/hello-tank ./my-scene
+vscada preview ./my-scene/scene.ts
+```
+
+Read `scene.ts` top to bottom — it's the same file the quickstart docs (Story 5.6) walk through line by line.

package/templates/hello-tank/scene.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { assertSchemaValid, assertSimCoversEveryBoundTag } from '../template-test-utils';
+import sceneBuilder from './scene';
+
+describe('hello-tank template (Story 5.4 Task 2, AC1)', () => {
+  const scene = sceneBuilder.build();
+
+  it('builds a schema-valid scene', () => {
+    assertSchemaValid(scene);
+  });
+
+  it('has a tank, a pump, and a gauge, connected by one pipe', () => {
+    const typesById = new Map(scene.elements.map((el) => [el.id, el.type]));
+    expect(typesById.get('T-101')).toBe('tank-vertical');
+    expect(typesById.get('PMP-01')).toBe('pump-centrifugal');
+    expect(typesById.get('PI-01')).toBe('gauge-analog');
+    expect(scene.connections).toHaveLength(1);
+    expect(scene.connections[0]).toMatchObject({ from: 'T-101.outlet-bot', to: 'PMP-01.suction' });
+  });
+
+  it('gives the simulator generator coverage for every bound tag', () => {
+    assertSimCoversEveryBoundTag(scene);
+  });
+});

package/templates/hello-tank/scene.ts

@@ -0,0 +1,50 @@
+import { createScene, gaugeAnalog, pumpCentrifugal, tankVertical } from '@vscada/builder';
+
+/**
+ * hello-tank — the 10-minute quickstart (Story 5.4 AC1; Story 5.6 walks
+ * through this exact file line by line). One tank, one pipe, one pump, one
+ * gauge. Run it with `vscada preview --template hello-tank`, then copy this
+ * directory into your own project and start editing.
+ */
+
+// 1. Every primitive type has a typed factory — `tankVertical(id)` starts a
+//    tank whose scene id is "T-101". Chain calls to place and configure it.
+const tank = tankVertical('T-101')
+  .at(80, 60) // top-left corner, in scene pixels
+  .label('Feed tank')
+  .medium('water') // the active theme colors pipes/fills by medium
+  .bind({ tag: 'T101.level', type: 'level', min: 0, max: 100, unit: '%' }); // drives the fill height
+
+// 2. Relative placement (`.rightOf`) beats hand-picked coordinates once a
+//    scene has more than one or two elements — this pump sits 120px to the
+//    right of the tank, top-aligned with it. (`.alignPorts` is for lining
+//    up two ports that face the SAME axis, e.g. two side ports on a
+//    horizontal run — the tank's outlet faces down, so it isn't a fit here.)
+const pump = pumpCentrifugal('PMP-01')
+  .rightOf(tank.id, 120)
+  .label('Feed pump')
+  .bind({ tag: 'PMP01.status', type: 'state', map: { '0': 'stopped', '1': 'running' } }); // drives the impeller spin
+
+// 3. A gauge reading the pump's discharge pressure, placed below it.
+const gauge = gaugeAnalog('PI-01')
+  .below(pump.id, 40)
+  .label('Discharge PSI')
+  .bind({ tag: 'PMP01.psi', type: 'needle', min: 0, max: 150 });
+
+export default createScene('hello-tank', {
+  canvas: { width: 500, height: 340 },
+  title: 'Hello Tank',
+  theme: 'classic-hmi',
+})
+  .add(tank)
+  .add(pump)
+  .add(gauge)
+  // 4. The "pipe" is a `.connect()` between two ports, not a separate
+  //    element — this one also carries its own `flow` binding so it
+  //    animates while the pump runs.
+  .connect(tank.port('outlet-bot'), pump.port('suction'), {
+    id: 'P-01',
+    medium: 'water',
+    bindings: [{ tag: 'P01.flow', type: 'flow', min: 0, max: 50 }],
+  })
+  .inferTopology(); // derives the topology graph straight from the one .connect() above

package/templates/substation-single-line/README.md

@@ -0,0 +1,9 @@
+# substation-single-line
+
+A single-line diagram: generator → breaker → main bus → breaker → step-down transformer → breaker → secondary bus → feeder breaker. The one template that exercises the electrical primitive group end to end (breakers, transformer, busbars, generator), with `direct` connection routing and an isolated feeder breaker demonstrating energization/isolation.
+
+Run it:
+
+```sh
+vscada preview --template substation-single-line
+```

package/templates/substation-single-line/scene.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { assertSchemaValid, assertSimCoversEveryBoundTag } from '../template-test-utils';
+import sceneBuilder from './scene';
+
+describe('substation-single-line template (Story 5.4 Task 4)', () => {
+  const scene = sceneBuilder.build();
+
+  it('builds a schema-valid scene', () => {
+    assertSchemaValid(scene);
+  });
+
+  it('exercises the electrical primitives with direct routing', () => {
+    const typesById = new Map(scene.elements.map((el) => [el.id, el.type]));
+    expect(typesById.get('GEN-01')).toBe('generator');
+    expect([...typesById.values()].filter((t) => t === 'breaker')).toHaveLength(4);
+    expect([...typesById.values()].filter((t) => t === 'busbar')).toHaveLength(2);
+    expect(typesById.get('TRF-01')).toBe('transformer');
+    for (const connection of scene.connections) {
+      expect(connection.routing).toBe('direct');
+    }
+  });
+
+  it('leaves the feeder breaker downstream port unconnected (the isolation demo)', () => {
+    const feederConnections = scene.connections.filter((c) => c.from.startsWith('BRK-04') || c.to.startsWith('BRK-04'));
+    expect(feederConnections).toHaveLength(1); // only its upstream tie, nothing downstream
+  });
+
+  it('gives the simulator generator coverage for every bound tag', () => {
+    assertSimCoversEveryBoundTag(scene);
+  });
+});

package/templates/substation-single-line/scene.ts

@@ -0,0 +1,63 @@
+import { breaker, busbar, createScene, generator, transformer } from '@vscada/builder';
+
+/**
+ * substation-single-line — Story 5.4 Task 4 / spec-amendments §C2 item 4:
+ * a single-line diagram exercising the electrical primitive group (Story
+ * 3.10's composite "grown up") that no other template touches —
+ * generator → breaker → busbar → breaker → transformer → breaker → busbar
+ * → feeder breaker. Every connection uses `routing: 'direct'` (single-line
+ * diagrams draw straight ties, not orthogonal pipe runs). `BRK-04`, the
+ * feeder breaker, is deliberately left with an unconnected downstream port
+ * — the isolation demo: AD-12's topology-inferred state resolves an
+ * isolated branch's visual state from the breaker's own bound state,
+ * nothing scripted here needs to force it.
+ */
+const gen = generator('GEN-01')
+  .at(40, 120)
+  .label('Generator')
+  .bind(
+    { tag: 'SUB_GEN01.power', type: 'readout', unit: 'MW', decimals: 1 },
+    { tag: 'SUB_GEN01.state', type: 'state', map: { '0': 'offline', '1': 'online' } },
+  );
+
+const brk1 = breaker('BRK-01').at(160, 145).label('Generator breaker').bind({ tag: 'SUB_BRK01.state', type: 'state', map: { '0': 'open', '1': 'closed' } });
+
+const bus1 = busbar('BUS-01').at(270, 150).size(300, 20).label('Main bus').bind({ tag: 'SUB_BUS01.state', type: 'state', map: { '0': 'de-energized', '1': 'energized' } });
+
+const brk2 = breaker('BRK-02').at(610, 145).label('Bus tie breaker').bind({ tag: 'SUB_BRK02.state', type: 'state', map: { '0': 'open', '1': 'closed' } });
+
+const transformerEl = transformer('TRF-01')
+  .at(720, 135)
+  .label('Step-down transformer')
+  .bind({ tag: 'SUB_TRF01.load', type: 'readout', unit: 'MW', decimals: 1 });
+
+const brk3 = breaker('BRK-03').at(830, 145).label('Secondary breaker').bind({ tag: 'SUB_BRK03.state', type: 'state', map: { '0': 'open', '1': 'closed' } });
+
+const bus2 = busbar('BUS-02').at(940, 150).size(300, 20).label('Secondary bus').bind({ tag: 'SUB_BUS02.state', type: 'state', map: { '0': 'de-energized', '1': 'energized' } });
+
+const brk4 = breaker('BRK-04')
+  .at(1280, 145)
+  .label('Feeder breaker (isolated)')
+  .bind({ tag: 'SUB_BRK04.state', type: 'state', map: { '0': 'open', '1': 'closed' } });
+
+export default createScene('substation-single-line', {
+  canvas: { width: 1400, height: 300 },
+  title: 'Substation single-line diagram',
+  theme: 'classic-hmi',
+})
+  .add(gen)
+  .add(brk1)
+  .add(bus1)
+  .add(brk2)
+  .add(transformerEl)
+  .add(brk3)
+  .add(bus2)
+  .add(brk4)
+  .connect(gen.port('output'), brk1.port('line-in'), { id: 'C-1', medium: 'electricity', routing: 'direct' })
+  .connect(brk1.port('line-out'), bus1.port('line-in'), { id: 'C-2', medium: 'electricity', routing: 'direct' })
+  .connect(bus1.port('line-out'), brk2.port('line-in'), { id: 'C-3', medium: 'electricity', routing: 'direct' })
+  .connect(brk2.port('line-out'), transformerEl.port('primary'), { id: 'C-4', medium: 'electricity', routing: 'direct' })
+  .connect(transformerEl.port('secondary'), brk3.port('line-in'), { id: 'C-5', medium: 'electricity', routing: 'direct' })
+  .connect(brk3.port('line-out'), bus2.port('line-in'), { id: 'C-6', medium: 'electricity', routing: 'direct' })
+  .connect(bus2.port('line-out'), brk4.port('line-in'), { id: 'C-7', medium: 'electricity', routing: 'direct' })
+  .inferTopology();

package/templates/template-test-utils.ts

@@ -0,0 +1,49 @@
+import type { AnyElement, Binding, Scene } from '@vscada/core';
+import { validateScene } from '@vscada/core/scene-authoring';
+import { createSimulator } from '@vscada/sim';
+import { expect } from 'vitest';
+
+/** `off-page` elements (Story 2.6) carry a scene-navigation `target`, not tag bindings — every other element type does. */
+export function elementBindings(element: AnyElement | undefined): readonly Binding[] {
+  return element && 'bindings' in element ? element.bindings : [];
+}
+
+/**
+ * Story 5.4 Task 5 — the two assertions every template's own test repeats:
+ * (1) the built scene is schema-valid (redundant with `.build()`'s own
+ * always-on `validateScene` call, but asserted explicitly here so a future
+ * refactor of `SceneBuilder.build()` can't silently start returning
+ * unvalidated data without a test noticing), and (2) `@vscada/sim`'s
+ * generator inference (Story 5.2) produces a value for every tag the scene
+ * itself binds — a template that references a tag with no generator
+ * coverage would sit frozen at "no value yet" forever in a live preview.
+ */
+export function assertSchemaValid(scene: Scene): void {
+  const result = validateScene(scene);
+  if (!result.success) {
+    expect.fail(`scene failed schema validation:\n${JSON.stringify(result.issues, null, 2)}`);
+  }
+}
+
+function allBoundTags(scene: Scene): Set<string> {
+  const tags = new Set<string>();
+  for (const element of scene.elements) {
+    // `off-page` elements (Story 2.6) carry a scene-navigation `target`, not tag bindings.
+    if (!('bindings' in element)) continue;
+    for (const binding of element.bindings) tags.add(binding.tag);
+  }
+  for (const connection of scene.connections) {
+    for (const binding of connection.bindings ?? []) tags.add(binding.tag);
+  }
+  return tags;
+}
+
+export function assertSimCoversEveryBoundTag(scene: Scene): void {
+  const expectedTags = allBoundTags(scene);
+  const sim = createSimulator(scene, { seed: 1, quality: { enabled: false } });
+  const pushed = sim.step(1000);
+  const pushedTags = new Set(pushed.map((v) => v.tag));
+
+  const missing = [...expectedTags].filter((tag) => !pushedTags.has(tag));
+  expect(missing, `tags with no simulator coverage: ${missing.join(', ')}`).toEqual([]);
+}

package/templates/tsconfig.json

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

package/templates/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    // Runs post-build only (`pnpm test:cli-templates`) -- these tests import
+    // @vscada/core's BUILT dist via subpath exports (e.g.
+    // `@vscada/core/scene-authoring`), which don't exist until `pnpm build`
+    // has run. See ../vitest.config.ts for the matching exclude.
+    include: ['**/*.test.ts'],
+  },
+});

package/templates/waste-to-energy/README.md

@@ -0,0 +1,13 @@
+# waste-to-energy
+
+The flagship template — base spec §16's reference scene, in full: feed hopper → furnace → flue-gas train (duct, two ID fans, coil bank, stack + plume) alongside the boiler → steam valve → turbine → condenser → feedwater pump → **back to the boiler** recycle loop (the loop that exercises topology cycle detection, Story 2.3). Motor starter panel, four analog gauges, an ash off-page connector, and a bottom status bar with a STOP button round it out.
+
+This scene is also the visual-regression baseline and the Storybook landing page (Story 7.4 wires it in).
+
+Run it:
+
+```sh
+vscada preview --template waste-to-energy
+```
+
+See `scene.ts` for a documented catalog gap: the element catalog's `boiler` type has no gas-side port, so the flue-gas path runs through the coil bank rather than literally piping into the boiler drum — a follow-up for whoever next touches the `boiler`/`heat-exchanger-coil` catalog entries.

package/templates/waste-to-energy/scene.test.ts

@@ -0,0 +1,15 @@
+import { describe, it } from 'vitest';
+import { assertSchemaValid, assertSimCoversEveryBoundTag } from '../template-test-utils';
+import sceneBuilder from './scene';
+
+describe('waste-to-energy template (Story 5.4 Task 3, AC2)', () => {
+  const scene = sceneBuilder.build();
+
+  it('builds a schema-valid scene', () => {
+    assertSchemaValid(scene);
+  });
+
+  it('gives the simulator generator coverage for every bound tag', () => {
+    assertSimCoversEveryBoundTag(scene);
+  });
+});

package/templates/waste-to-energy/scene.ts

@@ -0,0 +1,250 @@
+import {
+  boiler,
+  condenser,
+  createScene,
+  duct,
+  fanCentrifugal,
+  furnace,
+  gaugeAnalog,
+  heatExchangerCoil,
+  hopper,
+  motorStarterPanel,
+  offPage,
+  plume,
+  pumpCentrifugal,
+  pushbutton,
+  readoutPanel,
+  stack,
+  turbine,
+  valveControl,
+} from '@vscada/builder';
+
+/**
+ * waste-to-energy — Story 5.4 AC2 / base spec §16's reference scene, the
+ * flagship template: visual-regression baseline, Storybook landing page,
+ * and §16 compliance artifact. Every element and connection below is
+ * commented with the §16 bullet it satisfies.
+ *
+ * KNOWN CATALOG GAP (documented per Dev Notes — "gaps reopen the owning
+ * story, templates don't get local hacks"): §16 asks for "furnace → boiler
+ * drum via flue gas duct", but `ELEMENT_CATALOG['boiler']` only declares
+ * water-side ports (`feedwater-inlet`, `steam-outlet`) — no gas-side port
+ * to receive flue gas. The gas path below runs furnace → duct → ID fan →
+ * coil bank → ID fan → stack instead (heat recovery happens through the
+ * coil bank, matching real WtE gas-train topology); the boiler drum
+ * appears immediately below the gas path, thermally adjacent but not
+ * port-connected to it. A future revision of the element catalog
+ * (owning story: whichever story next touches `heat-exchanger-coil`/
+ * `boiler`) should add a gas-side port pair to `boiler` so this can be a
+ * literal connection.
+ */
+
+// --- Waste feed → furnace (§16: "Feed hopper (level) → furnace (state, firing rate)") ---
+const wasteHopper = hopper('HPR-01')
+  .at(40, 100)
+  .label('Waste feed hopper')
+  .medium('waste')
+  .bind({ tag: 'HPR01.level', type: 'level', min: 0, max: 100, unit: '%' })
+  .thresholds(
+    { tag: 'HPR01.level', level: 'low-low', value: 10, direction: 'below' },
+    { tag: 'HPR01.level', level: 'high-high', value: 90, direction: 'above' },
+  );
+
+const furnaceEl = furnace('FCE-01')
+  .at(240, 100)
+  .label('Furnace')
+  .bind(
+    { tag: 'FCE01.state', type: 'state', map: { '0': 'idle', '1': 'firing' } },
+    // The furnace primitive (Story 3.7) specifically looks for a `color-ramp`
+    // binding to drive its firing-rate glow — matching §16's own wording.
+    { tag: 'FCE01.firingRate', type: 'color-ramp', min: 0, max: 100 },
+  );
+
+const furnaceTempGauge = gaugeAnalog('GA-01').at(240, 260).label('Furnace temp').bind({ tag: 'FCE01.temp', type: 'needle', min: 0, max: 1200 });
+
+// --- Gas path (§16: "Furnace → boiler drum via flue gas duct", "Two ID fans on the gas path", "Heat exchanger coil bank", "Stack with temperature readout and plume") ---
+const flueDuct = duct('DCT-01').at(420, 130).label('Flue gas duct');
+
+const idFan1 = fanCentrifugal('FAN-01')
+  .at(580, 115)
+  .label('ID Fan 1')
+  .bind({ tag: 'IDF01.state', type: 'state', map: { '0': 'stopped', '1': 'running' } }, { tag: 'IDF01.rpm', type: 'rotate', min: 0, max: 1800 });
+
+const coilBank = heatExchangerCoil('COIL-01').at(690, 140).label('Heat exchanger coil bank');
+
+const idFan2 = fanCentrifugal('FAN-02')
+  .at(830, 115)
+  .label('ID Fan 2')
+  .bind({ tag: 'IDF02.state', type: 'state', map: { '0': 'stopped', '1': 'running' } }, { tag: 'IDF02.rpm', type: 'rotate', min: 0, max: 1800 });
+
+const stackEl = stack('STK-01').at(960, 50).label('Stack').bind({ tag: 'STK01.temp', type: 'readout', unit: 'degC', decimals: 0 });
+
+const plumeEl = plume('PLM-01').at(955, 0).bind({ tag: 'PLM01.density', type: 'emission', min: 0, max: 100 });
+
+const stackTempGauge = gaugeAnalog('GA-02').at(1010, 120).label('Stack temp').bind({ tag: 'STK01.temp', type: 'needle', min: 0, max: 600 });
+
+// --- Steam / water recycle loop (§16: "Boiler drum (level, pressure) → turbine via steam line",
+// "Turbine (power, RPM readouts) → condenser → feedwater pump → back to drum — THE recycle loop,
+// exercises cycle detection", "Steam control valve (position 0–100) on the turbine inlet") ---
+const boilerDrum = boiler('BLR-01')
+  .at(240, 400)
+  .label('Boiler drum')
+  .bind(
+    { tag: 'BLR01.level', type: 'level', min: 0, max: 100, unit: '%' },
+    { tag: 'BLR01.pressure', type: 'readout', unit: 'bar', decimals: 1 },
+  )
+  .thresholds(
+    { tag: 'BLR01.level', level: 'low-low', value: 20, direction: 'below' },
+    { tag: 'BLR01.level', level: 'high-high', value: 85, direction: 'above' },
+  );
+
+const steamValve = valveControl('VLV-01').at(400, 440).label('Steam control valve').bind({ tag: 'VLV01.pos', type: 'position', min: 0, max: 100 });
+
+const turbineEl = turbine('TRB-01')
+  .at(500, 415)
+  .label('Turbine')
+  .bind({ tag: 'TRB01.power', type: 'readout', unit: 'MW', decimals: 1 }, { tag: 'TRB01.rpm', type: 'rotate', min: 0, max: 3600 });
+
+const steamFlowGauge = gaugeAnalog('GA-04').at(560, 500).label('Steam flow').bind({ tag: 'STM02.flow', type: 'needle', min: 0, max: 100 });
+
+const condenserEl = condenser('CND-01').at(650, 430).label('Condenser');
+
+const feedwaterPump = pumpCentrifugal('PMP-02')
+  .at(820, 430)
+  .label('Feedwater pump')
+  .bind({ tag: 'FWP01.state', type: 'state', map: { '0': 'stopped', '1': 'running' } }, { tag: 'FWP01.rpm', type: 'rotate', min: 0, max: 1800 });
+
+// Motor starter panel — §16: "Motor starter panels for each pump" (one pump in this scene).
+// Bound to the SAME tag as the pump's own status: the panel mirrors the pump's run state,
+// not an independent value — one generator, two visual representations (Story 5.2 precedent).
+const feedwaterMsp = motorStarterPanel('MSP-01')
+  .at(900, 410)
+  .label('Feedwater pump starter')
+  .bind({ tag: 'FWP01.state', type: 'state', map: { '0': 'stopped', '1': 'running' } });
+
+const feedwaterFlowGauge = gaugeAnalog('GA-03').at(820, 530).label('Feedwater flow').bind({ tag: 'FW01.flow', type: 'needle', min: 0, max: 100 });
+
+// --- Ash byproduct (§16 media list includes "ash"; §16 gives the furnace no ash-handling
+// port — see the KNOWN CATALOG GAP note above — so the ash hopper is shown adjacent to the
+// gas train and its own outlet feeds an off-page connector, exercising the "ash" medium on
+// a real connection without inventing a furnace port that doesn't exist in the catalog) ---
+const ashHopper = hopper('ASH-01').at(40, 600).label('Ash hopper').medium('ash').bind({ tag: 'ASH01.level', type: 'level', min: 0, max: 100, unit: '%' });
+
+// `.target()` is required by both the Zod schema (`OffPageElementSchema`)
+// and the always-on structural validator ("off-page must declare target") —
+// this scene predates that requirement and was never updated, so it built
+// "successfully" (the generic element schema's plain z.union silently
+// absorbed the malformed off-page element) while failing structural
+// validation at render time. "ash-handling"/"from-boiler" mirrors the
+// existing off-page fixture convention (structural-validator.test.ts) for
+// the same "ash" flow this element represents.
+const ashOffPage = offPage('OFP-01').at(220, 650).label('Ash to disposal').target('ash-handling', 'from-boiler');
+
+// --- Bottom status bar (§16: "Bottom status bar with plant-level readouts and a STOP button") ---
+// readout-panel (Story 3.6) only renders `readout`-typed bindings — one row each.
+const statusPanel = readoutPanel('RDP-01')
+  .at(700, 800)
+  .label('Plant status')
+  .bind(
+    { tag: 'PLANT.load', type: 'readout', unit: 'MW', decimals: 1 },
+    { tag: 'PLANT.steamOutput', type: 'readout', unit: 't/h', decimals: 1 },
+  );
+
+// Read-only display per base spec §1.2 (no write-back path — AD-1: values enter only via
+// `values`/`setValues()`; nothing here dispatches a command back into the store).
+const stopButton = pushbutton('PB-01').at(820, 810).label('STOP').bind({ tag: 'PLANT.stop', type: 'state', map: { '0': 'released', '1': 'pressed' } });
+
+export default createScene('waste-to-energy', {
+  canvas: { width: 1150, height: 900 },
+  title: 'Waste to Energy — reference scene (base spec §16)',
+  theme: 'classic-hmi',
+})
+  .add(wasteHopper)
+  .add(furnaceEl)
+  .add(furnaceTempGauge)
+  .add(flueDuct)
+  .add(idFan1)
+  .add(coilBank)
+  .add(idFan2)
+  .add(stackEl)
+  .add(plumeEl)
+  .add(stackTempGauge)
+  .add(boilerDrum)
+  .add(steamValve)
+  .add(turbineEl)
+  .add(steamFlowGauge)
+  .add(condenserEl)
+  .add(feedwaterPump)
+  .add(feedwaterMsp)
+  .add(feedwaterFlowGauge)
+  .add(ashHopper)
+  .add(ashOffPage)
+  .add(statusPanel)
+  .add(stopButton)
+  // Media exercised (§16): waste, flue-gas, steam, feedwater, condensate, ash.
+  .connect(wasteHopper.port('outlet-bot'), furnaceEl.port('fuel-inlet'), {
+    id: 'C-WASTE',
+    medium: 'waste',
+    bindings: [{ tag: 'WASTE01.flow', type: 'flow', min: 0, max: 20 }],
+  })
+  .connect(furnaceEl.port('flue-outlet'), flueDuct.port('inlet'), {
+    id: 'C-FG1',
+    medium: 'flue-gas',
+    bindings: [{ tag: 'FG01.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(flueDuct.port('outlet'), idFan1.port('inlet'), {
+    id: 'C-FG2',
+    medium: 'flue-gas',
+    bindings: [{ tag: 'FG02.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(idFan1.port('outlet'), coilBank.port('inlet'), {
+    id: 'C-FG3',
+    medium: 'flue-gas',
+    bindings: [{ tag: 'FG03.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(coilBank.port('outlet'), idFan2.port('inlet'), {
+    id: 'C-FG4',
+    medium: 'flue-gas',
+    bindings: [{ tag: 'FG04.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(idFan2.port('outlet'), stackEl.port('inlet'), {
+    id: 'C-FG5',
+    medium: 'flue-gas',
+    bindings: [{ tag: 'FG05.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(boilerDrum.port('steam-outlet'), steamValve.port('inlet'), {
+    id: 'C-STM1',
+    medium: 'steam',
+    bindings: [{ tag: 'STM01.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(steamValve.port('outlet'), turbineEl.port('inlet'), {
+    id: 'C-STM2',
+    medium: 'steam',
+    bindings: [{ tag: 'STM02.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(turbineEl.port('outlet'), condenserEl.port('inlet'), {
+    id: 'C-STM3',
+    medium: 'steam',
+    bindings: [{ tag: 'STM03.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(condenserEl.port('outlet'), feedwaterPump.port('suction'), {
+    id: 'C-COND',
+    medium: 'condensate',
+    bindings: [{ tag: 'COND01.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  // The recycle loop (§16): feedwater pump discharge closes back onto the boiler drum's own
+  // feedwater inlet — this edge is what makes the topology graph a cycle (Story 2.3).
+  .connect(feedwaterPump.port('discharge'), boilerDrum.port('feedwater-inlet'), {
+    id: 'C-FW',
+    medium: 'feedwater',
+    bindings: [{ tag: 'FW01.flow', type: 'flow', min: 0, max: 100 }],
+  })
+  .connect(ashHopper.port('outlet-bot'), ashOffPage.port('link'), {
+    id: 'C-ASH',
+    medium: 'ash',
+    bindings: [{ tag: 'ASH01.flow', type: 'flow', min: 0, max: 20 }],
+  })
+  // Boiler section collapsible (Dev Notes: "2.5 in anger") — the steam-generation core.
+  .group('boiler-section', { label: 'Boiler', collapsed: false, x: 220, y: 380, w: 280, h: 180, children: ['BLR-01', 'VLV-01'] })
+  .group('status-bar-group', { label: 'Plant status bar', collapsed: false, x: 680, y: 780, w: 200, h: 100, children: ['RDP-01', 'PB-01'] })
+  .inferTopology();