textweb 0.1.2 → 0.2.0

package/README.md

@@ -48,26 +48,6 @@ textweb --json https://example.com
 
 ~500 bytes. An LLM can read this, understand the layout, and say "click ref 9" to open the first link. No vision model needed.
 
-## LLM Configuration
-
-TextWeb's job application pipeline uses a local or remote LLM for freeform questions. Configure via `.env` file or environment variables:
-
-```bash
-cp .env.example .env
-# Edit .env with your settings
-```
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `TEXTWEB_LLM_URL` | `http://localhost:1234/v1` | OpenAI-compatible API endpoint |
-| `TEXTWEB_LLM_API_KEY` | *(empty)* | API key (optional for local LLMs) |
-| `TEXTWEB_LLM_MODEL` | `google/gemma-3-4b` | Model name |
-| `TEXTWEB_LLM_MAX_TOKENS` | `200` | Max response tokens |
-| `TEXTWEB_LLM_TEMPERATURE` | `0.7` | Sampling temperature |
-| `TEXTWEB_LLM_TIMEOUT` | `60000` | Request timeout (ms) |
-
-Works with LM Studio, Ollama, OpenAI, or any OpenAI-compatible endpoint. No API key needed for local models.
-
 ## Integration Options
 
 TextWeb works with any AI agent framework. Pick your integration:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textweb",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A text-grid web renderer for AI agents — see the web without screenshots",
   "main": "src/browser.js",
   "bin": {

package/src/browser.js

@@ -60,7 +60,7 @@ class AgentBrowser {
   async click(ref) {
     const el = this._getElement(ref);
     await this.page.click(el.selector);
-    await this.page.waitForLoadState('networkidle').catch(() => {});
+    await this._settle();
     return await this.snapshot();
   }
 
@@ -103,7 +103,7 @@ class AgentBrowser {
 
   async press(key) {
     await this.page.keyboard.press(key);
-    await this.page.waitForLoadState('networkidle').catch(() => {});
+    await this._settle();
     return await this.snapshot();
   }
 
@@ -159,6 +159,56 @@ class AgentBrowser {
     }
   }
 
+  /**
+   * Get the current page URL
+   */
+  getCurrentUrl() {
+    return this.page ? this.page.url() : null;
+  }
+
+  /**
+   * Find elements matching a CSS selector
+   * Returns array of {tag, text, selector, visible} objects
+   */
+  async query(selector) {
+    if (!this.page) throw new Error('No page open. Call navigate() first.');
+    return await this.page.evaluate((sel) => {
+      const els = document.querySelectorAll(sel);
+      return Array.from(els).map((el, i) => ({
+        tag: el.tagName.toLowerCase(),
+        text: (el.textContent || '').trim().substring(0, 200),
+        selector: `${sel}:nth-child(${i + 1})`,
+        visible: el.offsetParent !== null,
+        href: el.href || null,
+        value: el.value || null,
+      }));
+    }, selector);
+  }
+
+  /**
+   * Take a screenshot (for debugging)
+   * @param {object} options - Playwright screenshot options (path, fullPage, type, etc.)
+   */
+  async screenshot(options = {}) {
+    if (!this.page) throw new Error('No page open. Call navigate() first.');
+    return await this.page.screenshot({
+      fullPage: true,
+      type: 'png',
+      ...options,
+    });
+  }
+
+  /**
+   * Wait for page to settle after an interaction.
+   * Races networkidle against a short timeout to avoid hanging on SPAs.
+   */
+  async _settle() {
+    await Promise.race([
+      this.page.waitForLoadState('networkidle').catch(() => {}),
+      new Promise(r => setTimeout(r, 3000)),
+    ]);
+  }
+
   _getElement(ref) {
     if (!this.lastResult) throw new Error('No snapshot. Navigate first.');
     const el = this.lastResult.elements[ref];

package/src/cli.js

@@ -17,7 +17,6 @@ function parseArgs() {
     json: false,
     serve: false,
     cols: 100,
-    rows: 30,
     port: 3000,
     help: false
   };
@@ -48,7 +47,9 @@ function parseArgs() {
         
       case '--rows':
       case '-r':
-        options.rows = parseInt(args[++i]) || 30;
+        // Deprecated: height is dynamic (grows to fit content). Ignored.
+        console.error('Warning: --rows is deprecated. Height is dynamic (grows to fit content).');
+        args[++i]; // consume the value
         break;
         
       case '--port':
@@ -85,7 +86,7 @@ USAGE:
 
 OPTIONS:
   --cols, -c <number>                Grid width in characters (default: 100)
-  --rows, -r <number>                Grid height in characters (default: 30)
+  --rows, -r <number>                (deprecated, height is dynamic)
   --port, -p <number>                Server port (default: 3000)
   --interactive, -i                  Interactive REPL mode
   --json, -j                         JSON output format
@@ -117,7 +118,7 @@ INTERACTIVE COMMANDS:
 async function render(url, options) {
   const browser = new AgentBrowser({
     cols: options.cols,
-    rows: options.rows,
+
     headless: true
   });
 
@@ -156,7 +157,7 @@ async function render(url, options) {
 async function interactive(url, options) {
   const browser = new AgentBrowser({
     cols: options.cols,
-    rows: options.rows,
+
     headless: true
   });
 
@@ -367,7 +368,7 @@ async function serve(options) {
   
   const server = createServer({
     cols: options.cols,
-    rows: options.rows
+
   });
   
   server.listen(options.port, () => {

package/src/renderer.js

@@ -7,8 +7,8 @@
  * Key design decisions:
  * - Overflow > truncation (never lose information)
  * - Measure actual font metrics from the page
- * - Table-aware layout
- * - Z-index compositing (back to front)
+ * - Row-grouping layout (elements grouped by Y position)
+ * - Dynamic height (grows to fit all content)
  */
 
 /**
@@ -277,44 +277,6 @@ async function extractElements(page) {
   });
 }
 
-/**
- * Place text onto the grid, allowing overflow (never truncate).
- * Text wraps to the next line at grid edge, continuing at the same start column.
- */
-function placeText(grid, zGrid, z, row, col, text, cols, rows) {
-  let r = row;
-  let c = col;
-
-  for (let i = 0; i < text.length; i++) {
-    // Grow grid vertically if needed (overflow — don't lose data)
-    while (r >= grid.length) {
-      grid.push(Array(cols).fill(' '));
-      zGrid.push(Array(cols).fill(-1));
-    }
-
-    if (c >= cols) {
-      // Wrap to next line at original column position
-      r++;
-      c = col;
-      while (r >= grid.length) {
-        grid.push(Array(cols).fill(' '));
-        zGrid.push(Array(cols).fill(-1));
-      }
-    }
-
-    const ch = text[i];
-    if (ch === '\n') { r++; c = col; continue; }
-
-    if (c >= 0 && c < cols && z >= zGrid[r][c]) {
-      grid[r][c] = ch;
-      zGrid[r][c] = z;
-    }
-    c++;
-  }
-
-  return r; // Return last row written to (useful for tracking grid growth)
-}
-
 /**
  * Detect row boundaries — groups of elements that share the same Y position
  * This prevents text from different elements on the same visual line from overlapping

package/src/server.js

@@ -10,7 +10,7 @@ class TextWebServer {
   constructor(options = {}) {
     this.options = {
       cols: options.cols || 100,
-      rows: options.rows || 30,
+      // rows is deprecated — height is dynamic
       timeout: options.timeout || 30000,
       ...options
     };
@@ -33,7 +33,6 @@ class TextWebServer {
     if (!this.browser) {
       this.browser = new AgentBrowser({
         cols: this.options.cols,
-        rows: this.options.rows,
         headless: true,
         timeout: this.options.timeout
       });

package/.env.example

@@ -1,25 +0,0 @@
-# TextWeb LLM Configuration
-# Copy this to .env and fill in your values
-
-# Base URL for any OpenAI-compatible API
-# Default: http://localhost:1234/v1 (LM Studio)
-# Examples:
-#   https://api.openai.com/v1
-#   https://api.anthropic.com/v1
-#   http://localhost:11434/v1 (Ollama)
-TEXTWEB_LLM_URL=http://localhost:1234/v1
-
-# API key (optional for local LLMs like LM Studio/Ollama)
-TEXTWEB_LLM_API_KEY=
-
-# Model name
-TEXTWEB_LLM_MODEL=google/gemma-3-4b
-
-# Max tokens for responses (default: 200)
-TEXTWEB_LLM_MAX_TOKENS=200
-
-# Temperature (default: 0.7)
-TEXTWEB_LLM_TEMPERATURE=0.7
-
-# Request timeout in milliseconds (default: 60000)
-TEXTWEB_LLM_TIMEOUT=60000