makersclaw 0.7.0 → 0.8.1

package/registry/blocks/chat-pane/chat-pane.jsx

@@ -0,0 +1,398 @@
+"use client";
+
+import { useContext, useEffect, useRef, useState } from "react";
+import { Button, Icon, IconButton, Spinner, cx } from "../../ui";
+import { addFiles, filesFromTransfer, readFile, useDictation } from "./chat-attach";
+import { ChatDockContext } from "./chat-context";
+import { ChatComposer } from "./chat-composer";
+import { ChatsList } from "./chats-list";
+import { startStep } from "./chat-model";
+
+// ChatPane — the desk's chat pane (claw's web/src/os/windows/artifact/
+// ChatPane.tsx and the composer of its EveChat), as the app's own, in the
+// app's theme (0.8.1, X5; the founder: "add claw's ChatPane as a block in
+// the makersclaw template"). It is the chrome around a conversation:
+//
+//   head       the title, New chat, Chats (the list drops over the chat,
+//              the desk's column mode), close
+//   empty      before the first ask: one line, the past chats, the
+//              suggestions
+//   scroll     the conversation, which stays at the newest words until the
+//              member scrolls up, with a jump to latest
+//   bar        what waits on the member, or says the agent is working
+//   composer   ONE box: the words on top; under them + (attach) at the
+//              left, the microphone and a round arrow at the right, the
+//              arrow a stop while a turn runs; a quiet hint under it
+//
+// It is not the conversation's lines: those are the children. agent-pane
+// draws the agent's (the plan, the work folded, the questions, what it
+// made); any lines will do. Nothing here asks the agent anything: `chat`
+// is an object of the shape useAgentPane() returns (lib/hooks.js), and the
+// pane calls its send, stop, newChat and openSession.
+//
+// A "have the agent do it" button reaches the pane through the dock:
+// openAgent({ ask }) (blocks/agent-dock) hands the pane a starting line,
+// which it sends as the member's first words in a fresh chat (or puts in
+// the box). The agent asks only for what it is missing, in the chat.
+//
+//   chat         the object useAgentPane() returns (required)
+//   title        the head's words, and the box's label (default "Ask the agent")
+//   suggestions  asks that fit the moment, before the first ask
+//   empty        one line before the first ask
+//   placeholder  the box's words before the first ask; once there is a
+//                conversation it says "Ask a follow-up…" (D29) unless
+//                `chat.sameConversation` is false (the next message starts a
+//                new request, and the box keeps the app's own words)
+//   closedWords  the box's words while `blocked` ("Answer above first")
+//   hint         a quiet line under the box
+//   recent       past chats listed before the first ask (default 5; 0 none)
+//   bare         no head (inside a Sheet or a Card that has its own)
+//   fill         take the container's height (default); false: compact,
+//                the conversation scrolls inside a capped height
+//   onClose      a close in the head; inside an AgentDock it is the dock's
+//   started      there is a conversation to draw (else the empty state)
+//   busy         a turn runs: the arrow is a stop while the box is empty
+//   blocked      something waits on the member: the whole box is closed
+//   bar          a node between the conversation and the box
+//   children     the conversation's lines
+//   className    layout around it. Never colour.
+export function ChatPane({
+  chat,
+  title = "Ask the agent",
+  suggestions = [],
+  empty,
+  placeholder,
+  closedWords = "Not available right now",
+  hint,
+  recent = 5,
+  bare = false,
+  fill = true,
+  onClose: onCloseProp,
+  started = false,
+  busy = false,
+  blocked = false,
+  bar,
+  className,
+  children,
+}) {
+  const dock = useContext(ChatDockContext);
+  const onClose = onCloseProp ?? dock?.close;
+  const [text, setText] = useState("");
+  const [listOpen, setListOpen] = useState(false);
+  const [stopping, setStopping] = useState(false);
+  const [atBottom, setAtBottom] = useState(true);
+  const [files, setFiles] = useState([]);
+  const [attachError, setAttachError] = useState(null);
+  const [encoding, setEncoding] = useState(false);
+  const [dragOver, setDragOver] = useState(false);
+  const fileInput = useRef(null);
+  const textarea = useRef(null);
+  const dragDepth = useRef(0);
+  const listRef = useRef(null);
+  const rootRef = useRef(null);
+  const stick = useRef(true);
+  const chatRef = useRef(chat);
+  chatRef.current = chat;
+
+  const chats = chat?.chats && !chat.chats.unavailable ? chat.chats : null;
+  const canNew = typeof chat?.newChat === "function";
+  const canStop = busy && !blocked && Boolean(chat?.request?.id) && Boolean(chat?.stop);
+
+  useEffect(() => {
+    if (!busy) setStopping(false);
+  }, [busy]);
+
+  // Dictation adds finished phrases to the box.
+  const dictation = useDictation((words) => setText((t) => (t.trim() ? `${t.trimEnd()} ${words}` : words)));
+
+  const attach = (incoming) => {
+    const r = addFiles(files, incoming);
+    setFiles(r.files);
+    setAttachError(r.error);
+  };
+
+  // The Chats list closes on a press outside it and on Escape.
+  useEffect(() => {
+    if (!listOpen) return undefined;
+    const onDown = (e) => {
+      if (!rootRef.current?.querySelector("[data-chats]")?.contains(e.target) && !e.target.closest?.("[data-chats-toggle]")) setListOpen(false);
+    };
+    const onKey = (e) => {
+      if (e.key === "Escape") setListOpen(false);
+    };
+    document.addEventListener("mousedown", onDown);
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("mousedown", onDown);
+      document.removeEventListener("keydown", onKey);
+    };
+  }, [listOpen]);
+
+  // The newest words stay in view while the agent writes — until the
+  // member scrolls up to read, which stops it following.
+  useEffect(() => {
+    const el = listRef.current;
+    if (el && stick.current) el.scrollTop = el.scrollHeight;
+  }, [chat?.view, chat?.turns, chat?.pending, chat?.state, chat?.needs?.at, started]);
+  const onScroll = () => {
+    const el = listRef.current;
+    if (!el) return;
+    const near = el.scrollHeight - el.scrollTop - el.clientHeight < 48;
+    stick.current = near;
+    setAtBottom(near);
+  };
+  const jump = () => {
+    const el = listRef.current;
+    if (el) el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
+  };
+
+  const submit = async (words) => {
+    const typed = String(words ?? text).trim();
+    const sending = words === undefined ? files : [];
+    // Files without words still go: the agent is told what they are.
+    const t = typed || (sending.length ? `Attached: ${sending.map((f) => f.name).join(", ")}` : "");
+    if (!t || !chat?.send || encoding) return;
+    dictation.stop();
+    stick.current = true;
+    if (sending.length === 0) {
+      setText("");
+      chat.send(t);
+      return;
+    }
+    setEncoding(true);
+    try {
+      const read = await Promise.all(sending.map(readFile));
+      setText("");
+      setFiles([]);
+      setAttachError(null);
+      chat.send(t, { files: read });
+    } catch {
+      setAttachError("A file could not be read. Try attaching it again.");
+    } finally {
+      setEncoding(false);
+    }
+  };
+  const stop = () => {
+    if (stopping || !chat?.stop) return;
+    setStopping(true);
+    chat.stop();
+  };
+
+  // A starting line from the dock (openAgent). Fresh: a new conversation
+  // first, then the line sent as its first words, so the agent asks only
+  // for what it is missing. Or prefilled for the member to finish. The pane
+  // tells the dock it took it; a pane that has not mounted yet takes it when
+  // it does.
+  const start = dock?.start ?? null;
+  const takenRef = useRef(null);
+  const newedRef = useRef(null);
+  useEffect(() => {
+    if (!start) return;
+    const step = startStep({
+      start,
+      handled: takenRef.current,
+      sessionId: chat?.sessionId ?? null,
+      blocked,
+      canNew,
+      newed: newedRef.current === start.nonce,
+    });
+    if (step === "none" || step === "wait") return;
+    if (step === "new-chat") {
+      newedRef.current = start.nonce;
+      setListOpen(false);
+      chatRef.current?.newChat?.();
+      return;
+    }
+    takenRef.current = start.nonce;
+    if (step === "send") {
+      stick.current = true;
+      chatRef.current?.send?.(String(start.ask).trim());
+    } else {
+      // Words already in the box are the member's: the line goes under them.
+      setText((t) => (t.trim() ? `${t.trimEnd()}\n${start.ask}` : String(start.ask)));
+      requestAnimationFrame(() => {
+        const el = textarea.current;
+        if (!el || el.disabled) return;
+        el.focus({ preventScroll: true });
+        el.setSelectionRange(el.value.length, el.value.length);
+      });
+    }
+    dock?.taken?.(start.nonce);
+  }, [start, chat?.sessionId, blocked, canNew, dock]);
+
+  const followUp = started && chat?.sameConversation !== false;
+  const words = blocked ? closedWords : followUp ? "Ask a follow-up…" : (placeholder ?? "Ask anything…");
+
+  return (
+    <div
+      ref={rootRef}
+      className={cx("@container relative flex min-w-0 flex-col bg-background text-sm text-foreground", fill && "h-full min-h-0", className)}
+      onDragEnter={(e) => {
+        if (!e.dataTransfer?.types?.includes("Files") || blocked) return;
+        e.preventDefault();
+        dragDepth.current += 1;
+        setDragOver(true);
+      }}
+      onDragLeave={(e) => {
+        if (!e.dataTransfer?.types?.includes("Files")) return;
+        dragDepth.current = Math.max(0, dragDepth.current - 1);
+        if (dragDepth.current === 0) setDragOver(false);
+      }}
+      onDragOver={(e) => {
+        if (e.dataTransfer?.types?.includes("Files")) e.preventDefault();
+      }}
+      onDrop={(e) => {
+        if (!e.dataTransfer?.types?.includes("Files")) return;
+        e.preventDefault();
+        dragDepth.current = 0;
+        setDragOver(false);
+        if (!blocked) attach(filesFromTransfer(e.dataTransfer));
+      }}
+    >
+      {dragOver ? (
+        <div className="pointer-events-none absolute inset-0 z-20 grid place-items-center rounded-[var(--radius)] border-2 border-dashed border-primary bg-background/80 text-sm font-medium">
+          Drop files to attach
+        </div>
+      ) : null}
+      {!bare ? (
+        <div className="flex h-10 shrink-0 items-center gap-1 border-b border-border pl-3.5 pr-2 font-semibold">
+          <Icon name="sparkles" size={16} className="shrink-0 text-primary" />
+          <span className="min-w-0 flex-1 truncate">{title}</span>
+          {canNew ? (
+            <IconButton
+              icon="plus"
+              size="sm"
+              label="New chat"
+              onClick={() => {
+                setListOpen(false);
+                chat.newChat();
+              }}
+            />
+          ) : null}
+          {chats ? (
+            <Button size="sm" variant="quiet" data-chats-toggle="" aria-expanded={listOpen} aria-label="Chats" onClick={() => setListOpen((v) => !v)}>
+              <Icon name="history" size={14} />
+              <span className="hidden @[16rem]:inline">Chats</span>
+              {chats.items.length > 0 ? <span className="text-xs text-muted-foreground">{chats.items.length}</span> : null}
+            </Button>
+          ) : null}
+          {onClose ? <IconButton icon="x" size="sm" label="Close" onClick={onClose} /> : null}
+        </div>
+      ) : null}
+
+      {listOpen && chats ? (
+        <div data-chats="" className="absolute inset-x-0 z-10 max-h-72 overflow-y-auto border-b border-border bg-popover text-popover-foreground shadow-md" style={{ top: bare ? 0 : "2.5rem" }}>
+          <ChatsList
+            chats={chats}
+            currentId={chat?.sessionId}
+            onPick={(id) => {
+              setListOpen(false);
+              chat.openSession?.(id);
+            }}
+          />
+        </div>
+      ) : null}
+
+      <div className={cx("relative", fill ? "min-h-0 flex-1" : "")}>
+        <div
+          ref={listRef}
+          onScroll={onScroll}
+          role="log"
+          aria-live="polite"
+          aria-label={title}
+          className={cx("grid min-w-0 content-start gap-3 overflow-y-auto overscroll-contain p-3.5", fill ? "h-full min-h-0" : started ? "max-h-96" : "")}
+        >
+          {started ? (
+            children
+          ) : (
+            <>
+              {empty ? <p className="text-muted-foreground">{empty}</p> : null}
+              {chat?.loading ? (
+                <div className="flex items-center gap-2 text-xs text-muted-foreground">
+                  <Spinner size="sm" label="Loading" /> Opening the chat…
+                </div>
+              ) : null}
+              {chats && recent > 0 && !chat?.loading ? (
+                <section aria-label="Recent chats" className="grid min-w-0 gap-0.5">
+                  <h3 className="text-xs font-medium text-muted-foreground">Recent chats</h3>
+                  <div className="-mx-3.5">
+                    <ChatsList chats={{ ...chats, items: chats.items.slice(0, recent) }} currentId={chat?.sessionId} onPick={(id) => chat.openSession?.(id)} />
+                  </div>
+                  {chats.items.length > recent ? (
+                    <Button variant="link" size="inherit" className="justify-self-start text-xs" onClick={() => setListOpen(true)}>
+                      All {chats.items.length} chats
+                    </Button>
+                  ) : null}
+                </section>
+              ) : null}
+              {suggestions.length ? (
+                <div className="flex min-w-0 flex-wrap gap-1.5">
+                  {suggestions.map((s) => (
+                    <button
+                      key={s}
+                      type="button"
+                      onClick={() => submit(s)}
+                      className="flex max-w-full min-w-0 items-start gap-1.5 rounded-[var(--radius)] border border-border px-2.5 py-1 text-left text-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring"
+                    >
+                      <Icon name="sparkles" size={12} className="mt-0.5 shrink-0 text-muted-foreground" />
+                      <span className="min-w-0 break-words">{s}</span>
+                    </button>
+                  ))}
+                </div>
+              ) : null}
+            </>
+          )}
+        </div>
+        {!atBottom && started ? (
+          <IconButton icon="arrow-down" size="sm" label="Jump to latest" onClick={jump} className="absolute bottom-2 right-3 shadow-md" />
+        ) : null}
+      </div>
+
+      {bar}
+      {chat?.error ? <p className="shrink-0 px-3.5 pt-2 text-xs text-destructive">{chat.error}</p> : null}
+      {chat?.notice ? (
+        <p role="status" className="shrink-0 px-3.5 pt-2 text-xs text-muted-foreground">
+          {chat.notice}
+        </p>
+      ) : null}
+      {chat?.unavailable ? (
+        <p className="shrink-0 px-3.5 pt-2 text-xs text-muted-foreground">
+          This chat needs a newer Makersclaw.{" "}
+          {chat.request ? (
+            <Button variant="link" size="inherit" onClick={() => chat.openOnDesk?.()}>
+              Open it on the desk
+            </Button>
+          ) : null}
+        </p>
+      ) : null}
+      {attachError || dictation.error ? (
+        <p role="alert" className="shrink-0 px-3.5 pt-2 text-xs text-destructive">
+          {attachError ?? dictation.error}
+        </p>
+      ) : null}
+
+      <ChatComposer
+        className="shrink-0 px-3 pb-3 pt-2"
+        label={title}
+        value={text}
+        onChange={setText}
+        onSubmit={() => submit()}
+        onStop={stop}
+        onAttach={attach}
+        files={files}
+        onRemoveFile={(i) => setFiles((all) => all.filter((_, j) => j !== i))}
+        busy={busy}
+        canStop={canStop}
+        stopping={stopping}
+        blocked={blocked}
+        sending={Boolean(chat?.sending)}
+        encoding={encoding}
+        dictation={dictation}
+        placeholder={words}
+        hint={hint}
+        textareaRef={textarea}
+        fileInputRef={fileInput}
+      />
+    </div>
+  );
+}

package/registry/blocks/chat-pane/chats-list.jsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { cx } from "../../ui";
+import { ago } from "./chat-model";
+
+/**
+ * The member's past chats, newest first, one line each: the title, a dot on
+ * one that needs them (warning) or is working (info), and its age. The
+ * pane's Chats overlay and its empty state both draw this.
+ *
+ *   chats      { items: [{ sessionId, title, mark: "needs" | "working" | null, at }],
+ *                loading, error }
+ *   currentId  the open chat's session
+ *   onPick     (sessionId) => void
+ */
+export function ChatsList({ chats, currentId, onPick }) {
+  if (chats.items.length === 0)
+    return (
+      <p className="px-3.5 py-3 text-xs text-muted-foreground">{chats.loading ? "Loading chats…" : chats.error ? "The chats did not load." : "No chats yet. Your first message starts one."}</p>
+    );
+  return (
+    <nav aria-label="Past chats" className="grid">
+      {chats.items.map((c) => (
+        <button
+          key={c.sessionId}
+          type="button"
+          aria-current={c.sessionId === currentId ? "true" : undefined}
+          onClick={() => onPick(c.sessionId)}
+          className={cx(
+            "flex min-w-0 items-center gap-2 px-3.5 py-2 text-left text-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring",
+            c.sessionId === currentId && "bg-muted font-medium",
+          )}
+        >
+          <span className="min-w-0 flex-1 truncate" title={c.title}>
+            {c.title}
+          </span>
+          {c.mark ? (
+            <span
+              role="img"
+              aria-label={c.mark === "needs" ? "Needs you" : "Working"}
+              title={c.mark === "needs" ? "Needs you" : "Working"}
+              className={cx("size-2 shrink-0 rounded-full", c.mark === "needs" ? "bg-warning" : "animate-pulse bg-info")}
+            />
+          ) : null}
+          <time className="shrink-0 text-muted-foreground" dateTime={c.at ?? undefined}>
+            {ago(c.at)}
+          </time>
+        </button>
+      ))}
+    </nav>
+  );
+}

package/registry/blocks/chat-pane/demo.jsx

@@ -0,0 +1,103 @@
+"use client";
+
+// ChatPane over a pretend chat — the gallery's and the smoke test's surface.
+// Not installed into apps. Three frames side by side: an empty chat (past
+// chats, suggestions, the message box and its hint), a chat that answers
+// after a moment (ask anything: a stop takes the send arrow's place while it
+// works), and a chat that waits on the member (the box is closed and says
+// why). The message box is the desk's: the words on top, + at the left and
+// the microphone and a round arrow at the right.
+import { useEffect, useRef, useState } from "react";
+import { ChatPane } from "../components/blocks/chat-pane";
+
+const CHATS = {
+  items: [
+    { sessionId: "past-1", title: "Who should we follow up with this week?", mark: "needs", at: new Date(Date.now() - 20 * 60 * 1000).toISOString() },
+    { sessionId: "past-2", title: "Weekly pipeline read", mark: null, at: new Date(Date.now() - 3 * 3600 * 1000).toISOString() },
+  ],
+  loading: false,
+  error: null,
+  unavailable: false,
+};
+
+function usePretendChat({ chats = CHATS, answer = true } = {}) {
+  const [messages, setMessages] = useState([]);
+  const [state, setState] = useState(null);
+  const timers = useRef([]);
+  useEffect(() => () => timers.current.forEach(clearTimeout), []);
+  return {
+    sessionId: messages.length ? "demo" : null,
+    state,
+    request: messages.length ? { id: "demo-request", title: "Ask" } : null,
+    view: { messages, thinking: state === "working", failure: null, questions: [] },
+    turns: [],
+    pending: null,
+    sending: false,
+    loading: false,
+    error: null,
+    unavailable: false,
+    chats,
+    send: (text) => {
+      const id = `m${Date.now()}`;
+      setState("working");
+      setMessages((m) => [...m, { id: `${id}u`, role: "user", text }]);
+      if (!answer) return;
+      timers.current.push(
+        setTimeout(() => {
+          setMessages((m) => [...m, { id: `${id}a`, role: "assistant", text: "Three people have gone quiet for over two weeks. Want me to draft a note to each?" }]);
+          setState("done");
+        }, 1800),
+      );
+    },
+    stop: () => setState("stopped"),
+    newChat: () => {
+      setMessages([]);
+      setState(null);
+    },
+    openSession: () => undefined,
+    openOnDesk: () => true,
+  };
+}
+
+function Lines({ messages }) {
+  return messages.map((m) => (
+    <p key={m.id} className={m.role === "user" ? "justify-self-end rounded-[var(--radius)] bg-muted px-3 py-2" : ""}>
+      {m.text}
+    </p>
+  ));
+}
+
+function Frame({ title, ...options }) {
+  const chat = usePretendChat(options);
+  const messages = chat.view.messages;
+  return (
+    <div className="h-[560px] min-w-0 overflow-hidden rounded-lg border border-border">
+      <ChatPane
+        chat={chat}
+        title={title}
+        empty="The agent reads every person and deal. What it changes you can take back."
+        suggestions={["Who should we follow up with?", "What changed this week?"]}
+        hint="Enter sends · Shift+Enter is a new line"
+        started={messages.length > 0}
+        busy={chat.state === "working"}
+      >
+        <Lines messages={messages} />
+      </ChatPane>
+    </div>
+  );
+}
+
+export default function ChatPaneDemo() {
+  const waiting = usePretendChat({ chats: null });
+  return (
+    <div className="grid gap-4 p-6 md:grid-cols-3">
+      <Frame title="Ask the agent" />
+      <Frame title="No chats yet" chats={{ items: [], loading: false, error: null, unavailable: false }} />
+      <div className="h-[560px] min-w-0 overflow-hidden rounded-lg border border-border">
+        <ChatPane chat={waiting} title="Waiting on you" started blocked closedWords="Answer above first" bar={<p className="border-t border-border px-3.5 py-2 text-xs text-muted-foreground">A question for you: which list first?</p>}>
+          <p>I can start with the warm leads or the investors.</p>
+        </ChatPane>
+      </div>
+    </div>
+  );
+}

package/registry/blocks/chat-pane/index.js

@@ -0,0 +1,9 @@
+// The ChatPane block — `makersclaw add chat-pane`. Fixed: compose it
+// through its props (README.md beside this file). The model's helpers are
+// plain functions; they work on the server too.
+export { ChatPane } from "./chat-pane";
+export { ChatComposer } from "./chat-composer";
+export { ChatsList } from "./chats-list";
+export { ChatDockContext } from "./chat-context";
+export { ago, startStep } from "./chat-model";
+export { MAX_BYTES, MAX_FILES, addFiles, filesFromTransfer, formatBytes, readFile, useDictation } from "./chat-attach";

package/registry/blocks/connect-card/README.md

@@ -0,0 +1,99 @@
+# ConnectCard
+
+The accounts the app declares, as rows the member already knows from the
+window's Settings › Connections: what each is for, its kind (Mail,
+Calendar), needed or optional, **live** or **not connected** (a mark and
+a word), which accounts meet it, and **Connect** or **Change**. Part of
+the agent kit (0.8.1): the member connects where the need is felt,
+inside the app.
+
+```jsx
+import { ConnectCard, ConnectRow } from "../components/blocks/connect-card";   // a Makersclaw app
+import { ConnectCard, ConnectRow } from "@/components/makersclaw/blocks/connect-card";   // a shadcn project
+```
+
+A client component. Its own width decides its layout: under about
+384 px each row's state and button go under its words.
+
+## What Connect does
+
+The block only calls `onConnect(key)`. `useConnections().connect` then:
+
+1. Inside the desk, asks it to open its connections panel for that
+   need (`claw:open-connections`). The panel lists every provider of the
+   need's kind — a "mail" need shows Gmail, Outlook, Zoho Mail — and the
+   member signs in there. No agent turn, no chat.
+2. Outside the desk (the app on its own host), fetches the link (`POST
+   _claw/connect`) and opens it in a new tab.
+3. Either way, looks every 3 s for two minutes until the account is
+   live; `connecting` is its key meanwhile, and the row says "Waiting
+   for sign-in".
+
+## Props
+
+### ConnectCard
+
+- `connections` — useConnections' `connections`: `[{ key, label,
+  required, connected, accounts, category, category_label }]`.
+- `onConnect(key)` — useConnections' `connect`. Leave it out and no
+  button is drawn (a read-only list).
+- `connecting` — the key being connected (useConnections'
+  `connecting`).
+- `title` — the head (default "Accounts it uses"); `null` for none.
+  `description` — one line under it: what the app does with them.
+- `empty` — what it says with no accounts; `null` draws nothing.
+- `className` — layout around it. Never colour.
+
+### ConnectRow
+
+One row, for a list of your own (an empty state, a setup step):
+`connection`, `onConnect(key)`, `connecting` (boolean), `connectLabel`
+("Connect"), `changeLabel` ("Change"). Put it inside a `<ul>`, in an
+element with `@container` so its layout follows its width.
+
+## useConnections (lib/hooks.js)
+
+```js
+const { connections, connecting, connect } = useConnections();
+```
+
+It reads `GET _claw/connect` once, then only while an account is being
+connected, and again when the page comes back. `connect(key)` resolves
+`{ opened: "desk" | "tab" | false, connected?, error? }`. On a claw from
+before the door it is `unavailable`: draw the card with `empty`, never
+an error.
+
+## Who may do what
+
+Any member who opens the app sees the accounts and may connect one: the
+sign-in is theirs, at the provider, as on the desk. Which accounts an
+app may use is the app's declaration, not this block's.
+
+## Never
+
+- Never a sign-in form, a password or a key field: the member signs in
+  at the provider, on the desk's panel or the link's page.
+- Never an agent turn to connect an account ("Ask the agent to connect
+  Gmail"): Connect opens the panel.
+- Never live or not by colour alone.
+
+## Example
+
+```jsx
+"use client";
+import { useConnections } from "../lib/hooks";
+import { ConnectCard } from "../components/blocks/connect-card";
+
+export default function WhatItReads() {
+  const { connections, connecting, connect } = useConnections();
+  return (
+    <ConnectCard
+      title="What the CRM reads"
+      description="Your mail and calendar, to build each person's timeline."
+      connections={connections}
+      connecting={connecting}
+      onConnect={connect}
+    />
+  );
+}
+```

package/registry/blocks/connect-card/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "connect-card",
+  "title": "ConnectCard",
+  "description": "The accounts the app declares, as rows like the window's Settings › Connections: what each is for, its kind (Mail, Calendar), needed or optional, live or not connected as a mark and a word, which accounts meet it, and Connect or Change. The press goes out as onConnect(key): useConnections() (lib/hooks.js) opens the desk's connections panel for that need, listing every provider of the kind (no agent turn), or hands out the link in a new tab outside the desk, then watches until the account is live. Signing in stays the member's, at the provider.",
+  "useWhen": "An app that reads or writes through an outside account shows what it uses and lets the member connect it where the need is felt: a CRM's \"What the CRM reads\" (mailbox, calendar), an inbox app's accounts, a setup step, the empty state of a screen that needs a mailbox. For a first-run checklist use setup-checklist; for the app's own settings page use settings-list.",
+  "tags": ["connect", "connections", "accounts", "integrations", "oauth", "mailbox", "calendar", "sign in", "setup", "live", "kit"],
+  "exports": ["ConnectCard", "ConnectRow"],
+  "files": ["index.js", "connect-card.jsx"],
+  "requires": []
+}