From 7799529788abff136fee50a073122deb105f687d Mon Sep 17 00:00:00 2001
From: Towsty <ianjmcarr@gmail.com>
Date: Fri, 2 Oct 2026 08:50:31 -0500
Subject: [PATCH] Extend Prompt Builder with sequence characters, outfits, and
 scene toggles.

Characters live on the sequence with per-scene on/off and outfit picks; Copy scene exports only the active tab; legacy saves still open.
---
 pages/prompt-builder.vue                  | 319 +++++++++++++++++-----
 server/api/prompt-sequences.post.ts       |   2 +
 server/api/prompt-sequences/[id].patch.ts |   3 +-
 server/utils/promptSequences.ts           |  32 ++-
 tests/prompt-sequences.test.mjs           | 132 ++++++---
 utils/promptSequences.ts                  | 228 +++++++++++++---
 6 files changed, 569 insertions(+), 147 deletions(-)

diff --git a/pages/prompt-builder.vue b/pages/prompt-builder.vue
index 002a1fc..e0f0b40 100644
--- a/pages/prompt-builder.vue
+++ b/pages/prompt-builder.vue
@@ -44,6 +44,89 @@
           <p class="mt-1 text-[11px] text-zinc-500">Save key only — never copied into the prompt text.</p>
         </label>
 
+        <div class="space-y-3">
+          <div class="flex flex-wrap items-center justify-between gap-2">
+            <div>
+              <span class="text-sm font-medium text-zinc-300">Characters</span>
+              <p class="text-[11px] text-zinc-500">Sequence-wide. Toggle and outfit per scene below.</p>
+            </div>
+            <button
+              type="button"
+              class="rounded-full border border-white/10 px-3 py-1 text-[11px] text-zinc-300 hover:border-amber-300/50 hover:text-white"
+              @click="addCharacter"
+            >
+              Add character
+            </button>
+          </div>
+          <div
+            v-for="(character, cIndex) in characters"
+            :key="character.id"
+            class="rounded-2xl border border-white/10 bg-zinc-950/40 p-3 space-y-3"
+          >
+            <div class="flex items-center justify-between gap-2">
+              <span class="text-[11px] uppercase tracking-wide text-zinc-500">Character {{ cIndex + 1 }}</span>
+              <div class="flex items-center gap-2">
+                <button type="button" class="text-[11px] text-zinc-500 hover:text-amber-200" @click="clearCharacter(cIndex)">Clear</button>
+                <button
+                  v-if="characters.length > 1"
+                  type="button"
+                  class="text-[11px] text-zinc-500 hover:text-red-300"
+                  @click="removeCharacter(cIndex)"
+                >
+                  Remove
+                </button>
+              </div>
+            </div>
+            <input
+              v-model="character.name"
+              class="w-full rounded-xl border border-white/10 bg-zinc-950 px-3 py-2 text-sm outline-none ring-amber-300/40 placeholder:text-zinc-600 focus:ring-2"
+              maxlength="120"
+              placeholder="Name"
+            >
+            <textarea
+              v-model="character.description"
+              rows="2"
+              class="w-full rounded-xl border border-white/10 bg-zinc-950/70 px-3 py-2 text-sm outline-none ring-amber-300/40 placeholder:text-zinc-600 focus:ring-2"
+              placeholder="Description"
+            />
+            <div class="space-y-2 border-t border-white/5 pt-3">
+              <div class="flex flex-wrap items-center justify-between gap-2">
+                <span class="text-[11px] font-medium uppercase tracking-wide text-zinc-500">Outfits</span>
+                <button
+                  type="button"
+                  class="text-[11px] text-zinc-400 hover:text-amber-200"
+                  @click="addOutfit(cIndex)"
+                >
+                  Add outfit
+                </button>
+              </div>
+              <p v-if="!character.outfits.length" class="text-[11px] text-zinc-600">No outfits yet.</p>
+              <div
+                v-for="(outfit, oIndex) in character.outfits"
+                :key="outfit.id"
+                class="rounded-xl border border-white/5 bg-zinc-950/50 p-2 space-y-2"
+              >
+                <div class="flex items-center justify-between gap-2">
+                  <span class="text-[11px] text-zinc-500">Outfit {{ oIndex + 1 }}</span>
+                  <button type="button" class="text-[11px] text-zinc-500 hover:text-red-300" @click="removeOutfit(cIndex, oIndex)">Remove</button>
+                </div>
+                <input
+                  v-model="outfit.name"
+                  class="w-full rounded-lg border border-white/10 bg-zinc-950 px-2.5 py-1.5 text-sm outline-none ring-amber-300/40 placeholder:text-zinc-600 focus:ring-2"
+                  maxlength="120"
+                  placeholder="Outfit name"
+                >
+                <textarea
+                  v-model="outfit.description"
+                  rows="2"
+                  class="w-full rounded-lg border border-white/10 bg-zinc-950/70 px-2.5 py-1.5 text-sm outline-none ring-amber-300/40 placeholder:text-zinc-600 focus:ring-2"
+                  placeholder="What they are wearing"
+                />
+              </div>
+            </div>
+          </div>
+        </div>
+
         <div class="flex flex-wrap items-center gap-2 border-b border-white/10 pb-2">
           <button
             v-for="(scene, index) in scenes"
@@ -107,47 +190,37 @@
           </div>
 
           <div class="space-y-3">
-            <div class="flex flex-wrap items-center justify-between gap-2">
-              <span class="text-sm font-medium text-zinc-300">Characters</span>
-              <button
-                type="button"
-                class="rounded-full border border-white/10 px-3 py-1 text-[11px] text-zinc-300 hover:border-amber-300/50 hover:text-white"
-                @click="addCharacter"
-              >
-                Add character
-              </button>
+            <div>
+              <span class="text-sm font-medium text-zinc-300">In this scene</span>
+              <p class="text-[11px] text-zinc-500">Toggle who appears. Pick an outfit for each on character.</p>
             </div>
             <div
-              v-for="(character, cIndex) in activeScene.characters"
-              :key="character.id"
-              class="rounded-2xl border border-white/10 bg-zinc-950/40 p-3 space-y-2"
+              v-for="character in characters"
+              :key="'scene-'+character.id"
+              class="rounded-2xl border border-white/10 bg-zinc-950/40 px-3 py-2.5 space-y-2"
             >
-              <div class="flex items-center justify-between gap-2">
-                <span class="text-[11px] uppercase tracking-wide text-zinc-500">Character {{ cIndex + 1 }}</span>
-                <div class="flex items-center gap-2">
-                  <button type="button" class="text-[11px] text-zinc-500 hover:text-amber-200" @click="clearCharacter(cIndex)">Clear</button>
-                  <button
-                    v-if="activeScene.characters.length > 1"
-                    type="button"
-                    class="text-[11px] text-zinc-500 hover:text-red-300"
-                    @click="removeCharacter(cIndex)"
-                  >
-                    Remove
-                  </button>
-                </div>
-              </div>
-              <input
-                v-model="character.name"
-                class="w-full rounded-xl border border-white/10 bg-zinc-950 px-3 py-2 text-sm outline-none ring-amber-300/40 placeholder:text-zinc-600 focus:ring-2"
-                maxlength="120"
-                placeholder="Name"
-              >
-              <textarea
-                v-model="character.description"
-                rows="2"
-                class="w-full rounded-xl border border-white/10 bg-zinc-950/70 px-3 py-2 text-sm outline-none ring-amber-300/40 placeholder:text-zinc-600 focus:ring-2"
-                placeholder="Description"
-              />
+              <label class="flex items-center justify-between gap-3 text-sm text-zinc-200">
+                <span class="min-w-0 truncate">{{ character.name || 'Unnamed character' }}</span>
+                <input
+                  type="checkbox"
+                  class="accent-amber-400"
+                  :checked="isCharacterOn(character.id)"
+                  @change="setCharacterOn(character.id, ($event.target as HTMLInputElement).checked)"
+                >
+              </label>
+              <label v-if="isCharacterOn(character.id)" class="block text-[11px] text-zinc-500">
+                Outfit
+                <select
+                  class="mt-1 w-full rounded-xl border border-white/10 bg-zinc-950 px-3 py-2 text-sm text-zinc-200 outline-none ring-amber-300/40 focus:ring-2"
+                  :value="activeOutfitId(character.id) || ''"
+                  @change="setCharacterOutfit(character.id, ($event.target as HTMLSelectElement).value)"
+                >
+                  <option value="">None</option>
+                  <option v-for="outfit in character.outfits" :key="outfit.id" :value="outfit.id">
+                    {{ outfit.name || 'Untitled outfit' }}
+                  </option>
+                </select>
+              </label>
             </div>
           </div>
 
@@ -172,6 +245,14 @@
               <p class="text-[11px] text-zinc-500">Assembled text ready to copy. Sequence name is omitted.</p>
             </div>
             <div class="flex items-center gap-2">
+              <button
+                type="button"
+                class="rounded-full border border-white/10 px-3 py-1.5 text-xs text-zinc-300 hover:border-amber-300/50 hover:text-white disabled:opacity-50"
+                :disabled="!activeSceneText"
+                @click="copyScene"
+              >
+                {{ copiedScene ? 'Scene copied' : 'Copy scene' }}
+              </button>
               <button
                 type="button"
                 class="rounded-full border border-white/10 px-3 py-1.5 text-xs text-zinc-300 hover:border-amber-300/50 hover:text-white disabled:opacity-50"
@@ -219,6 +300,7 @@
                   <p class="truncate text-sm font-medium text-zinc-100">{{ sequence.name }}</p>
                   <p class="mt-0.5 text-[11px] text-zinc-500">
                     {{ sequence.scenes?.length || 0 }} scene{{ (sequence.scenes?.length || 0) === 1 ? '' : 's' }}
+                    · {{ sequence.characters?.length || 0 }} character{{ (sequence.characters?.length || 0) === 1 ? '' : 's' }}
                   </p>
                 </div>
                 <button
@@ -238,12 +320,20 @@
 </template>
 
 <script setup lang="ts">
-import type { PromptSequence, PromptSequenceScene } from '~/utils/promptSequences'
+import type {
+  PromptSequence,
+  PromptSequenceCharacter,
+  PromptSequenceScene
+} from '~/utils/promptSequences'
 import {
+  assembleSceneText,
   assembleSequenceText,
   cloneSceneForNext,
   emptyCharacter,
-  emptyScene
+  emptyOutfit,
+  emptyScene,
+  ensureSceneStatesForCharacters,
+  normalizePromptSequence
 } from '~/utils/promptSequences'
 
 useHead({ title: 'Prompt Builder' })
@@ -251,65 +341,149 @@ useHead({ title: 'Prompt Builder' })
 const sequences = ref<PromptSequence[]>([])
 const selectedId = ref('')
 const name = ref('')
-const scenes = ref<PromptSequenceScene[]>([emptyScene(1)])
+const characters = ref<PromptSequenceCharacter[]>([emptyCharacter()])
+const scenes = ref<PromptSequenceScene[]>([emptyScene(1, characters.value)])
 const activeIndex = ref(0)
 const previewOpen = ref(true)
 const busy = ref('')
 const error = ref('')
 const notice = ref('')
 const copied = ref(false)
+const copiedScene = ref(false)
 let copyTimer: ReturnType<typeof setTimeout> | null = null
+let copySceneTimer: ReturnType<typeof setTimeout> | null = null
 
 const activeScene = computed(() => scenes.value[activeIndex.value] || null)
-const previewText = computed(() => assembleSequenceText({ scenes: scenes.value }))
+const previewText = computed(() => assembleSequenceText({
+  characters: characters.value,
+  scenes: scenes.value
+}))
+const activeSceneText = computed(() => {
+  if (!activeScene.value) return ''
+  return assembleSceneText(activeScene.value, characters.value)
+})
 
 function startNew() {
   selectedId.value = ''
   name.value = ''
-  scenes.value = [emptyScene(1)]
+  characters.value = [emptyCharacter()]
+  scenes.value = [emptyScene(1, characters.value)]
   activeIndex.value = 0
   error.value = ''
   notice.value = ''
 }
 
 function select(sequence: PromptSequence) {
-  selectedId.value = sequence.id
-  name.value = sequence.name
-  scenes.value = (sequence.scenes?.length ? sequence.scenes : [emptyScene(1)]).map((scene, index) => ({
-    ...emptyScene(index + 1),
+  const normalized = normalizePromptSequence(sequence) || sequence
+  selectedId.value = normalized.id
+  name.value = normalized.name
+  characters.value = (normalized.characters?.length ? normalized.characters : [emptyCharacter()]).map(character => ({
+    ...emptyCharacter(),
+    ...character,
+    outfits: (character.outfits || []).map(outfit => ({ ...emptyOutfit(), ...outfit }))
+  }))
+  scenes.value = (normalized.scenes?.length ? normalized.scenes : [emptyScene(1, characters.value)]).map((scene, index) => ({
+    ...emptyScene(index + 1, characters.value),
     ...scene,
-    characters: (scene.characters?.length ? scene.characters : [emptyCharacter()]).map(character => ({
-      ...emptyCharacter(),
-      ...character
+    characterStates: (scene.characterStates || []).map(state => ({
+      characterId: state.characterId,
+      on: state.on !== false,
+      outfitId: state.outfitId || null
     }))
   }))
+  ensureSceneStatesForCharacters(scenes.value, characters.value)
   activeIndex.value = 0
   error.value = ''
   notice.value = ''
 }
 
 function addNextScene() {
-  const previous = scenes.value[scenes.value.length - 1] || emptyScene(1)
+  const previous = scenes.value[scenes.value.length - 1] || emptyScene(1, characters.value)
   const next = cloneSceneForNext(previous, scenes.value.length + 1)
   scenes.value.push(next)
   activeIndex.value = scenes.value.length - 1
 }
 
 function addCharacter() {
-  if (!activeScene.value) return
-  activeScene.value.characters.push(emptyCharacter())
+  const character = emptyCharacter()
+  characters.value.push(character)
+  ensureSceneStatesForCharacters(scenes.value, characters.value, {
+    newCharacterId: character.id,
+    turnOnSceneIndex: activeIndex.value
+  })
 }
 
 function clearCharacter(index: number) {
-  const character = activeScene.value?.characters[index]
+  const character = characters.value[index]
   if (!character) return
   character.name = ''
   character.description = ''
+  character.outfits = []
+  for (const scene of scenes.value) {
+    const state = scene.characterStates.find(item => item.characterId === character.id)
+    if (state) state.outfitId = null
+  }
 }
 
 function removeCharacter(index: number) {
-  if (!activeScene.value || activeScene.value.characters.length <= 1) return
-  activeScene.value.characters.splice(index, 1)
+  if (characters.value.length <= 1) return
+  const [removed] = characters.value.splice(index, 1)
+  if (!removed) return
+  for (const scene of scenes.value) {
+    scene.characterStates = scene.characterStates.filter(state => state.characterId !== removed.id)
+  }
+}
+
+function addOutfit(characterIndex: number) {
+  const character = characters.value[characterIndex]
+  if (!character) return
+  character.outfits.push(emptyOutfit())
+}
+
+function removeOutfit(characterIndex: number, outfitIndex: number) {
+  const character = characters.value[characterIndex]
+  if (!character) return
+  const [removed] = character.outfits.splice(outfitIndex, 1)
+  if (!removed) return
+  for (const scene of scenes.value) {
+    const state = scene.characterStates.find(item => item.characterId === character.id)
+    if (state?.outfitId === removed.id) state.outfitId = null
+  }
+}
+
+function sceneState(characterId: string) {
+  return activeScene.value?.characterStates.find(state => state.characterId === characterId)
+}
+
+function isCharacterOn(characterId: string) {
+  const state = sceneState(characterId)
+  return state ? !!state.on : true
+}
+
+function setCharacterOn(characterId: string, on: boolean) {
+  const state = sceneState(characterId)
+  if (!state) {
+    activeScene.value?.characterStates.push({ characterId, on, outfitId: null })
+    return
+  }
+  state.on = on
+}
+
+function activeOutfitId(characterId: string) {
+  return sceneState(characterId)?.outfitId || ''
+}
+
+function setCharacterOutfit(characterId: string, outfitId: string) {
+  const state = sceneState(characterId)
+  if (!state) {
+    activeScene.value?.characterStates.push({
+      characterId,
+      on: true,
+      outfitId: outfitId || null
+    })
+    return
+  }
+  state.outfitId = outfitId || null
 }
 
 async function loadSequences() {
@@ -326,11 +500,16 @@ async function save() {
   busy.value = 'save'
   error.value = ''
   notice.value = ''
+  const payload = {
+    name: nextName,
+    characters: characters.value,
+    scenes: scenes.value
+  }
   try {
     if (updateExisting && selectedId.value) {
       const saved = await $fetch<{ sequence: PromptSequence; sequences: PromptSequence[] }>(`/api/prompt-sequences/${selectedId.value}`, {
         method: 'PATCH',
-        body: { name: nextName, scenes: scenes.value }
+        body: payload
       })
       sequences.value = saved.sequences
       select(saved.sequence)
@@ -338,7 +517,7 @@ async function save() {
     } else {
       const saved = await $fetch<{ sequence: PromptSequence; sequences: PromptSequence[] }>('/api/prompt-sequences', {
         method: 'POST',
-        body: { name: nextName, scenes: scenes.value, overwrite: Boolean(existingByName) }
+        body: { ...payload, overwrite: Boolean(existingByName) }
       })
       sequences.value = saved.sequences
       select(saved.sequence)
@@ -368,19 +547,32 @@ async function remove(sequence: PromptSequence) {
   }
 }
 
-async function copyPreview() {
-  const text = previewText.value
+async function writeClipboard(text: string, kind: 'all' | 'scene') {
   if (!text) return
   try {
     await navigator.clipboard.writeText(text)
-    copied.value = true
-    if (copyTimer) clearTimeout(copyTimer)
-    copyTimer = setTimeout(() => { copied.value = false }, 1500)
+    if (kind === 'scene') {
+      copiedScene.value = true
+      if (copySceneTimer) clearTimeout(copySceneTimer)
+      copySceneTimer = setTimeout(() => { copiedScene.value = false }, 1500)
+    } else {
+      copied.value = true
+      if (copyTimer) clearTimeout(copyTimer)
+      copyTimer = setTimeout(() => { copied.value = false }, 1500)
+    }
   } catch {
     error.value = 'Could not copy to the clipboard'
   }
 }
 
+async function copyPreview() {
+  await writeClipboard(previewText.value, 'all')
+}
+
+async function copyScene() {
+  await writeClipboard(activeSceneText.value, 'scene')
+}
+
 onMounted(async () => {
   try {
     await loadSequences()
@@ -391,5 +583,6 @@ onMounted(async () => {
 
 onBeforeUnmount(() => {
   if (copyTimer) clearTimeout(copyTimer)
+  if (copySceneTimer) clearTimeout(copySceneTimer)
 })
 </script>
diff --git a/server/api/prompt-sequences.post.ts b/server/api/prompt-sequences.post.ts
index 2de2d7f..f3c226b 100644
--- a/server/api/prompt-sequences.post.ts
+++ b/server/api/prompt-sequences.post.ts
@@ -4,11 +4,13 @@ export default defineEventHandler(async (event) => {
   const { owner } = assertLibraryOwner(event)
   const body = await readBody<{
     name?: string
+    characters?: unknown
     scenes?: unknown
     overwrite?: boolean
   }>(event).catch(() => ({}))
   const sequence = await savePromptSequence(owner, {
     name: body?.name || '',
+    characters: body?.characters,
     scenes: body?.scenes,
     overwrite: body?.overwrite === true
   })
diff --git a/server/api/prompt-sequences/[id].patch.ts b/server/api/prompt-sequences/[id].patch.ts
index 0d0ba9a..9248223 100644
--- a/server/api/prompt-sequences/[id].patch.ts
+++ b/server/api/prompt-sequences/[id].patch.ts
@@ -3,9 +3,10 @@ import { listPromptSequences, updatePromptSequence } from '~/server/utils/prompt
 export default defineEventHandler(async (event) => {
   const { owner } = assertLibraryOwner(event)
   const id = String(getRouterParam(event, 'id') || '')
-  const body = await readBody<{ name?: string; scenes?: unknown }>(event).catch(() => ({}))
+  const body = await readBody<{ name?: string; characters?: unknown; scenes?: unknown }>(event).catch(() => ({}))
   const sequence = await updatePromptSequence(owner, id, {
     name: body?.name,
+    characters: body?.characters,
     scenes: body?.scenes
   })
   return {
diff --git a/server/utils/promptSequences.ts b/server/utils/promptSequences.ts
index c852f75..d651d93 100644
--- a/server/utils/promptSequences.ts
+++ b/server/utils/promptSequences.ts
@@ -4,9 +4,12 @@ import { ownerRoot } from '~/server/utils/library'
 import {
   normalizePromptSequence,
   normalizePromptSequenceName,
+  normalizeCharacter,
   normalizeScene,
+  emptyCharacter,
   emptyScene,
   type PromptSequence,
+  type PromptSequenceCharacter,
   type PromptSequenceScene
 } from '~/utils/promptSequences'
 
@@ -54,9 +57,14 @@ function mutate<T>(owner: string, fn: (sequences: PromptSequence[]) => T): Promi
   return run
 }
 
-function normalizeScenesInput(raw: unknown): PromptSequenceScene[] {
-  if (!Array.isArray(raw) || !raw.length) return [emptyScene(1)]
-  return raw.map((scene, index) => normalizeScene(scene, index))
+function normalizeCharactersInput(raw: unknown): PromptSequenceCharacter[] {
+  if (!Array.isArray(raw) || !raw.length) return [emptyCharacter()]
+  return raw.map(normalizeCharacter)
+}
+
+function normalizeScenesInput(raw: unknown, characters: PromptSequenceCharacter[]): PromptSequenceScene[] {
+  if (!Array.isArray(raw) || !raw.length) return [emptyScene(1, characters)]
+  return raw.map((scene, index) => normalizeScene(scene, index, characters))
 }
 
 export function listPromptSequences(owner: string) {
@@ -72,12 +80,14 @@ export function getPromptSequence(owner: string, id: string) {
 
 export async function savePromptSequence(owner: string, input: {
   name: string
+  characters?: unknown
   scenes?: unknown
   overwrite?: boolean
 }) {
   const name = normalizePromptSequenceName(input.name)
   if (!name) throw createError({ statusCode: 400, statusMessage: 'A sequence name is required' })
-  const scenes = normalizeScenesInput(input.scenes)
+  const characters = normalizeCharactersInput(input.characters)
+  const scenes = normalizeScenesInput(input.scenes, characters)
   const now = Date.now()
   return mutate(owner, (sequences) => {
     const existing = sequences.find(item => item.name.toLowerCase() === name.toLowerCase())
@@ -85,6 +95,7 @@ export async function savePromptSequence(owner: string, input: {
       throw createError({ statusCode: 409, statusMessage: `Overwrite sequence “${existing.name}”?` })
     }
     if (existing) {
+      existing.characters = characters
       existing.scenes = scenes
       existing.updatedAt = now
       return existing
@@ -92,6 +103,7 @@ export async function savePromptSequence(owner: string, input: {
     const created: PromptSequence = {
       id: crypto.randomUUID(),
       name,
+      characters,
       scenes,
       createdAt: now,
       updatedAt: now
@@ -103,6 +115,7 @@ export async function savePromptSequence(owner: string, input: {
 
 export async function updatePromptSequence(owner: string, id: string, input: {
   name?: string
+  characters?: unknown
   scenes?: unknown
 }) {
   const wanted = String(id || '').trim()
@@ -117,8 +130,15 @@ export async function updatePromptSequence(owner: string, id: string, input: {
       if (clash) throw createError({ statusCode: 409, statusMessage: `A sequence named “${clash.name}” already exists` })
       existing.name = name
     }
-    if (input.scenes !== undefined) {
-      existing.scenes = normalizeScenesInput(input.scenes)
+    if (input.characters !== undefined || input.scenes !== undefined) {
+      const characters = input.characters !== undefined
+        ? normalizeCharactersInput(input.characters)
+        : existing.characters
+      const scenes = input.scenes !== undefined
+        ? normalizeScenesInput(input.scenes, characters)
+        : existing.scenes.map((scene, index) => normalizeScene(scene, index, characters))
+      existing.characters = characters
+      existing.scenes = scenes
     }
     existing.updatedAt = Date.now()
     return existing
diff --git a/tests/prompt-sequences.test.mjs b/tests/prompt-sequences.test.mjs
index ee318c5..fb28876 100644
--- a/tests/prompt-sequences.test.mjs
+++ b/tests/prompt-sequences.test.mjs
@@ -20,15 +20,23 @@ const {
   assembleSequenceText,
   formatCharacterLine,
   emptyScene,
-  cloneSceneForNext
+  emptyCharacter,
+  emptyOutfit,
+  cloneSceneForNext,
+  normalizePromptSequence,
+  ensureSceneStatesForCharacters
 } = await import(pathToFileURL(tmp).href)
 unlinkSync(tmp)
 
-test('formatCharacterLine covers name/description cases', () => {
+test('formatCharacterLine covers name/description and outfit', () => {
   assert.equal(formatCharacterLine({ name: 'Ada', description: 'tall' }), 'Ada: tall')
   assert.equal(formatCharacterLine({ name: 'Ada', description: '' }), 'Ada')
   assert.equal(formatCharacterLine({ name: '', description: 'tall' }), 'tall')
   assert.equal(formatCharacterLine({ name: '', description: '' }), '')
+  assert.equal(
+    formatCharacterLine({ name: 'Ada', description: 'tall' }, { name: 'Work', description: 'blue jacket' }),
+    'Ada: tall. Outfit: blue jacket'
+  )
 })
 
 test('assembleSceneText joins non-empty boxes with a single blank line', () => {
@@ -45,6 +53,43 @@ test('assembleSceneText joins non-empty boxes with a single blank line', () => {
   assert.equal(text, 'oil paint\n\nnight\n\nAda: tall\nBo: hat\n\nwalks')
 })
 
+test('off characters and active outfits affect assembly', () => {
+  const ada = { ...emptyCharacter(), id: 'c1', name: 'Ada', description: 'tall', outfits: [
+    { ...emptyOutfit(), id: 'o1', name: 'Day', description: 'red dress' },
+    { ...emptyOutfit(), id: 'o2', name: 'Night', description: 'black coat' }
+  ] }
+  const bo = { ...emptyCharacter(), id: 'c2', name: 'Bo', description: 'hat', outfits: [] }
+  const scene1 = {
+    style: 's1',
+    settings: '',
+    prompt: 'p1',
+    characterStates: [
+      { characterId: 'c1', on: true, outfitId: 'o1' },
+      { characterId: 'c2', on: true, outfitId: null }
+    ]
+  }
+  const scene2 = {
+    style: 's2',
+    settings: '',
+    prompt: 'p2',
+    characterStates: [
+      { characterId: 'c1', on: false, outfitId: 'o1' },
+      { characterId: 'c2', on: true, outfitId: null }
+    ]
+  }
+  assert.equal(
+    assembleSceneText(scene1, [ada, bo]),
+    's1\n\nAda: tall. Outfit: red dress\nBo: hat\n\np1'
+  )
+  assert.equal(
+    assembleSceneText(scene2, [ada, bo]),
+    's2\n\nBo: hat\n\np2'
+  )
+  const full = assembleSequenceText({ characters: [ada, bo], scenes: [scene1, scene2] })
+  assert.equal(full, 's1\n\nAda: tall. Outfit: red dress\nBo: hat\n\np1\n\n\ns2\n\nBo: hat\n\np2')
+  assert.ok(!full.includes('not present'))
+})
+
 test('assembleSequenceText uses double blank line between scenes and skips empties', () => {
   const text = assembleSequenceText({
     name: 'ignored',
@@ -58,58 +103,59 @@ test('assembleSequenceText uses double blank line between scenes and skips empti
   assert.ok(!text.includes('ignored'))
 })
 
-test('example shape is two jobs for desktop Batch', () => {
-  const text = assembleSequenceText({
+test('legacy sequences migrate to sequence characters all on with no outfits', () => {
+  const legacy = normalizePromptSequence({
+    id: 'seq1',
+    name: 'Old',
     scenes: [
       {
-        style: 'style scene 1',
-        settings: 'settings scene 1',
-        characters: [
-          { name: 'Character one', description: 'desc' },
-          { name: 'Character two', description: 'desc' }
-        ],
-        prompt: 'prompt scene 1'
+        id: 'sc1',
+        title: 'Scene 1',
+        style: 'a',
+        settings: '',
+        prompt: 'p',
+        characters: [{ id: 'x', name: 'Ada', description: 'tall' }]
       },
       {
-        style: 'style scene 2',
-        settings: 'settings scene 2',
-        characters: [{ name: 'Character one', description: 'desc' }],
-        prompt: 'prompt scene 2'
+        id: 'sc2',
+        title: 'Scene 2',
+        style: 'b',
+        settings: '',
+        prompt: 'q',
+        characters: [{ id: 'x', name: 'Ada', description: 'tall' }]
       }
-    ]
+    ],
+    createdAt: 1,
+    updatedAt: 1
   })
-  assert.equal(
-    text,
-    [
-      'style scene 1',
-      '',
-      'settings scene 1',
-      '',
-      'Character one: desc',
-      'Character two: desc',
-      '',
-      'prompt scene 1',
-      '',
-      '',
-      'style scene 2',
-      '',
-      'settings scene 2',
-      '',
-      'Character one: desc',
-      '',
-      'prompt scene 2'
-    ].join('\n')
-  )
+  assert.equal(legacy.characters.length, 1)
+  assert.equal(legacy.characters[0].name, 'Ada')
+  assert.deepEqual(legacy.characters[0].outfits, [])
+  assert.equal(legacy.scenes[0].characterStates[0].on, true)
+  assert.equal(legacy.scenes[0].characterStates[0].outfitId, null)
+  assert.equal(legacy.scenes[1].characterStates[0].on, true)
 })
 
-test('cloneSceneForNext copies fields with new ids', () => {
-  const first = emptyScene(1)
+test('cloneSceneForNext copies toggles and outfit choices', () => {
+  const chars = [emptyCharacter()]
+  const first = emptyScene(1, chars)
   first.style = 'a'
-  first.characters[0].name = 'Ada'
+  first.characterStates[0].on = false
+  first.characterStates[0].outfitId = 'o9'
   const next = cloneSceneForNext(first, 2)
   assert.equal(next.title, 'Scene 2')
   assert.equal(next.style, 'a')
-  assert.equal(next.characters[0].name, 'Ada')
+  assert.equal(next.characterStates[0].on, false)
+  assert.equal(next.characterStates[0].outfitId, 'o9')
   assert.notEqual(next.id, first.id)
-  assert.notEqual(next.characters[0].id, first.characters[0].id)
+})
+
+test('ensureSceneStatesForCharacters turns new character on only for current scene', () => {
+  const a = emptyCharacter()
+  const scenes = [emptyScene(1, [a]), emptyScene(2, [a])]
+  const b = emptyCharacter()
+  const list = [a, b]
+  ensureSceneStatesForCharacters(scenes, list, { newCharacterId: b.id, turnOnSceneIndex: 1 })
+  assert.equal(scenes[0].characterStates.find(s => s.characterId === b.id).on, false)
+  assert.equal(scenes[1].characterStates.find(s => s.characterId === b.id).on, true)
 })
diff --git a/utils/promptSequences.ts b/utils/promptSequences.ts
index 502aa6c..409c2d2 100644
--- a/utils/promptSequences.ts
+++ b/utils/promptSequences.ts
@@ -1,7 +1,21 @@
+export type PromptSequenceOutfit = {
+  id: string
+  name: string
+  description: string
+}
+
 export type PromptSequenceCharacter = {
   id: string
   name: string
   description: string
+  outfits: PromptSequenceOutfit[]
+}
+
+export type PromptSequenceCharacterState = {
+  characterId: string
+  on: boolean
+  /** Active outfit id for this scene, or null/'' for none. */
+  outfitId: string | null
 }
 
 export type PromptSequenceScene = {
@@ -9,13 +23,14 @@ export type PromptSequenceScene = {
   title: string
   style: string
   settings: string
-  characters: PromptSequenceCharacter[]
+  characterStates: PromptSequenceCharacterState[]
   prompt: string
 }
 
 export type PromptSequence = {
   id: string
   name: string
+  characters: PromptSequenceCharacter[]
   scenes: PromptSequenceScene[]
   createdAt: number
   updatedAt: number
@@ -32,17 +47,25 @@ export function newId() {
   return `ps-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
 }
 
-export function emptyCharacter(): PromptSequenceCharacter {
+export function emptyOutfit(): PromptSequenceOutfit {
   return { id: newId(), name: '', description: '' }
 }
 
-export function emptyScene(index = 1): PromptSequenceScene {
+export function emptyCharacter(): PromptSequenceCharacter {
+  return { id: newId(), name: '', description: '', outfits: [] }
+}
+
+export function defaultCharacterState(characterId: string, on = true): PromptSequenceCharacterState {
+  return { characterId, on, outfitId: null }
+}
+
+export function emptyScene(index = 1, characters: PromptSequenceCharacter[] = []): PromptSequenceScene {
   return {
     id: newId(),
     title: `Scene ${Math.max(1, index)}`,
     style: '',
     settings: '',
-    characters: [emptyCharacter()],
+    characterStates: characters.map(character => defaultCharacterState(character.id, true)),
     prompt: ''
   }
 }
@@ -53,34 +76,77 @@ export function cloneSceneForNext(previous: PromptSequenceScene, nextIndex: numb
     title: `Scene ${nextIndex}`,
     style: previous.style,
     settings: previous.settings,
-    characters: (previous.characters || []).map(character => ({
-      id: newId(),
-      name: character.name,
-      description: character.description
+    characterStates: (previous.characterStates || []).map(state => ({
+      characterId: state.characterId,
+      on: !!state.on,
+      outfitId: state.outfitId || null
     })),
     prompt: previous.prompt
   }
 }
 
-/** Character line: "Name: description", or name-only, or description-only. */
-export function formatCharacterLine(character: { name?: string; description?: string }) {
-  const name = String(character?.name || '').trim()
-  const description = String(character?.description || '').trim()
-  if (!name && !description) return ''
-  if (name && description) return `${name}: ${description}`
-  return name || description
+function outfitPromptText(outfit?: { name?: string; description?: string } | null) {
+  if (!outfit) return ''
+  return String(outfit.description || '').trim() || String(outfit.name || '').trim()
 }
 
-export function assembleSceneText(scene: {
-  style?: string
-  settings?: string
-  characters?: Array<{ name?: string; description?: string }>
-  prompt?: string
-}) {
-  const characterBlock = (scene.characters || [])
-    .map(formatCharacterLine)
+/**
+ * Character line when on:
+ * - with outfit: "Name: description. Outfit: outfit description"
+ * - without: "Name: description" (or name-only / description-only)
+ */
+export function formatCharacterLine(
+  character: { name?: string; description?: string },
+  outfit?: { name?: string; description?: string } | null
+) {
+  const name = String(character?.name || '').trim()
+  const description = String(character?.description || '').trim()
+  let base = ''
+  if (name && description) base = `${name}: ${description}`
+  else base = name || description
+  if (!base) return ''
+  const outfitText = outfitPromptText(outfit)
+  if (!outfitText) return base
+  return `${base}. Outfit: ${outfitText}`
+}
+
+export function resolveSceneCharacterLines(
+  scene: { characterStates?: PromptSequenceCharacterState[] },
+  characters: PromptSequenceCharacter[] = []
+) {
+  const states = scene.characterStates || []
+  const stateById = new Map(states.map(state => [state.characterId, state]))
+  return characters
+    .map((character) => {
+      const state = stateById.get(character.id)
+      // Missing state (legacy) => on
+      if (state && !state.on) return ''
+      const outfitId = state?.outfitId || null
+      const outfit = outfitId
+        ? (character.outfits || []).find(item => item.id === outfitId) || null
+        : null
+      return formatCharacterLine(character, outfit)
+    })
     .filter(Boolean)
-    .join('\n')
+}
+
+export function assembleSceneText(
+  scene: {
+    style?: string
+    settings?: string
+    prompt?: string
+    characterStates?: PromptSequenceCharacterState[]
+    /** Legacy per-scene characters (migration / old tests). */
+    characters?: Array<{ name?: string; description?: string }>
+  },
+  sequenceCharacters?: PromptSequenceCharacter[]
+) {
+  const characterBlock = sequenceCharacters?.length
+    ? resolveSceneCharacterLines(scene, sequenceCharacters).join('\n')
+    : (scene.characters || [])
+        .map(character => formatCharacterLine(character))
+        .filter(Boolean)
+        .join('\n')
   const parts = [
     String(scene.style || '').trim(),
     String(scene.settings || '').trim(),
@@ -96,15 +162,18 @@ export function assembleSceneText(scene: {
  * Sequence name is never included.
  */
 export function assembleSequenceText(sequence: {
+  characters?: PromptSequenceCharacter[]
   scenes?: Array<{
     style?: string
     settings?: string
-    characters?: Array<{ name?: string; description?: string }>
     prompt?: string
+    characterStates?: PromptSequenceCharacterState[]
+    characters?: Array<{ name?: string; description?: string }>
   }>
 }) {
+  const characters = sequence.characters || []
   return (sequence.scenes || [])
-    .map(assembleSceneText)
+    .map(scene => assembleSceneText(scene, characters.length ? characters : undefined))
     .filter(Boolean)
     .join('\n\n\n')
 }
@@ -122,7 +191,7 @@ export function normalizePromptSequenceTitle(raw: unknown, fallback: string) {
   return title || fallback
 }
 
-export function normalizeCharacter(raw: unknown): PromptSequenceCharacter {
+export function normalizeOutfit(raw: unknown): PromptSequenceOutfit {
   const rec = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
   return {
     id: String(rec.id || '').trim() || newId(),
@@ -131,17 +200,79 @@ export function normalizeCharacter(raw: unknown): PromptSequenceCharacter {
   }
 }
 
-export function normalizeScene(raw: unknown, index: number): PromptSequenceScene {
+export function normalizeCharacter(raw: unknown): PromptSequenceCharacter {
+  const rec = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+  const outfits = Array.isArray(rec.outfits) ? rec.outfits.map(normalizeOutfit) : []
+  return {
+    id: String(rec.id || '').trim() || newId(),
+    name: String(rec.name || '').trim().slice(0, 120),
+    description: normalizePromptSequenceField(rec.description).trim(),
+    outfits
+  }
+}
+
+export function normalizeCharacterState(raw: unknown, fallbackCharacterId = ''): PromptSequenceCharacterState {
+  const rec = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+  const characterId = String(rec.characterId || fallbackCharacterId || '').trim()
+  const outfitRaw = rec.outfitId
+  const outfitId = outfitRaw == null || outfitRaw === '' ? null : String(outfitRaw).trim() || null
+  return {
+    characterId,
+    on: rec.on === undefined ? true : !!rec.on,
+    outfitId
+  }
+}
+
+function liftLegacyCharacters(scenesRaw: unknown[]): PromptSequenceCharacter[] {
+  const byId = new Map<string, PromptSequenceCharacter>()
+  for (const scene of scenesRaw) {
+    if (!scene || typeof scene !== 'object') continue
+    const chars = (scene as Record<string, unknown>).characters
+    if (!Array.isArray(chars)) continue
+    for (const character of chars) {
+      const normalized = normalizeCharacter(character)
+      if (!byId.has(normalized.id)) byId.set(normalized.id, normalized)
+    }
+  }
+  return [...byId.values()]
+}
+
+function syncCharacterStates(
+  statesRaw: unknown,
+  characters: PromptSequenceCharacter[],
+  defaultOn = true
+): PromptSequenceCharacterState[] {
+  const incoming = Array.isArray(statesRaw)
+    ? statesRaw.map(state => normalizeCharacterState(state)).filter(state => state.characterId)
+    : []
+  const byId = new Map(incoming.map(state => [state.characterId, state]))
+  return characters.map((character) => {
+    const existing = byId.get(character.id)
+    if (existing) {
+      const outfitOk = existing.outfitId
+        && character.outfits.some(outfit => outfit.id === existing.outfitId)
+      return {
+        characterId: character.id,
+        on: existing.on,
+        outfitId: outfitOk ? existing.outfitId : null
+      }
+    }
+    return defaultCharacterState(character.id, defaultOn)
+  })
+}
+
+export function normalizeScene(
+  raw: unknown,
+  index: number,
+  characters: PromptSequenceCharacter[] = []
+): PromptSequenceScene {
   const rec = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
-  const characters = Array.isArray(rec.characters)
-    ? rec.characters.map(normalizeCharacter)
-    : [emptyCharacter()]
   return {
     id: String(rec.id || '').trim() || newId(),
     title: normalizePromptSequenceTitle(rec.title, `Scene ${index + 1}`),
     style: normalizePromptSequenceField(rec.style),
     settings: normalizePromptSequenceField(rec.settings),
-    characters: characters.length ? characters : [emptyCharacter()],
+    characterStates: syncCharacterStates(rec.characterStates, characters, true),
     prompt: normalizePromptSequenceField(rec.prompt)
   }
 }
@@ -152,13 +283,42 @@ export function normalizePromptSequence(raw: unknown): PromptSequence | null {
   const name = normalizePromptSequenceName(rec.name)
   if (!name) return null
   const scenesRaw = Array.isArray(rec.scenes) ? rec.scenes : []
-  const scenes = scenesRaw.map((scene, index) => normalizeScene(scene, index))
+  let characters = Array.isArray(rec.characters)
+    ? rec.characters.map(normalizeCharacter)
+    : liftLegacyCharacters(scenesRaw)
+  if (!characters.length) characters = [emptyCharacter()]
+  const scenes = scenesRaw.length
+    ? scenesRaw.map((scene, index) => normalizeScene(scene, index, characters))
+    : [emptyScene(1, characters)]
   const createdAt = Number(rec.createdAt) || Date.now()
   return {
     id: String(rec.id || '').trim() || newId(),
     name,
-    scenes: scenes.length ? scenes : [emptyScene(1)],
+    characters,
+    scenes,
     createdAt,
     updatedAt: Number(rec.updatedAt) || createdAt
   }
 }
+
+/** Ensure every scene has a state row for every sequence character. */
+export function ensureSceneStatesForCharacters(
+  scenes: PromptSequenceScene[],
+  characters: PromptSequenceCharacter[],
+  opts?: { newCharacterId?: string; turnOnSceneIndex?: number }
+) {
+  const newId = opts?.newCharacterId
+  const turnOnIndex = opts?.turnOnSceneIndex
+  for (let i = 0; i < scenes.length; i++) {
+    const scene = scenes[i]
+    const byId = new Map(scene.characterStates.map(state => [state.characterId, state]))
+    scene.characterStates = characters.map((character) => {
+      const existing = byId.get(character.id)
+      if (existing) return existing
+      const on = newId && character.id === newId
+        ? i === turnOnIndex
+        : true
+      return defaultCharacterState(character.id, on)
+    })
+  }
+}