refactor(web): sweep AGENTS.md TypeScript + Mantine rule violations (#1762)

[cliffhall]

Closes #1762

Summary

Codebase-wide audit sweep against the AGENTS.md TypeScript and Mantine/React conventions, driven by three parallel per-cluster audits (TypeScript rules, Mantine styling, Mantine structure). The codebase was already in strong shape (post-#1690/#1756), so the actionable set is small and cohesive — this is one reviewable PR rather than a batch.

Audit outcome (verified inventory)

• TypeScript: zero any types; zero config-level suppressions (no-unused-vars stays at error with the sanctioned _-prefix pattern); all 12 non-test as unknown as casts already carry justification comments. Two tightenings applied (below).
• Styling: no inline styles (the one in SortableServerCard is the sanctioned dnd-kit per-frame transform), no stray hex/rgba() in props or theme overrides (theme.ts hex are the Mantine palette tuples; issue-number #1234 comments are not colors), no layout divs. One minor CSS-class finding fixed.
• Structure: Rules for Box.withProps misuse (0), domain logic in theme files (0), and elements importing from src/theme/ (0) are all clean. Repeated-inline-element and inline-logic findings fixed (below).

Changes

Styling

• ServerListScreen: fold align-items: start into the existing styles prop; drop the .grid-align-start class + its App.css rule.

Structure — extract repeated inline elements to named .withProps() constants

• NetworkEntry: DimmedNote (xs/dimmed) + SectionLabel (sm/500) replace 9 repeated inline <Text>s.
• ServerImportConfigModal: GroupHeading replaces 3 repeated <Text fw={600} size="sm">s.
• ViewHeader: HeaderStackCell replaces the twice-repeated animated wrapper (mirrors the file's existing RightConnectedGroup className-in-withProps convention).
• ResourceControls: TightRow replaces two <Group gap="xs" wrap="nowrap">.

Structure — extract inline logic to named functions

• ToolsScreen: handleSelectTool replaces the ~20-line inline onSelectTool handler.
• ServerConfigModal: setTextField/clearTextField factories replace 6 repeated text-field onChange/clear closures.

TypeScript

• App.tsx messagesToLogEntries: replace an as unknown as double cast with a single narrowing cast on just the params value.
• createRemoteLogger: the pino/browser.js @ts-expect-error is genuinely unavoidable — TS resolves the real untyped JS file, so an ambient declare module can't type it (I tried; it fails with TS7016). Kept, with a comment now explaining why no better option exists.

Testing

npm run ci passes end to end: validate → the per-file ≥90 coverage gate → smokes (incl. the headless-browser boot smoke) → all 456 Storybook play-function tests. All 3472 unit tests pass; every touched file clears the ≥90 coverage threshold.

🤖 Generated with Claude Code

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 2m 51s —— View job

---

Code review — PR #1771

• Gather context (read full diff)
• Review styling changes (App.css, ServerListScreen)
• Review structural extractions (NetworkEntry, ServerImportConfigModal, ViewHeader, ResourceControls)
• Review logic extractions (ToolsScreen, ServerConfigModal)
• Review TypeScript changes (App.tsx, createRemoteLogger)
• Post review

---

Verdict

Looks good — no blocking issues. This is a genuinely behavior-preserving sweep. I traced each change against the AGENTS.md rule it claims to satisfy and against the CSS/type context, and every extraction is faithful. Comments below are nits and one thing worth a conscious sign-off.

What I verified

• .grid-align-start removal — no remaining references anywhere in the repo (searched all file types, incl. stories/tests). className and styles.root both target SimpleGrid's root, so alignItems: "start" lands on the same element the class did; inline-from-styles also outranks the deleted class, so no specificity regression.
• App.tsx cast — genuinely equivalent, not just shorter. LogEntryData.params is already declared as LoggingMessageNotification["params"] (LogEntry.tsx:11), so the single cast now matches the consumer's own type exactly instead of routing through a whole-object double cast. Good tightening.
• ToolsScreen — the formValues → nextFormValues rename is necessary and correct: at function scope the old name would shadow the formValues destructured from ui at line 161. The /* v8 ignore next */ still sits immediately above if (tool), so the ignore still lands on the intended line after reflow.
• ServerConfigModal handler factories — the ChangeEvent<HTMLInputElement | HTMLTextAreaElement> param is contravariantly assignable to both TextInput's and Textarea's narrower onChange slots, so the one factory legitimately serves both. Identity churn per render is unchanged (inline arrows before, factory calls now). Nice that the currentTarget-nulling rationale got promoted from a per-callsite comment to one canonical spot.
• NetworkEntry / ResourceControls / ServerImportConfigModal — prop-for-prop identical; SectionLabel c="red" and DimmedNote aria-live="polite" override/extend correctly through withProps. Text/Group remain imported and used elsewhere in each file, so no dead imports.

Notes

1. HeaderStackCell: Box → Group is a display-model change — clients/web/src/components/groups/ViewHeader/ViewHeader.tsx:180-185

Box rendered a plain block div; Group renders display: flex; align-items: center; flex-wrap: wrap. The cell is grid-area: 1 / 1; place-self: center (App.css:348), and each instance has exactly one child (a SegmentedControl or a Title), so shrink-to-fit sizing should be identical in practice — but this is the one change in the PR that isn't purely mechanical. Worth an eyeball on the connect/disconnect crossfade if you haven't already. The swap itself is required (AGENTS.md forbids Box.withProps) and Group matches the file's existing RightConnectedGroup/ServerName className-in-withProps convention, so I wouldn't change the approach.

2. TextField union could derive from FormState — ServerConfigModal.tsx:53

type TextField = Exclude<keyof FormState, "transport">;

Self-maintaining: adding a string field to FormState picks it up automatically, and adding a non-string field would surface as a type error at the factory rather than silently drifting from the hand-written list. Purely a maintainability nit — the current union is correct today. Fix this →

3. alignItems in styles vs. a theme variant — ServerListScreen.tsx:143

AGENTS.md's preference order puts theme variants above CSS classes, and a styles prop sits somewhere in between (Mantine emits it as an inline style on the root). Folding it into the pre-existing GRID_SURFACE_STYLES is clearly better than the standalone class, and this grid is a one-off, so I'd leave it — flagging only so the choice is deliberate rather than accidental if a future sweep re-reads this line as an inline style.

4. Pre-existing (not introduced here): messagesToLogEntries asserts params is present, but the JSONRPC notification type makes it optional — a malformed notifications/message with no params would yield params: undefined and blow up in LogEntry. The old double cast had the exact same hole, so this PR is neutral on it; mentioning it only in case it's worth a follow-up guard.

5. createRemoteLogger @ts-expect-error — agreed with the analysis. TS resolves the real pino/browser.js, so an ambient declare module "pino/browser.js" is shadowed and you land on TS7016 regardless. The expanded comment is the right outcome; it now explains why no better option exists, which is what the AGENTS.md escape-hatch policy asks for.

Nothing found on

any usage, config-level lint suppressions, dead CSS/imports, changed prop semantics, or coverage-ignore drift.

---

· branch v2/fix-1762-agents-md-sweep

[cliffhall]

Thanks for the thorough trace-through. Responses to each note:

1. HeaderStackCell Box → Group display-model change — Verified visually. Ran the dev server and screenshotted the header: the disconnected "MCP Inspector" title renders centered in the stack cell exactly as before, and the server cards below are correctly top-aligned (confirming the alignItems: "start" fold). The connected-state header (tab bar) uses the same HeaderStackCell constant with a single SegmentedControl child, so the shrink-to-fit sizing is identical — the swap is a visual no-op. The 20 ViewHeader unit tests plus the Storybook crossfade play-functions (which assert the mid-flight data-anim="out" state) also stay green.

2. TextField derive from FormState — Applied in 4e5e022. Now type TextField = Exclude<keyof FormState, "transport">; typecheck + the 27 ServerConfigModal tests pass. Agreed it's the self-maintaining form.

3. alignItems in styles vs. theme variant — Deliberate. This grid is a one-off and GRID_SURFACE_STYLES already existed as the home for its root-level overrides, so folding the property in there (rather than minting a theme variant for a single consumer) is the proportionate choice. Noted for the record.

4. Pre-existing params-optional hole in messagesToLogEntries — Correct that it's pre-existing and this PR is neutral on it (the old double cast had the identical assumption). Out of scope for a behavior-preserving sweep; I'll leave a follow-up note rather than widen this PR.

5. createRemoteLogger @ts-expect-error — Agreed, thanks for confirming the TS7016 reasoning independently.

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 3m 20s —— View job

---

Code review — PR #1771 (re-review)

• Read full diff vs origin/v2/main
• Verify the new commit (4e5e022 — TextField derived from FormState)
• Re-verify styling / structural / logic extractions
• Re-verify TypeScript changes
• Post review

---

Verdict

Approve-equivalent — one comment-accuracy nit, nothing blocking. The follow-up commit 4e5e022 lands the TextField derivation cleanly, and everything else re-verifies as behavior-preserving. One finding below: a claim in the new comment doesn't hold under TypeScript, and I checked it against a compiler rather than reasoning about it.

Finding — the TextField comment overstates what the type guarantees

clients/web/src/components/groups/ServerConfigModal/ServerConfigModal.tsx:50-54

// … adding a string field picks it up, and adding a
// non-string field would surface as a type error at the factory instead of
// silently drifting.
type TextField = Exclude<keyof FormState, "transport">;

The first clause is true. The second isn't. A computed property whose key is a union of literals doesn't narrow the assignment — TS widens the literal to an index signature and the spread keeps the declared property types, so the result still satisfies FormState and nothing errors. Verified with tsc --strict:

interface FormState { id: string; transport: "stdio" | "sse"; command: string; port: number; }
type TextField = Exclude<keyof FormState, "transport">;   // includes "port"
const setTextField = (field: TextField) => (v: string) =>
  setForm((f): FormState => ({ ...f, [field]: v }));       // no error
setTextField("port");                                      // no error — a string lands in a number field

→ exit=0. So a future non-string FormState field would be silently accepted by setTextField, which is exactly the drift the comment says it prevents. (Same exposure the hand-written union had, so this is not a regression — the code is fine today, the comment just promises more than it delivers.)

Two ways to close it, either is fine:

(a) Trim the comment to the claim that holds — "derived so a new string field is picked up automatically."

(b) Make the type actually enforce it — select on the value type instead of excluding by name. Verified this does error at the call site (TS2345: Argument of type '"port"' is not assignable to parameter of type 'TextField'):

// Keys whose value is exactly `string` — excludes `transport`, whose value is a
// literal union, and any future non-string field.
type PlainStringKeys<T> = { [K in keyof T]-?: string extends T[K] ? K : never }[keyof T];
type TextField = PlainStringKeys<FormState>;

This also drops the hand-written "transport" from the type. Fix this →

Re-verified clean

• 4e5e022 (TextField) — FormState's six non-transport fields are all string, so Exclude<keyof FormState, "transport"> is exactly the previous hand-written union. Correct today.
• setTextField / clearTextField — ChangeEvent<HTMLInputElement | HTMLTextAreaElement> is contravariantly assignable to both TextInput's and Textarea's narrower onChange slots, so one factory legitimately serves both. Handler identity churn per render is unchanged (inline arrows before, factory calls now). The currentTarget-nulling rationale reads better as one canonical comment than six copies.
• App.tsx cast — LogEntryData.params is declared LoggingMessageNotification["params"] (clients/web/src/components/elements/LogEntry/LogEntry.tsx:11), so the single cast now targets the consumer's own type exactly instead of routing the whole object through unknown. Genuine tightening, not just shorter.
• .grid-align-start removal — zero remaining references anywhere in the repo (searched all file types incl. tests/stories). className and styles.root both target SimpleGrid's root, and styles emits an inline style that outranks the deleted class, so no specificity regression.
• HeaderStackCell (Box → Group) — the two ViewHeader cells sit at grid-area: 1 / 1; place-self: center (App.css:348-351), so both a block div and a flex row shrink-to-fit identically with a single child; gap/wrap are inert at one child. The 20 ViewHeader tests locate the cell via closest("[data-anim]") (ViewHeader.test.tsx:240,265,327,…) — element- and class-agnostic, so the swap can't silently break them. Combined with your visual check, I'm satisfied.
• NetworkEntry / ResourceControls / ServerImportConfigModal — prop-for-prop identical; SectionLabel c="red" overrides and DimmedNote aria-live="polite" extends correctly through withProps; Text/Group/Box all still used elsewhere in each file, so no dead imports.
• ToolsScreen — the formValues → nextFormValues rename is required (the old name would shadow the formValues destructured from ui), and /* v8 ignore next */ still sits immediately above if (tool) after the reflow.
• createRemoteLogger — agreed on the TS7016 reasoning; the expanded comment now explains why no better option exists, which is what the AGENTS.md escape-hatch policy asks for.

Nothing found on

any usage, config-level lint suppressions, dead CSS, changed prop semantics, coverage-ignore drift, or new inline styles.

---

· branch v2/fix-1762-agents-md-sweep

[cliffhall]

Good catch — you're right that the computed union key widens to an index signature, so the "type error at the factory" claim didn't hold. Applied your option (b) in 6a7b85d: TextField is now PlainStringKeys<FormState> (selects keys whose value is exactly string), which drops the hand-written "transport" and actually makes passing a non-string key a compile error at the call site — the guarantee the comment now describes. Typecheck + the 27 ServerConfigModal tests pass.

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 2m 54s —— View job

---

Code review — PR #1771 (re-review after 6a7b85d1)

• Read full diff vs origin/v2/main
• Verify the new commit (6a7b85d1 — PlainStringKeys<FormState>) against a real compiler
• Re-verify styling / structural / logic / TypeScript changes
• Post review

---

Verdict

Approve-equivalent. 6a7b85d1 closes the previous finding properly — I re-ran the enforcement claim through tsc --strict rather than reasoning about it, and it now holds. One new (minor, optional) finding below: a residual instance of the exact rule this PR applied elsewhere.

Verified: PlainStringKeys genuinely enforces what the comment claims

clients/web/src/components/groups/ServerConfigModal/ServerConfigModal.tsx:51-60

I compiled the pattern with a FormState deliberately containing a number field, an optional string, and the literal-union transport:

interface FormState { id: string; transport: "stdio" | "sse"; command: string; port: number; maybe?: string; }
type PlainStringKeys<T> = { [K in keyof T]-?: string extends T[K] ? K : never }[keyof T];
type TextField = PlainStringKeys<FormState>;
const setTextField = (field: TextField) => (v: string) => setForm((f) => ({ ...f, [field]: v }));

setTextField("id");         // ok
setTextField("maybe");      // ok — `-?` strips undefined, so `string extends string`
// @ts-expect-error port is a number
setTextField("port");
// @ts-expect-error transport is a literal union
setTextField("transport");

→ exit=0 with both @ts-expect-errors consumed (an unused one would have failed the run), so the errors really fire. This is the enforcing version, and the hand-written "transport" exclusion is correctly gone. FormState's six non-transport fields are all plain string, so TextField resolves to exactly the previous set — no call-site churn.

_{Pedantic footnote, not a finding: string extends T[K] also admits unknown and any-typed keys. Neither exists in FormState and neither would ever be added for a text input, so the comment reads true in practice.}

Finding (minor) — the same flat-CSS-class rule is left unapplied on the constant this PR just created

clients/web/src/components/groups/ViewHeader/ViewHeader.tsx:181-185 · clients/web/src/App.css:348-351

The PR's styling change removes .grid-align-start because a flat property (align-items) doesn't belong in App.css. HeaderStackCell — a constant introduced by this PR — carries a class whose rule is flat-only, with no pseudo-selector or keyframe companion:

.header-stack-cell { grid-area: 1 / 1; place-self: center; }

Contrast the file's other classes, which all earn their place and say so in a comment: .header-anim is keyframe/attribute-selector driven, .server-drag-handle and .resize-handle are cursor + :hover/:active, .markdown-content is nested third-party selectors. .header-stack-cell is the only one in the className:-in-withProps set that is pure flat CSS. Per AGENTS.md ("flat CSS properties … belong in the theme"), it's the same finding the PR fixed one file over:

const HeaderStackCell = Group.withProps({
  className: "header-anim",
  styles: { root: { gridArea: "1 / 1", placeSelf: "center" } },
});

I checked the blast radius: zero references to header-stack-cell in any test or story, and the prefers-reduced-motion block targets only .header-anim[data-anim=…], so the class can be deleted from App.css without touching the reduced-motion path. The prose comment at ViewHeader.tsx:339 mentions it by name and would need a word change.

Low stakes and entirely defensible to leave — but this is a sweep PR whose stated deliverable is catching exactly this, so it's worth either fixing or recording as deliberate. Fix this →

Re-verified clean

• .grid-align-start removal — zero remaining references repo-wide (all file types, incl. tests/stories). className and styles.root both land on SimpleGrid's root, and styles emits an inline style that outranks the deleted class, so no specificity regression.
• App.tsx cast — "method" in m.message narrows to JSONRPCRequest | JSONRPCNotification (core/mcp/types.ts:281-284), both of which expose params, and LogEntryData.params is declared as LoggingMessageNotification["params"]. The single cast now targets the consumer's own type instead of routing the whole object through unknown — a real tightening, not just shorter.
• ServerConfigModal factories — ChangeEvent<HTMLInputElement | HTMLTextAreaElement> is contravariantly assignable to both TextInput's and Textarea's narrower onChange slots, so one factory legitimately serves both; clearTextField's returned thunk ignoring ClearButton's MouseEvent arg is fine. Handler identity churn per render is unchanged (inline arrows before, factory calls now). The currentTarget-nulling rationale reads better as one canonical comment than six copies.
• HeaderStackCell (Box → Group) — both cells sit at grid-area: 1 / 1; place-self: center, so block-div and flex-row shrink-to-fit identically with a single child; gap/wrap are inert at one child. Tests locate the cell via closest("[data-anim]"), which is element- and class-agnostic. Combined with your screenshot check, settled.
• NetworkEntry / ResourceControls / ServerImportConfigModal — prop-for-prop identical; SectionLabel c="red" overrides and DimmedNote aria-live="polite" extends correctly through withProps. Text/Group/Box all still used elsewhere in each file — no dead imports.
• ToolsScreen — the formValues → nextFormValues rename is required (the old name would shadow the formValues destructured from ui), and /* v8 ignore next */ still sits immediately above if (tool) after the reflow.
• createRemoteLogger — agreed on TS7016; the expanded comment now explains why no better option exists, which is what the AGENTS.md escape-hatch policy asks for.

Nothing found on

any usage, config-level lint suppressions, dead CSS, changed prop semantics, coverage-ignore drift, or new inline styles.

_{Caveat: this checkout has no node_modules, so I did not run the suite — I'm taking your npm run ci result at face value. The tsc verification above was run against a standalone TypeScript 5.9 install.}

--- · branch v2/fix-1762-agents-md-sweep

[cliffhall]

Nice consistency catch — you're right that .header-stack-cell was flat-only CSS and is exactly what this sweep is meant to fix, especially on a constant the PR itself introduced. Applied in 553e874: folded grid-area/place-self into HeaderStackCell's styles.root, kept the keyframe-driven header-anim class, deleted the App.css block, and updated the two prose comments that named the class. The prefers-reduced-motion block only targets .header-anim[data-anim=…], so it's untouched. validate:web (3472 unit tests) + the ViewHeader Storybook crossfade play-tests pass.

Also confirmed your PlainStringKeys re-verification — thanks for compiling the @ts-expect-error cases rather than reasoning about them.

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 3m 23s —— View job

---

Code review — PR #1771 (re-review after 553e8742)

• Read full diff vs origin/v2/main
• Verify the new commit (553e8742 — .header-stack-cell fold)
• Re-verify styling / structural / logic / TypeScript changes
• Post review

---

Verdict

Approve-equivalent — no blocking issues. 553e8742 closes the last finding correctly, and I verified the fold can't regress the animation rather than assuming it. One observation below about the criterion the sweep applied, worth recording on the issue so a future audit doesn't re-derive a different (much larger) set from the same rule.

Verified: the .header-stack-cell fold is safe, including the animation path

clients/web/src/components/groups/ViewHeader/ViewHeader.tsx:181-186 · clients/web/src/App.css

The concern with moving CSS-class properties into Mantine's styles prop is that styles emits an inline style attribute, which outranks any stylesheet rule for the same property — exactly the hazard your own src/theme/Group.ts:10-11 comment warns about (#1460). I checked whether that applies here and it does not:

• .header-anim[data-anim="in"|"out"] (App.css:338-344) sets only animation; the keyframes inspector-fade-slide-in/-out (App.css:280-300) animate only opacity and transform.
• The folded properties are grid-area and place-self.

Disjoint sets — the inline style can't shadow the animation, and the prefers-reduced-motion block (App.css:349-354) targets .header-anim[data-anim=…] { animation: none }, which is likewise untouched. Keeping className: "header-anim" (keyframe-driven → legitimately CSS) while moving the flat properties is the right split per AGENTS.md.

Also checked:

• Zero dangling references to header-stack-cell or grid-align-start anywhere under clients/, core/, docs/, specification/ — all file types, incl. tests and stories.
• Prose comments are accurate. ViewHeader.tsx:340-341 now says "grid-area 1/1, set on HeaderStackCell"; the three surviving header-anim mentions (:60, :153, :182) all still describe a real class.
• Box is still used in the file (:344 grid stack, :445 Transition interpolation), so no dead import.

Observation — the sweep applied a repetition criterion, not AGENTS.md's literal one

Not a defect in this PR, but worth pinning down because #1762 is framed as a codebase-wide audit and the next person re-running it will get a different answer.

AGENTS.md's literal rule is "ALWAYS declare a meaningfully named subcomponent as a constant using .withProps() if a component has two or more props." The sweep instead extracted elements repeated within a file — which is the pragmatic reading, and it was applied consistently. But under the literal reading there are ~30 remaining multi-prop inline Mantine elements across clients/web/src/components, three of them in files this PR touched:

Location	Element
NetworkEntry.tsx:518	<Text span ff="monospace">
NetworkEntry.tsx:569	<Text size="xs" ff="monospace" c="red">
ServerConfigModal.tsx:425	<Text c="red" size="sm" role="alert">

Each is a single occurrence within its file, so leaving them is consistent with the criterion actually used — NetworkEntry.tsx:569 sitting directly under the newly-extracted SectionLabel c="red" just makes the boundary visible. There's also cross-file repetition the within-file criterion structurally can't catch (<Group justify="space-between" mb="sm"> ×5 in TaskListPanel / LogStreamPanel / ProtocolListPanel / NetworkStreamPanel / ConsoleScreen; <Text c="red" size="sm" role="alert"> ×2 in ServerConfigModal / ServerRemoveConfirmModal).

Suggestion: rather than widening this PR, record the interpretation — either note on #1762 that "repeated within a file" is the operative bar, or tighten the AGENTS.md wording so the rule and the practice agree. As written, the two diverge by ~30 instances.

Re-verified clean

• PlainStringKeys<FormState> (ServerConfigModal.tsx:51-60) — FormState's six non-transport fields are all plain string and transport is the literal union "stdio" | "sse" | "streamable-http", so string extends T[K] excludes it and TextField resolves to exactly the previous set — no call-site churn. Matches last round's tsc --strict check (both @ts-expect-errors consumed), so the comment's enforcement claim now holds.
• setTextField / clearTextField — ChangeEvent<HTMLInputElement | HTMLTextAreaElement> is contravariantly assignable to both TextInput's and Textarea's narrower onChange slots; clearTextField's thunk correctly ignores ClearButton's MouseEvent. Handler identity churn per render is unchanged (inline arrows before, factory calls now).
• App.tsx cast — "method" in m.message narrows to the request/notification arm, both of which expose params; LogEntryData.params is declared LoggingMessageNotification["params"], so the single cast now targets the consumer's own type instead of routing the whole object through unknown. Real tightening.
• .grid-align-start → GRID_SURFACE_STYLES — className and styles.root both land on SimpleGrid's root; styles emits inline, which outranks the deleted class, so no specificity regression. alignItems: "start" type-checks against csstype's SelfPosition even under as const.
• Box → Group on HeaderStackCell — with justify-self: center from place-self, both a block div and a flex row shrink-to-fit; gap/wrap/align-items are inert at one child, and preventGrowOverflow only engages under grow, which isn't set. Tests locate the cell via closest("[data-anim]"), element- and class-agnostic. Combined with your screenshot, settled.
• NetworkEntry / ResourceControls / ServerImportConfigModal — prop-for-prop identical; SectionLabel c="red" overrides and DimmedNote aria-live="polite" extends correctly (Mantine's withProps spreads call-site props last). No dead imports.
• ToolsScreen — the formValues → nextFormValues rename is required (the old name would shadow the formValues destructured from ui), and /* v8 ignore next */ still sits immediately above if (tool), so the ignored branch is unchanged.
• createRemoteLogger — agreed on TS7016; the expanded comment explains why no better option exists, which is what the AGENTS.md escape-hatch policy asks for.

Nothing found on

any usage, config-level lint suppressions, dead CSS, changed prop semantics, coverage-ignore drift, or new inline style={{…}} props.

_{Caveat: this checkout has no node_modules, so I did not run the suite — taking your npm run ci result at face value. All CSS/type reasoning above was checked against the files in the branch.}

--- · branch v2/fix-1762-agents-md-sweep

[cliffhall]

Thanks — glad the animation-path check confirmed the fold is safe (the grid-area/place-self vs opacity/transform disjointness is exactly why keeping header-anim as a class while moving only the flat props is the right split).

On the observation: agreed it's a criterion question, not a PR defect, and I've taken your suggestion to record rather than widen. Posted an interpretation note on #1762 documenting that the operative bar for .withProps() extraction in this sweep was repetition within a file (not the literal "≥2 props" reading), including the in-scope / deliberately-skipped / cross-file-only buckets and the ~30-instance gap. I flagged tightening the AGENTS.md wording as a maintainer-call follow-up since it edits the contract doc.

That leaves this PR with no outstanding code changes — all four review rounds' actionable findings are applied.

[cliffhall]

Full strict sweep applied (dba00b5)

Per maintainer direction, the AGENTS.md subcomponent rule is now applied strictly across the entire web client — every inline Mantine element with 2+ static (literal) props is a named per-file .withProps() constant, not just repeated-within-a-file patterns. An exhaustive 4-way audit found ~170 offenders across ~50 files (≈6× the earlier estimate); all are fixed. 77 files changed.

Also tightened the AGENTS.md wording in this PR (not deferred): the rule now states explicitly that it applies in all cases including single-use elements, and defines "static props" as literal-valued (dynamic props are passed at the call site, not counted).

Box handling

• ResizeHandle, ScreenStage → converted Box → named Flex.withProps() constants.
• App.tsx reauth-banner → Box → named Paper.withProps().
• ViewHeader display:grid container and AppRenderer iframe Box → left inline with justifying comments (no Mantine primitive fits).

Two constructs that can't use .withProps() (left inline, commented — same exemption class as Box)

• Accordion — a compound, multiple-discriminated generic; .withProps({ multiple: true, … }) loses its JSX call signature and fails to type (TS2604/2786/2322). Verified with tsc.
• data-* attributes (data-testid, data-autofocus) — not part of a component's typed props, so .withProps({ "data-testid": … }) is rejected (TS2353); passed at the call site instead.

(These two were the only type-level fallout from the mechanical extraction; the agents' vite-based unit tests don't typecheck, so I caught them in the project tsc -b pass and corrected them.)

Verification

npm run ci green end to end: 3472 unit tests, the per-file ≥90 coverage gate (98.58% overall), all smokes including the headless-browser boot (clean first render across the converted Boxes), and 456 Storybook play-tests.

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 6m 2s —— View job

---

Code review — PR #1771 (re-review after dba00b5f)

• Read the new commit's diff (dba00b5f — full strict sweep, 77 files)
• Verify the AGENTS.md wording change matches the applied practice
• Spot-check the mechanical extractions for prop/behavior drift
• Check the Box conversions and the documented exemptions (Accordion, data-*)
• Post review

---

Verdict

One thing I'd fix before merge, plus a few cleanups. The 179 extractions are overwhelmingly prop-for-prop faithful, and the AGENTS.md wording now matches the practice. But the sweep's Box → Flex conversions are the one non-mechanical class of change, and ScreenStage swaps the display model of the container that every screen renders inside — that one looks like a real layout regression, not a no-op. There's also a garbled comment and four orphaned JSDoc blocks.

I verified the extractions are structurally safe first: every one of the 179 .withProps() constants is declared at module scope (I checked for indented declarations — zero), so none creates a fresh component type per render. Only two classNames appear in added code (resize-handle, header-anim), and neither collides with a call-site className.

---

1. ScreenStage: Box → Flex changes how every screen is sized — clients/web/src/components/elements/ScreenStage/ScreenStage.tsx:11-16

const StageLayer = Flex.withProps({
  pos: "absolute", top: 0, left: 0, right: 0,
});

Box rendered a plain div (display: block); Flex renders display: flex; flex-direction: row. StageLayer itself is still full-width (absolute with both left and right set + width: auto fills the containing block — shrink-to-fit doesn't apply). The problem is its child:

• Before: the child was a block-level box in a block container → width: auto → fills 100%.
• After: the child is a flex item in a row container → flex: 0 1 auto with flex-grow: 0 → width is content-based, and only shrinks (never grows) to the container.

Every screen mounts through this. ToolsScreen, ServerListScreen, ConsoleScreen, … all root at ScreenLayout = Flex.withProps({ variant: "screen", h: "calc(…)", … }) — none sets w, and the screen variant (src/theme/Flex.ts) only adds overflow: hidden. So each screen now sizes to its own max-content instead of the viewport.

ServerListScreen is the sharpest case, because its grid contributes zero intrinsic width:

const ServerGrid = SimpleGrid.withProps({ type: "container", … });  // ServerListScreen.tsx:170

type="container" applies container-type: inline-size → contain: inline-size, which makes the element's inline size compute without regard to its contents. So the grid's max-content contribution is 0, and ScreenLayout's content-based width collapses to roughly the header row (Servers title + the Export/Add/toggle controls) — a few hundred px on a wide viewport, where it previously filled it.

Neither the test suite nor Storybook can catch this: happy-dom does no layout, and the stories render the screens directly rather than through ScreenStage. The headless-browser smoke asserts the "Add Servers" control renders, not its width. So a green npm run ci is consistent with the regression.

Minimal faithful fix — make it a column flex. In a column flex the cross axis is the width and align-items: stretch (Mantine's default) makes the single child fill it, while the main axis (height) stays content-sized. That reproduces block layout exactly:

const StageLayer = Flex.withProps({
  direction: "column",
  pos: "absolute", top: 0, left: 0, right: 0,
});

(w: "100%" also works; direction: "column" additionally avoids the row-flex align-items: stretch forcing the child to the container's height in the fill case.) Worth an actual browser check on the Servers tab at a wide viewport either way.

I checked the sibling conversion and it's fine: ResizeHandle's Flex is childless with an explicit width: 6px from .resize-handle (App.css:590-597), so its display model is inert.

Fix this →

---

2. Garbled comment — two notes spliced mid-sentence — clients/web/src/components/groups/ResourceControls/ResourceControls.tsx:39-45

// Full-height, multi-open accordion for the resource sections.
// `transitionDuration: 0` disables Mantine's panel height animation: its
// Collapse drives open/close via an inline `height` that briefly jumps the panel
// to its full natural height, fighting the flex sizing (the panels are
// Accordion is a compound, `multiple`-discriminated generic component, so
// `.withProps({ multiple: true, ... })` loses its call signature and can't type
// — it stays inline (same tooling limit as Box).

export interface ResourceControlsProps {

The sentence breaks at "(the panels are" and the Accordion-exemption note is pasted over the remainder — clearly the residue of an extracted-then-reverted constant. It also now sits directly above export interface ResourceControlsProps, so IDE hover on the interface shows the Accordion note. (The transitionDuration rationale itself survives, correctly abbreviated, at the call site — :250-252.) Deleting the orphan block or restoring the two as separate comments both work. [Fix this →](https://claude.ai/code?q=In%20clients%2Fweb%2Fsrc%2Fcomponents%2Fgroups%2FResourceControls%2FResourceControls.tsx%20on%20branch%20v2%2Ffix-1762-agents-md-sweep%2C%20the%20comment%20block%20at%20lines%2039-45%20is%20garbled%20-%20a%20sentence%20about%20transitionDuration%20breaks%20mid-phrase%20at%20'(the%20panels%20are'%20and%20the%20Accordion-exemption%20note%20is%20spliced%20over%20the%20rest%2C%20and%20the%20whole%20block%20now%20dangles%20above%20export%20interface%20ResourceControlsProps.%20The%20transitionDuration%20rationale%20already%20lives%20at%20the%20call%20site.%20Clean%20this%20up%20so%20only%20a%20coherent%20Accordion-exemption%20note%20remains%20(or%20delete%20the%20block).%20Then%20run%20npm%20run%20validate%3Aweb.&repo=modelcontextprotocol/inspector)

---

3. Four exported components lost their JSDoc to the new constant

Inserting the .withProps() constant between a component's doc comment and the component re-targets the doc:

File	Doc now attached to	Doc obviously describes
ExpandToggle.tsx:18-29	ExpandActionIcon	"…aria-expanded exposes the disclosure state and ariaLabel can distinguish sibling toggles"
PinToggle.tsx:10-19	PinActionIcon	"…the aria-label stays 'Pin'/'Unpin'"
MonitoringToggle.tsx:14-27	MonitoringActionIcon	"…the caller only mounts it when the sidebar is available"
ReplayButton.tsx:9-19	ReplayActionIcon	"Icon form of the 'Replay' action, used in the compact (column) ProtocolEntry layout"

Hovering the exported component in an editor now shows nothing; hovering the styling constant shows the component's docs. The sweep got this right everywhere else (McpErrorBadge, FilterToggleButton, EmbeddableScrollArea, SubscriptionStreamBadge, … all place the constant above the doc block) — these four are the outliers. Moving the constant above the /** fixes all four. Fix this →

---

4. Minor: Box → Paper adds a border-radius to the full-bleed re-auth bar — clients/web/src/App.tsx:398-405

Paper's root carries border-radius: var(--paper-radius), defaulting to the theme's defaultRadius: "md" (src/theme/theme.ts:172) — the previous Box had none. On a pos="sticky" full-width bar that means rounded bottom corners under the box-shadow. Small, but a visible delta rather than a refactor.

The shadow is safe: .reauth-banner-bar { box-shadow: var(--mantine-shadow-sm) } (App.css:578-581) and Paper's box-shadow: var(--paper-shadow) are both single-class specificity, and App.css is imported after @mantine/core/styles.css (main.tsx:5-7), so the class wins. bg was already pinned to --mantine-color-body, which is Paper's default anyway. Adding radius: 0 to the constant restores the old geometry.

5. Nits

• ServerConfigModal.tsx:68-75 — IdTextInput and RequiredTextInput are byte-identical (required: true, rightSectionPointerEvents: "auto"). The ID field's only distinguishing props (label, description, placeholder, data-autofocus) are all passed at the call site, so one constant covers both.
• ServerConfigModal.tsx:394-409 — the "Working directory" TextInput still carries inline placeholder="(inherit)" + rightSectionPointerEvents="auto" (two static props) while all five of its siblings in the same file were extracted. ClearableTextInput — the exact single-prop constant this needs — already exists in ServerSettingsForm and ClientSettingsForm.

Re-verified clean

• AGENTS.md wording — the new rule text ("static prop … a single-use element with two or more static props must still be extracted") matches what the commit actually did, and the static/dynamic split it defines is the one applied throughout (value/on*/children/key consistently at the call site). Tightening the contract in the same PR rather than deferring is the right call.
• Component identity — all 179 constants at module scope; no per-render component types, so no remount/focus-loss class of bug.
• Prop fidelity, spot-checked across all 77 files — ControlsCluster genuinely equals the <Group gap="sm" wrap="nowrap"> it replaced in NetworkEntry's wide layout (:87-96); SectionLabel c="red", DimmedNote aria-live="polite", SessionBadge color="green", ScopeBadge color={…} all override/extend correctly (call-site props spread last). No call site passes an explicit undefined for a prop the constant bakes, which is the one way withProps can silently drop a default.
• className handling — only resize-handle and header-anim are baked, neither collides, and HeaderStackCell's styles.root (gridArea/placeSelf) stays disjoint from the keyframes' opacity/transform, so the crossfade is unaffected (as established last round).
• Documented exemptions — Accordion (compound + multiple-discriminated generic) and data-* attributes (not in the typed props object, so excess-property-checked out of a withProps literal) are both genuine TS limits, correctly left inline with comments. ViewHeader's display="grid" Box and AppRenderer's component="iframe" Box are likewise correctly exempted — no Mantine primitive is a grid, and the iframe is a native element.
• Logic extractions — ToolsScreen.handleSelectTool keeps /* v8 ignore next */ immediately above if (tool); the formValues → nextFormValues rename is still required to avoid shadowing ui.formValues.
• PlainStringKeys<FormState> / App.tsx cast / .grid-align-start / createRemoteLogger — unchanged since the last round and still correct.

Nothing found on

any usage, config-level lint suppressions, dead CSS or dead imports, coverage-ignore drift, new inline style={{…}} props, or raw hex/rgba() literals.

_{Caveat: this checkout has no node_modules, so I did not run the suite or a browser — finding 1 is reasoned from the CSS box model plus the files in the branch, and is exactly the class a headless first-render smoke can't see. Please confirm it visually before merge.}

--- · branch v2/fix-1762-agents-md-sweep

[cliffhall]

All five findings addressed in 5e175b3. Thank you for the box-model analysis on finding 1 — that was a real regression a first-render smoke can't see.

1. ScreenStage layout regression — Fixed and visually verified. Added direction: "column" to StageLayer so the width sits on the cross axis, where Mantine's default align-items: stretch makes the single child fill it (reproducing the old block behavior). I ran the dev server and checked the Servers tab at a wide viewport: the grid + surface panel span the full width again, matching the pre-sweep baseline. Confirmed ResizeHandle's Flex is inert (childless, fixed width: 6px), so it needed no change. Left a load-bearing comment on the direction prop.

2. Garbled ResourceControls comment — Removed the spliced orphan block; the transitionDuration rationale stays at the call site, and the Accordion-exemption note now sits as a coherent comment directly above the inline <Accordion>.

3. Four orphaned JSDoc blocks — Moved the .withProps() constant above the doc in ExpandToggle, PinToggle, MonitoringToggle, and ReplayButton, so each doc documents its exported component again (matching how McpErrorBadge/FilterToggleButton do it).

4. Paper border-radius on the reauth bar — Added radius: 0 to ReAuthBannerBar so the full-bleed sticky bar keeps square corners like the Box it replaced.

5. ServerConfigModal nits — Collapsed the now-byte-identical IdTextInput into RequiredTextInput (the ID field passes data-autofocus at the call site); extracted the "Working directory" field via a new ClearableTextInput constant so it no longer carries 2 inline static props.

npm run ci green end to end, plus the manual wide-viewport check of the Servers screen.

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 5m 48s —— View job

---

Code review — PR #1771 (re-review after 5e175b37)

• Read the latest commit's diff (5e175b37 — review fixes)
• Verify the five prior findings are correctly closed
• Fresh pass over the full sweep for anything not yet covered
• Post review

---

Verdict

Approve-equivalent — nothing blocking. All five findings from the last round are correctly closed, and I re-derived the ScreenStage fix from the box model rather than taking it on the commit message. Three residual items below, all in the "a sweep PR should probably own this" category rather than defects.

Verified: the five fixes

• ScreenStage direction: "column" (ScreenStage.tsx:16-22) — this is the right fix, and I checked both call paths. In a column flex the cross axis is horizontal, so Mantine's default align-items: stretch gives the single child width: 100% — exactly what the old block child had. The main axis stays content-sized (flex-basis: auto, flex-grow: 0), matching height: auto. I also checked the fill path (MonitoringScreen.tsx:67, bottom: 0 → definite container height): a column flex item's min-height: auto resolves to its content-based minimum, so it can't shrink below content the way flex-shrink: 1 alone would suggest — the overflow behavior matches the old block layout too. ResizeHandle's Flex is genuinely inert (childless; .resize-handle sets flex: 0 0 auto; width: 6px, App.css:590-597).
• ResourceControls comment — the spliced block is gone and the Accordion note now sits directly above the <Accordion> (:237-239); the transitionDuration rationale survives at :247-248. Coherent.
• Four JSDoc blocks — I re-scanned every touched .tsx for a */ immediately followed by a const X = Y.withProps( and got zero hits, so all four are fixed and none were introduced elsewhere. MonitoringToggle correctly split the size={36} sentence out of the component doc into a note on the constant.
• radius: 0 on ReAuthBannerBar — restores the Box geometry. .reauth-banner-bar (App.css:578-581) only sets z-index + box-shadow, both unaffected.
• ServerConfigModal — IdTextInput/RequiredTextInput collapse is byte-equivalent (the ID field's data-autofocus/label/description/placeholder were already call-site props), and ClearableTextInput matches the same-named constant in ServerSettingsForm/ClientSettingsForm. ArgsTextarea/EnvTextarea/RequiredTextInput/ClearableTextInput are all still referenced — I checked every declared constant across all 80 files for dead declarations and found none.

---

1. The strict sweep left a handful of offenders behind — one in a file it touched

I scripted the rule the PR just codified (JSX-tag scan → count literal-valued styling/layout/behavior props, excluding value/on*/children/key/ref/style/component/error/*Section) over all 365 non-test/non-story .tsx in clients/web/src. After discarding the documented exemptions (Box, Accordion) and comment-text false positives, these survive:

Location	Element	Static props
clients/web/src/components/elements/EmbeddableScrollArea/EmbeddableScrollArea.tsx:59	<Stack>	flex={1} mih={0} gap={0}
clients/web/src/components/groups/ToolResultPanel/ToolCallErrorPanel.tsx:73	<Title>	order={3} size="h4"
clients/web/src/components/groups/ToolResultPanel/ToolCallErrorPanel.tsx:77	<Alert>	color="red" variant="light"
clients/web/src/components/groups/SortableServerCard/SortableServerCard.tsx:33	<ActionIcon>	variant="subtle" color="gray" size="md" className
clients/web/src/components/elements/ContentViewer/CsvTable.tsx:52	<Table>	striped highlightOnHover withTableBorder withColumnBorders
clients/web/src/components/elements/ContentViewer/BinaryNotice.tsx:18	<Code>	block p={36}

The EmbeddableScrollArea one is the notable one — this PR edited that file, extracting StreamScrollArea three lines below while leaving the wrapper <Stack> inline. The other five are in files the sweep didn't open, and two of them are near-misses by adjacency: ToolCallErrorPanel.tsx sits in the same folder as the swept ToolResultPanel.tsx, and its <Title order={3} size="h4"> is the identical pattern the sweep extracted as PanelTitle (ServerListScreen) and ToolsTitle (ToolControls); SortableServerCard.tsx sits beside the swept ServerCard.tsx.

Separately, there's a boundary worth stating out loud rather than leaving to the next auditor: ~20 <Checkbox label="…" description="…"> / <Select label="…" description="…" allowDeselect={false}> in ServerSettingsForm/ClientSettingsForm are literal-valued but are content, not "styling/layout/behavior" — so excluding them is consistent with the AGENTS.md text as written. The sweep did bake literal label/placeholder elsewhere (ExcludedDivider's label="Excluded (SEP-2243)", SearchInput's placeholder="Search tools..."), so the line is real but implicit. Either is defensible; it just isn't written down.

Fix this →

2. The Accordion-exemption comment still dangles in three other files

ResourceControls got this fixed; the same note is stranded in the module-scope constant block of three more files, nowhere near the <Accordion> it explains:

• clients/web/src/components/groups/ClientSettingsForm/ClientSettingsForm.tsx:60-62 — sits between ErrorAlert and ClearableTextInput, ~115 lines above the <Accordion> at :176, and immediately above an unrelated /** Human-readable one-liner for an RFC 7591 DCR rejection. */.
• clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx:140-142 — between isModernLogLevelValue() and ClearableTextInput; the <Accordion> is at :392.
• clients/web/src/components/groups/ImportServerJsonPanel/ImportServerJsonPanel.tsx:97-99 — between ChooseFileButton and FileContentsTextarea; the <Accordion> is at :159.

Reading any of these in place, the note appears to explain the constant below it. Moving each to a JSX comment above its <Accordion> — exactly what ResourceControls.tsx:237-239 now does — makes all four consistent. Fix this →

3. AGENTS.md codifies the rule but not the two exemptions the sweep discovered

The wording change is good and matches the practice. But the sweep found two constructs that can't satisfy it — compound multiple-discriminated generics (Accordion) and data-* attributes (not in the typed props object, so excess-property-checked out of a withProps literal) — and documented them only in ~6 scattered code comments. AGENTS.md's subcomponent section lists the Box exemption explicitly, so a reader takes that list as exhaustive and the next audit re-derives these from scratch (as this one did). One sentence next to the Box bullet would close it.

---

Re-verified clean

• Component identity — all 184 .withProps() constants are declared at module scope (zero indented declarations), so no per-render component types and no remount/focus-loss class of bug.
• className bakes — only three in added code (reauth-banner-bar, resize-handle, header-anim); none collides with a call-site className, and HeaderStackCell's styles.root (gridArea/placeSelf) stays disjoint from the keyframes' opacity/transform, so the crossfade is unaffected.
• Prop fidelity — spot-checked NetworkEntry, ToolControls, ClientSettingsForm, ExperimentalFeaturesPanel, ServerCard, ServerListScreen, EmbeddableScrollArea: all prop-for-prop. SentinelTooltip label={…}, SessionBadge color="green"|"yellow", ControlsCluster reuse in both NetworkEntry layouts, ClearableTextInput across three forms — every override lands correctly (call-site props spread last). EmbeddableScrollArea's hoisted viewportProps: { tabIndex: 0 } is a small bonus: stable object identity instead of a fresh literal per render.
• Box exemptions — ViewHeader's display="grid" container (no Mantine primitive is a grid; converting would break the shared-cell overlay) and AppRenderer's component="iframe" are both genuine and now commented. HtmlFrame.tsx:28 / PdfFrame.tsx:33 are the same iframe pattern, uncommented, but equally exempt.
• PlainStringKeys<FormState> / App.tsx single cast / .grid-align-start removal / createRemoteLogger @ts-expect-error / ToolsScreen.handleSelectTool — unchanged since prior rounds and still correct.

Nothing found on

any usage, config-level lint suppressions, dead constants or imports, coverage-ignore drift, new inline style={{…}} props, or raw hex/rgba() literals.

_{Caveat: this checkout has no node_modules, so I did not run the suite or a browser — taking your npm run ci result and wide-viewport check at face value. The layout, CSS, and scope analysis above was run against the files in the branch.}

--- · branch v2/fix-1762-agents-md-sweep