@seybel/breakhound 1.0.4 → 1.0.6

package/README.md

@@ -78,10 +78,10 @@ npx @seybel/breakhound --url https://staging.example.com   # every route, on ano
 | Angular | your route definitions, from `src/main.ts` on, with lazily loaded `loadChildren` routes under their path |
 | Anything else | links followed from the home page (up to 50 pages, a few per section) |
 
-**Dynamic routes** like `/blog/[slug]` are scanned once, using a real link found on your pages (routes that share a template share a layout). Routes below one reuse its values: once `/cohorts/css-101` is found, `/cohorts/[slug]/settings` is scanned as `/cohorts/css-101/settings`. If something is still missing, it's listed with a hint naming the parameters. Give them a real value once, by name, and every route that uses them is filled in:
+**Dynamic routes** like `/blog/[slug]` are scanned once, using a real link found on your pages (routes that share a template share a layout). Routes below one reuse its values: once `/users/jane` is found, `/users/[username]/settings` is scanned as `/users/jane/settings`. If something is still missing, it's listed with a hint naming the parameters. Give them a real value once, by name, and every route that uses them is filled in:
 
 ```ts
-params: { slug: 'css-101', submissionId: '42' }
+params: { username: 'jane', orderId: '1001' }
 ```
 
 Or give one route its own URL, which wins over `params`:
@@ -159,7 +159,7 @@ The folder is for you, not your repo, so it keeps itself out of git: breakhound
 
 ## Chrome extension
 
-The breakhound extension runs the same checks on the tab you have open, with nothing to install in your project. Get it from the [Chrome Web Store](https://chromewebstore.google.com/detail/ddnmhnjmcokbfabeileblceehjhefkpc); it works on any page Chrome can open, from localhost to production. The quickest way in is to right-click the page and choose **Scan with breakhound**: the breakhound panel opens in Chrome's side panel and starts right away. Clicking the breakhound icon in the toolbar opens it ready to scan, and the same panel is a **breakhound** tab in DevTools. The page grows steadily from 320px to 1920px (or the widths you set) while the timeline fills in live: each run of widths that share a layout, every width where the layout changes, and where something breaks. Then you get:
+The breakhound extension runs the same checks on the tab you have open, with nothing to install in your project. Get it from the [Chrome Web Store](https://chromewebstore.google.com/detail/ddnmhnjmcokbfabeileblceehjhefkpc); it works on any page Chrome can open, from localhost to production. For a page opened from a file (`file://`), Chrome asks you to turn on **Allow access to file URLs** for breakhound once; the panel has a button that takes you there. The quickest way in is to right-click the page and choose **Scan with breakhound**: the breakhound panel opens in Chrome's side panel and starts right away. Clicking the breakhound icon in the toolbar opens it ready to scan, and the same panel is a **breakhound** tab in DevTools. The page grows steadily from 320px to 1920px (or the widths you set) while the timeline fills in live: each run of widths that share a layout, every width where the layout changes, and where something breaks. Then you get:
 
 - the issues, each with its exact width ranges, the element, the numbers and the likely fix
 - the timeline: the layout bands, the media query widths, the changes no media or container query explains, and a bar for each issue across the widths it covers

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { existsSync as existsSync16 } from "fs";
-import { join as join18, resolve as resolve7 } from "path";
+import { join as join19, resolve as resolve7 } from "path";
 import { parseArgs, styleText as styleText9 } from "util";
 
 // ../engine/src/index.ts
@@ -2107,11 +2107,12 @@ async function printPdf(html, file) {
 
 // src/auth.ts
 import { existsSync as existsSync7, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname4, join as join8 } from "path";
+import { dirname as dirname4, join as join9 } from "path";
 import { createInterface } from "readline";
 import { styleText as styleText3 } from "util";
 
 // src/app.ts
+import { join as join7 } from "path";
 import { styleText } from "util";
 
 // ../routes/src/ast.ts
@@ -2917,8 +2918,8 @@ function staticRoutes(project) {
 }
 
 // ../routes/src/project.ts
-import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
-import { dirname as dirname2, join as join5 } from "path";
+import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync5 } from "fs";
+import { dirname as dirname2, join as join5, relative as relative3 } from "path";
 var FRAMEWORKS = {
   next: { name: "Next.js", routing: "files" },
   nuxt: { name: "Nuxt", routing: "code" },
@@ -3052,11 +3053,69 @@ function normalizeBasePath(path) {
   if (!trimmed) return "";
   return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
 }
+var RUNS_PACKAGES = /\b(turbo|nx|lerna|moon)\b|\bpnpm\b.*\s(-r|--recursive|--filter|-F)\b|\b(npm|yarn|bun)\b.*\s(--workspaces?|-w|--filter|workspaces?)\b/;
+function workspaceDirs(root, pkg) {
+  const globs = Array.isArray(pkg.workspaces) ? [...pkg.workspaces] : [...pkg.workspaces?.packages ?? []];
+  const pnpm = join5(root, "pnpm-workspace.yaml");
+  if (existsSync4(pnpm)) {
+    let inPackages = false;
+    for (const line of readFileSync5(pnpm, "utf8").split(/\r?\n/)) {
+      if (/^packages\s*:/.test(line)) inPackages = true;
+      else if (/^\S/.test(line)) inPackages = false;
+      else if (inPackages) {
+        const item = line.match(/^\s*-\s*['"]?([^'"#]+?)['"]?\s*(?:#.*)?$/)?.[1];
+        if (item) globs.push(item);
+      }
+    }
+  }
+  const expand = (dir, parts, depth = 0) => {
+    const [part, ...rest2] = parts;
+    if (part === void 0) return [dir];
+    if (part === "." || part === "") return expand(dir, rest2, depth);
+    if (!part.includes("*"))
+      return existsSync4(join5(dir, part)) ? expand(join5(dir, part), rest2, depth) : [];
+    let subdirs;
+    try {
+      subdirs = readdirSync2(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && d.name !== "node_modules" && !d.name.startsWith(".")).map((d) => d.name);
+    } catch {
+      return [];
+    }
+    if (part === "**") {
+      return [
+        ...expand(dir, rest2, depth),
+        ...depth < 3 ? subdirs.flatMap((d) => expand(join5(dir, d), parts, depth + 1)) : []
+      ];
+    }
+    const match = new RegExp(
+      `^${part.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`
+    );
+    return subdirs.filter((d) => match.test(d)).flatMap((d) => expand(join5(dir, d), rest2, depth));
+  };
+  const of = (globs2) => globs2.flatMap((g) => expand(root, g.replace(/\/+$/, "").split("/")));
+  const left = new Set(of(globs.filter((g) => g.startsWith("!")).map((g) => g.slice(1))));
+  return [...new Set(of(globs.filter((g) => !g.startsWith("!"))))].filter((d) => !left.has(d));
+}
+function workspaceApps(root, pkg) {
+  return workspaceDirs(root, pkg).filter((dir) => {
+    const app = readJson(join5(dir, "package.json"));
+    if (!app) return false;
+    const framework = detectFramework({ ...app.dependencies, ...app.devDependencies });
+    const script = pickDevScript(app.scripts ?? {});
+    return framework.id !== "unknown" && !!script && DEV_SERVER.test(script.command);
+  });
+}
 function detectProject(cwd) {
   const pkg = readJson(join5(cwd, "package.json"));
   if (!pkg) return null;
   const deps = { ...pkg.dependencies, ...pkg.devDependencies };
   const framework = detectFramework(deps);
+  const own = pickDevScript(pkg.scripts ?? {});
+  const isApp = framework.id !== "unknown" && !!own && !RUNS_PACKAGES.test(own.command);
+  const apps = isApp ? [] : workspaceApps(cwd, pkg);
+  if (apps.length === 1) {
+    const app = detectProject(apps[0]);
+    if (app) return { ...app, workspace: relative3(cwd, apps[0]) };
+  }
   const devScript = pickDevScript(pkg.scripts ?? {});
   const defaultPort = DEFAULT_PORT[framework.id];
   const configured = [...new Set(configuredPorts(cwd, devScript?.command))];
@@ -3068,7 +3127,8 @@ function detectProject(cwd) {
     devScript,
     ports: [...new Set(ports)],
     configuredPorts: configured,
-    basePath: detectBasePath(cwd)
+    basePath: detectBasePath(cwd),
+    ...apps.length > 1 ? { apps: apps.map((a) => relative3(cwd, a)) } : {}
   };
 }
 
@@ -3107,8 +3167,8 @@ var RouteQueue = class {
   /** For routes left waiting at the end: the parameters nothing gave a value. */
   missing = /* @__PURE__ */ new Map();
   /**
-   * Values parameters took in real URLs, under the route they belong to: `/cohorts/[slug]` →
-   * `css-101`. Routes below it reuse them, since a child of a real page is real too.
+   * Values parameters took in real URLs, under the route they belong to: `/users/[username]` →
+   * `jane`. Routes below it reuse them, since a child of a real page is real too.
    */
   seen = /* @__PURE__ */ new Map();
   patterns = /* @__PURE__ */ new Map();
@@ -3266,14 +3326,14 @@ var RouteQueue = class {
 function readRuntimeRoutes() {
   const w = window;
   const paths = /* @__PURE__ */ new Set();
-  const join19 = (base, path) => path.startsWith("/") ? path : `${base.replace(/\/?\*$/, "").replace(/\/+$/, "")}/${path}`;
+  const join20 = (base, path) => path.startsWith("/") ? path : `${base.replace(/\/?\*$/, "").replace(/\/+$/, "")}/${path}`;
   const manifest = w.__reactRouterManifest?.routes ?? w.__remixManifest?.routes;
   if (manifest && typeof manifest === "object") {
     const fullPath = (id, depth = 0) => {
       const r = manifest[id];
       if (!r || depth > 50) return "";
       const parent = r.parentId ? fullPath(r.parentId, depth + 1) : "";
-      return r.path ? join19(parent, r.path) : parent;
+      return r.path ? join20(parent, r.path) : parent;
     };
     for (const id of Object.keys(manifest)) {
       const r = manifest[id];
@@ -3320,7 +3380,7 @@ function readRuntimeRoutes() {
         if (e?.props?.children && !e.props.path) walkElements(e.props.children, base);
         continue;
       }
-      const full = typeof e.props.path === "string" ? join19(base, e.props.path) : base;
+      const full = typeof e.props.path === "string" ? join20(base, e.props.path) : base;
       if (typeof e.props.path === "string") paths.add(full);
       else if (e.props.index) paths.add(indexPath2(base));
       walkElements(e.props.children, full);
@@ -3330,7 +3390,7 @@ function readRuntimeRoutes() {
     if (!Array.isArray(routes) || depth > 30) return;
     for (const r of routes) {
       if (!r || typeof r !== "object") continue;
-      const full = typeof r.path === "string" ? join19(base, r.path) : base;
+      const full = typeof r.path === "string" ? join20(base, r.path) : base;
       if (typeof r.path === "string") paths.add(full);
       else if (r.index) paths.add(indexPath2(base));
       walkObjects(r.children, full, depth + 1);
@@ -3342,7 +3402,7 @@ function readRuntimeRoutes() {
       if (Array.isArray(matches) && matches.length) {
         let base = "";
         for (const m of matches)
-          if (typeof m.route?.path === "string") base = join19(base, m.route.path);
+          if (typeof m.route?.path === "string") base = join20(base, m.route.path);
         return base;
       }
     }
@@ -3371,7 +3431,7 @@ function readRuntimeRoutes() {
         if (Array.isArray(matches)) {
           let base = "";
           for (const m of matches) {
-            if (typeof m?.route?.path === "string") base = join19(base, m.route.path);
+            if (typeof m?.route?.path === "string") base = join20(base, m.route.path);
             if (Array.isArray(m?.route?.children)) {
               kind ??= "react-router";
               walkObjects(m.route.children, base);
@@ -3555,7 +3615,7 @@ async function startServer(project, options = {}) {
   }
   const timeoutMs = options.timeoutMs ?? 12e4;
   const child = spawn(command, {
-    cwd: project.root,
+    cwd: options.cwd ?? project.root,
     shell: true,
     detached: process.platform !== "win32",
     stdio: ["ignore", "pipe", "pipe"],
@@ -3592,6 +3652,13 @@ async function startServer(project, options = {}) {
   let failingSince = null;
   while (Date.now() < deadline) {
     if (child.exitCode !== null) {
+      const printed2 = printedUrl;
+      const page = printed2 ? await probe(`${printed2}/`, 5e3) : null;
+      if (printed2 && page && page.status < 500 && looksLikeProject(project, page, true)) {
+        process.removeListener("exit", cleanup);
+        return { url: printed2, alreadyRunning: true, stop: async () => {
+        } };
+      }
       throw new Error(
         `The dev server (${command}) stopped before it was ready:
 ${output.slice(-15).join("\n")}`
@@ -3946,9 +4013,34 @@ async function resolveServer(cwd, config, quiet) {
       "No package.json here, so there is no app to find. Run breakhound in your project folder, or pass a URL: npx @seybel/breakhound http://localhost:3000"
     );
   }
-  if (config.server?.port) {
-    project.ports = [config.server.port, ...project.ports.filter((p) => p !== config.server?.port)];
-    project.configuredPorts = [config.server.port, ...project.configuredPorts];
+  const withPort = (p) => {
+    const port = config.server?.port;
+    if (!port) return p;
+    p.ports = [port, ...p.ports.filter((q) => q !== port)];
+    p.configuredPorts = [port, ...p.configuredPorts];
+    return p;
+  };
+  withPort(project);
+  if (project.workspace) log(quiet, styleText("dim", `Using the app in ${project.workspace}`));
+  if (project.apps && !config.server?.command) {
+    const found = await Promise.all(
+      project.apps.map(async (dir2) => {
+        const found2 = detectProject(join7(cwd, dir2));
+        const app2 = found2 && withPort(found2);
+        const running3 = app2 ? await findRunningServer(app2) : null;
+        return app2 && running3 ? { dir: dir2, app: app2, running: running3 } : null;
+      })
+    );
+    const live = found.filter((f) => f !== null);
+    if (live.length !== 1 || !live[0]) {
+      throw new Error(
+        `This is a monorepo with ${project.apps.length} apps (${project.apps.join(", ")}). Run breakhound in the one to scan, e.g. cd ${project.apps[0]} && npx @seybel/breakhound, or start its dev server first.`
+      );
+    }
+    const { dir, app, running: running2 } = live[0];
+    const baseUrl2 = withBasePath(running2.url, app.basePath);
+    log(quiet, `${styleText("green", "\u2714")} ${app.framework.name} in ${dir} running at ${baseUrl2}`);
+    return { project: { ...app, workspace: dir }, baseUrl: baseUrl2, server: null };
   }
   const running = config.server?.command ? null : await findRunningServer(project);
   if (running) {
@@ -3961,7 +4053,8 @@ async function resolveServer(cwd, config, quiet) {
   log(quiet, styleText("dim", `Starting ${name ?? "the app"} with ${label}...`));
   let pid;
   const started = await startServer(project, {
-    ...command ? { command } : {},
+    // A command from the config runs where breakhound was run, like the user would run it.
+    ...command ? { command, cwd } : {},
     ...config.server?.port ? { port: config.server.port } : {},
     ...config.server?.timeout ? { timeoutMs: config.server.timeout * 1e3 } : {},
     onSpawn: (id) => {
@@ -3972,6 +4065,12 @@ async function resolveServer(cwd, config, quiet) {
     guard.untrackServer(pid);
     throw error;
   });
+  if (started.alreadyRunning) {
+    guard.untrackServer(pid);
+    const baseUrl2 = withBasePath(started.url, project.basePath);
+    log(quiet, `${styleText("green", "\u2714")} ${name ?? "App"} already running at ${baseUrl2}`);
+    return { project, baseUrl: baseUrl2, server: null };
+  }
   const server2 = {
     ...started,
     stop: async () => {
@@ -4058,7 +4157,7 @@ async function planRoutes(app, config, scanner, explicit) {
 import { spawnSync as spawnSync3 } from "child_process";
 import { existsSync as existsSync6, readFileSync as readFileSync8 } from "fs";
 import { createRequire as createRequire2 } from "module";
-import { dirname as dirname3, join as join7 } from "path";
+import { dirname as dirname3, join as join8 } from "path";
 import { styleText as styleText2 } from "util";
 var DOWNLOAD_MB = { chromium: 150, webkit: 80, firefox: 90 };
 function installed(name) {
@@ -4086,7 +4185,7 @@ function playwrightCli() {
   const manifest = require2.resolve("playwright/package.json");
   const { bin } = JSON.parse(readFileSync8(manifest, "utf8"));
   const file = typeof bin === "string" ? bin : bin?.playwright ?? "cli.js";
-  return join7(dirname3(manifest), file);
+  return join8(dirname3(manifest), file);
 }
 function installBrowsers(names, withDeps) {
   const cli = playwrightCli();
@@ -4117,7 +4216,7 @@ async function runLogin(cwd, config, options = {}) {
   };
   ensureBrowsers();
   const app = await resolveServer(cwd, config, options.quiet ?? false);
-  const file = join8(cwd, AUTH_FILE);
+  const file = join9(cwd, AUTH_FILE);
   const browser = await launch(Boolean(automate));
   try {
     const context = await browser.newContext({
@@ -4243,7 +4342,7 @@ function copyToClipboard(text2) {
 
 // src/config.ts
 import { existsSync as existsSync8, readFileSync as readFileSync10 } from "fs";
-import { join as join9, resolve as resolve2 } from "path";
+import { join as join10, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var CONFIG_FILES = [
   "breakhound.config.ts",
@@ -4261,7 +4360,7 @@ function selfModule() {
   return "@seybel/breakhound";
 }
 async function loadConfig(cwd, explicit) {
-  const file = explicit ? resolve2(cwd, explicit) : CONFIG_FILES.map((f) => join9(cwd, f)).find((f) => existsSync8(f));
+  const file = explicit ? resolve2(cwd, explicit) : CONFIG_FILES.map((f) => join10(cwd, f)).find((f) => existsSync8(f));
   if (!file) return { config: {}, file: null, warnings: [] };
   if (!existsSync8(file)) throw new Error(`Config file not found: ${file}`);
   let config;
@@ -4347,7 +4446,7 @@ function validateConfig(config) {
     const ok = config.params && typeof config.params === "object" && !Array.isArray(config.params) && Object.values(config.params).every((v) => typeof v === "string" && v !== "");
     if (!ok) {
       throw new Error(
-        `params must give dynamic route parameters a real value by name, like { "slug": "css-101" }`
+        `params must give dynamic route parameters a real value by name, like { "username": "jane" }`
       );
     }
   }
@@ -4444,14 +4543,14 @@ function normalizeIgnore(ignore) {
 // src/fix.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync12, readFileSync as readFileSync14, statSync as statSync3, writeFileSync as writeFileSync6 } from "fs";
-import { join as join13, normalize as normalize2 } from "path";
+import { join as join14, normalize as normalize2 } from "path";
 import { styleText as styleText6 } from "util";
 
 // src/session.ts
 import { spawnSync as spawnSync5 } from "child_process";
 import { randomBytes } from "crypto";
 import { existsSync as existsSync9, readFileSync as readFileSync11, realpathSync, writeFileSync as writeFileSync3 } from "fs";
-import { join as join10, relative as relative3, resolve as resolve3, sep as sep2 } from "path";
+import { join as join11, relative as relative4, resolve as resolve3, sep as sep2 } from "path";
 var SESSION_FILE = "session.json";
 function git(cwd, args, input) {
   const run2 = spawnSync5("git", args, {
@@ -4484,7 +4583,7 @@ function fromRoot(root, cwd, path) {
     base = realpathSync(cwd);
   } catch {
   }
-  return relative3(root, resolve3(base, path)).split(sep2).join("/");
+  return relative4(root, resolve3(base, path)).split(sep2).join("/");
 }
 function changedFiles(cwd, outDir = ".breakhound") {
   const root = gitRoot(cwd);
@@ -4503,7 +4602,7 @@ function changedFiles(cwd, outDir = ".breakhound") {
   return files.filter((f) => f !== skip && !f.startsWith(`${skip}/`));
 }
 function sessionPath(cwd, outDir) {
-  return join10(resolve3(cwd, outDir), SESSION_FILE);
+  return join11(resolve3(cwd, outDir), SESSION_FILE);
 }
 function readSession(cwd, outDir = ".breakhound") {
   const file = sessionPath(cwd, outDir);
@@ -4710,11 +4809,11 @@ function undo(cwd, req) {
 
 // src/verify.ts
 import { existsSync as existsSync11, readFileSync as readFileSync13, writeFileSync as writeFileSync5 } from "fs";
-import { join as join12, resolve as resolve5 } from "path";
+import { join as join13, resolve as resolve5 } from "path";
 
 // src/scan.ts
-import { existsSync as existsSync10, readdirSync as readdirSync2, readFileSync as readFileSync12, rmSync, statSync as statSync2, writeFileSync as writeFileSync4 } from "fs";
-import { isAbsolute, join as join11, relative as relative5, resolve as resolve4, sep as sep3 } from "path";
+import { existsSync as existsSync10, readdirSync as readdirSync3, readFileSync as readFileSync12, rmSync, statSync as statSync2, writeFileSync as writeFileSync4 } from "fs";
+import { isAbsolute, join as join12, relative as relative6, resolve as resolve4, sep as sep3 } from "path";
 import { fileURLToPath as fileURLToPath3, pathToFileURL } from "url";
 import { styleText as styleText5 } from "util";
 
@@ -4872,7 +4971,7 @@ ${SETUP}`
 }
 
 // src/print.ts
-import { relative as relative4 } from "path";
+import { relative as relative5 } from "path";
 import { styleText as styleText4 } from "util";
 var BADGE = {
   error: styleText4("red", "\u2716 error  "),
@@ -4949,7 +5048,7 @@ function printIssues(result) {
 }
 function printFooter(paths, result, cwd) {
   const rel = (p) => {
-    const r = relative4(cwd, p);
+    const r = relative5(cwd, p);
     return r.startsWith("..") ? p : r;
   };
   console.log("");
@@ -5134,7 +5233,7 @@ function routeOf(url, cwd) {
   const u = new URL(url);
   if (u.protocol === "file:") {
     const path = fileURLToPath3(u);
-    const rel = relative5(cwd, path);
+    const rel = relative6(cwd, path);
     return rel.startsWith("..") ? path : rel;
   }
   return `${u.pathname}${u.search}` || "/";
@@ -5142,9 +5241,9 @@ function routeOf(url, cwd) {
 var SCREENSHOT_FILE = /^[0-9a-f]{10}\.png$/;
 function clearScreenshots(dir) {
   if (!existsSync10(dir)) return;
-  for (const name of readdirSync2(dir)) {
-    if (SCREENSHOT_FILE.test(name)) rmSync(join11(dir, name), { force: true });
-    else if (BROWSER_NAMES.includes(name)) clearScreenshots(join11(dir, name));
+  for (const name of readdirSync3(dir)) {
+    if (SCREENSHOT_FILE.test(name)) rmSync(join12(dir, name), { force: true });
+    else if (BROWSER_NAMES.includes(name)) clearScreenshots(join12(dir, name));
   }
 }
 function resolveTargets(targets, config, cwd) {
@@ -5170,25 +5269,26 @@ function projectPath(file, root, basePath = "") {
   if (isAbsolute(path)) candidates.push(path);
   if (path.startsWith("/")) {
     const inApp = basePath && path.startsWith(`${basePath}/`) ? path.slice(basePath.length) : path;
-    candidates.push(join11(root, inApp));
+    candidates.push(join12(root, inApp));
   } else {
-    candidates.push(join11(root, path));
+    candidates.push(join12(root, path));
   }
   for (const candidate of candidates) {
-    const rel = relative5(root, candidate);
+    const rel = relative6(root, candidate);
     if (!rel.startsWith("..") && !isAbsolute(rel) && isFile(candidate))
       return rel.split(sep3).join("/");
   }
   return null;
 }
-function relativeSources(routes, root, basePath) {
+function relativeSources(routes, root, basePath, workspace = "") {
+  const prefix = workspace ? `${workspace.split(sep3).join("/")}/` : "";
   for (const route of routes) {
     for (const issue of route.issues) {
       for (const element of [issue.element, issue.related]) {
         const source = element?.source;
         if (!element || !source) continue;
         const file = projectPath(source.file, root, basePath);
-        element.source = file ? { ...source, file } : null;
+        element.source = file ? { ...source, file: `${prefix}${file}` } : null;
       }
     }
   }
@@ -5245,11 +5345,11 @@ async function scan(req) {
   const pageMode = jobs ? jobs.every((j) => !j.url.startsWith("http")) : req.targets.length > 0 && req.targets.every((t) => isPageTarget(t, cwd));
   const pageTargets = jobs && pageMode ? jobs : pageMode ? resolveTargets(req.targets, config, cwd) : [];
   const outDir = resolve4(cwd, config.outDir ?? ".breakhound");
-  const screenshotDir = join11(outDir, "screenshots");
+  const screenshotDir = join12(outDir, "screenshots");
   const browsers = config.browsers?.length ? config.browsers : ["chromium"];
   const [firstBrowser = "chromium", ...otherBrowsers] = browsers;
   ensureBrowsers(browsers);
-  const authFile = join11(cwd, AUTH_FILE);
+  const authFile = join12(cwd, AUTH_FILE);
   const auth = existsSync10(authFile) ? { storageState: authFile } : {};
   const scanner = new Scanner({ ...auth, browser: firstBrowser });
   const startedAt = /* @__PURE__ */ new Date();
@@ -5369,7 +5469,7 @@ async function scan(req) {
           const result2 = await other.scanPage(route.url, {
             ...baseOptions,
             route: route.route,
-            ...baseOptions.screenshotDir ? { screenshotDir: join11(baseOptions.screenshotDir, browser) } : {}
+            ...baseOptions.screenshotDir ? { screenshotDir: join12(baseOptions.screenshotDir, browser) } : {}
           });
           for (const i of result2.issues)
             if (i.screenshot) i.screenshot = `${browser}/${i.screenshot}`;
@@ -5440,7 +5540,12 @@ async function scan(req) {
     if (!req.app) await app?.server?.stop();
   }
   applySeverity(routes, config);
-  relativeSources(routes, app?.project?.root ?? cwd, app?.project?.basePath ?? "");
+  relativeSources(
+    routes,
+    app?.project?.root ?? cwd,
+    app?.project?.basePath ?? "",
+    app?.project?.workspace
+  );
   const firstUrl = pageTargets[0]?.url;
   const baseUrl = app?.baseUrl ?? config.baseUrl ?? (firstUrl?.startsWith("http") ? new URL(firstUrl).origin : null);
   const framework = app?.project?.framework;
@@ -5458,7 +5563,7 @@ async function scan(req) {
   const kept = req.app ? app : null;
   if (req.write === false) return { result, reports: null, app: kept };
   const reports = await saveReports(result, config, cwd);
-  const baselineFile = join11(outDir, BASELINE_FILE);
+  const baselineFile = join12(outDir, BASELINE_FILE);
   const earlier = !pageMode && req.targets.length > 0 && existsSync10(baselineFile) ? JSON.parse(readFileSync12(baselineFile, "utf8")) : null;
   const baseline = earlier && !earlier.from ? mergeScans(earlier, result) : result;
   writeFileSync4(baselineFile, `${JSON.stringify(baseline, null, 2)}
@@ -5479,7 +5584,7 @@ async function saveExtensionScan(sent, config, cwd) {
     issues: r.issues.filter((i) => off[i.detector] !== false)
   }));
   applySeverity(routes, config);
-  relativeSources(routes, project?.root ?? cwd, project?.basePath ?? "");
+  relativeSources(routes, project?.root ?? cwd, project?.basePath ?? "", project?.workspace);
   const framework = project?.framework;
   const result = createScanResult(routes, {
     version: sent.tool.version,
@@ -5493,9 +5598,9 @@ async function saveExtensionScan(sent, config, cwd) {
     from: "extension"
   });
   const outDir = resolve4(cwd, config.outDir ?? ".breakhound");
-  clearScreenshots(join11(outDir, "screenshots"));
+  clearScreenshots(join12(outDir, "screenshots"));
   await saveReports(result, config, cwd);
-  writeFileSync4(join11(outDir, BASELINE_FILE), `${JSON.stringify(result, null, 2)}
+  writeFileSync4(join12(outDir, BASELINE_FILE), `${JSON.stringify(result, null, 2)}
 `);
   touchSession(cwd, config.outDir ?? ".breakhound");
   return result;
@@ -5503,14 +5608,14 @@ async function saveExtensionScan(sent, config, cwd) {
 function saveReports(result, config, cwd) {
   const outDir = resolve4(cwd, config.outDir ?? ".breakhound");
   return writeReports(result, outDir, {
-    screenshotDir: join11(outDir, "screenshots"),
+    screenshotDir: join12(outDir, "screenshots"),
     pdf: config.pdf ?? false,
     verifyCommand: "npx @seybel/breakhound verify"
   });
 }
 function readLastResult(cwd, outDir = ".breakhound") {
   const dir = resolve4(cwd, outDir);
-  const file = join11(dir, "result.json");
+  const file = join12(dir, "result.json");
   if (!existsSync10(file)) throw new Error("No scan yet. Run breakhound first.");
   return { result: JSON.parse(readFileSync12(file, "utf8")), dir };
 }
@@ -5537,7 +5642,7 @@ function mergeScans(earlier, now) {
 function readBaseline(cwd, outDir = ".breakhound") {
   const dir = resolve5(cwd, outDir);
   for (const name of [BASELINE_FILE, "result.json"]) {
-    const file = join12(dir, name);
+    const file = join13(dir, name);
     if (existsSync11(file)) return JSON.parse(readFileSync13(file, "utf8"));
   }
   throw new Error("Nothing to verify against yet. Run breakhound first to scan the app.");
@@ -5676,7 +5781,7 @@ async function finishVerify(req, baseline, result) {
   const outcome = { baselineAt: baseline.startedAt, ...diff, current, reports };
   const dir = resolve5(req.cwd, req.config.outDir ?? ".breakhound");
   const { current: _, reports: __, ...saved } = outcome;
-  writeFileSync5(join12(dir, "verify.json"), `${JSON.stringify(saved, null, 2)}
+  writeFileSync5(join13(dir, "verify.json"), `${JSON.stringify(saved, null, 2)}
 `);
   return outcome;
 }
@@ -5794,12 +5899,12 @@ function pickFiles(cwd, issue, tracked = trackedFiles(cwd)) {
   const terms = searchTerms(issue);
   const scores = /* @__PURE__ */ new Map();
   for (const source of [issue.element.source, issue.related?.source]) {
-    if (source?.file && existsSync12(join13(cwd, source.file))) {
+    if (source?.file && existsSync12(join14(cwd, source.file))) {
       scores.set(source.file, (scores.get(source.file) ?? 0) + 100);
     }
   }
   for (const file of tracked) {
-    const full = join13(cwd, file);
+    const full = join14(cwd, file);
     try {
       if (statSync3(full).size > MAX_SCAN_BYTES) continue;
       const content = readFileSync14(full, "utf8");
@@ -5808,7 +5913,7 @@ function pickFiles(cwd, issue, tracked = trackedFiles(cwd)) {
     } catch {
     }
   }
-  return [...scores.entries()].sort((a, b) => b[1] - a[1]).slice(0, MAX_FILES3).map(([path]) => ({ path, content: excerpt(readFileSync14(join13(cwd, path), "utf8"), terms) }));
+  return [...scores.entries()].sort((a, b) => b[1] - a[1]).slice(0, MAX_FILES3).map(([path]) => ({ path, content: excerpt(readFileSync14(join14(cwd, path), "utf8"), terms) }));
 }
 function parseEdits(reply) {
   const edits = [];
@@ -5855,7 +5960,7 @@ function applyEdits(cwd, edits, allowed) {
   const originals = /* @__PURE__ */ new Map();
   for (const edit of edits) {
     if (!allowed.has(edit.file)) return { error: `${edit.file} wasn't one of the files given.` };
-    const current = next.get(edit.file) ?? readFileSync14(join13(cwd, edit.file), "utf8");
+    const current = next.get(edit.file) ?? readFileSync14(join14(cwd, edit.file), "utf8");
     if (!originals.has(edit.file)) originals.set(edit.file, current);
     const at = locate(current, edit.search);
     if (at === "many") {
@@ -5867,11 +5972,11 @@ function applyEdits(cwd, edits, allowed) {
       return { error: `The search text for ${edit.file} isn't in the file. Copy it exactly.` };
     next.set(edit.file, current.slice(0, at.start) + edit.replace + current.slice(at.end));
   }
-  for (const [file, content] of next) writeFileSync6(join13(cwd, file), content);
+  for (const [file, content] of next) writeFileSync6(join14(cwd, file), content);
   return { originals };
 }
 function restore2(cwd, originals) {
-  for (const [file, content] of originals) writeFileSync6(join13(cwd, file), content);
+  for (const [file, content] of originals) writeFileSync6(join14(cwd, file), content);
 }
 function promptFor(group, text2, files, feedback) {
   const parts = [text2, "", "Files:", ""];
@@ -6012,7 +6117,7 @@ async function fix(req) {
 
 // src/init.ts
 import { existsSync as existsSync13, readFileSync as readFileSync15, writeFileSync as writeFileSync7 } from "fs";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 import { styleText as styleText7 } from "util";
 var TEMPLATE = (baseUrl, typed) => `${typed ? "import { defineConfig } from '@seybel/breakhound';\n\nexport default defineConfig({" : "/** @type {import('@seybel/breakhound').BreakhoundConfig} */\nexport default {"}
   // breakhound finds your dev server, or starts it, by itself. Set this to
@@ -6049,7 +6154,7 @@ var JSON_TEMPLATE = `${JSON.stringify(
 `;
 function isInstalled(cwd) {
   try {
-    const pkg = JSON.parse(readFileSync15(join14(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync15(join15(cwd, "package.json"), "utf8"));
     return Boolean(pkg.dependencies?.breakhound || pkg.devDependencies?.breakhound);
   } catch {
     return false;
@@ -6057,7 +6162,7 @@ function isInstalled(cwd) {
 }
 function guessBaseUrl(cwd) {
   try {
-    const pkg = JSON.parse(readFileSync15(join14(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync15(join15(cwd, "package.json"), "utf8"));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     const dev = pkg.scripts?.dev ?? "";
     const port = dev.match(/(?:--port|-p)[ =](\d{2,5})/)?.[1];
@@ -6072,15 +6177,15 @@ function guessBaseUrl(cwd) {
   return "http://localhost:3000";
 }
 function runInit(cwd) {
-  const existing = ["ts", "mts", "js", "mjs", "cjs", "json"].map((ext) => `breakhound.config.${ext}`).find((f) => existsSync13(join14(cwd, f)));
+  const existing = ["ts", "mts", "js", "mjs", "cjs", "json"].map((ext) => `breakhound.config.${ext}`).find((f) => existsSync13(join15(cwd, f)));
   if (existing) {
     console.log(`${existing} already exists. Nothing to do.`);
     return;
   }
   const installed2 = isInstalled(cwd);
-  const typed = existsSync13(join14(cwd, "tsconfig.json"));
+  const typed = existsSync13(join15(cwd, "tsconfig.json"));
   const file = !installed2 ? "breakhound.config.json" : typed ? "breakhound.config.ts" : "breakhound.config.mjs";
-  writeFileSync7(join14(cwd, file), installed2 ? TEMPLATE(guessBaseUrl(cwd), typed) : JSON_TEMPLATE);
+  writeFileSync7(join15(cwd, file), installed2 ? TEMPLATE(guessBaseUrl(cwd), typed) : JSON_TEMPLATE);
   console.log(`${styleText7("green", "\u2714")} Created ${file}`);
   if (!installed2) {
     console.log(
@@ -6097,7 +6202,7 @@ Now run ${styleText7("bold", "npx @seybel/breakhound")}.`);
 
 // src/mcp.ts
 import { existsSync as existsSync14, readFileSync as readFileSync17 } from "fs";
-import { join as join16, resolve as resolve6 } from "path";
+import { join as join17, resolve as resolve6 } from "path";
 import { createInterface as createInterface2 } from "readline";
 import { fileURLToPath as fileURLToPath4 } from "url";
 
@@ -6105,7 +6210,7 @@ import { fileURLToPath as fileURLToPath4 } from "url";
 import { randomUUID } from "crypto";
 import { readFileSync as readFileSync16 } from "fs";
 import { createServer } from "http";
-import { basename, join as join15 } from "path";
+import { basename, join as join16 } from "path";
 var EXTENSION_IDS = ["ddnmhnjmcokbfabeileblceehjhefkpc"];
 var POLL_MS = 25e3;
 var PICKUP_MS = 2e4;
@@ -6130,7 +6235,7 @@ function allowedOrigins() {
 }
 function projectName(root) {
   try {
-    const name = JSON.parse(readFileSync16(join15(root, "package.json"), "utf8")).name;
+    const name = JSON.parse(readFileSync16(join16(root, "package.json"), "utf8")).name;
     if (typeof name === "string" && name) return name;
   } catch {
   }
@@ -6550,7 +6655,7 @@ function createTools() {
             true
           );
         const out = { content: [{ type: "text", text: found.text }] };
-        const shot = found.issue.screenshot && join16(dir, "screenshots", found.issue.screenshot);
+        const shot = found.issue.screenshot && join17(dir, "screenshots", found.issue.screenshot);
         if (shot && existsSync14(shot)) {
           out.content.push({
             type: "image",
@@ -6683,7 +6788,7 @@ Run verify to see the issues back.`
   ];
 }
 function fixedDetails(ctx, routes) {
-  const file = join16(resolve6(ctx.root, ctx.config.outDir ?? ".breakhound"), "verify.json");
+  const file = join17(resolve6(ctx.root, ctx.config.outDir ?? ".breakhound"), "verify.json");
   if (!existsSync14(file)) return [];
   try {
     const v = JSON.parse(readFileSync17(file, "utf8"));
@@ -6754,7 +6859,7 @@ async function runMcpServer(version, io = { input: process.stdin, output: proces
       "package.json",
       "breakhound.config.json",
       "breakhound.config.ts"
-    ].some((f) => existsSync14(join16(cwd, f)));
+    ].some((f) => existsSync14(join17(cwd, f)));
     if (!looksLikeProject2 && clientCanListRoots) {
       try {
         const res = await request("roots/list");
@@ -6901,7 +7006,7 @@ async function runMcpServer(version, io = { input: process.stdin, output: proces
 import { spawnSync as spawnSync6 } from "child_process";
 import { existsSync as existsSync15, mkdirSync as mkdirSync3, readFileSync as readFileSync18, writeFileSync as writeFileSync8 } from "fs";
 import { homedir } from "os";
-import { dirname as dirname5, join as join17, relative as relative6 } from "path";
+import { dirname as dirname5, join as join18, relative as relative7 } from "path";
 import { createInterface as createInterface3 } from "readline/promises";
 import { styleText as styleText8 } from "util";
 var SERVER_NAME = "breakhound";
@@ -6967,12 +7072,12 @@ function onPath(command) {
 function allClients(cwd, home = homedir()) {
   const { command, args } = serverCommand();
   return [
-    jsonClient("claude", "Claude Code", join17(cwd, ".mcp.json"), "mcpServers", { command, args }),
-    jsonClient("cursor", "Cursor", join17(cwd, ".cursor", "mcp.json"), "mcpServers", {
+    jsonClient("claude", "Claude Code", join18(cwd, ".mcp.json"), "mcpServers", { command, args }),
+    jsonClient("cursor", "Cursor", join18(cwd, ".cursor", "mcp.json"), "mcpServers", {
       command,
       args
     }),
-    jsonClient("vscode", "VS Code", join17(cwd, ".vscode", "mcp.json"), "servers", {
+    jsonClient("vscode", "VS Code", join18(cwd, ".vscode", "mcp.json"), "servers", {
       type: "stdio",
       command,
       args,
@@ -6984,7 +7089,7 @@ function allClients(cwd, home = homedir()) {
     jsonClient(
       "antigravity",
       "Antigravity",
-      join17(cwd, ".agents", "mcp_config.json"),
+      join18(cwd, ".agents", "mcp_config.json"),
       "mcpServers",
       {
         command,
@@ -6994,26 +7099,26 @@ function allClients(cwd, home = homedir()) {
     jsonClient(
       "windsurf",
       "Windsurf",
-      join17(home, ".codeium", "windsurf", "mcp_config.json"),
+      join18(home, ".codeium", "windsurf", "mcp_config.json"),
       "mcpServers",
       { command, args }
     ),
-    codexClient(join17(home, ".codex", "config.toml"))
+    codexClient(join18(home, ".codex", "config.toml"))
   ];
 }
 function detectClients(cwd, home = homedir()) {
   const found = {
-    claude: existsSync15(join17(cwd, ".mcp.json")) || existsSync15(join17(cwd, ".claude")) || existsSync15(join17(cwd, "CLAUDE.md")) || existsSync15(join17(home, ".claude")) || onPath("claude"),
-    cursor: existsSync15(join17(cwd, ".cursor")) || existsSync15(join17(home, ".cursor")),
-    vscode: existsSync15(join17(cwd, ".vscode")) || onPath("code"),
-    antigravity: existsSync15(join17(cwd, ".agents", "mcp_config.json")) || existsSync15(join17(home, ".gemini", "config", "mcp_config.json")) || existsSync15(join17(home, ".gemini", "antigravity")) || onPath("antigravity"),
-    windsurf: existsSync15(join17(home, ".codeium", "windsurf")),
-    codex: existsSync15(join17(home, ".codex"))
+    claude: existsSync15(join18(cwd, ".mcp.json")) || existsSync15(join18(cwd, ".claude")) || existsSync15(join18(cwd, "CLAUDE.md")) || existsSync15(join18(home, ".claude")) || onPath("claude"),
+    cursor: existsSync15(join18(cwd, ".cursor")) || existsSync15(join18(home, ".cursor")),
+    vscode: existsSync15(join18(cwd, ".vscode")) || onPath("code"),
+    antigravity: existsSync15(join18(cwd, ".agents", "mcp_config.json")) || existsSync15(join18(home, ".gemini", "config", "mcp_config.json")) || existsSync15(join18(home, ".gemini", "antigravity")) || onPath("antigravity"),
+    windsurf: existsSync15(join18(home, ".codeium", "windsurf")),
+    codex: existsSync15(join18(home, ".codex"))
   };
   return allClients(cwd, home).filter((c) => found[c.id]);
 }
 function show(path, cwd) {
-  const rel = relative6(cwd, path);
+  const rel = relative7(cwd, path);
   return rel.startsWith("..") ? path.replace(homedir(), "~") : rel;
 }
 async function installMcp(cwd, options = {}) {
@@ -7279,7 +7384,7 @@ async function main(argv) {
   }
   const outDir = values.out ?? fileConfig.outDir ?? ".breakhound";
   if (command === "report") {
-    const file = join18(resolve7(cwd, outDir), "report.html");
+    const file = join19(resolve7(cwd, outDir), "report.html");
     if (!existsSync16(file)) throw new Error("No report yet. Run breakhound first.");
     openInDefaultApp(file);
     console.log(file);

package/dist/index.d.cts

@@ -175,7 +175,7 @@ export interface BreakhoundConfig {
 	samples?: Record<string, string>;
 	/**
 	 * Values for dynamic route parameters by name, for routes no link on your pages fits,
-	 * e.g. { slug: 'css-101', submissionId: '42' }. Every route using those names is filled in;
+	 * e.g. { username: 'jane', orderId: '1001' }. Every route using those names is filled in;
 	 * a parent route's real URL fills its own parameters for the routes below it already.
 	 */
 	params?: Record<string, string>;

package/dist/index.d.ts

@@ -175,7 +175,7 @@ export interface BreakhoundConfig {
 	samples?: Record<string, string>;
 	/**
 	 * Values for dynamic route parameters by name, for routes no link on your pages fits,
-	 * e.g. { slug: 'css-101', submissionId: '42' }. Every route using those names is filled in;
+	 * e.g. { username: 'jane', orderId: '1001' }. Every route using those names is filled in;
 	 * a parent route's real URL fills its own parameters for the routes below it already.
 	 */
 	params?: Record<string, string>;

package/dist/schema.json

@@ -43,7 +43,7 @@
       "additionalProperties": {
         "type": "string"
       },
-      "description": "Values for dynamic route parameters by name, for routes no link on your pages fits, e.g. { slug: 'css-101', submissionId: '42' }. Every route using those names is filled in; a parent route's real URL fills its own parameters for the routes below it already."
+      "description": "Values for dynamic route parameters by name, for routes no link on your pages fits, e.g. { username: 'jane', orderId: '1001' }. Every route using those names is filled in; a parent route's real URL fills its own parameters for the routes below it already."
     },
     "maxRoutes": {
       "type": "number",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seybel/breakhound",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Find where your layout breaks across every viewport width, then hand the fix to your coding agent.",
   "keywords": [
     "responsive",