03 — Editor Architecture

Three editors — World Builder, Region Builder, Adventure Builder — share one canvas, one asset system, one terrain system, one simulation runtime, and one world document. Each editor is a projection preset: same data, different tool palette, different camera scale, different default rules.

0. Where we actually are (refreshed 2026-09-06)

The sections below describe the intended editor design. This block records what is actually on main, verified against apps/web/src and git log (PRs #26–#120). Ground truth for milestones is superpowers/STATUS.md.

1. The three editors

A user can keep one canonical world spanning all three scales. The Adventure Builder sits "inside" a Region Builder area; the Region Builder sits inside a World Builder continent. Tiles know their parents via region.parent and world.parent references.

A single world document may contain all three editors' content; the editor switches its tool palette when the user zooms past a configurable threshold.

2. Editor shell

+---------------------------------------------------------------+
|  Top bar: world title · autosave · undo/redo · mode switch    |
+---------------------------------------------------------------+
| Tools |                                              | Right  |
| dock  |                                              | panel  |
|       |                                              |        |
| - Sel |              CANVAS                           | Layers |
| - Brus|                                              | Props  |
| - Fill|                                              | Theme  |
| - Eras|                                              | Pack   |
| - Prob|                                              | Hist   |
| - Line|                                              |        |
| - Scat|                                              |        |
+-------+----------------------------------------------+--------+
|  Bottom bar: cursor · tile · zoom · minimap · mode tabs       |
+---------------------------------------------------------------+

Panels:

• Tool dock (left): the active tool palette.
• Layers (right): toggle visibility of terrain, objects, regions, gameplay, fog.
• Properties (right): selection inspector.
• Theme (right): active theme pack, palette, lighting.
• Pack (right): installed packs, search marketplace, install.
• History (right): undo/redo list.

3. Tools

Tools are mode-aware: World Builder exposes Scatter and Biome Brush; Adventure Builder exposes Wall, Door, Pillar.

4. Canvas

4.1 Rendering

• 2D: HTML5 Canvas + WebGL2 (PixiJS or native Canvas2D depending on tile count).
  • Sub-pixel translation, integer zoom.
  • Offscreen worker renders the static layer; the foreground (selection, hover) paints on the main thread.
• 3D: Three.js + React Three Fiber (see 04-3d-world-engine.md).

The canvas is always one of these — never both. Mode tabs at the bottom switch between 2D and 3D. The 2D canvas and 3D canvas are two projections of the same world; switching is instant.

4.2 Camera

• Pan: drag with middle mouse or space + drag.
• Zoom: scroll wheel; clamped to RENDERING.minZoom..maxZoom.
• Rotate: 3D only (RMB drag or R + drag).
• Focus: F focuses the camera on the selection.
• Frame all: Shift + F fits the entire world.

Camera state is not persisted in the world document — it is editor UI state.

4.3 Coordinate display

Bottom bar shows the cursor's grid coordinate, sub-tile offset, world-space metres, and zoom level.

5. Selection & manipulation

5.1 Selection model

• Single, multi (Shift + click), rectangular marquee, lasso, by-region.
• Selection can be filtered by layer (only objects, only NPCs, etc.).

5.2 Manipulation

• Move — drag; snaps to grid unless Alt is held.
• Rotate — [ and ] keys, or R then drag.
• Scale — S then drag; clamped per-asset.
• Duplicate — Ctrl/Cmd + D.
• Delete — Delete or Backspace.

All manipulations are undoable.

6. Undo / redo

• Command-pattern undo stack, capped at 200 operations.
• Scoped per world document (not per editor session).
• Persisted to IndexedDB so a refresh keeps the stack.
• Coalesces drags into a single command; supports a coalesce window (250 ms).
• Branching history (timeline view) is a Phase 5 feature.

7. Properties panel

The right-hand Properties panel reflects the current selection:

• Tile — biome, terrain, elevation, variant, tags, gameplay overrides.
• Object — assetId, variant, rotation, scale, tags, collision, gameplay overrides.
• Region — kind, points, biome, tags.
• NPC — name, role, home, schedule, goals, dialogue refs.
• Quest — title, stages, rewards.
• Camera keyframe — t, position, lookAt, fov, easing.

Edits flow through the same command pipeline as canvas edits.

8. Theme & pack switcher

A world always has one active theme pack and one or more installed packs. The user can swap the theme and the world re-renders immediately.

Pack management:

• Installed — packs the user owns or has installed.
• Marketplace — search, preview, buy, install.
• Local — drag-and-drop a folder or .gas-pack file.

See 10-marketplace-and-packs.md.

9. Minimap & navigation

• Bottom-right minimap shows the full world.
• Click to pan; drag a box to zoom.
• Coloured markers indicate regions, NPCs, quests, camera paths.
• Fog of war dims unexplored areas in GM mode.

10. Modes (editor vs projection)

The same shell can be in Editor mode (default) or a Projection mode:

Switching modes never mutates the world document. See 05-simulation-and-game-modes.md.

11. Keyboard map

The command palette exposes every action with fuzzy search.

12. Autosave & history

• Autosave every 5 seconds of inactivity (debounced).
• Worlds are versioned in IndexedDB; the History panel lists each save.
• Ctrl/Cmd + Shift + Z opens the time-machine view (Phase 5).

13. Performance

• Tile culling — only visible tiles paint.
• Object culling — only visible objects evaluate.
• Web Workers — terrain generation, scatter, and edge auto-tiling run off the main thread.
• Asset streaming — SVG variants load on demand; GLB meshes stream LOD-aware.

For a 64×48 hex world (~3000 tiles) the editor should hold a stable 60 fps on a mid-range laptop.

14. Accessibility

• Keyboard-only editing for select / brush / fill / erase.
• High-contrast theme for low-vision users.
• Screen-reader announcements for mode switches and tool changes.
• Reduced motion mode disables camera fly-throughs and particle previews.
• Colour-vision-deficient palettes ship with every theme pack.

15. Mobile & tablet

The editor is touch-first on tablets:

• One-finger pan, two-finger pinch zoom, three-finger rotate (3D).
• Apple Pencil / S-Pen pressure maps to brush size.
• Bottom toolbar collapses to a radial menu.

The phone experience is a read-only companion — see 07-export-and-engine-targets.md §6.