AGENTS.md@packages/client/src/lib git:20261020.d2e6cf7A

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

# DOX — packages/client/src/lib

Files in this directory. One row per source file.

| File | Purpose |
|------|---------|
| `__tests__/editor-pane-state.handler-mode.test.ts` | E11 `handlerMode` hydration (non-string dropped per tab, unknown claim kept) + `setHandlerMode` reducer. Per-file in-memory `localStorage`. See change: add-editor-pane-file-handlers. |
| `__tests__/sha1.test.ts` | Fallback + subtle parity vs node sha1 (block boundaries, binary). See change: add-editor-pane-file-handlers. |
| `__tests__/theme-body-text-contrast.test.ts` | Contrast floor over all 18 palettes: `--text-secondary`/`--text-tertiary` AA, hierarchy, Base `index.css` parity, hue/sat preservation, ring 3:1, card-fill AA. Accent-text ramp: 108 `--accent-<hue>-text` AA on surface/tertiary/primary/card fill, fidelity vs live `--accent-<hue>`, passing source adopted unchanged (28), Base parity via no-fallback `tokenIn`, CIE76 ΔE ≥ 8 with `KNOWN_INDISTINGUISHABLE = ["solarized:dark"]`; helper fixtures prove each check rejects. See changes: stop-discarding-known-session-state, remediate-accent-text-contrast. |
| `__tests__/aligned-surfaces-no-literals.test.ts` | AST scan (string/template literals, comments skipped) of the aligned surfaces: E3 no palette class / hex / `rgba(`; E5 `--text-muted` only as `disabled:` or on `aria-hidden`. Surfaces = the action surfaces, the shared recipes (`client-utils` StatusPill + Dialog, runtime `settings-fields.tsx`) and their migrated consumers (menu panel, provider/plugin pills, services + vault parts), the board's new-session regions, and the `settings-nav-rail` block of `SettingsPanel.tsx`. E13 self-tests: `bg-red-600` reintroduced in `Dialog.tsx` fails naming the file; a palette class in the rail block is caught. Plus the flow agent card gate (E11). See change: align-ui-with-theme-tokens, align-ui-contract-recipes. |
| `__tests__/event-reducer.subagent-stop.test.ts` | L1 subagent-stop finalize: E1–E19, F1–F6, X1, X4 — `subagent_completed`/`failed` + `agent_settled` finalize running Agent rows, sibling isolation, neutral sentinel + `resultMissing`, late-tick guard, real end overwrites, determinism. See change: finalize-agent-card-on-subagent-stop. |
| `__tests__/folder-focus.test.ts` | Unit cover for `folder-focus.ts`: `demandsAttention` status/tool/unread matrix, `resolveGroupRenderMode` across focused/attention/peek inputs, `resolveActiveCwd` intent precedence (`select` vs `activate`). See change: add-focus-mode-and-card-block-toggles. |
| `__tests__/initial-ws-url.test.ts` | `getInitialWsUrl`: Electron local window ignores a saved remote (value kept). See change: add-electron-server-windows. |
| `context-usage.ts` | Exports `buildContextUsageMap(sessionStates, sessions): Map<string, ContextUsageInfo>`. → see `context-usage.ts.AGENTS.md` |
| `create-project.ts` | `createProjectAndPin(name, {send, setPinned})` — POST `/api/browse/create-project`; on success optimistic pin + `pin_directory` with the returned real path. Never throws; failure → `{ok:false, reason?}`, nothing pinned. See change: streamline-first-run. |
| `css-escape.ts` | `cssEscape(s)`: native `CSS.escape` when present, else hex-escapes every code point outside `[A-Za-z0-9_-]`. Fallback specified for quoted attribute values only (`[data-x="…"]`). Used by `SessionList.tsx`, `OpenSpecBoardView.tsx`. See change: fix-codeql-small-findings. |
| `electron-server-windows.ts` | `getOpenServerWindow()` — feature-detect `window.piDashboard.openServerWindow` on a loopback origin (DOM-free, no i18n). See change: add-electron-server-windows (D9, D13). |
| `file-digest.ts` | `fetchFileDigest(cwd,path,purpose,signal)` → `{sha1,size,mtime} \| null` via `fetchWithoutGrantPrompt` (never prompts). See change: gate-changed-on-disk-by-content. |
| `folder-focus.ts` | Pure accordion/focus decision logic for the sidebar folder list. Exports `demandsAttention(session)` (status/currentTool/unread), `GroupRenderMode` = `full`\|`collapsed`\|`compactAttention`\|`compactEmpty`, `resolveGroupRenderMode(input)`, `FocusIntent` = `select`\|`activate`, `resolveActiveCwd(input)` (focused folder follows the LATEST intent). No React, no DOM — the accordion's rendering rules are testable without mounting `SessionList`. See change: add-focus-mode-and-card-block-toggles. |
| `init-setup-state.ts` | `setupState(status) → "not-a-project"\|"ok"\|"unknown"` + `SetupState`. Checklist `settings` entry wins; deprecated `configured` boolean only without checklist; neither → `unknown` (fail open). Shared by `useInitStatus` + `FolderActionBanner` so the hook never imports a component. See change: fix-project-setup-completion-state. |
| `i18n-en-source.json` | English source catalog (structured key → copy) for `scripts/i18n-migrate-auto-keys.mjs`. User-facing copy says new session / start / restart, never spawn; keys stay stable (gate: `__tests__/ui-copy-no-spawn.test.ts`). See change: align-ui-with-theme-tokens. `settings.archiveAfterDaysHint` / `settings.archiveDaysInvalid` scope `0` to age-based auto-archive. See change: archive-service-sessions-on-end. Adds `gateway.lan.*`, `connection.connect*`, `connection.requestAccess`, `landing.request.*`, `pairingApproval.knock*`, `gateway.pair.*`; changes `common.pairingNeedsSecureRoad`. See change: add-lan-knock-pairing. Adds `questions.*` keys. See change: add-pending-question-stack. |
| `model-scope.ts` | Pure logic of the `enabledModels` scope editor: `buildScopeCatalogue`, `parseScope` (provider glob only when it covers EVERY catalogue model; picks matched by full id before suffix strip; else pattern), `serializeScope`, `toggleProvider`/`toggleModel` (slash-id providers → explicit picks; deselect-one rewrites `p/*` into picks), `addPattern`, `countInScope` (shared matcher). Entries keep their original strings. See change: pi-settings-full-coverage. |
| `open-server-window-failure.ts` | `describeOpenFailure(reason, name)` — toast text for a failed open-server-window request (i18n keys `connection.openWindow.*`). See change: add-electron-server-windows. |
| `settings-promotions.ts` | Pure settings-nav promotion resolver. Exports `resolveSettingsPromotions(rows, reserved)` → `Map<pluginId, SettingsPromotion>` in display order (`order`, `label`, id), `RESERVED_SETTINGS_LABELS` (static: built-in page + group labels, en + every locale via `translationsOf`, folded), `foldSettingsLabel` (NFKC+trim+lowercase), `PROMOTION_GROUP_ALLOWLIST` (`models`). Gate: settings-section `nav` + allowlisted group + `row.firstParty === true` + non-reserved label; first eligible claim per plugin; label de-dupe by (`order`, id). See change: promote-model-roles-settings. Reserved labels now include `settings.groupAddons` / `settings.addons` (Add-ons); `Packages` / `Extensions` group labels retired from the list (Resources › Extensions stays). See change: addons-hub-declutter. Reserved label `settings.vault` / "Vault". See change: add-credential-vault. `PROMOTION_GROUP_ALLOWLIST` = `models` + `resources`. See change: add-skill-atlas-screen. `translationsOf` now reads static `RESERVED_LABEL_TRANSLATIONS` (lazy catalogs not loaded). See change: shrink-client-entry-lazy-islands. |
| `selection-modifier.ts` | Pure file-manager selection rules. `isAddToSelectionModifier(e, "mac"\|"other")` (mac → metaKey, else ctrlKey; macOS Ctrl-click never toggles). `applyRowClick(prev,{path,ordered,mod,shift})` → `{selected,anchor}`: plain replaces, mod toggles (anchor follows), Shift ranges from anchor in document order, no anchor → plain. Test `__tests__/selection-modifier.test.ts` (E1–E7). See change: simplify-add-folder-picker. |
| `sha1.ts` | `sha1Hex(bytes)` (`crypto.subtle`, else pure-JS `sha1HexSync` for plain-http origins) — the file-handler snapshot token. See change: add-editor-pane-file-handlers. |
| `use-loopback-link-open.ts` | `useLoopbackLinkOpen()` → `(e,href)` click handler shared by `MarkdownContent.a()` + `UrlLink`. → see `use-loopback-link-open.ts.AGENTS.md` |