@liminis/editor 0.1.0-rc.1

package/dist/app/editor/c4/parser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * C4-PlantUML Parser
+ *
+ * Parses C4-PlantUML macro syntax into a C4 diagram AST.
+ * Supports: Person, System, Container, Component (and _Ext, Db, Queue variants),
+ * System_Boundary, Container_Boundary, Rel (and directional variants), BiRel.
+ *
+ * Strips: @startuml/@enduml, !include, SHOW_LEGEND(), LAYOUT_* directives.
+ */
+import type { C4Diagram, ParseError, ParseResult } from './types.js';
+/**
+ * Parse C4-PlantUML code into a C4 diagram AST.
+ */
+export declare function parseC4(code: string): ParseResult;
+/**
+ * Validate that a C4 diagram is well-formed.
+ * Checks for duplicate IDs, missing relationship targets, etc.
+ */
+export declare function validateC4(diagram: C4Diagram): ParseError[];

package/dist/app/editor/c4/parser.js

@@ -0,0 +1,410 @@
+/**
+ * C4-PlantUML Parser
+ *
+ * Parses C4-PlantUML macro syntax into a C4 diagram AST.
+ * Supports: Person, System, Container, Component (and _Ext, Db, Queue variants),
+ * System_Boundary, Container_Boundary, Rel (and directional variants), BiRel.
+ *
+ * Strips: @startuml/@enduml, !include, SHOW_LEGEND(), LAYOUT_* directives.
+ */
+const ELEMENT_MACROS = {
+    // Person
+    Person: { type: 'person', external: false, shape: 'rectangle', argStyle: 'system', boundary: false },
+    Person_Ext: { type: 'person', external: true, shape: 'rectangle', argStyle: 'system', boundary: false },
+    // System
+    System: { type: 'system', external: false, shape: 'rectangle', argStyle: 'system', boundary: false },
+    System_Ext: { type: 'system', external: true, shape: 'rectangle', argStyle: 'system', boundary: false },
+    SystemDb: { type: 'system', external: false, shape: 'cylinder', argStyle: 'system', boundary: false },
+    SystemDb_Ext: { type: 'system', external: true, shape: 'cylinder', argStyle: 'system', boundary: false },
+    SystemQueue: { type: 'system', external: false, shape: 'queue', argStyle: 'system', boundary: false },
+    SystemQueue_Ext: { type: 'system', external: true, shape: 'queue', argStyle: 'system', boundary: false },
+    // Container
+    Container: { type: 'container', external: false, shape: 'rectangle', argStyle: 'detail', boundary: false },
+    Container_Ext: { type: 'container', external: true, shape: 'rectangle', argStyle: 'detail', boundary: false },
+    ContainerDb: { type: 'container', external: false, shape: 'cylinder', argStyle: 'detail', boundary: false },
+    ContainerDb_Ext: { type: 'container', external: true, shape: 'cylinder', argStyle: 'detail', boundary: false },
+    ContainerQueue: { type: 'container', external: false, shape: 'queue', argStyle: 'detail', boundary: false },
+    ContainerQueue_Ext: { type: 'container', external: true, shape: 'queue', argStyle: 'detail', boundary: false },
+    // Component
+    Component: { type: 'component', external: false, shape: 'rectangle', argStyle: 'detail', boundary: false },
+    Component_Ext: { type: 'component', external: true, shape: 'rectangle', argStyle: 'detail', boundary: false },
+    ComponentDb: { type: 'component', external: false, shape: 'cylinder', argStyle: 'detail', boundary: false },
+    ComponentDb_Ext: { type: 'component', external: true, shape: 'cylinder', argStyle: 'detail', boundary: false },
+    ComponentQueue: { type: 'component', external: false, shape: 'queue', argStyle: 'detail', boundary: false },
+    ComponentQueue_Ext: { type: 'component', external: true, shape: 'queue', argStyle: 'detail', boundary: false },
+    // Boundaries
+    System_Boundary: { type: 'system', external: false, shape: 'rectangle', argStyle: 'system', boundary: true },
+    Container_Boundary: { type: 'container', external: false, shape: 'rectangle', argStyle: 'system', boundary: true },
+    Enterprise_Boundary: { type: 'system', external: false, shape: 'rectangle', argStyle: 'system', boundary: true },
+    Boundary: { type: 'system', external: false, shape: 'rectangle', argStyle: 'system', boundary: true },
+    // Deployment nodes (C4 deployment diagrams)
+    Deployment_Node: { type: 'system', external: false, shape: 'rectangle', argStyle: 'detail', boundary: true },
+    Deployment_Node_L: { type: 'system', external: false, shape: 'rectangle', argStyle: 'detail', boundary: true },
+    Deployment_Node_R: { type: 'system', external: false, shape: 'rectangle', argStyle: 'detail', boundary: true },
+    Node: { type: 'system', external: false, shape: 'rectangle', argStyle: 'detail', boundary: true },
+    Node_L: { type: 'system', external: false, shape: 'rectangle', argStyle: 'detail', boundary: true },
+    Node_R: { type: 'system', external: false, shape: 'rectangle', argStyle: 'detail', boundary: true },
+    // Infrastructure nodes (C4 deployment diagrams)
+    InfrastructureNode: { type: 'component', external: false, shape: 'rectangle', argStyle: 'detail', boundary: false },
+    InfrastructureNode_Ext: { type: 'component', external: true, shape: 'rectangle', argStyle: 'detail', boundary: false },
+};
+const REL_MACROS = new Set([
+    'Rel', 'Rel_Back', 'Rel_Neighbor',
+    'Rel_D', 'Rel_U', 'Rel_L', 'Rel_R',
+    'BiRel', 'BiRel_D', 'BiRel_U', 'BiRel_L', 'BiRel_R',
+]);
+/** Directives and macros to silently skip */
+const SKIP_PREFIXES = ['@startuml', '@enduml', '!include', '!define', 'SHOW_', 'HIDE_', 'title '];
+// =============================================================================
+// LINE-BASED PARSER
+// =============================================================================
+/**
+ * Parse C4-PlantUML code into a C4 diagram AST.
+ */
+export function parseC4(code) {
+    const parser = new C4PlantUMLParser(code);
+    return parser.parse();
+}
+/**
+ * Validate that a C4 diagram is well-formed.
+ * Checks for duplicate IDs, missing relationship targets, etc.
+ */
+export function validateC4(diagram) {
+    const errors = [];
+    const elementIds = new Set();
+    for (const element of diagram.elements) {
+        if (elementIds.has(element.id)) {
+            errors.push({
+                message: `Duplicate element ID: '${element.id}'`,
+                line: 0,
+                column: 0,
+            });
+        }
+        elementIds.add(element.id);
+    }
+    for (const rel of diagram.relationships) {
+        if (!elementIds.has(rel.sourceId)) {
+            errors.push({
+                message: `Relationship source '${rel.sourceId}' not found`,
+                line: 0,
+                column: 0,
+            });
+        }
+        if (!elementIds.has(rel.targetId)) {
+            errors.push({
+                message: `Relationship target '${rel.targetId}' not found`,
+                line: 0,
+                column: 0,
+            });
+        }
+    }
+    return errors;
+}
+class C4PlantUMLParser {
+    lines;
+    lineNum = 0;
+    elements = [];
+    relationships = [];
+    errors = [];
+    direction;
+    constructor(code) {
+        this.lines = code.split('\n');
+    }
+    parse() {
+        this.parseLines(undefined);
+        const diagram = {
+            elements: this.elements,
+            relationships: this.relationships,
+            direction: this.direction,
+        };
+        return {
+            diagram: this.errors.length === 0 ? diagram : null,
+            errors: this.errors,
+        };
+    }
+    /**
+     * Parse lines at the current level. If parentId is set, we're inside a boundary.
+     * Stops when we hit a closing brace or run out of lines.
+     */
+    parseLines(parentId) {
+        while (this.lineNum < this.lines.length) {
+            const rawLine = this.lines[this.lineNum];
+            const line = this.stripComment(rawLine).trim();
+            // Empty or comment-only line
+            if (line === '') {
+                this.lineNum++;
+                continue;
+            }
+            // Closing brace — return to parent
+            if (line === '}' || line.startsWith('}')) {
+                this.lineNum++;
+                return;
+            }
+            // Parse LAYOUT directives
+            if (line.startsWith('LAYOUT_TOP_DOWN')) {
+                this.direction = 'down';
+                this.lineNum++;
+                continue;
+            }
+            if (line.startsWith('LAYOUT_LEFT_RIGHT')) {
+                this.direction = 'right';
+                this.lineNum++;
+                continue;
+            }
+            // Skip other directives
+            if (this.isSkippable(line)) {
+                this.lineNum++;
+                continue;
+            }
+            // Extract the macro name (first word before '(')
+            const macroMatch = /^([A-Za-z_][A-Za-z0-9_]*)\s*\(/.exec(line);
+            if (!macroMatch) {
+                // Unknown line
+                this.errors.push({
+                    message: `Unrecognized syntax: '${line.slice(0, 50)}'`,
+                    line: this.lineNum + 1,
+                    column: 1,
+                });
+                this.lineNum++;
+                continue;
+            }
+            const macroName = macroMatch[1];
+            // Element macro
+            if (macroName in ELEMENT_MACROS) {
+                this.parseElementMacro(macroName, line, parentId);
+                continue;
+            }
+            // Relationship macro
+            if (REL_MACROS.has(macroName)) {
+                this.parseRelMacro(line);
+                this.lineNum++;
+                continue;
+            }
+            // Unknown macro — skip
+            this.errors.push({
+                message: `Unknown macro: '${macroName}'`,
+                line: this.lineNum + 1,
+                column: 1,
+            });
+            this.lineNum++;
+        }
+    }
+    /**
+     * Parse an element macro like Person(alias, "Label", "Description")
+     * or a boundary like System_Boundary(alias, "Label") { ... }
+     */
+    parseElementMacro(macroName, line, parentId) {
+        const info = ELEMENT_MACROS[macroName];
+        const currentLine = this.lineNum + 1;
+        // Extract arguments from parentheses
+        const args = this.extractArgs(line, currentLine);
+        if (args === null) {
+            this.lineNum++;
+            return;
+        }
+        // First arg is always the alias (unquoted identifier)
+        const alias = args[0]?.replace(/^"|"$/g, '');
+        if (!alias) {
+            this.errors.push({
+                message: `${macroName}: missing alias (first argument)`,
+                line: currentLine,
+                column: 1,
+            });
+            this.lineNum++;
+            return;
+        }
+        // Build properties from remaining args
+        const properties = {};
+        let name;
+        if (info.external)
+            properties.external = true;
+        if (info.shape !== 'rectangle')
+            properties.shape = info.shape;
+        if (info.boundary)
+            properties.style = 'boundary';
+        if (info.argStyle === 'system') {
+            // (alias, "label", "description")
+            name = this.unquote(args[1] ?? '') || alias;
+            const desc = this.unquote(args[2] ?? '');
+            if (desc)
+                properties.description = desc;
+        }
+        else {
+            // (alias, "label", "technology", "description")
+            name = this.unquote(args[1] ?? '') || alias;
+            const tech = this.unquote(args[2] ?? '');
+            const desc = this.unquote(args[3] ?? '');
+            if (tech)
+                properties.tech = tech;
+            if (desc)
+                properties.description = desc;
+        }
+        // Check for $tags and other named params
+        for (const arg of args) {
+            if (arg.startsWith('$tags=')) {
+                // Could be used for styling in the future
+            }
+        }
+        const element = {
+            type: info.type,
+            id: alias,
+            name,
+            properties,
+            children: [],
+            parent: parentId,
+        };
+        this.elements.push(element);
+        // Check if this line ends with { (boundary with children)
+        const hasBrace = line.includes('{') && !line.includes('}');
+        if (hasBrace) {
+            this.lineNum++;
+            // Parse children
+            const childrenBefore = this.elements.length;
+            this.parseLines(alias);
+            // Link children
+            for (let i = childrenBefore; i < this.elements.length; i++) {
+                if (this.elements[i].parent === alias) {
+                    element.children.push(this.elements[i]);
+                }
+            }
+        }
+        else {
+            this.lineNum++;
+        }
+    }
+    /**
+     * Parse a relationship macro like Rel(from, to, "label", "tech")
+     */
+    parseRelMacro(line) {
+        const currentLine = this.lineNum + 1;
+        const args = this.extractArgs(line, currentLine);
+        if (args === null)
+            return;
+        if (args.length < 3) {
+            this.errors.push({
+                message: `Relationship requires at least 3 arguments (from, to, label)`,
+                line: currentLine,
+                column: 1,
+            });
+            return;
+        }
+        const sourceId = args[0].replace(/^"|"$/g, '');
+        const targetId = args[1].replace(/^"|"$/g, '');
+        const label = this.unquote(args[2]);
+        const tech = this.unquote(args[3] ?? '');
+        const fullLabel = tech ? `${label} [${tech}]` : label;
+        this.relationships.push({
+            sourceId,
+            targetId,
+            label: fullLabel,
+        });
+    }
+    /**
+     * Extract comma-separated arguments from a macro call.
+     * Handles quoted strings with commas inside them.
+     */
+    extractArgs(line, lineNum) {
+        // Find opening paren
+        const openIdx = line.indexOf('(');
+        if (openIdx === -1) {
+            this.errors.push({
+                message: `Expected '(' in macro call`,
+                line: lineNum,
+                column: 1,
+            });
+            return null;
+        }
+        // Find matching closing paren (handle nested parens in edge cases)
+        let depth = 0;
+        let closeIdx = -1;
+        for (let i = openIdx; i < line.length; i++) {
+            if (line[i] === '(')
+                depth++;
+            else if (line[i] === ')') {
+                depth--;
+                if (depth === 0) {
+                    closeIdx = i;
+                    break;
+                }
+            }
+        }
+        if (closeIdx === -1) {
+            this.errors.push({
+                message: `Unmatched '(' — missing closing ')'`,
+                line: lineNum,
+                column: openIdx + 1,
+            });
+            return null;
+        }
+        const inner = line.slice(openIdx + 1, closeIdx);
+        return this.splitArgs(inner);
+    }
+    /**
+     * Split a comma-separated argument string, respecting quoted strings.
+     */
+    splitArgs(inner) {
+        const args = [];
+        let current = '';
+        let inQuote = false;
+        let escaped = false;
+        for (const char of inner) {
+            if (escaped) {
+                current += char;
+                escaped = false;
+                continue;
+            }
+            if (char === '\\') {
+                escaped = true;
+                current += char;
+                continue;
+            }
+            if (char === '"') {
+                inQuote = !inQuote;
+                current += char;
+                continue;
+            }
+            if (char === ',' && !inQuote) {
+                const trimmed = current.trim();
+                if (trimmed)
+                    args.push(trimmed);
+                current = '';
+                continue;
+            }
+            current += char;
+        }
+        const trimmed = current.trim();
+        if (trimmed)
+            args.push(trimmed);
+        return args;
+    }
+    /**
+     * Remove surrounding quotes from a string argument.
+     */
+    unquote(s) {
+        s = s.trim();
+        if (s.startsWith('"') && s.endsWith('"')) {
+            return s.slice(1, -1);
+        }
+        return s;
+    }
+    /**
+     * Strip single-line comment (C4-PlantUML uses ' for comments)
+     */
+    stripComment(line) {
+        let inQuote = false;
+        for (let i = 0; i < line.length; i++) {
+            if (line[i] === '"')
+                inQuote = !inQuote;
+            if (line[i] === '\'' && !inQuote) {
+                return line.slice(0, i);
+            }
+        }
+        return line;
+    }
+    /**
+     * Check if a line should be silently skipped (directives, etc.)
+     */
+    isSkippable(line) {
+        return SKIP_PREFIXES.some((p) => line.startsWith(p));
+    }
+}

package/dist/app/editor/c4/render-to-string.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Headless C4 SVG rendering — pure .ts wrapper (no JSX).
+ *
+ * Bridges the React C4Renderer to Node.js contexts (Electron main process)
+ * by using renderToStaticMarkup + createElement instead of JSX.
+ *
+ * Used by the app_render_c4_diagram MCP tool for Confluence publishing.
+ */
+import type { ParseError } from './types.js';
+/**
+ * Parse C4 code and render to SVG string in one call.
+ *
+ * @param code - C4 DSL source code
+ * @param isDarkMode - Whether to render in dark mode
+ * @param manualPositions - Optional manual positions for elements (bypasses dagre auto-layout)
+ * @returns svg string and any parse/validation errors
+ */
+export declare function renderC4DiagramToSVG(code: string, isDarkMode?: boolean, manualPositions?: Record<string, {
+    x: number;
+    y: number;
+}>): {
+    svg: string;
+    errors: ParseError[];
+};

package/dist/app/editor/c4/render-to-string.js

@@ -0,0 +1,34 @@
+/**
+ * Headless C4 SVG rendering — pure .ts wrapper (no JSX).
+ *
+ * Bridges the React C4Renderer to Node.js contexts (Electron main process)
+ * by using renderToStaticMarkup + createElement instead of JSX.
+ *
+ * Used by the app_render_c4_diagram MCP tool for Confluence publishing.
+ */
+import { renderToStaticMarkup } from 'react-dom/server';
+import { createElement } from 'react';
+import { C4Renderer } from './renderer.js';
+import { parseC4, validateC4 } from './parser.js';
+import { layoutC4Diagram } from './layout.js';
+/**
+ * Parse C4 code and render to SVG string in one call.
+ *
+ * @param code - C4 DSL source code
+ * @param isDarkMode - Whether to render in dark mode
+ * @param manualPositions - Optional manual positions for elements (bypasses dagre auto-layout)
+ * @returns svg string and any parse/validation errors
+ */
+export function renderC4DiagramToSVG(code, isDarkMode = false, manualPositions) {
+    const parseResult = parseC4(code);
+    if (parseResult.diagram) {
+        const validationErrors = validateC4(parseResult.diagram);
+        parseResult.errors.push(...validationErrors);
+    }
+    if (!parseResult.diagram || parseResult.errors.length > 0) {
+        return { svg: '', errors: parseResult.errors };
+    }
+    const layout = layoutC4Diagram(parseResult.diagram, undefined, manualPositions);
+    const svg = renderToStaticMarkup(createElement(C4Renderer, { layout, isDarkMode }));
+    return { svg, errors: [] };
+}

package/dist/app/editor/c4/renderer.d.ts

@@ -0,0 +1,64 @@
+/**
+ * C4 SVG Renderer (Canonical)
+ *
+ * Pure React component that renders C4 architecture diagrams as SVG.
+ * This is the single authoritative renderer — used in the editor (via C4Node)
+ * and for headless SVG generation (via renderToStaticMarkup for publishing).
+ *
+ * Features:
+ * - All C4 element types (person, system, container, component)
+ * - All shapes (rectangle, cylinder, queue)
+ * - Boundary nesting with alternating fills
+ * - Edge labels with line clipping, rotation, and multi-line support
+ * - Step number labels (circled) and legend ref labels (squared)
+ * - Smart legend placement for long/parallel labels
+ * - Light and dark theme support
+ */
+import type { LayoutResult } from './types.js';
+/**
+ * Compute legend placement and dimensions for a layout.
+ * Exported for use by C4InteractiveRenderer to create a legend hit area.
+ * Returns null if the layout has no legend entries.
+ */
+export declare function computeLegendInfo(layout: LayoutResult): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+export interface C4RendererProps {
+    /** Layout result from the layout engine */
+    layout: LayoutResult;
+    /** Whether dark mode is enabled */
+    isDarkMode: boolean;
+}
+/**
+ * C4 Diagram SVG Renderer.
+ *
+ * Pure component: takes layout + theme, returns SVG.
+ * Used directly in the editor and via renderToStaticMarkup for publishing.
+ */
+export declare function C4Renderer({ layout, isDarkMode }: C4RendererProps): JSX.Element;
+/**
+ * Renders C4 diagram content (nodes, edges, legend) as SVG group elements.
+ * Exported for use by C4InteractiveRenderer to embed diagram content
+ * inside a custom SVG wrapper without depending on C4Renderer's DOM structure.
+ */
+export interface C4RendererContentProps extends C4RendererProps {
+    /** Override legend position (for manual layout mode) */
+    legendPositionOverride?: {
+        x: number;
+        y: number;
+    } | null;
+}
+export declare function C4RendererContent({ layout, isDarkMode, legendPositionOverride }: C4RendererContentProps): JSX.Element;
+export interface C4ErrorDisplayProps {
+    errors: {
+        message: string;
+        line: number;
+        column: number;
+    }[];
+    isDarkMode: boolean;
+}
+export declare function C4ErrorDisplay({ errors, isDarkMode }: C4ErrorDisplayProps): JSX.Element;
+export default C4Renderer;