@aicopycoders/exodus 2026.11.700-beta.1 → 2026.11.1000-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: exodus-video
3
- description: Make a video ad with Exodus from the terminal. The main path is script-first: run a saved video workflow with `npx @aicopycoders/exodus workflow run`. You read and approve the storyboard, pull every finished piece (per-scene clips, the narration track and per-scene voice, keyframes, cast identity stills, word timings, the music bed) into a folder with `exodus video pull`, and upload a finished cut for approval. Exodus makes the pieces; the cut is made outside it, in whatever editor the user wants — this skill hands over the pieces and the facts about them, it does not prescribe an editor. Use it whenever the user has invoked Exodus and wants anything to do with a video ad, an ad run's clips or storyboard, "pull the pieces", "stitch it together", "make the cut", "upload my cut", or checking on a video run ("exodus, make a video ad from this script", "exodus, is my video run done", "exodus, pull the clips for run X and cut them", "exodus, what's wrong with scene 3", "exodus video status"). Also use it when the user ran an `npx @aicopycoders/exodus video` command or the `exodus` hub skill routed here. Admins get every video command; beta testers with video switched on get start, status, storyboard, approve, voices, retry-frame, pull and upload on their own brands (see "Beta testers"). "video isn't enabled for this key" means the run id is wrong, the command is admin-only, or video isn't switched on for that dashboard user, so check the id and then say so; do not retry. Never claim generic video-editing asks ("edit this mp4", "add captions to my reel") without Exodus context; in shared folders those belong to the user's other tools. Running or authoring workflows generally is `exodus-workflow`; static image ads are `exodus-image`; copy is `exodus-write`.
3
+ description: Make a video ad with Exodus from the terminal. One sentence ("swipe this ad as a microdrama for my brand", "make this a UGC video") is walked through the template door stop by stop, with a yes asked before each paid step. The main path is script-first: run a saved video workflow with `npx @aicopycoders/exodus workflow run`. You read and approve the storyboard, pull every finished piece (per-scene clips, the narration track and per-scene voice, keyframes, cast identity stills, word timings, the music bed) into a folder with `exodus video pull`, and upload a finished cut for approval. Exodus makes the pieces; the cut is made outside it, in whatever editor the user wants — this skill hands over the pieces and the facts about them, it does not prescribe an editor. Use it whenever the user has invoked Exodus and wants anything to do with a video ad, an ad run's clips or storyboard, "pull the pieces", "stitch it together", "make the cut", "upload my cut", or checking on a video run ("exodus, make a video ad from this script", "exodus, is my video run done", "exodus, pull the clips for run X and cut them", "exodus, what's wrong with scene 3", "exodus video status"). Also use it when the user ran an `npx @aicopycoders/exodus video` command or the `exodus` hub skill routed here. Admins get every video command; beta testers with video switched on get start, status, storyboard, approve, voices, retry-frame, pull and upload on their own brands (see "Beta testers"). "video isn't enabled for this key" means the run id is wrong, the command is admin-only, or video isn't switched on for that dashboard user, so check the id and then say so; do not retry. Never claim generic video-editing asks ("edit this mp4", "add captions to my reel") without Exodus context; in shared folders those belong to the user's other tools. Running or authoring workflows generally is `exodus-workflow`; static image ads are `exodus-image`; copy is `exodus-write`.
4
4
  ---
5
5
 
6
6
  # Video: make the pieces, cut the ad, hand it back
@@ -69,11 +69,231 @@ not on the menu by name; Custom is the way to them. A narrator-only script fits
69
69
  Custom alone. If the refusal lists different keys from this table, the server
70
70
  is right and this table is stale.
71
71
 
72
+ The template door is a second menu, `exodus video start --input-options`. The
73
+ Golden Six formats start there. "From one sentence to a film" walks it.
74
+
72
75
  The Rig box on that workflow is where the run's Conceit and Style come from.
73
76
  Conceit is the family plus Wrapper, Narrator Person, and Delivery. Style is the
74
77
  look. Narrated Story is the voice-over family and Acted Story is the dialogue
75
78
  family (`familyTree.ts`). Those family names stay the code's names.
76
79
 
80
+ ## From one sentence to a film
81
+
82
+ The member types one sentence, such as "swipe this ad as a microdrama for my
83
+ brand". You drive the run through its stops and wait for the member at each
84
+ one. The Golden Six formats start on the template door, which needs
85
+ Templates switched on for the member's account. Without it the CLI answers
86
+ "video isn't enabled for this key" or "Templates aren't available on your
87
+ account. Ask an admin if you need it." Tell the member that and stop. A beta
88
+ tester's key refuses the template flags and `retry-clip` with a sentence
89
+ naming what it refused ("Beta testers"): tell the member and stop. Do not retry.
90
+
91
+ Two rules hold at every stop:
92
+
93
+ - **The run page link.** The start prints `Watch it: <link>`. Keep it and give
94
+ it to the member at every stop: the faces, rooms, pictures, voice samples
95
+ and clips open there. `status` leaves it out at the storyboard stop.
96
+ - **A yes before every paid step.** Tell the member what the step buys
97
+ and its price, then wait for their yes. The price is the one the CLI
98
+ printed: `maximumUsd` and `estimatedUsd` under `preparationQuote` from
99
+ `--quote-preparation`, or the total from `video quote`. Where the CLI prints
100
+ no price, say that it prints none. A quote covers only its phase, never the
101
+ whole video: say so. A saved quote that has expired or no
102
+ longer matches is refused with nothing spent: quote again and ask again.
103
+ Reads cost nothing and need no yes.
104
+
105
+ **The Golden Six.** `exodus video start --input-options` lists the templates
106
+ this account may start, the Golden Six first, one line each:
107
+ `<key> — <label> — <description> — <n> structures`. Use the key it prints.
108
+ `--style` takes the template's own look, from this table.
109
+
110
+ | The member asks for | `--conceit` | `--style` |
111
+ |---|---|---|
112
+ | UGC, a creator talking to camera | `ugc-template` | `raw-iphone-ugc-template` |
113
+ | an authority yapper, an expert explaining | `authority-yapper-template` | `realistic-template` |
114
+ | a microdrama, a short acted scene | `microdrama-template` | `realistic-template` |
115
+ | a skeleton timeline | `skeleton-timeline-template` | `pixar-3d-template` |
116
+ | a song ad, a Suno song, a jingle | `pixar-song-template` | `pixar-3d-template` |
117
+ | personification, the product or a body part talking | `personification-template` | none of its own: ask the member to pick one of the looks the server offers |
118
+
119
+ A `--style` the server does not offer is refused with the list of looks it
120
+ does offer, and nothing is spent.
121
+
122
+ ### Start
123
+
124
+ 1. Find three things in the sentence, and ask one question for whatever is
125
+ missing:
126
+ - the source ad: pasted text or a file, as it is, or the words of an ad in
127
+ Exodus or behind a link (the `swipe` skill's section 1 gets them). Save
128
+ the words to `source.txt`.
129
+ - the format: the table above.
130
+ - the brand: `exodus brand current`.
131
+ 2. `exodus video start --input-options --conceit <key>` prints the template's
132
+ story structures, its reference ads, the saved references and the account
133
+ voices. It writes, quotes and starts nothing. Name the structures to the
134
+ member, one line each. A structure they pick goes on the stop 1 lines as
135
+ `--structure <key>`.
136
+ 3. A template run always stops at the storyboard. The CLI refuses `--one-shot`
137
+ on a template start before anything is sent ("Template preparation requires
138
+ storyboard review; do not combine it with --one-shot. Nothing has
139
+ started."), and the server never approves a template's storyboard by
140
+ itself. A member who asks for no stops still gets each paid step named, with
141
+ its price or the fact that the CLI prints none, and a yes asked before it
142
+ runs.
143
+
144
+ ### Stop 1: the script and the cast
145
+
146
+ 1. Quote the script:
147
+
148
+ ```
149
+ exodus video start --script source.txt --conceit <key> --style <look> \
150
+ --adapt "<what may change, in the member's words>" --stop-at-script \
151
+ --quote-preparation --json > script-quote.json
152
+ ```
153
+
154
+ Add `--product <brandProductId>` only when the member gives a saved
155
+ product's id; the CLI lists no products. Give the member the price.
156
+ 2. On their yes, run the same line with `--authorize-preparation
157
+ script-quote.json` in place of `--quote-preparation`, into `stop1.json`. It
158
+ writes the script and starts no run.
159
+ 3. Write the script out byte for byte:
160
+ `node -e 'process.stdout.write(require("./stop1.json").script)' > script.txt`.
161
+ Show the member the source and `script.txt` side by side, and the cast:
162
+ each name that speaks a line. Ask: go on, change a line, or stop.
163
+ - Go on: "The run starts" below.
164
+ - Change a line: copy `script.txt` to `edited.txt` and make their change.
165
+ An edited script is checked and approved again, at a price of its own.
166
+ The first line quotes; the second waits for their yes:
167
+
168
+ ```
169
+ exodus video start --resume-script stop1.json --script edited.txt \
170
+ --conceit <key> --style <look> --stop-at-script --quote-preparation --json > edit-quote.json
171
+ exodus video start --resume-script stop1.json --script edited.txt \
172
+ --conceit <key> --style <look> --stop-at-script --authorize-preparation edit-quote.json --json > stop1b.json
173
+ ```
174
+
175
+ From here `stop1b.json` is the stop file. Write its script over
176
+ `script.txt` the same way and show it again.
177
+ - Stop: nothing more is spent.
178
+
179
+ ### The run starts
180
+
181
+ `<stop file>` is the latest one: `stop1.json`, or `stop1b.json` after an edit.
182
+ Use it with `script.txt` written out from it, unchanged. A different script,
183
+ product, voice or reference is refused, and nothing starts.
184
+
185
+ ```
186
+ exodus video start --resume-script <stop file> --script script.txt \
187
+ --conceit <key> --style <look> --quote-preparation --json > board-quote.json
188
+ ```
189
+
190
+ That quotes the storyboard. On the member's yes:
191
+
192
+ ```
193
+ exodus video start --resume-script <stop file> --script script.txt \
194
+ --conceit <key> --style <look> --authorize-preparation board-quote.json --wait
195
+ ```
196
+
197
+ It prints the run id and `Watch it: <link>`, then waits until the run needs
198
+ the member.
199
+
200
+ ### Stop 2: the picks (arrives with the next server update)
201
+
202
+ Today a run goes from the script straight to the storyboard. Run this stop
203
+ only when `status` says the run is waiting for picks.
204
+
205
+ 1. `exodus video picks <runId>` lists, for each person, four faces and the
206
+ voices; four rooms for the set; the camera styles, when the run offers them.
207
+ Each face, room and voice sample has its own link. Show it all with the run
208
+ page link.
209
+ 2. Ask for one face and one voice per person, one room, and a style when
210
+ one is offered. Send the answers as:
211
+
212
+ ```
213
+ exodus video pick <runId> --face <who>=<n> --voice <who>=<n|voice name|voice id> \
214
+ --room <place>=<n> [--style <key>] [--note "<text>"]
215
+ ```
216
+
217
+ `<who>` is the name the script uses. `--face` and `--voice` repeat once
218
+ per person. `--style` (the camera style) is for the
219
+ microdrama. The run goes on only when every slot has a pick. A pick that leaves a slot open prints the open
220
+ slots: ask for those.
221
+ 3. "Show me other faces": `exodus video picks <runId> --redo face:<who> --note
222
+ "<what to change>"`, or `room:<place>` for rooms. It draws four new paid
223
+ pictures. The CLI prints no price for them: say so, never guess one, and run
224
+ it only after their yes. The second redo of a slot needs the note, and a
225
+ third is refused: ask them to pick from what is shown.
226
+
227
+ When `picks` answers that the server does not support it yet, the run has no
228
+ picks stop: go to stop 3. When it answers `Unknown subcommand: "picks"`, this
229
+ CLI is older than the server: run `npx @aicopycoders/exodus@latest update`,
230
+ then `picks` again.
231
+
232
+ ### Stop 3: the storyboard
233
+
234
+ `status` says "Parked: the storyboard is waiting for your yes."
235
+ `exodus video storyboard <runId>` prints each scene's line and picture, and who
236
+ speaks with which voice ("Reading the storyboard gate" has the detail). Show it
237
+ with the run page link, then ask: approve, redo a picture, change a voice, or
238
+ stop.
239
+
240
+ - Approve: `exodus video approve <runId>`. It buys the voices and the clips
241
+ (with the pilot stop, the pilot first), the expensive part. The CLI prints
242
+ no price for them at this stop: say so, and approve on their yes. A storyboard the app's check stopped is
243
+ refused with the reason. Tell the member, and on their yes approve again
244
+ with `--accept-findings`.
245
+ - Redo a picture: `exodus video retry-frame <runId> --node <nodeId> --scene <n>
246
+ --note "<what is wrong>"`, with the node id from the `Redo one frame:` line
247
+ `status` printed. It redraws one picture. The CLI prints no price for it:
248
+ say so and wait for their yes.
249
+ - Change a voice: `exodus video voices <runId> --set <who>=<voice>` ("Giving
250
+ the characters voices").
251
+ - Stop: `exodus workflow cancel <runId>`.
252
+
253
+ **The song format** waits twice more. `exodus video song <runId>` prints the
254
+ Song master, its listen link and its sha256 once one is ready. The member
255
+ listens; on their yes,
256
+ `exodus video song approve <runId> --master <masterSha256>`. Before its clips
257
+ the run parks with "Parked: final provider requests are prepared".
258
+ `exodus video quote <runId>` prints each request's price and the total; on
259
+ their yes, `exodus video approve <runId> --request-quote <reviewSha256>`.
260
+
261
+ ### Stop 4: the pilot clip (arrives with the next server update)
262
+
263
+ Today approving the storyboard makes every clip, and the next stop is the end.
264
+ With the pilot stop, the run makes one clip after the storyboard, checks it and
265
+ parks. `status` then says it "made its pilot clip (scene <n>)" and whether the
266
+ words heard match. On UGC and the authority yapper the pilot is two clips, one
267
+ talking and one listening in silence. Show the pilot on the run page, the
268
+ words line and every "Check failed" or "Check skipped" line, then ask: keep
269
+ it, or redo it. When `status` says the pilot clip failed, there is nothing to
270
+ keep: offer the redo it prints, which names the scene.
271
+
272
+ - Keep it: `exodus video approve <runId>` makes the other clips, the expensive
273
+ part. The CLI prints no price for it: say so, and approve on their yes.
274
+ - Redo it: `exodus video retry-clip <runId> --scene <n> --note "<what is
275
+ wrong>"`. One new clip. The CLI prints no price for it: say so and wait for
276
+ their yes. The note steers the motion,
277
+ never the words.
278
+
279
+ ### End: watch and approve
280
+
281
+ At the final watch, follow the block `status` prints ("Where a run can
282
+ stop"). When the cut is already uploaded, give the member the run page to
283
+ watch it. When the run waits for a cut: `exodus video pull <runId> --out ./ad-<runId>`, make the
284
+ cut ("Cutting the ad"), `exodus video upload <runId> --file <cut.mp4>`, and
285
+ give the member the run page. Ask: approve, redo a clip, or stop here.
286
+
287
+ - Approve: `exodus video approve <runId>` makes the cut the ad. It is one-way.
288
+ - Redo a clip: `retry-clip` as at stop 4, after their yes. Then pull, cut
289
+ and upload again.
290
+
291
+ **On the song format**, tell the member this before they approve: "The song
292
+ made here is for review. Before this video runs as a paid ad, make the same
293
+ lyrics and style again in the Suno app while on a Pro or Premier plan, download
294
+ it there and use that file: Suno's terms allow commercial use only of songs made
295
+ on those plans and downloaded from Suno."
296
+
77
297
  ## Before anything
78
298
 
79
299
  - `npx @aicopycoders/exodus video --help` and `workflow --help` are the
@@ -191,9 +411,85 @@ exodus video director <runId> on|off|follow the trial director for
191
411
  what it is doing and its last three notes
192
412
  ```
193
413
 
414
+ **Starting from a template.** The Golden Six start here; "From one sentence to
415
+ a film" walks them. Each paid template phase, the script and then the
416
+ storyboard, is quoted first: run the line with `--quote-preparation --json`,
417
+ give the member `maximumUsd`, and run it again with `--authorize-preparation
418
+ <saved-quote.json>` in its place only on their yes. A template line with
419
+ neither is refused, and nothing is spent. The template flags, as `exodus video
420
+ --help` prints them:
421
+
422
+ ```operator-guide
423
+ exodus video start --script <file> --conceit <kind> --style <look> [--direction "<note>"] [--frame pov] [--pacing <jump-cuts|long-take|montage>] [--voice-path <path>] [--video-model <id>] [--voice <native|voice-first>] [--source-record <file.json>] [--adaptation-plan <file|original>] [--music] [--broll] [--one-shot] [--director] [--wait] [--json]
424
+ Template starts also accept: [--requested-seconds <seconds>] [--pictures-per-scene <1|3>] [--product <brandProductId>] [--elements <json|@file>] [--voices <json|@file>] [--resume-script <saved-stop-response.json>]
425
+ With --describe: [--product-context <text>] [--audience <text>] [--offer <text>] [--mechanism <text>]
426
+ exodus video start --input-options [--conceit <template>] [--voice <native|voice-first>] [--voice-path <path>] [--video-model <id>] [--json]
427
+
428
+ --describe Template: explicitly write from the brief in --script.
429
+ Review the returned script before preparing a storyboard.
430
+ Cannot be combined with --adapt or --resume-script
431
+ --adapt <intent> Template: adapt the exact pasted text in --script to the
432
+ selected structure. State what may change; no new claims,
433
+ identities or consent are inferred. Review original and
434
+ changed text before continuing. Not --adaptation-plan
435
+ --keep-original With --adapt, intentionally review the exact original
436
+ instead of generating changes. Guards and billable checks
437
+ still require a quote; no adaptation is claimed
438
+ --quote-preparation Request only the current script or storyboard phase quote.
439
+ No writer/audio/image/video work. Save --json and review
440
+ estimatedUsd (approximate), maximumUsd (phase bound), scope
441
+ and expiry; this is not a whole-video price
442
+ --authorize-preparation <saved-quote.json>
443
+ Explicitly accept that quote's maximumUsd for its exact
444
+ phase/input. Never upgrades input Automatic to paid consent.
445
+ Keep the same file for recovery; no silent new quote/retry
446
+ --stop-at-script Print the script the run would start on, and start no
447
+ storyboard/video run (start, with --conceit). Preparation
448
+ may still be paid. For templates, use
449
+ --json to save the approval, source and choices; edit only
450
+ a separate script file, then continue with --resume-script
451
+ --resume-script <saved-stop-response.json>
452
+ Continue a template's saved --stop-at-script --json
453
+ response with --script <edited.txt>, --conceit and
454
+ --style. Keep the server-issued approval, approved source,
455
+ brief, product, selected video model, signed references and voice map.
456
+ V2 also retains input intent/subject/structure/reference,
457
+ direction, sound/story choices and declared source/adaptation
458
+ records; material edits need a new quoted script review.
459
+ Explicit length, picture, --voice, --voice-path and
460
+ --video-model flags override their matching saved choices.
461
+ Changed or cleared --elements and --voices require
462
+ explicit --stop-at-script --json with
463
+ --resume-script to check the edited script and issue a new
464
+ approval; then resume that returned response to start.
465
+ Keep your original description and edited script files.
466
+ A different product still needs fresh writing and approval
467
+ without --resume-script.
468
+ Not for --show
469
+ --input-options List your templates: Golden Six first, then more templates.
470
+ Add --conceit <template> for structures, capabilities,
471
+ identity locks, references and account voices.
472
+ GET only: writes, quotes and starts nothing. Optional
473
+ --voice, --voice-path and --video-model require --conceit.
474
+ Reports unsupported, unavailable and empty separately;
475
+ use the returned IDs with --elements and --voices
476
+ ```
477
+
478
+ The other template flags (`--input-mode`, `--structure`, `--reference`,
479
+ `--subject`, `--template-brief`, `--song-controls`, `--mechanism-plan`,
480
+ `--requested-seconds`, `--pictures-per-scene`, `--product`, `--elements`,
481
+ `--voices`) are in `exodus video --help`.
482
+
194
483
  **From the storyboard on.**
195
484
 
196
485
  ```operator-guide
486
+ exodus video picks <runId> a format with a picks stop parks before the storyboard:
487
+ the faces, voices and rooms it drew, one link each
488
+ exodus video pick <runId> --face <who>=<n> --voice <who>=<n> --room <place>=<n>
489
+ pick one of each; nothing is planned until every slot has one
490
+ exodus video picks <runId> --redo face:<who>|room:<place> --note "…"
491
+ four new paid pictures for one face or room;
492
+ only after the member's yes
197
493
  exodus video storyboard <runId> read the scene cards
198
494
  exodus video voices <runId> who speaks and with whose voice
199
495
  exodus video voices <runId> --set <character>=<voiceId> give a character a voice
@@ -304,6 +600,10 @@ started.
304
600
  `status` prints "the app checks the storyboard and approves it itself if the
305
601
  checks pass" on a run headed that way. `--review-storyboard` is the default
306
602
  and changes nothing.
603
+ - A template run (the Golden Six, "From one sentence to a film") quotes the
604
+ script and the storyboard before it spends (`--quote-preparation`, then
605
+ `--authorize-preparation`), and always stops at the storyboard. `--one-shot`
606
+ is refused on a template start, and nothing is sent.
307
607
  - A Show run (`video start --show`) and a saved workflow run (`workflow run`)
308
608
  still pause at the storyboard for approval. Approving is what releases the
309
609
  voices and the clips. `status` prints "This run will pause for your approval
@@ -919,6 +1219,14 @@ dropped[] B-roll scene numbers the app left out
919
1219
  They have no clip on purpose: cut with
920
1220
  `--skip` and stay on the speaker
921
1221
  narration { file, timing }, or null on a per-scene run
1222
+ clipAudio keep | discard, on template-video pulls.
1223
+ Native talking keeps the clip's dialogue.
1224
+ Voice-first narration and song discard ALL
1225
+ embedded clip audio, including wordless
1226
+ pictures and reactions; use only the approved
1227
+ voice/song track. The bundled first-cut reads
1228
+ this policy for hand-run and automatic cuts.
1229
+ Absent on other models: existing cut rules apply.
922
1230
  cast[] one per identity still
923
1231
  characterId, name from the run's cast lock; null for an
924
1232
  unclaimed ledger still
@@ -1,4 +1,5 @@
1
1
  // B32–B34 consumer contract. No source mutation, policy table or width estimate.
2
+ /** Normalized [left, top, right, bottom] (XYXY), not storyboard XYWH. */
2
3
  export type Box = [number, number, number, number];
3
4
  export interface TextHold { code: string; id: string; reason: string; required: true; inherited?: true }
4
5
  export interface HeardWord { text: string; start: number; end: number; lineId?: string }
@@ -92,6 +93,8 @@ export interface Permissions {
92
93
  }
93
94
  export interface CaptionOptions {
94
95
  cap?: CaptionStyle | null; names?: string[]; lyricLines?: string[];
96
+ /** Internal selected narrated-finish grouping; ordinary callers default off. */
97
+ keepNumericLists?: boolean;
95
98
  /** Actual cut boundaries in the same heard clock. */
96
99
  cuts?: number[]; avoid?: Avoidance[]; W: number; H: number; totalSec?: number | null; measureText?: MeasureText;
97
100
  }
@@ -102,7 +105,7 @@ export interface CardOptions {
102
105
  }
103
106
  export interface PlanTextInput extends CardOptions {
104
107
  treatment: string; words?: HeardWord[];
105
- captions?: { on?: boolean; cap?: CaptionStyle; lyricLines?: string[]; names?: string[] };
108
+ captions?: { on?: boolean; cap?: CaptionStyle; lyricLines?: string[]; names?: string[]; keepNumericLists?: boolean };
106
109
  items?: TextItem[]; selection?: Selection; libass: boolean; cuts?: number[];
107
110
  inheritedHolds?: Array<{ code: string; id: string; reason: string }>;
108
111
  }
@@ -54,7 +54,7 @@ function fitText(text, { kind, fs: initialFs, box, xShare, yShare, style, W, H,
54
54
  return { code: "text-overflow" };
55
55
  }
56
56
 
57
- export function planCaptionScreens(words, { cap = null, names = [], lyricLines = [], cuts = [], avoid = [], W, H, totalSec = null, measureText } = {}) {
57
+ export function planCaptionScreens(words, { cap = null, names = [], lyricLines = [], cuts = [], avoid = [], W, H, totalSec = null, measureText, keepNumericLists = false } = {}) {
58
58
  const holds = [], notes = [];
59
59
  const fail = (code, reason) => ({ screens: [], holds: [hold(code, "captions", reason)], notes });
60
60
  if (!Array.isArray(words) || !words.length) return fail("word-times-missing", "captions require heard words on the cut clock");
@@ -70,6 +70,24 @@ export function planCaptionScreens(words, { cap = null, names = [], lyricLines =
70
70
  const neg = (k) => NEGATOR.test(c[k]) || /n['’]t$/iu.test(raw[k]);
71
71
  glue[i] = (/\d/u.test(raw[i]) && UNIT.test(c[i + 1])) || neg(i) || (AUX.test(c[i]) && neg(i + 1)) || FUNC.test(c[i]) || /^[$€£]$/u.test(raw[i]) || (/^[-–,.]$/u.test(raw[i + 1]) && /\d/u.test(raw[i])) || (/^[-–,.]$/u.test(raw[i]) && i > 0 && /\d/u.test(raw[i - 1])) || (/^\p{Lu}/u.test(raw[i]) && /^\p{Lu}/u.test(raw[i + 1]) && c[i] !== "i");
72
72
  }
73
+ // Only the selected narrated finish opts into this grouping. Ordinary
74
+ // caption callers retain their existing boundaries and chunk behavior.
75
+ if (keepNumericLists === true) {
76
+ // Preserve numeric enumerations without rewriting their punctuation.
77
+ // Actual sentence/pause/cut boundaries below still win.
78
+ const number = /^(?:\d+(?:[.,]\d+)*|zero|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve)(?:[-–]figure)?[,;.!?]?$/iu;
79
+ for (let i = 0; i < raw.length - 1; i++) {
80
+ if (!number.test(raw[i]) || !/[,;]$/u.test(raw[i])) continue;
81
+ let last = i, count = 1;
82
+ for (let j = i + 1; j < raw.length; j++) {
83
+ if (/^(?:and|or)$/iu.test(raw[j]) && number.test(raw[j + 1] ?? "")) continue;
84
+ if (!number.test(raw[j])) break;
85
+ last = j; count++;
86
+ if (!/[,;]$/u.test(raw[j]) && !/^(?:and|or)$/iu.test(raw[j + 1] ?? "")) break;
87
+ }
88
+ if (count > 1) for (let j = i; j < last; j++) glue[j] = true;
89
+ }
90
+ }
73
91
  for (const name of names) {
74
92
  const p = squash(name).split(" ").map(core);
75
93
  for (let i = 0; i + p.length <= words.length; i++) if (p.every((t, k) => t === c[i + k])) for (let k = 0; k < p.length - 1; k++) glue[i + k] = true;
@@ -238,7 +256,7 @@ export function planText({ treatment, words = [], captions = {}, items = [], avo
238
256
  directives.cards = cp.cards; directives.hook = cp.hook; directives.endCard = cp.endCard;
239
257
  if (captions.on === true) {
240
258
  const cardAvoid = [...cp.cards, ...(cp.hook ? [cp.hook] : []), ...(cp.endCard ? [cp.endCard] : []), ...cp.reservations];
241
- const p = planCaptionScreens(words, { cap: captions.cap, names: captions.names, lyricLines: captions.lyricLines, cuts, avoid: [...avoid, ...cardAvoid], W, H, totalSec, measureText });
259
+ const p = planCaptionScreens(words, { cap: captions.cap, names: captions.names, lyricLines: captions.lyricLines, keepNumericLists: captions.keepNumericLists === true, cuts, avoid: [...avoid, ...cardAvoid], W, H, totalSec, measureText });
242
260
  holds.push(...p.holds); directives.captions = p.screens;
243
261
  }
244
262
  if (!libass && (captions.on === true || all.some((i) => !["physical-readout", "authentic-lettering"].includes(i.provenance)))) holds.push(hold("libass-missing", "burn", "actual subtitles filter is unavailable; text is not delivered"));
@@ -95,6 +95,15 @@ export interface SourceMapFinding {
95
95
  detail: string;
96
96
  }
97
97
 
98
+ export interface NarrationFinishClock {
99
+ durationSec: number;
100
+ words: Array<{ w: string; s: number; e: number; lineId: string }>;
101
+ cuts: Array<{ sceneIndex: number; startSec: number; durationSec: number }>;
102
+ }
103
+ /** Existing pulled master, actual scene-cut starts and canonical tagged words.
104
+ * Refuses missing/invalid clocks before the worker can order finishing sound. */
105
+ export function narrationFinishClock(input: { dir: string; manifest: unknown; storyboard: unknown }): NarrationFinishClock;
106
+
98
107
  /**
99
108
  * Only with manifest.sourceMap === true, which auto-cut sets when the run's
100
109
  * frozen payload turns sourceEditMap on.
@@ -232,6 +241,17 @@ export interface CutPace {
232
241
  brollMinSec?: number;
233
242
  speedUpSlowBroll?: true;
234
243
  cutChecks?: true;
244
+ /** Present only with cutChecks. */
245
+ blipCheck?: true;
246
+ freezeCheck?: true;
247
+ floorCheck?: true;
248
+ flashCheck?: true;
249
+ levelStepCheck?: true;
250
+ voFitCheck?: true;
251
+ dashGapCheck?: true;
252
+ /** The numbers the pace was checked at: PACE_BARS, or the format's own. */
253
+ paceCheck?: { minWps: number; maxWps: number; minGapSec: number; maxGapSec: number; beatMaxSec: number; hookMaxGapSec: number };
254
+ nameCheck?: true;
235
255
  };
236
256
  /** `limited`: limitPeaks' limiter ran after the loudness pass. */
237
257
  loudness?: { lufs: number; truePeak: number; passes: 1 | 2; limited?: true };
@@ -252,6 +272,32 @@ export interface CutChecks {
252
272
  shortShots: Array<{ n: number; role: string; at: number; sec: number }>;
253
273
  /** null when ffmpeg could not read the cut's motion. */
254
274
  slowShots: Array<{ n: number; role: string; at: number; sec: number; motion: number; median: number }> | null;
275
+ /** blipCheck: shots under a second whose source shot ran a second or longer (srcSec null: no source shot to compare). Present only with it on. */
276
+ blips?: Array<{ n: number; role: string; at: number; sec: number; srcSec: number | null }>;
277
+ /** freezeCheck: stretches of a second or more where the picture does not move. Present only with it on. */
278
+ freezes?: Array<{ at: number; sec: number }>;
279
+ /** floorCheck: cards outside 2.5 to 3 s, shots after a card under 1 s before their first word, dialogue takes under 8 s with no reaction after, takes over 25% short of plan. */
280
+ floors?: {
281
+ cards: Array<{ n: number; label: string; at: number; sec: number }>;
282
+ leads: Array<{ card: number; n: number; at: number; leadSec: number }>;
283
+ dialogue: Array<{ n: number; at: number; sec: number }>;
284
+ shortTakes: Array<{ n: number; sec: number; planSec: number }>;
285
+ };
286
+ /** flashCheck: shots under 0.2 s (`shot`) and one-frame flashes the motion read shows (`frame`, n null). */
287
+ flashes?: Array<{ n: number | null; at: number; sec: number; from: "shot" | "frame" }>;
288
+ /** levelStepCheck: cuts where the sound between words steps over 3 dB; null when the cut's sound could not be read. */
289
+ levelSteps?: Array<{ n: number; at: number; stepDb: number; beforeDb: number; afterDb: number }> | null;
290
+ /** voFitCheck: a voice-over take starting under 0.3 s after the word before it (`early`), or its last word past its take (`late`). */
291
+ voFits?: Array<{ n: number; at: number; early?: number; late?: number }>;
292
+ /** dashGapCheck: gaps over 0.15 s after a line ending on a dash; `rolled` a gap over 0.3 s inside one take. */
293
+ dashGaps?: Array<{ line: string; next: string; at: number; gapSec: number; sameTake: boolean; rolled?: true }>;
294
+ /** paceCheck: lines outside the words-a-second band, and gaps between lines outside theirs. */
295
+ paceBreaks?: {
296
+ lines: Array<{ line: string; at: number; wps: number }>;
297
+ gaps: Array<{ line: string; next: string; at: number; gapSec: number; hook?: true; beat?: true }>;
298
+ };
299
+ /** nameCheck: how many script names were looked for in their takes, and the ones the scribe did not hear. */
300
+ names?: { checked: number; missing: Array<{ n: number; line: string; name: string }> };
255
301
  lufs: number | null;
256
302
  truePeak: number | null;
257
303
  verdict: { pass: boolean; fails: string[] };
@@ -288,16 +334,35 @@ export interface FirstCutOptions {
288
334
  music?: boolean;
289
335
  /** #3365: hold a scene's keyframe where it has no clip, instead of refusing. Defaults to off. */
290
336
  stillFill?: boolean;
291
- /** With the measured map only: render immutable pre-text pixels, then complete with completeFirstCutText. */
337
+ /** Render immutable pre-text pixels for mapped cuts or trusted Template authored text, then complete with completeFirstCutText. */
292
338
  prepareText?: boolean;
293
339
  }
294
340
 
341
+ /** Semantic preservation and visible final-clock windows, not generated-quality proof.
342
+ * Only trusted template runs carry this; ordinary cuts retain their old shape. */
343
+ export interface CutMotion {
344
+ shots: Array<{
345
+ sceneIndex: number; startSec: number; seconds: number; file: string | null; speed: number;
346
+ /** Actual selected board/plan obligations, never prompt-keyword inference. */
347
+ protection?: Record<string, unknown>;
348
+ }>;
349
+ holds: Array<{
350
+ sceneIndex: number; startSec: number; seconds: number; basis: string;
351
+ /** The actual underlying spine has no audible voice or whole-song track. */
352
+ silent: boolean;
353
+ }>;
354
+ }
355
+
295
356
  export interface FirstCut {
296
357
  out: string;
297
358
  durationSec: number;
298
359
  /** The music file the cut used, or null. */
299
360
  music: string | null;
300
- timeline: { spine: Array<{ sceneIndex: number }>; left: string[] };
361
+ timeline: {
362
+ spine: Array<{ sceneIndex: number; audio?: "clip" | "narration" | "silence"; startSec?: number }>;
363
+ left: string[];
364
+ };
365
+ motion?: CutMotion;
301
366
  /** Budget-only decoded receipt; also supported when sourceEditMap is absent. */
302
367
  planningTiming?: FinalPlanningTiming;
303
368
  /** Present only when the manifest turned a finishing setting on. */
@@ -313,7 +378,7 @@ export interface FirstCut {
313
378
  * final heard word, with visible living-tail observation, never silent fill. */
314
379
  sourceMap?: SourceEditMap;
315
380
  /** Internal prepared artifact; cannot be attached as a completed text finish. */
316
- textStage?: { dir: string; board: unknown; policy: unknown };
381
+ textStage?: { dir: string; board: unknown; policy: unknown; speed?: number; frames?: number };
317
382
  text?: TextPlan;
318
383
  }
319
384
 
@@ -321,6 +386,12 @@ export interface FirstCut {
321
386
  export function sourceMapPath(outPath: string): string;
322
387
 
323
388
  export function firstCut(options: FirstCutOptions): FirstCut;
389
+ /** Resolve approved authored phases against visible source/word windows.
390
+ * Flexible template phases bind actual planPicture slots, never unused capacity. */
391
+ export function resolveTemporalRequirements(cut: FirstCut, board: unknown): Pick<TemporalFinishEvidence, "requirements" | "owners" | "holds">;
392
+ /** Consume exact-source temporal evidence and retained media. Unknown inputs are
393
+ * serialized board/policy/receipt shapes; this does not manufacture observations. */
394
+ export function finishFulfillment(cut: FirstCut, board: unknown, policy: unknown, temporal?: unknown): FinishFulfillment;
324
395
  /** Measures the actual final file without constructing a source map or changing media. */
325
396
  export function measureCutPlanningTiming(file: string, planningBudget: PlanningBudget): {
326
397
  planningTiming: FinalPlanningTiming;
@@ -333,7 +404,12 @@ export interface TextRenderer {
333
404
  assertFont?: () => boolean;
334
405
  }
335
406
 
336
- /** Observes the exact prepared pixels, measures/renders literal text, stream-copies sound and re-probes the final target. */
407
+ /** Observes the exact prepared pixels, measures/renders literal text, stream-copies sound and re-probes the final target.
408
+ * Trusted Template authored text also supports native/song cuts without adding
409
+ * a source map or changing their audio finishing. Captions follow audible
410
+ * joins/removals, not muted picture inserts; selected captionsByLine adds
411
+ * approved line boundaries without changing word intervals. Ordinary routes
412
+ * retain their grouping. Missing libass/font measurement still holds. */
337
413
  export function completeFirstCutText(cut: FirstCut, options?: {
338
414
  out?: string;
339
415
  prepareReadoutVerifier?: ReadoutPreparer;