# @webavatar/webavatar-core

Reusable realtime-session infrastructure for webavatar client projects — session management, auth tokens, provider adapters, and the WebSocket relay — so a client project doesn't reimplement the basics from scratch. Privately distributed (not published to the public npm registry); see the monorepo root's `docs/ARCHITECTURE.md` for the full picture and `docs/REALTIME_SESSION.md` for how the session layer works.

**ESM-only.** No CommonJS build; `require()` is unsupported by design.

## Entry points

| Entry                              | Contains                                                                                                                                                                                                                                                                                                  |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@webavatar/webavatar-core`        | Isomorphic contracts: the `ClientEvent`/`ServerEvent` protocol, `Logger`/`LogEntry`/`LogLevel`/`NOOP_LOGGER`, `ToolDefinition`/`formatToolError`, `SessionPersona`. Safe for both browser and server code.                                                                                                |
| `@webavatar/webavatar-core/client` | Browser transports and wrappers: `RealtimeClient`, `ResilientRealtimeClient`, client-side logging (`clientLogger`, `debugLogStore`), `createToolDispatcher`. Transport only, no business logic.                                                                                                           |
| `@webavatar/webavatar-core/server` | Server-only implementations: `loadConfig`, `selectProvider`, the analytics recorders, `resolveSessionDefaults`, `handleRealtimeUpgrade`, token mint/verify, `createToolRegistry`, and the `createRealtimeRuntime` composition-root factory. Resolves to a throwing stub in any consumer's browser bundle. |
| `@webavatar/webavatar-core/vite`   | `realtimeDevWsPlugin` — the Vite dev-server integration that wires the same WS upgrade handling into `npm run dev`. Kept separate from `./server` so importing the package root never pulls in Vite.                                                                                                      |

## The composition-root factory

Both a production entrypoint and a Vite dev-server plugin need the same wiring — load config, pick a provider, choose an analytics recorder, merge session defaults with your persona and tool registry:

```ts
import { createRealtimeRuntime } from '@webavatar/webavatar-core/server';

const runtime = createRealtimeRuntime({ persona, toolRegistry, isDev: false });
server.on('upgrade', runtime.handleUpgrade);
server.listen(runtime.config.port);
```

`isDev` is the only thing that differs per entrypoint. See `docs/ARCHITECTURE.md`'s "Composition roots" for why this exists — it's what keeps a consuming app's `server.js`/`vite.config.ts` thin.

## Server-only safety

`./server` and `./vite` map to a stub that throws when evaluated in a browser bundle (this package's `browser` export condition), for every consumer, automatically. A consuming SvelteKit app should still route through its own `$lib/server` wrapper and a build-time guard for defense in depth — see `docs/ARCHITECTURE.md`'s "Server-only safety" section for the full layered approach the template app uses.

## Compatibility

Caret-ranged (`^0.1.0`) during the `0.x` window — a core minor is a coordinated release with `@webavatar/webavatar-humanoid`'s peer range. See the monorepo root's `docs/MONOREPO_MIGRATION_BRIEF.md` ("Versions, ranges, and the `0.x` window") for the full policy.

## Peer dependencies

`vite` is an **optional** peer — only needed if you import `./vite`. Consumers that never touch that entry point don't need Vite installed at all.