@aprovan/patchwork 0.1.0

package/packages/editor/src/lib/vfs.ts

@@ -0,0 +1,106 @@
+import { 
+  VFSStore, 
+  LocalFSBackend, 
+  type VirtualProject,
+  type VirtualFile 
+} from '@aprovan/patchwork-compiler';
+
+/**
+ * VFS client for persisting virtual projects to the stitchery server.
+ * Uses LocalFSBackend which makes HTTP requests to /vfs routes.
+ */
+
+// VFS base URL - points to stitchery server's VFS routes
+const VFS_BASE_URL = '/vfs';
+
+// Cached VFS config
+let vfsConfigCache: { usePaths: boolean } | null = null;
+
+/**
+ * Get VFS configuration from the server.
+ * Caches the result for subsequent calls.
+ */
+export async function getVFSConfig(): Promise<{ usePaths: boolean }> {
+  if (vfsConfigCache) return vfsConfigCache;
+  
+  try {
+    const res = await fetch(`${VFS_BASE_URL}/config`);
+    if (res.ok) {
+      vfsConfigCache = await res.json();
+      return vfsConfigCache!;
+    }
+  } catch {
+    // Server not available, use default
+  }
+  
+  return { usePaths: false };
+}
+
+// Create a singleton store instance for dev mode
+let storeInstance: VFSStore | null = null;
+
+/**
+ * Get the VFS store instance (creates one if needed).
+ * Store uses LocalFSBackend to persist to the stitchery server.
+ */
+export function getVFSStore(): VFSStore {
+  if (!storeInstance) {
+    const backend = new LocalFSBackend({ baseUrl: VFS_BASE_URL });
+    storeInstance = new VFSStore(backend);
+  }
+  return storeInstance;
+}
+
+/**
+ * Save a virtual project to disk via the stitchery server.
+ * Projects are saved under their ID in the VFS directory.
+ */
+export async function saveProject(project: VirtualProject): Promise<void> {
+  const store = getVFSStore();
+  await store.saveProject(project);
+}
+
+/**
+ * Load a project from disk by ID.
+ */
+export async function loadProject(id: string): Promise<VirtualProject | null> {
+  const store = getVFSStore();
+  return store.loadProject(id);
+}
+
+/**
+ * List all stored project IDs.
+ */
+export async function listProjects(): Promise<string[]> {
+  const store = getVFSStore();
+  const files = await store.listFiles();
+  
+  // Extract unique project IDs (first path segment)
+  const projectIds = new Set<string>();
+  for (const file of files) {
+    const id = file.split('/')[0];
+    if (id) projectIds.add(id);
+  }
+  
+  return Array.from(projectIds);
+}
+
+/**
+ * Save a single file to the VFS.
+ */
+export async function saveFile(file: VirtualFile): Promise<void> {
+  const store = getVFSStore();
+  await store.putFile(file);
+}
+
+/**
+ * Check if VFS is available (stitchery server is running with vfs-dir enabled).
+ */
+export async function isVFSAvailable(): Promise<boolean> {
+  try {
+    const res = await fetch(VFS_BASE_URL, { method: 'HEAD' });
+    return res.ok || res.status === 404; // 404 on root is expected if empty
+  } catch {
+    return false;
+  }
+}

package/packages/editor/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "jsx": "react-jsx"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/editor/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  external: ['react', 'react-dom'],
+  treeshake: true,
+});

package/packages/images/ink/node_modules/.bin/jiti

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/jiti@1.21.7/node_modules/jiti/bin/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/jiti@1.21.7/node_modules/jiti/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/jiti@1.21.7/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/jiti@1.21.7/node_modules/jiti/bin/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/jiti@1.21.7/node_modules/jiti/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/jiti@1.21.7/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../../node_modules/.pnpm/jiti@1.21.7/node_modules/jiti/bin/jiti.js" "$@"
+else
+  exec node  "$basedir/../../../../../node_modules/.pnpm/jiti@1.21.7/node_modules/jiti/bin/jiti.js" "$@"
+fi

package/packages/images/ink/node_modules/.bin/tsc

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/packages/images/ink/node_modules/.bin/tsserver

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/packages/images/ink/node_modules/.bin/tsup

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/dist/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/dist/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsup/dist/cli-default.js" "$@"
+else
+  exec node  "$basedir/../tsup/dist/cli-default.js" "$@"
+fi

package/packages/images/ink/node_modules/.bin/tsup-node

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/dist/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/dist/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.6_tsx@4.21.0_typescript@5.9.3/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsup/dist/cli-node.js" "$@"
+else
+  exec node  "$basedir/../tsup/dist/cli-node.js" "$@"
+fi

package/packages/images/ink/node_modules/.bin/tsx

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsx@4.21.0/node_modules/tsx/dist/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsx@4.21.0/node_modules/tsx/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsx@4.21.0/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsx@4.21.0/node_modules/tsx/dist/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsx@4.21.0/node_modules/tsx/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/tsx@4.21.0/node_modules:/home/runner/work/patchwork/patchwork/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../../node_modules/.pnpm/tsx@4.21.0/node_modules/tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../../../../../node_modules/.pnpm/tsx@4.21.0/node_modules/tsx/dist/cli.mjs" "$@"
+fi

package/packages/images/ink/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@aprovan/patchwork-ink",
+  "version": "0.1.0",
+  "description": "Patchwork image: Ink terminal UI for CLI widgets",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runner": {
+      "types": "./dist/runner.d.ts",
+      "import": "./dist/runner.js"
+    },
+    "./setup": {
+      "types": "./dist/setup.d.ts",
+      "import": "./dist/setup.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "patchwork": {
+    "platform": "cli",
+    "esbuild": {
+      "target": "node20",
+      "format": "esm",
+      "jsx": "automatic"
+    }
+  },
+  "dependencies": {
+    "react": "^18.0.0",
+    "ink": "^5.0.0",
+    "ink-spinner": "^5.0.0",
+    "ink-link": "^4.0.0",
+    "ink-box": "^2.0.0",
+    "chalk": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@types/react": "^18.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/packages/images/ink/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * @aprovan/patchwork-image-ink
+ *
+ * Ink terminal UI image for CLI widgets.
+ * Provides React components for building terminal interfaces.
+ */
+
+export { setup, cleanup } from './setup.js';
+export type { SetupOptions, InkEnvironment } from './setup.js';
+
+// Runner - mounting/execution for terminal widgets
+export {
+  run,
+  runOnce,
+  evaluateWidget,
+  renderComponent,
+  getGlobals,
+} from './runner.js';
+export type {
+  RunnerOptions,
+  RunnerInstance,
+  CompiledWidget,
+  GlobalInjection,
+} from './runner.js';
+
+// Re-export Ink components for convenience
+export {
+  render,
+  Box,
+  Text,
+  Static,
+  Transform,
+  Newline,
+  Spacer,
+  useInput,
+  useApp,
+  useFocus,
+  useFocusManager,
+  useStdin,
+  useStdout,
+  useStderr,
+} from 'ink';
+
+// Re-export React for widget authors
+export { default as React } from 'react';
+
+// Re-export chalk for styling
+export { default as chalk } from 'chalk';

package/packages/images/ink/src/runner.ts

@@ -0,0 +1,331 @@
+/**
+ * @aprovan/patchwork-ink - Runner
+ *
+ * Provides the runtime mounting logic for Ink terminal widgets.
+ * The image owns all ink/react dependencies and mounting code.
+ */
+
+import type { WriteStream } from 'node:tty';
+import { render } from 'ink';
+import React from 'react';
+
+/**
+ * Global injections for compiling widgets with this image
+ *
+ * These tell the compiler which imports to transform into global variable references.
+ * The evaluateWidget function will provide these globals at runtime.
+ */
+export interface GlobalInjection {
+  module: string;
+  globalName: string;
+}
+
+export function getGlobals(): GlobalInjection[] {
+  return [
+    { module: 'react', globalName: '__REACT__' },
+    { module: 'ink', globalName: '__INK__' },
+  ];
+}
+
+export interface RunnerOptions {
+  /** Service proxy for UTCP calls */
+  proxy?: {
+    call(
+      namespace: string,
+      procedure: string,
+      args: unknown[],
+    ): Promise<unknown>;
+  };
+  /** Initial props/inputs to pass to widget */
+  inputs?: Record<string, unknown>;
+  /** Output stream (default: process.stdout) */
+  stdout?: WriteStream;
+  /** Input stream (default: process.stdin) */
+  stdin?: NodeJS.ReadStream;
+  /** Exit on Ctrl+C (default: true) */
+  exitOnCtrlC?: boolean;
+}
+
+export interface RunnerInstance {
+  /** Unique mount ID */
+  id: string;
+  /** Unmount the widget */
+  unmount: () => void;
+  /** Wait until the widget exits */
+  waitUntilExit: () => Promise<void>;
+  /** Rerender with new props */
+  rerender: (props: Record<string, unknown>) => void;
+  /** Clear the terminal output */
+  clear: () => void;
+}
+
+let mountCounter = 0;
+
+function generateMountId(): string {
+  return `patchwork-ink-${Date.now()}-${++mountCounter}`;
+}
+
+/**
+ * Generate namespace globals that proxy calls to a service proxy
+ *
+ * Given services like ["git.branch", "git.status", "github.repos.get"],
+ * generates globals with appropriate methods.
+ */
+function generateNamespaceGlobals(
+  services: string[],
+  proxy: RunnerOptions['proxy'],
+): Record<string, unknown> {
+  if (!proxy) return {};
+
+  const namespaces: Record<string, Record<string, unknown>> = {};
+
+  for (const service of services) {
+    const parts = service.split('.');
+    if (parts.length < 2) continue;
+
+    const namespace = parts[0] as string;
+    const procedurePath = parts.slice(1);
+
+    if (!namespaces[namespace]) {
+      namespaces[namespace] = {};
+    }
+
+    let current = namespaces[namespace] as Record<string, unknown>;
+    for (let i = 0; i < procedurePath.length - 1; i++) {
+      const key = procedurePath[i] as string;
+      if (!current[key]) {
+        current[key] = {};
+      }
+      current = current[key] as Record<string, unknown>;
+    }
+
+    const finalKey = procedurePath[procedurePath.length - 1] as string;
+    const fullProcedure = procedurePath.join('.');
+    current[finalKey] = (...args: unknown[]) =>
+      proxy.call(namespace, fullProcedure, args);
+  }
+
+  return namespaces;
+}
+
+/**
+ * Extract unique namespace names from services array
+ */
+function extractNamespaces(services: string[]): string[] {
+  const namespaces = new Set<string>();
+  for (const service of services) {
+    const parts = service.split('.');
+    if (parts[0]) {
+      namespaces.add(parts[0]);
+    }
+  }
+  return Array.from(namespaces);
+}
+
+/**
+ * Inject namespace globals into globalThis
+ */
+function injectNamespaceGlobals(namespaces: Record<string, unknown>): void {
+  for (const [name, value] of Object.entries(namespaces)) {
+    (globalThis as Record<string, unknown>)[name] = value;
+  }
+}
+
+/**
+ * Remove namespace globals from globalThis
+ */
+function removeNamespaceGlobals(namespaceNames: string[]): void {
+  for (const name of namespaceNames) {
+    delete (globalThis as Record<string, unknown>)[name];
+  }
+}
+
+export interface CompiledWidget {
+  /** Compiled ESM code */
+  code: string;
+  /** Content hash for caching */
+  hash: string;
+  /** Original manifest */
+  manifest: {
+    name: string;
+    services?: string[];
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Run a compiled widget using Ink
+ *
+ * This is the main entry point for running terminal widgets.
+ * The image owns all React/Ink dependencies.
+ */
+export async function run(
+  widget: CompiledWidget,
+  options: RunnerOptions = {},
+): Promise<RunnerInstance> {
+  const {
+    proxy,
+    inputs = {},
+    stdout = process.stdout as WriteStream,
+    stdin = process.stdin,
+    exitOnCtrlC = true,
+  } = options;
+  const mountId = generateMountId();
+
+  // Inject namespace globals for services
+  const services = widget.manifest.services || [];
+  const namespaceNames = extractNamespaces(services);
+  const namespaces = generateNamespaceGlobals(services, proxy);
+  injectNamespaceGlobals(namespaces);
+
+  // Import the widget module from code
+  const dataUri = `data:text/javascript;base64,${Buffer.from(
+    widget.code,
+  ).toString('base64')}`;
+
+  let module: { default?: unknown };
+  try {
+    module = await import(/* webpackIgnore: true */ /* @vite-ignore */ dataUri);
+  } catch {
+    // Fallback: use Function-based loading
+    const AsyncFunction = Object.getPrototypeOf(async function () {})
+      .constructor as new (argName: string, code: string) => (
+      exports: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>;
+    const exports: Record<string, unknown> = {};
+    const fn = new AsyncFunction('exports', widget.code + '\nreturn exports;');
+    module = await fn(exports);
+  }
+
+  const Component = module.default;
+  if (!Component) {
+    removeNamespaceGlobals(namespaceNames);
+    throw new Error('Widget must export a default component');
+  }
+
+  if (typeof Component !== 'function') {
+    removeNamespaceGlobals(namespaceNames);
+    throw new Error('Widget default export must be a function/component');
+  }
+
+  // Render using Ink
+  let currentInputs = { ...inputs };
+  const element = React.createElement(
+    Component as React.ComponentType,
+    currentInputs,
+  );
+  const instance = render(element, {
+    stdout,
+    stdin,
+    exitOnCtrlC,
+  });
+
+  return {
+    id: mountId,
+    unmount() {
+      instance.unmount();
+      removeNamespaceGlobals(namespaceNames);
+    },
+    waitUntilExit() {
+      return instance.waitUntilExit();
+    },
+    rerender(newInputs: Record<string, unknown>) {
+      currentInputs = { ...currentInputs, ...newInputs };
+      const newElement = React.createElement(
+        Component as React.ComponentType,
+        currentInputs,
+      );
+      instance.rerender(newElement);
+    },
+    clear() {
+      instance.clear();
+    },
+  };
+}
+
+/**
+ * Run a widget once and wait for exit
+ */
+export async function runOnce(
+  widget: CompiledWidget,
+  options: RunnerOptions = {},
+): Promise<void> {
+  const instance = await run(widget, options);
+  await instance.waitUntilExit();
+  instance.unmount();
+}
+
+/**
+ * Evaluate widget code and return the component
+ *
+ * This is used for more advanced scenarios where you need
+ * direct access to the component.
+ */
+export async function evaluateWidget(
+  code: string,
+  services: Record<string, unknown> = {},
+): Promise<React.ComponentType<{ services?: Record<string, unknown> }>> {
+  // Store services for widget access
+  (globalThis as Record<string, unknown>).__PATCHWORK_SERVICES__ = services;
+
+  // Inject globals that the compiled code expects
+  const __EXPORTS__: Record<string, unknown> = {};
+  const __REACT__ = React;
+  const __INK__ = await import('ink');
+
+  // Execute the transformed code with injected globals
+  const fn = new Function('__EXPORTS__', '__REACT__', '__INK__', code);
+  fn(__EXPORTS__, __REACT__, __INK__);
+
+  const Component =
+    __EXPORTS__.default ||
+    __EXPORTS__.Widget ||
+    Object.values(__EXPORTS__).find(
+      (v): v is React.ComponentType => typeof v === 'function',
+    );
+
+  if (!Component) {
+    throw new Error('No default export or Widget component found');
+  }
+
+  return Component as React.ComponentType<{
+    services?: Record<string, unknown>;
+  }>;
+}
+
+/**
+ * Render a component directly with Ink
+ *
+ * For cases where you already have an evaluated component.
+ */
+export function renderComponent(
+  Component: React.ComponentType<Record<string, unknown>>,
+  props: Record<string, unknown> = {},
+  options: Omit<RunnerOptions, 'proxy' | 'inputs'> = {},
+): RunnerInstance {
+  const {
+    stdout = process.stdout as WriteStream,
+    stdin = process.stdin,
+    exitOnCtrlC = true,
+  } = options;
+  const mountId = generateMountId();
+
+  let currentProps = { ...props };
+  const element = React.createElement(Component, currentProps);
+  const instance = render(element, {
+    stdout,
+    stdin,
+    exitOnCtrlC,
+  });
+
+  return {
+    id: mountId,
+    unmount: () => instance.unmount(),
+    waitUntilExit: () => instance.waitUntilExit(),
+    rerender(newProps: Record<string, unknown>) {
+      currentProps = { ...currentProps, ...newProps };
+      instance.rerender(React.createElement(Component, currentProps));
+    },
+    clear: () => instance.clear(),
+  };
+}