makersclaw 0.7.0 → 0.8.1

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

@@ -0,0 +1,439 @@
+// The automation blocks' words: a schedule, a time, a cost, a health, a
+// run's outcome, each in the plain way a person reads them.
+//
+// Pure; the clock and the zone come in as arguments so a test can read
+// them. A time is shown in the automation's own zone: a 07:00 schedule
+// says 07:00 whoever is looking (an app once said "07:00" for a wake that
+// ran at 06:00 UTC; this file is why it cannot again).
+
+/* ---- a schedule in words (five-field cron) ------------------------------- */
+
+const andList = (names) => {
+  const unique = [...new Set(names)];
+  if (unique.length <= 1) return unique[0] ?? "";
+  return `${unique.slice(0, -1).join(", ")} and ${unique[unique.length - 1]}`;
+};
+
+const DAY_NAMES = ["Sundays", "Mondays", "Tuesdays", "Wednesdays", "Thursdays", "Fridays", "Saturdays"];
+const MONTH_NAMES = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const pad2 = (n) => String(n).padStart(2, "0");
+const clock = (h, m) => `${pad2(h)}:${pad2(m)}`;
+const capital = (s) => (s ? s[0].toUpperCase() + s.slice(1) : s);
+
+function ordinal(n) {
+  const last2 = n % 100;
+  if (last2 >= 11 && last2 <= 13) return `${n}th`;
+  return `${n}${["th", "st", "nd", "rd"][n % 10] ?? "th"}`;
+}
+
+/** A field's numbers: a literal, a list, ranges inside the list, or a `*` /
+ *  `a-b` step. Sorted, each once; null when a piece is anything else or out
+ *  of [min, max]. */
+function fieldValues(field, min, max) {
+  const out = new Set();
+  for (const piece of field.split(",")) {
+    const m = /^(?:(\*)|(\d{1,2})(?:-(\d{1,2}))?)(?:\/(\d{1,2}))?$/.exec(piece);
+    if (!m) return null;
+    const step = m[4] ? Number(m[4]) : 1;
+    if (step < 1) return null;
+    const from = m[1] ? min : Number(m[2]);
+    const to = m[1] ? max : m[3] !== undefined ? Number(m[3]) : m[4] ? max : from;
+    if (from < min || to > max || from > to) return null;
+    for (let v = from; v <= to; v += step) out.add(v);
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
+function daysPhrase(dow) {
+  if (dow === "*") return "";
+  const values = fieldValues(dow, 0, 7);
+  if (!values) return null;
+  const days = [...new Set(values.map((d) => d % 7))];
+  const key = [...days].sort((a, b) => a - b).join(",");
+  if (days.length === 7) return "";
+  if (key === "1,2,3,4,5") return "weekdays";
+  if (key === "0,6") return "weekends";
+  const mondayFirst = days.sort((a, b) => ((a + 6) % 7) - ((b + 6) % 7));
+  return andList(mondayFirst.map((d) => DAY_NAMES[d]));
+}
+
+/** The cron as a sentence ("Weekdays at 07:00", "Every 15 minutes"), or
+ *  null when it is not one of the shapes read here. A cron that names both
+ *  days of the month and days of the week is null: cron runs it on EITHER,
+ *  which no short sentence says honestly. */
+export function cronWords(cron) {
+  const fields = String(cron ?? "").trim().split(/\s+/);
+  if (fields.length !== 5) return null;
+  const [m, h, dom, mon, dow] = fields;
+  const minute = /^\d{1,2}$/.test(m) && Number(m) < 60 ? Number(m) : null;
+  const hours = /^\d{1,2}(,\d{1,2})*$/.test(h) ? fieldValues(h, 0, 23) : null;
+  const times = minute !== null && hours ? andList(hours.map((x) => clock(x, minute))) : null;
+
+  if (dom !== "*" || mon !== "*") {
+    if (dow !== "*" || !times) return null;
+    const days = dom === "*" ? null : fieldValues(dom, 1, 31);
+    const months = mon === "*" ? null : fieldValues(mon, 1, 12);
+    if ((dom !== "*" && !days) || (mon !== "*" && !months)) return null;
+    const monthWords = months ? andList(months.map((x) => MONTH_NAMES[x - 1])) : null;
+    if (!days) return `At ${times} every day in ${monthWords}`;
+    return `At ${times} on the ${andList(days.map(ordinal))} of ${monthWords ?? "each month"}`;
+  }
+
+  const days = daysPhrase(dow);
+  if (days === null) return null;
+  const withDays = (body) => (days ? `${capital(days)}, ${body}` : capital(body));
+  const everyMin = /^\*\/(\d{1,2})$/.exec(m);
+  if (everyMin && h === "*") {
+    const n = Number(everyMin[1]);
+    if (n < 1 || n > 59) return null;
+    return withDays(n === 1 ? "every minute" : `every ${n} minutes`);
+  }
+  if (m === "*" && h === "*") return withDays("every minute");
+  if (minute === null) return null;
+  const past = minute ? ` at :${pad2(minute)}` : "";
+  if (h === "*") return withDays(`every hour${past}`);
+  const everyH = /^\*\/(\d{1,2})$/.exec(h);
+  if (everyH) {
+    const n = Number(everyH[1]);
+    if (n < 1 || n > 23) return null;
+    return withDays(n === 1 ? `every hour${past}` : `every ${n} hours${past}`);
+  }
+  const range = /^(\d{1,2})-(\d{1,2})(?:\/(\d{1,2}))?$/.exec(h);
+  if (range) {
+    const [a, b] = [Number(range[1]), Number(range[2])];
+    const step = range[3] ? Number(range[3]) : 1;
+    if (a > 23 || b > 23 || a >= b || step < 1 || step > 23) return null;
+    const every = step === 1 ? "every hour" : `every ${step} hours`;
+    return withDays(`${every}, ${clock(a, minute)}–${clock(b, minute)}`);
+  }
+  if (!times) return null;
+  return days ? `${capital(days)} at ${times}` : `Every day at ${times}`;
+}
+
+/* ---- triggers ------------------------------------------------------------ */
+
+/** A name the platform writes with underscores or dots, as a person says it
+ *  ("add_people" is "add people"). */
+const plain = (name) => String(name ?? "").replace(/[._-]+/g, " ").replace(/\s+/g, " ").trim().toLowerCase();
+
+/** The kinds a record trigger names, as a person says them: "a contact",
+ *  "a contact or a deal", "a record" when it names none. */
+function kindsWords(kinds) {
+  const names = (Array.isArray(kinds) ? kinds : []).map(plain).filter(Boolean);
+  if (names.length === 0) return "a record";
+  return names.map((n) => `a ${n}`).join(" or ");
+}
+
+/** "Weekdays at 07:00" / "By hand" / "When “rows.imported” is sent". The zone
+ *  is named only when it is not the team's own. */
+export function triggerWords(trigger) {
+  if (!trigger || trigger.type === "manual") return "By hand";
+  switch (trigger.type) {
+    case "schedule": {
+      if (typeof trigger.cron !== "string") return "By hand";
+      const said = cronWords(trigger.cron) ?? trigger.cron;
+      const zone = typeof trigger.tz === "string" && trigger.tz !== "team" ? trigger.tz : null;
+      return zone ? `${said} (${zone})` : said;
+    }
+    case "event":
+      return trigger.topic ? `When “${trigger.topic}” is sent${trigger.app ? ` by ${trigger.app}` : ""}` : "When an event is sent";
+    case "action":
+      return trigger.action ? `When ${plain(trigger.action)} finishes${trigger.app ? ` in ${trigger.app}` : ""}` : "When an app action finishes";
+    case "record": {
+      const ops = Array.isArray(trigger.ops) && trigger.ops.length === 1 ? (trigger.ops[0] === "create" ? "added" : "changed") : "added or changed";
+      return `When ${kindsWords(trigger.kinds)} is ${ops}${trigger.app ? ` in ${trigger.app}` : ""}`;
+    }
+    case "webhook":
+      return "When its web address is called";
+    case "automation": {
+      const when = trigger.when === "failed" ? "fails" : trigger.when === "any" ? "ends" : "finishes";
+      return trigger.key ? `When “${trigger.key}” ${when}` : "When another automation finishes";
+    }
+    default:
+      return "By hand";
+  }
+}
+
+/** What a delete asks first, in plain words: what it does to this one. */
+export function deleteWords(name, status) {
+  return `Deletes "${name}". Its runs stay in history.${status === "on" ? " It is switched on, so deleting also switches it off." : ""}`;
+}
+
+/** A trigger type, as a person says it. */
+export function triggerTypeWords(type) {
+  switch (type) {
+    case "schedule":
+      return "On schedule";
+    case "manual":
+      return "By hand";
+    case "event":
+      return "By an event";
+    case "action":
+      return "By an app action";
+    case "record":
+      return "By a record";
+    case "webhook":
+      return "By a web address";
+    case "automation":
+      return "By another automation";
+    default:
+      return String(type ?? "");
+  }
+}
+
+/* ---- times --------------------------------------------------------------- */
+
+function zoneOr(tz) {
+  try {
+    new Intl.DateTimeFormat("en", { timeZone: tz });
+    return tz;
+  } catch {
+    return "UTC";
+  }
+}
+
+/** "Tue 07:00" for the next run, in the automation's zone; "Today 07:00"
+ *  and "Tomorrow 07:00" when it is that close. */
+export function clockWords(iso, tz, now = new Date()) {
+  if (!iso) return null;
+  const at = new Date(iso);
+  if (Number.isNaN(at.getTime())) return null;
+  const zone = zoneOr(tz);
+  const dayKey = (d) => new Intl.DateTimeFormat("en-CA", { timeZone: zone, year: "numeric", month: "2-digit", day: "2-digit" }).format(d);
+  const time = new Intl.DateTimeFormat("en-GB", { timeZone: zone, hour: "2-digit", minute: "2-digit", hour12: false }).format(at);
+  const today = dayKey(now);
+  const that = dayKey(at);
+  if (that === today) return `Today ${time}`;
+  if (that === dayKey(new Date(now.getTime() + 86_400_000))) return `Tomorrow ${time}`;
+  const weekday = new Intl.DateTimeFormat("en-GB", { timeZone: zone, weekday: "short" }).format(at);
+  const within = at.getTime() - now.getTime() < 6 * 86_400_000 && at.getTime() > now.getTime();
+  if (within) return `${weekday} ${time}`;
+  const date = new Intl.DateTimeFormat("en-GB", { timeZone: zone, day: "numeric", month: "short" }).format(at);
+  return `${date} ${time}`;
+}
+
+/** "3m ago", "yesterday", "5d ago". */
+export function agoWords(iso, now = new Date()) {
+  if (!iso) return null;
+  const t = new Date(iso).getTime();
+  if (Number.isNaN(t)) return null;
+  const s = (now.getTime() - t) / 1000;
+  if (s < 60) return "just now";
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86_400) return `${Math.floor(s / 3600)}h ago`;
+  if (s < 172_800) return "yesterday";
+  return `${Math.floor(s / 86_400)}d ago`;
+}
+
+/** "42 s", "3 min 10 s". */
+export function durationWords(from, to) {
+  if (!from || !to) return null;
+  const ms = new Date(to).getTime() - new Date(from).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return null;
+  const s = Math.round(ms / 1000);
+  if (s < 1) return "under a second";
+  if (s < 60) return `${s} s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m} min${s % 60 ? ` ${s % 60} s` : ""}`;
+  return `${Math.floor(m / 60)} h ${m % 60} min`;
+}
+
+/* ---- money --------------------------------------------------------------- */
+
+/** One decimal only when there is one: 3 is "3", 2.4 is "2.4", 29000 is
+ *  "29,000". */
+export const formatCreditAmount = (credits) => Number(credits).toLocaleString("en-US", { minimumFractionDigits: 0, maximumFractionDigits: 1 });
+
+/** "free" for nothing, else "2.4 cr". */
+export function creditsWords(value) {
+  const n = typeof value === "string" ? Number(value) : (value ?? 0);
+  if (!Number.isFinite(n) || n <= 0) return "free";
+  return `${formatCreditAmount(Math.round(n * 10) / 10)} cr`;
+}
+
+/** The price tag of each metered step, by step id, from a run's estimate
+ *  ({ steps: [{ id, credits, credits_max }] }): the figure a run is
+ *  expected to spend there (a loop's inner step: across its passes). */
+export function priceMap(estimate) {
+  const out = new Map();
+  for (const s of estimate?.steps ?? []) {
+    const prior = out.get(s.id);
+    out.set(s.id, { credits: (prior?.credits ?? 0) + s.credits, max: (prior?.max ?? 0) + s.credits_max });
+  }
+  return out;
+}
+
+/* ---- health and outcomes ------------------------------------------------- */
+
+/** A run's status as a tone and a word: { tone: green|blue|amber|red|grey,
+ *  text }. Never a status code. */
+export function runStatusWords(status, dry = false) {
+  if (dry) {
+    switch (status) {
+      case "done":
+        return { tone: "green", text: "Test passed" };
+      case "failed":
+        return { tone: "red", text: "Test failed" };
+      case "stopped":
+      case "needs_you":
+        return { tone: "amber", text: "Test stopped" };
+      case "running":
+      case "queued":
+        return { tone: "blue", text: "Testing" };
+      default:
+        break;
+    }
+  }
+  switch (status) {
+    case "done":
+      return { tone: "green", text: "Done" };
+    case "running":
+      return { tone: "blue", text: "Running" };
+    case "queued":
+      return { tone: "blue", text: "Starting" };
+    case "waiting":
+      return { tone: "amber", text: "Waiting" };
+    case "needs_you":
+      return { tone: "amber", text: "Needs its owner" };
+    case "failed":
+      return { tone: "red", text: "Failed" };
+    case "stopped":
+      return { tone: "grey", text: "Stopped" };
+    default:
+      return { tone: "grey", text: String(status ?? "") };
+  }
+}
+
+/** What a test run says a step would have done: the platform's own words
+ *  when the viewer may read them, else a plain line. Never an id. */
+export function wouldWords(row) {
+  const w = row?.output?.would;
+  const words = w && typeof w.words === "string" ? w.words.trim() : "";
+  return words || "Would run.";
+}
+
+/** A test run, in one or two plain sentences: "Test passed: nothing was sent
+ *  or changed. 3 steps would have run." `detail` is a run's account
+ *  ({ run }). Null for a run that was not a test. */
+export function testWords(detail) {
+  const run = detail?.run;
+  if (!run || run.dry !== true) return null;
+  const would = Number(run.result?.dry?.simulated ?? 0);
+  const count = Number.isFinite(would) && would > 0 ? would : 0;
+  if (run.status === "done") {
+    const tail = count === 0 ? "No step needed to change anything." : `${count} ${count === 1 ? "step" : "steps"} would have run.`;
+    return `Test passed: nothing was sent or changed. ${tail}`;
+  }
+  if (run.status === "failed") {
+    const why = run.error && typeof run.error.words === "string" ? run.error.words.trim() : "";
+    return why ? `Test failed. ${why}` : "Test failed.";
+  }
+  if (run.status === "stopped" || run.status === "needs_you" || run.status === "waiting") {
+    const why = run.error && typeof run.error.words === "string" ? run.error.words.trim() : "";
+    return why ? `Test stopped: ${why.charAt(0).toLowerCase()}${why.slice(1)}` : run.status === "stopped" ? "Test stopped." : "Test stopped: it needs something first.";
+  }
+  if (run.status === "running" || run.status === "queued") return "Testing: reading your real data, changing nothing.";
+  return null;
+}
+
+/** The list's health word for an automation row: how it is doing now. */
+export function healthOf(a) {
+  if (a.status === "needs_owner") return { tone: "amber", text: "Needs an owner" };
+  if (a.status === "draft" || a.live_version === null || a.live_version === undefined) return { tone: "grey", text: "Not live yet" };
+  if (a.status === "off") return { tone: "grey", text: "Off" };
+  if ((a.active_runs ?? 0) > 0) return { tone: "blue", text: "Running" };
+  const last = a.last_run;
+  if (!last) return { tone: "grey", text: "Has not run yet" };
+  if (last.status === "failed") return { tone: "red", text: "Last run failed" };
+  if (last.status === "needs_you") return { tone: "amber", text: "Needs its owner" };
+  if (last.status === "waiting") return { tone: "amber", text: "Waiting" };
+  return { tone: "green", text: "Healthy" };
+}
+
+export function nodeStateWords(state) {
+  switch (state) {
+    case "done":
+      return "Done";
+    case "running":
+      return "Running";
+    case "failed":
+      return "Failed";
+    case "fixed":
+      return "Fixed by the agent";
+    case "would":
+      return "Would run";
+    case "waiting":
+      return "Waiting";
+    case "skipped":
+      return "Skipped";
+    case "unknown":
+      return "Needs a look";
+    case "notreached":
+      return "Not reached";
+    default:
+      return "";
+  }
+}
+
+/** The list's one line of where an automation lives: the team's, or an
+ *  app's. `appName(id)` names an app, or null. */
+export function originWords(a, appName) {
+  if (a.owner_kind === "app" && a.app_id) return appName?.(a.app_id) ?? "An app";
+  return "Team";
+}
+
+/** "Run 7 · 3m ago · Done": a run, in one line. */
+export function runLine(run, n) {
+  const status = runStatusWords(run.status, run.dry === true).text;
+  return `${run.is_test ? "Test " : "Run "}${n} · ${agoWords(run.created_at) ?? "just now"} · ${status}`;
+}
+
+/* ---- the list's and the runs' counts ------------------------------------- */
+
+/** What the list's one line counts: what is on, what failed, what waits for
+ *  its owner, and which runs next. */
+export function summaryOf(rows, now = new Date()) {
+  let on = 0;
+  let failing = 0;
+  let needs = 0;
+  let next = null;
+  for (const r of rows ?? []) {
+    if (r.status === "on") on += 1;
+    if (r.last_run?.status === "failed") failing += 1;
+    if (r.status === "needs_owner" || r.last_run?.status === "needs_you") needs += 1;
+    if (r.status === "on" && r.next_run_at && new Date(r.next_run_at) > now && (!next || r.next_run_at < next.next_run_at)) next = r;
+  }
+  return { on, failing, needs, next };
+}
+
+/** A run still going or waiting on someone. */
+export const ACTIVE = new Set(["queued", "running", "waiting", "needs_you"]);
+
+/** An automation's runs, counted: what finished, what failed, what is
+ *  going, and what it cost. */
+export function overviewOf(runs) {
+  let done = 0;
+  let failed = 0;
+  let active = 0;
+  let credits = 0;
+  for (const r of runs ?? []) {
+    if (r.status === "done") done += 1;
+    else if (r.status === "failed") failed += 1;
+    else if (ACTIVE.has(r.status)) active += 1;
+    const c = typeof r.credits === "string" ? Number(r.credits) : r.credits;
+    if (Number.isFinite(c)) credits += c;
+  }
+  return { done, failed, active, credits };
+}
+
+/** The report a run left, as short lines (a number or a word each). */
+export function reportLines(result) {
+  if (!result) return [];
+  const out = [];
+  for (const [k, v] of Object.entries(result)) {
+    if (out.length >= 8) break;
+    if (v === null || v === undefined) continue;
+    if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") out.push({ label: k.replace(/_/g, " "), value: String(v) });
+  }
+  return out;
+}

package/registry/blocks/automations-screen/README.md

@@ -0,0 +1,207 @@
+# AutomationsScreen
+
+The whole Automations page of an app, as ONE block. It answers "how do I give
+my app an Automations page?" with one component and a handful of props, so a
+fix to the page reaches every app through `update` and no app carries a copy.
+
+The places a member goes:
+
+- **The list** — each automation as a row that opens whole, an on/off switch,
+  **New automation** (the starting points, **Describe it**), the week's
+  **allowance shown once** above the rows, and two slots under them: jobs that
+  run **on request** and the app's own **extras**.
+- **New** — a new automation in the editor, from a starting point or blank. It
+  is not saved until **Create**.
+- **One automation** — its flow on a canvas, edited, tested, kept and switched
+  on; its **Runs**; and any tabs the app adds.
+- **One run** — step by step, with the run's controls (pause, retry, skip…)
+  and the agent's fixes.
+
+It composes `automation-list`, `automation-editor`, `run-view` and `cost`, and
+decides only what they leave open:
+
+- **Which place is showing, and how it travels in a page address.** The place
+  is `{ automation, tab, run, start }`; `placeFromParams` and `paramsOfPlace`
+  turn it into and out of the query string. Hold it yourself (`place` +
+  `onPlace`) or leave it to the block.
+- **Back to where the member WAS.** Back from an automation is the list with
+  the words that were in its search box. Back from a run is the Runs tab it was
+  opened from (or the flow, when it was opened from a test).
+- **What each editor is handed**: the platform's `triggers`, the automation's
+  `selfKey`, its webhook (`hook`, `onRotateHook`), its `tests`, `compareTo`
+  (what "What changed" compares an agent's draft with), the app's declared
+  `actions`, and the save with `baseVersion` (a save names the version the copy
+  began on, so an agent's newer draft is never buried).
+- **A delete that asks first and can be undone.** The row's menu and the
+  editor's menu ask (`Deletes "<name>". Its runs stay in history.`); then a
+  toast says what was deleted, which automations followed it and will no longer
+  start, and offers **Undo** for a few seconds.
+- **Describe it** — to the platform (`onDescribe="platform"`), or handed on to
+  the agent beside the page (`onDescribe={(ask) => …}`).
+- **The app's older schedule.** A row from before the engine (`source:
+  "legacy"`) opens read-only, with a line saying why.
+
+```jsx
+import { AutomationsScreen, placeFromParams, paramsOfPlace } from "../components/blocks/automations-screen";   // a Makersclaw app
+import { AutomationsScreen, placeFromParams, paramsOfPlace } from "@/components/makersclaw/blocks/automations-screen";   // a shadcn project
+```
+
+`makersclaw add automations-screen` lays `automation-list`, `automation-editor`,
+`run-view`, `cost` and `automation-model` (and what they need) with it. A
+client component. It fills its parent's height (give it a parent with one, or a
+`frame`), and each block inside decides its own layout from its own width.
+
+## Props
+
+### Required
+
+- `hooks` — the engine's hooks and doors, from `lib/hooks`: `{ useAutomations,
+  useAutomation, useAutomationRun, deleteAutomation, restoreAutomation }`. A
+  block may not import `lib/`, so they come in here. The first three are
+  required (without them the block draws a plain notice naming what is
+  missing); the two doors are optional (without `deleteAutomation` there is no
+  Delete; without `restoreAutomation` no Undo). Pass a module-level object so
+  it is the same on every render.
+
+### Where it is
+
+- `place`, `onPlace(place)` — the place, controlled. Leave both out and the
+  block holds it. `place` is `{ automation: null | "new" | <id>, tab: "flow" |
+  "runs" | <an extra tab's key>, run: <run id> | null, start: <starting point
+  id> | null }`; anything missing is the list. Always called back with a
+  complete place.
+- `placeFromParams(searchParams)` → a place. Takes a `URLSearchParams`, a
+  `useSearchParams()` result or a function name → value; reads `automation`,
+  `tab`, `run`, `start`.
+- `paramsOfPlace(place)` → the query parameters of a place, only what is set
+  (the list is `{}`); spread them into your own: `{ view: "automations",
+  ...paramsOfPlace(place) }`.
+- `query`, `onQueryChange(text)` — the list's search box. Held by the block
+  unless you pass them (to keep it across a reload, say).
+
+### The list
+
+- `title` ("Automations"), `intro` — the list's heading and its line.
+- `allowance` — `{ used, of, words? }`: the week's credits, drawn once above
+  the list as a meter (`cost`'s `Allowance`). From `useJobs().budget`
+  (`week_used_credits`, `week_cap_credits`). `null` (default): none. `words` is
+  your own line ("4,180 of 10,000 credits this week").
+- `onRequest`, `extras` — nodes, or functions `({ automations }) => node`, drawn
+  under the rows once they have loaded (`onRequest` first). `onRequest` is for
+  jobs a press or an ask starts and no schedule runs; `extras` is anything else
+  of the app's.
+- `starts` — the app's own starting points: `[{ id, name, blurb, glyph, needs,
+  build(takenKeys) → a whole definition }]`, offered first under New. The
+  platform's come after them (or, where it has none, the template's five).
+- `onDescribe` — `"platform"` (the platform drafts it, one model call, and the
+  new automation opens), a function `(ask) => Promise<{ ok: true } | { ok:
+  false, error }>` (the sentence is handed on, to an agent beside the page say;
+  the box empties), or nothing (no Describe it). `describePrice` (the words on
+  the Draft it button; `""` for none), `describeChips`.
+- `onToggled(row, on)` — async, after a switch was saved. Keep a setting of the
+  app's own in step with it; a throw is shown above the rows.
+- `canToggle`, `canCreate`, `canDelete` — all true by default.
+- `now` — the clock, for a test.
+
+### One automation
+
+- `actions` — the app's declared actions, for the action step: `[{ name,
+  description }]` (`manifest.actions` without those marked `agent: false`).
+- `apps`, `runnable`, `ownedByApp` (default true) — as the editor's.
+- `extraTabs` — tabs the app adds beside Flow and Runs: `[{ key, label,
+  when?(automation) → bool, render({ automation, definition, tab, runId, go })
+  → node }]`. `when` decides which automations get the tab (omit: all). `flow`
+  and `runs` are not yours.
+- `aboveOne` — a node, or `({ automation, definition, tab, runId, run, go }) =>
+  node`: drawn above an automation (a connection it needs, a notice).
+- `afterRun` — the same, under a run (the app's own account of it). `run` is the
+  run.
+- `legacyWords` — the line over a read-only older schedule (`false`: none).
+- Run again, in a run: after a test it is a test; after a real run it is a real
+  run (it spends, and it acts). The run-view block says which on the button.
+- `onFocus({ selected, unsaved, baseVersion })` — the editor's, for an agent
+  pane beside the page that must know what the member is looking at.
+- `every` — how often the hooks look again, in ms (default theirs: 30 s, 5 s
+  while one runs). Lower it while an agent beside the page works.
+
+### The frame
+
+- `frame({ crumb, label, fill, children })` — a plain function (no hooks in it)
+  that wraps each place in the app's chrome and returns it. `crumb` is
+  `[{ label, href?, onPress? }]`: the ancestors (with `onPress`, and `href` when
+  you give `hrefOf`) then the page you are on. `label` names the content region;
+  `fill` is true where the body owns its own scrolling (the editor, a run).
+  **The first crumb is always the list itself** (the block's `title`; on the
+  list it is the only crumb), and its `onPress` goes back to the list with
+  the member's search kept: use `onPress` when it is there, `href` only when
+  you gave `hrefOf`. An app that draws its own root crumb ("Morning checks"
+  above the page) drops that first one: `crumb.slice(1)`. Default: the kit's `AppLayout` filling its parent. An app draws its top bar
+  here and returns `<AppLayout …>`:
+
+  ```jsx
+  frame={({ crumb, label, fill, children }) => (
+    <>
+      <TopBar icon="zap" crumb={crumb.map((c) => ({ label: c.label, href: c.href }))} />
+      <AppLayout contentLabel={label} contentMode={fill ? "fill" : undefined}>{children}</AppLayout>
+    </>
+  )}
+  ```
+- `hrefOf(place)` → a string. When given, ancestor crumbs carry an `href`.
+- `unavailableWords` — the line where this Makersclaw has no engine yet.
+
+## Example
+
+The whole page of an app whose address carries the place:
+
+```jsx
+"use client";
+import { useRouter, useSearchParams } from "next/navigation";
+import { useAutomation, useAutomationRun, useAutomations, deleteAutomation, restoreAutomation, useJobs } from "../lib/hooks";
+import { AutomationsScreen, paramsOfPlace, placeFromParams } from "../components/blocks/automations-screen";
+import manifest from "../makersclaw.json";
+
+const HOOKS = { useAutomations, useAutomation, useAutomationRun, deleteAutomation, restoreAutomation };
+const ACTIONS = (manifest.actions ?? []).filter((a) => a.agent !== false).map((a) => ({ name: a.name, description: a.description }));
+
+export default function Automations() {
+  const router = useRouter();
+  const sp = useSearchParams();
+  const { budget } = useJobs();
+  return (
+    <AutomationsScreen
+      hooks={HOOKS}
+      place={placeFromParams(sp)}
+      onPlace={(place) => router.push(`/s/today?${new URLSearchParams({ view: "automations", ...paramsOfPlace(place) })}`, { scroll: false })}
+      actions={ACTIONS}
+      allowance={budget ? { used: budget.week_used_credits, of: budget.week_cap_credits } : null}
+      onDescribe="platform"
+      onRequest={<p className="text-sm text-muted-foreground">The first read starts when a mailbox connects.</p>}
+    />
+  );
+}
+```
+
+## States
+
+Drawn in the demo (a state picker and a width picker for 1280, 800, 368 and
+320 px): many automations (one with a very long name), one, none (the first-run
+screen with starting points and Describe it), loading (a skeleton, never the
+first-run screen), the list failing to load (a notice with Try again), a
+platform without the engine, an app's older read-only schedule, an automation
+that will not open or is gone (a line and a way back), a run that will not open,
+a test run, a run opened from the Runs tab, an app tab, a delete with its
+Undo, and a delete the platform refuses (an app's own job).
+
+## Who may do what
+
+The platform decides; a hidden button is never the guard. Any member who opens
+the app edits and runs its automations. A delete is the owner's or an admin's;
+a refusal comes back in the platform's own words and is shown as it is.
+
+## Never
+
+- Never import `lib/` here: the hooks are the `hooks` prop.
+- Never a run that starts on its own: a run starts only on Test run or Run again.
+- Never a second Allowance: it is drawn once, on the list.
+- Never the raw words of a failure: a list that cannot load says so in one plain
+  sentence; the blocks inside show the platform's plain words.