makersclaw 0.8.0 → 0.8.1

package/registry/blocks/top-bar/top-bar-model.js

@@ -0,0 +1,152 @@
+// The top bar's rules, as plain functions and one table: what the bar draws
+// at a given width, in what order things give way, and whether Ask is drawn.
+// No React here, so a test can walk every width and the server can use it.
+//
+// Why a table (2026-10-12, the UI review): fourteen apps drew their own top
+// bar, and in Newsletter the week's allowance ran into Find. A bar that is
+// told only "hide this under 56rem" overlaps the day an app adds a longer
+// button. So every piece has a width it is allowed to take (`rem`) and the
+// bar width it appears from (`from`, a Tailwind container size), and a test
+// walks the widths from a phone to a wide desk and checks that what is drawn
+// always fits. The CSS classes in `SHOW` are written from the same table.
+
+/** Container sizes, in rem, as Tailwind v4 names them (@lg = 32rem…). */
+export const SIZES = { xs: 20, sm: 24, md: 28, lg: 32, xl: 36, "2xl": 42, "3xl": 48, "4xl": 56, "5xl": 64, "6xl": 72 };
+
+/** The width the bar has to give each piece, in rem, and where it appears.
+ *  `from: null` is always drawn. The crumb's last label is the floor: it
+ *  truncates, but never gives up the room it is counted here. `extra` and
+ *  the action's label are the app's: they are held to these widths (the
+ *  README says how; `BarText` hides a label under `lg`). */
+export const PIECES = [
+  { key: "lead", rem: 2.5, from: null },
+  { key: "crumb", rem: 5, from: null },
+  { key: "find", rem: 2.5, from: null },
+  { key: "ask", rem: 2.5, from: null },
+  { key: "action", rem: 2.5, from: null },
+  { key: "findLabel", rem: 3.5, from: "lg" },
+  { key: "askLabel", rem: 2.5, from: "lg" },
+  { key: "actionLabel", rem: 7, from: "lg" },
+  { key: "trail", rem: 0, from: "xl" }, // earlier crumbs and the note: they truncate, so they take what is left and no more
+  { key: "findKey", rem: 3.2, from: "2xl" },
+  { key: "extra", rem: 12, from: "3xl" },
+  { key: "allowance", rem: 5, from: "4xl" },
+  { key: "allowanceWords", rem: 8, from: "5xl" },
+];
+
+/** Space between neighbours, in rem (gap-1.5). */
+export const GAP = 0.375;
+
+/** The classes that show a piece from its size and hide it under, written
+ *  whole so Tailwind reads them. */
+export const SHOW = {
+  findLabel: "hidden @lg/bar:inline",
+  askLabel: "hidden @lg/bar:inline",
+  // The action's words stay for a screen reader under 32rem (a button that is
+  // only its icon still has its name): sr-only there, drawn from 32rem.
+  actionLabel: "sr-only @lg/bar:not-sr-only",
+  trailFlex: "hidden @xl/bar:flex",
+  trailInline: "hidden @xl/bar:inline",
+  findKey: "hidden @2xl/bar:inline-flex",
+  extra: "hidden @3xl/bar:flex",
+  allowance: "hidden @4xl/bar:flex",
+  allowanceWords: "hidden @5xl/bar:inline",
+};
+
+const has = (piece, present) => (piece.key.startsWith("find") ? present.find : piece.key.startsWith("ask") ? present.ask : true);
+
+/** The pieces drawn in a bar `rem` wide. `present`: { find, ask } say whether
+ *  those are drawn at all (an app can leave Find out; it can never leave
+ *  Ask out when it has a dock). */
+export function visibleAt(rem, present = { find: true, ask: true }) {
+  return PIECES.filter((p) => has(p, present) && (p.from === null || rem >= SIZES[p.from])).map((p) => p.key);
+}
+
+/** The room the drawn pieces take at `rem`, gaps included. A label rides
+ *  inside its button, so only these items have a gap between them. */
+const ITEMS = ["lead", "crumb", "find", "ask", "action", "extra", "allowance"];
+export function usedAt(rem, present = { find: true, ask: true }) {
+  const keys = new Set(visibleAt(rem, present));
+  const sum = PIECES.filter((p) => keys.has(p.key)).reduce((n, p) => n + p.rem, 0);
+  const items = ITEMS.filter((k) => keys.has(k)).length;
+  return sum + Math.max(0, items - 1) * GAP;
+}
+
+/** True when what is drawn at `rem` fits with nothing over it. */
+export function fitsAt(rem, present) {
+  return usedAt(rem, present) <= rem;
+}
+
+/** The narrowest bar the table is true for: what is always drawn. */
+export function floorRem(present) {
+  return usedAt(0, present);
+}
+
+/** Is Ask drawn? Whenever the app has an agent to ask: a dock handed over,
+ *  an `onAsk`, or an AskProvider above the bar. There is no prop that turns
+ *  it off, and that is the point: an app with a dock cannot have an agent
+ *  nobody can open. */
+export function askDrawn({ dock, onAsk, context } = {}) {
+  return Boolean(dock || onAsk || context);
+}
+
+/** What pressing Ask does: an `onAsk` the app gave wins, then the dock's
+ *  toggle, then the provider's. Null when there is nothing to open. */
+export function askAction({ dock, onAsk, context } = {}) {
+  if (typeof onAsk === "function") return onAsk;
+  if (dock && typeof dock.toggle === "function") return dock.toggle;
+  if (context && typeof context.toggle === "function") return context.toggle;
+  return null;
+}
+
+/** Whether the agent is open, for aria-pressed. */
+export function askOpen({ dock, asking, context } = {}) {
+  if (typeof asking === "boolean") return asking;
+  if (dock && typeof dock.open === "boolean") return dock.open;
+  if (context && typeof context.open === "boolean") return context.open;
+  return false;
+}
+
+/** The props a screen's TopBar may leave to the shell: the week's allowance
+ *  and how Find is reached are the same on every screen of an app, so the
+ *  shell says them once on its AskProvider and a bar uses them unless it
+ *  passes its own. */
+export const BAR_DEFAULTS = ["allowance", "allowanceLabel", "allowanceUnit", "allowancePeriod", "onFind", "findEvent", "findLabel", "findWord", "askLabel"];
+
+/** The shell's defaults, from the props it gave AskProvider: only the keys it
+ *  set, `undefined` ones left out. */
+export function barDefaultsOf(props = {}) {
+  const out = {};
+  for (const key of BAR_DEFAULTS) if (props[key] !== undefined) out[key] = props[key];
+  return out;
+}
+
+/** One screen's bar props over the shell's defaults. A prop the screen passes
+ *  (even `null`, which leaves the allowance out for that screen) wins; one it
+ *  leaves `undefined` takes the shell's; else the built-in ("cr", "this
+ *  week"). */
+export function resolveBar(own = {}, defaults = {}) {
+  const out = {};
+  for (const key of BAR_DEFAULTS) out[key] = own[key] !== undefined ? own[key] : defaults[key];
+  out.allowanceUnit ??= "cr";
+  out.allowancePeriod ??= "this week";
+  return out;
+}
+
+/** The allowance as { left, used, cap, pct } from the platform's budget
+ *  ({ used, cap }); null when there is no cap to count against. */
+export function allowanceOf(allowance) {
+  const cap = Number(allowance?.cap);
+  if (!allowance || !Number.isFinite(cap) || cap <= 0) return null;
+  const used = Math.max(0, Number(allowance.used) || 0);
+  return { used, cap, left: Math.max(0, cap - used), pct: Math.min(100, Math.round((used / cap) * 100)) };
+}
+
+const num = (n) => Math.round(Number(n)).toLocaleString("en-US");
+
+/** The allowance in words: "15,000 cr left" and, from 64rem, " this week". */
+export function allowanceWords(allowance, { unit = "cr", period = "this week" } = {}) {
+  const a = allowanceOf(allowance);
+  if (!a) return null;
+  return { short: `${num(a.left)} ${unit} left`, long: `${num(a.left)} ${unit} left ${period}`, period, left: a.left, cap: a.cap };
+}

package/registry/blocks/top-bar/top-bar.jsx

@@ -0,0 +1,244 @@
+"use client";
+
+import { createContext, useCallback, useContext, useMemo } from "react";
+import { createPortal } from "react-dom";
+import { Button, Icon, IconButton, Kbd, Meter, cx } from "../../ui";
+import { SHOW, allowanceOf, allowanceWords, askAction, askDrawn, askOpen, barDefaultsOf, resolveBar } from "./top-bar-model";
+
+// TopBar — the one bar every app draws over its work (2026-10-12). It holds
+// where you are, the week's allowance, Find, Ask and the page's action, and
+// it gives way in a set order as the app's window narrows, so nothing runs
+// into anything:
+//
+//   always      the menu/lead, the last crumb, Find and Ask as icons, the action
+//   from 32rem  the words on Find, Ask and the action (BarText)
+//   from 36rem  the earlier crumbs and the note
+//   from 42rem  the ⌘K key on Find
+//   from 48rem  `extra` (a switch, a chip)
+//   from 56rem  the allowance, as a bar
+//   from 64rem  the allowance in words
+//
+// The sizes are measures of the BAR, not the window: the app lives in a frame
+// on the desk, and an open agent dock takes a quarter of it. top-bar-model.js
+// holds the table; a test walks every width and checks what is drawn fits.
+//
+// Ask is never optional. If the app has an agent to ask (a `dock` from
+// useAgentDock, an `onAsk`, or an AskProvider above the bar) the bar draws
+// Ask and it opens the agent. There is no prop that leaves it out, so an app
+// that mounts an AgentDock cannot have an agent nobody can reach (Gantt
+// Planner, 2026-10-12: the dock was mounted and no button opened it).
+// `npm run check` (rule 19, ask) refuses the app that mounts a dock without
+// one.
+
+/** Where a screen's bar goes: the shell's header slot (an element). Leave it
+ *  unprovided and the bar draws where it is rendered (as an AppLayout's
+ *  `header`); provide null until the slot has mounted and it draws nothing. */
+export const TopBarSlot = createContext(undefined);
+
+const AskContext = createContext(null);
+const BarContext = createContext({});
+
+/** Put the app's agent within reach of every bar below, and say the bar's
+ *  defaults once: the shell wraps its layout in it, with the dock
+ *  useAgentDock() returned, and no screen has to pass anything to its TopBar.
+ *    dock     what useAgentDock() returned ({ open, toggle })
+ *    onAsk    or your own opener, when there is no dock yet
+ *    open     with onAsk: whether the agent is open (aria-pressed)
+ *  and the props every screen's bar repeats, which a bar uses unless it passes
+ *  its own (pass `allowance={null}` on a screen to leave it out there):
+ *    allowance, allowanceLabel, allowanceUnit, allowancePeriod
+ *    findEvent, onFind, findLabel, findWord
+ *    askLabel */
+export function AskProvider({ dock, onAsk, open, children, ...bar }) {
+  const toggle = askAction({ dock, onAsk });
+  const isOpen = askOpen({ dock, asking: open });
+  const value = useMemo(() => (toggle ? { toggle, open: isOpen } : null), [toggle, isOpen]);
+  const d = barDefaultsOf(bar);
+  // The allowance is a fresh object each render; what matters is its numbers.
+  const key = JSON.stringify([d.allowance?.used ?? null, d.allowance?.cap ?? null, d.allowanceLabel, d.allowanceUnit, d.allowancePeriod, d.findEvent, d.findLabel, d.findWord, d.askLabel]);
+  const defaults = useMemo(() => d, [key, d.onFind]); // eslint-disable-line react-hooks/exhaustive-deps
+  return (
+    <AskContext.Provider value={value}>
+      <BarContext.Provider value={defaults}>{children}</BarContext.Provider>
+    </AskContext.Provider>
+  );
+}
+
+/** { toggle, open } from the nearest AskProvider, or null. */
+export function useAsk() {
+  return useContext(AskContext);
+}
+
+/** A label for the bar's buttons that gives way under 32rem, leaving the
+ *  icon; a screen reader still hears it (it is sr-only there, so an icon-only
+ *  button keeps its name). Use it for the action's words: `<Button
+ *  icon="plus"><BarText>New issue</BarText></Button>`. The button needs an
+ *  icon, or under 32rem there is nothing to see (npm run check, rule
+ *  barlabel). Keep the words to about 12 characters. */
+export function BarText({ children, className }) {
+  return <span className={cx(SHOW.actionLabel, className)}>{children}</span>;
+}
+
+/** The Ask button. TopBar draws it; use it on its own only in a bar of your
+ *  own that cannot be a TopBar (the check accepts it as the way in).
+ *    dock, onAsk, asking   as AskProvider; the provider's is the default
+ *    label                 the words from 32rem. Default "Ask" */
+export function AskButton({ dock, onAsk, asking, label = "Ask", className }) {
+  const context = useContext(AskContext);
+  const act = askAction({ dock, onAsk, context });
+  const on = useCallback(() => act?.(), [act]);
+  if (!askDrawn({ dock, onAsk, context })) return null;
+  return (
+    <Button size="sm" onClick={on} data-bar-piece="ask" aria-label="Ask the agent" aria-pressed={askOpen({ dock, asking, context })} className={className}>
+      <Icon name="sparkles" size={14} />
+      <span className={SHOW.askLabel}>{label}</span>
+    </Button>
+  );
+}
+
+/** The Find button. `onFind`, or else a window event named `event` (the
+ *  app's finder listens for it).
+ *    label  what a screen reader hears ("Find an issue, a change or a post")
+ *    word   the visible word from 32rem. Default "Find" */
+export function FindButton({ onFind, event = "app:find", label = "Find", word = "Find", className }) {
+  const on = () => (onFind ? onFind() : window.dispatchEvent(new CustomEvent(event)));
+  return (
+    <Button size="sm" onClick={on} data-bar-piece="find" aria-label={label} className={className}>
+      <Icon name="search" size={14} />
+      <span className={SHOW.findLabel}>{word}</span>
+      <Kbd className={SHOW.findKey}>⌘K</Kbd>
+    </Button>
+  );
+}
+
+// The allowance: its words, then the kit's Meter in its compact form (the bar
+// alone; the label and the numbers go to a screen reader and the tooltip).
+function AllowanceBar({ allowance, unit, period, label }) {
+  const a = allowanceOf(allowance);
+  const words = allowanceWords(allowance, { unit, period });
+  if (!a) return null;
+  return (
+    <span data-bar-piece="allowance" className={cx(SHOW.allowance, "shrink-0 items-center gap-2 whitespace-nowrap text-xs text-muted-foreground")}>
+      <span className="tabular-nums">
+        {words.short}
+        <span className={SHOW.allowanceWords}> {period}</span>
+      </span>
+      <Meter value={a.used} max={a.cap} label={label ?? "Allowance"} unit={unit} valueText={null} size="thin" compact className="w-14" />
+    </span>
+  );
+}
+
+function Crumb({ items, back }) {
+  const last = items[items.length - 1];
+  return (
+    <nav aria-label="Where you are" data-bar-piece="crumb" className="flex min-w-0 shrink items-center gap-1.5 overflow-hidden whitespace-nowrap font-medium">
+      {back ? <IconButton icon="chevron-left" label="Back" size="sm" href={back} /> : null}
+      {items.map((c, i) => {
+        const here = c === last;
+        return (
+          <span key={`${c.label}-${i}`} className={cx("flex min-w-0 items-center gap-1.5", here ? "shrink" : cx(SHOW.trailFlex, "shrink-[4]"))}>
+            {i ? (
+              <span aria-hidden="true" className={SHOW.trailInline}>
+                <Icon name="chevron-right" size={12} className="shrink-0 text-muted-foreground" />
+              </span>
+            ) : null}
+            {c.href && !here ? (
+              <span className="min-w-0 truncate font-normal">
+                <Button variant="link" tone="muted" size="inherit" href={c.href}>
+                  {c.label}
+                </Button>
+              </span>
+            ) : (
+              <span className={cx("min-w-0 truncate", c.muted && "font-normal text-muted-foreground")} aria-current={here ? "page" : undefined}>
+                {c.label}
+              </span>
+            )}
+          </span>
+        );
+      })}
+    </nav>
+  );
+}
+
+/**
+ * One screen's top bar.
+ *
+ *   lead        a node before everything (the sidebar trigger, a period picker)
+ *   back        a path: a back button before the crumb
+ *   crumb       [{ label, href?, muted? }]: where you are; the last is this screen
+ *   note        muted words after the crumb (from 36rem)
+ *   extra       nodes before the allowance (from 48rem)
+ *   allowance   { used, cap } of the week's credits, from the platform's budget
+ *               (null: nothing drawn). `allowanceLabel`, `allowanceUnit` ("cr"),
+ *               `allowancePeriod` ("this week"). Left out, the shell's
+ *               AskProvider says them once; null leaves it out on this screen
+ *   find        false leaves Find out. `onFind`, or `findEvent` (a window event;
+ *               default "app:find"), `findLabel` (for a screen reader), `findWord`.
+ *               Left out, the AskProvider's are used
+ *   dock        what useAgentDock() returns: Ask opens it
+ *   onAsk       or your own opener. Neither: the nearest AskProvider's. If none,
+ *               the app has no agent and no Ask is drawn
+ *   asking      whether the agent is open, when you pass onAsk
+ *   askLabel    the word on Ask. Default "Ask"
+ *   action      the screen's main action, last in the bar: a Button whose words
+ *               are <BarText>
+ *   className   spacing only
+ *
+ * It draws where it is rendered (as an AppLayout `header`), or into the
+ * shell's header slot when a TopBarSlot is provided.
+ */
+export function TopBar({
+  lead,
+  back,
+  crumb = [],
+  note,
+  extra,
+  allowance: allowanceOwn,
+  allowanceLabel: allowanceLabelOwn,
+  allowanceUnit: allowanceUnitOwn,
+  allowancePeriod: allowancePeriodOwn,
+  find = true,
+  onFind: onFindOwn,
+  findEvent: findEventOwn,
+  findLabel: findLabelOwn,
+  findWord: findWordOwn,
+  dock,
+  onAsk,
+  asking,
+  askLabel: askLabelOwn,
+  action,
+  className,
+}) {
+  const slot = useContext(TopBarSlot);
+  const defaults = useContext(BarContext);
+  if (slot === null) return null;
+  // What this screen did not pass, the shell's AskProvider said once.
+  const { allowance, allowanceLabel, allowanceUnit, allowancePeriod, onFind, findEvent, findLabel, findWord, askLabel } = resolveBar(
+    {
+      allowance: allowanceOwn,
+      allowanceLabel: allowanceLabelOwn,
+      allowanceUnit: allowanceUnitOwn,
+      allowancePeriod: allowancePeriodOwn,
+      onFind: onFindOwn,
+      findEvent: findEventOwn,
+      findLabel: findLabelOwn,
+      findWord: findWordOwn,
+      askLabel: askLabelOwn,
+    },
+    defaults,
+  );
+  const bar = (
+    <div data-top-bar className={cx("@container/bar flex h-10 min-w-0 items-center gap-1.5", slot === undefined && "px-2 sm:px-3", className)}>
+      {lead ? <span className="flex shrink-0 items-center">{lead}</span> : null}
+      <Crumb items={crumb} back={back} />
+      {note ? <span data-bar-piece="note" className={cx(SHOW.trailInline, "min-w-0 shrink-[4] truncate whitespace-nowrap text-muted-foreground")}>{note}</span> : null}
+      <span className="min-w-0 flex-1" />
+      {extra ? <span data-bar-piece="extra" className={cx(SHOW.extra, "shrink-0 items-center gap-1.5")}>{extra}</span> : null}
+      <AllowanceBar allowance={allowance} unit={allowanceUnit} period={allowancePeriod} label={allowanceLabel} />
+      {find ? <FindButton onFind={onFind} event={findEvent} label={findLabel} word={findWord} className="shrink-0" /> : null}
+      <AskButton dock={dock} onAsk={onAsk} asking={asking} label={askLabel} className="shrink-0" />
+      {action ? <span data-bar-piece="action" className="flex shrink-0 items-center">{action}</span> : null}
+    </div>
+  );
+  return slot === undefined ? bar : createPortal(bar, slot);
+}

package/registry/blocks/trigger-picker/README.md

@@ -0,0 +1,98 @@
+# TriggerPicker
+
+What starts an automation, as a panel. Seven ways, and the platform says
+which of them it runs:
+
+- **By hand**: someone presses Run, or the agent runs it.
+- **On a schedule**: every day, every weekday, every week, every hour, or
+  another schedule written as a five-field cron, with a time of day (or the
+  minute past the hour, or the weekday) and a sentence that says it back:
+  "Runs weekdays at 07:00, team time." **The team's time zone** is the
+  default, and it is the point: 07:00 stays 07:00 through daylight saving,
+  whoever is looking. A schedule the picker cannot read back stays the
+  custom cron it was.
+- **When an app sends an event**: a topic like `rows.imported`. A team
+  automation may name the app it hears. Events that carry a `key` run once
+  per item; events without one run at most once in five minutes.
+- **When an app action finishes**: one of the app's declared actions, done
+  by a person or by the app's agent. An action another automation ran does
+  not start it (that would loop); "after another automation" is for that.
+- **When a record is added or changed**: in the company brain, for the
+  kinds picked (none picked: every kind the owner can read), added and/or
+  changed. One run for each record, looked at once a minute. Changes the
+  app's own jobs make do not start it.
+- **When its web address is called**: the automation's own address, which
+  any system can post JSON to. The panel makes the secret, shows it once,
+  and replaces it on request (the old one stops at once). The sender signs
+  the body with it, or adds `?token=<secret>` to the address when it cannot
+  sign.
+- **When another automation finishes**: done, failed, or either. The
+  platform refuses a loop when the automation is saved.
+
+A connection's own events (a new mail, a new row in a sheet) are listed as
+**soon**, with what to use until then.
+
+```jsx
+import { TriggerPicker } from "../components/blocks/trigger-picker";   // a Makersclaw app
+import { TriggerPicker } from "@/components/makersclaw/blocks/trigger-picker";   // a shadcn project
+```
+
+`makersclaw add trigger-picker` lays `automation-model` with it. A client
+component. It is a panel (a head, a body): place it beside or over the
+canvas. `automation-editor` does that when the trigger card is pressed, and
+passes it what the hooks give it.
+
+## Props
+
+- `trigger`: `{ type: "manual" }`, `{ type: "schedule", cron, tz }`,
+  `{ type: "event", topic, app? }`, `{ type: "action", action, app? }`,
+  `{ type: "record", kinds?, ops?, app? }`, `{ type: "webhook" }` or
+  `{ type: "automation", key, when }` (`tz` is `"team"` or an IANA zone).
+- `onChange(trigger)`: a whole new trigger, ready to put into the
+  definition.
+- `catalog`: what the platform offers, `useAutomations().triggers`:
+  `{ choices: [{ type, label, hint, available, why? }], apps: [{ name,
+  actions: [{ name, description }], kinds, topics }], automations: [{ key,
+  name }] }`. Without it the panel offers by hand and a schedule and lists
+  `later` as "soon" (a platform from before the other triggers).
+- `ownedByApp`: the automation belongs to an app, so its actions, kinds and
+  topics are that app's (the first of `catalog.apps`); a team automation
+  picks an app.
+- `selfKey`: this automation's key, which it cannot follow.
+- `hook`: a webhook trigger's address once the automation is saved,
+  `useAutomation(id).hook`: `{ path, has_secret, rotated_at, last_received_at }`.
+- `onRotateHook()`: makes or replaces the secret; resolves `{ ok: true,
+  hook: { secret } }` (`useAutomation(id).rotateHook`).
+- `origin`: where the address lives (default: this page's origin).
+- `readOnly`: shown, not editable.
+- `onClose`: draws the close button.
+- `later`: without a `catalog`, the ways to start that are not built yet,
+  `[{ id, label, hint }]`.
+
+## Never
+
+- Never show a schedule in the viewer's time zone: say it in the
+  automation's.
+- Never offer a trigger the platform does not run without saying "soon".
+- Never keep the webhook's secret anywhere after it has been shown: the
+  platform does not send it again.
+
+## Example
+
+```jsx
+"use client";
+import { useState } from "react";
+import { useAutomation, useAutomations } from "../lib/hooks";
+import { TriggerPicker } from "../components/blocks/trigger-picker";
+
+export default function WhenItRuns({ id }) {
+  const { triggers } = useAutomations();
+  const { automation, definition, hook, rotateHook } = useAutomation(id);
+  const [trigger, setTrigger] = useState(definition?.trigger ?? { type: "manual" });
+  return (
+    <div className="max-w-sm overflow-hidden rounded-lg border border-border">
+      <TriggerPicker trigger={trigger} onChange={setTrigger} catalog={triggers} ownedByApp selfKey={automation?.key} hook={hook} onRotateHook={rotateHook} />
+    </div>
+  );
+}
+```

package/registry/blocks/trigger-picker/block.json

@@ -0,0 +1,38 @@
+{
+  "name": "trigger-picker",
+  "title": "TriggerPicker",
+  "description": "What starts an automation, as a panel: by hand, on a schedule in the team's time zone, when an app sends an event, when one of an app's actions finishes, when a record is added or changed, when the automation's own web address is called (its secret made and replaced here, shown once), or when another automation finishes. The platform says which of these it runs (the list door's triggers); a connection's own events are listed as \"soon\" with what to use meanwhile. The schedule is offered in the shapes people ask for (every day, every weekday, every week, every hour, another schedule as five-field cron) with a time of day, a weekday, the team's zone or another, and a sentence saying it back (\"Runs weekdays at 07:00, team time\").",
+  "useWhen": "An automation's trigger is edited in your own screen. automation-editor opens it when the trigger card is pressed; pass it the platform's triggers (useAutomations().triggers) so it offers what the platform runs.",
+  "tags": [
+    "automation",
+    "workflow",
+    "trigger",
+    "schedule",
+    "cron",
+    "time",
+    "when",
+    "every day",
+    "weekday",
+    "time zone",
+    "manual",
+    "n8n",
+    "make",
+    "event",
+    "webhook",
+    "record",
+    "action",
+    "web address",
+    "secret",
+    "follow"
+  ],
+  "exports": [
+    "TriggerPicker"
+  ],
+  "files": [
+    "index.js",
+    "trigger-picker.jsx"
+  ],
+  "requires": [
+    "automation-model"
+  ]
+}

package/registry/blocks/trigger-picker/demo.jsx

@@ -0,0 +1,59 @@
+"use client";
+
+// TriggerPicker — the gallery's and the smoke test's surface. Not
+// installed into apps. Switch between the ways to start (by hand, a
+// schedule, an event, an action, a record, a web address, after another
+// automation): the sentence under the title says it back. The second panel
+// is a platform from before the other triggers (by hand and a schedule,
+// the rest listed as soon); the third is read-only.
+import { useState } from "react";
+import { TriggerPicker } from "../components/blocks/trigger-picker";
+
+const CATALOG = {
+  choices: [
+    { type: "manual", label: "By hand", hint: "Someone presses Run, or the agent runs it.", available: true },
+    { type: "schedule", label: "On a schedule", hint: "Every day, every weekday, every hour.", available: true },
+    { type: "event", label: "When an app sends an event", hint: "An app announces something, like rows.imported.", available: true },
+    { type: "action", label: "When an app action finishes", hint: "A person or the app's agent ran one of its actions.", available: true },
+    { type: "record", label: "When a record is added or changed", hint: "A new person, a changed deal, in the company brain.", available: true },
+    { type: "webhook", label: "When its web address is called", hint: "Another system posts to a secret address of its own.", available: true },
+    { type: "automation", label: "When another automation finishes", hint: "One flow starts the next.", available: true },
+    { type: "connection", label: "When something happens in a connected account", hint: "A new mail, a new row in a sheet.", available: false, why: "Not offered yet. Use a schedule with a step that reads the account, or the web address trigger." },
+  ],
+  apps: [{ name: "CRM", actions: [{ name: "add_people", description: "Add people" }, { name: "suggest", description: "Suggest" }], kinds: ["contact", "deal", "company"], topics: ["rows.imported", "reply.received"] }],
+  automations: [{ key: "morning-read", name: "Morning read" }, { key: "weekly-look", name: "Weekly look back" }],
+};
+
+export default function TriggerPickerDemo() {
+  const [trigger, setTrigger] = useState({ type: "schedule", cron: "0 7 * * 1-5", tz: "team" });
+  const [hook, setHook] = useState({ path: "/hooks/automation/0b9f3c1a-5d2e-4c70-8a11-93e5f2a6b7d4", has_secret: false, rotated_at: null, last_received_at: null });
+  return (
+    <div className="grid gap-4 p-4 sm:grid-cols-2">
+      <div className="max-w-sm overflow-hidden rounded-lg border border-border">
+        <TriggerPicker
+          trigger={trigger}
+          onChange={setTrigger}
+          catalog={CATALOG}
+          ownedByApp
+          selfKey="reply-tidy"
+          hook={hook}
+          origin="https://app.makersclaw.com"
+          onRotateHook={async () => {
+            setHook((h) => ({ ...h, has_secret: true, rotated_at: new Date().toISOString() }));
+            return { ok: true, hook: { secret: "9f2c41a7e0b35d68c1a4f7203be96d85a1c0f3e7b2d49586" } };
+          }}
+        />
+      </div>
+      <div className="max-w-sm overflow-hidden rounded-lg border border-border">
+        <TriggerPicker trigger={{ type: "manual" }} onChange={() => {}} />
+      </div>
+      <div className="max-w-sm overflow-hidden rounded-lg border border-border">
+        <TriggerPicker trigger={{ type: "schedule", cron: "0 13,21 * * 1-5", tz: "Europe/Paris" }} onChange={() => {}} readOnly later={[]} />
+      </div>
+      <div className="max-w-sm overflow-hidden rounded-lg border border-border">
+        <TriggerPicker trigger={{ type: "record", kinds: ["contact"], ops: ["create"], app: "CRM" }} onChange={() => {}} catalog={CATALOG} selfKey="reply-tidy" readOnly />
+      </div>
+      <pre className="m-0 overflow-auto rounded-md bg-muted p-2 font-mono text-xs sm:col-span-2">{JSON.stringify(trigger)}</pre>
+    </div>
+  );
+}

package/registry/blocks/trigger-picker/index.js

@@ -0,0 +1,3 @@
+// The TriggerPicker block — `makersclaw add trigger-picker`. Fixed:
+// compose it through its props (README.md beside this file).
+export { TriggerPicker } from "./trigger-picker";