@flatkit/compiler 0.35.1 → 0.35.3

package/docs/dsl-gotchas.md

@@ -465,15 +465,21 @@ and composes with `self.x`/`self.y` etc. (same `self`).
 
 ## `filter` performance
 
-- A `filter glow`/`shadow` = **one offscreen canvas recomposited** per group carrying the
-  filter. The engine automatically **caches** *static* filtered subtrees (decor with no
-  expression or animation): they are only re-rendered on zoom/pan or asset load. So a filter
-  on **static decor** is nearly free in steady state.
-- A filter on an **animated** element (channel expression, `bind`, timeline) is recomposited
-  every frame. Keep filters on animated elements **small**.
+- A `filter glow`/`shadow` = **one offscreen canvas recomposited**, then blitted. The engine **caches**
+  that composite, keyed on the item's screen placement, so a filter that holds still is repaid once and
+  then costs a single blit — on a group **and on a bare shape** (`circle … filter glow`), which went
+  uncached until 0.35.0: 360 recompositions over 60 frames where the same thing, cached, does 0.
+- The cache is **per instance**, not per item: eight lanterns from one filtered symbol keep eight bitmaps.
+  (They shared one entry before 0.35.0 and thrashed it — 480 recompositions over 60 frames.)
+- **What defeats it: motion that never settles.** The key is the placement, so a *periodic* `clock`/`time`
+  motion (`dy = 3 * sin(clock)`) on the filtered item **or on any ancestor** never repeats a key: 270
+  recompositions over 60 frames, for as long as the scene is open. `--check` reports it, naming the
+  culprits. A motion that comes to REST (a `shake` at 0, a `clamp` decay) pays once and hits forever, and
+  animating **`opacity`** is free — it is applied at blit time, deliberately outside the key.
 - Cheap alternative for decor shadows: a **"baked" shadow** = the same path offset by a few
   px in `#00000028` UNDER the cutout (no offscreen canvas). Ideal for large planes.
-- Drop-shadow cost ∝ area × blur: a large blurred plane is expensive when not cached.
+- Drop-shadow cost ∝ area × blur: a large blurred plane is expensive when not cached. A document keeps at
+  most 256 baked composites; past that, the extra ones simply draw the slow way.
 
 ## Audio
 

package/docs/scene-and-drawing.md

@@ -90,8 +90,11 @@ 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).
+A filter is composited off-screen and the result is **cached** on the item's screen placement — on a group
+and on a bare shape alike — so decor that holds still is repaid once. What defeats the cache is placement
+that never settles: a periodic `sin(clock)` motion on the item **or an ancestor** re-composites every
+frame, and `--check` says so. Animating `opacity` instead is free. See the
+[gotchas](dsl-gotchas.md#filter-performance) for the numbers.
 
 ## Clipping & masks
 

package/docs/tooling.md

@@ -90,6 +90,15 @@ or a `tint`) that the symbol doesn't declare — a silent "dead recolor". The la
 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 reports what a gesture or a shape does SILENTLY when its options do not add up: a `draw` on a shape
+with no `stroke` (nothing to trim), a `reveal … cells` array whose length does not match the grid the
+engine builds (writes past the end are dropped, so a restored session comes back untouched — the message
+states the geometry and the exact `fill(N, 0)` to declare), a `step` of 0 or less on a `trace` (the
+progress can never move, so the drill cannot be completed), `both ends` without `step`, a non-positive
+`tolerance`/`brush`/`grain` (silently replaced by the default), and a `filter` under a transform that
+never stops moving (the composite is re-baked every frame, forever — see the
+[gotchas](dsl-gotchas.md#filter-performance)).
+
 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

package/package.json

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