@flatkit/compiler 0.35.3 → 0.36.1

package/docs/animating-symbols.md

@@ -303,18 +303,23 @@ symbol "Boat" {
 ```
 
 - `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.
+  `bool` or `text`. 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.
+- **`text` params** are what a text says — `text libelle at …` (the bare name instead of a quoted
+  string) draws the instance's value: a reusable button carries its own label. Declared with a quoted
+  default: `text libelle = "OK" "label of the button"`.
 - **`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):
+Set params at the instance **call-site** (literals), in `--preview`, or at runtime (see below):
+`Boat.wave = 1.5` for a `number`/`bool` (any expression), `Boat.hull = #33aa33` for a `color` (a color
+literal), `Bouton.libelle = "Bravo"` for a `text` (a quoted text). `flatc --check` reports a param the
+symbol does not declare, a value of the wrong type or out of its range, and a state that does not exist.
 
 ```
 instance "Boat" as "Hero" at center { hull = #1a5f3a, wave = 1.5, flag = false }

package/docs/behavior-and-interactions.md

@@ -154,7 +154,8 @@ object "Piece" {
   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> { … }`.
+  pointer instead. Define an explicit rectangle with `group "Zone" … hitbox <w> <h> { … }` — it is also
+  where the object is touched (click, press, drag, hover) when nothing drawn inside it is hit first.
 - 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).
 
@@ -393,9 +394,33 @@ object "Card" {
 }
 ```
 
+## Keyboard access (`focusable`)
+
+An object that declares `focusable` can be reached and used **without a pointer**:
+
+```
+object "Validate" {
+  focusable order 3            # order is optional: ranked objects first (lower first), then the others in document order
+  when clicked { check() }     # Enter or Space on the focused object fires this too
+}
+object "Hint" {
+  focusable noring             # no default ring: this object draws its own…
+  opacity = self.focused ? 1 : 0.7      # …from `self.focused` (1 while it holds the focus)
+}
+```
+
+- **Tab / Shift+Tab** walk the focusable objects; **Enter** and **Space** click the focused one (its
+  `when clicked`). An object that is not shown (opacity 0, or absent from the picture) is skipped.
+- The player draws a **focus ring** around the focused object — around its `hitbox` when it has one.
+  `noring` leaves the drawing to the scene.
+- The focus is a stop, not a trap: past the last object (or before the first), Tab goes back to the page.
+- Using the pointer drops the keyboard focus, like `:focus-visible` on a web page.
+- Under `flatc --play`, `{ "type": "key", "name": "Tab" }` moves the focus and `"Enter"` clicks, so a
+  keyboard path is tested like any other.
+
 ## Feedback
 
-An object can read **its own interaction state** in channel expressions: `self.hovered`, `self.grabbed`,
+An object can read **its own interaction state** in channel expressions: `self.focused`, `self.hovered`, `self.grabbed`,
 `self.pressed` (each `0`/`1`). So hover-lift and grab-squash are just expressions — no mirror variable,
 no handler:
 

package/docs/dsl-gotchas.md

@@ -114,7 +114,9 @@
   (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)"`.
+  `turns(time)` (one turn per second), `deg(r)`. e.g. `expr rotation "turns(time * 0.5)"`. Or write
+  `expr rotationDeg "<degrees>"`, the degree twin (as in a behavior block). Any other channel name is a
+  compile error.
 - **`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)`.
@@ -170,8 +172,16 @@
 - **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.
+  - `group "Zone" … hitbox <W> <H> { … }`: an **explicit rectangle** (centered on the
+    origin, ±W/2 × ±H/2) instead of the content bbox. Replaces invisible `#ffffff01` paths. Works on an
+    `instance` too.
+- **`hitbox` is also where the object is TOUCHED** — clicked, pressed, dragged, hovered — whenever
+  nothing drawn inside it is hit first. Use it for a stroke-only ring (only the stroke is touched
+  otherwise, not the middle), a small handle that deserves a finger-sized target, or an empty group laid
+  over a picture. The rectangle follows the object. What is drawn ABOVE it keeps the pointer.
+- **What lets the pointer through**: `nohit`, a hidden item, and anything whose `opacity` is `0.01` or
+  less — with or without a `hitbox`. An invisible touch area is an empty group with a `hitbox`, at full
+  opacity: there is nothing to draw.
 - **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
@@ -225,9 +235,9 @@ Inside an `object "Name" { … }`, besides `drag x, y` / `dragX` / `dragY`:
     See [Behavior](behavior-and-interactions.md#seeing-where-it-was-scratched-reveal--cells).
   - A `reveal` target is grabbable **over its whole zone**, whatever its content looks like — so a veil
     stays scratchable where its cells have already gone to `opacity 0`. (Everywhere else, an item at
-    `opacity 0` lets the pointer through; a group whose children are ALL invisible is not hit, and
-    `hitbox` does not change that — it is the drop-zone rectangle, not a hit surface. Only a replayed
-    `down/move/up` script shows this class of bug: a static render looks perfect.)
+    `opacity 0` lets the pointer through; a group whose children are ALL invisible is not hit unless
+    it declares a `hitbox`. Only a replayed `down/move/up` script shows this class of bug: a static
+    render looks perfect.)
 - **`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

package/docs/expressions-and-stdlib.md

@@ -50,9 +50,10 @@ per second), `deg(r)` (the inverse, for readouts). Or bind the **`rotationDeg`**
 | `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) |
+| `random()` | a number in `[0, 1[`, a new one at each call. Reproducible when the player is given a `seed` (always the case under `flatc --play`, see `--seed`) — see [host integration](host-integration.md) |
+| `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, **or** the physical key, `KeyboardEvent.code` (`keys.ShiftLeft`, `keys.Digit1`, `keys.Numpad1`, `keys.KeyA`) — the way to tell the two Shift keys apart and to read the digit row. 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) |
+| `self.hovered` `self.grabbed` `self.pressed` `self.focused` | the object's own interaction state (`0`/`1`; `focused` = it holds the keyboard focus, see `focusable`) — see [feedback](behavior-and-interactions.md#feedback) |
 | `<Name>.x` `<Name>.y` … | a named object's live channels (e.g. `Target.x`) |
 
 ## Arrays

package/docs/host-integration.md

@@ -25,11 +25,26 @@ const player = new FlatPlayer(canvas, doc, {
 | `autoplay` | `false` | starts the timeline on mount |
 | `loop` | `true` | loops the timeline |
 | `padding` | `0` | margin around the page, in CSS px |
-| `audio` | `true` | `false` mutes `sound "…"` and audio tracks |
+| `audio` | `true` | `false` mutes `sound "…"` and audio tracks. Sounds are decoded when the document loads, so the first one plays on time |
 | `input` | `true` | `false` = non-interactive preview: it animates but ignores pointer **and keyboard** |
 | `render` | `true` | `false` = headless (logic + `send`s only, no Canvas API needed) |
 | `resolveAsset` | embedded only | maps an asset to a URL. Default: embedded `data:` URIs only — see [Security](#security) |
 | `onEvent` | — | called on every `send` |
+| `focusRing` | `true` | the ring drawn around the object that holds the keyboard focus (`focusable`). `false` = none, or `{ color, width }` |
+| `seed` | none | seed of `random()`: the scene then draws the same numbers on every run. Absent, it draws from `Math.random` |
+| `maxPixelRatio` | none | upper bound on the device pixel ratio the canvas is sized with. The backing store grows with the square of the ratio; on a 3x phone, `2` trades a little sharpness for a much cheaper frame |
+
+### When the player paints
+
+While it plays, the player repaints a frame **only when the picture can have changed**: a variable an
+expression reads was written, a param or a state moved, a spring is still settling, the pointer or a key
+changed, an image or a font finished loading. A scene at rest costs no paint at all. A scene whose
+expressions read `time`, `clock`, `frame` or `random()`, or whose keyframes play with the playhead, is
+repainted every frame as before.
+
+Everything the player exposes paints on its own (`setVar`, `setKey`, `seek`, `load`…). If the host changes
+what is drawn behind the player's back — it mutates the document it handed over, say — it calls
+`player.render()`.
 
 ## Receiving events (`send` → `onEvent`)
 
@@ -124,6 +139,28 @@ place, and `render()` forces a repaint (useful after a late font settles).
 `KeyboardEvent.key` value — `keys.ArrowRight`, `keys.a`, `keys.Escape` — plus one alias: the space bar
 (`key === ' '`) is also exposed as **`keys.Space`**.
 
+A physical key answers to its **`KeyboardEvent.code`** as well: `keys.ShiftLeft` and `keys.ShiftRight` are
+two keys (both are `keys.Shift`), the digit row is `keys.Digit1`…`keys.Digit0` (its `key` is `"1"`, which
+an expression cannot spell), the keypad `keys.Numpad1`, a letter wherever the layout puts it `keys.KeyA`.
+
+### Keyboard focus
+
+A scene whose objects declare `focusable` makes its canvas a **stop in the page's tab order** (the player
+sets `tabindex="0"` on it unless you set one). Reached with Tab, the first object takes the focus (the last
+one when the page came backwards); Tab then walks the objects, Enter and Space click the focused one, and
+past either end the key is left to the page. The player handles Tab only while the canvas has the page's
+focus, so it never interferes with the rest of your page.
+
+- `focusRing` option: `false` to draw no ring (the scene uses `self.focused`), or `{ color, width }`.
+- `player.focused` is the name of the focused object (or `null`); `player.focusNext(1 | -1)` moves the
+  focus from the host (it returns `false` when there is nothing left that way).
+- The canvas keeps the browser's own focus outline: style it as you would any focusable element.
+
+### Pointers
+
+Each pointer has its own gesture: two fingers can press, hold and drag two objects at once, and lifting
+one releases only what it was holding. `mouse.x` / `mouse.y` follow the pointer that moved last.
+
 The listeners are attached to the **window** (a scene reacts immediately, with no click-to-focus step),
 but the player is a good citizen about it — you should not have to do anything:
 

package/docs/scene-and-drawing.md

@@ -24,8 +24,15 @@ ellipse <cx> <cy> <rx> <ry>
 rect    <x> <y> <w> <h>            # · <r> for uniform rounded corners · <rx> <ry> for distinct
 path    "M0 0 L10 0 L10 10 Z"      # raw SVG path data
 circle  100 100 40 as "Ring"       # name a shape (right after the geometry) → addressable, e.g. text `along "Ring"`
+path    "M0 0 L8 3 L15 9 …" smooth # free-hand material: rounded wherever the outline turns gently
 ```
 
+A `path` means what its data says: `L`, `H` and `V` are **straight lines**, next to a curve or on their own
+— a hexagon has six flat sides. **`smooth`**, right after the path data, reads the path as **free-hand
+material** instead: its points are joined by a curve that rounds every gentle turn (under 60°) and keeps
+the sharp ones. It is what the editor's brush exports, and what a curve sampled as many small `L` steps
+wants. `flatc --check` points at a long run of points with gentle turns that does not say `smooth`.
+
 ### Fill, stroke, opacity
 
 ```
@@ -35,6 +42,37 @@ path "…" nofill stroke #888 2                                   # outline only
 rect 0 0 40 40 fill #00aaff opacity 0.5                         # 0..1 (8-digit hex alpha also works)
 ```
 
+### A shape computed while the scene runs (`polyline`)
+
+`polyline` is a shape whose points are **two array variables**, read every frame — a trajectory, a curve as
+it is being computed, a polygon the learner deforms:
+
+```
+var tx = fill(200, 0)
+var ty = fill(200, 0)
+var n = 0
+scene {
+  layer "c" {
+    polyline tx ty count "n" nofill stroke #cc3333 3 cap round    # the first n points, as a line
+    polyline px py closed fill #3366cc                             # all the points, as a filled polygon
+  }
+}
+every frame {
+  if n < 200 {
+    tx[n] = 20 + n * 2
+    ty[n] = 90 - 60 * sin(n / 10)
+    n = n + 1
+  }
+}
+```
+
+- `polyline <xs> <ys>` takes the **names** of the two arrays. `count <n>` or `count "<expr>"` keeps the
+  first points only (never past the arrays); `closed` joins the last point to the first.
+- The segments are **straight**. Fill, stroke, `opacity`, `draw` and `nohit` are those of any shape.
+- The arrays are the truth: write them from `every frame` or a handler, and the line follows. A scene that
+  stops writing them stops being repainted. `flatc --check` reports a name that is not a declared array.
+- Fewer than two points draw nothing.
+
 ### Drawing a stroke progressively (`draw`)
 
 `draw` sets **how much of an outline is stroked**, as a fraction of its **arc length** — ink that appears

package/docs/tooling.md

@@ -233,6 +233,11 @@ flatc <file> --play --script gestures.json [--trace]
 ```
 
 - `drag` / `tap` / `scratch` (sweeps a `reveal` zone) / `connect` (pulls a `link` wire) — by name.
+  `tap` also takes a point instead of a name — `{ "type": "tap", "x": 120, "y": 80 }` — for a rail or
+  an area that has no name.
+- Audio is off in `--play`: a `sound` action is a silent no-op, so a program is replayed as written.
+- `random()` is seeded in `--play` (seed `1`), so a replay says the same thing twice and an `expect` can
+  assert on a draw. `--seed N` picks another one.
 - **`turn`** rotates a `turn`/`turnDeg` target by `angle` (degrees for `turnDeg`, radians for `turn`),
   swept in sub-steps so a multi-turn rotation lands. It presses the object where the engine finds it, i.e.
   on **whatever is topmost there** — two clock hands overlapping at noon give the gesture to the one on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatkit/compiler",
-  "version": "0.35.3",
+  "version": "0.36.1",
   "description": "The FlatInk language (parser + AST) and compiler (.flatink → .flatpack). Ships the flatc CLI.",
   "license": "MIT",
   "author": "Zwyk Studio",
@@ -57,9 +57,9 @@
     "docs"
   ],
   "dependencies": {
-    "@flatkit/engine": "0.35.3",
-    "@flatkit/player": "0.35.3",
-    "@flatkit/types": "0.35.3"
+    "@flatkit/engine": "0.36.1",
+    "@flatkit/player": "0.36.1",
+    "@flatkit/types": "0.36.1"
   },
   "peerDependencies": {
     "skia-canvas": "^3.0.8"

package/prompts/flatink-core.md

@@ -252,7 +252,8 @@ State & helpers:
 var x = 0    var arr = [0,0,0]    var z = fill(8, 0)     // runtime state (arrays via fill)
 fn dist(ax,ay,bx,by) = hypot(ax-bx, ay-by)              // value fn
 fn reset() { score = 0  go to frame 0 }                  // procedure fn
-self.hovered self.grabbed self.pressed                   // own interaction state (0/1)
+self.hovered self.grabbed self.pressed self.focused      // own interaction state (0/1)
+focusable [order <n>] [noring]                           // in an object block: Tab reaches it, Enter/Space fire `when clicked`, the player rings it
 feedback lift tilt dim shake(<expr>)                     // one-liner reactions (auto use "feedback")
 ```
 
@@ -323,7 +324,7 @@ ramp over `dur` s for a readable timed feedback — capture the instant with **`
 13. **`$()` is for compile-time interpolation in scene coords**; runtime expressions use bare
     identifiers and `[]` indexing. Arrays must exist before indexed write (`var hx = fill(n,0)`).
 14. **Drop test = object center** by default; use `when dropped on Zone at pointer` for the pointer, or
-    `group "Zone" … hitbox W H { … }` for an explicit rectangle. `when released` fires BEFORE the drop test.
+    `group "Zone" … hitbox W H { … }` for an explicit rectangle (also the object's TOUCH area: a stroke-only ring is clicked in its middle only with a `hitbox`). `when released` fires BEFORE the drop test.
 15. **`reveal`/`trace` progress is monotone** (never decreases). `link` works in WORLD coords.
 16. **Stroke width scales with the group** (drawn in scaled space) — don't compensate by hand.
 17. **All rotation is radians; author degrees with the `*Deg` twins.** The `rotation` channel,

package/prompts/flatink-lite.md

@@ -87,7 +87,8 @@ link endX,endY,target to <Group>     // target = hit index 1..n (0=none), WORLD
   // link draws NO thread. A bar drawn from its own origin, then:
   //   rotation = angle(srcX, srcY, endX, endY)   scaleX = dist(srcX, srcY, endX, endY) / <drawn length>
 ```
-Self-state & feedback: `self.hovered self.grabbed self.pressed` (0/1) ·
+Keyboard: `focusable [order n]` in an `object` block → Tab reaches it, Enter/Space fire its `when clicked`.
+Self-state & feedback: `self.hovered self.grabbed self.pressed self.focused` (0/1) ·
 `feedback lift tilt dim shake(<expr>)`.
 State/funcs: `var a = 0` · `var arr = fill(8,0)` (also as an ASSIGNMENT: `arr = fill(n, 0)` blanks a grid) · `fn dist(ax,ay,bx,by) = hypot(ax-bx,ay-by)` ·
 `fn reset() { score = 0 }`.

package/prompts/role-asset-creator.md

@@ -69,7 +69,9 @@ symbol "Boat" {
   }
 }
 ```
-- Types: `color`, `number` (`number wave = 1 range 0 2 "…"`), `bool`.
+- Types: `color`, `number` (`number wave = 1 range 0 2 "…"`), `bool`, `text` (`text label = "OK" "…"`).
+- A `text` param is drawn with `text label at …` (the bare name instead of a quoted string): a button
+  carries its own label, set per instance with `{ label = "Play" }`.
 - `color` params go anywhere a `#color` literal goes (`fill hull`, `stroke hull 3`).
 - Preview a restyle: `flatc --preview Boat.flat --render --set hull=#1a5f3a -o boat.png`.