test(documents): E2E smoke + visual snapshots for hub rebuild

Two smoke specs cover the headline flows:
  - 04-documents-hub-aggregated: asserts system roots (Clients/Companies/
    Yachts) appear in FolderTreeSidebar with lock icons, breadcrumb updates
    on selection, and EntityFolderView renders Signing + Files sections.
  - 04-documents-hub-upload-into-entity: API-fixture approach (Option B) —
    creates a client, uploads via /api/v1/files/upload with clientId, then
    asserts the file surfaces in the entity folder view.

Visual baselines: hub-root added to the PAGES table so it snapshots via the
standard loop; hub-entity-folder added as a best-effort standalone test with
explicit skip guards when no entity sub-folders exist. Baselines require a
running dev server to generate (pnpm exec playwright test --project=visual
--update-snapshots).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tests/e2e/smoke/04-documents-hub-aggregated.spec.ts

@@ -0,0 +1,146 @@
+import { test, expect } from '@playwright/test';
+import { login, navigateTo } from './helpers';
+
+/**
+ * Smoke spec — Documents Hub aggregated view (Wave 11.B rebuild)
+ *
+ * Exercises the structural layout of the new DocumentsHub:
+ *   - FolderTreeSidebar with system-root folders (Clients / Companies / Yachts)
+ *   - HubRootView sections ("Signing in progress" + "Recent files")
+ *   - Expanding a system root to reveal entity sub-folders
+ *   - Selecting an entity sub-folder switches to EntityFolderView which
+ *     renders the AggregatedSection blocks
+ *
+ * Note: This spec intentionally avoids asserting on seeded file/workflow
+ * counts — those vary by seed state.  The integration tests (Tasks 8 + 9)
+ * already verify service correctness; this spec guards UI-level rendering.
+ */
+
+test.describe('Documents hub — aggregated view', () => {
+  test.beforeEach(async ({ page }) => {
+    await login(page, 'super_admin');
+  });
+
+  test('hub root shows Signing-in-progress and Recent-files sections', async ({ page }) => {
+    await navigateTo(page, '/documents');
+    await page.waitForLoadState('networkidle');
+
+    // HubRootView renders two labelled sections.
+    await expect(page.getByText('Signing in progress')).toBeVisible({ timeout: 10_000 });
+    await expect(page.getByText('Recent files')).toBeVisible({ timeout: 5_000 });
+  });
+
+  test('sidebar shows All-documents and Root pseudo-rows', async ({ page }) => {
+    await navigateTo(page, '/documents');
+    await page.waitForLoadState('networkidle');
+
+    // FolderTreeSidebar always renders these two pseudo-rows at the top.
+    await expect(page.getByRole('button', { name: 'All documents' })).toBeVisible({
+      timeout: 10_000,
+    });
+    await expect(page.getByRole('button', { name: 'Root (no folder)' })).toBeVisible({
+      timeout: 5_000,
+    });
+  });
+
+  test('system-root folders appear in the sidebar with lock icons', async ({ page }) => {
+    await navigateTo(page, '/documents');
+    await page.waitForLoadState('networkidle');
+
+    // ensureSystemRoots creates Clients / Companies / Yachts on port creation.
+    // Each node has systemManaged=true → FolderRow renders a Lock icon beside
+    // the name. We assert text presence; the SVG lock icon is decoration only
+    // and aria-labeled "System folder" by the component.
+    for (const rootName of ['Clients', 'Companies', 'Yachts']) {
+      await expect(page.getByText(rootName)).toBeVisible({ timeout: 10_000 });
+    }
+    // At least one system-folder lock icon should be in the sidebar.
+    const lockIcons = page.locator('aside [aria-label="System folder"]');
+    await expect(lockIcons.first()).toBeVisible({ timeout: 5_000 });
+  });
+
+  test('clicking a system root selects it and breadcrumb updates', async ({ page }) => {
+    await navigateTo(page, '/documents');
+    await page.waitForLoadState('networkidle');
+
+    // Click the Clients system root folder button (the label button inside FolderRow).
+    // The chevron button and the label button are siblings — we target the button
+    // that contains the text "Clients".
+    const clientsBtn = page
+      .locator('aside button')
+      .filter({ hasText: /^Clients$/ })
+      .first();
+    await expect(clientsBtn).toBeVisible({ timeout: 10_000 });
+    await clientsBtn.click();
+
+    // The breadcrumb (nav[aria-label="breadcrumb"]) should now show "Clients".
+    await expect(page.getByRole('navigation', { name: /breadcrumb/i })).toContainText('Clients', {
+      timeout: 10_000,
+    });
+  });
+
+  test('entity sub-folder view renders Signing-in-progress and Files sections', async ({
+    page,
+    request,
+  }) => {
+    // Create a fresh client via the API so we have a guaranteed entity with a
+    // folder. ensureEntityFolder is called by the createClient service hook.
+    const res = await request.post('/api/v1/clients', {
+      data: {
+        firstName: 'HubAgg',
+        lastName: `Smoke${Date.now()}`,
+        email: `hubagg${Date.now()}@e2e.test`,
+      },
+    });
+    // If creation fails (e.g. no active port cookie yet), skip gracefully —
+    // we still assert basic hub structure in the earlier tests.
+    if (!res.ok()) {
+      test.skip(
+        true,
+        `Client create returned ${res.status()} — entity sub-folder assertion skipped`,
+      );
+      return;
+    }
+    const { data: client } = (await res.json()) as { data: { id: string; firstName: string; lastName: string } };
+
+    // Navigate to the documents hub.
+    await navigateTo(page, '/documents');
+    await page.waitForLoadState('networkidle');
+
+    // Expand the Clients system root by clicking its chevron (Expand button).
+    // The Expand chevron is the first button sibling inside the FolderRow div.
+    // It is aria-labeled "Expand" when collapsed.
+    const expandBtn = page
+      .locator('aside')
+      .getByRole('button', { name: 'Expand' })
+      .first();
+    await expect(expandBtn).toBeVisible({ timeout: 10_000 });
+    await expandBtn.click();
+
+    // The entity folder is named "<FirstName> <LastName>".
+    const entityFolderBtn = page
+      .locator('aside button')
+      .filter({ hasText: `${client.firstName} ${client.lastName}` })
+      .first();
+
+    if (!(await entityFolderBtn.isVisible({ timeout: 8_000 }).catch(() => false))) {
+      // ensureEntityFolder may not have run yet (async post-create); reload to
+      // pick up the folder tree refresh.
+      await navigateTo(page, '/documents');
+      await page.waitForLoadState('networkidle');
+      // Re-expand.
+      const expandBtn2 = page
+        .locator('aside')
+        .getByRole('button', { name: 'Expand' })
+        .first();
+      await expandBtn2.click();
+    }
+
+    await expect(entityFolderBtn).toBeVisible({ timeout: 10_000 });
+    await entityFolderBtn.click();
+
+    // EntityFolderView renders two AggregatedSection blocks with these headings.
+    await expect(page.getByText('Signing in progress')).toBeVisible({ timeout: 10_000 });
+    await expect(page.getByText('Files')).toBeVisible({ timeout: 5_000 });
+  });
+});