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.
- 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)?
- 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.
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. |