@nodaro/prompts 1.33.0 → 1.35.0

package/dist/index.d.cts

@@ -1062,7 +1062,9 @@ declare function buildImagePromptSegments(config: BuildImagePromptConfig, bodySe
  * consistent identifier in both the bulleted list and the scene description.
  * Numeric indices match the user-typed slug format (`@kira:1:smile`).
  *
- * Out-of-range indices are left untouched so they're visible in the output.
+ * Out-of-range indices are left untouched by this helper. `buildImagePrompt`
+ * then renders any such token by the unwired rule (`dropUnwiredImageTokens`):
+ * its label, or nothing — never the raw token.
  */
 declare function expandImageRefTokens(prompt: string, imageCount: number): string;
 /** Build the combined per-identity directive intro for previews.
@@ -2701,19 +2703,22 @@ interface ReferenceCounts {
  *   - `N < 1` or `N > counts[kind]` (out of range / no such reference) → drop to
  *     the bare `label` (or empty if label-less). This is the legacy
  *     `stripVideoImageTokens` strip behavior: drop the token, keep the label text.
+ *     The rendering is `unboundReferenceTokenText` — shared with the image prompt
+ *     builder, which applies the same rule to its own unwired `{image:N}` tokens.
  *   - in range, label present → `REF_BINDING[kind](label, N)`
  *     (e.g. `the person from @image_2`).
  *   - in range, no label → the bare `@${kind}_${N}` (the ref-only default): the
  *     binding lands with no descriptive wrapper.
  *
  * Runs of 2+ HORIZONTAL whitespace (left behind by a dropped label-less token)
- * collapse to one space, the result is trimmed, and an empty result becomes
- * `undefined` — matching the `stripVideoImageTokens` contract so this can replace
- * it cleanly. The collapse class is `[^\S\r\n]` (NOT `\s`) on purpose: Task 2.4
- * applies this to the FULLY-ASSEMBLED core prompt, which carries `\n\n` block
- * separators between the "Use these characters:" directive block and the body —
- * a `\s{2,}` collapse would silently merge those paragraphs. Horizontal-only
- * collapse preserves newline structure while still tidying the dropped-token gap.
+ * collapse to one space, the result is trimmed (`tidyReferenceTokenGaps`, also
+ * shared with the image builder), and an empty result becomes `undefined` —
+ * matching the `stripVideoImageTokens` contract so this can replace it cleanly.
+ * The collapse class is `[^\S\r\n]` (NOT `\s`) on purpose: the core applies this
+ * to the FULLY-ASSEMBLED prompt, which carries `\n\n` block separators between
+ * the "Use these characters:" directive block and the body — a `\s{2,}` collapse
+ * would silently merge those paragraphs. Horizontal-only collapse preserves
+ * newline structure while still tidying the dropped-token gap.
  * The `kind` is lowercased before indexing `counts`/`REF_BINDING`, so a
  * case-variant token (`{Image:1}`) resolves to the same binding rather than
  * mis-classifying as out-of-range.
@@ -7837,8 +7842,12 @@ declare function getPromptTips(providerId: string): readonly string[];
  * Source of truth for the semantics documented here (verified 2026-08-25):
  * - `IMAGE_TOKEN_PATTERN` = `/\{image:(\d+)(?::([^}\n]+))?\}/gi`
  * - `expandImageRefTokens`: `{image:N:label}` → `Image N (label)`,
- *   `{image:N}` → `Image N`; out-of-range tokens are left untouched so the
- *   author can see and fix them.
+ *   `{image:N}` → `Image N`.
+ * - A token with no reference at N follows the video resolver's rule
+ *   (`dropUnwiredImageTokens` in `prompt-builder.ts`): `{image:N:label}` →
+ *   `label`, a bare `{image:N}` is dropped. Two places keep a token as typed,
+ *   on purpose: a wired token in a hybrid `Avoid:` line, and the native
+ *   negative prompt of models with their own negative field (e.g. ideogram-v3).
  * - N is the reference's 1-based position in the assembled reference list
  *   (connection order on the `references` handle).
  */

package/dist/index.d.ts

@@ -1062,7 +1062,9 @@ declare function buildImagePromptSegments(config: BuildImagePromptConfig, bodySe
  * consistent identifier in both the bulleted list and the scene description.
  * Numeric indices match the user-typed slug format (`@kira:1:smile`).
  *
- * Out-of-range indices are left untouched so they're visible in the output.
+ * Out-of-range indices are left untouched by this helper. `buildImagePrompt`
+ * then renders any such token by the unwired rule (`dropUnwiredImageTokens`):
+ * its label, or nothing — never the raw token.
  */
 declare function expandImageRefTokens(prompt: string, imageCount: number): string;
 /** Build the combined per-identity directive intro for previews.
@@ -2701,19 +2703,22 @@ interface ReferenceCounts {
  *   - `N < 1` or `N > counts[kind]` (out of range / no such reference) → drop to
  *     the bare `label` (or empty if label-less). This is the legacy
  *     `stripVideoImageTokens` strip behavior: drop the token, keep the label text.
+ *     The rendering is `unboundReferenceTokenText` — shared with the image prompt
+ *     builder, which applies the same rule to its own unwired `{image:N}` tokens.
  *   - in range, label present → `REF_BINDING[kind](label, N)`
  *     (e.g. `the person from @image_2`).
  *   - in range, no label → the bare `@${kind}_${N}` (the ref-only default): the
  *     binding lands with no descriptive wrapper.
  *
  * Runs of 2+ HORIZONTAL whitespace (left behind by a dropped label-less token)
- * collapse to one space, the result is trimmed, and an empty result becomes
- * `undefined` — matching the `stripVideoImageTokens` contract so this can replace
- * it cleanly. The collapse class is `[^\S\r\n]` (NOT `\s`) on purpose: Task 2.4
- * applies this to the FULLY-ASSEMBLED core prompt, which carries `\n\n` block
- * separators between the "Use these characters:" directive block and the body —
- * a `\s{2,}` collapse would silently merge those paragraphs. Horizontal-only
- * collapse preserves newline structure while still tidying the dropped-token gap.
+ * collapse to one space, the result is trimmed (`tidyReferenceTokenGaps`, also
+ * shared with the image builder), and an empty result becomes `undefined` —
+ * matching the `stripVideoImageTokens` contract so this can replace it cleanly.
+ * The collapse class is `[^\S\r\n]` (NOT `\s`) on purpose: the core applies this
+ * to the FULLY-ASSEMBLED prompt, which carries `\n\n` block separators between
+ * the "Use these characters:" directive block and the body — a `\s{2,}` collapse
+ * would silently merge those paragraphs. Horizontal-only collapse preserves
+ * newline structure while still tidying the dropped-token gap.
  * The `kind` is lowercased before indexing `counts`/`REF_BINDING`, so a
  * case-variant token (`{Image:1}`) resolves to the same binding rather than
  * mis-classifying as out-of-range.
@@ -7837,8 +7842,12 @@ declare function getPromptTips(providerId: string): readonly string[];
  * Source of truth for the semantics documented here (verified 2026-08-25):
  * - `IMAGE_TOKEN_PATTERN` = `/\{image:(\d+)(?::([^}\n]+))?\}/gi`
  * - `expandImageRefTokens`: `{image:N:label}` → `Image N (label)`,
- *   `{image:N}` → `Image N`; out-of-range tokens are left untouched so the
- *   author can see and fix them.
+ *   `{image:N}` → `Image N`.
+ * - A token with no reference at N follows the video resolver's rule
+ *   (`dropUnwiredImageTokens` in `prompt-builder.ts`): `{image:N:label}` →
+ *   `label`, a bare `{image:N}` is dropped. Two places keep a token as typed,
+ *   on purpose: a wired token in a hybrid `Avoid:` line, and the native
+ *   negative prompt of models with their own negative field (e.g. ideogram-v3).
  * - N is the reference's 1-based position in the assembled reference list
  *   (connection order on the `references` handle).
  */