m0saic 0.2.2 → 0.3.1

package/node_modules/@m0saic/knowledge/docs/skills/m0saic-string-generation.md

@@ -0,0 +1,251 @@
+# m0 Generator Guidelines
+
+Practical algorithm outline for generating valid m0 strings programmatically. **Prefer official helpers over hand-emitting tokens.**
+
+> **Source of truth:**
+> - Builders: [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/builders](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/builders)
+> - Unified transforms: [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/transforms/unified](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/transforms/unified)
+> - Validation: [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate)
+> - Feasibility: [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/feasibility](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/feasibility)
+
+---
+
+## 0. Prime directives
+
+### 0.1 Prefer library ops over hand-writing strings
+
+If an official op/helper exists for the transformation you want, **use it** instead of emitting raw m0 tokens.
+
+Three primary sources of safe generation:
+
+- **`@m0saic/dsl-stdlib/builders`** — high-level builders (`grid`, `weightedSplit`, `strip`, `container`, `aspectFit`, `placeRect`/`placeRects`, `rectsToM0`, `safeCanvas`, `snapGridFit`, `spotlight`, `comparison`, `rankedList`, `goldenSplit`, `goldenSpiral`, etc.). Full surface: see [`dsl-stdlib-method-catalog.md`](./dsl-stdlib-method-catalog.md).
+- **`@m0saic/dsl-stdlib/transforms`** — unified ops (`split`, `replace`, `addOverlay`, `removeOverlay`, `setTileType`, `measureSplit`, `swapFrames`).
+- **`@m0saic/dsl`** — low-level parsing + validation; never the right tool for *generation*.
+
+Raw string emission is a **last resort.**
+
+### 0.2 Use `grid` for grids
+
+For row/column grids (equal cells, weighted cells, gutters, outer gutters), call:
+
+```ts
+import { grid } from "@m0saic/dsl-stdlib";
+
+const result = grid({ rows: 3, cols: 4, gutter: 0.05 });
+// result.m0 — canonical m0 string
+// result.totalX, result.totalY — split factors
+// result.cellW, result.gutterW — resolved weights
+```
+
+The builder handles weighted-split expansion via `0` carry runs, gutter `-` slots, the illegal `1(...)` / `1[...]` rule, exact classifier-count = child-slot count, and canonical output. **Don't hand-author split trees.**
+
+Workflow: build the base layout with a builder, apply targeted edits with unified transforms, validate.
+
+---
+
+## 1. Validation and feasibility
+
+### 1.1 Always validate
+
+```ts
+import { validateM0String } from "@m0saic/dsl";
+
+const v = validateM0String(m0);
+if (!v.ok) {
+  // v.error is a single structured violation: { code, kind, message, ... }
+  // (singular — https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts M0ValidationResult)
+}
+```
+
+Boolean shortcut: `isValidM0String(m0)`.
+
+The validator enforces grammar, token rules, overlay correctness, child-count exactness, the trailing-passthrough rule (trailing `0` is always invalid, even with overlay), and the no-sources rule (≥1 leaf `1` required somewhere in the layout). Overlay bodies do NOT need their own source — sourceless bodies like `1{-}` are legal (relaxed 2026-06-03; see [`overlay-semantics.md`](overlay-semantics.md)). See [`handbook/dsl-rules.md`](../handbook/dsl-rules.md) for the full grammar.
+
+### 1.2 Check feasibility when dimensions are known
+
+```ts
+import { computeFeasibility } from "@m0saic/dsl";
+
+const f = computeFeasibility(m0);
+if (targetWidth < f.minWidthPx || targetHeight < f.minHeightPx) {
+  // Layout cannot render at this resolution — would produce 0-size frames.
+  throw new Error(`Below feasible: ${f.minWidthPx}×${f.minHeightPx}`);
+}
+```
+
+If you parse anyway, `parseM0StringComplete` emits `SPLIT_EXCEEDS_AXIS` at parse time:
+
+```ts
+import { parseM0StringComplete } from "@m0saic/dsl";
+
+const parsed = parseM0StringComplete(m0, width, height);
+// parsed.precision, parsed.warnings, optional parsed.error
+```
+
+### 1.3 Feasibility vs. precision (important distinction)
+
+- **`computeFeasibility`** — exact `{ minWidthPx, minHeightPx }`. Accounts for nested same-axis splits, passthrough carry chains, overlays. Use for all feasibility decisions.
+- **Precision** is a separate, independent floor (neither bounds the other). For a combined verdict use `evaluateM0` from `@m0saic/dsl-stdlib` — it returns `feasible`, `meetsPrecision`, and `recommendedMin` (the per-axis max of both floors). (`computePrecisionFromString` is an internal dsl helper, not public API.)
+
+See [`../handbook/feasibility-precision-quantization.md`](../handbook/feasibility-precision-quantization.md) (canonical) for the two-floor model.
+
+---
+
+## 2. Unified transforms — the canonical API for structural changes
+
+When you mutate an existing string, use the unified transforms exported from `@m0saic/dsl-stdlib`. Every transform takes `(m0, target, options) → m0` where `target: TransformTarget` is a discriminated union.
+
+### TransformTarget
+
+```ts
+type TransformTarget =
+  | { by: "logicalIndex"; index: number }    // 0-based index of rendered frames (1/F only)
+  | { by: "span"; span: { start: number; end: number } }  // exact char span
+  | { by: "stableKey"; key: string };        // structural identity path
+```
+
+Pick the addressing mode that matches your invariant — `logicalIndex` for "the Nth rendered tile," `stableKey` for "this specific node, even after edits," `span` for parser-visible ranges. See [`../file-formats/m0p-and-custom-field.md`](../file-formats/m0p-and-custom-field.md) and [`identity.md`](identity.md) for identity semantics.
+
+### 2.1 Split
+
+```ts
+import { split } from "@m0saic/dsl-stdlib";
+
+// Uniform 3-way column split on the 0th tile
+split(m0, { by: "logicalIndex", index: 0 }, { axis: "col", count: 3 });
+
+// Weighted split: weights.length must equal count
+split(m0, { by: "logicalIndex", index: 0 }, { axis: "col", count: 2, weights: [60, 40] });
+```
+
+GCD-reduces emitted DSL by default. Pass `weightMode: "literal"` to preserve exact slot count.
+
+### 2.2 Measure-mode split
+
+```ts
+import { measureSplit } from "@m0saic/dsl-stdlib";
+
+// axis "col" or "row"; count = granularity; ranges are {a, b} objects (inclusive)
+// (MeasureSplitOptions — https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/transforms/unified/measureSplit.ts#L9)
+measureSplit(m0, { by: "logicalIndex", index: 1 }, { axis: "row", count: 12, ranges: [{ a: 2, b: 8 }] });
+```
+
+### 2.3 Set leaf type
+
+```ts
+import { setTileType } from "@m0saic/dsl-stdlib";
+
+// Change a leaf to "-" (null), ">" (passthrough), "F" (frame), or "1"
+setTileType(m0, { by: "logicalIndex", index: 0 }, "-");
+setTileType(m0, { by: "stableKey", key: "r/growc0/fc1" }, ">");
+```
+
+### 2.4 Add / remove overlay
+
+```ts
+import { addOverlay, removeOverlay } from "@m0saic/dsl-stdlib";
+
+addOverlay(m0, { by: "logicalIndex", index: 2 });          // visual overlay
+removeOverlay(m0, { by: "stableKey", key: "r/fc2" });
+```
+
+### 2.5 Replace / swap
+
+```ts
+import { replace, swapFrames } from "@m0saic/dsl-stdlib";
+
+replace(m0, { by: "logicalIndex", index: 0 }, "2(F,F)");   // replace subtree at target
+swapFrames(m0, 0, 1);   // swap rendered tiles — takes two logicalIndex numbers
+                        // directly, NOT a TransformTarget (the one exception to §2)
+```
+
+---
+
+## 3. Repair-loop strategy
+
+When validation fails, apply targeted repairs instead of regenerating from scratch.
+
+### 3.1 ILLEGAL_ONE_SPLIT
+
+Problem: `1(...)` or `1[...]` — wrapping a single child as a pseudo-container is illegal.
+
+Fix: drop the `1(...)` wrapper or use `0`-runs instead.
+
+### 3.2 Trailing passthrough
+
+Problem: last child in a split is `0` (even with overlay — `0{...}` trailing is always invalid).
+
+Fix:
+- Replace trailing `0` with `-`: `2(1,0)` → `2(1,-)`
+- Or replace trailing `0` with `1`: `2(1,0)` → `2(1,1)`
+
+Don't use `2(1,0{1})` — trailing passthrough with overlay is still invalid.
+
+### 3.3 TOKEN_COUNT mismatch
+
+Problem: classifier `N` doesn't match the number of children.
+
+Fix: adjust `N` to match children, or add/remove children to match `N`.
+
+### 3.4 SPLIT_EXCEEDS_AXIS
+
+Problem: classifier count exceeds available pixels on an axis.
+
+Fixes (in order):
+1. Reduce split count.
+2. Collapse subtree to `1`.
+3. Replace with fewer parts.
+
+### 3.5 NO_SOURCES
+
+Problem: the layout as a whole contains no leaf `1` (overlay bodies are allowed to be
+sourceless — `ZERO_SOURCE_OVERLAY` is no longer raised).
+
+Fix: ensure at least one `1` / `F` exists somewhere (a source inside an overlay counts:
+`2(-,-){1}` is valid). See [`overlay-semantics.md`](overlay-semantics.md).
+
+### 3.6 INVALID_CHAR / TOKEN_RULE
+
+Problem: malformed output. **Generator bug** — fix the generation logic, don't band-aid the output.
+
+---
+
+## 4. Overlay body constraints
+
+Bodies are parsed as complete m0 sub-expressions: non-empty, not a bare `0`
+(`INVALID_EMPTY`), no trailing passthrough — but they do **NOT** need a leaf `1`
+(sourceless `{-}` / `{2(-,-)}` are legal; relaxed 2026-06-03). Full rules:
+[`overlay-semantics.md`](overlay-semantics.md) and
+[`structural-construction.md`](structural-construction.md) §7.
+
+---
+
+## 5. Output format options
+
+Most ops accept output options:
+
+```ts
+{ output: "canonical" }   // 1, 0
+{ output: "pretty" }      // F, >
+```
+
+Agents should prefer canonical output for machine use unless pretty is explicitly required.
+
+---
+
+## 6. Precision warnings
+
+High classifier counts emit `PRECISION_EXCEEDS_NORM` warnings (informational, never
+blocking; raise the threshold via `parseM0StringComplete(s, w, h, { precisionNorm: 256 })`).
+The two-floor feasibility/precision model:
+[`../handbook/feasibility-precision-quantization.md`](../handbook/feasibility-precision-quantization.md).
+
+---
+
+## See also
+
+- [`../handbook/dsl-rules.md`](../handbook/dsl-rules.md) — full grammar.
+- [`../handbook/feasibility-precision-quantization.md`](../handbook/feasibility-precision-quantization.md) — feasibility rules (canonical).
+- [`structural-construction.md`](structural-construction.md) — structural-build patterns.
+- [`overlay-semantics.md`](overlay-semantics.md) — overlay rules.
+- [`parse-apis.md`](parse-apis.md) — parser entry points.

package/node_modules/@m0saic/knowledge/docs/skills/more-atoms-not-bigger-atoms.md

@@ -0,0 +1,77 @@
+# More atoms, never bigger atoms — the scaling contract with ffmpeg
+
+> The measured cliffs behind atom 1 (and the "graph-size OOM" debunk) live in
+> [`../runtime/ffmpeg-expression-limits.md`](../runtime/ffmpeg-expression-limits.md).
+> This is the general principle; that is the case study.
+
+m0saic renders arbitrarily complex templates by splitting work into pieces.
+That works because ffmpeg capacity scales with the NUMBER of things it is
+given (commands, inputs, filters, files). It breaks when a feature grows a
+single UNPARTITIONABLE ATOM with content. Chunking cannot rescue a bigger
+atom — the atom is smaller than a command.
+
+## The four atoms (with measured walls)
+
+1. **One expression string.** `av_expr_parse` has a ~100 recursion budget:
+   ~98 flat `+` terms or ~100 nesting levels, independent of char length.
+   Failure is a phantom `Cannot allocate memory` (−12) or `Invalid
+   argument` (−22) at graph init, in <80 ms. Applies to EVERY expression:
+   `enable`, `geq`, crop/scale/drawtext params, `%{eif}`.
+2. **One filter's per-frame work.** `geq` interprets its expression per
+   pixel per plane per frame (nodes × W × H × fps). No crash — render time
+   explodes. Chunking does not reduce it: same pixels either way.
+3. **One frame's memory.** frames-in-flight × W × H × 4 B. Buffering
+   filters (`loop=size=N`, `split`, framesync queues, `tpad`) and
+   resolution multiply it; filter COUNT does not (12,000 chained filters /
+   1.19 MB single graph verified fine).
+4. **One process's argv.** Windows caps ~32 K → `ENAMETOOLONG`.
+
+## The classification test (apply to any content-scaled feature)
+
+When something scales with content (N tiles, steps, keyframes, data
+points), ask: **which quantity grows?**
+
+- Count of commands / inputs / filters / workspace files grows → MORE
+  ATOMS → fine; capacity, chunkable.
+- A single expression, a single filter's per-pixel cost, a single frame's
+  resident bytes, or argv grows → BIGGER ATOM → redesign before shipping.
+
+## Bigger-atom anti-patterns → more-atoms replacements
+
+| anti-pattern (bigger atom) | replacement (more atoms / bounded atom) |
+|---|---|
+| nested `if(cond,…,else)` per keyframe (`expr = if(...,${expr})` builders) | flat gated sum: `lt(t,t0)*(v0)+(gte·lt)*seg+…+gte(t,tN)*(vN)` |
+| `.join("+")` on a content-scaled window list, emitted raw | route through the funnels (below) or `rebalanceAdditiveChains` |
+| `geq` on a canvas/panel-sized stream | static SVG/PNG mask + `alphamerge`; keep geq on small intermediates |
+| animated values as ever-larger exprs | pre-render to a small intermediate (value `.mov`s, text renders) |
+| content-scaled string inline in argv (`-i lavfi`, drawtext text) | workspace file (`-filter_complex_script`, `-graph_file`, `textfile=`) |
+| full-res lossless-alpha (qtrle/argb) intermediates on opaque nodes | alpha intermediates only where alpha flows |
+
+## Existing enforcement (route new work through these; do not bypass)
+
+- `rebalanceAdditiveChains` (`@m0saic/platform` ffexpr) auto-applied at the
+  funnels: `quoteEnableArg` (all `:enable=`), `buildOverlayAlphaFilter`
+  (enable→geq alpha fold), `buildCameraFilters` (zoom/focus). >32 flat
+  terms → balanced tree (O(log n) depth, verified past 1024 terms); ≤32
+  passes byte-identical. It CANNOT fix nesting — builders must emit flat
+  shapes.
+- Input-count split (`maxInputsPerCommand`) — more commands per node.
+- Graph/text file lowering — argv atom stays constant.
+- SVG rounding rasterizer (default) — rounding is a mask input, not geq.
+
+Known bypasses to watch: hand-rolled lavfi `enable=` strings (dsl-string
+caret track, dsl-canvas drawbox — currently ≤3 terms) and nested-if
+builders in other templates (e.g. line-chart anim) that will hit atom 1 if
+their datasets grow.
+
+## Review greps
+
+`join("+")` on generated arrays; recursive expr accumulation
+(`= \`if(…,${expr})\``); `geq` fed by canvas-sized labels; content
+interpolation into `-i`/argv rather than a workspace file.
+
+---
+
+*Per-pixel eval cost (atom 2) is the next practical wall at denser grids — a
+perf ceiling, not a crash; fix it representationally (masks, pre-rendered
+intermediates), not by chunking.*

package/node_modules/@m0saic/knowledge/docs/skills/overlay-semantics.md

@@ -0,0 +1,194 @@
+## Overlay Semantics & Paint Order
+
+Overlays are recursive layout subtrees rendered inside an owner's rect — a first-class
+compositional primitive, not just "layers". This doc covers attachment, paint order,
+deferred zero-overlay paint, the overlay-body validity rule, and composition at scale.
+
+> **Source of truth:** overlay parsing in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts);
+> overlay-body validation in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts)
+> (relaxation comment at lines 479–486); error codes in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/errors/errors.ts).
+> Every accept/reject example below was runtime-verified against https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/dist
+> via `validateM0String` on 2026-07-27.
+
+## Attachment: any node can own an overlay
+
+Form:
+
+    node{ overlay_body }
+
+`node` may be ANY node kind — not just `1`:
+
+- `1` (tile), `0` (passthrough), `-` (null — child position only; see Logical Owner)
+- `N(...)` / `N[...]` (splits)
+- a node that is itself an overlay owner (chains)
+
+No base `1` is required for an overlay to exist. A chain of full layouts is legal:
+
+    2(1,1){3(1,1,1){2(1,1)}}    — base 2-col, overlay 3-col, overlay-on-overlay 2-col
+
+Rules:
+
+- At most ONE immediate overlay object per node — `1{1}{1}` rejects
+  (`OVERLAY_CHAIN`). Stack by nesting instead: `1{1{1}}`.
+- The overlay body must validate independently as a full m0 string, recursively.
+- Nesting depth is structurally unbounded — but see the render-cost caveat below.
+
+Valid: `1{1}` · `2(1,1){1}` · `1{1{1}}` · `2(1,1){3(1,1,1){2(1,1)}}`
+
+## Overlay rect = owner rect
+
+The overlay subtree is parsed against owner.x / owner.y / owner.width / owner.height.
+
+- It does NOT inherit sibling geometry.
+- It does NOT escape its parent rect.
+
+Applies to tile, group, null, and zero overlays alike.
+
+## Overlays never mutate geometry
+
+Overlay stacking, at any depth:
+
+- does NOT change splitEven results or sibling sizes
+- does NOT change structuralDepth
+- does NOT alter stableKeys of the base structure
+
+It only increments `overlayDepth` and adds paint layers. The base layout defines
+geometry; overlay chains define drawing.
+
+## Paint order
+
+Deterministic, defined by engine traversal.
+
+### Tile overlay
+
+    1{1}
+
+1. Base tile
+2. Overlay subtree (immediately after owner)
+
+### Group overlay
+
+    2(1,1){1}
+
+1. Child 0
+2. Child 1
+3. Group overlay — group overlays paint AFTER all base children.
+
+### Zero overlay (deferred paint)
+
+    3(0{1},1,1)
+
+Zero overlays do NOT paint immediately; they defer until the claimant renders:
+
+1. Claimant tile
+2. Deferred zero overlay
+
+Multiple zero overlays in one run:
+
+    3(0{1},0{1},1)
+
+1. Claimant
+2. Larger-area zero overlay
+3. Smaller-area zero overlay (top-most)
+
+Deferred zero overlays are sorted by area DESCENDING → smaller overlays paint on top.
+
+### Claimant with its own overlay
+
+    3(0{1},1{1},1)
+
+1. Claimant tile
+2. Claimant's own overlay
+3. Deferred zero overlay — always after the claimant AND the claimant's overlay.
+
+### Nested overlays
+
+    1{1{1}}
+
+1. Base tile
+2. First overlay
+3. Nested overlay
+
+## Logical owner `-`
+
+`-{X}` marks `isLogicalOwner = true`: the base does not render, but the overlay rect
+exists and carry is still absorbed if it is a claimant. Use for editor semantics and
+labeling containers.
+
+Position matters: `-{...}` is valid in a child slot or inside an overlay body, NOT as
+the whole-string root — `2(-{1},1)` and `1{-{1}}` accept; bare `-{1}` rejects
+(`TOKEN_RULE`), as does a bare `-` root (`INVALID_EMPTY`).
+
+## Overlay depth vs structural depth
+
+Two independent counters:
+
+- `structuralDepth` — increases entering numeric containers; root = 0.
+- `overlayDepth` — increases entering `{...}`; base layout = 0, first overlay = 1.
+
+Overlay frames inherit the structuralDepth of their context and use a separate frame
+namespace.
+
+## Overlay body node rule (`INVALID_EMPTY`)
+
+An overlay body `{...}` must contribute at least ONE node to the graph, but does not
+have to paint. Logical-owner anchors (`-{X}`) are the common shape.
+
+Rejected — zero nodes, or a single root with nothing to act on:
+
+    1{}        — empty body; no nodes at all
+    1{0}       — bare passthrough at the overlay root; nothing to donate to
+    1{-{}}     — recursive: the inner `{}` is rejected (deepest offender reported)
+
+Accepted — at least one node, even if nothing paints:
+
+    1{-}              — single null node; logical-owner anchor
+    1{2(-,-)}         — all-null split; structural nodes, no paint
+    1{2(0,-)}         — passthrough with a sibling to donate space to
+    1{-{-}}           — nested logical owners
+    1{-{2(0,-)}}      — nested with structural content
+    1{2(-,1)}         — overlay body has a source (always valid)
+    1{2[1,1]{1}}      — nested overlay body has a source
+
+The legacy `ZERO_SOURCE_OVERLAY` rule (body must contain at least one leaf `1`) was
+relaxed 2026-06-03 — overlay bodies no longer have to paint, only exist as nodes
+([`m0StringValidator.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/validate/m0StringValidator.ts):479–486).
+The whole-string `NO_SOURCES` check still requires the OUTER (root) layout to produce
+at least one source tile, so the renderer is never asked to draw a fully empty canvas.
+
+Error code when rejected: `INVALID_EMPTY` (kind `SYNTAX`).
+
+## Composition at scale: deep overlay stacks
+
+Overlay chains are how large rect sets are composed: each `{}` wraps a full valid
+subtree, and each layer paints inside the owner's rect. A 109-overlay brand mark —
+each overlay an independently calculated m0saic drawing one precise rectangle — is a
+measured working example; its serialized string ran to tens of thousands of
+characters, which parse/validate/walk handle without issue.
+
+Deep stacks are editor-clean: each overlay is its own layer, filterable by
+`overlayDepth`, structurally independent, with no geometry coupling.
+
+Use deep overlays for programmatic rect emission — dictionary-based layouts, glyphs,
+masks, strict layering control. Prefer a single split when it expresses intent more
+clearly or raw-string readability matters.
+
+> ⚠️ **Render-cost caveat** (measured 2026-07-02): depth is free structurally, NOT at
+> render time. Each overlay level is one sequential blend pass on ffmpeg's single
+> graph thread, and past ~25 nested overlay layers inline-masks silently degrade
+> (circles→squares, text→tofu) — engine wall W3. Deep stacks are cheap to WRITE
+> and inspect, not cheap to RENDER — collapse time-disjoint line geometry into
+> lavfi tracks first. Author-facing rules:
+> [`../templates/patterns/perf-authoring-rules.md`](../templates/patterns/perf-authoring-rules.md)
+> (R6). Deep dives are engine-internal: `.ai/moat/runtime/ffmpeg-limitations.md`,
+> `.ai/moat/runtime/render-cost-model.md` — absent in the shipped copy.
+
+## Invalid constructions (verified, with codes)
+
+    1{}          — INVALID_EMPTY (empty body)
+    1{0}         — INVALID_EMPTY (bare passthrough body)
+    1{-{}}       — INVALID_EMPTY (recursive)
+    1{1}{1}      — OVERLAY_CHAIN (two immediate overlays; nest instead)
+    1{{1}}       — TOKEN_RULE (no owner token for the inner overlay)
+    1{2(1,0)}    — PASSTHROUGH_TO_NOTHING (trailing `0` inside overlay body)
+    -{1}         — TOKEN_RULE (`-{...}` cannot be the whole-string root)

package/node_modules/@m0saic/knowledge/docs/skills/parse-apis.md

@@ -0,0 +1,79 @@
+# Choosing the right parse API (and mapping frames → sources)
+
+> **Source of truth:** [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts).
+> All four parse exports re-exported from `@m0saic/dsl`. (A fifth,
+> `parseM0StringToFullGraphWithTraversal`, was removed in the public-API prune —
+> use `parseM0StringComplete` with `opts.trace`.)
+
+## The canonical entry point: `parseM0StringComplete`
+
+`parseM0StringComplete(input, width, height, opts?)` returns (on success):
+
+- `ok: true`
+- `ir.renderFrames` — RenderFrame[] in **paint order**
+- `ir.editorFrames` — EditorFrame[] (full structural graph, always present)
+- `ir.traversal` — optional DFS event stream if `opts.trace`
+- `precision`, `resolutionDiagnostics`, `warnings`
+
+Frames are one level deep under **`ir`**, not top-level. On failure:
+`{ ok: false, error, precision, warnings }`. Other options:
+`opts.materialize: "renderOnly"` (the cheap mode `parseM0StringToLogicalFrames`
+rides on) and `opts.precisionNorm` (default 100; gates `PRECISION_EXCEEDS_NORM`
+warnings). Prefer Complete for tooling, editor logic, anything non-trivial.
+
+## The three cheaper tiers
+
+| Tier | API | Returns | Use for |
+|---|---|---|---|
+| 1 | `parseM0StringToLogicalFrames(s, w, h)` | rendered leaves only, **logical order**; each has `rect`, `logicalIndex` (array index === logicalIndex), `meta` | template tile mapping — `cell-<logicalIndex>`, labels indexing, "Nth tile" logic |
+| 2 | `parseM0StringToRenderFrames(s, w, h)` | renderable frames in **paint order**; each has `rect`, `paintOrder`, `logicalIndex` | engine paint plan / ffmpeg stacking |
+| 3 | `parseM0StringToFullGraph(s, w, h)` | EVERYTHING as EditorFrame[] — roots, groups, leaves, passthroughs, nulls, overlay subtrees | editor UIs, structural analysis |
+
+Key invariant (Tier 2): `paintOrder` is the compositing order; `logicalIndex` is
+the logical tile index. There is **no `sourceIndex` field** — build sources by
+`logicalIndex`, paint by `paintOrder`.
+
+Common mistakes the wrong tier causes: confusing paint order with logical order,
+attaching sources to the wrong index, losing overlays/group nodes in a UI.
+
+## Identity on every frame
+
+All frame views carry `meta` identity: deterministic StableKey, structuralDepth,
+overlayDepth (separate axes; overlay keys live in the `/ov{depth}c{k}` namespace and
+never shift structural keys). The full contract: [`identity.md`](identity.md).
+
+## Frames → sources → children (the template bridge)
+
+The standard pattern for turning geometry into a `MosaicDocument`:
+
+1. Parse the layout — `parseM0StringToLogicalFrames` for leaf mapping. The public
+   frames APIs already exclude null-render nodes (the parser filters
+   `nullRender` internally — you do NOT hand-filter holes/containers).
+2. For each frame: create a child renderable (often
+   `renderNestedTemplate(cellTemplateId, props, ctx)` —
+   https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/render/renderNestedTemplate.ts#L35), attach it under
+   `children[id]`, push a `sources[]` entry referencing it.
+3. Return `{ m0: <same layout>, config.sources, children }` (the document's layout
+   field is `m0` — https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/document/document.ts#L132).
+
+Rules that keep the bridge deterministic:
+
+- **Child IDs come from `frame.logicalIndex`** (e.g. `cell-${logicalIndex}`) — or
+  `frame.stableKey` when identity must survive structural edits. Never bare loop
+  order. ([`identity.md`](identity.md) owns the when-to-use-which.)
+- **Size and time from `ctx.target`, never `ctx.output`** — `ctx.output` is
+  format/codec/alpha only ([`../templates/rendering-model-contract.md`](../templates/rendering-model-contract.md) Rule 5b).
+- **Internal cell templates** (`internal: true`, id `…/cell/v1`) are the reusable
+  building block for per-tile content — wireframe-style label/debug tiles are the
+  canonical example.
+- Props schemas: use `definePropsSchema` with typed defaults. (There is no
+  `constraints.isM0saicLayout` — an older revision of this guidance invented it;
+  the real constraint set is `MosaicPropConstraints`,
+  https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts#L108-146`.)
+
+## Quick decision table
+
+- Engine paint plan / ffmpeg stacking → `parseM0StringToRenderFrames`
+- Template tile mapping / "Nth tile" logic → `parseM0StringToLogicalFrames`
+- Full structural tree / editor UI → `parseM0StringToFullGraph`
+- Traversal events, or anything multi-view → `parseM0StringComplete` (+ `opts.trace`)