@nodaro/prompts 1.26.1 → 1.28.0

package/src/picker-art/sound-art-types.ts

@@ -0,0 +1,19 @@
+/** The dimension fields of each music / voice catalog that carries art. */
+export interface SoundArtFields {
+  "music-genre": "genre" | "subgenre" | "era"
+  "music-mood": "energy" | "emotion" | "vibe"
+  instrumentation: "instruments" | "production" | "vocalPresence" | "singingStyle"
+  "voice-character": "age" | "gender" | "language" | "accent" | "timbre"
+  "voice-delivery": "pace" | "emotion" | "archetype"
+}
+
+export type SoundArtCatalogId = keyof SoundArtFields
+
+/** `emoji/<slug>` or `flags/<code>` — a key of SOUND_ART_FILES. */
+export type SoundArtKey = `emoji/${string}` | `flags/${string}`
+
+export type SoundArtMap = {
+  readonly [C in SoundArtCatalogId]: {
+    readonly [F in SoundArtFields[C]]: Readonly<Record<string, SoundArtKey>>
+  }
+}

package/src/picker-catalogs.ts

@@ -81,7 +81,8 @@ import { ANIMALS, ANIMAL_SUBCATEGORY_LABELS, ANIMAL_SUBCATEGORY_ORDER, getAnimal
 import { VEHICLES, VEHICLE_SUBCATEGORY_LABELS, VEHICLE_SUBCATEGORY_ORDER } from "@nodaro/shared"
 import { WEAPONS, WEAPON_SUBCATEGORY_LABELS, WEAPON_SUBCATEGORY_ORDER } from "@nodaro/shared"
 import { FURNITURE, FURNITURE_SUBCATEGORY_LABELS, FURNITURE_SUBCATEGORY_ORDER } from "@nodaro/shared"
-import type { ProjectedCatalog, ProjectedCatalogOption, ProjectedCatalogDimension } from "@nodaro/shared"
+import type { ProjectedCatalog, ProjectedCatalogOption, ProjectedCatalogDimension, ProjectedCatalogSection } from "@nodaro/shared"
+import { pickerOptionImageUrl, pickerSectionImageUrl, type PickerImageOptions } from "./picker-art/images.js"
 import { HELD_PROPS, HELD_PROP_CATEGORY_LABELS, HELD_PROP_CATEGORY_ORDER } from "./held-prop.js"
 import { FRAMINGS, FRAMING_FIELD_BY_CATEGORY, FRAMING_CATEGORY_LABELS } from "./framing.js"
 import { LIGHTINGS, LIGHTING_FIELD_BY_CATEGORY, LIGHTING_CATEGORY_ORDER, LIGHTING_CATEGORY_LABELS } from "./lighting.js"
@@ -89,6 +90,7 @@ import { TEMPORALS, TEMPORAL_FIELD_BY_CATEGORY, TEMPORAL_CATEGORY_LABELS } from
 import { EXPOSURE_SETTINGS, EXPOSURE_FIELD_BY_CATEGORY, EXPOSURE_CATEGORY_LABELS } from "./exposure-settings.js"
 import { PEOPLE, PERSON_FIELD_BY_DIMENSION, PERSON_DIMENSION_ORDER, PERSON_DIMENSION_LABELS } from "./person.js"
 import { STYLINGS, STYLING_FIELD_BY_DIMENSION, STYLING_DIMENSION_ORDER, STYLING_DIMENSION_LABELS } from "./styling.js"
+import { catalogTopics } from "./catalog-sections.js"
 import { MUSIC_GENRES, MUSIC_ERAS } from "./music-genre.js"
 import { MUSIC_ENERGIES, MUSIC_EMOTIONS, MUSIC_VIBES } from "./music-mood.js"
 import { INSTRUMENTS, PRODUCTION_STYLES, VOCAL_PRESENCE, SINGING_STYLES } from "./instrumentation.js"
@@ -129,6 +131,17 @@ export interface PickerOption {
    * duration" — the safe reading, since the composer then behaves as before.
    */
   readonly instant?: true
+  /**
+   * PER-OPTION PARAMETERS — extra node-data fields that apply only while THIS
+   * option is picked, each with its own rows (Transitions: a wipe's
+   * `wipeDirection`; see `Transition.options`). Same shape as the catalog's
+   * `dimensions`, but scoped to the row that declares them: a consumer shows
+   * the control while the row is picked and stores the chosen row id under
+   * `field` beside the pick. The `auto` row leads each list and means "send
+   * nothing"; a row's `promptHint` is the phrase it writes into the option's
+   * description, not a clause of its own. Absent on every other option.
+   */
+  readonly params?: readonly PickerDimension[]
   /** Only present if the source catalog entry already carries a data icon/emoji/thumbnail field. */
   readonly icon?: string
 }
@@ -184,6 +197,18 @@ interface BaseCatalogEntry {
   readonly adultOnly?: true
   /** Transitions: see `Transition.instant`. Propagated into the flattened option as `instant: true`. */
   readonly instant?: boolean
+  /** Transitions: see `Transition.options`. Propagated as the option's `params`. */
+  readonly options?: ReadonlyArray<{
+    readonly field: string
+    readonly label: string
+    readonly choices: ReadonlyArray<{
+      readonly id: string
+      readonly label: string
+      readonly description: string
+      readonly phrase: string
+      readonly term: string
+    }>
+  }>
 }
 
 /**
@@ -213,6 +238,19 @@ function toOptions<T extends BaseCatalogEntry>(
     if (categoryField) opt.category = e[categoryField] as unknown as string
     if (e.adultOnly) opt.adultOnly = true
     if (e.instant) opt.instant = true
+    if (e.options?.length) {
+      opt.params = e.options.map((o) => ({
+        field: o.field,
+        label: o.label,
+        options: o.choices.map((c) => ({
+          id: c.id,
+          label: c.label,
+          description: c.description,
+          promptHint: c.phrase,
+          term: c.term,
+        })),
+      }))
+    }
     return opt as PickerOption
   })
 }
@@ -908,23 +946,41 @@ export interface PickerCatalogSummary {
   readonly fields?: readonly string[]
   /** single: options.length; multi: sum of every dimension's options. */
   readonly optionCount: number
+  /** How many of those options carry an `imageUrl` (0 without picture options). */
+  readonly imageCount: number
 }
 
-/** Lightweight directory of every picker catalog — no option payloads. */
-export function summarizePickerCatalogs(): readonly PickerCatalogSummary[] {
-  return getRegisteredPickerCatalogs().map((c) => ({
-    nodeType: c.nodeType,
-    label: c.label,
-    catalogId: c.catalogId,
-    kind: c.kind,
-    valueField: c.valueField,
-    fields: c.fields,
-    // Every option the detail call will return, whichever kind — a single-dim
-    // catalog with secondary dimensions carries both.
-    optionCount:
-      (c.options?.length ?? 0) +
-      (c.dimensions?.reduce((n, d) => n + d.options.length, 0) ?? 0),
-  }))
+/** Every (field, option) pair a catalog's detail call returns, whichever kind. */
+function everyOption(c: PickerCatalog): ReadonlyArray<{ readonly field: string | undefined; readonly option: PickerOption }> {
+  return [
+    ...(c.options ?? []).map((option) => ({ field: c.valueField, option })),
+    ...(c.dimensions ?? []).flatMap((d) => d.options.map((option) => ({ field: d.field, option }))),
+  ]
+}
+
+/**
+ * Lightweight directory of every picker catalog — no option payloads. With
+ * `images`, `imageCount` says how many options the detail call pictures.
+ */
+export function summarizePickerCatalogs(opts: { readonly images?: PickerImageOptions } = {}): readonly PickerCatalogSummary[] {
+  return getRegisteredPickerCatalogs().map((c) => {
+    const all = everyOption(c)
+    const images = opts.images
+    return {
+      nodeType: c.nodeType,
+      label: c.label,
+      catalogId: c.catalogId,
+      kind: c.kind,
+      valueField: c.valueField,
+      fields: c.fields,
+      // Every option the detail call will return, whichever kind — a single-dim
+      // catalog with secondary dimensions carries both.
+      optionCount: all.length,
+      imageCount: images
+        ? all.filter(({ field, option }) => pickerOptionImageUrl(c, field, option.id, images) !== undefined).length
+        : 0,
+    }
+  })
 }
 
 export type PickerCatalogDetail = "compact" | "full"
@@ -936,6 +992,12 @@ export interface ProjectPickerCatalogOptions {
   readonly category?: string
   /** multi-dim: keep only this dimension field. */
   readonly field?: string
+  /**
+   * Attach each option's absolute `imageUrl` (and the Person / Styling topic
+   * pictures). Left out, no option carries one — the caller (the API) knows
+   * which host this installation is reached at, the package does not.
+   */
+  readonly images?: PickerImageOptions
 }
 
 // The projection shape now lives in `@nodaro/shared` (Apache) as the tag-free
@@ -946,10 +1008,29 @@ export type ProjectedPickerOption = ProjectedCatalogOption
 export type ProjectedPickerDimension = ProjectedCatalogDimension
 export type ProjectedPickerCatalog = ProjectedCatalog
 
-function projectOption(o: PickerOption, detail: PickerCatalogDetail): ProjectedPickerOption {
+function projectOption(o: PickerOption, detail: PickerCatalogDetail, imageUrl?: string): ProjectedPickerOption {
   // `term` rides at BOTH detail levels: a thin client renders `label` and
   // injects `term`, so compact must carry it — it is what makes compact hint
   // mode possible without a second round-trip for the full payload.
+  const projected = projectOptionFields(o, detail, imageUrl)
+  // Per-option params (a wipe's direction) ride at both detail levels too: an
+  // id-only client needs the rows to offer the control at all.
+  return o.params
+    ? {
+        ...projected,
+        params: o.params.map((d) => ({
+          field: d.field,
+          label: d.label,
+          options: d.options.map((p) => projectOption(p, detail)),
+        })),
+      }
+    : projected
+}
+
+function projectOptionFields(o: PickerOption, detail: PickerCatalogDetail, imageUrl?: string): ProjectedPickerOption {
+  // `imageUrl` (display data) rides at both detail levels too, present only
+  // when the option has a picture.
+  const extras = { ...(o.motion ? { motion: o.motion } : {}), ...(imageUrl ? { imageUrl } : {}) }
   return detail === "full"
     ? {
         id: o.id,
@@ -959,9 +1040,25 @@ function projectOption(o: PickerOption, detail: PickerCatalogDetail): ProjectedP
         promptHint: o.promptHint,
         term: o.term,
         icon: o.icon,
-        ...(o.motion ? { motion: o.motion } : {}),
+        ...extras,
       }
-    : { id: o.id, label: o.label, category: o.category, term: o.term, icon: o.icon, ...(o.motion ? { motion: o.motion } : {}) }
+    : { id: o.id, label: o.label, category: o.category, term: o.term, icon: o.icon, ...extras }
+}
+
+/**
+ * The topics a catalog's settings are grouped under in the editor (Person,
+ * Styling), as node-data fields; only the fields the catalog has are listed.
+ */
+function catalogSections(c: PickerCatalog, images: PickerImageOptions | undefined): ProjectedCatalogSection[] | undefined {
+  const source = catalogTopics(c.catalogId)
+  if (!source) return undefined
+  const present = new Set((c.dimensions ?? []).map((d) => d.field))
+  return source
+    .map((s) => {
+      const imageUrl = images ? pickerSectionImageUrl(s.label, images) : undefined
+      return { label: s.label, fields: s.fields.filter((f) => present.has(f)), ...(imageUrl ? { imageUrl } : {}) }
+    })
+    .filter((s) => s.fields.length > 0)
 }
 
 /** Project a catalog to the wire shape: compact by default, optional category/field filter. */
@@ -981,17 +1078,20 @@ export function projectPickerCatalog(
     categoryLabels: c.categoryLabels,
     detail,
   }
+  const images = opts.images
+  const imageOf = (field: string | undefined, o: PickerOption) =>
+    images ? pickerOptionImageUrl(c, field, o.id, images) : undefined
   const projectDims = (dims: readonly PickerDimension[]) =>
     dims.map((d) => ({
       field: d.field,
       label: d.label,
-      options: d.options.map((o) => projectOption(o, detail)),
+      options: d.options.map((o) => projectOption(o, detail, imageOf(d.field, o))),
     }))
 
   if (c.kind === "single") {
     let options = c.options ?? []
     if (opts.category) options = options.filter((o) => o.category === opts.category)
-    const projected = { ...base, options: options.map((o) => projectOption(o, detail)) }
+    const projected = { ...base, options: options.map((o) => projectOption(o, detail, imageOf(c.valueField, o))) }
     // A single-dim catalog may still carry secondary parameter dimensions
     // (transition's position/duration/intensity). They are additive — a
     // consumer reading only `options` is unaffected — but dropping them here
@@ -1003,7 +1103,8 @@ export function projectPickerCatalog(
   }
   let dims = c.dimensions ?? []
   if (opts.field) dims = dims.filter((d) => d.field === opts.field)
-  return { ...base, fields: c.fields, dimensions: projectDims(dims) }
+  const sections = catalogSections(c, images)
+  return { ...base, fields: c.fields, dimensions: projectDims(dims), ...(sections ? { sections } : {}) }
 }
 
 /**
@@ -1011,6 +1112,6 @@ export function projectPickerCatalog(
  * `/v1/catalogs` wire shape. This is what the `GET /v1/catalogs` route and its
  * SDK resource serve, so a deployment's vendored packs are reflected verbatim.
  */
-export function projectAllCatalogs(opts: { detail?: PickerCatalogDetail } = {}): ProjectedCatalog[] {
-  return getRegisteredPickerCatalogs().map((c) => projectPickerCatalog(c, { detail: opts.detail }))
+export function projectAllCatalogs(opts: { detail?: PickerCatalogDetail; images?: PickerImageOptions } = {}): ProjectedCatalog[] {
+  return getRegisteredPickerCatalogs().map((c) => projectPickerCatalog(c, { detail: opts.detail, images: opts.images }))
 }

package/src/prompt-builder.ts

@@ -4,6 +4,7 @@
  * provider-aware prompt truncation (default 5000 chars), and reference image filtering by model support.
  */
 
+import { joinSentences } from "./hint-join.js"
 import { resolveTemplate, applyTemplate } from "./prompt-templates.js"
 import { NATIVE_NEGATIVE_PROMPT_MODELS, MODELS_WITH_REFERENCE_IMAGE_SUPPORT, imageReferenceLimit, getMaxImagePromptChars, getMaxNegativePromptChars } from "@nodaro/shared"
 import { getStylePromptHint, isDeniedStyleId } from "./style.js"
@@ -60,7 +61,7 @@ function composeIdentityDescPart(
   if (c) parts.push(c)
   const e = elementInjection?.trim()
   if (e) parts.push(e)
-  return parts.length > 0 ? `${subject} — ${parts.join(". ")}` : subject
+  return parts.length > 0 ? `${subject} — ${joinSentences(parts)}` : subject
 }
 
 /**

package/src/prompt-hint-join.ts

@@ -22,7 +22,11 @@
  * Never mutates its inputs.
  */
 
-/** The measured separator between the user's prompt and each folded hint. */
+/** The measured separator between the user's prompt and each folded hint.
+ *  Pieces that already end a sentence are followed by a single space instead
+ *  (`joinSentences`), so this is the longest separator a join can add. */
+import { joinSentences } from "./hint-join.js"
+
 export const PROMPT_HINT_SEPARATOR = ". "
 
 /**
@@ -35,5 +39,7 @@ export const PROMPT_HINT_SEPARATOR = ". "
  */
 export function joinPromptHints(userPrompt: string, hints: readonly string[]): string {
   if (hints.length === 0) return userPrompt
-  return [userPrompt.trim(), ...hints].filter((p) => p.length > 0).join(PROMPT_HINT_SEPARATOR)
+  // Sentence-aware: a prompt or hint that already ends a sentence is followed
+  // by a space, not by PROMPT_HINT_SEPARATOR (which made "watermark.. hint").
+  return joinSentences([userPrompt.trim(), ...hints])
 }

package/src/prompt-style-section.ts

@@ -45,7 +45,8 @@
  * section is written flush-left rather than relying on that collapse to be
  * harmless.
  */
-import { joinPromptHints, PROMPT_HINT_SEPARATOR } from "./prompt-hint-join.js"
+import { joinPromptHints } from "./prompt-hint-join.js"
+import { joinSentences } from "./hint-join.js"
 import {
   renderDirectionHintClauses,
   type DirectionFamily,
@@ -173,10 +174,7 @@ export function partitionStyleClauses(
  */
 export function styleSectionFromClauses(clauses: readonly SlottedPromptClause[]): string {
   const line = (slot: PromptClauseSlot) =>
-    clauses
-      .filter((c) => c.slot === slot)
-      .map((c) => c.text)
-      .join(PROMPT_HINT_SEPARATOR)
+    joinSentences(clauses.filter((c) => c.slot === slot).map((c) => c.text))
   const lines = [line("film"), line("scene")].filter((l) => l.length > 0)
   return lines.length === 0 ? "" : `${STYLE_SECTION_HEADER}\n${lines.join("\n")}`
 }

package/src/resolve-prompt.ts

@@ -1,5 +1,6 @@
 import { resolveNodeRefs, readPromptAffixes, type PromptAffixes } from "@nodaro/shared"
 import { SOCIAL_POST_NODE_TYPES } from "@nodaro/shared"
+import { joinSentences } from "./hint-join.js"
 
 export interface ResolvePromptArgs {
   override?: string
@@ -72,7 +73,8 @@ export function applyPromptAffixes(
  *  override (list fan-out) > first present typed candidate > wired > "".
  *  "present" = non-empty after trim. {Label} refs are resolved on the chosen
  *  branch via the shared resolveNodeRefs. With `appendWired`, the chosen base
- *  AND the wired value are both emitted (joined ". "). Affixes wrap the result. */
+ *  AND the wired value are both emitted, joined as sentences (`joinSentences`:
+ *  ". ", or a space after one that already ends). Affixes wrap the result. */
 export function resolvePrompt({ override, typed = [], wired, refMap, appendWired, affixes }: ResolvePromptArgs): string {
   return applyPromptAffixes(resolveCore({ override, typed, wired, refMap, appendWired }), affixes, refMap)
 }
@@ -83,7 +85,7 @@ function resolveCore({ override, typed = [], wired, refMap, appendWired }: Omit<
   // so per-item fan-out prompts are unchanged.
   if (appendWired && !present(override)) {
     const base = typed.find(present)
-    return [base, wired].filter(present).map((s) => rr(s, refMap)).join(". ")
+    return joinSentences([base, wired].filter(present).map((s) => rr(s, refMap)))
   }
   if (present(override)) return rr(override, refMap)
   for (const t of typed) if (present(t)) return rr(t, refMap)
@@ -92,13 +94,13 @@ function resolveCore({ override, typed = [], wired, refMap, appendWired }: Omit<
 }
 
 /** Compose a final NEGATIVE prompt from a TYPED base + a WIRED (connected
- *  negative-handle) value: both are emitted, joined ". " (mirrors `appendWired`
+ *  negative-handle) value: both are emitted, joined as sentences (`joinSentences`, mirrors `appendWired`
  *  for the positive prompt). Pure join — the caller resolves `{label}` refs on
  *  the typed value first, and the wired value is already a resolved output that
  *  the input-resolver has filtered (referenced / Inject-Negative-off dropped).
  *  Generate-image / generate-video only; empty parts are dropped. */
 export function composeNegative(typed?: string, wired?: string): string {
-  return [typed, wired].filter(present).join(". ")
+  return joinSentences([typed, wired])
 }
 
 /** Ordered typed-candidate fields per node type — the precedence source of
@@ -184,3 +186,19 @@ export function computeLlmChatFields(
     systemPrompt: resolvePrompt({ typed: [data.systemPrompt as string | undefined], wired: wiredSystemPrompt, refMap }),
   }
 }
+
+/** generate-script's topic. Both engines call this, so a wired Text node reads
+ *  the same on a single-node run and a server run.
+ *
+ *  Precedence is override (a list fan-out item) > wired > `data.prompt`. Wired
+ *  comes BEFORE the typed field, the reverse of `computeNodePrompt`, because
+ *  `data.prompt` has no editor: the panel's text field is the style guide. A
+ *  value there was written by the old connect-time `{Label}` auto-fill or by an
+ *  agent, and it is kept only as the fallback that saved workflows rely on. */
+export function computeScriptTopic(
+  data: Record<string, unknown>,
+  { override, wired, refMap }: Omit<ComputeNodePromptArgs, "appendWired">,
+): string {
+  const core = [override, wired, data.prompt as string | undefined].find(present)
+  return applyPromptAffixes(core === undefined ? "" : rr(core, refMap), readPromptAffixes(data), refMap)
+}

package/src/styling.ts

@@ -467,6 +467,24 @@ export const STYLING_DIMENSION_ORDER: ReadonlyArray<StylingDimension> = [
   "wardrobe-state",
 ]
 
+/**
+ * The Styling picker's topics, in display order (mirrors PERSON_DIMENSION_SECTIONS):
+ * every dimension belongs to exactly one — styling-sections.test.ts fails the build
+ * when a new dimension is left out or listed twice. The editor lays the open
+ * picker out by these, and the API serves them as the catalog's `sections`.
+ */
+export interface StylingDimensionSection {
+  readonly label: string
+  readonly dimensions: ReadonlyArray<StylingDimension>
+}
+
+export const STYLING_DIMENSION_SECTIONS: ReadonlyArray<StylingDimensionSection> = [
+  { label: "Beauty & Hair", dimensions: ["makeup", "hair-cut", "hair-treatment", "hair-state", "nails", "face-paint"] },
+  { label: "Accessories",   dimensions: ["eyewear", "headwear", "jewelry"] },
+  { label: "Wardrobe",      dimensions: ["outfit", "top", "bottom", "outerwear", "legwear", "footwear"] },
+  { label: "Fabric & Fit",  dimensions: ["fabric", "wardrobe-state"] },
+]
+
 export const STYLING_DIMENSION_LABELS: Readonly<Record<StylingDimension, string>> = {
   makeup: "Makeup",
   eyewear: "Eyewear",