@agent-native/core 0.120.3 → 0.121.0

package/corpus/templates/content/app/components/editor/DocumentEditor.tsx

@@ -644,16 +644,8 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       }
     : undefined;
 
-  // Live collaboration for everyone who can open the doc — editors and viewers
-  // alike. Viewers join the shared Y.Doc read-only: they see live keystrokes,
-  // cursors, and presence (Google-Docs style) instead of a lagging SQL snapshot.
-  // The server enforces the split — collab READ routes (state / awareness GET /
-  // users) require viewer access, WRITE routes (update) require editor — so a
-  // viewer's client can subscribe but never push. The editor stays non-editable
-  // for viewers (see `editable={canEdit}` below), and VisualEditor additionally
-  // neutralizes every local Y.Doc mutation for viewers (no seed, no reconcile
-  // apply) so a read-only client can never originate a rejected `/update` POST.
-  // Local-file documents are still excluded (they have no SQL-backed collab doc).
+  // All SQL-backed readers subscribe for presence. Only editors bind the body
+  // to Yjs; viewers render canonical SQL so missing collab state cannot hide it.
   const collabEnabled = !isLocalFileDocument;
   const {
     ydoc,
@@ -671,6 +663,12 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
   const bodyHydrationPending = documentBodyHydrationIsPending(document);
   const editorCanEdit =
     canEdit && !bodyHydrationPending && (isLocalFileDocument || !collabLoading);
+  // Bind an editor's stable Y.Doc on its first mount, even while the initial
+  // state is loading. Editability remains gated by `editorCanEdit`, and the
+  // reconcile hook remains gated by `collabSynced`; keeping the Y.Doc binding
+  // stable avoids a snapshot -> collab remount that can seed the same SQL body
+  // beside freshly projected persisted CRDT content.
+  const collabEditorEnabled = collabEnabled && canEdit && !bodyHydrationPending;
   canEditRef.current = editorCanEdit;
 
   // Viewers intentionally join awareness so they receive live cursors, but
@@ -900,6 +898,12 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     },
     [document, documentId, queryClient, updateDocument],
   );
+  // The document query can refresh its object identity without changing the
+  // flush request itself. Keep the latest save function behind a ref so those
+  // routine refreshes do not restart the one-shot flush reader and flood the
+  // browser with duplicate application-state requests.
+  const persistDocumentUpdatesRef = useRef(persistDocumentUpdates);
+  persistDocumentUpdatesRef.current = persistDocumentUpdates;
 
   const saveDocumentImmediately = useCallback(
     async (
@@ -1216,7 +1220,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             }
             try {
               if (Object.keys(updates).length > 0) {
-                const saved = await persistDocumentUpdates(updates);
+                const saved = await persistDocumentUpdatesRef.current(updates);
                 if (isDocumentUpdateConflict(saved)) {
                   // Do not acknowledge a CAS loss as a successful flush. The
                   // requester must stop instead of pushing/replacing stale SQL.
@@ -1290,7 +1294,6 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     flushRequestKey,
     flushRequestWake,
     isLocalFileDocument,
-    persistDocumentUpdates,
     t,
   ]);
 
@@ -1372,6 +1375,24 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     setHoveredThreadId(null);
   }, []);
 
+  const activateCommentThread = useCallback((threadId: string) => {
+    setPendingComment(null);
+    setHoveredThreadId(null);
+    setSelectedThreadId(threadId);
+    setUtilityPanel("comments");
+  }, []);
+
+  const handleUtilityPanelChange = useCallback(
+    (nextPanel: DocumentUtilityPanel) => {
+      setUtilityPanel(nextPanel);
+      if (nextPanel !== "comments") {
+        setPendingComment(null);
+        clearCommentFocus();
+      }
+    },
+    [clearCommentFocus],
+  );
+
   useEffect(() => {
     setPendingComment(null);
     setUtilityPanel(null);
@@ -1512,9 +1533,11 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       scrollContainerRef={scrollContainerRef}
       activeThreadId={activeThreadId}
       selectedThreadId={selectedThreadId}
+      onActivateThread={activateCommentThread}
       onSelectedThreadChange={setSelectedThreadId}
       onHoveredThreadChange={setHoveredThreadId}
       currentUserEmail={session?.email}
+      alignToAnchors={hasUtilityRailSpace}
       forceVisible
     />
   );
@@ -1566,7 +1589,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             type="button"
             className="ms-auto flex size-8 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
             aria-label={t("editor.toolbar.closeUtilityPanel")}
-            onClick={() => setUtilityPanel(null)}
+            onClick={() => handleUtilityPanelChange(null)}
           >
             <IconX size={16} />
           </button>
@@ -1594,7 +1617,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       <div
         className="relative flex min-h-0 min-w-0 flex-1"
         data-document-print-root
-        onPointerDownCapture={(event) => {
+        onClickCapture={(event) => {
           const target = event.target as HTMLElement | null;
           if (
             target?.closest("[data-comments-sidebar], [data-comment-thread]")
@@ -1626,7 +1649,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             }
             onDelete={handleDeleteDocument}
             utilityPanel={utilityPanel}
-            onUtilityPanelChange={setUtilityPanel}
+            onUtilityPanelChange={handleUtilityPanelChange}
             showCommentsControl={editorCanEdit && !isLocalFileDocument}
             onOpenBreadcrumbItem={handleOpenToolbarBreadcrumb}
           />
@@ -1817,7 +1840,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                       // fields.
                       const primaryEditor = (
                         <VisualEditor
-                          key={`${documentId}:${editorCanEdit && !isLocalFileDocument ? "live" : "snapshot"}`}
+                          key={`${documentId}:${collabEditorEnabled && ydoc ? "live-ready" : canEdit && !isLocalFileDocument ? "live-pending" : `snapshot:${document.updatedAt}`}`}
                           documentId={documentId}
                           content={
                             isLocalFileDocument
@@ -1831,13 +1854,11 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                           }
                           onChange={handleContentChange}
                           onSaveContent={handleContentSaveNow}
-                          // Bind the shared Y.Doc/awareness for viewers too — the
-                          // editor is non-editable for them and VisualEditor blocks
-                          // any local Y.Doc mutation, so they get live edits +
-                          // cursors without ever writing. Excludes local-file docs.
-                          ydoc={collabEnabled ? ydoc : null}
-                          collabSynced={collabEnabled ? collabSynced : true}
-                          awareness={collabEnabled ? awareness : null}
+                          ydoc={collabEditorEnabled ? ydoc : null}
+                          collabSynced={
+                            collabEditorEnabled ? collabSynced : true
+                          }
+                          awareness={collabEditorEnabled ? awareness : null}
                           user={currentUser}
                           editable={editorCanEdit}
                           localFileMode={isLocalFileDocument}
@@ -1854,7 +1875,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                           pendingHighlight={pendingComment?.range ?? null}
                           onActivateThread={
                             editorCanEdit && !isLocalFileDocument
-                              ? setSelectedThreadId
+                              ? activateCommentThread
                               : undefined
                           }
                           onJoinTitle={joinFirstBodyBlockToTitle}
@@ -1883,6 +1904,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                     })()}
                     {!bodyHydrationPending &&
                     !isLocalFileDocument &&
+                    canEdit &&
                     collabLoading ? (
                       <div
                         className="mt-4 inline-flex items-center gap-2 rounded-md border border-border bg-muted/40 px-3 py-2 text-xs text-muted-foreground"
@@ -1910,20 +1932,21 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             open={utilityPanel !== null}
             onOpenChange={(open) => {
               if (!open) {
-                setUtilityPanel(null);
-                setPendingComment(null);
+                handleUtilityPanelChange(null);
               }
             }}
           >
             <SheetContent
               side="right"
-              className="w-[85vw] max-w-sm p-0"
+              className="flex min-h-0 w-[85vw] max-w-sm flex-col overflow-hidden p-0"
               aria-describedby={undefined}
             >
               <SheetHeader className="sr-only">
                 <SheetTitle>{utilityPanelTitle}</SheetTitle>
               </SheetHeader>
-              {utilityPanelContent}
+              <div className="min-h-0 min-w-0 flex-1 overflow-x-hidden overflow-y-auto">
+                {utilityPanelContent}
+              </div>
             </SheetContent>
           </Sheet>
         ) : null}

package/corpus/templates/content/app/components/editor/database/sidebar.tsx

@@ -136,8 +136,14 @@ export function ContentFilesSidebarView({
     | "scroll"
   >;
 }) {
+  const usableData =
+    data?.database &&
+    Array.isArray(data.items) &&
+    Array.isArray(data.properties)
+      ? data
+      : undefined;
   const viewConfig = applyPersonalSidebarViewOverrides(
-    data?.database.viewConfig ?? defaultDatabaseViewConfig(),
+    usableData?.database.viewConfig ?? defaultDatabaseViewConfig(),
     overrides,
   );
   const [selectedViewId, setSelectedViewId] = useState(
@@ -154,10 +160,10 @@ export function ContentFilesSidebarView({
   useEffect(() => {
     setConstraintsCleared(false);
   }, [activeFilterKey, activeView.id]);
-  const items = data
+  const items = usableData
     ? applyDatabaseView(
-        data.items,
-        data.properties,
+        usableData.items,
+        usableData.properties,
         "",
         constraintsCleared ? [] : activeView.filters,
         activeView.sorts,
@@ -167,16 +173,18 @@ export function ContentFilesSidebarView({
   const groups = databaseVisibleGroups(
     databaseViewItemGroups(
       items,
-      data?.properties ?? [],
+      usableData?.properties ?? [],
       activeView.groupByPropertyId,
     ),
     activeView.hideEmptyGroups === true,
   );
-  const hasFilesHierarchy = data?.properties.some(
+  const hasFilesHierarchy = usableData?.properties.some(
     (property) => property.definition.systemRole === "files_parent",
   );
   const hierarchyItems = hasFilesHierarchy ? items : undefined;
-  const hierarchyUniverseItems = hasFilesHierarchy ? data?.items : undefined;
+  const hierarchyUniverseItems = hasFilesHierarchy
+    ? usableData?.items
+    : undefined;
   return (
     <div className="min-w-0">
       {viewConfig.views.length > 1 && (
@@ -204,7 +212,10 @@ export function ContentFilesSidebarView({
         {...labels}
         groups={groups}
         grouped={
-          !!databaseViewGroupingProperty(activeView, data?.properties ?? [])
+          !!databaseViewGroupingProperty(
+            activeView,
+            usableData?.properties ?? [],
+          )
         }
         isLoading={isLoading}
         hasActiveConstraints={

package/corpus/templates/content/app/i18n-data.ts

@@ -3085,6 +3085,7 @@ const enUS = {
     askAi: "Ask AI",
     resolve: "Resolve",
     resolved: "Resolved ({{count}})",
+    unanchored: "Highlight unavailable",
     reply: "Reply...",
     reopen: "Reopen",
     agentRegardingText: 'Regarding this text: "{{text}}"',
@@ -8761,6 +8762,19 @@ const contentReferenceMessagesByLocale = {
   },
 } satisfies Partial<Record<LocaleCode, typeof enUS.editor.reference>>;
 
+const commentMessagesByLocale = {
+  "zh-CN": { unanchored: "高亮不可用" },
+  "zh-TW": { unanchored: "無法使用醒目提示" },
+  "es-ES": { unanchored: "Resaltado no disponible" },
+  "fr-FR": { unanchored: "Surlignage indisponible" },
+  "de-DE": { unanchored: "Hervorhebung nicht verfügbar" },
+  "ja-JP": { unanchored: "ハイライトを利用できません" },
+  "ko-KR": { unanchored: "강조 표시를 사용할 수 없음" },
+  "pt-BR": { unanchored: "Destaque indisponível" },
+  "hi-IN": { unanchored: "हाइलाइट उपलब्ध नहीं है" },
+  "ar-SA": { unanchored: "التمييز غير متاح" },
+} satisfies Partial<Record<LocaleCode, Partial<typeof enUS.comments>>>;
+
 function mergeMessages(overrides: PartialMessages): Messages {
   return {
     root: { ...enUS.root, ...overrides.root },
@@ -8862,6 +8876,7 @@ function mergeMessagesForLocale(
   });
   return {
     ...base,
+    comments: { ...base.comments, ...commentMessagesByLocale[locale] },
     root: { ...base.root, ...rawLiteralOverrides.root },
     team: { ...base.team, ...rawLiteralOverrides.team },
     settings: { ...base.settings, ...rawLiteralOverrides.settings },

package/corpus/templates/content/changelog/2026-07-23-shared-pages-now-keep-durable-content-visible-and-comment-th.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-23
+---
+
+Shared pages now keep durable content visible, and comment threads stay stable and connected while you navigate.

package/corpus/templates/content/changelog/2026-07-24-comment-drafts-now-stay-open-when-saving-fails-and-long-live.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-24
+---
+
+Comment drafts now stay open when saving fails, and long-lived document sessions no longer flood the browser with sync requests.

package/corpus/templates/design/actions/update-file.ts

@@ -5,7 +5,7 @@ import {
   applyText,
   seedFromText,
 } from "@agent-native/core/collab";
-import { isPostgres } from "@agent-native/core/db";
+import { getDbExec, isPostgres } from "@agent-native/core/db";
 import { accessFilter, assertAccess } from "@agent-native/core/sharing";
 import { and, eq, isNull, sql } from "drizzle-orm";
 import { z } from "zod";
@@ -16,6 +16,30 @@ import { assertDesignHtmlEditIntegrity } from "../shared/html-integrity.js";
 import { assertLockedLayersPreserved } from "../shared/locked-layers.js";
 import { sourceContentHash } from "../shared/source-workspace.js";
 
+// TEMPORARY diagnostic — remove once we've read a few real conflicts in prod.
+// Conflicts are now benign 409s the framework no longer error-logs; this keeps
+// them visible in Netlify, and `content-conflict`'s cacheIsStale field tells us
+// whether they're the multi-instance stale-cache phantom (→ worth the core
+// reload fix) or a genuine concurrent writer (→ 409-rebase is already correct).
+function logSaveConflictDebug(
+  event: string,
+  detail: Record<string, unknown>,
+): void {
+  console.warn(`[update-file:debug] ${event}`, detail);
+}
+
+// 404 via statusCode (NOT status — the action route only reads statusCode) so
+// the client save-outbox treats a gone file as terminal and drops it, instead
+// of looping a masked 500. Used at every missing-file guard, including the
+// post-lock rereads a concurrent delete can hit.
+function fileNotFound(id: string): Error & { statusCode?: number } {
+  const err = new Error(`File not found: ${id}`) as Error & {
+    statusCode?: number;
+  };
+  err.statusCode = 404;
+  return err;
+}
+
 function rowsAffected(result: unknown): number | undefined {
   const candidate = result as {
     rowsAffected?: unknown;
@@ -169,16 +193,8 @@ export default defineAction({
       .limit(1);
 
     if (!file) {
-      // Terminal (not transient): the row is gone or out of access scope, so a
-      // retry can never succeed. Mark it 404 so the client save-outbox drops the
-      // entry instead of retrying forever (which turns one orphaned/deleted
-      // screen into an update-file 500 storm — see design-save-outbox
-      // isTerminalSaveError).
-      const notFound = new Error(`File not found: ${id}`) as Error & {
-        status?: number;
-      };
-      notFound.status = 404;
-      throw notFound;
+      // The row is gone or out of access scope — retry can't succeed.
+      throw fileNotFound(id);
     }
 
     await assertAccess("design", file.designId, "editor");
@@ -232,7 +248,9 @@ export default defineAction({
           .where(eq(schema.designFiles.id, id))
           .limit(1);
         if (!persistedFile) {
-          throw new Error(`File not found: ${id}`);
+          // Delete-race: the row passed the access check but is gone now.
+          // Same 404 as the outer guard, not a bare 500 the outbox retries.
+          throw fileNotFound(id);
         }
 
         const persistedContentHash = sourceContentHash(persistedFile.content);
@@ -390,9 +408,47 @@ export default defineAction({
                 skippedStaleMirror = true;
               }
             } else {
-              throw new Error(
+              const liveContentHash = sourceContentHash(liveContent);
+              // Diagnostic probe (never affects the outcome): `getText` read this
+              // instance's Y.Doc cache, never re-hydrated from the DB. Compare it
+              // to the freshly persisted text_snapshot so the log distinguishes a
+              // multi-instance stale cache (cacheIsStale) from a genuine writer.
+              let freshDbLiveHash: string | null = null;
+              try {
+                const { rows } = await getDbExec().execute({
+                  sql: "SELECT text_snapshot FROM _collab_docs WHERE doc_id = ?",
+                  args: [id],
+                });
+                if (rows.length > 0) {
+                  freshDbLiveHash = sourceContentHash(
+                    String(rows[0]?.text_snapshot ?? ""),
+                  );
+                }
+              } catch {
+                // diagnostic only
+              }
+              logSaveConflictDebug("content-conflict", {
+                id,
+                caller: context?.caller,
+                syncCollab,
+                operationRevision: operationRevision ?? null,
+                expectedVersionHash,
+                sentContentHash: sourceContentHash(content),
+                liveContentHash,
+                persistedMirrorHash: persistedContentHash,
+                cacheIsStale:
+                  freshDbLiveHash !== null &&
+                  freshDbLiveHash !== liveContentHash,
+                freshDbMatchesExpected: freshDbLiveHash === expectedVersionHash,
+              });
+              // 409 (statusCode), not a bare 500: an expected optimistic-
+              // concurrency outcome the framework returns verbatim and the client
+              // rebases from, instead of a Sentry-captured fault + retry storm.
+              const conflict = new Error(
                 "File changed since it was read. Re-read the file and retry.",
-              );
+              ) as Error & { statusCode?: number };
+              conflict.statusCode = 409;
+              throw conflict;
             }
           }
         }
@@ -461,7 +517,9 @@ export default defineAction({
             // guarded UPDATE alone can still race. Serialize design-file renames in
             // this rare path without using SQLite's fragile async savepoint wrapper.
             await (
-              tx as unknown as { execute: (query: unknown) => Promise<unknown> }
+              tx as unknown as {
+                execute: (query: unknown) => Promise<unknown>;
+              }
             ).execute(sql`LOCK TABLE design_files IN SHARE ROW EXCLUSIVE MODE`);
             const [collision] = await tx
               .select({ id: schema.designFiles.id })
@@ -545,7 +603,7 @@ export default defineAction({
             .from(schema.designFiles)
             .where(eq(schema.designFiles.id, id))
             .limit(1);
-          if (!confirmed) throw new Error(`File not found: ${id}`);
+          if (!confirmed) throw fileNotFound(id);
           const confirmedHash = sourceContentHash(confirmed.content);
           const exactOperationPersisted =
             confirmed.contentOperationSource === operationSource &&
@@ -622,9 +680,18 @@ export default defineAction({
         }
         return;
       }
-      throw new Error(
+      logSaveConflictDebug("retry-exhausted", {
+        id,
+        caller: context?.caller,
+        operationSource: operationSource ?? null,
+        operationRevision: operationRevision ?? null,
+        expectedVersionHash,
+      });
+      const exhausted = new Error(
         "File changed repeatedly while it was being saved. Re-read the file and retry.",
-      );
+      ) as Error & { statusCode?: number };
+      exhausted.statusCode = 409;
+      throw exhausted;
     });
 
     // Update the parent design's updatedAt timestamp. This still runs even

package/corpus/templates/design/app/lib/design-save-outbox.ts

@@ -37,6 +37,14 @@ export interface DrainDesignSaveOutboxResult {
    * transient/conflict errors that SHOULD be retried.
    */
   dropped: Array<{ entry: DesignSaveOutboxEntry; error: unknown }>;
+  /**
+   * Entries dropped because the server moved past their base version (a 409
+   * conflict). Distinct from `dropped`: the file still exists and nothing was
+   * lost to deletion, so the editor should rebase from the server rather than
+   * warn "changes discarded". Kept separate so a normal concurrent edit is
+   * never presented as a deleted file.
+   */
+  rebased: Array<{ entry: DesignSaveOutboxEntry; error: unknown }>;
 }
 
 /**
@@ -58,6 +66,24 @@ export function isTerminalSaveError(error: unknown): boolean {
   );
 }
 
+/**
+ * The server's update-file version conflict ("File changed since it was read…").
+ * Its frozen expectedVersionHash can never match on retry, so drop-and-rebase
+ * rather than loop forever. Matched by MESSAGE, not bare status 409, on purpose:
+ * the client-side "no known base version" / "changed elsewhere" 409 synthetics
+ * are intentionally retained by drainEntries, and the client-build-mismatch 409
+ * is a reload-then-retry.
+ */
+export function isConflictSaveError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const candidate = error as { code?: unknown; message?: unknown };
+  if (candidate.code === "client_build_mismatch") return false;
+  return (
+    typeof candidate.message === "string" &&
+    /changed since it was read|re-read the file/i.test(candidate.message)
+  );
+}
+
 const DATABASE_NAME = "agent-native-design-save-outbox";
 const DATABASE_VERSION = 2;
 const ENTRY_STORE = "entries";
@@ -324,6 +350,7 @@ async function drainEntries(
     saved: [],
     failed: [],
     dropped: [],
+    rebased: [],
   };
   for (const entry of await storage.list(designId, actorScope)) {
     try {
@@ -374,6 +401,18 @@ async function drainEntries(
             `[design-save-outbox] dropped unrecoverable save for ${entry.actionName} ${entry.resourceId} (file no longer exists)`,
           );
         }
+      } else if (isConflictSaveError(error)) {
+        // Base version superseded — retry is futile and replaying the stale
+        // snapshot would clobber newer content. Drop into `rebased` (NOT
+        // `dropped`) so the editor rebases from the server instead of warning
+        // that the file was discarded/deleted.
+        await storage.deleteIfRevision(entry);
+        result.rebased.push({ entry, error });
+        if (typeof console !== "undefined") {
+          console.warn(
+            `[design-save-outbox] rebased superseded save for ${entry.actionName} ${entry.resourceId} (server content moved on)`,
+          );
+        }
       } else {
         result.failed.push({ entry, error });
       }

package/corpus/templates/slides/app/components/editor/EditorToolbar.tsx

@@ -29,6 +29,7 @@ import {
   IconAdjustments,
   IconPencilPlus,
   IconPin,
+  IconLetterT,
   IconWand,
   IconUpload,
   IconSun,
@@ -123,6 +124,10 @@ interface EditorToolbarProps {
   pinMode?: boolean;
   /** Toggle comment-pin drop mode */
   onTogglePinMode?: () => void;
+  /** Whether the add-text-box tool is active */
+  textBoxMode?: boolean;
+  /** Toggle the add-text-box tool */
+  onToggleTextBoxMode?: () => void;
   /** Duplicate the current deck */
   onDuplicateDeck?: () => void;
   /** Export the deck as PDF */
@@ -247,6 +252,8 @@ export default function EditorToolbar({
   onToggleDrawMode,
   pinMode,
   onTogglePinMode,
+  textBoxMode,
+  onToggleTextBoxMode,
   onDuplicateDeck,
   onExportPdf,
   onExportPptx,
@@ -305,10 +312,10 @@ export default function EditorToolbar({
   const [themeMounted, setThemeMounted] = useState(false);
   useEffect(() => setThemeMounted(true), []);
   const isDark = themeMounted ? resolvedTheme === "dark" : false;
-  // The four secondary tools share an "active when something is on" indicator
-  // so the dot on the consolidated button reflects any of them.
+  // The secondary tools share an "active when something is on" indicator so
+  // the dot on the consolidated button reflects any of them.
   const anyToolActive = Boolean(
-    animationsOpen || tweaksOpen || drawMode || pinMode,
+    animationsOpen || tweaksOpen || drawMode || pinMode || textBoxMode,
   );
 
   const closeAll = () => {
@@ -731,7 +738,8 @@ graph TD
         (onToggleAnimations ||
           onToggleTweaks ||
           onToggleDrawMode ||
-          onTogglePinMode) && (
+          onTogglePinMode ||
+          onToggleTextBoxMode) && (
           <>
             <Tooltip>
               <TooltipTrigger asChild>
@@ -834,6 +842,23 @@ graph TD
                     </span>
                   </button>
                 )}
+                {onToggleTextBoxMode && (
+                  <button
+                    onClick={() => {
+                      onToggleTextBoxMode();
+                      setToolsOpen(false);
+                    }}
+                    data-toolbar-textbox-button
+                    className={`flex items-center gap-2 w-full px-3 py-1.5 text-xs transition-colors ${
+                      textBoxMode
+                        ? "text-foreground bg-accent/50"
+                        : "text-muted-foreground hover:text-foreground hover:bg-accent/50"
+                    }`}
+                  >
+                    <IconLetterT className="w-3.5 h-3.5" />
+                    {t("editorToolbar.addTextBox")}
+                  </button>
+                )}
               </div>
             </ToolbarPopover>
           </>