omegon 0.6.0

package/extensions/render/excalidraw/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Excalidraw element factory — programmatic .excalidraw file generation.
+ *
+ * Usage in LLM tool calls:
+ *   import { rect, diamond, ellipse, dot, text, arrow, line,
+ *            bindArrow, createDocument, validateDocument,
+ *            fanOut, timeline, grid,
+ *            SEMANTIC_COLORS, TEXT_COLORS } from "./excalidraw/index.ts";
+ *
+ * See UPSTREAM.md for vendoring provenance and sync instructions.
+ */
+
+export {
+	// Shape factories
+	rect,
+	diamond,
+	ellipse,
+	dot,
+	// Text
+	text,
+	// Connectors
+	arrow,
+	line,
+	// Binding
+	bindArrow,
+	// Document
+	createDocument,
+	validateDocument,
+	resetIndexCounter,
+	// Layout helpers
+	fanOut,
+	timeline,
+	grid,
+} from "./elements.ts";
+
+export type {
+	ExcalidrawElement,
+	ExcalidrawFile,
+	RectangleElement,
+	DiamondElement,
+	EllipseElement,
+	TextElement,
+	ArrowElement,
+	LineElement,
+	SemanticPurpose,
+	TextLevel,
+	Point,
+	ShapeOptions,
+	TextOptions,
+	ArrowOptions,
+} from "./elements.ts";
+
+export {
+	SEMANTIC_COLORS,
+	TEXT_COLORS,
+	FONT_FAMILIES,
+	DEFAULT_ELEMENT_STYLE,
+	DEFAULT_APP_STATE,
+} from "./types.ts";
+
+export type {
+	ColorPair,
+	AppState,
+	ArrowBinding,
+	BoundElement,
+} from "./types.ts";

package/extensions/render/excalidraw/types.ts

@@ -0,0 +1,223 @@
+/**
+ * Excalidraw Element Type Definitions
+ *
+ * Vendored from @swiftlysingh/excalidraw-cli@1.1.0 (src/types/excalidraw.ts)
+ * with additions for semantic palette system. See UPSTREAM.md for sync guide.
+ *
+ * Based on Excalidraw JSON schema v2 (excalidraw.com)
+ */
+
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+
+export type ExcalidrawElementType =
+	| "rectangle"
+	| "diamond"
+	| "ellipse"
+	| "text"
+	| "arrow"
+	| "line"
+	| "freedraw";
+
+export type FillStyle = "solid" | "hachure" | "cross-hatch";
+export type StrokeStyle = "solid" | "dashed" | "dotted";
+export type Arrowhead = "arrow" | "bar" | "dot" | "triangle" | null;
+export type TextAlign = "left" | "center" | "right";
+export type VerticalAlign = "top" | "middle" | "bottom";
+
+export interface Roundness {
+	type: 1 | 2 | 3; // 1=legacy, 2=proportional, 3=adaptive
+}
+
+export interface BoundElement {
+	id: string;
+	type: "arrow" | "text";
+}
+
+export interface ArrowBinding {
+	elementId: string;
+	mode: "orbit" | "point";
+	fixedPoint: [number, number]; // Normalized [0-1] coordinates
+}
+
+// ---------------------------------------------------------------------------
+// Element types
+// ---------------------------------------------------------------------------
+
+export interface ElementBase {
+	id: string;
+	type: ExcalidrawElementType;
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	angle: number;
+	strokeColor: string;
+	backgroundColor: string;
+	fillStyle: FillStyle;
+	strokeWidth: number;
+	strokeStyle: StrokeStyle;
+	roughness: number;
+	opacity: number;
+	groupIds: string[];
+	frameId: string | null;
+	index: string;
+	roundness: Roundness | null;
+	seed: number;
+	version: number;
+	versionNonce: number;
+	isDeleted: boolean;
+	boundElements: BoundElement[] | null;
+	updated: number;
+	link: string | null;
+	locked: boolean;
+}
+
+export interface RectangleElement extends ElementBase {
+	type: "rectangle";
+}
+
+export interface DiamondElement extends ElementBase {
+	type: "diamond";
+}
+
+export interface EllipseElement extends ElementBase {
+	type: "ellipse";
+}
+
+export interface TextElement extends ElementBase {
+	type: "text";
+	text: string;
+	fontSize: number;
+	fontFamily: number; // 1=Virgil, 2=Helvetica, 3=Cascadia, 5=Excalifont
+	textAlign: TextAlign;
+	verticalAlign: VerticalAlign;
+	containerId: string | null;
+	originalText: string;
+	autoResize: boolean;
+	lineHeight: number;
+}
+
+export interface ArrowElement extends ElementBase {
+	type: "arrow";
+	points: Array<[number, number]>;
+	lastCommittedPoint: [number, number] | null;
+	startBinding: ArrowBinding | null;
+	endBinding: ArrowBinding | null;
+	startArrowhead: Arrowhead;
+	endArrowhead: Arrowhead;
+	elbowed: boolean;
+}
+
+export interface LineElement extends ElementBase {
+	type: "line";
+	points: Array<[number, number]>;
+	lastCommittedPoint: [number, number] | null;
+	startBinding: ArrowBinding | null;
+	endBinding: ArrowBinding | null;
+	startArrowhead: Arrowhead;
+	endArrowhead: Arrowhead;
+}
+
+export type ExcalidrawElement =
+	| RectangleElement
+	| DiamondElement
+	| EllipseElement
+	| TextElement
+	| ArrowElement
+	| LineElement;
+
+// ---------------------------------------------------------------------------
+// File structure
+// ---------------------------------------------------------------------------
+
+export interface AppState {
+	gridSize: number;
+	gridStep: number;
+	gridModeEnabled: boolean;
+	viewBackgroundColor: string;
+}
+
+export interface ExcalidrawFile {
+	type: "excalidraw";
+	version: 2;
+	source: string;
+	elements: ExcalidrawElement[];
+	appState: AppState;
+	files: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_APP_STATE: AppState = {
+	gridSize: 20,
+	gridStep: 5,
+	gridModeEnabled: false,
+	viewBackgroundColor: "#06080e",
+};
+
+export const DEFAULT_ELEMENT_STYLE = {
+	strokeColor: "#1e1e1e",
+	backgroundColor: "transparent",
+	fillStyle: "solid" as FillStyle,
+	strokeWidth: 2,
+	strokeStyle: "solid" as StrokeStyle,
+	roughness: 0, // Clean/modern default (upstream uses 1)
+	opacity: 100,
+};
+
+export const FONT_FAMILIES = {
+	Virgil: 1,
+	Helvetica: 2,
+	Cascadia: 3,
+	Excalifont: 5,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Semantic palette (omegon addition, not from upstream)
+// ---------------------------------------------------------------------------
+
+export type SemanticPurpose =
+	| "primary"
+	| "secondary"
+	| "tertiary"
+	| "start"
+	| "end"
+	| "warning"
+	| "decision"
+	| "ai"
+	| "inactive"
+	| "error"
+	| "evidence";
+
+export interface ColorPair {
+	fill: string;
+	stroke: string;
+}
+
+export const SEMANTIC_COLORS: Record<SemanticPurpose, ColorPair> = {
+	primary:   { fill: "#1a4a6e", stroke: "#2ab4c8" },
+	secondary: { fill: "#1a3a5a", stroke: "#1a8898" },
+	tertiary:  { fill: "#0e2a40", stroke: "#344858" },
+	start:     { fill: "#0e2e20", stroke: "#1ab878" },
+	end:       { fill: "#2e2010", stroke: "#b89020" },
+	warning:   { fill: "#2a1808", stroke: "#c86418" },
+	decision:  { fill: "#2a1010", stroke: "#c83030" },
+	ai:        { fill: "#1a1040", stroke: "#6060c0" },
+	inactive:  { fill: "#0e1622", stroke: "#344858" },
+	error:     { fill: "#2e0e0e", stroke: "#c83030" },
+	evidence:  { fill: "#06080e", stroke: "#1a3448" },
+};
+
+export const TEXT_COLORS = {
+	title:    "#2ab4c8",
+	subtitle: "#1a8898",
+	body:     "#607888",
+	onLight:  "#c4d8e4",
+	onDark:   "#c4d8e4",
+} as const;
+
+export type TextLevel = keyof typeof TEXT_COLORS;

package/extensions/render/excalidraw-renderer/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "excalidraw-render"
+version = "0.1.0"
+description = "Render .excalidraw JSON files to PNG via Playwright + headless Chromium"
+requires-python = ">=3.11"
+dependencies = [
+    "playwright>=1.40.0",
+]

package/extensions/render/excalidraw-renderer/render_excalidraw.py

@@ -0,0 +1,182 @@
+"""Render Excalidraw JSON to PNG using Playwright + headless Chromium.
+
+Vendored from coleam00/excalidraw-diagram-skill (references/render_excalidraw.py)
+with minor changes: pinned esm.sh version in template, improved error messages.
+
+Usage:
+    cd skills/visualize/references/excalidraw
+    uv run python render_excalidraw.py <path-to-file.excalidraw> [--output path.png] [--scale 2]
+
+First-time setup:
+    cd skills/visualize/references/excalidraw
+    uv sync
+    uv run playwright install chromium
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def validate_excalidraw(data: dict) -> list[str]:
+    """Validate Excalidraw JSON structure. Returns list of errors (empty = valid)."""
+    errors: list[str] = []
+
+    if data.get("type") != "excalidraw":
+        errors.append(f"Expected type 'excalidraw', got '{data.get('type')}'")
+
+    if "elements" not in data:
+        errors.append("Missing 'elements' array")
+    elif not isinstance(data["elements"], list):
+        errors.append("'elements' must be an array")
+    elif len(data["elements"]) == 0:
+        errors.append("'elements' array is empty — nothing to render")
+
+    return errors
+
+
+def compute_bounding_box(elements: list[dict]) -> tuple[float, float, float, float]:
+    """Compute bounding box (min_x, min_y, max_x, max_y) across all elements."""
+    min_x = float("inf")
+    min_y = float("inf")
+    max_x = float("-inf")
+    max_y = float("-inf")
+
+    for el in elements:
+        if el.get("isDeleted"):
+            continue
+        x = el.get("x", 0)
+        y = el.get("y", 0)
+        w = el.get("width", 0)
+        h = el.get("height", 0)
+
+        if el.get("type") in ("arrow", "line") and "points" in el:
+            for px, py in el["points"]:
+                min_x = min(min_x, x + px)
+                min_y = min(min_y, y + py)
+                max_x = max(max_x, x + px)
+                max_y = max(max_y, y + py)
+        else:
+            min_x = min(min_x, x)
+            min_y = min(min_y, y)
+            max_x = max(max_x, x + abs(w))
+            max_y = max(max_y, y + abs(h))
+
+    if min_x == float("inf"):
+        return (0, 0, 800, 600)
+
+    return (min_x, min_y, max_x, max_y)
+
+
+def render(
+    excalidraw_path: Path,
+    output_path: Path | None = None,
+    scale: int = 2,
+    max_width: int = 1920,
+) -> Path:
+    """Render an .excalidraw file to PNG. Returns the output PNG path."""
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        print("ERROR: playwright not installed.", file=sys.stderr)
+        print("Run: cd skills/visualize/references/excalidraw && uv sync && uv run playwright install chromium", file=sys.stderr)
+        sys.exit(1)
+
+    raw = excalidraw_path.read_text(encoding="utf-8")
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(f"ERROR: Invalid JSON in {excalidraw_path}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    errors = validate_excalidraw(data)
+    if errors:
+        print(f"ERROR: Invalid Excalidraw file:", file=sys.stderr)
+        for err in errors:
+            print(f"  - {err}", file=sys.stderr)
+        sys.exit(1)
+
+    elements = [e for e in data["elements"] if not e.get("isDeleted")]
+    min_x, min_y, max_x, max_y = compute_bounding_box(elements)
+    padding = 80
+    diagram_w = max_x - min_x + padding * 2
+    diagram_h = max_y - min_y + padding * 2
+
+    vp_width = min(int(diagram_w), max_width)
+    vp_height = max(int(diagram_h), 600)
+
+    if output_path is None:
+        output_path = excalidraw_path.with_suffix(".png")
+
+    template_path = Path(__file__).parent / "render_template.html"
+    if not template_path.exists():
+        print(f"ERROR: Template not found at {template_path}", file=sys.stderr)
+        sys.exit(1)
+
+    template_url = template_path.as_uri()
+
+    with sync_playwright() as p:
+        try:
+            browser = p.chromium.launch(headless=True)
+        except Exception as e:
+            if "Executable doesn't exist" in str(e) or "browserType.launch" in str(e):
+                print("ERROR: Chromium not installed for Playwright.", file=sys.stderr)
+                print("Run: cd skills/visualize/references/excalidraw && uv run playwright install chromium", file=sys.stderr)
+                sys.exit(1)
+            raise
+
+        try:
+            page = browser.new_page(
+                viewport={"width": vp_width, "height": vp_height},
+                device_scale_factor=scale,
+            )
+
+            page.goto(template_url)
+            page.wait_for_function("window.__moduleReady === true", timeout=30000)
+
+            # Use Playwright argument passing instead of string interpolation
+            # to avoid JS injection issues with special characters in JSON values.
+            result = page.evaluate("(data) => window.renderDiagram(data)", data)
+
+            if not result or not result.get("success"):
+                error_msg = result.get("error", "Unknown render error") if result else "renderDiagram returned null"
+                print(f"ERROR: Render failed: {error_msg}", file=sys.stderr)
+                sys.exit(1)
+
+            # Wait for render to complete (exportToSvg is async, renderDiagram
+            # sets __renderComplete after SVG is appended to DOM).
+            page.wait_for_function("window.__renderComplete === true", timeout=15000)
+
+            svg_el = page.query_selector("#root svg")
+            if svg_el is None:
+                print("ERROR: No SVG element found after render.", file=sys.stderr)
+                sys.exit(1)
+
+            svg_el.screenshot(path=str(output_path))
+        finally:
+            browser.close()
+
+    return output_path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Render Excalidraw JSON to PNG")
+    parser.add_argument("input", type=Path, help="Path to .excalidraw JSON file")
+    parser.add_argument("--output", "-o", type=Path, default=None, help="Output PNG path")
+    parser.add_argument("--scale", "-s", type=int, default=2, help="Device scale factor (default: 2)")
+    parser.add_argument("--width", "-w", type=int, default=1920, help="Max viewport width (default: 1920)")
+    args = parser.parse_args()
+
+    if not args.input.exists():
+        print(f"ERROR: File not found: {args.input}", file=sys.stderr)
+        sys.exit(1)
+
+    png_path = render(args.input, args.output, args.scale, args.width)
+    print(str(png_path))
+
+
+if __name__ == "__main__":
+    main()

package/extensions/render/excalidraw-renderer/render_template.html

@@ -0,0 +1,59 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { background: #ffffff; overflow: hidden; }
+    #root { display: inline-block; }
+    #root svg { display: block; }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+
+  <!--
+    Pin @excalidraw/excalidraw to a specific version to avoid CDN updates breaking rendering.
+    Update this version intentionally when syncing with upstream (see UPSTREAM.md).
+    Current pin: 0.18.0 (pinned 2026-03-03)
+  -->
+  <script type="module">
+    import { exportToSvg } from "https://esm.sh/@excalidraw/excalidraw@0.18.0?bundle";
+
+    window.renderDiagram = async function(jsonData) {
+      try {
+        const data = typeof jsonData === "string" ? JSON.parse(jsonData) : jsonData;
+        const elements = data.elements || [];
+        const appState = data.appState || {};
+        const files = data.files || {};
+
+        appState.viewBackgroundColor = appState.viewBackgroundColor || "#ffffff";
+        appState.exportWithDarkMode = false;
+
+        const svg = await exportToSvg({
+          elements: elements,
+          appState: {
+            ...appState,
+            exportBackground: true,
+          },
+          files: files,
+        });
+
+        const root = document.getElementById("root");
+        root.innerHTML = "";
+        root.appendChild(svg);
+
+        window.__renderComplete = true;
+        window.__renderError = null;
+        return { success: true, width: svg.getAttribute("width"), height: svg.getAttribute("height") };
+      } catch (err) {
+        window.__renderComplete = true;
+        window.__renderError = err.message;
+        return { success: false, error: err.message };
+      }
+    };
+
+    window.__moduleReady = true;
+  </script>
+</body>
+</html>