docs: improve vgraph skill guidance

skills/vgraph-development-assistant/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+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, VGraph examples, API docs, demos, blank-canvas bugs, layout bugs, performance issues, or VGraph-specific migration guidance."
 ---
 
 # VGraph Development Assistant
@@ -28,20 +28,20 @@ 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, simple snippet | `references/knowledge/00-overview.md`, then `references/examples/basic-graph.md` |
-| Standalone demo page, runnable HTML demo, previewable structure diagram, knowledge map showcase, code tab | `references/examples/demo-html-page.md`, plus the relevant graph/layout/behavior references below |
-| 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` |
+Read only the files needed for the task. If you load one reference, read it completely. Do NOT load unrelated reference files just because they are nearby; keep answers grounded in the chosen route.
+
+| User intent or keywords | Read | Do NOT load by default |
+| --- | --- | --- |
+| Getting started, create graph, basic demo, simple snippet | `references/knowledge/00-overview.md`, then `references/examples/basic-graph.md` | React/editor/performance references |
+| Standalone demo page, runnable HTML demo, previewable structure diagram, knowledge map showcase, code tab | `references/examples/demo-html-page.md`, plus the relevant graph/layout/behavior references below | All examples not used by the selected graph family |
+| Graph vs TreeGraph vs GraphStructure | `references/knowledge/01-graph-treegraph.md`, then `references/type/graph-options.md` | React/editor examples |
+| Data, nodes, edges, groups, TreeData, GraphData | `references/knowledge/02-data-model.md` | Layout examples unless layout is part of the question |
+| Node, edge, group style, state, custom shape, anchors | `references/knowledge/03-node-edge-group.md`, then `references/type/model-options.md` | Demo page reference |
+| Layout, dag, force, tree, compactBox, mindMap, nestedDag, pipeline | `references/knowledge/04-layouts.md`, then `references/examples/tree-graph.md` for tree tasks | React/editor references |
+| 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 | Layout/debug references unless needed |
+| React node, Viewer, hooks, tooltip, context menu | `references/knowledge/06-react-integration.md`, then `references/examples/react-viewer.md` | Standalone HTML demo reference |
+| Editor, stack, node mover, edge editor, minimap, grid | `references/knowledge/07-components-editor.md` | React Viewer example unless DOM nodes are requested |
+| Blank canvas, not rendering, performance, memory, export, update bugs | `references/knowledge/08-performance-debugging.md` | Demo/examples unless reproducing |
 
 Do not load all references by default. For simple code-generation requests, one knowledge file plus one example file is usually enough.
 
@@ -76,7 +76,9 @@ For simple examples, API usage, configuration help, or debugging answers, prefer
 
 A standard demo page should include a `Demo` tab for the live VGraph canvas and a `Code` tab for the core runnable TypeScript/JavaScript. The Code tab should be a fixed-size panel with internal scrolling (`overflow: auto`) so long examples do not expand the whole page or hide the live demo. Include a copy-code action when practical.
 
-For large trees, knowledge maps, organization charts, or any graph that can overwhelm the viewport, add readability controls by default. Use `panZoom` and `dragCanvas`, start from a conservative overview when it helps users understand the top-level structure, and provide controls such as "expand all", "collapse details", search, filter, group focus, or fit-to-view. Implement tree collapse by keeping source data immutable, deriving visible `children` from a collapsed-ID set, and refreshing the graph with `graph.data(visibleTree)`. For non-tree Graph/DAG demos, do not force tree-collapse patterns onto edge-list data; prefer viewport, filtering, grouping, highlighting, or progressive disclosure controls.
+For large trees, knowledge maps, organization charts, or any graph that can overwhelm the viewport, add readability controls by default. Use `panZoom` and `dragCanvas`, start from a conservative overview when it helps users understand the top-level structure, and provide controls such as "expand all", "collapse details", search, filter, group focus, or fit-to-view. For `TreeGraph` hierarchy expand/collapse, use native `collapse`, `expand`, or `toggleCollapse` first so the interaction stays a visibility/layout operation instead of a full data replacement. For non-tree Graph/DAG demos, do not force tree-collapse patterns onto edge-list data; prefer viewport, filtering, grouping, highlighting, or progressive disclosure controls.
+
+For knowledge-system or structure-map demos, preserve semantic shape before visual polish. Decide whether the requested content is a strict hierarchy, a DAG, or a general network. For school-stage or curriculum maps, keep the main levels explicit (for example stage -> subject -> topic -> skill) and avoid turning cross-links into primary parent-child edges. If the user asks for expand/collapse on a hierarchy, use `TreeGraph` native `collapse`, `expand`, or `toggleCollapse` first; do not rebuild a visible tree and call `graph.data(...)` on each click unless the user specifically needs data filtering or virtualization.
 
 After creating a standalone HTML demo, verify that it renders without console errors. If the environment supports browser preview, start or reuse a local static/dev server and provide the accessible URL; if browser preview is unavailable, say what validation was skipped and why.
 
@@ -93,4 +95,4 @@ After creating a standalone HTML demo, verify that it renders without console er
 
 ## 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.
+For generated snippets, make sure the imports exist in `packages/vgraph/src/index.ts` or the relevant package export, and verify non-obvious config fields against source typings or implementation before suggesting them. 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/demo-html-page.md

@@ -15,6 +15,10 @@ A polished standalone demo should contain:
 - For large tree or hierarchy demos, an initial collapsed view and controls such as `Expand all` and `Collapse details`.
 - For large non-tree Graph/DAG demos, readability controls such as fit-to-view, search/highlight, filtering, grouping, or progressive disclosure. Do not force tree-collapse patterns onto edge-list data.
 
+Keep generic HTML/CSS minimal. Spend tokens on VGraph data shape, layout,
+behaviors, interaction controls, and runtime verification rather than decorative
+page chrome.
+
 ## Minimal HTML shell
 
 For a real standalone HTML file, use an executable module script. Prefer a local
@@ -130,7 +134,13 @@ for (const tab of tabs) {
 
 ## Tree collapse pattern
 
-Use `TreeGraph` for nested `children` data. Keep the original full tree immutable, derive a visible tree from collapsed IDs, and call `graph.data(visibleTree)` after each toggle.
+Use `TreeGraph` for nested `children` data. Prefer the native collapse API:
+`graph.collapse(node)`, `graph.expand(node)`, or `graph.toggleCollapse(node)`.
+Do not implement ordinary expand/collapse by deriving a new visible tree and
+calling `graph.data(...)` on every click; that turns a visibility interaction
+into a data update, re-layout, redraw, and possible animation replay. Use the
+visible-tree pattern only when the user needs true data filtering,
+virtualization, or server-side paging.
 
 ```ts
 import { TreeGraph, panZoom, dragCanvas } from "@visactor/vgraph";
@@ -143,7 +153,6 @@ interface TreeNode {
   children?: TreeNode[];
 }
 
-const collapsedIds = new Set<string>();
 const nodeMap = new Map<string, TreeNode>();
 
 function walkTree(node: TreeNode, visitor: (node: TreeNode) => void) {
@@ -153,33 +162,14 @@ function walkTree(node: TreeNode, visitor: (node: TreeNode) => void) {
 
 walkTree(sourceTree, node => {
   nodeMap.set(node.id, node);
-  if (node.children?.length && node.level === "module") {
-    collapsedIds.add(node.id);
-  }
+  node.collapsed = Boolean(node.children?.length && node.level === "module");
 });
 
-function cloneVisibleNode(node: TreeNode): TreeNode {
-  const children = node.children ?? [];
-  const collapsed = children.length > 0 && collapsedIds.has(node.id);
-  const next: TreeNode = {
-    ...node,
-    collapsed,
-    name: children.length ? `${collapsed ? "▸" : "▾"} ${node.name}` : node.name
-  };
-
-  if (children.length && !collapsed) {
-    next.children = children.map(cloneVisibleNode);
-  } else {
-    delete next.children;
-  }
-
-  return next;
-}
-
 const graph = new TreeGraph({
   container: "container",
   width,
   height,
+  animate: false,
   layout: {
     type: "compactBox",
     options: { direction: "LR" }
@@ -197,26 +187,23 @@ const graph = new TreeGraph({
   })
 });
 
-function renderTree() {
-  graph.data(cloneVisibleNode(sourceTree));
-}
-
 graph.addBehavior(panZoom, { sensitivity: 4 });
 graph.addBehavior(dragCanvas);
 
 graph.on("node:click", ev => {
   const id = ev?.target?.get?.("id");
   if (!id || !nodeMap.get(id)?.children?.length) return;
 
-  if (collapsedIds.has(id)) collapsedIds.delete(id);
-  else collapsedIds.add(id);
-
-  renderTree();
+  graph.toggleCollapse(ev.target);
 });
 
-renderTree();
+graph.data(sourceTree);
 ```
 
+Set `animate: false` for static knowledge-map demos when repeated expand/collapse
+should feel instant and not replay layout transitions. Keep animation on only
+when the transition itself is part of the requested experience.
+
 ## Verification
 
 After creating the HTML file, open it through a local static/dev server when possible and check the browser console. The expected result is a visible graph in the Demo tab, a scrollable Code tab, working copy-code behavior if included, and no console errors. If browser preview is unavailable, state that runtime validation was skipped instead of implying it passed.

skills/vgraph-development-assistant/references/knowledge/04-layouts.md

@@ -33,10 +33,12 @@ Batch pattern:
 const autoDraw = graph.disableAutoDraw();
 const autoLayout = graph.disableAutoLayout();
 
-graph.updateData(nextData);
-
-graph.enableAutoLayout(autoLayout);
-graph.enableAutoDraw(autoDraw);
+try {
+  graph.updateData(nextData);
+} finally {
+  graph.enableAutoLayout(autoLayout);
+  graph.enableAutoDraw(autoDraw);
+}
 ```
 
 If layout still does not appear to run:

skills/vgraph-development-assistant/references/knowledge/05-behaviors-events.md

@@ -25,9 +25,18 @@ Some behaviors accept options:
 
 ```ts
 graph.addBehavior(panZoom, { sensitivity: 5 });
-graph.addBehavior(dragCanvas, { eventType: "right" });
+graph.addBehavior(dragCanvas, {
+  shouldTrigger(event) {
+    return !event.target || event.target.type === "canvas";
+  }
+});
 ```
 
+`dragCanvas` does not expose an `eventType: "right"` option. Its built-in
+trigger rejects right-button drags (`nativeEvent.buttons === 2`). Use
+`shouldTrigger`, `canvasOnly`, `xOnly`, `yOnly`, `limit`, or behavior mode
+switching instead of inventing event-type configuration.
+
 Remove by behavior config or type string:
 
 ```ts