chore(web): move App.tsx's module-level block into files

[cliffhall]

Closes #2127

Phase 0 of #2126 — the module-level block at the top of clients/web/src/App.tsx moves into files. App.tsx: 5,303 → 4,892 lines (−411). No behavior change: every symbol moved verbatim, and the only edits to the bodies are the export keyword and the import paths.

What moved where

Placement follows the lib vs utils rule in AGENTS.md — pure computation to utils/, anything touching the environment to lib/.

Symbols	Destination
redirectUrlProvider, getAuthToken	lib/authToken.ts
messagesToLogEntries, replayProtocolRequest	lib/protocolReplay.ts
errorMessage, errorCodeOf, formatErrorDetails	utils/errorFormat.ts
EMPTY_SETTINGS	utils/serverSettingsDefaults.ts
isEmaStepUp, isStepUpConfirmation, StepUpSource	utils/stepUp.ts
bodyDroppedToastId, CLIENT_CONFIG_LOAD_ERROR_NOTIFICATION_ID	utils/toasts/toastIds.ts
PROGRESS_TOAST_AUTOCLOSE_MS, progressToastId, formatProgressToastMessage	utils/toasts/progressToasts.ts
TASK_CANCELLED_TOAST_AUTOCLOSE_MS, TERMINAL_TASK_STATUSES, isTerminalTaskStatus, taskToastId, taskToastColor, TaskToastInput, formatTaskToastMessage	utils/toasts/taskToasts.ts
ToastCauseList, ToastLinkButton	components/elements/Toasts/ToastPrimitives.tsx
FetchBodyDroppedToastMessage	components/elements/Toasts/FetchBodyDroppedToastMessage.tsx
OutputValidationToastMessage	components/elements/Toasts/OutputValidationToastMessage.tsx
UrlElicitationErrorToastMessage	components/elements/Toasts/UrlElicitationErrorToastMessage.tsx
ReAuthBannerBar	components/groups/ReAuthBanner/ReAuthBannerBar.tsx

Three judgment calls worth reviewing rather than deciding silently

1. EMPTY_SETTINGS and the toast ids did NOT go to a new top-level src/constants.ts, which is what the issue's table suggested. The web coverage include in clients/web/vite.config.ts is a whitelist naming components/hooks/theme/lib/utils/server, so a module at src/constants.ts would have fallen out of the ≥90 gate entirely and silently — the exact hazard AGENTS.md calls out. They live under utils/ instead, where they are gated like everything else.

2. The issue asked whether the error helpers already had a near-duplicate. Checked: clients/web/src/{utils,lib,components} export nothing equivalent, so there was no home to extend. The err instanceof Error ? err.message : String(err) idiom does appear inline ~10 times in core/, but that is a different package with no web-side importer, and hoisting it there is a wider change than this phase.

3. ReAuthBannerBar is in the block but not in the issue's table — it was added to App.tsx after the issue was written (#2108). It moved too, to components/groups/ReAuthBanner/, beside the banner it wraps.

Two v8 ignore annotations, both justified in place

• getAuthToken's typeof window === "undefined" guard — a happy-dom-inherent path, one of the categories AGENTS.md names. The function was never gated before (it lived in the ungated App.tsx), so this is the first time the branch has had to answer for itself.
• replayProtocolRequest's default: case — provably dead: isReplayableProtocolMethod admits exactly the nine methods the switch enumerates. Kept anyway so that adding a method to REPLAYABLE_PROTOCOL_METHODS without a case here reports a reason rather than resolving as a dispatched replay.

Coverage

Every new module is at 100% on all four dimensions (lines/statements/functions/branches), comfortably over the ≥90 gate:

src/lib/authToken.ts                                     100 / 100 / 100 / 100
src/lib/protocolReplay.ts                                100 / 100 / 100 / 100
src/utils/errorFormat.ts                                 100 / 100 / 100 / 100
src/utils/serverSettingsDefaults.ts                      100 / 100 / 100 / 100
src/utils/stepUp.ts                                      100 / 100 / 100 / 100
src/utils/toasts/toastIds.ts                             100 / 100 / 100 / 100
src/utils/toasts/progressToasts.ts                       100 / 100 / 100 / 100
src/utils/toasts/taskToasts.ts                           100 / 100 / 100 / 100
src/components/elements/Toasts/ToastPrimitives.tsx       100 / 100 / 100 / 100
src/components/elements/Toasts/FetchBodyDropped…tsx      100 / 100 / 100 / 100
src/components/elements/Toasts/OutputValidation…tsx      100 / 100 / 100 / 100
src/components/elements/Toasts/UrlElicitationErr…tsx     100 / 100 / 100 / 100
src/components/groups/ReAuthBanner/ReAuthBannerBar.tsx   100 / 100 / 100 / 100

The four toast components render through renderWithMantine (never a hand-rolled provider). getAuthToken gets a case per source in the priority order plus both storage-unavailable branches — happy-dom returns a fresh Storage wrapper per window.sessionStorage access, so a spy on the instance never fires; the test replaces the property instead, and says so in a comment.

Toasts/ was the only components/elements/ directory without a *.stories.tsx, so it has one now, matching the convention the web README states.

Docs

AGENTS.md and clients/web/README.md both carry an anchors list for the lib vs utils split; the new modules are added to both.

Screenshots

None — this is a pure move with no rendered change. The four toast bodies and the re-auth banner render from the same JSX they did before, through the same call sites.

Verification

npm run ci green.

[Copilot]

Pull request overview

Phase 0 of decomposing App.tsx, extracting module-level helpers and UI fragments into gated, purpose-specific modules without intended behavior changes.

Changes:

• Moves environment adapters to lib/ and pure helpers to utils/.
• Extracts toast and re-auth UI components.
• Adds unit tests, Storybook coverage, and architecture documentation.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
AGENTS.md	Documents new lib and utils examples.
clients/web/README.md	Updates web architecture guidance.
clients/web/src/App.tsx	Replaces module-level definitions with imports.
clients/web/src/lib/authToken.ts	Extracts token and redirect handling.
clients/web/src/lib/authToken.test.ts	Tests token source priority and storage failures.
clients/web/src/lib/protocolReplay.ts	Extracts log conversion and protocol replay.
clients/web/src/lib/protocolReplay.test.ts	Tests replay methods and log filtering.
clients/web/src/utils/errorFormat.ts	Extracts error-formatting helpers.
clients/web/src/utils/errorFormat.test.ts	Tests error formatting branches.
clients/web/src/utils/serverSettingsDefaults.ts	Extracts stable settings defaults.
clients/web/src/utils/serverSettingsDefaults.test.ts	Verifies defaults and identity.
clients/web/src/utils/stepUp.ts	Extracts step-up adapters and type.
clients/web/src/utils/stepUp.test.ts	Tests step-up classification.
clients/web/src/utils/toasts/toastIds.ts	Extracts shared toast identifiers.
clients/web/src/utils/toasts/toastIds.test.ts	Tests stable toast identifiers.
clients/web/src/utils/toasts/progressToasts.ts	Extracts progress-toast formatting.
clients/web/src/utils/toasts/progressToasts.test.ts	Tests progress-toast behavior.
clients/web/src/utils/toasts/taskToasts.ts	Extracts task-toast helpers.
clients/web/src/utils/toasts/taskToasts.test.ts	Tests task status and formatting.
clients/web/src/components/groups/ReAuthBanner/ReAuthBannerBar.tsx	Extracts the re-auth banner container.
clients/web/src/components/groups/ReAuthBanner/ReAuthBannerBar.test.tsx	Tests banner positioning styles.
clients/web/src/components/elements/Toasts/ToastPrimitives.tsx	Adds shared toast primitives.
clients/web/src/components/elements/Toasts/FetchBodyDroppedToastMessage.tsx	Extracts body-drop warning content.
clients/web/src/components/elements/Toasts/OutputValidationToastMessage.tsx	Extracts validation warning content.
clients/web/src/components/elements/Toasts/UrlElicitationErrorToastMessage.tsx	Extracts elicitation error content.
clients/web/src/components/elements/Toasts/Toasts.test.tsx	Tests extracted toast components.
clients/web/src/components/elements/Toasts/Toasts.stories.tsx	Adds toast component stories.

Suppressed comments (7)

clients/web/src/lib/protocolReplay.test.ts:30

• The double cast bypasses the MessageEntry contract even though this is intended to be a valid request fixture. Type it directly and supply the required tracking id and Date timestamp.

    } as unknown as MessageEntry;

clients/web/src/lib/protocolReplay.test.ts:35

• The double cast bypasses the MessageEntry contract even though this is intended to be a valid response fixture. Type it directly and supply the required tracking id and Date timestamp.

    } as unknown as MessageEntry;

clients/web/src/lib/authToken.test.ts:59

• The double cast is unnecessary and violates the repository's type-safety rule. Delete the injected property through the reflection API instead.

    delete (window as unknown as Record<string, unknown>)[
      INSPECTOR_API_TOKEN_GLOBAL
    ];

clients/web/src/lib/authToken.test.ts:64

• Avoid casting window through unknown just to install the test global; Reflect.set handles a dynamic property key without erasing the object's type.

    (window as unknown as Record<string, unknown>)[INSPECTOR_API_TOKEN_GLOBAL] =
      "from-global";

clients/web/src/lib/authToken.test.ts:74

• Avoid the unjustified double cast when setting the empty injected token; use the reflection API for the dynamic global property.

    (window as unknown as Record<string, unknown>)[INSPECTOR_API_TOKEN_GLOBAL] =
      "";

clients/web/src/lib/authToken.test.ts:80

• Avoid the unjustified double cast when setting the non-string injected token; use the reflection API for the dynamic global property.

    (window as unknown as Record<string, unknown>)[INSPECTOR_API_TOKEN_GLOBAL] =
      123;

clients/web/src/lib/authToken.test.ts:100

• Avoid casting window through unknown here as well; use the reflection API to set the injected token while preserving type safety.

    (window as unknown as Record<string, unknown>)[INSPECTOR_API_TOKEN_GLOBAL] =
      "from-global";

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[cliffhall]

Round 1 of Copilot review addressed in 4b119c9. Mirroring here since the inline replies go hidden once the threads are outdated.

Accepted — 6 of 7

1. lib/protocolReplay.ts importing "up" into components/. Fixed in the half that was a real runtime edge: REPLAYABLE_PROTOCOL_METHODS / isReplayableProtocolMethod is a pure predicate over a string set, so by the project's own lib vs utils rule it never belonged in components/groups/protocolUtils.ts. It now lives in utils/replayableProtocolMethods.ts with both consumers (ProtocolEntry and this module) importing from there, and its own test. The LogEntryData import stays and is now commented: it is type-only, so it produces no runtime edge — AGENTS.md draws that same line for the analogous case — and re-homing the interface would move the shape the Logs screen renders away from the component that renders it, for nothing the compiler or bundle can observe.

2. ReplayClient contract. replayProtocolRequest now takes an exported Pick<InspectorClient, …> naming the nine methods it calls; the test's mock is satisfies ReplayClient with each vi.fn<ReplayClient["method"]>() typed against the real signature. The cast is gone and a drift in InspectorClient now fails the typecheck here.

3. MessageEntry fixtures. This one was a real defect, not just a style violation: MessageEntry.timestamp is a Date and the fixture passed 1000, and since messagesToLogEntries copies that straight onto LogEntryData.receivedAt (also a Date), the assertion was confirming a shape the function cannot produce. All three fixtures are plain typed values now, each commented with which direction-vs-frame-shape disagreement it exercises.

4. window double casts. Reflect.set / Reflect.deleteProperty in all six places; zero as unknown as remain in either test file. The 123 case is deliberate and survives — it is what covers the typeof fromGlobal === "string" guard.

5. Stale placement comment on ReAuthBannerBar. Good catch. That sentence predates the move to a centered popup, moved verbatim, and arrived contradicting the paragraph directly below it. Gone; the rest of the rationale (why it is not a sticky full-bleed bar) still holds and is kept.

Declined — 1 of 7

6. styles: { root: { transform, zIndex } } as an inline style. Two reasons. It is not an inline style: AGENTS.md forbids style={{…}}, whereas styles is Mantine's Styles API, and the rule's own preference order puts component props first — which is what withProps is. Those two properties are here precisely because they cannot be props, since Mantine exposes neither z nor transform as one; the comment on the constant already says so. And re-homing them as a Paper theme variant is a styling change rather than a move — worth doing, but not in the phase whose entire safety argument is that every symbol is byte-identical to what was in App.tsx.

npm run ci green after the changes.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated no new comments.