@yuzhouu/canvas-kit 0.1.9 → 0.1.11

package/README.md

@@ -1,151 +1,254 @@
 # @land/canvas-kit
 
-`@land/canvas-kit` is the public React SDK for the Land canvas kit. It includes the product runtime, built-in canvas extensions, image integration, persistence, chrome context, and typed controller surface behind one package root.
+CanvasKit is the public composition root for the Land canvas. It compiles one graph of `CanvasPlugin` objects and nested plugin groups to assemble an isolated Runtime, then exposes a controller-oriented API without exposing Editor, services, registries, or private render data.
 
-## Install
+## React usage
 
-```bash
-pnpm add @land/canvas-kit react react-dom
-```
-
-## Basic Usage
+Keep the options object stable. The hook uses reference identity to decide when to replace a Runtime.
 
 ```tsx
-import { useMemo } from "react";
 import {
   CanvasKitRoot,
-  defineCanvasKit,
+  useCanvasKitRuntime,
+  type CanvasKitRuntimeOptions,
 } from "@land/canvas-kit";
-import "@land/canvas-kit/style.css";
+
+const RUNTIME_OPTIONS: CanvasKitRuntimeOptions = {
+  id: "my-canvas",
+  storageNamespace: "my-app.canvas",
+};
 
 export function App() {
-  const product = useMemo(
-    () =>
-      defineCanvasKit({
-        onControllerReady(controller) {
-          console.log(controller.snapshot());
-        },
-      }),
-    [],
-  );
+  const state = useCanvasKitRuntime(RUNTIME_OPTIONS);
+
+  if (state.status === "error") throw state.error;
+  if (state.status !== "ready") return null;
 
   return (
-    <div style={{ width: "100%", height: "100vh" }}>
-      <CanvasKitRoot product={product} />
-    </div>
+    <CanvasKitRoot
+      runtime={state.runtime}
+      onControllerReady={(controller) => {
+        controller.setTool("select");
+      }}
+    />
   );
 }
 ```
 
-The host element must provide a size. `CanvasKitRoot` fills the space provided by its parent and mounts the canvas runtime for the product.
+Use a module-level constant or `useMemo` for `CanvasKitRuntimeOptions`. An inline object creates and disposes a Runtime after every render.
 
-## Custom Chrome
+## Imperative usage
 
-Use the `chrome` option when you want to provide your own toolbar, panels, or menus while keeping the kit runtime and built-in extensions.
+The creator owns the complete lifecycle:
 
 ```tsx
-import { useMemo } from "react";
+import { createRoot } from "react-dom/client";
 import {
   CanvasKitRoot,
-  defineCanvasKit,
-  type CanvasKitController,
-  type CanvasKitChromeContext,
+  createCanvasKitRuntime,
 } from "@land/canvas-kit";
-import "@land/canvas-kit/style.css";
 
-function MyChrome({
-  context,
-}: {
-  context: CanvasKitChromeContext<CanvasKitController>;
-}) {
-  return (
-    <>
-      <button
-        type="button"
-        disabled={!context.history.canUndo}
-        onClick={context.history.undo}
-      >
-        Undo
-      </button>
-      <button type="button" onClick={context.zoom.zoomIn}>
-        Zoom in
-      </button>
-      <button
-        type="button"
-        disabled={context.selection.count === 0}
-        onClick={() => context.controller.deleteShapes([...context.selectedShapeIds])}
-      >
-        Delete
-      </button>
-    </>
-  );
+const runtime = createCanvasKitRuntime({ persistence: null });
+const startup = await runtime.start();
+
+const root = createRoot(document.getElementById("app")!);
+root.render(<CanvasKitRoot runtime={runtime} />);
+
+// Later:
+root.unmount();
+runtime.dispose();
+```
+
+One Runtime can be mounted by only one `CanvasKitRoot` at a time. `CanvasKitRoot` requires a ready Runtime and never calls `start()` or `dispose()`.
+
+## Runtime options
+
+```ts
+interface CanvasKitRuntimeOptions {
+  id?: string;
+  chrome?: CanvasKitChromeRenderer;
+  documentMeta?: Record<string, unknown>;
+  persistence?: ProductPersistenceAdapter | null;
+  seedDocument?: CanvasKitDocumentSeed;
+  shouldSkipStoredSnapshots?: () => boolean;
+  plugins?: readonly CanvasPluginInput[];
+  storageNamespace?: string;
 }
+```
 
-export function App() {
-  const product = useMemo(
-    () =>
-      defineCanvasKit({
-        chrome: (context) => <MyChrome context={context} />,
-      }),
-    [],
-  );
+Controller callbacks, window exposure, and `windowKey` are mount concerns and
+belong on `CanvasKitRoot`. Export appearance is supplied to each export request;
+it is not stored on the Root or Runtime.
 
-  return (
-    <div style={{ width: "100%", height: "100vh" }}>
-      <CanvasKitRoot product={product} />
-    </div>
-  );
+`plugins` is the complete caller-supplied plugin graph. Before compiling it,
+CanvasKit adds a built-in default provider for generic tool actions or the
+export API only when the graph does not already provide the corresponding
+capability token. A plugin that provides `canvasToolActionsCapability` or
+`canvasExportApiToken` therefore replaces that built-in implementation.
+Built-in defaults and caller plugins use the same `CanvasPlugin` contract and
+compile into one dependency graph.
+
+## Startup result
+
+`runtime.start()` is single-flight and idempotent. It returns:
+
+```ts
+interface CanvasKitStartupResult {
+  documentSource: "restored" | "seeded" | "empty";
+  sessionRestored: boolean;
+  warnings: readonly unknown[];
 }
 ```
 
-Chrome should operate through `CanvasKitChromeContext` and `context.controller`. The product shell owns canvas mounting, so custom chrome should render controls and overlays rather than the canvas itself. It should not import `@land/canvas-core`, `@land/canvas-react`, built-in plugin packages, or kit internals.
+Startup loads snapshots, resets to a clean document/session, restores the document or seeds after a clean fallback, restores session state, clears history, prepares assets, runs `beforeReady`, and starts Runtime-owned persistence coordination. Recoverable load/restore/asset/hook errors are returned in `warnings`. Synchronous assembly and seed failures are fatal.
 
-The package no longer exposes a one-component direct render entry. Apps should define a product with `defineCanvasKit` and render it through `CanvasKitRoot`.
+Disposal aborts startup and unwinds one Runtime-owned disposer stack in reverse creation order. Persistence, plugin setup resources, Editor, and services all enter that stack. A disposed Runtime cannot restart.
 
-## Local Persistence
+## Persistence adapter
 
-Default browser persistence restores supported records even when a saved
-snapshot also contains unsupported shape or binding types. Unsupported raw
-records are preserved outside the live editor and merged back into future saves.
-When this happens, `CanvasKitRoot` shows a persistence notice and custom
-chrome can inspect `context.persistence.status` or call
-`context.persistence.discardUnsupportedRecords?.()` after explicit user
-confirmation.
+Persistence is IO-only; Runtime owns restore and seed ordering.
 
-## Internal Assembly
+```ts
+interface ProductPersistenceAdapter {
+  load?(options: {
+    signal: AbortSignal;
+  }): Promise<{
+    documentSnapshot: unknown | null;
+    sessionSnapshot: unknown | null;
+  }>;
+  saveDocument?(snapshot: DocumentSnapshot): Promise<void>;
+  saveSession?(snapshot: SessionSnapshot): Promise<void>;
+}
+```
+
+Runtime captures document state from operation commits, captures session state
+independently, applies trailing debounce, retries transient write failures, and
+passes immutable snapshots to the adapter. When no document snapshot exists,
+`seedDocument` runs once. Session restore happens after seed so persisted camera
+and selection state win.
+
+## Plugin authoring
+
+Use `defineCanvasPlugin()` and pass plugins or nested plugin groups through Runtime options:
+
+```ts
+import {
+  createProductServiceToken,
+  createStandardCanvasKitPlugins,
+  defineCanvasPlugin,
+  type CanvasKitRuntimeOptions,
+} from "@land/canvas-kit";
+
+const analyticsToken = createProductServiceToken<{ track(name: string): void }>(
+  "example.analytics",
+);
+
+const analyticsPlugin = defineCanvasPlugin({
+  id: "example.analytics",
+  provides: [analyticsToken],
+  setup(context) {
+    const analytics = context.services.add({
+      token: analyticsToken,
+      create: () => ({ track: console.log }),
+    });
+    context.actions.add({
+      id: "example.track",
+      run: () => analytics.track("canvas-action"),
+    });
+  },
+});
+
+const reportingPlugin = defineCanvasPlugin({
+  id: "example.reporting",
+  requires: [analyticsToken],
+  setup(context) {
+    context.services.get(analyticsToken)?.track("runtime-ready");
+  },
+});
+
+const options: CanvasKitRuntimeOptions = {
+  plugins: [
+    createStandardCanvasKitPlugins(),
+    [analyticsPlugin, reportingPlugin],
+  ],
+};
+```
+
+`CanvasPlugin` has optional `editor`, `render`, and `setup` entries. `requires` lives at the plugin top level, so one dependency order applies to editor/render creation and setup installation. Depend on a plugin object when the whole extension must exist; depend on a typed API, service, or value capability token when only that cross-plugin contract matters. Providers declare those tokens in `provides` and register the matching implementation during setup. Raw `{ id }` dependency objects are rejected.
 
-The public product remains opaque. Internally, `defineCanvasKit()` resolves options into explicit product fields:
+Nested arrays are groups only; they do not need IDs and are flattened in declaration order. Optional features are included or omitted explicitly.
 
-- `LandExtension[]` installs editor/canvas render plugins through `@land/canvas-react/host`.
-- `CanvasKitHostExtension[]` installs product-host behavior such as clipboard, toolbar, context menu, image import, asset URL resolution, SVG asset inlining, and controller components.
-- Service factories and asset resolver tokens wire product-level services into runtime.
-- `CanvasKitRuntime` creates services, the plugin host runtime, the editor, controller registry, and then runs product runtime setup.
+Runtime creation compiles the graph, creates Editor and the Runtime resource owner, runs each setup once in dependency order, then seals all registries. Sealing validates duplicate IDs and action references, materializes registered APIs, and prevents later registration.
 
-Advanced products can pass additional `hostExtensions` to `defineCanvasKit()`
-for product-host behavior that should compose with the built-in runtime instead
-of being hard-coded in chrome or canvas runtime modules.
+Packaging is intentionally outside the standard plugin profile. Products that
+need it add the public plugin explicitly:
 
-This keeps app chrome on the root package controller while keeping browser-specific host behavior out of concrete shape plugins and out of `canvas-core`.
+```ts
+import {
+  Packaging,
+  createStandardCanvasKitPlugins,
+  type CanvasKitRuntimeOptions,
+} from "@land/canvas-kit";
+
+const options: CanvasKitRuntimeOptions = {
+  plugins: [createStandardCanvasKitPlugins(), Packaging],
+};
+```
+
+`setup(context)` installs capabilities through focused registrars:
+
+- `actions`, `toolbar`, `contextMenu`, and `apis`
+- `services`
+- `assets`
+- `ui`
+- `lifecycle.beforeReady()`, `lifecycle.beforeCommand()`, and `lifecycle.defer()`
 
-## Public Exports
+`setup` returns nothing. Every owned resource registers cleanup through `lifecycle.defer()`, which gives Runtime one cleanup protocol and reverse-order resource stack. `beforeReady` runs serially during `start()` after restore/seed and asset preparation. `beforeCommand` is a repeatable interceptor executed by the Runtime-bound command executor.
 
-The published package intentionally exposes only:
+The set-active-tool and tool-lock actions are provided by the replaceable
+built-in default for `canvasToolActionsCapability`, so shape toolbar plugins do
+not depend on the standard profile installing a Tool action provider.
+Components share one props contract and render between Canvas and chrome; there
+are no component slots.
 
-- `@land/canvas-kit`
-- `@land/canvas-kit/style.css`
+## Public controller
 
-Package subpaths are internal implementation details.
+External code should work through `runtime.controller` or the controller supplied to `onControllerReady`. The controller exposes document, selection, page, tool, camera, layer, history, export, built-in shape creation, and registered API operations without exposing the raw store.
 
-## Local Build
+### Export API
 
-Run from the workspace root:
+SVG and PNG export are async registered APIs so resource preparation and
+embedding complete before a result is returned:
 
-```bash
-pnpm build:canvas-kit:bundle
+```ts
+import { canvasExportApiToken } from "@land/canvas-kit";
+
+const exportApi = runtime.controller.apis.get(canvasExportApiToken);
+if (!exportApi) throw new Error("Canvas export API is unavailable.");
+
+const pagePng = await exportApi.exportPng({
+  appearance: {
+    resolveThemeColor(token, fallback) {
+      return currentTheme.tokens[token] ?? fallback;
+    },
+  },
+  scope: "page",
+  pixelRatio: 2,
+});
+const selectedSvg = await exportApi.exportSvg({ scope: "selection" });
+const customSvg = await exportApi.exportSvg({ shapeIds: [shapeId] });
 ```
 
-The publish-ready output is written to:
+`exportPng()` resolves with an `image/png` Blob and `exportSvg()` resolves with
+a self-contained SVG string when export succeeds. The API deliberately exposes
+no loading state; callers own pending-state presentation around the returned
+Promise. SVG and PNG share one internal lock and reject a concurrent export.
+When `appearance.resolveThemeColor` is omitted, core color fallbacks are used.
+
+## Styles
 
-```text
-packages/canvas-kit/dist-component/
+The package root imports its base styles. Published consumers may also use the explicit stylesheet export when their bundler requires it:
+
+```ts
+import "@land/canvas-kit/style.css";
 ```

package/_vendor/canvas-core/bindings/bindingUtil.d.ts

@@ -1,16 +1,20 @@
 import type { Editor } from "../editor/editor";
 import type { SelectionOverlayFrameGeometryState } from "../editor/selection";
+import type { Vec } from "../geometry/vec";
 import type { BindingId, BindingRecord, BindingRecordBase, ShapeRecord } from "../schema/records";
 export interface BindingUtilEffect {
     shapes?: ShapeRecord[];
     bindings?: BindingRecord[];
     deleteShapeIds?: ShapeRecord["id"][];
     deleteBindingIds?: BindingId[];
+    /** Suppress these bindings while applying this effect and its derived writes. */
+    suppressBindingIds?: BindingId[];
 }
 export interface BindingShapeChangeContext {
     before: ShapeRecord;
     after: ShapeRecord;
     role: "from" | "to";
+    reason: "self" | "ancestry";
 }
 export interface BindingShapeDeleteContext {
     shape: ShapeRecord;
@@ -27,6 +31,10 @@ export interface BindingShapeGeometryDependencyContext {
     shape: ShapeRecord;
     role: "from" | "to";
 }
+export interface BindingTargetShapeContentCutoutContext {
+    fromShape: ShapeRecord;
+    toShape: ShapeRecord;
+}
 export declare abstract class BindingUtil<B extends BindingRecordBase = BindingRecordBase> {
     abstract readonly type: B["type"];
     abstract getDefaultProps(): B["props"];
@@ -36,10 +44,25 @@ export declare abstract class BindingUtil<B extends BindingRecordBase = BindingR
     onBindingCreate?(editor: Editor, binding: B): BindingUtilEffect | void;
     onBindingUpdate?(editor: Editor, before: B, after: B): BindingUtilEffect | void;
     onBindingLoad?(editor: Editor, binding: B): BindingUtilEffect | void;
+    onInvalidBindingLoad?(editor: Editor, binding: B): BindingUtilEffect | void;
     onAfterShapeChange?(editor: Editor, binding: B, context: BindingShapeChangeContext): BindingUtilEffect | void;
     onBeforeDeleteShape?(editor: Editor, binding: B, context: BindingShapeDeleteContext): BindingUtilEffect | void;
     onBeforeDeleteBinding?(editor: Editor, binding: B): BindingUtilEffect | void;
     getExportShapeIds?(editor: Editor, binding: B): ShapeRecord["id"][];
+    /**
+     * Map a hierarchy companion (for example, a bound label) to the shape that
+     * owns its group lifecycle and selection semantics.
+     */
+    getShapeHierarchyRootId?(binding: B, shapeId: ShapeRecord["id"]): ShapeRecord["id"] | null;
+    canUseShapeHierarchy?(binding: B, context: BindingEndpointContext): boolean;
     getGeometryDependentShapeIds?(editor: Editor, binding: B, context: BindingShapeGeometryDependencyContext): ShapeRecord["id"][];
+    /**
+     * Return polygons in the target shape's local space that should be removed
+     * from its rendered content. This lets a binding-owned companion such as a
+     * text label create a transparent gap without coupling the target plugin to
+     * the companion shape implementation.
+     */
+    getTargetShapeContentCutoutLocalPolygons?(editor: Editor, binding: B, context: BindingTargetShapeContentCutoutContext): readonly (readonly Vec[])[];
     getSelectionCompanionFrameGeometries?(editor: Editor, binding: B, context: BindingSelectionCompanionFrameContext): SelectionOverlayFrameGeometryState[];
 }
+export declare function resolveShapeHierarchyRootId(shapeId: ShapeRecord["id"], bindings: readonly BindingRecord[], getBindingUtil: (binding: BindingRecord) => BindingUtil): ShapeRecord["id"];

package/_vendor/canvas-core/bindings/terminalPorts.d.ts

@@ -0,0 +1,67 @@
+import type { Editor } from "../editor/editor";
+import { Vec } from "../geometry/vec";
+import type { ShapeRecord } from "../schema/records";
+export type TerminalBindingPortId = "top" | "right" | "bottom" | "left" | (string & {});
+export interface ShapeTerminalBindingPort {
+    id: TerminalBindingPortId;
+    normalizedAnchor: {
+        x: number;
+        y: number;
+    };
+    outwardNormal: {
+        x: number;
+        y: number;
+    };
+}
+export interface ResolvedShapeTerminalBindingPort {
+    id: TerminalBindingPortId;
+    normalizedAnchor: {
+        x: number;
+        y: number;
+    };
+    pagePoint: Vec;
+    pageOutwardNormal: Vec;
+}
+export declare const DEFAULT_TERMINAL_BINDING_PORTS: readonly [{
+    readonly id: "top";
+    readonly normalizedAnchor: {
+        readonly x: 0.5;
+        readonly y: 0;
+    };
+    readonly outwardNormal: {
+        readonly x: 0;
+        readonly y: -1;
+    };
+}, {
+    readonly id: "right";
+    readonly normalizedAnchor: {
+        readonly x: 1;
+        readonly y: 0.5;
+    };
+    readonly outwardNormal: {
+        readonly x: 1;
+        readonly y: 0;
+    };
+}, {
+    readonly id: "bottom";
+    readonly normalizedAnchor: {
+        readonly x: 0.5;
+        readonly y: 1;
+    };
+    readonly outwardNormal: {
+        readonly x: 0;
+        readonly y: 1;
+    };
+}, {
+    readonly id: "left";
+    readonly normalizedAnchor: {
+        readonly x: 0;
+        readonly y: 0.5;
+    };
+    readonly outwardNormal: {
+        readonly x: -1;
+        readonly y: 0;
+    };
+}];
+export declare function getResolvedShapeTerminalBindingPorts(editor: Editor, shape: ShapeRecord): ResolvedShapeTerminalBindingPort[];
+export declare function getResolvedShapeTerminalBindingPort(editor: Editor, shape: ShapeRecord, portId: TerminalBindingPortId): ResolvedShapeTerminalBindingPort | null;

package/_vendor/canvas-core/editor/bindingReactionScope.d.ts

@@ -0,0 +1,7 @@
+import type { BindingId } from "../schema/records";
+import type { Editor } from "./editor";
+declare const SYNCHRONOUS_CALLBACK_ERROR = "Binding reaction scope callbacks must be synchronous";
+type SynchronousCallbackGuard<T> = T extends PromiseLike<unknown> ? [error: typeof SYNCHRONOUS_CALLBACK_ERROR] : [];
+export declare function getSuppressedBindingReactionIds(editor: Editor): ReadonlySet<BindingId>;
+export declare function runWithSuppressedBindingReactions<T>(editor: Editor, bindingIds: Iterable<BindingId>, callback: () => T, ..._synchronousCallbackGuard: SynchronousCallbackGuard<T>): T;
+export {};

package/_vendor/canvas-core/editor/cameraPanSession.d.ts

@@ -0,0 +1,9 @@
+import type { Vec } from "../geometry/vec";
+import type { Camera } from "../schema/records";
+import type { Editor } from "./editor";
+export interface CameraPanSession {
+    originScreenPoint: Vec;
+    originCamera: Camera;
+}
+export declare function createCameraPanSession(editor: Editor, originScreenPoint: Vec): CameraPanSession;
+export declare function updateCameraPanSession(editor: Editor, session: CameraPanSession, screenPoint: Vec): void;

package/_vendor/canvas-core/editor/canvasPanInteraction.d.ts

@@ -0,0 +1,2 @@
+import type { LandInteractionHandler } from "./interactions";
+export declare function createCanvasPanInteractionHandler(): LandInteractionHandler;

package/_vendor/canvas-core/editor/commands.d.ts

@@ -4,6 +4,16 @@ import type { AssetId, AssetRecord, AssetRecordBase, BindingId, BindingRecordBas
 export interface EditorCommandOptions {
     source?: ChangeSource;
 }
+export interface CreateShapesOptions extends EditorCommandOptions {
+    /** Defer spatial containment until an interactive creation gesture completes. */
+    autoReparent?: boolean;
+    /** Internal: allow a container to receive children later in the same atomic command. */
+    deferMinimumChildRepair?: boolean;
+}
+export interface UpdateShapesOptions extends EditorCommandOptions {
+    /** Suppress these bindings while applying this update and its derived writes. */
+    suppressBindingIds?: ReadonlySet<BindingId>;
+}
 export interface CreateShapeInput {
     type: ShapeRecordBase["type"];
     x: number;
@@ -14,6 +24,7 @@ export interface CreateShapeInput {
     opacity?: number;
     isHidden?: boolean;
     rotation?: number;
+    skewX?: number;
     scaleX?: number;
     scaleY?: number;
     isLocked?: boolean;
@@ -35,6 +46,7 @@ export interface ShapeUpdate {
     x?: number;
     y?: number;
     rotation?: number;
+    skewX?: number;
     scaleX?: number;
     scaleY?: number;
     opacity?: number;
@@ -57,7 +69,7 @@ export interface StartEditingShapeInput {
         y: number;
     };
     markId?: string;
-    reuseExistingMark?: boolean;
+    reuseActiveOperation?: boolean;
     preserveInteraction?: boolean;
 }
 export interface CreateBindingInput {
@@ -106,19 +118,19 @@ export interface EditorCommands {
     updateDocumentMeta(input: UpdateDocumentMetaInput, options?: EditorCommandOptions): DocumentMetadataRecord;
     updatePageMeta(input: UpdatePageMetaInput, options?: EditorCommandOptions): PageRecord | null;
     movePage(input: MovePageInput, options?: EditorCommandOptions): void;
-    createShapes(inputs: CreateShapeInput[], options?: EditorCommandOptions): ShapeRecord[];
+    createShapes(inputs: CreateShapeInput[], options?: CreateShapesOptions): ShapeRecord[];
     /**
      * Persist already-built shape records (with their existing ids) through the
      * command pipeline. Used by paste/duplicate where ids must be assigned before
      * parent/binding remapping. Prefer `createShapes` for fresh shapes.
      */
     createShapesFromRecords(records: ShapeRecord[], options?: EditorCommandOptions): ShapeRecord[];
-    updateShapes(updates: ShapeUpdate[], options?: EditorCommandOptions): void;
+    updateShapes(updates: ShapeUpdate[], options?: UpdateShapesOptions): void;
     /**
      * Move shapes to a new parent, appending shapes that are entering that parent
      * to the end of its child order in the order provided by `ids`.
      */
-    reparentShapes(input: ReparentShapesInput, options?: EditorCommandOptions): void;
+    reparentShapes(input: ReparentShapesInput, options?: EditorCommandOptions): boolean;
     deleteShapes(ids: ShapeId[], options?: EditorCommandOptions): void;
     createAsset(input: CreateAssetInput, options?: EditorCommandOptions): AssetRecord;
     /**

package/_vendor/canvas-core/editor/createEditorWithPlugins.d.ts

@@ -0,0 +1,6 @@
+import { type EditorPlugin } from "../plugins";
+import { Editor, type EditorOptions } from "./editor";
+export interface CreateEditorWithPluginsOptions extends Omit<EditorOptions, "shapeUtils" | "shapeSvgExporters" | "bindingUtils" | "shapeCapabilities"> {
+    plugins?: readonly EditorPlugin[];
+}
+export declare function createEditorWithPlugins(options?: CreateEditorWithPluginsOptions): Editor;