feat(web): add compact file chip paths - #8825

💭 I'm examining the PR for UI consistency, environment routing, and settings panel patterns—specifically checking whether the new SettingsRow in SettingsPanels.tsx includes a title prop or relies on searchableSetting to supply the label, comparing it against how other SettingsRow usages are structured. Also checking the ChatMarkdown component's use of the file-link-paths hook with cwd as workspace root, and whether there's a separate mobile renderer that stays basename-only per the docs. I want to look at the actual source files to confirm these details.

1. browse_code — apps/web/src/filePathDisplay.ts

2. browse_code — apps/web/src/components/settings/SettingsPanels.tsx

💭 Now I want to check ChatMarkdown for how file chips are rendered, whether that label is shared with other renderers, and whether fileLinkMeta.targetPath and cwd resolve to the correct workspace root given environment scoping rules.

3. git_tools — targetPath|parentSuffix|fileLinkMeta

💭 I'm checking whether the tooltip and chip label truncation still work fine now that compact paths are longer, and I want to look at the MarkdownFileLink render code around lines 1700-1775 to see if there's a max-width truncation class affecting layout. I'm also considering whether a separate mobile chip renderer exists elsewhere that could be inconsistent, though the docs suggest mobile intentionally stays basename-only.

4. browse_code — apps/web/src/components/ChatMarkdown.tsx

💭 I want to check FileTagChipContent and the chip class name to see how truncation and max-width are handled.

5. git_tools — CHAT_FILE_TAG_CHIP_CLASS_NAME|function FileTagChipContent

6. browse_code — apps/web/src/components/chat/FileTagChip.tsx

7. browse_code — apps/web/src/components/composerInlineChip.ts

💭 I'm noticing that the chip's truncate behavior could clip the file name when compact paths are long, since the prefix shows but the basename gets cut off under constrained width. It feels like a plausible but soft UX concern rather than a definitive bug, since truncation was already pre-existing behavior. Let me check other file chip renderers in apps/web that share the same short-label construction logic, searching for parentSuffix/basename patterns using " · ", to see if this preference creates inconsistency across different surfaces of the product.

8. git_tools — L${|labelParts|·

9. git_tools — formatWorkspaceRelativePath|formatCompactFilePath|formatFileChipLabel

💭 I'm checking whether the cwd prop already handles environment scoping, since it's reused from resolveMarkdownFileLinkMeta, so no new fallback is needed. The useShowFileLinkPaths setting is global rather than environment-scoped, which seems fine, but I want to verify whether ChatMarkdown is also used on mobile and how that renderer handles this.

10. browse_code — In apps/web/src, which components render file link chips for chat markdown besides ChatMarkdown.tsx? Is there a mobile markdown renderer (e.g. MobileChatMarkdown or similar) that renders file chips with basename-only labels? List file paths and how they compute chip labels.

💭 I'm considering that PullRequestMarkdown reuses ChatMarkdown across environments, so the cwd prop might come from the wrong environment in PR panels—this is a pre-existing issue since displayPath already relied on cwd, but enabling showFileLinkPaths could surface it by producing an incorrect relative path claim, though it's not something this change introduces. Shifting to settings, I want to check whether they added a bespoke useShowFileLinkPaths hook instead of using the existing useClientSettings with a selector—if that hook already supports selectors, this new one would duplicate an existing contract rather than reuse it, so I should look at useSettings.ts to confirm.

11. browse_code — apps/web/src/hooks/useSettings.ts

12. browse_code — apps/web/src/hooks/useSettings.ts

💭 This existing pattern matches how the legacy sidebar setting works, so adding a similar hook with useSyncExternalStore is consistent and not really a concern, including the server-side fallback. I'm now checking whether there's a default value mismatch related to this setting. I check that the useMemo dependency for markdown components correctly includes the new setting. I also verify that other file chip label computations, like the parent suffix disambiguation, remain harmless even when the new label mode is active, and that server-side rendering paths are unaffected since the fallback snapshot works fine there too. Finally I look at whether the diff introduces any new CSS or test setup files. I'm now examining that hand-rolled DOM harness for tests, wondering whether the repo already has an established DOM testing environment like jsdom or happy-dom that this duplicates, since introducing a custom 200-line fake DOM instead of reusing an existing contract would be worth flagging.

13. browse_code — How do apps/web tests render React components? Is there an existing DOM environment (jsdom, happy-dom) configured for vite-plus tests, or an existing test helper for mounting React components (e.g. @testing-library/react, renderHook, a shared test harness under apps/web/src/test)? Show vite/vitest config test environment settings for apps/web and examples of existing tests that mount components with react-dom/client.

💭 I'm noting that reactDomHarness.ts is a new test harness alongside the existing reactHookHarness.ts, but that's likely outside the scope of the UI consistency check since it's test infrastructure, not shared UI components. I'm weighing whether the guidance about not requiring tests for trivial visual migrations versus requiring them when primitive composition changes behavior applies here. Now I'm looking for a genuine UI regression in the diff. One candidate is the chip label truncation when showFileLinkPaths is enabled — truncating a long file path from the end could hide the filename, the most meaningful part, which seems like a real readability concern worth flagging even though it's opt-in. Another candidate is an aria-label issue on a non-primary-action button that I want to examine more closely. I'm also considering whether the environment routing rule applies here — checking how the workspace root path reaches the markdown renderer and whether the compact path formatting properly accounts for POSIX vs Windows display styles, plus whether the home-directory detection heuristics are just guesses rather than reliable signals. I want to verify the new settings entry has a proper title and keywords by checking how other items in the settings search file are structured for consistency.

14. browse_code — apps/web/src/components/settings/settingsSearch.ts

💭 The search order lines up correctly with the panel layout. I'm weighing whether the new setting's placement in General versus Appearance is a real issue, but it seems more like a subjective aesthetic call rather than something worth flagging strongly. Now I want to check whether showFileLinkPaths was properly added everywhere it needs to be — the schema, patch logic, and any exhaustive lists of client setting keys used for syncing to mobile/desktop or import/export. If such a list exists in the contracts package and wasn't updated, the setting could fail to persist or sync properly, so I'm going to check DEFAULT_CLIENT_SETTINGS and related key arrays there.

15. git_tools — legacySidebarEnabled

💭 I'm checking whether the desktop settings test file uses a strict ClientSettings type that would break if a new required field is added, though desktop is technically out of scope here — but since withDecodingDefault makes the encoded type optional, the decoded default should keep things safe.

16. browse_code — apps/desktop/src/settings/DesktopClientSettings.test.ts

💭 I'm noticing that clientSettings literal is missing showFileLinkPaths, which raises the question of whether withDecodingDefault makes the decoded type required while keeping the encoded side optional—I need to check how ClientSettings' type is derived and whether DEFAULT_CLIENT_SETTINGS lets other places skip full literals. But this file is in apps/desktop, which falls outside the include patterns for this check's scope. Since I can only take actions on in-scope files, I should verify whether this is actually a real type error before deciding whether it's even worth mentioning as context.

17. git_tools — export type ClientSettings|DEFAULT_CLIENT_SETTINGS =|withDecodingDefault

💭 I'm checking whether showFileLinkPaths is required on the ClientSettings type, since the desktop test literal omits it—if withDecodingDefault only relaxes the encoded/optional side but keeps the decoded Type required, that literal would fail typecheck. Since the desktop test's object literal appears exhaustive across every current settings key, that supports the Type-required interpretation, meaning this PR likely breaks apps/desktop's typecheck. Now I want to check apps/web too for any similar exhaustive ClientSettings literal that could break in-scope.

18. git_tools — wordWrap: (true|false)

19. git_tools — DEFAULT_UNIFIED_SETTINGS

💭 I'm checking a test file's settings object to see if it's typed exhaustively against ClientSettings—if it's missing showFileLinkPaths, that could break the web typecheck.

20. browse_code — apps/web/src/clientPersistenceStorage.test.ts

💭 The web spread looks fine, though the desktop test literal seems out of scope but still triggers a real typecheck break. I'm checking whether Effect v4's Schema.withDecodingDefault makes fields optional on the constructor side but required on the Type side, and looking at what fields like appearanceContrast appear in that desktop test. Better evidence would come from git history — checking whether DesktopClientSettings.test.ts was updated when previous client settings like showSkillsInSlashMenu or browserAutoShowFloatingPreview were added, so let me search with pickaxe.

21. git_tools — apps/desktop/src/settings/DesktopClientSettings.test.ts

22. git_tools

💭 Looking at prior commits that added client settings, they consistently also updated DesktopClientSettings.test.ts, confirming this is a required pattern. This PR appears to miss adding showFileLinkPaths to that test file, which would break the typecheck. But that file is outside my scope for this review (apps/desktop isn't in my include patterns), so I shouldn't post a comment directly on it. I could mention it as context in the summary without treating it as a blocking in-scope finding, but first I want to double-check by looking at the actual diff of commit 9da0fab to confirm the test literal was indeed updated there.

23. git_tools — 9da0fab

💭 This does break desktop typecheck, but it's technically out-of-scope for inline comments given the include pattern restrictions. I'll note it as context in the details section while keeping pass/fail based on in-scope findings, then keep digging for more issues. Looking at ChatMarkdown, I'm checking whether the compact-path label preserves tooltip behavior and whether the line/column format is consistent with the copy-path behavior — seems fine so far. I want to check if the repo has an existing path-truncation primitive for handling long paths with start/middle ellipsis, so I'm searching for existing path-display components with that pattern.

24. git_tools — direction:rtl|rtl|truncate-start|ellipsis-start

25. browse_code — apps/web/src/components/StartTruncatedPath.tsx

💭 There's already a shared component, StartTruncatedPath, used for showing paths that truncate at the start to preserve the filename. But the new file chip's compact-path mode truncates at the end instead, hiding the filename — the opposite of the established pattern. I want to check where StartTruncatedPath is used elsewhere to ground this observation.

26. git_tools — StartTruncatedPath

💭 With only one existing consumer plus this new use, the pattern is weakly established, so I'm weighing whether that's enough to justify a named primitive versus flagging this as a regression risk instead—since end-truncating a full path would hide the filename, unlike the old label where truncation was harmless because it started with the basename. I'm now checking whether truncation would actually trigger given the chip's max-width constraint within its container. Given the container widths at play, truncation seems unlikely in most layouts but plausible in narrower panels, so this feels like a defensible but not certain finding, with a fix available by reusing the start-truncation treatment for the compact-path label. Still cautious about false positives, I want to weigh other candidates first, particularly the environment-routing rule and how the chip renderer's cwd prop flows from call sites like PullRequestMarkdown. The bigger concern is that formatCompactFilePath guesses the home directory using regex heuristics rather than pulling from the environment's actual server config, which conflicts with the rule that capability gating, action dispatch, and labels must all read from the same environment config. Since ChatMarkdown already derives other labels like the file-manager and editor menu labels from environment config, I want to check whether homeDirectory is available there too, which would make the heuristic redundant and potentially wrong.

27. browse_code — apps/web/src/components/ChatMarkdown.tsx

💭 I'm checking whether serverConfig already exposes the home directory through environment.platform, since if it does, guessing paths like /root or /home/x for the "~/" heuristic would be redundant and risks producing an incorrect label when the guess is wrong.

28. browse_code — Does the server config exposed to the web client (serverEnvironment.configValueAtom / ServerConfig contract in packages/contracts) include the environment's home directory and platform info (e.g. environment.platform.os, homeDirectory, homePath)? Show the relevant schema fields and any existing web code that shortens absolute paths using the environment's home directory (e.g. replacing home with ~).

💭 The home directory guess seems intentional and well-tested as a display heuristic rather than an environment routing issue, since it's derived from the thread's own cwd. I'm now checking other surfaces where file chips might get truncated, like narrow display contexts in the timeline components. I'm also weighing whether the useShowFileLinkPaths hook creates a hydration mismatch — its server snapshot defaults to false while the live snapshot could be true, meaning users with the setting enabled might briefly see basename chips flash to compact paths once localStorage resolves. I want to check whether similar settings like wordWrap are gated behind hydration checks to see if this flash is an existing accepted pattern or a genuine inconsistency worth flagging. Given that the tooltip still reveals the full path on hover, I'm now leaning toward treating truncation as acceptable since it matches the existing chip contract, though I still want to consider how much wider these compact-path chips could get inside a narrow panel and whether that causes real layout issues. Checking other rendered chip surfaces — composer file mentions, terminal context chips, diff headers, review annotations — none need to honor this new preference since it's explicitly scoped to chat file chips only, so that's consistent with the intended design. Verifying placement: "File chip paths" sits correctly under General between Time format and Hide whitespace changes, and it's grouped into the same changed-labels list as word wrap and other general settings, so the ordering checks out. I'm also confirming the dependency array and reset-defaults were updated to include the new setting, and looking at whether MarkdownFileLink's memo comparator properly accounts for the label prop — it does. Now I'm checking whether the file link parent suffix computation becomes unnecessary work when showFileLinkPaths is enabled, though this isn't really an issue worth flagging, and looking at how inline code links resolve their metadata. I'm tracing whether targetPath could remain relative rather than absolute — when cwd or workspaceRoot is undefined, the display path falls back to whatever was authored, so compact mode could end up showing a raw relative path like "src/main.ts" as-is. Now I'm checking that splitPathAndPosition correctly handles Windows drive paths like "C:/Users/mike/project/src/main.ts", making sure the colon after the drive letter isn't misparsed as a position separator, since existing tests seem to cover this case. Also thinking through WSL-style backslash paths with trailing line/column markers like :12:3, and whether normalizeAbsolutePath and hasDotPathSegment interact correctly when applied before versus after path normalization — this seems fine since normalizePathSeparators runs internally. Overall, I'm leaning toward this passing review, with the main real issue being the missing description I noted earlier. I check the new reactDomHarness.ts test utility file — it's shared across two test files but isn't a UI component, so it doesn't count as a locally reconstructed primitive violation. I also glance at compact path rendering with chip icons and long paths to see if there's a regression there. Checking other file-label formatting spots like the review annotation headers in MessagesTimeline, which use a different pre-existing formatting approach — that's not a new inconsistency introduced here. I'm leaning toward there being no strong in-scope finding, but I want to revisit the desktop typecheck issue once more, specifically whether ClientSettings type could have optional fields for withDecodingDefault. Given the check's scope is explicitly limited to files matching include/exclude patterns, reporting a genuine build break on an out-of-scope file feels wrong even though it's a real issue — likely another check catches it. I'll settle on noting it neutrally as out-of-scope context in the details rather than raising it as an inline comment. Now I'm working through the "defaults to failure" instruction, which conflicts with the JSON schema requirement — I'll interpret "All clear" as the intended content within the required JSON structure rather than literal free text, setting a success state with an "All clear"-style title when there are no findings. I'm also spot-checking a few more UI details for consistency: the ChatMarkdown compact-mode label format, the Switch import usage, the documented behavior that compact-path applies only on web/desktop while mobile stays basename-only, and whether SettingsRow sits correctly inside GeneralSettingsPanel with the right search route. Weighing whether long labels could get truncated in narrow chip containers, but since there's a tooltip mitigation and this is opt-in behavior, I don't think it's worth flagging. I've also confirmed useShowFileLinkPaths doesn't interfere with the static-markup rendering path in tests, so I'm settling on a pass with "All clear."