@kitionstage/sdk 0.0.0-stage → 0.5.2-stage.2
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 +73 -2
- package/dist/LICENSE +177 -0
- package/dist/THIRD_PARTY_NOTICES +28 -0
- package/dist/lib/assets/kitEngine.worker-3iMvwtlI.js +12732 -0
- package/dist/lib/assets/loro_wasm_bg-Gulzks_0.wasm +0 -0
- package/dist/lib/chunks/batch-BWpAyHvP.js +789 -0
- package/dist/lib/chunks/canonical-BIWfVCL-.js +87 -0
- package/dist/lib/chunks/envelope-D6MGY-ZN.js +61 -0
- package/dist/lib/chunks/replica-D8w3I4sn.js +2472 -0
- package/dist/lib/chunks/runtime-BVJHE1Pg.js +997 -0
- package/dist/lib/chunks/session-BqXC9a1-.js +281 -0
- package/dist/lib/chunks/toolIds-BCeSGHpV.js +821 -0
- package/dist/lib/chunks/workspaceTree-Destqupf.js +23 -0
- package/dist/lib/convergence/index.js +1035 -0
- package/dist/lib/convergence/node.js +8 -0
- package/dist/lib/embed-server/callbacks.js +37 -0
- package/dist/lib/embed-server/cli.js +19 -0
- package/dist/lib/embed-server/index.js +272 -0
- package/dist/lib/extensions/index.js +439 -0
- package/dist/lib/extensions/panel.html +208 -0
- package/dist/lib/extensions/runtime.js +198 -0
- package/dist/lib/extensions/sandbox.html +35 -0
- package/dist/lib/kdm/index.js +437 -0
- package/dist/lib/kit-dev-host/checkUiIds.mjs +44 -0
- package/dist/lib/kit-dev-host/index.js +308 -0
- package/dist/lib/kit-dev-host/lineRow.mjs +47 -0
- package/dist/lib/kit-dev-host/modeSmoke.mjs +178 -0
- package/dist/lib/kit-editor/index.js +6481 -0
- package/dist/lib/kit-editor/styles.css +807 -0
- package/dist/lib/kit-editor/workspaceTree.js +1 -0
- package/dist/lib/kit-engine/index.js +7 -0
- package/dist/lib/kit-host/index.js +530 -0
- package/dist/lib/kit-ui-protocol/index.js +336 -0
- package/dist/lib/node-only/embed-server-callbacks.js +2 -0
- package/dist/lib/node-only/embed-server.js +2 -0
- package/dist/lib/sync/index.js +1008 -0
- package/dist/lib/sync/openToken.js +201 -0
- package/dist/lib/sync/replicaVersions.js +51 -0
- package/dist/standalone/chunks/batch-CAGYk6m4.js +789 -0
- package/dist/standalone/chunks/client-B9xkOcvf.js +772 -0
- package/dist/standalone/chunks/collab-CTQZ9h7J.js +1022 -0
- package/dist/standalone/chunks/comment-Ds9t8xSE.js +94 -0
- package/dist/standalone/chunks/comments-uVDS8Wxp.js +41 -0
- package/dist/standalone/chunks/document-B5MMuYyN.js +324 -0
- package/dist/standalone/chunks/envelope-GX4Cynkx.js +7612 -0
- package/dist/standalone/chunks/index-BEgEEnhU.js +287 -0
- package/dist/standalone/chunks/index-EEl8hGbP.js +1967 -0
- package/dist/standalone/chunks/kits-Cp51mDlw.js +9 -0
- package/dist/standalone/chunks/replica-Di2iCPiD.js +3281 -0
- package/dist/standalone/chunks/replicaVersions-C3rJxnk9.js +50 -0
- package/dist/standalone/chunks/touched-T9jKJjxn.js +78 -0
- package/dist/standalone/index.js +12 -0
- package/dist/standalone/script/index.js +339 -0
- package/dist/standalone/script/kits/board.js +5 -0
- package/dist/standalone/script/kits/cad.js +5 -0
- package/dist/standalone/script/kits/design.js +5 -0
- package/dist/standalone/script/kits/doc.js +5 -0
- package/dist/standalone/script/kits/film.js +5 -0
- package/dist/standalone/script/kits/html.js +5 -0
- package/dist/standalone/script/kits/index.js +38 -0
- package/dist/standalone/script/kits/layout.js +5 -0
- package/dist/standalone/script/kits/motion.js +5 -0
- package/dist/standalone/script/kits/note.js +5 -0
- package/dist/standalone/script/kits/pdf.js +5 -0
- package/dist/standalone/script/kits/photo.js +5 -0
- package/dist/standalone/script/kits/scene.js +5 -0
- package/dist/standalone/script/kits/sheet.js +5 -0
- package/dist/standalone/script/kits/slide.js +5 -0
- package/dist/standalone/script/kits/table.js +5 -0
- package/dist/standalone/script/kits/vector.js +5 -0
- package/dist/standalone/script/node.js +401 -0
- package/dist/standalone/script/proxy.js +254 -0
- package/dist/types/convergence/src/adapter.d.ts +131 -0
- package/dist/types/convergence/src/engine.d.ts +66 -0
- package/dist/types/convergence/src/index.d.ts +21 -0
- package/dist/types/convergence/src/net.d.ts +52 -0
- package/dist/types/convergence/src/node.d.ts +6 -0
- package/dist/types/convergence/src/report.d.ts +56 -0
- package/dist/types/convergence/src/rng.d.ts +12 -0
- package/dist/types/convergence/src/scenarios.d.ts +15 -0
- package/dist/types/convergence/src/state.d.ts +67 -0
- package/dist/types/embed/src/agent.d.ts +88 -0
- package/dist/types/embed/src/blobs.d.ts +2 -0
- package/dist/types/embed/src/collab.d.ts +250 -0
- package/dist/types/embed/src/comments.d.ts +30 -0
- package/dist/types/embed/src/errors.d.ts +24 -0
- package/dist/types/embed/src/handlers.d.ts +92 -0
- package/dist/types/embed/src/index.d.ts +20 -0
- package/dist/types/embed/src/mount.d.ts +39 -0
- package/dist/types/embed/src/replicaStore.d.ts +3 -0
- package/dist/types/embed/src/rooms.d.ts +40 -0
- package/dist/types/embed/src/schemas.d.ts +7 -0
- package/dist/types/embed/src/syncClients.d.ts +28 -0
- package/dist/types/embed/src/theme.d.ts +7 -0
- package/dist/types/embed/src/types.d.ts +596 -0
- package/dist/types/embed/src/ui.d.ts +33 -0
- package/dist/types/embed/src/version.d.ts +2 -0
- package/dist/types/embed-server/src/callbacks.d.ts +30 -0
- package/dist/types/embed-server/src/cli.d.ts +1 -0
- package/dist/types/embed-server/src/index.d.ts +19 -0
- package/dist/types/embed-server/src/page.d.ts +15 -0
- package/dist/types/embed-server/src/server.d.ts +39 -0
- package/dist/types/embed-server/src/session.d.ts +22 -0
- package/dist/types/extensions/src/gate.d.ts +17 -0
- package/dist/types/extensions/src/generated/runtime.d.ts +8 -0
- package/dist/types/extensions/src/host.d.ts +135 -0
- package/dist/types/extensions/src/index.d.ts +13 -0
- package/dist/types/extensions/src/manifest.d.ts +82 -0
- package/dist/types/extensions/src/protocol.d.ts +159 -0
- package/dist/types/extensions/src/rpc.d.ts +52 -0
- package/dist/types/extensions/src/runtime/document.d.ts +40 -0
- package/dist/types/extensions/src/runtime/index.d.ts +10 -0
- package/dist/types/extensions/src/runtime/panel.d.ts +19 -0
- package/dist/types/extensions/src/runtime/runtime.d.ts +54 -0
- package/dist/types/extensions/src/runtime/worker.d.ts +1 -0
- package/dist/types/extensions/src/sandbox.d.ts +41 -0
- package/dist/types/kdm/src/args.d.ts +12 -0
- package/dist/types/kdm/src/batch.d.ts +118 -0
- package/dist/types/kdm/src/canonical.d.ts +25 -0
- package/dist/types/kdm/src/comment.d.ts +114 -0
- package/dist/types/kdm/src/diff.d.ts +125 -0
- package/dist/types/kdm/src/envelope.d.ts +27 -0
- package/dist/types/kdm/src/errors.d.ts +28 -0
- package/dist/types/kdm/src/footprint.d.ts +21 -0
- package/dist/types/kdm/src/ids.d.ts +57 -0
- package/dist/types/kdm/src/index.d.ts +18 -0
- package/dist/types/kdm/src/marks.d.ts +32 -0
- package/dist/types/kdm/src/op.d.ts +124 -0
- package/dist/types/kdm/src/origin.d.ts +41 -0
- package/dist/types/kdm/src/overlay.d.ts +92 -0
- package/dist/types/kdm/src/projection.d.ts +29 -0
- package/dist/types/kdm/src/read.d.ts +90 -0
- package/dist/types/kdm/src/replica.d.ts +403 -0
- package/dist/types/kdm/src/schema.d.ts +185 -0
- package/dist/types/kdm/src/testing.d.ts +28 -0
- package/dist/types/kdm/src/toolIds.d.ts +61 -0
- package/dist/types/kdm/src/touched.d.ts +24 -0
- package/dist/types/kdm/src/tx.d.ts +215 -0
- package/dist/types/kdm/src/value.d.ts +23 -0
- package/dist/types/kit-dev-host/src/checkNoPaths.d.ts +19 -0
- package/dist/types/kit-dev-host/src/checkUiIds.d.mts +2 -0
- package/dist/types/kit-dev-host/src/index.d.ts +179 -0
- package/dist/types/kit-dev-host/src/lineRow.d.mts +14 -0
- package/dist/types/kit-dev-host/src/memoryFiles.d.ts +15 -0
- package/dist/types/kit-dev-host/src/modeSmoke.d.mts +8 -0
- package/dist/types/kit-editor/src/CommandDialog.d.ts +22 -0
- package/dist/types/kit-editor/src/CommentsPanel.d.ts +45 -0
- package/dist/types/kit-editor/src/CustomizeDialog.d.ts +32 -0
- package/dist/types/kit-editor/src/HostButtons.d.ts +11 -0
- package/dist/types/kit-editor/src/RenderFailure.d.ts +7 -0
- package/dist/types/kit-editor/src/TextSink.d.ts +6 -0
- package/dist/types/kit-editor/src/brand.d.ts +2 -0
- package/dist/types/kit-editor/src/catalogMenus.d.ts +27 -0
- package/dist/types/kit-editor/src/chart.d.ts +138 -0
- package/dist/types/kit-editor/src/conflicts.d.ts +12 -0
- package/dist/types/kit-editor/src/drawing.d.ts +83 -0
- package/dist/types/kit-editor/src/editor.d.ts +544 -0
- package/dist/types/kit-editor/src/engine/KitCanvas.d.ts +70 -0
- package/dist/types/kit-editor/src/engine/backdrop.d.ts +32 -0
- package/dist/types/kit-editor/src/engine/createKitFile.d.ts +12 -0
- package/dist/types/kit-editor/src/engine/decorations.d.ts +14 -0
- package/dist/types/kit-editor/src/engine/engineOverlays.d.ts +197 -0
- package/dist/types/kit-editor/src/engine/engineTools.d.ts +116 -0
- package/dist/types/kit-editor/src/engine/kitDraft.d.ts +70 -0
- package/dist/types/kit-editor/src/engine/kitEngine.d.ts +390 -0
- package/dist/types/kit-editor/src/engine/kitEngine.worker.d.ts +30 -0
- package/dist/types/kit-editor/src/engine/kitHost.d.ts +41 -0
- package/dist/types/kit-editor/src/engine/kitModel.d.ts +32 -0
- package/dist/types/kit-editor/src/engine/kitModelRunner.d.ts +99 -0
- package/dist/types/kit-editor/src/engine/kitModule.d.ts +185 -0
- package/dist/types/kit-editor/src/engine/kitShortcuts.d.ts +32 -0
- package/dist/types/kit-editor/src/engine/kitTools.d.ts +79 -0
- package/dist/types/kit-editor/src/engine/lazyFonts.d.ts +34 -0
- package/dist/types/kit-editor/src/engine/lentFiles.d.ts +29 -0
- package/dist/types/kit-editor/src/engine/rasterViewport.d.ts +178 -0
- package/dist/types/kit-editor/src/engine/readOnly.d.ts +78 -0
- package/dist/types/kit-editor/src/engine/refusal.d.ts +39 -0
- package/dist/types/kit-editor/src/engine/replica.d.ts +23 -0
- package/dist/types/kit-editor/src/engine/useKitDocument.d.ts +154 -0
- package/dist/types/kit-editor/src/engine/workerRelay.d.ts +62 -0
- package/dist/types/kit-editor/src/files.d.ts +74 -0
- package/dist/types/kit-editor/src/frame/EditorFrame.d.ts +74 -0
- package/dist/types/kit-editor/src/frame/FocusBar.d.ts +10 -0
- package/dist/types/kit-editor/src/frame/MenuNodes.d.ts +20 -0
- package/dist/types/kit-editor/src/frame/MenuRibbon.d.ts +8 -0
- package/dist/types/kit-editor/src/frame/ModeButton.d.ts +7 -0
- package/dist/types/kit-editor/src/frame/menus.d.ts +64 -0
- package/dist/types/kit-editor/src/frame/modes.d.ts +51 -0
- package/dist/types/kit-editor/src/frame/useFrameLayout.d.ts +34 -0
- package/dist/types/kit-editor/src/host.d.ts +127 -0
- package/dist/types/kit-editor/src/index.d.ts +85 -0
- package/dist/types/kit-editor/src/ink.d.ts +26 -0
- package/dist/types/kit-editor/src/lease.d.ts +53 -0
- package/dist/types/kit-editor/src/oneInFlight.d.ts +7 -0
- package/dist/types/kit-editor/src/phrases.d.ts +25 -0
- package/dist/types/kit-editor/src/presence.d.ts +79 -0
- package/dist/types/kit-editor/src/strings.d.ts +6 -0
- package/dist/types/kit-editor/src/toolIcons.d.ts +32 -0
- package/dist/types/kit-editor/src/uiCatalog.d.ts +59 -0
- package/dist/types/kit-editor/src/uiConfig.d.ts +53 -0
- package/dist/types/kit-editor/src/uiContext.d.ts +65 -0
- package/dist/types/kit-editor/src/uiStore.d.ts +20 -0
- package/dist/types/kit-editor/src/useCommentAnchors.d.ts +29 -0
- package/dist/types/kit-editor/src/useKitSession.d.ts +115 -0
- package/dist/types/kit-editor/src/workspaceTree.d.ts +5 -0
- package/dist/types/kit-engine/src/contract.d.ts +154 -0
- package/dist/types/kit-engine/src/index.d.ts +2 -0
- package/dist/types/kit-engine/src/session.d.ts +133 -0
- package/dist/types/kit-host/src/files.d.ts +163 -0
- package/dist/types/kit-host/src/index.d.ts +315 -0
- package/dist/types/kit-ui-protocol/src/index.d.ts +1145 -0
- package/dist/types/loro-crdt.d.ts +9 -0
- package/dist/types/script/kits/board.d.ts +534 -0
- package/dist/types/script/kits/cad.d.ts +2937 -0
- package/dist/types/script/kits/design.d.ts +3213 -0
- package/dist/types/script/kits/doc.d.ts +2575 -0
- package/dist/types/script/kits/film.d.ts +4067 -0
- package/dist/types/script/kits/html.d.ts +38 -0
- package/dist/types/script/kits/index.d.ts +20 -0
- package/dist/types/script/kits/layout.d.ts +3483 -0
- package/dist/types/script/kits/motion.d.ts +4826 -0
- package/dist/types/script/kits/note.d.ts +631 -0
- package/dist/types/script/kits/pdf.d.ts +829 -0
- package/dist/types/script/kits/photo.d.ts +7574 -0
- package/dist/types/script/kits/scene.d.ts +2962 -0
- package/dist/types/script/kits/sheet.d.ts +2419 -0
- package/dist/types/script/kits/slide.d.ts +1894 -0
- package/dist/types/script/kits/table.d.ts +654 -0
- package/dist/types/script/kits/vector.d.ts +5167 -0
- package/dist/types/script/src/agentRelay.d.ts +48 -0
- package/dist/types/script/src/capabilities.d.ts +21 -0
- package/dist/types/script/src/document.d.ts +87 -0
- package/dist/types/script/src/drafts.d.ts +141 -0
- package/dist/types/script/src/exchange.d.ts +30 -0
- package/dist/types/script/src/headless.d.ts +190 -0
- package/dist/types/script/src/index.d.ts +15 -0
- package/dist/types/script/src/kitModel.d.ts +17 -0
- package/dist/types/script/src/kits.d.ts +8 -0
- package/dist/types/script/src/node.d.ts +42 -0
- package/dist/types/script/src/port.d.ts +89 -0
- package/dist/types/script/src/proxy.d.ts +132 -0
- package/dist/types/script/src/room.d.ts +162 -0
- package/dist/types/script/src/sources.d.ts +73 -0
- package/dist/types/sync/src/backoff.d.ts +9 -0
- package/dist/types/sync/src/blobSection.d.ts +23 -0
- package/dist/types/sync/src/capabilities.d.ts +20 -0
- package/dist/types/sync/src/client.d.ts +253 -0
- package/dist/types/sync/src/framing.d.ts +35 -0
- package/dist/types/sync/src/hash.d.ts +2 -0
- package/dist/types/sync/src/index.d.ts +19 -0
- package/dist/types/sync/src/leases.d.ts +82 -0
- package/dist/types/sync/src/openToken.d.ts +104 -0
- package/dist/types/sync/src/protocol.d.ts +484 -0
- package/dist/types/sync/src/relay.d.ts +52 -0
- package/dist/types/sync/src/replicaVersions.d.ts +17 -0
- package/dist/types/sync/src/saveMachine.d.ts +83 -0
- package/dist/types/sync/src/saveRun.d.ts +52 -0
- package/dist/types/sync/src/transport.d.ts +19 -0
- package/package.json +229 -4
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The editor's live UI configuration (protocol section 9): the host's, replaced by `ui/configure`,
|
|
3
|
+
* and the person's hides, applied at once and kept by the host (`host/customize`).
|
|
4
|
+
*/
|
|
5
|
+
import type { KitNotifications } from '../../kit-ui-protocol/src/index.js';
|
|
6
|
+
import type { UiConfig } from './uiConfig.js';
|
|
7
|
+
export type UiStore = {
|
|
8
|
+
get: () => UiConfig;
|
|
9
|
+
/** For `useSyncExternalStore`. */
|
|
10
|
+
subscribe: (listener: () => void) => () => void;
|
|
11
|
+
/** Replaces the host's configuration. While a personal change is being kept, it stays over the host's. */
|
|
12
|
+
replace: (config: UiConfig) => void;
|
|
13
|
+
/** Whether the host keeps what the person hides (capability `customize`). */
|
|
14
|
+
customizable: boolean;
|
|
15
|
+
/** Sets the person's hides; rejects when the host could not keep them (they still apply). */
|
|
16
|
+
setPersonal: (hide: string[]) => Promise<void>;
|
|
17
|
+
/** A host button was pressed (`ui/action`). */
|
|
18
|
+
action: (params: KitNotifications['ui/action']) => void;
|
|
19
|
+
};
|
|
20
|
+
export declare function createUiStore(initial: UiConfig, customize: ((hide: string[]) => Promise<void>) | null, action: (params: KitNotifications['ui/action']) => void): UiStore;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { CommentAnchor, CommentThread } from '../../kdm/src/index.js';
|
|
2
|
+
export type CommentMarkerRect = {
|
|
3
|
+
x: number;
|
|
4
|
+
y: number;
|
|
5
|
+
width: number;
|
|
6
|
+
height: number;
|
|
7
|
+
};
|
|
8
|
+
export type CommentMarker = {
|
|
9
|
+
thread: string;
|
|
10
|
+
anchor: CommentAnchor;
|
|
11
|
+
rect: CommentMarkerRect;
|
|
12
|
+
resolved: boolean;
|
|
13
|
+
count: number;
|
|
14
|
+
active: boolean;
|
|
15
|
+
};
|
|
16
|
+
export type CommentAnchorsOptions = {
|
|
17
|
+
threads: CommentThread[];
|
|
18
|
+
/** Where `anchor` is now, in the kit's own coordinates; `null` when it is not shown. */
|
|
19
|
+
locate: (anchor: CommentAnchor) => CommentMarkerRect | null;
|
|
20
|
+
/** Markers for resolved threads too (default: only open ones). */
|
|
21
|
+
showResolved?: boolean;
|
|
22
|
+
activeThread?: string | null;
|
|
23
|
+
/** Changes whenever what `locate` answers may have changed (a document revision, the zoom). */
|
|
24
|
+
revision?: unknown;
|
|
25
|
+
};
|
|
26
|
+
/** The markers to draw, in the threads' order. */
|
|
27
|
+
export declare function commentMarkers({ threads, locate, showResolved, activeThread }: CommentAnchorsOptions): CommentMarker[];
|
|
28
|
+
/** `commentMarkers`, kept while its inputs (and `revision`) stay the same. */
|
|
29
|
+
export declare function useCommentAnchors(options: CommentAnchorsOptions): CommentMarker[];
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
import { KitRpcError, type DocumentChangeBy, type KitLease } from '../../kit-ui-protocol/src/index.js';
|
|
2
|
+
import type { Origin } from '../../kdm/src/index.js';
|
|
3
|
+
import type { HostConnection } from './host.js';
|
|
4
|
+
import type { KitEngine, KitEngineInfo } from './engine/kitEngine.js';
|
|
5
|
+
import type { KitCommand, KitModuleManifest } from './engine/kitModule.js';
|
|
6
|
+
import { type KitDocumentOptions, type KitRunOptions } from './engine/useKitDocument.js';
|
|
7
|
+
import type { RasterRect } from './engine/rasterViewport.js';
|
|
8
|
+
import type { DraftSummary } from '../../kit-ui-protocol/src/index.js';
|
|
9
|
+
import { type KitLeases } from './lease.js';
|
|
10
|
+
/** The error a command refused because the document is read-only answers with. `step` names the `ai/run` step. */
|
|
11
|
+
export declare function readOnlyRefusal(command: string, step?: number): KitRpcError;
|
|
12
|
+
/** Who made the document's last change, when it was not the person: the editor's status line says so. */
|
|
13
|
+
export type KitEditedBy = Exclude<DocumentChangeBy, {
|
|
14
|
+
by: 'person';
|
|
15
|
+
}>;
|
|
16
|
+
/**
|
|
17
|
+
* Opens the host's document in `manifest`'s engine. `describe` turns `inspect()` into what the
|
|
18
|
+
* editor shows. Answers the host's `ui/initialize` once open, and serves `ai/*`.
|
|
19
|
+
*/
|
|
20
|
+
/** A kit's own choices for its session. */
|
|
21
|
+
export type KitSessionOptions = {
|
|
22
|
+
/**
|
|
23
|
+
* An `ai/run` step that moves neither the engine's revision nor its `inspect()` (an agent
|
|
24
|
+
* selecting) refreshes the editor without repainting the canvas (`KitRunOptions.skipUnchangedPaint`).
|
|
25
|
+
* Off by default: a kit opts in when its engine paints nothing that neither of them shows.
|
|
26
|
+
*/
|
|
27
|
+
agentSkipsUnchangedPaint?: boolean;
|
|
28
|
+
/**
|
|
29
|
+
* The lease (Kit UI protocol section 7b) an `ai/run` step on the live document must hold, for a
|
|
30
|
+
* kit some of whose commands need one (a PDF's full rewrite takes the whole document, `*`):
|
|
31
|
+
* asked before each step with its command and params, answering the scope, or `null` or `''`
|
|
32
|
+
* for none (a kit with an engine extra such as `leaseScope` asks its engine). The session takes
|
|
33
|
+
* the lease through the host before the step and releases it when the step ends. A step whose
|
|
34
|
+
* lease another session holds is not run: `ai/run` fails at it with reason `held` and the
|
|
35
|
+
* person sees a notice; with a kit that asks, a step that edits without a lease of its own is
|
|
36
|
+
* refused the same way while another session holds the whole document (`*`). Not asked when
|
|
37
|
+
* the host serves no leases (nobody to coordinate with) or for the agent's draft, which is
|
|
38
|
+
* never shared until the person merges it. An error asking counts as no lease.
|
|
39
|
+
*/
|
|
40
|
+
agentLeaseScope?: (command: string, params: Record<string, unknown>, engine: KitEngine) => string | null | Promise<string | null>;
|
|
41
|
+
/** One renewal's length for an agent step's lease (milliseconds, `host/leaseAcquire`'s `ttl`); the host's own by default. */
|
|
42
|
+
agentLeaseTtl?: number;
|
|
43
|
+
/** The kit's engine merges the file into an older stored replica when it opens (`KitDocumentOptions.replicaMergesFile`). */
|
|
44
|
+
replicaMergesFile?: boolean;
|
|
45
|
+
/**
|
|
46
|
+
* Takes a change of the file on disk into the open document while it has no unsaved edits
|
|
47
|
+
* (`KitDocumentOptions.followFile`); without it, or when it answers `false`, the document reopens.
|
|
48
|
+
*/
|
|
49
|
+
followFile?: KitDocumentOptions['followFile'];
|
|
50
|
+
/**
|
|
51
|
+
* The person merged the agent's draft (`draft/merge`, section 7d): it is in the document as
|
|
52
|
+
* one step of the person's Undo (KitModel 1.1 M12a). A kit that keeps its own undo history
|
|
53
|
+
* records the step here. Called once the merge took changes in, before the host's answer.
|
|
54
|
+
*/
|
|
55
|
+
draftMerged?: (merged: {
|
|
56
|
+
summary: DraftSummary;
|
|
57
|
+
}) => void;
|
|
58
|
+
};
|
|
59
|
+
/** The error an `ai/run` step answers when another session holds the lease it needs (`data.reason` `held`). */
|
|
60
|
+
export declare function leaseHeldRefusal(command: string, step: number, scope: string, holder: KitLease['holder'] | null): KitRpcError;
|
|
61
|
+
/**
|
|
62
|
+
* Runs one agent step under the lease `scope` needs (none when empty): a lease another session
|
|
63
|
+
* holds refuses it before anything runs (`refuse` answers the error to throw), and the step's own
|
|
64
|
+
* lease is released when it ends, however it ends. Without a scope, a step that edits is refused
|
|
65
|
+
* while another session holds the whole document.
|
|
66
|
+
*/
|
|
67
|
+
export declare function withAgentLease<T>(leases: KitLeases, scope: string, mutates: boolean, ttl: number | undefined, step: () => Promise<T>, refuse: (scope: string, holder: KitLease['holder'] | null) => Error): Promise<T>;
|
|
68
|
+
export declare function useKitSession<T>(host: HostConnection, manifest: KitModuleManifest, describe: (info: KitEngineInfo) => T, options?: KitSessionOptions): {
|
|
69
|
+
run: (command: string, params?: Record<string, unknown>, damage?: RasterRect | null, options?: KitRunOptions) => Promise<string | null>;
|
|
70
|
+
editedBy: KitEditedBy | null;
|
|
71
|
+
comments: ReadonlySet<string>;
|
|
72
|
+
path: string;
|
|
73
|
+
manifest: KitModuleManifest;
|
|
74
|
+
doc: KitEngine | null;
|
|
75
|
+
info: KitEngineInfo | null;
|
|
76
|
+
state: T | null;
|
|
77
|
+
change: import(".//index.js").KitChange;
|
|
78
|
+
repaints: import(".//index.js").KitRepaints;
|
|
79
|
+
dirty: boolean;
|
|
80
|
+
failure: string | null;
|
|
81
|
+
openMs: number | null;
|
|
82
|
+
saving: boolean;
|
|
83
|
+
conflict: boolean;
|
|
84
|
+
tool: <R>(name: import("./engine/kitEngine.js").KitToolMethod, args?: unknown[], settled?: boolean) => Promise<R | null>;
|
|
85
|
+
commands: () => Promise<never[] | KitCommand[]>;
|
|
86
|
+
disabledCommands: () => Promise<string[] | never[]>;
|
|
87
|
+
save: () => Promise<void>;
|
|
88
|
+
replica: {
|
|
89
|
+
version: () => Promise<ArrayBuffer>;
|
|
90
|
+
exportChanges: (since: ArrayBuffer) => Promise<{
|
|
91
|
+
changes: ArrayBuffer;
|
|
92
|
+
blobs: ArrayBuffer;
|
|
93
|
+
}>;
|
|
94
|
+
importChanges: (changes: ArrayBuffer, blobs: ArrayBuffer) => Promise<unknown>;
|
|
95
|
+
docId: () => Promise<string | null>;
|
|
96
|
+
};
|
|
97
|
+
model: {
|
|
98
|
+
describe: (schema: object | null) => Promise<Record<string, unknown>>;
|
|
99
|
+
version: () => Promise<string>;
|
|
100
|
+
changes: (since: string, schema: object | null) => Promise<import("./engine/kitEngine.js").KitModelChanges>;
|
|
101
|
+
batch: (request: Record<string, unknown>, schema: object | null) => Promise<import("../../kit-ui-protocol/src/index.js").ModelBatchResult>;
|
|
102
|
+
};
|
|
103
|
+
draft: {
|
|
104
|
+
open: () => Promise<{
|
|
105
|
+
engine: KitEngine;
|
|
106
|
+
base: ArrayBuffer;
|
|
107
|
+
}>;
|
|
108
|
+
merge: (changes: ArrayBuffer, blobs: ArrayBuffer, origin: Origin, schema: object | null) => Promise<DraftSummary>;
|
|
109
|
+
compare: (changes: ArrayBuffer, schema: object | null) => Promise<DraftSummary>;
|
|
110
|
+
};
|
|
111
|
+
reopen: () => void;
|
|
112
|
+
keepMine: () => Promise<void>;
|
|
113
|
+
checkFile: (isCurrent?: () => boolean) => Promise<void>;
|
|
114
|
+
holdFile: (stamp: string) => Promise<void>;
|
|
115
|
+
};
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Engine contract 2 as TypeScript (Kition platform docs/platform/kits/engine.md, architecture 7.2): the document
|
|
3
|
+
* class a kit's engine worker drives. A WebAssembly engine made with `export_kit_document!` and
|
|
4
|
+
* `export_kit_session!` has exactly these members, so one worker (`@kition/sdk/editor`), the embed
|
|
5
|
+
* SDK, and the object model serve both runtimes.
|
|
6
|
+
*/
|
|
7
|
+
/** One historical coverage comparison from the kit's `covered` premise callback. */
|
|
8
|
+
export interface Covered {
|
|
9
|
+
id: string | number;
|
|
10
|
+
covered: boolean | null;
|
|
11
|
+
/** The held object no longer exists. The guard refuses with `deleted`. */
|
|
12
|
+
gone?: boolean;
|
|
13
|
+
content?: 'same' | 'changed' | 'deleted' | 'unknown';
|
|
14
|
+
}
|
|
15
|
+
export interface CoveredAt {
|
|
16
|
+
under: Array<string | number>;
|
|
17
|
+
covered: Covered[];
|
|
18
|
+
}
|
|
19
|
+
/** One command as `commands()` lists it (Kition platform docs/platform/reference/contract.md). */
|
|
20
|
+
export type KitEngineCommand = {
|
|
21
|
+
id: string;
|
|
22
|
+
title: string;
|
|
23
|
+
/** What the command does, when to choose it, and what it changes or answers: one or two sentences, never the title again or the parameter notation (`kition_kit::testing::check_commands`). */
|
|
24
|
+
description?: string | null;
|
|
25
|
+
/** The menu path, for example `["Page", "New"]`; `null` or empty when it is in no menu. */
|
|
26
|
+
menu: string[] | null;
|
|
27
|
+
/** As `Cmd+Shift+N`. */
|
|
28
|
+
shortcut: string | null;
|
|
29
|
+
mutates: boolean;
|
|
30
|
+
enabled: boolean;
|
|
31
|
+
/** The parameters as a JSON schema (`ParameterSchemaSpec`); commands with one can be agent tools. */
|
|
32
|
+
schema?: Record<string, unknown> | null;
|
|
33
|
+
/** What the command answers, as one `ValueSchemaSpec` (KHP A1 `output.schema`); optional. */
|
|
34
|
+
outputSchema?: Record<string, unknown> | null;
|
|
35
|
+
/** Parameter notes for an agent. */
|
|
36
|
+
params?: string | null;
|
|
37
|
+
/** Words an agent's command search finds it by that its id, title and params do not say (the effect names `effect.apply` takes); searched, never listed. */
|
|
38
|
+
keywords?: string[] | null;
|
|
39
|
+
};
|
|
40
|
+
/** What a change made stale on screen, as `importChanges` and `undo` answer it (Rust `Damage`). */
|
|
41
|
+
export type KitDamage = {
|
|
42
|
+
kind: 'none';
|
|
43
|
+
} | {
|
|
44
|
+
kind: 'full';
|
|
45
|
+
} | {
|
|
46
|
+
kind: 'rects';
|
|
47
|
+
rects: Array<[number, number, number, number]>;
|
|
48
|
+
};
|
|
49
|
+
export type KitCallContext = {
|
|
50
|
+
on?: Array<string | number>;
|
|
51
|
+
part?: Record<string, unknown>;
|
|
52
|
+
time?: number;
|
|
53
|
+
};
|
|
54
|
+
/** One open document. Every member is synchronous: the worker runs one request at a time. */
|
|
55
|
+
export interface KitEngineDocument {
|
|
56
|
+
readonly width: number;
|
|
57
|
+
readonly height: number;
|
|
58
|
+
/** Moves with every change. */
|
|
59
|
+
readonly revision: bigint;
|
|
60
|
+
/** Whether the document changed since the bytes `markSaved` confirmed. */
|
|
61
|
+
readonly dirty: boolean;
|
|
62
|
+
/** RGBA8 pixels; an engine whose editor draws itself answers transparent pixels. */
|
|
63
|
+
render(x: number, y: number, scale: number, width: number, height: number): Uint8Array;
|
|
64
|
+
renderArea(x0: number, y0: number, x1: number, y1: number, width: number, height: number): Uint8Array;
|
|
65
|
+
/** Runs a command as the host's person, JSON in and out. */
|
|
66
|
+
execute(command: string, params: string): string;
|
|
67
|
+
/** The document as JSON; it includes `canUndo` and `canRedo`. */
|
|
68
|
+
inspect(): string;
|
|
69
|
+
/** Every command as JSON (`KitEngineCommand[]`). */
|
|
70
|
+
commands(): string;
|
|
71
|
+
/** The ids of the commands that cannot run now, as JSON. */
|
|
72
|
+
disabledCommands(): string;
|
|
73
|
+
/** The document's diagnostics as JSON `{ diagnostics: KitEngineDiagnostic[] }` (KHP A21); optional. */
|
|
74
|
+
check?(): string;
|
|
75
|
+
/** The document as file bytes; it stays unsaved until `markSaved`. */
|
|
76
|
+
save(name?: string): Uint8Array;
|
|
77
|
+
markSaved(): void;
|
|
78
|
+
free(): void;
|
|
79
|
+
/** The replica's own id (a sync room's `docId`). */
|
|
80
|
+
readonly docId: string;
|
|
81
|
+
/** The replica's version, encoded. */
|
|
82
|
+
version(): Uint8Array;
|
|
83
|
+
/** The changes since `since` (empty bytes: all of them). */
|
|
84
|
+
exportChanges(since: Uint8Array): Uint8Array;
|
|
85
|
+
/** Imports another replica's changes; answers the damage as JSON. */
|
|
86
|
+
importChanges(changes: Uint8Array): string;
|
|
87
|
+
snapshot(): Uint8Array;
|
|
88
|
+
/** `{"done", "damage"}` as JSON. */
|
|
89
|
+
undo(): string;
|
|
90
|
+
redo(): string;
|
|
91
|
+
canUndo(): boolean;
|
|
92
|
+
canRedo(): boolean;
|
|
93
|
+
/** Runs a command as `origin`, the KDM's commit form `[kind, principal, label]` as JSON. */
|
|
94
|
+
executeAs(command: string, params: string, origin: string): string;
|
|
95
|
+
/** The schema version the replica reads (its kit's `model.schemaVersion`); optional. */
|
|
96
|
+
schemaVersion?(): number;
|
|
97
|
+
/**
|
|
98
|
+
* The newest schema version any of the replica's changes was written under (standard 2.0 rule
|
|
99
|
+
* M5a), or `null` when none records one; optional. Above `schemaVersion()`, a newer kit edited
|
|
100
|
+
* the document, and the host tells the person (Kit UI protocol `document/schema`).
|
|
101
|
+
*/
|
|
102
|
+
authorSchemaVersion?(): number | null;
|
|
103
|
+
/**
|
|
104
|
+
* The blobs the replica's changes refer to, as a bundle for `addBlobs`; a host sends them with
|
|
105
|
+
* every exchange of changes. Empty for a document without media.
|
|
106
|
+
*/
|
|
107
|
+
blobs(): Uint8Array;
|
|
108
|
+
addBlobs(blobs: Uint8Array): void;
|
|
109
|
+
/** Read-only premise callbacks, JSON in and out, evaluated in the worker's call context. */
|
|
110
|
+
premiseRead?(method: string, params: string): string;
|
|
111
|
+
forkForPremises?(): KitEngineDocument;
|
|
112
|
+
/** Opaque transient state, or JSON null when the kit cannot isolate agent contexts. */
|
|
113
|
+
editorState?(): string;
|
|
114
|
+
restoreEditorState?(state: string): void;
|
|
115
|
+
setContext?(context: string): void;
|
|
116
|
+
}
|
|
117
|
+
/** The document class a module exports under the manifest's `engine.class`. */
|
|
118
|
+
export interface KitEngineClass {
|
|
119
|
+
/** 1: hosts built for contract 1 open it; the manifest and the session members make it contract 2. */
|
|
120
|
+
contractVersion(): number;
|
|
121
|
+
open(name: string, bytes: Uint8Array): KitEngineDocument;
|
|
122
|
+
/** Opens a file with the replica stored for it; a file that holds its replica may ignore them. */
|
|
123
|
+
openWithReplica(name: string, bytes: Uint8Array, snapshot: Uint8Array, blobs: Uint8Array): KitEngineDocument;
|
|
124
|
+
create(name: string, width: number, height: number): KitEngineDocument;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* What a `ts-worker` module's default export receives before its first document (rule K11): where
|
|
128
|
+
* the module was loaded from, and, where `fetch` cannot read files (Node), how to read one of the
|
|
129
|
+
* package's files by its path relative to `base`.
|
|
130
|
+
*/
|
|
131
|
+
export type KitEngineInit = {
|
|
132
|
+
base: string;
|
|
133
|
+
read?: (file: string) => Promise<Uint8Array>;
|
|
134
|
+
};
|
|
135
|
+
/** The module's default export: prepares the engine (for example, loads its dependencies' WebAssembly). */
|
|
136
|
+
export type KitEngineModuleInit = (init: KitEngineInit) => Promise<void>;
|
|
137
|
+
/** One thing an engine found wrong with its document (KHP A21): a stable `<kit>.<name>` code, what it is about (none set: the whole document; pages and slides count from 1), and a command hint to fix it. */
|
|
138
|
+
export type KitEngineDiagnostic = {
|
|
139
|
+
code: string;
|
|
140
|
+
severity: 'error' | 'warning' | 'info';
|
|
141
|
+
target: {
|
|
142
|
+
objectId?: string;
|
|
143
|
+
path?: string;
|
|
144
|
+
page?: number;
|
|
145
|
+
slide?: number;
|
|
146
|
+
sheet?: string;
|
|
147
|
+
cell?: string;
|
|
148
|
+
};
|
|
149
|
+
message: string;
|
|
150
|
+
fix?: {
|
|
151
|
+
command: string;
|
|
152
|
+
params?: Record<string, unknown>;
|
|
153
|
+
};
|
|
154
|
+
};
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
export type { Covered, CoveredAt, KitCallContext, KitDamage, KitEngineClass, KitEngineCommand, KitEngineDiagnostic, KitEngineDocument, KitEngineInit, KitEngineModuleInit } from './contract.js';
|
|
2
|
+
export { historyScope, kitEngineClass, KitSession, mergeDamage, type KitEngineClassOptions, type KitModel, type KitSize } from './session.js';
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `KitSession`: the TypeScript twin of `kition_kit::session` (architecture 7.1 and 7.2). A kit
|
|
3
|
+
* supplies a `KitModel`, its materialised view over a KDM replica and its commands, and
|
|
4
|
+
* `kitEngineClass` makes the contract 2 document class from it: the replica, the exchange of
|
|
5
|
+
* changes, undo and redo, the saved state, and the JSON of the contract.
|
|
6
|
+
*/
|
|
7
|
+
import { Replica, type ObjectId, type Origin, type ProjectedObject, type Schema, type Tx, type UndoScope } from '../../kdm/src/index.js';
|
|
8
|
+
import type { KitCallContext, KitDamage, KitEngineClass, KitEngineCommand, KitEngineDiagnostic, KitEngineDocument } from './contract.js';
|
|
9
|
+
export type KitSize = {
|
|
10
|
+
width: number;
|
|
11
|
+
height: number;
|
|
12
|
+
};
|
|
13
|
+
/**
|
|
14
|
+
* A kit's engine on the KDM: its view of a replica and how commands change the replica.
|
|
15
|
+
*
|
|
16
|
+
* - E11: `load` builds the view, `apply` patches it from the objects an import, undo, or redo
|
|
17
|
+
* changed (throw to have it loaded again).
|
|
18
|
+
* - E12: `command` turns a command into transactions on the replica (`replica.transact`); a view
|
|
19
|
+
* that changes itself first records the difference as the command's transaction, as long as
|
|
20
|
+
* `apply` still brings it up to date.
|
|
21
|
+
* - E13: `import` makes a new replica from file bytes (`Replica.createWith`), `export` writes the
|
|
22
|
+
* file from the replica.
|
|
23
|
+
* - E14: `validate` repairs what a merge left invalid; its changes commit with origin `system`.
|
|
24
|
+
*/
|
|
25
|
+
export interface KitModel<View> {
|
|
26
|
+
readonly schema: Schema;
|
|
27
|
+
projectedObjects?(view: View, replica: Replica): ProjectedObject[];
|
|
28
|
+
load(replica: Replica): View;
|
|
29
|
+
apply(view: View, replica: Replica, changed: ReadonlySet<ObjectId>): KitDamage;
|
|
30
|
+
/** Runs `id`; answers its JSON result. Throw to refuse it. */
|
|
31
|
+
command(view: View, replica: Replica, id: string, params: Record<string, unknown>, origin: Origin): unknown;
|
|
32
|
+
commands(view: View, replica: Replica): KitEngineCommand[];
|
|
33
|
+
/** Repairs, as one transaction; answers whether it wrote anything. */
|
|
34
|
+
validate?(tx: Tx, replica: Replica, changed: ReadonlySet<ObjectId>): boolean;
|
|
35
|
+
import(name: string, bytes: Uint8Array, actor: bigint): Replica;
|
|
36
|
+
/**
|
|
37
|
+
* Opens file bytes with the replica a host stored for them (`openWithReplica`), for a format that
|
|
38
|
+
* does not hold its replica (Markdown): the replica from `snapshot` (a KDM snapshot or a full
|
|
39
|
+
* change export, `blobs` its media), and what the file says that it lacks as a `system` import
|
|
40
|
+
* change; empty `bytes` open the replica alone. Without it, a stored replica adds nothing to a
|
|
41
|
+
* file that holds its own, which opens as `import` makes it.
|
|
42
|
+
*/
|
|
43
|
+
openReplica?(name: string, bytes: Uint8Array, snapshot: Uint8Array, blobs: Uint8Array, actor: bigint): Replica;
|
|
44
|
+
export(view: View, replica: Replica, name: string): Uint8Array;
|
|
45
|
+
/** A new document; without it, `create` refuses. */
|
|
46
|
+
create?(name: string, size: KitSize, actor: bigint): Replica;
|
|
47
|
+
/**
|
|
48
|
+
* Media: the blob bundle the replica's changes refer to, and taking one in. Without them the
|
|
49
|
+
* document has no media: `blobs()` is empty and a bundle someone sends is refused.
|
|
50
|
+
*/
|
|
51
|
+
blobs?(view: View, replica: Replica): Uint8Array;
|
|
52
|
+
addBlobs?(view: View, replica: Replica, blobs: Uint8Array): void;
|
|
53
|
+
/** What `inspect()` adds to `canUndo` and `canRedo`. */
|
|
54
|
+
inspect?(view: View, replica: Replica): Record<string, unknown>;
|
|
55
|
+
/** What is wrong with the document (Kit Harness Protocol (KHP) A21); without it, `check()` answers none. It must not change the document. */
|
|
56
|
+
check?(view: View, replica: Replica): KitEngineDiagnostic[];
|
|
57
|
+
/** The document's size in pixels (0 × 0 when the editor draws itself). */
|
|
58
|
+
size?(view: View, replica: Replica): KitSize;
|
|
59
|
+
/** Kit-defined guard reads; return null from `under` when the command has no extra premises. */
|
|
60
|
+
premise?(view: View, replica: Replica, method: string, params: Record<string, unknown>): unknown;
|
|
61
|
+
/** Transient selection/part/time state. Supply all three hooks to isolate agent calls. */
|
|
62
|
+
editorState?(view: View, replica: Replica): unknown;
|
|
63
|
+
restoreEditorState?(view: View, replica: Replica, state: unknown): void;
|
|
64
|
+
setContext?(view: View, replica: Replica, context: KitCallContext): void;
|
|
65
|
+
}
|
|
66
|
+
/** Both damages: full absorbs everything, rects add up. */
|
|
67
|
+
export declare function mergeDamage(a: KitDamage, b: KitDamage): KitDamage;
|
|
68
|
+
/** One document: a replica, the model's view of it, and its saved state. */
|
|
69
|
+
export declare class KitSession<View> {
|
|
70
|
+
readonly model: KitModel<View>;
|
|
71
|
+
readonly replica: Replica;
|
|
72
|
+
private viewState;
|
|
73
|
+
private savedVersion;
|
|
74
|
+
/** The version the bytes of the last `save()` hold, until `markSaved`. */
|
|
75
|
+
private pendingSave;
|
|
76
|
+
private revisionCount;
|
|
77
|
+
constructor(model: KitModel<View>, replica: Replica);
|
|
78
|
+
get view(): View;
|
|
79
|
+
get revision(): bigint;
|
|
80
|
+
get dirty(): boolean;
|
|
81
|
+
/** Runs a command as `origin`; the view follows what it committed. */
|
|
82
|
+
execute(id: string, params: Record<string, unknown>, origin: Origin): unknown;
|
|
83
|
+
/** Applies only a validated file difference, retaining both undo histories and identities. */
|
|
84
|
+
reread(reconcile: (view: View, tx: Tx) => void): KitDamage;
|
|
85
|
+
/** Imports another replica's changes; repairs what they left invalid. */
|
|
86
|
+
importChanges(bytes: Uint8Array): KitDamage;
|
|
87
|
+
/** Undoes the person's last step (KitModel M12a: never an agent's). */
|
|
88
|
+
undo(): {
|
|
89
|
+
done: boolean;
|
|
90
|
+
damage: KitDamage;
|
|
91
|
+
};
|
|
92
|
+
redo(): {
|
|
93
|
+
done: boolean;
|
|
94
|
+
damage: KitDamage;
|
|
95
|
+
};
|
|
96
|
+
/** Undoes the last step of `scope` (an agent's undo takes back only the agent's steps); repairs the result. */
|
|
97
|
+
undoIn(scope: UndoScope): {
|
|
98
|
+
done: boolean;
|
|
99
|
+
damage: KitDamage;
|
|
100
|
+
};
|
|
101
|
+
redoIn(scope: UndoScope): {
|
|
102
|
+
done: boolean;
|
|
103
|
+
damage: KitDamage;
|
|
104
|
+
};
|
|
105
|
+
/** The file bytes; the document stays unsaved until `markSaved`. */
|
|
106
|
+
save(name: string): Uint8Array;
|
|
107
|
+
markSaved(): void;
|
|
108
|
+
/** After an import, undo, or redo: validate over what changed (a `system` repair), then apply both. */
|
|
109
|
+
private settle;
|
|
110
|
+
/** Applies `changed` to the view; if that fails, loads the view again so it still matches. */
|
|
111
|
+
private refresh;
|
|
112
|
+
}
|
|
113
|
+
/** Options of `kitEngineClass`. */
|
|
114
|
+
export type KitEngineClassOptions = {
|
|
115
|
+
/** The actor of each new replica; a random one by default (each open document is its own replica). */
|
|
116
|
+
actor?: () => bigint;
|
|
117
|
+
};
|
|
118
|
+
/**
|
|
119
|
+
* The contract 2 document class for `model`, to export under the manifest's `engine.class`:
|
|
120
|
+
*
|
|
121
|
+
* ```ts
|
|
122
|
+
* export const BoardDocument = kitEngineClass(boardModel)
|
|
123
|
+
* ```
|
|
124
|
+
*/
|
|
125
|
+
export declare function kitEngineClass<View>(model: KitModel<View>, options?: KitEngineClassOptions): KitEngineClass & (new (session: KitSession<View>) => KitEngineDocument & {
|
|
126
|
+
readonly session: KitSession<View>;
|
|
127
|
+
});
|
|
128
|
+
/**
|
|
129
|
+
* The undo scope an `edit.undo` or `edit.redo` works in (KitModel M12a): the one its `scope`
|
|
130
|
+
* parameter names (`"person"` or `"agent"`), else its origin's (`agent` for an agent's step,
|
|
131
|
+
* `person` for the person's and for scripts). The Rust twin is `kition_kit::session::history_scope`.
|
|
132
|
+
*/
|
|
133
|
+
export declare function historyScope(params: Record<string, unknown>, origin: Origin): UndoScope;
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The host's side of KitFiles 1.0 (Kition platform `docs/platform/sets/files.md`; Kit UI protocol section
|
|
3
|
+
* 7g): a session's grant table (handle → session, kit, principal, rights, kind), the `files/*`
|
|
4
|
+
* requests served from it with the host's own storage, staged writes, and names that never
|
|
5
|
+
* replace a file. The host's storage speaks in its own references (`KitFileRef`, such as a
|
|
6
|
+
* workspace path); they never leave this module: the kit sees only handles and display names
|
|
7
|
+
* (FA-P2, UI-F1).
|
|
8
|
+
*/
|
|
9
|
+
import { KitRpcError, type KitFileErrorReason, type KitFileRight, type KitFileStat, type KitFilesPickParams, type KitToHost } from '../../kit-ui-protocol/src/index.js';
|
|
10
|
+
/** The host's own name for a file or folder (a workspace path). The kit never sees it. */
|
|
11
|
+
export type KitFileRef = string;
|
|
12
|
+
/** A file or folder as the host's storage sees it now. */
|
|
13
|
+
export type KitFileEntry = {
|
|
14
|
+
kind: 'file' | 'folder';
|
|
15
|
+
size?: number;
|
|
16
|
+
mime?: string;
|
|
17
|
+
version: string | null;
|
|
18
|
+
};
|
|
19
|
+
/** A write in progress, kept by the storage (a temporary file) until it commits or is aborted. */
|
|
20
|
+
export type KitFileStaging = {
|
|
21
|
+
append: (bytes: Uint8Array) => Promise<void>;
|
|
22
|
+
/** Commits atomically (temporary file, then rename, H4), as `commit` does with the staged bytes. */
|
|
23
|
+
commit: () => Promise<{
|
|
24
|
+
version: string;
|
|
25
|
+
}>;
|
|
26
|
+
abort: () => Promise<void>;
|
|
27
|
+
};
|
|
28
|
+
/** How a staged write commits: a new file (never an existing one), or a replacement of the version the kit read. */
|
|
29
|
+
export type KitFileCommitMode = {
|
|
30
|
+
mode: 'create';
|
|
31
|
+
} | {
|
|
32
|
+
mode: 'replace';
|
|
33
|
+
expected: string;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* The host's storage, in its own references. Every answer about a file the kit may not see (outside
|
|
37
|
+
* the workspace, the host's own data, a hidden path; H3, LR2, FA8) is the same as for a missing file.
|
|
38
|
+
*/
|
|
39
|
+
export type KitFilesStorage = {
|
|
40
|
+
/** The file or folder at `ref`; `null` when there is none or the kit may not see it. */
|
|
41
|
+
stat: (ref: KitFileRef) => KitFileEntry | null | Promise<KitFileEntry | null>;
|
|
42
|
+
/** At most `length` bytes from `offset` (to the end without `length`); `size` is the whole file's. */
|
|
43
|
+
read: (ref: KitFileRef, offset: number, length: number | undefined) => Promise<{
|
|
44
|
+
bytes: ArrayBuffer;
|
|
45
|
+
version: string;
|
|
46
|
+
size: number;
|
|
47
|
+
}>;
|
|
48
|
+
/** A folder's entries, not recursively. */
|
|
49
|
+
list: (ref: KitFileRef) => KitFileRef[] | Promise<KitFileRef[]>;
|
|
50
|
+
/** The reference of `name` in `folder`; `null` is the document's own folder. */
|
|
51
|
+
child: (folder: KitFileRef | null, name: string) => KitFileRef;
|
|
52
|
+
/** The display name of `ref`: its last segment. Default: what follows the last `/` or `\`. */
|
|
53
|
+
name?: (ref: KitFileRef) => string;
|
|
54
|
+
/**
|
|
55
|
+
* Puts `bytes` at `ref` atomically. `create` MUST refuse a file that exists (throw `fileError('conflict')`);
|
|
56
|
+
* `replace` MUST refuse unless the file's version is still `expected` (`conflict`).
|
|
57
|
+
*/
|
|
58
|
+
commit: (ref: KitFileRef, bytes: Uint8Array, mode: KitFileCommitMode) => Promise<{
|
|
59
|
+
version: string;
|
|
60
|
+
}>;
|
|
61
|
+
/** Stages a write elsewhere than in memory (a temporary file), for exports of any length. Absent: staged in memory, then `commit`. */
|
|
62
|
+
stage?: (ref: KitFileRef, mode: () => KitFileCommitMode) => KitFileStaging;
|
|
63
|
+
/** The file is open with unsaved edits in an editor (FA14). */
|
|
64
|
+
unsaved?: (ref: KitFileRef) => boolean | Promise<boolean>;
|
|
65
|
+
};
|
|
66
|
+
/** What a kit may ask for, from its manifest's `files` (K15): extensions without the dot. */
|
|
67
|
+
export type KitFilesManifest = {
|
|
68
|
+
read?: string[];
|
|
69
|
+
create?: string[];
|
|
70
|
+
folders?: boolean;
|
|
71
|
+
print?: boolean;
|
|
72
|
+
};
|
|
73
|
+
/** How a handle was granted (KitFiles section 3), for the grant log. */
|
|
74
|
+
export type KitFileGrantFlow = 'pick' | 'create' | 'list' | 'agent' | 'drop';
|
|
75
|
+
/** One grant, as the host records it in its session log (section 7, A10, A30) and shows it (FA16). */
|
|
76
|
+
export type KitFileGrant = {
|
|
77
|
+
handle: string;
|
|
78
|
+
session: string;
|
|
79
|
+
kit: string;
|
|
80
|
+
principal: string;
|
|
81
|
+
flow: KitFileGrantFlow;
|
|
82
|
+
rights: KitFileRight[];
|
|
83
|
+
kind: 'file' | 'folder';
|
|
84
|
+
name: string;
|
|
85
|
+
};
|
|
86
|
+
export type KitFilesOptions = {
|
|
87
|
+
storage: KitFilesStorage;
|
|
88
|
+
/** The kit's id, and the person (or the person an agent runs for) the handles are bound to (FA1). */
|
|
89
|
+
kit: string;
|
|
90
|
+
principal: string;
|
|
91
|
+
/** The kit manifest's `files` lists (K15). Absent: the kit asked for nothing, and every grant is refused. */
|
|
92
|
+
manifest?: KitFilesManifest;
|
|
93
|
+
/** The host's picker (capability `files-pick`): answers the references the person chose, none when they cancel. */
|
|
94
|
+
pick?: (params: KitFilesPickParams) => Promise<KitFileRef[]>;
|
|
95
|
+
/** The system's print dialog (capability `print`): answers whether the person printed. */
|
|
96
|
+
print?: (job: {
|
|
97
|
+
bytes: Uint8Array;
|
|
98
|
+
title: string;
|
|
99
|
+
}) => Promise<boolean>;
|
|
100
|
+
/**
|
|
101
|
+
* Whether the person just made a gesture in the kit (FA6, FA11). Default: the page's transient
|
|
102
|
+
* user activation, which a click in the kit's frame gives its parent too; true where the browser
|
|
103
|
+
* does not tell.
|
|
104
|
+
*/
|
|
105
|
+
gesture?: () => boolean;
|
|
106
|
+
/** Caps on the bytes written per grant and per session (FA10). */
|
|
107
|
+
quota?: {
|
|
108
|
+
perGrant?: number;
|
|
109
|
+
perSession?: number;
|
|
110
|
+
};
|
|
111
|
+
/** Every grant, for the host's session log. */
|
|
112
|
+
log?: (grant: KitFileGrant) => void;
|
|
113
|
+
/** Every `files/*` request the kit sends, before it is served (`@kition/sdk/dev-host`'s `checkNoPaths`). */
|
|
114
|
+
trace?: (method: string, params: unknown) => void;
|
|
115
|
+
};
|
|
116
|
+
/** A `files/*` refusal: `-32000` with `error.data.reason` (KitFiles section 10). */
|
|
117
|
+
export declare function fileError(reason: KitFileErrorReason, message: string): KitRpcError;
|
|
118
|
+
/** The extension of a name, lower case, without the dot; empty when it has none. */
|
|
119
|
+
export declare function extensionOf(name: string): string;
|
|
120
|
+
/**
|
|
121
|
+
* A name the host may create (FA15): the last segment only, no control characters or characters
|
|
122
|
+
* the platforms reserve, no leading dot, no trailing dot or space, no reserved device name
|
|
123
|
+
* (`CON`, `NUL` on Windows), at most 255 characters; `Untitled` when nothing is left.
|
|
124
|
+
*/
|
|
125
|
+
export declare function sanitizeFileName(suggested: string): string;
|
|
126
|
+
/** `Report.pdf`, then `Report 2.pdf`, `Report 3.pdf`, …: the first name `taken` says is free (FA7). */
|
|
127
|
+
export declare function unusedName(name: string, taken: (candidate: string) => boolean | Promise<boolean>): Promise<string>;
|
|
128
|
+
/** One kit session's file grants and the `files/*` requests served from them. */
|
|
129
|
+
export type KitFileSession = {
|
|
130
|
+
/** This session's id (FA1). */
|
|
131
|
+
id: string;
|
|
132
|
+
/** The capabilities to list in `ui/initialize`: `files`, and `files-pick` and `print` when the host has them. */
|
|
133
|
+
capabilities: string[];
|
|
134
|
+
/**
|
|
135
|
+
* Grants a handle on a file the host chose (an agent's `file` parameter, A28; a drop): the same
|
|
136
|
+
* policy as the kit's own requests. A `write` grant from an agent needs `approved` (a draft beside
|
|
137
|
+
* the file, or the person's explicit approval; FA13), and no session that is read-only gets one (FA17).
|
|
138
|
+
* The document the agent's tool call targets is never granted here: saving it is editing it
|
|
139
|
+
* (`host/write`, A7, A12), not replacing a file under FA13.
|
|
140
|
+
*/
|
|
141
|
+
grant: (ref: KitFileRef, rights: KitFileRight[], options: {
|
|
142
|
+
flow: 'agent' | 'drop';
|
|
143
|
+
approved?: boolean;
|
|
144
|
+
}) => Promise<KitFileStat>;
|
|
145
|
+
/** Revokes handles early (FA4, FA16) and tells the kit (`files/revoked`). */
|
|
146
|
+
revoke: (handles: string[]) => Promise<void>;
|
|
147
|
+
/** What this session holds now (FA16). */
|
|
148
|
+
grants: () => KitFileGrant[];
|
|
149
|
+
/** Serves a `files/*` request from the kit. */
|
|
150
|
+
serve: <M extends FilesMethod>(method: M, params: KitToHost[M][0]) => Promise<KitToHost[M][1]>;
|
|
151
|
+
/** The session ended (the frame closed): every handle expires and staged writes are dropped (FA4, FA9). */
|
|
152
|
+
end: () => Promise<void>;
|
|
153
|
+
};
|
|
154
|
+
export type FilesMethod = 'files/pick' | 'files/create' | 'files/stat' | 'files/read' | 'files/list' | 'files/write' | 'files/release' | 'files/print';
|
|
155
|
+
export declare const FILES_METHODS: FilesMethod[];
|
|
156
|
+
/**
|
|
157
|
+
* Opens one kit session's grant table. `readOnly` is the document's (UI-K7, FA17); `revoked` tells
|
|
158
|
+
* the kit of handles revoked early.
|
|
159
|
+
*/
|
|
160
|
+
export declare function openFileSession(options: KitFilesOptions & {
|
|
161
|
+
readOnly?: boolean;
|
|
162
|
+
revoked?: (handles: string[]) => void;
|
|
163
|
+
}): KitFileSession;
|