@tsplc/debug 0.0.0-stage → 0.2.16

package/src/ui/hardware.ts

@@ -0,0 +1,368 @@
+import type { DebugDevice } from "../manifest.ts";
+import { mapBits, readBits } from "./bits.ts";
+import type { Quality } from "../api.ts";
+import {
+  type View,
+  deviceHealth,
+  empty,
+  fill,
+  h,
+  healthBadge,
+  pathLink,
+  sourceLink,
+} from "./dom.ts";
+import { formatScalar, formatValue, valueState, valueStateLabels } from "./format.ts";
+import type { Store } from "./store.ts";
+
+const deviceHref = (id: string) => `#/hardware/${encodeURIComponent(id)}`;
+
+const assemblySummary = (device: DebugDevice) =>
+  device.assemblies
+    .map((assembly) => `${assembly.direction === "input" ? "in" : "out"} ${assembly.bytes} B`)
+    .join(" · ");
+
+const deviceList = (store: Store): View => {
+  const body = h("tbody");
+  const render = () =>
+    body.replaceChildren(
+      ...store.manifest.devices.map((device) =>
+        h(
+          "tr",
+          { class: "link-row", onclick: () => (location.hash = deviceHref(device.id)) },
+          h("td", {}, healthBadge(deviceHealth(store, device))),
+          h("td", {}, h("a", { href: deviceHref(device.id), class: "mono" }, device.id)),
+          h("td", {}, [device.vendor, device.product].filter(Boolean).join(" ")),
+          h(
+            "td",
+            { class: "mono" },
+            device.network
+              ? `${device.network.address}${device.network.rpiMs === undefined ? "" : ` · RPI ${device.network.rpiMs} ms`}`
+              : "",
+          ),
+          h("td", {}, device.connection ?? ""),
+          h("td", { class: "mono" }, assemblySummary(device)),
+          h("td", { class: "num" }, String(device.channels.length)),
+        ),
+      ),
+    );
+  render();
+  store.show({
+    health: store.manifest.devices.filter((device) => device.health).map(({ id }) => id),
+  });
+  return {
+    element: h(
+      "div",
+      { class: "page" },
+      h("h1", {}, "Hardware"),
+      store.manifest.devices.length
+        ? h(
+            "table",
+            { class: "grid" },
+            h(
+              "thead",
+              {},
+              h(
+                "tr",
+                {},
+                ...[
+                  "Health",
+                  "Device",
+                  "Product",
+                  "Network",
+                  "Connection",
+                  "Assemblies",
+                  "Channels",
+                ].map((label) => h("th", {}, label)),
+              ),
+            ),
+            body,
+          )
+        : empty("This build configures no devices."),
+    ),
+    update(topics) {
+      if (topics.has("devices") || topics.has("stream") || topics.has("session")) render();
+    },
+  };
+};
+
+const deviceDetail = (store: Store, device: DebugDevice): View => {
+  const io = store.manifest.io.filter((entry) => entry.device === device.id);
+  const badge = h("span");
+  const status = h("dl", { class: "facts readings" });
+  const grids = h("div", { class: "assemblies" });
+  const channelBody = h("tbody");
+
+  /** The state for the manifest's `index`th assembly: the host lists them in the same order per direction. */
+  const bytesOf = (index: number) => {
+    const assembly = device.assemblies[index];
+    if (!assembly) return undefined;
+    const sameDirection = device.assemblies
+      .slice(0, index)
+      .filter((other) => other.direction === assembly.direction).length;
+    return store.devices
+      .get(device.id)
+      ?.assemblies.filter((state) => state.direction === assembly.direction)[sameDirection];
+  };
+
+  const renderHealth = () => {
+    const health = deviceHealth(store, device);
+    badge.replaceChildren(
+      healthBadge(health),
+      health.detail ? h("span", { class: "dim" }, ` ${health.detail}`) : "",
+    );
+  };
+
+  /** Device states carry no sample time, so only the connection marks their values stale. */
+  const reading = (quality: Quality, value: string) => {
+    const state = valueState(quality, 0, {
+      connected: store.connected,
+      intervalMs: store.session.reading.intervalMs,
+    });
+    return [
+      h("span", { class: `value s-${state}` }, value),
+      h("span", { class: `meta s-${state}` }, valueStateLabels[state]),
+    ];
+  };
+
+  const renderStatus = () => {
+    const values = store.devices.get(device.id)?.status ?? {};
+    fill(
+      status,
+      ...Object.keys(device.status ?? {}).flatMap((label) => {
+        const entry = values[label];
+        return [
+          h("dt", {}, label),
+          h(
+            "dd",
+            {},
+            ...(entry
+              ? reading(entry.quality, formatScalar(entry.value))
+              : [h("span", { class: "value s-unavailable" }, "not read")]),
+          ),
+        ];
+      }),
+    );
+  };
+
+  const renderGrids = () =>
+    grids.replaceChildren(
+      ...device.assemblies.map((assembly, index) => {
+        const state = bytesOf(index);
+        const bytes = state?.bytes ?? null;
+        const bits = mapBits(device.id, assembly.direction, assembly.bytes, device.channels, io);
+        const quality = !store.connected ? "stale" : state ? state.quality : "unavailable";
+        return h(
+          "section",
+          { class: `panel assembly q-${quality}` },
+          h(
+            "h3",
+            {},
+            `${assembly.direction === "input" ? "Input" : "Output"} assembly · ${assembly.bytes} bytes`,
+            assembly.address ? h("span", { class: "mono dim" }, ` ${assembly.address}`) : "",
+            h(
+              "span",
+              { class: "dim" },
+              bytes
+                ? ` · ${quality === "good" ? "raw bytes" : `raw bytes, ${quality}`}`
+                : assembly.raw
+                  ? " · raw bytes not read yet"
+                  : " · no raw bytes in this build: it has no generated device tree",
+            ),
+          ),
+          h(
+            "div",
+            { class: "bitgrid" },
+            h("span", { class: "bh" }, "byte"),
+            ...Array.from({ length: 8 }, (_, bit) => h("span", { class: "bh" }, `.${bit}`)),
+            h("span", { class: "bh" }, "hex"),
+            h("span", { class: "bh legend-head" }, "mapped"),
+            ...Array.from({ length: assembly.bytes }, (_, byte) => {
+              const value = bytes?.[byte];
+              const starts = device.channels.filter(
+                (channel) =>
+                  channel.direction === assembly.direction && channel.offsetBits >> 3 === byte,
+              );
+              return [
+                h("span", { class: "byte mono" }, `+${byte}`),
+                ...Array.from({ length: 8 }, (_, bit) => {
+                  const mapped = bits[byte * 8 + bit];
+                  const on = value === undefined ? undefined : (value >> bit) & 1;
+                  const where = `byte ${byte} bit ${bit}`;
+                  return h(
+                    "span",
+                    {
+                      class: `bit${mapped ? " mapped" : ""}${on === 1 ? " on" : ""}${on === undefined ? " none" : ""}`,
+                      title: mapped
+                        ? `${where} · ${mapped.channel.name} (${mapped.channel.id})${mapped.paths.map((path) => `\n${path}`).join("")}`
+                        : `${where} · not mapped`,
+                    },
+                    on === undefined ? "·" : String(on),
+                    mapped && mapped.channel.offsetBits === byte * 8 + bit
+                      ? h("small", {}, mapped.channel.id)
+                      : undefined,
+                  );
+                }),
+                h(
+                  "span",
+                  { class: "hex mono" },
+                  value === undefined ? "··" : value.toString(16).padStart(2, "0").toUpperCase(),
+                ),
+                h(
+                  "span",
+                  { class: "legend" },
+                  ...starts.map((channel) =>
+                    h(
+                      "span",
+                      { class: "legend-item" },
+                      h("b", {}, channel.id),
+                      ...io
+                        .filter((entry) => entry.channel === channel.id)
+                        .map((entry) =>
+                          pathLink(entry.path, entry.path.split(".").slice(-3).join(".")),
+                        ),
+                    ),
+                  ),
+                ),
+              ];
+            }).flat(),
+          ),
+        );
+      }),
+    );
+
+  const renderChannels = () =>
+    channelBody.replaceChildren(
+      ...device.channels.map((channel) => {
+        const index = device.assemblies.findIndex(
+          (assembly) => assembly.direction === channel.direction,
+        );
+        const bytes = index >= 0 ? bytesOf(index)?.bytes : undefined;
+        const raw = bytes ? readBits(bytes, channel.offsetBits, channel.bits) : null;
+        const mapped = io.filter((entry) => entry.channel === channel.id);
+        return h(
+          "tr",
+          {},
+          h("td", { class: "mono" }, channel.id),
+          h(
+            "td",
+            {},
+            channel.name,
+            channel.description ? h("div", { class: "dim" }, channel.description) : "",
+          ),
+          h("td", {}, channel.direction),
+          h(
+            "td",
+            { class: "mono" },
+            `${channel.offsetBits >> 3}.${channel.offsetBits & 7} · ${channel.bits} bit${channel.bits === 1 ? "" : "s"}`,
+          ),
+          h("td", { class: "mono" }, channel.address ?? ""),
+          h(
+            "td",
+            { class: "mono num", title: "Decoded from the raw assembly bytes" },
+            raw === null ? "—" : String(raw),
+            channel.unit ? ` ${channel.unit}` : "",
+          ),
+          h(
+            "td",
+            {},
+            ...(mapped.length
+              ? mapped.map((entry) => {
+                  const bound = store.devices
+                    .get(device.id)
+                    ?.channels.find(
+                      (candidate) => candidate.id === channel.id && candidate.path === entry.path,
+                    );
+                  const node = store.tree.resolve(entry.path);
+                  return h(
+                    "div",
+                    { class: "mapped-path" },
+                    pathLink(entry.path),
+                    entry.inverted ? h("span", { class: "tag" }, "inverted") : "",
+                    ...(bound
+                      ? reading(bound.quality, formatValue(store.manifest, entry.type, bound.value))
+                      : []),
+                    node?.declaration ? sourceLink(store, node.declaration) : "",
+                  );
+                })
+              : [h("span", { class: "dim" }, "not mapped")]),
+          ),
+        );
+      }),
+    );
+
+  renderHealth();
+  renderStatus();
+  renderGrids();
+  renderChannels();
+  store.show({ devices: [device.id] });
+
+  const identity: [string, string | undefined][] = [
+    ["Vendor", device.vendor],
+    ["Product", device.product],
+    ["Product code", device.productCode],
+    ["Address", device.network?.address],
+    ["RPI", device.network?.rpiMs === undefined ? undefined : `${device.network.rpiMs} ms`],
+    ["Connection", device.connection],
+  ];
+  return {
+    element: h(
+      "div",
+      { class: "page" },
+      h("div", { class: "crumbs" }, h("a", { href: "#/hardware" }, "Hardware"), " / "),
+      h("h1", { class: "mono" }, device.id, " ", badge),
+      h(
+        "dl",
+        { class: "facts" },
+        ...identity.flatMap(([label, value]) =>
+          value === undefined ? [] : [h("dt", {}, label), h("dd", { class: "mono" }, value)],
+        ),
+      ),
+      device.status && h("h2", {}, "Status"),
+      status,
+      grids,
+      h("h2", {}, "Channels"),
+      device.channels.length
+        ? h(
+            "table",
+            { class: "grid" },
+            h(
+              "thead",
+              {},
+              h(
+                "tr",
+                {},
+                ...["Id", "Name", "Dir", "Bits", "Address", "Raw", "TypeScript"].map((label) =>
+                  h("th", {}, label),
+                ),
+              ),
+            ),
+            channelBody,
+          )
+        : empty("No channels configured."),
+    ),
+    update(topics) {
+      if (topics.has("devices") || topics.has("stream") || topics.has("session")) {
+        renderHealth();
+        renderStatus();
+        renderGrids();
+        renderChannels();
+      }
+    },
+  };
+};
+
+export const hardwareView = (store: Store, id: string | undefined): View => {
+  if (id === undefined) return deviceList(store);
+  const device = store.manifest.devices.find((candidate) => candidate.id === id);
+  if (device) return deviceDetail(store, device);
+  store.show();
+  return {
+    element: h(
+      "div",
+      { class: "page" },
+      h("h1", {}, "Hardware"),
+      empty(`No device ${id} in this build.`),
+    ),
+    update() {},
+  };
+};

package/src/ui/header.ts

@@ -0,0 +1,179 @@
+import { h } from "./dom.ts";
+import { formatAge, formatClock, formatInterval } from "./format.ts";
+import type { Store, Topic } from "./store.ts";
+
+export const ROUTES = ["overview", "variables", "hardware", "jobs", "recent", "requests"] as const;
+export type Route = (typeof ROUTES)[number];
+
+const shortId = (id: string | null) => (id === null ? "unknown" : id.slice(0, 10));
+
+const readout = (label: string, ...value: (Node | string)[]) =>
+  h(
+    "div",
+    { class: "readout" },
+    h("span", { class: "label" }, label),
+    h("span", { class: "reading" }, ...value),
+  );
+
+/** Always visible: which build runs, how values are read and whether they can be, and how far to trust times. */
+export const header = (store: Store) => {
+  const readouts = h("div", { class: "readouts" });
+  const banners = h("div", { class: "banners" });
+  const links = new Map(ROUTES.map((route) => [route, h("a", { href: `#/${route}` }, route)]));
+  const element = h(
+    "header",
+    {},
+    h(
+      "div",
+      { class: "bar" },
+      h(
+        "div",
+        { class: "brand" },
+        h("b", {}, "tsPLC"),
+        h("span", {}, "debug"),
+        h(
+          "span",
+          { class: "ro", title: "The debugger never writes or forces values" },
+          "read-only",
+        ),
+      ),
+      readouts,
+    ),
+    h("nav", {}, ...links.values()),
+    banners,
+  );
+
+  const render = () => {
+    const { session } = store;
+    const { build, connection, reading } = session;
+    const buildState = build.matches ? "match" : "mismatch";
+    readouts.replaceChildren(
+      readout(
+        "build",
+        h(
+          "span",
+          {
+            class: `build ${buildState}`,
+            title: `manifest ${build.manifest ?? "none"}\ncontroller ${build.controller ?? "unknown"}`,
+          },
+          `manifest ${shortId(build.manifest)}`,
+          h("i", {}, build.matches ? " = " : " ≠ "),
+          `controller ${shortId(build.controller)}`,
+        ),
+      ),
+      readout(
+        "values",
+        h("span", { class: `dot c-${connection.state}`, title: connection.endpoint }),
+        `${reading.method} · every ${formatInterval(reading.intervalMs)}`,
+        h(
+          "span",
+          { class: "dim" },
+          ` · ${connection.state} since ${formatClock(connection.since).slice(0, 8)}`,
+          ` (${formatAge(store.ageOf(connection.since)).replace(" ago", "")})`,
+        ),
+      ),
+      // The PLC clock counts from the runtime's start, so only the precision of the mapping means anything.
+      readout(
+        "plc clock",
+        session.clock
+          ? `±${session.clock.uncertaintyMs.toFixed(1)} ms against the app server's`
+          : "not estimated",
+      ),
+      readout(
+        "scans",
+        ...session.tasks.map((task) => {
+          const interval = store.manifest.tasks.find(
+            (candidate) => candidate.name === task.name,
+          )?.intervalMs;
+          return h(
+            "span",
+            {
+              class: "task",
+              title:
+                interval === undefined
+                  ? task.name
+                  : `${task.name}: configured every ${interval} ms`,
+            },
+            `${task.name} `,
+            h("b", {}, task.scansPerSecond === null ? "—" : task.scansPerSecond.toFixed(1)),
+            "/s",
+            task.dropped > 0
+              ? h(
+                  "span",
+                  {
+                    class: "err",
+                    title:
+                      "Telemetry records overwritten before the PLC sent them: Recent is missing these",
+                  },
+                  ` ${task.dropped} dropped`,
+                )
+              : "",
+          );
+        }),
+      ),
+      readout(
+        "release",
+        session.release
+          ? h(
+              "span",
+              { title: `deployed ${session.release.deployedAt}` },
+              `${session.release.id} · ${session.release.operation} · ${formatAge(store.ageOf(session.release.deployedAt))}`,
+            )
+          : "not reported",
+      ),
+    );
+
+    const notices: [string, string][] = [];
+    if (!build.matches)
+      notices.push([
+        "danger",
+        build.controller === null
+          ? "The controller's build id could not be read, so this manifest may not describe what is running."
+          : `Build mismatch: the controller runs ${build.controller}, but this manifest is ${build.manifest ?? "missing"}. Paths, values and source links may be wrong.`,
+      ]);
+    if (store.stream === "reconnecting")
+      notices.push([
+        "warn",
+        "Lost the stream from the debugger host; reconnecting. Every value is stale until it resumes.",
+      ]);
+    else if (connection.state !== "connected")
+      notices.push([
+        "warn",
+        `${connection.error ?? `Reading values: ${connection.state} since ${formatClock(connection.since)}.`} Values shown are the last read and marked stale.`,
+      ]);
+    if (store.error) notices.push(["error", store.error]);
+    banners.replaceChildren(
+      ...notices.map(([tone, text]) =>
+        h(
+          "div",
+          { class: `banner ${tone}` },
+          text,
+          tone === "error"
+            ? h(
+                "button",
+                { onclick: () => ((store.error = undefined), store.notify("error")) },
+                "dismiss",
+              )
+            : "",
+        ),
+      ),
+    );
+  };
+
+  render();
+  return {
+    element,
+    update(topics: Set<Topic>) {
+      if (
+        topics.has("session") ||
+        topics.has("stream") ||
+        topics.has("error") ||
+        topics.has("clock")
+      )
+        render();
+    },
+    setRoute(route: Route) {
+      for (const [name, link] of links) link.classList.toggle("on", name === route);
+    },
+  };
+};

package/src/ui/index.ts

@@ -0,0 +1,20 @@
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { html } from "./page.ts";
+
+let ui: Promise<{ html: string; script: string }> | undefined;
+
+const build = async () => {
+  const result = await Bun.build({
+    entrypoints: [
+      resolve(dirname(createRequire(import.meta.url).resolve("@tsplc/debug")), "../src/ui/main.ts"),
+    ],
+    target: "browser",
+    minify: true,
+  });
+  if (!result.success) throw new AggregateError(result.logs, "Bundling the debugger UI failed");
+  return { html, script: await result.outputs[0]!.text() };
+};
+
+/** The browser UI: serve `html` at `GET /` and `script` at `GET /ui.js`. Bundled on first call, then cached. */
+export const loadUi = () => (ui ??= build());