web-app · git:20261114.74435bb · 2026-11-14 · sha256 a3a15a035269f406

web-app git:20261114.74435bbA

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

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_yc7hyr2rs5xfpiff/a3a15a035269f4066be8217c57368fe4a9a2052aa46dac997694d1913d7f7c0a.json

Then /plugin install web-app@markdownregistry-yc7hyr2rs5xfpiff in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: web-app
description: >
  React web app in packages/web: folder layout, the IServerConnection interface and its WebSocket
  implementation, access token handling, conversation state, the feed and composer, the mission
  board, the squad panel, usage and agent login indicators, the skills page, the import convention,
  testing with Testing Library and fake connections, and vendored shadcn/ui components. Use when
  working with the web package, React components, the browser connection to the server or the
  access token form.
---

# Web app

> **Maintaining this skill**
>
> Update this document whenever any rule described here changes. The criterion is not
> *which* rule — it is the nature of the change: a layout, connection, import or testing rule
> changed → update; a visual tweak that preserves the described behavior → leave it alone.

`packages/web` (`@agent-remote-control/web`) is a React + Vite + React Router + Tailwind v4 + shadcn/ui
app. It talks to the server only through `@agent-remote-control/protocol`, over a WebSocket.

## Layout

```text
packages/web/src/
├── main.tsx                 # bootstrap: ConnectionProvider + RouterProvider
├── router.tsx               # route table (`routes`) and the browser router
├── connection/              # IServerConnection, WebSocket implementation, AccessTokenStore, context
├── conversations/           # reducer, context, entry grouping, open question, team state, presence
├── artifacts/               # the mission board of each conversation: reducer, context, useBoard, tree helpers, labels, paths
├── theme/                   # ThemeProvider and useTheme (light, dark, system)
├── pages/                   # route-level screens
├── test/                    # FakeServerConnection, renderApp, feed providers, fixtures
├── components/              # app components; components/ui is vendored shadcn
│   ├── agent/               # AgentMark: the round lens with an animated glyph per role
│   ├── squad/               # SquadPanel (right panel), Station, spine and motion hooks, squad status
│   ├── usage/               # UsageIndicator (header), UsagePanel, useAgentQuota, quota levels
│   ├── auth/                # AgentAuthController (toasts), AgentAuthPopover (header), AgentLoginCard, useAgentAuthStatus
│   ├── artifacts/           # ArtifactBoard (list and kanban), ArtifactPane and ArtifactDetail, create dialog, properties, activity
│   ├── skills/              # SkillList, SkillDetail, SkillRoles and the skill paths of the skills page
│   ├── settings/            # agent, model and effort pickers of the settings sheet
│   ├── prompt-input/        # PromptInput and its hooks: history, file mentions, attachments, voice
│   └── entries/             # feed rows: handoff rows, activity groups, messages, questions
└── lib/                     # cn(), agent-identity (mark, color, stage, responsibility per role), tool-label, formatting, clocks, media query, useStoredFlag
```

## App shell

- `AppLayout` renders a header (a `PanelLeftOpen`/`PanelLeftClose` `IconButton` "Show conversations"/"Hide conversations" with `aria-expanded`, the primary "New conversation" button, the truncating `h1`, then the Skills link (an icon link with a tooltip, to `/skills`), the agent logins popover, usage indicator, connection badge and theme toggle on the right) above the page. It also mounts the sonner `Toaster` once, so every toast of the app and of the specs renders.
- From 768 px of viewport the conversation list is a docked `aside` (`id="conversation-list"`, 288 px) that pushes the page; it stays mounted and `hidden` while closed, defaults to closed and the choice is kept by `useStoredFlag` under `arc.conversationListOpen`. Below 768 px the same toggle opens `ConversationList` in a left shadcn `Sheet` (not persisted), which picking a conversation closes (`onNavigate`).
- "New conversation" lives only in the header (icon-only below `sm`) and the empty state of `ConversationPage`.
- `useStoredFlag` (`lib/`) keeps a UI boolean in `localStorage` under an `arc.*` key, in memory when storage throws.

## Connection

- Components depend on `IServerConnection` (`connect`, `disconnect`, `send`, `onEvent`, `onStatus`, `hasAccessToken`, `setAccessToken`), never
  on `WebSocket`, so another transport can replace `WebSocketServerConnection`. Status is
  `'connecting' | 'open' | 'unauthorized' | 'closed'`; `onEvent` and `onStatus` return an unsubscribe function.
  `hasAccessToken()` says whether a token is at hand (in storage or in a `#token=` link the page was opened with)
  and `setAccessToken(token)` keeps the one the user typed.
- `WebSocketServerConnection` receives an `AccessTokenStore` through its constructor (`main.tsx` creates it) and always connects to the relative `/ws` (`wss` on https), sends `auth` first and
  reports `open` on `auth.ok`. `auth.failed` or close code `4401` clears the stored token, reports
  `unauthorized` and stops. Other closes reconnect with exponential backoff from 500 ms to a 10 s cap, reset
  after a successful auth. Commands sent while not `open` are queued and flushed after `auth.ok`. Every frame
  goes through `parseServerEvent`; invalid frames are dropped with `console.warn`.
- `ConnectionProvider` owns the token state and the connection lifecycle: it asks the connection for the token
  (`hasAccessToken`, `setAccessToken`), connects when one exists and
  exposes `status`, `hasToken` and `submitToken` through `useConnection()`. Without a token (or after
  `unauthorized`) `AppLayout` renders `MissingTokenPage`.
- `AccessTokenStore` (`connection/access-token-store.ts`) keeps the token in `localStorage` (`arc.accessToken`) with `read`, `store`, `clear` and `load`. `load` first takes a `#token=` URL fragment into storage and removes it
  with `history.replaceState`. Every storage access is wrapped in `try/catch`.
- Vite proxies `/ws` and `/health` to the server in `dev` and `preview` without `changeOrigin`, so the server's origin check sees a same-origin request; the target port is the `PORT` of the root `.env` (default `3000`). nginx proxies the same path in production.

## Imports and vendored UI

- Relative imports with the `.js` suffix, which Vite resolves to `.ts`/`.tsx`. The `@/` alias is not used.
- `components/ui/**` is shadcn code kept as vendored source (style `base-nova`, Base UI); it is excluded from
  coverage. Look for a shadcn component before writing one, install it with the shadcn CLI and restore
  relative imports after each CLI run.
- Never disable lint rules globally to make generated code pass.

## Tests

- Specs sit next to the file under test (`*.spec.ts`, `*.spec.tsx`) and run in the Vitest project `web`
  (jsdom, globals, `@testing-library/jest-dom`).
- Use `FakeServerConnection` from `src/test/fake-server-connection.ts` for components; it records sent
  commands, lets the test emit events and statuses, and keeps the token in memory (`accessToken`, a token at the start;
  set it to `null` for a signed-out spec).
- The browser `WebSocket` is an external I/O boundary: stub it with `vi.stubGlobal` and fake timers.
- Specs that render the feed wrap it in `VirtuosoMockContext` (`renderApp` already does); the scrolling specs are described in [references/conversation-feed.md](references/conversation-feed.md).
- Target 100% coverage outside `components/ui`.

## Conversation state

- `conversationsReducer` is a pure reducer from `ServerEvent` to `ConversationsState` (`list` ordered by
  `updatedAt` desc, `agents`, and `byId` with `entryIds`, `entries`, `state`, `loaded`, `configured`,
  `profilesLoaded`, `profiles`). `conversation.entry` upserts by id (existing ids replaced in place, new ids
  appended); `conversation.history` replaces the conversation wholesale. Events that carry no state
  (`models.list`, `efforts.list`, `error`, auth) leave it untouched; the settings sheet listens to them
  through `connection.onEvent`.
- State that only one feature reads (the board, usage, agent logins) lives in its own provider or hook, outside
  the conversations reducer.
- `ConversationsProvider` lives inside the router (`AppLayout`). It sends `conversation.list` on every `open`
  status, and navigates to `/c/<id>` on the `conversation.created` whose `requestId` it generated.
  `ConversationView` sends `conversation.history` and `profiles.get` whenever the status is `open` or the
  conversation changes, and `agents.list` while no agents are known.

## Theme and motion

- `ThemeProvider` keeps the choice (`'light' | 'dark' | 'system'`, default `'system'`) in `localStorage`
  (`arc.theme`) and toggles the `dark` class on `<html>`; `system` follows `prefers-color-scheme` live. An inline
  script in `index.html` applies the class before the first paint. `ThemeToggle` (a shadcn dropdown menu) sits in
  the header. Style through the theme tokens so both modes work.
- Scrollbars are styled once, in the base layer of `index.css`, for every scrolling element: a thin floating thumb on a transparent track, from `--scrollbar-thumb` and `--scrollbar-thumb-hover`. A component adds no scrollbar styling of its own; `scrollbar-width` or `scrollbar-color` on an element turn the `::-webkit-scrollbar` rules off in Chromium, so those properties apply only where the pseudo-elements do not exist.
- Every animation sits behind `motion-safe:` or a `prefers-reduced-motion: no-preference` query; `index.css` holds the keyframes.

## Feature areas

Each area below has a reference with its components, states and exact texts. Read the reference before changing that area.

- **Conversation list**: rows ordered by recency, Rename and Archive through `conversation.rename`/`conversation.archive`, an "Archived (n)" group, in-place `TitleInput`. Read [references/conversation-list.md](references/conversation-list.md) when touching the list or renaming.
- **Feed**: how each entry type renders, questions and the open question, the virtualized `FeedList` with stick-to-end and "Go to question", the streaming draft and the "Working…" indicator. Read [references/conversation-feed.md](references/conversation-feed.md) when touching `components/entries/`, question cards or feed scrolling.
- **Composer**: disabled until `open` and `configured`, Stop sends `turn.cancel`, prompt history, `@` file mentions, chunked attachments, voice recording, and the answer input of the question card. Read [references/composer.md](references/composer.md) when touching `components/prompt-input/` or the composer.
- **Mission board**: the `Chat | Tasks` routes, `ArtifactsProvider` and `useBoard`, the list and kanban views, the create dialog, the artifact detail and frozen tasks. Read [references/mission-board.md](references/mission-board.md) when touching `artifacts/` or `components/artifacts/`.
- **Team presentation**: the feed is the history and the squad panel is the present moment; agent identity and `AgentMark`, `deriveTeam`, stations, focus, the panel layout and presence. Read [references/team-presentation.md](references/team-presentation.md) when touching `components/squad/`, `components/agent/`, team state or agent colors.
- **Agent usage**: the header meters, the usage popover and the `quota.get` refresh cadence. Read [references/agent-usage.md](references/agent-usage.md) when touching `components/usage/`.
- **Agent logins**: the logins popover, the login state machine and the persistent per-agent toasts. Read [references/agent-logins.md](references/agent-logins.md) when touching `components/auth/`.
- **Skills page**: `/skills` routes, the list and detail, "Ask the CEO", deleting a custom skill and `startConversation(prompt)`. Read [references/skills-page.md](references/skills-page.md) when touching `components/skills/` or `SkillsPage`.