@flatkit/compiler 0.34.0 → 0.34.1

package/docs/dsl-gotchas.md

@@ -29,6 +29,16 @@
   ("one action per line — unexpected `=`"), with the column pointing at the second `=`.
   A swallowed statement is named now — `score = score + 1  send "ok", 1` reports *"two statements on one
   line — `send …` was swallowed into the expression before it"*, not `unexpected character """`.
+- **The space between a keyword and its literal is NOT significant.** `send"win"`, `send "win"` and
+  `send\t"win"` are one and the same statement, and so are `object"R"` / `object "R"`, `layer"c"`,
+  `text"Hi"`, `font"sans-serif"`. The grammar is tokenized: it never sees the whitespace. (Everything
+  round-trips to the canonical one-space spelling, which is what `flatc` prints.)
+  ⚠️ **So do not police a program with a regex.** A guard looking for `send\s+"…"` misses `send"…"` by one
+  character — and, worse, misses an event emitted through a function: a fragment that never types `send`
+  can call a `fn` the rest of the program defines, and the event fires. To decide what a program is allowed
+  to DO, read its structure: `manifestEvents(doc)` (from `@flatkit/compiler`) returns every event any
+  action emits, procedures, `if`/`repeat` bodies and timeline hooks included. See
+  [Tooling](tooling.md#what-does-this-program-do).
 - **`send` footgun (fixed)**: `send "evt", x = 1` (with a comma) used to capture `x = 1` as
   the *payload*. It is now a dedicated error. A `send` carries at most one payload:
   `send "evt"`, `send "evt", <expr>`, `send "evt", text("textId")`, or the record form

package/docs/tooling.md

@@ -250,6 +250,31 @@ In the player, `player.startRecording()` / `stopRecording(): Gesture[]` capture
 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.
 
+## What does this program DO?
+
+Merging DSL you did not write (a generated skin, a themed layer) raises a question a compiler answers and
+a regex cannot: *what is this fragment allowed to do?* Read the structure, never the source text:
+
+```js
+import { parseProgramFull } from '@flatkit/engine/flatFormat'
+import { manifestEvents } from '@flatkit/compiler'
+
+const emitted = manifestEvents(parseProgramFull(merged))   // every `send`, wherever it hides
+const introduced = emitted.filter((e) => !ownEvents.includes(e))
+if (introduced.length) throw new Error(`the skin emits ${introduced.join(', ')}`)
+```
+
+`manifestEvents` walks every action of the document — inside `if` / `repeat` bodies, inside procedures,
+inside the timeline hooks — so it sees what a pattern over the source cannot:
+
+- `send"win"` with no space (the grammar does not require one — see the [gotchas](dsl-gotchas.md));
+- an event emitted **through a function**: a fragment that never writes `send` at all can call a `fn` the
+  rest of the program defines, and the event fires.
+
+Symmetrically, it does not fire on the word `send` sitting in a comment or inside a string a text draws —
+which a pattern would reject. `manifestVars` and `docToManifest` answer the same kind of question for the
+variables a program reads and the contract its objects carry.
+
 ## 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatkit/compiler",
-  "version": "0.34.0",
+  "version": "0.34.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.34.0",
-    "@flatkit/player": "0.34.0",
-    "@flatkit/types": "0.34.0"
+    "@flatkit/engine": "0.34.1",
+    "@flatkit/player": "0.34.1",
+    "@flatkit/types": "0.34.1"
   },
   "peerDependencies": {
     "skia-canvas": "^3.0.8"