@wire-dsl/engine 0.4.0 → 0.5.0

package/README.md

@@ -92,7 +92,7 @@ validateIR(ir); // Throws if invalid
 
 **Display**: Divider, Badge, Link, Alert
 
-**Info**: StatCard, Code, ChartPlaceholder
+**Info**: Stat, Code, ChartPlaceholder
 
 **Feedback**: Modal, Spinner
 

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",
@@ -2575,7 +2588,7 @@ ${messages}`);
       "Label",
       "Image",
       "Card",
-      "StatCard",
+      "Stat",
       "Topbar",
       "Table",
       "Chart",
@@ -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;
@@ -3669,7 +3731,7 @@ var LayoutEngine = class {
     if (node.componentType === "Textarea") return 100 + controlLabelOffset;
     if (node.componentType === "Modal") return 300;
     if (node.componentType === "Card") return 120;
-    if (node.componentType === "StatCard") return 120;
+    if (node.componentType === "Stat") return 120;
     if (node.componentType === "Chart" || node.componentType === "ChartPlaceholder") return 250;
     if (node.componentType === "List") {
       const itemsFromProps = String(node.props.items || "").split(",").map((item) => item.trim()).filter(Boolean);
@@ -3720,7 +3782,10 @@ var LayoutEngine = class {
       const density = this.style.density || "normal";
       const extraPadding = resolveControlHorizontalPadding(String(node.props.padding || "none"), density);
       const textWidth = this.estimateTextWidth(text, fontSize);
-      return Math.max(60, Math.ceil(textWidth + (paddingX + extraPadding) * 2));
+      const iconName = String(node.props.icon || "").trim();
+      const iconSize = iconName ? Math.round(fontSize * 1.1) : 0;
+      const iconGap = iconName ? 8 : 0;
+      return Math.max(60, Math.ceil(textWidth + iconSize + iconGap + (paddingX + extraPadding) * 2));
     }
     if (node.componentType === "Label" || node.componentType === "Text") {
       const text = String(node.props.text || "");
@@ -3751,7 +3816,7 @@ var LayoutEngine = class {
     if (node.componentType === "Table") {
       return 400;
     }
-    if (node.componentType === "StatCard" || node.componentType === "Card") {
+    if (node.componentType === "Stat" || node.componentType === "Card") {
       return 280;
     }
     if (node.componentType === "SidebarMenu") {
@@ -4617,7 +4682,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 +4783,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) {
@@ -4789,8 +4872,8 @@ var SVGRenderer = class {
         return this.renderModal(node, pos);
       case "List":
         return this.renderList(node, pos);
-      case "StatCard":
-        return this.renderStatCard(node, pos);
+      case "Stat":
+        return this.renderStat(node, pos);
       case "Image":
         return this.renderImage(node, pos);
       // Icon components
@@ -4836,6 +4919,7 @@ var SVGRenderer = class {
     const text = String(node.props.text || "Button");
     const variant = String(node.props.variant || "default");
     const size = String(node.props.size || "md");
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const density = this.ir.project.style.density || "normal";
     const extraPadding = resolveControlHorizontalPadding(String(node.props.padding || "none"), density);
     const labelOffset = this.parseBooleanProp(node.props.labelSpace, false) ? 18 : 0;
@@ -4881,7 +4965,7 @@ var SVGRenderer = class {
       textX = pos.x + buttonWidth / 2;
       textAnchor = "middle";
     }
-    let svg = `<g${this.getDataNodeId(node)}>
+    let svg = `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>
     <rect x="${pos.x}" y="${buttonY}"
           width="${buttonWidth}" height="${buttonHeight}"
           rx="${radius}"
@@ -4947,6 +5031,7 @@ var SVGRenderer = class {
     const placeholder = String(node.props.placeholder || "");
     const iconLeftName = String(node.props.iconLeft || "").trim();
     const iconRightName = String(node.props.iconRight || "").trim();
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const radius = this.tokens.input.radius;
     const fontSize = this.tokens.input.fontSize;
     const paddingX = this.tokens.input.paddingX;
@@ -4963,7 +5048,7 @@ var SVGRenderer = class {
     const textX = pos.x + (iconLeftSvg ? leftOffset : paddingX);
     const iconColor = this.hexToRgba(this.resolveMutedColor(), 0.8);
     const iconCenterY = controlY + (controlHeight - iconSize) / 2;
-    let svg = `<g${this.getDataNodeId(node)}>`;
+    let svg = `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>`;
     if (label) {
       svg += `
     <text x="${pos.x + paddingX}" y="${this.getControlLabelBaselineY(pos.y)}"
@@ -5014,7 +5099,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 +5238,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 +5301,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);
@@ -5586,6 +5686,7 @@ var SVGRenderer = class {
     const placeholder = String(node.props.placeholder || "Select...");
     const iconLeftName = String(node.props.iconLeft || "").trim();
     const iconRightName = String(node.props.iconRight || "").trim();
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const labelOffset = this.getControlLabelOffset(label);
     const controlY = pos.y + labelOffset;
     const controlHeight = Math.max(16, pos.height - labelOffset);
@@ -5599,7 +5700,7 @@ var SVGRenderer = class {
     const chevronWidth = 20;
     const iconColor = this.hexToRgba(this.resolveMutedColor(), 0.8);
     const iconCenterY = controlY + (controlHeight - iconSize) / 2;
-    let svg = `<g${this.getDataNodeId(node)}>`;
+    let svg = `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>`;
     if (label) {
       svg += `
     <text x="${pos.x}" y="${this.getControlLabelBaselineY(pos.y)}"
@@ -5648,10 +5749,11 @@ var SVGRenderer = class {
   renderCheckbox(node, pos) {
     const label = String(node.props.label || "Checkbox");
     const checked = String(node.props.checked || "false").toLowerCase() === "true";
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const controlColor = this.resolveControlColor();
     const checkboxSize = 18;
     const checkboxY = pos.y + pos.height / 2 - checkboxSize / 2;
-    return `<g${this.getDataNodeId(node)}>
+    return `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>
     <rect x="${pos.x}" y="${checkboxY}" 
           width="${checkboxSize}" height="${checkboxSize}" 
           rx="4" 
@@ -5672,10 +5774,11 @@ var SVGRenderer = class {
   renderRadio(node, pos) {
     const label = String(node.props.label || "Radio");
     const checked = String(node.props.checked || "false").toLowerCase() === "true";
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const controlColor = this.resolveControlColor();
     const radioSize = 16;
     const radioY = pos.y + pos.height / 2 - radioSize / 2;
-    return `<g${this.getDataNodeId(node)}>
+    return `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>
     <circle cx="${pos.x + radioSize / 2}" cy="${radioY + radioSize / 2}" 
             r="${radioSize / 2}" 
             fill="${this.renderTheme.cardBg}" 
@@ -5693,11 +5796,12 @@ var SVGRenderer = class {
   renderToggle(node, pos) {
     const label = String(node.props.label || "Toggle");
     const enabled = String(node.props.enabled || "false").toLowerCase() === "true";
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const controlColor = this.resolveControlColor();
     const toggleWidth = 40;
     const toggleHeight = 20;
     const toggleY = pos.y + pos.height / 2 - toggleHeight / 2;
-    return `<g${this.getDataNodeId(node)}>
+    return `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>
     <rect x="${pos.x}" y="${toggleY}" 
           width="${toggleWidth}" height="${toggleHeight}" 
           rx="10" 
@@ -5993,7 +6097,7 @@ var SVGRenderer = class {
           text-anchor="middle">${node.componentType}</text>
   </g>`;
   }
-  renderStatCard(node, pos) {
+  renderStat(node, pos) {
     const title = String(node.props.title || "Metric");
     const value = String(node.props.value || "0");
     const rawCaption = String(node.props.caption || "");
@@ -6001,7 +6105,9 @@ var SVGRenderer = class {
     const hasCaption = caption.trim().length > 0;
     const iconName = String(node.props.icon || "").trim();
     const iconSvg = iconName ? getIcon(iconName) : null;
-    const accentColor = this.resolveAccentColor();
+    const variant = String(node.props.variant || "default");
+    const baseAccent = this.resolveAccentColor();
+    const accentColor = variant !== "default" ? this.resolveVariantColor(variant, baseAccent) : baseAccent;
     const padding = this.resolveSpacing(node.style.padding) || 16;
     const innerX = pos.x + padding;
     const innerY = pos.y + padding;
@@ -6025,7 +6131,7 @@ var SVGRenderer = class {
     const visibleTitle = this.truncateTextToWidth(title, titleMaxWidth, titleSize);
     const visibleCaption = hasCaption ? this.truncateTextToWidth(caption, Math.max(20, innerWidth), captionSize) : "";
     let svg = `<g${this.getDataNodeId(node)}>
-    <!-- StatCard Background -->
+    <!-- Stat Background -->
     <rect x="${pos.x}" y="${pos.y}" 
           width="${pos.width}" height="${pos.height}" 
           rx="8" 
@@ -6668,10 +6774,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 +7213,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 +7328,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,
@@ -7287,9 +7394,9 @@ var SkeletonSVGRenderer = class extends SVGRenderer {
     return svg;
   }
   /**
-   * Render StatCard with gray blocks instead of values
+   * Render Stat with gray blocks instead of values
    */
-  renderStatCard(node, pos) {
+  renderStat(node, pos) {
     const hasIcon = String(node.props.icon || "").trim().length > 0;
     const hasCaption = String(node.props.caption || "").trim().length > 0;
     const iconSize = 20;
@@ -8416,7 +8523,7 @@ var SketchSVGRenderer = class extends SVGRenderer {
   /**
    * Render stat card with sketch filter and Comic Sans
    */
-  renderStatCard(node, pos) {
+  renderStat(node, pos) {
     const title = String(node.props.title || "Metric");
     const value = String(node.props.value || "0");
     const rawCaption = String(node.props.caption || "");
@@ -8424,7 +8531,9 @@ var SketchSVGRenderer = class extends SVGRenderer {
     const hasCaption = caption.trim().length > 0;
     const iconName = String(node.props.icon || "").trim();
     const iconSvg = iconName ? getIcon(iconName) : null;
-    const accentColor = this.resolveAccentColor();
+    const variant = String(node.props.variant || "default");
+    const baseAccent = this.resolveAccentColor();
+    const accentColor = variant !== "default" ? this.resolveVariantColor(variant, baseAccent) : baseAccent;
     const padding = this.resolveSpacing(node.style.padding);
     const innerX = pos.x + padding;
     const innerY = pos.y + padding;
@@ -8447,7 +8556,7 @@ var SketchSVGRenderer = class extends SVGRenderer {
     const visibleTitle = this.truncateTextToWidth(title, titleMaxWidth, titleSize);
     const visibleCaption = hasCaption ? this.truncateTextToWidth(caption, Math.max(20, pos.width - padding * 2), captionSize) : "";
     let svg = `<g${this.getDataNodeId(node)}>
-    <!-- StatCard Background -->
+    <!-- Stat Background -->
     <rect x="${pos.x}" y="${pos.y}"
           width="${pos.width}" height="${pos.height}"
           rx="8"

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;
@@ -661,7 +706,7 @@ declare class SVGRenderer {
     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 renderStat(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;
@@ -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;
@@ -847,9 +892,9 @@ declare class SkeletonSVGRenderer extends SVGRenderer {
      */
     protected renderTopbar(node: IRComponentNode, pos: any): string;
     /**
-     * Render StatCard with gray blocks instead of values
+     * Render Stat with gray blocks instead of values
      */
-    protected renderStatCard(node: IRComponentNode, pos: any): string;
+    protected renderStat(node: IRComponentNode, pos: any): string;
     /**
      * Render icon as gray square instead of hiding it
      */
@@ -992,7 +1037,7 @@ declare class SketchSVGRenderer extends SVGRenderer {
     /**
      * Render stat card with sketch filter and Comic Sans
      */
-    protected renderStatCard(node: IRComponentNode, pos: any): string;
+    protected renderStat(node: IRComponentNode, pos: any): string;
     /**
      * Render image with sketch filter
      */
@@ -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;
@@ -661,7 +706,7 @@ declare class SVGRenderer {
     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 renderStat(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;
@@ -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;
@@ -847,9 +892,9 @@ declare class SkeletonSVGRenderer extends SVGRenderer {
      */
     protected renderTopbar(node: IRComponentNode, pos: any): string;
     /**
-     * Render StatCard with gray blocks instead of values
+     * Render Stat with gray blocks instead of values
      */
-    protected renderStatCard(node: IRComponentNode, pos: any): string;
+    protected renderStat(node: IRComponentNode, pos: any): string;
     /**
      * Render icon as gray square instead of hiding it
      */
@@ -992,7 +1037,7 @@ declare class SketchSVGRenderer extends SVGRenderer {
     /**
      * Render stat card with sketch filter and Comic Sans
      */
-    protected renderStatCard(node: IRComponentNode, pos: any): string;
+    protected renderStat(node: IRComponentNode, pos: any): string;
     /**
      * Render image with sketch filter
      */
@@ -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",
@@ -2529,7 +2542,7 @@ ${messages}`);
       "Label",
       "Image",
       "Card",
-      "StatCard",
+      "Stat",
       "Topbar",
       "Table",
       "Chart",
@@ -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;
@@ -3623,7 +3685,7 @@ var LayoutEngine = class {
     if (node.componentType === "Textarea") return 100 + controlLabelOffset;
     if (node.componentType === "Modal") return 300;
     if (node.componentType === "Card") return 120;
-    if (node.componentType === "StatCard") return 120;
+    if (node.componentType === "Stat") return 120;
     if (node.componentType === "Chart" || node.componentType === "ChartPlaceholder") return 250;
     if (node.componentType === "List") {
       const itemsFromProps = String(node.props.items || "").split(",").map((item) => item.trim()).filter(Boolean);
@@ -3674,7 +3736,10 @@ var LayoutEngine = class {
       const density = this.style.density || "normal";
       const extraPadding = resolveControlHorizontalPadding(String(node.props.padding || "none"), density);
       const textWidth = this.estimateTextWidth(text, fontSize);
-      return Math.max(60, Math.ceil(textWidth + (paddingX + extraPadding) * 2));
+      const iconName = String(node.props.icon || "").trim();
+      const iconSize = iconName ? Math.round(fontSize * 1.1) : 0;
+      const iconGap = iconName ? 8 : 0;
+      return Math.max(60, Math.ceil(textWidth + iconSize + iconGap + (paddingX + extraPadding) * 2));
     }
     if (node.componentType === "Label" || node.componentType === "Text") {
       const text = String(node.props.text || "");
@@ -3705,7 +3770,7 @@ var LayoutEngine = class {
     if (node.componentType === "Table") {
       return 400;
     }
-    if (node.componentType === "StatCard" || node.componentType === "Card") {
+    if (node.componentType === "Stat" || node.componentType === "Card") {
       return 280;
     }
     if (node.componentType === "SidebarMenu") {
@@ -4571,7 +4636,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 +4737,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) {
@@ -4743,8 +4826,8 @@ var SVGRenderer = class {
         return this.renderModal(node, pos);
       case "List":
         return this.renderList(node, pos);
-      case "StatCard":
-        return this.renderStatCard(node, pos);
+      case "Stat":
+        return this.renderStat(node, pos);
       case "Image":
         return this.renderImage(node, pos);
       // Icon components
@@ -4790,6 +4873,7 @@ var SVGRenderer = class {
     const text = String(node.props.text || "Button");
     const variant = String(node.props.variant || "default");
     const size = String(node.props.size || "md");
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const density = this.ir.project.style.density || "normal";
     const extraPadding = resolveControlHorizontalPadding(String(node.props.padding || "none"), density);
     const labelOffset = this.parseBooleanProp(node.props.labelSpace, false) ? 18 : 0;
@@ -4835,7 +4919,7 @@ var SVGRenderer = class {
       textX = pos.x + buttonWidth / 2;
       textAnchor = "middle";
     }
-    let svg = `<g${this.getDataNodeId(node)}>
+    let svg = `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>
     <rect x="${pos.x}" y="${buttonY}"
           width="${buttonWidth}" height="${buttonHeight}"
           rx="${radius}"
@@ -4901,6 +4985,7 @@ var SVGRenderer = class {
     const placeholder = String(node.props.placeholder || "");
     const iconLeftName = String(node.props.iconLeft || "").trim();
     const iconRightName = String(node.props.iconRight || "").trim();
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const radius = this.tokens.input.radius;
     const fontSize = this.tokens.input.fontSize;
     const paddingX = this.tokens.input.paddingX;
@@ -4917,7 +5002,7 @@ var SVGRenderer = class {
     const textX = pos.x + (iconLeftSvg ? leftOffset : paddingX);
     const iconColor = this.hexToRgba(this.resolveMutedColor(), 0.8);
     const iconCenterY = controlY + (controlHeight - iconSize) / 2;
-    let svg = `<g${this.getDataNodeId(node)}>`;
+    let svg = `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>`;
     if (label) {
       svg += `
     <text x="${pos.x + paddingX}" y="${this.getControlLabelBaselineY(pos.y)}"
@@ -4968,7 +5053,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 +5192,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 +5255,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);
@@ -5540,6 +5640,7 @@ var SVGRenderer = class {
     const placeholder = String(node.props.placeholder || "Select...");
     const iconLeftName = String(node.props.iconLeft || "").trim();
     const iconRightName = String(node.props.iconRight || "").trim();
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const labelOffset = this.getControlLabelOffset(label);
     const controlY = pos.y + labelOffset;
     const controlHeight = Math.max(16, pos.height - labelOffset);
@@ -5553,7 +5654,7 @@ var SVGRenderer = class {
     const chevronWidth = 20;
     const iconColor = this.hexToRgba(this.resolveMutedColor(), 0.8);
     const iconCenterY = controlY + (controlHeight - iconSize) / 2;
-    let svg = `<g${this.getDataNodeId(node)}>`;
+    let svg = `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>`;
     if (label) {
       svg += `
     <text x="${pos.x}" y="${this.getControlLabelBaselineY(pos.y)}"
@@ -5602,10 +5703,11 @@ var SVGRenderer = class {
   renderCheckbox(node, pos) {
     const label = String(node.props.label || "Checkbox");
     const checked = String(node.props.checked || "false").toLowerCase() === "true";
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const controlColor = this.resolveControlColor();
     const checkboxSize = 18;
     const checkboxY = pos.y + pos.height / 2 - checkboxSize / 2;
-    return `<g${this.getDataNodeId(node)}>
+    return `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>
     <rect x="${pos.x}" y="${checkboxY}" 
           width="${checkboxSize}" height="${checkboxSize}" 
           rx="4" 
@@ -5626,10 +5728,11 @@ var SVGRenderer = class {
   renderRadio(node, pos) {
     const label = String(node.props.label || "Radio");
     const checked = String(node.props.checked || "false").toLowerCase() === "true";
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const controlColor = this.resolveControlColor();
     const radioSize = 16;
     const radioY = pos.y + pos.height / 2 - radioSize / 2;
-    return `<g${this.getDataNodeId(node)}>
+    return `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>
     <circle cx="${pos.x + radioSize / 2}" cy="${radioY + radioSize / 2}" 
             r="${radioSize / 2}" 
             fill="${this.renderTheme.cardBg}" 
@@ -5647,11 +5750,12 @@ var SVGRenderer = class {
   renderToggle(node, pos) {
     const label = String(node.props.label || "Toggle");
     const enabled = String(node.props.enabled || "false").toLowerCase() === "true";
+    const disabled = this.parseBooleanProp(node.props.disabled, false);
     const controlColor = this.resolveControlColor();
     const toggleWidth = 40;
     const toggleHeight = 20;
     const toggleY = pos.y + pos.height / 2 - toggleHeight / 2;
-    return `<g${this.getDataNodeId(node)}>
+    return `<g${this.getDataNodeId(node)}${disabled ? ' opacity="0.45"' : ""}>
     <rect x="${pos.x}" y="${toggleY}" 
           width="${toggleWidth}" height="${toggleHeight}" 
           rx="10" 
@@ -5947,7 +6051,7 @@ var SVGRenderer = class {
           text-anchor="middle">${node.componentType}</text>
   </g>`;
   }
-  renderStatCard(node, pos) {
+  renderStat(node, pos) {
     const title = String(node.props.title || "Metric");
     const value = String(node.props.value || "0");
     const rawCaption = String(node.props.caption || "");
@@ -5955,7 +6059,9 @@ var SVGRenderer = class {
     const hasCaption = caption.trim().length > 0;
     const iconName = String(node.props.icon || "").trim();
     const iconSvg = iconName ? getIcon(iconName) : null;
-    const accentColor = this.resolveAccentColor();
+    const variant = String(node.props.variant || "default");
+    const baseAccent = this.resolveAccentColor();
+    const accentColor = variant !== "default" ? this.resolveVariantColor(variant, baseAccent) : baseAccent;
     const padding = this.resolveSpacing(node.style.padding) || 16;
     const innerX = pos.x + padding;
     const innerY = pos.y + padding;
@@ -5979,7 +6085,7 @@ var SVGRenderer = class {
     const visibleTitle = this.truncateTextToWidth(title, titleMaxWidth, titleSize);
     const visibleCaption = hasCaption ? this.truncateTextToWidth(caption, Math.max(20, innerWidth), captionSize) : "";
     let svg = `<g${this.getDataNodeId(node)}>
-    <!-- StatCard Background -->
+    <!-- Stat Background -->
     <rect x="${pos.x}" y="${pos.y}" 
           width="${pos.width}" height="${pos.height}" 
           rx="8" 
@@ -6622,10 +6728,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 +7167,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 +7282,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,
@@ -7241,9 +7348,9 @@ var SkeletonSVGRenderer = class extends SVGRenderer {
     return svg;
   }
   /**
-   * Render StatCard with gray blocks instead of values
+   * Render Stat with gray blocks instead of values
    */
-  renderStatCard(node, pos) {
+  renderStat(node, pos) {
     const hasIcon = String(node.props.icon || "").trim().length > 0;
     const hasCaption = String(node.props.caption || "").trim().length > 0;
     const iconSize = 20;
@@ -8370,7 +8477,7 @@ var SketchSVGRenderer = class extends SVGRenderer {
   /**
    * Render stat card with sketch filter and Comic Sans
    */
-  renderStatCard(node, pos) {
+  renderStat(node, pos) {
     const title = String(node.props.title || "Metric");
     const value = String(node.props.value || "0");
     const rawCaption = String(node.props.caption || "");
@@ -8378,7 +8485,9 @@ var SketchSVGRenderer = class extends SVGRenderer {
     const hasCaption = caption.trim().length > 0;
     const iconName = String(node.props.icon || "").trim();
     const iconSvg = iconName ? getIcon(iconName) : null;
-    const accentColor = this.resolveAccentColor();
+    const variant = String(node.props.variant || "default");
+    const baseAccent = this.resolveAccentColor();
+    const accentColor = variant !== "default" ? this.resolveVariantColor(variant, baseAccent) : baseAccent;
     const padding = this.resolveSpacing(node.style.padding);
     const innerX = pos.x + padding;
     const innerY = pos.y + padding;
@@ -8401,7 +8510,7 @@ var SketchSVGRenderer = class extends SVGRenderer {
     const visibleTitle = this.truncateTextToWidth(title, titleMaxWidth, titleSize);
     const visibleCaption = hasCaption ? this.truncateTextToWidth(caption, Math.max(20, pos.width - padding * 2), captionSize) : "";
     let svg = `<g${this.getDataNodeId(node)}>
-    <!-- StatCard Background -->
+    <!-- Stat Background -->
     <rect x="${pos.x}" y="${pos.y}"
           width="${pos.width}" height="${pos.height}"
           rx="8"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wire-dsl/engine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "WireDSL engine - Parser, IR generator, layout engine, and SVG renderer (browser-safe, pure JS/TS)",
   "type": "module",
   "exports": {
@@ -32,7 +32,7 @@
   "dependencies": {
     "chevrotain": "11.1.1",
     "zod": "4.3.6",
-    "@wire-dsl/language-support": "0.4.0"
+    "@wire-dsl/language-support": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "25.2.0",