desktop-team-doc 0.1.0

package/content/docs/knowledge/implementation-guides/cab-integration.md

@@ -0,0 +1,194 @@
+# Adding Cab
+
+*Last Updated: 2025-03-02*
+
+This document outlines the process for integrating new cab assets into the BIAS_ONE_GUI project using the Figma parser tool.
+
+## Overview
+
+The cab integration process involves extracting cab assets from Figma designs, generating the necessary JSON files, and placing the assets in the correct directories within the BIAS_ONE_GUI project. This guide will walk you through each step of the process.
+
+## Cab Reference Data
+
+For cab initialization data, refer to the following Google Spreadsheet:
+[BIAS ONE Cab Reference Data](https://docs.google.com/spreadsheets/d/1GbX8jtDhavA5rNZoTNQ8rY9-fVTb9IS-qhvv1-AMIic/edit?gid=1857417807#gid=1857417807)
+
+### Available Fields in the Spreadsheet
+
+The spreadsheet contains the following fields for each cab:
+
+- **UUID**: Unique identifier for the cab (e.g., "50B743E0-E702-476C-8A62-57FB0B1C0FFD") - *Defined by desktop developers*
+- **DSP Value**: The DSP parameter value used to select this cab in the backend (e.g., 0.001, 0.002) - *Assigned by the DSP team, cannot be modified by desktop developers*
+- **Display Name**: The name shown in the UI (e.g., "Blackface", "British 30") - *Defined by Product Management*
+- **Speaker Configuration**: The speaker layout (e.g., "1x12", "2x12", "4x12") - *Defined by Product Management*
+- **Category**: The cab category (e.g., "Electric Guitar", "Bass", "Acoustic") - *Defined by Product Management*
+- **Display Order**: The order in which cabs appear within their category in the UI - *Defined by Product Management*
+
+### How to Use the Reference Data
+
+When accessing the spreadsheet:
+
+1. **For Adding New Cabs**:
+   - Desktop developers should generate a new UUID
+   - Consult with the DSP team to get an assigned DSP value
+   - Get the display name, speaker configuration, category, and display order from Product Management
+
+2. **For Updating Existing Cabs**:
+   - Reference the spreadsheet to ensure consistency with existing cab configurations
+   - Note that DSP values cannot be modified by desktop developers
+   - Any changes to display names, categories, or other UI elements must be approved by Product Management
+
+3. **For Integration with DSP**:
+   - The DSP value from the spreadsheet (assigned by the DSP team) must be used in the `cabSpeakerBg.json` file to properly map the cab to its visual representation
+   - Never create or modify DSP values without DSP team approval
+
+4. **For UI Integration**:
+   - Use the display name, speaker configuration, category, and display order values (defined by Product Management) when updating the `cabDisplayInfo.json` file
+
+This reference data is essential when adding new cabs to ensure proper integration with both the UI and DSP components of the application.
+
+## Prerequisites
+
+- Access to the Figma design file containing cab designs
+- Node.js installed on your machine
+- BIAS_ONE_GUI project cloned locally
+
+## Step 1: Using the Figma Parser
+
+The Figma parser tool (`tools/gear-figma-parser`) is used to extract cab assets from Figma designs.
+
+### Figma Design Requirements for Cab
+
+- The main node in Figma must be named `cab design`
+- The node should contain:
+  - TEXT: Cab Name (e.g., "Blackface")
+  - TEXT: UUID (e.g., "50B743E0-E702-476C-8A62-57FB0B1C0FFD")
+  - RECTANGLE: Cab on signal path (for thumbnail image)
+
+### Running the Figma Parser
+
+1. Navigate to the `tools/gear-figma-parser` directory:
+   ```bash
+   cd tools/gear-figma-parser
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Run the plugin UI:
+   ```bash
+   npm run watch
+   ```
+
+4. In the Figma Desktop App:
+   - Enable Figma Dev Mode
+   - Under Plugin tab > Click + > Select `Import plugin from manifest` > select the `manifest.json` from the gear-figma-parser directory
+   - Click the plugin and then select the Cab design
+   - Click `Export All` or `Export JSON only` to export assets
+
+The parser will generate:
+- A JSON file with the cab's UUID as the filename
+- A PNG image for the signal path thumbnail named `sigpath-[UUID].png`
+
+## Step 2: Moving Assets to template-cab
+
+1. Move the generated JSON file to the `public/gear/template-cab` directory:
+   ```bash
+   mv [UUID].json public/gear/template-cab/
+   ```
+
+2. Verify that the JSON file contains the cab's UUID:
+   ```json
+   {"id":"[UUID]"}
+   ```
+
+## Step 3: Updating cabDisplayInfo.json
+
+Update the `public/gear/cabDisplayInfo.json` file to include the new cab:
+
+1. Open `public/gear/cabDisplayInfo.json`
+2. Add a new entry to the `data` object:
+   ```json
+   "[UUID]": {
+     "displayName": "Cab Name",
+     "directName": "Speaker Configuration (e.g., 1x12, 2x12, 4x12)",
+     "categoryKey": "Category (e.g., Electric Guitar, Acoustic & Bass)",
+     "displayOrder": [Next available number in the category]
+   }
+   ```
+
+Example:
+```json
+"NEW-UUID-HERE": {
+  "displayName": "New Cab",
+  "directName": "2x12",
+  "categoryKey": "Electric Guitar",
+  "displayOrder": 20
+}
+```
+
+If needed, add a new category to the `category` object:
+```json
+"New Category": "New Category Display Name"
+```
+
+## Step 4: Updating cabSpeakerBg.json
+
+Update the `public/gear/cabSpeakerBg.json` file to map the cab's DSP value to a speaker background image:
+
+1. Open `public/gear/cabSpeakerBg.json`
+2. Add a new entry:
+   ```json
+   "0.XXX": "images/Cab3/Speaker.Default.png"
+   ```
+
+Replace `0.XXX` with the DSP value for the new cab, and use either `Speaker.Default.png` or `Speaker.Spectre.png` as appropriate for the cab type.
+
+## Step 5: Moving Assets to Cab3
+
+If your cab requires a custom speaker background image:
+
+1. Create the speaker background image named according to the cab (e.g., `Speaker.NewCab.png`)
+2. Move the image to the `public/images/Cab3` directory:
+   ```bash
+   mv Speaker.NewCab.png public/images/Cab3/
+   ```
+3. Update the `cabSpeakerBg.json` file to reference this new image:
+   ```json
+   "0.XXX": "images/Cab3/Speaker.NewCab.png"
+   ```
+
+## Step 6: Moving Assets to SigPath/Cab
+
+Move the signal path thumbnail image to the `public/images/SigPath/Cab` directory:
+
+```bash
+mv sigpath-[UUID].png public/images/SigPath/Cab/
+```
+
+This image will be used to display the cab in the signal path view.
+
+## Troubleshooting
+
+### Missing Images
+
+If images are not displaying correctly:
+- Verify that the image paths in `cabSpeakerBg.json` are correct
+- Check that all image files have been moved to the correct directories
+- Ensure that the image filenames match the references in the JSON files
+
+### Cab Not Appearing in UI
+
+If the cab is not appearing in the UI:
+- Verify that the cab has been added to `cabDisplayInfo.json` with the correct UUID
+- Check that the cab's JSON file exists in the `public/gear/template-cab` directory
+- Ensure that the signal path thumbnail image exists in `public/images/SigPath/Cab`
+
+### Figma Parser Issues
+
+If the Figma parser is not generating the expected files:
+- Verify that the Figma design follows the required structure
+- Check that the cab design node is named `cab design`
+- Ensure that the UUID text node contains a valid UUID

package/content/docs/knowledge/implementation-guides/custom-pedal-integration.md

@@ -0,0 +1,309 @@
+# Custom Pedal Integration Guide
+
+*Last Updated: 2025-03-02*
+
+This guide explains how to integrate custom pedals with specialized UI components into BIAS X.
+
+## Overview
+
+BIAS X supports custom pedal interfaces that go beyond standard controls, allowing for specialized interactions like wah pedals with foot controllers, delay units with tape animations, and other unique interfaces. These custom pedals are implemented through:
+
+1. Panel JSON configuration files
+2. Background images
+3. Custom React components
+
+## File Structure and Naming Conventions
+
+### Panel Configuration Files
+
+Panel configuration files follow this naming pattern:
+- `public/panel/DSP.<dspId>.Panel.json` - Main configuration file
+
+### Background Images
+
+Background images follow these naming patterns:
+- `public/panel/DSP.<dspId>.BG.png` - Main panel background
+- `public/panel/DSP.<dspId>.Panel.Board.png` - Pedal board view (for wah-like pedals)
+- `public/panel/DSP.<dspId>.Pedal.BG.png` - Pedal background (for pedalboard view)
+
+## Panel JSON Configuration
+
+### Basic Structure
+
+```json
+{
+  "data": {
+    "id": "dspId",
+    "shouldScale": false,
+    "width": 1000,
+    "height": 600,
+    "ratio": 1,
+    "y": 0,
+    
+    "bg": {
+      "normal": "panel/DSP.dspId.BG.png",
+      "retina": "panel/DSP.dspId.BG@2x.png",
+      "width": 1000,
+      "height": 600,
+      "x": 0,
+      "y": 0
+    },
+    
+    "controls": [
+      // Control definitions
+    ],
+    
+    "powers": [
+      // Power button and LED definitions
+    ],
+    
+    "cables": [
+      // Cable definitions
+    ]
+  }
+}
+```
+
+### Standard Controls
+
+#### Knob Control
+
+```json
+{
+  "pid": 0,
+  "param": "gain",
+  "type": "knob",
+  "width": 60,
+  "height": 60,
+  "x": 100,
+  "y": 200,
+  "res": "knob/chicken-black"
+}
+```
+
+#### Switch Control
+
+```json
+{
+  "pid": 1,
+  "param": "mode",
+  "type": "switch",
+  "width": 40,
+  "height": 40,
+  "x": 200,
+  "y": 300,
+  "res": "switch/toggle-1"
+}
+```
+
+#### Slider Control
+
+```json
+{
+  "pid": 2,
+  "param": "level",
+  "type": "slider",
+  "width": 200,
+  "height": 20,
+  "x": 300,
+  "y": 400,
+  "useSimpleTransform": true,
+  "res": "slider/fader-1"
+}
+```
+
+### Wah-like Pedals
+
+For pedals with specialized foot controller interfaces:
+
+```json
+{
+  "data": {
+    "id": "CryWah",
+    "panel": {
+      "width": 1978,
+      "height": 800,
+      "reflection": {
+        "src": "panel/DSP.CryWah.BG.png",
+        "y": 680
+      },
+      "bg": {
+        "normal": "panel/DSP.CryWah.BG.png",
+        "width": 1978,
+        "height": 800,
+        "x": -30,
+        "y": 0
+      }
+    },
+    "pedal": {
+      "bg": {
+        "normal": "panel/DSP.CryWah.Pedal.BG.png"
+      },
+      "board": {
+        "normal": "panel/DSP.CryWah.Panel.Board.png"
+      },
+      "rotation": {
+        "origin": {
+          "x": 0.5,
+          "y": 0.8
+        },
+        "min": 0,
+        "max": 20
+      }
+    },
+    "decorations": [
+      {
+        "res": "images/Customization/CryWah/screw.png",
+        "width": 1978,
+        "height": 800,
+        "x": -30,
+        "y": 0
+      }
+    ]
+  }
+}
+```
+
+## Custom Component Implementation
+
+For pedals requiring specialized UI beyond standard controls, you need to create custom React components.
+
+### Component Structure
+
+1. Create a directory for your custom pedal:
+   ```
+   src/components/dumbs/addons-pedal-panel/YourPedalName/
+   ```
+
+2. Create an index.tsx file with your component implementation:
+   ```
+   src/components/dumbs/addons-pedal-panel/YourPedalName/index.tsx
+   ```
+
+### Example Implementation
+
+Here's an example of a custom wah pedal implementation. 專案已不再使用 Emotion；新程式請以 Tailwind 或 `style` 實作樣式。
+
+```tsx
+import React from 'react';
+import RotationPedal from '@/src/components/dumbs/pedal-panel-customization/shared/RotationPedal';
+import { ParameterPanel, usePanelStore, usePanelStoreSelector } from '@/src/components/panel-factory/shared';
+import { ROOT_FOLDER } from '@/src/utils/assetUtils';
+
+const PEDAL_IMG_URL = `url(${ROOT_FOLDER}/panel/DSP.CryWah.Panel.Board.png)`;
+
+const PID_FILTER = 0;
+
+const CryWah: ParameterPanel = ({ config }) => {
+  const { updateParameterValue } = usePanelStore().getState();
+  const pidFilter = usePanelStoreSelector((state) => state.parameterValues[PID_FILTER]);
+  const { x, y, height, width } = config.bg;
+
+  return (
+    <RotationPedal
+      value={pidFilter}
+      originX={729 / width}
+      originY={410 / height}
+      minRotationAngle={0}
+      maxRotationAngle={+11}
+      panelXOffset={-30}
+      panelYOffset={0}
+      style={{
+        width: width,
+        height: height,
+        top: y,
+        left: x,
+        backgroundImage: PEDAL_IMG_URL,
+      }}
+      onChange={(value) => updateParameterValue(PID_FILTER, value)}
+    />
+  );
+};
+
+export default CryWah;
+```
+
+### Reusable Components
+
+The system provides several reusable components for building custom pedal interfaces:
+
+- `RotationPedal`: For pedals that rotate (like wah pedals)
+- `ImageKnob`: For custom knob implementations
+- `MaskedBgSlider`: For sliders with custom backgrounds
+- `Toggle`: For toggle switches
+- `Indicator`: For LED indicators
+
+## Registering Custom Components
+
+To make your custom component available in the application, you need to register it in the addons panel map:
+
+1. Open `src/components/panel-factory/shared/customization/addonsPanelMap.tsx`
+2. Import your component:
+   ```tsx
+   const YourPedalName = React.lazy(() => import('@/src/components/dumbs/addons-pedal-panel/YourPedalName'));
+   ```
+3. Add it to the panel map:
+   ```tsx
+   panelMap.set('YourPedalDspId', YourPedalName);
+   ```
+4. For pedals that should be available in pedalboard mode:
+   ```tsx
+   panelMap.set('YourPedalDspId', [YourPedalName, true]);
+   ```
+
+## Integration Process
+
+1. **Create Panel JSON**: Define the panel configuration in `public/panel/DSP.<dspId>.Panel.json`
+2. **Prepare Assets**: Create and place background images in the `public/panel/` directory
+3. **Implement Custom Component**: Create your React component in `src/components/dumbs/addons-pedal-panel/`
+4. **Register Component**: Add your component to the addons panel map
+5. **Test**: Test your implementation in both panel and pedalboard modes
+
+## AddonsContainer Component
+
+The `AddonsContainer` component in `src/components/smarts/pedal-panel/AddonsContainer.tsx` is responsible for rendering the custom pedal components:
+
+```tsx
+export const AddonsContainer: ParameterPanel = (props) => {
+  const { api } = props;
+  const { selectedFx } = usePanelStore().getState();
+  const addonsComp = getAddonsPanel({ ...props, selectedFx });
+  return (
+    <div className={`pedal-panel-v2--addons relative left-0 top-0`}>
+      <Provider store={api.getStore()}>{addonsComp}</Provider>
+    </div>
+  );
+};
+```
+
+This component uses `getAddonsPanel` from `addonsPanelMap.tsx` to retrieve and render the appropriate custom component based on the selected effect.
+
+## Legacy vs. Modern Components
+
+BIAS X supports two types of custom pedal components:
+
+1. **Modern Components**: Located in `src/components/dumbs/addons-pedal-panel/`
+   - Registered in `panelMap`
+   - Used by `AddonsContainer`
+
+2. **Legacy Components**: Located in `src/components/dumbs/pedal-panel-customization/`
+   - Registered in `legacyPanelMap`
+   - Used by `LegacyAddonsContainer`
+
+When creating new custom pedals, use the modern approach with components in the `addons-pedal-panel` directory.
+
+## Best Practices
+
+1. **Component Organization**: Keep all files related to a specific pedal in its own directory
+2. **Parameter Access**: Use `usePanelStoreSelector` to access parameter values
+3. **Parameter Updates**: Use `updateParameterValue` from the panel store to update parameters
+4. **Responsive Design**: Use relative positioning and sizing for proper scaling
+5. **Performance**: Optimize renders using React.memo and useMemo where appropriate
+6. **Reusable Components**: Leverage existing components like RotationPedal for common interactions
+
+## Troubleshooting
+
+1. **Component Not Appearing**: Verify the component is properly registered in the addons panel map
+2. **Parameter Not Updating**: Check that the PID matches the parameter ID in the DSP
+3. **Styling Issues**: Ensure background images are properly referenced and sized
+4. **Performance Issues**: Check for unnecessary re-renders or heavy computations

package/content/docs/knowledge/projects/BIAS_ONE_GUI/README.md

@@ -0,0 +1,17 @@
+# BIAS_ONE_GUI Knowledge Base
+
+Project-specific knowledge for the BIAS_ONE_GUI application.
+
+## Structure
+
+- **architecture/** – State management, native bridge, API clients, component architecture
+- **core-components/** – Signal Path, Panel Factory, Guitar Match, Preset AI, App Navigation
+- **gear-customization/** – Amp, Effect, Cab, Custom Pedal integration
+- **redux-slices/** – Slice and thunk action documentation
+- **services-and-utils/** – Configuration, localization, license, Firebase Remote Config
+
+## Related Documentation
+
+- [Architecture Patterns](../../architecture/) – Team-wide architecture patterns
+- [Implementation Guides](../../implementation-guides/) – Adding amp, FX, cab, custom pedals
+- [Signal Path](../../domain/sigpath.md) – Signal path domain knowledge

package/content/manifest.json

@@ -0,0 +1,122 @@
+{
+  "version": "1",
+  "entries": [
+    {
+      "src": "docs/instructions",
+      "type": "dir",
+      "cursor": ".cursor/docs/instructions",
+      "claude": ".claude/docs/instructions",
+      "roo": ".roo/rules/desktop-team-documentation/instructions",
+      "gemini": ".gemini/docs/instructions",
+      "description": "Coding conventions and workflows"
+    },
+    {
+      "src": "docs/knowledge",
+      "type": "dir",
+      "cursor": ".cursor/docs/knowledge",
+      "claude": ".claude/docs/knowledge",
+      "roo": ".roo/rules/desktop-team-documentation/knowledge",
+      "gemini": ".gemini/docs/knowledge",
+      "description": "Knowledge base (architecture, development, projects, implementation-guides, component-library, domain)"
+    },
+    {
+      "src": "docs/index.md",
+      "type": "file",
+      "cursor": ".cursor/docs/index.md",
+      "claude": ".claude/docs/index.md",
+      "roo": ".roo/rules/desktop-team-documentation/index.md",
+      "gemini": ".gemini/docs/index.md",
+      "description": "Main documentation index"
+    },
+    {
+      "src": "docs/README.md",
+      "type": "file",
+      "cursor": ".cursor/docs/README.md",
+      "claude": ".claude/docs/README.md",
+      "roo": ".roo/rules/desktop-team-documentation/README.md",
+      "gemini": ".gemini/docs/README.md",
+      "description": "Repository README"
+    },
+    {
+      "src": "rules/cpp.mdc",
+      "type": "file",
+      "cursor": ".cursor/rules/cpp.mdc",
+      "claude": ".claude/rules/cpp.mdc",
+      "roo": null,
+      "gemini": ".gemini/rules/cpp.mdc",
+      "description": "Cursor/Claude rule file"
+    },
+    {
+      "src": "rules/frontend.mdc",
+      "type": "file",
+      "cursor": ".cursor/rules/frontend.mdc",
+      "claude": ".claude/rules/frontend.mdc",
+      "roo": null,
+      "gemini": ".gemini/rules/frontend.mdc",
+      "description": "Cursor/Claude rule file"
+    },
+    {
+      "src": "rules/index.mdc",
+      "type": "file",
+      "cursor": ".cursor/rules/index.mdc",
+      "claude": ".claude/rules/index.mdc",
+      "roo": null,
+      "gemini": ".gemini/rules/index.mdc",
+      "description": "Cursor/Claude rule file"
+    },
+    {
+      "src": "rules/knowledge.mdc",
+      "type": "file",
+      "cursor": ".cursor/rules/knowledge.mdc",
+      "claude": ".claude/rules/knowledge.mdc",
+      "roo": null,
+      "gemini": ".gemini/rules/knowledge.mdc",
+      "description": "Cursor/Claude rule file"
+    },
+    {
+      "src": "rules/team-wide.mdc",
+      "type": "file",
+      "cursor": ".cursor/rules/team-wide.mdc",
+      "claude": ".claude/rules/team-wide.mdc",
+      "roo": null,
+      "gemini": ".gemini/rules/team-wide.mdc",
+      "description": "Cursor/Claude rule file"
+    },
+    {
+      "src": "rules/workflows.mdc",
+      "type": "file",
+      "cursor": ".cursor/rules/workflows.mdc",
+      "claude": ".claude/rules/workflows.mdc",
+      "roo": null,
+      "gemini": ".gemini/rules/workflows.mdc",
+      "description": "Cursor/Claude rule file"
+    },
+    {
+      "src": "tools/agents",
+      "type": "dir",
+      "cursor": ".cursor/agents",
+      "claude": ".claude/agents",
+      "roo": null,
+      "gemini": ".gemini/agents",
+      "description": "Agent definitions"
+    },
+    {
+      "src": "tools/skills",
+      "type": "dir",
+      "cursor": ".cursor/skills",
+      "claude": ".claude/skills",
+      "roo": null,
+      "gemini": null,
+      "description": "Skills (from knowledge dirs with SKILL.md)"
+    },
+    {
+      "src": "tools/slash-commands",
+      "type": "dir",
+      "cursor": ".cursor/commands/team",
+      "claude": ".claude/commands/team",
+      "roo": null,
+      "gemini": ".gemini/commands/team",
+      "description": "Slash commands"
+    }
+  ]
+}