realtimekit-ui

# PROJECT KNOWLEDGE BASE

**Generated:** 2026-02-25  
**Commit:** 2557985  
**Branch:** sm/agents-md

## OVERVIEW

Stencil.js Web Components UI kit for Cloudflare RealtimeKit (RTK), published as `@cloudflare/realtimekit-ui`. Framework wrappers for React and Angular are auto-generated by Stencil output targets on every build; the Vue wrapper is **deprecated and unsupported**.

## STRUCTURE

```
realtimekit-ui/
├── packages/core/            # Source of truth — 136 Stencil Web Components
├── packages/react-library/   # Auto-generated React proxies (@stencil/react-output-target)
├── packages/angular-library/ # Auto-generated Angular directives (@stencil/angular-output-target)
├── packages/vue-library/     # Deprecated — not supported
├── scripts/                  # Docs generation + emoji processing
├── .github/workflows/        # CI: lint, test, release, cross-repo docs PR
└── .releaserc.js             # semantic-release config (Lerna publish after release)
```

## WHERE TO LOOK

| Task                      | Location                                                                            |
| ------------------------- | ----------------------------------------------------------------------------------- |
| Add/modify a component    | `packages/core/src/components/rtk-<name>/`                                          |
| Shared library modules    | `packages/core/src/lib/` — audio, grid, i18n, icons, render engine, builder, addons |
| Utility functions + store | `packages/core/src/utils/` — ~29 files; store lives in `sync-with-store/`           |
| TypeScript types          | `packages/core/src/types/` — `UIConfig`, `States`, `DesignTokens`, `Peer`           |
| Tailwind / CSS tokens     | `packages/core/src/theme/` — all colors backed by `--rtk-*` CSS custom props        |
| Public API surface        | `packages/core/src/exports.ts` — everything consumers import                        |
| Default component tree    | `packages/core/src/lib/default-ui-config.ts`                                        |
| Stencil + build config    | `packages/core/stencil.config.ts`, `packages/core/rollup.config.mjs`                |
| Release pipeline          | `.releaserc.js` + `.github/workflows/release.yml`                                   |

## CODE MAP

| Symbol                        | Type                  | Location                                              | Role                                                  |
| ----------------------------- | --------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
| `rtk-meeting`                 | Web Component         | `packages/core/src/components/rtk-meeting/`           | Top-level shell; owns peer store, routes screens      |
| `rtk-ui-provider`             | Web Component         | `packages/core/src/components/rtk-ui-provider/`       | Headless store provider for composable usage          |
| `uiStore` / `createPeerStore` | Store                 | `packages/core/src/utils/sync-with-store/ui-store.ts` | Reactive state; per-peer store for multi-instance     |
| `@SyncWithStore()`            | Decorator             | `packages/core/src/utils/sync-with-store/index.ts`    | Wires component props to the reactive store           |
| `Render` / `RenderChildren`   | Functional components | `packages/core/src/lib/render/index.tsx`              | UIConfig-driven rendering engine                      |
| `createDefaultConfig`         | Function              | `packages/core/src/lib/default-ui-config.ts`          | Returns fresh mutable default `UIConfig`              |
| `RtkUiBuilder`                | Class                 | `packages/core/src/lib/builder/index.ts`              | Fluent API for mutating `UIConfig`                    |
| `registerAddons`              | Function              | `packages/core/src/lib/addons/index.ts`               | Applies addon plugins sequentially to a config        |
| `useLanguage`                 | Function              | `packages/core/src/lib/lang/index.ts`                 | Creates locale-aware `RtkI18n` lookup function        |
| `defaultIconPack`             | Object                | `packages/core/src/lib/icons/default-icon-pack.ts`    | ~70 inline SVG strings; merge-overridable             |
| `generateConfig`              | Function              | `packages/core/src/utils/config.ts`                   | Converts legacy `RTKThemePreset` → `UIConfig`         |
| `sendNotification`            | Function              | `packages/core/src/utils/notification.ts`             | Fires toast notification via DOM event                |
| `useGrid`                     | Function              | `packages/core/src/lib/grid.ts`                       | Computes tile dimensions/positions for N participants |

## CONVENTIONS

**Component naming:** All Stencil components use `rtk-` prefix. Tag: `rtk-foo-bar`. Class: `RtkFooBar`. File: `rtk-foo-bar.tsx`. Always Shadow DOM (`shadow: true`).

**Standard prop block:** Every component that needs store data declares these props in this order, each with `@SyncWithStore()` BEFORE `@Prop()`:

```ts
@SyncWithStore() @Prop() meeting: Meeting;
@SyncWithStore() @Prop() config: UIConfig = createDefaultConfig();
@SyncWithStore() @Prop() iconPack: IconPack = defaultIconPack;
@SyncWithStore() @Prop() t: RtkI18n = useLanguage();
@SyncWithStore() @Prop() states: States;
@SyncWithStore() @Prop() overrides: Overrides = defaultOverrides;
```

**Reflected props:** Visual props (`size`, `variant`, `kind`) use `@Prop({ reflect: true })` so CSS can target `:host([size='sm'])`.

**Events:** Child components emit `rtkStateUpdate` (singular). Only `rtk-meeting` / `rtk-ui-provider` emit `rtkStatesUpdate` (plural). Event names are `camelCase` with `rtk` prefix.

**Tailwind variants:** Custom `size-sm:`, `size-md:`, `size-lg:`, `size-xl:` variants target `:host([size='X'])` attributes — not standard media queries. `preflight: false` — Shadow DOM manages its own baseline.

**Branching:** PRs always target `staging` (NOT `main`). `staging` → pre-release publish. `main` → production release.

**Commits:** Conventional Commits enforced by commitlint + Commitizen. `feat:` bumps MINOR, `fix:` bumps PATCH. Pre-commit hook auto-runs `lint:fix`.

**Code style:** `singleQuote: true`, `printWidth: 100`, `tabWidth: 2`, `trailingComma: 'es5'`. Tailwind class order auto-sorted by Prettier.

## ANTI-PATTERNS (THIS PROJECT)

- **Never** emit `rtkStatesUpdate` from child components — only `rtk-meeting` does this.
- **Never** omit `@SyncWithStore()` on standard store props (`meeting`, `config`, `iconPack`, `t`, `states`, `overrides`) in new components.
- **Never** add `addListener` without a matching `removeListener` in `disconnectedCallback` — causes memory leaks.
- **Never** use `.bind()` in JSX props — `react/jsx-no-bind` forbids it; store bound handlers as arrow-function class fields.
- **Never** add `console.log` to component code without `/* eslint-disable no-console */` guards.
- **Never** export `const enum` without `// eslint-disable-next-line @stencil-community/ban-exported-const-enums`.
- **Never** target `main` in PRs — always `staging` first.
- **Never** call `UIElemEditor.style`, `.setChildrenProps()`, `.getChildrenProps()`, `.replace()` — unimplemented stubs.
- **Never** edit files in `packages/*/src/*/stencil-generated/` by hand — auto-overwritten on build.

## KNOWN INCOMPLETE / WORKAROUNDS

- `rtk-broadcast-message-modal.sendMessage()` — does not call any real API; shows a fake success after 2s.
- `lib/builder`: `UIElemEditor.style/setChildrenProps/getChildrenProps/replace` are stubs that only `console.log`.
- `rtk-grid.tsx` `filterParticipants()` uses `overrides.videoUnsubscribed` as a temp hack.
- Vue library is deprecated and unsupported — do not add new components to `packages/vue-library/lib/components.ts`.
- `peerDepdendencies` (misspelled) in `packages/core/package.json:55` is silently ignored by npm.

## COMMANDS

```bash
npm install               # Install all workspaces
npm run dev               # Dev server (core package only)
npm run build             # Build all packages
npm test                  # Stencil spec + e2e tests
npm run lint              # Lint all packages
npm run lint:fix          # Lint + auto-fix
npm run docs:generate     # Generate TypeDoc API reference markdown
```