!!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
# **Mirror drag-and-drop semantics** – anything the developer can drop onto PaperScape must be sendable over the queue (URLs, data URLs, staged code snippets).
# **Round-trip safety** – every action should either be reversible (undo/remove) or prompt before destructive updates.
# **Pluggable tooling** – editors expose hook points (menu buttons, status panels) so new analyzers can be injected without rewriting the UI.
# **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
# **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
# Confirm PaperScape `paperscape.js` will emit acknowledgements / optional responses when certain queue actions finish so the console can show success/failure.
# Prototype Phase 1 quickly (queue wiring   status) inside `/OpenForum/AddOn/PaperScape/Developer/page.js` and validate with a live PaperScape tab.
# Iterate through the phases above, updating this document as scope expands.
