### PaperScape Developer Suite Design

Living design document for evolving the `/OpenForum/AddOn/PaperScape/Developer` workspace into a queue-aware PaperScape app development suite.

### Vision

- Unified browser workspace for prototyping `.giraffe.js` apps, JSON scenes, and diagnostics without leaving PaperScape.
- Tight OpenForum.IntraQ integration so scripts, assets, and commands stream straight into the active canvas.
- Opinionated tooling (lint, schema validation, scene helpers) layered on top of the dual code editors that already exist.

### Guiding Principles

1. - - Mirror drag-and-drop semantics** – anything the developer can drop onto PaperScape must be sendable over the queue (URLs, data URLs, staged code snippets).
2. - - Round-trip safety** – every action should either be reversible (undo/remove) or prompt before destructive updates.
3. - - Pluggable tooling** – editors expose hook points (menu buttons, status panels) so new analyzers can be injected without rewriting the UI.
4. - - Observable** – surface queue activity, PaperScape responses, and errors in a console pane for rapid feedback.

### Target Feature Map

Area | Feature | Notes |
Workspace | Split-pane JS/JSON editors | Keep StandaloneEditor but add presets (template dropdown) and quick actions. |
Workspace | Embedded log/console | Mirrors queue send/receive events, PaperScape replies, lint warnings. |
Queue Bridge | PaperScapeQueue helper | Expose minimal wrapper around `/OpenForum/AddOn/PaperScape/paperscape-queue.js` with UI controls (pointer presets, replace toggle). |
Queue Bridge | Live status | Display connection state (queue owner, last send/receive, target tab id). |
App Lifecycle | "Run in PaperScape" | Sends JS editor contents as `{action:"load-code"}` with optional `name` `replace` flags. |
App Lifecycle | "Reload selection" | Reads Items list from PaperScape via IntraQ request/response or manual entry to quickly replace a named app. |
Scene Flow | "Send JSON" | Pushes JSON editor contents as `.giraffe.json` payload; prompts for append vs replace (issue a `clear` helper script when replace chosen). |
Assets | URL/file dropper | Small form to push asset URLs or pick local files (uses `sendUrl`/`sendFile`). |
Diagnostics | IntraQ inspector | Shows raw packets to aid automation debugging. |
Documentation | Inline quick tips | Link back to /OpenForum/AddOn/PaperScape/QuickDevelopersGuide IntraQ section and this plan. |

### High-Level Architecture

- - - Editors Layer** – existing `StandaloneEditor` instances plus toolbar wiring for queue actions and template injection.

- - Queue Service** – singleton `PaperScapeQueue` instance with higher-level helpers (runCode, sendScene, sendAsset, sendCommand, requestItems).

- - State Store** – lightweight module (e.g., `developerSuiteState`) tracks current target item name, pointer preset, replace toggle, and queue metrics.

- - UI Components** –

- Control bar above editors (pointer selector, target name, replace switch, "Send" buttons).
- Console/log pane (append-only with filters for sent vs received).
- Optional sidebar for assets snippets.

- - Integration Hooks** – watchers on editors to auto-save drafts (localStorage) and to enable/disable buttons when JSON parses cleanly.

### Implementation Phases

1. - - Phase 1 – Queue foundation**

- Load `/OpenForum/AddOn/PaperScape/paperscape-queue.js` inside page.js and expose `window.psq`.
- Add mini status widget (queue name, target tab id, last heartbeat).
- Wire "Run" menu item to call `psq.sendCode(editorValue, {name, replace})` instead of the legacy `iQ.send` placeholder.
- - Phase 2 – UI scaffolding**

- Replace placeholder rows with a responsive grid: JS editor (left/top), JSON editor (right/bottom), console beneath.
- Add control toolbar: target name input, pointer dropdown (`Center`, `Cursor`, manual XY), replace toggle, buttons for `Run`, `Send JSON`, `Send URL`, `Send File`.
- Persist toolbar settings via `OpenForum.Storage` so they survive refreshes.
- - Phase 3 – Validation and helpers**

- Integrate a lightweight JSON schema (optional) or at least syntax validation before enabling "Send JSON".
- Provide starter templates (dropdown injecting sample widget skeletons / scene stubs into editors).
- Show success/error toast when queue actions complete (optimistically log send, listen for `joined` / ack packets for confirmation).
- - Phase 4 – Diagnostics & automation**

- Subscribe to queue events and display them in the console with timestamps.
- Add optional command palette: e.g., "List Items" (sends `{action:"list-items"}`) and display responses.
- Document the message catalog (actions, payloads) to encourage automation from other pages.

### IntraQ Message Catalog (Draft)

Action | Direction | Payload | Effect |
`load-code` | Dev → PaperScape | `{code,name,replace,pointer}` | Compiles and injects `.giraffe.js` code. |
`load-file` | Dev → PaperScape | `{data,name,pointer}` | Loads `.giraffe.json` or binary asset represented as data URL. |
`load-url` | Dev → PaperScape | `{url,name,pointer}` | Fetches remote asset/script. |
`list-items` | Dev → PaperScape | `{requestId}` | PaperScape (future enhancement) responds with registered items to target replacements. |
`ack` | PaperScape → Dev | `{action:"ack", requestId, result}` | Optional acknowledgement once loaders finish; log to console. |

### Open Questions

- Do we need two-way RPC (PaperScape responding with JSON) immediately, or is fire-and-forget acceptable for MVP?
- Should developer suite support file uploads via `/Uploads` behind the scenes, or rely solely on drag/queue data URLs?
- How aggressively should we auto-save editor contents (per keystroke vs manual save)?

### Next Steps

2. Confirm PaperScape `paperscape.js` will emit acknowledgements / optional responses when certain queue actions finish so the console can show success/failure.
3. Prototype Phase 1 quickly (queue wiring status) inside `/OpenForum/AddOn/PaperScape/Developer/page.js` and validate with a live PaperScape tab.
4. Iterate through the phases above, updating this document as scope expands.