makersclaw 0.8.0 → 0.8.1

package/registry/blocks/activity-log/README.md

@@ -0,0 +1,112 @@
+# ActivityLog
+
+Who did what, to what, when. Newest first, one row per event on a
+vertical timeline: the author's face, "**Anna Lee** edited **deals**",
+the line's detail under it in muted words, a kind dot and the time.
+
+The agent is an author like a person, with its own mark (the diamond from
+`agent-marks`) where a face would be:
+
+- "Agent, for Anna Lee" — the agent wrote it on Anna's ask;
+- "Agent, on a run" — a scheduled job wrote it.
+
+With a record, it is that record's story. Grown in the CRM (0.7.0) as
+`activity-feed`; the premium registry owns that name, so here it is
+`activity-log`, and `ActivityFeed` stays exported as an alias.
+
+```jsx
+import { ActivityLog } from "../components/blocks/activity-log";   // a Makersclaw app ("./blocks/activity-log" from components/)
+import { ActivityLog } from "@/components/makersclaw/blocks/activity-log";   // a shadcn project
+```
+
+A client component. It requires `agent-marks` (laid with it). The
+Example is at the end.
+
+## Which hook feeds it
+
+```js
+const { rows, loading, unavailable } = useActivity({ row: deal.id });   // lib/hooks.js
+```
+
+`useActivity({ row, surface, since, limit, agent })` reads `GET
+_claw/data/activity`: the lines the data door wrote for every change it
+took, `{ id, at, action, surface, row_ref, detail, data, by }`. `row`
+keeps one record's lines; `agent: true` keeps only the agent's. `by` is
+`user:<email>`, `agent:<email>` (the agent, on that member's ask) or
+`agent:job` (a scheduled run). `action` is the door's word: `added`,
+`edited`, `moved`, `removed`, `confirmed`, `merged`, `linked`,
+`unlinked`, `listed`, `unlisted`.
+
+## Props
+
+- `rows` — `useActivity()`'s rows. The block words them (below).
+- `people` — `{ "anna@acme.com": "Anna Lee" }`: names for the emails in
+  `by`. Without a name, the email shows.
+- `formatTime(at)` — words for a line's time. Default "just now", "5 min
+  ago", "3 h ago", "yesterday", "12 Sep".
+- `describe(row)` — part of an item laid over what the block makes of a
+  row: an `href` to the record, an `object` name, a `tone`.
+- `items` — instead of `rows`: items you shaped yourself, `[{ id,
+  actorName, actorAvatar?, agent?, verb, object, objectHref?, detail?,
+  tone, time, timestamp?, href?, onClick? }]`. `agent: true` draws the
+  agent's mark. `tone` is `success` · `info` · `warning` · `danger` ·
+  `neutral`.
+- `title` — a head; draws the log inside a `Card`. `subtitle` — a muted
+  line under it.
+- `subject` — a pill after the title naming whose story this is.
+- `loading` — skeleton rows instead of items.
+- `onItemClick(item)` — every row without its own `href`, `onClick` or
+  `objectHref` becomes a button calling it.
+- `emptyTitle` — default "No activity yet". `emptyBody` — a muted line
+  under it.
+- `label` — the list's name for a screen reader. Default the title, or
+  "Activity".
+- `leading` — `avatar` (default) · `icon`: one subject's journey, each
+  row its kind's icon in a tinted circle, a title with the date, no
+  author column.
+- `kinds` — `{ [kind]: { icon, tone } }` for `leading="icon"`; a row's
+  kind is its `action`.
+- `className` — layout around it. Never colour.
+
+`activityItems(rows, { people, formatTime, describe })`,
+`activityAuthor(by, people)` and `activityTime(at)` are exported for a
+screen that words lines itself.
+
+## Who may do what
+
+Any member who can open the app reads every line. That is why a line
+never holds a field's value: only the action, the surface, the record's
+id and one sentence of detail. The log has no controls of its own.
+
+## Never
+
+- Never put a field's value in a line's `detail` for this log to show.
+- Never draw the agent with a person's avatar, or a person with the
+  agent's mark.
+- Never use it for one ask's changes with an Undo: that is
+  `agent-changes`.
+
+## Example
+
+A record's story, beside the record.
+
+```jsx
+"use client";
+import { useActivity } from "../lib/hooks";
+import { ActivityLog } from "../components/blocks/activity-log";
+
+export default function DealStory({ deal, people }) {
+  const { rows, loading, unavailable } = useActivity({ row: deal.id });
+  if (unavailable) return <p className="text-sm text-muted-foreground">The story is not connected yet.</p>;
+  return (
+    <ActivityLog
+      title="Story"
+      subject={deal.name}
+      rows={rows}
+      people={people}
+      loading={loading}
+      emptyBody="Changes to this deal show here, by people and by the agent."
+    />
+  );
+}
+```

package/registry/blocks/activity-log/activity-log.jsx

@@ -0,0 +1,351 @@
+"use client";
+
+import { Avatar, Badge, Button, Card, Empty, Icon, Item, ItemGroup, Skeleton, StatusDot, cx } from "../../ui";
+import { AgentMark } from "../agent-marks";
+
+// ActivityLog — who did what, to what, when; newest first (the app kit,
+// D15; grown as the CRM's activity-feed, 0.7.0). One row per event: the
+// author's face on a vertical timeline line, "<b>Actor</b> verb
+// <b>Object</b>" with a muted detail under it, and a kind dot and the time
+// on the right. The agent is an author like a person, with its own mark:
+// "Agent, for anna@acme.com", "Agent, on a run".
+//
+// Two ways in. `items` are rows you shaped yourself (the caller formats
+// the time and picks the tone). `rows` are the app's activity lines as
+// useActivity() returns them (lib/hooks.js) — { id, at, action, surface,
+// row_ref, detail, by } — and the block words them: `by` user:<email> is
+// the person (named through `people`), agent:<email> is "Agent, for
+// <them>", agent:job is "Agent, on a run".
+//
+// leading="icon" is one subject's journey instead: each row leads with its
+// kind's icon in a circle tinted by its tone, a title with the short date
+// beside it, one muted line under it, no actor and no trailing column; the
+// header can name the subject in a pill.
+
+const TONES = ["success", "info", "warning", "danger", "neutral"];
+const LOADING_ROWS = 4;
+
+// The circle behind a kind's icon: a wash of its tone, the glyph in it.
+const DISC = {
+  success: "bg-success/15 text-success",
+  info: "bg-info/15 text-info",
+  warning: "bg-warning/15 text-warning",
+  danger: "bg-destructive/15 text-destructive",
+  primary: "bg-primary/15 text-primary",
+  neutral: "bg-muted text-muted-foreground",
+};
+
+// The icon and tone of a journey row: its own, else its kind's.
+function kindOf(item, kinds) {
+  const k = (item.kind != null && kinds?.[item.kind]) || {};
+  const tone = item.tone ?? k.tone;
+  return { icon: item.icon ?? k.icon ?? "circle", tone: DISC[tone] ? tone : "neutral" };
+}
+
+/** The timeline segment behind the avatar column: from the row's middle
+ *  down on the first row, top to middle on the last, full height between.
+ *  left-7 is the avatar's centre (Item's px-3 + half of a 32px avatar). */
+function Line({ first, last, icon }) {
+  if (first && last) return null;
+  if (icon)
+    // The journey's circles sit on the title line, not the row's middle:
+    // their centre is 26px down (py-3.5 + half of a 24px circle), left-6.
+    return (
+      <span
+        aria-hidden="true"
+        className={cx("absolute left-6 w-px -translate-x-1/2 bg-border", first ? "top-[26px]" : "top-0", last ? "h-[26px]" : "bottom-0")}
+      />
+    );
+  return (
+    <span
+      aria-hidden="true"
+      className={cx("absolute left-7 w-px -translate-x-1/2 bg-border", first ? "top-1/2" : "top-0", last ? "bottom-1/2" : "bottom-0")}
+    />
+  );
+}
+
+function Disc({ icon, tone }) {
+  return (
+    // raw: an icon in a circle washed with a status tone; Item's own `icon`
+    // square is always muted, and no kit part tints a glyph's backdrop.
+    <span aria-hidden="true" className={cx("relative flex size-6 shrink-0 items-center justify-center rounded-full", DISC[tone])}>
+      <Icon name={icon} size={13} />
+    </span>
+  );
+}
+
+function JourneyRow({ item, first, last, kinds, onItemClick }) {
+  const { icon, tone } = kindOf(item, kinds);
+  const onClick = item.onClick ?? (onItemClick && !item.href ? () => onItemClick(item) : undefined);
+  return (
+    // raw: a positioned wrapper so the timeline line runs behind the
+    // circles across the whole row; no kit part draws a timeline.
+    <div className="relative">
+      <Line first={first} last={last} icon />
+      <Item
+        className="py-3.5 rounded-none [&]:items-start"
+        media={<Disc icon={icon} tone={tone} />}
+        title={
+          <>
+            {item.title ?? item.object}
+            {item.time ? (
+              <>
+                {" "}
+                <time dateTime={item.timestamp} title={item.timestamp || undefined} data-nums className="ml-1 text-xs font-normal text-muted-foreground">
+                  {item.time}
+                </time>
+              </>
+            ) : null}
+          </>
+        }
+        description={item.detail || undefined}
+        href={item.href}
+        onClick={item.href ? undefined : onClick}
+      />
+    </div>
+  );
+}
+
+function Sentence({ item, linkObject }) {
+  return (
+    <>
+      <span>{item.actorName}</span> <span className="font-normal text-muted-foreground">{item.verb}</span>{" "}
+      {linkObject ? (
+        // The kit's inline text link, in the sentence's own size and weight;
+        // a row that is not a target of its own can still link its object.
+        <Button variant="link" size="inherit" href={item.objectHref} className="relative z-10">
+          {item.object}
+        </Button>
+      ) : (
+        <span>{item.object}</span>
+      )}
+    </>
+  );
+}
+
+function Row({ item, first, last, onItemClick }) {
+  const tone = TONES.includes(item.tone) ? item.tone : "neutral";
+  const onClick = item.onClick ?? (onItemClick && !item.href && !item.objectHref ? () => onItemClick(item) : undefined);
+  const linkObject = Boolean(item.objectHref) && !item.href && !onClick;
+  return (
+    // raw: a positioned wrapper so the timeline line can run behind the
+    // Item's avatar across the whole row; no kit part draws a timeline.
+    <div className="relative">
+      <Line first={first} last={last} />
+      <Item
+        size="default"
+        className="py-3.5 rounded-none hover:bg-muted/50"
+        media={
+          item.agent ? (
+            // raw: the agent's mark in the avatar's circle, so the timeline
+            // line runs behind it like a face.
+            <span className="relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted">
+              <AgentMark size="md" />
+            </span>
+          ) : (
+            <Avatar name={item.actorName} src={item.actorAvatar} size="sm" />
+          )
+        }
+        title={<Sentence item={item} linkObject={linkObject} />}
+        description={item.detail || undefined}
+        href={item.href}
+        onClick={item.href ? undefined : onClick}
+        meta={
+          <span className="inline-flex items-center gap-2 whitespace-nowrap text-sm">
+            <StatusDot tone={tone} size="sm" />
+            <time dateTime={item.timestamp} title={item.timestamp || undefined}>
+              {item.time}
+            </time>
+          </span>
+        }
+      />
+    </div>
+  );
+}
+
+function SkeletonRow({ first, last, icon }) {
+  return (
+    <div className="relative">
+      <Line first={first} last={last} icon={icon} />
+      <Item
+        className={cx("py-3.5 rounded-none", icon && "[&]:items-start")}
+        media={<Skeleton shape="circle" className={icon ? "size-6" : "size-8"} />}
+        title={<Skeleton className="w-48 max-w-full" />}
+        description={<Skeleton className="mt-1.5 w-32 max-w-full" />}
+        meta={icon ? undefined : <Skeleton className="w-16" />}
+      />
+    </div>
+  );
+}
+
+const ISO = /^\d{4}-\d{2}-\d{2}T/;
+
+/** "just now", "5 min ago", "3 h ago", "yesterday", "12 Sep". */
+export function activityTime(at, now = new Date()) {
+  const d = at instanceof Date ? at : typeof at === "string" && (ISO.test(at) || /^\d{4}-\d{2}-\d{2}/.test(at)) ? new Date(at) : null;
+  if (!d || Number.isNaN(d.getTime())) return at == null ? "" : String(at);
+  const s = Math.round((now.getTime() - d.getTime()) / 1000);
+  if (s < 60) return "just now";
+  if (s < 3600) return `${Math.floor(s / 60)} min ago`;
+  if (s < 86400 && d.toDateString() === now.toDateString()) return `${Math.floor(s / 3600)} h ago`;
+  const y = new Date(now);
+  y.setDate(y.getDate() - 1);
+  if (d.toDateString() === y.toDateString()) return "yesterday";
+  return d.toLocaleDateString("en-GB", { day: "numeric", month: "short", ...(d.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }) });
+}
+
+/** A line's tone from its action word (the door's: added, edited, …). */
+const ACTION_TONE = { added: "success", created: "success", confirmed: "success", linked: "info", listed: "info", edited: "info", moved: "info", merged: "warning", removed: "danger", erased: "danger", unlinked: "neutral", unlisted: "neutral" };
+
+/** Who a `by` names, in words: { name, agent, email }. */
+export function activityAuthor(by, people) {
+  const raw = String(by ?? "");
+  const named = (email) => (email && people && (people[email] ?? people[email.toLowerCase()])) || email;
+  if (raw === "agent:job" || raw === "agent:run") return { name: "Agent, on a run", agent: true };
+  if (raw.startsWith("agent:")) {
+    const email = raw.slice(6);
+    return { name: email ? `Agent, for ${named(email)}` : "Agent", agent: true, email };
+  }
+  if (raw.startsWith("user:")) {
+    const who = raw.slice(5);
+    if (!who || who === "unknown") return { name: "Someone", agent: false };
+    return { name: named(who), agent: false, email: who.includes("@") ? who : undefined };
+  }
+  return { name: raw || "Someone", agent: false };
+}
+
+/**
+ * The app's activity lines (useActivity's `rows`) as items:
+ *
+ *   rows        [{ id, at, action, surface, row_ref, detail, data, by }]
+ *   people      { "anna@acme.com": "Anna Lee" }: names for emails
+ *   formatTime  (at) → words; default activityTime ("5 min ago")
+ *   describe    (row) → part of an item, laid over what this makes
+ *               (an href, an object's name, a tone)
+ */
+export function activityItems(rows, { people, formatTime = activityTime, describe } = {}) {
+  return (rows ?? []).filter(Boolean).map((row, i) => {
+    const who = activityAuthor(row.by, people);
+    const item = {
+      id: row.id ?? `${row.at ?? ""}-${i}`,
+      actorName: who.name,
+      agent: who.agent,
+      verb: row.action ?? "changed",
+      object: row.surface || "a record",
+      detail: row.detail || undefined,
+      tone: ACTION_TONE[row.action] ?? "neutral",
+      kind: row.action,
+      // A journey row's title is the sentence; its detail line, the detail.
+      title: [who.name, row.action ?? "changed", row.surface].filter(Boolean).join(" "),
+      time: formatTime(row.at),
+      timestamp: typeof row.at === "string" ? row.at : row.at instanceof Date ? row.at.toISOString() : undefined,
+    };
+    return describe ? { ...item, ...describe(row) } : item;
+  });
+}
+
+/**
+ *   items        [{ id, actorName, actorAvatar?, agent?, verb, object,
+ *                  objectHref?, detail?, tone, time, timestamp?, href?,
+ *                  onClick? }]; agent: true draws the agent's mark
+ *   rows         instead of items: useActivity()'s rows, worded by
+ *                activityItems (with `people`, `formatTime`, `describe`)
+ *   title        optional header, draws the feed inside a Card
+ *   subtitle     a muted line under the title (drawn only with a title)
+ *   loading      skeleton rows instead of items
+ *   onItemClick  (item) → void; every row without its own href, onClick
+ *                or objectHref becomes a button calling it
+ *   emptyTitle   default "No activity yet"
+ *   emptyBody    a muted line under it
+ *   label        the list's name for a screen reader; default title or "Activity"
+ *   leading      avatar (default: the actor's face, the sentence, a dot and
+ *                the time on the right) · icon (a journey: the kind's icon
+ *                in a tinted circle, title + date, no rules between rows)
+ *   kinds        { [kind]: { icon, tone } } — leading="icon" looks up a
+ *                row's `kind` here; a row's own `icon`/`tone` win
+ *   subject      a pill after the title naming whose history this is
+ */
+export function ActivityLog({
+  items,
+  rows,
+  people,
+  formatTime,
+  describe,
+  title,
+  subtitle,
+  loading = false,
+  onItemClick,
+  emptyTitle = "No activity yet",
+  emptyBody,
+  label,
+  leading = "avatar",
+  kinds,
+  subject,
+  className,
+}) {
+  const journey = leading === "icon";
+  const list = (items ?? (rows ? activityItems(rows, { people, formatTime, describe }) : [])).filter(Boolean);
+  const named = label ?? (typeof title === "string" ? title : "Activity");
+  const framed = Boolean(title);
+
+  let body;
+  if (loading) {
+    body = (
+      <ItemGroup variant={framed ? "plain" : "outline"} aria-label={`${named}, loading`}>
+        {Array.from({ length: LOADING_ROWS }, (_, i) => (
+          <SkeletonRow key={i} first={i === 0} last={i === LOADING_ROWS - 1} icon={journey} />
+        ))}
+      </ItemGroup>
+    );
+  } else if (list.length === 0) {
+    body = <Empty icon="clock" title={emptyTitle} body={emptyBody} className={framed ? "m-4" : undefined} />;
+  } else {
+    body = (
+      <ItemGroup
+        variant={framed ? "plain" : "outline"}
+        aria-label={named}
+        // A journey is one line of events, no rules between them.
+        className={journey ? "py-1 [&>li]:border-t-0" : undefined}
+      >
+        {list.map((item, i) =>
+          journey ? (
+            <JourneyRow key={item.id ?? i} item={item} first={i === 0} last={i === list.length - 1} kinds={kinds} onItemClick={onItemClick} />
+          ) : (
+            <Row key={item.id ?? i} item={item} first={i === 0} last={i === list.length - 1} onItemClick={onItemClick} />
+          ),
+        )}
+      </ItemGroup>
+    );
+  }
+
+  if (!framed) return <div className={className}>{body}</div>;
+  return (
+    <Card
+      title={
+        subject ? (
+          <span className="flex flex-wrap items-center gap-x-2 gap-y-1">
+            <span>{title}</span>
+            {typeof subject === "string" ? (
+              <Badge variant="soft" className="font-normal">
+                {subject}
+              </Badge>
+            ) : (
+              subject
+            )}
+          </span>
+        ) : (
+          title
+        )
+      }
+      description={subtitle} className={cx("overflow-hidden", className)}>
+      {/* Edge to edge under the header, as the rows' rules are. */}
+      <div aria-busy={loading || undefined} className="-mx-4 -mb-4 border-t border-border">
+        {body}
+      </div>
+    </Card>
+  );
+}
+
+/** The CRM's name for it (0.7.0), kept so a screen written against the
+ *  CRM's activity-feed moves without a rename. */
+export const ActivityFeed = ActivityLog;

package/registry/blocks/activity-log/block.json

@@ -0,0 +1,33 @@
+{
+  "name": "activity-log",
+  "title": "ActivityLog",
+  "description": "Who did what, to what, when, newest first: one row per event on a vertical timeline, \"Anna Lee edited deals\" with the line's detail under it, a kind dot and the time. The agent is an author like a person, with its own mark: \"Agent, for anna@acme.com\", \"Agent, on a run\". It takes the app's activity lines as useActivity() returns them (lib/hooks.js; with a row, one record's timeline) and words them itself, or rows you shaped. leading=\"icon\" draws one subject's journey instead.",
+  "useWhen": "A record's story (what happened to this deal, and who did it), an app's recent changes on a home screen, a review of what the agent did this week next to what people did. Not for one job's own steps (job-panel), one ask's changes with an undo (agent-changes), or a sortable audit table (data-table).",
+  "tags": [
+    "activity",
+    "timeline",
+    "history",
+    "audit",
+    "log",
+    "feed",
+    "events",
+    "who did what",
+    "record story",
+    "recent",
+    "changes"
+  ],
+  "exports": [
+    "ActivityLog",
+    "ActivityFeed",
+    "activityItems",
+    "activityAuthor",
+    "activityTime"
+  ],
+  "files": [
+    "index.js",
+    "activity-log.jsx"
+  ],
+  "requires": [
+    "agent-marks"
+  ]
+}

package/registry/blocks/activity-log/demo.jsx

@@ -0,0 +1,48 @@
+"use client";
+
+// ActivityLog over fake lines shaped as useActivity() returns them, and in
+// its other states — the gallery's and the smoke test's surface. Not
+// installed into apps.
+import { ActivityLog } from "../components/blocks/activity-log";
+
+const ago = (min) => new Date(Date.now() - min * 60 * 1000).toISOString();
+
+const ROWS = [
+  { id: "a1", at: ago(2), action: "moved", surface: "deals", row_ref: "d1", detail: "Pinewood to Won", by: "agent:anna@acme.com" },
+  { id: "a2", at: ago(14), action: "edited", surface: "people", row_ref: "p4", detail: "Sofia Reyes: job title", by: "user:owen@acme.com" },
+  { id: "a3", at: ago(95), action: "added", surface: "deals", row_ref: "d9", detail: "Crumb & Co: 22 shops", by: "agent:job" },
+  { id: "a4", at: ago(60 * 26), action: "removed", surface: "notes", row_ref: "n2", detail: null, by: "user:unknown" },
+  {
+    id: "a5",
+    at: ago(60 * 24 * 6),
+    action: "merged",
+    surface: "companies",
+    row_ref: "c3",
+    detail: "Harborview Hospitality Group and Harborview Hospitality Group Ltd (a duplicate found in last week's import)",
+    by: "user:priya.nair@acme.com",
+  },
+];
+
+const PEOPLE = { "anna@acme.com": "Anna Lee", "owen@acme.com": "Owen Park" };
+
+export default function ActivityLogDemo() {
+  return (
+    <div className="grid gap-6 p-6">
+      <ActivityLog title="Story" subject="Pinewood" rows={ROWS} people={PEOPLE} />
+      <div className="grid gap-4 [grid-template-columns:repeat(auto-fit,minmax(min(100%,20rem),1fr))]">
+        <ActivityLog title="Loading" loading />
+        <ActivityLog title="Empty" rows={[]} emptyBody="Changes show here, by people and by the agent." />
+        <ActivityLog
+          title="A journey"
+          leading="icon"
+          rows={ROWS.slice(0, 3)}
+          people={PEOPLE}
+          kinds={{ moved: { icon: "arrow-right", tone: "info" }, edited: { icon: "pencil", tone: "neutral" }, added: { icon: "plus", tone: "success" } }}
+        />
+      </div>
+      <div className="w-80 max-w-full">
+        <ActivityLog rows={ROWS} people={PEOPLE} label="Narrow" />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/activity-log/index.js

@@ -0,0 +1,4 @@
+// The ActivityLog block — `makersclaw add activity-log`. Fixed: compose it
+// through its props (README.md beside this file). ActivityFeed is the
+// CRM's name for the same block.
+export { ActivityLog, ActivityFeed, activityItems, activityAuthor, activityTime } from "./activity-log";

package/registry/blocks/agent-changes/README.md

@@ -0,0 +1,94 @@
+# AgentChanges
+
+The receipt of one ask. After the agent changes many things at once, the
+member sees:
+
+- what it did, in one line: "Sorted 46 stickies into 6 groups";
+- who asked and when: "By the agent, on Priya's ask · 11:20";
+- each change, folded after five ("Show 41 more");
+- **Undo this ask**, which takes all of them back in one press.
+
+Undone, the receipt stays, struck through, and says so in words.
+
+The block draws; **the app does the undo**. Only the app knows what an
+ask drew (the whiteboard's stickies, the map's branches, the plan's
+bars), so Undo calls your own declared undo action.
+
+```jsx
+import { AgentChanges } from "../components/blocks/agent-changes";   // a Makersclaw app ("./blocks/agent-changes" from components/)
+import { AgentChanges } from "@/components/makersclaw/blocks/agent-changes";   // a shadcn project
+```
+
+A client component. It requires `agent-marks` (laid with it).
+
+## Which hook feeds it
+
+The changes come from what the ask reported, or from the activity lines
+the agent wrote since it started:
+
+```js
+const { rows } = useActivity({ agent: true, since: ask.started_at });   // lib/hooks.js
+const changes = rows.map((r) => ({ id: r.id, label: r.detail ?? `${r.action} ${r.surface}` }));
+```
+
+Undo is the app's own declared action (`runAction`, lib/actions): the
+same write path the agent uses, with the same door rules.
+
+## Props
+
+- `summary` — what the ask did, one line, in the app's words.
+- `changes` — `[{ id?, label, detail? }]`, each change. Folded after five.
+- `by` — who and when: `Byline`'s props (`{ by, ask, at }`, e.g. `{ ask:
+  "Priya", at: "11:20" }`), or your own words.
+- `onUndo()` — async, answers `{ ok: true }` or `{ ok: false, error }` (a
+  throw counts as failed). The button spins while it runs; a failure says
+  why under it. Without `onUndo` there is no Undo.
+- `undone` — `true` when your data says the ask was undone already.
+- `undoLabel` — default "Undo this ask".
+- `undoneWords` — default "Undone. Everything this ask changed is back as
+  it was."
+- `label` — the region's name for a reader. Default the summary.
+- `className` — layout around it. Never colour.
+
+## Who may do what
+
+Give `onUndo` to the member who asked, and to an owner or admin; your
+declared undo action refuses anyone else anyway. Everyone else sees the
+receipt without the button.
+
+## Never
+
+- Never undo by deleting what looks new: undo exactly what this ask
+  wrote, through your declared action.
+- Never hide the receipt after an undo; it stays, struck, so the member
+  knows what happened.
+- Never use it for proposals the member has not kept yet: that is
+  `suggestion`.
+
+## Example
+
+The receipt under a whiteboard after the agent sorted it.
+
+```jsx
+"use client";
+import { runAction } from "../lib/actions";
+import { AgentChanges } from "../components/blocks/agent-changes";
+
+export function SortReceipt({ ask, moves, reload }) {
+  return (
+    <AgentChanges
+      summary={`Sorted ${moves.length} stickies into ${ask.groups} groups`}
+      by={{ ask: ask.asked_by_name, at: ask.ended_at }}
+      changes={moves.map((m) => ({ id: m.id, label: m.sticky, detail: `to ${m.group}` }))}
+      undone={ask.undone}
+      onUndo={async () => {
+        const r = await runAction({ name: "undo_ask", args: { ask: ask.id } });
+        if (r.ok) reload();
+        return r;
+      }}
+    />
+  );
+}
+```
+
+In a server-mode app the same calls are `loadRows` in a server surface and the Server Actions of `lib/actions`.