@startsimpli/integrations 0.2.33 → 0.2.35

package/src/__tests__/corpus-folders.test.tsx

@@ -0,0 +1,727 @@
+/**
+ * THE FOLDER TREE (bd startsim-ei8gm.5), over the REAL client and the REAL
+ * tenant contract.
+ *
+ * WHY THE FIXTURE HTTP AND NOT A HAND-WRITTEN `CorpusApi`. The bug this feature
+ * can most easily ship with is not a rendering bug — it is a REQUEST bug, and a
+ * stubbed api hides exactly those. The facet action refuses unknown parameters
+ * (`_Scoped.initial()` screens it against `_FACET_FILTERS`), `has_children`
+ * arrives camel-cased through the app's fetch wrapper, and `__under` is a union
+ * rather than a prefix. So these tests drive `createCorpusApi` over
+ * `createFixtureCorpusHttp`, whose facet route mirrors
+ * `apps/api/filters.py::EntityQuery.facets` including the parts that REFUSE.
+ *
+ * THE THREE THINGS THAT MUST HOLD, in the order they would break:
+ *
+ *   1. NOTHING IS ASSEMBLED IN THE BROWSER (CLAUDE.md rule 8). One request per
+ *      level, paged. A tree that read every document's path would pass a
+ *      rendering test and fail in the low thousands.
+ *   2. NO NODE APPEARS THAT THE SERVER DID NOT RETURN FOR THIS READER. The facet
+ *      read is gated out of `EntityViewSet.get_queryset()`, and a folder name
+ *      leaks plenty on its own — `/Legal/Terminations`. Every level is drawn
+ *      from its own response and nothing is merged across two.
+ *   3. A CONTROL, NEVER A SENTENCE, where the reader is asking what they may do.
+ */
+import { describe, expect, it } from 'vitest';
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { FolderTree, folderTrail } from '../components/FolderTree';
+import { LibraryPage } from '../components/pages/LibraryPage';
+import { createCorpusApi } from '../corpus/client';
+import { toFolder } from '../corpus/entities';
+import {
+  FIXTURE_ORG,
+  FIXTURE_SOURCE_LABELS,
+  createFixtureCorpusHttp,
+} from '../corpus/fixtures';
+import type { CorpusApi, CorpusFolder, CorpusPage, FolderQuery } from '../corpus/types';
+
+const SCOPE = { orgId: FIXTURE_ORG };
+
+/**
+ * A folder ROW by its exact name.
+ *
+ * The accessible name of a node is "<name> <count>", so a loose `/^Contracts/`
+ * also matches `Contracts-old` — which is the very sibling these tests exist to
+ * keep apart. Anchoring both ends is not test hygiene here; a matcher that
+ * conflated them would hide the bug.
+ */
+function folderRow(name: string): RegExp {
+  return new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}, \\d+ documents? inside$`);
+}
+
+/** The real adapter over the fixture tenant, recording every request it makes. */
+function tenant(options: Parameters<typeof createFixtureCorpusHttp>[0] = {}) {
+  const seen: Array<{ path: string; params: Record<string, unknown> }> = [];
+  const { http } = createFixtureCorpusHttp({
+    ...options,
+    onRequest: (path, params) => {
+      seen.push({ path, params });
+      options.onRequest?.(path, params);
+    },
+  });
+  const api = createCorpusApi({
+    http,
+    scope: SCOPE,
+    sourceLabels: FIXTURE_SOURCE_LABELS,
+    // The fixture tenant reports its own `applied_filters`, which is what the
+    // composer's honesty banner reads. Nothing is declared here.
+    resolveParticipants: false,
+  });
+  return { api, seen, facets: () => seen.filter((r) => r.path.includes('facets')) };
+}
+
+// ---------------------------------------------------------------------------
+//  THE WIRE
+// ---------------------------------------------------------------------------
+
+describe('the facet read, as the tenant really answers it', () => {
+  it('asks for one level with the attribute and the container, and nothing else', async () => {
+    const { api, facets } = tenant();
+    await api.listFolders!({ under: '/' });
+
+    expect(facets()).toHaveLength(1);
+    expect(facets()[0].params).toMatchObject({
+      type: 'source_document', attr: 'path', under: '/', page: 1,
+    });
+  });
+
+  it('sends NONE of the document filters, which the facet action would refuse', async () => {
+    // The failure being prevented: reusing the list's parameter builder. The
+    // facet action screens its vocabulary and 400s the whole read on a stray
+    // `occurred_after` — so a Library with a date filter set would lose its
+    // tree, and only in the deployments where somebody used the filters.
+    const { api, facets } = tenant();
+    await api.listFolders!({ under: '/Contracts', page: 2, pageSize: 10 });
+
+    expect(Object.keys(facets()[0].params).sort()).toEqual(
+      ['attr', 'page', 'page_size', 'type', 'under'],
+    );
+  });
+
+  it('returns FULL child paths, which is what goes back out unchanged', async () => {
+    const { api } = tenant();
+    const page = await api.listFolders!({ under: '/Contracts' });
+
+    // `/Contracts/Acme`, not `Acme`. A client that got a bare segment would have
+    // to re-join, which is a small escaping bug in every client that tries.
+    expect(page.results.map((row) => row.path)).toContain('/Contracts/Acme');
+    expect(page.results.map((row) => row.name)).toContain('Acme');
+  });
+
+  it('counts DESCENDANTS, so a collapsed folder reports what is really under it', async () => {
+    const { api } = tenant();
+    const page = await api.listFolders!({ under: '/' });
+    const contracts = page.results.find((row) => row.path === '/Contracts')!;
+
+    // `/Contracts` holds one file of its own and one under `/Contracts/Acme`
+    // and one under `/Contracts/Acme/2026`.
+    expect(contracts.count).toBe(3);
+    expect(contracts.hasChildren).toBe(true);
+  });
+
+  it('never returns a sibling whose name merely starts the same way', async () => {
+    // `/Contracts-old` is the reason `__under` is one parameter and not a
+    // `startswith` a client assembled.
+    const { api } = tenant();
+    const page = await api.listFolders!({ under: '/Contracts' });
+
+    expect(page.results.map((row) => row.path)).not.toContain('/Contracts-old');
+    const root = await api.listFolders!({ under: '/' });
+    expect(root.results.map((row) => row.path)).toContain('/Contracts-old');
+  });
+
+  it('does not turn the files sitting IN a folder into a nameless child folder', async () => {
+    const { api } = tenant();
+    const page = await api.listFolders!({ under: '/Contracts' });
+
+    expect(page.results.map((row) => row.path)).not.toContain('/Contracts/');
+    expect(page.results.every((row) => row.name !== '')).toBe(true);
+  });
+
+  it('reads `has_children` in BOTH spellings, because the browser sees one of them', () => {
+    // `@startsimpli/api`'s fetch wrapper camel-cases every response key. Reading
+    // only the wire spelling renders every folder as a childless leaf — a tree
+    // that silently stops at depth one, in the browser only.
+    expect(toFolder({ value: '/A', count: 2, has_children: true }).hasChildren).toBe(true);
+    expect(toFolder({ value: '/A', count: 2, hasChildren: true }).hasChildren).toBe(true);
+    // Absent means NO, not unknown: a triangle that cannot expand is worse than
+    // no triangle.
+    expect(toFolder({ value: '/A', count: 2 }).hasChildren).toBe(false);
+  });
+});
+
+describe('the document list, bounded by a folder', () => {
+  it('asks for the shelf with attr.path when browsing', async () => {
+    const { api, seen } = tenant();
+    await api.listDocuments({ folder: '/Contracts' });
+
+    const list = seen.filter((r) => !r.path.includes('facets')).pop()!;
+    expect(list.params['attr.path']).toBe('/Contracts');
+    expect(list.params['attr.path__under']).toBeUndefined();
+  });
+
+  it('asks for the SUBTREE with attr.path__under when searching', async () => {
+    const { api, seen } = tenant();
+    await api.listDocuments({ underFolder: '/Contracts' });
+
+    const list = seen.filter((r) => !r.path.includes('facets')).pop()!;
+    expect(list.params['attr.path__under']).toBe('/Contracts');
+    // NEVER BOTH: the list endpoint ANDs its filters, so sending both would
+    // intersect a folder with its own subtree and quietly answer with the shelf.
+    expect(list.params['attr.path']).toBeUndefined();
+  });
+
+  it('the subtree really is a union, not a prefix', async () => {
+    const { api } = tenant();
+    const under = await api.listDocuments({ underFolder: '/Contracts', pageSize: 50 });
+    const titles = under.results.map((document) => document.title);
+
+    // The folder's own file AND the ones below it…
+    expect(titles).toContain('NDA (countersigned).pdf');
+    expect(titles).toContain('Statement of work — phase 2.pdf');
+    // …and not the sibling that merely starts the same way.
+    expect(titles).not.toContain('Superseded MSA 2024.pdf');
+  });
+
+  it('carries the record’s own container through to the row', async () => {
+    const { api } = tenant();
+    const page = await api.listDocuments({ folder: '/Contracts/Acme' });
+    expect(page.results[0].folder).toBe('/Contracts/Acme');
+  });
+});
+
+// ---------------------------------------------------------------------------
+//  THE TREE
+// ---------------------------------------------------------------------------
+
+function tree(api: CorpusApi, onSelect = () => {}) {
+  return render(<FolderTree api={api} selected={null} onSelect={onSelect} />);
+}
+
+describe('FolderTree — one level per request, and only ever one', () => {
+  it('draws the top level from a single request', async () => {
+    const { api, facets } = tenant();
+    tree(api);
+
+    expect(await screen.findByRole('button', { name: folderRow('Contracts') })).toBeInTheDocument();
+    expect(await screen.findByRole('button', { name: folderRow('Decks') })).toBeInTheDocument();
+    await waitFor(() => expect(facets()).toHaveLength(1));
+    expect(facets()[0].params.under).toBe('/');
+  });
+
+  it('does NOT read the corpus to build itself', async () => {
+    // The rejected design, and the one this API exists to remove: page every
+    // document, read `path` off each row, assemble the tree in the browser. It
+    // works at 247 records and expires in the low thousands.
+    const { api, seen } = tenant();
+    tree(api);
+    await screen.findByRole('button', { name: folderRow('Contracts') });
+
+    expect(seen.filter((r) => !r.path.includes('facets'))).toHaveLength(0);
+  });
+
+  it('fetches a child level only when the node is expanded', async () => {
+    const user = userEvent.setup();
+    const { api, facets } = tenant();
+    tree(api);
+
+    await screen.findByRole('button', { name: folderRow('Contracts') });
+    expect(facets()).toHaveLength(1);
+
+    await user.click(screen.getByRole('button', { name: 'Expand Contracts' }));
+
+    await screen.findByRole('button', { name: folderRow('Acme') });
+    await waitFor(() => expect(facets()).toHaveLength(2));
+    // Addressed by the FULL path the first response returned.
+    expect(facets()[1].params.under).toBe('/Contracts');
+  });
+
+  it('goes deeper than one level, which is the whole point of a tree', async () => {
+    const user = userEvent.setup();
+    const { api, facets } = tenant();
+    tree(api);
+
+    await screen.findByRole('button', { name: folderRow('Contracts') });
+    await user.click(screen.getByRole('button', { name: 'Expand Contracts' }));
+    await screen.findByRole('button', { name: 'Expand Acme' });
+    await user.click(screen.getByRole('button', { name: 'Expand Acme' }));
+
+    expect(await screen.findByRole('button', { name: folderRow('2026') })).toBeInTheDocument();
+    expect(facets().map((r) => r.params.under)).toEqual(['/', '/Contracts', '/Contracts/Acme']);
+  });
+
+  it('offers no disclosure control on a leaf, and asks nothing about it', async () => {
+    const { api } = tenant();
+    tree(api);
+
+    // `/Pricing` holds one file and no folders.
+    await screen.findByRole('button', { name: folderRow('Pricing') });
+    expect(screen.queryByRole('button', { name: 'Expand Pricing' })).toBeNull();
+  });
+
+  it('re-expanding a node costs no second request', async () => {
+    const user = userEvent.setup();
+    const { api, facets } = tenant();
+    tree(api);
+
+    await screen.findByRole('button', { name: folderRow('Contracts') });
+    await user.click(screen.getByRole('button', { name: 'Expand Contracts' }));
+    await screen.findByRole('button', { name: folderRow('Acme') });
+    await user.click(screen.getByRole('button', { name: 'Collapse Contracts' }));
+    await user.click(screen.getByRole('button', { name: 'Expand Contracts' }));
+
+    await waitFor(() => expect(facets()).toHaveLength(2));
+  });
+
+  it('pages a wide level instead of asking for all of it', async () => {
+    // Rule 8 applies to FOLDERS too. A directory with 900 subfolders must cost
+    // one page until somebody asks for the next.
+    const user = userEvent.setup();
+    const rows: CorpusFolder[] = Array.from({ length: 7 }, (_, index) => ({
+      path: `/Wide/f${index}`, name: `f${index}`, count: 1, hasChildren: false,
+    }));
+    const asked: FolderQuery[] = [];
+    const paged: CorpusApi = {
+      listDocuments: async () => ({ count: 0, next: null, previous: null, results: [] }),
+      getDocument: async () => { throw new Error('unused'); },
+      listParties: async () => ({ count: 0, next: null, previous: null, results: [] }),
+      listSources: async () => [],
+      async listFolders(query): Promise<CorpusPage<CorpusFolder>> {
+        asked.push(query);
+        const page = query.page ?? 1;
+        return {
+          count: rows.length,
+          next: page * 3 < rows.length ? 'more' : null,
+          previous: null,
+          results: rows.slice((page - 1) * 3, page * 3),
+        };
+      },
+    };
+    render(<FolderTree api={paged} selected={null} onSelect={() => {}} pageSize={3} />);
+
+    await screen.findByRole('button', { name: folderRow('f0') });
+    expect(screen.queryByRole('button', { name: folderRow('f3') })).toBeNull();
+
+    await user.click(screen.getByRole('button', { name: 'Show 4 more folders' }));
+
+    expect(await screen.findByRole('button', { name: folderRow('f3') })).toBeInTheDocument();
+    // Still there — appending page 2 to page 1 of the SAME container.
+    expect(screen.getByRole('button', { name: folderRow('f0') })).toBeInTheDocument();
+    expect(asked.map((query) => query.page)).toEqual([1, 2]);
+  });
+
+  it('renders nothing at all when the corpus cannot enumerate folders', async () => {
+    // A fork built before start-simpli-api#391 has no facet route and answers
+    // 404. A half-drawn tree would be worse than none.
+    const { api } = tenant({ missing: ['facets'] });
+    const { container } = render(
+      <FolderTree api={api} selected={null} onSelect={() => {}} />,
+    );
+
+    await waitFor(() => expect(container.querySelector('nav')).toBeNull());
+  });
+});
+
+describe('a member with a full corpus and NO folders at all', () => {
+  /**
+   * NOT AN ERROR, NOT AN EMPTY CORPUS, AND IT IS THE COMMON CASE. Verified in
+   * production the day this shipped: `jpo@ogmc.ai` reads 51 documents on tandem
+   * and the facet read answers `{"count": 0, "results": []}` — every one of his
+   * records is a Granola meeting note, which has no `path` because it is not a
+   * file. A screen that showed him "no documents", an error, or a broken panel
+   * would be lying about a corpus that is entirely there.
+   *
+   * (The same member's colleague sees `/Demo Day Presentations`, `/ERA22 Shared`
+   * and `/Topmarq` and jpo sees NONE of those NAMES, which is the gate working.)
+   */
+  const pathless: CorpusApi = {
+    listDocuments: async () => ({
+      count: 51, next: null, previous: null, appliedFilters: [],
+      results: [{
+        id: 'n1', title: 'Meeting note 1', body: 'Owners and next steps agreed.',
+        sections: [], occurredAt: null, source: 'granola', sourceLabel: 'Granola',
+        sourceRef: 'not_1', participants: [], scope: SCOPE,
+      }],
+    }),
+    getDocument: async () => { throw new Error('unused'); },
+    listParties: async () => ({ count: 0, next: null, previous: null, results: [] }),
+    listSources: async () => [],
+    listFolders: async () => ({ count: 0, next: null, previous: null, results: [] }),
+  };
+
+  it('still lists every record, under a folder panel that is simply empty', async () => {
+    render(<LibraryPage api={pathless} scope={SCOPE} />);
+
+    expect(await screen.findByText('Meeting note 1')).toBeInTheDocument();
+    expect(await screen.findByText(/51 records/)).toBeInTheDocument();
+    // The panel is THERE and quiet. Not hidden — a member who connects a drive
+    // tomorrow should not watch the layout rearrange — and not apologising.
+    const folders = await screen.findByLabelText('Folders');
+    expect(within(folders).getByRole('button', { name: 'All documents' })).toHaveAttribute(
+      'aria-current', 'true',
+    );
+  });
+
+  it('says nothing about it — no error, no warning, no empty state', async () => {
+    render(<LibraryPage api={pathless} scope={SCOPE} />);
+    await screen.findByText('Meeting note 1');
+
+    expect(screen.queryByRole('alert')).toBeNull();
+    expect(screen.queryByText(/no folders/i)).toBeNull();
+    expect(screen.queryByText(/nothing/i)).toBeNull();
+  });
+
+  it('sends no path filter at all, so a pathless record is never dropped', async () => {
+    // The facet read skips rows with no `path` (`Q(_v__isnull=False)`). If the
+    // top of the tree narrowed to anything — an "unfiled" bucket, `path=""`,
+    // `path=/` — this member's entire corpus would vanish from his own Library.
+    const asked: Array<Record<string, unknown>> = [];
+    render(
+      <LibraryPage
+        api={{ ...pathless, listDocuments: async (query) => {
+          asked.push(query as Record<string, unknown>);
+          return { count: 51, next: null, previous: null, results: [], appliedFilters: [] };
+        } }}
+        scope={SCOPE}
+      />,
+    );
+
+    await waitFor(() => expect(asked.length).toBeGreaterThan(0));
+    expect(asked[0].folder).toBeUndefined();
+    expect(asked[0].underFolder).toBeUndefined();
+  });
+});
+
+describe('FolderTree — nothing is synthesised from another level’s answer', () => {
+  it('shows only what the server returned for the container it was asked about', async () => {
+    // THE LEAK, REBUILT IN THE BROWSER, is the failure this guards. `/Shared` is
+    // visible; `/Legal/Terminations` is a folder this reader's own documents are
+    // not in, so the gated facet read never names it — and nothing in the client
+    // may infer it from anywhere else.
+    const asked: string[] = [];
+    const gated: CorpusApi = {
+      listDocuments: async () => ({ count: 0, next: null, previous: null, results: [] }),
+      getDocument: async () => { throw new Error('unused'); },
+      listParties: async () => ({ count: 0, next: null, previous: null, results: [] }),
+      listSources: async () => [],
+      async listFolders({ under }) {
+        asked.push(under);
+        const byContainer: Record<string, CorpusFolder[]> = {
+          '/': [{ path: '/Shared', name: 'Shared', count: 1, hasChildren: true }],
+          '/Shared': [{ path: '/Shared/Public', name: 'Public', count: 1, hasChildren: false }],
+        };
+        return {
+          count: (byContainer[under] ?? []).length,
+          next: null,
+          previous: null,
+          results: byContainer[under] ?? [],
+        };
+      },
+    };
+    const user = userEvent.setup();
+    render(<FolderTree api={gated} selected={null} onSelect={() => {}} />);
+
+    await screen.findByRole('button', { name: folderRow('Shared') });
+    await user.click(screen.getByRole('button', { name: 'Expand Shared' }));
+    await screen.findByRole('button', { name: folderRow('Public') });
+
+    expect(screen.queryByText(/Terminations/)).toBeNull();
+    expect(asked).toEqual(['/', '/Shared']);
+  });
+
+  it('drops everything it fetched when the principal changes', async () => {
+    // The rows on screen were gated for the OLD reader. Reusing them across a
+    // workspace switch is a stale-folder leak wearing a cache.
+    const forA: CorpusApi = {
+      listDocuments: async () => ({ count: 0, next: null, previous: null, results: [] }),
+      getDocument: async () => { throw new Error('unused'); },
+      listParties: async () => ({ count: 0, next: null, previous: null, results: [] }),
+      listSources: async () => [],
+      listFolders: async () => ({
+        count: 1, next: null, previous: null,
+        results: [{ path: '/OnlyA', name: 'OnlyA', count: 1, hasChildren: false }],
+      }),
+    };
+    const forB: CorpusApi = {
+      ...forA,
+      listFolders: async () => ({
+        count: 1, next: null, previous: null,
+        results: [{ path: '/OnlyB', name: 'OnlyB', count: 1, hasChildren: false }],
+      }),
+    };
+    const view = render(<FolderTree api={forA} selected={null} onSelect={() => {}} />);
+    await screen.findByRole('button', { name: folderRow('OnlyA') });
+
+    view.rerender(<FolderTree api={forB} selected={null} onSelect={() => {}} />);
+
+    await screen.findByRole('button', { name: folderRow('OnlyB') });
+    expect(screen.queryByRole('button', { name: folderRow('OnlyA') })).toBeNull();
+  });
+});
+
+describe('folderTrail', () => {
+  it('names every ancestor of a path the server already returned', () => {
+    expect(folderTrail('/Decks/2022 pitch/fonts')).toEqual([
+      { path: '/Decks', name: 'Decks' },
+      { path: '/Decks/2022 pitch', name: '2022 pitch' },
+      { path: '/Decks/2022 pitch/fonts', name: 'fonts' },
+    ]);
+  });
+
+  it('has nothing to say about the root', () => {
+    expect(folderTrail('/')).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+//  THE LIBRARY, WITH THE TREE IN IT
+// ---------------------------------------------------------------------------
+
+describe('LibraryPage — one list, categorised by folder structure', () => {
+  it('narrows the list to the folder that was clicked, server-side', async () => {
+    const user = userEvent.setup();
+    const { api, seen } = tenant();
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    await screen.findByRole('button', { name: folderRow('Decks') });
+    await user.click(screen.getByRole('button', { name: folderRow('Pricing') }));
+
+    await waitFor(() => {
+      const list = seen.filter((r) => !r.path.includes('facets')).pop()!;
+      expect(list.params['attr.path__under']).toBe('/Pricing');
+    });
+    expect(await screen.findByText('Rate card 2026')).toBeInTheDocument();
+    await waitFor(() =>
+      expect(screen.queryByText('Poppins-BoldItalic.ttf')).toBeNull());
+  });
+
+  it('a CONTAINER folder lists what is under it, not an empty shelf', async () => {
+    // THE BUG THIS PINS, seen in the browser before it was fixed: the sidebar
+    // said "Decks 8" and the screen said "0 records" under the sentence
+    // "Nothing matches those filters. Clear them to see everything." — filters
+    // the reader never set, in the place a control belongs. A folder's count is
+    // DESCENDANTS, so a list bounded to the exact shelf disagrees with it for
+    // every folder that holds its documents in subfolders. On live tandem that
+    // is the two biggest: /ERA22 Shared (142) and /Demo Day Presentations (37).
+    const user = userEvent.setup();
+    const { api } = tenant();
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    await user.click(await screen.findByRole('button', { name: folderRow('Decks') }));
+
+    // `/Decks` itself holds no files at all — everything is one level down.
+    expect(await screen.findByText('Poppins-BoldItalic.ttf')).toBeInTheDocument();
+    // TWO rows called "Lilo Deck V4.key", one per pitch folder — which is bd
+    // startsim-maios's own example of why the flat list was unreadable, and now
+    // the tree beside them says which is which.
+    expect(await screen.findAllByText('Lilo Deck V4.key')).toHaveLength(2);
+    expect(screen.queryByText(/Nothing matches those filters/)).toBeNull();
+  });
+
+  it('the count beside a folder is the count above its list', async () => {
+    const user = userEvent.setup();
+    const { api } = tenant();
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    const decks = await screen.findByRole('button', { name: folderRow('Decks') });
+    // The accessible name carries the tree's own number, so the two claims can
+    // be compared without reaching into the DOM for a count badge.
+    const sidebar = Number(/(\d+) document/.exec(decks.getAttribute('aria-label') ?? '')![1]);
+    await user.click(decks);
+
+    expect(await screen.findByText(new RegExp(`^${sidebar} records`))).toBeInTheDocument();
+  });
+
+  it('offers the remedy as a control when the shelf really is empty', async () => {
+    // Narrowing to `/Decks` itself is a true zero, and the reader asked for it —
+    // but the generic empty state says "Nothing matches those filters. Clear
+    // them to see everything.", which is advice about filters they never set.
+    // A control that does the one useful thing stands there instead.
+    const user = userEvent.setup();
+    const { api } = tenant();
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    await user.click(await screen.findByRole('button', { name: folderRow('Decks') }));
+    await screen.findByText('Poppins-BoldItalic.ttf');
+    await user.click(screen.getByLabelText('Include subfolders'));
+
+    const remedy = await screen.findByRole('button', { name: 'Include subfolders' });
+    expect(screen.queryByText(/Nothing matches those filters/)).toBeNull();
+
+    await user.click(remedy);
+    expect(await screen.findByText('Poppins-BoldItalic.ttf')).toBeInTheDocument();
+  });
+
+  it('does not carry "only this shelf" into the NEXT folder', async () => {
+    // Sticky, this is the container-folder disagreement again in two clicks:
+    // uncheck on `/Decks`, click `/Contracts` — which DOES have files of its own
+    // — and the list shows 2 of the 7 the sidebar claims.
+    const user = userEvent.setup();
+    const { api, seen } = tenant();
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    await user.click(await screen.findByRole('button', { name: folderRow('Decks') }));
+    await screen.findByText('Poppins-BoldItalic.ttf');
+    await user.click(screen.getByLabelText('Include subfolders'));
+    await screen.findByRole('button', { name: 'Include subfolders' });
+
+    await user.click(screen.getByRole('button', { name: folderRow('Contracts') }));
+
+    await waitFor(() => {
+      const list = seen.filter((r) => !r.path.includes('facets')).pop()!;
+      expect(list.params['attr.path__under']).toBe('/Contracts');
+    });
+    expect((screen.getByLabelText('Include subfolders') as HTMLInputElement).checked).toBe(true);
+  });
+
+  it('offers a control to narrow to the shelf, and it really narrows', async () => {
+    // The other reading stays available — as a CONTROL, not as a hidden mode
+    // that depended on whether the search box happened to have a term in it.
+    const user = userEvent.setup();
+    const { api, seen } = tenant();
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    await user.click(await screen.findByRole('button', { name: folderRow('Decks') }));
+    await screen.findByText('Poppins-BoldItalic.ttf');
+
+    await user.click(screen.getByLabelText('Include subfolders'));
+
+    await waitFor(() => {
+      const list = seen.filter((r) => !r.path.includes('facets')).pop()!;
+      expect(list.params['attr.path']).toBe('/Decks');
+      expect(list.params['attr.path__under']).toBeUndefined();
+    });
+  });
+
+  it('tells the reader where they are, and lets them climb back out', async () => {
+    const user = userEvent.setup();
+    const { api } = tenant();
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    await screen.findByRole('button', { name: folderRow('Decks') });
+    await user.click(screen.getByRole('button', { name: 'Expand Decks' }));
+    await user.click(await screen.findByRole('button', { name: folderRow('2022 pitch') }));
+
+    const trail = await screen.findByLabelText('Folder path');
+    expect(within(trail).getByText('Decks')).toBeInTheDocument();
+    expect(within(trail).getByText('2022 pitch')).toBeInTheDocument();
+
+    await user.click(within(trail).getByRole('button', { name: 'All documents' }));
+    await waitFor(() => expect(screen.queryByLabelText('Folder path')).toBeNull());
+  });
+
+  it('keeps records that are in NO folder reachable from the top', async () => {
+    // The facet read enumerates values of `path` and skips records without one,
+    // so a meeting note is in no folder — which on today's tandem is most of the
+    // corpus. The top of the tree therefore clears the filter rather than
+    // narrowing to an invented "unfiled" bucket.
+    const { api, seen } = tenant();
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    expect(await screen.findByText('Acme <> StartSimpli weekly sync')).toBeInTheDocument();
+    const list = seen.filter((r) => !r.path.includes('facets'))[0];
+    expect(list.params['attr.path']).toBeUndefined();
+    expect(list.params['attr.path__under']).toBeUndefined();
+  });
+
+  it('searches the whole subtree of the open folder, not just its shelf', async () => {
+    const user = userEvent.setup();
+    const { api, seen } = tenant({ searchBackend: 'postgres_fulltext' });
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    await screen.findByRole('button', { name: folderRow('Contracts') });
+    await user.click(screen.getByRole('button', { name: folderRow('Contracts') }));
+    await user.type(screen.getByLabelText('Search'), 'migration');
+    await user.click(screen.getByRole('button', { name: 'Search' }));
+
+    await waitFor(() => {
+      const list = seen.filter((r) => !r.path.includes('facets')).pop()!;
+      expect(list.params['attr.path__under']).toBe('/Contracts');
+      expect(list.params.search).toBe('migration');
+    });
+    // Two folders down, and found.
+    expect(await screen.findByText('Statement of work — phase 2.pdf')).toBeInTheDocument();
+  });
+
+  it('says so on screen when the server did not narrow by the folder', async () => {
+    // A tree the server cannot act on is worse than no tree: the reader clicks a
+    // folder, the list does not change, and nothing says why.
+    const user = userEvent.setup();
+    const deaf: CorpusApi = {
+      listDocuments: async () => ({
+        count: 0, next: null, previous: null, results: [], appliedFilters: [],
+      }),
+      getDocument: async () => { throw new Error('unused'); },
+      listParties: async () => ({ count: 0, next: null, previous: null, results: [] }),
+      listSources: async () => [],
+      listFolders: async () => ({
+        count: 1, next: null, previous: null,
+        results: [{ path: '/Contracts', name: 'Contracts', count: 4, hasChildren: false }],
+      }),
+    };
+    render(<LibraryPage api={deaf} scope={SCOPE} />);
+
+    await user.click(await screen.findByRole('button', { name: folderRow('Contracts') }));
+
+    expect(await screen.findByText(/does not filter by folder/)).toBeInTheDocument();
+  });
+
+  it('renders the flat list, and no tree, on a corpus that cannot enumerate folders', async () => {
+    const { api } = tenant({ missing: ['facets'] });
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    expect(await screen.findByText('Rate card 2026')).toBeInTheDocument();
+    await waitFor(() => expect(screen.queryByLabelText('Folders')).toBeNull());
+  });
+});
+
+describe('a row whose text cannot be pulled offers a DISABLED control, not a sentence', () => {
+  it('replaces the explanation with a greyed-out button', async () => {
+    const { api } = tenant();
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    // THE SENTENCE IS GONE. "No text was captured for this record." stood where
+    // a control belongs; it answered "what happened" to a reader asking "what
+    // can I do".
+    expect(await screen.findByText('Poppins-BoldItalic.ttf')).toBeInTheDocument();
+    expect(screen.queryByText(/No text was captured/)).toBeNull();
+
+    const buttons = await screen.findAllByRole('button', { name: 'Get text' });
+    expect(buttons.length).toBeGreaterThan(0);
+    // Greyed out, because the action genuinely cannot be performed: content is
+    // opt-in and this deployment pulls none (bd startsim-h6xnu).
+    expect(buttons.every((button) => (button as HTMLButtonElement).disabled)).toBe(true);
+  });
+
+  it('is live, and calls through, when the deployment CAN fetch the text', async () => {
+    // The seam is not decorative: bd startsim-99g8.2 lands into it and the same
+    // control wakes up with no change here.
+    const user = userEvent.setup();
+    const asked: string[] = [];
+    const { api } = tenant();
+    render(
+      <LibraryPage
+        api={api}
+        scope={SCOPE}
+        pageSize={50}
+        onRequestText={(document) => { asked.push(document.title); }}
+      />,
+    );
+
+    const button = (await screen.findAllByRole('button', { name: 'Get text' }))[0];
+    expect((button as HTMLButtonElement).disabled).toBe(false);
+    await user.click(button);
+
+    expect(asked).toHaveLength(1);
+  });
+
+  it('offers no such control on a row that HAS text', async () => {
+    const { api } = tenant();
+    render(<LibraryPage api={api} scope={SCOPE} pageSize={50} />);
+
+    const row = (await screen.findByText('Rate card 2026')).closest('div.rounded-lg')!;
+    expect(within(row as HTMLElement).queryByRole('button', { name: 'Get text' })).toBeNull();
+  });
+});