summer-engine 3.7.0 → 4.0.0

package/library/skills/scene-scripting/references/ctx-api.md

@@ -0,0 +1,184 @@
+# scene-scripting: the extended ctx API
+
+The second and later tiers of the `ctx` object that `summer_run_script` hands to `func run(ctx):`. The core tier (creation helpers, `find`, `save_scene`, `summary`) is in the `scene-scripting` skill. Call results from `ctx` are untyped: write `var wall = ctx.add_mesh(...)`, never `var wall := ...` (GDScript cannot infer a type from an untyped call and refuses to compile).
+
+## The geometry & authoring stdlib (geometry tier)
+
+Newer engines extend ctx with a second tier: real geometry (booleans, lathe, sweep, terrain), mesh post-processing (smooth, decimate, UVs, mirror, collision), keyframe animation, and text shaders. Frozen signatures:
+
+```gdscript
+boolean(a: Node, b: Node, op: String = "union") -> MeshInstance3D
+    # op: union|difference|intersection. Manifold-exact CSG, baked to a plain
+    # ArrayMesh — no live CSG nodes remain. a and b are CONSUMED (freed) by
+    # default; pass keep_inputs: bool = true as the final param to keep them.
+extrude_polygon(points: PackedVector2Array, depth: float, name: String,
+                parent: Node = null) -> MeshInstance3D        # 2D footprint -> prism, baked
+lathe(points: PackedVector2Array, name: String, parent: Node = null,
+      spin_degrees: float = 360.0, sides: int = 32) -> MeshInstance3D  # revolve a profile, baked
+sweep(points: PackedVector2Array, path_points: PackedVector3Array,
+      name: String, parent: Node = null) -> MeshInstance3D    # profile swept along a 3D path, baked
+# add_mesh shapes extended: torus | text (props.text: String, TextMesh)
+set_smooth(node: Node, angle_deg: float = 30.0) -> bool       # shade smooth by angle
+terrain(size: Vector2, height: float, seed: int, name: String,
+        parent: Node = null, image_path: String = "") -> MeshInstance3D
+    # noise heightfield (or heightmap image via image_path); adds
+    # HeightMapShape3D collision under a StaticBody3D child automatically
+decimate(node: Node, ratio: float) -> bool                    # simplify mesh to ~ratio of triangles
+convex_collision(node: Node, decompose: bool = false) -> Node
+    # single convex hull, or multi-shape convex decomposition when decompose;
+    # ALL created bodies are owned — they survive the save
+uv_planar(node: Node, axis: String = "y", scale: float = 1.0) -> bool
+uv_box(node: Node, scale: float = 1.0) -> bool                # make textures land on generated geometry
+mirror(node: Node, axis: String = "x") -> Node                # mirrored duplicate
+animate(node: Node, property: String, keys: Array, anim_name: String = "",
+        loop: bool = false, player: AnimationPlayer = null) -> AnimationPlayer
+    # keys: [[time_s, value], ...]; gets-or-creates the AnimationPlayer and
+    # library; position/rotation/scale get dedicated 3D tracks (rotation keys
+    # are converted for you — never hand-build quaternion tracks)
+make_shader(code: String, params: Dictionary = {}) -> ShaderMaterial
+    # builds Shader + ShaderMaterial from source and sets shader parameters;
+    # compile errors come back VERBATIM in the result (the `make_shader_errors`
+    # report entry, plus errors[]) — read them
+```
+
+Conventions, same as the rest of the stdlib: creation helpers set the owner and return the created node; bad input produces a per-helper `report` entry plus a `null`/`false` return, never a crash; every baked mesh carries generated normals (and tangents where UVs exist). On an older engine these helpers are missing — the CSG-node fallback recipe in `recipes-3d.md` (next to this file) still works everywhere.
+
+## The animation stdlib (animation tier)
+
+Character-animation USAGE on top of `animate()` — state machines, method tracks, bone poses, head tracking. Same conventions. Frozen signatures:
+
+```gdscript
+animate(...) v2 — additive extensions, signature unchanged:
+    # keys entries also accept {time, value, interpolation: "nearest"|"linear"|"cubic"}
+    # property may target bones: "<skeleton_node>:<bone_name>/position|rotation|scale"
+    #   -> creates bone position_3d/rotation_3d/scale_3d tracks (path "Skeleton:bone")
+animate_method(node: Node, calls: Array, anim_name: String = "",
+               loop: bool = false, player: AnimationPlayer = null) -> AnimationPlayer
+    # calls: [[time_s, method_name, args_array], ...] -> one method-call track
+anim_state_machine(target: Node, spec: Dictionary,
+                   player: AnimationPlayer = null) -> AnimationTree
+    # spec: { states: {name: clip_name}, transitions: [[from, to, {auto?: bool,
+    #   blend_s?: float}], ...], start: name }
+    # get-or-create AnimationTree wired to the (found or given) player,
+    # AnimationNodeStateMachine, active=true; unknown clip names -> report
+    # entry listing the player's actual clips (never silent)
+bone_pose(skeleton: Node, bone: String, pose: Dictionary) -> bool
+    # pose keys position/rotation/scale -> set_bone_pose_* on Skeleton3D;
+    # unknown bone -> false + report listing bone names (capped 64)
+look_at_modifier(node: Node, target: Node, props: Dictionary = {}) -> Node
+    # LookAtModifier3D under the skeleton/node, owned
+```
+
+Blend shapes key through plain `animate()` with property `"blend_shapes/<name>"` (value tracks) — no separate helper. The end-to-end recipe (inspect an imported rig's real clips/bones, locomotion wiring, footstep method tracks, root motion, the raw-GDScript fallback for engines without these helpers) lives in `character-animation-wiring` — one hop, not duplicated here.
+
+## The game-completeness stdlib (game-completeness tier: 2D, UI, gameplay code)
+
+Everything a script needs to produce a GAME, not just a 3D scene: 2D levels, Control trees, persisted signal connections, attached scripts, prefabs, project settings. Same conventions (owner-by-default, return the node, `prop_warnings`, structured report entries on failure — never silent). 2D helpers work in any edited scene (root may be `Node2D` or `Node`); Control helpers parent under the edited root unless a parent is given. Frozen signatures:
+
+```gdscript
+# 2D
+add_sprite(texture_path: String, name: String, parent: Node = null,
+           props: Dictionary = {}) -> Sprite2D          # missing texture -> report + null
+add_animated_sprite(frames: Dictionary, name: String, parent: Node = null,
+                    autoplay: String = "") -> AnimatedSprite2D
+    # frames: { anim_name: { frames: [texture_paths], fps: float, loop: bool } } -> SpriteFrames
+add_tilemap(tileset_path: String, name: String, parent: Node = null) -> TileMapLayer
+paint_tiles(layer: TileMapLayer, cells: Array, source_id: int,
+            atlas_coords: Vector2i = Vector2i.ZERO) -> int     # cells: [Vector2i]; returns count
+paint_rect(layer: TileMapLayer, rect: Rect2i, source_id: int,
+           atlas_coords: Vector2i = Vector2i.ZERO) -> int
+add_body_2d(kind: String, name: String, parent: Node = null,
+            shape: Dictionary = {}, props: Dictionary = {}) -> Node
+    # kind: static|rigid|character|area ; shape: {type: rect|circle|capsule, size|radius|height}
+    # -> body + owned CollisionShape2D child. Empty shape = a 32x32 rect (confessed in
+    #    prop_warnings); size may be a float (square); props try the body, then the shape
+add_camera_2d(position: Vector2, zoom: Vector2 = Vector2.ONE, make_current: bool = true,
+              limits: Rect2i = Rect2i()) -> Camera2D          # empty limits = unlimited
+    # Camera2D has no saved "current" flag: make_current persists as `enabled` (+ a live
+    # make_current()); make_current: false saves the camera disabled
+add_parallax(layers: Array, name: String, parent: Node = null) -> Node
+    # layers: [{texture: path, motion_scale: Vector2, repeat: Vector2i}] -> one Parallax2D per
+    #   layer under one Node2D group; repeat -> repeat_size. Parallax2D is in the engine tree
+    #   (no ParallaxBackground fallback); a layer whose texture fails to load is skipped + reported
+
+# UI (Control)
+add_ui(kind: String, name: String, parent: Node = null, props: Dictionary = {}) -> Control
+    # kind: label|button|panel|vbox|hbox|grid|margin|texture_rect|progress_bar|line_edit|
+    #       rich_text|color_rect|center ; panel -> PanelContainer (container semantics for HUD
+    #       layouts; a plain Panel is add_node("Panel", ...)). props.anchor: full_rect|center|
+    #       top_left|top_right|bottom_left|bottom_right|top_wide|bottom_wide (+ the other
+    #       Control::PRESET_* names) -> set_anchors_and_offsets_preset, applied BEFORE the other
+    #       props so an explicit size/position wins; props.text/custom_minimum_size/etc via set();
+    #       props.texture as a "res://" path is loaded for you. A Control parented under a Node2D
+    #       gets a prop_warning (it scrolls with the camera — HUDs go under add_canvas_layer)
+add_canvas_layer(name: String, layer: int = 1, parent: Node = null) -> CanvasLayer
+set_theme_overrides(control: Control, overrides: Dictionary) -> int
+    # {font_size: int, font_color: Color, <theme_item>: value} -> add_theme_*_override; count applied
+    # dispatch by value: Color or "#hex" -> color; int/float -> font_size when the key is/ends with
+    #   font_size, else constant; StyleBox/Font/Texture2D (or a "res://" path) -> style/font/icon.
+    #   An item the control's theme type does not define is stored but confessed in prop_warnings
+connect_signal(emitter: Node, signal_name: String, target: Node, method: String,
+               binds: Array = []) -> bool               # PERSIST flag so it saves in .tscn;
+                                                        # unknown signal/method -> report, false
+    # NOT `connect` — a ctx method of that name would shadow Object.connect on the ctx object,
+    #   so nothing named `connect` is bound. Method gate: target.has_method, else its script
+    #   has_method, else the script SOURCE declares `func <method>(` (attached this run, not yet
+    #   compiled). Already connected -> true (+ already_connected in the report). Both ends must
+    #   be owned by the edited root for the .tscn to carry the connection (prop_warning otherwise)
+
+# Gameplay-code lane
+attach_script(node: Node, source: String, path: String = "") -> Script
+    # compile-validate first (GDScriptLanguage::validate; parse errors -> `attach_script_errors`
+    # report entry {node, path, errors: [{line, column, message}]}, null, nothing written);
+    # path empty -> res://scripts/<SceneName>/<NodeName>.gd (dirs created; the root node's name
+    # when the scene was never saved, prop_warning); writes the file, FS rescan, set_script.
+    # An existing file at path IS overwritten; its previous sha is recorded in the report (the
+    # pre-run checkpoint covers rollback). Gate: the script's native base (`extends`) must be an
+    # ancestor of the node's class — else the file is written but NOT attached (report, null)
+make_prefab(node: Node, path: String, replace_with_instance: bool = true) -> Node
+    # pack the subtree to res:// path as a PackedScene (owner fix-up first), save; when
+    # replace_with_instance the node is swapped for an instance of the new file (same
+    # name/transform/parent; outgoing persisted connections re-established) and the instance
+    # is returned; else returns node. REFUSES the scene root and a path open in an editor tab.
+    # The node's own position is zeroed for the pack (prefab authored at its origin, like the
+    # editor's Save Branch) and restored / copied onto the instance; rotation and scale stay in
+    # the prefab. A failure AFTER the file was written keeps + returns the original node (report)
+add_autoload(name: String, path: String) -> bool       # ProjectSettings autoload/<name>="*res://…"
+    # same gates as the editor's autoload dock: valid identifier, no engine/global-class
+    # collision, existing res:// path to a Script or PackedScene
+add_input_action(action: String, events: Array) -> bool
+    # events: [{type: key, keycode: String|int} | {type: mouse_button, button_index: int} |
+    #          {type: joypad_button, button_index: int} | {type: joypad_axis, axis:int, value:float}]
+    # writes input/<action> = {deadzone, events} in ProjectSettings + saves; every event is
+    # built BEFORE anything is written — unknown shape -> report, false, nothing half-written.
+    # New action: deadzone = the engine default 0.2. Existing action: keeps its deadzone and
+    # gains only the events it does not already match. Keycode strings go through
+    # find_keycode ("Space", "Left", "Ctrl+S" — modifiers become the event's modifier flags)
+set_main_scene(path: String) -> bool                   # application/run/main_scene + save
+    # path must exist and be a PackedScene
+# Project settings are written in the res:// PATH form ("*res://…", "res://…"); the editor UI
+# writes uid:// forms — both resolve. Do not "fix" one into the other.
+```
+
+**Engine posture. Read before relying on any of this.** The game-completeness tier is a frozen contract that not every engine build exposes yet; treat it with the same preview posture as `summer_run_script` itself (which returns `engine_lacks_op` on engines without RunSceneScript). On an engine that has RunSceneScript but predates this tier, a missing helper is a plain GDScript error (`Invalid call to method 'add_ui'…`) and, under the default `undo: "action"`, the whole run rolls back. Fall back to what works everywhere:
+
+| Game-completeness helper | Works on every engine |
+|---|---|
+| `add_tilemap` / `paint_tiles` / `paint_rect` | `TileMapLayer.new()` + `layer.tile_set = load(path)`, then `layer.set_cell(coords, source_id, atlas_coords)` in a loop — the GridMap recipe, in 2D |
+| `add_sprite` / `add_animated_sprite` / `add_body_2d` / `add_camera_2d` / `add_parallax` | manual `.new()` + `add_child` + `ctx.set_owner_recursive` |
+| `add_ui` / `add_canvas_layer` / `set_theme_overrides` | `.new()` + `set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)` + `add_theme_constant_override(...)`, owned as above — the `ui-basics` skill's plain-node script |
+| `connect_signal` | `summer_connect_signal` (persists in the `.tscn`); a raw `emitter.pressed.connect(...)` inside the run script does NOT persist |
+| `attach_script` | `summer_write_file` the source, `summer_get_script_errors` on it, then `node.set_script(load(path))` in a script |
+| `make_prefab` | `PackedScene.new().pack(node)` + `ResourceSaver.save(...)` (pack includes only OWNED descendants — owner rules again), then `summer_instantiate_scene` |
+| `add_input_action` / `add_autoload` / `set_main_scene` | `summer_input_map_bind`; `summer_project_setting` (`autoload/<Name>`, `application/run/main_scene`) |
+
+**Undo posture.** File-writing helpers (`attach_script`, `make_prefab`) and project-settings helpers (`add_autoload`, `add_input_action`, `set_main_scene`) are covered by the pre-run checkpoint, NOT by the packed-scene undo action — a `rolled_back: true` result has reverted the scene but not those files or settings. The result's `undo_action` note says so whenever any of them ran (`files_written: [paths]`, `project_settings_changed: [keys]`): read it, and surface `no_rewind_point: true` to the user before more work of this kind.
+
+## Pitfalls
+
+| Pitfall | Reality |
+|---|---|
+| Calling a geometry, animation or game-completeness helper on an engine that predates it | `Invalid call to method` — the run rolls back. Use the fallback table above. |
+| Reading `rolled_back: true` as "nothing happened" after `attach_script` / `add_autoload` / `set_main_scene` | Files and `project.godot` sit outside the undo action. Read `files_written` / `project_settings_changed`; the checkpoint is the rollback. |
+| `ctx.connect(button, "pressed", hud, "_on_pressed")` | That is `Object.connect` on the ctx object, not the helper — wrong-signature error. The helper is `ctx.connect_signal(...)`. |
+| `var node := ctx.add_node(...)` | `ctx` is untyped, so the type cannot be inferred and the script does not compile. Write `var node = ctx.add_node(...)`. |

package/library/skills/scene-scripting/references/recipes-2d-ui.md

@@ -0,0 +1,193 @@
+# scene-scripting: 2D, UI and gameplay-code recipes
+
+Every recipe below is the `source` of one call: `summer_run_script(scenePath="res://<the scene>.tscn", source=<the recipe>)`. Name the scene every time; it is opened first when it is not the edited one, and the person's tab comes back after the run. The core helpers (`add_node`, `find`, `add_mesh`, `make_material`, `save_scene` ...) are in the `scene-scripting` skill itself.
+These use the game-completeness tier (`ctx-api.md`, next to this file); on an engine that predates it, use the fallback table there.
+
+## 2D platformer level — tilemap paint, character body, camera limits, parallax (game-completeness tier)
+
+One script lays down the level: paint the ground, drop a character body with collision, bound the camera to the level, stack parallax behind it. Tile coordinates are cells; camera limits are pixels (cells × tile size — 32 here).
+
+```gdscript
+func run(ctx):
+    const TILE := 32
+    var ground = ctx.add_tilemap("res://tilesets/grass.tres", "Ground")
+    var painted = ctx.paint_rect(ground, Rect2i(0, 12, 64, 4), 0, Vector2i(0, 0))   # floor: 64 wide, 4 deep
+    painted += ctx.paint_rect(ground, Rect2i(20, 8, 6, 1), 0, Vector2i(1, 0))       # a floating platform
+    painted += ctx.paint_tiles(ground, [Vector2i(10, 11), Vector2i(11, 11), Vector2i(12, 11)], 0, Vector2i(2, 0))  # a step
+    ctx.report("tiles_painted", painted)
+
+    var player = ctx.add_body_2d("character", "Player", null,
+        {"type": "capsule", "radius": 14.0, "height": 60.0},
+        {"position": Vector2(3 * TILE, 11 * TILE)})
+    ctx.add_sprite("res://sprites/player_idle.png", "Sprite", player)
+
+    var cam = ctx.add_camera_2d(player.position, Vector2(2, 2), true, Rect2i(0, 0, 64 * TILE, 16 * TILE))
+    cam.reparent(player, false)              # follow the body...
+    cam.position = Vector2.ZERO
+    ctx.set_owner_recursive(cam)             # ...and re-stamp the owner after ANY reparent
+
+    ctx.add_parallax([
+        {"texture": "res://backgrounds/sky.png",   "motion_scale": Vector2(0.1, 0.1), "repeat": Vector2i(1024, 0)},
+        {"texture": "res://backgrounds/hills.png", "motion_scale": Vector2(0.4, 0.4), "repeat": Vector2i(1024, 0)},
+    ], "Background")
+    ctx.report("level", ctx.summary())
+```
+
+Compare `tiles_painted` with the cell areas you asked for (256 + 6 + 3 here) — a short count means cells were skipped. Then `summer_snapshot_diff`: `added` must list `Ground`, `Player` **with its `CollisionShape2D` child**, the camera under `Player`, and the `Background` group with one `Parallax2D` per layer. Screenshot `target:"scene" nodePath:"Player"` to see the body standing on the floor row, then the whole scene to see the platform is reachable. Movement needs the controller script and the input actions — two recipes below. Want a working baseline instead of a blank scene? The `2d-platformer` template already has tilemap + `CharacterBody2D` + parallax wired.
+
+## Animated sprite (game-completeness tier)
+
+`add_animated_sprite` builds the `SpriteFrames` resource from per-frame texture paths — one entry per animation, `fps` and `loop` per clip — and optionally autoplays one. Cut a sheet into frames first (`assets.slice_sheet`, or the `sprite-sheet` skill when generating them).
+
+```gdscript
+func run(ctx):
+    var player = ctx.find("Player")
+    if player == null:
+        ctx.report("error", "Player not found")
+        return
+    var anim = ctx.add_animated_sprite({
+        "idle": {"frames": ["res://sprites/player/idle_0.png", "res://sprites/player/idle_1.png"], "fps": 4.0, "loop": true},
+        "run":  {"frames": ["res://sprites/player/run_0.png", "res://sprites/player/run_1.png",
+                            "res://sprites/player/run_2.png", "res://sprites/player/run_3.png"], "fps": 12.0, "loop": true},
+        "jump": {"frames": ["res://sprites/player/jump_0.png"], "fps": 1.0, "loop": false},
+    }, "Anim", player, "idle")
+    ctx.report("animations", anim.sprite_frames.get_animation_names())
+```
+
+A missing texture path comes back as a report entry — read it before wondering why a clip is short. Which clip plays when is gameplay code (`anim.play("run")` from the controller's `_physics_process`), not scene setup. Verify by playing: `summer_play`, move, `summer_screenshot target:"game"` — an edit-time preview shows frame 0 only.
+
+## HUD — canvas layer, margin, vbox, label/progress/button, anchors, theme overrides (game-completeness tier)
+
+```gdscript
+func run(ctx):
+    var hud = ctx.add_canvas_layer("HUD", 1)
+    var margin = ctx.add_ui("margin", "Margin", hud, {"anchor": "full_rect"})
+    ctx.set_theme_overrides(margin, {"margin_left": 24, "margin_top": 24, "margin_right": 24, "margin_bottom": 24})
+
+    var column = ctx.add_ui("vbox", "TopLeft", margin)
+    var score = ctx.add_ui("label", "Score", column, {"text": "Score: 0"})
+    ctx.set_theme_overrides(score, {"font_size": 28, "font_color": Color(1, 1, 1)})
+    var health = ctx.add_ui("progress_bar", "Health", column,
+        {"min_value": 0, "max_value": 100, "value": 100, "show_percentage": false,
+         "custom_minimum_size": Vector2(240, 18)})
+
+    var pause = ctx.add_ui("button", "PauseButton", hud, {"text": "Pause", "anchor": "top_right"})
+    pause.process_mode = Node.PROCESS_MODE_ALWAYS      # still clickable while the tree is paused
+    ctx.report("hud", ctx.summary())
+```
+
+`props.anchor` runs `set_anchors_and_offsets_preset` — the right way to pin a Control; hand-set `anchor_*`/`offset_*` values drift the moment the window resizes. The preset is applied before the other props, so an explicit `size`/`position` in the same dict wins. `add_ui("panel", …)` is a **PanelContainer** (it sizes to its child — a backdrop for a vbox/hbox); a plain `Panel` is `add_node("Panel", …)`. `set_theme_overrides` returns how many overrides it applied — compare with what you passed (an `int` on a key that is not `font_size` becomes a *constant* override, as with the margins above). Unknown `props` keys land in `prop_warnings` as always (use real property names: `custom_minimum_size`, not `min_size` or a guess). HUD Controls belong under a `CanvasLayer` — a Control parented under a `Node2D` scrolls with the camera and gets a `prop_warning`. For the layout and theme *design* — which container for which job, theme vs inline styling — use `ui-basics`; this is its one-script form.
+
+## Wire a button with connect_signal() (game-completeness tier)
+
+`ctx.connect_signal` makes a **persisted** connection (`CONNECT_PERSIST`) — it survives in the `.tscn`, exactly what the editor's ConnectionsDock writes. The target needs a method to call, so attach the script first; a script attached in the same run has not compiled yet, and `connect_signal` accepts it because the source declares `func _on_pause_pressed(` (the method gate):
+
+```gdscript
+func run(ctx):
+    var hud = ctx.find("HUD")
+    var button = ctx.find("PauseButton")
+    if ctx.attach_script(hud, """
+extends CanvasLayer
+
+func _on_pause_pressed() -> void:
+    get_tree().paused = not get_tree().paused
+""") == null:
+        return                                   # parse errors are in the report — fix, re-run
+    if not ctx.connect_signal(button, "pressed", hud, "_on_pause_pressed"):
+        return                                   # the report names the unknown signal or method
+    ctx.report("wired", "PauseButton.pressed -> HUD._on_pause_pressed")
+```
+
+Never wire with a bare `button.pressed.connect(...)` inside the run script: that connection lives only in the editor process and is not saved. And the helper is `connect_signal`, not `connect` — `ctx.connect(...)` is `Object.connect` on the ctx object itself and fails with a wrong-signature error. `true` from `ctx.connect_signal` says the connection was made and flagged persistent (an already-connected pair also returns `true`, with `already_connected` in the report); both ends must be owned by the edited root or the `.tscn` cannot carry it. The proof is `summer_play`, click, `summer_screenshot target:"game"`.
+
+## attach_script — behavior with the parse-error loop (game-completeness tier)
+
+`attach_script` validates the source **before** writing anything: a parse error comes back as a report entry (with the line) and the return is `null` — no half-written file, no broken node. Empty `path` → `res://scripts/<SceneName>/<NodeName>.gd`.
+
+```gdscript
+func run(ctx):
+    var player = ctx.find("Player")
+    var script = ctx.attach_script(player, """
+extends CharacterBody2D
+
+const SPEED := 220.0
+const JUMP_VELOCITY := -420.0
+
+@onready var anim: AnimatedSprite2D = $Anim
+
+func _physics_process(delta: float) -> void:
+    if not is_on_floor():
+        velocity += get_gravity() * delta
+    if Input.is_action_just_pressed("jump") and is_on_floor():
+        velocity.y = JUMP_VELOCITY
+    var dir := Input.get_axis("move_left", "move_right")
+    velocity.x = dir * SPEED
+    if dir != 0.0:
+        anim.flip_h = dir < 0.0
+    anim.play("jump" if not is_on_floor() else ("run" if dir != 0.0 else "idle"))
+    move_and_slide()
+""")
+    if script == null:
+        return                                   # read the report: line + message; fix THAT line; re-run
+    ctx.report("script", script.resource_path)
+```
+
+The loop: read the exact parse error (line and identifier) from the report → fix that line → re-run. Do not guess-and-mutate. An existing file at `path` is overwritten and its previous sha recorded in the report — the pre-run checkpoint is the rollback for that, not the undo action. Idioms (typed declarations, signals, `_ready` vs `_process`): `gdscript-patterns`. Later edits to a script already on disk: `summer_write_file` + `summer_get_script_errors`.
+
+## make_prefab — turn a built subtree into a reusable .tscn (game-completeness tier)
+
+Build the thing once in-scene, then pack it. With `replace_with_instance` (the default) the inline subtree is swapped for an instance of the new file — same name, transform, parent — and the instance is returned.
+
+```gdscript
+func run(ctx):
+    var torch = ctx.find("Torch")               # Sprite2D + PointLight2D + Area2D you built above
+    if torch == null:
+        return
+    var first = ctx.make_prefab(torch, "res://prefabs/torch.tscn")
+    for i in range(3):
+        var t = ctx.instance_scene("res://prefabs/torch.tscn", null, "Torch%d" % (i + 2))
+        t.position = first.position + Vector2(160 * (i + 1), 0)
+    ctx.report("prefab", first.scene_file_path)
+```
+
+The owner fix-up runs before packing, so a child you forgot to own is included instead of silently dropped. The prefab is authored at its origin — the node's position is zeroed for the pack (the editor's Save Branch default) and copied back onto the instance, so `first.position` above is still where the torch stood; rotation and scale stay in the prefab. `make_prefab` refuses the scene root (pack a child subtree, never `ctx.get_scene_root()`) and a path that is open in an editor tab. The receipt: `res://prefabs/torch.tscn` in the result's `files_written`, `Torch` now reporting a `scene_file_path`, and the copies in the diff's `added`. From here on, edit the prefab file, not the instances.
+
+## Input actions, autoload, main scene (game-completeness tier)
+
+Project-level wiring in one run — the platformer controller above already reads these actions:
+
+```gdscript
+func run(ctx):
+    ctx.add_input_action("move_left",  [{"type": "key", "keycode": "A"}, {"type": "key", "keycode": "Left"},
+                                        {"type": "joypad_axis", "axis": 0, "value": -1.0}])
+    ctx.add_input_action("move_right", [{"type": "key", "keycode": "D"}, {"type": "key", "keycode": "Right"},
+                                        {"type": "joypad_axis", "axis": 0, "value": 1.0}])
+    ctx.add_input_action("jump",       [{"type": "key", "keycode": "Space"}, {"type": "joypad_button", "button_index": 0}])
+    ctx.add_autoload("GameState", "res://scripts/autoload/game_state.gd")   # the file must exist — write it first
+    if ctx.save_scene("res://levels/level_01.tscn"):
+        ctx.set_main_scene("res://levels/level_01.tscn")
+```
+
+An unknown event shape → report + `false`, never a half-written action (every event is built before anything is written). A new action gets the engine's default deadzone, 0.2; re-running on an existing action keeps its deadzone and appends only the events it does not already match, so the recipe is safe to re-run. Keycode strings are `find_keycode` names (`"Space"`, `"Left"`, `"Ctrl+S"` — modifiers become the event's modifier flags). Write the autoload's script before registering it (`summer_write_file`, or `attach_script` on a node you then `make_prefab`) — `add_autoload` applies the editor dock's gates (valid identifier, no class-name collision, an existing `res://` Script or PackedScene). These helpers write the `res://` path form (`"*res://…"`, `"res://…"`); the editor UI writes `uid://` forms and both resolve — leave them be. They write `project.godot`, not the scene: the result's `undo_action` note lists them under `project_settings_changed`, outside the scene undo — checkpoint territory. Proof: `summer_play` → `summer_get_runtime_tree` shows `/root/GameState`; the keys move the body in a `target:"game"` capture.
+
+## Verifying 2D and UI work
+
+Same loop, different framing:
+
+- **Diff first.** `added` must carry the bodies' `CollisionShape2D` children, the `CanvasLayer` with its Controls, one `Parallax2D` per layer. Anchors and theme overrides show up as `changed` properties on the Controls.
+- **2D scene captures.** `summer_screenshot target:"scene"` on a 2D scene synthesizes a `Camera2D` and auto-fits the `CanvasItem` bounds — the 3D presets do not apply, and `framing:"camera"` errors on a scene with no 3D content. `nodePath:"Player"` frames one node (its 2D rect, children included); `size:[1280, 720]` sets the resolution that anchors resolve against.
+- **UI and anything input-driven** is only proven in the running game: `summer_play`, then `summer_screenshot target:"game"`. An edit-time preview of a HUD approximates a viewport the editor does not have.
+- Read the confession fields in every capture (synthetic camera, no camera, project mismatch). A capture you did not receive is not evidence — `verifying-scenes` has the full discipline.
+
+## Pitfalls
+
+| Pitfall | Reality |
+|---|---|
+| Painting tiles with `summer_set_prop`, or hand-editing `tile_map_data` | `ctx.paint_rect` / `paint_tiles` (or `set_cell` in a loop) — cells are packed data. |
+| Building a HUD with a dozen `summer_add_node`/`summer_set_prop` calls | One script: `add_canvas_layer` → `add_ui` → `set_theme_overrides`. |
+| `button.pressed.connect(...)` inside the run script | Not persisted — gone when the script ends. `ctx.connect_signal` (or `summer_connect_signal`) saves it in the `.tscn`. |
+| `{"min_size": ...}` in `add_ui` props | Not a Control property — lands in `prop_warnings` and does nothing. The property is `custom_minimum_size`. |
+| `ctx.make_prefab(ctx.get_scene_root(), ...)` | Refused. Pack a child subtree; the scene itself is `save_scene`. |
+| Re-running a failed `attach_script` with a guessed fix | The parse error is in the report with the line. Read it, fix that line. |
+| Judging a HUD from an edit-time scene preview | Anchors resolve against the real viewport. `summer_play` + `target:"game"`. |
+