@mantir/headless-view

A reusable, headless execution view for Mantir workflows. This package provides a complete UI experience for running workflows, handling interruptions, and visualizing progress.

Installation

npm install @mantir/headless-view
# or
pnpm add @mantir/headless-view
# or
yarn add @mantir/headless-view

Usage

1. Import Styles

If you are not using Tailwind CSS in your project, or you want the default Mantir styles "out of the box", import the CSS file in your main entry point (e.g., _app.tsx, layout.tsx, or main.tsx):

import '@mantir/headless-view/styles.css';

2. Use the Component

import { HeadlessExecutor } from '@mantir/headless-view';

function App() {
  const workflow = { /* your workflow object */ };

  return (
    <div className="my-container">
      <HeadlessExecutor 
        workflow={workflow} 
        apiEndpoint="/api/execute" 
        onResult={(result) => console.log('Final workflow result:', result)}
        onDone={() => console.log('Execution finished')}
        initialInput="Programmatic input value"
      />
    </div>
  );
}

3. Custom Logic with Hooks

If you want to build your own UI but use the Mantir execution logic:

import { useWorkflowExecution } from '@mantir/headless-view';

function CustomExecutor({ workflow }) {
  const { 
    messages, 
    isRunning, 
    pendingInterrupt, 
    execute, // Programmatic trigger
    resume 
  } = useWorkflowExecution({
    apiEndpoint: "/api/execute",
    workflow: workflow, // Pass to enable initialInput auto-start
    initialInput: "Hello world",
    onResult: (data) => console.log(data),
    onDone: () => console.log("Done")
  });

  return (
    <div>
      {/* Your custom UI here */}
    </div>
  );
}

Props / Hook Options

• apiEndpoint: (string) The URL to post workflow execution requests to.
• workflow: (Workflow, optional) The JSON workflow definition. When provided with initialInput, enables auto-start.
• initialInput: (string, optional) If provided, the workflow will automatically start on mount using this value.
• onResult: (callback, optional) Called when the workflow produces a final JSON result.
• onDone: (callback, optional) Called when the execution stream finishes completely.
• onMessage: (callback, optional) Called for every message/trace event.
• onInterrupt: (callback, optional) Called when the workflow requires user input.
• onError: (callback, optional) Called if a network or execution error occurs.

Configuration for Tailwind CSS Projects

If your project already uses Tailwind CSS (v3 or v4) and you want to use your project's theme and styles, you should add the package to your Tailwind configuration instead of importing the CSS file.

Tailwind CSS v4

In your globals.css:

@source "path/to/node_modules/@mantir/headless-view/dist/**/*.{js,mjs}";

Tailwind CSS v3

In your tailwind.config.js:

module.exports = {
  content: [
    "./node_modules/@mantir/headless-view/dist/**/*.{js,mjs}",
    // ...
  ],
  // ...
}

Peer Dependencies

• react >= 18
• react-dom >= 18

API Reference

useWorkflowExecution Hook

Returns an object with:

• messages: Message[] - Array of all messages from the workflow execution
• isRunning: boolean - Whether the workflow is currently executing
• error: Error | null - Any error that occurred during execution
• pendingInterrupt: any | null - Details of any pending user input request
• currentThreadId: string | undefined - The current execution thread ID
• execute: (workflow: Workflow, input: string) => Promise<void> - Programmatically start a workflow
• restart: (workflow: Workflow, input: string) => Promise<void> - Restart the workflow from the beginning
• resume: (workflow: Workflow, value: any) => Promise<void> - Resume after an interrupt
• runExecution: Internal execution function (advanced use only)

Message Type

interface Message {
  id: string;
  role: "user" | "assistant" | "system" | "trace";
  content: string;
  meta?: any;
}