@m0saic/knowledge 0.2.0

package/docs/handbook/m0-construction-methods.md

@@ -0,0 +1,201 @@
+# m0 construction methods — the all-up map
+
+> Every way to produce an m0 string, on one page. **Two questions pick the method;
+> four currencies price it.** This is an index — each row links to the canonical
+> treatment. Companions:
+> [`feasibility-precision-quantization.md`](feasibility-precision-quantization.md)
+> (per-split math, §3a/§3b pairwise choices),
+> [`composition-arithmetic.md`](composition-arithmetic.md) (nesting math),
+> [`precision-tiers.md`](precision-tiers.md) (head vs primitive),
+> https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/GCD.md (the encoder story), and https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/API.md +
+> https://github.com/m0saic-dsl/m0/blob/main/https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/.ai/method-catalog.md (signatures / per-method docs).
+
+---
+
+## 0. The two questions
+
+1. **Who owns the canvas?** (the MODE, feasibility §3c) — a nestable **primitive**
+   must stay RATIO; a **head** that owns its render target may go ABSOLUTE; a baked
+   pixel-animation asset is BITMAP (bake once, reference forever).
+2. **What shape is the content?** — proportional regions · uniform grid · one exact
+   rect · many exact rects · curves/shapes · imported geometry · an existing m0 to
+   edit.
+
+Answer both before touching a builder. Mode mistakes are the expensive ones —
+laundering ABSOLUTE into fine RATIO is the §3c anti-pattern that silently drops
+nested content.
+
+---
+
+## 1. The four currencies
+
+Every method pays for geometry in some mix of:
+
+| currency | what it costs | where it shows |
+|---|---|---|
+| **slots** | m0 chars + precision floor | the string itself; `computePrecisionFromString` |
+| **drift** | visual px moved off-target | the render; arithmetically CLEAN cells (composition-arithmetic §3) |
+| **fiber** | nothing structural — inset / cell-local masks / xExpr | invisible to the m0; leaf-only; previews must read `placement` |
+| **layers** | overlay depth | graph cost; the ~25-mask cliff (engine wall W3, internal doc) |
+
+A method is a fixed exchange rate among these. The recurring trade: exact-pixel
+truth costs **slots**; you buy them back with **drift** (visual error), **fiber**
+(shrink-room + transparency required), or **layers** (graph depth).
+
+---
+
+## 2. The map
+
+### 2a. Proportional — RATIO (resolution-independent, nests)
+
+| method | shape | notes |
+|---|---|---|
+| `weightedSplit` (+ `equalSplit`, `container`, `weightedTokens`, `strip`) | authored proportional regions | auto-GCD-reduced; quantizes when basis ∤ axis (feasibility §3); the default |
+| `grid` | uniform cells, ratio gutters | `MIN_PX_PER_WEIGHT = 4` auto-scale; for a GAPPED grid go **gutterless + `latticeCellInset`** — gap in the fiber, see construction-strategy's grid recipe (`gridCellInset` is deprecated: approximate) |
+| `safeCanvas` / `snapGridFit` / `snapGridFind` / `snapGridEnumerate` / `aspectSafeGrid` | design-time canvas/grid search | quantization-free dims; ranking; landscape↔portrait pairs |
+| `goldenSplit` / `goldenSpiral` | φ compositions | Fibonacci weights = the optimal bounded-basis approximants of φ (composition-arithmetic §7) |
+| `spotlight` / `comparison` / `rankedList` | opinionated presets | sugar over weighted splits |
+| template-local kits (`rowSplit`/`colSplit`/`insetNode` in alpine `_shared`, dsl-tutorial `node-kit`) | per-pack sugar | NOT published; **`insetNode` is the §3b trap** — its margins are real cells that quantize INTO the placed rect; never use it for must-be-exact elements |
+
+### 2b. Exact-pixel — ABSOLUTE (resolution-baked; head-only unless laundered)
+
+| method | shape | pays | notes |
+|---|---|---|---|
+| `aspectFit` | letterbox an aspect | slots | exact frame + null margins |
+| `placeRect` | ONE exact rect | slots | null-tile margins, multi-resolution-safe (§3b); `goldenRect` wraps it |
+| `placeRects` | MANY exact rects | slots (+ layers on overlap) | band decomposition + `importance` z-packing; exact at its canvas (§3a) |
+| `snapRectPrecision` | one rect, near-exact | drift | Pareto frontier of nearby low-precision rects; the single-rect GCD-snap |
+| `placeOptimizedRects` / `placeOptimizedPieces` (template-utils) | many rects, near-exact | drift | per-rect `driftPx` budgets, `0` = LOCK exact; zero-drift ⇒ byte-identical to `placeRects` |
+| `placeInsetRects` / `placeInsetPieces` (template-utils) | many rects, exact content in coarse cells | fiber (+ layers on overlap) | divisor-pitch cells + half-pixel-centered inset recovery: **zero drift** at bounded precision; needs transparent-margin leaves + shrink room; `onHostile: "exact"` for runtime primitives (prime dims degrade to exact, reported). Exemplar: `alpine/stat-card/v1` |
+
+### 2c. The launder ladder — making ABSOLUTE content composable
+
+**This is the canonical enumeration** (per-rung mechanics, constraints, and
+measured numbers live in
+[`feasibility-precision-quantization.md`](feasibility-precision-quantization.md)
+§3c, which references these rung numbers). In preference order — stop at the
+first rung that fits:
+
+1. **Restructure into nested ratio splits** — no helper, no cost (all six alpine
+   rebuilds landed here). Includes canvas-adaptive re-layout: a template is
+   `(props, canvas) → m0`, so at a size that would quantize, return a DIFFERENT
+   ratio m0 that divides cleanly.
+2. **Decouple thin features from the basis** — thin lines only: fixed-px strips
+   at proportional overlay offsets instead of an interleaved `[gap,line,gap,…]`
+   split (`primitives/grid/v2`); N shallow mask-free overlays, nests into any
+   cell.
+3. **Ratio grid + gap-as-`latticeCellInset`** — uniform grids; never drift a grid
+   (unequal cells), never `placeRects` per cell.
+4. **Mask-in-a-cell** — curves/charts/rings: marks are masks filling ONE ratio
+   cell in cell-local coords; registration is free because they share the cell.
+5. **`placeInsetRects` / `placeInsetPieces`** — independent rect soups with
+   transparent margins and gaps ≥ pitch−1: zero drift, bounded precision
+   (stat-card ships on this rung).
+6. **`placeOptimizedRects` drift** — when inset-recovery doesn't apply: container
+   edges, cell-painting tiles, wanted-snap (pixel-aligned strokes), or mixed
+   soups needing per-rect LOCKS.
+7. **Self-framed coarse-quantize** — many-mask soups over the ~25-mask cliff:
+   own P-divisible frame, outward bbox snap, ratio letterbox (≤1px uniform
+   translation).
+8. **Honest ABSOLUTE at the head** — the element owns its canvas and never nests
+   (pulse beats). Legitimate; just keep it out of `primitive`-role templates
+   (the audit slope catches violations).
+
+**Verify the rung held.** Tag the placed sources with LABELS and declare
+canvas-independent ratio invariants (aspect / fraction / `within` / **presence**,
+incl. through nesting) via the **layout contract** — `checkLayout` is the pure
+evaluator a layout search loops on, and `npm run audit:layout-envelope` reports
+the canvas range where each holds. The emitter round-trip guard
+(`audit:geometry-matrix` / `audit:geometry-proof`) additionally locks a
+zero-drift placement. Resolve-only, opt-in. See
+[`../templates/construction-strategy.md`](../templates/construction-strategy.md)
+"Verifying layout intent survived".
+
+### 2d. Import & generate (content → m0)
+
+| method | source | notes |
+|---|---|---|
+| `svgToM0` / `enumerateSvgToM0` / `rectsToM0` (+ `parseSvg`, `extractGeometry`, `inferGrid`) | SVG / pixel-rect sets | packing + gcd-snap drift modes; the GCD.md story; emit variants and `compareM0` them |
+| `qrToM0` / `barcodeToM0` / `binaryGridToM0` + pixel-art family | codes / bitmaps | **BITMAP mode** — bake to an asset, never live-compose |
+| `generateMasks` / `circleMask` / `roundedRectMask` / `pillMask` / `toLocalPath` | shapes | fiber, not m0 — mask sidecars + cell-local paths |
+
+### 2e. Re-emission (m0 → m0)
+
+| method | job |
+|---|---|
+| targeted transforms (`split`, `replace`, `addOverlay`, …) + `pipe`/`compose`/`withHistory` | edits that preserve StableKey identity |
+| `reduceSplitCounts` | per-split GCD tidy, drift-budgeted (default lossless) |
+| `compactLossless` / `compactDocument` | closeout: null-layer removal, growth-guarded repack, optional gcd drift |
+| `rebuildRects` | post-render geometry edits — always rebuilds, resolution-baked |
+
+**Rule:** when identity must survive (saved docs, `_humanedits`), EDIT the existing
+m0 — never regenerate from scratch.
+
+### 2f. Not-a-builder — the fiber
+
+Sometimes the answer is no m0 at all: `placement.inset` (`latticeCellInset`, the
+`placeInsetPieces` recovery), cell-local mask paths, `xExpr`/`yExpr` offsets,
+cell-local text. Zero chars, zero precision, leaf-only, invisible to structure —
+and *unable* to break composition (composition-arithmetic §4). If nothing else
+needs to see the geometry structurally, put it in the fiber.
+
+> **The inset fiber now has a persisted file-format home.** `placement.inset`
+> is promoted to a first-class, stableKey-keyed `insets` field on `.m0c` /
+> `.m0p` (per-edge fractions; resolved projection of the `MosaicBoxFrac`
+> superset), so the recovered rect survives to the file, is painted as a cyan
+> inner box in Layout, and is editable per-edge in the inspector + File
+> Details. See `file-formats/m0p-and-custom-field.md` §4. It's still fiber —
+> zero m0 chars — just no longer invisible to the editor.
+
+---
+
+## 3. Pairwise discriminators (the recurring confusions)
+
+- **`weightedSplit` vs `placeRects`** → feasibility §3a. Portable proportions vs
+  baked exactness; clean proportions cost the same either way.
+- **`placeRect` vs `placeRects`** → count (§3b). More than a couple of rects →
+  plural (layer packing is the real win).
+- **`snapRectPrecision` vs `placeOptimizedRects`** → one rect (with a Pareto
+  frontier to choose from) vs many (with per-rect budgets/locks).
+- **`placeInsetRects` vs `placeOptimizedRects`** → where BOTH apply (independent
+  transparent-margin leaves, gaps ≥ pitch−1) inset-recovery dominates (zero
+  drift). Drift remains RIGHT for: per-rect LOCKS, container edges, tiles that
+  paint their whole cell, wanted-snap (strokes, butt-joint cell edges). Both
+  degrade identically on hostile prime axes (pitch → 1, exact).
+- **`grid` vs anything-per-cell** → never place grid cells individually; grids
+  are one ratio structure + fiber gaps.
+- **mask-in-a-cell vs self-framed quantize** → count the masks: one shared cell
+  until the ~25-mask cliff; past it, self-frame with `placeRects` layer-packing.
+- **`insetNode` vs `placeRect`** → §3b: insetNode margins quantize INTO the rect;
+  placeRect null margins never claim space.
+
+---
+
+## 4. The decision playbook (in order)
+
+1. **Mode first.** Primitive → RATIO only (rungs 1–7 of the ladder). Head →
+   ABSOLUTE allowed (rung 8). Pixel animation → BITMAP, baked.
+2. **Shape second.** Proportional regions → `weightedSplit`. Uniform grid →
+   `grid` gutterless + `latticeCellInset`. One exact element → `placeRect`. Many
+   exact rects → `placeRects` (head) or the launder ladder (primitive).
+   Curves/shapes → masks in a shared ratio cell. Import → §2d. Existing m0 → §2e.
+3. **Price it.** Split counts from `divisors(axis)`, 5-smooth, basis ≤ 120 for
+   family portability (composition-arithmetic §1–§2). Layers under the cliff.
+4. **Measure, don't guess.** `evaluateM0` / `compareM0` / `quantizationSpread` at
+   ≥ `recommendedMin`; generators should emit 2–3 candidates and compare.
+
+---
+
+## See also
+
+- [`feasibility-precision-quantization.md`](feasibility-precision-quantization.md) —
+  §3a/§3b/§3c: the pairwise choices and the per-rung launder detail this map
+  routes between.
+- [`composition-arithmetic.md`](composition-arithmetic.md) — why the routing works
+  (currencies, hereditary quantization, the lattice math).
+- [`precision-tiers.md`](precision-tiers.md) — head/primitive.
+- [`../templates/construction-strategy.md`](../templates/construction-strategy.md) —
+  authoring-side application (the recipe subsections).
+- https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/API.md / https://github.com/m0saic-dsl/m0/blob/main/https://github.com/m0saic-dsl/m0/blob/main/packages/dsl-stdlib/.ai/method-catalog.md — signatures and
+  per-method agent docs.
+- https://github.com/m0saic-dsl/m0/blob/main/packages/dsl/GCD.md — the import-path compression story.

package/docs/handbook/precision-tiers.md

@@ -0,0 +1,84 @@
+# Precision tiers — light primitives, precise compositions
+
+**The rule.** Precision and complexity belong to HIGHER-LEVEL constructs, not the
+base. Keep base-level primitives (a card, a row, a badge, a table) small and
+simple — mostly **general grid positioning** via coarse proportional splits.
+A complex base makes every composition that nests it ultra-complex (the cost is
+multiplicative: one heavy primitive × N instances × M beats).
+
+**How to author light:**
+- Build primitives with the split kit (`rowSplit`/`colSplit`, basis ≤ ~120) and
+  proportional weights — NOT pixel-exact `placeRects`. Snap height weights to a
+  small multiple (e.g. 8) so nested splits GCD-collapse + stay quantization-feasible.
+- A primitive must render fine at SMALL px (it'll be nested into a cell) without
+  blowing up the parent's m0 string.
+- The primitive/head split IS the **RATIO/ABSOLUTE mode choice**: a primitive stays
+  RATIO so it nests (proportional splits, or fixed-px features at proportional offsets
+  for thin lines — never a per-pixel `placeRects` basis, which silently drops when
+  nested); a head may go ABSOLUTE since it owns its canvas. See the three drafting
+  modes in [`feasibility-precision-quantization.md` §3c](feasibility-precision-quantization.md).
+
+**The sandbox-loop exception (and the discipline around it):**
+- You MAY author at HIGH precision (exact-px `placeRects`, fine silhouettes) while
+  iterating WITH the human in the sandbox loop — precise rects make the geometry
+  conversation concrete.
+- But COMPRESS the result before it becomes the primitive: run Compact (null/repack/
+  prune) + a GCD reduce. The silhouette's exact px is scaffolding; the shipped
+  primitive is the compressed layout.
+- **Minor positional DRIFT to achieve sufficient GCD collapse is very worthwhile** —
+  trading a few px of exactness for a big drop in cell count / DSL size is the right
+  call for a base-level item. (Precision you can't perceive at the primitive's render
+  size is precision not worth paying for.) How much drift? See the search below.
+
+## GCD-collapse search — find the collapse point, don't guess a drift
+
+Reducing a pixel-exact layout to a light one is a **SEARCH, not a setting**. Let the
+grid drift by a small tolerance so nearby weights share a common divisor; once they
+do, splits GCD-collapse and the m0 string shrinks dramatically.
+
+1. Sweep the drift tolerance from ~0 upward in small steps (0.1%, 0.2%, … to ~2%).
+2. At each step, re-quantize (Compact / GCD-reduce) and measure the resulting
+   **m0 string length**.
+3. The curve is **NON-MONOTONIC**: small drifts give small wins (5–6%), length can
+   even rise — then at one value it **collapses** (typically 70%+ smaller). That's
+   the collapse point.
+4. Take the smallest drift at the collapse — minimum drift for maximum collapse.
+
+The collapse drift is layout-specific (it depends on the weights' near-common
+divisors) and the win is discontinuous, so **no fixed default is right** — 0.5% may
+do nothing for one layout and 70% for another. Always sweep. Measured exemplar: the
+contributor-table grid went ~14K → ~6K chars at ~0.5% (Mosaic Desktop: Layout →
+Compact, sweep the drift-tolerance knob and read the length).
+
+Programmatic routes (these automate the sweep — reach for them before hand-sweeping):
+`snapRectPrecision` returns a **Pareto frontier** (drift vs precision — the swept
+curve, precomputed), `placeOptimizedRects` reports per-rect `driftPx`, and
+`reduceSplitCounts` takes an explicit drift budget (all in `@m0saic/dsl-stdlib`).
+Open questions (capture findings here): per-layout collapse signatures, automated
+collapse-point detection, whether a second collapse exists higher up.
+
+**Where precision IS warranted:** the composition / hero layer — where exact
+alignment across panels reads, and the cost isn't multiplied downstream. Even
+there, prefer baking a constant precise subtree to a flat asset (see
+`../runtime/reduce-to-one.md`) over carrying it live.
+
+## Cost model — where high-precision DSL actually costs
+
+A long, high-precision m0 is **NOT expensive to render** — the engine parses
+arbitrary-length DSL cheaply at render time. The cost lands in exactly two places,
+and that's what sets the tier:
+
+1. **Composition** — a primitive is nested N× inside higher constructs, so a heavy
+   primitive multiplies. Keep primitives LIGHT (coarse splits / GCD-collapse /
+   `placeRects` packing).
+2. **The editor** — Mosaic Desktop materializes rects as **React DOM objects**, so a
+   high rect count bloats the editor DOM. Anything a human edits wants a modest rect
+   count.
+
+So: **primitives → keep DSL low** (they compose AND get edited). **Hero /
+intended-final-output templates → full precision/resolution is FAIR** — the geometry
+is derived from the hero's own inputs, it's designed for its render resolution, it
+isn't nested into anything else, and DSL length is cheap to parse at render. Don't
+contort a hero to shave bytes; do contort a primitive. Pin must-be-exact elements
+with `placeRect` / `placeRects` in EITHER tier (see the resolution-safe escape hatch
+in `feasibility-precision-quantization.md`).

package/docs/m0saic-thesis.md

@@ -0,0 +1,95 @@
+# The m0saic Thesis — read this first
+
+> Max-importance. This is the *why* behind every other doc. When a design choice
+> is unclear, return here. The Handbook is canonical for *grammar*; this is
+> canonical for *intent*.
+
+## The product IS m0
+
+m0saic is not "a tool that happens to use a DSL." **The product IS the m0 string.**
+Everything — templates, the engine, Make, Layout, Render Hero, the corpus —
+revolves around producing, inspecting, and rendering one string.
+
+## Everything is rectangles on a canvas
+
+This is a mental change, and it's the whole change. m0saic does exactly one thing:
+
+> **Place arbitrary rectangles within a canvas, and render content inside them.**
+
+Once you adopt it, every visual problem dissolves into the same shape — a title,
+an axis label, a gridline, a chart line, a KPI card, a glyph, a video tile: all
+of it is **rectangles on a canvas**. There is no other primitive. What varies is
+only what you do with a rect:
+
+- **Fill it** — put pixels in the rect, from *any* source: a solid color
+  (lavfi), an image or video (media), a nested template (mosaic), a mirrored
+  cell (ref), rendered text, … The source type varies; the act is identical —
+  **pixels into a rect.** (The data-fetcher source is the one exception: it
+  supplies *data* for other sources to render, not pixels of its own.)
+- **Mask it** — a shape carved inside the rect (inline-mask path).
+- **Reveal it in order** — animate a set of rects (overlay alpha / draw-on).
+- **Rank / set it** — proportion or arrange rects by weight, grid, or placement.
+
+It is **always** rectangles on a canvas. If you're reaching for anything else
+(drawtext positioning, `size`/`fit` scaling, a full-frame source standing in for
+a small element), you've stepped off the thesis — step back on. The answer to
+almost every "how do I render X here" is: **carve a rect sized exactly to the
+bounds, then fill or mask it.**
+
+## Embrace complexity in m0 — don't fear it
+
+The instinct to keep the m0 string "small" or "readable" is wrong. **We do not
+fear complexity in the m0 string — we embrace it.** Pushing all complexity *into*
+the string is precisely what keeps everything downstream simple:
+
+- **One source of truth.** All complexity lives in a single string. The document,
+  the render, the preview, the corpus entry — all derive from it. Nothing is
+  hidden in source code, in `xExpr` math, or in a mask pretending to be a layout.
+- **Unambiguous + deterministic.** The same m0 string is *always* the same
+  geometry, byte-for-byte. No hidden state, no time-dependence, no surprises.
+- **Inspectable.** Because the geometry is *in* the string, the DSL view, the
+  structure preview, Render Hero, and selection all just work. A layout that
+  bakes its geometry into pixels or source code is invisible to all of them.
+
+A 78-overlay "renders right but carries no geometry" template is the failure
+mode. A frame tree of hundreds of real cells — even thousands — is the success
+mode, even when the string is enormous.
+
+## There is effectively no upper limit
+
+Do not cap the geometry out of fear of string size. **m0 strings of millions of
+characters have been tested and parse fine.** Length is not a constraint — nest,
+split, place, and stack as much as the design needs.
+
+## Agents: use the DSL — it is the point
+
+Agents have been **far too shy about using the DSL.** Reaching for a full-frame
+source, a `drawtext` position, or a `size` expression to dodge "complex" geometry
+is dodging the entire point of the program. Lean in:
+
+- Translate JS pixel-math into **real m0 cells**, not baked pixels.
+- When you need a thin/short/precise element, **carve the cell** — don't scale a
+  source to fake it.
+- Reuse primitives (the `@m0saic/primitives/grid/v2` template; the `weightedSplit`
+  and `placeRects` stdlib builders) — they exist to emit geometry so you don't
+  hand-roll donation runs. (grid v1 is deprecated — nested, its basis silently drops.)
+- A big, exact, fully-geometric m0 string is the goal, not something to minimize.
+
+## Operational corollaries (where this gets concrete)
+
+- **The grammar itself** (start here to understand the m0 string):
+  [`handbook/dsl-rules.md`](handbook/dsl-rules.md) — the exact surface grammar,
+  semantic rules, and validation invariants of the m0 DSL. Canonical.
+- **The geometry math** (feasibility, precision, quantization, GCD — the absolute
+  math behind balanced layouts):
+  [`handbook/feasibility-precision-quantization.md`](handbook/feasibility-precision-quantization.md).
+- **Template construction:** `docs/templates/construction-strategy.md`
+  — the Rect Thesis, the Real-Geometry Hard Rule, the size-expr smell test.
+- **Spatial vs temporal:** `docs/templates/philosophy-and-contract.md`
+  (§"Document vs pipeline") — geometry is the document; time is the pipeline.
+  Keep the algebra pure.
+- **Determinism + DSL integrity:** the agent contract (the maintainers' agent contract §9 (not published)) and
+  the Handbook (canonical grammar). Verify every string with `validateM0String`.
+
+> If you remember one sentence: **everything is rectangles on a canvas, all
+> complexity lives in the m0 string, and that is a feature — so use it fully.**

package/docs/runtime/README.md

@@ -0,0 +1,17 @@
+# runtime/ — CLI usage & author-facing render guidance
+
+The public runtime shelf. Deep engine internals (the W1–W12 ffmpeg walls, the
+executable cost model, the mosaic-vs-ffmpeg responsibility model, audio wiring)
+are **engine-internal** — `.ai/moat/runtime/` (absent in the shipped copy). The
+author-facing consequences of those internals are already distilled into
+[`../templates/patterns/perf-authoring-rules.md`](../templates/patterns/perf-authoring-rules.md),
+which stands alone.
+
+- [`cli-usage.md`](cli-usage.md) — rendering with the CLI: 14 commands (12
+  public + 2 dev-gated) plus `telemetry`, routing (template id / `.mosaic` /
+  `.mosaicx` / inline DSL), the `make` flag surface.
+- [`ffmpeg-expression-limits.md`](ffmpeg-expression-limits.md) — the
+  `av_expr_parse` ~100-term recursion cliff that masquerades as OOM, and the
+  public mitigation (`platform/ffexpr` chain rebalancing).
+- [`reduce-to-one.md`](reduce-to-one.md) — complexity pushdown: nest a complex
+  subtree as a child doc, then bake constant subtrees to flat assets.