Initial commit

2025-12-20 16:32:05 +02:00
commit f430c2b757
31 changed files with 4797 additions and 0 deletions
--- a/.context/Autosave
+++ b/.context/Autosave
@@ -0,0 +1,75 @@
+🔍 Problem Summary
+
+You implemented **Local Storage Autosave** (item #2), but **on page reload, the session does not restore the saved state**. The page loads with the default state instead.
+
+---
+
+## 🔎 Likely Root Cause
+
+### ❌ You're saving the state to Local Storage, but **not loading it on startup**.
+
+In `useDrumMachine.ts`, the state is probably initialized like this (or similar):
+
+```ts
+const [state, setState] = useState(defaultState);
+```
+
+This means the state **always starts from `defaultState`**, and no logic attempts to retrieve from `localStorage`.
+
+---
+
+## ✅ Solution
+
+### 🛠 Modify the Initial State to Load from Local Storage
+
+Update your `useDrumMachine` hook to **attempt to load the autosaved session from localStorage first**, before falling back to the default state.
+
+#### ✅ Example Patch:
+
+```ts
+const loadInitialState = (): StateType => {
+  try {
+    const saved = localStorage.getItem('Autosaved Session');
+    if (saved) {
+      const parsed = JSON.parse(saved);
+      return parsed.data;
+    }
+  } catch (e) {
+    console.error('Failed to load autosaved session:', e);
+  }
+  return defaultState;
+};
+
+const [state, setState] = useState(loadInitialState);
+```
+
+---
+
+## 📌 Notes
+
+- Make sure this runs **only for new sessions**, not when joining an existing session.
+    
+- If your app distinguishes between "new session" and "joined session" using `useSession`, you can use that to conditionally load from local storage.
+    
+
+#### Example:
+
+```ts
+const sessionId = useSession();
+const isNewSession = sessionId.startsWith('new-'); // or whatever logic you use
+
+const [state, setState] = useState(() => {
+  if (isNewSession) return loadInitialState();
+  return defaultState;
+});
+```
+
+---
+
+## ✅ Recap
+
+|Problem|Fix|
+|---|---|
+|State always loads from `defaultState`|Load from `localStorage` on first mount|
+|Only autosave was implemented|Add **autosave + restore** for full loop|
+|Make it conditional on session type|Don't overwrite a joined session with autosaved local one|
--- a/.context/Local
+++ b/.context/Local
@@ -0,0 +1,40 @@
+### Local Storage Autosave
+
+#### ✅ Behavior
+
+- All local state changes (either **user-made** or **received from others**) are autosaved into local storage under the key `Autosaved Session`.
+    
+- Throttle or debounce autosaving to reduce performance overhead.
+	-  **Delay** of `750–1500ms` is typically ideal — tweak based on UX feedback.
+	 - Wrap autosave logic in a `useEffect` (for React) that depends on your state.
+	 - **Cancel debounce** on unmount to avoid memory leaks:
+		     ```
+```ts
+useEffect(() => {
+  return () => debouncedAutosave.cancel();
+}, []);
+
+```
+
+#### 🔁 Autosave Trigger Events
+
+- State change from user interaction
+    
+- State update from WebSocket messages
+    
+- After loading a saved session (explained further below)
+    
+
+#### 🧠 Decision Logic on Load
+
+1. **New session**:
+    
+    - Start with default state
+        
+    - Autosave begins immediately
+        
+2. **Join existing session**:
+    
+    - Request full state from server
+        
+    - Begin autosaving once session state is received and applied
--- a/.context/Manual
+++ b/.context/Manual
@@ -0,0 +1,82 @@
+### 1. Manual Save
+
+#### ✅ "Save Session" Button
+
+- Button icon: 🖫 (diskette), with tooltip: "Save session"
+    
+- Opens modal:
+    
+    - Input: name of the session
+        
+    - Option: overwrite existing session with same name (if applicable)
+        
+- Stores:
+    
+    - Name
+        
+    - Timestamp
+        
+    - State (`data`)
+        
+    - `isAutosave: false`
+        
+
+---
+
+### 2. Saved Sessions Panel
+
+#### ✅ Access
+
+- Button/icon to open modal or dropdown with saved sessions
+    
+
+#### 🔁 Display Rules
+
+- Top item: "Autosaved Session" (non-deletable, clearly labeled)
+    
+- Followed by manually saved sessions, **sorted alphabetically by name**
+    
+
+#### ✅ Item UI Elements
+
+- Session name
+    
+- Save timestamp
+    
+- Load button (clickable name)
+    
+- Delete button (only for manual saves)
+    
+    - Delete must open confirmation modal:
+        
+        > “Delete this saved session? This action cannot be undone.”
+        
+
+#### ✅ Loading a Saved Session
+
+- Replaces current app state with the saved one
+    
+- If unsaved changes exist, confirm before loading:
+    
+    > “Load saved session? This will replace your current progress.”
+    
+
+---
+
+### 🧠 Logic Extension: Loading Saved Sessions & Autosave
+
+> ✅ **When the user loads a saved session, autosave continues in the background.**
+
+- The **loaded state becomes the new working session**.
+    
+- All further changes are autosaved into the `Autosaved Session`.
+    
+- The user can still press "Save Session" again:
+    
+    - If using the **same name**, prompt:
+        
+        > “Overwrite the session ‘ChillBeat’? This will replace the saved version.”
+        
+        - Or offer a new name input
+            
+- User can also choose to **delete the older version** after saving.
--- a/.context/task.md
+++ b/.context/task.md
@@ -0,0 +1,76 @@
+Here is a clear and concise explanation of the task for an AI agent to fix the described problem.
+
+---
+
+### **Objective: Fix Session State Synchronization for New Clients**
+
+Your task is to correct a bug in the application's real-time collaboration feature. Currently, when a new client joins an existing session, they see the application's default state, not the session's current, modified state. This creates a state desynchronization issue.
+
+### **Problem Analysis**
+
+The client-side application is already architected to handle an initial state dump upon connection.
+
+1. **`useWebSocket.ts`:** When a message with `type: 'welcome'` is received, the hook is designed to take the `message.payload.state` object and pass it to the application's main state management hook.
+    
+2. **`useDrumMachine.ts`:** This hook has a `useEffect` that listens for incoming messages. It contains a specific `case 'state':` that correctly processes a full state object, updating the grid, bassline, tempo, steps, and other parameters.
+    
+
+The problem is not on the client side. **The root cause is on the server-side WebSocket implementation.**
+
+The server is likely doing one of the following incorrect things:
+
+- It sends a `'welcome'` message that does **not** contain the complete, current state of the session.
+    
+- It sends a `'welcome'` message with an empty or default `state` object.
+    
+- There is a race condition where the server sends the `'welcome'` message _before_ it has finished retrieving the current session state from its data store.
+    
+
+### **Required Implementation**
+
+You must modify the **server-side** WebSocket logic to ensure state is synchronized correctly.
+
+1. **On a new WebSocket connection:** When a client connects and provides a `sessionId`, your server-side code must immediately perform the following steps.
+    
+2. **Retrieve the complete current state** for that `sessionId`. This state must include:
+    
+    - The drum `grid`
+        
+    - The `bassLine`
+        
+    - The current `tempo`
+        
+    - The number of `steps`
+        
+    - The `mutes` array
+        
+    - The `drumVolume`
+        
+    - The `bassVolume`
+        
+3. **Construct a `'welcome'` message.** This message must contain the full state object you just retrieved. The JSON payload sent to the newly connected client must follow this exact structure:
+    
+    JSON
+    
+    ```
+    {
+      "type": "welcome",
+      "payload": {
+        "clientId": "UNIQUE_CLIENT_ID_FOR_NEW_CLIENT",
+        "state": {
+          "grid": [/* current grid state */],
+          "bassLine": [/* current bassline state */],
+          "tempo": 135, // The current tempo
+          "steps": 32,  // The current number of steps
+          "mutes": [false, true, ...], // The current mute states
+          "drumVolume": 0.8,
+          "bassVolume": 0.5
+        }
+      }
+    }
+    ```
+    
+4. **Send this `'welcome'` message** to the newly connected client _immediately_ upon their connection. This must be the very first message they receive, ensuring the UI is rendered with the correct state from the start.
+    
+
+This change will ensure that any client joining an in-progress session will see the exact same state as all other participants, resolving the synchronization bug.
--- a/.context/task2.md
+++ b/.context/task2.md
@@ -0,0 +1,103 @@
+To solve the **desynchronization problem** where **Client 2 sees default state instead of current state**, the AI agent needs to implement **state synchronization on join**. Here's a detailed plan for what needs to be done, which you can feed to an AI agent or developer:
+
+---
+
+## ✅ Problem Summary
+
+* **Client 1** changes app state; changes are broadcast via WebSocket.
+* **Client 2** joins a session but does **not receive the current state** of all elements—only the default.
+* When Client 1 makes further changes, Client 2 sees them, but this causes layout inconsistency since Client 2’s other state is outdated.
+* If Client 2 makes changes, it **overwrites** the correct session state.
+
+---
+
+## 🧠 What the AI Agent Must Do
+
+### 1. **Server: Maintain the Current State per Session**
+
+* In `server.js`, ensure there is a per-session object (e.g., `{ sessionId: stateObject }`) that stores **all element states**.
+* When **Client 1** sends a change message (`{ type: 'update', payload: {...} }`), update that stored session state accordingly.
+
+#### ✅ Example in `server.js`
+
+```js
+const sessions = {}; // { [sessionId]: { state: {...}, clients: [] } }
+
+function handleMessage(message, ws, sessionId) {
+  const data = JSON.parse(message);
+  if (data.type === 'update') {
+    // Update session state
+    if (!sessions[sessionId].state) sessions[sessionId].state = {};
+    sessions[sessionId].state[data.payload.id] = data.payload;
+    
+    // Broadcast to others
+    broadcastExcept(ws, sessionId, message);
+  }
+}
+```
+
+---
+
+### 2. **Client 2: Request the Current Session State on Join**
+
+* When Client 2 connects via WebSocket, it must send a message like:
+
+```json
+{ "type": "get_state" }
+```
+
+---
+
+### 3. **Server: Respond to `get_state` with Full State Snapshot**
+
+* On receiving `{ type: 'get_state' }`, send:
+
+```json
+{ "type": "session_state", "payload": { ...allCurrentState } }
+```
+
+---
+
+### 4. **Client 2: Apply the Session State on First Load**
+
+In `useDrumMachine` (or wherever state is applied), handle a new message type:
+
+```ts
+if (message.type === 'session_state') {
+  applyFullState(message.payload); // update all controls
+}
+```
+
+---
+
+### 5. **(Optional) Mark Synchronization Complete**
+
+* Use a flag like `isSynchronized` on the client to **ignore all inputs** until the full session state is received and applied.
+
+---
+
+## 🧩 Where This Fits in Your Code
+
+* In `App.tsx`, you’re already using a `useWebSocket` hook — you’ll need to modify it so that:
+
+  * On `open`, send `get_state`.
+  * On receiving `session_state`, trigger state application.
+
+* The actual application of state will happen inside `useDrumMachine`.
+
+---
+
+## ✅ Summary Checklist
+
+| Step | Task                                                      |
+| ---- | --------------------------------------------------------- |
+| ✅    | Store session state on server per `sessionId`             |
+| ✅    | Update session state on every change                      |
+| ✅    | On new client connect, send `get_state`                   |
+| ✅    | Server responds with `session_state`                      |
+| ✅    | Client applies full session state before handling updates |
+| ⛔    | Don't allow local edits before sync is complete           |
+
+---
+
+Would you like help modifying the specific `useWebSocket` or `useDrumMachine` code to support this logic?