Here is the revised architectural specification incorporating your exact adjustments for your architect agent:

---

# Architectural Spec: Dual-Layer Prop Scaling System (Revised)

Status: **implemented and user verified** (2026-09-22).

This specification outlines the architecture for supporting prop scaling across two layers: permanent template scaling in the **Prop Editor** and contextual instance scaling in the **Sandbox Stage**.

---

## 1. System Architecture & Division of Responsibilities

```
  ┌─────────────────────────────────────────────────────────┐
  │                   PROP EDITOR (Phase 9)                 │
  │  • Permanent template geometry mutation                 │
  │  • Vertex & radius coordinate transformations           │
  │  • Anchor offset auto-scaling                           │
  │  • Stickman guide silhouette (Default: OFF)             │
  └────────────────────────────┬────────────────────────────┘
                               │ Saves .prop file
                               ▼
  ┌─────────────────────────────────────────────────────────┐
  │                  SANDBOX STAGE (Phase 10)               │
  │  • Contextual instance scaling via corner gizmos only   │
  │  • Locked aspect ratio (uniform scaling)                │
  │  • Physics mass decoupled from visual scale             │
  └────────────────────────────┴────────────────────────────┘

```

| Layer             | Target Entity                 | Operation Type              | Scaling Behavior                                                 | Data Persistence                                 |
| ----------------- | ----------------------------- | --------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
| **Prop Editor**   | Template Asset (`.prop`)      | Permanent geometry mutation | Bakes scale into raw vector vertices, radii, and anchor offsets. | Persists into `.prop` file.                      |
| **Sandbox Stage** | Object Instance (`PropBlock`) | Node transform scaling      | Pure gizmo scaling with **locked aspect ratio**.                 | Persists into `.scene` file (`scale: { x, y }`). |

---

## 2. Prop Editor Implementation (Template Sizing)

### A. Document Geometry Scale Tool

- **Scope:** Modifies raw geometry arrays (`points` for polygons/lines, `radius` for circles) in the shape stack.

- **Anchor Recalculation:** All registered anchor offset positions (`x`, `y`) automatically multiply by the scale factor so grip, pivot, and emitter points maintain exact relative alignment.

- **Normalize Size Action:** Adds a canvas action (📏 **Normalize Size**) alongside 🎯 **Center Prop** that computes the bounding box union of all shapes and uniformly scales the document to fit within a standard $96 \times 96\text{ px}$ canvas box.

### B. Stickman Visual Reference Silhouette

- **Overlay Guide:** Renders a semi-transparent 1:1 Stickman figure silhouette on the canvas background for scale context against full character rigs ($\approx 336 \times 940\text{ px}$).

- **Default State:** Toggleable via the UI / canvas controls and **defaults to OFF**.

- **View Aid Only:** Non-selectable, non-interactive visual guide that is excluded from `.prop` file serialization.

---

## 3. Sandbox Stage Implementation (Instance Sizing)

### A. Gizmo-Driven Scaling (No UI SpinBoxes / No Presets)

- **Corner Scale Handles:** Extends `StageGizmos` in `EDIT` mode to render corner cross handles on selected prop bounding boxes.

- **Aspect Ratio Locking:** Dragging any corner handle scales the object while strictly **locking the aspect ratio** (uniform scaling).

- **Streamlined UI:** No numeric scale SpinBoxes or preset buttons (`S`/`M`/`L`) are added to the stage UI; all scaling is performed intuitively directly on the canvas via gizmo manipulation.

### B. Mode Lifecycle & Physics Rules

- **Decoupled Mass Contract:** Scaling a prop adjusts node visual geometry (`Polygon2D`, `Line2D`) and collision bounds (`CollisionPolygon2D`, `CollisionShape2D`). RigidBody `mass` remains independent, governed strictly by the assigned Material Preset (Wood, Metal, Rubber, Cardboard).

- **Lifecycle State Handling (`PLAY` $\rightarrow$ `EDIT`):** Transitioning from `PLAY` back to `EDIT` mode restores the authored `position` and `rotation` and zeroes linear/angular velocity, but **does not reset or alter the node scale**. The authored scale set during editing is retained as-is.

---

## 4. Implementation Roadmap

1. **Phase A (Prop Editor Tooling):**

- Implement document-wide geometry and anchor scaling logic in `PropEditor`.

- Add the toggleable Stickman Reference Silhouette (**default OFF**) and "Normalize Size" canvas button.

2. **Phase B (Sandbox Gizmo Scaling):**

- Extend `StageGizmos` with corner scale handles that lock aspect ratio during drag operations.

- Ensure `StageSelection` AABB bounding boxes recalculate accurately to account for scaled instances.

3. **Phase C (Persistence & Verification):**

- Verify scene save/load serialization of scaled `PropBlock` instances.

- Confirm that `EDIT` $\rightarrow$ `PLAY` $\rightarrow$ `EDIT` mode switches restore authored position/rotation while keeping object scale intact.

## 5. Verified final Prop Editor controls

The Arrange mode top bar presents these controls in order:

1. **Transform Whole Prop**
2. **Normalize Size**
3. **Center Prop**
4. **Show Stickman Guide**

The numeric scale textbox and Apply Scale button were removed. Transform Whole
Prop previews and commits whole-document move, rotation, and uniform resize
gestures around the canonical origin. Grid Snap rounds move deltas, Ctrl snaps
rotation to 15-degree increments, editable anchors follow the geometry, and Esc
cancels an active preview. Normalize Size fits the shape-point bounds to a 96 px
maximum dimension. Transform Whole Prop and Normalize Size are hidden in Reshape
and Attach; Center Prop and Show Stickman Guide remain available in all modes.

Sandbox instance scaling remains a separate prop-only uniform corner-gizmo
operation. It retains the authored scene scale, preset-governed mass, and
PLAY-to-EDIT position/rotation restoration behavior.