Cursor rule

1---
2globs: packages/client/src/**/*
3---
4 
5## Client Adapters (packages/client)
6 
7- **Role**: Bridge between UI (Vue/Pinia) and core (`packages/core`) in both:
8  - **Browser-only mode** (embedded core via `core-runtime` / `core-bridge`).
9  - **Server mode** (WebSocket adapter to `apps/server`).
10- Keep this package thin and focused on:
11  - Event wiring.
12  - Session/account management.
13  - Store updates and derivations for UI consumption.
14 
15### Core Runtime & Bridge
16 
17- `core-runtime`:
18  - Owns the lifecycle of `CoreContext` and DB initialization in browser mode.
19  - Exposes helper methods (`getCtx`, `destroy`, etc.) instead of leaking internal implementation.
20- `core-bridge`:
21  - Manages sessions, the active account slot, and event handler registration.
22  - On account switch:
23    - Destroy the existing `CoreContext`.
24    - Re-register client-side event handlers for the new active account.
25  - Never share a single runtime instance across different account IDs.
26 
27### Events & Type Safety
28 
29- Always go through the typed WebSocket/core event maps:
30  - Use `WsEventToServer`, `WsEventToClient`, and `FromCoreEvent` / `ToCoreEvent` types.
31  - Avoid untyped `any` payloads or generic `Record<string, unknown>` where stronger types are available.
32- When adding new events:
33  - Update the shared `@tg-search/server/types`.
34  - Extend client event handler maps and registration helpers.
35  - Keep the mapping between WS event names and core events explicit.
36 
37### Pinia Stores & Composables
38 
39- Stores in `packages/client` are the **source of truth** for app state:
40  - Use actions to emit events to core and react to `FromCoreEvent` updates.
41  - Avoid duplicating the same state in both `apps/web` and `packages/client`.
42- For reusable logic, prefer composables and pure utilities inside this package rather than re-implementing logic in components.
43 
44### Logging & Error Handling
45 
46- Use `useLogger` with a **component/module name** (e.g. `'CoreBridge'`) for all logs in this package.
47- Log:
48  - High-level intent (event name, account/session IDs).
49  - Errors when event delivery or handler invocation fails.
50- Do not log sensitive payload data (raw messages, tokens, secrets).
51- When something fails:
52  - Prefer emitting a client-facing event that the UI can react to (e.g. a `core:error` or domain-specific failure event).
53  - Avoid throwing unhandled exceptions that would crash the whole bridge.
54 
55