@theoremjs/react 0.3.4-next.389.gecc7333 → 0.3.4-next.401.gec4c582

package/README.md

@@ -180,6 +180,7 @@ The server keeps the conversation in its `conversationStore`. The browser never
 
 - when the message reaches the server
 - each time the server saves the reply, while the reply runs and when it ends
+- with `undefined` when the server can no longer open the ref you resumed. The chat starts a new conversation with no error, so forget the ref.
 
 Keep the latest ref. To resume the conversation, pass it as `conversation`. The component reads this value once, when it mounts. It then draws the conversation as the server keeps it, including a reply that waits for a gate.
 
@@ -187,7 +188,7 @@ Keep the latest ref. To resume the conversation, pass it as `conversation`. The
 <TheoremChat
   endpoint="/api/theorem"
   conversation={savedRef}
-  onConversationChange={(ref) => saveRef(ref)}
+  onConversationChange={(ref) => (ref ? saveRef(ref) : forgetRef())}
 />
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/react",
-  "version": "0.3.4-next.389.gecc7333",
+  "version": "0.3.4-next.401.gec4c582",
   "description": "React bindings for Theorem: headless hooks + transport, an Astryx chat UI, and a Web-standard server handler.",
   "license": "MIT",
   "type": "module",
@@ -60,8 +60,8 @@
     "@stylexjs/stylex": "0.19.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@theoremjs/agents": "^0.3.4-next.389.gecc7333",
-    "@theoremjs/web": "^0.3.4-next.389.gecc7333"
+    "@theoremjs/agents": "^0.3.4-next.401.gec4c582",
+    "@theoremjs/web": "^0.3.4-next.401.gec4c582"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {

package/ui/ChatTranscript.js

@@ -121,17 +121,91 @@ function CopyAndTime(props) {
     const time = _jsx(MessageTime, { at: props.at });
     return (_jsxs(HStack, { gap: 1, vAlign: "center", children: [props.sender === 'user' ? time : copy, props.sender === 'user' ? copy : time] }));
 }
+/** How long the newest message keeps its copy button, time and status in view after it lands or its status changes. */
+const CHROME_FRESH_MS = 4_000;
+const CHROME_FADE = 'opacity 160ms ease';
+/** A press on a control inside the message, which does its own thing rather than show the details. */
+function isControl(target) {
+    return (target instanceof Element &&
+        target.closest('a, button, input, textarea, [role="button"]') !== null);
+}
+/**
+ * Whether a message shows its copy button, time and status: while it is hovered, while focus is
+ * inside it, after a tap or hold until the next tap, and for a few seconds when it is the newest
+ * message or its status changes.
+ */
+function useChromeReveal(isNewest, status) {
+    const [hovered, setHovered] = useState(false);
+    const [focused, setFocused] = useState(false);
+    const [tapped, setTapped] = useState(false);
+    const fresh = useFresh(isNewest, status);
+    // why: A hold opens the context menu and may end in a pointerup; that pointerup must not hide it again.
+    const held = useRef(false);
+    const handlers = {
+        onPointerEnter: (event) => {
+            if (event.pointerType === 'mouse')
+                setHovered(true);
+        },
+        onPointerLeave: (event) => {
+            if (event.pointerType === 'mouse')
+                setHovered(false);
+        },
+        onPointerUp: (event) => {
+            if (event.pointerType === 'mouse' || isControl(event.target))
+                return;
+            if (held.current)
+                held.current = false;
+            else
+                setTapped((open) => !open);
+        },
+        onContextMenu: () => {
+            held.current = true;
+            setTapped(true);
+        },
+        onFocus: () => setFocused(true),
+        onBlur: (event) => {
+            if (!event.currentTarget.contains(event.relatedTarget))
+                setFocused(false);
+        },
+    };
+    return { revealed: hovered || focused || tapped || fresh, handlers };
+}
+/** Whether a message has just landed, or its status just changed: true for a few seconds after. */
+function useFresh(isNewest, status) {
+    // why: Only the last prompt carries a status, and it can mount with one when its reply commits.
+    // why: A count, so a status that lands while the details already show starts their seconds over.
+    const [fresh, setFresh] = useState(isNewest || status !== undefined ? 1 : 0);
+    const [seenStatus, setSeenStatus] = useState(status);
+    // why: A message that stops being the last prompt loses its status; only a new one is news.
+    if (status !== seenStatus) {
+        setSeenStatus(status);
+        if (status !== undefined)
+            setFresh((count) => count + 1);
+    }
+    useEffect(() => {
+        if (fresh === 0)
+            return;
+        const timer = setTimeout(() => setFresh(0), CHROME_FRESH_MS);
+        return () => clearTimeout(timer);
+    }, [fresh]);
+    return fresh > 0;
+}
 /** A message's copy button (outermost), time and status; a failure says why on hovering its status. */
 function MessageChrome(props) {
-    const usage = props.usage ? _jsx(Usage, { tokens: props.usage }) : undefined;
-    const aside = props.error !== undefined ? (_jsx(Failed, { reason: props.error })) : props.stopped !== undefined ? (_jsx(Stopped, { label: props.stopped })) : (usage);
-    return (_jsx(ChatMessageMetadata
-    // why: The row's first slot is the one nearest the margin.
-    , { 
+    const notice = turnNotice(props.error, props.stopped);
+    return (_jsx(ChatMessageMetadata, { style: { opacity: props.revealed ? 1 : 0, transition: CHROME_FADE }, 
         // why: The row's first slot is the one nearest the margin.
         timestamp: _jsx(CopyAndTime, { sender: props.sender, at: props.at, copyText: props.copyText }), 
         // why: Astryx's statuses are a closed set, so these ride the footer.
-        footer: aside, status: props.error !== undefined || props.stopped !== undefined ? undefined : props.status }));
+        footer: notice ?? (props.usage ? _jsx(Usage, { tokens: props.usage }) : undefined), status: notice === undefined ? props.status : undefined }));
+}
+/** Why a turn failed or stopped short, said where its status goes. */
+function turnNotice(error, stopped) {
+    if (error !== undefined)
+        return _jsx(Failed, { reason: error });
+    if (stopped !== undefined)
+        return _jsx(Stopped, { label: stopped });
+    return undefined;
 }
 function dataUrl(mimeType, data) {
     return data === undefined ? undefined : `data:${mimeType};base64,${data}`;
@@ -348,6 +422,11 @@ const THOUGHT_MARKDOWN = {
     paragraph: ({ children }) => (_jsx(Text, { size: "sm", color: "secondary", display: "block", as: "p", children: children })),
     heading: ({ children }) => (_jsx(Text, { size: "sm", color: "secondary", weight: "semibold", display: "block", as: "p", children: children })),
 };
+// why: Lists and other blocks Markdown draws itself take no `components`; the thought's tokens quiet them too.
+const THOUGHT_TEXT = {
+    '--text-body-size': 'var(--text-supporting-size)',
+    '--color-text-primary': 'var(--color-text-secondary)',
+};
 function TraceList({ items, streaming }) {
     const t = useLabels();
     const showUsage = useContext(ShowUsage);
@@ -365,7 +444,7 @@ function TraceList({ items, streaming }) {
             continue;
         }
         flush();
-        rows.push(_jsx(StreamedMarkdown, { text: item.text, streaming: streaming && i === items.length - 1, density: "compact", components: THOUGHT_MARKDOWN }, item.id));
+        rows.push(_jsx("div", { style: THOUGHT_TEXT, children: _jsx(StreamedMarkdown, { text: item.text, streaming: streaming && i === items.length - 1, density: "compact", components: THOUGHT_MARKDOWN }) }, item.id));
     }
     flush();
     return _jsx(VStack, { gap: 2, children: rows });
@@ -436,29 +515,31 @@ function PendingImage(props) {
 }
 function AssistantTurn(props) {
     const t = useLabels();
+    const chrome = useChromeReveal(props.isNewest === true);
     const showUsage = useContext(ShowUsage);
     const elapsedMs = useTurnElapsed(props.streaming, props.startedAt, props.workedMs);
     const { trace, gatedTools, body, hasTrace } = composeAssistantTurn(props.blocks);
     const rows = bodyRows(t, body);
     const status = workStatusLabel(t, workStatus({ streaming: props.streaming, hasTrace, elapsedMs }));
     const copyText = assistantTurnCopyText(body.length > 0 ? body : props.blocks);
-    return (_jsx(ChatMessage, { sender: "assistant", name: props.handle, metadata: props.streaming ? undefined : (_jsx(MessageChrome, { sender: "assistant", at: props.at, copyText: copyText, error: props.error, stopped: props.stopped, usage: showUsage ? props.usage : undefined })), children: _jsxs(VStack, { gap: 3, width: "100%", children: [_jsx(TurnStatus, { status: status, trace: trace, hasTrace: hasTrace, streaming: props.streaming }), gatedTools.map((block) => (_jsx(GateCard, { block: block, handle: props.handle, handlers: props.handlers }, block.id))), keyedByContent(rows, (row) => (row.kind === 'gallery' ? 'gallery' : row.block.kind)).map(({ item: row, index: i, key }) => (_jsx(BodyRowView
+    return (_jsx(ChatMessage, { sender: "assistant", name: props.handle, ...chrome.handlers, metadata: props.streaming ? undefined : (_jsx(MessageChrome, { sender: "assistant", at: props.at, copyText: copyText, error: props.error, stopped: props.stopped, usage: showUsage ? props.usage : undefined, revealed: chrome.revealed })), children: _jsxs(VStack, { gap: 3, width: "100%", children: [_jsx(TurnStatus, { status: status, trace: trace, hasTrace: hasTrace, streaming: props.streaming }), gatedTools.map((block) => (_jsx(GateCard, { block: block, handle: props.handle, handlers: props.handlers }, block.id))), keyedByContent(rows, (row) => (row.kind === 'gallery' ? 'gallery' : row.block.kind)).map(({ item: row, index: i, key }) => (_jsx(BodyRowView
                 // why: Not the block id: the committed turn re-mints ids, and a
                 // remount would cut the text reveal short.
                 , { row: row, streaming: props.streaming && i === rows.length - 1, imageOutput: props.imageOutput }, key))), _jsx(PendingImage, { imageOutput: props.imageOutput, streaming: props.streaming, rows: rows })] }) }));
 }
 function UserTurn(props) {
     const t = useLabels();
+    const reveal = useChromeReveal(props.isNewest === true, props.status);
     const copyText = props.blocks
         .map((block) => transcriptBlockCopyText(t, block))
         .filter(Boolean)
         .join('\n\n');
-    const chrome = (_jsx(MessageChrome, { sender: "user", at: props.at, copyText: copyText, status: props.status, stopped: props.stopped, error: props.error }));
+    const chrome = (_jsx(MessageChrome, { sender: "user", at: props.at, copyText: copyText, status: props.status, stopped: props.stopped, error: props.error, revealed: reveal.revealed }));
     // why: Astryx: metadata goes on the last bubble, or on the message when the last
     // content is unbubbled (an attachment or voice note).
     const last = props.blocks.at(-1);
     const lastIsBubble = last?.kind === 'user-text';
-    return (_jsx(ChatMessage, { sender: "user", metadata: lastIsBubble ? undefined : chrome, children: props.blocks.map((block) => (_jsx(UserBlock, { block: block, metadata: block === last && lastIsBubble ? chrome : undefined }, block.id))) }));
+    return (_jsx(ChatMessage, { sender: "user", ...reveal.handlers, metadata: lastIsBubble ? undefined : chrome, children: props.blocks.map((block) => (_jsx(UserBlock, { block: block, metadata: block === last && lastIsBubble ? chrome : undefined }, block.id))) }));
 }
 /** Why a turn failed: its error block's message. */
 function failureOf(group) {
@@ -491,7 +572,7 @@ function ChatTranscriptBody({ blocks, handle, streaming = false, delivery, onToo
         const next = groups[index + 1];
         const error = isBareFailure(next) ? failureOf(next) : undefined;
         const status = index === lastUser ? (delivery ?? undefined) : undefined;
-        return (_jsx(UserTurn, { blocks: group.blocks, at: promptTime(groups, index, timeOf), status: status, stopped: stopText(group.stop, group.blocks, labels), error: error }, group.key));
+        return (_jsx(UserTurn, { blocks: group.blocks, at: promptTime(groups, index, timeOf), status: status, stopped: stopText(group.stop, group.blocks, labels), error: error, isNewest: index === groups.length - 1 }, group.key));
     };
     const turnOf = (group, index) => {
         if (group.kind === 'user')
@@ -507,7 +588,7 @@ function ChatTranscriptBody({ blocks, handle, streaming = false, delivery, onToo
         });
         // why: A reply is dated when it last stopped: a reply that just finished reads "now".
         const at = endedAt ?? timeOf(key);
-        return (_jsx(AssistantTurn, { ...turn, ...timing, blocks: group.blocks, streaming: live, at: at, error: failureOf(group), stopped: stopText(group.stop, group.blocks, labels), usage: group.usage }, key));
+        return (_jsx(AssistantTurn, { ...turn, ...timing, blocks: group.blocks, streaming: live, at: at, error: failureOf(group), stopped: stopText(group.stop, group.blocks, labels), usage: group.usage, isNewest: index === groups.length - 1 }, key));
     };
     const turns = groups.flatMap((group, index) => {
         const label = dividers?.[group.key];

package/ui/TheoremChat.d.ts

@@ -86,9 +86,11 @@ export type TheoremChatProps = {
     initialText?: string;
     /**
      * Called with each new ref the host issues for the conversation: once the message posts, and
-     * again as the reply's runs are saved. Keep the latest to resume the chat later.
+     * again as the reply's runs are saved. Keep the latest to resume the chat later. `undefined`
+     * when the host can no longer open the ref the chat resumed: the chat starts a new one, so
+     * forget it.
      */
-    onConversationChange?: (ref: string) => void;
+    onConversationChange?: (ref: string | undefined) => void;
     /** Lets the host send a message as the composer would; see {@link TheoremChatHandle}. */
     chatRef?: Ref<TheoremChatHandle>;
     /**