@pipelex/mthds-ui 0.26.0 → 0.28.0

package/README.md

@@ -37,11 +37,11 @@ If you render the React components, one setup step follows the install: the form
 import { GraphViewer } from "@pipelex/mthds-ui/graph/react";
 
 function MethodGraph({ graphspec }) {
-  return <GraphViewer graphspec={graphspec} />;
+  return <GraphViewer graph={{ graphSpec: graphspec }} />;
 }
 ```
 
-That's it. `GraphViewer` handles layout, styling, CSS variables, and all ReactFlow internals. All props except `graphspec` are optional with sensible defaults. The one exception to "styling" is the detail panel's data view, which shows a result through the form kernel's controls; those are styled by your app, as [Styling the form controls](#styling-the-form-controls) describes.
+That's it. `GraphViewer` handles layout, styling, CSS variables, and all ReactFlow internals. All props except `graph` are optional with sensible defaults. The one exception to "styling" is the detail panel's data view, which shows a result through the form kernel's controls; those are styled by your app, as [Styling the form controls](#styling-the-form-controls) describes.
 
 ### Next.js (App Router)
 
@@ -63,15 +63,29 @@ const GraphViewer = dynamic(
 ) as React.ComponentType<GraphViewerProps>;
 
 export function MyGraph({ graphspec }) {
-  return <GraphViewer graphspec={graphspec} />;
+  return <GraphViewer graph={{ graphSpec: graphspec }} />;
 }
 ```
 
+### Showing what a run produced
+
+`graph` carries the spec together with the artifacts that describe its pipes, and the detail panel uses them to lay a data node's value out. They must all come from one source, because the panel looks each value's descriptor up by the `pipe_ref` of the pipe that produced it in this graph: a run's own results, or a method's validate report beside that method's dry or static graph. A run's results carry all four, and `graphArtifactsFrom` reads them in one call:
+
+```tsx
+import { GraphViewer, graphArtifactsFrom } from "@pipelex/mthds-ui/graph/react";
+
+// results: { graph_spec, pipe_io_contracts, output_form, input_form }
+const graph = graphArtifactsFrom(results);
+return <GraphViewer graph={graph} />;
+```
+
+Without `pipeIoContracts` and `outputForm` the panel shows each concept's structure table and no data tab. See [docs/stuff-result-panel.md](docs/stuff-result-panel.md).
+
 ### GraphViewer props
 
 | Prop               | Type                                              | Default                | Description                              |
 | ------------------ | ------------------------------------------------- | ---------------------- | ---------------------------------------- |
-| `graphspec`        | `GraphSpec \| null`                               | —                      | Graph data (nodes + edges)               |
+| `graph`            | `GraphArtifacts \| null`                          | —                      | The spec and its descriptors, one source |
 | `config`           | `GraphConfig`                                     | `DEFAULT_GRAPH_CONFIG` | Layout and visual configuration          |
 | `direction`        | `GraphDirection`                                  | `"LR"`                 | Layout direction: `TB`, `LR`, `RL`, `BT` |
 | `showControllers`  | `boolean`                                         | `false`                | Show controller group outlines           |
@@ -237,7 +251,7 @@ const myConfig = {
 
 ```tsx
 <GraphViewer
-  graphspec={graphspec}
+  graph={{ graphSpec: graphspec }}
   config={{
     ...DEFAULT_GRAPH_CONFIG,
     paletteColors: {

package/dist/{chunk-XBHDA3PQ.js → chunk-7WJYQHYF.js}

@@ -4,7 +4,7 @@ import {
   GRAPH_THEME,
   GRAPH_THEME_MODE,
   TOOLBAR_POSITION
-} from "./chunk-VCO4GZDZ.js";
+} from "./chunk-AE7AA5XC.js";
 import {
   __spreadProps,
   __spreadValues
@@ -192,4 +192,4 @@ export {
   DEFAULT_GRAPH_CONFIG,
   getPaletteColors
 };
-//# sourceMappingURL=chunk-XBHDA3PQ.js.map
+//# sourceMappingURL=chunk-7WJYQHYF.js.map

package/dist/{chunk-VCO4GZDZ.js → chunk-AE7AA5XC.js}

@@ -170,4 +170,4 @@ export {
   nodeWidth,
   nodeHeight
 };
-//# sourceMappingURL=chunk-VCO4GZDZ.js.map
+//# sourceMappingURL=chunk-AE7AA5XC.js.map

package/dist/{chunk-VCO4GZDZ.js.map → chunk-AE7AA5XC.js.map}

@@ -1 +1 @@
-{"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 — see `wip/pr-63-review-notes.md`.\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":"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","names":[]}
+{"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":"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","names":[]}

package/dist/{chunk-K3BWHQVX.js → chunk-I7Z5TTQI.js}

@@ -17,7 +17,7 @@ import {
   nodeWidth,
   stuffDigestFromId,
   stuffNodeId
-} from "./chunk-VCO4GZDZ.js";
+} from "./chunk-AE7AA5XC.js";
 import {
   __objRest,
   __spreadProps,
@@ -1663,4 +1663,4 @@ export {
   buildControllerNodes,
   applyControllers
 };
-//# sourceMappingURL=chunk-K3BWHQVX.js.map
+//# sourceMappingURL=chunk-I7Z5TTQI.js.map

package/dist/form/react/RunPanel.css

@@ -89,9 +89,7 @@
      token, so nothing else shifts as a consequence.
 
      `src/form/__tests__/contrast.test.ts` reads these two literals back and
-     holds them to the AA line — including the `var()` they must not become. And
-     `wip/adopt-form/deferred-run-button-contrast.md` records the alternatives
-     that were weighed. */
+     holds them to the AA line — including the `var()` they must not become. */
   background: #0369a1;
   color: #ffffff;
   font-family: inherit;

package/dist/form/react/index.d.ts

@@ -2,7 +2,7 @@ import { FieldEnv } from '@pipelex/mthds-form/react';
 export * from '@pipelex/mthds-form/react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ValidationMessageKey, PipeIOContract, RunField, RunInputError, PipeInputFormDescriptor } from '@pipelex/mthds-form';
-import { G as GraphTheme } from '../../types-DgqW3Jg4.js';
+import { G as GraphTheme } from '../../types-DvhUuMHz.js';
 
 /**
  * The panel's submit path, kept React-free.
@@ -102,7 +102,7 @@ interface RunPanelProps {
      * with the kernel's `getPipeIOContract(contracts, domain, pipeCode)`. The
      * panel deliberately does NOT accept a `GraphSpec` and derive a contract from
      * it — deriving field meaning locally is precisely what this component exists
-     * not to do (design Decision A).
+     * not to do.
      */
     contract: PipeIOContract;
     /**
@@ -224,9 +224,9 @@ interface RunPanelProps {
  * `runSubmitGate` (over the kernel's four steps) decides what goes on the wire.
  * What lives here is layout: which fields are visible, where the toggle and the
  * button sit, and how a rejected verdict is shown. The panel never reads
- * `json_schema` to make a rendering decision and never sniffs a value's shape
- * (design Decision C) — which is what keeps a change to the kernel's derivation
- * invisible to this repo.
+ * `json_schema` to make a rendering decision and never sniffs a value's shape,
+ * since meaning is the kernel's — which is what keeps a change to the kernel's
+ * derivation invisible to this repo.
  */
 declare function RunPanel({ contract, descriptor, values, onValuesChange, onRun, running, env, uploadFile, title, theme, translate, idPrefix, className, }: RunPanelProps): react_jsx_runtime.JSX.Element;
 

package/dist/form/react/index.js

@@ -1,10 +1,10 @@
 "use client";
 import {
   getPaletteForTheme
-} from "../../chunk-XBHDA3PQ.js";
+} from "../../chunk-7WJYQHYF.js";
 import {
   GRAPH_THEME
-} from "../../chunk-VCO4GZDZ.js";
+} from "../../chunk-AE7AA5XC.js";
 import {
   __spreadProps,
   __spreadValues