@flatkit/compiler 0.38.0 → 0.39.0

package/docs/behavior-and-interactions.md

@@ -27,7 +27,7 @@ Inside `object "Name" { … }`:
 | `when held` | a long press |
 | `when dropped on <Zone> [at pointer]` | released over a drop zone (see [drag & drop](#drag--drop)) |
 
-Scene-wide: `when loaded { … }` (once), `every frame { … }` (each tick), `at frame <n> { … }`,
+Scene-wide: `when loaded { … }` (once), `every frame { … }` (each simulation step, 60 Hz — see [how a frame runs](#how-a-frame-runs)), `at frame <n> { … }`,
 `label <frame> "name"`. These live at the TOP LEVEL of the program, outside any `object` block — inside
 one they do nothing, and `--check` says so.
 
@@ -501,6 +501,45 @@ match Word1, Word2 onto Good, Bad {
 It generates, per item, `<Item>_placed` / `<Item>_ok` / `<Item>_zone` state and the drag+drop handlers;
 you keep the visual (`var <Item>_x`/`_y` + your channel expressions).
 
+## How a frame runs
+
+Three things happen, always in this order, and knowing it removes most "it reads the old value" surprises.
+
+**1. Events, as they arrive.** A press, a move, a release or a key runs its handlers **at once**, between
+two displays — not at the next step. At a release the order is: the gesture's outputs are written (drag
+position, `link` target), then `when released`, then `when dropped on …` (in declaration order), then
+`when clicked` if the press stayed a tap.
+
+**2. Steps of the simulation.** `every frame { … }` runs at a **fixed 60 Hz**: one run is one step of
+exactly 1/60 s, **whatever the `timeline` fps and whatever the display**. `timeline 30 …` only sets the
+speed of the playhead: after 60 steps `clock` has advanced by 1 and `frame` by 30. The step has a name,
+**`DT`** (= 1/60, in seconds), so an integration is written `v = v + a * DT` — never measure it from
+`clock`. In a browser `clock`, `time` and `frame` follow REAL time, once per display, so two steps run in
+the same display read the same `clock`; `clock - previous` is then the display's duration on the first and
+`0` on the second. (`flatc --play` advances them by 1/60 per step, which is why a replay is exact.)
+
+How many steps run before each display depends on the display: none or one at 120 Hz, one at 60 Hz, two at
+30. When the display stalls (a tab in the background, a slow device) the player does **not** catch up: it
+counts at most 0.25 s per display and runs at most 30 steps, dropping the rest. The simulation then runs
+slower than the wall clock; it never jumps. Within a step, the scene's `every frame` runs first, then
+those of the active symbols; `at frame <n>` scripts come after, in the same step.
+
+**3. The picture.** Channel bindings (`x = px`, `opacity = lit`) are not statements that run: they are
+read whenever something looks at the object — when it is drawn, when it is hit-tested, when a handler
+reads `Target.x` — and always give the value of NOW. What is drawn between two steps is interpolated
+between them, for smoothness; variables are never changed by that.
+
+What follows from it:
+
+- **A handler reads a derived value as the last step left it.** If `every frame { double = count * 2 }`
+  and a handler does `count = count + 1` then reads `double`, it reads the value from BEFORE its own
+  write. Two events between two steps: the second sees what the first *wrote*, not what `every frame`
+  derives from it. Derive in the handler what the handler needs, or make it a function (`fn`).
+- **`flatc --play` gives every pointer event one step** (see [tooling](tooling.md#headless-play----play)),
+  as a real pointer does; `"settle": 0` replays two events with no step in between, which is the case above.
+- **The step is guaranteed**; the number of steps per display is not. A rule that counts steps counts
+  sixtieths of a second of simulated time.
+
 ## See also
 
 - The expression language and stdlib → **[Expressions & stdlib](expressions-and-stdlib.md)**

package/docs/dsl-gotchas.md

@@ -10,6 +10,11 @@
 - 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.
+- **`every frame` is a 60 Hz simulation step, not a timeline frame.** One run is exactly 1/60 s —
+  the constant **`DT`** — whatever `timeline <fps>` says and whatever the display does; integrate with
+  `v = v + a * DT`, never with a `dt` measured from `clock`. Handlers run when their event arrives,
+  BEFORE the next step: a handler that reads a value derived in `every frame` reads the one of the last
+  step. The full order is in [how a frame runs](behavior-and-interactions.md#how-a-frame-runs).
 
 ## `object "X"` addresses an ANIMATABLE item — a group, instance, text or image
 

package/docs/expressions-and-stdlib.md

@@ -30,7 +30,8 @@ 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`.
+Constants: `PI`, `TAU` (2π), `E`, and **`DT`** — the duration of one `every frame` step, in seconds: 1/60,
+whatever the timeline's fps (`v = v + a * DT`). See [how a frame runs](behavior-and-interactions.md#how-a-frame-runs).
 
 > **`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
@@ -70,6 +71,38 @@ its index are expressions, only the element picked is evaluated, and it indexes
 index is rounded; outside the table it is `NaN`, so the binding keeps its fallback). It is not a value on
 its own: `[1, 2, 3]` without an index is an error — to keep a table, declare `var t = [1, 2, 3]`.
 
+## Determinism
+
+For someone replaying a simulation elsewhere (a Python replica, a test that compares to the bit), what can
+be counted on. Numbers are IEEE 754 doubles, and an expression is evaluated in the order it is written,
+one rounded operation at a time (no fused multiply-add).
+
+- **Exact** — the same bits on every engine: the operators `+ - * / %` and the comparisons, and `abs`
+  `floor` `ceil` `round` `sign` `min` `max` `sqrt` `clamp` `lerp` `mod` `between` `rad` `deg` `turns`.
+  (`sqrt` is the IEEE square root, correctly rounded on every engine in use, although ECMAScript does not
+  formally demand it. `rad`, `deg` and `turns` multiply by the double `PI`: exact, provided the replica
+  does the same operations in the same order — `rad(d)` is `d * PI / 180`.)
+- **Engine-dependent** — ECMAScript leaves the last bits to the implementation: `sin` `cos` `tan` `asin`
+  `acos` `atan` `atan2` `pow` `exp` `log` `hypot`. Two browsers usually agree, and nothing guarantees
+  it; a Python or C library need not agree with either. Integrated over thousands of steps, one bit
+  becomes a visible gap. A replica that must match to the bit uses its own polynomial for these, on both
+  sides.
+
+Three spellings that differ from other languages:
+
+- **`%`** is the remainder of the truncated division: it takes the sign of the LEFT operand (`-1 % 3` is
+  `-1`), and works on decimals (`3.25 % 12` is `3.25`). It is C's `fmod`, Python's `math.fmod` — not
+  Python's `%`. **`mod(a, b)`** is the positive one (`mod(-1, 3)` is `2`), Python's `%` for `b > 0`.
+- **`round`** sends a half UP, toward +∞: `round(2.5)` is `3`, `round(-2.5)` is `-2`. Python's `round`
+  sends it to the even neighbour. An array index is rounded the same way.
+- **`random()`** draws from a seeded generator made of integer operations only: the same seed gives the
+  same sequence on every engine. A replay is always seeded (`flatc --play`, seed `1`, or `--seed N`); a
+  player in a page draws from the browser unless its host passes `seed`.
+
+Time: one step of `every frame` is exactly **`DT`** = 1/60 s — integrate with it. `clock`, `time` and
+`frame` follow real time in a browser and are exact only in a replay (see
+[how a frame runs](behavior-and-interactions.md#how-a-frame-runs)).
+
 ## Functions (`fn`)
 
 Define reusable helpers — a **value** function (an expression) or a **procedure** (actions):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatkit/compiler",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "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.38.0",
-    "@flatkit/player": "0.38.0",
-    "@flatkit/types": "0.38.0"
+    "@flatkit/player": "0.39.0",
+    "@flatkit/engine": "0.39.0",
+    "@flatkit/types": "0.39.0"
   },
   "peerDependencies": {
     "skia-canvas": "^3.0.8 || ^4.0.0-rc7"

package/prompts/flatink-core.md

@@ -288,7 +288,9 @@ align top of "Bin" [offset dx,dy]                         // pin origin onto ano
 Pure & numeric (no booleans: comparisons/logic yield `1`/`0`). Operators: `?: || && == != < > <= >=
 + - * / % - ! . [] fn()`. A lookup table can be written in place and indexed at once: `[10, 20, 30][i]`.
 Built-ins: `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 E`.
+clamp(x,lo,hi) lerp(a,b,t) mod(a,b) between(x,lo,hi) rad(deg) deg(rad) turns(n)`. Constants `PI TAU E`, and `DT` = 1/60 s: `every frame` is a
+fixed 60 Hz step whatever the timeline's fps, so integrate with `v = v + a * DT`. Handlers run when their event
+arrives, before the next step.
 Reserved: `time` (seconds, **wraps** every `durationFrames`), `clock` (seconds, **monotone**), `frame`,
 `value`, `mouse.x/y`, `keys.<Key>`, `self.*`, `<Name>.*`.
 Packages: `use "collision" | "easing" | "gesture" | "feedback"`; functions are available bare and

package/prompts/flatink-lite.md

@@ -104,7 +104,7 @@ State/funcs: `var a = 0` · `var arr = fill(8,0)` (also as an ASSIGNMENT: `arr =
 ## Expressions
 Pure numeric, no booleans (compare/logic → 1/0). Ops: `?: || && == != < > <= >= + - * / % - ! . [] fn()` · inline table `[10, 20, 30][i]`.
 Funcs: `sin cos tan atan2 abs sqrt pow 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)`. Const `PI TAU E`.
+mod(a,b) between(x,lo,hi) rad(deg) deg(rad) turns(n)`. Const `PI TAU E` · `DT` = 1/60 s (the `every frame` step, fixed 60 Hz: `v = v + a * DT`).
 Reserved: `time`(s, **wraps**) `clock`(s, **monotone**) `frame` `value` `mouse.x/y` `keys.<Key>` `self.*` `<Name>.*`.
 Channels: `x y scaleX scaleY rotation opacity` (absolute) + `dx dy` (additive: `pos = at + (dx, dy)`).
 Stateful easing: `spring <ch> "<target>" stiffness <0..1> damping <0..1>` · `smooth <ch> "<target>" k <0..1>`

package/prompts/role-coder.md

@@ -68,7 +68,7 @@ object "Dial" { spring rotation = aim { stiffness 0.08 damping 0.86 } }   // smo
 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
 sign min max hypot clamp(x,lo,hi) lerp(a,b,t) mod(a,b) between(x,lo,hi) rad deg turns`. Constants
-`PI TAU E`. Reserved: `time` (s), `frame`, `value`, `mouse.x/y`, `keys.<Key>`, `self.*`, `<Name>.*`.
+`PI TAU E`, `DT` (= 1/60 s: `every frame` is a fixed 60 Hz step, integrate with `v = v + a * DT`). Reserved: `time` (s), `frame`, `value`, `mouse.x/y`, `keys.<Key>`, `self.*`, `<Name>.*`.
 
 Functions: `fn dist(ax,ay,bx,by) = hypot(ax-bx, ay-by)` (value) · `fn reset() { score = 0 }` (procedure).