@m0saic/knowledge 0.2.0

package/docs/templates/philosophy-and-contract.md

@@ -0,0 +1,310 @@
+# Templates: Contract & Philosophy
+
+Entry doc for `docs/templates/`. Defines what a template IS — the
+executable contract and its invariants. How to BUILD one is
+[`construction-strategy.md`](construction-strategy.md); the required authoring
+process (add / deprecate, tests, registry) is the maintainers' agent contract §10 (not published).
+
+## The template contract
+
+A template is not "a layout string" — a `MosaicTemplate<P>` is a **typed,
+capability-scoped program**: a globally-identified unit (`id`), a typed props
+interface with schema + canonical defaults (`propsSchema`, `defaultProps`), an
+explicit security contract (`capabilities`), and
+`render(props, ctx) -> Promise<MosaicRenderableFile>` where the renderable is a
+`MosaicDocument` or `MosaicDocumentPipeline`. Templates are the main extension
+point for m0saic.
+
+Every template must: return a valid renderable whose emitted m0 strings validate
+(`isValidM0String` / `validateM0String`); stay feasible at intended default
+sizes; be deterministic under `tier: "core"`; declare capabilities honestly
+under `tier: "capability"`. It should document intended resolutions via
+`outputHints.note`, provide safe defaults, and avoid unnecessary complexity for
+human-authored layouts.
+
+> **Source of truth:** authoring entrypoints `defineMosaicTemplate` +
+> `definePropsSchema` in [https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src](https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src);
+> implementations in [https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic](https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic);
+> the full type contract in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts.
+
+## Renderables: spatial vs temporal
+
+**`MosaicDocument` (spatial)** — a pure spatial description of a single render
+pass: `m0` defines layout geometry only (splits, holes, donations,
+overlays); `config` defines sources and render intent; optional `children`
+enables recursive composition (children render first, their outputs become
+sources). The DSL describes *where tiles exist*; the template decides *what
+fills them*.
+
+**`MosaicDocumentPipeline` (temporal)** — composes multiple renderables over
+time: `steps[]` each carry inline `file: MosaicDocument` or a `ref`, explicit
+per-step timing (`durationMs`), explicit transitions (`cut` / `fade`), optional
+pipeline-level fps normalization. A pipeline has no single `m0` string —
+each step has its own spatial layout.
+
+### Document vs pipeline — when to use which
+
+Use a **MosaicDocument** when building layouts, split logic, overlays, spatial media
+composition, or reusable building blocks. Use a **MosaicDocumentPipeline** when
+sequencing scenes, slideshows, transitions, fade/cut stitching — combining documents
+over time. Geometry is the document; time is the pipeline; keep the spatial algebra
+pure. (Full pipeline semantics — `emit: "single" | "multi"`, `intermediate`, per-step
+geometry — live in [`rendering-model-contract.md`](rendering-model-contract.md).)
+
+## Output contract (hints vs reality)
+
+Templates may provide `outputHints` (width / height / fps / durationMs / note /
+format intent). These are UI recommendations, not enforced requirements — with
+one declaration the contract does ask for:
+
+**Every public template declares `outputHints.format`** (the `outputFormat`
+convention, 2026-09-13; record posture — the templates build gate WARNS, never
+fails, and lists it in the Stage 1 line as `warning knob(s): outputFormat`).
+`{ kind: "video", container: "mp4" }` for anything with motion;
+`{ kind: "image", container: "png" }` for a still, plus `pixelFormat: "rgba"`
+when it ships alpha (transparent overlays, QR stamps, wireframes); a template
+with an `outputFormat` knob declares the knob's DEFAULT (the knob still wins
+at render — precedence in
+[`output-resolution-tree.md`](output-resolution-tree.md) §format). Without
+it the CLI names the output `out.mp4` even for a still and a Make share link
+at defaults carries an `f=` ask. Exempt: `internal: true` (building blocks
+render only nested) and `deprecated` (frozen history). Mixed-output templates
+whose kind follows the INPUT (blur-regions, watermark) declare the common
+case; Make derives the real kind from the resolved renderable and the CLI
+switches a defaulted output to png when every input is an image. Audit:
+`auditOutputFormat` (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/template/auditSchemaConventions.ts).
+
+**A canvas that is a knob declares `resolveOutputHints(props)`** (2026-09-15,
+`MosaicTemplate.resolveOutputHints?: (props) => Partial<MosaicTemplateOutputHints>`).
+Pure and cheap — props in, hints out; no ctx, no media, no I/O. Hosts call it
+with the CURRENT props before rendering and seed the target from the result
+merged over the static hints (`resolveTemplateOutputHints` in
+`@m0saic/template-utils`), so the CLI plans at the right canvas, Make's Device
+anchor follows the knob, and the feasibility guard measures the right size.
+Precedence is unchanged: an explicit user ask still wins. `render` reads the
+canvas back from `ctx.target` like every other template and must still lay
+out correctly at ANY target (a host that predates the field ignores it — the
+resolver decides the canvas, it is not the layout). Convention
+`outputHintsResolve` (throw): object, deterministic, and at defaults equal to
+the static hints. First implementer: `@m0saic-dev/creator/drop-calendar/v1`
+(`platform` → canvas + safe area).
+
+Authoritative values always come from `ctx` (resolved by host) — but from the right slot:
+
+- **`ctx.target` — geometry and timing.** Width/height/fps/duration for everything you
+  size or time. It is the per-render slot rect and may differ from `ctx.output` (nested
+  renders override only `ctx.target` — https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/render/renderNestedTemplate.ts#L43).
+- **`ctx.output` — format decisions only.** Container/codec/alpha. **Never geometry** —
+  sizing off `ctx.output.width/height` is the latent 5× bug documented in
+  [`rendering-model-contract.md`](rendering-model-contract.md) Rule 5b.
+
+Templates MUST read timing/resolution from `ctx.target` (the only source of time
+— agent contract §10) and stamp resolved values into returned renderables for
+portability and correct nesting (the wrapper does this — internal render-path
+walkthrough: `.ai/moat/templates/cli-template-lifecycle.md`, step 4). Resolution is
+a host decision: be resolution-aware, not resolution-dependent unless documented.
+
+**An `outputHints.durationMs` is a HINT, never a pin.** The CLI seeds
+`ctx.output.durationMs` from the hint, so comparing it to your default to detect a
+user ask reads a host default as user intent — dsl-tutorial crammed every walk into
+its 12s hint (gate 33, 2026-09-05). Detect a pin with `resolvePinnedDurationMs(ctx)`
+(https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/anim/timing.ts#L156, `userIntent`-only); otherwise
+author the NATURAL length on `doc.durationMs` (template intent out-ranks the hint
+at plan time). On the CLI `.mosaicx` path the wrapper's `durationMs` (or
+`--durationMs`) IS the ask — `mosaicxUserIntent` threads it as
+`userIntent.durationMs` on both `make` and `resolve`
+(the CLI source (not published)); before 2026-09-05 it only set the plan
+length, so a self-timing template was TRIMMED (30s of a 220s walk) while Make
+pinned. Full precedence tree: [`output-resolution-tree.md`](output-resolution-tree.md).
+
+## Capabilities: explicit security contract
+
+Every template must declare `capabilities`. This is not optional metadata — it is
+part of the core execution contract. Two tiers:
+
+### Tier: core (deterministic, safe anywhere)
+
+`{ tier: "core" }` — fully deterministic, safe to run anywhere without
+sandboxing, suitable for public registries and one-click renders. Core templates
+must not depend on: filesystem access, network access, process execution,
+wall-clock time, non-seeded randomness.
+
+#### Core is dynamic — but pure
+
+`{ tier: "core" }` does **not** mean static. A core template may generate different
+m0 strings from props, branch on numeric inputs, inspect **engine-provided** media
+metadata (ffprobe-derived dimensions/duration — explicit inputs, not side effects),
+compute layouts programmatically, and use seeded randomness when the seed derives
+from props. Deterministic branching — e.g. `2(1,1)` for landscape media, `2[1,1]`
+for portrait — is fully allowed. The rule is purity, not staticness: core templates
+are **pure functions of their declared inputs** (`props`, `ctx`, engine metadata) —
+same inputs + same engine version → identical `MosaicDocument`.
+
+### Tier: capability (powerful, explicitly granted)
+
+`{ tier: "capability", caps: { fs?, net?, exec? } }` — may request filesystem
+access (read/list/write/temp), network access (fetch), process execution
+(spawn). The host (CLI / Desktop / Web) may grant, restrict, or deny.
+**Default-deny applies: only explicitly granted capabilities are exposed on the
+engine context.** Capability templates can fetch external data, build caches,
+preprocess assets, and orchestrate multi-step pipelines — intentionally
+powerful; treat them like code (review source, understand the requested caps).
+Full patterns: [`capability-templates.md`](capability-templates.md).
+
+Because templates are typed, validated before render, capability-scoped, and
+deterministic by default, they are the standard mechanism for turning structured
+data (JSON, metrics, event lists) into reproducible media artifacts.
+
+## Props as a UI-renderable schema
+
+Props are defined by `propsSchema` (metadata) + `defaultProps` (canonical
+defaults). Prop metadata exists for UI generation, docs, and high-level
+validation. The design goal: every prop must have a clear generic UI
+representation.
+
+The full `MosaicTemplatePropType` union
+(https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts#L75-105`, verified 2026-07-27):
+
+- primitives: `string`, `number`, `boolean`
+- arrays: `string[]`, `number[]`
+- media: `media`, `media[]`
+- structural: `group`, `list`
+- m0-family (DSL inputs — editor surfaces them as Layout pickers): `m0` (bare
+  layout string), `m0c` (m0 with cell labels; can require label names via
+  `meta.contract`), `m0p` (named bag of layout variants, enumerated or targeted
+  — see `MosaicPropContract`, template.ts:815)
+- `json` — structured payload mapping to a TS interface; renders as a code
+  editor, or a structured form when `meta.constraints.jsonSchema` is declared.
+  The validator accepts any value for `type: "json"` — render-time parsing /
+  validation is the template's job. Prefer this over JSON-string encoding.
+  Details: [`reference/json-prop-type.md`](reference/json-prop-type.md).
+
+Constraints (`MosaicPropConstraints`, template.ts:108-146): numeric bounds
+(`min`/`max`), array bounds (`minItems`/`maxItems`), linked lengths
+(`lengthOf`), literal enums (`oneOf`), `isColor`, and `jsonSchema` for `json`
+props. (An `isM0saicLayout` flag no longer exists — layout inputs are the
+m0-family prop *types* above.) Editor presentation hints live under `meta.ui`
+(`MosaicPropUI`, template.ts:727).
+
+### Defaults are part of the contract — "a knob shows what it does"
+
+Founder ruling 2026-09-05 (gate 33): Make showed dsl-tutorial's `title` EMPTY and
+`showCanvas` OFF while the render used "DSL Tutorial" with the canvas on, because
+those fallbacks lived inside `render()` where no editor can see them. "If they are
+at a default value, the prop showing has to reflect that — enforce it at the
+contract level." An optional knob's UNSET state must be visible:
+
+| optional knob | must carry |
+|---|---|
+| `boolean` | a `defaultProps` value (a toggle cannot show "unset" — it shows OFF) |
+| closed-set `string`/`number` (`constraints.oneOf` / `control.options`) | a `defaultProps` value (a picker shows "—" otherwise) |
+| plain `string`/`number` | a `defaultProps` value OR `meta.control.placeholder` naming the unset behaviour ("auto") |
+| required · `ui.hidden` · `ui.consumer:"human"` · media / json / lists / m0-family / code / a group's own presence | exempt (inputs, not defaults); a `group` is audited field by field against its default object |
+
+Keep `render()` fallbacks as belt-and-braces only; the schema is the truth an
+editor shows.
+
+**Where it fires:** inside `defineMosaicTemplate` — the one seam every registered
+template passes through — at DEFINITION time (module import / `registerTemplate`),
+so the author sees it, not a test they may never run. Code
+(https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/template, verified 2026-09-05; re-verify:
+`grep -n "^export function\|^export class" https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/template/{auditDefaultProps,templateConventions,templateOriginScope}.ts`):
+
+- `auditDefaultProps` / `assertDefaultPropsComplete` — the pure rule
+  (`auditDefaultProps.ts:97` / `:108`).
+- `enforceTemplateConventions` + `TemplateConventionError` (`templateConventions.ts:106`
+  / `:51`) — the seam; findings log `listTemplateConventionFindings` /
+  `drainTemplateConventionFindings` (`:81` / `:86`).
+- **Posture follows the ambient origin scope** (`templateOriginScope.ts:50`, shared by
+  the registry and the wrapper): first-party → **throws**; inside
+  `withExternalTemplateOrigin` (`templateRegistry.ts:274` — an external repo,
+  including one whose module body calls `defineMosaicTemplate` directly at import)
+  → **recorded**, never thrown, so one bad template can't abort a repo load; hosts
+  read the log. `defineMosaicTemplate(t, { conventions: "record" | "throw" })`
+  overrides.
+- **No escape hatch.** The 76 pre-contract templates were migrated the day the
+  contract landed (2026-09-05, 366 knobs: a real default wherever the render had a
+  literal fallback, a placeholder wherever the value is derived from theme / data /
+  mode), so every first-party template passes at import; the registry sweep
+  https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/default-props-audit.test.ts restates the guarantee.
+- **Where a file defines a base and a runner under one id** (`brand/logo/v3`:
+  `logo.ts` + `logo_runner.ts`), the REGISTERED object is the one the seam audits.
+- **A closed set must contain the unset state.** `wireframe/*`'s `preset` picker had
+  no "no preset" option, so unset could not be shown: add the option (`"none"` =
+  mode-driven), default it, and normalise it back to `undefined` at the top of
+  `render()` — never default a real preset over "no preset".
+
+Lock per template: `expect(auditDefaultProps(T)).toEqual([])` plus an
+explicit-equals-implicit render in the gate test. Reference:
+[`reference/template-flags.md`](reference/template-flags.md).
+
+## Identity, nesting, and ownership
+
+Templates may stamp `editor` metadata (UI-only ownership/labeling/provenance)
+and `engine` metadata (diagnostics) on renderables; neither affects rendering.
+Identity inside the DSL is structural (StableKeys); template attachment is
+explicit via config/children — the DSL does not name tiles. Full nested-render
+semantics: [`recursion-nested-rendering.md`](recursion-nested-rendering.md).
+
+## Provenance & trust flair
+
+**Trust comes from the HOST-stamped `provenance` (`builtin` | `community` |
+`external`), never from anything a repo declares about itself** — `repoId`,
+`displayName`, template-id scope, homepage are all self-declared. Always call
+`deriveTemplateSource(templateId, meta)` WITH the meta
+(the Mosaic Desktop / Web app source (not published)); the id-prefix fallback
+exists only for hosts that predate the stamp. (The Templates card called it with
+the id alone until 2026-09-17, and an external repo publishing `@m0saic/…` ids
+wore a VERIFIED ribbon.)
+
+**Three protected namespaces get official flair; everything else is 3P.**
+
+| Namespace | Provenance | Flair |
+|---|---|---|
+| `@m0saic/…` (built-in) | `builtin` | VERIFIED ribbon / badge |
+| `@m0saic-dev/…`, `@m0saic-community` (the community pack) | `community` → kind `curated` | COMMUNITY ribbon, `Community · official` badge (same accent family) |
+| anything else | `external` | 3P ribbon + the third-party banner / note |
+
+Official templates ship inside the app; they are never loaded from a repo. The
+registry enforces the same three prefixes (`RESERVED_TEMPLATE_ID_PREFIXES` in
+https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/template/templateRegistry.ts): an external
+registration under any of them is refused (`TEMPLATE_ID_RESERVED_NAMESPACE`)
+unless the host opened the origin scope with a matching `trustedNamespaces`
+grant (only the pinned community repo).
+
+**Lookalikes get the louder warning.** `assessOfficialLookalike(templateId,
+meta, source)` (the Mosaic Desktop / Web app source (not published)) flags an
+EXTERNAL repo whose id scope is a protected namespace, or whose `repoId` /
+display name / source URL reads as m0saic or the community pack after folding
+case, leetspeak digits and separators (`m0saic`, `mo5aic`, `M-0-S-A-I-C` →
+`mosaic`; tokens: mosaic, community, official, verified, curated, builtin).
+Filesystem paths are never judged (every dev checkout lives under
+`…/m0saic/…`), and neither is `repoHomepage` (the public starter ships
+`github.com/m0saic/template-repo-starter`, and every un-edited fork carries
+it). Surfaces: `3P · NOT m0saic` ribbon (TemplateCard), red badge + "Not an
+m0saic template" note (TemplateInfoModal), red banner (Make), and a per-URL
+callout in the consent gate (`sourceLooksOfficial` — URL only, since no code
+has loaded). The classifier can only ESCALATE a warning; it never grants trust.
+
+An adversarial fixture exercises every layer in one folder:
+the Mosaic Desktop / Web app source (not published) (README has the desktop
+test steps; locked by the Mosaic Desktop / Web app source (not published)).
+
+## Template categories
+
+Practically, templates fall into three families: **structural** (human-authored
+split hierarchies, predictable, maintainable), **engine-native**
+(generated/dictionary-driven — deep overlay chains, large strings, optimized for
+deterministic emission over readability), and **advanced integrations**
+(capability-tier, data-connected). When to use which style — and the live
+category folder list — is [`construction-strategy.md`](construction-strategy.md).
+
+## Status flags: `internal` / `primitive` / `deprecated`
+
+Three orthogonal flags describe whether and how a template surfaces: `primitive`
+(informational badge — a base others build on, still standalone), `internal`
+(visibility gate — **not intended as a top-level pick**, hidden from listings but
+available for nested rendering; it may or may not render standalone — the flag
+doesn't decide that), `deprecated` (visibility gate — superseded, hidden with a
+"use X instead" pointer). Truth table, code pointers, surfaces, and the curation
+rules: [`reference/template-flags.md`](reference/template-flags.md).

package/docs/templates/recursion-nested-rendering.md

@@ -0,0 +1,138 @@
+# Children, recursion, and nested rendering
+
+How `children` work inside a `MosaicDocument`, and how nested documents and
+pipelines evaluate. Source of truth: `renderNestedTemplate`
+([https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/render/renderNestedTemplate.ts](https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/render/renderNestedTemplate.ts));
+document types in [https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src](https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src).
+
+The core rule — **bottom-up evaluation**: for a document D, every child C in
+`children` renders fully first; C's rendered output is then treated as a media
+source; D renders last from those resolved inputs. Each document stays spatially
+pure, children resolve before parent composition, and no circular dependencies
+are possible. Children may themselves contain children — recursion depth is
+unbounded in principle, limited only by practical engine constraints.
+
+## A nested mosaic is also a clip region
+
+Children have a second, less obvious use: **bounding an animated overlay's pixels.**
+
+### The trap
+
+`MosaicMediaSource.overlay.xExpr` / `.yExpr` are **offsets** handed to ffmpeg's
+`overlay` filter. That filter positions the layer — it does **not** clip it to the
+destination rect. So a source placed in a cell, even with `placement.inset` and a
+correct `fit: "contain"`, will happily paint **outside** its cell once `xExpr` /
+`yExpr` push it there. `applyInsetToRect`
+(the render engine source (not published), verified 2026-07-27) insets the
+*destination*; it does not constrain the *payload*. The natural assumption —
+"it's placed in a cell, so it stays in the cell" — is wrong.
+
+Worst offenders:
+
+- **Diagonal sweeps** — a tilted band's horizontal footprint is
+  `sin(angle)·tileSize + 2·halfWidth/cos(angle)`, easy to under-estimate.
+- **Offscreen entry/exit** — the layer is *intentionally* outside the rect at the
+  extremes of the animation.
+- **Procedural offsets** where no static bound is obvious.
+
+### The fix is structural, not arithmetic
+
+Don't tighten the math — **wrap the moving layer in a child mosaic.** Per the
+bottom-up rule, the engine renders each child into an intermediate framebuffer
+sized to its allocated frame, then composites that result. A finite buffer clips
+by construction: pixels the inner overlay tries to paint past the edge have
+nowhere to land.
+
+Parent — swap the moving media source for a `type: "mosaic"` source:
+
+```ts
+sources.push({
+  type: "mosaic",
+  ref: "<child-key>",
+  placement: { fit: "contain", hAlign: "left", vAlign: "top", inset: { /* … */ } },
+  overlay: { blendMode: "screen", enable: enableExpr },  // re-declare the gate here too
+});
+```
+
+Child — a transparent base plus the moving layer:
+
+```ts
+doc.children["<child-key>"] = {
+  kind: "mosaic_document",
+  version: 1,
+  m0: toM0String("F{F}", "ChildName"),
+  assets: { /* the moving layer */ },
+  sources: [
+    { type: "lavfi", color: "black@0" },          // transparent base = the framebuffer
+    { type: "media", mediaType: "image", assetId: id,
+      placement: { fit: "contain" },
+      overlay: { xExpr: sweepXExpr, enable: enableExpr } },   // clipped at the edge
+  ],
+};
+```
+
+`color: "black@0"` is the idiomatic transparent base. Intermediates carry alpha by
+default, so the composite stays clean.
+
+### Cost, and when to skip it
+
+One extra encode pass per nested mosaic — negligible for a small overlay (corner
+badge, shimmer on a 10–20% cell) against the parent's full-canvas encode, but not
+free. Skip the wrap when the offset is bounded by static math **and you have
+verified it** at every value (rare, historically easy to get wrong), or when you
+*want* the bleed (a shadow or glow deliberately falling outside its source).
+
+### Reference — read the history, not just the code
+
+https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/media/qr/stamp-video/v1 wraps its gleam sweep in
+`children["qr_stamp_gleam"]` (`qr-stamp.ts:536`), with a ±0.7w sweep in
+`gleamBand.ts` `buildGleamSweepXExpr` that pushes the band fully offscreen at both
+extremes — **only safe because the child clips.** It shipped with the bleed bug
+first; the wrap was the fix.
+
+> ⚠️ **That template is `deprecated`** (replacement `@m0saic/media/qr/stamp/v1`),
+> and its deprecation note retires the gleam sweep *by design*: "decoration
+> belongs baked into the input media, not computed in the stamp." It stays
+> registered as the reference adaptive video stamp. So this is currently a
+> **pattern with no live consumer** — the engine behavior it exploits is real and
+> unchanged, but if you reach for it, you are the first user in the current
+> shelf. Weigh the "bake it into the input instead" argument before adding an
+> animated overlay at all.
+
+Related: the same child mechanism is the vehicle for complexity pushdown — see
+[`../runtime/reduce-to-one.md`](../runtime/reduce-to-one.md). Clipping and
+pushdown are two applications of one feature.
+
+## Children fill tiles; they never change geometry
+
+    children?: Record<string, MosaicDocument | MosaicDocumentPipeline>
+
+The m0 string defines geometry only — it does not name tiles. Template code maps
+logical tiles to child entries by StableKey: parse the m0, identify target tiles,
+attach children under consistent keys. StableKeys are structural, so they stay
+stable across resolution changes — the mapping is robust.
+
+Children do NOT modify the parent's m0 string, split behavior, overlay logic, or
+StableKey generation. They only fill existing tiles: the DSL is *shape*,
+`children` is *content*.
+
+## Pipelines as children
+
+A child entry may be a `MosaicDocumentPipeline` rather than a document. The
+pipeline renders first; its final stitched output is treated as media that the
+parent consumes. This enables animated sub-tiles, time-sequenced inserts, and
+scene-within-scene structures without polluting the DSL with time.
+
+## Determinism
+
+Nested rendering stays deterministic when all child templates are deterministic,
+no capability introduces nondeterminism, and props + ctx.output are fixed —
+bottom-up evaluation then guarantees reproducibility.
+
+## Flags (`internal: true` etc.)
+
+Template status flags — `internal` (not intended as a top-level pick: hidden
+from public registries, available for nested rendering; standalone renderability
+varies per template), `primitive`, `deprecated` — are owned by
+[`reference/template-flags.md`](reference/template-flags.md). Internal templates are the
+natural children in layered template architectures.

package/docs/templates/reference/grid.md

@@ -0,0 +1,104 @@
+# grid
+
+Canonical dsl-stdlib builder for grid-layout m0 strings.
+
+> **Source of truth:** [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/builders/grid.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/builders/grid.ts) (`GridOptions` / `GridResult` in the same file).
+
+## Default mode: the gutterless simple path
+
+When the call has **no gutter, no `outerGutters`, no `cellWeightBase`, and no
+output dimensions**, the builder short-circuits (`grid.ts:65-82`): compact
+nested equal splits via `equalSplit`, one row expression per row, claimant `1`:
+
+```
+grid({ rows: 3, cols: 2 }).m0   // "3[2(1,1),2(1,1),2(1,1)]"
+grid({ rows: 1, cols: 4 }).m0   // "4(1,1,1,1)"  (rows=1 → just the row expr)
+```
+
+No weight math at all. Result metadata reflects the unit basis:
+`{ cellW: 1, cellH: 1, gutterW: 0, totalX: cols, totalY: rows }`. The per-axis
+basis is just the cell count — minimal quantization risk, nests cleanly.
+**This is the shape the ratio-grid recipe builds on** (gutterless `grid()` +
+gap carved with `latticeCellInset` — see "Uniform grids" in
+[`../construction-strategy.md`](../construction-strategy.md)). Reach for this
+first; the weighted machinery below exists for DSL-baked gutters.
+
+## Weighted mode: gutters and resolution-aware weights
+
+Any of `gutter > 0`, `outerGutters: true`, `cellWeightBase`, `outputWidth`, or
+`outputHeight` routes to the weighted path (`grid.ts:84-154`): cells become
+weight-`cellW` claimants, gaps become blank (`-`) tokens of weight `gutterW`,
+built via `strip` per axis. For the weight system itself (donation, `splitEven`,
+outside-in remainder) see [`../../handbook/dsl-rules.md`](../../handbook/dsl-rules.md);
+for why large weight bases quantize badly (px-per-weight collapse), see
+[`../../handbook/feasibility-precision-quantization.md`](../../handbook/feasibility-precision-quantization.md).
+
+### Cell weight (X) and auto-scaling
+
+Priority (`grid.ts:93-108`): explicit `cellWeightBase` wins; else if
+`outputWidth` is given, auto-scale to keep ≥ `MIN_PX_PER_WEIGHT = 4` px per
+weight unit; else `DEFAULT_CELL_WEIGHT = 50`.
+
+```
+maxTotalX = floor(outputWidth / 4)                       // MIN_PX_PER_WEIGHT
+cellW = max(2, min(50, floor((maxTotalX - gutterSlots) / cols)))
+```
+
+(`gutterSlots` approximates gutterW=1 for the budget; the `max(2, …)` clamp is
+in `grid.ts:99-105`.) Then `gutterW = max(1, round(cellW * gutter))`. Keeping
+px-per-weight ≥ 4 bounds the `splitEven` remainder at ≤ 25% of the base
+allocation. Trade-off: smaller `cellW` coarsens gutter-ratio precision — the
+minimum non-zero gutter is `1/cellW` of cell width (2% at the default 50).
+
+### Equal pixel gaps across axes (`cellH` derivation)
+
+With both output dimensions, `cellH` is derived so one weight unit maps to the
+same pixel count on both axes (`grid.ts:117-130`) — otherwise a `gutterW: 1` gap
+could be 6px across and 3px down:
+
+```
+Goal:  outputWidth / totalX = outputHeight / totalY
+totalX = cols * cellW + gutterCountX * gutterW
+targetTotalY = totalX * outputHeight / outputWidth
+cellH = max(1, round((targetTotalY - gutterCountY * gutterW) / rows))
+```
+
+`gutterW` stays identical on both axes; the cell weights absorb the aspect ratio.
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `rows` | number | required | Grid row count |
+| `cols` | number | required | Grid column count |
+| `gutter` | number | 0 | Gap ratio relative to cellW. gutterW = max(1, round(cellW * gutter)) |
+| `outerGutters` | boolean | false | Add gutter padding on all 4 edges, not just between cells |
+| `cellWeightBase` | number | 50 (or auto) | Explicit X cell weight. Overrides auto-scaling. |
+| `outputWidth` | number | - | Output pixel width. Enables auto-scaling and equal-gap correction. |
+| `outputHeight` | number | - | Output pixel height. Enables equal-gap correction. |
+
+## Result
+
+| Field | Description |
+|-------|-------------|
+| `m0` | The DSL string (field is `m0`, NOT `m0saic` — `GridResult`, https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/src/builders/grid.ts#L22) |
+| `order` | Row-major index array (always `[0, 1, 2, ...]`) |
+| `totalX` | Total X weight count (`cols` on the simple path) |
+| `totalY` | Total Y weight count (`rows` on the simple path) |
+| `cellW` | X-axis cell weight (`1` on the simple path; may be auto-scaled) |
+| `cellH` | Y-axis cell weight (equals cellW when no output dimensions) |
+| `gutterW` | Gutter weight (0 when no gutter) |
+
+> ⚠️ **When to pass `outputWidth`/`outputHeight` (corrected 2026-07-26).** Pass them
+> only when you are keeping DSL-baked gutters at the **head** of a document. For
+> primitives and anything that nests, the current guidance is the opposite: use the
+> **gutterless** simple path and carve gaps afterwards with `latticeCellInset`. A
+> pixel-derived gutter basis re-introduces the coprime-basis blowup
+> (`~30,316 → ~2,211` nodes measured) — see the ratio-grid recipe in
+> [`../construction-strategy.md`](../construction-strategy.md).
+
+## Golden tests
+
+Wireframe PNG goldens live in per-suite dirs under https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-visual-tests/src
+(e.g. `stdlib/grid/__goldens__/`, `stdlib/split/__goldens__/`,
+`stdlib/snapGrid/__goldens__/`, `brand/__goldens__/`). Run: `npm test --prefix https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-visual-tests