AGENTS.md@packages/client/src git:20260907.71cc2dcA

Immutable. This exact content is served forever at /api/v1/blob/1fd5050cced2dbe7.

# DOX — packages/client/src

Files in this directory. One row per source file.

| File | Purpose |
|------|---------|
| `App.tsx` | Two new shell-overlay routes: `/folder/:encodedCwd/view?path=…` (file preview) + `/pi-view?url=…` (URL… → see `App.tsx.AGENTS.md` The plugin-slot `h-[92vh]` wrapper STAYS: plugin claim bodies are `absolute inset-0` (zero intrinsic height) and would collapse to 0 under the deliberately height-INDEFINITE flush panel — a definite-height PIN, not a duplicated flex context. See change: fix-flush-dialog-scroll-and-close-collision. Hydrates `openspec.offerInitialization`/`enabled` from /api/config; threads them + readiness to SessionList/ComposerSessionActions. See change: add-openspec-init-affordances. |
| `index.css` | Global stylesheet + theme-variable roots. `:root` (dark) / `[data-theme="light"]` per-mode token maps, Tailwind `@source` directives, `text-code` utility, selected-card `card-glow-fx`/`card-ring-fx`. Home of `--elevation-rim` panel-bevel inset-highlight token (dark `rgba(255,255,255,0.10)`, light `rgba(255,255,255,0.9)`); theme-agnostic, NOT in `CSS_VAR_KEYS` so it survives `applyThemeVars`. Tool-group liveness: `tool-group-shimmer`/`tool-group-spin-pulse`/`tool-group-flash` (running header + completion flash) + `chat-stream-live` (streaming-bubble edge-pulse+sweep); all transform/opacity/background-position, suppressed under `prefers-reduced-motion`. `@keyframes wtinit-slide` drives WorktreeInitChip's indeterminate progress bar. Home of `--severity-{error,warning,success,info,neutral}-{bg,fg,border}` message-severity tokens — single color source for toasts/banners; accent tiers via `color-mix` (bg 10% into `--bg-tertiary`, fg 46% toward `--text-primary`, border 40% alpha), `neutral` = literal base tokens; `--severity-info` separate from `--status-notice`. OpenSpec-board drop targeting: `.board-drop-marker::after` paints the 3px insertion bar into the EXISTING `gap-2`/`p-2` space (never an inserted flex child, which would add a second gap and oscillate the resolved slot), own z-index band above `.card-stripes-fx`; `.board-append-rail`(`-active`) sticky ≥44px append target; `.board-column-target`/`-receded`/`.board-column-body-over` drag-state legibility; `.board-edge-glow`(`-top`/`-bottom`) auto-scroll zones at `height: 0` with a negative margin cancelling the flex gap so mounting them mid-drag shifts no card. Theme tokens only. Home of `--border-strong`, the WCAG 2.1 SC 1.4.11 (3:1) boundary token for an overlay surface floating on `--bg-primary`; REUSE it rather than re-deriving — no other border token qualifies. Like every token here it MUST be declared in BOTH theme blocks: one-block-only silently resolves to an invalid value in the other theme. Home of the overlay z-index layer scale `--z-base … --z-lightbox` (ascending: base<raised<sidebar<overlay<popover<dialog<toast<lightbox) + matching `@utility z-<layer>` — single source of stacking order (z-index / stacking-context / underlap / portal / layering). Portaled overlays reference a `z-<layer>` token, NEVER a raw `z-[NNNN]` (frozen ratchet `scripts/z-layer-lint.mjs`). See changes: add-panel-elevation-system, enhance-tool-call-grouping, friendlier-worktree-init, unify-message-severity-colors, fix-openspec-board-drop-targeting, fix-replay-pill-a11y-and-collision, add-overlay-layering-system. Imports `./styles/asciidoc.css` (the `.asciidoc-body` preview typography scope) right after `@import "tailwindcss"`. See change: asciidoc-support. |
| `main.tsx` | React app bootstrap + UI primitive registry registration. Creates root, wraps `App` in `UiPrimitiveProvider`, `Router`, `ThemeProvider`, `I18nProvider`, `MobileProvider`. Builds `primitiveRegistry` via `createUiPrimitiveRegistry` + `registerUiPrimitive` for every `UI_PRIMITIVE_KEYS.*` (`agentCard`, `markdownContent`, `confirmDialog`, `dialog`, `dialogPortal`, `searchableSelectDialog`, `zoomControls`, `formatTokens`, `formatDuration`, `actionList`, `statusPill`, `modelSelector`, `thinkingLevelSelector`, `popover`, `toolCallStep`, `thinkingBlock`, `logBlock`). Adapts `Confirm`→`ConfirmDialogPrimitive`, `ToolCallStep`→`ToolCallStepPrimitive` (minimal `ToolContext`), `ThinkingBlock`→`ThinkingBlockPrimitive`. Registers `/sw.js` service worker. Imports `katex.min.css`. Calls `installDeviceAuthFetch()` at startup (paired-device bearer on every same-origin API request). Renders `<PairLanding/>` instead of `<App/>` when `location.pathname === "/pair"` (phone-camera pairing landing, pre-auth). See change: make-pairing-qr-camera-scannable. `ui:model-selector` + `ui:thinking-level-selector` register the shell-bound wrappers from `lib/plugins/shell-primitives.tsx`. See change: upgrade-model-selector-primitives. |