cometchat-angular-v5-migration

Ground truth: migrates an Angular app FROM @cometchat/chat-uikit-angular@4 TO @5. v5 target symbols are catalog-verified vs installed 5.1.0; the v4→v5 breaking-change map is BAKED in references/migration-guide.md (distilled from the official "Upgrading From V4" guide + a real v4.3.36→v5.1.0 export diff — 146 genuine removals, 33 bare→Component renames, kept separate). The exhaustive per-component prop table is FETCHED from cometchat-angular-v5-components/references/catalog.md + the docs .md twins. APPEND/transform the user's code — never wipe it; work on a branch and confirm before bulk edits (RULES.md).

Companion skills (read first)

• cometchat-angular-v5-core — the v5 init/login/render the migrated app lands on. This skill ASSUMES it.
• cometchat-angular-v5-components — the v5 component catalog (the target names + real inputs/outputs).
• cometchat-angular-v5-placement — how to rebuild a v4 composite from v5 modules (§2 of the migration guide points here per composite).

Use this skill when

"upgrade my v4 UI Kit to v5", "migrate CometChat Angular v4→v5", "bump @cometchat/chat-uikit-angular to v5". Precondition: the project currently has @cometchat/chat-uikit-angular@4.

Migration workflow (BAKED)

1. Detect the starting point. Confirm package.json has @cometchat/chat-uikit-angular@4 (already @5 → STOP, nothing to migrate). Note whether the app uses composite components (...WithMessages/...WithDetails), CometChatThemeService, *Style inputs, DataSource/ChatConfigurator, or custom localization keys — each drives a later step. Work on a branch; transform in place, never delete the user's code.
2. Update dependencies. npm install @cometchat/chat-uikit-angular@5 @cometchat/chat-sdk-javascript@^4.1.13 @cometchat/cards-angular@^1.0.0 then npm uninstall @cometchat/uikit-elements @cometchat/uikit-resources @cometchat/uikit-shared. @cometchat/cards-angular is a genuine new 5.1.0 peer the official guide never mentions — install it or the build fails on a missing peer, not a CometChat error.
3. Scan the repo for v4 usage. Grep for every symbol in references/migration-guide.md §2 (composites, no-equivalent standalones, DataSource/decorators, the ~35 *Style objects) and §2b (the 33 bare-name renames) — produce the concrete change list before editing anything. A bare name is not automatically "removed"; check §2b first.
4. Apply the breaking-change map (references/migration-guide.md): §2/§2b symbol removals + renames, §3 theming (CometChatThemeService + *Style → CSS variables + the real ThemeService, not the official guide's own hand-rolled matchMedia example — see the warning in §3), §4 event-input → Output rename, §5 DataSource/ChatConfigurator → MessageBubbleConfigService or "nothing, it's auto-rendered," §6 drop CUSTOM_ELEMENTS_SCHEMA + convert to standalone, §7 optional ChatStateService adoption, §8 localization method renames. The baked map is a closed list, not a prop reference — FETCH the rest (RULES.md § Fetch discipline; never node_modules/**/*.d.ts), routed from cometchat-angular-v5-core/references/docs-map.md: the official guide {DOCS_BASE}/ui-kit/angular/customization/migration-guide.md for anything the map omits; a component's exact inputs/outputs/slots from its own .md twin (Angular has no migration-property-changes page — there is no single prop-diff table); an SDK method for a capability with no v5 component ({SDK_DOCS_BASE}/sdk/javascript/groups-overview.md et al.) — that is where the host-composed group surfaces in step 5 come from.
5. Rebuild every composite from modules. v5 has no composite components at all — CometChatConversationsWithMessages etc. must become a hand-stitched surface. Use cometchat-angular-v5-placement/references/core-surface.md (1:1) or combined-app.md (tabbed) as the target shape, not a literal prop-for-prop port — the composite's configuration options (which v4 had many of) don't exist in v5; its behavior is what you're reproducing.
6. Verify. Build/typecheck passes; NO v4 symbols remain (grep references/migration-guide.md §2's full list); every kit component is in its consumer's imports: []; the app renders after init→login resolves (cometchat-angular-v5-core/references/lifecycle.md). Reuse cometchat-angular-v5-core "Verify it works".

Common pitfalls (BAKED)

• Porting the official guide's own theming example. It shows a hand-rolled matchMedia listener for OS-follow — that predates the real v5 mechanism. ThemeService.initFromPreference() already does this; don't reintroduce v4-era manual theme-tracking code (§3).
• Treating a bare v4 name as removed when it's only renamed. Check §2b (33 bare→Component renames) before concluding a component is gone — most "missing" names are one word away from their v5 form.
• Missing @cometchat/cards-angular. Genuinely undocumented in the official migration guide; the install fails on a peer-dependency error that looks unrelated to the migration.
• Forgetting imports: [] after dropping CUSTOM_ELEMENTS_SCHEMA. v4's schema tolerated unregistered elements; v5's standalone components render nothing, silently if omitted from imports: [] — the single most common v5 failure mode, and migrated code is exactly where it's missed (cometchat-angular-v5-core/SKILL.md).
• Rebuilding a composite as a literal prop-for-prop port. v4 composites had large configuration surfaces (*Style objects, callback inputs) with no v5 equivalent — port the behavior, not the configuration, using cometchat-angular-v5-placement's real recipes as the target.
• Assuming every DataSourceDecorator needs MessageBubbleConfigService. Some were registering a built-in extension (polls, stickers, translation) — v5 auto-renders most of those once enabled in the dashboard, with nothing to register (cometchat-angular-v5-features/SKILL.md; verify against needs_stitching in features.angular-v5.json, never assume).

Verify it works

Build/typecheck is green; a repo-wide grep finds NO §2 v4 symbols (composites, CometChatThemeService, DataSource/ChatConfigurator, any *Style object, any bare §2b name unqualified); every kit component is in imports: []; the app renders once init→login resolves; migrated theming follows the OS via ThemeService, not a leftover matchMedia listener. Full per-component prop reference: cometchat-angular-v5-components/references/catalog.md + the docs .md twins.