@termdraw/pi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Vinegar
+
+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,73 @@
+# @termdraw/pi
+
+`@termdraw/pi` embeds termDRAW inside Pi using `opentui-island` so you can open the editor as a full-screen Pi overlay and insert drawings back into the current editor.
+
+## Install
+
+```bash
+pi install npm:@termdraw/pi
+```
+
+For a project-local install:
+
+```bash
+pi install -l npm:@termdraw/pi
+```
+
+## Usage
+
+Inside Pi:
+
+```text
+/termdraw
+```
+
+Use `Enter` or `Ctrl+S` to insert the drawing into Pi. Use `Ctrl+Q` to close without inserting.
+
+## Local development
+
+From this repo:
+
+```bash
+bun install
+pi install ./packages/pi
+```
+
+Or run the extension directly for a one-off test:
+
+```bash
+pi -e ./packages/pi/extensions/index.ts
+```
+
+## Smoke test
+
+There is a tmux-based end-to-end smoke test that verifies:
+
+- Pi starts with the extension loaded
+- `/termdraw` opens the embedded overlay
+- text can be entered into the island
+- saving returns the drawing back into the Pi editor
+
+Run it from the repo root:
+
+```bash
+bun run smoke:pi
+```
+
+Requirements:
+
+- `pi` installed and on `PATH`
+- `tmux` installed
+
+Set `PI_TERMDRAW_SMOKE_KEEP_SESSION=1` if you want the tmux session left alive for debugging on exit.
+
+## Notes
+
+- Requires Bun 1.3+ on the machine running Pi.
+- The embedded island currently loads from source (`islands/termdraw.island.tsx`) via Bun.
+- `opentui-island@0.3.0` still has an older optional Pi peer range, so some npm installs may still need `--legacy-peer-deps` depending on the Pi version in use.
+- This package targets the terminal Pi experience first. GUI support will depend on Pi's extension UI surface.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/extensions/index.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { runTermDrawCommand } from "./overlay.ts";
+
+export default function piTermDrawExtension(pi: ExtensionAPI) {
+  pi.registerCommand("termdraw", {
+    description: "Open termDRAW inside a Pi overlay",
+    handler: async (_args, ctx) => {
+      await runTermDrawCommand(ctx);
+    },
+  });
+}

package/extensions/overlay.ts

@@ -0,0 +1,259 @@
+import type { ExtensionCommandContext, Theme } from "@mariozechner/pi-coding-agent";
+import {
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  type Component,
+  type TUI,
+} from "@mariozechner/pi-tui";
+import type { OpenTuiBridgeEvent } from "opentui-island";
+import {
+  createPiTuiOpenTuiSurface,
+  disablePiTuiMouseMode,
+  enablePiTuiMouseMode,
+  type PiTuiOpenTuiSurface,
+} from "opentui-island/pi-tui";
+
+const TERM_DRAW_ISLAND_MODULE_URL = new URL("../islands/termdraw.island.tsx", import.meta.url);
+const PI_FOOTER_TEXT =
+  "Right palette tools/styles/colors • select tool can marquee multiple objects • drag box corners / line endpoints to edit • Esc deselect • Enter inserts into Pi • Ctrl+Q cancels";
+const READY_STATUS = "termDRAW ready. Press Enter or Ctrl+S to insert into Pi. Ctrl+Q cancels.";
+const LOADING_STATUS = "Starting termDRAW in a Bun sidecar…";
+const INSERTED_MESSAGE = "Inserted drawing into editor.";
+const CANCELLED_MESSAGE = "Drawing cancelled.";
+const ERROR_PREFIX = "termDRAW failed to start:";
+const SMOKE_TEXT = process.env.PI_TERMDRAW_SMOKE_TEXT?.trim() ?? "";
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+type TermDrawSaveEvent = OpenTuiBridgeEvent<"save", { art: string }>;
+type TermDrawCancelEvent = OpenTuiBridgeEvent<"cancel", { reason?: string }>;
+type TermDrawOverlayResult = { kind: "save"; art: string } | { kind: "cancel" };
+
+function isTermDrawSaveEvent(event: OpenTuiBridgeEvent): event is TermDrawSaveEvent {
+  return (
+    event.type === "save" &&
+    !!event.payload &&
+    typeof event.payload === "object" &&
+    "art" in event.payload
+  );
+}
+
+function isTermDrawCancelEvent(event: OpenTuiBridgeEvent): event is TermDrawCancelEvent {
+  return event.type === "cancel";
+}
+
+function padLine(text: string, width: number): string {
+  const truncated = truncateToWidth(text, width, "", true);
+  return truncated + " ".repeat(Math.max(0, width - visibleWidth(truncated)));
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+
+function formatForEditor(art: string): string {
+  const content = art.length > 0 ? art : " ";
+  return `\`\`\`text\n${content}\n\`\`\``;
+}
+
+class TermDrawOverlay implements Component {
+  private readonly surfaceHeight: number;
+  private readonly width: number;
+  private readonly smokeText: string;
+  private surface: PiTuiOpenTuiSurface | null = null;
+  private unsubscribeFromEvents: (() => void) | null = null;
+  private status = LOADING_STATUS;
+  private error: string | null = null;
+  private closing = false;
+
+  constructor(
+    private readonly tui: TUI,
+    private readonly theme: Theme,
+    private readonly done: (value: TermDrawOverlayResult) => void,
+  ) {
+    this.width = Math.max(1, this.tui.terminal.columns);
+    this.surfaceHeight = Math.max(1, this.tui.terminal.rows - 1);
+    this.smokeText = SMOKE_TEXT;
+    enablePiTuiMouseMode(this.tui.terminal);
+    void this.initialize();
+  }
+
+  private async initialize(): Promise<void> {
+    try {
+      this.surface = await createPiTuiOpenTuiSurface({
+        height: this.surfaceHeight,
+        initialWidth: this.width,
+        requestRender: () => this.tui.requestRender(),
+        island: {
+          module: TERM_DRAW_ISLAND_MODULE_URL,
+          props: {
+            showStartupLogo: false,
+            footerText: PI_FOOTER_TEXT,
+          },
+        },
+      });
+      this.unsubscribeFromEvents = this.surface.onEvent((event) => {
+        if (isTermDrawSaveEvent(event)) {
+          void this.close({ kind: "save", art: event.payload.art });
+          return;
+        }
+
+        if (isTermDrawCancelEvent(event)) {
+          void this.close({ kind: "cancel" });
+        }
+      });
+      this.surface.focused = true;
+      this.surface.setScreenBounds({
+        row: 0,
+        col: 0,
+        width: this.width,
+        height: this.surfaceHeight,
+      });
+      await this.surface.sync(this.width);
+      this.status = READY_STATUS;
+      if (this.smokeText.length > 0) {
+        void this.runSmokeAutomation();
+      }
+    } catch (error) {
+      this.error = formatError(error);
+      this.status = `${ERROR_PREFIX} ${this.error}`;
+    }
+
+    this.tui.requestRender();
+  }
+
+  private async runSmokeAutomation(): Promise<void> {
+    if (!this.surface || this.closing) {
+      return;
+    }
+
+    try {
+      await delay(150);
+      await this.surface.sendInput("\t");
+      await delay(50);
+      await this.surface.sendInput("\t");
+      await delay(50);
+
+      for (const char of this.smokeText) {
+        await this.surface.sendInput(char);
+      }
+
+      await delay(100);
+      await this.surface.sendInput("\r");
+    } catch (error) {
+      this.status = `Smoke automation failed: ${formatError(error)}`;
+      this.tui.requestRender();
+    }
+  }
+
+  handleInput(data: string): void {
+    if (
+      this.error &&
+      (matchesKey(data, "ctrl+q") || matchesKey(data, "escape") || matchesKey(data, "ctrl+c"))
+    ) {
+      void this.close({ kind: "cancel" });
+      return;
+    }
+
+    this.surface?.handleInput(data);
+    this.tui.requestRender();
+  }
+
+  invalidate(): void {
+    this.surface?.invalidate();
+  }
+
+  render(width: number): string[] {
+    const normalizedWidth = Math.max(1, width);
+
+    this.surface?.setScreenBounds({
+      row: 0,
+      col: 0,
+      width: normalizedWidth,
+      height: this.surfaceHeight,
+    });
+
+    if (this.error) {
+      const body = Array.from({ length: Math.max(1, this.surfaceHeight) }, (_, index) => {
+        if (index === 0) {
+          return padLine(this.theme.fg("error", `${ERROR_PREFIX} ${this.error}`), normalizedWidth);
+        }
+        if (index === 1) {
+          return padLine(
+            this.theme.fg("dim", "Make sure Bun 1.3+ is installed and available on PATH."),
+            normalizedWidth,
+          );
+        }
+        return " ".repeat(normalizedWidth);
+      });
+
+      return [
+        ...body,
+        padLine(this.theme.fg("warning", "Ctrl+Q, Esc, or Ctrl+C closes."), normalizedWidth),
+      ];
+    }
+
+    if (!this.surface) {
+      const body = Array.from({ length: Math.max(1, this.surfaceHeight) }, (_, index) =>
+        index === 0
+          ? padLine(this.theme.fg("accent", LOADING_STATUS), normalizedWidth)
+          : " ".repeat(normalizedWidth),
+      );
+
+      return [...body, padLine(this.theme.fg("dim", "Loading termDRAW…"), normalizedWidth)];
+    }
+
+    const body = this.surface.render(normalizedWidth).slice(0, this.surfaceHeight);
+    const footer = padLine(this.theme.fg("dim", this.status), normalizedWidth);
+    return [...body, footer];
+  }
+
+  private async close(result: TermDrawOverlayResult): Promise<void> {
+    if (this.closing) {
+      return;
+    }
+
+    this.closing = true;
+    try {
+      this.unsubscribeFromEvents?.();
+      this.unsubscribeFromEvents = null;
+      await this.surface?.destroy();
+    } finally {
+      disablePiTuiMouseMode(this.tui.terminal);
+      this.done(result);
+    }
+  }
+}
+
+export async function runTermDrawCommand(ctx: ExtensionCommandContext): Promise<void> {
+  if (!ctx.hasUI) {
+    return;
+  }
+
+  const result = await ctx.ui.custom<TermDrawOverlayResult>(
+    (tui, theme, _keybindings, done) => new TermDrawOverlay(tui, theme, done),
+    {
+      overlay: true,
+      overlayOptions: {
+        row: 0,
+        col: 0,
+        width: "100%",
+        maxHeight: "100%",
+        margin: 0,
+      },
+    },
+  );
+
+  if (!result || result.kind === "cancel") {
+    ctx.ui.notify(CANCELLED_MESSAGE, "info");
+    return;
+  }
+
+  const existing = ctx.ui.getEditorText();
+  const prefix = existing.endsWith("\n") || existing.length === 0 ? "" : "\n";
+  ctx.ui.pasteToEditor(`${prefix}${formatForEditor(result.art)}\n`);
+  ctx.ui.notify(INSERTED_MESSAGE, "info");
+}

package/islands/termdraw.island.tsx

@@ -0,0 +1,39 @@
+/** @jsxImportSource @opentui/react */
+
+import { useOpenTuiIslandBridge } from "opentui-island";
+import { TermDrawApp } from "@termdraw/opentui";
+
+type PiTermDrawIslandProps = {
+  showStartupLogo?: boolean;
+  footerText?: string;
+};
+
+export default function PiTermDrawIsland({
+  showStartupLogo = false,
+  footerText,
+}: PiTermDrawIslandProps) {
+  const bridge = useOpenTuiIslandBridge();
+
+  return (
+    <TermDrawApp
+      width="100%"
+      height="100%"
+      autoFocus
+      showStartupLogo={showStartupLogo}
+      cancelOnCtrlC={false}
+      footerText={footerText}
+      onSave={(art) => {
+        bridge.emit({
+          type: "save",
+          payload: { art },
+        });
+      }}
+      onCancel={() => {
+        bridge.emit({
+          type: "cancel",
+          payload: { reason: "user" },
+        });
+      }}
+    />
+  );
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@termdraw/pi",
+  "version": "0.1.0",
+  "description": "Pi extension package that embeds termDRAW inside Pi via opentui-island.",
+  "keywords": [
+    "drawing",
+    "opentui",
+    "pi-extension",
+    "pi-package",
+    "terminal",
+    "tui"
+  ],
+  "homepage": "https://github.com/benvinegar/termdraw/tree/main/packages/pi#readme",
+  "bugs": {
+    "url": "https://github.com/benvinegar/termdraw/issues"
+  },
+  "license": "MIT",
+  "author": "Ben Vinegar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/benvinegar/termdraw.git"
+  },
+  "files": [
+    "extensions",
+    "islands",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "pack:check": "npm pack --dry-run --ignore-scripts",
+    "smoke:pi": "bash ./scripts/smoke-pi-save.sh"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.1.97",
+    "@opentui/react": "^0.1.97",
+    "@termdraw/opentui": "0.3.0",
+    "opentui-island": "^0.3.0",
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@types/react": "^19.2.14",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=18"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  }
+}