@vizualmodel/vmblu-cli 0.3.2 → 0.3.3

package/README.md

@@ -1,7 +1,6 @@
 # CLI for vmblu
 This folder contains the CLI commands that are available for vmblu.
 
-
 ## Folder layout
 
 ```txt
@@ -12,7 +11,7 @@ vmblu/
       profile/
       migrate/
     templates/
-      0.8.2/
+      x.y.z/                # a directory per version x.y.z
         vmblu.schema.json
         vmblu.annex.md
         seed.md
@@ -25,7 +24,7 @@ vmblu/
 
 ## Add more commands
 
-Create commands/migrate/index.js with the same export shape { command, describe, builder, handler }. The router auto-discovers it, so users can run vmblu migrate ….
+Create commands/migrate/index.js with the same export shape { command, describe, builder, handler }. The router auto-discovers it.
 
 ## Dev/test workflow
 

package/commands/init/index.js

@@ -2,6 +2,8 @@
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { initProject } from './init-project.js';
+import pckg from '../../package.json' assert { type: 'json' };
+
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -9,7 +11,7 @@ export const command = 'init <folder name>';
 export const describe = 'Scaffold an empty vmblu project';
 export const builder = [
   { flag: '--name <project>', desc: 'Project name (default: folder name)' },
-  { flag: '--schema <ver>',   desc: 'Schema version (default: 0.8.2)' },
+  { flag: '--schema <ver>',   desc: 'Schema version (default: latest version)' },
   { flag: '--force',          desc: 'Overwrite existing files' },
   { flag: '--dry-run',        desc: 'Show actions without writing' }
 ];
@@ -28,7 +30,7 @@ export const handler = async (argv) => {
 
   const targetDir = path.resolve(args._[0] || '.');
   const projectName = args.name || path.basename(targetDir);
-  const schemaVersion = args.schema || '0.8.2';
+  const schemaVersion = args.schema || pckg.schemaVersion;
 
   await initProject({
     targetDir,

package/commands/init/init-project.js

@@ -6,6 +6,11 @@ import path from 'path';
 //import crypto from 'crypto';
 import { makePackageJson } from './make-package-json.js';
 
+// Get the versions
+import pckg from '../../package.json' assert { type: 'json' };
+const SCHEMA_VERSION = pckg.schemaVersion
+const CLI_VERSION = pckg.version
+
 function rel(from, to) {
   return path.posix.join(...path.relative(from, to).split(path.sep));
 }
@@ -50,7 +55,7 @@ function defaultModel(projectName) {
   const now = new Date().toISOString();
   return JSON.stringify({
     header: {
-      version: "0.8.2",
+      version: SCHEMA_VERSION,
       created: now,
       saved: now,
       utc: now,
@@ -73,7 +78,7 @@ function defaultModel(projectName) {
 function defaultDoc(projectName) {
   const now = new Date().toISOString();
   return JSON.stringify({
-    version: "0.0.0",
+    version: CLI_VERSION,
     generatedAt: now,
     entries: {}
   }, null, 2);
@@ -145,7 +150,7 @@ async function initProject(opts) {
   const {
     targetDir,
     projectName = path.basename(opts.targetDir),
-    schemaVersion = "0.8.2",
+    schemaVersion = SCHEMA_VERSION,
     force = false,
     dryRun = false,
     templatesDir = path.join(__dirname, '..', 'templates'),
@@ -246,7 +251,7 @@ async function initProject(opts) {
   }
 
   // 5) Make the package file
-  makePackageJson({ absTarget, projectName, force, dryRun, addCliDep: true, cliVersion: "^0.1.0" }, ui);
+  makePackageJson({ absTarget, projectName, force, dryRun, addCliDep: true, cliVersion: "^" + CLI_VERSION }, ui);
 
   // 6) Final tree hint
   ui.info(`\nScaffold complete${dryRun ? ' (dry run)' : ''}:\n` +

package/commands/profile/profile.bundle.js

@@ -2875,7 +2875,7 @@ async readSourceMap() {
 
     // get the full path
     const fullPath = this.arl?.getFullPath();
-
+console.log('FULLPATH', fullPath);
     // check
     if (!fullPath) return null
 
@@ -4054,8 +4054,6 @@ const keyboardHandling$1 = {
 
             // and redraw
             this.redraw();
-
-            console.log('hello baby');
         }
     },
 
@@ -4250,7 +4248,7 @@ const messageHandling = {
         //const appPath = doc.target.application?.userPath ?? Path.changeExt(doc.model.arl.userPath, 'js')
         const appPath =
             doc.target.library?.userPath ??
-            removeExt(doc.model.arl.userPath) + '-app.js';
+            removeExt(doc.model.arl.userPath) + '.app.js';
 
         // request the path for the save as operation
         this.tx.send('show app path', {
@@ -12227,7 +12225,12 @@ showProfile: {
         const profile = pin.is.input ? editor.doc.model.getInputPinProfile(pin) : editor.doc.model.getOutputPinProfile(pin);
 
         // check
-        if (!profile) return
+        if (!profile) {
+
+            console.log(`NO PROFILE ${pin.name}`);
+
+            return
+        }
 
         // show the profile
         editor.tx.send('pin profile',{pos, pin, profile,
@@ -14037,6 +14040,10 @@ Editor.prototype = {
 };
 Object.assign(Editor.prototype, mouseHandling$1, keyboardHandling$1, messageHandling, undoRedoHandling);
 
+/**
+ * @node editor editor
+ */
+
 function placePopup(pos) {
     return {x: pos.x - 15, y:pos.y + 10}
 }
@@ -14046,7 +14053,6 @@ const nodeClickHandling = {
     showExportForm(pos) {
 
         const node = this;
-        editor.tx;
 
         // send the show link path
         editor.tx.send("show link",{   
@@ -14062,7 +14068,6 @@ const nodeClickHandling = {
     showLinkForm(pos) {
 
         const node = this;
-        const tx = editor.tx;
 
         // check what path to show - show no path if from the main model
         const linkPath = (node.link && (node.link.model != editor.doc?.model)) ? node.link.model?.arl.userPath : '';
@@ -14090,7 +14095,7 @@ const nodeClickHandling = {
                     editor.doEdit('changeLink',{node, lName: newName, userPath: newPath});
 
                 // open the file if the link is to an outside file !
-                if (node.link.model?.arl && (node.link.model != editor.doc?.model)) tx.send('open document',node.link.model.arl);
+                if (node.link.model?.arl && (node.link.model != editor.doc?.model)) editor.tx.send('open document',node.link.model.arl);
             },
             cancel:()=>{}
         });
@@ -14099,7 +14104,6 @@ const nodeClickHandling = {
     iconClick(view, icon, pos) {
 
         const node = this;
-        const tx = editor.tx;
 
         // move the popup a bit away from the icon
         const newPos = placePopup(pos);
@@ -14119,7 +14123,7 @@ const nodeClickHandling = {
                 const factoryPath = node.factory.arl ? node.factory.arl.userPath : '';
 
                 // show the factory
-                tx.send("show factory",{ title: 'Factory for ' + node.name, 
+                editor.tx.send("show factory",{ title: 'Factory for ' + node.name, 
                                         name: factoryName,
                                         path: factoryPath,
                                         pos: newPos,
@@ -14138,7 +14142,7 @@ const nodeClickHandling = {
                                             const arl = node.factory.arl ?? editor.doc.resolve('./index.js');
 
                                             // open the file
-                                            tx.send('open source file',{arl});
+                                            editor.tx.send('open source file',{arl});
                                         },
                                         cancel:()=>{}
                 });
@@ -14175,7 +14179,7 @@ const nodeClickHandling = {
 
             case 'cog':
 
-                tx.send("settings",{    title:'Settings for ' + node.name, 
+                editor.tx.send("settings",{    title:'Settings for ' + node.name, 
                                         pos: newPos,
                                         json: node.sx,
                                         ok: (sx) => editor.doEdit("changeNodeSettings",{node, sx})
@@ -14184,7 +14188,7 @@ const nodeClickHandling = {
 
             case 'pulse':
 
-                tx.send("runtime settings",{    title:'Runtime settings for ' + node.name, 
+                editor.tx.send("runtime settings",{    title:'Runtime settings for ' + node.name, 
                                                 pos: newPos,
                                                 dx: node.dx,
                                                 ok: (dx) => editor.doEdit("changeNodeDynamics",{node, dx})
@@ -14194,7 +14198,7 @@ const nodeClickHandling = {
             case 'comment':
 
                 // save the node hit
-                tx.send("node comment", {   header: 'Comment for ' + node.name, 
+                editor.tx.send("node comment", {   header: 'Comment for ' + node.name, 
                                             pos: newPos, 
                                             uid: node.uid, 
                                             text: node.prompt ?? '', 
@@ -14208,7 +14212,6 @@ const nodeClickHandling = {
     iconCtrlClick(view,icon, pos) {
 
         const node = this;
-        const tx = editor.tx;
 
         switch (icon.type) {
     
@@ -14216,7 +14219,7 @@ const nodeClickHandling = {
             case 'lock': {
 
                 // open the file if it points to an external model
-                if (node.link?.model?.arl && (node.link.model != editor.doc?.model)) tx.send('open document',node.link.model.arl);
+                if (node.link?.model?.arl && (node.link.model != editor.doc?.model)) editor.tx.send('open document',node.link.model.arl);
             }
             break
 
@@ -14229,7 +14232,7 @@ const nodeClickHandling = {
                 const arl = node.factory.arl ?? editor.doc.resolve('./index.js');
 
                 // request to open the file
-                if (arl) tx.send("open source file", {arl});
+                if (arl) editor.tx.send("open source file", {arl});
             }
             break
     
@@ -17071,7 +17074,7 @@ cook( raw ) {
     for (const widget of this.widgets) if (widget.wid && (widget.wid > this.widGenerator)) this.widGenerator = widget.wid;
 
     // if there are widgets with a wid of zero, correct this
-    for (const widget of this.widgets) if (widget.wid && (widget.wid == 0)) widget.wid = this.generateWid();
+    for (const widget of this.widgets) if (widget.wid == 0) widget.wid = this.generateWid();
 },
 
 cookPin(raw) {
@@ -23326,7 +23329,13 @@ function getEnclosingHandlerName(callExpression) {
     return null;
 }
 
-const SRC_DOC_VERSION = '0.2';
+var version = "0.3.2";
+var pckg = {
+	version: version};
+
+const PROFILE_VERSION = pckg.version;
+
+// const PROFILE_VERSION = '0.2';
 
 // The main function for the profile tool
 async function profile(argv = process.argv.slice(2)) {
@@ -23413,7 +23422,7 @@ async function profile(argv = process.argv.slice(2)) {
 
     // and write the output to that file
     const output = {
-        version: SRC_DOC_VERSION,
+        version: PROFILE_VERSION,
         generatedAt,
         entries: rxtx
     };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@vizualmodel/vmblu-cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
+  "schemaVersion": "0.8.3",
   "type": "module",
   "bin": {
     "vmblu": "bin/vmblu.js"

package/templates/0.8.3/profile.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "@vizual_model/cli/templates/0.8.3/profile.schema.json",
+  "title": "vmblu Source Documentation (grouped by node)",
+  "type": "object",
+  "required": ["version", "generatedAt", "entries"],
+  "properties": {
+    "version": { "type": "string" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Entry" }
+    }
+  },
+  "$defs": {
+    "Param": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "type", "description"],
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "description": { "type": "string" }
+      }
+    },
+    "Handle": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pin", "handler", "file", "line", "summary", "returns", "examples", "params"],
+      "properties": {
+        "pin": { "type": "string" },
+        "handler": { "type": "string" },
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "summary": { "type": "string" },
+        "returns": { "type": "string" },
+        "examples": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "params": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Param" }
+        }
+      }
+    },
+    "Transmit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pin", "file", "line"],
+      "properties": {
+        "pin": { "type": "string" },
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "Entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["node", "handles", "transmits"],
+      "properties": {
+        "node": { "type": "string" },
+        "handles": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Handle" }
+        },
+        "transmits": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Transmit" }
+        }
+      }
+    }
+  }
+}

package/templates/0.8.3/seed.md

@@ -0,0 +1,17 @@
+# Session Seed (System Prompt)
+
+vmblu (Vizual Model Blueprint) is a graphical editor that maintains a visual, runnable model of a software system.
+vmblu models software as interconnected nodes that pass messages via pins.
+
+The model has a well defined format described by a schema. An additional annex gives semantic background information about the schema.
+The parameter profiles of messages and where messages are received and sent in the actual source code, are stored in a second file, the profile file.
+The profile file is generated automatically by vmblu and is only to be consulted, not written, at the start of a project it does not yet exist
+
+You are an expert **architecture + code copilot** for **vmblu** .
+You can find the location of the model file, the model schema, the model annex, the profile file and the profile schema in the 'manifest.json' file of this project. Read these files.
+
+The location of all other files in the project can be found via the model file.
+
+Your job is to co-design the architecture and the software for the system.
+For modifications of the model, always follow the schema. 
+If the profile does not exist yet or does notcontain profile information it could be that the code for the node has not been written yet, this should not stop you from continuing.

package/templates/0.8.3/vmblu.annex.md

@@ -0,0 +1,136 @@
+# Annex A: Semantic Clarifications for vmblu v0.8
+
+This annex captures subtle semantic points that are not fully enforceable in the JSON Schema but are critical for correct usage of the vmblu format by both humans and LLMs.
+
+## A.1 Nodes
+
+A source node groups the functionality of a system that belongs logically together. A source node can represent a UI element, the access to a database, a login procedure, a 3D scene list etc.
+
+The name of a node should be meaningful and unique inside a group node.
+
+## A.2 Interface names and Pin names
+
+- Pins are grouped in **interfaces**
+- There can only be one anonymous interface (name is ""), this is acceptable for nodes that have only a few pins.
+- Group pins together into meaningful interfaces
+- It is good practice to start a pin name with the name of the interface separated by a period or hyphen.
+
+## A.3 Handlers
+
+Every **input** or **reply** pin corresponds to a message handler in the node implementation.
+
+The naming convention for a handler is as follows:
+
+- Handler name is `on<PinNameInCamelCase>`.  
+- Example:  
+  - Pin: `"name": "saveMessage", "kind": "input"`  
+  - Handler: `onSaveMessage(payload)`  
+
+This uniform convention ensures LLMs and the editor can always map pins to their corresponding handler.
+
+Do not return a value from a handler, it is ignored.
+
+## A.4 Request / Reply Semantics
+
+A Request/Reply connection allows to group a message and the response to that message in one exchange.
+
+- A **request pin** is an **output pin**.  
+  - It is used by the requester node to initiate a request with `tx.request('pinName', payload)`.  
+  - This function returns a **Promise** which resolves when the callee replies. The **Promise** is generated and managed by the runtime.
+
+- A **reply pin** is an **input pin** on the callee.  
+  - It receives the request payload and has a handler like any input pin.  
+  - Inside this handler, the callee must call `tx.reply(payload)` to respond to the requester.  
+  - The runtime delivers this reply on the backchannel and resolves the requester’s Promise.
+  - Note that the handler return value is ignored, optional async only to await internal work.
+  - If tx.reply is not called, the request promise will simply time out.
+
+- **Connections**:  
+  - Normally, `request` pins connect to `reply` pins.  
+  - It is also valid to connect a `request` pin to an `input` pin (e.g. for logging or monitoring), but in that case no reply is sent.
+
+  Typical use of request/reply
+
+  The requesting node issues a request and then waits for the reply
+  ```js
+  tx.request('pinName', payload).then ( replyPayload => {
+
+    // handle the reply from the other node
+    ...
+  }) 
+  ```
+
+  The receiving node has a handler for the request
+  ```js
+  onPinName(payloed) {
+    // does some processing
+    ...
+    // and replies to the requesting node
+    tx.reply(replyPayload)
+  }
+  ```
+
+## A.5 Factory Function Signature
+
+A source node references its implementation via a **factory** object (`path` + `function`).  
+The factory function is called by the runtime to create the node instance.
+
+The runtime will detect if the factory function is a generator function or a class name and will call the factory function in that case as follows: `new factoryFunction(...)`
+
+In order to let documentation tools find the handlers of a node, add a *node* JSdoc tag in the file where the handlers are defined.
+The tage remains valid until the end of the file or until a new node tag is defined.
+
+- Signature:  
+  ```js
+  /**
+   * @node node name
+   */
+  export function createMyNode( tx, sx ) { ... }
+  ```
+
+- tx: object exposing runtime message functions (send, request, reply).
+- sx: arbitrary initialization data supplied by the model. sx can be null.
+- rx: not passed to the node. Runtime-only directives; used by the runtime to decide how/where to host the node (e.g. worker thread, debug flags).
+
+## A.6 Dock Nodes and Drift
+
+- A dock node references another node defined in a different file via a link.
+- Pins and connections of the dock node are kept in the importing file.
+- If the external node definition changes, the editor highlights differences (“drift”) between the dock node and its linked definition.
+
+## A.7 Buses
+
+A bus simplifies routing:
+
+- Outputs connected to a bus are forwarded to inputs of the same name.
+- Buses do not introduce new message names; they only group routes.
+
+Buses are created in the editor by the user to improve the readability of the vmblu diagram.
+
+## A.8 Pads
+
+Pads are how group nodes expose their internal pins externally.
+If a connection omits the node in its address, it refers to a pad on the group itself.
+
+## A.9 Connections
+
+A connection is between pins or interfaces.
+
+For a connection between pins, the message flow is from 'src' to 'dst'. So 'src is either an ouput pin of a node or an input pin of the containing group node (a pad in the editor) and 'dst' is either an input pin of a node or an ouput pin of the containing group node.
+
+When connecting interfaces the *ouput pins* of the interface are connected the *input pins* with the same name, of the interface on the other node, and in the same way the *input pins* of the interface are connected to the *output pins* with the same name of the interface connected to on the other node. Not all pins have to be present in both interfaces.
+
+## A.10 AI Generation Guidelines
+
+For LLMs working with vmblu files:
+
+- Respect node and pin names — do not rename unless explicitly asked.
+- Connection rules — only connect compatible pins:
+
+    - output → input
+    - request → reply
+
+- Reply requirement — every new request pin should be connected to at least one reply pin.
+- Do not edit editor fields — they are for the graphical editor only.
+- When generating source code for the nodes in the vmblu file, only generate code for the nodes, the *main* function and node setup is generated directly from the vmblu file itself. 
+- When changing code for an application only change the code for the nodes, not the application file that was generated. That file will be re-generated by the editor.

package/templates/0.8.3/vmblu.schema.json

@@ -0,0 +1,268 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "@vizual_model/cli/templates/0.8.3/vmblu.schema.json",
+    "title": "vmblu Model (v0.8.2 draft)",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["header", "root"],
+    "properties": {
+        "header": { "$ref": "#/$defs/Header" },
+        "imports": {
+            "description": "List of vmblu files that are referenced in the model. Allows for faster loading.",
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+        },
+        "factories": {
+            "description": "List of files where the source code of the source nodes can be found. Used by the docgen tool.",
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+        },
+        "libraries": {
+            "description": "List of vmblu files from which the editor allows the user to select nodes in an easy way.",
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+        },
+        "root": { 
+            "description": "The starting point of the vmblu model. Every field named 'editor' is there only to let the editor display the model for the user.",
+            "$ref": "#/$defs/Node" 
+        }
+    },
+    "$defs": {
+        "Header": {
+            "description": "Contains meta information about the model. Used by the editor.",
+            "type": "object",
+            "properties": {
+                "version": { "type": "string" },
+                "created": { "type": "string", "format": "date-time"  },
+                "saved": { "type": "string", "format": "date-time"  },
+                "utc": { "type": "string", "format": "date-time" },
+                "style": { "type": "string" },
+                "runtime": { "type": "string" }
+            },
+            "additionalProperties": false,
+            "required": ["version", "created", "saved", "utc"]
+        },
+        "Node" : {
+            "description": "A node describes a component of a software system. Nodes communicate via messages. There are three types of nodes.",
+            "type": "object",
+            "properties": {
+                "kind": {"enum": ["source", "group", "dock"]},
+                "name": { "type": "string", "minLength": 1, "pattern": "^[^@]+$" },
+                "label": { "type": "string"},
+                "interfaces":{
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/Interface" }
+                },
+                "prompt": {"type": "string"},
+                "sx": { "$ref": "#/$defs/NodeInitialization" },
+                "rx": { "$ref": "#/$defs/RuntimeDirectives" }
+            },
+            "oneOf": [
+                { "$ref": "#/$defs/SourceNode" },
+                { "$ref": "#/$defs/GroupNode" },
+                { "$ref": "#/$defs/DockNode" }
+            ],
+            "required": ["kind", "name"],
+            "unevaluatedProperties": false
+        },
+        "SourceNode": {
+            "description": "A source node has an implementation in source code.",
+            "type": "object",
+            "properties": {
+                "kind": {"const": "source"},
+                "factory": {
+                    "type": "object",
+                    "properties": {
+                        "path": { "type": "string", "minLength": 1 },
+                        "function": { "type": "string", "minLength": 1 }
+                    },
+                    "required": ["name"]
+                },
+                "editor": { "$ref": "#/$defs/EditorNode" }
+            }
+        },
+        "GroupNode": {
+            "description": "A group node consists of other connected nodes. It allows to build modular models.",
+            "type": "object",
+            "properties": {
+                "kind": {"const": "group"},
+                "nodes": { 
+                    "type": "array", 
+                    "items": { "$ref": "#/$defs/Node" } 
+                },
+                "connections": { 
+                    "type": "array", 
+                    "items": { "$ref": "#/$defs/Connection" } 
+                },
+                "editor": { "$ref": "#/$defs/EditorGroupNode" }
+            }
+        },
+        "DockNode": {
+            "description": "A dock node is a placeholder for a node that is defined in another file, specified in the link field.",
+            "type": "object",
+            "properties": {
+                "kind": {"const": "dock"},
+                "link": {
+                    "type": "object",
+                    "required": ["name"],
+                    "properties": {
+                        "path": { "type": "string", "minLength": 1 },
+                        "node": { "type": "string", "minLength": 1, "pattern": "^[^@]+$" }
+                    }
+                },
+                "editor": { "$ref": "#/$defs/EditorNode" }
+            }
+        },
+        "Interface": {
+            "description": "An interface groups a number of pins of a node.",
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+                "name": { "type": "string", "pattern": "^[^@]+$" },
+                "pins": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/Pin" }
+                },
+                "editor" : {
+                    "type": "object",
+                    "required": ["id"],
+                    "properties": {
+                        "id": {"type": "integer"}
+                    }
+                }
+            }
+        },
+        "Pin": {
+            "description": "A node can receive or send a message via a pin. Inputs connect to outputs and requests connect to replies.",
+            "type": "object",
+            "required": ["name", "kind"],
+            "properties": {
+                "name": { "type": "string", "minLength": 1, "pattern": "^[^@]+$"},
+                "kind": { "enum": ["input", "output", "request", "reply"] },
+                "editor": {"$ref": "#/$defs/EditorPin"}
+            }
+        },
+        "Connection": {
+            "description": "A connection can be made between two pins or between two interfaces. For pins the message flow is from 'src' to 'dst', so 'src' is either an output pin of a node or an input pin of the containing group node and 'dst' is either an input pin of a node or an output pin of the containing group node.",
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["from", "to"],
+            "properties": {
+                "src":   { "$ref": "#/$defs/Address" },
+                "dst":     { "$ref": "#/$defs/Address" }
+            }
+        },
+        "Address": {
+            "description": "The format for the address of a pin or interface. If node is omitted the node is the containing group node, and the pin or interface are represented as pads.",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "node":      { "type": "string", "minLength": 1, "pattern": "^[^@]+$" },
+                "pin":       { "type": "string", "minLength": 1, "pattern": "^[^@]+$" },
+                "interface": { "type": "string", "minLength": 1, "pattern": "^[^@]+$" }
+            },
+            "oneOf": [
+                { "required": ["pin"] },
+                { "required": ["interface"] }
+            ]
+        },
+        "NodeInitialization": {
+            "description": "Node-defined initialization data passed to the node at creation time. Shape is entirely up to the node designer.",
+            "type": "object"
+        },
+        "RuntimeDirectives": {
+            "description": "Runtime-defined creation/hosting directives. Shape is determined by the runtime (e.g., host=worker, debug=true).",
+            "type": "object",
+            "properties": {
+            "$contract": {
+                "type": "string",
+                "description": "Optional contract/version tag or URI (e.g., 'vmblu.rx/v1'). Lets tools know which directive dialect to expect."
+            }
+            },
+            "examples": [
+                { "$contract": "vmblu.rx/v1", "host": "worker", "debug": true, "logLevel": "info" }
+            ]
+        },
+        "EditorNode": {
+            "description": "Allows the editor to position and draw the node.",
+            "type": "object",
+            "properties": {
+                "rect": { "type": "string" }
+            }
+        },
+        "EditorGroupNode": {
+            "description": "Allows the editor to position and draw the content of a group node in a dedicated view.",
+            "type": "object",
+            "properties": {
+                "rect": { "type": "string" },
+                "view": {
+                    "type": "object",
+                    "required": ["rect"],
+                    "properties": {
+                        "state": {"enum": ["open", "closed"]},
+                        "rect": { "type": "string" },
+                        "transform": { "type": "string" }
+                    }
+                },
+                "buses": {
+                    "type": "array",
+                    "items": {"$ref": "#/$defs/EditorBus"}
+                },
+                "routes": {
+                    "type": "array",
+                    "items": {"$ref": "#/$defs/EditorRoute"}
+                }
+            }
+        },
+        "EditorPin" : {
+            "description": "Allows the editor to draw the pin in the node it belongs to.",
+            "type": "object",
+            "properties": {
+                "id": { "type": "integer" },
+                "align": { "enum": ["left", "right"]},
+                "pad": {
+                    "type": "object",
+                    "required": ["rect"],
+                    "properties": {
+                        "rect": { "type": "string" },
+                        "align": { "enum": ["left", "right"]}
+                    }
+                }
+            }
+        },
+        "EditorBus": {
+            "description": "A bus is an easy way to route multiple connections between nodes. A bus can also do some routing via a filter.",
+            "type": "object",
+            "required": ["kind","name"],
+            "properties": {
+                "kind": { "enum": ["busbar", "cable"]},
+                "name": { "type": "string", "minLength": 1, "pattern": "^[^@]+$" },
+                "filter": { "$ref": "#/$defs/Filter" },
+                "start" : { "type": "string"},
+                "wire": { "type": "string" }
+            }
+        },
+        "Filter": {
+            "description": "A bus uses a filter to route messages based on message parameters. A filter is a software routine.",
+            "type": "object",
+            "required": ["path", "function"],
+            "properties": {
+                "path": { "type": "string", "minLength": 1 },
+                "function": { "type": "string", "minLength": 1 }
+            }
+        },
+        "EditorRoute": {
+            "description": "A route is how the editor shows the connections between pins or interfaces.The from-string and to-string start with either pin, bus, pad or itf",
+            "type": "object",
+            "properties": {
+                "from":{ "type": "string" },
+                "to":{ "type": "string" },
+                "wire": { "type": "string" }
+            }
+        }
+    }
+}
+