@wenathlan/saddle 1.8.5 → 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.5` | publishgithubnpm.yml | pending release |
-| GHCR | `ghcr.io/wenathlan/saddle:1.8.5` and `latest` | publishghcr.yml | pending release |
-| Maven | `io.wenathlan:saddle:1.8.5` | publishmaven.yml | pending release |
-| NuGet | `Saddle.1.8.5.nupkg` | publishnuget.yml | pending release |
-| RubyGems | `saddle 1.8.5` | publishrubygems.yml | pending release |
-| npmjs | `@wenathlan/saddle@1.8.5` | 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.5 extends the 1.8.4 engine contracts with package metadata for Node.js 26.7.0 and npm 12, an optional Playwright peer, and an explicit Node-only `browser-playwright` adapter. 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.
+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/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 |
+| 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/platformpipelineaudit.md

@@ -1,12 +1,16 @@
 # Platform pipeline audit
 
-This document records the platform facts used by the 1.8.4 pipeline work. The workflows remain caller-configured: repository owners provide runner availability, deployment secrets and target repository names.
+This document records the platform facts used by the 1.8.6 pipeline work and the subsequent web root migration. The workflows remain caller-configured: repository owners provide runner availability, deployment secrets and target repository names.
+
+## repository layout contract
+
+The repository has one package manifest and one npm lockfile at the root. The static application is rooted at `web/` without a nested `client/` or `src/` directory: `web/index.html`, `web/main.tsx`, `web/App.tsx`, `web/components/`, `web/pages/`, `web/public/` and `web/dist/` are the canonical paths. Every Pages pipeline installs from the root with `npm ci`, runs `npm run web:check`, and writes the deployable artifact to `web/dist/public`. No nested web package, pnpm lockfile or platform workflow is retained.
 
 ## verified platform facts
 
 | Platform | Verified contract | Source |
 | --- | --- | --- |
-| GitHub Pages | A custom workflow uses `actions/configure-pages@v5`, uploads a static artifact with `actions/upload-pages-artifact@v4`, then deploys with `actions/deploy-pages@v4`. The deployment job needs `pages: write` and `id-token: write`, depends on the build job and uses the `github-pages` environment. | [GitHub Pages custom workflows](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages) |
+| GitHub Pages | A custom workflow uses `actions/configure-pages@v5`, derives the project base path from the Pages output or repository name, uploads a static artifact with `actions/upload-pages-artifact@v4`, then deploys from a dependent job with `actions/deploy-pages@v4`. The deployment job needs `pages: write` and `id-token: write`, depends on the build job and uses the `github-pages` environment. The repository source is configured as GitHub Actions and the current site is `https://wenathlan.github.io/saddle/`. | [GitHub Pages custom workflows](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages) |
 | Codeberg Pages | Forgejo Actions can deploy with `https://codeberg.org/git-pages/action@v2`, using `site`, `source` and the injected `${{ forge.token }}`. Publishing the repository subdomain should be restricted to the default branch. Codeberg is migrating its legacy Pages v2 flow; custom domains still have separate constraints. | [Codeberg Pages via Forgejo Actions](https://docs.codeberg.org/codeberg-pages/forgejo-actions/), [Codeberg Pages output](https://docs.codeberg.org/codeberg-pages/pushing-output/) |
 | GitLab Pages | A job with `pages: true` publishes the default `public` directory; the job can also use a `pages` hash for a `path_prefix`. Static HTML, CSS and JavaScript are supported through GitLab CI/CD. | [GitLab Pages](https://docs.gitlab.com/user/project/pages/) |
 | Woodpecker CI | A workflow is a serial list of container steps with `image` and `commands`; branch/event filters belong in `when`, and secrets are injected through the pipeline environment rather than committed YAML. | [Woodpecker workflow syntax](https://woodpecker-ci.org/docs/usage/workflow-syntax) |

package/docs/releaseassets.md

@@ -0,0 +1,16 @@
+# 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.
+
+```bash
+npm run release:assets -- \
+  --version 1.8.6 \
+  --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 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/extension/README.md

@@ -14,7 +14,7 @@ The manifest requests only `activeTab`, `scripting` and `storage`. It does not r
 
 ## boundaries
 
-The content bridge runs in Chrome's isolated world. It exposes bounded page metadata, visible text, stable references and user initiated click or fill commands. The service worker forwards versioned messages, persists bounded pending command records and stores the latest snapshot metadata in session storage. Rehydration is explicit; startup never replays a command without a caller action. No endpoint, credential, remote script or browser profile is embedded.
+The content bridge runs in Chrome's isolated world. It exposes bounded page metadata, visible text, stable references and user initiated click or fill commands. Extension snapshots carry optional window, tab and frame identifiers and can produce bounded additions, removals and changed-element diffs. `pagebridge.js` runs in the page world as a narrow read-only boundary; the isolated content script requests the `pagefacts` command through a token-correlated `postMessage` channel and rejects foreign sources or timed-out responses. The page world cannot invoke extension commands, receive credentials or evaluate arbitrary extension code. The service worker forwards versioned messages, persists bounded pending command records and restores their context metadata on explicit resume. No endpoint, credential, remote script or browser profile is embedded.
 
 `protocol.js` and `serviceworker.js` are reusable ESM contracts. `content.js` is intentionally a classic injected file because programmatic Chrome content scripts are loaded as files; it exposes a small global bridge and avoids arbitrary page JavaScript evaluation.
 
@@ -24,4 +24,4 @@ The Node-only build adapter creates an isolated unpacked artifact with the relea
 
 ## next slices
 
-The next extension slices should add snapshot diffing, richer tab and frame metadata, optional host permission escalation and browser action results. Browser providers, login profiles, captcha solvers and remote runners remain caller owned adapters.
+The next extension slices should add optional host permission escalation, richer browser action results and Firefox, Edge or Safari adapter profiles. Browser providers, login profiles, captcha solvers and remote runners remain caller owned adapters.

package/extension/build.js

@@ -7,7 +7,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const rootpath = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const entries = ["manifest.json", "worker.js", "serviceworker.js", "content.js", "popup.js", "popup.html", "popup.css", "protocol.js", "permissions.js"];
+const entries = ["manifest.json", "worker.js", "serviceworker.js", "content.js", "pagebridge.js", "popup.js", "popup.html", "popup.css", "protocol.js", "permissions.js"];
 
 function parsearguments(argumentslist) {
   const options = {};

package/extension/content.js

@@ -6,12 +6,14 @@
 (function installglobalbridge(global) {
   const installedkey = "__saddlecontentbridge";
   const protocolversion = 1;
-  const commands = ["snapshot", "readpage", "clickref", "fillref"];
+  const commands = ["snapshot", "readpage", "pagefacts", "clickref", "fillref"];
+  const pagechannelname = "saddle.pagefacts.v1";
 
-  function createbridge(documentref, now = () => Date.now()) {
+  function createbridge(documentref, now = () => Date.now(), options = {}) {
     let snapshotid = null;
     let sequence = 0;
     const references = new Map();
+    const pagechannel = options.pagechannel ?? (typeof global.addEventListener === "function" && typeof global.postMessage === "function" ? createpagechannel(global, now, options.timeout) : null);
 
     function snapshotpage() {
       const nextid = `snap${++sequence}${now()}`;
@@ -45,6 +47,10 @@
       const payload = request.payload ?? {};
       if (request.command === "snapshot") return snapshotpage();
       if (request.command === "readpage") return readpage();
+      if (request.command === "pagefacts") {
+        if (!pagechannel) throw failure("page_bridge_unavailable", "page bridge is not available");
+        return pagechannel.readpage();
+      }
       const element = resolve(payload.ref, payload.snapshotid);
       if (request.command === "clickref") { element.click?.(); return { ref: payload.ref, clicked: true, snapshotid }; }
       if (!isfillable(element)) throw failure("not_fillable", `element is not fillable: ${payload.ref}`);
@@ -52,7 +58,43 @@
       return { ref: payload.ref, filled: true, snapshotid };
     }
 
-    return { handle, snapshotpage, readpage };
+    return { handle, snapshotpage, readpage, pagechannel };
+  }
+
+  function createpagechannel(globalref = global, now = () => Date.now(), timeout = 1500) {
+    if (typeof globalref.addEventListener !== "function" || typeof globalref.postMessage !== "function") throw new TypeError("page channel requires window messaging APIs");
+    if (!Number.isSafeInteger(timeout) || timeout < 1) throw new TypeError("page channel timeout must be a positive safe integer");
+    const pending = new Map();
+    let sequence = 0;
+    const token = `token${now()}${Math.random().toString(16).slice(2)}`;
+
+    function listener(event) {
+      const response = event?.data;
+      if (event?.source && event.source !== globalref) return;
+      if (response?.channel !== pagechannelname || response.type !== "response" || response.token !== token) return;
+      const request = pending.get(response.requestid);
+      if (!request) return;
+      pending.delete(response.requestid);
+      globalref.clearTimeout?.(request.timer);
+      request.resolve(response.payload ?? {});
+    }
+
+    function readpage() {
+      const requestid = `page${now()}${++sequence}`;
+      return new Promise((resolve, reject) => {
+        const timer = globalref.setTimeout(() => {
+          pending.delete(requestid);
+          const error = new Error("page bridge response timed out");
+          error.code = "page_bridge_timeout";
+          reject(error);
+        }, timeout);
+        pending.set(requestid, { resolve, timer });
+        globalref.postMessage({ channel: pagechannelname, version: 1, type: "request", requestid, token }, "*");
+      });
+    }
+
+    globalref.addEventListener("message", listener);
+    return { readpage, dispose() { globalref.removeEventListener?.("message", listener); for (const request of pending.values()) globalref.clearTimeout?.(request.timer); pending.clear(); } };
   }
 
   function install(runtime = global.chrome?.runtime, documentref = global.document) {
@@ -80,6 +122,6 @@
   function setvalue(element, value) { element.value = String(value ?? ""); element.dispatchEvent?.(new Event("input", { bubbles: true })); element.dispatchEvent?.(new Event("change", { bubbles: true })); }
   function failure(code, message) { const error = new Error(message); error.code = code; return error; }
 
-  global.saddlecontent = { createbridge, install };
+  global.saddlecontent = { createbridge, createpagechannel, install };
   if (global.chrome?.runtime?.onMessage && global.document) install();
 })(globalThis);

package/extension/manifest.json

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

package/extension/pagebridge.js

@@ -0,0 +1,41 @@
+/**
+ * page bridge exposes bounded, read-only page facts to the isolated content world.
+ * It never executes page supplied commands and never forwards extension credentials.
+ */
+
+(function installpagebridge(global) {
+  const channel = "saddle.pagefacts.v1";
+  const installedkey = "__saddlepagebridge";
+
+  function createpagebridge(globalref = global) {
+    function readpage() {
+      const documentref = globalref.document;
+      return {
+        url: String(documentref?.location?.href ?? ""),
+        title: String(documentref?.title ?? "").slice(0, 500),
+        text: String(documentref?.body?.innerText ?? "").slice(0, 100000)
+      };
+    }
+
+    function listener(event) {
+      const request = event?.data;
+      if (event?.source && event.source !== globalref) return;
+      if (request?.channel !== channel || request.type !== "request" || typeof request.requestid !== "string" || typeof request.token !== "string") return;
+      globalref.postMessage({ channel, version: 1, type: "response", requestid: request.requestid, token: request.token, payload: readpage() }, "*");
+    }
+
+    return { channel, listener, readpage };
+  }
+
+  function install(globalref = global) {
+    if (typeof globalref?.addEventListener !== "function" || !globalref.document) throw new TypeError("page bridge requires a window and document");
+    if (globalref[installedkey]) return globalref[installedkey];
+    const bridge = createpagebridge(globalref);
+    globalref.addEventListener("message", bridge.listener);
+    globalref[installedkey] = { ...bridge, dispose() { globalref.removeEventListener?.("message", bridge.listener); delete globalref[installedkey]; } };
+    return globalref[installedkey];
+  }
+
+  global.saddlepagebridge = { channel, createpagebridge, install };
+  if (global.document && typeof global.addEventListener === "function") install(global);
+})(globalThis);

package/extension/protocol.js

@@ -3,7 +3,7 @@
  */
 
 export const protocolversion = 1;
-export const extensioncommands = Object.freeze(["snapshot", "readpage", "clickref", "fillref"]);
+export const extensioncommands = Object.freeze(["snapshot", "readpage", "pagefacts", "clickref", "fillref"]);
 
 /** Creates a compact identifier without embedding a host, port or credential. */
 export function createid(prefix = "msg", source) {
@@ -59,10 +59,13 @@ export function createsnapshot(input = {}) {
     version: protocolversion,
     snapshotid: String(input.snapshotid ?? createid("snap")),
     createdat: Number(input.createdat ?? Date.now()),
+    windowid: input.windowid === undefined ? undefined : String(input.windowid),
+    tabid: input.tabid === undefined ? undefined : String(input.tabid),
+    frameid: input.frameid === undefined ? undefined : String(input.frameid),
     url: String(input.url ?? ""),
     title: String(input.title ?? ""),
     text: String(input.text ?? ""),
-    elements: Array.isArray(input.elements) ? input.elements.map((element) => ({ ref: String(element.ref), role: String(element.role ?? "generic"), name: String(element.name ?? "") })) : []
+    elements: Array.isArray(input.elements) ? input.elements.map((element) => ({ ref: String(element.ref), role: String(element.role ?? "generic"), name: String(element.name ?? ""), value: element.value === undefined ? undefined : String(element.value), disabled: Boolean(element.disabled) })) : []
   };
   assertserializable(snapshot);
   return snapshot;
@@ -71,6 +74,22 @@ export function createsnapshot(input = {}) {
 /** Returns whether a reference still belongs to the current page snapshot. */
 export function isfreshsnapshot(snapshotid, currentid) { return Boolean(snapshotid && currentid && snapshotid === currentid); }
 
+/** Computes bounded additions, removals and changed elements between extension snapshots. */
+export function snapshotdiff(previous, current) {
+  const before = createsnapshot(previous);
+  const after = createsnapshot(current);
+  const oldmap = new Map(before.elements.map((element) => [element.ref, element]));
+  const newmap = new Map(after.elements.map((element) => [element.ref, element]));
+  return {
+    from: before.snapshotid,
+    to: after.snapshotid,
+    contextchanged: before.windowid !== after.windowid || before.tabid !== after.tabid || before.frameid !== after.frameid,
+    added: after.elements.filter((element) => !oldmap.has(element.ref)),
+    removed: before.elements.filter((element) => !newmap.has(element.ref)),
+    changed: after.elements.filter((element) => oldmap.has(element.ref) && JSON.stringify(oldmap.get(element.ref)) !== JSON.stringify(element))
+  };
+}
+
 function assertserializable(value) {
   try { JSON.stringify(value); } catch (error) { throw new TypeError(`extension message is not serializable: ${error.message}`); }
 }

package/extension/serviceworker.js

@@ -60,7 +60,8 @@ export function createworkerrouter(options = {}) {
   async function dispatch(request, sender = {}) {
     const tabid = request.payload?.tabid ?? sender.tab?.id;
     await ensurecontent(tabid);
-    return tabs.sendMessage(tabid, request);
+    const response = await tabs.sendMessage(tabid, request);
+    return decorate(response, sender, tabid);
   }
 
   async function handle(message, sender = {}) {
@@ -70,7 +71,7 @@ export function createworkerrouter(options = {}) {
     await enqueue(request, { ...sender, tab: { ...sender.tab, id: tabid } });
     try {
       const response = await dispatch(request, { ...sender, tab: { ...sender.tab, id: tabid } });
-      await complete(request.id, response?.type === "response" && response.payload?.snapshotid ? { tabid, snapshotid: response.payload.snapshotid, updatedat: Date.now() } : { updatedat: Date.now() });
+    await complete(request.id, response?.type === "response" && response.payload?.snapshotid ? { tabid, snapshotid: response.payload.snapshotid, frameid: response.payload.frameid, windowid: response.payload.windowid, updatedat: Date.now() } : { updatedat: Date.now() });
       return response;
     } catch (error) {
       await markfailure(request.id, error);
@@ -85,8 +86,8 @@ export function createworkerrouter(options = {}) {
     const pending = state.pending.find((item) => item.requestid === requestid);
     if (!pending) throw extensionerror("PENDING_NOT_FOUND", `pending command not found: ${requestid}`);
     const tabid = pending.tabid ?? sender.tab?.id;
-    const response = await dispatch(pending.message, { ...sender, tab: { ...sender.tab, id: tabid } });
-    await complete(requestid, response?.type === "response" && response.payload?.snapshotid ? { tabid, snapshotid: response.payload.snapshotid, updatedat: Date.now() } : { updatedat: Date.now() });
+    const response = await dispatch(pending.message, { ...sender, frameId: pending.frameid ?? sender.frameId, tab: { ...sender.tab, id: tabid, windowId: pending.windowid ?? sender.tab?.windowId } });
+    await complete(requestid, response?.type === "response" && response.payload?.snapshotid ? { tabid, snapshotid: response.payload.snapshotid, frameid: response.payload.frameid, windowid: response.payload.windowid, updatedat: Date.now() } : { updatedat: Date.now() });
     return response;
   }
 
@@ -95,7 +96,13 @@ export function createworkerrouter(options = {}) {
   return { ensurecontent, readstate, savestate, rehydrate, enqueue, resume, cancel, handle };
 }
 
-function pendingrecord(request, sender = {}) { return { requestid: request.id, command: request.command, message: request, tabid: request.payload?.tabid ?? sender.tab?.id, attempts: 0, createdat: Date.now(), updatedat: Date.now() }; }
+function pendingrecord(request, sender = {}) { return { requestid: request.id, command: request.command, message: request, tabid: request.payload?.tabid ?? sender.tab?.id, frameid: request.payload?.frameid ?? sender.frameId, windowid: request.payload?.windowid ?? sender.tab?.windowId, attempts: 0, createdat: Date.now(), updatedat: Date.now() }; }
+
+function decorate(response, sender, tabid) {
+  if (response?.type !== "response" || !response.payload || typeof response.payload !== "object" || !response.payload.snapshotid) return response;
+  const payload = { ...response.payload, tabid: response.payload.tabid ?? (tabid === undefined ? undefined : String(tabid)), frameid: response.payload.frameid ?? (sender.frameId === undefined ? undefined : String(sender.frameId)), windowid: response.payload.windowid ?? (sender.tab?.windowId === undefined ? undefined : String(sender.tab.windowId)) };
+  return { ...response, payload };
+}
 
 function validpending(value) { return Boolean(value && typeof value === "object" && typeof value.requestid === "string" && value.message && value.message.type === "command" && Number.isSafeInteger(value.attempts) && value.attempts >= 0); }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/saddle",
-  "version": "1.8.5",
+  "version": "1.8.6",
   "description": "binary computing engine that turns distributed storage into a publishable working set",
   "type": "module",
   "private": false,
@@ -11,15 +11,39 @@
   "module": "./index.js",
   "browser": "./index.js",
   "packageManager": "npm@12.0.2",
-  "publishConfig": { "access": "public" },
-  "repository": { "type": "git", "url": "https://github.com/wenathlan/saddle.git" },
-  "bugs": { "url": "https://github.com/wenathlan/saddle/issues" },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wenathlan/saddle.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wenathlan/saddle/issues"
+  },
   "homepage": "https://github.com/wenathlan/saddle#readme",
-  "keywords": ["distributed computing", "virtual memory", "runner", "storage", "automation"],
-  "engines": { "node": ">=26.7.0", "npm": ">=10.9.2" },
-  "peerDependencies": { "playwright": "^1.62.1" },
-  "peerDependenciesMeta": { "playwright": { "optional": true } },
-  "bin": { "saddle": "./cli/main.js" },
+  "keywords": [
+    "distributed computing",
+    "virtual memory",
+    "runner",
+    "storage",
+    "automation"
+  ],
+  "engines": {
+    "node": ">=26.7.0",
+    "npm": ">=10.9.2"
+  },
+  "peerDependencies": {
+    "playwright": "^1.62.1"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "bin": {
+    "saddle": "./cli/main.js"
+  },
   "exports": {
     ".": "./index.js",
     "./memory": "./memory/bridge.js",
@@ -43,16 +67,137 @@
     "./queue-persistent": "./queue/persistent.js",
     "./captcha-evidence": "./captcha/evidence.js",
     "./hash": "./core/hash.js",
+    "./release-assets": "./release/assets.js",
     "./worker": "./runtime/worker.js"
   },
-  "files": ["core", "domain", "memory", "runners", "runtime", "storage", "sessions", "modes", "adapters", "persistence", "queue", "dispatch", "scrape", "crawl", "api", "mcp", "browser", "proxy", "captcha", "ai", "webhook", "surfaces", "library", "errors", "retry", "server", "binary", "format", "packager", "bot", "protocol", "workflow", "cli", "extension", "index.js", "docs", "examples", "README.md", "LICENSE"],
+  "files": [
+    "core",
+    "domain",
+    "memory",
+    "runners",
+    "runtime",
+    "storage",
+    "sessions",
+    "modes",
+    "adapters",
+    "persistence",
+    "queue",
+    "dispatch",
+    "scrape",
+    "crawl",
+    "api",
+    "mcp",
+    "browser",
+    "proxy",
+    "captcha",
+    "ai",
+    "webhook",
+    "surfaces",
+    "library",
+    "errors",
+    "retry",
+    "server",
+    "binary",
+    "format",
+    "packager",
+    "bot",
+    "protocol",
+    "workflow",
+    "cli",
+    "extension",
+    "release",
+    "index.js",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "check": "node --check index.js && node --check runtime/engine.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/popup.js && node --check extension/permissions.js && node --check extension/build.js && node --check sessions/replay.js && node --check browser/recorder.js && node --check scrape/normalize.js",
+    "check": "node --check index.js && node --check runtime/engine.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",
     "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",
     "pack:check": "npm run check && npm run formatcheck && npm test && npm pack --dry-run",
-    "prepublishOnly": "npm run pack:check"
+    "prepublishOnly": "npm run pack:check",
+    "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": {
+    "@hookform/resolvers": "^5.2.2",
+    "@radix-ui/react-accordion": "^1.2.12",
+    "@radix-ui/react-alert-dialog": "^1.1.15",
+    "@radix-ui/react-aspect-ratio": "^1.1.7",
+    "@radix-ui/react-avatar": "^1.1.10",
+    "@radix-ui/react-checkbox": "^1.3.3",
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@radix-ui/react-context-menu": "^2.2.16",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-hover-card": "^1.1.15",
+    "@radix-ui/react-label": "^2.1.7",
+    "@radix-ui/react-menubar": "^1.1.16",
+    "@radix-ui/react-navigation-menu": "^1.2.14",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-progress": "^1.1.7",
+    "@radix-ui/react-radio-group": "^1.3.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.7",
+    "@radix-ui/react-slider": "^1.3.6",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-toggle": "^1.1.10",
+    "@radix-ui/react-toggle-group": "^1.1.11",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "axios": "^1.12.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "embla-carousel-react": "^8.6.0",
+    "express": "^4.21.2",
+    "framer-motion": "^12.23.22",
+    "input-otp": "^1.4.2",
+    "lucide-react": "^0.453.0",
+    "nanoid": "^5.1.5",
+    "next-themes": "^0.4.6",
+    "react": "^19.2.1",
+    "react-day-picker": "^9.11.1",
+    "react-dom": "^19.2.1",
+    "react-hook-form": "^7.64.0",
+    "react-resizable-panels": "^3.0.6",
+    "recharts": "^2.15.2",
+    "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",
+    "@builder.io/vite-plugin-jsx-loc": "^0.1.1",
+    "@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",
+    "tsx": "^4.19.1",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "5.6.3",
+    "vite": "^7.1.7",
+    "vite-plugin-manus-runtime": "^0.0.58",
+    "vitest": "^2.1.4"
   }
 }

package/release/assets.js

@@ -0,0 +1,70 @@
+/**
+ * release assets create deterministic checksums, SBOM data and provenance statements.
+ * The adapter reads caller-selected artifacts and never publishes or handles credentials.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const rootpath = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Builds deterministic release metadata files for caller-selected artifacts. */
+export async function createassets(options = {}) {
+  const packagefile = resolve(options.packagefile ?? join(rootpath, "package.json"));
+  const lockfile = resolve(options.lockfile ?? join(rootpath, "package-lock.json"));
+  const output = resolve(options.output ?? join(rootpath, "build", "release"));
+  const artifactroot = resolve(options.artifactroot ?? rootpath);
+  const packagejson = JSON.parse(await readFile(packagefile, "utf8"));
+  const lockjson = JSON.parse(await readFile(lockfile, "utf8"));
+  const artifacts = [...new Set((options.artifacts ?? []).map((artifact) => resolve(String(artifact))))].sort();
+  const subjects = await Promise.all(artifacts.map(async (artifact) => ({ name: relative(artifactroot, artifact).replaceAll("\\", "/"), digest: await sha256(artifact) })));
+  await mkdir(output, { recursive: true });
+  const checksums = `${subjects.map((subject) => `${subject.digest}  ${subject.name}`).join("\n")}${subjects.length ? "\n" : ""}`;
+  const sbom = createsbom(packagejson, lockjson);
+  const provenance = createprovenance(packagejson, subjects, options);
+  const files = { checksums: join(output, "SHA256SUMS"), sbom: join(output, "sbom.cdx.json"), provenance: join(output, "provenance.intoto.jsonl") };
+  await writeFile(files.checksums, checksums);
+  await writeFile(files.sbom, `${JSON.stringify(sbom, null, 2)}\n`);
+  await writeFile(files.provenance, `${JSON.stringify(provenance)}\n`);
+  return { output, files, subjects, sbom, provenance };
+}
+
+/** Creates a compact CycloneDX component list from the root lockfile dependencies. */
+export function createsbom(packagejson, lockjson = {}) {
+  const root = lockjson.packages?.[""] ?? {};
+  const dependencies = { ...(root.dependencies ?? {}), ...(root.devDependencies ?? {}) };
+  const components = Object.keys(dependencies).map((name) => {
+    const entry = lockjson.packages?.[`node_modules/${name}`] ?? {};
+    const version = String(entry.version ?? dependencies[name]).replace(/^[^0-9]*/, "");
+    return { "bom-ref": `pkg:npm/${name}@${version}`, name, version, purl: `pkg:npm/${name}@${version}`, scope: root.devDependencies?.[name] ? "optional" : "required", type: "library" };
+  }).sort((left, right) => left.name.localeCompare(right.name));
+  return { bomFormat: "CycloneDX", specVersion: "1.5", serialNumber: `urn:uuid:${stableuuid(`${packagejson.name}@${packagejson.version}`)}`, version: 1, metadata: { component: { type: "application", name: String(packagejson.name), version: String(packagejson.version) } }, components };
+}
+
+/** Creates an in-toto statement whose subjects are the caller-selected release artifacts. */
+export function createprovenance(packagejson, subjects = [], options = {}) {
+  const normalized = subjects.map((subject) => ({ name: String(subject.name), digest: { sha256: String(subject.digest) } })).sort((left, right) => left.name.localeCompare(right.name));
+  return { _type: "https://in-toto.io/Statement/v1", subject: normalized, predicateType: "https://slsa.dev/provenance/v1", predicate: { buildDefinition: { buildType: String(options.buildtype ?? "caller-defined"), externalParameters: { package: String(packagejson.name), version: String(options.version ?? packagejson.version) }, internalParameters: {} }, runDetails: { builder: { id: String(options.builder ?? "caller-defined") }, metadata: { invocationId: stableuuid(`${packagejson.name}@${options.version ?? packagejson.version}:${normalized.map((subject) => subject.name).join(",")}`) } } } };
+}
+
+async function sha256(path) { const hash = createHash("sha256"); hash.update(await readFile(path)); return hash.digest("hex"); }
+
+function stableuuid(value) { const hex = createHash("sha256").update(String(value)).digest("hex").slice(0, 32); return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-${(8 + (Number.parseInt(hex.slice(16, 17), 16) % 4).toString(16))}${hex.slice(17, 20)}-${hex.slice(20)}`; }
+
+function parsearguments(argumentslist) {
+  const options = { artifacts: [] };
+  for (let index = 0; index < argumentslist.length; index += 1) {
+    const argument = argumentslist[index];
+    if (argument === "--output") options.output = argumentslist[++index];
+    else if (argument === "--version") options.version = argumentslist[++index];
+    else if (argument === "--artifact") options.artifacts.push(argumentslist[++index]);
+    else if (argument === "--build-type") options.buildtype = argumentslist[++index];
+    else if (argument === "--builder") options.builder = argumentslist[++index];
+    else throw new TypeError(`unsupported release asset argument: ${argument}`);
+  }
+  return options;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) createassets(parsearguments(process.argv.slice(2))).then(({ output }) => { console.log(`release assets: ${output}`); }).catch((error) => { console.error(error.message); process.exitCode = 1; });