Replace Prompt Builder beats with complete set framings.

Sets are places with labeled full-text framings; selecting a framing copies only that text, and legacy beat-only sets migrate to a wide framing.

Co-authored-by: Cursor <cursoragent@cursor.com>

tests/prompt-sequences.test.mjs

@@ -23,11 +23,10 @@ const {
   emptyCharacter,
   emptyOutfit,
   emptySet,
-  emptyBeat,
+  emptyFraming,
   cloneSceneForNext,
   normalizePromptSequence,
-  ensureSceneStatesForCharacters,
+  ensureSceneStatesForCharacters
-  beatMatchesShotSize
 } = await import(pathToFileURL(tmp).href)
 unlinkSync(tmp)
 
@@ -39,84 +38,112 @@ test('formatCharacterLine covers name/description and outfit', () => {
   )
 })
 
-test('shot size filters beats; untagged always included; tags never copied', () => {
+test('selecting a framing copies only that framing text; labels never appear', () => {
+  const wide = { ...emptyFraming('wide'), id: 'f-wide', text: 'open courtyard at dawn' }
+  const medium = { ...emptyFraming('medium'), id: 'f-med', text: 'courtyard from the arch' }
+  const narrow = { ...emptyFraming('narrow'), id: 'f-nar', text: 'door latch detail' }
   const set = {
     ...emptySet(),
     id: 's1',
-    name: 'BadgeSet',
+    name: 'Courtyard',
-    description: 'studio backdrop',
+    framings: [wide, medium, narrow]
-    beats: [
-      { ...emptyBeat(), id: 'b1', name: 'WideBeat', text: 'wide only line', framings: ['wide'] },
-      { ...emptyBeat(), id: 'b2', name: 'WideMed', text: 'wide and medium', framings: ['wide', 'medium'] },
-      { ...emptyBeat(), id: 'b3', name: 'Always', text: 'untagged beat', framings: [] },
-      { ...emptyBeat(), id: 'b4', name: 'CU', text: 'close only', framings: ['close-up'] }
-    ]
   }
-  const sceneMedium = {
+  const base = {
     style: 'style',
     settings: 'settings',
-    shotSize: 'medium',
-    setStates: [{ setId: 's1', on: true }],
     characterStates: [],
     prompt: 'prompt'
   }
-  const mediumText = assembleSceneText(sceneMedium, [], [set])
+  const mediumText = assembleSceneText({
-  assert.equal(
+    ...base,
-    mediumText,
+    setStates: [{ setId: 's1', on: true, framingId: 'f-med' }]
-    'style\n\nsettings\n\nstudio backdrop\nwide and medium\nuntagged beat\n\nprompt'
+  }, [], [set])
-  )
+  assert.equal(mediumText, 'style\n\nsettings\n\ncourtyard from the arch\n\nprompt')
-  assert.ok(!mediumText.includes('wide only'))
+  assert.ok(!mediumText.includes('open courtyard'))
-  assert.ok(!mediumText.includes('close only'))
+  assert.ok(!mediumText.includes('door latch'))
-  assert.ok(!mediumText.includes('BadgeSet'))
+  assert.ok(!mediumText.includes('Courtyard'))
-  assert.ok(!mediumText.includes('WideBeat'))
+  assert.ok(!mediumText.includes('wide'))
-  assert.ok(!mediumText.includes('close-up'))
+  assert.ok(!mediumText.includes('medium'))
-  assert.ok(!/\bwide\b/.test(mediumText.replace('wide and medium', '')))
+  assert.ok(!mediumText.includes('narrow'))
 
-  const sceneClose = { ...sceneMedium, shotSize: 'close-up' }
+  const narrowText = assembleSceneText({
-  const closeText = assembleSceneText(sceneClose, [], [set])
+    ...base,
-  assert.equal(
+    setStates: [{ setId: 's1', on: true, framingId: 'f-nar' }]
-    closeText,
+  }, [], [set])
-    'style\n\nsettings\n\nstudio backdrop\nuntagged beat\nclose only\n\nprompt'
+  assert.equal(narrowText, 'style\n\nsettings\n\ndoor latch detail\n\nprompt')
-  )
+  assert.ok(!narrowText.includes('open courtyard'))
+  assert.ok(!narrowText.includes('from the arch'))
 
-  const sceneAny = { ...sceneMedium, shotSize: '' }
+  const noneText = assembleSceneText({
-  const anyText = assembleSceneText(sceneAny, [], [set])
+    ...base,
-  assert.ok(anyText.includes('wide only line'))
+    setStates: [{ setId: 's1', on: true, framingId: null }]
-  assert.ok(anyText.includes('wide and medium'))
+  }, [], [set])
-  assert.ok(anyText.includes('untagged beat'))
+  assert.equal(noneText, 'style\n\nsettings\n\nprompt')
-  assert.ok(anyText.includes('close only'))
-
-  assert.equal(beatMatchesShotSize({ framings: ['wide'] }, 'medium'), false)
-  assert.equal(beatMatchesShotSize({ framings: [] }, 'medium'), true)
 })
 
-test('off set omitted; copy scene is one scene; sequence join is double blank', () => {
+test('off set is omitted; sequence join is double blank', () => {
-  const set = {
+  const framing = { ...emptyFraming('wide'), id: 'f1', text: 'set text' }
-    ...emptySet(),
+  const set = { ...emptySet(), id: 's1', name: 'Place', framings: [framing] }
-    id: 's1',
-    description: 'set desc',
-    beats: [{ ...emptyBeat(), text: 'beat', framings: [] }]
-  }
   const scene1 = {
     style: 'a',
     settings: '',
-    shotSize: '',
+    setStates: [{ setId: 's1', on: true, framingId: 'f1' }],
-    setStates: [{ setId: 's1', on: true }],
     characterStates: [],
     prompt: 'p1'
   }
   const scene2 = {
     style: 'b',
     settings: '',
-    shotSize: '',
+    setStates: [{ setId: 's1', on: false, framingId: 'f1' }],
-    setStates: [{ setId: 's1', on: false }],
     characterStates: [],
     prompt: 'p2'
   }
   assert.equal(assembleSceneText(scene2, [], [set]), 'b\n\np2')
   const full = assembleSequenceText({ sets: [set], scenes: [scene1, scene2] })
-  assert.equal(full, 'a\n\nset desc\nbeat\n\np1\n\n\nb\n\np2')
+  assert.equal(full, 'a\n\nset text\n\np1\n\n\nb\n\np2')
-  assert.equal(assembleSceneText(scene1, [], [set]), 'a\n\nset desc\nbeat\n\np1')
+  assert.ok(!full.includes('Place'))
+  assert.ok(!full.includes('wide'))
+})
+
+test('legacy beat-only set still opens as one wide framing', () => {
+  const legacy = normalizePromptSequence({
+    id: 'seq1',
+    name: 'Old beats',
+    sets: [{
+      id: 's1',
+      name: 'Hall',
+      description: 'stone walls',
+      beats: [
+        { id: 'b1', name: 'Beat1', text: 'first beat', framings: ['wide'] },
+        { id: 'b2', name: 'Beat2', text: 'second beat', framings: ['medium'] }
+      ]
+    }],
+    scenes: [{
+      id: 'sc1',
+      title: 'Scene 1',
+      style: 'oil',
+      settings: '',
+      shotSize: 'wide',
+      setStates: [{ setId: 's1', on: true }],
+      prompt: 'walk',
+      characters: []
+    }],
+    characters: [{ id: 'x', name: 'Ada', description: 'tall', outfits: [] }],
+    createdAt: 1,
+    updatedAt: 1
+  })
+  assert.equal(legacy.sets.length, 1)
+  assert.equal(legacy.sets[0].framings.length, 1)
+  assert.equal(legacy.sets[0].framings[0].label, 'wide')
+  assert.ok(legacy.sets[0].framings[0].text.includes('stone walls'))
+  assert.ok(legacy.sets[0].framings[0].text.includes('first beat'))
+  assert.ok(legacy.sets[0].framings[0].text.includes('second beat'))
+  assert.equal(legacy.scenes[0].setStates[0].framingId, legacy.sets[0].framings[0].id)
+  const text = assembleSequenceText(legacy)
+  assert.ok(text.includes('stone walls'))
+  assert.ok(text.includes('first beat'))
+  assert.ok(!text.includes('Hall'))
+  assert.ok(!text.includes('Beat1'))
 })
 
 test('legacy sequence without sets still assembles', () => {
@@ -137,19 +164,17 @@ test('legacy sequence without sets still assembles', () => {
     updatedAt: 1
   })
   assert.deepEqual(legacy.sets, [])
-  assert.equal(legacy.scenes[0].shotSize, '')
+  assert.equal(assembleSequenceText(legacy), 'oil\n\nAda: tall\n\nwalk')
-  const text = assembleSequenceText(legacy)
-  assert.equal(text, 'oil\n\nAda: tall\n\nwalk')
 })
 
-test('cloneSceneForNext copies shotSize and setStates', () => {
+test('cloneSceneForNext copies setStates including framingId', () => {
   const sets = [emptySet()]
   const first = emptyScene(1, [], sets)
-  first.shotSize = 'close-up'
   first.setStates[0].on = false
+  first.setStates[0].framingId = sets[0].framings[0].id
   const next = cloneSceneForNext(first, 2)
-  assert.equal(next.shotSize, 'close-up')
   assert.equal(next.setStates[0].on, false)
+  assert.equal(next.setStates[0].framingId, sets[0].framings[0].id)
   assert.equal(next.setStates[0].setId, sets[0].id)
 })
 
@@ -164,7 +189,6 @@ test('character outfit and off still work with sets', () => {
   const text = assembleSceneText({
     style: '',
     settings: '',
-    shotSize: '',
     setStates: [],
     characterStates: [{ characterId: 'c1', on: true, outfitId: 'o1' }],
     prompt: 'hi'

utils/promptSequences.ts

@@ -18,28 +18,26 @@ export type PromptSequenceCharacterState = {
   outfitId: string | null
 }
 
-export type PromptSequenceShotSize = '' | 'wide' | 'medium' | 'close-up' | 'detail'
+/** Suggested labels only — not a hard enum. */
+export const PROMPT_SEQUENCE_FRAMING_SUGGESTIONS = ['wide', 'medium', 'narrow'] as const
 
-export const PROMPT_SEQUENCE_SHOT_SIZES = ['wide', 'medium', 'close-up', 'detail'] as const
+export type PromptSequenceFraming = {
-
-export type PromptSequenceBeat = {
   id: string
-  name: string
+  label: string
   text: string
-  /** Empty = always include for any shot size. */
-  framings: Array<'wide' | 'medium' | 'close-up' | 'detail'>
 }
 
 export type PromptSequenceSet = {
   id: string
   name: string
-  description: string
+  framings: PromptSequenceFraming[]
-  beats: PromptSequenceBeat[]
 }
 
 export type PromptSequenceSetState = {
   setId: string
   on: boolean
+  /** Chosen framing for this set in this scene (like outfitId). Empty = copy nothing. */
+  framingId: string | null
 }
 
 export type PromptSequenceScene = {
@@ -47,7 +45,6 @@ export type PromptSequenceScene = {
   title: string
   style: string
   settings: string
-  shotSize: PromptSequenceShotSize
   setStates: PromptSequenceSetState[]
   characterStates: PromptSequenceCharacterState[]
   prompt: string
@@ -82,20 +79,20 @@ export function emptyCharacter(): PromptSequenceCharacter {
   return { id: newId(), name: '', description: '', outfits: [] }
 }
 
-export function emptyBeat(): PromptSequenceBeat {
+export function emptyFraming(label = ''): PromptSequenceFraming {
-  return { id: newId(), name: '', text: '', framings: [] }
+  return { id: newId(), label, text: '' }
 }
 
 export function emptySet(): PromptSequenceSet {
-  return { id: newId(), name: '', description: '', beats: [emptyBeat()] }
+  return { id: newId(), name: '', framings: [emptyFraming()] }
 }
 
 export function defaultCharacterState(characterId: string, on = true): PromptSequenceCharacterState {
   return { characterId, on, outfitId: null }
 }
 
-export function defaultSetState(setId: string, on = true): PromptSequenceSetState {
+export function defaultSetState(setId: string, on = true, framingId: string | null = null): PromptSequenceSetState {
-  return { setId, on }
+  return { setId, on, framingId }
 }
 
 export function emptyScene(
@@ -108,8 +105,7 @@ export function emptyScene(
     title: `Scene ${Math.max(1, index)}`,
     style: '',
     settings: '',
-    shotSize: '',
+    setStates: sets.map(set => defaultSetState(set.id, true, null)),
-    setStates: sets.map(set => defaultSetState(set.id, true)),
     characterStates: characters.map(character => defaultCharacterState(character.id, true)),
     prompt: ''
   }
@@ -121,10 +117,10 @@ export function cloneSceneForNext(previous: PromptSequenceScene, nextIndex: numb
     title: `Scene ${nextIndex}`,
     style: previous.style,
     settings: previous.settings,
-    shotSize: previous.shotSize || '',
     setStates: (previous.setStates || []).map(state => ({
       setId: state.setId,
-      on: !!state.on
+      on: !!state.on,
+      framingId: state.framingId || null
     })),
     characterStates: (previous.characterStates || []).map(state => ({
       characterId: state.characterId,
@@ -160,19 +156,9 @@ export function formatCharacterLine(
   return `${base}. Outfit: ${outfitText}`
 }
 
-export function beatMatchesShotSize(
+/** Selected framing text for each on set. No set name, no framing label. */
-  beat: { framings?: string[] },
-  shotSize: string = ''
-) {
-  const framings = Array.isArray(beat.framings) ? beat.framings.filter(Boolean) : []
-  if (!framings.length) return true
-  if (!shotSize) return true
-  return framings.includes(shotSize)
-}
-
-/** Set description + matching beat texts (one per line). No set/beat names or framing tags. */
 export function assembleSetBlock(
-  scene: { shotSize?: string; setStates?: PromptSequenceSetState[] },
+  scene: { setStates?: PromptSequenceSetState[] },
   sets: PromptSequenceSet[] = []
 ) {
   const states = scene.setStates || []
@@ -181,13 +167,11 @@ export function assembleSetBlock(
   for (const set of sets) {
     const state = stateById.get(set.id)
     if (state && !state.on) continue
-    const description = String(set.description || '').trim()
+    const framingId = state?.framingId || null
-    const beatLines = (set.beats || [])
+    if (!framingId) continue
-      .filter(beat => beatMatchesShotSize(beat, scene.shotSize || ''))
+    const framing = (set.framings || []).find(item => item.id === framingId)
-      .map(beat => String(beat.text || '').trim())
+    const text = String(framing?.text || '').trim()
-      .filter(Boolean)
+    if (text) chunks.push(text)
-    const lines = [description, ...beatLines].filter(Boolean)
-    if (lines.length) chunks.push(lines.join('\n'))
   }
   return chunks.join('\n')
 }
@@ -216,7 +200,6 @@ export function assembleSceneText(
     style?: string
     settings?: string
     prompt?: string
-    shotSize?: string
     setStates?: PromptSequenceSetState[]
     characterStates?: PromptSequenceCharacterState[]
     /** Legacy per-scene characters (migration / old tests). */
@@ -256,7 +239,6 @@ export function assembleSequenceText(sequence: {
     style?: string
     settings?: string
     prompt?: string
-    shotSize?: string
     setStates?: PromptSequenceSetState[]
     characterStates?: PromptSequenceCharacterState[]
     characters?: Array<{ name?: string; description?: string }>
@@ -287,12 +269,6 @@ export function normalizePromptSequenceTitle(raw: unknown, fallback: string) {
   return title || fallback
 }
 
-export function normalizeShotSize(raw: unknown): PromptSequenceShotSize {
-  const value = String(raw || '').trim()
-  if (value === 'wide' || value === 'medium' || value === 'close-up' || value === 'detail') return value
-  return ''
-}
-
 export function normalizeOutfit(raw: unknown): PromptSequenceOutfit {
   const rec = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
   return {
@@ -313,29 +289,46 @@ export function normalizeCharacter(raw: unknown): PromptSequenceCharacter {
   }
 }
 
-export function normalizeBeat(raw: unknown): PromptSequenceBeat {
+export function normalizeFraming(raw: unknown): PromptSequenceFraming {
   const rec = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
-  const framings = Array.isArray(rec.framings)
-    ? [...new Set(rec.framings.map(item => String(item || '').trim()).filter((item): item is 'wide' | 'medium' | 'close-up' | 'detail' =>
-      item === 'wide' || item === 'medium' || item === 'close-up' || item === 'detail'
-    ))]
-    : []
   return {
     id: String(rec.id || '').trim() || newId(),
-    name: String(rec.name || '').trim().slice(0, 120),
+    label: String(rec.label || '').trim().slice(0, 120),
-    text: normalizePromptSequenceField(rec.text),
+    text: normalizePromptSequenceField(rec.text)
-    framings
   }
 }
 
+/** Fold legacy beat-only sets into one framing labeled "wide". */
+function framingsFromLegacyBeats(rec: Record<string, unknown>): PromptSequenceFraming[] {
+  const parts: string[] = []
+  const description = normalizePromptSequenceField(rec.description).trim()
+  if (description) parts.push(description)
+  const beats = Array.isArray(rec.beats) ? rec.beats : []
+  for (const beat of beats) {
+    if (!beat || typeof beat !== 'object') continue
+    const text = normalizePromptSequenceField((beat as Record<string, unknown>).text).trim()
+    if (text) parts.push(text)
+  }
+  if (!parts.length) return [emptyFraming()]
+  return [{ id: newId(), label: 'wide', text: parts.join('\n') }]
+}
+
 export function normalizeSet(raw: unknown): PromptSequenceSet {
   const rec = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
-  const beats = Array.isArray(rec.beats) ? rec.beats.map(normalizeBeat) : []
+  let framings: PromptSequenceFraming[]
+  if (Array.isArray(rec.framings) && rec.framings.length) {
+    framings = rec.framings.map(normalizeFraming)
+  } else if (Array.isArray(rec.beats) && rec.beats.length) {
+    framings = framingsFromLegacyBeats(rec)
+  } else if (String(rec.description || '').trim()) {
+    framings = framingsFromLegacyBeats(rec)
+  } else {
+    framings = [emptyFraming()]
+  }
   return {
     id: String(rec.id || '').trim() || newId(),
     name: String(rec.name || '').trim().slice(0, 120),
-    description: normalizePromptSequenceField(rec.description),
+    framings
-    beats: beats.length ? beats : [emptyBeat()]
   }
 }
 
@@ -351,11 +344,30 @@ export function normalizeCharacterState(raw: unknown, fallbackCharacterId = ''):
   }
 }
 
-export function normalizeSetState(raw: unknown, fallbackSetId = ''): PromptSequenceSetState {
+export function normalizeSetState(
+  raw: unknown,
+  fallbackSetId = '',
+  sets: PromptSequenceSet[] = [],
+  legacyShotSize = ''
+): PromptSequenceSetState {
   const rec = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+  const setId = String(rec.setId || fallbackSetId || '').trim()
+  const framingRaw = rec.framingId
+  let framingId = framingRaw == null || framingRaw === '' ? null : String(framingRaw).trim() || null
+  const set = sets.find(item => item.id === setId)
+  if (framingId && set && !set.framings.some(framing => framing.id === framingId)) {
+    framingId = null
+  }
+  if (!framingId && legacyShotSize && set) {
+    const match = set.framings.find(
+      framing => framing.label.trim().toLowerCase() === legacyShotSize.trim().toLowerCase()
+    )
+    if (match) framingId = match.id
+  }
   return {
-    setId: String(rec.setId || fallbackSetId || '').trim(),
+    setId,
-    on: rec.on === undefined ? true : !!rec.on
+    on: rec.on === undefined ? true : !!rec.on,
+    framingId
   }
 }
 
@@ -400,16 +412,32 @@ function syncCharacterStates(
 function syncSetStates(
   statesRaw: unknown,
   sets: PromptSequenceSet[],
-  defaultOn = true
+  defaultOn = true,
+  legacyShotSize = ''
 ): PromptSequenceSetState[] {
   const incoming = Array.isArray(statesRaw)
-    ? statesRaw.map(state => normalizeSetState(state)).filter(state => state.setId)
+    ? statesRaw.map(state => normalizeSetState(state, '', sets, legacyShotSize)).filter(state => state.setId)
     : []
   const byId = new Map(incoming.map(state => [state.setId, state]))
   return sets.map((set) => {
     const existing = byId.get(set.id)
-    if (existing) return { setId: set.id, on: existing.on }
+    if (existing) {
-    return defaultSetState(set.id, defaultOn)
+      const framingOk = existing.framingId
+        && set.framings.some(framing => framing.id === existing.framingId)
+      return {
+        setId: set.id,
+        on: existing.on,
+        framingId: framingOk ? existing.framingId : null
+      }
+    }
+    let framingId: string | null = null
+    if (legacyShotSize) {
+      const match = set.framings.find(
+        framing => framing.label.trim().toLowerCase() === legacyShotSize.trim().toLowerCase()
+      )
+      if (match) framingId = match.id
+    }
+    return defaultSetState(set.id, defaultOn, framingId)
   })
 }
 
@@ -420,13 +448,13 @@ export function normalizeScene(
   sets: PromptSequenceSet[] = []
 ): PromptSequenceScene {
   const rec = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+  const legacyShotSize = String(rec.shotSize || '').trim()
   return {
     id: String(rec.id || '').trim() || newId(),
     title: normalizePromptSequenceTitle(rec.title, `Scene ${index + 1}`),
     style: normalizePromptSequenceField(rec.style),
     settings: normalizePromptSequenceField(rec.settings),
-    shotSize: normalizeShotSize(rec.shotSize),
+    setStates: syncSetStates(rec.setStates, sets, true, legacyShotSize),
-    setStates: syncSetStates(rec.setStates, sets, true),
     characterStates: syncCharacterStates(rec.characterStates, characters, true),
     prompt: normalizePromptSequenceField(rec.prompt)
   }
@@ -493,11 +521,19 @@ export function ensureSceneStatesForSets(
     const byId = new Map((scene.setStates || []).map(state => [state.setId, state]))
     scene.setStates = sets.map((set) => {
       const existing = byId.get(set.id)
-      if (existing) return existing
+      if (existing) {
+        const framingOk = existing.framingId
+          && set.framings.some(framing => framing.id === existing.framingId)
+        return {
+          setId: set.id,
+          on: existing.on,
+          framingId: framingOk ? existing.framingId : null
+        }
+      }
       const on = newSetId && set.id === newSetId
         ? i === turnOnIndex
         : true
-      return defaultSetState(set.id, on)
+      return defaultSetState(set.id, on, null)
     })
   }
 }