@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/tools/phase2-accuracy/layout-intelligence/index.ts

@@ -0,0 +1,663 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Layout Intelligence
+// Analyses a Figma node's container type and recommends (or applies) optimal
+// Auto-Layout settings drawn from a built-in container → settings lookup table.
+// All spacing values are snapped to the nearest spacing token.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { getBridge } from "../../../shared/figma-bridge.js";
+import { decisionLog } from "../../../shared/decision-log.js";
+import { snapToSpacingToken } from "../../../shared/token-utils.js";
+import { FigmaNode } from "../../../shared/types.js";
+import { generateValidatorScript, generateDocumentRepairScript, generateDocumentRepairCall } from "../../../shared/auto-layout-validator.js";
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+export interface LayoutIntelligenceArgs {
+  nodeId: string;
+  applyChanges: boolean;
+  spacingTokenSet?: string;
+  responsiveHints?: boolean;
+  reportDiff?: boolean;
+  recursive?: boolean;
+}
+
+export type ContainerKind =
+  | "navigation bar"
+  | "card"
+  | "form"
+  | "button"
+  | "grid"
+  | "list item"
+  | "modal"
+  | "section"
+  | "document_page"
+  | "header_block"
+  | "section_block"
+  | "toc_row"
+  | "paragraph_group"
+  | "divider"
+  | "footer_block"
+  | "table_block";
+
+export interface AutoLayoutSpec {
+  direction: "HORIZONTAL" | "VERTICAL" | "WRAP";
+  primaryAxisSizingMode: "FIXED" | "AUTO";  // width
+  counterAxisSizingMode: "FIXED" | "AUTO";  // height
+  paddingToken: string;
+  gapToken: string;
+  paddingValue: number;   // resolved px
+  gapValue: number;       // resolved px
+}
+
+export interface PropertyDiff {
+  property: string;
+  before: string | number | undefined;
+  after: string | number;
+  tokenName?: string;
+}
+
+export interface LayoutIntelligenceResult {
+  nodeId: string;
+  nodeName: string;
+  detectedKind: ContainerKind | "unknown";
+  spec: AutoLayoutSpec;
+  diff: PropertyDiff[];
+  applied: boolean;
+  responsiveHints?: string[];
+  logEntryId: string;
+  validationFixes?: number;
+}
+
+// ─── Spacing token name → px value ───────────────────────────────────────────
+
+const SPACE: Record<string, number> = {
+  "--space-xs":  4,
+  "--space-sm":  8,
+  "--space-md":  16,
+  "--space-lg":  24,
+  "--space-xl":  32,
+  "--space-2xl": 48,
+  "--space-3xl": 56,
+  "--space-4xl": 64,
+};
+
+// ─── Container → Auto-Layout mapping table ────────────────────────────────────
+// direction          / primaryAxis (W) / counterAxis (H) / padding token    / gap token
+
+const CONTAINER_SPECS: Record<ContainerKind, AutoLayoutSpec> = {
+  "navigation bar": {
+    direction: "HORIZONTAL",
+    primaryAxisSizingMode: "AUTO",   // Fill W
+    counterAxisSizingMode: "AUTO",   // Hug H
+    paddingToken: "--space-md",
+    gapToken: "--space-md",
+    paddingValue: SPACE["--space-md"],
+    gapValue: SPACE["--space-md"],
+  },
+  card: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",   // Fill W
+    counterAxisSizingMode: "AUTO",   // Hug H
+    paddingToken: "--space-lg",
+    gapToken: "--space-lg",
+    paddingValue: SPACE["--space-lg"],
+    gapValue: SPACE["--space-lg"],
+  },
+  form: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-md",
+    gapToken: "--space-md",
+    paddingValue: SPACE["--space-md"],
+    gapValue: SPACE["--space-md"],
+  },
+  button: {
+    direction: "HORIZONTAL",
+    primaryAxisSizingMode: "AUTO",   // Hug W
+    counterAxisSizingMode: "AUTO",   // Hug H
+    paddingToken: "--space-sm",
+    gapToken: "--space-sm",
+    paddingValue: SPACE["--space-sm"],
+    gapValue: SPACE["--space-sm"],
+  },
+  grid: {
+    direction: "WRAP",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-md",
+    gapToken: "--space-md",
+    paddingValue: SPACE["--space-md"],
+    gapValue: SPACE["--space-md"],
+  },
+  "list item": {
+    direction: "HORIZONTAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-sm",
+    gapToken: "--space-sm",
+    paddingValue: SPACE["--space-sm"],
+    gapValue: SPACE["--space-sm"],
+  },
+  modal: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "FIXED",  // Fixed W
+    counterAxisSizingMode: "AUTO",   // Hug H
+    paddingToken: "--space-xl",
+    gapToken: "--space-xl",
+    paddingValue: SPACE["--space-xl"],
+    gapValue: SPACE["--space-xl"],
+  },
+  section: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-2xl",
+    gapToken: "--space-2xl",
+    paddingValue: SPACE["--space-2xl"],
+    gapValue: SPACE["--space-2xl"],
+  },
+
+  // ─── Document layout primitives ───────────────────────────────────────────
+  document_page: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",    // Hug H (page grows with content)
+    counterAxisSizingMode: "FIXED",   // Fixed W (document width)
+    paddingToken: "--space-3xl",
+    gapToken: "--space-2xl",
+    paddingValue: SPACE["--space-3xl"],
+    gapValue: SPACE["--space-2xl"],
+  },
+  header_block: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-xs",
+    gapToken: "--space-sm",
+    paddingValue: 0,
+    gapValue: SPACE["--space-sm"],
+  },
+  section_block: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-xs",
+    gapToken: "--space-lg",
+    paddingValue: 0,
+    gapValue: SPACE["--space-lg"],
+  },
+  toc_row: {
+    direction: "HORIZONTAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-xs",
+    gapToken: "--space-sm",
+    paddingValue: 0,
+    gapValue: SPACE["--space-sm"],
+  },
+  paragraph_group: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-xs",
+    gapToken: "--space-sm",
+    paddingValue: 0,
+    gapValue: SPACE["--space-sm"],
+  },
+  divider: {
+    direction: "HORIZONTAL",
+    primaryAxisSizingMode: "FIXED",
+    counterAxisSizingMode: "FIXED",
+    paddingToken: "--space-xs",
+    gapToken: "--space-xs",
+    paddingValue: 0,
+    gapValue: 0,
+  },
+  footer_block: {
+    direction: "HORIZONTAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-xs",
+    gapToken: "--space-md",
+    paddingValue: 0,
+    gapValue: SPACE["--space-md"],
+  },
+  table_block: {
+    direction: "VERTICAL",
+    primaryAxisSizingMode: "AUTO",
+    counterAxisSizingMode: "AUTO",
+    paddingToken: "--space-xs",
+    gapToken: "--space-xs",
+    paddingValue: 0,
+    gapValue: 0,
+  },
+};
+
+// ─── Container-kind detection heuristics ─────────────────────────────────────
+
+function detectContainerKind(node: FigmaNode): ContainerKind | "unknown" {
+  const name = node.name.toLowerCase();
+  const childCount = node.children?.length ?? 0;
+  const w = node.absoluteBoundingBox?.width ?? 0;
+  const h = node.absoluteBoundingBox?.height ?? 0;
+  const aspectRatio = h > 0 ? w / h : 1;
+
+  // Document layout primitives (highest priority — checked first)
+  if (/doc(ument)?[\s_-]?page|spec[\s_-]?page|guide(line)?[\s_-]?page/.test(name)) return "document_page";
+  if (/header[\s_-]?block|doc[\s_-]?header|page[\s_-]?title[\s_-]?block/.test(name)) return "header_block";
+  if (/section[\s_-]?block|content[\s_-]?section/.test(name)) return "section_block";
+  if (/toc[\s_-]?row|table[\s_-]?of[\s_-]?contents/.test(name)) return "toc_row";
+  if (/paragraph[\s_-]?group|body[\s_-]?text[\s_-]?block|text[\s_-]?block/.test(name)) return "paragraph_group";
+  if (/\bdivider\b|\bseparator\b|\bhr\b/.test(name)) return "divider";
+  if (/footer[\s_-]?block|doc[\s_-]?footer/.test(name)) return "footer_block";
+  if (/table[\s_-]?block|spec[\s_-]?table|data[\s_-]?table/.test(name)) return "table_block";
+
+  // Name-based detection for UI containers
+  if (/nav(igation)?\s*(bar)?|navbar|top\s*bar|header\s*bar/.test(name)) return "navigation bar";
+  if (/\bmodal\b|\bdialog\b|\bdrawer\b|\bpopup\b/.test(name)) return "modal";
+  if (/\bcard\b|\btile\b|\bpanel\b/.test(name)) return "card";
+  if (/\bform\b|\binput\s*group\b/.test(name)) return "form";
+  if (/\bbtn\b|\bbutton\b|\bcta\b/.test(name)) return "button";
+  if (/\bgrid\b|\bmasonry\b|\bgallery\b/.test(name)) return "grid";
+  if (/\blist\s*item\b|\brow\b|\bcell\b/.test(name)) return "list item";
+  if (/\bsection\b|\bhero\b|\bfooter\b|\bpage\b/.test(name)) return "section";
+
+  // Geometry-based fallback: document page (wide, vertical, many children)
+  if (w >= 1000 && w <= 1400 && node.layoutMode === "VERTICAL" && childCount > 5) return "document_page";
+
+  // Geometry-based fallback for UI containers
+  if (w > 0 && h <= 80 && aspectRatio > 5) return "navigation bar";       // very wide & short
+  if (w <= 120 && h <= 60 && childCount <= 3) return "button";             // small & few children
+  if (childCount > 6 && node.layoutMode === "NONE") return "grid";         // many children, no layout
+  if (h > 300 && w < 600 && childCount > 2) return "modal";               // tall-ish popup sized box
+  if (childCount > 0 && node.layoutMode === "VERTICAL") return "card";
+  if (aspectRatio > 4 && childCount <= 5) return "list item";
+
+  return "unknown";
+}
+
+// ─── Diff builder ─────────────────────────────────────────────────────────────
+
+function buildDiff(node: FigmaNode, spec: AutoLayoutSpec): PropertyDiff[] {
+  const diffs: PropertyDiff[] = [];
+
+  const currentLayoutMode = node.layoutMode ?? "NONE";
+  const targetLayoutMode = spec.direction === "WRAP" ? "HORIZONTAL" : spec.direction;
+
+  if (currentLayoutMode !== targetLayoutMode) {
+    diffs.push({ property: "layoutMode", before: currentLayoutMode, after: targetLayoutMode });
+  }
+
+  // WRAP is represented via layoutWrap which we handle separately
+  if (spec.direction === "WRAP") {
+    diffs.push({ property: "layoutWrap", before: "NO_WRAP", after: "WRAP" });
+  }
+
+  const spacingFields: Array<keyof FigmaNode> = [
+    "paddingLeft",
+    "paddingRight",
+    "paddingTop",
+    "paddingBottom",
+  ];
+
+  for (const field of spacingFields) {
+    const current = node[field] as number | undefined;
+    const snapped = snapToSpacingToken(spec.paddingValue);
+    if (current !== snapped.tokenValue) {
+      diffs.push({
+        property: field,
+        before: current,
+        after: snapped.tokenValue,
+        tokenName: snapped.tokenName,
+      });
+    }
+  }
+
+  const currentGap = node.itemSpacing ?? 0;
+  const snappedGap = snapToSpacingToken(spec.gapValue);
+  if (currentGap !== snappedGap.tokenValue) {
+    diffs.push({
+      property: "itemSpacing",
+      before: currentGap,
+      after: snappedGap.tokenValue,
+      tokenName: snappedGap.tokenName,
+    });
+  }
+
+  if (node.primaryAxisSizingMode !== spec.primaryAxisSizingMode) {
+    diffs.push({
+      property: "primaryAxisSizingMode",
+      before: node.primaryAxisSizingMode,
+      after: spec.primaryAxisSizingMode,
+    });
+  }
+
+  if (node.counterAxisSizingMode !== spec.counterAxisSizingMode) {
+    diffs.push({
+      property: "counterAxisSizingMode",
+      before: node.counterAxisSizingMode,
+      after: spec.counterAxisSizingMode,
+    });
+  }
+
+  return diffs;
+}
+
+// ─── Figma script builder ─────────────────────────────────────────────────────
+
+function buildApplyScript(nodeId: string, spec: AutoLayoutSpec, paddingPx: number, gapPx: number): string {
+  const layoutMode = spec.direction === "WRAP" ? "HORIZONTAL" : spec.direction;
+  const wrapLine = spec.direction === "WRAP"
+    ? `node.layoutWrap = 'WRAP';`
+    : `node.layoutWrap = 'NO_WRAP';`;
+
+  return `
+    const node = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
+    if (!node) throw new Error('Node not found: ${nodeId}');
+    if (!('layoutMode' in node)) throw new Error('Node does not support Auto Layout');
+    node.layoutMode = ${JSON.stringify(layoutMode)};
+    ${wrapLine}
+    node.primaryAxisSizingMode = ${JSON.stringify(spec.primaryAxisSizingMode)};
+    node.counterAxisSizingMode = ${JSON.stringify(spec.counterAxisSizingMode)};
+    node.paddingLeft   = ${paddingPx};
+    node.paddingRight  = ${paddingPx};
+    node.paddingTop    = ${paddingPx};
+    node.paddingBottom = ${paddingPx};
+    node.itemSpacing   = ${gapPx};
+
+    // ── Deep recursive FILL enforcement ──
+    function isAL(n) { return n.layoutMode === 'HORIZONTAL' || n.layoutMode === 'VERTICAL'; }
+    function isDocContainer(name) {
+      return /section|header|footer|table|paragraph|toc|block|overview|anatomy|content|divider/i.test(name);
+    }
+    function enforceChildFill(parent, depth) {
+      if (depth > 20 || !('children' in parent)) return;
+      const dir = parent.layoutMode;
+      const parentIsAL = isAL(parent);
+      if (!parentIsAL) return;
+
+      for (const child of parent.children) {
+        if (!('layoutAlign' in child)) continue;
+        const cName = (child.name || '').toLowerCase();
+        const cType = child.type;
+
+        // Skip small fixed elements (icons ≤48px) unless they're semantic containers
+        const isSmallFixed = child.width && child.height && child.width <= 48 && child.height <= 48;
+        if (isSmallFixed && !isDocContainer(cName) &&
+            !/input|field|button|btn|bar|card|container|wrapper|form/.test(cName)) {
+          continue;
+        }
+
+        if (dir === 'VERTICAL') {
+          // VERTICAL parent → children fill width
+          if (cType === 'FRAME' || cType === 'COMPONENT' || cType === 'INSTANCE' ||
+              cType === 'RECTANGLE' || cType === 'GROUP' || cType === 'TEXT') {
+            child.layoutAlign = 'STRETCH';
+            if ('layoutSizingHorizontal' in child) child.layoutSizingHorizontal = 'FILL';
+          }
+        } else if (dir === 'HORIZONTAL') {
+          // HORIZONTAL parent → grow content children, fill height on frames
+          if (cType === 'FRAME' || cType === 'COMPONENT' || cType === 'INSTANCE') {
+            if (/input|field|search|content|main|body|spacer/.test(cName) || isDocContainer(cName)) {
+              child.layoutGrow = 1;
+            }
+          }
+        }
+
+        // Recurse into child frames
+        if ('children' in child && isAL(child)) {
+          enforceChildFill(child, depth + 1);
+        }
+      }
+    }
+    enforceChildFill(node, 0);
+
+    return { success: true };
+  `.trim();
+}
+
+// ─── Responsive hints ─────────────────────────────────────────────────────────
+
+function generateResponsiveHints(kind: ContainerKind | "unknown", spec: AutoLayoutSpec): string[] {
+  const hints: string[] = [];
+
+  if (kind === "navigation bar") {
+    hints.push("On mobile (<768px): switch to VERTICAL and collapse secondary items into a hamburger menu.");
+    hints.push("Ensure flex-shrink is applied to label text so icons stay visible at small widths.");
+  } else if (kind === "card") {
+    hints.push("In a responsive grid, let cards stretch to Fill-W; avoid Fixed widths.");
+    hints.push("Increase padding to --space-xl on desktop for breathing room.");
+  } else if (kind === "modal") {
+    hints.push("On mobile: set width to Fill-W and reduce padding to --space-md.");
+    hints.push("Use max-height: 90vh with scrollable content area to prevent overflow.");
+  } else if (kind === "grid") {
+    hints.push("Use Constraints → Scale on children so grid items resize proportionally.");
+    hints.push("Reduce gap to --space-sm on mobile breakpoints.");
+  } else if (kind === "form") {
+    hints.push("Stack label + input vertically on mobile; use horizontal layout on desktop.");
+  } else if (kind === "section") {
+    hints.push("Reduce padding from --space-2xl to --space-xl on tablet and --space-lg on mobile.");
+  } else if (kind === "document_page") {
+    hints.push("On mobile: reduce page width to 100vw, padding to --space-lg, section gap to --space-xl.");
+    hints.push("Consider collapsible TOC on narrow viewports.");
+  } else if (kind === "section_block" || kind === "paragraph_group") {
+    hints.push("Keep FILL width at all breakpoints for readable line lengths.");
+  }
+
+  if (spec.direction === "HORIZONTAL") {
+    hints.push("If children need to wrap at narrow viewports, enable layoutWrap = WRAP.");
+  }
+
+  return hints;
+}
+
+// ─── Document container kinds (used to auto-enable recursive validation) ─────
+
+const DOCUMENT_KINDS: Set<ContainerKind | "unknown"> = new Set([
+  "document_page", "header_block", "section_block", "toc_row",
+  "paragraph_group", "divider", "footer_block", "table_block",
+]);
+
+function isDocumentKind(kind: ContainerKind | "unknown"): boolean {
+  return DOCUMENT_KINDS.has(kind);
+}
+
+// ─── Recursive spec application for nested document containers ───────────────
+
+function buildRecursiveSpecScript(nodeId: string): string {
+  // Serialize the detection patterns and specs as inline JS so they run inside
+  // the Figma Plugin API context (bridge.execute).
+  return `
+(async () => {
+  const root = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
+  if (!root) throw new Error('Node not found');
+
+  const SPECS = {
+    document_page:   { dir: 'VERTICAL',   pw: 'AUTO',  cw: 'FIXED', pad: 56, gap: 48 },
+    header_block:    { dir: 'VERTICAL',   pw: 'AUTO',  cw: 'AUTO',  pad: 0,  gap: 8  },
+    section_block:   { dir: 'VERTICAL',   pw: 'AUTO',  cw: 'AUTO',  pad: 0,  gap: 24 },
+    toc_row:         { dir: 'HORIZONTAL', pw: 'AUTO',  cw: 'AUTO',  pad: 0,  gap: 8  },
+    paragraph_group: { dir: 'VERTICAL',   pw: 'AUTO',  cw: 'AUTO',  pad: 0,  gap: 8  },
+    divider:         { dir: 'HORIZONTAL', pw: 'FIXED', cw: 'FIXED', pad: 0,  gap: 0  },
+    footer_block:    { dir: 'HORIZONTAL', pw: 'AUTO',  cw: 'AUTO',  pad: 0,  gap: 16 },
+    table_block:     { dir: 'VERTICAL',   pw: 'AUTO',  cw: 'AUTO',  pad: 0,  gap: 0  },
+  };
+
+  const DETECT = [
+    [/doc(ument)?[\\s_-]?page|spec[\\s_-]?page|guide(line)?[\\s_-]?page/i, 'document_page'],
+    [/header[\\s_-]?block|doc[\\s_-]?header|page[\\s_-]?title[\\s_-]?block/i, 'header_block'],
+    [/section[\\s_-]?block|content[\\s_-]?section/i, 'section_block'],
+    [/toc[\\s_-]?row|table[\\s_-]?of[\\s_-]?contents/i, 'toc_row'],
+    [/paragraph[\\s_-]?group|body[\\s_-]?text[\\s_-]?block|text[\\s_-]?block/i, 'paragraph_group'],
+    [/\\bdivider\\b|\\bseparator\\b|\\bhr\\b/i, 'divider'],
+    [/footer[\\s_-]?block|doc[\\s_-]?footer/i, 'footer_block'],
+    [/table[\\s_-]?block|spec[\\s_-]?table|data[\\s_-]?table/i, 'table_block'],
+  ];
+
+  function detectKind(node) {
+    const n = (node.name || '').toLowerCase();
+    for (const [re, kind] of DETECT) {
+      if (re.test(n)) return kind;
+    }
+    return null;
+  }
+
+  function isAL(n) { return n.layoutMode === 'HORIZONTAL' || n.layoutMode === 'VERTICAL'; }
+
+  let applied = 0;
+
+  function applySpec(node, spec) {
+    if (!('layoutMode' in node)) return;
+    node.layoutMode = spec.dir;
+    node.layoutWrap = 'NO_WRAP';
+    node.primaryAxisSizingMode = spec.pw;
+    node.counterAxisSizingMode = spec.cw;
+    node.paddingLeft = spec.pad;
+    node.paddingRight = spec.pad;
+    node.paddingTop = spec.pad;
+    node.paddingBottom = spec.pad;
+    node.itemSpacing = spec.gap;
+    applied++;
+  }
+
+  function walkAndApply(node, depth) {
+    if (depth > 20 || !('children' in node)) return;
+    for (const child of node.children) {
+      const kind = detectKind(child);
+      if (kind && SPECS[kind]) {
+        applySpec(child, SPECS[kind]);
+      }
+
+      // Enforce FILL on children of VERTICAL auto-layout containers
+      if (isAL(node) && node.layoutMode === 'VERTICAL' && 'layoutAlign' in child) {
+        const cType = child.type;
+        if (cType === 'FRAME' || cType === 'COMPONENT' || cType === 'INSTANCE' ||
+            cType === 'RECTANGLE' || cType === 'GROUP' || cType === 'TEXT') {
+          // Skip small icons
+          const isSmall = child.width && child.height && child.width <= 48 && child.height <= 48;
+          if (!isSmall) {
+            child.layoutAlign = 'STRETCH';
+            if ('layoutSizingHorizontal' in child) child.layoutSizingHorizontal = 'FILL';
+          }
+        }
+      }
+
+      walkAndApply(child, depth + 1);
+    }
+  }
+
+  // Don't re-apply to root (already done by buildApplyScript), only children
+  walkAndApply(root, 0);
+  return { applied: applied };
+})();
+  `.trim();
+}
+
+// ─── Main handler ─────────────────────────────────────────────────────────────
+
+export async function layoutIntelligenceHandler(
+  args: LayoutIntelligenceArgs
+): Promise<LayoutIntelligenceResult> {
+  const {
+    nodeId,
+    applyChanges,
+    spacingTokenSet,  // reserved for future token-set override
+    responsiveHints = false,
+    reportDiff = true,
+  } = args;
+
+  if (!nodeId) throw new Error("layoutIntelligence: `nodeId` is required.");
+
+  const bridge = await getBridge();
+
+  // 1. Fetch the node tree
+  const node = await bridge.getNode(nodeId);
+
+  // 2. Detect container type
+  const detectedKind = detectContainerKind(node);
+
+  // 3. Resolve spec (fall back to "card" for unknown containers)
+  const resolvedKind: ContainerKind = detectedKind === "unknown" ? "card" : detectedKind;
+  const spec = CONTAINER_SPECS[resolvedKind];
+
+  // Override spacing if spacingTokenSet is provided and matches a known token
+  if (spacingTokenSet && SPACE[spacingTokenSet] !== undefined) {
+    spec.paddingValue = SPACE[spacingTokenSet];
+    spec.paddingToken = spacingTokenSet;
+  }
+
+  // 4. Snap spacing values
+  const snappedPadding = snapToSpacingToken(spec.paddingValue);
+  const snappedGap = snapToSpacingToken(spec.gapValue);
+
+  // 5. Build diff
+  const diff = reportDiff ? buildDiff(node, spec) : [];
+
+  // 6. Apply if requested
+  let applied = false;
+  if (applyChanges) {
+    const script = buildApplyScript(nodeId, spec, snappedPadding.tokenValue as number, snappedGap.tokenValue as number);
+    const execResult = await bridge.execute(script);
+    if (!execResult.success) {
+      throw new Error(`layoutIntelligence: Failed to apply changes — ${execResult.error}`);
+    }
+    applied = true;
+
+    // 6b. For document containers: recursively apply specs to nested children
+    if (isDocumentKind(detectedKind)) {
+      const recursiveScript = buildRecursiveSpecScript(nodeId);
+      await bridge.execute(recursiveScript);
+    }
+  }
+
+  // 7. Log the decision
+  const logEntry = await decisionLog.log({
+    tool: "layout-intelligence",
+    nodeIds: [nodeId],
+    rationale: `Detected container kind "${detectedKind}" on node "${node.name}". Recommended spec: ${spec.direction}, padding=${snappedPadding.tokenName}, gap=${snappedGap.tokenName}. Applied: ${applied}. Diff properties changed: ${diff.length}.`,
+    tokens: [snappedPadding.tokenName, snappedGap.tokenName],
+    reversible: applied,
+    metadata: { detectedKind, resolvedKind, spec, diffCount: diff.length },
+  });
+
+  // 8. Auto-layout validation + document repair
+  //    Auto-enabled for document containers; also runs when recursive=true
+  const shouldValidate = args.recursive || isDocumentKind(detectedKind);
+  let validationFixes = 0;
+  if (shouldValidate && applied) {
+    const validatorScript = `
+(async () => {
+  ${generateValidatorScript()}
+  ${generateDocumentRepairScript()}
+  const node = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
+  if (!node) throw new Error('Node not found: ${nodeId}');
+  const valResult = validateAutoLayout(node);
+  ${generateDocumentRepairCall('node')}
+  const totalFixes = valResult.fixes + (_docRepair ? _docRepair.repairs : 0);
+  return { fixes: totalFixes, valDetails: valResult.details, repairDetails: _docRepair ? _docRepair.details : [] };
+})();
+    `.trim();
+    const valResult = await bridge.execute(validatorScript);
+    if (valResult.success && valResult.result) {
+      validationFixes = (valResult.result as { fixes: number }).fixes;
+    }
+  }
+
+  const result: LayoutIntelligenceResult = {
+    nodeId,
+    nodeName: node.name,
+    detectedKind,
+    spec,
+    diff,
+    applied,
+    logEntryId: logEntry.id,
+    ...(shouldValidate ? { validationFixes } : {}),
+  };
+
+  if (responsiveHints) {
+    result.responsiveHints = generateResponsiveHints(detectedKind, spec);
+  }
+
+  return result;
+}