@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.
Files changed (66) hide show
  1. package/README.md +103 -2
  2. package/dist/LICENSE +177 -0
  3. package/dist/assets/kitEngine.worker-9PIHJagj.js +13020 -0
  4. package/dist/chunks/workspaceTree-CpJ2i9hy.js +23 -0
  5. package/dist/index.js +6434 -0
  6. package/dist/styles.css +807 -0
  7. package/dist/types/src/CommandDialog.d.ts +22 -0
  8. package/dist/types/src/CommentsPanel.d.ts +45 -0
  9. package/dist/types/src/CustomizeDialog.d.ts +32 -0
  10. package/dist/types/src/HostButtons.d.ts +11 -0
  11. package/dist/types/src/RenderFailure.d.ts +7 -0
  12. package/dist/types/src/TextSink.d.ts +6 -0
  13. package/dist/types/src/brand.d.ts +2 -0
  14. package/dist/types/src/catalogMenus.d.ts +27 -0
  15. package/dist/types/src/chart.d.ts +138 -0
  16. package/dist/types/src/conflicts.d.ts +12 -0
  17. package/dist/types/src/drawing.d.ts +83 -0
  18. package/dist/types/src/editor.d.ts +544 -0
  19. package/dist/types/src/engine/KitCanvas.d.ts +70 -0
  20. package/dist/types/src/engine/createKitFile.d.ts +12 -0
  21. package/dist/types/src/engine/decorations.d.ts +14 -0
  22. package/dist/types/src/engine/engineOverlays.d.ts +197 -0
  23. package/dist/types/src/engine/engineTools.d.ts +116 -0
  24. package/dist/types/src/engine/kitDraft.d.ts +70 -0
  25. package/dist/types/src/engine/kitEngine.d.ts +370 -0
  26. package/dist/types/src/engine/kitEngine.worker.d.ts +30 -0
  27. package/dist/types/src/engine/kitHost.d.ts +41 -0
  28. package/dist/types/src/engine/kitModel.d.ts +32 -0
  29. package/dist/types/src/engine/kitModelRunner.d.ts +93 -0
  30. package/dist/types/src/engine/kitModule.d.ts +173 -0
  31. package/dist/types/src/engine/kitShortcuts.d.ts +32 -0
  32. package/dist/types/src/engine/kitTools.d.ts +79 -0
  33. package/dist/types/src/engine/lentFiles.d.ts +29 -0
  34. package/dist/types/src/engine/rasterViewport.d.ts +178 -0
  35. package/dist/types/src/engine/readOnly.d.ts +78 -0
  36. package/dist/types/src/engine/refusal.d.ts +39 -0
  37. package/dist/types/src/engine/replica.d.ts +23 -0
  38. package/dist/types/src/engine/useKitDocument.d.ts +154 -0
  39. package/dist/types/src/engine/workerRelay.d.ts +62 -0
  40. package/dist/types/src/files.d.ts +74 -0
  41. package/dist/types/src/frame/EditorFrame.d.ts +74 -0
  42. package/dist/types/src/frame/FocusBar.d.ts +10 -0
  43. package/dist/types/src/frame/MenuNodes.d.ts +20 -0
  44. package/dist/types/src/frame/MenuRibbon.d.ts +8 -0
  45. package/dist/types/src/frame/ModeButton.d.ts +7 -0
  46. package/dist/types/src/frame/menus.d.ts +64 -0
  47. package/dist/types/src/frame/modes.d.ts +51 -0
  48. package/dist/types/src/frame/useFrameLayout.d.ts +34 -0
  49. package/dist/types/src/host.d.ts +127 -0
  50. package/dist/types/src/index.d.ts +84 -0
  51. package/dist/types/src/ink.d.ts +26 -0
  52. package/dist/types/src/lease.d.ts +53 -0
  53. package/dist/types/src/oneInFlight.d.ts +7 -0
  54. package/dist/types/src/phrases.d.ts +25 -0
  55. package/dist/types/src/presence.d.ts +79 -0
  56. package/dist/types/src/strings.d.ts +6 -0
  57. package/dist/types/src/toolIcons.d.ts +32 -0
  58. package/dist/types/src/uiCatalog.d.ts +59 -0
  59. package/dist/types/src/uiConfig.d.ts +53 -0
  60. package/dist/types/src/uiContext.d.ts +65 -0
  61. package/dist/types/src/uiStore.d.ts +20 -0
  62. package/dist/types/src/useCommentAnchors.d.ts +29 -0
  63. package/dist/types/src/useKitSession.d.ts +115 -0
  64. package/dist/types/src/workspaceTree.d.ts +5 -0
  65. package/dist/workspaceTree.js +1 -0
  66. 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>;