# CORE PACKAGE KNOWLEDGE BASE

## OVERVIEW
`@cloudflare/realtimekit` — the WebRTC SDK engine; single default export `RealtimeKitClient`.

## STRUCTURE
```
core/
├── .config/          # 6 Vite build configs + build-types.sh + prepublish.js
├── src/              # All source (controllers, media, roomNode, socketService, e2ee, mock, …)
├── docs/             # Node-based API reference generator (jsdoc-to-markdown)
├── samples/          # Standalone transformer examples (audio/video middleware demos)
├── __mocks__/        # Vitest manual mocks: window globals + sockrates-client
└── dist/             # Build output (not committed; generated by build scripts)
```

## BUILD TARGETS

| Vite config | Output file(s) | Format | Purpose |
|-------------|---------------|--------|---------|
| `vite.config.ts` | `dist/index.es.js`, `dist/index.cjs.js` | ESM + CJS | Main tree-shakeable + CommonJS builds |
| `vite.iife.config.ts` | `dist/browser.js` | IIFE | Self-contained browser bundle; bundle diff tracked in CI |
| `vite.rn.config.ts` | `dist/index.rn.js` | CJS | React Native (keeps `@dyteinternals/mediasoup-client` as external) |
| `vite.es5.config.ts` | `dist/index.es5.js` | ESM+Babel | Babel-transpiled ES5-compatible output via `@babel/preset-env` |
| `vite.e2ee.es.ts` | `dist/EncryptionManager.{es,cjs}.js` | ESM + CJS | E2EE sub-module (`./e2ee` export path) |
| `vite.mock.es.ts` | `dist/ClientMock.{es,cjs}.js` | ESM + CJS | Mock client for testing (`./mock` export path); polyfills `events`+`buffer` |
| `build-types.sh` (tsup) | `dist/index.d.ts`, `dist/EncryptionManager.d.ts`, `dist/ClientMock.d.ts` | `.d.ts` | Type declarations via tsup `--dts-only`; strips `#private;` lines |

**Build order inside `core`:** All 6 Vite targets run in parallel via `concurrently`, then `build:types` runs, then `downlevel-dts`.

## EXPORT PATHS

| Export path | File | Consumers |
|-------------|------|-----------|
| `.` | `dist/index.es.js` / `dist/index.cjs.js` | Standard ESM/CJS imports |
| `./inlined` | `dist/browser.js` | Script-tag / CDN — all deps bundled in |
| `./compatible` | `dist/index.es5.js` | Legacy bundlers requiring ES5 |
| `./e2ee` | `dist/EncryptionManager.{es,cjs}.js` | Apps opting into E2EE encryption |
| `./mock` | `dist/ClientMock.{es,cjs}.js` | Test environments (no real WebRTC) |

TypeScript `<4.0` consumers are redirected to `dist/ts3.4/` via `typesVersions`.

## WHERE TO LOOK

| Task | Location |
|------|----------|
| Type declaration generation | `.config/build-types.sh` — strips `@dyte-in/*` deps before tsup, then strips `#private;` lines from `.d.ts` |
| Pre-publish package.json rewrite | `.config/prepublish.js` — removes private deps, injects `VERSION_PLACEHOLDER` into 4 dist files, sets npm tag from `ENVIRONMENT` env var |
| Post-publish restore | `package.json` backed up to `package.json.bak` before publish; restored via `postpublish` script |
| TS 3.4 compat types | `dist/ts3.4/` produced by `downlevel-dts dist dist/ts3.4/dist` after type build |
| Bundle analyzer | `stats.html` generated by `rollup-plugin-visualizer` when `VITE_ANALYZE=1` |
| Transformer samples | `samples/transformers/` — audio (low-pass, pitch, noise) + video middleware examples |
| API reference generator | `docs/api-reference-generator.js` — run via `npm run docs`; outputs Markdown from JSDoc |

## NOTES

- `dist/browser.js` is the IIFE bundle — CI tracks its size diff on every PR; do not add large dependencies to the main entry without expecting a size alert.
- `react-native` field in `package.json` (`./dist/index.rn.js`) is read by Metro bundler; it is a CJS build that keeps `@dyteinternals/mediasoup-client` external (unlike the main CJS build which inlines it).
- `build-types.sh` temporarily strips `@dyte-in*` / `@dyteinternals/*` from `package.json` so tsup resolves and bundles their types into the output `.d.ts`; `package.json` is restored via `trap restore EXIT`.
- `prepublish.js` strips `lodash-es` and all `@dyte-in*`/`@dyteinternals/*` (except `mediasoup-client`) from `dependencies` before publishing — these are inlined in the dist.
- `envPrefix: 'RTK_'` — only `RTK_*` env vars are exposed to Vite builds; use `RTK_` prefix for any new build-time flags.
- `vite.mock.es.ts` adds Node polyfills (`events`, `buffer`) because `ClientMock` runs in Node test environments.
- `vitest-github-coverage-provider.mts` — custom coverage reporter that emits GitHub-compatible annotations; only active in CI.