@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/workbench/assistant.tsx

@@ -0,0 +1,516 @@
+// The ASSISTANT of the workbench: an island over it where the person says what they want, and
+// the platform's assistant does it with the editor's own content tools — as this person, on this
+// site. Where it floats depends on the page: at the bottom over Home and the lists, over the tree
+// in the editor — never a column taking the room. The workbench follows it: a block it is about to
+// change is selected in the canvas, a draft it changed is read again into every canvas holding it
+// (unless the person has unsaved work there) with the block it touched selected, a draft it opens,
+// makes or changes elsewhere is opened, the lists are read anew. While it works the workbench is
+// frozen: edits made under it would only collide with its own. What the person sees — the page,
+// the draft, the block selected — goes with every message.
+import { useComponent, useDi } from '@mosetta/react';
+import { DI_CONTAINER_TOKEN } from '@mosetta/di';
+import { editingSessionHubOf, ensureEditingSession } from '@mosetta/content';
+import type { ContentKind, EditingSession, ILoadedDraft, IPageDoc } from '@mosetta/content';
+import { fullServerTileId } from '@mosetta/server-action/core';
+import { ensureServerActionClient, SERVER_DATA_MANAGER } from '@mosetta/server-action/client';
+import { useDiOptional, useRoute } from '@mosetta/react';
+import { ROUTER_TOKEN } from '@mosetta/runtime/client';
+import { ReactNode, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { WORKSPACE_TOKEN } from './workspace';
+import { basePathOf, pathOfView } from './workbenchAddress';
+import type { IOpenDoc } from './workbenchAddress';
+import {
+  ASSISTANT_PATH,
+  changesContent,
+  chatEvents,
+  chatReduce,
+  draftTouched,
+  EMPTY_CHAT,
+  IChatState,
+  IDraftTouched,
+  nodeOfCall,
+  TChatItem,
+  touchedNodes,
+  withUserMessage,
+} from './assistantChat';
+import { useDictation } from './dictation';
+import './assistant.css';
+
+/** the conversation, kept for this tab of this site — a reload keeps it, another tab starts its own */
+const storageKey = (): string => `mosetta-assistant:${window.location.host}`;
+
+function readChat(): IChatState {
+  try {
+    const raw = window.sessionStorage.getItem(storageKey());
+    const held = raw ? (JSON.parse(raw) as Partial<IChatState>) : null;
+    if (held && Array.isArray(held.items) && Array.isArray(held.history)) return { items: held.items, history: held.history, cost: Number(held.cost) || 0 };
+  } catch { /* storage denied, or not ours */ }
+  return EMPTY_CHAT;
+}
+
+function writeChat(state: IChatState): void {
+  try {
+    window.sessionStorage.setItem(storageKey(), JSON.stringify(state));
+  } catch {
+    // too large for the tab's storage, or denied: the conversation lives for the page only
+  }
+}
+
+// the little of markdown a model writes in a chat: [words](link), a bare link, **bold**, `code`
+const MARK_RE = /\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)|(https?:\/\/[^\s)<>]+)|\*\*([^*\n]+)\*\*|`([^`\n]+)`/g;
+
+/** a link as words: the host and the path, cut short — a signed preview link is long */
+function shortLink(href: string): string {
+  try {
+    const url = new URL(href);
+    const shown = `${url.host}${url.pathname === '/' ? '' : url.pathname}`;
+    return `${shown.length > 48 ? `${shown.slice(0, 47)}…` : shown}${url.search ? ' ↗' : ''}`;
+  } catch {
+    return href;
+  }
+}
+
+/** the assistant's words: paragraphs as written, links short, a little markdown understood */
+function Words({ text }: { text: string }) {
+  const parts: ReactNode[] = [];
+  let at = 0;
+  for (const match of text.matchAll(MARK_RE)) {
+    if (match.index > at) parts.push(text.slice(at, match.index));
+    const [whole, label, labelled, bare, bold, code] = match;
+    const key = match.index;
+    if (labelled) {
+      parts.push(<a key={key}
+                    href={labelled}
+                    target="_blank"
+                    rel="noreferrer">{label}</a>);
+    } else if (bare) {
+      parts.push(<a key={key}
+                    href={bare}
+                    target="_blank"
+                    rel="noreferrer"
+                    title={bare}>{shortLink(bare)}</a>);
+    } else if (bold) parts.push(<strong key={key}>{bold}</strong>);
+    else if (code) parts.push(<code key={key}>{code}</code>);
+    else parts.push(whole);
+    at = match.index + whole.length;
+  }
+  if (at < text.length) parts.push(text.slice(at));
+  return <>{parts}</>;
+}
+
+const ToolMark: Record<'running' | 'ok' | 'failed', ReactNode> = {
+  running: <span className="assistant__spinner"
+                 aria-label="working" />,
+  ok: <span aria-label="done">✓</span>,
+  failed: <span aria-label="failed">!</span>,
+};
+
+function Item({ item }: { item: TChatItem }) {
+  switch (item.kind) {
+    case 'user':
+      return <div className="assistant__user"
+                  data-test-id="assistant-user">{item.text}</div>;
+    case 'assistant':
+      return <div className="assistant__reply"
+                  data-test-id="assistant-reply"><Words text={item.text} /></div>;
+    case 'tool':
+      return (
+        <>
+          <details className={`assistant__tool assistant__tool--${item.status}`}
+                   data-test-id="assistant-tool"
+                   data-tool={item.name}
+                   data-status={item.status}>
+            <summary>
+              <span className="assistant__tool-mark">{ToolMark[item.status]}</span>
+              <span className="assistant__tool-summary">{item.summary}</span>
+            </summary>
+            {item.result ? <pre className="assistant__tool-result">{item.result}</pre> : null}
+          </details>
+          {/* what the assistant looked at, as it saw it */}
+          {item.pictures?.length ? (
+            <div className="assistant__pictures"
+                 data-test-id="assistant-pictures">
+              {item.pictures.map((picture) => (
+                <a key={picture.url}
+                   href={picture.url}
+                   target="_blank"
+                   rel="noreferrer"
+                   data-tooltip={picture.caption}>
+                  <img src={picture.url}
+                       alt={picture.caption}
+                       loading="lazy" />
+                </a>
+              ))}
+            </div>
+          ) : null}
+        </>
+      );
+    case 'error':
+      return <div className="assistant__error"
+                  data-test-id="assistant-error">{item.text}</div>;
+    default:
+      return null;
+  }
+}
+
+const SUGGESTIONS = [
+  'What pages does this site have?',
+  'Make a new page /about with a heading and a short text about us',
+  'Copy the post at https://… into a new blog page',
+];
+
+const MicIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <rect x="5.5"
+          y="1.8"
+          width="5"
+          height="8.4"
+          rx="2.5"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.4" />
+    <path d="M3.2 7.6a4.8 4.8 0 0 0 9.6 0M8 12.4v2"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.4"
+          strokeLinecap="round" />
+  </svg>
+);
+
+const SendIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <path d="M8 13V3.5M3.8 7.4L8 3.2l4.2 4.2"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.7"
+          strokeLinecap="round"
+          strokeLinejoin="round" />
+  </svg>
+);
+
+const StopIcon = (
+  <svg viewBox="0 0 16 16"
+       aria-hidden="true">
+    <rect x="4.5"
+          y="4.5"
+          width="7"
+          height="7"
+          rx="1.2"
+          fill="currentColor" />
+  </svg>
+);
+
+/** where the island floats: at the bottom over Home and the lists, over the tree in the editor */
+export type TAssistantPlacement = 'bottom' | 'tree';
+
+export interface IAssistantPanelProps {
+  readonly placement: TAssistantPlacement;
+  /** the platform writes dictation out (any language, no switch); else the browser recognizes it */
+  readonly transcription: boolean;
+  readonly onClose: () => void;
+  /** the workbench freezes while the assistant works */
+  readonly onWorking: (working: boolean) => void;
+}
+
+const INPUT_HEIGHT_MAX = 168;
+
+/** a recording's length as a clock: 0:07, 1:42 */
+const clock = (seconds: number): string => `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
+
+export function AssistantPanel({ placement, transcription, onClose, onWorking }: IAssistantPanelProps) {
+  const di = useDi(DI_CONTAINER_TOKEN);
+  const workspace = useDiOptional(WORKSPACE_TOKEN);
+  const router = useDiOptional(ROUTER_TOKEN);
+  const route = useRoute();
+  // the content module of THIS editor — where a changed draft is read again
+  const reference = useComponent().reference;
+  const contentId = fullServerTileId({ namespace: reference.namespace, version: reference.version, name: 'content' });
+  const [chat, setChat] = useState<IChatState>(readChat);
+  const [draft, setDraft] = useState('');
+  const draftRef = useRef(draft);
+  draftRef.current = draft;
+  const [working, setWorking] = useState(false);
+  // over Home and the lists the island folds to its input when the person wants the page back
+  const [folded, setFolded] = useState(false);
+  const abort = useRef<AbortController | null>(null);
+  const list = useRef<HTMLDivElement>(null);
+  const input = useRef<HTMLTextAreaElement>(null);
+  const dictation = useDictation(setDraft, () => draftRef.current, transcription);
+  useEffect(() => writeChat(chat), [chat]);
+  useEffect(() => {
+    list.current?.scrollTo({ top: list.current.scrollHeight });
+  }, [chat.items, folded]);
+  useEffect(() => onWorking(working), [working, onWorking]);
+  // the field grows with what is written, up to a few lines — never dragged
+  useLayoutEffect(() => {
+    const field = input.current;
+    if (!field) return;
+    field.style.height = 'auto';
+    field.style.height = `${Math.min(field.scrollHeight, INPUT_HEIGHT_MAX)}px`;
+  }, [draft]);
+
+  /** the canvases holding a draft: the workspace's tabs, each with its own session in the hub */
+  const sessionsOn = useCallback((kind: ContentKind, name: string, draftId: string): EditingSession[] => {
+    const hub = editingSessionHubOf(di);
+    const tabs = workspace?.snapshot().tabs ?? [];
+    const sessions: EditingSession[] = hub
+      ? tabs.map((tab) => hub.peek(tab.id)).filter((session): session is EditingSession => session !== null)
+      : [ensureEditingSession(di)];
+    return sessions.filter((session) => {
+      const state = session.snapshot();
+      return state.kind === kind && state.pageName === name && state.draftId === draftId;
+    });
+  }, [di, workspace]);
+
+  /** a draft the assistant changed, read again into every canvas that holds it unchanged — false: none does */
+  const reload = useCallback(async (touched: IDraftTouched, select: string | null): Promise<boolean> => {
+    const holding = sessionsOn(touched.kind, touched.name, touched.draftId);
+    if (!holding.length) return false;
+    const clean = holding.filter((session) => !session.snapshot().dirty);
+    if (!clean.length) return true;
+    const res = await fetch(`/api/server-action/${contentId}/loadPageDraft`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({ name: touched.name, draftId: touched.draftId, kind: touched.kind }),
+    });
+    const body = (await res.json().catch(() => null)) as { ok?: boolean; draft?: ILoadedDraft<IPageDoc> } | null;
+    if (!body?.ok || !body.draft) return true;
+    for (const session of clean) {
+      session.openPage(touched.name, touched.draftId, body.draft.doc, touched.kind);
+      if (select) session.selectNode(select);
+    }
+    return true;
+  }, [contentId, sessionsOn]);
+
+  /**
+   * A draft opened in front of the person: as a tab where the editor is up, else by a move to the
+   * editor's page (Home and the lists have no tabs) — the way the pages list opens one
+   */
+  const openDraft = useCallback((doc: IOpenDoc): void => {
+    if (workspace) {
+      workspace.open(doc);
+      return;
+    }
+    if (!route || !router?.active) return;
+    const { pathname, version } = pathOfView(basePathOf(route.pattern ?? null, route.path ?? '/'), { view: 'editor', ...doc });
+    const query = new URLSearchParams(version).toString();
+    void router.navigate(query ? `${pathname}?${query}` : pathname);
+  }, [route, router, workspace]);
+
+  /** the block a tool is about to look at or change, selected where its draft is open */
+  const aboutToTouch = (name: string, args: unknown): void => {
+    const node = nodeOfCall(name, args);
+    const a = args as { name?: unknown; draftId?: unknown; kind?: unknown };
+    if (!node || typeof a.name !== 'string' || typeof a.draftId !== 'string') return;
+    for (const session of sessionsOn(a.kind === 'prefabs' ? 'prefabs' : 'pages', a.name, a.draftId)) session.selectNode(node);
+  };
+
+  /** a draft a tool changed, in front of the person: opened when new, read again where open, opened where not */
+  const follow = async (touched: IDraftTouched | null, result: string): Promise<void> => {
+    if (!touched) return;
+    const doc = { kind: touched.kind, page: touched.name, draftId: touched.draftId };
+    if (touched.fresh) {
+      openDraft(doc);
+      return;
+    }
+    const shown = await reload(touched, touchedNodes(result)[0] ?? null);
+    if (!shown) openDraft(doc);
+  };
+
+  /** what the person looks at — the page and the block selected in the canvas in front */
+  const contextNow = (): Record<string, unknown> => {
+    const active = editingSessionHubOf(di)?.active.snapshot();
+    return {
+      path: `${window.location.pathname}${window.location.search}`,
+      ...(active?.pageName ? {
+        selection: {
+          kind: active.kind,
+          page: active.pageName,
+          ...(active.draftId ? { draftId: active.draftId } : {}),
+          ...(active.selectedNodeId ? { node: active.selectedNodeId } : {}),
+        },
+      } : {}),
+    };
+  };
+
+  const send = useCallback(async (typed: string): Promise<void> => {
+    if (working) return;
+    // sent while dictating: what is being said goes with it
+    const message = (dictation.listening || dictation.busy ? await dictation.finish() : typed).trim();
+    if (!message) return;
+    setDraft('');
+    setFolded(false);
+    setWorking(true);
+    const controller = new AbortController();
+    abort.current = controller;
+    let state = withUserMessage(chat, message);
+    setChat(state);
+    const calls = new Map<string, { name: string; args: unknown }>();
+    let changed = false;
+    try {
+      const res = await fetch(ASSISTANT_PATH, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'text/event-stream' },
+        body: JSON.stringify({ history: chat.history, input: { text: message, context: contextNow() } }),
+        signal: controller.signal,
+      });
+      if (!res.ok || !res.body) {
+        const failure = (await res.json().catch(() => null)) as { error?: { message?: string } } | null;
+        state = chatReduce(state, { type: 'error', message: failure?.error?.message ?? `the assistant answered ${res.status}` });
+        setChat(state);
+        return;
+      }
+      for await (const event of chatEvents(res.body)) {
+        state = chatReduce(state, event);
+        setChat(state);
+        if (event.type === 'tool') {
+          calls.set(event.id, { name: event.name, args: event.args });
+          aboutToTouch(event.name, event.args);
+        }
+        if (event.type === 'tool_result' && event.ok && changesContent(event.name)) {
+          changed = true;
+          const call = calls.get(event.id);
+          await follow(call ? draftTouched(call.name, call.args, event.text) : null, event.text);
+        }
+      }
+    } catch (e) {
+      if (!controller.signal.aborted) {
+        state = chatReduce(state, { type: 'error', message: `the conversation broke off: ${(e as Error).message}` });
+        setChat(state);
+      }
+    } finally {
+      abort.current = null;
+      setWorking(false);
+      // the lists and the pages panel read the site anew
+      if (changed) {
+        ensureServerActionClient(di);
+        di.getByToken(SERVER_DATA_MANAGER).invalidate(['pages']);
+      }
+    }
+  }, [chat, di, dictation, openDraft, reload, sessionsOn, working]);
+
+  const startOver = (): void => {
+    if (working) return;
+    setChat(EMPTY_CHAT);
+  };
+
+  const listShown = !(placement === 'bottom' && folded);
+  return (
+    <aside className={`assistant assistant--${placement}${listShown ? '' : ' assistant--folded'}`}
+           data-test-id="assistant-panel"
+           data-placement={placement}
+           data-working={working || undefined}>
+      <div className="assistant__head">
+        <span className="assistant__title">Assistant</span>
+        {chat.cost > 0 ? <span className="assistant__cost"
+                               data-tooltip="What this conversation has cost">${chat.cost.toFixed(3)}</span> : null}
+        <button type="button"
+                className="assistant__head-button"
+                data-test-id="assistant-new"
+                disabled={working || !chat.items.length}
+                onClick={startOver}>New chat</button>
+        {placement === 'bottom' ? (
+          <button type="button"
+                  className="assistant__head-button"
+                  data-test-id="assistant-fold"
+                  aria-label={folded ? 'Show the conversation' : 'Fold to the input'}
+                  data-tooltip={folded ? 'Show the conversation' : 'Fold to the input'}
+                  onClick={() => setFolded(!folded)}>{folded ? '▴' : '▾'}</button>
+        ) : null}
+        <button type="button"
+                className="assistant__head-button"
+                data-test-id="assistant-close"
+                aria-label="Close the assistant"
+                data-tooltip="Close (⌘J opens it again)"
+                onClick={onClose}>✕</button>
+      </div>
+      {listShown ? (
+        <div className="assistant__list"
+             ref={list}>
+          {chat.items.length ? chat.items.map((item, i) => <Item key={i}
+                                                                 item={item} />) : (
+            <div className="assistant__empty">
+              <p>Ask for what you want on the site — the assistant builds it in a draft you can see here, and publishes only when you say so.</p>
+              {SUGGESTIONS.map((suggestion) => (
+                <button key={suggestion}
+                        type="button"
+                        className="assistant__suggestion"
+                        onClick={() => {
+                          setDraft(suggestion);
+                          input.current?.focus();
+                        }}>{suggestion}</button>
+              ))}
+            </div>
+          )}
+          {working && chat.items[chat.items.length - 1]?.kind === 'user' ? <div className="assistant__thinking">Thinking…</div> : null}
+        </div>
+      ) : null}
+      <form className="assistant__composer"
+            onSubmit={(e) => {
+              e.preventDefault();
+              void send(draft);
+            }}>
+        <div className={`assistant__field${dictation.listening ? ' assistant__field--listening' : ''}`}>
+          <textarea className="assistant__input"
+                    data-test-id="assistant-input"
+                    ref={input}
+                    value={draft}
+                    rows={1}
+                    placeholder={working ? 'The assistant is working…' : dictation.listening ? 'Listening…' : dictation.busy ? 'Writing down what you said…' : 'What should change on the site?'}
+                    disabled={working}
+                    onChange={(e) => setDraft(e.target.value)}
+                    onKeyDown={(e) => {
+                      if (e.key === 'Enter' && !e.shiftKey && !e.nativeEvent.isComposing) {
+                        e.preventDefault();
+                        void send(draft);
+                      }
+                    }} />
+          <div className="assistant__actions">
+            {dictation.supported && !working ? (
+              <>
+                {dictation.listening && !dictation.lang ? (
+                  <span className="assistant__clock"
+                        data-test-id="assistant-dictation-clock">{clock(dictation.seconds)}</span>
+                ) : null}
+                {dictation.lang ? (
+                  <button type="button"
+                          className="assistant__lang"
+                          data-test-id="assistant-dictation-lang"
+                          data-tooltip="The language you dictate in"
+                          onClick={dictation.nextLang}>{dictation.lang.split('-')[0].toUpperCase()}</button>
+                ) : null}
+                <button type="button"
+                        className={`assistant__icon${dictation.listening ? ' assistant__icon--on' : ''}`}
+                        data-test-id="assistant-dictate"
+                        data-busy={dictation.busy || undefined}
+                        aria-pressed={dictation.listening}
+                        aria-label={dictation.listening ? 'Stop dictating' : dictation.busy ? 'Writing down what you said' : 'Dictate'}
+                        data-tooltip={dictation.listening ? 'Stop — the words appear in a moment'
+                          : dictation.lang ? 'Dictate — speak, the words appear here' : 'Dictate in any language — press again when done'}
+                        disabled={dictation.busy}
+                        onClick={dictation.toggle}>{dictation.busy ? <span className="assistant__spinner" /> : MicIcon}</button>
+              </>
+            ) : null}
+            {working ? (
+              <button type="button"
+                      className="assistant__icon assistant__icon--send"
+                      data-test-id="assistant-stop"
+                      aria-label="Stop"
+                      data-tooltip="Stop"
+                      onClick={() => abort.current?.abort()}>{StopIcon}</button>
+            ) : (
+              <button type="submit"
+                      className="assistant__icon assistant__icon--send"
+                      data-test-id="assistant-send"
+                      aria-label="Send"
+                      disabled={!draft.trim() && !dictation.listening && !dictation.busy}>{SendIcon}</button>
+            )}
+          </div>
+        </div>
+        {dictation.problem ? <div className="assistant__hint">{dictation.problem}</div> : null}
+      </form>
+    </aside>
+  );
+}

package/tiles/workbench/assistantChat.ts

@@ -0,0 +1,165 @@
+// The ASSISTANT's conversation as the workbench holds it — no react here: what the panel shows
+// (the person's words, the assistant's, each tool it used and how that went), the history the
+// server gets back whole with the next message, and how one event of the server's stream changes
+// both. The history only grows: every message is kept exactly as the server sent it.
+import type { ContentKind } from '@mosetta/content';
+
+export const ASSISTANT_PATH = '/__mosetta__/assistant';
+
+/** a picture a tool showed the assistant (a screenshot): its address and what it is */
+export interface IPicture {
+  readonly url: string;
+  readonly caption: string;
+}
+
+export type TChatItem
+  = | { readonly kind: 'user'; readonly text: string }
+  | { readonly kind: 'assistant'; readonly text: string }
+  | { readonly kind: 'tool'; readonly id: string; readonly name: string; readonly summary: string; readonly status: 'running' | 'ok' | 'failed'; readonly result?: string; readonly pictures?: readonly IPicture[] }
+  | { readonly kind: 'error'; readonly text: string };
+
+export interface IChatState {
+  readonly items: readonly TChatItem[];
+  /** the messages as the server sent them — sent back whole with the next one */
+  readonly history: readonly unknown[];
+  /** what the conversation has cost so far, in dollars */
+  readonly cost: number;
+}
+
+export const EMPTY_CHAT: IChatState = { items: [], history: [], cost: 0 };
+
+export type TChatEvent
+  = | { readonly type: 'message'; readonly message: { readonly role: string } }
+  | { readonly type: 'text'; readonly delta: string }
+  | { readonly type: 'tool'; readonly id: string; readonly name: string; readonly args: unknown }
+  | { readonly type: 'tool_result'; readonly id: string; readonly name: string; readonly ok: boolean; readonly text: string; readonly pictures?: readonly IPicture[] }
+  | { readonly type: 'done'; readonly usage: { readonly cost?: number } }
+  | { readonly type: 'error'; readonly message: string };
+
+const isObject = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** an address in a few words: its host and path */
+function shortUrl(href: string): string {
+  try {
+    const url = new URL(href);
+    const shown = `${url.host}${url.pathname === '/' ? '' : url.pathname}`;
+    return shown.length > 60 ? `${shown.slice(0, 59)}…` : shown;
+  } catch {
+    return href.slice(0, 60);
+  }
+}
+
+/** a tool call in a few words: what it acts on */
+export function toolSummary(name: string, args: unknown): string {
+  const a = isObject(args) ? args : {};
+  const what = [typeof a.url === 'string' ? shortUrl(a.url) : null, a.name, a.node, a.pattern, a.device === 'mobile' ? 'mobile' : null]
+    .filter((part): part is string => typeof part === 'string').join(' · ');
+  const ops = Array.isArray(a.ops) ? ` — ${a.ops.length} ${a.ops.length === 1 ? 'change' : 'changes'}` : '';
+  return `${name.replace(/_/g, ' ')}${what ? ` ${what}` : ''}${ops}`;
+}
+
+/** the conversation after one event of the stream */
+export function chatReduce(state: IChatState, event: TChatEvent): IChatState {
+  switch (event.type) {
+    case 'message':
+      return { ...state, history: [...state.history, event.message] };
+    case 'text': {
+      const last = state.items[state.items.length - 1];
+      if (last?.kind === 'assistant') return { ...state, items: [...state.items.slice(0, -1), { kind: 'assistant', text: last.text + event.delta }] };
+      return { ...state, items: [...state.items, { kind: 'assistant', text: event.delta }] };
+    }
+    case 'tool':
+      return { ...state, items: [...state.items, { kind: 'tool', id: event.id, name: event.name, summary: toolSummary(event.name, event.args), status: 'running' }] };
+    case 'tool_result':
+      return {
+        ...state,
+        items: state.items.map((item) => (item.kind === 'tool' && item.id === event.id
+          ? { ...item, status: event.ok ? 'ok' : 'failed', result: event.text, ...(event.pictures?.length ? { pictures: event.pictures } : {}) }
+          : item)),
+      };
+    case 'done':
+      return { ...state, cost: state.cost + (typeof event.usage.cost === 'number' ? event.usage.cost : 0) };
+    case 'error':
+      return { ...state, items: [...state.items, { kind: 'error', text: event.message }] };
+    default:
+      return state;
+  }
+}
+
+/** the person's message, shown at once — the server's copy of it joins the history when it comes */
+export const withUserMessage = (state: IChatState, text: string): IChatState => ({ ...state, items: [...state.items, { kind: 'user', text }] });
+
+/** the events of a server's stream, as they come */
+export async function* chatEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<TChatEvent> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) return;
+    buffer += decoder.decode(value, { stream: true });
+    for (let at = buffer.indexOf('\n\n'); at >= 0; at = buffer.indexOf('\n\n')) {
+      const block = buffer.slice(0, at);
+      buffer = buffer.slice(at + 2);
+      const data = block.split('\n').filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trim()).join('');
+      if (!data) continue;
+      try {
+        yield JSON.parse(data) as TChatEvent;
+      } catch { /* not an event */ }
+    }
+  }
+}
+
+/** what a finished tool call changed — a draft to reload where it is open, or to open */
+export interface IDraftTouched {
+  readonly kind: ContentKind;
+  readonly name: string;
+  readonly draftId: string;
+  /** a draft the assistant opened or made: the workbench opens it */
+  readonly fresh: boolean;
+}
+
+const CHANGING = new Set(['edit_draft', 'save_draft', 'create_draft', 'create_page', 'publish_page', 'discard_draft']);
+
+/** whether a tool changes the site's content — lists are read anew after it */
+export const changesContent = (name: string): boolean => CHANGING.has(name);
+
+/** the draft a successful tool call touched, from its arguments and its answer */
+export function draftTouched(name: string, args: unknown, result: string): IDraftTouched | null {
+  const a = isObject(args) ? args : {};
+  const kind: ContentKind = a.kind === 'prefabs' ? 'prefabs' : 'pages';
+  if (typeof a.name !== 'string') return null;
+  if (name === 'edit_draft' || name === 'save_draft') {
+    return typeof a.draftId === 'string' ? { kind, name: a.name, draftId: a.draftId, fresh: false } : null;
+  }
+  if (name === 'create_draft' || name === 'create_page') {
+    // the answer may arrive cut for showing — the id comes first in it
+    const draftId = /"draftId":\s*"([a-z0-9-]+)"/.exec(result)?.[1];
+    return draftId ? { kind: name === 'create_page' ? 'pages' : kind, name: a.name, draftId, fresh: true } : null;
+  }
+  return null;
+}
+
+/**
+ * The blocks an edit touched and still has — what the canvas shows selected once the edit lands:
+ * read off the edit's own account (`set <id> › …`, `insert <id> into …`, `move <id> into …`).
+ */
+export function touchedNodes(result: string): string[] {
+  const ids: string[] = [];
+  for (const m of result.matchAll(/"(?:set|unset|insert|move) ([^\s"›]+)/g)) if (!ids.includes(m[1])) ids.push(m[1]);
+  return ids;
+}
+
+/** the block a tool is about to look at or change — selected in the canvas while it works */
+export function nodeOfCall(name: string, args: unknown): string | null {
+  const a = isObject(args) ? args : {};
+  if (name === 'read_node' && typeof a.node === 'string') return a.node;
+  if (name === 'edit_draft' && Array.isArray(a.ops)) {
+    for (const op of a.ops) {
+      if (!isObject(op)) continue;
+      if (typeof op.node === 'string' && op.op !== 'remove') return op.node;
+      if (typeof op.parent === 'string') return op.parent;
+    }
+  }
+  return null;
+}