@flatkit/compiler 0.33.0 → 0.33.1

package/docs/behavior-and-interactions.md

@@ -207,7 +207,9 @@ sane start: big enough never to stall a real gesture, small enough that skipping
 impossible.
 
 **Restarting**: assign the progress variable (`progress = 0`) — the trace re-seats itself on what the scene
-wrote, and the entry end opens again. There is no other reset, on purpose: the variable is the truth.
+wrote, and the entry end opens again. There is no other reset, on purpose: the variable is the truth. The
+same rule **restores** a session: seed the progress (in `doc.variables`, or `setVar` from the host) and the
+ink, the marker and the finger all resume together — see [host integration](host-integration.md#saving-and-restoring-a-session).
 
 ### Drawing what a `trace` traced
 
@@ -298,6 +300,10 @@ the grid is as monotone as the fraction, and both agree. (The array is yours to
 coverage behind it has no reset — so each new grab re-syncs the array from the interactor's own state,
 rather than letting a scene show an intact cell over a zone counted as cleared.)
 
+The array reads **both ways**: seed it at load and the veil comes back scratched exactly where it was,
+`erase` included, with the fraction recomputed from it — how a reader resumes a half-scratched image (see
+[host integration](host-integration.md#saving-and-restoring-a-session)).
+
 Declare the array at exactly `cols * rows` — `flatc --check` states the geometry and the exact
 `var … = fill(N, 0)` to write whenever the sizes disagree, because a short array drops the writes past its
 end in silence.

package/docs/host-integration.md

@@ -90,6 +90,30 @@ player.allVars()                      // snapshot of everything, for debugging/s
 `getVar`/`allVars` return **copies**: mutating the result never touches the running scene. Symmetrically
 `setVar` clones what you pass in.
 
+### Saving and restoring a session
+
+`allVars()` is the save file, and a document's `variables` (or `setVar`) is how you put it back — a reader
+returning to a half-finished activity finds it where they left it:
+
+```js
+const saved = player.allVars()                 // …persist it however you like
+player.load({ ...doc, variables: saved })      // …and the activity resumes
+```
+
+The gestures that keep state **beside** the variables re-seat themselves on what you seed, so a restored
+scene is coherent and not merely correct-looking:
+
+- a **continuous [`trace`](behavior-and-interactions.md#a-cursor-or-a-trace-step)** picks its progress back
+  up from its own variable — the ink, the pen-tip marker and the finger all resume at the same place
+  (rather than the stroke being drawn to three quarters while the next touch starts from zero);
+- a **[`reveal … cells`](behavior-and-interactions.md#seeing-where-it-was-scratched-reveal--cells)** grid
+  is restored from the array it writes: seed that array and the veil comes back scratched exactly where it
+  was, `erase` included, with the fraction recomputed from it. The same format both directions.
+
+This happens once per `load()` (and at construction), before the first paint. Writing the variable later —
+from the host with `setVar`, or from the scene with an assignment — re-seats it just the same: the two are
+the same path on purpose.
+
 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatkit/compiler",
-  "version": "0.33.0",
+  "version": "0.33.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.33.0",
-    "@flatkit/types": "0.33.0",
-    "@flatkit/player": "0.33.0"
+    "@flatkit/engine": "0.33.1",
+    "@flatkit/types": "0.33.1",
+    "@flatkit/player": "0.33.1"
   },
   "peerDependencies": {
     "skia-canvas": "^3.0.8"

package/prompts/flatink-core.md

@@ -197,7 +197,8 @@ link  <endX>,<endY>,<target> to <Group>            // elastic thread → target
 `trace avance along Chemin` on one, `draw "avance"` on the other — the ink follows the finger by arc
 length. Add **`step <px>`** or the drill is free: without it the progress is where the finger PROJECTS, so
 one press near the finish completes it. With it, the run must start at an end and pass through everything
-(and it resumes across a lift, since a child stops mid-letter). Restart with `avance = 0`. **A scratch card is `reveal cleared { brush 28 · erase }` on a grey rectangle** — nothing else: `erase`
+(and it resumes across a lift, since a child stops mid-letter). Restart with `avance = 0` — and the same variable RESTORES a session: seed it (or the `cells` array of a
+`reveal`) and the gesture resumes where the reader left it. **A scratch card is `reveal cleared { brush 28 · erase }` on a grey rectangle** — nothing else: `erase`
 makes the runtime rub the veil out under the finger (a `mask` layer CANNOT do it, its matter is an even-odd
 clip path where two overlapping stamps cancel). **`reveal … cells grille`** is the other half, for a scene
 that must REACT to the uncovered area: it writes `grille[i] = 1` for each cleared cell (`i = row * cols + col`,