### PaperScape Quick Developers Guide

Fast path for building and testing custom `.giraffe.js` components inside PaperScape.

## Environment Checklist

- Ensure `/OpenForum/Giraffe/giraffe.js` is up to date; PaperScape relies on Canvas, Composite, Picture, Text, etc.
- Open two tabs: `/OpenForum/AddOn/PaperScape` for runtime testing and `/OpenForum/AddOn/PaperScape/Developer` for scripts.
- Keep a copy of `paperScape.json` in case you need to restore the default scene.

## Create a Component

1. Define your constructor: `var MyWidget = function(x,y,canvas,htmlCanvas,controller) { ... };`
2. Inside, build a container (e.g., `var container = new Composite(x,y);`) and attach shapes, text, or child composites.
3. Expose the required API: `self.getName = function() { return "My Widget"; };` and `self.getContainer = function() { return container; };`.
4. Optional extras: `self.toJson()`, `self.fromJson(json)`, `self.getForm()` (return HTML fragment string), and `self.getConfig()` ({ layer: "view" | "control" | "overlay" }).
5. Finish with `target = MyWidget;` so PaperScape knows which constructor to instantiate.

## Test Loop

1. Save the file under `/OpenForum/AddOn/PaperScape/Apps/` or an accessible page path.
2. Drag the `.giraffe.js` file onto the PaperScape canvas or call `paperScape.load("/path/to/MyWidget.giraffe.js")` from the console.
3. Use the Developer console’s Run action to execute rapid patches without reloading the page.
4. Open the Items menu entry to configure or remove the test instance.

## IntraQ Hot Reload

1. Load `/OpenForum/AddOn/PaperScape/paperscape-queue.js` (add a `<script>` tag or run `OpenForum.loadScript` from the console).
2. Instantiate `var psq = new PaperScapeQueue();`—it binds to the shared `PaperScape` queue and targets the live canvas.
3. `psq.sendUrl("/OpenForum/AddOn/PaperScape/Apps/whiteboard.giraffe.js")` or `psq.sendFile(fileInput.files0)` simulates drag/drop without leaving your editor tab.
4. `psq.sendCode(editor.getValue(), {name:"My Widget", replace:true})` instantly replaces a running app; omit `replace` (or set `false`) to spawn a parallel copy.
5. Advanced: `psq.sendMessage({action:"load-file", name:"scene.giraffe.json", data: jsonString, pointer:{x:250,y:250}})` hands you full control over the queue payload.

- Supported actions: `load-url`, `load-file`/`load-data`, and `load-code`/`replace-app`.
- `pointer` accepts either `"center"` (default) or absolute coordinates to steer the drop location.
- Queued loads append to the scene—remove items or reload the page before replaying scenes.

## Persist & Share

- Add supporting fragments (forms, HTML) alongside the script (e.g., `Apps/my-widget.html.fragment`).
- Provide sensible defaults in `toJson()`/`fromJson()` so users can save/load scenes.
- Document usage in Quick Reference if the component is user-facing.
- When exporting object-model scenes, keep filenames ending with `.omv.json` so downloads and drag/drop imports remain compatible.
- Package seeds (`.giraffe.json`) for common arrangements to accelerate reuse.

## Debugging Tips

- Use `canvas.log("message")` or `console.log` (browser dev tools) to inspect state.
- Leverage `paperScape.setAllowDrag(false)` when you need precise pointer interactions.
- Register temporary file processors with `paperScape.addFileProcessor()` to handle custom imports during development.
- Remember that dropped scripts execute immediately; wrap prototypes in `try/catch` during exploratory work.