@m0saic/knowledge 0.2.0

package/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/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/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.

package/docs/templates/reference/prop-bindings.md

@@ -0,0 +1,203 @@
+# Prop bindings — the rect that SHOWS a prop is its handle in Make
+
+A template marks the source that DISPLAYS a prop with `source.editor.binding`
+(or `bindings`, several leaves on one rect). Make resolves them per render and
+turns the rect into the prop's canvas handle: double-click / a badge to edit,
+a file dropped on it to fill a media slot. Bindings are re-resolved on every
+render and keyed by the PROP — never by a stableKey, which changes whenever the
+geometry does.
+
+One predicate decides what is bindable: `classifyBindableProp` in
+`@m0saic/platform` (`mosaic/propBindings`). Template tests
+(`resolvePropBindings` in `@m0saic/template-utils`) and the Make page both use
+it, so a template can never offer an edit the page refuses, or vice versa.
+`bindProps` / `bindPropPath` THROW at author time for what the platform would
+silently drop — a template test should never reach the silent path.
+
+## The wire shape
+
+```ts
+binding: {
+  propKey: string;                 // dotted path as propsSchema nests it: "label", "titles.title"
+  index?: number;                  // ONE element of string[] / number[] / media[]
+  path?: Array<string | number>;   // route into a json / list / array value: [2, "title"]
+  kind?: "string" | "number" | "color" | "rect" | "media";  // required on structured leaves
+  layer?: number;                  // which text layer shows the leaf (multi-layer text)
+  onClear?: "remove-element" | "unset-leaf";
+  seedDraft?: string;
+  companion?: boolean;
+  range?: { start: number; end: number };   // one line of a multi-line string leaf
+  focus?: { start: number; end: number };   // the token the rect shows, inside range
+}
+```
+
+Rules:
+
+- `propKey` is exactly as `propsSchema` nests it; every segment past the
+  first walks a `type: "group"` prop's `fields`.
+- Basic lists (`string[]`, `number[]`, `media[]`) bind ONE element — a
+  non-negative integer `index`. The list itself is never bindable.
+- Structured props (`json` / `list` / `array`) bind a LEAF: `path` from the
+  prop's value plus an explicit `kind` (the schema has no per-leaf type, and an
+  empty leaf must still be an "add" handle). `index` is shorthand for a leading
+  numeric segment.
+- `meta.ui.hidden` props, booleans, enum / connection-option strings (closed
+  pickers) and whole lists are never bindable. A stray `index` on a scalar is
+  ignored.
+- Bind even when the value is empty — the rect is then a handle to ADD.
+
+## Kinds
+
+| prop / leaf | binding | kind | Make handle |
+|---|---|---|---|
+| free-text `string` (or one `string[]` element, or a structured leaf) | `bindProp(src, key[, i])` / `bindPropPath(src, key, path, "string")` | `"string"` | T — the inline text form |
+| colour-valued string (`isColor` / `colorPicker`) | same | `"color"` | swatch — a picker |
+| `number` (or one `number[]` element, or a leaf) | same, `"number"` | `"number"` | 123 — the inline form |
+| `json` with `picker: "regions"`, `regions.max: 1` | `bindPropRect(src, key)` — no path | `"rect"` | move glyph — the regions draw session on the cell |
+| `media`, one `media[]` element, or a leaf holding a path | `bindProp(src, key[, i])` / `bindPropPath(…, "media")` | `"media"` | picture glyph — a DROP target + the media chip |
+
+Order the entries the way a double-click should read them: `fields[0]` is the
+primary action (a plain double-click); the badge row offers every kind.
+
+## Authoring helpers (`@m0saic/template-utils`)
+
+- `bindProp(src, propKey, index?)` — the basic case.
+- `bindProps(src, entries)` — several leaves on one rect (a multi-layer text,
+  a cell that moves AND edits AND takes a drop). Writes `editor.bindings`,
+  which wins over the single `binding`.
+- `bindPropPath(src, propKey, path, kind, { onClear?, seedDraft? })` — one
+  structured leaf.
+- `bindPropRect(src, propKey)` — a one-region regions picker edited in place.
+- `bindPropRange(src, propKey, index, range, focus?)` — one line of a
+  multi-line string prop (a code state, a lyric block); offsets index the RAW
+  prop string.
+- `stripPropBindings(doc)` — a host composing ANOTHER template's render drops
+  its bindings (they name the inner template's props).
+- `tag(src, label)` composes either way round with all of them.
+
+## `onClear` — what an EMPTY commit means
+
+```ts
+{ propKey: "days", path: [rowIndex, "day"], kind: "number", onClear: "remove-element" }
+```
+
+- `"remove-element"` — splice the element at the leading numeric path segment
+  (the whole row, or one element of a basic list) out of its array. Needs an
+  `index` or a numeric first `path` segment.
+- `"unset-leaf"` — delete the leaf key from its object, or unset a basic prop
+  so its default shows again. Not for array-element leaves (no key).
+- Absent — numbers and colours refuse an empty commit; strings write `""`;
+  a scalar media clears to `""`; a `media[]` element refuses (a hole in a media
+  list is not a value the engine can open).
+
+Editor rules: "empty" is blank for numbers / colours, `""` for text. An empty
+commit against an already-empty leaf writes nothing. In a multi-field session a
+row removal supersedes its siblings' writes; rows go highest index first. The
+panel stays the primary place rows are deleted — canvas clear is an accelerator.
+
+## `seedDraft` — prefill an EMPTY leaf from the rect's context
+
+```ts
+{ propKey: "days", path: [len, "day"], kind: "number", onClear: "remove-element", seedDraft: String(info.day) }
+```
+
+- Applies only when the bound leaf reads EMPTY / absent; a leaf with a value
+  ignores it. A DRAFT: shown pre-selected (Enter alone accepts it), written on
+  commit like typed text, never applied by itself. Deleting it and committing
+  empty still runs `onClear`.
+- Blur commits too, so an untouched seeded form that loses focus WRITES the
+  seed — mind this when seeding.
+- Wire shape is a string; a blank seed, or a non-numeric seed on a number
+  leaf, throws at author time; `rect` and `media` leaves take no seed.
+- Focus lands on the FIRST field: order a seeded field first when the seed is
+  the whole suggestion.
+
+## `kind: "media"` — a rect that takes a dropped file
+
+A media-bound rect is a DROP target on the Make canvas (a file dragged onto it
+writes the path) with a picture-glyph handle that opens the media chip —
+`Choose file…` / `Replace…` · `Remove` (when clearable) · "or drop a file on
+the cell". A file in flight lights every media slot; a slot whose prop refuses
+the kind lights muted.
+
+- What may land is the PROP's say: `meta.control.accept` (`["image","video"]`)
+  and `meta.control.extensions`. Judged by MIME while in flight, by extension
+  at drop.
+- `media[]`: index `< length` replaces, `=== length` appends (an add handle),
+  `> length` is refused. A media list is never padded with `""`.
+- A tile pairs handles freely — the drop-calendar's facecam is
+  `bindProps(src, [{ propKey: "facecamRegion", kind: "rect" }, { propKey: "facecam" }])`:
+  move it, or drop on it. Put the MEDIA entry first when a double-click should
+  mean "replace the picture".
+
+### A drop commits the tile's seeded companions
+
+When a file lands, every EMPTY sibling leaf on the tile that carries a
+`seedDraft` is written with its seed — the rect's meaning travels with the
+gesture (the clicked date; the slot number). Leaves with a value, or empty
+leaves without a seed, are untouched.
+
+`companion: true` marks a seeded leaf ONLY the drop fills:
+
+```ts
+{ propKey: "days", path: [row, "teaser"], kind: "number", seedDraft: String(teasers.length + 1), companion: true }
+```
+
+It never shows in the text form (a blur-commit there would write the seed on
+an unrelated edit) and never earns a badge. Needs a kept `seedDraft`; refused
+on media / rect leaves. The drop-calendar date cell, in full — one drop births
+a pictured row:
+
+```ts
+bindProps(cell, [
+  { propKey: "days", path: [n, "day"],   kind: "number", onClear: "remove-element", seedDraft: String(day) },
+  { propKey: "days", path: [n, "title"], kind: "string" },
+  { propKey: "teasers", index: teasers.length, kind: "media" },
+  { propKey: "days", path: [n, "teaser"], kind: "number", seedDraft: String(teasers.length + 1), companion: true },
+])
+```
+
+## Starter media — the slot before the footage
+
+A template that wants the slot present (and droppable) before the user has a
+file renders a stand-in while the prop is empty. Two sources:
+
+1. **Bring your own** — media bundled next to the template
+   (`assets/*.png|mp4|svg`, mirrored by copy-assets), built with
+   `fileAsset(resolve(__dirname, "assets"), name, kind)` from
+   `@m0saic/template-utils/dist/m0saic/assetPath` (asar-safe).
+2. **Included defaults** — `starterMedia(role)` from
+   `@m0saic/template-utils/dist/media/defaultMedia` (node-only deep import):
+   roles `portrait` `landscape` `square` `facecam` `avatar` `logo`, one small
+   viewBox-only SVG each (`assets/starter/`, minted by
+   `tools/mint-starter-svg.mjs`). Returns `null` when the file is not on disk —
+   degrade to the template's own stand-in, never an error mosaic.
+
+An `.svg` file asset is rasterized to a PNG at plan time by the engine, and
+Make's preview still-extractor rasterizes it the same way before ffmpeg sees
+it — ffmpeg itself has no svg decoder, so never hand an svg path to it directly.
+A still stand-in in a video slot keeps a no-footage render a poster (PNG);
+motion arrives with the real clip.
+
+Make marks an EXISTING slot with no path (a starter showing) with a persistent
+dashed outline and an "Add …" glyph. An add handle (`teasers[len]`, an unborn
+row) is not a slot and stays quiet — otherwise every empty date cell would light.
+
+## What Make does with them (the host side, for orientation)
+
+- Badge row on hover: one glyph per kind (T · 123 · swatch · move · picture),
+  collapsing to one dot on a tile under ~60 on-screen px. A click on a glyph is
+  a double-click WITH that intent.
+- Text / number / colour → the inline form over the rect (Enter / blur commit,
+  Esc cancels, an unchanged draft writes nothing). Rect → the regions draw
+  session seeded from the painted cell. Media → the chip; a drop needs no click.
+- Every write goes through the ONE prop writer, so it survives every other
+  edit and re-renders the template; the panel field updates because it IS the
+  prop.
+- The double-clicked tile is often chrome stacked over the bound rect (gridlines,
+  glass) — Make looks THROUGH the stack under the pointer for the topmost bound
+  tile, for clicks and drops alike.
+
+First implementers: `@m0saic-dev/creator/drop-calendar/v1` (every kind, the
+companion, the facecam slot); `@m0saic/alpine/*` (text / number / colour);
+`@m0saic-dev/music/lyric-video/v1` (ranges).