@wire-dsl/engine 0.4.0 → 0.4.1

package/dist/index.cjs

@@ -2245,7 +2245,21 @@ var IRComponentNodeSchema = import_zod.z.object({
   style: IRNodeStyleSchema,
   meta: IRMetaSchema
 });
-var IRNodeSchema = import_zod.z.union([IRContainerNodeSchema, IRComponentNodeSchema]);
+var IRInstanceNodeSchema = import_zod.z.object({
+  id: import_zod.z.string(),
+  kind: import_zod.z.literal("instance"),
+  definitionName: import_zod.z.string(),
+  definitionKind: import_zod.z.enum(["component", "layout"]),
+  invocationProps: import_zod.z.record(import_zod.z.string(), import_zod.z.union([import_zod.z.string(), import_zod.z.number()])),
+  expandedRoot: import_zod.z.object({ ref: import_zod.z.string() }),
+  style: IRNodeStyleSchema,
+  meta: IRMetaSchema
+});
+var IRNodeSchema = import_zod.z.discriminatedUnion("kind", [
+  IRContainerNodeSchema,
+  IRComponentNodeSchema,
+  IRInstanceNodeSchema
+]);
 var IRScreenSchema = import_zod.z.object({
   id: import_zod.z.string(),
   name: import_zod.z.string(),
@@ -2468,7 +2482,7 @@ ${messages}`);
     const layoutChildren = layout.children;
     const layoutDefinition = this.definedLayouts.get(layout.layoutType);
     if (layoutDefinition) {
-      return this.expandDefinedLayout(layoutDefinition, layoutParams, layoutChildren, context);
+      return this.expandDefinedLayout(layoutDefinition, layoutParams, layoutChildren, context, layout._meta?.nodeId);
     }
     const nodeId = this.idGen.generate("node");
     const childRefs = [];
@@ -2507,8 +2521,8 @@ ${messages}`);
       children: childRefs,
       style,
       meta: {
-        nodeId: layout._meta?.nodeId
-        // Pass SourceMap nodeId from AST
+        // Scope nodeId per instance so each expansion gets a unique identifier
+        nodeId: context?.instanceScope ? `${layout._meta?.nodeId}@${context.instanceScope}` : layout._meta?.nodeId
       }
     };
     this.nodes[nodeId] = containerNode;
@@ -2537,8 +2551,7 @@ ${messages}`);
       // Cells have no padding by default - grid gap handles spacing
       meta: {
         source: "cell",
-        nodeId: cell._meta?.nodeId
-        // Pass SourceMap nodeId from AST
+        nodeId: context?.instanceScope ? `${cell._meta?.nodeId}@${context.instanceScope}` : cell._meta?.nodeId
       }
     };
     this.nodes[nodeId] = containerNode;
@@ -2565,7 +2578,7 @@ ${messages}`);
     const resolvedProps = this.resolveComponentProps(component.componentType, component.props, context);
     const definition = this.definedComponents.get(component.componentType);
     if (definition) {
-      return this.expandDefinedComponent(definition, resolvedProps, context);
+      return this.expandDefinedComponent(definition, resolvedProps, component._meta?.nodeId, context);
     }
     const builtInComponents = /* @__PURE__ */ new Set([
       "Button",
@@ -2611,35 +2624,49 @@ ${messages}`);
       props: resolvedProps,
       style: {},
       meta: {
-        nodeId: component._meta?.nodeId
-        // Pass SourceMap nodeId from AST
+        // Scope nodeId per instance so each expansion gets a unique identifier
+        nodeId: context?.instanceScope ? `${component._meta?.nodeId}@${context.instanceScope}` : component._meta?.nodeId
       }
     };
     this.nodes[nodeId] = componentNode;
     return nodeId;
   }
-  expandDefinedComponent(definition, invocationArgs, parentContext) {
+  expandDefinedComponent(definition, invocationArgs, callSiteNodeId, parentContext) {
     const context = {
       args: invocationArgs,
       providedArgNames: new Set(Object.keys(invocationArgs)),
       usedArgNames: /* @__PURE__ */ new Set(),
       definitionName: definition.name,
       definitionKind: "component",
-      allowChildrenSlot: false
+      allowChildrenSlot: false,
+      // Scope internal nodeIds using the call-site nodeId
+      instanceScope: callSiteNodeId
     };
+    let expandedRootId = null;
     if (definition.body.type === "layout") {
-      const result = this.convertLayout(definition.body, context);
-      this.reportUnusedArguments(context);
-      return result;
+      expandedRootId = this.convertLayout(definition.body, context);
     } else if (definition.body.type === "component") {
-      const result = this.convertComponent(definition.body, context);
-      this.reportUnusedArguments(context);
-      return result;
+      expandedRootId = this.convertComponent(definition.body, context);
     } else {
       throw new Error(`Invalid defined component body type for "${definition.name}"`);
     }
+    this.reportUnusedArguments(context);
+    if (!expandedRootId) return null;
+    const instanceNodeId = this.idGen.generate("node");
+    const instanceNode = {
+      id: instanceNodeId,
+      kind: "instance",
+      definitionName: definition.name,
+      definitionKind: "component",
+      invocationProps: invocationArgs,
+      expandedRoot: { ref: expandedRootId },
+      style: {},
+      meta: { nodeId: callSiteNodeId }
+    };
+    this.nodes[instanceNodeId] = instanceNode;
+    return instanceNodeId;
   }
-  expandDefinedLayout(definition, invocationParams, invocationChildren, parentContext) {
+  expandDefinedLayout(definition, invocationParams, invocationChildren, parentContext, callSiteNodeId) {
     if (invocationChildren.length !== 1) {
       this.errors.push({
         type: "layout-children-arity",
@@ -2655,11 +2682,26 @@ ${messages}`);
       definitionName: definition.name,
       definitionKind: "layout",
       allowChildrenSlot: true,
-      childrenSlot: resolvedSlot
+      childrenSlot: resolvedSlot,
+      // Scope internal nodeIds using the call-site nodeId
+      instanceScope: callSiteNodeId
     };
-    const nodeId = this.convertLayout(definition.body, context);
+    const expandedRootId = this.convertLayout(definition.body, context);
     this.reportUnusedArguments(context);
-    return nodeId;
+    if (!callSiteNodeId) return expandedRootId;
+    const instanceNodeId = this.idGen.generate("node");
+    const instanceNode = {
+      id: instanceNodeId,
+      kind: "instance",
+      definitionName: definition.name,
+      definitionKind: "layout",
+      invocationProps: invocationParams,
+      expandedRoot: { ref: expandedRootId },
+      style: {},
+      meta: { nodeId: callSiteNodeId }
+    };
+    this.nodes[instanceNodeId] = instanceNode;
+    return instanceNodeId;
   }
   resolveChildrenSlot(slot, parentContext) {
     if (slot.type === "component" && slot.componentType === "Children") {
@@ -3025,6 +3067,8 @@ var LayoutEngine = class {
     }
     if (node.kind === "container") {
       this.calculateContainer(node, nodeId, x, y, width, height);
+    } else if (node.kind === "instance") {
+      this.calculateInstance(node, nodeId, x, y, width, height, parentContainerType);
     } else {
       this.calculateComponent(node, nodeId, x, y, width, height);
     }
@@ -3057,7 +3101,7 @@ var LayoutEngine = class {
         this.calculateCard(node, innerX, innerY, innerWidth, innerHeight);
         break;
     }
-    if (isVerticalStack || node.containerType === "card") {
+    if ((isVerticalStack || node.containerType === "card") && node.children.length > 0) {
       let containerMaxY = y;
       node.children.forEach((childRef) => {
         const childPos = this.result[childRef.ref];
@@ -3200,6 +3244,10 @@ var LayoutEngine = class {
     const gap = this.resolveSpacing(node.style.gap);
     const padding = this.resolveSpacing(node.style.padding);
     let totalHeight = padding * 2;
+    const EMPTY_CONTAINER_MIN_HEIGHT = 40;
+    if (node.children.length === 0) {
+      return Math.max(totalHeight, EMPTY_CONTAINER_MIN_HEIGHT);
+    }
     if (node.containerType === "grid") {
       const columns = Number(node.params.columns) || 12;
       const colWidth = (availableWidth - gap * (columns - 1)) / columns;
@@ -3452,6 +3500,20 @@ var LayoutEngine = class {
       }
     });
   }
+  /**
+   * 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.
+   */
+  calculateInstance(node, nodeId, x, y, width, height, parentContainerType) {
+    const expandedRootId = node.expandedRoot.ref;
+    this.calculateNode(expandedRootId, x, y, width, height, parentContainerType);
+    const expandedPos = this.result[expandedRootId];
+    if (expandedPos) {
+      this.result[nodeId] = { ...expandedPos };
+    }
+  }
   calculateComponent(node, nodeId, x, y, width, height) {
     if (node.kind !== "component") return;
     const componentWidth = Number(node.props.width) || width;
@@ -4617,7 +4679,8 @@ var SVGRenderer = class {
       height: options?.height || 720,
       theme: colorScheme,
       includeLabels: options?.includeLabels ?? true,
-      screenName: options?.screenName
+      screenName: options?.screenName,
+      showDiagnostics: options?.showDiagnostics ?? false
     };
     this.colorResolver = new ColorResolver();
     this.buildParentContainerIndex();
@@ -4717,13 +4780,30 @@ var SVGRenderer = class {
       if (node.containerType === "split") {
         this.renderSplitDecoration(node, pos, containerGroup);
       }
-      node.children.forEach((childRef) => {
-        this.renderNode(childRef.ref, containerGroup);
-      });
+      if (node.children.length === 0 && this.options.showDiagnostics) {
+        containerGroup.push(this.renderEmptyContainerDiagnostic(pos, node.containerType));
+      } else {
+        node.children.forEach((childRef) => {
+          this.renderNode(childRef.ref, containerGroup);
+        });
+      }
       if (hasNodeId) {
         containerGroup.push("</g>");
       }
       output.push(...containerGroup);
+    } else if (node.kind === "instance") {
+      const instanceGroup = [];
+      if (node.meta.nodeId) {
+        instanceGroup.push(`<g data-node-id="${node.meta.nodeId}">`);
+      }
+      instanceGroup.push(
+        `<rect x="${pos.x}" y="${pos.y}" width="${pos.width}" height="${pos.height}" fill="transparent" stroke="none" pointer-events="all"/>`
+      );
+      this.renderNode(node.expandedRoot.ref, instanceGroup);
+      if (node.meta.nodeId) {
+        instanceGroup.push("</g>");
+      }
+      output.push(...instanceGroup);
     } else if (node.kind === "component") {
       const componentSvg = this.renderComponent(node, pos);
       if (componentSvg) {
@@ -5014,7 +5094,7 @@ var SVGRenderer = class {
     const variant = String(node.props.variant || "default");
     const accentColor = variant === "default" ? this.resolveAccentColor() : this.resolveVariantColor(variant, this.resolveAccentColor());
     const showBorder = this.parseBooleanProp(node.props.border, false);
-    const showBackground = this.parseBooleanProp(node.props.background ?? node.props.backround, false);
+    const showBackground = this.parseBooleanProp(node.props.background, false);
     const radiusMap = {
       none: 0,
       sm: 4,
@@ -5153,6 +5233,21 @@ var SVGRenderer = class {
     </g>`;
     output.push(svg);
   }
+  /**
+   * Renders a yellow warning placeholder for containers with no children.
+   * Only shown when `showDiagnostics` is enabled (editor/canvas mode).
+   */
+  renderEmptyContainerDiagnostic(pos, containerType) {
+    const diagColor = "#F59E0B";
+    const diagBg = "#FFFBEB";
+    const diagText = "#92400E";
+    const minHeight = 40;
+    const h = Math.max(pos.height, minHeight);
+    const cx = pos.x + pos.width / 2;
+    const cy = pos.y + h / 2;
+    const label = containerType ? `Empty ${containerType}` : "Empty layout";
+    return `<g><rect x="${pos.x}" y="${pos.y}" width="${pos.width}" height="${h}" rx="4" fill="${diagBg}" stroke="${diagColor}" stroke-width="1" stroke-dasharray="6 3"/><text x="${cx}" y="${cy}" font-family="Arial, Helvetica, sans-serif" font-size="12" fill="${diagText}" text-anchor="middle" dominant-baseline="middle">${label}</text></g>`;
+  }
   renderSplitDecoration(node, pos, output) {
     if (node.kind !== "container") return;
     const gap = this.resolveSpacing(node.style.gap);
@@ -5201,7 +5296,7 @@ var SVGRenderer = class {
     const hasCaption = caption.length > 0;
     const showOuterBorder = this.parseBooleanProp(node.props.border, false);
     const showOuterBackground = this.parseBooleanProp(
-      node.props.background ?? node.props.backround,
+      node.props.background,
       false
     );
     const showInnerBorder = this.parseBooleanProp(node.props.innerBorder, true);
@@ -6668,10 +6763,11 @@ var SVGRenderer = class {
   buildParentContainerIndex() {
     this.parentContainerByChildId.clear();
     Object.values(this.ir.project.nodes).forEach((node) => {
-      if (node.kind !== "container") return;
-      node.children.forEach((childRef) => {
-        this.parentContainerByChildId.set(childRef.ref, node);
-      });
+      if (node.kind === "container") {
+        node.children.forEach((childRef) => {
+          this.parentContainerByChildId.set(childRef.ref, node);
+        });
+      }
     });
   }
   escapeXml(text) {
@@ -7106,7 +7202,7 @@ var SkeletonSVGRenderer = class extends SVGRenderer {
     const hasCaption = String(node.props.caption || "").trim().length > 0;
     const showOuterBorder = this.parseBooleanProp(node.props.border, false);
     const showOuterBackground = this.parseBooleanProp(
-      node.props.background ?? node.props.backround,
+      node.props.background,
       false
     );
     const showInnerBorder = this.parseBooleanProp(node.props.innerBorder, true);
@@ -7221,7 +7317,7 @@ var SkeletonSVGRenderer = class extends SVGRenderer {
     const variant = String(node.props.variant || "default");
     const accentBlock = variant === "default" ? this.renderTheme.border : this.hexToRgba(this.resolveVariantColor(variant, this.resolveAccentColor()), 0.35);
     const showBorder = this.parseBooleanProp(node.props.border, false);
-    const showBackground = this.parseBooleanProp(node.props.background ?? node.props.backround, false);
+    const showBackground = this.parseBooleanProp(node.props.background, false);
     const radiusMap = {
       none: 0,
       sm: 4,

package/dist/index.d.cts

@@ -267,7 +267,7 @@ interface IRScreen {
         ref: string;
     };
 }
-type IRNode = IRContainerNode | IRComponentNode;
+type IRNode = IRContainerNode | IRComponentNode | IRInstanceNode;
 interface IRContainerNode {
     id: string;
     kind: 'container';
@@ -298,6 +298,28 @@ 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;
@@ -441,6 +463,13 @@ declare class LayoutEngine {
     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;
@@ -568,6 +597,12 @@ interface SVGRenderOptions {
     theme?: 'light' | 'dark';
     includeLabels?: boolean;
     screenName?: string;
+    /**
+     * When true, renders visual diagnostic overlays for invalid DSL states
+     * (e.g. empty containers). Enable in editor/canvas mode; leave false for
+     * clean exports (CLI, PDF, PNG).
+     */
+    showDiagnostics?: boolean;
 }
 interface SVGComponent {
     tag: string;
@@ -641,6 +676,16 @@ declare class SVGRenderer {
     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;
+    /**
+     * Renders a yellow warning placeholder for containers with no children.
+     * Only shown when `showDiagnostics` is enabled (editor/canvas mode).
+     */
+    protected renderEmptyContainerDiagnostic(pos: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, containerType?: string): string;
     protected renderSplitDecoration(node: IRNode, pos: any, output: string[]): void;
     protected renderTable(node: IRComponentNode, pos: any): string;
     protected renderChartPlaceholder(node: IRComponentNode, pos: any): string;
@@ -750,7 +795,7 @@ declare class SVGRenderer {
      * Get data-node-id attribute string for SVG elements
      * Enables bidirectional selection between code and canvas
      */
-    protected getDataNodeId(node: IRComponentNode | IRContainerNode): string;
+    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;
@@ -1348,4 +1393,4 @@ declare class SourceMapResolver {
 
 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 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 };
+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 };

package/dist/index.d.ts

@@ -267,7 +267,7 @@ interface IRScreen {
         ref: string;
     };
 }
-type IRNode = IRContainerNode | IRComponentNode;
+type IRNode = IRContainerNode | IRComponentNode | IRInstanceNode;
 interface IRContainerNode {
     id: string;
     kind: 'container';
@@ -298,6 +298,28 @@ 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;
@@ -441,6 +463,13 @@ declare class LayoutEngine {
     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;
@@ -568,6 +597,12 @@ interface SVGRenderOptions {
     theme?: 'light' | 'dark';
     includeLabels?: boolean;
     screenName?: string;
+    /**
+     * When true, renders visual diagnostic overlays for invalid DSL states
+     * (e.g. empty containers). Enable in editor/canvas mode; leave false for
+     * clean exports (CLI, PDF, PNG).
+     */
+    showDiagnostics?: boolean;
 }
 interface SVGComponent {
     tag: string;
@@ -641,6 +676,16 @@ declare class SVGRenderer {
     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;
+    /**
+     * Renders a yellow warning placeholder for containers with no children.
+     * Only shown when `showDiagnostics` is enabled (editor/canvas mode).
+     */
+    protected renderEmptyContainerDiagnostic(pos: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, containerType?: string): string;
     protected renderSplitDecoration(node: IRNode, pos: any, output: string[]): void;
     protected renderTable(node: IRComponentNode, pos: any): string;
     protected renderChartPlaceholder(node: IRComponentNode, pos: any): string;
@@ -750,7 +795,7 @@ declare class SVGRenderer {
      * Get data-node-id attribute string for SVG elements
      * Enables bidirectional selection between code and canvas
      */
-    protected getDataNodeId(node: IRComponentNode | IRContainerNode): string;
+    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;
@@ -1348,4 +1393,4 @@ declare class SourceMapResolver {
 
 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 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 };
+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 };

package/dist/index.js

@@ -2199,7 +2199,21 @@ var IRComponentNodeSchema = z.object({
   style: IRNodeStyleSchema,
   meta: IRMetaSchema
 });
-var IRNodeSchema = z.union([IRContainerNodeSchema, IRComponentNodeSchema]);
+var IRInstanceNodeSchema = z.object({
+  id: z.string(),
+  kind: z.literal("instance"),
+  definitionName: z.string(),
+  definitionKind: z.enum(["component", "layout"]),
+  invocationProps: z.record(z.string(), z.union([z.string(), z.number()])),
+  expandedRoot: z.object({ ref: z.string() }),
+  style: IRNodeStyleSchema,
+  meta: IRMetaSchema
+});
+var IRNodeSchema = z.discriminatedUnion("kind", [
+  IRContainerNodeSchema,
+  IRComponentNodeSchema,
+  IRInstanceNodeSchema
+]);
 var IRScreenSchema = z.object({
   id: z.string(),
   name: z.string(),
@@ -2422,7 +2436,7 @@ ${messages}`);
     const layoutChildren = layout.children;
     const layoutDefinition = this.definedLayouts.get(layout.layoutType);
     if (layoutDefinition) {
-      return this.expandDefinedLayout(layoutDefinition, layoutParams, layoutChildren, context);
+      return this.expandDefinedLayout(layoutDefinition, layoutParams, layoutChildren, context, layout._meta?.nodeId);
     }
     const nodeId = this.idGen.generate("node");
     const childRefs = [];
@@ -2461,8 +2475,8 @@ ${messages}`);
       children: childRefs,
       style,
       meta: {
-        nodeId: layout._meta?.nodeId
-        // Pass SourceMap nodeId from AST
+        // Scope nodeId per instance so each expansion gets a unique identifier
+        nodeId: context?.instanceScope ? `${layout._meta?.nodeId}@${context.instanceScope}` : layout._meta?.nodeId
       }
     };
     this.nodes[nodeId] = containerNode;
@@ -2491,8 +2505,7 @@ ${messages}`);
       // Cells have no padding by default - grid gap handles spacing
       meta: {
         source: "cell",
-        nodeId: cell._meta?.nodeId
-        // Pass SourceMap nodeId from AST
+        nodeId: context?.instanceScope ? `${cell._meta?.nodeId}@${context.instanceScope}` : cell._meta?.nodeId
       }
     };
     this.nodes[nodeId] = containerNode;
@@ -2519,7 +2532,7 @@ ${messages}`);
     const resolvedProps = this.resolveComponentProps(component.componentType, component.props, context);
     const definition = this.definedComponents.get(component.componentType);
     if (definition) {
-      return this.expandDefinedComponent(definition, resolvedProps, context);
+      return this.expandDefinedComponent(definition, resolvedProps, component._meta?.nodeId, context);
     }
     const builtInComponents = /* @__PURE__ */ new Set([
       "Button",
@@ -2565,35 +2578,49 @@ ${messages}`);
       props: resolvedProps,
       style: {},
       meta: {
-        nodeId: component._meta?.nodeId
-        // Pass SourceMap nodeId from AST
+        // Scope nodeId per instance so each expansion gets a unique identifier
+        nodeId: context?.instanceScope ? `${component._meta?.nodeId}@${context.instanceScope}` : component._meta?.nodeId
       }
     };
     this.nodes[nodeId] = componentNode;
     return nodeId;
   }
-  expandDefinedComponent(definition, invocationArgs, parentContext) {
+  expandDefinedComponent(definition, invocationArgs, callSiteNodeId, parentContext) {
     const context = {
       args: invocationArgs,
       providedArgNames: new Set(Object.keys(invocationArgs)),
       usedArgNames: /* @__PURE__ */ new Set(),
       definitionName: definition.name,
       definitionKind: "component",
-      allowChildrenSlot: false
+      allowChildrenSlot: false,
+      // Scope internal nodeIds using the call-site nodeId
+      instanceScope: callSiteNodeId
     };
+    let expandedRootId = null;
     if (definition.body.type === "layout") {
-      const result = this.convertLayout(definition.body, context);
-      this.reportUnusedArguments(context);
-      return result;
+      expandedRootId = this.convertLayout(definition.body, context);
     } else if (definition.body.type === "component") {
-      const result = this.convertComponent(definition.body, context);
-      this.reportUnusedArguments(context);
-      return result;
+      expandedRootId = this.convertComponent(definition.body, context);
     } else {
       throw new Error(`Invalid defined component body type for "${definition.name}"`);
     }
+    this.reportUnusedArguments(context);
+    if (!expandedRootId) return null;
+    const instanceNodeId = this.idGen.generate("node");
+    const instanceNode = {
+      id: instanceNodeId,
+      kind: "instance",
+      definitionName: definition.name,
+      definitionKind: "component",
+      invocationProps: invocationArgs,
+      expandedRoot: { ref: expandedRootId },
+      style: {},
+      meta: { nodeId: callSiteNodeId }
+    };
+    this.nodes[instanceNodeId] = instanceNode;
+    return instanceNodeId;
   }
-  expandDefinedLayout(definition, invocationParams, invocationChildren, parentContext) {
+  expandDefinedLayout(definition, invocationParams, invocationChildren, parentContext, callSiteNodeId) {
     if (invocationChildren.length !== 1) {
       this.errors.push({
         type: "layout-children-arity",
@@ -2609,11 +2636,26 @@ ${messages}`);
       definitionName: definition.name,
       definitionKind: "layout",
       allowChildrenSlot: true,
-      childrenSlot: resolvedSlot
+      childrenSlot: resolvedSlot,
+      // Scope internal nodeIds using the call-site nodeId
+      instanceScope: callSiteNodeId
     };
-    const nodeId = this.convertLayout(definition.body, context);
+    const expandedRootId = this.convertLayout(definition.body, context);
     this.reportUnusedArguments(context);
-    return nodeId;
+    if (!callSiteNodeId) return expandedRootId;
+    const instanceNodeId = this.idGen.generate("node");
+    const instanceNode = {
+      id: instanceNodeId,
+      kind: "instance",
+      definitionName: definition.name,
+      definitionKind: "layout",
+      invocationProps: invocationParams,
+      expandedRoot: { ref: expandedRootId },
+      style: {},
+      meta: { nodeId: callSiteNodeId }
+    };
+    this.nodes[instanceNodeId] = instanceNode;
+    return instanceNodeId;
   }
   resolveChildrenSlot(slot, parentContext) {
     if (slot.type === "component" && slot.componentType === "Children") {
@@ -2979,6 +3021,8 @@ var LayoutEngine = class {
     }
     if (node.kind === "container") {
       this.calculateContainer(node, nodeId, x, y, width, height);
+    } else if (node.kind === "instance") {
+      this.calculateInstance(node, nodeId, x, y, width, height, parentContainerType);
     } else {
       this.calculateComponent(node, nodeId, x, y, width, height);
     }
@@ -3011,7 +3055,7 @@ var LayoutEngine = class {
         this.calculateCard(node, innerX, innerY, innerWidth, innerHeight);
         break;
     }
-    if (isVerticalStack || node.containerType === "card") {
+    if ((isVerticalStack || node.containerType === "card") && node.children.length > 0) {
       let containerMaxY = y;
       node.children.forEach((childRef) => {
         const childPos = this.result[childRef.ref];
@@ -3154,6 +3198,10 @@ var LayoutEngine = class {
     const gap = this.resolveSpacing(node.style.gap);
     const padding = this.resolveSpacing(node.style.padding);
     let totalHeight = padding * 2;
+    const EMPTY_CONTAINER_MIN_HEIGHT = 40;
+    if (node.children.length === 0) {
+      return Math.max(totalHeight, EMPTY_CONTAINER_MIN_HEIGHT);
+    }
     if (node.containerType === "grid") {
       const columns = Number(node.params.columns) || 12;
       const colWidth = (availableWidth - gap * (columns - 1)) / columns;
@@ -3406,6 +3454,20 @@ var LayoutEngine = class {
       }
     });
   }
+  /**
+   * 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.
+   */
+  calculateInstance(node, nodeId, x, y, width, height, parentContainerType) {
+    const expandedRootId = node.expandedRoot.ref;
+    this.calculateNode(expandedRootId, x, y, width, height, parentContainerType);
+    const expandedPos = this.result[expandedRootId];
+    if (expandedPos) {
+      this.result[nodeId] = { ...expandedPos };
+    }
+  }
   calculateComponent(node, nodeId, x, y, width, height) {
     if (node.kind !== "component") return;
     const componentWidth = Number(node.props.width) || width;
@@ -4571,7 +4633,8 @@ var SVGRenderer = class {
       height: options?.height || 720,
       theme: colorScheme,
       includeLabels: options?.includeLabels ?? true,
-      screenName: options?.screenName
+      screenName: options?.screenName,
+      showDiagnostics: options?.showDiagnostics ?? false
     };
     this.colorResolver = new ColorResolver();
     this.buildParentContainerIndex();
@@ -4671,13 +4734,30 @@ var SVGRenderer = class {
       if (node.containerType === "split") {
         this.renderSplitDecoration(node, pos, containerGroup);
       }
-      node.children.forEach((childRef) => {
-        this.renderNode(childRef.ref, containerGroup);
-      });
+      if (node.children.length === 0 && this.options.showDiagnostics) {
+        containerGroup.push(this.renderEmptyContainerDiagnostic(pos, node.containerType));
+      } else {
+        node.children.forEach((childRef) => {
+          this.renderNode(childRef.ref, containerGroup);
+        });
+      }
       if (hasNodeId) {
         containerGroup.push("</g>");
       }
       output.push(...containerGroup);
+    } else if (node.kind === "instance") {
+      const instanceGroup = [];
+      if (node.meta.nodeId) {
+        instanceGroup.push(`<g data-node-id="${node.meta.nodeId}">`);
+      }
+      instanceGroup.push(
+        `<rect x="${pos.x}" y="${pos.y}" width="${pos.width}" height="${pos.height}" fill="transparent" stroke="none" pointer-events="all"/>`
+      );
+      this.renderNode(node.expandedRoot.ref, instanceGroup);
+      if (node.meta.nodeId) {
+        instanceGroup.push("</g>");
+      }
+      output.push(...instanceGroup);
     } else if (node.kind === "component") {
       const componentSvg = this.renderComponent(node, pos);
       if (componentSvg) {
@@ -4968,7 +5048,7 @@ var SVGRenderer = class {
     const variant = String(node.props.variant || "default");
     const accentColor = variant === "default" ? this.resolveAccentColor() : this.resolveVariantColor(variant, this.resolveAccentColor());
     const showBorder = this.parseBooleanProp(node.props.border, false);
-    const showBackground = this.parseBooleanProp(node.props.background ?? node.props.backround, false);
+    const showBackground = this.parseBooleanProp(node.props.background, false);
     const radiusMap = {
       none: 0,
       sm: 4,
@@ -5107,6 +5187,21 @@ var SVGRenderer = class {
     </g>`;
     output.push(svg);
   }
+  /**
+   * Renders a yellow warning placeholder for containers with no children.
+   * Only shown when `showDiagnostics` is enabled (editor/canvas mode).
+   */
+  renderEmptyContainerDiagnostic(pos, containerType) {
+    const diagColor = "#F59E0B";
+    const diagBg = "#FFFBEB";
+    const diagText = "#92400E";
+    const minHeight = 40;
+    const h = Math.max(pos.height, minHeight);
+    const cx = pos.x + pos.width / 2;
+    const cy = pos.y + h / 2;
+    const label = containerType ? `Empty ${containerType}` : "Empty layout";
+    return `<g><rect x="${pos.x}" y="${pos.y}" width="${pos.width}" height="${h}" rx="4" fill="${diagBg}" stroke="${diagColor}" stroke-width="1" stroke-dasharray="6 3"/><text x="${cx}" y="${cy}" font-family="Arial, Helvetica, sans-serif" font-size="12" fill="${diagText}" text-anchor="middle" dominant-baseline="middle">${label}</text></g>`;
+  }
   renderSplitDecoration(node, pos, output) {
     if (node.kind !== "container") return;
     const gap = this.resolveSpacing(node.style.gap);
@@ -5155,7 +5250,7 @@ var SVGRenderer = class {
     const hasCaption = caption.length > 0;
     const showOuterBorder = this.parseBooleanProp(node.props.border, false);
     const showOuterBackground = this.parseBooleanProp(
-      node.props.background ?? node.props.backround,
+      node.props.background,
       false
     );
     const showInnerBorder = this.parseBooleanProp(node.props.innerBorder, true);
@@ -6622,10 +6717,11 @@ var SVGRenderer = class {
   buildParentContainerIndex() {
     this.parentContainerByChildId.clear();
     Object.values(this.ir.project.nodes).forEach((node) => {
-      if (node.kind !== "container") return;
-      node.children.forEach((childRef) => {
-        this.parentContainerByChildId.set(childRef.ref, node);
-      });
+      if (node.kind === "container") {
+        node.children.forEach((childRef) => {
+          this.parentContainerByChildId.set(childRef.ref, node);
+        });
+      }
     });
   }
   escapeXml(text) {
@@ -7060,7 +7156,7 @@ var SkeletonSVGRenderer = class extends SVGRenderer {
     const hasCaption = String(node.props.caption || "").trim().length > 0;
     const showOuterBorder = this.parseBooleanProp(node.props.border, false);
     const showOuterBackground = this.parseBooleanProp(
-      node.props.background ?? node.props.backround,
+      node.props.background,
       false
     );
     const showInnerBorder = this.parseBooleanProp(node.props.innerBorder, true);
@@ -7175,7 +7271,7 @@ var SkeletonSVGRenderer = class extends SVGRenderer {
     const variant = String(node.props.variant || "default");
     const accentBlock = variant === "default" ? this.renderTheme.border : this.hexToRgba(this.resolveVariantColor(variant, this.resolveAccentColor()), 0.35);
     const showBorder = this.parseBooleanProp(node.props.border, false);
-    const showBackground = this.parseBooleanProp(node.props.background ?? node.props.backround, false);
+    const showBackground = this.parseBooleanProp(node.props.background, false);
     const radiusMap = {
       none: 0,
       sm: 4,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wire-dsl/engine",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "WireDSL engine - Parser, IR generator, layout engine, and SVG renderer (browser-safe, pure JS/TS)",
   "type": "module",
   "exports": {