@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-angular-theming/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: cometchat-angular-theming
+description: "CometChatThemeService palette — color tokens, light/dark mode, typography, per-component style objects, and CSS variable overrides for the CometChat Angular UI Kit v4."
+license: "MIT"
+compatibility: "Angular >=12 <=15; @cometchat/chat-uikit-angular ^4; @cometchat/chat-sdk-javascript ^4"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory, AskUserQuestion"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat angular theming colors dark-mode typography palette css-variables"
+---
+
+## Purpose
+
+Teaches Claude how to theme the CometChat Angular UI Kit v4 via `CometChatThemeService` and per-component style objects. Covers palette tokens, light/dark mode switching, typography, per-component style classes, CSS variable overrides, and preset themes.
+
+**Read `cometchat-angular-core` first** — `CometChatThemeService` is injected in `AppComponent`'s constructor, which is covered there.
+
+Ground truth: `docs/ui-kit/angular/theme`, `docs/ui-kit/angular/colors`, `docs/ui-kit/angular/component-styling`, and `@cometchat/chat-uikit-angular@4.x` style exports.
+
+---
+
+## 0. Preset themes (quickest start)
+
+Five built-in presets. Apply by setting these CSS variables in `src/styles.scss` after any existing imports:
+
+| Preset | `--cometchat-primary-color` | `--cometchat-font-family` | `--cometchat-background-color-01` | `--cometchat-text-color-primary` | Notes |
+|---|---|---|---|---|---|
+| `slack` | `#611f69` | `Lato, sans-serif` | `#ffffff` | `#1d1c1d` | |
+| `whatsapp` | `#25d366` | `'Segoe UI', Helvetica, sans-serif` | `#f0f2f5` | `#111b21` | |
+| `imessage` | `#007aff` | `-apple-system, 'SF Pro Text', sans-serif` | `#ffffff` | `#000000` | |
+| `discord` | `#5865f2` | `'gg sans', 'Noto Sans', Helvetica, sans-serif` | `#36393f` | `#dcddde` | Dark mode built-in |
+| `notion` | `#2eaadc` | `-apple-system, Helvetica, sans-serif` | `#ffffff` | `#37352f` | |
+
+Example — apply the Slack preset:
+
+```scss
+/* src/styles.scss — after existing imports */
+:root {
+  --cometchat-primary-color: #611f69;
+  --cometchat-font-family: Lato, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --cometchat-background-color-01: #ffffff;
+  --cometchat-text-color-primary: #1d1c1d;
+}
+```
+
+Also set the matching `CometChatThemeService` palette so the Angular DI layer stays in sync:
+
+```typescript
+// AppComponent constructor:
+themeService.theme.palette.setPrimary({ light: "#611f69", dark: "#611f69" });
+```
+
+---
+
+## 1. How theming works in Angular
+
+The Angular UI Kit uses two mechanisms for theming:
+
+1. **`CometChatThemeService`** — Angular DI service that controls the global palette (primary color, mode). Inject once in `AppComponent`.
+2. **Per-component style objects** — typed style classes (`ConversationsStyle`, `MessageListStyle`, etc.) passed as `[*Style]` inputs to individual components.
+
+```
+CometChatThemeService (global palette)
+  ↓
+every <cometchat-*> component reads palette via the service
+  ↓
+component's default styles merge with palette + per-component style overrides
+```
+
+### Style precedence (highest to lowest)
+
+1. **Per-component `[*Style]` input** — wins always. Per-component tweak.
+2. **`CometChatThemeService` palette** — app-wide primary color + mode.
+3. **Default theme** — the UI Kit's built-in palette.
+
+---
+
+## 2. CometChatThemeService — global palette
+
+Inject in `AppComponent`'s constructor (not `ngOnInit` — the palette must be set before any component renders):
+
+```typescript
+import { Component } from "@angular/core";
+import { CometChatThemeService } from "@cometchat/chat-uikit-angular";
+
+@Component({ selector: "app-root", templateUrl: "./app.component.html" })
+export class AppComponent {
+  constructor(private themeService: CometChatThemeService) {
+    // Set mode
+    themeService.theme.palette.setMode("light");  // "light" | "dark"
+
+    // Set primary brand color (light + dark variants)
+    themeService.theme.palette.setPrimary({ light: "#6851D6", dark: "#6851D6" });
+
+    // Optional: set accent color
+    themeService.theme.palette.setAccent({ light: "#F76808", dark: "#FF8A3D" });
+  }
+}
+```
+
+### Dynamic mode switching
+
+```typescript
+@Component({ /* ... */ })
+export class AppComponent {
+  constructor(private themeService: CometChatThemeService) {}
+
+  toggleDarkMode(isDark: boolean): void {
+    this.themeService.theme.palette.setMode(isDark ? "dark" : "light");
+  }
+}
+```
+
+The palette change propagates to all rendered CometChat components immediately — no page reload needed.
+
+---
+
+## 3. Color tokens
+
+### Primary (brand accent)
+
+| Method | Controls |
+|---|---|
+| `setPrimary({ light, dark })` | Outgoing message bubbles, send button, active tabs, buttons |
+| `setAccent({ light, dark })` | Secondary accent — links, highlights |
+
+Both methods take `{ light: "#hex", dark: "#hex" }`. Always provide both variants.
+
+### Mode
+
+| Mode | Effect |
+|---|---|
+| `"light"` | Light backgrounds, dark text |
+| `"dark"` | Dark backgrounds, light text |
+
+### Palette methods reference
+
+```typescript
+themeService.theme.palette.setMode("light" | "dark");
+themeService.theme.palette.setPrimary({ light: "#hex", dark: "#hex" });
+themeService.theme.palette.setAccent({ light: "#hex", dark: "#hex" });
+themeService.theme.palette.setBackground({ light: "#hex", dark: "#hex" });
+themeService.theme.palette.setSecondary({ light: "#hex", dark: "#hex" });
+```
+
+---
+
+## 4. Per-component style objects
+
+Each component accepts a typed style object. Import from `@cometchat/uikit-shared`:
+
+```typescript
+import {
+  ConversationsStyle,
+  MessagesStyle,
+  MessageListStyle,
+  MessageComposerStyle,
+  MessageHeaderStyle,
+  UsersStyle,
+  GroupsStyle,
+  AvatarStyle,
+  BadgeStyle,
+  StatusIndicatorStyle,
+  ListItemStyle,
+  DateStyle,
+  BackdropStyle,
+  ConfirmDialogStyle,
+  LoaderStyle,
+} from "@cometchat/uikit-shared";
+```
+
+### ConversationsStyle
+
+```typescript
+conversationsStyle = new ConversationsStyle({
+  width: "100%",
+  height: "100%",
+  border: "1px solid #e8e8e8",
+  borderRadius: "8px",
+  background: "#ffffff",
+  titleTextFont: "600 18px Inter, sans-serif",
+  titleTextColor: "#141414",
+  lastMessageTextFont: "400 14px Inter, sans-serif",
+  lastMessageTextColor: "#727272",
+  typingIndictorTextColor: "#6851D6",
+  onlineStatusColor: "#09C26F",
+  privateGroupIconBackground: "#F76808",
+  passwordGroupIconBackground: "#FFAB00",
+});
+```
+
+```html
+<cometchat-conversations [conversationsStyle]="conversationsStyle"></cometchat-conversations>
+```
+
+### MessageListStyle
+
+```typescript
+messageListStyle = new MessageListStyle({
+  width: "100%",
+  height: "100%",
+  background: "#fafafa",
+  border: "none",
+  // Bubble colors
+  sendBubbleBackground: "#6851D6",
+  sendBubbleTextColor: "#ffffff",
+  sendBubbleTextFont: "400 15px Inter, sans-serif",
+  receiveBubbleBackground: "#f0f0f0",
+  receiveBubbleTextColor: "#141414",
+  receiveBubbleTextFont: "400 15px Inter, sans-serif",
+});
+```
+
+### MessageComposerStyle
+
+```typescript
+messageComposerStyle = new MessageComposerStyle({
+  width: "100%",
+  background: "#ffffff",
+  border: "1px solid #e8e8e8",
+  borderRadius: "0",
+  inputBackground: "#f5f5f5",
+  inputBorder: "none",
+  inputBorderRadius: "8px",
+  textFont: "400 15px Inter, sans-serif",
+  textColor: "#141414",
+  placeHolderTextColor: "#a1a1a1",
+  sendIconTint: "#6851D6",
+  attachmentIconTint: "#727272",
+});
+```
+
+### AvatarStyle
+
+```typescript
+avatarStyle = new AvatarStyle({
+  width: "40px",
+  height: "40px",
+  border: "none",
+  borderRadius: "50%",
+  backgroundColor: "#6851D6",
+  nameTextColor: "#ffffff",
+  nameTextFont: "600 16px Inter, sans-serif",
+  backgroundSize: "cover",
+});
+```
+
+### BadgeStyle
+
+```typescript
+badgeStyle = new BadgeStyle({
+  background: "#6851D6",
+  textColor: "#ffffff",
+  textFont: "600 11px Inter, sans-serif",
+  border: "none",
+  borderRadius: "10px",
+  width: "20px",
+  height: "20px",
+});
+```
+
+---
+
+## 5. Common theming recipes
+
+### Match a brand color (most common)
+
+```typescript
+// In AppComponent constructor:
+themeService.theme.palette.setPrimary({ light: "#FF6B35", dark: "#FF8F66" });
+```
+
+This single call changes the outgoing message bubble color, send button, active tab indicator, and every primary accent in the UI.
+
+### Dark mode + custom brand
+
+```typescript
+themeService.theme.palette.setMode("dark");
+themeService.theme.palette.setPrimary({ light: "#6851D6", dark: "#A594F3" });
+themeService.theme.palette.setBackground({ light: "#ffffff", dark: "#1a1a1a" });
+```
+
+### Custom message bubble colors
+
+```typescript
+messageListStyle = new MessageListStyle({
+  sendBubbleBackground: "#FF6B35",
+  sendBubbleTextColor: "#ffffff",
+  receiveBubbleBackground: "#f0f0f0",
+  receiveBubbleTextColor: "#1a1a1a",
+});
+```
+
+### Custom font across the whole UI
+
+The Angular UI Kit reads font from CSS. Override via global styles:
+
+```css
+/* styles.css (global) */
+:root {
+  --cometchat-font-family: "Inter", sans-serif;
+}
+```
+
+Or pass `textFont` / `titleTextFont` in each component's style object.
+
+---
+
+## 6. CSS variable overrides
+
+The Angular UI Kit exposes CSS custom properties for fine-grained control. Override in `styles.css` (global):
+
+```css
+/* styles.css */
+:root {
+  /* Primary color */
+  --cometchat-primary-color: #6851D6;
+
+  /* Background colors */
+  --cometchat-background-color-01: #ffffff;
+  --cometchat-background-color-02: #fafafa;
+  --cometchat-background-color-03: #f5f5f5;
+
+  /* Text colors */
+  --cometchat-text-color-primary: #141414;
+  --cometchat-text-color-secondary: #727272;
+  --cometchat-text-color-tertiary: #a1a1a1;
+
+  /* Border */
+  --cometchat-border-color-default: #e8e8e8;
+
+  /* Font */
+  --cometchat-font-family: "Inter", sans-serif;
+}
+```
+
+CSS variable overrides apply globally and take effect immediately. Use them for app-wide changes that the `CometChatThemeService` palette methods don't cover.
+
+---
+
+## 7. Anti-patterns
+
+1. **Do NOT call `themeService.theme.palette.setMode()` in `ngOnInit`.** Call it in the constructor — the palette must be set before any CometChat component renders. `ngOnInit` runs after the first change detection cycle, which may be too late.
+
+2. **Do NOT mix `CometChatThemeService` and per-component `[*Style]` for the same property.** The per-component style wins — the service override becomes dead code. Pick one: service for app-wide, `[*Style]` for one-offs.
+
+3. **Do NOT use non-hex colors in style objects.** Some style properties expect hex strings. `rgb()` / named colors / `hsl()` may not work in all style properties.
+
+4. **Do NOT wrap `CometChatThemeService` injection in a lazy-loaded module.** The service is a singleton — inject it at the root level (`AppComponent`) so the palette is set before any component renders.
+
+5. **Do NOT forget to provide both `light` and `dark` variants** when calling `setPrimary()` or `setAccent()`. Providing only one variant leaves the other as the default, which may not match your brand in dark mode.
+
+---
+
+## Skill routing reference
+
+| Skill | When to route |
+|---|---|
+| `cometchat-angular-core` | Init, login, module setup — always first |
+| `cometchat-angular-components` | Per-component `[*Style]` prop reference |
+| `cometchat-angular-placement` | Where to put chat |
+| `cometchat-angular-theming` | This skill — palette, dark mode, typography |
+| `cometchat-angular-customization` | Custom slot views, formatters |
+| `cometchat-angular-troubleshooting` | Colors not applying, dark mode not switching |

package/skills/cometchat-angular-troubleshooting/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: cometchat-angular-troubleshooting
+description: "Diagnose CometChat Angular UI Kit v4 integration failures — init/login, CUSTOM_ELEMENTS_SCHEMA, assets config, module imports, height/layout issues, Angular Universal SSR, v3-to-v4 upgrade, and production auth errors."
+license: "MIT"
+compatibility: "Angular >=12 <=15; @cometchat/chat-uikit-angular ^4; @cometchat/chat-sdk-javascript ^4"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory, AskUserQuestion"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat angular troubleshooting schema assets module height ssr upgrade"
+---
+
+## Purpose
+
+Teaches Claude how to diagnose and fix CometChat Angular UI Kit v4 integration failures. Covers every category of failure across NgModule and standalone component setups, with an up-front triage flow so Claude asks the right questions before assuming a fix.
+
+**Read `cometchat-angular-core` first** — most "why doesn't this work" issues trace to the init/login/module setup explained there.
+
+Ground truth: `docs/ui-kit/angular/troubleshooting`, `docs/ui-kit/angular/getting-started`, and first-hand failure modes from real integrations.
+
+---
+
+## 1. Triage — read project state before guessing
+
+When the user reports a problem, gather facts before proposing a fix.
+
+### 1a. Is `CUSTOM_ELEMENTS_SCHEMA` in every module that uses `<cometchat-*>` tags?
+
+```bash
+grep -r "CUSTOM_ELEMENTS_SCHEMA" src/
+```
+
+If missing from any module or standalone component that uses `<cometchat-*>` tags, Angular throws "Unknown element" errors. Every module/component needs it independently.
+
+### 1b. Are the assets configured in `angular.json`?
+
+```bash
+grep -A5 '"assets"' angular.json | grep cometchat
+```
+
+If missing, icons render as broken images. The required entry:
+```json
+{ "glob": "**/*", "input": "./node_modules/@cometchat/chat-uikit-angular/assets/", "output": "assets/" }
+```
+
+### 1c. Is init complete before any `<cometchat-*>` component renders?
+
+```bash
+grep -n "CometChatUIKit.init\|isReady\|APP_INITIALIZER" src/app/app.component.ts
+```
+
+Look for the init promise + `isReady` flag or `APP_INITIALIZER`. Components rendered before init completes produce blank output.
+
+### 1d. Is `UIKitSettingsBuilder` used (not a flat object)?
+
+```bash
+grep -n "UIKitSettingsBuilder\|CometChatUIKit.init" src/
+```
+
+Angular requires `UIKitSettingsBuilder` from `@cometchat/uikit-shared`. A flat object passed to `init()` fails silently or throws a type error.
+
+### 1e. Are CometChat components imported in the module?
+
+```bash
+grep -n "CometChatConversations\|CometChatMessages\|CometChatMessageList" src/app/app.module.ts
+```
+
+Every `<cometchat-*>` component must be imported in the module (or standalone component) where it's used.
+
+### 1f. Is `BrowserAnimationsModule` imported?
+
+```bash
+grep "BrowserAnimationsModule" src/app/app.module.ts
+```
+
+Missing `BrowserAnimationsModule` causes runtime errors in components that use Angular animations.
+
+---
+
+## 2. Symptom → fix lookup tables
+
+### 2a. Initialization + login
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Components render nothing after login | `init()` not awaited before mount | Use `*ngIf="isReady"` on the container; set `isReady = true` after init + login resolve |
+| Blank screen, no errors | Component rendered before init completed | Gate with `*ngIf="isReady"` |
+| `getLoggedinUser()` returns `null` | Login not called or session expired | Call `CometChatUIKit.login({ uid })` after init resolves |
+| Login fails: "UID not found" | User doesn't exist in CometChat | Create via dashboard, SDK, or REST API. For dev, use `cometchat-uid-1` through `cometchat-uid-5` |
+| `CometChatUIKit.init()` fails silently | Invalid `APP_ID` / `REGION` / `AUTH_KEY` | Re-verify from dashboard → your app → Credentials |
+| `UIKitSettingsBuilder is not a constructor` | Imported from wrong package | Import from `@cometchat/uikit-shared`, not `@cometchat/chat-uikit-angular` |
+| Production build exposes Auth Key | Using `authKey` in `environment.prod.ts` | Switch to server-minted auth tokens. See `cometchat-angular-production` |
+
+### 2b. Module / schema errors
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `'cometchat-conversations' is not a known element` | Missing `CUSTOM_ELEMENTS_SCHEMA` | Add `schemas: [CUSTOM_ELEMENTS_SCHEMA]` to the module or standalone component |
+| `'cometchat-conversations' is not a known element` (even with schema) | Component not imported in the module | Import `CometChatConversations` from `@cometchat/chat-uikit-angular` in the module's `imports` array |
+| `Can't bind to 'user' since it isn't a known property` | Component not imported | Same fix — import the component in the module |
+| `NullInjectorError: No provider for CometChatThemeService` | `CometChatThemeService` not available | It's `providedIn: 'root'` — ensure `AppModule` is the root module. If using standalone bootstrap, ensure `provideAnimations()` is in providers. |
+| `BrowserAnimationsModule` error | Missing animation module | Add `BrowserAnimationsModule` to `AppModule` imports |
+
+### 2c. Assets / icons
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Icons show as broken images (404) | Missing assets config in `angular.json` | Add the glob entry for `@cometchat/chat-uikit-angular/assets/` to `build.options.assets` |
+| Icons broken only in production build | Assets config present but `outputPath` differs | Verify the `output` path in the assets config matches your production output directory |
+| Icons broken after `ng build` | Assets not copied during build | Run `ng build` again after adding the assets config; check `dist/assets/` for the icon files |
+
+### 2d. Layout / height issues
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Conversation list / message list renders empty | Container has no bounded height | Wrap in `<div style="height: 100vh;">` or `<div style="flex: 1; overflow: hidden;">` |
+| Components collapse to zero height | Parent is a `display: block` with no height | Use `display: flex; flex-direction: column; height: 100vh` on the parent |
+| Message list doesn't scroll | Container doesn't have `overflow: hidden` | Add `overflow: hidden` to the message list's container; the component handles its own internal scroll |
+| Chat dialog too small | Angular Material dialog has no explicit size | Set `width` and `height` on the dialog container or pass `{ width: '480px', height: '600px' }` to `MatDialog.open()` |
+| Sidebar chat panel has no height | Sidenav content has no height constraint | Add `height: 100%` or `height: 100vh` to the sidenav content |
+
+### 2e. Angular Router integration
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Chat route shows blank | CometChat init not complete when route activates | Use `APP_INITIALIZER` or a route guard that waits for init |
+| `window.location.reload()` after login breaks routing | Anti-pattern — reload destroys Angular state | Use `this.router.navigate(['/chat'])` instead |
+| Lazy-loaded chat module fails to init | `CometChatUIKit.init()` called inside the lazy module | Move init to `APP_INITIALIZER` at the root level |
+| Route guard `canActivate` always returns false | `getLoggedinUser()` called before init | Ensure init completes before the guard runs (use `APP_INITIALIZER`) |
+
+### 2f. Theming
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Theme overrides don't apply | `setPrimary()` called in `ngOnInit` instead of constructor | Move to constructor — palette must be set before first render |
+| Dark mode doesn't switch | `setMode()` called once but not reactive | Call `setMode()` again when the user toggles; the service is reactive |
+| Custom color shows as default | Color not a valid CSS color string | Use valid CSS color values (`#hex`, `rgb()`, named colors) |
+| `[conversationsStyle]` input has no effect | Style object not instantiated with `new ConversationsStyle({...})` | Use `new ConversationsStyle({...})` — don't pass a plain object |
+
+### 2g. Components
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Slot view (`[listItemView]`, `[subtitleView]`, etc.) renders nothing | `@ViewChild` reference not resolved yet | Ensure `@ViewChild` is accessed after `ngAfterViewInit`, not `ngOnInit` |
+| `[onItemClick]` callback not firing | Wrong binding syntax — using round brackets | Use `[onItemClick]="myFn"` (square brackets, Input callback), never `(onItemClick)="myFn($event)"` (round brackets) |
+| `[user]` input has no effect | Passing a UID string instead of `CometChat.User` instance | `await CometChat.getUser(uid)` first, pass the resolved object |
+| Conversations list empty but data exists | Wrong request builder filters | Check `[conversationsRequestBuilder]` filters (tags, types, limits) |
+| "Reply in Thread" option does nothing | Thread panel not wired | Wire `[onThreadRepliesClick]="myFn"` on `<cometchat-message-list>` and render a thread panel — see `cometchat-angular-components` § 11 |
+| `[onError]` callback fires with "not initialized" | Component rendered before init | Gate with `*ngIf="isReady"` |
+
+### 2h. Calling
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Call buttons missing | `@cometchat/calls-sdk-javascript` not installed | `npm install @cometchat/calls-sdk-javascript` + rebuild |
+| Incoming call UI doesn't show | `<cometchat-incoming-call>` not mounted or listener not registered | Register `CometChat.addCallListener(...)` in `AppComponent.ngOnInit` and mount `<cometchat-incoming-call>` at the app root |
+| Call listener fires twice | Listener registered in a component that gets destroyed and re-created | Move listener registration to `AppComponent` (root, never destroyed) |
+
+### 2i. Extensions
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Polls option missing from composer | Extension not enabled in dashboard | `cometchat features enable polls --json` or toggle in dashboard → Features |
+| Extension enabled but UI doesn't appear | Cached session — hard reload needed | Stop `ng serve`, clear browser cache, restart |
+| Extension says enabled but `auto_wired_in_uikit: false` | Needs `.setExtensions([...])` on `UIKitSettingsBuilder` | Add `new PollsExtension()` etc. to the builder — see `cometchat-angular-features` § 2 |
+
+### 2j. Production / auth tokens
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `login({ authToken })` fails: "user does not exist" | User not created in CometChat before token mint | Create user server-side via REST API on your signup flow. See `cometchat-angular-production` § 6 |
+| Token endpoint returns 401 | Backend auth check failing | Verify `Authorization: Bearer <jwt>` header is attached to the Angular `HttpClient` request |
+| 429 rate limit on token endpoint | Minting tokens too often (e.g. per component init) | Cache client-side, reuse until expiry |
+| `CometChatUIKit.loginWithAuthToken` not found | Wrong API name | It's `CometChatUIKit.login({ authToken })` — same method as dev, different key |
+
+### 2k. SSR / Angular Universal
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `window is not defined` during SSR | CometChat uses browser APIs | Guard with `isPlatformBrowser(platformId)` — see `cometchat-angular-patterns` § 7 |
+| `document is not defined` during SSR | Same cause | Same fix |
+| Components render on server but throw | CometChat components use browser APIs | Wrap `<cometchat-*>` tags with `*ngIf="isBrowser"` |
+
+---
+
+## 3. Deep dives on common failures
+
+### 3a. "The most common 'why is my chat blank' bug"
+
+CometChat components fill 100% of their parent's height. If the parent has no bounded height, the components render at 0px and look empty.
+
+Diagnostic:
+
+```bash
+# Check the parent container of the CometChat component
+grep -B5 "cometchat-message-list\|cometchat-conversations" src/app/**/*.html
+```
+
+Look for the component's parent. One of these must be true:
+- Parent has `height: 100vh` or `height: 100%`
+- Parent is a flex column with the component getting `flex: 1`
+- Parent has an explicit `height: Npx`
+
+Broken example:
+```html
+<!-- ✗ WRONG — div has no height -->
+<div>
+  <cometchat-message-list [user]="selectedUser"></cometchat-message-list>
+</div>
+```
+
+Fixed:
+```html
+<!-- ✓ RIGHT -->
+<div style="height: 100vh; display: flex; flex-direction: column;">
+  <cometchat-message-list
+    [user]="selectedUser"
+    style="flex: 1; overflow: hidden;"
+  ></cometchat-message-list>
+</div>
+```
+
+### 3b. "Unknown element" errors for `<cometchat-*>` tags
+
+Two separate fixes are both required:
+
+1. **Import the component** in the module's `imports` array:
+   ```typescript
+   import { CometChatConversations } from "@cometchat/chat-uikit-angular";
+   @NgModule({ imports: [CometChatConversations] })
+   ```
+
+2. **Add `CUSTOM_ELEMENTS_SCHEMA`** to the module's `schemas`:
+   ```typescript
+   import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+   @NgModule({ schemas: [CUSTOM_ELEMENTS_SCHEMA] })
+   ```
+
+Both are required. Missing either one produces the "Unknown element" error.
+
+### 3c. Components render before init completes
+
+The most reliable fix is `APP_INITIALIZER` (see `cometchat-angular-patterns` § 1). If not using `APP_INITIALIZER`, use `*ngIf="isReady"`:
+
+```typescript
+// app.component.ts
+isReady = false;
+
+ngOnInit(): void {
+  CometChatUIKit.init(settings)
+    .then(() => CometChatUIKit.getLoggedinUser())
+    .then((user) => user || CometChatUIKit.login({ uid: "cometchat-uid-1" }))
+    .then(() => (this.isReady = true))
+    .catch(console.error);
+}
+```
+
+```html
+<!-- app.component.html -->
+<ng-container *ngIf="isReady">
+  <router-outlet></router-outlet>
+</ng-container>
+```
+
+---
+
+## 4. v3 → v4 upgrade gotchas
+
+If the user is upgrading from `@cometchat/chat-uikit-angular@3`, these are the common breakages.
+
+| v3 | v4 | Notes |
+|---|---|---|
+| `CometChatTheme` class | `CometChatThemeService` (Angular DI) | Theme is now an injectable service |
+| `CometChatConversationsWithMessages` composite | Still available but configuration API changed | Check `[conversationsConfiguration]` + `[messagesConfiguration]` props |
+| `theme` prop on components | Theme via `CometChatThemeService` only | Per-component theme prop removed |
+| `onClick` callback names | `onItemClick` callback names | Renamed for consistency |
+| `CometChat.login(uid, authKey)` | `CometChatUIKit.login({ uid })` | Object-form argument |
+| Flat settings object | `UIKitSettingsBuilder` | Builder pattern required |
+
+### Upgrade sequence
+
+```bash
+# 1. Update the main kit
+npm install @cometchat/chat-uikit-angular@latest
+
+# 2. Update peer packages
+npm install @cometchat/uikit-elements@latest @cometchat/uikit-resources@latest @cometchat/uikit-shared@latest
+
+# 3. Replace flat settings object with UIKitSettingsBuilder
+# 4. Replace CometChatTheme class with CometChatThemeService injection
+# 5. Rename onClick → onItemClick throughout templates
+# 6. Add CUSTOM_ELEMENTS_SCHEMA to all modules (new requirement in v4)
+# 7. Add assets config to angular.json (new requirement in v4)
+# 8. Rebuild + test
+```
+
+---
+
+## 5. Escalation — when the above doesn't solve it
+
+1. **Read the raw error.** Angular errors are usually specific — "Can't bind to 'user'" is different from "NullInjectorError".
+2. **Check the browser console + Angular DevTools.** Angular DevTools shows the component tree and change detection state.
+3. **Search the upstream docs MCP** (`cometchat-docs` if installed).
+4. **If the issue is a kit bug**, file at https://github.com/cometchat/cometchat-uikit-angular/issues with a minimal repro.
+
+---
+
+## 6. Hard rules (diagnostic best-practice)
+
+1. **Don't assume — triage first.** § 1 gets the schema, assets, init state, and module imports before proposing a fix.
+2. **Don't suggest "try reinstalling node_modules" as a first step.** Check the schema, assets config, and module imports first.
+3. **When recommending a rebuild, say why + what to rebuild.** "`ng build` after adding assets config" is more useful than "try rebuilding."
+4. **Never guess a fix that requires code changes without first gathering facts.**
+
+---
+
+## Skill routing reference
+
+| Skill | When to route |
+|---|---|
+| `cometchat-angular-core` | Most "doesn't work" bugs trace back here — init/login/module setup |
+| `cometchat-angular-components` | Wrong input / slot view / request builder |
+| `cometchat-angular-placement` | Blank chat / bounded-height issues |
+| `cometchat-angular-patterns` | Route guard, lazy loading, SSR, APP_INITIALIZER |
+| `cometchat-angular-theming` | Theme not applying, dark mode not switching |
+| `cometchat-angular-features` | Calls don't work, extension UI missing after enable |
+| `cometchat-angular-customization` | Formatter not rendering, listener not firing, template not showing |
+| `cometchat-angular-production` | 401 on token fetch, user-does-not-exist on login |
+| `cometchat-angular-troubleshooting` | This skill — cross-category diagnosis + v3→v4 upgrade |