feat: asteroids

CLAUDE.md

@@ -179,12 +179,56 @@ Puppeteer settings for A4 worksheets:
 - Margins: zero (CSS handles margins)
 - `preferCSSPageSize: true`
 
+## Visual Position Editor
+
+`output/html/editor.html` — a standalone drag-and-drop editor for repositioning elements (asteroids, icons, etc.) in generated worksheets.
+
+### Usage
+
+```
+http://localhost:3300/html/editor.html?file=collecting-asteroids-1.html
+```
+
+- **Mouse drag** — move elements freely
+- **Arrow keys** — nudge 1mm (Shift+Arrow = 5mm)
+- **Copy All JSON** — export all positions to clipboard
+- **Copy Changes** — export only moved elements
+- **`window.getConfig()`** — same via console
+
+### How it works
+
+The editor `fetch()`es the worksheet HTML and injects it into its own DOM, adding drag-and-drop behavior. The worksheet HTML stays clean — no editor code touches it. The editor identifies draggable elements via CSS selector (e.g., `img[src*="pack3-asteroids"]` for asteroids).
+
+### Applying positions from editor
+
+User copies JSON from editor, gives it to Claude. Claude applies positions via a Node.js one-liner:
+
+```js
+// Pattern: regex-replace positions in order per page
+html.replace(
+  /(<div class="absolute" style="left: )-?\d+mm; top: -?\d+mm(;"><div class="relative w-\[88px\]...pack3-asteroids)/g,
+  (match, prefix, suffix) => { /* replace with new left/top from JSON */ }
+);
+```
+
+### When to use this pattern
+
+Use the visual editor approach whenever a worksheet requires **manual fine-tuning of element positions** — any time automated placement can't fully replace human judgment (e.g., avoiding overlaps with irregular ship shapes, achieving visual balance). The workflow is:
+
+1. Claude generates initial positions algorithmically
+2. User opens editor, adjusts positions visually
+3. User exports JSON → Claude applies to HTML
+4. Generate PDF
+
+This pattern can be extended to other element types by adding new CSS selectors to the editor's identification logic.
+
 ## Workflow
 
 1. User describes the math task idea (or runs `/new-doc`)
 2. Claude creates/updates a JSON config in `tasks/` with `pages[].task` descriptions
 3. Claude reads `src/templates/space-base.html` + `src/examples/space-worksheet.html` as references
 4. Claude generates HTML file in `output/html/` — creates concrete problems from `task` text, assigns unique shuffled icons, builds all pages
-5. Add a link to the new document in `output/index.html` (card with title and path)
-6. Run `pnpm pdf -- output/html/<file>.html` to create PDF
-7. Preview with `pnpm preview` at localhost:3000
+5. **(Optional)** User fine-tunes element positions via visual editor at `editor.html?file=<name>.html`, exports JSON, Claude applies
+6. Add a link to the new document in `output/index.html` (card with title and path)
+7. Run `node src/scripts/generate-pdf.mjs output/html/<file>.html` to create PDF
+8. Preview with `pnpm preview` at localhost:3300