@kition/kit-editor 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -2
- package/dist/LICENSE +177 -0
- package/dist/assets/kitEngine.worker-9PIHJagj.js +13020 -0
- package/dist/chunks/workspaceTree-CpJ2i9hy.js +23 -0
- package/dist/index.js +6434 -0
- package/dist/styles.css +807 -0
- package/dist/types/src/CommandDialog.d.ts +22 -0
- package/dist/types/src/CommentsPanel.d.ts +45 -0
- package/dist/types/src/CustomizeDialog.d.ts +32 -0
- package/dist/types/src/HostButtons.d.ts +11 -0
- package/dist/types/src/RenderFailure.d.ts +7 -0
- package/dist/types/src/TextSink.d.ts +6 -0
- package/dist/types/src/brand.d.ts +2 -0
- package/dist/types/src/catalogMenus.d.ts +27 -0
- package/dist/types/src/chart.d.ts +138 -0
- package/dist/types/src/conflicts.d.ts +12 -0
- package/dist/types/src/drawing.d.ts +83 -0
- package/dist/types/src/editor.d.ts +544 -0
- package/dist/types/src/engine/KitCanvas.d.ts +70 -0
- package/dist/types/src/engine/createKitFile.d.ts +12 -0
- package/dist/types/src/engine/decorations.d.ts +14 -0
- package/dist/types/src/engine/engineOverlays.d.ts +197 -0
- package/dist/types/src/engine/engineTools.d.ts +116 -0
- package/dist/types/src/engine/kitDraft.d.ts +70 -0
- package/dist/types/src/engine/kitEngine.d.ts +370 -0
- package/dist/types/src/engine/kitEngine.worker.d.ts +30 -0
- package/dist/types/src/engine/kitHost.d.ts +41 -0
- package/dist/types/src/engine/kitModel.d.ts +32 -0
- package/dist/types/src/engine/kitModelRunner.d.ts +93 -0
- package/dist/types/src/engine/kitModule.d.ts +173 -0
- package/dist/types/src/engine/kitShortcuts.d.ts +32 -0
- package/dist/types/src/engine/kitTools.d.ts +79 -0
- package/dist/types/src/engine/lentFiles.d.ts +29 -0
- package/dist/types/src/engine/rasterViewport.d.ts +178 -0
- package/dist/types/src/engine/readOnly.d.ts +78 -0
- package/dist/types/src/engine/refusal.d.ts +39 -0
- package/dist/types/src/engine/replica.d.ts +23 -0
- package/dist/types/src/engine/useKitDocument.d.ts +154 -0
- package/dist/types/src/engine/workerRelay.d.ts +62 -0
- package/dist/types/src/files.d.ts +74 -0
- package/dist/types/src/frame/EditorFrame.d.ts +74 -0
- package/dist/types/src/frame/FocusBar.d.ts +10 -0
- package/dist/types/src/frame/MenuNodes.d.ts +20 -0
- package/dist/types/src/frame/MenuRibbon.d.ts +8 -0
- package/dist/types/src/frame/ModeButton.d.ts +7 -0
- package/dist/types/src/frame/menus.d.ts +64 -0
- package/dist/types/src/frame/modes.d.ts +51 -0
- package/dist/types/src/frame/useFrameLayout.d.ts +34 -0
- package/dist/types/src/host.d.ts +127 -0
- package/dist/types/src/index.d.ts +84 -0
- package/dist/types/src/ink.d.ts +26 -0
- package/dist/types/src/lease.d.ts +53 -0
- package/dist/types/src/oneInFlight.d.ts +7 -0
- package/dist/types/src/phrases.d.ts +25 -0
- package/dist/types/src/presence.d.ts +79 -0
- package/dist/types/src/strings.d.ts +6 -0
- package/dist/types/src/toolIcons.d.ts +32 -0
- package/dist/types/src/uiCatalog.d.ts +59 -0
- package/dist/types/src/uiConfig.d.ts +53 -0
- package/dist/types/src/uiContext.d.ts +65 -0
- package/dist/types/src/uiStore.d.ts +20 -0
- package/dist/types/src/useCommentAnchors.d.ts +29 -0
- package/dist/types/src/useKitSession.d.ts +115 -0
- package/dist/types/src/workspaceTree.d.ts +5 -0
- package/dist/workspaceTree.js +1 -0
- package/package.json +43 -3
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
import type { KitCommand, KitModuleManifest, KitModuleReplica } from './kitModule.js';
|
|
2
|
+
import type { LentFiles } from './lentFiles.js';
|
|
3
|
+
import type { RasterPins } from './rasterViewport.js';
|
|
4
|
+
import { type DraftSummary, type KitDiagnostic, type ModelBatchResult } from '@kition/kit-ui-protocol';
|
|
5
|
+
import type { Origin, StateDiff } from '@kition/kdm';
|
|
6
|
+
import { type KitModelSupport, type ModelErrorData } from './kitModel.js';
|
|
7
|
+
import { type KitParamError } from './refusal.js';
|
|
8
|
+
/** What the page keeps in sync about the open document after every request that can change it. */
|
|
9
|
+
export type KitEngineInfo = {
|
|
10
|
+
width: number;
|
|
11
|
+
height: number;
|
|
12
|
+
pinned: RasterPins;
|
|
13
|
+
revision: number;
|
|
14
|
+
dirty: boolean;
|
|
15
|
+
canUndo: boolean;
|
|
16
|
+
canRedo: boolean;
|
|
17
|
+
/** The SDK's `inspect()` JSON; each kit's editor reads its own fields from it. */
|
|
18
|
+
inspected: Record<string, unknown>;
|
|
19
|
+
/** The replica's version, when the engine follows its replica and has made one. */
|
|
20
|
+
replica?: Uint8Array | null;
|
|
21
|
+
/** How the engine answers the object model (`kitModel.ts`); absent or null: it does not. */
|
|
22
|
+
model?: KitModelSupport;
|
|
23
|
+
/**
|
|
24
|
+
* Whether the engine runs commands as an origin (engine contract 2, `executeAs`), so the agent's
|
|
25
|
+
* steps are its own undo scope (KitModel M12a) and the agent's undo never takes back the
|
|
26
|
+
* person's edit; absent: it does not.
|
|
27
|
+
*/
|
|
28
|
+
origins?: boolean;
|
|
29
|
+
/**
|
|
30
|
+
* Whether the engine keeps editor state and takes a call context (`editorState`,
|
|
31
|
+
* `restoreEditorState`, `setContext`), so an agent's step can run in an editor state of the
|
|
32
|
+
* agent's own (`KitAgentStep`) without moving the person's; absent: it does not.
|
|
33
|
+
*/
|
|
34
|
+
context?: boolean;
|
|
35
|
+
/**
|
|
36
|
+
* Whether the engine keeps a replica the worker can read changes from (`version`,
|
|
37
|
+
* `exportChanges`), so the agent's write is answered with what it changed (`modelChanges`);
|
|
38
|
+
* absent: it does not.
|
|
39
|
+
*/
|
|
40
|
+
changes?: boolean;
|
|
41
|
+
/** The engine answers kit-defined premise reads for the live editor. */
|
|
42
|
+
premises?: boolean;
|
|
43
|
+
/**
|
|
44
|
+
* The schema version the engine's replica reads and the newest one its changes were written
|
|
45
|
+
* under (KitModel rule M5a), read when the document opens and after imports; absent or
|
|
46
|
+
* null for an engine that does not answer them.
|
|
47
|
+
*/
|
|
48
|
+
schema?: KitEngineSchema | null;
|
|
49
|
+
};
|
|
50
|
+
/** What one agent step acts on and in (Kit Process Protocol section 7a's `context.set`): the ids, the part, the time. */
|
|
51
|
+
export type KitCallContext = {
|
|
52
|
+
on?: Array<string | number>;
|
|
53
|
+
part?: Record<string, unknown>;
|
|
54
|
+
time?: number;
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* An agent's own editor state over one `ai/run` (C3b): what the kit's `editorState()` answered
|
|
58
|
+
* after the agent's last step, `null` before its first (the step then starts from the person's).
|
|
59
|
+
* Each step updates it.
|
|
60
|
+
*/
|
|
61
|
+
export type KitAgentState = {
|
|
62
|
+
state: string | null;
|
|
63
|
+
};
|
|
64
|
+
/**
|
|
65
|
+
* An agent step on the live document in the agent's own editor state: in one turn of the engine
|
|
66
|
+
* the person's state is put aside, `state` is put in place and `set` (the step's call context)
|
|
67
|
+
* set, the command runs, the agent's state is kept in `state`, and the person's is put back.
|
|
68
|
+
*/
|
|
69
|
+
export type KitAgentStep = {
|
|
70
|
+
state: KitAgentState;
|
|
71
|
+
set: KitCallContext | null;
|
|
72
|
+
};
|
|
73
|
+
/** What `modelChanges` answers: the change set and the version now, or no change set and why. */
|
|
74
|
+
export type KitModelChanges = {
|
|
75
|
+
changes: StateDiff;
|
|
76
|
+
version: string;
|
|
77
|
+
} | {
|
|
78
|
+
changes: null;
|
|
79
|
+
unavailable: string;
|
|
80
|
+
version: string;
|
|
81
|
+
};
|
|
82
|
+
/** A replica's schema versions: what it reads, and the newest its changes name (`null`: none). */
|
|
83
|
+
export type KitEngineSchema = {
|
|
84
|
+
reads: number;
|
|
85
|
+
newestAuthor: number | null;
|
|
86
|
+
};
|
|
87
|
+
/** How a document opens with a replica: a stored one to open with, and whether `info` follows it. */
|
|
88
|
+
export type KitEngineReplica = {
|
|
89
|
+
stored: KitModuleReplica | null;
|
|
90
|
+
follow: boolean;
|
|
91
|
+
};
|
|
92
|
+
export type KitEngineRequest = {
|
|
93
|
+
method: 'open';
|
|
94
|
+
manifest: KitModuleManifest;
|
|
95
|
+
name: string;
|
|
96
|
+
bytes: ArrayBuffer;
|
|
97
|
+
lent: LentFiles | null;
|
|
98
|
+
replica?: KitEngineReplica | null;
|
|
99
|
+
readOnly?: boolean;
|
|
100
|
+
canComment?: boolean;
|
|
101
|
+
} | {
|
|
102
|
+
method: 'create';
|
|
103
|
+
manifest: KitModuleManifest;
|
|
104
|
+
name: string;
|
|
105
|
+
width: number;
|
|
106
|
+
height: number;
|
|
107
|
+
lent: LentFiles | null;
|
|
108
|
+
readOnly?: boolean;
|
|
109
|
+
} | {
|
|
110
|
+
method: 'execute';
|
|
111
|
+
command: string;
|
|
112
|
+
params: Record<string, unknown>;
|
|
113
|
+
origin?: Origin;
|
|
114
|
+
agent?: {
|
|
115
|
+
state: string | null;
|
|
116
|
+
set: KitCallContext | null;
|
|
117
|
+
};
|
|
118
|
+
} | {
|
|
119
|
+
method: 'render';
|
|
120
|
+
x: number;
|
|
121
|
+
y: number;
|
|
122
|
+
scale: number;
|
|
123
|
+
width: number;
|
|
124
|
+
height: number;
|
|
125
|
+
} | {
|
|
126
|
+
method: 'renderArea';
|
|
127
|
+
x0: number;
|
|
128
|
+
y0: number;
|
|
129
|
+
x1: number;
|
|
130
|
+
y1: number;
|
|
131
|
+
width: number;
|
|
132
|
+
height: number;
|
|
133
|
+
} | {
|
|
134
|
+
method: 'commands';
|
|
135
|
+
} | {
|
|
136
|
+
method: 'disabledCommands';
|
|
137
|
+
} | {
|
|
138
|
+
method: 'check';
|
|
139
|
+
} | {
|
|
140
|
+
method: 'lendHandle';
|
|
141
|
+
handle: string;
|
|
142
|
+
bytes: ArrayBuffer | null;
|
|
143
|
+
} | {
|
|
144
|
+
method: 'takeOutput';
|
|
145
|
+
id: string;
|
|
146
|
+
max?: number;
|
|
147
|
+
} | {
|
|
148
|
+
method: 'save';
|
|
149
|
+
} | {
|
|
150
|
+
method: 'markSaved';
|
|
151
|
+
revision?: number;
|
|
152
|
+
} | {
|
|
153
|
+
method: 'info';
|
|
154
|
+
} | {
|
|
155
|
+
method: 'invoke';
|
|
156
|
+
name: string;
|
|
157
|
+
args: unknown[];
|
|
158
|
+
} | {
|
|
159
|
+
method: 'tool';
|
|
160
|
+
name: KitToolMethod;
|
|
161
|
+
args: unknown[];
|
|
162
|
+
settled: boolean;
|
|
163
|
+
} | {
|
|
164
|
+
method: 'saveWithReplica';
|
|
165
|
+
} | {
|
|
166
|
+
method: 'replicaVersion';
|
|
167
|
+
} | {
|
|
168
|
+
method: 'replicaExport';
|
|
169
|
+
since: ArrayBuffer;
|
|
170
|
+
} | {
|
|
171
|
+
method: 'replicaImport';
|
|
172
|
+
changes: ArrayBuffer;
|
|
173
|
+
blobs: ArrayBuffer;
|
|
174
|
+
} | {
|
|
175
|
+
method: 'replicaDocId';
|
|
176
|
+
} | {
|
|
177
|
+
method: 'replicaMerge';
|
|
178
|
+
changes: ArrayBuffer;
|
|
179
|
+
blobs: ArrayBuffer;
|
|
180
|
+
origin: Origin;
|
|
181
|
+
schema: object | null;
|
|
182
|
+
} | {
|
|
183
|
+
method: 'replicaCompare';
|
|
184
|
+
changes: ArrayBuffer;
|
|
185
|
+
schema: object | null;
|
|
186
|
+
} | {
|
|
187
|
+
method: 'modelVersion';
|
|
188
|
+
} | {
|
|
189
|
+
method: 'modelChanges';
|
|
190
|
+
since: string;
|
|
191
|
+
schema: object | null;
|
|
192
|
+
} | {
|
|
193
|
+
method: 'modelDescribe';
|
|
194
|
+
schema: object | null;
|
|
195
|
+
} | {
|
|
196
|
+
method: 'modelReply';
|
|
197
|
+
value: unknown;
|
|
198
|
+
} | {
|
|
199
|
+
method: 'modelBatch';
|
|
200
|
+
request: Record<string, unknown>;
|
|
201
|
+
schema: object | null;
|
|
202
|
+
} | {
|
|
203
|
+
method: 'premiseRead';
|
|
204
|
+
name: string;
|
|
205
|
+
params: Record<string, unknown>;
|
|
206
|
+
} | {
|
|
207
|
+
method: 'inspectAt';
|
|
208
|
+
context: KitCallContext;
|
|
209
|
+
part?: number;
|
|
210
|
+
};
|
|
211
|
+
/** The engine-tools capability's methods (kit editors U8b), each answering JSON. */
|
|
212
|
+
export type KitToolMethod = 'tools' | 'tool' | 'selectTool' | 'pointer' | 'toolKey' | 'toolText' | 'toolState';
|
|
213
|
+
/**
|
|
214
|
+
* A refusal names its reason (`read-only`; `invalid-params` with the engine's `errors`;
|
|
215
|
+
* `unsupported`), so the page can tell it from a failure; a refused object-model batch carries
|
|
216
|
+
* the protocol's error `data`.
|
|
217
|
+
*/
|
|
218
|
+
export type KitEngineResponse = {
|
|
219
|
+
id: number;
|
|
220
|
+
ok: true;
|
|
221
|
+
value: unknown;
|
|
222
|
+
} | {
|
|
223
|
+
id: number;
|
|
224
|
+
ok: false;
|
|
225
|
+
error: string;
|
|
226
|
+
reason?: string;
|
|
227
|
+
data?: ModelErrorData;
|
|
228
|
+
errors?: KitParamError[];
|
|
229
|
+
};
|
|
230
|
+
/**
|
|
231
|
+
* The page's handle on one document open in a kit engine worker. Every call
|
|
232
|
+
* is asynchronous and answered in order; `info` is current after each change.
|
|
233
|
+
*/
|
|
234
|
+
export declare class KitEngine {
|
|
235
|
+
private readonly worker;
|
|
236
|
+
info: KitEngineInfo;
|
|
237
|
+
closed: boolean;
|
|
238
|
+
private readonly pending;
|
|
239
|
+
private nextId;
|
|
240
|
+
private failure;
|
|
241
|
+
private constructor();
|
|
242
|
+
/**
|
|
243
|
+
* Starts a worker and opens the file's bytes in it with the kit's SDK; the bytes move to the
|
|
244
|
+
* worker. `lent` is where the document's other files (media) are read from, if anywhere;
|
|
245
|
+
* `replica` the stored replica to open them with, and whether `info` follows the replica.
|
|
246
|
+
* `readOnly` opens it for viewing: the worker refuses edits (`ReadOnlyError`, see `readOnly.ts`);
|
|
247
|
+
* with `canComment` (a commenter), it still runs the manifest's `commentCommands`, as long as
|
|
248
|
+
* they change only comment objects.
|
|
249
|
+
*/
|
|
250
|
+
static open(manifest: KitModuleManifest, name: string, bytes: ArrayBuffer, lent?: LentFiles | null, replica?: KitEngineReplica | null, readOnly?: boolean, canComment?: boolean): Promise<KitEngine>;
|
|
251
|
+
/**
|
|
252
|
+
* Starts a worker with a new, empty document made by the kit's SDK; nothing is written yet.
|
|
253
|
+
* `lent` lets it read other files, for example the clip a video project is made from.
|
|
254
|
+
*/
|
|
255
|
+
static create(manifest: KitModuleManifest, name: string, width: number, height: number, lent?: LentFiles | null, readOnly?: boolean): Promise<KitEngine>;
|
|
256
|
+
get width(): number;
|
|
257
|
+
get height(): number;
|
|
258
|
+
get pinned(): RasterPins;
|
|
259
|
+
private settle;
|
|
260
|
+
private fail;
|
|
261
|
+
private call;
|
|
262
|
+
/**
|
|
263
|
+
* Runs an engine command, as `origin` when given and the engine runs commands as an origin
|
|
264
|
+
* (`executeAs`); with `agent`, in the agent's own editor state (`KitAgentStep`), which it
|
|
265
|
+
* updates.
|
|
266
|
+
*/
|
|
267
|
+
execute(command: string, params?: Record<string, unknown>, origin?: Origin, agent?: KitAgentStep): Promise<string>;
|
|
268
|
+
/** RGBA8 of the area at (`x`, `y`) document pixels shown at `scale` screen pixels per pixel. */
|
|
269
|
+
render(x: number, y: number, scale: number, width: number, height: number): Promise<Uint8Array<ArrayBuffer>>;
|
|
270
|
+
/** RGBA8 of the document area (`x0`, `y0`)–(`x1`, `y1`), averaged down to exactly `width` × `height`. */
|
|
271
|
+
renderArea(x0: number, y0: number, x1: number, y1: number, width: number, height: number): Promise<Uint8Array<ArrayBuffer>>;
|
|
272
|
+
commands(): Promise<KitCommand[]>;
|
|
273
|
+
/** The ids of the commands that cannot run now: the cheap call for menu and shortcut states. */
|
|
274
|
+
disabledCommands(): Promise<string[]>;
|
|
275
|
+
/** The engine's diagnostics on the document (KHP A21), errors first; none from an engine without `check`. */
|
|
276
|
+
check(): Promise<KitDiagnostic[]>;
|
|
277
|
+
/**
|
|
278
|
+
* Lends a granted file's bytes to the engine under its handle (engine contract E15), before a command that
|
|
279
|
+
* names the handle runs; `null` takes them back. The bytes move to the worker.
|
|
280
|
+
*/
|
|
281
|
+
lendHandle(handle: string, bytes: ArrayBuffer | null): Promise<void>;
|
|
282
|
+
/**
|
|
283
|
+
* The next chunk of a file a command produced (engine contract E16), at most `max` bytes: take chunks until
|
|
284
|
+
* the output's `size`; the engine then forgets it. An engine without outputs refuses every id.
|
|
285
|
+
*/
|
|
286
|
+
takeOutput(id: string, max?: number): Promise<Uint8Array<ArrayBuffer>>;
|
|
287
|
+
/** The document as file bytes; it stays unsaved until `markSaved`. */
|
|
288
|
+
save(): Promise<Uint8Array<ArrayBuffer>>;
|
|
289
|
+
/**
|
|
290
|
+
* The document as file bytes and the revision they hold, which may be later than `info`'s when
|
|
291
|
+
* commands were still on their way to the engine: give it to `markSaved`.
|
|
292
|
+
*/
|
|
293
|
+
serialize(): Promise<{
|
|
294
|
+
bytes: Uint8Array<ArrayBuffer>;
|
|
295
|
+
revision: number;
|
|
296
|
+
}>;
|
|
297
|
+
/**
|
|
298
|
+
* The document as file bytes with its replica taken at the same moment (null when the engine
|
|
299
|
+
* has none to give), so the stored replica holds exactly what the file does, and the revision
|
|
300
|
+
* they hold (see `serialize`).
|
|
301
|
+
*/
|
|
302
|
+
saveWithReplica(): Promise<{
|
|
303
|
+
bytes: Uint8Array<ArrayBuffer>;
|
|
304
|
+
replica: KitModuleReplica | null;
|
|
305
|
+
revision: number;
|
|
306
|
+
}>;
|
|
307
|
+
/** The replica's version; the engine makes its replica now if it has none yet. */
|
|
308
|
+
replicaVersion(): Promise<ArrayBuffer>;
|
|
309
|
+
/** The replica's changes since `since` (empty: all of them) and every blob they may need. */
|
|
310
|
+
replicaExport(since: ArrayBuffer): Promise<{
|
|
311
|
+
changes: ArrayBuffer;
|
|
312
|
+
blobs: ArrayBuffer;
|
|
313
|
+
}>;
|
|
314
|
+
/** Imports another replica's changes (and their blobs) into the document; answers the damage. */
|
|
315
|
+
replicaImport(changes: ArrayBuffer, blobs: ArrayBuffer): Promise<unknown>;
|
|
316
|
+
/** The replica's own id (the kit module's `docId`), or `null` when the engine has none. */
|
|
317
|
+
replicaDocId(): Promise<string | null>;
|
|
318
|
+
/**
|
|
319
|
+
* Takes a draft's changes (and their blobs) into the document as one step of its undo history,
|
|
320
|
+
* recorded as `origin` (Kit UI protocol section 7d); `schema` is the kit's, as the host sends it.
|
|
321
|
+
* Answers what changed. A refusal rejects with a `KitModelError`.
|
|
322
|
+
*/
|
|
323
|
+
replicaMerge(changes: ArrayBuffer, blobs: ArrayBuffer, origin: Origin, schema: object | null): Promise<DraftSummary>;
|
|
324
|
+
/** What merging a draft's changes would change in the document now. */
|
|
325
|
+
replicaCompare(changes: ArrayBuffer, schema: object | null): Promise<DraftSummary>;
|
|
326
|
+
/** The replica's version, base64 (C3b): what `modelChanges` takes back. */
|
|
327
|
+
modelVersion(): Promise<string>;
|
|
328
|
+
premiseRead(name: string, params: Record<string, unknown>): Promise<unknown>;
|
|
329
|
+
inspectAt(context: KitCallContext, part?: number): Promise<{
|
|
330
|
+
details: Record<string, unknown>;
|
|
331
|
+
part?: unknown;
|
|
332
|
+
}>;
|
|
333
|
+
/**
|
|
334
|
+
* What changed since the replica version `since` (base64), with the version now: a change set,
|
|
335
|
+
* or `null` and why when the replica's history does not hold `since` (C3b, as Kit Process
|
|
336
|
+
* Protocol's `model.changes`). `schema` is the host's, as for `modelDescribe`.
|
|
337
|
+
*/
|
|
338
|
+
modelChanges(since: string, schema: object | null): Promise<KitModelChanges>;
|
|
339
|
+
/** `model/describe` (`kitModel.ts`); `schema` is the host's, for an engine that does not describe its own. */
|
|
340
|
+
modelDescribe(schema: object | null): Promise<Record<string, unknown>>;
|
|
341
|
+
agentReply<T>(value: T): Promise<T>;
|
|
342
|
+
/**
|
|
343
|
+
* `model/batch`: answers `{ refs, results, loaded, version }`, `version` the replica's after it
|
|
344
|
+
* (null when there is none). A refused batch rejects with a `KitModelError`.
|
|
345
|
+
*/
|
|
346
|
+
modelBatch(request: Record<string, unknown>, schema: object | null): Promise<ModelBatchResult>;
|
|
347
|
+
/**
|
|
348
|
+
* Marks the document saved; with `revision` (what `serialize` answered) only if it has not
|
|
349
|
+
* changed since, so an edit that reached the engine after the bytes were taken stays unsaved.
|
|
350
|
+
*/
|
|
351
|
+
markSaved(revision?: number): Promise<void>;
|
|
352
|
+
/** Brings `info` up to date after changes it does not follow (an `invoke` that edits, such as a merge of the file). */
|
|
353
|
+
refreshInfo(): Promise<KitEngineInfo>;
|
|
354
|
+
/**
|
|
355
|
+
* Calls one of the kit module's own document methods beyond the shared contract, for example
|
|
356
|
+
* Photo's `selectionOutline`. Typed-array results arrive as that array. Changes made this way
|
|
357
|
+
* are not reflected in `info`; use `execute` for edits.
|
|
358
|
+
*/
|
|
359
|
+
invoke<T = unknown>(name: string, ...args: unknown[]): Promise<T>;
|
|
360
|
+
/**
|
|
361
|
+
* Calls one of the engine's tool methods and returns its parsed answer. `info` is brought up
|
|
362
|
+
* to date when the call changed the document, or always when `settled` (the end of a gesture,
|
|
363
|
+
* which may change only the selection); mid-drag calls skip that, since `inspect()` costs.
|
|
364
|
+
*/
|
|
365
|
+
tool<T = unknown>(name: KitToolMethod, args?: unknown[], settled?: boolean): Promise<{
|
|
366
|
+
value: T;
|
|
367
|
+
changed: boolean;
|
|
368
|
+
}>;
|
|
369
|
+
dispose(): void;
|
|
370
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One open kit document in its own worker: the kit's SDK decodes, renders,
|
|
3
|
+
* edits, and encodes here, so the page stays responsive however large the
|
|
4
|
+
* file is, and a failing engine cannot take the page down. Requests are
|
|
5
|
+
* answered in the order they arrive.
|
|
6
|
+
*/
|
|
7
|
+
import { type KitModuleDocument } from './kitModule.js';
|
|
8
|
+
import type { KitEngineRequest, KitEngineSchema } from './kitEngine.js';
|
|
9
|
+
export declare function premisePlan(params: Record<string, unknown>, source?: KitModuleDocument, planSchema?: object): Promise<unknown>;
|
|
10
|
+
/** The SDK's own `docId` (`replica/info`, protocol minor version 1.3), or `null` when the
|
|
11
|
+
* engine's document has none. */
|
|
12
|
+
export declare function replicaDocId(open: KitModuleDocument): string | null;
|
|
13
|
+
/**
|
|
14
|
+
* The blobs a `replicaExport` sends alongside its changes: only what changed since `since` when
|
|
15
|
+
* the SDK can tell narrower than its whole bundle (`blobsSince`, protocol minor version 1.3),
|
|
16
|
+
* else every blob the replica references.
|
|
17
|
+
*/
|
|
18
|
+
export declare function replicaBlobsSince(open: KitModuleDocument, since: Uint8Array): Uint8Array;
|
|
19
|
+
/**
|
|
20
|
+
* The schema the engine's replica reads and the newest one its changes were written under
|
|
21
|
+
* (KitModel rule M5a), for an engine that answers both and has made its replica (asking
|
|
22
|
+
* would make it); `null` otherwise. Read when a document opens and after imports: the person's
|
|
23
|
+
* own edits are written under the replica's own schema.
|
|
24
|
+
*/
|
|
25
|
+
export declare function readSchema(open: KitModuleDocument): KitEngineSchema | null;
|
|
26
|
+
/** Answers one request; exported for tests (the worker answers through `onmessage`). */
|
|
27
|
+
export declare function handle(request: KitEngineRequest): Promise<{
|
|
28
|
+
value: unknown;
|
|
29
|
+
transfer?: Transferable[];
|
|
30
|
+
}>;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/** A document's KDM replica (snapshot and blobs) and the stamp of the file it was saved with. */
|
|
2
|
+
export type KitStoredReplica = {
|
|
3
|
+
snapshot: ArrayBuffer;
|
|
4
|
+
blobs: ArrayBuffer;
|
|
5
|
+
fileStamp: string;
|
|
6
|
+
};
|
|
7
|
+
/**
|
|
8
|
+
* How a kit editor reaches the file it edits. Kition reads workspace files
|
|
9
|
+
* over its loopback API and writes them through `PUT /v1/kits/files`; another
|
|
10
|
+
* host supplies its own. Version stamps (an `etag`, or time and size) let the
|
|
11
|
+
* editor notice when something else, such as an agent, replaced the file.
|
|
12
|
+
*/
|
|
13
|
+
export type KitHost = {
|
|
14
|
+
/** The file's bytes and the stamp of that version. */
|
|
15
|
+
read: (path: string) => Promise<{
|
|
16
|
+
bytes: ArrayBuffer;
|
|
17
|
+
stamp: string | null;
|
|
18
|
+
}>;
|
|
19
|
+
/** The stamp of the file's current version, or null when it cannot tell. */
|
|
20
|
+
stamp: (path: string) => Promise<string | null>;
|
|
21
|
+
/** Replaces the file with `bytes` only if `expected` still matches; answers the new stamp. */
|
|
22
|
+
write: (path: string, bytes: Uint8Array, expected?: string | null) => Promise<string | null | void>;
|
|
23
|
+
/**
|
|
24
|
+
* The document's replica as the host stored it with the file it was saved with (the Kit UI
|
|
25
|
+
* protocol's `replica` capability), or null. Absent: the host keeps no replicas.
|
|
26
|
+
*/
|
|
27
|
+
replicaRead?: (path: string) => Promise<KitStoredReplica | null>;
|
|
28
|
+
/** Stores the document's replica with the stamp of the file it belongs to. */
|
|
29
|
+
replicaWrite?: (path: string, replica: KitStoredReplica) => Promise<void>;
|
|
30
|
+
/**
|
|
31
|
+
* Where the document at `path` may read the other files it names (lent files): an absolute
|
|
32
|
+
* URL of the workspace root that serves ranged reads, and the document's folder in it. Absent:
|
|
33
|
+
* documents read no other files.
|
|
34
|
+
*/
|
|
35
|
+
lend?: (path: string) => {
|
|
36
|
+
root: string;
|
|
37
|
+
folder: string;
|
|
38
|
+
} | null;
|
|
39
|
+
};
|
|
40
|
+
/** A version stamp from HTTP headers: the validator, or the time and size. */
|
|
41
|
+
export declare function stampFromHeaders(headers: Headers): string | null;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The object model (`KitObjectModel 1.0`) answered by the kit itself: the Kit UI protocol's
|
|
3
|
+
* capability `model` (Kition platform docs/platform/reference/ui-protocol.md section 7a), so a script's batch is a step of the
|
|
4
|
+
* person's own undo history rather than a collaborator's change. This module is what the page and
|
|
5
|
+
* the worker share; the worker runs batches in `kitModelRunner.ts`.
|
|
6
|
+
*
|
|
7
|
+
* Two ways in, by what the kit's engine offers:
|
|
8
|
+
* - `engine`: the engine answers `modelDescribe()` and `modelBatch(json)` itself
|
|
9
|
+
* (`export_kit_session!`); a batch is one undo group of its session.
|
|
10
|
+
* - `replica`: any contract 2 engine (it exchanges changes): the worker keeps a scratch replica of
|
|
11
|
+
* the document, runs each run of model operations as one transaction on it, and hands the
|
|
12
|
+
* changes to the engine. Those steps are kept in a script history next to the engine's own, so
|
|
13
|
+
* Undo and Redo reach them in order (see `ReplicaModel`).
|
|
14
|
+
*/
|
|
15
|
+
import type { ModelErrorData } from '@kition/kit-ui-protocol';
|
|
16
|
+
import type { KitModuleDocument } from './kitModule.js';
|
|
17
|
+
export type { ModelErrorData };
|
|
18
|
+
/** How a kit's engine answers the object model, if it does. */
|
|
19
|
+
export type KitModelSupport = 'engine' | 'replica' | null;
|
|
20
|
+
export declare function modelSupport(open: KitModuleDocument): KitModelSupport;
|
|
21
|
+
/** A refused batch: `data` is the protocol's `{ code, index, message }`. */
|
|
22
|
+
export declare class KitModelError extends Error {
|
|
23
|
+
readonly data: ModelErrorData;
|
|
24
|
+
constructor(data: ModelErrorData);
|
|
25
|
+
}
|
|
26
|
+
/** Whether a batch request writes: every operation does; `load` alone only reads. */
|
|
27
|
+
export declare function batchWrites(request: {
|
|
28
|
+
ops?: unknown;
|
|
29
|
+
}): boolean;
|
|
30
|
+
/** The history commands, by id (as `READ_ONLY_RULES.editingCommands` lists them). */
|
|
31
|
+
export declare const UNDO_COMMANDS: ReadonlySet<string>;
|
|
32
|
+
export declare const REDO_COMMANDS: ReadonlySet<string>;
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The object model over a contract 2 engine's change exchange, run in the kit's engine worker
|
|
3
|
+
* (see `kitModel.ts`). Loaded on the first `model/*` request: it brings `@kition/kdm` and Loro.
|
|
4
|
+
*
|
|
5
|
+
* It imports no value from the worker's other modules: a bundler puts those in the worker's
|
|
6
|
+
* entry chunk, and WebKit evaluates a module worker's entry script again when a chunk imports
|
|
7
|
+
* it, replacing the worker's message handler with one that has no document open.
|
|
8
|
+
*/
|
|
9
|
+
import { type BatchRequest, type BatchResult, type Origin, type StateDiff } from '@kition/kdm';
|
|
10
|
+
import type { ModelErrorData } from '@kition/kit-ui-protocol';
|
|
11
|
+
import type { KitModuleDocument } from './kitModule.js';
|
|
12
|
+
/** A failure as the protocol answers it. */
|
|
13
|
+
export declare function modelErrorData(error: unknown): ModelErrorData;
|
|
14
|
+
/** Runs a command of a batch as its origin, when the engine can (`executeAs`); answers its parsed result. */
|
|
15
|
+
export declare function runAs(open: KitModuleDocument, id: string, params: unknown, origin: Origin): unknown;
|
|
16
|
+
/**
|
|
17
|
+
* The object model of an engine that exchanges changes but does not answer it itself. A scratch
|
|
18
|
+
* replica of the document (its own actor) is caught up with the engine's changes before every
|
|
19
|
+
* read and write; each run of a batch's model operations is one transaction on it, whose changes
|
|
20
|
+
* the engine imports. Its commands run in the engine as the batch's origin.
|
|
21
|
+
*
|
|
22
|
+
* The engine takes those changes as a collaborator's, outside its own undo history, so the script
|
|
23
|
+
* steps are kept here: each is undone and redone through the scratch replica's own undo (which
|
|
24
|
+
* keeps everything else that changed since), and the engine's Undo reaches them in order. A step
|
|
25
|
+
* is the next to undo when the document is as it left it (its state's digest), or when the engine
|
|
26
|
+
* has nothing left to undo; otherwise the engine's own last step goes first. The same holds for
|
|
27
|
+
* Redo. An edit of the person's own drops the steps to redo.
|
|
28
|
+
*
|
|
29
|
+
* Each step also records its writes by object identity. When an engine step removed an object a
|
|
30
|
+
* step undone had changed and another brought it back (Undo past the command that made it, then
|
|
31
|
+
* Redo), the object is a new one to the scratch replica's history, which no longer reaches it:
|
|
32
|
+
* Redo then makes the step's writes again, as a new transaction (whose Undo is the scratch
|
|
33
|
+
* replica's again).
|
|
34
|
+
*/
|
|
35
|
+
export declare class ReplicaModel {
|
|
36
|
+
private readonly open;
|
|
37
|
+
private scratch;
|
|
38
|
+
private schema;
|
|
39
|
+
private schemaText;
|
|
40
|
+
/** The script steps to undo, each with the digest of the document as it left it, oldest first. */
|
|
41
|
+
private undoSteps;
|
|
42
|
+
/** The steps undone, each with the digest of the document as undoing it left it, the next to redo last. */
|
|
43
|
+
private redoSteps;
|
|
44
|
+
constructor(open: KitModuleDocument);
|
|
45
|
+
/** Translate replies using the native model description or the host-supplied schema. */
|
|
46
|
+
reply(value: unknown): unknown;
|
|
47
|
+
canUndo(): boolean;
|
|
48
|
+
canRedo(): boolean;
|
|
49
|
+
/** The person edited the document: the script steps undone so far cannot be redone. */
|
|
50
|
+
dropRedo(): void;
|
|
51
|
+
/** `model/describe`: the schema, the root's id, and the engine's commands. */
|
|
52
|
+
forkForPremises(open: KitModuleDocument): ReplicaModel;
|
|
53
|
+
/** `model/describe`: the schema, the root's id, and the engine's commands. */
|
|
54
|
+
describe(schema: object | null | undefined): Record<string, unknown>;
|
|
55
|
+
/** `model/batch`. */
|
|
56
|
+
batch(request: BatchRequest, schema: object | null | undefined, readOnly: boolean): Promise<BatchResult>;
|
|
57
|
+
/**
|
|
58
|
+
* Takes an agent's draft into the document (Kit UI protocol section 7d): its changes since it
|
|
59
|
+
* was forked are merged into the scratch replica as one transaction of `origin`, which the
|
|
60
|
+
* engine imports. It is a script step: the editor's Undo takes the whole merge back. Answers
|
|
61
|
+
* what it changed.
|
|
62
|
+
*/
|
|
63
|
+
merge(changes: Uint8Array, origin: Origin, schema: object | null | undefined): StateDiff;
|
|
64
|
+
/**
|
|
65
|
+
* What changed in the document since the replica version `since` (C3b, as Kit Process Protocol's
|
|
66
|
+
* `model.changes`): the change set `@kition/kdm`'s `changesSince` answers, or no change set and
|
|
67
|
+
* why when the replica's history does not hold `since` (never an empty one in its place).
|
|
68
|
+
*/
|
|
69
|
+
changesSince(since: Uint8Array, schema: object | null | undefined): {
|
|
70
|
+
changes: StateDiff;
|
|
71
|
+
} | {
|
|
72
|
+
changes: null;
|
|
73
|
+
unavailable: string;
|
|
74
|
+
};
|
|
75
|
+
/** What merging a draft's `changes` would change in the document now, without merging them. */
|
|
76
|
+
compare(changes: Uint8Array, schema: object | null | undefined): StateDiff;
|
|
77
|
+
/** Undoes the last script step when it comes before the engine's own; answers whether it did. */
|
|
78
|
+
undo(engineCanUndo: boolean): boolean;
|
|
79
|
+
/** Redoes the last script step undone when it comes before the engine's own; answers whether it did. */
|
|
80
|
+
redo(engineCanRedo: boolean): boolean;
|
|
81
|
+
/**
|
|
82
|
+
* The engine undid or redid a step of its own. When it removed an object a script step undone
|
|
83
|
+
* had changed, the scratch replica's redo no longer reaches that object, even once it is back.
|
|
84
|
+
*/
|
|
85
|
+
engineMoved(): void;
|
|
86
|
+
private travel;
|
|
87
|
+
private useSchema;
|
|
88
|
+
private forget;
|
|
89
|
+
private catchUp;
|
|
90
|
+
private state;
|
|
91
|
+
/** One run of model operations: a transaction on the scratch replica, then in the engine. */
|
|
92
|
+
private step;
|
|
93
|
+
}
|