page-analyzer 1.2.1 → 1.2.3

package/.env.example

@@ -0,0 +1,36 @@
+# ----------------------------------------------------------------------------
+# LLM backend
+# ----------------------------------------------------------------------------
+# Three backends are supported via LLM_TYPE:
+#   openai   - OpenAI-compatible HTTP API (default; needs API key + endpoint)
+#   codex    - Local `codex exec` CLI (uses your local codex auth, no API key)
+#   claude   - Local `claude -p` CLI  (uses your local claude auth, no API key)
+LLM_TYPE=openai
+
+# Model name. Required for all backends.
+#   openai : e.g. gpt-4, gpt-4o, gpt-5-mini, ...
+#   codex  : e.g. gpt-5-codex, gpt-5.5 (gpt-5.5 auto-enables service_tier=fast)
+#   claude : e.g. sonnet, opus, haiku, claude-sonnet-4-6, ...
+LLM_MODEL=gpt-4
+
+# Required only when LLM_TYPE=openai
+LLM_API_ENDPOINT=https://api.openai.com/v1/chat/completions
+LLM_API_KEY=sk-your-openai-or-compatible-key
+
+# ----------------------------------------------------------------------------
+# S3 screenshot upload (optional)
+# Only used when the calling code wires `extractorConfig.s3` from these vars
+# (page-analyzer itself does not read them). Leave unset to keep screenshots
+# on local disk.
+# ----------------------------------------------------------------------------
+# S3_BUCKET=my-page-analyzer-bucket
+# S3_REGION=ap-northeast-1
+# S3_PREFIX=page-analyzer/snapshots
+# S3_PUBLIC_BASE_URL=https://cdn.example.com
+# S3_ACCESS_KEY_ID=
+# S3_SECRET_ACCESS_KEY=
+
+# ----------------------------------------------------------------------------
+# Result viewer (scripts/serve-result-viewer.js)
+# ----------------------------------------------------------------------------
+# PORT=4173

package/README.md

@@ -114,6 +114,8 @@ const result = await analyzeUrl('https://example.com', {
   },
   showEvents: true,
   showBlockIdx: true,
+  showElement: true,
+  elementSize: 24,
   fullPageScreenshot: true,
   blockScreenshots: true,
   waitForImagesLoaded: true,
@@ -148,6 +150,8 @@ const result = await analyzeUrl('https://example.com', {
 | `options.extractorConfig` | `object` | 否 | Playwright 页面抓取配置 |
 | `options.showEvents` | `boolean` | 否 | 是否返回完整事件数组和元素明细 |
 | `options.showBlockIdx` | `boolean` | 否 | 是否返回 CSV 与区块索引相关字段 |
+| `options.showElement` | `boolean` | 否 | 是否采集所有"有尺寸"的可见 DOM 元素并嵌套到各区块的 `elements` 下，默认 `false`（不开启时走之前的逻辑，不采集） |
+| `options.elementSize` | `number` | 否 | `showElement` 的尺寸阈值（px），元素满足 `width > elementSize 或 height > elementSize` 才返回，默认 `24` |
 | `options.fullPageScreenshot` | `boolean` | 否 | 是否保存整页截图到当前运行目录的 `snapshots/` 并返回文件路径 |
 | `options.blockScreenshots` | `boolean` | 否 | 是否在 LLM 合并区块后，保存每个逻辑区块截图到当前运行目录的 `snapshots/` 并返回文件路径 |
 | `options.waitForImagesLoaded` | `boolean` | 否 | 是否在提取区块、分析和截图前等待页面图片加载完成，默认 `false` |
@@ -189,6 +193,7 @@ const result = await analyzePageEvents({
 | `url` | `string` | 是 | 页面 URL，用于解析相对链接 |
 | `blocks` | `Array` | 否 | 视觉区块快照 |
 | `elementGeometries` | `Array` | 否 | 页面中交互元素的几何信息 |
+| `sizedElements` | `Array` | 否 | 页面中所有"有尺寸"的可见元素（`width > 24 或 height > 24`），会按几何位置嵌套到对应区块的 `elements` 下 |
 | `llm` | `object` | 是 | LLM 配置 |
 | `knownEventTypes` | `string[]` | 否 | 已知事件类型 |
 | `parserConfig` | `object` | 否 | HTML 解析配置 |
@@ -223,7 +228,26 @@ const result = await analyzePageEvents({
           blockDescription: '...',
           blockSemantics: [],
           blockCssPath: '...',
-          blockPosition: {}
+          blockPosition: {},
+          elements: [
+            {
+              tag: 'a',
+              text: 'Sign up',
+              href: 'https://example.com/signup',
+              src: '',
+              width: 80,
+              height: 30,
+              top: 0,
+              left: 0,
+              cssSelector: 'body > main:nth-of-type(1) > section:nth-of-type(1) > a:nth-of-type(1)',
+              id: '',
+              class: 'cta',
+              role: '',
+              ariaLabel: '',
+              imageAlt: '',
+              interactive: true
+            }
+          ]
         }
       ],
       stats: {
@@ -234,6 +258,8 @@ const result = await analyzePageEvents({
 }
 ```
 
+启用 `showElement: true` 后，每个区块会带上 `elements` 数组，列出该区块下所有"有尺寸"的可见 DOM 元素（任意标签，`width > elementSize 或 height > elementSize`，默认阈值 24），按 `top, left` 排序；每个元素携带原始信息：`tag, text, href, src, width, height, top, left, cssSelector, id, class, role, ariaLabel, imageAlt, interactive`（坐标含滚动偏移）。极少数无法归入任何区块的元素（页面无视觉区块时）会放在 `analysis.block_analysis.unassignedElements`。不开启 `showElement` 时不会采集这些元素，走之前的逻辑。阈值通过 `elementSize`（或 `extractorConfig.sizedElementMinSize`）调整。
+
 启用 `showEvents: true` 后，输出会包含更多用于调试和下游处理的字段，例如：
 
 - `elements`：解析出的页面元素明细
@@ -250,7 +276,7 @@ const result = await analyzePageEvents({
 
 启用 `blockScreenshots: true` 后，模块会在 LLM 合并区块后再截图。返回结果会包含 `screenshots.blocks`，每项包含逻辑区块序号 `blockIdx` 和对应截图 `path`；区块分析结果中的每个 block 也会额外带上 `blockScreenshotPaths`，每个逻辑区块最多对应一张截图。无法通过 `blockCssPath` 截图的隐藏或空区块会被跳过。
 
-如果配置 `extractorConfig.s3`，截图不会写入本地 `snapshots/`，而是直接上传到 S3；`screenshots.fullPage`、`screenshots.blocks[].path` 和 `blockScreenshotPaths` 会返回 HTTPS URL。上传不会设置 ACL，访问权限沿用 bucket 策略。单张截图上传失败会重试 3 次，仍失败则跳过该截图。
+如果配置 `extractorConfig.s3`，截图不会写入本地 `snapshots/`，而是直接上传到 S3；`screenshots.fullPage`、`screenshots.blocks[].path` 和 `blockScreenshotPaths` 会返回 HTTPS URL。S3 对象 key 使用 `<prefix>/<domain>/<file-md5>.png`，上传前会先检查对象是否已存在，已存在时直接返回对应 URL，避免重复上传和冗余对象。上传不会设置 ACL，访问权限沿用 bucket 策略。单张截图检查或上传失败会重试 3 次，仍失败则跳过该截图。
 
 启用 `waitForImagesLoaded: true` 后，模块会先滚动页面触发懒加载，再等待当前 DOM 中的 `<img>` 完成加载或失败，之后再提取区块、分析和截图；等待时间受 `extractorConfig.timeoutMs` 控制。
 
@@ -316,7 +342,7 @@ const result = await analyzeUrl('https://example.com', {
 });
 ```
 
-`extractorConfig.s3.bucket` 和 `extractorConfig.s3.region` 必填。`credentials` 可省略，省略时使用 AWS SDK 默认凭证链。`publicBaseUrl` 可省略，省略时返回 `https://<bucket>.s3.<region>.amazonaws.com/<key>`；配置后返回 `${publicBaseUrl}/<key>`。
+`extractorConfig.s3.bucket` 和 `extractorConfig.s3.region` 必填。`credentials` 可省略，省略时使用 AWS SDK 默认凭证链。`publicBaseUrl` 可省略，省略时返回 `https://<bucket>.s3.<region>.amazonaws.com/<key>`；配置后返回 `${publicBaseUrl}/<key>`。启用 S3 上传时，需要凭证具备 `s3:GetObject` 和 `s3:PutObject` 权限；如果希望不存在的对象能被稳定识别为 404，还需要对应 bucket/prefix 的 `s3:ListBucket` 权限。
 
 ### parserConfig
 

package/extractors/block-assigner.js

@@ -56,7 +56,7 @@ function overlapArea(rectA, rectB) {
   return width * height;
 }
 
-function mapRectToBlock(rect, blocks = []) {
+export function mapRectToBlock(rect, blocks = []) {
   const hasRect = rect && rect.width > 0 && rect.height > 0;
   if (!hasRect || !Array.isArray(blocks) || blocks.length === 0) {
     return -1;

package/index.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Type declarations for page-analyzer.
+ *
+ * Standalone module: Playwright → HTML parse → block assign → CSV → LLM
+ * block/event analysis. Authored to mirror the runtime shapes produced by
+ * index.js (analyzeUrl / analyzePageEvents) and the PageExtractor bundle.
+ */
+
+export type LlmProviderType = 'openai' | 'codex' | 'claude';
+
+export const LLM_PROVIDER_TYPES: readonly LlmProviderType[];
+
+export interface LlmConfig {
+  /** Backend type. Default: 'openai'. */
+  type?: LlmProviderType;
+  /** Model name (required for all backends). */
+  model: string;
+  /** API key (required when type === 'openai'). */
+  apiKey?: string;
+  /** API endpoint URL (required when type === 'openai'). */
+  apiEndpoint?: string;
+  /** Override CLI binary path (codex/claude). */
+  cliPath?: string;
+  /** Working directory for the CLI child process (codex/claude). */
+  cwd?: string;
+  /** Codex only; auto-enabled when model === 'gpt-5.5'. */
+  fast?: boolean;
+  /** Max tokens (openai only). */
+  maxTokens?: number;
+  /** Temperature (openai only). */
+  temperature?: number;
+  /** Request timeout (ms). */
+  timeout?: number;
+  /** Max retries. */
+  maxRetries?: number;
+  /** Pre-configured known event types. */
+  knownEventTypes?: string[];
+  /** Optional interaction logger. */
+  interactionLogger?: (...args: any[]) => void;
+}
+
+/** Optional S3 config for uploading screenshots instead of saving locally. */
+export interface S3Config {
+  bucket: string;
+  region?: string;
+  prefix?: string;
+  publicBaseUrl?: string;
+  [key: string]: unknown;
+}
+
+/** PageExtractor config (passed via options.extractorConfig). */
+export interface PageExtractorConfig {
+  timeoutMs?: number;
+  viewportWidth?: number;
+  viewportHeight?: number;
+  minBlockHeight?: number;
+  minBlockWidthRatio?: number;
+  blockMaxHeightRatio?: number;
+  blockMaxDepth?: number;
+  textPreviewMaxChars?: number;
+  /** Enable collection of all visible sized DOM elements. */
+  sizedElementsEnabled?: boolean;
+  /** Min size (px) threshold for sized-element collection. Default: 24. */
+  sizedElementMinSize?: number;
+  waitForImagesLoaded?: boolean;
+  fullPageScreenshot?: boolean;
+  blockScreenshots?: boolean;
+  snapshotDir?: string;
+  s3?: S3Config;
+  [key: string]: unknown;
+}
+
+/** A visible DOM element with "some size" (width or height > elementSize). */
+export interface SizedElement {
+  tag: string;
+  text: string;
+  /** Resolved href / action / formaction (link-like elements). */
+  href: string;
+  /** Resolved src (img/source/video/iframe/audio/embed). */
+  src: string;
+  width: number;
+  height: number;
+  /** Absolute top (includes scroll offset). */
+  top: number;
+  /** Absolute left (includes scroll offset). */
+  left: number;
+  /** nth-of-type CSS path, e.g. "body > main:nth-of-type(1) > a:nth-of-type(1)". */
+  cssSelector: string;
+  id: string;
+  class: string;
+  role: string;
+  ariaLabel: string;
+  imageAlt: string;
+  interactive: boolean;
+}
+
+export interface BlockPosition {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export interface BlockSemanticGroup {
+  blockIdxs: string;
+  blockSemantic: string;
+}
+
+/** One logical (output) block in analysis.block_analysis.blocks. */
+export interface BlockAnalysisBlock {
+  blockName: string;
+  blockDescription: string;
+  blockSemantics: string[];
+  blockCssPath: string;
+  blockPosition: BlockPosition;
+  fixed: boolean;
+  tag: string;
+  branchPath: string;
+  depth: number;
+  domOrder: number;
+  textPreview: string;
+  childInteractiveCount: number;
+  /**
+   * Sized DOM elements nested under this block (present when showElement=true,
+   * sorted by top then left). Each satisfies width > elementSize OR height > elementSize.
+   */
+  elements?: SizedElement[];
+  /** Present when showBlockIdx=true: dot-joined physical block indices, e.g. "0.1.2". */
+  blockIdxs?: string;
+  blockSemanticGroups?: BlockSemanticGroup[];
+  rowCount?: number;
+  /** Present when showEvents=true. */
+  blockPossibleEvents?: string[];
+  /** Present when showEvents=true: 'skipped' | 'direct' | 'llm'. */
+  mode?: string;
+  /** Screenshot path(s) for this block (when blockScreenshots=true). */
+  blockScreenshotPaths?: string[];
+}
+
+export interface BlockAnalysisStats {
+  total_blocks: number;
+  skipped_blocks?: number;
+  direct_blocks?: number;
+  llm_blocks?: number;
+  llm_group_count?: number;
+  llm_group_rows?: number;
+}
+
+export interface BlockAnalysis {
+  site_summary: string;
+  blocks: BlockAnalysisBlock[];
+  /** Present when showEvents=true. */
+  possible_event_types?: string[];
+  /** Sized elements that matched no block (only when the page has no visual blocks). */
+  unassignedElements?: SizedElement[];
+  stats: BlockAnalysisStats;
+}
+
+export interface AnalysisResult {
+  block_analysis: BlockAnalysis;
+  /** Present when showEvents=true. */
+  events_by_node?: unknown[];
+  event_types_summary?: unknown;
+  new_event_types?: string[];
+  [key: string]: unknown;
+}
+
+export interface ParseMetrics {
+  parseMs: number;
+  contextBuildMs: number;
+  elementsCount: number;
+  linksCount: number;
+  heapUsedMB: number;
+  contextLevel: string;
+}
+
+export interface ScreenshotInfo {
+  fullPage?: string;
+  blocks?: Array<{ blockIdx: number; path: string }>;
+  [key: string]: unknown;
+}
+
+export interface AnalyzeResult {
+  title: string;
+  parseMetrics: ParseMetrics;
+  analysis: AnalysisResult;
+  screenshots?: ScreenshotInfo;
+  /** Present when showEvents=true. */
+  elements?: unknown[];
+  csvContent?: string;
+  links?: unknown[];
+}
+
+export interface AnalyzeUrlOptions {
+  llm: LlmConfig;
+  /** Accumulated event types for consistency across pages. */
+  knownEventTypes?: string[];
+  /** HtmlParser config overrides. */
+  parserConfig?: Record<string, unknown>;
+  /** PageExtractor config overrides. */
+  extractorConfig?: PageExtractorConfig;
+  /** Include event arrays + full event metadata; also enables node-level events. */
+  showEvents?: boolean;
+  /** Include CSV/block index alignment fields. */
+  showBlockIdx?: boolean;
+  /**
+   * Collect all visible DOM elements with width > elementSize OR height > elementSize
+   * and nest them under each block as `elements`. Default false (previous behavior).
+   */
+  showElement?: boolean;
+  /** Min size (px) threshold for showElement. Default 24. */
+  elementSize?: number;
+  /** Save a full-page screenshot and return its path. */
+  fullPageScreenshot?: boolean;
+  /** Save one screenshot per merged logical block. */
+  blockScreenshots?: boolean;
+  /** Wait for page images before extracting/screenshotting. */
+  waitForImagesLoaded?: boolean;
+}
+
+export interface AnalyzePageEventsInput {
+  /** Raw HTML of the page. */
+  html: string;
+  /** Page URL (for resolving relative links). */
+  url: string;
+  /** Visual blocks from Playwright extraction. */
+  blocks?: unknown[];
+  /** Element geometry records (interactive). */
+  elementGeometries?: unknown[];
+  /**
+   * All visible sized DOM elements (width or height > 24) to nest under blocks.
+   * Typically PageExtractor.collectSizedElements output.
+   */
+  sizedElements?: SizedElement[];
+  /** Markdown content (reserved). */
+  markdown?: string;
+  llm: LlmConfig;
+  knownEventTypes?: string[];
+  parserConfig?: Record<string, unknown>;
+  showEvents?: boolean;
+  showBlockIdx?: boolean;
+  screenshots?: ScreenshotInfo | null;
+  nodeId?: string;
+  domain?: string;
+}
+
+/**
+ * One-call entry: pass a URL, get back the analysis.
+ * Playwright → HTML parse → block assign → CSV → LLM block/event analysis.
+ */
+export function analyzeUrl(url: string, options: AnalyzeUrlOptions): Promise<AnalyzeResult>;
+
+/**
+ * Run the pipeline on pre-fetched data (no browser): HTML parse → block assign
+ * → CSV → LLM block/event analysis.
+ */
+export function analyzePageEvents(input: AnalyzePageEventsInput): Promise<AnalyzeResult>;
+
+export interface PageExtractorBundle {
+  html: string;
+  blocks: unknown[];
+  elementGeometries: unknown[];
+  sizedElements: SizedElement[];
+  screenshots: ScreenshotInfo;
+  pageSize: { width: number; height: number };
+}
+
+export class PageExtractor {
+  constructor(config?: PageExtractorConfig);
+  config: Required<PageExtractorConfig> & Record<string, unknown>;
+  withPreparedPage<T>(url: string, callback: (page: any, targetUrl: string) => Promise<T>): Promise<T>;
+  extractPreparedPage(page: any, targetUrl: string): Promise<PageExtractorBundle>;
+  extract(url: string): Promise<PageExtractorBundle>;
+  collectElementGeometries(page: any): Promise<unknown[]>;
+  /** Collect all visible DOM elements with width or height > sizedElementMinSize. */
+  collectSizedElements(page: any): Promise<SizedElement[]>;
+}
+
+export function createLlmProvider(config: LlmConfig): unknown;
+
+export function assignBlocksToElements(
+  elements?: unknown[],
+  blocks?: unknown[],
+  elementGeometries?: unknown[],
+  pageUrl?: string
+): unknown[];
+
+export class HtmlParser {
+  constructor(config?: Record<string, unknown>);
+  parse(html: string, url: string): { elements: unknown[]; links: unknown[]; title: string; metrics: ParseMetrics };
+}
+
+export class CsvExporter {
+  buildCsvContent(nodeId: string, elements: unknown[]): string;
+}
+
+export class EventAnalyzer {
+  constructor(provider: unknown, config: LlmConfig, runContext?: Record<string, unknown>);
+  analyzeEvents(
+    csvContent: string,
+    markdown: string,
+    knownEventTypes: string[],
+    options?: { blocks?: unknown[]; analyzeNodeEvents?: boolean }
+  ): Promise<AnalysisResult>;
+}
+
+export class BaseLlmProvider {
+  analyze(prompt: string, options?: Record<string, unknown>): Promise<unknown>;
+}
+export class OpenAiProvider extends BaseLlmProvider {
+  constructor(config: Record<string, unknown>);
+}
+export class CodexCliProvider extends BaseLlmProvider {
+  constructor(config?: Record<string, unknown>);
+}
+export class ClaudeCliProvider extends BaseLlmProvider {
+  constructor(config?: Record<string, unknown>);
+}