@synergenius/flow-weaver 0.10.0 → 0.10.2

package/README.md

@@ -1,8 +1,12 @@
 # @synergenius/flow-weaver
 
-[![npm version](https://img.shields.io/npm/v/@synergenius/flow-weaver.svg)](https://www.npmjs.com/package/@synergenius/flow-weaver)
-[![License: Flow Weaver Library License](https://img.shields.io/badge/License-Flow%20Weaver%20Library-blue.svg)](./LICENSE)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/@synergenius/flow-weaver?style=flat)](https://www.npmjs.com/package/@synergenius/flow-weaver)
+[![npm downloads](https://img.shields.io/npm/dw/@synergenius/flow-weaver?style=flat)](https://www.npmjs.com/package/@synergenius/flow-weaver)
+[![CI](https://img.shields.io/github/actions/workflow/status/synergenius-fw/flow-weaver/ci.yml?branch=main&style=flat)](https://github.com/synergenius-fw/flow-weaver/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/moraispgsi/305430ef59a51d0a58eb61fefdfbe634/raw/flow-weaver-test-count.json&style=flat)](https://github.com/synergenius-fw/flow-weaver/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/synergenius-fw/flow-weaver?style=flat)](https://codecov.io/gh/synergenius-fw/flow-weaver)
+[![License: Flow Weaver Library License](https://img.shields.io/badge/License-Flow%20Weaver%20Library-blue?style=flat)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green?style=flat)](https://nodejs.org)
 
 **Build AI agent workflows visually. Ship them as your own code.**
 
@@ -10,11 +14,17 @@ Design agent workflows in the Studio, in TypeScript, or let AI build them for yo
 
 ## Three Ways to Build
 
-**Studio.** Drag, drop, connect. The visual editor renders your workflow as an interactive graph with bidirectional sync: canvas changes write code, code changes update the canvas. 80+ plugins handle rendering, state, minimap, undo/redo, and more.
+**Studio.**
+A unified environment that combines a full code editor with a visual graph builder. You can write and refactor workflows directly in code or compose them visually on the canvas. Both representations stay synchronized at all times. Editing either one updates the other instantly, so you can move between abstraction levels without friction.
 
-**TypeScript.** Annotate plain functions with JSDoc tags. The compiler turns them into executable workflow graphs with full type safety, IDE autocomplete, and compile-time validation. No YAML, no JSON configs.
+**TypeScript.**
+Define workflows in plain TypeScript by annotating functions with JSDoc. The compiler derives an executable workflow graph with static typing and compile-time validation.
+There is no YAML, no JSON configuration, and no runtime layer.
+No lock-in. Remove the annotations and you keep a clean, readable TypeScript file with zero dependencies.
 
-**AI Agents.** Connect Claude Code, Cursor, or OpenClaw and they scaffold, validate, and ship workflows using 30+ MCP tools. The agent reads validation errors, fixes issues, and re-validates until the workflow compiles clean. The development loop (steps 1-4 are fully autonomous):
+**AI Agents.**
+Connect Claude Code, Cursor, or OpenClaw to design and ship workflows. Agents scaffold implementations, run the compiler, interpret validation errors, apply corrections, and repeat the process until the workflow compiles successfully.
+With more than 30 MCP tools available, the entire build loop can run autonomously.
 
 1. **Agent creates**: scaffolds from templates, builds from a model, or writes from scratch
 2. **Compiler validates**: 15+ validation passes catch missing connections, type mismatches, unreachable paths

package/dist/cli/flow-weaver.mjs

@@ -16881,6 +16881,121 @@ var require_browser = __commonJS({
   }
 });
 
+// node_modules/has-flag/index.js
+var require_has_flag = __commonJS({
+  "node_modules/has-flag/index.js"(exports2, module2) {
+    "use strict";
+    module2.exports = (flag, argv = process.argv) => {
+      const prefix = flag.startsWith("-") ? "" : flag.length === 1 ? "-" : "--";
+      const position = argv.indexOf(prefix + flag);
+      const terminatorPosition = argv.indexOf("--");
+      return position !== -1 && (terminatorPosition === -1 || position < terminatorPosition);
+    };
+  }
+});
+
+// node_modules/supports-color/index.js
+var require_supports_color = __commonJS({
+  "node_modules/supports-color/index.js"(exports2, module2) {
+    "use strict";
+    var os3 = __require("os");
+    var tty = __require("tty");
+    var hasFlag = require_has_flag();
+    var { env } = process;
+    var forceColor;
+    if (hasFlag("no-color") || hasFlag("no-colors") || hasFlag("color=false") || hasFlag("color=never")) {
+      forceColor = 0;
+    } else if (hasFlag("color") || hasFlag("colors") || hasFlag("color=true") || hasFlag("color=always")) {
+      forceColor = 1;
+    }
+    if ("FORCE_COLOR" in env) {
+      if (env.FORCE_COLOR === "true") {
+        forceColor = 1;
+      } else if (env.FORCE_COLOR === "false") {
+        forceColor = 0;
+      } else {
+        forceColor = env.FORCE_COLOR.length === 0 ? 1 : Math.min(parseInt(env.FORCE_COLOR, 10), 3);
+      }
+    }
+    function translateLevel(level) {
+      if (level === 0) {
+        return false;
+      }
+      return {
+        level,
+        hasBasic: true,
+        has256: level >= 2,
+        has16m: level >= 3
+      };
+    }
+    function supportsColor(haveStream, streamIsTTY) {
+      if (forceColor === 0) {
+        return 0;
+      }
+      if (hasFlag("color=16m") || hasFlag("color=full") || hasFlag("color=truecolor")) {
+        return 3;
+      }
+      if (hasFlag("color=256")) {
+        return 2;
+      }
+      if (haveStream && !streamIsTTY && forceColor === void 0) {
+        return 0;
+      }
+      const min = forceColor || 0;
+      if (env.TERM === "dumb") {
+        return min;
+      }
+      if (process.platform === "win32") {
+        const osRelease = os3.release().split(".");
+        if (Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) {
+          return Number(osRelease[2]) >= 14931 ? 3 : 2;
+        }
+        return 1;
+      }
+      if ("CI" in env) {
+        if (["TRAVIS", "CIRCLECI", "APPVEYOR", "GITLAB_CI", "GITHUB_ACTIONS", "BUILDKITE"].some((sign) => sign in env) || env.CI_NAME === "codeship") {
+          return 1;
+        }
+        return min;
+      }
+      if ("TEAMCITY_VERSION" in env) {
+        return /^(9\.(0*[1-9]\d*)\.|\d{2,}\.)/.test(env.TEAMCITY_VERSION) ? 1 : 0;
+      }
+      if (env.COLORTERM === "truecolor") {
+        return 3;
+      }
+      if ("TERM_PROGRAM" in env) {
+        const version3 = parseInt((env.TERM_PROGRAM_VERSION || "").split(".")[0], 10);
+        switch (env.TERM_PROGRAM) {
+          case "iTerm.app":
+            return version3 >= 3 ? 3 : 2;
+          case "Apple_Terminal":
+            return 2;
+        }
+      }
+      if (/-256(color)?$/i.test(env.TERM)) {
+        return 2;
+      }
+      if (/^screen|^xterm|^vt100|^vt220|^rxvt|color|ansi|cygwin|linux/i.test(env.TERM)) {
+        return 1;
+      }
+      if ("COLORTERM" in env) {
+        return 1;
+      }
+      return min;
+    }
+    function getSupportLevel(stream2) {
+      const level = supportsColor(stream2, stream2 && stream2.isTTY);
+      return translateLevel(level);
+    }
+    module2.exports = {
+      supportsColor: getSupportLevel,
+      stdout: translateLevel(supportsColor(true, tty.isatty(1))),
+      stderr: translateLevel(supportsColor(true, tty.isatty(2)))
+    };
+  }
+});
+
 // node_modules/debug/src/node.js
 var require_node = __commonJS({
   "node_modules/debug/src/node.js"(exports2, module2) {
@@ -16899,7 +17014,7 @@ var require_node = __commonJS({
     );
     exports2.colors = [6, 2, 3, 4, 5, 1];
     try {
-      const supportsColor = __require("supports-color");
+      const supportsColor = require_supports_color();
       if (supportsColor && (supportsColor.stderr || supportsColor).level >= 2) {
         exports2.colors = [
           20,
@@ -61065,12 +61180,12 @@ function renderConnection(parts2, conn, gradIndex) {
     `  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`
   );
 }
-function renderScopeConnection(parts2, conn, allConnections) {
+function renderScopeConnection(parts2, conn, allConnections, parentNodeId) {
   const gradIndex = allConnections.indexOf(conn);
   if (gradIndex < 0) return;
   const dashAttr = conn.isStepConnection ? "" : ' stroke-dasharray="8 4"';
   parts2.push(
-    `    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`
+    `    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input" data-scope="${escapeXml(parentNodeId)}"/>`
   );
 }
 function renderNodeBody(parts2, node, theme, indent) {
@@ -61114,7 +61229,7 @@ function renderScopedContent(parts2, node, theme, themeName, allConnections) {
     `    <rect x="${scopeX}" y="${scopeY}" width="${scopeW}" height="${scopeH}" rx="4" fill="none" stroke="${theme.scopeAreaStroke}" stroke-width="1" stroke-dasharray="4 2" opacity="0.5"/>`
   );
   for (const conn of node.scopeConnections ?? []) {
-    renderScopeConnection(parts2, conn, allConnections);
+    renderScopeConnection(parts2, conn, allConnections, node.id);
   }
   if (scopePorts) {
     renderPortDots(parts2, node.id, scopePorts.inputs, scopePorts.outputs, themeName);
@@ -61351,6 +61466,21 @@ path[data-source].port-hover { opacity: 1; }
   border-radius: 3px; font-family: 'SF Mono', 'Fira Code', monospace;
   font-size: 12px; background: rgba(255,255,255,0.1);
 }
+
+/* Studio nudge toast */
+#studio-hint {
+  position: fixed; bottom: 60px; left: 50%;
+  transform: translateX(-50%);
+  background: ${surfaceMain}; border: 1px solid ${borderSubtle};
+  padding: 8px 16px; border-radius: 8px;
+  font-size: 13px; color: ${textMed};
+  box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+  z-index: 20; opacity: 0; transition: opacity 0.4s;
+  pointer-events: none;
+}
+#studio-hint.visible { opacity: 1; pointer-events: auto; }
+#studio-hint a { color: ${brandAccent}; text-decoration: none; font-weight: 600; }
+#studio-hint a:hover { text-decoration: underline; }
 </style>
 </head>
 <body>
@@ -61374,6 +61504,12 @@ path[data-source].port-hover { opacity: 1; }
       <path d="M1 5h12M1 9h12M5 1v12M9 1v12" opacity="0.4"/>
     </svg>
   </button>
+  <button class="ctrl-btn" id="btn-reset" title="Reset layout" aria-label="Reset layout">
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" stroke-width="1.5">
+      <path d="M1.5 2v3.5h3.5"/>
+      <path d="M2.1 8.5a5 5 0 1 0 .9-4L1.5 5.5"/>
+    </svg>
+  </button>
 </div>
 <div id="info-panel">
   <h3 id="info-title"></h3>
@@ -61384,6 +61520,7 @@ path[data-source].port-hover { opacity: 1; }
   <span>Flow Weaver</span>
 </a>
 <div id="scroll-hint">Use <kbd id="mod-key">Ctrl</kbd> + scroll to zoom</div>
+<div id="studio-hint">Like rearranging? <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> saves your layouts.</div>
 <script>
 (function() {
   'use strict';
@@ -61396,6 +61533,7 @@ path[data-source].port-hover { opacity: 1; }
   var infoTitle = document.getElementById('info-title');
   var infoBody = document.getElementById('info-body');
   var scrollHint = document.getElementById('scroll-hint');
+  var studioHint = document.getElementById('studio-hint');
 
   // Parse the original viewBox (diagram bounding box)
   var vbParts = '${viewBox}'.split(/\\s+/).map(Number);
@@ -61467,6 +61605,17 @@ path[data-source].port-hover { opacity: 1; }
 
   // ---- Pan (drag) + Node drag ----
   var draggedNodeId = null, dragNodeStart = null, didDragNode = false;
+  var dragCount = 0, nudgeIndex = 0, nudgeTimer = null;
+  var nudgeMessages = [
+    'Like rearranging? <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> saves your layouts.',
+    'Changes here are temporary. <a href="https://flowweaver.ai" target="_blank" rel="noopener">Try the Studio</a> to keep them.',
+    'Want to collaborate? <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> has real-time sharing.',
+    'Build and deploy from the cloud with <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a>.',
+    'This viewer is read-only. <a href="https://flowweaver.ai" target="_blank" rel="noopener">Build workflows</a> in the Studio.',
+    'Version history, diff viewer, rollbacks. All in <a href="https://flowweaver.ai" target="_blank" rel="noopener">the Studio</a>.',
+    'Debug workflows step by step in <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a>.',
+    'Ship faster. <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> runs your workflows in the cloud.'
+  ];
 
   canvas.addEventListener('pointerdown', function(e) {
     if (e.button !== 0) return;
@@ -61525,6 +61674,18 @@ path[data-source].port-hover { opacity: 1; }
   });
 
   function endDrag() {
+    if (didDragNode) {
+      dragCount++;
+      var threshold = nudgeIndex === 0 ? 3 : 5;
+      if (dragCount >= threshold) {
+        dragCount = 0;
+        studioHint.innerHTML = nudgeMessages[nudgeIndex % nudgeMessages.length];
+        nudgeIndex++;
+        studioHint.classList.add('visible');
+        clearTimeout(nudgeTimer);
+        nudgeTimer = setTimeout(function() { studioHint.classList.remove('visible'); }, 5000);
+      }
+    }
     pointerDown = false;
     draggedNodeId = null;
     canvas.classList.remove('dragging');
@@ -61616,9 +61777,41 @@ path[data-source].port-hover { opacity: 1; }
   var connIndex = [];
   content.querySelectorAll('path[data-source]').forEach(function(p) {
     var src = p.getAttribute('data-source'), tgt = p.getAttribute('data-target');
-    connIndex.push({ el: p, src: src, tgt: tgt, srcNode: src.split('.')[0], tgtNode: tgt.split('.')[0] });
+    connIndex.push({ el: p, src: src, tgt: tgt, srcNode: src.split('.')[0], tgtNode: tgt.split('.')[0], scopeOf: p.getAttribute('data-scope') || null });
   });
 
+  // Snapshot of original port positions for reset
+  var origPortPositions = {};
+  for (var pid in portPositions) {
+    origPortPositions[pid] = { cx: portPositions[pid].cx, cy: portPositions[pid].cy };
+  }
+
+  function resetLayout() {
+    for (var nid in nodeOffsets) {
+      var esc = CSS.escape(nid);
+      var nodeG = content.querySelector('.nodes [data-node-id="' + esc + '"]');
+      if (nodeG) nodeG.removeAttribute('transform');
+      var labelG = content.querySelector('[data-label-for="' + esc + '"]');
+      if (labelG) labelG.removeAttribute('transform');
+      allLabelIds.forEach(function(id) {
+        if (id.indexOf(nid + '.') === 0) {
+          var el = labelMap[id];
+          if (el) el.removeAttribute('transform');
+        }
+      });
+    }
+    nodeOffsets = {};
+    for (var pid in origPortPositions) {
+      portPositions[pid] = { cx: origPortPositions[pid].cx, cy: origPortPositions[pid].cy };
+    }
+    connIndex.forEach(function(c) {
+      var sp = portPositions[c.src], tp = portPositions[c.tgt];
+      if (sp && tp) c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+    });
+    fitToView();
+  }
+  document.getElementById('btn-reset').addEventListener('click', resetLayout);
+
   // ---- Node drag: moveNode ----
   function moveNode(nodeId, dx, dy) {
     if (!nodeOffsets[nodeId]) nodeOffsets[nodeId] = { dx: 0, dy: 0 };
@@ -61626,9 +61819,18 @@ path[data-source].port-hover { opacity: 1; }
     off.dx += dx; off.dy += dy;
     var tr = 'translate(' + off.dx + ',' + off.dy + ')';
 
-    // Move node group
+    // Move node group (if nested inside a scoped parent, subtract parent offset)
     var nodeG = content.querySelector('.nodes [data-node-id="' + CSS.escape(nodeId) + '"]');
-    if (nodeG) nodeG.setAttribute('transform', tr);
+    if (nodeG) {
+      var parentNodeG = nodeG.parentElement ? nodeG.parentElement.closest('[data-node-id]') : null;
+      if (parentNodeG) {
+        var parentId = parentNodeG.getAttribute('data-node-id');
+        var parentOff = nodeOffsets[parentId] || { dx: 0, dy: 0 };
+        nodeG.setAttribute('transform', 'translate(' + (off.dx - parentOff.dx) + ',' + (off.dy - parentOff.dy) + ')');
+      } else {
+        nodeG.setAttribute('transform', tr);
+      }
+    }
 
     // Move label
     var labelG = content.querySelector('[data-label-for="' + CSS.escape(nodeId) + '"]');
@@ -61675,11 +61877,20 @@ path[data-source].port-hover { opacity: 1; }
       });
     }
 
-    // Recalculate affected connection paths
+    // Recalculate affected connection paths (skip scope connections when parent is dragged \u2014 they move with the group transform)
     connIndex.forEach(function(c) {
+      if (c.scopeOf === nodeId) return;
       if (c.srcNode === nodeId || c.tgtNode === nodeId) {
         var sp = portPositions[c.src], tp = portPositions[c.tgt];
-        if (sp && tp) c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+        if (sp && tp) {
+          if (c.scopeOf) {
+            // Scope connection paths live inside the parent group; use parent-local coords
+            var pOff = nodeOffsets[c.scopeOf] || { dx: 0, dy: 0 };
+            c.el.setAttribute('d', computeConnectionPath(sp.cx - pOff.dx, sp.cy - pOff.dy, tp.cx - pOff.dx, tp.cy - pOff.dy));
+          } else {
+            c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+          }
+        }
       }
       if (nodeG) {
         var children = nodeG.querySelectorAll(':scope > g[data-node-id]');
@@ -61687,7 +61898,14 @@ path[data-source].port-hover { opacity: 1; }
           var childId = childG.getAttribute('data-node-id');
           if (c.srcNode === childId || c.tgtNode === childId) {
             var sp = portPositions[c.src], tp = portPositions[c.tgt];
-            if (sp && tp) c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+            if (sp && tp) {
+              if (c.scopeOf) {
+                var pOff = nodeOffsets[c.scopeOf] || { dx: 0, dy: 0 };
+                c.el.setAttribute('d', computeConnectionPath(sp.cx - pOff.dx, sp.cy - pOff.dy, tp.cx - pOff.dx, tp.cy - pOff.dy));
+              } else {
+                c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+              }
+            }
           }
         });
       }
@@ -96512,7 +96730,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.10.0" : "0.0.0-dev";
+var version2 = true ? "0.10.2" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").version(version2, "-v, --version", "Output the current version");
 program2.configureOutput({

package/dist/diagram/html-viewer.js

@@ -170,6 +170,21 @@ path[data-source].port-hover { opacity: 1; }
   border-radius: 3px; font-family: 'SF Mono', 'Fira Code', monospace;
   font-size: 12px; background: rgba(255,255,255,0.1);
 }
+
+/* Studio nudge toast */
+#studio-hint {
+  position: fixed; bottom: 60px; left: 50%;
+  transform: translateX(-50%);
+  background: ${surfaceMain}; border: 1px solid ${borderSubtle};
+  padding: 8px 16px; border-radius: 8px;
+  font-size: 13px; color: ${textMed};
+  box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+  z-index: 20; opacity: 0; transition: opacity 0.4s;
+  pointer-events: none;
+}
+#studio-hint.visible { opacity: 1; pointer-events: auto; }
+#studio-hint a { color: ${brandAccent}; text-decoration: none; font-weight: 600; }
+#studio-hint a:hover { text-decoration: underline; }
 </style>
 </head>
 <body>
@@ -193,6 +208,12 @@ path[data-source].port-hover { opacity: 1; }
       <path d="M1 5h12M1 9h12M5 1v12M9 1v12" opacity="0.4"/>
     </svg>
   </button>
+  <button class="ctrl-btn" id="btn-reset" title="Reset layout" aria-label="Reset layout">
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" stroke-width="1.5">
+      <path d="M1.5 2v3.5h3.5"/>
+      <path d="M2.1 8.5a5 5 0 1 0 .9-4L1.5 5.5"/>
+    </svg>
+  </button>
 </div>
 <div id="info-panel">
   <h3 id="info-title"></h3>
@@ -203,6 +224,7 @@ path[data-source].port-hover { opacity: 1; }
   <span>Flow Weaver</span>
 </a>
 <div id="scroll-hint">Use <kbd id="mod-key">Ctrl</kbd> + scroll to zoom</div>
+<div id="studio-hint">Like rearranging? <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> saves your layouts.</div>
 <script>
 (function() {
   'use strict';
@@ -215,6 +237,7 @@ path[data-source].port-hover { opacity: 1; }
   var infoTitle = document.getElementById('info-title');
   var infoBody = document.getElementById('info-body');
   var scrollHint = document.getElementById('scroll-hint');
+  var studioHint = document.getElementById('studio-hint');
 
   // Parse the original viewBox (diagram bounding box)
   var vbParts = '${viewBox}'.split(/\\s+/).map(Number);
@@ -286,6 +309,17 @@ path[data-source].port-hover { opacity: 1; }
 
   // ---- Pan (drag) + Node drag ----
   var draggedNodeId = null, dragNodeStart = null, didDragNode = false;
+  var dragCount = 0, nudgeIndex = 0, nudgeTimer = null;
+  var nudgeMessages = [
+    'Like rearranging? <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> saves your layouts.',
+    'Changes here are temporary. <a href="https://flowweaver.ai" target="_blank" rel="noopener">Try the Studio</a> to keep them.',
+    'Want to collaborate? <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> has real-time sharing.',
+    'Build and deploy from the cloud with <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a>.',
+    'This viewer is read-only. <a href="https://flowweaver.ai" target="_blank" rel="noopener">Build workflows</a> in the Studio.',
+    'Version history, diff viewer, rollbacks. All in <a href="https://flowweaver.ai" target="_blank" rel="noopener">the Studio</a>.',
+    'Debug workflows step by step in <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a>.',
+    'Ship faster. <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> runs your workflows in the cloud.'
+  ];
 
   canvas.addEventListener('pointerdown', function(e) {
     if (e.button !== 0) return;
@@ -344,6 +378,18 @@ path[data-source].port-hover { opacity: 1; }
   });
 
   function endDrag() {
+    if (didDragNode) {
+      dragCount++;
+      var threshold = nudgeIndex === 0 ? 3 : 5;
+      if (dragCount >= threshold) {
+        dragCount = 0;
+        studioHint.innerHTML = nudgeMessages[nudgeIndex % nudgeMessages.length];
+        nudgeIndex++;
+        studioHint.classList.add('visible');
+        clearTimeout(nudgeTimer);
+        nudgeTimer = setTimeout(function() { studioHint.classList.remove('visible'); }, 5000);
+      }
+    }
     pointerDown = false;
     draggedNodeId = null;
     canvas.classList.remove('dragging');
@@ -435,9 +481,41 @@ path[data-source].port-hover { opacity: 1; }
   var connIndex = [];
   content.querySelectorAll('path[data-source]').forEach(function(p) {
     var src = p.getAttribute('data-source'), tgt = p.getAttribute('data-target');
-    connIndex.push({ el: p, src: src, tgt: tgt, srcNode: src.split('.')[0], tgtNode: tgt.split('.')[0] });
+    connIndex.push({ el: p, src: src, tgt: tgt, srcNode: src.split('.')[0], tgtNode: tgt.split('.')[0], scopeOf: p.getAttribute('data-scope') || null });
   });
 
+  // Snapshot of original port positions for reset
+  var origPortPositions = {};
+  for (var pid in portPositions) {
+    origPortPositions[pid] = { cx: portPositions[pid].cx, cy: portPositions[pid].cy };
+  }
+
+  function resetLayout() {
+    for (var nid in nodeOffsets) {
+      var esc = CSS.escape(nid);
+      var nodeG = content.querySelector('.nodes [data-node-id="' + esc + '"]');
+      if (nodeG) nodeG.removeAttribute('transform');
+      var labelG = content.querySelector('[data-label-for="' + esc + '"]');
+      if (labelG) labelG.removeAttribute('transform');
+      allLabelIds.forEach(function(id) {
+        if (id.indexOf(nid + '.') === 0) {
+          var el = labelMap[id];
+          if (el) el.removeAttribute('transform');
+        }
+      });
+    }
+    nodeOffsets = {};
+    for (var pid in origPortPositions) {
+      portPositions[pid] = { cx: origPortPositions[pid].cx, cy: origPortPositions[pid].cy };
+    }
+    connIndex.forEach(function(c) {
+      var sp = portPositions[c.src], tp = portPositions[c.tgt];
+      if (sp && tp) c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+    });
+    fitToView();
+  }
+  document.getElementById('btn-reset').addEventListener('click', resetLayout);
+
   // ---- Node drag: moveNode ----
   function moveNode(nodeId, dx, dy) {
     if (!nodeOffsets[nodeId]) nodeOffsets[nodeId] = { dx: 0, dy: 0 };
@@ -445,9 +523,18 @@ path[data-source].port-hover { opacity: 1; }
     off.dx += dx; off.dy += dy;
     var tr = 'translate(' + off.dx + ',' + off.dy + ')';
 
-    // Move node group
+    // Move node group (if nested inside a scoped parent, subtract parent offset)
     var nodeG = content.querySelector('.nodes [data-node-id="' + CSS.escape(nodeId) + '"]');
-    if (nodeG) nodeG.setAttribute('transform', tr);
+    if (nodeG) {
+      var parentNodeG = nodeG.parentElement ? nodeG.parentElement.closest('[data-node-id]') : null;
+      if (parentNodeG) {
+        var parentId = parentNodeG.getAttribute('data-node-id');
+        var parentOff = nodeOffsets[parentId] || { dx: 0, dy: 0 };
+        nodeG.setAttribute('transform', 'translate(' + (off.dx - parentOff.dx) + ',' + (off.dy - parentOff.dy) + ')');
+      } else {
+        nodeG.setAttribute('transform', tr);
+      }
+    }
 
     // Move label
     var labelG = content.querySelector('[data-label-for="' + CSS.escape(nodeId) + '"]');
@@ -494,11 +581,20 @@ path[data-source].port-hover { opacity: 1; }
       });
     }
 
-    // Recalculate affected connection paths
+    // Recalculate affected connection paths (skip scope connections when parent is dragged — they move with the group transform)
     connIndex.forEach(function(c) {
+      if (c.scopeOf === nodeId) return;
       if (c.srcNode === nodeId || c.tgtNode === nodeId) {
         var sp = portPositions[c.src], tp = portPositions[c.tgt];
-        if (sp && tp) c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+        if (sp && tp) {
+          if (c.scopeOf) {
+            // Scope connection paths live inside the parent group; use parent-local coords
+            var pOff = nodeOffsets[c.scopeOf] || { dx: 0, dy: 0 };
+            c.el.setAttribute('d', computeConnectionPath(sp.cx - pOff.dx, sp.cy - pOff.dy, tp.cx - pOff.dx, tp.cy - pOff.dy));
+          } else {
+            c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+          }
+        }
       }
       if (nodeG) {
         var children = nodeG.querySelectorAll(':scope > g[data-node-id]');
@@ -506,7 +602,14 @@ path[data-source].port-hover { opacity: 1; }
           var childId = childG.getAttribute('data-node-id');
           if (c.srcNode === childId || c.tgtNode === childId) {
             var sp = portPositions[c.src], tp = portPositions[c.tgt];
-            if (sp && tp) c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+            if (sp && tp) {
+              if (c.scopeOf) {
+                var pOff = nodeOffsets[c.scopeOf] || { dx: 0, dy: 0 };
+                c.el.setAttribute('d', computeConnectionPath(sp.cx - pOff.dx, sp.cy - pOff.dy, tp.cx - pOff.dx, tp.cy - pOff.dy));
+              } else {
+                c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+              }
+            }
           }
         });
       }

package/dist/diagram/renderer.js

@@ -100,12 +100,12 @@ function renderConnection(parts, conn, gradIndex) {
     const dashAttr = conn.isStepConnection ? '' : ' stroke-dasharray="8 4"';
     parts.push(`  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`);
 }
-function renderScopeConnection(parts, conn, allConnections) {
+function renderScopeConnection(parts, conn, allConnections, parentNodeId) {
     const gradIndex = allConnections.indexOf(conn);
     if (gradIndex < 0)
         return;
     const dashAttr = conn.isStepConnection ? '' : ' stroke-dasharray="8 4"';
-    parts.push(`    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`);
+    parts.push(`    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input" data-scope="${escapeXml(parentNodeId)}"/>`);
 }
 // ---- Node rendering ----
 /** Render node body rect + icon */
@@ -147,7 +147,7 @@ function renderScopedContent(parts, node, theme, themeName, allConnections) {
     parts.push(`    <rect x="${scopeX}" y="${scopeY}" width="${scopeW}" height="${scopeH}" rx="4" fill="none" stroke="${theme.scopeAreaStroke}" stroke-width="1" stroke-dasharray="4 2" opacity="0.5"/>`);
     // Scope connections (before ports so ports appear on top)
     for (const conn of node.scopeConnections ?? []) {
-        renderScopeConnection(parts, conn, allConnections);
+        renderScopeConnection(parts, conn, allConnections, node.id);
     }
     // Scope port dots (before children so dots sit on top of connections)
     if (scopePorts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",
@@ -145,6 +145,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.11.0",
     "@types/react": "^19.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "esbuild": "^0.27.2",
     "prettier": "^3.1.1",
     "rimraf": "6.1.2",