@inspector-agent/core

@inspector-agent/core

Inspector-Agent 의 공용 엔진입니다. 실제 브라우저 렌더링에서 레이아웃 결함을 규칙으로(LLM 없이) 탐지하고, 결함을 에이전트가 읽기 좋은 압축 컨텍스트로 바꾸는 순수 함수와 타입을 제공합니다.

대부분은 이 패키지를 직접 쓰지 않고 @inspector-agent/verifier(CLI)나 @inspector-agent/vite-plugin을 씁니다. 직접 쓰는 경우는 다음과 같습니다.

• 자체 도구에서 탐지기를 페이지에 주입해 결과를 받을 때
• 스캔 시나리오(JSON)를 검증하거나, 결함을 URL 과 무관하게 묶거나, 에이전트용 페이로드로 압축할 때

설치

npm install @inspector-agent/core

Node 20 이상, ESM 전용입니다.

브라우저에 탐지기 주입

detector.global.js 는 페이지에서 실행되는 IIFE 번들이며 window.__INSPECTOR_AGENT__.detect() 를 노출합니다.

import { readFile } from 'node:fs/promises'
import { createRequire } from 'node:module'
import { chromium } from 'playwright-core'
import type { ScanResult } from '@inspector-agent/core'

const detectorPath = createRequire(import.meta.url).resolve('@inspector-agent/core/detector.global.js')
const browser = await chromium.launch()
const page = await browser.newPage({ viewport: { width: 375, height: 812 } })
await page.goto('http://localhost:5173')
await page.addScriptTag({ content: await readFile(detectorPath, 'utf8') })
const result = await page.evaluate((): ScanResult => window.__INSPECTOR_AGENT__!.detect())
console.log(result.defects.map((defect) => `${defect.severity} ${defect.node.selector}`))
await browser.close()

탐지 종류는 overflow-x(가로 넘침, 같은 줄의 연쇄 결함 묶음 포함), overflow-y(높이가 고정된 컨테이너 밖으로 세로 넘침), clipped-text(말줄임 없이 잘리는 텍스트), occluded(팝업이 다른 요소에 가려짐, stacking context 원인 분석)입니다. 모달 포커스 이탈(focus-escape)은 실제 키 입력이 필요해 @inspector-agent/verifier 가 검사합니다.

주요 API

타입(Defect, ScanResult, Scenario 등)은 모두 index.d.ts 로 제공됩니다.

라이선스

MIT