@jr2/orchestrator 0.1.0

package/console/components/app.ts

@@ -0,0 +1,79 @@
+// The Console shell (ADR-0032): nav over a master–detail main — the fleet rail on the left, the
+// selected workflow's Machine in the center, the Attention/Activity drawer on the right. One pure
+// render over the store plus the bootstrap's working state; Preact's diff replaces main.js's
+// hand-rolled memo()/paint() machinery (ADR-0034). Which drawer tab the reader chose is view state
+// like the zoom — component state, never the store's.
+
+import { Fragment, h, type JSX } from "preact";
+import { useState } from "preact/hooks";
+import { selectedRun, selectedRunGates, type Frame, type Store } from "../store.ts";
+import type { MachineDoc } from "../canvas.ts";
+import { Nav } from "./nav.ts";
+import { Fleet } from "./fleet.ts";
+import { Drawer, type DrawerTab } from "./drawer.ts";
+import { MachinePane } from "./machine-pane.ts";
+
+/**
+ * What the bootstrap (main.ts) hands the components: every write path in one object, so no
+ * component ever reaches a fetch, the history API, or the canvas on its own. `dispatch` stays the
+ * store's one door (ADR-0032 store-first); the rest wrap the guarded surface and the viewport.
+ */
+export type AppApi = {
+  /** Fold one frame into the store and re-render — the ONLY way belief changes. */
+  dispatch(frame: Frame): void;
+  /** Move the selection: address, store, feed, diagram — `push` on a click that moves. */
+  selectWorkflow(name: string | null, opts?: { push?: boolean; runId?: string | null }): Promise<void>;
+  toggleStartForm(name: string): Promise<void>;
+  /** POST the start body; resolves to an inline error string, or null when the run started. */
+  startRun(name: string, body: Record<string, unknown>): Promise<string | null>;
+  /** POST one gate event; same contract as {@link AppApi.startRun}. */
+  deliverGate(runId: string, gate: string, event: string, body: Record<string, unknown>): Promise<string | null>;
+  setToken(value: string): void;
+  /** The canvas reports its zoom readout through here (nav renders it). */
+  onScale(pct: number): void;
+  zoomIn(): void;
+  zoomOut(): void;
+  zoomReset(): void;
+  zoomFit(): void;
+};
+
+/** The center pane's working state — the machine doc in hand (or why there is none). Fetch
+ *  bookkeeping like main.ts's doc cache, deliberately NOT store belief: the doc is structure the
+ *  server serves, and `dispatch` stays the only door into what the page believes. */
+export type MachineView = {
+  doc: MachineDoc | null;
+  /** `/` — nothing selected; the canvas says what to do instead. */
+  placeholder: string | null;
+  /** An error ("no workflow"), or — with `notice` — a caveat about the diagram (opaque states). */
+  note: { text: string; notice: boolean } | null;
+};
+
+export function App(props: {
+  store: Store;
+  view: MachineView;
+  zoomPct: number;
+  initialToken: string;
+  schemas: ReadonlyMap<string, unknown>;
+  api: AppApi;
+}): JSX.Element {
+  const { store, view, zoomPct, initialToken, schemas, api } = props;
+  const [chosenTab, setChosenTab] = useState<DrawerTab>("attention");
+  return h(
+    Fragment,
+    null,
+    h(Nav, { store, machineId: view.doc?.id ?? null, zoomPct, initialToken, onChooseTab: setChosenTab, api }),
+    h(
+      "main",
+      null,
+      h(Fleet, { store, schemas, api }),
+      h(MachinePane, {
+        view,
+        run: selectedRun(store),
+        selectedNodeId: store.selectedNodeId,
+        gates: selectedRunGates(store),
+        api,
+      }),
+      h(Drawer, { store, chosenTab, onChooseTab: setChosenTab, api }),
+    ),
+  );
+}

package/console/components/drawer.ts

@@ -0,0 +1,131 @@
+// The drawer: Attention (the gate inbox) + Activity (the emit log). Tokenless there is no
+// Attention tab at all — the observer band of ADR-0014/0032 — and a card is only ever a re-fetched
+// fact: it empties when the server's next answer says so, never through bookkeeping on this side.
+
+import { h, type JSX } from "preact";
+import { visibleGates, type GateCard, type Store } from "../store.ts";
+import { SchemaForm } from "./schema-form.ts";
+import type { AppApi } from "./app.ts";
+
+/** Which tab the reader last chose. View state like the zoom, not belief — the store's `token`
+ *  decides whether Attention exists at all. */
+export type DrawerTab = "attention" | "activity";
+
+export function Drawer(props: {
+  store: Store;
+  chosenTab: DrawerTab;
+  onChooseTab: (tab: DrawerTab) => void;
+  api: AppApi;
+}): JSX.Element {
+  const { store, chosenTab, onChooseTab, api } = props;
+  const unlocked = store.token === "live";
+  const tab = unlocked ? chosenTab : "activity"; // tokenless: no Attention tab — today's observer
+  return h(
+    "aside",
+    { id: "drawer" },
+    h(
+      "div",
+      { class: "drawer-tabs" },
+      h(
+        "button",
+        {
+          id: "tab-attention",
+          hidden: !unlocked,
+          class: tab === "attention" ? "tab--active" : "",
+          onClick: () => onChooseTab("attention"),
+        },
+        "Attention",
+      ),
+      h(
+        "button",
+        { id: "tab-activity", class: tab === "activity" ? "tab--active" : "", onClick: () => onChooseTab("activity") },
+        "Activity",
+      ),
+    ),
+    h(
+      "div",
+      { id: "attention-panel", hidden: tab !== "attention" },
+      h(
+        "label",
+        { class: "inbox-scope" },
+        h("input", {
+          id: "inbox-all",
+          type: "checkbox",
+          checked: store.inboxAll,
+          onChange: (e: Event) =>
+            api.dispatch({ kind: "inboxScope", all: (e.currentTarget as HTMLInputElement).checked }),
+        }),
+        " all workflows",
+      ),
+      h("ul", { id: "gate-inbox" }, inbox(store, api)),
+    ),
+    h("div", { id: "activity-panel", hidden: tab !== "activity" }, h("ul", { id: "emit-log" }, activity(store))),
+  );
+}
+
+function inbox(store: Store, api: AppApi): JSX.Element | JSX.Element[] {
+  const cards = visibleGates(store);
+  if (!cards.length) {
+    return h(
+      "li",
+      { class: "empty" },
+      store.inboxAll || !store.workflow ? "no gates waiting" : "no gates waiting here",
+    );
+  }
+  return cards.flatMap(({ runId, workflow, gates }) =>
+    gates.map((view) => inboxCard(runId, workflow, view, store, api)),
+  );
+}
+
+/** One parked decision: meta to read, one form per accepted event (the shared ADR-0033 form). */
+function inboxCard(runId: string, workflow: string, view: GateCard, store: Store, api: AppApi): JSX.Element {
+  return h(
+    "li",
+    { key: `${runId}/${view.gate}`, class: "gate-card" },
+    h(
+      "div",
+      {
+        class: "gate-head",
+        title: "show this run",
+        onClick: () => {
+          if (workflow === store.workflow) api.dispatch({ kind: "selectRun", runId });
+          else void api.selectWorkflow(workflow, { push: true, runId });
+        },
+      },
+      h("span", { class: "gate-id" }, `⚑ ${view.gate}`),
+      h("span", { class: "dim" }, `${workflow} · ${runId.slice(0, 8)}`),
+    ),
+    view.meta && Object.keys(view.meta).length
+      ? h(
+          "dl",
+          { class: "gate-meta" },
+          Object.entries(view.meta).flatMap(([k, v]) => [
+            h("dt", { key: `t:${k}` }, k),
+            h("dd", { key: `d:${k}` }, typeof v === "string" ? v : JSON.stringify(v)),
+          ]),
+        )
+      : null,
+    view.accepts.map((accepted) =>
+      h(
+        "div",
+        { key: accepted.name, class: "gate-event" },
+        h("div", { class: "gate-event-name", title: accepted.description }, accepted.name),
+        h(SchemaForm, {
+          schema: accepted.input,
+          submitLabel: "send",
+          // Deliberately NO local bookkeeping on success: the delivery moves the Machine, the move
+          // lands a frame, the frame triggers the re-fetch, and the re-fetch empties this card
+          // (ADR-0032) — `deliverGate` concludes nothing on its own.
+          onSubmit: (body) => api.deliverGate(runId, view.gate, accepted.name, body),
+        }),
+      ),
+    ),
+  );
+}
+
+function activity(store: Store): JSX.Element | JSX.Element[] {
+  if (!store.emits.length) return h("li", { class: "empty" }, "no emits yet");
+  return store.emits.map((emitted) =>
+    h("li", null, emitted.type, h("span", { class: "dim" }, emitted.runId.slice(0, 8))),
+  );
+}

package/console/components/fleet.ts

@@ -0,0 +1,117 @@
+// The fleet rail: every registered workflow, each expandable to its runs — the master half of the
+// master–detail shell (ADR-0032). Every row derives from store selectors (`fleetRuns`), never a
+// component-local cache; the vdom's keyed diff is what keeps a half-typed start form alive under
+// the status frames that used to demand main.js's hand-rolled `memo()`.
+
+import { h, type JSX } from "preact";
+import { fleetRuns, type ObservedRun, type Store } from "../store.ts";
+import { SchemaForm } from "./schema-form.ts";
+import type { AppApi } from "./app.ts";
+
+export function Fleet(props: { store: Store; schemas: ReadonlyMap<string, unknown>; api: AppApi }): JSX.Element {
+  const { store, schemas, api } = props;
+  return h(
+    "aside",
+    { id: "fleet" },
+    h("div", { class: "sidebar-head" }, h("h2", null, "Fleet")),
+    h(
+      "ul",
+      { id: "workflow-list" },
+      store.workflows.length
+        ? store.workflows.map((name) => workflowItem(name, store, schemas, api))
+        : h("li", { class: "empty" }, "no workflows registered"),
+    ),
+  );
+}
+
+function workflowItem(name: string, store: Store, schemas: ReadonlyMap<string, unknown>, api: AppApi): JSX.Element {
+  const rows = fleetRuns(store, name);
+  return h(
+    "li",
+    { key: name, class: name === store.workflow ? "wf wf--selected" : "wf" },
+    h(
+      "div",
+      { class: "wf-head", onClick: () => void api.selectWorkflow(name, { push: true }) },
+      h(
+        "button",
+        {
+          class: "wf-caret",
+          title: "fold this workflow's runs",
+          onClick: (e: Event) => {
+            e.stopPropagation();
+            api.dispatch({ kind: "toggleWorkflow", workflow: name });
+          },
+        },
+        store.expanded.has(name) ? "▾" : "▸",
+      ),
+      h("span", { class: "wf-name" }, name),
+      h("span", { class: "wf-count" }, String(rows.filter((r) => !r.settled).length)),
+      store.token === "live"
+        ? h(
+            "button",
+            {
+              class: "wf-start-btn",
+              title: `start a ${name} run`,
+              onClick: (e: Event) => {
+                e.stopPropagation();
+                void api.toggleStartForm(name);
+              },
+            },
+            "start",
+          )
+        : null,
+    ),
+    store.startFormFor === name ? startForm(name, schemas, api) : null,
+    store.expanded.has(name) ? runRows(name, rows, store, api) : null,
+  );
+}
+
+/** The start-run form (ADR-0033), or its placeholder while the input schema is on the wire. */
+function startForm(name: string, schemas: ReadonlyMap<string, unknown>, api: AppApi): JSX.Element {
+  if (!schemas.has(name)) return h("div", { class: "start-form" }, "loading input schema…");
+  return h(
+    "div",
+    { class: "start-form" },
+    h(SchemaForm, {
+      schema: schemas.get(name),
+      submitLabel: "start run",
+      onSubmit: (body) => api.startRun(name, body),
+    }),
+  );
+}
+
+function runRows(
+  name: string,
+  rows: Array<{ run: ObservedRun; settled: boolean }>,
+  store: Store,
+  api: AppApi,
+): JSX.Element {
+  return h(
+    "ul",
+    { class: "wf-runs" },
+    rows.length
+      ? rows.map(({ run, settled }) => runRow(name, run, settled, store, api))
+      : h("li", { class: "empty" }, "no live runs"),
+  );
+}
+
+function runRow(name: string, run: ObservedRun, settled: boolean, store: Store, api: AppApi): JSX.Element {
+  const gates = store.gates.get(run.runId)?.gates.length ?? 0;
+  const selected = name === store.workflow && run.runId === store.selectedRunId;
+  return h(
+    "li",
+    {
+      key: run.runId,
+      class: `${settled ? "settled" : ""}${selected ? " selected" : ""}`.trim(),
+      onClick: () => {
+        if (name === store.workflow) api.dispatch({ kind: "selectRun", runId: run.runId });
+        else void api.selectWorkflow(name, { push: true, runId: run.runId });
+      },
+    },
+    h("span", { class: "run-id" }, run.runId.slice(0, 8)),
+    gates
+      ? h("span", { class: "gate-badge", title: `${gates} open gate${gates === 1 ? "" : "s"}` }, `⚑${gates}`)
+      : null,
+    h("span", { class: `run-status status--${run.status}` }, run.status),
+  );
+}

package/console/components/machine-pane.ts

@@ -0,0 +1,85 @@
+// The center pane: the selected workflow's Machine. The vdom renders the pane's chrome — the
+// placeholder, the error/notice, the root-transition strip — and mounts one <svg> it then never
+// looks inside: canvas.ts owns everything under that ref imperatively (ADR-0034 — the canvas is
+// deliberately NOT vdom-ified; elk's layout is async and pan/zoom is a 60Hz transform).
+
+import { h, type JSX } from "preact";
+import { useEffect, useRef } from "preact/hooks";
+import type { GateCard, ObservedRun } from "../store.ts";
+import {
+  clearCanvas,
+  initCanvas,
+  updateCanvas,
+  type MachineDoc,
+  type MachineStateDoc,
+  type MachineTransitionDoc,
+} from "../canvas.ts";
+import type { AppApi, MachineView } from "./app.ts";
+
+export function MachinePane(props: {
+  view: MachineView;
+  run: ObservedRun | null;
+  selectedNodeId: string | null;
+  gates: GateCard[];
+  api: AppApi;
+}): JSX.Element {
+  const { view, run, selectedNodeId, gates, api } = props;
+  const canvasRef = useRef<HTMLElement>(null);
+  const svgRef = useRef<SVGSVGElement>(null);
+
+  // Mount: hand the refs to the imperative island once. Declared first, so it runs before the
+  // update effect below (same commit, declaration order).
+  useEffect(() => {
+    initCanvas(
+      { canvas: canvasRef.current!, svg: svgRef.current! },
+      {
+        onSelectNode: (nodeId) => api.dispatch({ kind: "selectNode", nodeId }),
+        onScale: api.onScale,
+      },
+    );
+    // The canvas outlives every render and there is exactly one pane — no teardown to return.
+  }, []);
+
+  // Re-run the imperative render when its inputs move: the doc, the selected run's status (a new
+  // object per frame), the node selection, the gate paths. `updateCanvas` re-lays out only when
+  // the doc or the instance SET changed; everything else is a highlight pass (canvas.ts). No doc
+  // means FORGET the diagram now — frames landing before the next doc arrives must not touch the
+  // machine the reader just left.
+  const gateKey = gates.map((g) => (g.path ?? []).join("/")).join(",");
+  useEffect(() => {
+    if (view.doc) updateCanvas(view.doc, run, selectedNodeId, gates);
+    else clearCanvas();
+  }, [view.doc, run, selectedNodeId, gateKey]);
+
+  return h(
+    "section",
+    { id: "canvas", ref: canvasRef },
+    h("div", { id: "placeholder", hidden: !view.placeholder }, view.placeholder ?? ""),
+    h("div", { id: "error", hidden: !view.note, class: view.note?.notice ? "notice" : "" }, view.note?.text ?? ""),
+    rootTransitionStrip(view.doc),
+    h("svg", { id: "machine-svg", ref: svgRef }),
+  );
+}
+
+/** Machine-level transitions ("from any state") as the strip above the Machine — an edge from the
+ *  root would lie, because the root has no box (it renders as the page). */
+function rootTransitionStrip(doc: MachineDoc | null): JSX.Element {
+  const transitions: MachineTransitionDoc[] = doc ? doc.transitions.filter((t) => t.source === doc.root.id) : [];
+  const keyOf = new Map<string, string>();
+  if (doc) {
+    const index = (s: MachineStateDoc): void => {
+      keyOf.set(s.id, s.key);
+      s.states.forEach(index);
+    };
+    index(doc.root);
+  }
+  return h(
+    "div",
+    { id: "root-transitions" },
+    transitions.map((t, i) => {
+      const guard = t.guard ? ` [${t.guard}]` : "";
+      const target = t.targets.length ? ` → ${t.targets.map((id) => keyOf.get(id) ?? id).join(", ")}` : "";
+      return h("span", { key: i }, `on ${t.label}${guard}${target}`);
+    }),
+  );
+}

package/console/components/nav.ts

@@ -0,0 +1,81 @@
+// The nav: breadcrumb (the address, made clickable), the Machine's id, the zoom controls, the
+// fleet-wide attention badge, the feed state, and the token box (ADR-0032). The token INPUT is
+// uncontrolled — its value is the reader's secret, never state — seeded once from sessionStorage
+// and committed on the change event; the store carries only the token's STATE, which is what the
+// badge renders.
+
+import { h, type JSX } from "preact";
+import { gateCount, type Store, type TokenState } from "../store.ts";
+import type { AppApi } from "./app.ts";
+
+const TOKEN_BADGES: Record<TokenState, string> = { none: "", checking: "…", live: "live", invalid: "invalid" };
+
+export function Nav(props: {
+  store: Store;
+  machineId: string | null;
+  zoomPct: number;
+  initialToken: string;
+  onChooseTab: (tab: "attention") => void;
+  api: AppApi;
+}): JSX.Element {
+  const { store, machineId, zoomPct, initialToken, onChooseTab, api } = props;
+  const connection = store.workflow ? store.connection : "idle";
+  const count = gateCount(store);
+  return h(
+    "header",
+    null,
+    h(
+      "nav",
+      { id: "breadcrumb" },
+      h(
+        "a",
+        {
+          id: "crumb-root",
+          href: "/",
+          title: "the fleet",
+          onClick: (e: Event) => {
+            e.preventDefault();
+            void api.selectWorkflow(null, { push: true });
+          },
+        },
+        h("span", { class: "mark" }, "jr2"),
+      ),
+      h("span", { id: "crumb-sep", class: "dim", hidden: !store.workflow }, "/"),
+      h("h1", { id: "workflow-name" }, store.workflow ?? ""),
+    ),
+    h("span", { id: "machine-id", class: "dim" }, machineId ? `machine: ${machineId}` : ""),
+    h(
+      "div",
+      { class: "zoom" },
+      h("button", { id: "zoom-out", title: "zoom out", onClick: () => api.zoomOut() }, "−"),
+      h("button", { id: "zoom-reset", title: "reset zoom", onClick: () => api.zoomReset() }, `${zoomPct}%`),
+      h("button", { id: "zoom-in", title: "zoom in", onClick: () => api.zoomIn() }, "+"),
+      h("button", { id: "zoom-fit", title: "fit to width", onClick: () => api.zoomFit() }, "fit"),
+    ),
+    h(
+      "button",
+      {
+        id: "attention-badge",
+        hidden: store.token !== "live" || count === 0,
+        title: "open gates across the fleet",
+        onClick: () => onChooseTab("attention"),
+      },
+      "⚑ ",
+      h("span", { id: "attention-count" }, String(count)),
+    ),
+    h("span", { id: "connection", class: `conn conn--${connection}`, title: "feed connection" }, connection),
+    h(
+      "label",
+      { id: "token-box", title: "Instance token — unlocks start & gates (ADR-0032)" },
+      h("input", {
+        id: "token",
+        type: "password",
+        placeholder: "instance token",
+        autocomplete: "off",
+        defaultValue: initialToken,
+        onChange: (e: Event) => api.setToken((e.currentTarget as HTMLInputElement).value.trim()),
+      }),
+      h("span", { id: "token-state", class: `token-state token-state--${store.token}` }, TOKEN_BADGES[store.token]),
+    ),
+  );
+}

package/console/components/schema-form.ts

@@ -0,0 +1,137 @@
+// The shared form (start-run + gate delivery — ADR-0033): one component for both writes the
+// Console makes. A flat object schema becomes typed inputs (string/number/boolean/enum, required
+// marked), no schema becomes a raw JSON textarea. `onSubmit` resolves to an error string to render
+// inline (the server's 400 names the accepted shape — that text IS the form's error display) or null when the write
+// landed. The inputs are UNCONTROLLED: what the reader is typing is theirs, not state, and the
+// vdom's keyed diff keeps the elements — and so the half-typed text — alive across status frames.
+
+import { h, type JSX } from "preact";
+import { useState } from "preact/hooks";
+
+/** One property of a flat object schema, as far as the form reads it. */
+type SchemaProp = { type?: string; enum?: unknown[]; description?: string };
+
+/** The schema's `properties`, or null when there is no schema to generate from (→ raw textarea). */
+function propsOf(schema: unknown): Record<string, SchemaProp> | null {
+  if (!schema || typeof schema !== "object") return null;
+  return (schema as { properties?: Record<string, SchemaProp> }).properties ?? {};
+}
+
+function requiredOf(schema: unknown): Set<unknown> {
+  const required = (schema as { required?: unknown } | null)?.required;
+  return new Set(Array.isArray(required) ? required : []);
+}
+
+export function SchemaForm(props: {
+  schema: unknown;
+  submitLabel: string;
+  onSubmit: (body: Record<string, unknown>) => Promise<string | null>;
+}): JSX.Element {
+  const { schema, submitLabel, onSubmit } = props;
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const properties = propsOf(schema);
+  const required = requiredOf(schema);
+
+  const submit = (e: Event): void => {
+    e.preventDefault();
+    setError(null);
+    let body: Record<string, unknown>;
+    try {
+      body = collect(e.currentTarget as HTMLFormElement, properties);
+    } catch (ex) {
+      setError(ex instanceof Error ? ex.message : String(ex));
+      return;
+    }
+    setBusy(true);
+    void onSubmit(body)
+      .catch((ex: unknown) => String(ex))
+      .then((failure) => {
+        setBusy(false);
+        if (failure) setError(failure); // the server's 400 body, inline where the reader typed
+      });
+  };
+
+  return h(
+    "form",
+    { class: "schema-form", onSubmit: submit },
+    properties === null
+      ? h("textarea", { placeholder: "{ }  — raw JSON: this workflow declares no input schema", rows: 3 })
+      : Object.entries(properties).map(([key, prop]) => field(key, prop, required)),
+    h("button", { type: "submit", disabled: busy }, submitLabel),
+    h("div", { class: "form-error", hidden: error === null }, error ?? ""),
+  );
+}
+
+function field(key: string, prop: SchemaProp, required: Set<unknown>): JSX.Element {
+  let input: JSX.Element;
+  if (Array.isArray(prop.enum)) {
+    // Options carry the value's INDEX, not its string: a numeric enum must round-trip as a
+    // number or the server 400s a form no input could ever satisfy. An optional enum gets an
+    // "(omit)" first option — a <select> always holds something, so absence needs a row.
+    input = h(
+      "select",
+      { name: key },
+      ...(required.has(key) ? [] : [h("option", { value: "" }, "(omit)")]),
+      ...prop.enum.map((v, i) => h("option", { value: String(i) }, typeof v === "string" ? v : JSON.stringify(v))),
+    );
+  } else if (prop.type === "boolean") {
+    // A checkbox always answers (unchecked reads as false), which would override a server
+    // default the schema marked optional — an optional boolean must be OMISSIBLE.
+    input = required.has(key)
+      ? h("input", { name: key, type: "checkbox" })
+      : h(
+          "select",
+          { name: key },
+          h("option", { value: "" }, "(omit)"),
+          h("option", { value: "true" }, "true"),
+          h("option", { value: "false" }, "false"),
+        );
+  } else if (prop.type === "number" || prop.type === "integer") {
+    input = h("input", { name: key, type: "number", step: "any" });
+  } else {
+    input = h("input", { name: key, type: "text" });
+  }
+  return h("label", { key, title: prop.description }, h("span", null, required.has(key) ? `${key} *` : key), input);
+}
+
+/** The submit body, read back off the DOM the fields live in. Typed fields: empty optional inputs
+ *  are ABSENT, not "" — the server's schema is the authority on required-ness and says so in its
+ *  400. The raw textarea must parse to an object. */
+function collect(form: HTMLFormElement, properties: Record<string, SchemaProp> | null): Record<string, unknown> {
+  if (properties === null) {
+    const text = (form.querySelector("textarea")?.value ?? "").trim();
+    if (!text) return {};
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new Error("not valid JSON");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("the body must be a JSON object");
+    }
+    return parsed as Record<string, unknown>;
+  }
+  const body: Record<string, unknown> = {};
+  for (const [key, prop] of Object.entries(properties)) {
+    const el = form.elements.namedItem(key);
+    if (!(el instanceof HTMLInputElement || el instanceof HTMLSelectElement)) continue;
+    if (el instanceof HTMLInputElement && el.type === "checkbox") {
+      body[key] = el.checked; // a required boolean: always an answer, by design
+      continue;
+    }
+    const value = el.value;
+    if (value === "") continue;
+    if (Array.isArray(prop.enum)) {
+      body[key] = prop.enum[Number(value)]; // the option held the index — the VALUE keeps its type
+      continue;
+    }
+    if (prop.type === "boolean") {
+      body[key] = value === "true"; // the optional-boolean select
+      continue;
+    }
+    body[key] = prop.type === "number" || prop.type === "integer" ? Number(value) : value;
+  }
+  return body;
+}