@lincyaw/kernel 1.0.0-rc.11 → 1.0.0-rc.111

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 (61) hide show
  1. package/README.md +1 -1
  2. package/package.json +4 -2
  3. package/src/authoring.ts +3 -1
  4. package/src/contracts/agent-activity.ts +18 -0
  5. package/src/contracts/authoring-actions.ts +3 -3
  6. package/src/contracts/authoring-clients.ts +96 -8
  7. package/src/contracts/authoring-windows.ts +47 -0
  8. package/src/contracts/authoring.ts +1 -1
  9. package/src/contracts/capture.ts +174 -0
  10. package/src/contracts/document-audio.ts +8 -6
  11. package/src/contracts/document-image.ts +7 -5
  12. package/src/contracts/document-voice.ts +42 -2
  13. package/src/contracts/document.ts +18 -1
  14. package/src/contracts/media-uploads.ts +28 -0
  15. package/src/contracts/plugin.ts +1 -3
  16. package/src/contracts/preview.ts +3 -3
  17. package/src/contracts/projects.ts +15 -2
  18. package/src/contracts/speech-settings.ts +13 -0
  19. package/src/contracts/speech.ts +16 -0
  20. package/src/contracts/voiceover-execution.ts +25 -1
  21. package/src/contracts/workspace-changes.ts +27 -0
  22. package/src/contracts/workspace-review.ts +39 -0
  23. package/src/contracts/workspace-source.ts +38 -0
  24. package/src/contracts/workspace.ts +16 -0
  25. package/src/contracts.ts +7 -0
  26. package/src/document-authoring-actions.ts +23 -4
  27. package/src/document-caption-scale.ts +17 -0
  28. package/src/document-caption-timings.ts +2 -0
  29. package/src/document-comments.ts +30 -37
  30. package/src/document-components.ts +4 -12
  31. package/src/document-narrations.ts +57 -0
  32. package/src/document-operations.ts +32 -2
  33. package/src/document-pages.ts +8 -1
  34. package/src/document-places.ts +92 -0
  35. package/src/document-schema.ts +4 -4
  36. package/src/document.ts +13 -1
  37. package/src/embed.ts +26 -0
  38. package/src/escape-html.ts +4 -0
  39. package/src/html.ts +1 -4
  40. package/src/index.ts +16 -6
  41. package/src/ir.ts +23 -48
  42. package/src/lower-myst.ts +3 -12
  43. package/src/myst-marks.ts +15 -0
  44. package/src/node/authoring-actions.ts +3 -1
  45. package/src/node/authoring-windows.ts +11 -0
  46. package/src/node/document-voice.ts +6 -2
  47. package/src/node/fonts.ts +6 -3
  48. package/src/node/index.ts +11 -3
  49. package/src/node/operator-speech.ts +4 -0
  50. package/src/node/packages.ts +25 -0
  51. package/src/node/service-lease.ts +34 -0
  52. package/src/node/service-state.ts +67 -0
  53. package/src/node/workspace-changes.ts +7 -0
  54. package/src/node/workspace-review.ts +9 -0
  55. package/src/node/workspace-source.ts +10 -0
  56. package/src/preview-events.ts +6 -4
  57. package/src/preview-frame-connect.ts +1110 -0
  58. package/src/preview-frame.ts +30 -1131
  59. package/src/production-captions.ts +9 -0
  60. package/src/random-uuid.ts +8 -0
  61. 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.11",
3
+ "version": "1.0.0-rc.111",
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
  }
package/src/authoring.ts CHANGED
@@ -28,11 +28,13 @@ export const DOCUMENT_CHANGE_JSON_SCHEMA: Schema = {
28
28
  operation('updateSection', { sectionId: id, title: { type: 'string' }, layout: ref('Layout') }, ['sectionId']),
29
29
  operation('setStepState', { stepId: id, visuals: { type: 'array', items: ref('Visual') }, inherits: id }, ['stepId', 'visuals']),
30
30
  operation('setNarration', { narration: ref('Narration'), stepId: id, index }, ['narration']),
31
+ operation('removeNarration', { stepId: id, narrationId: id }),
32
+ operation('setStepNarrations', { stepId: id, narrationIds: { type: 'array', maxItems: 1000, items: id, uniqueItems: true, description: 'Complete ordered existing narration IDs for this step. Omitted references are removed; entities still used by other steps remain.' } }),
31
33
  operation('setTiming', { stepId: id, sectionId: id, value: ref('StepProduction') }, ['value']),
32
34
  operation('replaceAsset', { asset: ref('Asset') }),
33
35
  ] },
34
36
  DocumentChange: {
35
- ...object({ id, baseDocumentVersion: { type: 'string', minLength: 1, maxLength: 128 }, replacement: ref('TeachingDocument'), operations: { type: 'array', minItems: 1, maxItems: 1000, items: ref('DocumentOperation') }, fileChanges: { type: 'array', maxItems: 15, items: object({ path: { type: 'string', minLength: 1 }, content: { type: 'string' }, base: { type: ['string', 'null'] } }) } }, ['id', 'baseDocumentVersion']),
37
+ ...object({ id, baseDocumentVersion: { type: 'string', minLength: 1, maxLength: 128 }, replacement: ref('TeachingDocument'), operations: { type: 'array', minItems: 1, maxItems: 1000, items: ref('DocumentOperation') }, fileChanges: { type: 'array', maxItems: 15, items: object({ path: { type: 'string', minLength: 1, description: 'Workspace-relative path within the selected document, including its directory prefix. For document papers/re-search, use papers/re-search/scenes/story.ts. Scene implementation paths inside lecture.json are document-relative instead.' }, content: { type: 'string' }, base: { type: ['string', 'null'] } }) } }, ['id', 'baseDocumentVersion']),
36
38
  oneOf: [{ required: ['replacement'], not: { required: ['operations'] } }, { required: ['operations'], not: { required: ['replacement'] } }],
37
39
  },
38
40
  },
@@ -0,0 +1,18 @@
1
+ import type { Member } from './server.ts'
2
+
3
+ export type AgentActivityOperation = 'read' | 'edit' | 'navigate' | 'preview' | 'build' | 'voice' | 'workspace'
4
+ export interface AgentActivityTarget { section?: string, block?: string, step?: string }
5
+ /** Ephemeral UI presence. Never contains tool arguments, document text, credentials or failure details. */
6
+ export interface AgentActivity {
7
+ id: string
8
+ operation: AgentActivityOperation
9
+ document?: string
10
+ targets: AgentActivityTarget[]
11
+ state: 'running' | 'done' | 'failed' | 'cancelled'
12
+ startedAt: number
13
+ finishedAt?: number
14
+ }
15
+ export interface AgentActivitySnapshot { activities: AgentActivity[] }
16
+ export interface AgentActivityObserver {
17
+ begin(input: Pick<AgentActivity, 'operation' | 'document' | 'targets'>, member: Member): (state: Exclude<AgentActivity['state'], 'running'>) => void
18
+ }
@@ -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,26 +12,57 @@ 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', 'production-drafts.inspect', 'production-drafts.read', 'production-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', 'production-drafts.inspect', 'production-drafts.read', 'comment-drafts.inspect', 'comment-drafts.read'].includes(type)
22
+ export const authoringClientActionMutatesDraft = (type: AuthoringClientActionType): boolean => ['production-drafts.discard', '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' }
21
- | { type: 'comment-drafts.inspect', cursor?: { after: string, token: string }, limit?: number }
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 }
31
+ | { type: 'comment-drafts.inspect', cursor?: { after: string, token: string }, limit?: number, details?: boolean }
22
32
  | { type: 'comment-drafts.read', draft: ClientCommentDraftReference, offset: number, maxChars?: number }
23
- | { type: 'comment-drafts.restore', draft: ClientCommentDraftReference, composerId: string, expectedCurrent: ClientCommentDraftReference | null }
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 }
28
43
  | { type: 'component-drafts.discard', draft: ClientComponentDraftReference, current: boolean }
44
+ | { type: 'production-drafts.inspect', cursor?: { after: string, token: string }, limit?: number }
45
+ | { type: 'production-drafts.read', draft: string, offset: number, maxChars?: number }
46
+ | { type: 'production-drafts.discard', draft: string, confirm: true }
29
47
  | { type: 'playback.pause' }
30
48
  | { type: 'position.step', sectionId: string, stepId: string }
31
49
  | { type: 'playback.play', binding: ProductionBinding }
32
50
  | { type: 'playback.seek', binding: ProductionBinding, timeMs: number }
33
51
  | { type: 'playback.rate', binding: ProductionBinding, rate: number }
34
52
 
53
+ /** Opaque exact-branch reference resolved only by the native document actor. */
54
+ export type ClientBodyDraftReference = string
55
+ export interface ClientBodyDraftMetadata {
56
+ draft: ClientBodyDraftReference
57
+ current: boolean
58
+ storage: 'durable' | 'rescue' | 'session'
59
+ updatedAt: number
60
+ baseVersion: string
61
+ /** Matches the browser's last observed saved version; does not assert server freshness. */
62
+ baseObserved: boolean
63
+ composing: boolean
64
+ pendingSubmission: boolean
65
+ }
35
66
  export interface ClientCommentDraftReference { id: string, revision: number, token: string }
36
67
  export interface ClientComponentDraftReference { id: string, revision: number, token: string, blockId: string, stepId?: string }
37
68
  /** No parameter values, baselines, workspace identity or member IDs enter this metadata. */
@@ -60,10 +91,33 @@ export interface ClientCommentDraftMetadata {
60
91
  active: boolean
61
92
  discardable: boolean
62
93
  restore?: { composerId: string, expectedCurrent: ClientCommentDraftReference | null }
94
+ restorable?: true
63
95
  threadId?: string
64
96
  commentId?: string
65
97
  }
98
+ const PRODUCTION_DRAFT_KINDS = ['step-timing', 'caption-timing', 'recording-range', 'voice', 'media-clip', 'transcription'] as const
99
+ export interface ClientProductionDraftMetadata {
100
+ draft: string
101
+ kind: typeof PRODUCTION_DRAFT_KINDS[number]
102
+ stepId: string
103
+ field?: 'minimumHoldMs' | 'trailingPauseMs'
104
+ assetId?: string
105
+ clipId?: string
106
+ targetAvailable: boolean
107
+ requiresReview: boolean
108
+ storage: 'tab' | 'memory'
109
+ discardable: boolean
110
+ }
66
111
  export type AuthoringClientActionResult =
112
+ | { type: 'body-drafts.inspect', family: 'body', coverage: 'stored-and-session' | 'partial', token: string, drafts: ClientBodyDraftMetadata[], next?: { after: string, token: string } }
113
+ | { 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 }
114
+ | { type: 'body-drafts.restore' | 'body-drafts.discard' | 'body-drafts.retry', family: 'body', draft: ClientBodyDraftReference,
115
+ outcome: 'restored' | 'already-saved' | 'source-restored' | 'backup-discarded' | 'saved', dirty: boolean, conflicted: boolean, backupPending?: true, backupRetained?: true }
116
+
117
+ | { type: 'production-drafts.inspect', family: 'production', coverage: 'tab-state' | 'partial', token: string, drafts: ClientProductionDraftMetadata[], next?: { after: string, token: string } }
118
+ | { type: 'production-drafts.read', family: 'production', draft: string, format: 'presmium-production-draft-json-v1', offset: number, endOffset: number, totalUtf16: number, totalUtf8: number, sha256: string, jsonText: string }
119
+ | { type: 'production-drafts.discard', family: 'production', draft: string, discarded: true }
120
+
67
121
  | { type: 'comment-drafts.inspect', family: 'comment', coverage: 'stored-and-session' | 'session-only', skippedInvalid: number, token: string, drafts: ClientCommentDraftMetadata[], next?: { after: string, token: string } }
68
122
  | { 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
123
  | { type: 'comment-drafts.restore', family: 'comment', draft: ClientCommentDraftReference, composerId: string, restored: ClientCommentDraftReference, preservedCurrent: ClientCommentDraftReference | null, targetState: 'current' | 'changed' }
@@ -77,7 +131,9 @@ export type AuthoringClientActionResult =
77
131
  export interface AuthoringClientSnapshot {
78
132
  revision: number
79
133
  source: CanonicalSource
80
- view: 'document' | 'present'
134
+ view: 'document' | 'scrolly' | 'present'
135
+ mode?: AuthoringClientView
136
+ 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
137
  editing: { dirty: boolean, saving: boolean, composing: boolean, conflicted: boolean, locked: boolean, loading: boolean }
82
138
  interaction: string
83
139
  position?: { sectionId: string, stepId?: string }
@@ -97,6 +153,7 @@ export interface AuthoringClientDescriptor extends AuthoringClientConnection {
97
153
  observedAt: string
98
154
  verification: 'reported-state'
99
155
  snapshot: AuthoringClientSnapshot
156
+ pendingRequest?: { requestId: string, action: AuthoringClientActionType, cancellationRequested?: true }
100
157
  }
101
158
  export interface AuthoringClientList { document: string, clients: AuthoringClientDescriptor[], nextAfter?: string, unavailable: readonly string[] }
102
159
  export interface AuthoringClientRequest {
@@ -114,6 +171,7 @@ export interface AuthoringClientRequestResult extends AuthoringClientConnection
114
171
  action: AuthoringClientActionType
115
172
  source: CanonicalSource
116
173
  state: AuthoringClientRequestState
174
+ cancellationRequested?: true
117
175
  admittedAt: string
118
176
  expiresAt: string
119
177
  observedAt?: string
@@ -138,6 +196,7 @@ export interface AuthoringClients {
138
196
  list(document: string, query: { clientId?: string, after?: string }, member: Member): Promise<AuthoringClientList>
139
197
  request(document: string, request: AuthoringClientRequest, member: Member): Promise<AuthoringClientRequestResult>
140
198
  get(document: string, query: { clientId: string, epoch: string, requestId: string }, member: Member): Promise<AuthoringClientRequestResult>
199
+ cancel?(document: string, query: { clientId: string, epoch: string, requestId: string }, member: Member): Promise<AuthoringClientRequestResult>
141
200
  }
142
201
 
143
202
  /** Reserve the complete receipt and the host-only lease, rather than budgeting only the text fragment. */
@@ -163,15 +222,26 @@ const bool: Schema = { type: 'boolean' }
163
222
  const object = (properties: Record<string, Schema>, required = Object.keys(properties)): Schema => ({ type: 'object', additionalProperties: false, properties, required })
164
223
  const digest: Schema = { type: 'string', pattern: '^[a-f0-9]{64}$' }
165
224
  const draftReference = object({ id: entity, revision: { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER }, token: digest })
225
+ const bodyDraftReference = digest
226
+ const bodyMetadata = object({ draft: bodyDraftReference, current: bool, storage: { enum: ['durable', 'rescue', 'session'] }, updatedAt: integer, baseVersion: entity, baseObserved: bool, composing: bool, pendingSubmission: bool })
166
227
  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
228
  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
229
  const nullableComponentReference: Schema = { oneOf: [componentDraftReference, { type: 'null' }] }
169
230
  const nullableCommentReference: Schema = { oneOf: [draftReference, { type: 'null' }] }
170
231
  const commentRestore = object({ composerId: id, expectedCurrent: nullableCommentReference })
171
232
  const cursor = object({ after: entity, token: digest })
233
+ const productionMetadata = object({ draft: digest, kind: { enum: [...PRODUCTION_DRAFT_KINDS] }, stepId: entity, field: { enum: ['minimumHoldMs', 'trailingPauseMs'] }, assetId: entity, clipId: entity, targetAvailable: bool, requiresReview: bool, storage: { enum: ['tab', 'memory'] }, discardable: bool }, ['draft', 'kind', 'stepId', 'targetAvailable', 'requiresReview', 'storage', 'discardable'])
172
234
  export const AUTHORING_CLIENT_ACTION_RESULT_SCHEMA: Schema = { oneOf: [
235
+ object({ type: { const: 'body-drafts.inspect' }, family: { const: 'body' }, coverage: { enum: ['stored-and-session', 'partial'] }, token: digest,
236
+ drafts: { type: 'array', maxItems: 10, items: bodyMetadata }, next: cursor }, ['type', 'family', 'coverage', 'token', 'drafts']),
237
+ 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 } }),
238
+ object({ type: { enum: ['body-drafts.restore', 'body-drafts.discard', 'body-drafts.retry'] }, family: { const: 'body' }, draft: bodyDraftReference,
239
+ 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']),
240
+ object({ type: { const: 'production-drafts.inspect' }, family: { const: 'production' }, coverage: { enum: ['tab-state', 'partial'] }, token: digest, drafts: { type: 'array', maxItems: 10, items: productionMetadata }, next: cursor }, ['type', 'family', 'coverage', 'token', 'drafts']),
241
+ object({ type: { const: 'production-drafts.read' }, family: { const: 'production' }, draft: digest, format: { const: 'presmium-production-draft-json-v1' }, offset: integer, endOffset: integer, totalUtf16: integer, totalUtf8: integer, sha256: digest, jsonText: { type: 'string', maxLength: 2048 } }),
242
+ object({ type: { const: 'production-drafts.discard' }, family: { const: 'production' }, draft: digest, discarded: { const: true } }),
173
243
  object({ type: { const: 'comment-drafts.inspect' }, family: { const: 'comment' }, coverage: { enum: ['stored-and-session', 'session-only'] }, skippedInvalid: integer,
174
- 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']),
244
+ 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, restorable: { const: true }, threadId: entity, commentId: entity }, ['draft', 'kind', 'storage', 'updatedAt', 'baseVersion', 'composing', 'pendingSubmission', 'ownersKnown', 'active', 'discardable']) }, next: cursor }, ['type', 'family', 'coverage', 'skippedInvalid', 'token', 'drafts']),
175
245
  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 } }),
176
246
  object({ type: { const: 'comment-drafts.restore' }, family: { const: 'comment' }, draft: draftReference, composerId: id, restored: draftReference, preservedCurrent: nullableCommentReference, targetState: { enum: ['current', 'changed'] } }),
177
247
  object({ type: { const: 'comment-drafts.discard' }, family: { const: 'comment' }, draft: draftReference, discarded: { const: true } }),
@@ -186,7 +256,11 @@ const binding = object({ source, irRevision: entity, planId: entity })
186
256
  const position = object({ timeMs: number, stepTimeMs: number, sectionId: entity, stepId: entity, durationMs: number, playing: bool, rate: { type: 'number', exclusiveMinimum: 0, maximum: 16 }, trying: bool, waitingFor: entity }, ['timeMs', 'durationMs', 'playing', 'rate', 'trying'])
187
257
  const playback = object({ binding, status: { enum: ['loading', 'ready', 'estimated', 'unavailable', 'failed'] }, position, error: { type: 'string', maxLength: 300 } }, ['binding', 'status'])
188
258
  export const AUTHORING_CLIENT_SNAPSHOT_SCHEMA: Schema = object({
189
- revision: integer, source, view: { enum: ['document', 'present'] }, editing: object({ dirty: bool, saving: bool, composing: bool, conflicted: bool, locked: bool, loading: bool }),
259
+ revision: integer, source, view: { enum: ['document', 'scrolly', 'present'] }, editing: object({ dirty: bool, saving: bool, composing: bool, conflicted: bool, locked: bool, loading: bool }),
260
+ mode: { enum: ['document', 'reading', 'presentation', 'production'] },
261
+ recording: object({ phase: { enum: ['idle', 'requesting', 'recording', 'stopping', 'ready', 'failed'] }, elapsedMs: number,
262
+ candidate: object({ byteLength: integer, mime: { type: 'string', maxLength: 200 }, assetId: entity }, ['byteLength', 'mime']),
263
+ error: entity, audition: { enum: ['idle', 'loading', 'playing', 'failed'] } }, ['phase', 'elapsedMs']),
190
264
  interaction: { type: 'string', maxLength: 200 }, position: object({ sectionId: entity, stepId: entity }, ['sectionId']), binding, playback,
191
265
  preview: { oneOf: [object({ status: { enum: ['unprepared', 'preparing', 'unavailable'] } }), object({ status: { const: 'prepared' }, source, irRevision: entity, projectRevision: integer })] },
192
266
  actions: { type: 'array', items: { enum: [...AUTHORING_CLIENT_ACTIONS] }, maxItems: AUTHORING_CLIENT_ACTIONS.length, uniqueItems: true }, unsubmittedContent: { const: 'not-inspected' },
@@ -194,10 +268,24 @@ export const AUTHORING_CLIENT_SNAPSHOT_SCHEMA: Schema = object({
194
268
  const action = (type: string, properties: Record<string, Schema> = {}): Schema => object({ type: { const: type }, ...properties })
195
269
  export const AUTHORING_CLIENT_ACTION_SCHEMA: Schema = { oneOf: [
196
270
  action('state.read'), action('source.flush'), action('preview.prepare'), action('playback.pause'), action('position.step', { sectionId: entity, stepId: entity }),
197
- object({ type: { const: 'comment-drafts.inspect' }, cursor, limit: { type: 'integer', minimum: 1, maximum: 10 } }, ['type']),
271
+ action('view.set', { view: { enum: ['document', 'reading', 'presentation', 'production'] } }),
272
+ ...['native-history.undo', 'native-history.redo', 'recording.start', 'recording.stop', 'recording.cancel', 'recording.save', 'recording.listen', 'recording.pause'].map(type => action(type)),
273
+ action('recording.discard', { confirm: { const: true } }),
274
+ object({ type: { const: 'production-drafts.inspect' }, cursor, limit: { type: 'integer', minimum: 1, maximum: 10 } }, ['type']),
275
+ object({ type: { const: 'production-drafts.read' }, draft: digest, offset: integer, maxChars: { type: 'integer', minimum: 2, maximum: 2048 } }, ['type', 'draft', 'offset']),
276
+ action('production-drafts.discard', { draft: digest, confirm: { const: true } }),
277
+ object({ type: { const: 'comment-drafts.inspect' }, cursor, limit: { type: 'integer', minimum: 1, maximum: 10 }, details: bool }, ['type']),
198
278
  object({ type: { const: 'comment-drafts.read' }, draft: draftReference, offset: integer, maxChars: { type: 'integer', minimum: 2, maximum: 2048 } }, ['type', 'draft', 'offset']),
199
- action('comment-drafts.restore', { draft: draftReference, composerId: id, expectedCurrent: nullableCommentReference }),
279
+ { ...object({ type: { const: 'comment-drafts.restore' }, draft: draftReference,
280
+ composerId: { ...id, description: 'Advanced: provide together with expectedCurrent; omit both to select the unique native recovery target.' },
281
+ expectedCurrent: { ...nullableCommentReference, description: 'Advanced: provide together with composerId; null requires no current draft.' } }, ['type', 'draft']),
282
+ oneOf: [{ required: ['composerId', 'expectedCurrent'] }, { not: { anyOf: [{ required: ['composerId'] }, { required: ['expectedCurrent'] }] } }] },
200
283
  action('comment-drafts.discard', { draft: draftReference }),
284
+ object({ type: { const: 'body-drafts.inspect' }, cursor, limit: { type: 'integer', minimum: 1, maximum: 10 } }, ['type']),
285
+ object({ type: { const: 'body-drafts.read' }, draft: bodyDraftReference, offset: integer, maxChars: { type: 'integer', minimum: 2, maximum: 2048 } }, ['type', 'draft', 'offset']),
286
+ action('body-drafts.restore', { draft: bodyDraftReference }),
287
+ action('body-drafts.discard', { draft: bodyDraftReference, confirm: { const: true } }),
288
+ action('body-drafts.retry', { draft: bodyDraftReference }),
201
289
  object({ type: { const: 'component-drafts.inspect' }, cursor, limit: { type: 'integer', minimum: 1, maximum: 10 } }, ['type']),
202
290
  object({ type: { const: 'component-drafts.read' }, draft: componentDraftReference, offset: integer, maxChars: { type: 'integer', minimum: 2, maximum: 2048 } }, ['type', 'draft', 'offset']),
203
291
  action('component-drafts.restore', { draft: componentDraftReference, expectedCurrent: nullableComponentReference }),
@@ -0,0 +1,47 @@
1
+ import type { Schema } from '@cfworker/json-schema'
2
+ import type { Member } from './server.ts'
3
+ import type { AuthoringClientConnection, AuthoringClientLease, AuthoringClientRequestState } from './authoring-clients.ts'
4
+
5
+ /** Window lifetime survives home and document changes; it never asserts a CanonicalSource. */
6
+ export const AUTHORING_WINDOW_ACTIONS = ['window.read', 'document.open', 'document.close'] as const
7
+ export type AuthoringWindowAction = { type: 'window.read' } | { type: 'document.open', document: string } | { type: 'document.close' }
8
+ export type AuthoringWindowLocation = { type: 'home' } | { type: 'document', document: string, documentId?: string, status: 'loading' | 'ready' | 'failed' }
9
+ export interface AuthoringWindowSnapshot { revision: number, location: AuthoringWindowLocation, actions: (typeof AUTHORING_WINDOW_ACTIONS[number])[] }
10
+ export interface AuthoringWindowOpen { clientId: string, epoch: string, snapshot: AuthoringWindowSnapshot }
11
+ export interface AuthoringWindowDescriptor extends AuthoringClientConnection { connected: boolean, snapshot: AuthoringWindowSnapshot, observedAt: string, pendingRequest?: { requestId: string, action: AuthoringWindowAction['type'], cancellationRequested?: true } }
12
+ export interface AuthoringWindowRequest extends AuthoringClientConnection {
13
+ requestId: string
14
+ revision: number
15
+ action: AuthoringWindowAction
16
+ /** Pinned internally before approval; path reuse cannot select a different document. */
17
+ target?: { document: string, documentId: string }
18
+ }
19
+ export interface AuthoringWindowRequestResult extends AuthoringClientConnection {
20
+ requestId: string, action: AuthoringWindowAction['type'], state: AuthoringClientRequestState, admittedAt: string, expiresAt: string,
21
+ snapshot?: AuthoringWindowSnapshot, outcome?: 'observed' | 'opened' | 'closed' | 'unchanged', cancellationRequested?: true, error?: { code: string }, acknowledged: boolean, current: boolean
22
+ }
23
+ export type AuthoringWindowEvent = { type: 'connected', connectionId: string } | { type: 'request', request: AuthoringWindowRequest, expiresAt: string } | { type: 'cancel', connectionId: string, requestId: string }
24
+ export interface AuthoringWindowReport { sequence: number, snapshot: AuthoringWindowSnapshot }
25
+ export interface AuthoringWindowAcknowledgement extends AuthoringWindowReport { requestId: string, state: 'executing' | 'done' | 'refused' | 'failed', outcome?: AuthoringWindowRequestResult['outcome'], error?: { code: string } }
26
+ export type AuthoringWindowReference = Pick<AuthoringWindowRequest, 'clientId' | 'epoch' | 'requestId'>
27
+ export interface AuthoringWindows {
28
+ list(query: { clientId?: string, after?: string }, member: Member): Promise<{ scope: 'workspace', clients: AuthoringWindowDescriptor[], nextAfter?: string }>
29
+ request(request: AuthoringWindowRequest, member: Member): Promise<AuthoringWindowRequestResult>
30
+ get(reference: AuthoringWindowReference | string, member: Member): Promise<AuthoringWindowRequestResult>
31
+ cancel(reference: AuthoringWindowReference | string, member: Member): Promise<AuthoringWindowRequestResult>
32
+ }
33
+
34
+ const id: Schema = { type: 'string', minLength: 1, maxLength: 80, pattern: '^[a-zA-Z0-9.-]+$' }
35
+ export const AUTHORING_WINDOW_HANDLE_SCHEMA: Schema = id
36
+ const directory: Schema = { type: 'string', maxLength: 200 }
37
+ const entity: Schema = { type: 'string', minLength: 1, maxLength: 200 }
38
+ const integer: Schema = { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER }
39
+ const object = (properties: Record<string, Schema>, required = Object.keys(properties)): Schema => ({ type: 'object', additionalProperties: false, properties, required })
40
+ const connection = { clientId: id, epoch: id, connectionId: id }
41
+ export const AUTHORING_WINDOW_ACTION_SCHEMA: Schema = { oneOf: [object({ type: { const: 'window.read' } }), object({ type: { const: 'document.open' }, document: directory }), object({ type: { const: 'document.close' } })] }
42
+ export const AUTHORING_WINDOW_SNAPSHOT_SCHEMA: Schema = object({ revision: integer, location: { oneOf: [object({ type: { const: 'home' } }), object({ type: { const: 'document' }, document: directory, documentId: entity, status: { enum: ['loading', 'ready', 'failed'] } }, ['type', 'document', 'status'])] }, actions: { type: 'array', items: { enum: [...AUTHORING_WINDOW_ACTIONS] }, maxItems: AUTHORING_WINDOW_ACTIONS.length, uniqueItems: true } })
43
+ export const AUTHORING_WINDOW_OPEN_SCHEMA: Schema = object({ clientId: id, epoch: id, snapshot: AUTHORING_WINDOW_SNAPSHOT_SCHEMA })
44
+ export const AUTHORING_WINDOW_REQUEST_SCHEMA: Schema = object({ ...connection, requestId: id, revision: integer, action: AUTHORING_WINDOW_ACTION_SCHEMA, target: object({ document: directory, documentId: entity }) }, [...Object.keys(connection), 'requestId', 'revision', 'action'])
45
+ export const AUTHORING_WINDOW_REPORT_SCHEMA: Schema = object({ sequence: integer, snapshot: AUTHORING_WINDOW_SNAPSHOT_SCHEMA })
46
+ export const AUTHORING_WINDOW_ACK_SCHEMA: Schema = object({ sequence: integer, snapshot: AUTHORING_WINDOW_SNAPSHOT_SCHEMA, requestId: id, state: { enum: ['executing', 'done', 'refused', 'failed'] }, outcome: { enum: ['observed', 'opened', 'closed', 'unchanged'] }, error: object({ code: { type: 'string', minLength: 1, maxLength: 160 } }) }, ['sequence', 'snapshot', 'requestId', 'state'])
47
+ export type AuthoringWindowLease = AuthoringClientLease
@@ -6,7 +6,7 @@ import type { DocumentOutlineAnswer, DocumentOutlineQuery, DocumentPartAnswer, D
6
6
  import type { AppliedDocumentAuthoringAction, DocumentAuthoringActionInspection, DocumentAuthoringActionPlan, DocumentAuthoringActionRead, DocumentAuthoringActionReference, DocumentAuthoringActionRequest, DocumentAuthoringAction, DocumentComponentImpactAnswer, DocumentComponentImpactQuery } from './authoring-actions.ts'
7
7
 
8
8
  export const AUTHORING_API_VERSION = 1 as const
9
- export const DOCUMENT_OPERATION_TYPES = ['insertBlock', 'moveBlock', 'deleteBlock', 'updateText', 'updateSection', 'setStepState', 'setNarration', 'setTiming', 'replaceAsset'] as const satisfies readonly DocumentEditOperation['type'][]
9
+ export const DOCUMENT_OPERATION_TYPES = ['insertBlock', 'moveBlock', 'deleteBlock', 'updateText', 'updateSection', 'setStepState', 'setNarration', 'removeNarration', 'setStepNarrations', 'setTiming', 'replaceAsset'] as const satisfies readonly DocumentEditOperation['type'][]
10
10
 
11
11
  export interface AuthoringCapabilities {
12
12
  apiVersion: typeof AUTHORING_API_VERSION
@@ -0,0 +1,174 @@
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
+ import type { CanonicalSource } from '../ir.ts'
8
+
9
+ /** Identity and location of one capture, kept beside its pictures as capture.json. */
10
+ export interface CaptureEvidence {
11
+ id: string
12
+ createdAt: string
13
+ directory: string
14
+ manifestFile: string
15
+ /** Retained in the service cache instead of being removed with older recent captures. */
16
+ retained: boolean
17
+ /** The source actually shown in the capturing browser, when its hook reports it. */
18
+ source?: CanonicalSource
19
+ /** The document code bundle loaded by that browser; source alone does not identify scene code. */
20
+ codeBundle?: string
21
+ }
22
+
23
+ /** At most this many pictures a request: each is one image in a tool result. */
24
+ export const CAPTURE_MAX_FRAMES = 12
25
+ /** At most this many boxes a picture reports for `measure`. */
26
+ export const CAPTURE_MAX_BOXES = 200
27
+
28
+ export interface SlideCaptureRequest {
29
+ /** Keep this evidence in the service cache beyond its recent-capture cleanup. */
30
+ retain?: boolean
31
+ /** The page (section) id, or its number from 1. */
32
+ section: string
33
+ /** The steps to show, from 0; every step of the page when omitted. */
34
+ steps?: number[]
35
+ /** Milliseconds into each step's animation; each step's rest frame (its final state) when omitted. */
36
+ at?: number[]
37
+ appearance?: 'light' | 'dark'
38
+ /** Device pixels per slide pixel. */
39
+ scale?: 1 | 2
40
+ /** A region of the slide, in slide pixels. */
41
+ clip?: { x: number, y: number, width: number, height: number }
42
+ /** A CSS selector: the boxes of the matching elements in the slide are reported, in slide pixels. */
43
+ measure?: string
44
+ /**
45
+ * How the presentation reaches each step: `direct` (default) draws it from its step and moment; `backward` shows the
46
+ * step after it first and goes back as a presenter does, with the page's own clock, to check that going back works.
47
+ * `backward` and `at` cannot be combined: use separate calls for timed frames and reverse arrival at rest.
48
+ */
49
+ arrive?: 'direct' | 'backward'
50
+ /** Draw the presentation's captions over the slide (default true); false shows the whole slide, the narration being in `narration`. */
51
+ captions?: boolean
52
+ }
53
+
54
+ export interface ReadingCaptureRequest {
55
+ retain?: boolean
56
+ /** The page (section) id, or its number from 1. */
57
+ section: string
58
+ /** The window's width in CSS pixels (default 1280; 390 for a phone). */
59
+ width?: number
60
+ appearance?: 'light' | 'dark'
61
+ /** Device pixels per CSS pixel. */
62
+ scale?: 1 | 2
63
+ /** A CSS selector: the boxes of the matching elements in the page's section are reported, in CSS pixels. */
64
+ measure?: string
65
+ }
66
+
67
+ export interface CapturedReading {
68
+ section: string
69
+ /** The PNG file of the picture, in the service's state directory. */
70
+ file: string
71
+ /** The section's size in CSS pixels; the picture is cut at `CAPTURE_MAX_HEIGHT`. */
72
+ width: number
73
+ height: number
74
+ cut: boolean
75
+ boxes?: CapturedBox[]
76
+ }
77
+
78
+ export interface ReadingCaptureResult {
79
+ document: string
80
+ capture?: CaptureEvidence
81
+ width: number
82
+ frames: CapturedReading[]
83
+ problems: string[]
84
+ }
85
+
86
+ /** The tallest picture of a reading page's section, in CSS pixels. */
87
+ export const CAPTURE_MAX_HEIGHT = 8000
88
+
89
+ export interface CapturedBox {
90
+ x: number
91
+ y: number
92
+ width: number
93
+ height: number
94
+ visible: boolean
95
+ /** The start of the element's text. */
96
+ text: string
97
+ /** Its `id`, `class` and `data-*` attributes. */
98
+ attributes: Record<string, string>
99
+ }
100
+
101
+ export interface CapturedSlide {
102
+ section: string
103
+ slide: number
104
+ step: number
105
+ /** Milliseconds into the step, or null for its rest frame. */
106
+ at: number | null
107
+ /** The step's narration (its script), as text: what the captions show. */
108
+ narration: string
109
+ /** The PNG file of the picture, in the service's state directory. */
110
+ file: string
111
+ width: number
112
+ height: number
113
+ boxes?: CapturedBox[]
114
+ }
115
+
116
+ export interface SlideCaptureResult {
117
+ document: string
118
+ capture?: CaptureEvidence
119
+ /** The slide's size in slide pixels. */
120
+ shape: { width: number, height: number }
121
+ frames: CapturedSlide[]
122
+ /** What failed in the page while it was drawn: component errors, page errors. */
123
+ problems: string[]
124
+ }
125
+
126
+ export interface OverviewCaptureRequest {
127
+ retain?: boolean
128
+ /** Each page's last step (default), or every step of every page. */
129
+ steps?: 'last' | 'all'
130
+ appearance?: 'light' | 'dark'
131
+ /** Thumbnails a row on a sheet (default 4). */
132
+ columns?: number
133
+ /** Draw the presentation's captions over the slides (default true). */
134
+ captions?: boolean
135
+ }
136
+
137
+ export interface OverviewCaptureResult {
138
+ document: string
139
+ capture?: CaptureEvidence
140
+ /** The directory of the pictures, named so that they sort in reading order (`03-12-page.png`: page 3, step 12 from 0). */
141
+ dir: string
142
+ frames: { section: string, slide: number, step: number, file: string, narration: string }[]
143
+ /** `narration.md` beside the pictures: each picture's narration under its file name. */
144
+ narrationFile: string
145
+ /** Sheets of thumbnails, at most `CAPTURE_SHEET_SIZE` each, in order. */
146
+ sheets: string[]
147
+ problems: string[]
148
+ }
149
+
150
+ /** Thumbnails on one overview sheet; and the most pictures an overview takes. */
151
+ export const CAPTURE_SHEET_SIZE = 20
152
+ export const CAPTURE_MAX_OVERVIEW = 400
153
+
154
+ export interface DocumentCapture {
155
+ /** The pictures, with their PNG bytes in the order of `frames`. */
156
+ slides(document: string, request: SlideCaptureRequest, signal?: AbortSignal): Promise<SlideCaptureResult & { images: Uint8Array[] }>
157
+ /** A page of the reading version (the web page), with its PNG bytes. */
158
+ reading(document: string, request: ReadingCaptureRequest, signal?: AbortSignal): Promise<ReadingCaptureResult & { images: Uint8Array[] }>
159
+ /** Every page's rest frames as the presentation shows them, as files and as sheets of thumbnails (the images). */
160
+ overview(document: string, request: OverviewCaptureRequest, signal?: AbortSignal): Promise<OverviewCaptureResult & { images: Uint8Array[] }>
161
+ }
162
+
163
+ /** The hook a viewer page opened with `?capture` installs, which the capturing browser drives. */
164
+ export interface CaptureHook {
165
+ /** Identity of the source and document code actually loaded in the page. Older viewers may omit it. */
166
+ snapshot?(): { source?: CanonicalSource, codeBundle?: string }
167
+ /** A slide at a step: drawn at the moment `at` (its rest frame when omitted), or reached going back from the step after. */
168
+ show(position: { section: string, step: number, at?: number, arrive?: 'direct' | 'backward' }): Promise<{ problems: string[] }>
169
+ /** A section of the reading page, scrolled through so that its components load, at rest. */
170
+ read(section: string): Promise<{ problems: string[] }>
171
+ }
172
+
173
+ export const CAPTURE_HOOK = 'presmiumCapture'
174
+ export const CAPTURE_PARAM = 'capture'
@@ -1,3 +1,5 @@
1
+ import { MEDIA_LOCATION_PROPERTIES, MEDIA_LOCATION_CHOICES, mediaFileSchema } from './media-uploads.ts'
2
+ import type { DocumentMediaLocation, DocumentMediaFile } from './media-uploads.ts'
1
3
  import type { CanonicalSource } from '../ir.ts'
2
4
  import type { Finding } from './checks.ts'
3
5
  import type { DocumentIssue, MediaClip, TimeRange } from './document.ts'
@@ -33,18 +35,18 @@ export interface VerifiedDocumentRecordingAdoption extends DocumentChangeAnswer
33
35
  }
34
36
  /** Inspect an existing real snapshot; an expected revision is optional during discovery. */
35
37
  export type DocProductionPlanQuery = ProductionAudioPlanQuery
36
- export interface DocumentWorkspaceAudioInspect { source: CanonicalSource, path: string }
38
+ export type DocumentWorkspaceAudioInspect = { source: CanonicalSource } & DocumentMediaLocation
37
39
  export interface WorkspaceAudioInspectionAnswer {
38
40
  document: string
39
41
  source: CanonicalSource
40
- file: { path: string, sha256: string, byteLength: number }
42
+ file: DocumentMediaFile
41
43
  inspection: Omit<ProductionAssetInspection, 'assetId' | 'mediaId'>
42
44
  }
43
45
  export interface DocumentWorkspaceAudioImport {
44
46
  id: string
45
47
  source: CanonicalSource
46
48
  /** Workspace-relative regular file permitted by the selected document's existing source scope. */
47
- file: { path: string, sha256: string, byteLength: number }
49
+ file: DocumentMediaFile
48
50
  }
49
51
  export interface VerifiedDocumentAudioImport extends DocumentAudioImportAnswer {
50
52
  verification: {
@@ -116,15 +118,15 @@ export const DOCUMENT_AUDIO_WORKSPACE_IMPORT_SCHEMA = {
116
118
  type: 'object', additionalProperties: false,
117
119
  properties: {
118
120
  id: { type: 'string', minLength: 1, maxLength: 200 }, source,
119
- file: { type: 'object', additionalProperties: false, properties: { path: { type: 'string', minLength: 1, maxLength: 1024 }, sha256: { type: 'string', pattern: '^[a-f\\d]{64}$' }, byteLength: { type: 'integer', minimum: 1, maximum: DOCUMENT_AUDIO_MAX_BYTES } }, required: ['path', 'sha256', 'byteLength'] },
121
+ file: mediaFileSchema(DOCUMENT_AUDIO_MAX_BYTES),
120
122
  },
121
123
  required: ['id', 'source', 'file'],
122
124
  } as const
123
125
 
124
126
  export const DOCUMENT_WORKSPACE_AUDIO_INSPECTION_SCHEMA = {
125
127
  type: 'object', additionalProperties: false,
126
- properties: { source, path: { type: 'string', minLength: 1, maxLength: 1024 } },
127
- required: ['source', 'path'],
128
+ properties: { source, ...MEDIA_LOCATION_PROPERTIES },
129
+ required: ['source'], oneOf: MEDIA_LOCATION_CHOICES,
128
130
  } as const
129
131
 
130
132
  const clipId = { type: 'string', minLength: 1, maxLength: 200, pattern: '^[^\\u0000-\\u001f]+$', not: { enum: ['__proto__', 'constructor', 'prototype'] } } as const