develop-frontend

Develop the Frontend

Read the Contracts

1. Read packages/app/AGENTS.md and Web product contract.
2. Read Frontend data sync for contexts, snapshots, events, streaming, composer intent, or loaded buckets.
3. Read Browser runtime for Browser UI or Desktop/Web presentation changes.
4. Load change-server-api when the UI needs a new or changed server contract; load add-tool for tool-card presentation.

Preserve State and API Ownership

1. Use stores for coherent keyed collections and signals for independent scalar state.
2. Apply entity updates with targeted setters and reconcile; do not replace a whole stored object for a one-field event.
3. Keep derived values one-way. Preserve composer resolution as explicit draft → session default → fallback; only explicit user choices persist upward.
4. Use generated SDK methods for ordinary internal HTTP routes. Keep raw browser transports only for WebSocket/EventSource/WebRTC, external URLs, platform fetch injection, and browser file/blob/download flows that the SDK should not represent.
5. Preserve Scope/directory parameters, authentication, error semantics, asset URLs, event seq/epoch, replay, and loading/error states.
6. For append-only LLM streams, keep the full snapshot as recovery state while imperative renderers track an offset and consume only the appended suffix through the dependency's typed live-update API. Do not rescan the accumulated prefix or insert an independent character-rate playback backlog; reset from a checkpoint only when the append invariant breaks. Derive terminal presentation from explicit part or message lifecycle markers, not coarse session status or the presence of a later timeline part. Key imperative terminal transitions and enhancements by content identity so unrelated sibling updates cannot restart them.
7. Do not key the whole turn or message-role boundary by object identity: message.updated events land as fresh objects on every update, so a keyed Show/Match destroys and rebuilds the entire turn (tool-card expansion, scroll, and Markdown state included) several times per reply. Keep those boundaries non-keyed responsive updates, and instead isolate failures inside Part with an identity snapshot: capture session/message/part/type before child evaluation, render the ErrorBoundary fallback from that snapshot only, and never re-read the failed child's live props. Log the original error with stable IDs only; exclude message content, tool payloads, and workspace paths. Cover this with a real Solid lifecycle test that proves a secondary stale read cannot escape the local boundary.
8. Read session-shaped store fields through the session data view only: ui components use useData().view (partsFor/messagesFor/permissionsFor/statusFor/inboxFor/hasInboxBucket/todosFor/dagNodesFor/questionsFor/cortexTasks/sessions/sessionFor), app components use useSessionDataView(). Do not read data.store.part/permission/... or sync.data.<field>[sessionID] directly in render code — session switches race store intermediate states (missing buckets, released scope stores) and createMemo defaults stop applying after first compute, so a direct read can surface undefined and crash with a rotating set of TypeErrors. The view accessors apply their empty fallback inside the function body. Missing array buckets must resolve to the shared constants in packages/ui/src/context/session-data-view.ts (EMPTY_PARTS, EMPTY_MESSAGES, …) — never a fresh array literal, because the render chain's same() equality guards short-circuit on reference identity and a fresh literal would invalidate every downstream memo on each store tick. hasInboxBucket is the only accessor that reports bucket presence: use it to preserve an "not loaded yet" gate when undefined semantics matter (e.g. inbox loading state).
9. Callback parameters are accessors or raw values depending on the control: non-keyed <Show> and <Index> pass an accessor — call it (param()) before rendering or passing it into i18n values, formatters, or attributes — while <Show keyed> and <For> pass the raw value itself. Passing an accessor uncalled renders its minified source (the crash-page footer once displayed Version: () => { if (!untrack(condition)) … }), and calling a keyed <Show> or For parameter fails typechecking. Prefer the non-callback form reading the source signal directly when no narrowing is needed.