diff --git a/freevideo_engine/agent/cast.py b/freevideo_engine/agent/cast.py
index 6b2a2e21..3e7cfcb6 100644
--- a/freevideo_engine/agent/cast.py
+++ b/freevideo_engine/agent/cast.py
@@ -25,7 +25,7 @@
 ORIGINS = ('user', 'agent', 'builtin')
 LABELS = schema.LABELS
 EDITABLE = ('name', 'description', 'images', 'voice')
-MAX_IMAGES = 6
+MAX_IMAGES = schema.MAX_CAST_IMAGES
 MAX_CANDIDATES = 6
 MAX_RECEIPTS = 64
 VOICE_SECONDS = (2, 15)
@@ -40,7 +40,7 @@
 CLOSE_UP = dict(aspect='1:1', seconds=4)
 SCENE = dict(aspect='16:9', seconds=6)
 
-# The sheet of every view a shot carries for each person, put together here from the card's own pictures: up to six
+# The sheet of every view a continuing shot carries for a single person, put together here from the card's own pictures: up to six
 # equal cells (three to a row) on a light grey ground, each picture scaled whole and centred, no text.
 SHEET_VERSION = 1
 SHEET_ORDER = ('front', 'three_quarter', 'side', 'back', 'face')  # then any other label, in card order
@@ -140,6 +140,12 @@ def _plain(item):
     return None
 
 
+def _caption(row):
+    """A requested picture's caption on one line, as picture fields ({} when it has none)."""
+    text = ' '.join(str(row.get('caption') or '').split())
+    return {'caption': text} if text else {}
+
+
 def _check(record, stem):
     card = record['card']
     if (card['id'] != stem or not CARD.fullmatch(stem) or card['kind'] not in KINDS
@@ -161,7 +167,8 @@ def _check(record, stem):
         if not isinstance(card[key], list) or len(card[key]) > limit:
             raise ValueError('Invalid pictures')
         for row in card[key]:
-            if not isinstance(row['label'], str) or not isinstance(row['media']['file'], str):
+            if (not isinstance(row['label'], str) or not isinstance(row['media']['file'], str)
+                    or not isinstance(row.get('caption', ''), str)):
                 raise ValueError('Invalid picture')
             unknown_labels |= row['label'] not in LABELS
     if card['voice'] is not None:
@@ -383,7 +390,7 @@ def create(self, value, *, by='builtin', ref=None, made_for=None, local=True, cl
         images = []
         for index, row in enumerate(value.get('images', [])):
             entry = self._picture_at(identity, row['media'], by, index)
-            images.append(dict(entry, label=row.get('label', 'other')))
+            images.append(dict(entry, label=row.get('label', 'other'), **_caption(row)))
         voice = self._voice(identity, value['voice']) if value.get('voice') else None
         with self.changed:
             digest, replay = self._receipt('cast:create', value, ref, client)
@@ -461,7 +468,7 @@ def update(self, identity, value, *, by='builtin', ref=None, revision=None, loca
         for key, rows in changes.items():
             if key == 'images':
                 resolved['images'] = [entry if entry is not None else dict(self._picture_at(identity, row['media'], by, index),
-                                      label=row.get('label', 'other')) for index, (row, entry) in enumerate(rows)]
+                                      label=row.get('label', 'other'), **_caption(row)) for index, (row, entry) in enumerate(rows)]
             elif key == 'voice':
                 resolved['voice'] = None if rows is None else self._voice(identity, rows)
             else:
@@ -510,16 +517,19 @@ def _changes(self, card, value, by):
                         entry.pop('label_guess', None)
                         if by == 'user':
                             entry.pop('generated', None)  # The user's label makes it the user's picture.
+                    if 'caption' in row:  # Left out, the caption stays; "" removes it.
+                        entry.pop('caption', None)
+                        entry.update(_caption(row))
                 else:
                     fresh = True
                 rows.append((row, entry))
-            current = [(r['media']['file'], r['label']) for r in card['images']]
-            proposed = [(e['media']['file'], e['label']) for _, e in rows if e is not None]
+            current = [(r['media']['file'], r['label'], r.get('caption')) for r in card['images']]
+            proposed = [(e['media']['file'], e['label'], e.get('caption')) for _, e in rows if e is not None]
             if fresh or proposed != current:
                 changes['images'] = rows
                 if by != 'user' and card['edited_by_user']['images']:
                     # The user's pictures may only be joined by candidates the server made; never replaced.
-                    untouched = all((f, l) in proposed for f, l in current) and len(kept) == len(current)
+                    untouched = all(row in proposed for row in current) and len(kept) == len(current)
                     if fresh or not untouched or not added:
                         raise self._by_user(card, 'images')
         if 'voice' in value:
diff --git a/freevideo_engine/agent/drama.py b/freevideo_engine/agent/drama.py
index ac0b32b9..58a28dca 100644
--- a/freevideo_engine/agent/drama.py
+++ b/freevideo_engine/agent/drama.py
@@ -60,8 +60,8 @@ def __init__(self, problems):
 CAPTIONED = 3  # the score of a take with unwanted captions
 CARD = re.compile(r'c[0-9a-f]{12}')  # characters.<key>.card names a cast library card
 # How a shot carries its cast cards. Change these after the reference tests; nothing else needs to.
-# Each person is two pictures: one sheet of every view (made by the cast library when the card has none), then
-# the face close-up. A continuing shot with several people has no room for two each: it carries one picture a person.
+# A fresh shot carries every picture of each person, the one standing for the person last. A continuing shot has room
+# for three pictures: one person carries the sheet of every view then the face, several people one picture each.
 FACE_ORDER = ('face', 'front', 'three_quarter')  # the one picture standing for a person, then any other label, in card order
 MAX_VOICES = 3      # voice clips per shot, the model limit
 MAX_REFERENCES = 32
@@ -266,7 +266,8 @@ def prompt(play, shot):
 def subject_definitions(subjects):
     """The prompt prefix tying cast cards to their reference tags; the one place its wording lives.
 
-    subjects: [{'name', 'description', 'pictures': (first, last), a list of such pairs, or None, 'audio': number or None}].
+    subjects: [{'name', 'description', 'pictures': (first, last), a list of such pairs, or None, 'captions': [(picture,
+    text)], 'audio': number or None}].
     The page writes the same prompt from the same wording (web/cast_mention.js); tests/fixtures/subject_definitions.json
     holds the cases both sides must reproduce exactly."""
     parts = []
@@ -282,6 +283,10 @@ def subject_definitions(subjects):
                                  for a, b in ranges)
             single = len(ranges) == 1 and ranges[0][0] == ranges[0][1]
             tags.append('%s show%s its appearance' % (pictures, 's' if single else ''))
+            for picture, caption in subject.get('captions') or ():
+                caption = (caption or '').strip().rstrip('.')
+                if caption:
+                    tags.append('<Picture %d> shows %s' % (picture, caption))
         if subject.get('audio'):
             tags.append('<Audio %d> is its voice' % subject['audio'])
         if tags:
@@ -305,12 +310,17 @@ def sheet_of(card):
 
 
 def person_pictures(card, *, alone=True, continues=False):
-    """The pictures one person carries into a shot, in order: the sheet, then the face close-up (the front view
-    when there is no face). Two of them on every device. A card that has no sheet (one picture, or none could be
-    made) carries its face alone (else the front view). A shot that continues the previous one with several
-    people carries only the face (else the front view) of each, with no sheet."""
+    """The pictures one person carries into a shot, in order. A fresh shot carries every picture of the card in card
+    order, the one standing for the person (the face, else the front view) moved last. A shot that continues the
+    previous one carries the sheet then that picture, or that picture alone when the card has no sheet (one picture,
+    or none could be made); with several people it carries only that picture of each (else the sheet)."""
     views = _views(card)
-    if continues and not alone:
+    if not continues:
+        pictures = [row['media'] for row in card.get('images') or []]
+        if not views:
+            return pictures
+        return [media for media in pictures if media is not views[0]] + views[:1]
+    if not alone:
         return views[:1] or ([sheet_of(card)] if sheet_of(card) else [])
     sheet = sheet_of(card)
     if sheet is None:
@@ -318,6 +328,12 @@ def person_pictures(card, *, alone=True, continues=False):
     return [sheet] + [view for view in views[:1] if view.get('file') != sheet.get('file')]
 
 
+def picture_captions(card, pictures):
+    """The card's caption of each of these pictures; None for one without a caption or not on the card (a sheet)."""
+    captions = {row['media'].get('file'): row.get('caption') for row in card.get('images') or []}
+    return [captions.get(item.get('file')) for item in pictures]
+
+
 def cast_references(play, shot, cards, *, continues=False):
     """Which cast cards a shot carries, as references and a prompt prefix.
 
@@ -328,7 +344,8 @@ def cast_references(play, shot, cards, *, continues=False):
     names its own first frame or references; an empty list means no pictures), 'missing' (a card was deleted),
     'partial' (not everyone fit) or 'cards'. 'omitted' lists people left out
     entirely; 'voice_omitted' lists people whose pictures are carried but whose
-    voice did not fit. A shot that continues the previous one carries no voice
+    voice did not fit. A person whose pictures do not all fit in the references
+    left carries the first ones and the one standing for the person. A shot that continues the previous one carries no voice
     clip (its voices carry on from the previous shot) and at most CONTINUED_PICTURES
     pictures: two for a single person, else one for each of up to that many people."""
     characters = play.get('characters', {})
@@ -362,9 +379,12 @@ def cast_references(play, shot, cards, *, continues=False):
                 result['omitted'].append(key)
             continue
         voice = card.get('voice') is not None and voices < MAX_VOICES
-        if pictures + len(images) + voices + voice > MAX_REFERENCES:
+        room = MAX_REFERENCES - pictures - voices - voice
+        if room < min(len(images), 1):
             result['omitted'].append(key)
             continue
+        if len(images) > room:
+            images = images[:room - 1] + images[-1:]
         if card.get('voice') is not None and not voice:
             result['voice_omitted'].append(key)  # shown, without the voice that did not fit
         pictures, voices = pictures + len(images), voices + voice
@@ -381,6 +401,9 @@ def cast_references(play, shot, cards, *, continues=False):
         subject = dict(name=person.get('name') or key, description=card.get('description'),
                        pictures=(picture + 1, picture + len(images)) if images else None,
                        audio=len(clips) if voice else None)
+        captions = [(picture + n, text) for n, text in enumerate(picture_captions(card, images), 1) if text]
+        if captions:
+            subject['captions'] = captions
         picture += len(images)
         if images or voice:
             subjects.append(subject)
@@ -403,15 +426,16 @@ def cast_references(play, shot, cards, *, continues=False):
 def with_cast(text, resolved, *, limit=PROMPT_LIMIT):
     """The submitted prompt: the subject definitions, then the shot's own prompt.
 
-    Cards can grow after a plan; when the whole prompt would pass the limit, the card descriptions are
-    shortened (the pictures still show each person). Plan previews and submissions both call this."""
+    Cards can grow after a plan; when the whole prompt would pass the limit, the card descriptions and picture
+    captions are shortened (the pictures still show each person). Plan previews and submissions both call this."""
     if not resolved.get('prefix'):
         return text
     full = resolved['prefix'] + '\n\n' + text
     if len(full) <= limit or not resolved.get('subjects'):
         return full
     for cut in DESCRIPTION_CUTS:
-        subjects = [dict(s, description=(s.get('description') or '')[:cut].rstrip() or None)
+        subjects = [dict(s, description=(s.get('description') or '')[:cut].rstrip() or None,
+                         captions=[(n, text[:cut].rstrip()) for n, text in s.get('captions') or ()])
                     for s in resolved['subjects']]
         short = subject_definitions(subjects) + '\n\n' + text
         if len(short) <= limit:
diff --git a/freevideo_engine/agent/guide.py b/freevideo_engine/agent/guide.py
index f0095b93..3980a2e7 100644
--- a/freevideo_engine/agent/guide.py
+++ b/freevideo_engine/agent/guide.py
@@ -4,7 +4,7 @@
 own prompt rules; the enhancement job applies the same contract.
 """
 from ..default_prompt import DEFAULT_PROMPT
-from .schema import CAST_OPERATIONS, DRAMA_OPERATIONS, IMAGE_OPERATIONS, PROJECT_OPERATIONS, SESSION_OPERATIONS, WHITEBOX_OPERATIONS
+from .schema import CAST_OPERATIONS, DRAMA_OPERATIONS, IMAGE_OPERATIONS, MAX_CAST_IMAGES, PROJECT_OPERATIONS, SESSION_OPERATIONS, WHITEBOX_OPERATIONS
 
 from .whitebox import SCENE_PROMPT
 
@@ -609,11 +609,15 @@ def connection_text(value):
 GUIDE['cast_routes'] = [dict(operation=name, method=method, path=path, description=summary)
     for name, (method, path, summary) in CAST_OPERATIONS.items()]
 GUIDE['cast'] = [
-    'A card is a character or setting: name, a one-sentence English description used in prompts, up to six '
-    'labelled pictures (front, three_quarter, side, back, face, sheet, other) and an optional 2 to 15 s voice.',
+    'A card is a character or setting: name, a one-sentence English description used in prompts, up to %d '
+    'labelled pictures (front, three_quarter, side, back, face, sheet, other) and an optional 2 to 15 s voice. '
+    'Each picture may have a caption: what it shows that the others do not ("dragon tattoo on her back"), written '
+    'into the prompt beside its picture tag.'
+    % MAX_CAST_IMAGES,
     'Changes need the revision you read (body revision or If-Match); stale_revision returns the current card in '
     'error.card. Fields the user changed return changed_by_user: keep the user\'s version.',
-    'Film with a card by setting characters.<key>.card. Cards are read when each take is submitted. Shots that '
+    'Film with a card by setting characters.<key>.card. Cards are read when each take is submitted. A shot carries '
+    'every picture of its carded people within the 32 references (the face, else the front, last). Shots that '
     'continue the previous one carry the sheet and the face for a single person, else one picture each (the face, '
     'else the front) for at most 3 people, and keep the voices of the previous shot; POST /drama/plan shows each shot\'s cast. '
     'A shot\'s own references replace the card pictures; references=[] sends none. '
diff --git a/freevideo_engine/agent/productions.py b/freevideo_engine/agent/productions.py
index 68345481..dbeace78 100644
--- a/freevideo_engine/agent/productions.py
+++ b/freevideo_engine/agent/productions.py
@@ -978,8 +978,8 @@ def _cast(self, state, take, item):
         return resolved
 
     def _carry(self, play, shot, cards, item, *, continues):
-        """The cast a shot carries: each person's sheet and face close-up on every device (one picture a person when
-        a continuing shot has several people). Plan previews and submissions both come here, so they agree."""
+        """The cast a shot carries: every picture of each person (the sheet and face of one person, or one picture a
+        person, when the shot continues). Plan previews and submissions both come here, so they agree."""
         return drama.cast_references(play, shot, cards, continues=continues)
 
     def _current(self, play):
diff --git a/freevideo_engine/agent/schema.py b/freevideo_engine/agent/schema.py
index 905a4d0e..4328f0fd 100644
--- a/freevideo_engine/agent/schema.py
+++ b/freevideo_engine/agent/schema.py
@@ -592,6 +592,10 @@ def drama_schema(name):
     return obj(dict(ref=REF, **({'transition': enum(('cut', 'crossfade'))} if name == 'finish' else {})))
 
 
+# A card's pictures; each may carry a one-line caption that prompts write beside its <Picture N> tag.
+MAX_CAST_IMAGES = 24
+MAX_CAST_CAPTION = 200
+
 CAST_OPERATIONS = {
     'create': ('POST', '/cast', 'Create a character or setting card when no existing card fits'),
     'list': ('GET', '/cast', 'Search the cast library before casting; reuse a matching card'),
@@ -612,7 +616,10 @@ def cast_schema(name, *, local=False):
     sound['oneOf'][1]['properties']['url'] = picture['oneOf'][1]['properties']['url']
     sound['oneOf'][1]['allOf'] = sound['oneOf'][1]['allOf'][:1]
     fields = dict(name=string(120), description=nullable(string(1000)),
-                  images=array(obj(dict(media=picture, label=enum(LABELS)), ('media',)), 0, 6),
+                  images=array(obj(dict(media=picture, label=enum(LABELS), caption={'type': 'string', 'maxLength': MAX_CAST_CAPTION,
+                      'description': 'Optional: what this picture shows, e.g. "dragon tattoo on her back"; written into prompts. '
+                                     '"" removes it.'}),
+                      ('media',)), 0, MAX_CAST_IMAGES),
                   voice=nullable(obj(dict(media=sound, start=number(0, 3600, default=0), end=number(0, 3600)), ('media',))))
     if name == 'create':
         return obj(dict(kind=enum(('character', 'setting'), default='character'), **fields, ref=REF), ('name',))
@@ -637,7 +644,7 @@ def cast_schema(name, *, local=False):
 def cast_view():
     picture = obj(dict(media=obj(dict(file=FILE, url=string(2048)), ('file', 'url')),
                        by=enum(('user', 'agent', 'builtin')), from_job=JOB, generated={'type': 'boolean'},
-                       label={'type': 'string'}, label_guess={'type': 'boolean'}), ('media', 'by', 'label'))
+                       label={'type': 'string'}, label_guess={'type': 'boolean'}, caption=string(MAX_CAST_CAPTION)), ('media', 'by', 'label'))
     generating = obj(dict(job=JOB, face_job=nullable(JOB), jobs=array(JOB, 1, 5),
         source=enum(('image', 'video')), replace={'type': 'boolean'}, at=string(),
         by=enum(('user', 'agent', 'builtin'))), ('job', 'face_job', 'replace', 'at', 'by'))
@@ -646,7 +653,7 @@ def cast_view():
         ('job', 'face_job', 'seed', 'prompt_version'))
     return dict(obj(dict(id=CAST, kind=enum(('character', 'setting')), name=string(120),
         description=nullable(string(1000)), revision=number(1, integer=True),
-        images=array(picture, 0, 6), candidates=array(picture, 0, 6),
+        images=array(picture, 0, MAX_CAST_IMAGES), candidates=array(picture, 0, 6),
         generating=nullable(generating), generated=nullable(generated),
         generate_error=nullable(obj(dict(code=string(), job=JOB, message=string(), error_zh=string(), error_en=string()), ('code', 'job', 'message')))),
         ('id', 'kind', 'name', 'revision', 'images', 'candidates', 'generating')), additionalProperties=True)
@@ -1058,7 +1065,7 @@ def production_response():
             cast_reference=CAST_REFERENCE, cast_omitted=dict(type='array', items=string()),
             cast_voice_omitted=dict(type='array', items=string()),
             cast_missing=dict(type='array', items=string()),
-            cast_pictures_each=dict(type=['integer', 'null'], description='Most pictures one person carries in this shot: two (the sheet of every view and the face close-up), or one each when a continuing shot has several people.'),
+            cast_pictures_each=dict(type=['integer', 'null'], description='Most pictures one person carries in this shot: every picture of the card (fewer only when the 32 references run out), or in a continuing shot the sheet and the face for one person, else one each.'),
             takes=dict(type='array', items=dict(type='object', properties=dict(take=number(1, integer=True), job=REF,
                 task={'oneOf': [JOB, {'type': 'null'}]}, generation=number(0, integer=True), seed=number(0, integer=True),
                 stale={'type': 'boolean'}, error={'type': ['object', 'null']},
diff --git a/scripts/test_freevideo_entry.mjs b/scripts/test_freevideo_entry.mjs
index 891d3781..6144b1de 100644
--- a/scripts/test_freevideo_entry.mjs
+++ b/scripts/test_freevideo_entry.mjs
@@ -9,9 +9,32 @@ import {uploadMedia} from '../web/media_upload.js';
 import {outputDownloadURL} from '../web/output_download.js';
 import {regenerateResult, upscaleResult, createSecondPassQueue, enableNode} from '../web/studio_queue.js';
 import {referenceInputs, mediaRows} from '../web/prompt_references.js';
-import {expandCast} from '../web/cast_mention.js';
+import {expandCast, restoreCast, staleCast, withCharacter, withCurrentCard} from '../web/cast_mention.js';
 import {cleanAudioUse, cleanOptionalPrompt, cleanOptionalWidgets, optionalInputValue} from '../web/optional_inputs.js';
 
+test('character captions and scene references survive card updates and prompt rewrites', () => {
+    const character = {id: 'one', name: 'Alex', revision: 1, description: 'A scar', images: [
+        {label: 'front', media: {file: 'front.png'}, caption: 'face'},
+        {label: 'other', media: {file: 'back.png'}, caption: 'tattoo'},
+    ]};
+    const second = {id: 'two', name: 'Alex', revision: 1, images: [{label: 'front', media: {file: 'second.png'}}]};
+    const scene = {id: 'place', kind: 'setting', name: 'Harbor', revision: 1, description: 'Rainy', images: [
+        {label: 'other', media: {file: 'harbor.png'}},
+    ]};
+    let rows = withCharacter(withCharacter(withCharacter([], character), second), scene);
+    assert.equal(rows.at(-1).cast.setting, true);
+    const expanded = expandCast('@Alex and @Alex (2) at @Harbor', rows);
+    assert.match(expanded.text, /<Picture 1> shows tattoo/);
+    assert.match(expanded.text, /setting: Harbor: Rainy\. <Picture 4> shows the place\./);
+    assert.equal(restoreCast('subject_definitions: rewritten\n\n<Subject 1> and <Subject 2>', expanded.subjects), '@Alex and @Alex (2)');
+    assert.deepEqual(staleCast(rows, [{id: 'place', revision: 2}]), ['place']);
+    rows = withCurrentCard(rows, {...scene, revision: 2, description: 'Sunny'});
+    assert.equal(rows.at(-1).cast.setting, true);
+    assert.match(expandCast('@Harbor', rows).text, /setting: Harbor: Sunny/);
+    const continued = expandCast('@Alex at @Harbor', rows, {continued: true});
+    assert.match(continued.text, /setting: Harbor: Sunny\. <Picture 3> shows the place\./);
+});
+
 class Element {
     constructor(tag) {
         this.tag = tag; this.children = []; this.dataset = {}; this.attributes = {};
@@ -48,7 +71,7 @@ test('main browser entry registers both views and preserves node hooks', async t
     let restoreReleases = 0;
     let launchReady = null;
     const opening = {setName: name => openingEvents.push(['name', name]), cover: () => openingEvents.push(['cover']), finish: () => openingEvents.push(['finish'])};
-    const casts = [];
+    const casts = [], castCards = {};
     let progressView, progressOptions, realProgressFactory, studioView, doneNotifyOptions;
     const app = {
         registerExtension(extension) { extensions.push(extension); },
@@ -59,9 +82,10 @@ test('main browser entry registers both views and preserves node hooks', async t
         createElementNS: (namespaceURI, tag) => Object.assign(new Element(tag), {namespaceURI}),
         createRange: () => ({createContextualFragment: () => new Element('span')})};
     const dependencies = {
-        app, api, uploadMedia, outputDownloadURL, regenerateResult, upscaleResult, createSecondPassQueue, enableNode, referenceInputs, mediaRows, expandCast, cleanAudioUse, cleanOptionalPrompt, cleanOptionalWidgets, optionalInputValue,
+        app, api, uploadMedia, outputDownloadURL, regenerateResult, upscaleResult, createSecondPassQueue, enableNode, referenceInputs, mediaRows, expandCast, staleCast, withCurrentCard, cleanAudioUse, cleanOptionalPrompt, cleanOptionalWidgets, optionalInputValue,
         createCastLibrary: options => {
-            const cast = {element: new Element('cast'), options, destroyed: false, destroy() { this.destroyed = true; }};
+            const cast = {element: new Element('cast'), options, destroyed: false, destroy() { this.destroyed = true; },
+                get: async id => structuredClone(castCards[id])};
             casts.push(cast); return cast;
         },
         secondPassAction: () => new Element('button'),
@@ -129,7 +153,7 @@ test('main browser entry registers both views and preserves node hooks', async t
             .replace("import { startUpdateChecks } from './updates.js';", 'const {startUpdateChecks} = globalThis.__freevideoEntryTest;')
             .replace("import { startDoneNotify, askDesktopPermission, DESKTOP_SETTING } from './done_notify.js';", 'const {startDoneNotify} = globalThis.__freevideoEntryTest; const askDesktopPermission = (...args) => globalThis.__permissionAsks.push(args); const DESKTOP_SETTING = "FreeVideo.DoneNotify.Desktop";')
             .replace("import { attachReferencePicker, referenceItems, syncReferencePrompt, referenceInputs, mediaRows, mediaNodeOf } from './prompt_references.js';", 'const {attachReferencePicker,referenceItems,syncReferencePrompt,referenceInputs,mediaRows} = globalThis.__freevideoEntryTest; const mediaNodeOf = () => null;')
-            .replace("import { expandCast } from './cast_mention.js';", 'const {expandCast} = globalThis.__freevideoEntryTest;')
+            .replace("import { expandCast, staleCast, withCurrentCard } from './cast_mention.js';", 'const {expandCast,staleCast,withCurrentCard} = globalThis.__freevideoEntryTest;')
             .replace("import { outputDownloadURL } from './output_download.js';", 'const {outputDownloadURL} = globalThis.__freevideoEntryTest;')
             .replace("import { shareButton } from './share.js';", 'const {shareButton} = globalThis.__freevideoEntryTest;')
             .replace("import { reportFileName } from './report_issue.js';", 'const {reportFileName} = globalThis.__freevideoEntryTest;')
@@ -527,6 +551,25 @@ test('main browser entry registers both views and preserves node hooks', async t
         assert.equal(casts[0].options.api, api);
         assert.equal(typeof casts[0].options.uploadOne, 'function');
         assert.equal(typeof casts[0].options.viewURL, 'function');
+        // A mentioned character's rows follow its edited card: every picture with its caption and the new description,
+        // in place of the old rows; a picture switched off stays off, and an unchanged card rewrites nothing.
+        const was = {id: 'c1', name: 'Mara', description: 'Old'};
+        media.widgets[0].value = JSON.stringify([{file: 'street.png', role: 'reference', enabled: true},
+            {file: 'sheet.png', role: 'reference', enabled: true, cast: was}, {file: 'face.png', role: 'reference', enabled: false, cast: was}]);
+        castCards.c1 = {id: 'c1', name: 'Mara', description: 'A dragon tattoo on her back', revision: 4, images: [
+            {label: 'front', media: {file: 'front.png'}}, {label: 'face', media: {file: 'face.png'}},
+            {label: 'other', media: {file: 'tattoo.png'}, caption: 'the dragon tattoo on her back'}]};
+        const listed = [{id: 'c1', name: 'Mara', description: 'A dragon tattoo on her back', revision: 4}, {id: 'c2', name: 'Ann', revision: 1}];
+        casts[0].options.onChange(listed); await new Promise(resolve => setTimeout(resolve, 0));
+        const now = {id: 'c1', name: 'Mara', description: 'A dragon tattoo on her back', revision: 4};
+        assert.deepEqual(JSON.parse(media.widgets[0].value), [{file: 'street.png', role: 'reference', enabled: true},
+            {file: 'front.png', role: 'reference', enabled: true, cast: now},
+            {file: 'tattoo.png', role: 'reference', enabled: true, cast: {...now, caption: 'the dragon tattoo on her back'}},
+            {file: 'face.png', role: 'reference', enabled: false, cast: now}]);
+        const followed = media.widgets[0].value;
+        casts[0].options.onChange(listed); await new Promise(resolve => setTimeout(resolve, 0));
+        assert.equal(media.widgets[0].value, followed);
+        media.widgets[0].value = '[]';
         assert.match(mode.textContent, /Reference/);
         assert.equal(audioHelp.hidden, false);
         assert.match(audioHelp.textContent, /<Audio 1>/);
diff --git a/web/cast_generate.js b/web/cast_generate.js
index ecb0fd4b..19e6609e 100644
--- a/web/cast_generate.js
+++ b/web/cast_generate.js
@@ -226,7 +226,7 @@ export function mountCastGenerate({container, api, text, t = text, viewURL, onSt
         const summary = JSON.stringify([running, complete, Math.round(progress * 100)]);
         if (summary !== last) {
             last = summary;
-            onState({busy: running, progress, done: complete});
+            onState({busy: running, progress, done: complete, description: state.description});
         }
     }
 
diff --git a/web/cast_library.css b/web/cast_library.css
index 83f1eec6..3da2ba86 100644
--- a/web/cast_library.css
+++ b/web/cast_library.css
@@ -20,13 +20,18 @@
 .fv-cast-dialog .fv-cast-close{min-height:28px;width:28px;padding:0;border:0;background:transparent;color:var(--fv-muted);font-size:22px}
 .fv-cast-name{display:block;width:100%;height:36px;margin:0 0 14px;padding:6px 10px;border:1px solid var(--fv-border);border-radius:var(--fv-r-sm,8px);background:var(--fv-raised);color:var(--fv-ink);font:inherit}
 .fv-cast-name::placeholder{color:var(--fv-disabled)}
+.fv-cast-description{display:block;width:100%;min-height:56px;margin:0 0 14px;padding:6px 10px;border:1px solid var(--fv-border);border-radius:var(--fv-r-sm,8px);background:var(--fv-raised);color:var(--fv-ink);font:inherit;resize:vertical}
+.fv-cast-description::placeholder{color:var(--fv-disabled)}
 .fv-cast-tabs{display:flex;gap:3px;margin-bottom:16px;padding:3px;border:1px solid var(--fv-border);border-radius:var(--fv-r-sm,8px);background:var(--fv-bg)}
 .fv-cast-tabs button{flex:1;border:0;background:transparent;color:var(--fv-muted)}
 .fv-cast-tabs button[aria-selected=true]{background:var(--fv-raised);color:var(--fv-ink)}
 .fv-cast-upload{display:grid;grid-template-columns:minmax(0,2fr) minmax(0,3fr);gap:16px}
-.fv-cast-views{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));grid-template-rows:repeat(2,minmax(0,1fr));gap:8px}
-.fv-cast-slot{position:relative;min-width:0;min-height:0;aspect-ratio:3/4}
-.fv-cast-front{aspect-ratio:3/4}
+.fv-cast-views{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));align-content:start;gap:8px}
+.fv-cast-slot{display:flex;flex-direction:column;gap:4px;min-width:0;min-height:0}
+.fv-cast-frame{position:relative;min-height:0;aspect-ratio:3/4}
+.fv-cast-front{align-self:start}
+.fv-cast-caption{display:block;width:100%;height:26px;padding:3px 7px;border:1px solid var(--fv-border);border-radius:var(--fv-r-sm,8px);background:var(--fv-raised);color:var(--fv-ink);font:inherit;font-size:12px}
+.fv-cast-caption::placeholder{color:var(--fv-disabled)}
 .fv-cast-dialog .fv-cast-choose{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px;width:100%;height:100%;min-height:0;padding:0;border:1px dashed var(--fv-sheen);border-radius:var(--fv-r-sm,8px);background:var(--fv-raised);color:var(--fv-muted);overflow:hidden}
 .fv-cast-choose:has(img){border-style:solid}
 .fv-cast-slot-plus{font-size:24px;line-height:1}
@@ -52,5 +57,5 @@
 .fv-cast-library[data-kind=scene] .fv-cast-avatar img{object-position:50% 50%;object-view-box:none}
 .fv-cast-dialog[data-kind=scene] .fv-cast-upload{display:block}
 .fv-cast-dialog[data-kind=scene] .fv-cast-views{grid-template-columns:repeat(3,minmax(0,1fr));grid-template-rows:none}
-.fv-cast-dialog[data-kind=scene] .fv-cast-slot{aspect-ratio:16/9}
+.fv-cast-dialog[data-kind=scene] .fv-cast-frame{aspect-ratio:16/9}
 .fv-cast-dialog[data-kind=scene] .fv-cast-choose img{object-fit:cover}
diff --git a/web/cast_library.js b/web/cast_library.js
index 0f21f51e..fa45370a 100644
--- a/web/cast_library.js
+++ b/web/cast_library.js
@@ -22,10 +22,12 @@ const button = (className, label, action) => {
     const node = el('button', className, label); node.type = 'button'; node.onclick = action; return node;
 };
 const path = id => '/freevideo/agent/cast/' + encodeURIComponent(id);
+// MAX_CAST_IMAGES and MAX_CAST_CAPTION in agent/schema.py.
+const MAX_PICTURES = 24, MAX_CAPTION = 200;
 
 // kind 'setting' is the scene row: wide pictures, up to 3 per card, and no front picture.
 export function createCastLibrary({api, text, viewURL, uploadOne, onChange = () => {}, kind = 'character'}) {
-    const scene = kind === 'setting', SLOTS = scene ? 3 : 6;
+    const scene = kind === 'setting', SLOTS = scene ? 3 : MAX_PICTURES;
     const word = (character, place) => scene ? place : character;
     if (!document.querySelector('link[data-freevideo-cast]')) {
         const css = el('link'); css.rel = 'stylesheet'; css.dataset.freevideoCast = '';
@@ -103,9 +105,9 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
         if (disposed || !available) return;
         current?.close();
         let closed = false, loading = !!id, saving = false, revision, active = 'upload';
-        let generator = null, aiState = {busy: false, done: false}, deleteTimer = null, confirming = false, frontless = scene, beyond = [];
-        const slots = Array(SLOTS).fill(null), slotUI = [];
-        const dialog = el('dialog', 'fv-cast-dialog'); dialog.dataset.kind = scene ? 'scene' : 'character';
+    let generator = null, aiState = {busy: false, done: false}, deleteTimer = null, confirming = false, frontless = scene, beyond = [], mirrored = '', savedDescription = null;
+        const slots = [null], slotUI = [];
+    const dialog = el('dialog', 'fv-cast-dialog'); dialog.dataset.kind = scene ? 'scene' : 'character';
         const top = el('div', 'fv-cast-top');
         const title = el('h2', '', id ? word(text('Edit character', '编辑角色'), text('Edit scene', '编辑场景')) : word(text('New character', '新建角色'), text('New scene', '新建场景')));
         dialog.setAttribute('aria-label', title.textContent);
@@ -115,6 +117,10 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
         name.placeholder = word(text('Name', '名字'), text('Name', '名称')); name.setAttribute('aria-label', name.placeholder);
         name.oninput = () => sync();
         name.onkeydown = event => { if (event.key === 'Enter') event.preventDefault(); };
+        const description = el('textarea', 'fv-cast-description'); description.rows = 2; description.maxLength = 1000;
+        description.placeholder = text('Description (optional): details the pictures may not show, e.g. a dragon tattoo on the back, a scar over the left eyebrow',
+            '描述（可选）：图片里可能看不到的细节，例如背上的龙纹身、左眉上的疤');
+        description.setAttribute('aria-label', text('Description', '描述'));
         const tabs = el('div', 'fv-cast-tabs'); tabs.setAttribute('role', 'tablist');
         tabs.setAttribute('aria-label', text('Images', '图片'));
         const uploadTab = button('', text('Upload images', '上传图片'), () => select('upload'));
@@ -130,7 +136,7 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
         const save = button('fv-cast-save', text('Save', '保存'), () => saveCard());
         actions.append(remove, cancel, save);
         const issue = issueButton(text, () => ({where: CAST_ISSUE, message: status.textContent})); issue.hidden = true;
-        dialog.append(top, name, tabs, uploadPane, aiPane, status, issue, actions); tabs.append(uploadTab, aiTab);
+        dialog.append(top, name, description, tabs, uploadPane, aiPane, status, issue, actions); tabs.append(uploadTab, aiTab);
 
         // A refresh notice is plain secondary text; only failures are shown as errors.
         const message = (content, notice = false) => {
@@ -147,7 +153,7 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
             : aiState.done ? '' : word(text('Generate the images first', '先生成角色图片'), text('Generate the images first', '先生成场景图片'));
         function sync() {
             const busy = loading || saving;
-            name.disabled = busy; remove.disabled = busy;
+            name.disabled = description.disabled = busy; remove.disabled = busy;
             uploadTab.disabled = aiTab.disabled = busy;
             const before = missing;
             missing = busy ? '' : missingNow();
@@ -156,14 +162,14 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
             else { save.removeAttribute('aria-disabled'); save.removeAttribute('title'); }
             if (before && before !== missing && status.textContent === before) message('');
             for (let index = 0; index < slotUI.length; index++) {
-                slotUI[index].choose.disabled = busy; slotUI[index].remove.disabled = busy;
+                slotUI[index].choose.disabled = busy; slotUI[index].remove.disabled = busy; slotUI[index].caption.disabled = busy;
             }
         }
         // A refused picture is named on its own tile; choosing another picture there, or saving again, clears it.
         // A tile too narrow for the words keeps only its red border, and the words go on the line under the pictures.
         let markedBelow = -1;
         function mark(index, content = '') {
-            const {slot, problem} = slotUI[index];
+            const {slot, frame, problem} = slotUI[index];
             // Clear the line only while it still holds this tile's words, not a later message.
             if (markedBelow === index) { markedBelow = -1; if (status.textContent === problem.dataset.message) message(''); }
             problem.dataset.message = content;
@@ -171,8 +177,8 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
             problem.replaceChildren(...content.replace(/([，。]|\. )/g, '$1\n').split('\n').filter(Boolean).map(part => el('span', 'fv-cast-slot-line', part)));
             if (content) problem.append(issueButton(text, () => ({where: CAST_ISSUE, message: content})));
             problem.hidden = !content; slot.classList.toggle('fv-cast-bad', !!content);
-            const width = slot.clientWidth;
-            if (content && width > 0 && (width < 100 || problem.scrollWidth > problem.clientWidth || problem.offsetHeight > slot.clientHeight / 2)) {
+            const width = frame.clientWidth;
+            if (content && width > 0 && (width < 100 || problem.scrollWidth > problem.clientWidth || problem.offsetHeight > frame.clientHeight / 2)) {
                 problem.hidden = true; markedBelow = index; message(content);
             }
         }
@@ -190,13 +196,14 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
             select(event.key === 'Home' ? 'upload' : event.key === 'End' ? 'ai' : active === 'upload' ? 'ai' : 'upload');
             (active === 'upload' ? uploadTab : aiTab).focus();
         };
-        function release(index) {
-            if (slots[index]?.preview) URL.revokeObjectURL(slots[index].preview);
-            slots[index] = null;
-        }
+        const revoke = picture => { if (picture?.preview) URL.revokeObjectURL(picture.preview); };
         function paint(index) {
-            const {choose, remove} = slotUI[index], picture = slots[index];
+            const {choose, remove, caption} = slotUI[index], picture = slots[index];
+            caption.hidden = !picture; caption.value = picture?.caption || '';
+            caption.setAttribute('aria-label', text(`What image ${index + 1} shows`, `图片 ${index + 1} 的内容`));
             choose.replaceChildren(); let image = null;
+            choose.setAttribute('aria-label', !index && !frontless ? text('Front image', '正面图片')
+                : picture ? text(`Image ${index + 1}`, `图片 ${index + 1}`) : text('Add images', '添加图片'));
             if (picture) {
                 image = el('img'); image.alt = '';
                 // The remove button waits for the picture, so a slot still loading never looks like a filled one.
@@ -206,34 +213,60 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
                 choose.append(image);
             } else {
                 choose.append(el('span', 'fv-cast-slot-plus', '+'));
-                if (!index && !scene) choose.append(el('span', '', text('Front image', '正面图片')));
+                choose.append(el('span', '', index || frontless ? text('Add images', '添加图片') : text('Front image', '正面图片')));
             }
             remove.hidden = true; if (image?.complete) remove.hidden = false; mark(index); sync();
         }
+        // A tile for each picture and one empty tile after them, until the card is full.
+        function layout() {
+            const wanted = Math.min(slots.length + 1, SLOTS);
+            while (slotUI.length > wanted) slotUI.pop().slot.remove();
+            while (slotUI.length < wanted) addSlot();
+        }
+        // The first file goes on the tile it was given to; the others go after the last picture.
         function chooseFiles(index, files) {
             if (loading || saving || closed) return;
-            for (const file of Array.from(files).slice(0, SLOTS - index)) {
-                release(index);
-                slots[index] = {file, label: index || scene ? 'other' : 'front', preview: URL.createObjectURL(file)};
-                paint(index++);
+            const changed = [];
+            for (const file of Array.from(files)) {
+                if (index >= SLOTS) break;
+                revoke(slots[index]);
+                slots[index] = {file, label: index || frontless ? 'other' : 'front', preview: URL.createObjectURL(file)};
+                changed.push(index); index = slots.length;
             }
-            message('');
+            layout(); changed.forEach(at => paint(at)); message('');
         }
-        for (let index = 0; index < SLOTS; index++) {
-            const slot = el('div', 'fv-cast-slot' + (index || scene ? '' : ' fv-cast-front'));
-            const input = el('input'); input.type = 'file'; input.accept = 'image/*'; input.hidden = true;
-            const label = scene ? text(`Image ${index + 1}`, `图片 ${index + 1}`) : index ? text(`View ${index}`, `视角 ${index}`) : text('Front image', '正面图片');
-            const choose = button('fv-cast-choose', '', () => input.click()); choose.setAttribute('aria-label', label);
-            const remove = button('fv-cast-remove', '×', () => { release(index); paint(index); });
+        function drop(index) {
+            revoke(slots[index]);
+            if (!index && !frontless) { slots[0] = null; paint(0); return; }
+            // A refused picture keeps its mark when the pictures after the removed one move up.
+            const marks = slotUI.map(({problem}) => problem.dataset.message || '');
+            if (markedBelow >= index) mark(markedBelow);
+            slots.splice(index, 1); layout();
+            if (!slots.length) slots.push(null);
+            for (let at = index; at < slotUI.length; at++) { paint(at); if (marks[at + 1]) mark(at, marks[at + 1]); }
+        }
+        function addSlot() {
+            const index = slotUI.length;
+            const slot = el('div', 'fv-cast-slot' + (index || scene ? '' : ' fv-cast-front')), frame = el('div', 'fv-cast-frame');
+            const input = el('input'); input.type = 'file'; input.accept = 'image/*'; input.multiple = true; input.hidden = true;
+            const choose = button('fv-cast-choose', '', () => input.click());
+            const remove = button('fv-cast-remove', '×', () => drop(index));
             remove.setAttribute('aria-label', text('Remove image', '移除图片'));
+            const caption = el('input', 'fv-cast-caption'); caption.type = 'text'; caption.maxLength = MAX_CAPTION;
+            caption.placeholder = text('What it shows', '图中内容');
+            caption.title = text('Goes into the prompt with this image, e.g. "dragon tattoo on her back"', '会和这张图一起写进提示词，例如“背上的龙纹身”');
+            caption.oninput = () => { if (slots[index]) slots[index].caption = caption.value; };
+            caption.onkeydown = event => { if (event.key === 'Enter') event.preventDefault(); };
             input.onchange = () => { chooseFiles(index, input.files); input.value = ''; };
             slot.ondragover = event => { event.preventDefault(); event.stopPropagation(); };
             slot.ondrop = event => { event.preventDefault(); event.stopPropagation(); chooseFiles(index, event.dataTransfer.files); };
             const problem = el('div', 'fv-cast-slot-error'); problem.setAttribute('role', 'alert'); problem.hidden = true;
             // The remove button comes after the text so it stays above it on a narrow tile.
-            slot.append(choose, problem, remove, input); slotUI.push({slot, choose, remove, problem});
+            frame.append(choose, problem, remove); slot.append(frame, caption, input);
+            slotUI.push({slot, frame, choose, remove, problem, caption});
             (index || scene ? views : uploadPane).append(slot); paint(index);
         }
+        layout();
         uploadPane.append(views);
         function resetDelete() {
             clearTimeout(deleteTimer); deleteTimer = null; confirming = false;
@@ -244,15 +277,16 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
             try {
                 const card = await get(id);
                 if (closed) return;
-                revision = card.revision; name.value = card.name;
-                for (let i = 0; i < SLOTS; i++) release(i);
+                revision = card.revision; name.value = card.name; mirrored = '';
+                savedDescription = card.description ?? null; description.value = savedDescription || '';
+                slots.forEach(revoke);
                 // A card may have no front picture (the API does not require one): all its pictures stay, in order, and
                 // saving does not ask for a front; the front slot is only reserved while there is a front to keep first.
                 frontless = scene || card.images.length > 0 && card.images[0].label !== 'front';
-                card.images.slice(0, SLOTS).forEach((picture, index) => { slots[index] = {...picture}; });
-                // The API allows six pictures on a scene card but the dialog shows three: the rest stay as they are.
-                beyond = card.images.slice(SLOTS).map(picture => ({media: picture.media, label: picture.label}));
-                slotUI.forEach((_, index) => paint(index));
+                slots.splice(0, slots.length, ...card.images.slice(0, SLOTS).map(picture => ({...picture})));
+                beyond = scene ? card.images.slice(SLOTS).map(picture => ({media: picture.media, label: picture.label, caption: picture.caption || ''})) : [];
+                if (!slots.length) slots.push(null);
+                layout(); slotUI.forEach((_, index) => paint(index));
                 generator?.cancel(); aiState = {busy: false, done: false}; select('upload'); resetDelete();
             } finally { loading = false; if (!closed) sync(); }
         }
@@ -277,7 +311,7 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
                 }));
                 const frontNeeded = !scene && (active === 'ai' || !frontless);
                 if (!pictures.length || pictures.length > SLOTS || (frontNeeded && !pictures.some(picture => picture.label === 'front'))) {
-                    message(word(text('Choose one front image and up to 5 more angles', '选一张正面图片，再加最多 5 张其他角度的图片'),
+                    message(word(text(`Choose one front image and up to ${MAX_PICTURES - 1} more images`, `选一张正面图片，再加最多 ${MAX_PICTURES - 1} 张其他图片`),
                         text('Choose up to 3 images', '最多选 3 张图片')), true); return;
                 }
                 const images = [];
@@ -285,11 +319,14 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
                     if (closed) return;
                     // Cache uploads on the slot so retrying a refused save does not upload twice.
                     if (picture.file && !picture.media) picture.media = (await uploadOne(picture.file)).file;
-                    images.push({media: picture.media, label: picture.label});
+                    images.push({media: picture.media, label: picture.label, caption: String(picture.caption || '').replace(/\s+/g, ' ').trim()});
                 }
                 if (id && scene) images.push(...beyond);
                 if (closed) return;
-                const body = {name: name.value.trim(), images};
+                // An untouched description goes back exactly as the card has it; a typed one goes on one line.
+                const about = description.value === (savedDescription || '') ? savedDescription
+                    : description.value.replace(/\s+/g, ' ').trim() || null;
+                const body = {name: name.value.trim(), description: about, images};
                 await value(await (id ? agentSend(api, 'PATCH', path(id), {revision, ...body})
                     : agentPost(api, '/freevideo/agent/cast', {kind, ...body})));
                 close(); await saved();
@@ -317,7 +354,7 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
             if (closed) return;
             closed = true; clearTimeout(deleteTimer);
             generator?.cancel(); generator?.destroy();
-            for (let index = 0; index < SLOTS; index++) release(index);
+            slots.forEach(revoke);
             if (dialog.open) dialog.close(); dialog.remove();
             if (current?.element === dialog) current = null;
             add.focus();
@@ -330,10 +367,14 @@ export function createCastLibrary({api, text, viewURL, uploadOne, onChange = ()
         name.value = ''; select('upload'); document.body.append(dialog); dialog.showModal(); name.focus();
         if (id) load().catch(error => message(error.message));
         // A scene has one set of pictures: the chosen option takes the first place, where the Upload tab shows it.
-        const pick = file => { if (closed || !scene) return; slots[0] = {media: file, label: 'other'}; paint(0); };
+        const pick = file => { if (closed || !scene) return; revoke(slots[0]); slots[0] = {media: file, label: 'other'}; paint(0); };
         mountGenerator({container: aiPane, api, text, viewURL, kind, onPick: pick, onState: state => {
             if (closed) return;
-            aiState = state; sync();
+            aiState = state;
+            // The words that made the AI pictures describe the character too, unless the box says something else.
+            const words = state.description || '', typed = description.value.trim();
+            if (words && (!typed || typed === mirrored)) description.value = mirrored = words;
+            sync();
         }}).then(instance => {
             if (closed) { instance?.cancel(); instance?.destroy(); return; }
             generator = instance; aiTab.hidden = tabs.hidden = !instance; sync();
diff --git a/web/cast_mention.js b/web/cast_mention.js
index 382f3f61..110d8eae 100644
--- a/web/cast_mention.js
+++ b/web/cast_mention.js
@@ -1,16 +1,15 @@
 // @-mentions of library characters in the prompt box.
 // While editing, the text keeps the character's name ("@Su Wan"); the character's pictures are ordinary reference rows
-// of the media list that carry `cast: {id, name, description}`. When a request is made the names become <Subject N>
-// and the subject definitions go in front, the same wording the Agent's drama planner writes (agent/drama.py).
+// of the media list that carry `cast: {id, name, description, revision, caption?}`. When a request is made the names become
+// <Subject N> and the subject definitions go in front, the same wording the Agent's drama planner writes (agent/drama.py).
 export const MAX_PEOPLE = 3;
-export const MAX_PICTURES_EACH = 2;
 export const MAX_REFERENCES = 32;
-// Which of a card's pictures stands for the person after the sheet; the others follow in the card's own order.
+// Which of a card's pictures stands for the person; it goes after the others, which keep the card's own order.
 export const PICTURE_ORDER = ['face', 'front', 'three_quarter'];
 
-// subjects: [{name, description, pictures: [first, last] | null, audio: number | null}]. This is the one JS place for
-// the wording; its Python twin is subject_definitions() and tests/fixtures/subject_definitions.json holds the cases
-// both sides must reproduce character for character.
+// subjects: [{name, description, pictures: [first, last] | null, captions?: [[picture, text]], audio: number | null}]. This
+// is the one JS place for the wording; its Python twin is subject_definitions() and tests/fixtures/subject_definitions.json
+// holds the cases both sides must reproduce character for character.
 export function subjectDefinitions(subjects) {
     const parts = subjects.map((subject, index) => {
         let text = `<Subject ${index + 1}> is ${subject.name}`;
@@ -23,6 +22,10 @@ export function subjectDefinitions(subjects) {
             const pictures = ranges.map(([a, b]) => a === b ? `<Picture ${a}>` : `<Picture ${a}> to <Picture ${b}>`).join(', ');
             const single = ranges.length === 1 && ranges[0][0] === ranges[0][1];
             tags.push(`${pictures} show${single ? 's' : ''} its appearance`);
+            for (const [picture, caption] of subject.captions || []) {
+                const words = String(caption || '').trim().replace(/\.+$/, '');
+                if (words) tags.push(`<Picture ${picture}> shows ${words}`);
+            }
         }
         if (subject.audio) tags.push(`<Audio ${subject.audio}> is its voice`);
         if (tags.length) text += ' ' + tags.join('; ') + '.';
@@ -141,7 +144,9 @@ export function expandCast(text, rows, {active = true, continued = false} = {})
             const last = ranges[ranges.length - 1];
             if (last && number === last[1] + 1) last[1] = number; else ranges.push([number, number]);
         }
-        return {name: person.name, handle: person.handle ?? person.name, description: person.description, pictures: ranges, audio: null};
+        const captions = person.rows.filter(index => numbers.has(index) && list[index].cast.caption)
+            .map(index => [numbers.get(index), list[index].cast.caption]).sort((a, b) => a[0] - b[0]);
+    return {name: person.name, handle: person.handle ?? person.name, description: person.description, pictures: ranges, ...(captions.length ? {captions} : {}), audio: null};
     });
     const definitions = [...(subjects.length ? [subjectDefinitions(subjects)] : []), ...places].join(' ');
     return {text: definitions + '\n\n' + result, subjects};
@@ -160,24 +165,20 @@ export function restoreCast(text, subjects) {
     return (body || text).replace(/<Subject (\d+)>/g, (_, number) => '@' + handles[number - 1]);
 }
 
-// The pictures of a card to put in the media list, as the Agent carries them (agent/drama.py person_pictures): the sheet of
-// every view (the card's own, else the one the library made), then the face close-up, else the front view. A card with no
-// sheet (one picture, or none could be made) carries its face alone.
+// Every picture of a card for the media list, as a fresh Agent shot carries them (agent/drama.py person_pictures): card
+// order, with the one standing for the person moved last so a continued part keeps it. [{file, caption?}]
 export function cardPictures(card) {
     const rank = new Map(PICTURE_ORDER.map((label, index) => [label, index]));
     const usable = (card?.images || []).map((image, index) => ({image, index}))
         .filter(({image}) => image?.media?.file && IMAGE.test(image.media.file));
-    const views = usable.filter(({image}) => image.label !== 'sheet')
-        .sort((a, b) => (rank.get(a.image.label) ?? PICTURE_ORDER.length) - (rank.get(b.image.label) ?? PICTURE_ORDER.length) || a.index - b.index)
-        .map(({image}) => image.media.file);
-    const sheet = usable.find(({image}) => image.label === 'sheet')?.image.media.file
-        || (IMAGE.test(card?.sheet?.file || '') ? card.sheet.file : null);
-    if (!sheet) return views.slice(0, 1);
-    return [sheet, ...views.slice(0, 1).filter(file => file !== sheet)];
+    const best = usable.filter(({image}) => image.label !== 'sheet')
+        .sort((a, b) => (rank.get(a.image.label) ?? PICTURE_ORDER.length) - (rank.get(b.image.label) ?? PICTURE_ORDER.length) || a.index - b.index)[0];
+    return [...usable.filter(entry => entry !== best), ...(best ? [best] : [])]
+        .map(({image}) => ({file: image.media.file, ...(image.caption ? {caption: image.caption} : {})}));
 }
 
 // Whether a character can be mentioned now; `reason` is the one thing in the way.
-// `count` is how many pictures the card would add when only its list row is known.
+// `count` is how many pictures the card would add when only its list row is known; one row of room is enough (characterRows).
 export function mentionState(rows, card, count = cardPictures(card).length, {continued = false} = {}) {
     const list = Array.isArray(rows) ? rows : [];
     const people = castInRows(list);
@@ -187,7 +188,7 @@ export function mentionState(rows, card, count = cardPictures(card).length, {con
         return {ok: false, reason: card.kind === 'setting' ? 'place' : 'people'};
     }
     if (continued && pictureNumbers(list).size >= CONTINUE_PICTURES) return {ok: false, reason: 'continued'};
-    if (list.filter(enabled).length + count > MAX_REFERENCES) return {ok: false, reason: 'full'};
+    if (list.length + Math.min(count, 1) > MAX_REFERENCES) return {ok: false, reason: 'full'};
     return {ok: true, present: false};
 }
 
@@ -208,7 +209,34 @@ export function mentionHandle(rows, card, pending = new Map()) {
 export function withCharacter(rows, card, typed = '') {
     const list = Array.isArray(rows) ? rows.map(row => ({...row})) : [];
     if (castInRows(list).some(person => person.id === card.id)) return list;
-    const handle = typed || mentionHandle(list, card);
-    const cast = {id: card.id, name: card.name, description: card.description || '', ...(card.kind === 'setting' ? {setting: true} : {}), ...(handle === card.name ? {} : {handle})};
-    return [...list, ...cardPictures(card).map(file => ({file, role: 'reference', enabled: true, cast}))];
+    return [...list, ...characterRows(card, typed || mentionHandle(list, card), MAX_REFERENCES - list.length)];
+}
+
+// A card's picture rows; with less room than pictures, the first ones and the one standing for the person.
+function characterRows(card, handle, room) {
+    const pictures = cardPictures(card);
+    const kept = pictures.length <= room ? pictures : room > 0 ? [...pictures.slice(0, room - 1), pictures.at(-1)] : [];
+    const cast = {id: card.id, name: card.name, description: card.description || '', revision: card.revision,
+        ...(card.kind === 'setting' ? {setting: true} : {}), ...(handle === card.name ? {} : {handle})};
+    return kept.map(({file, caption}) => ({file, role: 'reference', enabled: true, cast: caption ? {...cast, caption} : cast}));
+}
+
+// Characters in the list whose card (a library list row) has changed since they were mentioned.
+export function staleCast(rows, cards) {
+    const revisions = new Map((Array.isArray(cards) ? cards : []).map(card => [card.id, card.revision]));
+    return [...new Set((Array.isArray(rows) ? rows : []).filter(row => row?.cast?.id && revisions.has(row.cast.id)
+        && row.cast.revision !== revisions.get(row.cast.id)).map(row => row.cast.id))];
+}
+
+// The list with this character's rows made again from its card as it is now, where its first row was. The text keeps
+// naming it as before and pictures switched off stay off; the same array when nothing changed.
+export function withCurrentCard(rows, card) {
+    const list = Array.isArray(rows) ? rows : [], at = list.findIndex(row => row?.cast?.id === card.id);
+    if (at < 0) return rows;
+    const old = list.filter(row => row?.cast?.id === card.id), others = list.filter(row => row?.cast?.id !== card.id);
+    const off = new Set(old.filter(row => row.enabled === false).map(row => row.file));
+    const fresh = characterRows(card, old[0].cast.handle || old[0].cast.name || card.name, MAX_REFERENCES - others.length)
+        .map(row => off.has(row.file) ? {...row, enabled: false} : row);
+    if (JSON.stringify(fresh) === JSON.stringify(old)) return rows;
+    return [...others.slice(0, at), ...fresh, ...others.slice(at)];
 }
diff --git a/web/freevideo.js b/web/freevideo.js
index dd2e1db0..12b0a2ce 100644
--- a/web/freevideo.js
+++ b/web/freevideo.js
@@ -17,7 +17,7 @@ import { isLaunchVisit } from './launch_visit.js';
 import { openFreeVideoWorkflow } from './launcher.js';
 import { agentInterfaceState } from './agent_connect.js';
 import { attachReferencePicker, referenceItems, syncReferencePrompt, referenceInputs, mediaRows, mediaNodeOf } from './prompt_references.js';
-import { expandCast } from './cast_mention.js';
+import { expandCast, staleCast, withCurrentCard } from './cast_mention.js';
 import { requestText } from './prompt_sections.js';
 import { outputDownloadURL } from './output_download.js';
 import { shareButton } from './share.js';
@@ -160,8 +160,23 @@ function mediaPanel(node, mount = null) {
     }
     role.value = 'reference';
     toolbar.append(add, generateImage, addAudio, role, picker, audioPicker); panel.append(toolbar, mode, note, audioHelp, connections, cards);
-    const cast = createCastLibrary({api, text, viewURL, uploadOne});
-    const places = createCastLibrary({api, text, viewURL, uploadOne, kind: 'setting'});
+    // Mentioned characters follow their cards: pictures, captions and description as they are now, one card at a time.
+    let following = Promise.resolve();
+    const cast = createCastLibrary({api, text, viewURL, uploadOne, onChange: cards => {
+        following = following.then(() => followCards(cards, cast)).catch(() => {});
+    }});
+    const places = createCastLibrary({api, text, viewURL, uploadOne, kind: 'setting', onChange: cards => {
+        following = following.then(() => followCards(cards, places)).catch(() => {});
+    }});
+    async function followCards(cards, library) {
+        let rows; try { rows = read(); } catch { return; }
+        for (const id of staleCast(rows, cards)) {
+            const card = await library.get(id);
+            try { rows = read(); } catch { return; }
+            const current = withCurrentCard(rows, card);
+            if (current !== rows) update(current);
+        }
+    }
     panel.prepend(cast.element, places.element);
     const read = () => {
         const rows = JSON.parse(serialized.value || "[]");
diff --git a/web/studio.css b/web/studio.css
index 648fd686..5b7d4928 100644
--- a/web/studio.css
+++ b/web/studio.css
@@ -27,6 +27,13 @@
 .fv-studio textarea{display:block;resize:vertical;min-height:148px;height:170px;max-height:340px;border-radius:var(--fv-r-md);line-height:1.65}
 .fv-studio textarea::placeholder{color:var(--fv-disabled)}.fv-studio input:disabled,.fv-studio textarea:disabled{opacity:.5}
 .fv-prompt-guide{box-sizing:border-box;margin:8px 0 0;color:var(--fv-muted);font:12px/1.7 var(--fv-font);white-space:normal;overflow-wrap:anywhere}
+.fv-studio .fv-full-prompt-open{min-height:27px;height:27px;margin-right:6px;padding:0 9px;border:0;background:transparent;color:var(--fv-muted);font-size:12px}
+.fv-studio .fv-full-prompt{width:min(760px,calc(100vw - 48px));max-width:none;max-height:calc(100dvh - 48px);margin:auto;padding:20px;border:1px solid var(--fv-border);border-radius:var(--fv-r-lg);background:var(--fv-bg);color:var(--fv-ink);box-shadow:0 24px 80px #0008}
+.fv-studio .fv-full-prompt::backdrop{background:#070a0d99}
+.fv-studio .fv-full-prompt h2{margin:0 0 12px;font-size:var(--fv-strong);font-weight:var(--fv-semibold)}
+.fv-studio .fv-full-prompt textarea{height:min(60dvh,520px);max-height:none;resize:vertical;font:12px/1.6 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;white-space:pre-wrap}
+.fv-studio .fv-full-prompt-foot{display:flex;align-items:center;gap:8px;margin-top:12px}
+.fv-studio .fv-full-prompt-note{margin-right:auto;color:var(--fv-muted);font-size:12px}
 .fv-prompt-guide a,.fv-studio .fv-prompt-guide a{display:inline;min-height:0;padding:0;border:0;border-radius:0;background:transparent;color:var(--fv-accent);text-decoration:underline;text-underline-offset:3px}
 .fv-prompt-guide a:hover,.fv-studio .fv-prompt-guide a:hover{background:transparent;color:var(--fv-ink)}
 .fv-prompt-guide a:focus-visible{outline:2px solid var(--fv-accent);outline-offset:3px}
diff --git a/web/studio.js b/web/studio.js
index fbf9283a..8a252f2b 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -24,14 +24,14 @@ import { createStudioQueue, randomSeed, turnNodeOn } from './studio_queue.js';
 import { isNetworkTypeError, connectionLostText, wrappedFetchOnly } from './browser_extension.js';
 import { attachReferencePicker, referenceItems, enhancementMedia, syncReferencePrompt, referenceInputs, mentionAt, handleNames, mediaRows } from './prompt_references.js';
 import { attachTermSuggest } from './prompt_terms.js';
-import { castInRows, expandCast, mentionHandle, mentionState, mentionedIds, restoreCast, withCharacter, MAX_PICTURES_EACH } from './cast_mention.js';
+import { castInRows, expandCast, mentionHandle, mentionState, mentionedIds, restoreCast, withCharacter } from './cast_mention.js';
 import { attachMentionOverlay } from './cast_overlay.js';
 import { openCastLibrary } from './cast_source.js';
 import { uploadMedia } from './media_upload.js';
 import { reconcileLoraTriggers } from './lora_triggers.js';
 import { createVerdicts, describeVerdict, feedbackDraft } from './lora_check.js';
 import { continuationUpscale, createSamplingEffort, effortFor, effortsFrom, passSwitch, stepCacheOf, upscaleOf } from './sampling_effort.js';
-import { resultActions, previewBadge, icon, actionsUnavailable } from './result_actions.js';
+import { resultActions, previewBadge, icon, actionsUnavailable, copyText } from './result_actions.js';
 import { framesOf } from './result_reuse.js';
 import { createPromptEnhancer } from './prompt_enhance.js';
 import { requestText, shownRewrite } from './prompt_sections.js';
@@ -752,7 +752,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
         const rows = mediaRows(node);
         const places = (sceneLibrary?.list() || []).map(card => ({...card, kind: 'setting'}));
         return [...castLibrary.list(), ...places].filter(card => card.name).map(card => {
-            const state = mentionState(rows, card, Math.min(MAX_PICTURES_EACH, Number(card.images) || 0), {continued: Boolean(extension.source)});
+            const state = mentionState(rows, card, Number(card.images) || 0, {continued: Boolean(extension.source)});
             return {id: card.id, name: card.name, handle: mentionHandle(rows, card, castPending), thumb: card.thumbnail?.file ? view(card.thumbnail.file) : card.thumbnail?.url || '',
                 ...(card.kind === 'setting' ? {setting: true} : {}), blocked: state.ok ? '' : castBlocked(state.reason) || true};
         });
@@ -805,7 +805,23 @@ export function openStudio(node, {extendFrom = null} = {}) {
         draftNote.textContent = save ? t('Prompt not saved · retry', '描述没能保存 · 重试') : t('Last prompt not loaded · retry', '上次的描述没能读取 · 重试');
     };
     showDraftTrouble(promptDraftTrouble()); cleanup.push(watchPromptDraftTrouble(showDraftTrouble));
-    const promptTools = el('div', null, 'fv-prompt-tools'); promptTools.append(draftNote, mention); promptEditor.append(promptTools);
+    // The node's own serializer (freevideo.js) makes the request text, so this shows exactly what H3 is sent.
+    const fullPrompt = button(t('Full prompt', '完整提示词'), () => {
+        const text = widget(node, 'text')?.serializeValue?.() ?? expandCast(prompt.value, mediaRows(node), {continued: Boolean(extension.source)}).text;
+        const box = el('dialog', null, 'fv-full-prompt'), area = el('textarea');
+        box.setAttribute('aria-label', t('Prompt sent to H3', '发送给 H3 的提示词'));
+        area.readOnly = true; area.spellcheck = false; area.value = text;
+        const note = el('span', t(`${text.length} characters`, `${text.length} 个字符`), 'fv-full-prompt-note');
+        if (extension.source) note.textContent += t(' · continuing with the first frame adds a note about it', ' · 接续并参考首帧时会再加一句首帧说明');
+        const copy = button(t('Copy', '复制'), async () => { copy.textContent = await copyText(text) ? t('Copied', '已复制') : t('Select and copy', '请手动复制'); });
+        const foot = el('div', null, 'fv-full-prompt-foot'); foot.append(note, copy, button(t('Close', '关闭'), () => box.close()));
+        box.append(el('h2', t('Prompt sent to H3', '发送给 H3 的提示词')), area, foot);
+        box.onclose = () => box.remove();
+        dialog.append(box); box.showModal(); area.focus(); area.setSelectionRange(0, 0);
+    }, 'fv-full-prompt-open');
+    fullPrompt.title = t('See the exact prompt the model receives', '查看模型收到的完整提示词');
+    fullPrompt.disabled = prompt.disabled;
+    const promptTools = el('div', null, 'fv-prompt-tools'); promptTools.append(draftNote, fullPrompt, mention); promptEditor.append(promptTools);
     cleanup.push(() => references.dispose());
     const terms = attachTermSuggest(prompt, {t, host: dialog, suppressed: () => !!mentionAt(prompt.value, prompt.selectionStart, prompt.selectionEnd, handleNames(castChoices()))});
     cleanup.push(() => terms.dispose());
@@ -851,7 +867,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
         enhancer.sync(readable === null ? '' : text);
     };
     showPrompt();
-    const promptChanged = e => { if (String(e.detail) === String(node.id)) { prompt.disabled = linked(node, 'text'); showPrompt(); mention.disabled = prompt.disabled; placeholder(); castOverlay.refresh(); references.refresh(); announceCast(); } };
+    const promptChanged = e => { if (String(e.detail) === String(node.id)) { prompt.disabled = linked(node, 'text'); showPrompt(); mention.disabled = fullPrompt.disabled = prompt.disabled; placeholder(); castOverlay.refresh(); references.refresh(); announceCast(); } };
     window.addEventListener('freevideo-reference-prompt', promptChanged);
     cleanup.push(() => window.removeEventListener('freevideo-reference-prompt', promptChanged));
     const promptSection = section(t('Describe your scene', '描述画面'));