makersclaw 0.7.0 → 0.8.1

package/registry/blocks/margin-notes/margin-notes.jsx

@@ -0,0 +1,465 @@
+"use client";
+
+// Passages of text with notes in the margin, level with their words. Each
+// passage is a row: the words on one side, the notes about them on the
+// other (stacked under the words when the container is narrow). A note says
+// where the words came from (source), that they need a look (flag), that
+// they were cut and why (cut), or what someone thought (comment); an app
+// can add kinds. The words a note is about are marked in the passage, and
+// the selected note and its passage are linked: click either, or press J
+// and K to walk the notes that still need a person.
+//
+// Props in, callbacks out: the block never reads or writes data. A press on
+// a note's button calls onAction(note, actionId); the app does the work and
+// hands back changed notes. README.md beside this file is the contract.
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Badge, Button, Empty, Icon, Kbd, Notice, Skeleton, cx } from "../../ui";
+import { AgentMark } from "../agent-marks";
+import { actionsOf, arrangeNotes, countNotes, countWords, cycleNote, inlineMarks, isSettled, noteLook, resolveKinds, walkNext } from "./margin-model";
+
+// Literal class names, so Tailwind sees every one of them.
+const GRID = {
+  right: {
+    sm: "@2xl:grid-cols-[minmax(0,1fr)_15rem]",
+    md: "@2xl:grid-cols-[minmax(0,1fr)_18rem]",
+    lg: "@2xl:grid-cols-[minmax(0,1fr)_22rem]",
+  },
+  left: {
+    sm: "@2xl:grid-cols-[15rem_minmax(0,1fr)]",
+    md: "@2xl:grid-cols-[18rem_minmax(0,1fr)]",
+    lg: "@2xl:grid-cols-[22rem_minmax(0,1fr)]",
+  },
+};
+
+const TEXT = { sm: "text-sm leading-relaxed", md: "text-base leading-relaxed", lg: "text-lg leading-relaxed" };
+
+// The coloured bar down a note's inline-start edge.
+const BAR = {
+  neutral: "bg-muted-foreground",
+  primary: "bg-primary",
+  info: "bg-info",
+  success: "bg-success",
+  warning: "bg-warning",
+  danger: "bg-destructive",
+};
+const BAR_HUE = { 1: "bg-chart-1", 2: "bg-chart-2", 3: "bg-chart-3", 4: "bg-chart-4", 5: "bg-chart-5" };
+
+const DECO = {
+  neutral: "decoration-muted-foreground",
+  primary: "decoration-primary",
+  info: "decoration-info",
+  success: "decoration-success",
+  warning: "decoration-warning",
+  danger: "decoration-destructive",
+};
+const DECO_HUE = { 1: "decoration-chart-1", 2: "decoration-chart-2", 3: "decoration-chart-3", 4: "decoration-chart-4", 5: "decoration-chart-5" };
+
+const WASH = {
+  neutral: "bg-muted",
+  primary: "bg-primary/15",
+  info: "bg-info/15",
+  success: "bg-success/15",
+  warning: "bg-warning/15",
+  danger: "bg-destructive/15",
+};
+const WASH_HUE = { 1: "bg-chart-1/15", 2: "bg-chart-2/15", 3: "bg-chart-3/15", 4: "bg-chart-4/15", 5: "bg-chart-5/15" };
+
+const deco = (look) => (look.hue ? DECO_HUE[look.hue] : DECO[look.tone]);
+const wash = (look) => (look.hue ? WASH_HUE[look.hue] : WASH[look.tone]);
+
+const domId = (root, kind, id) => `${root}-${kind}-${String(id).replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+
+const reducedMotion = () => typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+
+/** Words typed into, or a key meant for something else: J and K are left alone. */
+function isTyping(el) {
+  if (!el || el.nodeType !== 1) return false;
+  return Boolean(el.closest?.("input, textarea, select, [contenteditable=''], [contenteditable='true']"));
+}
+
+/** The words of a passage, with the marks the notes make on them. */
+function Words({ passage, notes, kinds, selectedId, rootId, as: Tag = "p" }) {
+  const looks = useMemo(() => new Map(notes.map((n) => [n.id, noteLook(n, kinds)])), [notes, kinds]);
+  const { segments } = useMemo(() => inlineMarks(passage.text, notes, (n) => looks.get(n.id)?.mark ?? "none"), [passage.text, notes, looks]);
+  if (passage.node != null) {
+    const struck = notes.find((n) => !isSettled(n) && looks.get(n.id)?.mark === "strike");
+    const look = struck ? looks.get(struck.id) : null;
+    return <div className={cx("min-w-0 break-words", look && cx("text-muted-foreground line-through decoration-2", deco(look)))}>{passage.node}</div>;
+  }
+  return (
+    <Tag className={cx("m-0 min-w-0 break-words", Tag !== "p" && "text-[1.05em] font-semibold leading-snug")}>
+      {segments.map((seg, i) => {
+        if (!seg.ids.length) return <span key={i}>{seg.text}</span>;
+        const id = seg.ids.includes(selectedId) ? selectedId : seg.ids[0];
+        const look = looks.get(id);
+        const on = seg.ids.includes(selectedId);
+        const common = { "data-note": id, "data-selected": on ? "" : undefined, "aria-describedby": domId(rootId, "note", id) };
+        if (look.mark === "strike")
+          return (
+            <del key={i} {...common} className={cx("rounded-sm text-muted-foreground line-through decoration-2", deco(look), on && wash(look))}>
+              <span className="sr-only">{look.label}: </span>
+              {seg.text}
+            </del>
+          );
+        return (
+          <mark
+            key={i}
+            {...common}
+            className={cx(
+              "rounded-sm text-inherit",
+              look.mark === "highlight" || on ? wash(look) : "bg-transparent",
+              look.mark === "underline" && "underline decoration-dotted decoration-2 underline-offset-4",
+              look.mark === "wavy" && "underline decoration-wavy decoration-1 underline-offset-4",
+              look.mark !== "highlight" && deco(look),
+            )}
+          >
+            <span className="sr-only">{look.label}: </span>
+            {seg.text}
+          </mark>
+        );
+      })}
+    </Tag>
+  );
+}
+
+/** One note. */
+function Note({ note, kinds, selected, busy, error, readOnly, canAct, onSelect, onPress, rootId, cardRef, quoteShown }) {
+  const look = noteLook(note, kinds);
+  const settled = isSettled(note);
+  const actions = canAct ? actionsOf(note, kinds, { readOnly }) : [];
+  const agent = note.by === "agent" || note.by?.agent === true;
+  const byName = typeof note.by === "string" ? (note.by === "agent" ? "" : note.by) : (note.by?.name ?? "");
+  const showReopen = settled && canAct && !readOnly && look.reopen;
+
+  return (
+    <article
+      ref={cardRef}
+      id={domId(rootId, "note", note.id)}
+      tabIndex={-1}
+      data-note={note.id}
+      data-kind={note.kind}
+      data-selected={selected ? "" : undefined}
+      aria-current={selected ? "true" : undefined}
+      aria-label={note.title && note.title !== look.label ? `${look.label}: ${note.title}` : look.label}
+      onClick={() => onSelect(note.id)}
+      className={cx(
+        "relative grid min-w-0 gap-1.5 overflow-hidden rounded-lg border border-border py-3 pe-3 ps-4 text-sm text-card-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        selected && "ring-2 ring-ring",
+        settled ? "bg-muted" : "bg-card",
+      )}
+    >
+      <span aria-hidden="true" className={cx("absolute inset-y-0 start-0 w-1", look.hue ? BAR_HUE[look.hue] : BAR[look.tone], settled && "opacity-40")} />
+      {settled ? (
+        <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
+          <Icon name="check" size={14} className="shrink-0 text-success" />
+          <span className="text-[13px] font-medium">{note.answer || "Settled"}</span>
+          {note.at ? <span className="text-xs text-muted-foreground">{note.at}</span> : null}
+          {showReopen ? (
+            <Button size="sm" variant="link" tone="muted" loading={busy === "reopen"} aria-label={`${look.reopen.label ?? "Reopen"}: ${look.label}`} onClick={() => onPress(note, "reopen")}>
+              {look.reopen.label ?? "Reopen"}
+            </Button>
+          ) : null}
+        </div>
+      ) : (
+        <>
+          <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
+            <Badge variant="soft" tone={look.hue ? undefined : look.tone} hue={look.hue ?? undefined} className="gap-1">
+              <Icon name={look.icon} size={12} aria-hidden="true" />
+              {look.label}
+            </Badge>
+            {agent ? <AgentMark label="Raised by the agent" /> : null}
+            {byName ? <span className="text-xs text-muted-foreground">{byName}</span> : null}
+            {note.at ? <span className="text-xs tabular-nums text-muted-foreground">{note.at}</span> : null}
+          </div>
+          {note.title ? <p className="m-0 font-medium">{note.title}</p> : null}
+          {note.meta ? <p className="m-0 text-xs text-muted-foreground">{note.meta}</p> : null}
+          {quoteShown && note.quote ? <p className="m-0 break-words text-[13px] italic text-muted-foreground">{`“${note.quote}”`}</p> : null}
+          {note.text ? <p className="m-0 break-words">{note.text}</p> : null}
+          {note.detail ? <p className="m-0 mt-0.5 break-words border-t border-dashed border-border pt-1.5 text-[13px] leading-snug text-muted-foreground">{note.detail}</p> : null}
+          {note.href ? (
+            <a href={note.href} target="_blank" rel="noreferrer" className="inline-flex items-center gap-1 justify-self-start rounded-sm text-xs font-medium text-primary underline-offset-4 hover:underline focus-visible:ring-2 focus-visible:ring-ring">
+              {note.hrefLabel || "Open the source"}
+              <Icon name="external" size={12} aria-hidden="true" />
+            </a>
+          ) : null}
+          {note.locked ? (
+            <p className="m-0 flex items-start gap-1.5 text-xs text-muted-foreground">
+              <Icon name="lock" size={12} className="mt-0.5 shrink-0" />
+              <span className="min-w-0">{note.locked}</span>
+            </p>
+          ) : null}
+          {actions.length ? (
+            <div className="flex flex-wrap items-center gap-1.5 pt-0.5">
+              {actions.map((a) => (
+                <Button
+                  key={a.id}
+                  size="sm"
+                  variant={a.variant || "secondary"}
+                  icon={a.icon}
+                  loading={busy === a.id}
+                  disabled={Boolean(busy) && busy !== a.id}
+                  aria-label={`${a.label}: ${look.label}${note.title ? `, ${note.title}` : ""}`}
+                  onClick={() => onPress(note, a.id)}
+                >
+                  {a.label}
+                </Button>
+              ))}
+            </div>
+          ) : null}
+        </>
+      )}
+      {error ? (
+        <p role="alert" className="m-0 text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+    </article>
+  );
+}
+
+/** Rows of grey bars where the passages and their notes will be. */
+function Loading({ cols }) {
+  return (
+    <div role="status" aria-label="Loading" aria-busy="true" className={cx("grid grid-cols-[minmax(0,1fr)] gap-x-6 gap-y-4", cols)}>
+      {[0, 1, 2].map((i) => (
+        <div key={i} className="contents">
+          <div className="grid min-w-0 gap-2 py-2">
+            <Skeleton className="w-full" />
+            <Skeleton className="w-11/12" />
+            <Skeleton className="w-2/3" />
+          </div>
+          <div className="grid min-w-0 content-start py-2">
+            <Skeleton shape="rect" className="h-16 w-full" />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ *   passages    [{ id, text | node, lead?, label?, level? }]: the words. `lead` is a
+ *               short figure before them (a time, a number); `label` a name above
+ *               (a speaker, a section); `level` 2 · 3 · 4 draws the text as a heading.
+ *   notes       [{ id, passage, kind, title?, meta?, text?, detail?, quote?, by?, at?,
+ *               href?, hrefLabel?, locked?, state?, answer?, actions?, tone?, hue?,
+ *               mark?, label? }]
+ *   selected / defaultSelected / onSelect(id | null)   the selected note
+ *   onAction(note, actionId)   async → { ok } | { ok: false, error }
+ *   kinds       changes to the built-in kinds, or new ones
+ *   side        right (default) · left: which side of the words the margin is on
+ *   marginWidth sm · md (default) · lg
+ *   marginTitle the margin's heading
+ *   showNotes   false hides the margin (default true)
+ *   textSize    sm · md (default) · lg
+ *   status      ready (default) · loading · failed, with `error` and onRetry
+ *   readOnly    notes to read: no buttons
+ *   keys        J and K walk the notes (default true)
+ */
+export function MarginNotes({
+  passages = [],
+  notes = [],
+  selected,
+  defaultSelected = null,
+  onSelect,
+  onAction,
+  kinds: kindChanges,
+  side = "right",
+  marginWidth = "md",
+  marginTitle,
+  showNotes = true,
+  textSize = "md",
+  status = "ready",
+  error,
+  onRetry,
+  readOnly = false,
+  keys = true,
+  noNotes = "Nothing in the margin.",
+  orphanTitle = "Not tied to a passage",
+  emptyTitle = "Nothing to read yet",
+  emptyBody,
+  countLabels,
+  label = "Passages with notes in the margin",
+  className,
+}) {
+  const rootId = useRef(`mn${Math.random().toString(36).slice(2, 8)}`).current;
+  const kinds = useMemo(() => resolveKinds(kindChanges), [kindChanges]);
+  const { byPassage, ordered, orphans } = useMemo(() => arrangeNotes(passages, notes), [passages, notes]);
+  const counts = useMemo(() => countNotes(notes), [notes]);
+
+  const [inner, setInner] = useState(defaultSelected);
+  const raw = selected === undefined ? inner : selected;
+  const current = raw != null && ordered.some((n) => n.id === raw) ? raw : null;
+  const position = current == null ? 0 : ordered.findIndex((n) => n.id === current) + 1;
+
+  const [busy, setBusy] = useState({});
+  const [errors, setErrors] = useState({});
+  const cards = useRef(new Map());
+  const rows = useRef(new Map());
+  const frame = useRef(0);
+  useEffect(() => () => cancelAnimationFrame(frame.current), []);
+
+  const choose = (id, bring = false) => {
+    if (selected === undefined) setInner(id);
+    onSelect?.(id);
+    if (bring && id != null) {
+      cancelAnimationFrame(frame.current);
+      frame.current = requestAnimationFrame(() => {
+        cards.current.get(id)?.focus({ preventScroll: true });
+        (rows.current.get(ordered.find((n) => n.id === id)?.passage) ?? cards.current.get(id))?.scrollIntoView({ block: "nearest", behavior: reducedMotion() ? "auto" : "smooth" });
+      });
+    }
+  };
+
+  async function press(note, actionId) {
+    if (!onAction) return;
+    const key = note.id;
+    if (busy[key]) return;
+    setBusy((b) => ({ ...b, [key]: actionId }));
+    setErrors((e) => ({ ...e, [key]: null }));
+    let r;
+    try {
+      r = await onAction(note, actionId);
+    } catch (e) {
+      r = { ok: false, error: e?.message ?? String(e) };
+    }
+    setBusy((b) => ({ ...b, [key]: null }));
+    if (r && r.ok === false) setErrors((e) => ({ ...e, [key]: r.error || "That did not work. Try again." }));
+  }
+
+  function onKeyDown(e) {
+    if (e.defaultPrevented || e.metaKey || e.ctrlKey || e.altKey || isTyping(e.target)) return;
+    if (e.key === "Escape" && current != null) {
+      e.preventDefault();
+      choose(null);
+    } else if (keys && showNotes && (e.key === "j" || e.key === "J" || e.key === "k" || e.key === "K")) {
+      const next = walkNext(ordered, current, e.key.toLowerCase() === "j" ? 1 : -1);
+      if (next == null) return;
+      e.preventDefault();
+      choose(next, true);
+    }
+  }
+
+  const cols = showNotes ? (GRID[side] ?? GRID.right)[marginWidth] ?? GRID.right.md : "";
+  const marginFirst = side === "left";
+  const typeSize = TEXT[textSize] ?? TEXT.md;
+  const summary = countWords(counts, countLabels);
+
+  const noteList = (list) =>
+    list.map((n) => (
+      <Note
+        key={n.id}
+        note={n}
+        kinds={kinds}
+        selected={n.id === current}
+        busy={busy[n.id]}
+        error={errors[n.id]}
+        readOnly={readOnly}
+        canAct={Boolean(onAction)}
+        onSelect={(id) => choose(id)}
+        onPress={press}
+        rootId={rootId}
+        cardRef={(el) => (el ? cards.current.set(n.id, el) : cards.current.delete(n.id))}
+        quoteShown={passages.find((p) => p.id === n.passage)?.node != null}
+      />
+    ));
+
+  let body;
+  if (status === "loading") body = <Loading cols={cols} />;
+  else if (status === "failed")
+    body = (
+      <Notice tone="danger" title="The notes did not load" action={onRetry ? <Button size="sm" icon="refresh" onClick={onRetry}>Try again</Button> : null}>
+        {error || "Something went wrong. Try again."}
+      </Notice>
+    );
+  else if (!passages.length) body = <Empty icon="message-square" title={emptyTitle} body={emptyBody} />;
+  else
+    body = (
+      <>
+        <ol className="m-0 grid list-none gap-y-1 p-0">
+          {passages.map((p) => {
+            const mine = byPassage.get(p.id) ?? [];
+            const selectedHere = mine.some((n) => n.id === current);
+            const Heading = p.level >= 2 && p.level <= 4 ? `h${p.level}` : null;
+            const onPassage = mine.length ? () => choose(cycleNote(mine, current)) : undefined;
+            return (
+              <li
+                key={p.id}
+                ref={(el) => (el ? rows.current.set(p.id, el) : rows.current.delete(p.id))}
+                data-passage={p.id}
+                data-selected={selectedHere ? "" : undefined}
+                className={cx("grid grid-cols-[minmax(0,1fr)] gap-x-6 gap-y-2 py-1.5", cols)}
+              >
+                <div
+                  {...(mine.length
+                    ? {
+                        tabIndex: 0,
+                        onClick: onPassage,
+                        onKeyDown: (e) => {
+                          if ((e.key === "Enter" || e.key === " ") && e.target === e.currentTarget) {
+                            e.preventDefault();
+                            onPassage();
+                          }
+                        },
+                        "aria-label": `${p.label ? `${p.label}. ` : ""}${mine.length} ${mine.length === 1 ? "note" : "notes"}. Press Enter to select.`,
+                        role: "group",
+                      }
+                    : {})}
+                  className={cx(
+                    "flex min-w-0 gap-3 rounded-md px-2 py-1.5 outline-none",
+                    typeSize,
+                    marginFirst && showNotes && "@2xl:order-last",
+                    mine.length && "cursor-pointer focus-visible:ring-2 focus-visible:ring-ring",
+                    selectedHere ? "bg-accent" : mine.length ? "hover:bg-accent/50" : "",
+                  )}
+                >
+                  {p.lead ? <span className="w-12 shrink-0 pt-0.5 text-xs tabular-nums text-muted-foreground">{p.lead}</span> : null}
+                  <div className="grid min-w-0 grow gap-0.5">
+                    {p.label ? <span className="text-[13px] font-semibold leading-snug">{p.label}</span> : null}
+                    <Words passage={p} notes={mine} kinds={kinds} selectedId={current} rootId={rootId} as={Heading ?? "p"} />
+                  </div>
+                </div>
+                {showNotes ? <div className={cx("grid min-w-0 content-start gap-2", marginFirst && "@2xl:order-first")}>{noteList(mine)}</div> : null}
+              </li>
+            );
+          })}
+        </ol>
+        {showNotes && orphans.length ? (
+          <section aria-label={orphanTitle} className="mt-2 grid gap-2 border-t border-border pt-3">
+            <h3 className="m-0 text-xs font-medium uppercase tracking-wide text-muted-foreground">{orphanTitle}</h3>
+            <div className="grid grid-cols-[minmax(0,1fr)] gap-2 @2xl:grid-cols-2">{noteList(orphans)}</div>
+          </section>
+        ) : null}
+      </>
+    );
+
+  return (
+    <section
+      aria-label={label}
+      tabIndex={0}
+      onKeyDown={onKeyDown}
+      className={cx("@container grid min-w-0 grid-cols-[minmax(0,1fr)] gap-3 rounded-lg outline-none focus-visible:ring-2 focus-visible:ring-ring", className)}
+    >
+      {showNotes && status === "ready" && passages.length > 0 && Boolean(marginTitle || summary || (keys && ordered.length > 0) || !notes.length) ? (
+        <header className="flex flex-wrap items-baseline justify-between gap-x-4 gap-y-1">
+          {marginTitle ? <h2 className="m-0 text-base font-semibold leading-tight">{marginTitle}</h2> : null}
+          <p className="m-0 flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground">
+            {summary ? <span>{summary}</span> : !notes.length ? <span>{noNotes}</span> : null}
+            {keys && ordered.length ? (
+              <span className="hidden items-center gap-1 @2xl:inline-flex">
+                <Kbd>J</Kbd>
+                <Kbd>K</Kbd>
+                <span>next and previous note</span>
+              </span>
+            ) : null}
+          </p>
+        </header>
+      ) : null}
+      <p role="status" aria-live="polite" className="sr-only">
+        {current != null ? `Note ${position} of ${ordered.length}` : ""}
+      </p>
+      {body}
+    </section>
+  );
+}

package/registry/blocks/mind-map/README.md

@@ -96,7 +96,9 @@ string, or nothing (a fresh map). The component runs it on `value`.
 - `placeholder` — what an empty topic shows while it is typed (default
   "New topic").
 - `height` — px or any CSS length, default `600`. A height class in
-  `className` (`h-dvh`, `h-full`, `flex-1`) replaces it.
+  `className` (`h-full`, `min-h-0 flex-1`) replaces it: `min-h-0 flex-1`
+  fills what the surface has left (the Example). Never `h-dvh` or a `vh`
+  height, which `npm run check` refuses.
 - `label` — the map's accessible name (default "Mind map").
 - `onSelectionChange(topic | null)` — the selected topic changed (a side
   panel with its notes).
@@ -186,7 +188,7 @@ function PlanMap({ plan }) {
       onChange={setMap}
       onSave={(m) => updateRow({ source: "plans", id: plan.id, patch: { map: m, map_text: mindMapToText(m) } })}
       label={`${plan.name} map`}
-      className="h-[calc(100dvh-8rem)]"
+      className="min-h-0 flex-1"
     />
   );
 }

package/registry/blocks/needs-you/README.md

@@ -0,0 +1,177 @@
+# NeedsYou
+
+What waits on the member, drawn inside the app. Four pieces:
+
+- **NeedsYou** — the queue. The agent's questions and its yeses on this
+  app. A question is **answered in place** (`QuestionBox`); a yes is the
+  `approval` block's press frame (`renderYes`); anything else the app
+  cannot settle (connecting an account, spending money, several questions
+  at once) opens the desk with one press.
+- **QuestionBox** — the agent's question, answered where it was asked: its
+  options, one press each, and a box for the member's own words where the
+  question welcomes them.
+- **WaitingYes** — the frozen-text card. What goes out, frozen while the
+  ask waits, then "Waiting for your yes on the desk", **Open the desk**
+  and **Take the ask back**. It is also what the `approval` block shows
+  when its press frame cannot load.
+- **AgentWorking** — the strip while the agent works: what it is on now,
+  **Stop**, and "Stop keeps everything written so far".
+
+An answer is words, so the app takes it. The yes is not: the app's own
+code never draws an Approve. The press is the Makersclaw-held frame of the
+`approval` block, which app code cannot script. Connecting an account and
+money stay on the desk.
+
+```jsx
+import { NeedsYou, QuestionBox, WaitingYes, AgentWorking } from "../components/blocks/needs-you";   // a Makersclaw app ("./blocks/needs-you" from components/)
+import { NeedsYou, QuestionBox, WaitingYes, AgentWorking } from "@/components/makersclaw/blocks/needs-you";   // a shadcn project
+```
+
+Client components. The Example is at the end.
+
+## Which hook feeds it
+
+```js
+const needs = useNeedsYou();   // lib/hooks.js
+// → { items, working, open(item), answer(item, …), takeBack(item), stop(request), loading, error, unavailable, reload }
+```
+
+It reads `GET _claw/requests`: only the member's own asks (`mine`).
+`items` are the asks that wait on them; `working` are their asks that
+run now. Each item says how the app can settle it: `via` is `"answer"` (a
+question: `answer(item, { optionId | text })`, which is
+`POST _claw/requests/:id/answer`), `"press"` (the one ask's yes: the
+`approval` block, `useApproval(item.id)`) or `null` (the desk: `open`).
+`takeBack` and `stop` are `POST _claw/requests/:id/stop`.
+
+## Props
+
+### NeedsYou
+
+- `items` — `needs.items`: `[{ id, request, kind, text, title, at, via,
+  options, free, needsAt }]`. `kind` is `question`, `yes` or `spend`
+  ("Waiting for your yes on the desk · Open the desk" when the app cannot
+  take it), `connect` ("Connect on the desk"); any other word reads "Needs
+  you on the desk". `text` is the agent's words, `title` the ask's, `at`
+  when (words, a `Date` or ISO).
+- `onOpen(item)` — `needs.open`. The press of everything the app cannot
+  settle itself. Without it those rows have no press.
+- `onAnswer(item, { optionId | text })` — `needs.answer`. An item with
+  `via: "answer"` then shows its `QuestionBox`; without it that item opens
+  the desk, as before.
+- `renderYes(item)` — draws the yes of an item with `via: "press"`: a
+  component of yours that calls `useApproval(item.id)` and returns the
+  `approval` block. Without it that item opens the desk.
+- `empty` — the line when nothing waits. Default "Nothing waits on you
+  here." `false` draws nothing at all when the list is empty.
+- `title` — the head. Default "Needs you"; `null` for none.
+- `loading` — `needs.loading`: skeleton lines before the first read.
+- `unavailable` — `needs.unavailable`: a quiet "not connected yet".
+- `className` — layout around it. Never colour.
+
+### QuestionBox
+
+- `options` — `[{ id, label }]` the question offers (none: words only).
+  A lone press answers on the spot, as the desk's form does.
+- `free` — `false` when the question takes one of its options only
+  (default: words are welcome).
+- `onAnswer({ optionId } | { text })` — `needs.answer(item, …)` or
+  `chat.answer(…)`; async, answers `{ ok }` or `{ ok: false, error }`. A
+  refusal is shown as the door words it.
+- `placeholder`, `sendLabel`, `className`.
+
+### WaitingYes
+
+- `title` — what it is ("How to cover a sudden sick day").
+- `frozen` — what goes out, exactly as it will go (text or a node). It is
+  drawn frozen (muted, with a lock) while the ask waits.
+- `kicker` — the line over it. Default "Ready to send".
+- `state` — `ready` (nothing asked yet: the text only, no state line) ·
+  `waiting` (default) · `approved` ("You said yes · the agent is on it")
+  · `declined` · `taken` · `failed` (with `error`).
+- `body` — one sentence under "Waiting for your yes on the desk", in the
+  app's words: say what the agent does after the yes.
+- `onOpen()` — opens the desk on this ask (`() => needs.open(item)`).
+- `onTakeBack()` — async, answers `{ ok: true }` or `{ ok: false, error
+  }` (`() => needs.takeBack(item)`). It stops the ask while the agent
+  has not acted; the card then says "Taken back. Nothing went out."
+  Without it there is no Take back.
+- `takeBackLabel` — default "Take the ask back".
+
+### AgentWorking
+
+- `words` — what the agent is doing, in the app's words ("Writing the
+  draft"). Default "Working on it".
+- `steps` — `[{ label, status }]` (`running` · `done` · `failed`): the
+  running step shows, with "2 of 6 steps done".
+- `onStop()` — `() => needs.stop(request)` or `chat.stop`. It may be
+  async and answer `{ ok }` or `{ ok: false, error }`: the button spins
+  while it is out and a failure says why. Without it there is no Stop.
+- `stopping` — true while a stop you track yourself is out.
+- `stopHint` — default "Stop keeps everything written so far"; `null`
+  for none.
+
+## Who may do what
+
+- Every member sees only their own asks: the door lists `mine`.
+- Stop and Take back: the asker, an owner, an admin, or the app's owner
+  (`mayStop` on the request). Give `onStop`/`onTakeBack` only when the
+  request says the member may; the door refuses anyone else anyway.
+- Only the member who asked answers a question or gives a yes; the door
+  refuses everyone else (owners and admins too), and a question answered
+  after it moved on (`needsAt`) is refused.
+- The yes: the `approval` block's press frame, never these blocks.
+- An account sign-in and money: the desk, always.
+
+## Never
+
+- **Never an Approve, a Yes, or a Send that gives the yes.** The yes is
+  the `approval` block's frame; this block's only press toward it is Open
+  the desk, when the frame cannot load.
+- Never answer the one ask (a yes) through `QuestionBox`: the door refuses
+  it (`needs_a_press`).
+- Never let the frozen text be edited while the ask waits. To change it,
+  take the ask back first.
+- Never show another member's asks here.
+
+## Example
+
+A post that waits for its yes, the strip while the agent works, and the
+queue on the home screen.
+
+```jsx
+"use client";
+import { useNeedsYou } from "../lib/hooks";
+import { NeedsYou, WaitingYes, AgentWorking } from "../components/blocks/needs-you";
+
+export function PostStatus({ post }) {
+  const needs = useNeedsYou();
+  const item = needs.items.find((i) => i.request?.id === post.request_id);
+  const running = needs.working.find((r) => r.id === post.request_id);
+  if (running) return <AgentWorking words="Putting the post on Webflow" onStop={() => needs.stop(running)} />;
+  return (
+    <WaitingYes
+      title={post.title}
+      frozen={post.body}
+      state={item ? "waiting" : "ready"}
+      body="Say yes there, and the agent makes this one post live on Webflow, then adds its link here."
+      onOpen={item ? () => needs.open(item) : undefined}
+      onTakeBack={item ? () => needs.takeBack(item) : undefined}
+    />
+  );
+}
+
+export function Waiting() {
+  const needs = useNeedsYou();
+  return (
+    <NeedsYou
+      items={needs.items}
+      onOpen={needs.open}
+      onAnswer={needs.answer}
+      renderYes={(item) => <SendCard item={item} />}   // an Approval card, see the approval block
+      loading={needs.loading}
+      unavailable={needs.unavailable}
+    />
+  );
+}
+```