{"owner":"bytedance","repo":"flowgram.ai","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Repository Overview\n\nFlowGram is a composable, visual workflow development framework built as a Rush-managed monorepo. It provides tools for building AI workflow platforms, including a flow canvas, node configuration forms, variable scope chains, and pre-built materials (LLM, Condition, Code Editor, etc.).\n\n## Build System & Package Management\n\nThis monorepo uses **Rush 5.150.0** with **pnpm 10.6.5** as the package manager. Node.js version must be >=18.20.3 <19.0.0 || >=20.14.0 <23.0.0.\n\n### Essential Commands\n\n```bash\n# Install dependencies (required first step)\nrush install\n\n# Build all packages\nrush build\n\n# Build specific package and its dependencies\nrush build --to @flowgram.ai/core\n\n# Lint all packages\nrush lint\n\n# Fix lint issues\nrush lint:fix\n\n# TypeScript type checking\nrush ts-check\n\n# Run unit tests\nrush test\n\n# Run tests with coverage\nrush test:cov\n\n# Build packages in watch mode (for development)\nrush build:watch\n\n# E2E tests with Playwright\nrush e2e:test\n\n# Update E2E screenshots\nrush e2e:update-screenshot\n```\n\n### Development Commands for Demos\n\n```bash\n# Run docs site with hot reload\nrush dev:docs\n\n# Run specific demo apps with hot reload\nrush dev:demo-free-layout\nrush dev:demo-fixed-layout\nrush dev:demo-fixed-layout-simple\nrush dev:demo-free-layout-simple\nrush dev:demo-nextjs\nrush dev:demo-nextjs-antd\n```\n\nThese commands use `concurrently` to run `rush build:watch` for dependencies alongside the demo's dev server.\n\n### Single Package Development\n\nTo work on a single package in isolation:\n```bash\ncd packages/canvas-engine/core\nrushx build        # Runs the build script for this package only\nrushx test         # Runs tests for this package only\nrushx ts-check     # Type checks this package only\n```\n\n## Monorepo Structure\n\n### Core Organization\n\n- **`packages/`** - Production libraries organized by functional area:\n  - `canvas-engine/` - Canvas rendering and layout systems (core, document, renderer, fixed-layout-core, free-layout-core)\n  - `node-engine/` - Node data and form management (node, form, form-core)\n  - `variable-engine/` - Variable scoping and type inference (variable-core, variable-layout, json-schema)\n  - `runtime/` - Workflow execution engines (interface, js-core, nodejs)\n  - `plugins/` - Extensibility modules (23+ plugins for features like history, drag, snap, minimap, etc.)\n  - `client/` - High-level React components (editor, fixed-layout-editor, free-layout-editor, playground-react)\n  - `materials/` - Pre-built node materials (form-materials, form-antd-materials, fixed-semi-materials, coze-editor, type-editor)\n  - `common/` - Shared utilities (utils, reactive, command, history, history-storage, i18n)\n\n- **`apps/`** - Demos and documentation:\n  - `docs/` - Main documentation site\n  - `demo-*/` - Example applications (free-layout, fixed-layout, nextjs, vite, playground, etc.)\n  - `create-app/`, `cli/` - CLI tools for scaffolding\n\n- **`e2e/`** - End-to-end test suites (fixed-layout, free-layout)\n- **`config/`** - Shared configuration (eslint-config, ts-config)\n- **`common/`** - Rush tooling and scripts\n\n### Architectural Layers\n\nFlowGram is architected in distinct layers:\n\n1. **Canvas Engine Layer** (`@flowgram.ai/core`, `@flowgram.ai/document`, `@flowgram.ai/renderer`)\n   - Core abstractions for canvas rendering, document model, and viewport management\n   - Supports two layout modes: free-layout (drag-anywhere) and fixed-layout (structured positioning)\n   - Plugin-based architecture using dependency injection (inversify)\n\n2. **Node Engine Layer** (`@flowgram.ai/node`, `@flowgram.ai/form`, `@flowgram.ai/form-core`)\n   - Manages node data structures and lifecycle\n   - Form engine with validation, side effects, linkage, and error capture\n   - Uses `FormModelV2` (exported as `FormModel` from `@flowgram.ai/editor`)\n\n3. **Variable Engine Layer** (`@flowgram.ai/variable-core`, `@flowgram.ai/json-schema`)\n   - Provides variable scoping, structure inspection, and type inference\n   - Manages data flow constraints across workflow nodes\n   - Scope chain mechanism for variable resolution\n\n4. **Runtime Layer** (`@flowgram.ai/runtime-js`, `@flowgram.ai/runtime-nodejs`, `@flowgram.ai/runtime-interface`)\n   - Executes workflows in JavaScript/Node.js environments\n   - Interface package defines runtime contracts\n   - Separate implementations for browser and server\n\n5. **Client/Editor Layer** (`@flowgram.ai/editor`, `@flowgram.ai/fixed-layout-editor`, `@flowgram.ai/free-layout-editor`)\n   - High-level React components that integrate all subsystems\n   - `@flowgram.ai/editor` is the main barrel export for fixed-layout workflows\n   - Re-exports from core, form, variable, and plugin packages\n\n6. **Plugin Ecosystem**\n   - 20+ plugins providing features like drag-and-drop, history/undo, snap-to-grid, minimap, auto-layout, etc.\n   - Plugins are registered via dependency injection containers\n   - Naming convention: `free-*-plugin` for free-layout, `fixed-*-plugin` for fixed-layout, or generic plugins\n\n## Key Design Patterns\n\n### Dependency Injection\nThe codebase heavily uses **inversify** for dependency injection. Services are decorated with `@injectable()` and injected via `@inject()`. Container modules organize related services.\n\n### Reactive State Management\nUses a custom reactive system (`@flowgram.ai/reactive`) with React hooks:\n- `ReactiveState` and `ReactiveBaseState` for observable state\n- `useReactiveState`, `useReadonlyReactiveState`, `useObserve` hooks\n- `Tracker` for dependency tracking\n\n### Command Pattern\n`@flowgram.ai/command` provides a command/command registry system for undo/redo operations. Re-exported by `@flowgram.ai/core`.\n\n### Plugin Architecture\nPlugins extend functionality via:\n- `Plugin` interface from `@flowgram.ai/core`\n- Registration through container modules\n- Lifecycle hooks (`onInit`, `onDestroy`, etc.)\n\n## Testing\n\n- **Unit tests**: Use Vitest, located in `__tests__/` folders or `*.test.ts` files\n- **E2E tests**: Use Playwright, located in `e2e/*/tests/` directories\n- Run all tests: `rush test`\n- Run E2E tests for specific package: `rush e2e:test --to @flowgram.ai/e2e-free-layout`\n- Update Playwright snapshots: `rush e2e:update-screenshot`\n\n## Code Quality\n\n### Linting & Type Checking\n- ESLint configuration in `config/eslint-config` enforces 2-space indentation, semicolons, and import order\n- TypeScript config in `config/ts-config`\n- Always run `rush lint:fix` before committing\n- Run `rush ts-check` to validate TypeScript across all packages\n\n### Naming Conventions\n- **React components/classes**: PascalCase\n- **Variables/functions**: camelCase\n- **Constants**: SCREAMING_SNAKE_CASE (only for exported config)\n- **File names**: kebab-case (e.g., `flow-node-form.tsx`)\n\n### Pre-commit Hooks\n- `rush lint-staged` - Runs linting on staged files\n- `rush commitlint` - Validates commit message format (conventional commits)\n\n### Dependency Checks\n- `rush check-circular-dependency` - Detects circular dependencies\n- `rush dep-check` - Validates dependency consistency\n\n## Commit & Pull Request Standards\n\nFollow **conventional commits** format: `type(scope): subject`\n\nExamples from recent history:\n- `fix(auto-layout): rankdir top to bottom`\n- `feat(landing): hover logo node glowing`\n- `docs(variable): optimize variable docs by codex`\n\nKeep commit subjects imperative, ≤72 characters. Reference GitHub issues in PR descriptions.\n\n## Working with Packages\n\n### Adding a New Package\n1. Create folder under appropriate category (`packages/<category>/<package-name>`)\n2. Add entry to `rush.json` \"projects\" array with:\n   - `packageName`: `@flowgram.ai/<package-name>`\n   - `projectFolder`: relative path\n   - `versionPolicyName`: typically \"publishPolicy\" for libraries, \"appPolicy\" for apps\n   - `tags`: for categorization\n3. Run `rush update` to link the package\n\n### Publishing Workflow\nPackages with `versionPolicyName: \"publishPolicy\"` are publishable to npm. Apps use `\"appPolicy\"`.\n\n### Inter-package Dependencies\nUse `workspace:^x.x.x` protocol in package.json for internal dependencies. Rush will link them locally during development.\n\n## Common Issues\n\n### Build Failures\n- Ensure `rush install` was run after pulling changes\n- Check Node.js version matches `nodeSupportedVersionRange` in rush.json\n- Clear incremental build cache: delete `common/temp` and rebuild\n\n### Type Errors in Editor Packages\nThe main editor packages (`@flowgram.ai/editor`, `@flowgram.ai/fixed-layout-editor`, `@flowgram.ai/free-layout-editor`) re-export many types. Look for type definitions in their upstream dependencies (@flowgram.ai/form, @flowgram.ai/core, @flowgram.ai/node).\n\n### Plugin Registration\nPlugins must be registered in a dependency injection container. Check demo apps for examples of container module setup.\n\n### Rush Command Not Found\nEnsure Rush is installed globally: `npm install -g @microsoft/rush`\nOr use the install-run script: `node common/scripts/install-run-rush.js <command>`\n\n## Additional Resources\n\n- Documentation: https://flowgram.ai\n- Issues: https://github.com/bytedance/flowgram.ai/issues\n- Contributing: See CONTRIBUTING.md\n","AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\nFlowGram is a Rush-managed monorepo. Production-ready libraries live under `packages/*` (canvas engine, node engine, runtime, plugins). Demo UIs and docs sit inside `apps/*` (for example `apps/demo-free-layout`, `apps/docs`). Shared tooling, config, and scripts live under `common/` and `config/`. End-to-end Playwright suites are isolated in `e2e/<scenario>` so they can be installed and run independently. New code should land in the closest existing package; create additional Rush projects only when a module needs its own version and publish cycle.\n\n## Build, Test, and Development Commands\nUse Node.js 18 LTS with pnpm 10.6.5 (Rush enforces versions). Install dependencies via `rush install`. Run `rush build` to compile every registered project. Use `rush dev:docs` or `rush dev:demo-free-layout` for hot-reload docs and demos. `rush lint`, `rush lint:fix`, and `rush ts-check` keep lint/TS diagnostics consistent. `rush test` aggregates unit tests; `rush e2e:test` runs Playwright suites, while `rush e2e:update-screenshot` refreshes snapshots.\n\n## Coding Style & Naming Conventions\nWe write TypeScript with React, sharing configs from `config/eslint-config`. ESLint enforces 2-space indentation, semicolons, and import order; run `rush lint:fix` before committing. Use `PascalCase` for React components and classes, `camelCase` for variables/functions, and `SCREAMING_SNAKE_CASE` only for constants exported from config files. File names follow kebab-case (e.g., `flow-node-form.tsx`). Keep public API surfaces documented via barrel files such as `packages/canvas-engine/core/src/index.ts`.\n\n## Testing Guidelines\nUnit tests use Vitest and live beside source in `__tests__` folders or `*.test.ts` files; prefer descriptive names like `node-service.test.ts`. Ensure new logic is covered by `rush test`, and include data fixtures where possible. Playwright specs under `e2e/*/tests` cover critical workflows—coordinate UI changes with updated snapshots and run `rush e2e:test --to <package>` to scope failures.\n\n## Commit & Pull Request Guidelines\nFollow conventional commits (`type(scope): subject`) as seen in history (`fix(auto-layout): ...`). Keep subjects imperative and ≤72 characters, with optional bodies for context. PRs must describe the change, link GitHub issues, and attach before/after screenshots for UI updates. Confirm CI status, note any follow-ups, and request reviewers from the owning package tags (see `rush.json`).\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Repository Overview\n\nFlowGram is a composable, visual workflow development framework built as a Rush-managed monorepo. It provides tools for building AI workflow platforms, including a flow canvas, node configuration forms, variable scope chains, and pre-built materials (LLM, Condition, Code Editor, etc.).\n\n## Build System & Package Management\n\nThis monorepo uses **Rush 5.150.0** with **pnpm 10.6.5** as the package manager. Node.js version must be >=18.20.3 <19.0.0 || >=20.14.0 <23.0.0.\n\n### Essential Commands\n\n```bash\n# Install dependencies (required first step)\nrush install\n\n# Build all packages\nrush build\n\n# Build specific package and its dependencies\nrush build --to @flowgram.ai/core\n\n# Lint all packages\nrush lint\n\n# Fix lint issues\nrush lint:fix\n\n# TypeScript type checking\nrush ts-check\n\n# Run unit tests\nrush test\n\n# Run tests with coverage\nrush test:cov\n\n# Build packages in watch mode (for development)\nrush build:watch\n\n# E2E tests with Playwright\nrush e2e:test\n\n# Update E2E screenshots\nrush e2e:update-screenshot\n```\n\n### Development Commands for Demos\n\n```bash\n# Run docs site with hot reload\nrush dev:docs\n\n# Run specific demo apps with hot reload\nrush dev:demo-free-layout\nrush dev:demo-fixed-layout\nrush dev:demo-fixed-layout-simple\nrush dev:demo-free-layout-simple\nrush dev:demo-nextjs\nrush dev:demo-nextjs-antd\n```\n\nThese commands use `concurrently` to run `rush build:watch` for dependencies alongside the demo's dev server.\n\n### Single Package Development\n\nTo work on a single package in isolation:\n```bash\ncd packages/canvas-engine/core\nrushx build        # Runs the build script for this package only\nrushx test         # Runs tests for this package only\nrushx ts-check     # Type checks this package only\n```\n\n## Monorepo Structure\n\n### Core Organization\n\n- **`packages/`** - Production libraries organized by functional area:\n  - `canvas-engine/` - Canvas rendering and layout systems (core, document, renderer, fixed-layout-core, free-layout-core)\n  - `node-engine/` - Node data and form management (node, form, form-core)\n  - `variable-engine/` - Variable scoping and type inference (variable-core, variable-layout, json-schema)\n  - `runtime/` - Workflow execution engines (interface, js-core, nodejs)\n  - `plugins/` - Extensibility modules (23+ plugins for features like history, drag, snap, minimap, etc.)\n  - `client/` - High-level React components (editor, fixed-layout-editor, free-layout-editor, playground-react)\n  - `materials/` - Pre-built node materials (form-materials, form-antd-materials, fixed-semi-materials, coze-editor, type-editor)\n  - `common/` - Shared utilities (utils, reactive, command, history, history-storage, i18n)\n\n- **`apps/`** - Demos and documentation:\n  - `docs/` - Main documentation site\n  - `demo-*/` - Example applications (free-layout, fixed-layout, nextjs, vite, playground, etc.)\n  - `create-app/`, `cli/` - CLI tools for scaffolding\n\n- **`e2e/`** - End-to-end test suites (fixed-layout, free-layout)\n- **`config/`** - Shared configuration (eslint-config, ts-config)\n- **`common/`** - Rush tooling and scripts\n\n### Architectural Layers\n\nFlowGram is architected in distinct layers:\n\n1. **Canvas Engine Layer** (`@flowgram.ai/core`, `@flowgram.ai/document`, `@flowgram.ai/renderer`)\n   - Core abstractions for canvas rendering, document model, and viewport management\n   - Supports two layout modes: free-layout (drag-anywhere) and fixed-layout (structured positioning)\n   - Plugin-based architecture using dependency injection (inversify)\n\n2. **Node Engine Layer** (`@flowgram.ai/node`, `@flowgram.ai/form`, `@flowgram.ai/form-core`)\n   - Manages node data structures and lifecycle\n   - Form engine with validation, side effects, linkage, and error capture\n   - Uses `FormModelV2` (exported as `FormModel` from `@flowgram.ai/editor`)\n\n3. **Variable Engine Layer** (`@flowgram.ai/variable-core`, `@flowgram.ai/json-schema`)\n   - Provides variable scoping, structure inspection, and type inference\n   - Manages data flow constraints across workflow nodes\n   - Scope chain mechanism for variable resolution\n\n4. **Runtime Layer** (`@flowgram.ai/runtime-js`, `@flowgram.ai/runtime-nodejs`, `@flowgram.ai/runtime-interface`)\n   - Executes workflows in JavaScript/Node.js environments\n   - Interface package defines runtime contracts\n   - Separate implementations for browser and server\n\n5. **Client/Editor Layer** (`@flowgram.ai/editor`, `@flowgram.ai/fixed-layout-editor`, `@flowgram.ai/free-layout-editor`)\n   - High-level React components that integrate all subsystems\n   - `@flowgram.ai/editor` is the main barrel export for fixed-layout workflows\n   - Re-exports from core, form, variable, and plugin packages\n\n6. **Plugin Ecosystem**\n   - 20+ plugins providing features like drag-and-drop, history/undo, snap-to-grid, minimap, auto-layout, etc.\n   - Plugins are registered via dependency injection containers\n   - Naming convention: `free-*-plugin` for free-layout, `fixed-*-plugin` for fixed-layout, or generic plugins\n\n## Key Design Patterns\n\n### Dependency Injection\nThe codebase heavily uses **inversify** for dependency injection. Services are decorated with `@injectable()` and injected via `@inject()`. Container modules organize related services.\n\n### Reactive State Management\nUses a custom reactive system (`@flowgram.ai/reactive`) with React hooks:\n- `ReactiveState` and `ReactiveBaseState` for observable state\n- `useReactiveState`, `useReadonlyReactiveState`, `useObserve` hooks\n- `Tracker` for dependency tracking\n\n### Command Pattern\n`@flowgram.ai/command` provides a command/command registry system for undo/redo operations. Re-exported by `@flowgram.ai/core`.\n\n### Plugin Architecture\nPlugins extend functionality via:\n- `Plugin` interface from `@flowgram.ai/core`\n- Registration through container modules\n- Lifecycle hooks (`onInit`, `onDestroy`, etc.)\n\n## Testing\n\n- **Unit tests**: Use Vitest, located in `__tests__/` folders or `*.test.ts` files\n- **E2E tests**: Use Playwright, located in `e2e/*/tests/` directories\n- Run all tests: `rush test`\n- Run E2E tests for specific package: `rush e2e:test --to @flowgram.ai/e2e-free-layout`\n- Update Playwright snapshots: `rush e2e:update-screenshot`\n\n## Code Quality\n\n### Linting & Type Checking\n- ESLint configuration in `config/eslint-config` enforces 2-space indentation, semicolons, and import order\n- TypeScript config in `config/ts-config`\n- Always run `rush lint:fix` before committing\n- Run `rush ts-check` to validate TypeScript across all packages\n\n### Naming Conventions\n- **React components/classes**: PascalCase\n- **Variables/functions**: camelCase\n- **Constants**: SCREAMING_SNAKE_CASE (only for exported config)\n- **File names**: kebab-case (e.g., `flow-node-form.tsx`)\n\n### Pre-commit Hooks\n- `rush lint-staged` - Runs linting on staged files\n- `rush commitlint` - Validates commit message format (conventional commits)\n\n### Dependency Checks\n- `rush check-circular-dependency` - Detects circular dependencies\n- `rush dep-check` - Validates dependency consistency\n\n## Commit & Pull Request Standards\n\nFollow **conventional commits** format: `type(scope): subject`\n\nExamples from recent history:\n- `fix(auto-layout): rankdir top to bottom`\n- `feat(landing): hover logo node glowing`\n- `docs(variable): optimize variable docs by codex`\n\nKeep commit subjects imperative, ≤72 characters. Reference GitHub issues in PR descriptions.\n\n## Working with Packages\n\n### Adding a New Package\n1. Create folder under appropriate category (`packages/<category>/<package-name>`)\n2. Add entry to `rush.json` \"projects\" array with:\n   - `packageName`: `@flowgram.ai/<package-name>`\n   - `projectFolder`: relative path\n   - `versionPolicyName`: typically \"publishPolicy\" for libraries, \"appPolicy\" for apps\n   - `tags`: for categorization\n3. Run `rush update` to link the package\n\n### Publishing Workflow\nPackages with `versionPolicyName: \"publishPolicy\"` are publishable to npm. Apps use `\"appPolicy\"`.\n\n### Inter-package Dependencies\nUse `workspace:^x.x.x` protocol in package.json for internal dependencies. Rush will link them locally during development.\n\n## Common Issues\n\n### Build Failures\n- Ensure `rush install` was run after pulling changes\n- Check Node.js version matches `nodeSupportedVersionRange` in rush.json\n- Clear incremental build cache: delete `common/temp` and rebuild\n\n### Type Errors in Editor Packages\nThe main editor packages (`@flowgram.ai/editor`, `@flowgram.ai/fixed-layout-editor`, `@flowgram.ai/free-layout-editor`) re-export many types. Look for type definitions in their upstream dependencies (@flowgram.ai/form, @flowgram.ai/core, @flowgram.ai/node).\n\n### Plugin Registration\nPlugins must be registered in a dependency injection container. Check demo apps for examples of container module setup.\n\n### Rush Command Not Found\nEnsure Rush is installed globally: `npm install -g @microsoft/rush`\nOr use the install-run script: `node common/scripts/install-run-rush.js <command>`\n\n## Additional Resources\n\n- Documentation: https://flowgram.ai\n- Issues: https://github.com/bytedance/flowgram.ai/issues\n- Contributing: See CONTRIBUTING.md\n","AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\nFlowGram is a Rush-managed monorepo. Production-ready libraries live under `packages/*` (canvas engine, node engine, runtime, plugins). Demo UIs and docs sit inside `apps/*` (for example `apps/demo-free-layout`, `apps/docs`). Shared tooling, config, and scripts live under `common/` and `config/`. End-to-end Playwright suites are isolated in `e2e/<scenario>` so they can be installed and run independently. New code should land in the closest existing package; create additional Rush projects only when a module needs its own version and publish cycle.\n\n## Build, Test, and Development Commands\nUse Node.js 18 LTS with pnpm 10.6.5 (Rush enforces versions). Install dependencies via `rush install`. Run `rush build` to compile every registered project. Use `rush dev:docs` or `rush dev:demo-free-layout` for hot-reload docs and demos. `rush lint`, `rush lint:fix`, and `rush ts-check` keep lint/TS diagnostics consistent. `rush test` aggregates unit tests; `rush e2e:test` runs Playwright suites, while `rush e2e:update-screenshot` refreshes snapshots.\n\n## Coding Style & Naming Conventions\nWe write TypeScript with React, sharing configs from `config/eslint-config`. ESLint enforces 2-space indentation, semicolons, and import order; run `rush lint:fix` before committing. Use `PascalCase` for React components and classes, `camelCase` for variables/functions, and `SCREAMING_SNAKE_CASE` only for constants exported from config files. File names follow kebab-case (e.g., `flow-node-form.tsx`). Keep public API surfaces documented via barrel files such as `packages/canvas-engine/core/src/index.ts`.\n\n## Testing Guidelines\nUnit tests use Vitest and live beside source in `__tests__` folders or `*.test.ts` files; prefer descriptive names like `node-service.test.ts`. Ensure new logic is covered by `rush test`, and include data fixtures where possible. Playwright specs under `e2e/*/tests` cover critical workflows—coordinate UI changes with updated snapshots and run `rush e2e:test --to <package>` to scope failures.\n\n## Commit & Pull Request Guidelines\nFollow conventional commits (`type(scope): subject`) as seen in history (`fix(auto-layout): ...`). Keep subjects imperative and ≤72 characters, with optional bodies for context. PRs must describe the change, link GitHub issues, and attach before/after screenshots for UI updates. Confirm CI status, note any follow-ups, and request reviewers from the owning package tags (see `rush.json`).\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Repository Overview\n\nFlowGram is a composable, visual workflow development framework built as a Rush-managed monorepo. It provides tools for building AI workflow platforms, including a flow canvas, node configuration forms, variable scope chains, and pre-built materials (LLM, Condition, Code Editor, etc.).\n\n## Build System & Package Management\n\nThis monorepo uses **Rush 5.150.0** with **pnpm 10.6.5** as the package manager. Node.js version must be >=18.20.3 <19.0.0 || >=20.14.0 <23.0.0.\n\n### Essential Commands\n\n```bash\n# Install dependencies (required first step)\nrush install\n\n# Build all packages\nrush build\n\n# Build specific package and its dependencies\nrush build --to @flowgram.ai/core\n\n# Lint all packages\nrush lint\n\n# Fix lint issues\nrush lint:fix\n\n# TypeScript type checking\nrush ts-check\n\n# Run unit tests\nrush test\n\n# Run tests with coverage\nrush test:cov\n\n# Build packages in watch mode (for development)\nrush build:watch\n\n# E2E tests with Playwright\nrush e2e:test\n\n# Update E2E screenshots\nrush e2e:update-screenshot\n```\n\n### Development Commands for Demos\n\n```bash\n# Run docs site with hot reload\nrush dev:docs\n\n# Run specific demo apps with hot reload\nrush dev:demo-free-layout\nrush dev:demo-fixed-layout\nrush dev:demo-fixed-layout-simple\nrush dev:demo-free-layout-simple\nrush dev:demo-nextjs\nrush dev:demo-nextjs-antd\n```\n\nThese commands use `concurrently` to run `rush build:watch` for dependencies alongside the demo's dev server.\n\n### Single Package Development\n\nTo work on a single package in isolation:\n```bash\ncd packages/canvas-engine/core\nrushx build        # Runs the build script for this package only\nrushx test         # Runs tests for this package only\nrushx ts-check     # Type checks this package only\n```\n\n## Monorepo Structure\n\n### Core Organization\n\n- **`packages/`** - Production libraries organized by functional area:\n  - `canvas-engine/` - Canvas rendering and layout systems (core, document, renderer, fixed-layout-core, free-layout-core)\n  - `node-engine/` - Node data and form management (node, form, form-core)\n  - `variable-engine/` - Variable scoping and type inference (variable-core, variable-layout, json-schema)\n  - `runtime/` - Workflow execution engines (interface, js-core, nodejs)\n  - `plugins/` - Extensibility modules (23+ plugins for features like history, drag, snap, minimap, etc.)\n  - `client/` - High-level React components (editor, fixed-layout-editor, free-layout-editor, playground-react)\n  - `materials/` - Pre-built node materials (form-materials, form-antd-materials, fixed-semi-materials, coze-editor, type-editor)\n  - `common/` - Shared utilities (utils, reactive, command, history, history-storage, i18n)\n\n- **`apps/`** - Demos and documentation:\n  - `docs/` - Main documentation site\n  - `demo-*/` - Example applications (free-layout, fixed-layout, nextjs, vite, playground, etc.)\n  - `create-app/`, `cli/` - CLI tools for scaffolding\n\n- **`e2e/`** - End-to-end test suites (fixed-layout, free-layout)\n- **`config/`** - Shared configuration (eslint-config, ts-config)\n- **`common/`** - Rush tooling and scripts\n\n### Architectural Layers\n\nFlowGram is architected in distinct layers:\n\n1. **Canvas Engine Layer** (`@flowgram.ai/core`, `@flowgram.ai/document`, `@flowgram.ai/renderer`)\n   - Core abstractions for canvas rendering, document model, and viewport management\n   - Supports two layout modes: free-layout (drag-anywhere) and fixed-layout (structured positioning)\n   - Plugin-based architecture using dependency injection (inversify)\n\n2. **Node Engine Layer** (`@flowgram.ai/node`, `@flowgram.ai/form`, `@flowgram.ai/form-core`)\n   - Manages node data structures and lifecycle\n   - Form engine with validation, side effects, linkage, and error capture\n   - Uses `FormModelV2` (exported as `FormModel` from `@flowgram.ai/editor`)\n\n3. **Variable Engine Layer** (`@flowgram.ai/variable-core`, `@flowgram.ai/json-schema`)\n   - Provides variable scoping, structure inspection, and type inference\n   - Manages data flow constraints across workflow nodes\n   - Scope chain mechanism for variable resolution\n\n4. **Runtime Layer** (`@flowgram.ai/runtime-js`, `@flowgram.ai/runtime-nodejs`, `@flowgram.ai/runtime-interface`)\n   - Executes workflows in JavaScript/Node.js environments\n   - Interface package defines runtime contracts\n   - Separate implementations for browser and server\n\n5. **Client/Editor Layer** (`@flowgram.ai/editor`, `@flowgram.ai/fixed-layout-editor`, `@flowgram.ai/free-layout-editor`)\n   - High-level React components that integrate all subsystems\n   - `@flowgram.ai/editor` is the main barrel export for fixed-layout workflows\n   - Re-exports from core, form, variable, and plugin packages\n\n6. **Plugin Ecosystem**\n   - 20+ plugins providing features like drag-and-drop, history/undo, snap-to-grid, minimap, auto-layout, etc.\n   - Plugins are registered via dependency injection containers\n   - Naming convention: `free-*-plugin` for free-layout, `fixed-*-plugin` for fixed-layout, or generic plugins\n\n## Key Design Patterns\n\n### Dependency Injection\nThe codebase heavily uses **inversify** for dependency injection. Services are decorated with `@injectable()` and injected via `@inject()`. Container modules organize related services.\n\n### Reactive State Management\nUses a custom reactive system (`@flowgram.ai/reactive`) with React hooks:\n- `ReactiveState` and `ReactiveBaseState` for observable state\n- `useReactiveState`, `useReadonlyReactiveState`, `useObserve` hooks\n- `Tracker` for dependency tracking\n\n### Command Pattern\n`@flowgram.ai/command` provides a command/command registry system for undo/redo operations. Re-exported by `@flowgram.ai/core`.\n\n### Plugin Architecture\nPlugins extend functionality via:\n- `Plugin` interface from `@flowgram.ai/core`\n- Registration through container modules\n- Lifecycle hooks (`onInit`, `onDestroy`, etc.)\n\n## Testing\n\n- **Unit tests**: Use Vitest, located in `__tests__/` folders or `*.test.ts` files\n- **E2E tests**: Use Playwright, located in `e2e/*/tests/` directories\n- Run all tests: `rush test`\n- Run E2E tests for specific package: `rush e2e:test --to @flowgram.ai/e2e-free-layout`\n- Update Playwright snapshots: `rush e2e:update-screenshot`\n\n## Code Quality\n\n### Linting & Type Checking\n- ESLint configuration in `config/eslint-config` enforces 2-space indentation, semicolons, and import order\n- TypeScript config in `config/ts-config`\n- Always run `rush lint:fix` before committing\n- Run `rush ts-check` to validate TypeScript across all packages\n\n### Naming Conventions\n- **React components/classes**: PascalCase\n- **Variables/functions**: camelCase\n- **Constants**: SCREAMING_SNAKE_CASE (only for exported config)\n- **File names**: kebab-case (e.g., `flow-node-form.tsx`)\n\n### Pre-commit Hooks\n- `rush lint-staged` - Runs linting on staged files\n- `rush commitlint` - Validates commit message format (conventional commits)\n\n### Dependency Checks\n- `rush check-circular-dependency` - Detects circular dependencies\n- `rush dep-check` - Validates dependency consistency\n\n## Commit & Pull Request Standards\n\nFollow **conventional commits** format: `type(scope): subject`\n\nExamples from recent history:\n- `fix(auto-layout): rankdir top to bottom`\n- `feat(landing): hover logo node glowing`\n- `docs(variable): optimize variable docs by codex`\n\nKeep commit subjects imperative, ≤72 characters. Reference GitHub issues in PR descriptions.\n\n## Working with Packages\n\n### Adding a New Package\n1. Create folder under appropriate category (`packages/<category>/<package-name>`)\n2. Add entry to `rush.json` \"projects\" array with:\n   - `packageName`: `@flowgram.ai/<package-name>`\n   - `projectFolder`: relative path\n   - `versionPolicyName`: typically \"publishPolicy\" for libraries, \"appPolicy\" for apps\n   - `tags`: for categorization\n3. Run `rush update` to link the package\n\n### Publishing Workflow\nPackages with `versionPolicyName: \"publishPolicy\"` are publishable to npm. Apps use `\"appPolicy\"`.\n\n### Inter-package Dependencies\nUse `workspace:^x.x.x` protocol in package.json for internal dependencies. Rush will link them locally during development.\n\n## Common Issues\n\n### Build Failures\n- Ensure `rush install` was run after pulling changes\n- Check Node.js version matches `nodeSupportedVersionRange` in rush.json\n- Clear incremental build cache: delete `common/temp` and rebuild\n\n### Type Errors in Editor Packages\nThe main editor packages (`@flowgram.ai/editor`, `@flowgram.ai/fixed-layout-editor`, `@flowgram.ai/free-layout-editor`) re-export many types. Look for type definitions in their upstream dependencies (@flowgram.ai/form, @flowgram.ai/core, @flowgram.ai/node).\n\n### Plugin Registration\nPlugins must be registered in a dependency injection container. Check demo apps for examples of container module setup.\n\n### Rush Command Not Found\nEnsure Rush is installed globally: `npm install -g @microsoft/rush`\nOr use the install-run script: `node common/scripts/install-run-rush.js <command>`\n\n## Additional Resources\n\n- Documentation: https://flowgram.ai\n- Issues: https://github.com/bytedance/flowgram.ai/issues\n- Contributing: See CONTRIBUTING.md\n","category":"root","tokens":2306},{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Repository Guidelines\n\n## Project Structure & Module Organization\nFlowGram is a Rush-managed monorepo. Production-ready libraries live under `packages/*` (canvas engine, node engine, runtime, plugins). Demo UIs and docs sit inside `apps/*` (for example `apps/demo-free-layout`, `apps/docs`). Shared tooling, config, and scripts live under `common/` and `config/`. End-to-end Playwright suites are isolated in `e2e/<scenario>` so they can be installed and run independently. New code should land in the closest existing package; create additional Rush projects only when a module needs its own version and publish cycle.\n\n## Build, Test, and Development Commands\nUse Node.js 18 LTS with pnpm 10.6.5 (Rush enforces versions). Install dependencies via `rush install`. Run `rush build` to compile every registered project. Use `rush dev:docs` or `rush dev:demo-free-layout` for hot-reload docs and demos. `rush lint`, `rush lint:fix`, and `rush ts-check` keep lint/TS diagnostics consistent. `rush test` aggregates unit tests; `rush e2e:test` runs Playwright suites, while `rush e2e:update-screenshot` refreshes snapshots.\n\n## Coding Style & Naming Conventions\nWe write TypeScript with React, sharing configs from `config/eslint-config`. ESLint enforces 2-space indentation, semicolons, and import order; run `rush lint:fix` before committing. Use `PascalCase` for React components and classes, `camelCase` for variables/functions, and `SCREAMING_SNAKE_CASE` only for constants exported from config files. File names follow kebab-case (e.g., `flow-node-form.tsx`). Keep public API surfaces documented via barrel files such as `packages/canvas-engine/core/src/index.ts`.\n\n## Testing Guidelines\nUnit tests use Vitest and live beside source in `__tests__` folders or `*.test.ts` files; prefer descriptive names like `node-service.test.ts`. Ensure new logic is covered by `rush test`, and include data fixtures where possible. Playwright specs under `e2e/*/tests` cover critical workflows—coordinate UI changes with updated snapshots and run `rush e2e:test --to <package>` to scope failures.\n\n## Commit & Pull Request Guidelines\nFollow conventional commits (`type(scope): subject`) as seen in history (`fix(auto-layout): ...`). Keep subjects imperative and ≤72 characters, with optional bodies for context. PRs must describe the change, link GitHub issues, and attach before/after screenshots for UI updates. Confirm CI status, note any follow-ups, and request reviewers from the owning package tags (see `rush.json`).\n","category":"root","tokens":629}]}