@nodaro/prompts 1.14.0 → 1.15.0

package/src/catalog-overlay.ts

@@ -0,0 +1,148 @@
+import type { PickerCatalog, PickerOption } from "./picker-catalogs.js"
+import { catalogPacksVersion, hasCatalogPacksFor } from "./catalog-packs.js"
+
+/**
+ * THE RESOLVER-SIDE HALF OF CATALOG CURATION.
+ *
+ * Every per-catalog module builds an index from its own base constant at load
+ * (`settingById = new Map(SETTINGS…)`) and its `getSetting(id)` reads that. A
+ * deployment's catalog packs compose a DIFFERENT catalog — entries removed,
+ * some rewritten at the same id — and until this module existed nothing on
+ * the resolve path read it. So on a curated deployment a denied id still
+ * turned into its full stock prompt text at run time, and a rewritten entry
+ * injected the stock wording instead of the curated one. The curation was
+ * real in `/v1/catalogs` and invisible in every generated prompt.
+ *
+ * `overlayEntry` sits inside each getter, between the base lookup and the
+ * return:
+ *   - no pack targets the catalog  → the base entry, untouched. This is the
+ *     mainline path and it is byte-identical by construction; a deployment
+ *     that curates nothing pays one Set probe per lookup.
+ *   - a pack targets it, id absent  → undefined. Denied means denied on the
+ *     prompt path too, not only in the picker.
+ *   - a pack targets it, id present → the base entry with the composed
+ *     option's label / description / promptHint / term / category on top,
+ *     so a rewrite reaches the prompt. Fields the composed option does not
+ *     carry (typed extras a specific builder reads) survive from the base.
+ *   - pack-ADDED id (no base entry)  → the composed option itself.
+ *
+ * LATE-BOUND RESOLVER, ON PURPOSE. The catalog modules cannot import
+ * `getPickerCatalog`: picker-catalogs.ts imports every one of them to build
+ * `PICKER_CATALOGS` at module scope, and a module-scope cycle is a TDZ error
+ * under some load orders. picker-catalogs.ts instead installs its resolver
+ * here when IT loads (`setComposedCatalogResolver`), and this module imports
+ * only the pack registry, which imports nothing of the catalogs.
+ *
+ * FAIL CLOSED. If a pack targets a catalog and the resolver is somehow not
+ * installed, every lookup on that catalog throws rather than silently
+ * returning the base entry — a curated deployment answering with stock text
+ * is the failure this whole module exists to prevent.
+ *
+ * SCOPE BOUNDARY, on purpose: the transition / character-fx TIMING dimensions
+ * (position start/middle/end, duration, intensity) are structural knobs the
+ * catalogs expose for thin clients, not content — no curation removes "end".
+ * Their composers index total clause records by construction, and threading
+ * the overlay through that would trade a guaranteed-total prompt for a hole
+ * nothing needs. They stay uncurated; the wall still checks their ids.
+ */
+
+type Resolver = (catalogIdOrNodeType: string) => PickerCatalog | undefined
+let resolver: Resolver | null = null
+
+/** Installed by picker-catalogs.ts at load. */
+export function setComposedCatalogResolver(fn: Resolver): void {
+  resolver = fn
+}
+
+let memo: { v: number; byCatalog: Map<string, ReadonlyMap<string, PickerOption>> } | null = null
+
+/** id → composed option for one catalog, memoized on the pack version. */
+export function composedOptionIndex(catalogId: string): ReadonlyMap<string, PickerOption> {
+  const v = catalogPacksVersion()
+  if (!memo || memo.v !== v) memo = { v, byCatalog: new Map() }
+  const hit = memo.byCatalog.get(catalogId)
+  if (hit) return hit
+  if (!resolver) {
+    throw new Error(
+      `[catalog-overlay] catalog "${catalogId}" is curated by a pack but the composed-catalog resolver is not installed — refusing to resolve against the stock catalog`,
+    )
+  }
+  const cat = resolver(catalogId)
+  const index = new Map<string, PickerOption>()
+  if (cat) {
+    for (const o of cat.options ?? []) index.set(o.id, o)
+    for (const d of cat.dimensions ?? []) for (const o of d.options) if (!index.has(o.id)) index.set(o.id, o)
+  }
+  memo.byCatalog.set(catalogId, index)
+  return index
+}
+
+/**
+ * Overlay the composed catalog on a base lookup. See the module doc for the
+ * four outcomes. `T` is the module's own entry type; the composed option's
+ * common fields are spread over it, so callers keep their typed result.
+ */
+export function overlayEntry<T extends { readonly id: string }>(
+  catalogId: string,
+  id: string,
+  base: T | undefined,
+): T | undefined {
+  if (!hasCatalogPacksFor(catalogId)) return base
+  const opt = composedOptionIndex(catalogId).get(id)
+  if (!opt) return undefined
+  if (!base) return opt as unknown as T
+  return {
+    ...base,
+    label: opt.label,
+    promptHint: opt.promptHint,
+    term: opt.term,
+    ...(opt.description !== undefined ? { description: opt.description } : {}),
+    ...(opt.category !== undefined ? { category: opt.category } : {}),
+  }
+}
+
+/**
+ * Membership only — for id-carrying fields whose entries live outside this
+ * package (the animal / vehicle / weapon / furniture catalogs resolve through
+ * `@nodaro/shared`, which cannot depend on this package). The dispatcher asks
+ * this before calling those getters.
+ */
+export function composedHas(catalogId: string, id: string): boolean {
+  if (!hasCatalogPacksFor(catalogId)) return true
+  return composedOptionIndex(catalogId).has(id)
+}
+
+/** The composed option, or undefined — for callers that render from it directly. */
+export function composedOption(catalogId: string, id: string): PickerOption | undefined {
+  if (!hasCatalogPacksFor(catalogId)) return undefined
+  return composedOptionIndex(catalogId).get(id)
+}
+
+/**
+ * A base entry LIST filtered to ids the composed catalog offers and relabelled
+ * where a pack rewrote an entry — the list-shaped twin of `overlayEntry`, for
+ * anything that renders a whole catalog (pickers, dropdowns, studio browsers).
+ * Returns the base array BY IDENTITY when no pack targets the catalog, so
+ * memo deps and equality checks on mainline are unchanged. Pack-ADDED entries
+ * are not surfaced here: the caller's typed entry shape may carry fields a
+ * PickerOption cannot supply.
+ */
+export function curateEntries<T extends { readonly id: string; readonly label: string }>(
+  catalogId: string,
+  base: readonly T[],
+): readonly T[] {
+  if (!hasCatalogPacksFor(catalogId)) return base
+  const index = composedOptionIndex(catalogId)
+  const out: T[] = []
+  for (const e of base) {
+    const opt = index.get(e.id)
+    if (!opt) continue
+    out.push({
+      ...e,
+      label: opt.label,
+      ...(opt.description !== undefined ? { description: opt.description } : {}),
+      ...("promptHint" in e && opt.promptHint !== undefined ? { promptHint: opt.promptHint } : {}),
+    })
+  }
+  return out
+}

package/src/catalog-packs.ts

@@ -59,20 +59,45 @@ export interface CatalogPack {
 
 let packs: CatalogPack[] = []
 let version = 0
+// Registration can land AFTER a consumer first read (the browser fetches a
+// deployment's composed catalogs at boot; a picker may already be mounted).
+// A read-only memo keyed on `version` sees the change on its NEXT read, but
+// nothing re-runs a React render for it — that gap is how a deployment's
+// curation once rendered as the stock catalogs for a whole session. Listeners
+// let a UI hook subscribe to the version instead of polling it.
+const listeners = new Set<() => void>()
+function bump(): void {
+  version++
+  for (const l of listeners) l()
+}
 
 export function registerCatalogPack(pack: CatalogPack): void {
   if (packs.some((p) => p.id === pack.id)) throw new Error(`duplicate catalog pack id "${pack.id}"`)
   packs = [...packs, pack]
-  version++
   // Push this pack's localized sidecars into the shared app-UI localizer (G10)
   // so pack-added entries resolve in `resolveLabel`/`resolveDescription`/search.
   // One generic point covers every pack, incl. the person extend fan-out.
   registerCatalogSidecars(pack.catalogId, pack.sidecars)
+  bump()
 }
 export function getRegisteredCatalogPacks(): readonly CatalogPack[] { return packs }
-export function resetCatalogPacks(): void { packs = []; version++; resetCatalogSidecars() }
+export function resetCatalogPacks(): void { packs = []; resetCatalogSidecars(); bump() }
 export function catalogPacksVersion(): number { return version }
 
+/** True when at least one pack targets this catalog — i.e. this deployment
+ *  CURATES it and the base constants are no longer the truth for it. */
+export function hasCatalogPacksFor(catalogId: string): boolean {
+  return packs.some((p) => p.catalogId === catalogId)
+}
+
+/** Subscribe to registrations/resets. Returns the unsubscribe. */
+export function subscribeCatalogPacks(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
 function cloneCatalog(c: PickerCatalogInput): PickerCatalog {
   return {
     ...c,

package/src/character-fx.ts

@@ -19,6 +19,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type CharacterFxCategory =
   | "transformation"
@@ -249,7 +250,7 @@ const characterFxById = new Map<string, CharacterFx>(
 
 export function getCharacterFx(id: string | undefined | null): CharacterFx | undefined {
   if (!id) return undefined
-  return characterFxById.get(id)
+  return overlayEntry("character-fx", id, characterFxById.get(id))
 }
 
 export function getCharacterFxLabel(id: string | undefined | null, fallback?: string): string {

package/src/color-look.ts

@@ -12,6 +12,7 @@
  */
 
 import { resolveTerm } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type ColorLookCategory = "palette" | "film-emulation" | "social-preset"
 
@@ -98,7 +99,7 @@ const colorLookById = new Map<string, ColorLook>(COLOR_LOOKS.map((c) => [c.id, c
 
 export function getColorLook(id: string | undefined | null): ColorLook | undefined {
   if (!id) return undefined
-  return colorLookById.get(id)
+  return overlayEntry("color-look", id, colorLookById.get(id))
 }
 
 export function getColorLookLabel(id: string | undefined | null, fallback?: string): string {

package/src/composition-effects.ts

@@ -16,6 +16,7 @@
  */
 
 import { resolveTerm } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export interface CompositionEffect {
   readonly id: string
@@ -64,7 +65,7 @@ const compositionEffectById = new Map<string, CompositionEffect>(
 
 export function getCompositionEffect(id: string | undefined | null): CompositionEffect | undefined {
   if (!id) return undefined
-  return compositionEffectById.get(id)
+  return overlayEntry("composition-effects", id, compositionEffectById.get(id))
 }
 
 export function getCompositionEffectLabel(id: string | undefined | null, fallback?: string): string {

package/src/era.ts

@@ -18,6 +18,7 @@
  */
 
 import { resolveTerm } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type EraCategory = "decade-20c" | "pre-modern" | "speculative"
 
@@ -282,7 +283,7 @@ const eraById = new Map<string, Era>(ERAS.map((e) => [e.id, e]))
 
 export function getEra(id: string | undefined | null): Era | undefined {
   if (!id) return undefined
-  return eraById.get(id)
+  return overlayEntry("era", id, eraById.get(id))
 }
 
 export function getEraLabel(id: string | undefined | null, fallback?: string): string {

package/src/exposure-settings.ts

@@ -20,6 +20,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type ExposureCategory = "aperture" | "shutter-speed" | "iso"
 
@@ -97,7 +98,7 @@ const exposureById = new Map<string, ExposureSettings>(
 
 export function getExposure(id: string | undefined | null): ExposureSettings | undefined {
   if (!id) return undefined
-  return exposureById.get(id)
+  return overlayEntry("exposure-settings", id, exposureById.get(id))
 }
 
 export function getExposureLabel(id: string | undefined | null, fallback?: string): string {

package/src/framing.ts

@@ -10,6 +10,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type FramingCategory =
   | "shot-size"
@@ -568,7 +569,7 @@ const framingById = new Map<string, Framing>(FRAMINGS.map((f) => [f.id, f]))
 
 export function getFraming(id: string | undefined | null): Framing | undefined {
   if (!id) return undefined
-  return framingById.get(id)
+  return overlayEntry("framing", id, framingById.get(id))
 }
 
 export function getFramingLabel(id: string | undefined | null, fallback?: string): string {

package/src/held-prop.ts

@@ -23,6 +23,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type HeldPropCategory =
   | "device"
@@ -142,7 +143,7 @@ const heldPropById = new Map<string, HeldProp>(HELD_PROPS.map((p) => [p.id, p]))
 
 export function getHeldProp(id: string | undefined | null): HeldProp | undefined {
   if (!id) return undefined
-  return heldPropById.get(id)
+  return overlayEntry("held-prop", id, heldPropById.get(id))
 }
 
 export function getHeldPropLabel(id: string | undefined | null, fallback?: string): string {

package/src/index.ts

@@ -35,8 +35,12 @@ export * from "./veo-i2v-inputs.js"
 export * from "./person.js"
 export * from "./picker-catalogs.js"
 export * from "./catalog-packs.js"
+export * from "./catalog-overlay.js"
+export * from "./shared-catalog-overlay.js"
+export * from "./catalog-id-guard.js"
 export * from "./catalog-sidecar-coverage.js"
 export * from "./person-packs.js"
+export * from "./age-floor.js"
 export * from "./picker-analyzer-registry.js"
 export * from "./action-fx.js"
 export * from "./aesthetic.js"

package/src/instrumentation.ts

@@ -273,16 +273,16 @@ const VOCAL_BY_ID = new Map(VOCAL_PRESENCE.map((x) => [x.id, x]))
 const SINGING_STYLE_BY_ID = new Map(SINGING_STYLES.map((x) => [x.id, x]))
 
 export function getInstrument(id: string | undefined): CategorizedInstrument | undefined {
-  return id ? INSTRUMENT_BY_ID.get(id) : undefined
+  return id ? overlayEntry("instrumentation", id, INSTRUMENT_BY_ID.get(id)) : undefined
 }
 export function getProductionStyle(id: string | undefined): InstrumentationEntry | undefined {
-  return id ? PRODUCTION_BY_ID.get(id) : undefined
+  return id ? overlayEntry("instrumentation", id, PRODUCTION_BY_ID.get(id)) : undefined
 }
 export function getVocalPresence(id: string | undefined): InstrumentationEntry | undefined {
-  return id ? VOCAL_BY_ID.get(id) : undefined
+  return id ? overlayEntry("instrumentation", id, VOCAL_BY_ID.get(id)) : undefined
 }
 export function getSingingStyle(id: string | undefined): InstrumentationEntry | undefined {
-  return id ? SINGING_STYLE_BY_ID.get(id) : undefined
+  return id ? overlayEntry("instrumentation", id, SINGING_STYLE_BY_ID.get(id)) : undefined
 }
 
 /**
@@ -306,6 +306,7 @@ export function getSingingStyleTerm(id: string | undefined | null): string {
 }
 
 import { pickIds } from "@nodaro/shared"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export function buildInstrumentationHints(
   data: {

package/src/lens.ts

@@ -11,6 +11,7 @@
  */
 
 import { resolveTerm } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export interface Lens {
   readonly id: string
@@ -53,7 +54,7 @@ const lensById = new Map<string, Lens>(LENSES.map((l) => [l.id, l]))
 
 export function getLens(id: string | undefined | null): Lens | undefined {
   if (!id) return undefined
-  return lensById.get(id)
+  return overlayEntry("lens", id, lensById.get(id))
 }
 
 export function getLensLabel(id: string | undefined | null, fallback?: string): string {

package/src/lighting.ts

@@ -11,6 +11,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type LightingCategory =
   | "time-of-day"
@@ -143,7 +144,7 @@ const lightingById = new Map<string, Lighting>(LIGHTINGS.map((l) => [l.id, l]))
 
 export function getLighting(id: string | undefined | null): Lighting | undefined {
   if (!id) return undefined
-  return lightingById.get(id)
+  return overlayEntry("lighting", id, lightingById.get(id))
 }
 
 export function getLightingLabel(id: string | undefined | null, fallback?: string): string {

package/src/loop-subject.ts

@@ -19,6 +19,7 @@
  */
 
 import { resolveTerm } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type LoopSubjectCategory = "realistic" | "abstract"
 
@@ -280,7 +281,8 @@ export const LOOP_SUBJECTS: ReadonlyArray<LoopSubject> = [
 ]
 
 export function getLoopSubject(id: string | undefined | null): LoopSubject | undefined {
-  return LOOP_SUBJECTS.find((s) => s.id === id)
+  if (!id) return undefined
+  return overlayEntry("loop-subject", id, LOOP_SUBJECTS.find((s) => s.id === id))
 }
 
 export function getLoopSubjectLabel(id: string): string {

package/src/materials.ts

@@ -24,6 +24,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type MaterialCategory =
   | "fabric"
@@ -139,7 +140,7 @@ const materialById = new Map<string, Material>(MATERIALS.map((m) => [m.id, m]))
 
 export function getMaterial(id: string | undefined | null): Material | undefined {
   if (!id) return undefined
-  return materialById.get(id)
+  return overlayEntry("materials", id, materialById.get(id))
 }
 
 export function getMaterialLabel(id: string | undefined | null, fallback?: string): string {

package/src/mood.ts

@@ -24,6 +24,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type MoodCategory = "positive" | "negative" | "neutral" | "intense"
 
@@ -33,6 +34,16 @@ export interface Mood {
   readonly category: MoodCategory
   readonly description: string
   readonly promptHint: string
+  /**
+   * W1-a minor-age floor (spec 2026-09-01 §3.3). `true` marks an entry whose
+   * hint describes body exposure, sheer/wet clothing, swimwear/lingerie, a
+   * seductive expression or gaze, or a body-placed tattoo. The fragment
+   * collectors DROP flagged entries for a minor subject (`isMinorAge`), the
+   * picker hides their tiles, the analyzer never emits them, and the backend
+   * policy strips their wording from free text. Hand-curated; the
+   * `adult-only-ratchet` test only ratchets. Never set on neutral defaults.
+   */
+  readonly adultOnly?: true
   /**
    * Compact professional term injected in compact hint mode (see `term.ts`).
    *
@@ -91,10 +102,10 @@ export const MOODS: ReadonlyArray<Mood> = [
   { id: "determined",  label: "Determined",   category: "intense",  description: "Resolute, focused will",      promptHint: "with a determined, resolute expression and iron focus", term: "determined, resolute expression" },
   { id: "passionate",  label: "Passionate",   category: "intense",  description: "Burning passion",             promptHint: "with a passionate, burning expression full of conviction", term: "passionate expression" },
   { id: "brooding",    label: "Brooding",     category: "intense",  description: "Dark, brooding melancholy",   promptHint: "with a brooding, dark expression and moody introspection", term: "brooding expression" },
-  { id: "seductive",   label: "Seductive",    category: "intense",  description: "Alluring, seductive",         promptHint: "with a seductive, alluring expression and lidded gaze", term: "seductive expression" },
+  { id: "seductive",   label: "Seductive",    category: "intense",  description: "Alluring, seductive",         promptHint: "with a seductive, alluring expression and lidded gaze", term: "seductive expression" , adultOnly: true },
   { id: "defiant",     label: "Defiant",      category: "intense",  description: "Defiant, unyielding",         promptHint: "with a defiant, unyielding expression and challenging stance", term: "defiant expression" },
-  { id: "sultry",      label: "Sultry",       category: "intense",  description: "Smoldering, heavy-lidded",    promptHint: "with a sultry, smoldering expression, heavy-lidded gaze and lips softly parted", term: "sultry expression" },
-  { id: "smoldering",  label: "Smoldering",   category: "intense",  description: "Coiled, slow-burning intensity", promptHint: "with a smoldering, coiled expression, slow-burning intensity behind half-closed eyes and a still, predatory calm", term: "smoldering intensity" },
+  { id: "sultry",      label: "Sultry",       category: "intense",  description: "Smoldering, heavy-lidded",    promptHint: "with a sultry, smoldering expression, heavy-lidded gaze and lips softly parted", term: "sultry expression" , adultOnly: true },
+  { id: "smoldering",  label: "Smoldering",   category: "intense",  description: "Coiled, slow-burning intensity", promptHint: "with a smoldering, coiled expression, slow-burning intensity behind half-closed eyes and a still, predatory calm", term: "smoldering intensity" , adultOnly: true },
   { id: "sinister",    label: "Sinister",     category: "intense",  description: "Dark, malicious, threatening", promptHint: "with a sinister expression, a slow crooked smile and eyes glinting with dark malicious intent", term: "sinister expression" },
   { id: "wiccan-mystical", label: "Wiccan / Mystical", category: "intense", description: "Quietly otherworldly, occult", promptHint: "with a quietly mystical, otherworldly expression, eyes distant and knowing as if reading something the camera cannot see", term: "occult, otherworldly mystical expression" },
   { id: "lazy-shy",    label: "Lazy Shy",     category: "neutral",  description: "Drowsy, soft, half-shy",      promptHint: "with a soft, drowsy half-shy expression, eyes lowered and barely-there smile, languid and unbothered", term: "drowsy, half-shy expression" },
@@ -102,7 +113,7 @@ export const MOODS: ReadonlyArray<Mood> = [
   { id: "shocked",     label: "Shocked",      category: "intense",  description: "Surprised, mouth open",       promptHint: "with a shocked, surprised expression, eyes wide, brows raised and mouth open", term: "shocked expression" },
 
   // -------------------- Micro-emotions --------------------
-  { id: "flirty",      label: "Flirty",       category: "positive", description: "Playful flirtation, lingering smile, sustained eye contact", promptHint: "with a flirty expression, a lingering playful smile and sustained, knowing eye contact with the camera", term: "flirty expression" },
+  { id: "flirty",      label: "Flirty",       category: "positive", description: "Playful flirtation, lingering smile, sustained eye contact", promptHint: "with a flirty expression, a lingering playful smile and sustained, knowing eye contact with the camera", term: "flirty expression" , adultOnly: true },
   { id: "suspicious",  label: "Suspicious",   category: "negative", description: "Wary distrust, narrowed eyes, side-eye", promptHint: "with a suspicious, wary expression, eyes narrowed in distrust and a sidelong side-eye glance", term: "suspicious, wary expression" },
   { id: "resigned",    label: "Resigned",     category: "neutral",  description: "Quiet acceptance of an unpleasant situation, sigh", promptHint: "with a resigned expression of quiet acceptance, shoulders softly dropped mid-sigh and a tired half-closed gaze", term: "resigned expression of quiet acceptance" },
   { id: "conflicted",  label: "Conflicted",   category: "neutral",  description: "Visible internal struggle, brow furrowed, gaze unfocused", promptHint: "with a conflicted expression of visible internal struggle, brow furrowed and gaze unfocused, caught between two impulses", term: "conflicted, torn expression" },
@@ -112,7 +123,7 @@ const moodById = new Map<string, Mood>(MOODS.map((m) => [m.id, m]))
 
 export function getMood(id: string | undefined | null): Mood | undefined {
   if (!id) return undefined
-  return moodById.get(id)
+  return overlayEntry("mood", id, moodById.get(id))
 }
 
 export function getMoodLabel(id: string | undefined | null, fallback?: string): string {

package/src/music-genre.ts

@@ -15,6 +15,7 @@
 import { pickIds } from "@nodaro/shared"
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type MusicGenreCategory =
   | "hip-hop-rnb"
@@ -610,12 +611,12 @@ const ERA_BY_ID = new Map(MUSIC_ERAS.map((e) => [e.id, e]))
 
 export function getMusicGenre(id: string | undefined): MusicGenre | undefined {
   if (!id) return undefined
-  return GENRE_BY_ID.get(id)
+  return overlayEntry("music-genre", id, GENRE_BY_ID.get(id))
 }
 
 export function getMusicGenreLabel(id: string | undefined): string {
   if (!id) return ""
-  return GENRE_BY_ID.get(id)?.label ?? id
+  return getMusicGenre(id)?.label ?? id
 }
 
 export function getMusicSubgenre(
@@ -624,12 +625,12 @@ export function getMusicSubgenre(
 ): MusicSubgenre | undefined {
   if (!genreId || !subgenreId) return undefined
   const genre = GENRE_BY_ID.get(genreId)
-  return genre?.subgenres.find((s) => s.id === subgenreId)
+  return overlayEntry("music-genre", subgenreId, genre?.subgenres.find((s) => s.id === subgenreId))
 }
 
 export function getMusicEra(id: string | undefined): MusicEra | undefined {
   if (!id) return undefined
-  return ERA_BY_ID.get(id)
+  return overlayEntry("music-genre", id, ERA_BY_ID.get(id))
 }
 
 /**

package/src/music-mood.ts

@@ -6,6 +6,7 @@
 import { pickIds } from "@nodaro/shared"
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export interface MusicMoodEntry {
   readonly id: string
@@ -102,13 +103,13 @@ const EMOTION_BY_ID = new Map(MUSIC_EMOTIONS.map((x) => [x.id, x]))
 const VIBE_BY_ID = new Map(MUSIC_VIBES.map((x) => [x.id, x]))
 
 export function getMusicEnergy(id: string | undefined): MusicMoodEntry | undefined {
-  return id ? ENERGY_BY_ID.get(id) : undefined
+  return id ? overlayEntry("music-mood", id, ENERGY_BY_ID.get(id)) : undefined
 }
 export function getMusicEmotion(id: string | undefined): MusicMoodEntry | undefined {
-  return id ? EMOTION_BY_ID.get(id) : undefined
+  return id ? overlayEntry("music-mood", id, EMOTION_BY_ID.get(id)) : undefined
 }
 export function getMusicVibe(id: string | undefined): MusicMoodEntry | undefined {
-  return id ? VIBE_BY_ID.get(id) : undefined
+  return id ? overlayEntry("music-mood", id, VIBE_BY_ID.get(id)) : undefined
 }
 
 /**