@m0saic/knowledge 0.2.0

package/docs/templates/emission-patterns.md

@@ -0,0 +1,130 @@
+# Template emission patterns — data + telemetry
+
+Templates produce up to three kinds of output: **pixels** (the rendered video/image —
+the primary purpose, documented in `rendering-model-contract.md`), **structured data**
+(typed values published to downstream consumers), and **telemetry** (observability
+events). This doc covers the latter two.
+
+---
+
+## The three channels
+
+| Channel | Audience | Persistence | Read via |
+|---|---|---|---|
+| `MosaicDataSource` in `doc.sources` | Downstream pipeline steps | In-memory, render-scoped | `ctx.upstreamData[alias]` |
+| `doc.sidecars.<key>` | End user / external callers | Disk, as `{output-basename}.<key>.json` | the file |
+| `emitTemplateLog(ctx, …)` | Analytics, debugging, dev console | Sink-defined (NDJSON, IPC, …) | `MosaicEngineContext.telemetry` |
+
+Sidecar writing is owned by the engine — the render engine source (not published).
+Templates *declare*; core *writes*. Do not write sidecar files from inside `render()`.
+
+> **Adoption reality check (2026-07-26).** These are real, wired mechanisms, but
+> adoption is thin: **`@m0saic/media/subtitle-burn/v1` is still the only template that
+> emits telemetry at all**, and only it and `@m0saic/forensic/watermark/video/v1`
+> declare `sidecarsSchema`. Treat the conventions below as *the intended shape*, not as
+> a well-trodden path — you may be the second or third adopter, so prefer following
+> subtitle-burn exactly over inventing a variant.
+
+---
+
+## Telemetry: always via `emitTemplateLog`
+
+Emit through `emitTemplateLog` from `@m0saic/types` — **never construct envelopes
+inline**. The helper supplies correlation-field defaults and falls back to a no-op sink
+when `ctx.telemetry` is absent, so it is safe to call unconditionally.
+
+**`traceId` / `spanId` still default to the `"unwired"` sentinel**
+(https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/telemetry/emit.ts#L13-14`). This survived the telemetry sprint —
+it is current behavior, not a stale note. Don't be surprised by `"unwired"` in output,
+and don't hand-fake a trace id to work around it.
+
+### Event discriminator convention
+
+The closed `kind` union stays `template_log` for **all** template-emitted events.
+Distinguish event types with `data.event: "<name>"` inside the free-form payload. This
+gives consumers a stable filter key without growing the union — adding a `kind` member
+is a types-package change with a much wider blast radius.
+
+### Taxonomy for selection-style templates
+
+Templates that pick one thing from many (track, preset, route, fallback):
+
+| Event | Carries |
+|---|---|
+| `<thing>_discovered` | what the template saw — count + identifying metadata |
+| `<thing>_selected` | what it picked, including `rule: "<algorithm-path>"` |
+| `<thing>_filtered` | counts before/after window/predicate filtering |
+| `<thing>_applied` | that an optional transform actually fired |
+| `passthrough` | no selection was possible — **always include `reason`** |
+
+Subtitle-burn emits all five: `tracks_discovered`, `track_selected`, `cues_filtered`,
+`clip_applied`, and `passthrough` at three distinct sites (`no-video-source`,
+`invalid-clip-range`, and the selection `rule`). Note `passthrough` recurs with
+different `reason` values rather than becoming several event names — follow that.
+
+---
+
+## Data emission: dual-channel symmetry
+
+When publishing structured data alongside pixels, emit through **both** channels with
+the **same payload shape**:
+
+1. `MosaicDataSource` with `alias: "<name>"` in `doc.sources` — pipeline-readable
+2. `doc.sidecars.<name>` — disk-readable
+
+They serve different audiences (pipeline composition vs. external consumption);
+symmetric semantics let a consumer switch channels without recoding.
+
+**Sidecar-only is legitimate** when there is no plausible downstream *pipeline* reader.
+`forensic/watermark/video/v1` is the reference: its `watermark` sidecar is the
+per-render embedding record (payload, ECC params, key, grid, slots, embed α, host
+reference, render dims) that the **decoder** consumes later, out of band. Nothing in
+the render graph wants it, so it declares no `MosaicDataSource`. Don't add one for
+symmetry's sake.
+
+### Opt-in via `emit<Thing>?: boolean`, default `false`
+
+Auxiliary data emission is opt-in and free when disabled — no extra sources, no disk
+write. The pixels are the primary output; aux data shouldn't bloat every render.
+Subtitle-burn's `emitCues` (default `false`) is the pattern.
+
+Exception: when the sidecar *is* the point (forensic watermark — the render is useless
+without its decode record), make it unconditional and `required: true` in the schema.
+
+### Declare the schemas even when free-form
+
+Declare `outputsSchema` (for `MosaicDataSource` shapes) and `sidecarsSchema` (for
+`doc.sidecars` keys) even when entries are `type: "object"` with a prose description.
+They are living documentation that ships with the code, and engine-side validation may
+follow. Write the description as if it's the only thing a consumer will read — for
+sidecars, say **where the file lands** (`{output-basename}.<key>.json`) and **what
+gates it**.
+
+---
+
+## Two habits worth copying
+
+**Selection-rule introspection.** A template making an algorithmic choice should return
+a typed `{ result, rule }` from its selector and stamp `rule` into *both* the
+`<thing>_selected` telemetry event and the published data payload. Consumers then
+attribute behavior to an algorithm path without reverse-engineering props.
+Subtitle-burn's rule union: `"explicit-index" | "language-match" | "fallback-default" | …`.
+
+**Pass-through graceful degradation.** A template handling optional input (a video that
+may or may not have subtitles) must render the base content cleanly when the optional
+path can't fire — and emit `passthrough` with a `reason` so consumers can see *why*.
+Silence here is the failure mode: an empty overlay and a successful render are
+indistinguishable without the event.
+
+---
+
+## Worked example
+
+https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/media/subtitle-burn/v1/subtitle-burn.ts is the canonical
+reference — read it end-to-end before authoring an emission-heavy template. It
+demonstrates every convention above: five telemetry events, dual-channel emission gated
+by `emitCues`, selection-rule stamping, and both schemas declared.
+
+**Related:** `data-pipeline.md` — the data-fetcher role's
+`MosaicDataSource` publishing is one specific application of the dual-channel idea here;
+that doc covers the *role* contract, this one covers the *mechanism*.

package/docs/templates/geometry-recipes.md

@@ -0,0 +1,248 @@
+# Geometry recipes — laundering pixel math into composable m0
+
+Scope: the placement recipes for templates that follow the Real-Geometry Hard Rule.
+You computed each piece's pixel rect in JS; these recipes turn those rects into m0
+geometry whose precision does NOT track the canvas. Read
+[`construction-strategy.md`](construction-strategy.md) first (the Rect Thesis + Hard
+Rule — why the rects must be real cells at all); the underlying theory (feasibility
+vs precision vs quantization, GCD collapse, §3a/§3c fixes) is
+[`../handbook/feasibility-precision-quantization.md`](../handbook/feasibility-precision-quantization.md).
+
+## Routing — which launder for which shape
+
+- Uniform grid of equal cells → **Recipe 3** (gutterless ratio grid + `latticeCellInset`).
+- Bar row/column → Recipe 3 with a non-zero `marginPx` on the layout axis.
+- Independent chrome/text (stat-card bands, KPI blocks, badges) → **Recipe 2**
+  (`placeInsetPieces`; `placeOptimizedPieces` when inset-recovery doesn't apply).
+- Tight-mask pieces (animated line/area/points) → **Recipe 1** (`SNAP_PX` snap-outward).
+- Squarified tiling (treemap) → nested ratio splits with gap-as-inset per leaf
+  (adjacent tiles share edges — drift opens gaps).
+- Connected/curve/ring geometry → mask-in-a-cell (handbook §3c); legit-absolute ONLY
+  when the animation varies the mask PATH per frame — almost nothing does.
+- One must-be-exact element at any resolution → the `placeRect` escape hatch (end of
+  this doc).
+
+## Recipe 1 — snap tight-mask cells to a grid (`SNAP_PX`)
+
+After computing a masked piece's tight bbox (see the animation-exemption steps in
+`construction-strategy.md`), **snap it OUTWARD to a small px grid (`SNAP_PX`, e.g. 4)
+before you author the mask** — then build the mask sized to the *snapped* cell. Two
+wins from one move:
+
+- **Seams disappear.** Independently-quantized tight cells miss each other by a
+  sub-pixel (hairline seams between abutting pieces). Snapping every edge to a
+  shared grid lands neighbours on the same grid lines, so they meet.
+- **DSL collapses.** Once all band edges are multiples of `SNAP_PX`, `placeRects`
+  GCD-reduces by that factor (~`SNAP_PX`× shorter). donut/v3: 27,016 → 6,142 chars
+  at `SNAP_PX=4`, ring unchanged.
+
+**Mask-safe because the order matters:** snap the cell, THEN author the mask for
+the snapped cell (`bounds` = snapped cell px). The shape path is still generated
+from the true center/radius (exact geometry); only the cell *bounds* snap, so the
+mask never re-scales. This is the build-time, distortion-free analog of the Layout
+editor's "GCD reduce + drift %" compaction — do NOT run that compaction on a
+mask-bearing doc after the fact (it resizes cells the masks were authored against
+→ distortion).
+
+Pick `SNAP_PX` to taste: ↑ = smaller DSL + coarser edges (more outward drift),
+↓ = larger DSL + finer. ~4px is a good default. (The line-chart does the
+equivalent via a fixed basis grid: `snapAndPlace` quantizes to `BASIS_COL`×
+`BASIS_ROW` so its data layer shares the chrome's basis.) Pair it with a hair of
+overlap between abutting same-content pieces (and a smaller amount across a color
+boundary) so anti-aliased edges can't reveal the background — snapping aligns
+edges, overlap covers the residual.
+
+> Worked examples: `charts/donut/v3/donut.ts` (`SNAP_PX` + `placePiece`);
+> `charts/line-chart/v1/line-series.ts` (`snapAndPlace`). This is how a tight-mask
+> template *makes* its positions GCD-collapsible on purpose — see handbook §3a.
+
+**Head-only as written — a FIXED `SNAP_PX` still tracks the canvas.** A fixed
+pitch bounds the CHAR count but not precision: the basis is `regionSide/SNAP_PX`,
+which grows with the canvas (donut/v3 probed ABSOLUTE, slope 1.04, and pinned its
+parent). A **nestable primitive** uses the self-framed version instead:
+canvas-proportional pitch `P = round(min(W,H)/K)`, square frame side
+`S = ceil(regionSide/P)·P` (a `P`-multiple by construction), `placeRects` inside
+the frame, then ratio-letterbox the frame into the canvas (cost: ≤1px uniform
+translation, zero relative drift). Precision bounds at ~`K` on every canvas —
+even coprime dims. `charts/donut/v4` is the exemplar (`ABSOLUTE 1.04 → RATIO ~0`,
+library to 0 audit warnings); full treatment handbook §3c. Also from v4: on a
+light or deeply-nested surface, anti-aliased sliver notches need an **inflated
+seamless base per segment, timed to each segment's completion** — the
+overlap-hair above can't close an AA gap.
+
+## Recipe 2 — independent chrome/text: launder the basis (`placeInsetPieces` / `placeOptimizedPieces`)
+
+The `SNAP_PX` recipe above is the by-hand move for masked pieces. For a primitive
+that positions **independent** rects (stat-card chrome, KPI blocks, badges) with
+`placeRects`, use the tool-ified version — and the default tool is the
+**zero-drift** one: hand your `{ rect, source }` pieces to `placeInsetPieces`
+(`@m0saic/template-utils`, https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/layout/placeInsetPieces.ts#L119).
+It quantizes each piece's CELL outward to a divisor
+lattice (precision bounds at ~120, the modern canvas-family gcd) and returns the
+frame-aligned sources with a recovery `placement.inset` wired onto each — every
+element paints on its EXACT computed rect. Why it matters: ONE coprime edge pins
+the whole leaf to ~its render canvas AND back-solves to pin the parent
+(`needs = self × canvas ÷ slot`) — the stat-card rail is what held the pulse
+hero's Safe-Min at 1895×1080. Exemplar: `alpine/stat-card/v1` (migrated
+2026-07-10 from the drift budget: same `100% → ~17%` collapse, now with zero
+visual drift; hostile prime-dim cells automatically degrade to exact on that
+axis and render fine). Contract: sources must paint nothing outside their inset
+box (transparent margins), and a source may not already carry `placement.inset`
+— bake design insets into the rect instead (it paints exactly, so shrinking it
+is free).
+
+Reach for `placeOptimizedPieces` (drift;
+https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/layout/placeOptimizedPieces.ts#L95) instead when
+inset-recovery doesn't
+apply: per-piece LOCKS (`drift: "exact"` on must-stay-exact geometry mixed with
+collapsible chrome), container rects, tiles that paint their whole cell, or
+wanted-snap (pixel-aligned strokes). Scope guard for BOTH: independent elements
+ONLY — a uniform grid wants the ratio-grid recipe (Recipe 3; equal cells snap
+unequal under drift), a tiling shares edges (drift opens gaps), and
+connected/curve geometry wants mask-in-a-cell instead (handbook §3c). Full
+treatment: handbook §3c (fixes three and four).
+
+## Recipe 3 — uniform grids: gutterless ratio grid + gap-as-inset (`grid` + `latticeCellInset`)
+
+> **⚠️ Helper changed 2026-07-21.** This recipe's *shape* is unchanged and still
+> correct — gutterless `grid()`, gap in the fiber, zero DSL tokens. But the helper
+> that computes the inset is now **`latticeCellInset`**; **`gridCellInset` is
+> deprecated** (approximate, ±1px gap wobble — see handbook §3c and
+> `HELPER_DEPRECATIONS` in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/deprecation.ts). Read
+> "Migrating off `gridCellInset`" at the end of this recipe before writing code:
+> the replacement is **not a drop-in rename**, it takes different inputs.
+
+**A nestable primitive whose picture is a uniform grid of equal
+cells emits a gutterless `grid()` with the gap as a `latticeCellInset` on each cell
+source — never DSL gutters, never `placeRects` per cell.** The absolute build
+(`placeRects` per cell on a per-pixel snap grid) pins precision to the canvas —
+coprime cell pitches ⇒ `gcd 1` ⇒ ~100% precision (heatmap v1 was a **30k-node
+m0**) — and drift is the WRONG launder here (equal cells snap unequal; a
+quantization-spread guard catches it). The ratio build:
+
+1. **Gutterless `grid({ rows, cols })`** for the cells. No DSL gutters — a gutter
+   is a pixel-width band baked into the split, which re-introduces the
+   coprime-basis blowup. The gutterless grid's precision is the **cell count**
+   (`max(rows, cols)`), constant across every canvas.
+2. **Gap as a per-cell `placement.inset`** via `latticeCellInset({ rows, cols,
+   canvasW, canvasH, gutterXPx, gutterYPx, marginPx, cells })`
+   (`@m0saic/template-utils`,
+   https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/layout/latticeCellInset.ts#L79) — a render-time
+   fractional inset, **zero DSL
+   tokens**, so the layout string stays compact. It authors the TARGET painted
+   grid first as integer lattice lines (`X_k = round(m + k·(unitW + g))`, each
+   boundary rounded independently so drift can't accumulate), then emits each
+   inset as `(px + 0.5) / rawSize` so the engine's per-edge `Math.floor`
+   recovers the integer target exactly. Result: gutters are **exactly** `g` px
+   between every adjacent pair and margins exactly `m`, on every canvas.
+3. **Chrome as plain ratio splits** (`weightedSplit`; the alpine kit's local
+   `rowSplit`/`colSplit` in `alpine/_shared` are sugar over it — not published) —
+   row/col labels, legend, letterbox. Center square cells with a null-node
+   letterbox (`{ weight: LB, node: EMPTY }`), never absolute offsets.
+
+Measured (heatmap v1 → v2, defaultProps): audit `ABSOLUTE slope 1.04 → RATIO
+0.00`; Safe-Min @1080² `~777×583 → ~120×121`; `~30,316 → ~2,211` m0 nodes (~13×
+leaner); ~5× faster default render; precision sweep clean everywhere. The
+Safe-Min collapse is the composability payoff — an absolute grid back-solves
+(`needs = self × canvas ÷ slot`) to pin its PARENT near its own render canvas;
+the ratio grid asks its parent for almost nothing.
+
+Trade-offs to know:
+
+- **Full-bleed vs equal cells.** With `latticeCellInset` this is just
+  `marginPx`: `marginPx: 0` is full-bleed (gaps only *between* cells),
+  `marginPx: g` puts an equal margin around the grid. Unlike the deprecated
+  `gridCellInset` — whose full-bleed default left outer cells up to `gapPx/2`
+  larger than interior ones (invisible for image/color tiles, **wrong for bars**)
+  — the lattice authors every boundary from the same integer line set, so cells
+  differ only by ±1px independent-rounding jitter at any `marginPx`.
+- **Check `maxClampPx` / `clampedEdges` on the result.** When the ideal slack
+  (≈ `g/cols` px at the extreme interior boundaries) drops below the raw split's
+  quantization jitter — tiny canvases with tiny gutters — a target edge escapes
+  its raw cell and is **clamped to the cell boundary rather than thrown**,
+  narrowing that one gutter. `0` on healthy lattices. A template that cares
+  should assert it in its geometry-contract test; degrading to a ≤2px-off gutter
+  at hostile canvases beats a dead render, but you want to know.
+- **`skipFirstRowTop`** (a `gridCellInset` knob, for a grid hugging a header
+  directly above it) has **no direct `latticeCellInset` equivalent** — express it
+  in the lattice instead, by authoring the target rows you actually want.
+- **The gap is not a DSL edge.** Because it's an inset, geometry-mode previews
+  and the Render Hero layout viz must read `placement.inset` to show it (they
+  do). A consumer reading only the m0 doesn't see the gap — that's the point
+  (compactness), but preview code has to opt in.
+- **Values / overlays** ride a *second* gutterless grid of the same shape,
+  `overlay`-stacked on the cells — same precision, index-aligned.
+
+### Migrating off `gridCellInset` (not a rename)
+
+The two helpers take different inputs, because that's *why* the new one is exact:
+
+| | `gridCellInset` (deprecated) | `latticeCellInset` |
+|---|---|---|
+| Sizing basis | the **ideal** cell (`gridW / cols`) | the **raw parsed** cell the engine really produced |
+| Needs | `rows, cols, gridW, gridH, gapPx` | `rows, cols, canvasW, canvasH, gutterXPx, gutterYPx, marginPx, cells[]` |
+| Fractions | plain `n / cell` | half-pixel-centered `(n + 0.5) / rawSize` |
+| Outer margin | `outerMargin: true \| {x,y}` | `marginPx` (integer px) |
+| Returns | inset per cell | `insetAt(i)`, `targets[]`, `columnEdges/rowEdges`, `maxClampPx`, `clampedEdges` |
+
+The load-bearing step is supplying `cells[]`: **parse the COMPOSED m0 at the
+render canvas** and hand over each span's `{ unit, raw }`. The raw cell is the
+truth only *after* basis-capped ratio splits, letterbox bands, and engine
+rounding have all happened — a `split()` whose weights sum past 120 RESCALES to
+basis 120, so no up-front pixel math survives. Computing `cells[]` from your own
+intended geometry re-introduces exactly the ideal-vs-quantized bug you're
+migrating away from.
+
+Then set `placement.inset = insetAt(i)` per source (skip when it returns
+`undefined` — the raw cell already *is* the target), and assert against
+`targets[]` in the geometry-contract test.
+
+> Exemplars: `@m0saic/media/screencap_grid/v2` (gap-carved integer rects → one
+> `placeInsetPieces` call — the pick when the helper should own the whole
+> layout); `@m0saic/alpine/heatmap/v2` (the full data-viz build — cells + value
+> overlay grid + labels + legend — migrated to `latticeCellInset`, with a
+> regression test that replays the engine floor and asserts ONE gap value per
+> axis at both the design canvas and an awkward 1000×700).
+> `@m0saic/media/screencap_grid/v1` is kept registered + `deprecated` as the
+> canonical reference for the ideal-cell-gap pitfall; `@m0saic/alpine/heatmap/v1`
+> likewise for the "absolute grid" anti-example.
+
+## The two floors — and the third question
+
+Every m0 string exposes **two floors** — know which one you're hitting:
+
+- **Feasibility** (`computeFeasibility` → `minWidthPx/minHeightPx`): the "won't
+  error" floor. Below it the layout **errors** (0-size *frame*) — won't render.
+- **Precision** (`M0Precision.maxSplit*`): the "looks right" floor — the smallest
+  canvas where every split cell (incl. passthrough/donation cells) is ≥1px.
+  **Independent of feasibility, and can be higher OR lower** (gutter grids:
+  precision > feasibility; deep nesting: feasibility > precision). In practice
+  render at ≥ the per-axis max of both (`evaluateM0`'s `recommendedMin`).
+- Then a THIRD question above both floors: **quantization** — even on a big-enough
+  canvas, if the split factor doesn't divide the axis the remainder spreads
+  (1996px ÷ 499 → uniform 4px cells; 1920px ÷ 499 → some 3px/some 4px → positions
+  shift). Deterministic, **not a bug** — see the handbook.
+
+To get the appearance guarantee back: render at quantization-free dimensions
+(`snapGridFit` / `snapGridEnumerate` find the largest clean inner rect), keep
+cell counts modest, or quantize to a bounded basis and **derive dependent
+geometry from the weights** so animated/overlaid layers track whatever spread the
+canvas imposes.
+
+Full treatment — feasibility vs precision, the quantization options, and GCD
+collapse — in [`../handbook/feasibility-precision-quantization.md`](../handbook/feasibility-precision-quantization.md).
+
+## Escape hatch — `placeRect` for must-be-exact elements
+
+When an icon / chip / fixed-font band must occupy an exact pixel rect *regardless
+of resolution*, position it with `placeRect` (null-tile margins, byte-exact at any
+canvas; https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/builders/placeRect.ts#L99) — NOT a margin-based
+`insetNode` (an alpine-pack-local helper at
+https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/alpine/_shared/alpine-card.ts#L90, not a published
+API), which turns the margins into split cells and spreads the quantization
+remainder INTO the element (a flaky, resolution-dependent misalignment). See the
+placeRect escape-hatch section in the handbook.
+
+Layout-intent verification for all of these recipes — the label-keyed layout
+contract + the three resolve-only audits — lives in
+[`layout-contract.md`](layout-contract.md).

package/docs/templates/layout-contract.md

@@ -0,0 +1,168 @@
+# The layout contract — verifying layout intent survived
+
+Scope: the opt-in, label-keyed contract layer in `@m0saic/template-utils` that
+checks a template's authored design intent against what the m0 actually resolves
+to at a given canvas. Companion to
+[`construction-strategy.md`](construction-strategy.md) (real-geometry authoring)
+and [`geometry-recipes.md`](geometry-recipes.md) (the placement recipes whose
+output this layer guards).
+
+Verified code paths (as of 2026-07-27; re-verify:
+`grep -rn "export function \(withLayoutContract\|checkLayout\|assertLayout\|withGeometryContract\)" https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/geometry-contract):
+
+- `withLayoutContract` / `assertLayout` — https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/geometry-contract/withLayoutContract.ts#L65 / `:106`
+- `checkLayout` + `LayoutConstraint` — https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/geometry-contract/layoutConstraint.ts#L215 / `:39`
+- `withGeometryContract` — https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/geometry-contract/withGeometryContract.ts#L69; `GeometryExpectation` — https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/geometry-contract/types.ts#L24
+- The three audits — npm scripts in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/package.json#L13-15` (run from https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates)
+
+## Why it exists
+
+Real-geometry-first gets the rects right in JS pixel math — but the m0 is exact
+yet **disposable**: a template re-addresses its whole geometry tree on any change
+of canvas or props, so stableKeys and tile order are per-string and can't carry
+authored intent. And quantization squashes stay invisible to every
+string-level tool because the STRING is healthy (the stat-card icon rendered
+33×23 for an intended 26px square; the value band crushed 59→38px; grid/v1
+SILENTLY VANISHED when nested at small canvases). `@m0saic/template-utils`
+closes the loop with a **label-keyed, ratio-based contract** — opt-in per
+template.
+
+## Labels carry intent
+
+**Intent lives on a LABEL.** Tag a source (`source.editor.label = "hero"`);
+wherever the builder scatters it in the string, the **source array is the
+invariant** — the engine binds `sources[frame.logicalIndex]`, so a tag ties to
+its exact geometry node. Declare invariants against the label, as
+canvas-INDEPENDENT ratios:
+
+```ts
+withLayoutContract(doc, ctx, {
+  templateId, debug: props.debugLayout,
+  constraints: [
+    { label: "hero",   aspect: 16/9, aspectTolerance: 0.04 },   // shape, at ANY canvas
+    { label: "value",  minHeightFrac: 0.18, minWidthFrac: 0.5 },// ≥18% tall, ≥50% wide
+    { label: "header", within: { yFrac: [0, 0.22] } },          // lives in the top 22%
+    { label: "grid" },                                          // PRESENCE — must render at all
+  ],
+  relations: [
+    { label: "photo", equal: "size" },                          // uniform thumbnails (one-to-MANY)
+    { label: "photo", gutter: { axis: "x", target: 0.02 } },    // even 2%-of-canvas gutters
+  ],
+});
+```
+
+- **`checkLayout(doc, { canvasW, canvasH, constraints, relations, flatten? })`**
+  is the PURE evaluator — a template (or an agent) loops on it during a **layout
+  search**: try a packing via the DSL builders → evaluate → keep the one whose
+  labeled invariants hold. `withLayoutContract` is the debug tripwire (falsy
+  `debug` → returns `doc` untouched at zero cost; a violation → a
+  `LAYOUT_CONTRACT` error mosaic at the canvas that broke + an
+  `editor.layoutContract` stamp). `assertLayout` is the throwing CI sibling.
+- **A label is one-to-MANY** — `{ label: "cell", aspect: 1 }` checks EVERY cell,
+  so you constrain a KIND, not a node.
+- **Presence, including THROUGH nesting.** A bare `{ label }` asserts the element
+  rendered; `checkLayout` auto-flattens nested docs (a parent's top-level m0 is
+  trivial), so a parent guards a nested child — and a flatten failure
+  (`SPLIT_EXCEEDS_AXIS`) IS the drop signal. This is exactly what would have
+  caught grid/v1's silent nested vanish at the canvas it broke (regression test:
+  https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/primitives/grid/v1/grid.regression.test.ts).
+- **Running the contract backfills `doc.labels`** (`stableKey → label`) from the
+  source tags — labeling and checking are one pass; Make / `.m0c` / diagnostics
+  get the human names for free.
+- **You author the label; the per-m0 resolution is OUTPUT.** The result's
+  `matched` / `resolved` map each label → the `stableKey` + `sourceIndex`
+  (= `logicalIndex`, the `sources[]` index) it landed on THIS render — for tooling
+  (Make's jump-to-piece), never for authored intent.
+
+## The three audits (all resolve-only — NO ffmpeg)
+
+- `npm run audit:layout-envelope` → `LAYOUT-ENVELOPE.md` — per labeled invariant,
+  the **canvas range where it holds vs breaks**, with the boundary
+  (`breaks ≤ Npx, holds ≥ Mpx`). The layout-solver report: it hands you the
+  feasible envelope, so you fix the geometry math for the range you need or
+  declare the template's supported output range.
+- `npm run audit:geometry-matrix` → `GEOMETRY-MATRIX.md` — curated tier sweep
+  (modern-core / adjacent / hostile) with §3c routing hints (geometry expectations).
+- `npm run audit:geometry-proof -- --template <id> [--range … | --canvases …]`
+  → **sloth** tier (NOT in the merge gate; estimator refuses ≥10min without
+  `--yes`), a clustered PROVEN/FAILED report (geometry expectations).
+
+## Two contracts, distinct jobs
+
+- **`LayoutConstraint`** (label + ratio) — the authored DESIGN contract; survives
+  every m0 the template regenerates. Add a `debugLayout?: boolean` prop (section
+  "Debug", deterministic default false).
+- **`GeometryExpectation`** (px rect + inset + maskBounds, zip-ordered) — the
+  SECONDARY "did the builder's m0 round-trip" guard, emitted for free by
+  `placeInsetPieces` / `placeOptimizedPieces`; `withGeometryContract` +
+  `debugGeometry`. Near-tautological for a correct builder — use it to
+  regression-lock a zero-drift placement, not to express design intent.
+
+## Text: fit under the ruler the contract measures with
+
+The engine's `drawtext` never shrinks a string — `placement.fit:"contain"` only
+picks the anchor. A font derived from a bar's HEIGHT alone clips the moment the
+canvas is narrower than the design aspect (portrait 1080×1920 turned "Animated
+Wireframe" into "Animated"; 4-digit values into two digits — gate 33,
+dsl-tutorial, 2026-09-05). Every text a template paints needs a WIDTH budget.
+
+- **`textFits` is the contract side** — `{ label, textFits: { charWidthEm?, padPx? } }`
+  (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/geometry-contract/layoutConstraint.ts#L285; defaults
+  `0.72em` / `2px`, measured against the CLI rasterizer) estimates
+  `textEmUnits(text) × fontSize × em + pad` (`:71`) against the label's realized box.
+  Expr content is skipped by design (a live counter has no single width).
+- **Fit with the SAME ruler.** Size the font from `textEmUnits × em` so the fit and
+  the check can't disagree. Per-site em that held at 12 canvases (1920×200 …
+  3840×2160): prose/labels `0.62`, digit-heavy values `0.68`, ALL-CAPS captions
+  `0.76` (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/dsl-tutorial/v1/_shared/text-fit.ts:
+  `PROSE_EM` / `DIGIT_EM` / `CAPS_EM`, `fitFontPx`, `fitLine`).
+- **Budget = `cell × 0.94 − 2px`** (`FIT_SLACK`, `FIT_QUANT_PX`). Floor quantization
+  hands a leaf 1–2px LESS than its modelled share, per split level, not
+  proportionally — a proportional-only slack passed the model and still failed the
+  realized box (a 28px chip realized 24px at 800×450). With the budget carrying
+  the allowance, declare `textFits.padPx: 0`.
+- **Degrade ladders beat ellipsis at the floor.** Title: shrink to 70% of the design
+  size, THEN ellipsize. Pills: full → compact wording (`Speed  1.0x` → `1.0x`).
+  Status strips: drop trailing metrics (whole ones). Captions: blank at the floor.
+  Tile marks: drop the dims line, keep the number.
+- **Per-glyph-column text (a strip, a ruler) is bounded by its WIDEST glyph**
+  (`>` .86em, brackets .42em on the m0 alphabet — `widestM0GlyphEm`), not a flat
+  cap; a flat prose em over-measures a comma-heavy m0 string ~1.7×.
+- **Live/expr text can't be contract-checked** — model its WIDEST state
+  (`Step  N / N`) for the fit and lock it in a unit test.
+- **Chrome that is a fraction of HEIGHT is a portrait bug waiting** — size bars off
+  `min(H, 0.75·W)` (landscape byte-identical; portrait gets app-bar chrome) and cap
+  row heights to the panel WIDTH in tall side panels.
+
+## `missing-label` is the drop signal, not noise
+
+A hairline (a 1-unit rule inside a ~1px/unit band) quantizes to a 0-size frame →
+`SPLIT_EXCEEDS_AXIS` → the CLI refuses the whole render ("expects 39 renderable
+sources but doc.sources has 40" at 480×270), and `flattenMosaicDocument` collapses
+the WHOLE nested layout wherever the child's slot and the flattened parent's cell
+differ by ±1px (700–960px wide for dsl-tutorial). The label-keyed contract reports
+this class as `missing-label` ("layout collapsed … flatten failed") — treat it as
+the geometry bug it is. The sizing rule lives in the handbook
+([`feasibility-precision-quantization.md`](../handbook/feasibility-precision-quantization.md)
+§3 "Hairlines").
+
+## Recommended: the contract BEFORE the first candidate (founder, 2026-09-05)
+
+"The layout contract can be heavily recommended in a template authoring guide due
+to this exact scenario." Default authoring step for any template that paints text:
+
+1. **Tag every fitted text source** (`tag(src, label)`) and declare `textFits` for it
+   under the template's `debugLayout` prop — before minting candidate-01.
+2. **Sweep `assertLayout` at the 7-canvas set in the gate test** — 1920×1080 ·
+   1280×720 · 1080×1920 · 1080×1080 · 3840×2160 · 640×360 · 480×270 — THROUGH
+   nested children (`checkLayout` auto-flattens). The end user only ever sees
+   "layout contract satisfied"; the failures it takes to get there are the agent's,
+   and the sweep is where they surface. Exemplar:
+   https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/dsl-tutorial/v1/dsl-tutorial.gate33.test.ts.
+3. Debug-only, forever (2026-08-22 ruling): a production render never blocks on a
+   contract violation — `debugLayout` is the tripwire, the gate test is the lock.
+
+Full design: (internal design history). Opt-in —
+trivial-geometry templates gain nothing; don't add ceremony. The positioning
+audit + precision sweep remain the zero-effort baseline every template gets for
+free.