rules

.cursor/rules/plugin.mdc

@@ -0,0 +1,139 @@
+---
+description: "Rojo Studio plugin specifics: Roact patterns, reconciler logic, WebSocket protocol, and plugin testing."
+globs:
+  - "plugin/**/*.lua"
+  - "plugin/**/*.luau"
+  - "plugin/**/*.json"
+---
+
+# Rojo Studio Plugin
+
+Built with Roact (React-like), handles WebSocket sync with server, patch application to Studio, and UI.
+
+**Entry:** `plugin/src/init.server.lua` | **Protocol:** WebSocket v5 | **Must match server MAJOR.MINOR**
+
+## Architecture
+
+### Key Components
+
+**1. UI Layer** (`App/`)
+- **App.lua** - Root component, manages connection state
+- **Components/** - Reusable UI components
+  - `StatusPages/` - Connected, Connecting, Error, Settings screens
+  - `PatchVisualizer/` - Shows changes before applying
+  - `StringDiffVisualizer/` - Side-by-side script diffs
+  - `TableDiffVisualizer/` - Attributes and Tags diffs
+  - `Notifications/` - Toast notifications
+- **Theme.lua** - Studio-matched color palette
+- Uses Roact for declarative UI
+
+**2. Communication** (`ServeSession.lua`)
+- WebSocket connection to server (previously long-polling)
+- Handles patches, errors, reconnection
+- Protocol version checking
+
+**3. Reconciler** (`Reconciler/`)
+- **applyPatch.lua** - Applies server patches to Studio tree
+- **reify.lua** - Creates instances from snapshots
+- **hydrate.lua** - Updates existing instances
+- **diff.lua** - Generates patches (for two-way sync)
+- **decodeValue.lua** - Converts encoded values to Roblox types
+- **setProperty.lua** - Sets properties safely
+- **getProperty.lua** - Gets properties with fallbacks
+
+**4. State Management**
+- **Settings.lua** - Persistent plugin settings
+- **InstanceMap.lua** - Tracks server ID → Studio instance mapping
+- **PatchSet.lua** / **PatchTree.lua** - Patch representation
+
+**5. Testing**
+- Unit tests: `.spec.lua` files (TestEZ)
+- Integration tests: `integration/` directory
+- Stress tests: `.stress.spec.lua` files
+- Test runner: `runTests.lua`
+
+## Key Configuration (`Config.lua`)
+
+```lua
+{
+    version = {7, 7, 0, "-rc.1"},
+    protocolVersion = 5,  -- MUST match server
+    ignoredClassNames = { TouchTransmitter = true, Camera = true }
+}
+```
+
+**When changing protocol:** Bump `protocolVersion` in both plugin AND server.
+
+## WebSocket Protocol (v5)
+
+1. Connect to `ws://host:port/api/rojo`
+2. Server sends: protocol version, project name
+3. Plugin sends: `{"type": "Subscribe"}`
+4. Server sends patches on filesystem changes
+
+**Patch structure:**
+```lua
+{
+    type = "ApplyPatch",
+    sessionId = "uuid",
+    patch = {
+        removed = {"id1", "id2"},           -- Array of IDs (Vec<Ref>)
+        added = { ["id3"] = {...} },        -- Map: ID → Instance data
+        updated = {                          -- Array of updates (Vec<InstanceUpdate>)
+            { id = "id4", changedName = "...", changedProperties = {...} }
+        }
+    }
+}
+```
+
+## Reconciler (`Reconciler/`)
+
+**applyPatch.lua** - Main patch application:
+1. Remove instances in `removed`
+2. Create instances in `added` via `reify`
+3. Update instances in `updated` via `hydrate`
+4. Collect errors, show in UI
+
+**reify.lua** - Create instances (parent last - Roblox best practice)
+**hydrate.lua** - Update existing (only changed properties)
+**setProperty.lua** / **getProperty.lua** - Handle unscriptable properties
+
+## UI Components (`App/`)
+
+**StatusPages:** NotConnected, Connecting, Connected, Error, Settings
+**PatchVisualizer:** Tree view of changes with property diffs
+**StringDiffVisualizer:** Side-by-side script diffs
+**TableDiffVisualizer:** Attributes and Tags diffs
+**Notifications:** Toast messages
+**Theme.lua:** Studio-matched colors (auto light/dark)
+
+## InstanceMap
+
+Bidirectional Server ID ↔ Studio Instance mapping:
+
+```lua
+instanceMap:insert(serverId, studioInstance)
+local instance = instanceMap:fromId(serverId)
+local serverId = instanceMap:fromInstance(instance)
+```
+
+Critical for patch application and avoiding duplicates.
+
+## Two-Way Sync (Experimental)
+
+⚠️ Watches Studio changes, sends to server. Has known issues - use with caution.
+
+## Dependencies (`plugin/Packages/`)
+
+Roact, Flipper, Promise, TestEZ, t, Highlighter, msgpack-luau. **Don't edit vendored packages.**
+
+## Common Issues
+
+**Plugin not reloading:** Enable Studio setting "Reload plugins on file change"
+**Connection fails:** Check server running, host/port match, protocol versions match
+**Properties not syncing:** Verify scriptable in rbx_reflection_database
+**Duplicates:** InstanceMap corruption - disconnect, restart Studio
+
+## Debugging
+
+Settings → Log Level → "Trace" for verbose output. `ROJO_DEV_BUILD` instance enables auto-tests.