@wenathlan/saddle 2.1.7 → 2.1.8

package/docs/browser.md

@@ -1,7 +1,24 @@
 # Saddle browser surface
 
-The root `browser/` directory contains the transport-neutral browser-agent contracts: session state, context, snapshots, fingerprints, Playwright integration, recording and agent orchestration. It is library logic and is shared by callers; it is not a second copy of the desktop UI.
+The root `browser.ts` carries the transport-neutral browser-agent contracts of the engine: session state, context, snapshots, fingerprints, the virtual-browser request/decision/handoff/receipt family, the optional Playwright adapter, recording and agent orchestration (sections 1-9 of the grand merge). It is library logic and is shared by callers; it is not a second copy of the desktop UI.
 
 The user-facing browser application is the existing Tauri shell in `desktop/`, which wraps the compiled `web/dist/public` surface on Windows, Linux and macOS. Android and iOS convert the same web output through Capacitor. This boundary keeps browser behavior in the library and keeps presentation and native packaging in their target surfaces.
 
+## The Manifest V3 extension migrated to devthink (wave 2 regrouping)
+
+The Chrome Manifest V3 extension surface — the former sections 10-17 of `browser.ts` (`extension/permissions`, `extension/protocol`, `extension/content`, `extension/popup`, `extension/pagebridge`, `extension/worker`, `extension/serviceworker`, `extension/build`) — now lives in **`devthink/browserextension.ts`** with every export under the same name and signature. The family rule that drove the move: the saddle is exclusively the virtualization engine (VM / sandbox / microVM / the ninety modalities / vGPU / vCPU) and never touches the browser, GPU, CPU or storage of the user — every feature that runs in the user's browser is not a VM modality and belongs to devthink, the owner of the family extension product (which already packages its own extension through `packageextension.ts` and `crossbrowser.ts`).
+
+What moved with the surface:
+
+| former saddle root file | devthink root file |
+| --- | --- |
+| `browser.ts` sections 10-17 | `devthink/browserextension.ts` |
+| `manifest.json` (MV3 bridge manifest) | `devthink/extensionmanifest.json` |
+| `popup.html` | `devthink/extensionpopup.html` |
+| `popup.css` | `devthink/extensionpopup.css` |
+| `icon32.png` / `icon64.png` / `icon128.png` | `devthink/extensionicon32.png` / `extensionicon64.png` / `extensionicon128.png` |
+| `tests/extension.test.ts` | `devthink/tests/browserextension.test.ts` |
+
+The tracked assets carry the `extension` prefix at the devthink root because devthink already owns its own extension surface (`manifest.json` of record, `popup.ts`, `design.html`) — no root name collides. The build adapter (section 17 of the migrated module) is self-referential: it extracts the seven script sections from `devthink/browserextension.ts` itself, reads `extensionmanifest.json` for the versioned manifest and copies the extension-prefixed assets into an isolated unpacked artifact (default output `build/browserextension`, so it never touches the `build/extension` directory owned by the devthink extension build). The `@wenathlan/saddle/extension` package export and the `extension:build` script retired with the migration — consumers import the surface from the devthink app.
+
 Release filenames identify the user-facing desktop browser with the dotted lowercase pattern `saddle.browser.1.8.14.<format>`. Internal module filenames remain API-compatible unless a deliberate public compatibility migration is documented.

package/docs/extension.md

@@ -1,5 +1,16 @@
 # saddle browser bridge
 
+> **Migration note (wave 2 regrouping):** the extension surface moved to
+> `devthink/browserextension.ts` (sections 10-17 of the former
+> `saddle/browser.ts`), with its tracked assets at the devthink root
+> (`extensionmanifest.json`, `extensionpopup.html`, `extensionpopup.css`,
+> `extensionicon32.png`, `extensionicon64.png`, `extensionicon128.png`)
+> and its test battery at `devthink/tests/browserextension.test.ts`. The
+> saddle is exclusively the virtualization engine; everything that runs
+> in the user's browser belongs to devthink, the owner of the family
+> extension product. The notes below describe the bridge design and stay
+> accurate for the migrated surface.
+
 This directory contains the first Manifest V3 surface for Saddle. It is a user initiated bridge, not a hidden automation service.
 
 ## load unpacked
@@ -7,7 +18,7 @@ This directory contains the first Manifest V3 surface for Saddle. It is a user i
 1. Open `chrome://extensions`.
 2. Enable developer mode.
 3. Choose **Load unpacked**.
-4. Select this `extension/` directory.
+4. Select the built artifact directory (the unpacked output of the build adapter below).
 5. Open a page, invoke Saddle from the extension action and choose `Snapshot` or `Read page`.
 
 The manifest requests only `activeTab`, `scripting` and `storage`. It does not request broad host permissions, cookies, tabs, webRequest or debugger access. `activeTab` gives temporary access after the user invokes the action for the current tab.
@@ -20,7 +31,7 @@ The content bridge runs in Chrome's isolated world. It exposes bounded page meta
 
 ## deterministic release artifact
 
-The Node-only build adapter creates an isolated unpacked artifact with the release version in its manifest. A caller can run `npm run extension:build -- --version 1.8.14 --output build/extension` and package that directory with the archive tool available in the host environment. The release workflow derives the version from the published tag and attaches `saddle.extension.<version>.zip` without changing the source manifest.
+The Node-only build adapter creates an isolated unpacked artifact with the release version in its manifest. A caller can run `node --import tsx ./browserextension.ts --version 1.8.14 --output build/browserextension` from the devthink app root (the retired saddle `extension:build` script went with the migration) and package that directory with the archive tool available in the host environment. The release workflow derives the version from the published tag and attaches `saddle.extension.<version>.zip` without changing the source manifest.
 
 ## next slices
 

package/docs/libraryapi.md

@@ -60,7 +60,7 @@ The `fetcher`, browser adapter, persistence adapter, proxy pool, captcha solver,
 
 The package exposes explicit subpaths for `./browser`, `./bot`, `./captcha`, `./memory-engine`, `./deploy`, and `./release-evidence`. Desktop, mobile, target-plan and n8n contracts are exported from the root entry; the root entry remains the complete compiled JavaScript API with generated TypeScript declarations for consumers that prefer one import.
 
-The `./extension` subpath exposes browser-neutral message, snapshot and service-worker routing contracts. The concrete Manifest V3 files live in `extension/`; they are not imported by the core at runtime and do not require Chrome when the library is used as a Node package. The browser surface also exposes snapshots, tab/frame context, action results, bounded action batches and recording through `./browser`.
+The former `./extension` subpath retired with the wave 2 regrouping: the Chrome Manifest V3 surface (message, snapshot and service-worker routing contracts, the content and page bridges, the popup and the build adapter) runs in the user's browser, so it is not a VM modality of the engine and migrated to `devthink/browserextension.ts` with every export under the same name. The browser surface keeps exposing snapshots, tab/frame context, action results, bounded action batches and recording through `./browser`.
 
 The current release exposes `desktopmanifest`, `mobilemanifest`, `desktopadapter`, `mobileadapter`, `n8nnode`, `n8nmatch`, `n8nexecute`, `controlsurface`, `controlservice`, and `workerbridge`. These factories describe surface boundaries and invoke caller-owned handlers; they do not install a native toolkit, start an n8n server, create a dashboard, or store credentials.