mirror of
https://github.com/basketikun/infinite-canvas.git
synced 2026-08-02 23:11:14 +08:00
feat(plugin-sdk): add TypeScript SDK for Infinite Canvas plugins with automatic JSX and build support
This commit is contained in:
HouYunFei
@@ -0,0 +1,18 @@
|
||||
import type { CanvasPlugin, CanvasPluginFactory, PluginRuntime } from "./types";
|
||||
|
||||
// 身份帮助函数:为插件对象(或工厂)补全类型,给作者完整补全与校验。
|
||||
// 采用 automatic JSX 后,插件通常不再需要 runtime,直接写对象形式即可:
|
||||
//
|
||||
// export default definePlugin({ id, name, version, nodes: [...] })
|
||||
//
|
||||
// 仍支持工厂形式(需要 runtime.version/emit/on 时):
|
||||
//
|
||||
// export default definePlugin((runtime) => ({ ... }))
|
||||
|
||||
export function definePlugin(plugin: CanvasPlugin): CanvasPlugin;
|
||||
export function definePlugin(factory: CanvasPluginFactory): CanvasPluginFactory;
|
||||
export function definePlugin(input: CanvasPlugin | CanvasPluginFactory): CanvasPlugin | CanvasPluginFactory {
|
||||
return input;
|
||||
}
|
||||
|
||||
export type { PluginRuntime };
|
||||
@@ -0,0 +1,8 @@
|
||||
// @infinite-canvas/plugin-sdk 公开入口。
|
||||
//
|
||||
// 插件作者用 TS/TSX 编写,只关注节点 UI 与逻辑;类型、JSX、运行时桥接、构建
|
||||
// 全部由本 SDK 提供,产物仍是宿主 loader 现有契约的 ESM(React external,宿主单例)。
|
||||
|
||||
export * from "./types";
|
||||
export { definePlugin } from "./define-plugin";
|
||||
export { getReact, getRuntime, useState, useEffect, useLayoutEffect, useMemo, useCallback, useRef, useReducer, useContext, useId } from "./runtime";
|
||||
@@ -0,0 +1,16 @@
|
||||
// automatic JSX 的 dev 变体(编译器在 dev 模式会引用 jsxDEV)。转发到同一套 createElement。
|
||||
|
||||
import type * as React from "react";
|
||||
|
||||
import { getReact } from "./runtime";
|
||||
import { Fragment } from "./jsx-runtime";
|
||||
|
||||
export { Fragment };
|
||||
export type { JSX } from "./jsx-runtime";
|
||||
|
||||
export function jsxDEV(type: unknown, props: Record<string, unknown> | null, key?: unknown): React.ReactElement {
|
||||
const react = getReact();
|
||||
const resolvedType = type === Fragment ? react.Fragment : type;
|
||||
const config = key === undefined ? props : { ...(props ?? {}), key };
|
||||
return react.createElement(resolvedType as never, config as never);
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
// automatic JSX 运行时:esbuild/tsc 的 `jsxImportSource` 指向本包时,
|
||||
// TSX 会被编译成对本模块 jsx()/jsxs() 的调用。这里统一转发到宿主 React.createElement,
|
||||
// 让插件写纯 TSX、无需手动 `const { React } = runtime`,同时 react 全程 external。
|
||||
|
||||
import type * as React from "react";
|
||||
|
||||
import { getReact } from "./runtime";
|
||||
|
||||
// Fragment 哨兵:渲染时才解析为宿主 React.Fragment,避免模块顶层触碰运行时。
|
||||
export const Fragment = Symbol.for("infinite-canvas.jsx.fragment") as unknown as React.ExoticComponent<{ children?: React.ReactNode }>;
|
||||
|
||||
function createElement(type: unknown, props: Record<string, unknown> | null, key?: unknown): React.ReactElement {
|
||||
const react = getReact();
|
||||
const resolvedType = type === Fragment ? react.Fragment : type;
|
||||
// automatic 运行时已把 children 放进 props;key 单独传入以避免展开 key 警告。
|
||||
const config = key === undefined ? props : { ...(props ?? {}), key };
|
||||
return react.createElement(resolvedType as never, config as never);
|
||||
}
|
||||
|
||||
export function jsx(type: unknown, props: Record<string, unknown> | null, key?: unknown): React.ReactElement {
|
||||
return createElement(type, props, key);
|
||||
}
|
||||
|
||||
// jsxs 用于静态多子节点;转发逻辑与 jsx 一致(children 已在 props 内)。
|
||||
export const jsxs = jsx;
|
||||
|
||||
// 让 `jsxImportSource` 指向本包的编译器能从这里取到 JSX 内建标签类型(复用 @types/react)。
|
||||
export namespace JSX {
|
||||
export type Element = React.JSX.Element;
|
||||
export type ElementType = React.JSX.ElementType;
|
||||
export type ElementClass = React.JSX.ElementClass;
|
||||
export type ElementAttributesProperty = React.JSX.ElementAttributesProperty;
|
||||
export type ElementChildrenAttribute = React.JSX.ElementChildrenAttribute;
|
||||
export type LibraryManagedAttributes<C, P> = React.JSX.LibraryManagedAttributes<C, P>;
|
||||
export type IntrinsicAttributes = React.JSX.IntrinsicAttributes;
|
||||
export type IntrinsicClassAttributes<T> = React.JSX.IntrinsicClassAttributes<T>;
|
||||
export type IntrinsicElements = React.JSX.IntrinsicElements;
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
// 运行时桥接:所有对宿主 React 的访问都惰性读取全局运行时,
|
||||
// 保证插件与画布共用同一份 React(不打包第二份),且不在模块顶层触碰运行时
|
||||
// (宿主 loader 会先 import 插件模块、再设置运行时)。
|
||||
|
||||
import type * as React from "react";
|
||||
|
||||
import type { PluginRuntime } from "./types";
|
||||
|
||||
type RuntimeGlobal = { InfiniteCanvasRuntime?: PluginRuntime };
|
||||
|
||||
/** 取宿主注入的插件运行时(含 React、事件总线、injectCSS 等)。 */
|
||||
export function getRuntime(): PluginRuntime {
|
||||
const runtime = (globalThis as unknown as RuntimeGlobal).InfiniteCanvasRuntime;
|
||||
if (!runtime) {
|
||||
throw new Error("[plugin-sdk] Infinite Canvas 运行时未就绪:请在画布宿主中加载本插件");
|
||||
}
|
||||
return runtime;
|
||||
}
|
||||
|
||||
/** 取宿主的 React 实例。仅在渲染/hook 调用时(运行时已就绪)使用。 */
|
||||
export function getReact(): typeof React {
|
||||
return getRuntime().React as unknown as typeof React;
|
||||
}
|
||||
|
||||
// --- 类型完整的 hooks 转发:签名取自 @types/react,运行时转发到宿主 React ---
|
||||
// 这样插件作者可以直接 `import { useState } from "@infinite-canvas/plugin-sdk"`,
|
||||
// 无需再从 runtime 里解构 React。
|
||||
|
||||
export const useState: typeof React.useState = ((...args: unknown[]) => (getReact().useState as (...a: unknown[]) => unknown)(...args)) as typeof React.useState;
|
||||
export const useEffect: typeof React.useEffect = ((...args: unknown[]) => (getReact().useEffect as (...a: unknown[]) => unknown)(...args)) as typeof React.useEffect;
|
||||
export const useLayoutEffect: typeof React.useLayoutEffect = ((...args: unknown[]) => (getReact().useLayoutEffect as (...a: unknown[]) => unknown)(...args)) as typeof React.useLayoutEffect;
|
||||
export const useMemo: typeof React.useMemo = ((...args: unknown[]) => (getReact().useMemo as (...a: unknown[]) => unknown)(...args)) as typeof React.useMemo;
|
||||
export const useCallback: typeof React.useCallback = ((...args: unknown[]) => (getReact().useCallback as (...a: unknown[]) => unknown)(...args)) as typeof React.useCallback;
|
||||
export const useRef: typeof React.useRef = ((...args: unknown[]) => (getReact().useRef as (...a: unknown[]) => unknown)(...args)) as typeof React.useRef;
|
||||
export const useReducer: typeof React.useReducer = ((...args: unknown[]) => (getReact().useReducer as (...a: unknown[]) => unknown)(...args)) as typeof React.useReducer;
|
||||
export const useContext: typeof React.useContext = ((...args: unknown[]) => (getReact().useContext as (...a: unknown[]) => unknown)(...args)) as typeof React.useContext;
|
||||
export const useId: typeof React.useId = ((...args: unknown[]) => (getReact().useId as (...a: unknown[]) => unknown)(...args)) as typeof React.useId;
|
||||
@@ -0,0 +1,238 @@
|
||||
// Infinite Canvas 插件公共契约类型。
|
||||
//
|
||||
// 这是插件作者面向的「公开接口」子集,自包含、不依赖宿主 `@/` 内部模块,
|
||||
// 因此可以被独立构建的插件包直接 import,获得完整的 TS 提示。
|
||||
//
|
||||
// 真源:宿主 `web/src/types/canvas-plugin.ts` 及其引用的类型。本文件是它的公开镜像,
|
||||
// 若宿主契约变更,请同步更新此处(两者结构保持一致即可,无需逐字节相同)。
|
||||
|
||||
import type { ComponentType, ReactNode } from "react";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 画布基础几何与节点数据
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type Position = { x: number; y: number };
|
||||
|
||||
export type ViewportTransform = { x: number; y: number; k: number };
|
||||
|
||||
// 内置节点类型;插件节点建议用 "<pluginId>:<name>"。放开为字符串以便扩展。
|
||||
export type CanvasBuiltinNodeType = "image" | "text" | "config" | "video" | "audio" | "group";
|
||||
export type CanvasNodeTypeId = CanvasBuiltinNodeType | (string & {});
|
||||
|
||||
export type CanvasNodeStatus = "idle" | "success" | "loading" | "error";
|
||||
export type CanvasGenerationMode = "text" | "image" | "video" | "audio";
|
||||
export type CanvasImageGenerationType = "generation" | "edit";
|
||||
|
||||
// 节点 metadata 是扁平可选字段袋;插件自定义字段可直接写入(内容惯例放 content)。
|
||||
export type CanvasNodeMetadata = {
|
||||
content?: string;
|
||||
composerContent?: string;
|
||||
prompt?: string;
|
||||
status?: CanvasNodeStatus;
|
||||
errorDetails?: string;
|
||||
fontSize?: number;
|
||||
generationMode?: CanvasGenerationMode;
|
||||
generationType?: CanvasImageGenerationType;
|
||||
model?: string;
|
||||
size?: string;
|
||||
quality?: string;
|
||||
count?: number;
|
||||
seconds?: string;
|
||||
vquality?: string;
|
||||
generateAudio?: string;
|
||||
watermark?: string;
|
||||
audioVoice?: string;
|
||||
audioFormat?: string;
|
||||
audioSpeed?: string;
|
||||
audioInstructions?: string;
|
||||
references?: string[];
|
||||
naturalWidth?: number;
|
||||
naturalHeight?: number;
|
||||
freeResize?: boolean;
|
||||
isBatchRoot?: boolean;
|
||||
batchRootId?: string;
|
||||
batchChildIds?: string[];
|
||||
batchUsesReferenceImages?: boolean;
|
||||
primaryImageId?: string;
|
||||
imageBatchExpanded?: boolean;
|
||||
storageKey?: string;
|
||||
mimeType?: string;
|
||||
bytes?: number;
|
||||
durationMs?: number;
|
||||
groupId?: string;
|
||||
// 插件可写入任意自定义字段
|
||||
[key: string]: unknown;
|
||||
};
|
||||
|
||||
export type CanvasNodeData = {
|
||||
id: string;
|
||||
type: CanvasNodeTypeId;
|
||||
title: string;
|
||||
position: Position;
|
||||
width: number;
|
||||
height: number;
|
||||
metadata?: CanvasNodeMetadata;
|
||||
};
|
||||
|
||||
export type CanvasConnection = {
|
||||
id: string;
|
||||
fromNodeId: string;
|
||||
toNodeId: string;
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 主题 token(用来让插件 UI 跟随画布明暗主题)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type CanvasTheme = {
|
||||
canvas: {
|
||||
background: string;
|
||||
dot: string;
|
||||
line: string;
|
||||
selectionStroke: string;
|
||||
selectionFill: string;
|
||||
};
|
||||
node: {
|
||||
label: string;
|
||||
fill: string;
|
||||
panel: string;
|
||||
stroke: string;
|
||||
activeStroke: string;
|
||||
placeholder: string;
|
||||
text: string;
|
||||
muted: string;
|
||||
faint: string;
|
||||
};
|
||||
toolbar: {
|
||||
panel: string;
|
||||
border: string;
|
||||
item: string;
|
||||
itemHover: string;
|
||||
activeBg: string;
|
||||
activeText: string;
|
||||
};
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 画布指令集(ctx.applyOps):与 AI Agent 同级的画布操作能力
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type CanvasAgentOp =
|
||||
| { type: "add_node"; id?: string; nodeType?: CanvasNodeTypeId; title?: string; position?: { x: number; y: number }; x?: number; y?: number; width?: number; height?: number; metadata?: CanvasNodeMetadata }
|
||||
| { type: "update_node"; id: string; patch?: Partial<CanvasNodeData>; metadata?: CanvasNodeMetadata }
|
||||
| { type: "delete_node"; id?: string; ids?: string[]; nodeType?: CanvasNodeTypeId }
|
||||
| { type: "delete_connections"; id?: string; ids?: string[]; all?: boolean }
|
||||
| { type: "connect_nodes"; id?: string; fromNodeId: string; toNodeId: string }
|
||||
| { type: "set_viewport"; viewport: ViewportTransform }
|
||||
| { type: "select_nodes"; ids: string[] }
|
||||
| { type: "run_generation"; nodeId: string; mode?: CanvasGenerationMode; prompt?: string };
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 资源:插件节点作为上游输入被消费时输出什么(接入生成/引用体系)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type CanvasResourceKind = "image" | "video" | "audio" | "text";
|
||||
export type CanvasNodeResource = { kind: CanvasResourceKind; text?: string; url?: string };
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 节点上下文:每个节点渲染时注入,是插件与画布交互的核心接口
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type PluginStorage = {
|
||||
get: <T = unknown>(key: string) => Promise<T | null>;
|
||||
set: (key: string, value: unknown) => Promise<void>;
|
||||
remove: (key: string) => Promise<void>;
|
||||
};
|
||||
|
||||
export type CanvasNodeContext = {
|
||||
// 自身数据
|
||||
node: CanvasNodeData;
|
||||
theme: CanvasTheme;
|
||||
scale: number;
|
||||
updateMetadata: (patch: CanvasNodeMetadata) => void;
|
||||
updateNode: (patch: Partial<Pick<CanvasNodeData, "title" | "width" | "height">>) => void;
|
||||
// 图访问
|
||||
getNode: (id: string) => CanvasNodeData | null;
|
||||
getNodes: () => CanvasNodeData[];
|
||||
getConnections: () => CanvasConnection[];
|
||||
getUpstream: () => CanvasNodeData[];
|
||||
getDownstream: () => CanvasNodeData[];
|
||||
// 画布操作(复用 Agent 指令集)
|
||||
applyOps: (ops: CanvasAgentOp[]) => void;
|
||||
// 节点间/插件间通信
|
||||
emit: (event: string, payload?: unknown) => void;
|
||||
on: (event: string, handler: (payload: unknown) => void) => () => void;
|
||||
// 插件私有持久化,按插件 id 命名空间隔离
|
||||
storage: PluginStorage;
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 节点定义:内置节点与插件节点统一走这套结构
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type CanvasNodeToolbarItem = {
|
||||
id: string;
|
||||
title: string;
|
||||
label: string;
|
||||
icon: ReactNode;
|
||||
onClick: () => void;
|
||||
active?: boolean;
|
||||
danger?: boolean;
|
||||
};
|
||||
|
||||
export type CanvasNodeContentProps = { ctx: CanvasNodeContext };
|
||||
export type CanvasNodePanelProps = { ctx: CanvasNodeContext; onClose: () => void };
|
||||
|
||||
export type CanvasNodeDefinition = {
|
||||
type: string; // 建议 "<pluginId>:<name>",全局唯一
|
||||
title: string;
|
||||
icon: ReactNode; // emoji 字符串或任意 ReactNode
|
||||
description?: string;
|
||||
defaultSize: { width: number; height: number };
|
||||
defaultMetadata?: CanvasNodeMetadata;
|
||||
minimapColor?: string;
|
||||
showInCreateMenu?: boolean; // 默认 true
|
||||
hasSourceHandle?: boolean; // 右侧输出连接点,默认 true
|
||||
keepAspectRatio?: (node: CanvasNodeData) => boolean;
|
||||
resource?: (node: CanvasNodeData) => CanvasNodeResource | null;
|
||||
// 渲染
|
||||
Content?: ComponentType<CanvasNodeContentProps>;
|
||||
Panel?: ComponentType<CanvasNodePanelProps>; // 节点下方面板
|
||||
toolbar?: (ctx: CanvasNodeContext) => CanvasNodeToolbarItem[];
|
||||
onDoubleClick?: (ctx: CanvasNodeContext) => boolean; // 返回 true 表示已处理
|
||||
};
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 插件运行时与插件包
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
// 插件启动时(setup)可访问的应用能力
|
||||
export type CanvasPluginApp = {
|
||||
version: string;
|
||||
emit: (event: string, payload?: unknown) => void;
|
||||
on: (event: string, handler: (payload: unknown) => void) => () => void;
|
||||
// 注入插件样式,返回移除函数;传 key 时同 key 覆盖旧样式
|
||||
injectCSS: (css: string, key?: string) => () => void;
|
||||
};
|
||||
|
||||
// 宿主注入的运行时(工厂形式插件的入参),内含宿主 React 实例避免双 React
|
||||
export type PluginRuntime = CanvasPluginApp & {
|
||||
React: typeof import("react");
|
||||
jsx: typeof import("react").createElement;
|
||||
Fragment: typeof import("react").Fragment;
|
||||
};
|
||||
|
||||
// 插件包(默认导出对象,或返回它的工厂函数)
|
||||
export type CanvasPlugin = {
|
||||
id: string; // 唯一,kebab-case
|
||||
name: string;
|
||||
version: string;
|
||||
description?: string;
|
||||
minAppVersion?: string;
|
||||
css?: string; // 插件样式,启用时自动注入、卸载/禁用时自动清理
|
||||
nodes: CanvasNodeDefinition[];
|
||||
setup?: (app: CanvasPluginApp) => void | (() => void);
|
||||
};
|
||||
|
||||
export type CanvasPluginFactory = (runtime: PluginRuntime) => CanvasPlugin;
|
||||
Reference in New Issue
Block a user