@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-angular-v5-placement/references/combined-app.md

@@ -0,0 +1,174 @@
+# Combined app — the grow target
+
+Load this only when the user asks for the whole chat application: a tabbed selector (chats · users · groups · calls), the message pane, and details/thread panels.
+
+Built on `core-surface.md` — the shell, `ChatStateService` wiring, teardown and responsive rules are identical. This adds the tab selector and the details panel.
+
+> **Carry the whole core surface over, not just the shell.** `chat-experience`'s contract is a SUPERSET of `core-chat-surface`, so everything core-surface.md wires comes too — including **search** (`side-panel-or-column-search`: the toggle + `<cometchat-search>` in the list column) and the **thread panel**. Dropping search because this file does not repeat it is the easy mistake: this file shows only the DELTA.
+
+## Tabs
+```ts
+type Tab = 'chats' | 'users' | 'groups' | 'calls';
+
+export class ChatAppComponent {
+  readonly tab = signal<Tab>('chats');
+  readonly showDetails = signal(false);
+
+  // THREE handlers, not one. `(itemClick)` emits a different type per list:
+  //   cometchat-conversations → Conversation   (needs discriminating — see core-surface.md open())
+  //   cometchat-users         → User
+  //   cometchat-groups        → Group
+  // Routing users/groups through open() fails the build:
+  //   TS2345: Argument of type 'User' is not assignable to parameter of type 'Conversation'.
+  openUser(user: CometChat.User) { this.chatState.setActiveUser(user); }
+  openGroup(group: CometChat.Group) { this.chatState.setActiveGroup(group); }
+}
+```
+```html
+<aside class="cc-side">
+  <nav class="cc-tabs">
+    <button (click)="tab.set('chats')"  [class.active]="tab() === 'chats'">Chats</button>
+    <button (click)="tab.set('users')"  [class.active]="tab() === 'users'">Users</button>
+    <button (click)="tab.set('groups')" [class.active]="tab() === 'groups'">Groups</button>
+    <button (click)="tab.set('calls')"  [class.active]="tab() === 'calls'">Calls</button>
+  </nav>
+
+  <cometchat-conversations class="cc-fill" *ngIf="tab() === 'chats'"  (itemClick)="open($event)"></cometchat-conversations>
+  <cometchat-users         class="cc-fill" *ngIf="tab() === 'users'"  (itemClick)="openUser($event)"></cometchat-users>
+  <cometchat-groups        class="cc-fill" *ngIf="tab() === 'groups'" (itemClick)="openGroup($event)"></cometchat-groups>
+  <!-- Wire the calls tab too, or clicking a log dead-ends (RULES.md wire-or-hide). -->
+  <!-- ⚠️ GATE the call-logs surface on callsReady(): the kit's call-logs component NPEs
+       ("Cannot read properties of null (reading 'CallLogRequestBuilder')") if it mounts before
+       the lazily-loaded Calls SDK populates CometChatUIKitCalls — its ngOnInit touches the builder
+       synchronously, and Retry does not recover. callsReady() awaits CometChatUIKit.callingReady
+       AND null-checks CometChatUIKitCalls (see cometchat-angular-v5-calls § Call history).
+       STOPGAP until the kit component awaits readiness itself. -->
+  <ng-container *ngIf="tab() === 'calls'">
+    <cometchat-call-logs class="cc-fill" *ngIf="callsReady(); else callsLoading" (itemClick)="openCallLog($event)"></cometchat-call-logs>
+    <ng-template #callsLoading><div class="cc-empty">Loading call history…</div></ng-template>
+  </ng-container>
+</aside>
+```
+```css
+/* .cc-side is already display:flex;flex-direction:column from core-surface.md. The tab
+   nav must not be squeezed, and whichever list is showing must be the ONE flex child
+   that fills the rest — see .cc-fill's comment in core-surface.md for why this is
+   required, not cosmetic: without it the list can't scroll, it gets clipped. */
+.cc-tabs { flex-shrink: 0; }
+```
+The tab nav is yours — the kit ships no tab component. Every kit component used above must
+be in this component's `imports: []`, or it renders **nothing, silently**:
+
+```ts
+import { Component, inject, signal, computed } from '@angular/core';
+import { CometChat } from '@cometchat/chat-sdk-javascript';
+import { CommonModule } from '@angular/common';
+import {
+  ChatStateService,
+  CometChatUIKit,
+  CometChatUIKitCalls,
+  CometChatConversationsComponent,
+  CometChatUsersComponent,
+  CometChatGroupsComponent,
+  CometChatCallLogsComponent,
+  CometChatGroupMembersComponent,
+  CometChatIncomingCallComponent,
+} from '@cometchat/chat-uikit-angular';
+
+@Component({
+  selector: 'app-chat-tabs',
+  standalone: true,
+  imports: [                      // ← omit any of these and that tab renders blank
+    CommonModule,
+    CometChatConversationsComponent,
+    CometChatUsersComponent,
+    CometChatGroupsComponent,
+    CometChatCallLogsComponent,
+    // The Details panel and Incoming calls sections below use these two. Omitting them is
+    // NG8001 ("not a known element") plus NG8002 on [group] — this file's own #1 pitfall.
+    CometChatGroupMembersComponent,
+    CometChatIncomingCallComponent,
+  ],
+  templateUrl: './chat-tabs.component.html',
+})
+export class ChatTabsComponent {
+  private readonly chatState = inject(ChatStateService);
+  readonly tab = signal<'chats' | 'users' | 'groups' | 'calls'>('chats');
+
+  // The template below binds these — declare them here or the build fails TS2339.
+  readonly activeUser = computed(() => this.chatState.activeUser() ?? undefined);
+  readonly activeGroup = computed(() => this.chatState.activeGroup() ?? undefined);
+  readonly activeConversation = computed(() => this.chatState.activeConversation() ?? undefined);
+  readonly showDetails = signal(false);
+  readonly threadParent = signal<any>(null);
+
+  // Gate the call-logs tab: <cometchat-call-logs> NPEs if it mounts before the lazily-loaded
+  // Calls SDK populates CometChatUIKitCalls. callingReady ALONE is not enough (it defaults to a
+  // pre-resolved Promise and the namespace can still be null) — also null-check CometChatUIKitCalls.
+  // STOPGAP (AUDIT-163, proven live).
+  readonly callsReady = signal(false);
+  constructor() {
+    CometChatUIKit.callingReady
+      .then(() => this.callsReady.set(!!CometChatUIKitCalls))
+      .catch(() => this.callsReady.set(false));
+  }
+
+  open(conversation: CometChat.Conversation) { /* see core-surface.md open() */ }
+  openUser(user: CometChat.User) { this.chatState.setActiveUser(user); }
+  openGroup(group: CometChat.Group) { this.chatState.setActiveGroup(group); }
+  openCallLog(_log: any) { /* render your own detail pane — v5 ships none */ }
+  openDetails() { this.threadParent.set(null); this.showDetails.set(true); }
+  closeDetails() { this.showDetails.set(false); }
+  closeThread() { this.threadParent.set(null); }
+  openThread(m: any) { this.showDetails.set(false); this.threadParent.set(m); }
+}
+```
+
+## Details panel
+There is no single "details" component. Compose it: your own header plus `<cometchat-group-members>` for a group.
+```html
+<!-- The OPENER: the message header's own (itemClick) — clicking the avatar/name area.
+     Without it openDetails() is never called and the panel is unreachable. -->
+<cometchat-message-header
+  [user]="activeUser()" [group]="activeGroup()"
+  (itemClick)="openDetails()">
+</cometchat-message-header>
+
+<aside class="cc-panel" *ngIf="showDetails()">
+  <header class="cc-panel-head">
+    <span>{{ activeGroup()?.getName() ?? activeUser()?.getName() }}</span>
+    <button (click)="showDetails.set(false)">Close</button>
+  </header>
+  <!-- `[group]` is REQUIRED (Group, not Group | undefined). `*ngIf="activeGroup()"` guards at
+       runtime but does NOT narrow the type: activeGroup() is a signal CALL, and Angular's
+       strict template checker cannot narrow a call expression across the binding. Written the
+       obvious way it fails the build with
+         TS2322: Type 'Group | undefined' is not assignable to type 'Group'.
+       Bind the `as` alias instead — that narrows, and the *ngIf still guards. -->
+  <ng-container *ngIf="activeGroup() as group">
+    <cometchat-group-members class="cc-fill" [group]="group"></cometchat-group-members>
+  </ng-container>
+</aside>
+```
+Banned members and create-group have no component — see `cometchat-angular-v5-components/references/host-composed.md`.
+
+## Incoming calls
+Mount the listener **once at app root**, not inside the chat page, or it stops working the moment the user navigates away.
+```html
+<!-- app.component.html -->
+<cometchat-incoming-call></cometchat-incoming-call>
+<router-outlet></router-outlet>
+```
+
+## Panel arbitration
+Thread and details compete for the same column. Decide explicitly — opening one should close the other:
+```ts
+openThread(m: any) { this.showDetails.set(false); this.threadParent.set(m); }
+openDetails()      { this.threadParent.set(null);  this.showDetails.set(true); }
+// Call logs: v5 ships no detail component — render your own pane (cometchat-angular-v5-calls).
+openCallLog(log: any) { this.selectedCallLog.set(log); }
+```
+Two panels open at once on a 1280px screen leaves the message pane unusably narrow.
+
+## Verify
+Every tab renders its list · switching tabs keeps the open conversation · details and thread never both open · incoming calls ring from any route · one pane on mobile.

package/skills/cometchat-angular-v5-placement/references/core-surface.md

@@ -0,0 +1,199 @@
+# Core surface — the default "add chat" layout
+
+List + message pane, with thread and search as panels. Ships conversations, messages, threaded replies and search. This is the default for an unscoped request; grow to `combined-app.md` only when asked.
+
+## Component
+```ts
+import { Component, inject, signal, computed, OnDestroy } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { Subject, takeUntil } from 'rxjs';
+import { CometChat } from '@cometchat/chat-sdk-javascript';   // Conversation / User / Group types
+import {
+  ChatStateService, CometChatUIKitConstants,
+  CometChatConversationsComponent, CometChatMessageHeaderComponent,
+  CometChatMessageListComponent, CometChatMessageComposerComponent,
+  CometChatThreadHeaderComponent, CometChatErrorBoundaryComponent,
+  CometChatSearchComponent,
+} from '@cometchat/chat-uikit-angular';
+import type { SearchConversationClickEvent, SearchMessageClickEvent } from '@cometchat/chat-uikit-angular';
+
+@Component({
+  selector: 'app-chat',
+  standalone: true,
+  imports: [
+    CommonModule,
+    CometChatErrorBoundaryComponent,
+    CometChatConversationsComponent,
+    CometChatMessageHeaderComponent,
+    CometChatMessageListComponent,
+    CometChatMessageComposerComponent,
+    CometChatThreadHeaderComponent,
+    CometChatSearchComponent,
+  ],
+  templateUrl: './chat.component.html',
+  styleUrl: './chat.component.css',
+})
+export class ChatComponent implements OnDestroy {
+  private destroy$ = new Subject<void>();
+  readonly chatState = inject(ChatStateService);
+
+  // ChatStateService signals are `T | null`; the kit's inputs are OPTIONAL
+  // (`user?: CometChat.User`). Binding the raw signal fails Angular's strict
+  // template check with "Type 'User | null' is not assignable to 'User | undefined'".
+  // Normalise once here rather than writing `?? undefined` at every binding.
+  readonly activeUser = computed(() => this.chatState.activeUser() ?? undefined);
+  readonly activeGroup = computed(() => this.chatState.activeGroup() ?? undefined);
+  readonly activeConversation = computed(() => this.chatState.activeConversation() ?? undefined);
+  readonly hasActiveChat = computed(() => !!(this.activeUser() || this.activeGroup()));
+
+  readonly threadParent = signal<any>(null);
+
+  // `(itemClick)` emits a **Conversation**, never a User or a Group. Resolve the subject
+  // with getConversationWith() and branch on getConversationType() — a Conversation has
+  // no getGuid(), so sniffing for one silently sends every group into the user slot and
+  // the header/list/composer throw "getUid is not a function".
+  open(conversation: CometChat.Conversation) {
+    this.threadParent.set(null);                 // closing context when switching chats
+    const subject = conversation.getConversationWith();
+    if (conversation.getConversationType() === CometChatUIKitConstants.MessageReceiverType.group) {
+      this.chatState.setActiveGroup(subject as CometChat.Group);
+    } else {
+      this.chatState.setActiveUser(subject as CometChat.User);
+    }
+  }
+
+  openThread(message: any) { this.threadParent.set(message); }
+  closeThread() { this.threadParent.set(null); }
+  back() { this.chatState.clearActiveChat(); }
+
+  // Search is part of the core surface, not an extra — `core-chat-surface` contracts
+  // both `global-conversation-search` and `in-chat-message-search-default`. It swaps
+  // INTO the side column rather than overlaying it, so nothing is covered up.
+  readonly searchOpen = signal(false);
+  openSearch() { this.searchOpen.set(true); }
+  closeSearch() { this.searchOpen.set(false); }
+
+  // A search hit must LAND somewhere — an unwired result list is a dead affordance.
+  // Both outputs emit a WRAPPER, not the domain object: `{ conversation, searchKeyword }`
+  // and `{ message, searchKeyword }`. Binding them as if they emitted a Conversation is a
+  // compile error, and `$event.conversation` is the field you actually want.
+  onSearchConversation(e: SearchConversationClickEvent) { this.open(e.conversation); this.closeSearch(); }
+  async onSearchMessage(e: SearchMessageClickEvent) {
+    // Reuse open() rather than hand-deriving the counterpart: the SDK converts a message
+    // back into its Conversation, which works for both 1:1 and group hits.
+    const conversation = await CometChat.CometChatHelper.getConversationFromMessage(e.message);
+    this.open(conversation);
+    this.closeSearch();
+  }
+
+  ngOnDestroy() { this.destroy$.next(); this.destroy$.complete(); }
+}
+```
+
+## Template
+```html
+<cometchat-error-boundary>
+  <div class="cc-shell">
+    <aside class="cc-side">
+      <ng-container *ngIf="!searchOpen(); else searchPane">
+        <!-- Global search is ENTERED from the conversation list's OWN search bar, not a separate
+             button stacked above it: [showSearchBar] renders the built-in bar in the Conversations
+             header and (searchBarClick) opens the search pane. Do NOT hand-roll a search button. -->
+        <cometchat-conversations
+          class="cc-fill"
+          [showSearchBar]="true"
+          [activeConversation]="activeConversation()"
+          (searchBarClick)="openSearch()"
+          (itemClick)="open($event)">
+        </cometchat-conversations>
+      </ng-container>
+      <ng-template #searchPane>
+        <cometchat-search
+          class="cc-fill"
+          [uid]="activeUser()?.getUid()"
+          [guid]="activeGroup()?.getGuid()"
+          (conversationClick)="onSearchConversation($event)"
+          (messageClick)="onSearchMessage($event)"
+          (backClick)="closeSearch()">
+        </cometchat-search>
+      </ng-template>
+    </aside>
+
+    <main class="cc-main" *ngIf="hasActiveChat(); else empty">
+      <cometchat-message-header [user]="activeUser()" [group]="activeGroup()"></cometchat-message-header>
+      <cometchat-message-list
+        class="cc-fill"
+        [user]="activeUser()"
+        [group]="activeGroup()"
+        (threadRepliesClick)="openThread($event)">
+      </cometchat-message-list>
+      <cometchat-message-composer [user]="activeUser()" [group]="activeGroup()"></cometchat-message-composer>
+    </main>
+    <ng-template #empty><div class="cc-empty">Select a conversation</div></ng-template>
+
+    <aside class="cc-panel" *ngIf="threadParent()">
+      <cometchat-thread-header [parentMessage]="threadParent()" (closeClick)="closeThread()"></cometchat-thread-header>
+      <cometchat-message-list
+        class="cc-fill"
+        [user]="activeUser()"
+        [group]="activeGroup()"
+        [parentMessageId]="threadParent()?.getId()">
+      </cometchat-message-list>
+      <cometchat-message-composer
+        [user]="activeUser()"
+        [group]="activeGroup()"
+        [parentMessageId]="threadParent()?.getId()">
+      </cometchat-message-composer>
+    </aside>
+  </div>
+</cometchat-error-boundary>
+```
+
+## Styles
+```css
+/* <cometchat-error-boundary> ships NO :host rule (verified vs 5.1.0 — its styles array
+   only covers .cometchat-error-boundary__fallback). As the template ROOT it therefore
+   sits BETWEEN your sized ancestor and .cc-shell as an auto-height flex item, and a
+   `height: 100%` below it resolves against an indefinite height. Size it or the whole
+   surface balloons to content height and is clipped by the ancestor's overflow: hidden.
+   `height: 100dvh` on .cc-shell below happens to survive this (viewport-relative, so it
+   ignores the broken chain) — but the moment this recipe is ROUTED and .cc-shell becomes
+   `height: 100%` under a 100dvh outlet, the missing rule silently breaks every pane.
+   Field-proven: a real v4→v5 migration made exactly that (correct) routed adaptation and
+   measured 4120px of list inside an 827px viewport, unscrollable. */
+cometchat-error-boundary { display: flex; flex-direction: column; flex: 1; min-height: 0; overflow: hidden; }
+
+.cc-shell { display: flex; height: 100dvh; width: 100%; min-height: 0; overflow: hidden; }
+.cc-side  { width: 320px; min-height: 0; overflow: hidden; display: flex; flex-direction: column; border-right: 1px solid var(--cometchat-border-color-default); }
+.cc-main  { flex: 1; display: flex; flex-direction: column; min-height: 0; overflow: hidden; }
+.cc-panel { width: 360px; min-height: 0; overflow: hidden; display: flex; flex-direction: column; border-left: 1px solid var(--cometchat-border-color-default); }
+
+/* The thread panel needs its own background so it reads as a distinct surface. Unlike
+   React — where the message list paints an OPAQUE token and a wrapper background never
+   shows (AUDIT-020/024) — Angular's `--cometchat-message-list-background` defaults to
+   **transparent** (verified in the shipped kit), so the wrapper's own background shows
+   through and is all you need. Do NOT copy React's `--cometchat-message-list-bg`
+   override: that token does not exist in this kit and the rule silently does nothing. */
+.cc-panel { background: var(--cometchat-background-color-01); }
+.cc-empty { flex: 1; display: grid; place-items: center; color: var(--cometchat-text-color-secondary); }
+
+/* Every cometchat-conversations / -users / -groups / -call-logs / -search / -message-list
+   host resolves an internal `height: 100%` down to its OWN scroll region
+   (.cometchat-paginated-list { overflow-y: auto }) — it does not size itself. Left
+   unsized inside a flex column it defaults to min-height: auto (refuses to shrink below
+   its content), so the list balloons past the shell and gets hard-clipped by .cc-side's
+   overflow: hidden instead of scrolling. flex: 1 gives it the column's remaining space;
+   min-height: 0 lets it actually shrink to that space so overflow-y: auto can engage. */
+.cc-fill { flex: 1; min-height: 0; overflow: hidden; }
+
+@media (max-width: 768px) {
+  .cc-shell { flex-direction: column; }
+  .cc-side, .cc-panel { width: 100%; }
+}
+```
+`html, body { height: 100%; margin: 0; }` in `styles.css` is required.
+
+## Notes
+- `[user]` and `[group]` are both bound and one is always undefined — the components accept that and it avoids branching the template twice. What they do **not** accept is the wrong kind in either slot: a `Group` in `[user]` throws `getUid is not a function`, which is why `open()` branches on `getConversationType()` rather than duck-typing the emitted object.
+- Switching conversation clears the open thread; leaving it open would show a thread from the previous chat.
+- Search is wired above, swapped into `.cc-side` behind a toggle — never overlaid. Binding `[uid]`/`[guid]` scopes it to the open chat (`in-chat-message-search-default`); with neither bound it searches everything (`global-conversation-search`). Both outputs are handled: an unwired result list is a dead affordance (`RULES.md` §12).

package/skills/cometchat-angular-v5-production/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: cometchat-angular-v5-production
+description: "Ship a CometChat Angular integration safely — server-minted auth tokens instead of the Auth Key, environment file replacement, key hygiene, build config and a pre-launch checklist. Triggers: 'is this production ready', 'auth token instead of auth key angular', 'secure my cometchat setup', 'production build config', 'going live checklist'."
+license: "MIT"
+compatibility: "@cometchat/chat-uikit-angular ^5 (5.1.0–5.2.0 verified); Angular 17-21"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat angular production v5 security auth-token hardening deployment"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-angular@5` (5.1.0–5.2.0 verified). The auth-token API is FETCHED from `{DOCS_BASE}/ui-kit/angular/methods.md` and `/integration.md` (base + paths in `cometchat-angular-v5-core/references/docs-map.md`). **The Angular UI Kit docs have no dedicated production-hardening page** — the checklist below is the pack's own guidance, derived from the credential rules in `RULES.md` §4 and what the kit ships; it is labelled as such rather than presented as documented. Treat that as a tracked DOCS GAP.
+
+## Companion skills (read first)
+- `cometchat-angular-v5-core` — `references/setup-credentials.md` covers the dev credential flow this replaces.
+- `cometchat-security` — the enterprise auth model this client-side hardening plugs into: wiring your IdP / SSO into the token flow (your IdP → your server → mint the CometChat auth token; CometChat is **not** an IdP), token expiry/refresh + re-login, RBAC roles + group (SBAC) scopes, and Auth Key vs auth token vs REST API Key. Load it for a security review or any SSO question.
+
+## Use this skill when
+Moving off the development setup: going live, a security review, or "is this safe to ship".
+
+## The one thing that matters
+**Never ship the Auth Key in the browser bundle.**
+
+The Auth Key can mint a session for **any user in your app**. Anything in `environment.ts` is compiled into JavaScript your users download, so an Auth Key there is public. Anyone can read it, log in as any UID, and read every conversation.
+
+| | Development | Production |
+| --- | --- | --- |
+| Login | `CometChatUIKit.login(uid)` | `CometChatUIKit.loginWithAuthToken(token)` |
+| Auth Key | in `environment.ts` | **absent from the bundle** |
+| Token source | n/a | your backend, per authenticated user |
+| REST API Key | never client-side | server only |
+
+## The production login flow
+1. Your app authenticates the user (your own auth — CometChat is not an identity provider).
+2. Your **server** calls CometChat's REST API with the **REST API Key** to mint an auth token for that user's UID.
+3. The server returns the token to the browser over an authenticated request.
+4. The app calls `loginWithAuthToken(token)`.
+
+```ts
+import { inject } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { firstValueFrom } from 'rxjs';
+import { CometChatUIKit } from '@cometchat/chat-uikit-angular';
+
+const http = inject(HttpClient);
+
+async function loginForCurrentUser() {
+  // your endpoint, protected by your own session
+  const { authToken } = await firstValueFrom(
+    http.get<{ authToken: string }>('/api/cometchat-token', { withCredentials: true }),
+  );
+  return CometChatUIKit.loginWithAuthToken(authToken);
+}
+```
+
+The endpoint must derive the UID from the **server-side session**, never from a request parameter. Accepting `?uid=` lets any caller impersonate anyone.
+
+## Environment files
+```ts
+// src/environments/environment.prod.ts
+export const environment = {
+  production: true,
+  cometchat: { appId: 'APP_ID', region: 'REGION', authKey: '' },   // empty on purpose
+};
+```
+App ID and Region are not secrets — they identify the app. The Auth Key is the secret, and it is empty here. Confirm `fileReplacements` is wired in the production configuration, then **grep the built bundle** for the key to be certain:
+```bash
+ng build --configuration production && grep -r "YOUR_AUTH_KEY" dist/ || echo "clean"
+```
+Run that in CI. A misconfigured `fileReplacements` fails silently and ships the dev file.
+
+## Also before launch
+- **Users are created server-side**, as part of your signup — not from the browser.
+- **Log out properly**: `await CometChatUIKit.logout()`, then clear derived state and unregister push tokens (`cometchat-angular-v5-push`).
+- **HTTPS everywhere** — required for calls (`getUserMedia`) and push.
+- **Pin the kit** to an exact or `~` range so a minor cannot change component behaviour under you.
+- **Set a log level**: `CometChatUIKit.setLogLevel(...)` — quieter in production.
+- **Handle errors visibly**: every list EXCEPT `<cometchat-call-logs>` has an `(error)` output — verified vs 5.1.0, its only outputs are `itemClick` and `callButtonClicked`; it takes an `onError` INPUT callback instead, so `(error)` there binds a DOM listener that never fires. Conversations / Users / Groups / GroupMembers / MessageList all do have `(error)`; wrap the surface in `<cometchat-error-boundary>`.
+- **Teardown** — `ngOnDestroy` on every subscription and listener; leaks are worse in a long-lived SPA.
+- **Region must match** the dashboard app, in every configuration you build.
+
+## Pre-launch checklist
+- [ ] Auth Key absent from the production bundle (grep-verified in CI)
+- [ ] `loginWithAuthToken` in production; UID from the server session
+- [ ] REST API Key server-side only
+- [ ] `fileReplacements` verified by building, not by reading config — note the production build FAILS on the default 1 MB budget until you raise it (`cometchat-angular-v5-core` Install); the grep below never runs otherwise
+- [ ] HTTPS, valid certificate
+- [ ] Logout clears session, state and push tokens
+- [ ] Kit version pinned
+- [ ] Error boundary + error outputs handled
+- [ ] Dashboard extensions/AI enabled for the production app, not just dev
+- [ ] Tested against the production app's credentials
+
+## Common pitfalls
+1. **Auth Key in the production bundle** — the critical one.
+2. **Token endpoint trusting a client-supplied UID** — impersonation.
+3. **`fileReplacements` assumed rather than verified** — dev config ships.
+4. **Dashboard configured on the dev app only** — features silently missing in production.
+5. **No logout teardown** — the next user inherits the session or the push token.
+
+## Verify it works
+Production build contains no Auth Key · login works via token · a tampered UID is rejected by the server · logout fully clears · calls and push work over HTTPS · features enabled on the production app.

package/skills/cometchat-angular-v5-push/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: cometchat-angular-v5-push
+description: "Web push notifications for a CometChat Angular app — the Notifications product, FCM registration, the service worker, and token lifecycle. Docs-first: fetches the current notifications docs rather than baking a version-specific recipe. Triggers: 'add push notifications to my angular app', 'notify users when the app is closed', 'fcm setup', 'register push token'."
+license: "MIT"
+compatibility: "@cometchat/chat-sdk-javascript ^4.1.13; Angular 17-21; requires the CometChat Notifications product"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat angular push v5 notifications fcm firebase service-worker"
+---
+
+> **Ground truth:** push is the CometChat **Notifications** product, not a UI Kit component — this skill is THIN and docs-first. Registration, payload shape and provider setup are FETCHED from the notifications docs via `cometchat-angular-v5-core/references/docs-map.md`; nothing about them is baked here. Live delivery cannot be auto-smoked — say so honestly rather than claiming verification.
+
+## Companion skills (read first)
+- `cometchat-angular-v5-core` — install, credentials, `init→login→render`. Assumed.
+
+## Use this skill when
+Delivering notifications while the app is closed or backgrounded.
+
+## This skill is deliberately THIN — fetch the docs
+Push spans a product (CometChat Notifications), a third-party provider (Firebase/FCM), a service worker, and browser permission rules. Every one of those changes independently, so a baked recipe goes stale fast.
+
+**Start here:** `{SDK_DOCS_BASE}/notifications/overview.md`, then the web push integration page. Discover the current pages from the SDK index (`cometchat-angular-v5-core/references/docs-map.md`). Read before writing.
+
+Angular's own docs cover push only inside `{DOCS_BASE}/ui-kit/angular/campaigns.md` — there is no dedicated Angular push page. That is a **known docs gap**; the product-level notifications docs are the source of truth.
+
+## What is true regardless of version
+**1. Push is a separate product.** It must be enabled and configured for the app in the dashboard, with provider credentials added there. No client code substitutes for that step.
+
+**2. It is not the UI Kit.** Registration is SDK-level (`CometChatNotifications`), not a component. There is nothing to render.
+
+**3. It needs a service worker at origin root.** `firebase-messaging-sw.js` must be served from `/`, not from a nested path. In Angular, add it to the app's `assets` in `angular.json` so it lands at the root of `dist/`, and confirm it is reachable at `/firebase-messaging-sw.js` after build — a 404 there is the single most common cause of "push does nothing".
+
+**4. Permission requires a user gesture.** Call the permission request from a click. Browsers block it on load, and repeated silent blocks poison the origin.
+
+**5. Token lifecycle is yours.** Register the FCM token after login; unregister on logout. Skipping the unregister sends the next user's notifications to the previous device.
+
+**6. iOS Safari is PWA-only.** Web push on iOS requires the site installed to the home screen. Not a bug; set expectations.
+
+## Angular specifics
+- Register the token **after** `login()` resolves — see core's guarded-login pattern.
+- Put registration in a service, not a component, so it does not re-run per route.
+- If the app is SSR, guard all of it with `isPlatformBrowser` (`cometchat-angular-v5-patterns`).
+- Unregister in the same place you call `CometChatUIKit.logout()`.
+
+## Verify it works
+Push cannot be verified in a headless browser: it needs a real device or browser profile, a live provider, and a backgrounded app. Expect to test by hand:
+1. Load over HTTPS, grant permission from a click.
+2. Confirm `/firebase-messaging-sw.js` returns 200.
+3. Background the tab; send a message from a second account.
+4. Notification arrives; tapping it focuses the app.
+5. Log out; confirm notifications stop.
+
+## Common pitfalls
+1. **Notifications not enabled in the dashboard** — nothing works, no error.
+2. **Service worker not at origin root** — silent failure.
+3. **Permission requested on load** — blocked.
+4. **Token registered before login** — no user to attach it to.
+5. **No unregister on logout** — notifications follow the wrong user.
+6. **Expecting iOS Safari to work outside a PWA.**
+7. **Baking a recipe from memory** — fetch the docs; this area moves.

package/skills/cometchat-angular-v5-testing/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: cometchat-angular-v5-testing
+description: "Test an Angular app that embeds CometChat — what to mock vs exercise for real, TestBed setup for standalone kit components, avoiding real network in unit tests, and a two-account manual pass for realtime. Triggers: 'write tests for my chat', 'mock cometchat in jest', 'testbed cometchat', 'my tests hang', 'e2e test the chat'."
+license: "MIT"
+compatibility: "@cometchat/chat-uikit-angular ^5 (5.1.0–5.2.0 verified); Angular 17-21; Jest / Karma / Vitest / Playwright"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat angular testing v5 testbed jest mock e2e playwright"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-angular@5` (5.1.0–5.2.0 verified). **The Angular UI Kit docs have no testing page** — the strategy here is the pack's own, and is labelled as such rather than presented as documented (a tracked DOCS GAP). Any kit symbol a test mocks must still exist in the `angular-v5` catalog, and its real shape comes from the component's `.md` twin via `cometchat-angular-v5-core/references/docs-map.md` — mock the API the kit actually exposes, never one invented to fit the test.
+
+## Companion skills (read first)
+- `cometchat-angular-v5-core` — init/login lifecycle, which is what makes tests hang if unmocked.
+
+## Use this skill when
+Writing tests for a component that renders kit components, or diagnosing tests that hang or fail on network.
+
+## Decide what you are testing
+| Testing | Approach |
+| --- | --- |
+| **Your** logic — selection, routing, state | Unit test with CometChat **mocked** |
+| Kit component internals | Don't. It is a third-party dependency with its own tests |
+| Your app's chat flow end-to-end | Playwright against a real dev app, two accounts |
+| Realtime delivery | Manual, two browsers. Not automatable cheaply |
+
+The common mistake is unit-testing kit internals. Test the seam: given a click, does your component set the right active chat?
+
+## Mock CometChat in unit tests
+Kit components open sockets and call the API at construction. Left real, tests hang, fail offline, and pollute a live app with test data.
+
+```ts
+// src/testing/cometchat.mock.ts
+export const cometChatUIKitMock = {
+  initFromSettings: jest.fn().mockResolvedValue({}),
+  login: jest.fn().mockResolvedValue({ getUid: () => 'test-uid' }),
+  loginWithAuthToken: jest.fn().mockResolvedValue({ getUid: () => 'test-uid' }),
+  logout: jest.fn().mockResolvedValue(undefined),
+  getLoggedInUser: jest.fn().mockReturnValue({ getUid: () => 'test-uid' }),
+  isInitialized: jest.fn().mockReturnValue(true),
+  isCallingEnabled: jest.fn().mockReturnValue(false),
+};
+```
+Point the module at it (Jest):
+```ts
+jest.mock('@cometchat/chat-uikit-angular', () => ({
+  ...jest.requireActual('@cometchat/chat-uikit-angular'),
+  CometChatUIKit: cometChatUIKitMock,
+}));
+```
+Keep `requireActual` so real component classes and `ChatStateService` still exist — you want your own wiring exercised, only the network faked.
+
+## TestBed with standalone kit components
+They are standalone, so they go in `imports`, exactly as in the app:
+```ts
+import { TestBed } from '@angular/core/testing';
+import { ChatComponent } from './chat.component';
+
+beforeEach(async () => {
+  await TestBed.configureTestingModule({ imports: [ChatComponent] }).compileComponents();
+});
+```
+If a test fails with "is not a known element", the component under test is missing it from its own `imports` — a real bug the test just caught, not a test problem.
+
+## Prefer testing ChatStateService over the DOM
+Assert state, not kit markup. Kit internals change between releases; your wiring should not.
+```ts
+it('sets the active group when a group conversation is clicked', () => {
+  const fixture = TestBed.createComponent(ChatComponent);
+  const cmp = fixture.componentInstance;
+
+  // Mock the SHAPE the kit actually emits: a Conversation whose subject is a Group.
+  // Handing open() a bare { getGuid } instead lets a duck-typing bug pass the test
+  // while every group chat throws "getUid is not a function" in the browser.
+  const group = new CometChat.Group('g1', 'Team', CometChat.GROUP_TYPE.PUBLIC);
+  const conversation = { getConversationType: () => 'group', getConversationWith: () => group };
+
+  cmp.open(conversation as unknown as CometChat.Conversation);
+  expect(cmp.chatState.getActiveGroup()).toBeTruthy();
+  expect(cmp.chatState.getActiveUser()).toBeFalsy();      // the group must NOT land in the user slot
+});
+```
+> **Mock the emitted shape, not the shape your code happens to check.** A mock built backwards from the implementation can only confirm the implementation — including its bugs. `(itemClick)` emits a `Conversation`; a test that passes anything else is not exercising the wiring.
+
+## E2E with Playwright
+Use a real dev app and two seeded users. What is worth asserting:
+- The conversation list renders rows
+- Clicking one opens header + list + composer
+- Sending text makes it appear
+- **No console errors** — the kit fails quietly, so this catches a lot
+- **Nothing collapsed** — assert the message list's height is non-zero; a zero-height pane is the most common silent break
+
+```ts
+const box = await page.locator('cometchat-message-list').boundingBox();
+expect(box!.height).toBeGreaterThan(100);
+```
+Seed users and conversations through the REST API in setup, not the UI.
+
+## Not worth automating
+Realtime delivery between two clients, calls (needs media permissions and two peers), and push (needs a real device and a backgrounded app). Verify these manually and say so in the test plan rather than writing brittle automation.
+
+## Common pitfalls
+1. **Unmocked CometChat in unit tests** → hangs, flakes, offline failures.
+2. **Mocking the whole module** without `requireActual` → your own wiring never runs.
+3. **Asserting kit DOM internals** → breaks on every kit release.
+4. **Tests against a production app** → real users, real data.
+5. **No zero-height assertion in E2E** → the most common visual break goes unnoticed.
+6. **No teardown in tests** → leaked listeners bleed across specs.
+
+## Verify it works
+Unit tests pass offline · no test opens a real socket · a missing `imports` entry fails a test · E2E asserts non-zero height and no console errors · manual checks are documented, not faked.