@wire-dsl/engine 0.0.3 → 0.2.0

package/dist/index.d.cts

@@ -1,40 +1,182 @@
+/**
+ * SourceMap Types for Wire DSL
+ *
+ * Provides bidirectional mapping between code positions and AST nodes
+ * for features like code-canvas selection, visual editing, and error reporting.
+ */
+
+/**
+ * Position in source code (1-based line, 0-based column)
+ */
+interface Position {
+    line: number;
+    column: number;
+    offset?: number;
+}
+/**
+ * Range in source code
+ */
+interface CodeRange {
+    start: Position;
+    end: Position;
+}
+/**
+ * SourceMap for a single property
+ * Captures ranges for precise property editing
+ */
+interface PropertySourceMap {
+    name: string;
+    value: any;
+    range: CodeRange;
+    nameRange: CodeRange;
+    valueRange: CodeRange;
+}
+/**
+ * Types of nodes in Wire DSL
+ */
+type SourceMapNodeType = 'project' | 'screen' | 'layout' | 'component' | 'component-definition' | 'cell' | 'style' | 'mocks' | 'colors';
+/**
+ * Main SourceMap entry - represents one node in the AST
+ */
+interface SourceMapEntry {
+    nodeId: string;
+    type: SourceMapNodeType;
+    range: CodeRange;
+    filePath: string;
+    parentId: string | null;
+    name?: string;
+    layoutType?: string;
+    componentType?: string;
+    indexInParent?: number;
+    isUserDefined?: boolean;
+    keywordRange?: CodeRange;
+    nameRange?: CodeRange;
+    bodyRange?: CodeRange;
+    properties?: Record<string, PropertySourceMap>;
+    insertionPoint?: InsertionPoint;
+}
+/**
+ * Insertion point for new children (FASE 3)
+ */
+interface InsertionPoint {
+    line: number;
+    column: number;
+    indentation: string;
+    after?: string;
+}
+/**
+ * Parse result with SourceMap
+ */
+interface ParseResult {
+    ast: AST;
+    sourceMap: SourceMapEntry[];
+    errors: ParseError[];
+}
+/**
+ * Parse error with optional nodeId reference
+ */
+interface ParseError {
+    message: string;
+    range: CodeRange;
+    severity: 'error' | 'warning';
+    nodeId?: string;
+}
+/**
+ * Captured tokens from Chevrotain parser (internal use)
+ * These are NOT stored in AST, only used temporarily during SourceMap building
+ */
+interface CapturedTokens {
+    keyword?: any;
+    name?: any;
+    paramList?: any;
+    properties?: any[];
+    body?: any;
+    children?: any[];
+}
+
 interface AST {
     type: 'project';
     name: string;
-    theme: Record<string, string>;
+    style: Record<string, string>;
     mocks: Record<string, string>;
     colors: Record<string, string>;
     definedComponents: ASTDefinedComponent[];
     screens: ASTScreen[];
+    _meta?: {
+        nodeId: string;
+    };
 }
 interface ASTDefinedComponent {
     type: 'definedComponent';
     name: string;
     body: ASTLayout | ASTComponent;
+    _meta?: {
+        nodeId: string;
+    };
 }
 interface ASTScreen {
     type: 'screen';
     name: string;
     params: Record<string, string | number>;
     layout: ASTLayout;
+    _meta?: {
+        nodeId: string;
+    };
 }
 interface ASTLayout {
     type: 'layout';
     layoutType: string;
     params: Record<string, string | number>;
     children: (ASTComponent | ASTLayout | ASTCell)[];
+    _meta?: {
+        nodeId: string;
+    };
 }
 interface ASTCell {
     type: 'cell';
     props: Record<string, string | number>;
     children: (ASTComponent | ASTLayout)[];
+    _meta?: {
+        nodeId: string;
+    };
 }
 interface ASTComponent {
     type: 'component';
     componentType: string;
     props: Record<string, string | number>;
+    _meta?: {
+        nodeId: string;
+    };
 }
 declare function parseWireDSL(input: string): AST;
+/**
+ * Parse Wire DSL with SourceMap generation
+ *
+ * Returns both AST and SourceMap for bidirectional code-canvas mapping
+ * Useful for:
+ * - Visual editors (Wire Studio)
+ * - Code navigation (click canvas → jump to code)
+ * - Error reporting with precise locations
+ * - Component inspection and manipulation
+ *
+ * @param input - Wire DSL source code
+ * @param filePath - Optional file path (default: "<input>") - used for stable nodeIds
+ * @returns ParseResult with AST, SourceMap, and errors
+ *
+ * @example
+ * ```typescript
+ * const { ast, sourceMap } = parseWireDSLWithSourceMap(code, 'screens/Main.wire');
+ *
+ * // Find node by position
+ * const node = sourceMap.find(e =>
+ *   e.range.start.line === 5 && e.range.start.column === 4
+ * );
+ *
+ * // Access AST node
+ * console.log(node.astNode.type);  // 'component'
+ * ```
+ */
+declare function parseWireDSLWithSourceMap(input: string, filePath?: string): ParseResult;
 interface ParsedWireframe {
     name: string;
     components: ParsedComponent[];
@@ -61,19 +203,21 @@ interface IRContract {
 interface IRProject {
     id: string;
     name: string;
-    theme: IRTheme;
+    style: IRStyle;
     mocks: Record<string, unknown>;
     colors: Record<string, string>;
     screens: IRScreen[];
     nodes: Record<string, IRNode>;
 }
-interface IRTheme {
+interface IRStyle {
     density: 'compact' | 'normal' | 'comfortable';
     spacing: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
     radius: 'none' | 'sm' | 'md' | 'lg' | 'full';
     stroke: 'thin' | 'normal' | 'thick';
     font: 'sm' | 'base' | 'lg';
     background?: string;
+    theme?: string;
+    device?: string;
 }
 interface IRScreen {
     id: string;
@@ -96,7 +240,7 @@ interface IRContainerNode {
     children: Array<{
         ref: string;
     }>;
-    style: IRStyle;
+    style: IRNodeStyle;
     meta: IRMeta;
 }
 interface IRComponentNode {
@@ -104,10 +248,10 @@ interface IRComponentNode {
     kind: 'component';
     componentType: string;
     props: Record<string, string | number>;
-    style: IRStyle;
+    style: IRNodeStyle;
     meta: IRMeta;
 }
-interface IRStyle {
+interface IRNodeStyle {
     padding?: string;
     gap?: string;
     align?: 'left' | 'center' | 'right' | 'justify';
@@ -116,6 +260,7 @@ interface IRStyle {
 }
 interface IRMeta {
     source?: string;
+    nodeId?: string;
 }
 declare class IRGenerator {
     private idGen;
@@ -124,9 +269,9 @@ declare class IRGenerator {
     private definedComponentIndices;
     private undefinedComponentsUsed;
     private warnings;
-    private theme;
+    private style;
     generate(ast: AST): IRContract;
-    private applyTheme;
+    private applyStyle;
     private convertScreen;
     /**
      * Validates that component definitions appear before their first usage
@@ -179,6 +324,44 @@ interface IRMetadata {
     description?: string;
 }
 
+/**
+ * Device viewport presets for multi-device wireframe rendering
+ *
+ * Defines standard viewport widths and minimum heights for different device
+ * categories. Final render height remains dynamic and grows with content.
+ */
+interface DevicePreset {
+    name: string;
+    width: number;
+    minHeight: number;
+    category: 'mobile' | 'desktop' | 'tablet' | 'print';
+    description: string;
+}
+/**
+ * Standard device viewport presets
+ *
+ * `minHeight` is used as the baseline viewport height. Renderers still
+ * expand dynamically when content exceeds this value.
+ */
+declare const DEVICE_PRESETS: Record<string, DevicePreset>;
+/**
+ * Resolve device preset name to viewport dimensions
+ *
+ * @param device - Device preset name (case-insensitive)
+ * @returns Viewport width and minimum height in pixels
+ */
+declare function resolveDevicePreset(device: string): {
+    width: number;
+    minHeight: number;
+};
+/**
+ * Check if a device preset name is valid
+ *
+ * @param device - Device preset name to validate
+ * @returns True if device preset exists
+ */
+declare function isValidDevice(device: string): boolean;
+
 /**
  * Layout Engine
  *
@@ -196,7 +379,7 @@ interface LayoutResult {
 }
 declare class LayoutEngine {
     private nodes;
-    private theme;
+    private style;
     private result;
     private viewport;
     private ir;
@@ -213,16 +396,119 @@ declare class LayoutEngine {
     private calculateCard;
     private calculateComponent;
     private resolveSpacing;
+    private getSeparateSize;
     private getComponentHeight;
+    private getTextMetricsForDensity;
+    private getButtonMetricsForDensity;
+    private getHeadingMetricsForDensity;
+    private wrapTextToLines;
     private getIntrinsicComponentHeight;
+    private getControlLabelOffset;
     private getIntrinsicComponentWidth;
     private calculateChildHeight;
     private calculateChildWidth;
+    private estimateTextWidth;
     private adjustNodeYPositions;
 }
 declare function calculateLayout(ir: IRContract): LayoutResult;
 declare function resolveGridPosition(row: number, col: number, rowSpan?: number, colSpan?: number, gridWidth?: number, gridHeight?: number, gridCols?: number, gridRows?: number): LayoutPosition;
 
+/**
+ * Color Resolver
+ *
+ * Resolves color references from project colors, named colors, or hex values
+ */
+declare class ColorResolver {
+    private customColors;
+    private namedColors;
+    /**
+     * Set custom colors from project definition
+     */
+    setCustomColors(colors: Record<string, string>): void;
+    /**
+     * Check if a color key/reference is resolvable.
+     */
+    hasColor(colorRef: string): boolean;
+    /**
+     * Resolve a color reference to a hex value
+     * Priority: custom colors > named colors > hex validation > default
+     */
+    resolveColor(colorRef: string, defaultColor?: string): string;
+    private resolveColorInternal;
+    /**
+     * Validate hex color (6-character hex code)
+     */
+    private isValidHex;
+    /**
+     * Validate and return hex, or undefined if invalid
+     */
+    private validateHex;
+}
+
+/**
+ * Design Tokens System
+ *
+ * Visual properties organized by density levels.
+ * These tokens are read from ir.project.style (density, spacing, radius, stroke, font)
+ * and used by all renderers to maintain consistent visual styling.
+ */
+interface DesignTokens {
+    spacing: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    };
+    button: {
+        paddingX: number;
+        paddingY: number;
+        radius: number;
+        fontSize: number;
+        fontWeight: number;
+    };
+    input: {
+        paddingX: number;
+        paddingY: number;
+        radius: number;
+        fontSize: number;
+    };
+    card: {
+        padding: number;
+        radius: number;
+        strokeWidth: number;
+    };
+    heading: {
+        fontSize: number;
+        fontWeight: number;
+        marginBottom: number;
+    };
+    text: {
+        fontSize: number;
+        lineHeight: number;
+    };
+    badge: {
+        paddingX: number;
+        paddingY: number;
+        radius: number | 'pill';
+        fontSize: number;
+    };
+    table: {
+        cellPaddingX: number;
+        cellPaddingY: number;
+        headerFontWeight: number;
+        borderWidth: number;
+    };
+}
+/**
+ * Token sets for each density level
+ */
+declare const DENSITY_TOKENS: Record<'compact' | 'normal' | 'comfortable', DesignTokens>;
+/**
+ * Resolve design tokens based on IRStyle
+ */
+declare function resolveTokens(style: any): DesignTokens;
+
 /**
  * SVG Renderer
  *
@@ -241,14 +527,40 @@ interface SVGComponent {
     children?: SVGComponent[];
     text?: string;
 }
+declare const THEMES: {
+    light: {
+        bg: string;
+        cardBg: string;
+        border: string;
+        text: string;
+        textMuted: string;
+        primary: string;
+        primaryHover: string;
+        primaryLight: string;
+    };
+    dark: {
+        bg: string;
+        cardBg: string;
+        border: string;
+        text: string;
+        textMuted: string;
+        primary: string;
+        primaryHover: string;
+        primaryLight: string;
+    };
+};
 declare class SVGRenderer {
     private ir;
     private layout;
-    private options;
-    private renderTheme;
+    protected options: Required<Omit<SVGRenderOptions, 'screenName'>> & {
+        screenName?: string;
+    };
+    protected renderTheme: typeof THEMES.light;
+    protected tokens: DesignTokens;
     private selectedScreenName?;
-    private renderedNodeIds;
-    private colorResolver;
+    protected renderedNodeIds: Set<string>;
+    protected colorResolver: ColorResolver;
+    protected fontFamily: string;
     constructor(ir: IRContract, layout: LayoutResult, options?: SVGRenderOptions);
     /**
      * Get list of available screens in the project
@@ -260,53 +572,715 @@ declare class SVGRenderer {
     /**
      * Get the currently selected or first screen
      */
-    private getSelectedScreen;
+    protected getSelectedScreen(): {
+        screen: any;
+        name: string;
+    };
     render(): string;
-    private calculateContentHeight;
-    private renderNode;
-    private renderComponent;
-    private renderHeading;
-    private renderButton;
-    private renderInput;
-    private renderTopbar;
-    private renderPanelBorder;
-    private renderCardBorder;
-    private renderTable;
-    private renderChartPlaceholder;
-    private renderText;
-    private renderLabel;
-    private renderCode;
-    private renderTextarea;
-    private renderSelect;
-    private renderCheckbox;
-    private renderRadio;
-    private renderToggle;
-    private renderSidebar;
-    private renderTabs;
-    private renderDivider;
-    private renderAlert;
-    private renderBadge;
-    private renderModal;
-    private renderList;
-    private renderGenericComponent;
-    private renderStatCard;
-    private renderImage;
-    private renderBreadcrumbs;
-    private renderSidebarMenu;
-    private renderIcon;
-    private renderIconButton;
+    protected calculateContentHeight(): number;
+    protected renderNode(nodeId: string, output: string[]): void;
+    protected renderComponent(node: IRComponentNode, pos: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): string;
+    protected renderHeading(node: IRComponentNode, pos: any): string;
+    protected renderButton(node: IRComponentNode, pos: any): string;
+    protected renderLink(node: IRComponentNode, pos: any): string;
+    protected renderInput(node: IRComponentNode, pos: any): string;
+    protected renderTopbar(node: IRComponentNode, pos: any): string;
+    protected renderPanelBorder(node: IRNode, pos: any, output: string[]): void;
+    protected renderCardBorder(node: IRNode, pos: any, output: string[]): void;
+    protected renderTable(node: IRComponentNode, pos: any): string;
+    protected renderChartPlaceholder(node: IRComponentNode, pos: any): string;
+    protected renderText(node: IRComponentNode, pos: any): string;
+    protected renderLabel(node: IRComponentNode, pos: any): string;
+    protected renderCode(node: IRComponentNode, pos: any): string;
+    protected renderTextarea(node: IRComponentNode, pos: any): string;
+    protected renderSelect(node: IRComponentNode, pos: any): string;
+    protected renderCheckbox(node: IRComponentNode, pos: any): string;
+    protected renderRadio(node: IRComponentNode, pos: any): string;
+    protected renderToggle(node: IRComponentNode, pos: any): string;
+    protected renderSidebar(node: IRComponentNode, pos: any): string;
+    protected renderTabs(node: IRComponentNode, pos: any): string;
+    protected renderDivider(node: IRComponentNode, pos: any): string;
+    protected renderSeparate(node: IRComponentNode, _pos: any): string;
+    protected renderAlert(node: IRComponentNode, pos: any): string;
+    protected renderBadge(node: IRComponentNode, pos: any): string;
+    protected renderModal(node: IRComponentNode, pos: any): string;
+    protected renderList(node: IRComponentNode, pos: any): string;
+    protected renderGenericComponent(node: IRComponentNode, pos: any): string;
+    protected renderStatCard(node: IRComponentNode, pos: any): string;
+    protected renderImage(node: IRComponentNode, pos: any): string;
+    protected renderBreadcrumbs(node: IRComponentNode, pos: any): string;
+    protected renderSidebarMenu(node: IRComponentNode, pos: any): string;
+    protected renderIcon(node: IRComponentNode, pos: any): string;
+    protected renderIconButton(node: IRComponentNode, pos: any): string;
     /**
      * Extract SVG path/element content from a full SVG string
      * Removes the outer <svg> tag but keeps the content
      */
-    private extractSvgContent;
-    private resolveSpacing;
-    private escapeXml;
+    protected extractSvgContent(svgString: string): string;
+    protected resolveVariantColor(variant: string, fallback: string): string;
+    protected resolveAccentColor(): string;
+    protected resolveControlColor(): string;
+    protected resolveChartColor(): string;
+    protected getSemanticVariantColor(variant: string): string | undefined;
+    protected hexToRgba(hex: string, alpha: number): string;
+    protected getIconSize(size?: string): number;
+    protected getIconButtonSize(size?: string): number;
+    protected resolveSpacing(spacing?: string): number;
+    protected wrapTextToLines(text: string, maxWidth: number, fontSize: number): string[];
+    protected clampControlWidth(idealWidth: number, availableWidth: number): number;
+    protected truncateTextToWidth(text: string, maxWidth: number, fontSize: number): string;
+    protected estimateTextWidth(text: string, fontSize: number): number;
+    protected generateUpwardTrendValues(count: number, start: number, end: number): number[];
+    protected getControlLabelOffset(label: string): number;
+    protected getControlLabelBaselineY(y: number): number;
+    protected getHeadingTypography(node: IRComponentNode): {
+        fontSize: number;
+        fontWeight: number;
+        lineHeight: number;
+    };
+    protected getHeadingFirstLineY(node: IRComponentNode, pos: {
+        y: number;
+        height: number;
+    }, fontSize: number, lineHeightPx: number, lineCount: number): number;
+    protected calculateTopbarLayout(node: IRComponentNode, pos: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, title: string, subtitle: string, actions: string, user: string): {
+        hasSubtitle: boolean;
+        titleY: number;
+        subtitleY: number;
+        textX: number;
+        titleMaxWidth: number;
+        visibleTitle: string;
+        visibleSubtitle: string;
+        leftIcon: null | {
+            badgeX: number;
+            badgeY: number;
+            badgeSize: number;
+            badgeRadius: number;
+            iconX: number;
+            iconY: number;
+            iconSize: number;
+            iconSvg: string;
+        };
+        actions: Array<{
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+            label: string;
+        }>;
+        userBadge: null | {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+            label: string;
+        };
+        avatar: null | {
+            cx: number;
+            cy: number;
+            r: number;
+        };
+    };
+    protected parseBooleanProp(value: unknown, fallback?: boolean): boolean;
+    protected escapeXml(text: string): string;
+    /**
+     * Get data-node-id attribute string for SVG elements
+     * Enables bidirectional selection between code and canvas
+     */
+    protected getDataNodeId(node: IRComponentNode | IRContainerNode): string;
 }
 declare function renderToSVG(ir: IRContract, layout: LayoutResult, options?: SVGRenderOptions): string;
 declare function createSVGElement(tag: string, attrs: Record<string, string | number>, children?: string[]): string;
 declare function buildSVG(component: SVGComponent): string;
 
+/**
+ * Skeleton SVG Renderer
+ *
+ * Renders wireframes in a skeleton/loading state style:
+ * - Text/Heading: Gray rectangular blocks instead of text
+ * - Buttons: Shape outline only (no text, no fill)
+ * - Icons: Hidden completely
+ * - All text content: Gray blocks instead of actual text
+ *
+ * Used for:
+ * - Loading states
+ * - Content placeholders
+ * - Wireframe presentations without actual content
+ */
+
+declare class SkeletonSVGRenderer extends SVGRenderer {
+    /**
+     * Render button with same appearance as standard but without text
+     */
+    protected renderButton(node: IRComponentNode, pos: any): string;
+    /**
+     * Render link as placeholder block + underline (no text)
+     */
+    protected renderLink(node: IRComponentNode, pos: any): string;
+    /**
+     * Render heading as gray block
+     */
+    protected renderHeading(node: IRComponentNode, pos: any): string;
+    /**
+     * Render text as gray block
+     */
+    protected renderText(node: IRComponentNode, pos: any): string;
+    /**
+     * Render label as gray block
+     */
+    protected renderLabel(node: IRComponentNode, pos: any): string;
+    /**
+     * Render badge as shape only (no text)
+     */
+    protected renderBadge(node: IRComponentNode, pos: any): string;
+    /**
+     * Render alert as shape with gray block instead of message
+     */
+    protected renderAlert(node: IRComponentNode, pos: any): string;
+    /**
+     * Render input with gray block for placeholder text
+     */
+    protected renderInput(node: IRComponentNode, pos: any): string;
+    /**
+     * Render textarea with gray block for placeholder text
+     */
+    protected renderTextarea(node: IRComponentNode, pos: any): string;
+    /**
+     * Render select as shape only (no placeholder text)
+     */
+    protected renderSelect(node: IRComponentNode, pos: any): string;
+    /**
+     * Render checkbox as shape only (no label text)
+     */
+    protected renderCheckbox(node: IRComponentNode, pos: any): string;
+    /**
+     * Render radio as shape only (no label text)
+     */
+    protected renderRadio(node: IRComponentNode, pos: any): string;
+    /**
+     * Render toggle as shape only (no label text)
+     */
+    protected renderToggle(node: IRComponentNode, pos: any): string;
+    /**
+     * Render code as shape with gray block instead of code text
+     */
+    protected renderCode(node: IRComponentNode, pos: any): string;
+    /**
+     * Render table with gray blocks instead of text
+     */
+    protected renderTable(node: IRComponentNode, pos: any): string;
+    /**
+     * Render topbar with gray blocks instead of text
+     */
+    protected renderTopbar(node: IRComponentNode, pos: any): string;
+    /**
+     * Render StatCard with gray blocks instead of values
+     */
+    protected renderStatCard(node: IRComponentNode, pos: any): string;
+    /**
+     * Render icon as gray square instead of hiding it
+     */
+    protected renderIcon(node: IRComponentNode, pos: any): string;
+    /**
+     * Render IconButton with same appearance as standard but without icon
+     */
+    protected renderIconButton(node: IRComponentNode, pos: any): string;
+    /**
+     * Render Sidebar with gray blocks instead of text
+     */
+    protected renderSidebar(node: IRComponentNode, pos: any): string;
+    /**
+     * Render SidebarMenu with gray blocks instead of text and no icons
+     */
+    protected renderSidebarMenu(node: IRComponentNode, pos: any): string;
+    /**
+     * Private helper: Render text as gray block
+     */
+    private renderTextBlock;
+    private renderWrappedLineBlocks;
+}
+
+/**
+ * Sketch SVG Renderer
+ *
+ * Renders wireframes in a hand-drawn/sketch style:
+ * - Thicker borders with sketch appearance
+ * - For variant elements (Button, Badge): colored border instead of fill
+ * - Keeps text and icons visible
+ * - Traditional wireframe look
+ *
+ * Used for:
+ * - Low-fidelity wireframes
+ * - Traditional hand-drawn wireframe presentations
+ * - Early design mockups
+ */
+
+declare class SketchSVGRenderer extends SVGRenderer {
+    /**
+     * Override render to add sketch filter definitions
+     */
+    render(): string;
+    /**
+     * Render button with colored border instead of fill
+     */
+    protected renderButton(node: IRComponentNode, pos: any): string;
+    /**
+     * Render badge with colored border instead of fill
+     */
+    protected renderBadge(node: IRComponentNode, pos: any): string;
+    /**
+     * Render IconButton with colored border instead of fill
+     */
+    protected renderIconButton(node: IRComponentNode, pos: any): string;
+    /**
+     * Render alert with colored border
+     */
+    protected renderAlert(node: IRComponentNode, pos: any): string;
+    /**
+     * Render input with thicker border
+     */
+    protected renderInput(node: IRComponentNode, pos: any): string;
+    /**
+     * Render textarea with thicker border
+     */
+    protected renderTextarea(node: IRComponentNode, pos: any): string;
+    /**
+     * Render card with thicker border and sketch filter
+     */
+    protected renderCard(node: IRComponentNode, pos: any): string;
+    /**
+     * Render panel with thicker border and sketch filter
+     */
+    protected renderPanel(node: IRComponentNode, pos: any): string;
+    /**
+     * Render heading with sketch filter and Comic Sans
+     */
+    protected renderHeading(node: IRComponentNode, pos: any): string;
+    /**
+     * Render topbar with sketch filter and Comic Sans
+     */
+    protected renderTopbar(node: IRComponentNode, pos: any): string;
+    /**
+     * Render table with sketch filter and Comic Sans
+     */
+    protected renderTable(node: IRComponentNode, pos: any): string;
+    /**
+     * Render text with Comic Sans
+     */
+    protected renderText(node: IRComponentNode, pos: any): string;
+    /**
+     * Render label with Comic Sans
+     */
+    protected renderLabel(node: IRComponentNode, pos: any): string;
+    /**
+     * Render code with sketch filter and Comic Sans
+     */
+    protected renderCode(node: IRComponentNode, pos: any): string;
+    /**
+     * Render select with sketch filter and Comic Sans
+     */
+    protected renderSelect(node: IRComponentNode, pos: any): string;
+    /**
+     * Render checkbox with sketch filter and Comic Sans
+     */
+    protected renderCheckbox(node: IRComponentNode, pos: any): string;
+    /**
+     * Render radio with sketch filter and Comic Sans
+     */
+    protected renderRadio(node: IRComponentNode, pos: any): string;
+    /**
+     * Render toggle with sketch filter and Comic Sans
+     */
+    protected renderToggle(node: IRComponentNode, pos: any): string;
+    /**
+     * Render sidebar with sketch filter and Comic Sans
+     */
+    protected renderSidebar(node: IRComponentNode, pos: any): string;
+    /**
+     * Render tabs with sketch filter and Comic Sans
+     */
+    protected renderTabs(node: IRComponentNode, pos: any): string;
+    /**
+     * Render divider with sketch filter
+     */
+    protected renderDivider(node: IRComponentNode, pos: any): string;
+    /**
+     * Render modal with sketch filter and Comic Sans
+     */
+    protected renderModal(node: IRComponentNode, pos: any): string;
+    /**
+     * Render list with sketch filter and Comic Sans
+     */
+    protected renderList(node: IRComponentNode, pos: any): string;
+    /**
+     * Render generic component with sketch filter and Comic Sans
+     */
+    protected renderGenericComponent(node: IRComponentNode, pos: any): string;
+    /**
+     * Render stat card with sketch filter and Comic Sans
+     */
+    protected renderStatCard(node: IRComponentNode, pos: any): string;
+    /**
+     * Render image with sketch filter
+     */
+    protected renderImage(node: IRComponentNode, pos: any): string;
+    /**
+     * Render breadcrumbs with Comic Sans
+     */
+    protected renderBreadcrumbs(node: IRComponentNode, pos: any): string;
+    /**
+     * Render sidebar menu with sketch filter and Comic Sans
+     */
+    protected renderSidebarMenu(node: IRComponentNode, pos: any): string;
+    /**
+     * Render icon (same as base, icons don't need filter)
+     */
+    protected renderIcon(node: IRComponentNode, pos: any): string;
+    /**
+     * Render chart placeholder with sketch filter and Comic Sans
+     */
+    protected renderChartPlaceholder(node: IRComponentNode, pos: any): string;
+    /**
+     * Helper method to get icon SVG
+     */
+    private getIconSvg;
+}
+
+/**
+ * Content-based hash generation for stable NodeIds
+ *
+ * Browser-safe implementation (no crypto/node dependencies)
+ * Generates stable IDs that persist across parses if code hasn't changed
+ *
+ * **Uniqueness Strategy:**
+ * Includes `indexInParent` in the hash to ensure identical components
+ * in the same parent get unique IDs. This prevents nodeId collisions for:
+ *
+ * ```wire
+ * layout stack {
+ *   component Button text: "Click"  // index 0
+ *   component Button text: "Click"  // index 1
+ *   component Button text: "Click"  // index 2
+ * }
+ * ```
+ *
+ * Each button will have a different nodeId despite being identical.
+ */
+
+/**
+ * Generate a stable, content-based node ID
+ *
+ * The ID is based on:
+ * - File path (distinguishes nodes across files)
+ * - Line and column (unique position in file)
+ * - Node type (component, layout, screen, etc.)
+ * - Index in parent array (distinguishes identical siblings)
+ * - Optional name (for named nodes like screens, defined components)
+ *
+ * Examples:
+ * - "node-k7m2p9-component" (Icon component at Main.wire:5:4, index 0)
+ * - "node-abc123-screen"    (Main screen at Main.wire:2:0, index 0)
+ * - "node-xyz789-layout"    (stack layout at Main.wire:3:2, index 0)
+ *
+ * @param type - Type of AST node
+ * @param filePath - Source file path
+ * @param line - Line number (1-based)
+ * @param column - Column number (0-based)
+ * @param indexInParent - Index in parent's child array (0-based)
+ * @param name - Optional name (for screens, defined components)
+ * @returns Stable node ID
+ */
+declare function generateStableNodeId(type: SourceMapNodeType, filePath: string, line: number, column: number, indexInParent: number, name?: string): string;
+/**
+ * Validate if a string looks like a valid node ID
+ *
+ * @param id - String to validate
+ * @returns true if it matches the node ID pattern
+ */
+declare function isValidNodeId(id: string): boolean;
+/**
+ * Extract node type from a node ID
+ *
+ * @param nodeId - Node ID to parse
+ * @returns The node type, or null if invalid
+ */
+declare function getTypeFromNodeId(nodeId: string): SourceMapNodeType | null;
+
+/**
+ * SourceMapBuilder
+ *
+ * Constructs SourceMap during AST traversal using semantic node IDs.
+ *
+ * **ID Strategy:**
+ * - Uses human-readable, semantic IDs: `{type}-{subtype}-{counter}`
+ * - Counter is per type-subtype to keep indices small
+ * - Examples: `component-button-0`, `layout-stack-1`, `screen-0`
+ *
+ * **Stability:**
+ * - IDs remain stable when editing properties ✅
+ * - IDs change when reordering nodes ⚠️
+ * - Ideal for editor UX where property editing is frequent
+ *
+ * **Generated IDs:**
+ * - `project` - Single project (no counter)
+ * - `screen-{n}` - Screens by index (0-based)
+ * - `component-{type}-{n}` - Components by subtype (button-0, input-0, etc.)
+ * - `layout-{type}-{n}` - Layouts by subtype (stack-0, grid-1, etc.)
+ * - `cell-{n}` - Grid cells by index
+ * - `define-{name}` - Component definitions by name
+ */
+
+/**
+ * Builder for constructing SourceMap entries during parsing
+ * Uses semantic IDs based on type-subtype-counter (e.g., component-button-0)
+ */
+declare class SourceMapBuilder {
+    private entries;
+    private filePath;
+    private sourceCode;
+    private parentStack;
+    private counters;
+    constructor(filePath?: string, sourceCode?: string);
+    /**
+     * Add a node to the SourceMap
+     * Generates semantic IDs like: project, screen-0, component-button-1, layout-stack-0
+     *
+     * @param type - Type of AST node
+     * @param tokens - Captured tokens from parser
+     * @param metadata - Optional metadata (name, layoutType, componentType)
+     * @returns Generated nodeId
+     */
+    addNode(type: SourceMapNodeType, tokens: CapturedTokens, metadata?: {
+        name?: string;
+        layoutType?: string;
+        componentType?: string;
+        isUserDefined?: boolean;
+    }): string;
+    /**
+     * Generate semantic node ID based on type and subtype
+     * Format: {type}-{subtype}-{counter} or {type}-{counter}
+     *
+     * Examples:
+     * - project → "project"
+     * - theme → "theme"
+     * - mocks → "mocks"
+     * - colors → "colors"
+     * - screen → "screen-0", "screen-1"
+     * - component Button → "component-button-0", "component-button-1"
+     * - layout stack → "layout-stack-0", "layout-stack-1"
+     * - cell → "cell-0", "cell-1"
+     * - component-definition → "define-MyButton"
+     */
+    private generateNodeId;
+    /**
+     * Add a property to an existing node in the SourceMap
+     * Captures precise ranges for property name and value for surgical editing
+     *
+     * @param nodeId - ID of the node that owns this property
+     * @param propertyName - Name of the property (e.g., "text", "direction")
+     * @param propertyValue - Parsed value of the property
+     * @param tokens - Captured tokens for the property
+     * @returns The PropertySourceMap entry created
+     */
+    addProperty(nodeId: string, propertyName: string, propertyValue: any, tokens: {
+        name?: any;
+        value?: any;
+        separator?: any;
+        full?: any;
+    }): PropertySourceMap;
+    /**
+     * Push a parent onto the stack (when entering a container node)
+     */
+    pushParent(nodeId: string): void;
+    /**
+     * Pop a parent from the stack (when exiting a container node)
+     */
+    popParent(): void;
+    /**
+     * Get the current parent nodeId (or null if at root)
+     */
+    getCurrentParent(): string | null;
+    /**
+     * Build and return the final SourceMap
+     */
+    build(): SourceMapEntry[];
+    /**
+     * Calculate insertionPoints for all container nodes
+     * Container nodes: project, screen, layout, cell, component-definition
+     */
+    private calculateAllInsertionPoints;
+    /**
+     * Calculate CodeRange from captured tokens
+     * Finds the earliest start and latest end among all tokens
+     */
+    private calculateRange;
+    /**
+     * Convert a single token to CodeRange
+     */
+    private tokenToRange;
+    /**
+     * Calculate body range from closing brace token
+     * Body range typically spans from opening brace to closing brace
+     */
+    private calculateBodyRange;
+    /**
+     * Extract the first real token from a CST node (earliest by offset)
+     * Recursively searches through children to find the token with smallest offset
+     */
+    private getFirstToken;
+    /**
+     * Extract the last real token from a CST node (latest by offset)
+     * Recursively searches through children to find the token with largest offset
+     */
+    private getLastToken;
+    /**
+     * Extract start position from a Chevrotain token or CST node
+     */
+    private getTokenStart;
+    /**
+     * Extract end position from a Chevrotain token or CST node
+     */
+    private getTokenEnd;
+    /**
+     * Reset the builder (for reuse)
+     */
+    reset(filePath?: string, sourceCode?: string): void;
+    /**
+     * Calculate insertion point for adding new children to a container node
+     *
+     * Strategy:
+     * - If node has children: insert after last child, preserve indentation
+     * - If node is empty: insert inside body, use parent indentation + 2 spaces
+     *
+     * @param nodeId - ID of the container node
+     * @returns InsertionPoint with line, column, indentation, and optional after
+     */
+    calculateInsertionPoint(nodeId: string): {
+        line: number;
+        column: number;
+        indentation: string;
+        after?: string;
+    } | undefined;
+    /**
+     * Extract indentation (leading whitespace) from a line
+     */
+    private extractIndentation;
+}
+
+/**
+ * SourceMapResolver
+ *
+ * Provides query APIs for bidirectional code↔canvas selection
+ *
+ * **Use Cases:**
+ * 1. Canvas → Code: Click SVG element with data-node-id → find code location
+ * 2. Code → Canvas: Click code position → find corresponding node
+ *
+ * **Performance:**
+ * - getNodeById: O(1) with Map index
+ * - getNodeByPosition: O(n) linear search (could be optimized with interval tree)
+ * - getChildren/getParent: O(1) with indexes
+ */
+
+/**
+ * Query result for position-based lookups
+ */
+interface PositionQueryResult extends SourceMapEntry {
+    depth: number;
+}
+/**
+ * SourceMap query and navigation API
+ */
+declare class SourceMapResolver {
+    private nodeMap;
+    private childrenMap;
+    private positionIndex;
+    constructor(sourceMap: SourceMapEntry[]);
+    /**
+     * Find node by ID (Canvas → Code)
+     *
+     * @example
+     * // User clicks SVG element with data-node-id="component-button-0"
+     * const node = resolver.getNodeById("component-button-0");
+     * editor.revealRange(node.range); // Jump to code
+     */
+    getNodeById(nodeId: string): SourceMapEntry | null;
+    /**
+     * Find node at position (Code → Canvas)
+     * Returns the most specific (deepest) node containing the position
+     *
+     * @example
+     * // User clicks code at line 5, column 10
+     * const node = resolver.getNodeByPosition(5, 10);
+     * canvas.highlightElement(node.nodeId); // Highlight in canvas
+     */
+    getNodeByPosition(line: number, column: number): SourceMapEntry | null;
+    /**
+     * Get all child nodes of a parent
+     *
+     * @example
+     * const children = resolver.getChildren("layout-stack-0");
+     * // Returns: [component-button-0, component-input-0, ...]
+     */
+    getChildren(nodeId: string): SourceMapEntry[];
+    /**
+     * Get parent node
+     *
+     * @example
+     * const parent = resolver.getParent("component-button-0");
+     * // Returns: layout-stack-0
+     */
+    getParent(nodeId: string): SourceMapEntry | null;
+    /**
+     * Get all nodes in the SourceMap
+     */
+    getAllNodes(): SourceMapEntry[];
+    /**
+     * Get all nodes of a specific type
+     *
+     * @example
+     * const buttons = resolver.getNodesByType("component", "Button");
+     */
+    getNodesByType(type: SourceMapEntry['type'], subtype?: string): SourceMapEntry[];
+    /**
+     * Get siblings of a node (nodes with same parent)
+     */
+    getSiblings(nodeId: string): SourceMapEntry[];
+    /**
+     * Get path from root to node (breadcrumb)
+     *
+     * @example
+     * const path = resolver.getPath("component-button-0");
+     * // Returns: [project, screen-0, layout-stack-0, component-button-0]
+     */
+    getPath(nodeId: string): SourceMapEntry[];
+    /**
+     * Check if a position is within a node's range
+     */
+    private containsPosition;
+    /**
+     * Calculate depth of a node in the tree (0 = root)
+     */
+    private calculateDepth;
+    /**
+     * Get statistics about the SourceMap
+     */
+    getStats(): {
+        totalNodes: number;
+        byType: Record<string, number>;
+        maxDepth: number;
+    };
+}
+
 declare const version = "0.0.1";
 
-export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTLayout, type ASTScreen, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRProject, type IRScreen, type IRStyle, type IRTheme, type IRWireframe, LayoutEngine, type LayoutPosition, type LayoutResult, type ParsedComponent, type ParsedWireframe, type SVGComponent, type SVGRenderOptions, SVGRenderer, buildSVG, calculateLayout, createSVGElement, generateIR, parseWireDSL, renderToSVG, resolveGridPosition, version };
+export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTLayout, type ASTScreen, type CapturedTokens, type CodeRange, DENSITY_TOKENS, DEVICE_PRESETS, type DesignTokens, type DevicePreset, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRNodeStyle, type IRProject, type IRScreen, type IRStyle, type IRWireframe, type InsertionPoint, LayoutEngine, type LayoutPosition, type LayoutResult, type ParseError, type ParseResult, type ParsedComponent, type ParsedWireframe, type Position, type PositionQueryResult, type PropertySourceMap, type SVGComponent, type SVGRenderOptions, SVGRenderer, SkeletonSVGRenderer, SketchSVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidDevice, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveDevicePreset, resolveGridPosition, resolveTokens, version };