@inspector-agent/verifier 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HamHyunJun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @inspector-agent/verifier
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+헤드리스 Chromium(Playwright)으로 페이지를 **여러 뷰포트에서 스캔**해 레이아웃 결함을 규칙으로 탐지하고, 패치 전후를 **같은 상태에서 재측정**하는 검증기입니다. CI 에서 쓰는 `inspector-scan` CLI 를 포함합니다. [Inspector-Agent](https://github.com/HamHyunJun/Inspector-Agent) 의 일부입니다.
+
+탐지 종류: 가로·세로 오버플로우(연쇄 결함 묶음), 말줄임 없는 텍스트 잘림, 팝업 가려짐(stacking context 원인), **모달 포커스 이탈**(실제 Tab/Shift+Tab 입력).
+
+## 설치
+
+```bash
+npm install -D @inspector-agent/verifier
+npx playwright-core@1.56.1 install chromium   # 브라우저가 없다면 한 번 (또는 INSPECTOR_CHROMIUM_PATH 로 경로 지정)
+```
+
+Node 20 이상.
+
+## CLI
+
+```bash
+npx inspector-scan http://localhost:5173 --viewports 375,768,1280 --fail-on high
+```
+
+| 옵션 | 설명 |
+| --- | --- |
+| `--viewports 375,768x1024` | 뷰포트 너비(또는 `너비x높이`) 목록. 기본 375, 768, 1280 |
+| `--fail-on high\|medium\|low` | 해당 심각도 이상 결함이 하나라도 있으면 종료 코드 1 |
+| `--summary 파일` | 마크다운 요약을 파일에 덧붙임. GitHub Actions 에서는 `"$GITHUB_STEP_SUMMARY"` |
+| `--scenario 파일.json` | 스캔 전에 시드(localStorage/sessionStorage/쿠키)를 심고 단계(click/fill/wait)를 실행 |
+| `--report http://localhost:3000` | 결과를 Inspector-Agent 대시보드로 전송 |
+
+종료 코드: `0` 통과 · `1` 기준 초과 · `2` 사용법 오류 또는 스캔 실패.
+
+GitHub Actions 예시:
+
+```yaml
+- run: npx inspector-scan http://localhost:3000 --fail-on high --summary "$GITHUB_STEP_SUMMARY"
+```
+
+데이터가 있어야 그려지는 화면이나 클릭해야 열리는 UI 는 [시나리오](https://github.com/HamHyunJun/Inspector-Agent/blob/main/docs/scenarios/README.md)로 스캔합니다. 소스 위치(`파일:라인`)까지 보려면 앱의 개발 서버에 [`@inspector-agent/vite-plugin`](https://www.npmjs.com/package/@inspector-agent/vite-plugin) 을 켜세요.
+
+## API
+
+```ts
+import { scanPage, measureDefect } from '@inspector-agent/verifier'
+
+const [mobile] = await scanPage('http://localhost:5173', [{ width: 375, height: 812 }])
+const target = mobile.defects[0]
+// 패치를 적용한 뒤, 같은 URL·뷰포트·시나리오에서 다시 재서 통과 여부를 판정
+const result = await measureDefect(target, mobile.defects)
+console.log(result.passed, result.verdict)
+```
+
+통과 조건은 "대상 결함이 사라지고 새 결함이 없을 때"입니다. 가려짐은 비율이 0% 가 되어야 하고, 포커스 이탈은 두 방향 모두 막혀야 합니다.
+
+## 라이선스
+
+MIT

package/dist/chunk-7XQGXD7A.js

@@ -0,0 +1,228 @@
+// src/index.ts
+import { readFile } from "fs/promises";
+import { createRequire } from "module";
+import { chromium } from "playwright-core";
+import { DEFAULT_MIN_COVERED_RATIO, defectMagnitude, qualifyDefectId, scenarioKey } from "@inspector-agent/core";
+
+// src/focus.ts
+import { createDefectId, createFingerprint, diagnoseFocus } from "@inspector-agent/core";
+var buildFocusDefect = (modal, result, context) => {
+  const fingerprint = createFingerprint("focus-escape", modal.node.source, modal.node.selector, context.viewport.width);
+  const metrics = {
+    kind: "focus-escape",
+    trigger: modal.trigger,
+    focusableCount: modal.focusableCount,
+    escapesForward: result.forward !== void 0,
+    escapesBackward: result.backward !== void 0,
+    tabsToEscape: result.forward?.presses,
+    escapedTo: result.forward?.escapedTo ?? result.backward?.escapedTo
+  };
+  return {
+    id: createDefectId(context.url, fingerprint),
+    fingerprint,
+    kind: "focus-escape",
+    // 키보드 사용자가 모달 뒤의 페이지를 조작하게 되므로 항상 높음
+    severity: "high",
+    url: context.url,
+    viewport: context.viewport,
+    node: modal.node,
+    parent: modal.parent,
+    metrics,
+    suggestions: diagnoseFocus(metrics),
+    detectedAt: context.detectedAt
+  };
+};
+var probeDirection = async (page, modal, key, maxPresses, sourceAttribute) => {
+  const focused = await page.evaluate((index) => window.__INSPECTOR_AGENT__?.focusFirstInModal(index) ?? false, modal.index);
+  if (!focused) return void 0;
+  for (let presses = 1; presses <= maxPresses; presses++) {
+    await page.keyboard.press(key);
+    const state = await page.evaluate(
+      ({ index, attribute }) => window.__INSPECTOR_AGENT__?.modalFocusState(index, { sourceAttribute: attribute }) ?? { inside: true },
+      { index: modal.index, attribute: sourceAttribute }
+    );
+    if (!state.inside) return { presses, state };
+  }
+  return void 0;
+};
+var scanFocusEscapes = async (page, url, viewport, detect = {}) => {
+  const modals = await page.evaluate(
+    (options) => window.__INSPECTOR_AGENT__?.findModals(options) ?? [],
+    { sourceAttribute: detect.sourceAttribute }
+  );
+  const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const defects = [];
+  for (const modal of modals) {
+    const forward = await probeDirection(page, modal, "Tab", modal.focusableCount + 1, detect.sourceAttribute);
+    const backward = await probeDirection(page, modal, "Shift+Tab", 1, detect.sourceAttribute);
+    if (!forward && !backward) continue;
+    defects.push(
+      buildFocusDefect(
+        modal,
+        {
+          forward: forward ? { presses: forward.presses, escapedTo: forward.state.active } : void 0,
+          backward: backward ? { escapedTo: backward.state.active } : void 0
+        },
+        { url, viewport, detectedAt }
+      )
+    );
+  }
+  return defects;
+};
+
+// src/scenario.ts
+import { toStorageString } from "@inspector-agent/core";
+var STEP_TIMEOUT_MS = 5e3;
+var seedContext = async (context, url, scenario) => {
+  const seed = scenario.seed;
+  if (!seed) return;
+  if (seed.cookies?.length) {
+    const { hostname } = new URL(url);
+    await context.addCookies(
+      seed.cookies.map((cookie) => cookie.path ? { name: cookie.name, value: cookie.value, domain: hostname, path: cookie.path } : { name: cookie.name, value: cookie.value, url })
+    );
+  }
+  const toStrings = (values) => Object.fromEntries(Object.entries(values ?? {}).map(([key, value]) => [key, toStorageString(value)]));
+  const local = toStrings(seed.localStorage);
+  const session = toStrings(seed.sessionStorage);
+  if (Object.keys(local).length === 0 && Object.keys(session).length === 0) return;
+  await context.addInitScript(
+    ({ local: localValues, session: sessionValues }) => {
+      const write = (storage, values) => {
+        for (const [key, value] of Object.entries(values)) storage.setItem(key, value);
+      };
+      try {
+        write(window.localStorage, localValues);
+        write(window.sessionStorage, sessionValues);
+      } catch {
+      }
+    },
+    { local, session }
+  );
+};
+var describeStep = (step) => {
+  if (step.action === "wait") return step.selector !== void 0 ? `wait ${step.selector}` : `wait ${step.ms}ms`;
+  return `${step.action} ${step.selector}`;
+};
+var runScenarioSteps = async (page, steps) => {
+  for (const [index, step] of steps.entries()) {
+    try {
+      if (step.action === "click") await page.click(step.selector, { timeout: STEP_TIMEOUT_MS });
+      else if (step.action === "fill") await page.fill(step.selector, step.value, { timeout: STEP_TIMEOUT_MS });
+      else if (step.selector !== void 0) await page.waitForSelector(step.selector, { state: "visible", timeout: STEP_TIMEOUT_MS });
+      else await page.waitForTimeout(step.ms ?? 0);
+    } catch (error) {
+      const reason = (error instanceof Error ? error.message : String(error)).split("\n")[0];
+      throw new Error(`\uC2DC\uB098\uB9AC\uC624 steps[${index}] (${describeStep(step)}) \uC2E4\uD328: ${reason}`);
+    }
+  }
+};
+
+// src/index.ts
+var DEFAULT_VIEWPORTS = [
+  { width: 375, height: 812 },
+  { width: 768, height: 1024 },
+  { width: 1280, height: 800 }
+];
+var require2 = createRequire(import.meta.url);
+var detectorSource;
+var loadDetectorSource = async () => {
+  if (detectorSource) return detectorSource;
+  const path = require2.resolve("@inspector-agent/core/detector.global.js");
+  detectorSource = await readFile(path, "utf8");
+  return detectorSource;
+};
+var launch = async (options) => chromium.launch({
+  headless: true,
+  executablePath: options.executablePath ?? process.env.INSPECTOR_CHROMIUM_PATH ?? void 0
+});
+var scanWithBrowser = async (browser, url, viewport, options) => {
+  const context = await browser.newContext({ viewport });
+  try {
+    const { scenario } = options;
+    if (scenario) await seedContext(context, url, scenario);
+    const page = await context.newPage();
+    await page.goto(url, { waitUntil: "networkidle" });
+    await page.waitForTimeout(options.settleMs ?? 300);
+    if (scenario?.steps?.length) {
+      await runScenarioSteps(page, scenario.steps);
+      await page.waitForTimeout(options.settleMs ?? 300);
+    }
+    await page.addScriptTag({ content: await loadDetectorSource() });
+    const result = await page.evaluate((detectOptions) => {
+      const agent = window.__INSPECTOR_AGENT__;
+      if (!agent) throw new Error("Inspector-Agent \uD0D0\uC9C0\uAE30 \uC8FC\uC785\uC5D0 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4.");
+      return agent.detect(detectOptions);
+    }, options.detect ?? {});
+    const focusDefects = await scanFocusEscapes(page, result.url, viewport, options.detect);
+    const defects = [...result.defects, ...focusDefects];
+    if (!scenario) return { ...result, defects };
+    const key = scenarioKey(scenario);
+    return {
+      ...result,
+      scenarioKey: key,
+      defects: defects.map((defect) => ({ ...defect, id: qualifyDefectId(defect.id, key), scenarioKey: key }))
+    };
+  } finally {
+    await context.close();
+  }
+};
+var scanPage = async (url, viewports = DEFAULT_VIEWPORTS, options = {}) => {
+  const browser = await launch(options);
+  try {
+    const results = [];
+    for (const viewport of viewports) {
+      results.push(await scanWithBrowser(browser, url, viewport, options));
+    }
+    return results;
+  } finally {
+    await browser.close();
+  }
+};
+var isSameDefect = (target, candidate) => candidate.fingerprint === target.fingerprint || candidate.node.selector === target.node.selector;
+var MEASURE_UNIT = { "overflow-x": "px", "overflow-y": "px", "clipped-text": "px", occluded: "ratio", "focus-escape": "count" };
+var SUBJECT = { "overflow-x": "\uC624\uBC84\uD50C\uB85C\uC6B0", "overflow-y": "\uC138\uB85C \uC624\uBC84\uD50C\uB85C\uC6B0", "clipped-text": "\uD14D\uC2A4\uD2B8 \uC798\uB9BC", occluded: "\uAC00\uB824\uC9D0", "focus-escape": "\uD3EC\uCEE4\uC2A4 \uC774\uD0C8" };
+var describeMagnitude = (defect, value) => {
+  const unit = MEASURE_UNIT[defect.kind];
+  return unit === "ratio" ? `${Math.round(value * 100)}%` : unit === "count" ? `${value}\uBC29\uD5A5` : `${Math.round(value)}px`;
+};
+var measureDefect = async (target, baseline, options = {}) => {
+  const browser = await launch(options);
+  try {
+    const detect = target.kind === "occluded" ? { ...options.detect, minCoveredRatio: 0.01 } : options.detect;
+    const result = await scanWithBrowser(browser, target.url, target.viewport, { ...options, detect });
+    const remaining = result.defects.find((defect) => isSameDefect(target, defect));
+    const regressions = result.defects.filter(
+      (defect) => !isSameDefect(target, defect) && !baseline.some((known) => isSameDefect(known, defect)) && (defect.kind !== "occluded" || defect.metrics.coveredRatio >= DEFAULT_MIN_COVERED_RATIO)
+    );
+    const before = defectMagnitude(target);
+    const after = remaining ? defectMagnitude(remaining) : 0;
+    const passed = remaining === void 0 && regressions.length === 0;
+    const subject = SUBJECT[target.kind];
+    const verdict = passed ? `${subject} ${describeMagnitude(target, before)} \u2192 ${describeMagnitude(target, 0)}, \uC0C8 \uACB0\uD568 \uC5C6\uC74C` : remaining ? `${subject} ${describeMagnitude(target, before)} \u2192 ${describeMagnitude(target, after)}\uB85C \uB0A8\uC544 \uC788\uC2B5\uB2C8\uB2E4` : `\uB300\uC0C1 \uACB0\uD568\uC740 \uC0AC\uB77C\uC84C\uC9C0\uB9CC \uC0C8 \uACB0\uD568 ${regressions.length}\uAC74\uC774 \uC0DD\uACBC\uC2B5\uB2C8\uB2E4`;
+    return {
+      passed,
+      verdict,
+      stillPresent: remaining !== void 0,
+      unit: MEASURE_UNIT[target.kind],
+      beforePx: before,
+      afterPx: after,
+      regressions,
+      documentOverflowPx: result.documentOverflowPx,
+      measuredAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  } finally {
+    await browser.close();
+  }
+};
+var parseViewports = (value) => value.split(",").map((part) => part.trim()).filter((part) => part !== "").map((part) => {
+  const [width = "0", height] = part.split("x");
+  return { width: Number(width), height: height ? Number(height) : 900 };
+});
+
+export {
+  DEFAULT_VIEWPORTS,
+  scanPage,
+  measureDefect,
+  parseViewports
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import {
+  DEFAULT_VIEWPORTS,
+  parseViewports,
+  scanPage
+} from "./chunk-7XQGXD7A.js";
+
+// src/cli.ts
+import { appendFile, readFile } from "fs/promises";
+import { formatMagnitude as formatMagnitude2, parseScenario } from "@inspector-agent/core";
+
+// src/report.ts
+import { formatMagnitude } from "@inspector-agent/core";
+var SEVERITY_RANK = { low: 0, medium: 1, high: 2 };
+var SEVERITY_LABEL = { high: "\u{1F534} high", medium: "\u{1F7E0} medium", low: "\u{1F7E1} low" };
+var parseFailOn = (value) => {
+  if (value === void 0) return void 0;
+  if (value === "high" || value === "medium" || value === "low") return value;
+  throw new Error(`--fail-on \uC740 high, medium, low \uC911 \uD558\uB098\uC5EC\uC57C \uD569\uB2C8\uB2E4 (\uBC1B\uC740 \uAC12: ${value || "\uC5C6\uC74C"})`);
+};
+var defectsAtOrAbove = (results, threshold) => results.flatMap((result) => result.defects.filter((defect) => SEVERITY_RANK[defect.severity] >= SEVERITY_RANK[threshold]));
+var cell = (text) => text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+var locationOf = (defect) => defect.node.source ? `${defect.node.source.file}:${defect.node.source.line}` : defect.node.selector;
+var renderMarkdown = (url, results, failOn, scenarioName) => {
+  const total = results.reduce((sum, result) => sum + result.defects.length, 0);
+  const failing = failOn ? defectsAtOrAbove(results, failOn).length : 0;
+  const verdict = failOn ? failing > 0 ? `\u274C \uC2E4\uD328: \`${failOn}\` \uC774\uC0C1 ${failing}\uAC74` : `\u2705 \uD1B5\uACFC: \`${failOn}\` \uC774\uC0C1 \uC5C6\uC74C` : "(\uD1B5\uACFC/\uC2E4\uD328 \uAE30\uC900 \uC5C6\uC74C)";
+  const lines = ["## Inspector-Agent \uB808\uC774\uC544\uC6C3 \uC2A4\uCE94", "", `- \uB300\uC0C1: ${url}`, ...scenarioName ? [`- \uC2DC\uB098\uB9AC\uC624: ${scenarioName}`] : [], `- \uBDF0\uD3EC\uD2B8: ${results.map((result) => `${result.viewport.width}px`).join(", ")}`, `- \uACB0\uD568: ${total}\uAC74 \xB7 ${verdict}`];
+  if (total === 0) return `${lines.join("\n")}
+
+\uACB0\uD568\uC774 \uC5C6\uC2B5\uB2C8\uB2E4. \u2705
+`;
+  lines.push("", "| \uBDF0\uD3EC\uD2B8 | \uC2EC\uAC01\uB3C4 | \uC704\uCE58 | \uC885\uB958 | \uD06C\uAE30 | \uC9C4\uB2E8 |", "| --- | --- | --- | --- | --- | --- |");
+  for (const result of results) {
+    for (const defect of result.defects) {
+      const hints = defect.suggestions.map((suggestion) => suggestion.hint).join(", ") || "-";
+      lines.push(
+        `| ${result.viewport.width}px | ${SEVERITY_LABEL[defect.severity]} | \`${cell(locationOf(defect))}\` | ${defect.kind} | ${cell(formatMagnitude(defect))} | ${cell(hints)} |`
+      );
+    }
+  }
+  return `${lines.join("\n")}
+`;
+};
+
+// src/cli.ts
+var readFlag = (args, name) => {
+  const index = args.indexOf(name);
+  return index === -1 ? void 0 : args[index + 1];
+};
+var main = async () => {
+  const args = process.argv.slice(2);
+  const url = args.find((arg) => /^https?:\/\//.test(arg));
+  if (!url) {
+    console.error("\uC0AC\uC6A9\uBC95: inspector-scan <url> [--viewports 375,768,1280] [--report <\uB300\uC2DC\uBCF4\uB4DC URL>] [--fail-on high|medium|low] [--summary <\uD30C\uC77C>] [--scenario <\uD30C\uC77C.json>]");
+    process.exitCode = 2;
+    return;
+  }
+  const viewportFlag = readFlag(args, "--viewports");
+  const report = readFlag(args, "--report");
+  const summaryFile = readFlag(args, "--summary");
+  const scenarioFile = readFlag(args, "--scenario");
+  const failOn = parseFailOn(args.includes("--fail-on") ? readFlag(args, "--fail-on") ?? "" : void 0);
+  let scenario;
+  if (scenarioFile) {
+    try {
+      scenario = parseScenario(JSON.parse(await readFile(scenarioFile, "utf8")));
+    } catch (error) {
+      throw new Error(`--scenario ${scenarioFile} \uB97C \uC77D\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    console.log(`\uC2DC\uB098\uB9AC\uC624: ${scenario.name ?? scenarioFile}`);
+  }
+  const results = await scanPage(url, viewportFlag ? parseViewports(viewportFlag) : DEFAULT_VIEWPORTS, { scenario });
+  for (const result of results) {
+    console.log(`
+[${result.viewport.width}px] \uACB0\uD568 ${result.defects.length}\uAC74, \uBB38\uC11C \uAC00\uB85C \uC2A4\uD06C\uB864 ${result.documentOverflowPx}px`);
+    for (const defect of result.defects) {
+      const source = defect.node.source ? `${defect.node.source.file}:${defect.node.source.line}` : defect.node.selector;
+      const hints = defect.suggestions.map((suggestion) => suggestion.hint).join(", ");
+      console.log(`  - [${defect.severity}] ${source} ${formatMagnitude2(defect)} (${hints})`);
+    }
+  }
+  if (report) {
+    const response = await fetch(new URL("/api/scans", report), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ results, scenario })
+    });
+    console.log(`
+\uB300\uC2DC\uBCF4\uB4DC \uC804\uC1A1: ${response.status}`);
+  }
+  if (summaryFile) await appendFile(summaryFile, `${renderMarkdown(url, results, failOn, scenario?.name)}
+`, "utf8");
+  if (failOn) {
+    const failing = defectsAtOrAbove(results, failOn);
+    if (failing.length > 0) {
+      console.error(`
+\uC2E4\uD328: --fail-on ${failOn} \uAE30\uC900 ${failing.length}\uAC74`);
+      process.exitCode = 1;
+    } else {
+      console.log(`
+\uD1B5\uACFC: ${failOn} \uC774\uC0C1 \uACB0\uD568 \uC5C6\uC74C`);
+    }
+  }
+};
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 2;
+});

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { Viewport, Defect, DetectOptions, Scenario, ScanResult } from '@inspector-agent/core';
+
+interface VerifierOptions {
+    /** Chromium 실행 파일 경로. 미지정 시 INSPECTOR_CHROMIUM_PATH, 그다음 Playwright 기본 설치본 */
+    executablePath?: string;
+    detect?: DetectOptions;
+    /** 페이지 로드 후 레이아웃 안정화를 기다리는 시간(ms). 기본 300 */
+    settleMs?: number;
+    /** 스캔 전에 시드를 심고 단계를 실행할 시나리오. 스캔과 패치 후 재측정이 같은 값을 넘기면 같은 상태에서 잰다 */
+    scenario?: Scenario;
+}
+interface DefectMeasurement {
+    /** 같은 fingerprint(또는 셀렉터)의 결함이 아직 남아 있는지 */
+    stillPresent: boolean;
+    /** 패치 전/후 측정값. unit 이 px 이면 오버플로우 양, ratio 이면 가려진 비율(0~1), count 이면 포커스가 빠져나가는 방향 수(0~2) */
+    unit: 'px' | 'ratio' | 'count';
+    beforePx: number;
+    afterPx: number;
+    /** 패치 후 같은 뷰포트에 새로 생긴 결함 (회귀) */
+    regressions: Defect[];
+    documentOverflowPx: number;
+}
+interface VerificationResult extends DefectMeasurement {
+    passed: boolean;
+    verdict: string;
+    measuredAt: string;
+}
+declare const DEFAULT_VIEWPORTS: Viewport[];
+/** 하나의 URL을 여러 뷰포트에서 스캔한다 */
+declare const scanPage: (url: string, viewports?: Viewport[], options?: VerifierOptions) => Promise<ScanResult[]>;
+/**
+ * 패치 적용 후 같은 URL·뷰포트에서 다시 측정한다.
+ * "LLM이 고쳤다고 주장"하는 대신 수치가 실제로 0이 되었는지, 새 결함이 생기지 않았는지로 판정한다.
+ * - overflow-x: 오버플로우 px 가 0
+ * - occluded: 가려진 비율이 0. 일부만 풀린 경우(클릭이 여전히 막힘)는 실패이므로 탐지 임계값을 낮춰 잔여 가려짐까지 본다
+ * baseline 은 패치 전 같은 뷰포트의 결함 목록이며, 여기에 없던 결함은 회귀로 본다.
+ */
+declare const measureDefect: (target: Defect, baseline: Defect[], options?: VerifierOptions) => Promise<VerificationResult>;
+declare const parseViewports: (value: string) => Viewport[];
+
+export { DEFAULT_VIEWPORTS, type DefectMeasurement, type VerificationResult, type VerifierOptions, measureDefect, parseViewports, scanPage };

package/dist/index.js

@@ -0,0 +1,12 @@
+import {
+  DEFAULT_VIEWPORTS,
+  measureDefect,
+  parseViewports,
+  scanPage
+} from "./chunk-7XQGXD7A.js";
+export {
+  DEFAULT_VIEWPORTS,
+  measureDefect,
+  parseViewports,
+  scanPage
+};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@inspector-agent/verifier",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Playwright 로 여러 뷰포트를 스캔하고(inspector-scan CLI) 패치 전후를 재측정하는 레이아웃 결함 검증기",
+  "license": "MIT",
+  "author": "HamHyunJun",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HamHyunJun/Inspector-Agent.git",
+    "directory": "packages/verifier"
+  },
+  "homepage": "https://github.com/HamHyunJun/Inspector-Agent/tree/main/packages/verifier#readme",
+  "bugs": {
+    "url": "https://github.com/HamHyunJun/Inspector-Agent/issues"
+  },
+  "keywords": [
+    "playwright",
+    "layout",
+    "overflow",
+    "viewport",
+    "cli",
+    "ci",
+    "accessibility",
+    "focus-trap"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "inspector-scan": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "playwright-core": "1.56.1",
+    "@inspector-agent/core": "^0.2.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }