@m0saic/knowledge 0.2.0

package/docs/templates/rendering-model-contract.md

@@ -0,0 +1,392 @@
+# Rendering-model contract
+
+**Anchor doc for the 12-rule contract spanning `MosaicDocument`, `MosaicDocumentPipeline`, `MosaicOutputEncode`, `MosaicEngineContext`, the engine planner, and the CLI.**
+
+Verified against (at promotion time, 2026-05-15):
+- https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/document/document.ts (MosaicDocument)
+- https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/document/document-pipeline.ts (MosaicDocumentPipeline, PipelineStepBase)
+- https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/output/encode.ts (MosaicOutputEncode)
+- https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/output/format.ts / `audio-config.ts` / `color-config.ts` / `container-metadata.ts` / `target.ts` (sub-field types)
+- https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/engine-context/engine-context.ts (MosaicEngineContext)
+- https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/document/pipeline-helpers.ts (helpers + predicates)
+- the render engine source (not published) (planner)
+- the render engine source (not published) (output-format precedence chain)
+- the render engine source (not published) (ctx assembly)
+- the render engine source (not published) (multi-encode transcode passes)
+- the render engine source (not published) (workspace + multi-output handling)
+- the CLI source (not published) (capability fixtures gating each rule)
+- the CLI source (not published) (E2E gate)
+- the render engine source (not published) (visual gate)
+
+## Core architectural insights
+
+Two facts drive the whole contract:
+
+1. **A `MosaicDocument` has exactly one `m0` string → exactly one geometry.** Width, height, fps, durationMs, target preset, format, audio, color, metadata, backgroundColor are properties of the *one render* the doc describes. A doc cannot have "multiple outputs at different geometries"; that's a contradiction with one `m0`.
+
+2. **A `MosaicDocumentPipeline` is a sequence of `MosaicDocument`s, each with their own `m0`.** Multi-geometry is therefore a natural property of pipelines (not just of `emit:"multi"`). Different steps can have different canvases; in `emit:"single"` the engine concatenates them onto one pipeline-level canvas (letterbox / element-wise-max default), in `emit:"multi"` each step emits its own file at its own canvas.
+
+The shape of the types reflects this directly: output knobs are flattened onto Document and Pipeline (no map of "named outputs"), and multi-encode is a separate top-level field.
+
+## Shape
+
+```ts
+type MosaicDocument = {
+  kind: "mosaic_document";
+  version: 1;
+  m0: M0String;
+  assets: MosaicAssetManifest;
+  sources: MosaicSource[];
+  children?: Record<string, MosaicRenderable>;
+  meta?: MosaicFileMeta;
+  labels?: ...;                                // out of rendering-model scope
+  variables?: ...; sidecars?: ...;
+  editor?: ...; engine?: ...;
+  created?: string; app?: ...; appVersion?: ...;
+
+  // -- Rendering-model output knobs (one config per doc) --
+  size?: { width: number; height: number };
+  fps?: number;
+  durationMs?: number;
+  target?: MosaicOutputTarget;
+  format?: MosaicOutputFormat;
+  audio?: MosaicAudioConfig;
+  color?: MosaicColorConfig;
+  metadata?: MosaicContainerMetadata;
+  backgroundColor?: MosaicColor;
+
+  // -- Multi-deliverable transcode pass (post-render) --
+  encodes?: Record<string, MosaicOutputEncode>;
+};
+
+type MosaicDocumentPipeline = {
+  kind: "mosaic_pipeline";
+  version: 1;
+  steps: MosaicPipelineStep[];
+  defaultTransition?: MosaicPipelineTransition;
+  meta?: ...; created?: ...; app?: ...; appVersion?: ...;
+  variables?: ...; sidecars?: ...;
+  editor?: ...; engine?: ...;
+
+  // -- Rendering-model output knobs (one config per pipeline) --
+  size?: { width: number; height: number };
+  fps?: number;
+  durationMs?: number;
+  target?: MosaicOutputTarget;
+  format?: MosaicOutputFormat;
+  audio?: MosaicAudioConfig;
+  color?: MosaicColorConfig;
+  metadata?: MosaicContainerMetadata;
+  backgroundColor?: MosaicColor;
+
+  // -- Pipeline-specific --
+  emit?: "single" | "multi";    // single = concat to 1 file; multi = N files
+
+  encodes?: Record<string, MosaicOutputEncode>;
+};
+
+type MosaicOutputEncode = {
+  size?: { width: number; height: number };   // optional ffmpeg `scale` (stretches)
+  format?: MosaicOutputFormat;
+  audio?: MosaicAudioConfig;
+  color?: MosaicColorConfig;
+  metadata?: MosaicContainerMetadata;
+  // NOT settable: fps, durationMs, target, emit (inherited from master)
+};
+```
+
+The `outputs: Record<string, MosaicOutput>` map and the `MosaicOutput` type are **gone**.
+
+---
+
+## Rule 1 — Top-level return types
+
+A template returns exactly one of:
+
+    MosaicDocument | MosaicDocumentPipeline
+
+- `MosaicDocument` → always exactly 1 master render at 1 geometry.
+- `MosaicDocumentPipeline` → a sequence of documents, possibly with different geometries.
+
+Runtime discrimination: `isPipelineFile()` / `isDocumentFile()`.
+
+## Rule 2 — Pipeline emit mode
+
+A pipeline declares `emit?: "single" | "multi"` (default `"single"`).
+
+- `"single"` → render every step, concatenate the output-steps into 1 video. Step geometries reconcile to the pipeline's canvas (explicit `pipeline.size`, or element-wise max of step canvases).
+- `"multi"` → render every step, emit each output-step as its own file at its own step's geometry. **Top-level only**: nested pipelines silently downgrade to `"single"` (`PIPELINE_EMIT_MULTI_DOWNGRADED`).
+
+The relevant fan-out test:
+
+    isMultiOutputCapable = pipeline is top-level
+                           && emit === "multi"
+                           && outputStepCount > 1
+
+## Rule 3 — Step model
+
+Each pipeline step:
+
+- has `durationMs: number` — exact rendered length.
+- may carry `intermediate?: boolean` (default `false`).
+- may carry `name?: string` — friendly-slug used for filename basis under `emit:"multi"` and for CLI per-step addressing. Falls back to `step-{index}`.
+- may carry `label?: string` — template-author hint for `{{label}}` token in the CLI's `--output-pattern` (e.g. the user-supplied input filename when a template fans 1→N variants).
+
+Derived:
+
+    outputSteps = steps.filter(s => !s.intermediate)
+    outputCount = outputSteps.length
+
+At least one step must be non-intermediate (`PIPELINE_NO_OUTPUT_STEPS` otherwise).
+
+## Rule 4 — Pipeline execution
+
+**Top-level pipeline:**
+- Renders all steps (intermediates included — they back ref-sources).
+- `emit:"single"` → concat output-steps; pipeline-level output knobs govern the concat canvas + final format.
+- `emit:"multi"` → each output-step emits its own file at its own step's canvas. Pipeline-level knobs are mostly inert for canvas/fps/duration (steps win); pipeline-level `encodes` apply to **each** emitted file.
+
+Each step renders at its own declared `step.file.size`; the pipeline-level / CLI `-w/-h` target is the default canvas, used only when a step doesn't declare its own (`buildMosaicPlanFromFile.ts` step loop).
+
+**Per-cell tap intermediates (Phase 3c.4).** When a `media`-source cell is the target of one or more `MosaicRefSource`s, the planner emits an additional per-cell `.mov` render (the "tap") via `tapNodeIdFor(stepIndex, flattenedStableKey)`. The tap captures that cell's post-decoration, pre-composite pixel stream; ref consumers (same-doc and cross-step) read from it. Cells that aren't ref targets are unaffected — the tap is opt-in via a pre-pass (`collectRefTargets`) that scans the whole renderable once before plan-build. `text` and `mosaic` ref targets reuse their existing per-cell intermediates; `lavfi` ref targets re-emit the same lavfi expression at the consumer (hash-deduped by graph string).
+
+**Nested pipeline** (appears in a parent's `children`):
+- Must produce exactly one clip for the parent slot's effective duration `T`.
+- Engine sums step durations to meet `T`; trims last step; falls back to embedding source's `MosaicPlaybackProps.loopMode` (`"loop"` / `"freeze"` / `"cut"`) when the pipeline is shorter.
+- Per-step canvases are overridden under nesting; parent slot's canvas wins (`PIPELINE_NESTED_CANVAS_COLLAPSED`).
+- `emit:"multi"` silently downgrades to `"single"`.
+
+## Rule 5 — Output resolution (single render)
+
+Applies to:
+- `MosaicDocument` (always — a doc is always one render).
+- `MosaicDocumentPipeline` with `emit:"single"` or `outputCount === 1` (the pipeline produces one concatenated file).
+
+Each output field resolves via a **3-tier chain** (highest first):
+
+    1. User intent  (CLI flags + .m0v defaults, assembled by the CLI)
+    2. Template intent  (the fields set on doc / pipeline by render())
+    3. Engine default  (target preset → engine hardcoded defaults)
+
+`.m0v` is CLI-consumed default user input — not part of the template/engine contract. Templates never read `.m0v` files. The CLI loads `.m0v` (when supplied) and uses its named output presets as the User tier's default layer; CLI flags override `.m0v` defaults within the same tier; the merged result is the User tier for the document/pipeline.
+
+### Rule 5b — Size off `ctx.target`, never `ctx.output`
+
+**`ctx.target.{width,height}` is THIS template's canvas. `ctx.output` is the top-level
+render envelope.** They are not the same thing once a template is nested.
+
+| | `ctx.target` | `ctx.output` |
+|---|---|---|
+| Means | the canvas *this* template is drawing into | the root render's envelope (codec / container / pixel format + root dims) |
+| Top level | identical to `ctx.output` | identical to `ctx.target` |
+| Nested via `renderNestedTemplate(id, props, ctx, { slot })` | **the slot** (e.g. 640×216) | **still the parent root** (e.g. 1920×1080) |
+
+`renderNestedTemplate` deliberately overrides **only** `ctx.target`
+(https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/render/renderNestedTemplate.ts — `fps` and `durationMs`
+default to the parent's target too). Time already comes from `ctx.target.durationMs` by
+convention; **size must come from `ctx.target` for the same reason.**
+
+**Use `ctx.target` for:**
+- font sizes — `Math.round(ctx.target.height * FRAC)`
+- px → fraction conversions
+- `makeErrorMosaic` / `makeStubMosaic` dimensions
+
+**Use `ctx.output` only for** format / codec / alpha decisions — never geometry.
+
+#### ⚠️ Why this hides
+
+At top level `ctx.target === ctx.output`, so a template that reads `ctx.output` looks
+completely correct — every standalone render, every preview, every golden. The bug
+appears **only** when someone composes it: the child sizes to the parent's canvas and
+blows out of its cell. `stat-card` rendered ~5× too large this way.
+
+That means **a passing test suite is not evidence.** The check is a grep, not a render:
+
+```
+grep -rn "ctx.output.width\|ctx.output.height" https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src
+```
+
+Every hit is either an error-card dimension (should be `ctx.target`) or geometry (must
+be `ctx.target`). As of 2026-07-26 this still returns hits across ~23 template files —
+including `charts/donut/v4`, which is `primitive: true` (i.e. explicitly meant to be
+composed) and sets `const W = ctx.output.width` for its entire layout. Latent today
+because nothing nests it in-repo; a live 5× bug the moment something does.
+
+## Rule 6 — Multi-output (pipelines only)
+
+Multi-output happens only when a top-level pipeline has `emit:"multi"` and more than one output-step. There is no multi-output for individual documents (one m0 = one geometry).
+
+Rules:
+- The template authors a pipeline with N output-steps; each step is its own `MosaicDocument` with its own geometry.
+- The engine emits N files, named by `step.name` (or `step-{index}` fallback): `{base}-{stepName}.{ext}`.
+- Pipeline-level `encodes` apply to each emitted file (each file → N transcoded variants).
+- User intent (`ctx.userIntent.outputs`) is surfaced to templates that want to map presets to specific steps (rule 8).
+
+## Rule 7 — Exact per-output override
+
+Special case for pipeline `emit:"multi"`:
+
+    if (Object.keys(userIntent.outputs).length === outputStepCount)
+
+Then user overrides are applied **positionally** to each output-step (joined by index, not name). This overrides whatever the template authored on each step's MosaicDocument output fields. The CLI also emits an `OUTPUT_NAME_NOT_FOUND` warning per stale key when the user's keys drift from the template's step names — the override still fires (because count matched), but the warning surfaces the drift.
+
+## Rule 8 — Preset semantics
+
+The user can supply (via CLI flags directly, or via `.m0v` defaults the CLI loads):
+- A default output config.
+- Named presets (e.g. `"desktop"`, `"mobile"`, `"alpha-master"`).
+
+Behavior:
+- **Single render (document, or pipeline emit:single)** → presets resolve directly through the 3-tier chain (rule 5). Only one preset's worth of fields is actually applied.
+- **Multi render (pipeline emit:multi)** → presets are input to the template via `ctx.userIntent.outputs`. The template decides how to map preset names onto its own step `name`s. The exact-override path (rule 7) is the only hard-override.
+
+## Rule 9 — Intermediate steps + back-edge refs
+
+Steps with `intermediate: true`:
+- DO render. The engine produces a real video file in `workspaceDir`.
+- The workspace file is deleted at the end of the render job — not delivered to the user.
+- ARE available to later steps via `MosaicRefSource` (back-edge invariant; see below).
+- Do NOT count toward `outputCount`.
+- Are NOT concatenated under `emit:"single"`.
+- Are NOT exposed as per-file under `emit:"multi"`.
+- Their `transitionToNext` is ignored.
+
+**`MosaicRefSource` scope (post-3c.4).** Refs are back-edge mirrors of another cell's pixels. They work in both directions intermediate steps unlock — but the surface is broader than pipelines:
+
+- **Locality**: same-document (`stepIndex` omitted) AND cross-step (`stepIndex` set; must be strictly earlier).
+- **Targets**: any cell that produces pixels — `media`, `text`, `mosaic`, top-level same-doc `lavfi`, and overlay frames (`r/.../ovNcN`). Inner cells of nested mosaics resolve at any depth via `flattenedStableKey` (e.g. `r/gcolc0/fc1`, `r/growc0/fc0`).
+- **Not targets**: `data` sources (structurally hidden from layout), other ref sources (chains — editor flattens them; engine rejects with `MOSAIC_REF_TARGET_NOT_SUPPORTED`), cross-step lavfi (deferred — same code emits `MOSAIC_REF_TARGET_NOT_SUPPORTED` and falls back to placeholder).
+- **Matrix normalization**: when the ref's slot dims / fps / duration / pixfmt differ from the target's, the consumer's own filter chain inserts `scale=` / `fps=` / `setpts=` / `format=` to bridge. Ref's own `placement` / `playback` / `effects` / `mask` then apply on top.
+
+Use case: a "header strip" rendered once into workspace, referenced from multiple downstream steps for pixel reuse. Or: a hero clip rendered in step 0 echoed at a different size in step 3 with audio sync preserved. Or: a same-doc overlay frame reused as the visual content of another cell.
+
+### Note — `MosaicRefSource` lavfi-target gap (v1)
+
+Lavfi ref targets have a narrower v1 surface than the other source kinds: they resolve only when the target cell is at the root of the same doc (`descendPath.length === 0`). Refs to lavfi cells at deeper nesting silently fall back to black placeholders with a `MOSAIC_REF_TARGET_NOT_SUPPORTED` warning — only surfaced in `--validate-only` or `--report` output. Media / mosaic / text-with-image-render-mode targets all walk nested depth fine (see the `ref-same-doc-multi-level-inner-cell` and `ref-cross-step-nested-inner-cell` fixtures).
+
+For "one solid colour reused across many cells", prefer N independent `MosaicLavfiSource` entries — ffmpeg's `color=` generator is essentially free, so the ref optimization has no payoff there. Reserve refs for targets with a real intermediate to share (media files, text-as-image PNGs, nested mosaics).
+
+If a use case for nested-lavfi refs surfaces (e.g. mirroring a complex procedural gradient across deep cells), the gate at the render engine source (not published) is where the resolver is deferred. Verify with: `grep -nE "descendPath\.length > 0" the render engine source (not published).
+
+### Solid-colour tile sources — use `makeColorTile`
+
+Full section (API forms, why lavfi `color=` beats an empty text source, adoption list) moved to
+[`construction-strategy.md`](construction-strategy.md) § "Solid-colour tile sources — use `makeColorTile`". Source: https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/sources/makeColorTile.ts#L52.
+
+## Rule 10 — Single vs multi render
+
+| Mode    | Source                                                           | User authority |
+|---------|------------------------------------------------------------------|----------------|
+| Single  | `MosaicDocument`, or pipeline with `emit:"single"` / 1 output    | Full (rule 5)  |
+| Multi   | Pipeline with top-level `emit:"multi"` and `outputCount > 1`     | Template-driven (rule 6); user only via rule 7 |
+
+## Rule 11 — Multi-encode (separate axis)
+
+`encodes?: Record<string, MosaicOutputEncode>` on `MosaicDocument` and `MosaicDocumentPipeline` declares N transcoded variants of the master render(s).
+
+    1 render → 1 master + N encodes
+
+Engine implementation: master renders into a workspace `{base}.__master.{ext}` (never the user-facing path, so encodes can stream-copy/transcode from it), then post-process ffmpeg passes `ffmpeg -i master.<ext> ...` produce each encode entry. `runPlanInWorkspace` skips its "final command" sweep when `multiOutput: true`, so every command writes to its own `outputPath` hint instead of getting rerouted to the user-facing path.
+
+### What an encode CAN change
+- Codec, container, pixel format, encoder tuning (the primary axis).
+- Width/height (optional `scale` filter pass — **stretches** content; no aspect-aware padding or re-layout).
+- Audio, color tagging, container metadata.
+
+### What an encode CANNOT change
+- `fps`, `durationMs` (inherited from master).
+- The render's `target` preset or `emit` mode.
+
+### Pipeline + encodes
+- `emit:"single"` → `encodes` apply to the one concat output (one master, N encodes).
+- `emit:"multi"` → `encodes` apply to **each** emitted file (each of N step outputs gets N encodes — `outputCount × encodeCount` files total).
+
+### Container/codec compatibility defaults
+- WebM rejects AAC; when no audio override is supplied and the encode targets WebM, `buildEncodeCommand` defaults to `-c:a libopus` (master AAC can't be stream-copied into WebM).
+- `matroska` / `quicktime` / `mpegts` are ffmpeg muxer names; `containerToExt` aliases them to `.mkv` / `.mov` / `.ts` so the writer emits valid file extensions.
+
+## Rule 12 — Template / engine / CLI responsibilities
+
+**Templates:**
+- Author one `MosaicDocument` or one `MosaicDocumentPipeline` per `render()` call.
+- Set output knobs (`size`, `fps`, etc.) on the doc/pipeline as **template intent** (tier 2 of rule 5).
+- For multi-output (pipeline emit:multi) authors: read `ctx.userIntent.outputs` and map preset names onto step `name`s.
+- Never read `.m0v` files directly.
+
+**Engine:**
+- Resolves output knobs per rule 5 (User > Template > Engine default).
+- Branches on `emit` at top level: concat for single, fan-out for multi.
+- Filters `intermediate` steps from output count / concat / per-file emission.
+- Honors the exact-override path (rule 7) when triggered.
+- Issues post-render transcode passes per `encodes` (rule 11).
+- Concat path always emits audio (silent AAC track when sources are image-only) so downstream encodes carry an audio stream regardless of source mediaType.
+
+**CLI:**
+- Loads `.m0v` (when supplied) as default user input.
+- Merges CLI flags on top (CLI flags > `.m0v` defaults within the User tier).
+- Assembles `ctx.userIntent` and bakes user values into the doc/pipeline before plan-build.
+
+---
+
+## Per-rule wiring status (2026-05-15, end of Phase 5)
+
+| # | Rule                       | Typed? | Wired? | Tested? | Notes                                                              |
+|---|----------------------------|--------|--------|---------|--------------------------------------------------------------------|
+| 1 | Top-level return types     | ✓      | ✓      | ✓       | Document/Pipeline dispatch wired in `buildMosaicPlanFromFile.ts`. |
+| 2 | Pipeline emit single/multi | ✓      | ✓      | ✓       | `multi-output-minimal` fixture; `test-templates.e2e.test.js`.    |
+| 3 | Step model (durationMs, intermediate, name, label) | ✓ | ✓ | ✓ | label honored in `--output-pattern`'s `{{label}}` token.        |
+| 4 | Pipeline execution         | ✓      | ✓      | ✓       | Per-step `size` honored; nested-downgrade emits diagnostic.      |
+| 5 | Output resolution (single) | ✓      | ✓      | ✓       | 3-tier chain in `resolveOutputFormat.ts`.                        |
+| 6 | Multi-output (pipeline emit:multi) | ✓ | ✓      | ✓       | Fan-out + workspace→user-facing copy in CLI.                     |
+| 7 | Exact per-output override  | ✓      | ✓      | ✓       | Length-match triggers positional merge; warns on key drift.      |
+| 8 | Preset semantics           | ✓      | ✓      | ✓       | CLI `--m0v` + flag merge; `ctx.userIntent.outputs` surfaced.     |
+| 9 | Intermediate steps         | ✓      | ✓      | ✓       | Filter in step loop; verified absent from user-facing output.    |
+| 10 | Single vs multi distinction | ✓     | ✓      | ✓       | Follows from rules 6+7.                                          |
+| 11 | Multi-encode (separate axis) | ✓   | ✓      | ✓       | Transcode chain + matroska alias + WebM audio default.           |
+| 12 | Template / engine / CLI responsibilities | ✓ | ✓ | ✓ | `ctx.userIntent` wired through `createEngineContext`.            |
+
+Legend: ✓ fully present · partial present-but-incomplete · ✗ absent.
+
+---
+
+## Test coverage by rule
+
+> ⚠️ **Fixture set has roughly quadrupled since this table was written (2026-05-15).**
+> As of 2026-07-26 the always-on gate renders **49 fixtures**, including **20 `ref-*`**
+> (cross-step / same-doc mirror coverage for Rule 9), **15 `effects/*`**, the data-
+> pipeline fixtures (`fixture-pipeline-via-mosaicx`, `github-pulse-replay`), and 4 audio
+> fixtures with `minMeanVolumeDb` floors. The rows below name the original anchor
+> fixtures only — the `FIXTURES` array in
+> the CLI source (not published) is the live inventory.
+
+| Rule | Gate type | Where |
+|---|---|---|
+| 1 | unit | the render engine source (not published) |
+| 2/3/4/9/10 | E2E + visual | the CLI source (not published) (multi-output-minimal); the render engine source (not published) |
+| 5 | unit | the render engine source (not published) |
+| 6 | E2E | the CLI source (not published) (multi-output-minimal) |
+| 7 | unit + E2E | the render engine source (not published) exact-override branch; the CLI source (not published) --m0v plumbing |
+| 8 | unit | the CLI source (not published); CLI `cli.flags.test.js` |
+| 11 | E2E | the CLI source (not published) (doc-with-encodes, pipeline-single-encodes, pipeline-multi-encodes, codec-matrix-video, codec-matrix-audio) |
+| 12 | structural | See the render-path walkthrough (internal: `.ai/moat/templates/cli-template-lifecycle.md`) |
+
+---
+
+## Migration notes (what disappeared)
+
+This contract represents a flatten refactor from a previous design:
+
+- **`MosaicOutput` type — DELETED.** Its fields are flat on `MosaicDocument` and `MosaicDocumentPipeline` now.
+- **`outputs: Record<string, MosaicOutput>` map — DELETED.** Documents have one output config; multi-geometry deliverables go through pipelines.
+- **`outputsRef?: string` — DELETED.** Templates don't reference `.m0v` files; the CLI loads `.m0v` as default user input.
+- **`labelsRef?: string` — DELETED.** Same principle as `outputsRef`. The canonical path for `.m0c` / `.m0p` content into a doc is via the template `m0c` / `m0p` prop type — the CLI/host loads the file, supplies it as a prop value, and the template extracts the labels into `doc.labels`. See `MosaicTemplatePropType` in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts.
+- **`encodes?: ...` — MOVED to top-level** on Document and Pipeline (was nested inside MosaicOutput).
+- **`emit?: ...` — MOVED to top-level** on Pipeline (was on MosaicOutput).
+- **`ctx.userIntent.requestedOutputs` — REMOVED.** Subsumed by `ctx.userIntent.outputs` (the engine reads `Object.keys(outputs)` for the count signal in rule 7).
+
+## Forward references
+
+- `MosaicPipelineStep / PipelineStepBase` JSDoc — full `intermediate` / `label` semantics.
+- `MosaicOutputEncode` JSDoc — full multi-encode contract.
+- Concrete render walkthrough for templates consulting `ctx.userIntent` — engine-internal: `.ai/moat/templates/cli-template-lifecycle.md` (absent in the shipped copy).
+- Data-fetcher / adapter / handle patterns — rely on intermediate steps and data-only docs in pipelines. Promoted: [`data-pipeline.md`](data-pipeline.md) (sibling doc in this folder).

package/docs/templates/standalone-pack-authoring.md

@@ -0,0 +1,233 @@
+# Standalone data-viz pack authoring — the sandbox playbook
+
+A *pack* (`@<publisher>/<pack>/<slug>/vN`) is a cohesive set of **standalone**
+templates sharing one brand look. Do **not** compose the generic `@m0saic/charts/*`
+primitives — **reuse their pure geometry MATH** and build your own chrome on a small
+shared kit. Canonical reference: `@m0saic/alpine/*` (bar-graph · commit-feed ·
+contributor-table · donut · heatmap · kpi-card · leaderboard · line-chart ·
+progress-card · stat-card · timeline · treemap), a **12-template** pack (as of
+2026-07-27 — `ls` the folder) built end-to-end via the sandbox protocol. Pairs with
+https://github.com/m0saic-project/m0saic-sandbox/blob/main/packages/sandbox/agent.md and this folder's `construction-strategy.md` + `reference/`.
+
+## 0. Constraints first — the authoring loop (founder direction, 2026-09-05)
+
+"Template design should move towards: you start by defining your constraints and
+general direction, then build layout and check against various canvases and prop
+combinations in a loop. The layout contract allows you to drive towards a
+solution. And the build-time check throws before you even have a chance to open
+Mosaic Desktop or invoke the CLI."
+
+1. **Declare the contract before the layout.** Write the props schema with its
+   defaults (every optional boolean / closed-set knob has a `defaultProps` value,
+   every plain string/number a default or a placeholder — §3 "Defaults are the
+   contract"), tag the pieces that carry design intent, and declare their
+   `LayoutConstraint`s + `textFits` under `debugLayout` — canvas-independent
+   ratios, not pixels. State the general direction (the aspect it is designed for,
+   how it degrades) in the description.
+2. **Build the layout against those constraints.** Real geometry first
+   ([`construction-strategy.md`](construction-strategy.md)); fit text under the
+   same ruler the contract checks with ([`layout-contract.md`](layout-contract.md)
+   §"Text").
+3. **Loop: check, don't eyeball.** `assertLayout` at the 7-canvas set
+   (1920×1080 · 1280×720 · 1080×1920 · 1080×1080 · 3840×2160 · 640×360 · 480×270)
+   × the prop combinations that change geometry (long titles, max items, every
+   closed-set value) in the gate test; `auditDefaultProps(T)` empty. A violation is
+   a design decision to make (shrink, compact wording, drop), not noise — the
+   contract drives toward the solution. Exemplar:
+   https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/dsl-tutorial/v1/dsl-tutorial.gate33.test.ts.
+4. **The build is the first gate.** `npm run build` in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates (and
+   in the community pack and both starter repos) ends by loading the built
+   registry first-party (`tools/check-registry.mjs`): a template that hides a
+   default throws — naming the knobs and the fix — and the build fails before the
+   template can load in Mosaic Desktop or the CLI. Only then does the sandbox loop
+   (candidate → human verdict, §4) begin.
+
+The layout contract stays debug-only at render time (2026-08-22 ruling — a render
+with slightly clipped text beats no render); the gate test and the build step are
+where it bites during authoring.
+
+## 1. Stand up the seam first (once per pack)
+
+Three `_shared/` files (verified 2026-07-27 in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/alpine/_shared):
+
+- `<pack>-theme.ts` — tokens (surface/card/border, title/subtitle/label/muted,
+  primary/positive/negative, grid/axis), a categorical `PALETTE`,
+  `PRESETS{light,dark}`, a `theme(preset)` resolver. **Dark is not an afterthought:**
+  every color, wash, and contrast must be retuned for it (leaderboard `MEDALS_DARK`,
+  heatmap `EMPTY_DARK`) — a wash tuned for white glares or vanishes on navy.
+- `<pack>-card.ts` — the Node combinator kit lifted from `charts/bar-graph/v2` (the
+  canonical tight-rect template): `paint` / `EMPTY` / `rowSplit` / `colSplit` /
+  `overlay` / `insetNode` / `textCell`, plus `resolveColor`, and a
+  `card({theme, W, H, title, subtitle})` returning `{contentRect, compose(content,
+  ...extraLayers), backgroundColor}`. Every template wraps its body in this card.
+- `<pack>-anim.ts` — shared reveal choreography + prop-schema field factories:
+  `revealGate` / `revealSlide` / `revealFade` (source and Node flavors), the `fBool`
+  / `fStr` / `fNum` / `fFrac` / `fEnum` schema-field helpers, and the shared
+  `ALPINE_ANIM_FIELDS` block every template spreads into its props schema.
+
+A `Node` is `{ m0: string; sources: MosaicSource[] }` built together so source
+emission order always matches the DSL's DFS order.
+
+**And the front door (the hello-world convention, 2026-09-14).** Every template
+repo names the template a newcomer renders first: `repo.helloWorld` on the repo
+descriptor (`src/repo.ts` in the starters). The default is the canonical m0saic
+card, one call from `@m0saic/template-utils`:
+
+```ts
+const card = defineHelloWorldTemplate({ id: "@acme/basics/hello-world/v1", subline: `by ${TEMPLATE_REPO.displayName}` });
+```
+
+The field, the M, the wordmark and the greeting stay the brand ("made with
+m0saic"); `subline` is the repo's own line, seeded into the `caption` prop. A pack
+that wants its own look writes its own template and points `repo.helloWorld` at
+it. The gate warns (`repoFrontDoor`, record posture — never fatal) when a repo
+names no front door or names an id it does not register. `m0saic hello-world
+--template-repo .` renders it; the manifest carries the field zero-exec.
+
+Two authoring facts, both learned on the starters:
+
+- Spell the structural fields out in the repo module — a literal with
+  `version`, `propsSchema: { ...HELLO_WORLD_PROPS_SCHEMA }`, `defaultProps`, and a
+  `render` that delegates to the factory — because the no-install contract check
+  loads the entry with every `@m0saic/*` import stubbed to an identity proxy, under
+  which a bare factory call reads as an options bag. Copy either starter's
+  `src/basics/hello-world/v1/hello-world.ts`.
+- A still of the card at t=0 is a bare navy canvas (the field wipes in, the M
+  assembles). Gallery stills are cut from the clip near its end — the starters'
+  `gen-previews.mjs` carries a per-id `STILL_AT_SEC` (hello-world → 2.45 s). The
+  card also WIDENS for a long line (to 92% of the canvas) before type shrinks or
+  truncates; the default card never widens, so the shipped fingerprint holds.
+
+## 2. Two construction modes — pick per template
+
+- **Splits** (leaderboard, bar, progress) — real m0 cells via `weightedSplit`. Best
+  for row/column layouts. Snap nested weights to a multiple of 8 so they GCD-collapse
+  and stay quantization-feasible at any resolution. (Large splits with coprime pixel
+  weights deterministically spread the fractional remainder — that's precision, not
+  a bug; canonical: `handbook/feasibility-precision-quantization.md`.)
+- **placeRects absolute** (donut, line, heatmap, timeline, treemap) — every cell is a
+  tight rect on the **SNAP_PX (4px) lattice**, packed full-canvas via `placeRects`.
+  Use for grids, rings, scatter, calendars, treemaps, spines — anything not a clean
+  split. **THE recurring bug (bit on heatmap, timeline, treemap):** pass the
+  placeRects body as a **full-canvas extraLayer** — `card.compose(EMPTY, body)` —
+  **never as the scaled `content`.** Scaled content goes through `insetNode`, which
+  re-quantizes the split weights into a smaller rect → uneven cells /
+  `SPLIT_EXCEEDS_AXIS` (0-size band). Also snap **pitch, gap, and all offsets** to
+  the lattice so every cell edge and gap-band boundary is grid-aligned.
+
+## 3. The knobs every template gets right
+
+- **Defaults are the contract ("a knob shows what it does", 2026-09-05).** Every
+  optional `boolean` and closed-set knob (`constraints.oneOf` / `control.options`)
+  carries a `defaultProps` value; every plain `string` / `number` a default OR a
+  `meta.control.placeholder` naming the unset behaviour ("auto"). A fallback that
+  lives only in `render()` (`props.title ?? "…"`, `props.show !== false`) makes the
+  Make panel LIE (empty / OFF for a value the render fills in). `defineMosaicTemplate`
+  throws `TemplateConventionError` for a first-party violation at import; an external
+  pack's is recorded, never fatal. A closed-set knob whose unset state is not one
+  of its options gets a `"none"` option (defaulted, normalised away in `render()`).
+  Rule + exemptions: [`philosophy-and-contract.md`](philosophy-and-contract.md)
+  §"Props as a UI-renderable schema".
+- **`resolveColor(value, fallback)` on EVERY color knob.** A bare `props.color ??
+  fallback` keeps `""` (not nullish) → renders the mark in no color → invisible. A
+  cleared / "none" / blank picker must fall back.
+- **Dual props.** Agent-canonical knobs (`anim`, `valueMode`, `orientation`, …) plus
+  human-facing toggles/sliders (`animate`, `showValue`, `introLength`, `cornerRadius`)
+  wired via `meta.control.syncsTo` (e.g. `animate` → `anim.reduceMotion` boolInvert).
+  Anything a human flips or drags belongs in `consumer:"human"` — they WILL ask.
+- **Labels.** Compact big numbers (`compactNum`: `4500→4.5K`); size the font
+  length-aware or shrink-to-fit; ellipsis-truncate only when even the min font
+  overflows, bounding truncation width so labels can't collide. Do **not** use
+  `fit:"contain"` for a single line — it scales to HEIGHT and clips width. Fit
+  under `textEmUnits × fontSize × em` with a `cell × 0.94 − 2px` budget and lock it
+  with `textFits` — [`layout-contract.md`](layout-contract.md) §"Text".
+- **Contrast auto-flip.** `onColor(hex, light, dark)` via relative luminance for any
+  text sitting on a colored fill (white on saturated, dark on pale/amber).
+- **Animation.** Opacity rides `overlay.alpha` — `makeColorTile` IGNORES `visual`.
+  `fadeInExpr(start, dur)` cascades; `animateNumbersInText` for count-up;
+  `reduceMotion` → the static board. **Overlay-depth limit (~25 nested layers):** the
+  engine silently drops masks (circle markers → squares, text → tofu); use a single
+  curtain-wipe overlay, not a per-sliver cascade.
+- **Aspect-awareness.** Stress vertical / square / horizontal. A wide card may need a
+  different layout (timeline's `orientation:"auto"`); clamp edge content so it can't
+  spill the card.
+- **A canvas that is a knob → `resolveOutputHints(props)`.** When a prop picks the
+  output size (a `platform` knob: YouTube 1920×1080 vs TikTok 1080×1920), declare
+  the resolver on the template so hosts SEED the right target before rendering
+  (`resolveTemplateOutputHints` is the one helper CLI / Electron / web / Make use);
+  `render` still reads `ctx.target` and lays out at any size. At `defaultProps` it
+  must agree with the static `outputHints` (`outputHintsResolve`, throw). Rules:
+  [`philosophy-and-contract.md`](philosophy-and-contract.md) §"Output contract".
+- **Prop bindings — the rect that SHOWS a prop is its handle in Make.**
+  `bindProp(src, key)` / `bindProps(src, entries)` / `bindPropPath(src, key, path,
+  kind)` / `bindPropRange(...)` (`@m0saic/template-utils`) stamp `editor.binding` on
+  the source that displays a prop; Make resolves them per render (`bindingsSound`
+  throws on a binding the schema refuses — booleans, closed pickers and whole lists
+  are never bindable) and the preview shows one glyph per thing the tile can do (T
+  text · 123 number · swatch colour · move rect · picture media), collapsing to ONE
+  dot on a small tile. Bind even when the value is empty (the rect is a handle to
+  ADD). The full contract — kinds, `onClear`, `seedDraft`, `kind: "media"` (a rect
+  that takes a dropped file), `companion`, starter media — is
+  [`reference/prop-bindings.md`](reference/prop-bindings.md).
+  **`kind: "rect"` (2026-09-15) — a rendered cell edited IN PLACE:** a `json` prop
+  with `picker: "regions"` and `regions.max: 1`, bound with `bindPropRect(src, key)`
+  (no path). Double-click / the move badge opens the regions draw session seeded
+  from the cell's painted rect; drag, 8 handles, Shift = aspect lock, Delete = back
+  to automatic placement, Esc / Enter = done; every gesture end writes `{ canvas,
+  regions: [rect] }` into the prop and the template re-renders — never a
+  destructive post-render edit. The template must still render a correct default
+  placement when the prop is empty: the binding is the handle, not the layout. A
+  cell may carry several bindings (`bindProps` with a rect entry AND text entries) —
+  that is the "move the cell OR change its contents" surface. First implementer:
+  `@m0saic-dev/creator/drop-calendar/v1` (`facecamRegion`).
+
+## 4. The sandbox loop
+
+The full iteration ritual is https://github.com/m0saic-project/m0saic-sandbox/blob/main/packages/sandbox/agent.md — read it before authoring
+or iterating on any candidate; this doc does not duplicate it. Naming convention in
+one line: `candidate-NNN.mosaicx` (one file = one question = one verdict), a frozen
+`candidate-NNN-agent.mosaicx` snapshot before every open, and
+`candidate-NNN_humanedits.mosaic` frozen from the live dist BEFORE editing the
+template on negative feedback.
+
+## 5. The lock is the full closeout — non-negotiable
+
+Canonical: https://github.com/m0saic-project/m0saic-sandbox/blob/main/packages/sandbox/agent.md §"Session closeout" + §"Template-build
+closeout (the `.mosaicx` flavor)". This doc intentionally does not summarize the
+artifact list — read agent.md and follow it. Two rules earlier summaries
+dangerously omitted:
+
+1. **The master is `master_candidate-NN.mosaicx` until approval.** "Do NOT mint a
+   bare `master.mosaicx` before approval — that name is reserved for the approved
+   file." Rejected gates stay frozen; the fix ships as `master_candidate-02`, etc.;
+   only on approval is the file renamed to `master.mosaicx` + `master.mosaic`.
+2. **"Gate EVERY output aspect, not just one."** Aspect-adaptive templates pass
+   desktop and still fail square/mobile — the final gate is the human rendering ALL
+   aspects (H / V / square) from the candidate and signing off. Verify the aspects
+   yourself first, but the gate is theirs.
+3. **The layout contract comes BEFORE candidate-01.** Tag every fitted text source,
+   declare `textFits` under `debugLayout`, and sweep `assertLayout` at the 7-canvas
+   set in the gate test — [`layout-contract.md`](layout-contract.md)
+   §"Recommended". A gate that passed one aspect and clipped on portrait is the
+   scenario this rule was written for (gate 33).
+
+## 6. Cross-cutting gotchas (bit on multiple templates)
+
+- `cornerRadius` is a **0..0.5 fraction of the cell's shorter side** → px radius
+  (`borderRadius * min(w, h)`). At high radius, inset top-left labels must clear
+  the corner curve.
+- **Make `--make` open adopts the file's `size`** over the template's `outputHints`
+  (a 1080² candidate must open square, not 1280×800). Beware: Make's save-back
+  rewrites the file's size/props to the panel state — re-freeze candidates that drift.
+- **The render-hero preview rounds a cell by driving `border-radius !important`** on
+  the matched ViewFrame cell (`Frame.tsx` wires `var(--vf-tile-radius, 0px)`, so a
+  plain assign is overridden). Measure the radius via `ResizeObserver` — cells can be
+  0×0 on the first effect pass.
+- **The 119/121 fencepost.** `weights.map(w => round(w / sum * 120))` sums to
+  120 ± (bands − 1): every Alpine card carried `121×2`, the pulse heroes `121×8`,
+  and 121 = 11² poisons every composition (LCM with the core = 14,520). The kit
+  line is `weightedSplit(latticeWeights(weights, { cap: 120 }), axis, { claimants })`
+  (Hamilton to an exact 5-smooth total, GCD to a divisor: `[59,1802,59] → [1,28,1]`).
+  Since 2026-09-16 the build gate and `m0saic doctor` refuse a rough count above 12
+  (`latticeSmooth`, throw — [`reference/template-flags.md`](reference/template-flags.md))
+  — for a pack it is the publish requirement, so run the doctor before tagging.