@zamery/browser-provider

Provider-neutral TypeScript contracts for browser integrations.

This is the foundation package for Zamery Browser. It defines BrowserProvider V1 and the additive BrowserProvider V2 contract without depending on Pi, Firefox, Zamery Workbench, or any concrete automation engine.

Install

npm install @zamery/browser-provider

What it gives you

• A stable provider-neutral browser contract.
• Explicit browser/provider session identity.
• Freshness and provenance semantics for semantic snapshots.
• Declared vs observed action semantics.
• Validated action receipts that preserve ambiguous outcomes instead of converting them into success.
• Side-by-side V1/V2 contracts so protocol evolution is explicit.
• Optional, independently versioned interfaces with structural type guards: BrowserAttentionProviderV1 (bounded user-attention requests that never grant authority), BrowserAuthorizationProviderV1, BrowserControlProviderV1 (claim / hand-off / mutation status), BrowserTabProviderV1, BrowserTabGroupProviderV1 and BrowserArtifactProviderV1 (bounded screenshots). V2 stays the core contract; these never widen its enums.
• Optional BrowserAssetProviderV1 contracts for bounded, opaque browser-backed asset discovery and transfer without exposing source URLs or credentials.

Example

import {
  BROWSER_PROVIDER_V2,
  type BrowserProviderV2,
} from "@zamery/browser-provider";

function acceptsV2(provider: BrowserProviderV2): boolean {
  return provider.protocolVersion === BROWSER_PROVIDER_V2;
}

A concrete provider can expose createBrowserProvider(options) for the stable V1 path and createBrowserProviderV2(options) for V2-aware consumers.

Compatibility

• Node.js >=22.19.0 <25.
• BrowserProvider protocol revisions are separate from npm package semver.
• V1 remains available; V2 does not silently reinterpret V1 behavior.

Related packages

• @zamery/pi-browser — typed Pi browser tools backed by a BrowserProvider.
• @zamery/browser-firefox — Firefox implementation for an already-running browser.

Versioning while 0.x

Patch releases preserve exported runtime/TypeScript semantics. Minor releases may add APIs. Intentional breaking API or semantic changes are called out with migration notes even before 1.0.

License

Apache-2.0.