<!--Content built using /OpenForum/Javascript/PageBuilder/default-page.builder.js 0.0.7 Gloomy November builder and renderer DefaultRenderer v1.08 2021 Covid release-->
<h3>PaperScape Developer Suite Design</h3>

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

<h3>Vision</h3>
<ul><li> Unified browser workspace for prototyping `.giraffe.js` apps, JSON scenes, and diagnostics without leaving PaperScape.</li>
<li> Tight OpenForum.IntraQ integration so scripts, assets, and commands stream straight into the active canvas.</li>
<li> Opinionated tooling (lint, schema validation, scene helpers) layered on top of the dual code editors that already exist.</li>
</ul>
<h3>Guiding Principles</h3>
<ol><li><ul><li><ul><li>Mirror drag-and-drop semantics** – anything the developer can drop onto PaperScape must be sendable over the queue (URLs, data URLs, staged code snippets).</li></ul></li></ul></li>
<li><ul><li><ul><li>Round-trip safety** – every action should either be reversible (undo/remove) or prompt before destructive updates.</li></ul></li></ul></li>
<li><ul><li><ul><li>Pluggable tooling** – editors expose hook points (menu buttons, status panels) so new analyzers can be injected without rewriting the UI.</li></ul></li></ul></li>
<li><ul><li><ul><li>Observable** – surface queue activity, PaperScape responses, and errors in a console pane for rapid feedback.</li></ul></li></ul></li>
</ol>
<h3>Target Feature Map</h3>
<table><tr><td>Area</td><td>Feature</td><td>Notes</td><td></td></tr>
<tr><td>Workspace</td><td>Split-pane JS/JSON editors</td><td>Keep StandaloneEditor but add presets (template dropdown) and quick actions.</td><td></td></tr>
<tr><td>Workspace</td><td>Embedded log/console</td><td>Mirrors queue send/receive events, PaperScape replies, lint warnings.</td><td></td></tr>
<tr><td>Queue Bridge</td><td>PaperScapeQueue helper</td><td>Expose minimal wrapper around `/OpenForum/AddOn/PaperScape/paperscape-queue.js` with UI controls (pointer presets, replace toggle).</td><td></td></tr>
<tr><td>Queue Bridge</td><td>Live status</td><td>Display connection state (queue owner, last send/receive, target tab id).</td><td></td></tr>
<tr><td>App Lifecycle</td><td>"Run in PaperScape"</td><td>Sends JS editor contents as `{action:"load-code"}` with optional `name`   `replace` flags.</td><td></td></tr>
<tr><td>App Lifecycle</td><td>"Reload selection"</td><td>Reads Items list from PaperScape via IntraQ request/response or manual entry to quickly replace a named app.</td><td></td></tr>
<tr><td>Scene Flow</td><td>"Send JSON"</td><td>Pushes JSON editor contents as `.giraffe.json` payload; prompts for append vs replace (issue a `clear` helper script when replace chosen).</td><td></td></tr>
<tr><td>Assets</td><td>URL/file dropper</td><td>Small form to push asset URLs or pick local files (uses `sendUrl`/`sendFile`).</td><td></td></tr>
<tr><td>Diagnostics</td><td>IntraQ inspector</td><td>Shows raw packets to aid automation debugging.</td><td></td></tr>
<tr><td>Documentation</td><td>Inline quick tips</td><td>Link back to <a href="/OpenForum/AddOn/PaperScape/QuickDevelopersGuide" target="newTab">/OpenForum/AddOn/PaperScape/QuickDevelopersGuide<img src='/OpenForum/Images/icons/png/link_go.png' /></a> IntraQ section and this plan.</td><td></td></tr>
</table>
<h3>High-Level Architecture</h3>
<ul><li><ul><li><ul><li>Editors Layer** – existing `StandaloneEditor` instances plus toolbar wiring for queue actions and template injection.</li></ul></li></ul></li>
<ul><li><ul><li><li>Queue Service** – singleton `PaperScapeQueue` instance with higher-level helpers (runCode, sendScene, sendAsset, sendCommand, requestItems).</li></ul></li></ul></li>
<ul><li><ul><li><li>State Store** – lightweight module (e.g., `developerSuiteState`) tracks current target item name, pointer preset, replace toggle, and queue metrics.</li></ul></li></ul></li>
<ul><li><ul><li><li>UI Components** –</li></ul></li></ul></li>
<li> Control bar above editors (pointer selector, target name, replace switch, "Send" buttons).</li>
<li> Console/log pane (append-only with filters for sent vs received).</li>
<li> Optional sidebar for assets   snippets.</li>
<ul><li><ul><li><li>Integration Hooks** – watchers on editors to auto-save drafts (localStorage) and to enable/disable buttons when JSON parses cleanly.</li></ul></li></ul></li>
</ul>
<h3>Implementation Phases</h3>
<ol><li><ul><li><ul><li>Phase 1 – Queue foundation**</li></ul></li></ul></li>
<ul><li> Load `/OpenForum/AddOn/PaperScape/paperscape-queue.js` inside page.js and expose `window.psq`.</li>
<li> Add mini status widget (queue name, target tab id, last heartbeat).</li>
<li> Wire "Run" menu item to call `psq.sendCode(editorValue, {name, replace})` instead of the legacy `iQ.send` placeholder.</li>
<li><ul><li><li>Phase 2 – UI scaffolding**</li></ul></li></ul></li>
<ul><li> Replace placeholder rows with a responsive grid: JS editor (left/top), JSON editor (right/bottom), console beneath.</li>
<li> Add control toolbar: target name input, pointer dropdown (`Center`, `Cursor`, manual XY), replace toggle, buttons for `Run`, `Send JSON`, `Send URL`, `Send File`.</li>
<li> Persist toolbar settings via `OpenForum.Storage` so they survive refreshes.</li>
<li><ul><li><li>Phase 3 – Validation and helpers**</li></ul></li></ul></li>
<ul><li> Integrate a lightweight JSON schema (optional) or at least syntax validation before enabling "Send JSON".</li>
<li> Provide starter templates (dropdown injecting sample widget skeletons / scene stubs into editors).</li>
<li> Show success/error toast when queue actions complete (optimistically log send, listen for `joined` / ack packets for confirmation).</li>
<li><ul><li><li>Phase 4 – Diagnostics & automation**</li></ul></li></ul></li>
<ul><li> Subscribe to queue events and display them in the console with timestamps.</li>
<li> Add optional command palette: e.g., "List Items" (sends `{action:"list-items"}`) and display responses.</li>
<li> Document the message catalog (actions, payloads) to encourage automation from other pages.</li>
</ul>
<h3>IntraQ Message Catalog (Draft)</h3>
<table><tr><td>Action</td><td>Direction</td><td>Payload</td><td>Effect</td><td></td></tr>
<tr><td>`load-code`</td><td>Dev → PaperScape</td><td>`{code,name,replace,pointer}`</td><td>Compiles and injects `.giraffe.js` code.</td><td></td></tr>
<tr><td>`load-file`</td><td>Dev → PaperScape</td><td>`{data,name,pointer}`</td><td>Loads `.giraffe.json` or binary asset represented as data URL.</td><td></td></tr>
<tr><td>`load-url`</td><td>Dev → PaperScape</td><td>`{url,name,pointer}`</td><td>Fetches remote asset/script.</td><td></td></tr>
<tr><td>`list-items`</td><td>Dev → PaperScape</td><td>`{requestId}`</td><td>PaperScape (future enhancement) responds with registered items to target replacements.</td><td></td></tr>
<tr><td>`ack`</td><td>PaperScape → Dev</td><td>`{action:"ack", requestId, result}`</td><td>Optional acknowledgement once loaders finish; log to console.</td><td></td></tr>
</table>
<h3>Open Questions</h3>
<ul><li> Do we need two-way RPC (PaperScape responding with JSON) immediately, or is fire-and-forget acceptable for MVP?</li>
<li> Should developer suite support file uploads via `/Uploads` behind the scenes, or rely solely on drag/queue data URLs?</li>
<li> How aggressively should we auto-save editor contents (per keystroke vs manual save)?</li>
</ul>
<h3>Next Steps</h3>
<li> Confirm PaperScape `paperscape.js` will emit acknowledgements / optional responses when certain queue actions finish so the console can show success/failure.</li>
<li> Prototype Phase 1 quickly (queue wiring   status) inside `/OpenForum/AddOn/PaperScape/Developer/page.js` and validate with a live PaperScape tab.</li>
<li> Iterate through the phases above, updating this document as scope expands.</li>
</ol>