@m0saic/knowledge 0.2.0

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

@@ -0,0 +1,37 @@
+{
+  "name": "@m0saic/knowledge",
+  "version": "0.2.0",
+  "private": false,
+  "license": "MIT",
+  "description": "The m0saic knowledge base for agents and authors: the m0 handbook, the engine mental models, and the template-authoring contract, as plain Markdown. Point your coding agent at README.md before it writes a template.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "node test/docs.test.mjs --build",
+    "test": "node --test test/docs.test.mjs"
+  },
+  "keywords": [
+    "m0saic",
+    "m0",
+    "templates",
+    "knowledge-base",
+    "agents",
+    "AGENTS.md"
+  ],
+  "author": "m0saic LLC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m0saic-project/m0saic-packages.git",
+    "directory": "packages/knowledge"
+  },
+  "homepage": "https://github.com/m0saic-project/m0saic-packages/tree/main/packages/knowledge#readme",
+  "bugs": {
+    "url": "https://github.com/m0saic-project/m0saic-packages/issues"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "LICENSE",
+    "README.md"
+  ]
+}