@flatkit/compiler 0.26.0 → 0.28.0

package/docs/dsl-gotchas.md

@@ -0,0 +1,428 @@
+# FlatInk DSL — gotchas & best practices (appendix)
+
+> **New here?** Start with the [documentation index](README.md) and the
+> [getting-started guide](getting-started.md). This page is the **appendix**: hard-won pitfalls and
+> sharp edges learned on a real production pipeline, then fixed in the engine or written down here.
+> Skim it once you know the basics.
+
+## Mental model
+
+- A `.flatink` file splits in two: the **`scene { … }`** block (the VISUAL composition:
+  `path`/`circle`/`group`/`image`/`text`) and the **behavior** that follows (`object "Name"
+  { … }`, `every frame`, timeline bindings). The two do NOT share the same grammar.
+
+## `object "X"` addresses an ANIMATABLE item — a group, instance, text or image
+
+- A **shape is baked material**: `rect 0 0 960 540 as "Eclat"` names it so `text … along "Eclat"` can
+  find it, but it carries **no pose**, so it can never be animated. Same for a **layer**. An `object`
+  block on either used to be dropped in **total silence** — the program compiled, ran, and the animation
+  simply did not exist. It is now a **compile error** naming what you actually hit. To animate a shape,
+  wrap it: `group "Eclat" { layer "art" { rect … } }`.
+- Corollary — **opacities multiply**. Setting `opacity 0` on the shape to hide it at rest cancels the
+  group's animation even when the group lights up. Drive the *group's* opacity and leave the shape at 1.
+
+## One action / one binding per line
+
+- **Comments are `//`, never `#`.** `#` starts a COLOR (`#ffcc00`), so a `# note` inside a program is a
+  parse error, not a comment. (Reference listings in these docs annotate with `#`; runnable examples use `//`.)
+- **One single action or assignment per line.** `x = 1  y = 2` raises a clear error
+  ("one action per line — unexpected `=`"), with the column pointing at the second `=`.
+  A swallowed statement is named now — `score = score + 1  send "ok", 1` reports *"two statements on one
+  line — `send …` was swallowed into the expression before it"*, not `unexpected character """`.
+- **`send` footgun (fixed)**: `send "evt", x = 1` (with a comma) used to capture `x = 1` as
+  the *payload*. It is now a dedicated error. A `send` carries at most one payload:
+  `send "evt"`, `send "evt", <expr>`, `send "evt", text("textId")`, or the record form
+  `send "evt", { a = <expr>, b }` — several *named* values in ONE event, not several payloads.
+  Inside a record the same rule holds: `{ x = y = 1 }` is the same error.
+
+## Drawing (region / path)
+
+- **`stroke` DOES exist on paths** (despite the folklore):
+  `path "…" fill #rrggbb stroke #rrggbb <width> [cap butt|round|square] [join …] [miter n] [dash a,b,…]`.
+  No need to draw ropes/threads as thin filled shapes.
+- **`stroke` ALSO exists on text** (same grammar): `text "…" color #fff stroke #000 4 join round` outlines
+  the glyphs (stroke drawn behind the fill). No need to fake outlines by stacking two text objects.
+- **`opacity` DOES exist on paths**: `path "…" fill #000 opacity 0.5`. (8-digit hex alpha
+  works too, but `opacity` reads better.)
+- **Shape primitives** (sugar, normalized to `path` on save):
+  - `circle <cx> <cy> <r>`
+  - `ellipse <cx> <cy> <rx> <ry>`
+  - `rect <x> <y> <w> <h>` · `… <r>` (uniform rounded corners) · `… <rx> <ry>`
+  No more hand-computing the k = 0.5523·r Bézier constant.
+- **`filter` on a path**: accepted (`path "…" fill #000 filter glow 6 #fff`). No need to wrap
+  in a `group` just to add a shadow/glow. (Also works on group/image/text.)
+- **`linear(angle, …)` gradient**: `0` = → (left to right), `90` = ↓ (top to bottom).
+- **Rings / holes = ONE path with multiple closed subpaths** — fill is **even-odd**, so a nested subpath
+  cuts a hole: `path "M-30 -30L30 -30L30 30L-30 30Z M-15 -15L15 -15L15 15L-15 15Z" fill #c33` is a solid
+  filled ring (frame + hole). No need to fake it with `nofill stroke`.
+- **Stroke width SCALES with the group**: a child of a `group`/instance at `scale 0.4` (or a `pose scale`)
+  draws its stroke at 0.4× too (the stroke is drawn in the scaled space). So a thin ring stays
+  proportional when you shrink the group — don't compensate the width by hand.
+- **`clip <x> <y> <w> <h>` on a group/instance**: cuts content to a rectangle (the container's LOCAL
+  coords) — e.g. hide the "feet" of an emerging shape: `group "Arc" clip -100 -60 200 60 { … }`. For an
+  arbitrary clip shape, use a `mask` layer instead. **Render-only**: hit-testing and the preview/auto-size
+  bbox ignore it (clipped-away area stays clickable / counts toward the framing) — it's a visual cut.
+
+## Text
+
+- **Word-wrap**: opt-in via `wrap`. `text "long sentence…" … box <W> <H> wrap` breaks at
+  spaces within `W`. Without `wrap`, text does NOT wrap on its own (it respects explicit
+  `\n`). Opt-in on purpose, to avoid breaking existing layouts.
+- **Dynamic text (read-only)**: `text "Angle: {}°" … bind "round(aDeg)" decimals 1`. The
+  expression is evaluated every frame; its formatted value fills the **`{}`** slot in the
+  content (or is shown alone when there is no `{}`). `decimals` sets the decimal count.
+  No more gauges/needles just to display a measurement (angle, timer, score…).
+- **Centering an `image`**: the origin is the top-left corner → center with `at -W/2,-H/2`.
+
+## Animation (pose / cel / timeline)
+
+> Full guide: **[Animating a symbol](animating-symbols.md)**. The sharp edges:
+
+- **`pose` rotates/scales in human units**: `pose "G" rotate 90 scale 2` — **degrees** and multipliers,
+  **around the group's `pivot`**. No hand-written `matrix(cosθ, sinθ, …)`, no radians. `scaleX`/`scaleY`
+  for non-uniform. `matrix(…)` still works as an escape hatch.
+- **A pose only overrides what it states** (patch, not replace): `pose "G" opacity 0.5` keeps G's
+  declared position/rotation/scale. Don't re-type `at x,y` in every cel.
+- **Set the `pivot` to the visual center** or a part **orbits** instead of spinning in place. `pivot`
+  (local, on the roster item) = the center of rotation/scale; `at x,y` (on the pose) = where the local
+  origin lands. `spin cw|ccw` / `turns N` also turn around the pivot.
+- **`expr rotation` is in RADIANS**, like `sin`/`cos`. Stay in degrees with the helpers: `rad(45)`,
+  `turns(time)` (one turn per second), `deg(r)`. e.g. `expr rotation "turns(time * 0.5)"`.
+- **`time` WRAPS at `durationFrames`** (the timeline loops), so `sin(time * f)` with an arbitrary `f`
+  **jumps** every loop — and a `.flatink` with no `timeline` defaults to **60 frames (2.5 s @24fps)**, so
+  the jump is frequent. For free-running ambiance use **`clock`** (monotone, never wraps): `sin(clock * f)`.
+  Alternatively drive it by the loop phase `frame / <durationFrames>` (reboucles cleanly) or set a long
+  `timeline`. `--check` warns when a channel expression uses `time` under a short looping timeline.
+- **`x`/`y` channels REPLACE the base transform — they are NOT a delta.** `object "G" { x = bump }` sets
+  G's local x to `bump`, **overwriting** the group's declared `at X,Y` (x snaps to `bump` ≈ 0 → the element
+  jumps to the left edge whenever the expression is small). The channel value is absolute, not added to `at` —
+  classic cause of "the animation appears in the wrong place." Two ways to keep it on the anchor:
+  - **Preferred — additive offsets `dx`/`dy`** (binding-only): `object "G" { dx = bump }` resolves to
+    `pos = at + (dx, dy)`, so `dx = 58*sin(clock)` oscillates **around** `at X,Y` with no base to re-type.
+    This is the natural "offset from the anchor" idiom (mirror of CSS `translate` / pivot). `dx`/`dy` compose
+    with an absolute `x`/`y` if both are bound (`pos = x + dx`); they have no keyframe/`spring`/`smooth` form.
+  - **Or re-inject the base** with the absolute channel: `x = $(X) + bump` (same for `y`/`rotation`/`scaleX`/…).
+- **Channel `scaleX`/`scaleY`/`rotation` turn around the group's `pivot`** (like cel poses), so a panel
+  with `pivot <center>` driven by `object "P" { scaleX = s }` grows/spins **in place** — it no longer
+  shrinks toward the top-left corner. With no `pivot` (default `{0,0}`) it scales/rotates around the origin
+  as before. When a `pivot` is set, the `x`/`y` channels position **the pivot** (the object's anchor).
+- **A layer WITH cels draws ONLY the cel's `matter` + the containers that cel poses.** A bare shape
+  written straight into such a layer is **silently never drawn** (it stays in the roster, which holds
+  bodies, not drawings). The drawing of a frame goes inside the cel: `cel 0 { matter { circle 0 0 30
+  fill #e33 } }` — that IS how you author **frame-by-frame** (a new `matter` per cel; it holds until the
+  next one, `morph` tweens the shape). A static element belongs on a **cel-less layer**. `--check` warns
+  on all three silent drops: a bare shape in a cel layer, a `pose "X"` matching no roster item, and a
+  roster item no cel poses. See [Animating a symbol](animating-symbols.md).
+- **Render order**: in an animated layer the **matter draws BEHIND the posed containers**, and
+  declaration order between the matter and an animated `group` is NOT preserved. To put a static
+  shape in front of an animation, give it its own **layer above** (or wrap it in a group).
+- **Gating a subtree by opacity is FREE**: a group whose resolved `opacity` is `<= 0.01` (e.g. the
+  off-phase branch of `opacity = phase == X ? 1 : 0`, even when smoothed toward ~0) is **pruned** — its
+  whole subtree is skipped for both draw AND expression eval, exactly like the hit-test already treats it
+  as click-through. So `opacity = phase==X ? 1 : 0` on the phase groups is the idiomatic, performant way to
+  show/hide whole acts; you don't need `visible`/`hidden` (which aren't animatable anyway).
+- **Preview without clipping**: `flatc --preview` defaults to `--bbox all` (union over every frame, so
+  drifting/rotating/growing motion fits). `--bbox frame0` is the old frame-0 measure; `--pad N` adds a
+  margin.
+- **Preview origin is STABLE across frames**: the canvas is auto-sized once (the union), independent of
+  `--frame`. So rendering several frames of an oscillating/translating symbol gives the SAME frame each
+  time — the object moves *inside* a fixed canvas, it does not "jump". No need for an invisible anchor.
+- **Exposed interface** (`params {}` / `states {}`): a symbol can publish typed params (color/number/bool,
+  `fill <param>`) and named states (`states door { closed at 0 open at 24 }`, driven by `Name.param = open`).
+  See [Animating a symbol](animating-symbols.md). Restyle/tune without touching internals.
+- **A container shows only on cels that pose it** — a cel is a full snapshot, so a container omitted from a
+  cel disappears there (that's how a symbol *exits*). For a container that stays put: declare it on its own
+  **cel-less layer** (always shown, declared once), or use **`cel N hold { … }`** to carry the previous
+  cel's poses forward (compile-time sugar — you only write what changes). It's per-*keyframe*, not per-frame.
+- **`--preview --set` bakes the values into the flatpack** (onto the wrapped instance's `params`), so a
+  pre-themed `.flatpack` plays correctly in the browser too — provided the player bundle is current (a
+  stale bundle won't resolve `fill <param>` → black; rebuild after a `@flatkit/*` bump).
+
+## Drag & drop
+
+- **Drop semantics**: by default the **object's center** (its x/y channels) is tested against
+  the zone. Two levers to match human expectations:
+  - `when dropped on Zone at pointer { … }`: tests the **POINTER position** (not the center).
+  - `group "Zone" … hitbox <W> <H> { … }`: an **explicit drop rectangle** (centered on the
+    origin, ±W/2 × ±H/2) instead of the content bbox. Replaces invisible `#ffffff01` paths.
+- **Locking a placed object**: `drag x, y { enabled <expr> }`. The drag is active only while
+  the expression is ≠ 0. No more `x = (p==1) ? Zone.x : xv` + `if p==0` guard patterns.
+- **Event order on release**: `when released` fires **BEFORE** the drop test (useful to lower a
+  "hold" flag before the drop fires). A `link` interactor writes its outputs (`<target>` index,
+  end position) **before** `released` too, so a `when released` handler can read `<target>`
+  directly (consistent with `drag`, which writes its vars before `dragged`).
+- **Several `when dropped on` per object**: evaluated in **declaration order**, without
+  short-circuit (the basis of the right-zone / wrong-zones pattern).
+
+## Gestures beyond drag (interactors)
+
+Inside an `object "Name" { … }`, besides `drag x, y` / `dragX` / `dragY`:
+
+- **`turn <angle> around <x>,<y> [{ snap <deg> · enabled <expr> }]`**: pointer-driven
+  rotation. Writes into `<angle>` the pivot→cursor direction **in radians** (like the `rotation` channel
+  and `gesture.angle`), so `rotation = <angle>` wires directly. To work in **degrees**, use the twin
+  **`turnDeg`** (writes degrees) paired with the **`rotationDeg = <angle>`** channel (sugar for
+  `rotation = rad(<angle>)`). `snap <deg>` is authored in degrees on both. Great for clock hands, dials, knobs.
+- **`trace <progress> along <TraceGroup> [{ tolerance <px> · enabled <expr> }]`**: follow a
+  path with the finger. While the pointer stays within `tolerance` of the trace (the regions
+  of the named group), `<progress>` rises from 0 to 1 (monotone, never goes back down).
+  Great for tracing a letter, a border, a constellation. (`tolerance` defaults to 24 px.)
+- **`reveal <progress> [{ brush <px> · enabled <expr> }]`**: scratch / wipe. The grabbed
+  object IS the area to reveal; rubbing it ticks the cells of an internal grid (cell side =
+  `brush`) and `<progress>` rises from 0 to 1 (monotone, and **cumulative across separate grabs**
+  — a child rubbing in several short strokes keeps adding coverage, it does not reset). Drive a
+  cover's opacity with `opacity = 1 - <progress>`. Great for scratch cards, fogged glass, digging.
+  (`brush` defaults to 24 px; coverage model, no pixel mask.)
+- **`link <endX>, <endY>, <target> to <TargetsGroup> [{ enabled <expr> }]`**: pull an elastic
+  thread toward a target. During the drag, `<endX>`/`<endY>` = pointer position (DRAW the
+  thread yourself with expressions, e.g. a region connecting the object to `endX,endY`). On
+  release, `<target>` = the **1..n** index of the named child of the group that was hit
+  (0 if none), and the thread end snaps to the linked target's center; off-target, the
+  author handles the "return" via `<target> == 0`. Several links coexist: one `link`
+  interactor per source object. Great for word↔image, prey↔predator, capital↔country.
+  **WORLD coords** (place sources and targets at the scene root so the thread lines up).
+- Reminder: `{ enabled <expr> }` (dynamic lock) works on `turn`/`trace`/`reveal`/`link` too.
+- **Output into an ARRAY element**: every gesture output accepts `name[<idx>]` (not just a
+  bare identifier) — `drag hx[i], hy[i]`, `turn ang[k] around …`, `reveal seen[2]`,
+  `link ex[i], ey[i], rel[i] to …`. This is the natural form **under `each`**:
+  `each "Handle" as i { drag hx[i], hy[i] }` attaches one drag per instance, each writing its
+  OWN slot. (The index is substituted by `each`; the array must exist: `var hx = fill(n, 0)`.)
+
+## Feedback (reactions in one line)
+
+An object's channel expressions can read **its own interaction state**: `self.hovered`,
+`self.grabbed`, `self.pressed` (each `0`/`1`). So a hover-lift or a grab-squash is just an
+expression — no mirror variable, no handler:
+
+```
+object "Button" {
+  scaleX  = self.hovered ? 1.06 : 1
+  opacity = self.hovered ? 0.85 : 1
+  scaleY  = self.grabbed ? 0.94 : 1
+}
+```
+
+`self.hovered` tracks the pointer **handler-independently** (you do not need a `when enter/leave`),
+and composes with `self.x`/`self.y` etc. (same `self`).
+
+- **`feedback <tokens>` sugar** — the one-liner. Inside an `object` block,
+  `feedback lift tilt dim shake(<expr>)` unfolds into the channel bindings above (auto-injecting
+  `use "feedback"`), **composed per channel** so it never clashes with your `x`/`y` position
+  bindings. Tokens: `lift` (hover grow), `tilt` (grab squash), `dim` (hover opacity),
+  `shake(<expr>)` (refusal wobble — `<expr> ≠ 0` shakes the `rotation`). One line per element
+  instead of six — the biggest size/token saver across an activity.
+  ```
+  object "Tile" {
+    x = tx   y = ty                 // your position bindings, untouched
+    feedback lift dim shake(wrongZone)
+  }
+  ```
+- **`use "feedback"` functions** — the same reactions as plain helpers if you want to wire them by
+  hand: `lift(h)` · `dim(h)` · `tilt(g)` · `sink(g)` · `shake(bad, t)`. (Settle-bounce is not here
+  yet: it needs a release timestamp, so it is not stateless.)
+- ⚠️ **Capture an instant with `clock`, never `time`.** `pulse`/`shake` ride the monotone `clock`, so
+  an instant captured on the looping `time` is compared against an axis it never shares: `clock - since`
+  grows without bound and **the ramp never fires**. Nothing jumps, nothing blinks — the failure is
+  entirely silent, which makes it far more expensive than a visible one. It is the classic leftover of
+  a pre-0.23 codebase, where `pulse` rode `time` too.
+  ```
+  when wrong { shown = clock }        // ✓  monotone — pulse can subtract it
+  when wrong { shown = time }         // ✗  wraps every durationFrames — the ramp never starts
+  opacity = pulse(shown, 4)
+  ```
+  `flatc --check` now names it: *"shown" is captured on `time` but read as an INSTANT by `pulse()`…*
+
+## Factoring
+
+- **Scene-level `repeat`**: generates N items.
+  ```
+  scene {
+    layer "Stars" {
+      repeat i from 0 to 9 {
+        circle $(60 + i*40) 80 6 fill #ffd98a
+      }
+    }
+  }
+  ```
+  The index is used inside numbers via the **`$(expr)`** interpolation (compile-time
+  arithmetic: `$(i*40)`, `$( (i+1)*20 )`…). Nested loops are fine (grids).
+  ⚠️ Not to be confused with `repeat … times` / `repeat i from … to …` inside `object`
+  scripts (a RUNTIME loop, executed every frame).
+- **`def <name> = <expr>`**: a named **compile-time** constant (columns, margins, counts…).
+  Declared anywhere (the line is removed at compile time), usable in any scene coordinate via
+  `$()`, including `repeat` bounds. A `def` may reference earlier ones.
+  ```
+  def colL = 120
+  def gap  = 40
+  def n    = 2
+  scene { layer "L" {
+    repeat i from 0 to n { circle $(colL + i*gap) 80 6 fill #ffd98a }
+  } }
+  ```
+  `def`s resolve **everywhere**: scene coordinates AND behavior expressions (`object`/`each`,
+  e.g. `x = 20 + t * $(vmax)`). ⚠️ Compile-time only: `def`s are NOT runtime variables (no
+  `var`), they vanish from the model (like `repeat`); for a value that changes at runtime,
+  use `var`. (Avoid naming a `def` like a symbol parameter — collision.)
+- **`at center` anchor**: positions an item at the canvas center. `at center` (both axes),
+  `at center,540` (x centered, y = 540), `at 120,center` (x = 120, y centered). Sugar
+  resolved at parse from `size` (re-serialized as coords, like `def`). Composes with `$()`.
+- **`align <point> of "Name" [offset dx,dy]` anchor**: puts an item's **origin** on a point
+  of **another item's bbox** (center inside a frame, hang a counter under a pit, snap a sign
+  to an edge). 9 points: `center`, `top`, `bottom`, `left`, `right`, `topleft`, `topright`,
+  `bottomleft`, `bottomright` (an edge point = centered on the cross axis). Optional
+  `offset dx,dy`.
+  ```
+  group "Counter" align bottom of "Pit" offset 0,18 { … }
+  group "Tag" align top of "Bin" { … }
+  ```
+  ⚠️ **STATIC bbox** (scene transforms, WITHOUT expression channels — same as drop zones).
+  Anchoring only (NO adjacency/flow: deliberate — stacking is done with `repeat`+`$()`,
+  e.g. `at $(120 + i*84),540`). Positions in **root** space (place source and target at the
+  same level). Missing target = error. Sugar resolved at parse (re-serialized as coords).
+- **Parameterized symbols**: `symbol "Name"(p, q = default) { … }` + `instance "Name"(args)
+  [as "X"] at x,y`. Reuse a VISUAL while varying values (label, tint, size). `$(param)`
+  substitution in the body — params can be **numbers AND text/color** (`text "$(label)"`,
+  `fill $(tint)`).
+  ```
+  symbol "Card"(label, tint = "#ffffff") {
+    layer "c" { rect -40 -40 80 80 fill $(tint)
+                text "$(label)" as "lbl$(label)" font "sans-serif" size 20 align center line 1.2 color #000 box 80 80 }
+  }
+  scene { layer "L" {
+    repeat i from 0 to 4 { instance "Card"($(i+1)) as "C$(i)" at $(80 + i*90),200 }
+  } }
+  ```
+  - **Defaults**: a param can gain a default without breaking existing calls (the signature
+    doubles as documentation).
+  - **Per-instance ids**: `as "lbl$(label)"` in the body → each card exposes its own
+    `text("lblFire")` for `send` payloads.
+  - Each `instance(...)` becomes a concrete **`group`** (substitution at PARSE time, **zero
+    runtime cost**).
+  - ⚠️ A param is **frozen** (≠ `var`: it is not a runtime variable). The body sees ONLY its
+    params (not the `i` of an outer `repeat` — pass it as an argument). Wrong arity / unknown
+    param = error.
+  - ⚠️ Compile-time sugar (re-serialized as groups, like `def`/`repeat`). For shared
+    BEHAVIOR, see `each` below.
+  - ⚠️ **`.flatink`-only**: a parameterized `symbol "X"(…)` lives in the **program** (`.flatink`), NOT in a
+    `.flat` library. `.flat` libs hold **non-parameterized** symbols, instanced **without** parens
+    (`instance "Hero" as "H"`); a parameterized one is instanced **with** args (`instance "Card"("A")`).
+    Putting a `(…)` symbol in a `.flat` — or letting `flatc` auto-discover such a `.flat` in the folder —
+    surfaces as a misleading `"{" expected, "("` (the `.flat` parser doesn't take parameters). Rule of
+    thumb: parens ⇔ parameterized ⇔ inline in the `.flatink`.
+- **`each "Symbol" as i { … }`**: applies BEHAVIOR to every instance of a symbol, with
+  index `i`.
+  - **Channel bindings** on real instances (`each "Brick" as i { opacity = bricks[i] }`) →
+    resolved at runtime (`vals[i]`, variable arrays).
+  - **Handlers** on the instances of a **parameterized symbol** (`each "Key" as i { when
+    clicked { … } }`) → unrolled at parse into one `object` per generated instance (index `i`
+    substituted). The BEHAVIOR counterpart of parameterized symbols (the VISUAL): together
+    they make a full keypad in ~10 lines.
+    ⚠️ Give instances distinct names (`as "K$(i)"`) so each handler targets ITS tile.
+- **Indexed assignment**: `arr[<expr>] = <value>` (the `set` keyword is optional). The index
+  can be any expression, **including nested**: `occ[sl[i + 1]] = 0` works (balanced
+  brackets). An unclosed bracket is a **hard error** (no more silent truncation).
+- **`else if`**: supported (`} else if cond {`); no need to nest `else { if … }`.
+- **`match` — declarative pairing** (factors the drag+drop boilerplate). Unrolled into
+  `object` blocks.
+  ```
+  match Word1, Word2, Word3 onto NounBin, VerbBin, AdjBin {
+    correct Word1 -> NounBin, Word2 -> VerbBin, Word3 -> AdjBin
+    lock on wrong                                  // optional; absent = RETRYABLE (default)
+    on correct as it { send "found", text(it) }    // optional GENERIC action hooks
+    on wrong   as it { send "miss" }               // `it` = the current item's name
+    on done            { send "done" }             // fires when all correct placements are in
+  }
+  ```
+  Generates, per item: `drag <Item>_x, <Item>_y { enabled <Item>_placed == 0 }` + one
+  `dropped on` per zone that sets the **exposed state**: `<Item>_placed` (0/1), `<Item>_ok`
+  (0/1), `<Item>_zone` (index). **No event is imposed** (full host decoupling) — you decide
+  what to send via the hooks. The **visual stays yours**: declare `var <Item>_x`/`var
+  <Item>_y` (start positions) and write your expressions.
+
+## Tooling (the generation loop)
+
+- **`flatc --check <file>`**: semantic lint only. Exits ≠ 0 on ERROR; **warnings** print
+  without blocking. Also covers **layout** (approximate, no rendering): text (without `wrap`)
+  overflowing the canvas edge, image/text clipped at an edge, missing drop zone,
+  **overlapping hitboxes**, never-used global variable.
+- **`flatc --watch <file>`**: recompiles on every change in the folder.
+- **`flatc --render <file> -o out.png [--frame N] [--at k=v[,k2=v2]] [--steps N] [--scale S]`**:
+  renders a headless **PNG image** (skia backend, faithful to the browser: SVG, gradients,
+  glow/shadow filters). This is how you **see what you draw** before playing. `--at` forces
+  variables → capture a precise state (e.g. `--at step=2` for an escape-room stage); `--frame N`
+  targets a frame. **`--steps N`** runs N fixed simulation steps (`every frame`, 60 Hz) *before*
+  the capture, so a stateful act unfolds on its own — no need to force every derived ramp variable
+  by hand in `--at`. (Bounded to 10 000 steps.) Requires the optional `skia-canvas` dependency
+  (see the error message for the install steps).
+- **`flatc --assets inline|external <file>`**: how media is baked. `inline` (default) embeds each
+  asset as a base64 `data:` URI inside the `.flatpack` — one portable file. `external` keeps
+  `asset.data` as a relative key and copies the files into a sidecar `<out>.assets/` folder; serve
+  that folder and play with `sameOriginAssetResolver(<flatpackUrl>)`. Use `external` for big media
+  (video, large audio) you do not want inflating the JSON.
+- **`flatc --play <file.flatink|.flatpack> --script <gestures.json>`**: plays **headless**
+  (no canvas), replays a gesture script and prints `{ sends, vars }` as JSON. Great in CI.
+  Script format: an array of gestures. **Prefer SEMANTIC gestures** (by object NAME) —
+  robust (coordinate-independent), readable, and the engine resolves the position:
+  ```json
+  [
+    { "type": "drag",    "source": "Card1", "target": "ZoneA" },
+    { "type": "wait",    "frames": 30 },
+    { "type": "tap",     "target": "Button" },
+    { "type": "scratch", "target": "Cover1" },
+    { "type": "connect", "source": "Word", "target": "Picture" }
+  ]
+  ```
+  `drag source→target` = the engine grabs `source` (at its RESOLVED position, expressions
+  included) and releases it at the center of `target`; `tap target` = a click at the object's
+  center; **`scratch target`** = the engine sweeps the `reveal` target's whole bbox for you
+  (boustrophedon at the brush spacing) so its coverage reaches ~1 — no more dozens of hand-typed
+  `move`s; **`connect source→target`** = pulls a `link` wire from `source` and releases over
+  `target`, resolving the target index. Unknown object → **hard error** (not a silent miss). The
+  generator describes the INTENT; the engine guarantees the interaction.
+  LOW-LEVEL gestures (scene coords) remain available for special cases:
+  ```json
+  [
+    { "type": "down", "x": 50, "y": 50 }, { "type": "move", "x": 60, "y": 60 }, { "type": "up", "x": 60, "y": 60 },
+    { "type": "set",  "name": "unlocked", "value": 1 }, { "type": "wait", "frames": 60 }
+  ]
+  ```
+  (`set` drives a variable from the "host"; `wait` lets the simulation run N fixed 60 Hz
+  steps — required to "wait out" `every frame` physics, time does not advance on its own in
+  headless mode.)
+- **`flatc --play … --trace`**: instead of the final JSON, a **human-readable log per
+  gesture** — the emitted `send`s + the **variable diff** at each step. Step-by-step
+  inspection to understand/debug a script (a headless debug-player):
+  ```
+  drag Word1→Bin1   sends:[found]          vars{Word1_placed:undefined→1 Word1_ok:undefined→1}
+  wait 5
+  drag Word2→Bin2   sends:[found, win]     vars{Word2_placed:undefined→1 Word2_ok:undefined→1}
+  ```
+- **`expect` — self-verification in CI**: a gesture `{ "type": "expect", "sends": ["done"],
+  "vars": { "score": 3 } }` in the script compares and makes **`flatc --play` exit ≠ 0** on
+  mismatch (each mismatch listed on stderr). `sends` = the **sequence of names** emitted
+  SINCE the last `expect`; `vars` = current state. No more eyeballing: the script becomes a
+  test. Works with or without `--trace`.
+- **Gesture recording**: `player.startRecording()` / `stopRecording(): Gesture[]` capture
+  gestures played BY HAND (down/up/cancel + the `move`s during a drag, with `wait`s for
+  elapsed time) → a script **directly replayable by `--play`**. No more hand-written coords.
+- **Canonical file name**: `.flatpack` (JSON inside; `.flatpack.json` is a legacy alias that
+  `--play` tolerates).
+
+## `filter` performance
+
+- A `filter glow`/`shadow` = **one offscreen canvas recomposited** per group carrying the
+  filter. The engine automatically **caches** *static* filtered subtrees (decor with no
+  expression or animation): they are only re-rendered on zoom/pan or asset load. So a filter
+  on **static decor** is nearly free in steady state.
+- A filter on an **animated** element (channel expression, `bind`, timeline) is recomposited
+  every frame. Keep filters on animated elements **small**.
+- Cheap alternative for decor shadows: a **"baked" shadow** = the same path offset by a few
+  px in `#00000028` UNDER the cutout (no offscreen canvas). Ideal for large planes.
+- Drop-shadow cost ∝ area × blur: a large blurred plane is expensive when not cached.
+
+## Audio
+
+- `sound "assetId" at <frame> [gain <g>] [loop]` on the timeline, and the `sound "assetId"`
+  action in a handler, ARE wired (WebAudio). Declare the asset like images:
+  `asset "ding" "ding.mp3" sound`. Media (mp3/wav/ogg/m4a) are embedded as data URIs by
+  `flatc`. (No sample sounds ship for now — bring your own.)

package/docs/embedding-fonts.md

@@ -0,0 +1,95 @@
+# Embedding the player: loading embedded fonts
+
+A `.flatink` can **embed its fonts** so a deck is self-contained:
+
+```
+asset "Archivo Black" "ArchivoBlack.woff2" font
+scene { layer "L" { text "Déçu où ? ÇÀ" at 20,40 font "Archivo Black" size 48 } }
+```
+
+`flatc` inlines the face into the compiled doc as a base64 data-URI:
+
+```jsonc
+// doc.assets
+[{ "id": "Archivo Black", "kind": "font", "mime": "font/woff2",
+   "data": "data:font/woff2;base64,…", "family": "Archivo Black" }]
+```
+
+## The host owns font loading
+
+`FlatPlayer` draws text with `ctx.font = "<family>"` on the canvas it was given. It does **not** register
+the doc's `kind:'font'` assets itself — loading a face is environment-specific (a browser `FontFace`, a
+skia `FontLibrary`, …) and asynchronous, while the player's render is synchronous. So **the host that embeds
+the player is responsible for registering the embedded fonts before rendering.** Skip this and text silently
+falls back to a system font.
+
+> The `family` to register is **`asset.family || asset.id`** — it's exactly what the text targets via
+> `font "<…>"`. Wrap loading in `try/catch`: a corrupt face should degrade to a fallback, never crash.
+
+### Browser (`<canvas>`)
+
+`@flatkit/player` exports the helper — `import` it, no need to reimplement:
+
+```js
+import { FlatPlayer, loadEmbeddedFonts } from '@flatkit/player'
+
+await loadEmbeddedFonts(doc) //            ← BEFORE new FlatPlayer
+const player = new FlatPlayer(canvas, doc)
+
+// Optional safety net (FOIT): redraw once any late face settles.
+document.fonts?.ready.then(() => player.render())
+```
+
+`loadEmbeddedFonts(doc)` registers each `asset kind:'font'` (base64 data-URI) as a `FontFace` under
+`asset.family || asset.id`, **no-ops outside a DOM** (SSR / Node), and **skips a corrupt face** (graceful
+fallback, never throws). It's a tiny tree-shakeable export — it pulls in no extra dependency (uses the
+browser's own `FontFace` / `document.fonts`). Calling it again (e.g. a remount) is harmless: a family
+already on `document.fonts` is not re-registered.
+
+> **Security.** Only embedded `data:` URIs are honored, and the bytes are decoded and handed to `FontFace`
+> directly — `asset.data` is never spliced into a CSS `src` string. So an untrusted doc can neither point a
+> face at a remote origin (no network fetch) nor inject extra CSS `src` descriptors via `url()`/`local()`.
+> This is the same "no arbitrary fetch" contract the player's image/audio paths enforce.
+
+### Node / headless (`skia-canvas`)
+
+`FontLibrary` reads **file** paths, so materialize each base64 data-URI to a temp file, then register it.
+
+```js
+import { FlatPlayer } from '@flatkit/player'
+import { FontLibrary } from 'skia-canvas'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+function useEmbeddedFonts(doc) {
+  for (const a of doc.assets ?? []) {
+    if (a.kind !== 'font' || !/^data:[^;]*;base64,/.test(a.data ?? '')) continue
+    const base64 = a.data.slice(a.data.indexOf(',') + 1)
+    const ext = (a.mime || '').includes('woff2') ? 'woff2' : (a.mime || '').includes('woff') ? 'woff' : 'ttf'
+    const file = join(mkdtempSync(join(tmpdir(), 'fk-fonts-')), `${(a.family || a.id).replace(/[^a-z0-9]+/gi, '_')}.${ext}`)
+    writeFileSync(file, Buffer.from(base64, 'base64'))
+    try {
+      FontLibrary.use(a.family || a.id, [file]) // 2-arg form forces the family alias
+    } catch {
+      /* invalid font → fallback */
+    }
+  }
+}
+
+useEmbeddedFonts(doc) //                    ← BEFORE the first render
+const player = new FlatPlayer(canvasEl, doc, { input: false, audio: false })
+```
+
+`FontLibrary` is a **global, idempotent** registry for the process — registering the same family twice is
+harmless (you may memoize by family to avoid re-writing temp files).
+
+## What's already handled for you
+
+- **`flatc --render`** (the CLI, used for preview/OG images) registers embedded fonts **internally** before
+  drawing — CLI users and render pipelines get correct text for free. The host glue above is only needed when
+  you drive `@flatkit/player` **directly**.
+
+- The **browser** path ships as `loadEmbeddedFonts` (exported above). The **skia/Node** path stays a snippet:
+  it would drag the optional `skia-canvas` dependency into the package, so it's left to the host (and the
+  `flatc --render` CLI already covers headless rendering).

package/docs/expressions-and-stdlib.md

@@ -0,0 +1,107 @@
+# Expressions & stdlib
+
+Expressions appear in channel bindings (`rotation = …`), conditions (`if …`, `enabled …`), `send`
+payloads, `bind` text, text-on-path `start`/`spacing` (`text … along "…" start "time*0.1"`), and `$()`
+interpolation. They are **pure and numeric** — no statements, no loops, no side effects (so they can't
+hang and only touch the values the runtime provides).
+
+## Operators
+
+From lowest to highest precedence:
+
+```
+?:            ternary          a > 0 ? 1 : -1
+|| &&         logical
+== != < > <= >=   comparison    (a value ≠ 0 is "true")
++ - * / %     arithmetic
+- !           unary
+. []          member / index    mouse.x · slots[i]
+fn(…)         call
+```
+
+There are no booleans — comparisons and logic yield `1` / `0`.
+
+## Built-in functions
+
+```
+sin cos tan  asin acos atan atan2
+abs sqrt pow exp log  floor ceil round sign
+min max  hypot  clamp(x, lo, hi)  lerp(a, b, t)  mod(a, b)  between(x, lo, hi)
+rad(deg)  deg(rad)  turns(n)
+```
+
+Constants: `PI`, `TAU` (2π), `E`.
+
+> **`lerp` is the exponential smoother.** `lerp(v, target, k)` = `v + (target - v) * k` — so
+> `niv = lerp(niv, target, 0.1)` in `every frame` eases `niv` toward `target` (no new helper needed; the
+> target and rate stay explicit). For a timed 1→0 feedback ramp, see `pulse(since, dur)` in `use "feedback"`.
+
+**Angles are RADIANS** (the `rotation` channel, `sin`/`cos`/`atan2`). Author in degrees with the helpers:
+`rad(45)` (degrees → radians), `turns(n)` (n full turns → radians, e.g. `rotation = turns(time)` spins once
+per second), `deg(r)` (the inverse, for readouts). Or bind the **`rotationDeg`** channel (sugar for
+`rotation = rad(…)`) and use the **`turnDeg`** interactor — both work in degrees, for when that reads better.
+
+## Reserved names
+
+| Name | Meaning |
+|---|---|
+| `time` | seconds elapsed — **resets to 0 every `durationFrames`** (the timeline loops). Fine for motion tuned to the loop; for free-running ambiance use `clock`. |
+| `clock` | seconds elapsed, **monotone** (never wraps). Use for ambient motion in a looping/interactive scene so `sin(clock * f)` doesn't jump on each loop. |
+| `frame` | current frame (0-based; also wraps at `durationFrames`) |
+| `value` | the channel's current value (in a channel binding) |
+| `mouse.x` `mouse.y` | pointer position (scene units) |
+| `keys.<Key>` | `1` while a key is held, `0` otherwise — `<Key>` is the browser `KeyboardEvent.key` value (`keys.ArrowRight`, `keys.a`, `keys.Escape`), plus the alias `keys.Space` for the space bar. Naming a key here also makes the player **consume** it (no page scroll) — see [host integration](host-integration.md#keyboard) |
+| `self.x` `self.y` `self.scaleX` … | the object's own current pose (in its channel bindings) |
+| `self.hovered` `self.grabbed` `self.pressed` | the object's own interaction state (`0`/`1`) — see [feedback](behavior-and-interactions.md#feedback) |
+| `<Name>.x` `<Name>.y` … | a named object's live channels (e.g. `Target.x`) |
+
+## Arrays
+
+```
+var slots = [0, 0, 0]
+object "P" { x = slots[i] }          // computed index
+slots[i + 1] = 1                      // indexed assignment (in actions)
+```
+
+## Functions (`fn`)
+
+Define reusable helpers — a **value** function (an expression) or a **procedure** (actions):
+
+```
+fn dist(ax, ay, bx, by) = hypot(ax - bx, ay - by)      # value
+fn reset() { score = 0  go to frame 0 }                 # procedure
+```
+
+## Stdlib packages
+
+Import bundled helpers with `use "<name>"`. They're embedded (no network, no files), referenced in the
+`.flatpack`, and resolved by the player. Functions are available **bare** and **qualified**
+(`boxHit(…)` or `collision.boxHit(…)` — the qualified form disambiguates collisions).
+
+> **The `use` line is optional**: calling a package function imports its package automatically. A package
+> is a vocabulary, not a module to wire up — `pulse(…)` works because you wrote it. Write `use` when you
+> want the dependency stated, or to pick a side when two packages share a bare name. Your own `fn` of the
+> same name always wins.
+
+```
+use "collision"   # boxHit(ax,ay,bx,by,hw,hh) · dist(ax,ay,bx,by) · near(ax,ay,bx,by,r)
+use "easing"      # easeIn(t) · easeOut(t) · easeInOut(t) · smooth(t)        (t in 0..1)
+use "gesture"     # snap(v,step) · snapTo(v,target,r) · railT/railX/railY(px,py,ax,ay,bx,by) · angle(cx,cy,px,py) · inZone(px,py,x,y,w,h)
+use "feedback"    # lift(h) · dim(h) · tilt(g) · sink(g) · shake(bad,t) · pulse(since,dur)  (channel reactions)
+                  #   shake/pulse ride the MONOTONE `clock` → capture instants with `clock`, never `time`
+```
+
+Example:
+
+```
+use "collision"
+object "Ball" {
+  when dropped on Goal { won = near(self.x, self.y, Goal.x, Goal.y, 30) ? 1 : 0 }
+}
+```
+
+## See also
+
+- Where expressions are used (channels, interactors, feedback) → **[Behavior & interactions](behavior-and-interactions.md)**
+- The `feedback` sugar that writes channel expressions for you → **[Feedback](behavior-and-interactions.md#feedback)**
+- Sending computed values out to the embedding app → **[Host integration](host-integration.md)**