@seybel/breakhound 0.0.0-stage → 1.0.0

package/dist/index.cjs

@@ -0,0 +1,34 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib.ts
+var lib_exports = {};
+__export(lib_exports, {
+  defineConfig: () => defineConfig
+});
+module.exports = __toCommonJS(lib_exports);
+
+// src/define.ts
+function defineConfig(config) {
+  return config;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineConfig
+});

package/dist/index.d.cts

@@ -0,0 +1,254 @@
+export type Severity = "error" | "warning" | "info";
+export type DetectorId = "page-overflow" | "content-overflow" | "media-overflow" | "overlap" | "unexpected-wrap" | "clipped-text" | "squished-text" | "distorted-media" | "small-tap-target" | "tiny-text" | "oversized-text" | "edge-gutter" | "viewport-meta"
+/** Opt-in: what a vision model noticed in screenshots. Never run in the page. */
+ | "vision";
+/** Where an element comes from in the project's code. */
+export interface SourceLocation {
+	/** Path relative to the project root, with `/` separators. */
+	file: string;
+	line?: number;
+	column?: number;
+	/** The component that renders the element, when known. */
+	component?: string;
+	/**
+	 * True when this is the element's own line (from a source plugin or the
+	 * framework's dev info). False when it's only the file or component that
+	 * renders it, so the element is somewhere inside.
+	 */
+	exact: boolean;
+}
+export interface ElementInfo {
+	/** Shortest unique CSS selector, stable across viewport widths. */
+	selector: string;
+	/** Readable ancestry, e.g. `header > nav > ul`. */
+	path: string;
+	/** Trimmed outerHTML of the opening tag plus a short text preview. */
+	html: string;
+	text: string | null;
+	/** Where it's written in the code, when the page gives that away (dev builds only). */
+	source?: SourceLocation | null;
+}
+export interface IgnoreRule {
+	/** CSS selector; matching elements and everything inside them are ignored. */
+	selector: string;
+	/** Limit the rule to these detectors. Omit to ignore every detector. */
+	detectors?: DetectorId[];
+}
+/**
+ * What a toggle opens. `menu`: navigation menus, drawers and dropdowns.
+ * `disclosure`: anything else with aria-expanded, such as accordions.
+ */
+export type ToggleKind = "menu" | "dialog" | "popover" | "details" | "disclosure";
+export interface WidthRange {
+	from: number;
+	to: number;
+}
+export type BrowserName = "chromium" | "webkit" | "firefox";
+/** A menu, dialog or disclosure that was opened for part of the scan. */
+export interface PageState {
+	kind: ToggleKind;
+	/** The accessible name of what was clicked: "Menu", "Open main menu". */
+	label: string;
+	/** Selector of what was clicked to open it. */
+	trigger: string;
+}
+export interface ScannedState extends PageState {
+	/** Widths where it could be opened and was measured open. */
+	ranges: WidthRange[];
+}
+export interface Issue {
+	/** Stable across scans: hash of route, detector and element. */
+	id: string;
+	/** Route-independent key (detector + element), used to group the same issue across pages. */
+	fingerprint: string;
+	detector: DetectorId;
+	severity: Severity;
+	title: string;
+	/** Inclusive viewport-width ranges where the issue occurs. */
+	ranges: WidthRange[];
+	/** Width where the issue is most severe; details below are taken from here. */
+	worstAt: number;
+	/** `source` is where the element is written in the code, when the page gives that away. */
+	element: ElementInfo & {
+		source: SourceLocation | null;
+	};
+	related?: ElementInfo;
+	evidence: Record<string, number | string | boolean>;
+	styles: Record<string, string>;
+	/** Plain-language hint at the likely fix. */
+	suggestion?: string;
+	/** Screenshot file name inside the scan's screenshot directory. */
+	screenshot?: string;
+	/** Set when the issue only shows while something is open, such as the mobile menu. */
+	state?: PageState;
+	/** The browsers it shows in, when the page was scanned in more than one. */
+	browsers?: BrowserName[];
+}
+export interface Breakpoints {
+	/** Widths where the layout actually changes. */
+	observed: number[];
+	/** Widths declared by CSS media queries. */
+	declared: number[];
+	/** Widths where a container query switches (@container). */
+	containers?: number[];
+	/** Observed changes with no media or container query nearby. */
+	unexplained: number[];
+}
+export interface PageResult {
+	url: string;
+	/** Where the page ended up after redirects (e.g. a login page). */
+	finalUrl: string;
+	/**
+	 * `empty`: the page rendered (almost) nothing, usually because it crashed.
+	 * `login`: it sent the browser to a sign-in page instead.
+	 * `redirect` and `skipped`: left out on purpose; `error` says why.
+	 */
+	status: PageStatus;
+	error?: string;
+	/** Uncaught exceptions thrown by the page while it was scanned. */
+	pageErrors: string[];
+	/** Things that made this page's results less exact than usual. */
+	warnings: string[];
+	breakpoints: Breakpoints;
+	issues: Issue[];
+	/** Menus, dialogs and disclosures that were also scanned open. */
+	states?: ScannedState[];
+	/** Number of distinct widths that were measured. */
+	measurements: number;
+	durationMs: number;
+}
+export type PageStatus = "scanned" | "empty" | "error" | "login" | "redirect" | "skipped";
+export interface RouteResult extends PageResult {
+	/** Route pattern, e.g. `/products/[id]`, or the URL path for a plain URL. */
+	route: string;
+}
+/** Everything one run of breakhound produced. All reports are rendered from this. */
+export interface ScanResult {
+	schemaVersion: 1;
+	tool: {
+		name: "breakhound";
+		version: string;
+	};
+	project: {
+		framework: string | null;
+		baseUrl: string | null;
+		root: string | null;
+	};
+	startedAt: string;
+	durationMs: number;
+	settings: {
+		minWidth: number;
+		maxWidth: number;
+		step: number;
+		browsers: BrowserName[];
+	};
+	routes: RouteResult[];
+	/**
+	 * Set when the developer scanned in the browser extension and sent it to their agent: verify
+	 * then checks again in that same browser, so logins and the browser's own setup carry over.
+	 */
+	from?: "extension";
+	summary: {
+		routes: number;
+		issues: number;
+		/** Issues counted once even when the same element breaks on several routes. */
+		uniqueIssues: number;
+		/** Unique issues by severity. */
+		bySeverity: Record<Severity, number>;
+	};
+}
+/**
+ * The config file's shape. Everything is optional: with no config at all,
+ * breakhound finds the app, its routes and its dev server by itself.
+ */
+export interface BreakhoundConfig {
+	/** Where your app is running, e.g. http://localhost:3000. */
+	baseUrl?: string;
+	/** Pages to scan: paths (joined to baseUrl) or full URLs. Leave it out to find every route automatically. */
+	routes?: string[];
+	/** Only scan routes matching these globs, e.g. ['/blog/**']. `*` is one segment, `**` any number. */
+	include?: string[];
+	/** Skip routes matching these globs, e.g. ['/admin/**']. */
+	exclude?: string[];
+	/** A real URL for each dynamic route, e.g. { '/products/[id]': '/products/42' }. */
+	samples?: Record<string, string>;
+	/** Most routes to scan in one run (default 100). */
+	maxRoutes?: number;
+	/** How to start the app when it isn't running, if not with its "dev" script. */
+	server?: {
+		/** Command that starts the app, e.g. "npm run dev -- --port 4000". */
+		command?: string;
+		/** Port to wait on, when the command doesn't print its URL. */
+		port?: number;
+		/** Seconds to wait for the server to answer (default 120). */
+		timeout?: number;
+	};
+	/** Viewport widths to sweep, in CSS pixels. */
+	widths?: {
+		/** Narrowest width (default 320). */
+		min?: number;
+		/** Widest width (default 1920). */
+		max?: number;
+		/** Step of the first, coarse sweep before narrowing down (default 16). */
+		step?: number;
+	};
+	/** Turn a check off with `false`, or change how serious it is. */
+	detectors?: Partial<Record<DetectorId, boolean | Severity>>;
+	/** Elements to leave out: a CSS selector, or a selector limited to some checks. */
+	ignore?: (string | IgnoreRule)[];
+	/** Exit with code 1 when an issue at this level (or worse) is found. */
+	failOn?: Severity | "none";
+	/** Where reports are written. */
+	outDir?: string;
+	/** Take a screenshot of every issue. */
+	screenshots?: boolean;
+	/**
+	 * Also open menus, dialogs and expandable sections (the mobile menu, a
+	 * modal, an FAQ) and scan them open. A number sets the most to open on one
+	 * page (default 5); false turns it off.
+	 */
+	states?: boolean | number;
+	/** Also write report.pdf. */
+	pdf?: boolean;
+	/**
+	 * Browser engines to scan in: chromium, webkit (Safari's engine) and
+	 * firefox. The first finds the routes; the others check the same pages after
+	 * it, one at a time. Default ["chromium"].
+	 */
+	browsers?: ("chromium" | "webkit" | "firefox")[];
+	/**
+	 * Also show screenshots of each page at 375, 768 and 1280px to your own
+	 * vision model (the one `fix` uses, or set one here) and report what it
+	 * says looks off, as info. Off by default.
+	 */
+	vision?: boolean | {
+		provider?: "anthropic" | "openai" | "ollama";
+		model?: string;
+		widths?: number[];
+	};
+	/** The model `breakhound fix` uses; flags and environment variables work too. */
+	fix?: {
+		/** anthropic, openai (or any compatible API) or ollama. Picked from your environment when left out. */
+		provider?: "anthropic" | "openai" | "ollama";
+		model?: string;
+	};
+	/** Browser tabs to use at once (default: half your CPU cores, up to 4). */
+	concurrency?: number;
+	/**
+	 * Most memory the dev server and browser breakhound starts may use
+	 * together before it shuts them down, so a big app can't freeze your
+	 * computer: a size like "6GB", a share like "50%", or "off". Default 60% of
+	 * your memory, leaving at least 2 GB free.
+	 */
+	memoryLimit?: string | false;
+	/** How long to wait for the page to settle. */
+	settle?: {
+		/** Most milliseconds to wait for the network to go quiet after load (default 5000). */
+		networkIdleMs?: number;
+		/** Most milliseconds to wait for the layout to stop moving after a resize (default 1000). */
+		maxSettleMs?: number;
+	};
+}
+export declare function defineConfig(config: BreakhoundConfig): BreakhoundConfig;
+
+export {};

package/dist/index.d.ts

@@ -0,0 +1,254 @@
+export type Severity = "error" | "warning" | "info";
+export type DetectorId = "page-overflow" | "content-overflow" | "media-overflow" | "overlap" | "unexpected-wrap" | "clipped-text" | "squished-text" | "distorted-media" | "small-tap-target" | "tiny-text" | "oversized-text" | "edge-gutter" | "viewport-meta"
+/** Opt-in: what a vision model noticed in screenshots. Never run in the page. */
+ | "vision";
+/** Where an element comes from in the project's code. */
+export interface SourceLocation {
+	/** Path relative to the project root, with `/` separators. */
+	file: string;
+	line?: number;
+	column?: number;
+	/** The component that renders the element, when known. */
+	component?: string;
+	/**
+	 * True when this is the element's own line (from a source plugin or the
+	 * framework's dev info). False when it's only the file or component that
+	 * renders it, so the element is somewhere inside.
+	 */
+	exact: boolean;
+}
+export interface ElementInfo {
+	/** Shortest unique CSS selector, stable across viewport widths. */
+	selector: string;
+	/** Readable ancestry, e.g. `header > nav > ul`. */
+	path: string;
+	/** Trimmed outerHTML of the opening tag plus a short text preview. */
+	html: string;
+	text: string | null;
+	/** Where it's written in the code, when the page gives that away (dev builds only). */
+	source?: SourceLocation | null;
+}
+export interface IgnoreRule {
+	/** CSS selector; matching elements and everything inside them are ignored. */
+	selector: string;
+	/** Limit the rule to these detectors. Omit to ignore every detector. */
+	detectors?: DetectorId[];
+}
+/**
+ * What a toggle opens. `menu`: navigation menus, drawers and dropdowns.
+ * `disclosure`: anything else with aria-expanded, such as accordions.
+ */
+export type ToggleKind = "menu" | "dialog" | "popover" | "details" | "disclosure";
+export interface WidthRange {
+	from: number;
+	to: number;
+}
+export type BrowserName = "chromium" | "webkit" | "firefox";
+/** A menu, dialog or disclosure that was opened for part of the scan. */
+export interface PageState {
+	kind: ToggleKind;
+	/** The accessible name of what was clicked: "Menu", "Open main menu". */
+	label: string;
+	/** Selector of what was clicked to open it. */
+	trigger: string;
+}
+export interface ScannedState extends PageState {
+	/** Widths where it could be opened and was measured open. */
+	ranges: WidthRange[];
+}
+export interface Issue {
+	/** Stable across scans: hash of route, detector and element. */
+	id: string;
+	/** Route-independent key (detector + element), used to group the same issue across pages. */
+	fingerprint: string;
+	detector: DetectorId;
+	severity: Severity;
+	title: string;
+	/** Inclusive viewport-width ranges where the issue occurs. */
+	ranges: WidthRange[];
+	/** Width where the issue is most severe; details below are taken from here. */
+	worstAt: number;
+	/** `source` is where the element is written in the code, when the page gives that away. */
+	element: ElementInfo & {
+		source: SourceLocation | null;
+	};
+	related?: ElementInfo;
+	evidence: Record<string, number | string | boolean>;
+	styles: Record<string, string>;
+	/** Plain-language hint at the likely fix. */
+	suggestion?: string;
+	/** Screenshot file name inside the scan's screenshot directory. */
+	screenshot?: string;
+	/** Set when the issue only shows while something is open, such as the mobile menu. */
+	state?: PageState;
+	/** The browsers it shows in, when the page was scanned in more than one. */
+	browsers?: BrowserName[];
+}
+export interface Breakpoints {
+	/** Widths where the layout actually changes. */
+	observed: number[];
+	/** Widths declared by CSS media queries. */
+	declared: number[];
+	/** Widths where a container query switches (@container). */
+	containers?: number[];
+	/** Observed changes with no media or container query nearby. */
+	unexplained: number[];
+}
+export interface PageResult {
+	url: string;
+	/** Where the page ended up after redirects (e.g. a login page). */
+	finalUrl: string;
+	/**
+	 * `empty`: the page rendered (almost) nothing, usually because it crashed.
+	 * `login`: it sent the browser to a sign-in page instead.
+	 * `redirect` and `skipped`: left out on purpose; `error` says why.
+	 */
+	status: PageStatus;
+	error?: string;
+	/** Uncaught exceptions thrown by the page while it was scanned. */
+	pageErrors: string[];
+	/** Things that made this page's results less exact than usual. */
+	warnings: string[];
+	breakpoints: Breakpoints;
+	issues: Issue[];
+	/** Menus, dialogs and disclosures that were also scanned open. */
+	states?: ScannedState[];
+	/** Number of distinct widths that were measured. */
+	measurements: number;
+	durationMs: number;
+}
+export type PageStatus = "scanned" | "empty" | "error" | "login" | "redirect" | "skipped";
+export interface RouteResult extends PageResult {
+	/** Route pattern, e.g. `/products/[id]`, or the URL path for a plain URL. */
+	route: string;
+}
+/** Everything one run of breakhound produced. All reports are rendered from this. */
+export interface ScanResult {
+	schemaVersion: 1;
+	tool: {
+		name: "breakhound";
+		version: string;
+	};
+	project: {
+		framework: string | null;
+		baseUrl: string | null;
+		root: string | null;
+	};
+	startedAt: string;
+	durationMs: number;
+	settings: {
+		minWidth: number;
+		maxWidth: number;
+		step: number;
+		browsers: BrowserName[];
+	};
+	routes: RouteResult[];
+	/**
+	 * Set when the developer scanned in the browser extension and sent it to their agent: verify
+	 * then checks again in that same browser, so logins and the browser's own setup carry over.
+	 */
+	from?: "extension";
+	summary: {
+		routes: number;
+		issues: number;
+		/** Issues counted once even when the same element breaks on several routes. */
+		uniqueIssues: number;
+		/** Unique issues by severity. */
+		bySeverity: Record<Severity, number>;
+	};
+}
+/**
+ * The config file's shape. Everything is optional: with no config at all,
+ * breakhound finds the app, its routes and its dev server by itself.
+ */
+export interface BreakhoundConfig {
+	/** Where your app is running, e.g. http://localhost:3000. */
+	baseUrl?: string;
+	/** Pages to scan: paths (joined to baseUrl) or full URLs. Leave it out to find every route automatically. */
+	routes?: string[];
+	/** Only scan routes matching these globs, e.g. ['/blog/**']. `*` is one segment, `**` any number. */
+	include?: string[];
+	/** Skip routes matching these globs, e.g. ['/admin/**']. */
+	exclude?: string[];
+	/** A real URL for each dynamic route, e.g. { '/products/[id]': '/products/42' }. */
+	samples?: Record<string, string>;
+	/** Most routes to scan in one run (default 100). */
+	maxRoutes?: number;
+	/** How to start the app when it isn't running, if not with its "dev" script. */
+	server?: {
+		/** Command that starts the app, e.g. "npm run dev -- --port 4000". */
+		command?: string;
+		/** Port to wait on, when the command doesn't print its URL. */
+		port?: number;
+		/** Seconds to wait for the server to answer (default 120). */
+		timeout?: number;
+	};
+	/** Viewport widths to sweep, in CSS pixels. */
+	widths?: {
+		/** Narrowest width (default 320). */
+		min?: number;
+		/** Widest width (default 1920). */
+		max?: number;
+		/** Step of the first, coarse sweep before narrowing down (default 16). */
+		step?: number;
+	};
+	/** Turn a check off with `false`, or change how serious it is. */
+	detectors?: Partial<Record<DetectorId, boolean | Severity>>;
+	/** Elements to leave out: a CSS selector, or a selector limited to some checks. */
+	ignore?: (string | IgnoreRule)[];
+	/** Exit with code 1 when an issue at this level (or worse) is found. */
+	failOn?: Severity | "none";
+	/** Where reports are written. */
+	outDir?: string;
+	/** Take a screenshot of every issue. */
+	screenshots?: boolean;
+	/**
+	 * Also open menus, dialogs and expandable sections (the mobile menu, a
+	 * modal, an FAQ) and scan them open. A number sets the most to open on one
+	 * page (default 5); false turns it off.
+	 */
+	states?: boolean | number;
+	/** Also write report.pdf. */
+	pdf?: boolean;
+	/**
+	 * Browser engines to scan in: chromium, webkit (Safari's engine) and
+	 * firefox. The first finds the routes; the others check the same pages after
+	 * it, one at a time. Default ["chromium"].
+	 */
+	browsers?: ("chromium" | "webkit" | "firefox")[];
+	/**
+	 * Also show screenshots of each page at 375, 768 and 1280px to your own
+	 * vision model (the one `fix` uses, or set one here) and report what it
+	 * says looks off, as info. Off by default.
+	 */
+	vision?: boolean | {
+		provider?: "anthropic" | "openai" | "ollama";
+		model?: string;
+		widths?: number[];
+	};
+	/** The model `breakhound fix` uses; flags and environment variables work too. */
+	fix?: {
+		/** anthropic, openai (or any compatible API) or ollama. Picked from your environment when left out. */
+		provider?: "anthropic" | "openai" | "ollama";
+		model?: string;
+	};
+	/** Browser tabs to use at once (default: half your CPU cores, up to 4). */
+	concurrency?: number;
+	/**
+	 * Most memory the dev server and browser breakhound starts may use
+	 * together before it shuts them down, so a big app can't freeze your
+	 * computer: a size like "6GB", a share like "50%", or "off". Default 60% of
+	 * your memory, leaving at least 2 GB free.
+	 */
+	memoryLimit?: string | false;
+	/** How long to wait for the page to settle. */
+	settle?: {
+		/** Most milliseconds to wait for the network to go quiet after load (default 5000). */
+		networkIdleMs?: number;
+		/** Most milliseconds to wait for the layout to stop moving after a resize (default 1000). */
+		maxSettleMs?: number;
+	};
+}
+export declare function defineConfig(config: BreakhoundConfig): BreakhoundConfig;
+
+export {};

package/dist/index.js

@@ -0,0 +1,7 @@
+// src/define.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  defineConfig
+};