feat(FN-2221): constrain setup wizard modal shell and add CSS regression test

- Add display:flex and flex-direction:column to .setup-wizard-modal for scroll containment
- Ensure .setup-wizard-content has flex:1, min-height:0, overflow-y:auto for internal scrolling
- Protect header/footer with flex-shrink:0 to prevent collapse
- Add regression test coverage for viewport-safe layout contract
- Preserve mobile full-screen modal behavior

packages/dashboard/app/__tests__/setup-wizard-modal-layout.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "fs";
+import { resolve } from "path";
+
+const css = readFileSync(resolve(__dirname, "../styles.css"), "utf-8");
+
+describe("setup-wizard-modal-layout (FN-2221)", () => {
+  /**
+   * Finds all CSS rule blocks for a given selector, returning their positions.
+   * Works by scanning for the selector and matching balanced braces.
+   */
+  function findAllRuleBlocks(
+    source: string,
+    selector: string
+  ): Array<{ start: number; end: number; block: string; inMediaQuery: boolean }> {
+    const results: Array<{
+      start: number;
+      end: number;
+      block: string;
+      inMediaQuery: boolean;
+    }> = [];
+    const escapedSelector = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(escapedSelector + "\\s*\\{", "g");
+
+    let match;
+    while ((match = regex.exec(source)) !== null) {
+      const start = match.index;
+      const braceStart = start + match[0].length;
+
+      // Find matching closing brace
+      let depth = 1;
+      let pos = braceStart;
+      while (pos < source.length && depth > 0) {
+        if (source[pos] === "{") depth++;
+        else if (source[pos] === "}") depth--;
+        pos++;
+      }
+
+      const end = pos;
+      const block = source.slice(start, end);
+
+      // Check if this rule is inside a media query
+      // Search backwards for the nearest @media
+      let before = source.slice(0, start);
+      const lastMediaQuery = before.lastIndexOf("@media");
+      let inMediaQuery = false;
+      if (lastMediaQuery !== -1) {
+        // Check if there's a closing brace between the @media and this rule
+        const afterMedia = before.slice(lastMediaQuery);
+        const openBraces = (afterMedia.match(/\{/g) || []).length;
+        const closeBraces = (afterMedia.match(/\}/g) || []).length;
+        inMediaQuery = openBraces > closeBraces;
+      }
+
+      results.push({ start, end, block, inMediaQuery });
+    }
+
+    return results;
+  }
+
+  describe("modal shell constraints (.setup-wizard-modal)", () => {
+    it("base rule establishes flex context with display: flex and flex-direction: column", () => {
+      const rules = findAllRuleBlocks(css, ".setup-wizard-modal");
+      // Find the base rule (not in media query)
+      const baseRules = rules.filter((r) => !r.inMediaQuery);
+      expect(baseRules.length).toBeGreaterThan(0);
+
+      const rule = baseRules[0].block;
+      expect(rule).toContain("display: flex");
+      expect(rule).toContain("flex-direction: column");
+    });
+
+    it("has viewport-bounded max-height to prevent off-screen rendering", () => {
+      const rules = findAllRuleBlocks(css, ".setup-wizard-modal");
+      const baseRules = rules.filter((r) => !r.inMediaQuery);
+      expect(baseRules.length).toBeGreaterThan(0);
+
+      const rule = baseRules[0].block;
+      // Should use viewport-relative max-height (calc with 100dvh or similar)
+      expect(rule).toMatch(/max-height:.*100dvh/i);
+    });
+
+    it("has overflow: hidden to contain scrollable content", () => {
+      const rules = findAllRuleBlocks(css, ".setup-wizard-modal");
+      const baseRules = rules.filter((r) => !r.inMediaQuery);
+      expect(baseRules.length).toBeGreaterThan(0);
+
+      const rule = baseRules[0].block;
+      expect(rule).toContain("overflow: hidden");
+    });
+
+    it("mobile version also establishes flex context", () => {
+      const rules = findAllRuleBlocks(css, ".setup-wizard-modal");
+      // Find the mobile rule (in media query)
+      const mobileRules = rules.filter((r) => r.inMediaQuery);
+      expect(mobileRules.length).toBeGreaterThan(0);
+
+      // Find the setup wizard mobile rule by checking it contains viewport-bounded max-height
+      const setupWizardMobile = mobileRules.find((r) =>
+        r.block.includes("100dvh")
+      );
+      expect(setupWizardMobile).toBeDefined();
+      expect(setupWizardMobile!.block).toContain("display: flex");
+      expect(setupWizardMobile!.block).toContain("flex-direction: column");
+    });
+  });
+
+  describe("internal content scrolling (.setup-wizard-content)", () => {
+    it("is a shrinkable scroll region with flex: 1 and min-height: 0", () => {
+      const rules = findAllRuleBlocks(css, ".setup-wizard-content");
+      const baseRules = rules.filter((r) => !r.inMediaQuery);
+      expect(baseRules.length).toBeGreaterThan(0);
+
+      const rule = baseRules[0].block;
+      expect(rule).toContain("flex: 1");
+      expect(rule).toContain("min-height: 0");
+    });
+
+    it("has overflow-y: auto for internal scrolling", () => {
+      const rules = findAllRuleBlocks(css, ".setup-wizard-content");
+      const baseRules = rules.filter((r) => !r.inMediaQuery);
+      expect(baseRules.length).toBeGreaterThan(0);
+
+      const rule = baseRules[0].block;
+      expect(rule).toContain("overflow-y: auto");
+    });
+  });
+
+  describe("non-collapsing footer (.setup-wizard-footer)", () => {
+    it("has flex-shrink: 0 to prevent footer collapse", () => {
+      const rules = findAllRuleBlocks(css, ".setup-wizard-footer");
+      const baseRules = rules.filter((r) => !r.inMediaQuery);
+      expect(baseRules.length).toBeGreaterThan(0);
+
+      const rule = baseRules[0].block;
+      expect(rule).toContain("flex-shrink: 0");
+    });
+  });
+
+  describe("non-collapsing header (.setup-wizard-header)", () => {
+    it("has flex-shrink: 0 to prevent header collapse", () => {
+      const rules = findAllRuleBlocks(css, ".setup-wizard-header");
+      const baseRules = rules.filter((r) => !r.inMediaQuery);
+      expect(baseRules.length).toBeGreaterThan(0);
+
+      const rule = baseRules[0].block;
+      expect(rule).toContain("flex-shrink: 0");
+    });
+  });
+});

packages/dashboard/app/styles.css

@@ -21405,6 +21405,8 @@ html .column.drag-over * {
 
 /* === Setup Wizard Modal (Onboarding) === */
 .setup-wizard-modal {
+  display: flex;
+  flex-direction: column;
   max-width: 540px;
   width: 100%;
   max-height: min(720px, calc(100dvh - (var(--space-2xl) * 2)));
@@ -21731,6 +21733,8 @@ html .column.drag-over * {
   }
 
   .setup-wizard-modal {
+    display: flex;
+    flex-direction: column;
     max-width: 100%;
     width: 100%;
     max-height: calc(100dvh - max(var(--space-2xl), env(safe-area-inset-top, 0px)) - max(var(--space-2xl), env(safe-area-inset-bottom, 0px)));