@graphvideo/backend-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type { Info, Node } from '@graphvideo/kernel';
+export type AnyNode = Node<any, any>;
+/** Creates exactly one ordinary Node and never creates or owns a Runtime. */
+export type NodeFactory<Input = void, Output extends AnyNode = AnyNode> = (input: Input) => Output;
+/** Creates a flat batch of ordinary Nodes and never creates or owns a Runtime. */
+export type GraphFactory<Input = void, Output extends AnyNode = AnyNode> = (input: Input) => readonly Output[];
+export declare function defineNodeFactory<Input, Output extends AnyNode>(factory: NodeFactory<Input, Output>): NodeFactory<Input, Output>;
+export declare function defineGraphFactory<Input, Output extends AnyNode>(factory: GraphFactory<Input, Output>): GraphFactory<Input, Output>;
+export interface BackendPluginContext<Dependencies> {
+    readonly pluginId: string;
+    readonly dependencies: Readonly<Dependencies>;
+}
+export interface BackendPlugin<Dependencies = Record<string, never>> {
+    readonly id: string;
+    createNodes(context: BackendPluginContext<Dependencies>): readonly AnyNode[];
+    /** Explicit user commands only. Internal observations and WorldNode effects
+     * must not be public roots. Backend code is trusted, not sandboxed. */
+    readonly rendererRoots?: readonly RendererRoot[];
+}
+export interface RendererRoot {
+    readonly targetNodeId: string;
+    readonly infoType: string;
+    readonly validate: (info: Info) => boolean;
+}
+export declare function assertRendererRoot<Dependencies>(plugins: readonly BackendPlugin<Dependencies>[], input: {
+    targetNodeId: string;
+    info: Info;
+}): void;
+export interface BackendPluginModule<Dependencies = Record<string, never>> {
+    readonly default?: BackendPlugin<Dependencies>;
+    readonly plugin?: BackendPlugin<Dependencies>;
+}
+export declare function defineBackendPlugin<Dependencies>(plugin: BackendPlugin<Dependencies>): BackendPlugin<Dependencies>;
+export declare function createPluginNodes<Dependencies>(plugins: readonly BackendPlugin<Dependencies>[], dependencies: Dependencies): readonly AnyNode[];
+export type { EffectAdapter, EffectContext } from '@graphvideo/kernel';
+export { Node, WorldNode } from '@graphvideo/kernel';
+export type { ChangeContext, DomainChangeContext, Info, WorldChangeContext, } from '@graphvideo/kernel';
+export type { StudioPluginManifest } from './plugin-manifest.mjs';
+export { defineStudioPluginManifest, parseStudioPluginManifest, } from './plugin-manifest.mjs';

package/dist/index.mjs

@@ -0,0 +1,99 @@
+import { Node as e, WorldNode as t } from "@graphvideo/kernel";
+//#region sdk/backend/plugin-manifest.mjs
+var n = /^[a-z0-9][a-z0-9.-]*$/, r = /^(?![\\/])(?!.*(?:^|[\\/])\.\.(?:[\\/]|$)).+$/;
+function i(e, t) {
+	if (e === void 0) return [];
+	if (!Array.isArray(e) || e.some((e) => typeof e != "string" || !n.test(e))) throw Error(`Plugin ${t} 必须是合法 ID 数组`);
+	if (new Set(e).size !== e.length) throw Error(`Plugin ${t} 存在重复 ID`);
+	return [...e];
+}
+function a(e, t) {
+	if (e !== void 0) {
+		if (typeof e != "string" || !r.test(e.replace(/\\/g, "/"))) throw Error(`Plugin ${t} 必须是包内相对路径`);
+		return e.replace(/\\/g, "/");
+	}
+}
+function o(e) {
+	let t = e;
+	if (typeof e == "string") try {
+		t = JSON.parse(e);
+	} catch {
+		throw Error("graphvideo.plugin.json 不是有效 JSON");
+	}
+	if (!t || typeof t != "object" || Array.isArray(t)) throw Error("graphvideo.plugin.json 必须是对象");
+	let r = t;
+	if (r.apiVersion !== 1) throw Error("Plugin apiVersion 必须是 1");
+	if (typeof r.id != "string" || !n.test(r.id)) throw Error("Plugin id 只能包含小写字母、数字、点和短横线");
+	if (typeof r.name != "string" || !r.name.trim()) throw Error("Plugin name 不能为空");
+	if (typeof r.version != "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(r.version)) throw Error("Plugin version 必须是 SemVer");
+	let o = r.contributes === void 0 ? {} : r.contributes;
+	if (!o || typeof o != "object" || Array.isArray(o)) throw Error("Plugin contributes 必须是对象");
+	return Object.freeze({
+		id: r.id,
+		name: r.name.trim(),
+		version: r.version,
+		apiVersion: 1,
+		contributes: Object.freeze({
+			backend: a(o.backend, "contributes.backend"),
+			elements: Object.freeze(i(o.elements, "contributes.elements")),
+			workspaces: Object.freeze(i(o.workspaces, "contributes.workspaces"))
+		})
+	});
+}
+function s(e) {
+	return o(e);
+}
+//#endregion
+//#region sdk/backend/index.ts
+function c(e) {
+	return (t) => {
+		let n = e(t);
+		if (!n.id) throw Error("NodeFactory 必须产出具有非空 id 的 Node");
+		return n;
+	};
+}
+function l(e) {
+	return (t) => {
+		let n = e(t), r = /* @__PURE__ */ new Set();
+		for (let e of n) {
+			if (!e.id) throw Error("GraphFactory 必须产出具有非空 id 的 Node");
+			if (r.has(e.id)) throw Error(`GraphFactory 产出了重复 Node ID: ${e.id}`);
+			r.add(e.id);
+		}
+		return n;
+	};
+}
+function u(e, t) {
+	let n = e.flatMap((e) => e.rendererRoots ?? []).find((e) => e.targetNodeId === t?.targetNodeId && e.infoType === t?.info?.type);
+	if (!n || !n.validate(t.info)) throw Error("Renderer root Info 未授权或参数无效");
+}
+function d(e) {
+	if (!e.id.trim()) throw Error("Backend Plugin id 不能为空");
+	if (typeof e.createNodes != "function") throw Error(`Backend Plugin ${e.id} 缺少 createNodes`);
+	return Object.freeze(e);
+}
+function f(e, t) {
+	let n = /* @__PURE__ */ new Set(), r = /* @__PURE__ */ new Map(), i = [];
+	for (let a of [...e].sort((e, t) => e.id.localeCompare(t.id))) {
+		if (n.has(a.id)) throw Error(`Backend Plugin ID 重复: ${a.id}`);
+		n.add(a.id);
+		let e = a.createNodes({
+			pluginId: a.id,
+			dependencies: t
+		}), o = new Set(e.map((e) => e.id)), s = /* @__PURE__ */ new Set();
+		for (let e of a.rendererRoots ?? []) {
+			let t = `${e.targetNodeId}\0${e.infoType}`;
+			if (!o.has(e.targetNodeId) || !e.infoType || typeof e.validate != "function" || s.has(t)) throw Error(`Plugin ${a.id} renderer root 无效: ${t}`);
+			s.add(t);
+		}
+		for (let t of e) {
+			if (!t.id) throw Error(`Backend Plugin ${a.id} 产出了空 Node ID`);
+			let e = r.get(t.id);
+			if (e) throw Error(`Node ID 冲突: ${t.id} (${e} / ${a.id})`);
+			r.set(t.id, a.id), i.push(t);
+		}
+	}
+	return i;
+}
+//#endregion
+export { e as Node, t as WorldNode, u as assertRendererRoot, f as createPluginNodes, d as defineBackendPlugin, l as defineGraphFactory, c as defineNodeFactory, s as defineStudioPluginManifest, o as parseStudioPluginManifest };

package/dist/plugin-manifest.d.mts

@@ -0,0 +1,19 @@
+export interface StudioPluginManifest {
+  readonly id: string
+  readonly name: string
+  readonly version: string
+  readonly apiVersion: 1
+  readonly contributes: {
+    readonly backend?: string
+    readonly elements: readonly string[]
+    readonly workspaces: readonly string[]
+  }
+}
+
+export function parseStudioPluginManifest(textOrValue: string | unknown): StudioPluginManifest
+export function defineStudioPluginManifest(
+  manifest: StudioPluginManifest | (Omit<StudioPluginManifest, 'contributes'> & {
+    contributes?: Partial<StudioPluginManifest['contributes']>
+  }),
+): StudioPluginManifest
+

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@graphvideo/backend-sdk",
+  "version": "1.0.0",
+  "description": "Backend plugin SDK for GraphFramework: Node factories, plugin contract, kernel re-exports",
+  "license": "Apache-2.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:vd249175-cpu/GSDK.git",
+    "directory": "sdk/backend"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@graphvideo/kernel": "^1.0.0"
+  }
+}