@wenathlan/saddle 1.8.8 → 1.8.10

package/docs/artifactavailability.md

@@ -0,0 +1,40 @@
+# Saddle 1.8.9 artifact availability
+
+Saddle 1.8.9 is a TypeScript-first engine release with native packaging generated from the shared Tauri 2 desktop boundary. The workflows derive the release version from the release tag and attach only the files produced by the corresponding runner. Tauri documents `android build` and `ios build` as separate platform commands, while the desktop `build` command generates platform installers from the resolved frontend distribution [1].
+
+## Verified release assets
+
+The following artifacts are attached to the [v1.8.9 GitHub release][3]. The desktop assets are unsigned build artifacts; code signing, notarization and store submission remain caller-owned. The Android files are debug-signed test artifacts and are not production store releases.
+
+| Surface           | Generated asset                                                                                                                   | Release status | Distribution note                                                                     |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------- |
+| Windows           | [Saddle Browser 1.8.9 setup EXE](https://github.com/wenathlan/saddle/releases/download/v1.8.9/Saddle.Browser_1.8.9_x64-setup.exe) | Generated      | Unsigned installer; caller-owned signing and update policy.                           |
+| Windows           | [Saddle Browser 1.8.9 MSI](https://github.com/wenathlan/saddle/releases/download/v1.8.9/Saddle.Browser_1.8.9_x64_en-US.msi)       | Generated      | Unsigned installer; caller-owned signing and enterprise deployment.                   |
+| Linux             | [Debian package](https://github.com/wenathlan/saddle/releases/download/v1.8.9/Saddle.Browser_1.8.9_amd64.deb)                     | Generated      | Unsigned package; Snap and Flatpak are not part of this release.                      |
+| Linux             | [RPM package](https://github.com/wenathlan/saddle/releases/download/v1.8.9/Saddle.Browser-1.8.9-1.x86_64.rpm)                     | Generated      | Unsigned package; repository publication remains caller-owned.                        |
+| Linux             | [AppImage](https://github.com/wenathlan/saddle/releases/download/v1.8.9/Saddle.Browser_1.8.9_amd64.AppImage)                      | Generated      | Portable unsigned image.                                                              |
+| macOS             | [DMG](https://github.com/wenathlan/saddle/releases/download/v1.8.9/Saddle.Browser_1.8.9_aarch64.dmg)                              | Generated      | Unsigned and not notarized; PKG is deferred.                                          |
+| Android           | [Debug APK](https://github.com/wenathlan/saddle/releases/download/v1.8.9/app-universal-debug.apk)                                 | Generated      | Debug key for test installation; production signing is caller-owned.                  |
+| Android           | [Debug AAB](https://github.com/wenathlan/saddle/releases/download/v1.8.9/app-universal-debug.aab)                                 | Generated      | Debug key for test packaging; production signing is caller-owned.                     |
+| Container         | [Saddle container tarball](https://github.com/wenathlan/saddle/releases/download/v1.8.9/saddle-container-1.8.9.tar.gz)            | Generated      | OCI image exported as a tarball; deployment runtime and registry remain caller-owned. |
+| Browser extension | [Saddle extension ZIP](https://github.com/wenathlan/saddle/releases/download/v1.8.9/saddle-extension-1.8.9.zip)                   | Generated      | Deterministic extension package.                                                      |
+
+The platform manifests and checksums are also attached. They are named `artifact-manifest-linux.json`, `artifact-manifest-windows.json`, `artifact-manifest-macos.json`, `artifact-manifest-android.json`, `container-artifact-manifest.json`, `SHA256SUMS-linux`, `SHA256SUMS-windows`, `SHA256SUMS-macos`, `SHA256SUMS-android` and `SHA256SUMS-container`.
+
+## Unavailable or caller-owned targets
+
+The iOS workflow exists but is gated by `SADDLE_IOS_ENABLED` or an explicit manual dispatch input. No IPA is claimed for v1.8.9 because the release was not run with Apple Developer certificates, provisioning profiles and export credentials. The same ownership rule applies to PKG, MSIX, Snap, Flatpak, production Android signing, Windows signing, macOS signing and notarization. The package targets for npm, GitHub Packages, GHCR, Maven, NuGet and RubyGems remain separate registry workflows and are not duplicated as release binaries.
+
+Tauri configuration is resolved from `tauri.conf.json` and can be extended with platform-specific configuration files, which keeps the core application boundary reusable without embedding signing material or infrastructure endpoints [2].
+
+## References
+
+[1]: https://v2.tauri.app/reference/cli/ "Tauri Command Line Interface"
+[2]: https://v2.tauri.app/develop/configuration-files/ "Tauri Configuration Files"
+[3]: https://github.com/wenathlan/saddle/releases/tag/v1.8.9 "Saddle v1.8.9 GitHub Release"
+
+## 1.8.10 conversion contract
+
+Version 1.8.10 keeps the Tauri desktop browser and adds explicit Capacitor Android and iOS conversion targets. The shared source is the TypeScript library plus the compiled `web/dist/public` output; the native folders do not fork engine logic. The Android release build enables R8 and resource shrinking, and the workflow creates an ephemeral CI test key when caller production signing secrets are absent.
+
+The 1.8.10 workflow names the public outputs `saddle.browser.1.8.10.<format>`, `saddle.apk.1.8.10.apk`, `saddle.aab.1.8.10.aab`, `saddle.ipa.1.8.10.ipa`, `saddle.container.1.8.10.tar.gz` and `saddle.extension.1.8.10.zip`. Surface manifests and checksums use the corresponding `manifest.<surface>.1.8.10.json` and `sha256.<surface>.1.8.10` forms. The release is not considered complete until the live GitHub asset list matches these generated names.

package/docs/artifactresearch-1.8.9.md

@@ -0,0 +1,42 @@
+# Artifact research 1.8.9
+
+## Decision summary
+
+The missing release artifacts require a shared desktop browser shell plus platform-specific CI jobs. The source boundary should remain one TypeScript application and one compiled Saddle library; platform jobs should package that boundary rather than create independent application logic.
+
+| Surface | Recommended build boundary | Required runner or toolchain | Release status |
+| --- | --- | --- | --- |
+| Desktop browser shell | Tauri 2 or an equivalent caller-selected shell around the existing web build | Rust, platform WebView and platform packaging tools | Can generate platform bundles in CI; signing remains caller-owned |
+| Windows | Tauri Windows bundle or Electron Forge maker when an Electron shell is explicitly selected | Windows runner; EXE/MSI/MSIX maker and optional signing certificate | Unsigned installers can be generated by configured CI; store distribution requires signing |
+| Linux | Tauri Debian, RPM, AppImage, Snap or Flatpak bundle | Linux runner and format-specific tools | Debian and AppImage are practical first artifacts; Snap/Flatpak require their own validation and publishing channels |
+| macOS | Tauri app/DMG/PKG bundle | macOS runner with Xcode toolchain | App, DMG and PKG need signing; outside the App Store also needs notarization |
+| Android | Shared web application through Tauri Android or a native Gradle wrapper | Linux runner with Android SDK/Gradle | Debug APK can be produced without the owner's release key; release APK/AAB requires private signing material |
+| iOS | Shared web application through Tauri iOS or a native Xcode project | macOS runner with Xcode | IPA/archive requires Xcode, provisioning and signing inputs; no unsigned App Store artifact is a valid release product |
+
+## Primary findings
+
+Tauri 2 exposes `build`, `android build` and `ios build` commands and automatically bundles configured platform formats. Its distribution documentation lists Debian, Snap, AppImage, Flatpak and RPM for Linux, DMG and app bundles for macOS, Windows installers, and Android/iOS distribution surfaces. The same documentation states that most platforms require code signing, so an artifact workflow must distinguish generated unsigned output from store-ready signed output [1].
+
+Tauri's development documentation confirms that the web UI is displayed inside the platform WebView and that the mobile commands use Android Studio or Xcode when the caller needs an IDE. It also warns that mobile iOS physical-device development requires the `TAURI_DEV_HOST` address and an Xcode-connected device, which is why the repository should expose that value as workflow configuration rather than hardcoding a host [2].
+
+Electron Forge is a viable alternative when the project explicitly chooses Electron. Its makers are configured per platform and can produce formats such as DMG, AppX and Flatpak [3]. The Debian maker requires Linux or macOS plus `fakeroot` and `dpkg`, so Debian packaging belongs on a Linux CI job with those packages available [4]. The project should not add Electron merely to produce installers if a lighter Tauri shell satisfies the browser requirement.
+
+Android's official command-line guidance distinguishes debug and release output. `assembleDebug` creates a debug APK signed by the SDK's debug key for testing, while release APKs and bundles require the owner's private signing key. The same documentation describes Gradle `bundle<Variant>` tasks for AAB output and explains that an AAB is not directly installable on a device [5]. Consequently, the workflow may publish a debug APK as a clearly labeled test artifact, but must require a repository secret or environment-provided keystore before claiming a release APK or AAB.
+
+Apple's Xcode command-line guidance identifies `xcodebuild` as the tool for building, testing, archiving and exporting Xcode projects. iOS packaging therefore belongs on a macOS runner and must receive a scheme, archive path, export options, provisioning profile and certificate from the caller or repository secrets [6]. The workflow can prepare an archive contract when those inputs are absent, but it must not fabricate an IPA or signing identity.
+
+GitHub-hosted runners provide standard Linux, Windows and macOS labels. The runner reference documents `ubuntu-latest`, `windows-latest` and `macos-latest` families and notes Android SDK acceleration on Linux runners [7]. The release workflow should use those labels for platform jobs and derive every version from the release tag; it should not assume that a Linux sandbox can cross-build a signed Windows, Android or iOS artifact.
+
+## Implementation consequence
+
+The first implementation should add a shared desktop application manifest and a Tauri-oriented workflow contract, then add Windows and Linux jobs that can generate unsigned installers when their native tools are present. Android and iOS jobs should be caller-configured and should report `unavailable` rather than emitting a misleading artifact when SDKs, certificates or provisioning inputs are missing. Every generated file must be checksumed, uploaded to the existing GitHub release and listed in a machine-readable release asset manifest.
+
+## References
+
+[1]: https://v2.tauri.app/distribute/ "Tauri 2 distribution and signing guidance"
+[2]: https://v2.tauri.app/develop/ "Tauri 2 desktop and mobile development guidance"
+[3]: https://www.electronforge.io/config/makers "Electron Forge makers"
+[4]: https://www.electronforge.io/config/makers/deb "Electron Forge Debian maker requirements"
+[5]: https://developer.android.com/build/building-cmdline "Android command-line build, APK, AAB and signing guidance"
+[6]: https://developer.apple.com/library/archive/technotes/tn2339/_index.html "Apple Xcode command-line build and archive guidance"
+[7]: https://docs.github.com/en/actions/reference/runners/github-hosted-runners "GitHub-hosted runner platforms and capabilities"

package/docs/enginearchitecture.md

@@ -23,7 +23,7 @@ The project has no `src` folder. The root is the map of the engine.
 | `tests` | local deterministic tests without credentials |
 | `examples` | small runnable integration examples |
 
-All internal file names are lowercase and contain no underscore or hyphen. Related logic stays grouped and each module remains small enough to reason about in isolation. Version 1.8.8 groups crawl URL normalization, traversal, frontier budgets and persistence in `scrape/crawl.js`; it does not merge distinct storage cache, job queue or browser session contracts merely because they use similar words.
+All internal file names are lowercase and contain no underscore or hyphen. Related logic stays grouped and each module remains small enough to reason about in isolation. Version 1.8.9 uses TypeScript source at the root and groups crawl URL normalization, traversal, frontier budgets and persistence in `scrape/crawl.ts`; it does not merge distinct storage cache, job queue or browser session contracts merely because they use similar words.
 
 ## public contracts
 
@@ -65,7 +65,7 @@ The same contracts support paired modes. A mode can exist without its pair, and
 | browser | headless job definition | capture and replay adapter |
 | network | local deterministic job | remote provider and storage adapter |
 
-The first cut implements library, cli, binary entry point, internal memory, and internal file. The other modes are extension points, not hardcoded promises. Version 1.8.8 preserves this boundary while reducing duplicated active context files.
+The first cut implements library, CLI, binary entry point, internal memory, and internal file. The other modes are extension points and declarative target plans, not hardcoded platform promises. Version 1.8.9 preserves this boundary while compiling the active engine to ignored `dist/` output.
 
 ## infrastructure rules
 

package/docs/gapmatrix.md

@@ -19,11 +19,11 @@ This matrix turns the supplied README and conclusions into implementation decisi
 | 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 | 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 runtime | TypeScript-first Manifest V3 source, service worker, content bridge, popup, snapshot diffs, context metadata and deterministic JavaScript build artifact are implemented | Cross-browser manifests remain unbundled | P2 | Keep the compiled MV3 artifact minimal and keep cross-browser profiles caller-owned |
 | 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 | 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 |
+| Content isolation | Implemented read-only page-to-extension boundary | The page world cannot invoke extension commands; richer page facts remain bounded | P1 | Keep the compiled page bridge 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 |

package/docs/libraryapi.md

@@ -56,7 +56,7 @@ The `fetcher`, browser adapter, persistence adapter, proxy pool, captcha solver,
 
 ## package surfaces
 
-The package exposes explicit subpaths for `./browser`, `./bot`, `./captcha`, `./memory-engine`, and `./deploy`. Desktop, mobile, and n8n contracts are exported from the root entry; the root entry remains the complete JavaScript API for consumers that prefer one import.
+The package exposes explicit subpaths for `./browser`, `./bot`, `./captcha`, `./memory-engine`, and `./deploy`. 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`.
 

package/docs/mobileconversionresearch-1.8.10.md

@@ -0,0 +1,59 @@
+# Mobile conversion research for Saddle 1.8.10
+
+## Scope and date
+
+This research was reviewed on 13 August 2026 for the 1.8.10 planning cycle. The objective is to preserve one TypeScript-first library core, reuse the compiled web surface, create explicit Android and iOS boundaries, keep the Tauri desktop browser, reduce Android release size and make release filenames predictable.
+
+## Framework comparison
+
+| Approach | Strengths | Tradeoffs | Setup complexity | Decision |
+| --- | --- | --- | --- | --- |
+| Tauri 2 for desktop and mobile | Reuses any HTML, CSS and JavaScript frontend; uses the system webview; already builds Saddle desktop; Rust boundary remains available for native capabilities. Tauri documents a small native footprint because the webview is not bundled with every application [1]. | Android and iOS projects are generated through Tauri’s mobile commands; native signing and store configuration remain platform-specific. The current Android debug build is not a valid production-size benchmark. | Medium for desktop, medium-high for mobile | Keep for the desktop browser and retain as a supported mobile alternative. |
+| Capacitor 8.5.0 for Android and iOS | Designed to drop into an existing web project. The documented requirements are a package manifest, a built web directory and a root `index.html`; `npx cap add android`, `npx cap add ios` and `npx cap sync` create and synchronize the native projects [2]. Android uses the system WebView and exposes a JavaScript bridge to Java or Kotlin [3]. | Adds native Android and iOS project trees and a separate plugin boundary. It does not automatically make a web bundle small; release shrinking, asset selection and ABI strategy still control the final size. | Medium | Select as the primary 1.8.10 conversion path for explicit `android/` and `ios/` folders. |
+| Ionic Framework 7.2.1 with Capacitor | Provides a mobile UI component system and navigation conventions on top of the web stack. It can be adopted where mobile-specific controls are required. | It is optional for Capacitor. Adding Ionic to Saddle’s existing React/Tailwind surface would duplicate or replace UI primitives and would not, by itself, solve the 119 MiB debug APK problem. | Medium-high | Do not migrate the current design to Ionic in 1.8.10. Evaluate Ionic components later only for a clearly identified mobile interaction gap. |
+
+## Chosen architecture
+
+The library remains the source of truth. The existing `desktop/` Tauri shell remains the browser and desktop application surface. The existing root `browser/` directory remains the transport-neutral browser-agent logic and must not be duplicated as a second browser implementation.
+
+The 1.8.10 work introduces explicit `android/` and `ios/` surface boundaries using Capacitor configuration and native project inputs. Both surfaces consume the same compiled web distribution and import the same library contracts. They do not fork the engine, reimplement browser actions or store credentials in source control. The generated native projects are conversion targets; the TypeScript and TSX source remains authoritative.
+
+The browser naming is normalized at the release boundary rather than by renaming the transport-neutral `browser/` logic into a second application. The desktop browser bundle is named from the Saddle product identity, while the internal browser modules keep their API-compatible names.
+
+## Why the 1.8.9 debug APK is large
+
+The v1.8.9 APK is `125,242,132` bytes, approximately 119.5 MiB. It was generated by the workflow with Tauri’s `--debug --apk --aab` path, so it is a debug test artifact rather than a production-size release benchmark. The release AAB is `35,494,095` bytes, approximately 33.8 MiB, but it is also debug-signed.
+
+The primary optimization path is therefore to generate a release build, enable R8 code shrinking and resource shrinking, and measure the result with Android’s APK Analyzer. Android documents that R8 removes unreachable code, optimizes and obfuscates the remaining code, while resource shrinking removes unused resources [4]. Android also documents that App Bundles allow Google Play to generate device-specific APKs and that `--split-per-abi` is useful for testing or distribution outside Google Play [5]. APK Analyzer reports raw size, estimated download size and side-by-side differences between builds [6].
+
+The 1.8.10 workflow will keep a debug artifact only as an explicitly named test output. The release path will produce a release AAB and an architecture-specific APK when signing inputs are available. It will not claim that a debug universal APK is store-ready.
+
+### Measured 1.8.9 APK composition
+
+The downloaded `app-universal-debug.apk` is 120 MiB on disk and contains 925 archive entries with 133,213,007 bytes of uncompressed content. The dominant entry is `lib/arm64-v8a/libsaddle_desktop.so` at 118,076,216 bytes. The web distribution is approximately 3.3 MiB, so the web assets are not the primary cause of the APK size. The first optimization target is the debug Rust shared library: release compilation, symbol stripping, native profile selection and inspection of the generated `.so` are required before evaluating a framework change.
+
+## Release naming policy
+
+Public artifact names use lowercase product identity, dots as separators and the release version. The policy avoids underscores, build-helper names and ambiguous generic files.
+
+| Surface | 1.8.10 naming pattern |
+| --- | --- |
+| Desktop browser | `saddle.browser.1.8.10.<format>` |
+| Android APK | `saddle.apk.1.8.10.<abi>.apk` |
+| Android AAB | `saddle.aab.1.8.10.aab` |
+| iOS IPA | `saddle.ipa.1.8.10.ipa` |
+| Container | `saddle.container.1.8.10.tar.gz` |
+| Extension | `saddle.extension.1.8.10.zip` |
+| Checksums | `sha256.<surface>.1.8.10` |
+| Manifest | `manifest.<surface>.1.8.10.json` |
+
+The workflow must reject `build_script_build*.exe`, `build-script-build.exe`, `saddle_desktop.exe`, generic `artifact-manifest.json`, generic `SHA256SUMS` and any public filename containing an underscore. Rust build-script executables are intermediate compilation outputs and are never release assets.
+
+## References
+
+[1]: https://v2.tauri.app/start/ "Tauri: What is Tauri?"
+[2]: https://capacitorjs.com/docs/getting-started "Capacitor: Installing Capacitor"
+[3]: https://capacitorjs.com/docs/android "Capacitor Android Documentation"
+[4]: https://developer.android.com/topic/performance/app-optimization/enable-app-optimization "Android Developers: Enable app optimization with R8"
+[5]: https://v2.tauri.app/distribute/google-play/ "Tauri: Google Play distribution"
+[6]: https://developer.android.com/studio/debug/apk-analyzer "Android Developers: Analyze your build with the APK Analyzer"

package/docs/release.md

@@ -6,10 +6,10 @@ The release path is intentionally split into source validation, package validati
 
 | step | owner | condition |
 |---|---|---|
-| package version | repository | `package.json` matches the release tag, for example `1.8.8` |
+| package version | repository | `package.json` matches the release tag, for example `1.8.9` |
 | quality gate | GitHub Actions | `npm run pack:check` passes |
-| tag | repository owner | tag `v1.8.8` points to the validated release commit |
-| GitHub release | repository owner | release `v1.8.8` is created from the validated tag |
+| tag | repository owner | tag `v1.8.9` points to the validated release commit |
+| GitHub release | repository owner | release `v1.8.9` is created from the validated tag |
 | GitHub Packages | GitHub Actions | `publishgithubnpm.yml`, `publishghcr.yml`, `publishmaven.yml`, `publishnuget.yml`, and `publishrubygems.yml` use `GITHUB_TOKEN` |
 | public npmjs | owner-managed GitHub Actions secret | `publishnpmjs.yml` uses `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` and derives the version from the release tag or latest release in manual maintenance runs |
 | extension zip | GitHub Actions | `buildextension.yml` derives the version from the release tag, validates the unpacked artifact and attaches `saddle-extension-<version>.zip` |
@@ -22,8 +22,8 @@ The npm token previously sent in chat is compromised and must not be used. GitHu
 
 ```text
 npm run pack:check
-git tag v1.8.8
-git push origin v1.8.8
+git tag v1.8.9
+git push origin v1.8.9
 ```
 
 The release-created event is the publication and extension-asset trigger for the release workflows. A dry-run verifies package shape and local tests, but cannot verify registry ownership, Trusted Publisher configuration, package scope authorization, package visibility or browser-store submission; those remain settings controlled by the owner.

package/docs/releaseassets.md

@@ -1,16 +1,17 @@
 # Release assets
 
-The Node-only release adapter creates deterministic metadata for caller-selected artifacts. It writes `SHA256SUMS`, `sbom.cdx.json` in CycloneDX 1.5 shape and `provenance.intoto.jsonl` in an in-toto statement shape. The adapter never publishes, authenticates or selects a registry.
+The Node-only release adapter creates deterministic metadata for caller-selected artifacts. For version `1.8.10`, it writes dotted surface-specific names such as `sha256.desktop.1.8.10`, `manifest.desktop.1.8.10.json`, `sbom.desktop.1.8.10.cdx.json` and `provenance.desktop.1.8.10.intoto.jsonl`. The adapter rejects underscore-based public names and Rust build-helper executables. It never publishes, authenticates or selects a registry.
 
 ```bash
 npm run release:assets -- \
-  --version 1.8.8 \
+  --version 1.8.10 \
+  --surface desktop \
   --output build/release \
   --artifact build/saddle.tgz \
   --build-type caller-build \
   --builder caller-ci
 ```
 
-The artifact paths are supplied by the caller and are sorted before the checksum and provenance files are written. Package dependencies are read from the root lockfile to build a compact component list. The output can be attached to a release or checked by a registry-specific workflow without adding credentials to the library.
+The artifact paths are supplied by the caller and are sorted before the checksum, manifest, SBOM and provenance files are written. Package dependencies are read from the root lockfile to build a compact component list. The output can be attached to a release or checked by a registry-specific workflow without adding credentials to the library.
 
 The package also exports the adapter as `@wenathlan/saddle/release-assets`. It is intentionally Node-only because release metadata reads files and uses the Node crypto implementation; the transport-neutral root remains free of Node imports.

package/docs/reorganization-1.8.9.md

@@ -0,0 +1,28 @@
+# Reorganization 1.8.9
+
+## Scope
+
+Version 1.8.9 converts the active engine and its deterministic test surface to a root-based TypeScript source layout. The source tree does not gain `src/`; generated JavaScript, declarations, source maps and target plans are created in ignored `dist/` or `build/` directories by local scripts and release workflows.
+
+## Ownership groups
+
+| Group | Canonical source context | Compatibility rule |
+| --- | --- | --- |
+| Public engine | `index.ts`, `library`, `domain`, `core`, `runtime` | Root exports keep their public names and emit stable `dist/*.js` paths. |
+| Storage and memory | `storage`, `memory`, `persistence` | Physical, vector, remote and in-process adapters remain caller-owned. |
+| Acquisition | `scrape`, `browser`, `captcha`, `proxy` | Scrape, crawl, browser and evidence contracts remain separate where their capabilities differ. |
+| Operations | `queue`, `dispatch`, `workflow`, `runners`, `observability` | Retry, circuit, scheduling and resume contracts stay grouped by lifecycle responsibility. |
+| Delivery | `packager`, `release`, `binary`, `surfaces`, `extension`, `cli` | Delivery modules describe plans or build adapters; they do not own store credentials or signing keys. |
+| Web | `web/App.tsx`, `web/components`, `web/pages`, `web/lib`, `web/contexts`, `web/hooks` | The static React surface remains root based and TypeScript. The dynamic debug collector is an explicit `@ts-nocheck` browser instrumentation boundary. |
+
+## Build boundary
+
+The project uses a project-local TypeScript 7 compiler. `npm run build:engine` removes and regenerates `dist/`; package `main`, `module`, `browser`, `types`, `bin` and all declared export targets point at that generated output. The npm package includes `dist`, but the Git repository does not commit generated output.
+
+## Target boundary
+
+Application, computer, desktop, mobile, Android, iOS, browser, extension, web, CLI, binary, LibreOffice, MCP, VSIX and container formats are represented by declarative manifests. The workflow produces plans for each target and uploads them as CI artifacts. Actual Android SDK, Xcode, desktop installer, browser-store, LibreOffice and signing toolchains remain caller-selected adapters because the core cannot safely embed platform credentials or vendor infrastructure.
+
+## Verification
+
+The active Node contract has 98 passing tests. The preserved legacy scrape TypeScript surface has 69 passing Vitest tests. Web `tsc`, Pages build, format checks, package dry-run and high-severity audit remain release gates. A target plan is accepted only when it contains the release version, canonical compiled entry, output path, caller-managed credentials marker and reproducible metadata.

package/docs/toolchainresearch-1.8.9.md

@@ -0,0 +1,18 @@
+# Toolchain research 1.8.9
+
+## Date
+
+The migration baseline is **2026-08-13**.
+
+## Verified sources
+
+| Area | Verified finding | Source |
+| --- | --- | --- |
+| TypeScript | The official TypeScript download page states that TypeScript 7.0 is currently available and recommends a project-local npm installation for reproducible lockfiles. | [TypeScript download](https://www.typescriptlang.org/download/) |
+| TypeScript release | The official TypeScript team blog announces TypeScript 7.0 as the current native compiler release. | [Announcing TypeScript 7.0](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/) |
+| Node.js | Node.js 26.7.0 is the current release in the v26 line as of 2026-08-05. | [Node.js 26.7.0](https://nodejs.org/en/blog/release/v26.7.0) |
+| Node.js support | The official release table identifies v26 as Current and v24 as LTS; production targets should remain caller-selectable between supported Current and LTS runtimes. | [Node.js releases](https://nodejs.org/en/about/previous-releases) |
+
+## Migration decision
+
+The root project will use a project-local TypeScript compiler pinned in `package.json` and `package-lock.json`. The engine target remains Node.js `>=26.7.0`, while target manifests may declare a different runtime only when the target adapter and workflow provide an explicit compatibility contract. Generated JavaScript, declaration files, source maps and bundles remain build output and are not committed as source.

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Saddle browser bridge",
-  "version": "1.8.8",
+  "version": "1.8.10",
   "description": "User initiated page snapshots through the Saddle browser contract.",
   "minimum_chrome_version": "110",
   "permissions": ["activeTab", "scripting", "storage"],

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "@wenathlan/saddle",
-  "version": "1.8.8",
+  "version": "1.8.10",
   "description": "binary computing engine that turns distributed storage into a publishable working set",
   "type": "module",
   "private": false,
   "license": "GPL-3.0-only",
   "author": "Wenathlan",
   "sideEffects": false,
-  "main": "./index.js",
-  "module": "./index.js",
-  "browser": "./index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "browser": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "packageManager": "npm@12.0.2",
   "publishConfig": {
     "access": "public"
   },
+  "overrides": {
+    "xcode": {
+      "uuid": "11.1.1"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/wenathlan/saddle.git"
@@ -42,88 +48,66 @@
     }
   },
   "bin": {
-    "saddle": "./cli/main.js"
+    "saddle": "./dist/cli/main.js"
   },
   "exports": {
-    ".": "./index.js",
-    "./memory": "./memory/bridge.js",
-    "./memory-node": "./memory/bridge.js",
-    "./memory-engine": "./memory/engine.js",
-    "./storage": "./storage/index.js",
-    "./storage-node": "./storage/local.js",
-    "./runners": "./runners/scheduler.js",
-    "./sessions": "./domain/sessions.js",
-    "./modes": "./modes/resolve.js",
-    "./mode": "./modes/matrix.js",
-    "./browser": "./browser/index.js",
-    "./browser-playwright": "./browser/playwright.js",
-    "./bot": "./bot/bot.js",
-    "./captcha": "./captcha/contract.js",
-    "./deploy": "./deploy/index.js",
-    "./extension": "./extension/index.js",
-    "./server-node": "./server/node.js",
-    "./sessions-file": "./sessions/file.js",
-    "./sessions-store": "./sessions/store.js",
-    "./queue-persistent": "./queue/persistent.js",
-    "./captcha-evidence": "./captcha/evidence.js",
-    "./hash": "./core/hash.js",
-    "./release-assets": "./release/assets.js",
-    "./worker": "./runtime/worker.js"
+    ".": "./dist/index.js",
+    "./memory": "./dist/memory/bridge.js",
+    "./memory-node": "./dist/memory/bridge.js",
+    "./memory-engine": "./dist/memory/engine.js",
+    "./storage": "./dist/storage/index.js",
+    "./storage-node": "./dist/storage/local.js",
+    "./runners": "./dist/runners/scheduler.js",
+    "./sessions": "./dist/domain/sessions.js",
+    "./modes": "./dist/modes/resolve.js",
+    "./mode": "./dist/modes/matrix.js",
+    "./browser": "./dist/browser/index.js",
+    "./browser-playwright": "./dist/browser/playwright.js",
+    "./bot": "./dist/bot/bot.js",
+    "./captcha": "./dist/captcha/contract.js",
+    "./deploy": "./dist/deploy/index.js",
+    "./extension": "./dist/extension/index.js",
+    "./server-node": "./dist/server/node.js",
+    "./sessions-file": "./dist/sessions/file.js",
+    "./sessions-store": "./dist/sessions/store.js",
+    "./queue-persistent": "./dist/queue/persistent.js",
+    "./captcha-evidence": "./dist/captcha/evidence.js",
+    "./hash": "./dist/core/hash.js",
+    "./release-assets": "./dist/release/assets.js",
+    "./worker": "./dist/runtime/worker.js"
   },
   "files": [
-    "core",
-    "domain",
-    "memory",
-    "runners",
-    "runtime",
-    "storage",
-    "sessions",
-    "modes",
-    "adapters",
-    "persistence",
-    "queue",
-    "dispatch",
-    "scrape",
-    "api",
-    "mcp",
-    "browser",
-    "proxy",
-    "captcha",
-    "ai",
-    "webhook",
-    "surfaces",
-    "library",
-    "server",
-    "binary",
-    "format",
-    "packager",
-    "bot",
-    "protocol",
-    "workflow",
-    "cli",
-    "extension",
-    "release",
-    "index.js",
+    "dist",
+    "extension/manifest.json",
     "docs",
-    "examples",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "check": "node --check index.js && node --check runtime/engine.js && node --check runtime/retry.js && node --check cli/main.js && node --check extension/protocol.js && node --check extension/serviceworker.js && node --check extension/worker.js && node --check extension/content.js && node --check extension/pagebridge.js && node --check extension/popup.js && node --check extension/permissions.js && node --check extension/build.js && node --check release/assets.js && node --check sessions/replay.js && node --check browser/recorder.js && node --check scrape/normalize.js && node --check scrape/crawl.js",
-    "formatcheck": "node format/check.js",
-    "test": "node --test tests/*.test.js",
-    "run": "node cli/main.js",
-    "extension:build": "node extension/build.js",
-    "release:assets": "node release/assets.js",
+    "build:engine": "node tests/scripts/buildengine.mjs",
+    "check": "npm run build:engine && node --check dist/index.js && node --check dist/runtime/engine.js && node --check dist/cli/main.js && node --check dist/extension/serviceworker.js && node --check dist/release/assets.js",
+    "formatcheck": "node --import tsx format/check.ts",
+    "test": "npm run build:engine && node --import tsx --test tests/engine.test.ts tests/extension.test.ts tests/package.test.ts tests/release.test.ts",
+    "test:legacy": "vitest run tests/agent-utils.test.ts tests/cache.test.ts tests/chunking.test.ts tests/core.test.ts tests/errors.test.ts tests/llms-txt.test.ts tests/middleware.test.ts tests/proxy.test.ts tests/tokens.test.ts",
+    "run": "npm run build:engine && node dist/cli/main.js",
+    "extension:build": "npm run build:engine && node dist/extension/build.js",
+    "release:assets": "npm run build:engine && node dist/release/assets.js",
+    "target:manifest": "npm run build:engine && node dist/packager/targetcli.js",
     "pack:check": "npm run check && npm run formatcheck && npm test && npm pack --dry-run",
     "prepublishOnly": "npm run pack:check",
+    "tauri": "npx --yes @tauri-apps/cli@2.11.4",
+    "capacitor:sync:android": "npm run web:build:pages && cap sync android",
+    "capacitor:sync:ios": "npm run web:build:pages && cap sync ios",
     "web:dev": "vite --config web/vite.config.ts --host",
     "web:check": "tsc --project web/tsconfig.json --noEmit",
     "web:build": "vite build --config web/vite.config.ts",
     "web:build:pages": "vite build --config web/vite.config.ts"
   },
   "devDependencies": {
+    "@capacitor/android": "^8.5.0",
+    "@capacitor/cli": "^8.5.0",
+    "@capacitor/core": "^8.5.0",
+    "@capacitor/ios": "^8.5.0",
     "@hookform/resolvers": "^5.2.2",
     "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-alert-dialog": "^1.1.15",
@@ -151,17 +135,31 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "@tailwindcss/typography": "^0.5.15",
+    "@tailwindcss/vite": "^4.1.3",
+    "@types/express": "4.17.21",
+    "@types/google.maps": "^3.58.1",
+    "@types/node": "^24.7.0",
+    "@types/react": "^19.2.1",
+    "@types/react-dom": "^19.2.1",
+    "@vitejs/plugin-react": "^5.0.4",
+    "add": "^2.0.6",
+    "autoprefixer": "^10.4.20",
     "axios": "^1.12.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "embla-carousel-react": "^8.6.0",
+    "esbuild": "^0.25.0",
     "express": "^4.21.2",
     "framer-motion": "^12.23.22",
     "input-otp": "^1.4.2",
+    "jsdom": "26.1.0",
     "lucide-react": "^0.453.0",
     "nanoid": "^5.1.5",
     "next-themes": "^0.4.6",
+    "postcss": "^8.4.47",
+    "prettier": "^3.6.2",
     "react": "^19.2.1",
     "react-day-picker": "^9.11.1",
     "react-dom": "^19.2.1",
@@ -171,29 +169,16 @@
     "sonner": "^2.0.7",
     "streamdown": "^1.4.0",
     "tailwind-merge": "^3.3.1",
-    "tailwindcss-animate": "^1.0.7",
-    "vaul": "^1.1.2",
-    "wouter": "^3.3.5",
-    "zod": "^4.1.12",
-    "@tailwindcss/typography": "^0.5.15",
-    "@tailwindcss/vite": "^4.1.3",
-    "@types/express": "4.17.21",
-    "@types/google.maps": "^3.58.1",
-    "@types/node": "^24.7.0",
-    "@types/react": "^19.2.1",
-    "@types/react-dom": "^19.2.1",
-    "@vitejs/plugin-react": "^5.0.4",
-    "add": "^2.0.6",
-    "autoprefixer": "^10.4.20",
-    "esbuild": "^0.25.0",
-    "postcss": "^8.4.47",
-    "prettier": "^3.6.2",
     "tailwindcss": "^4.1.14",
+    "tailwindcss-animate": "^1.0.7",
     "tsx": "^4.19.1",
     "tw-animate-css": "^1.4.0",
-    "typescript": "5.6.3",
+    "typescript": "7.0.2",
+    "vaul": "^1.1.2",
     "vite": "^7.1.7",
     "vite-plugin-manus-runtime": "^0.0.58",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "wouter": "^3.3.5",
+    "zod": "^4.1.12"
   }
 }

package/adapters/forge.js

@@ -1,16 +0,0 @@
-/**
- * forge adapter defines the common dispatch and artifact surface for compatible forges.
- */
-import { transport } from "./transport.js";
-
-export function forgeadapter(options = {}) {
-  if (!options.baseurl || typeof options.token !== "function") throw new TypeError("forge adapter requires baseurl and token function");
-  const client = transport({ fetcher: options.fetcher, attempts: options.attempts, timeout: options.timeout });
-  async function call(path, init = {}) { const token = await options.token(); return client.request(new URL(path, options.baseurl), { ...init, headers: { authorization: `Bearer ${token}`, accept: "application/json", ...(init.headers ?? {}) } }); }
-  return {
-    kind: options.kind ?? "forge",
-    async health(path = "/") { const response = await call(path); return { ok: response.ok, status: response.status }; },
-    async dispatch(spec) { if (!spec?.path || !spec.ref) throw new TypeError("forge dispatch requires path and ref"); const response = await call(spec.path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ref: spec.ref, inputs: spec.inputs ?? {} }) }); return { accepted: response.ok, status: response.status, body: response.json ? await response.json() : undefined }; },
-    async upload(spec) { if (!spec?.path || !spec.data) throw new TypeError("forge upload requires path and data"); const response = await call(spec.path, { method: "PUT", headers: { "content-type": spec.contenttype ?? "application/octet-stream" }, body: spec.data }); return { accepted: response.ok, status: response.status }; }
-  };
-}

package/adapters/github.js

@@ -1,19 +0,0 @@
-/**
- * github adapter uses caller supplied credentials and base url configuration.
- */
-import { transport } from "./transport.js";
-
-export function githubadapter(options = {}) {
-  if (!options.baseurl || typeof options.token !== "function") throw new TypeError("github adapter requires baseurl and token function");
-  const client = transport({ fetcher: options.fetcher, attempts: options.attempts, timeout: options.timeout });
-  async function call(path, init = {}) {
-    const token = await options.token();
-    const headers = { accept: "application/vnd.github+json", authorization: `Bearer ${token}`, "x-github-api-version": options.apiversion ?? "2022-11-28", ...(init.headers ?? {}) };
-    return client.request(new URL(path, options.baseurl), { ...init, headers });
-  }
-  return {
-    async health() { const response = await call("/rate_limit"); return { ok: response.ok, status: response.status }; },
-    async dispatch(owner, repository, workflow, input = {}) { const response = await call(`/repos/${owner}/${repository}/actions/workflows/${workflow}/dispatches`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ref: input.ref ?? "main", inputs: input.inputs ?? {} }) }); return { accepted: response.status === 204, status: response.status }; },
-    async run(owner, repository, runid) { const response = await call(`/repos/${owner}/${repository}/actions/runs/${runid}`); return response.json(); }
-  };
-}

package/adapters/gitlab.js

@@ -1,10 +0,0 @@
-/**
- * gitlab adapter keeps project addressing and token ownership outside the package.
- */
-import { forgeadapter } from "./forge.js";
-
-export function gitlabadapter(options = {}) {
-  const project = encodeURIComponent(options.project ?? "");
-  const base = forgeadapter({ ...options, kind: "gitlab" });
-  return { ...base, async dispatch(spec) { return base.dispatch({ ...spec, path: spec.path ?? `/api/v4/projects/${project}/pipeline` }); } };
-}

package/adapters/socket.js

@@ -1,14 +0,0 @@
-/**
- * socket adapter keeps realtime optional and accepts a caller supplied websocket constructor.
- */
-export function socketadapter(options = {}) {
-  const websocket = options.websocket ?? globalThis.WebSocket;
-  if (!websocket) throw new Error("websocket implementation is required");
-  return {
-    connect(url, protocols) {
-      if (!url) throw new TypeError("socket url is required");
-      const socket = new websocket(url, protocols);
-      return { socket, send(value) { socket.send(typeof value === "string" ? value : JSON.stringify(value)); }, close(code, reason) { socket.close(code, reason); } };
-    }
-  };
-}