ax-grep 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { formatSemanticTreeText, observeSemanticTree } from './browser.js';
 import { StaticSemanticTreeOptions } from './static.js';
-import { E as ExtractorScriptOptions, O as ObserverScriptOptions, S as SemanticNode, a as SemanticTreeOptions } from './types-gwHWhYmw.js';
-export { A as AgentAction, b as AgentActionTargetChoice, c as AgentAnswerPlan, d as AgentBrowserHtmlCapture, e as AgentCitation, f as AgentContinuationMode, g as AgentContract, h as AgentContractFeature, i as AgentExecutionMode, j as AgentExecutorStep, k as AgentExpectedOutcome, l as AgentExpectedOutcomeKind, m as AgentFindMatch, n as AgentFindSummary, o as AgentFormChoice, p as AgentFormField, q as AgentFormHiddenField, r as AgentHandoff, s as AgentJsonEnvelope, t as AgentLoopDecision, u as AgentLoopDirective, v as AgentNext, w as AgentPageAction, x as AgentPageApiEndpoint, y as AgentPageAppHint, z as AgentPageAuthorLink, B as AgentPageBarrier, C as AgentPageBreadcrumb, D as AgentPageBreadcrumbItem, F as AgentPageCheck, G as AgentPageCitation, H as AgentPageClientState, I as AgentPageCodeBlock, J as AgentPageConfig, K as AgentPageContactPoint, L as AgentPageDataTable, M as AgentPageDataset, N as AgentPageDecision, P as AgentPageEmbed, Q as AgentPageEvidence, R as AgentPageFaq, T as AgentPageForm, U as AgentPageHttpPolicy, V as AgentPageHydration, W as AgentPageIdentity, X as AgentPageKeyValue, Y as AgentPageMedia, Z as AgentPageMetaFact, _ as AgentPageMetadata, $ as AgentPageMobileHint, a0 as AgentPageOffer, a1 as AgentPagePagination, a2 as AgentPageProvenance, a3 as AgentPageResource, a4 as AgentPageRuntime, a5 as AgentPageSchemaFact, a6 as AgentPageSchemaFactValue, a7 as AgentPageSection, a8 as AgentPageTimeline, a9 as AgentPageToc, aa as AgentPageTocItem, ab as AgentPageTopic, ac as AgentPageTranscript, ad as AgentQualityGate, ae as AgentQualityGateKind, af as AgentReadTarget, ag as AgentReadValue, ah as AgentReadValueInline, ai as AgentReadValueKind, aj as AgentReadValuePayload, ak as AgentReadValueReference, al as AgentReadValueScalar, am as AgentResultChoice, an as AgentRoutingIntent, ao as AgentSearchDecision, ap as AgentSemanticSummary, aq as AgentSignal, ar as AgentSignalKind, as as AgentSignalSeverity, at as AgentSourceChoice, au as AgentSourceSearch, av as AgentSourceSearchResult, aw as AgentStatus, ax as AgentSummary, ay as AgentTarget, az as AgentVerification, aA as ExtractMode, aB as OutputFormat, aC as SemanticNodeBounds, aD as SemanticNodeState, aE as SemanticTreeChange, aF as SemanticTreeObserverOptions } from './types-gwHWhYmw.js';
+import { E as ExtractorScriptOptions, O as ObserverScriptOptions, S as SemanticNode, a as SemanticTreeOptions } from './types-K1hqb7Pq.js';
+export { A as AgentAction, b as AgentActionTargetChoice, c as AgentAnswerPlan, d as AgentBrowserHtmlCapture, e as AgentCitation, f as AgentContinuationMode, g as AgentContract, h as AgentContractFeature, i as AgentExecutionMode, j as AgentExecutorStep, k as AgentExpectedOutcome, l as AgentExpectedOutcomeKind, m as AgentFindMatch, n as AgentFindSummary, o as AgentFormChoice, p as AgentFormField, q as AgentFormHiddenField, r as AgentHandoff, s as AgentJsonEnvelope, t as AgentLoopDecision, u as AgentLoopDirective, v as AgentNext, w as AgentPageAction, x as AgentPageApiEndpoint, y as AgentPageAppHint, z as AgentPageAuthorLink, B as AgentPageBarrier, C as AgentPageBreadcrumb, D as AgentPageBreadcrumbItem, F as AgentPageCheck, G as AgentPageCitation, H as AgentPageClientState, I as AgentPageCodeBlock, J as AgentPageConfig, K as AgentPageContactPoint, L as AgentPageDataTable, M as AgentPageDataset, N as AgentPageDecision, P as AgentPageEmbed, Q as AgentPageEvidence, R as AgentPageFaq, T as AgentPageForm, U as AgentPageHttpPolicy, V as AgentPageHydration, W as AgentPageIdentity, X as AgentPageKeyValue, Y as AgentPageMedia, Z as AgentPageMetaFact, _ as AgentPageMetadata, $ as AgentPageMobileHint, a0 as AgentPageOffer, a1 as AgentPagePagination, a2 as AgentPageProvenance, a3 as AgentPageResource, a4 as AgentPageRuntime, a5 as AgentPageSchemaFact, a6 as AgentPageSchemaFactValue, a7 as AgentPageSection, a8 as AgentPageTimeline, a9 as AgentPageToc, aa as AgentPageTocItem, ab as AgentPageTopic, ac as AgentPageTranscript, ad as AgentQualityGate, ae as AgentQualityGateKind, af as AgentReadTarget, ag as AgentReadValue, ah as AgentReadValueInline, ai as AgentReadValueKind, aj as AgentReadValuePayload, ak as AgentReadValueReference, al as AgentReadValueScalar, am as AgentResultChoice, an as AgentRoutingIntent, ao as AgentSearchDecision, ap as AgentSemanticSummary, aq as AgentSignal, ar as AgentSignalKind, as as AgentSignalSeverity, at as AgentSourceChoice, au as AgentSourceSearch, av as AgentSourceSearchResult, aw as AgentStatus, ax as AgentSummary, ay as AgentTarget, az as AgentVerification, aA as ExtractMode, aB as OutputFormat, aC as SemanticNodeBounds, aD as SemanticNodeState, aE as SemanticTreeChange, aF as SemanticTreeObserverOptions } from './types-K1hqb7Pq.js';
 
 declare function extract(html: string, options?: StaticSemanticTreeOptions): SemanticNode;
 declare function createExtractorScript(options?: ExtractorScriptOptions): string;

package/dist/static.d.ts

@@ -1,4 +1,4 @@
-import { a as SemanticTreeOptions, S as SemanticNode } from './types-gwHWhYmw.js';
+import { a as SemanticTreeOptions, S as SemanticNode } from './types-K1hqb7Pq.js';
 
 type StaticSemanticTreeOptions = Pick<SemanticTreeOptions, "excludeLikelyAds" | "excludeLikelyBoilerplate" | "includeAttributes" | "includeHidden" | "includeSelectOptions" | "includeTextNodes" | "maxChildrenPerNode" | "maxLinkFarmChildren" | "maxRepeatedSubtreeInstances" | "maxTextLength" | "mode" | "pruneCollapsedSubtrees" | "pruneLikelyClosedOverlays" | "summarizeLargeSubtrees" | "summarizeLikelyLinkFarms" | "summarizeRepeatedSubtrees">;
 declare function extractStaticSemanticTree(html: string, options?: StaticSemanticTreeOptions): SemanticNode;

package/dist/{types-gwHWhYmw.d.ts → types-K1hqb7Pq.d.ts}

@@ -86,7 +86,7 @@ type ObserverScriptOptions = SemanticTreeObserverOptions & {
     globalName?: string;
 };
 type AgentStatus = "ready" | "choose-result" | "verify" | "needs-browser" | "error";
-type AgentBrowserHtmlReasonCode = "no-inspectable-content" | "client-rendered" | "http-error" | "fetch-error" | "challenge" | "hcaptcha" | "recaptcha" | "cloudflare-challenge" | "login-required" | "paywall" | "blocked-or-empty" | "retry-action" | "interaction-required" | "browser-interaction" | "unknown";
+type AgentBrowserHtmlReasonCode = "no-inspectable-content" | "client-rendered" | "http-error" | "fetch-error" | "challenge" | "hcaptcha" | "recaptcha" | "cloudflare-challenge" | "akamai-challenge" | "datadome-challenge" | "perimeterx-challenge" | "kasada-challenge" | "login-required" | "paywall" | "blocked-or-empty" | "retry-action" | "interaction-required" | "browser-interaction" | "unknown";
 type AgentStaticReadiness = "usable-content" | "usable-structured-data" | "usable-hidden-data" | "thin" | "needs-browser" | "error";
 type AgentStaticReadinessReasonCode = "browser-required" | "client-rendered" | "interaction-required" | "extraction-error" | "hidden-data" | "source-link" | "form" | "action-target" | "structured-data" | "readable-content" | "limited-static-payload" | "thin-content";
 type AgentSourceSearchFailureKind = "not-found" | "http-client-error" | "http-server-error" | "http-error" | "fetch-error" | "timeout" | "rate-limited" | "no-inspectable-content" | "unknown";

package/docs/README.md

@@ -8,11 +8,13 @@ Start here when README is too small for the detail you need.
 | Use CLI search and `--agent` output | [cli-agent.md](./cli-agent.md) |
 | Build a minimal agent handoff loop | [agent-handoff.md](./agent-handoff.md) |
 | Use as a server/library package | [library-api.md](./library-api.md) |
-| Inject into WebViews or browser pages | [library-api.md](./library-api.md#browser-injection) |
+| Integrate with server-side agent SDKs | [server-agent.md](./server-agent.md) |
+| Inject into WebViews or browser pages | [webview.md](./webview.md) |
 | Check readiness before promotion | [agent-readiness.md](./agent-readiness.md) |
 | Track current progress and next work | [progress.md](./progress.md) |
 | Review feature details | [features.md](./features.md) |
 | Run benchmarks and comparisons | [benchmarks.md](./benchmarks.md) |
+| Publish with npm trusted publishing | [release.md](./release.md) |
 | Read current `agent-browser` comparison notes | [comparison-baseline.md](./comparison-baseline.md) |
 
 The root README should stay short: skill install first, server library usage

package/docs/benchmarks.md

@@ -30,6 +30,7 @@ Resource safety:
 
 ```sh
 pnpm benchmark:agent-cost
+pnpm benchmark:library-cost
 pnpm compare:sample
 pnpm compare:static:fixtures
 pnpm compare:static:fixtures:gate
@@ -82,6 +83,39 @@ Search, social, challenge, and volatile targets may be diagnostic-only and
 excluded from gate averages. Check each run's `included` and `excluded` counts
 before treating an average as release-gating coverage.
 
+## Library Cost Benchmark
+
+`pnpm benchmark:library-cost` measures warm in-process `extract(html)` calls and
+writes `tmp/benchmarks/library-cost.json`. It does not fetch remote pages and
+does not launch a browser. This is the better metric for server integrations
+where a Node process is already running and the question is incremental RSS per
+library call, not total CLI process RSS.
+
+The report includes:
+
+- `incrementalRssKb`: RSS after extraction minus RSS before extraction.
+- `estimatedTokens`: `cl100k_base` tokens for `formatSemanticTreeText(tree)`.
+- `summary.nodeCount`: semantic tree size after compact extraction.
+
+Run it with the package script so Node exposes GC before each measured case:
+
+```sh
+pnpm benchmark:library-cost
+```
+
+Use `benchmark:agent-cost` for CLI-vs-browser release claims. Use
+`benchmark:library-cost` for server SDK sizing and memory regression checks.
+
+Latest local library-only run:
+
+| Case | HTML bytes | Incremental RSS | Output tokens | Nodes |
+| --- | ---: | ---: | ---: | ---: |
+| content-page | 737 | 0 KB | 79 | 16 |
+| challenge-page | 251 | 0 KB | 8 | 2 |
+| large-list-page | 37,390 | 896 KB | 428 | 76 |
+
+Summary: max incremental RSS was 896 KB, average incremental RSS was 299 KB.
+
 `compare:static:fixtures:gate` is the non-browser smoke gate: it uses synthetic
 HTML fixtures only, so it should not fetch remote pages or launch
 `agent-browser`. Use `compare:static:fixtures` when you need the JSON report.

package/docs/cli-agent.md

@@ -31,7 +31,7 @@ ax-grep --search "ax-grep npm" --engine bing --lang en --region US
 ax-grep --search "ax-grep npm" --open-result best --json
 ```
 
-- `--search` tries DuckDuckGo, Bing, and StartPage by default.
+- `--search` tries DuckDuckGo, Bing, StartPage, and Google by default.
 - `--engine <name>` forces one search engine.
 - `--open-result <n|best>` fetches a ranked result in the same command.
 - `--lang` and `--region` make locale-specific searches reproducible.

package/docs/release.md

@@ -0,0 +1,24 @@
+# Release
+
+## npm Trusted Publisher
+
+Configure npm once before publishing from GitHub Actions:
+
+- Package settings: `https://www.npmjs.com/package/ax-grep/access`
+- Publisher: GitHub Actions
+- Organization or user: `hmmhmmhm`
+- Repository: `ax-grep`
+- Workflow filename: `publish.yml`
+- Environment name: leave blank
+- Allowed actions: `npm publish`
+
+After the trusted publisher is saved, publish a release by pushing a version tag:
+
+```sh
+git tag v0.1.2
+git push origin v0.1.2
+```
+
+The workflow uses GitHub OIDC instead of an npm token and runs `npm publish`.
+For GitHub Actions and public packages, npm automatically publishes provenance
+attestations when trusted publishing is used.

package/docs/server-agent.md

@@ -0,0 +1,71 @@
+# Server Agent Integration
+
+Use `ax-grep` in an agent service when you already fetched HTML and want a
+compact, accessibility-style source view before paying for browser automation.
+This is useful in Codex SDK, OpenRouter, queue workers, and custom agent loops.
+
+## Minimal Pattern
+
+```ts
+import { extract, formatSemanticTreeText } from "ax-grep";
+
+export async function readForAgent(url: string) {
+  const response = await fetch(url, {
+    headers: {
+      accept: "text/html,application/xhtml+xml",
+      "user-agent": "my-agent/1.0",
+    },
+  });
+
+  const html = await response.text();
+  const tree = extract(html, {
+    includeAttributes: false,
+    includeHidden: false,
+  });
+
+  return {
+    url: response.url || url,
+    status: response.status,
+    text: formatSemanticTreeText(tree),
+  };
+}
+```
+
+Pass `text` into the model as source evidence. Escalate to a browser only when
+the fetched HTML is thin, blocked, or client-rendered.
+
+## Agent Prompt Shape
+
+```ts
+const page = await readForAgent("https://example.com");
+
+const messages = [
+  {
+    role: "system",
+    content: "Use the provided semantic tree as page evidence. Ask for browser automation only when the evidence is insufficient.",
+  },
+  {
+    role: "user",
+    content: `URL: ${page.url}\nHTTP: ${page.status}\n\n${page.text}`,
+  },
+];
+```
+
+For live URLs, the CLI can also produce an agent handoff with challenge
+detection and search metadata:
+
+```sh
+npx --yes ax-grep@latest https://example.com --agent-brief
+```
+
+Use that command when you want `agent.executor`, `agent.handoff`, `pageCheck`,
+and challenge reason codes without building the fetch layer yourself.
+
+## Failure Policy
+
+- If a challenge marker is detected, return a browser-required message instead
+  of retrying in a loop.
+- If HTML is mostly an app shell, fetch browser-captured HTML or run WebView
+  injection.
+- Keep server fetches sequential for release smoke checks. Browser-backed
+  comparisons must use `pnpm check:processes` before and after the run.

package/docs/webview.md

@@ -0,0 +1,70 @@
+# WebView and In-Page Usage
+
+Use `createExtractorScript()` when the current page already exists in a mobile
+WebView, Playwright page, Puppeteer page, browser extension, or in-app browser.
+It builds an accessibility-style semantic tree from the live DOM without
+opening a separate browser.
+
+## Playwright
+
+```ts
+import { createExtractorScript } from "ax-grep";
+
+const text = await page.evaluate(createExtractorScript({
+  format: "text",
+  mode: "interactive",
+  includeBounds: false,
+  includeAttributes: false,
+}));
+```
+
+## Android WebView
+
+```kotlin
+webView.evaluateJavascript(scriptFromServer) { jsonEncodedResult ->
+  // scriptFromServer is createExtractorScript({ format: "text" }).
+  // jsonEncodedResult contains the semantic tree text.
+}
+```
+
+Generate the script in your JavaScript bundle or server:
+
+```ts
+import { createExtractorScript } from "ax-grep";
+
+export const scriptFromServer = createExtractorScript({
+  format: "text",
+  mode: "interactive",
+});
+```
+
+## iOS WKWebView
+
+```swift
+webView.evaluateJavaScript(scriptFromServer) { result, error in
+  if let text = result as? String {
+    // Send text to the local model or agent parser.
+  }
+}
+```
+
+## In-Page Bundle
+
+When your code already runs inside the page, use the browser entry point:
+
+```ts
+import { extract, formatSemanticTreeText } from "ax-grep/browser";
+
+const tree = extract({
+  mode: "interactive",
+  includeBounds: false,
+});
+
+console.log(formatSemanticTreeText(tree));
+```
+
+## Mobile Agent Policy
+
+For local sLLM search or parsing, run extraction in the current WebView first.
+Escalate to network search or remote browser automation only when the semantic
+tree lacks the target evidence, login state, or post-interaction content.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ax-grep",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A browser-native semantic accessibility tree extractor that runs without DevTools or CDP.",
   "type": "module",
   "engines": {
@@ -48,6 +48,7 @@
     "readiness:audit": "tsx scripts/check-agent-readiness.ts",
     "readiness:real-page-smoke": "tsx scripts/check-real-page-smoke.ts",
     "readiness:search-smoke": "tsx scripts/check-search-smoke.ts",
+    "readiness:published-smoke": "tsx scripts/check-published-package-smoke.ts",
     "readiness:agent-browser-smoke": "tsx scripts/check-agent-browser-smoke.ts",
     "readiness:agent-browser-text-heavy-smoke": "tsx scripts/check-agent-browser-text-heavy-smoke.ts",
     "test": "vitest run",
@@ -57,6 +58,7 @@
     "compare:static": "tsx scripts/compare-static.ts",
     "compare:tokens": "tsx scripts/compare-token-cost.ts",
     "benchmark:agent-cost": "tsx scripts/benchmark-agent-cost.ts",
+    "benchmark:library-cost": "node --expose-gc --import tsx scripts/benchmark-library-cost.ts",
     "compare:browser:fixture": "tsx scripts/compare-browser-fixture.ts",
     "compare:gate": "tsx scripts/check-comparison-gates.ts",
     "compare:sample": "tsx scripts/compare.ts https://example.com https://www.wikipedia.org https://developer.mozilla.org/en-US/docs/Web/Accessibility https://news.ycombinator.com https://github.com/features https://libraries.io/npm/typescript https://www.npmjs.com/package/typescript",
@@ -96,5 +98,10 @@
   },
   "optionalDependencies": {
     "impit": "^0.14.1"
+  },
+  "pnpm": {
+    "overrides": {
+      "esbuild": "0.28.1"
+    }
   }
 }