makersclaw 0.7.0 → 0.8.1

package/registry/blocks/chat-pane/README.md

@@ -0,0 +1,143 @@
+# ChatPane
+
+The desk's chat pane, as the app's own, in the app's theme (0.8.1). The
+founder, after reviewing the app agent's message box next to the
+Automations window's: "add claw's ChatPane as a block in the makersclaw
+template". This is that port: claw's `web/src/os/windows/artifact/ChatPane`
+and the composer of its `EveChat`, in JSX, with the kit's `Icon` and
+`Button` and the app's tokens, talking to the agent through the app's own
+hook (`useAgentPane`, `lib/hooks.js`) instead of `eve/client`.
+
+It is the **chrome around a conversation**:
+
+- **The head**: the title, **New chat**, **Chats** (the past chats drop over
+  the conversation, newest first, with a dot on one that needs you or is
+  working), and a close.
+- **The empty state**: before the first ask, one line, the recent chats
+  ("No chats yet. Your first message starts one." when there are none), and
+  the app's suggestions.
+- **The conversation**: its lines are the children. It stays at the newest
+  words until the member scrolls up, then offers a jump to latest.
+- **The bar** between the conversation and the box: what waits on the member,
+  or that the agent is working.
+- **The message box**: the desk's composer. **One rounded box.** The words
+  on top, full width, growing with what is typed. Under them a row: **+**
+  (attach) at the left, and at the right the **microphone** and a **round
+  arrow** to send. **While a turn runs, a round stop takes the arrow's
+  place** (once the member types, the arrow comes back: a message sent then
+  waits its turn, as before). A quiet `hint` can sit under the box.
+- **Files** by the + button, by paste and by a drop anywhere on the pane (up
+  to 4 files and 3 MB together); **dictation** where the browser has speech
+  recognition; the box **closed** while something waits on the member, with
+  the reason in its placeholder.
+- **A starting line** from the dock: `openAgent({ ask })` (blocks/agent-dock).
+  The pane sends it as the member's first words in a new chat, or puts it
+  in the box. See "Have the agent do it" below.
+
+```jsx
+import { ChatPane } from "../components/blocks/chat-pane";   // a Makersclaw app ("./blocks/chat-pane" from components/)
+import { ChatPane } from "@/components/makersclaw/blocks/chat-pane";   // a shadcn project
+```
+
+A client component. It needs the kit and nothing else; it is not tied to the
+agent's lines. **For the agent's conversation use `agent-pane`**, which
+draws the plan, the work folded into "Worked through N steps", the
+questions, the yes and what the agent made, inside this pane. Use `ChatPane`
+itself for lines of your own in the desk's frame.
+
+## What was ported, and what was not
+
+Ported: the head (New chat, Chats), the past chats list and its marks, the
+empty state, the scroll that follows, the composer (its layout, the
+attachments, the dictation, the send and stop), the closed box, and the
+hand-off seam in a form the app needs (the starting line).
+
+Not ported, because the app has no such thing: the desk's **rail** beside the
+chat (an app's agent lives in the dock, a column; the Chats overlay is the
+column mode's), the **binding** (headers, scope, the session pointer: the
+app's `useAgentPane` holds those), **`openSession`/`pendingLine`** (the desk's
+hand-off of a request into the agent's chat; the app's starting line does
+that job), **`chatMarks` "In Makersclaw"** (an ask made in Makersclaw shows
+as a pointer in the conversation instead) and the wallet gate (the platform
+refuses a turn with no credits and says so).
+
+## Props
+
+- `chat` — what `useAgentPane()` returns. Required. The pane calls its
+  `send(text, { files })`, `stop()`, `newChat()` and `openSession(id)` and
+  reads `sessionId`, `request`, `chats`, `view`/`turns`/`pending`/`state`
+  (to follow the newest words), `sameConversation`, `sending`, `loading`,
+  `error`, `notice`, `unavailable`.
+- `title` — the head's words, and the box's label. Default `"Ask the agent"`.
+- `suggestions` — asks that fit the moment, as chips 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…" unless `chat.sameConversation` is
+  false.
+- `closedWords` — the box's words while `blocked` ("Answer above first").
+- `hint` — a quiet line under the box ("Enter sends · Shift+Enter is a new
+  line").
+- `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` — default `true`: the pane takes its container's height and the
+  conversation scrolls inside it. `false`: compact, a capped height.
+- `onClose` — a close in the head. Inside an `agent-dock` 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.
+
+`ChatComposer` is also exported, for a box of your own around the same
+frame: `value`, `onChange`, `onSubmit`, `onStop`, `onAttach`, `files`,
+`onRemoveFile`, `busy`, `canStop`, `stopping`, `blocked`, `sending`,
+`encoding`, `dictation` (`useDictation()`), `placeholder`, `label`, `hint`,
+`textareaRef`, `fileInputRef`. `ChatsList` draws the past chats.
+
+## Have the agent do it
+
+A button that says the agent will do the work does not open a form. It calls
+`openAgent("Draft a project plan for me")` (blocks/agent-dock). The dock
+opens, tells this pane the line through `ChatDockContext`, and the pane:
+
+1. starts a new chat (if one is open; `fresh: false` carries on in it),
+2. sends the line as the member's first words, once,
+3. and tells the dock it took it.
+
+With `send: false` it puts the line in the box instead, with the cursor at
+its end (words the member already typed stay, and the line goes under them). A closed box (something waits on the member) always takes the line
+as a prefill. The pure rule is `startStep(...)` in `chat-model.js`.
+
+## The model (plain functions)
+
+`ago(iso)`, `startStep({ start, handled, sessionId, blocked, canNew, newed })`,
+and the composer's parts: `addFiles`, `filesFromTransfer`, `readFile`,
+`formatBytes`, `MAX_FILES`, `MAX_BYTES`, `useDictation`.
+
+## Example
+
+```jsx
+"use client";
+import { useAgentPane } from "../lib/hooks";
+import { ChatPane } from "../components/blocks/chat-pane";
+
+export default function Notes() {
+  const chat = useAgentPane({ key: "notes" });
+  const messages = chat.view?.messages ?? [];
+  return (
+    <ChatPane
+      chat={chat}
+      title="Ask about your notes"
+      suggestions={["Summarise this week"]}
+      hint="Enter sends · Shift+Enter is a new line"
+      started={messages.length > 0}
+      busy={chat.state === "working"}
+    >
+      {messages.map((m) => (
+        <p key={m.id}>{m.text}</p>
+      ))}
+    </ChatPane>
+  );
+}
+```

package/registry/blocks/chat-pane/block.json

@@ -0,0 +1,48 @@
+{
+  "name": "chat-pane",
+  "title": "ChatPane",
+  "description": "The desk's chat pane as the app's own, in the app's theme: the chrome around a conversation. A head (title, New chat, Chats, close) with the past chats dropping over the chat; before the first ask one line, the recent chats and the suggestions; the conversation, kept at the newest words until the member scrolls up, with a jump to latest; a bar for what waits on the member; and the desk's composer: ONE rounded box with the words on top and under them a row, + (attach) at the left and the microphone and a round arrow to send at the right, the arrow a stop while a turn runs, a quiet hint under the box. Files by + or paste or drop, dictation, the box closed while something waits. A starting line handed down by the dock (openAgent) is sent as the member's first words in a fresh chat, or put in the box. It draws what useAgentPane() returns (lib/hooks.js) and decides nothing about the lines of the conversation: those are its children (agent-pane draws the agent's).",
+  "useWhen": "Any app chat with the agent: the pane inside an agent-dock, a compact card beside a record, a sheet. Use agent-pane when the conversation is the agent's (it puts the plan, the work, the questions and the yes inside this pane); use chat-pane itself to draw your own lines in the desk's frame, or just the composer (ChatComposer). Not for a chat between people (chat) or an agent run that is commissioned from a verb and watched (job-panel).",
+  "tags": [
+    "chat",
+    "composer",
+    "message box",
+    "ask",
+    "assistant",
+    "conversation",
+    "new chat",
+    "chats",
+    "send",
+    "stop",
+    "attach",
+    "dictate",
+    "copilot",
+    "sidebar"
+  ],
+  "exports": [
+    "ChatPane",
+    "ChatComposer",
+    "ChatsList",
+    "ChatDockContext",
+    "ago",
+    "startStep",
+    "MAX_BYTES",
+    "MAX_FILES",
+    "addFiles",
+    "filesFromTransfer",
+    "formatBytes",
+    "readFile",
+    "useDictation"
+  ],
+  "files": [
+    "index.js",
+    "chat-pane.jsx",
+    "chat-composer.jsx",
+    "chats-list.jsx",
+    "chat-context.js",
+    "chat-model.js",
+    "chat-attach.js"
+  ],
+  "requires": [],
+  "offer": { "since": "0.8.1", "why": "the desk's chat pane and message box as the app's own, for a chat of the app's own lines (agent-pane already lays it)" }
+}

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

@@ -0,0 +1,166 @@
+"use client";
+
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+
+// The composer's parts (0.8.1, D27 phase 4): files to send with the words,
+// and dictation. Both are the browser's own — nothing here reads a door. The
+// platform checks the files again (agent-app app-attachments.ts) and the
+// limits below are its. They lived in agent-pane/composer.jsx until the
+// chat-pane block (X5); that file now re-exports them from here.
+
+/** At most this many files, and this many bytes together, per message. */
+export const MAX_FILES = 4;
+export const MAX_BYTES = 3 * 1024 * 1024;
+
+export function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Add `incoming` files to `current`, within the limits.
+ *   → { files, error }  `error` is words for the member, or null
+ */
+export function addFiles(current, incoming) {
+  const files = [...current];
+  let error = null;
+  let total = files.reduce((n, f) => n + f.size, 0);
+  for (const file of incoming) {
+    if (files.length >= MAX_FILES) {
+      error = `Send at most ${MAX_FILES} files at a time.`;
+      break;
+    }
+    if (file.size === 0) {
+      error = `${file.name} is empty.`;
+      continue;
+    }
+    if (total + file.size > MAX_BYTES) {
+      error = `Files can be up to ${formatBytes(MAX_BYTES)} together here. Attach a smaller one, or attach it in the Makersclaw window.`;
+      continue;
+    }
+    total += file.size;
+    files.push(file);
+  }
+  return { files, error };
+}
+
+/** A File as the ask takes it: { name, type, data } with a base64 data URL. */
+export function readFile(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve({ name: file.name, type: file.type || "application/octet-stream", data: String(reader.result) });
+    reader.onerror = () => reject(reader.error ?? new Error("read failed"));
+    reader.readAsDataURL(file);
+  });
+}
+
+/** Files off a paste or a drop. A pasted image is named "image.png" by the
+ *  browser; stamp it so several stay apart in the thread. */
+export function filesFromTransfer(dt) {
+  if (!dt) return [];
+  const out = [];
+  for (const item of Array.from(dt.items ?? [])) {
+    if (item.kind !== "file") continue;
+    const file = item.getAsFile();
+    if (!file) continue;
+    out.push(
+      file.name === "image.png" && file.type.startsWith("image/")
+        ? new File([file], `pasted-${new Date().toISOString().replace(/[:.]/g, "-")}.png`, { type: file.type })
+        : file,
+    );
+  }
+  return out;
+}
+
+function recognitionCtor() {
+  if (typeof window === "undefined") return null;
+  return window.SpeechRecognition ?? window.webkitSpeechRecognition ?? null;
+}
+
+/**
+ * Dictation: the microphone to text through the browser's speech
+ * recognition (the desk's composer does the same). `onText(words)` hears
+ * each finished phrase. `supported` is false where the browser has none,
+ * and the pane draws no microphone. `error` says when the microphone is
+ * refused (a frame the desk has not allowed it in, or the member said no).
+ */
+export function useDictation(onText) {
+  const [supported] = useState(() => recognitionCtor() !== null);
+  const [listening, setListening] = useState(false);
+  const [interim, setInterim] = useState("");
+  const [error, setError] = useState(null);
+  const recRef = useRef(null);
+  const wantRef = useRef(false);
+  const onTextRef = useRef(onText);
+  useLayoutEffect(() => {
+    onTextRef.current = onText;
+  }, [onText]);
+
+  const stop = useCallback(() => {
+    wantRef.current = false;
+    recRef.current?.stop();
+    recRef.current = null;
+    setListening(false);
+    setInterim("");
+  }, []);
+
+  const start = useCallback(() => {
+    const Ctor = recognitionCtor();
+    if (!Ctor || recRef.current) return;
+    setError(null);
+    const rec = new Ctor();
+    rec.continuous = true;
+    rec.interimResults = true;
+    rec.lang = (typeof navigator !== "undefined" && navigator.language) || "en-US";
+    rec.onresult = (event) => {
+      let interimText = "";
+      for (let i = event.resultIndex; i < event.results.length; i += 1) {
+        const result = event.results[i];
+        const transcript = result[0]?.transcript ?? "";
+        if (result.isFinal) {
+          if (transcript.trim()) onTextRef.current(transcript.trim());
+        } else {
+          interimText += transcript;
+        }
+      }
+      setInterim(interimText);
+    };
+    rec.onend = () => {
+      recRef.current = null;
+      setInterim("");
+      if (wantRef.current) {
+        // Silence ends a recognition; while the toggle is on, listen again.
+        try {
+          rec.start();
+          recRef.current = rec;
+          return;
+        } catch {
+          wantRef.current = false;
+        }
+      }
+      setListening(false);
+    };
+    rec.onerror = (event) => {
+      if (event.error === "not-allowed" || event.error === "service-not-allowed") {
+        wantRef.current = false;
+        setListening(false);
+        setError("The microphone is not allowed here. Allow it for this site, or type instead.");
+      }
+    };
+    wantRef.current = true;
+    try {
+      rec.start();
+    } catch {
+      wantRef.current = false;
+      setError("The microphone could not start.");
+      return;
+    }
+    recRef.current = rec;
+    setListening(true);
+  }, []);
+
+  const toggle = useCallback(() => (listening ? stop() : start()), [listening, start, stop]);
+  useEffect(() => stop, [stop]);
+  return { supported, listening, interim, error, toggle, stop };
+}

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

@@ -0,0 +1,195 @@
+"use client";
+
+import { useEffect } from "react";
+import { Icon, cx } from "../../ui";
+import { filesFromTransfer, formatBytes } from "./chat-attach";
+
+// ChatComposer — the desk's message box (claw's ChatComposer, as the app
+// draws it): ONE rounded box. The words on top, full width, growing with
+// what is typed; under them a row with + (attach) at the left, and at the
+// right the microphone and a round arrow to send. While a turn runs, a round
+// stop takes the arrow's place. A quiet hint can sit under the box.
+//
+// It draws the box and nothing else: the words, the files and the dictation
+// are the pane's (so a drop anywhere on the pane, a prefilled line and a
+// sent suggestion all reach the same box).
+//
+//   value, onChange     the words (controlled)
+//   onSubmit()          Enter, or the arrow
+//   onStop()            the stop (shown while `busy` and `canStop`)
+//   onAttach(File[])    the + and a paste
+//   files, onRemoveFile(i)   what is attached, as chips inside the box
+//   busy                a turn runs: the arrow is a stop while the box is empty
+//   canStop, stopping   the stop can be pressed / has been
+//   blocked             something waits on the member: the whole box is closed
+//   sending, encoding   the arrow waits
+//   dictation           useDictation()'s object (no microphone where the
+//                       browser has none)
+//   placeholder, label  the box's words, and its name for a screen reader
+//   hint                a quiet line under the box
+//   textareaRef         the pane's handle on the box (focus, caret)
+
+const ROUND = "inline-flex size-8 shrink-0 items-center justify-center outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-card disabled:cursor-not-allowed disabled:opacity-40";
+
+export function ChatComposer({
+  value,
+  onChange,
+  onSubmit,
+  onStop,
+  onAttach,
+  files = [],
+  onRemoveFile,
+  busy = false,
+  canStop = false,
+  stopping = false,
+  blocked = false,
+  sending = false,
+  encoding = false,
+  dictation,
+  placeholder,
+  label = "Message",
+  hint,
+  textareaRef,
+  fileInputRef,
+  className,
+}) {
+  const empty = !value.trim() && files.length === 0;
+  const stopShown = busy && canStop && empty;
+
+  // The box grows with its words, up to its max-h; a hidden box measures 0
+  // and is left natural (pinning 0px would stick).
+  useEffect(() => {
+    const el = textareaRef?.current;
+    if (!el) return;
+    el.style.height = "auto";
+    if (el.scrollHeight > 0) el.style.height = `${el.scrollHeight}px`;
+  }, [value, textareaRef]);
+
+  return (
+    <div className={cx("grid min-w-0 gap-1.5", className)}>
+      <form
+        data-chat-composer=""
+        className="grid min-w-0 gap-2 rounded-xl border border-border bg-card px-3 pb-2 pt-2.5 text-card-foreground shadow-sm transition-colors focus-within:border-ring motion-reduce:transition-none"
+        onSubmit={(e) => {
+          e.preventDefault();
+          onSubmit?.();
+        }}
+      >
+        {files.length > 0 ? (
+          <ul aria-label="Files to send" className="flex min-w-0 flex-wrap gap-1.5">
+            {files.map((f, i) => (
+              <li key={`${f.name}-${i}`} className="inline-flex max-w-full min-w-0 items-center gap-1.5 rounded-md border border-border py-0.5 pl-2 pr-1 text-xs">
+                <Icon name="paperclip" size={12} className="shrink-0 text-muted-foreground" />
+                <span className="min-w-0 truncate">{f.name}</span>
+                <span className="shrink-0 text-muted-foreground">{formatBytes(f.size)}</span>
+                <button
+                  type="button"
+                  aria-label={`Remove ${f.name}`}
+                  title={`Remove ${f.name}`}
+                  onClick={() => onRemoveFile?.(i)}
+                  className="inline-flex size-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground outline-none hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+                >
+                  <Icon name="x" size={12} />
+                </button>
+              </li>
+            ))}
+          </ul>
+        ) : null}
+
+        <textarea
+          ref={textareaRef}
+          aria-label={label}
+          rows={1}
+          placeholder={placeholder}
+          value={value}
+          disabled={blocked}
+          onChange={(e) => onChange?.(e.target.value)}
+          onPaste={(e) => {
+            const pasted = filesFromTransfer(e.clipboardData);
+            if (pasted.length > 0) {
+              e.preventDefault();
+              onAttach?.(pasted);
+            }
+          }}
+          onKeyDown={(e) => {
+            if (e.key === "Enter" && !e.shiftKey && !e.nativeEvent.isComposing) {
+              e.preventDefault();
+              onSubmit?.();
+            }
+          }}
+          className="block max-h-40 min-h-6 w-full min-w-0 resize-none overflow-y-auto bg-transparent text-sm leading-6 text-foreground outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed"
+        />
+
+        {dictation?.listening ? (
+          <p role="status" className="flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground">
+            <span aria-hidden="true" className="size-1.5 shrink-0 animate-pulse rounded-full bg-destructive motion-reduce:animate-none" />
+            Listening…
+            {dictation.interim ? <span className="min-w-0 truncate italic">{dictation.interim}</span> : null}
+          </p>
+        ) : null}
+
+        <div className="flex items-center gap-1.5">
+          <input
+            ref={fileInputRef}
+            type="file"
+            multiple
+            hidden
+            aria-hidden="true"
+            tabIndex={-1}
+            onChange={(e) => {
+              onAttach?.(Array.from(e.target.files ?? []));
+              e.target.value = "";
+            }}
+          />
+          <button
+            type="button"
+            aria-label="Attach a file"
+            title="Attach a file"
+            disabled={blocked || encoding}
+            onClick={() => fileInputRef?.current?.click()}
+            className={cx(ROUND, "rounded-lg border border-border text-muted-foreground hover:bg-accent hover:text-foreground")}
+          >
+            <Icon name="plus" size={16} />
+          </button>
+          <span className="flex-1" />
+          {dictation?.supported ? (
+            <button
+              type="button"
+              aria-label={dictation.listening ? "Stop dictating" : "Dictate"}
+              title={dictation.listening ? "Stop dictating" : "Dictate"}
+              aria-pressed={dictation.listening}
+              disabled={blocked}
+              onClick={dictation.toggle}
+              className={cx(ROUND, "rounded-lg hover:bg-accent", dictation.listening ? "text-destructive" : "text-muted-foreground hover:text-foreground")}
+            >
+              <Icon name="mic" size={16} />
+            </button>
+          ) : null}
+          {stopShown ? (
+            <button
+              type="button"
+              aria-label={stopping ? "Stopping…" : "Stop"}
+              title={stopping ? "Stopping…" : "Stop"}
+              disabled={stopping}
+              onClick={onStop}
+              className={cx(ROUND, "rounded-full bg-primary text-primary-foreground hover:opacity-90")}
+            >
+              <Icon name="stop" size={12} />
+            </button>
+          ) : (
+            <button
+              type="submit"
+              aria-label="Send"
+              title="Send"
+              disabled={blocked || encoding || sending || empty}
+              className={cx(ROUND, "rounded-full bg-primary text-primary-foreground hover:opacity-90")}
+            >
+              <Icon name="arrow-up" size={16} />
+            </button>
+          )}
+        </div>
+      </form>
+      {hint ? <p className="px-1 text-xs text-muted-foreground">{hint}</p> : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,17 @@
+"use client";
+
+import { createContext } from "react";
+
+// What a ChatPane placed inside an AgentDock (blocks/agent-dock) is told:
+//
+//   close   folds the dock (the head's close, when the app gave no onClose)
+//   mode    "column" or "sheet"
+//   start   the starting line a "have the agent do it" button asked for
+//           (openAgent({ ask }), blocks/agent-dock), or null:
+//           { ask, send, fresh, nonce }
+//   taken   (nonce) => void — the pane took it; the dock drops it
+//
+// Null outside a dock, where nothing changes. It lives here, beside the
+// pane, so the pane never imports the dock; agent-pane re-exports it as
+// AgentDockContext, which is the name the dock and apps have always used.
+export const ChatDockContext = createContext(null);

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

@@ -0,0 +1,43 @@
+// chat-pane: the rules that need no React, as plain functions (they work on
+// the server too, and test/chat-pane.test.mjs holds them).
+
+/** "now", "5m", "3h", "2d", else the date: a past chat's age. */
+export function ago(iso, now = Date.now()) {
+  const t = iso ? Date.parse(iso) : Number.NaN;
+  if (!Number.isFinite(t)) return "";
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 60) return "now";
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  if (s < 7 * 86400) return `${Math.floor(s / 86400)}d`;
+  return new Date(t).toLocaleDateString(undefined, { month: "short", day: "numeric" });
+}
+
+/**
+ * What the pane does next with a starting line the dock holds (openAgent in
+ * blocks/agent-dock). A "have the agent do it" button does not open a form:
+ * it hands the agent its first line, and the agent asks only for what it is
+ * missing, in the chat.
+ *
+ *   start      { ask, send, fresh, nonce } or null
+ *   handled    the nonce this pane already took, or null
+ *   sessionId  the conversation open now (null: a fresh one)
+ *   blocked    the box is closed (something waits on the member)
+ *   canNew     the chat can start a new conversation (chat.newChat)
+ *   newed      newChat was already called for this nonce
+ *
+ * → "none"      nothing to do
+ *   "new-chat"  start a fresh conversation first (fresh, and one is open)
+ *   "wait"      the fresh conversation has not replaced the old one yet
+ *   "send"      send the line as the member's first words
+ *   "prefill"   put the line in the box for the member to finish (send is
+ *               false, or the box is closed and cannot send)
+ */
+export function startStep({ start, handled = null, sessionId = null, blocked = false, canNew = true, newed = false } = {}) {
+  if (!start || !String(start.ask ?? "").trim()) return "none";
+  if (handled !== null && handled === start.nonce) return "none";
+  if (start.send === false || blocked) return "prefill";
+  const fresh = start.fresh !== false && canNew;
+  if (fresh && sessionId) return newed ? "wait" : "new-chat";
+  return "send";
+}