webavatar-core/packages/core

@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:

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.