# @add-ideas/toolbox-contract

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

```ts
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](https://git.add-ideas.de/lotobo/toolbox-sdk#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`.