textweb 0.2.3 → 0.2.5

package/README.md

@@ -26,10 +26,19 @@ npx playwright install chromium
 # Render any page
 textweb https://news.ycombinator.com
 
+# Explicitly request grid mode (same as default)
+textweb --output grid https://news.ycombinator.com
+
+# Semantic JSON output for agent workflows
+textweb --output semantic https://example.com
+
+# Hybrid output (grid + semantic metadata)
+textweb --output hybrid https://example.com
+
 # Interactive mode
 textweb --interactive https://github.com
 
-# JSON output for agents
+# Legacy JSON output (backward compatible)
 textweb --json https://example.com
 ```
 
@@ -176,10 +185,11 @@ curl -X POST http://localhost:3000/scroll -d '{"direction": "down"}'
 const { AgentBrowser } = require('textweb');
 
 const browser = new AgentBrowser({ cols: 120 });
-const { view, elements, meta } = await browser.navigate('https://example.com');
+const { view, elements, semantic, meta } = await browser.navigate('https://example.com');
 
 console.log(view);        // The text grid
 console.log(elements);    // { 0: { selector, tag, text, href }, ... }
+console.log(semantic);    // { mode, url, title, elements: [...] }
 console.log(meta.stats);  // { totalElements, interactiveElements, renderMs }
 
 await browser.click(3);              // Click element [3]
@@ -275,6 +285,33 @@ Useful session tools:
 - `textweb_session_list` → inspect active sessions
 - `textweb_session_close` → close one session or all
 
+## App Runtime Prototype (Manifest + LARC)
+
+This repository now includes an early scaffold for a manifest-driven user runtime shell (separate from low-level raw admin tooling):
+
+- Manifest validator: `src/app-runtime/manifest.js`
+- PAN topic contract: `src/app-runtime/topics.js`
+- Runtime shell + left nav + tabbed content: `canvas/app-runtime/app-shell.html`
+- Sample manifest: `canvas/app-runtime/sample-app.json`
+
+The runtime shell uses [LARC](https://github.com/larcjs/larc) PAN (`@larcjs/core-lite`) for in-page event communication, with a local fallback bus if the module cannot be loaded.
+
+To open the prototype:
+
+```bash
+# Start API server for integration hooks (save manifest/components)
+npm run serve
+
+# In another terminal, open the runtime shell
+open /Users/cdr/Projects/textweb/canvas/app-runtime/app-shell.html
+```
+
+Integration actions implemented on the API server:
+- `POST /integrations/sync_saved_form`
+- `POST /integrations/save_manifest`
+- `POST /integrations/upsert_nav_item`
+- `POST /integrations/runtime_state`
+
 ## Testing
 
 ```bash

package/mcp/index.js

@@ -11,6 +11,7 @@
  */
 
 const { AgentBrowser } = require('../src/browser');
+const { ensureBrowser } = require('../src/ensure-browser');
 
 const SERVER_INFO = {
   name: 'textweb',
@@ -462,4 +463,7 @@ function main() {
   });
 }
 
-main();
+ensureBrowser().then(main).catch((err) => {
+  process.stderr.write(`Fatal: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textweb",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "A text-grid web renderer for AI agents — see the web without screenshots",
   "main": "src/browser.js",
   "bin": {
@@ -10,7 +10,10 @@
   "scripts": {
     "start": "node src/cli.js",
     "serve": "node src/server.js",
-    "test": "node test/test-form.js && node test/test-live.js && node test/test-ats-e2e.js",
+    "test": "node test/app-runtime-manifest.js && node test/runtime-integrations.js && node test/output-modes.js && node test/test-form.js && node test/test-live.js && node test/test-ats-e2e.js",
+    "test:app-runtime": "node test/app-runtime-manifest.js",
+    "test:integrations": "node test/runtime-integrations.js",
+    "test:output": "node test/output-modes.js",
     "test:form": "node test/test-form.js",
     "test:live": "node test/test-live.js",
     "test:ats": "node test/test-ats-e2e.js"

package/src/app-runtime/manifest.js

@@ -0,0 +1,220 @@
+(function initManifestModule(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+    return;
+  }
+  root.TextWebAppManifest = factory();
+})(typeof globalThis !== 'undefined' ? globalThis : this, function manifestFactory() {
+  const APP_MANIFEST_VERSION = '1';
+
+  const LIFECYCLE_EVENTS = Object.freeze([
+    'onLoad',
+    'onView',
+    'onSave',
+    'onBeforeSave',
+    'onAfterSave'
+  ]);
+
+  function isPlainObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value);
+  }
+
+  function appendError(errors, path, message) {
+    errors.push(`${path}: ${message}`);
+  }
+
+  function validateHook(hook, path, errors) {
+    if (!isPlainObject(hook)) {
+      appendError(errors, path, 'hook must be an object');
+      return;
+    }
+
+    if (typeof hook.name !== 'string' || hook.name.trim() === '') {
+      appendError(errors, `${path}.name`, 'must be a non-empty string');
+    }
+
+    if (!['client', 'server'].includes(hook.target)) {
+      appendError(errors, `${path}.target`, 'must be "client" or "server"');
+    }
+
+    if (hook.target === 'client' && (typeof hook.topic !== 'string' || hook.topic.trim() === '')) {
+      appendError(errors, `${path}.topic`, 'is required for client hooks');
+    }
+
+    if (hook.target === 'server') {
+      const hasAction = typeof hook.action === 'string' && hook.action.trim() !== '';
+      const hasEndpoint = typeof hook.endpoint === 'string' && hook.endpoint.trim() !== '';
+      if (!hasAction && !hasEndpoint) {
+        appendError(errors, path, 'server hooks require either action or endpoint');
+      }
+    }
+  }
+
+  function validateEvents(events, path, errors) {
+    if (!isPlainObject(events)) {
+      appendError(errors, path, 'must be an object');
+      return;
+    }
+
+    for (const [eventName, hooks] of Object.entries(events)) {
+      if (!LIFECYCLE_EVENTS.includes(eventName)) {
+        appendError(errors, `${path}.${eventName}`, `is not supported (allowed: ${LIFECYCLE_EVENTS.join(', ')})`);
+        continue;
+      }
+      if (!Array.isArray(hooks)) {
+        appendError(errors, `${path}.${eventName}`, 'must be an array of hooks');
+        continue;
+      }
+      hooks.forEach((hook, index) => validateHook(hook, `${path}.${eventName}[${index}]`, errors));
+    }
+  }
+
+  function validateNavItem(item, path, errors) {
+    if (!isPlainObject(item)) {
+      appendError(errors, path, 'must be an object');
+      return;
+    }
+
+    if (typeof item.id !== 'string' || item.id.trim() === '') {
+      appendError(errors, `${path}.id`, 'must be a non-empty string');
+    }
+
+    if (typeof item.label !== 'string' || item.label.trim() === '') {
+      appendError(errors, `${path}.label`, 'must be a non-empty string');
+    }
+
+    if (item.componentId != null && (typeof item.componentId !== 'string' || item.componentId.trim() === '')) {
+      appendError(errors, `${path}.componentId`, 'must be a non-empty string when provided');
+    }
+
+    const hasChildren = Array.isArray(item.children) && item.children.length > 0;
+    if (!item.componentId && !hasChildren) {
+      appendError(errors, path, 'must define componentId or non-empty children');
+    }
+
+    if (item.children != null) {
+      if (!Array.isArray(item.children)) {
+        appendError(errors, `${path}.children`, 'must be an array');
+      } else {
+        item.children.forEach((child, index) => validateNavItem(child, `${path}.children[${index}]`, errors));
+      }
+    }
+
+    if (item.events != null) {
+      validateEvents(item.events, `${path}.events`, errors);
+    }
+  }
+
+  function validateComponent(component, path, errors) {
+    if (!isPlainObject(component)) {
+      appendError(errors, path, 'must be an object');
+      return;
+    }
+
+    if (typeof component.id !== 'string' || component.id.trim() === '') {
+      appendError(errors, `${path}.id`, 'must be a non-empty string');
+    }
+
+    if (typeof component.tagName !== 'string' || component.tagName.trim() === '') {
+      appendError(errors, `${path}.tagName`, 'must be a non-empty string');
+    }
+
+    if (component.moduleUrl != null && typeof component.moduleUrl !== 'string') {
+      appendError(errors, `${path}.moduleUrl`, 'must be a string when provided');
+    }
+  }
+
+  function validateAppManifest(manifest) {
+    const errors = [];
+
+    if (!isPlainObject(manifest)) {
+      return {
+        valid: false,
+        errors: ['root: manifest must be an object']
+      };
+    }
+
+    if (String(manifest.schemaVersion || '') !== APP_MANIFEST_VERSION) {
+      appendError(errors, 'schemaVersion', `must equal "${APP_MANIFEST_VERSION}"`);
+    }
+
+    if (!isPlainObject(manifest.app)) {
+      appendError(errors, 'app', 'must be an object');
+    } else {
+      if (typeof manifest.app.id !== 'string' || manifest.app.id.trim() === '') {
+        appendError(errors, 'app.id', 'must be a non-empty string');
+      }
+      if (typeof manifest.app.name !== 'string' || manifest.app.name.trim() === '') {
+        appendError(errors, 'app.name', 'must be a non-empty string');
+      }
+    }
+
+    if (!Array.isArray(manifest.navigation) || manifest.navigation.length === 0) {
+      appendError(errors, 'navigation', 'must be a non-empty array');
+    } else {
+      manifest.navigation.forEach((item, index) => validateNavItem(item, `navigation[${index}]`, errors));
+    }
+
+    if (manifest.components != null) {
+      if (!Array.isArray(manifest.components)) {
+        appendError(errors, 'components', 'must be an array when provided');
+      } else {
+        manifest.components.forEach((component, index) => validateComponent(component, `components[${index}]`, errors));
+        const seenComponentIds = new Set();
+        manifest.components.forEach((component, index) => {
+          if (!component || typeof component.id !== 'string') return;
+          if (seenComponentIds.has(component.id)) {
+            appendError(errors, `components[${index}].id`, `duplicate id "${component.id}"`);
+            return;
+          }
+          seenComponentIds.add(component.id);
+        });
+      }
+    }
+
+    if (manifest.events != null) {
+      validateEvents(manifest.events, 'events', errors);
+    }
+
+    if (manifest.integrations != null) {
+      if (!isPlainObject(manifest.integrations)) {
+        appendError(errors, 'integrations', 'must be an object');
+      } else {
+        if (manifest.integrations.serverBaseUrl != null && typeof manifest.integrations.serverBaseUrl !== 'string') {
+          appendError(errors, 'integrations.serverBaseUrl', 'must be a string when provided');
+        }
+        if (manifest.integrations.allowedActions != null) {
+          if (!Array.isArray(manifest.integrations.allowedActions)) {
+            appendError(errors, 'integrations.allowedActions', 'must be an array when provided');
+          } else {
+            manifest.integrations.allowedActions.forEach((action, index) => {
+              if (typeof action !== 'string' || action.trim() === '') {
+                appendError(errors, `integrations.allowedActions[${index}]`, 'must be a non-empty string');
+              }
+            });
+          }
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  function assertValidAppManifest(manifest) {
+    const result = validateAppManifest(manifest);
+    if (!result.valid) {
+      throw new Error(`Invalid app manifest:\n- ${result.errors.join('\n- ')}`);
+    }
+    return manifest;
+  }
+
+  return {
+    APP_MANIFEST_VERSION,
+    LIFECYCLE_EVENTS,
+    validateAppManifest,
+    assertValidAppManifest
+  };
+});

package/src/app-runtime/topics.js

@@ -0,0 +1,46 @@
+(function initTopicsModule(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+    return;
+  }
+  root.TextWebPanTopics = factory();
+})(typeof globalThis !== 'undefined' ? globalThis : this, function topicsFactory() {
+  const PAN_TOPICS = Object.freeze({
+    APP_NAV_OPEN: 'app.nav.open',
+    APP_TAB_OPEN: 'app.tab.open',
+    APP_VIEW_LOAD: 'app.view.load',
+    FORM_SAVE_REQUEST: 'form.save.request',
+    FORM_SAVE_SUCCESS: 'form.save.success',
+    FORM_SAVE_ERROR: 'form.save.error',
+    INTEGRATION_SERVER_REQUEST: 'integration.server.request',
+    INTEGRATION_SERVER_RESPONSE: 'integration.server.response'
+  });
+
+  const EVENT_TO_TOPIC = Object.freeze({
+    onLoad: PAN_TOPICS.APP_VIEW_LOAD,
+    onView: PAN_TOPICS.APP_VIEW_LOAD,
+    onSave: PAN_TOPICS.FORM_SAVE_REQUEST,
+    onBeforeSave: PAN_TOPICS.FORM_SAVE_REQUEST,
+    onAfterSave: PAN_TOPICS.FORM_SAVE_SUCCESS
+  });
+
+  function allTopics() {
+    return Object.values(PAN_TOPICS);
+  }
+
+  function isKnownTopic(topic) {
+    return allTopics().includes(topic);
+  }
+
+  function topicForLifecycleEvent(eventName) {
+    return EVENT_TO_TOPIC[eventName] || null;
+  }
+
+  return {
+    PAN_TOPICS,
+    EVENT_TO_TOPIC,
+    allTopics,
+    isKnownTopic,
+    topicForLifecycleEvent
+  };
+});

package/src/cli.js

@@ -6,6 +6,7 @@
 
 const { AgentBrowser } = require('./browser');
 const { createServer } = require('./server');
+const { ensureBrowser } = require('./ensure-browser');
 const readline = require('readline');
 
 // Parse command line arguments
@@ -15,6 +16,7 @@ function parseArgs() {
     url: null,
     interactive: false,
     json: false,
+    output: 'grid',
     serve: false,
     cols: 100,
     port: 3000,
@@ -33,7 +35,21 @@ function parseArgs() {
       case '--json':
       case '-j':
         options.json = true;
+        options.output = 'json';
         break;
+
+      case '--output':
+      case '-o': {
+        const value = (args[++i] || '').toLowerCase();
+        if (['grid', 'semantic', 'hybrid', 'json'].includes(value)) {
+          options.output = value;
+          options.json = value === 'json';
+        } else {
+          options.help = true;
+          options.error = `Invalid --output value "${value}". Expected one of: grid, semantic, hybrid, json`;
+        }
+        break;
+      }
         
       case '--serve':
       case '-s':
@@ -81,7 +97,8 @@ TextWeb - Text-grid web renderer for AI agents
 USAGE:
   textweb <url>                    Render page and print to console
   textweb --interactive <url>      Start interactive REPL mode
-  textweb --json <url>             Output as JSON (view + elements)
+  textweb --json <url>             Output as JSON (legacy: view + elements + meta)
+  textweb --output <mode> <url>    Choose output mode (grid|semantic|hybrid|json)
   textweb --serve                  Start HTTP API server
 
 OPTIONS:
@@ -90,12 +107,15 @@ OPTIONS:
   --port, -p <number>                Server port (default: 3000)
   --interactive, -i                  Interactive REPL mode
   --json, -j                         JSON output format
+  --output, -o <mode>                Output mode: grid, semantic, hybrid, json
   --serve, -s                        Start HTTP server
   --help, -h                         Show this help message
 
 EXAMPLES:
   textweb https://example.com
   textweb --interactive https://github.com
+  textweb --output semantic https://news.ycombinator.com
+  textweb --output hybrid --cols 120 https://news.ycombinator.com
   textweb --json --cols 120 https://news.ycombinator.com
   textweb --serve --port 8080
 
@@ -125,8 +145,22 @@ async function render(url, options) {
   try {
     console.error(`Rendering: ${url}`);
     const result = await browser.navigate(url);
-    
-    if (options.json) {
+
+    if (options.output === 'semantic') {
+      console.log(JSON.stringify(result.semantic || {
+        mode: 'semantic',
+        url: result.meta?.url || null,
+        title: result.meta?.title || null,
+        elements: [],
+      }, null, 2));
+    } else if (options.output === 'hybrid') {
+      console.log(JSON.stringify({
+        mode: 'hybrid',
+        view: result.view,
+        semantic: result.semantic || { mode: 'semantic', elements: [] },
+        meta: result.meta,
+      }, null, 2));
+    } else if (options.json || options.output === 'json') {
       console.log(JSON.stringify({
         view: result.view,
         elements: result.elements,
@@ -379,6 +413,7 @@ async function serve(options) {
     console.log(`  POST /type       - Type text`);
     console.log(`  POST /scroll     - Scroll page`);
     console.log(`  POST /select     - Select dropdown option`);
+    console.log(`  POST /integrations/:action - Runtime integration hook actions`);
     console.log(`  GET  /snapshot   - Get current state`);
     console.log(`  GET  /health     - Health check`);
   });
@@ -387,12 +422,19 @@ async function serve(options) {
 // Main entry point
 async function main() {
   const options = parseArgs();
+  if (options.error) {
+    console.error(`Error: ${options.error}`);
+    showHelp();
+    process.exit(1);
+  }
   
   if (options.help || (process.argv.length === 2)) {
     showHelp();
     return;
   }
-  
+
+  await ensureBrowser();
+
   if (options.serve) {
     await serve(options);
   } else if (options.interactive) {
@@ -425,4 +467,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { parseArgs, render, interactive, serve };
+module.exports = { parseArgs, render, interactive, serve };

package/src/ensure-browser.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * ensure-browser.js
+ *
+ * Checks whether Playwright's Chromium is installed and, when running
+ * in an interactive terminal, offers to install it automatically.
+ *
+ * All output goes to stderr so it never pollutes stdout-based protocols
+ * (e.g. the MCP JSON-RPC transport).
+ */
+
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+const readline = require('readline');
+
+function ask(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function log(msg) {
+  process.stderr.write(msg + '\n');
+}
+
+function isInstalled() {
+  try {
+    const { chromium } = require('playwright');
+    const execPath = chromium.executablePath();
+    return fs.existsSync(execPath);
+  } catch {
+    return false;
+  }
+}
+
+function install() {
+  // Prefer the local playwright CLI (bundled with the dep) over npx
+  let cliPath = null;
+  try {
+    cliPath = require.resolve('playwright/cli.js');
+  } catch { /* fall through to npx */ }
+
+  const result = cliPath
+    ? spawnSync(process.execPath, [cliPath, 'install', 'chromium'], { stdio: 'inherit' })
+    : spawnSync('npx', ['playwright', 'install', 'chromium'], { stdio: 'inherit', shell: true });
+
+  return result.status === 0;
+}
+
+async function ensureBrowser() {
+  if (isInstalled()) return;
+
+  log('');
+  log('⚠  Playwright Chromium is not installed — textweb needs it to browse the web.');
+
+  if (process.stdin.isTTY) {
+    const answer = await ask('   Install it now? (Y/n) ');
+    if (answer.toLowerCase() === 'n') {
+      log('');
+      log('   Run manually:  npx playwright install chromium');
+      log('');
+      process.exit(1);
+    }
+  } else {
+    log('');
+    log('   Run:  npx playwright install chromium');
+    log('');
+    process.exit(1);
+  }
+
+  log('');
+  log('   Installing Chromium — this takes ~30 seconds the first time…');
+  log('');
+
+  if (!install()) {
+    log('');
+    log('   Installation failed. Run manually:  npx playwright install chromium');
+    log('');
+    process.exit(1);
+  }
+
+  log('');
+  log('✓  Chromium installed successfully!');
+  log('');
+}
+
+module.exports = { ensureBrowser };

package/src/renderer.js

@@ -56,6 +56,7 @@ async function measureCharSize(page) {
 async function extractElements(page) {
   return await page.evaluate(() => {
     const results = [];
+    const interactiveSelector = 'a[href], button, input, select, textarea, [onclick], [role="button"], [role="link"], [tabindex]:not([tabindex="-1"]), summary';
 
     function isVisible(el) {
       const style = getComputedStyle(el);
@@ -131,7 +132,24 @@ async function extractElements(page) {
     }
 
     function isInteractive(el) {
-      return el.matches('a[href], button, input, select, textarea, [onclick], [role="button"], [role="link"], [tabindex]:not([tabindex="-1"]), summary');
+      return el.matches(interactiveSelector);
+    }
+
+    function domPath(el) {
+      const parts = [];
+      let current = el;
+      while (current && current.nodeType === Node.ELEMENT_NODE && current !== document.body) {
+        const tag = current.tagName.toLowerCase();
+        let idx = 1;
+        let sib = current;
+        while ((sib = sib.previousElementSibling)) {
+          if (sib.tagName.toLowerCase() === tag) idx++;
+        }
+        parts.push(`${tag}:${idx}`);
+        current = current.parentElement;
+      }
+      parts.push('body:1');
+      return parts.reverse().join('/');
     }
 
     // Detect tables and extract their structure
@@ -203,18 +221,23 @@ async function extractElements(page) {
 
       const tag = el.tagName.toLowerCase();
       const interactive = isInteractive(el);
+      const role = el.getAttribute('role') || null;
 
       let text = '';
+      let value = null;
       if (isText) {
         text = node.textContent.trim();
       } else if (tag === 'input') {
         const type = (el.type || 'text').toLowerCase();
         text = el.value || el.placeholder || '';
+        value = el.value || '';
       } else if (tag === 'select') {
         const opt = el.options && el.options[el.selectedIndex];
         text = opt ? opt.text : '';
+        value = el.value || '';
       } else if (tag === 'textarea') {
         text = el.value || el.placeholder || '';
+        value = el.value || '';
       } else if (tag === 'img') {
         text = el.alt || '[img]';
       } else if (tag === 'hr') {
@@ -286,14 +309,28 @@ async function extractElements(page) {
         }
       }
 
+      const parentElement = el.parentElement;
+      const parentInteractive = !!(parentElement && parentElement.matches(interactiveSelector));
+      const parentPath = parentElement ? domPath(parentElement) : null;
+
       results.push({
         text,
         label: label || '',
+        role,
         tag,
         semantic,
         headingLevel: headingMatch ? parseInt(headingMatch[1]) : 0,
         interactive,
+        isTextNode: isText,
         checked: !!el.checked,
+        selected: !!el.selected,
+        disabled: !!el.disabled,
+        required: !!el.required,
+        expanded: el.getAttribute('aria-expanded') === 'true',
+        placeholder: el.getAttribute('placeholder') || null,
+        name: el.getAttribute('name') || '',
+        alt: el.getAttribute('alt') || '',
+        value,
         x: rect.x,
         y: rect.y,
         w: rect.width,
@@ -301,6 +338,9 @@ async function extractElements(page) {
         z: getZIndex(el),
         href: el.href || null,
         selector: buildSelector(el),
+        domPath: domPath(el),
+        parentPath,
+        parentInteractive,
         tableCell,
       });
     }
@@ -311,6 +351,103 @@ async function extractElements(page) {
   });
 }
 
+function stableHash(input) {
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = ((hash << 5) + hash) + input.charCodeAt(i);
+    hash |= 0;
+  }
+  return (hash >>> 0).toString(36);
+}
+
+function buildSemanticModel(rawElements, layoutEntries, pageMeta) {
+  const layoutByDomPath = new Map();
+  for (const item of layoutEntries || []) {
+    const key = item.domPath || `${item.selector}|${item.x}|${item.y}`;
+    layoutByDomPath.set(key, item);
+  }
+
+  const elements = [];
+  const byPath = new Map();
+  const rawByPath = new Map();
+  const identityCounts = new Map();
+
+  for (let i = 0; i < rawElements.length; i++) {
+    const el = rawElements[i];
+    rawByPath.set(el.domPath, el);
+    const name = (el.label || el.text || el.alt || el.name || '').trim();
+    const baseSeed = [
+      el.semantic || 'unknown',
+      el.role || '',
+      name.toLowerCase(),
+      el.parentPath || '',
+      el.domPath || '',
+    ].join('|');
+    const ordinal = identityCounts.get(baseSeed) || 0;
+    identityCounts.set(baseSeed, ordinal + 1);
+    const id = `e_${stableHash(`${baseSeed}|${ordinal}`).slice(0, 8)}`;
+
+    const layoutKey = el.domPath || `${el.selector}|${el.x}|${el.y}`;
+    const layout = layoutByDomPath.get(layoutKey);
+    const semanticEl = {
+      id,
+      type: el.semantic || 'text',
+      role: el.role || null,
+      name: name || null,
+      text: el.text || null,
+      value: el.value ?? null,
+      href: el.href || null,
+      placeholder: el.placeholder || null,
+      checked: typeof el.checked === 'boolean' ? el.checked : null,
+      selected: typeof el.selected === 'boolean' ? el.selected : null,
+      disabled: !!el.disabled,
+      required: !!el.required,
+      expanded: !!el.expanded,
+      visible: true,
+      parent_id: null,
+      children: [],
+      grid_ref: layout && layout.ref !== null ? layout.ref : null,
+      grid_bounds: layout ? {
+        row: layout.row,
+        col_start: layout.colStart,
+        col_end: layout.colEnd,
+      } : null,
+      selector: el.selector,
+      path: el.domPath,
+      // Future hooks: action routing and structural diff matching.
+      actions: el.interactive ? ['click'] : [],
+    };
+
+    if (semanticEl.type === 'input' || semanticEl.type === 'textarea' || semanticEl.type === 'select') {
+      semanticEl.actions.push('type');
+    }
+    if (semanticEl.type === 'select') {
+      semanticEl.actions.push('select');
+    }
+
+    byPath.set(el.domPath, semanticEl);
+    elements.push(semanticEl);
+  }
+
+  for (const el of elements) {
+    const raw = rawByPath.get(el.path);
+    const parentPath = raw ? raw.parentPath : null;
+    if (!parentPath) continue;
+    const parent = byPath.get(parentPath);
+    if (parent) {
+      el.parent_id = parent.id;
+      parent.children.push(el.id);
+    }
+  }
+
+  return {
+    mode: 'semantic',
+    url: pageMeta.url || null,
+    title: pageMeta.title || null,
+    elements,
+  };
+}
+
 /**
  * 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
@@ -384,10 +521,12 @@ function formatElement(el, ref, cols, startCol, charW) {
  * 3. Each visual row maps to one or more grid lines
  * 4. Grid grows as needed (overflow — never lose data)
  */
-function renderGrid(elements, cols, charW, charH, scrollY = 0) {
+function renderGrid(elements, cols, charW, charH, scrollY = 0, options = {}) {
+  const { includeLayout = false } = options;
   const elementMap = {};
   let refId = 0;
   const lines = []; // output lines as strings
+  const layout = [];
 
   // Filter to viewport (vertically — allow overflow below)
   const visible = elements.filter(el => {
@@ -399,6 +538,7 @@ function renderGrid(elements, cols, charW, charH, scrollY = 0) {
   const visualRows = groupByRows(visible, charH);
 
   for (const rowElements of visualRows) {
+    const rowIndex = lines.length;
     // Sort elements in this row by X position (left to right)
     rowElements.sort((a, b) => a.x - b.x);
 
@@ -428,18 +568,35 @@ function renderGrid(elements, cols, charW, charH, scrollY = 0) {
       const display = formatElement(el, ref, cols, targetCol, charW);
       if (!display) continue;
 
+      let startCol = cursor;
       if (targetCol > cursor) {
         // Pad with spaces to reach the target column
         line += ' '.repeat(targetCol - cursor);
         cursor = targetCol;
+        startCol = cursor;
       } else if (cursor > 0 && targetCol <= cursor) {
         // Elements overlap — add a single space separator
         line += ' ';
         cursor += 1;
+        startCol = cursor;
       }
 
       line += display;
       cursor += display.length;
+
+      if (includeLayout) {
+        layout.push({
+          ref,
+          row: rowIndex,
+          colStart: startCol,
+          colEnd: cursor - 1,
+          selector: el.selector,
+          domPath: el.domPath,
+          semantic: el.semantic,
+          x: el.x,
+          y: el.y,
+        });
+      }
     }
 
     lines.push(line.trimEnd());
@@ -448,11 +605,13 @@ function renderGrid(elements, cols, charW, charH, scrollY = 0) {
   // Remove trailing empty lines
   while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
 
-  return {
+  const result = {
     view: lines.join('\n'),
     elements: elementMap,
     meta: { cols, rows: lines.length, scrollY, totalRefs: refId, charW, charH }
   };
+  if (includeLayout) result.layout = layout;
+  return result;
 }
 
 /**
@@ -468,7 +627,12 @@ async function render(page, options = {}) {
   const charH = metrics.charH;
   
   const elements = await extractElements(page);
-  const result = renderGrid(elements, cols, charW, charH, scrollY);
+  const gridResult = renderGrid(elements, cols, charW, charH, scrollY, { includeLayout: true });
+  const result = {
+    view: gridResult.view,
+    elements: gridResult.elements,
+    meta: gridResult.meta,
+  };
   
   // Add stats to meta
   result.meta.stats = {
@@ -476,8 +640,10 @@ async function render(page, options = {}) {
     interactiveElements: result.meta.totalRefs,
     renderMs: Date.now() - startMs,
   };
+
+  result.semantic = buildSemanticModel(elements, gridResult.layout || [], result.meta);
   
   return result;
 }
 
-module.exports = { render, extractElements, renderGrid, measureCharSize };
+module.exports = { render, extractElements, renderGrid, measureCharSize, buildSemanticModel };

package/src/server.js

@@ -4,7 +4,10 @@
 
 const http = require('http');
 const url = require('url');
+const path = require('path');
+const fs = require('fs/promises');
 const { AgentBrowser } = require('./browser');
+const { assertValidAppManifest } = require('./app-runtime/manifest');
 
 class TextWebServer {
   constructor(options = {}) {
@@ -12,6 +15,7 @@ class TextWebServer {
       cols: options.cols || 100,
       // rows is deprecated — height is dynamic
       timeout: options.timeout || 30000,
+      appRuntimeDir: options.appRuntimeDir || path.join(process.cwd(), 'canvas', 'app-runtime'),
       ...options
     };
     
@@ -125,6 +129,18 @@ class TextWebServer {
     }
 
     try {
+      if (method === 'GET' && this.isAppRuntimePath(pathname)) {
+        return await this.handleAppRuntimeStatic(req, res, pathname);
+      }
+
+      if (pathname.startsWith('/integrations/')) {
+        if (method === 'POST') {
+          const action = decodeURIComponent(pathname.replace('/integrations/', '') || '');
+          return await this.handleIntegrationAction(req, res, action);
+        }
+        return this.sendError(res, `Method ${method} not allowed for ${pathname}`, 405);
+      }
+
       switch (pathname) {
         case '/health':
           return this.handleHealth(req, res);
@@ -362,14 +378,15 @@ class TextWebServer {
     if (typeof body.ref !== 'number') {
       return this.sendError(res, 'Element reference (ref) is required');
     }
-    if (!body.files) {
-      return this.sendError(res, 'files (string or array of file paths) is required');
+    const filePaths = body.files ?? body.path;
+    if (!filePaths) {
+      return this.sendError(res, 'files or path (string or array of file paths) is required');
     }
     if (!this.browser) {
       return this.sendError(res, 'Browser not initialized. Navigate to a page first.');
     }
     
-    const result = await this.browser.upload(body.ref, body.files);
+    const result = await this.browser.upload(body.ref, filePaths);
     
     this.sendJSON(res, {
       success: true,
@@ -470,6 +487,198 @@ class TextWebServer {
     res.end(screenshot);
   }
 
+  isAppRuntimePath(pathname) {
+    return pathname === '/' || pathname === '/app-runtime' || pathname.startsWith('/app-runtime/');
+  }
+
+  contentTypeFor(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === '.html') return 'text/html; charset=utf-8';
+    if (ext === '.js' || ext === '.mjs') return 'application/javascript; charset=utf-8';
+    if (ext === '.json') return 'application/json; charset=utf-8';
+    if (ext === '.css') return 'text/css; charset=utf-8';
+    if (ext === '.svg') return 'image/svg+xml';
+    return 'text/plain; charset=utf-8';
+  }
+
+  async handleAppRuntimeStatic(req, res, pathname) {
+    let relative = pathname;
+    if (relative === '/') {
+      relative = '/app-runtime/app-shell.html';
+    } else if (relative === '/app-runtime') {
+      relative = '/app-runtime/app-shell.html';
+    }
+
+    const runtimeRoot = path.resolve(this.options.appRuntimeDir);
+    const runtimeRelative = relative.replace(/^\/app-runtime\/?/, '');
+    const candidate = path.resolve(path.join(runtimeRoot, runtimeRelative));
+    if (!candidate.startsWith(runtimeRoot)) {
+      return this.sendError(res, 'Not found', 404);
+    }
+
+    try {
+      const data = await fs.readFile(candidate);
+      res.writeHead(200, {
+        'Content-Type': this.contentTypeFor(candidate),
+        'Access-Control-Allow-Origin': '*'
+      });
+      res.end(data);
+    } catch (error) {
+      if (error && error.code === 'ENOENT') {
+        return this.sendError(res, 'Not found', 404);
+      }
+      throw error;
+    }
+  }
+
+  runtimePath(...segments) {
+    return path.join(this.options.appRuntimeDir, ...segments);
+  }
+
+  sanitizeFileName(name, fallback = 'app.manifest.json') {
+    const candidate = String(name || '').trim();
+    const safe = candidate
+      .replace(/[^a-zA-Z0-9._-]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^\.+/, '');
+    if (!safe) return fallback;
+    return safe.endsWith('.json') ? safe : `${safe}.json`;
+  }
+
+  async readJSON(filePath, defaultValue) {
+    try {
+      const raw = await fs.readFile(filePath, 'utf8');
+      return JSON.parse(raw);
+    } catch (error) {
+      if (error && error.code === 'ENOENT') {
+        return defaultValue;
+      }
+      throw error;
+    }
+  }
+
+  async writeJSON(filePath, value) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  }
+
+  findNavItemById(items, id) {
+    for (const item of items) {
+      if (item.id === id) return item;
+      if (Array.isArray(item.children)) {
+        const child = this.findNavItemById(item.children, id);
+        if (child) return child;
+      }
+    }
+    return null;
+  }
+
+  async handleIntegrationAction(req, res, action) {
+    const body = await this.parseBody(req);
+    const handlers = {
+      sync_saved_form: this.handleIntegrationSyncSavedForm.bind(this),
+      save_manifest: this.handleIntegrationSaveManifest.bind(this),
+      upsert_nav_item: this.handleIntegrationUpsertNavItem.bind(this),
+      runtime_state: this.handleIntegrationRuntimeState.bind(this)
+    };
+
+    const handler = handlers[action];
+    if (!handler) {
+      return this.sendError(res, `Unknown integration action: ${action}`, 404);
+    }
+
+    const result = await handler(body);
+    this.sendJSON(res, {
+      success: true,
+      action,
+      result
+    });
+  }
+
+  async handleIntegrationSyncSavedForm(body) {
+    const componentId = String(body.componentId || '').trim();
+    if (!componentId) {
+      throw new Error('componentId is required');
+    }
+    if (!Array.isArray(body.schema)) {
+      throw new Error('schema must be an array');
+    }
+
+    const targetPath = this.runtimePath('generated-components.json');
+    const current = await this.readJSON(targetPath, []);
+    const next = current.filter(entry => entry.id !== componentId);
+    next.push({
+      id: componentId,
+      label: String(body.label || componentId),
+      schema: body.schema,
+      updatedAt: new Date().toISOString()
+    });
+    await this.writeJSON(targetPath, next);
+    return { saved: true, path: targetPath, total: next.length };
+  }
+
+  async handleIntegrationSaveManifest(body) {
+    const manifest = body.manifest;
+    assertValidAppManifest(manifest);
+
+    const fileName = this.sanitizeFileName(body.fileName, `${manifest.app.id}.json`);
+    const targetPath = this.runtimePath('manifests', fileName);
+    await this.writeJSON(targetPath, manifest);
+    return { saved: true, path: targetPath, fileName };
+  }
+
+  async handleIntegrationUpsertNavItem(body) {
+    const manifest = body.manifest;
+    const navItem = body.navItem;
+    const parentId = body.parentId ? String(body.parentId) : null;
+
+    assertValidAppManifest(manifest);
+    if (!navItem || typeof navItem !== 'object') {
+      throw new Error('navItem is required');
+    }
+    if (!navItem.id || !navItem.label || !navItem.componentId) {
+      throw new Error('navItem.id, navItem.label, and navItem.componentId are required');
+    }
+
+    const target = {
+      id: String(navItem.id),
+      label: String(navItem.label),
+      componentId: String(navItem.componentId),
+      events: navItem.events || undefined
+    };
+
+    let collection = manifest.navigation;
+    if (parentId) {
+      const parent = this.findNavItemById(manifest.navigation, parentId);
+      if (!parent) {
+        throw new Error(`parentId not found: ${parentId}`);
+      }
+      if (!Array.isArray(parent.children)) {
+        parent.children = [];
+      }
+      collection = parent.children;
+    }
+
+    const existingIndex = collection.findIndex(item => item.id === target.id);
+    if (existingIndex >= 0) {
+      collection[existingIndex] = { ...collection[existingIndex], ...target };
+    } else {
+      collection.push(target);
+    }
+
+    assertValidAppManifest(manifest);
+    return { saved: true, navItemId: target.id, parentId };
+  }
+
+  async handleIntegrationRuntimeState() {
+    const componentPath = this.runtimePath('generated-components.json');
+    const components = await this.readJSON(componentPath, []);
+    return {
+      generatedComponentsPath: componentPath,
+      generatedComponents: components
+    };
+  }
+
   /**
    * Close browser
    */
@@ -500,4 +709,4 @@ function createServer(options = {}) {
   });
 }
 
-module.exports = { createServer, TextWebServer };
+module.exports = { createServer, TextWebServer };