@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,173 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The engine contract from JavaScript (Kition platform docs/platform/reference/contract.md): how a kit's engine, compiled to
|
|
3
|
+
* WebAssembly or written in TypeScript (`ts-worker`), is loaded and opened. Every kit exposes the same document class shape, so one
|
|
4
|
+
* worker, one client, and one document hook serve every kit.
|
|
5
|
+
*/
|
|
6
|
+
/** One engine command, as the editor's menus and shortcuts show it. */
|
|
7
|
+
export type KitCommand = {
|
|
8
|
+
id: string;
|
|
9
|
+
title: string;
|
|
10
|
+
/** What the command does, when to choose it, and what it changes or answers (KitCommand::description); null when the kit has not said. */
|
|
11
|
+
description: string | null;
|
|
12
|
+
/** The command's family, the id's first segment. */
|
|
13
|
+
group: string;
|
|
14
|
+
mutates: boolean;
|
|
15
|
+
enabled: boolean;
|
|
16
|
+
/** The menu path, for example ["Layer", "New"]; empty when it is not in a menu. */
|
|
17
|
+
menu: string[];
|
|
18
|
+
/** As `Cmd+Shift+N`; `Cmd` is Control off macOS. */
|
|
19
|
+
shortcut: string | null;
|
|
20
|
+
/** The parameters as a DeepSeek Harness `ParameterSchemaSpec`; commands with one can be agent tools. */
|
|
21
|
+
schema?: Record<string, unknown> | null;
|
|
22
|
+
/** What the command answers, as one `ValueSchemaSpec` (KHP A1 `output.schema`); hosts send it as the tool's MCP `outputSchema`. */
|
|
23
|
+
outputSchema?: Record<string, unknown> | null;
|
|
24
|
+
/** The engine's own parameter notes, as the agent reads them. */
|
|
25
|
+
params?: string | null;
|
|
26
|
+
/** Words an agent's command search finds it by that its title and params do not say (the effect names `effect.apply` takes); searched, never shown. */
|
|
27
|
+
keywords?: string[] | null;
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* How the engine is built (`engine.runtime` in kit.json, rule K11): `rust-wasm`, a wasm-pack
|
|
31
|
+
* module (`<module>.js` and `<module>_bg.wasm`), or `ts-worker`, an ES module `<module>.js` whose
|
|
32
|
+
* default export prepares it given `{ base }` (`@kition/kit-engine`'s `KitEngineInit`).
|
|
33
|
+
*/
|
|
34
|
+
export type KitModuleRuntime = 'rust-wasm' | 'ts-worker';
|
|
35
|
+
/** Where a kit's engine module lives: `<base>/<module>.js`, and `<module>_bg.wasm` for a Rust engine. */
|
|
36
|
+
export type KitModuleManifest = {
|
|
37
|
+
/** The kit id, for example `kit.photo`. */
|
|
38
|
+
kitId: string;
|
|
39
|
+
/** The folder holding the module, as a URL (absolute, or relative to the page). */
|
|
40
|
+
base?: string;
|
|
41
|
+
/** Without `base`: the folder under the host's `/kits/` (host-drawn editors). */
|
|
42
|
+
dir?: string;
|
|
43
|
+
/** The wasm-pack module name, for example `kition_photo_kit`. */
|
|
44
|
+
module: string;
|
|
45
|
+
/** The exported document class, for example `PhotoDocument`. */
|
|
46
|
+
documentClass: string;
|
|
47
|
+
/** `rust-wasm` when absent. */
|
|
48
|
+
runtime?: KitModuleRuntime;
|
|
49
|
+
/**
|
|
50
|
+
* Extra methods (declared `extras`) the worker calls on every document it opens or makes,
|
|
51
|
+
* before the first render: an embedded editor's view options, such as one slide at a time.
|
|
52
|
+
*/
|
|
53
|
+
setup?: Array<{
|
|
54
|
+
method: string;
|
|
55
|
+
args: unknown[];
|
|
56
|
+
}>;
|
|
57
|
+
/**
|
|
58
|
+
* Font files (URLs) given to the engine's `addFont(bytes)` once it loads, before any document
|
|
59
|
+
* opens: faces for scripts the engine does not embed (a CJK font in a web build). One that does
|
|
60
|
+
* not load is skipped; text in it shows in the engine's own faces.
|
|
61
|
+
*/
|
|
62
|
+
fonts?: string[];
|
|
63
|
+
/**
|
|
64
|
+
* The commands that write only comment threads (KitModel rule M23): the kit's
|
|
65
|
+
* `kit.json` `collaboration.comments.commands`. A commenter's read-only session runs them (the
|
|
66
|
+
* Kit UI protocol's `document.comments.canComment`); see `readOnly.ts`.
|
|
67
|
+
*/
|
|
68
|
+
commentCommands?: readonly string[];
|
|
69
|
+
};
|
|
70
|
+
/** One open document, as every kit module exposes it to JavaScript. */
|
|
71
|
+
export interface KitModuleDocument {
|
|
72
|
+
readonly width: number;
|
|
73
|
+
readonly height: number;
|
|
74
|
+
/** Bands that stay in view while the rest scrolls, in document pixels (Standard E10); optional. */
|
|
75
|
+
readonly pinnedLeft?: number;
|
|
76
|
+
readonly pinnedTop?: number;
|
|
77
|
+
/** Moves with every change. */
|
|
78
|
+
readonly revision: bigint;
|
|
79
|
+
readonly dirty: boolean;
|
|
80
|
+
/** RGBA8 of the area at (`x`, `y`) document pixels shown at `scale` screen pixels per pixel. */
|
|
81
|
+
render(x: number, y: number, scale: number, width: number, height: number): Uint8Array;
|
|
82
|
+
/** RGBA8 of the document area (`x0`, `y0`)–(`x1`, `y1`), averaged down to exactly `width` × `height`. */
|
|
83
|
+
renderArea(x0: number, y0: number, x1: number, y1: number, width: number, height: number): Uint8Array;
|
|
84
|
+
/** Runs an engine command with JSON parameters; returns its JSON result. */
|
|
85
|
+
execute(command: string, params: string): string;
|
|
86
|
+
/** The document as JSON; it includes `canUndo` and `canRedo`. */
|
|
87
|
+
inspect(): string;
|
|
88
|
+
/** Every command as JSON: id, title, menu path, shortcut, mutates, enabled. */
|
|
89
|
+
commands(): string;
|
|
90
|
+
/** The ids of the commands that cannot run now, as JSON; optional in contract 1. */
|
|
91
|
+
disabledCommands?(): string;
|
|
92
|
+
/** The document's diagnostics as JSON `{ diagnostics: [...] }` (KHP A21); optional, engines before it have none. */
|
|
93
|
+
check?(): string;
|
|
94
|
+
/** The next chunk of a file a command produced (engine contract E16), at most `max` bytes; optional, engines before it make none. */
|
|
95
|
+
takeOutput?(id: string, max?: number): Uint8Array;
|
|
96
|
+
/** The document as file bytes; it stays unsaved until `markSaved`. */
|
|
97
|
+
save(name?: string): Uint8Array;
|
|
98
|
+
/** Records that the bytes from the last `save` reached the file. */
|
|
99
|
+
markSaved(): void;
|
|
100
|
+
free(): void;
|
|
101
|
+
/** Whether the document has made its replica yet (it makes one lazily); absent: it always has one. */
|
|
102
|
+
readonly hasReplica?: boolean;
|
|
103
|
+
/** The replica's version; makes the replica if there is none yet. */
|
|
104
|
+
version?(): Uint8Array;
|
|
105
|
+
exportChanges?(since: Uint8Array): Uint8Array;
|
|
106
|
+
/** Answers the damage as JSON. Add the changes' blobs first. */
|
|
107
|
+
importChanges?(changes: Uint8Array): string;
|
|
108
|
+
snapshot?(): Uint8Array;
|
|
109
|
+
/** Every blob the replica references, for `addBlobs`. */
|
|
110
|
+
blobs?(): Uint8Array;
|
|
111
|
+
/** Only the blobs new changes since `since` may need, when the engine can tell; narrower than
|
|
112
|
+
* `blobs()` for a client that already has most of them. Protocol minor version 1.3. */
|
|
113
|
+
blobsSince?(since: Uint8Array): Uint8Array;
|
|
114
|
+
addBlobs?(blobs: Uint8Array): void;
|
|
115
|
+
/** The replica's own id (a sync room's `docId`), when the engine's document is tied to one.
|
|
116
|
+
* Protocol minor version 1.3; absent (not merely empty) means the engine has none. */
|
|
117
|
+
readonly docId?: string;
|
|
118
|
+
/** Undo and redo of the engine's own history (contract 2); `undo()` answers `{"done", "damage"}`. */
|
|
119
|
+
canUndo?(): boolean;
|
|
120
|
+
canRedo?(): boolean;
|
|
121
|
+
/** Runs a command as `origin`, the KDM's commit form `[kind, principal, label]` (contract 2). */
|
|
122
|
+
executeAs?(command: string, params: string, origin: string): string;
|
|
123
|
+
/** The schema version the replica reads (its kit's `model.schemaVersion`). */
|
|
124
|
+
schemaVersion?(): number;
|
|
125
|
+
/**
|
|
126
|
+
* The newest schema version any of the replica's changes was written under (KitModel
|
|
127
|
+
* rule M5a); `null` or `undefined` when none records one. Above `schemaVersion()`, a newer kit
|
|
128
|
+
* edited the document: the editor tells its host (`document/schema`).
|
|
129
|
+
*/
|
|
130
|
+
authorSchemaVersion?(): number | null | undefined;
|
|
131
|
+
/**
|
|
132
|
+
* The object model answered by the engine itself (`export_kit_session!`): JSON text in and out.
|
|
133
|
+
* A batch is one undo step; a refused one throws an error whose message is `{code, index, message}`.
|
|
134
|
+
*/
|
|
135
|
+
modelDescribe?(): string;
|
|
136
|
+
modelBatch?(request: string): string;
|
|
137
|
+
/**
|
|
138
|
+
* The editor state that is not the document (selection, current part, current time), as JSON
|
|
139
|
+
* (`KitDocument::editor_state`); `"null"` for a kit that keeps none. Optional: engines before
|
|
140
|
+
* the call context have none.
|
|
141
|
+
*/
|
|
142
|
+
editorState?(): string;
|
|
143
|
+
/** Puts back what `editorState()` answered (`KitDocument::restore_editor_state`). */
|
|
144
|
+
restoreEditorState?(state: string): void;
|
|
145
|
+
/** Sets the editor state one command reads from a call context `{on?, part?, time?}` as JSON (`KitDocument::set_context`). */
|
|
146
|
+
setContext?(context: string): void;
|
|
147
|
+
/** Read-only guard callback (`under`, `covered`, `content`, `derived`, `identity`, `inputs`), JSON in and out. */
|
|
148
|
+
premiseRead?(method: string, params: string): string;
|
|
149
|
+
forkForPremises?(): KitModuleDocument;
|
|
150
|
+
}
|
|
151
|
+
/** A stored replica to open a file with: a snapshot and its blobs. */
|
|
152
|
+
export type KitModuleReplica = {
|
|
153
|
+
snapshot: ArrayBuffer;
|
|
154
|
+
blobs: ArrayBuffer;
|
|
155
|
+
};
|
|
156
|
+
type KitModuleExports = {
|
|
157
|
+
default: (input?: {
|
|
158
|
+
module_or_path?: string | URL;
|
|
159
|
+
}) => Promise<unknown>;
|
|
160
|
+
} & Record<string, {
|
|
161
|
+
open(name: string, bytes: Uint8Array): KitModuleDocument;
|
|
162
|
+
} | unknown>;
|
|
163
|
+
/** Loads and starts a kit's SDK once per page or worker. */
|
|
164
|
+
export declare function loadKitModule(manifest: KitModuleManifest): Promise<KitModuleExports>;
|
|
165
|
+
/** Opens file bytes with a loaded SDK's document class, with their stored replica when given and the SDK takes one. */
|
|
166
|
+
export declare function openKitModuleDocument(module: KitModuleExports, manifest: KitModuleManifest, name: string, bytes: Uint8Array, replica?: KitModuleReplica | null): KitModuleDocument;
|
|
167
|
+
/** A new, empty document of the SDK's own making (New image, New video project). */
|
|
168
|
+
export declare function createKitModuleDocument(module: KitModuleExports, manifest: KitModuleManifest, name: string, width: number, height: number): KitModuleDocument;
|
|
169
|
+
/** Whether a kit's SDK is built into this app (a missing file falls back to the app page). */
|
|
170
|
+
export declare function kitModuleAvailable(manifest: KitModuleManifest): Promise<boolean>;
|
|
171
|
+
/** A kit's commands from its SDK's `commands()` JSON. */
|
|
172
|
+
export declare function kitModuleCommands(json: string): KitCommand[];
|
|
173
|
+
export {};
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { KitCommand } from './kitModule.js';
|
|
2
|
+
/**
|
|
3
|
+
* Shortcuts Kition itself owns, written as kits write them; a kit command never takes them. A kit
|
|
4
|
+
* with its own key router drops its bindings that match one of these (and the host's
|
|
5
|
+
* `init.shortcuts`), so the host's key still reaches the host. `Cmd+.` opens Kition's command
|
|
6
|
+
* palette from inside a kit (Cmd+K stays the kit's: Word, Slide, and Sheet insert links with it).
|
|
7
|
+
*/
|
|
8
|
+
export declare const RESERVED_SHORTCUTS: ReadonlySet<string>;
|
|
9
|
+
type KeyLike = {
|
|
10
|
+
key: string;
|
|
11
|
+
code: string;
|
|
12
|
+
metaKey: boolean;
|
|
13
|
+
ctrlKey: boolean;
|
|
14
|
+
shiftKey: boolean;
|
|
15
|
+
altKey: boolean;
|
|
16
|
+
};
|
|
17
|
+
/**
|
|
18
|
+
* Whether `event` is `shortcut`, written as kits write it: `Cmd+Shift+Z`, `Alt+Backspace`, `F12`.
|
|
19
|
+
* `Delete` also answers to Backspace (the Mac delete key) unless `exact`.
|
|
20
|
+
*/
|
|
21
|
+
export declare function shortcutMatches(shortcut: string, event: KeyLike, mac?: boolean, exact?: boolean): boolean;
|
|
22
|
+
/**
|
|
23
|
+
* Whether the frame binds `shortcut`: with a modifier, or Delete, Backspace, Page Up, Page Down,
|
|
24
|
+
* or a function key; never Kition's own.
|
|
25
|
+
*/
|
|
26
|
+
export declare function bindableShortcut(shortcut: string | null): shortcut is string;
|
|
27
|
+
/**
|
|
28
|
+
* The command whose shortcut is `event`, if any, whether or not it can run now. An exact key wins
|
|
29
|
+
* over the Delete and Backspace alias (Film binds both, to different commands).
|
|
30
|
+
*/
|
|
31
|
+
export declare function commandForShortcut(commands: readonly KitCommand[], event: KeyLike, mac?: boolean): KitCommand | undefined;
|
|
32
|
+
export {};
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import type { RasterViewport } from './rasterViewport.js';
|
|
2
|
+
/** One pointer sample, in document pixels and in client pixels. */
|
|
3
|
+
export type KitPointer = {
|
|
4
|
+
x: number;
|
|
5
|
+
y: number;
|
|
6
|
+
pressure: number;
|
|
7
|
+
clientX: number;
|
|
8
|
+
clientY: number;
|
|
9
|
+
/** The pointer in the canvas's CSS pixels, for placing HTML over it. */
|
|
10
|
+
canvasX: number;
|
|
11
|
+
canvasY: number;
|
|
12
|
+
shift: boolean;
|
|
13
|
+
alt: boolean;
|
|
14
|
+
meta: boolean;
|
|
15
|
+
};
|
|
16
|
+
/** Draws a tool's live preview above the canvas, in canvas CSS pixels. */
|
|
17
|
+
export type KitOverlay = {
|
|
18
|
+
/** Clears the preview and draws `paint`; `toScreen` maps document points to the canvas. */
|
|
19
|
+
draw: (paint: (context: CanvasRenderingContext2D, toScreen: (x: number, y: number) => {
|
|
20
|
+
x: number;
|
|
21
|
+
y: number;
|
|
22
|
+
}) => void) => void;
|
|
23
|
+
/** Draws more on top of the current preview (strokes accumulate). */
|
|
24
|
+
add: (paint: (context: CanvasRenderingContext2D, toScreen: (x: number, y: number) => {
|
|
25
|
+
x: number;
|
|
26
|
+
y: number;
|
|
27
|
+
}) => void) => void;
|
|
28
|
+
clear: () => void;
|
|
29
|
+
};
|
|
30
|
+
/** What a tool can reach while it handles the pointer. */
|
|
31
|
+
export type KitToolContext = {
|
|
32
|
+
viewport: RasterViewport;
|
|
33
|
+
overlay: KitOverlay;
|
|
34
|
+
};
|
|
35
|
+
/** One drag, from pointer down to release. */
|
|
36
|
+
export type KitGesture = {
|
|
37
|
+
move?: (pointer: KitPointer, context: KitToolContext) => void;
|
|
38
|
+
/** The release; the overlay stays until the next document change has painted, unless cleared. */
|
|
39
|
+
end?: (pointer: KitPointer, context: KitToolContext) => void;
|
|
40
|
+
cancel?: (context: KitToolContext) => void;
|
|
41
|
+
};
|
|
42
|
+
/**
|
|
43
|
+
* A canvas tool: it turns pointer gestures into engine commands. `begin` gets
|
|
44
|
+
* the press; returning a gesture receives the moves and the release.
|
|
45
|
+
*/
|
|
46
|
+
export type KitTool = {
|
|
47
|
+
id: string;
|
|
48
|
+
cursor: string;
|
|
49
|
+
begin: (pointer: KitPointer, context: KitToolContext) => KitGesture | void;
|
|
50
|
+
/** The pointer moved with no button held (hover feedback, an open path's rubber band). */
|
|
51
|
+
hover?: (pointer: KitPointer, context: KitToolContext) => void;
|
|
52
|
+
/**
|
|
53
|
+
* The pointer moved over the canvas, whatever it is doing: hovering, in a gesture of this tool,
|
|
54
|
+
* or panning the view (Space or the middle button). For readouts of the pointer's place
|
|
55
|
+
* (Photoshop's Info panel); `hover` is the tool's own feedback.
|
|
56
|
+
*/
|
|
57
|
+
track?: (pointer: KitPointer, context: KitToolContext) => void;
|
|
58
|
+
/** The pointer left the canvas with no gesture held. */
|
|
59
|
+
leave?: (context: KitToolContext) => void;
|
|
60
|
+
/** A double click, after its two presses reached `begin`. */
|
|
61
|
+
doubleClick?: (pointer: KitPointer, context: KitToolContext) => void;
|
|
62
|
+
};
|
|
63
|
+
/** Drags the view. The canvas also uses it for Space and the middle button. */
|
|
64
|
+
export declare const HAND_TOOL: KitTool;
|
|
65
|
+
/** Click to zoom in at the pointer, Alt-click to zoom out. */
|
|
66
|
+
export declare const ZOOM_TOOL: KitTool;
|
|
67
|
+
/** A rectangle from two document points, normalised and rounded to whole pixels. */
|
|
68
|
+
export declare function dragRect(from: {
|
|
69
|
+
x: number;
|
|
70
|
+
y: number;
|
|
71
|
+
}, to: {
|
|
72
|
+
x: number;
|
|
73
|
+
y: number;
|
|
74
|
+
}, square?: boolean): {
|
|
75
|
+
x: number;
|
|
76
|
+
y: number;
|
|
77
|
+
width: number;
|
|
78
|
+
height: number;
|
|
79
|
+
};
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Lent files, the worker side: `globalThis.kitionHost`, which a kit module's Rust
|
|
3
|
+
* code calls through `kition_kit::host` to read the other files a document
|
|
4
|
+
* refers to (a film project's media). Reads are synchronous, as the engine
|
|
5
|
+
* needs them, which workers allow: ranged XMLHttpRequests against the host's
|
|
6
|
+
* file URL, cached in 1 MiB chunks so a long video is read once and in pieces.
|
|
7
|
+
* Errors are thrown as plain strings so the message reaches Rust.
|
|
8
|
+
*
|
|
9
|
+
* A file the person granted (engine contract E15) is named by its handle (`fh_…`), not a
|
|
10
|
+
* path: the binding reads it with `files/read` and lends its bytes here
|
|
11
|
+
* (`lendHandle`) before a command that names it runs.
|
|
12
|
+
*
|
|
13
|
+
* `exists` answers `kition_kit::host::exists`: `false` only when the host
|
|
14
|
+
* answers 404 for a path the binding let through, which a host does only for a
|
|
15
|
+
* path that passes every check of its confinement (Kit Process Protocol section
|
|
16
|
+
* 10, `file_not_found`); a path above the workspace or with a hidden segment
|
|
17
|
+
* (host contract LR2) is refused here, the same whether it exists or not.
|
|
18
|
+
*/
|
|
19
|
+
/** Where lent files come from: the workspace root URL, and the document's folder inside it. */
|
|
20
|
+
export type LentFiles = {
|
|
21
|
+
root: string;
|
|
22
|
+
folder: string;
|
|
23
|
+
};
|
|
24
|
+
/** Lends a granted file's bytes to the engine under its handle; `null` takes them back. */
|
|
25
|
+
export declare function lendHandle(handle: string, bytes: Uint8Array | null): void;
|
|
26
|
+
/** A workspace path for `file`, named by the document: relative to its folder, never above the root. */
|
|
27
|
+
export declare function resolveLentPath(folder: string, file: string): string;
|
|
28
|
+
/** Installs `globalThis.kitionHost` for one open document; `null` lends nothing. */
|
|
29
|
+
export declare function lendFiles(lent: LentFiles | null): void;
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
/** What the viewport needs from an engine: the document size and two render calls. */
|
|
2
|
+
export type RasterSource = {
|
|
3
|
+
readonly width: number;
|
|
4
|
+
readonly height: number;
|
|
5
|
+
/** Bands that stay in view while the rest scrolls (engine contract E10); none when absent. */
|
|
6
|
+
readonly pinned?: RasterPins;
|
|
7
|
+
render(x: number, y: number, scale: number, width: number, height: number): Promise<Uint8Array>;
|
|
8
|
+
renderArea(x0: number, y0: number, x1: number, y1: number, width: number, height: number): Promise<Uint8Array>;
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* The view: `zoom` screen pixels per image pixel, with image point (`x`, `y`) at the top-left.
|
|
12
|
+
* Along an axis with a pinned band, `x` (or `y`) is how far the rest is scrolled under the band.
|
|
13
|
+
*/
|
|
14
|
+
export type RasterView = {
|
|
15
|
+
zoom: number;
|
|
16
|
+
x: number;
|
|
17
|
+
y: number;
|
|
18
|
+
};
|
|
19
|
+
/** The columns left of `left` and the rows above `top` (document pixels) stay in view. */
|
|
20
|
+
export type RasterPins = {
|
|
21
|
+
left: number;
|
|
22
|
+
top: number;
|
|
23
|
+
};
|
|
24
|
+
/**
|
|
25
|
+
* A part of the canvas showing the document unscrolled along a pinned axis (`pinX`, `pinY`) or
|
|
26
|
+
* scrolled: document point (`dx`, `dy`) is at canvas point ((`dx` − `offX`) × zoom, …), shown
|
|
27
|
+
* within the canvas rectangle `clip` (CSS pixels) and covering document area `area`.
|
|
28
|
+
*/
|
|
29
|
+
export type RasterPane = {
|
|
30
|
+
pinX: boolean;
|
|
31
|
+
pinY: boolean;
|
|
32
|
+
offX: number;
|
|
33
|
+
offY: number;
|
|
34
|
+
clip: RasterRect;
|
|
35
|
+
area: RasterRect;
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* The panes of a `width` × `height` canvas at `view`: one, or with pinned bands up to four (the
|
|
39
|
+
* pinned corner, the pinned top and left bands, and the scrolled rest), as a spreadsheet's frozen
|
|
40
|
+
* panes are.
|
|
41
|
+
*/
|
|
42
|
+
export declare function viewPanes(view: RasterView, pins: RasterPins, width: number, height: number): RasterPane[];
|
|
43
|
+
/** An image area in image pixels. */
|
|
44
|
+
export type RasterRect = {
|
|
45
|
+
x0: number;
|
|
46
|
+
y0: number;
|
|
47
|
+
x1: number;
|
|
48
|
+
y1: number;
|
|
49
|
+
};
|
|
50
|
+
export type RasterViewportStats = {
|
|
51
|
+
renderMs: number;
|
|
52
|
+
frameWidth: number;
|
|
53
|
+
frameHeight: number;
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* Paints a kit document into a `<canvas>`. The engine renders the visible part of the image, and
|
|
57
|
+
* a margin around it, at the current zoom into a cached frame; panning and zooming redraw that
|
|
58
|
+
* frame at once, and a fresh render follows the next animation frame (one at a time, the last view
|
|
59
|
+
* again after it), so a view that keeps moving keeps being painted.
|
|
60
|
+
*/
|
|
61
|
+
/** Draws on top of the document in canvas CSS pixels; `toScreen` maps document points there. */
|
|
62
|
+
export type RasterDecoration = (context: CanvasRenderingContext2D, toScreen: (x: number, y: number) => {
|
|
63
|
+
x: number;
|
|
64
|
+
y: number;
|
|
65
|
+
}, view: RasterView) => void;
|
|
66
|
+
export declare class RasterViewport {
|
|
67
|
+
private readonly canvas;
|
|
68
|
+
private readonly doc;
|
|
69
|
+
private backdrop;
|
|
70
|
+
private readonly onChange;
|
|
71
|
+
/** A page shadow and transparency checks under the document; off for engines that paint their own canvas. */
|
|
72
|
+
private readonly framed;
|
|
73
|
+
/** A current render failed, or null after its pixels were replaced successfully. */
|
|
74
|
+
private readonly onRender;
|
|
75
|
+
view: RasterView;
|
|
76
|
+
/** Drawn after the document on every frame, for example marching ants. */
|
|
77
|
+
decorate: RasterDecoration | null;
|
|
78
|
+
private frames;
|
|
79
|
+
/**
|
|
80
|
+
* The view still on screen while a scroll waits for its render: a pan past the painted frame
|
|
81
|
+
* keeps showing the frame where it was, never blank canvas, until the new view is painted.
|
|
82
|
+
*/
|
|
83
|
+
private held;
|
|
84
|
+
private pattern;
|
|
85
|
+
/** The render asked for the next animation frame, and how to call it off. */
|
|
86
|
+
private settle;
|
|
87
|
+
/** Moves with every view change: a failure of a render for an older view is not reported. */
|
|
88
|
+
private moves;
|
|
89
|
+
private rendering;
|
|
90
|
+
private renderAgain;
|
|
91
|
+
/** Areas edits changed while a render was in flight, patched once it lands. */
|
|
92
|
+
private pendingDamage;
|
|
93
|
+
private disposed;
|
|
94
|
+
private generation;
|
|
95
|
+
private failed;
|
|
96
|
+
/** The area the view was last fitted to; cleared when the view moves otherwise. */
|
|
97
|
+
private fitted;
|
|
98
|
+
/** The canvas size the view was laid out for. */
|
|
99
|
+
private laidOut;
|
|
100
|
+
private panBounds;
|
|
101
|
+
constructor(canvas: HTMLCanvasElement, doc: RasterSource, backdrop: string, onChange: (view: RasterView, stats: RasterViewportStats | null) => void,
|
|
102
|
+
/** A page shadow and transparency checks under the document; off for engines that paint their own canvas. */
|
|
103
|
+
framed?: boolean,
|
|
104
|
+
/** A current render failed, or null after its pixels were replaced successfully. */
|
|
105
|
+
onRender?: (error: unknown | null) => void);
|
|
106
|
+
/**
|
|
107
|
+
* In-flight pixels and failures from before an edit must not replace the new state. A render
|
|
108
|
+
* in flight is dropped, so it runs again once it ends: the edit's own repaint may be a patch,
|
|
109
|
+
* or none at all (a settled click that changed nothing more), which would leave the dropped
|
|
110
|
+
* frame's older pixels on screen.
|
|
111
|
+
*/
|
|
112
|
+
invalidate(): void;
|
|
113
|
+
/** Drops what is in flight (the view moved: its own settled render follows). */
|
|
114
|
+
private drop;
|
|
115
|
+
dispose(): void;
|
|
116
|
+
private get size();
|
|
117
|
+
private get pins();
|
|
118
|
+
/** Canvas CSS pixel position of a document point. */
|
|
119
|
+
toScreen(x: number, y: number): {
|
|
120
|
+
x: number;
|
|
121
|
+
y: number;
|
|
122
|
+
};
|
|
123
|
+
/** Image coordinates of a point in the canvas's CSS pixels. */
|
|
124
|
+
toImage(clientX: number, clientY: number): {
|
|
125
|
+
x: number;
|
|
126
|
+
y: number;
|
|
127
|
+
};
|
|
128
|
+
fit(): void;
|
|
129
|
+
/** Fits `area` (document pixels) in the canvas, centred: a page or spread brought into view. */
|
|
130
|
+
fitArea(area: RasterRect): void;
|
|
131
|
+
/**
|
|
132
|
+
* Lays the view out again after the canvas changed size (a window maximized, a panel closed):
|
|
133
|
+
* a fitted view fits its area again; otherwise the document point at the centre stays there, or,
|
|
134
|
+
* with pinned bands, the top-left stays put as a spreadsheet's does.
|
|
135
|
+
*/
|
|
136
|
+
resized(): void;
|
|
137
|
+
/** Zooms to `zoom`, keeping the image point under (`clientX`, `clientY`) still; the centre by default. */
|
|
138
|
+
zoomTo(zoom: number, clientX?: number, clientY?: number): void;
|
|
139
|
+
/** Puts document point (`x`, `y`) at the view's top-left, keeping the zoom. */
|
|
140
|
+
panTo(x: number, y: number): void;
|
|
141
|
+
panBy(dx: number, dy: number): void;
|
|
142
|
+
/** Limits panning to a document's pages; a smaller document stays centred in the canvas. */
|
|
143
|
+
setPanBounds(bounds: RasterRect | null): void;
|
|
144
|
+
private setView;
|
|
145
|
+
/** The view on screen: the held one while a scroll waits for its render (see `held`). */
|
|
146
|
+
get shown(): RasterView;
|
|
147
|
+
/** Shows the view asked for, painted or not (a render that ended without pixels for it). */
|
|
148
|
+
private release;
|
|
149
|
+
/** Whether the frames hold every document pixel `view` shows. */
|
|
150
|
+
private covers;
|
|
151
|
+
/** Renders the view the next animation frame (a render in flight renders again after it). */
|
|
152
|
+
private schedule;
|
|
153
|
+
/**
|
|
154
|
+
* Renders the visible part of the image in the engine, then shows it; call after the
|
|
155
|
+
* document changes. One render runs at a time; a request meanwhile renders again after it.
|
|
156
|
+
*/
|
|
157
|
+
render(): Promise<boolean>;
|
|
158
|
+
/**
|
|
159
|
+
* Repaints `area` after an edit that changed only it (a caret moved): now, or once the render
|
|
160
|
+
* in flight lands. That render is kept, since everything outside `area` in it is still right;
|
|
161
|
+
* dropping it, as `invalidate` does, would render the whole view again for every caret move.
|
|
162
|
+
*/
|
|
163
|
+
patch(area: RasterRect): Promise<boolean>;
|
|
164
|
+
private renderNow;
|
|
165
|
+
/** Renders the document area a pane shows, at the zoom; null when it shows none of it. */
|
|
166
|
+
private renderPane;
|
|
167
|
+
/**
|
|
168
|
+
* Re-renders only `area` (what a stroke or a caret touched) into the cached frames, each pane's
|
|
169
|
+
* at its own scale, then redraws. When the frames changed meanwhile, renders them all again.
|
|
170
|
+
*/
|
|
171
|
+
renderArea(area: RasterRect): Promise<boolean>;
|
|
172
|
+
/** Paints `color` behind the document from now on (the theme changed), redrawing at once. */
|
|
173
|
+
setBackdrop(color: string): void;
|
|
174
|
+
/** Redraws the cached frame at the current view. */
|
|
175
|
+
draw(): void;
|
|
176
|
+
/** The colour of the image pixel under a canvas point, from the cached frame. */
|
|
177
|
+
sample(clientX: number, clientY: number): [number, number, number] | null;
|
|
178
|
+
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/** The reason code a refused call answers with (`error.data.reason` over the protocol). */
|
|
2
|
+
export declare const READ_ONLY_REASON = "read-only";
|
|
3
|
+
export declare const READ_ONLY_RULES: Readonly<{
|
|
4
|
+
/**
|
|
5
|
+
* Families whose commands only change what the person sees (zoom, selection, the playhead,
|
|
6
|
+
* playback): they run even when their kit flags them `mutates`.
|
|
7
|
+
*/
|
|
8
|
+
viewingGroups: readonly string[];
|
|
9
|
+
/** Single viewing commands in families that otherwise edit (Film's monitors and markers). */
|
|
10
|
+
viewingCommands: readonly string[];
|
|
11
|
+
/** Commands refused whatever their flag: the history, which some kits report as not editing. */
|
|
12
|
+
editingCommands: readonly string[];
|
|
13
|
+
/**
|
|
14
|
+
* Commands in viewing families that change the document all the same, so the editor shows them
|
|
15
|
+
* disabled rather than letting the backstop refuse them: settings a file keeps (a sheet's frozen
|
|
16
|
+
* panes, gridlines, and headings; guides and slices; saved selections and views; a 3D camera).
|
|
17
|
+
* Their kits flag them `mutates`; the viewing families cannot simply follow the flag while a kit
|
|
18
|
+
* (Film) still flags viewing commands as edits.
|
|
19
|
+
*/
|
|
20
|
+
documentSettings: readonly string[];
|
|
21
|
+
/** Families refused whatever their commands' flags, except `fileOutputs`. */
|
|
22
|
+
editingGroups: readonly string[];
|
|
23
|
+
/** `file` commands that only produce bytes (an export, a copy, a print): they run. */
|
|
24
|
+
fileOutputs: RegExp;
|
|
25
|
+
/** Engine tool calls that edit (U8a gestures, keys, typed text); `tools`, `toolState`, `selectTool`, `tool` run. */
|
|
26
|
+
refusedTools: readonly string[];
|
|
27
|
+
/** Document methods `invoke` refuses: they edit around the contract's checks. */
|
|
28
|
+
refusedMethods: readonly string[];
|
|
29
|
+
}>;
|
|
30
|
+
/** Whether running `command` is an edit a read-only document refuses (before the backstop). */
|
|
31
|
+
export declare function editsDocument(command: {
|
|
32
|
+
id: string;
|
|
33
|
+
mutates?: boolean | null;
|
|
34
|
+
}): boolean;
|
|
35
|
+
/**
|
|
36
|
+
* The comment commands a commenter's read-only session runs (the Kit UI protocol's
|
|
37
|
+
* `document.comments.canComment`, KitModel rule M23): the kit's `kit.json`
|
|
38
|
+
* `collaboration.comments.commands`, which its editor passes on as `KitModuleManifest.commentCommands`.
|
|
39
|
+
* Never the history or a `file` command, whatever the kit lists: a `file` command stays refused,
|
|
40
|
+
* and Undo and Redo reach only the commenter's own comments (`commenterHistory`). Empty when the
|
|
41
|
+
* person may not comment.
|
|
42
|
+
*/
|
|
43
|
+
export declare function commentCommands(listed: readonly string[] | null | undefined, canComment: boolean): ReadonlySet<string>;
|
|
44
|
+
/**
|
|
45
|
+
* Whether `id` is Undo or Redo of a commenter's session (`comments` not empty), which takes back
|
|
46
|
+
* or brings back the commenter's own comment changes (KitModel rule M23): the engine
|
|
47
|
+
* worker runs it only while the session has such a step to take, under the comment backstop.
|
|
48
|
+
* `null` for any other command, and for every command of a viewer's session.
|
|
49
|
+
*/
|
|
50
|
+
export declare function commenterHistory(id: string, comments: ReadonlySet<string>): 'undo' | 'redo' | null;
|
|
51
|
+
/**
|
|
52
|
+
* Whether a read-only document refuses `command` (before the backstop): an edit that is not one
|
|
53
|
+
* of the session's `comments` (`commentCommands`) or a commenter's Undo and Redo
|
|
54
|
+
* (`commenterHistory`). A comment command runs under the comment backstop instead: what it
|
|
55
|
+
* changes besides `CommentThread` and `Comment` objects is undone and the command refused.
|
|
56
|
+
*/
|
|
57
|
+
export declare function refusedReadOnly(command: {
|
|
58
|
+
id: string;
|
|
59
|
+
mutates?: boolean | null;
|
|
60
|
+
}, comments: ReadonlySet<string>): boolean;
|
|
61
|
+
/**
|
|
62
|
+
* Whether a commenter's editor hides `command` (Kit UI protocol `document.comments`): every
|
|
63
|
+
* command the read-only rules refuse them. A commenter sees what they can run (viewing, comment
|
|
64
|
+
* commands, and the history of their comments) instead of a document of disabled edits; a
|
|
65
|
+
* viewer's editor (`comments` empty) still shows the edits, disabled.
|
|
66
|
+
*/
|
|
67
|
+
export declare function hiddenForCommenter(command: {
|
|
68
|
+
id: string;
|
|
69
|
+
mutates?: boolean | null;
|
|
70
|
+
}, comments: ReadonlySet<string>): boolean;
|
|
71
|
+
/** A refusal because the document is read-only; `reason` is `read-only`. */
|
|
72
|
+
export declare class ReadOnlyError extends Error {
|
|
73
|
+
readonly reason = "read-only";
|
|
74
|
+
/** `what` is refused (as `\`slide.new\``); `message`, when given, is the whole message (one passed on from the worker). */
|
|
75
|
+
constructor(what: string, message?: string);
|
|
76
|
+
}
|
|
77
|
+
/** Whether `error` is a read-only refusal (from the worker, or made on the page). */
|
|
78
|
+
export declare function isReadOnlyError(error: unknown): error is ReadOnlyError;
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/** One parameter a call got wrong: a JSON Pointer into the params, what is wrong, and what the command takes there. */
|
|
2
|
+
export type KitParamError = {
|
|
3
|
+
path: string;
|
|
4
|
+
message: string;
|
|
5
|
+
expected?: string;
|
|
6
|
+
};
|
|
7
|
+
/** Separates a refusal's text from its errors (`kition_kit::schema::REFUSAL_SEPARATOR`). */
|
|
8
|
+
export declare const REFUSAL_SEPARATOR = "\u001E";
|
|
9
|
+
/** The reason of a host's change refused because the engine cannot keep it out of the undo history. */
|
|
10
|
+
export declare const UNSUPPORTED_REASON = "unsupported";
|
|
11
|
+
/** An engine refused a call's parameters; `message` is its text, `errors` each wrong parameter. */
|
|
12
|
+
export declare class KitParamsError extends Error {
|
|
13
|
+
readonly errors: KitParamError[];
|
|
14
|
+
readonly reason = "invalid-params";
|
|
15
|
+
constructor(message: string, errors: KitParamError[]);
|
|
16
|
+
}
|
|
17
|
+
/** The worker refused a call it cannot run as asked (`reason`). */
|
|
18
|
+
export declare class KitEngineRefusal extends Error {
|
|
19
|
+
readonly reason: typeof UNSUPPORTED_REASON;
|
|
20
|
+
constructor(reason: typeof UNSUPPORTED_REASON, message: string);
|
|
21
|
+
}
|
|
22
|
+
/** An engine's error as a `KitParamsError` when it is a refusal of the parameters; `null` for any other. */
|
|
23
|
+
export declare function paramsRefusal(error: unknown): KitParamsError | null;
|
|
24
|
+
/** Separates a command failure's text from its reason (`kition_kit::failure::FAILURE_SEPARATOR`). */
|
|
25
|
+
export declare const FAILURE_SEPARATOR = "\u001F";
|
|
26
|
+
/** The reasons a kit gives for a command that did not run (`kition_kit::failure::CommandFailure`). */
|
|
27
|
+
export declare const COMMAND_FAILURES: readonly ["command_not_found", "command_disabled", "invalid_params"];
|
|
28
|
+
export type CommandFailureReason = (typeof COMMAND_FAILURES)[number];
|
|
29
|
+
/** A command did not run for the `reason` its kit gave; `message` is the text a person reads. */
|
|
30
|
+
export declare class KitCommandFailure extends Error {
|
|
31
|
+
readonly reason: CommandFailureReason;
|
|
32
|
+
constructor(reason: CommandFailureReason, message: string);
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* An engine's error as a `KitCommandFailure` when the kit gave its reason (`kition_kit::failure`:
|
|
36
|
+
* its text, U+001F, the reason); `null` for any other, which is read by its wording where a code
|
|
37
|
+
* is needed.
|
|
38
|
+
*/
|
|
39
|
+
export declare function commandFailure(error: unknown): KitCommandFailure | null;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A document's KDM replica kept by the host next to its file (the Kit UI protocol's `replica`
|
|
3
|
+
* capability), for files that cannot hold a replica themselves, such as PSD. The file stays the
|
|
4
|
+
* document: a replica only counts while the file is the one it was saved with, so every failure
|
|
5
|
+
* here degrades to opening the file plainly, never to losing or blocking it.
|
|
6
|
+
*/
|
|
7
|
+
import type { KitHost } from './kitHost.js';
|
|
8
|
+
import type { KitModuleReplica } from './kitModule.js';
|
|
9
|
+
/**
|
|
10
|
+
* The stored replica to open `path` with: the host's, when it was saved with the file as it is
|
|
11
|
+
* now (`stamp`, the stamp of the bytes being opened; the host's current stamp when that is
|
|
12
|
+
* unknown). Otherwise (nothing stored, the file changed elsewhere since, the host failed) none:
|
|
13
|
+
* the file opens plainly, its replica is made anew on the first edit, and the next save replaces
|
|
14
|
+
* the stored one. `mergesFile` is for an engine that merges what the file holds into an older
|
|
15
|
+
* replica when it opens: the stored replica opens whatever the file's stamp.
|
|
16
|
+
*/
|
|
17
|
+
export declare function replicaToOpen(host: KitHost, path: string, stamp: string | null, mergesFile?: boolean): Promise<KitModuleReplica | null>;
|
|
18
|
+
/**
|
|
19
|
+
* Writes the file, then `replica` (taken with the file's bytes) under the stamp the write answered,
|
|
20
|
+
* or the file's stamp after it. A replica the host cannot store is left out: the file is saved,
|
|
21
|
+
* and it opens plainly next time. Answers the file's new stamp.
|
|
22
|
+
*/
|
|
23
|
+
export declare function writeWithReplica(host: KitHost, path: string, bytes: Uint8Array, replica: KitModuleReplica | null, expected?: string | null): Promise<string | null>;
|