AGENTS.md — Web client stack

Rules for packages/client/* (the browser side of the dsh web GUI) plus its build entry apps/web. They supplement the repo-wide conventions and the package rules. Before touching slots, component props, stores, or plugin structure, read the slot system standard (the definitive composition model) and the web client architecture note (loading chain, object layer, services).

Packages here are named with the directory prefix: @deepseek-ai/dsh-client-<name>.

Slot and props discipline

The slot system standard owns the full design; these are the rules you must not violate when writing or reviewing client code:

One API: a plugin composes UI only through ctx.slots.register({ name, children?, store?, inject? }, Component). There is no separate slot-definition call, no whitelist face object, no face-minting helper. The shell alone renders 'root'.
children = declaration + authorization: the slots your component renders are exactly the keys of your register call's children object (spec values: kind/scope). Rendering a slot you didn't declare, or declaring one someone else declared, fails at load — do not work around it; the conflict is the design speaking. Slot names mirror the composition path: <domain>.<entry>.<hole> (e.g. 'conversation.chat.toolview').
Component props are the four shares, all derived: PropsRuntime<K> (SlotMap: owner params + useSession/sessionId on session scope + global useSessions/useWorkspaces) & PropsRenderSlots<S> (children keys) & PropsStore<H> (store factory) & the inject face. Never hand-write a member a share already derives; never re-type a share locally.
Hooks are framework-made only: useSession, useSessions, useWorkspaces, useStore, renderSlot are the five standing seats, plus the use<Name> hooks the renderer binds from provide contributions and inject hooks compartments. Business code never creates a hook or selector as a prop value — pass plain data and callbacks. (Component-internal behavioral hooks that subscribe to nothing external are fine.)
Live data has exactly three channels: parent knows it → owner props at the renderSlot site; only the component knows it → local state; shared across entries or survives remounts → a store declared at register. Derived data is a pure function over framework-hook data (useMemo), never its own subscription.
Stores: read props.useStore, write props.actions.* — the declared actions are the complete mutation surface. Write the store as an exported createXXXStore() factory (module-level handles are forbidden — de-facto singletons); share by passing one handle to several registers inside apply. Production code never calls the factory or .create() outside apply; tests do (that is the sanctioned zero-machinery path).
inject returns plain data and callbacks from the apply closure's own ctx — no hand-made hooks, no ReactNode producers, no whole-service objects. A registrant-private reactive fact rides the reserved hooks compartment (bare observables the renderer binds to use<Name>; components never see the sources). Its capability boundary is the plugin's declared inject topology; there is no wider ctx to reach for.

Reactive read and contract-currency discipline

How live data reaches render code, and what may cross a business boundary:

Everything a render reads that can change outside React arrives through a framework hook (rule 4 above). Event-handler code may read live snapshots (e.g. keyboard.snapshot); render code subscribes.
Business components contain no subscription machinery — no useSyncExternalStore, no manual subscribe wiring, no mirroring an external snapshot into local state or a second store. Give each reactive fact its owning channel instead: registrant-private → the inject hooks compartment; cross-entry or remount-surviving → a declared store; per-session standard → sessions.provide.
Data-access ladder — resolve needs in this order: framework hooks (standing seats + provide/inject-bound use<Name>) → a declared store (useStore/actions) → inject callbacks → anything else is a new framework seam and needs main-thread arbitration.
Contract currency is JSON-able data and callbacks. Everything crossing a business boundary (owner props, inject faces, store state, provide contributions) is plain serializable data or a callback over such data; the inject hooks compartment is the one sanctioned carrier of bare observables, and components never see those either. ReactNode is not a currency: route render content through a slot; no new ReactNode-valued owner props or inject members (the composer's existing accessory/overlay/leftItems/rightItems seats are grandfathered and get migrated to slots progressively).
An observable source keeps two identities stable: the source object itself (hook binding is cached per source), and its snapshot between changes (getSnapshot returns the same reference until the fact moves).
Whoever rebuilds a published value republishes it through the same source in the same step, and a registration path that can run after consumers exist notifies the live consumers as part of registering.

Export discipline (client plugin packages)

The /client surface of a UI plugin package is a contract face, not a convenience barrel. Three rules, enforced package-wide (do not restate them as per-file comments):

A UI plugin exports no values beyond what cordis loading needs — apply / inject (and Config where present), plus store factories consumed type-only by components (ReturnType<typeof createXXXStore>). Types are the extra allowance: contract types (owner shares, injected shapes, composed props aliases) export freely. Implementation components, pure helpers, constants, and store handles stay internal. Adding any new value export requires user sign-off, not a matching consumer.
Same-package tests import internals directly — relative ../src/client/xxx.ts from package tests, or the ./src/* subpath where a spec lives outside the package. Never widen the public surface to make a test compile.
Cross-package imports of another plugin's symbols are in principle forbidden. The sanctioned routes are the slot system (register/renderSlot) and ctx services. If neither fits, stop and escalate — do not add an export to unblock yourself.

ctx discipline (components never see ctx)

ctx belongs to the apply world only: the plugin body and the inject factories closed over it. Components — every .tsx under a feature domain — receive all data and callbacks through the four props shares; they never call a hook that reaches ctx, never import a service class to poke it, never read a React context (business components see zero contexts — BindingContext and its kin are renderer-internal). If a component needs something new, the answer is a prop threaded from its share's source (owner site, store declaration, or inject face), not a hook.

Layering red lines

The stack has one-way knowledge, settled in the web client architecture note:

Data object layer (runtime, React-free): ConnectionController → SessionManager → Session own all business state (event windows, streaming accumulation, reconnect machine), and the snapshot-store engine (zustand/immer, defineStore, shallowEqual) lives here too — store products are bare observable sources with no hook members. Zero React imports — grep-assertable.
Render machinery (web-react, shell-only glue): the whole ctx↔React boundary — slot renderer/outlets, SessionProvider, the uSES bridge. Every hook is composed here at the binding site from bare sources; business plugin packages carry no web-react dependency at all.
Presentation components (plugin packages' src/client/, pure props): consumables, expected to be rewritten wholesale. Business logic must not leak into them; everything arrives through the four props shares.

Non-negotiables across the layers:

Business data lives in the object layer, never a store. Entry-declared stores carry shared viewing/interaction state (selection, drafts, panel widths); sessions, frames, and connections stay in the object layer.
rpcId is strictly bidirectional: the initiator mints, the responder echoes; business signatures see only RpcRequest<P>, minting stays in the carrier layer (layering and RPC protocol note).
Notifier publication discipline: notifyNow is only the direct echo of a user gesture; structural updates use microtask-batched markDirty, while visible streaming chunks use cumulative markFrameDirty. See runtime/src/client/sessions/notifier.ts.
The web layer is pure presentation. Nothing that is "how to draw" (tool-card views, queue states) enters the session log; the host computes such data per frame or pushes it live, and replay recomputes it — falling back to the generic form when it can't. A new model-visible input still requires a session event (repo-wide rule).

Directory regime (plugin packages)

One UI feature = one plugin package (src/client/ browser half). A multi-domain package splits by future package boundaries — ui-conversation is the exemplar: contract/ (the only shared face), domain directories that never import a sibling domain, and apply.ts as the single cross-domain assembly point; scripts/verify-client-domain-graph.ts enforces the levels. Registration goes through slots.register in apply — never module-level side effects.

Styling

docs/web-styling.md is authoritative. Shared --dsw-* tokens and global sheets live in ui-theme/src/styles/; feature components consume semantic aliases through CSS Modules and clsx, with no literal colors, component library, or Tailwind. Product copy is Chinese; code comments are English.

Testing and coverage

The GUI test structure (three tiers, lane map) is settled in the GUI testing system note; repo-wide policy in docs/testing.md.

Client source packages are inside the per-file 100% coverage gate (pnpm run test:coverage). Genuinely unreachable defensive arms take a /* v8 ignore -- <reason> */ comment with a real reason, never a bare ignore.
Component specs render with realistic props or a driven fixture runtime and assert user-visible behavior, not class names, hook internals, or render counts.
The jsdom environment comes from a per-file // @vitest-environment jsdom pragma on the spec's first line; the shared config stays node-env.
Each tier asserts its own layer. Data-layer semantics belong to the runtime and host suites; component specs cover presentation behavior.

Before you push: the local check ladder

Run the narrowest rung that covers what you touched; escalate only when the change surface demands it.

Every GUI code change — pnpm run test:gui (seconds; no browser, no server): the client suites plus the host-side GUI packages. This is the inner loop; run it as freely as a typecheck.
Any change that can alter the assembled browser or visible conversation/UI output (client components or copy, apps/web, Vite, dsh-host-webserver, connection/handler/SSE) — additionally DSH_SNAPSHOT=replay pnpm run test:web: rebuilds the frontend dist, then runs the browser smoke pair (the real-host case self-skips without DEEPSEEK_API_KEY) plus the keyless replayed e2e scenarios. Linux PR CI uses the same read-only replay mode. Use DSH_SNAPSHOT=refresh only after confirming an intentional output change, or DSH_SNAPSHOT=record with a key to re-record fixtures.
Before a PR — use dsh-pre-push-checks to select the narrow checks for the outgoing diff; there is no repo-wide pre-push aggregate.

If test:gui is red on code you did not touch, neither silently fix nor ignore it: note it in your handoff so it lands in the next PR window's sweep.

New plugin package checklist

Bringing up a new packages/client/<name> plugin package (ui-workspace is the latest walked example; ui-sidebar/ui-question are good skeletons to copy):

Package skeleton: package.json (@deepseek-ai/dsh-client-<name>, exports ././invariant/./client/./src/*/./package.json, dshClient manifest, files list), tsconfig.json (extends tsconfig.base.client.json, one references entry per workspace dependency plus support/invariants), tsdown.config.ts (clientBundle(id, ['lib/types/index.js', 'lib/types/invariant.js'])), src/index.ts (empty node-half apply), src/invariant.ts (companion with a real reason), src/css-modules.d.ts when using CSS Modules, README.md with the Model Experience section.
Three registration surfaces, all required (missing any one fails at a different, later point): the tsconfig.client.json aggregate references entry; a dshClient row in apps/cli/config/web.cordis.yml; an apps/cli/package.json dependency (Loader resolves each config-tree package against the composing app's URL — a row whose package is not an apps/cli dependency fails to import). pnpm-workspace.yaml already globs packages/*/*.
dshClient manifest semantics: platform: 'web' always; immediately: true only for stage-one-prefetch infrastructure rows. inject lists package-name dependency edges — they are informational only (preflight display, HMR diffing); they do not sequence entry activation or apply order. Activation order is cordis fiber inject waiting on services, nothing else.
Registering into another package's slot: if the declaring host provides no waitable service, your apply's order relative to the host's is unconstrained — a bare slots.register into its slot races boot (intermittent slot "..." is not declared page failures). Register with declaration-aware deferral: check ctx.slots.spec(name), otherwise ctx.slots.subscribe(name) and register on the declaration event (SlotCore supports subscribing ahead of declaration); make the registration idempotent, and unsubscribe + dispose in the effect disposer. Only take a service edge in inject when the host actually provides one (ui-question → 'conversation' is that case).
Rebuild the bundle (pnpm --filter <pkg> bundle) before probing a live dsh web server — the registry serves lib/client.js, not sources.

New component checklist

Compose through register: merge the slot contract into SlotMap, declare the slot in its parent entry's children, register your component — see the slot system standard. No other composition route exists.
Type the props as the four shares (PropsRuntime & PropsRenderSlots & PropsStore & inject face) — derive, don't hand-write. Shared/surviving state goes in a createXXXStore() factory declared at register; component-private state stays local.
Component tests feed props directly (createXXXStore().create() for the store share; plain stubs for framework hooks) — behavior-shaped assertions, no render machinery.
Tokens only in CSS; Chinese product copy; English comments.
pnpm run test:gui green; if the component changes visible assembled output, also run DSH_SNAPSHOT=replay pnpm run test:web.
Non-trivial change? It needs an Agent Note in the same PR (repo-wide rule) — the GUI notes above are the precedents to extend.

16 KiB Raw Blame History