@m0saic/knowledge 0.2.0

package/docs/skills/text-in-templates.md

@@ -0,0 +1,126 @@
+# Text in templates
+
+How to put text into a template without it silently clipping.
+
+---
+
+## ⚠️ The rule that bites: nothing soft-wraps
+
+**No rasterizer in m0saic wraps text.** A long string in a single `MosaicTextLayer`
+renders as **one line and clips off the cell** — no error, no warning, no visual cue
+in the plan. It just disappears past the edge.
+
+This is true for **both** rasterizers:
+
+- `drawtext` (ffmpeg) has no soft-wrap.
+- `rasterizer: "svg"` converts glyphs to outlines via `@m0saic/text` — there is no
+  wrapping logic in that path either.
+
+**Any template that puts user-typed or composed strings into text MUST pre-break
+them.** Use `multilineTextLayers` (below); don't hand-roll.
+
+The failure is worst with user data — a title that fits every fixture and clips on the
+one real input nobody tested.
+
+---
+
+## The source shape
+
+A text tile is one `MosaicTextSource` per leaf cell:
+
+```ts
+{
+  type: "text",
+  style: { fontSize, fontColor, fontFamily },   // source-level, applies to all layers
+  layers: [ /* MosaicTextLayer[] — one per LINE */ ],
+  placement: { hAlign, vAlign },                // optional if layers carry their own
+  visual: { backgroundColor },                  // solid fill behind the text
+  renderMode: { kind: "image" },                // see below
+}
+```
+
+A `MosaicTextLayer` is
+`{ content: { kind: "literal", text } | { kind: "expr", expr }, style?, placement? }`.
+Layers stack within one source; each may carry its own `placement` (including a
+`yExpr`) to position itself in the cell.
+
+### Two orthogonal knobs — don't confuse them
+
+| Knob | Values | Question it answers |
+|---|---|---|
+| `renderMode` | `{ kind: "image" }` \| `{ kind: "video" }` | single RGBA frame, or an RGBA video for `ctx.target.durationMs`? |
+| `rasterizer` | `"drawtext"` \| `"svg"` | which mechanism turns glyphs into pixels? |
+
+**Choose the rasterizer on dynamism**, per `templates/patterns/perf-authoring-rules.md`
+**R9**: `svg` for static text (a mask + colour tile — no drawtext, no per-frame
+shaping), `drawtext` only when the text is genuinely per-frame dynamic. `svg` does
+**not** support expressions; the fallback to drawtext for those is correct. Read R9
+before scaling up — it carries the density budgets (hundreds of glyph masks in one
+panel approach the argv wall) and the note that **the app fits text wider than the
+CLI**, so leave generous fixed-font margins.
+
+---
+
+## Helpers — use these, don't hand-roll
+
+All from `@m0saic/template-utils`:
+
+| Helper | Signature | Use |
+|---|---|---|
+| `multilineTextLayers` | `({ text, maxCharsPerLine, fontSize, lineHeightRatio?, hAlign? }) => MosaicTextLayer[]` | **The one you usually want.** Wraps and returns one centred layer per line, vertically stacked via `yExpr`. Feed straight into `layers`. |
+| `wrapText` | `(text, maxCharsPerLine) => string[]` | Greedy word-wrap by character count. Never splits a word. Use when you need the lines themselves. |
+| `makeErrorMosaic` | `(message, { width, height, title?, errorCode?, … })` | Fail-fast card that **also sets `engine.renderStatus = "error"`** — the UI disables Make, and the CLI exits **3** (RENDER DEGRADED) after writing the card. Use for invalid input, and **pass `errorCode`**: it is what lands in the `--report` sidecar's `renderErrorCodes` (omit it and the caller only sees `ENGINE_ERROR`). See `runtime/cli-usage.md` → "Exit codes". |
+| `makeStubMosaic` | `(label, { width, height, backgroundColor?, textColor?, note? })` | "STUB" placeholder. Auto-sizes the font. Does **not** mark an error — validate-only still passes. |
+| `animateNumbersInText` | `(text, { startSec, durationSec, ease }) => string` | Returns an `expr` that counts numbers up on intro (KPI / stat cards). |
+| `fadeInExpr` | `(startSec, durSec, ease?) => string` | Overlay-alpha expression for a timed fade-in. |
+
+> `multilineTextLayers` returns `[]` for empty input — **check and omit the source**
+> rather than emitting a text tile with no layers.
+
+> `makeErrorMosaic` vs `makeStubMosaic` is a real distinction, not a style choice:
+> error blocks the render path, stub does not. Reach for stub only when "not
+> implemented yet" is a legitimate state.
+
+Both size their cards from dimensions **you** pass — pass `ctx.target.{width,height}`,
+never `ctx.output` (see `rendering-model-contract.md` Rule 5b).
+
+---
+
+## Sizing
+
+`maxCharsPerLine` is coarse — glyph widths vary by font. Start from:
+
+```
+maxCharsPerLine = floor(cellWidthPx / (fontSize * 0.55))
+```
+
+and tune per font. **Scale `fontSize` to the cell** — `clamp(width / N, lo, hi)` —
+rather than hard-coding pixels, so the template survives a resolution change.
+
+### Canonical wrapped, centred text tile
+
+```ts
+import { multilineTextLayers } from "@m0saic/template-utils";
+
+function textTile(text: string, fontSize: number, bg: string, cellWidth: number) {
+  const maxChars = Math.max(8, Math.floor(cellWidth / (fontSize * 0.55)));
+  return {
+    type: "text" as const,
+    style: { fontSize, fontColor: "#ffffff", fontFamily: "Arial" },
+    layers: multilineTextLayers({ text, maxCharsPerLine: maxChars, fontSize }),
+    visual: { backgroundColor: bg },
+    renderMode: { kind: "image" as const },
+  };
+}
+```
+
+---
+
+## Related
+
+- **`templates/patterns/perf-authoring-rules.md` R9** — rasterizer choice + density budgets.
+- **`templates/construction-strategy.md`** — "Drawing shapes: SVG inline-mask on a
+  color source". Text is for *words*; never draw a shape with a glyph — ffmpeg drops
+  `▲`/`▼`/emoji as tofu.
+- **`templates/rendering-model-contract.md` Rule 5b** — size error/stub cards off
+  `ctx.target`.

package/docs/skills/zero-overlay-analysis.md

@@ -0,0 +1,87 @@
+# The `0{}` operator — phantom geometry, deferred paint
+
+`0` is a passthrough: it donates its space to the next claimant and renders nothing.
+`0{...}` is a passthrough whose overlay still renders: the base donates space as
+usual, but the body receives the accumulated carry rect and **paints on top of the
+claimant, deferred**. An element that gives its space away, then draws over the
+sibling that absorbed it. Trimmed 2026-07-27 from a longer essay (git history).
+
+> **Source of truth:** [https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts](https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/src/parse/m0StringParser.ts)
+> (+ `parse/sortDeferredOverlays.ts`). Basics: [`passthrough-semantics.md`](passthrough-semantics.md),
+> [`overlay-semantics.md`](overlay-semantics.md).
+
+## The four quadrants
+
+| | Owns space | Doesn't own space |
+|---|---|---|
+| **Paints** | `1` (tile) | `0{}` (phantom overlay) |
+| **Doesn't paint** | `-` (null gap) | `0` (passthrough) |
+
+`0{}` is the fourth quadrant: spatial accounting and visual presence, fully
+decoupled.
+
+## The mechanism (verified at runtime)
+
+`3(1, 0{1}, 1)` @ 1080×720 — three 360px slots; the `0` donates, the last tile
+claims 720px; the overlay body gets the merged carry rect and paints LAST:
+
+| Paint order | What | Rect | `logicalIndex` |
+|---|---|---|---|
+| 0 | first tile | `{x:0, w:360}` | 0 |
+| 1 | claimant (expanded) | `{x:360, w:720}` | 2 |
+| 2 | deferred zero-overlay | `{x:360, w:360}` | 1 |
+
+Note the split between orders: the overlay is `logicalIndex` **1** (encountered
+before the claimant in DFS) but paints **after** it. Build sources in logical
+order; paint order is derived.
+
+**Multiple `0{...}` before one claimant sort area-DESCENDING at flush** — widest
+paints first (background), narrowest last (top). `5(0{1},0{1},0{1},0,1)` @1000px:
+claimant 1000px paints first, then 600 → 400 → 200 on top. Free z-ordering from
+coverage, no z-index.
+
+**Rects grow monotonically:** each `0{...}` in a run captures the prefix sum of
+slot widths, anchored at the run start — `4(0{1},0{1},0{1},1)` @800px yields
+overlays at `{x:0, w:200/400/600}` under a full-width claimant. Concentric framing
+from pure geometry.
+
+**Trailing `0{}` is always invalid** — `PASSTHROUGH_TO_NOTHING`; an overlay does
+not exempt the donation from needing a claimant. `2(1,0{1})` invalid;
+`2(0{1},1)` valid.
+
+## The body is a full m0 sub-expression
+
+Splits, nulls, passthroughs, nested overlays — all legal inside `0{...}`, parsed
+into the merged rect like an independent document. So a phantom can carry an entire
+sub-layout: holes that let the claimant show through (`0{4(1,-,-,1)}`), stacked
+rows (`0{3[1,1,1]}`), thin gridline rules at precise offsets
+(`0{100[0,…,1,…,0,1,…]}`), even nested overlay depth (`0{2(1{1},1{1})}` — four
+sources from one zero-space element). Source count = whatever the body demands.
+
+## Patterns (one line each)
+
+- **Floating annotation** — grid-positioned callout over an expanded tile's region.
+- **Progressive reveal** — monotone widths + per-source `startAtSec`: layers peel
+  front-to-back.
+- **Gradient banding** — N phantoms at fractional widths, solid colors at
+  decreasing opacity.
+- **Watermark/badge** — a tiny phantom deep in a 100-split places a corner stamp;
+  content and stamp stay structurally independent.
+- **Conditional layer** — phantom sources honor `overlay.enable` windows: a flash
+  highlight with zero structural change.
+- **Debug overlay** — inject `0{1}` tints/labels during development; removing `{1}`
+  restores the bare `0` with geometry untouched.
+
+## When `0{}` is wrong
+
+- The layer should CLAIM space (push siblings) → use `1` or `-`.
+- The template has many sources and non-expert consumers → the logical/paint order
+  split confuses source mapping; keep `0{}` inside internal primitives.
+
+## For agents
+
+You will almost never need `0{}` — `1`, `-`, `0`, and `1{1}` cover ~99% of
+layouts. Reach for it only when all three hold: (1) a visual layer at a specific
+grid position, (2) painting on top of whatever fills that region, (3) claiming no
+layout space. When all three hold, `0{}` is the correct expression, not a
+workaround.

package/docs/templates/README.md

@@ -0,0 +1,65 @@
+# templates/ — the authoring surface
+
+Read as a path: **contract → build → verify → publish**. The required authoring
+process (add / deprecate / tests / registry) is the agent contract §10 — not
+duplicated here.
+
+## The path
+
+1. [`philosophy-and-contract.md`](philosophy-and-contract.md) — what a template
+   IS: the typed contract, ctx.target vs ctx.output, tiers, props-as-schema.
+   - **Defaults are part of the contract**: every optional boolean / closed-set
+     knob carries a `defaultProps` value, every plain string/number a default or
+     a placeholder — enforced inside `defineMosaicTemplate` (throws first-party).
+2. [`construction-strategy.md`](construction-strategy.md) — how to build one:
+   the Rect Thesis, styles, smell tests.
+   - **Constraints first.** Declare the props contract and the layout
+     constraints, THEN build, THEN check in a loop across canvases × prop
+     combinations; the build itself is the first gate —
+     [`standalone-pack-authoring.md`](standalone-pack-authoring.md) §0.
+3. [`geometry-recipes.md`](geometry-recipes.md) — the four placement recipes
+   (SNAP_PX · placeInsetPieces · placeOptimizedPieces · lattice ratio-grid).
+4. [`rendering-model-contract.md`](rendering-model-contract.md) — the 12-rule
+   output contract the engine holds you to.
+   - [`output-resolution-tree.md`](output-resolution-tree.md) — how top-level
+     duration / size / fps / format / audio resolve (user > template intent >
+     host hints > engine defaults); read before touching any of them.
+5. [`layout-contract.md`](layout-contract.md) — verify layout intent
+   (withLayoutContract / checkLayout / assertLayout). **Before the first
+   candidate** for anything that paints text: tag fitted text, declare
+   `textFits`, sweep `assertLayout` at the 7-canvas set in the gate test.
+
+## By topic
+
+- [`recursion-nested-rendering.md`](recursion-nested-rendering.md) — children,
+  bottom-up eval, nested-mosaic-as-clip-region.
+- [`data-pipeline.md`](data-pipeline.md) — fetcher / adapter / handle patterns +
+  the operational how-to.
+- [`render-lifecycle.md`](render-lifecycle.md) — the four entry points
+  (`render` required; `renderLite` / `renderCover` / `renderTutorial` opt-in),
+  the null-on-absent dispatch rule, and the onboarding-surface checklist.
+- [`capability-templates.md`](capability-templates.md) — self-fetch app-runnable
+  templates; renderLite rules.
+- [`emission-patterns.md`](emission-patterns.md) — non-pixel outputs (data /
+  sidecars / telemetry).
+- [`theming.md`](theming.md) — design tokens over the upstream channel.
+- [`ui-controls.md`](ui-controls.md) — the `picker` taxonomy + prop controls.
+- [`standalone-pack-authoring.md`](standalone-pack-authoring.md) — branded pack
+  playbook (alpine is the reference).
+
+## reference/ — lookup specs (types & builders)
+
+[`placement-props`](reference/mosaic-placement-props.md) ·
+[`prop type: json`](reference/json-prop-type.md) ·
+[`template flags`](reference/template-flags.md) ·
+[`grid builder`](reference/grid.md) · [`MosaicColor`](reference/mosaic-color.md) ·
+[`prop bindings`](reference/prop-bindings.md)
+
+## patterns/ — distilled experience
+
+- [`perf-authoring-rules.md`](patterns/perf-authoring-rules.md) — R1–R11, each
+  paid for by a measured incident. Read before shipping any template.
+- [`case-study-lessons.md`](patterns/case-study-lessons.md) — L1–L9 from the
+  early template generation.
+- [`primitive-extraction-pattern.md`](patterns/primitive-extraction-pattern.md)
+  — when/how to extract primitives (incl. Rule 7: verify NESTED).

package/docs/templates/capability-templates.md

@@ -0,0 +1,72 @@
+# Capability-tier templates
+
+The tier contract itself (what `{ tier: "capability", caps }` unlocks, default-deny
+caps, when to stay core) lives in [`philosophy-and-contract.md`](philosophy-and-contract.md).
+This doc carries the two shipped patterns that go beyond the contract: app-runnable
+self-fetch templates, and the `renderLite` preview rule.
+
+> **Source of truth:** capability declaration shape in
+> https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/template/defineMosaicTemplate.ts; the shipped exemplar
+> `@m0saic/github/weekly-pulse/v1` (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/github/weekly-pulse/v1).
+
+---
+
+## App-runnable capability templates (self-fetch)
+
+The `.mosaicx`/cron chain (fetcher → adapter → runner) can't run from the Templates
+UI — the core runner is core-tier (mock/upstream only) and the live chain only exists
+as a `.mosaicx`. The shipped pattern: a single **capability-tier** template that IS the
+whole chain in one pickable unit — `@m0saic/github/weekly-pulse/v1`. It
+`fetch → derive → render`s itself when flipped to `source: "live"` (+ repo + token),
+and replays a frozen sample by default (network-free).
+
+- It's a **plain-object** `MosaicTemplate` (not `defineMosaicTemplate`) because it
+  returns a duration-follows-timings pipeline, so it skips the wrapper's
+  `assertTiming` (the CLI `make` path still applies assertTiming — a plain object
+  does NOT escape it there).
+- It reuses the runner's extracted `buildPulsePipeline`, so the app-runnable version
+  and the cron runner emit the identical beat pipeline.
+- A template can't be "core sometimes, capability sometimes" — the app-runnable live
+  version is a SEPARATE capability template, leaving the runner core-tier for the
+  cron path.
+
+### Live-mode clock exception
+
+An app-runnable capability template MAY read the wall clock for ONE thing: a
+live-mode default window (`props.window ?? lastFullWeek(now)`), documented as a
+deliberate exception to the clock rule (this template is non-deterministic in live
+mode by design). Pinning `window` or using the cron `{{lastFullWeek*}}` tokens keeps
+it deterministic. Replay mode never reads the clock. A `livePreview: true` escape
+hatch lets power users fetch real data into the geometric preview on demand.
+
+---
+
+## renderLite is PREVIEW-ONLY (RenderHero uses the real render geometry)
+
+> `renderLite` is one of FOUR render entry points, and it is not a capability-tier
+> feature — a core template may declare it too. The lifecycle contract for all
+> four (including the opt-in `renderCover` / `renderTutorial` onboarding
+> surfaces) is [`render-lifecycle.md`](render-lifecycle.md). This section keeps
+> the part that IS capability-specific: why a self-fetching template's stand-in
+> must never reach RenderHero, and the `renderable_ready` wiring that avoids it.
+
+`renderLite()` returns a stand-in (a themed "ready" card) so selecting a
+side-effecting template never runs its real work. It must feed ONLY the idle-state
+GeometricPreview — NEVER the render-progress hero (RenderHero), which would otherwise
+show the card while ffmpeg renders the real beats. Shipped wiring:
+
+- `templates:get` returns `hasRenderLite: typeof tmpl.renderLite === "function"` so
+  the host/UI knows a preview is a stand-in.
+- `templates:renderToFile`: right after the real `render()` (BEFORE ffmpeg's
+  `render_start`), for renderLite templates the host forwards the resolved renderable
+  via a `renderable_ready` renderEvent.
+- MakePage captures it as `liveRenderable` and flattens THAT into the hero filmstrip;
+  a stand-in preview never drives the hero. Until `renderable_ready` lands (a few ms)
+  or if it can't be flattened, the hero shows the neutral loader — never the card.
+  Core templates (no renderLite) are unchanged: their preview already IS the render
+  geometry.
+
+**Rule for authors/hosts:** if `render()` returns geometry structurally different
+from `renderLite()` (as any self-fetching capability template does), the host must
+not reuse the renderLite doc for render-progress; it must hook the real `render()`
+output.