@nodaro/prompts 1.39.0 → 1.40.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { P as PICKER_CATALOGS, a as PickerCatalog, b as PickerCatalogDetail, c as PickerCatalogSummary, d as PickerDimension, e as PickerOption, f as ProjectPickerCatalogOptions, g as ProjectedPickerCatalog, h as ProjectedPickerDimension, i as ProjectedPickerOption, j as getPickerCatalog, k as getRegisteredPickerCatalogs, l as listPickerCatalogs, p as projectAllCatalogs, m as projectPickerCatalog, s as summarizePickerCatalogs } from './picker-catalogs-DDjtZND3.js';
-export { AssembleImageInput, AssembleImageResult, AssembleSunoInput, AssembleSunoResult, CharacterMeta, FrameDeliveryPlan, FrameDeliveryPlanArgs, GeminiOmniI2vInputsArgs, GeminiOmniI2vInputsResult, REF_BINDING, RefIdTokenContext, ReferenceCounts, ResolveVideoReferenceCoreArgs, SEEDANCE_VIDEO_EDIT_PREFIX, Seedance2InputsArgs, Seedance2InputsResult, Seedance2Mode, SoundComposition, SoundCompositionFields, SoundConsumerType, VeoI2vInputsArgs, VeoI2vInputsResult, VideoExtraRef, VideoPromptCapOptions, appendField, appendMusicMeta, assembleImageInput, assembleSunoInput, buildSeedanceVideoEditPrompt, buildSurroundFillPrompt, composeSoundHintFromConnections, composeVideoPromptText, getEffectiveSunoCustomMode, identityRefsSentence, planFrameDelivery, promptBindsFirstFrame, resolveGeminiOmniI2vInputs, resolveRefIdTokens, resolveReferenceTokens, resolveSeedance2Inputs, resolveVeoI2vInputs, resolveVideoReferenceCore, truncateForField } from './entries/assembly.js';
+export { AssembleImageInput, AssembleImageResult, AssembleSunoInput, AssembleSunoResult, CharacterMeta, FrameDeliveryPlan, FrameDeliveryPlanArgs, FrameReferenceSlotsArgs, FrameReferenceSlotsResult, GeminiOmniI2vInputsArgs, GeminiOmniI2vInputsResult, ImageBinding, REF_BINDING, RefIdTokenContext, ReferenceCounts, ResolveVideoReferenceCoreArgs, SEEDANCE_VIDEO_EDIT_PREFIX, Seedance2InputsArgs, Seedance2InputsResult, Seedance2Mode, SoundComposition, SoundCompositionFields, SoundConsumerType, VeoI2vInputsArgs, VeoI2vInputsResult, VideoExtraRef, VideoPromptCapOptions, appendField, appendMusicMeta, assembleImageInput, assembleSunoInput, buildSeedanceVideoEditPrompt, buildSurroundFillPrompt, composeSoundHintFromConnections, composeVideoPromptText, getEffectiveSunoCustomMode, identityRefsSentence, imageBindingFor, placeFramesAfterReferences, planFrameDelivery, promptBindsFirstFrame, resolveGeminiOmniI2vInputs, resolveRefIdTokens, resolveReferenceTokens, resolveSeedance2Inputs, resolveVeoI2vInputs, resolveVideoReferenceCore, truncateForField } from './entries/assembly.js';
 export { P as PickerHintMode, S as SuspiciousTermOptions, T as TERM_MAX_CHARS, a as TermCarrier, d as deriveTerm, i as isSuspiciousDerivedTerm, r as resolveTerm } from './term-C01_g6s1.js';
 export { C as CatalogPack, a as CatalogPackMode, P as PickerCatalogInput, b as PickerDimensionInput, c as PickerOptionInput, d as catalogPacksVersion, e as composePickerCatalogs, g as getRegisteredCatalogPacks, h as hasCatalogPacksFor, r as registerCatalogPack, f as resetCatalogPacks, s as subscribeCatalogPacks } from './catalog-packs-3SxAVxPF.js';
 export { SidecarCoverageReport, computePackSidecarCoverage } from './entries/catalog-packs.js';

package/dist/index.js

@@ -1,14 +1,14 @@
-export { BODY_CAPTIONS_PRESET_ID, BRAND_PRESETS, BRAND_PRESET_IDS, BRAND_PRESET_META, CAPTION_LEVERS_BY_LANGUAGE, CAPTION_SEGMENT_LEVER_KEYS, FACTORY_PRESETS, FACTORY_PRESET_PREVIEW_FILES, FACTORY_SNIPPETS, HOOK_PLATE_PRESET_ID, MAX_PRESET_REFERENCES, OBJECT_ANGLE_PRESETS, OBJECT_ANGLE_PROMPTS, OBJECT_ASSET_PRESETS, OBJECT_ASSET_PROMPTS, OBJECT_MATERIAL_PRESETS, OBJECT_MATERIAL_PROMPTS, OBJECT_VARIATION_PRESETS, OBJECT_VARIATION_PROMPTS, PRESET_PREVIEW_PATH, SNIPPET_MEDIA_VALUES, STYLE_PRESETS, factoryPresetPreviewUrl, getFactoryPresets, getFactorySnippets, getStylePreset, groupFactoryPresets, hookPlateCaptionSegments, presetMinReferences, resolveBrandInput } from './chunk-6MPZHFIS.js';
+export { BODY_CAPTIONS_PRESET_ID, BRAND_PRESETS, BRAND_PRESET_IDS, BRAND_PRESET_META, CAPTION_LEVERS_BY_LANGUAGE, CAPTION_SEGMENT_LEVER_KEYS, FACTORY_PRESETS, FACTORY_PRESET_PREVIEW_FILES, FACTORY_SNIPPETS, HOOK_PLATE_PRESET_ID, MAX_PRESET_REFERENCES, OBJECT_ANGLE_PRESETS, OBJECT_ANGLE_PROMPTS, OBJECT_ASSET_PRESETS, OBJECT_ASSET_PROMPTS, OBJECT_MATERIAL_PRESETS, OBJECT_MATERIAL_PROMPTS, OBJECT_VARIATION_PRESETS, OBJECT_VARIATION_PROMPTS, PRESET_PREVIEW_PATH, SNIPPET_MEDIA_VALUES, STYLE_PRESETS, factoryPresetPreviewUrl, getFactoryPresets, getFactorySnippets, getStylePreset, groupFactoryPresets, hookPlateCaptionSegments, presetMinReferences, resolveBrandInput } from './chunk-RB2F5JQF.js';
 export { readDirectionFields, readStructuredFields, readSubjectFields } from './chunk-6GVFJLDL.js';
-export { TEXT_REQUIRED_NODE_TYPES, WIRED_OUTPUT_NODE_TYPES, computeAiWriterInput, computeNodeSendText, stripAudioTags } from './chunk-Z3SZXWRU.js';
-export { NODE_PROMPT_CANDIDATE_FIELDS, NODE_PROMPT_FIELDS, PROMPT_AFFIX_CORE_FIELD_OVERRIDES, PROMPT_AFFIX_NODE_TYPES, applyPromptAffixes, composeNegative, computeLlmChatFields, computeNodePrompt, computeScriptTopic, getPromptFields, getSnippetMedia, joinPromptParts, nodeHasInlinePrompt, nodeHasPromptField, nodeSupportsPromptAffixes, promptAffixCoreField, promptFieldCarriesAffixes, promptPartSeparator, resolvePrompt } from './chunk-7XMTVYS5.js';
-export { REF_BINDING, SEEDANCE_VIDEO_EDIT_PREFIX, appendField, appendMusicMeta, assembleImageInput, assembleSunoInput, buildSeedanceVideoEditPrompt, buildSurroundFillPrompt, composeSoundHintFromConnections, composeVideoPromptText, getEffectiveSunoCustomMode, identityRefsSentence, planFrameDelivery, promptBindsFirstFrame, resolveGeminiOmniI2vInputs, resolveRefIdTokens, resolveReferenceTokens, resolveSeedance2Inputs, resolveVeoI2vInputs, resolveVideoReferenceCore, truncateForField } from './chunk-XU54YJXQ.js';
+export { TEXT_REQUIRED_NODE_TYPES, WIRED_OUTPUT_NODE_TYPES, computeAiWriterInput, computeNodeSendText, stripAudioTags } from './chunk-YS6HOWMW.js';
+export { NODE_PROMPT_CANDIDATE_FIELDS, NODE_PROMPT_FIELDS, PROMPT_AFFIX_CORE_FIELD_OVERRIDES, PROMPT_AFFIX_NODE_TYPES, applyPromptAffixes, composeNegative, computeLlmChatFields, computeNodePrompt, computeScriptTopic, getPromptFields, getSnippetMedia, joinPromptParts, nodeHasInlinePrompt, nodeHasPromptField, nodeSupportsPromptAffixes, promptAffixCoreField, promptFieldCarriesAffixes, promptPartSeparator, resolvePrompt } from './chunk-N6VMPG5S.js';
+export { REF_BINDING, SEEDANCE_VIDEO_EDIT_PREFIX, appendField, appendMusicMeta, assembleImageInput, assembleSunoInput, buildSeedanceVideoEditPrompt, buildSurroundFillPrompt, composeSoundHintFromConnections, composeVideoPromptText, getEffectiveSunoCustomMode, identityRefsSentence, imageBindingFor, placeFramesAfterReferences, planFrameDelivery, promptBindsFirstFrame, resolveGeminiOmniI2vInputs, resolveRefIdTokens, resolveReferenceTokens, resolveSeedance2Inputs, resolveVeoI2vInputs, resolveVideoReferenceCore, truncateForField } from './chunk-HQTHDTHN.js';
 export { ANGLE_LABELS, ASPECT_RATIO_LABELS, MAX_SUBJECT_KEYS, MOVEMENT_LABELS, SCENE_PROMPT_MAX_LENGTH, SHOT_LABELS, STYLE_SECTION_GAP, STYLE_SECTION_HEADER, SUBJECT_ARRAY_CEILING, SUBJECT_CUSTOM_AGE_KEY, SUBJECT_FIELDS, SUBJECT_FOLD_KEYS, SUBJECT_ID_MAX_CHARS, SUBJECT_IMAGE_HINT_MODE_DEFAULT, SUBJECT_KEYS, SUBJECT_KEY_MAX_CHARS, SUBJECT_VIDEO_HINT_MODE_DEFAULT, appendReferenceLines, applyReferenceOrderToVideo, asBodyClauses, buildIdentityDirectives, buildImagePrompt, buildImagePromptSegments, buildImagePromptWithOverflow, buildReferenceBlocks, buildScenePrompt, composeSectionedPrompt, endsInsideStyleSection, expandImagePositionRefs, expandImageRefTokens, getRegisteredSubjectKeys, insertBeforeStyleSection, normalizeSubjectFields, partitionStyleClauses, referenceDescriptionLine, renderDescribedReferenceLines, renderReferenceCaptionLines, renderStructuredFields, renderStyleSection, renderSubjectHints, resolveCharacterMentions, resolveLocationMentions, sectionedClauseCosts, splitStyleSection, styleSectionFromClauses, styleSlotFor, subjectFieldsForSurface, truncateText } from './chunk-DUXX6CBX.js';
 import './chunk-GILUVQQJ.js';
 export { keepableDirectionHints } from './chunk-JZOPMVGY.js';
 export { PROMPT_HINT_SEPARATOR, joinPromptHints } from './chunk-35UHMDGS.js';
 export { computePackSidecarCoverage } from './chunk-FDOG7BNB.js';
-export { AD_CREATIVE_ANALYSIS_FIELDS, AD_CREATIVE_ANALYSIS_SYSTEM_PROMPT, AUDIO_WIZARD_CATEGORIES, DEFAULT_OWN_MOTION, IMAGE_REFERENCE_PROMPT_DOCTRINE, IMAGE_WIZARD_CATEGORIES, LLM_CHAT_WIZARD_CATEGORIES, MUSIC_WIZARD_CATEGORIES, OWN_MOTION_NODE_TYPES, POST_CONTENT_ANALYSIS_SYSTEM_PROMPT, PROVIDER_CAPABILITIES, PROVIDER_PROMPT_DOCTRINES, REFERENCE_IMAGE_ROLES, SCENE3D_FIGURE_REFERENCE_RULE, SCENE3D_FREE_PLATE_SLOTS, SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE, SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE, SCENE3D_LAYOUT_SCOPING_FOR, SCENE3D_LAYOUT_SCOPING_IGNORE, SCENE3D_LAYOUT_SCOPING_LOOK_SOURCE, SCENE3D_LAYOUT_SCOPING_MARKER, SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE, TEXT_WIZARD_CATEGORIES, VIDEO_WIZARD_CATEGORIES, appendScene3DStillScopingLines, buildAdCreativeAnalysisUserText, buildCharacterPrompt, buildCreaturePrompt, buildFaceTemplateInputs, buildLocationMotionPrompt, buildLocationPrompt, buildLocationRefinePrompt, buildMotionPrompt, buildObjectMotionPrompt, buildObjectPrompt, buildScene3DLayoutScopingLine, buildScene3DUnreferencedFiguresWarning, getCategoriesForNodeType, getPromptDoctrine, getPromptTips, hasScene3DLayoutScopingLine, isWizardSupported, ownMotionHint, renderScene3DLayoutScopingLine, scene3DLayoutVideoCaptions } from './chunk-XRLOMTBZ.js';
+export { AD_CREATIVE_ANALYSIS_FIELDS, AD_CREATIVE_ANALYSIS_SYSTEM_PROMPT, AUDIO_WIZARD_CATEGORIES, DEFAULT_OWN_MOTION, IMAGE_REFERENCE_PROMPT_DOCTRINE, IMAGE_WIZARD_CATEGORIES, LLM_CHAT_WIZARD_CATEGORIES, MUSIC_WIZARD_CATEGORIES, OWN_MOTION_NODE_TYPES, POST_CONTENT_ANALYSIS_SYSTEM_PROMPT, PROVIDER_CAPABILITIES, PROVIDER_PROMPT_DOCTRINES, REFERENCE_IMAGE_ROLES, SCENE3D_FIGURE_REFERENCE_RULE, SCENE3D_FREE_PLATE_SLOTS, SCENE3D_LAYOUT_REFERENCE_SCOPING_FIXTURE, SCENE3D_LAYOUT_REFERENCE_SCOPING_LINE, SCENE3D_LAYOUT_SCOPING_FOR, SCENE3D_LAYOUT_SCOPING_IGNORE, SCENE3D_LAYOUT_SCOPING_LOOK_SOURCE, SCENE3D_LAYOUT_SCOPING_MARKER, SCENE3D_UNREFERENCED_FIGURES_WARNING_CODE, TEXT_WIZARD_CATEGORIES, VIDEO_WIZARD_CATEGORIES, appendScene3DStillScopingLines, buildAdCreativeAnalysisUserText, buildCharacterPrompt, buildCreaturePrompt, buildFaceTemplateInputs, buildLocationMotionPrompt, buildLocationPrompt, buildLocationRefinePrompt, buildMotionPrompt, buildObjectMotionPrompt, buildObjectPrompt, buildScene3DLayoutScopingLine, buildScene3DUnreferencedFiguresWarning, getCategoriesForNodeType, getPromptDoctrine, getPromptTips, hasScene3DLayoutScopingLine, isWizardSupported, ownMotionHint, renderScene3DLayoutScopingLine, scene3DLayoutVideoCaptions } from './chunk-C46256GZ.js';
 export { CINEMATIC_LOOK_TAIL, FILM_STILL_PREFIX, NEUTRAL_PERSON, REALISM_FINISH, REALISM_PASS_INSTRUCTION, REALISM_SKIN, REFERENCE_RULES, REFERENCE_RULES_MULTI_PERSON, SCENE_FRAME_RULE, filmStillPrefix, realismEmptyHands, realismViewpoint, referenceRulesBlock } from './chunk-T64D26P4.js';
 export { DEFAULT_IDENTITY_LOCK, DEFAULT_TEMPLATES, applyTemplate, buildIdentityLockLine, characterLockToRefLock, collectIdentityLockClause, getIdentityLockClause, hasUpstreamCharacter, resolveTemplate, toIdentityLockMode, withForcedIdentityLock } from './chunk-BQWIPLLR.js';
 import './chunk-ADMHDFHB.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -70,7 +70,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@nodaro/shared": "^3.33.0"
+    "@nodaro/shared": "^3.34.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",

package/src/__tests__/factory-presets-prototype-keys.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest"
+import { FACTORY_PRESETS, getFactoryPresets, presetMinReferences } from "../factory-presets.js"
+import { getPromptFields, nodeSupportsPromptAffixes, promptAffixCoreField, promptFieldCarriesAffixes } from "../node-prompt-fields.js"
+import { computeNodePrompt } from "../resolve-prompt.js"
+
+/**
+ * The registries keyed by node type are plain objects, and a node type is
+ * caller-supplied (`?nodeType=` on the public factory route, a preset row's
+ * `node_type`, workflow JSON). A name that is an Object.prototype member —
+ * `constructor`, `toString`, `__proto__` — must read as "no such type", never
+ * as the prototype's member: `FACTORY_PRESETS["constructor"]` is `Object`, so
+ * `?? []` did not fire and `.map` threw an anonymous 500.
+ */
+const PROTOTYPE_KEYS = ["constructor", "__proto__", "toString", "hasOwnProperty", "valueOf"] as const
+
+describe("node-type lookups and Object.prototype member names", () => {
+  it.each(PROTOTYPE_KEYS)("getFactoryPresets(%j) is an empty catalog", (key) => {
+    expect(getFactoryPresets(key)).toEqual([])
+    expect(key in FACTORY_PRESETS).toBe(key === "__proto__" || Object.prototype.hasOwnProperty.call(Object.prototype, key))
+  })
+
+  it.each(PROTOTYPE_KEYS)("presetMinReferences(%j, …) counts nothing and never throws", (key) => {
+    expect(presetMinReferences(key, { prompt: "{image:1}" })).toBe(0)
+    expect(presetMinReferences(key, {}, 2)).toBe(2)
+  })
+
+  it.each(PROTOTYPE_KEYS)("the prompt-field registry has no spec for %j", (key) => {
+    expect(getPromptFields(key)).toBeUndefined()
+    expect(nodeSupportsPromptAffixes(key)).toBe(false)
+    expect(promptAffixCoreField(key)).toBeUndefined()
+    expect(promptFieldCarriesAffixes(key, "prompt")).toBe(false)
+  })
+
+  it.each(PROTOTYPE_KEYS)("computeNodePrompt(%j, …) falls back to the plain prompt field", (key) => {
+    expect(computeNodePrompt(key, { prompt: "a fox" }, { refMap: new Map() })).toBe("a fox")
+  })
+
+  it("a real node type still resolves (the fix narrows nothing)", () => {
+    expect(getFactoryPresets("generate-image").length).toBeGreaterThan(0)
+    expect(presetMinReferences("generate-image", { prompt: "{image:2:person}" })).toBe(2)
+    expect(getPromptFields("generate-image")?.prompt).toBe("prompt")
+  })
+})

package/src/__tests__/frame-reference-slots.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest"
+import { placeFramesAfterReferences } from "../frame-reference-slots.js"
+
+const R = (n: number) => Array.from({ length: n }, (_, i) => `r${i + 1}`)
+
+describe("placeFramesAfterReferences", () => {
+  it("puts the caller's references first and the frames after them, bound by seat", () => {
+    const r = placeFramesAfterReferences({ firstFrameUrl: "F", lastFrameUrl: "L", refImageUrls: R(2), imageCap: 9 })
+    expect(r.imageUrls).toEqual(["r1", "r2", "F", "L"])
+    expect(r.firstFrameOrdinal).toBe(3)
+    expect(r.lastFrameOrdinal).toBe(4)
+    expect(r.promptSuffix).toBe("Use @image_3 as the opening (first) frame and @image_4 as the closing (last) frame of the video.")
+    expect(r.droppedRefImages).toBe(0)
+  })
+
+  it("keeps the frames at the cap and drops trailing caller references", () => {
+    const r = placeFramesAfterReferences({ firstFrameUrl: "F", lastFrameUrl: "L", refImageUrls: R(3), imageCap: 3 })
+    expect(r.imageUrls).toEqual(["r1", "F", "L"])
+    expect(r.droppedRefImages).toBe(2)
+  })
+
+  it("writes the binding in the provider's own syntax", () => {
+    const grok = placeFramesAfterReferences({ firstFrameUrl: "F", refImageUrls: R(2), imageCap: 7, syntax: "@image(n)", bindIdentities: true })
+    expect(grok.promptSuffix).toBe(
+      "Use @image(3) as the opening (first) frame of the video. @image(1) through @image(2) are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
+    )
+    const hh = placeFramesAfterReferences({ firstFrameUrl: "F", refImageUrls: R(1), imageCap: 9, syntax: "[Image N]", bindIdentities: true })
+    expect(hh.promptSuffix).toBe(
+      "Use [Image 2] as the opening (first) frame of the video. [Image 1] is an identity reference for this shot's subjects — match its subject's exact appearance; it is not a frame.",
+    )
+  })
+
+  it("skips the opening sentence when the prompt already binds it (@image_N form)", () => {
+    const r = placeFramesAfterReferences({ prompt: "use @image_2 as the first frame", firstFrameUrl: "F", refImageUrls: R(1), imageCap: 9 })
+    expect(r.promptSuffix).toBe("")
+  })
+
+  it("binds nothing with no frame, and emits no identity sentence without one", () => {
+    const r = placeFramesAfterReferences({ refImageUrls: R(2), imageCap: 9, bindIdentities: true })
+    expect(r.imageUrls).toEqual(["r1", "r2"])
+    expect(r.promptSuffix).toBe("")
+  })
+})

package/src/__tests__/gemini-omni-inputs.test.ts

@@ -13,19 +13,20 @@ describe("resolveGeminiOmniI2vInputs", () => {
   const FIRST = "https://r2/anchor.png"
   const refs = (n: number) => Array.from({ length: n }, (_, i) => `https://r2/ref-${i + 1}.png`)
 
-  it("binds the roles: image 1 is the opening frame, the rest are identities — not frames", () => {
+  it("binds the roles: the references first (identities, not frames), the start frame appended after them", () => {
     const r = resolveGeminiOmniI2vInputs({ prompt: "a walk on the beach", firstFrameUrl: FIRST, refImageUrls: refs(3) })
-    expect(r.imageUrls).toEqual([FIRST, ...refs(3)])
+    expect(r.imageUrls).toEqual([...refs(3), FIRST])
     expect(r.promptSuffix).toBe(
-      "Use @image_1 as the opening (first) frame of the video. " +
-        "@image_2 through @image_4 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
+      "Use @image_4 as the opening (first) frame of the video. " +
+        "@image_1 through @image_3 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
     )
     expect(r.droppedRefImages).toBe(0)
   })
 
   it("a single reference gets the singular sentence", () => {
     const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(1) })
-    expect(r.promptSuffix).toContain("@image_2 is an identity reference")
+    expect(r.promptSuffix).toContain("@image_1 is an identity reference")
+    expect(r.promptSuffix).toContain("Use @image_2 as the opening (first) frame")
     expect(r.promptSuffix).not.toContain("through")
   })
 
@@ -37,11 +38,12 @@ describe("resolveGeminiOmniI2vInputs", () => {
   it("drops TRAILING references to fit the 7-input quota — the start frame is never the one that goes", () => {
     const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(9) })
     expect(r.imageUrls).toHaveLength(7)
-    expect(r.imageUrls[0]).toBe(FIRST)
-    expect(r.imageUrls.at(-1)).toBe("https://r2/ref-6.png")
+    expect(r.imageUrls.at(-1)).toBe(FIRST)
+    expect(r.imageUrls[5]).toBe("https://r2/ref-6.png")
     expect(r.droppedRefImages).toBe(3)
-    // The binding names exactly the kept span.
-    expect(r.promptSuffix).toContain("@image_2 through @image_7")
+    // The binding names exactly the kept span, and the frame's own seat.
+    expect(r.promptSuffix).toContain("@image_1 through @image_6")
+    expect(r.promptSuffix).toContain("Use @image_7 as the opening (first) frame")
   })
 
   it("a connected source video eats two slots (images + 2×videos ≤ 7)", () => {
@@ -62,7 +64,7 @@ describe("resolveGeminiOmniI2vInputs", () => {
 
   it("skips empty/undefined reference entries without burning slots", () => {
     const r = resolveGeminiOmniI2vInputs({ firstFrameUrl: FIRST, refImageUrls: [undefined, "", ...refs(2)] })
-    expect(r.imageUrls).toEqual([FIRST, ...refs(2)])
+    expect(r.imageUrls).toEqual([...refs(2), FIRST])
     expect(r.droppedRefImages).toBe(0)
   })
 })

package/src/__tests__/provider-prompt-doctrine.test.ts

@@ -98,6 +98,20 @@ describe("PROVIDER_PROMPT_DOCTRINES", () => {
     expect(d.doctrine).not.toMatch(/higher quality/i)
   })
 
+  it("Vidu Q4 has its own doctrine carrying the two-endpoint contract", () => {
+    const d = getPromptDoctrine("vidu-q4")!
+    expect(d.providers).toEqual(["vidu-q4"])
+    // Mode pick, the frame fold and the hard reference-audio contract.
+    expect(d.doctrine).toMatch(/reference-to-video/)
+    expect(d.doctrine).toMatch(/prompt is REQUIRED/)
+    expect(d.doctrine).toMatch(/no text-only mode/i)
+    expect(d.doctrine).toMatch(/MP3, each 3-12 seconds/)
+    expect(d.doctrine).toMatch(/1-15 reference images/)
+    // The binding the editor actually emits, not the contract's prose form.
+    expect(d.doctrine).toContain("@image_N")
+    expect(d.doctrine).toMatch(/20,000 characters/)
+  })
+
   it("Gemini Omni Flash rides the sibling's doctrine (identical request surface)", () => {
     const d = getPromptDoctrine("gemini-omni-flash")!
     expect(d).toBe(getPromptDoctrine("gemini-omni-video"))

package/src/__tests__/veo-i2v-inputs.test.ts

@@ -6,9 +6,10 @@ import { resolveVeoI2vInputs } from "../veo-i2v-inputs.js"
  * VEO 3.x i2v input resolution. VEO's API makes frame conditioning and
  * reference ingredients mutually exclusive (one imageUrls array, ≤3, whose
  * meaning flips with generationType) — so an anchored call that must carry
- * identity references moves to REFERENCE_2_VIDEO with the anchor in seat 1.
- * References win the seats (the 2026-08-14 standing rule: refs are a must,
- * frames additional): the end anchor is dropped in reference mode.
+ * identity references moves to REFERENCE_2_VIDEO. The platform frame-slot
+ * convention (2026-10-18): the caller's references take the first seats, the
+ * frames follow them, and at the 3-seat cap the frames are kept while
+ * trailing references drop.
  */
 describe("resolveVeoI2vInputs", () => {
   const FIRST = "https://r2/anchor.png"
@@ -24,26 +25,30 @@ describe("resolveVeoI2vInputs", () => {
     })
   })
 
-  it("references flip the call to REFERENCE_2_VIDEO with the anchor in seat 1, capped at 3", () => {
+  it("references flip the call to REFERENCE_2_VIDEO, references first and the anchor after them, capped at 3", () => {
     const r = resolveVeoI2vInputs({ prompt: "p", firstFrameUrl: FIRST, refImageUrls: refs(4) })
     expect(r.generationType).toBe("REFERENCE_2_VIDEO")
-    expect(r.imageUrls).toEqual([FIRST, "https://r2/ref-1.png", "https://r2/ref-2.png"])
+    expect(r.imageUrls).toEqual(["https://r2/ref-1.png", "https://r2/ref-2.png", FIRST])
     expect(r.droppedRefImages).toBe(2)
     expect(r.promptSuffix).toBe(
-      "Use @image_1 as the opening (first) frame of the video. " +
-        "@image_2 through @image_3 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
+      "Use @image_3 as the opening (first) frame of the video. " +
+        "@image_1 through @image_2 are identity references for this shot's subjects — match each subject's exact appearance; they are not frames.",
     )
   })
 
-  it("the end anchor is DROPPED in reference mode — references win the seats", () => {
+  it("the end frame is KEPT in reference mode — frames win the seats, a trailing reference drops", () => {
     const r = resolveVeoI2vInputs({ firstFrameUrl: FIRST, endFrameUrl: "https://r2/end.png", refImageUrls: refs(2) })
-    expect(r.imageUrls).toEqual([FIRST, "https://r2/ref-1.png", "https://r2/ref-2.png"])
-    expect(r.droppedEndFrame).toBe(true)
+    expect(r.imageUrls).toEqual(["https://r2/ref-1.png", FIRST, "https://r2/end.png"])
+    expect(r.droppedRefImages).toBe(1)
+    expect(r.droppedEndFrame).toBe(false)
+    expect(r.promptSuffix).toContain("Use @image_2 as the opening (first) frame and @image_3 as the closing (last) frame of the video.")
+    expect(r.promptSuffix).toContain("@image_1 is an identity reference")
   })
 
   it("a single kept reference gets the singular sentence", () => {
     const r = resolveVeoI2vInputs({ firstFrameUrl: FIRST, refImageUrls: refs(1) })
-    expect(r.promptSuffix).toContain("@image_2 is an identity reference")
+    expect(r.promptSuffix).toContain("@image_1 is an identity reference")
+    expect(r.promptSuffix).toContain("Use @image_2 as the opening (first) frame")
   })
 
   it("suppresses the opening-frame sentence when the prompt already binds it", () => {

package/src/entries/assembly.ts

@@ -20,6 +20,7 @@ export * from "../assemble-video-input.js"
 export * from "../seedance-2-inputs.js"
 export * from "../gemini-omni-inputs.js"
 export * from "../veo-i2v-inputs.js"
+export * from "../frame-reference-slots.js"
 export * from "../surround-fill.js"
 // --- Start/end frame delivery: one plan for the dispatch and the editor ---
 export * from "../frame-delivery.js"

package/src/factory-presets/index.ts

@@ -1,4 +1,5 @@
 import { T2I_TO_I2I_VARIANT } from "@nodaro/shared/models"
+import { ownEntry } from "../own-entry.js"
 import type { FactoryPreset } from "./types.js"
 import { stylizedSubjectFor, editsFor } from "./shared-image.js"
 import { GENERATE_IMAGE_PRESETS } from "./generate-image.js"
@@ -57,6 +58,8 @@ export const FACTORY_PRESETS: Readonly<Record<string, readonly FactoryPreset[]>>
   "lottie-overlay": LOTTIE_OVERLAY_PRESETS,
 }
 
+/** The catalog for `nodeType`, or an empty one — also for a name that is an
+ *  Object.prototype member (`constructor`), which is no catalog of ours. */
 export function getFactoryPresets(nodeType: string): readonly FactoryPreset[] {
-  return FACTORY_PRESETS[nodeType] ?? []
+  return ownEntry(FACTORY_PRESETS, nodeType) ?? []
 }

package/src/factory-presets/references.ts

@@ -1,6 +1,7 @@
 import { IMAGE_TOKEN_PATTERN } from "../image-token-pattern.js"
 import { getPromptFields, nodeSupportsPromptAffixes, promptAffixCoreField } from "../node-prompt-fields.js"
 import { NODE_PROMPT_CANDIDATE_FIELDS } from "../resolve-prompt.js"
+import { ownEntry } from "../own-entry.js"
 import { MODELS_WITH_REFERENCE_IMAGE_SUPPORT, imageReferenceLimit } from "@nodaro/shared/models"
 
 /**
@@ -25,7 +26,7 @@ export const MAX_PRESET_REFERENCES: number = Math.max(
  */
 function promptFieldsOf(nodeType: string): string[] {
   const spec = getPromptFields(nodeType)
-  const candidates = NODE_PROMPT_CANDIDATE_FIELDS[nodeType] ?? []
+  const candidates = ownEntry(NODE_PROMPT_CANDIDATE_FIELDS, nodeType) ?? []
   if (!spec && candidates.length === 0) return []
   const fields = new Set<string>(candidates)
   if (spec) {

package/src/frame-reference-slots.ts

@@ -0,0 +1,92 @@
+import { identityRefsSentence, imageBindingFor } from "./ref-binding.js"
+
+/**
+ * WHERE A START / END FRAME GOES WHEN IT SHARES A MODEL'S REFERENCE LIST — the
+ * one platform convention (2026-10-18), for every video model whose frames and
+ * reference images travel in a single image array (`videoProviderAppendsFrames`
+ * in @nodaro/shared):
+ *
+ *   - the caller's own reference images come FIRST, in their order, so the
+ *     caller's image token N (`{image:N}`, `{ref:<id>}`, a typed ordinal)
+ *     always means their Nth reference;
+ *   - the frames are appended AFTER them (start, then end) and named in the
+ *     prompt as the opening / closing frame, in the provider's own syntax;
+ *   - at the image cap the frames are KEPT — they are explicit intent — and
+ *     trailing caller references are dropped and reported.
+ *
+ * `bindIdentities` adds the identity sentence the flat-image-list models carry
+ * (Gemini Omni, VEO, Grok, HappyHorse: nothing in their payload says which
+ * entries are identities, so the prompt says it). The Seedance-family resolver
+ * calls this without it — byte for byte what it always emitted.
+ */
+export interface FrameReferenceSlotsArgs {
+  /** Consulted only to skip a duplicate opening-frame sentence. */
+  prompt?: string
+  firstFrameUrl?: string
+  lastFrameUrl?: string
+  /** The caller's own reference images, in priority order. */
+  refImageUrls?: readonly (string | undefined)[]
+  /** The provider's image cap — frames and references together. */
+  imageCap: number
+  /** The provider's reference syntax (`videoProviderReferenceSyntax`). */
+  syntax?: "@image_N" | "@image(n)" | "[Image N]"
+  bindIdentities?: boolean
+}
+
+export interface FrameReferenceSlotsResult {
+  /** `[...keptRefs, start?, end?]` — never longer than `imageCap` (bar the frames themselves). */
+  imageUrls: string[]
+  promptSuffix: string
+  /** Trailing caller references dropped to keep the frames. */
+  droppedRefImages: number
+  /** 1-based seats of the frames in `imageUrls`; 0 when absent. */
+  firstFrameOrdinal: number
+  lastFrameOrdinal: number
+}
+
+export function placeFramesAfterReferences(args: FrameReferenceSlotsArgs): FrameReferenceSlotsResult {
+  const refs = (args.refImageUrls ?? []).filter((u): u is string => typeof u === "string" && u.trim().length > 0)
+  const frameCount = (args.firstFrameUrl ? 1 : 0) + (args.lastFrameUrl ? 1 : 0)
+  const kept = refs.slice(0, Math.max(0, args.imageCap - frameCount))
+  const droppedRefImages = refs.length - kept.length
+
+  const imageUrls = [...kept]
+  let firstFrameOrdinal = 0
+  let lastFrameOrdinal = 0
+  if (args.firstFrameUrl) { imageUrls.push(args.firstFrameUrl); firstFrameOrdinal = imageUrls.length }
+  if (args.lastFrameUrl) { imageUrls.push(args.lastFrameUrl); lastFrameOrdinal = imageUrls.length }
+
+  const syntax = args.syntax ?? "@image_N"
+  const binding = imageBindingFor(syntax)
+  // The duplicate-binding check reads the platform's `@image_N` form, which is
+  // the only form a caller's prompt can already carry it in.
+  const promptBindsStart = syntax === "@image_N" && promptBindsFirstFrame(args.prompt)
+  let frameSentence = ""
+  if (promptBindsStart && firstFrameOrdinal > 0 && lastFrameOrdinal === 0) {
+    // The prompt already binds the first frame at its own (working) position.
+  } else if (firstFrameOrdinal > 0 && lastFrameOrdinal > 0) {
+    frameSentence = `Use ${binding.ordinal(firstFrameOrdinal)} as the opening (first) frame and ${binding.ordinal(lastFrameOrdinal)} as the closing (last) frame of the video.`
+  } else if (firstFrameOrdinal > 0) {
+    frameSentence = binding.frame(firstFrameOrdinal, "opening")
+  } else if (lastFrameOrdinal > 0) {
+    frameSentence = binding.frame(lastFrameOrdinal, "closing")
+  }
+  const identitySentence = args.bindIdentities && kept.length > 0 && frameCount > 0
+    ? identityRefsSentence(1, kept.length, binding.ordinal)
+    : ""
+  const promptSuffix = [frameSentence, identitySentence].filter(Boolean).join(" ")
+  return { imageUrls, promptSuffix, droppedRefImages, firstFrameOrdinal, lastFrameOrdinal }
+}
+
+/** True when the prompt ALREADY binds an image as the first/opening frame —
+ *  e.g. the gvp overlap transport's colon-position directive ("use @image_1
+ *  as the first frame, it is the last keyframe of @video_1"). Field finding
+ *  (2026-07-20): the first-frame directive only works adjacent to the extend
+ *  colon; a duplicate sentence at the END of the prompt (this resolver's
+ *  default position) dilutes it back into coin-flip behavior — so when the
+ *  prompt carries its own binding, the suffix is suppressed (the frame image
+ *  itself still rides the reference list). */
+export function promptBindsFirstFrame(prompt: string | undefined): boolean {
+  if (!prompt) return false
+  return /@image_\d+\s+as\s+the\s+(first|opening)\s*(\(first\))?\s*frame/i.test(prompt)
+}

package/src/gemini-omni-inputs.ts

@@ -1,30 +1,33 @@
 import { VIDEO_REF_LIMITS_BY_PROVIDER } from "@nodaro/shared/models"
 
-import { promptBindsFirstFrame } from "./seedance-2-inputs.js"
-import { identityRefsSentence, REF_BINDING } from "./video-reference-resolver.js"
+import { placeFramesAfterReferences } from "./frame-reference-slots.js"
 
 /**
  * Gemini Omni Video i2v input resolution — the sibling of
  * `resolveSeedance2Inputs` for a model whose multimodal channel is ONE flat
  * `image_urls` list.
  *
+ * THE PLATFORM CONVENTION (2026-10-18, `placeFramesAfterReferences`): the
+ * caller's identity references come first, so their image token N is their Nth
+ * reference, and the start frame is appended after them. Until then the frame
+ * led the list, so a caller's `@image_1` landed on the frame.
+ *
  * WHY BINDING IS LOAD-BEARING: Gemini Omni receives the start frame and the
  * identity references in the same array, with nothing in the payload marking
  * which is which. A multimodal model treats unbound images as loose context —
  * field finding (recast keyframes run, 2026-08-14): the identity references
  * rode every call and the cast still drifted part to part, because the prompt
  * never said the images WERE identities to keep. So the resolver names the
- * roles in a prompt suffix, through the same `REF_BINDING` swap-point every
- * other video binding uses: image 1 is the opening frame; the rest are
- * identity references, explicitly not frames.
+ * roles in a prompt suffix: the references are identity references, explicitly
+ * not frames, and the last image is the opening frame.
  *
  * BUDGETED, NEVER REJECTED, for the list this resolver assembles: KIE's quota
  * is `images + 2×videos ≤ 7`, and `runGeminiOmni` hard-rejects overflow. That
  * reject is right for a caller-assembled list (the user's own images should
  * not silently thin out) and wrong for THIS merge, where the overflow is our
  * own construction — so trailing references are dropped to fit, the start
- * frame always kept, mirroring `resolveSeedance2Inputs`' drop-trailing
- * convention, and the drop count is reported for the caller to log.
+ * frame always kept (the convention's tie-break), and the drop count is
+ * reported for the caller to log.
  *
  * BYTE-IDENTICAL when there is nothing to bind: no references ⇒ no suffix and
  * a single-image list — exactly what every plain gemini-omni i2v call has
@@ -34,7 +37,7 @@ import { identityRefsSentence, REF_BINDING } from "./video-reference-resolver.js
 export interface GeminiOmniI2vInputsArgs {
   /** The composed prompt, used only to detect an existing first-frame binding. */
   prompt?: string
-  /** The start frame — always kept, always first in the list. */
+  /** The start frame — always kept, appended after the references. */
   firstFrameUrl: string
   /** Identity references, in priority order (trailing ones drop first). */
   refImageUrls?: Array<string | undefined>
@@ -48,7 +51,7 @@ export interface GeminiOmniI2vInputsArgs {
 }
 
 export interface GeminiOmniI2vInputsResult {
-  /** `[firstFrameUrl, ...keptRefs]` — the `image_urls` payload, quota-fitted. */
+  /** `[...keptRefs, firstFrameUrl]` — the `image_urls` payload, quota-fitted. */
   imageUrls: string[]
   /** The role-binding sentences; empty when no reference survived the budget. */
   promptSuffix: string
@@ -64,18 +67,16 @@ function geminiOmniInputSlots(provider: string | undefined): number {
 }
 
 export function resolveGeminiOmniI2vInputs(args: GeminiOmniI2vInputsArgs): GeminiOmniI2vInputsResult {
-  const refs = (args.refImageUrls ?? []).filter((u): u is string => typeof u === "string" && u.length > 0)
   const slots = geminiOmniInputSlots(args.provider) - (args.videoConnected ? 2 : 0)
-  const refSlots = Math.max(0, slots - 1)
-  const kept = refs.slice(0, refSlots)
-  const droppedRefImages = refs.length - kept.length
-  const imageUrls = [args.firstFrameUrl, ...kept]
-  if (kept.length === 0) return { imageUrls, promptSuffix: "", droppedRefImages }
-
-  // The opening-frame sentence is suppressed when the prompt already binds it
-  // at its own (working) position — same field-finding rule as seedance-2: a
-  // duplicate directive at the end dilutes the one that works.
-  const frameSentence = promptBindsFirstFrame(args.prompt) ? "" : REF_BINDING.frame(1, "opening")
-  const promptSuffix = [frameSentence, identityRefsSentence(2, kept.length + 1)].filter(Boolean).join(" ")
-  return { imageUrls, promptSuffix, droppedRefImages }
+  const placed = placeFramesAfterReferences({
+    prompt: args.prompt,
+    firstFrameUrl: args.firstFrameUrl,
+    refImageUrls: args.refImageUrls,
+    imageCap: Math.max(1, slots),
+    bindIdentities: true,
+  })
+  if (placed.imageUrls.length === 1) {
+    return { imageUrls: placed.imageUrls, promptSuffix: "", droppedRefImages: placed.droppedRefImages }
+  }
+  return { imageUrls: placed.imageUrls, promptSuffix: placed.promptSuffix, droppedRefImages: placed.droppedRefImages }
 }

package/src/node-prompt-fields.ts

@@ -25,6 +25,7 @@
 
 import type { SnippetMedia } from "./factory-snippets/types.js"
 import { NODE_PROMPT_CANDIDATE_FIELDS } from "./resolve-prompt.js"
+import { ownEntry } from "./own-entry.js"
 
 /** Which lucide glyph a node's prompt affordance uses. Kept as a string so this
  *  module stays icon-library-free; mapped to a component in the strip button. */
@@ -136,9 +137,10 @@ export const NODE_PROMPT_FIELDS: Readonly<Record<string, PromptFieldSpec>> = {
   "edit-plan": { prompt: "instructions", promptLabel: "Editing instructions", media: "video", inline: false },
 }
 
-/** The prompt-field spec for a node type, or undefined if it has none. */
+/** The prompt-field spec for a node type, or undefined if it has none (an
+ *  Object.prototype member name such as `constructor` has none). */
 export function getPromptFields(nodeType: string | undefined): PromptFieldSpec | undefined {
-  return nodeType ? NODE_PROMPT_FIELDS[nodeType] : undefined
+  return nodeType ? ownEntry(NODE_PROMPT_FIELDS, nodeType) : undefined
 }
 
 /** True when this node type has a registered, quick-editable prompt field. */
@@ -206,7 +208,7 @@ export function promptFieldCarriesAffixes(nodeType: string | undefined, promptFi
   const core = promptAffixCoreField(nodeType)
   if (core === undefined) return false
   if (promptField === undefined) return getPromptFields(nodeType)!.prompt === core
-  return promptField === core || (NODE_PROMPT_CANDIDATE_FIELDS[nodeType!] ?? []).includes(promptField)
+  return promptField === core || (ownEntry(NODE_PROMPT_CANDIDATE_FIELDS, nodeType) ?? []).includes(promptField)
 }
 
 /** The affix-capable node types, derived from the registry (never hand-listed). */

package/src/own-entry.ts

@@ -0,0 +1,11 @@
+/**
+ * A registry keyed by node type is a plain object, and the key is
+ * caller-supplied (`?nodeType=` on a public route, a preset row's `node_type`,
+ * workflow JSON). A plain `record[key] ?? fallback` reads an Object.prototype
+ * member for `"constructor"`, `"toString"` or `"__proto__"` — a function or
+ * the prototype itself, which the caller then maps or iterates and throws on.
+ * This reads an OWN entry only, so such a name is "no such type".
+ */
+export function ownEntry<T>(record: Readonly<Record<string, T>>, key: string | undefined): T | undefined {
+  return key !== undefined && Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined
+}

package/src/prompt-wizard-categories.ts

@@ -267,6 +267,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "gemini-omni-flash": "Google Gemini Omni Flash — faster, cheaper Omni tier; multimodal video with native audio, 4–10s, up to 4K.",
     "wan-3": "Wan 3.0 — multimodal refs (10 images / 5 videos / 5 audio) or first+last frame, native audio, 2–30s, 480p/720p/1080p",
     "wan-3-prime": "Wan 3.0 Prime — high-speed Wan 3.0 tier; same surface, faster turnaround at a higher rate",
+    "vidu-q4": "Vidu Q4 — start frame or up to 15 reference images + 3 MP3 audio refs, native audio, 3–16s, 540p–4K (image required)",
     "grok-imagine-video-1.5": "Grok Imagine 1.5 — image-to-video only; requires an input image",
   },
   "image-to-video": {
@@ -303,6 +304,7 @@ export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
     "gemini-omni-flash": "Google Gemini Omni Flash — faster, cheaper Omni tier; multimodal video with native audio, 4–10s, up to 4K.",
     "wan-3": "Wan 3.0 — multimodal refs (10 images / 5 videos / 5 audio) or first+last frame, native audio, 2–30s, 480p/720p/1080p",
     "wan-3-prime": "Wan 3.0 Prime — high-speed Wan 3.0 tier; same surface, faster turnaround at a higher rate",
+    "vidu-q4": "Vidu Q4 — animate a start frame, or direct up to 15 reference images + 3 MP3 audio refs; native audio, 3–16s, 540p–4K",
     "grok-imagine-video-1.5": "Grok Imagine 1.5 — stylized animation, 1–15s, 480p/720p (image required)",
   },
   "video-to-video": {