makersclaw 0.8.0 → 0.8.1

package/registry/blocks/automation-model/README.md

@@ -0,0 +1,109 @@
+# AutomationModel
+
+The pure part of the automation blocks. It has no screen of its own: it is
+what `flow-editor`, `step-picker`, `step-settings`, `data-picker`,
+`trigger-picker`, `automation-list`, `automation-editor` and `run-view`
+all read, so a kind of step has one name, one face and one price flag
+everywhere, and the canvas, the outline and a run say the same thing about
+the same definition. It is laid with the blocks that need it; you place it
+on its own only to build a screen of your own on automations.
+
+```jsx
+import { KINDS, layoutAutomation, triggerWords } from "../components/blocks/automation-model";   // a Makersclaw app
+import { KINDS, layoutAutomation, triggerWords } from "@/components/makersclaw/blocks/automation-model";   // a shadcn project
+```
+
+An automation is the platform's format 1: a trigger and an ordered list of
+steps. A condition has `then` and `else` lists, a loop has a `steps` list,
+no arrows, no cycles. The platform checks every definition when it is
+saved; this block only reads and dresses one.
+
+## What is in it
+
+- **The catalog** — `KINDS` (each kind's `name`, `blurb`, `glyph`, `tone`
+  plain · model · agent, `group`, `paid`), `paletteGroups()`,
+  `newStep(kind, takenIds)`, `stepTitle(step)`, `stepSub(step)`,
+  `RUNNABLE` (the kinds the platform runs today; a prop on the blocks
+  overrides it), `Glyph` (a kind's face, from the kit's icons).
+- **The layout** — `layoutAutomation(def, { triggerWords, collapsed })` →
+  `{ nodes, edges, groups, bounds }`: boxes and curved connectors, left to
+  right, a branch's two paths one above the other that meet at a join, a
+  for-each as a dashed box or one card. Every connector carries its
+  `slot`, the place in the definition a step added there would land.
+  `curveBetween(a, b)`, `readingOrder(layout)`, `slotWords(slot)`.
+- **The edits** — pure, the old definition never touched: `addStep`,
+  `insertStep`, `removeStep`, `updateStep`, `nudgeStep`, `duplicateStep`,
+  `findStep`, `locate`, `slotAfter`, `slotAtEnd`, `availableBefore(def,
+  id, stepTitle)` (what a step may read), `keyFromName`,
+  `blankAutomation`, `canonicalJson`.
+- **A run** — `overlayOf(layout, stepRows, runStatus)` → how each card
+  went, which connectors were walked, which way each condition took it;
+  `summarizeSteps(rows)`. In a **test run** (a dry run: it reads real data
+  and changes nothing) a step that stood in for itself has the state
+  `would` (it would have run; it did not), ranked between `done` and
+  `fixed`. Each summary also carries `would` (the step's own words, "Would
+  send with send_email.", else "Would run.") and `unchecked` (it needs
+  what a would-step would have made, so it could not be checked).
+- **Fixes and run controls** (`fixes.js`) — `draftOfStep(fixes, stepId)`
+  (the change the agent drafted for a step), `changeLines(patch, def)` (the
+  steps it would touch and what in them, by key, never a value),
+  `controlsOf(run, rows, { stepsVisible })` (which controls a run offers
+  right now), `retryFromOf(run, rows, def, stepId)` (whether "Retry from this
+  step" shows for a step, the top-level step it starts at, and whether to
+  ask first because something already sent; its words are `RETRY_FROM`), `fixTag(fix)` (the card's two words: "The agent fixed this",
+  or for a person's own edit "You changed its data"), and the words
+  `CONTROL_DONE` and `CONTROL_REFUSED`. For a screen that shares the draft
+  with the agent: `changeLinesBetween(before, after)` (what differs between
+  two definitions, one plain line each: how it starts, the name, a step
+  added, removed or changed, the settings; never a value),
+  `latestVersionOf({ versions, draftVersion, liveVersion })`,
+  `agentDraftOf({ versions, draftVersion, liveVersion })` (the draft, when the
+  agent wrote it and it is not live yet: `{ version, note }`) and
+  `newerVersionWords(version, versions)`. A step the AGENT fixed is `fixed`;
+  a person's own edit leaves the step `done`.
+- **The words** — `triggerWords`, `cronWords`, `clockWords(iso, tz)` (a
+  time in the automation's own zone: a 07:00 schedule says 07:00 whoever
+  looks), `agoWords`, `durationWords`, `creditsWords`, `healthOf(row)`,
+  `runStatusWords(status, dry?)` (a test says Test passed, Test failed,
+  Test stopped), `nodeStateWords`, `wouldWords(row)`, `testWords(detail)`
+  (the one line a test run leaves: "Test passed: nothing was sent or
+  changed. 3 steps would have run."), `summaryOf(rows)`,
+  `overviewOf(runs)`, `priceMap(estimate)`.
+- **The quick check** — `checkAutomation(def)` → `[{ path, message,
+  stepId }]`: the mistakes a person makes most (a blank action, an empty
+  branch, a step the platform cannot run yet), in words and by step. It
+  never says a definition is valid; only the platform does.
+  `issuesFromProblems(def, problems)` puts the platform's own refusal
+  lines on their steps.
+- **The shared pieces** — `Chip`, `Dot`, `SidePanel`, `PanelSection`,
+  `RunPicker`; `STARTING_POINTS`, the ready-made flows the list offers;
+  `startsFromPlatform(starts)` turns the desk's own list (`useAutomations().starts`)
+  into the same shape plus `ai` and `price: { credits, per }`, each with a
+  `build(taken)` that returns a whole definition under a free key.
+
+## Never
+
+- Never a status by colour alone: each comes with its word.
+- Never a time shown in the viewer's zone for a schedule: pass the
+  automation's `tz`.
+- Never trust `checkAutomation` over the platform: a save the platform
+  refuses is the answer.
+
+## Example
+
+```jsx
+"use client";
+import { KINDS, layoutAutomation, triggerWords } from "../components/blocks/automation-model";
+
+// How many cards a definition draws, and what starts it, in words.
+export default function Summary({ definition }) {
+  const layout = layoutAutomation(definition, { triggerWords: triggerWords(definition.trigger) });
+  const cards = layout.nodes.filter((n) => n.type === "step" || n.type === "card");
+  return (
+    <p>
+      {definition.name}: {cards.length} steps, {triggerWords(definition.trigger).toLowerCase()}.{" "}
+      {cards.some((n) => KINDS[n.kind]?.paid) ? "Some steps cost credits." : "All steps are free."}
+    </p>
+  );
+}
+```

package/registry/blocks/automation-model/block.json

@@ -0,0 +1,135 @@
+{
+  "name": "automation-model",
+  "title": "AutomationModel",
+  "description": "The pure part of the automation blocks, with no screen of its own: the step catalog (each kind's name, face, group and price flag, a fresh step, a step's title and quiet line), the canvas layout (an automation turned into boxes, curved connectors with a slot for every +, labelled branches that rejoin, a for-each box), the edits (insert, remove, update, nudge, duplicate, what a step may read), what a run did (each node's state, the path taken), the words (a schedule in cron and in speech, a time in the automation's zone, a cost, a health, a run's outcome), a quick check of a definition, and the starting points. Glyph draws a kind's face from the kit's icons.",
+  "useWhen": "You are building your own screen on automations (flow-editor, step-settings, automation-list and run-view all do) and need the catalog, the words or the layout without a canvas. Rarely placed on its own: it is laid with the blocks that need it.",
+  "tags": [
+    "automation",
+    "workflow",
+    "steps",
+    "trigger",
+    "schedule",
+    "cron",
+    "catalog",
+    "layout",
+    "graph",
+    "words",
+    "model",
+    "runs"
+  ],
+  "exports": [
+    "ACTIVE",
+    "GLYPH_ICON",
+    "GROUP_LABELS",
+    "GROUP_ORDER",
+    "Glyph",
+    "KINDS",
+    "LABEL_W",
+    "MARGIN",
+    "RUNNABLE",
+    "STARTING_POINTS",
+    "startsFromPlatform",
+    "testWords",
+    "wouldWords",
+    "T",
+    "WEEKDAYS",
+    "addStep",
+    "agoWords",
+    "allStepIds",
+    "availableBefore",
+    "blankAutomation",
+    "canonicalJson",
+    "checkAutomation",
+    "clockWords",
+    "creditsWords",
+    "deleteWords",
+    "cronFromParts",
+    "cronWords",
+    "curveBetween",
+    "duplicateStep",
+    "durationWords",
+    "findStep",
+    "flaggedSteps",
+    "formatCreditAmount",
+    "healthOf",
+    "humanize",
+    "innerCount",
+    "insertStep",
+    "isRunnable",
+    "issuesFor",
+    "issuesFromProblems",
+    "keyFromName",
+    "latestRows",
+    "layoutAutomation",
+    "locate",
+    "newStep",
+    "nodeIndex",
+    "nodeStateWords",
+    "nudgeStep",
+    "originWords",
+    "overlayOf",
+    "overviewOf",
+    "paletteGroups",
+    "parseTime",
+    "partsFromCron",
+    "plainWords",
+    "priceMap",
+    "readingOrder",
+    "removeStep",
+    "reportLines",
+    "runLine",
+    "runStatusWords",
+    "sameSlot",
+    "slotAfter",
+    "slotAtEnd",
+    "slotWords",
+    "stepIdForPath",
+    "stepSub",
+    "stepTitle",
+    "summaryOf",
+    "summarizeSteps",
+    "textToValue",
+    "timeText",
+    "triggerTypeWords",
+    "triggerWords",
+    "uniqueStepId",
+    "updateStep",
+    "valueToText",
+    "Chip",
+    "Dot",
+    "PanelSection",
+    "SidePanel",
+    "RunPicker",
+    "CONTROL_DONE",
+    "CONTROL_REFUSED",
+    "RETRY_FROM",
+    "agentDraftOf",
+    "changeLines",
+    "changeLinesBetween",
+    "controlsOf",
+    "draftOfStep",
+    "fixTag",
+    "latestVersionOf",
+    "newerVersionWords",
+    "retryFromOf",
+    "TRIGGER_TITLES",
+    "triggerGlyph",
+    "triggerTitle"
+  ],
+  "files": [
+    "index.js",
+    "catalog.js",
+    "graph.js",
+    "edit.js",
+    "overlay.js",
+    "fixes.js",
+    "words.js",
+    "schedule.js",
+    "values.js",
+    "check.js",
+    "templates.js",
+    "glyph.jsx",
+    "parts.jsx"
+  ],
+  "requires": []
+}

package/registry/blocks/automation-model/catalog.js

@@ -0,0 +1,256 @@
+// The step catalog: what each kind of step is called, which icon wears it,
+// where the picker files it, and what a fresh one looks like.
+//
+// Pure data and small functions; no React. The canvas, the picker, the
+// outline and the settings panel all read this one table, so a kind has
+// one name and one face everywhere. It mirrors the platform's automation
+// format (format 1: a trigger and an ordered list of steps; a condition
+// has `then` and `else`, a loop has `steps`); the platform validates a
+// definition when it is saved, this file only dresses it.
+
+/** A kind's face: a kit Icon name per glyph (glyph.jsx draws it). */
+export const GLYPH_ICON = {
+  "trigger-schedule": "calendar-clock",
+  "trigger-manual": "hand",
+  "trigger-event": "send",
+  "trigger-action": "zap",
+  "trigger-record": "database",
+  "trigger-webhook": "globe",
+  "trigger-automation": "workflow",
+  "trigger-connection": "plug",
+  action: "zap",
+  brain: "book-open",
+  condition: "split",
+  loop: "repeat",
+  set: "braces",
+  wait: "timer",
+  stop: "square",
+  notify: "bell",
+  tool: "plug",
+  search: "search",
+  llm: "sparkles",
+  agent: "bot",
+  zero: "dollar",
+  automation: "workflow",
+  join: "circle",
+  plus: "plus",
+};
+
+/** How each way of starting is named on the canvas, in the outline and at
+ *  the top of its panel: one short title per trigger type. */
+export const TRIGGER_TITLES = {
+  manual: "By hand",
+  schedule: "Schedule",
+  event: "Event",
+  action: "App action",
+  record: "Record",
+  webhook: "Web address",
+  automation: "After another",
+};
+
+/** The glyph of a trigger type (an unknown type wears the hand's). */
+export function triggerGlyph(type) {
+  return Object.prototype.hasOwnProperty.call(TRIGGER_TITLES, type) ? `trigger-${type}` : "trigger-manual";
+}
+
+/** The title of a trigger type. */
+export function triggerTitle(type) {
+  return TRIGGER_TITLES[type] ?? "By hand";
+}
+
+/** The picker's groups, in the order it shows them. A step's tone (plain,
+ *  model, agent) says how it is dressed: an agent step is solid in the AI
+ *  hue, a model call carries a "model" mark in it, the rest are plain. */
+export const GROUP_LABELS = {
+  app: "Your apps",
+  think: "Think",
+  flow: "Flow",
+  data: "Data",
+  tell: "Tell",
+  more: "More",
+};
+
+export const GROUP_ORDER = ["app", "think", "flow", "data", "tell", "more"];
+
+/** The kinds the platform knows, in format 1. */
+export const KINDS = {
+  action: { kind: "action", name: "App action", blurb: "Do something in one of your apps: add people, save a draft, close a task.", glyph: "action", tone: "plain", group: "app", paid: false },
+  "brain.read": { kind: "brain.read", name: "Read the company brain", blurb: "Look up notes and records you can read.", glyph: "brain", tone: "plain", group: "data", paid: false },
+  condition: { kind: "condition", name: "Condition", blurb: "Go one way when something is true and another way when it is not.", glyph: "condition", tone: "plain", group: "flow", paid: false },
+  loop: { kind: "loop", name: "For each", blurb: "Do the same steps for every item in a list.", glyph: "loop", tone: "plain", group: "flow", paid: false },
+  set: { kind: "set", name: "Set values", blurb: "Build or reshape a value for the steps after it.", glyph: "set", tone: "plain", group: "data", paid: false },
+  wait: { kind: "wait", name: "Wait", blurb: "Pause for a while, or until a time. Nothing runs while it waits.", glyph: "wait", tone: "plain", group: "flow", paid: false },
+  stop: { kind: "stop", name: "Stop", blurb: "End the run here with a plain message.", glyph: "stop", tone: "plain", group: "flow", paid: false },
+  notify: { kind: "notify", name: "Tell someone", blurb: "Leave a line for the owner: a note in their Needs you.", glyph: "notify", tone: "plain", group: "tell", paid: false },
+  tool: { kind: "tool", name: "Connected tool", blurb: "Use one of your connected accounts: read mail, post a message, add a row.", glyph: "tool", tone: "plain", group: "app", paid: false },
+  search: { kind: "search", name: "Search the web", blurb: "Look something up on the web.", glyph: "search", tone: "plain", group: "data", paid: true },
+  llm: { kind: "llm", name: "Ask the model", blurb: "One model call: write a line, sort a list, pull facts out of text.", glyph: "llm", tone: "model", group: "think", paid: true, mark: "model" },
+  agent: { kind: "agent", name: "Agent", blurb: "Hand a job that needs judgment to the agent, with a limit on what it may spend.", glyph: "agent", tone: "agent", group: "think", paid: true, mark: "agent" },
+  zero: { kind: "zero", name: "Buy paid data", blurb: "Pay for one call to a paid data service, up to a price you set. Plain steps, and the same call is never paid for twice.", glyph: "zero", tone: "plain", group: "data", paid: true },
+  automation: { kind: "automation", name: "Another automation", blurb: "Run another automation and use what it makes.", glyph: "automation", tone: "plain", group: "more", paid: false },
+};
+
+/** The kinds the engine runs today. Anything else can be drawn and is
+ *  saved only once the engine knows it (the platform refuses it until
+ *  then). A platform that runs more says so in `runnable` (a prop). */
+export const RUNNABLE = new Set(["action", "brain.read", "condition", "loop", "set", "wait", "stop", "notify", "tool", "search", "llm", "agent", "zero"]);
+
+export const isRunnable = (kind, runnable = RUNNABLE) => runnable.has(kind);
+
+const PALETTE_ORDER = ["action", "tool", "llm", "agent", "condition", "loop", "wait", "stop", "set", "brain.read", "search", "zero", "notify", "automation"];
+
+/** Palette order: the groups, and in each group the kinds in a fixed order. */
+export function paletteGroups() {
+  return GROUP_ORDER.map((group) => ({
+    group,
+    label: GROUP_LABELS[group],
+    kinds: PALETTE_ORDER.map((k) => KINDS[k]).filter((k) => k.group === group),
+  })).filter((g) => g.kinds.length > 0);
+}
+
+/* ---- a fresh step ------------------------------------------------------ */
+
+/** `brain.read` becomes `brain_read`: a step id's own alphabet. */
+const idBase = (kind) => kind.replace(/[^a-z0-9]+/g, "_");
+
+/** A step id no other step uses: `wait`, `wait_2`, `wait_3` … */
+export function uniqueStepId(kind, taken) {
+  const base = idBase(kind);
+  if (!taken.has(base)) return base;
+  for (let n = 2; n < 1000; n += 1) {
+    const id = `${base}_${n}`;
+    if (!taken.has(id)) return id;
+  }
+  return `${base}_${taken.size + 1}`;
+}
+
+/** A new step of a kind, with whatever default makes it read as itself.
+ *  Some kinds cannot be valid until a person names something (an action,
+ *  a tool): the settings panel asks for it, and the save waits. */
+export function newStep(kind, taken) {
+  const id = uniqueStepId(kind, taken);
+  switch (kind) {
+    case "action":
+      return { id, kind, action: "", input: {} };
+    case "brain.read":
+      return { id, kind, op: "search", input: { query: "" } };
+    case "condition":
+      return { id, kind, if: "{{ true }}", then: [], else: [] };
+    case "loop":
+      return { id, kind, over: "{{ trigger.items }}", max: 100, steps: [] };
+    case "set":
+      return { id, kind, values: { value: "" } };
+    case "wait":
+      return { id, kind, for: "10m" };
+    case "stop":
+      return { id, kind, message: "Done" };
+    case "notify":
+      return { id, kind, message: "Something to look at" };
+    case "tool":
+      return { id, kind, needs: { category: "mail" }, tool: "", input: {} };
+    case "search":
+      return { id, kind, query: "", limit: 5 };
+    case "llm":
+      return { id, kind, prompt: "", tier: "fast" };
+    case "agent":
+      return { id, kind, instructions: "", cap_credits: 50 };
+    case "zero":
+      return { id, kind, capability: "", url: "https://", max_pay_usd: 0.05 };
+    case "automation":
+      return { id, kind, key: "", input: {} };
+    default:
+      return { id, kind };
+  }
+}
+
+/* ---- words for a step on a card ---------------------------------------- */
+
+const strip = (text) => String(text ?? "").replace(/\{\{\s*|\s*\}\}/g, "").replace(/\s+/g, " ").trim();
+const cut = (text, n) => (text.length > n ? `${text.slice(0, n - 1).trimEnd()}…` : text);
+
+/** `read_mail` becomes "Read mail". */
+export function humanize(name) {
+  const s = String(name ?? "").replace(/[._-]+/g, " ").replace(/\s+/g, " ").trim();
+  return s ? s[0].toUpperCase() + s.slice(1) : "";
+}
+
+/** The card's title: the label the person gave it, else the kind's name
+ *  with what it is about. Written in full; the card wraps it. */
+export function stepTitle(step) {
+  if (step.label?.trim()) return step.label.trim();
+  switch (step.kind) {
+    case "action":
+      return step.action ? humanize(step.action) : "Pick an action";
+    case "tool":
+      return step.tool ? humanize(step.tool) : "Pick a tool";
+    case "condition":
+      return "Check a condition";
+    case "loop":
+      return "For each item";
+    case "brain.read":
+      return step.op === "get" ? "Read one record" : step.op === "list" ? "List records" : "Search the company brain";
+    case "set":
+      return "Set values";
+    case "wait":
+      return step.until ? "Wait until a time" : `Wait ${step.for ?? ""}`.trim();
+    case "stop":
+      return step.as === "failed" ? "Stop as failed" : "Stop";
+    case "notify":
+      return "Tell the owner";
+    case "search":
+      return "Search the web";
+    case "llm":
+      return "Ask the model";
+    case "agent":
+      return "Agent step";
+    case "zero":
+      return "Buy paid data";
+    case "automation":
+      return step.key ? `Run ${humanize(step.key)}` : "Run another automation";
+    default:
+      return humanize(step.kind);
+  }
+}
+
+/** "api.example.com · up to $0.05": where it goes and the most it may pay. */
+function zeroSub(step) {
+  const host = /^https:\/\/([^\s/{]+)/i.exec(String(step.url ?? "").trim())?.[1] ?? "";
+  const price = Number.isFinite(step.max_pay_usd) && step.max_pay_usd > 0 ? `up to $${Number(step.max_pay_usd).toString()}` : "";
+  return [host || "Needs an address", price].filter(Boolean).join(" · ");
+}
+
+/** The one quiet line under the title: "verb: object". */
+export function stepSub(step) {
+  switch (step.kind) {
+    case "action":
+      return step.app ? `in ${humanize(step.app)}` : "App action";
+    case "tool":
+      return step.needs?.category ? `Using ${step.needs.category}` : "Connected tool";
+    case "condition":
+      return cut(strip(step.if), 52);
+    case "loop":
+      return cut(`over ${strip(step.over)}${step.max ? `, up to ${step.max}` : ""}`, 52);
+    case "brain.read":
+      return Object.keys(step.input ?? {}).length ? `with ${Object.keys(step.input).slice(0, 3).join(", ")}` : "Company brain";
+    case "set":
+      return `Sets ${Object.keys(step.values ?? {}).slice(0, 3).join(", ") || "values"}`;
+    case "wait":
+      return step.until ? cut(strip(step.until), 52) : "Nothing runs meanwhile";
+    case "stop":
+      return cut(strip(step.message), 52);
+    case "notify":
+      return cut(strip(step.message), 52);
+    case "search":
+      return cut(strip(step.query) || "Web search", 52);
+    case "llm":
+      return step.tier === "smart" ? "Careful model" : "Quick model";
+    case "agent":
+      return cut(strip(step.instructions) || "Needs instructions", 52);
+    case "zero":
+      return cut(zeroSub(step), 52);
+    case "automation":
+      return "Another automation";
+    default:
+      return "";
+  }
+}

package/registry/blocks/automation-model/check.js

@@ -0,0 +1,161 @@
+// What is wrong with a definition, before the platform is asked.
+//
+// The platform validates every definition when it is saved (one validator,
+// whatever wrote the definition); a refusal comes back with `problems`,
+// one line each, and the builder shows those too. This file is the quick
+// check a screen makes on every edit, so a card can wear a red mark and
+// the Save button can say why it waits: the mistakes a person makes most,
+// in the words a person uses. It never says a definition is valid; only
+// the platform does.
+
+import { KINDS, RUNNABLE } from "./catalog";
+import { stepIdForPath } from "./edit";
+
+/** Words for the paths a person never sees spelled out. */
+function plainPath(path) {
+  if (!path) return "";
+  if (path.startsWith("trigger")) return "The trigger";
+  if (path.startsWith("settings")) return "The settings";
+  if (path.startsWith("inputs")) return "A question";
+  if (path.startsWith("name")) return "The name";
+  return "";
+}
+
+/** The platform's own wording for the mistakes a person makes most, in the
+ *  words a person uses. Anything not listed passes through as written. */
+export function plainWords(message) {
+  if (/^a condition needs steps in then, else or both/.test(message)) return "Add a step to the Yes or the No path, with the + on it.";
+  if (/^a loop has steps/.test(message)) return "Add a step inside the box, with the + on it.";
+  if (/^steps is a list with at least one step/.test(message)) return "Add a first step to save it.";
+  const unavailable = /^([a-z.]+) steps are not available yet/.exec(message);
+  if (unavailable) {
+    const info = KINDS[unavailable[1]];
+    return `${info?.name ?? unavailable[1]} steps cannot run yet. You can draw one, and save it once they can.`;
+  }
+  return message;
+}
+
+const blank = (v) => typeof v !== "string" || v.trim() === "";
+
+/** The most one Zero step may pay for a call, in USD: the platform's own ceiling
+ *  (claw shared/src/automation.ts ZERO_STEP_MAX_PAY_USD; keep the two equal). */
+const ZERO_MAX_PAY_USD = 2;
+
+/** One step's own problems: [{ path, message }]. */
+function stepProblems(step, path, runnable) {
+  const out = [];
+  const bad = (field, message) => out.push({ path: `${path}.${field}`, message });
+  if (!KINDS[step.kind]) {
+    out.push({ path, message: `${step.kind} is not a kind of step this editor knows.` });
+    return out;
+  }
+  if (!runnable.has(step.kind)) out.push({ path, message: `${step.kind} steps are not available yet.` });
+  switch (step.kind) {
+    case "action":
+      if (blank(step.action)) bad("action", "Pick the action to run.");
+      break;
+    case "tool":
+      if (blank(step.tool)) bad("tool", "Pick the tool to use.");
+      if (blank(step.needs?.category)) bad("needs", "Say what kind of account it uses.");
+      break;
+    case "condition":
+      if (blank(step.if)) bad("if", "Say when it goes the Yes way.");
+      if ((step.then ?? []).length + (step.else ?? []).length === 0) out.push({ path, message: "a condition needs steps in then, else or both." });
+      break;
+    case "loop":
+      if (blank(step.over)) bad("over", "Say which list to go through.");
+      if ((step.steps ?? []).length === 0) out.push({ path, message: "a loop has steps to repeat." });
+      break;
+    case "llm":
+      if (blank(step.prompt)) bad("prompt", "Say what to ask the model.");
+      break;
+    case "agent":
+      if (blank(step.instructions)) bad("instructions", "Tell the agent what to do.");
+      break;
+    case "search":
+      if (blank(step.query)) bad("query", "Say what to search for.");
+      break;
+    case "zero":
+      // A paid call needs the service, its address and a price it may not pass.
+      if (blank(step.capability)) bad("capability", "Say which paid service it uses.");
+      if (blank(step.url) || (!/^https:\/\/[^\s/]+/i.test(step.url.trim()) && !step.url.trimStart().startsWith("{{"))) bad("url", "Give the service's address, starting with https://.");
+      if (!(typeof step.max_pay_usd === "number" && Number.isFinite(step.max_pay_usd) && step.max_pay_usd > 0 && step.max_pay_usd <= ZERO_MAX_PAY_USD)) bad("max_pay_usd", `Set the most one call may cost: more than $0, and at most $${ZERO_MAX_PAY_USD}.`);
+      break;
+    case "stop":
+    case "notify":
+      if (blank(step.message)) bad("message", "Write the message.");
+      break;
+    case "wait":
+      if (blank(step.for) && blank(step.until)) bad("for", "Say how long to wait, or until when.");
+      break;
+    case "automation":
+      if (blank(step.key)) bad("key", "Say which automation to run.");
+      break;
+    default:
+      break;
+  }
+  return out;
+}
+
+/** Every step's problems, depth first, with the path the platform would
+ *  name (`steps[2].then[0].input`). */
+function walk(list, base, runnable, seen, out) {
+  list.forEach((step, i) => {
+    const path = `${base}[${i}]`;
+    if (seen.has(step.id)) out.push({ path, message: `the step id ${step.id} is used twice.` });
+    seen.add(step.id);
+    out.push(...stepProblems(step, path, runnable));
+    if (step.kind === "condition") {
+      walk(step.then ?? [], `${path}.then`, runnable, seen, out);
+      walk(step.else ?? [], `${path}.else`, runnable, seen, out);
+    } else if (step.kind === "loop") walk(step.steps ?? [], `${path}.steps`, runnable, seen, out);
+  });
+}
+
+/**
+ * checkAutomation(def, { runnable })
+ *   → [{ path, message, stepId }]
+ * `message` is for a person; `stepId` is the step it is about (null for
+ * the flow or its trigger). An empty canvas is not an error, only not
+ * finished, but it cannot be saved: the first problem says so.
+ */
+export function checkAutomation(def, { runnable = RUNNABLE } = {}) {
+  const raw = [];
+  if (blank(def.name)) raw.push({ path: "name", message: "Give it a name." });
+  const trigger = def.trigger ?? {};
+  if (trigger.type === "schedule" && String(trigger.cron ?? "").trim().split(/\s+/).length !== 5) {
+    raw.push({ path: "trigger.cron", message: "Use five fields: minute, hour, day, month, weekday." });
+  }
+  if (trigger.type === "event" && blank(trigger.topic)) raw.push({ path: "trigger.topic", message: "Say which event starts it." });
+  if (trigger.type === "action" && blank(trigger.action)) raw.push({ path: "trigger.action", message: "Pick the action it waits for." });
+  if (trigger.type === "automation" && blank(trigger.key)) raw.push({ path: "trigger.key", message: "Pick the automation it follows." });
+  if ((def.steps ?? []).length === 0) raw.push({ path: "steps", message: "steps is a list with at least one step." });
+  walk(def.steps ?? [], "steps", runnable, new Set(), raw);
+  return raw.map((p) => {
+    const said = plainWords(p.message);
+    const stepId = stepIdForPath(def, p.path);
+    // A blank canvas is not a mistake, only not finished.
+    const who = p.path === "steps" ? "" : stepId ? `“${stepId}”` : plainPath(p.path);
+    return { path: p.path, message: who ? `${who}: ${said}` : said, stepId };
+  });
+}
+
+/** Turn the platform's refusal lines (`problems`) into the same shape. */
+export function issuesFromProblems(def, problems) {
+  return (problems ?? []).map((line) => {
+    const m = /^([\w[\].]+):\s*(.*)$/.exec(line);
+    const path = m ? m[1] : "";
+    const stepId = path ? stepIdForPath(def, path) : null;
+    return { path, message: plainWords(m ? m[2] : line), stepId };
+  });
+}
+
+/** The steps with something wrong, for the red marks. */
+export function flaggedSteps(issues) {
+  return new Set(issues.map((i) => i.stepId).filter(Boolean));
+}
+
+/** The lines to show in one step's own panel. */
+export function issuesFor(issues, stepId) {
+  return issues.filter((i) => i.stepId === stepId).map((i) => i.message.replace(/^“[^”]*”: /, ""));
+}