@pipelex/mthds-ui 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pipelex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# @pipelex/mthds-ui
+
+Interactive graph visualization for [MTHDS](https://mthds.sh) method pipelines. Renders execution graphs from [GraphSpec](https://docs.pipelex.com/latest/under-the-hood/execution-graph-tracing/#graphspec) data — the canonical format produced by [Pipelex](https://pipelex.com) when tracing pipeline execution.
+
+Core graph logic (builders, layout, analysis) is pure TypeScript with no React dependency. The React layer provides a drop-in `GraphViewer` component powered by [ReactFlow](https://reactflow.dev).
+
+## Install
+
+```bash
+npm install @pipelex/mthds-ui
+```
+
+Released versions are listed on the [npm page](https://www.npmjs.com/package/@pipelex/mthds-ui) and the [GitHub releases page](https://github.com/Pipelex/mthds-ui/releases).
+
+### Peer dependencies
+
+| Dependency           | Required | Used by                       |
+| -------------------- | -------- | ----------------------------- |
+| `react`, `react-dom` | no       | React layer (`graph/react`)   |
+| `shiki`              | no       | Syntax highlighting (`shiki`) |
+
+### Bundled dependencies
+
+| Dependency      | License | Used by                         |
+| --------------- | ------- | ------------------------------- |
+| `elkjs`         | EPL-2.0 | Graph layout engine             |
+| `@xyflow/react` | MIT     | Graph rendering (`graph/react`) |
+
+`elkjs` (Eclipse Layout Kernel) is licensed under the [Eclipse Public License 2.0](https://www.eclipse.org/legal/epl-2.0/). See [NOTICE](./NOTICE) for details.
+
+## Quick start (React)
+
+```tsx
+import { GraphViewer } from "@pipelex/mthds-ui/graph/react";
+
+function MethodGraph({ graphspec }) {
+  return <GraphViewer graphspec={graphspec} />;
+}
+```
+
+That's it. `GraphViewer` handles layout, styling, CSS variables, and all ReactFlow internals. All props except `graphspec` are optional with sensible defaults.
+
+### Next.js (App Router)
+
+ReactFlow accesses browser globals at module-evaluation time, so it cannot be server-side rendered. Use `next/dynamic` with `ssr: false`:
+
+```tsx
+"use client";
+
+import dynamic from "next/dynamic";
+import type { GraphViewerProps } from "@pipelex/mthds-ui/graph/react";
+import React from "react";
+
+const GraphViewer = dynamic(
+  () =>
+    import("@pipelex/mthds-ui/graph/react").then((mod) => ({
+      default: mod.GraphViewer,
+    })),
+  { ssr: false },
+) as React.ComponentType<GraphViewerProps>;
+
+export function MyGraph({ graphspec }) {
+  return <GraphViewer graphspec={graphspec} />;
+}
+```
+
+### GraphViewer props
+
+| Prop               | Type                                              | Default                | Description                              |
+| ------------------ | ------------------------------------------------- | ---------------------- | ---------------------------------------- |
+| `graphspec`        | `GraphSpec \| null`                               | —                      | Graph data (nodes + edges)               |
+| `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           |
+| `onNavigateToPipe` | `(pipeCode: string, status?: PipeStatus) => void` | —                      | Callback when a pipe node is clicked     |
+| `onReactFlowInit`  | `(instance: AppRFInstance) => void`               | —                      | Access the underlying ReactFlow instance |
+
+### Container sizing
+
+The graph container uses `position: absolute; inset: 0` to fill its parent. Make sure the parent element has `position: relative` and a defined height (e.g. `h-full`, `flex-1`, or an explicit height).
+
+## GraphSpec
+
+GraphSpec is the data format that describes a pipeline execution graph. It's generated by Pipelex when running or validating MTHDS method bundles.
+
+### Generating a GraphSpec
+
+```bash
+# From a .mthds bundle file
+pipelex-agent validate bundle my-method.mthds --view
+
+# The output JSON contains a graphspec field
+```
+
+Or programmatically via the Pipelex Python SDK:
+
+```python
+from pipelex import Pipelex
+
+px = Pipelex()
+result = px.validate_bundle("my-method.mthds", view=True)
+graphspec = result.graphspec  # dict ready for JSON serialization
+```
+
+### Structure
+
+```typescript
+interface GraphSpec {
+  nodes: GraphSpecNode[];
+  edges: GraphSpecEdge[];
+}
+
+interface GraphSpecNode {
+  id: string;
+  pipe_code?: string; // e.g. "analyze_match"
+  pipe_type?: string; // e.g. "PipeLLM", "PipeSequence", "PipeExtract"
+  status?: string; // "succeeded", "failed", "running", "scheduled", "skipped"
+  io?: {
+    inputs?: IOItem[];
+    outputs?: IOItem[];
+  };
+}
+
+interface GraphSpecEdge {
+  id?: string;
+  source: string; // Source node ID
+  target: string; // Target node ID
+  kind: GraphSpecEdgeKind; // "data", "contains", "batch_item", etc.
+  label?: string;
+}
+```
+
+### Node types
+
+Nodes represent pipes (operations) and stuffs (data artifacts) in the pipeline:
+
+- **Pipe nodes** — operations like `PipeLLM`, `PipeSequence`, `PipeExtract`, `PipeSearch`
+- **Stuff nodes** — data flowing between pipes, typed by concepts (e.g. `CandidateProfile`, `Document`)
+
+### Edge kinds
+
+| Kind               | Description                                                 |
+| ------------------ | ----------------------------------------------------------- |
+| `data`             | Data flow — stuff produced by one pipe, consumed by another |
+| `contains`         | Containment — a controller pipe wraps child pipes           |
+| `batch_item`       | Batch processing — items fanned out from a collection       |
+| `batch_aggregate`  | Batch aggregation — items collected back                    |
+| `parallel_combine` | Parallel results combined                                   |
+
+### Example GraphSpec (minimal)
+
+```json
+{
+  "nodes": [
+    {
+      "id": "extract_text",
+      "pipe_code": "extract_text",
+      "pipe_type": "PipeExtract",
+      "io": {
+        "inputs": [{ "digest": "input_doc", "name": "document", "concept": "Document" }],
+        "outputs": [{ "digest": "pages", "name": "pages", "concept": "TextPages" }]
+      }
+    },
+    {
+      "id": "summarize",
+      "pipe_code": "summarize",
+      "pipe_type": "PipeLLM",
+      "io": {
+        "inputs": [{ "digest": "pages", "name": "pages", "concept": "TextPages" }],
+        "outputs": [{ "digest": "summary", "name": "summary", "concept": "Summary" }]
+      }
+    }
+  ],
+  "edges": []
+}
+```
+
+Full specification: [docs.pipelex.com — Execution Graph Tracing](https://docs.pipelex.com/latest/under-the-hood/execution-graph-tracing/#graphspec)
+
+## Configuration
+
+### GraphConfig
+
+Controls layout and visual behavior. All fields are optional — `DEFAULT_GRAPH_CONFIG` provides sensible defaults.
+
+```typescript
+import { DEFAULT_GRAPH_CONFIG } from "@pipelex/mthds-ui";
+
+// Override specific settings
+const myConfig = {
+  ...DEFAULT_GRAPH_CONFIG,
+  direction: "LR",
+  nodesep: 80,
+  ranksep: 50,
+};
+```
+
+| Field             | Type                     | Default       | Description                            |
+| ----------------- | ------------------------ | ------------- | -------------------------------------- |
+| `direction`       | `GraphDirection`         | `"LR"`        | Layout direction                       |
+| `showControllers` | `boolean`                | `false`       | Show controller group boxes            |
+| `nodesep`         | `number`                 | `50`          | Horizontal spacing between nodes       |
+| `ranksep`         | `number`                 | `100`         | Vertical spacing between ranks         |
+| `edgeType`        | `EdgeType`               | `"bezier"`    | Edge curve style                       |
+| `initialZoom`     | `number \| null`         | `null`        | Override fit-view zoom (`null` = auto) |
+| `panToTop`        | `boolean`                | `true`        | Pan viewport to top after layout       |
+| `paletteColors`   | `Record<string, string>` | _(see below)_ | CSS variable overrides for theming     |
+
+### Theming with palette colors
+
+`GraphViewer` applies CSS custom properties from `paletteColors` on mount. Override colors by passing a custom config:
+
+```tsx
+<GraphViewer
+  graphspec={graphspec}
+  config={{
+    ...DEFAULT_GRAPH_CONFIG,
+    paletteColors: {
+      ...DEFAULT_GRAPH_CONFIG.paletteColors,
+      "--color-pipe": "#e06c75",
+      "--color-stuff": "#61afef",
+      "--color-bg": "#282c34",
+    },
+  }}
+/>
+```
+
+Default palette colors include:
+
+| Variable                  | Purpose                    |
+| ------------------------- | -------------------------- |
+| `--color-pipe`            | Pipe node border/accent    |
+| `--color-pipe-bg`         | Pipe node background       |
+| `--color-stuff`           | Stuff node border/accent   |
+| `--color-stuff-bg`        | Stuff node background      |
+| `--color-edge`            | Edge line color            |
+| `--color-batch-item`      | Batch item edge color      |
+| `--color-batch-aggregate` | Batch aggregate edge color |
+| `--color-bg`              | Graph background           |
+| `--color-bg-dots`         | Background dot pattern     |
+| `--font-sans`             | Node font family           |
+| `--font-mono`             | Code/controller font       |
+
+See `graphConfig.ts` for the full default palette.
+
+## Entry points
+
+| Import path                     | Content                                                            |
+| ------------------------------- | ------------------------------------------------------------------ |
+| `@pipelex/mthds-ui`             | Pure-TS graph logic — types, builders, layout, controllers, config |
+| `@pipelex/mthds-ui/graph/react` | React components — `GraphViewer`, label helpers, type converters   |
+| `@pipelex/mthds-ui/shiki`       | MTHDS syntax highlighting with shiki                               |
+
+## Pure TypeScript usage
+
+Use the graph logic without React — build nodes/edges, run layout, and feed the result to your own renderer:
+
+```typescript
+import {
+  buildGraph,
+  getLayoutedElements,
+  applyControllers,
+  DEFAULT_GRAPH_CONFIG,
+} from "@pipelex/mthds-ui";
+
+// Build graph data from a GraphSpec
+const { graphData, analysis } = buildGraph(graphspec, "bezier");
+
+// Apply ELK layout
+const { nodes, edges } = getLayoutedElements(graphData.nodes, graphData.edges, "TB");
+
+// Optionally wrap nodes in controller groups
+const final = applyControllers(nodes, edges, graphspec, analysis, true);
+```
+
+## Shiki integration
+
+Syntax-highlight MTHDS code with the bundled grammar and themes:
+
+```typescript
+import { highlightMthds, getAvailableThemes } from "@pipelex/mthds-ui/shiki";
+
+const html = await highlightMthds(mthdsSource, "pipelex-dark");
+```
+
+## Development
+
+```bash
+npm install
+make check    # lint + format-check + typecheck
+make test     # unit tests (vitest)
+make build    # build to dist/
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+This project depends on [elkjs](https://github.com/kieler/elkjs) which is licensed under [EPL-2.0](https://www.eclipse.org/legal/epl-2.0/). See [NOTICE](./NOTICE) for third-party license details.