!!!!PaperScape Collaboration & Command Bus Integration Guide

((Use this prompt when you need another AI/helper to extend PaperScape apps or build new collaborative tools that work with the shared history/undo stack.))

!!!Key Concepts
*__Command Bus__: `/OpenForum/AddOn/PaperScape/commandBus.js` exposes `PaperScapeCommandBus` so apps can register as participants (`registerCommandParticipant`), push history entries (`pushHistoryEntry`), and listen for undo/redo/clear events.
*__Delta History__: DBModelView (and future tools) should record *deltas* (`add-table`, `update-table`, `move-table`, `delete-relationship`, etc.) rather than full snapshots. Each history entry describes what changed, plus enough data to undo/redo that specific action.
*__Collaboration Queue__: `/OpenForum/AddOn/PaperScape/CollaborationQueue` (bridge defined in `collaboration-bridge.js`) mirrors command-bus pushes across clients. Messages use envelopes like:
```
{
  "channel": "paperscape",
  "origin": "agent-id",
  "type": "history-entry",
  "packet": {
    "action": "history-entry",
    "entry": { ... history payload ... }
  }
}
```
`paperscape_queue` (Claude MCP tool) pushes/pulls these envelopes for MCP agents.

!!!When Updating an Existing PaperScape Tool
1. **Register with the Command Bus**: ensure the feature’s constructor grabs `PaperScapeCommandBus`, registers a participant, and listens for inbound commands (delete/undo/redo) relevant to the tool.
2. **Capture Deltas**: whenever the tool mutates state, capture the *before* data, apply the change, then call `pushHistoryEntry` with `{ action: "...", before: ..., after: ... }`. Provide `undo`/`redo` handlers so the shared history stack works without full-scene reloads.
3. **Flag Remote Entries**: when the collaboration bridge replays a remote history entry, it sets `pendingRemoteEntryIds`. Your code should respect those flags (avoid re-pushing the same entry).
4. **Send to Collaboration Queue**: if you emit custom packets (e.g., non-history actions), use `PaperScapeCollaborationBridge.sendToServer` or `PaperScapeQueue` so other sessions see the change.

!!!Building a New Collaborative Tool
1. **Standalone Module** (recommended structure)
```
OpenForum.includeScript("/OpenForum/MessageQueue/MessageQueue.js");
OpenForum.loadScript("/OpenForum/AddOn/PaperScape/paperscape-queue.js");
OpenForum.loadScript("/OpenForum/AddOn/PaperScape/collaboration-bridge.js");

var bridge = new PaperScapeCollaborationBridge({
  serverQueue: "/OpenForum/AddOn/PaperScape/CollaborationQueue",
  channel: "paperscape",
  paperQueueOptions: { appName: "YourTool" }
});
```
2. **Register Commands**: hook into `PaperScapeCommandBus` with `commands: ["undo","redo","delete", ...]` and implement `onCommand` to respond to bus events.
3. **Emit Deltas**: call `bridge.sendToServer({ type: "history-entry", packet: ... })` or just rely on the command bus (bridge automatically republishes history). Always include `entry.id` so duplicates are ignored.
4. **Sync Selection/Pointers**: use `commandBus.capturePointer` / `captureSelection` to keep metadata accurate for remote users and UI hints.

!!!Testing Checklist
* Undo/redo works locally via floating buttons and keyboard.
* History entries show up in the browser console and via `paperscape_queue` pull.
* Remote session (or `paperscape_queue push`) reproduces the change without duplicating history.
* MCP agents can push deltas using the same envelope format.

!!!References
* `/OpenForum/AddOn/PaperScape/commandBus.js`
* `/OpenForum/AddOn/PaperScape/collaboration-bridge.js`
* `/OpenForum/AddOn/PaperScape/paperscape-queue.js`
* `/OpenForum/AddOn/ClaudeMCP/PaperScapeQueueTool.sjs`
* `/HomeLab/DBModelView/db-model-view-core.giraffe.js` (example delta implementation)

((Share this prompt with any AI/helper working in PaperScape so they align with the collaboration architecture and reuse the existing bridge/command bus.))

!!!Testing `paperscape_queue` (MCP Tool)
1. **Push Test Entry**
```
paperscape_queue.handleRequest({
  action: "push",
  packet: "{\"action\":\"history-entry\",\"entry\":{\"id\":\"dbmv.test-\"+Date.now(),\"label\":\"Add Table test\",\"payload\":{\"action\":\"add-table\",\"table\":{\"id\":\"test_table\",\"name\":\"test_table\",\"columns\":[{\"name\":\"id\",\"type\":\"uuid\",\"primaryKey\":true}],\"indexes\":[],\"constraints\":[],\"position\":{\"x\":420,\"y\":280}},\"index\":999}}}"
});
```
2. **Confirm in PaperScape**: the collaboration bridge should log `[PaperScapeCollab] History entry pushed…` and the new table appears on canvas.
3. **Pull Messages** (optional)
```
paperscape_queue.handleRequest({
  action: "pull",
  since: String(Date.now() - 60000)
});
```
4. **Undo/Redo**: use the floating buttons or `PaperScapeCommandBus.undo()` to ensure the new entry is undoable.

!!!DBModelView MCP Tool (Beta)
*__Location__: `/OpenForum/AddOn/ClaudeMCP/DBModelViewTool.sjs` (tool id `dbModelView`).
*__Purpose__: Give AI helpers CRUD-style commands without hand-crafting PaperScape queue envelopes.
*__Available actions__:
  - `read_schema` – return the active DBModelView JSON snapshot.
  - `list_tables` – print table names + column counts for situational awareness.
  - `get_table` – fetch a single table definition (pass `table_id`).
  - `status` – quick check that `/OpenForum/AddOn/PaperScape/CollaborationQueue` is reachable/active.
  - `create_table` – accept a `table_definition` JSON payload (id/name, columns, optional position/index) and push an `add-table` history entry. The PaperScape canvas updates immediately; the JSON snapshot reflects the change after a save.
  - `update_table` – provide `table_id` + partial `table_definition` JSON to modify an existing table. Adds columns, changes metadata, etc.
  - `delete_table` – supply `table_id` to remove a table via a `delete-table` history entry.
  - `move_table` – supply `table_id` + `position` JSON (`{x,y}`) to move a table on the canvas.
*__Usage example__
```
dbModelView.handleRequest({
  action: "list_tables",
  schema_path: "/HomeLab/DBModelView/db-model-view-state.dbmv.json"
});

dbModelView.handleRequest({
  action: "get_table",
  table_id: "orders"
});

dbModelView.handleRequest({
  action: "create_table",
  table_definition: JSON.stringify({
    id: "mcp_demo",
    name: "mcp_demo",
    columns: [
      { "name": "id", "type": "uuid", "primaryKey": true, "nullable": false },
      { "name": "title", "type": "text" }
    ],
    position: { "x": 1400, "y": 720 }
  })
});
```
*__Next steps__: Wire the CRUD actions into PaperScape’s command bus so MCP agents can issue `create_table` etc. and have the collaboration bridge replay the resulting history entries automatically.
