@flatkit/compiler 0.26.0 → 0.27.0

package/docs/animating-symbols.md

@@ -0,0 +1,357 @@
+# Animating a symbol (`.flat`)
+
+> How a `.flat` symbol moves over time: the **timeline / cel / pose** model (Flash-style), the `pose`
+> keywords (`rotate`, `scale`, `opacity`, `spin`…), pivots, tweens, and how to preview the result.
+> If you only need static composition, see [Scene & drawing](scene-and-drawing.md).
+
+## The model in one paragraph
+
+A symbol owns a **timeline** (`timeline <fps> <durationFrames>`). Each animated **layer** is a time
+track: a sequence of **cels** (layer-wide keyframes). A cel lists the **poses** of the containers
+present at that frame (a `pose` per roster item) and, optionally, the **matter** (static drawing) at
+that key. Between two cels the layer either **holds** the last key or **tweens** toward the next one.
+
+```
+symbol "Wheel" {
+  timeline 24 24                 ← 24 fps, 24 frames (loops once per second)
+  layer "spin" {
+    group "Rim" at 100,100 pivot 0,0 {   ← the roster: declared ONCE, posed by the cels below
+      layer "art" { circle 0 0 40 nofill stroke #333 8 }
+    }
+    cel 0 tween { pose "Rim" rotate 0 }
+    cel 24       { pose "Rim" rotate 360 }   ← one full turn around the pivot, in DEGREES
+  }
+}
+```
+
+Preview it without authoring a wrapper:
+
+```
+flatc --preview Wheel.flat --render -o wheel.png   # a PNG (frame 0)
+flatc --preview Wheel.flat -o wheel.flatpack        # a playable .flatpack for the browser player
+```
+
+## `pose` — the keyframe of a container
+
+```
+pose "Name" [at <x>,<y>] [rotate <deg>] [scale <s> | scaleX <sx> scaleY <sy>]
+            [opacity <o>] [tint <#color> <amount>] [spin cw|ccw] [turns <n>] [filter …]
+```
+
+- **`rotate <deg>` and `scale`/`scaleX`/`scaleY` are in human units** (degrees, multipliers) and apply
+  **around the group's `pivot`** — no matrices, no radians, no trigonometry. `rotate 90` is a quarter
+  turn; `scale 2` is double size.
+- **`at <x>,<y>`** places the container's local **origin** in parent space. `rotate`/`scale` then turn
+  and scale around the `pivot` point (see below), keeping it anchored.
+- **`matrix(a,b,c,d,e,f)`** is still accepted as an escape hatch, but you almost never need it.
+
+### Patch semantics — a pose only overrides what it states
+
+A pose **inherits** every channel it does not mention from the container's resting pose (its declaration
+in the roster) — position, rotation, scale, opacity, tint, filters. So:
+
+```
+pose "Boat" opacity 0.5        ← keeps the Boat's declared position/rotation/scale; only dims it
+pose "Boat" rotate 3           ← keeps its position and scale; only tilts it 3°
+```
+
+You do **not** re-state `at x,y` in every cel just to change opacity. (This is a change from older
+builds where a partial pose snapped to `0,0`.)
+
+## Pivot vs `at` — where things turn
+
+- **`pivot <x>,<y>`** (set on the container in the roster, in its **local** coordinates) is the center
+  of rotation **and** scale **and** tween interpolation. Default is the local origin `0,0`.
+- **`at <x>,<y>`** (on the pose) is where the local origin lands in the parent.
+
+**Rule of thumb:** set the group's `pivot` to its visual center, then `rotate`/`scale`/`spin` turn it in
+place. A wheel whose art is centered on its local origin needs no pivot; a wheel drawn off-origin must
+set `pivot` to its hub, or it will **orbit** instead of spin.
+
+```
+group "Hand" at 200,200 pivot 0,-60 {   ← pivot at the clock center, 60px below the hand's tip
+  layer "art" { rect -4 -60 8 60 fill #111 }
+}
+…
+cel 0 tween { pose "Hand" rotate 0 }
+cel 60       { pose "Hand" rotate 360 }  ← sweeps around the pivot, not its own middle
+```
+
+## Tweens, easing, spin
+
+- **`cel N tween { … }`** interpolates this cel → the next for every container present in both. Without
+  `tween`, the cel **holds** until the next key.
+- **`ease <curve>`** on the cel: `linear` · `easeIn` · `easeOut` · `easeInOut` · `cubic(a,b,c,d)`.
+- **`spin cw|ccw`** + **`turns <n>`** force the rotation **direction** and add full turns across the
+  tween, so a 350° → 10° move can go the short way (`ccw`) or wind several times (`turns 2`). The spin
+  is **around the pivot**, like every other rotation.
+- **`morph`** on a cel tweens the *shape* of the `matter` (drawing) toward the next key.
+
+## Presence across cels — a cel is a full snapshot
+
+Each `cel` is a **keyframe = the full set of containers present at that instant** (Flash style). A container
+is shown only on the cels that **pose** it; one omitted from a cel **disappears** there. So a container
+visible across a span must be posed on **each cel of that span** (it's per-*keyframe*, not per-frame — three
+keyframes ⇒ three poses, not one per frame). This is also how a symbol **exits**: stop posing it.
+
+Two ways to avoid re-typing an unchanged container:
+
+- **Static element → its own layer WITHOUT cels.** A cel-less layer renders its items at every frame, so a
+  static base/background is declared **once** and never flickers. (Same idea as the render-order note below.)
+- **`cel N hold { … }`** — carry the previous cel's poses forward for every container this cel does *not*
+  mention, then apply the stated overrides. Pure authoring sugar (the compiler expands it to full cels), so
+  you only write what changes:
+
+```
+cel 0  tween { pose "Base" at 0,0   pose "Ring" scale 1 }
+cel 30 hold tween { pose "Ring" scale 4 }   # Base carried automatically
+cel 60 hold       { pose "Ring" scale 1 }
+```
+
+`hold` is opt-in per cel; without it the default (an omitted container is removed) is unchanged — so
+exits still work.
+
+## Frame-by-frame — a different DRAWING on each cel
+
+A cel carries the poses **and** the layer's **matter**: the drawing at that key, written as a
+`matter { … }` block. Change it from cel to cel and you get classic cel animation — one drawing per
+frame, no tween:
+
+```
+symbol "Blink" {
+  timeline 12 3
+  layer "draw" {
+    cel 0 { matter { circle 0 0 30 fill #e33 } }
+    cel 1 { matter { rect -30 -30 60 60 fill #3a3 } }
+    cel 2 { matter { path "M -30 30 L 0 -30 L 30 30 Z" fill #33e } }
+  }
+}
+```
+
+- The matter is **held** until the next cel that defines one — a drawing kept over several frames is
+  written **once**, on the cel where it appears. An explicit `matter { }` (empty) blanks it.
+- **`morph`** on the cel interpolates the *shape* toward the next cel's matter instead of cutting.
+- A cel can carry **both**: a `matter { … }` for that frame's drawing *plus* `pose "…"` for the
+  containers animated on top of it (matter always draws **behind** the posed containers).
+
+Two other ways to author the same thing, when the drawings already exist as objects:
+
+- **Swap containers** — declare each drawing as a group in the roster, then pose only the one you want on
+  each cel (a container omitted from a cel disappears — see above).
+- **Image sequence** — the same idiom with `image` items: `image "f1" 100 100 as "F1" at -50,-50` in the
+  roster, `cel 0 { pose "F1" }`. The media is declared in the `.flatink` (`asset "f1" "f1.png" image`).
+
+> **The trap:** in a layer that **has cels**, a bare shape written directly in the layer is **never
+> drawn** — such a layer renders the current cel's `matter` plus the containers that cel poses, and
+> nothing else. Put the shape inside a `matter { … }`, or on a **cel-less layer** if it is static decor.
+> `flatc --check` warns about it, and about the two sibling silent drops: a `pose "X"` naming no roster
+> item, and a roster item that no cel ever poses.
+
+## Driving a channel with an expression (`expr`)
+
+Instead of keyframes you can bind a channel to an expression on the container itself:
+
+```
+group "Fan" pivot 0,0 expr rotation "turns(time)" { … }   ← one turn per second
+```
+
+- The animatable channels are `x`, `y`, `scaleX`, `scaleY`, `rotation`, `opacity`.
+- **`rotation` is in RADIANS** (like `sin`/`cos`/`atan2`). Use the helpers to stay in degrees:
+  - `rad(deg)` → radians, e.g. `expr rotation "rad(45)"`
+  - `turns(n)` → `n` full turns in radians, e.g. `expr rotation "turns(time)"` or `"turns(time * 0.5)"`
+  - `deg(rad)` → the inverse, for readouts.
+
+## Stateful "feel": `spring` / `smooth`
+
+`expr` is **pure** — it recomputes from `time`/params each frame, with no memory. When you want a channel to
+*react over time* (lag behind a moving target, swing and settle), use a **modifier** instead. It carries
+per-instance state that **integrates** toward a target each frame — so an asset's physical "feel" lives **in
+the asset**, with no scene code:
+
+```
+group "Suspente" spring rotation "crochetX" stiffness 0.08 damping 0.86 { … }   # cable swings, then settles
+group "Aiguille" smooth rotationDeg "valeur * 270" k 0.18 { … }                 # needle eases to its value
+```
+
+- `smooth <channel> "<target>" k <0..1>` — 1st-order lag: each step `value += (target − value) * k`. Small
+  `k` = slow/heavy; `k = 1` = instant (no lag).
+- `spring <channel> "<target>" stiffness <0..1> damping <0..1>` — 2nd-order spring: overshoots then settles.
+  Lower `damping` = more bounce. (Both params are per fixed 60 Hz step; out-of-range values are clamped.)
+- `<target>` is an ordinary expression (params, `time`, `self.x`, …) — the resting value the channel chases.
+  Authoring sugar like `expr`: `rotate` = `rotation`; `rotationDeg` reads degrees (wraps the target in `rad()`).
+- A modifier **wins** over a plain `expr` / keyframes on the same channel.
+
+**React to MOVEMENT, not value — `velocity(expr)`.** Inside a modifier target (only there), `velocity(x)` is
+the per-second rate of change of `x`. It's **0 at rest** and while scrubbing/rendering, non-zero only while `x`
+is actually moving — perfect for a pendulum on a moving pivot (a crane cable that swings when the trolley moves,
+then hangs vertical again, with no scene code):
+
+```
+group "Suspente" spring rotation "rad(-velocity(crochetX) * 40)" stiffness 0.06 damping 0.22 { … }
+```
+
+At rest `velocity = 0` → target `0` → vertical, automatically; on a scrub/`--render` it's also `0` → snaps to
+rest. Composable in any target (`rad(-velocity(crochetX)*40 + 2*sin(time))`). `velocity()` is **only** valid in a
+modifier target — `flatc --check` flags it elsewhere.
+
+**Per instance.** State is keyed per instance, so two cranes side by side swing **independently** (even when
+the spring is on a group *inside* the symbol).
+
+**Live vs. static.** The spring animates during **playback** (gallery autoplay, an activity). On **random
+access** — a timeline scrub, `--render`, a contact sheet — there is no time to integrate, so the channel
+**snaps to its target** (the rest pose). So tune a spring by *playing* the preview, not by scrubbing.
+
+**Also scene-side.** The same modifier works in a `.flatink` `object` block — the target is then an ordinary
+(unquoted) FlatInk expression — for a one-off spring on a scene object, when the feel isn't baked into a `.flat`:
+
+```
+object "Hero" {
+  spring rotation = crochetX { stiffness 0.08 damping 0.86 }
+  smooth opacity = lit { k 0.18 }
+}
+```
+
+## Looping & instancing
+
+The timeline loops over `[0, durationFrames)`. An `instance` of a symbol chooses **how its own timeline
+advances** (Flash's symbol-instance models), written after the instance's attributes:
+
+```
+instance "Walk" as "legs"                # synced (default)
+instance "Walk" as "legs" loop           # independent (MovieClip)
+instance "Splash" as "fx" once           # play once, then hold the last frame
+```
+
+| mode | clock | behavior |
+|---|---|---|
+| *(default)* / `synced` | the parent's frame | **Graphic symbol**: scrubbed and *truncated* by the parent — if an ancestor's timeline is shorter than (or not a multiple of) the sub-loop, it snaps mid-cycle. Best for lip-sync, deterministic scrub. |
+| `loop` (`independent`) | the runtime's monotone clock | **MovieClip**: loops on its *own* duration, immune to any ancestor's loop length. Use for state-loops and idles that must keep their phase across the parent's wrap. |
+| `once` | the monotone clock, clamped | plays through **once**, then **holds** the last frame — a one-shot (a splash, an explosion, a pose that stays). |
+| `singleFrame` | — | frozen on a fixed frame. |
+
+A `loop`/`once` instance runs on the global heartbeat, so it never needs its parent padded to a common
+multiple ("LCM") of its sub-loops. In the **editor** it shows frame 0 (MovieClip-style authoring); it plays
+at runtime — edit its keyframes by opening the symbol itself. `--preview` sizes its window to show a nested
+`loop`/`once` looping cleanly, without touching the previewed symbol's own authored duration.
+
+## Exposed parameters (`params`)
+
+A symbol can publish a small, named **interface** instead of exposing its internals — useful for restyling
+an asset (hull/sail colors), tuning an animation (amplitude, speed), or toggling a detail, including
+"after the fact" by a small model.
+
+```
+symbol "Boat" {
+  params {
+    color  hull = #c0392b           "Hull color"
+    color  sail = #2980b9           "Sail color"
+    number wave = 1   range 0 2     "Bob amplitude"
+    bool   flag = true              "Show the pennant"
+  }
+  layer "body" {
+    path "…" fill hull                                  // a color param used as a fill
+    group "Deck" expr y "sin(clock*3) * wave" { … }     // a number param read in an expression
+    group "Flag" expr opacity "flag ? 1 : 0" { … }      // a bool param as a toggle
+  }
+}
+```
+
+- `params { <type> <name> = <default> [range <min> <max>] ["doc"] … }` — `<type>` is `color`, `number`,
+  or `bool`. The default, range, and doc string make the interface self-describing.
+- **`color` params** are used as a paint — `fill hull`, `stroke hull <width>`, a **gradient stop**
+  (`0:hull@0.8`, optional `@alpha`), or a **`tint hull <amount>`** (anywhere a `#color` literal goes).
+  Resolved per instance at render; *not* available in numeric expressions.
+- **`number` / `bool` params** become **variables in the symbol's expressions** (`wave`, `flag`). `bool`
+  reads as `1`/`0`. (`flatc --check` knows them — reading a declared param in an `expr` is not an "unknown
+  variable".)
+
+> The `timeline`, `params`, and `states` header blocks may appear in **any order** before the layers.
+
+Set params at the instance **call-site** (literals), in `--preview`, or — for `number`/`bool` — at
+runtime (`Boat.wave = 1.5`, see below):
+
+```
+instance "Boat" as "Hero" at center { hull = #1a5f3a, wave = 1.5, flag = false }
+flatc --preview Boat.flat --render --set hull=#1a5f3a,wave=1.5 -o boat.png
+```
+
+> A `state` (below) is just another exposed param — same call-site/preview/runtime surface.
+
+## Named states (`states`)
+
+A symbol can expose **named states** — points on its own timeline — and let a consumer switch between
+them. A door is the canonical case: the symbol animates from `closed` (frame 0) to `open` (frame 24),
+and exposes that as a single param.
+
+```
+symbol "Door" {
+  timeline 24 24
+  states door { closed at 0   open at 24   initial closed   transition 12 ease easeInOut }
+  layer "panel" {
+    group "Panel" at 60,10 pivot 0,0 { layer "art" { rect 0 0 40 80 fill #884422 } }
+    cel 0 tween { pose "Panel" rotate 0 }      // closed
+    cel 24       { pose "Panel" rotate 80 }    // open
+  }
+}
+```
+
+- `states <param> { <name> at <frame> … }` declares the state machine. `<param>` is the exposed
+  variable (`door`); each `<name> at <frame>` anchors a state to a frame of the symbol's timeline.
+- `initial <name>` is the resting state (default: the first). `transition <n> [ease <e>]` is the default
+  move between states.
+- **The param drives the symbol's local playhead.** `door = 0` (or `closed`) → frame 0; `door = 1`
+  (or `open`) → frame 24; a fractional `door = 0.5` → frame 12, i.e. the authored in-between animation.
+  So **animating the variable from 0→1 plays the open animation** — states live inside the ordinary
+  variable system, no special runtime.
+
+Select a state in a preview (a state name or a number):
+
+```
+flatc --preview Door.flat --render --set door=open -o open.png
+flatc --preview Door.flat --render --set door=0.5  -o half.png   # mid-transition
+```
+
+### Driving a state from a program (`set Name.param = state`)
+
+In a `.flatink` program, address an instance **by name** and set its state — the player plays the
+declared `transition` automatically. Each instance keeps its **own** state, so two doors are independent.
+
+```
+scene {
+  layer "stage" { instance "Door" as "FrontDoor" at 100,100 }
+}
+object "FrontDoor" {
+  when clicked { FrontDoor.door = open }   // animates closed → open over `transition` frames
+}
+```
+
+The right-hand side is a **state name** (`open`) or an expression (`FrontDoor.door = score > 5 ? open : closed`
+isn't valid — names aren't expressions; use a number there, e.g. `… ? 1 : 0`). `transition 0` snaps instantly.
+
+> **Scope note:** the state value drives the instance's playhead and is visible to that instance's own
+> expressions. Reading another object's state back by name (`FrontDoor.door` in an unrelated expression)
+> and the broader typed `params {}` interface (colors/numbers/toggles, `fill hull`) are still to come.
+
+## Render order (a real caveat)
+
+Within **one animated layer**, the **matter (static drawing) always renders behind the posed
+containers** — declaration order between a bare `path` and an animated `group` is **not** preserved,
+because the cel model stores matter and the container roster separately.
+
+**If a static shape must sit IN FRONT of an animated group**, give it its own group (so it becomes a
+posed container too) or, simpler, **put it on its own layer** above. Layers always honor their stacking
+order. This is the reliable way to control z-order around animation.
+
+## Previewing without clipping
+
+`flatc --preview` auto-sizes the stage to the symbol's bounds. By default (`--bbox all`) it measures the
+**union over every frame** (sub-timelines unfrozen), so a part that drifts, rotates, or grows is **never
+clipped**. Use `--bbox frame0` for the old frame-0-only measure, and `--pad N` to add a margin.
+
+```
+flatc --preview Boat.flat --render -o boat.png            # union bbox (default) — full motion fits
+flatc --preview Boat.flat --bbox frame0 --pad 40 -o b.png # frame-0 bounds + 40px margin
+```
+
+See also: [Tooling](tooling.md) for the full `flatc` reference, and
+[Gotchas](dsl-gotchas.md) for sharp edges.

package/docs/behavior-and-interactions.md

@@ -0,0 +1,306 @@
+# Behavior & interactions
+
+Everything after the `scene { … }` block is behavior. It attaches to named scene items via
+`object "Name" { … }`, or runs scene-wide via `every frame { … }` and timeline hooks.
+
+```
+var score = 0
+
+object "Coin" {
+  when clicked { score = score + 1 }     // an EVENT handler (actions)
+  rotation = clock * 90                   // a CHANNEL binding (expression, every frame)
+}
+
+every frame { if (score >= 10) { send "win" } }
+```
+
+## Events
+
+Inside `object "Name" { … }`:
+
+| Event | Fires when |
+|---|---|
+| `when clicked` | the item is **tapped** — press + release with no drag (fires on release, within a few px) |
+| `when hovered` / `when unhovered` | the pointer enters / leaves |
+| `when pressed` / `when released` | pointer down / up on the item |
+| `when dragged` | the item is being dragged (grab in progress) |
+| `when held` | a long press |
+| `when dropped on <Zone> [at pointer]` | released over a drop zone (see [drag & drop](#drag--drop)) |
+
+Scene-wide: `when loaded { … }` (once), `every frame { … }` (each tick), `at frame <n> { … }`,
+`label <frame> "name"`.
+
+## Actions
+
+In a handler body, one action per line:
+
+```
+play  ·  pause                          # timeline control
+go to frame <n> [and play|and pause]
+go to "<label>" [and play|and pause]
+<name> = <expr>                          # set a variable (the `set` keyword is optional)
+<arr>[<expr>] = <expr>                   # indexed assignment (nested indices ok: occ[sl[i]] = 0)
+if <cond> { … } [else if <cond> { … }] [else { … }]
+repeat <n> times { … }                   # runtime loop (bounded)
+repeat i from <a> to <b> { … }           # runtime range loop
+<fn>(<args>)                             # call a function
+send "<event>" [, <payload>]             # emit an event to the host (see below)
+sound "<assetId>"                        # one-shot audio
+```
+
+### `send` — talking to the host
+
+`send` is the one-way channel from the scene to the page that embeds it. Four payload forms:
+
+```
+send "win"                               # bare — just the event
+send "score", lives * 100                # a NUMBER (any expression)
+send "answer", text("txtCard")           # the live TEXT of a text item
+send "save", { x = px, y = py, doors }   # a RECORD: named numbers (a state patch)
+```
+
+In a record, `{ doors }` is shorthand for `{ doors = doors }` — handy when the field and the variable
+share a name. Fields hold **numbers only**, at most 32 per `send`, and each name must be a plain
+identifier (`[A-Za-z_]\w*`, 64 characters max, and never `__proto__`/`constructor`/`prototype`).
+
+The host receives one object: `{ name, value?, fields? }` — `value` for the number/text forms, `fields`
+for the record. Nothing comes back: `send` is fire-and-forget and never blocks the scene. See
+**[Host integration](host-integration.md)** for the receiving end.
+
+## Variables
+
+```
+var score = 0                # scalar (declared at the top of the file, Layer B state)
+var slots = [0, 0, 0]        # array literal
+var seen = fill(8, 0)        # array of 8 zeros
+```
+
+Read/write them in expressions and actions. `var`s are runtime state — distinct from `def` (a
+compile-time constant, see [factoring](#reuse--factoring)).
+
+## Channel bindings
+
+Drive an item's pose every frame with an expression. Channels: `x`, `y`, `scaleX`, `scaleY`,
+`rotation`, `opacity` (absolute), plus the additive position offsets `dx`, `dy` (`pos = at + (dx, dy)`).
+
+```
+object "Needle" {
+  rotation = atan2(mouse.y - 160, mouse.x - 240)   // point at the cursor (RADIANS)
+  opacity  = lit ? 1 : 0.3
+}
+```
+
+`rotation` is in **radians** (like `sin`/`cos`/`atan2`). To author in **degrees**, bind **`rotationDeg`**
+instead — sugar for `rotation = rad(<expr>)`: `rotationDeg = 45`, `rotationDeg = handAngle`.
+
+`x`/`y` are **absolute** — they REPLACE the item's declared `at X,Y`. For motion **around** the anchor,
+bind the additive offsets **`dx`/`dy`** instead: `pos = at + (dx, dy)`, so `dx = 30*sin(clock)` wobbles a
+group `at 620,150` around 620 with no base to re-inject (and `dx`/`dy` add on top of `x`/`y` if both are
+bound). Offsets are binding-only — no keyframe/`spring`/`smooth` form. See the
+[absolute-vs-offset gotcha](dsl-gotchas.md).
+
+`self.x`/`self.y`/… is the item's own current pose; `mouse.x`/`mouse.y` (and `mouse.wheel`, the per-frame
+scroll delta), `time`, `clock`, `frame`, variables and named objects (`Target.x`) are all available — see
+[Expressions](expressions-and-stdlib.md). Prefer **`clock`** (monotone) over `time` (restarts on every
+timeline loop) for free-running motion and for any instant you capture and compare later.
+
+## Drag & drop
+
+```
+object "Piece" {
+  drag px, py                            // follow the pointer, writing into px/py (use them: x = px, y = py)
+  x = px   y = py
+  when dropped on Slot at pointer { placed = 1 }
+}
+```
+
+- `drag x, y` / `dragX x` / `dragY y` — the gesture writes the position into your variables.
+- `{ confine to <Zone> }` clamp · `{ snap <grid> }` pixel-snap · `{ enabled <expr> }` active only while the expression ≠ 0 (a dynamic lock — no ternary needed).
+- ⚠️ **`enabled` gates the GESTURE, not the handlers.** Once it is off the object stops being draggable, but
+  `when pressed` / `when released` / `when clicked` **still fire** on it. Guard the handler body yourself
+  (`when released { if done == 0 { … } }`) whenever it must run only while the gesture is live. (A `link`'s
+  target index is the exception: it resolves to `0` — "no target reached" — on a gated-off release, so it
+  can never hand you the previous gesture's answer.)
+- **Drop zones**: by default the object's **center** is tested against the zone; `at pointer` tests the
+  pointer instead. Define an explicit rectangle with `group "Zone" … hitbox <w> <h> { … }`.
+- Several `when dropped on` per object are evaluated in declaration order (the right-zone / wrong-zones pattern).
+- **`match` sugar** factors the whole drag+drop boilerplate — see [factoring](#reuse--factoring).
+
+## Interactors
+
+Higher-level pointer behaviors (each writes into your variables; all accept `{ enabled <expr> }`):
+
+```
+turn    <angle> around <x>,<y> [{ snap <deg> }]    # dial / clock hand → angle in RADIANS → rotation = angle
+turnDeg <angle> around <x>,<y> [{ snap <deg> }]    # …in DEGREES → rotationDeg = angle  (rotationDeg = sugar for rotation = rad(…))
+trace <progress> along <Group> [{ tolerance <px> }]# follow a path → progress 0..1 (monotone)
+reveal <progress> [{ brush <px> }]                 # scratch/wipe the grabbed area → fraction 0..1 (cumulative across grabs)
+link  <endX>, <endY>, <target> to <Group>          # pull a thread → end follows the pointer; <target> = hit index 1..n on release (0 = none)
+```
+
+Each output also accepts an **array element** (`drag hx[i], hy[i]`, `reveal seen[2]`) — the natural form
+under `each` (see below).
+
+### Drawing the thread of a `link`
+
+`link` gives you the end position and the target index; **the visible wire is yours to draw**. The idiom:
+draw a horizontal bar of a known length, anchored at the source, then rotate and stretch it onto the end.
+
+```
+use "gesture"    // angle(cx, cy, px, py)   → radians
+use "collision"  // dist(ax, ay, bx, by)    → length
+
+scene {
+  layer "Fils" {
+    // A 100 px bar whose LEFT edge sits on the origin → scaling it stretches it away from the anchor.
+    group "Fil" at 120,300 { layer "c" { rect 0 -1 100 2 fill #3355ff } }
+  }
+  layer "Jeu" { group "Src" at 120,300 { layer "c" { circle 0 0 20 fill #3355ff } } }
+}
+
+object "Src" { link ex, ey, hit to Cibles }
+object "Fil" {
+  opacity  = self.grabbed          // only visible while the thread is being pulled
+  rotation = angle(120, 300, ex, ey)
+  scaleX   = dist(120, 300, ex, ey) / 100   // 100 = the bar's DRAWN length
+}
+```
+
+Two things make it work: the bar is drawn **from its own origin** (so `scaleX` stretches the far end, not
+both), and the divisor is the bar's drawn length. With the source at a variable position, replace the
+literals with its coordinates.
+
+## Pointer gestures (drag delta, finger-scroll, tap vs drag)
+
+`mouse.x`/`mouse.y` hold the pointer position inside **any** handler — including `when pressed` /
+`when clicked` / `when released` (the press/release point, on touch too), so you can capture a **grab
+anchor**. A grab **keeps tracking the pointer after it leaves the object** (pointer capture), so a drag is
+never lost at the object's edge.
+
+**Relative drag / finger-scroll** — accumulate the delta from the press anchor (one action per line):
+
+```
+object "List" {
+  when pressed {
+    a = mouse.y
+    base = off
+  }
+  when dragged {
+    off = base + (mouse.y - a)   // `off` scrolls by the finger delta
+  }
+}
+```
+
+**Mouse-wheel scroll** (desktop) — `mouse.wheel` is the wheel delta accumulated **this frame** (0 when the
+wheel is still), read in an `every frame` accumulator — the same idiom as the finger drag:
+
+```
+every frame {
+  off = clamp(off + mouse.wheel, 0, max)   // one notch ≈ tens of px; scale/clamp to taste
+}
+```
+
+The player consumes the wheel (keeps the page from scrolling over the canvas) **only when the scene reads
+`mouse.wheel`** — a scene that ignores it lets the page scroll normally.
+
+**Tap vs drag on the same element.** `when clicked` fires on **release**, and only if the pointer stayed
+put — a press that travels past a few px is a **drag**, not a click. So the *same* element can be both
+tappable and draggable: a tap fires `clicked`, a drag fires `dragged`/the interactor, with **no phantom
+click** when you drag. That's what makes "tap a card to pick it, drag the list to scroll" work on one zone:
+
+```
+object "Card" {
+  when clicked { picked = id }                 // fires on a TAP only
+  when dragged { off = base + (mouse.y - a) }  // a DRAG scrolls — `clicked` does not fire
+}
+```
+
+## Feedback
+
+An object can read **its own interaction state** in channel expressions: `self.hovered`, `self.grabbed`,
+`self.pressed` (each `0`/`1`). So hover-lift and grab-squash are just expressions — no mirror variable,
+no handler:
+
+```
+object "Button" {
+  scaleX  = self.hovered ? 1.06 : 1
+  scaleY  = self.grabbed ? 0.94 : 1
+  opacity = self.hovered ? 0.85 : 1
+}
+```
+
+The **`feedback` one-liner** generates these for you (auto-importing `use "feedback"`), composing per
+channel so it never clashes with your `x`/`y` bindings:
+
+```
+object "Tile" {
+  x = tx   y = ty
+  feedback lift tilt dim shake(wrongZone)   // lift=hover grow · tilt=grab squash · dim=hover opacity · shake=refusal wobble
+}
+```
+
+Or call the [`feedback` stdlib](expressions-and-stdlib.md#stdlib-packages) functions by hand
+(`lift`/`dim`/`tilt`/`sink`/`shake`).
+
+**Timed feedback** (a message/flash that fades over a readable duration) — `pulse(since, dur)` from
+`use "feedback"` is a linear `1→0` ramp over `dur` seconds since the instant `since`. Capture the instant
+in a handler so nothing is hidden:
+
+```
+var shown = -999
+object "Hint" { opacity = pulse(shown, 4) }     // visible 4 s after each trigger, then gone
+object "Piece" { when dropped on Wrong { shown = clock } }
+```
+
+(A multiplicative decay like `v * 0.86` is fine for a quick flash but vanishes before TEXT can be read —
+`pulse` gives a duration you state.)
+
+> ⚠️ **Capture the instant with `clock`, not `time`.** `pulse` and `shake` ride the monotone `clock`
+> precisely because `time` **resets every `durationFrames`** (2.5 s by default). Timed on `time`, a
+> one-shot end-of-game ramp *replays for ever* and a refusal wobble *skips* on every loop — with nothing
+> on screen, and nothing at `--check`, to say so. `--check` now names any function of yours that reads
+> `time` from inside a channel expression.
+
+## Reuse / factoring
+
+Cut repetition with compile-time sugar (all resolved at parse → zero runtime cost):
+
+```
+def gap = 70                              // a compile-time constant (removed at parse), used via $(…)
+scene { layer "L" {
+  repeat i from 0 to 4 { circle $(40 + i*gap) 80 6 fill #ffd98a }   // generate N items; $(expr) interpolates
+} }
+```
+
+**Parameterized symbols** (a reusable visual) + **`each`** (shared behavior):
+
+```
+symbol "Key"(label) { layer "c" { rect -28 -28 56 56 fill #e8e8e8
+  text "$(label)" font "sans-serif" size 24 align center line 1.2 color #111 box 56 56 } }
+
+scene { layer "Pad" {
+  repeat i from 0 to 8 { instance "Key"($(i+1)) as "K$(i)" at $(70 + (i%3)*80),$(80 + floor(i/3)*80) }
+} }
+
+each "Key" as i { when clicked { input = input * 10 + (i + 1) } }   // one handler per generated key
+```
+
+**`match`** — declarative pairing (factors drag+drop for a matching activity):
+
+```
+match Word1, Word2 onto Good, Bad {
+  correct Word1 -> Good, Word2 -> Bad
+  on correct as it { send "found", text(it) }
+  on done { send "win" }
+}
+```
+
+It generates, per item, `<Item>_placed` / `<Item>_ok` / `<Item>_zone` state and the drag+drop handlers;
+you keep the visual (`var <Item>_x`/`_y` + your channel expressions).
+
+## See also
+
+- The expression language and stdlib → **[Expressions & stdlib](expressions-and-stdlib.md)**
+- Receive `send` events / drive variables from the page → **[Host integration](host-integration.md)**
+- Test interactions headlessly (gesture scripts, `scratch`/`connect`) → **[Tooling](tooling.md)**
+- Pitfalls (event order, monotone reveal, `$()` in `each`…) → **[Gotchas](dsl-gotchas.md)**