@lincyaw/kernel 1.0.0-rc.5 → 1.0.0-rc.50

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 (50) hide show
  1. package/README.md +1 -1
  2. package/package.json +4 -2
  3. package/src/contracts/authoring-actions.ts +3 -3
  4. package/src/contracts/authoring-clients.ts +58 -1
  5. package/src/contracts/capture.ts +148 -0
  6. package/src/contracts/document-voice.ts +35 -2
  7. package/src/contracts/document.ts +14 -1
  8. package/src/contracts/plugin.ts +1 -3
  9. package/src/contracts/preview.ts +3 -3
  10. package/src/contracts/projects.ts +4 -1
  11. package/src/contracts/speech-settings.ts +13 -0
  12. package/src/contracts/speech.ts +16 -0
  13. package/src/contracts/voiceover-execution.ts +25 -1
  14. package/src/contracts/workspace-changes.ts +27 -0
  15. package/src/contracts/workspace-review.ts +39 -0
  16. package/src/contracts/workspace-source.ts +38 -0
  17. package/src/contracts/workspace.ts +2 -0
  18. package/src/contracts.ts +4 -0
  19. package/src/document-authoring-actions.ts +23 -4
  20. package/src/document-caption-scale.ts +17 -0
  21. package/src/document-comments.ts +30 -37
  22. package/src/document-components.ts +4 -12
  23. package/src/document-narrations.ts +57 -0
  24. package/src/document-operations.ts +15 -1
  25. package/src/document-pages.ts +8 -1
  26. package/src/document-places.ts +92 -0
  27. package/src/document-schema.ts +3 -3
  28. package/src/document.ts +13 -1
  29. package/src/embed.ts +26 -0
  30. package/src/escape-html.ts +4 -0
  31. package/src/html.ts +1 -4
  32. package/src/index.ts +15 -6
  33. package/src/ir.ts +23 -48
  34. package/src/lower-myst.ts +3 -12
  35. package/src/myst-marks.ts +15 -0
  36. package/src/node/authoring-actions.ts +3 -1
  37. package/src/node/document-voice.ts +6 -2
  38. package/src/node/fonts.ts +6 -3
  39. package/src/node/index.ts +8 -3
  40. package/src/node/operator-speech.ts +4 -0
  41. package/src/node/packages.ts +25 -0
  42. package/src/node/service-state.ts +52 -0
  43. package/src/node/workspace-changes.ts +7 -0
  44. package/src/node/workspace-review.ts +9 -0
  45. package/src/node/workspace-source.ts +10 -0
  46. package/src/preview-events.ts +6 -4
  47. package/src/preview-frame-connect.ts +1105 -0
  48. package/src/preview-frame.ts +30 -1120
  49. package/src/random-uuid.ts +8 -0
  50. package/src/stale-module.ts +15 -0
package/README.md CHANGED
@@ -14,7 +14,7 @@ Plugins declare it as a peer dependency, so they share the application's copy:
14
14
 
15
15
  ## Entries
16
16
 
17
- - `@lincyaw/kernel`: the contracts (`PresmiumNodePlugin`, `PluginDefinition`, `DirectiveSpec`, `IRPass`, `Renderer`, `RenderContext`, `Check`, the service tokens), the canonical authoring types (`TeachingDocument`, `DocumentEditOperation`), `DOCUMENT_ENTRY`, `DOCUMENT_SCHEMA_VERSION`, `DOCUMENT_JSON_SCHEMA`, `validateDocument`, the derived IR types (`IRDocument` and its nodes), `KERNEL_VERSION`, `IR_VERSION`, and plain helpers such as `docBlocks`, `withProp`, `deckLocale`, `jsonResponse` and `problemResponse`.
17
+ - `@lincyaw/kernel`: the contracts (`PresmiumNodePlugin`, `PluginDefinition`, `IRPass`, `Renderer`, `RenderContext`, `Check`, the service tokens), the canonical authoring types (`TeachingDocument`, `DocumentEditOperation`), `DOCUMENT_ENTRY`, `DOCUMENT_SCHEMA_VERSION`, `DOCUMENT_JSON_SCHEMA`, `validateDocument`, the derived IR types (`IRDocument` and its nodes), `KERNEL_VERSION`, `IR_VERSION`, and plain helpers such as `docBlocks`, `withProp`, `deckLocale`, `jsonResponse` and `problemResponse`.
18
18
  - `@lincyaw/kernel/contracts`, `@lincyaw/kernel/ir`: the contracts (types, service tokens and the preview protocol's parsers) or the IR types alone; the helpers are only in `@lincyaw/kernel`.
19
19
  - `@lincyaw/kernel/reading`: plain functions that read a compiled document, the IR (`chapters`, `blockText`, `narrationAt`, `tokenize`); they do no I/O.
20
20
  - `@lincyaw/kernel/node`: helpers for Node code: `copyPublished` and `isInside` (its other exports are internal).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lincyaw/kernel",
3
- "version": "1.0.0-rc.5",
3
+ "version": "1.0.0-rc.50",
4
4
  "description": "Presmium's shared kernel: the IR and plugin contracts, the service registry, anchors and checks",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -15,6 +15,7 @@
15
15
  "ir"
16
16
  ],
17
17
  "type": "module",
18
+ "sideEffects": false,
18
19
  "engines": {
19
20
  "node": ">=22.19"
20
21
  },
@@ -39,6 +40,7 @@
39
40
  "json-schema-library": "11.6.16",
40
41
  "parse5": "7.3.0",
41
42
  "semver": "^7.8.5",
42
- "proper-lockfile": "4.1.2"
43
+ "proper-lockfile": "4.1.2",
44
+ "resolve.exports": "2.0.4"
43
45
  }
44
46
  }
@@ -8,7 +8,7 @@ import type { DocumentChangePlan } from './authoring.ts'
8
8
 
9
9
  export const DOCUMENT_ACTION_MAX_REQUEST_CHARS = 4096
10
10
  export const DOCUMENT_ACTION_MAX_RESPONSE_CHARS = 7168
11
- export const DOCUMENT_AUTHORING_ACTION_TYPES = ['comment.create', 'comment.reply', 'comment.update', 'comment.react', 'comment.resolve', 'comment.reopen', 'comment.delete', 'voice.set', 'component.parameters.patch', 'component.step-parameters.patch', 'component.step-parameters.reset', 'component.definition.use', 'caption.timing.set', 'caption.timing.reset'] as const
11
+ export const DOCUMENT_AUTHORING_ACTION_TYPES = ['comment.create', 'comment.reply', 'comment.update', 'comment.react', 'comment.resolve', 'comment.reopen', 'comment.delete', 'voice.set', 'component.parameters.patch', 'component.step-parameters.patch', 'component.step-parameters.reset', 'component.definition.use', 'caption.timing.set', 'caption.timing.reset', 'caption.scale.set', 'production.enable'] as const
12
12
  export const DOCUMENT_PARAMETER_MAX_CHANGES = 32
13
13
  export const DOCUMENT_PARAMETER_MAX_PATH_DEPTH = 16
14
14
  /** Paths belong only to this component's parameters; set replaces an array item or appends at its length. */
@@ -39,9 +39,9 @@ export interface DocumentComponentImpactAnswer {
39
39
  collection: DocumentComponentImpactCollection, offset: number, total: number, entries: string[], nextOffset?: number, complete: boolean
40
40
  }
41
41
  /** New recording adoption belongs to the real-media service, never a raw settings action. */
42
- export type DocumentAuthoringAction = DocumentCommentAction | DocumentComponentAction | DocumentCaptionTimingAction | { type: 'voice.set', scope: DocumentVoiceScope, source: Exclude<VoiceSource, { type: 'recording' }> | null, replaceOverrides?: boolean }
42
+ export type DocumentAuthoringAction = DocumentCommentAction | DocumentComponentAction | DocumentCaptionTimingAction | { type: 'production.enable' } | { type: 'caption.scale.set', scale: number } | { type: 'voice.set', scope: DocumentVoiceScope, source: Exclude<VoiceSource, { type: 'recording' }> | null, replaceOverrides?: boolean }
43
43
  export interface DocumentAuthoringActionRequest { id: string, source: CanonicalSource, action: DocumentAuthoringAction }
44
- export type DocumentAuthoringActionEffect = { kind: 'caption', value: { stepId: string, segments: number, changed: boolean, mode: 'manual' | 'automatic' } } | { kind: 'comment', value: DocumentCommentEffect } | { kind: 'voice', scope: DocumentVoiceScope['kind'], value: DocumentVoiceImpact, recordings: { preserved: number, removed: number } } | { kind: 'component', value: DocumentComponentEffect }
44
+ export type DocumentAuthoringActionEffect = { kind: 'production', value: { enabled: true, changed: boolean } } | { kind: 'caption-scale', value: { scale: number, changed: boolean } } | { kind: 'caption', value: { stepId: string, segments: number, changed: boolean, mode: 'manual' | 'automatic' } } | { kind: 'comment', value: DocumentCommentEffect } | { kind: 'voice', scope: DocumentVoiceScope['kind'], value: DocumentVoiceImpact, recordings: { preserved: number, removed: number } } | { kind: 'component', value: DocumentComponentEffect }
45
45
  export interface DocumentAuthoringActionPlan extends DocumentChangePlan {
46
46
  action: DocumentAuthoringAction
47
47
  effect: DocumentAuthoringActionEffect
@@ -12,16 +12,31 @@ export const AUTHORING_CLIENT_MAX_REQUESTS = 64
12
12
  export const AUTHORING_CLIENT_REQUEST_TIMEOUT_MS = 30000
13
13
  export const AUTHORING_CLIENT_ACK_MAX_BYTES = 32768
14
14
  export const AUTHORING_CLIENT_EVENT_MAX_BYTES = 8 << 10
15
- export const AUTHORING_CLIENT_ACTIONS = ['state.read', 'source.flush', 'preview.prepare', 'comment-drafts.inspect', 'comment-drafts.read', 'comment-drafts.restore', 'comment-drafts.discard', 'component-drafts.inspect', 'component-drafts.read', 'component-drafts.restore', 'component-drafts.discard', 'playback.pause', 'position.step', 'playback.play', 'playback.seek', 'playback.rate'] as const
15
+ export const AUTHORING_CLIENT_ACTIONS = ['state.read', 'source.flush', 'preview.prepare', 'view.set', 'native-history.undo', 'native-history.redo', 'recording.start', 'recording.stop', 'recording.cancel', 'recording.discard', 'recording.save', 'recording.listen', 'recording.pause', 'comment-drafts.inspect', 'comment-drafts.read', 'comment-drafts.restore', 'comment-drafts.discard', 'body-drafts.inspect', 'body-drafts.read', 'body-drafts.restore', 'body-drafts.discard', 'body-drafts.retry', 'component-drafts.inspect', 'component-drafts.read', 'component-drafts.restore', 'component-drafts.discard', 'playback.pause', 'position.step', 'playback.play', 'playback.seek', 'playback.rate'] as const
16
16
  export type AuthoringClientActionType = typeof AUTHORING_CLIENT_ACTIONS[number]
17
+ export type AuthoringClientView = 'document' | 'reading' | 'presentation' | 'production'
18
+ /** Browser-owned actions that may write the saved source of the same document. */
19
+ export const authoringClientActionChangesSource = (type: AuthoringClientActionType): boolean => ['source.flush', 'native-history.undo', 'native-history.redo', 'recording.save', 'body-drafts.retry'].includes(type)
20
+ /** Local backup operations retain lease/input checks without requiring a readable current source. */
21
+ export const authoringClientActionUsesLocalDraft = (type: AuthoringClientActionType): boolean => ['body-drafts.inspect', 'body-drafts.read', 'body-drafts.restore', 'body-drafts.discard'].includes(type)
22
+ export const authoringClientActionMutatesDraft = (type: AuthoringClientActionType): boolean => ['comment-drafts.restore', 'comment-drafts.discard', 'component-drafts.restore', 'component-drafts.discard', 'body-drafts.restore', 'body-drafts.discard', 'body-drafts.retry'].includes(type)
17
23
  export type AuthoringClientAction =
18
24
  | { type: 'state.read' }
19
25
  | { type: 'source.flush' }
20
26
  | { type: 'preview.prepare' }
27
+ | { type: 'view.set', view: AuthoringClientView }
28
+ | { type: 'native-history.undo' | 'native-history.redo' }
29
+ | { type: 'recording.start' | 'recording.stop' | 'recording.cancel' | 'recording.save' | 'recording.listen' | 'recording.pause' }
30
+ | { type: 'recording.discard', confirm: true }
21
31
  | { type: 'comment-drafts.inspect', cursor?: { after: string, token: string }, limit?: number }
22
32
  | { type: 'comment-drafts.read', draft: ClientCommentDraftReference, offset: number, maxChars?: number }
23
33
  | { type: 'comment-drafts.restore', draft: ClientCommentDraftReference, composerId: string, expectedCurrent: ClientCommentDraftReference | null }
24
34
  | { type: 'comment-drafts.discard', draft: ClientCommentDraftReference }
35
+ | { type: 'body-drafts.inspect', cursor?: { after: string, token: string }, limit?: number }
36
+ | { type: 'body-drafts.read', draft: ClientBodyDraftReference, offset: number, maxChars?: number }
37
+ | { type: 'body-drafts.restore', draft: ClientBodyDraftReference }
38
+ | { type: 'body-drafts.discard', draft: ClientBodyDraftReference, confirm: true }
39
+ | { type: 'body-drafts.retry', draft: ClientBodyDraftReference }
25
40
  | { type: 'component-drafts.inspect', cursor?: { after: string, token: string }, limit?: number }
26
41
  | { type: 'component-drafts.read', draft: ClientComponentDraftReference, offset: number, maxChars?: number }
27
42
  | { type: 'component-drafts.restore', draft: ClientComponentDraftReference, expectedCurrent: ClientComponentDraftReference | null }
@@ -32,6 +47,19 @@ export type AuthoringClientAction =
32
47
  | { type: 'playback.seek', binding: ProductionBinding, timeMs: number }
33
48
  | { type: 'playback.rate', binding: ProductionBinding, rate: number }
34
49
 
50
+ /** Opaque exact-branch reference resolved only by the native document actor. */
51
+ export type ClientBodyDraftReference = string
52
+ export interface ClientBodyDraftMetadata {
53
+ draft: ClientBodyDraftReference
54
+ current: boolean
55
+ storage: 'durable' | 'rescue' | 'session'
56
+ updatedAt: number
57
+ baseVersion: string
58
+ /** Matches the browser's last observed saved version; does not assert server freshness. */
59
+ baseObserved: boolean
60
+ composing: boolean
61
+ pendingSubmission: boolean
62
+ }
35
63
  export interface ClientCommentDraftReference { id: string, revision: number, token: string }
36
64
  export interface ClientComponentDraftReference { id: string, revision: number, token: string, blockId: string, stepId?: string }
37
65
  /** No parameter values, baselines, workspace identity or member IDs enter this metadata. */
@@ -64,6 +92,11 @@ export interface ClientCommentDraftMetadata {
64
92
  commentId?: string
65
93
  }
66
94
  export type AuthoringClientActionResult =
95
+ | { type: 'body-drafts.inspect', family: 'body', coverage: 'stored-and-session' | 'partial', token: string, drafts: ClientBodyDraftMetadata[], next?: { after: string, token: string } }
96
+ | { type: 'body-drafts.read', family: 'body', draft: ClientBodyDraftReference, storage: 'durable' | 'rescue' | 'session', format: 'presmium-document-json-v1', offset: number, endOffset: number, totalUtf16: number, totalUtf8: number, sha256: string, jsonText: string }
97
+ | { type: 'body-drafts.restore' | 'body-drafts.discard' | 'body-drafts.retry', family: 'body', draft: ClientBodyDraftReference,
98
+ outcome: 'restored' | 'already-saved' | 'source-restored' | 'backup-discarded' | 'saved', dirty: boolean, conflicted: boolean, backupPending?: true, backupRetained?: true }
99
+
67
100
  | { type: 'comment-drafts.inspect', family: 'comment', coverage: 'stored-and-session' | 'session-only', skippedInvalid: number, token: string, drafts: ClientCommentDraftMetadata[], next?: { after: string, token: string } }
68
101
  | { type: 'comment-drafts.read', family: 'comment', draft: ClientCommentDraftReference, storage: 'durable' | 'session', format: 'presmium-rich-text-json-v1', offset: number, endOffset: number, totalUtf16: number, totalUtf8: number, sha256: string, jsonText: string }
69
102
  | { type: 'comment-drafts.restore', family: 'comment', draft: ClientCommentDraftReference, composerId: string, restored: ClientCommentDraftReference, preservedCurrent: ClientCommentDraftReference | null, targetState: 'current' | 'changed' }
@@ -78,6 +111,8 @@ export interface AuthoringClientSnapshot {
78
111
  revision: number
79
112
  source: CanonicalSource
80
113
  view: 'document' | 'present'
114
+ mode?: AuthoringClientView
115
+ recording?: { phase: 'idle' | 'requesting' | 'recording' | 'stopping' | 'ready' | 'failed', elapsedMs: number, candidate?: { byteLength: number, mime: string, assetId?: string }, error?: string, audition?: 'idle' | 'loading' | 'playing' | 'failed' }
81
116
  editing: { dirty: boolean, saving: boolean, composing: boolean, conflicted: boolean, locked: boolean, loading: boolean }
82
117
  interaction: string
83
118
  position?: { sectionId: string, stepId?: string }
@@ -97,6 +132,7 @@ export interface AuthoringClientDescriptor extends AuthoringClientConnection {
97
132
  observedAt: string
98
133
  verification: 'reported-state'
99
134
  snapshot: AuthoringClientSnapshot
135
+ pendingRequest?: { requestId: string, action: AuthoringClientActionType, cancellationRequested?: true }
100
136
  }
101
137
  export interface AuthoringClientList { document: string, clients: AuthoringClientDescriptor[], nextAfter?: string, unavailable: readonly string[] }
102
138
  export interface AuthoringClientRequest {
@@ -114,6 +150,7 @@ export interface AuthoringClientRequestResult extends AuthoringClientConnection
114
150
  action: AuthoringClientActionType
115
151
  source: CanonicalSource
116
152
  state: AuthoringClientRequestState
153
+ cancellationRequested?: true
117
154
  admittedAt: string
118
155
  expiresAt: string
119
156
  observedAt?: string
@@ -138,6 +175,7 @@ export interface AuthoringClients {
138
175
  list(document: string, query: { clientId?: string, after?: string }, member: Member): Promise<AuthoringClientList>
139
176
  request(document: string, request: AuthoringClientRequest, member: Member): Promise<AuthoringClientRequestResult>
140
177
  get(document: string, query: { clientId: string, epoch: string, requestId: string }, member: Member): Promise<AuthoringClientRequestResult>
178
+ cancel?(document: string, query: { clientId: string, epoch: string, requestId: string }, member: Member): Promise<AuthoringClientRequestResult>
141
179
  }
142
180
 
143
181
  /** Reserve the complete receipt and the host-only lease, rather than budgeting only the text fragment. */
@@ -163,6 +201,8 @@ const bool: Schema = { type: 'boolean' }
163
201
  const object = (properties: Record<string, Schema>, required = Object.keys(properties)): Schema => ({ type: 'object', additionalProperties: false, properties, required })
164
202
  const digest: Schema = { type: 'string', pattern: '^[a-f0-9]{64}$' }
165
203
  const draftReference = object({ id: entity, revision: { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER }, token: digest })
204
+ const bodyDraftReference = digest
205
+ const bodyMetadata = object({ draft: bodyDraftReference, current: bool, storage: { enum: ['durable', 'rescue', 'session'] }, updatedAt: integer, baseVersion: entity, baseObserved: bool, composing: bool, pendingSubmission: bool })
166
206
  const componentDraftReference = object({ id: entity, revision: { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER }, token: digest, blockId: entity, stepId: entity }, ['id', 'revision', 'token', 'blockId'])
167
207
  const componentMetadata = object({ draft: componentDraftReference, definitionId: entity, current: bool, storage: { enum: ['durable', 'session'] }, status: { enum: ['available', 'pending', 'session-only'] }, updatedAt: integer, baseVersion: entity, sourceCurrent: bool, composing: bool, reset: bool })
168
208
  const nullableComponentReference: Schema = { oneOf: [componentDraftReference, { type: 'null' }] }
@@ -170,6 +210,11 @@ const nullableCommentReference: Schema = { oneOf: [draftReference, { type: 'null
170
210
  const commentRestore = object({ composerId: id, expectedCurrent: nullableCommentReference })
171
211
  const cursor = object({ after: entity, token: digest })
172
212
  export const AUTHORING_CLIENT_ACTION_RESULT_SCHEMA: Schema = { oneOf: [
213
+ object({ type: { const: 'body-drafts.inspect' }, family: { const: 'body' }, coverage: { enum: ['stored-and-session', 'partial'] }, token: digest,
214
+ drafts: { type: 'array', maxItems: 10, items: bodyMetadata }, next: cursor }, ['type', 'family', 'coverage', 'token', 'drafts']),
215
+ object({ type: { const: 'body-drafts.read' }, family: { const: 'body' }, draft: bodyDraftReference, storage: { enum: ['durable', 'rescue', 'session'] }, format: { const: 'presmium-document-json-v1' }, offset: integer, endOffset: integer, totalUtf16: integer, totalUtf8: integer, sha256: digest, jsonText: { type: 'string', maxLength: 2048 } }),
216
+ object({ type: { enum: ['body-drafts.restore', 'body-drafts.discard', 'body-drafts.retry'] }, family: { const: 'body' }, draft: bodyDraftReference,
217
+ outcome: { enum: ['restored', 'already-saved', 'source-restored', 'backup-discarded', 'saved'] }, dirty: bool, conflicted: bool, backupPending: { const: true }, backupRetained: { const: true } }, ['type', 'family', 'draft', 'outcome', 'dirty', 'conflicted']),
173
218
  object({ type: { const: 'comment-drafts.inspect' }, family: { const: 'comment' }, coverage: { enum: ['stored-and-session', 'session-only'] }, skippedInvalid: integer,
174
219
  token: digest, drafts: { type: 'array', maxItems: 10, items: object({ draft: draftReference, kind: { enum: ['create', 'reply', 'edit'] }, storage: { enum: ['durable', 'session'] }, updatedAt: integer, baseVersion: entity, composing: bool, pendingSubmission: bool, ownersKnown: bool, active: bool, discardable: bool, restore: commentRestore, threadId: entity, commentId: entity }, ['draft', 'kind', 'storage', 'updatedAt', 'baseVersion', 'composing', 'pendingSubmission', 'ownersKnown', 'active', 'discardable']) }, next: cursor }, ['type', 'family', 'coverage', 'skippedInvalid', 'token', 'drafts']),
175
220
  object({ type: { const: 'comment-drafts.read' }, family: { const: 'comment' }, draft: draftReference, storage: { enum: ['durable', 'session'] }, format: { const: 'presmium-rich-text-json-v1' }, offset: integer, endOffset: integer, totalUtf16: integer, totalUtf8: integer, sha256: digest, jsonText: { type: 'string', maxLength: 2048 } }),
@@ -187,6 +232,10 @@ const position = object({ timeMs: number, stepTimeMs: number, sectionId: entity,
187
232
  const playback = object({ binding, status: { enum: ['loading', 'ready', 'estimated', 'unavailable', 'failed'] }, position, error: { type: 'string', maxLength: 300 } }, ['binding', 'status'])
188
233
  export const AUTHORING_CLIENT_SNAPSHOT_SCHEMA: Schema = object({
189
234
  revision: integer, source, view: { enum: ['document', 'present'] }, editing: object({ dirty: bool, saving: bool, composing: bool, conflicted: bool, locked: bool, loading: bool }),
235
+ mode: { enum: ['document', 'reading', 'presentation', 'production'] },
236
+ recording: object({ phase: { enum: ['idle', 'requesting', 'recording', 'stopping', 'ready', 'failed'] }, elapsedMs: number,
237
+ candidate: object({ byteLength: integer, mime: { type: 'string', maxLength: 200 }, assetId: entity }, ['byteLength', 'mime']),
238
+ error: entity, audition: { enum: ['idle', 'loading', 'playing', 'failed'] } }, ['phase', 'elapsedMs']),
190
239
  interaction: { type: 'string', maxLength: 200 }, position: object({ sectionId: entity, stepId: entity }, ['sectionId']), binding, playback,
191
240
  preview: { oneOf: [object({ status: { enum: ['unprepared', 'preparing', 'unavailable'] } }), object({ status: { const: 'prepared' }, source, irRevision: entity, projectRevision: integer })] },
192
241
  actions: { type: 'array', items: { enum: [...AUTHORING_CLIENT_ACTIONS] }, maxItems: AUTHORING_CLIENT_ACTIONS.length, uniqueItems: true }, unsubmittedContent: { const: 'not-inspected' },
@@ -194,10 +243,18 @@ export const AUTHORING_CLIENT_SNAPSHOT_SCHEMA: Schema = object({
194
243
  const action = (type: string, properties: Record<string, Schema> = {}): Schema => object({ type: { const: type }, ...properties })
195
244
  export const AUTHORING_CLIENT_ACTION_SCHEMA: Schema = { oneOf: [
196
245
  action('state.read'), action('source.flush'), action('preview.prepare'), action('playback.pause'), action('position.step', { sectionId: entity, stepId: entity }),
246
+ action('view.set', { view: { enum: ['document', 'reading', 'presentation', 'production'] } }),
247
+ ...['native-history.undo', 'native-history.redo', 'recording.start', 'recording.stop', 'recording.cancel', 'recording.save', 'recording.listen', 'recording.pause'].map(type => action(type)),
248
+ action('recording.discard', { confirm: { const: true } }),
197
249
  object({ type: { const: 'comment-drafts.inspect' }, cursor, limit: { type: 'integer', minimum: 1, maximum: 10 } }, ['type']),
198
250
  object({ type: { const: 'comment-drafts.read' }, draft: draftReference, offset: integer, maxChars: { type: 'integer', minimum: 2, maximum: 2048 } }, ['type', 'draft', 'offset']),
199
251
  action('comment-drafts.restore', { draft: draftReference, composerId: id, expectedCurrent: nullableCommentReference }),
200
252
  action('comment-drafts.discard', { draft: draftReference }),
253
+ object({ type: { const: 'body-drafts.inspect' }, cursor, limit: { type: 'integer', minimum: 1, maximum: 10 } }, ['type']),
254
+ object({ type: { const: 'body-drafts.read' }, draft: bodyDraftReference, offset: integer, maxChars: { type: 'integer', minimum: 2, maximum: 2048 } }, ['type', 'draft', 'offset']),
255
+ action('body-drafts.restore', { draft: bodyDraftReference }),
256
+ action('body-drafts.discard', { draft: bodyDraftReference, confirm: { const: true } }),
257
+ action('body-drafts.retry', { draft: bodyDraftReference }),
201
258
  object({ type: { const: 'component-drafts.inspect' }, cursor, limit: { type: 'integer', minimum: 1, maximum: 10 } }, ['type']),
202
259
  object({ type: { const: 'component-drafts.read' }, draft: componentDraftReference, offset: integer, maxChars: { type: 'integer', minimum: 2, maximum: 2048 } }, ['type', 'draft', 'offset']),
203
260
  action('component-drafts.restore', { draft: componentDraftReference, expectedCurrent: nullableComponentReference }),
@@ -0,0 +1,148 @@
1
+ /**
2
+ * Pictures of a document as its presentation shows it, taken by the workspace service in a headless browser: the rest
3
+ * frame of each step, or a moment into a step's animation, with the boxes of the elements an agent asks about. Agents
4
+ * (over MCP) check animations and layout with it instead of scripting a browser.
5
+ */
6
+
7
+ /** At most this many pictures a request: each is one image in a tool result. */
8
+ export const CAPTURE_MAX_FRAMES = 12
9
+ /** At most this many boxes a picture reports for `measure`. */
10
+ export const CAPTURE_MAX_BOXES = 200
11
+
12
+ export interface SlideCaptureRequest {
13
+ /** The page (section) id, or its number from 1. */
14
+ section: string
15
+ /** The steps to show, from 0; every step of the page when omitted. */
16
+ steps?: number[]
17
+ /** Milliseconds into each step's animation; each step's rest frame (its final state) when omitted. */
18
+ at?: number[]
19
+ appearance?: 'light' | 'dark'
20
+ /** Device pixels per slide pixel. */
21
+ scale?: 1 | 2
22
+ /** A region of the slide, in slide pixels. */
23
+ clip?: { x: number, y: number, width: number, height: number }
24
+ /** A CSS selector: the boxes of the matching elements in the slide are reported, in slide pixels. */
25
+ measure?: string
26
+ /**
27
+ * How the presentation reaches each step: `direct` (default) draws it from its step and moment; `backward` shows the
28
+ * step after it first and goes back as a presenter does, with the page's own clock, to check that going back works.
29
+ */
30
+ arrive?: 'direct' | 'backward'
31
+ /** Draw the presentation's captions over the slide (default true); false shows the whole slide, the narration being in `narration`. */
32
+ captions?: boolean
33
+ }
34
+
35
+ export interface ReadingCaptureRequest {
36
+ /** The page (section) id, or its number from 1. */
37
+ section: string
38
+ /** The window's width in CSS pixels (default 1280; 390 for a phone). */
39
+ width?: number
40
+ appearance?: 'light' | 'dark'
41
+ /** Device pixels per CSS pixel. */
42
+ scale?: 1 | 2
43
+ /** A CSS selector: the boxes of the matching elements in the page's section are reported, in CSS pixels. */
44
+ measure?: string
45
+ }
46
+
47
+ export interface CapturedReading {
48
+ section: string
49
+ /** The PNG file of the picture, in the service's state directory. */
50
+ file: string
51
+ /** The section's size in CSS pixels; the picture is cut at `CAPTURE_MAX_HEIGHT`. */
52
+ width: number
53
+ height: number
54
+ cut: boolean
55
+ boxes?: CapturedBox[]
56
+ }
57
+
58
+ export interface ReadingCaptureResult {
59
+ document: string
60
+ width: number
61
+ frames: CapturedReading[]
62
+ problems: string[]
63
+ }
64
+
65
+ /** The tallest picture of a reading page's section, in CSS pixels. */
66
+ export const CAPTURE_MAX_HEIGHT = 8000
67
+
68
+ export interface CapturedBox {
69
+ x: number
70
+ y: number
71
+ width: number
72
+ height: number
73
+ visible: boolean
74
+ /** The start of the element's text. */
75
+ text: string
76
+ /** Its `id`, `class` and `data-*` attributes. */
77
+ attributes: Record<string, string>
78
+ }
79
+
80
+ export interface CapturedSlide {
81
+ section: string
82
+ slide: number
83
+ step: number
84
+ /** Milliseconds into the step, or null for its rest frame. */
85
+ at: number | null
86
+ /** The step's narration (its script), as text: what the captions show. */
87
+ narration: string
88
+ /** The PNG file of the picture, in the service's state directory. */
89
+ file: string
90
+ width: number
91
+ height: number
92
+ boxes?: CapturedBox[]
93
+ }
94
+
95
+ export interface SlideCaptureResult {
96
+ document: string
97
+ /** The slide's size in slide pixels. */
98
+ shape: { width: number, height: number }
99
+ frames: CapturedSlide[]
100
+ /** What failed in the page while it was drawn: component errors, page errors. */
101
+ problems: string[]
102
+ }
103
+
104
+ export interface OverviewCaptureRequest {
105
+ /** Each page's last step (default), or every step of every page. */
106
+ steps?: 'last' | 'all'
107
+ appearance?: 'light' | 'dark'
108
+ /** Thumbnails a row on a sheet (default 4). */
109
+ columns?: number
110
+ /** Draw the presentation's captions over the slides (default true). */
111
+ captions?: boolean
112
+ }
113
+
114
+ export interface OverviewCaptureResult {
115
+ document: string
116
+ /** The directory of the pictures, named so that they sort in reading order (`03-12-page.png`: page 3, step 12 from 0). */
117
+ dir: string
118
+ frames: { section: string, slide: number, step: number, file: string, narration: string }[]
119
+ /** `narration.md` beside the pictures: each picture's narration under its file name. */
120
+ narrationFile: string
121
+ /** Sheets of thumbnails, at most `CAPTURE_SHEET_SIZE` each, in order. */
122
+ sheets: string[]
123
+ problems: string[]
124
+ }
125
+
126
+ /** Thumbnails on one overview sheet; and the most pictures an overview takes. */
127
+ export const CAPTURE_SHEET_SIZE = 20
128
+ export const CAPTURE_MAX_OVERVIEW = 400
129
+
130
+ export interface DocumentCapture {
131
+ /** The pictures, with their PNG bytes in the order of `frames`. */
132
+ slides(document: string, request: SlideCaptureRequest, signal?: AbortSignal): Promise<SlideCaptureResult & { images: Uint8Array[] }>
133
+ /** A page of the reading version (the web page), with its PNG bytes. */
134
+ reading(document: string, request: ReadingCaptureRequest, signal?: AbortSignal): Promise<ReadingCaptureResult & { images: Uint8Array[] }>
135
+ /** Every page's rest frames as the presentation shows them, as files and as sheets of thumbnails (the images). */
136
+ overview(document: string, request: OverviewCaptureRequest, signal?: AbortSignal): Promise<OverviewCaptureResult & { images: Uint8Array[] }>
137
+ }
138
+
139
+ /** The hook a viewer page opened with `?capture` installs, which the capturing browser drives. */
140
+ export interface CaptureHook {
141
+ /** A slide at a step: drawn at the moment `at` (its rest frame when omitted), or reached going back from the step after. */
142
+ show(position: { section: string, step: number, at?: number, arrive?: 'direct' | 'backward' }): Promise<{ problems: string[] }>
143
+ /** A section of the reading page, scrolled through so that its components load, at rest. */
144
+ read(section: string): Promise<{ problems: string[] }>
145
+ }
146
+
147
+ export const CAPTURE_HOOK = 'presmiumCapture'
148
+ export const CAPTURE_PARAM = 'capture'
@@ -1,7 +1,8 @@
1
1
  import type { CanonicalSource } from '../ir.ts'
2
+ import type { Schema } from '@cfworker/json-schema'
2
3
  import type { Finding } from './checks.ts'
3
4
  import type { Member } from './server.ts'
4
- import type { SpeechEngineInfo } from './speech.ts'
5
+ import type { SpeechEngineInfo, VoiceCloneRequest, VoiceCloneStatus } from './speech.ts'
5
6
  import type { VoiceCatalogAnswer, VoiceoverCancellation } from './voice.ts'
6
7
  import type { DocumentVoiceTasks, VoiceoverJobQuery, VoiceoverStart, VoicePreviewStart } from './voiceover-execution.ts'
7
8
 
@@ -16,13 +17,29 @@ export interface DocumentVoiceCapabilities {
16
17
  preview: boolean
17
18
  engines: SpeechEngineInfo[]
18
19
  defaultEngine?: string
19
- actions: { status: boolean, list: true, get: true, start: boolean, cancel: true, quotePreview: boolean, preview: boolean, readPreview: true }
20
+ actions: { status: boolean, list: true, get: true, start: boolean, cancel: true, quotePreview: boolean, preview: boolean, readPreview: true, clone?: boolean, cloneStatus?: boolean }
20
21
  tasks: { idempotency: 'process', limits: { intents: number, recentJobs: number, concurrent: number, quotes: number, quoteLifetimeMs: number, previewBytes: number, previewResources: number, retainedPreviewBytes: number } }
21
22
  findings?: Finding[]
22
23
  }
23
24
  export interface DocumentVoiceCatalogQuery { source?: CanonicalSource, engine?: string, lang?: string }
24
25
  export interface DocumentVoiceCatalogAnswer extends VoiceCatalogAnswer { document: string, source: CanonicalSource, findings?: Finding[] }
25
26
 
27
+ export const VOICE_CLONE_MAX_AUDIO_BYTES = 10 << 20
28
+ /** Files are scoped workspace paths; the service reads and fixes their bytes before spending approval. */
29
+ export type DocumentVoiceCloneRequest = Omit<VoiceCloneRequest, 'sample' | 'consent'> & {
30
+ source?: CanonicalSource
31
+ sample: string
32
+ consent: { speaker: string, scope: string, statement: string }
33
+ }
34
+ export interface DocumentVoiceCloneQuery { engine?: string, voice: string }
35
+ /** A process-local capability for this call, never a model argument or a retained plan. */
36
+ export interface PreparedVoiceClone {
37
+ engine: string
38
+ voice: string
39
+ start(signal?: AbortSignal): Promise<VoiceCloneStatus>
40
+ close(): void
41
+ }
42
+
26
43
  /** Shared voice discovery and explicitly authorized tasks; discovery never compiles or synthesizes. */
27
44
  export interface DocumentVoiceAuthoring extends DocumentVoiceTasks {
28
45
  capabilities(document: string, member: Member, signal?: AbortSignal): Promise<DocumentVoiceCapabilities>
@@ -32,6 +49,8 @@ export interface DocumentVoiceAuthoring extends DocumentVoiceTasks {
32
49
  checkPreview(document: string, request: VoicePreviewStart, member: Member, signal?: AbortSignal): Promise<void>
33
50
  /** Undefined when there is something to cancel; otherwise the unchanged state that cancel would report. */
34
51
  checkCancel(document: string, query: VoiceoverJobQuery, member: Member): Promise<VoiceoverCancellation | undefined>
52
+ prepareClone?(document: string, request: DocumentVoiceCloneRequest, member: Member, signal?: AbortSignal): Promise<PreparedVoiceClone>
53
+ cloneStatus?(document: string, query: DocumentVoiceCloneQuery, member: Member, signal?: AbortSignal): Promise<VoiceCloneStatus>
35
54
  }
36
55
 
37
56
  export const DOCUMENT_VOICE_CATALOG_SCHEMA = {
@@ -42,3 +61,17 @@ export const DOCUMENT_VOICE_CATALOG_SCHEMA = {
42
61
  lang: { type: 'string', minLength: 1, maxLength: 100 },
43
62
  },
44
63
  } as const
64
+
65
+ const cloneText = { type: 'string', minLength: 1, maxLength: 200 } as const
66
+ export const DOCUMENT_VOICE_CLONE_QUERY_SCHEMA: Schema = {
67
+ type: 'object', additionalProperties: false, properties: { engine: cloneText, voice: cloneText }, required: ['voice'],
68
+ }
69
+ export const DOCUMENT_VOICE_CLONE_SCHEMA: Schema = {
70
+ type: 'object', additionalProperties: false,
71
+ properties: {
72
+ source: structuredClone(DOCUMENT_VOICE_CATALOG_SCHEMA.properties.source) as unknown as Schema, engine: cloneText, voice: cloneText,
73
+ sample: { type: 'string', minLength: 1, maxLength: 1024 },
74
+ consent: { type: 'object', additionalProperties: false, properties: { speaker: cloneText, scope: { type: 'string', minLength: 1, maxLength: 2000 }, statement: { type: 'string', minLength: 1, maxLength: 1024 } }, required: ['speaker', 'scope', 'statement'] },
75
+ lang: { type: 'string', minLength: 1, maxLength: 100 }, text: { type: 'string', maxLength: 4000 },
76
+ }, required: ['voice', 'sample', 'consent'],
77
+ }
@@ -194,11 +194,24 @@ export interface Production {
194
194
  cueTimings?: Record<string, { pauseMs: number }>
195
195
  /** Stale mappings remain inspectable but never retime audio or replace changed narration. */
196
196
  captionTimings?: Record<StepId, CaptionTiming>
197
+ /** How large the captions are, in the presentation and burned into a lecture video; absent is the default size. */
198
+ captions?: CaptionStyle
197
199
  mediaClips: MediaClip[]
198
200
  }
201
+ /** `scale` multiplies the captions' default size, from `CAPTION_SCALE_MIN` to `CAPTION_SCALE_MAX` (Studio offers tenths). */
202
+ export interface CaptionStyle { scale: number }
203
+ export const CAPTION_SCALE_MIN = 0.7
204
+ export const CAPTION_SCALE_MAX = 1.6
199
205
 
200
206
  /** A stable rich-text/code ID, or `page:${sectionId}` reserved for an existing section title. */
201
207
  export interface DocumentTextPoint { blockId: string, offset: number }
208
+ export interface DocumentTextAnchor { from: DocumentTextPoint, to: DocumentTextPoint }
209
+ /** A stable block, optionally at one step that renders it; the step belongs to the block's section. */
210
+ export interface DocumentPlaceAnchor { blockId: BlockId, stepId?: StepId }
211
+ export type DocumentThreadAnchor = DocumentTextAnchor | DocumentPlaceAnchor
212
+ /** A text range and a place are disjoint shapes; read the shape instead of guessing from offsets. */
213
+ export const isDocumentTextAnchor = (anchor: DocumentThreadAnchor | undefined): anchor is DocumentTextAnchor => Boolean(anchor && 'from' in anchor && 'to' in anchor)
214
+ export const isDocumentPlaceAnchor = (anchor: DocumentThreadAnchor | undefined): anchor is DocumentPlaceAnchor => Boolean(anchor && 'blockId' in anchor && !('from' in anchor))
202
215
  export interface DocumentComment {
203
216
  id: string
204
217
  type: 'comment'
@@ -220,7 +233,7 @@ export interface DocumentThread {
220
233
  resolvedBy?: string
221
234
  metadata?: JsonObject
222
235
  deletedAt?: string
223
- anchor?: { from: DocumentTextPoint, to: DocumentTextPoint }
236
+ anchor?: DocumentThreadAnchor
224
237
  comments: DocumentComment[]
225
238
  }
226
239
 
@@ -1,4 +1,4 @@
1
- import type { CanonicalSource, DirectiveSpec, IRDocument, IRPass, Renderer, RendererContribution, RoleSpec } from '../ir.ts'
1
+ import type { CanonicalSource, IRDocument, IRPass, Renderer, RendererContribution } from '../ir.ts'
2
2
  import type { AgentTool } from './agent.ts'
3
3
  import type { AnchorResolver, AnchorString } from './anchors.ts'
4
4
  import type { Check, CheckContext } from './checks.ts'
@@ -159,7 +159,6 @@ export interface PresmiumNodePlugin {
159
159
  resolvers?: AnchorResolver[]
160
160
  checks?: Check[]
161
161
  anchors?(ctx: CheckContext): AnchorString[] | Promise<AnchorString[]>
162
- directives?: DirectiveSpec[]
163
162
  passes?: IRPass[]
164
163
  executors?: Executor[]
165
164
  renderer?: Renderer
@@ -177,7 +176,6 @@ export interface PresmiumNodePlugin {
177
176
  services?(ctx: NodeServiceContext): [ServiceToken<unknown>, unknown][]
178
177
  environments?: Record<string, EnvironmentProvider>
179
178
  server?(ctx: ServerContext): ServerContribution | Promise<ServerContribution>
180
- roles?: RoleSpec[]
181
179
  tools?: AgentTool[]
182
180
  operator?: boolean
183
181
  }
@@ -10,6 +10,9 @@ export const PREVIEW_PARAM = 'presmium-preview'
10
10
  /** The workbench's appearance when it loads a preview (`dark` or `light`), so that the page's first paint matches it. */
11
11
  export const PREVIEW_APPEARANCE_PARAM = 'presmium-appearance'
12
12
 
13
+ /** `?captions=off` starts a presentation with its captions off (a reader turns them on again with the captions button). */
14
+ export const CAPTIONS_PARAM = 'captions'
15
+
13
16
  export const PREVIEW_REVISION = 'presmiumRevision'
14
17
 
15
18
  export const AUTHOR_MARKS_CLASS = 'pm-author-marks'
@@ -201,8 +204,6 @@ export type PreviewReport =
201
204
  | { type: 'selection', selection: (PreviewAnchor & { text: string, rect?: PreviewRect, obstacles?: PreviewRect[] }) | null }
202
205
  /** Where the picked block or the selection is after the page scrolled or resized; null when it is out of sight. */
203
206
  | { type: 'rect', rect: PreviewRect | null, obstacles?: PreviewRect[] }
204
- /** Where the blocks the AI changed are in the preview's viewport while they blink, and again as the page scrolls (at most 16). */
205
- | { type: 'flashed', rects: PreviewRect[] }
206
207
  | { type: 'editing', target: PreviewAnchor, active: boolean }
207
208
  /** The text of a block edited in place, before and after (its `textContent`); sent only when it changed. */
208
209
  | { type: 'edited', target: PreviewAnchor, before: string, after: string, request?: number, revision?: string, binding?: string }
@@ -371,7 +372,6 @@ export function toPreviewReport(data: unknown, nonce: string): PreviewReport | u
371
372
  ? { type: 'selection', selection: { ...toAnchor(selected), text: selected.text, ...selected.rect ? { rect: toRect(selected.rect as PreviewRect) } : {}, ...selected.obstacles !== undefined ? { obstacles: (selected.obstacles as PreviewRect[]).map(toRect) } : {} } }
372
373
  : undefined
373
374
  }
374
- case 'flashed': return Array.isArray(m.rects) && m.rects.length <= 16 && m.rects.every(rect) ? { type: 'flashed', rects: (m.rects as PreviewRect[]).map(toRect) } : undefined
375
375
  case 'rect': return (m.rect === null || rect(m.rect)) && optional(m.obstacles, obstacles) ? { type: 'rect', rect: m.rect === null ? null : toRect(m.rect), ...m.obstacles !== undefined ? { obstacles: (m.obstacles as PreviewRect[]).map(toRect) } : {} } : undefined
376
376
  case 'editing': return anchor(m.target) && typeof m.active === 'boolean' ? { type: 'editing', target: toAnchor(m.target), active: m.active } : undefined
377
377
  case 'edited': return anchor(m.target) && text(m.before) && text(m.after) && m.before.length <= MAX_EDITED && m.after.length <= MAX_EDITED && editedRequest(m) ? { type: 'edited', target: toAnchor(m.target), before: m.before, after: m.after, ...m.request === undefined ? {} : { request: m.request as number, revision: m.revision as string, binding: m.binding as string } } : undefined
@@ -10,6 +10,8 @@ export type ProjectOperation = DocumentOperation | { op: 'retitle', dir: string,
10
10
  export interface ProjectCaller { member: Member, origin: 'editor' | 'agent', boundDocument?: string }
11
11
  export interface ProjectObservation { snapshot?: string, configuration: string }
12
12
  export interface ProjectCapabilities {
13
+ templates?: string[]
14
+ nextTemplatesOffset?: number
13
15
  available: boolean
14
16
  actions: Record<ProjectOperation['op'], { available: boolean, reasons: string[] }>
15
17
  reasons: string[]
@@ -45,7 +47,7 @@ export interface ProjectApplied extends OperationAnswer {
45
47
  }
46
48
  /** Directory management borrows the Web writer; metadata retitle borrows canonical document CAS. */
47
49
  export interface ProjectAuthoring {
48
- capabilities(caller: ProjectCaller): Promise<ProjectCapabilities>
50
+ capabilities(caller: ProjectCaller, query?: { templatesOffset?: number }): Promise<ProjectCapabilities>
49
51
  plan(request: ProjectPlanRequest, caller: ProjectCaller): Promise<ProjectPlan>
50
52
  readPlan(request: ProjectApply, caller: ProjectCaller): Promise<ProjectPlan>
51
53
  apply(request: ProjectApply, caller: ProjectCaller, signal?: AbortSignal): Promise<ProjectApplied>
@@ -57,3 +59,4 @@ export const PROJECT_PLAN_SCHEMA = { type: 'object', additionalProperties: false
57
59
  id: text, operation: { oneOf: [operation('create', { title: text, template: text }, []), operation('copy', { to: text, title: text }, ['to']), operation('rename', { to: text }, ['to']), operation('delete', {}, []), operation('retitle', { title: text }, ['title'])] },
58
60
  } } as const
59
61
  export const PROJECT_APPLY_SCHEMA = { type: 'object', additionalProperties: false, required: ['planId', 'digest'], properties: { planId: text, digest: { type: 'string', pattern: '^[a-f0-9]{64}$' }, confirmDeletion: { const: true } } } as const
62
+ export const PROJECT_CAPABILITIES_SCHEMA = { type: 'object', additionalProperties: false, properties: { templatesOffset: { type: 'integer', minimum: 0 } } } as const
@@ -1,3 +1,5 @@
1
+ import type { Schema } from '@cfworker/json-schema'
2
+
1
3
  /** Operator configuration is separate from document voice choices. Secret values are write-only. */
2
4
  export interface SpeechSettingsAnswer {
3
5
  provider: 'volcengine'
@@ -14,3 +16,14 @@ export interface SpeechSettingsAnswer {
14
16
  export type SpeechSettingsChange =
15
17
  | { action: 'save', revision: string, apiKey?: string, appId?: string }
16
18
  | { action: 'clear', revision: string }
19
+
20
+ export interface SpeechSettings {
21
+ read(): SpeechSettingsAnswer
22
+ change(change: SpeechSettingsChange): Promise<SpeechSettingsAnswer>
23
+ }
24
+
25
+ export const SPEECH_SETTINGS_CHANGE_SCHEMA: Schema = {
26
+ type: 'object', additionalProperties: false,
27
+ properties: { action: { enum: ['save', 'clear'] }, revision: { type: 'string', maxLength: 200 }, apiKey: { type: 'string', maxLength: 8192 }, appId: { type: 'string', maxLength: 32 } },
28
+ required: ['action', 'revision'],
29
+ }
@@ -103,6 +103,15 @@ export interface VoiceCloneStatus {
103
103
  message?: string
104
104
  }
105
105
 
106
+ export interface SpeechCachePrune {
107
+ /** Entries some request uses. */
108
+ kept: number
109
+ /** Entries no request uses, with the bytes of their files. */
110
+ unused: { key: string, bytes: number }[]
111
+ /** Whether the unused entries were deleted. */
112
+ removed: boolean
113
+ }
114
+
106
115
  export interface TranscriptionRequest {
107
116
  engine?: string
108
117
  audio: Blob
@@ -124,6 +133,13 @@ export interface SpeechService {
124
133
  cached?(key: string, signal?: AbortSignal): Promise<Synthesis | undefined>
125
134
  alignWords?(key: string, options: { lang: string, transcribe?: boolean }, signal?: AbortSignal): Promise<SpeechWord[] | undefined>
126
135
  pruneLock?(keep: ReadonlySet<string>): Promise<number>
136
+ /**
137
+ * The document's cached audio that no request of `keep` (every sentence the document says) uses: kept is any entry
138
+ * made for the same request under any configuration of the voice service. With `remove`, deletes the unused entries
139
+ * with their alignments and speech lock entries. Throws `speech-prune-engine-unknown` when a request names no engine
140
+ * and no default engine is configured, since its entries cannot be told apart then.
141
+ */
142
+ pruneCache?(keep: readonly SynthesisRequest[], options?: { remove?: boolean, signal?: AbortSignal }): Promise<SpeechCachePrune>
127
143
  transcribe(request: TranscriptionRequest, signal?: AbortSignal): Promise<Transcript>
128
144
  /** Registers the consent, then starts training; only for the document's owner. Absent: the service cannot clone. */
129
145
  cloneVoice?(request: VoiceCloneRequest, signal?: AbortSignal): Promise<VoiceCloneStatus>