# Tweaker: live styling and source write-back

Read this when the user is giving visual feedback or when applying a live
style change. Follow [AGENTS.md](../../AGENTS.md) for instance ownership and
capture policy. The overlay implementation is
[widgets/families/tweaker/src/tweaker.rs](../../widgets/families/tweaker/src/tweaker.rs).

## Interaction and commands

Toggle with Shift+F10 or `tweak on=1`. The overlay adds a property
sidebar and intercepts pointer events over the app body: selecting a button
outlines it without firing its action. Turn it off before testing ordinary
widget clicks.

| Command | Result |
|---|---|
| `tweak on=1` or `on=0` | Enable/disable the overlay |
| `tweak annotate=1` or `annotate=0` | Enable/disable freehand annotation; Alt-drag also draws |
| `tweak state` | Selection, reflected properties, hover, edits, and annotations |
| `tweak apply` | Apply one property or a Splash chunk and wait for relayout |
| `tweak diff` | Ordered edit log |
| `tweak clear` | Clear edit log and annotations |
| `tweak final` | Coalesced initial/final values and annotations; may include a PNG |
| `tweak grab` | App-owned grab including the overlay |

`tweak apply` can name one property:

```sh
makepad-remote app $P tweak apply path=main_window.body.panel prop=padding 'value=Inset{left: 20}'
```

Or merge a Splash chunk onto the selected instance:

```sh
makepad-remote app $P tweak apply path=main_window.body.panel 'splash={draw_bg +: {border_radius: 8}}'
```

Use the selected widget's reflected property names; not every draw type
exposes the same radius/color fields. In `tweak state`, `set:1` means a
property was explicitly applied.

Sidebar edits emit `TWEAK sidebar <path> <prop> <old> -> <new>` in the app
log. Listen through `log since=N`; do not poll `tweak state` for changes.
Read state when inspecting a selection or verifying an applied value.

## Structural edits: the designer

The Build tab's design session edits the Splash source of the file that
declares a widget: insert, move, delete, wrap, rename and set properties.
Each edit is a byte-range hunk inside the `script_mod!` body, previewed
live in the running app. The app never writes the file; the agent applies
the patch. The same session is reachable through `design <op>`, and a person's Build
tab edits and an agent's commands share one undo history.

| Command | Result |
|---|---|
| `design open path=P` | Start a session on the file declaring `P` (default: the pinned widget) |
| `design state` | File, edit count, status, `can_undo`/`can_redo`, `landing`, hunk labels |
| `design palette` | Insertable types with their default bodies |
| `design insert path=P place=before\|after\|inside type=T body=B` | Insert `T` (body defaults to the palette's); answers the new widget's path in `select` |
| `design move path=P to=Q place=...` | Move `P` next to or into `Q` |
| `design delete`, `duplicate`, `wrap`, `up`, `down`, `out` `path=P` | Structural edits of `P` |
| `design rename path=P name=N` | Name, rename or (empty `name`) unname a literal |
| `design set path=P key=K value=V` | Write a property into the literal (`+:` for a new typed property) |
| `design bake` | Write every value-ledger tweak on this file's widgets into the source |
| `design undo`, `redo`, `reset` | Step the source edits |
| `design patch`, `design commit` | The unified diff; `commit` adds `base_hash`, `new_hash`, `base_matches_disk` and the hunks |
| `design verify` | Every drawn widget of the file and whether its literal is found |
| `design close` | End the session; writes `local/design/<file>.patch` |

Edits answer after the frame that shows them, so a `grab` right after sees
the change; send `if_user_seq` like any other mutation. An edit whose
preview the runtime rejects is rolled back and reported in `status`. An op
on a `#(...)` placeholder is refused (it needs a rebuild), and so is an
edit to a widget declared in another file. To persist: read
`design commit`, check `base_matches_disk`, apply `diff` to the file, then
rebuild, relaunch and verify as below.

## Motion: the tween inspector

The Motion tab lists every animation the app's `TweenHost`s play (the
Splash `tween` driver, stack navigation, the widgets and stories built on
the tween engine) and shows the chosen one on a timeline: its labels on
the ruler, one lane per child indented by depth, and the playhead. Drag on
the timeline to scrub (the animation pauses, callbacks stay quiet, and it
plays on at release if it was playing); the chips pause, restart, set
the speed, loop (repeat forever) and yoyo; the divider between the
lane names and the timeline drags. Hosts publish only while the tab is up.

`tweak op op=motion` answers the same data as JSON: `open`, and per host
`id`, `name`, `age` and `roots` (`name`, `kind`, `len`, `time`, `paused`,
`linked` (0 once a kept animation completed), `repeat`, `yoyo`, `scale`,
`lanes`, `labels`). Add `host=<id> root=<k>` with one of
`seek=<seconds>`, `pause=1`, `resume=1`, `restart=1`, `scale=<x>`,
`loop=1|0` (repeat forever, or none) or `yoyo=1|0` to
control the k-th top-level animation of that host; the host applies it on
its next event, so read again after a frame. `open=1` publishes without
the tab.

## Persist the result

The overlay never writes source. With a design session open,
`design bake` turns the value tweaks into hunks and `design commit`
returns the patch; without one, at the end of a styling session:

1. Read `tweak final`. If annotations produced a `png`, inspect it; the
   strokes are part of the user's feedback.
2. Resolve each dotted widget path to its `script_mod!` declaration.
   Skip anonymous `-` segments when searching. `dump` shows the same ids.
3. Write properties at the most specific existing instance declaration.
   Create an instance override only if no appropriate site exists.
4. Preserve typed-property merging with `+:`. Plain walk/layout properties
   are assigned directly with the correct typed value.
5. Preserve returned source spellings, adding the Rust-macro `#x` color
   escape where required.
6. Rebuild and relaunch. Verify values through reflection or snapshots,
   and inspect a new frame when the visual result matters.
7. Finish your test instance through `gq`, or the cleanup fallback in
   the runbook.

Use these commands directly; this workflow does not require a helper
under `local/`.