@jr2/orchestrator 0.3.0 → 0.5.1

package/README.md

@@ -1,8 +1,26 @@
 # @jr2/orchestrator
 
 The jr2 Orchestrator: the runtime that executes Machines — xstate actors driving Agents in Kubernetes Sandboxes — plus
-the HTTP API, the Console it serves, and the kit pieces a Workflow imports (`agent()`, `workspace()`, `gate()`,
-`customize()`, …).
+the HTTP API, the Console it serves, and the Authoring surface.
+
+The Authoring surface is what this package exports from its root: the names that an author writes in a workflow module
+or in `jr2.config.ts`, and no other names.
+
+- **Machine and events:** `jr2Setup()`, `defineEvent()`, `sentBy()`, and the type `HostInjectedInput`.
+- **Agents:** `agent()`, and the types `AgentDefinition` and `ThinkingLevel`.
+- **Workspaces and Repos:** `workspace()`, and the types `Workspaced`, `RepoSlot` and `Binding`.
+- **Effects:** `command()`, `arg()`, `http()`, `secret()`, `bearer()`, `basic()`, `text()`, `file()`, `push()`,
+  `dispatch()`, `fromPick()`, `paramsOf()`, `answer()`, and the types `CommandOutput`, `HttpOutput`, `PushOutput` and
+  `DispatchOutput`.
+- **Composition:** `open`, `customize()`, `pool()`, `source()`, and the types `Customize`, `EffectBinding`, `Size` and
+  `UserContainer`.
+- **Charts:** `openBody()`, `chartSchema`, `chartSchemaFor()`, and the types `OpenBodyDeclaration` and `OpenBodyOutput`.
+- **Config:** `defineConfig()`, and the type `JR2Config`.
+
+A state that needs outside input invokes the Gate as `src: "gate"`. You do not import it: `jr2Setup()` registers it.
+
+The kit's own packages import `@jr2/orchestrator/internal`. It is not for workflow authors. It has no stability promise,
+and any name in it can change in any release.
 
 An Instance depends on it and its `workflows/` import from it; `jr2 up` bakes the engine and those workflows into one
 image, so this package is run in-cluster, never on the host. Its version is the kit's version: the Kit images an

package/bin/server.ts

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
-// The instance image's entrypoint (ADR-0019): boot the orchestrator described by env + cwd and
-// serve until SIGINT/SIGTERM. A zero-build `.ts` shebang like the `jr2` bin; the e2e tier spawns
-// this exact process as its per-scenario fixture (ADR-0010). Logic lives in `serverMain` — this
-// file owns only what a process owns: env, cwd, stdout, signals, exit.
+// The Orchestrator Kit image's entrypoint (ADR-0019, ADR-0069): boot the orchestrator described
+// by env + cwd and serve until SIGINT/SIGTERM. The cwd holds the state volume, and the Workflows
+// come from the current Assembly on it; the folder itself is never loaded, so a process with no
+// published Assembly serves none until `jr2 up` publishes one. A zero-build `.ts` shebang like
+// the `jr2` bin; the e2e tier spawns this exact process as its per-scenario fixture and publishes
+// through the same door (ADR-0010). Logic lives in `serverMain` — this file owns only what a
+// process owns: env, cwd, stdout, signals, exit.
 
 import { serverMain } from "../src/server.ts";
 

package/console/canvas.ts

@@ -8,7 +8,7 @@
 // Working state only, never belief: the fold set, the viewport transform, and what is SHOWN live
 // here — everything the page believes stays in store.ts and arrives as `updateCanvas` arguments.
 
-import type { GateCard, ObservedRun } from "./store.ts";
+import type { GateCard, ObservedRun, Seat } from "./store.ts";
 
 // ---- The machine doc, as `GET /workflows/:name/machine` serves it -------------------------------
 // Mirrors machine-doc.ts (the server's serializer) the way store.ts mirrors `RunObservation`: the
@@ -57,7 +57,8 @@ export type ChildMachineDoc = {
 export type MachineEventDoc = {
   name: string;
   description?: string;
-  audience: "agent" | "external" | "any";
+  /** Absent: each writing's state decides who may send it (ADR-0015). */
+  audience?: "agent" | "external" | "any";
   /** The def's input schema as JSON Schema. */
   input: unknown;
 };
@@ -70,6 +71,10 @@ export type MachineBodyDoc = {
   /** The events THIS Machine declares, and only this one (ADR-0049): a nested Machine's ride its
    *  own body doc, because event names are scoped to the Machine that declared them. */
   events: MachineEventDoc[];
+  /** Who may send what, per state (ADR-0015) — mirrors `MachineSeat`. */
+  seats: Seat[];
+  /** What the build found legal and suspect (ADR-0015). */
+  warnings: string[];
 };
 
 /** The serialized structure of a workflow's Machine — mirrors `MachineDoc`. */
@@ -77,6 +82,8 @@ export type MachineDoc = MachineBodyDoc & {
   workflow: string;
   /** States whose child list may be incomplete (enqueueActions closures) — surfaced as a notice. */
   opaqueStates?: string[];
+  /** A run's doc only: each bound Chart it could not draw, and why (ADR-0070) — surfaced as a notice. */
+  chartsNotDrawn?: Array<{ path: string; src: string; reason: string }>;
 };
 
 /** One live child actor as the observation band reports it — `ObservedRun.children`, deepened
@@ -138,9 +145,11 @@ export function initCanvas(els: { canvas: HTMLElement; svg: SVGSVGElement }, can
   svg = els.svg;
   hooks = canvasHooks;
   wireCanvasNavigation();
-  addEventListener("resize", () => {
-    if (fitting) fitToWidth();
-  });
+  // The pane changes size with the window AND with the strips above the diagram (a wait, a held
+  // pick, the seats opening) — a fit follows either.
+  new ResizeObserver(() => {
+    if (fitting) fitWhole();
+  }).observe(svg);
 }
 
 const SVG_NS = "http://www.w3.org/2000/svg";
@@ -498,8 +507,8 @@ let layoutSize = { width: 0, height: 0 };
 let scale = 1;
 let panX = 0;
 let panY = 0;
-/** Fit the Machine's width to the canvas, and keep fitting it as the diagram grows — until the
- * reader takes the view into their own hands, after which it is theirs. */
+/** Fit the whole Machine to the canvas, and keep fitting it as the diagram or the pane changes —
+ * until the reader takes the view into their own hands, after which it is theirs. */
 let fitting = true;
 /** The <g> the current render mounted — the transform target; each re-render swaps it in and
  * re-applies the view, so a relayout never resets where the reader was looking. */
@@ -513,11 +522,15 @@ function applyView(): void {
   hooks.onScale(Math.round(scale * 100)); // the nav readout follows every path
 }
 
-/** Scale so the whole width lands in the pane, centered. Never magnifies — a small Machine stays
- * 1:1. */
-function fitToWidth(): void {
-  if (!layoutSize.width || svg.clientWidth <= 0) return applyView();
-  scale = Math.min(1, Math.max(0.2, (svg.clientWidth - FIT_PAD * 2) / layoutSize.width));
+/** Scale so the whole Machine — its width AND its height — lands in the pane, centered across.
+ * Never magnifies (a small Machine stays 1:1), and never below the floor: a Machine larger than the
+ * floor allows pans. Fitting the width alone left a tall Machine's lower states — a `workspace()`
+ * body under the wrapper's chain — below the pane, where no reader looks for them. */
+function fitWhole(): void {
+  if (!layoutSize.width || svg.clientWidth <= 0 || svg.clientHeight <= 0) return applyView();
+  const across = (svg.clientWidth - FIT_PAD * 2) / layoutSize.width;
+  const down = (svg.clientHeight - FIT_PAD * 2) / layoutSize.height;
+  scale = Math.min(1, Math.max(0.2, Math.min(across, down)));
   panX = Math.max(FIT_PAD, (svg.clientWidth - layoutSize.width * scale) / 2);
   panY = FIT_PAD;
   applyView();
@@ -547,7 +560,7 @@ export function zoomReset(): void {
 }
 export function zoomFit(): void {
   fitting = true;
-  fitToWidth();
+  fitWhole();
 }
 
 // ---- Direct navigation: drag pans, wheel zooms --------------------------------------------------
@@ -638,7 +651,7 @@ async function renderMachine(doc: MachineBodyDoc, live: RunChild[]): Promise<voi
   renderEdges(layout, rootG);
   // The fresh <g> becomes the viewport, wearing the view the reader already had (or a fit).
   viewportG = rootG;
-  fitting ? fitToWidth() : applyView();
+  fitting ? fitWhole() : applyView();
 }
 
 // ---- Live runs ----------------------------------------------------------------------------------

package/console/components/app.ts

@@ -6,7 +6,15 @@
 
 import { Fragment, h, type JSX } from "preact";
 import { useState } from "preact/hooks";
-import { selectedRun, selectedRunGates, type Frame, type Store } from "../store.ts";
+import {
+  selectedRun,
+  selectedRunFailure,
+  selectedRunGates,
+  selectedRunHeld,
+  selectedRunWaiting,
+  type Frame,
+  type Store,
+} from "../store.ts";
 import type { MachineDoc } from "../canvas.ts";
 import { Nav } from "./nav.ts";
 import { Fleet } from "./fleet.ts";
@@ -71,6 +79,9 @@ export function App(props: {
         run: selectedRun(store),
         selectedNodeId: store.selectedNodeId,
         gates: selectedRunGates(store),
+        waiting: selectedRunWaiting(store),
+        held: selectedRunHeld(store),
+        failure: selectedRunFailure(store),
         api,
       }),
       h(Drawer, { store, chosenTab, onChooseTab: setChosenTab, api }),

package/console/components/fleet.ts

@@ -2,14 +2,18 @@
 // 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()`.
+//
+// A named Chart is a Workflow (ADR-0070): it lists under its Chart wrapper, indented, with its origin
+// (`chart file` or `chart`) and, when a publish no longer admits it, `unrunnable` with the reason.
 
 import { h, type JSX } from "preact";
-import { fleetRuns, type ObservedRun, type Store } from "../store.ts";
+import { dispatchBadge, fleetEntries, fleetRuns, type FleetEntry, 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;
+  const entries = fleetEntries(store.listing);
   return h(
     "aside",
     { id: "fleet" },
@@ -17,18 +21,38 @@ export function Fleet(props: { store: Store; schemas: ReadonlyMap<string, unknow
     h(
       "ul",
       { id: "workflow-list" },
-      store.workflows.length
-        ? store.workflows.map((name) => workflowItem(name, store, schemas, api))
+      entries.length
+        ? entries.map((entry) => workflowItem(entry, store, schemas, api))
         : h("li", { class: "empty" }, "no workflows registered"),
     ),
   );
 }
 
-function workflowItem(name: string, store: Store, schemas: ReadonlyMap<string, unknown>, api: AppApi): JSX.Element {
+/** How the rail names an origin (ADR-0070); a Machine that is no Chart wrapper shows none. */
+function originTag(entry: FleetEntry): string | null {
+  if (entry.origin === "file") return "chart file";
+  if (entry.origin === "runtime") return "chart";
+  if (entry.wrapper) return entry.wrapper.oneShot ? "chart wrapper, one-shot" : "chart wrapper";
+  return null;
+}
+
+function workflowItem(
+  entry: FleetEntry,
+  store: Store,
+  schemas: ReadonlyMap<string, unknown>,
+  api: AppApi,
+): JSX.Element {
+  const name = entry.name;
   const rows = fleetRuns(store, name);
+  const tag = originTag(entry);
   return h(
     "li",
-    { key: name, class: name === store.workflow ? "wf wf--selected" : "wf" },
+    {
+      key: name,
+      class: `${name === store.workflow ? "wf wf--selected" : "wf"}${entry.depth ? " wf--chart" : ""}`,
+      // A Chart indents under its wrapper; the rail's stylesheet has no rule for depth yet.
+      style: entry.depth ? { marginLeft: "14px" } : undefined,
+    },
     h(
       "div",
       { class: "wf-head", onClick: () => void api.selectWorkflow(name, { push: true }) },
@@ -45,8 +69,17 @@ function workflowItem(name: string, store: Store, schemas: ReadonlyMap<string, u
         store.expanded.has(name) ? "▾" : "▸",
       ),
       h("span", { class: "wf-name" }, name),
+      tag ? h("span", { class: "wf-count wf-origin" }, tag) : null,
+      entry.unrunnable ? h("span", { class: "wf-count wf-unrunnable", title: entry.unrunnable }, "unrunnable") : null,
+      entry.shadows
+        ? h(
+            "span",
+            { class: "wf-count wf-unrunnable", title: entry.shadows.unrunnable ?? "a Chart of this name is shadowed" },
+            entry.shadows.origin === "runtime" ? "shadows a chart" : "shadows a chart file",
+          )
+        : null,
       h("span", { class: "wf-count" }, String(rows.filter((r) => !r.settled).length)),
-      store.token === "live"
+      store.token === "live" && !entry.unrunnable
         ? h(
             "button",
             {
@@ -98,6 +131,8 @@ function runRows(
 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;
+  // A dispatched run names its caller on the row (ADR-0071), off the open observation.
+  const badge = dispatchBadge(run);
   return h(
     "li",
     {
@@ -109,6 +144,17 @@ function runRow(name: string, run: ObservedRun, settled: boolean, store: Store,
       },
     },
     h("span", { class: "run-id" }, run.runId.slice(0, 8)),
+    badge && run.dispatchedBy
+      ? h(
+          "span",
+          {
+            class: "dispatch-badge dim",
+            title: `dispatched by ${run.dispatchedBy.run} (${run.dispatchedBy.slot}), depth ${run.dispatchedBy.depth}`,
+            style: { fontSize: "11px", marginRight: "6px" },
+          },
+          badge,
+        )
+      : null,
     gates
       ? h("span", { class: "gate-badge", title: `${gates} open gate${gates === 1 ? "" : "s"}` }, `⚑${gates}`)
       : null,

package/console/components/machine-pane.ts

@@ -5,7 +5,15 @@
 
 import { h, type JSX } from "preact";
 import { useEffect, useRef } from "preact/hooks";
-import type { GateCard, ObservedRun } from "../store.ts";
+import {
+  dispatchStrip,
+  dispatchedStrip as dispatchedStripText,
+  docSeats,
+  type GateCard,
+  type HeldLine,
+  type ObservedRun,
+  type WaitingLine,
+} from "../store.ts";
 import {
   clearCanvas,
   initCanvas,
@@ -21,9 +29,12 @@ export function MachinePane(props: {
   run: ObservedRun | null;
   selectedNodeId: string | null;
   gates: GateCard[];
+  waiting: WaitingLine[];
+  held: HeldLine[];
+  failure: string | null;
   api: AppApi;
 }): JSX.Element {
-  const { view, run, selectedNodeId, gates, api } = props;
+  const { view, run, selectedNodeId, gates, waiting, held, failure, api } = props;
   const canvasRef = useRef<HTMLElement>(null);
   const svgRef = useRef<SVGSVGElement>(null);
 
@@ -56,11 +67,37 @@ export function MachinePane(props: {
     { 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 ?? ""),
+    dispatchedStrip(run),
+    startedStrip(run),
     rootTransitionStrip(view.doc),
+    seatsPanel(view.doc),
+    failureStrip(failure),
+    waitingStrip(waiting),
+    heldStrip(held),
     h("svg", { id: "machine-svg", ref: svgRef }),
   );
 }
 
+/** Who dispatched the selected run (ADR-0071): its caller's run, slot and the chain's depth. Read
+ *  off the open observation the pane already holds, so it shows for every viewer, with no fetch. */
+function dispatchedStrip(run: ObservedRun | null): JSX.Element | null {
+  const text = dispatchStrip(run);
+  if (!text) return null;
+  return h(
+    "div",
+    { id: "dispatched-by", class: "dim", style: { margin: "28px 28px 0", fontFamily: "var(--mono)" } },
+    text,
+  );
+}
+
+/** The runs the selected run dispatched (ADR-0071): the chain's other direction, off the same
+ *  open observation, with no fetch. */
+function startedStrip(run: ObservedRun | null): JSX.Element | null {
+  const text = dispatchedStripText(run);
+  if (!text) return null;
+  return h("div", { id: "dispatched", class: "dim", style: { margin: "8px 28px 0", fontFamily: "var(--mono)" } }, text);
+}
+
 /** 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 {
@@ -83,3 +120,92 @@ function rootTransitionStrip(doc: MachineDoc | null): JSX.Element {
     }),
   );
 }
+
+/** Who may send what, per state, and the load warnings (ADR-0015) — what `jr2 up` prints, for the
+ *  Machine and every Machine it composes. Structure, so tokenless too. Folded by default: the
+ *  diagram keeps the pane, and a warning shows in the summary so it is not missed folded. */
+function seatsPanel(doc: MachineDoc | null): JSX.Element | null {
+  const { seats, warnings } = docSeats(doc);
+  if (!seats.length && !warnings.length) return null;
+  return h(
+    "details",
+    { id: "seats" },
+    h(
+      "summary",
+      null,
+      "who may send what",
+      h("span", { class: "dim" }, ` · ${seats.length} seat${seats.length === 1 ? "" : "s"}`),
+      warnings.length
+        ? h("span", { class: "seats-warned" }, ` · ${warnings.length} warning${warnings.length === 1 ? "" : "s"}`)
+        : null,
+    ),
+    h(
+      "ul",
+      { class: "seat-list" },
+      seats.map((seat) =>
+        h(
+          "li",
+          { key: `${seat.state} ${seat.party} ${seat.agent ?? ""}` },
+          h("span", { class: "seat-state" }, seat.state),
+          h("span", { class: "dim" }, seat.party === "agent" ? ` agent:${seat.agent}` : " gate"),
+          h("span", { class: "seat-names" }, ` ${seat.names.length ? seat.names.join(", ") : "—"}`),
+        ),
+      ),
+    ),
+    warnings.length
+      ? h(
+          "ul",
+          { class: "seat-warnings" },
+          warnings.map((w) => h("li", { key: w }, w)),
+        )
+      : null,
+  );
+}
+
+/** Why the selected run failed (ADR-0073): the reason that the Machine gave to `fail`, as `jr2 status`
+ *  prints it. The rail colors a `failed` run for every viewer; the reason is in the run's output,
+ *  which is guarded, so it is here only with a live token. */
+function failureStrip(failure: string | null): JSX.Element {
+  return h("div", { id: "failure", hidden: failure === null }, failure === null ? "" : `failed: ${failure}`);
+}
+
+/** Why the selected run's Workspaces in `placing` wait (ADR-0064), one line each, in the
+ *  scheduler's or the quota's own words. The diagram lights `placing` for every viewer; this reason
+ *  is guarded, so it is here only with a live token. */
+function waitingStrip(waiting: WaitingLine[]): JSX.Element {
+  return h(
+    "ul",
+    { id: "waiting" },
+    waiting.map((w) =>
+      h(
+        "li",
+        { key: w.child },
+        h(
+          "span",
+          { class: "waiting-head" },
+          `${w.child || "Workspace"} waits for ${w.on === "quota" ? "quota" : "a node"}`,
+        ),
+        h("span", { class: "dim", title: w.since }, ` since ${new Date(w.since).toLocaleTimeString()}`),
+        h("div", { class: "waiting-message" }, w.message),
+      ),
+    ),
+  );
+}
+
+/** The selected run's outstanding picks (ADR-0024): the Agent, its pick, and since when it is held.
+ *  A held Turn has no default time bound, so this is where a human sees one that waits too long.
+ *  Guarded like the waiting strip: here only with a live token. */
+function heldStrip(held: HeldLine[]): JSX.Element {
+  return h(
+    "ul",
+    { id: "held" },
+    held.map((line) =>
+      h(
+        "li",
+        { key: `${line.agent} ${line.pick}` },
+        h("span", { class: "held-head" }, `${line.agent || "Agent"}'s pick ${line.pick} runs`),
+        h("span", { class: "dim", title: line.since }, ` held since ${new Date(line.since).toLocaleTimeString()}`),
+      ),
+    ),
+  );
+}

package/console/components/nav.ts

@@ -50,7 +50,7 @@ export function Nav(props: {
       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: "zoom-fit", title: "fit the whole Machine", onClick: () => api.zoomFit() }, "fit"),
     ),
     h(
       "button",

package/console/components/schema-form.ts

@@ -1,15 +1,14 @@
 // 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
+// marked; an object or array property is a JSON textarea, so a Chart wrapper's `chart` field —
+// ADR-0070 — goes as an object, not as a string), 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 };
+import { jsonField, type SchemaProp } from "../json-field.ts";
 
 /** The schema's `properties`, or null when there is no schema to generate from (→ raw textarea). */
 function propsOf(schema: unknown): Record<string, SchemaProp> | null {
@@ -89,12 +88,16 @@ function field(key: string, prop: SchemaProp, required: Set<unknown>): JSX.Eleme
         );
   } else if (prop.type === "number" || prop.type === "integer") {
     input = h("input", { name: key, type: "number", step: "any" });
+  } else if (isJsonType(prop.type)) {
+    input = h("textarea", { name: key, rows: 4, placeholder: `JSON ${prop.type}` });
   } else {
     input = h("input", { name: key, type: "text" });
   }
   return h("label", { key, title: prop.description }, h("span", null, required.has(key) ? `${key} *` : key), input);
 }
 
+const isJsonType = (type: string | undefined): type is "object" | "array" => type === "object" || type === "array";
+
 /** 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. */
@@ -116,6 +119,11 @@ function collect(form: HTMLFormElement, properties: Record<string, SchemaProp> |
   const body: Record<string, unknown> = {};
   for (const [key, prop] of Object.entries(properties)) {
     const el = form.elements.namedItem(key);
+    if (el instanceof HTMLTextAreaElement) {
+      const value = jsonField(key, prop, el.value);
+      if (value !== undefined) body[key] = value;
+      continue;
+    }
     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

package/console/json-field.ts

@@ -0,0 +1,23 @@
+// An object or array property's textarea, parsed (ADR-0033, ADR-0070): a Chart wrapper's one-shot
+// door takes `chart` as an object, so the Console's start form sends JSON of the property's type,
+// never a string. DOM-free, so the Node test project can read it without the browser libs.
+
+/** One property of a flat object schema, as far as the form reads it. */
+export type SchemaProp = { type?: string; enum?: unknown[]; description?: string };
+
+/** An object or array property's textarea, parsed: absent when empty, an error that names the
+ *  field when the text is not JSON of the property's type. */
+export function jsonField(key: string, prop: SchemaProp, text: string): unknown {
+  const trimmed = text.trim();
+  if (!trimmed) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    throw new Error(`${key}: not valid JSON`);
+  }
+  const isArray = Array.isArray(parsed);
+  const ok = prop.type === "array" ? isArray : parsed !== null && typeof parsed === "object" && !isArray;
+  if (!ok) throw new Error(`${key}: must be a JSON ${prop.type}`);
+  return parsed;
+}