@lincyaw/workbench 0.2.0-rc.4 → 0.2.0-rc.40

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.
Files changed (75) hide show
  1. package/package.json +5 -4
  2. package/src/MediaClipEditor.tsx +1 -1
  3. package/src/authoring-client.ts +3 -3
  4. package/src/authoring-draft-fragment.ts +3 -1
  5. package/src/component-property-drafts.ts +5 -5
  6. package/src/components.tsx +10 -28
  7. package/src/context.tsx +2 -1
  8. package/src/diagnostics.ts +1 -1
  9. package/src/document-drafts.ts +6 -7
  10. package/src/document-editing.ts +484 -0
  11. package/src/document-editor/BlockNoteSurface.tsx +25 -9
  12. package/src/document-editor/ComponentMaterials.tsx +3 -9
  13. package/src/document-editor/ComponentPropertiesDialog.tsx +4 -4
  14. package/src/document-editor/DocumentBlockPreview.tsx +4 -2
  15. package/src/document-editor/DocumentComments.tsx +58 -9
  16. package/src/document-editor/DocumentEditor.tsx +44 -7
  17. package/src/document-editor/DocumentStepNarration.tsx +30 -25
  18. package/src/document-editor/NarrationEditor.tsx +54 -20
  19. package/src/document-editor/NewCommentDrafts.tsx +4 -3
  20. package/src/document-editor/PlaceComment.tsx +150 -0
  21. package/src/document-editor/comment-drafts.ts +16 -14
  22. package/src/document-editor/comments.ts +30 -10
  23. package/src/document-editor/component-label.ts +11 -0
  24. package/src/document-editor/file-input.ts +2 -2
  25. package/src/document-editor/focus.ts +0 -2
  26. package/src/document-editor/insertion-place.ts +60 -0
  27. package/src/document-editor/messages.ts +3 -3
  28. package/src/document-editor/narration-schema.tsx +12 -6
  29. package/src/document-editor/narration.ts +19 -3
  30. package/src/document-editor/page-body.ts +60 -0
  31. package/src/document-editor/projection.ts +2 -2
  32. package/src/document-editor/rich-text.ts +3 -2
  33. package/src/document-editor/selection.ts +13 -0
  34. package/src/document-editor/style.css +12 -1
  35. package/src/document-editor/table-identities.ts +2 -1
  36. package/src/document-production.ts +331 -0
  37. package/src/document-session.ts +50 -16
  38. package/src/history.ts +3 -3
  39. package/src/index.ts +5 -5
  40. package/src/jobs.ts +1 -1
  41. package/src/messages.ts +19 -4
  42. package/src/panels/DocumentView.tsx +21 -21
  43. package/src/panels/DocumentVoiceDialog.tsx +2 -2
  44. package/src/panels/DocumentVoiceField.tsx +1 -1
  45. package/src/panels/ExportPanel.tsx +1 -6
  46. package/src/panels/HistoryPanel.tsx +1 -1
  47. package/src/panels/PageDeleteDialog.tsx +4 -4
  48. package/src/panels/PageRenameDialog.tsx +1 -1
  49. package/src/panels/PreviewPanel.tsx +1 -4
  50. package/src/panels/ProductionCaptionSize.tsx +20 -0
  51. package/src/panels/ProductionCaptionTiming.tsx +7 -7
  52. package/src/panels/ProductionMediaClips.tsx +6 -5
  53. package/src/panels/ProductionPanel.tsx +7 -3
  54. package/src/panels/ProductionRecording.tsx +1 -1
  55. package/src/panels/ProductionRecordingRange.tsx +4 -4
  56. package/src/panels/ProductionTimeline.tsx +6 -1
  57. package/src/panels/ProductionTranscription.tsx +5 -4
  58. package/src/panels/SourceDocumentPanel.tsx +12 -15
  59. package/src/panels/TranscriptionAdoption.tsx +9 -8
  60. package/src/panels/VoiceoverDialog.tsx +1 -1
  61. package/src/places.ts +1 -36
  62. package/src/preview-playback.ts +1 -1
  63. package/src/production-messages.ts +6 -0
  64. package/src/production-playback.ts +1 -1
  65. package/src/production-voice-playback.ts +3 -2
  66. package/src/sha256.ts +9 -0
  67. package/src/styles.css +16 -41
  68. package/src/use-recording-adoption.ts +2 -2
  69. package/src/voiceover-jobs.ts +1 -1
  70. package/src/workbench-state.ts +157 -0
  71. package/src/workbench.ts +101 -932
  72. package/src/workspace-client.ts +2 -1
  73. package/src/assistant-mascot.ts +0 -62
  74. package/src/mascot-preference.ts +0 -37
  75. package/src/panels/ChangeTrail.tsx +0 -79
@@ -0,0 +1,60 @@
1
+ import { createExtension } from '@blocknote/core'
2
+ import { Plugin, TextSelection } from '@tiptap/pm/state'
3
+ import type { EditorState } from '@tiptap/pm/state'
4
+ import { Decoration, DecorationSet } from '@tiptap/pm/view'
5
+ import type { Node } from '@tiptap/pm/model'
6
+ import type { NativeDocumentEditor } from './schema.tsx'
7
+
8
+ // Pages are top-level blocks: doc > blockGroup > blockContainer > (content, children?).
9
+ function emptyParagraph(container: Node | null | undefined): boolean {
10
+ return container?.childCount === 1 && container.firstChild!.type.name === 'paragraph' && container.firstChild!.content.size === 0
11
+ }
12
+
13
+ function pageEnds(doc: Node, placeholder: string): DecorationSet {
14
+ const group = doc.firstChild, found: Decoration[] = []
15
+ if (!group) return DecorationSet.empty
16
+ group.forEach((container, offset, index) => {
17
+ const next = index + 1 < group.childCount ? group.child(index + 1) : undefined
18
+ if (!emptyParagraph(container) || next && next.firstChild?.type.name !== 'presmiumPage') return
19
+ const start = 1 + offset + 1
20
+ found.push(Decoration.node(start, start + container.firstChild!.nodeSize, { 'data-page-end': '', 'data-placeholder': placeholder }))
21
+ })
22
+ return DecorationSet.create(doc, found)
23
+ }
24
+
25
+ /**
26
+ * A page's empty last paragraph shows the editor's placeholder even without the caret, so an empty body is visible;
27
+ * Enter at the end of a title goes into that paragraph instead of adding another one before it.
28
+ */
29
+ export const documentPageBodies = createExtension(({ editor }: { editor: NativeDocumentEditor }) => ({
30
+ key: 'presmium-document-page-bodies',
31
+ prosemirrorPlugins: [new Plugin<DecorationSet>({
32
+ state: {
33
+ init: (_, state: EditorState) => pageEnds(state.doc, editor.dictionary.placeholders.default ?? ''),
34
+ apply: (transaction, value) => transaction.docChanged ? pageEnds(transaction.doc, editor.dictionary.placeholders.default ?? '') : value,
35
+ },
36
+ props: { decorations(state) { return editor.isEditable ? this.getState(state) : undefined } },
37
+ })],
38
+ keyboardShortcuts: {
39
+ Enter: () => {
40
+ const { selection } = editor.prosemirrorState, { $head } = selection
41
+ if (!editor.isEditable || !selection.empty || $head.parent.type.name !== 'presmiumPage' || $head.parentOffset !== $head.parent.content.size) return false
42
+ const after = $head.after($head.depth - 1)
43
+ if (!emptyParagraph(editor.prosemirrorState.doc.resolve(after).nodeAfter)) return false
44
+ editor.transact(transaction => transaction.setSelection(TextSelection.create(transaction.doc, after + 2)).scrollIntoView())
45
+ return true
46
+ },
47
+ },
48
+ }))
49
+
50
+ /** The caret at the end of the document: in its empty last paragraph, or in a new one after the last block. */
51
+ export function focusDocumentEnd(editor: NativeDocumentEditor): void {
52
+ const last = editor.document.at(-1)
53
+ if (!last) return
54
+ editor.transact(transaction => {
55
+ if (last.type === 'paragraph' && !last.children.length && !last.content.length) editor.setTextCursorPosition(last, 'end')
56
+ else editor.setTextCursorPosition(editor.insertBlocks([{ type: 'paragraph' }], last, 'after')[0]!, 'start')
57
+ transaction.scrollIntoView()
58
+ })
59
+ editor.focus()
60
+ }
@@ -1,4 +1,4 @@
1
- import { documentPageDefaults, DOCUMENT_PAGE_DEFAULT_TIMING } from '@lincyaw/kernel'
1
+ import { documentPageDefaults, DOCUMENT_PAGE_DEFAULT_TIMING, randomUUID } from '@lincyaw/kernel'
2
2
  import type { DocumentBlock, DocumentPageIds, NarrationNode, RichTextNode, Section, TeachingDocument, TextBlock } from '@lincyaw/kernel'
3
3
  import { productInlineToNative } from './inline.ts'
4
4
  import { captureRichBaseline, createRichProjection, nativeRichTextToProduct, productRichTextToNative } from './rich-text.ts'
@@ -17,7 +17,7 @@ export interface DocumentProjection extends RichProjection {
17
17
  componentConfiguration: Map<string, string>
18
18
  }
19
19
  export type NativePageCreation = DocumentPageIds
20
- const newId = () => crypto.randomUUID()
20
+ const newId = () => randomUUID()
21
21
  export const pageId = (sectionId: string) => `page:${sectionId}`
22
22
  function plain(nodes: readonly { type: string, text?: string, children?: readonly unknown[] }[]): string {
23
23
  return nodes.map(node => node.type === 'text' ? node.text ?? '' : node.type === 'break' ? '\n' : node.children ? plain(node.children as Parameters<typeof plain>[0]) : '').join('')
@@ -1,4 +1,5 @@
1
1
  import type { InlineNode, JsonValue, ListItemNode, RichTextNode, TableNode } from '@lincyaw/kernel'
2
+ import { randomUUID } from '@lincyaw/kernel'
2
3
  import type { TableCellProps } from '@blocknote/core'
3
4
  import { nativeInlineToProduct, nativeTextStyleToProduct, productInlineToNative, productTextStyleToNative } from './inline.ts'
4
5
  import type { InlineProjectionContext, NativeInline } from './inline.ts'
@@ -27,12 +28,12 @@ export interface RichProjection extends InlineProjectionContext {
27
28
  tables: Map<string, { id: string, cells: string[] }[]>
28
29
  }
29
30
  export function createRichProjection(): RichProjection {
30
- return { rich: new Map(), baseline: new Map(), tables: new Map(), opaqueInline: new Map(), newInlineId: () => crypto.randomUUID() }
31
+ return { rich: new Map(), baseline: new Map(), tables: new Map(), opaqueInline: new Map(), newInlineId: () => randomUUID() }
31
32
  }
32
33
  export function captureRichBaseline(blocks: readonly DocumentEditorBlock[], context: RichProjection): void {
33
34
  for (const block of blocks) { context.baseline.set(block.id, JSON.stringify(block)); captureRichBaseline(block.children, context) }
34
35
  }
35
- const id = () => crypto.randomUUID()
36
+ const id = () => randomUUID()
36
37
  const atom = (node: RichTextNode): DocumentEditorInput => ({ id: node.id, type: 'presmiumAtom', props: { entityId: node.id, kind: `rich:${node.type}`, label: node.type === 'extension' ? fallbackText(node.fallback) : fallbackText(node) } })
37
38
 
38
39
  /** The projection records structural identities; the saved document owns all content. */
@@ -120,6 +120,19 @@ export function nativeTextPosition(editor: NativeDocumentEditor, point: { blockI
120
120
  return nativeTextPositionInDocument(editor.prosemirrorState.doc, point)
121
121
  }
122
122
 
123
+ /** The native range of a block's whole inline text, to select it. */
124
+ export function nativeBlockText(editor: NativeDocumentEditor, blockId: string): { from: number, to: number } | undefined {
125
+ let range: { from: number, to: number } | undefined
126
+ editor.prosemirrorState.doc.descendants((node, beforePos) => {
127
+ if (range) return false
128
+ if (node.attrs.id !== blockId) return
129
+ const info = getBlockInfoFromNode(node, beforePos)
130
+ if (info.hasContent && info.contentKind === 'inline') range = { from: info.contentStart, to: info.contentEnd }
131
+ return false
132
+ })
133
+ return range
134
+ }
135
+
123
136
  /** Stable anchor lookup against a captured native transaction’s input document. */
124
137
  export function nativeTextPositionInDocument(document: ProseMirrorNode, point: { blockId: string, offset: number }): number | undefined {
125
138
  let position: number | undefined
@@ -1,4 +1,8 @@
1
- .pm-document-editor { min-width: 0; }
1
+ .pm-document-editor { display: flex; flex: 1 0 auto; flex-direction: column; min-width: 0; }
2
+ /* The page below the last block, down to the sheet's end: a press there continues the document at its end. */
3
+ .pm-document-editor__end { flex: 1 0 auto; min-height: var(--pm-space-4); }
4
+ .pm-document-editor__end[data-editable] { cursor: text; }
5
+ .pm-document-editor .bn-block-content[data-page-end]:has(.ProseMirror-trailingBreak:only-child)::after { content: attr(data-placeholder); }
2
6
  .pm-document-editor__file-errors { display: flex; align-items: flex-start; gap: var(--pm-space-2); }
3
7
  .pm-document-editor__file-errors ul { flex: 1; min-width: 0; margin: 0; padding-inline-start: var(--pm-space-4); overflow-wrap: anywhere; }
4
8
  .pm-document-editor .pm-document-editor__page-title { margin-block: var(--pm-space-5) var(--pm-space-3); font-family: var(--pm-font-sans); font-size: var(--pm-text-title); font-weight: var(--pm-weight-semibold); line-height: var(--pm-leading-tight); }
@@ -7,3 +11,10 @@
7
11
  .pm-document-editor__fallback { display: grid; gap: var(--pm-space-2); min-width: 0; }
8
12
  .pm-document-editor__fallback p { margin: 0; white-space: pre-wrap; }
9
13
  .pm-document-editor__comment-tools { position: sticky; top: var(--pm-space-2); z-index: var(--pm-z-site-header); width: fit-content; margin-inline-start: var(--pm-space-5); }
14
+
15
+ /* A place comment's popover: the comment editor, a position picker and its actions. */
16
+ .pm-document-place-comment { width: min(var(--pm-comment-width), calc(100vw - var(--pm-space-8))); }
17
+ .pm-document-place-comment__body { display: grid; gap: var(--pm-space-2); min-width: 0; }
18
+ .pm-document-place-comment__editor { min-width: 0; }
19
+ .pm-document-place-comment__editor .bn-editor { max-height: min(var(--pm-comment-editor-max-height), 45vh); overflow-y: auto; overflow-wrap: anywhere; }
20
+ .pm-document-place-comment__actions { display: flex; justify-content: end; gap: var(--pm-space-2); }
@@ -1,6 +1,7 @@
1
1
  import { createExtension, getBlockInfoNearPos, getNodeId } from '@blocknote/core'
2
2
  import { Extension } from '@tiptap/core'
3
3
  import { Plugin } from '@tiptap/pm/state'
4
+ import { randomUUID } from '@lincyaw/kernel'
4
5
  import type { NativeDocumentEditor } from './schema.tsx'
5
6
  import type { RichProjection } from './rich-text.ts'
6
7
 
@@ -24,7 +25,7 @@ export const tableIdentityExtension = createExtension({
24
25
  after.doc.descendants((node, position) => {
25
26
  if (!TYPES.includes(node.type.name)) return
26
27
  let id = node.attrs[ATTR] as string | null
27
- if (!id || used.has(id)) { id = crypto.randomUUID(); transaction.setNodeMarkup(position, undefined, { ...node.attrs, [ATTR]: id }) }
28
+ if (!id || used.has(id)) { id = randomUUID(); transaction.setNodeMarkup(position, undefined, { ...node.attrs, [ATTR]: id }) }
28
29
  used.add(id)
29
30
  })
30
31
  if (transaction.steps.length) return transaction.setMeta('addToHistory', false)
@@ -0,0 +1,331 @@
1
+ import { applyDocumentCaptionTiming, changeDocumentCaptionScale, DOCUMENT_AUDIO_MAX_BYTES, randomUUID, replaceStepNarrations, sameProductionBinding, validateDocument } from '@lincyaw/kernel'
2
+ import type { DocumentAudioImportAnswer, DocumentAudioInspectionAnswer, DocumentCaptionTimingAction, DocumentChangeAnswer, DocumentRecordingAdoption, DocumentTranscriptionRequest, MediaClip, Narration, ProductionBinding, TeachingDocument, TranscriptionAdoptionAnswer, TranscriptionAdoptionApply, TranscriptionAdoptionDraft, TranscriptionAdoptionPlan, TranscriptionTask, VerifiedDocumentRecordingAdoption, VoiceSource } from '@lincyaw/kernel'
3
+ import { isAgentChanging } from './workbench-state.ts'
4
+ import type { WorkbenchStore } from './workbench-state.ts'
5
+ import type { DocumentSession, DocumentSessionState } from './document-session.ts'
6
+ import { WorkspaceServerError } from './workspace-client.ts'
7
+ import type { WorkspaceClient } from './workspace-client.ts'
8
+ import { sha256 } from './sha256.ts'
9
+ import { reconcileRecordingAdoption } from './recording-adoption.ts'
10
+ import { changeDocumentVoice } from './document-voices.ts'
11
+ import type { DocumentVoiceOptions, DocumentVoiceScope } from './document-voices.ts'
12
+ import { componentSource, sameComponentSource } from './component-properties.ts'
13
+ import { reconcileCaptionTiming } from './caption-timing.ts'
14
+ import { changeStepTiming } from './step-production.ts'
15
+ import type { StepDurationDraft, StepDurationKey, StepTimingPatch } from './step-production.ts'
16
+ import { DocumentTimingDrafts } from './document-timing-drafts.ts'
17
+ import { CaptionTimingDrafts } from './caption-timing-drafts.ts'
18
+ import type { CaptionTimingDraft } from './caption-timing-drafts.ts'
19
+
20
+ interface ProductionOptions {
21
+ store: WorkbenchStore
22
+ session: DocumentSession
23
+ client: WorkspaceClient
24
+ scope(): number
25
+ document(identity?: string): TeachingDocument | undefined
26
+ flush(signal?: AbortSignal): Promise<void>
27
+ pause(): Promise<void>
28
+ stopAuditions(): void
29
+ stopPreviewOutputs(): void
30
+ sourceCurrent(binding: ProductionBinding): boolean
31
+ }
32
+
33
+ /** Source-bound media transactions, timing drafts and narration edits share the document actor. */
34
+ export class DocumentProduction {
35
+ readonly #audioImports = new WeakMap<File, { identity: string, version: string, id: string }>()
36
+ readonly #audioFingerprints = new WeakMap<File, Promise<string>>()
37
+ readonly #documentTimingDrafts = new DocumentTimingDrafts()
38
+ readonly #captionTimingDrafts = new CaptionTimingDrafts()
39
+ readonly #removedCueTimings = new Map<string, { pauseMs: number }>()
40
+ readonly #removedNarrations = new Map<string, { narration: Narration, override?: { narrationStart: 'with-animation' | 'after-animation' } }>()
41
+ #cueTimingScope?: string
42
+ readonly #options: ProductionOptions
43
+ constructor(options: ProductionOptions) { this.#options = options }
44
+ draftState(authoring: DocumentSessionState) {
45
+ const scope = JSON.stringify([authoring.identity, authoring.reset])
46
+ if (this.#cueTimingScope !== scope) { this.#removedCueTimings.clear(); this.#removedNarrations.clear(); this.#cueTimingScope = scope }
47
+ return {
48
+ hasDocumentTimingDrafts: Boolean(authoring.identity && authoring.content && this.#documentTimingDrafts.has(authoring.identity, authoring.content)),
49
+ documentTimingDraftStorageFailure: this.#documentTimingDrafts.failed,
50
+ captionTimingDraftSteps: authoring.identity && authoring.member?.id && authoring.content ? this.#captionTimingDrafts.steps({ identity: authoring.identity, memberId: authoring.member.id }, authoring.content) : [],
51
+ captionTimingDraftStorageFailure: Boolean(authoring.identity && authoring.member?.id && this.#captionTimingDrafts.failed({ identity: authoring.identity, memberId: authoring.member.id })),
52
+ }
53
+ }
54
+ reset(): void { this.#removedCueTimings.clear(); this.#removedNarrations.clear(); this.#cueTimingScope = undefined }
55
+ dispose(): void { this.reset(); this.#captionTimingDrafts.close() }
56
+
57
+ source(expected: { identity: string, version: string }): DocumentSessionState {
58
+ const source = this.#options.store.state.authoring
59
+ if (!source || !this.#options.document(expected.identity) || source.version !== expected.version || !source.fingerprint
60
+ || source.dirty || source.saving || source.composing || source.restored || source.error || isAgentChanging(this.#options.store.state)) throw new Error('production-source-changed')
61
+ return source
62
+ }
63
+ /** Inspects the saved declaration, including a local asset not yet attached to a step. */
64
+ async inspectAudio(assetId: string, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<DocumentAudioInspectionAnswer> {
65
+ const source = this.source(expected), scope = this.#options.scope()
66
+ const answer = await this.#options.client.readDocumentAudio(source.directory, assetId, expected.version, signal)
67
+ signal?.throwIfAborted()
68
+ if (scope !== this.#options.scope() || answer.document !== source.directory || answer.version !== expected.version || answer.fingerprint !== source.fingerprint || answer.inspection.assetId !== assetId) throw new Error('production-source-changed')
69
+ this.source(expected)
70
+ return answer
71
+ }
72
+ /** Recognition keeps its captured source even if subsequent author input moves to a newer version. */
73
+ async startTranscription(request: Omit<DocumentTranscriptionRequest, 'source'>, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<TranscriptionTask> {
74
+ const source = this.source(expected)
75
+ if (!source.content || !source.fingerprint) throw new Error('production-source-changed')
76
+ const sent: DocumentTranscriptionRequest = { ...structuredClone(request), source: { documentId: source.content.id, version: expected.version, fingerprint: source.fingerprint } }
77
+ const answer = await this.#options.client.startTranscription(source.directory, sent, signal)
78
+ signal?.throwIfAborted()
79
+ if (answer.document !== source.directory || answer.intent !== sent.intent || answer.source.documentId !== sent.source.documentId
80
+ || answer.source.version !== sent.source.version || answer.source.fingerprint !== sent.source.fingerprint || answer.audio.assetId !== sent.assetId || answer.audio.sha256 !== sent.audioSha256) throw new Error('transcription-response-changed')
81
+ return answer
82
+ }
83
+ async planTranscription(draft: TranscriptionAdoptionDraft, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<TranscriptionAdoptionPlan> {
84
+ const source = this.source(expected), sent = structuredClone(draft)
85
+ if (sent.source.documentId !== source.content?.id || sent.source.version !== expected.version || sent.source.fingerprint !== source.fingerprint) throw new Error('production-source-changed')
86
+ const answer = await this.#options.client.planTranscriptionAdoption(source.directory, sent, signal)
87
+ signal?.throwIfAborted()
88
+ this.source(expected)
89
+ if (answer.document !== source.directory || answer.changeId !== sent.id || answer.source.documentId !== sent.source.documentId
90
+ || answer.source.version !== sent.source.version || answer.source.fingerprint !== sent.source.fingerprint || answer.candidate.id !== sent.candidate.id
91
+ || answer.candidate.revision !== sent.candidate.revision || answer.draftRevision !== sent.draftRevision) throw new Error('transcription-response-changed')
92
+ return answer
93
+ }
94
+ async adoptTranscription(request: TranscriptionAdoptionApply, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<TranscriptionAdoptionAnswer> {
95
+ const source = this.source(expected), sent = structuredClone(request)
96
+ if (sent.source.documentId !== source.content?.id || sent.source.version !== expected.version || sent.source.fingerprint !== source.fingerprint) throw new Error('production-source-changed')
97
+ const answer = await this.#writeDocumentMedia(expected, directory => this.#options.client.applyTranscriptionAdoption(directory, sent, signal), signal)
98
+ if (answer.adoption.planId !== sent.planId || answer.adoption.candidate.id !== sent.candidate.id || answer.adoption.candidate.revision !== sent.candidate.revision
99
+ || answer.adoption.draftRevision !== sent.draftRevision) throw new Error('transcription-response-changed')
100
+ return answer
101
+ }
102
+ async #writeDocumentMedia<T extends DocumentChangeAnswer>(expected: { identity: string, version: string }, write: (directory: string) => Promise<T>, signal?: AbortSignal): Promise<T> {
103
+ const scope = this.#options.scope(), source = this.source(expected)
104
+ this.#options.stopAuditions()
105
+ await this.#options.pause()
106
+ await this.#options.flush(signal)
107
+ signal?.throwIfAborted()
108
+ if (scope !== this.#options.scope()) throw new Error('production-source-changed')
109
+ this.source(expected)
110
+ let answer: T
111
+ try { answer = await write(source.directory) }
112
+ finally { await this.#options.session.refresh(source.directory) }
113
+ signal?.throwIfAborted()
114
+ if (scope !== this.#options.scope() || answer.document !== source.directory || answer.content.id !== source.content?.id) throw new Error('production-source-changed')
115
+ this.source({ identity: expected.identity, version: answer.version })
116
+ return answer
117
+ }
118
+ /** Import commits the original file and its declaration together, without creating a clip or narration. */
119
+ async importAudio(file: File, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<DocumentAudioImportAnswer> {
120
+ let request: { identity: string, version: string, id: string } | undefined
121
+ const answer = await this.#writeDocumentMedia(expected, async directory => {
122
+ const existing = this.#audioImports.get(file), first = !existing || existing.identity !== expected.identity
123
+ request = first ? { identity: expected.identity, version: expected.version, id: randomUUID() } : existing!
124
+ this.#audioImports.set(file, request)
125
+ try { return await this.#options.client.importDocumentAudio(directory, file, { id: request.id, baseDocumentVersion: request.version }, signal) }
126
+ catch (error) {
127
+ if (first && error instanceof WorkspaceServerError && error.status >= 400 && error.status < 500 && this.#audioImports.get(file) === request) this.#audioImports.delete(file)
128
+ throw error
129
+ }
130
+ }, signal)
131
+ if (answer.changeId !== request?.id || answer.inspection.assetId !== answer.assetId || !answer.content.assets[answer.assetId]) throw new Error('production-source-changed')
132
+ if (this.#audioImports.get(file) === request) this.#audioImports.delete(file)
133
+ return answer
134
+ }
135
+ /** Reconcile an ambiguous save against real asset bytes before admitting a new source-bound import. */
136
+ async ensureAudio(file: File, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<DocumentAudioInspectionAnswer> {
137
+ const source = this.source(expected)
138
+ if (!file.size || file.size > DOCUMENT_AUDIO_MAX_BYTES) throw new Error('production.asset-size')
139
+ let pending = this.#audioFingerprints.get(file)
140
+ if (!pending) {
141
+ pending = file.arrayBuffer().then(sha256)
142
+ this.#audioFingerprints.set(file, pending)
143
+ }
144
+ const hash = await pending
145
+ signal?.throwIfAborted(); this.source(expected)
146
+ for (const asset of Object.values(source.content?.assets ?? {})) {
147
+ if (asset.kind !== 'audio' || asset.fingerprint !== `sha256:${hash}`) continue
148
+ try {
149
+ const answer = await this.inspectAudio(asset.id, expected, signal)
150
+ if (answer.inspection.sha256 === hash) return answer
151
+ } catch (error) {
152
+ if (!(error instanceof WorkspaceServerError) || ![404, 413, 422].includes(error.status)) throw error
153
+ }
154
+ }
155
+ signal?.throwIfAborted(); this.source(expected)
156
+ const previous = this.#audioImports.get(file)
157
+ if (previous?.identity === expected.identity && previous.version !== expected.version) this.#audioImports.delete(file)
158
+ let imported: DocumentAudioImportAnswer
159
+ try { imported = await this.importAudio(file, expected, signal) }
160
+ catch (error) {
161
+ if (!previous || this.#audioImports.get(file) !== previous || !(error instanceof WorkspaceServerError)
162
+ || error.status !== 409 || error.message !== 'document-version-changed') throw error
163
+ signal?.throwIfAborted(); this.source(expected)
164
+ this.#audioImports.delete(file)
165
+ imported = await this.importAudio(file, expected, signal)
166
+ }
167
+ return { document: imported.document, version: imported.version, fingerprint: imported.fingerprint, inspection: imported.inspection }
168
+ }
169
+ /** The source actor owns this external transaction; capture is independent from preview output. */
170
+ async adoptRecording(request: DocumentRecordingAdoption, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<VerifiedDocumentRecordingAdoption> {
171
+ const scope = this.#options.scope(), source = this.source(expected), sent = structuredClone(request)
172
+ if (sent.source.documentId !== source.content?.id || sent.source.version !== source.version || sent.source.fingerprint !== source.fingerprint
173
+ || !source.content.steps[sent.stepId] || !source.content.assets[sent.assetId]) throw new Error('production-source-changed')
174
+ this.#options.stopPreviewOutputs()
175
+ await this.#options.pause()
176
+ await this.#options.flush(signal)
177
+ signal?.throwIfAborted()
178
+ if (scope !== this.#options.scope()) throw new Error('production-source-changed')
179
+ this.source(expected)
180
+ const answer = await this.#options.session.commitExternal(expected, async (_before, ownedSignal) => {
181
+ const saved = await this.#options.client.adoptRecording(source.directory, sent, ownedSignal)
182
+ if (saved.changeId !== sent.id || saved.verification.stepId !== sent.stepId || saved.verification.assetId !== sent.assetId || saved.verification.sha256 !== sent.sha256) throw new Error('document-confirmation')
183
+ return saved
184
+ }, (before, remote, current) => reconcileRecordingAdoption(sent, before, remote, current), signal)
185
+ signal?.throwIfAborted()
186
+ if (scope !== this.#options.scope() || this.#options.store.state.authoring?.identity !== expected.identity) throw new Error('production-source-changed')
187
+ return answer
188
+ }
189
+ async applyMediaClip(clip: MediaClip, expected: { identity: string, version: string, binding: ProductionBinding }, signal?: AbortSignal): Promise<DocumentChangeAnswer> {
190
+ this.source(expected)
191
+ if (!this.#options.store.state.productionPlan || !sameProductionBinding(this.#options.store.state.productionPlan.binding, expected.binding) || !this.#options.sourceCurrent(expected.binding)) throw new Error('production-source-changed')
192
+ const id = randomUUID(), value = structuredClone(clip)
193
+ const answer = await this.#writeDocumentMedia(expected, directory => this.#options.client.changeDocumentMediaClip(directory, { id, baseDocumentVersion: expected.version, binding: expected.binding, clip: value }, signal), signal)
194
+ if (answer.changeId !== id) throw new Error('production-source-changed')
195
+ return answer
196
+ }
197
+ async removeMediaClip(clipId: string, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<DocumentChangeAnswer> {
198
+ const id = randomUUID()
199
+ const answer = await this.#writeDocumentMedia(expected, directory => this.#options.client.changeDocumentMediaClip(directory, { id, baseDocumentVersion: expected.version, removeClipId: clipId }, signal), signal)
200
+ if (answer.changeId !== id) throw new Error('production-source-changed')
201
+ return answer
202
+ }
203
+ /** Applies a reviewed voice scope to the current source actor, without replacing body or narration. */
204
+ async applyVoice(scope: DocumentVoiceScope, value: VoiceSource | null, options: DocumentVoiceOptions, expected: { identity: string, version: string, fingerprint: string }): Promise<boolean> {
205
+ const source = this.#options.store.state.authoring, document = this.#options.document(expected.identity), context = this.#options.scope()
206
+ if (!source || !document || source.version !== expected.version || source.fingerprint !== expected.fingerprint
207
+ || source.dirty || source.saving || source.composing || source.restored || source.error || isAgentChanging(this.#options.store.state)) throw new Error('voice-context-changed')
208
+ const next = changeDocumentVoice(document, scope, value, options)
209
+ if (next === document) return true
210
+ this.#options.stopAuditions()
211
+ this.#options.session.record(next)
212
+ await this.#options.flush()
213
+ if (context !== this.#options.scope() || this.#options.store.state.authoring?.identity !== expected.identity) return false
214
+ const saved = this.#options.store.state.authoring
215
+ if (!saved || saved.dirty || saved.saving || saved.composing || saved.restored || saved.error) throw new Error('voice-save-unconfirmed')
216
+ return true
217
+ }
218
+
219
+ /** Manual caption times reuse the canonical action plan, media preflight and original source actor. */
220
+ async applyCaptionTiming(action: DocumentCaptionTimingAction, id: string, expected: { identity: string, version: string, fingerprint: string }, signal?: AbortSignal): Promise<DocumentChangeAnswer> {
221
+ const source = this.source(expected), scope = this.#options.scope()
222
+ if (!source.content || source.fingerprint !== expected.fingerprint) throw new Error('caption-source-changed')
223
+ const request = { id, source: componentSource({ content: source.content, version: source.version!, fingerprint: source.fingerprint! }), action }
224
+ const plan = await this.#options.client.planDocumentAction(source.directory, request, signal)
225
+ signal?.throwIfAborted()
226
+ if (scope !== this.#options.scope() || this.#options.store.state.authoring?.identity !== expected.identity || plan.effect.kind !== 'caption'
227
+ || plan.changeId !== id || JSON.stringify(plan.action) !== JSON.stringify(action) || !sameComponentSource(plan.source, request.source)) throw new Error('caption-source-changed')
228
+ this.#options.stopPreviewOutputs()
229
+ await this.#options.pause()
230
+ try {
231
+ return await this.#options.session.commitExternal(expected, async (_before, ownedSignal) => {
232
+ const receipt = await this.#options.client.applyDocumentAction(source.directory, { planId: plan.planId, digest: plan.digest, source: plan.source }, ownedSignal)
233
+ const actual = await this.#options.client.readDocument(source.directory)
234
+ if (receipt.planId !== plan.planId || receipt.digest !== plan.digest || receipt.changeId !== id || !receipt.verification.saved || !receipt.verification.actionStateVerified
235
+ || !sameComponentSource(receipt.verification.source, componentSource(actual))) throw new Error('document-confirmation')
236
+ return { ...actual, changeId: id, files: receipt.files }
237
+ }, (before, answer, current) => reconcileCaptionTiming(action, before, answer, current), signal)
238
+ } catch (error) {
239
+ const current = this.#options.store.state.authoring, file = plan.files.find(file => file.path === (source.directory ? `${source.directory}/lecture.json` : 'lecture.json'))
240
+ // Lost ACK was independently read by commitExternal; only the exact predicted saved version can settle it.
241
+ if (scope === this.#options.scope() && current?.identity === expected.identity && current.content && current.version === file?.version && current.fingerprint && !current.error) {
242
+ try {
243
+ if (!applyDocumentCaptionTiming(current.content, action).effect.changed) return { document: source.directory, content: plan.content, version: current.version!, fingerprint: current.fingerprint, changeId: id, issues: plan.issues, files: plan.files.map(({ path, version }) => ({ path, version })) }
244
+ } catch { /* A newer target stays pending with the actual request error. */ }
245
+ }
246
+ throw error
247
+ }
248
+ }
249
+ /** Uses the current actor revision so timing edits cannot replace later body or narration input. */
250
+ setStepTiming(stepId: string, patch: StepTimingPatch, identity?: string): void {
251
+ const document = this.#options.document(identity)
252
+ if (!document || isAgentChanging(this.#options.store.state)) return
253
+ const next = changeStepTiming(document, stepId, patch)
254
+ if (next === document) return
255
+ this.#options.stopAuditions()
256
+ this.#options.session.record(next)
257
+ }
258
+ /** The whole document's caption size (`production.captions.scale`), recorded like a step's timing. */
259
+ setCaptionScale(scale: number, identity?: string): void {
260
+ const document = this.#options.document(identity)
261
+ if (!document || isAgentChanging(this.#options.store.state)) return
262
+ const next = changeDocumentCaptionScale(document, scale)
263
+ if (next === document) return
264
+ this.#options.session.record(next)
265
+ }
266
+ timingDraft(stepId: string, key: StepDurationKey, identity: string, reset: number): StepDurationDraft | undefined {
267
+ const document = this.#options.document(identity)
268
+ return document && this.#options.store.state.authoring?.reset === reset ? this.#documentTimingDrafts.get(identity, document, stepId, key) : undefined
269
+ }
270
+ /** Retains unaccepted numeric input by stable target; it is not authoring content or a second timing source. */
271
+ setTimingDraft(stepId: string, key: StepDurationKey, draft: StepDurationDraft | undefined, identity: string, reset: number): void {
272
+ const source = this.#options.store.state.authoring, document = this.#options.document(identity)
273
+ if (!document?.steps[stepId] || source?.reset !== reset || isAgentChanging(this.#options.store.state)) return
274
+ if (!this.#documentTimingDrafts.set(identity, document, stepId, key, draft)) return
275
+ this.#options.store.set({ authoring: { ...source }, hasDocumentTimingDrafts: this.#documentTimingDrafts.has(identity, document), documentTimingDraftStorageFailure: this.#documentTimingDrafts.failed })
276
+ }
277
+ captionTimingDraft(stepId: string, identity: string): CaptionTimingDraft | undefined {
278
+ const source = this.#options.store.state.authoring
279
+ return source?.identity === identity && source.member?.id ? this.#captionTimingDrafts.get({ identity, memberId: source.member.id }, stepId) : undefined
280
+ }
281
+ setCaptionTimingDraft(stepId: string, draft: CaptionTimingDraft | undefined, identity: string): void {
282
+ const source = this.#options.store.state.authoring, document = this.#options.document(identity)
283
+ if (!document?.steps[stepId] || source?.identity !== identity || !source.member?.id) return
284
+ const scope = { identity, memberId: source.member.id }
285
+ this.#captionTimingDrafts.set(scope, stepId, draft)
286
+ this.#options.store.set({ captionTimingDraftSteps: this.#captionTimingDrafts.steps(scope, document), captionTimingDraftStorageFailure: this.#captionTimingDrafts.failed(scope) })
287
+ }
288
+ copyNarrationCueTiming(from: string, to: string, identity: string): void {
289
+ const document = this.#options.document(identity)
290
+ if (!document || isAgentChanging(this.#options.store.state)) return
291
+ const timing = document.production.cueTimings?.[from] ?? this.#removedCueTimings.get(from)
292
+ if (timing) this.#removedCueTimings.set(to, { ...timing })
293
+ }
294
+ /** Native block identity and order own the current step's complete script. */
295
+ setNarrations(stepId: string, narrations: Narration[], identity?: string): void {
296
+ const document = this.#options.document(identity)
297
+ if (!document || isAgentChanging(this.#options.store.state) || !Object.hasOwn(document.steps, stepId)) return
298
+ const step = document.steps[stepId]!
299
+ if (!document.sections[step.sectionId]?.stepOrder.includes(stepId)) return
300
+ const values = narrations.map(narration => {
301
+ const previous = document.narrations[narration.id] ?? this.#removedNarrations.get(narration.id)?.narration
302
+ return { ...previous, ...narration }
303
+ })
304
+ if (JSON.stringify(step.narrationIds.map(id => document.narrations[id])) === JSON.stringify(values)) return
305
+ const next = replaceStepNarrations(document, stepId, values)
306
+ for (const narration of values) {
307
+ const override = this.#removedNarrations.get(narration.id)?.override
308
+ if (override && !document.narrations[narration.id]) next.production.narrationOverrides = { ...next.production.narrationOverrides, [narration.id]: { ...override } }
309
+ }
310
+ const cueIds = new Set(values.flatMap(narration => narration.content.flatMap(node => node.type === 'cue' ? [node.id] : [])))
311
+ for (const cue of cueIds) {
312
+ const timing = this.#removedCueTimings.get(cue)
313
+ if (timing && !Object.hasOwn(next.production.cueTimings ?? {}, cue)) next.production.cueTimings = { ...next.production.cueTimings, [cue]: { ...timing } }
314
+ }
315
+ const references = (values: Narration[]) => JSON.stringify(values.map(narration => [narration.id, narration.provenance, narration.content.filter(node => node.type === 'cue')]))
316
+ if (references(step.narrationIds.map(id => document.narrations[id]!)) !== references(values)
317
+ && validateDocument(next).issues.some(issue => issue.severity === 'error')) throw new Error('document-narration-content')
318
+ for (const id of step.narrationIds) if (!next.steps[stepId]!.narrationIds.includes(id)) {
319
+ this.#removedNarrations.delete(id)
320
+ this.#removedNarrations.set(id, { narration: document.narrations[id]!, override: document.production.narrationOverrides?.[id] })
321
+ }
322
+ for (const [id, timing] of Object.entries(document.production.cueTimings ?? {})) if (!Object.hasOwn(next.production.cueTimings ?? {}, id)) {
323
+ this.#removedCueTimings.delete(id)
324
+ this.#removedCueTimings.set(id, { ...timing })
325
+ }
326
+ while (this.#removedNarrations.size > 512) this.#removedNarrations.delete(this.#removedNarrations.keys().next().value!)
327
+ while (this.#removedCueTimings.size > 512) this.#removedCueTimings.delete(this.#removedCueTimings.keys().next().value!)
328
+ this.#options.stopAuditions()
329
+ this.#options.session.record(next)
330
+ }
331
+ }