toolbox-sdk/packages/contract/README.md

@add-ideas/toolbox-contract

Typed, runtime-validated toolbox application manifests and catalogs, plus safe same-origin context discovery and URL resolution.

import {
  loadToolboxContext,
  parseToolboxApp,
} from "@add-ideas/toolbox-contract";

const app = parseToolboxApp(await response.json());
const result = await loadToolboxContext();

The package also owns the versioned same-origin browser preference contract. Use readToolboxPreferences() and writeToolboxPreferences() to share pinned apps, ordering, visibility, and light/dark/system mode with the Toolbox portal.

Applications can advertise accepted and produced formats through the optional io manifest profile, and required or optional browser features through capabilities. These fields are runtime validated while remaining compatible with existing v1 manifests. When the capability profile is present, a manifest that sets requirements.workers to true must also list "workers" in capabilities.required; progressive worker enhancements belong in capabilities.optional with the requirement set to false. Legacy v1 manifests without capabilities remain valid.

The package also provides an explicit local artifact handoff. A sender stores one or more bounded Blob objects in same-origin IndexedDB with a cryptographic, short-lived token and a target routing label. createToolboxTransferUrl() places only the opaque token in the target URL; consumeToolboxTransfer() atomically consumes it once. No file bytes are put in a URL, uploaded, or persisted after consumption. Destination URLs must remain same-origin, and descriptors, evidence, file counts, total bytes, and lifetimes are validated and bounded before storage.

All code on one origin is inside the trust boundary: same-origin scripts can open IndexedDB without using this API, so targetAppId is not authorization. Host mutually untrusted apps on distinct origins; they deliberately cannot use this transfer mechanism.

See the workspace README for the v1 document formats and full API.

The canonical schemas are also published at @add-ideas/toolbox-contract/schemas/toolbox-app.v1.schema.json and @add-ideas/toolbox-contract/schemas/toolbox-catalog.v1.schema.json.