footprintjs 0.2.2 → 0.3.0

package/dist/types/lib/builder/FlowChartBuilder.d.ts

@@ -28,13 +28,12 @@ export declare class DeciderList<TOut = any, TScope = any> {
     private readonly deciderDescription?;
     private readonly branchDescInfo;
     constructor(builder: FlowChartBuilder<TOut, TScope>, curNode: StageNode<TOut, TScope>, curSpec: SerializedPipelineStructure, parentDescriptionParts?: string[], parentStageDescriptions?: Map<string, string>, reservedStepNumber?: number, deciderDescription?: string);
-    addFunctionBranch(id: string, name: string, fn?: PipelineStageFunction<TOut, TScope>, displayName?: string, description?: string): DeciderList<TOut, TScope>;
+    addFunctionBranch(id: string, name: string, fn?: PipelineStageFunction<TOut, TScope>, description?: string): DeciderList<TOut, TScope>;
     addSubFlowChartBranch(id: string, subflow: FlowChart<TOut, TScope>, mountName?: string, options?: SubflowMountOptions): DeciderList<TOut, TScope>;
     addBranchList(branches: Array<{
         id: string;
         name: string;
         fn?: PipelineStageFunction<TOut, TScope>;
-        displayName?: string;
     }>): DeciderList<TOut, TScope>;
     setDefault(id: string): DeciderList<TOut, TScope>;
     end(): FlowChartBuilder<TOut, TScope>;
@@ -50,13 +49,12 @@ export declare class SelectorFnList<TOut = any, TScope = any> {
     private readonly selectorDescription?;
     private readonly branchDescInfo;
     constructor(builder: FlowChartBuilder<TOut, TScope>, curNode: StageNode<TOut, TScope>, curSpec: SerializedPipelineStructure, parentDescriptionParts?: string[], parentStageDescriptions?: Map<string, string>, reservedStepNumber?: number, selectorDescription?: string);
-    addFunctionBranch(id: string, name: string, fn?: PipelineStageFunction<TOut, TScope>, displayName?: string, description?: string): SelectorFnList<TOut, TScope>;
+    addFunctionBranch(id: string, name: string, fn?: PipelineStageFunction<TOut, TScope>, description?: string): SelectorFnList<TOut, TScope>;
     addSubFlowChartBranch(id: string, subflow: FlowChart<TOut, TScope>, mountName?: string, options?: SubflowMountOptions): SelectorFnList<TOut, TScope>;
     addBranchList(branches: Array<{
         id: string;
         name: string;
         fn?: PipelineStageFunction<TOut, TScope>;
-        displayName?: string;
     }>): SelectorFnList<TOut, TScope>;
     end(): FlowChartBuilder<TOut, TScope>;
 }
@@ -79,16 +77,25 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     private _stepCounter;
     private _stageDescriptions;
     private _stageStepMap;
+    private _inputSchema?;
+    private _outputSchema?;
+    private _outputMapper?;
     constructor(buildTimeExtractor?: BuildTimeExtractor<any>);
     private _appendDescriptionLine;
     private _appendSubflowDescription;
     setEnableNarrative(): this;
     setLogger(logger: ILogger): this;
-    start(name: string, fn?: PipelineStageFunction<TOut, TScope>, id?: string, displayName?: string, description?: string): this;
-    addFunction(name: string, fn?: PipelineStageFunction<TOut, TScope>, id?: string, displayName?: string, description?: string): this;
-    addStreamingFunction(name: string, streamId?: string, fn?: PipelineStageFunction<TOut, TScope>, id?: string, displayName?: string, description?: string): this;
-    addDeciderFunction(name: string, fn: PipelineStageFunction<TOut, TScope>, id?: string, displayName?: string, description?: string): DeciderList<TOut, TScope>;
-    addSelectorFunction(name: string, fn: PipelineStageFunction<TOut, TScope>, id?: string, displayName?: string, description?: string): SelectorFnList<TOut, TScope>;
+    /** Declare the input schema (readOnlyContext shape). Accepts Zod schema or JSON Schema. */
+    setInputSchema(schema: unknown): this;
+    /** Declare the output schema (response shape). Accepts Zod schema or JSON Schema. */
+    setOutputSchema(schema: unknown): this;
+    /** Set the output mapper that extracts the response from final scope. */
+    setOutputMapper(mapper: (finalScope: Record<string, unknown>) => unknown): this;
+    start(name: string, fn?: PipelineStageFunction<TOut, TScope>, id?: string, description?: string): this;
+    addFunction(name: string, fn?: PipelineStageFunction<TOut, TScope>, id?: string, description?: string): this;
+    addStreamingFunction(name: string, streamId?: string, fn?: PipelineStageFunction<TOut, TScope>, id?: string, description?: string): this;
+    addDeciderFunction(name: string, fn: PipelineStageFunction<TOut, TScope>, id?: string, description?: string): DeciderList<TOut, TScope>;
+    addSelectorFunction(name: string, fn: PipelineStageFunction<TOut, TScope>, id?: string, description?: string): SelectorFnList<TOut, TScope>;
     addListOfFunction(children: SimplifiedParallelSpec<TOut, TScope>[], options?: {
         failFast?: boolean;
     }): this;
@@ -117,5 +124,5 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
         root: StageNode<TOut, TScope>;
     }> | undefined, prefix: string): void;
 }
-export declare function flowChart<TOut = any, TScope = any>(name: string, fn?: PipelineStageFunction<TOut, TScope>, id?: string, displayName?: string, buildTimeExtractor?: BuildTimeExtractor<any>, description?: string): FlowChartBuilder<TOut, TScope>;
+export declare function flowChart<TOut = any, TScope = any>(name: string, fn?: PipelineStageFunction<TOut, TScope>, id?: string, buildTimeExtractor?: BuildTimeExtractor<any>, description?: string): FlowChartBuilder<TOut, TScope>;
 export declare function specToStageNode(spec: FlowChartSpec): StageNode<any, any>;

package/dist/types/lib/builder/types.d.ts

@@ -40,8 +40,6 @@ export type StageNode<TOut = any, TScope = any> = {
     name: string;
     /** Optional stable id (required by decider/fork aggregation). */
     id?: string;
-    /** Human-readable display name for UI. */
-    displayName?: string;
     /** Human-readable description of what this stage does. */
     description?: string;
     /** Linear continuation. */
@@ -77,7 +75,6 @@ export interface SerializedPipelineStructure {
     name: string;
     id?: string;
     type: 'stage' | 'decider' | 'fork' | 'streaming';
-    displayName?: string;
     description?: string;
     children?: SerializedPipelineStructure[];
     next?: SerializedPipelineStructure;
@@ -98,7 +95,6 @@ export interface SerializedPipelineStructure {
 export interface FlowChartSpec {
     name: string;
     id?: string;
-    displayName?: string;
     description?: string;
     children?: FlowChartSpec[];
     next?: FlowChartSpec;
@@ -130,11 +126,16 @@ export type FlowChart<TOut = any, TScope = any> = {
     logger?: ILogger;
     description: string;
     stageDescriptions: Map<string, string>;
+    /** Input schema (Zod or JSON Schema) — declared via setInputSchema(). */
+    inputSchema?: unknown;
+    /** Output schema (Zod or JSON Schema) — declared via setOutputSchema(). */
+    outputSchema?: unknown;
+    /** Output mapper — extracts response from final scope. */
+    outputMapper?: (finalScope: Record<string, unknown>) => unknown;
 };
 export type SimplifiedParallelSpec<TOut = any, TScope = any> = {
     id: string;
     name: string;
-    displayName?: string;
     fn?: PipelineStageFunction<TOut, TScope>;
 };
 export type ExecOptions = {
@@ -148,5 +149,4 @@ export type ExecOptions = {
 export interface SubflowRef {
     $ref: string;
     mountId: string;
-    displayName?: string;
 }

package/dist/types/lib/contract/defineContract.d.ts

@@ -0,0 +1,18 @@
+/**
+ * contract/defineContract.ts — Factory for creating a FlowChartContract.
+ *
+ * Wraps a compiled FlowChart with I/O schemas and an output mapper,
+ * using the same pattern as SubflowMountOptions (inputMapper/outputMapper).
+ *
+ * Usage:
+ *   const contract = defineContract(chart, {
+ *     inputSchema: z.object({ name: z.string() }),
+ *     outputSchema: z.object({ greeting: z.string() }),
+ *     outputMapper: (scope) => ({ greeting: scope.message as string }),
+ *   });
+ *
+ *   const openapi = contract.toOpenAPI();
+ */
+import type { FlowChart } from '../builder/types';
+import type { FlowChartContract, FlowChartContractOptions } from './types';
+export declare function defineContract<TInput = unknown, TOutput = unknown>(chart: FlowChart, options: FlowChartContractOptions<TInput, TOutput>): FlowChartContract<TInput, TOutput>;

package/dist/types/lib/contract/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * contract/ — FlowChart I/O contract and OpenAPI generation layer.
+ *
+ * Standalone library: wraps a compiled FlowChart with input/output schemas
+ * and generates OpenAPI 3.1 specs. Uses the same inputMapper/outputMapper
+ * pattern as subflow mounting.
+ *
+ * Zero runtime deps on Zod — Zod schemas detected via duck-typing and
+ * converted to JSON Schema at contract creation time.
+ */
+export { defineContract } from './defineContract';
+export { isZodSchema, normalizeSchema, zodToJsonSchema } from './schema';
+export { generateOpenAPI } from './openapi';
+export type { FlowChartContract, FlowChartContractOptions, JsonSchema, OpenAPIOptions, OpenAPISpec, SchemaInput, } from './types';

package/dist/types/lib/contract/openapi.d.ts

@@ -0,0 +1,12 @@
+/**
+ * contract/openapi.ts — OpenAPI 3.1 spec generator.
+ *
+ * Generates an OpenAPI spec from a FlowChartContract by combining:
+ * - chart.description → operation description
+ * - chart.stageDescriptions → step-by-step detail
+ * - inputSchema → requestBody
+ * - outputSchema → response
+ * - chart.buildTimeStructure → operation metadata (branches, forks, etc.)
+ */
+import type { FlowChartContract, OpenAPIOptions, OpenAPISpec } from './types';
+export declare function generateOpenAPI(contract: FlowChartContract, options?: OpenAPIOptions): OpenAPISpec;

package/dist/types/lib/contract/schema.d.ts

@@ -0,0 +1,14 @@
+/**
+ * contract/schema.ts — Schema normalization utilities.
+ *
+ * Converts Zod schemas or raw JSON Schema objects into a normalized
+ * JsonSchema format. Zod detection uses duck-typing (checks for `_def`).
+ *
+ * Standalone: no dependency on Zod at import time.
+ * Compatible with Zod v4 internals.
+ */
+import type { JsonSchema, SchemaInput } from './types';
+export declare function isZodSchema(input: unknown): boolean;
+/** Convert a Zod schema object to JSON Schema. */
+export declare function zodToJsonSchema(zodSchema: Record<string, unknown>): JsonSchema;
+export declare function normalizeSchema(input: SchemaInput): JsonSchema;

package/dist/types/lib/contract/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * contract/types.ts — Types for the FlowChart contract layer.
+ *
+ * Defines the I/O boundary for a flowchart: input schema, output schema,
+ * and output mapper. Uses the same pattern as SubflowMountOptions
+ * (inputMapper/outputMapper) but at the top-level flowchart boundary.
+ */
+import type { FlowChart } from '../builder/types';
+export type JsonSchema = {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: unknown[];
+    description?: string;
+    default?: unknown;
+    format?: string;
+    additionalProperties?: boolean | JsonSchema;
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    $ref?: string;
+    [key: string]: unknown;
+};
+/** Anything with a `def` (Zod v4) or `_def` (Zod v3) property is treated as a Zod schema. */
+export type SchemaInput = JsonSchema | {
+    def: unknown;
+    [key: string]: unknown;
+};
+export interface FlowChartContractOptions<TInput = unknown, TOutput = unknown> {
+    /** Schema describing the input (readOnlyContext) shape. Zod or JSON Schema. */
+    inputSchema?: SchemaInput;
+    /** Schema describing the output shape. Zod or JSON Schema. */
+    outputSchema?: SchemaInput;
+    /** Maps the final scope state into the response shape. */
+    outputMapper?: (finalScope: Record<string, unknown>) => TOutput;
+}
+export interface FlowChartContract<TInput = unknown, TOutput = unknown> {
+    /** The compiled flowchart. */
+    chart: FlowChart;
+    /** JSON Schema for the input (normalized from Zod or raw). */
+    inputSchema?: JsonSchema;
+    /** JSON Schema for the output (normalized from Zod or raw). */
+    outputSchema?: JsonSchema;
+    /** Maps the final scope state into the response shape. */
+    outputMapper?: (finalScope: Record<string, unknown>) => TOutput;
+    /** Auto-generated OpenAPI spec. */
+    toOpenAPI(options?: OpenAPIOptions): OpenAPISpec;
+}
+export interface OpenAPIOptions {
+    /** API version string (default: "1.0.0"). */
+    version?: string;
+    /** Base path prefix (default: "/"). */
+    basePath?: string;
+    /** HTTP method for the execute endpoint (default: "post"). */
+    method?: string;
+}
+export interface OpenAPISpec {
+    openapi: '3.1.0';
+    info: {
+        title: string;
+        description: string;
+        version: string;
+    };
+    paths: Record<string, Record<string, OpenAPIOperation>>;
+    components?: {
+        schemas?: Record<string, JsonSchema>;
+    };
+}
+export interface OpenAPIOperation {
+    operationId: string;
+    summary: string;
+    description: string;
+    requestBody?: {
+        required: boolean;
+        content: {
+            'application/json': {
+                schema: JsonSchema | {
+                    $ref: string;
+                };
+            };
+        };
+    };
+    responses: Record<string, {
+        description: string;
+        content?: {
+            'application/json': {
+                schema: JsonSchema | {
+                    $ref: string;
+                };
+            };
+        };
+    }>;
+}

package/dist/types/lib/engine/graph/StageNode.d.ts

@@ -23,8 +23,6 @@ export type StageNode<TOut = any, TScope = any> = {
     name: string;
     /** Optional stable id (required by decider/fork aggregation) */
     id?: string;
-    /** Human-readable display name for UI */
-    displayName?: string;
     /** Description of what this stage does. Used for narrative and tool descriptions. */
     description?: string;
     /** Linear continuation (linked list next pointer) */

package/dist/types/lib/engine/narrative/ControlFlowNarrativeGenerator.d.ts

@@ -14,16 +14,16 @@ import type { IControlFlowNarrative } from './types';
 export declare class ControlFlowNarrativeGenerator implements IControlFlowNarrative {
     private sentences;
     private isFirstStage;
-    onStageExecuted(stageName: string, displayName?: string, description?: string): void;
-    onNext(fromStage: string, toStage: string, toDisplayName?: string, description?: string): void;
-    onDecision(deciderName: string, chosenBranch: string, chosenDisplayName?: string, rationale?: string, deciderDescription?: string): void;
+    onStageExecuted(stageName: string, description?: string): void;
+    onNext(fromStage: string, toStage: string, description?: string): void;
+    onDecision(deciderName: string, chosenBranch: string, rationale?: string, deciderDescription?: string): void;
     onFork(parentStage: string, childNames: string[]): void;
     onSelected(parentStage: string, selectedNames: string[], totalCount: number): void;
     onSubflowEntry(subflowName: string): void;
     onSubflowExit(subflowName: string): void;
-    onLoop(targetStage: string, targetDisplayName: string | undefined, iteration: number, description?: string): void;
-    onBreak(stageName: string, displayName?: string): void;
-    onError(stageName: string, errorMessage: string, displayName?: string): void;
+    onLoop(targetStage: string, iteration: number, description?: string): void;
+    onBreak(stageName: string): void;
+    onError(stageName: string, errorMessage: string): void;
     /** Returns a defensive copy of accumulated sentences. */
     getSentences(): string[];
 }

package/dist/types/lib/engine/narrative/types.d.ts

@@ -9,11 +9,11 @@
  */
 export interface IControlFlowNarrative {
     /** Called when a stage executes. First stage uses distinct opening pattern. */
-    onStageExecuted(stageName: string, displayName?: string, description?: string): void;
+    onStageExecuted(stageName: string, description?: string): void;
     /** Called on linear continuation from one stage to the next. */
-    onNext(fromStage: string, toStage: string, toDisplayName?: string, description?: string): void;
+    onNext(fromStage: string, toStage: string, description?: string): void;
     /** Called when a decider selects a branch. Most valuable for LLM context. */
-    onDecision(deciderName: string, chosenBranch: string, chosenDisplayName?: string, rationale?: string, deciderDescription?: string): void;
+    onDecision(deciderName: string, chosenBranch: string, rationale?: string, deciderDescription?: string): void;
     /** Called when a fork executes all children in parallel. */
     onFork(parentStage: string, childNames: string[]): void;
     /** Called when a selector picks a subset of children. */
@@ -23,11 +23,11 @@ export interface IControlFlowNarrative {
     /** Called when exiting a subflow. */
     onSubflowExit(subflowName: string): void;
     /** Called on loop iteration (back-edge traversal). */
-    onLoop(targetStage: string, targetDisplayName: string | undefined, iteration: number, description?: string): void;
+    onLoop(targetStage: string, iteration: number, description?: string): void;
     /** Called when a stage triggers break (early termination). */
-    onBreak(stageName: string, displayName?: string): void;
+    onBreak(stageName: string): void;
     /** Called when a stage throws an error. */
-    onError(stageName: string, errorMessage: string, displayName?: string): void;
+    onError(stageName: string, errorMessage: string): void;
     /** Returns accumulated narrative sentences in execution order. */
     getSentences(): string[];
 }

package/dist/types/lib/engine/types.d.ts

@@ -169,7 +169,6 @@ export interface SerializedPipelineNode {
     name: string;
     id?: string;
     type?: 'stage' | 'decider' | 'fork' | 'streaming' | 'loop' | 'user' | 'tool' | 'function' | 'sequence';
-    displayName?: string;
     description?: string;
     children?: SerializedPipelineNode[];
     next?: SerializedPipelineNode;

package/dist/types/lib/runner/ExecutionRuntime.d.ts

@@ -16,7 +16,6 @@ import type { CommitBundle, FlowMessage, StageSnapshot } from '../memory/types';
 export interface NarrativeEntry {
     stageId: string;
     stageName: string;
-    displayName?: string;
     stageMessages: string[];
     flowMessage?: FlowMessage;
     timeIndex: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Turn your whiteboard flowchart into running code — with automatic causal traces for LLM reasoning",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",