page-analyzer 1.2.2 → 1.2.3

package/llm/providers/codex-cli-provider.js

@@ -0,0 +1,154 @@
+import { BaseLlmProvider } from './base-provider.js';
+import { runCli, makeTmpOutFile } from './cli-runner.js';
+
+const FAST_MODEL_NAME = 'gpt-5.5';
+
+/**
+ * Codex CLI provider — invokes the locally installed `codex exec` command.
+ *
+ * Auth is whatever the user's local codex install already has; no API key needed.
+ * Returns the final agent message (read from `-o` outfile) as a plain string,
+ * matching the BaseLlmProvider contract.
+ */
+export class CodexCliProvider extends BaseLlmProvider {
+  constructor(config = {}) {
+    super(config);
+    if (!this.model) {
+      throw new Error('CodexCliProvider: model is required');
+    }
+    this.cliPath = config.cliPath || 'codex';
+    this.cwd = config.cwd || null;
+    this.fast = typeof config.fast === 'boolean'
+      ? config.fast
+      : this.model === FAST_MODEL_NAME;
+  }
+
+  buildArgs(outFile) {
+    const args = [
+      'exec',
+      '-m', this.model,
+      '--skip-git-repo-check',
+      '--sandbox', 'read-only',
+      '--ephemeral',
+      '--color', 'never',
+      '--dangerously-bypass-approvals-and-sandbox',
+      '-o', outFile
+    ];
+    if (this.fast) {
+      args.push('-c', 'service_tier="fast"');
+    }
+    return args;
+  }
+
+  resolveInteractionContext(metadata) {
+    const context = metadata && typeof metadata === 'object' ? metadata : {};
+    const domain = String(context.domain || '').trim();
+    const nodeId = String(context.nodeId || '').trim();
+    if (!domain || !nodeId) {
+      return null;
+    }
+    return {
+      domain,
+      nodeId,
+      operation: String(context.operation || 'analysis').trim() || 'analysis',
+      chunkLabel: String(context.chunkLabel || '').trim() || null
+    };
+  }
+
+  async makeRequest(prompt, options = {}) {
+    const metadata = options && typeof options.metadata === 'object' ? options.metadata : {};
+    const interactionContext = this.resolveInteractionContext(metadata);
+    const { filePath: outFile, cleanup } = await makeTmpOutFile('codex-cli', 'last-message.txt');
+    const args = this.buildArgs(outFile);
+    const requestPayload = { argv: [this.cliPath, ...args], model: this.model, fast: this.fast };
+
+    let failureLogged = false;
+    try {
+      const result = await runCli({
+        command: this.cliPath,
+        args,
+        prompt,
+        timeoutMs: this.timeout,
+        outFile,
+        cwd: this.cwd || undefined
+      });
+
+      const outputText = String(result.outFileContent ?? '').trim();
+      if (result.code !== 0 || !outputText) {
+        if (interactionContext) {
+          await this.emitInteractionLog({
+            ...interactionContext,
+            provider: 'Codex',
+            model: this.model,
+            requestId: null,
+            inputText: prompt,
+            outputText: outputText || null,
+            requestPayload,
+            responsePayload: { stdout: result.stdout, stderr: result.stderr, code: result.code, signal: result.signal },
+            usagePromptTokens: null,
+            usageCompletionTokens: null,
+            usageReasoningTokens: null,
+            usageCost: null
+          });
+          failureLogged = true;
+        }
+        const reason = result.code !== 0
+          ? `exited with code ${result.code}${result.signal ? ` (signal ${result.signal})` : ''}`
+          : 'produced empty output file';
+        const stderrTail = String(result.stderr || '').slice(-500);
+        throw new Error(`codex exec ${reason}${stderrTail ? `: ${stderrTail}` : ''}`);
+      }
+
+      if (interactionContext) {
+        await this.emitInteractionLog({
+          ...interactionContext,
+          provider: 'Codex',
+          model: this.model,
+          requestId: null,
+          inputText: prompt,
+          outputText,
+          requestPayload,
+          responsePayload: { stdout: result.stdout, stderr: result.stderr, code: result.code, signal: result.signal },
+          usagePromptTokens: null,
+          usageCompletionTokens: null,
+          usageReasoningTokens: null,
+          usageCost: null
+        });
+      }
+
+      return outputText;
+    } catch (error) {
+      if (!failureLogged && interactionContext) {
+        await this.emitInteractionLog({
+          ...interactionContext,
+          provider: 'Codex',
+          model: this.model,
+          requestId: null,
+          inputText: prompt,
+          outputText: null,
+          requestPayload,
+          responsePayload: null,
+          usagePromptTokens: null,
+          usageCompletionTokens: null,
+          usageReasoningTokens: null,
+          usageCost: null
+        });
+      }
+      throw error;
+    } finally {
+      await cleanup();
+    }
+  }
+
+  async analyze(content, options = {}) {
+    const requestOptions = { ...options };
+    delete requestOptions.parseJson;
+    return this.makeRequestWithRetry(() => this.makeRequest(String(content ?? ''), requestOptions));
+  }
+
+  validateConfig() {
+    if (!this.model) {
+      throw new Error('Model is required');
+    }
+  }
+}

package/llm/providers/index.js

@@ -0,0 +1,61 @@
+import { OpenAiProvider } from './openai-provider.js';
+import { CodexCliProvider } from './codex-cli-provider.js';
+import { ClaudeCliProvider } from './claude-cli-provider.js';
+
+export const LLM_PROVIDER_TYPES = Object.freeze(['openai', 'codex', 'claude']);
+
+/**
+ * Build the right LLM provider instance from an llmConfig object.
+ *
+ * @param {Object} llmConfig
+ * @param {'openai'|'codex'|'claude'} [llmConfig.type='openai']
+ * @param {string} llmConfig.model
+ * @param {string} [llmConfig.apiKey]
+ * @param {string} [llmConfig.apiEndpoint]
+ * @param {string} [llmConfig.cliPath]
+ * @param {string} [llmConfig.cwd]
+ * @param {boolean} [llmConfig.fast]
+ * @param {number} [llmConfig.maxTokens]
+ * @param {number} [llmConfig.temperature]
+ * @param {number} [llmConfig.timeout]
+ * @param {number} [llmConfig.maxRetries]
+ * @param {Function} [llmConfig.interactionLogger]
+ */
+export function createLlmProvider(llmConfig = {}) {
+  const type = String(llmConfig.type || 'openai').toLowerCase();
+  const shared = {
+    model: llmConfig.model,
+    timeout: llmConfig.timeout,
+    maxRetries: llmConfig.maxRetries,
+    maxTokens: llmConfig.maxTokens,
+    interactionLogger: llmConfig.interactionLogger
+  };
+
+  switch (type) {
+    case 'openai':
+      return new OpenAiProvider({
+        ...shared,
+        apiKey: llmConfig.apiKey,
+        apiEndpoint: llmConfig.apiEndpoint,
+        temperature: llmConfig.temperature
+      });
+    case 'codex':
+      return new CodexCliProvider({
+        ...shared,
+        cliPath: llmConfig.cliPath,
+        cwd: llmConfig.cwd,
+        fast: llmConfig.fast
+      });
+    case 'claude':
+      return new ClaudeCliProvider({
+        ...shared,
+        cliPath: llmConfig.cliPath,
+        cwd: llmConfig.cwd
+      });
+    default:
+      throw new Error(`Unknown llm.type: ${llmConfig.type}. Expected one of: ${LLM_PROVIDER_TYPES.join(', ')}`);
+  }
+}
+
+export { OpenAiProvider, CodexCliProvider, ClaudeCliProvider };
+export { BaseLlmProvider } from './base-provider.js';

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "page-analyzer",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "type": "module",
   "description": "Standalone page analysis module.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liuzemei/page-analyzer.git"
+  },
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "test": "node test/smoke.test.js",
     "analyze": "node scripts/analyze.js",

package/page-extractor.js

@@ -161,6 +161,10 @@ export class PageExtractor {
       textPreviewMaxChars: Number.isInteger(config.textPreviewMaxChars)
         ? Math.max(120, config.textPreviewMaxChars)
         : 1200,
+      sizedElementsEnabled: Boolean(config.sizedElementsEnabled),
+      sizedElementMinSize: Number.isInteger(config.sizedElementMinSize)
+        ? Math.max(0, config.sizedElementMinSize)
+        : 24,
       waitForImagesLoaded: Boolean(config.waitForImagesLoaded),
       fullPageScreenshot: Boolean(config.fullPageScreenshot),
       blockScreenshots: Boolean(config.blockScreenshots),
@@ -476,6 +480,147 @@ export class PageExtractor {
     });
   }
 
+  /**
+   * Collect ALL visible DOM elements that have "some size" (width > minSize OR
+   * height > minSize), each annotated with basic raw info. Broader than
+   * collectElementGeometries (which is interactive-only); used to nest element
+   * detail under each block in the analysis output.
+   */
+  async collectSizedElements(page) {
+    const minSize = this.config.sizedElementMinSize;
+    const records = await page.evaluate((minSizePx) => {
+      const INTERACTIVE_SELECTOR = 'a, button, form, input, select, textarea, [onclick], [role="button"], [role="link"]';
+      const SKIP_TAGS = new Set([
+        'script', 'style', 'noscript', 'template', 'meta', 'link', 'br', 'wbr', 'head', 'title'
+      ]);
+      const MEDIA_TAGS = new Set(['img', 'source', 'video', 'iframe', 'audio', 'embed']);
+      const records = [];
+
+      const normalizeTextInPage = (value, maxLength = 240) => String(value || '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, maxLength);
+
+      const normalizeHref = (value) => {
+        const raw = String(value || '').trim();
+        if (!raw) return '';
+        try {
+          const resolved = new URL(raw, location.href);
+          resolved.hash = '';
+          const href = resolved.href;
+          return href.endsWith('/') && href !== `${resolved.origin}/`
+            ? href.slice(0, -1)
+            : href;
+        } catch {
+          return raw;
+        }
+      };
+
+      const buildPath = (el, useNthOfType) => {
+        if (!el || !el.tagName) return '';
+        const parts = [];
+        let current = el;
+        while (current && current.tagName && current.tagName.toLowerCase() !== 'body') {
+          const parent = current.parentElement;
+          if (!parent || parent.tagName.toLowerCase() === 'html') break;
+          const tag = current.tagName.toLowerCase();
+          const siblings = Array.from(parent.children).filter((child) => {
+            if (!(child instanceof Element)) return false;
+            return useNthOfType ? child.tagName.toLowerCase() === tag : true;
+          });
+          const index = siblings.indexOf(current) + 1;
+          const suffix = useNthOfType
+            ? `:nth-of-type(${index})`
+            : `:nth-child(${index})`;
+          parts.unshift(`${tag}${suffix}`);
+          current = parent;
+        }
+        if (parts.length === 0) return '';
+        return `body > ${parts.join(' > ')}`;
+      };
+
+      const pageWidth = Math.max(
+        document.documentElement?.scrollWidth || 0,
+        document.body?.scrollWidth || 0
+      );
+      const pageHeight = Math.max(
+        document.documentElement?.scrollHeight || 0,
+        document.body?.scrollHeight || 0
+      );
+
+      for (const element of document.querySelectorAll('body *')) {
+        if (!(element instanceof Element)) continue;
+        const tag = element.tagName.toLowerCase();
+        if (SKIP_TAGS.has(tag)) continue;
+
+        const style = getComputedStyle(element);
+        if (style.display === 'none') continue;
+        if (style.visibility === 'hidden' || style.visibility === 'collapse') continue;
+        if (parseFloat(style.opacity) === 0) continue;
+
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) continue;
+        if (!(rect.width > minSizePx || rect.height > minSizePx)) continue;
+
+        const top = rect.top + window.scrollY;
+        const left = rect.left + window.scrollX;
+        // Skip elements positioned fully outside the document (e.g. a11y skip-links at top:-17000)
+        if (top + rect.height <= 0 || left + rect.width <= 0) continue;
+        if (pageHeight > 0 && top >= pageHeight) continue;
+        if (pageWidth > 0 && left >= pageWidth) continue;
+
+        let imageAlt = '';
+        if (tag === 'img') {
+          imageAlt = normalizeTextInPage(element.getAttribute('alt') || '', 240);
+        } else {
+          const childImg = element.querySelector(':scope > img');
+          if (childImg) {
+            imageAlt = normalizeTextInPage(childImg.getAttribute('alt') || '', 240);
+          }
+        }
+
+        let src = '';
+        if (MEDIA_TAGS.has(tag)) {
+          src = normalizeHref(element.getAttribute('src') || element.currentSrc || '');
+        }
+
+        const role = element.getAttribute('role') || '';
+        const roleLower = role.toLowerCase();
+
+        records.push({
+          tag,
+          text: normalizeTextInPage(element.innerText || element.textContent || ''),
+          href: normalizeHref(
+            element.getAttribute('href')
+            || element.getAttribute('action')
+            || element.getAttribute('formaction')
+            || ''
+          ),
+          src,
+          width: rect.width,
+          height: rect.height,
+          top,
+          left,
+          cssSelector: buildPath(element, true),
+          id: element.id || '',
+          class: normalizeTextInPage(element.getAttribute('class') || '', 240),
+          role,
+          ariaLabel: normalizeTextInPage(element.getAttribute('aria-label') || '', 120),
+          imageAlt,
+          interactive: element.matches(INTERACTIVE_SELECTOR)
+            || element.hasAttribute('onclick')
+            || roleLower === 'button'
+            || roleLower === 'link'
+        });
+      }
+
+      return records;
+    }, minSize);
+
+    console.log(`[page-analyzer] Collected ${records.length} sized elements (width or height > ${minSize}px)`);
+    return records;
+  }
+
   async collectPageSize(page) {
     return page.evaluate(() => {
       const html = document.documentElement;
@@ -741,11 +886,11 @@ export class PageExtractor {
 
   /**
    * Extract page data from an already prepared Playwright page:
-   * html, blocks, elementGeometries, screenshots.
+   * html, blocks, elementGeometries, sizedElements, screenshots.
    * When config.s3 is provided, screenshots are uploaded to S3 and returned as URLs.
    * @param {import('playwright').Page} page - Prepared Playwright page
    * @param {string} targetUrl - URL loaded in the page
-   * @returns {Promise<{html, blocks, elementGeometries, screenshots, pageSize}>}
+   * @returns {Promise<{html, blocks, elementGeometries, sizedElements, screenshots, pageSize}>}
    */
   async extractPreparedPage(page, targetUrl) {
     const viewport = {
@@ -766,17 +911,20 @@ export class PageExtractor {
     });
     const blocks = Array.isArray(blocksResult?.blocks) ? blocksResult.blocks : [];
     const elementGeometries = await this.collectElementGeometries(page);
+    const sizedElements = this.config.sizedElementsEnabled
+      ? await this.collectSizedElements(page)
+      : [];
     const finalPageSize = await this.collectPageSize(page);
     const screenshots = await this.captureScreenshots(page, targetUrl, blocks);
 
-    return { html, blocks, elementGeometries, screenshots, pageSize: finalPageSize };
+    return { html, blocks, elementGeometries, sizedElements, screenshots, pageSize: finalPageSize };
   }
 
   /**
-   * Extract page data: html, blocks, elementGeometries, screenshots.
+   * Extract page data: html, blocks, elementGeometries, sizedElements, screenshots.
    * When config.s3 is provided, screenshots are uploaded to S3 and returned as URLs.
    * @param {string} url - URL to extract
-   * @returns {Promise<{html, blocks, elementGeometries, screenshots, pageSize}>}
+   * @returns {Promise<{html, blocks, elementGeometries, sizedElements, screenshots, pageSize}>}
    */
   async extract(url) {
     return this.withPreparedPage(url, async (page, targetUrl) => {

package/scripts/analyze.js

@@ -33,14 +33,19 @@ loadDotEnv(path.join(projectRoot, '.env'));
 
 const url = process.argv[2] || 'https://www.jcb.co.jp/ordercard/kojin_card/os_card_w2.html';
 
+const llmType = (process.env.LLM_TYPE || 'openai').toLowerCase();
+const llmConfig = { type: llmType, model: process.env.LLM_MODEL };
+if (llmType === 'openai') {
+  llmConfig.apiKey = process.env.LLM_API_KEY;
+  llmConfig.apiEndpoint = process.env.LLM_API_ENDPOINT;
+}
+
 const result = await analyzeUrl(url, {
   fullPageScreenshot: true,
   blockScreenshots: true,
-  llm: {
-    apiKey: process.env.LLM_API_KEY,
-    apiEndpoint: process.env.LLM_API_ENDPOINT,
-    model: process.env.LLM_MODEL
-  }
+  showElement: true,
+  elementSize: 24,
+  llm: llmConfig
 });
 
 fs.writeFileSync(

package/test/smoke.test.js

@@ -3,6 +3,11 @@ import { createHash } from 'node:crypto';
 import { EventAnalyzer } from '../llm/analyzers/event-analyzer/event-analyzer.js';
 import { buildBlockAnalysisArtifact } from '../llm/analyzers/event-analyzer/event-analyzer-blocks.js';
 import { OpenAiProvider } from '../llm/providers/openai-provider.js';
+import {
+  createLlmProvider,
+  CodexCliProvider,
+  ClaudeCliProvider
+} from '../llm/providers/index.js';
 import { PageExtractor } from '../page-extractor.js';
 import { analyzeUrl } from '../index.js';
 
@@ -205,6 +210,23 @@ async function analyzeWith(options = {}) {
         height: 24,
         selectorNthOfType: 'body > main:nth-of-type(1) > section:nth-of-type(1) > a:nth-of-type(1)'
       }],
+      sizedElements: [{
+        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
+      }],
       screenshots: { fullPage: '/tmp/full-page.png' },
       pageSize: { width: 1000, height: 800 }
     };
@@ -241,7 +263,9 @@ async function analyzeWith(options = {}) {
       },
       fullPageScreenshot: true,
       blockScreenshots: true,
-      showBlockIdx: true
+      showBlockIdx: true,
+      showElement: true,
+      elementSize: 24
     });
 
     assert.equal(calls.filter((call) => call[0] === 'withPreparedPage').length, 1);
@@ -253,6 +277,16 @@ async function analyzeWith(options = {}) {
       result.analysis.block_analysis.blocks[0].blockScreenshotPaths[0],
       '/tmp/logical-block-0.png'
     );
+
+    const firstBlockElements = result.analysis.block_analysis.blocks[0].elements;
+    assert.ok(Array.isArray(firstBlockElements), 'block should carry a sized elements array');
+    assert.equal(firstBlockElements.length, 1);
+    assert.equal(firstBlockElements[0].tag, 'a');
+    assert.equal(firstBlockElements[0].interactive, true);
+    assert.equal(firstBlockElements[0].cssSelector, 'body > main:nth-of-type(1) > section:nth-of-type(1) > a:nth-of-type(1)');
+    assert.equal(firstBlockElements[0].class, 'cta');
+    assert.equal(firstBlockElements[0].semantic, undefined);
+    assert.equal(firstBlockElements[0].event_type, undefined);
   } finally {
     PageExtractor.prototype.withPreparedPage = originalWithPreparedPage;
     PageExtractor.prototype.extractPreparedPage = originalExtractPreparedPage;
@@ -507,4 +541,51 @@ async function analyzeWith(options = {}) {
   assert.equal(artifact.blocks[0].blockCssPath, 'body > main:nth-of-type(1)');
 }
 
+{
+  // Factory dispatches to the right provider class
+  const openaiProvider = createLlmProvider({
+    type: 'openai',
+    apiKey: 'k',
+    apiEndpoint: 'https://example.invalid/v1/chat/completions',
+    model: 'm'
+  });
+  assert.ok(openaiProvider instanceof OpenAiProvider, 'type=openai → OpenAiProvider');
+
+  const codexProvider = createLlmProvider({ type: 'codex', model: 'gpt-5.5' });
+  assert.ok(codexProvider instanceof CodexCliProvider, 'type=codex → CodexCliProvider');
+  assert.equal(codexProvider.fast, true, 'gpt-5.5 auto-enables fast');
+  assert.ok(codexProvider.buildArgs('/tmp/x').includes('service_tier="fast"'), 'fast injects -c service_tier');
+
+  const codexOther = createLlmProvider({ type: 'codex', model: 'gpt-5-codex' });
+  assert.equal(codexOther.fast, false, 'other models do not auto-enable fast');
+  assert.ok(!codexOther.buildArgs('/tmp/x').includes('service_tier="fast"'));
+
+  const codexExplicitFast = createLlmProvider({ type: 'codex', model: 'gpt-5-codex', fast: true });
+  assert.equal(codexExplicitFast.fast, true, 'explicit fast:true overrides');
+
+  const codexExplicitOff = createLlmProvider({ type: 'codex', model: 'gpt-5.5', fast: false });
+  assert.equal(codexExplicitOff.fast, false, 'explicit fast:false overrides gpt-5.5');
+
+  const claudeProvider = createLlmProvider({ type: 'claude', model: 'sonnet' });
+  assert.ok(claudeProvider instanceof ClaudeCliProvider, 'type=claude → ClaudeCliProvider');
+
+  // Default type is openai
+  const defaultProvider = createLlmProvider({
+    apiKey: 'k',
+    apiEndpoint: 'https://example.invalid/v1/chat/completions',
+    model: 'm'
+  });
+  assert.ok(defaultProvider instanceof OpenAiProvider, 'missing type → openai default');
+
+  // Unknown type rejects
+  assert.throws(
+    () => createLlmProvider({ type: 'unknown', model: 'm' }),
+    /Unknown llm\.type/
+  );
+
+  // CLI providers require model
+  assert.throws(() => createLlmProvider({ type: 'codex' }), /model is required/);
+  assert.throws(() => createLlmProvider({ type: 'claude' }), /model is required/);
+}
+
 console.log('smoke tests passed');