@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/shared/lib/fs/file-kind-classify.test.ts

@@ -28,6 +28,7 @@ import {
   PDF_MAX_FILE_BYTES,
   unsupportedEditorMessage,
 } from '@/shared/lib/fs/file-kind';
+import { formatBytes } from '@/shared/lib/format/number';
 
 const bytes = (...values: number[]): Uint8Array => new Uint8Array(values);
 
@@ -96,8 +97,11 @@ describe('classifyEditorFile', () => {
 
   // The document ceiling does not reach plain text: a 6 MB source file is still
   // refused, because a textarea holds that buffer for the life of the tab.
-  test('plain text keeps the text ceiling', () => {
-    expect(classifyEditorFile({ path: 'big.ts', size: 6 * 1024 * 1024 })).toBe('too-large');
+  test('plain text keeps the text ceiling, which a real source file clears', () => {
+    // 6 MB was over the old 5 MiB ceiling and is a normal generated file, not a
+    // refusal. The ceiling moved; this case is what keeps it from moving back.
+    expect(classifyEditorFile({ path: 'big.ts', size: 6 * 1024 * 1024 })).toBe('text');
+    expect(classifyEditorFile({ path: 'big.log', size: EDITOR_MAX_FILE_BYTES })).toBe('text');
     expect(classifyEditorFile({ path: 'big.log', size: EDITOR_MAX_FILE_BYTES + 1 })).toBe('too-large');
   });
 
@@ -120,24 +124,34 @@ describe('unsupportedEditorMessage', () => {
   });
 
   test('a size refusal names both the actual size and the ceiling', () => {
-    const message = unsupportedEditorMessage('too-large', 9 * 1024 * 1024);
-    expect(message).toContain('9.00 MB');
-    expect(message).toContain('5.00 MB');
+    // Derived, never spelled out: the point of the sentence is that its number
+    // is the one the classifier applied, so a literal here would pass while the
+    // two disagreed.
+    const message = unsupportedEditorMessage('too-large', 40 * 1024 * 1024);
+    expect(message).toContain('40.00 MB');
+    expect(message).toContain(formatBytes(EDITOR_MAX_FILE_BYTES));
   });
 
   test('a size refusal without a measured size names only the ceiling', () => {
     const message = unsupportedEditorMessage('too-large');
-    expect(message).toContain('5.00 MB');
+    expect(message).toContain(formatBytes(EDITOR_MAX_FILE_BYTES));
     expect(message).not.toContain('undefined');
   });
 
+  test('the text ceiling leaves room for a real source file and stops short of the knee', () => {
+    // 32 MiB: measured, the last size before a tab's heap crosses a gigabyte and
+    // a 64 MB file stops opening at all (see the constant's own table).
+    expect(EDITOR_MAX_FILE_BYTES).toBe(32 * 1024 * 1024);
+    expect(EDITOR_MAX_FILE_BYTES).toBeGreaterThan(DOCUMENT_MAX_FILE_BYTES);
+  });
+
   // The sentence names the number the classifier actually applied: a PDF is
-  // refused against 30 MB, so telling the user "5.00 MB" would describe a limit
-  // the file was never measured against.
-  test('a PDF size refusal names the PDF ceiling', () => {
+  // refused against its own ceiling, so naming the text one would describe a
+  // limit the file was never measured against.
+  test('a PDF size refusal names the PDF ceiling, not the text one', () => {
     const message = unsupportedEditorMessage('too-large', 31 * 1024 * 1024, 'docs/report.pdf');
     expect(message).toContain('31.00 MB');
-    expect(message).toContain('30.00 MB');
-    expect(message).not.toContain('5.00 MB');
+    expect(message).toContain(formatBytes(PDF_MAX_FILE_BYTES));
+    expect(message).not.toContain(formatBytes(EDITOR_MAX_FILE_BYTES));
   });
 });

package/src/shared/lib/fs/file-kind.ts

@@ -143,16 +143,43 @@ export function getImageMimeFromBytes(bytes: Uint8Array): string | null {
 }
 
 /**
- * The largest file the editor will open when its bytes reach the page WHOLE.
+ * The largest text file the editor will open when its bytes reach the page
+ * WHOLE.
  *
- * Not a policy knob: the editor holds the whole file in one string and posts
- * the whole thing back on every save, so a ceiling has to exist. 5 MiB is above
- * any source file and well below the size at which a textarea stops responding.
+ * Not a policy knob: the editor holds the whole file in one string, CodeMirror
+ * holds a second representation of it, and the whole thing is posted back on
+ * every save — so a ceiling has to exist.
  *
- * A DOCX and an XLSX are parsed in the page too, but they get their own, higher
- * number — see `DOCUMENT_MAX_FILE_BYTES`.
+ * **32 MiB, measured.** The number used to be 5 MiB, and its justification died
+ * with the `<textarea>`: that limit existed because a textarea stops responding,
+ * and the surface is CodeMirror 6 now. Re-measured on the assembled app (a
+ * generated source file, Files panel open, Chromium):
+ *
+ * | File | Open | Keystroke | Save | JS heap |
+ * |---|---|---|---|---|
+ * | 5 MB | 99 ms | 17 ms | 289 ms | 73 MB |
+ * | 10 MB | 147 ms | 32 ms | 494 ms | 73 MB |
+ * | 20 MB | 212 ms | 34 ms | 969 ms | 73 MB |
+ * | 30 MB | 323 ms | 39 ms | 2 292 ms | — |
+ * | 40 MB | 283 ms | 45 ms | 1 793 ms | — |
+ * | 50 MB | 372 ms | 72 ms | 2 228 ms | **1 078 MB** |
+ * | 64 MB | never finished loading | — | — | — |
+ *
+ * The curve is flat through 40 MB and breaks at 50: the heap goes from a few
+ * hundred megabytes to over a gigabyte for ONE tab, and a 64 MB file does not
+ * open at all. 32 MiB is the last size with a comfortable margin below that
+ * knee — ten times any source file, and the point past which a tab is a risk to
+ * every other tab in the browser rather than a convenience.
+ *
+ * Two costs had to be removed before this number was reachable, and both were
+ * linear-in-file-size work paid per keystroke: the outline's scan-and-render of
+ * every declaration (`outline/rows.ts`), and a full `doc.toString()` on every
+ * render (`code-surface/index.tsx`).
+ *
+ * A DOCX and an XLSX are parsed in the page too, but they get their own number —
+ * see `DOCUMENT_MAX_FILE_BYTES`.
  */
-export const EDITOR_MAX_FILE_BYTES = 5 * 1024 * 1024;
+export const EDITOR_MAX_FILE_BYTES = 32 * 1024 * 1024;
 
 /**
  * The largest Word document or workbook the editor opens.
@@ -160,9 +187,10 @@ export const EDITOR_MAX_FILE_BYTES = 5 * 1024 * 1024;
  * `mammoth` and `read-excel-file` parse the fetched `ArrayBuffer` in the page,
  * so the file does sit in memory — but it is unzipped and converted once and
  * then released, where a text buffer is held for as long as the tab is open and
- * re-posted on every save. That is why these get four times the text ceiling
- * rather than the text ceiling itself: the reason the 5 MiB limit exists (a
- * textarea that stops responding) does not apply to a read-only conversion.
+ * re-posted on every save. That is why these get a ceiling of their own rather
+ * than the text one: the reason the text limit exists (a buffer that must stay
+ * editable, and a save that re-posts it) does not apply to a read-only
+ * conversion.
  *
  * Measured on a 15 MB workbook: the fetch, the unzip and the grid render all
  * complete, and the panel stays responsive.
@@ -170,8 +198,13 @@ export const EDITOR_MAX_FILE_BYTES = 5 * 1024 * 1024;
 export const DOCUMENT_MAX_FILE_BYTES = 20 * 1024 * 1024;
 
 /**
- * The largest PDF the editor opens — above both, because a PDF is the one
- * document the page never holds.
+ * The largest PDF the editor opens.
+ *
+ * Its own number rather than the text ceiling, because a PDF is the one document
+ * the page never holds — and the only one whose limit is not about a buffer at
+ * all (see below). It is no longer the largest of the three: the TEXT ceiling
+ * moved past it, which is fine because the two numbers answer different
+ * questions rather than ranking a shared budget.
  *
  * `PdfView` points an `<iframe>` at `/api/fs/raw`, so the bytes go straight to
  * Chrome's own viewer, which fetches them with range requests (verified: a
@@ -180,7 +213,8 @@ export const DOCUMENT_MAX_FILE_BYTES = 20 * 1024 * 1024;
  * Nothing in Kabmo buffers the file, so the text ceiling has no reason to
  * apply to it — and applying it was the bug: a 6 MB PDF dragged from Finder was
  * refused as "larger than the 5.00 MB the editor opens" before the document
- * branch was ever reached, because the size test runs first.
+ * branch was ever reached, because the size test runs first. The 30 MB here is
+ * Chrome's own plugin's comfort zone, not Kabmo's memory.
  */
 export const PDF_MAX_FILE_BYTES = 30 * 1024 * 1024;
 

package/src/shared/lib/fs/file-url.test.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `pathFromFileUrl` — the platform-specific half of a dropped-file reference.
+ *
+ * Pinned here rather than through the scope route because the Windows case is
+ * invisible on the machine this repository is developed on: the route's own test
+ * is `testPosix`, so the drive-letter branch had no test at all until a Windows
+ * CI run refused every dropped file.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { pathFromFileUrl } from '@/shared/lib/fs/file-url';
+
+describe('pathFromFileUrl', () => {
+  test('a POSIX file URL decodes to the path it names', () => {
+    expect(pathFromFileUrl('file:///tmp/x/b.ts')).toBe('/tmp/x/b.ts');
+  });
+
+  test('a percent-encoded space is decoded', () => {
+    expect(pathFromFileUrl('file:///tmp/x/My%20Notes.md')).toBe('/tmp/x/My Notes.md');
+  });
+
+  test('a Windows drive letter loses the leading slash, in every spelling', () => {
+    // All three forms answer `/C:/…` from `new URL().pathname`, and a leading
+    // slash on win32 resolves against the CURRENT DRIVE's root — a path no
+    // workspace contains.
+    expect(pathFromFileUrl('file:///C:/Users/x/b.ts')).toBe('C:/Users/x/b.ts');
+    expect(pathFromFileUrl('file://C:/Users/x/b.ts')).toBe('C:/Users/x/b.ts');
+    expect(pathFromFileUrl('file://C:\\Users\\x\\b.ts')).toBe('C:/Users/x/b.ts');
+  });
+
+  test('a percent-encoded drive path is decoded before the slash is dropped', () => {
+    expect(pathFromFileUrl('file:///D:/a/My%20Notes.md')).toBe('D:/a/My Notes.md');
+  });
+
+  test('a path that is not a file URL is refused rather than guessed at', () => {
+    expect(pathFromFileUrl('/tmp/x/b.ts')).toBeNull();
+    expect(pathFromFileUrl('https://example.com/x.ts')).toBeNull();
+  });
+
+  test('a malformed escape is refused, not thrown', () => {
+    expect(pathFromFileUrl('file:///tmp/%E0%A4%A')).toBeNull();
+  });
+
+  test('a lowercase drive letter is kept as written', () => {
+    expect(pathFromFileUrl('file:///c:/x/b.ts')).toBe('c:/x/b.ts');
+  });
+});

package/src/shared/lib/fs/file-url.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A `file://` URL to the path it names.
+ *
+ * Shared rather than private to the scope route, because the transformation is
+ * platform-specific and a private copy can only be exercised on the platform it
+ * was written on: the Windows branch below was wrong for as long as it lived
+ * inside a route whose test skipped Windows.
+ *
+ * Two rules, both measured:
+ *
+ * - **The pathname is percent-encoded** — a space is `%20`, and a Finder drop of
+ *   `My Notes.md` is exactly that — so decoding is not optional.
+ *   `decodeURIComponent` throws on a malformed escape, which is answered as
+ *   "not a path" rather than surfacing as a 500.
+ * - **A WINDOWS drive letter loses its leading slash.** `new URL('file://C:\a\b.ts')`
+ *   and the canonical `file:///C:/a/b.ts` BOTH answer `/C:/a/b.ts`, and
+ *   `path.resolve` on win32 turns that into `\C:\a\b.ts` — a path under the
+ *   current DRIVE's root, which no workspace contains. On the Windows CI leg
+ *   every dropped file was refused with "outside every workspace", so a file
+ *   dropped on the editor opened nothing at all. `fileURLToPath` drops the same
+ *   slash; this does it without a `node:url` import in a shared module.
+ */
+export function pathFromFileUrl(reference: string): string | null {
+  if (!/^file:\/\//i.test(reference)) return null;
+  try {
+    const pathname = decodeURIComponent(new URL(reference).pathname);
+    // `/C:/…` → `C:/…`; `/tmp/…` is left alone.
+    return /^\/[A-Za-z]:[\\/]/.test(pathname) ? pathname.slice(1) : pathname;
+  } catch {
+    return null;
+  }
+}

package/src/shared/lib/fs/patch-sides.test.ts

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A unified patch → the two documents it compares.
+ *
+ * What this pins is the shape a chat tool card depends on: a card has a PATCH
+ * and no files, and it draws the same merge surface the diff panel does — so the
+ * sides it hands over must be exactly what the patch says they were. A context
+ * row belongs to both, a `-` row only to the original, a `+` row only to the new
+ * one; everything else (the `diff --git` header, `index`, `---`/`+++`, mode and
+ * rename lines, the "No newline" marker) is metadata and must not appear in
+ * either document.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { patchSides } from '@/shared/lib/fs/patch-sides';
+
+const GIT_DIFF = [
+  'diff --git a/src/a.ts b/src/a.ts',
+  'index 1111111..2222222 100644',
+  '--- a/src/a.ts',
+  '+++ b/src/a.ts',
+  '@@ -1,3 +1,3 @@',
+  ' const one = 1;',
+  '-const two = 2;',
+  '+const two = 22;',
+  ' const three = 3;',
+  '',
+].join('\n');
+
+describe('patchSides', () => {
+  test('splits a git diff into the documents it compares', () => {
+    const sides = patchSides(GIT_DIFF);
+
+    expect(sides.original).toBe('const one = 1;\nconst two = 2;\nconst three = 3;');
+    expect(sides.next).toBe('const one = 1;\nconst two = 22;\nconst three = 3;');
+    expect(sides.additions).toBe(1);
+    expect(sides.deletions).toBe(1);
+    expect(sides.hasHunk).toBe(true);
+  });
+
+  test('keeps the header lines out of both documents', () => {
+    // A `--- a/x` header would otherwise land in the original as `-- a/x`, and
+    // the merge view would draw a chunk that is not a change.
+    const sides = patchSides(GIT_DIFF);
+    for (const line of ['diff --git', 'index ', '--- a/', '+++ b/']) {
+      expect(sides.original.includes(line)).toBe(false);
+      expect(sides.next.includes(line)).toBe(false);
+    }
+  });
+
+  test('a new file has an empty original and the whole new document', () => {
+    const sides = patchSides(['@@ -0,0 +1,2 @@', '+alpha', '+beta'].join('\n'));
+
+    expect(sides.original).toBe('');
+    expect(sides.next).toBe('alpha\nbeta');
+    expect(sides.additions).toBe(2);
+    expect(sides.deletions).toBe(0);
+  });
+
+  test('a deleted file is the mirror image', () => {
+    const sides = patchSides(['@@ -1,1 +0,0 @@', '-gone'].join('\n'));
+
+    expect(sides.original).toBe('gone');
+    expect(sides.next).toBe('');
+    expect(sides.deletions).toBe(1);
+  });
+
+  test('a header-only patch has no rows, so the caller can fall back to text', () => {
+    const sides = patchSides('--- a/x\n+++ b/x\n');
+
+    expect(sides.rows).toBe(0);
+    expect(sides.hasHunk).toBe(false);
+  });
+
+  test('an empty patch is the empty answer, not a one-line document', () => {
+    expect(patchSides('')).toEqual({ original: '', next: '', additions: 0, deletions: 0, rows: 0, hasHunk: false });
+    expect(patchSides('   \n')).toEqual({ original: '', next: '', additions: 0, deletions: 0, rows: 0, hasHunk: false });
+  });
+
+  test('counts rows without the blank line a trailing newline leaves behind', () => {
+    const sides = patchSides(['@@ -1 +1 @@', '-a', '+b'].join('\n'));
+
+    expect(sides.rows).toBe(2);
+  });
+
+  test('a hunk starting mid-file keeps its real line numbers', () => {
+    // Without the padding the change would be line 1 of the rebuilt document,
+    // and the card's gutter would name a line the file does not have it on.
+    const sides = patchSides(['@@ -43,2 +43,2 @@', ' context', '-old', '+new'].join('\n'));
+
+    expect(sides.original.split('\n')).toHaveLength(44);
+    expect(sides.original.split('\n')[42]).toBe('context');
+    expect(sides.original.split('\n')[43]).toBe('old');
+    expect(sides.next.split('\n')[43]).toBe('new');
+  });
+
+  test('the gap between two hunks is restored from their own headers', () => {
+    const sides = patchSides(
+      ['@@ -2,1 +2,1 @@', '-a', '+b', '@@ -10,1 +10,1 @@', '-c', '+d'].join('\n'),
+    );
+
+    // Line 2 is the first change, line 10 the second, and everything between is
+    // unchanged content the patch did not carry.
+    const original = sides.original.split('\n');
+    expect(original[1]).toBe('a');
+    expect(original[9]).toBe('c');
+    expect(original).toHaveLength(10);
+  });
+});

package/src/shared/lib/fs/patch-sides.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A unified patch as its two DOCUMENTS.
+ *
+ * This replaced a table parser (`diff-parser.ts`) that produced per-row line
+ * numbers and paired split-view rows. Both of those are now the merge view's
+ * job — `@codemirror/merge` computes the alignment itself from two documents —
+ * so the only thing still needed from a patch is what the two sides were.
+ *
+ * That matters in one place: a chat tool card has a PATCH and no documents, and
+ * the card draws the same merge surface the diff panel does. Reconstructing the
+ * sides here keeps one renderer for both, instead of the card growing a second
+ * diff implementation that drifts.
+ *
+ * **The gap between hunks is restored as blank lines, and that is what keeps the
+ * gutter honest.** A hunk header names the line it starts on (`@@ -43,7 +43,8`),
+ * and a document rebuilt by concatenating hunks would number the change from 1.
+ * Padding each side up to the header's own counters puts the change back on the
+ * line the file has it on — and because the padding is unchanged content, the
+ * merge view collapses it into one marker (`contentMode: 'diff'`).
+ *
+ * The counters are the patch's own (`+`/`-` rows, hunk headers excluded), which
+ * is what the card's header prints. The diff panel deliberately does NOT use
+ * them: it has the real documents, and its counts must describe the rows the
+ * merge view actually draws (a collapsed or whitespace-folded change is not a
+ * changed row on screen).
+ */
+
+/** One side's text, and what the patch said about it. */
+export interface PatchSides {
+  /** The document before the change, with the hunk gaps as blank lines. */
+  original: string;
+  /** The document after it, the same way. */
+  next: string;
+  additions: number;
+  deletions: number;
+  /** Content rows the patch produced — zero for a header-only or empty patch. */
+  rows: number;
+  /** The patch named at least one hunk (`@@`), so it is a real diff. */
+  hasHunk: boolean;
+}
+
+const EMPTY: PatchSides = { original: '', next: '', additions: 0, deletions: 0, rows: 0, hasHunk: false };
+
+/** Header lines that describe the patch rather than its content. */
+const HEADER_PREFIXES = [
+  'diff --git',
+  'index ',
+  '---',
+  '+++',
+  'new file mode',
+  'deleted file mode',
+  'similarity index',
+  'dissimilarity index',
+  'rename from',
+  'rename to',
+  'copy from',
+  'copy to',
+  'old mode',
+  'new mode',
+  '\\ No newline',
+];
+
+/** `@@ -43,7 +43,8 @@` → the two starting lines; anything else → null. */
+function hunkStarts(line: string): { old: number; next: number } | null {
+  const match = line.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+  if (!match) return null;
+  return { old: Number(match[1]), next: Number(match[2]) };
+}
+
+/** Pad `lines` with blanks until it holds `count` lines. */
+function padTo(lines: string[], count: number): void {
+  while (lines.length < count) lines.push('');
+}
+
+export function patchSides(patch: string): PatchSides {
+  if (!patch.trim()) return EMPTY;
+
+  const before: string[] = [];
+  const after: string[] = [];
+  let additions = 0;
+  let deletions = 0;
+  let rows = 0;
+  let hasHunk = false;
+
+  const lines = patch.split(/\r?\n/);
+  // A patch ends with a newline, and `split` turns that into a final empty
+  // string. It is the terminator, not a blank row: keeping it put an empty line
+  // at the end of BOTH documents, which the merge view drew as a chunk.
+  if (lines[lines.length - 1] === '') lines.pop();
+
+  for (const raw of lines) {
+    if (HEADER_PREFIXES.some((prefix) => raw.startsWith(prefix))) continue;
+
+    if (raw.startsWith('@@')) {
+      hasHunk = true;
+      const starts = hunkStarts(raw);
+      // `-0,0` (a new file) has no original line to reach, and `padTo` is a
+      // no-op for it because the count is below what is already there.
+      if (starts) {
+        padTo(before, starts.old - 1);
+        padTo(after, starts.next - 1);
+      }
+      continue;
+    }
+
+    if (raw.startsWith('+')) {
+      additions++;
+      rows++;
+      after.push(raw.slice(1));
+      continue;
+    }
+    if (raw.startsWith('-')) {
+      deletions++;
+      rows++;
+      before.push(raw.slice(1));
+      continue;
+    }
+    // A context row (` ` prefix) is on BOTH sides; a bare line is what a
+    // header-less patch carries, and it is context too.
+    const text = raw.startsWith(' ') ? raw.slice(1) : raw;
+    rows++;
+    before.push(text);
+    after.push(text);
+  }
+
+  return {
+    original: before.join('\n'),
+    next: after.join('\n'),
+    additions,
+    deletions,
+    rows,
+    hasHunk,
+  };
+}

package/src/shared/lib/realtime/protocol.ts

@@ -45,6 +45,22 @@ export const TOPIC_SIDEBAR = 'sidebar';
  *  the structure needs a JSONL scan to produce. */
 export const TOPIC_SIDEBAR_STATUS = 'sidebar:status';
 
+/**
+ * The last-activity stamp of each session with a run IN FLIGHT, keyed by id.
+ *
+ * Split from `sidebar` for the same reason `sidebar:status` is, but the cost
+ * difference is far larger: a transcript grows on every tool call, so this
+ * changes per tool call while the structure is a 216 KB payload over 731
+ * sessions (measured on the author's install) that must be re-scanned to
+ * produce. Only a RUNNING session's stamp can move between turn boundaries, so
+ * only those are carried — the payload is one ISO string per live run
+ * (measured: 87 bytes for one), against 216 KB for the whole list.
+ *
+ * The structure remains the authority for every other row; this only ever
+ * ADVANCES a stamp the structure already carries (see `applySidebarActivity`).
+ */
+export const TOPIC_SIDEBAR_ACTIVITY = 'sidebar:activity';
+
 /** One session's live conversation: agent frames, queue and modes. */
 export function sessionTopic(sessionId: string): string {
   return `session:${sessionId}`;

package/src/shared/lib/ui/toolbar-overflow.test.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `⋯` rule, asserted as arithmetic.
+ *
+ * Each case is a failure the toolbars had: a row that wrapped into two rows
+ * instead of hiding a control, a control hidden while the width was still
+ * unknown (a menu flashing on every mount), and a pinned control buried in the
+ * menu because the row happened to be narrow.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  TOOLBAR_ITEM_GAP_PX,
+  TOOLBAR_OVERFLOW_TRIGGER_PX,
+  toolbarHasOverflow,
+  toolbarVisibleClusters,
+} from '@/shared/lib/ui/toolbar-overflow';
+
+/** Save, find, wrap, zoom, copy, modes, full screen — the editor's real row. */
+const widths = [26, 26, 26, 52, 52, 52, 26];
+const pinned = [true, false, false, false, false, true, true];
+
+/** Row width needed to draw `visible` plus the trigger when anything is hidden. */
+function rowWidth(visible: boolean[]): number {
+  const shown = widths.filter((_, index) => visible[index]);
+  const overflow = toolbarHasOverflow(visible);
+  return (
+    shown.reduce((sum, width) => sum + width, 0) +
+    TOOLBAR_ITEM_GAP_PX * Math.max(0, shown.length - 1) +
+    (overflow ? TOOLBAR_OVERFLOW_TRIGGER_PX + TOOLBAR_ITEM_GAP_PX : 0)
+  );
+}
+
+describe('toolbarVisibleClusters', () => {
+  test('an unmeasured row shows every cluster', () => {
+    // Not "hide everything": the row is measured a layout effect later, and a
+    // menu that flashes on every mount is worse than one frame of a full row.
+    expect(toolbarVisibleClusters({ widths, pinned, available: 0 }).every(Boolean)).toBe(true);
+  });
+
+  test('a row wide enough for everything shows everything, with no trigger', () => {
+    const total = widths.reduce((sum, width) => sum + width, 0) + TOOLBAR_ITEM_GAP_PX * (widths.length - 1);
+    const visible = toolbarVisibleClusters({ widths, pinned, available: total });
+    expect(visible.every(Boolean)).toBe(true);
+    expect(toolbarHasOverflow(visible)).toBe(false);
+  });
+
+  test('a narrow row hides what does not fit and reserves the trigger', () => {
+    // 200px of row: the three pinned clusters (26 + 52 + 26) plus their gaps
+    // leave room for one unpinned control and the `⋯` trigger, and no more.
+    const visible = toolbarVisibleClusters({ widths, pinned, available: 200 });
+    expect(toolbarHasOverflow(visible)).toBe(true);
+    // The promise the arithmetic has to keep: what stays plus the trigger fits.
+    expect(rowWidth(visible)).toBeLessThanOrEqual(200);
+  });
+
+  test('a pinned cluster stays on the row at any width', () => {
+    // A 120px row fits one 26px control plus the trigger, and the pinned width
+    // modes (52px) would not fit at all on their own — they stay regardless,
+    // because a menu-only mode button is a mode the reader never finds.
+    const visible = toolbarVisibleClusters({ widths, pinned, available: 120 });
+    expect(visible[0]).toBe(true);
+    expect(visible[5]).toBe(true);
+    expect(visible[6]).toBe(true);
+    // The unpinned controls are what gives way.
+    expect(visible[1]).toBe(false);
+  });
+
+  test('order is preserved: what stays is a subsequence, not a re-sort', () => {
+    const visible = toolbarVisibleClusters({ widths, pinned, available: 200 });
+    const shownIndexes = visible.flatMap((isShown, index) => (isShown ? [index] : []));
+    expect([...shownIndexes].sort((a, b) => a - b)).toEqual(shownIndexes);
+  });
+
+  test('no clusters is no row', () => {
+    expect(toolbarVisibleClusters({ widths: [], pinned: [], available: 500 })).toEqual([]);
+  });
+});