@m0saic/knowledge 0.2.0

package/docs/templates/output-resolution-tree.md

@@ -0,0 +1,202 @@
+# The output-resolution tree
+
+How a render's top-level **duration / size / fps / format / audio** resolve,
+across CLI, Make, templates, and the engine. Mapped at gate 28 (2026-08-31)
+after three gates of the same bug class; merged from
+`candidates/2026-08-31-output-resolution-tree.md`.
+
+When writing a template or a host feature that touches any of these values,
+place it in the tree FIRST — the recurring failure is a value from one layer
+masquerading as another.
+
+## The law (as it now stands, gates 20–28)
+
+Precedence, top to bottom — higher wins:
+
+```
+L0  USER EXPLICIT      the ask the user actually typed/clicked
+L1  TEMPLATE INTENT    what the doc AUTHORS (the render's own declarations)
+L2  HOST DEFAULTS      hints the host seeds when the user said nothing
+L3  ENGINE DEFAULTS    DEFAULT_DURATION_MS / DEFAULT_FPS / mp4 / silence
+```
+
+The recurring bug class of this sprint (gates 26, 27, 28) was always the same
+shape: **an L2 value masquerading as L0** (hint-seeded target read as a pin;
+host canvas clobbering authored size) or **an L1 value lost in the wrapper**
+(stampDocOutput clobbering authored durationMs/size).
+
+## Per-property trees (current, verified)
+
+### durationMs
+- **L0**: CLI `--durationMs` → `ctx.userIntent.durationMs` (assembleUserIntent)
+  + plan `options.durationMs` (DURATION_MS_OVERRIDDEN_BY_CLI diagnostic).
+  Make's Duration field → `userIntent.durationMs` when SET (Q1, 08-31).
+  CLI `.mosaicx` path (`make <file.mosaicx>` / `resolve`): `--durationMs ??
+  wrapper.durationMs` → `userIntent.durationMs` via `mosaicxUserIntent`
+  (the CLI source (not published), 09-05) — the wrapper's `durationMs`
+  was already the plan length, so it is an explicit ask; before 09-05 it only
+  set the plan length and TRIMMED self-timing templates instead of pinning them.
+- **L1**: doc authors `durationMs` → `stampDocOutput` preserves it (gate-26
+  law). Pipelines: per-step `durationMs` is always authored (rule 4);
+  `resolveStampedPipelineDurationMs`.
+- **L2**: CLI seeds the render target from `outputHints.durationMs`
+  (animated variants: `resolveUnpinnedDurationMs`). The hint-echo trap is
+  CLOSED (Q1, 08-31): `resolvePinnedDurationMs` is `userIntent`-only, so a
+  hint-seeded `output.durationMs` can never read as a user ask. Template side:
+  never compare `ctx.output.durationMs` to your own default to detect a pin —
+  that reads L2 as L0 (dsl-tutorial crammed every walk into its 12s hint, gate
+  33, 09-05); call `resolvePinnedDurationMs(ctx)`, else author the natural
+  length on `doc.durationMs` (L1).
+- **L3**: `DEFAULT_DURATION_MS`.
+
+### size (width × height)
+- **L0**: explicit `-w/-h` / Make Device — ALWAYS wins. `make`'s dims are
+  now OPTIONAL: absence IS the explicitness signal (no provenance
+  introspection needed).
+- **L1**: the doc's own `size` — **required on every ROOT document** (the
+  boundary law: platform serializer + loader assert it; children stay
+  optional — the stretch-vs-letterbox lever). Hosts default the plan to
+  it: saved files reproduce ("open a .mosaic, render, get the same
+  thing"), templates that author their canvas (brand marks at official
+  dictionary dims) get it as the default. `stampDocOutput` preserves
+  authored size; docs authoring nothing get the resolved target so every
+  stamped root carries a canvas. Steps: `step.file.size` (rule 4) — same
+  law, always had it.
+- **L2**: template path seeds ctx from the template's hints when no explicit
+  dims — the static `outputHints.width/height`, with the template's
+  `resolveOutputHints(props)` merged over them (2026-09-15, the canvas-as-a-
+  knob contract: a creator template's `platform` picks 1920×1080 vs
+  1080×1920). ONE helper for every host: `resolveTemplateOutputHints(tmpl,
+  props)` in `@m0saic/template-utils` (CLI `make` + the wireframe/tutorial
+  paths, Electron preview/cover/renderToFile, the web design preview, and
+  Make's Device anchor, which re-resolves on every prop change so a locked
+  canvas follows the knob BEFORE the next preview). Tolerant: a throwing or
+  junk resolver falls back to the static hints; width/height round to even.
+  Fallback 1280×720.
+- **L3**: none.
+- **Guard law (2026-09-15):** the template-path feasibility guard measures the
+  rendered doc at the size the PLAN uses — the doc's authored size when no
+  `-w/-h` — never the hint-seeded target. It used to read the target and
+  rejected a correctly authored 1080×1920 doc against a 1920×1080 hint
+  ("below the minimum feasible") — the hint-read-as-ask bug class again.
+- **Removed**: `sizePolicy` (existed for ~a day) — "size always present +
+  default-not-command" dissolves the intent-vs-history ambiguity without
+  a field.
+
+### fps
+- **L0**: CLI `--fps` (explicit only — threads to planOptions;
+  FPS_OVERRIDDEN_BY_CLI). Make Output fps passes explicitly → wins (open
+  founder call from gate 20).
+- **L1**: pipeline-authored fps (gate-20: `resolveStampedPipelineFps`,
+  fps-follow for recordings). Plain docs: stamped from resolved target.
+- **L2**: `outputHints.fps` as ctx default. **L3**: DEFAULT_FPS.
+
+### format (container/kind)
+- **L0**: `-o` extension / `--format`.
+- **L1**: doc `format` (gate-26 convention: every rendered doc declares it)
+  + CLI rule-5 POST-RENDER enrichment (gate-22: authored mode-dependent
+  detail reaches the resolver; explicit `--alpha` wins). `doc.target`
+  presets resolve to format/audio/color defaults; per-field overrides win.
+- **L2**: the template tier, two statements, the more specific first:
+  1. a reserved prop named **`outputFormat`** holding a container name
+     (`png` / `jpeg` / `webp` → image; `mp4` / `mov` / `webm` / `mkv` → video) —
+     trickplay, screencap-grid, page-skeleton, qr/code, highlights. A prop is
+     the template speaking *per render*, so it WINS over the static hint
+     (the CLI source (not published) `handleTemplateMake`, flipped 2026-09-13 —
+     before that the hint would have silenced the knob; Make's
+     `outputFormat`-prop sync already behaved this way).
+  2. `outputHints.format` — the static deliverable. **Every public template
+     declares one** (the `outputFormat` convention, record posture — see
+     [`philosophy-and-contract.md`](philosophy-and-contract.md) §Output
+     contract); a knob template declares the knob's DEFAULT so the two agree
+     at defaults.
+- **L3**: mp4 — reached only by internal / deprecated templates now.
+
+Why L2 matters beyond the extension: the Make share link carries an `f=` ask
+only when the form's output kind differs from what the hint would set on the
+receiver, and the modal maps an empty kind to video — so a hint-less template
+put `f=video` on every link at defaults (the 2026-09-13 sweep: 33 public
+templates gained a hint, 26 video / 7 image).
+
+### audio
+- **L0**: CLI `--no-audio` → `audio.mode:"off"` patch.
+- **L1**: doc/encode `audio.mode` — the TRI-STATE law (Q2, founder-ruled
+  2026-08-31; `enabled: boolean` is GONE from `MosaicAudioConfig`, hard
+  swap, no deprecation):
+  - `"off"` → never a track, even with real inputs (the mute knob);
+  - `"on"` → always a track (real mix, or an anullsrc silence bed);
+  - `"auto"`/absent → real mix when audio-bearing inputs exist, **NO track
+    when none** — silent visuals ship video-only by default.
+  Source-level `MosaicAudioProps.enabled` (per-tile mute) is a DIFFERENT
+  type and keeps its boolean.
+- **L3**: silence-by-default is RETIRED. The engine chain rule:
+  - "Audio-bearing" = INTENT, not bindability: probed `hasAudio` streams
+    count, and an unprobed `mediaType:"audio"` source still counts (its
+    intent is unambiguous; the mix degrades to a bed, never to no-track).
+  - Internal carriers still always mux `[outa]` (gate-21 binding), but a
+    binding-only bed is stamped `audioIntent:false` on the command, and the
+    node-output stamp skips `hasAudio` for it — a child's bed never becomes
+    the parent's "audio input" (pre-fix every child-bearing composite
+    shipped a phantom silent track).
+  - Pipelines: `pipelineWantsAudio` resolves the same tri-state AFTER the
+    step loop ("auto" = any step actually muxed); the xfade stitch now
+    synths silence legs for audio-less steps exactly like the cut-concat
+    path (the old KNOWN GAP, hit the moment silent steps stopped muxing).
+  - Argv honesty on no-`-map` commands: `stepMuxesAudio`'s fallback reads
+    "no -map, no -an" as "keeps the input's audio", so any command without
+    maps that can end a nested plan MUST carry `-an` when its output is
+    video-only — the loop-fit pass (`pipeline_duration_fit`) does now
+    (a silent nested pipeline's fit output otherwise made the outer stitch
+    bind a `[i:a:0]` that matched no streams).
+  - Mixed compositions ("one source has audio, one doesn't" — the historic
+    reason for authoring null-audio beds everywhere) are guarded at three
+    levels: flat mixes probe-gate `[i:a:0]` refs to stamped streams; stitch
+    legs synth silence per audio-less step; child carriers always mux beds
+    so parent binding can't fail. Authored silence beds are no longer
+    needed for composition safety.
+  Locked by: `pipelineAudio.spec` ("Q2 tri-state law" describe),
+  `ffmpegCommands`/`buildMosaicPlanFromFile` unit specs, the CLI contract
+  matrix (57 silent-fixture rows now `acodec:null`, `audio-mode-on`
+  fixture = the bed opt-in leg, `codec-matrix-audio` out-silent = the mute
+  leg, `audio-montage-child` = real child audio survives).
+
+## Open simplifications (proposed, awaiting founder ruling)
+
+1. **Q1 — DONE (2026-08-31, founder-ruled).** Duration pinning is
+   `userIntent`-only: `resolvePinnedDurationMs` reads ONLY
+   `ctx.userIntent.durationMs`; the CLI populates it from an explicit
+   `--durationMs`, Make (electron main) from its Duration field when SET —
+   in both the real-render and design-preview ctx so they agree. The
+   hint-echo trap is dead globally; search-typing's gate-27 local
+   discriminator deleted. Fallback users verified: mermaid already fit to
+   `?? ctx.output.durationMs` (unchanged); camera-debug + snippet-morph
+   treat unpinned as natural cadence (the correct behavior their hint-pins
+   were masking).
+2. **Q2 — DONE (2026-08-31, founder-ruled).** Audio default flipped + the
+   config went tri-state (`mode: "auto"|"on"|"off"`, `enabled` deleted with
+   no deprecation — "we are pre launch", callers migrated, old docs may
+   break). Full law + engine chain rule in the audio section above. The
+   recurring gate-20 silent-track class is retired at the root: doc-level
+   `audio:{enabled:false}` boilerplate is no longer needed on silent
+   templates (existing `mode:"off"` sites are now pure intent, not
+   bug-avoidance). Golden sweep done (command goldens re-minted: silence-
+   bed mux siblings dropped, `-an` on silent deliverables).
+3. **Q3 — one duration-follow helper.** subtitle-burn, search-typing,
+   highlights each hand-roll "explicit ask wins, else follow natural/
+   input" with different spellings. A template-utils
+   `resolveOutputDurationMs(ctx, { naturalMs })` encoding L0>L1 would make
+   the law one function. (Blocked on Q1 for the clean version.)
+4. **DONE this gate:** the size tree is fully coherent (required-at-root
+   boundary law + optional `-w/-h` + host defaults to doc size);
+   `makeErrorMosaic` audio + size fixed fleet-wide; the stale
+   pre-gate-26 duration expectation in defineMosaicTemplate.test aligned.
+
+## Non-goals
+
+`outputHints` stays static (L2 seeding only) and is the browse-time truth
+(manifest, cards). Props-dependent dims need BOTH halves: author the doc for
+the PLAN (L1), and declare `resolveOutputHints(props)` so hosts SEED the
+right target too (L2) — the resolver is what removes the letterbox and the
+wrong-canvas guard. The seam's `outputHintsResolve` convention (throw) keeps
+it honest: an object, deterministic, and at `defaultProps` equal to the
+static hints for every field it returns.

package/docs/templates/patterns/case-study-lessons.md

@@ -0,0 +1,69 @@
+# Template case-study lessons
+
+Distilled 2026-07-26 from seven Feb-era case-study essays (deleted — git history has
+the long forms). Format follows [`perf-authoring-rules.md`](perf-authoring-rules.md):
+the rule, the incident that paid for it, the code that proves it. Companion:
+[`primitive-extraction-pattern.md`](primitive-extraction-pattern.md).
+
+**L1 — Derive overlay depth from source count; never hardcode `F{F{F}}`.**
+`buildOverlayStack(sources.length)` (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/m0saic/build-overlay-stack.ts#L11)
+keeps the m0 and the source array in lockstep when layers are added/removed.
+**But** apply the Rect-Thesis smell test first: if your m0 is `buildOverlayStack(N)`
+with `N == element count` and every source is full-canvas, you've baked pixel-math
+into drawtext instead of geometry — Preview/Render Hero will be empty. Rebuild with
+real cells ([`../construction-strategy.md`](../construction-strategy.md)).
+
+**L2 — Solid-colour cells are `makeColorTile`, not text-sources-with-background.**
+The old pill-bar technique (empty `MosaicTextSource` + `visual.backgroundColor`) is
+explicitly legacy: lavfi `color=` is free per cell, and `makeColorTile` tiles are
+valid `MosaicRefSource` targets without escape hatches
+(https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/sources/makeColorTile.ts#L28). For lavfi sizing,
+`fitMode:"tile"` fills the slot rect; `"content"` sizes to the content box +
+placement.
+
+**L3 — Transparent lavfi + `drawbox` needs `:replace=1`.** Plain `drawbox` on
+`color=black@0` blends RGB but does NOT write alpha. This is
+[`perf-authoring-rules.md`](perf-authoring-rules.md) **R7** — canonical there;
+verify transparent tracks in rgba.
+
+**L4 — Staggered reveals: lead + trail padding, identity by `logicalIndex`.**
+The wireframe reveal (`wireframe/animated/v1/animated-wireframe.ts`) is the reference:
+`startAtSec = leadPaddingSec + i * staggerSec`; trail padding =
+`max(leadPaddingMs, OVERLAY_SLIDE_MS = 300)` so the LAST slide finishes before the
+cut (`:157-161`); per-tile identity via `frame.logicalIndex`
+(`childId = \`cell-${logicalIndex}\``, `:236`). Gate with the typed
+`overlay.window` (preferred) or a recognized `enable` shape (R4).
+
+**L5 — Rank-driven per-tile animation (brand/logo/v3 machinery).** A deterministic
+rank function maps every filled tile to its time slot; four modes
+(`logo_loop | progress_fill | loading_shimmer | loading_ui_v2`) + `rankSet`
+(`diag | cascade | radial`) reuse one rank→enable/alpha pipeline
+(`brand/logo/v3/logo.ts:39`). Guard frame 0 with `gte(t, 1/fps)` so nothing pops
+before its slot. Two-doc blends ride the `F{F}` runner
+(`logo/v3/logo_runner.ts:233`). Dictionary geometry ids: `m-33`, `m0`,
+`m0saic-pattern`, `m-33_bitmap` (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/dictionary/src/entries/brand).
+
+**L6 — Primitive positioning must be RATIO-based, and verified NESTED.** grid v1
+computed absolute pixel positions and re-encoded them as a canvas-scale `placeRects`
+basis: renders perfectly standalone, **silently drops when nested** (the engine
+re-divides the per-pixel basis below 1px at e.g. 1024²). grid v2's design law:
+position = a proportion of the cell expressed as an overlay offset (`H*frac`);
+thickness = decoupled fixed-px strips (`primitives/grid/v2/grid.ts:23-40`).
+Composability wins over node count. Corollary: "runnable standalone" is NOT a
+sufficient primitive gate — test the primitive nested inside a parent split.
+
+**L7 — Primitives never interpret domain config.** A gridline primitive takes counts
+and fractions, not "chart config". [`primitive-extraction-pattern.md`](primitive-extraction-pattern.md)
+Rule 1 owns this.
+
+**L8 — Internal-pane text sizes derive from `ctx.target.height`, NOT the pane rect.**
+The screencap InfoPane fix (`media/screencap_grid/internal/info_pane.ts:56-58,93-94`):
+`titleFontSize = clamp(16..48, round(targetH * 0.022))` — pane-proportional fonts
+wobble as the pane resizes, and fractional y-offsets resolve against the RASTER
+height, landing text in the wrong band. Pixel-anchor metadata blocks
+(`metaY = topPad + titleBlockH + gap`); auto-size the pane from content in the
+parent.
+
+**L9 — A template can be a TOOL.** The contact-sheet class (screencap grid) earns
+its keep by producing a decision artifact a human can understand, share, and act on
+immediately — design for that artifact, not for DSL flex.

package/docs/templates/patterns/perf-authoring-rules.md

@@ -0,0 +1,100 @@
+# Template perf authoring rules
+
+> Templates layer. The author-facing distillation of the engine's cost model and
+> ffmpeg walls — the rules below stand alone; the deep dives are
+> **engine-internal** (`.ai/moat/runtime/render-cost-model.md`,
+> `.ai/moat/runtime/ffmpeg-limitations.md` — absent in the shipped copy).
+> Every rule below was paid for by a real dsl-tutorial or chart-template incident.
+
+## R1 — Complexity belongs in the m0 string, not the source list
+The string is near-free (millions of chars parse fine); **source count is the cost**
+— every source is built at setup AND composited on every frame for the whole clip
+(no active window unless it declares one — see R4). The smell: emitting N sources
+to draw ONE visual thing. Measured: a donut whose sweep needed 31 lavfi arc
+slivers took 376s to render 3s. Window gating does NOT fix this — the setup
+intercept and the per-frame composite count remain per source.
+
+## R2 — Smooth shapes are ONE masked tile; coarse shapes are a few unmasked tiles
+A mask is one source regardless of edge length; a tile grid stitches at ~N².
+Never draw shapes with drawtext glyphs (tofu) or text-masked rects (distortion) —
+shapes are `makeColorTile` + inline-mask SVG with `bounds` = cell aspect.
+
+## R3 — Never geq; never expression-mode filters
+geq evaluates its expression per pixel per frame — 2–3 orders of magnitude over
+compiled filters. Rounding and shape masks are SVG sidecars now (engine default).
+The trap re-enters through the back door: a time-varying `overlay.alpha` expression
+compiles INTO a per-pixel geq fold. Which is why —
+
+## R4 — Give every short-lived source a WINDOW; animated alpha is affordable when canonical
+`overlay:enable=` is a scalar per-frame gate (free) — still the right tool for
+hard on/off. And since the enable-gating engine sprint (2026-07-09/10), windowed
+FADES are cheap too: canonical alpha products (`fadeInExpr` shapes, `exit()`
+complements, the in/hold/out envelope, constants) lower to compiled
+`fade`/`colorchannelmixer`, and any surviving fold is dual-gated + trimmed to
+the source's window. Declare the window as an `enable` in a recognized shape
+(`gte(t,A)`, `lt(t,B)`, `between(t,A,B)`, `gte*lt`) or the typed
+`overlay.window {startSec,endSec}` — the published motion-kit helpers
+(`entrance`/`exit`/`composeMotion` + the track builders in
+`@m0saic/template-utils`) emit it automatically, as do the alpine-pack-local
+reveals (`revealGate`/`revealSlideNode`/`revealFade` in
+`alpine/_shared/alpine-anim.ts` — pack-local, not published). What still costs: NON-canonical alpha with NO window (spatial
+sweeps, custom eases, unbounded lifetimes). Consequence for two-mode templates:
+the alpine premium/light split is now a LOOK decision, not a perf one — the
+runner renders premium ≈ 3× faster than pre-sprint light.
+
+## R5 — A value that changes N times = one layer per DISTINCT VALUE, not one N-boundary expression
+The narration-collapse idiom (dsl-tutorial inspector). A single `%{eif:…}` with ~100
+change-boundaries crashes drawtext's ~80-boundary budget; 8 fields × animated alpha
+overflowed a filtergraph. One text source per distinct value, enable-gated over the
+union of windows where that value holds.
+
+## R6 — Line geometry over time = ONE lavfi drawbox track, not N masked overlays
+Cursors, split lines, borders, curtain wipes: collapse N time-disjoint elements into
+one lavfi source whose graph is a flat chain of enable-gated `drawbox` ops. Depth
+O(N) → O(1); measured 37.9s → 9.0s on the 4×4 canvas. Keeps the whole panel at a
+fixed handful of overlay layers at any tile count — safely under the ~25 overlay-depth
+mask-drop ceiling (see limitations doc W3). Constraints: solid rect strokes only
+(dashes = runs of boxes); positions snap per-window (no smooth per-frame motion).
+For a masked line draw-on, use a curtain wipe over the static art, not a per-sliver
+cascade.
+
+## R7 — `replace=1` on every drawbox over a transparent base
+Plain `drawbox` on `color=black@0` blends RGB but does NOT write alpha — edges are
+`(r,g,b,0)`: visible in an rgb24 probe, gone after compositing. Verify transparent
+lavfi tracks in **rgba** and check edge-pixel alpha.
+
+## R8 — Bake what never changes
+A subtree that is constant across renders and expensive to composite → render it once
+and reference the asset; a precise subtree that bloats the parent → nest it
+("reduce to 1"). Triggers, mechanics, and measured payoffs:
+[`../../runtime/reduce-to-one.md`](../../runtime/reduce-to-one.md). The cost-model
+bar: an intermediate round-trip costs ~5–15 ms/frame — anything costlier in-graph
+should be materialized.
+
+## R9 — Text: svg rasterizer for static, drawtext only for per-frame-dynamic
+`rasterizer:"svg"` turns static text into a mask + color tile (no drawtext, no
+per-frame shaping). It does NOT support expressions — that fallback to drawtext is
+correct, keep dynamic text drawtext and keep the instance count low. Mind
+density budgets: hundreds of glyph masks in one panel approach the argv wall
+(dsl-canvas caps: 260 mask subpaths, 200 labels, 500 curtain boxes per source).
+Also: the app fits text wider than the CLI — leave generous fixed-font margins.
+
+## R10 — Camera: constant zoom is cheap, animated zoom is a different animal
+Constant zoom = static `eval=init` scale + free crop. An animated zoom forces
+per-frame scale (`eval=frame`) — the stream becomes variable-size and materially
+more expensive. Don't animate zoom for effect you can get from enable-gated cuts.
+
+## R11 — Measure before optimizing
+`m0saic make … --perf` writes a `.perf.json`/`.perf.md` sidecar: per-command timing
+rolled up by node, with `overlayDepth` per rect and a hotPath. Render at two
+durations to split setup cost (intercept) from per-frame cost (slope). Optimize the
+named bottleneck, not the vibe.
+
+## Quick pre-flight (before handing off a candidate)
+- [ ] Source count ≈ number of visually distinct things (not slivers/glyph shards)?
+- [ ] Any geq / animated-alpha / N-boundary expression? (R3–R5)
+- [ ] Line geometry collapsed to tracks; `replace=1` present? (R6–R7)
+- [ ] Overlay depth per panel comfortably under ~25?
+- [ ] Static text on svg rasterizer; dynamic text instances counted? (R9)
+- [ ] Constant-across-renders expensive subtree baked or nested? (R8)
+- [ ] `--perf` sidecar checked once at target size?

package/docs/templates/patterns/primitive-extraction-pattern.md

@@ -0,0 +1,103 @@
+# Primitive Extraction Pattern (Templates → Primitives)
+
+The repeatable pattern for extracting reusable, globally-useful logic from a
+domain template into a **primitive** under `@m0saic/primitives/*`. Goal:
+primitives reusable across templates for years without inheriting domain
+assumptions.
+
+> **Source of truth:** primitives in [https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/primitives](https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/primitives); extraction helpers: `buildOverlayStack` in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/m0saic/build-overlay-stack.ts; `transparentSlot`, `lavfiStrip`, `buildGridlineSources` in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/primitives (`transparentSlot.ts`, `lavfiStrip.ts`, `girdlines.ts` (sic — misspelled in code)).
+
+## Definitions
+
+- **Domain template** — expresses a specific user-facing feature or design
+  (e.g. `@m0saic/collage/image-collage/v1`). Owns semantics, tunings, theme
+  tokens, animation rules.
+- **Internal template** — used only inside one domain template's tree (e.g.
+  `charts/bar-graph/v1/internal/plot-area`). Often expects injected children /
+  parent refs; often not runnable standalone; carries domain assumptions.
+- **Primitive template** — globally reusable building block (e.g.
+  `@m0saic/primitives/grid/v2`). One focused job, no domain coupling, runnable
+  standalone, designed for reuse across domains.
+
+## When to extract
+
+Extract when most of these hold: the behavior is **general** (gridlines,
+borders, matte fills, masks, simple overlays); it's **parameterizable** with a
+small stable prop surface; it's **already being reimplemented** (copy/paste
+creep); it has **no domain meaning**; it's **useful outside** the current
+template.
+
+Do NOT extract when: logic depends on domain semantics ("baseline belongs to
+PlotArea"); props need parent/child wiring (refs like `barsStackRef`); it's an
+experimental one-off or unstable API.
+
+## Hard rules
+
+1. **No domain semantics.** A primitive must not know "charts", "baseline",
+   "bars", "labels", or domain axis config. Accept generic parameters
+   (`direction`, `origin`, `excludeEdges`); the domain template decides meaning.
+2. **Small, explicit prop surface.** Prefer `direction`, `count`,
+   `excludeEdges?`, `origin?`, `color?`, `opacity?`, `thicknessFrac?`. No
+   kitchen-sink domain config objects.
+3. **Runnable standalone.** `m0saic make @m0saic/primitives/<slug>/vN` must
+   produce valid output — no required child refs, safe defaults, no crash in
+   isolation.
+4. **Flagged correctly.** Set `primitive: true`
+   (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts#L1416 — "is this a base others
+   build on?") and default to public (`internal: false` — "can this render on
+   its own?"); the two flags are orthogonal and compose freely. Example:
+   `primitives/grid/v1/grid.ts:166`. A truly-internal helper is not a
+   primitive; it's an internal utility template.
+5. **Reusable composition helpers.** Never hardcode `F{F{F}}` overlay chains —
+   compute from count via `buildOverlayStack(n)`.
+6. **Valid canonical m0 only.** Helpers that generate m0saic must produce
+   canonical strings, validate (or finalize) before returning, and return
+   branded `M0String` where possible.
+7. **Verify the primitive NESTED, not just standalone.** Standalone renders
+   prove nothing about composition: grid v1 satisfied every rule above and was
+   still deprecated. Its single-axis path re-encoded absolute pixel positions
+   as a `placeRects` split with a per-pixel basis — per the v2 header
+   (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/primitives/grid/v2/grid.ts#L16-22`): "it
+   renders exactly STANDALONE (853 slices of 853px = 1px each) but the
+   per-pixel basis does NOT nest — the engine folds the child split into the
+   parent layout, re-divides the basis below 1px, cells round to 0, and the
+   grid is SILENTLY DROPPED at certain canvases". A primitive's acceptance test
+   is composed-inside-a-cell at several canvas sizes, not one full-frame render.
+
+## The extraction process
+
+1. **Identify the core behavior** in non-domain words ("create N-1
+   evenly-spaced line overlays in one direction, optionally excluding edges").
+2. **Define the primitive API** — a tiny prop surface (Rule 2).
+3. **Move the implementation** to `@m0saic/primitives/...`: new template id,
+   defaults that render something clearly, runnable standalone (Rule 3),
+   flags per Rule 4.
+4. **Extract shared utilities into `@m0saic/template-utils`** when multiple
+   templates need them: `buildOverlayStack(count)`, `transparentSlot()`,
+   `buildGridlineSources(opts)`, `lavfiStrip(...)` (paths in the source-of-truth
+   note above).
+5. **Replace the old internal logic** with the primitive, keeping domain
+   decisions local (PlotArea decides baseline ownership; the grid primitive
+   just draws lines) — then **delete the legacy local versions**
+   (`horizontalLineAtFracY`-style shadow implementations must not survive).
+
+For a breaking change later: create `.../v2`; never mutate `v1`.
+
+## Worked example: grid v1 → v2 (the ratio-vs-absolute extraction)
+
+**v1** (`@m0saic/primitives/grid/v1`) was a textbook extraction by Rules 1-6:
+generic props, standalone-runnable, public + `primitive: true`, validated m0.
+It still failed as a primitive: it computed each gridline's ABSOLUTE pixel
+position from `ctx.target` and re-encoded them as a split whose basis ≈ the
+axis length in px (`853[0,1,0,…]`). Composed into a parent, the engine
+re-divides that basis below 1px and the gridlines silently vanish at some
+canvases (1024², 1000²) while surviving at others (1080²). Deprecated
+2026-07-07; kept registered as a "what not to do" reference
+(`primitives/grid/v1/grid.ts:170-175`).
+
+**v2** (`@m0saic/primitives/grid/v2`) repositions each line as a PROPORTION —
+a thin lavfi strip at an overlay offset (`H*frac`) evaluated against the actual
+cell at render time, thickness decoupled as a fixed thin strip. Costs N+1
+nested overlays instead of one `placeRects`, but composes at every canvas —
+for a primitive, composability wins. Full rationale in the v2 header
+(`grid/v2/grid.ts:1-55`). This failure mode is why Rule 7 exists.