49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
# @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`.
|