m0saic 0.2.1 → 0.3.0

package/node_modules/@m0saic/knowledge/docs/templates/standalone-pack-authoring.md

@@ -0,0 +1,299 @@
+# 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.
+- **Image or video → the same resolver (2026-09-26).** A template with a media slot
+  that accepts both kinds answers per props — `resolveOutputHints: (props) => ({ format })`
+  from a pure check on the media path's extension — and its static `outputHints.format`
+  is that value at `defaultProps`. An empty slot renders a still, so the honest static
+  answer is usually **image** (the seam's `outputHintsResolve` throw keeps the two
+  equal). Never let a host guess from the document: `inferOutputKind` is a last resort
+  for a bare `.mosaic`, not a decision. Reference: `reference/template-flags.md`
+  § "A canvas that is a knob".
+- **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".
+- ⛔ **Filling the canvas: `document.backgroundColor`, never a full-frame rect.** This is
+  the **`canvasFill` convention, and it THROWS** (2026-09-25) — the build and
+  `m0saic doctor` both refuse a root document carrying a static, opaque, full-canvas colour
+  source. A base rect is a click target that shadows everything behind it, selected any time
+  the pointer is not on a smaller tile, and it is redundant: `doc.backgroundColor` fills the
+  canvas with no rect at all. Only a STATIC, opaque, unshaped fill counts — a curtain wipe
+  (`overlay.enable` / `window`), a scrim (`overlay.alpha`), a masked shape, a rounded card
+  (`effects`) and an inset fill (`placement`) are all legitimate and never flagged.
+  Templates already frozen are exempt. `bindingsDeclared` also accepts a colour prop that IS the document background
+  with neither a binding nor a declaration, because such a prop has no rect to bind.
+  - ⚠️ **The one case that needs a rect: a template COMPOSED INTO another.** The engine
+    lifts `backgroundColor` from the PRIMARY OUTPUT document only, so a child document's
+    own background is silently ignored (tracked at
+    (internal design history) — founder
+    owns the engine fix).
+  - **The declared escape** — an opt-in dev prop, NOT a rect in the default shape.
+    Defaulting it to `true` is ALSO how a template tells `canvasFill` that its rect is
+    deliberate; declaring it `false` is no escape:
+
+    ```ts
+    useNestedBackgroundColor: {
+      type: "boolean", required: false,
+      description: "Compose-time: also paint the background as a full-frame rect, for when this template is nested inside another (a child document's own backgroundColor is ignored by the engine).",
+      meta: { ui: { hidden: true, label: "Nested background rect" } },
+    }
+    ```
+
+    `defaultProps` leaves it **false / absent**, so a standalone render never grows the
+    rect. A template that composes this one passes `useNestedBackgroundColor: true` in the
+    child's props. Keep `backgroundColor` set as well — it costs nothing and keeps the
+    standalone path identical.
+  - **The m0 move is ONE wrap.** `F{…}` prepends exactly one full-canvas frame and the
+    wrapped layout follows in order (`F{2[1,1]}` → `1280x720@0,0`, `1280x360@0,0`,
+    `1280x360@0,360` at 720p), so frame 0 is the base and the content overlays it:
+
+    ```ts
+    if (props.useNestedBackgroundColor) {
+      return { ...doc, m0: `F{${doc.m0}}`, sources: [colorSource(bg), ...doc.sources] };
+    }
+    ```
+
+    `F` is pretty syntax: it **canonicalizes to `1{…}`**, and the file formats never emit
+    pretty form, so on disk the wrapper reads `1{…}`. Every source index shifts by one, so
+    anything keyed by `sourceIndex` (never a binding — those key by prop) moves with it.
+  - `meta.ui.hidden` is deliberate: this is a compose-time flag a parent sets
+    programmatically, not a knob a human picks (and hidden props are outside
+    `bindingsDeclared`'s roll call — a boolean is anyway).
+  - **When the engine fix lands, this prop goes away**: delete it, delete the rect, keep
+    `backgroundColor`. That is the whole point of it being opt-in and hidden rather than
+    baked into every template's shape.
+
+- **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). ⛔ **`bindingsDeclared` (0.3.0) THROWS** when a prop that could carry a handle
+  is neither bound nor named in `template.bindings.unbound` with its reason
+  (`{ fps: "timing" }`) — free-text and colour strings, numbers, media, one element of a
+  basic list, one leaf of json/list/array, and a regions-picker rect must all be
+  accounted for; booleans, closed sets, groups, the m0 family, code and hidden/human
+  props never are. Templates in `frozen.manifest.json` are exempt. On a rect that
+  already binds another prop the fix is `bindProps`, never a second `bindProp` — it
+  would replace the first. 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.

package/node_modules/@m0saic/knowledge/docs/templates/theming.md

@@ -0,0 +1,81 @@
+# Theming — design tokens over the upstream channel
+
+> Templates layer. How a template consumes (or produces) shared design tokens.
+> Landed in F4 (`charts/stat-card/v1` is the first consumer). The token
+> plumbing lives in `@m0saic/template-utils` (`src/theming/`); the contract in
+> `@m0saic/types`; the reference producer at `@m0saic/theming/v1`.
+
+Theming lets a **producer** template publish design tokens that any **consumer**
+template overlays onto its own constants. Producer and consumer agree ONLY on a
+token SHAPE + an alias — never on a specific producer — so any conforming
+producer is swappable under any consumer.
+
+## The three homes
+
+- **Contract** — `@m0saic/types`: `MosaicThemeTokens` (21 role-based keys:
+  `surface*` / `text*` / `accent*` / `positive` / `negative` / `grid*` /
+  `axis*` / `radius` / `dataPalette`), `MosaicThemeMode`
+  (`dark` | `light` | `high-contrast`), `MOSAIC_THEME_ALIAS` (`"theme"`),
+  `MOSAIC_THEME_TOKEN_KEYS`. Keys are ADDITIVE-ONLY (renames force a
+  re-checkpoint).
+- **Plumbing** — `@m0saic/template-utils` (`src/theming/`): `publishTheme`,
+  `readTheme`, `applyTheme` (sync — ctx-read + per-key overlay), and
+  `resolveThemeTokens` (async — find-or-seed) + `ThemeSourceConfig`.
+- **Reference producer** — `@m0saic/theming/v1`: a layered system —
+  `M0SAIC_BRAND` (reference: navy + orange) → semantic `ThemeTokens` →
+  `THEME_PRESETS` / `resolveTheme(mode)`. Publishes via `publishTheme`;
+  `preview:false` emits a data-only doc valid only as an `intermediate`
+  pipeline step.
+
+## Consumer authoring pattern (the copyable recipe)
+
+1. Declare your current constants as a full `MosaicThemeTokens` `LOCAL_THEME`
+   (used keys carry the current hexes VERBATIM → byte-identity; unused keys are
+   defensible locals, never read). Do NOT import the producer's `resolveTheme`
+   into the fallback — coupling the fallback to a producer preset risks a drift
+   that breaks byte-identity.
+2. Add an opt-in `theme?: ThemeSourceConfig` prop
+   (`{ slug?, namespace?, props?, forceFetch? }`).
+3. In `render`: `const theme = await resolveThemeTokens(LOCAL_THEME, ctx,
+   props.theme);` then read `theme.<key>` everywhere a constant was read.
+
+## The resolution model — `theme = ctx[namespace] ?? seed(slug) ?? fallback`
+
+The same one call serves both roles a template can play:
+
+- **Vanilla** (no config, or a config without a `slug`): reads the default
+  `"theme"` namespace off ctx, else `LOCAL_THEME`. Un-themed → byte-identical.
+- **Child** (nested under a producer/pipeline that published tokens): finds them
+  on `ctx.upstreamData[namespace]` → uses them. No `slug` needed.
+- **Head** (top-level, nothing upstream, `slug` configured): INVOKES the producer
+  (`renderNestedTemplate` — a BUILD-TIME doc build, NOT ffmpeg) to seed the
+  tokens, then reads them.
+- **`forceFetch`**: re-seed via `slug` even when the namespace is populated
+  (escape hatch for a namespace collision; the real fix is usually higher in the
+  chain).
+
+**Swap the theme = swap `props.theme.slug` (or its `props`)** — a data change,
+never consumer code. `applyTheme` is the sync subset (ctx-read + overlay, no
+seeding) for consumers that never self-seed.
+
+## Two hard rules
+
+- Read via `applyTheme` / `resolveThemeTokens` (which read
+  `ctx.upstreamData[alias]` through `getUpstreamBlock`). NEVER hand-read
+  `ctx.upstreamVariables` for theme.
+- `LOCAL_THEME`'s used keys = the template's current hexes, so an un-themed,
+  un-configured render is byte-identical to pre-theming. Verify with a doc
+  snapshot deep-equal.
+
+## Pipeline alternative (production path for a chain)
+
+To re-skin a whole chain, put the producer as an `intermediate: true` step ahead
+of the consumers:
+`[ @m0saic/theming/v1 preset:dark preview:false → …consumers ]`. The producer
+threads tokens downstream at zero render cost; swapping the step's `preset`
+re-skins everything. Consumers need no `slug` in this mode — they find the tokens
+on ctx as children.
+
+Reference consumer: `charts/stat-card/v1` (first `resolveThemeTokens` consumer,
+F4). See also `data-pipeline.md`
+§"Publish channels × read views" for the underlying upstream channel.

package/node_modules/@m0saic/knowledge/docs/templates/ui-controls.md

@@ -0,0 +1,150 @@
+# Template UI controls
+
+Templates declare per-prop editor controls via `meta.control` on each
+`MosaicTemplatePropDefinition`. The desktop app's prop-dispatch surfaces read those
+declarations and render the matching widget.
+
+⚠️ **If you are adding a new control kind: the dispatch is duplicated across TWO
+surfaces, and a one-surface change silently no-ops on the other.** Update both.
+(There is no `props-control-dispatch.md` yet — the writeup is still an unmerged
+candidate at (internal design history); read
+that for the two surface locations.)
+
+---
+
+## The `picker` taxonomy
+
+`MosaicPropControl.picker` is a closed union
+(https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts#L186):
+
+| Value | Renders | Prop shape |
+|---|---|---|
+| `"file"` | OS file picker | one `type: "media"` prop |
+| `"folder"` | OS folder picker | one `type: "media"` prop |
+| `"time-range"` | Single-range clip modal | **paired** `*StartMs` / `*EndMs` numbers |
+| `"time-ranges"` | Multi-range Clip-Range Studio | **one** `type: "json"` prop |
+| `"cards"` | Image-card option grid | any prop with `control.options` |
+
+`"time-range"` and `"time-ranges"` are **both current and both in use** — the plural did
+not supersede the singular. Pick by cardinality:
+
+- **One window** out of a source (trim, clip, preview segment) → `"time-range"`.
+  Adopters: `media/subtitle-burn/v1`, `language/dual-sub/v1`,
+  `media/video_to_png_sequence/v1`.
+- **N windows** (highlight reels, multi-cut) → `"time-ranges"`.
+  Adopter: `media/highlights/v1`.
+
+---
+
+## `"time-range"` — the paired-prop picker
+
+Declared on **both** halves of a `<base>StartMs` / `<base>EndMs` numeric pair, with the
+same control block on each:
+
+```ts
+clipStartMs: {
+  type: "number",
+  required: false,
+  meta: {
+    control: {
+      picker: "time-range",
+      videoFromProp: "sourceId",            // sibling prop holding the video path
+      targetDurationMsFromProp: "duration", // optional — draws a "target band"
+      markersProvider: {                    // optional — semantic timeline ticks
+        kind: "subtitles",
+        videoFromProp: "sourceId",
+        languageFromProp: "languageCode",
+        trackIndexFromProp: "trackIndex",
+      },
+    },
+    ui: { label: "Clip start (ms)" },
+  },
+},
+clipEndMs: { /* mirrors clipStartMs, label "Clip end (ms)" */ },
+```
+
+**Pairing rule.** The dispatch matches the two halves by name suffix
+(`*StartMs` ↔ `*EndMs`) via `planTimeRangeEntries`
+(the Mosaic Desktop / Web app source (not published)). Both dispatch surfaces
+call that same planner, so pair-detection cannot drift between them.
+
+**`{ 0, 0 }` means "full source"** — it is the documented cleared sentinel, not a
+zero-length range. Don't treat it as an empty selection.
+
+---
+
+## `"time-ranges"` — the multi-range studio
+
+**One** `type: "json"` prop whose value is `Array<MosaicTimeRangeMs>`
+(`{ startMs, endMs, label? }`; integer ms, source-relative, sorted ascending; overlaps
+allowed; `[]` = no selection). No prop pairing — the editor reads and writes the whole
+array in a single `onChange`.
+
+```ts
+clipRanges: {
+  type: "json",
+  required: false,
+  meta: { control: { picker: "time-ranges", videoFromProp: "sourceId" } },
+},
+```
+
+**Read the value with `parseTimeRangesValue`**
+(https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/media/timeRanges.ts) — never hand-parse. The boundary is
+deliberately permissive (see `reference/json-prop-type.md`), so the value may arrive as a
+parsed array *or* a JSON string.
+
+---
+
+## Both pickers are one component underneath
+
+The Clip-Range Studio is the single implementation; the singular picker is an adapter
+over it.
+
+| Component | Role |
+|---|---|
+| `rangestudio/ClipRangeStudio.tsx` + `ClipRangeStudioModal.tsx` | the studio |
+| `rangestudio/SingleRangeModal.tsx` | single-range adapter — the studio at `maxRanges: 1`, legacy `{startMs, endMs}` in/out |
+| `rangestudio/TimeRangesField.tsx` | the `"time-ranges"` form field, rendered by **both** dispatch chains |
+
+> **Historical note:** `TimeRangePickerField.tsx` / `TimeRangePickerModal.tsx` were
+> **deleted** in the Clip-Range Studio rebuild. `SingleRangeModal` is their drop-in
+> replacement with the same public API. Older docs, plans, and candidates that cite
+> those two filenames are stale — the *pattern* they describe survived, the files did
+> not.
+
+Consumers of `SingleRangeModal` today: `PropsSchemaForm`, `MakePage`, and
+`compose/sources/MediaSourceEditor`.
+
+---
+
+## Marker providers (declarative)
+
+`markersProvider` asks the editor to overlay semantic landmarks on the timeline. The
+union currently has **exactly one kind**:
+
+- **`kind: "subtitles"`** — extracts cues for the resolved language/track and draws them
+  as ticks with inline labels. Chain: `subtitles:extract` IPC
+  (the Mosaic Desktop / Web app source (not published)) → cue hook → `markers` on the studio. The cues are
+  also painted as a live caption overlay on the preview `<video>`, because HTML5 video
+  cannot surface embedded MKV subtitle tracks.
+
+**There is no fallback path.** A `kind` the dispatch doesn't recognize is *silently
+ignored* — no warning, no error, the markers just never appear. Adding a kind
+(`scene-cuts`, `audio-peaks`, `chapters`) means expanding the union **and** adding the
+IPC **and** the hook **and** the dispatch wiring, in lockstep.
+
+---
+
+## Companion props and gotchas
+
+**Loop mode.** A time-range pairs naturally with a loop-mode enum when the selected
+segment can be shorter or longer than the render duration. Subtitle-burn's
+`clipLoopMode: "cut" | "loop" | "freeze"` is the reference — a plain enum via
+`meta.control.options`, threaded into `MosaicPlaybackProps.loopMode` at render time.
+
+**Cue-offset trap on clipped templates.** When a template offsets cues to output-time
+(subtitle-burn's `offsetCuesToOutput(rawCues, clipStartMs, clipEndMs, durationMs)`), the
+picked range must actually overlap where cues exist — otherwise the render is silently
+subtitle-free. The marker overlay is the editor-side mitigation: users see where cues
+live and aim accordingly. Surface this on any cue-bearing template rather than burying
+it.

package/node_modules/@m0saic/knowledge/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@m0saic/knowledge",
+  "version": "0.2.0",
+  "main": "dist/index.js",
+  "license": "MIT"
+}

package/node_modules/@m0saic/momo-types/README.md

@@ -0,0 +1,109 @@
+# `@m0saic/momo-types` — Vocabulary Contract for the AI-Human Work-Session Protocol
+
+This package **is** the canonical vocabulary for how AI agents and humans collaborate on m0saic layouts. When in doubt about which word to use, this file decides — collaborators (people, agents, downstream tooling) that drift into synonyms cause real fragmentation, and adapters between half-matching APIs are the cost. Read this file once; use these nouns everywhere.
+
+## Why a separate package
+
+The vocabulary is expected to grow as the AI layer matures (new categories, new evaluation kinds, future shapes none of us have named yet). Keeping it in its own publishable package — separate from the heavy `@m0saic/momo` runtime — means:
+
+- **Any package can share the shape cheaply.** File-format layers (`@m0saic/dsl-file-formats`), tooling (`wireframe.mjs`), the desktop editor (`apps/mosaic`) — they all take a dep on `@m0saic/momo-types` without pulling in the model wrapper, tool registry, or download lifecycle.
+- **Types-only / types-mostly.** Two small pure-function helpers (`gradeFromScore`, `normalizeCandidateContext`) ship alongside the types; everything else is type-only. Zero runtime baggage.
+- **The file formats own the wire shapes.** `M0AgentMeta`, `M0AgentResponse`, `M0AgentComment`, the loose `CandidateContext` and the transport helpers (`mintAgentId`, `normalizeAgentProse`…) are defined in `@m0saic/dsl-file-formats` — this package depends on it and re-exports them with the typed `CandidateContext` refinement, so the language repo stays free of the agent protocol and nothing is duplicated.
+- **Independent release cadence.** When the protocol churns (it will), `@m0saic/momo-types` can bump versions without dragging the rest of momo along.
+
+The model is consciously chess-inspired (see `./candidate.ts` for the chess.com grade union, taken verbatim) — sessions are games, candidates are positions, evaluations are annotator marks, scoring is the engine eval.
+
+---
+
+## Canonical noun set
+
+| Noun | Meaning | Lives in |
+|---|---|---|
+| **session** | A chronological directory of candidates exploring one problem. The "game" in the chess analogy. | `session.ts` |
+| **candidate** | One `.m0` (or `.m0c`) file inside a session. The "position / move". | `session.ts`, `candidate.ts` |
+| **intent** | What the writing party is *trying* to accomplish (per-candidate prose + optional closed-union verb). | `category.ts` |
+| **category** | What *class* of layout problem this session is solving. Closed union + `other` escape hatch. | `category.ts` |
+| **layout-intent** | The structural kind of a candidate's geometry (grid / comparison / spotlight / …). Picked by the scorer's caller. | `scoring.ts` |
+| **grade** | Categorical evaluation of a candidate (chess.com vocab, verbatim). Rank order (strong → weak): `brilliant` ▸ `great` ▸ `best` ▸ `excellent` ▸ `good` ▸ `inaccuracy` ▸ `mistake` ▸ `blunder`. Plus `book` (known canon), `miss` (human-only judgment), `unevaluated`. **Note:** `best` means "engine's top pick" — `brilliant` and `great` rank *above* it. | `candidate.ts` |
+| **score** / **breakdown** | The numeric automated quality signal from `scoreLayout`. `breakdown` is the per-metric view. Types here; values + scoring function in `@m0saic/momo/scoring`. | `scoring.ts` |
+| **evaluation** | The grade assignment for one candidate — `grade` + optional `breakdown` + provenance. | `candidate.ts` |
+| **annotation** | Any structured note attached to a candidate (a `RegionAnnotation`, a comment, a relation). | `region.ts`, `agent/meta.ts` |
+| **region** | A labeled sub-area of the geometry, keyed by stableKey. | `region.ts` |
+| **relation** | Lineage between candidates (`refines`, `branches-from`, `rejects`, …). | `candidate.ts` |
+| **party** | Anyone who can speak in the thread — `human`, `human:<name>`, `agent:<id>`. | `party.ts` |
+| **phase** | Tripartite session arc — `scaffolding` / `refining` / `finalizing`. Mosaic analog of chess opening/middlegame/endgame. | `session-summary.ts` |
+| **summary** | Per-party + per-phase stats across a session. Renders as the Game Review board on the post-mortem template. | `session-summary.ts` |
+| **corpus** | The union of all sessions across all sandboxes — the "book". | (concept; no type) |
+
+---
+
+## Banned synonyms
+
+When tempted to use the left, use the right.
+
+| Don't use | Use instead | Why |
+|---|---|---|
+| *background* | **context** | The `M0AgentMeta.context` field is the carrier; "background" is the same idea in different syllables. |
+| *prompt* | **question** | `M0AgentMeta.question` is the specific ask field; "prompt" is overloaded with LLM-prompt-engineering jargon. |
+| *attempt* | **candidate** | A candidate is one file (the position). Calling it an "attempt" loses the chess analogy. |
+| *iteration* | **session** OR **candidate** | Pick one — an iteration is *either* the whole session you went through *or* the next candidate you produced. Don't conflate. |
+| *rating* / *quality* (numeric) | **score** | `ScoreBreakdown.total` is "score". Use "rating" only for the per-session Elo-style number in `PartySummary.rating`. |
+| *grade* | **(only for the categorical thing)** | Grade is `brilliant` / `mistake` / `blunder` — the categorical chess mark. Don't write `grade` when you mean `score`. |
+
+---
+
+## The two orthogonal axes (read carefully)
+
+`LayoutIntent` and `SessionCategory` are the most-confused pair. They are **NOT the same thing**; they live on different axes of the same candidate.
+
+- **`LayoutIntent`** (`../scoring`) — *structural* kind of the layout. `grid`, `comparison`, `spotlight`, `magazine`, `ranked-list`, `free`. Picked by the scorer's caller so `scoreLayout` uses the right weight row.
+- **`SessionCategory`** (`./category.ts`) — *kind of exploration* the session is performing. `spacing-alignment`, `hierarchy-emphasis`, `scaffold-from-scratch`, etc. Picked by the human or agent to classify what the iteration is FOR.
+
+### Worked example
+
+A user is iterating on the bar-graph template. They have a working 5-bar grid that feels visually cramped. They open a session to refine it:
+
+- `SessionCategory`: `{ kind: "known", value: "spacing-alignment" }` — the session is exploring how to fix the cramped feeling.
+- Each candidate's `layoutIntent`: `"grid"` — the geometry stays a grid throughout; only its gutters and weights vary.
+
+The two axes co-vary in principle (a `spacing-alignment` session usually keeps `layoutIntent` constant across candidates because the geometry is what you're refining), but they're recorded independently because they answer different questions.
+
+---
+
+## Engine eval vs. annotator mark (the chess analogy is load-bearing)
+
+A chess game has BOTH the engine's centipawn score (numeric, machine-computed) AND the annotator's `?!` (categorical, human-applied). They don't replace each other — they're shown side-by-side in any decent game review.
+
+Same here:
+
+- `breakdown.total` (number, 0..1) — the **engine eval**. Cheap, deterministic, available on any candidate.
+- `evaluation.grade` (one of `brilliant` / `great` / … / `blunder`) — the **annotator mark**. Canonical; the human's selected answer.
+
+When they disagree, the human wins — and the disagreement itself is interesting. The post-mortem template surfaces those moments because they're exactly where learning lives.
+
+`gradeFromScore()` in `./candidate.ts` provides one auto-derivation path (use it for pre-fills); the human can always overwrite. **The automated grader caps at `best`** — it never returns `brilliant` or `great`, because those require insight (sacrifice, critical-moment recognition) an automated metric can't see. Same for `book` and `miss`. Those four grades are reserved for humans to award when they spot something the score didn't.
+
+---
+
+## Shared, not mirrored
+
+This package's types are the **single source of truth**. `@m0saic/dsl-file-formats` and `@m0saic/momo` both take a workspace dep on `@m0saic/momo-types` and import the shapes directly — no parallel declarations, no CI lint to keep mirrors in sync.
+
+(One holdover: `M0AgentMeta` itself remains mirrored between `@m0saic/momo` and `@m0saic/dsl-file-formats` — that struct predates this package and is stable enough that collapsing it isn't worth the churn.)
+
+---
+
+## Coexists with: scoring values in `@m0saic/momo/scoring`
+
+Scoring is **split** across the two packages:
+
+- **Types** (`ScoreBreakdown`, `LayoutIntent`, `ScoreInput`, `ScoreComponent`, `ScoreComponentKey`) live here in `./scoring.ts`.
+- **Values + logic** (`WEIGHTS`, `THRESHOLDS`, the `scoreLayout` function, quality curves) live in `@m0saic/momo/scoring`.
+
+`@m0saic/momo`'s `WEIGHTS` uses `satisfies Record<LayoutIntent, WeightTuple>` so the runtime constant and the type union stay in lockstep — adding a new intent requires editing both, with the type-check enforcing the consistency.
+
+---
+
+## Open: starter category enum
+
+The nine `KnownCategory` entries in `./category.ts` are the Plan-agent's best guess. They'll get refined once the user has driven enough real sessions to know which buckets are over/under-represented. Promote new patterns from `{ kind: "other", label: "X" }` to first-class after a label recurs ~3 times across sessions.