task-0094-comments-notifications.spec.ts

task-0094-comments-notifications.spec.tstests/e2e/specs/task-0094-comments-notifications.spec.tsraw ← specs37,792 B← Back to the app
1/**
2 * TASK-0094 — realtime comments + notifications E2E (Phase 7).
3 *
4 * ── RUNNER GATE (Docker) — NOT RUNNABLE LOCALLY ──────────────────────────
5 * This spec needs the full stack (Postgres + Redis + API :4000 + realtime
6 * :4001 + web :3000). A Docker daemon is unavailable in the authoring
7 * environment (permission denied; recorded, never faked). It is CI-ready
8 * under the same contract as every other spec in this package (`pnpm
9 * docker:up && pnpm dev`, then the suite). Committed so the TASK-0094
10 * acceptance mechanic is pinned for CI; it is not a local-green test here.
11 *
12 * ── WHAT RUNS, WHAT IS SKIPPED (honest split against pre-existing defects) ──
13 * While authoring this spec we audited the auth path end-to-end and found
14 * THREE pre-existing defects, each out of TASK-0094 scope, that gate the
15 * runnable surface. We split the file so the part that can run does run, and
16 * the rest is committed (selector + budget intact) but skipped with the
17 * exact blocker named — never faked, never a silent pass.
18 *
19 *   (D1) THE API GUARD IS BEARER-ONLY. apps/api/src/common/guards/
20 *        auth.guard.ts:35 reads `Authorization: Bearer …` and NOTHING else —
21 *        it never reads cookies. The API sets the HttpOnly refresh cookie
22 *        under `factory_refresh` (constants.ts:84). So the committed `api` /
23 *        `secondUser` fixtures — which authenticate with the login cookie
24 *        only — 401 on every non-public route. This is why Part A builds its
25 *        own Bearer context from the login response's `accessToken` instead
26 *        of reusing the `api` fixture.
27 *
28 *   (D2) THE WEB APP CANNOT AUTHENTICATE A BROWSER. The access token is
29 *        memory-only (lib/api.ts never reads `factory.accessToken` from
30 *        localStorage on startup); the only hydration path is `GET /auth/me`
31 *        enabled on `hasSession()` (hooks/use-auth.ts:24); and `hasSession()`
32 *        (lib/auth-store.ts:40) checks `document.cookie` for `factory_session`
33 *        — a cookie the API never sets (it sets `factory_refresh`, and an
34 *        HttpOnly cookie is invisible to `document.cookie` regardless). So
35 *        `hasSession()` is always false → `/auth/me` never fires → `initializing`
36 *        never clears → the (app) layout shows the spinner forever. On top of
37 *        that, `/auth/me` is Bearer-gated (D1) but the web calls it `noAuth`
38 *        (lib/api.ts), and `authApi.login/register` type the response as
39 *        `{ user, token, workspaceId }` while the API returns
40 *        `{ accessToken, refreshToken, session }` (auth.service.ts:81) — so
41 *        even the login page reads `undefined` and stays on /login. Net: no
42 *        browser context can reach an authenticated page. This gates PART B.
43 *
44 *   (D3) THE TWO-USER MEMBERSHIP FLOW IS EMAIL-GATED. `workspaces.invite`
45 *        hashes the invite token and EMAILS it (workspaces.service.ts:176-202)
46 *        — the HTTP response is `{ id, email, role, expiresAt }`, NO token.
47 *        There is no `?token=`-free or user-id add-member route (the only
48 *        accept route is `POST /workspaces/:id/members/invites/:inviteId/accept?token=…`).
49 *        So an automated test cannot get a second user into a workspace
50 *        without a mail server. This gates the team-per-member dedup case
51 *        (a team member must be a workspace member first). Note the committed
52 *        integration comments test (comments.integration.test.ts) has the same
53 *        latent gap: it parses `invite.invitation.token`, which the API never
54 *        returns.
55 *
56 * Part A (API-only, RUNS in CI) is self-contained around those gaps:
57 *   A0 — the guard is Bearer-only (a header-less request 401s). Pins the
58 *        contract Part A relies on and documents why the cookie-based `api`
59 *        fixture cannot work (D1).
60 *   A1 — an @user mention → EXACTLY ONE unread MENTION row for the recipient.
61 *        This is the acceptance #2 mechanic ("mentions create notifications")
62 *        in E2E form against the live API. It is SELF-CONTAINED:
63 *        `Notification.userId` is a plain `User` FK (no membership required —
64 *        prisma Notification.user → User), and `materializeMentions` notifies
65 *        any user id in the comment body (comments.service.ts:215 has no
66 *        membership gate for @user targets). So the owner (who creates the
67 *        workspace + page) can mention a freshly-registered outsider and the
68 *        row lands — no invite needed, no D3 dependency.
69 *
70 * Part B + A2 were committed-but-skipped on D2 (web-auth) + D3 (two-user
71 * membership); both are now FIXED (TASK-0095 S10 reworked the web auth to the
72 * cookie + silent-refresh contract so a browser authenticates; S9 added the
73 * internal add-member seam so a second/third user joins a workspace). This
74 * slice (S11) re-enables them — the `test.skip(true, …)` guards are removed
75 * and the bodies implemented below (A2 = A1 + a team fan-out + the dedup
76 * assert; B1–B4 = the browser UI mechanic on fresh-login tabs).
77 *
78 * ── API CONTRACT (verified against apps/api) ─────────────────────────────
79 *   Auth:    Authorization: Bearer <accessToken>   (D1 — the only path).
80 *   login:   POST /api/v1/auth/login {email,password}
81 *             → 200 { accessToken, refreshToken, expiresIn, session }
82 *             + Set-Cookie factory_refresh=<rft_…>; Path=/; HttpOnly; SameSite=Lax
83 *   user:    GET  /api/v1/auth/me → { user: { id, email, name }, workspaces }
84 *   page:    POST /api/v1/workspaces { name }
85 *              → 201 { …workspace, role: "OWNER" }   (BARE — not wrapped)
86 *           POST /api/v1/workspaces/:wid/pages { title?, parentId? }
87 *              → 201 { …page, teamId }               (BARE — not wrapped)
88 *   comment: POST /api/v1/comments { targetType, targetId, parentId?, body }
89 *             (the canonical mention tokens live in `body`; there is NO
90 *              `mentionIds` field — the server runs parseMentions(body))
91 *   notify:  GET  /api/v1/notifications[?read=false] → { data, nextCursor }
92 *            GET  /api/v1/notifications/unread-count → { count }
93 *            POST /api/v1/notifications/read-all     → { marked }
94 *            POST /api/v1/notifications/:id/read     → { read, id }
95 *   team:    POST /api/v1/workspaces/:wid/teams { name } → { …team } (bare)
96 *            POST /api/v1/workspaces/:wid/teams/:tid/members { userId }
97 *   Mention tokens (shared `parseMentions` contract): `@user:<id>`,
98 *   `@team:<id>`, `@page:<id>`, `@database:<id>`; ids are ≥ 8 chars (the
99 *   cuid ids satisfy the length rule). A plain `@Name` is NOT a mention.
100 *
101 * ── WHY PART A USES ITS OWN CONTEXT (not the `api` fixture / utils/api.ts) ──
102 * Two reasons, both recorded as D1 + a helper-staleness defect (D4):
103 *   (D4) tests/e2e/utils/api.ts is STALE against the API: `createWorkspace`
104 *        parses `body.workspace.id` but the API returns the bare workspace
105 *        (no wrapper); `inviteMember` POSTs `/workspaces/:wid/invitations`
106 *        (the route is `/workspaces/:id/members/invites`) and reads
107 *        `body.invitation.token` (the API returns a bare `{id,email,role,
108 *        expiresAt}` with no token — D3). Part A therefore calls the raw
109 *        routes itself and does not import those helpers. It also does NOT
110 *        call `loadAuthState()` at module scope, so the runnable tests do not
111 *        depend on global-setup having written `.auth/user.json` (global-setup
112 *        is still required by the Playwright config and must not crash — see
113 *        the companion global-setup fix for its `req.cookies()` crash on the
114 *        pinned @playwright/test, which would otherwise abort the whole suite).
115 *
116 * ── BUDGETS (honest) ─────────────────────────────────────────────────────
117 * UI budgets are a 2× flake-superset over the DoD metric and log the actual
118 * delta on failure: comment fan-out 1000 ms (DoD 300 ms), bell push 2000 ms
119 * (DoD 1 s). The API tests assert on a settle window: the MENTION row is
120 * written synchronously by CommentsService.create → materializeMentions →
121 * NotificationsService.notify (a `$transaction`) BEFORE the HTTP 2xx, so the
122 * poll should settle on its first tick; the window is a safety margin for
123 * CI load.
124 */
125import { test, expect, request as pwRequest } from "@playwright/test";
126import type { APIRequestContext, Browser, Page } from "@playwright/test";
127import {
128  addMemberViaSeam,
129  createPage,
130  createWorkspace,
131  seamServiceToken,
132} from "../utils/api";
133 
134const API_BASE = process.env.E2E_API_URL ?? "http://localhost:4000";
135const WEB_BASE = process.env.E2E_BASE_URL ?? "http://localhost:3000";
136 
137const COMMENT_VISIBLE_BUDGET_MS = 1000; // 2× the 300 ms DoD (flake-superset)
138const BELL_PUSH_BUDGET_MS = 2000; // 2× the 1 s DoD (flake-superset)
139const API_SETTLE_MS = 5000; // settle window for the sync MENTION write (A1/A2)
140 
141/** The canonical mention token (the shared parseMentions contract). */
142const mentionToken = (kind: string, id: string) => `@${kind}:${id}`;
143 
144/** A unique email for a freshly-registered E2E user (unique per run). */
145const uniqueEmail = (tag: string) =>
146  `e2e-0094-${tag}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@factory.local`;
147 
148// ---------------------------------------------------------------------------
149// Part A — authenticated Bearer context (self-contained; NOT the `api` fixture)
150// ---------------------------------------------------------------------------
151 
152interface ApiUser {
153  email: string;
154  password: string;
155  /** The login access token (the Bearer credential — D1). */
156  token: string;
157  /** The user's id (from /auth/me). */
158  id: string;
159  name: string;
160  /** An authenticated APIRequestContext (Bearer). */
161  api: APIRequestContext;
162  close: () => Promise<void>;
163}
164 
165/**
166 * Build an APIRequestContext that authenticates as the given user via the
167 * `Authorization: Bearer` header — the ONLY credential the guard accepts
168 * (auth.guard.ts:35). Relative paths resolve against `API_BASE`.
169 */
170async function bearerCtx(token: string): Promise<APIRequestContext> {
171  return pwRequest.newContext({
172    baseURL: API_BASE,
173    timeout: 30_000,
174    extraHTTPHeaders: { Authorization: `Bearer ${token}` },
175  });
176}
177 
178async function registerAndLogin(
179  name: string,
180): Promise<{ token: string; id: string; email: string; password: string }> {
181  const email = uniqueEmail(name.toLowerCase());
182  const password = `e2e-${Date.now().toString(36)}`;
183  // No-auth context (register/login are on the public whitelist — D1).
184  const plain = await pwRequest.newContext({ baseURL: API_BASE, timeout: 30_000 });
185  try {
186    const reg = await plain.post("/api/v1/auth/register", { data: { email, password, name } });
187    expect(reg.status(), `register ${email}: ${await reg.text()}`).toBe(201);
188    const lg = await plain.post("/api/v1/auth/login", { data: { email, password } });
189    expect(lg.status(), `login ${email}: ${await lg.text()}`).toBe(200);
190    const body = (await lg.json()) as { accessToken?: string };
191    expect(body.accessToken, `login body for ${email} carries accessToken`).toBeTruthy();
192    const token = body.accessToken!;
193 
194    // Resolve the user id via /auth/me on a Bearer context (D1).
195    const me = await bearerCtx(token);
196    const meRes = await me.get("/api/v1/auth/me");
197    await me.dispose();
198    expect(meRes.status(), `GET /me ${email}: ${await meRes.text()}`).toBe(200);
199    const meBody = (await meRes.json()) as { user: { id: string } };
200    return { token, id: meBody.user.id, email, password };
201  } finally {
202    await plain.dispose().catch(() => {});
203  }
204}
205 
206async function newApiUser(name: string): Promise<ApiUser> {
207  const { token, id, email, password } = await registerAndLogin(name);
208  const api = await bearerCtx(token);
209  return {
210    email,
211    password,
212    token,
213    id,
214    name,
215    api,
216    close: () => api.dispose().catch(() => {}),
217  };
218}
219 
220/**
221 * Seed (raw API, NOT utils/api.ts — D4): a freshly-registered OWNER with a
222 * workspace + a page, plus a freshly-registered ALICE (an OUTSIDER — not a
223 * member). A1 does not need Alice to be a member: Notification.userId is a
224 * plain User FK (no membership), and materializeMentions notifies any user id
225 * in the comment body. A2 would need Alice to be a member + on a team → D3.
226 */
227async function apiSeed() {
228  const owner = await newApiUser("Owner");
229  const alice = await newApiUser("Alice");
230  try {
231    const wsRes = await owner.api.post("/api/v1/workspaces", {
232      data: { name: `Comments ${Date.now()}` },
233    });
234    expect(wsRes.status(), `create workspace: ${await wsRes.text()}`).toBeLessThan(300);
235    const ws = (await wsRes.json()) as { id: string };
236 
237    const pgRes = await owner.api.post(`/api/v1/workspaces/${ws.id}/pages`, {
238      data: { title: "Comments page" },
239    });
240    expect(pgRes.status(), `create page: ${await pgRes.text()}`).toBeLessThan(300);
241    const pg = (await pgRes.json()) as { id: string };
242 
243    return {
244      owner,
245      alice,
246      wsId: ws.id,
247      pageId: pg.id,
248      closeAll: async () => {
249        await owner.close().catch(() => {});
250        await alice.close().catch(() => {});
251      },
252    };
253  } catch (err) {
254    await owner.close().catch(() => {});
255    await alice.close().catch(() => {});
256    throw err;
257  }
258}
259 
260/** The API's authoritative unread count for a user's Bearer context. */
261async function apiUnreadCount(api: APIRequestContext): Promise<number> {
262  const r = await api.get("/api/v1/notifications/unread-count");
263  expect(r.status(), `unread-count: ${await r.text()}`).toBe(200);
264  return ((await r.json()) as { count: number }).count;
265}
266 
267/** The caller's notification rows (the API is always self-scoped). */
268async function apiNotificationRows(
269  api: APIRequestContext,
270): Promise<{ type: string; readAt: string | null }[]> {
271  const r = await api.get("/api/v1/notifications");
272  expect(r.status(), `notifications list: ${await r.text()}`).toBe(200);
273  return ((await r.json()) as { data: { type: string; readAt: string | null }[] }).data;
274}
275 
276// ---------------------------------------------------------------------------
277// Part B — shared browser bootstrap (fresh-login tabs; re-enabled in S11)
278// ---------------------------------------------------------------------------
279 
280/**
281 * A freshly-registered user with its OWN demo-equivalent browser tab (the
282 * presence-cursors.spec.ts `newUser` idiom, S10-updated): a fresh login → the
283 * httpOnly refresh cookie jar → a storageState context. The web client
284 * silent-refreshes into a memory access token on load (S10 — the localStorage
285 * mirror the pre-S10 version carried is gone; the cookie is the source of
286 * truth). Each tab has its OWN session, so parallel tabs never share a refresh
287 * cookie (reuse-detection safety — the S10 concurrency rule).
288 */
289async function browserTab(
290  browser: Browser,
291  name: string,
292): Promise<{
293  email: string;
294  password: string;
295  /** The user id (from /auth/me — needed to target @user:<id> mentions). */
296  id: string;
297  /** The UI tab (authenticates via the refresh cookie + silent refresh). */
298  page: Page;
299  /** A BEARER API context (the guard is Bearer-only — D1). `page`'s
300   *  `context.request` is cookie-only and 401s on protected routes. */
301  api: APIRequestContext;
302  close: () => Promise<void>;
303}> {
304  const email = uniqueEmail(name.toLowerCase());
305  const password = `e2e-${Date.now().toString(36)}`;
306  const plain = await browser.newContext();
307  let token = "";
308  try {
309    const reg = await plain.request.post("/api/v1/auth/register", {
310      data: { email, password, name },
311    });
312    expect(reg.status(), `register ${email}: ${await reg.text()}`).toBe(201);
313    const lg = await plain.request.post("/api/v1/auth/login", {
314      data: { email, password },
315    });
316    expect(lg.status(), `login ${email}: ${await lg.text()}`).toBe(200);
317    token = ((await lg.json()) as { accessToken?: string }).accessToken ?? "";
318    expect(token, `login ${email} carried accessToken`).toBeTruthy();
319    const jar = await plain.cookies();
320    const state = {
321      cookies: jar.map((c) => ({
322        name: c.name,
323        value: c.value,
324        domain: c.domain,
325        path: c.path,
326        expires: c.expires,
327        httpOnly: c.httpOnly,
328        secure: c.secure,
329        sameSite: c.sameSite,
330      })),
331      origins: [],
332    };
333    await plain.close();
334    const context = await browser.newContext({ storageState: state });
335    const page = await context.newPage();
336    // A SEPARATE Bearer context for direct API calls (the UI tab authenticates
337    // via the cookie; the API guard reads only the Authorization header — D1).
338    const api = await pwRequest.newContext({
339      baseURL: API_BASE,
340      timeout: 30_000,
341      extraHTTPHeaders: { Authorization: `Bearer ${token}` },
342    });
343    const meRes = await api.get("/api/v1/auth/me");
344    expect(meRes.status(), `GET /me ${email}: ${await meRes.text()}`).toBe(200);
345    const id = ((await meRes.json()) as { user: { id: string } }).user.id;
346    return {
347      email,
348      password,
349      id,
350      page,
351      api,
352      close: async () => {
353        await context.close();
354        await api.dispose().catch(() => {});
355      },
356    };
357  } catch (err) {
358    await plain.close().catch(() => {});
359    throw err;
360  }
361}
362 
363/**
364 * Part B seed (raw API, the owner's Bearer context): a workspace + a page,
365 * plus ALICE + BOB as workspace members (the S9 seam — the public invite flow
366 * is email-gated and its token never reaches the client, D3). Alice and Bob
367 * are members so the comment composer enables for them (the panel is
368 * member-gated) and the People mention group lists them.
369 */
370async function partBSeed(browser: Browser) {
371  // The owner is a browser tab too (so the owner's UI is drivable in B1–B4);
372  // a freshly-registered user that creates the workspace is its OWNER, which
373  // is every authority the tests need (comment, create team, add members).
374  const owner = await browserTab(browser, "Owner");
375  const alice = await browserTab(browser, "Alice");
376  const bob = await browserTab(browser, "Bob");
377  try {
378    const ws = await createWorkspace(owner.api, `Comments UI ${Date.now()}`);
379    const pg = await createPage(owner.api, ws.id, { title: "Comments UI page" });
380    // Membership (the D3 unblock — the internal test seam, e2e-only).
381    await addMemberViaSeam(seamServiceToken(), ws.id, alice.email);
382    await addMemberViaSeam(seamServiceToken(), ws.id, bob.email);
383    const pageUrl = `/w/${ws.id}/page/${pg.id}`;
384    const inboxUrl = `/w/${ws.id}/notifications`;
385    return {
386      owner,
387      alice,
388      bob,
389      wsId: ws.id,
390      pageId: pg.id,
391      pageUrl,
392      inboxUrl,
393      closeAll: async () => {
394        await owner.close().catch(() => {});
395        await alice.close().catch(() => {});
396        await bob.close().catch(() => {});
397      },
398    };
399  } catch (err) {
400    await owner.close().catch(() => {});
401    await alice.close().catch(() => {});
402    await bob.close().catch(() => {});
403    throw err;
404  }
405}
406 
407// ---------------------------------------------------------------------------
408// PART A — API-only (CI-runnable)
409// ---------------------------------------------------------------------------
410 
411test.describe("TASK-0094 — comments + notifications (API-only)", () => {
412  test("A0 — the guard is Bearer-only: a header-less request 401s (D1)", async () => {
413    // Pins the contract Part A relies on: the API reads ONLY
414    // `Authorization: Bearer`. A request with no such header (even one that
415    // could carry a cookie) is 401. This is why the committed cookie-only
416    // `api`/`secondUser` fixtures cannot work (D1) and why Part A uses its
417    // own Bearer context.
418    const plain = await pwRequest.newContext({ baseURL: API_BASE, timeout: 15_000 });
419    try {
420      const res = await plain.get("/api/v1/notifications/unread-count");
421      expect(res.status(), `expected 401 (no bearer), got ${await res.text()}`).toBe(401);
422    } finally {
423      await plain.dispose().catch(() => {});
424    }
425  });
426 
427  test("A1 — an @user mention creates EXACTLY ONE unread MENTION row for the recipient", async () => {
428    const s = await apiSeed();
429    try {
430      // The owner comments on the page, mentioning Alice by her user id.
431      // Alice is an OUTSIDER (not a member) — that is deliberate: the
432      // mention mechanic notifies any user id (D3-independent; see header).
433      const res = await s.owner.api.post("/api/v1/comments", {
434        data: {
435          targetType: "page",
436          targetId: s.pageId,
437          body: `${mentionToken("user", s.alice.id)} — ship it`,
438        },
439      });
440      expect(res.status(), `comment create: ${await res.text()}`).toBeLessThan(300);
441 
442      // The MENTION row is written synchronously (CommentsService.create →
443      // materializeMentions → NotificationsService.notify $transaction)
444      // BEFORE the 2xx, so this settles on the first tick. Alice is fresh →
445      // exactly one unread MENTION row (a self-mention would be excluded, but
446      // she is not the mentioner).
447      await expect
448        .poll(
449          async () =>
450            (await apiNotificationRows(s.alice.api)).filter(
451              (n) => n.type === "MENTION" && n.readAt === null,
452            ).length,
453          { timeout: API_SETTLE_MS, message: "Alice has exactly one unread MENTION row" },
454        )
455        .toBe(1);
456 
457      // The unread count agrees (one unread — she has nothing else).
458      await expect
459        .poll(() => apiUnreadCount(s.alice.api), {
460          timeout: API_SETTLE_MS,
461          message: "Alice's unread count is 1",
462        })
463        .toBe(1);
464    } finally {
465      await s.closeAll();
466    }
467  });
468 
469  test("A2 — a user mentioned directly AND via a team gets EXACTLY ONE row (dedup)", async () => {
470    // Re-enabled in S11 (D3 unblocked by the S9 seam): the mechanic is A1 plus
471    // a team fan-out. materializeMentions collapses a direct + team path into
472    // ONE (user, target) row (comments.service.ts — the `userTargets` Set
473    // unions the direct users + the team members, then dedups on the target
474    // id before inserting).
475    const owner = await newApiUser("Owner");
476    const alice = await newApiUser("Alice");
477    const bob = await newApiUser("Bob");
478    try {
479      const wsRes = await owner.api.post("/api/v1/workspaces", {
480        data: { name: `Comments A2 ${Date.now()}` },
481      });
482      expect(wsRes.status(), `create workspace: ${await wsRes.text()}`).toBeLessThan(300);
483      const ws = (await wsRes.json()) as { id: string };
484 
485      // Alice + Bob are workspace members (the seam) — the team-member add
486      // below requires both to be in the workspace, and it keeps the scenario
487      // production-realistic.
488      await addMemberViaSeam(seamServiceToken(), ws.id, alice.email);
489      await addMemberViaSeam(seamServiceToken(), ws.id, bob.email);
490 
491      // A team with Alice + Bob as members (POST …/teams, then …/members per
492      // member — the team member route is user-id keyed, so it needs no email
493      // gate; D3 only gated WORKSPACE membership, which the seam covers).
494      const teamRes = await owner.api.post(`/api/v1/workspaces/${ws.id}/teams`, {
495        data: { name: "Engineering" },
496      });
497      expect(teamRes.status(), `create team: ${await teamRes.text()}`).toBeLessThan(300);
498      const team = (await teamRes.json()) as { id: string };
499      for (const member of [alice, bob]) {
500        const addRes = await owner.api.post(`/api/v1/workspaces/${ws.id}/teams/${team.id}/members`, {
501          data: { userId: member.id },
502        });
503        expect(addRes.status(), `team add ${member.name}: ${await addRes.text()}`).toBeLessThan(300);
504      }
505 
506      const pgRes = await owner.api.post(`/api/v1/workspaces/${ws.id}/pages`, {
507        data: { title: "Comments A2 page" },
508      });
509      expect(pgRes.status(), `create page: ${await pgRes.text()}`).toBeLessThan(300);
510      const pg = (await pgRes.json()) as { id: string };
511 
512      // The owner comments mentioning Alice BOTH directly AND via the team.
513      // The direct path adds alice.id; the team path adds every team member
514      // (alice + bob) → userTargets = { alice, bob }. Alice is therefore
515      // reachable via TWO paths but must yield EXACTLY ONE unread MENTION row
516      // (the dedup); Bob via the team path → his own one row.
517      const res = await owner.api.post("/api/v1/comments", {
518        data: {
519          targetType: "page",
520          targetId: pg.id,
521          body: `${mentionToken("user", alice.id)} ${mentionToken("team", team.id)} — review`,
522        },
523      });
524      expect(res.status(), `comment create: ${await res.text()}`).toBeLessThan(300);
525 
526      // Alice: exactly ONE unread MENTION row (dedup across the two paths).
527      await expect
528        .poll(
529          async () =>
530            (await apiNotificationRows(alice.api)).filter(
531              (n) => n.type === "MENTION" && n.readAt === null,
532            ).length,
533          { timeout: API_SETTLE_MS, message: "Alice has exactly one unread MENTION row (dedup)" },
534        )
535        .toBe(1);
536 
537      // Bob: exactly ONE unread MENTION row (the team fan-out).
538      await expect
539        .poll(
540          async () =>
541            (await apiNotificationRows(bob.api)).filter(
542              (n) => n.type === "MENTION" && n.readAt === null,
543            ).length,
544          { timeout: API_SETTLE_MS, message: "Bob has exactly one unread MENTION row (team)" },
545        )
546        .toBe(1);
547    } finally {
548      await owner.close().catch(() => {});
549      await alice.close().catch(() => {});
550      await bob.close().catch(() => {});
551    }
552  });
553});
554 
555// ---------------------------------------------------------------------------
556// PART B — BROWSER UI (re-enabled in S11 — D2 fixed by the S10 web-auth rework,
557// D3 fixed by the S9 seam)
558// ---------------------------------------------------------------------------
559//
560// These assert the frontend mechanic: the realtime bell push, the inbox
561// count / mark-read / deep-link, the mention-picker a11y, and the < 300 ms
562// comment fan-out. They are written against the real app (selectors + budgets
563// below). Bootstrap: `browserTab` (a fresh-login tab — cookie + silent refresh,
564// S10) + `partBSeed` (owner + Alice + Bob as members via the S9 seam).
565//
566// Selectors (slice 7a, committed 12d3b5fb): notification-bell (aria-label
567// `N unread notification(s)` / `Notifications`), notification-row-{id} (+
568// "Open" button), mark-all-read, comment-button (pill `Open comments (n new)`),
569// comment-panel (dialog "Comments"), comment-composer, comment-submit,
570// mention-listbox (role=listbox), mention-option-{kind}-{id} (aria-label
571// `"{label} (Member|Team|Page|Database)"`), groups role=group People/Teams/
572// Pages/Databases. Toasts are role="status".
573 
574test.describe("TASK-0094 — comments + notifications (browser UI)", () => {
575  // Open the comment panel on a page once the shell has authenticated +
576  // rendered (the S10 silent-refresh → /me → sidebar chain). Shared by B1/B4.
577  async function openCommentsPanel(page: Page) {
578    await expect(page.getByTestId("sidebar"), "the shell should authenticate + render").toBeVisible({
579      timeout: 20_000,
580    });
581    await page.getByTestId("comment-button").click();
582    await expect(page.getByTestId("comment-panel")).toBeVisible();
583  }
584 
585  test("B1 — B's comment appears in A's open panel within the budget (300 ms)", async ({
586    browser,
587  }) => {
588    // The R2 comment fan-out: owner + Alice on the SAME page with the comment
589    // panel OPEN; Alice composes+sends; the owner's panel (remote-update only)
590    // refetches on the comment.event frame and shows the new thread. The
591    // budget (DoD 300 ms, measured at a 2× flake-superset) is the
592    // REST-write → api publish → realtime stream → frame → refetch → render
593    // path; the join is NOT in the budget (both panels are open first).
594    const s = await partBSeed(browser);
595    try {
596      await s.owner.page.goto(s.pageUrl);
597      await s.alice.page.goto(s.pageUrl);
598      await openCommentsPanel(s.owner.page);
599      await openCommentsPanel(s.alice.page);
600 
601      // Both panels are open + empty (the fresh page has no comments).
602      await expect(s.owner.page.getByTestId("comment-panel")).toContainText("No comments yet");
603 
604      // Alice composes (the member-gated composer is enabled — she is a
605      // workspace member via the seam). The typing is SETUP, not the budget.
606      await s.alice.page.getByTestId("comment-composer").click();
607      await s.alice.page.keyboard.type("hello from alice");
608 
609      // Budget = the submit (REST write) → api publish → stream → frame →
610      // refetch → render. The DoD metric is 300 ms; measured at a 2×
611      // flake-superset, with the actual logged on failure.
612      const t0 = Date.now();
613      await s.alice.page.getByTestId("comment-submit").click();
614      await expect
615        .poll(
616          () => s.owner.page.getByTestId("comment-panel").innerText(),
617          { timeout: COMMENT_VISIBLE_BUDGET_MS, message: "owner's panel shows Alice's comment" },
618        )
619        .toContain("hello from alice");
620      const delta = Date.now() - t0;
621      expect(
622        delta,
623        `comment fan-out delta ${delta} ms (DoD metric is 300 ms; this is a 2× flake-superset)`,
624      ).toBeLessThanOrEqual(COMMENT_VISIBLE_BUDGET_MS);
625    } finally {
626      await s.closeAll();
627    }
628  });
629 
630  test("B2 — an @user mention bumps the recipient's bell < 1 s + fires the toast", async ({
631    browser,
632  }) => {
633    // R4 + R7: the owner comments mentioning Alice; the `notification.push`
634    // frame (over Alice's `user:{id}` control room) bumps her bell + fires a
635    // role=status toast; cross-check the API (exactly one unread MENTION row).
636    // Budget (DoD 1 s, measured at 2×) is the mention write → api publish →
637    // push frame → bell render.
638    const s = await partBSeed(browser);
639    try {
640      await s.owner.page.goto(s.pageUrl);
641      await s.alice.page.goto(s.pageUrl);
642      await openCommentsPanel(s.owner.page);
643      // Alice's bell starts clean (0 unread → the plain "Notifications" label).
644      await expect(s.alice.page.getByTestId("notification-bell")).toHaveAttribute(
645        "aria-label",
646        "Notifications",
647        { timeout: 15_000 },
648      );
649 
650      const t0 = Date.now();
651      // The owner composes a comment mentioning Alice by her user id (the
652      // canonical @user:<id> token the server parses into a MENTION row).
653      await s.owner.page.getByTestId("comment-composer").click();
654      await s.owner.page.keyboard.type(`@user:${s.alice.id} — review this`);
655      await s.owner.page.getByTestId("comment-submit").click();
656 
657      // Alice's bell bumps to "1 unread notification" within the budget.
658      await expect
659        .poll(
660          () => s.alice.page.getByTestId("notification-bell").getAttribute("aria-label"),
661          { timeout: BELL_PUSH_BUDGET_MS, message: "Alice's bell shows 1 unread" },
662        )
663        .toBe("1 unread notification");
664      const delta = Date.now() - t0;
665      expect(
666        delta,
667        `bell push delta ${delta} ms (DoD metric is 1 s; this is a 2× flake-superset)`,
668      ).toBeLessThanOrEqual(BELL_PUSH_BUDGET_MS);
669 
670      // The toast (role=status) carries the MENTION row's title
671      // ("You were mentioned in a comment").
672      await expect(
673        s.alice.page.getByRole("status").filter({ hasText: /mentioned in a comment/i }).first(),
674      ).toBeVisible({ timeout: BELL_PUSH_BUDGET_MS });
675 
676      // Cross-check the API is the source of truth (one unread MENTION row).
677      await expect
678        .poll(
679          async () =>
680            (await apiNotificationRows(s.alice.api)).filter(
681              (n) => n.type === "MENTION" && n.readAt === null,
682            ).length,
683          { timeout: API_SETTLE_MS, message: "API agrees: one unread MENTION row" },
684        )
685        .toBe(1);
686    } finally {
687      await s.closeAll();
688    }
689  });
690 
691  test("B3 — bell count tracks the API; row open navigates + marks read; mark-all → 0", async ({
692    browser,
693  }) => {
694    // R5/R7: 3 distinct mentions (API) → Alice's bell = 3; the inbox lists
695    // 3 rows under "Unread (3)"; a row's "Open" deep-links to the comment's
696    // page + marks it read (API unread → 2); back to the inbox →
697    // mark-all-read → 0 + the bell drops to the plain "Notifications" label.
698    const s = await partBSeed(browser);
699    try {
700      // 3 distinct page comments, each mentioning Alice → 3 unread MENTION rows.
701      for (let i = 0; i < 3; i += 1) {
702        const res = await s.owner.api.post("/api/v1/comments", {
703          data: {
704            targetType: "page",
705            targetId: s.pageId,
706            body: `${mentionToken("user", s.alice.id)} — item ${i + 1}`,
707          },
708        });
709        expect(res.status(), `comment ${i + 1}: ${await res.text()}`).toBeLessThan(300);
710      }
711      await expect
712        .poll(
713          async () =>
714            (await apiNotificationRows(s.alice.api)).filter(
715              (n) => n.type === "MENTION" && n.readAt === null,
716            ).length,
717          { timeout: API_SETTLE_MS, message: "API: three unread MENTION rows" },
718        )
719        .toBe(3);
720 
721      // Alice's shell (bell) + inbox.
722      await s.alice.page.goto(s.inboxUrl);
723      await expect(s.alice.page.getByTestId("notification-bell"), "shell authenticated").toBeVisible({
724        timeout: 20_000,
725      });
726      await expect(s.alice.page.getByTestId("notification-bell")).toHaveAttribute(
727        "aria-label",
728        "3 unread notifications",
729        { timeout: API_SETTLE_MS },
730      );
731      await expect(s.alice.page.getByText("Unread (3)")).toBeVisible();
732 
733      // Open the first row → navigates to the comment's page (the deep link
734      // uses the `pageId` ride-along) + marks it read (API unread 3 → 2).
735      const firstRow = s.alice.page.getByTestId(/^notification-row-/).first();
736      await firstRow.getByRole("button", { name: "Open" }).click();
737      await expect(s.alice.page).toHaveURL(/\/w\/[^/]+\/page\//, { timeout: 15_000 });
738      await expect
739        .poll(() => apiUnreadCount(s.alice.api), {
740          timeout: API_SETTLE_MS,
741          message: "API: unread 3 → 2 after opening a row",
742        })
743        .toBe(2);
744 
745      // Back to the inbox → mark-all-read → 0 + the bell's plain label.
746      await s.alice.page.goto(s.inboxUrl);
747      await expect(s.alice.page.getByTestId("mark-all-read")).toBeVisible({ timeout: 15_000 });
748      await s.alice.page.getByTestId("mark-all-read").click();
749      await expect.poll(() => apiUnreadCount(s.alice.api), {
750        timeout: API_SETTLE_MS,
751        message: "API: unread 0 after mark-all-read",
752      }).toBe(0);
753      await expect(s.alice.page.getByTestId("notification-bell")).toHaveAttribute(
754        "aria-label",
755        "Notifications",
756        { timeout: API_SETTLE_MS },
757      );
758    } finally {
759      await s.closeAll();
760    }
761  });
762 
763  test("B4 — a11y: the mention popup is a listbox with singular option names", async ({
764    browser,
765  }) => {
766    // R3 a11y (ux §12): typing "@" opens the grouped mention popup as
767    // role=listbox; each group is a labelled role=group; each option is
768    // role=option with the SINGULAR kind accessible name "Label (Member)";
769    // ArrowDown keeps exactly ONE option highlighted (one aria-selected);
770    // Escape closes the popup. The People group lists the workspace's members
771    // (owner + Alice + Bob, minus the composer's own user = owner → Alice + Bob).
772    const s = await partBSeed(browser);
773    try {
774      await s.owner.page.goto(s.pageUrl);
775      await openCommentsPanel(s.owner.page);
776 
777      // Type "@" → the popup opens as a listbox.
778      await s.owner.page.getByTestId("comment-composer").click();
779      await s.owner.page.keyboard.type("@");
780      const listbox = s.owner.page.getByTestId("mention-listbox");
781      await expect(listbox).toBeVisible({ timeout: 15_000 });
782      await expect(listbox).toHaveAttribute("role", "listbox");
783 
784      // The People group (role=group) + its options are role=option with the
785      // SINGULAR "Label (Member)" accessible name (mention-option-user-<id>).
786      const peopleGroup = listbox.getByRole("group", { name: /people/i }).first();
787      await expect(peopleGroup).toBeVisible();
788      const firstMemberOption = peopleGroup.getByRole("option").first();
789      await expect(firstMemberOption).toBeVisible();
790      await expect(firstMemberOption).toHaveAttribute("aria-label", /\(Member\)$/);
791      // Each People option carries the mention-option-user-<id> testid.
792      await expect(
793        peopleGroup.locator('[data-testid^="mention-option-user-"]'),
794      ).not.toHaveCount(0);
795 
796      // The People group is non-empty (owner + Alice + Bob, minus the composer
797      // = owner → at least Alice + Bob).
798      expect(await peopleGroup.getByRole("option").count(), "People group lists members").toBeGreaterThanOrEqual(2);
799 
800      // ArrowDown moves the highlight; exactly ONE option is selected at a time.
801      await s.owner.page.keyboard.press("ArrowDown");
802      const selectedCount = await listbox.locator('[aria-selected="true"]').count();
803      expect(selectedCount, "exactly one option highlighted after ArrowDown").toBe(1);
804 
805      // Escape closes the popup (it leaves the DOM).
806      await s.owner.page.keyboard.press("Escape");
807      await expect(listbox).toHaveCount(0);
808    } finally {
809      await s.closeAll();
810    }
811  });
812});
813