AGENTS.md@packages/client/src/lib/nav git:20261022.4339930A

Immutable. This exact content never changes and is served at /api/v1/blob/f7559df6d4c3fdc7.

# DOX — packages/client/src/lib/nav

Files in this directory. One row per source file. See change: fold-oversized-agents-directories.

| File | Purpose |
|------|---------|
| `back-target.ts` | Pure `computeBackTarget(route): string \| null` — maps route to parent route one shell depth up. → see `back-target.ts.AGENTS.md` |
| `document-title.ts` | Exports `buildDocumentTitle(session, folderCwd?)` — derives `<projectDir>` from `cwd` last segment, composes `"<name> (<dir>) — PI Dashboard"` title. Falls back to folder cwd or `"PI Dashboard"`. |
| `history-back.ts` | Exports `goBack(navigate, currentRoute, tracker)` — depth-aware mobile/overlay back action. → see `history-back.ts.AGENTS.md` |
| `move-tracker.ts` | In-flight package-move state tracker, keyed by `moveId`. Exports `MovePhase`, `MoveState`, `moveTracker`… → see `move-tracker.ts.AGENTS.md` |
| `nav-intent.ts` | Client half of signed navigation intents. Exports `mintNavIntent(view)` (POST `/api/nav-intent`, null on failure / 2 s), `withNavIntent(url, ni)`, `useNavIntentVerdict(ni, view)` → `pending|operator|agent` (verify ≤ 2 s; fixed per mount). See change: harden-client-sinks. |
| `nav-tracker.ts` | In-app depth-tagged nav stack. `Array<{url, depth}>` via `routeDepth`. → see `nav-tracker.ts.AGENTS.md` |
| `overlay-background.ts` | Route-backed overlay underlay + dismissal target. Exports `captureBackground`, `clearBackground`, `peekBackground`, `resolveBackground`, `recordLauncher`, `resolveDismissTarget`, `isOverlayRoute`, `splitLocation`. Launchers = STACK: overlay→other-surface pushes `from`; arriving on top launcher's surface pops (return ≠ new launch — fixes settings⇄tunnel-setup flip loop). Base-route landing clears stack. See change: add-route-backed-overlay-dialogs, fix-overlay-dismiss-flip-loop. `openspec/archive/:entry` (5 segments) is not an overlay route. See change: resolve-archived-attached-proposal. `isPluginDialog(p)` (only `"dialog"` lifted) + `shouldCaptureBackground(p)` (false for `"dialog"`/`"content"`), type `PluginOverlayPresentation`. See change: add-plugin-app-host. |
| `route-builders.ts` | URL builders for shell overlay routes: `buildOpenSpecPreviewUrl`, `buildOpenSpecArchiveUrl`,… → see `route-builders.ts.AGENTS.md` |
| `safe-navigation.tsx` | Client navigation chokepoints: re-exports SDK `SafeLink`, `openExternalUrl`, `assignLocation`; `useSafeNavigation()` = SDK hook + `useTrackedNavigate` for internal paths + split-viewer routing for loopback. Allowlisted raw-sink module of `check-client-sinks.mjs`. See change: harden-client-sinks. |
| `useArchiveRoute.ts` | `useArchiveRoute()` matches `/folder/:cwd/openspec/archive[/:entry[/:artifact]]` → `{cwd, entry?, artifact?}`; shared by App + ShellContent. See change: resolve-archived-attached-proposal. |
| `useTrackedNavigate.ts` | `useTrackedNavigate()` push-navigate that records into the nav tracker so Back returns to the launching view. See change: resolve-archived-attached-proposal. |
| `view-route.ts` | `/view` route helpers: `viewTargetToEditorPath(ViewTarget)` maps a view target to an editor-pane path. See change: open-view-command-in-editor-pane, fold-oversized-agents-directories. |