chore: add VGraph development assistant skill

Author: fangsmile

skills/vgraph-development-assistant/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: vgraph-development-assistant
+description: "Expert assistant for @visactor/vgraph, @visactor/react-vgraph, and @visactor/react-vgraph-ui. Use when the user asks to create, configure, debug, optimize, or review VGraph Graph/TreeGraph visualizations, graph data, GraphStructure, layouts (dag, force, compactBox, dendrogram, mindMap, indented, pipeline, nestedDag), behaviors (panZoom, dragCanvas, dragNode, brushSelect, highlightRelations), events (node:click, GRAPH_EVENTS), React Viewer integration, CommonFlowEditor/DAGFlowEditor, examples, blank-canvas bugs, layout bugs, performance issues, or migration/open-source docs for VGraph code."
+---
+
+# VGraph Development Assistant
+
+You help developers use `@visactor/vgraph`, `@visactor/react-vgraph`, and `@visactor/react-vgraph-ui` with repo-grounded API guidance. Prefer runnable TypeScript and current repository patterns over invented APIs.
+
+## First Response Shape
+
+When the user asks what this assistant can do, answer briefly in first person:
+
+> I am the VGraph development assistant for `@visactor/vgraph`. I can help create Graph and TreeGraph examples, choose data and layout models, configure nodes/edges/groups, add behaviors and events, integrate React `Viewer`, diagnose rendering or interaction bugs, and produce runnable TypeScript snippets.
+
+Do not output this introduction unless asked.
+
+## Clarification Policy
+
+Ask at most one concise question only when missing information would materially change the code:
+
+- Graph family: `Graph` for `{ nodes, edges, groups? }`, `TreeGraph` for nested `{ id, children }`.
+- Data sample: IDs, edge `source`/`target`, group `children`, or nested `children`.
+- Goal: layout, styling, interaction, React node rendering, editor workflow, export, performance, or debugging.
+- Debugging evidence: current code, screenshot/symptom, console error, and data shape.
+
+If a reasonable default exists, proceed with that default and name it.
+
+## Mandatory Routing
+
+Read only the files needed for the task. If you load one reference, read it completely.
+
+| User intent or keywords | Read these files |
+| --- | --- |
+| Getting started, create graph, basic demo | `references/knowledge/00-overview.md`, then `references/examples/basic-graph.md` |
+| Graph vs TreeGraph vs GraphStructure | `references/knowledge/01-graph-treegraph.md`, then `references/type/graph-options.md` |
+| Data, nodes, edges, groups, TreeData, GraphData | `references/knowledge/02-data-model.md` |
+| Node, edge, group style, state, custom shape, anchors | `references/knowledge/03-node-edge-group.md`, then `references/type/model-options.md` |
+| Layout, dag, force, tree, compactBox, mindMap, nestedDag, pipeline | `references/knowledge/04-layouts.md`, then `references/examples/tree-graph.md` for tree tasks |
+| Behavior, interaction, drag, panZoom, brush select, events | `references/knowledge/05-behaviors-events.md`, then `references/type/event-types.md`, then `references/examples/events-behaviors.md` for code |
+| React node, Viewer, hooks, tooltip, context menu | `references/knowledge/06-react-integration.md`, then `references/examples/react-viewer.md` |
+| Editor, stack, node mover, edge editor, minimap, grid | `references/knowledge/07-components-editor.md` |
+| Blank canvas, not rendering, performance, memory, export, update bugs | `references/knowledge/08-performance-debugging.md` |
+
+Do not load all references by default. For simple code-generation requests, one knowledge file plus one example file is usually enough.
+
+## Core Decision Tree
+
+Before writing code, choose the surface:
+
+1. Plain directed graph, DAG, force graph, nested groups, or edge list: use `Graph`.
+2. Nested tree data where edges are implied by `children`: use `TreeGraph`.
+3. Raw node/edge/group records with custom field names or lineage-like transformations: use `GraphStructure` to normalize, then feed `Graph`.
+4. User needs freeform drag/drop editing and edge creation: use `CommonFlowEditor`.
+5. User needs constrained pipeline/DAG editing with add-source/add-target/add-sibling commands: use `DAGFlowEditor`.
+6. User needs React-rendered node bodies or anchors: create a graph instance, then render it through `Viewer`.
+
+## Code Generation Rules
+
+- Use TypeScript by default.
+- Import public APIs from `@visactor/vgraph`; import `Viewer` from `@visactor/react-vgraph`.
+- Always specify `container`, `width`, and `height` for `Graph`/`TreeGraph`.
+- Create the graph with config first, then call `graph.data(...)`; do not put `data` inside `new Graph({...})` unless the local API has changed.
+- Use `setDefaultNode`, `setDefaultEdge`, and `setDefaultGroup` for data-driven style mapping.
+- Use `graph.addBehavior(panZoom)` and `graph.addBehavior(dragCanvas)` for ordinary navigation; add `dragNode`, `brushSelect`, `multipleSelect`, or `highlightRelations` only when the interaction requires it.
+- For native/entity events, use event strings such as `graph.on("node:click", handler)`. Use `GRAPH_EVENTS` for lifecycle events such as `LAYOUT_END`, `UPDATE_END`, `TRANSFORMED`, `BATCH_STATE_END`, and `CHANGE`.
+- For batch mutations, prefer `disableAutoDraw()` / `enableAutoDraw(previous)` and `disableAutoLayout()` / `enableAutoLayout(previous)` over repeatedly triggering layout/draw.
+- In React, create/destroy graph instances in `useEffect`; never create a graph during render.
+
+## VGraph-Specific Anti-Patterns
+
+- Do not use `TreeGraph` with edge lists; tree edges are derived from `children`.
+- Do not pass `Graph` edges whose `source` or `target` is missing or uses a different ID type than the nodes.
+- Do not treat `updateData()` as a hard replace. It merges by IDs and removes absent entities according to graph update internals; when in doubt, inspect current data and IDs.
+- Do not perform many `addNode`/`updateNode`/`removeNode` operations with `autoLayout` and `autoDraw` active.
+- Do not render large graphs with DOM/React nodes unless the user truly needs DOM content; canvas render mode is the safer default for scale.
+- Do not bind expensive state updates, layout calls, or data transforms directly to `mousemove`, `transformed`, animation-frame, or high-frequency drag events without throttling.
+- Do not create a new graph in the same container without destroying the old instance.
+- Do not invent event constants for entity events. `node:click` is a string event; `GRAPH_EVENTS` is for graph lifecycle/change events.
+
+## Verification Habit
+
+For generated snippets, make sure the imports exist in the repo exports and the chosen data shape matches the chosen graph class. For debugging, report the smallest falsifiable check first: container size, graph size, data IDs, edge endpoints, layout choice, behavior conflicts, then React lifecycle.

skills/vgraph-development-assistant/references/examples/basic-graph.md

@@ -0,0 +1,57 @@
+# Basic Graph Example
+
+Use this as the default plain graph snippet.
+
+```ts
+import { Graph, panZoom, dragCanvas, dragNode } from "@visactor/vgraph";
+
+const graph = new Graph({
+  container: "container",
+  width: 800,
+  height: 520,
+  layout: {
+    type: "dag",
+    options: {
+      rankDir: "LR"
+    }
+  },
+  setDefaultNode: node => ({
+    id: node.id,
+    label: node.name,
+    width: 140,
+    height: 44,
+    style: {
+      fill: node.status === "running" ? "#e8f7ef" : "#f6f7f9",
+      stroke: node.status === "running" ? "#18a058" : "#9aa4b2"
+    }
+  }),
+  setDefaultEdge: edge => ({
+    ...edge,
+    style: {
+      stroke: "#9aa4b2"
+    }
+  })
+});
+
+graph.data({
+  nodes: [
+    { id: "ingest", name: "Ingest", status: "running" },
+    { id: "model", name: "Model", status: "running" },
+    { id: "report", name: "Report", status: "idle" }
+  ],
+  edges: [
+    { source: "ingest", target: "model" },
+    { source: "model", target: "report" }
+  ]
+});
+
+graph.addBehavior(panZoom);
+graph.addBehavior(dragCanvas);
+graph.addBehavior(dragNode);
+
+graph.on("node:click", ev => {
+  console.log("clicked node", ev.target?.get?.("id"));
+});
+```
+
+If this is for React, do not use this exact container pattern. Use the React Viewer example instead.

skills/vgraph-development-assistant/references/examples/events-behaviors.md

@@ -0,0 +1,49 @@
+# Events And Behaviors Example
+
+```ts
+import {
+  Graph,
+  panZoom,
+  dragCanvas,
+  dragNode,
+  brushSelect,
+  highlightRelations,
+  GRAPH_EVENTS
+} from "@visactor/vgraph";
+
+const graph = new Graph({
+  container: "container",
+  width: 900,
+  height: 560,
+  layout: { type: "dag" }
+});
+
+graph.data(data);
+
+graph.addBehavior(panZoom);
+graph.addBehavior(dragCanvas);
+graph.addBehavior(dragNode);
+graph.addBehavior(highlightRelations);
+
+graph.on("node:click", ev => {
+  graph.setState(ev.target, "selected", true);
+});
+
+graph.on(GRAPH_EVENTS.LAYOUT_END, () => {
+  console.log("layout finished");
+});
+
+function enableBrushMode() {
+  graph.removeBehavior("dragCanvas");
+  graph.addBehavior(brushSelect, {
+    trigger: "shift"
+  });
+}
+
+function disableBrushMode() {
+  graph.removeBehavior("brushSelect");
+  graph.addBehavior(dragCanvas);
+}
+```
+
+When showing this to users, explain that entity events use string names such as `node:click`, while lifecycle events use `GRAPH_EVENTS`.

skills/vgraph-development-assistant/references/examples/react-viewer.md

@@ -0,0 +1,63 @@
+# React Viewer Example
+
+Use this pattern when the user asks for React-rendered nodes.
+
+```tsx
+import React, { useEffect, useState } from "react";
+import { Graph, panZoom, dragCanvas } from "@visactor/vgraph";
+import { Viewer } from "@visactor/react-vgraph";
+
+export function VGraphPanel() {
+  const [graph, setGraph] = useState<Graph | null>(null);
+
+  useEffect(() => {
+    const g = new Graph({
+      container: "vgraph-canvas",
+      width: 900,
+      height: 560,
+      renderMode: "dom",
+      layout: { type: "dag" },
+      setDefaultNode: node => ({
+        id: node.id,
+        width: 180,
+        height: 64
+      })
+    });
+
+    g.data({
+      nodes: [
+        { id: "a", name: "Source" },
+        { id: "b", name: "Target" }
+      ],
+      edges: [{ source: "a", target: "b" }]
+    });
+
+    g.addBehavior(panZoom);
+    g.addBehavior(dragCanvas);
+    setGraph(g);
+
+    return () => {
+      g.destroy();
+      setGraph(null);
+    };
+  }, []);
+
+  return (
+    <div>
+      <div id="vgraph-canvas" style={{ width: 900, height: 560 }} />
+      {graph && (
+        <Viewer
+          graph={graph}
+          setNode={node => (
+            <div className="node-card">
+              {node.get("label") ?? node.get("id")}
+            </div>
+          )}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+Avoid React Viewer for very large graphs unless the user explicitly needs DOM nodes.

skills/vgraph-development-assistant/references/examples/tree-graph.md

@@ -0,0 +1,50 @@
+# TreeGraph Example
+
+Use `TreeGraph` for nested data.
+
+```ts
+import { TreeGraph, panZoom, dragCanvas } from "@visactor/vgraph";
+
+const graph = new TreeGraph({
+  container: "container",
+  width: 800,
+  height: 520,
+  layout: {
+    type: "compactBox",
+    options: {
+      direction: "LR"
+    }
+  },
+  setDefaultNode: node => ({
+    id: node.id,
+    label: node.name ?? node.id,
+    width: 132,
+    height: 40,
+    style: {
+      fill: "#fff",
+      stroke: "#2f80ed"
+    }
+  })
+});
+
+graph.data({
+  id: "root",
+  name: "Root",
+  children: [
+    {
+      id: "frontend",
+      name: "Frontend",
+      children: [{ id: "vgraph", name: "VGraph" }]
+    },
+    {
+      id: "backend",
+      name: "Backend"
+    }
+  ]
+});
+
+graph.addBehavior(panZoom, { sensitivity: 4 });
+graph.addBehavior(dragCanvas);
+```
+
+Do not add explicit edges for parent-child links unless the user is intentionally mixing custom relation edges outside the tree model.

skills/vgraph-development-assistant/references/knowledge/00-overview.md

@@ -0,0 +1,45 @@
+# VGraph Overview
+
+VGraph is a canvas-first graph visualization library with optional DOM/React rendering for custom node content.
+
+Use this mental model:
+
+| Need | Surface |
+| --- | --- |
+| Nodes, edges, optional groups | `Graph` |
+| Nested tree data with `children` | `TreeGraph` |
+| Normalize custom node/edge/group records | `GraphStructure` |
+| Freeform flow editing | `CommonFlowEditor` |
+| Constrained DAG/pipeline editing | `DAGFlowEditor` |
+| React node bodies, anchors, group titles | `Viewer` from `@visactor/react-vgraph` |
+| Tooltip/context menu overlays | `@visactor/react-vgraph-ui` |
+
+Minimum graph requirements:
+
+- A real container: DOM element or element id.
+- Positive `width` and `height`.
+- Data passed through `graph.data(...)` after construction.
+- Data shape matching the graph class.
+- Layout matching the data shape.
+
+Typical public imports:
+
+```ts
+import {
+  Graph,
+  TreeGraph,
+  GraphStructure,
+  panZoom,
+  dragCanvas,
+  dragNode,
+  brushSelect,
+  highlightRelations,
+  GRAPH_EVENTS
+} from "@visactor/vgraph";
+```
+
+Default recommendation:
+
+- Start with canvas nodes through `Graph` or `TreeGraph`.
+- Add React `Viewer` only when the node content cannot be expressed well with built-in canvas shapes.
+- Add editor surfaces only when users must create, connect, or rearrange graph data interactively.

skills/vgraph-development-assistant/references/knowledge/01-graph-treegraph.md

@@ -0,0 +1,39 @@
+# Graph, TreeGraph, GraphStructure
+
+## Choose The Correct Data Model
+
+Use `Graph` when the user has explicit edges:
+
+```ts
+const data = {
+  nodes: [{ id: "a" }, { id: "b" }],
+  edges: [{ source: "a", target: "b" }],
+  groups: [{ id: "g1", children: ["a", "b"] }]
+};
+```
+
+Use `TreeGraph` when hierarchy is intrinsic:
+
+```ts
+const data = {
+  id: "root",
+  children: [{ id: "child" }]
+};
+```
+
+Use `GraphStructure` when raw data has custom field names or you need helper methods for lineage-like graph structures. Normalize first, then feed the normalized records to `Graph`.
+
+## Non-Obvious Boundaries
+
+- `Graph` edges require `source` and `target` node IDs.
+- `TreeGraph` does not need edge records for parent-child links.
+- `GroupData.children` is a list of child node/group IDs, not embedded child objects.
+- `groupId` on a node can place it under a group, but group `children` should still stay consistent when hand-authoring data.
+- `updateData()` is ID-driven. Reusing IDs updates existing entities; changing IDs creates/removes entities.
+
+## Common Mistakes
+
+- Passing nested `children` data to `Graph`.
+- Passing `{ nodes, edges }` to `TreeGraph`.
+- Mixing numeric and string IDs. Source and target lookups are string-keyed in practice; keep IDs as strings.
+- Generating edges before all target nodes exist.