# Messenger Phase 1 — Friend Groups Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Add full custom friend groups (create / rename / delete / assign) to the existing React friends list, with an Online/Offline-primary view plus a per-group chip filter. **Architecture:** Four new client→server packets (renderer composers + Arcturus handlers) drive category CRUD + friend assignment. The server persists to the existing `messenger_categories` table and the `messenger_friendships.category` column, then re-pushes authoritative state through the **existing** `MessengerInitComposer` (category list) and `UpdateFriendComposer` (a friend's new `categoryId`). The client already receives `categories` via `MessengerInitEvent` and `categoryId` per friend — we add CRUD actions + UI and a pure group-filter helper. **Tech Stack:** Arcturus (Java 21/Maven/HikariCP), Nitro_Render_V3 (TypeScript, yarn workspaces, Vitest), Nitro-V3 (React 19, Vite, Vitest). --- ## Cross-codebase header-ID contract Renderer **Outgoing** header N == Arcturus **Incoming** header N (verified across 8 existing friend packets, e.g. `SET_RELATIONSHIP_STATUS = 3768 == ChangeRelationEvent = 3768`). Phase 1 reuses existing server→client headers, so it needs **4 new client→server header IDs only**, used identically in `OutgoingHeader.ts` (renderer) and `Incoming.java` (Arcturus): | Logical packet | Renderer composer | Arcturus handler | Constant name (both sides) | |---|---|---|---| | Add category | `AddFriendCategoryComposer(name)` | `AddFriendCategoryEvent` | `ADD_FRIEND_CATEGORY` / `AddFriendCategoryEvent` | | Rename category | `RenameFriendCategoryComposer(categoryId, name)` | `RenameFriendCategoryEvent` | `RENAME_FRIEND_CATEGORY` / `RenameFriendCategoryEvent` | | Remove category | `RemoveFriendCategoryComposer(categoryId)` | `RemoveFriendCategoryEvent` | `REMOVE_FRIEND_CATEGORY` / `RemoveFriendCategoryEvent` | | Assign friend → category | `MoveFriendToCategoryComposer(friendId, categoryId)` | `MoveFriendToCategoryEvent` | `MOVE_FRIEND_TO_CATEGORY` / `MoveFriendToCategoryEvent` | The concrete numbers are chosen and verified in **Task 1**. ## File map **Arcturus (`Arcturus-Morningstar-Extended/Emulator/src/main/java/com/eu/habbo/`):** - Modify `messages/incoming/Incoming.java` — 4 new constants - Modify `messages/PacketManager.java` — 4 `registerHandler` lines - Modify `habbohotel/messenger/MessengerBuddy.java` — `setCategoryId(int)` - Modify `habbohotel/users/HabboInfo.java` — `renameMessengerCategory(int, String)` - Create `messages/incoming/friends/AddFriendCategoryEvent.java` - Create `messages/incoming/friends/RenameFriendCategoryEvent.java` - Create `messages/incoming/friends/RemoveFriendCategoryEvent.java` - Create `messages/incoming/friends/MoveFriendToCategoryEvent.java` **Renderer (`Nitro_Render_V3/packages/communication/src/`):** - Modify `messages/outgoing/OutgoingHeader.ts` — 4 constants - Modify `NitroMessages.ts` — imports + 4 `_composers.set` - Modify `messages/outgoing/friendlist/index.ts` — 4 exports - Create `messages/outgoing/friendlist/AddFriendCategoryComposer.ts` - Create `messages/outgoing/friendlist/RenameFriendCategoryComposer.ts` - Create `messages/outgoing/friendlist/RemoveFriendCategoryComposer.ts` - Create `messages/outgoing/friendlist/MoveFriendToCategoryComposer.ts` - Create `messages/outgoing/friendlist/__tests__/FriendCategoryComposers.test.ts` **Client (`Nitro-V3/src/`):** - Create `api/friends/friendCategory.helpers.ts` + `.test.ts` - Modify `api/friends/index.ts` — export helper - Modify `hooks/friends/useFriends.ts` — 4 actions + composer imports - Modify `components/friends/views/friends-list/FriendsListView.tsx` — chip row + filter - Create `components/friends/views/friends-list/FriendsListGroupChipsView.tsx` — chip filter row - Create `components/friends/views/friends-list/FriendsCategoryManagerView.tsx` — create/rename/delete modal - Modify `components/friends/views/friends-list/friends-list-group/FriendsListGroupItemView.tsx` — assign control - Modify `css/friends/FriendsView.css` — chip + manager + assign styles --- ## Task 1: Allocate & verify the 4 category header IDs **Files:** none yet (decision + verification only). - [ ] **Step 1: Try official IDs, then pick verified-free fallbacks** The user prefers official Habbo revision IDs for category packets. First check whether the connecting revision shipped friend-category management packets: Run (renderer): `grep -rin "categor" Nitro_Render_V3/packages/communication/src/messages/outgoing/OutgoingHeader.ts` Expected: only `MESSENGER_*` friend headers, **no** add/rename/remove/move-category constant. If no official category constants are found (expected — the bundled revision's `OutgoingHeader.ts` has none), use the custom fallback quartet **4081, 4082, 4083, 4084** and verify they are free on BOTH sides. - [ ] **Step 2: Verify the four numbers are unused on both sides** Run: ``` grep -rnE "= ?408[1-4]\b" Nitro_Render_V3/packages/communication/src/messages/outgoing/OutgoingHeader.ts grep -rnE "= ?408[1-4]\b" Arcturus-Morningstar-Extended/Emulator/src/main/java/com/eu/habbo/messages/incoming/Incoming.java ``` Expected: **no output** from either command (the IDs are free). If either prints a match, increment the base (try 4085–4088, etc.) and re-run until both commands return nothing. Record the final quartet here before continuing: ``` ADD_FRIEND_CATEGORY = 4081 RENAME_FRIEND_CATEGORY = 4082 REMOVE_FRIEND_CATEGORY = 4083 MOVE_FRIEND_TO_CATEGORY = 4084 ``` All later tasks reference the **constant names**, so only Tasks 2 and 4 (the constant definitions) carry the raw numbers. If you changed the numbers above, use your values in Tasks 2 and 4. - [ ] **Step 3: No commit** (decision task — nothing changed on disk yet). --- ## Task 2: Renderer — 4 outgoing composers + registration + test **Files:** - Create: `Nitro_Render_V3/packages/communication/src/messages/outgoing/friendlist/AddFriendCategoryComposer.ts` - Create: `Nitro_Render_V3/packages/communication/src/messages/outgoing/friendlist/RenameFriendCategoryComposer.ts` - Create: `Nitro_Render_V3/packages/communication/src/messages/outgoing/friendlist/RemoveFriendCategoryComposer.ts` - Create: `Nitro_Render_V3/packages/communication/src/messages/outgoing/friendlist/MoveFriendToCategoryComposer.ts` - Modify: `Nitro_Render_V3/packages/communication/src/messages/outgoing/OutgoingHeader.ts` - Modify: `Nitro_Render_V3/packages/communication/src/messages/outgoing/friendlist/index.ts` - Modify: `Nitro_Render_V3/packages/communication/src/NitroMessages.ts` - Test: `Nitro_Render_V3/packages/communication/src/messages/outgoing/friendlist/__tests__/FriendCategoryComposers.test.ts` - [ ] **Step 1: Write the failing test** Create `__tests__/FriendCategoryComposers.test.ts`: ```typescript import { describe, expect, it } from 'vitest'; import { AddFriendCategoryComposer } from '../AddFriendCategoryComposer'; import { RenameFriendCategoryComposer } from '../RenameFriendCategoryComposer'; import { RemoveFriendCategoryComposer } from '../RemoveFriendCategoryComposer'; import { MoveFriendToCategoryComposer } from '../MoveFriendToCategoryComposer'; describe('friend category composers', () => { it('AddFriendCategoryComposer carries the name', () => { expect(new AddFriendCategoryComposer('Best friends').getMessageArray()).toEqual([ 'Best friends' ]); }); it('RenameFriendCategoryComposer carries id + name', () => { expect(new RenameFriendCategoryComposer(5, 'Staff').getMessageArray()).toEqual([ 5, 'Staff' ]); }); it('RemoveFriendCategoryComposer carries the id', () => { expect(new RemoveFriendCategoryComposer(7).getMessageArray()).toEqual([ 7 ]); }); it('MoveFriendToCategoryComposer carries friendId + categoryId', () => { expect(new MoveFriendToCategoryComposer(42, 3).getMessageArray()).toEqual([ 42, 3 ]); }); }); ``` - [ ] **Step 2: Run it to confirm it fails** Run: `cd Nitro_Render_V3 && yarn test --run packages/communication/src/messages/outgoing/friendlist/__tests__/FriendCategoryComposers.test.ts` Expected: FAIL — cannot find module `../AddFriendCategoryComposer` (files not created yet). - [ ] **Step 3: Create the four composers** `AddFriendCategoryComposer.ts`: ```typescript import { IMessageComposer } from '@nitrots/api'; export class AddFriendCategoryComposer implements IMessageComposer> { private _data: ConstructorParameters; constructor(name: string) { this._data = [ name ]; } public getMessageArray() { return this._data; } public dispose(): void { return; } } ``` `RenameFriendCategoryComposer.ts`: ```typescript import { IMessageComposer } from '@nitrots/api'; export class RenameFriendCategoryComposer implements IMessageComposer> { private _data: ConstructorParameters; constructor(categoryId: number, name: string) { this._data = [ categoryId, name ]; } public getMessageArray() { return this._data; } public dispose(): void { return; } } ``` `RemoveFriendCategoryComposer.ts`: ```typescript import { IMessageComposer } from '@nitrots/api'; export class RemoveFriendCategoryComposer implements IMessageComposer> { private _data: ConstructorParameters; constructor(categoryId: number) { this._data = [ categoryId ]; } public getMessageArray() { return this._data; } public dispose(): void { return; } } ``` `MoveFriendToCategoryComposer.ts`: ```typescript import { IMessageComposer } from '@nitrots/api'; export class MoveFriendToCategoryComposer implements IMessageComposer> { private _data: ConstructorParameters; constructor(friendId: number, categoryId: number) { this._data = [ friendId, categoryId ]; } public getMessageArray() { return this._data; } public dispose(): void { return; } } ``` - [ ] **Step 4: Run the test to confirm it passes** Run: `cd Nitro_Render_V3 && yarn test --run packages/communication/src/messages/outgoing/friendlist/__tests__/FriendCategoryComposers.test.ts` Expected: PASS (4 tests). - [ ] **Step 5: Add the four header constants** In `OutgoingHeader.ts`, next to the other friend headers (after `public static FRIEND_LIST_UPDATE = 1419;`), add (use your Task 1 numbers): ```typescript public static ADD_FRIEND_CATEGORY = 4081; public static RENAME_FRIEND_CATEGORY = 4082; public static REMOVE_FRIEND_CATEGORY = 4083; public static MOVE_FRIEND_TO_CATEGORY = 4084; ``` - [ ] **Step 6: Export the composers from the friendlist barrel** In `messages/outgoing/friendlist/index.ts`, add: ```typescript export * from './AddFriendCategoryComposer'; export * from './MoveFriendToCategoryComposer'; export * from './RemoveFriendCategoryComposer'; export * from './RenameFriendCategoryComposer'; ``` - [ ] **Step 7: Register the composers in NitroMessages** First find how friendlist composers are imported in `NitroMessages.ts`: Run: `grep -n "SendMessageComposer" Nitro_Render_V3/packages/communication/src/NitroMessages.ts` This shows both the import line and the `_composers.set(...)` line. Add the four classes to that same import statement (the one that imports `SendMessageComposer`, `SetRelationshipStatusComposer`, etc.). Then, next to `this._composers.set(OutgoingHeader.SET_RELATIONSHIP_STATUS, SetRelationshipStatusComposer);`, add: ```typescript this._composers.set(OutgoingHeader.ADD_FRIEND_CATEGORY, AddFriendCategoryComposer); this._composers.set(OutgoingHeader.RENAME_FRIEND_CATEGORY, RenameFriendCategoryComposer); this._composers.set(OutgoingHeader.REMOVE_FRIEND_CATEGORY, RemoveFriendCategoryComposer); this._composers.set(OutgoingHeader.MOVE_FRIEND_TO_CATEGORY, MoveFriendToCategoryComposer); ``` - [ ] **Step 8: Type-check + full test run** Run: `cd Nitro_Render_V3 && yarn compile:fast && yarn test --run` Expected: compile clean; all tests pass (138 prior + 4 new = 142). - [ ] **Step 9: Commit** ```bash cd Nitro_Render_V3 git add packages/communication/src/messages/outgoing/friendlist/ packages/communication/src/messages/outgoing/OutgoingHeader.ts packages/communication/src/NitroMessages.ts git commit -m "feat(messenger): add friend-category client composers (add/rename/remove/move)" ``` --- ## Task 3: Emulator — category persistence helpers **Files:** - Modify: `Arcturus-Morningstar-Extended/Emulator/src/main/java/com/eu/habbo/habbohotel/messenger/MessengerBuddy.java` - Modify: `Arcturus-Morningstar-Extended/Emulator/src/main/java/com/eu/habbo/habbohotel/users/HabboInfo.java` > The emulator has **no unit-test infrastructure** (confirmed: no `src/test`, no JUnit in `pom.xml`). Verification for Tasks 3–4 is a successful `mvn package` + the manual integration checklist in Task 11. - [ ] **Step 1: Add `setCategoryId` to MessengerBuddy** `MessengerBuddy` already has `private int categoryId = 0;`, `private int userOne = 0;` (the owner's id), `this.id` (the friend's id), and `getCategoryId()`. Mirror the existing `setRelation`/`run()` DB idiom. Add after `getCategoryId()` (around line 141): ```java public void setCategoryId(int categoryId) { this.categoryId = categoryId; final int cat = categoryId; final int owner = this.userOne; final int friend = this.id; Emulator.getThreading().run(() -> { try (Connection connection = Emulator.getDatabase().getDataSource().getConnection(); PreparedStatement statement = connection.prepareStatement("UPDATE messenger_friendships SET category = ? WHERE user_one_id = ? AND user_two_id = ?")) { statement.setInt(1, cat); statement.setInt(2, owner); statement.setInt(3, friend); statement.execute(); } catch (SQLException e) { LOGGER.error("Caught SQL exception", e); } }); } ``` (`Connection`, `PreparedStatement`, `SQLException`, `Emulator`, and `LOGGER` are already imported in this file.) - [ ] **Step 2: Add `renameMessengerCategory` to HabboInfo** `HabboInfo` already has `loadMessengerCategories()`, `addMessengerCategory(MessengerCategory)` (INSERT + sets generated id), `deleteMessengerCategory(MessengerCategory)` (removes + DELETE via `SqlQueries.update`), and `getMessengerCategories()`. Add a rename helper after `deleteMessengerCategory` (around line 238), reusing the same `SqlQueries.update` idiom: ```java public void renameMessengerCategory(int categoryId, String name) { for (MessengerCategory category : this.messengerCategories) { if (category.getId() == categoryId) { category.setName(name); break; } } try { SqlQueries.update("UPDATE messenger_categories SET name = ? WHERE id = ? AND user_id = ?", name, categoryId, this.id); } catch (SqlQueries.DataAccessException e) { LOGGER.error("Caught SQL exception", e); } } ``` (`SqlQueries`, `MessengerCategory`, and `LOGGER` are already imported/available in this file.) - [ ] **Step 3: Compile** Run: `cd Arcturus-Morningstar-Extended/Emulator && mvn -q compile` Expected: BUILD SUCCESS (no compile errors). - [ ] **Step 4: Commit** ```bash cd Arcturus-Morningstar-Extended git add Emulator/src/main/java/com/eu/habbo/habbohotel/messenger/MessengerBuddy.java Emulator/src/main/java/com/eu/habbo/habbohotel/users/HabboInfo.java git commit -m "feat(messenger): persist friend category assignment + category rename" ``` --- ## Task 4: Emulator — 4 incoming handlers + registration **Files:** - Create: `Arcturus-Morningstar-Extended/Emulator/src/main/java/com/eu/habbo/messages/incoming/friends/AddFriendCategoryEvent.java` - Create: `.../friends/RenameFriendCategoryEvent.java` - Create: `.../friends/RemoveFriendCategoryEvent.java` - Create: `.../friends/MoveFriendToCategoryEvent.java` - Modify: `.../messages/incoming/Incoming.java` - Modify: `.../messages/PacketManager.java` - [ ] **Step 1: Add the 4 header constants to Incoming.java** Next to the other friend constants (e.g. after `public static final int InviteFriendsEvent = 1276;`), add (use your Task 1 numbers — must match the renderer): ```java public static final int AddFriendCategoryEvent = 4081; public static final int RenameFriendCategoryEvent = 4082; public static final int RemoveFriendCategoryEvent = 4083; public static final int MoveFriendToCategoryEvent = 4084; ``` - [ ] **Step 2: Create AddFriendCategoryEvent** Caps: ≤ 20 categories/user, name 1–25 chars, case-insensitive de-dupe. Persists via the existing `HabboInfo.addMessengerCategory` (which sets the generated id), then re-pushes the category list with the existing `MessengerInitComposer`. ```java package com.eu.habbo.messages.incoming.friends; import com.eu.habbo.habbohotel.messenger.MessengerCategory; import com.eu.habbo.habbohotel.users.Habbo; import com.eu.habbo.messages.incoming.MessageHandler; import com.eu.habbo.messages.outgoing.friends.MessengerInitComposer; public class AddFriendCategoryEvent extends MessageHandler { @Override public void handle() throws Exception { String name = this.packet.readString(); Habbo habbo = this.client.getHabbo(); if (habbo == null || name == null) return; name = name.trim(); if (name.isEmpty() || name.length() > 25) return; if (habbo.getHabboInfo().getMessengerCategories().size() >= 20) return; for (MessengerCategory existing : habbo.getHabboInfo().getMessengerCategories()) { if (existing.getName().equalsIgnoreCase(name)) return; } MessengerCategory category = new MessengerCategory(name, habbo.getHabboInfo().getId(), 0); habbo.getHabboInfo().addMessengerCategory(category); this.client.sendResponse(new MessengerInitComposer(habbo)); } } ``` - [ ] **Step 3: Create RenameFriendCategoryEvent** ```java package com.eu.habbo.messages.incoming.friends; import com.eu.habbo.habbohotel.messenger.MessengerCategory; import com.eu.habbo.habbohotel.users.Habbo; import com.eu.habbo.messages.incoming.MessageHandler; import com.eu.habbo.messages.outgoing.friends.MessengerInitComposer; public class RenameFriendCategoryEvent extends MessageHandler { @Override public void handle() throws Exception { int categoryId = this.packet.readInt(); String name = this.packet.readString(); Habbo habbo = this.client.getHabbo(); if (habbo == null || name == null) return; name = name.trim(); if (name.isEmpty() || name.length() > 25) return; boolean found = false; for (MessengerCategory category : habbo.getHabboInfo().getMessengerCategories()) { if (category.getId() == categoryId) { found = true; break; } } if (!found) return; habbo.getHabboInfo().renameMessengerCategory(categoryId, name); this.client.sendResponse(new MessengerInitComposer(habbo)); } } ``` - [ ] **Step 4: Create RemoveFriendCategoryEvent** Deleting a group resets its members to category `0`, pushing each via the existing `UpdateFriendComposer`, then re-pushes the (now shorter) category list. ```java package com.eu.habbo.messages.incoming.friends; import com.eu.habbo.habbohotel.messenger.MessengerBuddy; import com.eu.habbo.habbohotel.messenger.MessengerCategory; import com.eu.habbo.habbohotel.users.Habbo; import com.eu.habbo.messages.incoming.MessageHandler; import com.eu.habbo.messages.outgoing.friends.MessengerInitComposer; import com.eu.habbo.messages.outgoing.friends.UpdateFriendComposer; public class RemoveFriendCategoryEvent extends MessageHandler { @Override public void handle() throws Exception { int categoryId = this.packet.readInt(); Habbo habbo = this.client.getHabbo(); if (habbo == null) return; MessengerCategory target = null; for (MessengerCategory category : habbo.getHabboInfo().getMessengerCategories()) { if (category.getId() == categoryId) { target = category; break; } } if (target == null) return; habbo.getHabboInfo().deleteMessengerCategory(target); for (MessengerBuddy buddy : habbo.getMessenger().getFriends().values()) { if (buddy.getCategoryId() == categoryId) { buddy.setCategoryId(0); this.client.sendResponse(new UpdateFriendComposer(habbo, buddy, 0)); } } this.client.sendResponse(new MessengerInitComposer(habbo)); } } ``` - [ ] **Step 5: Create MoveFriendToCategoryEvent** `categoryId == 0` means "uncategorized"; any other id must be an existing category. Persists via `MessengerBuddy.setCategoryId` and pushes the updated friend via `UpdateFriendComposer`. ```java package com.eu.habbo.messages.incoming.friends; import com.eu.habbo.habbohotel.messenger.MessengerBuddy; import com.eu.habbo.habbohotel.messenger.MessengerCategory; import com.eu.habbo.habbohotel.users.Habbo; import com.eu.habbo.messages.incoming.MessageHandler; import com.eu.habbo.messages.outgoing.friends.UpdateFriendComposer; public class MoveFriendToCategoryEvent extends MessageHandler { @Override public void handle() throws Exception { int friendId = this.packet.readInt(); int categoryId = this.packet.readInt(); Habbo habbo = this.client.getHabbo(); if (habbo == null) return; MessengerBuddy buddy = habbo.getMessenger().getFriends().get(friendId); if (buddy == null) return; if (categoryId != 0) { boolean exists = false; for (MessengerCategory category : habbo.getHabboInfo().getMessengerCategories()) { if (category.getId() == categoryId) { exists = true; break; } } if (!exists) return; } buddy.setCategoryId(categoryId); this.client.sendResponse(new UpdateFriendComposer(habbo, buddy, 0)); } } ``` - [ ] **Step 6: Register the 4 handlers** In `PacketManager.java`, inside `registerFriends()`, add: ```java this.registerHandler(Incoming.AddFriendCategoryEvent, AddFriendCategoryEvent.class); this.registerHandler(Incoming.RenameFriendCategoryEvent, RenameFriendCategoryEvent.class); this.registerHandler(Incoming.RemoveFriendCategoryEvent, RemoveFriendCategoryEvent.class); this.registerHandler(Incoming.MoveFriendToCategoryEvent, MoveFriendToCategoryEvent.class); ``` Then add the four imports near the other `com.eu.habbo.messages.incoming.friends.*` imports at the top of the file: ```java import com.eu.habbo.messages.incoming.friends.AddFriendCategoryEvent; import com.eu.habbo.messages.incoming.friends.RenameFriendCategoryEvent; import com.eu.habbo.messages.incoming.friends.RemoveFriendCategoryEvent; import com.eu.habbo.messages.incoming.friends.MoveFriendToCategoryEvent; ``` (If `PacketManager.java` already uses a wildcard `import com.eu.habbo.messages.incoming.friends.*;`, skip the explicit imports — check with `grep -n "incoming.friends" PacketManager.java` first.) - [ ] **Step 7: Build the fat jar** Run: `cd Arcturus-Morningstar-Extended/Emulator && mvn -q clean package -DskipTests` Expected: BUILD SUCCESS; jar produced under `target/`. A failure here most likely means a duplicate header (the `registerHandler` guard throws `Header already registered`) — return to Task 1 and pick different free IDs. - [ ] **Step 8: Commit** ```bash cd Arcturus-Morningstar-Extended git add Emulator/src/main/java/com/eu/habbo/messages/incoming/friends/ Emulator/src/main/java/com/eu/habbo/messages/incoming/Incoming.java Emulator/src/main/java/com/eu/habbo/messages/PacketManager.java git commit -m "feat(messenger): friend-category CRUD + assign packet handlers" ``` --- ## Task 5: Client — pure group-filter helper (TDD) **Files:** - Create: `Nitro-V3/src/api/friends/friendCategory.helpers.ts` - Test: `Nitro-V3/src/api/friends/friendCategory.helpers.test.ts` - Modify: `Nitro-V3/src/api/friends/index.ts` - [ ] **Step 1: Write the failing test** `friendCategory.helpers.test.ts`: ```typescript import { describe, expect, it } from 'vitest'; import { MessengerFriend } from './MessengerFriend'; import { countFriendsByCategory, filterFriendsByCategory } from './friendCategory.helpers'; const makeFriend = (id: number, categoryId: number): MessengerFriend => { const friend = new MessengerFriend(); friend.id = id; friend.categoryId = categoryId; return friend; }; describe('filterFriendsByCategory', () => { const friends = [ makeFriend(1, 0), makeFriend(2, 5), makeFriend(3, 5), makeFriend(4, 8) ]; it('returns all friends when categoryId is 0 (All)', () => { expect(filterFriendsByCategory(friends, 0)).toHaveLength(4); }); it('returns only the friends in the given category', () => { expect(filterFriendsByCategory(friends, 5).map(f => f.id)).toEqual([ 2, 3 ]); }); it('returns an empty array for a category with no members', () => { expect(filterFriendsByCategory(friends, 99)).toEqual([]); }); it('is null-safe', () => { expect(filterFriendsByCategory(null, 5)).toEqual([]); }); }); describe('countFriendsByCategory', () => { const friends = [ makeFriend(1, 0), makeFriend(2, 5), makeFriend(3, 5) ]; it('counts members per category id', () => { const counts = countFriendsByCategory(friends); expect(counts.get(0)).toBe(1); expect(counts.get(5)).toBe(2); }); it('is null-safe', () => { expect(countFriendsByCategory(null).size).toBe(0); }); }); ``` - [ ] **Step 2: Run it to confirm it fails** Run: `cd Nitro-V3 && yarn test --run src/api/friends/friendCategory.helpers.test.ts` Expected: FAIL — cannot resolve `./friendCategory.helpers`. - [ ] **Step 3: Implement the helper** `friendCategory.helpers.ts`: ```typescript import { MessengerFriend } from './MessengerFriend'; /** * Filter a friend list to a single category. categoryId 0 means * "All" (no filtering) and returns the list unchanged. */ export const filterFriendsByCategory = (friends: MessengerFriend[], categoryId: number): MessengerFriend[] => { if(!friends) return []; if(!categoryId) return friends; return friends.filter(friend => (friend.categoryId === categoryId)); }; /** * Count how many friends belong to each category id. Used to render * member counts on the group chips. */ export const countFriendsByCategory = (friends: MessengerFriend[]): Map => { const counts = new Map(); if(!friends) return counts; for(const friend of friends) { counts.set(friend.categoryId, (counts.get(friend.categoryId) ?? 0) + 1); } return counts; }; ``` - [ ] **Step 4: Run the test to confirm it passes** Run: `cd Nitro-V3 && yarn test --run src/api/friends/friendCategory.helpers.test.ts` Expected: PASS (6 cases). - [ ] **Step 5: Export from the friends api barrel** In `src/api/friends/index.ts`, add: ```typescript export * from './friendCategory.helpers'; ``` - [ ] **Step 6: Commit** ```bash cd Nitro-V3 git add src/api/friends/friendCategory.helpers.ts src/api/friends/friendCategory.helpers.test.ts src/api/friends/index.ts git -c user.name=simoleo89 -c user.email=simoleo89@users.noreply.github.com commit -m "feat(friends): pure category filter + count helpers" ``` --- ## Task 6: Client — category CRUD + assign actions in the friends store **Files:** - Modify: `Nitro-V3/src/hooks/friends/useFriends.ts` The store re-pushes authoritative state through the server (the existing `MessengerInitEvent` handler updates `settings.categories`; `FriendListUpdateEvent` updates each friend's `categoryId`), so these actions are thin send-wrappers — no optimistic local mutation. - [ ] **Step 1: Import the new composers** In the top import from `@nitrots/nitro-renderer` in `useFriends.ts`, add `AddFriendCategoryComposer`, `MoveFriendToCategoryComposer`, `RemoveFriendCategoryComposer`, `RenameFriendCategoryComposer` to the named-import list. - [ ] **Step 2: Add the four actions inside `useFriendsStore`** Add alongside `followFriend` / `updateRelationship` (around line 42), before the `return`: ```typescript const addCategory = (name: string) => { const trimmed = (name ?? '').trim(); if(!trimmed.length || (trimmed.length > 25)) return; SendMessageComposer(new AddFriendCategoryComposer(trimmed)); }; const renameCategory = (categoryId: number, name: string) => { const trimmed = (name ?? '').trim(); if(!categoryId || !trimmed.length || (trimmed.length > 25)) return; SendMessageComposer(new RenameFriendCategoryComposer(categoryId, trimmed)); }; const removeCategory = (categoryId: number) => { if(!categoryId) return; SendMessageComposer(new RemoveFriendCategoryComposer(categoryId)); }; const moveFriendToCategory = (friendId: number, categoryId: number) => { if(!friendId) return; SendMessageComposer(new MoveFriendToCategoryComposer(friendId, categoryId)); }; ``` - [ ] **Step 3: Expose them from the store return** In `useFriendsStore`'s `return { ... }` add: `addCategory, renameCategory, removeCategory, moveFriendToCategory`. - [ ] **Step 4: Expose them via `useFriendsActions`** In the `useFriendsActions` destructure-from-`useBetween` AND its `return`, add the four names so consumers can pull them: ```typescript export const useFriendsActions = () => { const { requestFriend, requestResponse, followFriend, updateRelationship, addCategory, renameCategory, removeCategory, moveFriendToCategory } = useBetween(useFriendsStore); return { requestFriend, requestResponse, followFriend, updateRelationship, addCategory, renameCategory, removeCategory, moveFriendToCategory }; }; ``` (The deprecated `useFriends` shim returns the whole store, so it picks these up automatically.) - [ ] **Step 5: Type-check + full test run** Run: `cd Nitro-V3 && yarn typecheck && yarn test --run` Expected: typecheck clean; all tests pass (no regressions). - [ ] **Step 6: Commit** ```bash cd Nitro-V3 git add src/hooks/friends/useFriends.ts git -c user.name=simoleo89 -c user.email=simoleo89@users.noreply.github.com commit -m "feat(friends): category CRUD + assign actions in friends store" ``` --- ## Task 7: Client — group chip-filter row **Files:** - Create: `Nitro-V3/src/components/friends/views/friends-list/FriendsListGroupChipsView.tsx` - Modify: `Nitro-V3/src/components/friends/views/friends-list/FriendsListView.tsx` - [ ] **Step 1: Create the chip row component** It renders an "All" chip plus one chip per category (with member count), and a gear button to open the manager (wired in Task 8). It is a controlled component: parent owns `selectedCategoryId`. ```tsx import { FC } from 'react'; import { FriendCategoryData } from '@nitrots/nitro-renderer'; import { countFriendsByCategory, LocalizeText, MessengerFriend } from '../../../../api'; import { Flex } from '../../../../common'; interface FriendsListGroupChipsViewProps { categories: FriendCategoryData[]; friends: MessengerFriend[]; selectedCategoryId: number; setSelectedCategoryId: (id: number) => void; onManageClick: () => void; } export const FriendsListGroupChipsView: FC = props => { const { categories = [], friends = [], selectedCategoryId = 0, setSelectedCategoryId = null, onManageClick = null } = props; const counts = countFriendsByCategory(friends); return (
setSelectedCategoryId(0) }> { LocalizeText('friendlist.friends') } ({ friends.length })
{ categories.map(category => (
setSelectedCategoryId(category.id) }> { category.name } ({ counts.get(category.id) ?? 0 })
)) }
⚙
); }; ``` (If `Flex` is not exported from `../../../../common`, check the import other friends views use — `FriendsListView.tsx` already imports `Flex`, `Button` from `../../../../common`; match that path.) - [ ] **Step 2: Wire the chip row + filtering into FriendsListView** In `FriendsListView.tsx`: 1. Add imports: ```tsx import { useState } from 'react'; import { filterFriendsByCategory } from '../../../../api'; import { FriendsListGroupChipsView } from './FriendsListGroupChipsView'; import { FriendsCategoryManagerView } from './FriendsCategoryManagerView'; ``` (`useState` may already be imported — merge into the existing react import. `FriendsCategoryManagerView` is created in Task 8; this import is fine to add now and will resolve after Task 8.) 2. Pull `settings` from the friends state hook used in this component (it already destructures from `useFriendsState`/`useFriends`). Ensure `settings` (and `friends` for the unfiltered counts) are in scope: ```tsx const { onlineFriends, offlineFriends, requests, settings, friends } = useFriendsState(); ``` (Adjust to match the existing hook call in this file — keep whatever names it already destructures and add `settings` + `friends`.) 3. Add local UI state near the other `useState` calls: ```tsx const [ selectedCategoryId, setSelectedCategoryId ] = useState(0); const [ showCategoryManager, setShowCategoryManager ] = useState(false); const categories = settings?.categories ?? []; const filteredOnlineFriends = filterFriendsByCategory(onlineFriends, selectedCategoryId); const filteredOfflineFriends = filterFriendsByCategory(offlineFriends, selectedCategoryId); ``` 4. Insert the chip row directly under `` (before the ``): ```tsx setShowCategoryManager(true) } /> ``` 5. Replace every reference to `onlineFriends` / `offlineFriends` that feeds the **rendered list and counts** with the filtered versions (six edits): - online section header count: `(${ filteredOnlineFriends.length })` - online `select_all` toolbar: map/every over `filteredOnlineFriends` - online `` - offline section header count: `(${ filteredOfflineFriends.length })` - offline `select_all` toolbar: map/every over `filteredOfflineFriends` - offline `` (Leave the unfiltered `friends` for the chip counts and `onlineFriends`/`offlineFriends` references that are NOT about the rendered sections, if any.) 6. Render the manager modal at the end of the returned fragment (next to the existing `showRoomInvite` / `showRemoveFriendsConfirmation` blocks): ```tsx { showCategoryManager && setShowCategoryManager(false) } /> } ``` - [ ] **Step 3: Type-check** Run: `cd Nitro-V3 && yarn typecheck` Expected: clean (a TS2307 for `FriendsCategoryManagerView` is acceptable here only until Task 8 lands; if you implement Task 8 next there should be no errors). If you want a green checkpoint now, temporarily comment the manager import + render block, then restore in Task 8. - [ ] **Step 4: Commit** ```bash cd Nitro-V3 git add src/components/friends/views/friends-list/FriendsListGroupChipsView.tsx src/components/friends/views/friends-list/FriendsListView.tsx git -c user.name=simoleo89 -c user.email=simoleo89@users.noreply.github.com commit -m "feat(friends): group chip-filter row over online/offline list" ``` --- ## Task 8: Client — category manager (create / rename / delete) **Files:** - Create: `Nitro-V3/src/components/friends/views/friends-list/FriendsCategoryManagerView.tsx` - [ ] **Step 1: Create the manager modal** A small `NitroCardView` with an add-input and a list of categories, each with inline rename + delete. Uses `useFriendsActions`. ```tsx import { FC, useState } from 'react'; import { FriendCategoryData } from '@nitrots/nitro-renderer'; import { LocalizeText } from '../../../../api'; import { Button, Column, Flex, NitroCardContentView, NitroCardHeaderView, NitroCardView } from '../../../../common'; import { useFriendsActions } from '../../../../hooks'; interface FriendsCategoryManagerViewProps { categories: FriendCategoryData[]; onCloseClick: () => void; } export const FriendsCategoryManagerView: FC = props => { const { categories = [], onCloseClick = null } = props; const { addCategory, renameCategory, removeCategory } = useFriendsActions(); const [ newName, setNewName ] = useState(''); const [ editingId, setEditingId ] = useState(0); const [ editingName, setEditingName ] = useState(''); const submitAdd = () => { const trimmed = newName.trim(); if(!trimmed.length) return; addCategory(trimmed); setNewName(''); }; const submitRename = () => { const trimmed = editingName.trim(); if(editingId && trimmed.length) renameCategory(editingId, trimmed); setEditingId(0); setEditingName(''); }; return ( setNewName(event.target.value) } onKeyDown={ event => (event.key === 'Enter') && submitAdd() } /> { categories.map(category => ( { (editingId === category.id) ? <> setEditingName(event.target.value) } onKeyDown={ event => (event.key === 'Enter') && submitRename() } /> : <> { category.name }
{ setEditingId(category.id); setEditingName(category.name); } } />
removeCategory(category.id) } /> } )) } { !categories.length && { LocalizeText('friendlist.friends.offlinecaption') } } ); }; ``` > **Verify imports against the codebase.** `Column`, `Flex`, `Button`, and the `NitroCard*` components come from `../../../../common`; confirm the exact set with `grep -n "from '../../../../common'" src/components/friends/views/friends-list/FriendsListView.tsx`. The localization keys above (`generic.create` / `generic.save` / `generic.edit` / `generic.delete`) are placeholders for whatever your locale files already define — if a key renders raw, swap it for an existing one or add it to the locale JSON. The `icon-edit` / `icon-deselect` spritesheet classes: reuse whatever exists in `FriendsView.css`; if absent, use a plain text label ("✎" / "✕") instead. - [ ] **Step 2: Type-check + test** Run: `cd Nitro-V3 && yarn typecheck && yarn test --run` Expected: clean; tests green. (If you commented the manager wiring in Task 7 Step 3, restore it now.) - [ ] **Step 3: Commit** ```bash cd Nitro-V3 git add src/components/friends/views/friends-list/FriendsCategoryManagerView.tsx src/components/friends/views/friends-list/FriendsListView.tsx git -c user.name=simoleo89 -c user.email=simoleo89@users.noreply.github.com commit -m "feat(friends): create/rename/delete group manager" ``` --- ## Task 9: Client — per-friend "assign to group" control **Files:** - Modify: `Nitro-V3/src/components/friends/views/friends-list/friends-list-group/FriendsListGroupItemView.tsx` - [ ] **Step 1: Add categories + action to the component** At the top of the component body, pull categories from state and the move action from actions: ```tsx import { useFriendsActions, useFriendsState } from '../../../../../hooks'; ``` (Match the existing relative depth — this file is one level deeper than `FriendsListView.tsx`, so it's `../../../../../hooks`; confirm with the file's existing imports.) Inside the component: ```tsx const { settings } = useFriendsState(); const { moveFriendToCategory } = useFriendsActions(); const [ isGroupMenuOpen, setIsGroupMenuOpen ] = useState(false); const categories = settings?.categories ?? []; ``` (`useState` is likely already imported; if not, add it.) - [ ] **Step 2: Add the assign control to the actions row** In the `friends-list-actions` div (currently the follow / chat / relationship icons), add — only when the friend is a real user (`friend.id > 0`) and at least one category exists — a group icon that toggles a small menu: ```tsx { (friend.id > 0) && (categories.length > 0) &&
setIsGroupMenuOpen(prev => !prev) } /> { isGroupMenuOpen &&
{ moveFriendToCategory(friend.id, 0); setIsGroupMenuOpen(false); } }> { LocalizeText('friendlist.friends') }
{ categories.map(category => (
{ moveFriendToCategory(friend.id, category.id); setIsGroupMenuOpen(false); } }> { category.name }
)) }
}
} ``` (Reuse an existing spritesheet class for `icon-group` if one fits, or fall back to a text glyph. The "uncategorized" entry uses `friend.categoryId === 0`.) - [ ] **Step 3: Type-check + test** Run: `cd Nitro-V3 && yarn typecheck && yarn test --run` Expected: clean; tests green. - [ ] **Step 4: Commit** ```bash cd Nitro-V3 git add src/components/friends/views/friends-list/friends-list-group/FriendsListGroupItemView.tsx git -c user.name=simoleo89 -c user.email=simoleo89@users.noreply.github.com commit -m "feat(friends): per-friend assign-to-group control" ``` --- ## Task 10: Client — styles for chips, manager, assign menu **Files:** - Modify: `Nitro-V3/src/css/friends/FriendsView.css` - [ ] **Step 1: Append styles** Match the existing palette in this file (grays `#f3f3ef`/`#e6e6e6`, accent blue `#bfe7f6`, `#111` text). Append: ```css .friends-group-chips { border-bottom: 1px solid #e6e6e6; } .friends-group-chips-scroll { overflow-x: auto; flex-wrap: nowrap; } .friends-group-chips-scroll::-webkit-scrollbar { height: 4px; } .friends-group-chip { flex: 0 0 auto; padding: 1px 8px; border: 1px solid #d0d0c8; border-radius: 10px; background: #f3f3ef; font-size: 11px; line-height: 16px; white-space: nowrap; cursor: pointer; user-select: none; } .friends-group-chip.active { background: #bfe7f6; border-color: #7fb9d6; } .friends-group-chip-manage { padding: 1px 6px; } .nitro-friends-category-manager { width: 280px; } .friends-list-group-assign { display: inline-flex; } .friends-list-group-menu { position: absolute; right: 0; top: 100%; z-index: 20; min-width: 120px; max-height: 180px; overflow-y: auto; background: #fff; border: 1px solid #c0c0b8; border-radius: 4px; box-shadow: 0 2px 6px rgba(0, 0, 0, 0.2); } .friends-list-group-menu-item { padding: 3px 8px; font-size: 11px; cursor: pointer; white-space: nowrap; } .friends-list-group-menu-item:hover { background: #efefef; } .friends-list-group-menu-item.active { background: #bfe7f6; } ``` - [ ] **Step 2: Visual sanity (build only)** Run: `cd Nitro-V3 && yarn typecheck` Expected: clean (CSS isn't type-checked, but confirm nothing else broke). - [ ] **Step 3: Commit** ```bash cd Nitro-V3 git add src/css/friends/FriendsView.css git -c user.name=simoleo89 -c user.email=simoleo89@users.noreply.github.com commit -m "style(friends): group chips, category manager, assign menu" ``` --- ## Task 11: Integration verification (two live sessions) **Files:** none (manual verification + final checks). Fix-up commits only if something fails. - [ ] **Step 1: Apply the DB-side prerequisite check** The `messenger_categories` and `messenger_friendships.category` schema already exist (verified). Confirm against the running DB: ``` SELECT COUNT(*) FROM messenger_categories; SHOW COLUMNS FROM messenger_friendships LIKE 'category'; ``` (Per house rules, if a destructive statement is ever needed, hand the user a one-liner to run under `E:\laragon\bin\mysql\...` — but nothing destructive is required here.) - [ ] **Step 2: Run the new emulator jar + client dev server** - Emulator: run the jar built in Task 4 (`java -jar Arcturus-Morningstar-Extended/Emulator/target/Habbo-*-jar-with-dependencies.jar`). - Client: `cd Nitro-V3 && yarn start` (Vite picks up the renderer source live — no renderer build needed). - [ ] **Step 3: Manual test matrix (log in, open Friends)** Verify each: 1. **Create group:** open the manager (⚙), type a name, Create → a new chip appears (server re-pushed `MessengerInit`). 2. **Rename group:** edit a category name → chip label updates after round-trip. 3. **Delete group:** delete a category → chip disappears; any friend that was in it shows as uncategorized (its assign menu no longer marks that group active). 4. **Assign friend:** open a friend's group menu, pick a group → switch the chip filter to that group and confirm the friend appears there; switch to "All" and confirm they still appear once. 5. **Filter:** click each chip → only that group's friends show in both Online and Offline sections; counts in headers match; "All" shows everyone. 6. **Caps:** creating a 21st group is rejected (Create disabled at 20); a >25-char name is truncated by `maxLength`/server. 7. **Persistence:** relog → groups and assignments survive (DB-backed). 8. **No regressions:** follow, chat, relationship icons, requests, search, room-invite, remove-friend still work. - [ ] **Step 4: Final automated checks** Run: ``` cd Nitro_Render_V3 && yarn compile:fast && yarn test --run cd Nitro-V3 && yarn typecheck && yarn test --run && yarn eslint cd Arcturus-Morningstar-Extended/Emulator && mvn -q clean package -DskipTests ``` Expected: renderer tests green (142), client tests green (existing + 6 new helper cases), client typecheck + eslint clean, emulator BUILD SUCCESS. - [ ] **Step 5: Commit any fix-ups** ```bash # only if Step 3/4 required changes cd Nitro-V3 git -c user.name=simoleo89 -c user.email=simoleo89@users.noreply.github.com commit -am "fix(friends): integration fixes for friend groups" ``` --- ## Notes for the next phase - Phase 2 (offline messages) reuses the same `FriendChatMessageComposer` replay path — no new packets — and the `messenger_offline` table that already exists. - Phases 3–4 (read receipts, typing) will add custom packets following the same renderer-composer/Arcturus-handler pattern proven here, plus a new server→client event+parser (mirror `NewConsoleMessageEvent`/`NewConsoleMessageParser`) which this phase did not need. - Do NOT push automatically (the auto-push rule is scoped to the react19 branches only). Open PRs against the correct base per the duckietm `--base dev`/`Dev` convention when the user asks.