@the-forge-flow/visual-explainer-pi 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MonsieurBarti
+
+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,226 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/MonsieurBarti/The-Forge-Flow-CC/refs/heads/main/assets/forge-banner.png" alt="The Forge Flow - Visual Explainer PI" width="100%">
+
+  <h1>🎨 Visual Explainer PI</h1>
+
+  <p>
+    <strong>PI extension for generating beautiful HTML visualizations</strong>
+  </p>
+
+  <p>
+    <a href="https://github.com/MonsieurBarti/visual-explainer-pi/actions/workflows/ci.yml">
+      <img src="https://img.shields.io/github/actions/workflow/status/MonsieurBarti/visual-explainer-pi/ci.yml?label=CI&style=flat-square" alt="CI Status">
+    </a>
+    <a href="https://www.npmjs.com/package/@the-forge-flow/visual-explainer-pi">
+      <img src="https://img.shields.io/npm/v/@the-forge-flow/visual-explainer-pi?style=flat-square" alt="npm version">
+    </a>
+    <a href="LICENSE">
+      <img src="https://img.shields.io/github/license/MonsieurBarti/visual-explainer-pi?style=flat-square" alt="License">
+    </a>
+  </p>
+</div>
+
+---
+
+Turns complex terminal output into styled, self-contained HTML pages for diagrams, architecture overviews, diff reviews, data tables, and project recaps. Built on top of the design system from [nicobailon/visual-explainer](https://github.com/nicobailon/visual-explainer).
+
+## ✨ Features
+
+- **🎨 11 Visual Types**: architecture, flowchart, sequence, ER, state, table, diff, plan, timeline, dashboard, slides
+- **🖌️ 8 Aesthetic Palettes**: blueprint, editorial, paper, terminal, dracula, nord, solarized, gruvbox
+- **📄 Self-Contained HTML**: single file with embedded CSS/JS, opens in any browser
+- **🧜 Mermaid Integration**: automatic diagrams with zoom/pan controls
+- **📊 Data Tables**: responsive tables with sticky headers and status indicators
+- **🤖 PI-native**: seamless integration with PI's tool system, abort-signal aware, output truncated to PI's limits
+
+## 📦 Installation
+
+### 1. Install the extension with `pi install`
+
+PI discovers the extension automatically once installed as a pi package. By default this installs globally into `~/.pi/agent/`; pass `-l` to install into the current project (`.pi/`) instead.
+
+**From npm (recommended):**
+
+```bash
+pi install npm:@the-forge-flow/visual-explainer-pi
+```
+
+**From GitHub (tracks `main`):**
+
+```bash
+pi install git:github.com/MonsieurBarti/visual-explainer-pi
+```
+
+**Pin to a specific version:**
+
+```bash
+# npm — pin to a published version
+pi install npm:@the-forge-flow/visual-explainer-pi@0.1.0
+
+# git — pin to a release tag
+pi install git:github.com/MonsieurBarti/visual-explainer-pi@visual-explainer-pi-v0.1.0
+```
+
+Then reload PI with `/reload` (or restart it). On the next session you should see a notification that `Visual explainer ready`.
+
+**Manage installed packages:**
+
+```bash
+pi list    # show installed packages
+pi update  # update non-pinned packages
+pi remove npm:@the-forge-flow/visual-explainer-pi
+pi config  # enable/disable individual extensions, skills, prompts, themes
+```
+
+> For project-scoped installs, package filtering, and more, see the [pi packages doc](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/packages.md).
+
+## 🚀 Usage
+
+The extension registers a single `generate_visual` tool that the LLM can call directly. It also exposes two slash commands to reopen recently generated files.
+
+### `generate_visual`
+
+```typescript
+// Render a technical architecture diagram
+generate_visual({
+  type: "architecture",
+  title: "Auth System Overview",
+  aesthetic: "blueprint",
+  content: {
+    sections: [
+      { label: "Edge", content: "<div class=\"inner-card\">API Gateway</div>" },
+      { label: "Core", content: "<div class=\"inner-card\">Auth Service</div>", isHero: true },
+    ],
+  },
+});
+
+// Render a Mermaid flowchart
+generate_visual({
+  type: "flowchart",
+  title: "Data Pipeline",
+  aesthetic: "editorial",
+  content: "graph LR; A[Ingest] --> B[Transform] --> C[Store]",
+});
+
+// Render a comparison table
+generate_visual({
+  type: "table",
+  title: "API Endpoints",
+  aesthetic: "paper",
+  content: [
+    { method: "GET", path: "/users", status: "stable" },
+    { method: "POST", path: "/users", status: "beta" },
+  ],
+});
+```
+
+### Tool Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | enum | Visual type: `architecture`, `flowchart`, `sequence`, `er`, `state`, `table`, `diff`, `plan`, `timeline`, `dashboard`, `slides`, `mermaid_custom` |
+| `content` | string \| array | Raw content (mermaid syntax, markdown) or structured data rows |
+| `title` | string | Title for the visualization |
+| `aesthetic` | enum | Palette: `blueprint`, `editorial`, `paper`, `terminal`, `dracula`, `nord`, `solarized`, `gruvbox` |
+| `theme` | enum | `light`, `dark`, or `auto` |
+| `filename` | string | Optional output filename (auto-generated if omitted) |
+
+### Slash Commands
+
+- `/visual-reopen <n>` — re-open a recently generated visual by index (1-10)
+- `/visual-list` — list recently generated visuals
+
+### Output Location
+
+Generated HTML files are saved to `~/.agent/diagrams/` and automatically opened in your default browser.
+
+## 🏗️ Architecture
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
+│  LLM Request│────▶│ generate_visual  │────▶│   Browser   │
+│  (via PI)   │     │  (defineTool)    │     │   (HTML)    │
+└─────────────┘     └────────┬─────────┘     └─────────────┘
+                             │
+                    ┌────────▼─────────┐
+                    │ Palette + Template│
+                    │ HTML Generation   │
+                    │ File Written      │
+                    └───────────────────┘
+```
+
+Every tool call:
+
+1. Validates parameters (`type`, `content`, `aesthetic`, `theme`).
+2. Picks a template (`architecture`, `mermaid`, `data-table`) and a palette.
+3. Generates a self-contained HTML document with embedded CSS/JS.
+4. Truncates output to PI's ~50KB/2000-line limit via `truncateHead`.
+5. Writes the file to `~/.agent/diagrams/` and opens it in the default browser.
+
+## 🎨 Design Principles
+
+Inherited from [nicobailon/visual-explainer](https://github.com/nicobailon/visual-explainer):
+
+- **Typography First** — distinctive font pairings (never Inter as primary)
+- **Warm Palettes** — terracotta, sage, teal, rose (never indigo/violet/pink defaults)
+- **Depth Hierarchy** — hero → elevated → default → recessed visual weight
+- **No AI Slop** — forbidden: gradient text, emoji headers, neon glows, animated shadows
+- **Accessibility** — respects `prefers-reduced-motion`, semantic HTML tables
+
+## 🧪 Development
+
+```bash
+# Install dependencies (also wires lefthook git hooks)
+bun install
+
+# Run tests
+bun test
+
+# Lint & format
+bun run check
+
+# Typecheck
+bun run typecheck
+
+# Build for publish
+bun run build
+```
+
+## 📁 Project Structure
+
+```
+src/
+├── index.ts              # Extension entry, tool registration, state
+├── types.ts              # TypeScript type definitions
+├── templates/
+│   ├── architecture.ts   # CSS Grid card layout
+│   ├── data-table.ts     # HTML table template
+│   ├── mermaid.ts        # Mermaid diagram wrapper
+│   └── shared.ts         # Palettes, fonts, CSS variables
+└── utils/
+    ├── browser-open.ts   # Cross-platform browser launcher
+    ├── file-writer.ts    # Temp file + state management
+    └── validators.ts     # Input validation
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feat/amazing`)
+3. Commit with conventional commits (`git commit -m "feat: add something"`)
+4. Push to the branch (`git push origin feat/amazing`)
+5. Open a Pull Request
+
+## 🙏 Credits
+
+This extension re-uses the visual design system (palettes, typography, layout primitives) from [**nicobailon/visual-explainer**](https://github.com/nicobailon/visual-explainer) by [Nico Bailon](https://github.com/nicobailon). The PI integration layer (tool API, validators, templates re-implementation, tests) is original work. Huge thanks to Nico for the beautiful aesthetic foundation.
+
+## 📜 License
+
+MIT © [MonsieurBarti](https://github.com/MonsieurBarti)
+
+---
+
+<div align="center">
+  <sub>Built with ⚡ by <a href="https://github.com/MonsieurBarti">MonsieurBarti</a></sub>
+</div>

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Visual Explainer PI Extension
+ *
+ * Generates beautiful, self-contained HTML pages for diagrams, architecture,
+ * diff reviews, plan audits, data tables, and project recaps.
+ *
+ * Based on nicobailon/visual-explainer design principles.
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+/**
+ * Main extension export
+ */
+export default function visualExplainerExtension(pi: ExtensionAPI): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AA+JlE;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAAC,EAAE,EAAE,YAAY,QA6IhE"}

package/dist/index.js

@@ -0,0 +1,238 @@
+/**
+ * Visual Explainer PI Extension
+ *
+ * Generates beautiful, self-contained HTML pages for diagrams, architecture,
+ * diff reviews, plan audits, data tables, and project recaps.
+ *
+ * Based on nicobailon/visual-explainer design principles.
+ */
+import { StringEnum } from "@mariozechner/pi-ai";
+import { defineTool, truncateHead } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { generateArchitectureTemplate } from "./templates/architecture.js";
+import { generateTableTemplate } from "./templates/data-table.js";
+import { generateMermaidTemplate } from "./templates/mermaid.js";
+import { openInBrowser } from "./utils/browser-open.js";
+import { createInitialState, writeHtmlFile } from "./utils/file-writer.js";
+import { generateDefaultFilename, sanitizeFilename, validateParams } from "./utils/validators.js";
+// Extension state
+const state = createInitialState();
+/**
+ * Generate visual HTML based on type and content
+ */
+async function generateVisual(params, pi) {
+    // Determine if dark mode
+    const isDark = params.theme === "dark" || (params.theme === "auto" && prefersDarkMode());
+    // Generate HTML based on type
+    let html;
+    switch (params.type) {
+        case "architecture":
+            html = generateArchitectureTemplate(params.title, params.content, params.aesthetic ?? "blueprint", isDark);
+            break;
+        case "flowchart":
+        case "sequence":
+        case "er":
+        case "state":
+        case "mermaid_custom":
+            html = generateMermaidTemplate(params.title, {
+                mermaidSyntax: params.content,
+                caption: `${params.type} diagram`,
+            }, params.aesthetic ?? "blueprint", isDark);
+            break;
+        case "table":
+            html = generateTableTemplate(params.title, params.content, params.aesthetic ?? "blueprint", isDark);
+            break;
+        case "diff":
+            // For now, treat diff as architecture with special handling
+            html = generateArchitectureTemplate(params.title, {
+                sections: [
+                    {
+                        label: "Changes Overview",
+                        content: `<div class="inner-card"><div class="title">${escapeHtml(params.content).substring(0, 100)}...</div></div>`,
+                    },
+                ],
+            }, params.aesthetic ?? "blueprint", isDark);
+            break;
+        case "plan":
+            html = generateArchitectureTemplate(params.title, {
+                sections: [
+                    {
+                        label: "Implementation Plan",
+                        content: `<div class="callout">${escapeHtml(params.content).substring(0, 200)}...</div>`,
+                        isHero: true,
+                    },
+                ],
+            }, params.aesthetic ?? "blueprint", isDark);
+            break;
+        case "timeline":
+        case "dashboard":
+        case "slides":
+            // Fallback to architecture template for now
+            console.warn(`Type ${params.type} not fully implemented, using architecture template`);
+            html = generateArchitectureTemplate(params.title, {
+                sections: [
+                    {
+                        label: params.type,
+                        content: `<div class="inner-card"><div class="title">Content</div><div class="desc">${escapeHtml(String(params.content)).substring(0, 200)}...</div></div>`,
+                    },
+                ],
+            }, params.aesthetic ?? "blueprint", isDark);
+            break;
+        default:
+            throw new Error(`Unsupported visual type: ${params.type}`);
+    }
+    // Safety check: truncate if too large
+    const truncated = truncateHead(html, { maxBytes: 50000, maxLines: 2000 });
+    // Generate filename
+    const filename = params.filename
+        ? sanitizeFilename(params.filename)
+        : generateDefaultFilename(params.title);
+    // Write file
+    const filePath = await writeHtmlFile(filename, truncated.content, state);
+    // Open in browser
+    await openInBrowser(filePath, pi);
+    // Generate preview snippet (first 500 chars of content summary)
+    const previewSnippet = `Generated ${params.type} visualization: ${params.title}`;
+    return {
+        filePath,
+        previewSnippet,
+        url: `file://${filePath}`,
+    };
+}
+function prefersDarkMode() {
+    // This runs on the server, so we default to light
+    // In a real implementation, this could check system preferences
+    return false;
+}
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#039;");
+}
+/**
+ * Main extension export
+ */
+export default function visualExplainerExtension(pi) {
+    // Initialize on session start
+    pi.on("session_start", async (_event, ctx) => {
+        if (ctx.hasUI) {
+            ctx.ui.notify("Visual explainer ready", "info");
+        }
+    });
+    // Register generate_visual tool
+    const generateVisualTool = defineTool({
+        name: "generate_visual",
+        label: "Generate Visual",
+        description: "Generate beautiful, self-contained HTML pages for diagrams, architecture overviews, diff reviews, data tables, and visual explanations. Opens result in browser. Based on nicobailon/visual-explainer design principles.",
+        promptSnippet: "Create a visual diagram/architecture/table",
+        promptGuidelines: [
+            "Use this tool when the user asks for diagrams, architecture views, or data tables",
+            "Proactively use for complex tables (4+ rows, 3+ columns) instead of ASCII",
+            "Choose aesthetic based on context: blueprint (technical), editorial (formal), paper (warm), terminal (retro), dracula/nord/solarized/gruvbox (IDE themes)",
+            "Content can be structured data (for tables) or mermaid syntax (for diagrams)",
+        ],
+        parameters: Type.Object({
+            type: StringEnum([
+                "architecture",
+                "flowchart",
+                "sequence",
+                "er",
+                "state",
+                "table",
+                "diff",
+                "plan",
+                "timeline",
+                "dashboard",
+                "slides",
+                "mermaid_custom",
+            ], { description: "Type of visualization to generate" }),
+            content: Type.Union([
+                Type.String({ description: "Raw content (mermaid syntax, markdown)" }),
+                Type.Array(Type.Record(Type.String(), Type.Unknown()), {
+                    description: "Structured data rows for tables",
+                }),
+            ]),
+            title: Type.String({ description: "Title for the visualization" }),
+            aesthetic: Type.Optional(StringEnum([
+                "blueprint",
+                "editorial",
+                "paper",
+                "terminal",
+                "dracula",
+                "nord",
+                "solarized",
+                "gruvbox",
+            ], { description: "Visual aesthetic/theme palette" })),
+            theme: Type.Optional(StringEnum(["light", "dark", "auto"], {
+                description: "Color theme mode",
+            })),
+            filename: Type.Optional(Type.String({ description: "Output filename (auto-generated if omitted)" })),
+        }),
+        async execute(_toolCallId, rawParams, _signal, _onUpdate, _ctx) {
+            // Validate parameters
+            const params = validateParams(rawParams);
+            // Generate visual
+            const result = await generateVisual(params, pi);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${result.previewSnippet}\n\nOpened in browser: ${result.url}\nFile: ${result.filePath}`,
+                    },
+                ],
+                details: {
+                    type: params.type,
+                    title: params.title,
+                    aesthetic: params.aesthetic,
+                    theme: params.theme,
+                    filePath: result.filePath,
+                    url: result.url,
+                },
+            };
+        },
+    });
+    pi.registerTool(generateVisualTool);
+    // Register reopen command for recent files
+    pi.registerCommand("visual-reopen", {
+        description: "Re-open a recently generated visual by index (1-10)",
+        handler: async (args, ctx) => {
+            const index = Number.parseInt(args, 10) - 1;
+            if (index < 0 || index >= state.recentFiles.length) {
+                if (ctx.hasUI) {
+                    ctx.ui.notify(`Invalid index. Use 1-${state.recentFiles.length}`, "error");
+                }
+                return;
+            }
+            const filePath = state.recentFiles[index];
+            await openInBrowser(filePath, pi);
+            if (ctx.hasUI) {
+                ctx.ui.notify(`Re-opened: ${filePath}`, "info");
+            }
+        },
+    });
+    // Register list command
+    pi.registerCommand("visual-list", {
+        description: "List recently generated visuals",
+        handler: async (_args, ctx) => {
+            if (state.recentFiles.length === 0) {
+                if (ctx.hasUI) {
+                    ctx.ui.notify("No recent visuals", "warning");
+                }
+                return;
+            }
+            const list = state.recentFiles.map((f, i) => `${i + 1}. ${f}`).join("\n");
+            if (ctx.hasUI) {
+                ctx.ui.notify(`Recent visuals:\n${list}`, "info");
+            }
+        },
+    });
+    // Cleanup on shutdown
+    pi.on("session_shutdown", async () => {
+        // Note: We don't delete the HTML files - they persist for user reference
+        // Only cleanup would be if we created any temp directories
+        state.tempDirs = [];
+    });
+}

package/dist/templates/architecture.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Architecture template - CSS Grid card layout for text-heavy system overviews
+ * Based on nicobailon/visual-explainer architecture.html
+ */
+import type { Aesthetic } from "../types.js";
+export interface ArchitectureSection {
+    label: string;
+    labelColor?: "accent" | "green" | "orange" | "teal" | "plum";
+    content: string;
+    isHero?: boolean;
+    isRecessed?: boolean;
+}
+export interface ArchitectureContent {
+    sections: ArchitectureSection[];
+    flowArrows?: {
+        label: string;
+    }[];
+    threeColumn?: ArchitectureSection[];
+    pipeline?: {
+        steps: {
+            num: string;
+            name: string;
+            detail: string;
+            color: string;
+        }[];
+        legend?: {
+            color: string;
+            label: string;
+        }[];
+    };
+}
+export declare function generateArchitectureTemplate(title: string, content: ArchitectureContent, aesthetic: Aesthetic, isDark: boolean): string;
+//# sourceMappingURL=architecture.d.ts.map

package/dist/templates/architecture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"architecture.d.ts","sourceRoot":"","sources":["../../src/templates/architecture.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,aAAa,CAAC;AAUtD,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjC,WAAW,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACpC,QAAQ,CAAC,EAAE;QACV,KAAK,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QACtE,MAAM,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KAC5C,CAAC;CACF;AAED,wBAAgB,4BAA4B,CAC3C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,OAAO,GACb,MAAM,CAQR"}