@wenathlan/saddle 1.8.4 → 1.8.6

package/README.md

@@ -8,7 +8,7 @@
   <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/wenathlan/saddle/actions/workflows/ci.yml"><img src="https://github.com/wenathlan/saddle/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
-  <a href="https://github.com/wenathlan/saddle/releases/tag/v1.8.4"><img src="https://img.shields.io/badge/release-v1.8.4-d35d3d" alt="Release 1.8.4" /></a>
+  <a href="https://github.com/wenathlan/saddle/releases/tag/v1.8.6"><img src="https://img.shields.io/badge/release-v1.8.6-d35d3d" alt="Release 1.8.6" /></a>
   <a href="https://github.com/wenathlan/saddle/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-202a2f" alt="GPL 3.0 license" /></a>
 </p>
 
@@ -20,7 +20,7 @@ Ships as a library, CLI, binary, n8n node, CRX extension, Android/iOS and Tauri
 
 ## Start here
 
-Saddle requires **Node.js 22 or newer**.
+Saddle requires **Node.js 26.7.0 or newer**.
 
 ```bash
 npm install @wenathlan/saddle
@@ -109,7 +109,7 @@ The caller still chooses how to provide `fetcher`, browser transport, persistenc
 
 ## Browser extension
 
-Version 1.8.4 includes a pure JavaScript Manifest V3 reference surface in [`extension/`](extension/). It is deliberately narrow: the user invokes the action, the popup sends a versioned command, the service worker routes it, and an isolated content bridge returns bounded page metadata, visible text or a user initiated action result. The exported `permissionpolicy` keeps base permissions minimal and makes optional escalation caller-owned.
+Version 1.8.6 includes a pure JavaScript Manifest V3 reference surface in [`extension/`](extension/), a read-only page-world `pagefacts` boundary, snapshot diffs and persisted browser context metadata. It is deliberately narrow: the user invokes the action, the popup sends a versioned command, the service worker routes it, and an isolated content bridge returns bounded page metadata, visible text or a user initiated action result. The exported `permissionpolicy` keeps base permissions minimal and makes optional escalation caller-owned.
 
 ```bash
 # load the unpacked extension from chrome://extensions
@@ -145,12 +145,12 @@ saddle mcp
 
 | Registry | Artifact | Workflow | Status |
 | --- | --- | --- | --- |
-| GitHub npm | `@wenathlan/saddle@1.8.4` | publishgithubnpm.yml | pending release |
-| GHCR | `ghcr.io/wenathlan/saddle:1.8.4` and `latest` | publishghcr.yml | pending release |
-| Maven | `io.wenathlan:saddle:1.8.4` | publishmaven.yml | pending release |
-| NuGet | `Saddle.1.8.4.nupkg` | publishnuget.yml | pending release |
-| RubyGems | `saddle 1.8.4` | publishrubygems.yml | pending release |
-| npmjs | `@wenathlan/saddle@1.8.4` | publishnpmjs.yml | pending release |
+| GitHub npm | `@wenathlan/saddle@1.8.6` | publishgithubnpm.yml | pending release |
+| GHCR | `ghcr.io/wenathlan/saddle:1.8.6` and `latest` | publishghcr.yml | pending release |
+| Maven | `io.wenathlan:saddle:1.8.6` | publishmaven.yml | pending release |
+| NuGet | `Saddle.1.8.6.nupkg` | publishnuget.yml | pending release |
+| RubyGems | `saddle 1.8.6` | publishrubygems.yml | pending release |
+| npmjs | `@wenathlan/saddle@1.8.6` | publishnpmjs.yml | pending release |
 
 ## Development
 
@@ -188,7 +188,7 @@ Root-based JavaScript ESM layout, no src/ directory, no TypeScript build require
 
 ## Current scope
 
-Version 1.8.4 establishes the engine contracts, browser snapshot foundation, storage sync primitives, runner recovery contracts, scraping context provenance and normalization, API/MCP security contracts, bot integration lifecycle, the tested extension bridge and permission policy, deterministic extension packaging, context-aware replay, Node.js 26.7.0 cross-forge gates, desktop/mobile/n8n surface contracts, a framework-neutral operator control boundary and the first cross-runtime import boundary. Native runtimes, n8n host registration, provider credentials, persistent databases and production deployment remain caller-selected adapters. The next improvements should extend these contracts without coupling the core to one forge, registry, browser or storage vendor.
+Version 1.8.6 extends the 1.8.5 engine contracts with isolated page facts, extension snapshot diffs, persisted browser context metadata, deterministic release assets and root-based Pages deployment. Native runtimes, browser binaries, n8n host registration, provider credentials, persistent databases and production deployment remain caller-selected adapters. The next improvements should extend these contracts without coupling the core to one forge, registry, browser or storage vendor.
 
 ## License
 

package/browser/playwright.js

@@ -0,0 +1,22 @@
+/**
+ * browser playwright adapter keeps the optional Node browser provider outside the transport-neutral surface.
+ */
+
+/** Creates a caller-owned Playwright browser session when the optional peer is installed. */
+export async function createplaywrightsession(options = {}) {
+  let playwright;
+  try {
+    playwright = await import("playwright");
+  } catch (error) {
+    const missing = new Error("optional peer dependency 'playwright' is required for the Playwright adapter", { cause: error });
+    missing.code = "OPTIONAL_DEPENDENCY_MISSING";
+    throw missing;
+  }
+  const browsername = options.browser ?? "chromium";
+  const browsertype = playwright[browsername];
+  if (!browsertype || typeof browsertype.launch !== "function") throw new TypeError(`unsupported Playwright browser: ${browsername}`);
+  const browser = await browsertype.launch({ headless: options.headless ?? true, ...(options.launch ?? {}) });
+  const context = await browser.newContext(options.context ?? {});
+  const page = await context.newPage();
+  return { browser, context, page, close: () => browser.close() };
+}

package/docs/actionsincident.md

@@ -0,0 +1,29 @@
+# Actions and Pages incident
+
+This note records the GitHub-hosted failures observed while debugging the root web migration on 2026-08-13. The repository is public, the default branch is `main`, and the GitHub API reported `has_pages: false` before Pages configuration.
+
+## observed failures
+
+| Surface | Run | Evidence |
+| --- | --- | --- |
+| GitHub Pages | [31703685525](https://github.com/wenathlan/saddle/actions/runs/31703685525) | `actions/configure-pages@v5` returned `HttpError: Not Found`; the repository Pages site was not enabled/configured. |
+| CI | [31703407943](https://github.com/wenathlan/saddle/actions/runs/31703407943) | The historical workflow invoked `npm run build`, which is not a root package script. |
+| Uka tests | [31702858313](https://github.com/wenathlan/saddle/actions/runs/31702858313) | The historical workflow invoked `npm run typecheck`, which is not a root package script. |
+| CI | [31702858281](https://github.com/wenathlan/saddle/actions/runs/31702858281) | The historical workflow invoked both `npm run typecheck` and `npm run build`, which are not the engine gates. |
+| Dependabot | [31701834922](https://github.com/wenathlan/saddle/actions/runs/31701834922) | Dependabot attempted `/web/package.json`, which was intentionally removed during the root migration. |
+
+## correction contract
+
+The canonical npm manifest and lockfile are at the repository root. Engine workflows must use `npm ci`, `npm run check`, `npm run formatcheck`, `npm test` and `npm run pack:check`. The web Pages workflow must use `npm run web:check`, `npm run web:build:pages` and publish `web/dist/public`. Dependabot must use the `npm` ecosystem at `/`.
+
+The Pages workflow also requires the repository owner to enable GitHub Pages and select **GitHub Actions** as its source. The workflow cannot create the Pages site when the repository API still reports `has_pages: false`; that setting is managed at the repository level, not by the static artifact build.
+
+After selecting **GitHub Actions** in the repository settings, the Pages API reported `has_pages: true`, `build_type: workflow`, source `main` and the public URL `https://wenathlan.github.io/saddle/`. The corrected build/deploy workflow then completed successfully in [run 31705301175](https://github.com/wenathlan/saddle/actions/runs/31705301175), with `configure pages`, `web:check`, build, artifact upload and deploy all green.
+
+The final workflow commits also passed [Saddle engine CI run 31705367442](https://github.com/wenathlan/saddle/actions/runs/31705367442), [Uka-tests run 31705367433](https://github.com/wenathlan/saddle/actions/runs/31705367433) and [cross-runtime compatibility run 31705367432](https://github.com/wenathlan/saddle/actions/runs/31705367432). All three completed with `success` on `main`.
+
+The repository metadata audit found `main` as the default branch and one open Dependabot pull request (`#4`, branch `dependabot/npm_and_yarn/npm_and_yarn-2772e86c4e`). Its only commit (`4cb2a45`) changes the root package lock plus an unrelated nested `scrape/package.json` and `scrape/package-lock.json`; it does not represent a second production branch and is not safe to merge into the root release. The branch should be closed as an obsolete automated update after owner confirmation.
+
+The repository homepage About editor was opened in the authenticated browser and saved with the canonical Saddle description. The repository API should now report that description instead of the placeholder `saddle`.
+
+The six non-main Dependabot tips were preserved as `archive-dependabot-*` tags, their PRs were closed, and their branch refs were removed. The cleanup leaves `main` as the only active branch without deleting the archived commit objects.

package/docs/branchaudit.md

@@ -0,0 +1,21 @@
+# Branch audit
+
+This record preserves the branch tips and comparison results collected before the branch cleanup. Deleting a branch reference does not delete the commit objects or the tags that retain them; the hashes below remain available for audit and recovery while repository retention permits.
+
+| Branch | Tip commit | Ahead of `main` | Behind `main` | Unique change | Action |
+| --- | --- | ---: | ---: | --- | --- |
+| `main` | `04acff11e7f3c0bc830fdaaf1fc7bad9bdf1fcfa` | 0 | 0 | Current release line | Keep |
+| `dependabot/npm_and_yarn/lucide-react-1.31.0` | `45498007cc539d2c3df3d801cfb23dfdf575d859` | 1 | 11 | `package.json`, `package-lock.json` | Close PR #9 and delete branch |
+| `dependabot/npm_and_yarn/multi-b251156d90` | `cff1abfbcfe6fffae1a5517082c76b9f3e6195ea` | 1 | 11 | `package.json`, `package-lock.json` | Close PR #7 and delete branch |
+| `dependabot/npm_and_yarn/npm_and_yarn-2772e86c4e` | `4cb2a45cc8dd1bc53b05b5ffe8eeb07c1c46bc1c` | 1 | 13 | Root package files plus obsolete `scrape/` package files | Close PR #4 and delete branch |
+| `dependabot/npm_and_yarn/react-resizable-panels-4.12.2` | `8dfa1d1999c6cf0b80d39f54c1194499c2943739` | 1 | 11 | `package.json`, `package-lock.json` | Close PR #5 and delete branch |
+| `dependabot/npm_and_yarn/streamdown-2.5.0` | `ac04d2d01c2caa3c0bb9a8b7e8b952fd0af4b2d6` | 1 | 11 | `package.json`, `package-lock.json` | Close PR #6 and delete branch |
+| `dependabot/npm_and_yarn/typescript-7.0.2` | `7d5d3f7b70d28ed2663a6d9b2d4f8a3280571525` | 1 | 11 | `package.json`, `package-lock.json` | Close PR #8 and delete branch |
+
+All six non-main branches are single-commit Dependabot updates based on an older main tip. None is a second production line, and none should be merged blindly after the root web migration. The current `main` line keeps the release work; the branch tips above remain referenced by this audit until the remote branch refs are removed.
+
+The cleanup was completed by creating the six `archive-dependabot-*` tags, closing PRs #4 through #9, and deleting the six non-main branch refs. The repository is now intentionally reduced to `main`; the archive tags preserve the exact tips listed above.
+
+## Checks interpretation
+
+The check count changed because the workflow set changed during the root migration. Duplicate and obsolete workflow definitions were removed, while the canonical engine CI, Uka-tests, cross-runtime compatibility and Pages workflows were retained. The final `main` workflow set passed the current checks; a lower count therefore reflects fewer active check definitions, not a loss of commits or a failed release line.

package/docs/ecosystemplan.md

@@ -26,13 +26,13 @@ The engine owns **contracts, validation, orchestration, recovery and auditabilit
 | --- | --- | --- | --- |
 | 1 | audit and governance | active | gap matrix, sources, claims reconciled |
 | 2 | browser agent foundation | complete | snapshots, refs, stale errors, tabs, frames, action results and context-aware replay provenance tests |
-| 3 | extension runtime | first slice complete | MV3 unpacked surface, protocol, worker, content bridge and tests |
+| 3 | extension runtime | first slice complete | MV3 unpacked surface, protocol, worker, isolated content bridge, read-only page boundary and tests |
 | 4 | working set and storage | complete | range chunks, content dedupe, tiered cache, conflict sync and memory capabilities |
 | 5 | runners and execution | complete | provider health, triggers, cancellation, heartbeat and resumable runs |
 | 6 | scraping and context | complete | semantic extraction, content-type normalization, crawl budgets, RAG lineage and low-cardinality metrics |
 | 7 | API, MCP and security | complete | request identity, optional auth, secure headers, browser MCP tools and redirect/DNS checks |
 | 8 | bots and integrations | complete | app lifecycle, command scopes, idempotency, delivery retries and dead letters |
-| 9 | packaging and distribution | extension zip and registry slice prepared for 1.8.2 | desktop, mobile, n8n and binary artifacts remain caller-owned |
+| 9 | packaging and distribution | extension zip, checksum, SBOM and provenance slice implemented | desktop, mobile, n8n and binary artifacts remain caller-owned |
 | 10 | product surfaces and operations | first slice complete | desktop, mobile, n8n and operator control contracts; observability, retention and threat model remain |
 | 11 | cross-runtime compatibility | transport-neutral graph audit complete | Node, Bun and Deno root probe, browser worker bridge, extension permission/build checks and package graph audit |
 | 12 | release gates | active | deterministic checks, docs, clean diffs and claim/code parity |
@@ -52,7 +52,7 @@ Each block follows the same loop:
 
 ## current implementation
 
-Version 1.8.2 carries the public npm identity migration through the transferred `wenathlan` repository owner, aligns GitHub Packages npm, Maven and GHCR owner metadata, and includes the minimal extension permission policy, deterministic extension zip workflow, context-aware replay, transport-neutral graph audit and bounded content normalization. Registry publication is triggered only after the release tag and independent target checks. The first product surface slice adds desktop, mobile, n8n, operator control, operational policy and framework-neutral HTTP contracts. The first cross-runtime slice validates the root on Node, Bun and Deno, while extension-context and browser bundler checks remain caller-owned.
+Version 1.8.6 carries the public npm identity migration through the transferred `wenathlan` repository owner, aligns GitHub Packages npm, Maven and GHCR owner metadata, and includes the minimal extension permission policy, deterministic extension zip workflow, context-aware replay, transport-neutral graph audit, bounded content normalization, isolated page facts, snapshot context diffs, reproducible release assets and root-based Pages deployment. Registry publication is triggered only after the release tag and independent target checks. The first product surface slice adds desktop, mobile, n8n, operator control, operational policy and framework-neutral HTTP contracts. The first cross-runtime slice validates the root on Node, Bun and Deno, while extension-context and browser bundler checks remain caller-owned.
 
 ## evidence sources
 

package/docs/featureaudit.md

@@ -51,7 +51,7 @@ This audit compares the current repository with the project README and the addit
 | GitHub Packages and GHCR | missing | no package or image publishing jobs |
 | Maven, NuGet, RubyGems, PyPI | missing | no language specific wrappers or trusted publishing jobs |
 | jsDelivr, UNPKG, esm.sh | partial | URLs are documented; no release verification or SRI manifest |
-| browser extension | partial | surface manifest only; no CRX source or permissions manifest |
+| browser extension | partial | MV3 source, minimal permissions, isolated page boundary, snapshot diffs and unpacked zip build exist; CRX signing and cross-browser profiles remain caller-owned |
 | mobile and desktop apps | partial | target manifests only; no Tauri, Capacitor, Android, or iOS project |
 | site and per site database | missing | no `web` application, Hono server, Drizzle schema, Prisma schema, or site deployment adapter |
 | multi platform app identity | partial | generic bot and forge contracts; no OAuth or GitHub App installation flow |

package/docs/gapmatrix.md

@@ -15,15 +15,15 @@ This matrix turns the supplied README and conclusions into implementation decisi
 
 | Area | Current state | Gap | Priority | Decision |
 | --- | --- | --- | --- | --- |
-| Root library | Implemented ESM entry point with broad exports | No extension subpath or extension files are shipped | P0 | Add a small `extension/` package surface and export only serializable contracts |
-| Browser agent | Implemented injected action adapter for navigate, click, type, screenshot, DOM, title, scroll and command batches | Vendor-neutral action results and bounded action batches are now public | P1 | Keep the adapter boundary; add vendor adapters without moving browser ownership into the core |
+| Root library | Implemented ESM entry point with broad exports and an extension subpath | Browser-specific packaging and cross-browser profiles remain adapter-owned | P2 | Keep serializable extension contracts separate from browser binaries |
+| Browser agent | Implemented injected action adapter for navigate, click, type, screenshot, DOM, title, scroll and command batches | Vendor-neutral action results and bounded action batches are public; optional Playwright provider is isolated behind `browser-playwright` | P1 | Keep the adapter boundary; browser binaries and credentials remain caller-owned |
 | Browser snapshots | Implemented public contract | Snapshot ids, bounded elements, stable refs, stale checks and diffs are covered by deterministic tests | P0 | Reuse the contract from MCP and extension transport |
 | Session replay | Implemented | Replay restores caller-owned window, tab and frame context before actions; context identifiers are validated and counted | P1 | Keep browser selection and restoration in injected adapters |
-| Extension runtime | Surface is only declared in `surfaces/manifest.js` and `surfaces/targets.js` | No Manifest V3 manifest, service worker, content bridge, popup or build artifact | P0 | Implement a pure JavaScript MV3 reference surface with minimal permissions |
-| Extension messaging | Not implemented | No versioned envelope, correlation id, timeout, sender metadata or error response contract | P0 | Add transport-neutral message contracts and Chrome runtime adapter |
+| Extension runtime | Manifest V3 manifest, service worker, content bridge, popup, snapshot diffs, context metadata and deterministic build artifact are implemented | Cross-browser manifests remain unbundled | P2 | Keep a pure JavaScript MV3 reference surface with minimal permissions |
+| Extension messaging | Versioned envelope, correlation id, timeout, sender metadata and error response contract are implemented | Long-lived ports remain caller-owned | P1 | Keep transport-neutral messages and explicit runtime adapters |
 | Service worker resilience | Implemented contract slice | Pending command envelopes, attempt metadata and snapshot summaries persist through injected storage; resume remains explicit and user-owned | P0 | Rehydrate metadata on startup and never replay a command without an explicit caller action |
 | Permissions | Contract slice | `permissionpolicy` keeps the base permissions minimal and optional escalation caller-owned | P0 | Start with `storage` and no broad host permissions; make host access caller-configured |
-| Content isolation | Not implemented | No isolated-world DOM bridge or page-to-extension boundary | P0 | Add a narrow content script that reports page facts through the message contract |
+| Content isolation | Implemented read-only page-to-extension boundary | The page world cannot invoke extension commands; richer page facts remain bounded | P1 | Keep `pagebridge.js` read-only, token-correlated and caller-controlled |
 | Task agent | Partial | Jobs, workflows and bot commands exist, but no browser task planner or tool registry | P1 | Reuse workflow, trigger and bot contracts; add browser task commands only after snapshots |
 | MCP | Implemented scrape, crawl, batch, extract and serialize tools with JSON-RPC handling | No browser snapshot or browser action MCP tools | P1 | Add browser tools as an optional adapter over the same snapshot/action contracts |
 | API security | Implemented URL protocol and private hostname/IP checks | Request envelopes, optional authorization, security headers, redirect bounds and injected DNS resolution checks are now available | P0 | Keep credentials caller-owned and reject private or rebinding targets before transport |
@@ -40,7 +40,7 @@ This matrix turns the supplied README and conclusions into implementation decisi
 | Auth profiles | Session file and replay contracts exist | No extension profile or consent model | P1 | Defer cookie/profile export; support explicit user-owned session references only |
 | CAPTCHA | Contract, guard and evidence exist | No automatic solver integration | deferred | Keep external/manual solver boundary; do not promise bypass in the extension |
 | Stealth | Fingerprint contract exists | No automatic stealth patching | deferred | Keep opt-in fingerprint metadata; no hidden anti-detection behavior |
-| Packaging | npm, GHCR, Maven, NuGet, RubyGems and extension zip workflows are live | Desktop, mobile, n8n and binary release artifacts remain caller-owned | P1 | Keep non-JavaScript artifacts in explicit adapters and release jobs |
+| Packaging | npm, GHCR, Maven, NuGet, RubyGems, extension zip, deterministic SHA256SUMS, CycloneDX SBOM and in-toto-shaped provenance assets are implemented | Desktop, mobile, n8n and binary release artifacts remain caller-owned | P1 | Keep non-JavaScript artifacts in explicit adapters and release jobs |
 | Mobile and desktop apps | Contract slice | Desktop/mobile manifests and caller-owned adapter contracts exist; no native project is bundled | P1 | Keep native projects caller-owned and add runtime conformance tests incrementally |
 | n8n surface | Contract slice | Node metadata, trigger matching and declared action execution exist; no n8n host package is bundled | P1 | Keep node registration and credentials caller-owned |
 | Cross-browser | Target profile declares browser and extension | Firefox, Edge or Safari manifests remain unbundled; transport-neutral export graph is statically audited for Node-only imports | P2 | Keep WebExtension-compatible contracts and add browser adapters incrementally |
@@ -59,6 +59,7 @@ The first code slice targeted the P0 rows only. It now contains:
 6. A Chrome MV3 service worker that rehydrates state and routes messages.
 7. A narrow content script that reports document metadata and visible text through the bridge.
 8. Deterministic tests for browser contracts without Chrome credentials or network access.
+9. A read-only page-world bridge with token-correlated responses and bounded `pagefacts` reads.
 
 The extension remains an adapter. The root library continues to work without a browser, without an extension and without external memory.
 
@@ -66,7 +67,7 @@ The extension remains an adapter. The root library continues to work without a b
 
 Version 1.1 implements the first slice in `extension/`: `protocol.js` provides versioned serializable messages and snapshot identity; `serviceworker.js` provides browser independent routing; `worker.js` binds that router to Manifest V3 APIs; `content.js` runs the isolated page bridge; and `popup.html` with `popup.js` provides user initiated snapshot and read actions. The package exports `@wenathlan/saddle/extension`, while the root library remains usable without Chrome.
 
-The slice is intentionally not a full autonomous browser agent. Snapshot diffing, tab and frame identity, resumable command records, optional host escalation, browser action results and multi-browser packaging remain P1 or P2 work.
+The slice is intentionally not a full autonomous browser agent. Snapshot diffing, tab and frame identity, resumable command records, optional host escalation, browser action results and multi-browser packaging remain P1 or P2 work. The page-world bridge is deliberately read-only and cannot evaluate arbitrary page-provided commands.
 
 ## references
 

package/docs/libraryapi.md

@@ -39,6 +39,7 @@ The public API is designed around injected transports. Consumers can use the sam
 | `commandguard` | enforce caller-defined bot command scopes |
 | `deliveryqueue` | retry webhook deliveries and retain dead letters |
 | `nodeserver` | expose a Web Request/Response handler through Node HTTP |
+| `@wenathlan/saddle/browser-playwright` | optional Node-only Playwright session adapter; the peer is caller-installed and the root remains vendor-neutral |
 
 ```js
 import { scrapeurl, formatforagent } from "@wenathlan/saddle";

package/docs/packageaudit185.md

@@ -0,0 +1,23 @@
+# package metadata audit for 1.8.5
+
+The attached package manifest was used as a format reference, not as a dependency source. Its large application-oriented dependency graph, TypeScript build paths, workspace references and unrelated command names do not match the Saddle root-based JavaScript ESM library. Copying those entries would increase install cost, introduce unverified runtime coupling and weaken the transport-neutral package boundary.
+
+| Field | Decision | Reason |
+| --- | --- | --- |
+| `engines` | `node >=26.7.0`, `npm >=10.9.2` | matches the release toolchain and prevents silently testing on the older Node 22 floor |
+| `packageManager` | `npm@12.0.2` | records the current npm major used for the package contract without changing the existing release scripts |
+| `main`, `module`, `browser` | `./index.js` | gives older bundlers and browser-aware tooling a stable hint while `exports` remains authoritative |
+| `sideEffects` | `false` | the exported library modules are contract factories; CLI-only execution is guarded by direct-entry checks |
+| `peerDependencies.playwright` | `^1.62.1`, optional | the new explicit `browser-playwright` adapter dynamically loads a caller-installed provider |
+| `optionalDependencies` | not added | no optional package is required by a current implementation; an empty field would add no behavior |
+| `trustedDependencies` | not added | no install-time package script requires trust escalation; this is not an npm core field |
+| patch metadata | not added | no active dependency patch exists; pnpm 11 no longer reads settings from the `pnpm` field in `package.json` |
+
+The root entry remains free of Node-only imports and external runtime imports. The Playwright provider is only reachable through the explicit `./browser-playwright` subpath and is absent from the root transport-neutral graph. Consumers that do not need a browser provider do not need to install Playwright.
+
+## References
+
+1. [npm package.json documentation](https://docs.npmjs.com/cli/v12/configuring-npm/package-json/)
+2. [pnpm package.json documentation](https://pnpm.io/package_json)
+3. [Node.js package entry points and exports](https://nodejs.org/api/packages.html)
+4. [Playwright npm package](https://www.npmjs.com/package/playwright)

package/docs/plans/00.index.md

@@ -0,0 +1,50 @@
+# Index
+
+Project: **UKA** — computer use agent, sandbox for AI and captcha bypass. Super bot with computational memory. Package `@devthink/saddle`. Domain acquired.
+
+Theme: computer use, bypasses, captcha, sandbox for AI, container for AI, multi-platform bot, storage-to-compute memory transformation.
+
+## Planning Documents (`docs/plans`)
+
+| # | File | Subject |
+|---|------|---------|
+| 01 | [architecture.md](./01.architecture.md) | General system architecture |
+| 02 | [research.computer.use.md](./02.research.computer.use.md) | Research: computer use agents 2026 |
+| 03 | [research.captcha.bypass.md](./03.research.captcha.bypass.md) | Research: hcaptcha cloudflare recaptcha bypass |
+| 04 | [research.sandbox.ai.md](./04.research.sandbox.ai.md) | Research: virtual sandbox and containers for AI |
+| 05 | [capture.platform.md](./05.capture.platform.md) | Browser movement capture platform |
+| 06 | [dependencies.md](./06.dependencies.md) | 60+ project dependencies |
+| 07 | [captcha.test.page.md](./07.captcha.test.page.md) | Test page with hcaptcha cloudflare |
+| 08 | [production.infra.md](./08.production.infra.md) | Production infra (vercel/netlify) and sandbox backend |
+| 09 | [database.schema.md](./09.database.schema.md) | Database schema (drizzle/prisma/mysql2) |
+| 10 | [cloudinary.storage.md](./10.cloudinary.storage.md) | Data storage on cloudinary |
+| 11 | [movement.logs.json.md](./11.movement.logs.json.md) | JSON movement log format (brave) |
+| 12 | [research.atlas.agent.browser.md](./12.research.atlas.agent.browser.md) | Atlas: agent browser repos with same classification |
+| 28 | [action.plan.md](./28.action.plan.md) | Action plan and next steps |
+
+## Super Bot Documentation (`docs/plans`)
+
+| # | File | Subject |
+|---|------|---------|
+| 45 | [robotarchitecture.md](./45.robotarchitecture.md) | Super bot architecture overview |
+| 37 | [deploystrategy.md](./37.deploystrategy.md) | Deploy strategies (Netlify, Vercel, CI/CD, Docker, VM) |
+| 36 | [computational.memory.md](./36.computational.memory.md) | Storage-to-compute memory transformation system |
+| 39 | [multi.platform.bot.md](./39.multi.platform.bot.md) | Multi-platform bot (GitHub, GitLab, Forgejo, Gitea, Discord) |
+| 40 | [npm.publish.md](./40.npm.publish.md) | NPM package publishing (`@devthink/saddle`) |
+| 46 | [scdnintegration.md](./46.scdnintegration.md) | SCDN integration for assets and deployment |
+| 44 | [reference.md](./44.reference.md) | Reference index for all saddle documentation |
+| 33 | [bots.codigo.revisao.md](./33.bots.codigo.revisao.md) | Best AI code review bots (research) |
+| 32 | [bots.automacao.computacional.md](./32.bots.automacao.computacional.md) | Best computational automation bots (research) |
+| 34 | [bots.seguranca.cicd.md](./34.bots.seguranca.cicd.md) | Bot research (security + CI/CD) |
+
+## Folders
+
+- `docs/plans/` — planning and research (this index)
+- `docs/talks/` — decision transcripts
+- `docs/logs/` — JSON movement logs from Brave (`examplesession.json`)
+- `tests/` — unit tests (`examples/`, `output/`, `scripts/`)
+- `web/` — production site, deployed to Vercel or Netlify (files at root, no `src/`)
+
+## Phase Decision
+
+We are in **planning + research**. Platform implementation starts **only after user approval** (see `28.action.plan.md`).

package/docs/plans/01.architecture.md

@@ -0,0 +1,86 @@
+# 01 Architecture
+
+## Goal
+
+Build **UKA**, a computer use agent for ai that:
+
+1. Captures human movement in the browser (virtual mouse, virtual arrow, click, rotation, coordinates) in a real environment (brave / chromium).
+2. Exports movement as json logs to `docs/logs/`.
+3. Runs in a virtual sandbox to isolate ai agent execution.
+4. Faces strong captchas (hcaptcha, cloudflare turnstile, recaptcha) in controlled tests, opening test pages in brave.
+5. Persists data in production via a deployed site (vercel/netlify) plus db (drizzle/prisma/mysql2) plus cloudinary.
+
+## Architecture rules (skill arch)
+
+- No `src/` folder. Logic lives at the root of `web/`.
+- No vercel functions. No netlify functions. Use prisma, drizzle, mysql2, socket.
+- No localhost. Host is parametrized (`host`). Ports randomized then locked.
+- Files lowercase. No underscore. No hyphen. English docs. Jsdoc comments.
+- Logic grouped. Up to 20 related logics per file.
+- Runs as a library across modes (computer, browser, cli, binary, headless, etc).
+
+## Atlas (the browser)
+
+Atlas is the real browser component of UKA. It works across the 30 modes from the
+architecture skill (computer, browser, cli, binary, headless, etc) and its primary
+job is to bypass hcaptcha so the agent can act. It serves both the agent and the
+sandbox, and talks to our own database on vercel/netlify. See
+[12 research atlas agent browser](./12-research-atlas-agent-browser.md) for the
+prior-art survey and the p1 stealth / p2 vlm / p3 token fallback layering.
+
+## Components
+
+```
+atlas (web/atlas.js + deps)
+  - real browser across 30 modes
+  - stealth layer + hcaptcha bypass (vlm or token api fallback)
+  - feeds agent and sandbox
+
+capture ui (web/*.html + web/capture.js)
+  - virtual arrow / virtual mouse injected via cdp
+  - captures click, drag, scroll, coordinates, rotation
+  - exports json to docs/logs/
+
+sandbox (web/ + @vercel/sandbox)
+  - isolated firecracker microvm per session/agent
+  - chrome/brave ready, novnc streaming
+  - api https (post/get) to the deployed site
+
+production backend (web/, deployed to vercel/netlify)
+  - open node server (hono/express), not platform functions
+  - db (drizzle + mysql2 + prisma schema)
+  - cloudinary for assets and replays
+```
+
+## Main flows
+
+### A. Capture (local/dev)
+1. Open brave via playwright/chromium with `chrome.debugger` (cdp).
+2. Inject svg cursor sprite plus event listeners (`Input.dispatchMouseEvent`).
+3. Record each event with timestamp, type, coordinates, target, rng seed.
+4. Compact trajectories and export to `docs/logs/<session>.json`.
+
+### B. Captcha test
+1. Open test page (`tests/examples/hcaptchatest.html` or a real site).
+2. Run solver (hcaptcha challenger / vision) or record manual bypass.
+3. Save evidence (screenshot, token, log) to `tests/output/`.
+
+### C. Production
+1. Agent calls the deployed site api (`web/`).
+2. Backend writes session to db (drizzle/mysql2) and assets to cloudinary.
+3. Logs and replays available via get https.
+
+## Key technologies (details in `06-dependencies.md`)
+
+- Browser automation: `playwright`, `puppeteer`, `chromium-bidi`, `@playwright/test`
+- Human mouse: `bezier-js`, `@napi-rs/canvas`, `d3`
+- Ai / vision: `ai`, `@ai-sdk/*`, `@xenova/transformers`, `onnxruntime-web`, `tesseract.js`
+- Sandbox: `@vercel/sandbox`, `vercel`
+- Server: `hono`, `express`, `cors`, `helmet`, `socket.io` (socket realtime)
+- Db: `drizzle-orm`, `mysql2`, `@prisma/client`, `prisma`
+- Storage: `cloudinary`
+- Validation: `zod`, `valibot`, `arktype`
+
+## Next steps
+
+See `action-plan.md`. Implementation starts after user approval.

package/docs/plans/02.research.computer.use.md

@@ -0,0 +1,58 @@
+# 02 — Pesquisa: Computer Use Agents (2026)
+
+## Estado da arte
+
+Em 2026, *computer-use agents* deixaram de ser protótipos e entraram em produção para
+tarefas restritas e supervisionadas. Principais provedores e frameworks:
+
+- **Anthropic Computer Use** (`computer_use_20251124`): ferramentas `computer` (mouse/teclado),
+  `text_editor`, `bash`. Recomenda rodar em **VMs/containers com privilégios mínimos**.
+- **OpenAI Operator / CUA**: 87% de sucesso em sites JS complexos; 58% no WebArena.
+- **Google Project Mariner**: 83.5% WebVoyager, 84% ScreenSpot.
+- **Microsoft UFO²**: funde Windows UI Automation + OmniParser (visão).
+- **browser-use** (open source): 89.1% WebVoyager (abordagem híbrida DOM + visão).
+
+### Benchmarks
+- **OSWorld:** humano 72.36% vs SOTA ~12–20% (desktop ainda imaturo).
+- **WebArena:** tops ~71%, produção na faixa 50–60%.
+- **WebVoyager:** browser-use 89.1% (híbrido).
+
+### Conclusão de arquitetura
+Ganham abordagens **híbridas**:
+1. Raciocínio por **DOM / accessibility tree** para elementos estruturados.
+2. **Visão** (VLM) para layouts não-padrão, canvas, imagens.
+3. **Scripts determinísticos** para validação e replay.
+4. **Verificação** (screenshot antes/depois, diff de elementos).
+
+## Projetos de referência encontrados
+
+| Projeto | Diferencial relevante para UKA |
+|---------|-------------------------------|
+| [agentbrowser](https://github.com/AshtonVaughan/agentbrowser) | Cursor visível humano via CDP, trilha SVG, trajetórias Bézier com jitter/overshoot, **traces JSONL** em `~/.agentbrowser/traces/`, replay determinístico por seed, bypass de Cloudflare/OneTrust |
+| [humanjs](https://github.com/totigm/humanjs) | Playwright humanizado: curvas Bézier, ritmo de digitação, scroll, **personalidades** (careful/fast/distracted/precise), gravador → JSON timeline, MCP server |
+| [human-browser-use](https://github.com/andyless/human-browser-use) | Extensão p/ browser-use: trajetória Bézier, typing lognormal, scroll inercial, stealth fingerprint (`navigator.webdriver`, WebGL, canvas) |
+| [agentic-stealth-browser](https://github.com/shanewas/agentic-stealth-browser) | TLS spoofing (JA3/JA4), fingerprint, recovery chain (detecta captcha → rotaciona proxy), account warming |
+| [mantis](https://github.com/mercurialsolo/mantis) | Agent perception-reasoning-action em Xvfb+Chrome+xdotool (sem fingerprint Playwright), vídeo screencast, deploy em Baseten/Modal/EKS/GKE |
+| [win-pilot-mcp](https://github.com/omidmanoochehri/win-pilot-mcp) | MCP Windows computer-use: screen capture, OCR, mouse humano, logging estruturado, replay de macros |
+| [cloakbrowser-human](https://github.com/evelaa123/cloakbrowser-human) | Wrapper Playwright que adiciona camada **comportamental** (mouse Bézier, typing, scroll) — complementa stealth de fingerprint |
+
+## Padrões de movimento humano (extraídos da pesquisa)
+
+- **Trajetória do mouse:** curva Bézier única, velocidade variável por arc-length:
+  - 0–5%: ramp-up (0.3x → 2.5x)
+  - 5–75%: cruise (2.3–2.5x) com variação senoidal
+  - 75–100%: ease-out cúbico (2.5x → 0.3x)
+  - sub-pixel drift final (σ 0.3–1.5px)
+  - duração via **Lei de Fitts**: `0.05 + 0.07*log2(1 + distance/20)` s
+- **Overshoot:** ~15% de chance, auto-aumenta em movimentos longos.
+- **Typing:** inter-key delay lognormal (μ=4.17, σ=0.3 → ~65ms), bigram speedup, 2% typo.
+- **Scroll:** wheel events com acel/decel, overshoot, settle delay.
+- **Stealth:** `navigator.webdriver → undefined`, spoof de plugins/WebGL/canvas, flags de launch.
+
+## Aplicação no UKA
+
+- Implementar `HumanCursor` (SVG overlay + CDP `Input.dispatchMouseEvent`) inspirado no
+  agentbrowser/humanjs, com trajetórias Bézier + jitter + overshoot determinísticas por seed.
+- Gravar **todos os eventos** como `SessionEvent` tipado → exportar JSON para `docs/logs/`.
+- Usar replay determinístico (seed) para testes reprodutíveis.
+- Tratar GUI como imagem (visão) + DOM/accessibility para alvos estruturados.

package/docs/plans/03.research.captcha.bypass.md

@@ -0,0 +1,68 @@
+# 03 — Pesquisa: hCaptcha / Cloudflare / reCAPTCHA Bypass
+
+## Contexto
+
+O UKA precisa **testar** a capacidade do computer-use de enfrentar captchas fortes. A
+pesquisa abaixo levanta abordagens open-source e comerciais (uso edUKAcional / automação
+supervisionada).
+
+## hCaptcha
+
+### hcaptcha-challenger (QIN2DIM) — referência principal
+- Resolve hCaptcha com **LLM multimodal** (sem Tampermonkey, sem serviço anti-captcha 3º).
+- Modelos plugáveis (ONNX):
+  - `image_label_binary` → ResNet ✅
+  - `image_label_area_select: point` → YOLOv8 ✅
+  - `image_label_area_select: bounding box` → YOLOv8 segmentation
+  - `image_drag_drop` → Spatial Chain-of-Thought ✅
+  - `image_label_multiple_choice` → ViT zero-shot
+- Pipeline: `install()` → `AgentT.from_page()` → `handle_checkbox()` → `execute()` loop.
+- Deps: `playwright`, `httpx`, `opencv-python`, `pillow`, `loguru`, `pydantic-settings`.
+
+### Outros solvers
+- **hCaptcha-Solver (Camoufox + Multibot):** usa Camoufox p/ HSW token + Groq vision +
+  **geração de movimento de mouse realista** (Multibot API). Lida com `image_label_binary`,
+  `area_select`, `drag_drop`. Requer proxy.
+- **maximedrn/hcaptcha-solver-python-selenium:** userscript Tampermonkey + Selenium (edUKAcional).
+- **auto-captcha-solver / auto-captcha (NopeCHA):** detecta hCaptcha, reCAPTCHA v2/v3,
+  Cloudflare Turnstile via **API de token NopeCHA**; injeta token automaticamente. Tem MCP
+  server e CLI. Tipos: hCaptcha ✅, reCAPTCHA v2/v3 ✅, Turnstile ⚠️ (lento).
+
+## Cloudflare (Turnstile / interstitials)
+
+- **agentic-stealth-browser** passa Cloudflare interstitial usando TLS spoofing + fingerprint
+  + comportamento humano + **recovery chain** (detecta captcha → rotaciona proxy/sessão → retry).
+- **auto-captcha** resolve Turnstile via NopeCHA (fila lenta, requer proxy em produção).
+- **captcha-solver (CloakBrowser + 2Captcha/CapSolver):** Turnstile resolvido em ~5s via
+  ClickSolver (free) ou fallback pago.
+
+## reCAPTCHA
+
+- v2/v3/Enterprise: cobertos por hcaptcha-challenger (via proxy), auto-captcha (NopeCHA),
+  2Captcha, CapSolver.
+
+## Capes (tipos suportados por 2Captcha/CapSolver — 30+)
+
+reCAPTCHA v2/v3/Enterprise, Cloudflare Turnstile, hCaptcha, FunCaptcha (Arkose), GeeTest,
+KeyCaptcha, Amazon WAF, DataDome, Akamai, Imperva, Friendly, MTCaptcha, Lemin, Cutcaptcha,
+Tencent, Yandex, ALTCHA, Prosopo, entre outros.
+
+## Camadas de defesa que o UKA deve considerar
+
+| Camada | O que ataca | Mitigação no UKA |
+|--------|-------------|------------------|
+| Fingerprint (WebDriver, CDP, headless, GPU) | detecta automação | stealth JS + Brave real/CDP, spoof WebGL/canvas |
+| Comportamental (mouse/keyboard/scroll) | analisa padrões | trajetórias Bézier humanas, typing lognormal |
+| TLS (JA3/JA4) | identifica cliente | TLS regional / proxy residencial sticky |
+| IP reputation | bloqueia faixas | proxies residenciais com sessão sticky |
+| Captcha | desafio final | solver VLM (hcaptcha-challenger) ou token API |
+
+## Aplicação no UKA
+
+- Criar `tests/examples/hcaptcha-test.html` (página de teste local) + usar sites reais fortes
+  (Cloudflare, Google reCAPTCHA demo, hCaptcha demo) no Brave.
+- Pipeline de teste: abrir → detectar captcha → resolver (VLM ou token API) → registrar
+  token/screenshot/log em `tests/output/`.
+- **Não** usar para abuso: foco em automação supervisionada e pesquisa.
+- Dependências relevantes: `playwright`, `puppeteer`, `@xenova/transformers`,
+  `onnxruntime-web`, `tesseract.js`, `cloudinary` (evidências).

package/docs/plans/04.research.sandbox.ai.md

@@ -0,0 +1,52 @@
+# 04 — Pesquisa: Sandbox Virtual e Containers para IA
+
+## Por que sandbox?
+
+Computer-use agents executam código/inputs não confiáveis (saída de LLM, uploads de
+usuário). Rodar em sandbox isola a execução, impede acesso ao sistema de produção e limita
+recursos. A pesquisa mostra que provedores ladearam para **microVMs Firecracker**.
+
+## Vercel Sandbox (opção principal do UKA)
+
+- Compute primitive para rodar código não confiável com segurança (AI agents, code gen).
+- **Firecracker microVM** por sandbox, filesystem e rede próprios, isolamento forte.
+- Runtimes: `node26/24/22`, `python3.13`. Default `node24`.
+- Cada sandbox roda como `vercel-sandbox` (sudo disponível), working dir `/vercel/sandbox`.
+- Startup em **milissegundos**; suporta Docker/FUSE dentro do microVM (privilégio elevado).
+- **Credential brokering:** injeta secrets em requests de saída sem expor dentro do VM
+  (`console.log(process.env)` não vaza a chave).
+- **Network policy:** allowlist de domínios, atualizável em runtime.
+- SDK JS e Python; CLI. Multi-agent isolation (usuário Linux por agente, grupos p/ compartilhar).
+
+### AI SDK Computer Use (vercel-labs) — template de referência
+- Next.js + AI SDK + Claude Sonnet 4.5 + **Vercel Sandbox**.
+- Snapshot pré-construído com: **Xvnc**, **openbox**, **noVNC + websockify**, **Google
+  Chrome**, **xdotool + ImageMagick**.
+- Fluxo: User ↔ Chat UI ↔ AI SDK ↔ Claude → Vercel Sandbox (desktop via noVNC iframe).
+- Ferramentas: `computer` (screenshot/click/type/scroll) + `bash`.
+- Env: `ANTHROPIC_API_KEY`, `SANDBOX_SNAPSHOT_ID`, `VERCEL_OIDC_TOKEN`/`VERCEL_TOKEN`.
+
+### vercel-labs/agent-browser (serverless)
+- CLI Rust nativo; roda agent-browser + Chrome em Vercel Sandbox microVM efêmero.
+- Helper `@agent-browser/sandbox/vercel` + `@vercel/sandbox`.
+
+### vercel-labs/sandcastle (PoC desktop)
+- Desktop Linux web sobre Vercel Sandbox. Stack: Next.js, Tailwind, **Zustand + SWR**,
+  **Neon Postgres + Drizzle ORM**, `@vercel/sandbox`, code-server, Xpra. Auth password/OAuth.
+
+## Outras opções
+
+- **Modal / Baseten / EKS / GKE** (usados pelo mantis) — containers Docker customizados.
+- **Daytona / Cloudflare** — alternativas de sandbox (citadas mas com menos fit p/ TS).
+- **Containers Docker locais** (xdotool + Xvfb + Chromium) para dev sem nuvem.
+
+## Decisão para o UKA
+
+- **Produção:** Vercel Sandbox como camada de execução do computer-use; site de controle
+  deployado em **Vercel** (ou Netlify) (`web/`).
+- **Banco:** criado no deploy (Drizzle/LibSQL ou Prisma em Neon/Turso), conforme `09-esquema-banco-dados.md`.
+- **Armazenamento:** Cloudinary para assets/replays (`10-cloudinary-storage.md`).
+- **Dev local:** Brave real via Playwright/CDP para a plataforma de captura (`05-plataforma-captura-movimentos.md`).
+- **Comunicação:** requests **POST/GET HTTPS** do agente → site deployado → DB + Cloudinary.
+- Dependências: `@vercel/sandbox`, `vercel`, `@netlify/blobs`, `@netlify/functions`,
+  `hono`/`express`, `drizzle-orm`, `@libsql/client`, `socket.io`.