@wenathlan/saddle 1.8.1

package/readme.txt

@@ -0,0 +1,163 @@
+                    SADDLE - README
+                       Version 1.0, August 2026
+
+ Copyright (C) August 2026 devthink, nathlan, iakadion, nathu filho, allan neris, andraneris
+ Everyone is permitted to view this document, but changing it
+ is not allowed. This document is part of Project saddle.
+
+                            Preamble
+
+  Project saddle unifies both README sources.
+
+  Saddle is a JavaScript ESM engine for jobs that move data between storage,
+  a working set, an injected runner and durable artifacts. It includes
+  contracts for scraping, crawling, browser agents, queues, persistence,
+  MCP transport, webhooks and package delivery.
+
+  Core thesis: storage bytes and compute-memory bytes are the same bytes.
+  A Node.js framework runs on other people's runners, loading storage
+  buckets as virtual RAM/GPU via storage->RAM bridge.
+
+  This README is the single source of truth combining Foundation, Engine,
+  and Productization sections from both original READMEs.
+
+                       TERMS AND CONDITIONS
+
+  0. Overview.
+
+  See full readme.md for complete documentation, API, execution model,
+  CLI, security boundaries, package surfaces, development, and repository
+  map.
+
+  1. What is Included.
+
+  Jobs, Storage, Working set, Scraping, Crawl, Browser, Operations,
+  Protocols, Delivery, Agent Browser, Compute Backends, Storage Backends.
+
+  2. License.
+
+  Proprietary - View Only. See license.txt.
+
+                     END OF TERMS AND CONDITIONS
+
+
+# Saddle
+
+<p align="center">
+  <img src="docs/assets/saddlemark.svg" alt="Saddle" width="720" />
+</p>
+
+<p align="center">
+  <strong>Storage-backed jobs, scraping contracts and portable runners for Node.js.</strong><br/>
+  <strong>Binary computing agent, agent browser, computer-use, scraper and packager.</strong><br/>
+  <a href="https://github.com/iakadion/saddle/actions/workflows/ci.yml"><img src="https://github.com/iakadion/saddle/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/iakadion/saddle/releases/tag/v1.0.0"><img src="https://img.shields.io/badge/release-v1.0.0-d35d3d" alt="Release 1.0.0" /></a>
+  <a href="https://github.com/iakadion/saddle/blob/main/license.md"><img src="https://img.shields.io/badge/license-Proprietary--View--Only-202a2f" alt="Proprietary View Only" /></a>
+</p>
+
+> **Core idea:** storage is the durable side of the working set; the runner is replaceable; the artifact is the boundary. **Storage == Compute** — RAM and disk are the same construct, differing only by usage flag.
+
+Saddle is a **JavaScript ESM engine** for jobs that move data between storage, a working set, an injected runner and durable artifacts. It is also a **virtual machine you publish as a package** that runs on other people's computers (GitHub Actions, Forgejo, Gitea, GitLab, Codeberg, free Docker containers) and turns unlimited third-party storage buckets into virtual RAM/GPU/CPU. Nothing runs on the operator's local machine.
+
+Ships as a library, CLI, binary, n8n node, CRX extension, Android/iOS and Tauri desktop app. Package `@devthink/saddle` — published to npm, GitHub Packages, Maven, NuGet, RubyGems and GHCR (auto-mirrored to jsDelivr).
+
+## Start here
+
+Saddle requires **Node.js 22 or newer**.
+
+```bash
+npm install @devthink/saddle
+```
+
+```js
+import { scrapeurl, formatforagent } from "@devthink/saddle";
+
+const result = await scrapeurl("https://example.com", { format: "markdown" });
+const context = formatforagent(result, { maxchunksize: 2000, keypoints: 4 });
+
+console.log(context.summary);
+```
+
+Deterministic example with no network:
+
+```bash
+node examples/publicapi.js
+```
+
+## What is included
+
+| Area | Contract | Result |
+| --- | --- | --- |
+| Jobs | `engine`, `scheduler`, `inprocess` | `prepare → process → sync → cleanup` |
+| Storage | local, chunked, S3-compatible, GitHub Contents, file hosting | durable objects and chunks |
+| Working set | memory bridge, modes, objects, transforms | storage-to-compute and compute-to-storage |
+| Scraping | robots, cache, extraction, schema, scraper | text, metadata, links and structured output |
+| Crawl | normalization, BFS crawler, persistent frontier | bounded domain-aware crawling |
+| Browser | fingerprint, session, replay and injected agent | browser actions without vendor lock-in |
+| Operations | queues, idempotency, saga, retry, circuit breaker | controlled execution and recovery |
+| Protocols | JSON, NDJSON, SSE, blocks and MCP | transport-neutral messages |
+| Delivery | manifests, workflow registry, binary/container plans | package and runner surfaces |
+| Agent Browser | capture & replay, stealth, fingerprint | Brave capture, movement replay, session recording |
+| Compute Backends | github-actions, huggingface, gitlab-ci, kaggle, oracle-cloud | free runners chain |
+| Storage Backends | HF, Kaggle, Terabox, R2, Telegram, Discord via rclone | unlimited disk as RAM |
+
+## Public API
+
+| Export | Purpose |
+| --- | --- |
+| `saddleurl` | choose fetch or injected browser path |
+| `scrapeurl` | fetch one URL and extract |
+| `scrapehtml` | extract from HTML without network |
+| `extractcontent` | structured extraction |
+| `serializeresult` | serialize as JSON, Markdown, XML |
+| `formatforagent` | summary, chunks, token count |
+| `batchscrape` | bounded URL groups |
+| `crawlurl` | crawl contract |
+| `browseragent` | navigation, click, type, screenshot |
+| `mcpserver` / `mcptransport` | MCP tools over JSONL/HTTP |
+| `nodeserver` | Web Request/Response handler |
+
+Complete API: `docs/libraryapi.md`
+
+## The execution model
+
+Saddle coordinates contracts instead of hiding providers. A repo + CI runner is a virtual processor:
+
+- Repo = Disk (persistent state)
+- CI = CPU (workflow_dispatch = function call)
+- Pages = Bus + CDN
+- Static site = BIOS
+- repository_dispatch = IPC
+
+```js
+import { engine, eventbus, inprocess, localmemory, localstorage, scheduler } from "@devthink/saddle";
+const events = eventbus();
+const run = engine({
+  storage: localstorage("./.saddle-data"),
+  memory: localmemory(),
+  scheduler: scheduler([inprocess()]),
+  events
+});
+const result = await run.run(
+  { name: "example", input: { value: 42 } },
+  ({ job }) => ({ jobid: job.id, ok: true })
+);
+```
+
+## CLI
+
+```bash
+saddle help
+saddle modes
+saddle runexample
+saddle mcp
+saddle capture --url <url>
+saddle bot --platform github --token $SBOT_TOKEN
+saddle memory --load repo://owner/repo/path/file.json
+saddle deploy --target netlify
+```
+
+## Security boundaries
+
+| Boundary | Policy |
+| --- | --- 

package/retry/circuit.js

@@ -0,0 +1,15 @@
+/**
+ * circuit breaker protects providers from repeated failure storms.
+ */
+export function circuitbreaker(options = {}) {
+  const threshold = options.failurethreshold ?? 5;
+  const resettimeout = options.resettimeout ?? 60000;
+  let failures = 0;
+  let openedat = 0;
+  let state = "closed";
+  async function execute(handler) {
+    if (state === "open") { if (Date.now() - openedat < resettimeout) throw new Error("circuit breaker is open"); state = "halfopen"; }
+    try { const result = await handler(); failures = 0; state = "closed"; return result; } catch (error) { failures += 1; if (failures >= threshold) { state = "open"; openedat = Date.now(); } throw error; }
+  }
+  return { execute, status() { return { state, failures, openedat }; }, reset() { failures = 0; openedat = 0; state = "closed"; } };
+}

package/retry/policy.js

@@ -0,0 +1,12 @@
+/**
+ * retry policy handles transient errors and keeps non retryable failures terminal.
+ */
+export function retrypolicy(options = {}) {
+  const maxattempts = options.maxattempts ?? 3;
+  const base = options.base ?? 1000;
+  const factor = options.factor ?? 2;
+  const cap = options.cap ?? 30000;
+  return { async run(handler) { let last; for (let attempt = 1; attempt <= maxattempts; attempt += 1) { try { return await handler(attempt); } catch (error) { last = error; if (error?.retryable !== true || attempt === maxattempts) throw error; const wait = Math.min(cap, base * factor ** (attempt - 1)) + Math.floor(Math.random() * (options.jitter ?? 0)); options.onretry?.({ attempt, wait, error }); await delay(wait); } } throw last; } };
+}
+
+function delay(milliseconds) { return milliseconds ? new Promise((resolve) => setTimeout(resolve, milliseconds)) : Promise.resolve(); }

package/runners/health.js

@@ -0,0 +1,23 @@
+/**
+ * runner health checks describe provider capacity without selecting infrastructure.
+ */
+
+/** Checks provider readiness and returns a serializable health report. */
+export async function runnerhealth(provider, job = {}) {
+  if (typeof provider?.descriptor !== "function" || typeof provider?.canrun !== "function") throw new TypeError("runner health requires a provider");
+  const descriptor = provider.descriptor();
+  try {
+    const available = await provider.canrun(job);
+    return { id: String(descriptor.id), status: available ? descriptor.status ?? "available" : "busy", healthy: Boolean(available), checkedat: Date.now(), capacity: { maxconcurrent: descriptor.maxconcurrent, capabilities: [...(descriptor.capabilities ?? [])] } };
+  } catch (error) {
+    return { id: String(descriptor.id), status: "offline", healthy: false, checkedat: Date.now(), capacity: { maxconcurrent: descriptor.maxconcurrent, capabilities: [...(descriptor.capabilities ?? [])] }, error: { code: String(error.code ?? "RUNNER_HEALTH_FAILED"), message: String(error.message ?? error) } };
+  }
+}
+
+/** Checks a provider list in stable order and summarizes available capacity. */
+export async function runnerhealthall(providers = [], job = {}) {
+  if (!Array.isArray(providers)) throw new TypeError("runner health providers must be an array");
+  const reports = [];
+  for (const provider of providers) reports.push(await runnerhealth(provider, job));
+  return { checkedat: Date.now(), reports, available: reports.filter((report) => report.healthy).length, total: reports.length };
+}

package/runners/heartbeat.js

@@ -0,0 +1,26 @@
+/**
+ * heartbeat manages cooperative liveness signals for long-running local or remote jobs.
+ */
+
+/** Creates a heartbeat controller with manual ticks and optional interval execution. */
+export function heartbeat(options = {}) {
+  const interval = Number(options.interval ?? 30000);
+  if (!Number.isFinite(interval) || interval < 1) throw new TypeError("heartbeat interval must be positive");
+  let timer;
+  let sequence = 0;
+  let last;
+  const listeners = new Set();
+
+  async function tick(input = {}) {
+    const signal = { id: String(input.id ?? options.id ?? "job"), sequence: ++sequence, at: Date.now(), status: String(input.status ?? "running"), metadata: { ...(input.metadata ?? {}) } };
+    last = signal;
+    for (const listener of listeners) await listener({ ...signal, metadata: { ...signal.metadata } });
+    return signal;
+  }
+
+  function on(listener) { if (typeof listener !== "function") throw new TypeError("heartbeat listener must be a function"); listeners.add(listener); return () => listeners.delete(listener); }
+  function start(input = {}) { if (timer) return false; const run = () => tick(input).catch(() => undefined); timer = setInterval(run, interval); return true; }
+  function stop() { if (!timer) return false; clearInterval(timer); timer = undefined; return true; }
+  function status() { return { running: Boolean(timer), interval, sequence, last: last ? { ...last, metadata: { ...last.metadata } } : undefined }; }
+  return { tick, on, start, stop, status };
+}

package/runners/inprocess.js

@@ -0,0 +1,19 @@
+/**
+ * the in process runner is the deterministic baseline for local execution.
+ */
+export function inprocess(options = {}) {
+  let available = options.status !== "offline";
+  const runner = {
+    id: options.id ?? "runnerlocal",
+    name: options.name ?? "local in process runner",
+    priority: options.priority ?? 0,
+    maxconcurrent: options.maxconcurrent ?? 1,
+    capabilities: options.capabilities ?? ["node", "local"]
+  };
+  return {
+    descriptor() { return { ...runner, status: available ? "available" : "offline" }; },
+    setavailable(value) { available = Boolean(value); },
+    async canrun() { return available; },
+    async execute(context, handler) { return handler(context); }
+  };
+}

package/runners/scheduler.js

@@ -0,0 +1,16 @@
+/**
+ * scheduling uses stable priority order and selects the first available runner.
+ */
+import { runnerunavailable } from "../core/errors.js";
+
+export function scheduler(providers) {
+  if (!Array.isArray(providers) || providers.length === 0) throw new TypeError("scheduler requires providers");
+  const ordered = [...providers].sort((left, right) => left.descriptor().priority - right.descriptor().priority);
+  return {
+    async select(job) {
+      for (const provider of ordered) if (provider.descriptor().status === "available" && await provider.canrun(job)) return provider;
+      throw runnerunavailable(job.id);
+    },
+    list() { return [...ordered]; }
+  };
+}

package/runtime/abort.js

@@ -0,0 +1,10 @@
+/**
+ * abort helpers unify deadlines without depending on a server framework.
+ */
+export function deadline(milliseconds, parent) {
+  if (!Number.isFinite(milliseconds) || milliseconds < 1) throw new TypeError("deadline must be positive");
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error("deadline exceeded")), milliseconds);
+  if (parent) parent.addEventListener("abort", () => controller.abort(parent.reason), { once: true });
+  return { signal: controller.signal, cancel() { clearTimeout(timer); controller.abort(); } };
+}

package/runtime/compatibility.js

@@ -0,0 +1,13 @@
+/**
+ * compatibility contracts describe core capabilities without importing a runtime-specific adapter.
+ */
+
+import { runtimefeatures, runtimename } from "./detect.js";
+
+export const corecapabilities = Object.freeze(["esm", "fetch", "streams", "textencoding", "webcrypto"]);
+
+/** Reports the runtime capabilities expected by the transport-neutral root entry. */
+export function runtimecontract(scope = globalThis) { const features = runtimefeatures(scope); return { runtime: runtimename(scope), core: true, capabilities: { esm: true, fetch: features.fetch, streams: features.streams, textencoding: typeof scope.TextEncoder === "function" && typeof scope.TextDecoder === "function", webcrypto: Boolean(scope.crypto?.subtle) }, nodeonly: { filesystem: features.filesystem, server: Boolean(scope.process?.versions?.node) } }; }
+
+/** Returns a structured unsupported-mode error for a missing runtime capability. */
+export function unsupportedruntime(feature, contract = runtimecontract()) { const error = new Error(`runtime capability is unavailable: ${feature}`); error.code = "UNSUPPORTED_RUNTIME"; error.feature = String(feature); error.runtime = contract.runtime; return error; }

package/runtime/detect.js

@@ -0,0 +1,14 @@
+/**
+ * runtime detection uses standard globals and keeps node specific modules outside the core.
+ */
+export function runtimename(scope = globalThis) {
+  if (scope.Deno) return "deno";
+  if (scope.Bun) return "bun";
+  if (scope.process?.versions?.node) return "node";
+  if (scope.window?.document) return "browser";
+  return "unknown";
+}
+
+export function runtimefeatures(scope = globalThis) {
+  return { runtime: runtimename(scope), fetch: typeof scope.fetch === "function", streams: typeof scope.ReadableStream === "function" && typeof scope.WritableStream === "function", crypto: Boolean(scope.crypto), websocket: typeof scope.WebSocket === "function", filesystem: Boolean(scope.process?.versions?.node || scope.Deno) };
+}

package/runtime/engine.js

@@ -0,0 +1,56 @@
+/**
+ * the engine coordinates job intent, working memory, runner execution, and commit.
+ */
+import { aserror } from "../core/errors.js";
+import { eventbus } from "../core/events.js";
+import { idfactory, systemclock } from "../core/ids.js";
+import { createjob } from "../domain/jobs.js";
+
+export function engine(options) {
+  if (!options?.storage || !options?.memory || !options?.scheduler) throw new TypeError("engine requires storage memory and scheduler");
+  const events = options.events ?? eventbus();
+  const ids = options.ids ?? idfactory();
+  const clock = options.clock ?? systemclock();
+  async function emit(job, type, data) { events.emit({ id: ids.next("event"), type, jobid: job.id, at: clock.now(), data }); }
+  return {
+    events,
+    async run(spec, handler) {
+      const job = createjob(spec, ids, clock);
+      await emit(job, "jobqueued", { name: job.name });
+      let set;
+      let provider;
+      try {
+        job.status = "preparing";
+        await emit(job, "jobpreparing", { status: job.status });
+        provider = await options.scheduler.select(job);
+        await emit(job, "runnerselected", { runnerid: provider.descriptor().id });
+        set = await options.memory.prepare(job);
+        job.status = "running";
+        await emit(job, "jobrunning", { status: job.status, location: set.location });
+        const output = await provider.execute({ job, workingset: set, signal: new AbortController().signal }, handler);
+        const encoded = encodeoutput(output);
+        job.status = "syncing";
+        await emit(job, "jobsyncing", { status: job.status, bytes: encoded.bytes.byteLength });
+        const sync = await options.memory.sync(set, encoded.bytes);
+        const artifact = await options.storage.put({ key: spec.outputkey ?? `results/${job.id}${encoded.extension}`, data: encoded.bytes, contenttype: encoded.contenttype, metadata: { jobid: job.id, runnerid: provider.descriptor().id } });
+        await emit(job, "storagecommitted", { key: artifact.key, sha256: artifact.sha256 });
+        job.status = "completed";
+        await emit(job, "jobcompleted", { status: job.status, artifactkey: artifact.key });
+        return { job, output, runnerid: provider.descriptor().id, artifact, sync };
+      } catch (error) {
+        job.status = "failed";
+        const failure = aserror(error, job.id);
+        await emit(job, "jobfailed", { code: failure.code, retryable: failure.retryable, message: failure.message });
+        throw failure;
+      } finally {
+        if (set) await options.memory.cleanup(set);
+      }
+    }
+  };
+}
+
+function encodeoutput(output) {
+  if (output instanceof Uint8Array) return { bytes: output, contenttype: "application/octet-stream", extension: ".bin" };
+  if (typeof output === "string") return { bytes: new TextEncoder().encode(output), contenttype: "text/plain;charset=utf-8", extension: ".txt" };
+  return { bytes: new TextEncoder().encode(JSON.stringify(output)), contenttype: "application/json", extension: ".json" };
+}

package/runtime/worker.js

@@ -0,0 +1,18 @@
+/**
+ * worker bridge translates message events through an injected dispatcher without owning a worker runtime.
+ */
+
+/** Attaches a bounded message bridge to a caller-owned worker scope. */
+export function workerbridge(options = {}) {
+  const scope = options.scope ?? globalThis;
+  const dispatch = options.dispatch;
+  if (typeof scope.addEventListener !== "function") throw new TypeError("worker scope requires addEventListener");
+  if (typeof dispatch !== "function") throw new TypeError("worker bridge requires dispatch");
+  const event = String(options.event ?? "message");
+  async function listener(message) {
+    const input = message?.data ?? message;
+    try { scope.postMessage?.({ ok: true, requestid: input?.requestid, data: await dispatch(input) }); } catch (error) { scope.postMessage?.({ ok: false, requestid: input?.requestid, error: { code: String(error?.code ?? "WORKER_DISPATCH_FAILED"), message: String(error?.message ?? error) } }); }
+  }
+  scope.addEventListener(event, listener);
+  return { event, listener, close() { scope.removeEventListener?.(event, listener); } };
+}

package/scrape/cache.js

@@ -0,0 +1,14 @@
+/**
+ * ttl cache keeps fetch policy separate from extraction and transport.
+ */
+export function ttlcache(options = {}) {
+  const values = new Map();
+  const ttl = options.ttl ?? 300000;
+  return {
+    get(key) { const item = values.get(key); if (!item) return null; if (Date.now() > item.expires) { if (Date.now() > item.stale) values.delete(key); return options.stale ? item.value : null; } return item.value; },
+    set(key, value, valueoptions = {}) { const current = Date.now(); values.set(key, { value, expires: current + (valueoptions.ttl ?? ttl), stale: current + (valueoptions.stale ?? ttl * 2) }); return value; },
+    delete(key) { values.delete(key); },
+    clear() { values.clear(); },
+    size() { return values.size; }
+  };
+}

package/scrape/extract.js

@@ -0,0 +1,14 @@
+/**
+ * structured first extraction uses small built in heuristics and returns serializable data.
+ */
+export function extracthtml(html, url) {
+  const title = match(html, /<title[^>]*>([\s\S]*?)<\/title>/i);
+  const description = match(html, /<meta[^>]+name=["']description["'][^>]+content=["']([^"']*)["']/i) ?? match(html, /<meta[^>]+content=["']([^"']*)["'][^>]+name=["']description["']/i);
+  const links = [...html.matchAll(/<a[^>]+href=["']([^"']+)["'][^>]*>/gi)].map((item) => resolveurl(item[1], url)).filter(Boolean);
+  const text = html.replace(/<script[\s\S]*?<\/script>/gi, " ").replace(/<style[\s\S]*?<\/style>/gi, " ").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+  return { url, title: decode(title ?? ""), description: decode(description ?? ""), text, links: [...new Set(links)] };
+}
+
+function match(value, expression) { return value.match(expression)?.[1]?.trim(); }
+function decode(value) { return value.replaceAll("&amp;", "&").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", '"'); }
+function resolveurl(value, base) { try { return base ? new URL(value, base).href : new URL(value).href; } catch { return null; } }

package/scrape/robots.js

@@ -0,0 +1,32 @@
+/**
+ * robots rules are parsed locally and enforced before a fetch is attempted.
+ */
+export function robotsrules(text = "") {
+  const groups = [];
+  let current = null;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.split("#", 1)[0].trim();
+    if (!line) continue;
+    const separator = line.indexOf(":");
+    if (separator < 0) continue;
+    const key = line.slice(0, separator).trim().toLowerCase();
+    const value = line.slice(separator + 1).trim();
+    if (key === "user-agent") { current = { agents: [value.toLowerCase()], disallow: [], allow: [], delay: undefined, sitemaps: [] }; groups.push(current); }
+    else if (current && key === "disallow" && value) current.disallow.push(value);
+    else if (current && key === "allow" && value) current.allow.push(value);
+    else if (current && key === "crawl-delay" && Number.isFinite(Number(value))) current.delay = Number(value);
+    else if (key === "sitemap") (current ?? { sitemaps: [] }).sitemaps.push(value);
+  }
+  return { groups };
+}
+
+export function robotsallowed(rules, target, agent = "*") {
+  const pathname = new URL(target).pathname || "/";
+  const candidates = rules.groups.filter((group) => group.agents.includes(agent.toLowerCase()) || group.agents.includes("*"));
+  if (!candidates.length) return true;
+  const disallowed = candidates.flatMap((group) => group.disallow).filter((path) => pathname.startsWith(path));
+  const allowed = candidates.flatMap((group) => group.allow).filter((path) => pathname.startsWith(path));
+  return allowed.some((path) => path.length >= Math.max(...disallowed.map((item) => item.length), 0)) || disallowed.length === 0;
+}
+
+export function robotsdelay(rules, agent = "*") { return rules.groups.find((group) => group.agents.includes(agent.toLowerCase()) || group.agents.includes("*"))?.delay ?? 0; }

package/scrape/schema.js

@@ -0,0 +1,21 @@
+/**
+ * schema extraction accepts safe field descriptors and never evaluates source strings.
+ */
+export function extractwithschema(html, schema = {}, url) {
+  const result = {};
+  for (const [name, descriptor] of Object.entries(schema)) result[name] = extractfield(html, descriptor, url);
+  return result;
+}
+
+function extractfield(html, descriptor, url) {
+  if (typeof descriptor === "function") return descriptor({ html, url });
+  if (typeof descriptor === "string") return textfromselector(html, descriptor);
+  if (!descriptor || typeof descriptor.selector !== "string") throw new TypeError("schema field requires selector or function");
+  if (descriptor.selector === "title") return html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.trim() ?? null;
+  const escaped = descriptor.selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const attribute = descriptor.attribute;
+  const pattern = attribute ? new RegExp(`<[^>]+${escaped}[^>]*${attribute}=["']([^"']+)["'][^>]*>`, "i") : new RegExp(`<${escaped}[^>]*>([\\s\\S]*?)<\\/${escaped}>`, "i");
+  return pattern.exec(html)?.[1]?.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim() ?? null;
+}
+
+function textfromselector(html, selector) { return extractfield(html, { selector }); }

package/scrape/scraper.js

@@ -0,0 +1,40 @@
+/**
+ * scraper composes robots policy cache transport and extraction without browser assumptions.
+ */
+import { transport } from "../adapters/transport.js";
+import { extracthtml } from "./extract.js";
+import { robotsallowed, robotsdelay, robotsrules } from "./robots.js";
+import { ttlcache } from "./cache.js";
+
+export function scraper(options = {}) {
+  const client = options.transport ?? transport({ fetcher: options.fetcher, timeout: options.timeout, attempts: options.attempts });
+  const cache = options.cache ?? ttlcache(options.cacheoptions);
+  const agent = options.agent ?? "*";
+  const policies = new Map();
+  return {
+    async robots(origin) {
+      if (policies.has(origin)) return policies.get(origin);
+      const url = new URL("/robots.txt", origin).href;
+      const response = await client.request(url);
+      const rules = robotsrules(response.ok ? await response.text() : "");
+      policies.set(origin, rules);
+      return rules;
+    },
+    async scrape(url) {
+      const target = new URL(url);
+      if (!["http:", "https:"].includes(target.protocol)) throw new TypeError("scraper accepts http and https only");
+      const rules = await this.robots(target.origin);
+      if (!robotsallowed(rules, target.href, agent)) throw new Error("robots policy disallows target");
+      const cached = cache.get(target.href);
+      if (cached) return cached;
+      const wait = robotsdelay(rules, agent);
+      if (wait) await new Promise((resolve) => setTimeout(resolve, wait * 1000));
+      const response = await client.request(target.href, { headers: options.headers });
+      if (!response.ok) throw new Error(`scrape request failed with ${response.status}`);
+      const result = extracthtml(await response.text(), target.href);
+      cache.set(target.href, result, { ttl: options.ttl });
+      return result;
+    },
+    cache
+  };
+}

package/scrape/semantic.js

@@ -0,0 +1,22 @@
+/**
+ * semantic extraction exposes bounded headings, landmarks, controls and links without evaluating page code.
+ */
+
+/** Extracts semantic page facts from HTML using safe built-in parsing heuristics. */
+export function extractsemantic(html, url) {
+  const source = String(html ?? "");
+  const headings = [...source.matchAll(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi)].slice(0, 100).map((match) => ({ level: Number(match[1]), text: clean(match[2]) })).filter((item) => item.text);
+  const landmarks = [...source.matchAll(/<(main|nav|header|footer|aside|section|article)\b([^>]*)>/gi)].slice(0, 100).map((match) => ({ role: match[1].toLowerCase(), label: attribute(match[2], "aria-label") ?? attribute(match[2], "id") ?? "" }));
+  const controls = [...source.matchAll(/<(button|input|textarea|select|a)\b([^>]*)>([\s\S]*?)<\/\1>|<(input)\b([^>]*)\/?\s*>/gi)].slice(0, 200).map((match, index) => {
+    const tag = (match[1] ?? match[4]).toLowerCase();
+    const attrs = match[2] ?? match[5] ?? "";
+    return { ref: `e${index + 1}`, role: attribute(attrs, "role") ?? tag, name: attribute(attrs, "aria-label") ?? attribute(attrs, "placeholder") ?? clean(match[3] ?? ""), type: attribute(attrs, "type") };
+  });
+  const links = [...source.matchAll(/<a\b([^>]*)href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi)].slice(0, 500).map((match) => ({ url: resolve(match[2], url), text: clean(match[3]), rel: attribute(match[1], "rel") })).filter((link) => link.url);
+  return { url, title: clean(source.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] ?? ""), headings, landmarks, controls, links: dedupe(links, (item) => item.url), semantictext: clean(source.replace(/<script[\s\S]*?<\/script>/gi, " ").replace(/<style[\s\S]*?<\/style>/gi, " ").replace(/<[^>]+>/g, " ")).slice(0, 100000) };
+}
+
+function clean(value) { return String(value ?? "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").replaceAll("&amp;", "&").replaceAll("&lt;", "<").replaceAll("&gt;", ">").trim(); }
+function attribute(value, name) { return value.match(new RegExp(`${name}=["']([^"']*)["']`, "i"))?.[1] ?? null; }
+function resolve(value, base) { try { return new URL(value, base).href; } catch { return null; } }
+function dedupe(values, key) { const seen = new Set(); return values.filter((value) => { const item = key(value); if (seen.has(item)) return false; seen.add(item); return true; }); }

package/server/node.js

@@ -0,0 +1,34 @@
+/**
+ * node server is an optional adapter around the universal service contract.
+ */
+import { createServer } from "node:http";
+
+/** Creates a Node HTTP adapter with explicit host, port, and request handler. */
+export function nodeserver(options = {}) {
+  if (!options.host || !Number.isInteger(options.port) || options.port < 1) throw new TypeError("node server requires host and port");
+  if (typeof options.handle !== "function") throw new TypeError("node server requires handle");
+  /* Request translation stays inside the Node adapter. */
+  const server = createServer(async (request, response) => {
+    try {
+      const chunks = [];
+      for await (const chunk of request) chunks.push(chunk);
+      const body = Buffer.concat(chunks).toString("utf8");
+      const headers = new Headers(request.headers);
+      const webrequest = new Request(new URL(request.url ?? "/", `http://${options.host}:${options.port}`), { method: request.method, headers, body: body || undefined });
+      const result = await options.handle(webrequest);
+      response.statusCode = result.status;
+      result.headers.forEach((value, key) => response.setHeader(key, value));
+      response.end(Buffer.from(await result.arrayBuffer()));
+    } catch (error) {
+      response.statusCode = 500;
+      response.setHeader("content-type", "application/json");
+      response.end(JSON.stringify({ error: error.message }));
+    }
+  });
+  /* Lifecycle methods keep the server optional for library consumers. */
+  return {
+    server,
+    listen() { return new Promise((resolve, reject) => { server.once("error", reject); server.listen(options.port, options.host, () => resolve({ host: options.host, port: options.port })); }); },
+    close() { return new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve())); }
+  };
+}

package/sessions/file.js

@@ -0,0 +1,13 @@
+/**
+ * file session persistence writes one validated JSON document per session.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { validatesession } from "../domain/sessions.js";
+
+export function filesessions(root) {
+  return {
+    async save(session) { const valid = validatesession(session); const path = join(root, `${valid.id}.json`); await mkdir(dirname(path), { recursive: true }); await writeFile(path, JSON.stringify(valid, null, 2)); return valid; },
+    async load(id) { const value = JSON.parse(await readFile(join(root, `${id}.json`), "utf8")); return validatesession(value); }
+  };
+}

package/sessions/replay.js

@@ -0,0 +1,21 @@
+/**
+ * replay maps validated session events to an injected browser adapter.
+ */
+export async function replay(session, adapter, options = {}) {
+  if (!session?.events || typeof adapter?.move !== "function") throw new TypeError("replay requires session events and browser adapter");
+  const speed = options.speed ?? 1;
+  let previous = 0;
+  for (const event of session.events) {
+    const wait = Math.max(0, (event.t - previous) / speed);
+    if (wait) await delay(wait);
+    previous = event.t;
+    if (event.type === "move") await adapter.move(event);
+    else if (event.type === "click") await adapter.click(event);
+    else if (event.type === "drag") await adapter.drag(event);
+    else if (event.type === "scroll") await adapter.scroll(event);
+    else if (event.type === "key") await adapter.key(event);
+  }
+  return { events: session.events.length, duration: previous / speed };
+}
+
+function delay(milliseconds) { return new Promise((resolve) => setTimeout(resolve, milliseconds)); }

package/sessions/store.js

@@ -0,0 +1,13 @@
+/**
+ * jsonl session storage keeps append only traces independent from browser adapters.
+ */
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { validatesession } from "../domain/sessions.js";
+
+export function sessionstore(root) {
+  return {
+    async append(session) { const valid = validatesession(session); await mkdir(root, { recursive: true }); await appendFile(join(root, `${valid.id}.jsonl`), `${JSON.stringify(valid)}\n`); return valid; },
+    async read(id) { const text = await readFile(join(root, `${id}.jsonl`), "utf8"); return text.trim().split("\n").filter(Boolean).map((line) => validatesession(JSON.parse(line))); }
+  };
+}