@flatkit/compiler 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatkit/compiler",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "The FlatInk language (parser + AST) and compiler (.flatink → .flatpack). Ships the flatc CLI.",
   "license": "MIT",
   "author": "Zwyk Studio",
@@ -38,7 +38,14 @@
       "types": "./dist/analysis.d.ts",
       "import": "./dist/analysis.js",
       "require": "./dist/analysis.js"
-    }
+    },
+    "./render": {
+      "types": "./dist/cli/render.d.ts",
+      "import": "./dist/cli/render.js",
+      "require": "./dist/cli/render.js"
+    },
+    "./prompts/*": "./prompts/*",
+    "./docs/*": "./docs/*"
   },
   "bin": {
     "flatc": "./bin/flatc.mjs"
@@ -46,12 +53,13 @@
   "files": [
     "dist",
     "bin",
-    "prompts"
+    "prompts",
+    "docs"
   ],
   "dependencies": {
-    "@flatkit/engine": "0.25.0",
-    "@flatkit/types": "0.25.0",
-    "@flatkit/player": "0.25.0"
+    "@flatkit/engine": "0.27.0",
+    "@flatkit/types": "0.27.0",
+    "@flatkit/player": "0.27.0"
   },
   "peerDependencies": {
     "skia-canvas": "^3.0.8"
@@ -65,7 +73,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node ../../scripts/sync-docs.mjs",
     "typecheck": "tsc -p tsconfig.json"
   },
   "module": "./dist/index.js"

package/prompts/flatink-core.md

@@ -18,25 +18,25 @@ A `.flatink` is split in **two halves with different grammars**:
 ## `.flatink` skeleton
 
 ```
-size 480 320              # REQUIRED, must be the very first line (canvas units)
-background #0a0e1c        # optional
-timeline 30 300           # optional root timeline: fps, duration(frames). default 24 fps / 60 frames
-use "collision"           # optional stdlib/local packages
-asset "logo" "logo.svg" image   # optional media declarations
-var score = 0             # optional global state
+size 480 320              // REQUIRED, must be the very first line (canvas units)
+background #0a0e1c        // optional
+timeline 30 300           // optional root timeline: fps, duration(frames). default 24 fps / 60 frames
+use "collision"           // optional stdlib/local packages
+asset "logo" "logo.svg" image   // optional media declarations
+var score = 0             // optional global state
 
 scene {
   layer "bg"   { rect 0 0 480 320 fill #0a0e1c }
   layer "game" {
-    circle 240 160 40 fill #ffcc00 as "Sun"
+    group "Sun" at 240,160 { layer "art" { circle 0 0 40 fill #ffcc00 } }
   }
 }
 
-object "Sun" {
+object "Sun" {                  // behavior attaches BY NAME, to a group -- never to a bare shape
   when clicked { score = score + 1 }
-  rotation = time * 30
+  rotationDeg = clock * 30      // degrees; `clock` is monotone, `time` restarts every loop
 }
-every frame { if (score >= 10) { send "win" } }
+every frame { if score >= 10 { send "win" } }
 ```
 
 ## Drawing (inside `scene`/`symbol` layers)
@@ -46,24 +46,24 @@ Coordinates are plain numbers; canvas origin is **top-left**. Layers stack botto
 ```
 circle  <cx> <cy> <r>
 ellipse <cx> <cy> <rx> <ry>
-rect    <x> <y> <w> <h>  [<r> | <rx> <ry>]      # optional rounded corners
-path    "M0 0 L10 0 L10 10 Z"                    # raw SVG path data
+rect    <x> <y> <w> <h>  [<r> | <rx> <ry>]      // optional rounded corners
+path    "M0 0 L10 0 L10 10 Z"                    // raw SVG path data
 text    "Hi" font "sans-serif" size 24 align center line 1.2 color #fff box 200 40
-image   "logo" 80 80 at -40,-40                  # origin = top-left → center with at -w/2,-h/2
-group   "Name" at x,y pivot px,py { layer "c" { … } }   # nests its own layers
-instance "Symbol" as "Name" at x,y              # place a symbol from a .flat lib
+image   "logo" 80 80 at -40,-40                  // origin = top-left → center with at -w/2,-h/2
+group   "Name" at x,y pivot px,py { layer "c" { … } }   // nests its own layers
+instance "Symbol" as "Name" at x,y              // place a symbol from a .flat lib
 ```
 
 Paint / style (work on shapes; most on text & groups too):
 ```
 fill #rrggbb | nofill
 stroke #rrggbb <width> [cap butt|round|square] [join …] [miter n] [dash a,b,…]
-opacity 0..1                                       # also 8-digit hex alpha #rrggbbaa
-fill linear(90, 0:#bdecff, 1:#2f8fe0)              # angle 0 = →, 90 = ↓ ; stops offset:color
-fill radial(0.5, 0.5, 0.5, 0:#fff, 1:#000)         # cx, cy, r (0..1), then stops
+opacity 0..1                                       // also 8-digit hex alpha #rrggbbaa
+fill linear(90, 0:#bdecff, 1:#2f8fe0)              // angle 0 = →, 90 = ↓ ; stops offset:color
+fill radial(0.5, 0.5, 0.5, 0:#fff, 1:#000)         // cx, cy, r (0..1), then stops
 filter glow <blur> <color> | shadow <dx> <dy> <blur> <color> | blur <r> | adjust <b> <c> <s> <h>
-tint <color> <amount(0..1)>                        # Flash-style tint
-nohit                                              # drawn but ignored by hit-test
+tint <color> <amount(0..1)>                        // Flash-style tint
+nohit                                              // drawn but ignored by hit-test
 ```
 
 ## Animation — timeline / cel / pose (in a `symbol`)
@@ -74,13 +74,13 @@ the **poses** of containers declared once in the layer roster, plus (optionally)
 
 ```
 symbol "Wheel" {
-  timeline 24 24                          # fps, durationFrames
+  timeline 24 24                          // fps, durationFrames
   layer "spin" {
-    group "Rim" at 100,100 pivot 0,0 {    # roster: declared ONCE, posed by the cels below
+    group "Rim" at 100,100 pivot 0,0 {    // roster: declared ONCE, posed by the cels below
       layer "art" { circle 0 0 40 nofill stroke #333 8 }
     }
     cel 0 tween { pose "Rim" rotate 0 }
-    cel 24       { pose "Rim" rotate 360 }   # one full turn around the pivot, in DEGREES
+    cel 24       { pose "Rim" rotate 360 }   // one full turn around the pivot, in DEGREES
   }
 }
 
@@ -117,9 +117,9 @@ Additive position offsets: `dx dy` → **`pos = at + (dx, dy)`** (binding-only;
 
 ```
 object "Needle" {
-  rotation = atan2(mouse.y - 160, mouse.x - 240)   # RADIANS
+  rotation = atan2(mouse.y - 160, mouse.x - 240)   // RADIANS
   opacity  = lit ? 1 : 0.3
-  dx = 30 * sin(clock)                             # sways AROUND its declared at — no base to re-inject
+  dx = 30 * sin(clock)                             // sways AROUND its declared at — no base to re-inject
 }
 ```
 Or bind a channel on a symbol container directly: `group "Fan" pivot 0,0 expr rotation "turns(time)" { … }`.
@@ -128,9 +128,9 @@ Or bind a channel on a symbol container directly: `group "Fan" pivot 0,0 expr ro
 snapping to it. Per instance, zero cost when unused, and it snaps to the target on a seek (so tune it by
 PLAYING the preview, not by scrubbing).
 ```
-group "Cable" spring rotation "hookX" stiffness 0.08 damping 0.86 { … }   # in a .flat: overshoot, settle
-group "Panel" smooth y "target" k 0.15 { … }                              # 1st order: no overshoot
-object "Dial" { spring rotation = aim { stiffness 0.08 damping 0.86 } }   # scene-side form, in .flatink
+group "Cable" spring rotation "hookX" stiffness 0.08 damping 0.86 { … }   // in a .flat: overshoot, settle
+group "Panel" smooth y "target" k 0.15 { … }                              // 1st order: no overshoot
+object "Dial" { spring rotation = aim { stiffness 0.08 damping 0.86 } }   // scene-side form, in .flatink
 ```
 The quoted target's names must EXIST in that scope (a symbol `param`, a scene `var`) or `--check` errors.
 
@@ -145,37 +145,37 @@ Actions (one per line): `<var> = <expr>` · `arr[i] = <expr>` · `if/else if/els
 
 Drag & interactors (each writes into your vars; all accept `{ enabled <expr> }`):
 ```
-drag x, y [{ confine to <Zone> · snap <grid> · enabled <expr> }]   # dragX / dragY too
-turn    <angle> around <x>,<y> [{ snap <deg> }]    # → <angle> in RADIANS → rotation = <angle> directly
-turnDeg <angle> around <x>,<y> [{ snap <deg> }]    # → <angle> in DEGREES → pair with rotationDeg = <angle>
-trace <progress> along <Group> [{ tolerance <px> }]# follow a path → 0..1 monotone
-reveal <progress> [{ brush <px> }]                 # scratch/wipe → 0..1 cumulative
-link  <endX>,<endY>,<target> to <Group>            # elastic thread → target = hit index 1..n (0=none)
+drag x, y [{ confine to <Zone> · snap <grid> · enabled <expr> }]   // dragX / dragY too
+turn    <angle> around <x>,<y> [{ snap <deg> }]    // → <angle> in RADIANS → rotation = <angle> directly
+turnDeg <angle> around <x>,<y> [{ snap <deg> }]    // → <angle> in DEGREES → pair with rotationDeg = <angle>
+trace <progress> along <Group> [{ tolerance <px> }]// follow a path → 0..1 monotone
+reveal <progress> [{ brush <px> }]                 // scratch/wipe → 0..1 cumulative
+link  <endX>,<endY>,<target> to <Group>            // elastic thread → target = hit index 1..n (0=none)
 ```
 
 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)
-feedback lift tilt dim shake(<expr>)                     # one-liner reactions (auto use "feedback")
+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)
+feedback lift tilt dim shake(<expr>)                     // one-liner reactions (auto use "feedback")
 ```
 
 ## Factoring (compile-time, zero runtime cost)
 
 ```
-def gap = 70                                             # compile-time constant, used via $()
-repeat i from 0 to 4 { circle $(40 + i*gap) 80 6 fill #ffd98a }   # $(expr) = compile-time arithmetic
-symbol "Card"(label, tint = "#fff") { … text "$(label)" … fill $(tint) … }   # parameterized symbol
+def gap = 70                                             // compile-time constant, used via $()
+repeat i from 0 to 4 { circle $(40 + i*gap) 80 6 fill #ffd98a }   // $(expr) = compile-time arithmetic
+symbol "Card"(label, tint = "#fff") { … text "$(label)" … fill $(tint) … }   // parameterized symbol
 instance "Card"($(i+1)) as "C$(i)" at $(80 + i*90),200
-each "Key" as i { when clicked { input = input*10 + (i+1) } }    # shared behavior over instances
-match Word1, Word2 onto Good, Bad {                       # declarative drag+drop pairing
+each "Key" as i { when clicked { input = input*10 + (i+1) } }    // shared behavior over instances
+match Word1, Word2 onto Good, Bad {                       // declarative drag+drop pairing
   correct Word1 -> Good, Word2 -> Bad
   on done { send "win" }
 }
-at center | at center,540 | at 120,center                # canvas-relative anchor
-align top of "Bin" [offset dx,dy]                         # pin origin onto another item's bbox
+at center | at center,540 | at 120,center                // canvas-relative anchor
+align top of "Bin" [offset dx,dy]                         // pin origin onto another item's bbox
 ```
 
 ## Expressions & stdlib
@@ -195,6 +195,9 @@ ramp over `dur` s for a readable timed feedback — capture the instant with **`
 
 ## CRITICAL GOTCHAS — do not get these wrong
 
+0. **A comment is `//`, everywhere.** `#` opens a COLOUR (`#ffcc00`). Used as a comment it survives in
+   the header half and is a parse ERROR inside `scene { … }` — reported as `"layer" expected, "#" found`,
+   which points nowhere near the real cause.
 1. **`size W H` is required and MUST be the first line** of a `.flatink`. A `.flat` has no `size`.
 2. **Two grammars.** Drawing keywords live in `scene`/`symbol` layers; logic keywords live in
    `object`/`every frame`/`fn`. Don't mix (no `var`/`when` inside `scene`; no `circle` inside `object`).

package/prompts/flatink-lite.md

@@ -2,6 +2,7 @@
 
 You write **FlatInk**, a text language for animations & interactive scenes. Output **only valid source**
 in one fenced block. You won't have a compiler — get it right in one pass. Keep DSL keywords in English.
+**Comments are `//`, everywhere. `#` opens a COLOUR, and breaks inside `scene { … }`.**
 
 ## Two file types
 - **`.flat`** = a symbol library: one or more `symbol "Name" { … }`. **No `size` line.** Not playable alone.
@@ -12,27 +13,29 @@ group/instance); everything after = behavior (`object`, `every frame`, `var`, `f
 
 ## `.flatink` skeleton
 ```
-size 480 320                       # REQUIRED first line (canvas units; origin = top-left)
-background #0a0e1c                  # optional
-var score = 0                      # optional global runtime state
+size 480 320                       // REQUIRED first line (canvas units; origin = top-left)
+background #0a0e1c                 // optional
+var score = 0                      // optional global runtime state
 scene {
-  layer "bg"   { rect 0 0 480 320 fill #0a0e1c }      # layers stack bottom → top
-  layer "game" { circle 240 160 40 fill #ffcc00 as "Sun" }   # `as` names an item for behavior
+  layer "bg"   { rect 0 0 480 320 fill #0a0e1c }             // layers stack bottom -> top
+  layer "game" {
+    group "Sun" at 240,160 { layer "art" { circle 0 0 40 fill #ffcc00 } }
+  }
 }
-object "Sun" {                     # behavior attaches by name
+object "Sun" {                     // behavior attaches by name, to a GROUP (a bare shape is an error)
   when clicked { score = score + 1 }
-  rotation = time * 30             # channel binding, every frame (RADIANS)
+  rotationDeg = clock * 30         // channel binding, every frame (degrees; `clock` never wraps)
 }
-every frame { if (score >= 10) { send "win" } }
+every frame { if score >= 10 { send "win" } }
 ```
 
 ## Drawing (in scene/symbol layers)
 ```
 circle cx cy r   ·   ellipse cx cy rx ry   ·   rect x y w h [r | rx ry]   ·   path "M0 0 L10 0 L10 10 Z"
 text "Hi" font "sans-serif" size 24 align center line 1.2 color #fff box 200 40 [bold] [italic] [wrap]
-image "id" w h at -w/2,-h/2        # origin top-left → center yourself ; needs: asset "id" "f.png" image
-group "Name" at x,y pivot px,py { layer "c" { … } }      # nests its own layers
-instance "Symbol" as "Name" at x,y                        # place a symbol from a .flat
+image "id" w h at -w/2,-h/2        // origin top-left → center yourself ; needs: asset "id" "f.png" image
+group "Name" at x,y pivot px,py { layer "c" { … } }      // nests its own layers
+instance "Symbol" as "Name" at x,y                        // place a symbol from a .flat
 ```
 Style: `fill #rrggbb | nofill` · `stroke #rgb <w> [cap round][join round][dash a,b]` · `opacity 0..1` ·
 `fill linear(90, 0:#a, 1:#b)` (0=→,90=↓) · `fill radial(0.5,0.5,0.5, 0:#fff,1:#000)` ·
@@ -41,13 +44,13 @@ Style: `fill #rrggbb | nofill` · `stroke #rgb <w> [cap round][join round][dash
 ## Animation (in a symbol): timeline / cel / pose
 ```
 symbol "Wheel" {
-  timeline 24 24                              # fps, durationFrames (loops [0,dur))
+  timeline 24 24                              // fps, durationFrames (loops [0,dur))
   layer "spin" {
-    group "Rim" at 100,100 pivot 0,0 {        # roster: declared ONCE, posed by cels below
+    group "Rim" at 100,100 pivot 0,0 {        // roster: declared ONCE, posed by cels below
       layer "art" { circle 0 0 40 nofill stroke #333 8 }
     }
-    cel 0 tween { pose "Rim" rotate 0 }       # tween = interpolate to next cel; no tween = hold
-    cel 24       { pose "Rim" rotate 360 }    # DEGREES, around the pivot
+    cel 0 tween { pose "Rim" rotate 0 }       // tween = interpolate to next cel; no tween = hold
+    cel 24       { pose "Rim" rotate 360 }    // DEGREES, around the pivot
   }
 }
 pose "Name" [at x,y] [rotate deg] [scale s | scaleX sx scaleY sy] [opacity o] [spin cw|ccw] [turns n]
@@ -64,9 +67,9 @@ Actions (one per line): `<var> = <expr>` · `arr[i] = <expr>` · `if/else if/els
 `repeat i from a to b {}` · `play`/`pause` · `go to frame n [and play]` · `send "evt" [, <expr> | , text("id") | , { a = <expr>, b }]` · `sound "id"`.
 Drag/interactors (write into your vars; all take `{ enabled <expr> }`):
 ```
-drag x, y [{ confine to <Zone> · snap <grid> }]    # then USE them: x = px  y = py
+drag x, y [{ confine to <Zone> · snap <grid> }]    // then USE them: x = px  y = py
 turn <angle> around x,y    ·    trace <progress> along <Group>    ·    reveal <progress>
-link endX,endY,target to <Group>     # target = hit index 1..n (0=none), WORLD coords
+link endX,endY,target to <Group>     // target = hit index 1..n (0=none), WORLD coords
 ```
 Self-state & feedback: `self.hovered self.grabbed self.pressed` (0/1) ·
 `feedback lift tilt dim shake(<expr>)`.

package/prompts/role-asset-creator.md

@@ -11,10 +11,10 @@ Author verifies with `flatc --preview Asset.flat --render -o out.png`.
 
 ```
 symbol "Mug" {
-  layer "back" { ellipse 0 30 26 8 fill #00000022 }     # layers stack bottom → top
+  layer "back" { ellipse 0 30 26 8 fill #00000022 }     // layers stack bottom → top
   layer "body" {
     path "M-22 -28 L22 -28 L18 28 L-18 28 Z" fill #e8553a stroke #b23a24 3 join round
-    path "M22 -18 a14 14 0 0 1 0 28" nofill stroke #b23a24 5 cap round   # handle
+    path "M22 -18 a14 14 0 0 1 0 28" nofill stroke #b23a24 5 cap round   // handle
   }
 }
 ```
@@ -26,20 +26,20 @@ symbol "Mug" {
 
 ```
 circle  cx cy r              ellipse cx cy rx ry
-rect    x y w h [r | rx ry]  path "M… L… C… Z"      # raw SVG path data
+rect    x y w h [r | rx ry]  path "M… L… C… Z"      // raw SVG path data
 text    "Hi" font "sans-serif" size 24 align center line 1.2 color #fff box 200 40 [bold] [italic]
-image   "id" w h at -w/2,-h/2     # needs: asset "id" "file.png" image  (declared in the .flatink that uses it)
+image   "id" w h at -w/2,-h/2     // needs: asset "id" "file.png" image  (declared in the .flatink that uses it)
 ```
 
 Paint & finish:
 ```
 fill #rrggbb | nofill
 stroke #rrggbb <width> [cap butt|round|square] [join round|bevel|miter] [miter n] [dash a,b]
-opacity 0..1                                          # or 8-digit hex alpha #rrggbbaa
-fill linear(90, 0:#bdecff, 1:#2f8fe0)                 # angle 0 = →, 90 = ↓
-fill radial(0.5, 0.5, 0.5, 0:#fff, 1:#000)            # cx, cy, r in 0..1, then stops
+opacity 0..1                                          // or 8-digit hex alpha #rrggbbaa
+fill linear(90, 0:#bdecff, 1:#2f8fe0)                 // angle 0 = →, 90 = ↓
+fill radial(0.5, 0.5, 0.5, 0:#fff, 1:#000)            // cx, cy, r in 0..1, then stops
 filter glow <blur> <color> | shadow <dx> <dy> <blur> <color> | blur <r> | adjust <b> <c> <s> <h>
-tint <color> <amount(0..1)>      nohit                # nohit = drawn but click-through
+tint <color> <amount(0..1)>      nohit                // nohit = drawn but click-through
 ```
 
 ## Repetition without copy-paste (compile-time)
@@ -47,7 +47,7 @@ tint <color> <amount(0..1)>      nohit                # nohit = drawn but click-
 ```
 def n = 6
 layer "rays" {
-  repeat i from 0 to n { rect -2 -40 4 16 fill #ffd24d }   # $(…) interpolates compile-time math
+  repeat i from 0 to n { rect -2 -40 4 16 fill #ffd24d }   // $(…) interpolates compile-time math
 }
 ```
 `$(expr)` injects arithmetic into any coordinate: `circle $(60 + i*40) 80 6 …`. Nested loops = grids.
@@ -64,8 +64,8 @@ symbol "Boat" {
     bool  flag = true              "Show the pennant"
   }
   layer "body" {
-    path "M-40 0 L40 0 L24 20 L-24 20 Z" fill hull       # a color param used as a fill…
-    path "M0 -50 L0 0 L26 -10 Z"          fill sail       # …or stroke <param> <width>
+    path "M-40 0 L40 0 L24 20 L-24 20 Z" fill hull       // a color param used as a fill…
+    path "M0 -50 L0 0 L26 -10 Z"          fill sail       // …or stroke <param> <width>
   }
 }
 ```

package/prompts/role-coder.md

@@ -6,30 +6,29 @@ and the declarative factoring sugar. You wire behavior to named scene items.
 **Output contract:** a `.flatink` program. Emit **only the code** in a fenced block. Verify and test
 headlessly (no browser):
 ```
-flatc game.flatink --check                              # semantic + layout lint (exit ≠0 on ERROR)
-flatc game.flatink --play --script gestures.json --trace # replay gestures, see sends + var diffs
+flatc game.flatink --check                              // semantic + layout lint (exit ≠0 on ERROR)
+flatc game.flatink --play --script gestures.json --trace // replay gestures, see sends + var diffs
 ```
 
 ## File shape — TWO grammars, one file
 
 ```
-size 480 320              # REQUIRED, first line
+size 480 320              // REQUIRED, first line
 background #0a0e1c
-use "collision"           # stdlib: collision | easing | gesture | feedback
-var score = 0             # global runtime state (top of file)
+use "collision"           // stdlib: collision | easing | gesture | feedback
+var score = 0             // global runtime state (top of file)
 
-scene {                   # ── HALF 1: composition (what you see) ──
+scene {                   // -- HALF 1: composition (what you see) --
   layer "game" {
-    circle 240 160 40 fill #ffcc00 as "Sun"   # `as` names an item for behavior
-    instance "Card" as "C1" at 100,100
+    group "Sun" at 240,160 { layer "art" { circle 0 0 40 fill #ffcc00 } }
   }
 }
 
-object "Sun" {            # ── HALF 2: behavior, attaches by name ──
+object "Sun" {            // -- HALF 2: behavior, attaches by name --
   when clicked { score = score + 1 }
-  rotation = time * 90    # channel binding, evaluated every frame
+  rotationDeg = clock * 90   // channel binding, evaluated every frame
 }
-every frame { if (score >= 10) { send "win" } }
+every frame { if score >= 10 { send "win" } }
 ```
 **Drawing keywords (`circle`, `path`, `group`…) live ONLY in `scene`. Logic keywords (`var`, `when`,
 `object`, `fn`, `if`) live ONLY after it.** They don't share a grammar.
@@ -37,16 +36,16 @@ every frame { if (score >= 10) { send "win" } }
 ## State, events, actions
 
 ```
-var score = 0    var slots = [0,0,0]    var seen = fill(8, 0)     # arrays via literal or fill(n,v)
+var score = 0    var slots = [0,0,0]    var seen = fill(8, 0)     // arrays via literal or fill(n,v)
 ```
 Events (in `object "Name"`): `when clicked | hovered | unhovered | pressed | released | dragged | held
 | dropped on <Zone> [at pointer]`. Scene-wide: `when loaded`, `every frame`, `at frame <n>`.
 
 Actions — **one per line**:
 ```
-<var> = <expr>          arr[<expr>] = <expr>          # `set` keyword optional; nested indices ok
+<var> = <expr>          arr[<expr>] = <expr>          // `set` keyword optional; nested indices ok
 if <c> { … } [else if <c> { … }] [else { … }]
-repeat <n> times { … }          repeat i from a to b { … }      # RUNTIME loops (bounded)
+repeat <n> times { … }          repeat i from a to b { … }      // RUNTIME loops (bounded)
 play   pause   go to frame <n> [and play|and pause]   go to "<label>" [and play]
 send "<evt>" [, <expr> | , text("<id>") | , { a = <expr>, b }]   sound "<assetId>"   <fn>(<args>)
 ```
@@ -57,14 +56,14 @@ Drive `x y scaleX scaleY rotation opacity` (absolute) every frame, plus `dx dy`
 offsets, `pos = at + (dx, dy)`:
 ```
 object "Needle" {
-  rotation = atan2(mouse.y - 160, mouse.x - 240)   # RADIANS
+  rotation = atan2(mouse.y - 160, mouse.x - 240)   // RADIANS
   opacity  = lit ? 1 : 0.3
-  dx = 30 * sin(clock)                             # sways AROUND its declared at — no base to re-inject
+  dx = 30 * sin(clock)                             // sways AROUND its declared at — no base to re-inject
 }
 ```
 Chase a target with inertia instead of snapping to it:
 ```
-object "Dial" { spring rotation = aim { stiffness 0.08 damping 0.86 } }   # smooth y = target { k 0.15 }
+object "Dial" { spring rotation = aim { stiffness 0.08 damping 0.86 } }   // smooth y = target { k 0.15 }
 ```
 Pure numeric expressions (no booleans — logic/compares yield `1`/`0`). Operators `?: || && == != < >
 <= >= + - * / % - ! . [] fn()`. Built-ins: `sin cos tan atan2 abs sqrt pow exp log floor ceil round
@@ -77,15 +76,15 @@ Functions: `fn dist(ax,ay,bx,by) = hypot(ax-bx, ay-by)` (value) · `fn reset() {
 
 ```
 object "Piece" {
-  drag px, py { confine to Board · snap 20 }     # dragX / dragY for one axis
-  x = px   y = py                                 # USE the vars it writes
+  drag px, py { confine to Board · snap 20 }     // dragX / dragY for one axis
+  x = px   y = py                                 // USE the vars it writes
   when dropped on Slot at pointer { placed = 1 }
 }
-turn    <angle> around x,y [{ snap <deg> }]       # → RADIANS → rotation = <angle> directly
-turnDeg <angle> around x,y [{ snap <deg> }]       # → DEGREES → pair with rotationDeg = <angle>
-trace <progress> along <Group> [{ tolerance <px> }]  # follow path → 0..1 monotone
-reveal <progress> [{ brush <px> }]                # scratch/wipe grabbed area → 0..1 cumulative
-link  endX,endY,target to <Group>                 # elastic thread; target = hit index 1..n (0=none), WORLD coords
+turn    <angle> around x,y [{ snap <deg> }]       // → RADIANS → rotation = <angle> directly
+turnDeg <angle> around x,y [{ snap <deg> }]       // → DEGREES → pair with rotationDeg = <angle>
+trace <progress> along <Group> [{ tolerance <px> }]  // follow path → 0..1 monotone
+reveal <progress> [{ brush <px> }]                // scratch/wipe grabbed area → 0..1 cumulative
+link  endX,endY,target to <Group>                 // elastic thread; target = hit index 1..n (0=none), WORLD coords
 ```
 
 ## Feedback (reactions without handlers)
@@ -93,7 +92,7 @@ link  endX,endY,target to <Group>                 # elastic thread; target = hit
 ```
 object "Tile" {
   x = tx   y = ty
-  feedback lift tilt dim shake(wrongZone)   # lift=hover grow · tilt=grab squash · dim=hover dim · shake=wobble
+  feedback lift tilt dim shake(wrongZone)   // lift=hover grow · tilt=grab squash · dim=hover dim · shake=wobble
 }
 ```
 Or read state directly: `scaleX = self.hovered ? 1.06 : 1`, `scaleY = self.grabbed ? 0.94 : 1`.
@@ -102,19 +101,19 @@ Or read state directly: `scaleX = self.hovered ? 1.06 : 1`, `scaleY = self.grabb
 
 ```
 def gap = 70
-repeat i from 0 to 4 { circle $(40 + i*gap) 80 6 fill #ffd98a }      # $(…) = compile-time math
+repeat i from 0 to 4 { circle $(40 + i*gap) 80 6 fill #ffd98a }      // $(…) = compile-time math
 symbol "Key"(label) { layer "c" { rect -28 -28 56 56 fill #e8e8e8
   text "$(label)" font "sans-serif" size 24 align center line 1.2 color #111 box 56 56 } }
 scene { layer "Pad" {
   repeat i from 0 to 8 { instance "Key"($(i+1)) as "K$(i)" at $(70 + (i%3)*80),$(80 + floor(i/3)*80) }
 } }
-each "Key" as i { when clicked { input = input*10 + (i+1) } }        # one handler per generated instance
+each "Key" as i { when clicked { input = input*10 + (i+1) } }        // one handler per generated instance
 ```
 `match` factors a whole drag+drop matching activity:
 ```
 match Word1, Word2 onto Good, Bad {
   correct Word1 -> Good, Word2 -> Bad
-  lock on wrong                              # optional; absent = retryable
+  lock on wrong                              // optional; absent = retryable
   on correct as it { send "found", text(it) }
   on done { send "win" }
 }

package/prompts/role-motion-designer.md

@@ -6,9 +6,9 @@ pivots, expression-driven channels, and named states. You think in keyframes, ar
 **Output contract:** usually a `.flat` (animated `symbol`s). Emit **only the code** in a fenced block.
 A `.flat` has **no `size`**. Author previews with:
 ```
-flatc --preview Wheel.flat --render -o wheel.png        # PNG of one frame (default --bbox all, union)
-flatc --preview Wheel.flat -o wheel.flatpack            # playable file for the browser
-flatc --preview Door.flat --render --set door=0.5 -o half.png   # a state / param value
+flatc --preview Wheel.flat --render -o wheel.png        // PNG of one frame (default --bbox all, union)
+flatc --preview Wheel.flat -o wheel.flatpack            // playable file for the browser
+flatc --preview Door.flat --render --set door=0.5 -o half.png   // a state / param value
 ```
 
 ## The model in one paragraph
@@ -22,11 +22,11 @@ containers in the layer's **roster** (declared ONCE above the cels). Between two
 symbol "Wheel" {
   timeline 24 24
   layer "spin" {
-    group "Rim" at 100,100 pivot 0,0 {          # roster: declared once, posed below
+    group "Rim" at 100,100 pivot 0,0 {          // roster: declared once, posed below
       layer "art" { circle 0 0 40 nofill stroke #333 8 }
     }
     cel 0 tween { pose "Rim" rotate 0 }
-    cel 24       { pose "Rim" rotate 360 }       # one full turn around the pivot, in DEGREES
+    cel 24       { pose "Rim" rotate 360 }       // one full turn around the pivot, in DEGREES
   }
 }
 ```
@@ -75,7 +75,7 @@ A cel is a **full snapshot**: a container is shown only on cels that `pose` it;
 **disappears** there (that's how a symbol exits). To avoid re-typing unchanged containers:
 ```
 cel 0  tween { pose "Base" at 0,0   pose "Ring" scale 1 }
-cel 30 hold tween { pose "Ring" scale 4 }   # Base carried forward automatically
+cel 30 hold tween { pose "Ring" scale 4 }   // Base carried forward automatically
 cel 60 hold       { pose "Ring" scale 1 }
 ```
 Or keep a truly static element on its **own cel-less layer** (rendered every frame, declared once).
@@ -84,7 +84,7 @@ Or keep a truly static element on its **own cel-less layer** (rendered every fra
 
 Bind a channel on a container to a formula:
 ```
-group "Fan" pivot 0,0 expr rotation "turns(time)" { … }     # one turn per second
+group "Fan" pivot 0,0 expr rotation "turns(time)" { … }     // one turn per second
 ```
 - Channels: `x y scaleX scaleY rotation opacity` (absolute), plus **`dx` / `dy`** — additive position
   offsets, `pos = at + (dx, dy)`. Prefer them for motion AROUND a rest position: `expr dx "30*sin(clock)"`
@@ -101,15 +101,15 @@ unused, and **snaps to the target on a seek** — so tune it by PLAYING the prev
 
 ```
 symbol "Cable" {
-  params { number hookX = 0 range -1 1 "Hook offset" }        # the target must be a NAME this scope knows
+  params { number hookX = 0 range -1 1 "Hook offset" }        // the target must be a NAME this scope knows
   timeline 24 24
   layer "a" {
-    group "Swing" spring rotation "hookX" stiffness 0.08 damping 0.86 {   # 2nd order: overshoots, settles
+    group "Swing" spring rotation "hookX" stiffness 0.08 damping 0.86 {   // 2nd order: overshoots, settles
       layer "c" { rect -4 0 8 60 fill #333333 }
     }
   }
 }
-group "Leaf" smooth y "target" k 0.15 { … }                    # 1st order: no overshoot
+group "Leaf" smooth y "target" k 0.15 { … }                    // 1st order: no overshoot
 ```
 - `stiffness` / `damping` / `k` are all `0..1`. Low stiffness = lazy; damping near 1 = few oscillations.
 - The target is a quoted expression, and its names must EXIST in that scope (a symbol `param`, a scene
@@ -126,8 +126,8 @@ symbol "Door" {
   states door { closed at 0   open at 24   initial closed   transition 12 ease easeInOut }
   layer "panel" {
     group "Panel" at 60,10 pivot 0,0 { layer "art" { rect 0 0 40 80 fill #884422 } }
-    cel 0 tween { pose "Panel" rotate 0 }      # closed
-    cel 24       { pose "Panel" rotate 80 }    # open
+    cel 0 tween { pose "Panel" rotate 0 }      // closed
+    cel 24       { pose "Panel" rotate 80 }    // open
   }
 }
 ```