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

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Type definitions for visual-explainer-pi
+ */
+export type VisualType = "architecture" | "flowchart" | "sequence" | "er" | "state" | "table" | "diff" | "plan" | "timeline" | "dashboard" | "slides" | "mermaid_custom";
+export type Aesthetic = "blueprint" | "editorial" | "paper" | "terminal" | "dracula" | "nord" | "solarized" | "gruvbox";
+export type Theme = "light" | "dark" | "auto";
+export interface GenerateVisualParams {
+    type: VisualType;
+    content: string | Record<string, unknown>[];
+    title: string;
+    aesthetic?: Aesthetic;
+    theme?: Theme;
+    filename?: string;
+}
+export interface GenerateResult {
+    filePath: string;
+    previewSnippet: string;
+    url: string;
+}
+export interface ExtensionState {
+    recentFiles: string[];
+    tempDirs: string[];
+    defaultAesthetic: Aesthetic;
+    defaultTheme: Theme;
+}
+export interface TemplateContext {
+    title: string;
+    content: unknown;
+    aesthetic: Aesthetic;
+    theme: Theme;
+}
+export interface Palette {
+    [key: string]: string;
+    bg: string;
+    surface: string;
+    surface2: string;
+    surfaceElevated: string;
+    border: string;
+    borderBright: string;
+    text: string;
+    textDim: string;
+    accent: string;
+    accentDim: string;
+    green: string;
+    greenDim: string;
+    orange: string;
+    orangeDim: string;
+    teal: string;
+    tealDim: string;
+    plum: string;
+    plumDim: string;
+}
+export type FontPairing = {
+    body: string;
+    mono: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,UAAU,GACnB,cAAc,GACd,WAAW,GACX,UAAU,GACV,IAAI,GACJ,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,UAAU,GACV,WAAW,GACX,QAAQ,GACR,gBAAgB,CAAC;AAEpB,MAAM,MAAM,SAAS,GAClB,WAAW,GACX,WAAW,GACX,OAAO,GACP,UAAU,GACV,SAAS,GACT,MAAM,GACN,WAAW,GACX,SAAS,CAAC;AAEb,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gBAAgB,EAAE,SAAS,CAAC;IAC5B,YAAY,EAAE,KAAK,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;CACb;AAED,MAAM,WAAW,OAAO;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb,CAAC"}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for visual-explainer-pi
+ */
+export {};

package/dist/utils/browser-open.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Cross-platform browser opening utility
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export declare function openInBrowser(filePath: string, pi: ExtensionAPI): Promise<void>;
+//# sourceMappingURL=browser-open.d.ts.map

package/dist/utils/browser-open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-open.d.ts","sourceRoot":"","sources":["../../src/utils/browser-open.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCrF"}

package/dist/utils/browser-open.js

@@ -0,0 +1,33 @@
+/**
+ * Cross-platform browser opening utility
+ */
+export async function openInBrowser(filePath, pi) {
+    const platform = process.platform;
+    let command;
+    let args;
+    switch (platform) {
+        case "darwin":
+            command = "open";
+            args = [filePath];
+            break;
+        case "linux":
+            command = "xdg-open";
+            args = [filePath];
+            break;
+        case "win32":
+            command = "cmd";
+            args = ["/c", "start", "", filePath];
+            break;
+        default:
+            throw new Error(`Unsupported platform: ${platform}. Please open manually: ${filePath}`);
+    }
+    try {
+        const result = await pi.exec(command, args, { timeout: 10000 });
+        if (result.code !== 0) {
+            throw new Error(`Browser open failed: ${result.stderr || "Unknown error"}`);
+        }
+    }
+    catch (error) {
+        throw new Error(`Failed to open browser: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/utils/file-writer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * File writing utilities for visual-explainer
+ */
+import type { ExtensionState } from "../types.js";
+export declare function ensureOutputDir(): Promise<string>;
+export declare function writeHtmlFile(filename: string, html: string, state: ExtensionState): Promise<string>;
+export declare function createInitialState(): ExtensionState;
+//# sourceMappingURL=file-writer.d.ts.map

package/dist/utils/file-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-writer.d.ts","sourceRoot":"","sources":["../../src/utils/file-writer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAOvD;AAED,wBAAsB,aAAa,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,cAAc,GACnB,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED,wBAAgB,kBAAkB,IAAI,cAAc,CAOnD"}

package/dist/utils/file-writer.js

@@ -0,0 +1,40 @@
+/**
+ * File writing utilities for visual-explainer
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const OUTPUT_DIR = join(homedir(), ".agent", "diagrams");
+export async function ensureOutputDir() {
+    try {
+        await mkdir(OUTPUT_DIR, { recursive: true });
+        return OUTPUT_DIR;
+    }
+    catch (error) {
+        throw new Error(`Failed to create output directory: ${OUTPUT_DIR}: ${error}`);
+    }
+}
+export async function writeHtmlFile(filename, html, state) {
+    const outputDir = await ensureOutputDir();
+    const filePath = join(outputDir, filename);
+    try {
+        await writeFile(filePath, html, "utf8");
+        // Track in recent files
+        state.recentFiles.unshift(filePath);
+        if (state.recentFiles.length > 10) {
+            state.recentFiles = state.recentFiles.slice(0, 10);
+        }
+        return filePath;
+    }
+    catch (error) {
+        throw new Error(`Failed to write HTML file: ${error}`);
+    }
+}
+export function createInitialState() {
+    return {
+        recentFiles: [],
+        tempDirs: [],
+        defaultAesthetic: "blueprint",
+        defaultTheme: "auto",
+    };
+}

package/dist/utils/validators.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Input validation utilities for visual-explainer
+ */
+import type { Aesthetic, GenerateVisualParams, Theme, VisualType } from "../types.js";
+export declare function validateVisualType(type: unknown): VisualType;
+export declare function validateAesthetic(aesthetic: unknown): Aesthetic;
+export declare function validateTheme(theme: unknown): Theme;
+export declare function validateParams(params: unknown): GenerateVisualParams;
+export declare function sanitizeFilename(filename: string): string;
+export declare function generateDefaultFilename(title: string): string;
+//# sourceMappingURL=validators.d.ts.map

package/dist/utils/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/utils/validators.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8BtF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAO5D;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,CAO/D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAOnD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,oBAAoB,CA4BpE;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO7D"}

package/dist/utils/validators.js

@@ -0,0 +1,93 @@
+/**
+ * Input validation utilities for visual-explainer
+ */
+const VALID_VISUAL_TYPES = [
+    "architecture",
+    "flowchart",
+    "sequence",
+    "er",
+    "state",
+    "table",
+    "diff",
+    "plan",
+    "timeline",
+    "dashboard",
+    "slides",
+    "mermaid_custom",
+];
+const VALID_AESTHETICS = [
+    "blueprint",
+    "editorial",
+    "paper",
+    "terminal",
+    "dracula",
+    "nord",
+    "solarized",
+    "gruvbox",
+];
+const VALID_THEMES = ["light", "dark", "auto"];
+export function validateVisualType(type) {
+    if (typeof type !== "string" || !VALID_VISUAL_TYPES.includes(type)) {
+        throw new Error(`Invalid visual type: ${type}. Must be one of: ${VALID_VISUAL_TYPES.join(", ")}`);
+    }
+    return type;
+}
+export function validateAesthetic(aesthetic) {
+    if (aesthetic === undefined)
+        return "blueprint";
+    if (typeof aesthetic !== "string" || !VALID_AESTHETICS.includes(aesthetic)) {
+        console.warn(`Invalid aesthetic: ${aesthetic}. Falling back to "blueprint"`);
+        return "blueprint";
+    }
+    return aesthetic;
+}
+export function validateTheme(theme) {
+    if (theme === undefined)
+        return "auto";
+    if (typeof theme !== "string" || !VALID_THEMES.includes(theme)) {
+        console.warn(`Invalid theme: ${theme}. Falling back to "auto"`);
+        return "auto";
+    }
+    return theme;
+}
+export function validateParams(params) {
+    if (!params || typeof params !== "object") {
+        throw new Error("Parameters must be an object");
+    }
+    const p = params;
+    // Required fields
+    if (!p.title || typeof p.title !== "string") {
+        throw new Error("title is required and must be a string");
+    }
+    if (!p.content) {
+        throw new Error("content is required");
+    }
+    const type = validateVisualType(p.type);
+    const aesthetic = validateAesthetic(p.aesthetic);
+    const theme = validateTheme(p.theme);
+    return {
+        type,
+        content: p.content,
+        title: p.title,
+        aesthetic,
+        theme,
+        filename: p.filename && typeof p.filename === "string" ? p.filename : undefined,
+    };
+}
+export function sanitizeFilename(filename) {
+    // Remove any path components and sanitize
+    const base = filename.replace(/^[./\\]+/, "").replace(/[\\/:*?"<>|]/g, "-");
+    // Ensure .html extension
+    if (!base.endsWith(".html")) {
+        return `${base}.html`;
+    }
+    return base;
+}
+export function generateDefaultFilename(title) {
+    const timestamp = new Date().toISOString().split("T")[0];
+    const sanitized = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return `${timestamp}-${sanitized || "visual"}.html`;
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+	"name": "@the-forge-flow/visual-explainer-pi",
+	"version": "0.1.1",
+	"description": "PI extension for generating beautiful HTML visualizations of diagrams, architecture, and data",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:coverage": "vitest run --coverage",
+		"lint": "biome lint .",
+		"lint:fix": "biome lint . --write",
+		"format": "biome format .",
+		"format:fix": "biome format . --write",
+		"check": "biome check .",
+		"check:fix": "biome check . --write",
+		"typecheck": "tsc --noEmit",
+		"prepare": "lefthook install || true"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.4",
+		"@commitlint/cli": "^19.0.0",
+		"@commitlint/config-conventional": "^19.0.0",
+		"@sinclair/typebox": "^0.34.0",
+		"@types/node": "^22.0.0",
+		"lefthook": "^2.1.5",
+		"typescript": "^5.7.0",
+		"vitest": "^2.1.0"
+	},
+	"peerDependencies": {
+		"@mariozechner/pi-coding-agent": "*",
+		"@mariozechner/pi-ai": "*",
+		"@mariozechner/pi-tui": "*",
+		"@sinclair/typebox": "*"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"keywords": [
+		"pi-package",
+		"pi",
+		"extension",
+		"visualization",
+		"diagrams",
+		"architecture",
+		"html",
+		"mermaid"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/monsieurbarti/visual-explainer-pi.git"
+	},
+	"bugs": {
+		"url": "https://github.com/monsieurbarti/visual-explainer-pi/issues"
+	},
+	"homepage": "https://github.com/monsieurbarti/visual-explainer-pi#readme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"pi": {
+		"extensions": [
+			"./dist/index.js"
+		]
+	}
+}