m0saic 0.2.2 → 0.3.1

package/node_modules/@m0saic/knowledge/docs/templates/reference/prop-bindings.md

@@ -0,0 +1,338 @@
+# Prop bindings — the rect that SHOWS a prop is its handle in Make
+
+A template marks the source that DISPLAYS a prop with `source.editor.binding`
+(or `bindings`, several leaves on one rect). Make resolves them per render and
+turns the rect into the prop's canvas handle: double-click / a badge to edit,
+a file dropped on it to fill a media slot. Bindings are re-resolved on every
+render and keyed by the PROP — never by a stableKey, which changes whenever the
+geometry does.
+
+One predicate decides what is bindable: `classifyBindableProp` in
+`@m0saic/platform` (`mosaic/propBindings`). Template tests
+(`resolvePropBindings` in `@m0saic/template-utils`) and the Make page both use
+it, so a template can never offer an edit the page refuses, or vice versa.
+`bindProps` / `bindPropPath` THROW at author time for what the platform would
+silently drop — a template test should never reach the silent path.
+
+## The wire shape
+
+```ts
+binding: {
+  propKey: string;                 // dotted path as propsSchema nests it: "label", "titles.title"
+  index?: number;                  // ONE element of string[] / number[] / media[]
+  path?: Array<string | number>;   // route into a json / list / array value: [2, "title"]
+  kind?: "string" | "number" | "color" | "rect" | "media";  // required on structured leaves
+  layer?: number;                  // which text layer shows the leaf (multi-layer text)
+  onClear?: "remove-element" | "unset-leaf";
+  seedDraft?: string;
+  companion?: boolean;
+  range?: { start: number; end: number };   // one line of a multi-line string leaf
+  focus?: { start: number; end: number };   // the token the rect shows, inside range
+}
+```
+
+Rules:
+
+- `propKey` is exactly as `propsSchema` nests it; every segment past the
+  first walks a `type: "group"` prop's `fields`.
+- Basic lists (`string[]`, `number[]`, `media[]`) bind ONE element — a
+  non-negative integer `index`. The list itself is never bindable.
+- Structured props (`json` / `list` / `array`) bind a LEAF: `path` from the
+  prop's value plus an explicit `kind` (the schema has no per-leaf type, and an
+  empty leaf must still be an "add" handle). `index` is shorthand for a leading
+  numeric segment.
+- `meta.ui.hidden` props, booleans, connection-driven option strings
+  (`optionsFromConnection` — the host has no list without the connection) and
+  whole lists are never bindable. A stray `index` on a scalar is ignored.
+- A **closed set** — `constraints.oneOf` or a static `control.options` list — binds
+  as kind **`choice`** (2026-10-01): Make shows the set (a segmented row up to four
+  choices, a select beyond) on the inline editor and on the tile card, and one click
+  writes the value; nothing is typed, `seedDraft` is dropped. Basic props only — a
+  structured leaf has no set to offer, so `kind: "choice"` there is refused. The case it exists for:
+  a full-canvas card bound to its theme `preset` (the alpine cards, the GitHub year
+  card) — the click on the card is where the theme gets changed, and the `canvasFill`
+  rule accepts a full-canvas rect that carries such a handle.
+- Bind even when the value is empty — the rect is then a handle to ADD.
+
+## Kinds
+
+| prop / leaf | binding | kind | Make handle |
+|---|---|---|---|
+| free-text `string` (or one `string[]` element, or a structured leaf) | `bindProp(src, key[, i])` / `bindPropPath(src, key, path, "string")` | `"string"` | T — the inline text form |
+| colour-valued string (`isColor` / `colorPicker`) | same | `"color"` | swatch — a picker |
+| `number` (or one `number[]` element, or a leaf) | same, `"number"` | `"number"` | 123 — the inline form |
+| `json` with `picker: "regions"`, `regions.max: 1` | `bindPropRect(src, key)` — no path | `"rect"` | move glyph — the regions draw session on the cell |
+| `media`, one `media[]` element, or a leaf holding a path | `bindProp(src, key[, i])` / `bindPropPath(…, "media")` | `"media"` | picture glyph — a DROP target + the media chip |
+
+Order the entries the way a double-click should read them: `fields[0]` is the
+primary action (a plain double-click); the badge row offers every kind.
+
+## The roll call — `bindingsDeclared` (THROW, 2026-09-25)
+
+**Every prop that CAN carry a canvas handle is either bound, or declared.** A new template that does
+neither fails the build. Founder ruling: "if it makes sense to bind, we do — or warn if it's not."
+
+```ts
+bindings: { unbound: { fps: "timing", gap: "geometry", seed: "determinism" } }
+```
+
+One honest word is the point — the reason is for a reviewer. Keys are dotted exactly as `propsSchema`
+nests them (`titles.title`).
+
+### The complete surface — one ruling per control
+
+`MUST ACCOUNT` = bind it, or name it in `bindings.unbound`. `NEVER` = not a canvas thing; the
+right-hand panel is its surface, and the rule stays silent.
+
+| Prop / flavour | Handle | Convention |
+|---|---|---|
+| `string`, free text | `string` | **MUST ACCOUNT** |
+| `string` + `isColor` / `colorPicker` | `color` | **MUST ACCOUNT** |
+| `number` | `number` | **MUST ACCOUNT** |
+| `media` | `media` (also a drop target) | **MUST ACCOUNT** |
+| `string[]` · `number[]` · `media[]` | per element, by index | **MUST ACCOUNT** (bound anywhere on the prop counts) |
+| `json` · `list` · `array` | per leaf, `path` + `kind` | **MUST ACCOUNT** (any leaf counts) |
+| `json` + `picker: "regions"` | `rect` | **MUST ACCOUNT** |
+| `string` + closed set (`oneOf`, a static `options` list) | `choice` (a pick, never typed) | **NEVER DEMANDED** — a mode has no rect of its own; bind it when a rect IS the mode (the card → `preset`) |
+| `string` / `number` + `optionsFromConnection` | — | **NEVER** — the host has no list without the connection |
+| `number` + closed set | — | **NEVER** |
+| `boolean` | — | **NEVER** — a one-way door: `false` renders no rect to click |
+| `group` | — | **NEVER** — a container; its fields are walked individually |
+| `m0` · `m0c` · `m0p` | — | **NEVER** — the value IS the composition of every rect, not one of them |
+| `code` | — | **NEVER** — read-only by contract; a handle implies editing |
+| anything `ui.hidden` or `consumer: "human"` | — | **NEVER** |
+
+Why the `m0` family is excluded, since it is the tempting one: a layout prop has no clickable element.
+All 10 shipped layout props (wireframe, dsl-tutorial, screencap-grid v1/v2, watermark, qr-animate,
+camera-debug) drive the ROOT composition — you would have to select the whole grid, which the canvas
+cannot express. If a template ever nests a layout prop into ONE cell, that cell is a real handle and a
+sixth kind (`"layout"`) becomes worth having. None does today.
+
+**Bindable ≠ has a rect.** The predicate says a `number` is always inline-editable; whether any rect
+*shows* it is the template's business. `durationMs`, `fps`, `gap`, `seed`, `padding` are all
+accountable and correctly unbound — which is exactly why the rule takes a declaration instead of
+guessing from the pixels.
+
+**A colour that IS `document.backgroundColor` needs nothing** — no binding, no declaration. It has no
+source and no rect, so no handle can exist, and it is the way a canvas SHOULD be filled: a full-frame
+base rect becomes a click target that shadows everything behind it whenever the pointer is not on a
+smaller tile (founder direction 2026-09-25). Matched case-insensitively, root or child.
+
+**A binding in a nested CHILD counts.** A template that composes its content into a child document
+(the hello-world card puts everything in a `card` child) reaches its props perfectly well — Make
+resolves a binding through children. **But the audit renders at `defaultProps`,** so a rect the
+template only creates when a prop is non-empty reads as unbound. That is the "bind even when the value
+is empty" rule biting: bind it unconditionally, or declare it.
+
+**A stale declaration is a violation too:** naming a prop that cannot carry a handle, naming one that
+is in fact bound, or leaving the reason empty. An entry claims a reviewer looked at that prop.
+
+**Exempt:** any template hashed in the repo's `frozen.manifest.json`. It shipped before the
+convention, it is never edited in place, and the fix would be a vN+1 nobody will write. A repo with no
+manifest has shipped nothing and holds every template to the rule.
+
+## The in-context line — `bindingHints` (THROW, 2026-09-27)
+
+**Every bound rect shows one line in context.** Make puts it under the inline editor when a person
+double-clicks, on the tile card's row, and in the handle's hover tooltip — what changing the value
+does and what it looks like, so nobody has to open the settings pane or a manual to understand a knob.
+Founder ruling: a production-grade template adheres to all the surfaces of the ecosystem, and the
+canvas is now the primary one; "it's better to take this tax now."
+
+The line comes from either of two places, and the gate accepts either:
+
+| Where | How | Reaches |
+|---|---|---|
+| the prop | the catalog sidecar: `props.<key>.description` in `<name>.catalog.json` (0.3.1; `propsSchema.<key>.description` in code is the pre-0.3.1 form, kept only by shipped templates) | every rect bound to that prop |
+| the binding | `bindProp(src, key, i, { hint: "…" })` · a `bindProps` entry's `hint` · `withBindingHint(src, "…")` (composes with every binder) | that rect only — the wording for THIS place |
+
+One plain sentence, never markdown, never the value itself ("The month this calendar shows; the grid
+re-flows to its weeks", not "October"). Make trims it and caps it near 200 characters. The tax is
+therefore one honest sentence per bound prop, paid once in the sidecar; a per-rect `hint` (code — it
+describes one specific rect) is for the cases where the same prop means something different in
+different places. The gate judges hints AFTER the catalog applies, so a sidecar description satisfies it.
+
+**Needs none:** a `companion` leaf (filled only by a media drop, never shown in a form), and any prop
+that is not bound (an `unbound` declaration already carries its reason). A binding on an unknown prop
+is `bindingsSound`'s finding, not this one.
+
+**Exempt:** any template hashed in the repo's `frozen.manifest.json`, like the roll call — it reports
+in `lagging`, never `findings`. The CLI ignores the field entirely; it is extra data there.
+
+## The `bindingsCover` convention — what the gate checks
+
+The roll call above is the gate. `bindingsCover` is the WEAKER SECOND SIGNAL kept beside it
+(posture `record` → a warning): it reads the drawn text, so it is the only rule that can catch a prop
+bound to the WRONG rect, and it still fires on frozen templates where the roll call cannot. Both
+`check-registry.mjs` copies and `m0saic doctor <repo>` run both.
+
+- A **free-text `string`** prop — not `meta.ui.hidden`, not `consumer: "human"`, not a closed /
+  picked set — whose default is ≥2 characters and appears verbatim in drawn text must be bound.
+- A **`number`** prop, same exclusions, whose default appears in drawn text in one of its honest
+  spellings: `String(v)`, `toLocaleString("en-US")`, and `toFixed(1|2)` **only when the value already
+  has decimals** (nothing draws an integer count as `"1.0"`, but chrome draws versions that read that
+  way). A one-character spelling never counts.
+- Numbers match on a **digit boundary**: `12` is not read out of `2012` or `3.12`, and a drawn
+  `1,200` is not read as the prop `200`.
+- Coverage is per PROP, not per rect — a prop bound anywhere on the root document is covered.
+
+### One rect, two props — a composite line
+
+`"@qsbuilds · 2026 on GitHub"` is one rect drawing two props, and a single `editor.binding` names one
+of them. A bare `bindProp` there would REPLACE the existing handle, so the rule says so and names the
+fix that keeps both:
+
+```ts
+bindProps(src, [{ propKey: "handle" }, { propKey: "year", kind: "number" }])
+```
+
+— several handles on one rect — or split the line so each prop gets its own rect. (`year-card/v1` is
+the live example; it is frozen, so its fix is v2 and it warns until then.)
+
+Colour coverage is not checked: a colour is never drawn as text, so it needs a different detector.
+
+## Authoring helpers (`@m0saic/template-utils`)
+
+- `bindProp(src, propKey, index?)` — the basic case.
+- `bindProps(src, entries)` — several leaves on one rect (a multi-layer text,
+  a cell that moves AND edits AND takes a drop). Writes `editor.bindings`,
+  which wins over the single `binding`.
+- `bindPropPath(src, propKey, path, kind, { onClear?, seedDraft? })` — one
+  structured leaf.
+- `bindPropRect(src, propKey)` — a one-region regions picker edited in place.
+- `bindPropRange(src, propKey, index, range, focus?)` — one line of a
+  multi-line string prop (a code state, a lyric block); offsets index the RAW
+  prop string.
+- `stripPropBindings(doc)` — a host composing ANOTHER template's render drops
+  its bindings (they name the inner template's props).
+- `tag(src, label)` composes either way round with all of them.
+
+## `onClear` — what an EMPTY commit means
+
+```ts
+{ propKey: "days", path: [rowIndex, "day"], kind: "number", onClear: "remove-element" }
+```
+
+- `"remove-element"` — splice the element at the leading numeric path segment
+  (the whole row, or one element of a basic list) out of its array. Needs an
+  `index` or a numeric first `path` segment.
+- `"unset-leaf"` — delete the leaf key from its object, or unset a basic prop
+  so its default shows again. Not for array-element leaves (no key).
+- Absent — an OPTIONAL colour prop (a basic prop or a group field, not a leaf
+  inside a row or list) unsets, back to the template's own colour (platform
+  `defaultOnClear`); a required colour and other numbers refuse an empty commit;
+  strings write `""`; a scalar media clears to `""`; a `media[]` element refuses
+  (a hole in a media list is not a value the engine can open). `"none"` is never
+  a clear — it is a colour (transparent).
+
+Editor rules: "empty" is blank for numbers / colours, `""` for text. An empty
+commit against an already-empty leaf writes nothing. In a multi-field session a
+row removal supersedes its siblings' writes; rows go highest index first. The
+panel stays the primary place rows are deleted — canvas clear is an accelerator.
+
+## `seedDraft` — prefill an EMPTY leaf from the rect's context
+
+```ts
+{ propKey: "days", path: [len, "day"], kind: "number", onClear: "remove-element", seedDraft: String(info.day) }
+```
+
+- Applies only when the bound leaf reads EMPTY / absent; a leaf with a value
+  ignores it. A DRAFT: shown pre-selected (Enter alone accepts it), written on
+  commit like typed text, never applied by itself. Deleting it and committing
+  empty still runs `onClear`.
+- Blur commits too, so an untouched seeded form that loses focus WRITES the
+  seed — mind this when seeding.
+- Wire shape is a string; a blank seed, or a non-numeric seed on a number
+  leaf, throws at author time; `rect` and `media` leaves take no seed.
+- Focus lands on the FIRST field: order a seeded field first when the seed is
+  the whole suggestion.
+
+## `kind: "media"` — a rect that takes a dropped file
+
+A media-bound rect is a DROP target on the Make canvas (a file dragged onto it
+writes the path) with a picture-glyph handle that opens the media chip —
+`Choose file…` / `Replace…` · `Remove` (when clearable) · "or drop a file on
+the cell". A file in flight lights every media slot; a slot whose prop refuses
+the kind lights muted.
+
+- What may land is the PROP's say: `meta.control.accept` (`["image","video"]`)
+  and `meta.control.extensions`. Judged by MIME while in flight, by extension
+  at drop.
+- `media[]`: index `< length` replaces, `=== length` appends (an add handle),
+  `> length` is refused. A media list is never padded with `""`.
+- A tile pairs handles freely — the drop-calendar's facecam is
+  `bindProps(src, [{ propKey: "facecamRegion", kind: "rect" }, { propKey: "facecam" }])`:
+  move it, or drop on it. Put the MEDIA entry first when a double-click should
+  mean "replace the picture".
+
+### A drop commits the tile's seeded companions
+
+When a file lands, every EMPTY sibling leaf on the tile that carries a
+`seedDraft` is written with its seed — the rect's meaning travels with the
+gesture (the clicked date; the slot number). Leaves with a value, or empty
+leaves without a seed, are untouched.
+
+`companion: true` marks a seeded leaf ONLY the drop fills:
+
+```ts
+{ propKey: "days", path: [row, "teaser"], kind: "number", seedDraft: String(teasers.length + 1), companion: true }
+```
+
+It never shows in the text form (a blur-commit there would write the seed on
+an unrelated edit) and never earns a badge. Needs a kept `seedDraft`; refused
+on media / rect leaves. The drop-calendar date cell, in full — one drop births
+a pictured row:
+
+```ts
+bindProps(cell, [
+  { propKey: "days", path: [n, "day"],   kind: "number", onClear: "remove-element", seedDraft: String(day) },
+  { propKey: "days", path: [n, "title"], kind: "string" },
+  { propKey: "teasers", index: teasers.length, kind: "media" },
+  { propKey: "days", path: [n, "teaser"], kind: "number", seedDraft: String(teasers.length + 1), companion: true },
+])
+```
+
+## Starter media — the slot before the footage
+
+A template that wants the slot present (and droppable) before the user has a
+file renders a stand-in while the prop is empty. Two sources:
+
+1. **Bring your own** — media bundled next to the template
+   (`assets/*.png|mp4|svg`, mirrored by copy-assets), built with
+   `fileAsset(resolve(__dirname, "assets"), name, kind)` from
+   `@m0saic/template-utils/dist/m0saic/assetPath` (asar-safe).
+2. **Included defaults** — `starterMedia(role)` from
+   `@m0saic/template-utils/dist/media/defaultMedia` (node-only deep import):
+   roles `portrait` `landscape` `square` `facecam` `avatar` `logo`, one small
+   viewBox-only SVG each (`assets/starter/`, minted by
+   `tools/mint-starter-svg.mjs`). Returns `null` when the file is not on disk —
+   degrade to the template's own stand-in, never an error mosaic.
+
+An `.svg` file asset is rasterized to a PNG at plan time by the engine, and
+Make's preview still-extractor rasterizes it the same way before ffmpeg sees
+it — ffmpeg itself has no svg decoder, so never hand an svg path to it directly.
+A still stand-in in a video slot keeps a no-footage render a poster (PNG);
+motion arrives with the real clip.
+
+Make marks an EXISTING slot with no path (a starter showing) with a persistent
+dashed outline and an "Add …" glyph. An add handle (`teasers[len]`, an unborn
+row) is not a slot and stays quiet — otherwise every empty date cell would light.
+
+## What Make does with them (the host side, for orientation)
+
+- Badge row on hover: one glyph per kind (T · 123 · swatch · move · picture),
+  collapsing to one dot on a tile under ~60 on-screen px. A click on a glyph is
+  a double-click WITH that intent.
+- Text / number / colour → the inline form over the rect (Enter / blur commit,
+  Esc cancels, an unchanged draft writes nothing). Rect → the regions draw
+  session seeded from the painted cell. Media → the chip; a drop needs no click.
+- Every write goes through the ONE prop writer, so it survives every other
+  edit and re-renders the template; the panel field updates because it IS the
+  prop.
+- The double-clicked tile is often chrome stacked over the bound rect (gridlines,
+  glass) — Make looks THROUGH the stack under the pointer for the topmost bound
+  tile, for clicks and drops alike.
+
+First implementers: `@m0saic-dev/creator/drop-calendar/v1` (every kind, the
+companion, the facecam slot); `@m0saic/alpine/*` (text / number / colour);
+`@m0saic-dev/music/lyric-video/v1` (ranges).

package/node_modules/@m0saic/knowledge/docs/templates/reference/template-flags.md

@@ -0,0 +1,236 @@
+# Template status flags: `internal` / `primitive` / `deprecated`
+
+Lookup reference for the three orthogonal discovery/visibility flags on
+`MosaicTemplate`. A template may carry any combination; conflating them is the
+standard mistake. Declared in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts —
+`internal?`, `primitive?`, `deprecated?` (a `MosaicTemplateDeprecation`), each
+with its truth table in the JSDoc (re-verify:
+`grep -n "internal?: boolean\|primitive?: boolean\|deprecated?: MosaicTemplateDeprecation" https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts).
+
+**All three are CATALOG fields (0.3.1).** They describe a template without
+changing what it renders, so they are declared in the template's catalog
+sidecar — `<name>.catalog.json` beside its module — never in its code
+(`catalogSidecar`, throw). The registry applies the sidecar catalog-first when
+the template is defined, so hosts read `template.internal` / `.primitive` /
+`.deprecated` exactly as before. Templates shipped before 0.3.1 keep the values
+in their (frozen) code; a sidecar entry overrides them. The same goes for
+`label`, `description`, `tags`, `platforms`, `channels` and `preview`.
+
+| Flag | Question | Renderable alone? | Default UI |
+|---|---|---|---|
+| `primitive?: boolean` | "Is this a base others build on?" | **Yes** | Shown + **PRIMITIVE** badge (teal) |
+| `internal?: boolean` | "Is this intended as a **top-level selection**?" (No → hidden) | **Sometimes** — the flag doesn't decide this | **Hidden**; **INTERNAL** badge (violet) when revealed |
+| `deprecated?: MosaicTemplateDeprecation` (`{reason?, replacement?, since?}`) | "Is this still the recommended pick?" | Yes | **Hidden**; **DEPRECATED** tag + "use X instead" |
+
+**`primitive` is informational — it does NOT hide anything.** `internal` and
+`deprecated` are the visibility gates.
+
+## Why `primitive` ≠ `internal`
+
+- **`primitive` is a quality** — foundational, widely reused. `charts/donut`,
+  `charts/stat-card`, `charts/bar-graph`, `primitives/grid` are primitives *and*
+  perfectly good standalone picks.
+- **`internal` is an INTENT/visibility flag, not a capability statement** — it says
+  "not intended as a top-level pick": excluded from public listings and template
+  pickers by default, but fully available to `renderNestedTemplate()`
+  (`internal` JSDoc, `template.ts:1375-1384`). Whether it can render standalone
+  varies by template and is NOT what the flag encodes: the ffmpeg-pulse piece
+  templates are internal yet render fine on their own; `bar-graph`'s `bar-cell`
+  leaf is internal AND genuinely expects parent-injected context. Don't infer
+  either way from the flag — read the template.
+- **Both** is a real combination: a shared building block many templates reuse
+  that still isn't meant to be picked top-level.
+
+(The `primitive` flag's orthogonality table in `template.ts` used to gloss
+`internal` as "can this render on its own?", contradicting the `internal` JSDoc —
+fixed in-code 2026-07-27; both JSDoc now carry the top-level-selection semantics.)
+
+## Where the flags surface
+
+- **Electron `templates:get`** (the Mosaic Desktop / Web app source (not published)) serializes all
+  three into the meta the desktop Templates page consumes.
+- **Desktop Templates page** — PRIMITIVE / INTERNAL badges with explanatory tooltips.
+- **CLI `list-templates` / `browse-templates`** — annotates
+  `(primitive) (internal) (deprecated)` in that **fixed order**
+  (the CLI source (not published)-33`).
+
+## Curation is a content decision
+
+`primitive` started as 4 seeded entries and is on **29 templates** as of 2026-07-27
+(re-verify: `grep -rn "primitive: true" https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic | wc -l`).
+There is no rule that derives it — like `deprecated`, someone decides. If you're
+adding a template that other templates will compose, set it (in its catalog
+sidecar); don't wait for a sweep.
+
+⚠️ **Deprecating obligates a pruning pass** — declare `deprecated` in the old
+version's catalog sidecar (never its frozen code; a shipped deprecation is
+permanent), then repoint the curated registry,
+and remove the id from the CLI E2E cases and the e2e variant list. The full ordered
+procedure is in the maintainers' agent contract §10 (not published) "Deprecating a template"; a deprecated id must
+never linger in those lists. The default e2e sweep auto-excludes deprecated
+templates; opt back in with `M0SAIC_INCLUDE_DEPRECATED=1`.
+
+### Deprecation also silences convention advice (2026-09-09)
+
+`M0SAIC_INCLUDE_DEPRECATED=1` governs more than the e2e render sweep: it also
+controls **convention findings** in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/tools/check-registry.mjs,
+which gates `npm run build`.
+
+By default a deprecated template's definition-time and render-time convention
+warnings/errors are **suppressed** — the template is defunct, so the advice will
+never be acted on and repeating it forever is noise. This makes the intended
+workflow self-cleaning: for a shipped template that violates a convention, **bump
+to vN+1 and deprecate the old one — the old one goes quiet automatically.** There
+is no exclusion list to maintain.
+
+The `outputFormat` convention (2026-09-13: a public template declares
+`outputHints.format`; record posture) treats both visibility gates as
+exemptions at the audit itself, not only through this suppression: an
+`internal` building block renders only nested and a `deprecated` template is
+frozen history, so neither owes a deliverable declaration
+(`auditOutputFormat`, https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/template/auditSchemaConventions.ts).
+
+The suppressed count is always printed, never silent:
+
+```
+[check-registry] ℹ 14 finding(s) on 22 deprecated template(s) suppressed
+                   (advice only — freeze + fingerprints still apply).
+                   M0SAIC_INCLUDE_DEPRECATED=1 to see them.
+```
+
+⭐ **Suppression is ADVICE ONLY.** The freeze gate (`frozen.manifest.json`, every
+template shipped in 0.1.0) and the layout fingerprints still cover deprecated
+templates in full, byte for byte, in both modes. Deprecation means "stop
+suggesting improvements" — it NEVER grants permission to change a shipped
+template. See the maintainers' agent contract §10 (not published).
+
+Measured when introduced (103 registered templates, 22 deprecated): render-time
+warnings 21 → 12, definition-time warning knobs 208 → 165 across 30 → 25
+templates; freeze (327 files) and fingerprints (89) identical either way.
+
+## The repo's front door — `repo.helloWorld` (2026-09-14)
+
+Not a template flag but a **repo-descriptor** field beside them
+(`MosaicTemplateRepoDescriptor.helloWorld?: TemplateId`,
+https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template-repo/template-repo.ts): the id of the template a
+newcomer renders first. Core names `@m0saic/hello-world/v1`; each starter names
+its own `…/basics/hello-world/v1`. It is deliberately NOT a `TemplateRole` — roles
+say what a template *produces*; this says which one is the door.
+
+Readers: the CLI alias (`m0saic hello-world --template-repo <path>`), the manifest
+(the descriptor is embedded, so `template-manifest.json` carries it zero-exec; the
+platform loader passes it through), and — follow-up — Make's "Start here" chip.
+The gate's `repoFrontDoor` convention (record posture) warns when the field is
+unset or names an id the repo does not register; `internal` / `deprecated`
+templates are fine to name, just unusual. Authoring recipe: `standalone-pack-authoring.md`
+§1.
+
+## A canvas that is a knob — `resolveOutputHints` (2026-09-15)
+
+Also not a flag but a **template field** beside `outputHints`:
+`resolveOutputHints?: (props) => Partial<MosaicTemplateOutputHints>`. The
+static `outputHints` stay what the manifest and the cards show; the resolver
+is what a host asks with the current props before rendering, through the one
+helper `resolveTemplateOutputHints(tmpl, props)` (`@m0saic/template-utils`).
+Readers: CLI `make` (+ wireframe / tutorial paths), Electron preview / cover /
+render-to-file + the `templates:resolveOutputHints` IPC, the web design
+preview, and Make's Device anchor (re-resolved on every prop change). The
+seam's `outputHintsResolve` convention (THROW posture) checks it returns an
+object, is deterministic at `defaultProps`, and agrees with the static hints
+for every field it returns there. Precedence: [`../output-resolution-tree.md`](../output-resolution-tree.md) §size.
+
+**Image or video is part of the same answer (2026-09-26).** `format` rides the same
+resolver. A template whose kind depends on its inputs — a `media` prop that accepts
+both kinds — declares it per props, `resolveOutputHints: (props) => ({ format: … })`,
+and its static `outputHints.format` is that function's value at `defaultProps`, which
+for an EMPTY media slot is **image** even when the template is "for" video (the
+`outputHintsResolve` throw holds the two equal). The resolver is pure and prop-only:
+it runs before any probe, so a path's extension is the evidence available. Exactly
+three answers exist — the static hint at defaults, the resolver at the current
+props, and the user's override — and nothing else authors one. Every host asks the
+author through `resolveTemplateOutputHints(tmpl, props).format` and passes it into
+`createDesignContext` / `createEngineContext` as `format`, so the `format` the
+`defineMosaicTemplate` wrapper stamps on the rendered document is a RECORD of the
+decision, never a source of it. `inferOutputKind` (`@m0saic/platform`) is a last
+resort for a bare `.mosaic` opened cold with no template behind it, and since
+2026-09-26 it counts a `type: "media"` video source as motion (`videoMedia`) — the
+omission that made footage-through-a-mask read as a still. The defect class and the
+seven-surface audit that produced this rule:
+(internal design history).
+
+## The lattice declarations — `lattice` (2026-09-16)
+
+**Convention `latticeSmooth` (throw):** every split count above 12 in the rendered
+layout — root document and every nested child, walked as documents (a nested doc
+whose flatten fails below its floor is still measured) — is 5-smooth, `N = 2ᵃ·3ᵇ·5ᶜ`.
+Counts ≤ 12 with a rough factor (7 weekdays, 11 tiles) pass as small-basis ratio
+fill. Measured at the hinted canvas and, under `--sweep`, on the standard canvases.
+Why: all delivery canvases are 5-smooth with family gcd 120, so 5-smooth counts
+divide them (pixel-exact), any two 5-smooth self-lattices LCM to a small number,
+and a child never inherits a rough cell size (handbook
+[`composition-arithmetic.md`](../../handbook/composition-arithmetic.md) §1–3).
+`m0saic doctor <repo>` reports it for external packs at error severity — the
+publish requirement. Plan + numbers: (internal design history).
+
+`MosaicTemplate.lattice?` (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts, beside
+`primitive?` / `deprecated?`) is the declaration surface — every override is typed,
+reasoned, and printed by the gate:
+
+| field | when it is honest | effect |
+|---|---|---|
+| `mode: "bitmap"` | the split counts ARE a raster (QR modules, barcode bars, a logo trace, the community M) — handbook §3c BITMAP, baked once, never live-composed | the template is skipped with a note |
+| `allow: [{ count, reason }]` | a count above 12 that is content cardinality (53 ISO weeks; a 335-tile fixture grid) | the count is accepted; the reason is printed and carried in `--json` |
+| `canvas: "physical"` | the hinted size is a millimetre spec at a dpi (business card 1130×678 = 2·5·113 × 2·3·113) | the rough-axis finding is not raised, counts the canvas hands down are charged to it (not to the construction), and the `--sweep` canvases are skipped — a print size cannot move |
+
+Per DOCUMENT, `MosaicEngineMeta.lattice?: { mode: "bitmap" }` (`doc.engine.lattice`)
+marks a raster a parent assembles itself (the business card's QR child, built from
+`qrToRenderable` pieces) — that subtree is skipped, the parent is still measured.
+(The layout-fingerprint sidecar cannot carry this marker: the fleet lock
+https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/lattice-audit.test.ts re-measures such a template with
+`auditRenderedTemplate` instead of trusting the flattened string.)
+
+**Not honest:** a count that came from your arithmetic — independent rounding to a
+cap (121/119/241/245), a pitch matched to a grid that no longer exists (499),
+`round(side/K)` + `ceil` self-frames (99/101), pixel splits inside an already
+quantized cell. The finding names the nearest 5-smooth neighbours and the LCM cost;
+the neighbour almost always looks identical.
+
+## Reading the dictionary from a template — web vs node (2026-09-16)
+
+`@m0saic/dictionary` has two entries: node (`index.ts`, reads `.m0`/`.m0c` from
+disk) and browser (`browser.ts`, what the Mosaic Desktop / Web app source (not published) bundles via the package's
+`browser` field). Every jest suite resolves the NODE entry, so a template that reads
+a brand entry synchronously can be green under test and an error mosaic on
+app.m0saic.io — which is exactly what QR Code's centre M, Brand Marks v3 and
+community-m did until 2026-09-16 (the browser entry shipped every brand `m0` as `""`
+and its `getRankSet` threw). Rules that hold on BOTH entries now:
+
+- **`entry.m0` is populated for every entry whose canonical m0 is ≤ 40 KB**
+  (`INLINE_M0_MAX_CHARS` in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/dictionary/tools/validate.js, which emits a
+  committed sibling `m0.json` per entry that `browser.ts` imports). Only
+  `brand/m-33_bitmap` (149 KB) ships `m0: ""` on web — a template that can take it
+  must guard `if (!entry.m0)` and say "Desktop renders this" (Brand Marks v3 does).
+- **`entry.masks`, `entry.rankSets`, `entry.sourceCount` ride in `metadata.json`** →
+  identical on web. `registry.getRankSet(id, name)` works on web (same lookup as
+  node). Named mask SETS (`getMaskSet`) are node-only.
+- **The guards, in order of reach:** https://github.com/m0saic-project/m0saic-packages/blob/main/packages/dictionary/src/browser.test.ts
+  (browser m0 == node m0 for every inlined entry; only the bitmap lazy) ·
+  https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/webDictionary.test.ts (renders QR Code / Brand Marks /
+  community-m against the browser entry via `jest.mock`) · the Playwright web lane
+  the Mosaic Desktop / Web app source (not published) (the shipped bundle).
+  **Add your template to `webDictionary.test.ts` if it reads a brand entry.**
+
+the Mosaic Desktop / Web app source (not published) copies `*.json`, so `m0.json`
+also lands under `public/dictionary/` — harmless (≤ 10 KB each). The light entries in
+`browser.ts` are still hand-written F-form literals; the drift test compares them
+canonically to the generated `m0.json`.
+
+## Known wrinkle
+
+The Templates page's **"Show layout primitives" toggle** (renamed from "Show
+primitives" on 2026-09-16 so the label says what it does) gates a *tag-derived*
+Primitives **category** (tags `grid` / `primitive` — in practice the `primitives/`
+family) — separate from the cross-cutting `primitive` **flag**, which only ranks and
+badges. They coexist cleanly, but they are two mechanisms with one word. Driving the
+toggle off the flag would hide most of the alpine/charts shelf by default, so the
+founder kept the category gate and fixed the label instead.