ax-grep 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hmmhmmhm
+
+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,4 +1,109 @@
+<div align="center">
+
 # ax-grep
 
-Reserved package name for an accessibility tree extraction utility.
+[![npm version](https://img.shields.io/npm/v/ax-grep.svg)](https://www.npmjs.com/package/ax-grep)
+[![coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](./tests)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![agent ready](https://img.shields.io/badge/agent-ready-0b7f3a.svg)](./docs/agent-handoff.md)
+[![Codex skill](https://img.shields.io/badge/Codex-skill-111111.svg)](./skills/ax-grep-cli/SKILL.md)
+[![Claude compatible](https://img.shields.io/badge/Claude-compatible-5b4b8a.svg)](./docs/cli-agent.md)
+[![Gemini ready](https://img.shields.io/badge/Gemini-ready-1a73e8.svg)](./docs/cli-agent.md)
+
+<img src="./docs/assets/ax-grep-og.png" alt="ax-grep promo image" width="920">
+
+<img src="./docs/assets/ax-grep-benchmark.png" alt="ax-grep benchmark comparison image" width="920">
+
+<img src="./docs/assets/ax-grep-search.png" alt="ax-grep auto search comparison image" width="920">
+
+Compact semantic trees and agent-ready page checks from HTML, URLs, WebViews, and live browser pages.
+It approximates the accessibility tree browsers expose, but can do it from
+static HTML before launching browser automation.
+
+The CLI defaults to `impit` for browser-like HTTP/2/TLS static fetches, detects
+hCaptcha, reCAPTCHA, and Cloudflare challenge markers, then tells agents when a
+browser is actually needed. In the local benchmark, the decision handoff used
+15.4x less peak RAM on average and 3.0x fewer decision tokens on the content
+fixture than `agent-browser snapshot`.
+
+`--search` auto mode tries DuckDuckGo, Bing, and StartPage, records every
+engine attempt, and hands ranked source choices back to the agent.
+
+</div>
+
+## 1. Try With A Prompt
+
+Paste this into a Codex session or subagent prompt before opening a browser:
+
+```md
+Before opening a browser, inspect pages with ax-grep when possible.
+
+Run:
+npx --yes ax-grep@latest <url> --agent-brief
+
+Read agent.executor, agent.handoff, agent.readTargets, pageCheck, and
+verification first. Open a browser only when the payload says static HTML is
+not enough.
+```
+
+## 2. Install The CLI Skill
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/hmmhmmhm/ax-grep/main/skills.sh | sh
+```
+
+This installs the Codex skill prompt only. Restart Codex if the new skill is not listed immediately.
+
+## 3. Try The CLI
+
+```sh
+npx --yes ax-grep@latest https://example.com --agent-brief
+```
+
+If you installed the binary globally, use `ax-grep` directly.
+Agents should read `agent.executor`, `agent.handoff`, `agent.readTargets`,
+`pageCheck`, and `verification` first. Open a browser only when the handoff
+fields say static HTML is not enough.
+
+## 4. Use From A Server
+
+Use this inside agent services built with Codex SDK, OpenRouter, or similar
+LLM routing stacks to turn fetched HTML into compact source evidence before
+spending tokens or memory on browser automation.
+
+```sh
+npm install ax-grep
+```
+
+```ts
+import { extract, formatSemanticTreeText } from "ax-grep";
+
+const html = await fetch("https://example.com").then((r) => r.text());
+const tree = extract(html);
+const promptText = formatSemanticTreeText(tree);
+```
+
+`ax-grep` is ESM-only and requires Node 18 or newer. CommonJS services can use `const { extract } = await import("ax-grep")`.
+
+## 5. Use In WebViews Or Pages
+
+In mobile apps, WebViews, and in-page agents, inject the extractor to create an
+accessibility-style structure immediately from the current page. It is useful
+for local sLLM web search, local web parsing, and instant agent-ready page
+summaries without leaving the app.
+
+```ts
+import { createExtractorScript } from "ax-grep";
+
+const script = createExtractorScript({ format: "text" });
+const text = await page.evaluate(script);
+// iOS/Android WebView: evaluateJavaScript(script) returns the same text value.
+```
 
+## Docs
+- [Documentation index](./docs/README.md)
+- [CLI skill prompt](./skills/ax-grep-cli/SKILL.md)
+- [CLI and agent mode](./docs/cli-agent.md)
+- [Agent handoff loop](./docs/agent-handoff.md)
+- [Benchmarks](./docs/benchmarks.md)
+- [Library API](./docs/library-api.md)

package/dist/browser.d.ts

@@ -0,0 +1,11 @@
+import { a as SemanticTreeOptions, S as SemanticNode, aE as SemanticTreeChange, aF as SemanticTreeObserverOptions } from './types-gwHWhYmw.js';
+
+declare function extractSemanticTree(options?: SemanticTreeOptions): SemanticNode;
+
+declare function formatSemanticTreeText(node: SemanticNode): string;
+declare function observeSemanticTree(onChange: (change: SemanticTreeChange) => void, options?: SemanticTreeObserverOptions): {
+    disconnect: () => void;
+    snapshot: () => SemanticNode;
+};
+
+export { extractSemanticTree as extract, extractSemanticTree, formatSemanticTreeText, observeSemanticTree };

package/dist/browser.js

@@ -0,0 +1,12 @@
+import {
+  extractSemanticTree,
+  formatSemanticTreeText,
+  observeSemanticTree
+} from "./chunk-HPZ32BKV.js";
+export {
+  extractSemanticTree as extract,
+  extractSemanticTree,
+  formatSemanticTreeText,
+  observeSemanticTree
+};
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}