CultLib/packages/cultmesh-browser/README.md

# CultMesh Browser

`cultmesh-browser` is the browser-safe CultMesh client boundary. It owns one
WebSocket session for a stable Verse/authority-runtime target, retains explicit raw
document leases across route replacement, and correlates typed CultNet
operations with provider receipts.

It does not own application state and it does not expose direct document
writes. A renderer watches provider-owned records and invokes provider-owned
operations.

```ts
const odin = new CultMeshBrowserOdinRendezvous({
  endpoints: ["wss://odin.example/verse"],
  runtimeId: "counter-browser.discovery",
});

const mesh = await CultMeshBrowserClient.connect({
  verseId: "sample.counter",
  authorityRuntimeId: "sample.counter-daemon",
  runtimeId: "counter-browser",
  rendezvous: odin,
});

const counter = await mesh.leaseRawDocument({
  schemaId: "sample.counter_state.v1",
  recordKey: "counter:main",
});

counter.watch(record => renderCounter(decodeCultNetPayload(record)));
```

`invoke(...)` returns the correlated provider response. Routing, schema, and
envelope failures reject immediately with `CultMeshBrowserOperationError`;
callers can branch on its stable `status` and `code` without parsing prose or
waiting for the request timeout. Domain rejections remain typed provider
responses because the domain still owns their receipt schema.

`CultMeshBrowserOdinRendezvous` speaks the canonical CultNet Verse-catalog
messages to one or more configured Odin WebSocket endpoints. Application code
supplies the Verse and authority-runtime identity; it does not own endpoint
selection, reconnect, or resubscription. This is deliberately distinct from an
Eve surface's `providerId`, which identifies the UI provider inside the Verse.
The physical socket is a replaceable route, not either stable identity.

Odin returns exact authority-route bindings. The browser selects only routes
bound to the requested authority and `cultmesh.documents.v1`, then performs a
session-open handshake. It does not report `connected` until the peer proves
the exact Verse, authority runtime, protocol, and route generation. Operation
responses must also name that authority. Legacy catalogs are accepted only
when one authority runtime makes the endpoint binding unambiguous.

The browser handshake carries authentication through the host application's
ordinary secure cookie or equivalent upgrade credential. The C# host adapter
rejects endpoints without an authorization predicate unless anonymous local
development is explicitly enabled.

Run `scripts/verify-eve-browser-network.mjs --eve-root <path-to-Eve>` for the
real Chromium + C# headless chronology. The witness publishes a lower-priority
decoy endpoint owned by another runtime and proves that neither client connects
to it before and after route rotation.