akanjs 3.0.0-beta.9 → 3.0.1

package/ui/Agent/mentionDraft.ts

@@ -0,0 +1,91 @@
+"use client";
+import {
+  $createLineBreakNode,
+  $createParagraphNode,
+  $createTextNode,
+  $getRoot,
+  $getSelection,
+  $isElementNode,
+  $isRangeSelection,
+  $isRootNode,
+  $isTextNode,
+  type LexicalNode,
+} from "lexical";
+import { Reference } from "../../vendor/use-agentic";
+import { $createMentionNode, $isMentionNode } from "./MentionNode";
+
+export class MentionDraft {
+  static read(): string {
+    return $getRoot().getTextContent();
+  }
+
+  static write(text: string, caretAt?: number) {
+    const paragraph = $createParagraphNode();
+    paragraph.append(...MentionDraft.nodesOf(text));
+    $getRoot().clear().append(paragraph);
+    MentionDraft.place(caretAt ?? text.length);
+  }
+
+  static nodesOf(text: string): LexicalNode[] {
+    const nodes: LexicalNode[] = [];
+    let at = 0;
+    
+    const pattern = new RegExp(Reference.pattern.source, "g");
+    for (let match = pattern.exec(text); match; match = pattern.exec(text)) {
+      const [token, label, refName, refId, path] = match;
+      if (match.index > at) nodes.push(...MentionDraft.#plain(text.slice(at, match.index)));
+      nodes.push($createMentionNode({ refName, refId, label, ...(path ? { path } : {}) }));
+      at = match.index + token.length;
+    }
+    if (at < text.length) nodes.push(...MentionDraft.#plain(text.slice(at)));
+    return nodes;
+  }
+
+  static caret(): number | null {
+    const selection = $getSelection();
+    if (!$isRangeSelection(selection)) return null;
+    const anchor = selection.anchor;
+    const node = anchor.getNode();
+    if ($isTextNode(node)) {
+      
+      const inner = $isMentionNode(node) ? (anchor.offset ? node.getTextContent().length : 0) : anchor.offset;
+      return MentionDraft.#before(node) + inner;
+    }
+    const children = $isElementNode(node) ? node.getChildren() : [];
+    const within = children.slice(0, anchor.offset).reduce((sum, child) => sum + child.getTextContent().length, 0);
+    return MentionDraft.#before(node) + within;
+  }
+
+  static place(at: number) {
+    const paragraph = $getRoot().getLastChild();
+    if (!$isElementNode(paragraph)) return;
+    let seen = 0;
+    for (const child of paragraph.getChildren()) {
+      const length = child.getTextContent().length;
+      if (at <= seen + length) {
+        
+        if ($isTextNode(child) && !$isMentionNode(child)) child.select(at - seen, at - seen);
+        else if (at > seen) child.selectNext(0, 0);
+        else if (child.getPreviousSibling()) child.selectPrevious();
+        else paragraph.select(0, 0);
+        return;
+      }
+      seen += length;
+    }
+    paragraph.selectEnd();
+  }
+
+  static #plain(text: string): LexicalNode[] {
+    return text
+      .split("\n")
+      .flatMap((line, idx) => [...(idx ? [$createLineBreakNode()] : []), ...(line ? [$createTextNode(line)] : [])]);
+  }
+
+  static #before(node: LexicalNode): number {
+    let sum = 0;
+    for (let cursor = node.getPreviousSibling(); cursor; cursor = cursor.getPreviousSibling())
+      sum += cursor.getTextContent().length;
+    const parent = node.getParent();
+    return parent && !$isRootNode(parent) ? sum + MentionDraft.#before(parent) : sum;
+  }
+}

package/ui/Agent/tokenCount.ts

@@ -1,8 +1,4 @@
-/**
- * An estimated token count as a chat-sized label. Rounded hard on purpose: the estimate itself is four characters
- * to a token, so a digit-exact figure would claim a precision it does not have — what a reader needs from it is
- * whether a tool result cost a hundred tokens or a million.
- */
+/** Rounded hard: the estimate is four characters to a token, so exact digits would claim false precision. */
 export const tokenCount = (count: number): string => {
   if (count < 1_000) return String(count);
   if (count < 1_000_000) return `${Math.round(count / 100) / 10}k`;

package/ui/Agent/useChatAttachments.ts

@@ -16,18 +16,13 @@ interface ChatAttachmentsSetup {
   l: (key: string, param?: Record<string, string | number>) => string;
 }
 
-/**
- * What the composer is holding, and the ceilings it holds it under. Staged files are mirrored in a ref because a
- * multi-file drop reads them one at a time: the cap has to see what the previous file of the same drop added, and
- * React state inside that loop is still the value the render started with.
- */
 export const useChatAttachments = ({ session, attach, limits = {}, l }: ChatAttachmentsSetup) => {
   const count = limits.perMessageCount ?? maxMessageAttachments;
   const messageBytes = limits.perMessageBytes ?? maxMessageAttachmentBytes;
   const [attached, setAttached] = useState<MessageAttachment[]>([]);
-
   const [pending, setPending] = useState(0);
   const [dragging, setDragging] = useState(false);
+  
   const staged = useRef<MessageAttachment[]>([]);
   
   const depth = useRef(0);
@@ -40,7 +35,6 @@ export const useChatAttachments = ({ session, attach, limits = {}, l }: ChatAtta
     depth.current = 0;
     setDragging(false);
   };
-  /** Staged one at a time so one unreadable file names itself instead of failing the whole drop silently. */
   const add = async (files: File[]) => {
     for (const file of files) {
       if (staged.current.length >= count) {
@@ -81,13 +75,12 @@ export const useChatAttachments = ({ session, attach, limits = {}, l }: ChatAtta
     onDrop: (event) => {
       const files = [...event.dataTransfer.files];
       rest();
-
+      
       if (!files.length) return;
       event.preventDefault();
       void add(files);
     },
   };
-  /** Stages files taken back from a parked message, ahead of what was picked since. False, noted, when they do not fit. */
   const restore = (list: MessageAttachment[]): boolean => {
     const next = [...list, ...staged.current];
     const overflow = Attachment.overflow(next, limits);

package/ui/Agent/useChatQueue.ts

@@ -4,36 +4,26 @@ import type { AgentSession, MessageAttachment, MessageReference } from "../../ve
 import { Reference } from "../../vendor/use-agentic";
 import { type AttachLimits, Attachment, maxMessageAttachments } from "./attachment";
 
-/** What the composer held when it was sent: the shape a turn opens with, whether now or after the running one. */
 export interface QueuedMessage {
   text: string;
   attachments: MessageAttachment[];
-  /** What the parked text's tokens pointed at. Carried so a turn that opens later still knows what they held. */
   references: MessageReference[];
-  /** The ask came from the microphone, so the reply it gets is read aloud — carried until the send that opens it. */
+  /** The ask came from the microphone, so its reply is read aloud. */
   byVoice: boolean;
 }
 
 interface ChatQueueSetup {
   session: AgentSession;
   limits?: AttachLimits;
-  /** The chat's own version snapshot — the turn ending is one of the changes it counts. */
   version: number;
   l: (key: string, param?: Record<string, string | number>) => string;
   onFlush: (message: QueuedMessage) => void;
 }
 
-/**
- * One message parked while a turn runs, sent the moment the turn ends. One slot rather than a list: a second send
- * joins the first, so what reaches the model is one user message and the user has one thing to take back or drop.
- *
- * Mirrored in a ref because the flush and the drop both race the turn's own wind-down: `/new` empties the slot
- * and then aborts, and the abort's notify would otherwise read the state the render started with and send what
- * was just dropped.
- */
 export const useChatQueue = ({ session, limits = {}, version, l, onFlush }: ChatQueueSetup) => {
   const count = limits.perMessageCount ?? maxMessageAttachments;
   const [queued, setQueued] = useState<QueuedMessage | null>(null);
+  
   const held = useRef<QueuedMessage | null>(null);
   const put = (next: QueuedMessage | null) => {
     held.current = next;
@@ -47,7 +37,6 @@ export const useChatQueue = ({ session, limits = {}, version, l, onFlush }: Chat
   }, [version]);
   return {
     queued,
-    /** Parks a message, joined onto one already waiting. False, with the reason noted, when the files would not fit. */
     push: (message: QueuedMessage): boolean => {
       const before = held.current;
       const attachments = [...(before?.attachments ?? []), ...message.attachments];
@@ -59,7 +48,7 @@ export const useChatQueue = ({ session, limits = {}, version, l, onFlush }: Chat
       put({
         text: [before?.text, message.text].filter(Boolean).join("\n"),
         attachments,
-
+        
         references: [
           ...message.references,
           ...(before?.references ?? []).filter(
@@ -70,7 +59,6 @@ export const useChatQueue = ({ session, limits = {}, version, l, onFlush }: Chat
       });
       return true;
     },
-    /** Empties the slot and answers what was in it — the drop, and the first half of handing it back. */
     take: (): QueuedMessage | null => {
       const message = held.current;
       if (message) put(null);

package/ui/Agent/useChatReferences.ts

@@ -1,36 +1,24 @@
 "use client";
 import { type RefObject, useEffect, useMemo, useRef } from "react";
 import { type AgentSession, type MessageReference, Reference } from "../../vendor/use-agentic";
+import type { ComposerHandle } from "./Composer";
 
 interface ChatReferencesSetup {
   session: AgentSession;
   draft: string;
-  /** The chat's own version snapshot — a `refer` from anywhere on the page is one of the changes it counts. */
   version: number;
-  inputRef: RefObject<HTMLTextAreaElement | null>;
+  handleRef: RefObject<ComposerHandle | null>;
   onDraft: (text: string) => void;
 }
 
-/**
- * The composer's half of a reference: writing the token for one somebody pointed at elsewhere, and reading back
- * which references the draft now carries.
- *
- * **The text is the source of truth, and the staged values are looked up beside it.** A reference is on the
- * message because its token is in the message — so deleting the token by hand drops it, exactly as deleting the
- * chip does, and neither can leave the other behind. The draft is never scanned to re-derive a value; a token
- * whose value was never staged (pasted out of an earlier message) travels as a pointer with a note saying to read
- * it again, which is the same shape a restored conversation produces.
- */
-export const useChatReferences = ({ session, draft, version, inputRef, onDraft }: ChatReferencesSetup) => {
+export const useChatReferences = ({ session, draft, version, handleRef, onDraft }: ChatReferencesSetup) => {
   const caret = useRef<number | null>(null);
-
+  
   useEffect(() => session.attachChat(), [session]);
   useEffect(() => {
     const pending = session.pendingInserts;
     if (!pending.length) return;
-    const area = inputRef.current;
-
-    const at = area ? area.selectionStart : draft.length;
+    const at = handleRef.current?.caret() ?? draft.length;
     const head = draft.slice(0, at);
     const tail = draft.slice(at);
     const tokens = pending.map((one) => Reference.token(one)).join(" ");
@@ -44,11 +32,8 @@ export const useChatReferences = ({ session, draft, version, inputRef, onDraft }
     const at = caret.current;
     if (at === null) return;
     caret.current = null;
-    const area = inputRef.current;
-    if (!area) return;
     
-    area.focus();
-    area.setSelectionRange(at, at);
+    handleRef.current?.setCaret(at);
   }, [draft]);
   const references = useMemo<MessageReference[]>(() => {
     const staged = new Map(session.staged.map((one) => [Reference.keyOf(one), one]));
@@ -58,7 +43,6 @@ export const useChatReferences = ({ session, draft, version, inputRef, onDraft }
   }, [draft, version]);
   return {
     references,
-    /** Removing the chip removes the token, because the token is what puts the reference on the message. */
     remove: (key: string) => {
       onDraft(Reference.without(draft, key));
       session.unstage(key);

package/ui/Agent/useChatVoice.ts

@@ -6,20 +6,11 @@ import { type VoiceEngine, type VoiceListener, VoiceReader } from "./voice";
 interface ChatVoiceSetup {
   session: AgentSession;
   engine?: VoiceEngine;
-  /** The chat's own version snapshot — every transcript change re-runs the reading policy. */
   version: number;
   onTranscript: (text: string) => void;
   onFailed: () => void;
 }
 
-/**
- * The chat's speech policy, which is the framework's and not the engine's: one utterance per press, the
- * transcript landing in the composer to be corrected, barge-in on the next press or on Stop, and a reply read
- * aloud **only when the ask arrived by voice** — a typed question never turns the speakers on.
- *
- * A question or an approval the loop parked on is read too, and only in that same case: the loop stops there,
- * and a voice user staring at a card they were never told about is a conversation that simply ends.
- */
 export const useChatVoice = ({ session, engine, version, onTranscript, onFailed }: ChatVoiceSetup) => {
   const [listening, setListening] = useState(false);
   
@@ -28,11 +19,9 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
   const listener = useRef<VoiceListener | null>(null);
   const reader = useRef<VoiceReader | null>(null);
   reader.current ??= new VoiceReader(() => held.current);
-  /** Set while the draft came from the microphone, consumed by the send that carries it. */
   const byVoice = useRef(false);
-  /** The assistant message being read aloud, and where its turn began. Null means this turn is not one to read. */
+  
   const spoken = useRef<{ at: number; from: number } | null>(null);
-  /** The parked card already announced, so a question is not re-read on every transcript change. */
   const announced = useRef<string | null>(null);
   const heard = useRef(0);
   useEffect(() => {
@@ -56,7 +45,6 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
       (message, idx) => idx >= reading.from && message.role === "assistant" && !message.local && !!message.text,
     );
     if (at < 0) return;
-    
     if (at !== reading.at) {
       speaker.reset();
       reading.at = at;
@@ -75,7 +63,7 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
     },
     [],
   );
-  /** One press is one utterance, so the engine is told to stop even when it reported a final result itself. */
+  
   const endListening = () => {
     const running = listener.current;
     listener.current = null;
@@ -86,10 +74,6 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
     reader.current?.cancel();
     spoken.current = null;
   };
-  /**
-   * Whether the draft came from the microphone, cleared as it is read: the send consuming the draft takes it, and
-   * an ask parked behind a running turn carries it to the send that finally opens with it.
-   */
   const lift = () => {
     const was = byVoice.current;
     byVoice.current = false;
@@ -97,15 +81,12 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
   };
   return {
     listening,
-    /** A screen that cannot listen renders no microphone — the rule that publishes no tool for a missing control. */
     canListen: !!engine && (engine.available?.() ?? true),
     silence,
     lift,
-    /** Puts a lifted flag back, for a parked ask that returned to the composer instead of opening a turn. */
     hold: (spokenAsk: boolean) => {
       byVoice.current ||= spokenAsk;
     },
-    /** Called by the send that opens a turn: only an ask that arrived by voice is answered out loud. */
     take: (spokenAsk = lift()) => {
       
       spoken.current = spokenAsk ? { at: -1, from: session.messages.length } : null;
@@ -117,7 +98,6 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
       }
       const voiceEngine = held.current;
       if (!voiceEngine) return;
-      
       silence();
       listener.current = voiceEngine.listen({
         onInterim: onTranscript,
@@ -127,7 +107,6 @@ export const useChatVoice = ({ session, engine, version, onTranscript, onFailed
           endListening();
         },
         onError: (message) => {
-          
           console.warn(`[akan] voice input failed: ${message}`);
           onFailed();
           endListening();

package/ui/Agent/useDraftRecall.ts

@@ -2,19 +2,11 @@
 import { useRef, useState } from "react";
 import type { ChatMessage } from "../../vendor/use-agentic";
 
-/** What a restored transcript can still offer the arrows: the asks themselves, newest last. */
 const asked = (messages: readonly ChatMessage[], cap: number) =>
   messages
     .flatMap((message) => (message.role === "user" && !message.summary && message.text ? [message.text] : []))
     .slice(-cap);
 
-/**
- * ↑ walks back through what was sent, ↓ forward, and 0 is the draft it was walked away from. A single-line input
- * does nothing of its own with the vertical arrows, so recall is free to take them.
- *
- * Seeded from the transcript rather than starting empty, because a persisted chat restores the conversation and
- * losing only "what I just typed" across a reload is the one gap a user notices.
- */
 export const useDraftRecall = (messages: readonly ChatMessage[]) => {
   const cap = 30;
   const sent = useRef<string[] | null>(null);
@@ -29,7 +21,6 @@ export const useDraftRecall = (messages: readonly ChatMessage[]) => {
       if (history[history.length - 1] !== text) sent.current = [...history, text].slice(-cap);
       setAt(0);
     },
-    /** Answers the draft to show, or null when the walk cannot go that way. */
     step: (delta: number, draft: string): string | null => {
       const history = sent.current ?? [];
       const next = Math.max(0, Math.min(at + delta, history.length));

package/ui/Agent/useKeyboardInset.ts

@@ -1,13 +1,6 @@
 "use client";
 import { useEffect, useState } from "react";
 
-/**
- * How much of the layout viewport the on-screen keyboard is covering.
- *
- * `visualViewport` is the only thing that reports it — `dvh` tracks the browser's own chrome and not the
- * keyboard — and a full-screen chat whose composer sits under the keyboard is one nobody can type into. Answers
- * 0 wherever the API is absent, which is every desktop case and the server.
- */
 export const useKeyboardInset = () => {
   const [inset, setInset] = useState(0);
   useEffect(() => {

package/ui/Agent/useReferenceMenu.ts

@@ -4,29 +4,21 @@ import { useEffect, useRef, useState } from "react";
 import { type AgentSession, Reference } from "../../vendor/use-agentic";
 import type { MenuRow } from "./Menu";
 
-/** One row the `@` menu offers: a document of its source's model, named the way the screen names it. */
 export interface ReferenceCandidate {
   refId: string;
   label: string;
   description?: string;
 }
 
-/**
- * A kind of document the `@` menu can point at.
- *
- * `type` is the whole decision about what leaves the browser, in `st.expose`'s vocabulary — a model class masks by
- * that model. **Name the class that actually carries the fields somebody is pointing at**: a `Light<Model>` is
- * usually not it, and a reference masked by one arrives without the field that was the reason for pointing.
- *
- * `search` is the app's own query, because which documents a person may point at is the app's answer and not the
- * framework's; the signal is aborted when the query moves on. `resolve` is called once, when a row is picked.
- */
 export interface ReferenceSource<T extends AgentFieldType = AgentFieldType> {
   refName: string;
   /** What this group of rows is called in the menu. */
   label: string;
+  /** Masks what leaves the browser: name the class carrying the pointed-at fields, which a `Light<Model>` rarely is. */
   type: T;
+  /** The signal aborts when the query moves on. */
   search: (query: string, signal: AbortSignal) => Promise<ReferenceCandidate[]>;
+  /** Called once, when a row is picked. */
   resolve: (refId: string) => Promise<unknown>;
 }
 
@@ -38,21 +30,15 @@ interface ReferenceMenuSetup {
   onWrite: (text: string) => void;
 }
 
-/**
- * Only a word being typed at the end of the draft opens the menu. A `@` mid-sentence is left alone because the
- * draft is the only thing this can read — a textarea's caret is not in React state — and a completed token always
- * ends in a space, so the menu never reopens onto one it just wrote.
- */
 const atQuery = /(^|\s)@([^\s@[\]()]*)$/;
 
-/** Long enough that typing a name is one query rather than one per letter, short enough to feel like a menu. */
 const searchDelay = 150;
 
 export const useReferenceMenu = ({ draft, sources, session, l, onWrite }: ReferenceMenuSetup) => {
   const [rows, setRows] = useState<MenuRow[]>([]);
   const [cursor, setCursor] = useState(0);
   const [hidden, setHidden] = useState(false);
-
+  
   const held = useRef(sources);
   held.current = sources;
   const match = hidden ? null : atQuery.exec(draft);
@@ -60,7 +46,6 @@ export const useReferenceMenu = ({ draft, sources, session, l, onWrite }: Refere
   const query = match ? match[2] : null;
   const write = (candidate: ReferenceCandidate, source: ReferenceSource) => {
     const reference = { refName: source.refName, refId: candidate.refId, label: candidate.label };
-
     onWrite(`${draft.slice(0, match?.index ?? 0)}${match?.[1] ?? ""}${Reference.token(reference)} `);
     void source
       .resolve(candidate.refId)

package/ui/Agent/useSlashMenu.ts

@@ -9,10 +9,8 @@ interface SlashMenuSetup {
   onCommand: (command: ChatCommand) => void;
 }
 
-/** Only a bare `/name` opens the menu: once an argument is being typed, the list has nothing left to offer. */
 const slashQuery = /^\/[A-Za-z0-9_-]*$/;
 
-/** The `/` menu's rows — this chat's own commands — and which one the keys are on. */
 export const useSlashMenu = ({ draft, l, onCommand }: SlashMenuSetup) => {
   const [cursor, setCursor] = useState(0);
   const [hidden, setHidden] = useState(false);
@@ -30,7 +28,6 @@ export const useSlashMenu = ({ draft, l, onCommand }: SlashMenuSetup) => {
   return {
     rows,
     selected,
-    /** Reset when the draft is written to: a new query has a new first row, and Escape only hides the old one. */
     reopen: () => {
       setHidden(false);
       setCursor(0);

package/ui/Agent/voice.ts

@@ -1,38 +1,27 @@
-/** A recognition run in progress. `stop` ends it; a final result may still arrive after. */
+/** A final result may still arrive after `stop`. */
 export interface VoiceListener {
   stop: () => void;
 }
 
-/** One utterance being spoken. `cancel` is barge-in; `done` resolves when it finished or was cancelled. */
+/** `done` resolves when the utterance finished or was cancelled. */
 export interface VoiceSpeech {
   cancel: () => void;
   done: Promise<void>;
 }
 
 export interface VoiceHandlers {
-  /** Partial text while the user is still speaking. An engine without interim results simply never calls it. */
+  /** Partial text while the user is still speaking; an engine without interim results never calls it. */
   onInterim?: (text: string) => void;
   onFinal: (text: string) => void;
   onError: (message: string) => void;
 }
 
-/**
- * The seam a voice engine fills — one contract, whatever is behind it: the browser's own recognition, a cloud
- * STT/TTS pair, or a native plugin. The engine speaks and listens; **the framework owns the policy** — when to
- * listen, what to speak, sentence chunking, barge-in, and whether a reply is spoken at all.
- *
- * Shaped as a subscription rather than `listen(): Promise<string>` on purpose. A promise fits push-to-talk and
- * nothing else, and continuous listening could then only arrive as a breaking change; this shape carries both, so
- * hands-free is a later policy decision instead of a later contract.
- *
- * `listen` must be reachable from the click that starts it: microphone permission and, on iOS, the first
- * `speechSynthesis` utterance are both gated on a user gesture.
- */
+/** `listen` must run inside the click that starts it: mic permission and iOS's first utterance need a user gesture. */
 export interface VoiceEngine {
   listen: (handlers: VoiceHandlers) => VoiceListener;
-  /** One sentence at a time, already stripped of markdown. The framework queues; the engine speaks. */
+  /** Handed one markdown-free sentence at a time; the framework queues. */
   speak: (text: string) => VoiceSpeech;
-  /** Answering false hides the controls — a screen that cannot listen should not offer a microphone. */
+  /** `false` hides the microphone. */
   available?: () => boolean;
 }
 
@@ -45,16 +34,6 @@ const link = /\[([^\]]*)\]\([^)]*\)/g;
 const emphasis = /(\*\*\*|\*\*|\*|___|__|_|~~)/g;
 const inlineCode = /`([^`]*)`/g;
 
-/**
- * What of a model's answer should be read aloud.
- *
- * Code blocks, tables, and rules are dropped rather than spoken: a fence read character by character is noise,
- * and a table read cell by cell is worse than silence — in push-to-talk the user is looking at the screen that
- * already renders both. Inline code keeps its content, because that is usually a name worth hearing.
- *
- * Monotonic over a growing source, which is what lets the reader below track one offset: new text never changes
- * how earlier text was rendered, since a fence marker always arrives before the lines it swallows.
- */
 export const speechText = (markdown: string): string => {
   const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
   const kept: string[] = [];
@@ -76,16 +55,8 @@ export const speechText = (markdown: string): string => {
   return kept.join("\n");
 };
 
-/** A terminator counts only with whitespace behind it, so `1.5` is not a sentence and a stream is never cut early. */
 const sentenceEnd = /[.!?。！？…]+\s|\n/g;
 
-/**
- * Reads an assistant answer aloud as it streams in, one sentence at a time.
- *
- * Sentence-at-a-time rather than delta-at-a-time because a delta cuts words in half, and whole-message-at-a-time
- * because that waits for the turn to end. The offset is over `speechText` output, not the raw source, so a code
- * block that arrives mid-answer costs nothing.
- */
 export class VoiceReader {
   readonly #engine: () => VoiceEngine | undefined;
   #queue: string[] = [];
@@ -105,18 +76,12 @@ export class VoiceReader {
     this.#chunk(source, false);
   }
 
-  /**
-   * The turn ended: the last sentence has no whitespace behind it and would otherwise never be spoken. It still
-   * splits what is left, because a whole answer that arrived in one render must not be read as one long utterance.
-   */
+  /** The turn ended: also speaks the last sentence, which has no whitespace behind it. */
   flush(source: string) {
     this.#chunk(source, true);
   }
 
-  /**
-   * A line that is not part of the answer being tracked — the question or approval the loop parked on. It joins
-   * the same queue, so it is spoken after the sentence in flight rather than over it, and Stop still cancels it.
-   */
+  /** Queued behind the sentence in flight, outside the tracked answer; Stop still cancels it. */
   say(text: string) {
     this.#enqueue(speechText(text));
     this.#pump();

package/ui/Badge.tsx

@@ -8,10 +8,8 @@ export { type BadgeVariants, badgeRecipe };
 export type BadgeProps = HTMLAttributes<HTMLSpanElement> & BadgeVariants;
 
 const DefaultBadge = ({ className, variant, size, outline, ...rest }: BadgeProps) => {
-  
   const recipe = useUiRecipe("badge") ?? badgeRecipe;
   return <span className={recipe({ variant, size, outline }, className)} {...rest} />;
 };
 
-/** Status/label pill. Route-overridable via `page/**\/_overrides.tsx` (slot `Badge`). */
 export const Badge = createOverridable("Badge", DefaultBadge);

package/ui/BottomSheet.tsx

@@ -10,20 +10,17 @@ import { config, useSpring } from "react-spring";
 import { buttonRecipe } from "./Button";
 
 interface BottomSheetProps {
-  /** Additional classes for the sheet surface. */
   className?: string;
-  /** Additional classes for the scrolling body. */
   bodyClassName?: string;
-  /** Controlled open state. Left out, the sheet opens from its own trigger and handle. */
+  /** Left out, the sheet opens from its own trigger and handle. */
   open?: boolean;
   onCancel?: () => void;
-  /** Element that opens the sheet. */
   trigger?: ReactNode;
   /** Whole top row of the sheet, replacing the drag handle or the close row. */
   header?: ReactNode;
   /** The grab handle a `half` sheet draws. */
   handle?: ReactNode;
-  /** Element that closes a `full` sheet, inside the default header row. */
+  /** Closes a `full` sheet, inside the default header row. */
   close?: ReactNode;
   children: ReactNode;
   type: "full" | "half";