# AGENTS.md — stickman (Godot 4.4)

## Project type
- **Godot 4.4** 2D/GUI project (Forward Plus renderer)
- No CLI build/test/lint commands; open in the Godot editor to run
- **Main scene:** `res://scenes/stickman_editor.tscn` (set as `run/main_scene` in `project.godot`)

## Project overview
Stickman Studio is an editor tool for drawing and assembling stick figures. It is a
`Control`-based GUI (not physics/animation) in its current phase. Body-part vector shapes
are authored per-panel (each panel supports **multiple shapes** with Z-ordering) and
assembled in a "Whole Stickman" preview that supports translation, rotation, and scale.

## Required addon
- **Scalable Vector Shapes 2D** (v2.27.7) at `addons/curved_lines_2d/`
  - Declared dependency for the project. The current editor UI does not instantiate it directly,
    but keep it present — it is required for the legacy `stick.tscn` rig.

## Architecture
- `scripts/stickman_editor.gd` — `extends Control`; the main controller. Owns the menu bar,
  save/load/clear flow, JSON (de)serialization, and populates the 10 body-part panels.
  Writes `FILE_VERSION "1.5"`; auto-migrates `"1.0"`–`"1.4"` files on load. Coordinates cross-panel
  selection so only one shape is selected at a time (`shape_selected` → deselect others).
  Collects per-part `{shapes[], position, rotation, scale, pivot, length, guide_offset}` for save/load.
  - **Phase 8 save export:** writes top-level `proportions` (hardcoded master-rig rest-pose
    constants 168/200/200/200/391.5 via the `PROPORTIONS` const) and per-part `pivot`/`length`
    computed from the panel's local shape bounding box (`_compute_part_pivot_length()`): `pivot` =
    bbox center, `length` = bbox width for the 4 arm parts (`X_AXIS_PARTS`) and bbox height
    otherwise. `pivot`/`length`/`proportions` are write-only metadata — never read back on load,
    recomputed on every save.
  - **Phase 9 Round 5 guide-offset export:** each part's save dict also gains `"guide_offset":
    {x, y}` = (part bbox center in preview space) − (guide joint in preview space), computed in
    `_collect_all_shape_data()` as `(pos + pivot) - _whole_preview.get_guide_joint_preview(...)` —
    a **pure master-space delta** (both points are preview-world coordinates, so panel-size terms
    cancel). The part→joint map is `const GUIDE_JOINT_FOR_PART` (head→"Neck" — the head bone's
    rig attachment origin, NOT the circle center — torso→"Hips", upper arms→Shoulders, lower
    arms→Elbows, upper legs→"Hips", lower legs→Knees). Write-only metadata like `pivot`/`length`;
    the load path (`_apply_json_data`) ignores it, so v1.0–v1.4 files load unchanged and gain the
    key on their next save.
  - **Phase 6 recent colors:** stores `_recent_colors: Array[String]` (max 8,
    most-recent-first), loads from `settings.json` (`recent_colors` key) in
    `_load_settings()`, saves on each color selection via `_save_settings()`, and
    broadcasts to all 10 panels via `_broadcast_recent_colors()`.
  - `_on_color_selected(color, part_name)`: deduplicates, inserts the hex string at the
    front, trims to 8 entries, saves settings, then broadcasts to all panels.
  - `_broadcast_recent_colors()`: pushes `_recent_colors` to every panel via
    `BodyPartPanel.set_recent_colors(_recent_colors)`.
  - **Phase 6 status bar (cursor coords):** `_process()` polls
    `get_global_mouse_position()` each frame, checks each panel via
    `is_cursor_over_drawing(global_pos)` and the preview via
    `is_cursor_over_preview(global_pos)`, converts to world space via
    `global_to_world(global_pos)`, and writes `"X: ###  Y: ###"` to `_status_cursor_coords`.
  - **Phase 6 snap status:** `_status_snap_status` displays `"SNAP: ON"` / `"SNAP: OFF"`,
    set in `_ready()` and re-synced when snap is toggled (`_on_edit_menu_id_pressed`).
  - **Phase 7 pose guide toggle:** stores `_show_guide: bool` (default `true`), persisted to
    `settings.json` under the `show_pose_guide` key (default `true`) via `_load_settings()` /
    `_save_settings()`. The View menu item (id 1) is a **dynamic, text-only** label (no
    checkmark): "Hide Pose Guide" while the guide is visible, "Show Pose Guide" while hidden,
    set via `_guide_menu_label()`. `_update_guide_menu_item()` refreshes only the item text;
    it is synced on the `about_to_popup` signal (`_on_view_menu_about_to_popup`) and again at
    the end of `_load_settings()` (so a persisted `show_pose_guide: false` shows "Show Pose
    Guide" immediately at startup). `_on_view_menu_id_pressed` (id 1) toggles the state, saves,
    and broadcasts. `_broadcast_settings()` pushes the value to the preview via
    `WholeStickmanPreview.set_show_guide(_show_guide)` (called in `_ready()` after
    `_load_settings()`).
- `scripts/body_part_panel.gd` — `class_name BodyPartPanel`, `extends PanelContainer`.
  Reusable per-part editor. Public API:
  - `set_shape_data(data: Variant)` — import shape data (Array or single Dictionary; used on Load/Clear)
  - `get_shape_data() -> Array[Dictionary]` — export array of `{shape_type, points, color, closed, vertex_flags}`
  - `clear_shape()` — reset panel, clears all shapes (does **not** emit `shape_changed`)
  - `select()` — mark the panel's topmost shape as selected (white outline highlight)
  - `deselect()` — clear selection and cancel any in-progress vertex drag
  - `signal shape_changed(shapes: Array)` — emitted when any shape is created, modified, deleted, or reordered
  - `signal shape_selected()` — emitted on left-click; the editor deselects all other panels
  - `signal color_selected(color: Color)` — emitted when the color is confirmed (OK button)
  - `set_recent_colors(colors_hex: Array)` — clears existing ColorPicker presets and populates with the given hex colors
  - `is_cursor_over_drawing(global_pos: Vector2) -> bool` — true if `global_pos` is over the drawing surface
  - `global_to_world(global_pos: Vector2) -> Vector2` — maps a global position to drawing ("world") space
  - **Phase 2 vertex editing:** left-click on a shape selects it; drag a vertex handle to
    reshape in real time; with a shape selected, right-click near an outline edge offers
    "Create Point" (inserts a vertex flagged `1` at the edge midpoint). Original vertices
    are filled circles; user-created vertices are hollow rectangles.
  - **Phase 4 multi-shape:** panels store a `shapes[]` array. Right-click context menu
    includes "Send Back" (id 7) and "Bring Forward" (id 8) for Z-ordering. "Delete" (id 5)
    removes the specific shape under the mouse. `_selected_shape_idx` tracks which shape
    is active for vertex editing.
  - **Per-panel zoom:** mouse wheel multiplies `_zoom` by 1.10, clamped to `[0.3, 3.0]`;
    drawing and input hit-testing both run in world space via `draw_set_transform`.
  - **Phase 6 touchpad:** `_gui_input` handles `InputEventMagnifyGesture` (pinch zoom)
    and `InputEventPanGesture` (2-finger drag panning), both checked before
    `InputEventMouseButton`. Pan gesture delta is multiplied by 3.0 for speed
    parity with mouse panning.
  - **Phase 6 cursor-centered zoom:** both mouse wheel and pinch zoom adjust
    `_pan_offset` so the world point under the cursor stays fixed during zoom.
  - **Selection gizmos always on top:** bounding box, rotation circle, and scale
    crosses for the selected part are drawn in a second pass after all parts,
    via `_selected_gizmo_bounds`, so they always render in front.
- `scripts/whole_stickman_preview.gd` — `class_name WholeStickmanPreview`, `extends Control`;
  the assembly preview. Owns per-part position/rotation/scale, Z-order (`_part_order`),
  selection + gizmos, grid drawing, and pan/zoom. Public API includes `set_body_parts()`,
  `set_show_guide(enabled: bool)`, `reset_view()`, `is_cursor_over_preview(global_pos)`, and
  (Phase 9 Round 5) `get_guide_joint_preview(joint_name) -> Vector2` — returns the preview-space
  position of a `GUIDE_JOINTS` entry via `_guide_to_preview()`, guarded against unknown names
  (`push_warning` + `Vector2.ZERO`).
  - **Phase 7 pose silhouette guide:** `set_show_guide()` stores `_show_guide: bool`
    (default `true`) and redraws; `_draw_silhouette_guide()` is called in `_on_preview_draw()`
    after the part loop and before the drag highlight/selection gizmos, so it renders above
    the grid **and in front of user parts** (ghosting over them), below the selection
    gizmos and drag highlight. The guide is **centered** at the default view and after
    `Reset Views`, computed at draw time from the live preview size via
    `_guide_to_preview()` = `(master_pos - GUIDE_FIGURE_CENTER) * GUIDE_SCALE +
    preview_area.size * 0.5`, so it also re-centers on window resize; it remains a
    world-space fixture that moves with pan/zoom. Joint positions are **hardcoded
    constants** derived from the `master_rig.tscn` rest pose (`GUIDE_JOINTS`: 13 anchors
    Head/Neck/Shoulders/Elbows/Wrists/Hips/Knees/Ankles;
    `GUIDE_SCALE = 1.0`, `GUIDE_FIGURE_CENTER = (0, -93.75)`, `GUIDE_HEAD_RADIUS = 100.0`).
    Color-coded: left limbs cyan-blue `Color(0.35, 0.70, 1.00)`, right limbs orange-red
    `Color(1.00, 0.50, 0.20)`, central spine/head white, with lines at alpha `0.45` and joint
    dots at alpha `0.65`. Joint dots use `GUIDE_JOINT_RADIUS / _zoom` (6 px constant screen
    size). The guide is pure drawing — **no hit-testing** is added, so it never intercepts
    part dragging/selection.
- `scripts/stk_rig_adapter.gd` — `class_name StkRigAdapter`, `extends RefCounted`; a **standalone
  runtime adapter** (Phase 8, **not referenced by the editor**, extended by Phase 9).
  `static func apply(stk_data, rig)` fits an instantiated `master_rig.tscn` to a loaded `.stk`
  dictionary, calling three private helpers in order: `_fit_bones` (re-fits the 8 limb `Bone2D`
  lengths + lower-bone origins, and zeroes the Head driver's local position so the chin sits on
  the neck joint), `_recalibrate_ik` (repositions the `IK_Targets/Left|Right_Hand` and
  `Left|Right_Leg` targets), and `_mount_shapes` (mounts `.stk` shapes onto the `Body/*` visual
  nodes — one node per shape: closed → single `Polygon2D`, open → single `Line2D` width 2). The
  `RemoteTransform2D` drivers keep their defaults (`update_rotation = true`), so mounted shapes
  follow their bones in every pose.
  - **Phase 2 (Sandbox) single-shape support:** `_mount_shapes()` reads a part's `shapes` array
    when present (v1.2+), and otherwise — when the part dict itself carries `points` — wraps the
    whole dict as a single shape (`shapes = [pd]`), so v1.0/v1.1 single-shape `.stk` files (e.g.
    `stickmen/test.stk`) mount as visible geometry instead of being cleared to nothing.
  - **Phase 9 extension:** also fits the head bone (`Skeleton2D/Torso/Head.position.y =
    -proportions.torso_length`, x preserved) and mounts the head as **full geometry** like every
    other part — it clears the `Body/Head` node's inline `@tool` circle script via
    `set_script(null)` and mounts `.stk` head shapes as `Line2D`/`Polygon2D`. Dead helpers
    `_mount_head_circle`, `_compute_shapes_bbox`, and `_first_shape_color` were removed.
  - **Phase 9 Round 2 bugfix (hanging-convention mount):** driver rotation neutralization was
    **removed** — the `RemoteTransform2D` drivers keep `update_rotation = true`, so each mounted
    part rotates to follow its bone in every pose (IK flexing included). `_mount_shapes()` no
    longer reads the file's `pivot`/`length` fields — it recomputes a per-part bounding box at
    mount time via `_compute_part_bbox()` (empty bbox → the part is skipped) and derives the
    mount transform via `_compute_mount_transform()`, which emits `{anchor, scale, theta}`:
    geometry is mounted in the rig's **hanging convention** (joint anchor at the local origin,
    far end along local `+Y`). Anchors: head and torso → bottom-center `(cx, max_y)` (chin / hip
    end at the origin); left limbs drawn horizontally → `(max_x, cy)`; right limbs drawn
    horizontally → `(min_x, cy)`; vertically drawn limbs → top-center `(cx, min_y)`. Alignment
    rotation θ maps the far end onto local `+Y`: head `0`, torso `π` (driver π cancels it at
    rest), left horizontal limbs `−π/2`, right horizontal limbs `+π/2`, vertical limbs `0`.
    Scaling is **anisotropic** — only the **auto-detected drawn long axis** (`width >= height`)
    scales to the bone length (`bone_length/extent`, guard `extent <= 0.0001` → `1.0`); the
    cross axis stays 1:1 (so horizontally-drawn legs become ~200×28, not 101-px bars).
    `_bone_length_for()` maps each part to its bone length (upper/lower arm/leg, torso).
    `_map_point()` applies `(P − J) ⋅ S` then `q.rotated(θ)`. The **head driver's** local
    position (`Skeleton2D/Torso/Head/RemoteTransform2D`) is zeroed in `_fit_bones()` so the
    mounted head's chin lands on the neck joint. `DEFAULT_LINE_WIDTH := 2.0` (was 16.0) matches
    the editor's 2 px outline. `_reset_node_transform()` still resets each `Body/*` container's
    scale to `(1, 1)` and rotation to `0` before mounting (position untouched, owned by the
    driver).
  - **Phase 9 Round 3 bugfix (part preview transform + one node per shape):** the mount
    pipeline now **composes the part's preview transform** `E(P) = C + R(rot)·S·(P − C)`
    (scale-then-rotate about the raw bbox center — the editor's exact Whole-Stickman-preview
    transform) **before** the hanging-convention mount. `_mount_shapes()` reads the per-part
    `rotation` (degrees, default `0.0`) and `scale` (`{x,y}`, default `(1,1)`) from the part
    dict and applies `E` to the raw joint end `J_raw` and far point `F_pt_raw`
    (`J' = E(J_raw)`, `F' = E(F_pt_raw) − J'`). The anchor, alignment θ, and bone-fit scale `s`
    are then computed on the **transformed geometry**: rotations near ±180°
    (`|wrapf(rot)| > 0.75π`) swap the attachment to the drawn far end (`A = F_pt'`, `V = −F'`)
    so flips are visible (e.g. the 180° torso shows its drawn neck end at the hip joint and its
    hip end at the neck); other rotations keep limbs attached along their bones (a 90° forearm
    hangs from the elbow with its content turned, exactly as assembled). The bone-fit scale
    `s = bone_length / |V|` is measured on the transformed extent so user-scaled parts are not
    double-fitted. The **head** mounts upright with `θ = 0`, `s = 1` (a bone-fit scale would
    double-scale the face), but still applies the part scale through `E` (face ≈160 px) with
    the chin at the neck joint and the flip anchor rule still applying. `_mount_shape()` mounts
    **one node per shape**: closed → single `Polygon2D` (fill only, no paired `Line2D` outline);
    open → single `Line2D` (width 2).
  - **Phase 9 Round 4 bugfix (head chin drop):** adds `const HEAD_CHIN_DROP := 28.0`, derived
    from the editor's pose guide — the head circle (radius 100) is centered at the Head joint
    `(0, −463.5)`, so its bottom is `−363.5`; the neck (Head bone origin) is at `−391.5`, so the
    chin drops 28 px below the neck. The mounted head points get a `Vector2(0.0, 28.0)`
    rig-space translation (`offset` in `_compute_mount_transform()` / `_map_point()`, applied
    **after** the part transform and the `(θ = 0, s = 1)` transform; flip-agnostic — only the
    head branch sets a non-zero `offset`). Result: the head's chin lands at world ≈ `(0, −363.5)`,
    overlapping the torso's top (which ends at `−391.5`) by 28 px — matching the silhouette
    guide in the editor.
  - **Phase 9 Round 5 guide-offset application:** `_mount_shapes()` reads each part's
    `guide_offset` (`{x, y}`, default absent) and, **only when the key is present** (old files
    keep the previous offset-0 behavior and the head falls back to the Round 4
    `HEAD_CHIN_DROP`), applies a node-frame translation
    `t = (guide_offset + (A − C)).rotated(−c_node)` where A = the mount anchor already computed
    (the transformed joint end `J'`, or the transformed far end `F_pt'` when flipped — Round 3),
    C = the raw bbox center, and `c_node` = the part's driver `RemoteTransform2D.global_rotation`
    at apply time (read via the reintroduced `DRIVER_PATHS` const; null-guarded, fallback 0.0).
    This converts the editor's master-space guide offset into a bone-relative placement so the
    harness reproduces the guide placement 1:1 (and, for the head — mapped to the guide **Neck**
    joint — subsumes the `HEAD_CHIN_DROP` fallback). `t` is applied in `_map_point()` as the
    final rig-space translation, after `E`/θ/scale/flip and independent of the flip logic.
    Re-saving a `.stk` from the editor populates the offsets.
  - **Phase 9 Round 6 bugfix (guide-driven anchor selection):** when `guide_offset` is present,
    the joint anchor in `_compute_mount_transform()` is now whichever transformed end
    (`j_prime = E(J_raw)` or `f_pt_prime = E(F_pt_raw)`) is **nearest the part's stored guide
    joint** (`center − guide_offset`): if `d_far < d_joint` (strict) the far end attaches
    (`anchor = f_pt_prime`, `v = −f_prime`), else the family end (`anchor = j_prime`, `v =
    f_prime`). This replaces the per-side family choice **and** the 180° flip heuristic for the
    `guide_offset` case, fixing the **lower left leg** (knee now at the joint, was the ankle)
    and **lower right arm** (elbow now at the joint, was the wrist), both 180° off their bones
    because the user's drawn-side conventions are inconsistent per part. The nearest-end rule
    preserves every previously-correct case and naturally reproduces the 180° flip (a flipped
    part's far end lands nearest the joint — e.g. the flipped right upper arm shoulder and the
    flipped torso neck end), plus the head chin (nearest the guide Neck). Old files **without**
    the key keep the previous family rules + flip heuristic exactly as before. `theta`, `s`, the
    Round 5 offset `t`, and the `HEAD_CHIN_DROP` fallback are unchanged — they consume
    `anchor`/`v` generically.
  Targets `master_rig.tscn` node paths; every node lookup is null-guarded (missing node →
  `push_warning` + skip, never crash). Consumed by a future runtime pipeline.
- `scripts/stickman_rig.gd` — `class_name StickmanRig`, `extends Node2D`; the **runtime owner of
  facing direction, per-joint bone bend, and `Body/*` z-order** for `master_rig.tscn` (Phase 9
  Task 4). Attached to the `Master` root node of `master_rig.tscn`. **Non-`@tool`** — node
  resolution, flag writes, and z-order reordering run only at runtime (`_ready` + setters on a
  live instance). Enums `FacingProfile { LEFT, RIGHT, FORWARD }` (values are the harness facing-menu
  ids), `BendDirection { NORMAL, INVERTED }`, and `RigState { ANIMATED, RAGDOLL, RECOVERING }`.
  Constants (moved from the harness): `SKELETON_PATH`,
  `BODY_CONTAINER_PATH`, `BEND_JOINTS` (`["LeftArm","RightArm","LeftLeg","RightLeg"]`),
  `BEND_JOINT_BONE_PATHS` (each joint → its lower `Bone2D` NodePath relative to `Skeleton2D`),
  `PROFILE_FLAGS` (per-profile `flip_bend_direction` sets), `Z_ORDER_BY_PROFILE` (per-profile
  `Body/*` draw-order tables, back-to-front). Exports: `facing_profile: FacingProfile` (default
  `FORWARD`, a preset whose setter writes the four per-joint vars, reorders `Body/*`, and
  applies a whole-rig Y-axis mirror for LEFT — `Master.scale.x = -1`; RIGHT/FORWARD `(1,1)`) and an
  `@export_group("Bend Direction")` of four `@export_enum("Normal","Inverted")` vars
  `left_arm_bend`/`right_arm_bend`/`left_leg_bend`/`right_leg_bend` (defaults
  NORMAL/INVERTED/INVERTED/NORMAL = FORWARD). Recovery exports: `rest_timeout` (2.0 s),
  `auto_recover` (true), plus recovery constants
  `STAND_POSE`/`IK_TARGET_PATHS`/`REST_LINEAR_THRESHOLD`/`REST_ANGULAR_THRESHOLD`/
  `STAND_UP_DURATION`/`STABILIZATION_DELAY`/`RAGDOLL_TARGET_SOFTNESS`.
  Signals `facing_profile_changed(profile)` /
  `bend_flag_changed(joint, flipped)`. Public API: `set_facing_profile`/`get_facing_profile`,
  `set_joint_bend_flipped`/`get_joint_bend_flipped`, `get_bend_joints()`, and
  `get_bend_joint_global_position(joint)` (unknown joint → `push_warning` + no-op/`false`/
  `Vector2.ZERO`). `_ready()` resolves `Skeleton2D`/`Body`/4 lower `Bone2D`s/4 TwoBoneIK
  modifications (matched by `joint_two_bone2d_node` NodePath, **never stack index**), enables the
  modification stack (`stack.enabled = true`), applies the current profile once, then sets
  `_nodes_ready`; a `_nodes_ready` guard makes pre-`_ready` setters store-only (robust against
  setter timing during `PackedScene.instantiate()`). Null-guards + `push_warning` prefixed
  `"StickmanRig: "` throughout; never crashes.
  - **Whole-rig Y-axis mirror (replaces `_apply_head_flip()`, 2026 design change):** Facing LEFT
    is applied as a **whole-rig Y-axis mirror** — `Master.scale.x = -1` (RIGHT/FORWARD → `(1,1)`) —
    so the head AND body mirror together and face the correct direction. The old `_apply_head_flip()`
    and the `Body/Head.scale.x` mirror are **removed** (the Head Pivot node's driver transform is
    untouched). Per-joint `flip_bend_direction` flags (`PROFILE_FLAGS`) and `Z_ORDER_BY_PROFILE` are
    **kept provisionally** (unchanged): the mirror reflects the whole skeleton + `IK_Targets` +
    mounted `Body/*` geometry, while z-order (depth) is unaffected by an X-mirror. `walk_to()`
    always plays the canonical `walk_right` clip (X-mirrored by the root for LEFT; `walk_left` is
    no longer used at runtime) and sets the facing profile explicitly. Two **head-related fixes**
    under the mirror: the master_rig.tscn head `RemoteTransform2D` (`Skeleton2D/Torso/Head/Pivot`)
    no longer sets `update_scale = false` — it pushes the **full transform** like every other `Body`
    driver, so `Body/Head.scale` stays identity under the mirrored root (the old partial-channel
    push re-canonicalized the scale and caused per-frame Y-flips/wrap-jumps). And
    `_apply_head_lookat_mirror_mode()` (called from `_apply_profile()`) **disables** the head
    `SkeletonModification2DLookAt` when facing LEFT and pins the head bone rotation to the FORWARD
    canonical aim (π); `_pin_mirrored_head_rotation()` re-asserts that pin each `_physics_process`
    frame while ANIMATED/RECOVERING so recovery's stack re-arm can't let LookAt flip the bone.
    RIGHT/FORWARD re-enable the LookAt. Consequence: interactive head-aiming while facing LEFT is
    intentionally static.
  - **Phase 10 ragdoll state system:** `StickmanRig` owns a reversible `ANIMATED ⇄ RAGDOLL`
    physics mode switch plus a `RECOVERING` stand-up state. `enum RigState { ANIMATED, RAGDOLL,
    RECOVERING }`, `var state: RigState` (default `ANIMATED`), `signal state_changed(new_state:
    int)`, and public API `set_ragdoll(enabled: bool)` / `toggle_ragdoll()` / `is_in_ragdoll() ->
    bool` / `request_recovery()` / `snap_to_standing()` (Phase 2 Sandbox: instantly destroys the
    ragdoll or cancels the recovery tween, sets the 6 IK targets directly to `STAND_POSE`, re-shows
    `Body/*`, re-enables IK, and returns to `ANIMATED` with no stand-up glide). `_physics_process()`
    → `_track_momentum(delta)` caches the rig
    root's linear/angular velocity from per-frame `global_position`/`global_rotation` deltas, then
    drives `_update_rest_detection()` (auto-recovery trigger). `_enter_ragdoll()` `stop(true)`s the
    `AnimationPlayer` (`ANIMATION_PLAYER_PATH` const, keep_state — no pose reset), builds the
    ragdoll from the CURRENT solved bone positions while the IK stack is still enabled (disabling
    it first would revert the bones to the authored rest pose, popping the figure), then hides
    `Body/*` and disables the IK stack **immediately** — an instant handoff with no crossfade (the
    ragdoll spawns at exactly the same pose, so a fade would only read as ghosting), sets `state =
    RAGDOLL` + emits. `_build_ragdoll()` creates a `Node2D`
    container `"RagdollBodyContainer"` under the rig's **parent** (world root; fallback
    `get_tree().current_scene`) and populates it from the `RAGDOLL_BODIES` table (**10**
    `RigidBody2D`: torso `CapsuleShape2D` radius 12 mass 8.0, head `CircleShape2D` radius 100 mass
    2.0, limb capsules radius 8 masses 1.0–2.0; `collision_layer`/`collision_mask` = 1, bodies
    spawn fully visible) and the `RAGDOLL_JOINTS` table (**9** `PinJoint2D`, one per
    non-root body pinned at the child bone's origin, `softness = RAGDOLL_TARGET_SOFTNESS` at
    build). Angular limits via `_apply_ragdoll_joint_limits()`: `elbow_knee` folds +CW
    `-5°..+150°`, `elbow_knee_ccw` `-150°..+5°`, `shoulder_hip` ±160°, default (neck) free. Cached
    momentum is applied to the torso body. `apply_ragdoll_velocity_boost(velocity)` applies the
    same velocity delta (mass-scaled `apply_central_impulse`) to every ragdoll body — used by the
    harness "Knock Up" button. All ragdoll nodes are spawned procedurally — `master_rig.tscn` is
    **not** modified.
  - **Phase 11 instant handoff + recovery:** `_update_rest_detection()` (only when `state ==
    RAGDOLL`)
    reads `_ragdoll_bodies["torso"]`: when its linear/angular velocity drops below
    `REST_LINEAR_THRESHOLD`/`REST_ANGULAR_THRESHOLD` it accumulates `_rest_timer`; after
    `rest_timeout` (and a `STABILIZATION_DELAY` hold) with `auto_recover` on it calls
    `_start_recovery()`. `_start_recovery()` (also `request_recovery()`, no-op unless in
    RAGDOLL) captures the 10 bodies' rig-local `{pos, rot, half}` into `_captured_pose` (`half` =
    each capsule's half-length from build-time metadata) plus a landing anchor
    (`_captured_landing_center` = the ragdoll torso's world center, `_captured_ground_y` =
    `torso.center.y + RAGDOLL_TORSO_RADIUS`), `_reanchor_root_to_landing()`s (translates the rig
    root so the standing figure's **feet** sit on the ground at the landing X — `feet =
    (_captured_landing_center.x, _captured_ground_y)`, `new_root = feet + FOOT_OFFSET` — and
    re-bases the captured rig-local positions by the root shift; the figure stands up **in place,
    on the ground**, where the ragdoll landed, since the ragdoll bodies live under a world sibling
    and the root never moved while it fell), `_destroy_ragdoll()`s,
    sets `state = RECOVERING` + emits, then `_snap_skeleton_to_pose()` — a **marker-driven** snap
    writing `IK_Targets/Torso.position`/`.rotation`, `IK_Targets/Head.position`, and the 4 limb
    markers (never the slaved `Torso` Bone2D), re-showing
    `Body/*`, then calling `_rearm_ik_stack()` — a defensive re-setup (re-sets up the
    `SkeletonModificationStack2D` when it reports `!get_is_setup()`, re-asserts `enabled = true`
    and `Skeleton2D.set_process_internal(true)`, and re-asserts the Torso marker's
    `RemoteTransform2D` update-position/rotation/scale flags) so the stack reliably resumes solving
    toward the end-effectors after a disable→enable toggle. Runtime diagnosis of the re-arm is
    gated behind `const DEBUG_RECOVERY := false` (off by default; `_recovery_dbg()` traces stack
    enabled/setup/internal + bone-following state). Snap
    geometry: the ragdoll capsules span joint origin→tip along their +X, so the **hip** is derived
    as `torso.pos − spine_dir·half` and the wrist/ankle targets as `lower_body.pos + dir·half`;
    the Torso marker rotation subtracts the Torso Bone2D's `bone_angle` (bone world angle =
    marker rotation + bone_angle — copying the body rotation directly would slam the skeleton −90°
    and lay it flat).
    `_play_stand_up()` then tweens the 6 markers **directly** from their captured values to
    `STAND_POSE` over `STAND_UP_DURATION` (2.0 s, sine ease-in-out, `_tween_markers_to()`); the baked
    `"stand_up"` animation is **not** played (a fixed first keyframe can never match an arbitrary
    ragdoll rest pose, so recovery starts from wherever the snap left the markers). On tween
    finish `_on_stand_up_finished()` re-enables IK, re-shows `Body/*`, sets `state = ANIMATED`,
    and emits. Interruptible: `set_ragdoll(true)`
    during `RECOVERING` kills the stand-up tween and rebuilds the ragdoll;
    `set_ragdoll(false)` during `RAGDOLL` routes through `_start_recovery()`; repeated
    `set_ragdoll` calls are idempotent. `is_in_ragdoll()` stays
    `state == RigState.RAGDOLL` (so `RECOVERING` reads as "Stickman").
  - **Phase 3a director functionality:** adds navigation/walking, speech, an action queue, and a
    queue-runner state machine. Enums `RunnerState { IDLE, EXECUTING }` and `ActionPhase { NONE,
    WALKING, SPEAKING, WAITING, RAGDOLLING, RECOVERING }`. Constants `FOOT_OFFSET := (0, -385)`
    (feet → root; matches `StageSpawner.STICKMAN_FOOT_OFFSET`), `NAV_AGENT_LOCAL_POS := (0, 385)`
    (`== -FOOT_OFFSET`), `ARRIVE_DISTANCE` / `NAV_PATH_DESIRED_DISTANCE` / `NAV_TARGET_DESIRED_DISTANCE`
    / `SPEECH_BUBBLE_OFFSET`. New signals `arrived`, `action_started(action, index)`,
    `action_finished(action, index)`, `queue_finished` (on completion, not stop), `queue_changed`
    (any queue mutation), `speech_finished`. Exports `walk_speed` (300.0). Public API: `walk_to(
    target, speed = -1.0)` (feet/ground destination; no-op unless `state == ANIMATED`), `is_walking()`,
    `speak(text, duration)` (lazily creates a `SpeechBubble` child at `SPEECH_BUBBLE_OFFSET`, auto-hides
    + emits `speech_finished`), the queue API `queue_action` / `clear_queue` / `get_queue` /
    `remove_action` / `insert_action` / `queue_size` (all mutations emit `queue_changed`), and the
    runner API `start_queue` / `stop_queue` / `is_queue_running`. `_ready()` builds a
    `NavigationAgent2D` child at `NAV_AGENT_LOCAL_POS` (feet, on the ground-level nav mesh;
    `avoidance_enabled = false`, `max_speed = walk_speed`, shared default nav map layer 1). A
    `_physics_process` ordering of `_track_momentum` → `_update_rest_detection` → `_update_walking`
    → `_update_speech` → `_update_runner` drives the runner state machine per `ActionPhase`
    (`walk_to` → wait for `_walk_done`; `speak` → wait for `!_speech_active`; `wait` → `_phase_timer`
    countdown; `ragdoll` → `set_ragdoll(true)` then wait `is_ragdoll_at_rest()`; `recover` →
    `request_recovery()` then wait `state == ANIMATED`). `is_ragdoll_at_rest()` is a new public
    query exposing the rest result **regardless of `auto_recover`** (the runner polls it; auto-recovery
  logic is unchanged). `_enter_ragdoll()` additionally calls `_cancel_walking()` (no stale walk/path
  state) and resets `_ragdoll_at_rest = false`. **Walk fix (2026-08-29, hybrid policy):**
  `_update_walking` defers all nav reads until `NavigationServer2D.map_get_iteration_id(...) != 0`
  (map-sync guard), forces the path query via `get_next_path_position()` **before** any empty-path /
  finished check (the read-only `get_current_navigation_path()` alone never triggers a
  repath), then branches on `is_target_reachable()`: an **on-mesh target** follows the nav path
  (`_walk_mode = "nav"`), while an **off-mesh/unreachable target** switches to **direct
  straight-line steering** toward the clicked waypoint (`_walk_mode = "direct"`, root target =
  waypoint + `FOOT_OFFSET`) — a supported case with **no** `push_warning` (the old "warn + finish
  in place" policy was replaced; the rig never stands still at a waypoint). There is **no**
  `_walk_path_grace` variable (the map-sync guard + forced path query replace it) and **no
  unreachable warning**; the debug trace now carries a `mode=nav|direct` field. Off-by-default
  diagnostics: `DEBUG_WALK` + `_walk_dbg()` (rig) and `DEBUG_STAGE` + `_stage_dbg()` (sandbox_stage).
  Walking is kinematic
  (`global_position.move_toward`); movement composes with the canonical `walk_right` in-place limb
  animation, played for every direction — X-mirrored by the rig root for LEFT (facing is set
  explicitly by `walk_to()`/`set_facing_profile()`; `walk_left` is no longer used at runtime and
  the animation `.:facing_profile` tracks are neutralized/removed).
  - **Phase 4 triggers:** the `arrived` signal gained a `target: Vector2` payload (emits
    `_walk_target_feet`) so the stage can match waypoints for `arrived_at_waypoint` rules; new
    `enqueue_reactive(actions: Array[Dictionary]) -> void` appends reactive actions to the action
    queue and, if the runner is `IDLE`, resumes at the **first newly-appended action** (no replay of
    the already-consumed queue prefix). Sequential Phase 3a queues are untouched.
- `scripts/stickman_factory.gd` — `class_name StickmanFactory`, `extends RefCounted`; a **static
  factory** and the **runtime entry point** (Phase 9, **not used by the editor**) that turns a
  `.stk` file into a live, rigged `master_rig.tscn` instance:
  - `static func load_stk(path: String) -> Dictionary` — reads a `.stk` file (`FileAccess` +
    `JSON.parse_string`); returns `{}` + `push_warning` on failure.
  - `static func spawn_from_data(stk_data: Dictionary) -> StickmanRig` — instantiates
    `res://master_rig.tscn`, calls `StkRigAdapter.apply(stk_data, rig)`, returns the rig root
    (typed as `StickmanRig` since the rig now carries the `StickmanRig` root script).
  - `static func spawn(path: String) -> StickmanRig` — `load_stk()` then `spawn_from_data()`;
    returns `null` on empty data.
- `scripts/create_animations.gd` — `@tool extends EditorScript`; a **standalone editor utility**
  (run manually with `master_rig.tscn` open, **not** auto-loaded or referenced at runtime).
  Supersedes the deleted `scripts/create_walk.gd`. `_run()` bakes `walk_left`/`walk_right`
  (same keyframes as the old script, via `_generate_walk_animation()`) and a one-shot `stand_up`
  (via `_generate_pose_animation()`, `STAND_UP_DURATION` = 2.0, `loop_mode = LOOP_NONE`) into the
  open scene's default `AnimationLibrary`. `stand_up` keys the 6 `IK_Targets/*:position` tracks
  plus a `IK_Targets/Torso:rotation` track from `POSE_DOWN` (a generic "lying on back" pose) to
  `POSE_STANDING` (matching `master_rig.tscn` defaults), with `POSE_PATHS`/`POSE_MARKERS` consts.
  The baked `stand_up` is an **authored reference only** — runtime recovery does not play it
  (StickmanRig tweens the IK targets directly from the captured ragdoll pose).
- `scripts/test_harness.gd` — **standalone staging scene** (Phase 9, **not wired into the editor**;
  run via **F6** on `res://scenes/test_harness.tscn`) for debugging bone scales, vector drawing
  offsets, and IK limits in isolation. Top UI bar: "Open .stk…" button → `FileDialog` (`*.stk`);
  quick-select buttons for `stickmen/break.stk`, `stickmen/basic.stk`, `stickmen/test.stk`; "Show
  Bones" / "Show IK Handles" checkboxes; a status label showing the loaded filename. Viewport:
  `SubViewportContainer` → `SubViewport` → world `Node2D` + enabled `Camera2D`; middle-mouse pan,
  mouse-wheel zoom, camera recenters on each spawn. Each load frees the previous rig and spawns a
  fresh one via `StickmanFactory.spawn()`. Debug overlay (a world-space `Node2D` `_draw()`): true
  bone **segments** (a joint dot at each `Bone2D` origin + a parent→child line to each `Bone2D`
  child, color-coded left cyan / right orange / central white) with leaf bones drawn out to their
  IK targets (`LeftLowerArm→Left_Hand`, `RightLowerArm→Right_Hand`, `LeftLowerLeg→Left_Leg`,
  `RightLowerLeg→Right_Leg`) so wrist/ankle joints are visible (Phase 9 Round 2; previously only
  origin→parent-origin lines were drawn). The **Head** leaf is the exception (Phase 9 Round 3):
  its IK target is a `SkeletonModification2DLookAt` aim point, not a joint, so it is **not** in
  `LEAF_BONE_IK_PATHS` and the no-target fallback draws a ~90 px segment along the bone's own
  direction (`Vector2(length, 0)` rotated by `bone_angle` then `global_rotation`) instead of a
  line to the aim point; colored markers at
  `IK_Targets/{Left_Hand,Right_Hand,Left_Leg,Right_Leg}` when "Show IK Handles" is on. Interactive
  IK: click-drag the `Marker2D` IK targets; the scene's `SkeletonModificationStack2D` TwoBoneIK
  flexes limbs live (the rig self-enables its modification stack in `_ready()`).
  - **Phase 9 Round 7 draggable Torso & Head handles:** `IK_HANDLE_PATHS` now has **6 entries**
    — the 4 limb targets plus `"Head"` (`IK_Targets/Head`, the `SkeletonModification2DLookAt` aim
    point) and `"Torso"` (`IK_Targets/Torso`, whose child `RemoteTransform2D` moves the hip bone).
    Dragging the **Torso** handle translates **bones only** (no target following) — the marker's
    `RemoteTransform2D` moves the hip bone and the whole skeleton + `Body/*` visuals follow
    rigidly, while the limb/head targets stay put (dragging the figure away from them stretches
    the limbs toward the stationary targets, per user decision). Dragging the **Head** handle
    drives the Head bone's LookAt rotation (clamped at the authored ~55° constraint);
    `Body/Head` follows. `_handle_color()` colors the head marker yellow (`HANDLE_COLOR_HEAD`)
    and the torso marker magenta (`HANDLE_COLOR_TORSO`); hands stay green, feet blue. The IK
    overlay also draws a **null-guarded semi-transparent yellow aim line** from the Head bone
    origin to the head marker (`_draw_ik_handles`, width `1.5/zoom`, alpha `0.5`) — a visual aid
    for the LookAt test.
  - **Phase 9 Task 1 skeleton IK bone switches:** adds a "Facing" `MenuButton` (leftmost control
    in the top-bar `HBox`) and per-joint bend-direction toggles for the rig's TwoBoneIK "Flip
    Bend Direction" flags. The facing profile, the per-joint bend flags, and the `Body/*` z-order
    tables now **live in the `StickmanRig` script** (Phase 9 Task 4) — the harness drives the rig
    via `_rig_script: StickmanRig` (typed root from `StickmanFactory.spawn()`; signals connected
    **before** `add_child`) and keeps `_facing_profile` (default `FORWARD`) only as a **UI mirror**
    for the `[√] ` menu prefix + respawn re-application; the rig's exported `facing_profile` is the
    authority. Menu item ids are `StickmanRig.FacingProfile.LEFT/RIGHT/FORWARD` (values used
    directly as menu item ids). State `_context_joint`, `_facing_button`/`_facing_menu`,
    `_context_menu`. The Facing popup (Left/Right/Forward) uses dynamic text-only labels with the
    current profile prefixed `[√] `, refreshed on `about_to_popup` and after selection (mirroring
    the editor's snap-menu pattern); selection calls `_rig_script.set_facing_profile(id)`. Hit-test
    for the right-click toggle iterates `_rig_script.get_bend_joints()` with positions from
    `_rig_script.get_bend_joint_global_position(joint)`. Per-joint toggle: right-click inside the
    viewport on an elbow/knee (the upper↔lower limb connector, within `JOINT_HIT_RADIUS_PX := 14.0`
    screen px converted to world by `_camera.zoom.x`, nearest joint wins) pops a one-item context
    menu labeled **"Normal Bend"** (when the rig's `get_joint_bend_flipped(joint)` is true) or
    **"Invert Bend"** (when false); selecting calls
    `_rig_script.set_joint_bend_flipped(_context_joint, not _rig_script.get_joint_bend_flipped(_context_joint))`.
    Only the 4 elbows/knees are right-click targets — shoulders/hips/wrists/ankles/head/torso are
    not. Lifecycle: `_free_current_rig()` clears `_rig_script` (and `_context_joint`);
    `_load_and_spawn()` captures the remembered profile before `add_child` (so the rig's `_ready()`
    `facing_profile_changed(FORWARD)` doesn't clobber the mirror) then re-applies
    `_rig_script.set_facing_profile(remembered_profile)` after `_resolve_rig_nodes()`. The rig
    enables its own modification stack in `_ready()`. No persistence to disk.
  - **Phase 9 Task 2 body-part z-order:** the rig's `_apply_profile()` reorders the rig's `Body/*`
    visual part nodes (tree order = draw order) from the Facing profile; `Z_ORDER_BY_PROFILE` (now
    owned by `StickmanRig`) maps each `FacingProfile` to the `Body/*` part node names in
    **back-to-front draw order** (Godot 4 `Node2D` draws siblings in tree order; all parts keep
    `z_index = 0`). FORWARD: torso → left/right upper legs → left/right lower legs → left/right
    upper arms → left/right lower arms → head (all limbs in front of the torso); LEFT: left arm
    pair then left leg pair **behind** the torso, right leg pair then right arm pair in front;
    RIGHT: mirrored. In every profile upper limbs stay behind lower limbs; far-side
    (behind-torso) arms draw behind the legs while near-side arms draw in front of the legs; the
    **head is always frontmost**. The rig's `_apply_body_z_order()` walks the profile array
    back-to-front and `move_child(part, count - 1)`s each existing child (missing parts skipped),
    which yields the profile order; unknown extra children stay at the back. Safe with the adapter:
    shapes are children of the part nodes, so moving a part moves its whole shape group. No
    persistence to disk.
  - **Phase 9 Task 3 coordinates display:** adds a "Show Coords" `CheckBox` in the top-bar
    `HBox` (after "Show IK Handles", before the status label), default ON, toggled via
    `_on_show_coords_toggled(pressed)` (sets `_show_coords: bool = true`, flips
    `_coords_panel.visible`). A code-built right-side readout (`_build_coords_panel()`, called
    from `_build_ui()` after the viewport container so it renders in front): `_coords_panel`
    (`PanelContainer`) + monospace selectable `_coords_label` (`RichTextLabel`,
    `selection_enabled` + `context_menu_enabled` + `fit_content`, autowrap off, scroll off,
    `FOCUS_CLICK`; `SystemFont`: Consolas/Menlo/DejaVu Sans Mono/Courier New via the
    `normal_font`/`normal_font_size` (18) theme overrides), anchored `PRESET_TOP_RIGHT`,
    `offset_top = 40.0`, `offset_right = -8.0`, `offset_left = -COORDS_PANEL_WIDTH` (320.0),
    `grow_vertical = GROW_DIRECTION_END` + `grow_horizontal = GROW_DIRECTION_BEGIN`
    (auto-height/width, grows left so text never runs off-screen), `mouse_filter =
    MOUSE_FILTER_IGNORE` on the panel (the label itself stays interactive for selection);
    StyleBoxFlat
    bg `Color(0,0,0,0.55)`, border `Color(1,1,1,0.12)` w1, corner radius 4, content margin 8.
    Consts `COORDS_PANEL_WIDTH := 320.0` and `COORD_BONE_PATHS` (10 Skeleton2D-relative bone
    paths: Torso, Torso/Head, both upper/lower arms, both upper/lower legs). State
    `_coord_bones: Dictionary` (bone display name → `Bone2D`, keyed by `path.get_file()`),
    `_show_coords`. `_resolve_rig_nodes()` calls `_resolve_coord_bones()` (via
    `_skeleton.get_node_or_null`, `push_warning` on missing); `_free_current_rig()` clears
    `_coord_bones` (toggle persists across respawns). `_process(delta)` early-outs when hidden
    or label null, else `_update_coords_display()` — sections "Skeleton2D" pos + rot deg,
    "Bones" pos + rot deg, "IK Targets" pos only (reusing `IK_HANDLE_PATHS`/`_ik_handles`);
    "No rig loaded" fallback; every read guarded with `is_instance_valid`; the label text is
    only reassigned when the built string changes, so an active text selection survives idle
    frames. Values are
    world-space (`global_position`/`global_rotation`), rotation in degrees via
    `_fmt_deg(rad)` (1 decimal, `°`), `_fmt_vec2(v)` for positions. No persistence to disk.
  - **Phase 9 Task 5 rig animation:** adds top-bar controls immediately after the "Facing" menu
    — an `_anim_dropdown` `OptionButton` populated per spawn from
    `AnimationPlayer.get_animation_list()` (preferring `walk_right` via `DEFAULT_ANIMATION`), a
    `_play_button` whose label swaps "Play"/"Pause"/"Resume" by `_playback_state`, a `_stop_button`
    (Stop), and a `_loop_check` `CheckBox` default ON (harness-level, persists across respawns like
    `_show_coords`). The harness resolves the rig's `AnimationPlayer` directly by node path via the
    `ANIMATION_PLAYER_PATH` const (`_resolve_anim_player()`, called at the end of
    `_resolve_rig_nodes()`) and drives it directly; the `AnimationTree` node remains an untouched
    unconfigured placeholder (out of scope, D1). Loop is implemented by writing
    `Animation.loop_mode` (`LOOP_LINEAR`/`LOOP_NONE`) on the selected animation before each play
    (`_apply_loop_mode()`); playback state is tracked by the enum
    `PlaybackState {STOPPED, PLAYING, PAUSED}` via the button handlers + the `animation_finished`
    signal (guarded by `_loop`) — no polling in `_process`. Changing the dropdown selection stops
    playback;     `_free_current_rig()` clears `_anim_player`, the dropdown, `_selected_animation`,
    and state. The animation `.:facing_profile` tracks are **neutralized/removed** — facing is now
    set explicitly via `set_facing_profile()` / `walk_to()` (which sets LEFT/RIGHT from the walk
    direction and root-mirrors for LEFT), so playing `walk_right` no longer flips the rig's profile
    through an animation track. No
    persistence to disk. The "Facing" menu and all animation controls are **hidden until an .stk is
    loaded** (`_set_rig_controls_visible(false)` at the end of `_build_ui()` and in
    `_free_current_rig()`; shown on successful spawn in `_load_and_spawn()`).
- `scripts/terrain_block.gd` — `class_name TerrainBlock`, `extends StaticBody2D`; a **reusable
  vector terrain component** (Vector Terrain System, **not used by the editor**). Builds its three
  children in code: `Polygon2D` (interior fill, `fill_color`), `Line2D` (crisp vector border,
  `outline_color`/`outline_width`, auto-closed loop by appending the first vertex to the end,
  `LINE_JOINT_ROUND` + round caps), and `CollisionPolygon2D` (`BUILD_SOLIDS` solid decomposition —
  supports concave blocks). Exported properties: `polygon_points: PackedVector2Array`,
  `fill_color`, `outline_color`, `outline_width`; a unified setter pushes vertex changes to all
  three children live (no manual rebuilds).
- `scripts/terrain_utils.gd` — `class_name TerrainUtils`, `extends RefCounted`; static utility
  (**not used by the editor**):
  - `sanitize_points(points: PackedVector2Array, grid_size: float = 16.0) -> PackedVector2Array` —
    sanitization pipeline in order: grid snap → redundancy removal via a **local
    `_simplify_polyline()`** (Godot 4.7 has **no `Geometry2D.simplify_polyline()`**; the local
    version drops consecutive duplicates, a closing duplicate when `last == first`, and collinear
    vertices) → clockwise enforcement via `Geometry2D.is_polygon_clockwise()` (reverses if false,
    guaranteeing clockwise output).
  - `spawn_block(...)` — factory that sanitizes raw input vectors (`sanitize_points`), creates a
    `TerrainBlock`, applies the cleaned points, and adds it to the target container.
- `scripts/prop_block.gd` — `class_name PropBlock`, `extends RigidBody2D`; a **reusable
  dynamic vector prop component** (Dynamic Vector Props, **not used by the editor**), `@tool`.
  Builds its children in code: `Polygon2D` (interior fill, `fill_color`), `Line2D` (crisp
  vector outline, `outline_color`/`outline_width`, auto-closed loop by appending the first
  vertex, `LINE_JOINT_ROUND` + `LINE_CAP_ROUND`), and a collision node — `CollisionPolygon2D`
  (`BUILD_SOLIDS`) in `POLYGON` mode, or `CollisionShape2D` + `CircleShape2D` (48-segment
  radial loop, `CIRCLE_SEGMENTS = 48`) in `CIRCLE` mode, toggled via `shape_type`. Exported
  properties: `shape_type` (`@export_enum("Polygon","Circle")`), `polygon_points:
  PackedVector2Array`, `radius: float`, `fill_color`, `outline_color`, `outline_width`, and
  `material_preset` (`@export_enum("None","Wood","Rubber","Cardboard","Metal")`). Presets set
  `mass` + `physics_material_override` via static `mass_for()`/`physics_material()`/`tint_for()`
  (Wood: mass 3.0, friction 0.6, bounce 0.1; Rubber: mass 0.5, friction 0.9, bounce 0.85;
  Cardboard: mass 0.4, friction 0.3, bounce 0.05; Metal: mass 8.0, friction 0.9, bounce 0.0;
  None: mass 1.0, friction 0.5, bounce 0.05) and recolor fill/outline for non-`NONE`. Unified
  live-update setters push geometry/color changes to all children (null-guarded for `@tool`
  editor safety); `_apply_shape()` enables exactly one collision node.
  - **Phase 4 collision signal:** new `signal collided(other: Node)`; `_ready()` sets
    `contact_monitor = true`, `max_contacts_reported = 8`, and connects the guarded
    `body_entered` signal → `_on_body_entered` → `collided.emit(body)`, so **prop-vs-prop**
    collisions are reported by the physics engine (the stage's geometric feet-point test covers
    stickman-vs-prop separately).
- `scripts/trigger_area.gd` — `class_name TriggerArea`, `extends Node2D`; a **placeable sensor**
  (Phase 4, **not used by the editor**). `@export size: Vector2` (default 96×96), `get_area_rect()
  -> Rect2` (centered on the node's global position), and `_draw()` (translucent green fill +
  dashed border). **No physics and no signals** — it is a pure geometric region evaluated by
  `sandbox_stage.gd`'s event engine (`_update_area_entry`) for `entered_area` rules.
- `scripts/prop_utils.gd` — `class_name PropUtils`, `extends RefCounted`; static factory
  (**not used by the editor**):
  - `create_box(size := Vector2(48,48))` / `create_ball(radius := 24.0)` /
    `create_plank(length := 160.0, thickness := 16.0)` / `create_triangle(base := 56.0, height
    := 48.0)` — primitive generators returning shape-payload dictionaries with default
    dimensions + color themes (wood/rubber/metal/cardboard).
  - `spawn_prop(container, position, shape_payload, material_preset := WOOD, initial_velocity
    := Vector2.ZERO) -> PropBlock` — instantiates a `PropBlock`, applies the payload
    (`shape_type` + geometry + colors via `_apply_shape_payload()`, sanitizing polygon points
    through `TerrainUtils.sanitize_points()`), sets `linear_velocity` after `add_child` (only
    when non-zero), and returns the spawned prop.
- `scripts/physics_test_harness.gd` — `class_name PhysicsTestHarness`, `extends Node2D`; standalone
  staging scene root (Vector Terrain System / Dynamic Vector Props, **not wired into the editor**;
  run via **F6** on `res://scenes/physics_test_harness.tscn`). Builds flat ground, angled ramps, and stepped
  `TerrainBlock` instances via `TerrainUtils`, instantiates `res://master_rig.tscn` standing on the
  flat ground, and handles camera input. A top-bar UI (`_build_ui()`, a `CanvasLayer` +
  `PanelContainer` matching `test_harness`'s style) replaces the old key bindings: **Spawn
  Crate** / **Spawn Ball** / **Spawn Plank** buttons spawn dynamic props above the angled ramp
  via `PropUtils.spawn_prop()` (`PROP_SPAWN_POSITION = (300, -300)`: Wood Crate
  (`create_box()`, `WOOD`, velocity `(60,0)`), Bouncy Ball (`create_ball()`, `RUBBER`,
  `(-80,0)`), Heavy Plank (`create_plank()`, `METAL`, `(30,-40)`). Adds a **best-effort
  `StaticBody2D` collision proxy** (`RigCollisionProxy`, `_add_rig_collision_proxy()`) since the
  rig has **no physics bodies of its own** — a 240×1000 px `RectangleShape2D` centered at `(0,-500)`
  (  `RIG_PROXY_SIZE`/`RIG_PROXY_CENTER`) matching the standing figure's world bounds, so props
  bounce/rest against it; the proxy is a code-only stand-in, not part of the rig.
  - **Phase 10 ragdoll trigger:** the harness stores the spawned rig in `_rig: StickmanRig`
    and shows a toggle-mode `Button` (`_ragdoll_toggle`) whose text flips
    **"Stickman"** ↔ **"Ragdoll"** (`_update_ragdoll_toggle()`, `set_pressed_no_signal`
    keeps the label in sync without retriggering). Toggling calls `_rig.set_ragdoll(pressed)`,
    then on entry calls `_remove_rig_collision_proxy()` (the ragdoll collides directly with the
    terrain) and on exit `_add_rig_collision_proxy()`. `_add_rig_collision_proxy()` is idempotent
    — it first `_find_rig_collision_proxy()` (a direct child named `"RigCollisionProxy"`) and
    returns early if one exists, so rapid toggling leaves no duplicate proxies.
  - **Phase 10 external forces:** a **"Knock Up"** button (`_knock_up()`) tests impulses beyond
    gravity: when the rig is in RAGDOLL mode it calls `StickmanRig.apply_ragdoll_velocity_boost(
    KNOCK_UP_VELOCITY = (0, -450))` (mass-scaled `apply_central_impulse` on every ragdoll body,
    preserving internal structure), and applies the same upward velocity delta to every dynamic
    prop (`RigidBody2D` child of `_environment`) so the whole pile flies up together.
  - **Phase 11 recovery UI:** a `Label("Rest")` + `SpinBox` (`_rest_timeout_spinbox`, min 0.1 /
    max 10.0 / step 0.1, initialized to `_rig.rest_timeout` after `_build_ui`) and a **"Recover
    Now"** button (`_recover_now()` → `_rig.request_recovery()`) are added after the "Knock Up"
    button. `_on_rest_timeout_changed(v)` writes `_rig.rest_timeout = v` (runtime-only, no
    settings.json). `_spawn_rig()` connects `_rig.state_changed` → `_on_rig_state_changed()`,
    which removes the collision proxy on `RAGDOLL`, re-adds it on `ANIMATED`/`RECOVERING`, and
    always `_update_ragdoll_toggle()` (proxy helpers are idempotent, so the toggle handler's own
    add/remove is harmless). The toggle label reads "Stickman" during `RECOVERING` (since
    `    is_in_ragdoll()` is false).
- `scripts/sandbox_stage.gd` — `class_name SandboxStage`, `extends Node2D`; the **Sandbox Stage
  Builder** root controller (Phase 2, **not wired into the editor**; run via **F6** on
  `res://scenes/sandbox_stage.tscn`). Owns the EDIT/PLAY mode state machine, placement mode,
  camera pan/zoom, deletion, status bar, and signal fan-out; instantiates `StageSpawner` /
  `StageSelection` / `StageGizmos` (via `preload` consts). `enum StageMode { EDIT, PLAY }`
  (default EDIT). EDIT freezes `RigidBody2D` props with `freeze = true` +
  `freeze_mode = RigidBody2D.FREEZE_MODE_KINEMATIC` (script-driven gizmo dragging needs
  KINEMATIC, not STATIC) and keeps `StickmanRig`s ANIMATED (`set_ragdoll(false)` runs first);
  PLAY unfreezes props and ragdolls stickmen with `auto_recover = false`. Signals
  `mode_changed(mode)`, `object_placed(node)`, `object_selected(nodes)`, `object_deselected()`,
  `object_deleted(nodes)`. Camera: middle-mouse pan, wheel zoom clamped to `@export min_zoom` /
  `max_zoom` (0.1 / 6.0); mouse→world via `_camera.get_global_mouse_position()` (no SubViewport).
  `_world_children_selectable()` returns direct `Node2D` children of `World` excluding
  `RagdollBodyContainer`. **Authored-state / restart-the-sim:** `_authored` (instance id →
  `{node, position, rotation}`) is updated at **edit time** on every place (`_place_at` →
  `_save_object_state`) and move/rotate (`transform_committed` → `_on_transform_committed`),
  and cleared on delete (`_clear_object_state`). `_enter_edit_mode()` stands stickmen, then
  freezes every prop (`freeze_mode = FREEZE_MODE_KINEMATIC` **before** `freeze = true`, so the
  body freezes directly as kinematic — never via the static layer, whose transform sync drops a
  subsequent position set), then `_restore_authored_state()` teleports via
  `global_position`/`global_rotation` + zeroed velocity. Because the freeze+teleport can take a
  physics frame or two to settle, `_restore_authored_state()` is also re-asserted over the next
  few `_physics_process` frames (`_restore_frames_left`) — so every Play session starts from and
  returns to the same authored state. **Placement ghost:** while a palette
  item is active, `set_placement_mode(id)` spawns a translucent (`modulate.a = 0.5`),
  non-colliding (`collision_layer/mask = 0`, frozen) copy of the object reparented out of
  `World` into `_ghost_holder`; `_process()` tracks it to the cursor (+ snap) via
  `_update_ghost_position()`, and `_place_at()` re-spawns it after each placement. A ghost
  **stickman** has its `Skeleton2D` modification stack disabled and its `AnimationPlayer`
  stopped so it renders as a static standing figure (its limbs don't flex/follow the cursor).
  **Grid/snap:** an optional `StageGrid` overlay (drawn behind `World`) plus `Grid`/`Snap`
  `CheckBox` toggles and a `Size` `SpinBox`, persisted to `user://sandbox_settings.json`
  (`grid_size`/`snap_to_grid`/`show_grid`); snapping rounds the placement cursor and translate
  drags via `_snap_to_grid()` / `StageGizmos.snap_size`. The grid is visible only in EDIT mode
  (`_apply_grid_settings()` sets `_grid.visible = _show_grid and current_mode == EDIT`, re-applied
  on mode change). **Touchpad:** `_input` handles `InputEventMagnifyGesture` (pinch zoom ×factor)
  and `InputEventPanGesture` (two-finger pan, `delta × 3 / zoom`) alongside the mouse wheel/middle
  pan. UI built in code (CanvasLayer +
  PanelContainer top bar): mode toggle, six palette buttons (built from the spawner registry),
  Grid/Snap/Size controls, status label. The build controls (spawn palette + Grid/Snap/Size) are
  hidden in PLAY via `_set_build_controls_visible()`, called from `_enter_edit_mode()` /
  `_enter_play_mode()` (the mode toggle and status label stay visible).
  - **Phase 3a director tool:** adds a **"Direct"** palette toggle button (mutually exclusive with
    placement) and a `PopupMenu` (`_action_popup`, items `Walk To`/`Speak`/`Wait`/`Ragdoll`/`Recover`,
    ids `ACT_WALK`…`ACT_RECOVER`) opened by clicking a stickman (`_handle_direct_click`); the popup is
    positioned at the clicked stickman's world position converted to screen (`_world_to_screen(world_pos)`)
    offset 24 px right, not at the mouse cursor (this first menu also records the session popup anchor
    for the Phase 4 rule-builder child menus); speak/wait
    `AcceptDialog`s append `speak`/`wait` actions; `Walk To` enters a pending target-capture mode whose
    next stage click appends `{"type":"walk_to","target":world_pos}` and which **Esc** cancels (Esc
    priority: pending target → exit direct mode → existing placement clears). Builds a code-built
    `NavigationRegion2D` (`_build_navigation()`, child of the stage **not** `World` so it is never
    hit-tested) carrying a procedural `NavigationPolygon` from per-`TerrainBlock` convex decomposition
    (`_rebake_navigation()`, `Geometry2D.decompose_polygon_in_convex` + fan triangulation, world-space
    via `block.transform * p`); a `_nav_dirty` flag re-bakes once per frame (`_process`) on terrain
    place / move / rotate (`transform_committed`) / delete. Instantiates a `StageDirectorVisuals`
    overlay (`_build_director_visuals()`). **Play mode change (D3):** `_enter_play_mode()` no longer
    auto-ragdolls stickmen — it now sets each rig `auto_recover = false` and calls `start_queue()`;
    `ragdoll`/`recover` are explicit queue actions; props still unfreeze. `_enter_edit_mode()`
    `stop_queue()`s then `snap_to_standing()`s stickmen and re-enables the visuals. Wires
    `node.queue_changed → _director_visuals.mark_dirty` when a stickman is placed; `object_deleted` →
    `mark_dirty()`. `_set_build_controls_visible()` also hides the Direct button in PLAY.
  - **Phase 4 triggers & event system:** adds a When→Then **rule system** — `_event_rules:
    Array[Dictionary]` of `{id, trigger, actions}` rules (trigger types: `arrived_at_waypoint`,
    `action_finished`, `speech_finished`, `entered_area`, `collided`; action types reuse the Phase
    3a set: `walk_to`/`speak`/`wait`/`ragdoll`/`recover`). Rules persist across Play/Edit mode
    toggles but are **not** saved to disk (Phase 5). A geometric **event engine** runs in PLAY
    (`_update_area_entry` tests a movable's feet/position against each `TriggerArea.get_area_rect()`;
    `_update_stickman_prop_collision` tests a stickman's feet point against prop AABBs and vice-versa),
    with **edge-triggered** dicts (already-fired events) reset on mode entry. A **rule-builder UI
    state machine** (`RuleStep` enum: `IDLE`, `SELECT_TRIGGER`, `TRIGGER_TARGET`, `SELECT_ACTION`,
    `ACTION_TARGET`, `ACTION_POSITION`, `PARAMS`) is driven from a **"⚡ When..."** item in the Direct
    action popup: trigger sub-menu popup → trigger-target click → rule-action popup → target/position
    → "Add another action / Done" popup. **Esc** has highest priority; status-bar hints + toast
    messages guide the flow. Rule **label click** → consequence-only edit (replaces the rule, same
    `id`); **✕** deletes; `_cleanup_rules_for_nodes` auto-removes rules referencing deleted objects.
    All rule-builder context popups are **session-anchored**: the first popup in a session records
    its screen position (`_popup_anchor` / `_popup_anchor_set`; the Direct first menu = right of the
    clicked stickman, the rule-label edit entry = the click position), and every child popup in the
    session — "⚡ When…" trigger sub-menu, rule-action popup, "⬅ Back to actions", "Add another
    action" — reuses that recorded position via `_set_popup_anchor(rect)` / `_popup_anchor_rect()`,
    so cycling the menus never walks down the screen at the live cursor. The anchor is cleared on
    confirm (`_finalize_rule`), cancel (`_cancel_rule_build`), or Direct-mode/flow exit
    (`_clear_director_pending`), but **not** by `_reset_rule_builder()` (the Back-to-actions path
    intentionally reuses it).
  - **Phase 3b asset-library selector integration:** the **Stickman** and **Prop** palette buttons no
    longer place directly — pressing them opens a modal **selector grid** (`_selector: AssetSelector`,
    an instantiated `scenes/asset_selector.tscn` `PopupPanel`, added to the UI `CanvasLayer` in
    `_build_ui()` with theme/font overrides applied via `AssetSelector.apply_font`), backed by a
    dim backdrop `_selector_dim` (a black `ColorRect` at `SELECTOR_DIM_ALPHA` = 0.5, `mouse_filter =
    MOUSE_FILTER_IGNORE`, on the UI `CanvasLayer` behind the selector, shown only while the selector
    is open). State
    `_selector_open`/`_selector_kind`, `_thumbnail_queue`, `_thumbnail_busy`. `_ready()` builds
    `_stickman_library`/`_thumbnail_cache` and the two thumbnail renderer `Node`s
    (`_stickman_thumb`/`_prop_thumb`, added as children so they can `await`), plus a Browse
    `_browse_dialog` `FileDialog` (`*.stk`). `_on_palette_toggled` routes `stickman`/`prop` presses
    to `_open_selector(id)` (which forces the palette button pressed, rescans entries, performs the
    **single-item skip** for a lone stickman file, and — when the selected path is absent from the
    scan — reselects the first entry); its un-press branch closes a matching open selector.
    `_on_asset_selected(entry)` writes the selection to `StageSpawner` (`selected_stickman_path` /
    `selected_prop_id`), closes the selector, and calls `set_placement_mode(kind)`;
    `_close_selector()` also clears `_thumbnail_queue` (it flips `_selector_open` off before hiding
    the popup). `_on_selector_cancelled()` closes + exits
    placement (un-presses the palette button); the selector's `popup_hide` signal is also routed to
    `_on_selector_cancelled()` (idempotency-guarded), so an outside-click close likewise un-presses
    the palette button. `_on_browse_file_selected` builds an ad-hoc entry via
    `StickmanLibrary.make_entry(path)` (toast on failure); `_on_refresh_requested` rescans +
    re-enqueues. **Lazy thumbnail drain:** `_load_or_enqueue_thumbnails` seeds the selector from
    any cached PNG and enqueues the rest; `_process` → `_drain_thumbnail_queue()` renders **one per
    frame** (awaits the renderer, `save_png`s it, hands the texture back via
    `_selector.set_thumbnail` while the selector is open). The selector re-centers on window resize
    (the root `AssetSelector` re-runs `popup_centered()` on `size_changed` while visible). **Esc
    priority** inserts the selector
    before DIRECT/placement in `_unhandled_key_input`; `_handle_world_click` / `_handle_mouse_motion`
    early-return while `_selector_open` (belt-and-suspenders over the modal popup). Selection is
    **session-only** — persists across EDIT/DIRECT/PLAY toggles, resets on scene reload, **no disk
    save** (`_save_settings` is untouched).
- `scripts/stickman_speech_bubble.gd` — `class_name SpeechBubble`, `extends Node2D`; a **world-space
  speech bubble** drawn in `_draw()` (Phase 3a, **not used by the editor**). Child of a `StickmanRig`
  at `SPEECH_BUBBLE_OFFSET` (above the head), so it follows the figure and scales with the camera.
  Consts `FONT_SIZE`/`PADDING`/`TAIL_HEIGHT`/`MAX_WIDTH`/`BG_COLOR`/`BORDER_COLOR`/`TEXT_COLOR`.
  Measures text via `ThemeDB.fallback_font.get_string_size(...)`, draws a rounded-rect background +
  a downward tail triangle centered on the rig-local origin, then `draw_string(...)`; `visible = false`
  by default, no hit-testing. Public API: `show_text(text)` (store, `visible = true`, `queue_redraw()`),
  `hide_bubble()`. Driven by `StickmanRig.speak()`; the rig owns hiding + the `speech_finished` signal.
- `scripts/stage_director_visuals.gd` — `class_name StageDirectorVisuals`, `extends Node2D`; the
  **Edit-mode director overlay** (Phase 3a, **not used by the editor**), mirroring `StageGrid`/
  `StageGizmos`. State `camera`/`world`/`enabled`/`_dirty`; public `set_enabled(value)` /
  `mark_dirty()`. `_process()` redraws on a dirty flag; `_draw()` reads each rig's queue via
  `_collect_rigs()` (direct `World` children filtered `is StickmanRig`). Per action in order:
  `walk_to` → a blue waypoint dot (`WAYPOINT_RADIUS_PX / _zoom()`) with white outline + order number at
  `action["target"]`; dashed connectors (`draw_dashed_line`, `DASH_*` / `_zoom()`) between consecutive
  dots (and from the rig's current feet position to the first dot); non-walk actions (`speak`/`wait`/
  `ragdoll`/`recover`) → a badge (speech bubble / clock / X / up-arrow glyph + order number) anchored
  at the **stickman's position at that point in the sequence** — derived by simulating the queue
  (start at rig feet + `FOOT_OFFSET`; each `walk_to` advances the anchor; non-walk anchors at the
  current position), consecutive badges stacking `(0, -28)/zoom`. All sizes divided by `_zoom()` so
  markers stay screen-constant; pure `_draw()`, no hit-testing; hidden in PLAY via `set_enabled(false)`.
  - **Phase 4 rule visualization:** `_draw()` also renders `_event_rules` (set via `set_rules()`) —
    a **dashed white connector line** from the trigger object to the target, a green **⚡ trigger
    badge**, an orange **→ action badge**, a dark label with `rule_summary()` text, and a **✕ delete
    icon** (the label + icon are hit-testable via `hit_test_rule()`, `Vector2.INF` sentinel from
    `hit_test_waypoint()`); click-label → consequence-only edit, click-✕ → delete.
- `scripts/stage_spawner.gd` — `class_name StageSpawner`, `extends RefCounted`; registry-driven
  spawner (Phase 2). A `_registry: Array[Dictionary]` maps ids to terrain/prop/stickman templates;
  adding a type = appending an entry (no hard-coded id `match`). Reuses `TerrainUtils.spawn_block`,
  `PropUtils.spawn_prop`, `StickmanFactory.spawn_from_data` via `preload` consts. Terrain entries
  store origin-relative point templates (ground/ramp/step); `_spawn_terrain` centers the template
  bbox on its local origin then sets `block.position` to the cursor, so `global_rotation` =
  "rotate about center". Also exposes a `static get_world_aabb(node)` helper (for a stickman it
  unions the mounted `Body/*` shape geometry via a recursive `_collect_visual_points()` so the box
  is centered head-to-feet).
  - **Phase 4 area palette entry:** a new `"area"` registry entry (label "Area") → `_spawn_area()`
    instantiates a `TriggerArea`; `get_world_aabb()` gains a **duck-typed** `get_area_rect` AABB
    branch (if the node responds to `get_area_rect()`, use its `Rect2` as the world bounds).
  - **Phase 3b asset library (selected-asset spawner):** the registry entries are now
    `ground/ramp/step` (terrain) + `prop` + `stickman` + `area` — the separate `crate`/`ball`
    entries were **removed** and a single `"prop"` entry (label "Prop", kind `"prop"`) added, so
    `get_spawnable_ids()` == `["ground","ramp","step","prop","stickman","area"]`. Session state:
    `selected_stickman_path` (default `DEFAULT_STICKMAN_PATH` = `res://stickmen/test.stk`) and
    `selected_prop_id` (default `"crate"`), read/written by the sandbox selector (Phase 3b) — they
    are **session-only** (no disk save). `_stickman_cache: Dictionary` (path → parsed data) seeds
    the default path in `_init` and lazily loads+parses any newly selected path on first spawn.
    `_spawn_stickman` spawns from the **selected** path (applies `STICKMAN_FOOT_OFFSET (0, -385)`
    so feet land at the cursor); `_spawn_prop` looks the **selected** prop id up via
    `PropLibrary.get_entry(id)` and spawns its payload (`PropUtils.spawn_prop`) + material preset.
    New getters `get_selected_stickman_path()` / `get_selected_prop_id()` (status + tests).
- `scripts/stickman_library.gd` — `class_name StickmanLibrary`, `extends RefCounted` (Phase 3b,
  **not used by the editor**). Scans `res://stickmen/*.stk` into entry models for the asset
  selector. `const STICKMEN_DIR := "res://stickmen"`; `var entries: Array[Dictionary]`. Public API:
  `scan(dir_path: String = STICKMEN_DIR) -> Array[Dictionary]` (via `DirAccess` + per-file
  `StickmanFactory.load_stk`; a corrupt or missing-`body_parts` file is **skipped** with a
  `push_warning` — never `{}`-as-entry; the display `name` = `stickman_name` (stripped) if
  non-empty else the filename basename; results sorted by name, then path, cached on `self` and
  returned), `get_entries() -> Array[Dictionary]` (returns the last scan, does **not** rescan),
  `find_by_path(path) -> Dictionary` (`{}` if absent), and `make_entry(path) -> Dictionary`
  (ad-hoc single-file entry for **Browse**: `load_stk` + name fallback; `{}` on load failure or
  missing `body_parts`). Entry shape `{ "path", "name", "data" }`; thumbnails are **not** embedded
  in entries — resolved via `ThumbnailCache` at display time by the selector.
- `scripts/prop_library.gd` — `class_name PropLibrary`, `extends RefCounted` (Phase 3b, **not used
  by the editor**). A **static** registry of the 4 built-in prop templates for the asset selector.
  `static var _templates: Array[Dictionary]` (lazily built on first access — `PropUtils.create_*()`
  are `static func` and cannot run in a `const`). Public API: `static get_entries()` (builds once,
  returns the 4 templates), `static get_ids()`, `static get_entry(id) -> Dictionary` (`{}` if
  unknown), `static get_default_id() -> String` (`"crate"`). Template dicts carry `{id, name,
  material_preset, material_label, payload}` — Crate/Wood (`create_box()` + `WOOD`), Ball/Rubber
  (`create_ball()` + `RUBBER`), Plank/Metal (`create_plank()` + `METAL`), Triangle/Cardboard
  (`create_triangle()` + `CARDBOARD`) — generator color themes already match the presets.
- `scripts/thumbnails/thumbnail_cache.gd` — `class_name ThumbnailCache`, `extends RefCounted`
  (Phase 3b, **not used by the editor**). Disk PNG cache under `user://thumbnails/`. Consts
  `STICKMEN_DIR := "user://thumbnails/stickmen"`, `PROP_DIR := "user://thumbnails/props"`,
  `PROP_VERSION := 1`. Public API: `stickman_key(path)` → `"<basename>_<FileAccess.get_modified_time(path)>"`
  (an mtime change yields a new key → missing PNG → regenerate); `stickman_png(key)` /
  `prop_png(id)` (`"<id>_v<PROP_VERSION>.png"` — bump `PROP_VERSION` to invalidate all prop
  thumbnails); `load_png(png_path) -> Texture2D` (`Image.load_from_file` + `ImageTexture`, `null`
  if missing/unloadable); `save_png(tex, png_path) -> Error` (creates the parent dir); `ensure_dir`;
  `clean_stale_stickmen(valid_keys)` (deletes `basename_*` PNGs not in the valid key set).
- `scripts/thumbnails/stickman_thumbnail.gd` — `class_name StickmanThumbnail`, `extends Node`
  (Phase 3b, **not used by the editor**). Renders a parsed `.stk` into a `Texture2D` for the asset
  selector by spawning the **real rig**. `const SIZE := Vector2i(200, 200)`. `_ready()` builds one
  persistent offscreen `SubViewport` (`transparent_bg`, `render_target_update_mode = UPDATE_ALWAYS`)
  with an enabled in-viewport `Camera2D` (`make_current()`). `render(stk_data) -> Texture2D`:
  frees prior children, `StickmanFactory.spawn_from_data(stk_data)`s the rig into the viewport at
  `Vector2.ZERO`, frames it via `StageSpawner.get_world_aabb(rig)` (a degenerate/no-area bbox falls
  back to a fixed `(120×500)` rect), `_frame_camera` fits it with a 12 px margin, `await`s
  `RenderingServer.frame_post_draw` **twice** (standard offscreen capture recipe), grabs the viewport
  texture, frees the rig, and returns an `ImageTexture` — or `null` (a placeholder) when the capture
  is blank/empty (the **headless degrade**; pixel rendering is manual/F6 verification only). Output is
  identical to the rig actually placed on stage, not a re-implementation of the editor preview.
- `scripts/thumbnails/prop_thumbnail.gd` — `class_name PropThumbnail`, `extends Node` (Phase 3b,
  **not used by the editor**). Renders a prop template into a `Texture2D`. `const SIZE :=
  Vector2i(200, 200)`. `_ready()` builds the same offscreen `SubViewport` + `Camera2D` pattern as
  `StickmanThumbnail`. `render(payload, material_preset) -> Texture2D` mirrors `PropBlock`'s
  geometry into a plain `Node2D` with a `Polygon2D` (fill) + `Line2D` (closed loop, round
  joints/caps) — **not** a `RigidBody2D`, so nothing falls under gravity inside the viewport;
  circle payloads are re-expanded via `PropBlock.CIRCLE_SEGMENTS`; non-`NONE` presets tint fill via
  `PropBlock.tint_for` and darken the outline; then frames + double-`frame_post_draw` captures and
  returns an `ImageTexture` or `null` (blank → placeholder).
- `scripts/asset_selector.gd` — `class_name AssetSelector`, `extends PopupPanel` (Phase 3b, **not
  used by the editor**); root script of `scenes/asset_selector.tscn`. A **grid popup controller**.
  Signals `item_selected(entry)`, `cancelled()`, `browse_requested()`, `refresh_requested()`.
  `const COLUMNS := 4`, `ROWS := 3`, `PAGE_SIZE := 12`, `CELL_MIN_SIZE`, `THUMB_SIZE`. `var kind`
  (`"stickman"` | `"prop"`). Public API: `open(kind, entries)` (sets
  the title "Choose Your Stickman"/"Choose a Prop", shows **Browse…**/**Refresh** only for
  stickmen, then `popup_centered()`), `set_entries(entries)` (used by Refresh — resets page +
  thumbnails), `set_thumbnail(entry, tex)` (lazy handoff from the stage's drain), `close()`, and
  `apply_font(ui_font, emoji_font)` (walks the authored controls). `_ready()` sets `exclusive =
  true` and wires the footer buttons; `_unhandled_input` maps `KEY_ESCAPE` → `cancelled.emit()`
  (the Window's built-in Esc close is not relied on). Re-centers on window resize: the root's
  `size_changed` signal re-runs `popup_centered()` while the popup is visible. Cell build:
  `_rebuild()` frees the `%GridContainer` children, toggles the empty-state `%EmptyLabel`,
  shows/hides Prev/Next/page label by page count, and slices the current page via the
  **static pure** `page_bounds(total, page, page_size) -> Dictionary {start, end, total,
  page_count}` helper. `_build_cell(entry)` returns a `Button` with a `TextureRect`
  (cached/placeholder texture) + a name `Label` + (prop only) a material-badge `Label`; cells emit
  `item_selected`. No cell is pre-highlighted on open (the previous selection highlight styling
  was removed). The `.tscn` is a **minimal shell**
  (title bar, empty grid, footer as authored unique-name nodes `%TitleLabel`/`%GridContainer`/
  `%EmptyLabel`/`%PageLabel`/`%PrevButton`/`%NextButton`/`%BrowseButton`/`%RefreshButton`/
  `%CloseButton`); all dynamic per-cell content is built in code at runtime because the entry set is
  dynamic.
- `scripts/stage_selection.gd` — `class_name StageSelection`, `extends RefCounted`; hover/click/
  box selection via geometric world-space AABB hit-testing (Phase 2). `static get_world_aabb`
  unions a `Polygon2D` child's world points (terrain/props) or, for a stickman rig, recursively
  unions its mounted `Body/*` `Line2D`/`Polygon2D` geometry (`_collect_visual_points()`), so the
  bounding box is centered on the actual figure head-to-feet (not a fixed rect).
  `_frontmost_at` = highest `World` child index wins,
  smallest area breaks ties. `_is_selectable` excludes the `RagdollBodyContainer` subtree. Signals
  `hover_changed(node)` / `selection_changed(nodes)`; public API `get_selected`/`get_primary`/
  `clear_selection`/`select_only`/`add_to_selection`/`toggle_selection`/`is_selected`/`hit_test`/
  `update_hover`/`box_select`. (Phase 4) `get_world_aabb` also handles `TriggerArea` objects via
  the same **duck-typed** `get_area_rect` AABB branch, so trigger areas are selectable/hit-testable.
- `scripts/stage_gizmos.gd` — `class_name StageGizmos`, `extends Node2D`; hover highlight +
  selection outlines + a rotate ring (Phase 2). **No translate handle** — objects are dragged
  directly by the root; `set_targets(nodes: Array[Node2D])` holds the current multi-selection,
  and `begin_translate_drag(node, world_pos)` starts a TRANSLATE drag that moves **all** selected
  nodes together (`drag_to` drives `global_position` with optional grid snap via `snap_size`,
  snapping the drag anchor and applying the same delta to the rest). The **rotate ring** is drawn
  and hit-tested only when exactly one node is selected (`hit_test` → `Handle.ROTATE`).
  The rotate drag is **absolute-from-start** — `drag_to()` sets `global_rotation` to
  `_rotate_start_rotation + (current − start angle)`, with holding **Ctrl** snapping to
  15° increments via `snappedf(new_rotation, deg_to_rad(15.0))`.
  `_draw()` draws a selection outline for **every** selected node. Pure `_draw()` +
  distance-based hit-testing (no `Area2D`); `enum Handle { NONE, TRANSLATE, ROTATE }`.
  `transform_committed(nodes: Array[Node2D])` emitted on drag end. `set_enabled(false)` hides +
  disables in PLAY. Also draws the box-select marquee via `set_box_rect(rect)`.
- `scripts/stage_grid.gd` — `class_name StageGrid`, `extends Node2D`; the optional world-space
  grid overlay (Phase 2). Pure `_draw()`: grid lines pan/zoom with the camera (`camera.get_screen_center_position()`
  + viewport extent / zoom), with a heavier **major line every 5 cells**; `grid_size` / `enabled`
  are set by `SandboxStage`. Added as the first child of the stage root so it renders behind
  `World`; no hit-testing.
- Scenes:
  - `scenes/stickman_editor.tscn` — main editor layout; unique-name nodes (`%Prefix`) used
    for typed `@onready` access: `%MenuBar`, `%StickmanNameEdit`, `%LeftColumn`,
    `%CenterColumn`, `%WholeStickmanPreview`, `%SaveDialog`, `%LoadDialog`,
    `%ClearConfirmDialog`, `%ErrorDialog`, `%StatusBar`, `%CursorCoords`, `%SnapStatus`.
    - **Phase 6 status bar:** `StatusBar` is an `HBoxContainer` bottom-anchored at 28 px
      height containing `CursorCoords` (left) and `SnapStatus` (right); `MainLayout`
      `offset_bottom` is `-28.0` to leave room for it.
  - `scenes/body_part_panel.tscn` — instantiated 10× at runtime (5 per column). Each panel
    sets `size_flags_vertical = SIZE_EXPAND_FILL` so the panels expand to fill the column
    height in their parent VBoxContainer.
  - `scenes/test_harness.tscn` — **standalone staging scene** (Phase 9, not wired into the
    editor; run via **F6**). Backed by `scripts/test_harness.gd`. Top UI bar with file open /
    quick-select, "Show Bones" / "Show IK Handles" / "Show Coords" toggles, and a
    loaded-filename status label;
    `SubViewport` world with an enabled `Camera2D` (middle-mouse pan, wheel zoom, recenter on
    spawn); interactive limb IK via `SkeletonModificationStack2D` TwoBoneIK.
  - `scenes/physics_test_harness.tscn` — **standalone staging scene** (Vector Terrain System /
    Dynamic Vector Props, not wired into the editor; run via **F6**). Backed by
    `scripts/physics_test_harness.gd`. Root `Node2D` + script, `Camera2D` at position `(0, -400)`
    zoom `0.5`, empty Environment container. Wheel-zoom scales between `0.25x` and `3.0x`
    (resolution independence / vector outline thickness); middle-drag pans. Top-bar buttons
    **Spawn Crate / Spawn Ball / Spawn Plank** spawn dynamic props (`PropUtils`) above the
    angled ramp; a toggle button flips the rig **Stickman** ↔ **Ragdoll** (removing/restoring
    the best-effort `StaticBody2D` rig collision proxy); a **Knock Up** button impulses the
    ragdoll and all props upward.
  - `scenes/sandbox_stage.tscn` — **standalone staging scene** (Sandbox Stage Builder, Phase 2,
    not wired into the editor; run via **F6**). Backed by `scripts/sandbox_stage.gd`. Minimal
    root `Node2D` + script, `Camera2D` at position `(0, -400)` zoom `(0.5, 0.5)`, and an empty
    `World` (Node2D) container; the `GridLayer` (`StageGrid`), `GizmoLayer` (`StageGizmos`),
    `PlacementGhost` holder, and the CanvasLayer top-bar UI (mode toggle + six palette buttons +
    Grid/Snap/Size controls + status label) are built in code at `_ready()`. Phase 3b instantiates
    the `AssetSelector` grid popup (see below) into the UI `CanvasLayer`.
  - `scenes/asset_selector.tscn` — **standalone asset-selector grid popup** (Phase 3b, not wired
    into the editor). Rooted at `AssetSelector` (`PopupPanel`, `scripts/asset_selector.gd`); a
    **minimal shell/layout skeleton** — authored title bar, empty `GridContainer`, empty-state
    `Label`, and a footer (`Prev` / page label / `Next` / `Browse…` / `Refresh` / `Close`), all as
    unique-name nodes (`%TitleLabel`, `%GridContainer`, `%EmptyLabel`, `%PageLabel`, `%PrevButton`,
    `%NextButton`, `%BrowseButton`, `%RefreshButton`, `%CloseButton`). All dynamic per-cell content
    (thumbnail + name + prop material badge) is built in code at runtime because the entry set is
    dynamic; instantiated by `sandbox_stage.gd` (`_build_ui`) for the **Stickman** / **Prop**
    palette-button selector grids.

### Body-part data model
- 10 internal part keys (ordered): `head`, `torso`, `left_upper_arm`, `left_lower_arm`,
  `right_upper_arm`, `right_lower_arm`, `left_upper_leg`, `left_lower_leg`,
  `right_upper_leg`, `right_lower_leg`.
- Shape dictionary: `{ "shape_type": String, "points": Array[{x,y}], "color": "#hex",
  "closed": bool, "vertex_flags": Array[int] }`.
- `shape_type` values: `"line"`, `"rectangle"`, `"circle"`, `""` (empty).
  Descriptive tag in Phase 2 — rendering uses `closed`.
- `closed`: `true` = filled + closed outline, `false` = open outline-only.
- `vertex_flags`: same length as `points`; `0` = original vertex (filled circle),
  `1` = user-created via "Create Point" (hollow rectangle).
- **Phase 4:** A panel stores a `shapes[]` array of shape dictionaries. Z-order = array
  position (first = back, last = front). Per-part data includes `{shapes[], position,
  rotation, scale}`.
- **Phase 8:** per-part data adds `pivot` `{x, y}` (local bounding-box center = rotation
  origin) and `length` (float, bbox extent along the segment axis) for format v1.4; the
  `.stk` root also gains a top-level `proportions` object (5 rig bone lengths). All three
  are write-only metadata recomputed on every save — never read back on load.
- **Phase 9 Round 5:** per-part data adds `guide_offset` `{x, y}` (bbox center − guide joint,
  preview space; pure master-space delta) for format v1.5. Write-only metadata like
  `pivot`/`length`; the load path ignores it, so v1.0–v1.4 files load unchanged and gain the
  key on their next save.
- The JSON `.stk` format is defined in `README.md` (versioned `"1.5"`, extensible;
  `"1.0"`–`"1.4"` files auto-migrate on load).

### settings.json (Phase 6)
- Persisted editor preferences written to `settings.json` via `_save_settings()` and
  loaded in `_load_settings()`.
- Keys: `version`, `grid_size`, `snap_to_grid`, `recent_colors`, `show_pose_guide`.
- `recent_colors: Array[String]` — the last up-to-8 selected hex colors, most-recent-first.
  Populated on load and flushed on every color selection.
- `show_pose_guide: bool` — whether the pose silhouette guide is visible in the Whole
  Stickman preview. Default `true`. Loaded in `_load_settings()` and flushed on every toggle
  via `_broadcast_settings()`.

### Legacy scene (do not delete)
- `stick.tscn` — the original rigged/animated figure using `Skeleton2D` + IK targets +
  `RemoteTransform2D` + `Line2D` limbs, plus an embedded `@tool` script drawing the head
  circle. Animations: "walk", "walk_to", "RESET". **Not** the current main scene; kept for
  future animation/rigging phases.

## Editor conventions
- `.godot/` is gitignored; never edit it manually.
- Scene files (`*.tscn`) and `.import` files are text-based; use Godot's editor for complex changes.
- UID references (Godot 4 native) exist in scenes; do not change them by hand.
- Use standard Godot `Control` nodes where applicable.
- Use `class_name` for globally referenced scripts (`BodyPartPanel`, `WholeStickmanPreview`).
- Prefer `%UniqueName` access over exported node paths in `stickman_editor.gd` / `body_part_panel.gd`.
- Keep the `.stk` JSON format backward compatible — never change the meaning of an existing key.