@wire-dsl/engine 0.0.0-canary-20260221183600

package/dist/index.d.cts

@@ -0,0 +1,1380 @@
+/**
+ * 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' | 'layout-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[];
+    diagnostics: ParseError[];
+    errors: ParseError[];
+    warnings: ParseError[];
+    hasErrors: boolean;
+}
+/**
+ * Parse result with diagnostics and optional AST/SourceMap
+ * Used by tolerant editor flows where diagnostics are needed even when parsing fails
+ */
+interface ParseDiagnosticsResult {
+    ast?: AST;
+    sourceMap?: SourceMapEntry[];
+    diagnostics: ParseError[];
+    errors: ParseError[];
+    warnings: ParseError[];
+    hasErrors: boolean;
+}
+/**
+ * Parse error with optional nodeId reference
+ */
+interface ParseError {
+    message: string;
+    range: CodeRange;
+    severity: 'error' | 'warning';
+    code?: string;
+    phase?: 'lexer' | 'parser' | 'semantic';
+    expected?: string;
+    actual?: string;
+    suggestion?: string;
+    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;
+    style: Record<string, string>;
+    mocks: Record<string, string>;
+    colors: Record<string, string>;
+    definedComponents: ASTDefinedComponent[];
+    definedLayouts: ASTDefinedLayout[];
+    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;
+    };
+}
+interface ParseWireDSLWithSourceMapOptions {
+    throwOnError?: boolean;
+    includeSemanticWarnings?: boolean;
+}
+interface ASTDefinedLayout {
+    type: 'definedLayout';
+    name: string;
+    body: ASTLayout;
+    _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;
+declare function parseWireDSLWithSourceMap(input: string, filePath: string | undefined, options: ParseWireDSLWithSourceMapOptions & {
+    throwOnError: false;
+}): ParseDiagnosticsResult;
+interface ParsedWireframe {
+    name: string;
+    components: ParsedComponent[];
+}
+interface ParsedComponent {
+    type: string;
+    id: string;
+    children?: ParsedComponent[];
+    properties?: Record<string, unknown>;
+}
+
+/**
+ * Intermediate Representation (IR) Generator
+ *
+ * Transforms AST to normalized IR (JSON format)
+ * - Applies defaults from tokens
+ * - Generates unique IDs
+ * - Validates structure with Zod
+ */
+interface IRContract {
+    irVersion: string;
+    project: IRProject;
+}
+interface IRProject {
+    id: string;
+    name: string;
+    style: IRStyle;
+    mocks: Record<string, unknown>;
+    colors: Record<string, string>;
+    screens: IRScreen[];
+    nodes: Record<string, IRNode>;
+}
+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;
+    name: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    background?: string;
+    root: {
+        ref: string;
+    };
+}
+type IRNode = IRContainerNode | IRComponentNode | IRInstanceNode;
+interface IRContainerNode {
+    id: string;
+    kind: 'container';
+    containerType: 'stack' | 'grid' | 'split' | 'panel' | 'card';
+    params: Record<string, string | number>;
+    children: Array<{
+        ref: string;
+    }>;
+    style: IRNodeStyle;
+    meta: IRMeta;
+}
+interface IRComponentNode {
+    id: string;
+    kind: 'component';
+    componentType: string;
+    props: Record<string, string | number>;
+    style: IRNodeStyle;
+    meta: IRMeta;
+}
+interface IRNodeStyle {
+    padding?: string;
+    gap?: string;
+    align?: 'left' | 'center' | 'right' | 'justify';
+    justify?: 'start' | 'center' | 'end';
+    background?: string;
+}
+interface IRMeta {
+    source?: string;
+    nodeId?: string;
+}
+/**
+ * Wraps an expanded user-defined component or layout instance.
+ * Preserves the call-site identity (nodeId) in the SVG so the canvas
+ * can select and edit the instance independently from its definition.
+ */
+interface IRInstanceNode {
+    id: string;
+    kind: 'instance';
+    /** Name of the user-defined component or layout (e.g. "MyComp") */
+    definitionName: string;
+    /** Whether it originated from a `define Component` or `define Layout` */
+    definitionKind: 'component' | 'layout';
+    /** Props/params passed at the call site (e.g. { text: "Hello" }) */
+    invocationProps: Record<string, string | number>;
+    /** Reference to the root IR node produced by expanding the definition */
+    expandedRoot: {
+        ref: string;
+    };
+    style: IRNodeStyle;
+    /** meta.nodeId = SourceMap nodeId of the call-site AST node */
+    meta: IRMeta;
+}
+declare class IRGenerator {
+    private idGen;
+    private nodes;
+    private definedComponents;
+    private definedLayouts;
+    private definedComponentIndices;
+    private undefinedComponentsUsed;
+    private warnings;
+    private errors;
+    private style;
+    generate(ast: AST): IRContract;
+    private applyStyle;
+    private convertScreen;
+    /**
+     * Validates that component definitions appear before their first usage
+     * Generates warnings (not errors) to allow flexible code organization
+     */
+    private validateComponentOrder;
+    /**
+     * Recursively finds all component usages in a layout
+     */
+    private findComponentsInLayout;
+    /**
+     * Get all warnings generated during IR generation
+     */
+    getWarnings(): Array<{
+        message: string;
+        type: string;
+    }>;
+    private convertLayout;
+    private convertCell;
+    private convertComponent;
+    private expandDefinedComponent;
+    private expandDefinedLayout;
+    private resolveChildrenSlot;
+    private convertASTNode;
+    private resolveLayoutParams;
+    private normalizeSplitParams;
+    private resolveComponentProps;
+    private resolveBindingValue;
+    private isBindingTargetRequired;
+    private reportUnusedArguments;
+    private cleanParams;
+    private sanitizeId;
+}
+declare function generateIR(ast: AST): IRContract;
+interface IRWireframe {
+    id: string;
+    name: string;
+    components: IRComponent[];
+    layout: IRLayout;
+    metadata: IRMetadata;
+}
+interface IRComponent {
+    id: string;
+    type: string;
+    label?: string;
+    props?: Record<string, unknown>;
+    children?: IRComponent[];
+}
+interface IRLayout {
+    width: number;
+    height: number;
+    gridCols: number;
+    gridRows: number;
+}
+interface IRMetadata {
+    version: string;
+    created: string;
+    author?: string;
+    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
+ *
+ * Calculates positions and dimensions for all nodes
+ * Supports: stack (vertical/horizontal), grid (12-column)
+ */
+interface LayoutPosition {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface LayoutResult {
+    [nodeId: string]: LayoutPosition;
+}
+declare class LayoutEngine {
+    private nodes;
+    private style;
+    private result;
+    private viewport;
+    private ir;
+    private parentContainerTypes;
+    constructor(ir: IRContract);
+    calculate(): LayoutResult;
+    private calculateNode;
+    private calculateContainer;
+    private calculateStack;
+    private calculateContainerHeight;
+    private calculateGrid;
+    private calculateSplit;
+    private calculatePanel;
+    private calculateCard;
+    /**
+     * Calculate layout for an instance node.
+     * The instance is a transparent wrapper — its bounding box equals the
+     * expanded root's bounding box. We calculate the expanded root first and
+     * then copy its position to the instance nodeId so the renderer can use it.
+     */
+    private calculateInstance;
+    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 parseBooleanProp;
+    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
+ *
+ * Generates accessible, optimized SVG output from IR + Layout
+ */
+interface SVGRenderOptions {
+    width?: number;
+    height?: number;
+    theme?: 'light' | 'dark';
+    includeLabels?: boolean;
+    screenName?: string;
+}
+interface SVGComponent {
+    tag: string;
+    attrs: Record<string, string | number>;
+    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 {
+    protected ir: IRContract;
+    private layout;
+    protected options: Required<Omit<SVGRenderOptions, 'screenName'>> & {
+        screenName?: string;
+    };
+    protected renderTheme: typeof THEMES.light;
+    protected tokens: DesignTokens;
+    private selectedScreenName?;
+    protected renderedNodeIds: Set<string>;
+    protected colorResolver: ColorResolver;
+    protected fontFamily: string;
+    private parentContainerByChildId;
+    constructor(ir: IRContract, layout: LayoutResult, options?: SVGRenderOptions);
+    /**
+     * Get list of available screens in the project
+     */
+    getAvailableScreens(): Array<{
+        name: string;
+        id: string;
+    }>;
+    /**
+     * Get the currently selected or first screen
+     */
+    protected getSelectedScreen(): {
+        screen: any;
+        name: string;
+    };
+    render(): string;
+    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 renderSplitDecoration(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
+     */
+    protected extractSvgContent(svgString: string): string;
+    protected resolveVariantColor(variant: string, fallback: string): string;
+    protected resolveAccentColor(): string;
+    protected resolveControlColor(): string;
+    protected resolveChartColor(): string;
+    protected resolveTextColor(): string;
+    protected resolveMutedColor(): 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 shouldButtonFillAvailableWidth(node: IRComponentNode): boolean;
+    private buildParentContainerIndex;
+    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 | IRInstanceNode): 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 breadcrumbs as skeleton blocks: <rect> / <rect> / <rect accent>
+     */
+    protected renderBreadcrumbs(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 image as a plain skeleton rectangle — no icon, no placeholder label,
+     * just a filled block with the correct dimensions (aspect-ratio is preserved
+     * by the layout engine, so pos already has the right size).
+     */
+    protected renderImage(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"
+   * - layout-definition → "define-layout-MyShell"
+     */
+    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, layout-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 ASTDefinedLayout, 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 IRInstanceNode, 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 ParseDiagnosticsResult, type ParseError, type ParseResult, type ParseWireDSLWithSourceMapOptions, 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 };