@cloudflare/realtimekit 1.2.5-staging.1 → 1.2.5-staging.3

package/AGENTS.md

@@ -0,0 +1,63 @@
+# 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.