@yuzhouu/canvas-kit 0.1.2 → 0.1.4

package/README.md

@@ -1,102 +1,82 @@
 # @land/canvas-kit
 
-`@land/canvas-kit` 把 Land 画布打包成一个开箱即用的 React 画布套件，包含标准产品预设、插件集成和类型化 API。
+`@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`，用于直接嵌入标准画布套件
-- `createCanvasKitApi` 和 `CanvasKitApi`，用于编辑器自动化
-- `createCanvasKitProduct`，用于较底层的 `CanvasProductRoot` 产品组合
-- `@land/canvas-kit/product`，用于自定义产品 chrome
-- `@land/canvas-kit/standard`，用于标准内置插件扩展与类型化 API
-- 打包进发布产物的 Land 内部依赖
-- 作为 peer dependency 的 `react` 和 `react-dom`
-
-## 文档
-
-- [使用文档](./docs/使用文档.md) - 基于 `apps/professional` 和 `apps/zen` 示例的使用指南。
-- [API 文档](./docs/API文档.md) - `.`、`./product` 和 `./standard` 三个入口的完整 API 参考。
-
-## 安装
+## Install
 
 ```bash
 pnpm add @land/canvas-kit react react-dom
 ```
 
-## 使用
+## Basic Usage
 
 ```tsx
-import { useRef } from "react";
+import { useMemo } from "react";
 import {
-  CanvasKit,
-  type CanvasKitHandle,
+  CanvasKitRoot,
+  defineCanvasKit,
 } from "@land/canvas-kit";
 import "@land/canvas-kit/style.css";
 
 export function App() {
-  const apiRef = useRef<CanvasKitHandle>(null);
+  const product = useMemo(
+    () =>
+      defineCanvasKit({
+        onControllerReady(controller) {
+          console.log(controller.snapshot());
+        },
+      }),
+    [],
+  );
 
   return (
     <div style={{ width: "100%", height: "100vh" }}>
-      <CanvasKit
-        ref={apiRef}
-        onReady={(api) => {
-          console.log(api.snapshot());
-        }}
-      />
+      <CanvasKitRoot product={product} />
     </div>
   );
 }
 ```
 
-宿主容器需要提供明确尺寸。`CanvasKit` 会以 `width: 100%` 和 `height: 100%` 填满父容器。
-
-## 注意事项
-
-- 默认的 `canvas-kit` 产品包含画布表面、标准插件、产品运行时，以及插件自带的编辑 UI，例如文本行内格式工具条。
-- 它不会注册产品级 chrome 面板、工具栏或上下文菜单。
+The host element must provide a size. `CanvasKitRoot` fills the space provided by its parent and mounts the canvas runtime for the product.
 
-## 使用 `createCanvasKitProduct` 自定义 chrome
+## Custom Chrome
 
-`createCanvasKitProduct` 是围绕标准 Land 画布构建自定义产品壳的较底层组合入口。它负责编辑器运行时、标准插件、图片导入、剪贴板集成、持久化和 API 生命周期；你的应用只需要通过一个 `chrome(context)` 函数提供产品 UI。
+Use the `chrome` option when you want to provide your own toolbar, panels, or menus while keeping the kit runtime and built-in extensions.
 
 ```tsx
 import { useMemo } from "react";
-import { CanvasProductRoot } from "@land/canvas-product-react";
 import {
-  createCanvasKitProduct,
+  CanvasKitRoot,
+  defineCanvasKit,
+  type CanvasKitController,
   type CanvasKitChromeContext,
-} from "@land/canvas-kit/product";
-import { type CanvasKitApi } from "@land/canvas-kit";
+} from "@land/canvas-kit";
 import "@land/canvas-kit/style.css";
 
-function MyChrome({ context }: { context: CanvasKitChromeContext<CanvasKitApi> }) {
-  const { api, history, selectedShapeIds, selection, toolbarSurfaces, zoom } =
-    context;
-
+function MyChrome({
+  context,
+}: {
+  context: CanvasKitChromeContext<CanvasKitController>;
+}) {
   return (
     <>
-      <div className="my-topbar">
-        <button type="button" disabled={!history.canUndo} onClick={history.undo}>
-          撤销
-        </button>
-        <button type="button" onClick={zoom.zoomIn}>
-          放大
-        </button>
-        <button
-          type="button"
-          disabled={selection.count === 0}
-          onClick={() => api.deleteShapes([...selectedShapeIds])}
-        >
-          删除
-        </button>
-      </div>
-
-      {toolbarSurfaces.contextToolbarGroups.length > 0 ? (
-        <aside className="my-context-panel">
-          {toolbarSurfaces.contextToolbarTitle}
-        </aside>
-      ) : null}
+      <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>
     </>
   );
 }
@@ -104,41 +84,63 @@ function MyChrome({ context }: { context: CanvasKitChromeContext<CanvasKitApi> }
 export function App() {
   const product = useMemo(
     () =>
-      createCanvasKitProduct({
+      defineCanvasKit({
         chrome: (context) => <MyChrome context={context} />,
-        exposeApiOnWindow: true,
       }),
     [],
   );
 
   return (
     <div style={{ width: "100%", height: "100vh" }}>
-      <CanvasProductRoot product={product} />
+      <CanvasKitRoot product={product} />
     </div>
   );
 }
 ```
 
-如果要做 professional 风格的产品，可以围绕 `CanvasKitChromeContext` 添加自己的面板，并把文档改动保持在 `context.api` 上。chrome 不需要直接访问 `Editor`、`@land/canvas-core` 或 `@land/canvas-react/host`。
+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.
 
-## 高级入口
+The package no longer exposes a one-component direct render entry. Apps should define a product with `defineCanvasKit` and render it through `CanvasKitRoot`.
 
-包根入口会刻意保持精简。较底层的产品套件辅助方法请从显式子路径导入：
+## Local Persistence
 
-```tsx
-import { createCanvasKitProduct } from "@land/canvas-kit/product";
-import { standardCanvasExtensions } from "@land/canvas-kit/standard";
-```
+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.
+
+## Internal Assembly
+
+The public product remains opaque. Internally, `defineCanvasKit()` resolves options into explicit product fields:
+
+- `LandExtension[]` installs editor/canvas 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.
+
+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`.
+
+## Public Exports
+
+The published package intentionally exposes only:
+
+- `@land/canvas-kit`
+- `@land/canvas-kit/style.css`
+
+Package subpaths are internal implementation details.
 
-## 本仓库本地构建
+## Local Build
 
-从 workspace 根目录执行：
+Run from the workspace root:
 
 ```bash
 pnpm build:canvas-kit:bundle
 ```
 
-可发布产物会写入：
+The publish-ready output is written to:
 
 ```text
 packages/canvas-kit/dist-component/

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

@@ -0,0 +1,45 @@
+import type { Editor } from "../editor/editor";
+import type { SelectionOverlayFrameGeometryState } from "../editor/selection";
+import type { BindingId, BindingRecord, BindingRecordBase, ShapeRecord } from "../schema/records";
+export interface BindingUtilEffect {
+    shapes?: ShapeRecord[];
+    bindings?: BindingRecord[];
+    deleteShapeIds?: ShapeRecord["id"][];
+    deleteBindingIds?: BindingId[];
+}
+export interface BindingShapeChangeContext {
+    before: ShapeRecord;
+    after: ShapeRecord;
+    role: "from" | "to";
+}
+export interface BindingShapeDeleteContext {
+    shape: ShapeRecord;
+    role: "from" | "to";
+}
+export interface BindingEndpointContext {
+    fromShape: ShapeRecord;
+    toShape: ShapeRecord;
+}
+export interface BindingSelectionCompanionFrameContext {
+    selectedShape: ShapeRecord;
+}
+export interface BindingShapeGeometryDependencyContext {
+    shape: ShapeRecord;
+    role: "from" | "to";
+}
+export declare abstract class BindingUtil<B extends BindingRecordBase = BindingRecordBase> {
+    abstract readonly type: B["type"];
+    abstract getDefaultProps(): B["props"];
+    abstract validateProps(props: unknown): B["props"];
+    canBind?(editor: Editor, binding: B, context: BindingEndpointContext): boolean;
+    getExclusiveBindingKey?(binding: B): string | null;
+    onBindingCreate?(editor: Editor, binding: B): BindingUtilEffect | void;
+    onBindingUpdate?(editor: Editor, before: B, after: B): BindingUtilEffect | void;
+    onBindingLoad?(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"][];
+    getGeometryDependentShapeIds?(editor: Editor, binding: B, context: BindingShapeGeometryDependencyContext): ShapeRecord["id"][];
+    getSelectionCompanionFrameGeometries?(editor: Editor, binding: B, context: BindingSelectionCompanionFrameContext): SelectionOverlayFrameGeometryState[];
+}

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

@@ -0,0 +1,8 @@
+import type { BindingRecordBase } from "../schema/records";
+import { BindingUtil } from "./bindingUtil";
+export declare class BindingUtilRegistry {
+    private readonly registry;
+    register<B extends BindingRecordBase>(util: BindingUtil<B>): void;
+    values(): IterableIterator<BindingUtil>;
+    get<B extends BindingRecordBase>(type: B["type"]): BindingUtil<B>;
+}

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

@@ -0,0 +1,28 @@
+import { Vec } from "../geometry/vec";
+import type { Editor } from "../editor/editor";
+import type { BindingPreviewState } from "../editor/selection";
+import type { ShapeId } from "../schema/records";
+export interface ConnectionPoint {
+    x: number;
+    y: number;
+}
+export type ConnectionTerminal = "start" | "end";
+export interface TerminalBindingTargetInput {
+    targetShapeId: ShapeId;
+    normalizedAnchor: ConnectionPoint;
+}
+export interface ResolvedTerminalBinding {
+    pagePoint: Vec;
+    binding: TerminalBindingTargetInput | null;
+    preview: BindingPreviewState | null;
+}
+export interface TerminalBindingResolverInput {
+    terminal: ConnectionTerminal;
+    rawPagePoint: Vec;
+    oppositePagePoint: Vec;
+    excludeShapeId?: ShapeId;
+    ignoreTargets?: boolean;
+}
+export type TerminalBindingResolver = (editor: Editor, input: TerminalBindingResolverInput) => ResolvedTerminalBinding;
+export declare function getFreeTerminalBinding({ rawPagePoint, }: TerminalBindingResolverInput): ResolvedTerminalBinding;
+export declare function resolveTerminalBindingAtPoint(editor: Editor, input: TerminalBindingResolverInput): ResolvedTerminalBinding;

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

@@ -0,0 +1,3 @@
+export declare const CAMERA_MIN_ZOOM = 0.1;
+export declare const CAMERA_MAX_ZOOM = 8;
+export declare function clampCameraZoom(zoom: number): number;

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

@@ -0,0 +1,43 @@
+import type { ChangeSource } from "../../store/index";
+import { Vec } from "../geometry/vec";
+import type { AssetId, AssetRecord, BindingRecord, ShapeId, ShapeRecord } from "../schema/records";
+import type { Editor } from "./editor";
+export interface EditorClipboardPayload {
+    type: "land/clipboard";
+    version: 1;
+    source: {
+        app: "land";
+        documentId?: string;
+    };
+    rootShapeIds: readonly ShapeId[];
+    records: {
+        shapes: readonly ShapeRecord[];
+        bindings: readonly BindingRecord[];
+        assets: readonly AssetRecord[];
+    };
+    bounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+export interface ClipboardAssetSidecar {
+    assetId: AssetId;
+    kind: "local-image-blob";
+    storageKey: string;
+}
+export interface PasteClipboardPayloadInput {
+    payload: EditorClipboardPayload;
+    pagePoint?: Vec;
+    offset?: Vec;
+    source?: ChangeSource;
+}
+export interface DuplicateSelectionInput {
+    offset?: Vec;
+    source?: ChangeSource;
+}
+export declare function isEditorClipboardPayload(value: unknown): value is EditorClipboardPayload;
+export declare function createEditorClipboardPayloadFromSelection(editor: Editor): EditorClipboardPayload | null;
+export declare function pasteEditorClipboardPayload(editor: Editor, input: PasteClipboardPayloadInput): ShapeId[];
+export declare function duplicateEditorSelection(editor: Editor, input?: DuplicateSelectionInput): ShapeId[];

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

@@ -0,0 +1,131 @@
+import type { Editor } from "./editor";
+import type { ChangeSource } from "../../store/index";
+import type { AssetId, AssetRecord, AssetRecordBase, BindingId, BindingRecordBase, BindingRecord, Camera, PageId, PageRecord, ShapeId, ShapeParentId, ShapeRecordBase, ShapeRecord, ShapeEditingEntryMode } from "../schema/records";
+export interface EditorCommandOptions {
+    source?: ChangeSource;
+}
+export interface CreateShapeInput {
+    type: ShapeRecordBase["type"];
+    x: number;
+    y: number;
+    props?: Record<string, unknown>;
+    parentId?: ShapeParentId;
+    index?: string;
+    opacity?: number;
+    isHidden?: boolean;
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    isLocked?: boolean;
+    meta?: Record<string, unknown>;
+}
+export interface CreateAssetInput {
+    id?: AssetId;
+    type: AssetRecordBase["type"];
+    props?: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+}
+export interface UpdateAssetInput {
+    id: AssetId;
+    props?: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+}
+export interface ShapeUpdate {
+    id: ShapeId;
+    x?: number;
+    y?: number;
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    opacity?: number;
+    isHidden?: boolean;
+    isLocked?: boolean;
+    parentId?: ShapeParentId;
+    index?: string;
+    props?: Record<string, unknown>;
+}
+export interface ReparentShapesInput {
+    ids: ShapeId[];
+    parentId: ShapeParentId;
+}
+export interface StartEditingShapeInput {
+    shapeId: ShapeId;
+    entryMode?: ShapeEditingEntryMode;
+    caretPagePoint?: {
+        x: number;
+        y: number;
+    };
+    markId?: string;
+    reuseExistingMark?: boolean;
+    preserveInteraction?: boolean;
+}
+export interface CreateBindingInput {
+    id?: BindingId;
+    type: BindingRecordBase["type"];
+    fromId: ShapeId;
+    toId: ShapeId;
+    props?: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+}
+export interface UpdateBindingInput {
+    id: BindingId;
+    fromId?: ShapeId;
+    toId?: ShapeId;
+    props?: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+}
+export interface CreatePageInput {
+    name?: string;
+    index?: string;
+    meta?: Record<string, unknown>;
+}
+export interface RenamePageInput {
+    id: PageId;
+    name: string;
+}
+export interface MovePageInput {
+    id: PageId;
+    toIndex: number;
+}
+export interface SetCameraInput {
+    pageId?: PageId;
+    camera: Partial<Camera>;
+}
+export interface EditorCommands {
+    createPage(input?: CreatePageInput, options?: EditorCommandOptions): PageRecord;
+    deletePage(id: PageId, options?: EditorCommandOptions): boolean;
+    renamePage(input: RenamePageInput, options?: EditorCommandOptions): void;
+    movePage(input: MovePageInput, options?: EditorCommandOptions): void;
+    createShapes(inputs: CreateShapeInput[], options?: EditorCommandOptions): 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;
+    /**
+     * 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;
+    deleteShapes(ids: ShapeId[], options?: EditorCommandOptions): void;
+    createAsset(input: CreateAssetInput, options?: EditorCommandOptions): AssetRecord;
+    /**
+     * Persist already-built asset records (with their existing ids) through the
+     * command pipeline. Used by paste/duplicate. Prefer `createAsset` otherwise.
+     */
+    createAssetsFromRecords(records: AssetRecord[], options?: EditorCommandOptions): AssetRecord[];
+    updateAsset(input: UpdateAssetInput, options?: EditorCommandOptions): AssetRecord | null;
+    deleteAsset(id: AssetId, options?: EditorCommandOptions): boolean;
+    createBinding(input: CreateBindingInput, options?: EditorCommandOptions): BindingRecord;
+    updateBinding(input: UpdateBindingInput, options?: EditorCommandOptions): BindingRecord | null;
+    deleteBinding(id: BindingId, options?: EditorCommandOptions): boolean;
+    setCurrentPageId(id: PageId, options?: EditorCommandOptions): void;
+    setCamera(input: SetCameraInput, options?: EditorCommandOptions): void;
+    setSelectedShapeIds(ids: ShapeId[], options?: EditorCommandOptions): void;
+    setActiveTool(toolId: string, options?: EditorCommandOptions): void;
+    setToolLocked(locked: boolean, options?: EditorCommandOptions): void;
+}
+export declare function createEditorCommands(editor: Editor): EditorCommands;
+export declare function reparentShapeToContainingParent(editor: Editor, shapeId: ShapeId, options?: EditorCommandOptions): void;

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

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

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

@@ -0,0 +1,5 @@
+import { Vec } from "../geometry/vec";
+export declare function getEdgeScrollDelta(screenPoint: Vec, viewportSize: {
+    w: number;
+    h: number;
+}, elapsed: number): Vec;