@mulmoclaude/core 4.4.2 → 4.6.0

package/assets/helps/bug-report-faq.md

@@ -128,3 +128,16 @@ Desktop and phone views have **incompatible runtime contracts** — a desktop vi
 records with an injected token, while a `target: "mobile"` view gets them over a postMessage bridge
 and cannot `fetch` at all. A view authored against the wrong contract renders empty with no error.
 Check which target it is registered as before treating it as a rendering fault.
+
+## The narration is not the voice I asked for, or a small tweak re-recorded every beat
+
+help: mulmoscript.md
+help: error-recovery.md
+
+Speech settings resolve through fallbacks that raise no error, so read the script's own
+`speechParams` block against the speaker reference in `mulmoscript.md` (§ speechParams) before
+treating it as a bug. Three mechanisms explain nearly every report: a `lang` entry replaces the
+whole speaker rather than extending it, each delivery option reaches some providers and is dropped
+by others, and the audio cache key of each beat is built from the speaker's own fields — so editing
+one of them re-records every beat that speaker narrates. Which field is missing decides which
+symptom you are looking at.

package/assets/helps/business.md

@@ -18,6 +18,10 @@ Reach for `presentMulmoScript` when the user asks for a presentation, slideshow,
   - `markdown` — rich text, tables, mixed content
 - Do NOT use `imagePrompt` or `moviePrompt` in business presentations
 - Write concise, professional narration text for each beat (becomes the voiceover)
+- Leave the speaker's `model` out unless the user asks for higher-quality narration
+  (`"model": "gemini-2.5-pro-preview-tts"`), and set it before the first render — voice / model /
+  `speechOptions` form the audio cache key, so a later change re-records every beat
+  (full speaker reference: `config/helps/mulmoscript.md` → speechParams)
 - Put a 1–2 sentence summary of the whole presentation in the top-level `description` field
 
 ## Template

package/assets/helps/error-recovery.md

@@ -225,6 +225,41 @@ shipped registry repo's README. Common rejections:
 - `name` reuses the reserved value `official`.
 - `name` doesn't match `[A-Za-z0-9][A-Za-z0-9_-]{0,31}`.
 
+## A collection's icon shows up as letters, or smears over its neighbours
+
+### Symptoms
+
+- A collection / feed / pinned shortcut draws its icon NAME as text
+  (`podcasts`, or a fragment like `_A__C`) instead of a glyph.
+- The text spills out of its square and overlaps the buttons next to it
+  in the launcher bar.
+
+### Cause + fix
+
+`schema.icon` was set to something the Material Symbols font has no
+ligature for. The font matches icons by LIGATURE, so an unknown value
+is simply laid out as ordinary text.
+
+Valid names are lowercase letters, digits and underscores only —
+`podcasts`, `rss_feed`, `menu_book`, `3d_rotation`. Capitals, spaces
+and hyphens never match (`Podcasts` and `menu-book` are the usual
+typos). Look the name up in the Material Symbols set before writing it;
+do not invent one.
+
+An **emoji is a valid alternative** and is often the better choice: it
+is in colour and stands out among the monochrome glyphs, which is the
+point when several collections would otherwise share a look-alike icon
+(`podcasts` / `rss_feed` / `menu_book`). Set `"icon": "🎙️"` the same way you
+would set a name. Only the first GRAPHEME is drawn — one emoji, whatever
+number of code points it is built from (a variation selector, a skin tone, a
+ZWJ family) — so write exactly one glyph and nothing after it.
+
+If the smearing persists after the value is corrected, the surface
+drawing it is bypassing `IconGlyph`
+(`@mulmoclaude/core/plugin-vue`) — every schema-authored icon must go
+through it rather than into a bare
+`<span class="material-symbols-outlined">`.
+
 ## A hand-placed custom role never appears in the list
 
 ### Symptoms
@@ -365,6 +400,42 @@ missing key to `.env` (restart the server) or rewrite the script's
 keys configured. Don't retry the render unchanged — the same provider
 will fail the same way.
 
+## MulmoScript narration — wrong voice, ignored direction, or every beat re-recorded
+
+### Symptoms
+
+- A non-default language (`speechParams.speakers.<name>.lang.<code>`) renders
+  in a different voice, or fails on a missing `OPENAI_API_KEY` even though the
+  script names `gemini` everywhere.
+- `speechOptions.instruction` or `speed` has no audible effect on the narration.
+- A small edit to a speaker re-generates audio for **every** beat, including the
+  ones whose text never changed.
+
+### Cause
+
+Speech settings resolve through silent fallbacks — the schema does not reject a
+missing field, it fills one in:
+
+- A `lang` entry **replaces** the whole speaker; it does not extend it. Whatever
+  the entry omits falls back to the schema and provider defaults, so one holding
+  only `voiceId` loses `provider` (which then resolves to `openai`), `model`, and
+  `speechOptions`.
+- `instruction` is dropped by the `google` provider unless the speaker also sets
+  a `model`; `speed` is ignored by `gemini` altogether.
+- Each beat's audio file is cached under a hash of that beat's `text` plus the
+  speaker's `voiceId` + `provider` + `model` + `speechOptions`. Editing the
+  speaker is a new cache key for every beat that speaks through it — the whole
+  script when there is one speaker — so it is re-recorded and re-billed.
+
+### Fix
+
+Repeat every field the parent speaker sets — `provider` above all — inside each
+`lang` entry. Express pacing for Gemini through `instruction` rather than
+`speed`. Settle voice, model, and delivery **before** the first render — and when
+a change is genuinely wanted, say up front that every beat of that speaker
+re-records, rather than letting the bill surprise the user. Field-by-field
+reference: `config/helps/mulmoscript.md` → speechParams.
+
 ## Build / yarn workspace ordering
 
 ### Symptoms

package/assets/helps/gemini.md

@@ -15,7 +15,7 @@ A single key unlocks all three capabilities (images, TTS audio, video) — you d
 
 ### Audio
 
-- **MulmoScript speech** — `presentMulmoScript` synthesizes speaker voices via Gemini TTS (`gemini-2.5-flash-preview-tts`). This is what turns a storyboard into spoken narration, so the **Storyteller** and **Storyteller Plus** roles become near-complete multimedia pieces.
+- **MulmoScript speech** — `presentMulmoScript` synthesizes speaker voices via Gemini TTS. This is what turns a storyboard into spoken narration, so the **Storyteller** and **Storyteller Plus** roles become near-complete multimedia pieces. Speakers record with whatever the provider's current default is (today `gemini-2.5-flash-preview-tts`) unless the script names a model itself — a speaker can set `"model": "gemini-2.5-pro-preview-tts"` for higher-quality narration at about twice the token price (`config/helps/mulmoscript.md` → speechParams).
 
 ### Video
 

package/assets/helps/mulmoscript.md

@@ -197,7 +197,77 @@ Configure TTS voices per speaker.
 }
 ```
 
-Each speaker supports per-language voice overrides via a `lang` map.
+| Field | Required | Description |
+|---|---|---|
+| `voiceId` | Yes | Provider voice name. Gemini voices are names like `"Kore"`, `"Schedar"`, `"Aoede"` — `config/helps/storyteller.md` lists them by tone |
+| `provider` | No | **Falls back to `openai`, not Gemini** — always write `"provider": "gemini"` |
+| `model` | No | TTS model. Omitted → the provider's default (Gemini: `gemini-2.5-flash-preview-tts`) |
+| `isDefault` | No | Beats with no `speaker` field use this speaker |
+| `displayName` | No | Per-language label for the speaker |
+| `speechOptions` | No | How the line is delivered — see below |
+| `lang` | No | Per-language speaker **replacement** — see below |
+
+Nothing here is validated against the provider: `model` is a free-form string,
+and a missing `provider` / `model` is not rejected when the script is parsed — it
+resolves to a default, which may then be wrong at render time or merely audible.
+Set them deliberately rather than relying on the fallback.
+
+### Choosing a model
+
+Gemini TTS accepts two models:
+
+| Model | Cost | Use when |
+|---|---|---|
+| `gemini-2.5-flash-preview-tts` (default) | 1× | Everything, by default — leave `model` out |
+| `gemini-2.5-pro-preview-tts` | ~2× the token price | The user asks for higher-quality or more expressive narration |
+
+**Decide before the first render.** Each beat's audio file is cached under a hash
+of that beat's `text` plus the speaker's `voiceId` + `provider` + `model` +
+`speechOptions`. Rewriting one beat's text therefore re-records that beat alone,
+but touching the speaker changes the key of **every beat that speaks through it**
+— in a single-speaker script, the whole thing, billed again. Leave `model` out to
+track the provider default; add it only when you mean to pin a different model.
+
+### `speechOptions`
+
+`beats[].speechOptions` merges over the speaker's for that one beat, so a single
+line can be delivered differently without touching the speaker.
+
+| Option | Honored by | Notes |
+|---|---|---|
+| `instruction` | `gemini`, `openai` | Direction for delivery, sent as DIRECTOR'S NOTES ahead of the text. Under `google` it is **dropped unless `model` is set** |
+| `speed` | `openai`, `google`, `elevenlabs` | **Silently ignored by `gemini`** — ask for the pace in `instruction` instead |
+
+(`stability` / `similarity_boost` belong to `elevenlabs` and `decoration` to
+`kotodama`; neither provider is configured in this app.)
+
+### `lang` — a replacement, not an override
+
+A `lang` entry **replaces the whole speaker** for that language: whatever it
+omits falls back to the schema and provider defaults, never to the parent's
+value. Repeat every field the parent sets — `provider` above all, since an entry
+holding only `voiceId` resolves to the `openai` provider and then fails on a
+missing `OPENAI_API_KEY` (or rejects the Gemini voice name) even though the
+script names Gemini everywhere.
+
+```json
+{
+  "speakers": {
+    "Presenter": {
+      "provider": "gemini",
+      "voiceId": "Kore",
+      "speechOptions": { "instruction": "Warm and unhurried." },
+      "lang": {
+        "ja": {
+          "provider": "gemini",
+          "voiceId": "Kore",
+          "speechOptions": { "instruction": "Warm and unhurried." }
+        }
+      }
+    }
+  }
+}
+```
 
 ## audioParams
 

package/assets/helps/presentation-deck.md

@@ -26,7 +26,10 @@ override the generic guidance above:
 - **Tool**: hand the finished JSON to the `presentMulmoScript` tool — that is how a deck is rendered here.
 - **Narration / TTS**: declare a speaker once in `speechParams.speakers` with `isDefault: true` and
   the **Google** provider (`"provider": "gemini", "voiceId": "Kore"`). Beats then inherit it without
-  repeating `speaker`. Both samples below include this block — keep it.
+  repeating `speaker`. Both samples below include this block — keep it. Leave `model` out unless the
+  user asks for higher-quality narration (`"model": "gemini-2.5-pro-preview-tts"`), and set it before
+  the first render — voice / model / `speechOptions` are part of the audio cache key, so a later change
+  re-records every beat. Full speaker reference: `config/helps/mulmoscript.md` → speechParams.
 - **Providers are Google-only.** This app configures only Google providers; never emit `openai`,
   `elevenlabs`, etc. Neither approach generates AI images or video, so `imageParams` / `movieParams`
   are not needed (the `slide` type renders static layouts; `html_tailwind` + `animation` renders from

package/assets/helps/storyteller.md

@@ -31,6 +31,13 @@ Set `speechOptions.instruction` on the Narrator speaker to match the story's ton
 | Deep / authoritative | Alnilam, Iapetus, Algieba |
 | Soft / gentle | Aoede, Umbriel, Laomedeia, Achernar, Rasalgethi, Pulcherrima, Vindemiatrix, Sadachbia, Sadaltager, Zubenelgenubi |
 
+Leave `model` out — the speaker then records with Gemini's default TTS model. Add
+`"model": "gemini-2.5-pro-preview-tts"` only when the user asks for higher-quality
+narration, and add it **before the first render**: voice, model, and
+`speechOptions` are part of the audio cache key, so changing one later re-records
+every beat. Full speaker reference (including the `lang` map, which *replaces* the
+speaker rather than extending it): `config/helps/mulmoscript.md` → speechParams.
+
 ## Other Rules
 
 - Always use Google providers (`gemini` for TTS, `google` for image generation).

package/dist/collection/core/accentColor.d.ts

@@ -0,0 +1,23 @@
+/** The colours a schema may name, ordered around the hue circle.
+ *
+ *  Deliberately EXCLUDES the warm band (red / orange / amber): those are the
+ *  notification severities (`ENUM_ALERT` red, `ENUM_NUDGE` amber in
+ *  `enumColors.ts`) and the launcher's own session badges, so an accent can
+ *  never make a shortcut read as "something needs attention".
+ *
+ *  Seven rather than eight: rendering all eight candidates on one identical
+ *  glyph put `cyan` squarely between `sky` and `teal`, so a pill could hold
+ *  three shortcuts in the same blue-green band. A colour that cannot be told
+ *  from its neighbour identifies nothing, which is the entire job here — the
+ *  set is sized for separation, not for count. */
+export declare const ACCENT_COLORS: readonly ["violet", "indigo", "sky", "teal", "emerald", "lime", "fuchsia"];
+export type AccentColor = (typeof ACCENT_COLORS)[number];
+/** Narrowing guard: is `value` one of the colours a schema may name? */
+export declare function isAccentColor(value: unknown): value is AccentColor;
+/** The chip classes for `color`, or `null` when there is no accent to draw —
+ *  absent, blank, or a name this palette does not carry.
+ *
+ *  Unknown names fail soft rather than throwing, matching how `icon` is
+ *  handled: a schema is user/LLM-authored, and a typo should cost the colour,
+ *  not the surface. The caller falls back to its own unstyled treatment. */
+export declare function accentChipClasses(color: string | undefined): string | null;

package/dist/collection/core/iconGlyph.d.ts

@@ -0,0 +1,26 @@
+/** A resolved icon value: either a ligature name for the icon font, or a
+ *  literal glyph (emoji, a single letter) drawn as plain text. */
+export type IconGlyph = {
+    kind: "symbol";
+    name: string;
+} | {
+    kind: "glyph";
+    text: string;
+};
+/** Drawn when neither the value nor the surface's own fallback says anything.
+ *  Without it a blank `fallback` resolves to an EMPTY glyph and the surface
+ *  renders a hole — this function promises a drawable result for every input,
+ *  so the promise needs a floor. */
+export declare const DEFAULT_ICON = "dataset";
+/** Classify a schema-authored icon value.
+ *
+ *  `raw` empty / blank / absent falls back to `fallback` (the per-surface
+ *  default such as `"dataset"`), and a blank `fallback` in turn to
+ *  {@link DEFAULT_ICON}. Both are classified by the same rule — so a caller
+ *  can never smuggle an unrenderable default past the guard, and the result
+ *  is always something drawable.
+ *
+ *  A non-name value is cut to ONE grapheme. That bounds the character count,
+ *  not the rendered width — see the containment note in
+ *  `plugin-vue/IconGlyph.ts` for the other half. */
+export declare function resolveIconGlyph(raw: string | undefined, fallback: string): IconGlyph;

package/dist/collection/core/schema.d.ts

@@ -186,6 +186,15 @@ export interface CollectionSummary {
     slug: string;
     title: string;
     icon: string;
+    /** Optional accent colour name (see `ACCENT_COLORS`), drawn as a pale chip
+     *  behind the launcher glyph. Absent when the schema names none.
+     *
+     *  Declared NARROW (no `| undefined`), like its `appId` / `readonly`
+     *  siblings: the remote-host handlers pass these shapes through `Jsonify`,
+     *  which drops `undefined` from a member union, so a widened optional stops
+     *  being assignable there. Producers therefore ADD the key conditionally
+     *  rather than assigning `undefined` to it. */
+    color?: string;
     source: CollectionSource;
     /** Present (true) when the collection is backed by an external
      *  `dataSource` and therefore read-only in every UI/tool write path.

package/dist/collection/core/schemaZ.d.ts

@@ -693,6 +693,15 @@ export declare const StorageZ: z.ZodDiscriminatedUnion<[z.ZodObject<{
  *  this parses to, and nothing narrower. */
 declare const CollectionObjectZ: z.ZodObject<{
     title: z.ZodString;
+    color: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+        violet: "violet";
+        indigo: "indigo";
+        sky: "sky";
+        teal: "teal";
+        emerald: "emerald";
+        lime: "lime";
+        fuchsia: "fuchsia";
+    }>>>;
     icon: z.ZodString;
     dataPath: z.ZodOptional<z.ZodString>;
     dataSource: z.ZodOptional<z.ZodObject<{
@@ -1175,6 +1184,15 @@ declare const CollectionObjectZ: z.ZodObject<{
 export type CollectionSchemaInput = z.infer<typeof CollectionObjectZ>;
 export declare const CollectionSchemaZ: z.ZodPreprocess<z.ZodObject<{
     title: z.ZodString;
+    color: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+        violet: "violet";
+        indigo: "indigo";
+        sky: "sky";
+        teal: "teal";
+        emerald: "emerald";
+        lime: "lime";
+        fuchsia: "fuchsia";
+    }>>>;
     icon: z.ZodString;
     dataPath: z.ZodOptional<z.ZodString>;
     dataSource: z.ZodOptional<z.ZodObject<{
@@ -1653,5 +1671,5 @@ export declare const CollectionSchemaZ: z.ZodPreprocess<z.ZodObject<{
         }, z.core.$strip>>;
         fallback: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
-}, z.core.$strip>>;
+}, z.core.$strip>, unknown>;
 export {};

package/dist/collection/core/shortcutInfo.d.ts

@@ -0,0 +1,14 @@
+import { CollectionShortcutInfo } from './uiTypes';
+/** The fields an index row supplies. Both `CollectionSummary` and
+ *  `FeedSummary` satisfy it; `icon` is optional because a feed row may carry
+ *  an empty one and rely on the surface's default. */
+export interface ShortcutInfoSource {
+    slug: string;
+    title: string;
+    icon?: string | undefined;
+    color?: string | undefined;
+}
+/** An index row as shortcut-reconcile input. `fallbackIcon` stands in when the
+ *  row names no icon (feeds do this); `color` is omitted entirely rather than
+ *  set to `undefined` when the row has none. */
+export declare function toShortcutInfo(row: ShortcutInfoSource, fallbackIcon: string): CollectionShortcutInfo;

package/dist/collection/core/uiTypes.d.ts

@@ -122,6 +122,9 @@ export interface FeedSummary {
     slug: string;
     title: string;
     icon: string;
+    /** Optional accent colour name (see `ACCENT_COLORS`), drawn as a pale chip
+     *  behind the launcher glyph. Absent when the schema names none. */
+    color?: string;
     kind: string;
     schedule: string;
     lastFetchedAt: string | null;
@@ -136,4 +139,7 @@ export interface CollectionShortcutInfo {
     slug: string;
     title: string;
     icon: string;
+    /** Optional accent colour name (see `ACCENT_COLORS`), drawn as a pale chip
+     *  behind the launcher glyph. Absent when the schema names none. */
+    color?: string;
 }

package/dist/collection/index.cjs

@@ -1,8 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_dist = require("../dist-CsgSfWwR.cjs");
-const require_itemId = require("../itemId-CEQdK01z.cjs");
-const require_promptSafety = require("../promptSafety-C0BWDsfT.cjs");
+const require_itemId = require("../itemId-CGT2J7YK.cjs");
+const require_promptSafety = require("../promptSafety-Cv-SoTd4.cjs");
 const require_project = require("../project-C1ep9pvo.cjs");
+const require_iconGlyph = require("../iconGlyph-fSBp6k4J.cjs");
 //#region src/collection/core/presentCollection.ts
 var TOOL_NAME = "presentCollection";
 /** Stamp a host's opaque project scope onto a card payload. The ONLY way a
@@ -365,6 +366,19 @@ function skillCommandSeed(slug, message, itemId) {
 	return itemId ? `/${slug} id=${itemId} ${message}` : `/${slug} ${message}`;
 }
 //#endregion
+//#region src/collection/core/shortcutInfo.ts
+/** An index row as shortcut-reconcile input. `fallbackIcon` stands in when the
+*  row names no icon (feeds do this); `color` is omitted entirely rather than
+*  set to `undefined` when the row has none. */
+function toShortcutInfo(row, fallbackIcon) {
+	return {
+		slug: row.slug,
+		title: row.title,
+		icon: row.icon && row.icon.length > 0 ? row.icon : fallbackIcon,
+		...row.color === void 0 ? {} : { color: row.color }
+	};
+}
+//#endregion
 //#region src/collection/core/sortItems.ts
 var EMPTY = { empty: true };
 /** Field types that render no value text in the table, so offer no sort. */
@@ -635,8 +649,10 @@ var buildOntologyGraph = (entries) => {
 	};
 };
 //#endregion
+exports.ACCENT_COLORS = require_itemId.ACCENT_COLORS;
 exports.AGENT_INGEST_KIND = require_itemId.AGENT_INGEST_KIND;
 exports.COMPUTED_TYPES = require_itemId.COMPUTED_TYPES;
+exports.DEFAULT_ICON = require_iconGlyph.DEFAULT_ICON;
 exports.ENUM_ALERT = ENUM_ALERT;
 exports.ENUM_NEUTRAL = ENUM_NEUTRAL;
 exports.ENUM_NUDGE = ENUM_NUDGE;
@@ -647,6 +663,7 @@ exports.SAFE_RECORD_ID_PATTERN = require_itemId.SAFE_RECORD_ID_PATTERN;
 exports.SAFE_SLUG_PATTERN = require_itemId.SAFE_SLUG_PATTERN;
 exports.TOOL_DEFINITION = TOOL_DEFINITION;
 exports.TOOL_NAME = TOOL_NAME;
+exports.accentChipClasses = require_itemId.accentChipClasses;
 exports.actionVisible = require_promptSafety.actionVisible;
 exports.agentActionRunKey = require_promptSafety.agentActionRunKey;
 exports.assignLanes = require_itemId.assignLanes;
@@ -694,6 +711,7 @@ exports.firstMissingRequiredField = firstMissingRequiredField;
 exports.firstUnknownDefault = require_promptSafety.firstUnknownDefault;
 exports.flagFieldValue = require_promptSafety.flagFieldValue;
 exports.generateUniqueId = require_itemId.generateUniqueId;
+exports.isAccentColor = require_itemId.isAccentColor;
 exports.isCanonicalServerTime = require_itemId.isCanonicalServerTime;
 exports.isFieldDrivenEvery = require_itemId.isFieldDrivenEvery;
 exports.isLocalCollectionKey = require_itemId.isLocalCollectionKey;
@@ -725,6 +743,7 @@ exports.projectRecordFields = require_project.projectRecordFields;
 exports.recordSpan = require_itemId.recordSpan;
 exports.resolveEnumColor = resolveEnumColor;
 exports.resolveIcon = require_promptSafety.resolveIcon;
+exports.resolveIconGlyph = require_iconGlyph.resolveIconGlyph;
 exports.resolveRowRefs = require_promptSafety.resolveRowRefs;
 exports.rollupValue = require_promptSafety.rollupValue;
 exports.rowFromItem = rowFromItem;
@@ -746,6 +765,7 @@ exports.spanCoversDay = require_itemId.spanCoversDay;
 exports.storageKindFor = require_itemId.storageKindFor;
 exports.stringSortValue = stringSortValue;
 exports.toPresentCollectionData = toPresentCollectionData;
+exports.toShortcutInfo = toShortcutInfo;
 exports.toggleChecked = require_promptSafety.toggleChecked;
 exports.uniqueBacklinkSources = require_promptSafety.uniqueBacklinkSources;
 exports.uniqueEmbedTargets = require_promptSafety.uniqueEmbedTargets;