m0saic 0.2.1 → 0.3.0

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

@@ -0,0 +1,169 @@
+# The `"json"` prop type + typed-output templates
+
+Two additive capabilities that unblock structured-config props and typed
+data-fetcher templates. Both are **shipped and current** — verified against
+https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/template/template.ts, https://github.com/m0saic-project/m0saic-packages/blob/main/packages/template-utils/src/template,
+and `validateTemplateProps`.
+
+---
+
+## 1. `type: "json"`
+
+`"json"` is a member of `MosaicTemplatePropType`, alongside the string / number /
+boolean / media / structural (`group`, `list`) and m0-family (`m0`, `m0c`, `m0p`)
+entries.
+
+### When to reach for it
+
+Use `"json"` when a prop's value is a **structured object or array that maps to a
+TypeScript interface**:
+
+- `filter` / `sceneFilter` — a remote API's filter input passed wholesale
+- `{ low, high, mode }` clip-duration configs
+- `Array<MosaicTimeRangeMs>` — the multi-range clip seam (see §3)
+- Per-tile decoration bundles
+
+**Don't** use it for:
+
+| Instead of `"json"` | Use |
+|---|---|
+| a primitive that merely *looks* like JSON stringified | `"string"` / `"number"` / `"boolean"` |
+| an array of primitives | `"string[]"` / `"number[]"` |
+| a media reference | `"media"` |
+| a fixed set of named sub-fields you want as individual controls | `"group"` with `fields` |
+
+That last row is the common mistake: a `"group"` **without** `fields` degrades to a
+raw JSON bag in the editor, which is strictly worse than declaring `"json"` on
+purpose.
+
+### Validator behavior — permissive by design
+
+`validateTemplateProps` accepts **any non-undefined value** when `type === "json"`.
+The engine boundary does not parse, shape-check, or reject. That is deliberate:
+editors may deliver an already-parsed object *or* a raw JSON string, and both are
+legal at the boundary.
+
+**Consequence for template authors:** render-time parsing and shape-checking is
+**your** job. Call `JSON.parse` if the editor handed you a string, then validate
+however you like (Zod, Ajv, hand-rolled). Do not assume you received an object.
+
+There is intentionally no `JSON_PROP_SCHEMA_MISMATCH` diagnostic. If shape drift
+becomes a recurring failure mode, wiring one up would be additive.
+
+### `meta.constraints.jsonSchema` — an editor hint, never a gate
+
+Optional, two forms:
+
+| Form | Meaning |
+|---|---|
+| `{ ref: "<host-resolved-id>" }` | Points into a shared JSON-schema registry the host owns. Use when several templates share a payload shape. |
+| inline `Record<string, unknown>` | A JSON-Schema-ish object describing the payload. |
+
+Editors that understand the schema may render a structured form; those that don't
+fall back to a plain code editor. **The engine never validates this field.**
+
+### ⚠️ `as never` is NOT required — and existing casts are stale
+
+Several shipped templates write `type: "json" as never`
+(`charts/bar-graph/v1` + `v2`, `charts/line-chart/v1`, `internal/bars-stack`). **The
+cast is unnecessary.** Those are leftovers from before `"json"` joined the union.
+
+`definePropsSchema<P>` is typed as `Record<keyof P, MosaicTemplatePropDefinition>` —
+it constrains only the *key set*, never the relationship between a prop's TS type and
+its declared `type`. So this compiles clean, no casts:
+
+```ts
+type P = { barColor?: string | string[]; spec: Record<string, unknown> };
+
+const propsSchema = definePropsSchema<P>({
+  barColor: { type: "json", required: false },
+  spec:     { type: "json", required: true },
+});
+```
+
+(Verified 2026-07-26 with the repo's own `tsc -p https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/tsconfig.json.)
+`brand/qr-stamp/video/v2` (`luminanceBuckets`) is the correct, cast-free reference.
+
+**Do not copy the `as never` pattern into new templates**, and drop it opportunistically
+when you touch one of the offenders. The same goes for the neighbouring
+`type: "group" as any` casts — check whether they're still load-bearing before
+propagating them.
+
+---
+
+## 2. The 5-generic `defineMosaicTemplate`
+
+`MosaicTemplate` has carried 5 generics for a while; the helper now matches:
+
+```ts
+defineMosaicTemplate<
+  P extends MosaicTemplateProps,
+  O extends MosaicTemplateOutputs         = MosaicTemplateOutputs,
+  U extends MosaicTemplateUpstreamVariables = MosaicTemplateUpstreamVariables,
+  D extends MosaicTemplateUpstreamData    = MosaicTemplateUpstreamData,
+  S extends MosaicTemplateSidecars        = MosaicTemplateSidecars,
+>(template: MosaicTemplate<P, O, U, D, S>): MosaicTemplate<P, O, U, D, S>
+```
+
+Defaults preserve full back-compat — every existing 1-generic call site still
+compiles unchanged.
+
+**Use the full form when** your template (1) publishes typed outputs via
+`outputsSchema`, (2) publishes typed sidecars via `sidecarsSchema`, or (3) reads
+`ctx.upstreamData.<alias>` and wants type-checked access. Otherwise stay on
+`defineMosaicTemplate<P>` — it remains the recommendation for ordinary renderables.
+
+### Gotcha — don't narrow `U` / `D` to an empty shape
+
+A fetcher that reads no upstream is tempted to tighten `U` / `D` to
+`Record<string, never>`. **Don't.** `registerTemplate` accepts only the loose form
+(`Record<string, unknown>`), and narrowing reverses contravariance — TS rejects the
+registration.
+
+Pass the loose defaults explicitly for `U` and `D`; tighten only `O` and `S`.
+Consumer templates that *do* read upstream are the right place to tighten `U` / `D`,
+because there the context is an **input** to the bound, not an output.
+
+```ts
+export const RepoFetcher = defineMosaicTemplate<
+  Props,
+  Outputs,
+  MosaicTemplateUpstreamVariables,  // loose — narrowing breaks registerTemplate
+  MosaicTemplateUpstreamData,       //   (contravariance)
+  Sidecars
+>({
+  id: asTemplateId("@example/github/repo-fetcher/v1"),
+  role: "data-fetcher",
+  capabilities: { tier: "capability", caps: { net: { fetch: true } } },
+  propsSchema: {
+    apiUrl:   { type: "string", required: true },
+    tokenRef: { type: "string", required: false },
+    filter: {
+      type: "json",
+      required: false,
+      meta: { constraints: { jsonSchema: { ref: "@example/repo-filter/v1" } } },
+    },
+  },
+  defaultProps: { apiUrl: "https://api.github.com" },
+  async render(props, ctx) { /* … */ },
+});
+```
+
+---
+
+## 3. Cross-references
+
+- **Data-fetcher pattern** — `../data-pipeline.md`. The five-generic
+  `defineMosaicTemplate<Props, Outputs, …, Sidecars>` signature its fetcher contract
+  relies on was aspirational when first documented; it is valid TypeScript today.
+- **Multi-range clip picker** — `picker: "time-ranges"` is declared on a **single**
+  `type: "json"` prop whose value is `Array<MosaicTimeRangeMs>`
+  (`{ startMs, endMs, label? }`, integer ms, source-relative, sorted ascending;
+  overlaps allowed, empty array = no selection). Unlike the paired `"time-range"`
+  picker there is no prop pairing — the editor reads and writes the whole array
+  through that one prop in a single write. Boundary reader:
+  `parseTimeRangesValue` in `template-utils/src/media/timeRanges.ts` — use it rather
+  than hand-parsing, precisely because the value may arrive as object *or* string.
+- **Prop-shape consistency** — `npm run audit:props` in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates emits
+  `PROPS-SHAPE.md`, a cross-template prop-shape matrix. Run it after adding a
+  `"json"` prop to see how the shelf compares.

package/node_modules/@m0saic/knowledge/docs/templates/reference/mosaic-color.md

@@ -0,0 +1,81 @@
+# MosaicColor
+
+> **Source of truth:** [https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/colors/mosaicColor.ts](https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/colors/mosaicColor.ts) (the type), https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/colors/parseMosaicColors.ts (the validators), https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/colors/ffmpegNamedColors.ts (the named-color set).
+
+## The type
+
+Verbatim from `mosaicColor.ts:25`:
+
+```ts
+export type MosaicColor =
+  | "none"
+  | FfmpegNamedColor
+  | HexColor
+  | `${FfmpegNamedColor}${AlphaSuffix}`
+  | `${HexColor}${AlphaSuffix}`
+  | `none${AlphaSuffix}`;
+```
+
+Accepted: ffmpeg named colors (`"white"`, `"darkgray"`), hex (`"#fff"`,
+`"#ffffff"`, `"#ff00ffaa"`), optional alpha suffix (`"white@0.5"`), and
+`"none"` for transparency. `HexColor` is just `` `#${string}` `` — the type is
+a **shape contract, not a full validator** (no hex well-formedness, alpha
+range, or casing checks). Runtime validation is required on production paths.
+
+## Validate with the real exports — never hand-roll
+
+`@m0saic/types` ships the canonical pair; use them instead of local regexes
+(a naive "has an `@` suffix" check accepts `"garbage@0.5"` — the real one
+re-validates the base):
+
+- **`toMosaicColor(input, ctx?)`** (`parseMosaicColors.ts:16`) — throws on
+  invalid; returns a normalized (lowercased) `MosaicColor`. Splits any `@alpha`
+  suffix, requires alpha finite and in `[0, 1]` (`:39-41`), then validates the
+  **base** as `"none"`, a named color, or well-formed hex. `ctx` names the error.
+- **`isMosaicColor(input)`** (`parseMosaicColors.ts:75`) — non-throwing type guard.
+- **`FFMPEG_NAMED_COLORS_SET`** (`ffmpegNamedColors.ts:157`) — the membership
+  set behind named-color validation.
+
+Real caller: https://github.com/m0saic-project/m0saic-packages/blob/main/packages/templates/src/m0saic/charts/bar-graph/v1/internal/plot-area.ts#L30
+imports it and uses it as `toMosaicColor("#ffffff", "PlotArea.BASELINE_COLOR")` (:83).
+
+Where to validate: primitives validate incoming color props before passing them
+to sources; heroes normalize early; template-utils must never emit invalid
+`MosaicColor`. Never widen a field to `string` to silence the compiler.
+
+## `"none"` and alpha
+
+- `"none"` means transparent. The engine mapping to an ffmpeg color string
+  lives in the render engine source (not published) (`ffmpegColor()`) —
+  templates use `"none"` as intent, never hand-encoding the ffmpeg form.
+- Prefer `visual.opacity` for compositing; use an alpha suffix only when
+  transparency is part of the color's identity — never encode opacity in both.
+
+## Ternary widening (common pitfall)
+
+When assigning a `MosaicColor` via a conditional, TypeScript widens the literal
+branches to `string` and the assignment fails:
+
+```ts
+const style = {
+  borderColor: isDark ? "#fff" : "#000",  // ❌ widens to string — type error
+};
+```
+
+✅ Use `as const` on the literals:
+
+```ts
+const style = {
+  borderColor: (isDark ? ("#fff" as const) : ("#000" as const)),
+};
+```
+
+✅ Or extract a shared style record so each value is a known literal:
+
+```ts
+const COLORS = { light: "#fff", dark: "#000" } as const;
+const style = { borderColor: COLORS[isDark ? "dark" : "light"] };
+```
+
+The same trap fires on every `MosaicColor`-typed field reached via a ternary
+(`borderColor`, `fillColor`, …). Fix at the literal site, never by widening.

package/node_modules/@m0saic/knowledge/docs/templates/reference/mosaic-placement-props.md

@@ -0,0 +1,103 @@
+# MosaicPlacementProps
+
+> **Source of truth:** [https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/source/source.ts#L99-188`](https://github.com/m0saic-project/m0saic-packages/blob/main/packages/types/src/source/source.ts); runtime validation in https://github.com/m0saic-project/m0saic-packages/blob/main/packages/platform/src/mosaic/validate/validateSources.ts; cover-crop math in the render engine source (not published).
+
+## The union
+
+`MosaicPlacementProps = MosaicPlacementContain | MosaicPlacementCover`
+(`source.ts:188`) — a discriminated union on `fit`. Fields that are meaningless
+on one fit are declared `?: never` on that variant, so misuse is a **compile
+error**, not a silent no-op:
+
+| Field | Contain (`fit?: "contain"`, default) | Cover (`fit: "cover"`) |
+|---|---|---|
+| `inset` | ✅ (`source.ts:128`, on the shared base) | ✅ |
+| `padding` | ✅ (`source.ts:152`) | ❌ `padding?: never` (:166) |
+| `hAlign` / `vAlign` | ✅ (:133-134) | ❌ `hAlign?: never` / `vAlign?: never` (:162-163) |
+| `focusX` / `focusY` | ❌ `focusX?: never` / `focusY?: never` (:155-156) | ✅ (:177, :185) |
+
+Defaults when omitted: `fit="contain"`, `hAlign="center"`, `vAlign="middle"`,
+no `inset`, no `padding`; on cover, focus defaults to centered (`0.5`).
+
+## Boxes: tile rect → inset → padding → content box
+
+- **Tile rect**: the rectangle the layout engine allocates to the source.
+- **`inset?: MosaicBoxFrac`** (both fits): shrinks the destination rect **before**
+  fit math. Role: the **slot-level gutter**, typically owned by the composing
+  layer. Fractions of **tile size**.
+- **`padding?: MosaicBoxFrac`** (contain-only): extra dead space reserved
+  **inside** the inset box, before contain math. Role: content-level breathing
+  room, composing with (not fighting) the slot's `inset`. Fractions of the
+  **inset box** (= of tile size when `inset` is unset; the engine resolves
+  `padLeft = insetBox.width * padding.left`). Cover forbids it — "cover +
+  padding would create intentional dead space" — enforced by the type AND the
+  `*_COVER_PADDING` validator (`validateSources.ts:561`).
+- **`MosaicBoxFrac`** (`source.ts:85-97`): `0.02` (all sides) | `{x, y}`
+  (symmetric per axis) | `{top, right, bottom, left}` (per-side overrides win).
+  All fractions 0..1; validators require each side in `[0, 0.49]`.
+- **Content box**: the tile rect after `inset` (and, for contain, `padding`).
+
+⚠️ **Both are applied BEFORE the per-tile effects chain.** Quoting the `inset`
+JSDoc (`source.ts:117-121`): "Applied before the per-tile effects chain — the
+content's buffer IS the shrunk box, so effects that need headroom
+(`effects.rotate`) clip against it. Rotation headroom must be real geometry
+instead: a nested child whose declared `size` equals the padded box (see
+watermark page-mode `buildPaddedInstanceChild`)."
+
+## Contain
+
+Uniform scale, aspect preserved, so the media fits entirely inside the content
+box. Leftover per axis: `leftoverX = contentW - scaledW`, `leftoverY = contentH - scaledH`.
+
+Alignment maps to factors — `left/top = 0`, `center/middle = 0.5` (default),
+`right/bottom = 1` — and placement is:
+
+```
+x = contentX + (leftoverX > 0 ? leftoverX * hFactor(hAlign) : 0)
+y = contentY + (leftoverY > 0 ? leftoverY * vFactor(vAlign) : 0)
+```
+
+**Exact-fit invariant (still observable, and required):** on an axis with zero
+leftover, varying the alignment MUST NOT change output — byte-identical frames.
+This is the surviving observability check now that cover-side misuse is
+unrepresentable.
+
+## Cover
+
+Uniform scale, aspect preserved, so the media fully covers the content box;
+overflow is cropped to exactly `contentW × contentH`; placed at
+`(contentX, contentY)`. No leftover space, so alignment is unrepresentable.
+
+### Crop anchor: `focusX` / `focusY`
+
+```ts
+placement: { fit: "cover", focusX?: number, focusY?: number }   // 0..1 each
+```
+
+**Offset per axis = `(scaled - content) * focus`.** `0` keeps the leading edge
+(left/top), `0.5` centers (default), `1` keeps the trailing edge. Motivating
+case: portrait photos put faces near the top — `focusY: 0` keeps the head.
+
+- **Byte-identity guarantee.** Focus absent or exactly `0.5` emits the exact
+  legacy `(in_w-W)/2` string — helper `coverCropOffsetExpr`
+  (the render engine source (not published)). Existing goldens do not move.
+- **Enforced twice.** Type level: `focusX?: never` on contain. Runtime:
+  `*_FOCUS_REQUIRES_COVER` (https://github.com/m0saic-project/m0saic-packages/blob/main/packages/platform/src/mosaic/validate/validateSources.ts#L575)
+  plus range checks `*_INVALID_FOCUSX` / `*_INVALID_FOCUSY` in `[0, 1]`
+  (`validateFocus`, `validateSources.ts:502`). Note these live in **platform**,
+  not core.
+- **Also steered by focus:** `zoomInPercent`'s zoom crop on cover tiles
+  (contain + zoom stays centered), and `doc.backgroundImage`'s cover fill.
+- **Not `effects.camera`.** Same focus vocabulary, different layer: the camera
+  is the animatable zoom/pan downstream on the already-cropped content box;
+  placement focus is the static, plan-time fit-crop anchor. They compose.
+- **Web parity:** `GeometricPreview` maps cover focus to CSS
+  `object-position: ${fx*100}% ${fy*100}%` — identical percentage math.
+
+## Historical note
+
+Pre-v2 versions of this spec carried "for `fit="cover"`, `hAlign`/`vAlign`
+MUST NOT affect output" invariants. The union now declares those fields `never`
+on cover (verified against `source.ts` 2026-07-27), so the misuse is
+unrepresentable and those invariants are moot — only the contain exact-fit
+invariant above remains testable.