@pipelex/mthds-ui 0.28.0 → 0.29.1

package/dist/{types-DvhUuMHz.d.ts → types-BaFWy56P.d.ts}

@@ -1,8 +1,18 @@
-type PipeOperatorType = "PipeLLM" | "PipeExtract" | "PipeCompose" | "PipeImgGen" | "PipeSearch" | "PipeFunc" | "PipeStructure" | "PipeSignature";
+type PipeOperatorType = "PipeLLM" | "PipeExtract" | "PipeCompose" | "PipeImgGen" | "PipeSearch" | "PipeFunc" | "PipeStructure" | "PipeJudge" | "PipeDocGen" | "PipeSignature";
 type PipeControllerType = "PipeSequence" | "PipeParallel" | "PipeCondition" | "PipeBatch";
 type PipeType = PipeOperatorType | PipeControllerType;
 /** Every pipe class name pipelex emits as `pipe_type`. Used by validateGraphSpec. */
 declare const KNOWN_PIPE_TYPES: ReadonlySet<string>;
+/**
+ * The `pipe_type` of a binding node. A PipeSequence's binding step
+ * (`{ from = "invoice.total", result = "total_amount" }`) runs no pipe, so the
+ * class it carries is not a pipe class: pipelex writes `BindingStep` beside the
+ * `binding` node kind, and the node's `pipe_code` is the step's `from` path.
+ */
+declare const BINDING_STEP_TYPE: "BindingStep";
+type BindingStepType = typeof BINDING_STEP_TYPE;
+/** What a GraphSpec node's `pipe_type` names: a pipe class, or the binding step that runs none. */
+type NodePipeType = PipeType | BindingStepType;
 type PipeStatus = "succeeded" | "failed" | "running" | "scheduled" | "skipped" | "canceled";
 declare const GRAPH_SPEC_MODE: {
     readonly DRY: "dry";
@@ -55,7 +65,7 @@ interface GraphSpecNodeIo {
     inputs: GraphSpecNodeIoItem[];
     outputs: GraphSpecNodeIoItem[];
 }
-type NodeKind = "pipe_call" | "controller" | "operator" | "input" | "output" | "artifact" | "error";
+type NodeKind = "pipe_call" | "controller" | "operator" | "input" | "output" | "artifact" | "error" | "binding";
 interface GraphSpecNodeTiming {
     started_at: string;
     ended_at: string;
@@ -159,7 +169,7 @@ interface GraphSpecNode {
     id: string;
     kind: NodeKind;
     pipe_code?: string;
-    pipe_type: PipeType;
+    pipe_type: NodePipeType;
     description?: string;
     domain_code?: string;
     status: PipeStatus;
@@ -172,15 +182,33 @@ interface GraphSpecNode {
     execution_data?: Record<string, unknown>;
 }
 /**
- * A pipe-call node — the only node kind a real pipelex run emits. Narrowed
- * from `GraphSpecNode` for code paths that only ever render pipe-call nodes,
- * where `pipe_code` is guaranteed (validateGraphSpec enforces this).
+ * A pipe-call node: a controller or an operator. Narrowed from `GraphSpecNode`
+ * for code paths that only ever render pipe-call nodes, where `pipe_code` is
+ * guaranteed (validateGraphSpec enforces this).
  */
 type PipeCallNode = GraphSpecNode & {
     kind: "controller" | "operator";
     pipe_code: string;
     pipe_type: PipeType;
 };
+/**
+ * A binding node: a PipeSequence's binding step, which runs no pipe. Its
+ * `pipe_code` is the step's `from` path (`invoice.total`), its one input the
+ * root the path starts from, and its one output the stuff it binds, under the
+ * step's `result`. A binding that bound nothing, because the path held nothing,
+ * has no output; one whose root was absent has no input; a failed one may have
+ * neither. The graph draws it all the same. It is never a controller: nothing
+ * is contained in it.
+ */
+type BindingNode = GraphSpecNode & {
+    kind: "binding";
+    pipe_code: string;
+    pipe_type: BindingStepType;
+};
+/** A node the graph draws as a card: a pipe-call node or a binding node. */
+type CardNode = PipeCallNode | BindingNode;
+/** Whether a node is a binding step's node. */
+declare function isBindingNode(node: Pick<GraphSpecNode, "kind">): boolean;
 type GraphSpecEdgeKind = "contains" | "data" | "control" | "selected_outcome" | "batch_item" | "batch_aggregate" | "parallel_combine";
 interface GraphSpecEdge {
     id: string;
@@ -233,6 +261,22 @@ interface SubPipeSpec {
         input_item_stuff_name: string;
     } | null;
 }
+/**
+ * A PipeSequence binding step, as the runtime holds it and the registry
+ * serializes it: the value at `from_path` stored under `output_name`. A step
+ * whose `batch_over` is a dotted path is held as such a binding, under a
+ * private `_bound_…` name and with `is_dotted_batch_over` set, followed by the
+ * same pipe step batching over that name.
+ */
+interface BindingStepSpec {
+    from_path: string;
+    output_name: string;
+    is_dotted_batch_over?: boolean;
+}
+/** One step of a PipeSequence: a pipe step, or a binding step. */
+type SequenceStepSpec = SubPipeSpec | BindingStepSpec;
+/** Whether a sequence step is a binding step, which carries a `from_path` and runs no pipe. */
+declare function isBindingStepSpec(step: SequenceStepSpec): step is BindingStepSpec;
 interface PipeBlueprintBase {
     type: PipeType;
     pipe_category: "PipeOperator" | "PipeController";
@@ -370,6 +414,50 @@ interface PipeStructureBlueprint extends PipeBlueprintBase {
     /** `true` → let the LLM decide the count, a number → fixed count, null → single object. */
     output_multiplicity?: boolean | number | null;
 }
+/**
+ * The question a PipeJudge asks, as the runtime serializes it. Its `kind`
+ * decides the verdict native the judge answers with: `yes_no` → `YesNo`,
+ * `choice` → `Choice`, `rating` → `Rating`. `instructions` is the authored
+ * question, still a template.
+ */
+interface JudgmentQuestionSpec {
+    kind: "yes_no" | "choice" | "rating";
+    instructions: string;
+    yes_criterion?: string | null;
+    no_criterion?: string | null;
+    options?: Record<string, string | null> | null;
+    levels?: string[] | null;
+}
+/**
+ * A PipeJudge: asks a judging model one closed question about its inputs and
+ * stores the verdict native it answers with. Serialized from the runtime
+ * `PipeJudge`.
+ */
+interface PipeJudgeBlueprint extends PipeBlueprintBase {
+    type: "PipeJudge";
+    /** The judging model, a handle or an inline setting, or null for the deck's default. */
+    judgment_choice?: string | Record<string, unknown> | null;
+    judgment_question: JudgmentQuestionSpec;
+    /** The probability a yes/no verdict must reach to read as yes, when the pipe declares one. */
+    threshold?: number | null;
+}
+/**
+ * A PipeDocGen: lays its inputs out as a stored document file, in the declared
+ * format, and calls no AI model. Serialized from the runtime `PipeDocGen`.
+ */
+interface PipeDocGenBlueprint extends PipeBlueprintBase {
+    type: "PipeDocGen";
+    /** `pdf`, `html`, `xlsx` or `docx`. */
+    doc_gen_format: string;
+    /** The engine the step names, or null for the deck's default. */
+    doc_gen_choice?: string | Record<string, unknown> | null;
+    /** The HTML template of a pdf step, inline or read from its template file. */
+    template?: string | null;
+    /** The template file as the method names it. */
+    template_file?: string | null;
+    /** The file name the document is stored under, a template. */
+    filename?: string | null;
+}
 /**
  * A contract-only pipe: declares inputs + output but has no implementation.
  * Emitted under `--allow-signatures` so an in-progress bundle still validates
@@ -389,7 +477,8 @@ interface PipeSignatureBlueprint extends Omit<PipeBlueprintBase, "pipe_category"
 }
 interface PipeSequenceBlueprint extends PipeBlueprintBase {
     type: "PipeSequence";
-    sequential_sub_pipes: SubPipeSpec[];
+    /** Pipe steps and binding steps, in order — a dotted `batch_over` held as a binding then a batch. */
+    sequential_sub_pipes: SequenceStepSpec[];
 }
 interface PipeParallelBlueprint extends PipeBlueprintBase {
     type: "PipeParallel";
@@ -423,7 +512,7 @@ interface PipeBatchBlueprint extends PipeBlueprintBase {
  * be `null` is also declared optional, because a host that drops `null` values
  * delivers it absent: test it with `!= null`, optional chaining or truthiness.
  */
-type PipeBlueprintUnion = PipeLLMBlueprint | PipeImgGenBlueprint | PipeComposeBlueprint | PipeExtractBlueprint | PipeSearchBlueprint | PipeFuncBlueprint | PipeStructureBlueprint | PipeSignatureBlueprint | PipeSequenceBlueprint | PipeParallelBlueprint | PipeConditionBlueprint | PipeBatchBlueprint;
+type PipeBlueprintUnion = PipeLLMBlueprint | PipeImgGenBlueprint | PipeComposeBlueprint | PipeExtractBlueprint | PipeSearchBlueprint | PipeFuncBlueprint | PipeStructureBlueprint | PipeJudgeBlueprint | PipeDocGenBlueprint | PipeSignatureBlueprint | PipeSequenceBlueprint | PipeParallelBlueprint | PipeConditionBlueprint | PipeBatchBlueprint;
 interface GraphSpec {
     graph_id?: string;
     created_at?: string;
@@ -451,7 +540,11 @@ interface StuffRegistryEntry {
 }
 interface DataflowAnalysis {
     readonly stuffRegistry: Readonly<Record<string, StuffRegistryEntry>>;
-    readonly stuffProducers: Readonly<Record<string, string>>;
+    /**
+     * Every operator that writes each stuff. Usually one; a condition's output has one per
+     * outcome, because every outcome writes the condition's one slot and only one of them runs.
+     */
+    readonly stuffProducers: Readonly<Record<string, readonly string[]>>;
     readonly stuffConsumers: Readonly<Record<string, readonly string[]>>;
     readonly controllerNodeIds: ReadonlySet<string>;
     readonly childNodeIds: ReadonlySet<string>;
@@ -654,7 +747,7 @@ interface FoldToggleOptions {
 }
 interface PipeCardPayload {
     pipeCode: string;
-    pipeType: PipeType;
+    pipeType: NodePipeType;
     description?: string;
     status: PipeStatus;
     graphMode?: GraphSpecMode;
@@ -687,7 +780,7 @@ interface GraphNodeData extends Record<string, unknown> {
     isController?: boolean;
     labelText: string;
     pipeCode?: string;
-    pipeType?: PipeType;
+    pipeType?: NodePipeType;
     graphMode?: GraphSpecMode;
     pipeCardData?: PipeCardPayload;
     /** For stuff nodes: "input" (no producer), "output" (no consumer), or undefined (intermediate). */
@@ -748,4 +841,4 @@ declare const ARROW_CLOSED_MARKER = "arrowclosed";
 declare function nodeWidth(n: GraphNode): number;
 declare function nodeHeight(n: GraphNode): number;
 
-export { NODE_TYPE_PIPE_CARD as $, ARROW_CLOSED_MARKER as A, type FieldResolution as B, type ConceptInfo as C, type DataflowAnalysis as D, EDGE_TYPE as E, type FoldMode as F, type GraphTheme as G, GRAPH_DIRECTION as H, GRAPH_SPEC_MODE as I, GRAPH_THEME as J, GRAPH_THEME_MODE as K, type LabelDescriptor as L, type GraphSpecEdge as M, type NodeValidationSummary as N, type GraphSpecEdgeKind as O, type PipeBlueprintUnion as P, type GraphSpecMeta as Q, type GraphSpecModelUsage as R, type GraphSpecNodeError as S, type ToolbarPosition as T, type GraphSpecNodeIo as U, type ValidationIssue as V, type GraphSpecNodeTiming as W, type GraphSpecNodeUsage as X, type GraphSpecUsage as Y, KNOWN_PIPE_TYPES as Z, NODE_TYPE_CONTROLLER as _, type PresenceMarker as a, NODE_TYPE_STUFF as a0, type NodeKind as a1, type PipeBatchBlueprint as a2, type PipeBlueprintBase as a3, type PipeComposeBlueprint as a4, type PipeComposeConstructBlueprint as a5, type PipeComposeConstructField as a6, type PipeConditionBlueprint as a7, type PipeExtractBlueprint as a8, type PipeFuncBlueprint as a9, stuffDigestFromId as aA, stuffNodeId as aB, toolbarOrientation as aC, toolbarSide as aD, type PipeImgGenBlueprint as aa, type PipeLLMBlueprint as ab, type PipeParallelBlueprint as ac, type PipeSearchBlueprint as ad, type PipeSequenceBlueprint as ae, type PipeSignatureBlueprint as af, type PipeStructureBlueprint as ag, STUFF_ID_PREFIX as ah, type StuffMultiplicity as ai, type StuffRegistryEntry as aj, type StuffRole as ak, type StuffSpecInfo as al, type SubPipeSpec as am, TOOLBAR_POSITION as an, type TemplateBlueprint as ao, type ToolbarOrientation as ap, type ToolbarSide as aq, VALIDATION_STATE as ar, graphSpecMode as as, isDryGraphSpec as at, isPluralMultiplicity as au, isStaticGraphSpec as av, isStuffNodeId as aw, multiplicitySuffix as ax, nodeHeight as ay, nodeWidth as az, type GraphSpec as b, type GraphNodeData as c, type GraphEdge as d, type GraphNode as e, type GraphConfig as f, type GraphDirection as g, type GraphThemeMode as h, type PipeStatus as i, type GraphSpecNodeIoItem as j, type ValidationState as k, type PipeControllerType as l, type FoldToggleOptions as m, type PipeType as n, type GraphSpecMode as o, type GraphSpecNode as p, type PipeOperatorType as q, type PipeCallNode as r, type GraphData as s, type PipeCardPayload as t, type LayoutConfig as u, CONTROLLER_PADDING_BOTTOM as v, CONTROLLER_PADDING_TOP as w, CONTROLLER_PADDING_X as x, type EdgeType as y, FOLD_MODE as z };
+export { type GraphSpecNodeTiming as $, ARROW_CLOSED_MARKER as A, BINDING_STEP_TYPE as B, type ConceptInfo as C, type DataflowAnalysis as D, CONTROLLER_PADDING_TOP as E, type FoldMode as F, type GraphTheme as G, CONTROLLER_PADDING_X as H, EDGE_TYPE as I, type EdgeType as J, FOLD_MODE as K, type LabelDescriptor as L, type FieldResolution as M, type NodeValidationSummary as N, GRAPH_DIRECTION as O, type PipeBlueprintUnion as P, GRAPH_SPEC_MODE as Q, GRAPH_THEME as R, GRAPH_THEME_MODE as S, type ToolbarPosition as T, type GraphSpecEdge as U, type ValidationIssue as V, type GraphSpecEdgeKind as W, type GraphSpecMeta as X, type GraphSpecModelUsage as Y, type GraphSpecNodeError as Z, type GraphSpecNodeIo as _, type PresenceMarker as a, type GraphSpecNodeUsage as a0, type GraphSpecUsage as a1, type JudgmentQuestionSpec as a2, KNOWN_PIPE_TYPES as a3, NODE_TYPE_CONTROLLER as a4, NODE_TYPE_PIPE_CARD as a5, NODE_TYPE_STUFF as a6, type NodeKind as a7, type PipeBatchBlueprint as a8, type PipeBlueprintBase as a9, type ToolbarSide as aA, VALIDATION_STATE as aB, graphSpecMode as aC, isBindingNode as aD, isBindingStepSpec as aE, isDryGraphSpec as aF, isPluralMultiplicity as aG, isStaticGraphSpec as aH, isStuffNodeId as aI, multiplicitySuffix as aJ, nodeHeight as aK, nodeWidth as aL, stuffDigestFromId as aM, stuffNodeId as aN, toolbarOrientation as aO, toolbarSide as aP, type PipeComposeBlueprint as aa, type PipeComposeConstructBlueprint as ab, type PipeComposeConstructField as ac, type PipeConditionBlueprint as ad, type PipeDocGenBlueprint as ae, type PipeExtractBlueprint as af, type PipeFuncBlueprint as ag, type PipeImgGenBlueprint as ah, type PipeJudgeBlueprint as ai, type PipeLLMBlueprint as aj, type PipeParallelBlueprint as ak, type PipeSearchBlueprint as al, type PipeSequenceBlueprint as am, type PipeSignatureBlueprint as an, type PipeStructureBlueprint as ao, type PipeType as ap, STUFF_ID_PREFIX as aq, type SequenceStepSpec as ar, type StuffMultiplicity as as, type StuffRegistryEntry as at, type StuffRole as au, type StuffSpecInfo as av, type SubPipeSpec as aw, TOOLBAR_POSITION as ax, type TemplateBlueprint as ay, type ToolbarOrientation as az, type GraphSpec as b, type GraphNodeData as c, type GraphEdge as d, type GraphNode as e, type GraphConfig as f, type GraphDirection as g, type GraphThemeMode as h, type PipeStatus as i, type GraphSpecNodeIoItem as j, type ValidationState as k, type PipeControllerType as l, type FoldToggleOptions as m, type NodePipeType as n, type GraphSpecMode as o, type GraphSpecNode as p, type PipeOperatorType as q, type CardNode as r, type PipeCallNode as s, type GraphData as t, type PipeCardPayload as u, type LayoutConfig as v, type BindingNode as w, type BindingStepSpec as x, type BindingStepType as y, CONTROLLER_PADDING_BOTTOM as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipelex/mthds-ui",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "description": "Shared graph rendering logic for MTHDS method visualization",
   "license": "MIT",
   "repository": {

package/dist/chunk-AE7AA5XC.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/graph/types.ts"],"sourcesContent":["// ─── Pipe type taxonomy ─────────────────────────────────────────────────────\n// Operators perform work; controllers orchestrate other pipes.\n\nexport type PipeOperatorType =\n  | \"PipeLLM\"\n  | \"PipeExtract\"\n  | \"PipeCompose\"\n  | \"PipeImgGen\"\n  | \"PipeSearch\"\n  | \"PipeFunc\"\n  | \"PipeStructure\" // turns Text into a structured concept via an LLM\n  | \"PipeSignature\"; // contract-only stub — emitted under `--allow-signatures`\n\nexport type PipeControllerType = \"PipeSequence\" | \"PipeParallel\" | \"PipeCondition\" | \"PipeBatch\";\n\nexport type PipeType = PipeOperatorType | PipeControllerType;\n\n// Presence map over the full `PipeType` union — typed as `Record<PipeType, true>`\n// so adding a pipe class to the union without listing it here is a compile\n// error. `KNOWN_PIPE_TYPES` derives its keys from this map, keeping the runtime\n// check the validator performs in sync with the type.\nconst PIPE_TYPE_PRESENCE: Record<PipeType, true> = {\n  PipeLLM: true,\n  PipeExtract: true,\n  PipeCompose: true,\n  PipeImgGen: true,\n  PipeSearch: true,\n  PipeFunc: true,\n  PipeStructure: true,\n  PipeSignature: true,\n  PipeSequence: true,\n  PipeParallel: true,\n  PipeCondition: true,\n  PipeBatch: true,\n};\n\n/** Every pipe class name pipelex emits as `pipe_type`. Used by validateGraphSpec. */\nexport const KNOWN_PIPE_TYPES: ReadonlySet<string> = new Set(Object.keys(PIPE_TYPE_PRESENCE));\n\nexport type PipeStatus = \"succeeded\" | \"failed\" | \"running\" | \"scheduled\" | \"skipped\" | \"canceled\";\n\n// ─── GraphSpec mode contract ────────────────────────────────────────────────\n\nexport const GRAPH_SPEC_MODE = {\n  DRY: \"dry\",\n  LIVE: \"live\",\n  STATIC: \"static\",\n} as const;\n\nexport type GraphSpecMode = (typeof GRAPH_SPEC_MODE)[keyof typeof GRAPH_SPEC_MODE];\n\nexport interface GraphSpecMeta {\n  format: \"mthds\";\n  /**\n   * Missing mode is a legacy runtime graph. Static UI behavior must key only on\n   * `mode === \"static\"` and never infer it from absent runtime fields.\n   */\n  mode?: GraphSpecMode;\n  [key: string]: unknown;\n}\n\n// ─── Node type constants ────────────────────────────────────────────────────\n// Used by graphBuilders and consumed by ReactFlow custom node registration.\n\nexport const NODE_TYPE_PIPE_CARD = \"pipeCard\" as const;\nexport const NODE_TYPE_STUFF = \"default\" as const;\nexport const NODE_TYPE_CONTROLLER = \"controllerGroup\" as const;\n\n// ─── Stuff node ID helpers ──────────────────────────────────────────────────\n// Stuff (data) nodes use a \"stuff_<digest>\" convention throughout the graph.\n\nexport const STUFF_ID_PREFIX = \"stuff_\";\n\nexport function stuffNodeId(digest: string): string {\n  return STUFF_ID_PREFIX + digest;\n}\n\nexport function isStuffNodeId(id: string): boolean {\n  return id.startsWith(STUFF_ID_PREFIX);\n}\n\nexport function stuffDigestFromId(id: string): string {\n  return id.slice(STUFF_ID_PREFIX.length);\n}\n\n// ─── Stuff multiplicity ─────────────────────────────────────────────────────\n// How many values a stuff holds, in the encoding the pipe registry already uses\n// for `StuffSpecInfo.multiplicity`: `true` for a variable-length list (`Code[]`),\n// an integer for a fixed count (`Code[N]`), `null`/`false`/absent for a single\n// value. A count of exactly one is single throughout the MTHDS standard —\n// `Code[1]` is a way of writing `Code`, never a one-item list — so it reads as\n// single here too.\n\nexport type StuffMultiplicity = number | boolean | null;\n\n/** Whether a multiplicity declares a list: variable-length, or a fixed count of at least two. */\nexport function isPluralMultiplicity(multiplicity: StuffMultiplicity | undefined): boolean {\n  return multiplicity === true || (Number.isInteger(multiplicity) && (multiplicity as number) > 1);\n}\n\n/** The authored marker for a multiplicity — `\"[]\"`, `\"[N]\"`, or `\"\"` for a single value. */\nexport function multiplicitySuffix(multiplicity: StuffMultiplicity | undefined): string {\n  if (!isPluralMultiplicity(multiplicity)) return \"\";\n  return multiplicity === true ? \"[]\" : `[${multiplicity as number}]`;\n}\n\n// ─── GraphSpec types (from pipelex-agent --view output) ─────────────────────\n\nexport interface GraphSpecNodeIoItem {\n  name: string;\n  digest?: string;\n  /** The bare concept code or ref, never carrying a multiplicity marker — that is `multiplicity`. */\n  concept?: string;\n  /**\n   * How many values the stuff holds (see `StuffMultiplicity`). Emitted only on a\n   * plural stuff; absent means single. The static builder writes it, and a\n   * runtime graph carries it once its producer emits it, so a renderer must read\n   * absence as single rather than as unknown.\n   */\n  multiplicity?: StuffMultiplicity;\n  content_type?: string;\n  preview?: string;\n  size?: number;\n  data?: unknown;\n  data_text?: string;\n  data_html?: string;\n  extra?: Record<string, unknown>;\n}\n\nexport interface GraphSpecNodeIo {\n  inputs: GraphSpecNodeIoItem[];\n  outputs: GraphSpecNodeIoItem[];\n}\n\nexport type NodeKind =\n  | \"pipe_call\"\n  | \"controller\"\n  | \"operator\"\n  | \"input\"\n  | \"output\"\n  | \"artifact\"\n  | \"error\";\n\nexport interface GraphSpecNodeTiming {\n  started_at: string;\n  ended_at: string;\n  duration: number;\n}\n\nexport interface GraphSpecNodeError {\n  error_type: string;\n  message: string;\n  stack?: string;\n}\n\n/**\n * Inference usage attributed to one graph node — the mirror of pipelex's\n * `NodeUsageSpec`. Read the invariants before rendering any of these numbers;\n * getting them wrong means showing a wrong dollar figure, which is worse than\n * showing none.\n *\n *   1. `node.usage === undefined` is ALL-OR-NOTHING across a spec: it means the\n *      run reported no usage at all (collection off, or zero inference calls).\n *      As soon as one call was reported, EVERY node carries a usage object —\n *      zeroed for controllers, PipeFunc, PipeCompose, skipped and lifted pipes.\n *      So it never means \"this particular node was not measured\".\n *   2. `cost === null` ⟺ `rated_inference_calls === 0`. \"Made no call\" and \"made\n *      only unrated calls\" both land here; `inference_calls` tells them apart.\n *      Never render `null` as `$0.00` — a dry run is entirely unrated.\n *   3. `inference_calls > rated_inference_calls > 0` means `cost` is a LOWER\n *      BOUND, not a total. It must be marked (a leading \"≥\").\n *   4. `total_tokens` is input_joined + output. Do NOT sum\n *      `nb_tokens_by_category`: `input_cached` is a subset of `input`, not\n *      additive, so summing double-counts.\n *\n * The `subtree_*` half covers the node plus every descendant, rolled up by\n * pipelex so no consumer re-derives it. Controllers have only a subtree.\n */\n/**\n * What one inference model actually did for a node — the graph's only record of\n * the model that RAN.\n *\n * Everything else in a GraphSpec that names a model records what was *asked for*:\n * `execution_data.resolved_model` is the handle the pipe resolved to (often still\n * an alias like `@default-premium`, since aliases resolve at inference time), and\n * the blueprint holds the authored choice (`$writing-factual`). Only this survives\n * alias resolution, deck defaults, and any fallback or retry.\n *\n * `cost` follows the same rule as the node's: `null` iff no call to this model was\n * priced.\n */\nexport interface GraphSpecModelUsage {\n  inference_model_name: string;\n  inference_model_id: string;\n  /**\n   * Kind of inference: `\"llm\"`, `\"img_gen\"`, `\"extract\"`, `\"search\"`. Open set.\n   *\n   * The discriminator to check before displaying token counts: everything except\n   * `\"llm\"` is billed PER REQUEST, and pipelex encodes that price by putting\n   * `1_000_000` in each token category (rates are per-million), so those \"tokens\"\n   * are a scaled request counter rather than a measurement.\n   */\n  model_type: string;\n  inference_calls: number;\n  rated_inference_calls: number;\n  cost: number | null;\n}\n\nexport interface GraphSpecNodeUsage {\n  inference_calls: number;\n  rated_inference_calls: number;\n  nb_tokens_by_category: Record<string, number>;\n  total_tokens: number;\n  cost: number | null;\n  /** Components of `cost`; `input` is the joined input cost (non-cached + cached). */\n  cost_input: number | null;\n  cost_output: number | null;\n  /**\n   * The models that actually ran, most-used first. A list because one node\n   * routinely uses more than one — a PipeLLM's text pass and its object pass\n   * resolve separately — so `by_model[0]` is the dominant model, not \"the\" model.\n   */\n  by_model: GraphSpecModelUsage[];\n  subtree_inference_calls: number;\n  subtree_rated_inference_calls: number;\n  subtree_nb_tokens_by_category: Record<string, number>;\n  subtree_total_tokens: number;\n  subtree_cost: number | null;\n  subtree_cost_input: number | null;\n  subtree_cost_output: number | null;\n  /** Every model this node's whole branch used. */\n  subtree_by_model: GraphSpecModelUsage[];\n}\n\n/**\n * Run-level usage for a whole spec — the mirror of pipelex's `GraphUsageSpec`.\n *\n * `total` covers every call the run reported, attributed or not. `unattributed`\n * is the part that named no live node; on a healthy run it is zeroed, and a\n * non-zero one is worth surfacing rather than hiding. Neither has a subtree\n * distinct from itself, so their `subtree_*` fields repeat their own.\n */\nexport interface GraphSpecUsage {\n  total: GraphSpecNodeUsage;\n  unattributed: GraphSpecNodeUsage;\n}\n\nexport interface GraphSpecNode {\n  id: string;\n  kind: NodeKind;\n  pipe_code?: string;\n  pipe_type: PipeType;\n  description?: string;\n  domain_code?: string;\n  status: PipeStatus;\n  timing?: GraphSpecNodeTiming;\n  io: GraphSpecNodeIo;\n  error?: GraphSpecNodeError;\n  tags?: Record<string, string>;\n  metrics?: Record<string, number>;\n  usage?: GraphSpecNodeUsage;\n  execution_data?: Record<string, unknown>;\n}\n\n/**\n * A pipe-call node — the only node kind a real pipelex run emits. Narrowed\n * from `GraphSpecNode` for code paths that only ever render pipe-call nodes,\n * where `pipe_code` is guaranteed (validateGraphSpec enforces this).\n */\nexport type PipeCallNode = GraphSpecNode & {\n  kind: \"controller\" | \"operator\";\n  pipe_code: string;\n  pipe_type: PipeType;\n};\n\nexport type GraphSpecEdgeKind =\n  | \"contains\"\n  | \"data\"\n  | \"control\"\n  | \"selected_outcome\"\n  | \"batch_item\"\n  | \"batch_aggregate\"\n  | \"parallel_combine\";\n\nexport interface GraphSpecEdge {\n  id: string;\n  source: string;\n  target: string;\n  kind: GraphSpecEdgeKind;\n  label?: string;\n  source_stuff_digest?: string;\n  target_stuff_digest?: string;\n  meta?: Record<string, unknown>;\n}\n\n// ─── Concept and Pipe registry types ───────────────────────────────────────\n// Serialized from Python Concept and PipeAbstract instances via model_dump().\n//\n// Every field pipelex writes as `T | null` is declared `field?: T | null` here,\n// optional as well as nullable. Unlike `usage`, the registries cross the boundary\n// unvalidated, and a host that drops `null` values from the JSON it relays (ChatGPT\n// does, on the way to an MCP App view) delivers such a field with the key absent.\n// The optional marker is what makes the compiler refuse a strict `!== null` test\n// followed by a dereference.\n\n/**\n * A concept as the registry serializes it. A field that can be `null` is also\n * declared optional, because a host that drops `null` values delivers it absent:\n * test it with `!= null`, optional chaining or truthiness.\n */\nexport interface ConceptInfo {\n  code: string;\n  domain_code: string;\n  description: string;\n  structure_class_name: string;\n  refines?: string | null;\n  json_schema?: Record<string, unknown>;\n}\n\n/**\n * Presence of a value in a declared slot, mirroring the runtime's\n * `PresenceMarker`: `plain` (always present), `optional` (the `?` suffix — the\n * slot may legitimately hold no value), `force` (the `!` suffix — a use-site\n * assertion that the value must be present). The runtime defaults the field to\n * `plain`, so an absent `presence` reads as plain.\n */\nexport type PresenceMarker = \"plain\" | \"optional\" | \"force\";\n\nexport interface StuffSpecInfo {\n  concept: ConceptInfo;\n  multiplicity?: StuffMultiplicity;\n  presence?: PresenceMarker;\n}\n\n// ─── Template blueprint (shared by LLM prompts, Search, Compose, ImgGen) ───\n\nexport interface TemplateBlueprint {\n  template: string;\n  templating_style?: string | null;\n  category: string;\n  extra_context?: Record<string, unknown> | null;\n}\n\n// ─── Sub-pipe (used by Sequence, Parallel, Batch) ──────────────────────\n\nexport interface SubPipeSpec {\n  pipe_code: string;\n  output_name?: string | null;\n  output_multiplicity?: string | number | boolean | null;\n  batch_params?: { input_list_stuff_name: string; input_item_stuff_name: string } | null;\n}\n\n// ─── PipeAbstract base (common to all pipe types) ──────────────────────\n\nexport interface PipeBlueprintBase {\n  type: PipeType;\n  pipe_category: \"PipeOperator\" | \"PipeController\";\n  code: string;\n  domain_code: string;\n  description: string;\n  inputs: Record<string, StuffSpecInfo>;\n  output: StuffSpecInfo;\n}\n\n// ─── Operator blueprints ───────────────────────────────────────────────\n\nexport interface PipeLLMBlueprint extends PipeBlueprintBase {\n  type: \"PipeLLM\";\n  llm_prompt_spec: {\n    system_prompt_blueprint?: TemplateBlueprint | null;\n    prompt_blueprint?: TemplateBlueprint | null;\n    user_image_references?: unknown[] | null;\n    user_document_references?: unknown[] | null;\n    system_image_references?: unknown[] | null;\n    system_document_references?: unknown[] | null;\n  };\n  llm_choices?: { for_text?: string | null; for_object?: string | null } | null;\n  structuring_method?: string | null;\n  output_multiplicity?: string | number | null;\n}\n\nexport interface PipeImgGenBlueprint extends PipeBlueprintBase {\n  type: \"PipeImgGen\";\n  img_gen_prompt_blueprint: {\n    prompt_blueprint?: TemplateBlueprint | null;\n    negative_prompt_blueprint?: TemplateBlueprint | null;\n    image_references?: unknown[] | null;\n  };\n  img_gen_choice?: string | null;\n  aspect_ratio?: string | null;\n  is_raw?: boolean | null;\n  seed?: number | string | null;\n  background?: string | null;\n  output_format?: string | null;\n  output_multiplicity: number;\n}\n\n/**\n * A single field in a PipeCompose construct blueprint. Mirrors the\n * `ConstructFieldBlueprint` Pydantic model in pipelex. Exactly one of\n * `fixed_value` / `from_path` / `template` / `nested` is populated, matching\n * the `method` discriminator.\n *\n * - `fixed`    → `fixed_value` holds a literal (string, number, bool, list)\n * - `from_var` → `from_path` holds a dotted path into working memory,\n *                optionally with a `list_to_dict_keyed_by` modifier\n * - `template` → `template` holds a Jinja2 template string (per-field)\n * - `nested`   → `nested` holds a recursive construct blueprint for building\n *                nested structured content\n */\nexport interface PipeComposeConstructField {\n  method: \"from_var\" | \"fixed\" | \"template\" | \"nested\";\n  fixed_value?: unknown;\n  from_path?: string | null;\n  template?: string | null;\n  nested?: PipeComposeConstructBlueprint | null;\n  list_to_dict_keyed_by?: string | null;\n}\n\n/**\n * A PipeCompose construct blueprint, parsed from `[pipe.X.construct]` in MTHDS.\n * Mirrors the `ConstructBlueprint` Pydantic model in pipelex.\n */\nexport interface PipeComposeConstructBlueprint {\n  fields: Record<string, PipeComposeConstructField>;\n}\n\n/**\n * Per-field record of how each field was built at runtime, emitted by\n * `PipeCompose._run_construct_mode` in pipelex via `execution_data.fields`.\n *\n * - `method`   → which composition method was used (mirrors `ConstructFieldMethod`)\n * - `rendered` → present only for `template` fields, holds the Jinja2 output\n *\n * Nested fields record only their method; their sub-fields are not surfaced.\n */\nexport interface FieldResolution {\n  method: \"from_var\" | \"fixed\" | \"template\" | \"nested\";\n  rendered?: string;\n}\n\nexport interface PipeComposeBlueprint extends PipeBlueprintBase {\n  type: \"PipeCompose\";\n  /** Legacy monolithic template. Null when construct_blueprint is used instead. */\n  template?: string | null;\n  templating_style?: string | null;\n  category: string;\n  extra_context?: Record<string, unknown> | null;\n  /** Field-level construct form (e.g. `[pipe.X.construct]` in MTHDS). */\n  construct_blueprint?: PipeComposeConstructBlueprint | null;\n}\n\nexport interface PipeExtractBlueprint extends PipeBlueprintBase {\n  type: \"PipeExtract\";\n  extract_choice?: string | null;\n  should_caption_images: boolean;\n  max_page_images?: number | null;\n  should_include_page_views: boolean;\n  page_views_dpi?: number | null;\n  render_js?: boolean | null;\n  include_raw_html?: boolean | null;\n  image_stuff_name?: string | null;\n  document_stuff_name?: string | null;\n}\n\nexport interface PipeSearchBlueprint extends PipeBlueprintBase {\n  type: \"PipeSearch\";\n  search_choice?: string | null;\n  prompt_blueprint: TemplateBlueprint;\n  include_images_override?: boolean | null;\n  max_results_override?: number | null;\n  from_date?: string | null;\n  to_date?: string | null;\n  include_domains?: string[] | null;\n  exclude_domains?: string[] | null;\n  is_structured_output: boolean;\n}\n\nexport interface PipeFuncBlueprint extends PipeBlueprintBase {\n  type: \"PipeFunc\";\n}\n\n/**\n * A PipeStructure: an LLM-backed operator that turns a single Text-compatible\n * input into a structured concept. Serialized from the runtime `PipeStructure`,\n * so the registry entry carries the runtime fields below alongside the base.\n */\nexport interface PipeStructureBlueprint extends PipeBlueprintBase {\n  type: \"PipeStructure\";\n  /**\n   * LLM used to structure the text. A string model handle, an inline LLM\n   * setting object, or null (→ resolved from the model deck's `for_object`\n   * default at run time).\n   */\n  llm_choice?: string | Record<string, unknown> | null;\n  /** The single Text-compatible input variable the structuring reads. */\n  text_input_name: string;\n  /** `true` → let the LLM decide the count, a number → fixed count, null → single object. */\n  output_multiplicity?: boolean | number | null;\n}\n\n/**\n * A contract-only pipe: declares inputs + output but has no implementation.\n * Emitted under `--allow-signatures` so an in-progress bundle still validates\n * (dry-run mocks the declared output) before every referenced pipe is built.\n */\nexport interface PipeSignatureBlueprint extends Omit<PipeBlueprintBase, \"pipe_category\"> {\n  type: \"PipeSignature\";\n  /**\n   * Signatures sit outside the executable taxonomy, so pipelex serializes\n   * `pipe_category: null` (present, not omitted) — unlike operator/controller\n   * blueprints which carry \"PipeOperator\" / \"PipeController\". Optional all the\n   * same, since a host that drops `null` values delivers it absent.\n   */\n  pipe_category?: null;\n  /** Intended downstream pipe type once implemented — an optional hint. */\n  signature_for?: PipeType | null;\n}\n\n// ─── Controller blueprints ─────────────────────────────────────────────\n\nexport interface PipeSequenceBlueprint extends PipeBlueprintBase {\n  type: \"PipeSequence\";\n  sequential_sub_pipes: SubPipeSpec[];\n}\n\nexport interface PipeParallelBlueprint extends PipeBlueprintBase {\n  type: \"PipeParallel\";\n  parallel_sub_pipes: SubPipeSpec[];\n  add_each_output: boolean;\n  /**\n   * Removed from the language in pipelex 0.41 (a parallel always combines now),\n   * so 0.41 registry dumps omit the key entirely. Optional rather than deleted\n   * because the static builder still honors it as a legacy authoring key when\n   * naming the combined stuff, which L-260929-1e09e0 removes.\n   */\n  combined_output?: string | null;\n}\n\nexport interface PipeConditionBlueprint extends PipeBlueprintBase {\n  type: \"PipeCondition\";\n  expression: string;\n  outcome_map: Record<string, string>;\n  default_outcome: string;\n  add_alias_from_expression_to?: string | null;\n}\n\nexport interface PipeBatchBlueprint extends PipeBlueprintBase {\n  type: \"PipeBatch\";\n  branch_pipe_code: string;\n  batch_params: { input_list_stuff_name: string; input_item_stuff_name: string };\n}\n\n/**\n * A pipe as the registry serializes it, discriminated on `type`. A field that can\n * be `null` is also declared optional, because a host that drops `null` values\n * delivers it absent: test it with `!= null`, optional chaining or truthiness.\n */\nexport type PipeBlueprintUnion =\n  | PipeLLMBlueprint\n  | PipeImgGenBlueprint\n  | PipeComposeBlueprint\n  | PipeExtractBlueprint\n  | PipeSearchBlueprint\n  | PipeFuncBlueprint\n  | PipeStructureBlueprint\n  | PipeSignatureBlueprint\n  | PipeSequenceBlueprint\n  | PipeParallelBlueprint\n  | PipeConditionBlueprint\n  | PipeBatchBlueprint;\n\n// ─── GraphSpec top-level ───────────────────────────────────────────────────\n\nexport interface GraphSpec {\n  graph_id?: string;\n  created_at?: string;\n  pipeline_ref?: { domain?: string; main_pipe?: string; entrypoint?: string };\n  nodes: GraphSpecNode[];\n  edges: GraphSpecEdge[];\n  usage?: GraphSpecUsage;\n  meta?: GraphSpecMeta;\n  pipe_registry?: Record<string, PipeBlueprintUnion>;\n  concept_registry?: Record<string, ConceptInfo>;\n}\n\nexport function graphSpecMode(\n  spec: Pick<GraphSpec, \"meta\"> | null | undefined,\n): GraphSpecMode | undefined {\n  return spec?.meta?.mode;\n}\n\nexport function isStaticGraphSpec(spec: Pick<GraphSpec, \"meta\"> | null | undefined): boolean {\n  return graphSpecMode(spec) === GRAPH_SPEC_MODE.STATIC;\n}\n\nexport function isDryGraphSpec(spec: Pick<GraphSpec, \"meta\"> | null | undefined): boolean {\n  return graphSpecMode(spec) === GRAPH_SPEC_MODE.DRY;\n}\n\n// ─── Dataflow analysis result ───────────────────────────────────────────────\n\n/** One stuff as the dataflow analysis registers it, from the first io item naming its digest. */\nexport interface StuffRegistryEntry {\n  name: string;\n  concept?: string;\n  multiplicity?: StuffMultiplicity;\n  contentType?: string;\n}\n\nexport interface DataflowAnalysis {\n  readonly stuffRegistry: Readonly<Record<string, StuffRegistryEntry>>;\n  readonly stuffProducers: Readonly<Record<string, string>>;\n  readonly stuffConsumers: Readonly<Record<string, readonly string[]>>;\n  readonly controllerNodeIds: ReadonlySet<string>;\n  readonly childNodeIds: ReadonlySet<string>;\n  readonly containmentTree: Readonly<Record<string, readonly string[]>>;\n}\n\n// ─── Graph configuration ────────────────────────────────────────────────────\n\nexport const GRAPH_DIRECTION = {\n  TB: \"TB\",\n  BT: \"BT\",\n  LR: \"LR\",\n  RL: \"RL\",\n} as const;\n\nexport type GraphDirection = (typeof GRAPH_DIRECTION)[keyof typeof GRAPH_DIRECTION];\n\nexport const EDGE_TYPE = {\n  /** Bezier curve — ReactFlow v12 renamed this type from \"bezier\" to \"default\". */\n  DEFAULT: \"default\",\n  STEP: \"step\",\n  STRAIGHT: \"straight\",\n  SMOOTH_STEP: \"smoothstep\",\n} as const;\n\nexport type EdgeType = (typeof EDGE_TYPE)[keyof typeof EDGE_TYPE];\n\nexport const FOLD_MODE = {\n  /** Every pipe controller folded into a single pipe card. */\n  FOLDED: \"folded\",\n  /** Every pipe controller expanded as a group wrapper. */\n  EXPANDED: \"expanded\",\n  /** Renderer decides — reserved for future heuristics; currently behaves like EXPANDED. */\n  AUTO: \"auto\",\n} as const;\n\nexport type FoldMode = (typeof FOLD_MODE)[keyof typeof FOLD_MODE];\n\n/**\n * The *resolved* binary theme — the value that actually drives the palette and\n * the container class. `getPaletteForTheme` takes this. `system` is never a\n * resolved theme; it resolves to one of these via the environment.\n */\nexport const GRAPH_THEME = {\n  DARK: \"dark\",\n  LIGHT: \"light\",\n} as const;\n\nexport type GraphTheme = (typeof GRAPH_THEME)[keyof typeof GRAPH_THEME];\n\n/**\n * The user's theme *selection* — what the toolbar cycles, what gets persisted\n * and reported. `system` follows the host environment (browser `prefers-color-scheme`\n * or an injected `systemTheme`) and resolves to a binary `GraphTheme` at render\n * time. The `dark`/`light` overlap with `GraphTheme` is intentional: a resolved\n * theme is also a valid mode.\n */\nexport const GRAPH_THEME_MODE = {\n  DARK: \"dark\",\n  LIGHT: \"light\",\n  SYSTEM: \"system\",\n} as const;\n\nexport type GraphThemeMode = (typeof GRAPH_THEME_MODE)[keyof typeof GRAPH_THEME_MODE];\n\n/**\n * Anchor for the built-in floating toolbar. The values match ReactFlow's\n * `PanelPosition` union exactly, so they pass straight to `<Panel position=…>`\n * (the React layer asserts that subset relationship at compile time). Orientation\n * is *derived* from the position, never configured independently — see\n * `toolbarOrientation`: only the two edge-center anchors are vertical, everything\n * else (corners + top/bottom-center) is a horizontal bar.\n *\n * `types.ts` stays React-free, so `PanelPosition` is intentionally NOT imported\n * here — the compatibility assertion lives in `GraphToolbar.tsx`.\n */\nexport const TOOLBAR_POSITION = {\n  TOP_LEFT: \"top-left\",\n  TOP_CENTER: \"top-center\",\n  TOP_RIGHT: \"top-right\",\n  BOTTOM_LEFT: \"bottom-left\",\n  BOTTOM_CENTER: \"bottom-center\",\n  BOTTOM_RIGHT: \"bottom-right\",\n  CENTER_LEFT: \"center-left\",\n  CENTER_RIGHT: \"center-right\",\n} as const;\n\nexport type ToolbarPosition = (typeof TOOLBAR_POSITION)[keyof typeof TOOLBAR_POSITION];\n\nexport type ToolbarOrientation = \"horizontal\" | \"vertical\";\n\n/**\n * Derive the bar orientation from its anchor. \"Corners are horizontal, edges\n * decide the rest\": only `center-left` / `center-right` produce a vertical bar;\n * every other position (the four corners plus `top-center` / `bottom-center`) is\n * horizontal. Pure + React-free so it is unit-testable without rendering.\n */\nexport function toolbarOrientation(position: ToolbarPosition): ToolbarOrientation {\n  return position === TOOLBAR_POSITION.CENTER_LEFT || position === TOOLBAR_POSITION.CENTER_RIGHT\n    ? \"vertical\"\n    : \"horizontal\";\n}\n\nexport type ToolbarSide = \"left\" | \"center\" | \"right\";\n\n/**\n * Derive which edge the anchor hugs. The built-in `DetailPanel` overlays the\n * right edge, so only right-side anchors (`*-right`) need to dodge it — the\n * toolbar reads this to decide whether to shift left while the panel is open.\n * Pure + React-free so it is unit-testable without rendering, and exhaustively\n * switched so adding a `TOOLBAR_POSITION` value without a side fails to compile\n * — exactly like {@link toolbarOrientation}.\n */\nexport function toolbarSide(position: ToolbarPosition): ToolbarSide {\n  switch (position) {\n    case TOOLBAR_POSITION.TOP_LEFT:\n    case TOOLBAR_POSITION.CENTER_LEFT:\n    case TOOLBAR_POSITION.BOTTOM_LEFT:\n      return \"left\";\n    case TOOLBAR_POSITION.TOP_RIGHT:\n    case TOOLBAR_POSITION.CENTER_RIGHT:\n    case TOOLBAR_POSITION.BOTTOM_RIGHT:\n      return \"right\";\n    case TOOLBAR_POSITION.TOP_CENTER:\n    case TOOLBAR_POSITION.BOTTOM_CENTER:\n      return \"center\";\n    default: {\n      const _exhaustive: never = position;\n      return _exhaustive;\n    }\n  }\n}\n\n// ─── Validation status (toolbar widget) ──────────────────────────────────────\n\n/**\n * State of the toolbar's validation widget. The widget itself is opt-in: it\n * renders only when the host passes a `validationState` to `GraphViewer` —\n * `undefined` (the default) keeps it hidden entirely. The states describe the\n * host's validation lifecycle, not the static analyzer's: `validating` while a\n * verdict is being produced, `valid`/`invalid` once one exists, and `error`\n * when no verdict could be produced at all (validator unavailable, timeout…).\n * `unvalidated` is for a host with no validator at all, such as a page drawing\n * a method from its source: no verdict exists or is coming, and the issues are\n * what reading the source turned up.\n */\nexport const VALIDATION_STATE = {\n  VALIDATING: \"validating\",\n  VALID: \"valid\",\n  INVALID: \"invalid\",\n  ERROR: \"error\",\n  UNVALIDATED: \"unvalidated\",\n} as const;\n\nexport type ValidationState = (typeof VALIDATION_STATE)[keyof typeof VALIDATION_STATE];\n\n/**\n * One issue row in the validation panel. Mostly presentation: the host decides\n * which issues to show for each state (its validator's errors, the static\n * analyzer's diagnostics, or a mix) and handles navigation on row click. The\n * only fields the viewer interprets are the optional targeting fields\n * (`pipeRef` / `nodeId`), which drive node decorations on the graph.\n */\nexport interface ValidationIssue {\n  severity: \"error\" | \"warning\";\n  message: string;\n  /** Short locator chip, e.g. `pipe.analyze_candidate` or a TOML path. */\n  context?: string;\n  /** Owning-file basename, when the issue lives in a specific file. */\n  file?: string;\n  /** Human-readable suggested fix, when the validator derived one. */\n  suggestedFix?: string;\n  /** Which analyzer produced the issue: the host's validator or the static parser. */\n  origin?: \"validator\" | \"static\";\n  /**\n   * Fully-qualified pipe ref (`domain_code.pipe_code`, see `makePipeRef`) this\n   * issue targets — decorates every rendered node invoking that pipe (a pipe\n   * can be invoked from several places in the graph). Always qualified, never a\n   * bare code: two domains may declare the same pipe code, and a bare match\n   * would ring every same-code node. An emitter that cannot qualify must leave\n   * the issue untargeted (panel-only) rather than decorate by guess.\n   */\n  pipeRef?: string;\n  /**\n   * Precise invocation this issue targets — a GraphSpec node id (e.g.\n   * `demo.main_flow/step_2`). Takes precedence over `pipeRef` when both are\n   * set. Issues with neither targeting field stay panel-only.\n   */\n  nodeId?: string;\n}\n\n/**\n * Aggregated validation decoration for one rendered node — derived from the\n * targeted `ValidationIssue`s by `buildValidationDecorations` (worst severity\n * wins, folded controllers roll up their hidden descendants' issues). Rendered\n * as a severity ring + count badge on the node, with `lines` as the tooltip.\n */\nexport interface NodeValidationSummary {\n  /** Worst severity among the node's issues (`error` wins over `warning`). */\n  severity: \"error\" | \"warning\";\n  /** Number of issue hits on the node (a multi-instance pipe counts per invocation). */\n  count: number;\n  /** Tooltip lines: each issue's message, followed by a `Fix: …` line when present. */\n  lines: string[];\n}\n\nexport interface GraphConfig {\n  direction?: GraphDirection;\n  showControllers?: boolean;\n  foldMode?: FoldMode;\n  /**\n   * Theme *mode*: `dark | light | system`. `system` follows the host environment.\n   * Defaults to `system` (see `DEFAULT_GRAPH_CONFIG`). Pass `dark`/`light` to pin\n   * a fixed appearance.\n   */\n  theme?: GraphThemeMode;\n  /**\n   * Anchor for the built-in floating toolbar (default `top-right`). Orientation\n   * is derived from the position — see {@link toolbarOrientation}. The\n   * `toolbarPosition` *prop* on `GraphViewer` takes precedence over this; both\n   * are reactive and persistence is the host's responsibility.\n   */\n  toolbarPosition?: ToolbarPosition;\n  nodesep?: number;\n  ranksep?: number;\n  edgeType?: EdgeType;\n  initialZoom?: number | null;\n  panToTop?: boolean;\n  paletteColors?: Record<string, string>;\n}\n\n// ─── Label descriptors ──────────────────────────────────────────────────────\n// Plain objects, no React dependency. GraphViewer maps these to React elements.\n\nexport type LabelDescriptor =\n  | { kind: \"pipe\"; label: string; isFailed: boolean }\n  | { kind: \"stuff\"; label: string; concept: string };\n\n// ─── Fold toggle options ────────────────────────────────────────────────────\n// Passed by UI click handlers so the orchestrator can decide whether the\n// toggle should propagate to \"cousin\" controllers (other instances of the\n// same pipe) or affect only the clicked one.\n\nexport interface FoldToggleOptions {\n  /**\n   * When `true`, the toggle applies only to the clicked controller — its\n   * cousins (other controller nodes sharing the same `pipe_code`) are left\n   * untouched. Wired to the alt/option modifier key in the click handlers.\n   */\n  soloMode?: boolean;\n}\n\n// ─── Pipe card payload ──────────────────────────────────────────────────────\n// Built by graphBuilders, consumed by PipeCardNode in the React layer.\n\nexport interface PipeCardPayload {\n  pipeCode: string;\n  pipeType: PipeType;\n  description?: string;\n  status: PipeStatus;\n  graphMode?: GraphSpecMode;\n  inputs: { name: string; concept: string }[];\n  outputs: { name: string; concept: string }[];\n  /** Authored/static annotations and runtime tags carried by the GraphSpec node. */\n  tags?: Record<string, string>;\n  /** Layout direction — injected by the layout engine */\n  direction?: \"LR\" | \"TB\";\n  /** When set, the card renders an unfold button that invokes this callback. */\n  onExpand?: (options?: FoldToggleOptions) => void;\n  /** Validation decoration (severity ring + count badge), stamped by GraphViewer. */\n  validation?: NodeValidationSummary;\n  /** Badge click handler (opens the validation panel), stamped alongside `validation`. */\n  onValidationBadgeClick?: () => void;\n}\n\n// ─── Graph node data ────────────────────────────────────────────────────────\n// Extends Record<string, unknown> for ReactFlow's Node<T> generic parameter.\n\nexport type StuffRole = \"input\" | \"output\" | \"combined\";\n\nexport interface GraphNodeData extends Record<string, unknown> {\n  labelDescriptor?: LabelDescriptor;\n  label?: unknown;\n  nodeData?: GraphSpecNode;\n  isPipe: boolean;\n  isStuff: boolean;\n  isController?: boolean;\n  labelText: string;\n  pipeCode?: string;\n  pipeType?: PipeType;\n  graphMode?: GraphSpecMode;\n  pipeCardData?: PipeCardPayload;\n  /** For stuff nodes: \"input\" (no producer), \"output\" (no consumer), or undefined (intermediate). */\n  stuffRole?: StuffRole;\n  /** For stuff nodes: the digest used to build the node ID. */\n  stuffDigest?: string;\n  /** Validation decoration (severity ring + count badge), stamped by GraphViewer. */\n  validation?: NodeValidationSummary;\n  /** Badge click handler (opens the validation panel), stamped alongside `validation`. */\n  onValidationBadgeClick?: () => void;\n}\n\n// ─── Graph node / edge / data ───────────────────────────────────────────────\n\nexport interface GraphNode {\n  id: string;\n  type: string;\n  data: GraphNodeData;\n  position: { x: number; y: number };\n  style?: Record<string, string | number>;\n  sourcePosition?: \"top\" | \"bottom\" | \"left\" | \"right\";\n  targetPosition?: \"top\" | \"bottom\" | \"left\" | \"right\";\n  parentId?: string;\n  extent?: \"parent\";\n  selected?: boolean;\n}\n\nexport interface GraphEdge {\n  id: string;\n  source: string;\n  target: string;\n  type: string;\n  animated?: boolean;\n  label?: string;\n  labelStyle?: Record<string, string | number>;\n  labelBgStyle?: Record<string, string | number>;\n  labelBgPadding?: [number, number];\n  labelBgBorderRadius?: number;\n  style?: Record<string, string | number>;\n  markerEnd?: { type: string; color: string };\n  _batchEdge?: boolean;\n  _crossGroup?: boolean;\n}\n\nexport interface GraphData {\n  nodes: GraphNode[];\n  edges: GraphEdge[];\n}\n\n// ─── Layout ─────────────────────────────────────────────────────────────────\n\nexport interface LayoutConfig {\n  nodesep?: number;\n  ranksep?: number;\n}\n\n// Controller padding constants (shared between layout and controller modules)\nexport const CONTROLLER_PADDING_X = 40;\nexport const CONTROLLER_PADDING_TOP = 48;\nexport const CONTROLLER_PADDING_BOTTOM = 20;\n\n// Default marker type string (avoids ReactFlow dependency in pure modules)\nexport const ARROW_CLOSED_MARKER = \"arrowclosed\";\n\n// ─── Node dimension helpers ─────────────────────────────────────────────────\n// Extract dimensions from style. Used by buildControllerNodes.\n// NOT used by getLayoutedElements, which estimates dimensions before styles exist.\n\nexport function nodeWidth(n: GraphNode): number {\n  const raw = n.style?.width;\n  if (raw == null) return 200;\n  const w = typeof raw === \"number\" ? raw : parseFloat(raw);\n  return isNaN(w) || w <= 0 ? 200 : w;\n}\n\nexport function nodeHeight(n: GraphNode): number {\n  const raw = n.style?.height;\n  if (raw != null) {\n    const h = typeof raw === \"number\" ? raw : parseFloat(raw);\n    if (!isNaN(h) && h > 0) return h;\n  }\n  return n.data?.isStuff ? 60 : 70;\n}\n"],"mappings":";AAqBA,IAAM,qBAA6C;AAAA,EACjD,SAAS;AAAA,EACT,aAAa;AAAA,EACb,aAAa;AAAA,EACb,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,eAAe;AAAA,EACf,eAAe;AAAA,EACf,cAAc;AAAA,EACd,cAAc;AAAA,EACd,eAAe;AAAA,EACf,WAAW;AACb;AAGO,IAAM,mBAAwC,IAAI,IAAI,OAAO,KAAK,kBAAkB,CAAC;AAMrF,IAAM,kBAAkB;AAAA,EAC7B,KAAK;AAAA,EACL,MAAM;AAAA,EACN,QAAQ;AACV;AAiBO,IAAM,sBAAsB;AAC5B,IAAM,kBAAkB;AACxB,IAAM,uBAAuB;AAK7B,IAAM,kBAAkB;AAExB,SAAS,YAAY,QAAwB;AAClD,SAAO,kBAAkB;AAC3B;AAEO,SAAS,cAAc,IAAqB;AACjD,SAAO,GAAG,WAAW,eAAe;AACtC;AAEO,SAAS,kBAAkB,IAAoB;AACpD,SAAO,GAAG,MAAM,gBAAgB,MAAM;AACxC;AAaO,SAAS,qBAAqB,cAAsD;AACzF,SAAO,iBAAiB,QAAS,OAAO,UAAU,YAAY,KAAM,eAA0B;AAChG;AAGO,SAAS,mBAAmB,cAAqD;AACtF,MAAI,CAAC,qBAAqB,YAAY,EAAG,QAAO;AAChD,SAAO,iBAAiB,OAAO,OAAO,IAAI,YAAsB;AAClE;AAkeO,SAAS,cACd,MAC2B;AA5kB7B;AA6kBE,UAAO,kCAAM,SAAN,mBAAY;AACrB;AAEO,SAAS,kBAAkB,MAA2D;AAC3F,SAAO,cAAc,IAAI,MAAM,gBAAgB;AACjD;AAEO,SAAS,eAAe,MAA2D;AACxF,SAAO,cAAc,IAAI,MAAM,gBAAgB;AACjD;AAuBO,IAAM,kBAAkB;AAAA,EAC7B,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AAIO,IAAM,YAAY;AAAA;AAAA,EAEvB,SAAS;AAAA,EACT,MAAM;AAAA,EACN,UAAU;AAAA,EACV,aAAa;AACf;AAIO,IAAM,YAAY;AAAA;AAAA,EAEvB,QAAQ;AAAA;AAAA,EAER,UAAU;AAAA;AAAA,EAEV,MAAM;AACR;AASO,IAAM,cAAc;AAAA,EACzB,MAAM;AAAA,EACN,OAAO;AACT;AAWO,IAAM,mBAAmB;AAAA,EAC9B,MAAM;AAAA,EACN,OAAO;AAAA,EACP,QAAQ;AACV;AAeO,IAAM,mBAAmB;AAAA,EAC9B,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,aAAa;AAAA,EACb,eAAe;AAAA,EACf,cAAc;AAAA,EACd,aAAa;AAAA,EACb,cAAc;AAChB;AAYO,SAAS,mBAAmB,UAA+C;AAChF,SAAO,aAAa,iBAAiB,eAAe,aAAa,iBAAiB,eAC9E,aACA;AACN;AAYO,SAAS,YAAY,UAAwC;AAClE,UAAQ,UAAU;AAAA,IAChB,KAAK,iBAAiB;AAAA,IACtB,KAAK,iBAAiB;AAAA,IACtB,KAAK,iBAAiB;AACpB,aAAO;AAAA,IACT,KAAK,iBAAiB;AAAA,IACtB,KAAK,iBAAiB;AAAA,IACtB,KAAK,iBAAiB;AACpB,aAAO;AAAA,IACT,KAAK,iBAAiB;AAAA,IACtB,KAAK,iBAAiB;AACpB,aAAO;AAAA,IACT,SAAS;AACP,YAAM,cAAqB;AAC3B,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAeO,IAAM,mBAAmB;AAAA,EAC9B,YAAY;AAAA,EACZ,OAAO;AAAA,EACP,SAAS;AAAA,EACT,OAAO;AAAA,EACP,aAAa;AACf;AAmMO,IAAM,uBAAuB;AAC7B,IAAM,yBAAyB;AAC/B,IAAM,4BAA4B;AAGlC,IAAM,sBAAsB;AAM5B,SAAS,UAAU,GAAsB;AA38BhD;AA48BE,QAAM,OAAM,OAAE,UAAF,mBAAS;AACrB,MAAI,OAAO,KAAM,QAAO;AACxB,QAAM,IAAI,OAAO,QAAQ,WAAW,MAAM,WAAW,GAAG;AACxD,SAAO,MAAM,CAAC,KAAK,KAAK,IAAI,MAAM;AACpC;AAEO,SAAS,WAAW,GAAsB;AAl9BjD;AAm9BE,QAAM,OAAM,OAAE,UAAF,mBAAS;AACrB,MAAI,OAAO,MAAM;AACf,UAAM,IAAI,OAAO,QAAQ,WAAW,MAAM,WAAW,GAAG;AACxD,QAAI,CAAC,MAAM,CAAC,KAAK,IAAI,EAAG,QAAO;AAAA,EACjC;AACA,WAAO,OAAE,SAAF,mBAAQ,WAAU,KAAK;AAChC;","names":[]}