@nodaro/shared 3.16.0 → 3.18.0

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.
@@ -19,6 +19,19 @@
19
19
  * reads and exports keep both; every other reader's projection drops them, and
20
20
  * drops them from the bin's deleted entries too.
21
21
  *
22
+ * So is a LINKED (keyframe / sequence) production's owner state (T87), on the
23
+ * same terms: the director's sequence recommendations
24
+ * ({@link STUDIO_SEQUENCE_PLANNING_KEYS}), the current generation preferences
25
+ * ({@link STUDIO_SEQUENCE_POLICY_KEYS} — emptied, not dropped), a take's
26
+ * endpoint pins ({@link STUDIO_TAKE_SEQUENCE_KEYS}, on the result rows), a
27
+ * sequence take unit's continuation review
28
+ * ({@link STUDIO_SEQUENCE_UNIT_REVIEW_KEYS}), a unit result's frozen request
29
+ * ({@link STUDIO_SEQUENCE_UNIT_MANIFEST_KEYS}), a keyframe's in-flight runs
30
+ * and review record ({@link STUDIO_KEYFRAME_NODE_TRANSIENT_KEYS},
31
+ * {@link STUDIO_KEYFRAME_TRANSIENT_KEYS}, {@link STUDIO_KEYFRAME_REVIEW_KEYS}),
32
+ * and the owner's reason for waiving a keyframe's requirements, inside its
33
+ * acceptance ({@link STUDIO_KEYFRAME_ACCEPTANCE_PRIVATE_KEYS}).
34
+ *
22
35
  * They do NOT all live at the same level, and that is the whole reason this
23
36
  * file exists rather than one array: the writer puts `trash` and
24
37
  * `freecutDraftUrl` on `settings.studio` itself, and puts the per-shot markers
@@ -79,6 +92,22 @@ export const STUDIO_SHOT_TRANSIENT_KEYS = ["pendingClips", "pendingClip", "pendi
79
92
  */
80
93
  export const STUDIO_SHOT_DRAFT_KEYS = ["stillSlots", "clipSlots"] as const
81
94
 
95
+ /**
96
+ * ...and a SHOT's 3D previsualization RUN STATE, on `shots[].previsualization`:
97
+ * `pendingJobs` (the scene runs in flight) and `proSubmission` (a 3D Render Pro
98
+ * submission's idempotency key and its exact priced body). Same reason as the
99
+ * per-shot markers — they name jobs on the owner's account — and a sharper one
100
+ * for the Pro key: carried out, it would let a replay adopt the owner's paid
101
+ * run. A finished render and an unadopted result (`pendingPlan`) are results,
102
+ * not run state, and stay.
103
+ *
104
+ * The PUBLIC share read's strip only ({@link stripStudioTransientSettings}),
105
+ * mirroring the studio codec's non-owner projection (`stripTransientSettings`,
106
+ * which drops the same two keys). A `view` read keeps them, as the codec's
107
+ * read-only load does ({@link stripStudioDraftSettings}).
108
+ */
109
+ export const STUDIO_PREVIZ_RUN_STATE_KEYS = ["pendingJobs", "proSubmission"] as const
110
+
82
111
  /** Everything a shot entry loses on its way to a reader who is not its owner. */
83
112
  const STUDIO_SHOT_PRIVATE_KEYS: ReadonlyArray<string> = [...STUDIO_SHOT_TRANSIENT_KEYS, ...STUDIO_SHOT_DRAFT_KEYS]
84
113
 
@@ -96,6 +125,126 @@ const STUDIO_SHOT_PRIVATE_KEYS: ReadonlyArray<string> = [...STUDIO_SHOT_TRANSIEN
96
125
  */
97
126
  export const STUDIO_TAKE_VOICE_KEYS = ["revoiceTo", "voiceMode"] as const
98
127
 
128
+ /**
129
+ * ...and a finished TAKE's SEQUENCE PINS (studio ruling T87): the exact
130
+ * keyframe results a linked scene's clip was generated between
131
+ * (`sequenceEndpoints`). Like the voice record it rides the RESULT, on a canvas
132
+ * node's `data.generatedResults` rows, so the same walker drops both
133
+ * ({@link stripStudioTakeVoiceRecords}). The in-flight marker carrying the same
134
+ * pins (`pendingClips[].sequenceEndpoints`) already goes whole with
135
+ * {@link STUDIO_SHOT_TRANSIENT_KEYS}.
136
+ */
137
+ export const STUDIO_TAKE_SEQUENCE_KEYS = ["sequenceEndpoints"] as const
138
+
139
+ /** Everything a result row loses on its way to a reader who is not its owner. */
140
+ const STUDIO_TAKE_PRIVATE_KEYS: ReadonlyArray<string> = [...STUDIO_TAKE_VOICE_KEYS, ...STUDIO_TAKE_SEQUENCE_KEYS]
141
+
142
+ /**
143
+ * ...and a LINKED production's SEQUENCE PLANNING state on `settings.studio`
144
+ * itself (T87): `sequenceRecommendations`, the director's suggested generation
145
+ * policies for each sequence, with their reasons and provenance.
146
+ *
147
+ * The studio codec's non-owner view withholds more than the lists here carry
148
+ * — a take's `policy` and `compilation`, a unit's result rows (on the unit
149
+ * video node's `data.sequenceUnitResults`, mirrored in its `generatedResults`),
150
+ * a keyframe's `plan`, its `acceptance` record and all its results but the
151
+ * preview and the accepted one — because it builds that view AFTER reading
152
+ * the row. These strips drop KEYS from the stored row; they never filter rows
153
+ * or rewrite records, so all of it still goes out, the acceptance without its
154
+ * waiver reason ({@link STUDIO_KEYFRAME_ACCEPTANCE_PRIVATE_KEYS}).
155
+ *
156
+ * Part of it the codec's reader requires (0.13.0's `parseProduction`; without
157
+ * it every reader's load of the production fails): each take's `policy` and
158
+ * `compilation`; every unit result row some take selects, plus, for the take
159
+ * selected for export, the existing-clip opening row its policy names; a
160
+ * keyframe plan's `id`, `label`, `revision`, `frame` (any record, `{}`
161
+ * included) and `requirements` (a list, empty included); and the result its
162
+ * `previewResultKey` names. The rest it can do without: the unit node's
163
+ * mirror, the unit results no take selects, a keyframe's other results, its
164
+ * plan's `frame` content and `references`, and its `acceptance` — from which
165
+ * the non-owner view reads the accepted result. Studio ruling T94 keeps all of
166
+ * it visible.
167
+ */
168
+ export const STUDIO_SEQUENCE_PLANNING_KEYS = ["sequenceRecommendations"] as const
169
+
170
+ /**
171
+ * ...and a sequence TAKE's per-unit review (T87), on
172
+ * `settings.studio.sequenceTakes[].units[]`: `continuationAcceptance` — which
173
+ * result the owner accepted as the next continuation's predecessor, who, when,
174
+ * and the review checks.
175
+ */
176
+ export const STUDIO_SEQUENCE_UNIT_REVIEW_KEYS = ["continuationAcceptance"] as const
177
+
178
+ /**
179
+ * ...and a LINKED production's current GENERATION PREFERENCES on
180
+ * `settings.studio` (T87): `sequenceGenerationPolicies`, the policy the owner
181
+ * last set for each sequence — what its next take would be made with.
182
+ *
183
+ * EMPTIED, never deleted: a non-empty record goes out as `{}`. The codec's
184
+ * reader parses the key as a record whenever a production has takes, and
185
+ * reads an empty one fine. A row that does not carry the key never gains it:
186
+ * that reader takes the key alone for take state, and refuses it on a
187
+ * production that never declared takes. Each take's own `policy` — the one it
188
+ * was made with — stays (the reader requires it), so `{}` withholds the
189
+ * owner's current preference, not the takes' history.
190
+ */
191
+ export const STUDIO_SEQUENCE_POLICY_KEYS = ["sequenceGenerationPolicies"] as const
192
+
193
+ /**
194
+ * ...and a sequence unit RESULT's frozen request (T87), on a unit video node's
195
+ * `data.sequenceUnitResults[]` rows: `requestManifest` — the submission as the
196
+ * host froze it, with the compiled prompts, the reference media, the endpoint
197
+ * pins, the take's policy and snapshots of the owner's scenes as they stood
198
+ * then. Optional to the codec's reader; the rest of the row stays.
199
+ */
200
+ export const STUDIO_SEQUENCE_UNIT_MANIFEST_KEYS = ["requestManifest"] as const
201
+
202
+ /**
203
+ * ...and a KEYFRAME's in-flight image runs (T87, on T22's terms), which the
204
+ * writer keeps on the frame's image node: `data.keyframePendingImages`. Each
205
+ * names a job on the owner's account, with the frame it was submitted with and
206
+ * that submission's provenance; a reader can land none of them.
207
+ */
208
+ export const STUDIO_KEYFRAME_NODE_TRANSIENT_KEYS = ["keyframePendingImages"] as const
209
+
210
+ /**
211
+ * ...and the same runs on a DELETED keyframe, where the bin keeps the whole
212
+ * frame (`trash[].keyframe`, `kind: "keyframe"`) and calls them `pendingImages`.
213
+ */
214
+ export const STUDIO_KEYFRAME_TRANSIENT_KEYS = ["pendingImages"] as const
215
+
216
+ /**
217
+ * ...and a KEYFRAME's review record (T87): `rejections` — which of its results
218
+ * the owner sent back for revision, who, when and why — on each
219
+ * `settings.studio.keyframes[]` entry and on a deleted keyframe in the bin.
220
+ * Optional to the codec's reader. The frame's `acceptance` stays, without its
221
+ * waiver reason ({@link STUDIO_KEYFRAME_ACCEPTANCE_PRIVATE_KEYS}): every reader
222
+ * is shown the accepted result, and that is where the reader finds it.
223
+ */
224
+ export const STUDIO_KEYFRAME_REVIEW_KEYS = ["rejections"] as const
225
+
226
+ /**
227
+ * ...and a KEYFRAME acceptance's private part (T87): `waivedReason`, the
228
+ * owner's own words on why the requirements they waived are acceptable. It is
229
+ * one level down, inside the `acceptance` record of each
230
+ * `settings.studio.keyframes[]` entry and of a deleted keyframe in the bin, so
231
+ * the walk goes into the record ({@link keyframeForReader}).
232
+ *
233
+ * Optional to the codec's reader; the rest of the record stays, the waived
234
+ * requirement checks included. Only the codec's resolution of an accepted
235
+ * frame checks the reason (`reviewValid`): in a copy made from a stripped row,
236
+ * a frame that waived a requirement must be accepted again before the codec
237
+ * resolves it for a dependent frame or a clip.
238
+ */
239
+ export const STUDIO_KEYFRAME_ACCEPTANCE_PRIVATE_KEYS = ["waivedReason"] as const
240
+
241
+ /**
242
+ * Everything a deleted keyframe entry loses on its way to a reader who is not
243
+ * its owner. Its acceptance loses {@link STUDIO_KEYFRAME_ACCEPTANCE_PRIVATE_KEYS}
244
+ * as well.
245
+ */
246
+ const STUDIO_KEYFRAME_PRIVATE_KEYS: ReadonlyArray<string> = [...STUDIO_KEYFRAME_TRANSIENT_KEYS, ...STUDIO_KEYFRAME_REVIEW_KEYS]
247
+
99
248
  function isRecord(value: unknown): value is Record<string, unknown> {
100
249
  return !!value && typeof value === "object" && !Array.isArray(value)
101
250
  }
@@ -133,6 +282,25 @@ function stripShots(value: unknown, drop: ReadonlyArray<string>): unknown {
133
282
  return changed ? out : value
134
283
  }
135
284
 
285
+ /**
286
+ * `settings.studio.shots` with every shot's 3D run state
287
+ * ({@link STUDIO_PREVIZ_RUN_STATE_KEYS}) removed from its `previsualization`.
288
+ * The SAME array back when no shot carried any, and anything that is not
289
+ * shaped like a shot with a previsualization rides through untouched.
290
+ */
291
+ function stripPrevizRunState(value: unknown): unknown {
292
+ if (!Array.isArray(value)) return value
293
+ let changed = false
294
+ const out = value.map((entry) => {
295
+ if (!isRecord(entry)) return entry
296
+ const previz = entry.previsualization
297
+ if (!isRecord(previz) || !STUDIO_PREVIZ_RUN_STATE_KEYS.some((key) => key in previz)) return entry
298
+ changed = true
299
+ return { ...entry, previsualization: withoutKeys(previz, STUDIO_PREVIZ_RUN_STATE_KEYS) }
300
+ })
301
+ return changed ? out : value
302
+ }
303
+
136
304
  /**
137
305
  * A production's `settings` with the owner's working state removed.
138
306
  *
@@ -152,45 +320,151 @@ export function stripStudioTransientSettings(settings: unknown): unknown {
152
320
 
153
321
  const source = studio as Record<string, unknown>
154
322
  const kept = withoutKeys(source, STUDIO_TRANSIENT_KEYS)
155
- const shots = stripShots(source.shots, STUDIO_SHOT_PRIVATE_KEYS)
323
+ const shots = stripPrevizRunState(stripShots(source.shots, STUDIO_SHOT_PRIVATE_KEYS))
156
324
  if (source.shots !== undefined) kept.shots = shots
325
+ const planned = stripLinkedOwnerState(kept)
157
326
 
158
- // Nothing to drop at either level — hand back the original object so an
327
+ // Nothing to drop at any level — hand back the original object so an
159
328
  // ordinary share read allocates nothing.
160
- if (Object.keys(kept).length === Object.keys(source).length && shots === source.shots) {
329
+ if (Object.keys(kept).length === Object.keys(source).length && shots === source.shots && planned === kept) {
161
330
  return settings
162
331
  }
163
- return { ...(settings as Record<string, unknown>), studio: kept }
332
+ return { ...(settings as Record<string, unknown>), studio: planned }
164
333
  }
165
334
 
166
335
  /**
167
- * A workflow's `nodes` with every result row's voice record removed
168
- * ({@link STUDIO_TAKE_VOICE_KEYS}, T42).
336
+ * A workflow's `nodes` without the owner's state that rides a NODE rather
337
+ * than `settings`: every result row's voice record
338
+ * ({@link STUDIO_TAKE_VOICE_KEYS}, T42) and sequence pins
339
+ * ({@link STUDIO_TAKE_SEQUENCE_KEYS}, T87), every sequence unit result's
340
+ * frozen request ({@link STUDIO_SEQUENCE_UNIT_MANIFEST_KEYS}, T87), and a
341
+ * keyframe image node's in-flight runs
342
+ * ({@link STUDIO_KEYFRAME_NODE_TRANSIENT_KEYS}, T87). Named for the first.
169
343
  *
170
- * Every node's `data.generatedResults` is walked, not only a clip node's: the
171
- * keys exist only on clip takes, and a type list would be one more thing to
172
- * keep in step. Copy-on-write, and the SAME array back when no row carries
173
- * either key. Anything that is not node-shaped rides through untouched: this
174
- * runs on whatever is in the column.
344
+ * Every node is walked, not only a clip, unit or keyframe node: the keys exist
345
+ * only on those, and a type list would be one more thing to keep in step.
346
+ * Copy-on-write, and the SAME array back when no node carries any of the keys.
347
+ * Anything that is not node-shaped rides through untouched: this runs on
348
+ * whatever is in the column.
175
349
  */
176
350
  export function stripStudioTakeVoiceRecords(nodes: unknown): unknown {
177
351
  if (!Array.isArray(nodes)) return nodes
178
352
  let changed = false
179
353
  const out = nodes.map((node: unknown) => {
180
354
  const data = isRecord(node) ? node.data : undefined
181
- const rows = isRecord(data) ? data.generatedResults : undefined
182
- if (!Array.isArray(rows)) return node
355
+ if (!isRecord(data)) return node
356
+ const results = stripRows(data.generatedResults, STUDIO_TAKE_PRIVATE_KEYS)
357
+ const unitResults = stripRows(data.sequenceUnitResults, STUDIO_SEQUENCE_UNIT_MANIFEST_KEYS)
358
+ const running = STUDIO_KEYFRAME_NODE_TRANSIENT_KEYS.some((key) => key in data)
359
+ if (results === data.generatedResults && unitResults === data.sequenceUnitResults && !running) return node
360
+ changed = true
361
+ const kept = withoutKeys(data, STUDIO_KEYFRAME_NODE_TRANSIENT_KEYS)
362
+ if (results !== data.generatedResults) kept.generatedResults = results
363
+ if (unitResults !== data.sequenceUnitResults) kept.sequenceUnitResults = unitResults
364
+ return { ...(node as Record<string, unknown>), data: kept }
365
+ })
366
+ return changed ? out : nodes
367
+ }
368
+
369
+ /**
370
+ * A list of rows with the given keys off every row — a node's result rows, a
371
+ * unit's result rows. The SAME array back when no row carries one, and
372
+ * anything that is not a list, or not a row, rides through untouched.
373
+ */
374
+ function stripRows(value: unknown, drop: ReadonlyArray<string>): unknown {
375
+ if (!Array.isArray(value)) return value
376
+ let changed = false
377
+ const out = value.map((row: unknown) => {
378
+ if (!isRecord(row) || !drop.some((key) => key in row)) return row
379
+ changed = true
380
+ return withoutKeys(row, drop)
381
+ })
382
+ return changed ? out : value
383
+ }
384
+
385
+ /**
386
+ * `settings.studio` without the linked production's owner state these lists
387
+ * carry (T87): its own {@link STUDIO_SEQUENCE_PLANNING_KEYS}; each
388
+ * {@link STUDIO_SEQUENCE_POLICY_KEYS} record EMPTIED, never dropped and never
389
+ * added; every sequence take's units without their
390
+ * {@link STUDIO_SEQUENCE_UNIT_REVIEW_KEYS}; and every keyframe entry without
391
+ * its {@link STUDIO_KEYFRAME_REVIEW_KEYS} or its acceptance's
392
+ * {@link STUDIO_KEYFRAME_ACCEPTANCE_PRIVATE_KEYS}. Every other part of a take
393
+ * or a frame stays, including what the codec's reader requires to read the
394
+ * row (which part that is: {@link STUDIO_SEQUENCE_PLANNING_KEYS}).
395
+ *
396
+ * The ONE change site for both settings strips. The SAME object back when it
397
+ * carries none of it, and anything that is not take- or frame-shaped rides
398
+ * through — a preferences value that is not a record included.
399
+ */
400
+ function stripLinkedOwnerState(studio: Record<string, unknown>): Record<string, unknown> {
401
+ const takes = stripTakeUnitReviews(studio.sequenceTakes)
402
+ const keyframes = stripKeyframes(studio.keyframes)
403
+ const preferences = STUDIO_SEQUENCE_POLICY_KEYS.filter((key) => {
404
+ const value = studio[key]
405
+ return isRecord(value) && Object.keys(value).length > 0
406
+ })
407
+ if (!STUDIO_SEQUENCE_PLANNING_KEYS.some((key) => key in studio) && takes === studio.sequenceTakes
408
+ && keyframes === studio.keyframes && preferences.length === 0) return studio
409
+ const kept = withoutKeys(studio, STUDIO_SEQUENCE_PLANNING_KEYS)
410
+ if (takes !== studio.sequenceTakes) kept.sequenceTakes = takes
411
+ if (keyframes !== studio.keyframes) kept.keyframes = keyframes
412
+ for (const key of preferences) kept[key] = {}
413
+ return kept
414
+ }
415
+
416
+ /** `settings.studio.sequenceTakes` with every unit's review removed; the SAME array back when no unit carries one. */
417
+ function stripTakeUnitReviews(value: unknown): unknown {
418
+ if (!Array.isArray(value)) return value
419
+ let changed = false
420
+ const out = value.map((take: unknown) => {
421
+ if (!isRecord(take) || !Array.isArray(take.units)) return take
183
422
  let touched = false
184
- const kept = rows.map((row: unknown) => {
185
- if (!isRecord(row) || !STUDIO_TAKE_VOICE_KEYS.some((key) => key in row)) return row
423
+ const units = take.units.map((unit: unknown) => {
424
+ if (!isRecord(unit) || !STUDIO_SEQUENCE_UNIT_REVIEW_KEYS.some((key) => key in unit)) return unit
186
425
  touched = true
187
- return withoutKeys(row, STUDIO_TAKE_VOICE_KEYS)
426
+ return withoutKeys(unit, STUDIO_SEQUENCE_UNIT_REVIEW_KEYS)
188
427
  })
189
- if (!touched) return node
428
+ if (!touched) return take
190
429
  changed = true
191
- return { ...(node as Record<string, unknown>), data: { ...(data as Record<string, unknown>), generatedResults: kept } }
430
+ return { ...take, units }
192
431
  })
193
- return changed ? out : nodes
432
+ return changed ? out : value
433
+ }
434
+
435
+ /**
436
+ * `settings.studio.keyframes` with every entry as {@link keyframeForReader}
437
+ * leaves it: no {@link STUDIO_KEYFRAME_REVIEW_KEYS}, no acceptance waiver
438
+ * reason. The SAME array back when no entry carries either, and anything that
439
+ * is not a list, or not an entry, rides through untouched.
440
+ */
441
+ function stripKeyframes(value: unknown): unknown {
442
+ if (!Array.isArray(value)) return value
443
+ let changed = false
444
+ const out = value.map((frame: unknown) => {
445
+ if (!isRecord(frame)) return frame
446
+ const kept = keyframeForReader(frame, STUDIO_KEYFRAME_REVIEW_KEYS)
447
+ if (kept !== frame) changed = true
448
+ return kept
449
+ })
450
+ return changed ? out : value
451
+ }
452
+
453
+ /**
454
+ * A keyframe entry, live or deleted, without the given keys and without its
455
+ * acceptance's {@link STUDIO_KEYFRAME_ACCEPTANCE_PRIVATE_KEYS}; the rest of the
456
+ * acceptance stays. The ONE place either level is dropped, for the live
457
+ * entries ({@link stripKeyframes}) and the bin's ({@link binKeyframeForReader}).
458
+ * The SAME entry back when it carries none of it; an acceptance that is not a
459
+ * record rides through.
460
+ */
461
+ function keyframeForReader(frame: Record<string, unknown>, drop: ReadonlyArray<string>): Record<string, unknown> {
462
+ const acceptance = frame.acceptance
463
+ const waived = isRecord(acceptance) && STUDIO_KEYFRAME_ACCEPTANCE_PRIVATE_KEYS.some((key) => key in acceptance)
464
+ if (!waived && !drop.some((key) => key in frame)) return frame
465
+ const kept = withoutKeys(frame, drop)
466
+ if (waived) kept.acceptance = withoutKeys(acceptance, STUDIO_KEYFRAME_ACCEPTANCE_PRIVATE_KEYS)
467
+ return kept
194
468
  }
195
469
 
196
470
  /**
@@ -198,7 +472,9 @@ export function stripStudioTakeVoiceRecords(nodes: unknown): unknown {
198
472
  * slots ({@link STUDIO_SHOT_DRAFT_KEYS}) and its in-flight run markers
199
473
  * ({@link STUDIO_SHOT_TRANSIENT_KEYS}) — and the bin kept WITHOUT the owner's
200
474
  * drafts in it ({@link stripBin}: deleted empty slots, deleted takes' voice
201
- * records). The document-level markers and everything else stay.
475
+ * records) — and without a linked production's owner state
476
+ * ({@link stripLinkedOwnerState}, T87). The document-level markers and
477
+ * everything else stay.
202
478
  *
203
479
  * For a reader the owner let LOOK but not edit: a `view` reader's
204
480
  * `GET /v1/workflows/:id` and `GET /v1/workflows/:id/export`, and the MCP
@@ -208,7 +484,8 @@ export function stripStudioTakeVoiceRecords(nodes: unknown): unknown {
208
484
  * and a marker for a run started from a slot carries that slot's unsent
209
485
  * inputs. An editor keeps all of it: their editor saves `settings` back whole.
210
486
  *
211
- * The very same object back when neither a shot nor the bin carries any of it.
487
+ * The very same object back when neither a shot, the bin nor the linked
488
+ * owner state carries any of it.
212
489
  */
213
490
  export function stripStudioDraftSettings(settings: unknown): unknown {
214
491
  if (!settings || typeof settings !== "object") return settings
@@ -216,8 +493,9 @@ export function stripStudioDraftSettings(settings: unknown): unknown {
216
493
  if (!isRecord(studio)) return settings
217
494
  const shots = stripShots(studio.shots, STUDIO_SHOT_PRIVATE_KEYS)
218
495
  const trash = stripBin(studio.trash)
219
- if (shots === studio.shots && trash === studio.trash) return settings
220
- const kept: Record<string, unknown> = { ...studio }
496
+ const planned = stripLinkedOwnerState(studio)
497
+ if (shots === studio.shots && trash === studio.trash && planned === studio) return settings
498
+ const kept: Record<string, unknown> = { ...planned }
221
499
  if (shots !== studio.shots) kept.shots = shots
222
500
  if (trash !== studio.trash) kept.trash = trash
223
501
  return { ...(settings as Record<string, unknown>), studio: kept }
@@ -225,20 +503,27 @@ export function stripStudioDraftSettings(settings: unknown): unknown {
225
503
 
226
504
  /**
227
505
  * The owner's BIN (`settings.studio.trash`) as a `view` reader receives it —
228
- * T11 and T42 applied to what the owner deleted:
506
+ * T11, T42 and T87 applied to what the owner deleted:
229
507
  *
230
508
  * - a deleted EMPTY slot (`kind: "slot"`) goes whole: it is an unsubmitted
231
509
  * draft, prose and reference urls the owner never generated;
232
510
  * - a deleted SCENE (`kind: "shot"`) is a one-scene production graph, so it
233
- * gets what a live production gets: its takes' records off the graph's nodes
234
- * and its slots and runs off the graph's scene entry;
511
+ * gets what a live production gets: the owner's state off the graph's nodes
512
+ * (takes' records and sequence pins, unit results' frozen requests, frame
513
+ * runs), its slots and runs off the graph's scene entry, and its linked
514
+ * owner state off the graph's settings;
515
+ * - a deleted KEYFRAME (`kind: "keyframe"`) keeps the frame without its
516
+ * in-flight runs, its review record or its acceptance's waiver reason
517
+ * ({@link binKeyframeForReader});
235
518
  * - any other entry — a deleted take (`kind: "clip"`, or a legacy entry with
236
519
  * no kind, which the bin reads as a clip) — keeps its result without the
237
- * voice record. A deleted still or keyframe carries none and rides through.
520
+ * voice record or the sequence pins. A deleted still carries none and rides
521
+ * through.
238
522
  *
239
- * Mirrors the studio codec's `withoutBinDrafts` branch for branch. Copy-on-
240
- * write, the SAME array back when no entry carries any of it, and anything
241
- * that is not an entry rides through untouched.
523
+ * Mirrors the studio codec's `withoutBinDrafts` branch for branch (that walker
524
+ * does not drop the T87 state yet, and lets a deleted keyframe through
525
+ * whole). Copy-on-write, the SAME array back when no entry carries any of it,
526
+ * and anything that is not an entry rides through untouched.
242
527
  */
243
528
  function stripBin(trash: unknown): unknown {
244
529
  if (!Array.isArray(trash)) return trash
@@ -249,7 +534,10 @@ function stripBin(trash: unknown): unknown {
249
534
  changed = true
250
535
  continue
251
536
  }
252
- const kept = !isRecord(entry) ? entry : entry.kind === "shot" ? binSceneForReader(entry) : binTakeForReader(entry)
537
+ const kept = !isRecord(entry) ? entry
538
+ : entry.kind === "shot" ? binSceneForReader(entry)
539
+ : entry.kind === "keyframe" ? binKeyframeForReader(entry)
540
+ : binTakeForReader(entry)
253
541
  if (kept !== entry) changed = true
254
542
  out.push(kept)
255
543
  }
@@ -266,17 +554,30 @@ function binSceneForReader(entry: Record<string, unknown>): Record<string, unkno
266
554
  return { ...entry, graph: { ...graph, nodes, settings } }
267
555
  }
268
556
 
269
- /** A deleted take without its voice record; any other entry as it is. */
557
+ /** A deleted take without its voice record or sequence pins; any other entry as it is. */
270
558
  function binTakeForReader(entry: Record<string, unknown>): Record<string, unknown> {
271
559
  const result = entry.result
272
- if (!isRecord(result) || !STUDIO_TAKE_VOICE_KEYS.some((key) => key in result)) return entry
273
- return { ...entry, result: withoutKeys(result, STUDIO_TAKE_VOICE_KEYS) }
560
+ if (!isRecord(result) || !STUDIO_TAKE_PRIVATE_KEYS.some((key) => key in result)) return entry
561
+ return { ...entry, result: withoutKeys(result, STUDIO_TAKE_PRIVATE_KEYS) }
562
+ }
563
+
564
+ /**
565
+ * A deleted keyframe without its in-flight runs or its review record
566
+ * ({@link STUDIO_KEYFRAME_PRIVATE_KEYS}), and without its acceptance's waiver
567
+ * reason ({@link keyframeForReader}); the SAME entry back when it carries none
568
+ * of it.
569
+ */
570
+ function binKeyframeForReader(entry: Record<string, unknown>): Record<string, unknown> {
571
+ const keyframe = entry.keyframe
572
+ if (!isRecord(keyframe)) return entry
573
+ const kept = keyframeForReader(keyframe, STUDIO_KEYFRAME_PRIVATE_KEYS)
574
+ return kept === keyframe ? entry : { ...entry, keyframe: kept }
274
575
  }
275
576
 
276
577
  /**
277
578
  * A workflow row as a reader the owner let LOOK but not edit receives it: the
278
- * takes' voice records off its `nodes` ({@link stripStudioTakeVoiceRecords})
279
- * and the owner's drafts and runs off its `settings`
579
+ * owner's state off its `nodes` ({@link stripStudioTakeVoiceRecords}) and the
580
+ * owner's drafts, runs and linked-production state off its `settings`
280
581
  * ({@link stripStudioDraftSettings}).
281
582
  *
282
583
  * The ONE strip every `view` door applies, so no door can strip the settings
@@ -0,0 +1,75 @@
1
+ /**
2
+ * Capability lookups for the text-to-speech lane.
3
+ *
4
+ * Every "does this model do X" decision on that lane reads the model's `tts`
5
+ * sheet in `MODEL_CATALOG` through these helpers — tag stripping, which voice
6
+ * settings are sent and shown, the language picker. Declare the sheet honestly
7
+ * on the catalog entry and a new model is covered everywhere; do not compare a
8
+ * provider id by hand.
9
+ *
10
+ * "The text-to-speech lane" means the models that list the `tts` mode. The
11
+ * dialogue model carries a sheet too, but a text-to-speech request that names it
12
+ * runs as the fallback model, so these helpers answer for the fallback there.
13
+ * (Today only the dialogue sheet's `maxChars` and `languages` are read, by
14
+ * `MAX_TTS_CHARS_BY_PROVIDER` and the language picker.)
15
+ */
16
+ import { MODEL_CATALOG, type TtsCapabilities, type TtsSettingLever } from "./model-catalog.js"
17
+
18
+ /** Legacy provider ids that are another model under an old name. They have no catalog entry of their own. */
19
+ export const TTS_PROVIDER_ALIASES: Readonly<Record<string, string>> = {
20
+ elevenlabs: "elevenlabs-turbo",
21
+ }
22
+
23
+ /** The model a request runs on when its provider id is missing or unknown. */
24
+ export const TTS_FALLBACK_PROVIDER = "elevenlabs-turbo"
25
+
26
+ /**
27
+ * Resolve a legacy alias to the catalog id it runs as. Any other id passes
28
+ * through unchanged. Own properties only: an id that happens to be the name of
29
+ * an inherited object member (`constructor`, `__proto__`, `toString`) is an
30
+ * unknown id like any other, never a function.
31
+ */
32
+ export function canonicalTtsProvider(provider: string): string {
33
+ return typeof provider === "string" && Object.hasOwn(TTS_PROVIDER_ALIASES, provider) ? TTS_PROVIDER_ALIASES[provider]! : provider
34
+ }
35
+
36
+ /** The capability sheet of a text-to-speech model, or `undefined` when the id is not one. */
37
+ export function findTtsCapabilities(provider: string | undefined): TtsCapabilities | undefined {
38
+ // `typeof`: node data can be written straight into workflow JSON, so the "string" is not guaranteed — and
39
+ // `Object.hasOwn` would coerce an array like ["elevenlabs-v3"] into that model's id. A non-string is an unknown id.
40
+ if (typeof provider !== "string" || !provider) return undefined
41
+ const id = canonicalTtsProvider(provider)
42
+ if (!Object.hasOwn(MODEL_CATALOG, id)) return undefined
43
+ const entry = MODEL_CATALOG[id]!
44
+ return entry.modes.includes("tts") ? entry.tts : undefined
45
+ }
46
+
47
+ /**
48
+ * The capability sheet a text-to-speech request will actually run under: a
49
+ * missing or unknown provider id runs as {@link TTS_FALLBACK_PROVIDER}, so it
50
+ * gets that sheet — including its `maxChars` (turbo's 40,000), where
51
+ * `getMaxTtsChars` keeps answering its 5,000 default for such ids.
52
+ */
53
+ export function getTtsCapabilities(provider: string | undefined): TtsCapabilities {
54
+ return findTtsCapabilities(provider) ?? MODEL_CATALOG[TTS_FALLBACK_PROVIDER]!.tts!
55
+ }
56
+
57
+ /** The model performs inline `[audio tags]`. false ⇒ strip them before sending. */
58
+ export function ttsSupportsAudioTags(provider: string | undefined): boolean {
59
+ return getTtsCapabilities(provider).audioTags
60
+ }
61
+
62
+ /** The model honours SSML `<break time="…"/>` tags. */
63
+ export function ttsSupportsSsmlBreaks(provider: string | undefined): boolean {
64
+ return getTtsCapabilities(provider).ssmlBreaks
65
+ }
66
+
67
+ /** The model honours this voice-setting lever. */
68
+ export function ttsHasLever(provider: string | undefined, lever: TtsSettingLever): boolean {
69
+ return getTtsCapabilities(provider).levers.includes(lever)
70
+ }
71
+
72
+ /** Language codes offered for the model, in catalog order. */
73
+ export function ttsLanguageCodes(provider: string | undefined): readonly string[] {
74
+ return getTtsCapabilities(provider).languages
75
+ }