@nodaro/shared 1.4.1

package/src/i18n/index.ts

@@ -0,0 +1,208 @@
+/**
+ * i18n resolver + lazy loader for parameter-node picker labels/descriptions.
+ *
+ * Usage from a picker component:
+ *
+ * ```ts
+ * const locale = useUserLocale()                              // current user-selected locale
+ * await ensureLocaleCatalogLoaded("styling", locale)          // call once per (catalog, locale), cached
+ * const localized = getLocalizedEntry("styling", entry.id, locale)
+ * const label = localized?.label ?? entry.label              // fallback to canonical English
+ * const description = localized?.description ?? entry.description
+ * ```
+ *
+ * For search filtering, use `entryMatchesQuery(entry, locale, query)` which
+ * filters across BOTH the canonical English text AND the localized text.
+ */
+
+import type { I18nCatalogId, LocaleCatalogMap, LocaleId, LocalizedEntry } from "./types.js"
+
+export * from "./types.js"
+
+/**
+ * In-memory cache of loaded locale catalogs. Key = `<catalog>:<locale>`.
+ * `undefined` = never loaded; `null` = loaded but missing/empty.
+ */
+const cache = new Map<string, LocaleCatalogMap | null>()
+const inflight = new Map<string, Promise<LocaleCatalogMap | null>>()
+
+function cacheKey(catalog: I18nCatalogId, locale: LocaleId): string {
+  return `${catalog}:${locale}`
+}
+
+/**
+ * Lazy-load a sidecar catalog. Returns `null` if the locale is `en` (no
+ * sidecar — English lives in the canonical catalog file) or if no sidecar
+ * file exists for that (catalog, locale) pair.
+ *
+ * Implementation note: the dynamic import string is constructed so that
+ * Vite can statically analyze the glob and code-split each locale into its
+ * own chunk. The `/* @vite-ignore *\/` comment is required because the
+ * locale variable defeats Vite's default static analysis; we accept the
+ * runtime resolution and rely on the glob-discovery at module init.
+ */
+export async function ensureLocaleCatalogLoaded(
+  catalog: I18nCatalogId,
+  locale: LocaleId,
+): Promise<LocaleCatalogMap | null> {
+  if (locale === "en") return null
+  const key = cacheKey(catalog, locale)
+  const cached = cache.get(key)
+  if (cached !== undefined) return cached
+  const existing = inflight.get(key)
+  if (existing) return existing
+  const promise = loadLocaleCatalog(catalog, locale).then(
+    (map) => {
+      cache.set(key, map)
+      inflight.delete(key)
+      return map
+    },
+    (err) => {
+      inflight.delete(key)
+      // Cache the failure as null so we don't retry forever
+      cache.set(key, null)
+      // Don't throw — missing sidecars are expected during gradual rollout;
+      // the picker just falls back to English.
+      console.warn(`[i18n] failed to load ${key}:`, err)
+      return null
+    },
+  )
+  inflight.set(key, promise)
+  return promise
+}
+
+/**
+ * Resolved value lookup. Reads from the in-memory cache; returns `undefined`
+ * if the locale's catalog hasn't been loaded yet (caller should await
+ * `ensureLocaleCatalogLoaded` first).
+ */
+export function getLocalizedEntry(
+  catalog: I18nCatalogId,
+  id: string,
+  locale: LocaleId,
+): LocalizedEntry | undefined {
+  if (locale === "en") return undefined
+  const map = cache.get(cacheKey(catalog, locale))
+  if (!map) return undefined
+  return map[id]
+}
+
+/**
+ * Synchronous resolver that returns the best label available right now.
+ * Falls back to `englishLabel` when no translation exists (or the locale
+ * sidecar isn't loaded yet).
+ */
+export function resolveLabel(
+  catalog: I18nCatalogId,
+  id: string,
+  englishLabel: string,
+  locale: LocaleId,
+): string {
+  if (locale === "en") return englishLabel
+  return getLocalizedEntry(catalog, id, locale)?.label ?? englishLabel
+}
+
+/**
+ * Synchronous resolver that returns the best description available now.
+ * Falls back to `englishDescription` when no translation exists.
+ */
+export function resolveDescription(
+  catalog: I18nCatalogId,
+  id: string,
+  englishDescription: string,
+  locale: LocaleId,
+): string {
+  if (locale === "en") return englishDescription
+  return getLocalizedEntry(catalog, id, locale)?.description ?? englishDescription
+}
+
+/**
+ * Search predicate: returns true if `query` matches either the canonical
+ * English label/description or the localized label/description for the
+ * current locale.
+ *
+ * Empty query always matches.
+ */
+export function entryMatchesQuery(
+  catalog: I18nCatalogId,
+  id: string,
+  englishLabel: string,
+  englishDescription: string,
+  locale: LocaleId,
+  query: string,
+): boolean {
+  const q = query.trim().toLowerCase()
+  if (!q) return true
+  if (englishLabel.toLowerCase().includes(q)) return true
+  if (englishDescription.toLowerCase().includes(q)) return true
+  if (locale === "en") return false
+  const localized = getLocalizedEntry(catalog, id, locale)
+  if (!localized) return false
+  if (localized.label && localized.label.toLowerCase().includes(q)) return true
+  if (localized.description && localized.description.toLowerCase().includes(q)) return true
+  return false
+}
+
+/**
+ * Sidecar loader registry. Populated by the consuming app via
+ * `registerSidecarLoaders` at startup.
+ *
+ * Why externalised: this package is bundled by tsup for npm publish, and
+ * `tsup` does NOT expand Vite's `import.meta.glob`. Calling it from inside
+ * the bundled module yields an empty loader map at runtime → all pickers
+ * silently fall back to English regardless of the user's locale.
+ *
+ * The frontend (which is processed by Vite) owns the glob — see
+ * `frontend/src/lib/i18n-bootstrap.ts`. Backend / Node tests don't need
+ * picker translations and simply skip registration.
+ *
+ * Keys are file paths relative to `packages/shared/src/i18n/`, e.g.
+ * `"./person.ja.ts"`.
+ */
+type SidecarModule = { default?: LocaleCatalogMap } & Record<string, unknown>
+export type SidecarLoader = () => Promise<unknown>
+
+let sidecarLoaders: Record<string, SidecarLoader> = {}
+
+/**
+ * Register the map of locale-sidecar loaders. Call once at app startup
+ * before any picker mounts.
+ *
+ * In Vite-processed code:
+ * ```ts
+ * import { registerSidecarLoaders } from "@nodaro/shared"
+ * registerSidecarLoaders(
+ *   import.meta.glob("../../packages/shared/src/i18n/*.*.ts"),
+ * )
+ * ```
+ */
+export function registerSidecarLoaders(loaders: Record<string, SidecarLoader>): void {
+  sidecarLoaders = loaders
+}
+
+async function loadLocaleCatalog(
+  catalog: I18nCatalogId,
+  locale: LocaleId,
+): Promise<LocaleCatalogMap | null> {
+  if (locale === "en") return null
+  // Match by suffix so the registry survives different glob roots —
+  // frontend's bootstrap globs from a different relative path than
+  // this file lives at, so keys look like ".../i18n/person.ja.ts".
+  const suffix = `${catalog}.${locale}.ts`
+  const matchKey = Object.keys(sidecarLoaders).find((k) =>
+    k.endsWith(`/${suffix}`) || k === `./${suffix}`,
+  )
+  const loader = matchKey ? sidecarLoaders[matchKey] : undefined
+  if (!loader) return null
+  try {
+    const mod = (await loader()) as SidecarModule
+    if (mod.default && typeof mod.default === "object") return mod.default
+    // Fallback: convention-named export (e.g. STYLING_FR)
+    const conventional = `${catalog.toUpperCase().replace(/-/g, "_")}_${locale.toUpperCase().replace(/-/g, "_")}`
+    const named = mod[conventional]
+    if (named && typeof named === "object") return named as LocaleCatalogMap
+    return null
+  } catch {
+    return null
+  }
+}

package/src/i18n/instrumentation.ar.ts

@@ -0,0 +1,195 @@
+import type { LocaleCatalogMap } from "./types.js"
+
+const map: LocaleCatalogMap = {
+  // -------------------- INSTRUMENTS: Drums --------------------
+  "drums": { label: "طبول", description: "طقم طبول صوتي" },
+  "drum-machine": { label: "آلة الطبول", description: "إيقاعات مبرمجة" },
+  "808": { description: "باس وطقم Roland TR-808" },
+  "live-drums": { label: "طبول حية", description: "طقم صوتي مسجل" },
+  "breakbeats": { label: "بريك بيتس", description: "حلقات طبول مأخوذة كعينات" },
+  "trap-drums": { label: "طبول تراب", description: "تتابعات هاي هات + 808" },
+
+  // -------------------- INSTRUMENTS: Percussion --------------------
+  "bongos": { label: "بونغو", description: "زوج من الطبول الكوبية الصغيرة" },
+  "conga": { label: "كونغا", description: "طبل عالٍ بوجه واحد" },
+  "djembe": { label: "جمبي", description: "طبل على شكل كأس من غرب أفريقيا" },
+  "timbales": { label: "تيمبالس", description: "طبول معدنية كوبية مزدوجة" },
+  "tambourine": { label: "دف", description: "صنوج تُهز باليد" },
+  "shaker": { label: "هزّاز", description: "خشخيشة معبأة" },
+  "cowbell": { label: "جرس البقرة", description: "جرس بقرة محمول باليد" },
+  "maracas": { label: "ماراكاس", description: "زوج هزازات لاتينية" },
+  "claves": { label: "كلاڤيس", description: "عصي خشبية" },
+  "marimba": { label: "ماريمبا", description: "لوحة مفاتيح بمطارق خشبية" },
+  "vibraphone": { label: "ڤيبرافون", description: "مطرقة برنان كهربائي" },
+  "xylophone": { label: "إكسيلوفون", description: "مطرقة خشبية، صوت ساطع" },
+  "glockenspiel": { label: "غلوكنشپيل", description: "أجراس مطرقة عالية النبرة" },
+  "timpani": { label: "تيمباني", description: "طبل أوركسترالي كبير" },
+  "taiko": { label: "تايكو", description: "طبل فرقة ياباني" },
+  "frame-drum": { label: "طبل إطاري", description: "طبل دائري ضحل" },
+  "cajon": { label: "كاخون", description: "طبل بيروفي على شكل صندوق" },
+  "darbuka": { label: "دربوكة", description: "طبل كأسي من الشرق الأوسط" },
+
+  // -------------------- INSTRUMENTS: Keys --------------------
+  "piano": { label: "بيانو", description: "بيانو كبير أو قائم صوتي" },
+  "electric-piano": { label: "بيانو كهربائي", description: "بأسلوب Rhodes / Wurlitzer" },
+  "wurlitzer": { description: "بيانو كهربائي Wurlitzer كلاسيكي" },
+  "rhodes": { description: "بيانو كهربائي Rhodes كلاسيكي" },
+  "clavinet": { label: "كلاڤينيت", description: "Hohner D6 فانكي" },
+  "organ": { label: "أرغن", description: "Hammond أو أرغن أنابيب" },
+  "hammond-organ": { description: "أرغن B3 سول / روك" },
+  "pipe-organ": { label: "أرغن الأنابيب", description: "كاتدرائية / كنيسة" },
+  "accordion": { label: "أكورديون", description: "قصبات يحركها منفاخ" },
+  "mellotron": { label: "ميلوترون", description: "لوحة مفاتيح بحلقات شريط" },
+  "harpsichord": { label: "هاربسيكورد", description: "لوحة مفاتيح بأوتار منقورة" },
+  "celesta": { label: "سيليستا", description: "لوحة مفاتيح بصوت أجراس" },
+
+  // -------------------- INSTRUMENTS: Synth --------------------
+  "synthesizer": { label: "مؤلف توليفي", description: "مؤلف تناظري أو رقمي" },
+  "lead-synth": { label: "سينث رئيسي", description: "سينث لحني حاد" },
+  "pluck-synth": { label: "سينث منقور", description: "نغمة قصيرة منقورة" },
+  "pads": { label: "وسائد سينث", description: "نسيج سينث ممتد" },
+  "arpeggiator": { label: "أربيجياتور", description: "أنماط أربيجيو متسلسلة" },
+  "vocoder": { description: "سينث معدّل بالصوت" },
+  "talkbox": { description: "سينث مشكّل بالفم" },
+  "modular-synth": { label: "موديولاري", description: "سينث تناظري قابل للتوصيل" },
+  "fm-synth": { label: "سينث FM", description: "سينث تعديل التردد" },
+  "wavetable-synth": { label: "ويڤتيبل", description: "سينث مسح جدول الموجات" },
+  "stab-synth": { label: "ستاب", description: "وتر قصير إيقاعي" },
+
+  // -------------------- INSTRUMENTS: Guitar --------------------
+  "acoustic-guitar": { label: "جيتار صوتي", description: "أوتار فولاذية أو نايلون" },
+  "electric-guitar": { label: "جيتار كهربائي", description: "جسم صلب، غالباً مشوّه" },
+  "classical-guitar": { label: "جيتار كلاسيكي", description: "أوتار نايلون، نقر بالأصابع" },
+  "12-string-guitar": { label: "جيتار 12 وتراً", description: "ضرب بأوتار مزدوجة" },
+  "pedal-steel": { label: "بيدال ستيل", description: "ستيل انزلاقي ريفي" },
+  "lap-steel": { label: "لاب ستيل", description: "ستيل هاواي على الحجر" },
+  "dobro": { label: "دوبرو", description: "جيتار رنّان" },
+  "banjo": { label: "بانجو", description: "5 أوتار أو تينور" },
+  "mandolin": { label: "ماندولين", description: "فولك / بلوغراس" },
+  "ukulele": { label: "يوكوليلي", description: "يوكوليلي سوبرانو-تينور" },
+
+  // -------------------- INSTRUMENTS: Bass --------------------
+  "bass-guitar": { label: "جيتار باس", description: "باس كهربائي منخفض النبرة" },
+  "synth-bass": { label: "باس سينث", description: "ترددات منخفضة مولّفة" },
+  "sub-bass": { label: "ساب باس", description: "ترددات ساب جيبية عميقة" },
+  "acoustic-bass": { label: "باس صوتي", description: "جيتار باس صوتي" },
+  "upright-bass": { label: "كونترباص قائم", description: "كونترباص، أسلوب جاز" },
+  "fretless-bass": { label: "باس بدون عتبات", description: "جيتار باس انزلاقي" },
+  "acid-bass": { label: "باس أسيد", description: "TB-303 squelch" },
+  "wobble-bass": { label: "باس ووبل", description: "دبستب معدّل بـ LFO" },
+  "reese-bass": { label: "باس Reese", description: "دروم آند باس مفكوك التوليف" },
+
+  // -------------------- INSTRUMENTS: Brass --------------------
+  "brass": { label: "قسم النحاسيات", description: "بوق، ترومبون، إلخ" },
+  "trumpet": { label: "بوق", description: "بوق منفرد" },
+  "trombone": { label: "ترومبون", description: "ترومبون منفرد" },
+  "french-horn": { label: "بوق فرنسي", description: "نحاس ناعم" },
+  "tuba": { label: "توبا", description: "أدنى النحاسيات نبرة" },
+  "saxophone": { label: "ساكسوفون", description: "ساكسوفون منفرد أو في قسم" },
+  "flugelhorn": { label: "فلوغلهورن", description: "ابن عم البوق الناعم" },
+  "cornet": { label: "كورنيت", description: "كورنيت فرقة نحاسية" },
+  "muted-trumpet": { label: "بوق مكتوم", description: "بوق جاز مكتوم" },
+
+  // -------------------- INSTRUMENTS: Woodwinds --------------------
+  "flute": { label: "فلوت", description: "فلوت حفلات" },
+  "clarinet": { label: "كلارينت", description: "كلارينت منفرد" },
+  "harmonica": { label: "هارمونيكا", description: "هارمونيكا بلوز" },
+  "oboe": { label: "أوبوا", description: "تحركه قصبة، حزين" },
+  "bassoon": { label: "باسون", description: "قصبة مزدوجة منخفضة" },
+  "english-horn": { label: "بوق إنجليزي", description: "أوبوا تينور" },
+  "piccolo": { label: "بيكولو", description: "فلوت عالي النبرة" },
+  "recorder": { label: "ريكوردر", description: "آلة نفخ خشبية ناعمة الصوت" },
+  "pan-flute": { label: "فلوت بان", description: "فلوت أنابيب من الأنديز" },
+
+  // -------------------- INSTRUMENTS: Strings --------------------
+  "strings": { label: "قسم الأوتار", description: "قسم أوتار أوركسترالي" },
+  "violin": { label: "كمان", description: "كمان منفرد" },
+  "viola": { label: "ڤيولا", description: "ڤيولا منفردة" },
+  "cello": { label: "تشيلو", description: "تشيلو منفرد" },
+  "double-bass": { label: "كونترباص", description: "كونترباص أوركسترالي" },
+  "harp": { label: "قيثارة", description: "قيثارة حفلات أو فولك" },
+  "pizzicato-strings": { label: "بيتزيكاتو", description: "أوتار منقورة" },
+  "staccato-strings": { label: "ستاكاتو", description: "أوتار قصيرة وقوية" },
+  "fiddle": { label: "كمان فولك", description: "كمان بأسلوب فولك" },
+
+  // -------------------- INSTRUMENTS: World --------------------
+  "sitar": { label: "سيتار", description: "آلة هندية ذات رقبة طويلة" },
+  "tabla": { label: "تابلا", description: "طبول يدوية هندية" },
+  "steel-drum": { label: "طبل فولاذي", description: "ستيل بان من ترينيداد" },
+  "kalimba": { label: "كاليمبا", description: "بيانو الإبهام الأفريقي" },
+  "bagpipes": { label: "مزمار القربة", description: "مزمار القربة الاسكتلندي" },
+  "didgeridoo": { label: "ديدجريدو", description: "آلة نفخ أسترالية" },
+  "oud": { label: "عود", description: "عود شرق أوسطي" },
+  "erhu": { label: "إرهو", description: "كمان صيني ذو وترين" },
+  "koto": { label: "كوتو", description: "قانون ياباني" },
+  "shakuhachi": { label: "شاكوهاتشي", description: "فلوت ياباني ينفخ من الطرف" },
+  "shamisen": { label: "شاميسن", description: "عود ياباني ذو 3 أوتار" },
+  "duduk": { label: "دودوك", description: "قصبة مزدوجة أرمنية" },
+  "balalaika": { label: "بالالايكا", description: "عود روسي مثلث" },
+  "bouzouki": { label: "بوزوكي", description: "عود يوناني طويل العنق" },
+  "kora": { label: "كورا", description: "آلة 21 وتراً من غرب أفريقيا" },
+  "hang-drum": { label: "طبل هانغ", description: "هاندبان فولاذي" },
+
+  // -------------------- INSTRUMENTS: Middle Eastern --------------------
+  "kamancheh": { label: "كمنجة", description: "آلة وترية فارسية ذات قوس وسنّ" },
+  "ney": { label: "ناي", description: "ناي قصبي يُنفخ من الطرف (فارسي/عربي)" },
+  "santur": { label: "سنطور", description: "آلة وترية فارسية تُعزف بالمطارق" },
+
+  // -------------------- PRODUCTION_STYLES --------------------
+  "polished": { label: "مصقولة", description: "إنتاج نقي وسائد" },
+  "lo-fi": { description: "هسهسة شريط دافئة، غير مثالية" },
+  "raw": { label: "خام", description: "بدون فلترة، إحساس مباشر" },
+  "vintage": { label: "كلاسيكي", description: "دفء تناظري" },
+  "modern": { label: "حديث", description: "رقمي معاصر" },
+  "minimalist": { label: "بساطة", description: "متناثر، مقيّد" },
+  "wall-of-sound": { label: "جدار الصوت", description: "كثيف، متعدد الطبقات" },
+  "ambient": { label: "أمبيانت", description: "جو، مع تردد صدى" },
+  "garage-band": { label: "فرقة الكراج", description: "DIY، مسجل في القبو" },
+  "live-recording": { label: "حي", description: "صوت حفل / غرفة" },
+  "demo-quality": { label: "ديمو", description: "جمالية ديمو خام" },
+  "studio-pristine": { label: "استوديو نقي", description: "جودة مرجعية هاي فاي" },
+  "tape-saturated": { label: "شريط مشبع", description: "دفء شريط تناظري + تشغيل" },
+  "8-bit-retro": { label: "8-bit ريترو", description: "صوت ألعاب ريترو منخفض المعدل" },
+
+  // -------------------- VOCAL_PRESENCE --------------------
+  "instrumental": { label: "آلي", description: "بدون غناء (حصري)" },
+  "male-lead": { label: "غناء رجالي رئيسي", description: "غناء رجالي رئيسي" },
+  "female-lead": { label: "غناء نسائي رئيسي", description: "غناء نسائي رئيسي" },
+  "androgynous-lead": { label: "محايد جنسياً", description: "غناء رئيسي محايد جنسياً" },
+  "duet": { label: "ثنائي", description: "مغنيان رئيسيان" },
+  "choir": { label: "جوقة", description: "غناء جوقة / مجموعة" },
+  "gospel-choir": { label: "جوقة غوسبل", description: "جوقة دعم بأسلوب غوسبل" },
+  "harmony-stack": { label: "تكديس الهارمونيات", description: "هارمونيات صوتية مكدسة" },
+  "rapper-lead": { label: "مؤدي راب", description: "راب رئيسي" },
+  "spoken-word": { label: "كلمة منطوقة", description: "إلقاء / شعر فوق الموسيقى" },
+  "vocal-chops": { label: "قطع صوتية", description: "أصوات مأخوذة كعينات ومقطعة" },
+  "mixed": { label: "مختلط", description: "عدة مغنين رئيسيين" },
+
+  // -------------------- SINGING_STYLES --------------------
+  "pop-singing": { description: "أسلوب رئيسي سائد" },
+  "rock-singing": { description: "أداء صوتي بأسلوب الروك" },
+  "operatic": { label: "أوبرالي", description: "تقنية أوبرا كلاسيكية" },
+  "classical-vocals": { label: "كلاسيكي", description: "صوت كلاسيكي مدرّب" },
+  "rap": { label: "راب", description: "أداء منطوق إيقاعي" },
+  "trap-melodic": { label: "تراب (لحني)", description: "تراب لحني مع أوتو تيون" },
+  "growl": { label: "غراول", description: "غراول بأسلوب ديث ميتال" },
+  "scream": { label: "صراخ", description: "هاردكور / مصروخ" },
+  "shout": { label: "نداء", description: "نداء بانك / مرتل" },
+  "falsetto": { label: "فالسيتو", description: "نطاق عالٍ، خفيف" },
+  "head-voice": { label: "صوت الرأس", description: "نطاق عالٍ رنّان" },
+  "chest-voice": { label: "صوت الصدر", description: "نطاق منخفض قوي" },
+  "belting": { label: "بلتنغ", description: "نغمات عالية قوية ممتدة" },
+  "crooning": { label: "كرونينغ", description: "رومانسي كلاسيكي ناعم" },
+  "scat": { label: "سكات", description: "مقاطع جاز مرتجلة" },
+  "yodeling": { label: "يودلينغ", description: "تحول النطاق الألبي" },
+  "throat-singing": { label: "غناء الحلق", description: "نغمات إضافية منغولية / توڤانية" },
+  "melismatic": { label: "ميليسماتي", description: "جريات متعددة النغمات لكل مقطع" },
+  "autotuned": { label: "مضبوط بالأوتو تيون", description: "غناء مصحح الطبقة، معالج" },
+  "vocoded": { label: "معالج بالڤوكودر", description: "أصوات معالجة بالڤوكودر" },
+  "whisper-singing": { label: "غناء همسي", description: "غناء هادئ وحميمي" },
+  "breathy-singing": { label: "نَفَسي", description: "غناء هوائي حميمي" },
+  "harmonized": { label: "متناغم", description: "هارمونيات متعددة الأصوات" },
+  "chant": { label: "ترتيل", description: "ترتيل ليتورجي / رهباني" },
+}
+
+export default map

package/src/i18n/instrumentation.de.ts

@@ -0,0 +1,195 @@
+import type { LocaleCatalogMap } from "./types.js"
+
+const map: LocaleCatalogMap = {
+  // -------------------- INSTRUMENTS: Drums --------------------
+  "drums": { label: "Schlagzeug", description: "Akustisches Schlagzeug" },
+  "drum-machine": { label: "Drumcomputer", description: "Programmierte Beats" },
+  "808": { description: "Roland TR-808 Bass + Kit" },
+  "live-drums": { label: "Live-Schlagzeug", description: "Aufgenommenes akustisches Kit" },
+  "breakbeats": { description: "Gesampelte Drum-Loops" },
+  "trap-drums": { label: "Trap-Drums", description: "Hi-Hat-Rolls + 808" },
+
+  // -------------------- INSTRUMENTS: Percussion --------------------
+  "bongos": { description: "Paar kleine kubanische Trommeln" },
+  "conga": { description: "Hohe einfellige Trommel" },
+  "djembe": { label: "Djembé", description: "Becherförmige westafrikanische Trommel" },
+  "timbales": { description: "Kubanisches Metalltrommel-Paar" },
+  "tambourine": { label: "Tamburin", description: "Mit der Hand geschüttelte Schellen" },
+  "shaker": { description: "Gefüllte Rassel" },
+  "cowbell": { label: "Kuhglocke", description: "Handgehaltene Kuhglocke" },
+  "maracas": { description: "Lateinamerikanisches Shaker-Paar" },
+  "claves": { description: "Holzstäbe" },
+  "marimba": { description: "Holzschlägel-Tastatur" },
+  "vibraphone": { label: "Vibraphon", description: "Schlägel mit elektrischem Resonator" },
+  "xylophone": { label: "Xylophon", description: "Holzschlägel, hell" },
+  "glockenspiel": { description: "Hohe Schlägelglocken" },
+  "timpani": { label: "Pauken", description: "Große Orchesterpauke" },
+  "taiko": { description: "Japanische Ensemble-Trommel" },
+  "frame-drum": { label: "Rahmentrommel", description: "Flache runde Trommel" },
+  "cajon": { label: "Cajón", description: "Boxförmige peruanische Trommel" },
+  "darbuka": { label: "Darbuka", description: "Nahöstliche Kelchtrommel" },
+
+  // -------------------- INSTRUMENTS: Keys --------------------
+  "piano": { label: "Klavier", description: "Akustischer Flügel oder Pianino" },
+  "electric-piano": { label: "E-Piano", description: "Rhodes-/Wurlitzer-Stil" },
+  "wurlitzer": { description: "Vintage Wurlitzer E-Piano" },
+  "rhodes": { description: "Vintage Rhodes E-Piano" },
+  "clavinet": { description: "Funky Hohner D6" },
+  "organ": { label: "Orgel", description: "Hammond oder Pfeifenorgel" },
+  "hammond-organ": { description: "Soul/Rock B3-Orgel" },
+  "pipe-organ": { label: "Pfeifenorgel", description: "Kathedrale / Kirche" },
+  "accordion": { label: "Akkordeon", description: "Balgbetriebenes Rohrblatt" },
+  "mellotron": { description: "Tape-Loop-Tastatur" },
+  "harpsichord": { label: "Cembalo", description: "Tastatur mit gezupften Saiten" },
+  "celesta": { description: "Glockenähnliche Tastatur" },
+
+  // -------------------- INSTRUMENTS: Synth --------------------
+  "synthesizer": { description: "Analoger oder digitaler Synth" },
+  "lead-synth": { label: "Lead-Synth", description: "Schneidender melodischer Synth" },
+  "pluck-synth": { label: "Pluck-Synth", description: "Kurze, gezupfte Klangfarbe" },
+  "pads": { label: "Synth-Pads", description: "Gehaltene Synth-Texturen" },
+  "arpeggiator": { description: "Sequenzierte Arp-Pattern" },
+  "vocoder": { description: "Stimmmodulierter Synth" },
+  "talkbox": { description: "Mundgeformter Synth" },
+  "modular-synth": { label: "Modular", description: "Patchbarer Analog-Synth" },
+  "fm-synth": { description: "Frequenzmodulations-Synth" },
+  "wavetable-synth": { label: "Wavetable", description: "Wavetable-Scanning-Synth" },
+  "stab-synth": { label: "Stab", description: "Kurzer, perkussiver Akkord" },
+
+  // -------------------- INSTRUMENTS: Guitar --------------------
+  "acoustic-guitar": { label: "Akustische Gitarre", description: "Stahl- oder Nylonsaiten" },
+  "electric-guitar": { label: "E-Gitarre", description: "Solid-Body, oft verzerrt" },
+  "classical-guitar": { label: "Klassische Gitarre", description: "Nylonsaiten, Fingerstyle" },
+  "12-string-guitar": { label: "12-Saiten-Gitarre", description: "Doppelchörige Schlaggitarre" },
+  "pedal-steel": { description: "Country-Gleitsteel" },
+  "lap-steel": { description: "Hawaiianische Schoßsteel" },
+  "dobro": { description: "Resonator-Gitarre" },
+  "banjo": { description: "5-saitig oder Tenor" },
+  "mandolin": { label: "Mandoline", description: "Folk / Bluegrass" },
+  "ukulele": { description: "Sopran-Tenor-Uke" },
+
+  // -------------------- INSTRUMENTS: Bass --------------------
+  "bass-guitar": { label: "Bassgitarre", description: "Tieffrequenter E-Bass" },
+  "synth-bass": { label: "Synth-Bass", description: "Synthetisierte Tiefen" },
+  "sub-bass": { description: "Tiefe Sinus-Sub-Frequenzen" },
+  "acoustic-bass": { label: "Akustikbass", description: "Akustische Bassgitarre" },
+  "upright-bass": { label: "Kontrabass", description: "Kontrabass, Jazz-Stil" },
+  "fretless-bass": { description: "Bundlose, gleitende Bassgitarre" },
+  "acid-bass": { description: "TB-303-Squelch" },
+  "wobble-bass": { description: "LFO-modulierter Dubstep" },
+  "reese-bass": { description: "Verstimmter Drum-and-Bass" },
+
+  // -------------------- INSTRUMENTS: Brass --------------------
+  "brass": { label: "Bläsersatz", description: "Trompete, Posaune usw." },
+  "trumpet": { label: "Trompete", description: "Solo-Trompete" },
+  "trombone": { label: "Posaune", description: "Solo-Posaune" },
+  "french-horn": { label: "Waldhorn", description: "Weiche Blechbläser" },
+  "tuba": { description: "Tiefste Blechbläser" },
+  "saxophone": { label: "Saxophon", description: "Solo- oder Sektions-Sax" },
+  "flugelhorn": { label: "Flügelhorn", description: "Weicher Trompeten-Verwandter" },
+  "cornet": { label: "Kornett", description: "Brassband-Kornett" },
+  "muted-trumpet": { label: "Gedämpfte Trompete", description: "Gedämpfte Jazz-Trompete" },
+
+  // -------------------- INSTRUMENTS: Woodwinds --------------------
+  "flute": { label: "Flöte", description: "Konzertflöte" },
+  "clarinet": { label: "Klarinette", description: "Solo-Klarinette" },
+  "harmonica": { label: "Mundharmonika", description: "Blues-Harp" },
+  "oboe": { description: "Rohrblatt-getrieben, klagend" },
+  "bassoon": { label: "Fagott", description: "Tiefes Doppelrohrblatt" },
+  "english-horn": { label: "Englischhorn", description: "Tenor-Oboe" },
+  "piccolo": { label: "Piccoloflöte", description: "Hohe Flöte" },
+  "recorder": { label: "Blockflöte", description: "Weich klingendes Holzblasinstrument" },
+  "pan-flute": { label: "Panflöte", description: "Andine Pfeifenflöte" },
+
+  // -------------------- INSTRUMENTS: Strings --------------------
+  "strings": { label: "Streichersatz", description: "Orchestraler Streichersatz" },
+  "violin": { label: "Violine", description: "Solo-Violine" },
+  "viola": { label: "Bratsche", description: "Solo-Bratsche" },
+  "cello": { description: "Solo-Cello" },
+  "double-bass": { label: "Kontrabass", description: "Orchestraler Kontrabass" },
+  "harp": { label: "Harfe", description: "Konzert- oder Folk-Harfe" },
+  "pizzicato-strings": { label: "Pizzicato", description: "Gezupfte Streicher" },
+  "staccato-strings": { label: "Staccato", description: "Kurze, knackige Streicher" },
+  "fiddle": { label: "Fiedel", description: "Folk-Stil-Violine" },
+
+  // -------------------- INSTRUMENTS: World --------------------
+  "sitar": { description: "Indisches Instrument mit langem Hals" },
+  "tabla": { description: "Indische Handtrommeln" },
+  "steel-drum": { label: "Steeldrum", description: "Trinidadisches Steelpan" },
+  "kalimba": { description: "Afrikanisches Daumenklavier" },
+  "bagpipes": { label: "Dudelsack", description: "Schottischer Dudelsack" },
+  "didgeridoo": { description: "Australisches Blasinstrument" },
+  "oud": { description: "Nahöstliche Laute" },
+  "erhu": { description: "Chinesische 2-saitige Fiedel" },
+  "koto": { description: "Japanische Zither" },
+  "shakuhachi": { description: "Japanische Längsflöte" },
+  "shamisen": { description: "Japanische 3-saitige Laute" },
+  "duduk": { description: "Armenisches Doppelrohrblatt" },
+  "balalaika": { description: "Russische dreieckige Laute" },
+  "bouzouki": { description: "Griechische langhalsige Laute" },
+  "kora": { description: "Westafrikanisches 21-Saiten-Instrument" },
+  "hang-drum": { description: "Stahl-Handpan" },
+
+  // -------------------- INSTRUMENTS: Middle Eastern --------------------
+  "kamancheh": { description: "Persische Stachelgeige mit Bogen" },
+  "ney": { description: "Persisch/arabische endgeblasene Rohrflöte" },
+  "santur": { description: "Persisches Hackbrett" },
+
+  // -------------------- PRODUCTION_STYLES --------------------
+  "polished": { label: "Poliert", description: "Makellose, Mainstream-Produktion" },
+  "lo-fi": { description: "Warmes Bandrauschen, unvollkommen" },
+  "raw": { label: "Roh", description: "Ungefiltert, Live-Gefühl" },
+  "vintage": { description: "Analoge Wärme" },
+  "modern": { description: "Zeitgenössisch digital" },
+  "minimalist": { label: "Minimalistisch", description: "Sparsam, zurückhaltend" },
+  "wall-of-sound": { label: "Wall of Sound", description: "Dicht, geschichtet" },
+  "ambient": { description: "Atmosphärisch, hallig" },
+  "garage-band": { label: "Garagenband", description: "DIY, im Keller aufgenommen" },
+  "live-recording": { label: "Live", description: "Konzert-/Raumklang" },
+  "demo-quality": { label: "Demo", description: "Rohe Demo-Ästhetik" },
+  "studio-pristine": { label: "Studio-Brillanz", description: "Hi-Fi-Referenzqualität" },
+  "tape-saturated": { label: "Bandsättigung", description: "Analoge Bandwärme + Drive" },
+  "8-bit-retro": { description: "Niedrig aufgelöste Retro-Spielaudio" },
+
+  // -------------------- VOCAL_PRESENCE --------------------
+  "instrumental": { description: "Keine Vocals (exklusiv)" },
+  "male-lead": { label: "Männlicher Lead", description: "Männlicher Lead-Gesang" },
+  "female-lead": { label: "Weiblicher Lead", description: "Weiblicher Lead-Gesang" },
+  "androgynous-lead": { label: "Androgyn", description: "Geschlechtsneutraler Lead" },
+  "duet": { label: "Duett", description: "Zwei Lead-Sänger" },
+  "choir": { label: "Chor", description: "Chor- / Ensemblegesang" },
+  "gospel-choir": { label: "Gospelchor", description: "Gospel-Backing-Chor" },
+  "harmony-stack": { label: "Harmoniestapel", description: "Geschichtete Vocal-Harmonien" },
+  "rapper-lead": { label: "Rapper", description: "Rap-Lead" },
+  "spoken-word": { label: "Spoken Word", description: "Gesprochenes / Gedicht über Musik" },
+  "vocal-chops": { description: "Geschnittene Sample-Vocals" },
+  "mixed": { label: "Gemischt", description: "Mehrere Lead-Sänger" },
+
+  // -------------------- SINGING_STYLES --------------------
+  "pop-singing": { description: "Mainstream-Lead-Stil" },
+  "rock-singing": { description: "Rock-Stil-Gesangsdarbietung" },
+  "operatic": { label: "Opernhaft", description: "Klassische Operntechnik" },
+  "classical-vocals": { label: "Klassisch", description: "Geschulte klassische Stimme" },
+  "rap": { description: "Rhythmische gesprochene Darbietung" },
+  "trap-melodic": { label: "Trap (Melodisch)", description: "Melodischer Trap, autotune" },
+  "growl": { description: "Death-Metal-Style-Growl" },
+  "scream": { label: "Schrei", description: "Hardcore / geschrien" },
+  "shout": { label: "Ruf", description: "Punk- / Sprechgesang-Ruf" },
+  "falsetto": { label: "Falsett", description: "Hohe Lage, leicht" },
+  "head-voice": { label: "Kopfstimme", description: "Resonante hohe Lage" },
+  "chest-voice": { label: "Bruststimme", description: "Starke, tiefe Lage" },
+  "belting": { description: "Kraftvolle gehaltene Höhen" },
+  "crooning": { description: "Sanftes vintage-romantisches Singen" },
+  "scat": { label: "Scat-Gesang", description: "Improvisierte Jazz-Silben" },
+  "yodeling": { label: "Jodeln", description: "Alpiner Registerwechsel" },
+  "throat-singing": { label: "Kehlkopfgesang", description: "Mongolische / tuvinische Obertöne" },
+  "melismatic": { label: "Melismatisch", description: "Mehrtonläufe pro Silbe" },
+  "autotuned": { label: "Autogetuned", description: "Tonhöhenkorrigiert, bearbeitet" },
+  "vocoded": { label: "Vocodiert", description: "Vocoder-bearbeitete Vocals" },
+  "whisper-singing": { label: "Flüstergesang", description: "Gedämpftes, intimes Singen" },
+  "breathy-singing": { label: "Hauchig", description: "Luftiges, intimes Singen" },
+  "harmonized": { label: "Harmonisiert", description: "Mehrstimmige Harmonien" },
+  "chant": { label: "Choralgesang", description: "Liturgischer / Mönchsgesang" },
+}
+
+export default map