Skip to content
Merged
Show file tree
Hide file tree
Changes from 30 commits
Commits
Show all changes
47 commits
Select commit Hold shift + click to select a range
6cc684a
build: declare sideEffects and add a bundle size breakdown script
lukasIO Oct 7, 2026
d82bcf6
refactor(room): add the extension contract, move data streams and rpc…
lukasIO Oct 7, 2026
29108ef
refactor(room): move data tracks behind the dataTracks extension
lukasIO Oct 7, 2026
674c347
refactor(room): move frame metadata and E2EE setup behind extensions
lukasIO Oct 7, 2026
b24eb6a
feat(core): add an unpublished core entry and a gate for its imports
lukasIO Oct 7, 2026
7079642
docs: describe the room extension pattern in AGENTS.md
lukasIO Oct 7, 2026
7679901
chore(core): export the extension API types and tighten the core gate
lukasIO Oct 7, 2026
531508a
build: bundle the core entry and track its size with size-limit
lukasIO Oct 7, 2026
f81bf29
refactor(room): move video publishing behind the video extension
lukasIO Oct 8, 2026
8929d63
coreroom only
lukasIO Oct 8, 2026
b45fde1
feat(core): publish the livekit-client/core entry
lukasIO Oct 8, 2026
34b1139
refactor(room): move simulateParticipants and legacy chat behind exte…
lukasIO Oct 8, 2026
36fe44d
perf: mark module-level constructors and lookups as pure
lukasIO Oct 8, 2026
71b9053
feat(core): createRoom(options, [extensions]) replaces CoreRoom.with()
lukasIO Oct 8, 2026
5fb3fba
fix(lint): merge duplicate options import, rename shadowed parameter
lukasIO Oct 8, 2026
d2c747c
fix(core): keep the full entry's augmentations out of core consumers'…
lukasIO Oct 8, 2026
4189169
refactor(core): move extension-only operations onto ExtensionContext
lukasIO Oct 8, 2026
5e003ef
strip internal methods on core
lukasIO Oct 8, 2026
bb6a37a
build(core): emit the core entry's declarations with @internal stripped
lukasIO Oct 8, 2026
e4992de
fix(core): configured frameMetadata reaches the publish path; connect…
lukasIO Oct 8, 2026
7ac0614
fix(frameMetadata): hand core the options through a context slot; kee…
lukasIO Oct 8, 2026
85fa567
fix(video): gate the E2EE simulcast workaround on the room's E2EE setup
lukasIO Oct 8, 2026
0f62f0f
fix(e2ee): terminate the worker of an extension-created manager on di…
lukasIO Oct 8, 2026
aafbdb9
Update room-extensions.md
lukasIO Oct 8, 2026
5621bde
chore(types): hide SignalClient from the core types again
lukasIO Oct 15, 2026
6043550
build(core): emit the core declarations from a program rooted at core.ts
lukasIO Oct 15, 2026
5c7234b
Merge branch 'core' of github.com:livekit/client-sdk-js into core
lukasIO Oct 15, 2026
82a970c
refactor: let the extension objects and the check room infer their types
lukasIO Oct 15, 2026
a08c8e8
chore(extensions): name extension symbols lk.extension.<name>
lukasIO Oct 15, 2026
3cbccbf
remove core example for now
lukasIO Oct 15, 2026
aa37eb8
refactor: move the full Room module to src/Room.ts
lukasIO Oct 15, 2026
cf53cd2
cleanup readme
lukasIO Oct 15, 2026
01d397f
hooks on return type
lukasIO Oct 15, 2026
5ca6fe0
use fine grained interfaces for providers and hooks
lukasIO Oct 15, 2026
2326745
move room file
lukasIO Oct 16, 2026
0d88d8a
update import
lukasIO Oct 16, 2026
6ade193
mark as experimental
lukasIO Oct 16, 2026
a274a5b
remove unneeded size breakdown
lukasIO Oct 16, 2026
c7c164f
perf: mark module-level constructors and lookups as pure
lukasIO Oct 16, 2026
0ec3ca0
Merge branch 'main' into core
lukasIO Oct 16, 2026
35220cd
Merge remote-tracking branch 'origin/pure-annotations' into core
lukasIO Oct 16, 2026
3ef5505
fix(core): five review findings on the extension contract and the cor…
lukasIO Oct 16, 2026
6501533
fix(scripts): resolve the repo path with fileURLToPath so a path with…
lukasIO Oct 16, 2026
5aeee9f
remove dc encryption option from e2ee extension options
lukasIO Oct 16, 2026
2c99da2
remove deprecated APIs from core
lukasIO Oct 16, 2026
1e0ce9a
rename LocalApi to LocalParticipantApi
lukasIO Oct 16, 2026
5056f99
fix lint
lukasIO Oct 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/room-extensions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'livekit-client': minor
---

Split `Room` into `CoreRoom` plus extensions. `createRoom(options, [extensions])` from `livekit-client/core` builds a room with only the extensions an application needs; `e2ee`, `frameMetadata` and `dataStreams` take their options directly. `Room.dispose()` releases a room for good. Video publishing (camera, screen share, simulcast, SVC, backup codecs) is the `video` extension; receiving video stays in core. The new `livekit-client/core` entry (ESM only, experimental) exports `CoreRoom` and the extensions. `simulateParticipants` and the legacy chat messages are extensions too; the core entry does not offer legacy chat.
5 changes: 4 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -113,4 +113,7 @@ pkg/
bin/
examples/**/build/

.env.local
.env.local

# scratch dir of scripts/check-core-types.mjs
.tmp-core-types-*
6 changes: 6 additions & 0 deletions .size-limit.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,10 @@ module.exports = [
import: '{ Room }',
limit: '130 kB',
},
{
// the light entry (livekit-client/core) without any extension
path: 'dist/core/core.mjs',
import: '{ createRoom }',
limit: '85 kB',
},
];
83 changes: 83 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,89 @@ pnpm dev
The main demo app (`examples/demo/`) is a comprehensive kitchen-sink UI. Standalone examples
(`examples/rpc/`, `examples/data-tracks/`) focus on individual features.

## Room extensions

`Room` (the main export) is `CoreRoom` plus every extension, installed in its constructor through
`installExtensions()`. The core entry's `createRoom(options, [extensions])` does the same with the
list an app gives it.
`CoreRoom` (`src/room/CoreRoom.ts`) holds the signal client, engine, participants, media and
raw data packets. Everything else is a `RoomExtension` (`src/room/extensions.ts`) that
`installExtensions()` installs right after construction. `src/exports.ts` is the export surface both
entries share; `src/index.ts` adds `Room` and the type augmentations, `src/core.ts` adds
`CoreRoom` and the extension objects (`livekit-client/core`, experimental). The core entry is
built per module with dependencies external (`dist/core/`), so a consumer's bundler drops unused
modules whole; the main entry stays one self-contained bundle. `pnpm check:core` fails if
`CoreRoom` alone bundles an extension module, and `pnpm size-limit` tracks both entries.

- An extension is a plain object: `key`, optional `requires` (hard dependencies, installed first,
deduped by key), and `install(room, ctx)`. It lives in `extension.ts` next to its managers.
- `install` returns `{ room, local, dispose }`. `room` and `local` members are copied onto the
room and its local participant under the SDK's method names (`sendText`, `registerRpcMethod`).
Extra members (the managers) are visible to dependents through `ctx.get(extension)`.
- Extensions that take options (`e2ee`, `frameMetadata`, `dataStreams`) are built with
`defineExtension()` and are callable: listed bare they read today's `RoomOptions`, called with
options they use those, and a function is evaluated per room. Extensions without options are
plain objects. The resolver dedupes by key, installs dependencies first, lets an explicitly listed
instance win over a dependency's default, and throws when a key is listed twice.
- `install`, `dispose` and every hook are synchronous. Async setup starts in `install` and is
awaited in the extension's own methods.
- Core never reads an extension's slice of the room options (`e2ee`, `encryption`,
`frameMetadata`, `packetTrailer`, `dataStream`): a configured extension (`e2ee({ ... })`) does not
write them. What core needs comes through a context slot (`setFrameMetadataOptions`,
`setE2eeManager`), which the extension fills from its own options or, when listed bare, from
`RoomOptions`. `pnpm check:core` greps the core modules for such reads.
- A worker an app supplies to an extension is terminated in the extension's `dispose`, not on
disconnect: the room can connect again after a disconnect. The exception is a manager the app
passes in (`e2eeManager`): it can be shared between rooms, so the extension neither disposes
nor terminates it.
- Core calls out through `ExtensionContext` hooks only: `onEngineCreated` (the engine is replaced
after a close, so register engine listeners there), `onDataPacket` (one owner per `DataPacket`
case), `onDisconnect`, `onParticipantCreated`, `onParticipantUpdates`, `onSyncState`, and the
E2EE manager slot (`getE2eeManager` / `setE2eeManager` / `onE2eeManagerChanged`). Core owns
the slot because `RTCEngine` and the publish path read it. Prefer an existing `RoomEvent` over
a new hook.
- The full entry (`src/room/Room.ts`) augments `CoreRoom` and `LocalParticipant` with the
extension API interfaces via `declare module`, so the full build keeps its types wherever those
classes appear. Inside the SDK's own compilation this means core code can call extension
methods without a type error; `pnpm check:core` is the guard.
- Extension method bodies must be closures over the managers, never `this`-based: they are
copied onto instances with `Object.defineProperties`.
- The core declarations (`dist/core/types`) come from a program rooted at `src/core.ts`
(rollup `files: ['src/core.ts']`), so `src/index.ts` and its `declare module` augmentations are
not in it. That is the guard against the augmentations reaching a core consumer: tsc's
declaration emitter writes `import("../..")` for an inferred type whenever the index barrel is
in its program, and that import would type a `[rpc]` room as if every extension were installed.
Still, never import types from the barrel (`'../..'`, `'.'`) inside `src`. Inferred types on
exported values are fine. `pnpm check:core` compiles a consumer probe against declarations
emitted the same way and fails on a leak or a dangling reference.
- The core build emits its own declarations with `stripInternal` (`dist/core/types`); the main
entry keeps `@internal` members because components-js and React Native use some of them. Every
symbol a public signature names must therefore stay untagged (`ExtensionContext`,
`InternalRoomOptions`, the `RTCEngine` class), or the stripped declaration dangles. Tag members,
not the classes and interfaces that public types mention. `pnpm check:core` type-checks the
stripped declarations with `skipLibCheck` off and fails on a dangling reference.
- Operations that exist only for extensions live on `ExtensionContext`, not on `CoreRoom`:
`setLocalParticipantSlot()` (the `dataStreams` byte stream opener for the preconnect audio
buffer, the `video` publisher), `getOrCreateParticipant()` and `simulateConnected()`. The room
keeps the slots in one `LocalParticipantSlots` object that it hands to `LocalParticipant`.
`installExtensions()` is the only `@internal` member `CoreRoom` has for extensions.
- `Room.dispose()` disconnects, runs extension `dispose` in reverse order and removes the
`devicechange` listener. A disposed room cannot connect again.
- `simulateParticipants` is the `simulatedParticipants` extension (`src/room/simulated-participants/`);
it uses `ctx.simulateConnected()` and `ctx.getOrCreateParticipant()`.
`simulateScenario` stays in core. The legacy chat packets (`sendChatMessage`,
`RoomEvent.ChatMessage`) are the `chat` extension (`src/room/chat/`): the full `Room` installs it,
the core entry does not export it because text streams supersede it.
- Video publishing is the `video` extension (`src/room/video/`). Receiving video stays in core.
Core keeps type guards (`isLocalVideoTrack`) and instance method calls on video tracks, which
cost nothing; it must not import `LocalVideoTrack`, `publishUtils` or `facingMode` as values.
Two slots connect them: the `videoPublisher` slot on the local participant (the publish
pipeline for a video track: codec, encodings, layers, start bitrate, server codec fallback,
screen capture, set through `ctx.setLocalParticipantSlot`) and `setVideoCapture()` in
`track/create.ts` (how `createLocalTracks` builds a video track). The
full entry calls `registerVideoCapture()` at module load so `createLocalTracks({ video })` works
before any Room exists.

## Manager pattern

Managers (e.g. `RpcClientManager`, `RpcServerManager`, `OutgoingDataTrackManager`,
Expand Down
Loading