@m0saic/knowledge 0.2.0

package/docs/skills/axis-and-geometry.md

@@ -0,0 +1,103 @@
+## Axis & Geometry (Splits, Pixels, Remainders)
+
+The math layer of the walk: exact rectangle geometry from `()` and `[]`,
+deterministic pixel-remainder distribution (`splitEven`), and how `0`-runs and `-`
+holes shape final rects.
+
+> **Source of truth:** `splitEven` 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)
+> (line 478 as of 2026-07-27). Locked behavior: outside-in remainder distribution.
+> Test fixtures in [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/outside-in-remainder.test.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/outside-in-remainder.test.ts).
+
+## Axis semantics
+
+- Column split `N( ... )` — splits **width** into N segments; height stays the
+  container's height.
+- Row split `N[ ... ]` — splits **height** into N segments; width stays the
+  container's width.
+
+Children are laid out in order:
+
+- Columns advance **x** (left → right)
+- Rows advance **y** (top → bottom)
+
+## splitEven pixel distribution (deterministic)
+
+When splitting an integer pixel length (`total`) into `parts`:
+
+- `base = floor(total / parts)`
+- `remainder = total - base * parts`
+- The `remainder` extra pixels are distributed **outside-in**: indices
+  0, P-1, 1, P-2, 2, P-3, ...
+- The remaining segments get `base`
+
+Example:
+
+- `total = 1080`, `parts = 7`
+- `base = 154`, `remainder = 2`
+- Outside-in order: index 0 gets +1, then index 6 gets +1
+- Sizes: `[155, 154, 154, 154, 154, 154, 155]`
+
+Key consequence: remainders distribute symmetrically from the edges inward, keeping
+layouts visually balanced.
+
+## Coordinate propagation (rects)
+
+Every node owns a rectangle `(x, y, width, height)`. Splits carve that rect into
+child rects:
+
+- Column split: child width from `splitEven(width, N)`; child x = cumulative sum of
+  prior child widths; y/height unchanged.
+- Row split: child height from `splitEven(height, N)`; child y = cumulative sum of
+  prior child heights; x/width unchanged.
+
+Overlays always reuse the **owner rect** (same x/y/width/height) and never escape it.
+
+## How `0` and `-` affect geometry
+
+### `0` (passthrough)
+
+- Consumes a split slot; adds its slot size into "carry"
+- The claimant absorbs carry + its own slot, and snaps back to the run start position
+
+Geometry impact: `0` changes the eventual claimant rect size and origin. `0` itself
+creates no visible rect (but may create overlay rects via `0{...}`).
+
+### `-` (null)
+
+- Consumes a split slot; does NOT donate forward
+- Creates a hole / gutter region; can still host overlays (`-{...}`)
+
+Geometry impact: a stable region that does not affect siblings beyond consuming its
+share of split space. Useful for isolating sub-layouts and masks.
+
+## Why resolution matters (integer pixels)
+
+All geometry is integer-pixel based. Two implications:
+
+1. A layout can look "perfect" at one size and slightly biased at another, because
+   remainder pixels distribute outside-in (edges first).
+2. Bitmap-like layouts (e.g. 64×64 encodings) require compatible output sizes,
+   otherwise meaning drifts due to integer rounding distribution.
+
+Guidance: if a layout encodes literal grid art, render at sizes aligned to that grid
+(multiples of the grid resolution). For feasibility guards, quantization strategy,
+and quantization-free construction, see
+[`../handbook/feasibility-precision-quantization.md`](../handbook/feasibility-precision-quantization.md).
+
+## Minimal examples
+
+Even-ish columns — `3(1,1,1)` at width=10:
+
+- sizes = `[4,3,3]` (1 remainder pixel goes to the first edge)
+
+Rows — `2[1,1]` at height=5:
+
+- sizes = `[3,2]`
+
+Donation changes claimant geometry — `3(0,1,1)`:
+
+- first tile claims 2 slots (`0` + its own)
+
+Hole creates gutter — `3(1,-,1)`:
+
+- middle region is an explicit empty gutter

package/docs/skills/dsl-stdlib-method-catalog.md

@@ -0,0 +1,7 @@
+# dsl-stdlib method catalog → see the package
+
+The full `@m0saic/dsl-stdlib` method catalog (builders, transforms, queries, masks, SVG import, specialized generators) is **colocated with the package** so it can't drift from the code:
+
+➡️ [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/.ai/method-catalog.md](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/.ai/method-catalog.md)
+
+That doc is regenerated/reviewed in the same change that alters the API. This file is only a pointer — don't duplicate the catalog here.

package/docs/skills/identity.md

@@ -0,0 +1,123 @@
+# Identity — StableKey, depth axes, and selection
+
+Merged 2026-07-27 from four overlapping docs (stablekey-and-overlay-identity,
+identity-model, structural-vs-overlay-depth, structural-identity_visual-identity —
+deleted; git history has the long forms). One doc, one owner: everything about
+*referring to the same node* across parses, edits, and renders.
+
+> **Source of truth:** `StableKey` + `M0NodeIdentity` in
+> [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/types.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/types.ts); identity
+> construction in [`parse/m0StringParser.ts`](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts)
+> (search `buildIdentity`, `makeStableKeySegment`).
+
+## 1. The identity contract
+
+Every parsed node receives a deterministic `stableKey` — the address of the parser's
+walk through **structure**. Segments encode node kind + split axis + childIndex among
+structural siblings. Segment grammar (verified at runtime): `r` (root) ·
+`g{row|col}c{n}` (group) · `fc{n}` (frame) · `pc{n}` (passthrough) · `nc{n}` (null) ·
+`/ov{d}c{k}` (overlay namespace).
+
+Same canonical string → same StableKeys, same structuralDepth, same overlay
+namespace. If the string changes, the tree changes and some keys change — that is
+correct, not a bug.
+
+**StableKey is NOT:** `paintOrder` / `stackOrder` (paint depends on overlay-deferral
+rules), display/label numbering, or geometry. Geometry is *derived* —
+`rect = f(m0, width, height)` — and shifts with resolution and `splitEven`
+remainders while keys stay put. The DSL guarantees **structural** identity, never
+**visual** identity.
+
+## 2. The five axes — keep them separate
+
+| Axis | Increments when | Use it for |
+|---|---|---|
+| `structuralDepth` (`meta.structuralDepth`) | entering `N(...)` / `N[...]` | tree indentation, containment reasoning |
+| `overlayDepth` | entering `{...}` | layer filtering |
+| `paintOrder` / `stackOrder` | derived from traversal + overlay deferral | paint simulation ONLY |
+| `logicalIndex` | per rendered leaf, logical order | source assignment (`sources[i]`) |
+| `stableKey` | — (structural address) | persistent identity across edits |
+
+Worked example — `2(2(1,1),1)` (verified at runtime): the outermost split **IS the
+root** (`stableKey: r`, structuralDepth 0); the inner group is depth **1**
+(`r/gcolc0`); its tiles are depth **2** (`r/gcolc0/fc0`, `fc1`); the outer `1` is
+depth **1** (`r/fc1`). There is no extra root node above the outermost split.
+
+`1{1{1}}` has structuralDepth 0 on all three nodes and overlayDepth 0/1/2 — the two
+depth systems are orthogonal: deep structure with zero overlays, flat structure with
+100 overlays, or both.
+
+Never assume `deeper == painted later` — overlay deferral (and area-descending
+zero-overlay stacking) controls paint timing, not depth. See
+[`overlay-semantics.md`](overlay-semantics.md).
+
+> ⚠️ overlayDepth is structurally free but NOT render-free: each level is a
+> sequential blend pass, and inline-masks silently drop past ~25 nested layers
+> (engine wall W3 — internal: `.ai/moat/runtime/ffmpeg-limitations.md`).
+
+## 3. The overlay invariant
+
+Overlay subtrees do NOT affect structural childIndex assignment:
+
+- Adding/removing overlays never renumbers the base tree.
+- Overlay frames live in a separate namespace — `<ownerStableKey>/ov<depth>c<k>`
+  (`r/fc0` → `r/fc0/ov1c0` → `r/fc0/ov1c0/ov2c0`) — so overlay keys cannot collide
+  with or shift structural keys.
+
+This is why overlays can be used freely (debug layers, labels, reveals) without
+destabilizing the base layout or any tool keyed on it.
+
+## 4. logicalIndex vs paintOrder
+
+RenderFrames carry both `paintOrder` (stacking order) and `logicalIndex` (logical
+tile index — same as `LogicalFrame.logicalIndex`; there is **no `sourceIndex`
+field** in https://github.com/m0saic-dsl/m0/blob/main/packages/dsl). Build sources in logical order, paint in stack order —
+the split keeps the source array clean of paint semantics. See
+[`parse-apis.md`](parse-apis.md) for which parse API returns which.
+
+## 5. Stability limits — what edits do to keys
+
+Keys **WILL change** when you: change split counts, insert/remove siblings in the
+base tree, change axis/group nesting. Keys will **NOT change** when you: add/remove
+overlays, deepen overlay nesting, reorder overlay-only layers.
+
+Overlay data attaches to `ownerStableKey`, so across edits: split *inside* the owner
+→ owner survives → overlay stays valid; edit a sibling → unaffected; delete/replace
+the owner → the overlay has no owner and cannot reattach. That last case is correct
+behavior, not data loss to be papered over.
+
+**Never reattach by geometry.** Preserving overlays via nearest-rect / similar-size /
+pixel-overlap heuristics introduces non-determinism and unfixable edge cases. If the
+owner is gone, the overlay is gone. Determinism > convenience.
+
+## 6. Selection policies (agent workflows)
+
+When you need to "pick a tile" — recursive growth, demos, batch transforms — pick by
+StableKey, not geometry or paint order. Deterministic policies:
+
+- **Smallest StableKey lexicographically** — stable across edits, cheap.
+- **Earliest leaf in StableKey-sorted order** — a "top-left-most" that survives
+  structural change.
+- **`(seed + step) mod leafCount`** over a StableKey-sorted leaf list — round-robin
+  demos where each step targets a different tile.
+
+Anti-patterns: selecting by pixel position (resolution change → different
+selection), by paint order (adding overlays shifts it), or by unsorted traversal
+order.
+
+## 7. Labeling
+
+Label tiles by StableKey (`.m0c` labels are StableKey-keyed); use the label `text`
+as the human-meaningful join key (`.m0p` regions reference labels by text). If a
+label's key no longer exists in the current parse, `validateLabels`
+(`@m0saic/dsl-file-formats`) flags it — see
+[`../file-formats/m0p-and-custom-field.md`](../file-formats/m0p-and-custom-field.md) §5.
+
+## 8. Common mistakes
+
+- Treating overlay tiles as structural leaves — scope "leaves" iterations to the
+  base namespace; overlays live under `/ov…`.
+- Confusing overlayDepth for structuralDepth (UI tree depth ≠ "inside another split").
+- Hardcoding StableKey strings — they're stable across *layout* edits but computed
+  from structure; always derive them from a parse, never string-match literals.
+- Assuming paintOrder reflects structure — it's derived, overlay rules own it.

package/docs/skills/labels-and-masks.md

@@ -0,0 +1,170 @@
+# Labels and Masks
+
+How per-leaf **labels** and **masks** travel from a dictionary entry, through a
+generator, into the editor, and back to disk. The surface spans four packages; this is
+the single map.
+
+---
+
+## 1. What lives where
+
+| Layer | Shape | Home |
+|---|---|---|
+| **On disk** | `M0cFile` — `m0` + `labels` (`Record<StableKey, M0Label>`) + `masks` (`Record<StableKey, M0cMaskEntry \| null>`) + `fill` + `size` | https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-file-formats/src/types.ts |
+| **Dictionary entry** | `MosaicDictionaryEntry.labels` / `.masks` — same maps at runtime | https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/dictionary/dictionary.ts |
+| **Editor (live)** | `m0cExtrasRef` — `{ labels, masks, derive, custom }` for the open canvas | the Mosaic Desktop / Web app source (not published) |
+| **Generator output** | `GeneratorResult.m0c?: string` — optional serialized blob | https://github.com/m0saic-project/m0saic-packages/blob/main/packages/dictionary/src/generators |
+
+> **`labels[k].color` ≠ the rect fill.** `labels[k].color` tints the *badge*; `fill[k]`
+> paints the *rect*. The inspector once conflated them — don't re-conflate.
+
+---
+
+## 2. Dictionary entry convention
+
+- An entry MAY ship **`m0saic.m0c`** instead of `m0saic.m0`. The `.m0c` is
+  authoritative; `loadEntryM0()` auto-detects by filename and **throws if both exist**.
+- **`m0saic_src.m0`** is a read-only sibling auto-regenerated by `validate.js`, carrying
+  a `# note:` header. It exists for grep-by-DSL and human inspection. **No runtime reads
+  it** — never edit it, never treat it as a source.
+- **`entry.masks`** (StableKey-keyed) is the canonical mask path. `entry.maskSets` /
+  `getMaskSet()` is reserved for future *named alternate* sets — no current entry uses
+  it. Don't reach for it.
+- Positional lookup goes through `getSourceOrderStableKeys(entry)`
+  (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/dictionary/src/sourceOrder.ts#L50, memoized per `(entry.id, m0.length)`).
+  See logo v2/v3 and qr-animate.
+  ⚠️ **It throws when `entry.m0` isn't inlined.** Heavy entries carry a lazy
+  `entry.m0File` instead. For those, call `resolveM0saic(entry)` first and pass the
+  resolved string to the companion **`getSourceOrderStableKeysForM0(id, m0, w, h)`**.
+  The error message says this, but only after you've already hit it.
+- One-shot migrations live in **https://github.com/m0saic-project/m0saic-packages/blob/main/packages/dictionary/tools** (not repo-root `tools/`):
+  `migrate-masks-to-m0c.mjs` converts legacy `masks.json` + `.m0` → `.m0c`;
+  `normalize-mask-paths.mjs` runs the drop-rect-shaped + snap-to-bounds cleanup. Both
+  route through `parseM0StringComplete` to turn positional masks into per-StableKey
+  entries.
+
+---
+
+## 3. Generator label tiers
+
+Every label-emitting generator exposes `labels: LabelTier`
+(`"silent" | "signposts" | "atlas"`) built via `labelTierParam({ defaultTier })`
+(https://github.com/m0saic-project/m0saic-packages/blob/main/packages/dictionary/src/generators/labelTier.ts).
+
+| Tier | Emits |
+|---|---|
+| `silent` | plain m0, no labels |
+| `signposts` | named structural regions only ("hero", "feature") |
+| `atlas` | signposts + per-cell / per-level enumeration |
+
+`off` is accepted as a spelling alias for `silent`; **`silent` is the canonical wire
+value**. Resolve untrusted input with `resolveLabelTier(raw, fallback)`.
+
+### Per-generator defaults and emission path
+
+Two emission paths, and which one a generator uses is not arbitrary:
+
+- **`emitLabeledM0c({ m0, size, app, tier, labelsBySourceIndex, keyedLabels })`** —
+  use when labels map **positionally** to logical source order. Handles
+  source-index → stableKey translation, including a feasibility-fallback probe
+  scale-up for high-precision layouts.
+- **Direct `serializeM0cFile`** — use when the generator must **classify nulls by
+  position** or carries masks. Parse the m0, compute the placed-content bbox, classify
+  each `kind: "null"` editorFrame by centroid offset into `padding-top` /
+  `padding-right` / `padding-bottom` / `padding-left`. The same algorithm appears in
+  every padding-classifying generator — copy it, don't re-derive it.
+
+| Generator | Default tier | Path |
+|---|---|---|
+| `qrCodeGenerator` | **`signposts`** | direct |
+| `barcodeGenerator` | **`signposts`** | direct |
+| `aspectFit` | `silent` | direct (padding classification) |
+| `placeRect` | `silent` | direct (padding classification) |
+| `snapGrid` | `silent` | direct (padding classification) |
+| `aspectSafeGrid` | `silent` | direct (padding classification) |
+| `grid` | `silent` | `emitLabeledM0c` |
+| `spotlightGenerator` | `silent` | `emitLabeledM0c` |
+| `magazineGenerator` | `silent` | `emitLabeledM0c` |
+| `comparisonGenerator` | `silent` | `emitLabeledM0c` |
+| `rankedListGenerator` | `silent` | `emitLabeledM0c` |
+| `goldenLayout` | `silent` | `emitLabeledM0c` |
+| `goldenSpiralGenerator` | `silent` | `emitLabeledM0c` |
+| `safeCanvas` | `silent` | `emitLabeledM0c` |
+
+**`silent` is the default everywhere except the two code generators** (QR, barcode),
+which default to `signposts` to preserve their always-on label channel.
+
+*Keep this table in sync when adding a generator — verify with
+`grep -A3 "labelTierParam(" https://github.com/m0saic-project/m0saic-packages/blob/main/packages/dictionary/src/generators/*.ts.*
+
+---
+
+## 4. Editor rendering and drop rules
+
+**Chip render gate** — `Frame.tsx`: `canShowLabel = hasLabel && minPx >= 70`. There is
+**no kind filter here**: frames, plain nulls, and passthroughs all wear chips once
+mounted. Visibility moved upstream to the `showNullFrames` toggle, which controls
+whether nulls reach `displayFrames` at all.
+
+**Drop-label remap** — `ViewFrame.tsx` `buildDropZone`:
+
+```ts
+const isLabelable = (f) => f.kind === "frame" || f.kind === "null";
+```
+
+⚠️ **The root node is deliberately excluded.** Including it shifts every
+position-slice mapping by one — the off-by-one that mislabeled aspectFit's `content`.
+Bare-`F` drops (canvas was `"r"`) take a separate path: the new canvas *is* the dropped
+m0, so labels apply with their original keys.
+
+> **Name collision — two different `isLabelable`.** `ViewFrame`'s is **node-kind**
+> based (above). `App.tsx`'s is **format** based
+> (`loadedFormat === "m0c" || loadedFormat === "m0p"` — can this file carry labels at
+> all). Same identifier, unrelated meanings, different files. Check which one you're
+> reading.
+
+**Why no `isLogicalOwner` requirement.** aspectFit-style generators label plain `-`
+nulls (border padding). Requiring `-{...}` overlay anchors would force every
+padding-labeling generator to wrap each null in an overlay purely to make it visible.
+The relaxed rule lets any structural node carry a label, matching the `.m0c` format's
+own permissiveness.
+
+---
+
+## 5. Undo participation
+
+`useUndoRedoText(initial, { onCommit, onUndo, onRedo })` exposes side-channel
+callbacks. `App.tsx` snapshots `{ labels, masks }` from `m0cExtrasRef` into a parallel
+stack on every text commit, and restores on undo/redo.
+
+- Manual `setFrameLabel` edits **between** commits don't push their own entry — they're
+  absorbed into the *next* commit's snapshot. So manual label → text edit → Ctrl-Z
+  restores the manual label too.
+- Drop-derived labels vanish cleanly on Ctrl-Z because the snapshot at the drop's commit
+  is taken **before** the handler merges drop labels (`setProfileText` calls `onCommit`
+  synchronously, ahead of the `m0cExtrasRef` mutation). This ordering is load-bearing.
+
+---
+
+## 6. UI affordances
+
+- **The dictionary panel's drag chip is the sole apply path.** Click-drag splices into a
+  frame; double-click replaces the canvas (confirm modal when the canvas has structure;
+  bare-`F` skips the prompt). The standalone "Use Layout" button was **removed** — it
+  duplicated the pipeline and kept drifting.
+- **Save-As gates `.m0`** whenever labels or masks exist (`m0SaveBlocked` in `App.tsx`).
+  Both the Cmd/Ctrl+S guard and the format chooser respect it — a `.m0` save would
+  silently drop the sidecar maps.
+
+---
+
+## 7. Settled items (don't re-debate)
+
+- `aspectSafeGrid` carries m0c only on the **landscape primary** variant; portrait
+  alternates don't support m0c yet. Noted in its labels-param description.
+- `LabelTier` naming is **settled**. Renaming touches ~14 generators plus the panel UI.
+- Outer-gutter nulls in `safeCanvas` are **not** labeled — canvas margin, not
+  addressable cells.
+
+**Related:** `file-formats/m0p-and-custom-field.md` covers `.m0c`'s sibling format but
+predates this convention — read this doc for the entry convention and tier param.

package/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.