@@ -157,9 +157,11 @@ ports must be integers from 1 to 65535. Browser dev
157157prints its selected URL and can use a later port when the requested port is
158158occupied. Port selection does not isolate credentials or native plugin data;
159159use the existing ` BUZZODZ_PROFILE ` setting for separate plugin profiles.
160- Both run the development broker with your identity when the public
161- ` BUZZ_DEV_VIEWER ` pin is configured in ` .env.local ` , and start without live
162- identity otherwise; see [ the setup and Keychain requirements] ( ../README.md#relay-channels ) .
160+ A public ` BUZZ_DEV_VIEWER ` pin enables the legacy development broker for either
161+ command. Without it, browser development has no live broker identity, while
162+ supported desktop development can use native identity and relay access. See
163+ [ host modes below] ( #shared-logic-and-host-boundaries ) and
164+ [ the broker setup requirements] ( ../README.md#relay-channels ) .
163165
164166After creating a worktree, bootstrap it from the checkout whose local development
165167configuration it should inherit:
@@ -194,6 +196,70 @@ Ordinary checkouts, non-macOS launches, and `pnpm tauri build` keep their existi
194196icons. This does not change the app identifier, credentials, profiles, or
195197notification settings.
196198
199+ ## Shared logic and host boundaries
200+
201+ Browser and desktop share the React application, community sessions, durable
202+ outbox, protocol models and live scheduler. ` dev/ ` is the Node host for browser
203+ development and broker-backed tests, not generated output or another relay.
204+ Packaged desktop uses the Rust host. Node code does not run in a browser merely
205+ because it serves one, and packaged desktop does not need a Node backend.
206+
207+ | Mode | Identity and relay host |
208+ | --- | --- |
209+ | ` just web ` , public ` BUZZ_DEV_VIEWER ` pin | Node broker using the pinned existing legacy identity (macOS/Linux) |
210+ | ` just web ` , no pin | Shell/fixtures; no live broker identity |
211+ | ` just desktop ` , public pin | Legacy broker identity/relay access, even inside the native window; native-only capabilities may coexist |
212+ | ` just desktop ` , no pin | Native identity/relay access on supported macOS, Windows and Linux |
213+ | Packaged desktop | Native host; production builds exclude the dev broker regardless of the pin |
214+
215+ A static frontend build does not supply a standalone browser login/backend.
216+ The public pin does not migrate keys. Native debug worktrees share a credential
217+ namespace distinct from release and legacy broker credentials; ports and plugin
218+ profiles do not isolate those keys. Removing the pin may change the active
219+ identity, not just the transport. Do not change defaults, credentials or a running
220+ app as incidental cleanup. See [ identity custody and acceptance] ( identity.md ) .
221+
222+ ### Where behavior belongs
223+
224+ - Put platform-neutral models, edits and protocol policy in their existing
225+ ` src/features/* ` owner, with current callers rather than speculative adapter
226+ parity. The Node host and native frontend adapter can reuse dependency-free
227+ TypeScript where appropriate;
228+ [ sidebar edits] ( ../src/features/relay/sidebar-edits.ts ) and
229+ [ community commands] ( ../src/features/communities/admin-protocol.ts ) are examples.
230+ Shared modules must not depend on Node, Tauri or a dev-host implementation.
231+ - Keep signing keys, decryption, secure storage, subprocesses and host I/O in the
232+ host. Each independently callable HTTP/IPC boundary retains its own validation,
233+ signing policy, destination/identity binding, resource limits, cancellation and
234+ lifecycle ownership. Moving checks into shared frontend code is not a substitute
235+ for Rust enforcement. The relay remains the access-control authority.
236+ - For necessary cross-language implementations, share concrete contract cases
237+ rather than inventing a universal adapter or code generator. Existing JSON
238+ fixtures can be read by Vitest and Rust ` include_str! ` . Document intentional or
239+ unresolved differences with separate expected outcomes; neither implementation
240+ automatically defines the intended policy. Changing those outcomes is a behavior
241+ decision, not a refactor. Do not add a second source of feature policy in ` dev/ ` .
242+
243+ ### Review and evidence
244+
245+ A cross-host change names its feature owner/current consumers, supported modes,
246+ behavior preserved or explicitly approved differences, and the duplicate code it
247+ removes. Update the feature's contract cases and relevant wiring tests in the
248+ same change. Reuse existing runners and CI; this is not an extra full-suite gate
249+ for each edit. Keep feature details with their owner, not copied into this guide.
250+
251+ [ Canvas shape cases] ( ../src/features/channel-templates/canvas-signing-contract.json )
252+ are consumed by the Node and Rust tests. They cover kind-40100 tag shape, including
253+ an explicitly rejected native deserialization case; each host separately tests the
254+ UTF-8 content limit. This is not whole endpoint parity: broker freshness checks,
255+ native serialized-event limits, HTTP/IPC authorization and publication outcomes
256+ are separate layers. Existing host-specific checks remain necessary.
257+
258+ Report the exact snapshot and host/mode exercised. A broker-backed browser fixture,
259+ or a Tauri window using that broker, does not prove native signing, OS storage,
260+ networking or filesystem behavior. Native/live acceptance needs an agreed isolated
261+ identity/data setup; browser fixtures and test identities must never use real keys.
262+
197263## Interactive product iteration
198264
199265While shaping the first version, default to ** edit → human tries the running app
0 commit comments