@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/diagram/labels.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The name a person reads on a step.
+ *
+ * One rule, shared by the console, the process model, the brief and the
+ * SVG: an explicit instance label, else the node type's own label, else --
+ * for a generic built-in such as `waitForAgent`, whose function name says
+ * nothing about this step -- the instance id as words, else the type's
+ * function name as words.
+ */
+import type { TNodeInstanceAST, TNodeTypeAST } from '../ast/types';
+export declare function stepLabel(inst: TNodeInstanceAST, nt: TNodeTypeAST | undefined): string;
+//# sourceMappingURL=labels.d.ts.map

package/dist/diagram/lanes.d.ts

@@ -0,0 +1,93 @@
+/** What the layout needs to know about a step. The process model has all of it. */
+export interface LaneStep {
+    id: string;
+    /** `[pullExecution:]` declared: the step runs when something reads it. */
+    pull?: boolean;
+    /** The scope this step owns, when it has children. */
+    scope?: string | null;
+    /** Which of its owner's scopes this step sits in, when the owner has several. */
+    inScope?: string | null;
+    reads: Array<{
+        from: string;
+    }>;
+    produces: Array<{
+        to: string[];
+    }>;
+    children: LaneStep[];
+    entered: Array<{
+        from: string;
+        arm: 'ok' | 'fail';
+    }>;
+    successTo: string[];
+    failureTo: string[];
+}
+export interface LaneModel {
+    steps: LaneStep[];
+    startTo: string[];
+    exitFrom: Array<{
+        from: string;
+        arm: 'ok' | 'fail';
+    }>;
+}
+export type EdgeKind = 'ok' | 'fail' | 'loop' | 'return' | 'pull';
+export interface LaneRow<S extends LaneStep = LaneStep> {
+    id: string;
+    step: S | null;
+    depth: number;
+    lane: number;
+    owner: string | null;
+}
+export interface LaneEdge {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    fromLane: number;
+    lane: number;
+    toLane: number;
+}
+/**
+ * The rows a scope owner's body occupies: drawn as one band behind them, so
+ * the reader sees where the body starts and ends and whose it is, not only
+ * that the rows are indented.
+ */
+export interface LaneScope {
+    owner: string;
+    scope: string | null;
+    first: number;
+    last: number;
+    depth: number;
+    lane: number;
+}
+/**
+ * The rows one failure arm occupies, drawn as a band the way a scope body is:
+ * the reader sees which gate the detour leaves and where it rejoins, not only
+ * that some rows sit one lane right.
+ */
+export interface LaneArm {
+    gate: string;
+    first: number;
+    last: number;
+    lane: number;
+}
+export interface LaneGraph<S extends LaneStep = LaneStep> {
+    rows: LaneRow<S>[];
+    edges: LaneEdge[];
+    /** One per owner with a body, outer scopes first. */
+    scopes: LaneScope[];
+    /** One per gate arm that owns rows of its own. */
+    arms: LaneArm[];
+    lanes: number;
+    index: Record<string, number>;
+    /** Centre x of each lane. A lane carrying only edges is narrower than one holding tiles. */
+    laneX: number[];
+    /** Width of the whole gutter, i.e. where the step labels begin. */
+    gutter: number;
+}
+export declare function buildLanes<S extends LaneStep>(model: {
+    steps: S[];
+    startTo: string[];
+    exitFrom: LaneModel['exitFrom'];
+}): LaneGraph<S>;
+/** SVG path for one edge given row centre y positions and a lane x function. */
+export declare function edgePath(e: LaneEdge, y: (id: string) => number, x: (lane: number) => number): string;
+//# sourceMappingURL=lanes.d.ts.map

package/dist/diagram/layout.d.ts

@@ -1,4 +1,4 @@
-import type { TWorkflowAST } from '../ast/types.js';
+import type { TWorkflowAST } from '../ast/types';
 export interface LayoutResult {
     layers: string[][];
     nodeLayer: Map<string, number>;

package/dist/diagram/material-symbols.d.ts

@@ -0,0 +1,7 @@
+/** Every Material Symbol name, in the font's own `snake_case`. */
+export declare const MATERIAL_SYMBOLS: ReadonlySet<string>;
+/** The font's spelling of an icon name: `swapHoriz` and `swap_horiz` are the same symbol. */
+export declare const toSymbolName: (name: string) => string;
+/** Whether `@icon name` names a Material Symbol, in either spelling. */
+export declare const isMaterialSymbol: (name: string) => boolean;
+//# sourceMappingURL=material-symbols.d.ts.map

package/dist/diagram/orthogonal-router.d.ts

@@ -1,17 +1,7 @@
 /**
  * Orthogonal connection router for SVG diagram rendering.
  *
- * Ported from the original React-based editor's orthogonalRouter.ts.
- * Removed gl-matrix dependency — uses plain [number, number] tuples.
- *
- * Features:
- * - L-shape and S-shape routing with rounded corners
- * - Node collision avoidance via inflated bounding boxes
- * - Track allocator prevents parallel connections from overlapping
- * - Crossing minimization (evaluates up to 11 candidates per allocation)
- * - Per-port-index stub spacing
- * - Waypoint simplification (collinear removal, jog collapse)
- * - Backward/self connection escape routing
+ * Uses plain [number, number] tuples for points, with no vector-math dependency.
  */
 export interface NodeBox {
     id: string;
@@ -28,52 +18,26 @@ export interface OrthogonalRouteOptions {
     maxStubLength?: number;
     fromPortIndex?: number;
     toPortIndex?: number;
+    /** When true, treat same-node connections as forward (not self-loop). Used for scoped port connections. */
+    scopedInternal?: boolean;
+    /** Track allocator for preventing connections from overlapping on the same horizontal track. */
+    allocator?: TrackAllocator;
 }
 type Vec2 = [number, number];
-type InflatedBox = {
-    left: number;
-    right: number;
-    top: number;
-    bottom: number;
-};
+/**
+ * Prevents connections from running on the same horizontal track.
+ * Create one instance per render batch and pass it to all routing calls.
+ * Tracks are snapped to TRACK_SPACING grid. Only connections whose X corridors
+ * overlap can conflict.
+ */
 export declare class TrackAllocator {
     private claims;
-    private verticalClaims;
-    /** Check if a Y value is too close to any claimed segment whose X range overlaps. */
-    private isOccupied;
-    /** Check if an X value is too close to any claimed vertical segment whose Y range overlaps. */
-    private isOccupiedVertical;
-    /** Check if a horizontal segment at Y passes through any inflated node box. */
-    private isBlockedByNode;
-    /** Check if a vertical segment at X passes through any inflated node box. */
-    private isBlockedByNodeVertical;
-    /** Count claimed vertical segments that a horizontal segment at Y would cross. */
-    countHorizontalCrossings(xMin: number, xMax: number, y: number): number;
-    /** Count claimed horizontal segments that a vertical segment at X would cross. */
-    countVerticalCrossings(yMin: number, yMax: number, x: number): number;
-    /**
-     * Find the nearest free Y to candidateY in the given X range, preferring fewer crossings.
-     * When nodeBoxes is provided, candidates inside inflated node boxes are rejected (hard constraint).
-     */
-    findFreeY(xMin: number, xMax: number, candidateY: number, nodeBoxes?: InflatedBox[]): number;
-    /**
-     * Find the nearest free X to candidateX in the given Y range, preferring fewer crossings.
-     * When nodeBoxes is provided, candidates inside inflated node boxes are rejected (hard constraint).
-     */
-    findFreeX(yMin: number, yMax: number, candidateX: number, nodeBoxes?: InflatedBox[]): number;
-    /** Claim a horizontal segment so later connections avoid it. */
-    claim(xMin: number, xMax: number, y: number): void;
-    /** Claim a vertical segment so later connections avoid it. */
-    claimVertical(yMin: number, yMax: number, x: number): void;
+    claim(xMin: number, xMax: number, candidateY: number): number;
 }
+export declare function calculateOrthogonalPath(from: Vec2, to: Vec2, nodeBoxes: NodeBox[], sourceNodeId: string, targetNodeId: string, options?: OrthogonalRouteOptions): string | null;
 /**
- * Calculate an orthogonal SVG path between two ports.
- * Returns null if the path should fall back to bezier (e.g. nearly aligned ports).
- */
-export declare function calculateOrthogonalPath(from: Vec2, to: Vec2, nodeBoxes: NodeBox[], sourceNodeId: string, targetNodeId: string, options?: OrthogonalRouteOptions, allocator?: TrackAllocator): string | null;
-/**
- * Safe wrapper — returns null if routing fails, caller falls back to bezier.
+ * Safe wrapper: returns null if routing fails, caller falls back to straight line.
  */
-export declare function calculateOrthogonalPathSafe(from: Vec2, to: Vec2, nodeBoxes: NodeBox[], sourceNodeId: string, targetNodeId: string, options?: OrthogonalRouteOptions, allocator?: TrackAllocator): string | null;
+export declare function calculateOrthogonalPathSafe(from: Vec2, to: Vec2, nodeBoxes: NodeBox[], sourceNodeId: string, targetNodeId: string, options?: OrthogonalRouteOptions): string | null;
 export {};
 //# sourceMappingURL=orthogonal-router.d.ts.map

package/dist/diagram/process-view.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The process model: a workflow read as the process it runs, not the graph
+ * it is drawn as.
+ *
+ * It answers the questions an author or a reviewer actually has: in what
+ * order do the steps run, where does the process stop and wait for someone,
+ * what happens when a step fails, and which steps run at the same time.
+ * Everything is derived from the parsed AST with the same facts the engine
+ * uses -- topological order, control edges, and the durable classification
+ * -- so what is shown is what would run, never a hand-placed picture. The
+ * console, the brief and the spine SVG all draw from this model.
+ *
+ * Vocabulary:
+ *   stage   -- the longest control path from Start. Steps sharing a stage
+ *              have no control dependency between them
+ *   pause   -- a durable gate, where the process stops and waits for a resolver
+ *   segment -- the run between two pauses, i.e. what one continuation covers
+ *   arm     -- a failure edge
+ *   loop    -- a scope owner, with its children as an inner process
+ */
+import type { TWorkflowAST } from '../ast/types';
+export type ProcessKind = 'step' | 'pause' | 'effect' | 'loop';
+export interface ProcessStep {
+    id: string;
+    label: string;
+    type: string;
+    kind: ProcessKind;
+    gate: 'approval' | 'input' | 'agent' | 'timer' | null;
+    scope: string | null;
+    /**
+     * Which of its parent's scopes this step sits in. A node type may declare
+     * several (`@scope` more than once), each a callback the owner drives, and
+     * the children of all of them arrive in one list.
+     */
+    inScope: string | null;
+    pure: boolean;
+    expression: boolean;
+    stage: number;
+    segment: number;
+    reads: Array<{
+        port: string;
+        from: string;
+        fromPort: string;
+    }>;
+    exprs: Array<{
+        port: string;
+        expr: string;
+    }>;
+    produces: Array<{
+        port: string;
+        to: string[];
+    }>;
+    children: ProcessStep[];
+    entered: Array<{
+        from: string;
+        arm: 'ok' | 'fail';
+    }>;
+    successTo: string[];
+    failureTo: string[];
+    gateInputs: string[];
+    gateOutputs: string[];
+    description: string;
+}
+export interface ProcessModel {
+    name: string;
+    description: string;
+    params: string[];
+    returns: string[];
+    steps: ProcessStep[];
+    startTo: string[];
+    exitFrom: Array<{
+        from: string;
+        arm: 'ok' | 'fail';
+    }>;
+    segments: number;
+}
+/** Build the process model for one workflow. */
+export declare function buildProcessModel(ast: TWorkflowAST): ProcessModel;
+//# sourceMappingURL=process-view.d.ts.map

package/dist/diagram/spine.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The workflow as the console draws it, as one SVG.
+ *
+ * A spine: steps in run order down the page, one tile each, with the
+ * control flow as lanes beside them in the manner of a git graph. Failure
+ * arms branch out and merge back, a loop body is indented under its owner,
+ * a step read on demand hangs off a dashed line. It is the same lane
+ * layout and the same tiles the console shows live, drawn once and made
+ * still: what goes on a slide or in a document is what the operator sees.
+ *
+ * Self-contained: the fonts are the reader's system fonts, the icons are
+ * paths, the colours are literal. Nothing is fetched.
+ */
+import type { TWorkflowAST } from '../ast/types';
+export interface SpineOptions {
+    theme?: 'dark' | 'light';
+    /** The workflow's name and a line of facts above the spine. On by default, off when the page around it already says so. */
+    title?: boolean;
+    /** Shown under the title in place of the file name. */
+    subtitle?: string;
+}
+/** `color-mix(in srgb, a p%, b)` for two hex colours. */
+export declare function mix(a: string, b: string, p: number): string;
+export declare function renderSpineSVG(ast: TWorkflowAST, options?: SpineOptions): string;
+//# sourceMappingURL=spine.d.ts.map

package/dist/diagram/theme.d.ts

@@ -1,14 +1,12 @@
-import type { TDataType } from '../ast/types.js';
-import type { ThemePalette } from './types.js';
+import type { TDataType } from '../ast/types';
 export declare const NODE_DEFAULT_COLOR = "#334155";
 export declare const NODE_VARIANT_COLORS: Record<string, {
     border: string;
     darkBorder: string;
+    icon: string;
+    darkIcon: string;
 }>;
-export declare function getTheme(name: 'dark' | 'light'): ThemePalette;
 export declare function getPortColor(dataType: TDataType, isFailure: boolean, theme?: 'dark' | 'light'): string;
-/** Darker tinted version of the port color for the outer ring */
-export declare function getPortRingColor(dataType: TDataType, isFailure: boolean, theme?: 'dark' | 'light'): string;
 /** Map data types to short abbreviations for port labels */
 export declare const TYPE_ABBREVIATIONS: Record<string, string>;
 /**

package/dist/diagram/types.d.ts

@@ -1,11 +1,12 @@
-import type { TDataType } from '../ast/types.js';
+import type { TDataType } from '../ast/types';
 export interface DiagramOptions {
     theme?: 'dark' | 'light';
-    width?: number;
-    padding?: number;
-    showPortLabels?: boolean;
     workflowName?: string;
-    format?: 'svg' | 'html' | 'ascii' | 'ascii-compact' | 'text';
+    format?: 'svg' | 'ascii' | 'ascii-compact' | 'text';
+    /** For `svg`: the name and a line of facts above the spine (default on). */
+    title?: boolean;
+    /** For `svg`: shown under the title in place of the file name. */
+    subtitle?: string;
 }
 export interface DiagramPort {
     name: string;
@@ -67,19 +68,4 @@ export interface DiagramGraph {
     };
     workflowName: string;
 }
-export interface ThemePalette {
-    background: string;
-    nodeFill: string;
-    nodeStroke: string;
-    labelColor: string;
-    sublabelColor: string;
-    connectionColor: string;
-    dotColor: string;
-    labelBadgeFill: string;
-    labelBadgeBorder: string;
-    nodeIconColor: string;
-    scopeAreaStroke: string;
-    nodeShadowOpacity: number;
-    dotOpacity: number;
-}
 //# sourceMappingURL=types.d.ts.map

package/dist/diff/index.js

@@ -1,9 +1,53 @@
-/**
- * Semantic diff module for workflow comparison.
- * @module diff
- */
-export * from './types.js';
-export { WorkflowDiffer } from './WorkflowDiffer.js';
-export { IMPACT_DESCRIPTIONS, IMPACT_COLORS, getImpactReasons, hasBreakingChanges, getNodeTypeChanges, getCriticalConnections, } from './impact.js';
-export { formatDiff } from './formatDiff.js';
-//# sourceMappingURL=index.js.map
+import {
+  IMPACT_COLORS,
+  IMPACT_DESCRIPTIONS,
+  WorkflowDiffer,
+  formatDiff,
+  getCriticalConnections,
+  getImpactReasons,
+  getNodeTypeChanges,
+  hasBreakingChanges
+} from "../chunks/chunk-CYHYDLV4.js";
+import "../chunks/chunk-HKZLQJDV.js";
+import "../chunks/chunk-SEWDMQ6Q.js";
+
+// src/diff/types.ts
+var SEMANTIC_NODE_TYPE_FIELDS = [
+  "name",
+  "functionName",
+  "inputs",
+  "outputs",
+  "executeWhen",
+  "branchingStrategy",
+  "isAsync",
+  "scope",
+  "variant"
+];
+var SEMANTIC_INSTANCE_FIELDS = [
+  "id",
+  "nodeType",
+  "config.pullExecution",
+  "config.portConfigs",
+  "parent"
+];
+var SEMANTIC_CONNECTION_FIELDS = [
+  "from.node",
+  "from.port",
+  "from.scope",
+  "to.node",
+  "to.port",
+  "to.scope"
+];
+export {
+  IMPACT_COLORS,
+  IMPACT_DESCRIPTIONS,
+  SEMANTIC_CONNECTION_FIELDS,
+  SEMANTIC_INSTANCE_FIELDS,
+  SEMANTIC_NODE_TYPE_FIELDS,
+  WorkflowDiffer,
+  formatDiff,
+  getCriticalConnections,
+  getImpactReasons,
+  getNodeTypeChanges,
+  hasBreakingChanges
+};

package/dist/diff/types.d.ts

@@ -40,13 +40,9 @@ export interface TInstanceConfigChange {
     } | undefined>;
     portConfigs?: TChange<TPortConfig[] | undefined>;
 }
-/** Instance UI change (position, label, etc.) */
+/** Instance UI change (label, size, etc.) */
 export interface TInstanceUIChange {
     label?: TChange<string>;
-    position?: TChange<{
-        x: number;
-        y: number;
-    }>;
     size?: TChange<{
         width: number;
         height: number;

package/dist/doc-metadata/extractors/annotations.d.ts

@@ -25,10 +25,6 @@ export declare const METADATA_ANNOTATIONS: TAnnotationDoc[];
  * Standard JSDoc annotations (for completeness in IDE)
  */
 export declare const STANDARD_ANNOTATIONS: TAnnotationDoc[];
-/**
- * Pattern-specific annotations
- */
-export declare const PATTERN_ANNOTATIONS: TAnnotationDoc[];
 /**
  * Port modifiers - attributes in square brackets after port name
  */

package/dist/doc-metadata/extractors/cli-commands.d.ts

@@ -2,7 +2,8 @@
  * Extractor for CLI command documentation
  *
  * This defines all CLI commands with their descriptions, options, and action blocks.
- * The data is extracted from the Commander.js definitions in cli/index.ts.
+ * The data mirrors the Commander.js definitions in cli/program.ts; a test
+ * (tests/unit/doc-metadata/cli-commands-sync.test.ts) compares the two.
  * Template lists are generated from the actual template registries.
  */
 import type { TCliCommandDoc } from '../types.js';

package/dist/doc-metadata/extractors/core-metadata.d.ts

@@ -2,8 +2,8 @@
  * Core metadata extractor.
  *
  * Provides runtime-accessible arrays and objects for data types, strategies,
- * reserved names, templates, and package exports — derived from the actual
- * source constants so documentation stays in sync automatically.
+ * reserved names, templates, and package exports. These are derived from the
+ * actual source constants so documentation stays in sync automatically.
  */
 import { RESERVED_NODE_NAMES, RESERVED_PORT_NAMES, SCOPED_PORT_NAMES, EXECUTION_STRATEGIES, BRANCHING_STRATEGIES, VALID_NODE_COLORS } from '../../constants.js';
 import { type WorkflowTemplate, type NodeTemplate } from '../../cli/templates/index.js';
@@ -36,6 +36,9 @@ export declare const PACKAGE_EXPORTS: readonly [{
 }, {
     readonly subpath: "./runtime";
     readonly description: "Workflow runtime executor";
+}, {
+    readonly subpath: "./compiler";
+    readonly description: "Build-only executable artifact compiler";
 }, {
     readonly subpath: "./built-in-nodes";
     readonly description: "Standard node type library";
@@ -91,10 +94,22 @@ export declare const PACKAGE_EXPORTS: readonly [{
     readonly subpath: "./cli";
     readonly description: "CLI command definitions";
 }, {
-    readonly subpath: "./executor";
-    readonly description: "MCP workflow executor";
+    readonly subpath: "./version";
+    readonly description: "Package version metadata";
 }, {
     readonly subpath: "./context";
     readonly description: "LLM context generation";
+}, {
+    readonly subpath: "./agent";
+    readonly description: "Provider-agnostic agent tooling";
+}, {
+    readonly subpath: "./console";
+    readonly description: "The local operator console server";
+}, {
+    readonly subpath: "./coordinator";
+    readonly description: "Local run coordinator: start, resume and watch gated workflows from code";
+}, {
+    readonly subpath: "./server";
+    readonly description: "Workflows as HTTP endpoints: createWorkflowApi with Node, Express and fetch adapters, the handler behind fw serve";
 }];
 //# sourceMappingURL=core-metadata.d.ts.map

package/dist/doc-metadata/extractors/error-codes.d.ts

@@ -1,7 +1,7 @@
 /**
  * Single source of truth for validation error code documentation.
  *
- * Every code the validator (src/validator.ts) and agent rules
+ * Every code the validator (src/validation/validator.ts) and agent rules
  * (src/validation/agent-rules.ts) can emit is listed here.
  *
  * The generate-docs script uses this to build the summary tables

package/dist/doc-metadata/extractors/mcp-tools.d.ts

@@ -1,8 +1,12 @@
 /**
  * Extractor for MCP tool documentation
  *
- * This defines all MCP tools with their descriptions and parameters.
- * The data is extracted from the tool registration files (tools-query.ts, tools-template.ts, tools-pattern.ts, tools-export.ts).
+ * One entry per tool the MCP server registers, mirroring the zod schema in
+ * its src/mcp/tools-*.ts registration: same names, descriptions, parameter
+ * types, enums and required flags. It is exported from
+ * `@synergenius/flow-weaver/doc-metadata` for documentation tooling, so a tool
+ * missing here is missing from generated docs. When a tool schema changes,
+ * change the entry with it.
  */
 import type { TMcpToolDoc } from '../types.js';
 /**
@@ -10,7 +14,7 @@ import type { TMcpToolDoc } from '../types.js';
  */
 export declare const MCP_TOOLS: TMcpToolDoc[];
 /**
- * Extract MCP tool documentation
+ * Extract MCP tool documentation.
  */
 export declare function extractMcpTools(): TMcpToolDoc[];
 //# sourceMappingURL=mcp-tools.d.ts.map

package/dist/doc-metadata/index.d.ts

@@ -1,12 +1,11 @@
 export { extractMcpTools, MCP_TOOLS } from './extractors/mcp-tools.js';
 export { extractCliCommands, CLI_COMMANDS } from './extractors/cli-commands.js';
-export { PLUGIN_DEFINITION_FIELDS, PLUGIN_CAPABILITIES, PLUGIN_COMPONENT_CONFIG_FIELDS, PLUGIN_COMPONENT_AREAS, PLUGIN_UI_KIT_COMPONENTS, } from './extractors/plugin-api.js';
 export { ALL_ANNOTATIONS, PORT_MODIFIERS, NODE_MODIFIERS, } from './extractors/annotations.js';
 export { VALIDATION_CODES } from './extractors/error-codes.js';
 export type { TValidationCodeDoc } from './extractors/error-codes.js';
 export { extractGrammarEBNF, extractTerminals } from './extractors/grammar-rules.js';
 export type { TGrammarGroupDoc, TTerminalDoc } from './extractors/grammar-rules.js';
-export type { TMcpToolDoc, TMcpToolParam, TPluginApiFieldDoc, TCliCommandDoc, TCliOptionDoc } from './types.js';
+export type { TMcpToolDoc, TMcpToolParam, TCliCommandDoc, TCliOptionDoc } from './types.js';
 export { DATA_TYPES, MERGE_STRATEGIES, BRANCHING_STRATEGY_VALUES, EXECUTION_STRATEGY_VALUES, RESERVED_NODE_NAMES, RESERVED_PORT_NAMES, SCOPED_PORT_NAMES, EXECUTION_STRATEGIES, BRANCHING_STRATEGIES, VALID_NODE_COLORS, WORKFLOW_TEMPLATES, NODE_TEMPLATES, PACKAGE_EXPORTS, } from './extractors/core-metadata.js';
 export type { TemplateSummary } from './extractors/core-metadata.js';
 //# sourceMappingURL=index.d.ts.map