m0saic 0.2.1 → 0.3.0

package/node_modules/@m0saic/knowledge/docs/runtime/reduce-to-one.md

@@ -0,0 +1,96 @@
+# "Push complexity down" — reduce to 1, then bake the constant
+
+Two moves, applied in order. Move 1 is structural (isolate complexity); move 2
+is temporal (stop recomputing a constant). They compose: nest, prove the knobs,
+then bake. The user's vocabulary for this is literally **"reduce to 1"**, **"push
+complexity down"**, and **"bake that result to a flat video file."**
+
+## Move 1 — Reduce to 1 (nested source)
+
+When a subtree is too complex or too precise, render it as its own **nested
+source** (child mosaic document). In the parent it collapses to a single `F` —
+one cell, one source ref. High-level layout stays simple; the complexity is
+isolated one level down. It still renders every frame; you've only separated
+concerns by precision tier (e.g. a px-baked, quantization-sensitive scatter vs.
+resolution-independent chrome).
+
+Mechanism: wrap the subtree as a child doc (`children[...]` + a
+`{type:"mosaic", ref}` source) so the engine renders it into its own
+framebuffer and the parent sees one `F`. Same primitive as nested-mosaic
+clipping.
+
+## Move 2 — Bake the constant (flat asset)
+
+When a subtree is **identical on every render** — a fixed background, a
+decorative field, a logo sting with no data dependency — don't render it at
+runtime at all. Pre-render it **once** and reference the result as a flat asset.
+
+How:
+1. Author a one-off **`internal: true`** bake template whose only job is to
+   render that subtree full-canvas, opaque, at each target aspect (e.g.
+   `hero/ffmpeg-pulse/scatter-bake/v1`).
+2. `m0saic make` it once per aspect → small `.mp4` / `.png` into the pack's
+   `_shared/assets/` (mirror to `dist` via `build:templates`).
+3. In the real template, replace the nested subtree with one
+   `{type:"media", mediaType:"video"|"image", assetId, placement:{fit:"cover"}}`
+   source, picking the asset by aspect (`scatter-${variantKey}.mp4`).
+4. Update the unit test: assert the `assets.<name>` ref + the `mediaType`, and
+   DROP the now-stale "child carries N tiles / animates" assertions.
+
+Determinism still holds: a baked asset is a committed fixture, byte-identical
+every run. Animation is fine to bake — the reveal/motion lives in the video.
+
+## When to bake (the trigger)
+
+> "When you notice DSL count is high **and** render is long, and the result is
+> intended to be the same every time — bake it to a flat file."
+
+All three must hold:
+- **High DSL / long render** — the subtree dominates `dsl-complexity.md` metrics
+  or wall-clock.
+- **Constant across renders** — no prop/data dependency; same pixels every time.
+  (If it varies with data, you cannot bake it — keep it live or reduce to 1.)
+- **Knobs are locked** — bake LAST, after the look is signed off. Baking freezes
+  the subtree; re-tuning means re-baking.
+
+## When NOT to bake
+
+- The subtree depends on props/data (varies per render) → it's not constant.
+- The look isn't locked yet → premature; you'll re-bake every iteration.
+- The subtree is cheap → baking adds an asset + a build step for no win.
+
+## Measured payoff (FFmpeg-pulse title beat, 2026-06-23)
+
+The title beat's signature background is a ~225-rect scatter with an L→R reveal —
+the same on every render. Baking it to a flat per-aspect `.mp4`:
+
+| Metric | Live scatter (inlined) | Baked scatter (1 video src) | Change |
+|---|---|---|---|
+| Wall-clock render (1920×1080, 9 s) | ~5 min | 66 s | ~4.5× faster, ~78% less |
+| Flattened `.mosaic` size | ~163 K chars | 3,838 chars | ~98% smaller |
+| Flattened source count | 238 | 14 | ~94% fewer |
+| Baked asset size | — | ~98–155 KB / aspect | one-time, reused |
+
+One-time bake cost ~3 m 21 s/aspect, amortized over every future render (it pays
+for itself after ~1 render). The residual 66 s is the **chrome-overlay floor** —
+the variable, prop-driven work that legitimately stays live. The bake removed the
+*constant* cost and left only the *variable* cost; that's the whole point.
+
+## Trade-offs
+
+- **Inline:** one flat doc, simplest pipeline; fat parent m0, mixed precision
+  tiers, depth accrues toward the ~25-layer overlay mask ceiling (see
+  `feasibility-precision-quantization.md` and the overlay-depth limit), full cost
+  every render.
+- **Reduced to 1 (nested):** clean parent, isolated complexity, dodges the mask
+  ceiling; still full render cost (the subtree still renders).
+- **Baked (flat asset):** near-zero per-render cost for that subtree, tiny
+  parent; but adds a committed asset + a one-off bake template + a build step, and
+  the subtree is frozen (re-tune ⇒ re-bake).
+
+## Adjacent
+
+`dsl-complexity.md` (metrics → *when*), `feasibility-precision-quantization.md`
+(precision tiers + the mask ceiling), nested-mosaic clipping (the move-1
+mechanism). The shipped reference for a constant-subtree bake is
+https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/hero/ffmpeg-pulse/scatter-bake/v1.

package/node_modules/@m0saic/knowledge/docs/skills/README.md

@@ -0,0 +1,40 @@
+# skills/ — DSL & engine mental models
+
+Operational skills layered on the handbook. **The handbook is canonical** — a doc
+here that restates grammar is a checklist form of the same rules, and on any
+conflict [`../handbook/`](../handbook/README.md) wins.
+
+## Grammar & construction (emitting valid m0)
+
+- [`structural-construction.md`](structural-construction.md) — the build-time
+  rule checklist (count-exactness, overlay discipline, trailing-passthrough).
+- [`m0saic-string-generation.md`](m0saic-string-generation.md) — programmatic
+  generation: builders first, unified transforms, validate, repair loop.
+- [`dsl-stdlib-method-catalog.md`](dsl-stdlib-method-catalog.md) — pointer to
+  the full stdlib catalog (colocated with the package).
+
+## Geometry & semantics (what the parser does)
+
+- [`axis-and-geometry.md`](axis-and-geometry.md) — split axes, `splitEven`
+  remainders, rect propagation.
+- [`passthrough-semantics.md`](passthrough-semantics.md) — `0` donation runs,
+  claimants, carry scoping.
+- [`overlay-semantics.md`](overlay-semantics.md) — **the overlay anchor**:
+  attachment, bodies, deferred paint order.
+- [`zero-overlay-analysis.md`](zero-overlay-analysis.md) — the `0{}` phantom
+  operator (rarely needed; read overlay-semantics first).
+
+## Identity & parsing
+
+- [`identity.md`](identity.md) — StableKey, the five axes, selection policies.
+- [`parse-apis.md`](parse-apis.md) — which parse API to use + the
+  frames→sources bridge.
+
+## Authoring surfaces
+
+- [`labels-and-masks.md`](labels-and-masks.md) — labels/masks across
+  dictionary → generator → editor → disk.
+- [`text-in-templates.md`](text-in-templates.md) — text sources, rasterizer
+  choice, sizing traps.
+- [`more-atoms-not-bigger-atoms.md`](more-atoms-not-bigger-atoms.md) — the
+  ffmpeg scaling contract (capacity grows with atom COUNT).

package/node_modules/@m0saic/knowledge/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/node_modules/@m0saic/knowledge/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/node_modules/@m0saic/knowledge/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/node_modules/@m0saic/knowledge/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.