@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-angular-calls/references/ngzone-and-async-callbacks.md

@@ -1,184 +0,0 @@
-# NgZone + async SDK callbacks — the Angular calls gotcha
-
-Angular's change detection runs inside `NgZone`. Callbacks that fire *outside* NgZone don't trigger change detection — UI doesn't update. The Calls SDK fires lots of callbacks from native bridges (WebRTC, browser MediaStream events), and those bridges escape the zone.
-
-If your custom call UI seems "frozen" — call ends but the screen stays — this is almost always the cause.
-
----
-
-## Symptom
-
-```ts
-// OngoingCallComponent
-ngOnInit() {
-  CometChatCalls.joinSession(token, settings, container);  // v5 canonical (startSession is a deprecated shim)
-
-  // This callback is registered with the SDK, which is registered with WebRTC,
-  // which is a native browser API outside Angular's zone
-  callListener.onCallEnded = () => {
-    this.callEnded = true;       // ← variable updates
-    this.cleanup();              // ← runs
-    // BUT: change detection doesn't fire. The template doesn't re-render.
-    // User sees: "End" button still showing, no "Call ended" message.
-  };
-}
-```
-
----
-
-## Fix
-
-Wrap the callback body in `NgZone.run`:
-
-```ts
-import { NgZone } from "@angular/core";
-
-constructor(private zone: NgZone) {}
-
-ngOnInit() {
-  // ...
-  callListener.onCallEnded = () => {
-    this.zone.run(() => {
-      this.callEnded = true;
-      this.cleanup();
-    });
-  };
-}
-```
-
-Now change detection runs after the variable updates; template re-renders.
-
----
-
-## Which callbacks need NgZone.run?
-
-All Calls SDK event listeners. The kit's own components handle this internally; custom code that subscribes to the SDK directly does NOT.
-
-Conservative rule: **wrap every callback that mutates UI state** in `zone.run`.
-
-> `CometChatCalls.OngoingCallListener` is `@deprecated` in calls-sdk-javascript v5 (prefer `CometChatCalls.addEventListener(...)`); the listener pattern below still works and is shown here because this reference is about NgZone-wrapping. Note that the dominant-speaker signal is NOT a listener callback — subscribe to it via `addEventListener("onDominantSpeakerChanged", …)` (also wrap that handler in `zone.run`).
-
-```ts
-const listener = new CometChatCalls.OngoingCallListener({
-  onUserListUpdated: (userList) => {
-    this.zone.run(() => { this.participants = userList; });
-  },
-  onCallEnded: () => {
-    this.zone.run(() => { this.callEnded = true; this.cleanup(); });
-  },
-  onError: (err) => {
-    this.zone.run(() => { this.errorMessage = err.message; });
-  },
-});
-
-// Dominant speaker is an addEventListener event key, not a listener callback:
-const offSpeaker = CometChatCalls.addEventListener("onDominantSpeakerChanged", (p) => {
-  this.zone.run(() => { this.activeSpeakerUid = p.uid; });
-});
-```
-
-If a callback only triggers a side effect (logging, analytics) without UI changes, NgZone.run is not strictly required — but harmless.
-
----
-
-## Alternative: ChangeDetectorRef.detectChanges
-
-If you want to avoid NgZone for performance reasons (zone.run is cheap but adds overhead in hot paths), use `ChangeDetectorRef.detectChanges`:
-
-```ts
-import { ChangeDetectorRef } from "@angular/core";
-
-constructor(private cd: ChangeDetectorRef) {}
-
-ngOnInit() {
-  callListener.onCallEnded = () => {
-    this.callEnded = true;
-    this.cleanup();
-    this.cd.detectChanges();   // run change detection just for this component subtree
-  };
-}
-```
-
-Pros: scoped to the component (NgZone is global).
-Cons: if you have parent component bindings that depend on this state, they don't update. Use NgZone.run for cross-component state changes.
-
-For 95% of cases, NgZone.run is the right answer.
-
----
-
-## Async/await inside callbacks
-
-If your callback is `async`, wrap the whole function:
-
-```ts
-callListener.onCallEnded = async () => {
-  await this.zone.run(async () => {
-    await this.savePostCallAnalytics();
-    this.callEnded = true;
-    this.cleanup();
-  });
-};
-```
-
-Or simpler — use a plain method and let zone.js patch async automatically:
-
-```ts
-callListener.onCallEnded = () => {
-  this.zone.run(() => this.handleCallEnded());
-};
-
-private async handleCallEnded() {
-  await this.savePostCallAnalytics();
-  this.callEnded = true;
-  this.cleanup();
-}
-```
-
-Inside `handleCallEnded`, change detection fires automatically because zone.js patches `await`.
-
----
-
-## How to detect this bug
-
-Add a debug log inside the callback. If the log fires but the UI doesn't update, you're outside zone:
-
-```ts
-callListener.onCallEnded = () => {
-  console.log("[debug] onCallEnded fired", new Date().toISOString());
-  this.callEnded = true;
-};
-```
-
-If "fired" appears in console but the template still shows the call as active, wrap in zone.run.
-
----
-
-## OnPush change detection
-
-If your component uses `ChangeDetectionStrategy.OnPush`, NgZone.run alone isn't enough — OnPush only re-renders on `@Input` changes or explicit markForCheck. Combine:
-
-```ts
-import { ChangeDetectionStrategy, ChangeDetectorRef } from "@angular/core";
-
-@Component({
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class OngoingCallComponent {
-  constructor(private zone: NgZone, private cd: ChangeDetectorRef) {}
-
-  ngOnInit() {
-    callListener.onCallEnded = () => {
-      this.zone.run(() => {
-        this.callEnded = true;
-        this.cd.markForCheck();
-      });
-    };
-  }
-}
-```
-
----
-
-## When the kit fires NgZone-correctly
-
-The CometChat Angular UI Kit (`@cometchat/chat-uikit-angular`) handles this internally. If you only use `<cometchat-incoming-call>`, `<cometchat-ongoing-call>`, etc. — no manual NgZone needed. The bug only bites when you write custom subscriptions to `CometChatCalls.*` callbacks.

package/skills/cometchat-angular-calls/references/picture-in-picture.md

@@ -1,285 +0,0 @@
-# Picture-in-Picture on Angular
-
-Same browser APIs as React (Video PiP + Document PiP) — the SDK and underlying primitives are identical because Angular wraps the JS Calls SDK. For API-level details, browser support, and the Document PiP path, read `cometchat-react-calls/references/picture-in-picture.md` first. This reference covers Angular-specific wiring.
-
----
-
-## Video PiP — Angular component pattern
-
-```ts
-// components/pip-button/pip-button.component.ts
-@Component({
-  selector: "app-pip-button",
-  template: `
-    <button (click)="togglePip()" [disabled]="!supported" *ngIf="supported">
-      {{ inPip ? "Exit PiP" : "Enter PiP" }}
-    </button>
-  `,
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class PipButtonComponent implements OnInit, OnDestroy {
-  @Input() videoRef!: ElementRef<HTMLVideoElement>;
-  inPip = false;
-  supported = typeof document !== "undefined" && document.pictureInPictureEnabled;
-
-  private enterListener?: () => void;
-  private leaveListener?: () => void;
-
-  constructor(private zone: NgZone, private cd: ChangeDetectorRef) {}
-
-  ngOnInit() {
-    if (!this.videoRef?.nativeElement) return;
-    const video = this.videoRef.nativeElement;
-
-    this.enterListener = () => this.zone.run(() => { this.inPip = true; this.cd.markForCheck(); });
-    this.leaveListener = () => this.zone.run(() => { this.inPip = false; this.cd.markForCheck(); });
-
-    video.addEventListener("enterpictureinpicture", this.enterListener);
-    video.addEventListener("leavepictureinpicture", this.leaveListener);
-  }
-
-  ngOnDestroy() {
-    const video = this.videoRef?.nativeElement;
-    if (!video) return;
-    if (this.enterListener) video.removeEventListener("enterpictureinpicture", this.enterListener);
-    if (this.leaveListener) video.removeEventListener("leavepictureinpicture", this.leaveListener);
-    if (document.pictureInPictureElement) {
-      document.exitPictureInPicture().catch(() => {});
-    }
-  }
-
-  async togglePip() {
-    if (!this.videoRef?.nativeElement) return;
-    if (this.inPip) {
-      await document.exitPictureInPicture();
-    } else {
-      try {
-        await this.videoRef.nativeElement.requestPictureInPicture();
-      } catch (err) {
-        console.warn("PiP request failed:", err);
-      }
-    }
-  }
-}
-```
-
-The `@Input() videoRef` is the parent's `<video>` element via `@ViewChild`. NgZone wraps the events so OnPush components re-render correctly.
-
-Usage in the call screen:
-
-```ts
-@Component({
-  selector: "app-ongoing-call",
-  template: `
-    <video #remoteVideo autoplay playsinline [class.hidden]="inPip"></video>
-    <app-pip-button [videoRef]="remoteVideo"></app-pip-button>
-  `,
-  styles: [`
-    .hidden { visibility: hidden; }
-  `],
-})
-export class OngoingCallComponent {
-  @ViewChild("remoteVideo") remoteVideo!: ElementRef<HTMLVideoElement>;
-  inPip = false;
-}
-```
-
----
-
-## Document PiP — Angular host element transfer
-
-Document PiP lets you put arbitrary HTML in a floating window, including a full Angular component subtree. The challenge: detaching + re-attaching a DOM node mid-Angular-lifecycle.
-
-```ts
-// services/document-pip.service.ts
-import { Injectable, NgZone, RendererFactory2, Renderer2 } from "@angular/core";
-
-@Injectable({ providedIn: "root" })
-export class DocumentPipService {
-  private pipWindow: Window | null = null;
-  private renderer: Renderer2;
-
-  constructor(private zone: NgZone, private rendererFactory: RendererFactory2) {
-    this.renderer = rendererFactory.createRenderer(null, null);
-  }
-
-  get supported(): boolean {
-    return typeof window !== "undefined" && "documentPictureInPicture" in window;
-  }
-
-  async openWindow(content: HTMLElement, options: { width?: number; height?: number } = {}): Promise<Window | null> {
-    if (!this.supported) return null;
-
-    this.pipWindow = await (window as unknown as {
-      documentPictureInPicture: { requestWindow: (o: object) => Promise<Window> };
-    }).documentPictureInPicture.requestWindow({
-      width: options.width ?? 360,
-      height: options.height ?? 480,
-    });
-
-    // Copy stylesheets so kit + Angular Material styles work in the PiP window
-    for (const sheet of Array.from(document.styleSheets)) {
-      try {
-        const cssText = Array.from(sheet.cssRules ?? []).map(r => r.cssText).join("\n");
-        const style = this.pipWindow.document.createElement("style");
-        style.textContent = cssText;
-        this.pipWindow.document.head.appendChild(style);
-      } catch {
-        if (sheet.href) {
-          const link = this.pipWindow.document.createElement("link");
-          link.rel = "stylesheet";
-          link.href = sheet.href;
-          this.pipWindow.document.head.appendChild(link);
-        }
-      }
-    }
-
-    this.pipWindow.document.body.appendChild(content);
-
-    return this.pipWindow;
-  }
-
-  closeWindow() {
-    if (this.pipWindow) {
-      this.pipWindow.close();
-      this.pipWindow = null;
-    }
-  }
-}
-```
-
-Then in the call component:
-
-```ts
-@Component({
-  // ...
-  template: `
-    <div #callRoot class="call-root">
-      <video #remoteVideo autoplay playsinline></video>
-      <app-control-panel></app-control-panel>
-    </div>
-  `,
-})
-export class OngoingCallComponent {
-  @ViewChild("callRoot", { static: true }) callRoot!: ElementRef<HTMLElement>;
-
-  constructor(private docPip: DocumentPipService, private zone: NgZone) {}
-
-  async enterDocumentPip() {
-    const pipWin = await this.docPip.openWindow(this.callRoot.nativeElement);
-    if (!pipWin) return;
-
-    pipWin.addEventListener("pagehide", () => {
-      this.zone.run(() => {
-        // Restore the call-root back to the original mount point
-        const host = document.getElementById("call-host");
-        if (host && this.callRoot.nativeElement) {
-          host.appendChild(this.callRoot.nativeElement);
-        }
-      });
-    });
-  }
-}
-```
-
-When you transfer the DOM node into the PiP window, Angular's change detection still works because the node is the same. Click handlers, OnPush updates, NgZone events all continue functioning across the window boundary. This is the magic of Document PiP.
-
----
-
-## Auto-PiP on tab/window backgrounding
-
-```ts
-@Component({...})
-export class OngoingCallComponent implements OnInit, OnDestroy {
-  private visibilitySub?: Subscription;
-
-  ngOnInit() {
-    if (!document.pictureInPictureEnabled) return;
-    this.visibilitySub = fromEvent(document, "visibilitychange").subscribe(() => {
-      if (document.visibilityState === "hidden" && this.callActive) {
-        this.zone.run(() => {
-          this.remoteVideo.nativeElement.requestPictureInPicture().catch(() => {});
-        });
-      }
-    });
-  }
-
-  ngOnDestroy() {
-    this.visibilitySub?.unsubscribe();
-  }
-}
-```
-
-Same caveats as React — Safari rejects auto-PiP from non-user-gesture contexts in some versions. Test on real Safari before relying on this.
-
----
-
-## Auto-leave on hangup
-
-```ts
-async endCall() {
-  if (document.pictureInPictureElement) {
-    await document.exitPictureInPicture();
-  }
-  this.docPip.closeWindow();
-
-  CometChatCalls.leaveSession();   // v5 canonical (endSession is a deprecated shim)
-  // ...rest of cleanup
-}
-```
-
----
-
-## SSR considerations (Angular Universal)
-
-Document and Video PiP both reference `document.pictureInPictureEnabled` and `window.documentPictureInPicture`. Both are browser-only — guard:
-
-```ts
-import { isPlatformBrowser } from "@angular/common";
-
-constructor(@Inject(PLATFORM_ID) private platformId: object) {}
-
-get supported() {
-  return isPlatformBrowser(this.platformId)
-    && typeof document !== "undefined"
-    && document.pictureInPictureEnabled;
-}
-```
-
-Without this, SSR build crashes at boot.
-
----
-
-## Anti-patterns
-
-1. **`requestPictureInPicture()` from `ngOnInit`.** Browsers reject — needs user gesture. `(click)` is the trigger.
-2. **Skipping `NgZone.run`** for PiP enter/leave events. OnPush components don't re-render.
-3. **Document PiP without copying stylesheets.** PiP window unstyled.
-4. **Forgetting `pagehide` cleanup** when user closes the PiP window via system X. DOM node stays detached; controls broken.
-5. **No SSR guard.** Universal build crashes.
-6. **Two separate video elements** (one for normal, one for PiP). Use one `<video>` and `[class.hidden]` it.
-7. **Auto-PiP in `ngOnInit` with no user-gesture context.** Safari rejects.
-
----
-
-## Verification checklist
-
-- [ ] PiP button feature-detects `document.pictureInPictureEnabled`
-- [ ] Button hidden / disabled when unsupported
-- [ ] PiP request from `(click)`, not `ngOnInit`
-- [ ] `enterpictureinpicture` / `leavepictureinpicture` listeners wrapped in NgZone
-- [ ] OnPush components call `markForCheck()` after PiP state change
-- [ ] In-page video hidden while PiP active
-- [ ] Hangup path calls `document.exitPictureInPicture()` if active
-- [ ] Document PiP path closes window via `docPip.closeWindow()`
-- [ ] SSR builds: `isPlatformBrowser` guards
-- [ ] Real-browser smoke: Chrome (both APIs) + Safari (Video PiP) + Firefox (Video PiP)
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/picture-in-picture.md` — sister reference (browser API details, Document PiP semantics, browser support)
-- `references/custom-ui.md` — Angular custom call UI (PiP integration via @ViewChild on the video element)
-- `references/lazy-loading-pitfalls.md` — eager loading + SSR guards
-- `cometchat-angular-calls` SKILL.md — base hard rules

package/skills/cometchat-angular-calls/references/raise-hand.md

@@ -1,172 +0,0 @@
-# Raise hand on Angular
-
-Same SDK API as web (`@cometchat/calls-sdk-javascript`). Angular-specific wiring: NgZone wrap on listeners, RxJS Subject for the raised-hands roster, OnPush + markForCheck.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/raise-hand
-**Read first:** `cometchat-react-calls/references/raise-hand.md` — integration shape + anti-patterns are identical; this reference is the Angular-specific wiring.
-
----
-
-## SDK API (same as web)
-
-```ts
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-
-CometChatCalls.raiseHand();
-CometChatCalls.lowerHand();
-```
-
----
-
-## Angular wiring — service-driven roster
-
-Centralize raise-hand state in a service so any component can subscribe:
-
-```ts
-// services/raise-hand.service.ts
-import { Injectable, NgZone, OnDestroy } from "@angular/core";
-import { BehaviorSubject } from "rxjs";
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-
-interface RaisedParticipant { uid: string; name: string; raisedAt: number; }
-
-@Injectable({ providedIn: "root" })
-export class RaiseHandService implements OnDestroy {
-  private readonly raised = new Map<string, RaisedParticipant>();
-  readonly raised$ = new BehaviorSubject<RaisedParticipant[]>([]);
-
-  private onRaised = (p: { uid: string; name: string }) => {
-    this.zone.run(() => {
-      this.raised.set(p.uid, { ...p, raisedAt: Date.now() });
-      this.emit();
-    });
-  };
-
-  private onLowered = (p: { uid: string }) => {
-    this.zone.run(() => {
-      this.raised.delete(p.uid);
-      this.emit();
-    });
-  };
-
-  // addEventListener returns an unsubscribe fn — there is NO CometChatCalls.removeEventListener.
-  private offs: Array<() => void> = [];
-
-  constructor(private zone: NgZone) {
-    this.offs.push(
-      CometChatCalls.addEventListener("onParticipantHandRaised", this.onRaised),
-      CometChatCalls.addEventListener("onParticipantHandLowered", this.onLowered),
-    );
-  }
-
-  ngOnDestroy() {
-    this.offs.forEach(off => off());
-    this.offs = [];
-  }
-
-  raise() { CometChatCalls.raiseHand(); }
-  lower() { CometChatCalls.lowerHand(); }
-
-  private emit() {
-    const sorted = Array.from(this.raised.values()).sort((a, b) => a.raisedAt - b.raisedAt);
-    this.raised$.next(sorted);
-  }
-}
-```
-
-The `NgZone.run` wrapping is the canonical Angular rule (see `references/ngzone-and-async-callbacks.md`) — without it, `BehaviorSubject.next` doesn't trigger change detection in OnPush components.
-
----
-
-## Toggle button component
-
-```ts
-@Component({
-  selector: "app-raise-hand-button",
-  template: `
-    <button
-      (click)="toggle()"
-      [class.active]="raised"
-      [attr.aria-pressed]="raised"
-      [attr.aria-label]="raised ? 'Lower hand' : 'Raise hand'"
-    >
-      ✋ {{ raised ? "Lower" : "Raise" }}
-    </button>
-  `,
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class RaiseHandButtonComponent {
-  raised = false;
-  constructor(private svc: RaiseHandService, private cd: ChangeDetectorRef) {}
-
-  toggle() {
-    if (this.raised) this.svc.lower();
-    else this.svc.raise();
-    this.raised = !this.raised;
-    this.cd.markForCheck();
-  }
-}
-```
-
----
-
-## Roster component (host view)
-
-```ts
-@Component({
-  selector: "app-raised-hands-list",
-  template: `
-    <div *ngIf="(raised$ | async) as list">
-      <ul *ngIf="list.length > 0" aria-label="Raised hands queue">
-        <li *ngFor="let p of list; trackBy: trackByUid">
-          ✋ {{ p.name }} <span class="ago">{{ secondsAgo(p.raisedAt) }}</span>
-        </li>
-      </ul>
-    </div>
-  `,
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class RaisedHandsListComponent {
-  raised$ = this.svc.raised$;
-  constructor(private svc: RaiseHandService) {}
-  trackByUid(_: number, p: RaisedParticipant) { return p.uid; }
-  secondsAgo(t: number) { return `${Math.round((Date.now() - t) / 1000)}s ago`; }
-}
-```
-
-`trackByUid` is critical — without it, Angular re-renders every list item on every emit, which is bad for FlatList-style smooth scroll.
-
----
-
-## Anti-patterns
-
-Same shape as web sister reference, plus Angular-specific:
-
-1. **Service NOT provided in `root`.** If raise-hand service is provided in a feature module, it instantiates on lazy-load — listeners attach late. Provide in root so it boots with the app.
-2. **Skipping `markForCheck` with OnPush.** Service emits, component doesn't re-render.
-3. **Forgetting `ngOnDestroy` cleanup.** Service is `providedIn: "root"` so it lives forever, but the listeners would survive across logout/re-login. Reset on `CometChatUIKit.logout`.
-4. **`*ngFor` without `trackBy`.** Re-renders thrash; tile state lost.
-
----
-
-## Verification checklist
-
-- [ ] `RaiseHandService` provided in root
-- [ ] `NgZone.run` wraps both listener callbacks
-- [ ] `BehaviorSubject` emits sorted-by-raisedAt list
-- [ ] Toggle button has `aria-pressed` + `aria-label`
-- [ ] Roster uses `trackBy: trackByUid`
-- [ ] OnPush components call `markForCheck()` on state change
-- [ ] Listeners cleaned up in `ngOnDestroy`
-- [ ] `hideRaiseHandButton: true` in CallSettings if using custom UI
-- [ ] Browser smoke: 3 tabs in same call → host's roster updates with markForCheck
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/raise-hand.md` — sister reference
-- `references/ngzone-and-async-callbacks.md` — NgZone primer
-- `references/group-calls.md` — group call architecture in Angular
-- `cometchat-a11y` — `aria-pressed` + screen reader announcements
-- Canonical docs: https://www.cometchat.com/docs/calls/javascript/raise-hand