feat(web): realtime WebSocket sync for web editor

.gitignore

@@ -19,6 +19,7 @@ data/
 # Temp
 *.log
 .claude/
+.worktrees/
 CLAUDE.md
 .serena/
 .playwright-mcp/

docs/plans/2026-02-22-realtime-websocket-editor-design.md

@@ -0,0 +1,233 @@
+# Realtime WebSocket Editor Design
+
+**Date:** 2026-02-22
+**Status:** Approved
+**Scope:** HyperPerms plugin, HyperPermsWeb editor, new CF Workers relay
+
+## Problem
+
+The web editor at hyperperms.com uses a polling/REST model: the plugin POSTs session
+data to the API, the user edits in the browser, then runs `/hp apply <session>` to pull
+changes back. This is slow, manual, and one-directional.
+
+## Goal
+
+Two-way realtime sync between the browser editor and the Hytale plugin via WebSocket,
+so edits flow in both directions without manual commands.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Direction | Two-way full sync | Editor pushes to server, server pushes to editor |
+| Transport | WebSocket via Cloudflare Durable Objects | Already on CF Workers, no extra vendor, ~$5/month |
+| Relay model | API-side (CF DO) | Both plugin and browser connect as WS clients to CF |
+| Default apply mode | Batch with confirm | Safety: changes accumulate, user clicks Apply |
+| Live mode | Toggle in editor UI | Opt-in immediate apply for power users |
+| Undo | Server-side undo history (last 20 ops) | Reversible batch applies |
+| Message format | Incremental diffs (operations) | Small payloads, natural undo, efficient |
+| Conflict handling | Auto-merge non-conflicting, UI for conflicts | Server changes to different entities merge silently |
+
+## Architecture
+
+```
+Browser (Next.js) CF Durable Object Hytale Plugin (Java)
+ | (1 DO per session) |
+ |--- WS connect -------->| |
+ | |<-------- WS connect ---------------|
+ | | |
+ |-- editor.change ------->| (stores op in pending list) |
+ | | |
+ |-- batch.apply --------->| |
+ | |--- batch.apply ------------------->|
+ | | [applies to live server]
+ | |<--- apply.result ------------------|
+ |<-- apply.result --------| |
+ | | |
+ | |<--- server.change -----------------|
+ |<-- server.change -------| [in-game command ran]
+```
+
+### Session Lifecycle
+
+1. Player runs `/hp editor` in-game
+2. Plugin creates session via existing REST API (POST /api/session/create)
+3. API returns session ID + editor URL (unchanged)
+4. Plugin opens WebSocket to `wss://ws.hyperperms.com/session/<id>` as `plugin` role
+5. Player opens editor in browser, editor opens WebSocket to same URL as `editor` role
+6. DO has both connections -- relay begins
+7. On disconnect/timeout, DO hibernates (cost-efficient)
+8. Session expires after 24h (same as current TTL)
+
+### Why CF Durable Objects
+
+- CF Workers already in use (no new vendor)
+- DOs can hold persistent WebSocket connections (unlike Vercel serverless)
+- Built-in hibernation API saves costs when idle
+- Native WebSocket support with `acceptWebSocket()` API
+- Cost: ~$0.15/M requests + $0.50/GB-month -- effectively free at our volume
+- Stays within Cloudflare ecosystem
+
+## Message Protocol
+
+### Operation Types
+
+All messages are JSON with a `type` field. Operations are the atomic unit of change.
+
+```typescript
+// === Editor -> DO -> Plugin ===
+
+// Individual changes (accumulated in batch mode, applied immediately in live mode)
+{ type: "op", op: "permission.add", target: "group:admin", node: "server.kick", value: true }
+{ type: "op", op: "permission.remove", target: "group:admin", node: "server.kick" }
+{ type: "op", op: "permission.set", target: "user:<uuid>", node: "chat.color", value: false }
+{ type: "op", op: "group.create", name: "moderator", weight: 50, parents: ["default"] }
+{ type: "op", op: "group.delete", name: "moderator" }
+{ type: "op", op: "group.setMeta", target: "admin", key: "prefix", value: "&c[Admin] " }
+{ type: "op", op: "group.setWeight", target: "admin", weight: 100 }
+{ type: "op", op: "group.addParent", target: "moderator", parent: "default" }
+{ type: "op", op: "group.removeParent", target: "moderator", parent: "default" }
+{ type: "op", op: "user.addGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "user.removeGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "track.create", name: "staff", groups: ["default", "helper", "mod", "admin"] }
+{ type: "op", op: "track.delete", name: "staff" }
+{ type: "op", op: "track.addGroup", target: "staff", group: "moderator", position: 2 }
+{ type: "op", op: "track.removeGroup", target: "staff", group: "moderator" }
+
+// Batch apply (batch mode only)
+{ type: "batch.apply" }
+
+// Mode switch
+{ type: "session.mode", mode: "live" | "batch" }
+
+// === Plugin -> DO -> Editor ===
+
+// Server-side change (in-game command, API, another plugin)
+{ type: "server.change", op: "permission.add", target: "group:admin", node: "fly.use",
+ value: true, source: "console", timestamp: 1708617600000 }
+
+// Apply result
+{ type: "apply.result", success: true, applied: 5, failed: 0,
+ errors: [], undoId: "abc123" }
+
+// Undo result
+{ type: "undo.result", success: true, undoId: "abc123", reverted: 5 }
+
+// === Control messages (both directions) ===
+
+{ type: "session.sync", data: { groups: [...], users: [...], tracks: [...] } }
+{ type: "session.ping" }
+{ type: "session.pong" }
+{ type: "session.error", code: "CONFLICT", message: "...", details: {...} }
+```
+
+### Operation Inversion (for undo)
+
+Each operation has a natural inverse stored in the undo history:
+
+| Operation | Inverse |
+|---|---|
+| `permission.add` | `permission.remove` (same target/node) |
+| `permission.remove` | `permission.add` (with original value) |
+| `group.create` | `group.delete` |
+| `group.delete` | `group.create` (with full group data snapshot) |
+| `group.setWeight` | `group.setWeight` (with previous weight) |
+| `user.addGroup` | `user.removeGroup` |
+| `user.removeGroup` | `user.addGroup` |
+| `track.addGroup` | `track.removeGroup` |
+
+## Conflict Detection
+
+### Non-conflicting (auto-merge)
+
+Server change to entity A while editor has pending changes to entity B:
+- Apply server change to editor state silently
+- Show subtle indicator that server state updated (e.g. pulse animation on the changed entity)
+
+### Conflicting
+
+Server change to entity A while editor has pending changes to entity A:
+- Mark the entity with a conflict indicator in the UI
+- Show conflict banner: "Server changed [group: admin] -- your local changes may conflict"
+- Options: "Keep mine", "Accept server", "View diff"
+- Conflict state clears when user resolves
+
+### Detection Logic
+
+Conflict = same `target` value in both a pending editor op and an incoming server change.
+Tracked per-entity, not per-field (simple and predictable).
+
+## Undo History
+
+- Stored in the Durable Object's transactional storage
+- Last 20 batch applies, each with its inverse operations
+- Each undo entry: `{ undoId, timestamp, ops: Operation[], inverseOps: Operation[] }`
+- Undo request: `{ type: "undo", undoId: "abc123" }` -> sends inverse ops to plugin
+- History clears on session expiry
+
+## Three Codebases
+
+### 1. CF Workers (new Durable Object)
+
+**Location:** New worker in existing CF project or standalone
+**Responsibilities:**
+- Accept WebSocket connections from editor and plugin
+- Route messages between them based on type
+- Store pending operations (batch mode)
+- Maintain undo history
+- Handle hibernation for cost efficiency
+- Session authentication (validate session ID against Upstash Redis)
+
+**Key files:**
+- `src/session-do.ts` -- Durable Object class with WebSocket handlers
+- `src/index.ts` -- Worker entry point, routes `/session/:id` to DO
+- `wrangler.toml` -- DO binding configuration
+
+### 2. HyperPermsWeb (Next.js editor)
+
+**Changes:**
+- New WebSocket hook: `useRealtimeSession(sessionId)` -- manages WS connection, reconnection, message handling
+- Editor state: track pending operations, conflict state
+- UI: "Live" toggle switch, Apply button (batch mode), conflict banners, undo button
+- Connection status indicator (connected/reconnecting/disconnected)
+- Replace current `PUT /api/session` save flow with WebSocket ops
+
+**Key files:**
+- `src/hooks/useRealtimeSession.ts` -- WebSocket connection + state management
+- `src/components/editor/RealtimeStatus.tsx` -- Connection indicator
+- `src/components/editor/ConflictBanner.tsx` -- Conflict resolution UI
+- `src/components/editor/LiveModeToggle.tsx` -- Live/batch toggle
+- Modifications to existing editor components to dispatch ops instead of direct state mutation
+
+### 3. HyperPerms (Java plugin)
+
+**Changes:**
+- New `WebSocketClient` class using Java 11+ `HttpClient` WebSocket API
+- Change listener: hook into existing EventBus to detect in-game permission changes
+- Apply handler: receive ops from editor, apply them through existing manager layer
+- Undo support: store pre-apply snapshots for revert
+- Auto-reconnect on connection loss
+- New config options: `webEditor.realtimeEnabled`, `webEditor.wsUrl`
+
+**Key files:**
+- `src/main/java/com/hyperperms/web/RealtimeClient.java` -- WebSocket client
+- `src/main/java/com/hyperperms/web/RealtimeMessageHandler.java` -- Message routing
+- `src/main/java/com/hyperperms/web/OperationApplier.java` -- Applies ops to live state
+- `src/main/java/com/hyperperms/web/ChangeListener.java` -- Detects in-game changes, sends to WS
+- Modifications to `WebEditorService.java` -- Start WS after session creation
+
+## Security
+
+- Session ID serves as auth token (same as current model)
+- DO validates session exists in Redis before accepting WS upgrade
+- Plugin identifies as `role: plugin` on connect, editor as `role: editor`
+- Only one plugin connection per session (reject duplicates)
+- Rate limiting on operations (prevent abuse from editor)
+- All traffic over WSS (TLS)
+
+## Migration / Backwards Compatibility
+
+- Existing REST flow continues to work (no breaking changes)
+- WebSocket is additive -- if WS connection fails, editor falls back to REST save/load
+- Plugin config: `webEditor.realtimeEnabled: true` (default true for new installs)
+- `/hp apply` command still works as fallback

src/main/java/com/hyperperms/HyperPerms.java

@@ -217,7 +217,7 @@ public void enable() {
 
  // Initialize managers with event bus
  groupManager = new GroupManagerImpl(storage, cacheInvalidator, eventBus);
- trackManager = new TrackManagerImpl(storage);
+ trackManager = new TrackManagerImpl(storage, eventBus);
  userManager = new UserManagerImpl(storage, cache, eventBus, config.getDefaultGroup());
 
  // Load data
@@ -428,6 +428,11 @@ public void disable() {
  placeholderApiIntegration.unregister();
  }
 
+ // Disconnect WebSocket before shutting down scheduler
+ if (webEditorService != null) {
+ webEditorService.disconnectWebSocket();
+ }
+
  // Stop scheduled tasks FIRST to prevent new storage executor submissions
  if (expiryTask != null) {
  expiryTask.cancel(true);

src/main/java/com/hyperperms/api/events/HyperPermsEvent.java

@@ -71,6 +71,21 @@ enum EventType {
  */
  DATA_RELOAD,
 
+ /**
+ * Fired when a track is created.
+ */
+ TRACK_CREATE,
+
+ /**
+ * Fired when a track is deleted.
+ */
+ TRACK_DELETE,
+
+ /**
+ * Fired when a track is modified.
+ */
+ TRACK_MODIFY,
+
  /**
  * Fired when a user is promoted along a track.
  */

src/main/java/com/hyperperms/api/events/TrackCreateEvent.java

@@ -0,0 +1,112 @@
+package com.hyperperms.api.events;
+
+import com.hyperperms.model.Track;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Event fired when a track is created.
+ * <p>
+ * This event can be cancelled to prevent the track from being created.
+ * The PRE state fires before creation, the POST state fires after.
+ */
+public final class TrackCreateEvent implements HyperPermsEvent, Cancellable {
+
+ /**
+ * The state of the track creation event.
+ */
+ public enum State {
+ /**
+ * Before the track is created. The event can be cancelled at this point.
+ */
+ PRE,
+
+ /**
+ * After the track has been created. Cancellation has no effect.
+ */
+ POST
+ }
+
+ private final String trackName;
+ private final Track track;
+ private final State state;
+ private boolean cancelled;
+
+ /**
+ * Creates a PRE event for track creation.
+ *
+ * @param trackName the name of the track being created
+ */
+ public TrackCreateEvent(@NotNull String trackName) {
+ this.trackName = trackName;
+ this.track = null;
+ this.state = State.PRE;
+ this.cancelled = false;
+ }
+
+ /**
+ * Creates a POST event for track creation.
+ *
+ * @param track the created track
+ */
+ public TrackCreateEvent(@NotNull Track track) {
+ this.trackName = track.getName();
+ this.track = track;
+ this.state = State.POST;
+ this.cancelled = false;
+ }
+
+ @Override
+ public EventType getType() {
+ return EventType.TRACK_CREATE;
+ }
+
+ /**
+ * Gets the name of the track being created.
+ *
+ * @return the track name
+ */
+ @NotNull
+ public String getTrackName() {
+ return trackName;
+ }
+
+ /**
+ * Gets the created track.
+ * <p>
+ * This is only available in the POST state. Returns null in PRE state.
+ *
+ * @return the track, or null if PRE state
+ */
+ @Nullable
+ public Track getTrack() {
+ return track;
+ }
+
+ /**
+ * Gets the state of this event.
+ *
+ * @return the state
+ */
+ @NotNull
+ public State getState() {
+ return state;
+ }
+
+ @Override
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ @Override
+ public void setCancelled(boolean cancelled) {
+ if (state == State.PRE) {
+ this.cancelled = cancelled;
+ }
+ }
+
+ @Override
+ public String toString() {
+ return "TrackCreateEvent{trackName='" + trackName + "', state=" + state + ", cancelled=" + cancelled + "}";
+ }
+}

.gitignore

@@ -19,6 +19,7 @@ data/
 # Temp
 *.log
 .claude/
+.worktrees/
 CLAUDE.md
 .serena/
 .playwright-mcp/

docs/plans/2026-02-22-realtime-websocket-editor-design.md

@@ -0,0 +1,233 @@
+# Realtime WebSocket Editor Design
+
+**Date:** 2026-02-22
+**Status:** Approved
+**Scope:** HyperPerms plugin, HyperPermsWeb editor, new CF Workers relay
+
+## Problem
+
+The web editor at hyperperms.com uses a polling/REST model: the plugin POSTs session
+data to the API, the user edits in the browser, then runs `/hp apply <session>` to pull
+changes back. This is slow, manual, and one-directional.
+
+## Goal
+
+Two-way realtime sync between the browser editor and the Hytale plugin via WebSocket,
+so edits flow in both directions without manual commands.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Direction | Two-way full sync | Editor pushes to server, server pushes to editor |
+| Transport | WebSocket via Cloudflare Durable Objects | Already on CF Workers, no extra vendor, ~$5/month |
+| Relay model | API-side (CF DO) | Both plugin and browser connect as WS clients to CF |
+| Default apply mode | Batch with confirm | Safety: changes accumulate, user clicks Apply |
+| Live mode | Toggle in editor UI | Opt-in immediate apply for power users |
+| Undo | Server-side undo history (last 20 ops) | Reversible batch applies |
+| Message format | Incremental diffs (operations) | Small payloads, natural undo, efficient |
+| Conflict handling | Auto-merge non-conflicting, UI for conflicts | Server changes to different entities merge silently |
+
+## Architecture
+
+```
+Browser (Next.js) CF Durable Object Hytale Plugin (Java)
+ | (1 DO per session) |
+ |--- WS connect -------->| |
+ | |<-------- WS connect ---------------|
+ | | |
+ |-- editor.change ------->| (stores op in pending list) |
+ | | |
+ |-- batch.apply --------->| |
+ | |--- batch.apply ------------------->|
+ | | [applies to live server]
+ | |<--- apply.result ------------------|
+ |<-- apply.result --------| |
+ | | |
+ | |<--- server.change -----------------|
+ |<-- server.change -------| [in-game command ran]
+```
+
+### Session Lifecycle
+
+1. Player runs `/hp editor` in-game
+2. Plugin creates session via existing REST API (POST /api/session/create)
+3. API returns session ID + editor URL (unchanged)
+4. Plugin opens WebSocket to `wss://ws.hyperperms.com/session/<id>` as `plugin` role
+5. Player opens editor in browser, editor opens WebSocket to same URL as `editor` role
+6. DO has both connections -- relay begins
+7. On disconnect/timeout, DO hibernates (cost-efficient)
+8. Session expires after 24h (same as current TTL)
+
+### Why CF Durable Objects
+
+- CF Workers already in use (no new vendor)
+- DOs can hold persistent WebSocket connections (unlike Vercel serverless)
+- Built-in hibernation API saves costs when idle
+- Native WebSocket support with `acceptWebSocket()` API
+- Cost: ~$0.15/M requests + $0.50/GB-month -- effectively free at our volume
+- Stays within Cloudflare ecosystem
+
+## Message Protocol
+
+### Operation Types
+
+All messages are JSON with a `type` field. Operations are the atomic unit of change.
+
+```typescript
+// === Editor -> DO -> Plugin ===
+
+// Individual changes (accumulated in batch mode, applied immediately in live mode)
+{ type: "op", op: "permission.add", target: "group:admin", node: "server.kick", value: true }
+{ type: "op", op: "permission.remove", target: "group:admin", node: "server.kick" }
+{ type: "op", op: "permission.set", target: "user:<uuid>", node: "chat.color", value: false }
+{ type: "op", op: "group.create", name: "moderator", weight: 50, parents: ["default"] }
+{ type: "op", op: "group.delete", name: "moderator" }
+{ type: "op", op: "group.setMeta", target: "admin", key: "prefix", value: "&c[Admin] " }
+{ type: "op", op: "group.setWeight", target: "admin", weight: 100 }
+{ type: "op", op: "group.addParent", target: "moderator", parent: "default" }
+{ type: "op", op: "group.removeParent", target: "moderator", parent: "default" }
+{ type: "op", op: "user.addGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "user.removeGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "track.create", name: "staff", groups: ["default", "helper", "mod", "admin"] }
+{ type: "op", op: "track.delete", name: "staff" }
+{ type: "op", op: "track.addGroup", target: "staff", group: "moderator", position: 2 }
+{ type: "op", op: "track.removeGroup", target: "staff", group: "moderator" }
+
+// Batch apply (batch mode only)
+{ type: "batch.apply" }
+
+// Mode switch
+{ type: "session.mode", mode: "live" | "batch" }
+
+// === Plugin -> DO -> Editor ===
+
+// Server-side change (in-game command, API, another plugin)
+{ type: "server.change", op: "permission.add", target: "group:admin", node: "fly.use",
+ value: true, source: "console", timestamp: 1708617600000 }
+
+// Apply result
+{ type: "apply.result", success: true, applied: 5, failed: 0,
+ errors: [], undoId: "abc123" }
+
+// Undo result
+{ type: "undo.result", success: true, undoId: "abc123", reverted: 5 }
+
+// === Control messages (both directions) ===
+
+{ type: "session.sync", data: { groups: [...], users: [...], tracks: [...] } }
+{ type: "session.ping" }
+{ type: "session.pong" }
+{ type: "session.error", code: "CONFLICT", message: "...", details: {...} }
+```
+
+### Operation Inversion (for undo)
+
+Each operation has a natural inverse stored in the undo history:
+
+| Operation | Inverse |
+|---|---|
+| `permission.add` | `permission.remove` (same target/node) |
+| `permission.remove` | `permission.add` (with original value) |
+| `group.create` | `group.delete` |
+| `group.delete` | `group.create` (with full group data snapshot) |
+| `group.setWeight` | `group.setWeight` (with previous weight) |
+| `user.addGroup` | `user.removeGroup` |
+| `user.removeGroup` | `user.addGroup` |
+| `track.addGroup` | `track.removeGroup` |
+
+## Conflict Detection
+
+### Non-conflicting (auto-merge)
+
+Server change to entity A while editor has pending changes to entity B:
+- Apply server change to editor state silently
+- Show subtle indicator that server state updated (e.g. pulse animation on the changed entity)
+
+### Conflicting
+
+Server change to entity A while editor has pending changes to entity A:
+- Mark the entity with a conflict indicator in the UI
+- Show conflict banner: "Server changed [group: admin] -- your local changes may conflict"
+- Options: "Keep mine", "Accept server", "View diff"
+- Conflict state clears when user resolves
+
+### Detection Logic
+
+Conflict = same `target` value in both a pending editor op and an incoming server change.
+Tracked per-entity, not per-field (simple and predictable).
+
+## Undo History
+
+- Stored in the Durable Object's transactional storage
+- Last 20 batch applies, each with its inverse operations
+- Each undo entry: `{ undoId, timestamp, ops: Operation[], inverseOps: Operation[] }`
+- Undo request: `{ type: "undo", undoId: "abc123" }` -> sends inverse ops to plugin
+- History clears on session expiry
+
+## Three Codebases
+
+### 1. CF Workers (new Durable Object)
+
+**Location:** New worker in existing CF project or standalone
+**Responsibilities:**
+- Accept WebSocket connections from editor and plugin
+- Route messages between them based on type
+- Store pending operations (batch mode)
+- Maintain undo history
+- Handle hibernation for cost efficiency
+- Session authentication (validate session ID against Upstash Redis)
+
+**Key files:**
+- `src/session-do.ts` -- Durable Object class with WebSocket handlers
+- `src/index.ts` -- Worker entry point, routes `/session/:id` to DO
+- `wrangler.toml` -- DO binding configuration
+
+### 2. HyperPermsWeb (Next.js editor)
+
+**Changes:**
+- New WebSocket hook: `useRealtimeSession(sessionId)` -- manages WS connection, reconnection, message handling
+- Editor state: track pending operations, conflict state
+- UI: "Live" toggle switch, Apply button (batch mode), conflict banners, undo button
+- Connection status indicator (connected/reconnecting/disconnected)
+- Replace current `PUT /api/session` save flow with WebSocket ops
+
+**Key files:**
+- `src/hooks/useRealtimeSession.ts` -- WebSocket connection + state management
+- `src/components/editor/RealtimeStatus.tsx` -- Connection indicator
+- `src/components/editor/ConflictBanner.tsx` -- Conflict resolution UI
+- `src/components/editor/LiveModeToggle.tsx` -- Live/batch toggle
+- Modifications to existing editor components to dispatch ops instead of direct state mutation
+
+### 3. HyperPerms (Java plugin)
+
+**Changes:**
+- New `WebSocketClient` class using Java 11+ `HttpClient` WebSocket API
+- Change listener: hook into existing EventBus to detect in-game permission changes
+- Apply handler: receive ops from editor, apply them through existing manager layer
+- Undo support: store pre-apply snapshots for revert
+- Auto-reconnect on connection loss
+- New config options: `webEditor.realtimeEnabled`, `webEditor.wsUrl`
+
+**Key files:**
+- `src/main/java/com/hyperperms/web/RealtimeClient.java` -- WebSocket client
+- `src/main/java/com/hyperperms/web/RealtimeMessageHandler.java` -- Message routing
+- `src/main/java/com/hyperperms/web/OperationApplier.java` -- Applies ops to live state
+- `src/main/java/com/hyperperms/web/ChangeListener.java` -- Detects in-game changes, sends to WS
+- Modifications to `WebEditorService.java` -- Start WS after session creation
+
+## Security
+
+- Session ID serves as auth token (same as current model)
+- DO validates session exists in Redis before accepting WS upgrade
+- Plugin identifies as `role: plugin` on connect, editor as `role: editor`
+- Only one plugin connection per session (reject duplicates)
+- Rate limiting on operations (prevent abuse from editor)
+- All traffic over WSS (TLS)
+
+## Migration / Backwards Compatibility
+
+- Existing REST flow continues to work (no breaking changes)
+- WebSocket is additive -- if WS connection fails, editor falls back to REST save/load
+- Plugin config: `webEditor.realtimeEnabled: true` (default true for new installs)
+- `/hp apply` command still works as fallback

src/main/java/com/hyperperms/HyperPerms.java

@@ -217,7 +217,7 @@ public void enable() {
 
  // Initialize managers with event bus
  groupManager = new GroupManagerImpl(storage, cacheInvalidator, eventBus);
- trackManager = new TrackManagerImpl(storage);
+ trackManager = new TrackManagerImpl(storage, eventBus);
  userManager = new UserManagerImpl(storage, cache, eventBus, config.getDefaultGroup());
 
  // Load data
@@ -428,6 +428,11 @@ public void disable() {
  placeholderApiIntegration.unregister();
  }
 
+ // Disconnect WebSocket before shutting down scheduler
+ if (webEditorService != null) {
+ webEditorService.disconnectWebSocket();
+ }
+
  // Stop scheduled tasks FIRST to prevent new storage executor submissions
  if (expiryTask != null) {
  expiryTask.cancel(true);

src/main/java/com/hyperperms/api/events/HyperPermsEvent.java

@@ -71,6 +71,21 @@ enum EventType {
  */
  DATA_RELOAD,
 
+ /**
+ * Fired when a track is created.
+ */
+ TRACK_CREATE,
+
+ /**
+ * Fired when a track is deleted.
+ */
+ TRACK_DELETE,
+
+ /**
+ * Fired when a track is modified.
+ */
+ TRACK_MODIFY,
+
  /**
  * Fired when a user is promoted along a track.
  */

src/main/java/com/hyperperms/api/events/TrackCreateEvent.java

@@ -0,0 +1,112 @@
+package com.hyperperms.api.events;
+
+import com.hyperperms.model.Track;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Event fired when a track is created.
+ * <p>
+ * This event can be cancelled to prevent the track from being created.
+ * The PRE state fires before creation, the POST state fires after.
+ */
+public final class TrackCreateEvent implements HyperPermsEvent, Cancellable {
+
+ /**
+ * The state of the track creation event.
+ */
+ public enum State {
+ /**
+ * Before the track is created. The event can be cancelled at this point.
+ */
+ PRE,
+
+ /**
+ * After the track has been created. Cancellation has no effect.
+ */
+ POST
+ }
+
+ private final String trackName;
+ private final Track track;
+ private final State state;
+ private boolean cancelled;
+
+ /**
+ * Creates a PRE event for track creation.
+ *
+ * @param trackName the name of the track being created
+ */
+ public TrackCreateEvent(@NotNull String trackName) {
+ this.trackName = trackName;
+ this.track = null;
+ this.state = State.PRE;
+ this.cancelled = false;
+ }
+
+ /**
+ * Creates a POST event for track creation.
+ *
+ * @param track the created track
+ */
+ public TrackCreateEvent(@NotNull Track track) {
+ this.trackName = track.getName();
+ this.track = track;
+ this.state = State.POST;
+ this.cancelled = false;
+ }
+
+ @Override
+ public EventType getType() {
+ return EventType.TRACK_CREATE;
+ }
+
+ /**
+ * Gets the name of the track being created.
+ *
+ * @return the track name
+ */
+ @NotNull
+ public String getTrackName() {
+ return trackName;
+ }
+
+ /**
+ * Gets the created track.
+ * <p>
+ * This is only available in the POST state. Returns null in PRE state.
+ *
+ * @return the track, or null if PRE state
+ */
+ @Nullable
+ public Track getTrack() {
+ return track;
+ }
+
+ /**
+ * Gets the state of this event.
+ *
+ * @return the state
+ */
+ @NotNull
+ public State getState() {
+ return state;
+ }
+
+ @Override
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ @Override
+ public void setCancelled(boolean cancelled) {
+ if (state == State.PRE) {
+ this.cancelled = cancelled;
+ }
+ }
+
+ @Override
+ public String toString() {
+ return "TrackCreateEvent{trackName='" + trackName + "', state=" + state + ", cancelled=" + cancelled + "}";
+ }
+}

.gitignore

@@ -19,6 +19,7 @@ data/
 # Temp
 *.log
 .claude/
+.worktrees/
 CLAUDE.md
 .serena/
 .playwright-mcp/

docs/plans/2026-02-22-realtime-websocket-editor-design.md

@@ -0,0 +1,233 @@
+# Realtime WebSocket Editor Design
+
+**Date:** 2026-02-22
+**Status:** Approved
+**Scope:** HyperPerms plugin, HyperPermsWeb editor, new CF Workers relay
+
+## Problem
+
+The web editor at hyperperms.com uses a polling/REST model: the plugin POSTs session
+data to the API, the user edits in the browser, then runs `/hp apply <session>` to pull
+changes back. This is slow, manual, and one-directional.
+
+## Goal
+
+Two-way realtime sync between the browser editor and the Hytale plugin via WebSocket,
+so edits flow in both directions without manual commands.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Direction | Two-way full sync | Editor pushes to server, server pushes to editor |
+| Transport | WebSocket via Cloudflare Durable Objects | Already on CF Workers, no extra vendor, ~$5/month |
+| Relay model | API-side (CF DO) | Both plugin and browser connect as WS clients to CF |
+| Default apply mode | Batch with confirm | Safety: changes accumulate, user clicks Apply |
+| Live mode | Toggle in editor UI | Opt-in immediate apply for power users |
+| Undo | Server-side undo history (last 20 ops) | Reversible batch applies |
+| Message format | Incremental diffs (operations) | Small payloads, natural undo, efficient |
+| Conflict handling | Auto-merge non-conflicting, UI for conflicts | Server changes to different entities merge silently |
+
+## Architecture
+
+```
+Browser (Next.js) CF Durable Object Hytale Plugin (Java)
+ | (1 DO per session) |
+ |--- WS connect -------->| |
+ | |<-------- WS connect ---------------|
+ | | |
+ |-- editor.change ------->| (stores op in pending list) |
+ | | |
+ |-- batch.apply --------->| |
+ | |--- batch.apply ------------------->|
+ | | [applies to live server]
+ | |<--- apply.result ------------------|
+ |<-- apply.result --------| |
+ | | |
+ | |<--- server.change -----------------|
+ |<-- server.change -------| [in-game command ran]
+```
+
+### Session Lifecycle
+
+1. Player runs `/hp editor` in-game
+2. Plugin creates session via existing REST API (POST /api/session/create)
+3. API returns session ID + editor URL (unchanged)
+4. Plugin opens WebSocket to `wss://ws.hyperperms.com/session/<id>` as `plugin` role
+5. Player opens editor in browser, editor opens WebSocket to same URL as `editor` role
+6. DO has both connections -- relay begins
+7. On disconnect/timeout, DO hibernates (cost-efficient)
+8. Session expires after 24h (same as current TTL)
+
+### Why CF Durable Objects
+
+- CF Workers already in use (no new vendor)
+- DOs can hold persistent WebSocket connections (unlike Vercel serverless)
+- Built-in hibernation API saves costs when idle
+- Native WebSocket support with `acceptWebSocket()` API
+- Cost: ~$0.15/M requests + $0.50/GB-month -- effectively free at our volume
+- Stays within Cloudflare ecosystem
+
+## Message Protocol
+
+### Operation Types
+
+All messages are JSON with a `type` field. Operations are the atomic unit of change.
+
+```typescript
+// === Editor -> DO -> Plugin ===
+
+// Individual changes (accumulated in batch mode, applied immediately in live mode)
+{ type: "op", op: "permission.add", target: "group:admin", node: "server.kick", value: true }
+{ type: "op", op: "permission.remove", target: "group:admin", node: "server.kick" }
+{ type: "op", op: "permission.set", target: "user:<uuid>", node: "chat.color", value: false }
+{ type: "op", op: "group.create", name: "moderator", weight: 50, parents: ["default"] }
+{ type: "op", op: "group.delete", name: "moderator" }
+{ type: "op", op: "group.setMeta", target: "admin", key: "prefix", value: "&c[Admin] " }
+{ type: "op", op: "group.setWeight", target: "admin", weight: 100 }
+{ type: "op", op: "group.addParent", target: "moderator", parent: "default" }
+{ type: "op", op: "group.removeParent", target: "moderator", parent: "default" }
+{ type: "op", op: "user.addGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "user.removeGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "track.create", name: "staff", groups: ["default", "helper", "mod", "admin"] }
+{ type: "op", op: "track.delete", name: "staff" }
+{ type: "op", op: "track.addGroup", target: "staff", group: "moderator", position: 2 }
+{ type: "op", op: "track.removeGroup", target: "staff", group: "moderator" }
+
+// Batch apply (batch mode only)
+{ type: "batch.apply" }
+
+// Mode switch
+{ type: "session.mode", mode: "live" | "batch" }
+
+// === Plugin -> DO -> Editor ===
+
+// Server-side change (in-game command, API, another plugin)
+{ type: "server.change", op: "permission.add", target: "group:admin", node: "fly.use",
+ value: true, source: "console", timestamp: 1708617600000 }
+
+// Apply result
+{ type: "apply.result", success: true, applied: 5, failed: 0,
+ errors: [], undoId: "abc123" }
+
+// Undo result
+{ type: "undo.result", success: true, undoId: "abc123", reverted: 5 }
+
+// === Control messages (both directions) ===
+
+{ type: "session.sync", data: { groups: [...], users: [...], tracks: [...] } }
+{ type: "session.ping" }
+{ type: "session.pong" }
+{ type: "session.error", code: "CONFLICT", message: "...", details: {...} }
+```
+
+### Operation Inversion (for undo)
+
+Each operation has a natural inverse stored in the undo history:
+
+| Operation | Inverse |
+|---|---|
+| `permission.add` | `permission.remove` (same target/node) |
+| `permission.remove` | `permission.add` (with original value) |
+| `group.create` | `group.delete` |
+| `group.delete` | `group.create` (with full group data snapshot) |
+| `group.setWeight` | `group.setWeight` (with previous weight) |
+| `user.addGroup` | `user.removeGroup` |
+| `user.removeGroup` | `user.addGroup` |
+| `track.addGroup` | `track.removeGroup` |
+
+## Conflict Detection
+
+### Non-conflicting (auto-merge)
+
+Server change to entity A while editor has pending changes to entity B:
+- Apply server change to editor state silently
+- Show subtle indicator that server state updated (e.g. pulse animation on the changed entity)
+
+### Conflicting
+
+Server change to entity A while editor has pending changes to entity A:
+- Mark the entity with a conflict indicator in the UI
+- Show conflict banner: "Server changed [group: admin] -- your local changes may conflict"
+- Options: "Keep mine", "Accept server", "View diff"
+- Conflict state clears when user resolves
+
+### Detection Logic
+
+Conflict = same `target` value in both a pending editor op and an incoming server change.
+Tracked per-entity, not per-field (simple and predictable).
+
+## Undo History
+
+- Stored in the Durable Object's transactional storage
+- Last 20 batch applies, each with its inverse operations
+- Each undo entry: `{ undoId, timestamp, ops: Operation[], inverseOps: Operation[] }`
+- Undo request: `{ type: "undo", undoId: "abc123" }` -> sends inverse ops to plugin
+- History clears on session expiry
+
+## Three Codebases
+
+### 1. CF Workers (new Durable Object)
+
+**Location:** New worker in existing CF project or standalone
+**Responsibilities:**
+- Accept WebSocket connections from editor and plugin
+- Route messages between them based on type
+- Store pending operations (batch mode)
+- Maintain undo history
+- Handle hibernation for cost efficiency
+- Session authentication (validate session ID against Upstash Redis)
+
+**Key files:**
+- `src/session-do.ts` -- Durable Object class with WebSocket handlers
+- `src/index.ts` -- Worker entry point, routes `/session/:id` to DO
+- `wrangler.toml` -- DO binding configuration
+
+### 2. HyperPermsWeb (Next.js editor)
+
+**Changes:**
+- New WebSocket hook: `useRealtimeSession(sessionId)` -- manages WS connection, reconnection, message handling
+- Editor state: track pending operations, conflict state
+- UI: "Live" toggle switch, Apply button (batch mode), conflict banners, undo button
+- Connection status indicator (connected/reconnecting/disconnected)
+- Replace current `PUT /api/session` save flow with WebSocket ops
+
+**Key files:**
+- `src/hooks/useRealtimeSession.ts` -- WebSocket connection + state management
+- `src/components/editor/RealtimeStatus.tsx` -- Connection indicator
+- `src/components/editor/ConflictBanner.tsx` -- Conflict resolution UI
+- `src/components/editor/LiveModeToggle.tsx` -- Live/batch toggle
+- Modifications to existing editor components to dispatch ops instead of direct state mutation
+
+### 3. HyperPerms (Java plugin)
+
+**Changes:**
+- New `WebSocketClient` class using Java 11+ `HttpClient` WebSocket API
+- Change listener: hook into existing EventBus to detect in-game permission changes
+- Apply handler: receive ops from editor, apply them through existing manager layer
+- Undo support: store pre-apply snapshots for revert
+- Auto-reconnect on connection loss
+- New config options: `webEditor.realtimeEnabled`, `webEditor.wsUrl`
+
+**Key files:**
+- `src/main/java/com/hyperperms/web/RealtimeClient.java` -- WebSocket client
+- `src/main/java/com/hyperperms/web/RealtimeMessageHandler.java` -- Message routing
+- `src/main/java/com/hyperperms/web/OperationApplier.java` -- Applies ops to live state
+- `src/main/java/com/hyperperms/web/ChangeListener.java` -- Detects in-game changes, sends to WS
+- Modifications to `WebEditorService.java` -- Start WS after session creation
+
+## Security
+
+- Session ID serves as auth token (same as current model)
+- DO validates session exists in Redis before accepting WS upgrade
+- Plugin identifies as `role: plugin` on connect, editor as `role: editor`
+- Only one plugin connection per session (reject duplicates)
+- Rate limiting on operations (prevent abuse from editor)
+- All traffic over WSS (TLS)
+
+## Migration / Backwards Compatibility
+
+- Existing REST flow continues to work (no breaking changes)
+- WebSocket is additive -- if WS connection fails, editor falls back to REST save/load
+- Plugin config: `webEditor.realtimeEnabled: true` (default true for new installs)
+- `/hp apply` command still works as fallback

src/main/java/com/hyperperms/HyperPerms.java

@@ -217,7 +217,7 @@ public void enable() {
 
  // Initialize managers with event bus
  groupManager = new GroupManagerImpl(storage, cacheInvalidator, eventBus);
- trackManager = new TrackManagerImpl(storage);
+ trackManager = new TrackManagerImpl(storage, eventBus);
  userManager = new UserManagerImpl(storage, cache, eventBus, config.getDefaultGroup());
 
  // Load data
@@ -428,6 +428,11 @@ public void disable() {
  placeholderApiIntegration.unregister();
  }
 
+ // Disconnect WebSocket before shutting down scheduler
+ if (webEditorService != null) {
+ webEditorService.disconnectWebSocket();
+ }
+
  // Stop scheduled tasks FIRST to prevent new storage executor submissions
  if (expiryTask != null) {
  expiryTask.cancel(true);

src/main/java/com/hyperperms/api/events/HyperPermsEvent.java

@@ -71,6 +71,21 @@ enum EventType {
  */
  DATA_RELOAD,
 
+ /**
+ * Fired when a track is created.
+ */
+ TRACK_CREATE,
+
+ /**
+ * Fired when a track is deleted.
+ */
+ TRACK_DELETE,
+
+ /**
+ * Fired when a track is modified.
+ */
+ TRACK_MODIFY,
+
  /**
  * Fired when a user is promoted along a track.
  */

src/main/java/com/hyperperms/api/events/TrackCreateEvent.java

@@ -0,0 +1,112 @@
+package com.hyperperms.api.events;
+
+import com.hyperperms.model.Track;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Event fired when a track is created.
+ * <p>
+ * This event can be cancelled to prevent the track from being created.
+ * The PRE state fires before creation, the POST state fires after.
+ */
+public final class TrackCreateEvent implements HyperPermsEvent, Cancellable {
+
+ /**
+ * The state of the track creation event.
+ */
+ public enum State {
+ /**
+ * Before the track is created. The event can be cancelled at this point.
+ */
+ PRE,
+
+ /**
+ * After the track has been created. Cancellation has no effect.
+ */
+ POST
+ }
+
+ private final String trackName;
+ private final Track track;
+ private final State state;
+ private boolean cancelled;
+
+ /**
+ * Creates a PRE event for track creation.
+ *
+ * @param trackName the name of the track being created
+ */
+ public TrackCreateEvent(@NotNull String trackName) {
+ this.trackName = trackName;
+ this.track = null;
+ this.state = State.PRE;
+ this.cancelled = false;
+ }
+
+ /**
+ * Creates a POST event for track creation.
+ *
+ * @param track the created track
+ */
+ public TrackCreateEvent(@NotNull Track track) {
+ this.trackName = track.getName();
+ this.track = track;
+ this.state = State.POST;
+ this.cancelled = false;
+ }
+
+ @Override
+ public EventType getType() {
+ return EventType.TRACK_CREATE;
+ }
+
+ /**
+ * Gets the name of the track being created.
+ *
+ * @return the track name
+ */
+ @NotNull
+ public String getTrackName() {
+ return trackName;
+ }
+
+ /**
+ * Gets the created track.
+ * <p>
+ * This is only available in the POST state. Returns null in PRE state.
+ *
+ * @return the track, or null if PRE state
+ */
+ @Nullable
+ public Track getTrack() {
+ return track;
+ }
+
+ /**
+ * Gets the state of this event.
+ *
+ * @return the state
+ */
+ @NotNull
+ public State getState() {
+ return state;
+ }
+
+ @Override
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ @Override
+ public void setCancelled(boolean cancelled) {
+ if (state == State.PRE) {
+ this.cancelled = cancelled;
+ }
+ }
+
+ @Override
+ public String toString() {
+ return "TrackCreateEvent{trackName='" + trackName + "', state=" + state + ", cancelled=" + cancelled + "}";
+ }
+}

.gitignore

@@ -19,6 +19,7 @@ data/
 # Temp
 *.log
 .claude/
+.worktrees/
 CLAUDE.md
 .serena/
 .playwright-mcp/

docs/plans/2026-02-22-realtime-websocket-editor-design.md

@@ -0,0 +1,233 @@
+# Realtime WebSocket Editor Design
+
+**Date:** 2026-02-22
+**Status:** Approved
+**Scope:** HyperPerms plugin, HyperPermsWeb editor, new CF Workers relay
+
+## Problem
+
+The web editor at hyperperms.com uses a polling/REST model: the plugin POSTs session
+data to the API, the user edits in the browser, then runs `/hp apply <session>` to pull
+changes back. This is slow, manual, and one-directional.
+
+## Goal
+
+Two-way realtime sync between the browser editor and the Hytale plugin via WebSocket,
+so edits flow in both directions without manual commands.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Direction | Two-way full sync | Editor pushes to server, server pushes to editor |
+| Transport | WebSocket via Cloudflare Durable Objects | Already on CF Workers, no extra vendor, ~$5/month |
+| Relay model | API-side (CF DO) | Both plugin and browser connect as WS clients to CF |
+| Default apply mode | Batch with confirm | Safety: changes accumulate, user clicks Apply |
+| Live mode | Toggle in editor UI | Opt-in immediate apply for power users |
+| Undo | Server-side undo history (last 20 ops) | Reversible batch applies |
+| Message format | Incremental diffs (operations) | Small payloads, natural undo, efficient |
+| Conflict handling | Auto-merge non-conflicting, UI for conflicts | Server changes to different entities merge silently |
+
+## Architecture
+
+```
+Browser (Next.js) CF Durable Object Hytale Plugin (Java)
+ | (1 DO per session) |
+ |--- WS connect -------->| |
+ | |<-------- WS connect ---------------|
+ | | |
+ |-- editor.change ------->| (stores op in pending list) |
+ | | |
+ |-- batch.apply --------->| |
+ | |--- batch.apply ------------------->|
+ | | [applies to live server]
+ | |<--- apply.result ------------------|
+ |<-- apply.result --------| |
+ | | |
+ | |<--- server.change -----------------|
+ |<-- server.change -------| [in-game command ran]
+```
+
+### Session Lifecycle
+
+1. Player runs `/hp editor` in-game
+2. Plugin creates session via existing REST API (POST /api/session/create)
+3. API returns session ID + editor URL (unchanged)
+4. Plugin opens WebSocket to `wss://ws.hyperperms.com/session/<id>` as `plugin` role
+5. Player opens editor in browser, editor opens WebSocket to same URL as `editor` role
+6. DO has both connections -- relay begins
+7. On disconnect/timeout, DO hibernates (cost-efficient)
+8. Session expires after 24h (same as current TTL)
+
+### Why CF Durable Objects
+
+- CF Workers already in use (no new vendor)
+- DOs can hold persistent WebSocket connections (unlike Vercel serverless)
+- Built-in hibernation API saves costs when idle
+- Native WebSocket support with `acceptWebSocket()` API
+- Cost: ~$0.15/M requests + $0.50/GB-month -- effectively free at our volume
+- Stays within Cloudflare ecosystem
+
+## Message Protocol
+
+### Operation Types
+
+All messages are JSON with a `type` field. Operations are the atomic unit of change.
+
+```typescript
+// === Editor -> DO -> Plugin ===
+
+// Individual changes (accumulated in batch mode, applied immediately in live mode)
+{ type: "op", op: "permission.add", target: "group:admin", node: "server.kick", value: true }
+{ type: "op", op: "permission.remove", target: "group:admin", node: "server.kick" }
+{ type: "op", op: "permission.set", target: "user:<uuid>", node: "chat.color", value: false }
+{ type: "op", op: "group.create", name: "moderator", weight: 50, parents: ["default"] }
+{ type: "op", op: "group.delete", name: "moderator" }
+{ type: "op", op: "group.setMeta", target: "admin", key: "prefix", value: "&c[Admin] " }
+{ type: "op", op: "group.setWeight", target: "admin", weight: 100 }
+{ type: "op", op: "group.addParent", target: "moderator", parent: "default" }
+{ type: "op", op: "group.removeParent", target: "moderator", parent: "default" }
+{ type: "op", op: "user.addGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "user.removeGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "track.create", name: "staff", groups: ["default", "helper", "mod", "admin"] }
+{ type: "op", op: "track.delete", name: "staff" }
+{ type: "op", op: "track.addGroup", target: "staff", group: "moderator", position: 2 }
+{ type: "op", op: "track.removeGroup", target: "staff", group: "moderator" }
+
+// Batch apply (batch mode only)
+{ type: "batch.apply" }
+
+// Mode switch
+{ type: "session.mode", mode: "live" | "batch" }
+
+// === Plugin -> DO -> Editor ===
+
+// Server-side change (in-game command, API, another plugin)
+{ type: "server.change", op: "permission.add", target: "group:admin", node: "fly.use",
+ value: true, source: "console", timestamp: 1708617600000 }
+
+// Apply result
+{ type: "apply.result", success: true, applied: 5, failed: 0,
+ errors: [], undoId: "abc123" }
+
+// Undo result
+{ type: "undo.result", success: true, undoId: "abc123", reverted: 5 }
+
+// === Control messages (both directions) ===
+
+{ type: "session.sync", data: { groups: [...], users: [...], tracks: [...] } }
+{ type: "session.ping" }
+{ type: "session.pong" }
+{ type: "session.error", code: "CONFLICT", message: "...", details: {...} }
+```
+
+### Operation Inversion (for undo)
+
+Each operation has a natural inverse stored in the undo history:
+
+| Operation | Inverse |
+|---|---|
+| `permission.add` | `permission.remove` (same target/node) |
+| `permission.remove` | `permission.add` (with original value) |
+| `group.create` | `group.delete` |
+| `group.delete` | `group.create` (with full group data snapshot) |
+| `group.setWeight` | `group.setWeight` (with previous weight) |
+| `user.addGroup` | `user.removeGroup` |
+| `user.removeGroup` | `user.addGroup` |
+| `track.addGroup` | `track.removeGroup` |
+
+## Conflict Detection
+
+### Non-conflicting (auto-merge)
+
+Server change to entity A while editor has pending changes to entity B:
+- Apply server change to editor state silently
+- Show subtle indicator that server state updated (e.g. pulse animation on the changed entity)
+
+### Conflicting
+
+Server change to entity A while editor has pending changes to entity A:
+- Mark the entity with a conflict indicator in the UI
+- Show conflict banner: "Server changed [group: admin] -- your local changes may conflict"
+- Options: "Keep mine", "Accept server", "View diff"
+- Conflict state clears when user resolves
+
+### Detection Logic
+
+Conflict = same `target` value in both a pending editor op and an incoming server change.
+Tracked per-entity, not per-field (simple and predictable).
+
+## Undo History
+
+- Stored in the Durable Object's transactional storage
+- Last 20 batch applies, each with its inverse operations
+- Each undo entry: `{ undoId, timestamp, ops: Operation[], inverseOps: Operation[] }`
+- Undo request: `{ type: "undo", undoId: "abc123" }` -> sends inverse ops to plugin
+- History clears on session expiry
+
+## Three Codebases
+
+### 1. CF Workers (new Durable Object)
+
+**Location:** New worker in existing CF project or standalone
+**Responsibilities:**
+- Accept WebSocket connections from editor and plugin
+- Route messages between them based on type
+- Store pending operations (batch mode)
+- Maintain undo history
+- Handle hibernation for cost efficiency
+- Session authentication (validate session ID against Upstash Redis)
+
+**Key files:**
+- `src/session-do.ts` -- Durable Object class with WebSocket handlers
+- `src/index.ts` -- Worker entry point, routes `/session/:id` to DO
+- `wrangler.toml` -- DO binding configuration
+
+### 2. HyperPermsWeb (Next.js editor)
+
+**Changes:**
+- New WebSocket hook: `useRealtimeSession(sessionId)` -- manages WS connection, reconnection, message handling
+- Editor state: track pending operations, conflict state
+- UI: "Live" toggle switch, Apply button (batch mode), conflict banners, undo button
+- Connection status indicator (connected/reconnecting/disconnected)
+- Replace current `PUT /api/session` save flow with WebSocket ops
+
+**Key files:**
+- `src/hooks/useRealtimeSession.ts` -- WebSocket connection + state management
+- `src/components/editor/RealtimeStatus.tsx` -- Connection indicator
+- `src/components/editor/ConflictBanner.tsx` -- Conflict resolution UI
+- `src/components/editor/LiveModeToggle.tsx` -- Live/batch toggle
+- Modifications to existing editor components to dispatch ops instead of direct state mutation
+
+### 3. HyperPerms (Java plugin)
+
+**Changes:**
+- New `WebSocketClient` class using Java 11+ `HttpClient` WebSocket API
+- Change listener: hook into existing EventBus to detect in-game permission changes
+- Apply handler: receive ops from editor, apply them through existing manager layer
+- Undo support: store pre-apply snapshots for revert
+- Auto-reconnect on connection loss
+- New config options: `webEditor.realtimeEnabled`, `webEditor.wsUrl`
+
+**Key files:**
+- `src/main/java/com/hyperperms/web/RealtimeClient.java` -- WebSocket client
+- `src/main/java/com/hyperperms/web/RealtimeMessageHandler.java` -- Message routing
+- `src/main/java/com/hyperperms/web/OperationApplier.java` -- Applies ops to live state
+- `src/main/java/com/hyperperms/web/ChangeListener.java` -- Detects in-game changes, sends to WS
+- Modifications to `WebEditorService.java` -- Start WS after session creation
+
+## Security
+
+- Session ID serves as auth token (same as current model)
+- DO validates session exists in Redis before accepting WS upgrade
+- Plugin identifies as `role: plugin` on connect, editor as `role: editor`
+- Only one plugin connection per session (reject duplicates)
+- Rate limiting on operations (prevent abuse from editor)
+- All traffic over WSS (TLS)
+
+## Migration / Backwards Compatibility
+
+- Existing REST flow continues to work (no breaking changes)
+- WebSocket is additive -- if WS connection fails, editor falls back to REST save/load
+- Plugin config: `webEditor.realtimeEnabled: true` (default true for new installs)
+- `/hp apply` command still works as fallback

src/main/java/com/hyperperms/HyperPerms.java

@@ -217,7 +217,7 @@ public void enable() {
 
  // Initialize managers with event bus
  groupManager = new GroupManagerImpl(storage, cacheInvalidator, eventBus);
- trackManager = new TrackManagerImpl(storage);
+ trackManager = new TrackManagerImpl(storage, eventBus);
  userManager = new UserManagerImpl(storage, cache, eventBus, config.getDefaultGroup());
 
  // Load data
@@ -428,6 +428,11 @@ public void disable() {
  placeholderApiIntegration.unregister();
  }
 
+ // Disconnect WebSocket before shutting down scheduler
+ if (webEditorService != null) {
+ webEditorService.disconnectWebSocket();
+ }
+
  // Stop scheduled tasks FIRST to prevent new storage executor submissions
  if (expiryTask != null) {
  expiryTask.cancel(true);

src/main/java/com/hyperperms/api/events/HyperPermsEvent.java

@@ -71,6 +71,21 @@ enum EventType {
  */
  DATA_RELOAD,
 
+ /**
+ * Fired when a track is created.
+ */
+ TRACK_CREATE,
+
+ /**
+ * Fired when a track is deleted.
+ */
+ TRACK_DELETE,
+
+ /**
+ * Fired when a track is modified.
+ */
+ TRACK_MODIFY,
+
  /**
  * Fired when a user is promoted along a track.
  */

src/main/java/com/hyperperms/api/events/TrackCreateEvent.java

@@ -0,0 +1,112 @@
+package com.hyperperms.api.events;
+
+import com.hyperperms.model.Track;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Event fired when a track is created.
+ * <p>
+ * This event can be cancelled to prevent the track from being created.
+ * The PRE state fires before creation, the POST state fires after.
+ */
+public final class TrackCreateEvent implements HyperPermsEvent, Cancellable {
+
+ /**
+ * The state of the track creation event.
+ */
+ public enum State {
+ /**
+ * Before the track is created. The event can be cancelled at this point.
+ */
+ PRE,
+
+ /**
+ * After the track has been created. Cancellation has no effect.
+ */
+ POST
+ }
+
+ private final String trackName;
+ private final Track track;
+ private final State state;
+ private boolean cancelled;
+
+ /**
+ * Creates a PRE event for track creation.
+ *
+ * @param trackName the name of the track being created
+ */
+ public TrackCreateEvent(@NotNull String trackName) {
+ this.trackName = trackName;
+ this.track = null;
+ this.state = State.PRE;
+ this.cancelled = false;
+ }
+
+ /**
+ * Creates a POST event for track creation.
+ *
+ * @param track the created track
+ */
+ public TrackCreateEvent(@NotNull Track track) {
+ this.trackName = track.getName();
+ this.track = track;
+ this.state = State.POST;
+ this.cancelled = false;
+ }
+
+ @Override
+ public EventType getType() {
+ return EventType.TRACK_CREATE;
+ }
+
+ /**
+ * Gets the name of the track being created.
+ *
+ * @return the track name
+ */
+ @NotNull
+ public String getTrackName() {
+ return trackName;
+ }
+
+ /**
+ * Gets the created track.
+ * <p>
+ * This is only available in the POST state. Returns null in PRE state.
+ *
+ * @return the track, or null if PRE state
+ */
+ @Nullable
+ public Track getTrack() {
+ return track;
+ }
+
+ /**
+ * Gets the state of this event.
+ *
+ * @return the state
+ */
+ @NotNull
+ public State getState() {
+ return state;
+ }
+
+ @Override
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ @Override
+ public void setCancelled(boolean cancelled) {
+ if (state == State.PRE) {
+ this.cancelled = cancelled;
+ }
+ }
+
+ @Override
+ public String toString() {
+ return "TrackCreateEvent{trackName='" + trackName + "', state=" + state + ", cancelled=" + cancelled + "}";
+ }
+}

.gitignore

@@ -19,6 +19,7 @@ data/
 # Temp
 *.log
 .claude/
+.worktrees/
 CLAUDE.md
 .serena/
 .playwright-mcp/

docs/plans/2026-02-22-realtime-websocket-editor-design.md

@@ -0,0 +1,233 @@
+# Realtime WebSocket Editor Design
+
+**Date:** 2026-02-22
+**Status:** Approved
+**Scope:** HyperPerms plugin, HyperPermsWeb editor, new CF Workers relay
+
+## Problem
+
+The web editor at hyperperms.com uses a polling/REST model: the plugin POSTs session
+data to the API, the user edits in the browser, then runs `/hp apply <session>` to pull
+changes back. This is slow, manual, and one-directional.
+
+## Goal
+
+Two-way realtime sync between the browser editor and the Hytale plugin via WebSocket,
+so edits flow in both directions without manual commands.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Direction | Two-way full sync | Editor pushes to server, server pushes to editor |
+| Transport | WebSocket via Cloudflare Durable Objects | Already on CF Workers, no extra vendor, ~$5/month |
+| Relay model | API-side (CF DO) | Both plugin and browser connect as WS clients to CF |
+| Default apply mode | Batch with confirm | Safety: changes accumulate, user clicks Apply |
+| Live mode | Toggle in editor UI | Opt-in immediate apply for power users |
+| Undo | Server-side undo history (last 20 ops) | Reversible batch applies |
+| Message format | Incremental diffs (operations) | Small payloads, natural undo, efficient |
+| Conflict handling | Auto-merge non-conflicting, UI for conflicts | Server changes to different entities merge silently |
+
+## Architecture
+
+```
+Browser (Next.js) CF Durable Object Hytale Plugin (Java)
+ | (1 DO per session) |
+ |--- WS connect -------->| |
+ | |<-------- WS connect ---------------|
+ | | |
+ |-- editor.change ------->| (stores op in pending list) |
+ | | |
+ |-- batch.apply --------->| |
+ | |--- batch.apply ------------------->|
+ | | [applies to live server]
+ | |<--- apply.result ------------------|
+ |<-- apply.result --------| |
+ | | |
+ | |<--- server.change -----------------|
+ |<-- server.change -------| [in-game command ran]
+```
+
+### Session Lifecycle
+
+1. Player runs `/hp editor` in-game
+2. Plugin creates session via existing REST API (POST /api/session/create)
+3. API returns session ID + editor URL (unchanged)
+4. Plugin opens WebSocket to `wss://ws.hyperperms.com/session/<id>` as `plugin` role
+5. Player opens editor in browser, editor opens WebSocket to same URL as `editor` role
+6. DO has both connections -- relay begins
+7. On disconnect/timeout, DO hibernates (cost-efficient)
+8. Session expires after 24h (same as current TTL)
+
+### Why CF Durable Objects
+
+- CF Workers already in use (no new vendor)
+- DOs can hold persistent WebSocket connections (unlike Vercel serverless)
+- Built-in hibernation API saves costs when idle
+- Native WebSocket support with `acceptWebSocket()` API
+- Cost: ~$0.15/M requests + $0.50/GB-month -- effectively free at our volume
+- Stays within Cloudflare ecosystem
+
+## Message Protocol
+
+### Operation Types
+
+All messages are JSON with a `type` field. Operations are the atomic unit of change.
+
+```typescript
+// === Editor -> DO -> Plugin ===
+
+// Individual changes (accumulated in batch mode, applied immediately in live mode)
+{ type: "op", op: "permission.add", target: "group:admin", node: "server.kick", value: true }
+{ type: "op", op: "permission.remove", target: "group:admin", node: "server.kick" }
+{ type: "op", op: "permission.set", target: "user:<uuid>", node: "chat.color", value: false }
+{ type: "op", op: "group.create", name: "moderator", weight: 50, parents: ["default"] }
+{ type: "op", op: "group.delete", name: "moderator" }
+{ type: "op", op: "group.setMeta", target: "admin", key: "prefix", value: "&c[Admin] " }
+{ type: "op", op: "group.setWeight", target: "admin", weight: 100 }
+{ type: "op", op: "group.addParent", target: "moderator", parent: "default" }
+{ type: "op", op: "group.removeParent", target: "moderator", parent: "default" }
+{ type: "op", op: "user.addGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "user.removeGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "track.create", name: "staff", groups: ["default", "helper", "mod", "admin"] }
+{ type: "op", op: "track.delete", name: "staff" }
+{ type: "op", op: "track.addGroup", target: "staff", group: "moderator", position: 2 }
+{ type: "op", op: "track.removeGroup", target: "staff", group: "moderator" }
+
+// Batch apply (batch mode only)
+{ type: "batch.apply" }
+
+// Mode switch
+{ type: "session.mode", mode: "live" | "batch" }
+
+// === Plugin -> DO -> Editor ===
+
+// Server-side change (in-game command, API, another plugin)
+{ type: "server.change", op: "permission.add", target: "group:admin", node: "fly.use",
+ value: true, source: "console", timestamp: 1708617600000 }
+
+// Apply result
+{ type: "apply.result", success: true, applied: 5, failed: 0,
+ errors: [], undoId: "abc123" }
+
+// Undo result
+{ type: "undo.result", success: true, undoId: "abc123", reverted: 5 }
+
+// === Control messages (both directions) ===
+
+{ type: "session.sync", data: { groups: [...], users: [...], tracks: [...] } }
+{ type: "session.ping" }
+{ type: "session.pong" }
+{ type: "session.error", code: "CONFLICT", message: "...", details: {...} }
+```
+
+### Operation Inversion (for undo)
+
+Each operation has a natural inverse stored in the undo history:
+
+| Operation | Inverse |
+|---|---|
+| `permission.add` | `permission.remove` (same target/node) |
+| `permission.remove` | `permission.add` (with original value) |
+| `group.create` | `group.delete` |
+| `group.delete` | `group.create` (with full group data snapshot) |
+| `group.setWeight` | `group.setWeight` (with previous weight) |
+| `user.addGroup` | `user.removeGroup` |
+| `user.removeGroup` | `user.addGroup` |
+| `track.addGroup` | `track.removeGroup` |
+
+## Conflict Detection
+
+### Non-conflicting (auto-merge)
+
+Server change to entity A while editor has pending changes to entity B:
+- Apply server change to editor state silently
+- Show subtle indicator that server state updated (e.g. pulse animation on the changed entity)
+
+### Conflicting
+
+Server change to entity A while editor has pending changes to entity A:
+- Mark the entity with a conflict indicator in the UI
+- Show conflict banner: "Server changed [group: admin] -- your local changes may conflict"
+- Options: "Keep mine", "Accept server", "View diff"
+- Conflict state clears when user resolves
+
+### Detection Logic
+
+Conflict = same `target` value in both a pending editor op and an incoming server change.
+Tracked per-entity, not per-field (simple and predictable).
+
+## Undo History
+
+- Stored in the Durable Object's transactional storage
+- Last 20 batch applies, each with its inverse operations
+- Each undo entry: `{ undoId, timestamp, ops: Operation[], inverseOps: Operation[] }`
+- Undo request: `{ type: "undo", undoId: "abc123" }` -> sends inverse ops to plugin
+- History clears on session expiry
+
+## Three Codebases
+
+### 1. CF Workers (new Durable Object)
+
+**Location:** New worker in existing CF project or standalone
+**Responsibilities:**
+- Accept WebSocket connections from editor and plugin
+- Route messages between them based on type
+- Store pending operations (batch mode)
+- Maintain undo history
+- Handle hibernation for cost efficiency
+- Session authentication (validate session ID against Upstash Redis)
+
+**Key files:**
+- `src/session-do.ts` -- Durable Object class with WebSocket handlers
+- `src/index.ts` -- Worker entry point, routes `/session/:id` to DO
+- `wrangler.toml` -- DO binding configuration
+
+### 2. HyperPermsWeb (Next.js editor)
+
+**Changes:**
+- New WebSocket hook: `useRealtimeSession(sessionId)` -- manages WS connection, reconnection, message handling
+- Editor state: track pending operations, conflict state
+- UI: "Live" toggle switch, Apply button (batch mode), conflict banners, undo button
+- Connection status indicator (connected/reconnecting/disconnected)
+- Replace current `PUT /api/session` save flow with WebSocket ops
+
+**Key files:**
+- `src/hooks/useRealtimeSession.ts` -- WebSocket connection + state management
+- `src/components/editor/RealtimeStatus.tsx` -- Connection indicator
+- `src/components/editor/ConflictBanner.tsx` -- Conflict resolution UI
+- `src/components/editor/LiveModeToggle.tsx` -- Live/batch toggle
+- Modifications to existing editor components to dispatch ops instead of direct state mutation
+
+### 3. HyperPerms (Java plugin)
+
+**Changes:**
+- New `WebSocketClient` class using Java 11+ `HttpClient` WebSocket API
+- Change listener: hook into existing EventBus to detect in-game permission changes
+- Apply handler: receive ops from editor, apply them through existing manager layer
+- Undo support: store pre-apply snapshots for revert
+- Auto-reconnect on connection loss
+- New config options: `webEditor.realtimeEnabled`, `webEditor.wsUrl`
+
+**Key files:**
+- `src/main/java/com/hyperperms/web/RealtimeClient.java` -- WebSocket client
+- `src/main/java/com/hyperperms/web/RealtimeMessageHandler.java` -- Message routing
+- `src/main/java/com/hyperperms/web/OperationApplier.java` -- Applies ops to live state
+- `src/main/java/com/hyperperms/web/ChangeListener.java` -- Detects in-game changes, sends to WS
+- Modifications to `WebEditorService.java` -- Start WS after session creation
+
+## Security
+
+- Session ID serves as auth token (same as current model)
+- DO validates session exists in Redis before accepting WS upgrade
+- Plugin identifies as `role: plugin` on connect, editor as `role: editor`
+- Only one plugin connection per session (reject duplicates)
+- Rate limiting on operations (prevent abuse from editor)
+- All traffic over WSS (TLS)
+
+## Migration / Backwards Compatibility
+
+- Existing REST flow continues to work (no breaking changes)
+- WebSocket is additive -- if WS connection fails, editor falls back to REST save/load
+- Plugin config: `webEditor.realtimeEnabled: true` (default true for new installs)
+- `/hp apply` command still works as fallback

src/main/java/com/hyperperms/HyperPerms.java

@@ -217,7 +217,7 @@ public void enable() {
 
  // Initialize managers with event bus
  groupManager = new GroupManagerImpl(storage, cacheInvalidator, eventBus);
- trackManager = new TrackManagerImpl(storage);
+ trackManager = new TrackManagerImpl(storage, eventBus);
  userManager = new UserManagerImpl(storage, cache, eventBus, config.getDefaultGroup());
 
  // Load data
@@ -428,6 +428,11 @@ public void disable() {
  placeholderApiIntegration.unregister();
  }
 
+ // Disconnect WebSocket before shutting down scheduler
+ if (webEditorService != null) {
+ webEditorService.disconnectWebSocket();
+ }
+
  // Stop scheduled tasks FIRST to prevent new storage executor submissions
  if (expiryTask != null) {
  expiryTask.cancel(true);

src/main/java/com/hyperperms/api/events/HyperPermsEvent.java

@@ -71,6 +71,21 @@ enum EventType {
  */
  DATA_RELOAD,
 
+ /**
+ * Fired when a track is created.
+ */
+ TRACK_CREATE,
+
+ /**
+ * Fired when a track is deleted.
+ */
+ TRACK_DELETE,
+
+ /**
+ * Fired when a track is modified.
+ */
+ TRACK_MODIFY,
+
  /**
  * Fired when a user is promoted along a track.
  */

src/main/java/com/hyperperms/api/events/TrackCreateEvent.java

@@ -0,0 +1,112 @@
+package com.hyperperms.api.events;
+
+import com.hyperperms.model.Track;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Event fired when a track is created.
+ * <p>
+ * This event can be cancelled to prevent the track from being created.
+ * The PRE state fires before creation, the POST state fires after.
+ */
+public final class TrackCreateEvent implements HyperPermsEvent, Cancellable {
+
+ /**
+ * The state of the track creation event.
+ */
+ public enum State {
+ /**
+ * Before the track is created. The event can be cancelled at this point.
+ */
+ PRE,
+
+ /**
+ * After the track has been created. Cancellation has no effect.
+ */
+ POST
+ }
+
+ private final String trackName;
+ private final Track track;
+ private final State state;
+ private boolean cancelled;
+
+ /**
+ * Creates a PRE event for track creation.
+ *
+ * @param trackName the name of the track being created
+ */
+ public TrackCreateEvent(@NotNull String trackName) {
+ this.trackName = trackName;
+ this.track = null;
+ this.state = State.PRE;
+ this.cancelled = false;
+ }
+
+ /**
+ * Creates a POST event for track creation.
+ *
+ * @param track the created track
+ */
+ public TrackCreateEvent(@NotNull Track track) {
+ this.trackName = track.getName();
+ this.track = track;
+ this.state = State.POST;
+ this.cancelled = false;
+ }
+
+ @Override
+ public EventType getType() {
+ return EventType.TRACK_CREATE;
+ }
+
+ /**
+ * Gets the name of the track being created.
+ *
+ * @return the track name
+ */
+ @NotNull
+ public String getTrackName() {
+ return trackName;
+ }
+
+ /**
+ * Gets the created track.
+ * <p>
+ * This is only available in the POST state. Returns null in PRE state.
+ *
+ * @return the track, or null if PRE state
+ */
+ @Nullable
+ public Track getTrack() {
+ return track;
+ }
+
+ /**
+ * Gets the state of this event.
+ *
+ * @return the state
+ */
+ @NotNull
+ public State getState() {
+ return state;
+ }
+
+ @Override
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ @Override
+ public void setCancelled(boolean cancelled) {
+ if (state == State.PRE) {
+ this.cancelled = cancelled;
+ }
+ }
+
+ @Override
+ public String toString() {
+ return "TrackCreateEvent{trackName='" + trackName + "', state=" + state + ", cancelled=" + cancelled + "}";
+ }
+}

.gitignore

@@ -19,6 +19,7 @@ data/
 # Temp
 *.log
 .claude/
+.worktrees/
 CLAUDE.md
 .serena/
 .playwright-mcp/

docs/plans/2026-02-22-realtime-websocket-editor-design.md

@@ -0,0 +1,233 @@
+# Realtime WebSocket Editor Design
+
+**Date:** 2026-02-22
+**Status:** Approved
+**Scope:** HyperPerms plugin, HyperPermsWeb editor, new CF Workers relay
+
+## Problem
+
+The web editor at hyperperms.com uses a polling/REST model: the plugin POSTs session
+data to the API, the user edits in the browser, then runs `/hp apply <session>` to pull
+changes back. This is slow, manual, and one-directional.
+
+## Goal
+
+Two-way realtime sync between the browser editor and the Hytale plugin via WebSocket,
+so edits flow in both directions without manual commands.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Direction | Two-way full sync | Editor pushes to server, server pushes to editor |
+| Transport | WebSocket via Cloudflare Durable Objects | Already on CF Workers, no extra vendor, ~$5/month |
+| Relay model | API-side (CF DO) | Both plugin and browser connect as WS clients to CF |
+| Default apply mode | Batch with confirm | Safety: changes accumulate, user clicks Apply |
+| Live mode | Toggle in editor UI | Opt-in immediate apply for power users |
+| Undo | Server-side undo history (last 20 ops) | Reversible batch applies |
+| Message format | Incremental diffs (operations) | Small payloads, natural undo, efficient |
+| Conflict handling | Auto-merge non-conflicting, UI for conflicts | Server changes to different entities merge silently |
+
+## Architecture
+
+```
+Browser (Next.js) CF Durable Object Hytale Plugin (Java)
+ | (1 DO per session) |
+ |--- WS connect -------->| |
+ | |<-------- WS connect ---------------|
+ | | |
+ |-- editor.change ------->| (stores op in pending list) |
+ | | |
+ |-- batch.apply --------->| |
+ | |--- batch.apply ------------------->|
+ | | [applies to live server]
+ | |<--- apply.result ------------------|
+ |<-- apply.result --------| |
+ | | |
+ | |<--- server.change -----------------|
+ |<-- server.change -------| [in-game command ran]
+```
+
+### Session Lifecycle
+
+1. Player runs `/hp editor` in-game
+2. Plugin creates session via existing REST API (POST /api/session/create)
+3. API returns session ID + editor URL (unchanged)
+4. Plugin opens WebSocket to `wss://ws.hyperperms.com/session/<id>` as `plugin` role
+5. Player opens editor in browser, editor opens WebSocket to same URL as `editor` role
+6. DO has both connections -- relay begins
+7. On disconnect/timeout, DO hibernates (cost-efficient)
+8. Session expires after 24h (same as current TTL)
+
+### Why CF Durable Objects
+
+- CF Workers already in use (no new vendor)
+- DOs can hold persistent WebSocket connections (unlike Vercel serverless)
+- Built-in hibernation API saves costs when idle
+- Native WebSocket support with `acceptWebSocket()` API
+- Cost: ~$0.15/M requests + $0.50/GB-month -- effectively free at our volume
+- Stays within Cloudflare ecosystem
+
+## Message Protocol
+
+### Operation Types
+
+All messages are JSON with a `type` field. Operations are the atomic unit of change.
+
+```typescript
+// === Editor -> DO -> Plugin ===
+
+// Individual changes (accumulated in batch mode, applied immediately in live mode)
+{ type: "op", op: "permission.add", target: "group:admin", node: "server.kick", value: true }
+{ type: "op", op: "permission.remove", target: "group:admin", node: "server.kick" }
+{ type: "op", op: "permission.set", target: "user:<uuid>", node: "chat.color", value: false }
+{ type: "op", op: "group.create", name: "moderator", weight: 50, parents: ["default"] }
+{ type: "op", op: "group.delete", name: "moderator" }
+{ type: "op", op: "group.setMeta", target: "admin", key: "prefix", value: "&c[Admin] " }
+{ type: "op", op: "group.setWeight", target: "admin", weight: 100 }
+{ type: "op", op: "group.addParent", target: "moderator", parent: "default" }
+{ type: "op", op: "group.removeParent", target: "moderator", parent: "default" }
+{ type: "op", op: "user.addGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "user.removeGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "track.create", name: "staff", groups: ["default", "helper", "mod", "admin"] }
+{ type: "op", op: "track.delete", name: "staff" }
+{ type: "op", op: "track.addGroup", target: "staff", group: "moderator", position: 2 }
+{ type: "op", op: "track.removeGroup", target: "staff", group: "moderator" }
+
+// Batch apply (batch mode only)
+{ type: "batch.apply" }
+
+// Mode switch
+{ type: "session.mode", mode: "live" | "batch" }
+
+// === Plugin -> DO -> Editor ===
+
+// Server-side change (in-game command, API, another plugin)
+{ type: "server.change", op: "permission.add", target: "group:admin", node: "fly.use",
+ value: true, source: "console", timestamp: 1708617600000 }
+
+// Apply result
+{ type: "apply.result", success: true, applied: 5, failed: 0,
+ errors: [], undoId: "abc123" }
+
+// Undo result
+{ type: "undo.result", success: true, undoId: "abc123", reverted: 5 }
+
+// === Control messages (both directions) ===
+
+{ type: "session.sync", data: { groups: [...], users: [...], tracks: [...] } }
+{ type: "session.ping" }
+{ type: "session.pong" }
+{ type: "session.error", code: "CONFLICT", message: "...", details: {...} }
+```
+
+### Operation Inversion (for undo)
+
+Each operation has a natural inverse stored in the undo history:
+
+| Operation | Inverse |
+|---|---|
+| `permission.add` | `permission.remove` (same target/node) |
+| `permission.remove` | `permission.add` (with original value) |
+| `group.create` | `group.delete` |
+| `group.delete` | `group.create` (with full group data snapshot) |
+| `group.setWeight` | `group.setWeight` (with previous weight) |
+| `user.addGroup` | `user.removeGroup` |
+| `user.removeGroup` | `user.addGroup` |
+| `track.addGroup` | `track.removeGroup` |
+
+## Conflict Detection
+
+### Non-conflicting (auto-merge)
+
+Server change to entity A while editor has pending changes to entity B:
+- Apply server change to editor state silently
+- Show subtle indicator that server state updated (e.g. pulse animation on the changed entity)
+
+### Conflicting
+
+Server change to entity A while editor has pending changes to entity A:
+- Mark the entity with a conflict indicator in the UI
+- Show conflict banner: "Server changed [group: admin] -- your local changes may conflict"
+- Options: "Keep mine", "Accept server", "View diff"
+- Conflict state clears when user resolves
+
+### Detection Logic
+
+Conflict = same `target` value in both a pending editor op and an incoming server change.
+Tracked per-entity, not per-field (simple and predictable).
+
+## Undo History
+
+- Stored in the Durable Object's transactional storage
+- Last 20 batch applies, each with its inverse operations
+- Each undo entry: `{ undoId, timestamp, ops: Operation[], inverseOps: Operation[] }`
+- Undo request: `{ type: "undo", undoId: "abc123" }` -> sends inverse ops to plugin
+- History clears on session expiry
+
+## Three Codebases
+
+### 1. CF Workers (new Durable Object)
+
+**Location:** New worker in existing CF project or standalone
+**Responsibilities:**
+- Accept WebSocket connections from editor and plugin
+- Route messages between them based on type
+- Store pending operations (batch mode)
+- Maintain undo history
+- Handle hibernation for cost efficiency
+- Session authentication (validate session ID against Upstash Redis)
+
+**Key files:**
+- `src/session-do.ts` -- Durable Object class with WebSocket handlers
+- `src/index.ts` -- Worker entry point, routes `/session/:id` to DO
+- `wrangler.toml` -- DO binding configuration
+
+### 2. HyperPermsWeb (Next.js editor)
+
+**Changes:**
+- New WebSocket hook: `useRealtimeSession(sessionId)` -- manages WS connection, reconnection, message handling
+- Editor state: track pending operations, conflict state
+- UI: "Live" toggle switch, Apply button (batch mode), conflict banners, undo button
+- Connection status indicator (connected/reconnecting/disconnected)
+- Replace current `PUT /api/session` save flow with WebSocket ops
+
+**Key files:**
+- `src/hooks/useRealtimeSession.ts` -- WebSocket connection + state management
+- `src/components/editor/RealtimeStatus.tsx` -- Connection indicator
+- `src/components/editor/ConflictBanner.tsx` -- Conflict resolution UI
+- `src/components/editor/LiveModeToggle.tsx` -- Live/batch toggle
+- Modifications to existing editor components to dispatch ops instead of direct state mutation
+
+### 3. HyperPerms (Java plugin)
+
+**Changes:**
+- New `WebSocketClient` class using Java 11+ `HttpClient` WebSocket API
+- Change listener: hook into existing EventBus to detect in-game permission changes
+- Apply handler: receive ops from editor, apply them through existing manager layer
+- Undo support: store pre-apply snapshots for revert
+- Auto-reconnect on connection loss
+- New config options: `webEditor.realtimeEnabled`, `webEditor.wsUrl`
+
+**Key files:**
+- `src/main/java/com/hyperperms/web/RealtimeClient.java` -- WebSocket client
+- `src/main/java/com/hyperperms/web/RealtimeMessageHandler.java` -- Message routing
+- `src/main/java/com/hyperperms/web/OperationApplier.java` -- Applies ops to live state
+- `src/main/java/com/hyperperms/web/ChangeListener.java` -- Detects in-game changes, sends to WS
+- Modifications to `WebEditorService.java` -- Start WS after session creation
+
+## Security
+
+- Session ID serves as auth token (same as current model)
+- DO validates session exists in Redis before accepting WS upgrade
+- Plugin identifies as `role: plugin` on connect, editor as `role: editor`
+- Only one plugin connection per session (reject duplicates)
+- Rate limiting on operations (prevent abuse from editor)
+- All traffic over WSS (TLS)
+
+## Migration / Backwards Compatibility
+
+- Existing REST flow continues to work (no breaking changes)
+- WebSocket is additive -- if WS connection fails, editor falls back to REST save/load
+- Plugin config: `webEditor.realtimeEnabled: true` (default true for new installs)
+- `/hp apply` command still works as fallback

src/main/java/com/hyperperms/HyperPerms.java

@@ -217,7 +217,7 @@ public void enable() {
 
  // Initialize managers with event bus
  groupManager = new GroupManagerImpl(storage, cacheInvalidator, eventBus);
- trackManager = new TrackManagerImpl(storage);
+ trackManager = new TrackManagerImpl(storage, eventBus);
  userManager = new UserManagerImpl(storage, cache, eventBus, config.getDefaultGroup());
 
  // Load data
@@ -428,6 +428,11 @@ public void disable() {
  placeholderApiIntegration.unregister();
  }
 
+ // Disconnect WebSocket before shutting down scheduler
+ if (webEditorService != null) {
+ webEditorService.disconnectWebSocket();
+ }
+
  // Stop scheduled tasks FIRST to prevent new storage executor submissions
  if (expiryTask != null) {
  expiryTask.cancel(true);

src/main/java/com/hyperperms/api/events/HyperPermsEvent.java

@@ -71,6 +71,21 @@ enum EventType {
  */
  DATA_RELOAD,
 
+ /**
+ * Fired when a track is created.
+ */
+ TRACK_CREATE,
+
+ /**
+ * Fired when a track is deleted.
+ */
+ TRACK_DELETE,
+
+ /**
+ * Fired when a track is modified.
+ */
+ TRACK_MODIFY,
+
  /**
  * Fired when a user is promoted along a track.
  */

src/main/java/com/hyperperms/api/events/TrackCreateEvent.java

@@ -0,0 +1,112 @@
+package com.hyperperms.api.events;
+
+import com.hyperperms.model.Track;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Event fired when a track is created.
+ * <p>
+ * This event can be cancelled to prevent the track from being created.
+ * The PRE state fires before creation, the POST state fires after.
+ */
+public final class TrackCreateEvent implements HyperPermsEvent, Cancellable {
+
+ /**
+ * The state of the track creation event.
+ */
+ public enum State {
+ /**
+ * Before the track is created. The event can be cancelled at this point.
+ */
+ PRE,
+
+ /**
+ * After the track has been created. Cancellation has no effect.
+ */
+ POST
+ }
+
+ private final String trackName;
+ private final Track track;
+ private final State state;
+ private boolean cancelled;
+
+ /**
+ * Creates a PRE event for track creation.
+ *
+ * @param trackName the name of the track being created
+ */
+ public TrackCreateEvent(@NotNull String trackName) {
+ this.trackName = trackName;
+ this.track = null;
+ this.state = State.PRE;
+ this.cancelled = false;
+ }
+
+ /**
+ * Creates a POST event for track creation.
+ *
+ * @param track the created track
+ */
+ public TrackCreateEvent(@NotNull Track track) {
+ this.trackName = track.getName();
+ this.track = track;
+ this.state = State.POST;
+ this.cancelled = false;
+ }
+
+ @Override
+ public EventType getType() {
+ return EventType.TRACK_CREATE;
+ }
+
+ /**
+ * Gets the name of the track being created.
+ *
+ * @return the track name
+ */
+ @NotNull
+ public String getTrackName() {
+ return trackName;
+ }
+
+ /**
+ * Gets the created track.
+ * <p>
+ * This is only available in the POST state. Returns null in PRE state.
+ *
+ * @return the track, or null if PRE state
+ */
+ @Nullable
+ public Track getTrack() {
+ return track;
+ }
+
+ /**
+ * Gets the state of this event.
+ *
+ * @return the state
+ */
+ @NotNull
+ public State getState() {
+ return state;
+ }
+
+ @Override
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ @Override
+ public void setCancelled(boolean cancelled) {
+ if (state == State.PRE) {
+ this.cancelled = cancelled;
+ }
+ }
+
+ @Override
+ public String toString() {
+ return "TrackCreateEvent{trackName='" + trackName + "', state=" + state + ", cancelled=" + cancelled + "}";
+ }
+}

.gitignore

@@ -19,6 +19,7 @@ data/
 # Temp
 *.log
 .claude/
+.worktrees/
 CLAUDE.md
 .serena/
 .playwright-mcp/

docs/plans/2026-02-22-realtime-websocket-editor-design.md

@@ -0,0 +1,233 @@
+# Realtime WebSocket Editor Design
+
+**Date:** 2026-02-22
+**Status:** Approved
+**Scope:** HyperPerms plugin, HyperPermsWeb editor, new CF Workers relay
+
+## Problem
+
+The web editor at hyperperms.com uses a polling/REST model: the plugin POSTs session
+data to the API, the user edits in the browser, then runs `/hp apply <session>` to pull
+changes back. This is slow, manual, and one-directional.
+
+## Goal
+
+Two-way realtime sync between the browser editor and the Hytale plugin via WebSocket,
+so edits flow in both directions without manual commands.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Direction | Two-way full sync | Editor pushes to server, server pushes to editor |
+| Transport | WebSocket via Cloudflare Durable Objects | Already on CF Workers, no extra vendor, ~$5/month |
+| Relay model | API-side (CF DO) | Both plugin and browser connect as WS clients to CF |
+| Default apply mode | Batch with confirm | Safety: changes accumulate, user clicks Apply |
+| Live mode | Toggle in editor UI | Opt-in immediate apply for power users |
+| Undo | Server-side undo history (last 20 ops) | Reversible batch applies |
+| Message format | Incremental diffs (operations) | Small payloads, natural undo, efficient |
+| Conflict handling | Auto-merge non-conflicting, UI for conflicts | Server changes to different entities merge silently |
+
+## Architecture
+
+```
+Browser (Next.js) CF Durable Object Hytale Plugin (Java)
+ | (1 DO per session) |
+ |--- WS connect -------->| |
+ | |<-------- WS connect ---------------|
+ | | |
+ |-- editor.change ------->| (stores op in pending list) |
+ | | |
+ |-- batch.apply --------->| |
+ | |--- batch.apply ------------------->|
+ | | [applies to live server]
+ | |<--- apply.result ------------------|
+ |<-- apply.result --------| |
+ | | |
+ | |<--- server.change -----------------|
+ |<-- server.change -------| [in-game command ran]
+```
+
+### Session Lifecycle
+
+1. Player runs `/hp editor` in-game
+2. Plugin creates session via existing REST API (POST /api/session/create)
+3. API returns session ID + editor URL (unchanged)
+4. Plugin opens WebSocket to `wss://ws.hyperperms.com/session/<id>` as `plugin` role
+5. Player opens editor in browser, editor opens WebSocket to same URL as `editor` role
+6. DO has both connections -- relay begins
+7. On disconnect/timeout, DO hibernates (cost-efficient)
+8. Session expires after 24h (same as current TTL)
+
+### Why CF Durable Objects
+
+- CF Workers already in use (no new vendor)
+- DOs can hold persistent WebSocket connections (unlike Vercel serverless)
+- Built-in hibernation API saves costs when idle
+- Native WebSocket support with `acceptWebSocket()` API
+- Cost: ~$0.15/M requests + $0.50/GB-month -- effectively free at our volume
+- Stays within Cloudflare ecosystem
+
+## Message Protocol
+
+### Operation Types
+
+All messages are JSON with a `type` field. Operations are the atomic unit of change.
+
+```typescript
+// === Editor -> DO -> Plugin ===
+
+// Individual changes (accumulated in batch mode, applied immediately in live mode)
+{ type: "op", op: "permission.add", target: "group:admin", node: "server.kick", value: true }
+{ type: "op", op: "permission.remove", target: "group:admin", node: "server.kick" }
+{ type: "op", op: "permission.set", target: "user:<uuid>", node: "chat.color", value: false }
+{ type: "op", op: "group.create", name: "moderator", weight: 50, parents: ["default"] }
+{ type: "op", op: "group.delete", name: "moderator" }
+{ type: "op", op: "group.setMeta", target: "admin", key: "prefix", value: "&c[Admin] " }
+{ type: "op", op: "group.setWeight", target: "admin", weight: 100 }
+{ type: "op", op: "group.addParent", target: "moderator", parent: "default" }
+{ type: "op", op: "group.removeParent", target: "moderator", parent: "default" }
+{ type: "op", op: "user.addGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "user.removeGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "track.create", name: "staff", groups: ["default", "helper", "mod", "admin"] }
+{ type: "op", op: "track.delete", name: "staff" }
+{ type: "op", op: "track.addGroup", target: "staff", group: "moderator", position: 2 }
+{ type: "op", op: "track.removeGroup", target: "staff", group: "moderator" }
+
+// Batch apply (batch mode only)
+{ type: "batch.apply" }
+
+// Mode switch
+{ type: "session.mode", mode: "live" | "batch" }
+
+// === Plugin -> DO -> Editor ===
+
+// Server-side change (in-game command, API, another plugin)
+{ type: "server.change", op: "permission.add", target: "group:admin", node: "fly.use",
+ value: true, source: "console", timestamp: 1708617600000 }
+
+// Apply result
+{ type: "apply.result", success: true, applied: 5, failed: 0,
+ errors: [], undoId: "abc123" }
+
+// Undo result
+{ type: "undo.result", success: true, undoId: "abc123", reverted: 5 }
+
+// === Control messages (both directions) ===
+
+{ type: "session.sync", data: { groups: [...], users: [...], tracks: [...] } }
+{ type: "session.ping" }
+{ type: "session.pong" }
+{ type: "session.error", code: "CONFLICT", message: "...", details: {...} }
+```
+
+### Operation Inversion (for undo)
+
+Each operation has a natural inverse stored in the undo history:
+
+| Operation | Inverse |
+|---|---|
+| `permission.add` | `permission.remove` (same target/node) |
+| `permission.remove` | `permission.add` (with original value) |
+| `group.create` | `group.delete` |
+| `group.delete` | `group.create` (with full group data snapshot) |
+| `group.setWeight` | `group.setWeight` (with previous weight) |
+| `user.addGroup` | `user.removeGroup` |
+| `user.removeGroup` | `user.addGroup` |
+| `track.addGroup` | `track.removeGroup` |
+
+## Conflict Detection
+
+### Non-conflicting (auto-merge)
+
+Server change to entity A while editor has pending changes to entity B:
+- Apply server change to editor state silently
+- Show subtle indicator that server state updated (e.g. pulse animation on the changed entity)
+
+### Conflicting
+
+Server change to entity A while editor has pending changes to entity A:
+- Mark the entity with a conflict indicator in the UI
+- Show conflict banner: "Server changed [group: admin] -- your local changes may conflict"
+- Options: "Keep mine", "Accept server", "View diff"
+- Conflict state clears when user resolves
+
+### Detection Logic
+
+Conflict = same `target` value in both a pending editor op and an incoming server change.
+Tracked per-entity, not per-field (simple and predictable).
+
+## Undo History
+
+- Stored in the Durable Object's transactional storage
+- Last 20 batch applies, each with its inverse operations
+- Each undo entry: `{ undoId, timestamp, ops: Operation[], inverseOps: Operation[] }`
+- Undo request: `{ type: "undo", undoId: "abc123" }` -> sends inverse ops to plugin
+- History clears on session expiry
+
+## Three Codebases
+
+### 1. CF Workers (new Durable Object)
+
+**Location:** New worker in existing CF project or standalone
+**Responsibilities:**
+- Accept WebSocket connections from editor and plugin
+- Route messages between them based on type
+- Store pending operations (batch mode)
+- Maintain undo history
+- Handle hibernation for cost efficiency
+- Session authentication (validate session ID against Upstash Redis)
+
+**Key files:**
+- `src/session-do.ts` -- Durable Object class with WebSocket handlers
+- `src/index.ts` -- Worker entry point, routes `/session/:id` to DO
+- `wrangler.toml` -- DO binding configuration
+
+### 2. HyperPermsWeb (Next.js editor)
+
+**Changes:**
+- New WebSocket hook: `useRealtimeSession(sessionId)` -- manages WS connection, reconnection, message handling
+- Editor state: track pending operations, conflict state
+- UI: "Live" toggle switch, Apply button (batch mode), conflict banners, undo button
+- Connection status indicator (connected/reconnecting/disconnected)
+- Replace current `PUT /api/session` save flow with WebSocket ops
+
+**Key files:**
+- `src/hooks/useRealtimeSession.ts` -- WebSocket connection + state management
+- `src/components/editor/RealtimeStatus.tsx` -- Connection indicator
+- `src/components/editor/ConflictBanner.tsx` -- Conflict resolution UI
+- `src/components/editor/LiveModeToggle.tsx` -- Live/batch toggle
+- Modifications to existing editor components to dispatch ops instead of direct state mutation
+
+### 3. HyperPerms (Java plugin)
+
+**Changes:**
+- New `WebSocketClient` class using Java 11+ `HttpClient` WebSocket API
+- Change listener: hook into existing EventBus to detect in-game permission changes
+- Apply handler: receive ops from editor, apply them through existing manager layer
+- Undo support: store pre-apply snapshots for revert
+- Auto-reconnect on connection loss
+- New config options: `webEditor.realtimeEnabled`, `webEditor.wsUrl`
+
+**Key files:**
+- `src/main/java/com/hyperperms/web/RealtimeClient.java` -- WebSocket client
+- `src/main/java/com/hyperperms/web/RealtimeMessageHandler.java` -- Message routing
+- `src/main/java/com/hyperperms/web/OperationApplier.java` -- Applies ops to live state
+- `src/main/java/com/hyperperms/web/ChangeListener.java` -- Detects in-game changes, sends to WS
+- Modifications to `WebEditorService.java` -- Start WS after session creation
+
+## Security
+
+- Session ID serves as auth token (same as current model)
+- DO validates session exists in Redis before accepting WS upgrade
+- Plugin identifies as `role: plugin` on connect, editor as `role: editor`
+- Only one plugin connection per session (reject duplicates)
+- Rate limiting on operations (prevent abuse from editor)
+- All traffic over WSS (TLS)
+
+## Migration / Backwards Compatibility
+
+- Existing REST flow continues to work (no breaking changes)
+- WebSocket is additive -- if WS connection fails, editor falls back to REST save/load
+- Plugin config: `webEditor.realtimeEnabled: true` (default true for new installs)
+- `/hp apply` command still works as fallback

src/main/java/com/hyperperms/HyperPerms.java

@@ -217,7 +217,7 @@ public void enable() {
 
  // Initialize managers with event bus
  groupManager = new GroupManagerImpl(storage, cacheInvalidator, eventBus);
- trackManager = new TrackManagerImpl(storage);
+ trackManager = new TrackManagerImpl(storage, eventBus);
  userManager = new UserManagerImpl(storage, cache, eventBus, config.getDefaultGroup());
 
  // Load data
@@ -428,6 +428,11 @@ public void disable() {
  placeholderApiIntegration.unregister();
  }
 
+ // Disconnect WebSocket before shutting down scheduler
+ if (webEditorService != null) {
+ webEditorService.disconnectWebSocket();
+ }
+
  // Stop scheduled tasks FIRST to prevent new storage executor submissions
  if (expiryTask != null) {
  expiryTask.cancel(true);

src/main/java/com/hyperperms/api/events/HyperPermsEvent.java

@@ -71,6 +71,21 @@ enum EventType {
  */
  DATA_RELOAD,
 
+ /**
+ * Fired when a track is created.
+ */
+ TRACK_CREATE,
+
+ /**
+ * Fired when a track is deleted.
+ */
+ TRACK_DELETE,
+
+ /**
+ * Fired when a track is modified.
+ */
+ TRACK_MODIFY,
+
  /**
  * Fired when a user is promoted along a track.
  */

src/main/java/com/hyperperms/api/events/TrackCreateEvent.java

@@ -0,0 +1,112 @@
+package com.hyperperms.api.events;
+
+import com.hyperperms.model.Track;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Event fired when a track is created.
+ * <p>
+ * This event can be cancelled to prevent the track from being created.
+ * The PRE state fires before creation, the POST state fires after.
+ */
+public final class TrackCreateEvent implements HyperPermsEvent, Cancellable {
+
+ /**
+ * The state of the track creation event.
+ */
+ public enum State {
+ /**
+ * Before the track is created. The event can be cancelled at this point.
+ */
+ PRE,
+
+ /**
+ * After the track has been created. Cancellation has no effect.
+ */
+ POST
+ }
+
+ private final String trackName;
+ private final Track track;
+ private final State state;
+ private boolean cancelled;
+
+ /**
+ * Creates a PRE event for track creation.
+ *
+ * @param trackName the name of the track being created
+ */
+ public TrackCreateEvent(@NotNull String trackName) {
+ this.trackName = trackName;
+ this.track = null;
+ this.state = State.PRE;
+ this.cancelled = false;
+ }
+
+ /**
+ * Creates a POST event for track creation.
+ *
+ * @param track the created track
+ */
+ public TrackCreateEvent(@NotNull Track track) {
+ this.trackName = track.getName();
+ this.track = track;
+ this.state = State.POST;
+ this.cancelled = false;
+ }
+
+ @Override
+ public EventType getType() {
+ return EventType.TRACK_CREATE;
+ }
+
+ /**
+ * Gets the name of the track being created.
+ *
+ * @return the track name
+ */
+ @NotNull
+ public String getTrackName() {
+ return trackName;
+ }
+
+ /**
+ * Gets the created track.
+ * <p>
+ * This is only available in the POST state. Returns null in PRE state.
+ *
+ * @return the track, or null if PRE state
+ */
+ @Nullable
+ public Track getTrack() {
+ return track;
+ }
+
+ /**
+ * Gets the state of this event.
+ *
+ * @return the state
+ */
+ @NotNull
+ public State getState() {
+ return state;
+ }
+
+ @Override
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ @Override
+ public void setCancelled(boolean cancelled) {
+ if (state == State.PRE) {
+ this.cancelled = cancelled;
+ }
+ }
+
+ @Override
+ public String toString() {
+ return "TrackCreateEvent{trackName='" + trackName + "', state=" + state + ", cancelled=" + cancelled + "}";
+ }
+}

.gitignore

@@ -19,6 +19,7 @@ data/
 # Temp
 *.log
 .claude/
+.worktrees/
 CLAUDE.md
 .serena/
 .playwright-mcp/

docs/plans/2026-02-22-realtime-websocket-editor-design.md

@@ -0,0 +1,233 @@
+# Realtime WebSocket Editor Design
+
+**Date:** 2026-02-22
+**Status:** Approved
+**Scope:** HyperPerms plugin, HyperPermsWeb editor, new CF Workers relay
+
+## Problem
+
+The web editor at hyperperms.com uses a polling/REST model: the plugin POSTs session
+data to the API, the user edits in the browser, then runs `/hp apply <session>` to pull
+changes back. This is slow, manual, and one-directional.
+
+## Goal
+
+Two-way realtime sync between the browser editor and the Hytale plugin via WebSocket,
+so edits flow in both directions without manual commands.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Direction | Two-way full sync | Editor pushes to server, server pushes to editor |
+| Transport | WebSocket via Cloudflare Durable Objects | Already on CF Workers, no extra vendor, ~$5/month |
+| Relay model | API-side (CF DO) | Both plugin and browser connect as WS clients to CF |
+| Default apply mode | Batch with confirm | Safety: changes accumulate, user clicks Apply |
+| Live mode | Toggle in editor UI | Opt-in immediate apply for power users |
+| Undo | Server-side undo history (last 20 ops) | Reversible batch applies |
+| Message format | Incremental diffs (operations) | Small payloads, natural undo, efficient |
+| Conflict handling | Auto-merge non-conflicting, UI for conflicts | Server changes to different entities merge silently |
+
+## Architecture
+
+```
+Browser (Next.js) CF Durable Object Hytale Plugin (Java)
+ | (1 DO per session) |
+ |--- WS connect -------->| |
+ | |<-------- WS connect ---------------|
+ | | |
+ |-- editor.change ------->| (stores op in pending list) |
+ | | |
+ |-- batch.apply --------->| |
+ | |--- batch.apply ------------------->|
+ | | [applies to live server]
+ | |<--- apply.result ------------------|
+ |<-- apply.result --------| |
+ | | |
+ | |<--- server.change -----------------|
+ |<-- server.change -------| [in-game command ran]
+```
+
+### Session Lifecycle
+
+1. Player runs `/hp editor` in-game
+2. Plugin creates session via existing REST API (POST /api/session/create)
+3. API returns session ID + editor URL (unchanged)
+4. Plugin opens WebSocket to `wss://ws.hyperperms.com/session/<id>` as `plugin` role
+5. Player opens editor in browser, editor opens WebSocket to same URL as `editor` role
+6. DO has both connections -- relay begins
+7. On disconnect/timeout, DO hibernates (cost-efficient)
+8. Session expires after 24h (same as current TTL)
+
+### Why CF Durable Objects
+
+- CF Workers already in use (no new vendor)
+- DOs can hold persistent WebSocket connections (unlike Vercel serverless)
+- Built-in hibernation API saves costs when idle
+- Native WebSocket support with `acceptWebSocket()` API
+- Cost: ~$0.15/M requests + $0.50/GB-month -- effectively free at our volume
+- Stays within Cloudflare ecosystem
+
+## Message Protocol
+
+### Operation Types
+
+All messages are JSON with a `type` field. Operations are the atomic unit of change.
+
+```typescript
+// === Editor -> DO -> Plugin ===
+
+// Individual changes (accumulated in batch mode, applied immediately in live mode)
+{ type: "op", op: "permission.add", target: "group:admin", node: "server.kick", value: true }
+{ type: "op", op: "permission.remove", target: "group:admin", node: "server.kick" }
+{ type: "op", op: "permission.set", target: "user:<uuid>", node: "chat.color", value: false }
+{ type: "op", op: "group.create", name: "moderator", weight: 50, parents: ["default"] }
+{ type: "op", op: "group.delete", name: "moderator" }
+{ type: "op", op: "group.setMeta", target: "admin", key: "prefix", value: "&c[Admin] " }
+{ type: "op", op: "group.setWeight", target: "admin", weight: 100 }
+{ type: "op", op: "group.addParent", target: "moderator", parent: "default" }
+{ type: "op", op: "group.removeParent", target: "moderator", parent: "default" }
+{ type: "op", op: "user.addGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "user.removeGroup", target: "<uuid>", group: "admin" }
+{ type: "op", op: "track.create", name: "staff", groups: ["default", "helper", "mod", "admin"] }
+{ type: "op", op: "track.delete", name: "staff" }
+{ type: "op", op: "track.addGroup", target: "staff", group: "moderator", position: 2 }
+{ type: "op", op: "track.removeGroup", target: "staff", group: "moderator" }
+
+// Batch apply (batch mode only)
+{ type: "batch.apply" }
+
+// Mode switch
+{ type: "session.mode", mode: "live" | "batch" }
+
+// === Plugin -> DO -> Editor ===
+
+// Server-side change (in-game command, API, another plugin)
+{ type: "server.change", op: "permission.add", target: "group:admin", node: "fly.use",
+ value: true, source: "console", timestamp: 1708617600000 }
+
+// Apply result
+{ type: "apply.result", success: true, applied: 5, failed: 0,
+ errors: [], undoId: "abc123" }
+
+// Undo result
+{ type: "undo.result", success: true, undoId: "abc123", reverted: 5 }
+
+// === Control messages (both directions) ===
+
+{ type: "session.sync", data: { groups: [...], users: [...], tracks: [...] } }
+{ type: "session.ping" }
+{ type: "session.pong" }
+{ type: "session.error", code: "CONFLICT", message: "...", details: {...} }
+```
+
+### Operation Inversion (for undo)
+
+Each operation has a natural inverse stored in the undo history:
+
+| Operation | Inverse |
+|---|---|
+| `permission.add` | `permission.remove` (same target/node) |
+| `permission.remove` | `permission.add` (with original value) |
+| `group.create` | `group.delete` |
+| `group.delete` | `group.create` (with full group data snapshot) |
+| `group.setWeight` | `group.setWeight` (with previous weight) |
+| `user.addGroup` | `user.removeGroup` |
+| `user.removeGroup` | `user.addGroup` |
+| `track.addGroup` | `track.removeGroup` |
+
+## Conflict Detection
+
+### Non-conflicting (auto-merge)
+
+Server change to entity A while editor has pending changes to entity B:
+- Apply server change to editor state silently
+- Show subtle indicator that server state updated (e.g. pulse animation on the changed entity)
+
+### Conflicting
+
+Server change to entity A while editor has pending changes to entity A:
+- Mark the entity with a conflict indicator in the UI
+- Show conflict banner: "Server changed [group: admin] -- your local changes may conflict"
+- Options: "Keep mine", "Accept server", "View diff"
+- Conflict state clears when user resolves
+
+### Detection Logic
+
+Conflict = same `target` value in both a pending editor op and an incoming server change.
+Tracked per-entity, not per-field (simple and predictable).
+
+## Undo History
+
+- Stored in the Durable Object's transactional storage
+- Last 20 batch applies, each with its inverse operations
+- Each undo entry: `{ undoId, timestamp, ops: Operation[], inverseOps: Operation[] }`
+- Undo request: `{ type: "undo", undoId: "abc123" }` -> sends inverse ops to plugin
+- History clears on session expiry
+
+## Three Codebases
+
+### 1. CF Workers (new Durable Object)
+
+**Location:** New worker in existing CF project or standalone
+**Responsibilities:**
+- Accept WebSocket connections from editor and plugin
+- Route messages between them based on type
+- Store pending operations (batch mode)
+- Maintain undo history
+- Handle hibernation for cost efficiency
+- Session authentication (validate session ID against Upstash Redis)
+
+**Key files:**
+- `src/session-do.ts` -- Durable Object class with WebSocket handlers
+- `src/index.ts` -- Worker entry point, routes `/session/:id` to DO
+- `wrangler.toml` -- DO binding configuration
+
+### 2. HyperPermsWeb (Next.js editor)
+
+**Changes:**
+- New WebSocket hook: `useRealtimeSession(sessionId)` -- manages WS connection, reconnection, message handling
+- Editor state: track pending operations, conflict state
+- UI: "Live" toggle switch, Apply button (batch mode), conflict banners, undo button
+- Connection status indicator (connected/reconnecting/disconnected)
+- Replace current `PUT /api/session` save flow with WebSocket ops
+
+**Key files:**
+- `src/hooks/useRealtimeSession.ts` -- WebSocket connection + state management
+- `src/components/editor/RealtimeStatus.tsx` -- Connection indicator
+- `src/components/editor/ConflictBanner.tsx` -- Conflict resolution UI
+- `src/components/editor/LiveModeToggle.tsx` -- Live/batch toggle
+- Modifications to existing editor components to dispatch ops instead of direct state mutation
+
+### 3. HyperPerms (Java plugin)
+
+**Changes:**
+- New `WebSocketClient` class using Java 11+ `HttpClient` WebSocket API
+- Change listener: hook into existing EventBus to detect in-game permission changes
+- Apply handler: receive ops from editor, apply them through existing manager layer
+- Undo support: store pre-apply snapshots for revert
+- Auto-reconnect on connection loss
+- New config options: `webEditor.realtimeEnabled`, `webEditor.wsUrl`
+
+**Key files:**
+- `src/main/java/com/hyperperms/web/RealtimeClient.java` -- WebSocket client
+- `src/main/java/com/hyperperms/web/RealtimeMessageHandler.java` -- Message routing
+- `src/main/java/com/hyperperms/web/OperationApplier.java` -- Applies ops to live state
+- `src/main/java/com/hyperperms/web/ChangeListener.java` -- Detects in-game changes, sends to WS
+- Modifications to `WebEditorService.java` -- Start WS after session creation
+
+## Security
+
+- Session ID serves as auth token (same as current model)
+- DO validates session exists in Redis before accepting WS upgrade
+- Plugin identifies as `role: plugin` on connect, editor as `role: editor`
+- Only one plugin connection per session (reject duplicates)
+- Rate limiting on operations (prevent abuse from editor)
+- All traffic over WSS (TLS)
+
+## Migration / Backwards Compatibility
+
+- Existing REST flow continues to work (no breaking changes)
+- WebSocket is additive -- if WS connection fails, editor falls back to REST save/load
+- Plugin config: `webEditor.realtimeEnabled: true` (default true for new installs)
+- `/hp apply` command still works as fallback

src/main/java/com/hyperperms/HyperPerms.java

@@ -217,7 +217,7 @@ public void enable() {
 
  // Initialize managers with event bus
  groupManager = new GroupManagerImpl(storage, cacheInvalidator, eventBus);
- trackManager = new TrackManagerImpl(storage);
+ trackManager = new TrackManagerImpl(storage, eventBus);
  userManager = new UserManagerImpl(storage, cache, eventBus, config.getDefaultGroup());
 
  // Load data
@@ -428,6 +428,11 @@ public void disable() {
  placeholderApiIntegration.unregister();
  }
 
+ // Disconnect WebSocket before shutting down scheduler
+ if (webEditorService != null) {
+ webEditorService.disconnectWebSocket();
+ }
+
  // Stop scheduled tasks FIRST to prevent new storage executor submissions
  if (expiryTask != null) {
  expiryTask.cancel(true);

src/main/java/com/hyperperms/api/events/HyperPermsEvent.java

@@ -71,6 +71,21 @@ enum EventType {
  */
  DATA_RELOAD,
 
+ /**
+ * Fired when a track is created.
+ */
+ TRACK_CREATE,
+
+ /**
+ * Fired when a track is deleted.
+ */
+ TRACK_DELETE,
+
+ /**
+ * Fired when a track is modified.
+ */
+ TRACK_MODIFY,
+
  /**
  * Fired when a user is promoted along a track.
  */

src/main/java/com/hyperperms/api/events/TrackCreateEvent.java

@@ -0,0 +1,112 @@
+package com.hyperperms.api.events;
+
+import com.hyperperms.model.Track;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Event fired when a track is created.
+ * <p>
+ * This event can be cancelled to prevent the track from being created.
+ * The PRE state fires before creation, the POST state fires after.
+ */
+public final class TrackCreateEvent implements HyperPermsEvent, Cancellable {
+
+ /**
+ * The state of the track creation event.
+ */
+ public enum State {
+ /**
+ * Before the track is created. The event can be cancelled at this point.
+ */
+ PRE,
+
+ /**
+ * After the track has been created. Cancellation has no effect.
+ */
+ POST
+ }
+
+ private final String trackName;
+ private final Track track;
+ private final State state;
+ private boolean cancelled;
+
+ /**
+ * Creates a PRE event for track creation.
+ *
+ * @param trackName the name of the track being created
+ */
+ public TrackCreateEvent(@NotNull String trackName) {
+ this.trackName = trackName;
+ this.track = null;
+ this.state = State.PRE;
+ this.cancelled = false;
+ }
+
+ /**
+ * Creates a POST event for track creation.
+ *
+ * @param track the created track
+ */
+ public TrackCreateEvent(@NotNull Track track) {
+ this.trackName = track.getName();
+ this.track = track;
+ this.state = State.POST;
+ this.cancelled = false;
+ }
+
+ @Override
+ public EventType getType() {
+ return EventType.TRACK_CREATE;
+ }
+
+ /**
+ * Gets the name of the track being created.
+ *
+ * @return the track name
+ */
+ @NotNull
+ public String getTrackName() {
+ return trackName;
+ }
+
+ /**
+ * Gets the created track.
+ * <p>
+ * This is only available in the POST state. Returns null in PRE state.
+ *
+ * @return the track, or null if PRE state
+ */
+ @Nullable
+ public Track getTrack() {
+ return track;
+ }
+
+ /**
+ * Gets the state of this event.
+ *
+ * @return the state
+ */
+ @NotNull
+ public State getState() {
+ return state;
+ }
+
+ @Override
+ public boolean isCancelled() {
+ return cancelled;
+ }
+
+ @Override
+ public void setCancelled(boolean cancelled) {
+ if (state == State.PRE) {
+ this.cancelled = cancelled;
+ }
+ }
+
+ @Override
+ public String toString() {
+ return "TrackCreateEvent{trackName='" + trackName + "', state=" + state + ", cancelled=" + cancelled + "}";
+ }
+}