@tsplc/sim 0.0.0-stage → 0.2.0

package/src/layout.ts

@@ -0,0 +1,117 @@
+import type { Conveyor, Heading, Line, Target } from "./line";
+
+interface Point {
+  x: number;
+  y: number;
+}
+interface Route {
+  /** Corners in millimetres, from start to end. */
+  points: Point[];
+  headings: Heading[];
+}
+
+/** The view's fixed drawing scale, px per mm, shared by every conveyor so loads keep their proportions. */
+const scale = 0.05;
+/** How far past a side exit a conveyor it feeds starts, leaving room to draw the transfer. */
+const exitClearance = 1000;
+
+const direction: Record<Heading, Point> = {
+  right: { x: 1, y: 0 },
+  left: { x: -1, y: 0 },
+  up: { x: 0, y: -1 },
+  down: { x: 0, y: 1 },
+};
+const leftOf: Record<Heading, Heading> = { right: "up", up: "left", left: "down", down: "right" };
+const rightOf: Record<Heading, Heading> = { right: "down", down: "left", left: "up", up: "right" };
+
+const lengthOf = (conveyor: Conveyor) =>
+  conveyor.parts.reduce((sum, part) => sum + (part.kind === "part" ? part.length : 0), 0);
+
+const travel = (from: Point, heading: Heading, distance: number): Point => ({
+  x: from.x + direction[heading].x * distance,
+  y: from.y + direction[heading].y * distance,
+});
+
+const pointAt = (route: Route, mm: number) => {
+  let remaining = mm;
+  for (const [index, heading] of route.headings.entries()) {
+    const from = route.points[index]!,
+      to = route.points[index + 1]!,
+      length = Math.abs(to.x - from.x) + Math.abs(to.y - from.y);
+    if (remaining <= length || index === route.headings.length - 1)
+      return { point: travel(from, heading, remaining), heading };
+    remaining -= length;
+  }
+  throw new Error("A conveyor needs a route.");
+};
+
+/**
+ * Lays a line out in millimetres and returns each conveyor's drawing. A conveyor's length comes
+ * from its parts. One with no `at` starts where another discharges into it or feeds it sideways.
+ */
+export const drawLine = (line: Line): ReadonlyMap<Conveyor, string> => {
+  const conveyors = Object.values(line.conveyors);
+  const isConveyor = new Set<Target>(conveyors);
+  const feeders = new Map<Target, { from: Conveyor; at: number; side?: "left" | "right" }>();
+  for (const conveyor of conveyors) {
+    let position = 0;
+    for (const part of conveyor.parts) {
+      if (part.kind !== "part") continue;
+      for (const side of ["left", "right"] as const) {
+        const exit = part.exits?.[side];
+        if (exit && isConveyor.has(exit))
+          feeders.set(exit, { from: conveyor, at: position + part.length / 2, side });
+      }
+      position += part.length;
+    }
+    const next = conveyor.next;
+    if (next && !("to" in next) && isConveyor.has(next))
+      feeders.set(next, { from: conveyor, at: position });
+  }
+
+  const routes = new Map<Conveyor, Route>();
+  const active = new Set<Conveyor>();
+  const route = (conveyor: Conveyor): Route => {
+    const known = routes.get(conveyor);
+    if (known) return known;
+    if (active.has(conveyor)) throw new Error("Conveyors with no `at` cannot feed each other.");
+    active.add(conveyor);
+    let start: Point = conveyor.at ?? { x: 0, y: 0 };
+    let heading: Heading = conveyor.heading ?? "right";
+    const feeder = conveyor.at ? undefined : feeders.get(conveyor);
+    if (feeder) {
+      const exit = pointAt(route(feeder.from), feeder.at);
+      heading = !feeder.side
+        ? exit.heading
+        : feeder.side === "left"
+          ? leftOf[exit.heading]
+          : rightOf[exit.heading];
+      start = feeder.side ? travel(exit.point, heading, exitClearance) : exit.point;
+    }
+    const result: Route = { points: [start], headings: [] };
+    let remaining = lengthOf(conveyor);
+    for (const turn of conveyor.turns ?? []) {
+      if (turn.after <= 0 || turn.after >= remaining)
+        throw new Error(`A turn ${turn.after} mm along must fall inside its conveyor.`);
+      result.headings.push(heading);
+      result.points.push(travel(result.points.at(-1)!, heading, turn.after));
+      remaining -= turn.after;
+      heading = turn.to;
+    }
+    result.headings.push(heading);
+    result.points.push(travel(result.points.at(-1)!, heading, remaining));
+    active.delete(conveyor);
+    routes.set(conveyor, result);
+    return result;
+  };
+
+  const pixels = (mm: number) => Math.round(mm * scale * 100) / 100;
+  return new Map(
+    conveyors.map((conveyor) => [
+      conveyor,
+      route(conveyor)
+        .points.map(({ x, y }, index) => `${index ? "L" : "M"} ${pixels(x)} ${pixels(y)}`)
+        .join(" "),
+    ]),
+  );
+};

package/src/line.ts

@@ -0,0 +1,198 @@
+import type { Device, Wire } from "./hardware";
+
+type AnyDevice = Device<{ in: Record<string, unknown>; out: Record<string, unknown> }>;
+type Devices = Record<string, AnyDevice>;
+/** A zone controller senses the zone's photoeye and drives its rollers. */
+type ZoneController = Device<{ in: { photoeye: boolean }; out: { motor: number } }>;
+type MotorDevice = Device<{ in: Record<string, unknown>; out: { motor: number } }>;
+type ReaderDevice = Device<{ in: { read: string | null }; out: Record<string, unknown> }>;
+
+/**
+ * How a part moves the loads on it this tick, in mm/s: `along` the conveyor, or `across` it
+ * toward the right (positive) or left (negative) exit. With `across` set, loads whose middle is on
+ * the part do not travel along; they move sideways until they leave by the exit.
+ */
+export type Motion = { along: number } | { across: number } | { held: true };
+
+/** What a part's sensors can see, in millimetres from the part's start. */
+export interface Sensing {
+  /** A beam across the conveyor at `at` is blocked (by a load not yet moved off to the side). */
+  blocked: (at: number) => boolean;
+  /** Any load is on the part, including mid-transfer. */
+  occupied: boolean;
+  /** The loads on the part: edges in millimetres from its start, and how far each has moved across. */
+  loads: ReadonlyArray<{ head: number; tail: number; lateral: number }>;
+}
+
+/** Where a load goes next: a station or the start of another conveyor. */
+export type Target = Conveyor | Station;
+
+/**
+ * A length of conveyor and the devices on it, such as a zone, a gravity section or a project's
+ * own diverter. `motion` turns the devices' outputs into load movement; `sense` feeds what the
+ * part's sensors see to its devices' inputs and to PLC inputs wired straight to sensors.
+ */
+export interface CustomPart<Parts extends Devices = Devices> {
+  readonly kind: "part";
+  readonly id?: string;
+  /** What it is, for the view, such as "zone" or "diverter". */
+  readonly label?: string;
+  /** Millimetres along the conveyor. */
+  readonly length: number;
+  /** Lateral travel before a load leaves by a side exit. */
+  readonly width?: number;
+  readonly exits?: { readonly left?: Target; readonly right?: Target };
+  readonly devices: Parts;
+  motion(devices: Parts): Motion;
+  sense?(sensing: Sensing, devices: Parts): ReadonlyArray<readonly [Wire<boolean>, boolean]> | void;
+}
+export const part = <Parts extends Devices>(
+  options: Omit<CustomPart<Parts>, "kind">,
+): CustomPart<Parts> => ({ kind: "part", ...options });
+
+/** A driven length whose controller watches a photoeye, by default 50 mm before its end. */
+export const zone = (options: {
+  id?: string;
+  length: number;
+  controller: ZoneController;
+  eye?: number;
+}) =>
+  part({
+    ...(options.id !== undefined && { id: options.id }),
+    label: "zone",
+    length: options.length,
+    devices: { controller: options.controller },
+    motion: ({ controller }) => ({ along: controller.world.out.motor }),
+    sense: ({ blocked }, { controller }) => {
+      controller.world.in.photoeye = blocked(options.eye ?? options.length - 50);
+    },
+  });
+
+/** A length with a motor, or a fixed speed such as a gravity section (0 = passive). */
+export const section = (options: {
+  id?: string;
+  length: number;
+  motor?: MotorDevice;
+  speed?: number;
+}) =>
+  part({
+    ...(options.id !== undefined && { id: options.id }),
+    label: "section",
+    length: options.length,
+    devices: options.motor ? { motor: options.motor } : {},
+    motion: () => ({ along: options.motor?.world.out.motor ?? options.speed ?? 0 }),
+  });
+
+/** A photoeye beam across the conveyor, wired straight to a PLC input. */
+export interface Photoeye {
+  readonly kind: "photoeye";
+  readonly id?: string;
+  /** Millimetres from where it appears in the parts list; negative places it inside the part before. */
+  readonly offset?: number;
+  readonly output: Wire<boolean>;
+}
+/** A barcode reader that reads each load's code as its leading edge passes. */
+export interface Reader {
+  readonly kind: "reader";
+  readonly id?: string;
+  readonly offset?: number;
+  readonly device: ReaderDevice;
+}
+/** Where an operator takes loads off the line into a station, as they reach it. */
+export interface Pickup {
+  readonly kind: "pickup";
+  readonly id?: string;
+  readonly offset?: number;
+  readonly station: Station;
+  /** Which side of the conveyor the station is drawn on, by default the right. */
+  readonly side?: "left" | "right";
+}
+export const pickup = (options: Omit<Pickup, "kind">): Pickup => ({ kind: "pickup", ...options });
+
+export type Part = CustomPart | Photoeye | Reader | Pickup;
+
+export const photoeye = (options: Omit<Photoeye, "kind">): Photoeye => ({
+  kind: "photoeye",
+  ...options,
+});
+export const reader = (options: Omit<Reader, "kind">): Reader => ({ kind: "reader", ...options });
+
+export type Heading = "right" | "left" | "up" | "down";
+
+export interface Conveyor {
+  /**
+   * Where it starts on the floor, in millimetres with y growing downward. Omit it to start where
+   * another conveyor discharges into this one or feeds it from a side exit.
+   */
+  readonly at?: { readonly x: number; readonly y: number };
+  /** Its direction from `at`, by default right. One fed from another conveyor takes its direction from there. */
+  readonly heading?: Heading;
+  /** Corners, each `after` millimetres past the last; it runs on to the length of its parts. */
+  readonly turns?: ReadonlyArray<{ readonly after: number; readonly to: Heading }>;
+  readonly parts: readonly Part[];
+  /**
+   * Where the last part discharges: a conveyor's start or a station, or `{ to, at }` to merge
+   * onto another conveyor at `at` mm from its start.
+   */
+  readonly next?: Target | { readonly to: Conveyor; readonly at: number };
+}
+export const conveyor = (options: Conveyor): Conveyor => options;
+
+export interface StationSensor {
+  readonly output: Wire<boolean>;
+  readonly active: (station: { readonly loads: number }) => boolean;
+}
+/** Where loads leave the line: an operator station, a collection point or an exit. */
+export interface Station {
+  /** Loads it holds before refusing more; unlimited when omitted. */
+  readonly capacity?: number;
+  readonly sensors?: readonly StationSensor[];
+  readonly label?: string;
+}
+export const station = (options: Station = {}): Station => options;
+
+export interface LoadKind {
+  /** Millimetres along the direction of travel. */
+  readonly length: number;
+  readonly width?: number;
+}
+
+export interface Line {
+  readonly conveyors: Readonly<Record<string, Conveyor>>;
+  /** Devices not on a conveyor, such as pushbuttons and stack lights. */
+  readonly devices?: Readonly<Record<string, AnyDevice>>;
+  readonly stations?: Readonly<Record<string, Station>>;
+  readonly loads: Readonly<Record<string, LoadKind>>;
+}
+
+/** The name each conveyor and station has in a line. */
+export const targetNames = (line: Line): ReadonlyMap<Target, string> =>
+  new Map<Target, string>([
+    ...Object.entries(line.conveyors).map(([name, target]) => [target, name] as const),
+    ...Object.entries(line.stations ?? {}).map(([name, target]) => [target, name] as const),
+  ]);
+
+/** Checks every conveyor and station a part leads to is in the line, and returns the line unchanged. */
+export const defineLine = <const Definition extends Line>(line: Definition): Definition => {
+  const names = targetNames(line);
+  for (const [id, item] of Object.entries(line.conveyors)) {
+    const next = item.next && "to" in item.next ? item.next.to : item.next;
+    const targets: Array<Target | undefined> = [next];
+    for (const part of item.parts) {
+      if (part.kind === "part") targets.push(part.exits?.left, part.exits?.right);
+      if (part.kind === "pickup") targets.push(part.station);
+    }
+    for (const target of targets)
+      if (target !== undefined && !names.has(target))
+        throw new Error(`Conveyor ${id} leads to a conveyor or station missing from the line.`);
+  }
+  return line;
+};
+
+/** A record with one value per id, keeping the ids in its type. */
+export const keyed = <Id extends string, Value>(
+  ids: readonly Id[],
+  make: (id: Id) => Value,
+): Record<Id, Value> =>
+  // Object.fromEntries erases the keys; every id has just been given a value.
+  Object.fromEntries(ids.map((id) => [id, make(id)])) as Record<Id, Value>;

package/src/page.ts

@@ -0,0 +1,208 @@
+const escape = (value: string) =>
+  value.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]!);
+
+/** The live view: a self-contained page that polls `/state`. */
+export const page = (options: { title: string; css: string }) => `<!doctype html>
+<html><head><meta charset="utf-8"><title>${escape(options.title)}</title>
+<style>
+:root{--bg:#f6f7f9;--panel:#fff;--fg:#1c2026;--muted:#6b7280;--border:#d8dce3;--track:#c9ced8;
+--running:#16a34a;--busy:#2563eb;--stopped:#9aa3b2;--idle:#c3c9d4;--warning:#d97706;--fault:#dc2626;--load:#7c3aed}
+@media (prefers-color-scheme:dark){:root{--bg:#111318;--panel:#191c22;--fg:#e6e8ec;--muted:#9aa1ad;
+--border:#2c313a;--track:#3a404b;--stopped:#6b7280;--idle:#4b5260;--load:#a78bfa}}
+*{box-sizing:border-box}body{margin:0;font:13px system-ui,sans-serif;background:var(--bg);color:var(--fg);
+display:grid;grid-template-rows:auto 1fr;height:100vh}
+header{display:flex;gap:10px;align-items:center;padding:8px 14px;border-bottom:1px solid var(--border);background:var(--panel)}
+header h1{font-size:14px;margin:0 8px 0 0}#clock{font-family:ui-monospace,monospace;color:var(--muted)}
+#error{color:var(--fault)}button{font:inherit;border:1px solid var(--border);background:var(--bg);color:var(--fg);
+border-radius:6px;padding:3px 9px;cursor:pointer}button:hover{border-color:var(--muted)}
+main{display:grid;grid-template-columns:1fr 340px;min-height:0}svg{width:100%;height:100%}
+aside{border-left:1px solid var(--border);background:var(--panel);overflow:auto;padding:12px}
+h2{font-size:11px;text-transform:uppercase;letter-spacing:.08em;color:var(--muted);margin:14px 0 6px}
+.device{border:1px solid var(--border);border-radius:8px;padding:8px;margin-bottom:8px}
+.device b{display:block;margin-bottom:4px}table{width:100%;border-collapse:collapse;font-size:12px}
+td{padding:2px 0;border-bottom:1px dashed var(--border)}td:last-child{text-align:right;font-family:ui-monospace,monospace}
+.dot{display:inline-block;width:8px;height:8px;border-radius:50%;margin-right:6px}
+.actions{display:flex;flex-wrap:wrap;gap:6px;margin-top:6px}
+.control{display:flex;align-items:center;gap:6px;padding:3px 0;border-bottom:1px dashed var(--border)}
+.control b{flex:1;font-weight:500}.control span{color:var(--muted)}.control button{padding:1px 7px}.part{cursor:pointer}
+#toast{position:fixed;bottom:14px;left:14px;background:var(--fault);color:#fff;padding:6px 10px;border-radius:6px;display:none}
+${options.css}
+</style></head><body>
+<header><h1>${escape(options.title)}</h1><span id="clock"></span>
+<button id="pause">Pause</button><button id="step" disabled>Step</button><span id="error"></span></header>
+<main><svg id="line"><g id="tracks"></g><g id="parts"></g><g id="stations"></g><g id="loads"></g></svg>
+<aside><div id="inspector"><p style="color:var(--muted)">Select a part of the line to inspect it.</p></div>
+<h2>Actions</h2><div id="actions"></div><h2>Controls</h2><div id="controls"></div></aside></main><div id="toast"></div>
+<script>
+const NS = "http://www.w3.org/2000/svg", TRACK = 16;
+const $ = (id) => document.getElementById(id);
+const el = (name, attrs = {}, parent) => { const node = document.createElementNS(NS, name);
+  for (const [k, v] of Object.entries(attrs)) node.setAttribute(k, v); parent?.appendChild(node); return node; };
+const html = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+let state, selected = null, selectedLoad = null, built = "", geometry = new Map(), stationAt = new Map();
+
+const point = (id, mm) => {
+  const g = geometry.get(id), d = Math.max(0, Math.min(mm, g.length)) * g.scale;
+  const p = g.path.getPointAtLength(d), a = g.path.getPointAtLength(Math.max(0, d - 1)),
+    b = g.path.getPointAtLength(Math.min(g.total, d + 1)), angle = Math.atan2(b.y - a.y, b.x - a.x);
+  return { x: p.x, y: p.y, angle, nx: -Math.sin(angle), ny: Math.cos(angle) };
+};
+const color = (status) => "var(--" + status + ")";
+
+const build = () => {
+  for (const id of ["tracks", "parts", "stations"]) $(id).replaceChildren();
+  geometry = new Map(); stationAt = new Map();
+  for (const c of state.conveyors) {
+    const path = el("path", { d: c.draw, fill: "none", stroke: "var(--track)", "stroke-width": TRACK, "stroke-linecap": "round" }, $("tracks"));
+    const total = path.getTotalLength();
+    geometry.set(c.id, { path, total, length: c.length, scale: total / c.length });
+  }
+  for (const c of state.conveyors) {
+    const g = geometry.get(c.id);
+    for (const part of c.parts) {
+      if (part.start === part.end) {
+        const p = point(c.id, part.start), size = part.kind === "reader" ? 7 : 5, sign = part.side === "left" ? -1 : 1;
+        if (part.station && !stationAt.has(part.station)) stationAt.set(part.station, { x: p.x + sign * p.nx * 45, y: p.y + sign * p.ny * 45 });
+        const node = part.kind === "reader"
+          ? el("rect", { x: p.x + p.nx * (TRACK / 2 + 6) - size / 2, y: p.y + p.ny * (TRACK / 2 + 6) - size / 2, width: size, height: size }, $("parts"))
+          : el("circle", { cx: p.x + sign * p.nx * (TRACK / 2 + 5), cy: p.y + sign * p.ny * (TRACK / 2 + 5), r: size / 2 + 1 }, $("parts"));
+        node.dataset.part = part.id; node.classList.add("part");
+        continue;
+      }
+      const seg = el("path", { d: c.draw, fill: "none", "stroke-width": TRACK - 6,
+        "stroke-dasharray": "0 " + part.start * g.scale + " " + (part.end - part.start) * g.scale + " " + g.total }, $("parts"));
+      seg.dataset.part = part.id; seg.classList.add("part");
+      const b = point(c.id, part.start);
+      el("line", { x1: b.x + b.nx * TRACK / 2, y1: b.y + b.ny * TRACK / 2, x2: b.x - b.nx * TRACK / 2, y2: b.y - b.ny * TRACK / 2, stroke: "var(--bg)", "stroke-width": 1.5 }, $("tracks"));
+      for (const [side, sign] of [["left", -1], ["right", 1]]) {
+        const exit = part.exits?.[side]; if (!exit) continue;
+        const p = point(c.id, (part.start + part.end) / 2);
+        el("line", { x1: p.x, y1: p.y, x2: p.x + sign * p.nx * 46, y2: p.y + sign * p.ny * 46, stroke: "var(--track)", "stroke-width": 8 }, $("tracks"));
+        if (!stationAt.has(exit)) stationAt.set(exit, { x: p.x + sign * p.nx * 70, y: p.y + sign * p.ny * 70 });
+      }
+    }
+  }
+  for (const c of state.conveyors) {
+    const next = c.next ?? null;
+    if (next && !geometry.has(next) && !stationAt.has(next)) {
+      const p = point(c.id, c.length); stationAt.set(next, { x: p.x + Math.cos(p.angle) * 45, y: p.y + Math.sin(p.angle) * 45 });
+    }
+  }
+  for (const s of state.stations) {
+    const at = stationAt.get(s.id) ?? { x: 0, y: 0 };
+    const group = el("g", { transform: "translate(" + at.x + " " + at.y + ")" }, $("stations"));
+    group.dataset.part = s.id; group.classList.add("part");
+    el("rect", { x: -38, y: -14, width: 76, height: 28, rx: 5, fill: "var(--panel)", stroke: "var(--border)" }, group);
+    el("text", { "text-anchor": "middle", y: -1, "font-size": 9, fill: "var(--fg)" }, group).textContent = s.label;
+    el("text", { "text-anchor": "middle", y: 10, "font-size": 9, fill: "var(--muted)", "data-count": s.id }, group);
+  }
+  const box = $("line").getBBox(), pad = 60;
+  $("line").setAttribute("viewBox", [box.x - pad, box.y - pad, box.width + 2 * pad, box.height + 2 * pad].join(" "));
+};
+
+const render = () => {
+  const key = JSON.stringify(state.conveyors.map((c) => [c.id, c.draw, c.parts.map((p) => p.id)]));
+  if (key !== built) { built = key; build(); }
+  $("clock").textContent = (state.timeMs / 1000).toFixed(1) + " s";
+  $("error").textContent = state.error ?? "";
+  $("pause").textContent = state.paused ? "Resume" : "Pause"; $("step").disabled = !state.paused;
+  const views = new Map(state.conveyors.flatMap((c) => c.parts.map((p) => [p.id, p])));
+  for (const node of document.querySelectorAll("[data-part]")) {
+    const part = views.get(node.dataset.part); if (!part) continue;
+    const status = color(part.view.status);
+    node.setAttribute(node.tagName === "path" ? "stroke" : "fill", status);
+    node.setAttribute("stroke-opacity", selected === part.id ? 1 : 0.85);
+  }
+  for (const s of state.stations) {
+    const count = document.querySelector('[data-count="' + s.id + '"]'); if (count) count.textContent = s.loads + " held";
+  }
+  const loads = $("loads"); loads.replaceChildren();
+  const waiting = new Map();
+  for (const load of state.loads) {
+    if (load.place.kind === "waiting") { waiting.set(load.place.conveyor, (waiting.get(load.place.conveyor) ?? 0) + 1); continue; }
+    if (load.place.kind !== "conveyor") continue;
+    const g = geometry.get(load.place.conveyor), p = point(load.place.conveyor, load.place.head - load.length / 2);
+    const w = Math.max(load.length * g.scale, 4), h = Math.max(Math.min(load.width * g.scale, TRACK + 6), 4);
+    const x = p.x + p.nx * load.place.lateral * g.scale, y = p.y + p.ny * load.place.lateral * g.scale;
+    const r = el("rect", { x: -w / 2, y: -h / 2, width: w, height: h, rx: 2, fill: "var(--load)", opacity: .9,
+      transform: "translate(" + x + " " + y + ") rotate(" + p.angle * 180 / Math.PI + ")" }, loads);
+    r.dataset.load = load.id; r.classList.add("part");
+    if (selectedLoad === load.id) r.setAttribute("stroke", "var(--fg)");
+    el("title", {}, r).textContent = load.code + " (" + load.kind + ")";
+  }
+  for (const [conveyor, count] of waiting) {
+    const p = point(conveyor, 0);
+    el("text", { x: p.x - Math.cos(p.angle) * 30, y: p.y - Math.sin(p.angle) * 30, "font-size": 10, fill: "var(--muted)", "text-anchor": "middle" }, loads).textContent = "+" + count + " waiting";
+  }
+  inspect(); renderControls(); renderActions();
+};
+
+const removeButton = (id) => "<button data-remove='" + html(id) + "'>Remove</button>";
+const inspectLoad = () => {
+  const load = state.loads.find((l) => l.id === selectedLoad);
+  if (!load) { $("inspector").innerHTML = "<p style=color:var(--muted)>The load has left the line.</p>"; return; }
+  const where = load.place.kind === "conveyor" ? load.place.conveyor + " at " + Math.round(load.place.head) + " mm"
+    : load.place.kind === "station" ? load.place.station : "waiting for " + load.place.conveyor;
+  $("inspector").innerHTML = "<h2>" + html(load.code) + " · " + html(load.kind) + "</h2><div>" + html(where) + "</div>" +
+    "<div class=actions>" + state.actions.filter((a) => a.at === load.id).map((a) => "<button data-run='" + html(a.id) + "'>" + html(a.label) + "</button>").join("") +
+    removeButton(load.id) + "</div>";
+};
+const inspect = () => {
+  if (selectedLoad) return inspectLoad();
+  if (!selected) return;
+  const part = state.conveyors.flatMap((c) => c.parts).find((p) => p.id === selected);
+  const devices = state.devices.filter((d) => d.part === selected);
+  const loads = state.loads.filter((l) => l.place.kind === "station" && l.place.station === selected);
+  const rows = (obj) => Object.entries(obj ?? {}).map(([k, v]) => "<tr><td>" + html(k) + "</td><td>" + html(Array.isArray(v) ? "[" + v.length + "]" : v) + "</td></tr>").join("");
+  $("inspector").innerHTML = "<h2>" + html(selected) + (part ? " · " + part.kind : "") + "</h2>" +
+    (part ? "<div><span class=dot style=background:" + color(part.view.status) + "></span>" + html(part.view.label ?? part.view.status) + "</div>" : "") +
+    (loads.length ? "<table>" + loads.map((l) => "<tr><td>" + html(l.code) + " · " + html(l.kind) + "</td><td>" + removeButton(l.id) + "</td></tr>").join("") + "</table>" : "") +
+    "<div class=actions>" + state.actions.filter((a) => a.at === selected).map((a) => "<button data-run='" + html(a.id) + "'>" + html(a.label) + "</button>").join("") + "</div>" +
+    devices.map((d) => "<div class=device><b><span class=dot style=background:" + color(d.view.status) + "></span>" +
+      html(d.id.slice(selected.length + 1) || d.model) + " · " + html(d.model) + "</b>" +
+      (d.view.label ? "<div style=color:var(--muted)>" + html(d.view.label) + "</div>" : "") +
+      "<table>" + rows(d.view.details) + rows(d.pins) + "</table><div class=actions>" +
+      d.actions.map((a) => "<button data-device='" + html(d.id) + "' data-action='" + html(a) + "'>" + html(a) + "</button>").join("") +
+      "</div></div>").join("");
+};
+
+const renderControls = () => {
+  const controls = state.devices.filter((d) => d.part === null);
+  $("controls").innerHTML = controls.length
+    ? controls.map((d) => "<div class=control><i class=dot style=background:" + color(d.view.status) + "></i><b>" + html(d.id) + "</b><span>" +
+        html(d.view.label ?? d.view.status) + "</span>" + d.actions.map((a) => "<button data-device='" + html(d.id) + "' data-action='" + html(a) + "'>" + html(a) + "</button>").join("") + "</div>").join("")
+    : "<p style=color:var(--muted)>None.</p>";
+};
+const renderActions = () => {
+  const groups = new Map();
+  for (const a of state.actions) groups.set(a.at ?? "", [...(groups.get(a.at ?? "") ?? []), a]);
+  $("actions").innerHTML = groups.size
+    ? [...groups].map(([at, actions]) => (at ? "<div style='margin-top:8px;color:var(--muted)'>" + html(at) + "</div>" : "") +
+        "<div class=actions>" + actions.map((a) => "<button data-run='" + html(a.id) + "'>" + html(a.label) + "</button>").join("") + "</div>").join("")
+    : "<p style=color:var(--muted)>None available.</p>";
+};
+
+const post = async (url, body) => {
+  const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body ?? {}) });
+  if (!response.ok) { const toast = $("toast"); toast.textContent = (await response.json()).message ?? "Failed"; toast.style.display = "block"; setTimeout(() => toast.style.display = "none", 3000); }
+  await refresh();
+};
+document.addEventListener("click", (event) => {
+  const target = event.target.closest("[data-part],[data-device],[data-run],[data-load],[data-remove]");
+  if (!target) return;
+  if (target.dataset.run) return post("/actions/" + encodeURIComponent(target.dataset.run));
+  if (target.dataset.remove) return post("/loads/remove", { id: target.dataset.remove });
+  if (target.dataset.load) { selectedLoad = target.dataset.load; selected = null; return render(); }
+  if (target.dataset.device) {
+    const argument = target.dataset.action === "read" ? prompt("Code to read (empty for a no-read)") : "";
+    if (argument !== null) post("/devices/act", { device: target.dataset.device, action: target.dataset.action, argument });
+    return;
+  }
+  selected = target.dataset.part; selectedLoad = null; render();
+});
+$("pause").onclick = () => post("/control", { pause: !state.paused });
+$("step").onclick = () => post("/control", { step: true });
+const refresh = async () => { state = await (await fetch("/state")).json(); render(); };
+const loop = async () => { try { await refresh(); } catch {} setTimeout(loop, 200); };
+loop();
+</script></body></html>`;

package/src/paths.ts

@@ -0,0 +1,51 @@
+declare const valueType: unique symbol;
+const pathKey = Symbol("tsplc.path");
+
+/** One PLC variable of type `Value`, such as `LineIO.Conveyor_Inbound.Cards[3].Output.MotionAsserted`. */
+export interface Path<Value> {
+  readonly [valueType]?: Value;
+}
+
+/**
+ * Typed paths into a PLC's globals: records nest, `.at(index)` selects a record array's element, and
+ * scalars and scalar arrays (read and written whole) are `Path`s.
+ */
+export type Paths<T> =
+  T extends ReadonlyArray<infer Item>
+    ? Item extends object
+      ? { readonly at: (index: number) => Paths<Item> }
+      : Path<T>
+    : T extends object
+      ? { readonly [Key in keyof T]: Paths<T[Key]> }
+      : Path<T>;
+
+const join = (segments: readonly string[]) =>
+  segments.reduce(
+    (path, segment) =>
+      /^\d+$/.test(segment) ? `${path}[${segment}]` : path ? `${path}.${segment}` : segment,
+    "",
+  );
+
+// A function target so that `.at` is callable, and still a path for a record field named `at`.
+const proxy = (segments: readonly string[]): unknown =>
+  new Proxy(() => undefined, {
+    get: (_, key) => {
+      if (key === pathKey) return join(segments);
+      if (typeof key === "symbol") return undefined;
+      return proxy([...segments, key]);
+    },
+    apply: (_, __, [index]: [number]) => proxy([...segments.slice(0, -1), String(index)]),
+  });
+
+/**
+ * Builds typed paths for a generated `PlcGlobals`:
+ * `plcPaths<PlcGlobals>().LineIO.Conveyor_Inbound.Cards.at(3).Output.MotionAsserted`.
+ */
+export const plcPaths = <Globals>(): Paths<Globals> => proxy([]) as Paths<Globals>;
+
+/** The dotted variable path, e.g. `LineIO.Conveyor_Inbound.Cards[3].Output.MotionAsserted`. */
+export const pathName = (path: Path<unknown>): string => {
+  const name: unknown = Reflect.get(path, pathKey);
+  if (typeof name !== "string" || !name) throw new Error("Expected a path from plcPaths().");
+  return name;
+};