@flatkit/compiler 0.26.0 → 0.28.0

package/docs/getting-started.md

@@ -0,0 +1,107 @@
+# Getting started
+
+> Prerequisite: the `flatc` CLI — `pnpm add -D @flatkit/compiler` (or run it from this repo with
+> `pnpm flatc …`). See [Tooling](tooling.md) for the full CLI.
+
+## 1. Your first scene
+
+Create `hello.flatink`:
+
+```
+size 320 240
+background #0a0e1c
+
+scene {
+  layer "main" {
+    circle 160 120 48 fill #ffcc00
+    text "Hello, FlatInk" at 0,190 font "sans-serif" size 24 align center line 1.2 color #ffffff box 320 40
+  }
+}
+```
+
+- `size` is **required and must come first** (the canvas, in scene units).
+- `scene { … }` holds **layers**; layers hold **items** (`circle`, `text`, `path`, `image`, `group`…).
+- Coordinates are plain numbers; the origin is the top-left of the canvas.
+- On `text` (and `image`), `at x,y` comes **right after the content**, before `font`/`box`/`fill` — not at
+  the end. `text "…" box W H at x,y` fails; write `text "…" at x,y box W H`.
+
+Compile and look at it:
+
+```sh
+flatc hello.flatink -o hello.flatpack     # → a single playable file
+flatc hello.flatink --render -o hello.png  # → a PNG, to see what you drew (needs skia-canvas)
+```
+
+## 2. Make it move
+
+Animation comes from **channel expressions** in a behavior block, which target a **named object**
+(`group`/`instance`/`text`). A bare shape can't carry channels — its `as "<id>"` name only makes it
+addressable for **text-on-path** — so wrap it in a named **group** (the name lives on the group), then
+drive a channel:
+
+```
+scene {
+  layer "main" {
+    group "Sun" at 160,120 pivot 0,0 { layer "art" { circle 0 0 48 fill #ffcc00 } }
+  }
+}
+
+object "Sun" {
+  scaleX = 1 + sin(clock * 3) * 0.1   // gentle pulse
+  scaleY = 1 + sin(clock * 3) * 0.1
+}
+```
+
+`clock` is seconds elapsed, **monotone**; `sin`/`cos` and friends are built in (see
+[Expressions](expressions-and-stdlib.md)). Channels you can bind: `x`, `y`, `scaleX`, `scaleY`,
+`rotation`, `opacity`.
+
+> **`clock`, not `time`.** `time` restarts at 0 every `durationFrames` (2.5 s by default), so free-running
+> motion **jumps** on each loop and a one-shot ramp **replays**. Use `time` only for motion you tuned to
+> the loop itself; use `clock` for ambience and for any instant you capture and compare later. `--check`
+> warns when a channel reads `time` under a short timeline — including through a function you wrote.
+
+## 3. Make it react
+
+Add state (`var`) and an event handler:
+
+```
+var score = 0
+
+scene {
+  layer "main" {
+    group "Sun" at 160,120 pivot 0,0 { layer "art" { circle 0 0 48 fill #ffcc00 } }
+    text "Score: {}" at 0,10 bind "score" box 320 40 font "sans-serif" size 20 align center line 1.2 color #fff
+  }
+}
+
+object "Sun" {
+  when clicked { score = score + 1 }
+  scaleY = self.grabbed ? 0.92 : 1     // squash while pressed
+}
+```
+
+- `var score = 0` declares interactive state.
+- `when clicked { … }` runs actions on click.
+- `text "… {}" bind "score"` shows the live value (the `{}` slot).
+- `self.grabbed` is this object's own interaction state — see [feedback](behavior-and-interactions.md#feedback).
+
+## 4. Play it
+
+In a web page:
+
+```js
+import { FlatPlayer } from '@flatkit/player'
+
+const canvas = document.querySelector('canvas')
+const doc = await fetch('hello.flatpack').then((r) => r.json())
+const player = new FlatPlayer(canvas, doc, { autoplay: true })
+```
+
+Or verify it headlessly (great in CI) without a browser — see [Tooling → headless play](tooling.md#headless-play--play).
+
+## Where next
+
+- Draw richer scenes → **[Scene & drawing](scene-and-drawing.md)**
+- Drag/drop, interactors, feedback → **[Behavior & interactions](behavior-and-interactions.md)**
+- The full `flatc` CLI → **[Tooling](tooling.md)**

package/docs/host-integration.md

@@ -0,0 +1,162 @@
+# Host integration — embedding the player in an app
+
+A `.flatpack` is not a video: it has **state** and it can **talk back**. This guide is the receiving
+end — how the page that mounts `@flatkit/player` listens to a scene, drives it, and tears it down.
+
+The scene side of the contract lives in
+[Behavior & interactions](behavior-and-interactions.md#send--talking-to-the-host).
+
+## Mount
+
+```js
+import { FlatPlayer, loadEmbeddedFonts } from '@flatkit/player'
+
+const doc = await fetch('activity.flatpack').then((r) => r.json())
+await loadEmbeddedFonts(doc)                    // BEFORE mounting (see embedding-fonts.md)
+
+const player = new FlatPlayer(canvas, doc, {
+  autoplay: true,
+  onEvent: (e) => handle(e),                    // the `send` channel
+})
+```
+
+| Option | Default | What it does |
+|---|---|---|
+| `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 |
+| `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` |
+
+## Receiving events (`send` → `onEvent`)
+
+`onEvent` gets **one object per `send`**, synchronously, during the tick that fired it. The type is
+exported — `import type { SendEvent } from '@flatkit/player'`:
+
+```ts
+type SendEvent = {
+  name: string                          // the event name, e.g. "save"
+  value?: number | string               // number payload, or text("…") content
+  fields?: Record<string, number>       // record payload — named numbers
+}
+```
+
+Which key is present depends on the payload form the scene used:
+
+| In the scene | The host receives |
+|---|---|
+| `send "win"` | `{ name: 'win' }` |
+| `send "score", lives * 100` | `{ name: 'score', value: 300 }` |
+| `send "answer", text("txtCard")` | `{ name: 'answer', value: 'Bonjour' }` |
+| `send "save", { x = px, y = py, doors }` | `{ name: 'save', fields: { x: 12, y: 40, doors: 3 } }` |
+
+`value` and `fields` are mutually exclusive today — a record carries no positional `value`. Write the
+handler so an unknown/absent key is simply ignored, and it stays forward-compatible:
+
+```js
+function handle(e) {
+  switch (e.name) {
+    case 'score': setScore(e.value ?? 0); break
+    case 'save':  setState((s) => ({ ...s, ...e.fields })); break   // a record IS a state patch
+    case 'win':   finish(); break
+  }
+}
+```
+
+Three properties worth relying on:
+
+- **Fire-and-forget.** Nothing is returned to the scene; the return value of `onEvent` is ignored.
+- **Exception-safe.** If your callback throws, the player catches, logs, and keeps playing — a broken
+  host handler never freezes the activity. (So do your own error reporting inside it.)
+- **Vetted.** Everything crossing the boundary is validated by the player, not trusted from the
+  document: the event name matches `[A-Za-z_][A-Za-z0-9_-]{0,63}`, numbers are finite (`NaN`/`Infinity`
+  → `0`), text is truncated at 4096 characters, and a record carries at most 32 fields whose names are
+  plain identifiers — never `__proto__`, `constructor` or `prototype`. Spreading `e.fields` into your
+  own state cannot pollute a prototype.
+
+## Driving the scene from the host
+
+The state variables (`var` in the DSL, "Layer B") are readable and writable both ways:
+
+```js
+player.setVar('difficulty', 2)        // host → scene (redraws immediately; arrays are cloned)
+player.getVar('score')                // scene → host: number | number[] | undefined (arrays copied)
+player.allVars()                      // snapshot of everything, for debugging/save states
+```
+
+`getVar`/`allVars` return **copies**: mutating the result never touches the running scene. Symmetrically
+`setVar` clones what you pass in.
+
+Playback control mirrors the DSL actions: `play()`, `pause()`, `toggle()`, `stop()`, `seek(frame)`,
+plus the read-only `currentFrame`, `isPlaying`, `fps`, `duration`. `load(doc)` swaps the document in
+place, and `render()` forces a repaint (useful after a late font settles).
+
+## Keyboard
+
+`keys.<Key>` in an expression is `1` while the key is held. The name is the browser's
+`KeyboardEvent.key` value — `keys.ArrowRight`, `keys.a`, `keys.Escape` — plus one alias: the space bar
+(`key === ' '`) is also exposed as **`keys.Space`**.
+
+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:
+
+- **It never steals what you are typing.** A keystroke headed to an `<input>`, `<textarea>`, `<select>`
+  or any `contenteditable` element of the host page is ignored by the scene.
+- **It only consumes the keys the scene actually declares.** The player scans the document for
+  `keys.<Name>` and calls `preventDefault()` on those alone: an activity bound to the arrows stops
+  scrolling the page under it, while every other key keeps its native behavior. Browser/OS shortcuts
+  (any `Ctrl`/`Cmd`/`Alt` combination), `Tab` and the function keys are never consumed, whatever the
+  scene declares.
+- **A key never stays stuck.** Losing the window (alt-tab, an iframe taking the focus) releases the
+  held keys, even though the browser delivers no `keyup` in that case.
+
+`input: false` remains the total opt-out: no pointer and no keyboard listener at all.
+
+**On-screen controls.** There is no keyboard on a phone, so a key can also be driven programmatically —
+wire your own D-pad to `setKey`, and the scene cannot tell the difference:
+
+```js
+btn.addEventListener('pointerdown', () => player.setKey('ArrowRight', true))
+btn.addEventListener('pointerup',   () => player.setKey('ArrowRight', false))
+```
+
+A key stays held until released, so pair every `true` with a `false` (a `pointercancel`/`pointerleave`
+handler too, or a finger sliding off the button leaves the scene running).
+
+## Teardown
+
+```js
+player.destroy()   // pauses, releases the window/canvas listeners and the pending timers
+```
+
+Always call it when unmounting (a React `useEffect` cleanup, a route change…). Skipping it leaves
+`keydown`/`resize` listeners attached to the window.
+
+## Security
+
+A `.flatpack` is **untrusted input** — treat it like third-party HTML, not like your own code. The
+player is built for that: no `eval`, bounded per-tick work, and **no network access by default** (only
+the assets embedded as `data:` URIs are loaded). To serve external assets, pass an explicit resolver so
+the *host* picks the origin:
+
+```js
+import { FlatPlayer, sameOriginAssetResolver } from '@flatkit/player'
+new FlatPlayer(canvas, doc, { resolveAsset: sameOriginAssetResolver('/activities/42/') })
+```
+
+Read [SECURITY.md](../SECURITY.md) for the full threat model.
+
+## Testing the integration without a browser
+
+`flatc … --play --script gestures.json` replays a gesture script headlessly and prints the `sends` (with
+their `value`/`fields`) plus the final variables — the same objects your `onEvent` would receive. It is
+the cheapest way to lock the host contract in CI. See [Tooling](tooling.md).
+
+## See also
+
+- What the scene can emit → **[Behavior & interactions](behavior-and-interactions.md#send--talking-to-the-host)**
+- Registering the doc's embedded fonts → **[Embedding fonts](embedding-fonts.md)**
+- Headless replay and CI → **[Tooling](tooling.md)**

package/docs/scene-and-drawing.md

@@ -0,0 +1,168 @@
+# Scene & drawing
+
+Everything inside `scene { … }` is composition. The tree is **layers → items**; items can be shapes,
+text, images, or **groups** (which nest their own layers).
+
+```
+scene {
+  layer "bg"   { rect 0 0 480 320 fill #0a0e1c }
+  layer "game" {
+    group "Hero" at 240,160 { layer "c" { circle 0 0 30 fill #ffcc00 } }
+  }
+}
+```
+
+Layers stack bottom-to-top. A `layer` takes `"name"` and options (`opacity <n>`, `locked`, `hidden`).
+
+## Shapes
+
+Sugar primitives (normalized to a `path` on save — no need to hand-compute Beziers):
+
+```
+circle  <cx> <cy> <r>
+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"`
+```
+
+### Fill, stroke, opacity
+
+```
+circle 0 0 20 fill #ff3366
+path "…" fill #000 stroke #ffffff 3 cap round join round       # stroke: <color> <width> [cap] [join] [miter n] [dash a,b]
+path "…" nofill stroke #888 2                                   # outline only (a line, a thread)
+rect 0 0 40 40 fill #00aaff opacity 0.5                         # 0..1 (8-digit hex alpha also works)
+```
+
+### Paints (gradients)
+
+```
+fill linear(90, 0:#bdecff, 1:#2f8fe0)          # angle: 0 = →, 90 = ↓ ; stops are offset:color
+fill radial(0.5, 0.5, 0.5, 0:#fff, 1:#000)     # cx, cy, r (0..1), then stops
+```
+
+A stop's color can be a symbol **`color` param** instead of a literal — so a gradient (a halo, a glow) is
+recolorable per instance, like `fill <param>` is for a solid. An optional `@alpha` (0..1) sets the stop's
+alpha, since a param is a 6-digit hue:
+
+```
+params { color teinte = #ffe9a8 }
+circle 0 0 60 fill radial(0.5, 0.5, 0.5, 0:teinte@0.8, 1:teinte@0)   # same hue, alpha fading 0.8 → 0
+```
+
+Param and literal stops mix freely (`0:teinte@0.8, 0.5:#3366ffcc, 1:teinte@0`). See
+[exposed parameters](animating-symbols.md#exposed-parameters-params).
+
+### Filters
+
+`filter` works on any item (shape, text, image, group) — no need to wrap in a group:
+
+```
+filter glow <blur> <color>
+filter shadow <dx> <dy> <blur> <color>
+filter blur <radius>
+filter adjust <brightness> <contrast> <saturate> <hue>
+```
+
+Filters on **static** decor are cached (nearly free); on **animated** elements they recomposite every
+frame — keep those small (see the [gotchas](dsl-gotchas.md) for the perf details).
+
+## Clipping & masks
+
+Cut a container's content to a viewport — scroll panes, reveal windows, framed cards:
+
+```
+group "Viewport" at 20,20 clip 0 0 120 80 { layer "c" { … } }   // rectangular clip, in the group's LOCAL coords
+mask layer "Window" { circle 60 60 50 fill #fff  layer "c" { … } }  // arbitrary clip shape (the mask's matter clips its child layers)
+```
+
+- **`clip <x> <y> <w> <h>`** on a `group`/`instance` cuts everything outside the rectangle. **Render-only**:
+  hit-testing and the auto-size bbox ignore it (the clipped-away area stays clickable / counts toward
+  framing) — it's a visual cut, not a hit/layout change.
+- For an **arbitrary** clip shape, use a **`mask` layer**: its material (the shapes drawn directly in it)
+  clips its **child layers**. See the [gotchas](dsl-gotchas.md) for the clip/mask details.
+
+## Text
+
+```
+text "Hello" font "sans-serif" size 24 align center line 1.2 color #ffffff box 200 40
+text "OUTLINE" font "sans-serif" size 64 color #ffd23f stroke #e23b3b 6 join round   # outlined text
+```
+
+- `box <w> <h>` sets the text box; `align left|center|right`; `line` = line-height; `bold` / `italic`.
+- `stroke <color> <width> [cap …] [join …] [miter n] [dash a,b]` outlines the glyphs (same grammar as
+  paths). The stroke is drawn **behind** the fill, so the fill keeps its full weight. Accepts a gradient
+  paint too (`stroke linear(…) 4`).
+- **Word-wrap is opt-in**: add `wrap` to break at spaces within the box width (otherwise only explicit `\n` wraps).
+- **Live text**: `text "Angle: {}°" bind "round(a)" decimals 1` evaluates the expression every frame and
+  fills the `{}` slot (or replaces the whole string if there's no `{}`).
+- **Stable id**: `text "…" as "myId"` lets behavior reference it via `text("myId")` (e.g. in a `send`
+  payload). Without `as`, the id is auto-generated and not referenceable.
+
+### Text on a path
+
+Lay glyphs **along a curve** instead of a straight baseline — banners, badges, ribbons, dials:
+
+```
+text "SURF CLUB" along "Banner" align center             # follow a NAMED shape's outline
+text "loop" along path "M0 80 C120 0 360 0 480 80"       # …or inline SVG path data
+```
+
+- **`along "<id>"`** follows a **named shape** (`circle`/`rect`/`ellipse`/`path … as "<id>"`). A *closed*
+  named shape (circle/ellipse) anchors the run **upright, centered over the top** by default. **`along path
+  "<d>"`** takes inline path data instead — baked **literally**, so you own its start/direction.
+- **`align`** reuses the text alignment: `left` starts the run at the anchor, `center` centers on it,
+  `right` ends on it. **`start <0..1>`** moves the anchor along the curve (fraction of its length). On an
+  **open** path the anchor defaults to the start (0), so to center a label *on the path* use `align center
+  start 0.5` — with `start 0`, `center`/`right` push the run off the near end and those glyphs are dropped.
+  (Closed paths wrap, so `start 0` already centers over the top.)
+- **`side over|under`** — which side of the curve the run sits on: `over` = outside (default), `under` = inside.
+- **`spacing <px>`** — extra tracking per glyph (may be negative; the effective advance is floored at 1px).
+- **Animate** by quoting the value (it becomes an expression, same scope as `bind`: `time`, `frame`,
+  `clock`, vars): `start "time * 0.1"` scrolls the run along the path (**marquee** — wraps on a closed
+  shape); `spacing "sin(clock) * 4"` eases the tracking.
+- `along` replaces `at`/`box`/`wrap` (a path-laid run is not box-wrapped). A run longer than the path drops
+  its trailing glyphs, and `flatc` warns (`… overflows its path (~Npx > Lpx)`).
+
+## Images
+
+```
+asset "logo" "logo.svg" image      // declare the media (top of file) — embedded by flatc
+scene { layer "c" { image "logo" 80 80 at -40,-40 } }   // the origin is the top-left → center with at -w/2,-h/2
+```
+
+## Transforms & placement
+
+On any group / instance / text / image:
+
+```
+at <x>,<y>                          # translation
+matrix(a,b,c,d,e,f)                 # full affine
+at center  ·  at center,540  ·  at 120,center        # canvas-relative anchor (resolved from `size`)
+align <point> of "Name" [offset dx,dy]               # pin this item's origin onto another item's bbox
+```
+
+> **Placement & naming gotchas.** The order is fixed: **content → `as "…"` → `at …` / `matrix(…)` →
+> style attributes** (`font`/`box`/`fill`/…). So `text "…" box W H at x,y` fails — write `text "…" at x,y
+> box W H`; and `image "logo" 80 80 at 0,0 as "L"` fails — write `image "logo" 80 80 as "L" at 0,0`
+> (same for `instance "Sym" as "hero" at x,y`). **Shapes** name themselves with `as
+> "<id>"` **right after the geometry** (`circle cx cy r as "Ring" fill …`); a named shape is addressable by
+> **text-on-path** (`along "<id>"`). To drive a shape from *behavior* (clicks, `send`, drop zones), still
+> wrap it in a `group "Name"` — the region name addresses geometry, the group name an interactive object.
+
+`align` points: `center`, `top`, `bottom`, `left`, `right`, `topleft`, `topright`, `bottomleft`,
+`bottomright`. It uses the target's **static** bbox (no expression channels) — placement only, no flow
+layout (stack with `repeat` + `$()`, see [factoring](behavior-and-interactions.md#reuse--factoring)).
+
+## Other item attributes
+
+- `pivot <x>,<y>` — origin offset (the rotation/scale center).
+- `tint <color> <amount>` — Flash-style tint, `amount` 0..1. `<color>` may be a symbol `color` param (`tint teinte 0.4`), recolorable per instance.
+- `nohit` — stays **drawn** but ignored by hit-testing (clicks pass through). On a group, applies to the
+  whole subtree. Ideal for a decorative full-screen veil.
+
+## See also
+
+- Animate and react → **[Behavior & interactions](behavior-and-interactions.md)**
+- Reuse shapes (symbols, `repeat`, `each`) → **[Behavior & interactions → Reuse](behavior-and-interactions.md#reuse--factoring)**

package/docs/tooling.md

@@ -0,0 +1,236 @@
+# Tooling — the `flatc` CLI
+
+`flatc` compiles `.flatink` text into a single `.flatpack`, and helps you **see**, **test**, and
+**ship** scenes. Install with `pnpm add -D @flatkit/compiler` (or `pnpm flatc …` in this repo).
+`flatc --help` lists everything.
+
+## Files
+
+| File | What |
+|---|---|
+| `.flatink` | the program (composition + behavior, the DSL) |
+| `.flat` | a visual asset library (symbols), exported by the editor |
+| `.flatpack` | the baked, playable `Doc` (JSON) — what the player runs |
+
+```
+flatc game.flatink hero.flat -o game.flatpack
+```
+
+`.flat` libs in the program's folder are discovered automatically; media declared by
+`asset "id" "path" kind` are embedded as `data:` URIs.
+
+> **The extension decides how a file is read**, so it decides what `--check` verifies. A `.flat` is read
+> as a bag of symbols: a whole *program* saved under that name has no symbols in it, so `--check` used to
+> report "0 symbol(s)" and exit 0 with nothing verified. `flatc` now **refuses** a `.flat` that contains a
+> `scene { … }` block or `object` blocks. When checking a program, make sure it is named `.flatink`.
+>
+> **`--no-libs`** turns off the folder auto-discovery. In a working folder a neighbouring scratch file is
+> not a dependency — and when one of them fails to parse, the error now names the file.
+
+## Compile & check
+
+```
+flatc <program.flatink> [-o out.flatpack]
+flatc <program.flatink> --check      # semantic lint only (exits ≠0 on ERROR; warnings don't block)
+flatc <program.flatink> --check --no-libs    # …without pulling in the .flat files sitting next to it
+flatc <program.flatink> --watch      # recompile on every change in the folder
+flatc <library.flat> [more.flat …] --check   # lint an asset LIB per-symbol (several .flat are merged)
+```
+
+`--check` lints a program **or** an asset library (`.flat`): the same per-symbol checks (params-in-`expr`,
+undeclared color param in a paint, unknown functions/objects) run on a lib's symbols — no need to compile a
+preview first.
+
+`--check` also covers approximate **layout** warnings: text overflowing the canvas, **wrapped text taller
+than its box** (or holding a single word too wide to break), clipped items, missing/overlapping drop zones,
+never-used variables, and a `color` param used as a paint (a `fill`/`stroke`, a gradient stop `0:teinte@…`,
+or a `tint`) that the symbol doesn't declare — a silent "dead recolor". The layout passes descend **into
+groups** and measure in world coordinates, and they skip anything positioned at runtime (a bound or dragged
+item, and everything nested under one, has no meaningful static position).
+
+It flags an instant **captured on `time` and read by `pulse`/`shake`** — both ride the monotone `clock`, so
+the two axes never meet and the ramp never fires, with nothing on screen to say so. The costliest kind of
+bug in a codebase migrated from 0.21; see the
+[gotchas](dsl-gotchas.md#feedback-reactions-in-one-line).
+
+### Rendering from code — one frame, or three hundred
+
+`renderDocToPng(doc, opts)` draws one image. For a GIF, an MP4, a contact sheet or a loop check, hold a
+renderer OPEN instead: the expensive setup — the `skia-canvas` import, writing and registering the
+embedded fonts, decoding every image asset, building the player, installing the Node globals — is paid
+once rather than per frame.
+
+```ts
+import { createRenderer } from '@flatkit/compiler/render'
+
+const r = await createRenderer(doc, { scale: 2, params: { door: 'open' } })
+try {
+  for (let f = 0; f < 300; f++) writeFileSync(`out/${f}.png`, await r.frame(f))
+} finally {
+  r.close()   // restores the globals and drops the temp fonts — not optional
+}
+```
+
+`params` sets a SYMBOL's exposed params before rendering — a state NAME or a number, the same spelling
+`--set` accepts, and now available on `--render` too (`flatc --render p.flatink --set door=open`). It was
+`--preview`-only, which is why anyone wanting to render a program in a given state wrote their own
+harness.
+
+> **Driving the player yourself under Node?** You need a `document` shim, or every `filter` and `tint` is
+> dropped — the frame still draws, the effect is simply gone. The player warns once when that happens.
+> `createRenderer` installs the shims for you; prefer it.
+
+### The same pass, from code — `checkProgram`
+
+The compiled Doc is **not enough** to validate a program. A text that is not FlatInk at all compiles to an
+empty Doc nothing distinguishes from a valid one, and an `object` block that binds to nothing leaves no
+trace either: both errors live in the SOURCE. `checkProgram` runs the whole `--check` pass on a string, so
+validating in a service or a browser no longer means spawning `flatc`:
+
+```ts
+import { checkProgram } from '@flatkit/compiler'
+
+const { ok, errors, warnings, report, doc } = checkProgram(srcFromAnLLM, { assetSrcs: [libText] })
+if (!ok) regenerate(report) // the report doubles as the repair prompt
+```
+
+Never throws: a source the parser rejects outright comes back as a diagnostic with `doc: null`. The CLI
+calls the same function, so the two verdicts cannot drift.
+
+It also flags the three **silent drops of a cel layer** (such a layer draws only the current cel's
+`matter` and the containers that cel poses): a bare shape left in the layer, a `pose "X"` naming no roster
+item, and a roster item no cel ever poses. Each renders an empty frame with no other signal — see
+[frame-by-frame](animating-symbols.md#frame-by-frame--a-different-drawing-on-each-cel).
+
+## See what you draw — `--render`
+
+Render a PNG (skia backend, faithful to the browser). Needs the optional `skia-canvas` dep
+(`npm i -D skia-canvas`).
+
+```
+flatc <file> --render -o out.png [--frame N] [--at k=v[,k2=v2]] [--steps N] [--scale S]
+```
+
+- `--frame N` target frame · `--scale S` resolution factor.
+- `--at score=3,step=2` forces variables → capture a precise state.
+- **`--steps N`** runs N fixed simulation steps (`every frame`, 60 Hz) *before* capture, so a stateful
+  act unfolds on its own — no need to force every derived ramp variable by hand.
+- **Embedded fonts render too**: any `asset "id" "font.woff2" font` is registered with skia before
+  capture, so text uses the authored face (matched by the font's intrinsic family name — the same name
+  you put in `text … font "…"`) instead of a host fallback. `.woff2/.woff/.ttf/.otf` are all supported;
+  flatc prints the registered families to stderr.
+- **Font family alias**: add a quoted name after `font` — `asset "id" "font.woff2" font "Quicksand"` —
+  to register the face under *that* family instead of the file's intrinsic one. Use it when a font's
+  name table is wrong (e.g. a variable-font static export skia reads as `… Thin/Light`), so the alias
+  matches the `text … font "Quicksand"` you authored. Browsers ignore it (they bind families via
+  `FontFace`); it only steers headless `--render`.
+
+## Preview a `.flat` symbol — `--preview`
+
+Wrap ONE symbol of a `.flat` library into a playable, auto-sized Doc — no hand-authored wrapper. Outputs a
+`.flatpack` (drop it in the browser player) or, with `--render`, a PNG.
+
+```
+flatc --preview <library.flat> [--symbol NAME] [-o out.flatpack | --render -o out.png]
+                [--bbox all|frame0] [--pad N] [--set p=v[,p2=v2]] [--frame N] [--scale S]
+```
+
+- `--symbol NAME` picks the symbol (default: the first; others are listed on stderr).
+- **`--bbox all`** (default) auto-sizes to the UNION of bounds over every frame (sub-timelines unfrozen),
+  so drifting/rotating/growing motion is never clipped. `--bbox frame0` is the old frame-0-only measure;
+  `--pad N` adds a margin (default 24).
+- **`--set p=v`** sets the symbol's exposed [params](animating-symbols.md#exposed-parameters-params): a
+  `color` (`hull=#1a5`), a `number`/`bool` (`wave=1.5`), or a `state` by name (`door=open`). Baked into the
+  preview (flatpack + render).
+- **`--scale auto`** picks the render factor from the symbol's size — enlarges small/thin assets (so a fine
+  filament stays legible) and leaves large ones at 1×. Otherwise `--scale S` (default 2).
+
+## Media packing — `--assets`
+
+```
+flatc <file> --assets inline      # default: media embedded as data: URIs → one portable .flatpack
+flatc <file> --assets external    # asset.data = relative key + a sidecar <out>.assets/ folder
+```
+
+Use `external` for big media you don't want inflating the JSON; serve the folder and play with
+`sameOriginAssetResolver(<flatpackUrl>)` (see `@flatkit/player`).
+
+## Headless play — `--play`
+
+Run a scene **without a canvas**, replay a gesture script, and print `{ sends, vars }` — great in CI.
+
+```
+flatc <file> --play --script gestures.json [--trace]
+```
+
+**Prefer semantic gestures** (by object NAME — robust, the engine resolves coordinates):
+
+```json
+[
+  { "type": "drag",    "source": "Card1", "target": "ZoneA" },
+  { "type": "tap",     "target": "Button" },
+  { "type": "scratch", "target": "Cover1" },
+  { "type": "connect", "source": "Word",  "target": "Picture" },
+  { "type": "key",     "name": "ArrowRight", "frames": 10 },
+  { "type": "wait",    "frames": 30 },
+  { "type": "expect",  "sends": ["win"], "vars": { "score": 3 } }
+]
+```
+
+- `drag` / `tap` / `scratch` (sweeps a `reveal` zone) / `connect` (pulls a `link` wire) — by name.
+- `set` drives a variable from the host; `wait` runs N fixed 60 Hz steps (advances `every frame` physics).
+- **`key`** holds a key down (`keys.<name>` reads `1`) for `frames` steps — default `1` — then releases
+  it: the way to test a keyboard-driven scene in CI. Use the authored name (`"ArrowRight"`, `"Space"`).
+- **`expect`** turns the script into a test: it compares the `send`s emitted since the last `expect` and
+  the current vars, and makes `--play` **exit ≠0** on mismatch. No more eyeballing. It matches the
+  **sequence of event names**; to assert a payload, read `sends` from the JSON output (each entry is the
+  object the host would receive: `{ name, value?, fields? }` — see
+  [host integration](host-integration.md#receiving-events-send--onevent)).
+- Low-level gestures (`down`/`move`/`up`/`cancel` with `x,y`) remain for special cases.
+- `--trace` prints a human-readable log per gesture (emitted sends + variable diff) instead of JSON —
+  a `send` shows as `name`, `name=value`, or `name{a=1, b=2}` for a record payload.
+
+### Recording
+
+In the player, `player.startRecording()` / `stopRecording(): Gesture[]` capture gestures you play by
+hand into a script that `--play` replays. (Authoring/CI helpers live in `@flatkit/player/debug`.)
+Pointer only — key presses are not captured; add the `key` gestures to the recorded script yourself.
+
+## Teaching the language to a model
+
+Three pieces, all pure functions — no filesystem, no canvas — so they work in a browser as well as in CI:
+
+```ts
+import { languageCard, drawingCard, docToManifest, llmContext, manifestObjects, manifestEvents } from '@flatkit/compiler'
+
+languageCard()      // BEHAVIOR: events, channels, expressions (function/constant lists interpolated
+                    // from the engine, so they cannot go stale)
+drawingCard()       // COMPOSITION: shapes, paints, filters, text, clipping, and the word order that
+                    // breaks most often. Its examples are compiled by a test — a copied reference drifts
+docToManifest(doc)  // the SCENE MAP alone: the names this scene can reference, and the contract below
+llmContext(doc)     // the bundle: both cards + the map. `{ drawing: false }` drops the drawing half
+```
+
+Pick `docToManifest` when you already inject the references yourself — `llmContext` is the everything-included
+bundle, and calling it in that case ships the cards twice.
+
+The scene map (`docToManifest`) ends with the **binding contract**: for each named object, the events the
+logic handles on it, whether it is dragged, whether it is a drop zone, the channels the logic drives, and
+the state it reads — plus the events the program emits. Deliberately **no coordinates**: that is what lets
+a second skin honour the same logic with a completely different composition.
+
+```
+contract (honour these; the layout is yours):
+  Flask - zone
+  TileH - drag, on drop, driven: x y opacity rotation, reads: xh yh rmix inO
+events: correct, completed, incorrect
+```
+
+Longer, hand-written prompts (a full reference plus one file per role — asset creator, motion designer,
+coder) ship with the package under `prompts/`; see [its README](../packages/compiler/prompts/README.md).
+
+## See also
+
+- The language itself → **[Scene & drawing](scene-and-drawing.md)** · **[Behavior & interactions](behavior-and-interactions.md)**
+- Wiring a scene into an app → **[Host integration](host-integration.md)**
+- Pitfalls & best practices → **[Gotchas](dsl-gotchas.md)**