From 6f0ef58d9a54f35a2a5849e84234a67fa8d8a9b5 Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Fri, 22 May 2026 19:35:36 -0700 Subject: [PATCH 1/2] chore(release): publish - @fbp/evaluator@1.1.0 - @fbp/graph-editor@1.1.0 - @fbp/spec@1.1.0 - @fbp/types@1.1.0 --- packages/evaluator/CHANGELOG.md | 20 ++++++++++++++++ packages/evaluator/package.json | 2 +- packages/graph-editor/CHANGELOG.md | 37 ++++++++++++++++++++++++++++++ packages/graph-editor/package.json | 2 +- packages/spec/CHANGELOG.md | 9 ++++++++ packages/spec/package.json | 2 +- packages/types/CHANGELOG.md | 11 +++++++++ packages/types/package.json | 2 +- 8 files changed, 81 insertions(+), 4 deletions(-) diff --git a/packages/evaluator/CHANGELOG.md b/packages/evaluator/CHANGELOG.md index da47d5d..46ba864 100644 --- a/packages/evaluator/CHANGELOG.md +++ b/packages/evaluator/CHANGELOG.md @@ -3,6 +3,26 @@ All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. +# 1.1.0 (2026-05-23) + +### Bug Fixes + +- graphInput nodes now use default prop when no external input provided ([1d567ba](https://github.com/flow-based-programming/spec/commit/1d567ba0935e099f7c99e60ccbb301e1e92b9ea3)) +- remove output port from graphOutput node definition ([1281944](https://github.com/flow-based-programming/spec/commit/128194443195e99dda27a98a9abfc3f6ee11a081)) + +### Features + +- add @fbp/evaluator with lazy graph evaluation ([9e8dd3a](https://github.com/flow-based-programming/spec/commit/9e8dd3aed2f5cfe316cbef0f04e80642dfaeb9bb)) +- add boundary nodes with auto-naming and async evaluation ([075795d](https://github.com/flow-based-programming/spec/commit/075795db4c866d2ae21003f6e6bc0deda6c8a3b9)) +- add digital asset support with parameterization ([1e840b7](https://github.com/flow-based-programming/spec/commit/1e840b7d8c7abf2d42bdda1557e2199051e298ce)) +- add icons to all node definitions and display in UI ([bfb0c46](https://github.com/flow-based-programming/spec/commit/bfb0c4645ce5ae9415d57fcf79c8cf51e8abf77d)) +- add new node definitions (graphql/request, json/select, json/object, flow/guard, string/template, string/concat) ([75bda87](https://github.com/flow-based-programming/spec/commit/75bda87ad078793997693a253ad83a7c1d52ba03)) +- add react-icons SVG icons and GraphQL login example ([02a493d](https://github.com/flow-based-programming/spec/commit/02a493da93f0d2b4f7e661538f261591c0c7de09)) +- add subnet evaluation support with tests ([0c4a187](https://github.com/flow-based-programming/spec/commit/0c4a18789da49f51298a4765aa59c759bf1935fa)) +- add type dropdown and coercion to all boundary nodes (input, output, prop) ([78a6052](https://github.com/flow-based-programming/spec/commit/78a6052166b2d9aef3d47b9401cc1c13d7d9bd9b)) +- add type selector dropdown for graphInput nodes ([452043d](https://github.com/flow-based-programming/spec/commit/452043debf7a18b992d1cbbe5452e18e3983abb1)) +- refactor to (context, name) tuple model ([daac896](https://github.com/flow-based-programming/spec/commit/daac8966f111c0acfca79e0e9177662e4e31f0a9)) + # [1.0.0](https://github.com/flow-based-programming/spec/compare/@fbp/evaluator@0.2.0...@fbp/evaluator@1.0.0) (2026-04-17) **Note:** Version bump only for package @fbp/evaluator diff --git a/packages/evaluator/package.json b/packages/evaluator/package.json index 27923cd..c5f607f 100644 --- a/packages/evaluator/package.json +++ b/packages/evaluator/package.json @@ -1,6 +1,6 @@ { "name": "@fbp/evaluator", - "version": "1.0.0", + "version": "1.1.0", "author": "Dan Lynch ", "description": "Lazy graph evaluator for Flow-Based Programming", "main": "index.js", diff --git a/packages/graph-editor/CHANGELOG.md b/packages/graph-editor/CHANGELOG.md index 9d9d9ab..8905bb9 100644 --- a/packages/graph-editor/CHANGELOG.md +++ b/packages/graph-editor/CHANGELOG.md @@ -3,6 +3,43 @@ All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. +# 1.1.0 (2026-05-23) + +### Bug Fixes + +- add graph context for evaluator resolution + digital asset example ([981ffdc](https://github.com/flow-based-programming/spec/commit/981ffdc138f02aa70df38cdca4dc3cbe215a3e54)) +- derive subnet ports from boundary nodes for automatic sync at any level ([4d7c15f](https://github.com/flow-based-programming/spec/commit/4d7c15fe9f4cd32c85e4312358aa4b0b3c0f2bdf)) +- edge preview in subgraphs and boundary node sync with parent subnet ([891cc45](https://github.com/flow-based-programming/spec/commit/891cc45aafb9da90f7d47744c1ad4ae08d369697)) +- evaluation now works inside subgraphs using scoped graph ([16aa4e6](https://github.com/flow-based-programming/spec/commit/16aa4e6a4d5470a6d4be9522e3a5300a4314e56b)) +- **graph-editor:** add global keyboard handler for consistent Enter/U navigation ([cd3a373](https://github.com/flow-based-programming/spec/commit/cd3a373000e85c03649acc9b4cf98738aa75f4b8)) +- **graph-editor:** consistent Enter/U navigation + always-on workspace ([ad5b32c](https://github.com/flow-based-programming/spec/commit/ad5b32c7b672717785885b22e470da29e71ab671)) +- make all reducer actions scope-aware for subnet navigation ([051e7a8](https://github.com/flow-based-programming/spec/commit/051e7a85be0b657dba9a4e24b68811fc07640dc6)) +- move React hooks to top of PropertiesPanel to fix hooks order error ([24da1d3](https://github.com/flow-based-programming/spec/commit/24da1d36df85049766a9de6ba7f72c10d3d83274)) +- PropertiesPanel now uses scoped nodes for subnet context ([0331374](https://github.com/flow-based-programming/spec/commit/03313746b2eda43988aaa188d224551e61e8bb0b)) +- refresh button now uses live graph state, add default value for graphInput ([1dd7228](https://github.com/flow-based-programming/spec/commit/1dd7228fa4376d4a3571ea287ba6b2d19f8bc975)) +- remove stale compiled .js/.d.ts from graph-editor src and www/editor pages ([f2728c1](https://github.com/flow-based-programming/spec/commit/f2728c12cc5fd98a50a02541746d7f232676c47c)) +- subnet navigation now renders internal nodes when diving in ([83b99dc](https://github.com/flow-based-programming/spec/commit/83b99dc1f7acaa104ed94148c70e1d29c6213981)) +- **www/editor:** workspace browser improvements ([5e5a680](https://github.com/flow-based-programming/spec/commit/5e5a680a72f9dd87912b8aa7b52bee1b5c2abd96)) + +### Features + +- add @fbp/graph-editor package, remove litegraph ([7062610](https://github.com/flow-based-programming/spec/commit/70626102c71a1db963cebe68b1abacfe1c6222a8)) +- add autolayout for subnet nodes - arranges nodes in layers by dependency ([46d7c31](https://github.com/flow-based-programming/spec/commit/46d7c31124b3ec78e39dbeff6849a6b511572049)) +- add boundary nodes with auto-naming and async evaluation ([075795d](https://github.com/flow-based-programming/spec/commit/075795db4c866d2ae21003f6e6bc0deda6c8a3b9)) +- add copy/paste for groups (Cmd+C/V) and allow 1+ node collapse ([6182ac2](https://github.com/flow-based-programming/spec/commit/6182ac2d946aafe8793764bc52a5988f4aa22e6d)) +- add editable boundary node names and drag-and-drop from palette ([1030db2](https://github.com/flow-based-programming/spec/commit/1030db2b80789502aaa185b5ec535d10d78cb622)) +- add GraphOutput nodes with evaluation result display ([351e82b](https://github.com/flow-based-programming/spec/commit/351e82b25b590e9e3990ccbf7edcabe548aa968e)) +- add icons to all node definitions and display in UI ([bfb0c46](https://github.com/flow-based-programming/spec/commit/bfb0c4645ce5ae9415d57fcf79c8cf51e8abf77d)) +- add L hotkey to autolayout selected nodes ([4295ed6](https://github.com/flow-based-programming/spec/commit/4295ed60477b5846becf9927c4c9c4f1a3f03f7c)) +- add proper UI frame with header, node palette sidebar, and status bar ([9713b2a](https://github.com/flow-based-programming/spec/commit/9713b2a31a3df9db75ee6cbbd5d39e56adf5f9d7)) +- add react-icons SVG icons and GraphQL login example ([02a493d](https://github.com/flow-based-programming/spec/commit/02a493da93f0d2b4f7e661538f261591c0c7de09)) +- add refresh button to re-evaluate GraphOutput results ([9c37391](https://github.com/flow-based-programming/spec/commit/9c37391e771828e8a860af3a3edb68ccc678c9cd)) +- add subnet collapse feature (Shift+C to collapse selected nodes) ([d91f609](https://github.com/flow-based-programming/spec/commit/d91f6092349f9cfa8507eb4dfab734311de1a4e7)) +- add toolbar with hotkeys, node palette, drag-to-connect, and make home page show flow graph ([6548a2d](https://github.com/flow-based-programming/spec/commit/6548a2dd92be5ec45eafdf5a42a7cbbb4e5165e4)) +- improve evaluate button spinner animation ([f080856](https://github.com/flow-based-programming/spec/commit/f08085685e82a2f5c1bef3263b9bfa78353ab1d0)) +- improve marquee selection and add GraphQL syntax highlighting ([0d5757b](https://github.com/flow-based-programming/spec/commit/0d5757baa347e490d2bad8cf592983e857e3da47)) +- refactor to (context, name) tuple model ([daac896](https://github.com/flow-based-programming/spec/commit/daac8966f111c0acfca79e0e9177662e4e31f0a9)) + # [1.0.0](https://github.com/flow-based-programming/spec/compare/@fbp/graph-editor@0.2.0...@fbp/graph-editor@1.0.0) (2026-04-17) **Note:** Version bump only for package @fbp/graph-editor diff --git a/packages/graph-editor/package.json b/packages/graph-editor/package.json index 18ebc66..2d1ad24 100644 --- a/packages/graph-editor/package.json +++ b/packages/graph-editor/package.json @@ -1,6 +1,6 @@ { "name": "@fbp/graph-editor", - "version": "1.0.0", + "version": "1.1.0", "author": "Dan Lynch ", "description": "Houdini-inspired graph editor for Flow-Based Programming", "main": "index.js", diff --git a/packages/spec/CHANGELOG.md b/packages/spec/CHANGELOG.md index c694eff..e44d6b8 100644 --- a/packages/spec/CHANGELOG.md +++ b/packages/spec/CHANGELOG.md @@ -3,6 +3,15 @@ All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. +# 1.1.0 (2026-05-23) + +### Features + +- add @fbp/spec package with storage schema and path-based API ([2bb0070](https://github.com/flow-based-programming/spec/commit/2bb0070d7a158bac6157db2905bf7035a21ef248)) +- add digital asset support with parameterization ([1e840b7](https://github.com/flow-based-programming/spec/commit/1e840b7d8c7abf2d42bdda1557e2199051e298ce)) +- add optional schema field to PortDef and PropDef ([82c3b7b](https://github.com/flow-based-programming/spec/commit/82c3b7b3e7770a32bb188ae7cbac2697644953e2)) +- refactor to (context, name) tuple model ([daac896](https://github.com/flow-based-programming/spec/commit/daac8966f111c0acfca79e0e9177662e4e31f0a9)) + # [1.0.0](https://github.com/flow-based-programming/spec/compare/@fbp/spec@0.2.0...@fbp/spec@1.0.0) (2026-04-17) **Note:** Version bump only for package @fbp/spec diff --git a/packages/spec/package.json b/packages/spec/package.json index c4f1f19..08be796 100644 --- a/packages/spec/package.json +++ b/packages/spec/package.json @@ -1,6 +1,6 @@ { "name": "@fbp/spec", - "version": "1.0.0", + "version": "1.1.0", "author": "Dan Lynch ", "description": "Storage specification and API for flow-based programming graphs", "main": "index.js", diff --git a/packages/types/CHANGELOG.md b/packages/types/CHANGELOG.md index eb1dbfb..8dbc20c 100644 --- a/packages/types/CHANGELOG.md +++ b/packages/types/CHANGELOG.md @@ -3,6 +3,17 @@ All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. +# 1.1.0 (2026-05-23) + +### Features + +- add @fbp/evaluator with lazy graph evaluation ([9e8dd3a](https://github.com/flow-based-programming/spec/commit/9e8dd3aed2f5cfe316cbef0f04e80642dfaeb9bb)) +- add @fbp/graph-editor package, remove litegraph ([7062610](https://github.com/flow-based-programming/spec/commit/70626102c71a1db963cebe68b1abacfe1c6222a8)) +- add digital asset support with parameterization ([1e840b7](https://github.com/flow-based-programming/spec/commit/1e840b7d8c7abf2d42bdda1557e2199051e298ce)) +- add icons to all node definitions and display in UI ([bfb0c46](https://github.com/flow-based-programming/spec/commit/bfb0c4645ce5ae9415d57fcf79c8cf51e8abf77d)) +- add optional schema field to PortDef and PropDef ([82c3b7b](https://github.com/flow-based-programming/spec/commit/82c3b7b3e7770a32bb188ae7cbac2697644953e2)) +- refactor to (context, name) tuple model ([daac896](https://github.com/flow-based-programming/spec/commit/daac8966f111c0acfca79e0e9177662e4e31f0a9)) + # [1.0.0](https://github.com/flow-based-programming/spec/compare/@fbp/types@0.3.0...@fbp/types@1.0.0) (2026-04-17) **Note:** Version bump only for package @fbp/types diff --git a/packages/types/package.json b/packages/types/package.json index d0bc65d..ae67615 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -1,6 +1,6 @@ { "name": "@fbp/types", - "version": "1.0.0", + "version": "1.1.0", "author": "Dan Lynch ", "description": "Flow-Based Programming schemas and converters in TypeScript", "main": "index.js", From 6964f4ad6a6503a38a39015add1196c1cc7acbef Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Sun, 31 May 2026 23:03:40 +0000 Subject: [PATCH 2/2] feat: add fbp skill with AGENTS.md Move fbp skill from constructive-io/constructive-skills to this repo. Includes SKILL.md, all reference docs (fbp-types, fbp-spec, fbp-evaluator, fbp-graph-editor), packaged zip, and AGENTS.md listing the skill. --- .agents/skills/fbp.zip | Bin 0 -> 9239 bytes .agents/skills/fbp/SKILL.md | 54 +++++ .../skills/fbp/references/fbp-evaluator.md | 186 ++++++++++++++++ .../skills/fbp/references/fbp-graph-editor.md | 205 ++++++++++++++++++ .agents/skills/fbp/references/fbp-spec.md | 204 +++++++++++++++++ .agents/skills/fbp/references/fbp-types.md | 154 +++++++++++++ AGENTS.md | 23 ++ 7 files changed, 826 insertions(+) create mode 100644 .agents/skills/fbp.zip create mode 100644 .agents/skills/fbp/SKILL.md create mode 100644 .agents/skills/fbp/references/fbp-evaluator.md create mode 100644 .agents/skills/fbp/references/fbp-graph-editor.md create mode 100644 .agents/skills/fbp/references/fbp-spec.md create mode 100644 .agents/skills/fbp/references/fbp-types.md create mode 100644 AGENTS.md diff --git a/.agents/skills/fbp.zip b/.agents/skills/fbp.zip new file mode 100644 index 0000000000000000000000000000000000000000..e6b283b17ceec0a65d28d6123db3109b14da8d7d GIT binary patch literal 9239 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 TK!kvR|9uAj&eI{3e?0vcBB!aX literal 0 HcmV?d00001 diff --git a/.agents/skills/fbp/SKILL.md b/.agents/skills/fbp/SKILL.md new file mode 100644 index 0000000..e885ae9 --- /dev/null +++ b/.agents/skills/fbp/SKILL.md @@ -0,0 +1,54 @@ +--- +name: fbp +description: "Flow-Based Programming toolkit — type system (fbp-types), specification language (fbp-spec), evaluator engine (fbp-evaluator), and visual graph editor (fbp-graph-editor). Use when working with FBP graphs, defining flow types, evaluating flow specifications, or building visual flow editors." +metadata: + author: constructive-io + version: "1.0.0" +--- + +# FBP (Flow-Based Programming) + +The complete FBP toolkit: type system, specification language, evaluator engine, and visual graph editor. + +## When to Apply + +Use this skill when: +- Working with FBP graph definitions +- Defining flow types and port contracts +- Evaluating flow specifications +- Building or customizing visual flow editors + +## Components + +### FBP Types + +The type system for FBP — port types, graph validation, type contracts between components. + +See [fbp-types.md](./references/fbp-types.md) for the type system reference. + +### FBP Spec + +The specification language for defining FBP graphs — component declarations, connections, IIPs (Initial Information Packets). + +See [fbp-spec.md](./references/fbp-spec.md) for the specification language. + +### FBP Evaluator + +The evaluation engine that executes FBP graphs — scheduling, data flow, component lifecycle. + +See [fbp-evaluator.md](./references/fbp-evaluator.md) for the evaluator reference. + +### FBP Graph Editor + +Visual editor for FBP graphs — drag-and-drop components, connection drawing, graph serialization. + +See [fbp-graph-editor.md](./references/fbp-graph-editor.md) for the editor reference. + +## Reference Guide + +| Reference | Topic | Consult When | +|-----------|-------|--------------| +| [fbp-types.md](./references/fbp-types.md) | FBP type system | Defining port types, type contracts, validation | +| [fbp-spec.md](./references/fbp-spec.md) | FBP specification language | Graph definitions, component declarations, connections | +| [fbp-evaluator.md](./references/fbp-evaluator.md) | FBP evaluator engine | Executing graphs, scheduling, data flow | +| [fbp-graph-editor.md](./references/fbp-graph-editor.md) | Visual graph editor | Editor setup, drag-and-drop, serialization | diff --git a/.agents/skills/fbp/references/fbp-evaluator.md b/.agents/skills/fbp/references/fbp-evaluator.md new file mode 100644 index 0000000..6595eb4 --- /dev/null +++ b/.agents/skills/fbp/references/fbp-evaluator.md @@ -0,0 +1,186 @@ +--- +name: fbp-evaluator +description: Lazy graph evaluator for Flow-Based Programming. Use when evaluating FBP graphs, running dataflow computations, or working with the @fbp/evaluator package. +--- + +Lazy graph evaluator for Flow-Based Programming. + +## Installation + +```bash +pnpm add @fbp/evaluator +``` + +## Overview + +`@fbp/evaluator` provides a lazy evaluation engine for FBP graphs. It only evaluates nodes that are needed for the requested output, making it efficient for large graphs where only a subset of nodes contribute to the result. + +## Basic Usage + +```typescript +import { evaluate } from '@fbp/evaluator'; +import type { Graph } from '@fbp/types'; +import type { NodeDefinitionWithImpl } from '@fbp/evaluator'; + +// Define node implementations +const addDef: NodeDefinitionWithImpl = { + context: 'js', + category: 'math', + type: 'js/math/add', + inputs: [ + { name: 'a', type: 'number' }, + { name: 'b', type: 'number' } + ], + outputs: [{ name: 'sum', type: 'number' }], + impl: (inputs) => ({ + sum: (inputs.a ?? 0) + (inputs.b ?? 0) + }) +}; + +const constNumberDef: NodeDefinitionWithImpl = { + context: 'js', + category: 'const', + type: 'js/const/number', + props: [{ name: 'value', type: 'number' }], + outputs: [{ name: 'value', type: 'number' }], + impl: (inputs, props) => ({ + value: props.value ?? 0 + }) +}; + +// Create a graph +const graph: Graph = { + name: 'simple-add', + nodes: [ + { name: 'num1', type: 'js/const/number', props: [{ name: 'value', value: 5 }] }, + { name: 'num2', type: 'js/const/number', props: [{ name: 'value', value: 3 }] }, + { name: 'add', type: 'js/math/add' } + ], + edges: [ + { src: { node: 'num1', port: 'value' }, dst: { node: 'add', port: 'a' } }, + { src: { node: 'num2', port: 'value' }, dst: { node: 'add', port: 'b' } } + ] +}; + +// Evaluate the graph +const result = evaluate(graph, { + definitions: [constNumberDef, addDef], + outputNode: 'add', + outputPort: 'sum' +}); + +console.log(result); // 8 +``` + +## Node Definition with Implementation + +```typescript +interface NodeDefinitionWithImpl extends NodeDefinition { + impl: ( + inputs: Record, + props: Record + ) => Record; +} +``` + +The `impl` function receives: +- `inputs`: Values from connected input ports +- `props`: Property values set on the node instance + +It returns an object with output port names as keys. + +## API + +### `evaluate(graph, options)` + +Evaluates a graph starting from the specified output node/port. + +```typescript +const result = evaluate(graph, { + definitions: NodeDefinitionWithImpl[], // Node definitions with implementations + outputNode: string, // Node to get output from + outputPort: string, // Port to get output from + inputs?: Record, // External inputs for graphInput nodes + props?: Record // Props for graphProp nodes +}); +``` + +## Features + +### Lazy Evaluation + +Only evaluates nodes that are needed for the output. If a node's output isn't connected to the requested output path, it won't be evaluated. + +### Multi-Input Ports + +Supports ports that accept multiple incoming edges. Values are collected in edge array order: + +```typescript +const mergeDef: NodeDefinitionWithImpl = { + type: 'js/array/merge', + inputs: [{ name: 'items', type: 'any', multi: true }], + outputs: [{ name: 'array', type: 'any[]' }], + impl: (inputs) => ({ + array: inputs.items // Array of all connected values + }) +}; +``` + +### Boundary Nodes + +Supports `graphInput`, `graphOutput`, and `graphProp` boundary nodes for graph inputs/outputs/props: + +```typescript +// Provide external inputs +const result = evaluate(graph, { + definitions, + outputNode: 'output_result', + outputPort: 'value', + inputs: { a: 10, b: 20 }, // Keyed by portName + props: { scale: 2.0 } // Keyed by propName +}); +``` + +## Example: Building a Node Library + +```typescript +const mathNodes: NodeDefinitionWithImpl[] = [ + { + context: 'js', + category: 'math', + type: 'js/math/add', + inputs: [ + { name: 'a', type: 'number' }, + { name: 'b', type: 'number' } + ], + outputs: [{ name: 'sum', type: 'number' }], + impl: (inputs) => ({ sum: (inputs.a ?? 0) + (inputs.b ?? 0) }) + }, + { + context: 'js', + category: 'math', + type: 'js/math/multiply', + inputs: [ + { name: 'a', type: 'number' }, + { name: 'b', type: 'number' } + ], + outputs: [{ name: 'product', type: 'number' }], + impl: (inputs) => ({ product: (inputs.a ?? 1) * (inputs.b ?? 1) }) + }, + { + context: 'js', + category: 'math', + type: 'js/math/negate', + inputs: [{ name: 'value', type: 'number' }], + outputs: [{ name: 'negated', type: 'number' }], + impl: (inputs) => ({ negated: -(inputs.value ?? 0) }) + } +]; +``` + +## Best Practices + +1. Use descriptive type paths like `context/category/name` (e.g., `js/math/add`) +2. Always provide default values in `impl` functions for missing inputs +3. Keep node implementations pure — no side effects +4. Use `multi: true` for ports that should accept multiple connections diff --git a/.agents/skills/fbp/references/fbp-graph-editor.md b/.agents/skills/fbp/references/fbp-graph-editor.md new file mode 100644 index 0000000..6b12779 --- /dev/null +++ b/.agents/skills/fbp/references/fbp-graph-editor.md @@ -0,0 +1,205 @@ +--- +name: fbp-graph-editor +description: Houdini-inspired graph editor for Flow-Based Programming built with React. Use when building or customizing a visual graph editor, working with the @fbp/graph-editor package. +--- + +Houdini-inspired graph editor for Flow-Based Programming built with React. + +## Installation + +```bash +pnpm add @fbp/graph-editor +``` + +## Overview + +`@fbp/graph-editor` is a React component for visual editing of FBP graphs. It features an SVG-based canvas with pan/zoom, node rendering with fully-qualified type paths, Bezier edge connections, selection system, properties panel, and subgraph navigation. + +## Basic Usage + +```tsx +import { GraphEditor } from '@fbp/graph-editor'; +import type { Graph, NodeDefinition } from '@fbp/types'; + +const graph: Graph = { + name: 'my-graph', + definitions: [ + { + context: 'js', + category: 'math', + type: 'js/math/add', + inputs: [ + { name: 'a', type: 'number' }, + { name: 'b', type: 'number' } + ], + outputs: [ + { name: 'sum', type: 'number' } + ] + } + ], + nodes: [ + { name: 'add1', type: 'js/math/add', meta: { x: 100, y: 100 } } + ], + edges: [] +}; + +function App() { + return ( +
+ +
+ ); +} +``` + +## Features + +### SVG-Based Canvas + +The editor uses SVG for rendering, providing crisp visuals at any zoom level. Pan and zoom are supported via mouse/trackpad gestures. + +### Node Rendering + +Nodes display their fully-qualified type paths (e.g., `js/math/add`) and show input/output ports based on their definition. + +### Bezier Edge Connections + +Edges are rendered as smooth Bezier curves connecting output ports to input ports. Click and drag from a port to create new connections. + +### Selection System + +- Click to select a single node +- Shift+click to add/remove from selection +- Box select with Shift+drag +- Cmd/Ctrl+A to select all +- Escape to clear selection +- Cmd/Ctrl+D to duplicate selection + +### Properties Panel + +Auto-generated from `PropDefinition`. When a node is selected, its properties are displayed in a panel for editing. + +### Subgraph Navigation + +- Enter to dive into a selected subnet +- U to go up from a subnet + +## Keyboard Shortcuts + +| Shortcut | Action | +|----------|--------| +| Delete/Backspace | Delete selected nodes/edges | +| Cmd/Ctrl+D | Duplicate selection | +| Cmd/Ctrl+A | Select all | +| Escape | Clear selection | +| Enter | Dive into selected subnet | +| U | Go up from subnet | +| Shift+Drag | Box select | +| Alt+Drag or Middle Mouse | Pan canvas | +| Ctrl/Cmd+Scroll | Zoom | + +## Channel Reference Detection + +The editor detects channel references in property values using patterns like `ch("...")` and `$VAR`, enabling visual feedback for connected parameters. + +## Styling + +The editor uses Tailwind CSS for styling. Ensure your project has Tailwind configured: + +```tsx +// tailwind.config.js +module.exports = { + content: [ + './src/**/*.{js,ts,jsx,tsx}', + './node_modules/@fbp/graph-editor/**/*.{js,ts,jsx,tsx}' + ], + // ... +}; +``` + +## Props + +```typescript +interface GraphEditorProps { + graph: Graph; + onChange?: (graph: Graph) => void; + definitions?: NodeDefinition[]; + readOnly?: boolean; +} +``` + +| Prop | Type | Description | +|------|------|-------------| +| `graph` | `Graph` | The graph to display and edit | +| `onChange` | `(graph: Graph) => void` | Callback when graph changes | +| `definitions` | `NodeDefinition[]` | Additional node type definitions | +| `readOnly` | `boolean` | Disable editing | + +## Peer Dependencies + +```json +{ + "peerDependencies": { + "react": ">=18.0.0", + "react-dom": ">=18.0.0" + } +} +``` + +## Example: Complete Editor Setup + +```tsx +import { useState } from 'react'; +import { GraphEditor } from '@fbp/graph-editor'; +import type { Graph } from '@fbp/types'; + +const initialGraph: Graph = { + name: 'calculator', + definitions: [ + { + type: 'js/const/number', + context: 'js', + category: 'const', + props: [{ name: 'value', type: 'number', default: 0 }], + outputs: [{ name: 'value', type: 'number' }] + }, + { + type: 'js/math/add', + context: 'js', + category: 'math', + inputs: [ + { name: 'a', type: 'number' }, + { name: 'b', type: 'number' } + ], + outputs: [{ name: 'sum', type: 'number' }] + } + ], + nodes: [ + { name: 'num1', type: 'js/const/number', meta: { x: 50, y: 50 }, props: [{ name: 'value', value: 5 }] }, + { name: 'num2', type: 'js/const/number', meta: { x: 50, y: 150 }, props: [{ name: 'value', value: 3 }] }, + { name: 'add', type: 'js/math/add', meta: { x: 250, y: 100 } } + ], + edges: [ + { src: { node: 'num1', port: 'value' }, dst: { node: 'add', port: 'a' } }, + { src: { node: 'num2', port: 'value' }, dst: { node: 'add', port: 'b' } } + ] +}; + +function App() { + const [graph, setGraph] = useState(initialGraph); + + return ( +
+
+

{graph.name}

+
+
+ +
+
+ ); +} +``` diff --git a/.agents/skills/fbp/references/fbp-spec.md b/.agents/skills/fbp/references/fbp-spec.md new file mode 100644 index 0000000..1c02cfb --- /dev/null +++ b/.agents/skills/fbp/references/fbp-spec.md @@ -0,0 +1,204 @@ +--- +name: fbp-spec +description: Storage specification and manipulation API for flow-based programming graphs. Use when working with FBP graph storage, manipulating graph data structures, or using the @fbp/spec package. +--- + +Storage specification and manipulation API for flow-based programming graphs. + +## Installation + +```bash +pnpm add @fbp/spec +``` + +## Overview + +`@fbp/spec` provides a two-layer type system for flow-based programming graphs: + +| Layer | Purpose | +|-------|---------| +| **Storage** | Minimal canonical format for persistence | +| **Renderer** | Extended types with derived data for UI | +| **API** | Pure functions for graph manipulation | + +The storage layer is designed for content-addressable storage (merkle trees) where each graph state can be uniquely hashed. + +## Design Philosophy + +### Boundary Nodes as Single Source of Truth + +Traditional graph formats store interface definitions in two places (arrays and boundary nodes), causing sync bugs. This spec eliminates the problem by using boundary nodes as the ONLY source of truth. + +The `inputs/outputs/props` arrays are NOT stored in the storage format — they are derived at runtime from boundary nodes and cached in the renderer layer. + +### Path-Based Identity + +Nodes are identified by their path from the root: + +``` +/ # Root scope +/add1 # Root-level node +/subnet1/add1 # Node inside subnet1 +/subnet1/nested/add1 # Deeply nested node +``` + +### Per-Scope Edges + +Edges are stored within the scope they belong to. Root-level edges are in `graph.edges`, subnet edges are in `node.edges`. + +## API Reference + +All API functions are pure and immutable — they return new graphs without modifying the original. + +### Path Utilities + +```typescript +import { parsePath, joinPath, getParentPath, getNodeName, isRootPath } from '@fbp/spec'; + +parsePath('/foo/bar') // ['foo', 'bar'] +joinPath(['foo', 'bar']) // '/foo/bar' +getParentPath('/foo/bar') // '/foo' +getNodeName('/foo/bar') // 'bar' +isRootPath('/') // true +``` + +### Node Operations + +```typescript +import { insertNode, removeNode, renameNode, moveNode } from '@fbp/spec'; + +// Insert a node at root scope +const newGraph = insertNode(graph, '/', { + name: 'add1', + type: 'math/add' +}); + +// Insert into a subnet +const newGraph = insertNode(graph, '/subnet1', { + name: 'multiply1', + type: 'math/multiply' +}); + +// Remove a node and connected edges +const newGraph = removeNode(graph, '/add1'); + +// Rename a node (updates edge references) +const newGraph = renameNode(graph, '/add1', 'adder'); + +// Move a node to a different scope +const newGraph = moveNode(graph, '/add1', '/subnet1'); +``` + +### Property Operations + +```typescript +import { setProps, getProps, removeProp } from '@fbp/spec'; + +const newGraph = setProps(graph, '/add1', [ + { name: 'a', value: 5 }, + { name: 'b', value: 10 } +]); + +const props = getProps(graph, '/add1'); +// [{ name: 'a', value: 5 }, { name: 'b', value: 10 }] + +const newGraph = removeProp(graph, '/add1', 'a'); +``` + +### Edge Operations + +```typescript +import { addEdge, removeEdge } from '@fbp/spec'; + +const newGraph = addEdge(graph, '/', { + src: { node: 'input1', port: 'value' }, + dst: { node: 'add1', port: 'a' } +}); + +const newGraph = removeEdge(graph, '/', + { node: 'input1', port: 'value' }, + { node: 'add1', port: 'a' } +); +``` + +### Query Helpers + +```typescript +import { getNode, getNodes, getEdges, findNodes, findBoundaryNodes, hasNode, countNodes } from '@fbp/spec'; + +const node = getNode(graph, '/subnet1/add1'); +const rootNodes = getNodes(graph, '/'); +const rootEdges = getEdges(graph, '/'); + +const addNodes = findNodes(graph, (node) => node.type === 'math/add'); +// [{ node: {...}, path: '/add1' }, { node: {...}, path: '/subnet1/add2' }] + +const boundary = findBoundaryNodes(graph, '/subnet1'); +// { inputs: [...], outputs: [...], props: [...] } + +if (hasNode(graph, '/subnet1/add1')) { /* exists */ } + +const total = countNodes(graph); +``` + +### Metadata Operations + +```typescript +import { setMeta, setPosition } from '@fbp/spec'; + +const newGraph = setMeta(graph, '/add1', { description: 'Adds two numbers' }); +const newGraph = setPosition(graph, '/add1', 100, 200); +``` + +## Example: Simple Math Graph + +```json +{ + "nodes": [ + { + "name": "input_a", + "type": "graphInput", + "meta": { "x": 0, "y": 0 }, + "props": [ + { "name": "portName", "value": "a" }, + { "name": "dataType", "value": "number" } + ] + }, + { + "name": "input_b", + "type": "graphInput", + "meta": { "x": 0, "y": 100 }, + "props": [ + { "name": "portName", "value": "b" }, + { "name": "dataType", "value": "number" } + ] + }, + { + "name": "add1", + "type": "math/add", + "meta": { "x": 200, "y": 50 } + }, + { + "name": "output_sum", + "type": "graphOutput", + "meta": { "x": 400, "y": 50 }, + "props": [ + { "name": "portName", "value": "sum" }, + { "name": "dataType", "value": "number" } + ] + } + ], + "edges": [ + { "src": { "node": "input_a", "port": "value" }, "dst": { "node": "add1", "port": "a" } }, + { "src": { "node": "input_b", "port": "value" }, "dst": { "node": "add1", "port": "b" } }, + { "src": { "node": "add1", "port": "sum" }, "dst": { "node": "output_sum", "port": "value" } } + ] +} +``` + +## Normative Rules + +1. **Boundary Nodes ARE the Interface** — No separate `inputs/outputs/props` arrays in storage +2. **Edges are Per-Scope** — Each subnet stores its own edges +3. **Path-Based Identity** — Renaming/moving changes identity +4. **Minimal Storage** — Only store what's needed to reconstruct the graph diff --git a/.agents/skills/fbp/references/fbp-types.md b/.agents/skills/fbp/references/fbp-types.md new file mode 100644 index 0000000..d21e10a --- /dev/null +++ b/.agents/skills/fbp/references/fbp-types.md @@ -0,0 +1,154 @@ +--- +name: fbp-types +description: Flow-Based Programming TypeScript types and GraphSchemata specification. Use when working with FBP type definitions, graph schemata, or the @fbp/types package. +--- + +Flow-Based Programming TypeScript types and GraphSchemata specification. + +## Installation + +```bash +pnpm add @fbp/types +``` + +## Overview + +`@fbp/types` provides TypeScript types for a Houdini-inspired, merkle-friendly graph specification. The core design principles are explicitness over magic, composable subgraphs, stable content-addressable structure, and clear separation between dataflow and configuration. + +## Core Concepts + +### Everything is a Node + +The entire document is a single Node. Nodes may contain other nodes and edges, forming nested graphs (subnets). A node becomes a subnet simply by containing `nodes[]` and `edges[]`. There is no separate "graph" type. + +### Identity Model + +Node identity equals name within parent scope. Names may be hierarchical paths by convention (`some/subnet/node`). Rename or move equals identity change. This model is compatible with merkle/content-addressable versioning. + +## Type Definitions + +### Graph + +```typescript +interface Graph { + name?: string; + nodes: Node[]; + edges: Edge[]; + definitions?: NodeDefinition[]; + meta?: NodeMeta; +} +``` + +### Node + +```typescript +interface Node { + name: string; // Unique within parent scope + type: string; // References a NodeDefinition + meta?: NodeMeta; // Position and metadata + props?: PropValue[]; // Property values + nodes?: Node[]; // Child nodes (makes this a subnet) + edges?: Edge[]; // Edges within this scope +} +``` + +### Edge + +```typescript +interface Edge { + src: PortRef; // Source (output port) + dst: PortRef; // Destination (input port) + channel?: string; // Optional channel (default: "main") +} + +interface PortRef { + node: string; // Node name within scope + port: string; // Port name +} +``` + +### NodeDefinition + +```typescript +interface NodeDefinition { + type: string; // Unique identifier (e.g., "math/add") + context?: string; // Namespace (e.g., "math", "ui") + category?: string; // Palette category + inputs?: PortDef[]; // Input port definitions + outputs?: PortDef[]; // Output port definitions + props?: PropDef[]; // Property definitions + icon?: string; + description?: string; +} +``` + +### Port and Prop Definitions + +```typescript +interface PortDef { + name: string; + type?: string; // Data type (e.g., "string", "number", "any") + multi?: boolean; // Accepts multiple connections + description?: string; +} + +interface PropDef { + name: string; + type?: string; + default?: any; + description?: string; +} + +interface PropValue { + name: string; + value?: any; + ref?: boolean; // If true, value is a reference path +} +``` + +## Ports (No Lanes) + +Ports are named, typed, and singular. There is no lane or index dimension. Branching uses multiple named output ports (e.g., `true`, `false`, `error`). Fan-in is never implicit — multiple values must be combined via explicit nodes (`Merge`, `Collect`, etc.). + +## Props vs Dataflow + +Props are not dataflow. They configure node behavior and are not connected by edges. They may reference other parameters via `Ref`: + +```json +{ "ref": "../config/apiKey" } +``` + +## Boundary Nodes + +Boundary nodes define a subnet's interface: + +| Node Type | Purpose | Properties | +|-----------|---------|------------| +| `graphInput` | Input port | `portName`, `dataType` | +| `graphOutput` | Output port | `portName`, `dataType` | +| `graphProp` | Configuration property | `propName`, `dataType`, `default` | + +Reserved names `@in`, `@out`, `@props` are used for canonical boundary nodes. + +## Channels + +Edges may specify a `channel` for namespacing: + +```typescript +{ + src: { node: 'A', port: 'out' }, + dst: { node: 'B', port: 'in' }, + channel: 'error' +} +``` + +Default channel is `"main"`. Non-main channels are for error routing, control edges, metadata propagation. + +## Validation Rules + +- Node names must be unique within a scope +- Node names starting with `@` are reserved for boundary nodes +- Port names must be unique within inputs, outputs, and props +- Edges must reference existing ports +- Fan-in requires explicit merge nodes +- Branching requires explicit output ports diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0cdd14e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ +# AGENTS.md + +## Available Skills + +| Skill | Purpose | +|-------|---------| +| **fbp** | Flow-Based Programming toolkit — type system, specification language, evaluator engine, and visual graph editor | + +### Skill Location + +Skills are in `.agents/skills/`: + +``` +.agents/skills/ + fbp/ + SKILL.md # Skill definition + references/ + fbp-types.md # Type system reference + fbp-spec.md # Specification language + fbp-evaluator.md # Evaluator engine + fbp-graph-editor.md # Visual graph editor + fbp.zip # Packaged for distribution +```