# PaperScape Collaboration Queue Guide

This guide describes the shared collaboration queue envelope used by PaperScape and other OpenForum apps. The schema is defined in:

`/OpenForum/AddOn/PaperScape/collaboration-schema.json`

## Queue Location

Each user has a dedicated queue:

`/OpenForum/Users/<user>/CollaborationQueue`

PaperScape resolves the current user and connects to this queue automatically.

## Envelope Basics

Every message is wrapped in an envelope that includes routing metadata:

```json
{
  "schema": "/OpenForum/AddOn/PaperScape/collaboration-schema.json",
  "schemaVersion": "1.0",
  "channel": "collaboration",
  "origin": "PaperScapeClient-abc123",
  "timestamp": 1769000000000,
  "messageType": "command",
  "packet": {
    "command": "dependency-add",
    "payload": { "title": "MCP" },
    "selection": [{ "name": "Niks Dependency Model" }],
    "pointer": "center",
    "target": "PaperScape"
  }
}
```

`channel` and `origin` are used for filtering and loop prevention. The `packet` object is forwarded directly into IntraQ.

## PaperScape Commands

PaperScape listens for `packet.command` (preferred) or `packet.action` (legacy). Use the model-specific command names below.

### Dependency Model View

- `dependency-model-update` (payload: `{ title, storagePath, storageIsBrowser }`)
- `dependency-model-new` (payload: `{ title, storagePath, storageIsBrowser }`) (selection optional if active instance)
- `dependency-lookup` (payload: `{ title | name | query, requestId }`)
- `dependency-model-state` (payload: `{ requestId }`)
- `dependency-add`, `dependency-update`, `dependency-delete`
- `dependency-layout-grid`, `dependency-layout-radial`
- `dependency-highlight-add`, `dependency-highlight-set`, `dependency-highlight-clear`
- `dependency-relationship-add`, `dependency-relationship-update`, `dependency-relationship-delete`

### Object Model View

- `object-model-update` (payload: `{ title, storageKey }`)
- `object-model-new` (payload: `{ title, storagePath }`) (selection optional if active instance)
- `object-entity-lookup` (payload: `{ title | name | query, requestId }`)
- `object-model-state` (payload: `{ requestId }`)
- `object-entity-add`, `object-entity-update`, `object-entity-delete`
- `object-layout-grid`, `object-layout-radial`
- `object-highlight-add`, `object-highlight-set`, `object-highlight-clear`
- `object-field-add`, `object-field-update`, `object-field-delete`
- `object-method-add`, `object-method-update`, `object-method-delete`
- `object-relationship-add`, `object-relationship-update`, `object-relationship-delete`

### Database Model View

- `db-model-update` (payload: `{ title, storagePath }`)
- `db-model-new` (payload: `{ title, storagePath }`) (selection optional if only one DB model instance is active)
- `db-table-lookup` (payload: `{ title | name | query, requestId }`)
- `db-model-state` (payload: `{ requestId }`)
- `db-table-add`, `db-table-update`, `db-table-delete`
- `db-layout-grid`, `db-layout-radial`
- `db-highlight-add`, `db-highlight-set`, `db-highlight-clear`
- `db-column-add`, `db-column-update`, `db-column-delete`
- `db-relationship-add`, `db-relationship-update`, `db-relationship-delete`

## History Replication

History entries are mirrored as:

```json
{
  "messageType": "history-entry",
  "packet": {
    "action": "history-entry",
    "entry": { "...": "..." }
  }
}
```

PaperScape bridges these to the local command bus so undo/redo remains consistent.

## Lookup & State Responses

Lookup and state requests respond with `messageType: "response"` envelopes. Each response echoes the requestId when supplied.

Example lookup response:

```json
{
  "schema": "/OpenForum/AddOn/PaperScape/collaboration-schema.json",
  "schemaVersion": "1.0",
  "channel": "collaboration",
  "origin": "PaperScapeClient-abc123",
  "timestamp": 1769000000000,
  "messageType": "response",
  "packet": {
    "command": "dependency-lookup-result",
    "requestId": "req-42",
    "payload": {
      "query": "Burgess-Cross.com",
      "results": [
        { "id": "burgess-cross-com", "title": "Burgess-Cross.com" }
      ]
    }
  }
}
```

State responses use `*-model-state-result` with `payload.model` containing the full model/view payload returned by `toJson()`.

## Tips

- Use `selection` to target a model instance by name or id.
- Use `pointer: "center"` to place new items relative to the current view.
- Other apps (e.g., text editors) can reuse the same envelope with their own commands while keeping the same queue.

## Console Log Mirroring

PaperScape can mirror browser console output into the collaboration queue using `messageType: "log"`. By default, `console.log/info/warn/error/debug` are wrapped and forwarded through the collaboration bridge.

Disable with:

```js
window.PAPERSCAPE_LOG_TO_COLLAB = false;
```

## PaperScapeQueue Helpers

If you are running in-browser with `paperscape-queue.js` loaded, you can call helper methods instead of constructing raw packets:

```js
const queue = new PaperScapeQueue({ appName: "CollabClient" });
queue.addDependency({ title: "MCP" }, {
  selection: [{ name: "Niks Dependency Model" }],
  pointer: "center"
});
queue.addTable({ table: { name: "customer" } }, {
  selection: [{ name: "Hedgehog Policy Database Model" }]
});
queue.addEntity({ name: "Policy" }, {
  selection: [{ name: "Hedgehog Policy Object Model" }]
});
```
