stillmade-sdk 0.1.42 → 0.1.44

package/docs/reference/browser-applications.md

@@ -0,0 +1,267 @@
+# Experimental browser application contract
+
+# Browser application bundles — experimental source contract
+
+This is an additive source and execution-evidence contract under development.
+The exact reviewed Method Draw package has a private desktop install, editing
+and SVG export path. This does not admit arbitrary browser applications or
+make this runtime available through portable archives. Other repositories
+still require their own review and working acceptance evidence.
+
+The intended profile preserves a real built application's HTML, JavaScript,
+CSS, fonts, images and optional single-thread WebAssembly, plus a small
+Block-owned adapter. Original styling is the default. It does not rebuild the
+application UI using StillMade controls. The shared host supplies navigation,
+identity, storage authority, permissions and execution; application-specific
+behavior remains in the bundle and its independently versioned adapter.
+
+## Bundle identity and resources
+
+`defineBrowserApplication` validates a detached `desktop-browser-application/1`
+bundle. Every asset has a canonical relative path, MIME type, decoded byte count,
+SHA-256 and canonical base64 payload. Entry HTML and adapter JavaScript must be
+present. The contract rejects URL paths, path traversal, file/directory collisions,
+case collisions, unsupported file metadata, invalid encoding and changed bytes.
+`encodeBrowserApplicationFiles` accepts already-read regular-file bytes;
+filesystem importers remain responsible for rejecting links and escaping paths.
+
+Limits are explicit and independent of the older portable archive format. A
+bundle can contain at most 2,048 assets, 64 MiB per asset and 128 MiB total decoded
+bytes. Input, state and output messages remain bounded separately. Successful
+validation proves byte integrity and schema conformance, not code safety, license
+permission, dependency closure, build success or application behavior.
+
+The first profile declares no ambient networking, workers, native services or
+paid integration access. Single-thread WASM is an explicit requirement, not an
+automatic permission. Arbitrary development servers, native Node modules,
+service workers, threaded WASM and full-stack backends need distinct profiles
+and verified host capabilities. Existing SDK restrictions are not removed.
+
+The separately identified `desktop-browser-application/2` bundle may declare
+`features: {wasm:false, srcdocFrames:true}`. A trusted stage and runtime use this
+exact declaration to enable at most eight simultaneous direct `about:srcdoc`
+frames (32 over the page lifetime), with inline script needed for a preview
+document. Other frame URLs, nested frames, popups and local web workers remain
+denied. The trusted controller bootstrap runs only in the top document. This
+profile does not authorize ambient network requests or installation; exact
+source review, isolated execution and output review still apply. An authoring
+model can request it, but it cannot enable it by changing a prompt or manifest.
+
+`desktop-browser-application/3` adds `localWorkers:true` (and an explicit
+`srcdocFrames` boolean). It permits only dedicated workers whose script URL
+exactly names a bundled JavaScript asset on the application asset server. The
+target policy binds each worker to the exact parent page and browser context,
+requires a paused attachment, installs recursive target monitoring before
+resume, limits active and lifetime workers, and fails the session on an unknown
+target or unconfirmed detach. The host-controlled CSP permits same-origin
+workers and same-origin connections; the asset server serves only verified
+bundled files. The isolated job's private network namespace remains required.
+Chrome does not expose `Fetch.enable` on worker CDP sessions, so worker egress
+is enforced by the host CSP, exact local asset server and private network
+boundary, not by a worker-session Fetch interceptor. Blob, remote, shared and
+service workers remain denied. A local Chromium probe exercises the target
+policy and asset server, including a denied second loopback origin. A
+provisioned StillMade worker run and application-level review remain required.
+
+Inspect compiled dependencies as well as asset extensions. For example, a
+checked-in editor bundle may contain base64 WebAssembly or dynamically create
+workers without shipping any `.wasm` file. The current asset/declaration check
+does not prove those paths are absent. Admission must record which paths are
+needed, and the selected runtime must enforce its CSP, target and resource
+policy when code executes. A dead or explicitly unavailable feature is different
+from a verified fallback. The current development Linux worker rejects declared
+WASM; the new worker profile has not been provisioned or admitted for an
+installed Block.
+
+## Adapter lifecycle and completion
+
+An adapter needs to receive meaningful typed inputs, restore host-scoped editable
+state, checkpoint changes, export the actual result, cancel and dispose. Use
+original application APIs and controls. Keep autosave separate from explicit
+completion; mounting a UI or retaining the original input is not evidence of
+the requested transformation.
+
+For compiled applications, inspect where the original UI owns its live state.
+If that state is private to a bundled module, a bounded source edit may expose
+a data-only bridge for the Block-owned adapter. The edit must target an exact
+inspected pinned file and be rebuilt under the sealed source identity. The
+adapter should seed inputs and restore checkpoints through the original state
+path, then export the state changed by real UI actions. A global store bridge
+is not itself host storage or permission authority. Include binary project
+files or fail explicitly; silently dropping them makes saved state and export
+incomplete. Declare structured output meaning and schema so Revolver can
+distinguish a website-source project from arbitrary JSON. Browser-downloaded
+ZIP bytes are not a connected artifact until a trusted host materializer owns
+and validates them; a JSON/base64 field must not be presented as a ZIP.
+
+The candidate reviewer can perturb a primary `plain_text` input, or insert a
+valid HTML comment into a primary `html_document` input, in a fresh isolated
+session. It compares only declared text or schema-bearing structured output
+ports for the same export operation. A fixed JSON project now fails this check
+even when its original UI and save/reopen path appear to work. An arbitrary
+custom text format does not receive a guessed mutation. This diagnostic checks
+that output responds to changed input; it does not establish that the result
+has the correct application-specific meaning.
+
+When a Block receives an upstream value and also stores user edits, checkpoint
+both the editable document and the upstream value that seeded it. Reopen edits
+only when the mounted upstream value still matches; otherwise apply the new
+upstream value and rerun the original application's render path. A model must
+not treat the application's `localStorage` as the host's project or placement
+state. If rendering is debounced or asynchronous, `mount` must wait for the
+new result (or a real error) before acknowledging success, and `execute` must
+read the completed original result rather than an old preview. Runtime review
+should vary the input after a saved edit to catch stale-result replay.
+
+Exercise original export buttons under the exact runtime CSP as well as the
+declared adapter operations. Displaying SVG is weaker evidence than exporting
+PNG: embedded XHTML `foreignObject` labels can taint the canvas when that SVG
+is rasterized. An adapter may repair the original action with a bounded,
+reviewed conversion, but must compare the visible result and downloaded bytes.
+An operation that succeeds while the corresponding original control fails does
+not establish a preserved application interface. Clipboard actions require a
+separate approved capability and behavioral review.
+
+`prepareBrowserApplicationMount` binds a mount request to the exact package,
+bundle, input and state revision. A mount acknowledgement carries no outputs and
+cannot pass execution validation.
+
+`prepareBrowserApplicationExecution` additionally binds the named declared
+operation. Interactive applications require an explicitly interactive host;
+headless execution needs an implemented operation. The trusted host must issue
+the completion receipt only after the actual operation, output checks and
+current permission/state checks. `validateBrowserApplicationExecutionResult`
+and the saved-record validator check those bindings; their result explicitly
+keeps `independentlyVerified:false`. Arbitrary callers can fabricate JSON, so
+these pure helpers do not authenticate evidence or authorize adoption.
+An application package must declare at least one typed output, and each
+completed operation must actually return at least one declared output even if
+the port is optional. A nonempty value can still be semantically wrong; review
+must compare representative saved and exported results with the original app.
+
+`runBrowserApplication` requires an explicitly supplied trusted executor. It
+never falls back to evaluating source in the host or treating a mounted page as
+success. Cancellation and timeout signal the executor; actual process/resource
+termination is the executor's responsibility and needs independent verification.
+
+### Media output candidates
+
+An adapter exporting an `image` port returns actual PNG bytes as
+`{encoding:"base64",mimeType:"image/png",data:"..."}`. It must never return an
+`assetId`, `versionId`, URL or receipt of its own. The worker checks the shape
+and keeps the result an **untrusted candidate**. The host-side
+`materializeBrowserApplicationOutputs` boundary decodes and checks the image,
+writes it through trusted storage, reads back the exact bytes, checks the current
+execution revision again, and only then creates the typed image reference that
+Revolver can carry. Other media types still require materializers. The local
+worker, browser-control pipe and guest output envelope now each accept a
+bounded 4 MiB PNG after base64 encoding inside an 8 MiB frame; the session
+traffic cap is 32 MiB. Inputs and saved state retain their smaller limits.
+Large candidate transport was checked offline across those layers, while
+miniPaint's real PNG was separately decoded and materialized. A durable S3
+output adapter exists but is not wired into installed production execution.
+Installed image executions now reserve an 8 MiB aggregate maximum in the
+server-owned ledger before dispatch, under the account-wide lock. The
+reservation is compared with the account's storage-plan allotment and remains
+charged if dispatch becomes uncertain. A reservation proven never dispatched
+can be closed without consuming capacity. A completed run records verified
+stored bytes. This ledger measures application outputs separately from other
+project media; output deletion and plan-wide reconciliation still need the
+production lifecycle before enabling installed image exports.
+The desktop session now accepts a host-only `store.materializeOutputs` callback
+between isolated execution and completion. It rejects guest-minted image asset
+IDs before that callback, supplies the exact request and current authority
+binding, rechecks access afterward, and accepts only a valid typed result.
+The manager forwards this callback from trusted main-process composition; a
+real PNG was tested through decode, write, readback and receipt validation,
+including revocation after storage read. The installed HTTP host does not yet
+supply a media store, so this is a supported host boundary, not a production
+image export claim. Candidate review also lacks that store today.
+
+## Guest registration
+
+`installBrowserApplicationGuest({target,operations,messageBytes,outputBytes})` is the
+framework-neutral lifecycle dispatcher for a trusted bootstrap. It installs only
+`target.stillmadeApplication.register(adapter)` and returns a separate controller
+to that bootstrap. The host may select a larger output-only envelope up to
+8 MiB; the ordinary message limit still applies to inputs and saved state.
+It does not install a runtime or grant host access.
+
+The Block-owned adapter registers exactly these four methods once:
+
+For a new application with several export choices, each bundle operation maps
+to the output ports it actually produces, for example
+`{id:"png.export",kind:"export",outputs:["png"]}`. Ports absent from some
+operations must declare `required:false` in the shared manifest. The host
+requires every mapped operation to return exactly its listed ports before
+materializing media or committing a completion. Older bundles with only
+`{id,kind}` retain their original contract; the new mapping is additive and
+does not change published package bytes.
+
+| Method | Adapter result |
+| --- | --- |
+| `mount({inputs,state,signal})` | Restore the original UI and return exactly `{mounted:true}`. |
+| `serialize({signal})` | Return the versioned editable document as plain JSON. This is a snapshot, not output completion. |
+| `execute({operation,inputs,stateRevision,signal})` | Run a declared operation and return its raw typed output map; the dispatcher adds the `{outputs}` envelope. |
+| `dispose()` | Release adapter-owned resources. Return values are discarded. |
+
+Use closures or explicitly bound functions when application methods depend on
+their original receiver. The controller enforces mounting before serialization
+or execution, one active call, exact mounted inputs, declared operation names,
+bounded plain JSON, and rejection of guest receipt fields. Cancellation discards
+late results and leaves the guest usable only for disposal. Disposal itself is
+cooperative; a hung application must be terminated by the trusted host.
+
+The dispatcher is self-contained for inclusion in a reviewed bootstrap. Its
+JavaScript object checks are correctness checks inside an untrusted realm, not
+security boundaries. The host must revalidate every message, own checkpoint
+identity and UI-event sequencing, issue receipts, check current permissions,
+persist revisions and enforce resource limits outside the guest. No account
+token, filesystem access, native proxy or generic network function is exposed.
+
+## Runtime gates still required
+
+- Serve only exact verified bundle assets. Keep application sessions isolated
+  from host origin, cookies, local files, native IPC, credentials and one another.
+- Enforce navigation, external request and device denial. A sandboxed iframe,
+  request interceptor or CSP alone does not establish complete egress denial.
+- Keep the host responsive under infinite JavaScript/WASM loops and memory
+  pressure. Resource and cancellation enforcement must live outside the guest.
+- Scope persistence to account/project/placement and exact source. Shared state
+  needs permission checks, revision conflicts, recovery and flush-on-completion;
+  origin-global `localStorage` cannot establish that contract.
+- Build in a disposable secret-free worker with pinned dependencies, bounded
+  resources and no unrestricted network during source execution. Preserve
+  licenses, binary assets and exact output identities.
+- Run original UI operations and compare upstream/adapted exports. Then prove
+  a real producer → application → consumer chain, save/reopen, two placements,
+  cancellation, revocation, stale-result rejection and adversarial isolation.
+
+Method Draw is being used to study the first complete static editor route.
+Its remote fonts, global localStorage and SVG import behavior require explicit
+adaptation; an original-page baseline is not a completed Block integration.
+
+The worker now has a separate **candidate-review** stage identity for an
+unlisted, digest-verified browser package. Its driver and unit entry are selected
+by trusted code, while the installed supervisor and runner retain the exact
+reviewed-source registry. This is the source boundary needed to test generated
+adapters without editing a per-repository allowlist. A root-owned review
+supervisor, complete behavior gate, and admission-to-install handoff are still
+missing; staging a candidate does not run or install it.
+
+## Reproduce the reviewed package outside the repository
+
+The downloadable SDK zip includes `packages/block-sdk/browser-application.js`
+and `browser-application-execution.js`. The Method Draw source folder contains
+its own pinned upstream bytes, adapter, source hashes and package builder. With
+Node.js 22 or later, extract the SDK zip, place the complete Method Draw folder
+at `blocks/repository/methoddraw` inside the extracted directory, and run:
+
+```sh
+node --input-type=module -e 'import {buildMethodDrawPackage} from "./blocks/repository/methoddraw/build-package.mjs"; import {digest} from "./packages/block-sdk/contracts.js"; const source=await buildMethodDrawPackage(); console.log(await digest(source));'
+```
+
+For the reviewed source and SDK 0.1.0 archive the digest is
+`084ed75a82a66011344bcb609a12de018ccb4e20b828fabc2afef60399c5f6eb`.
+This reproduces source packaging only. It does not execute the editor, grant
+private installation, or show that a different GitHub repository is eligible.

package/docs/reference/capabilities.md

@@ -0,0 +1,45 @@
+# Runtime capabilities
+
+## Supported execution
+| Capability | SDK 0.1.0 |
+| --- | --- |
+| Declarative recipes | Supported; bounded allowlisted operations |
+| Standalone JavaScript | Supported in isolated QuickJS |
+| Hosted text.generate | Exact model, account BYOK or credits, and explicit run review |
+| Hosted audio.speech | One short text/script input to measured audio in any StillMade catalog voice (Deepgram, ElevenLabs, OpenAI, Kokoro) with credits, or OpenAI with your key; playback review; accepted project recordings can be explicitly added to Editor audio |
+| Hosted audio.transcribe | One owner-scoped stored audio asset to reviewed text and ordered word timings with StillMade transcription on credits, or OpenAI Whisper with your key |
+| Hosted audio.music | One prompt to generated music (5–240 seconds) with StillMade credits and playback review |
+| Hosted audio.sfx | One prompt to a generated sound effect (0.5–22 seconds) with StillMade credits and playback review |
+| Hosted image.generate | One prompt and optional reference images to a stored PNG with any catalog image model and its settings; StillMade credits or account key, and actual image review |
+| Hosted video.generate | One prompt and optional first/last frames to a measured stored video clip with any catalog video model and its settings; StillMade credits and actual video review |
+| Hosted image.describe | One to four owned images to bounded production notes; host-selected model/payment and actual description review |
+| Hosted media.analyze | One owned video (optionally one time range), image or up to four images to structured visual evidence: summary, timeline, observations, on-screen text and issues, with StillMade credits; detail "check" gives one to four photos a short answer each at one price per call |
+| Hosted web.fetch | One public web page read by the host and answered against the Block's instruction, with StillMade credits; no cookies, keys or private addresses |
+| Hosted web.research | One topic searched on the web and summarized with cited sources, with StillMade credits |
+| Hosted timeline.propose | Bounded typed context to strict timeline-edit JSON; host-selected model/payment, stale-before checks, preview and Apply |
+| Hosted workspace.propose | Bounded typed context to a strict workspace-edit proposal for one permitted workspace; preview and explicit Apply |
+| Hosted connection.execute | One reviewed action on a connected third-party app account through the host connection service; the Block never receives account credentials |
+| Typed inputs, outputs, semantic roles | Supported |
+| Schema-driven controls | Supported |
+| Scoped project context snapshots | Supported in Step workspaces |
+| Conditional SDK Steps | Supported with a compatible pass-through output |
+| Current-media batches | Supported for saved Canvas, panel/board, voiceover and editor media |
+| Future saved media | Supported with owner confirmation and the configured host worker |
+| Host editor and generation tools | Existing built-in Blocks; normal host controls and permissions |
+| Python, npm dependencies, shell, arbitrary native code | Not exposed to external packages |
+| Package-supplied React workspace UI | Not exposed |
+| Direct guest network, filesystem, or secrets | Not exposed |
+| ComfyUI execution adapter | Reviewed core image nodes with explicit account connection and remote tests |
+| Marketplace payments and seller onboarding | Not available; Blocks and Project Types are free |
+
+## Choose the boundary
+Implement deterministic text or pixel transformations with recipes or JavaScript. Use [hosted text](../build/hosted-text.md), [hosted speech](../build/hosted-speech.md), [hosted music and sound effects](../build/hosted-music.md), [hosted images](../build/hosted-images.md), or [image description](../build/image-description.md) for those specific reviewed requests. Accepted project speech can be [added to Editor audio](../build/audio-to-editor.md) through the host controls. Native Voiceover master recordings, takes, transcripts, and its primary script input retain their existing behavior. A runtime label or permission declaration does not create an unavailable host API.
+
+## ComfyUI and external backends
+The Block contract is independent of the execution backend. The reviewed adapter runs bounded core-image workflows using an explicit account connection. It supports reviewed core image generation using an already-installed safetensors checkpoint. It cannot install dependencies or run custom Python nodes. See [ComfyUI Blocks](../build/comfyui.md) for package structure, fixture expectations, import review and current limits. Imported source is never loaded as host code.
+
+## Environment differences
+The same portable Block can run in web, macOS, and Windows hosts. Desktop media and export features belong to the host capability bridge; a guest still receives bounded input data and no unrestricted disk access.
+
+## Limits
+JavaScript runs have a 500 ms guest deadline, 16 MiB heap, 512 KiB stack, 256 KiB source ceiling, and 4 MiB serialized input/output budgets. Recipes permit at most 64 operations. See [JavaScript](../build/javascript.md), [media](../build/media.md), and [automation](../project-types/automation.md) for the additional host limits.

package/docs/reference/cli.md

@@ -0,0 +1,71 @@
+# CLI reference
+
+## Run commands
+```sh
+npx stillmade-block <command> <target> [argument] [options]
+```
+That is the form after `npm install --save-dev stillmade-sdk`. From a downloaded SDK folder, run `node packages/block-cli/cli.js <command> …` instead. Output is a JSON object when it is piped, which is what coding agents read; `--text` prints readable text and `--json` forces JSON. Targets can be authoring folders or packed files, except where a command creates a new target. `--help` prints this list.
+
+| Command | Argument | Behavior |
+| --- | --- | --- |
+| create ./folder | A template (create --list shows them); omit for the text recipe | Write a complete folder: manifest, source, fixtures, a README and, where needed, tests/mocks.json and package.json |
+| create-type ./type.json | None | Write an editable connected Project Type example |
+| validate target | Optional --mobile | Check the contract without executing behavior; --mobile adds the 320-pixel phone layout profile to the report |
+| inspect target | None | Print manifest/runtime or workflow support |
+| test target | Optional --mock | Execute fixtures and return the report; --mock (or a tests/mocks.json file) answers hosted calls with [stand-ins](../build/testing.md) |
+| run target | Optional input.json, --mock; Blocks also accept --state file and --save-state new-file | Execute once and print the outputs (preview is the same command) |
+| dev folder | Optional --port 4800, --build "npm run build", and --live (with --site) to review each saved version in your StillMade account | [Preview the interface with hot reload](../build/local-preview.md) |
+| ready target | None | Run the [Block builder contract](../build/block-builder-contract.md) readiness check: fixtures, bad input, cancellation, reopen, composition with real catalog Blocks; exits non-zero when FAILED or BLOCKED |
+| gate folder | None | Run ready on every new or edited Block under the folder; a Block is not ready until it passes. Name the Block's own folder: `gate .` in a folder that also holds the extracted SDK checks the SDK's examples too |
+| pack target | Optional output path. A module Block (or a frame view with src/view-files/) writes `<id>-<version>.stillmade-module.json`, other runtimes `<id>-<version>.stillmade.json`; --original with an output.stillmade-block path writes an archive of your own recipe, JavaScript, capability or ComfyUI code and refuses a module Block | Require passing tests, then write the file to import |
+| remix target | Optional output path | Write an editable draft copy with retained license and pinned lineage; nothing is executed |
+
+## Templates
+| Template | Runtime | Starts |
+| --- | --- | --- |
+| recipe | recipe | Clean up text with built-in steps; no code. |
+| image | recipe | Thicken the lines of an image with built-in image steps. |
+| javascript | javascript | Count words with a few lines of sandboxed JavaScript. |
+| stateful | recipe | Number takes with memory saved between runs. |
+| module | module | Modern JavaScript (ES modules, async, typed arrays) in a Worker. |
+| module-wasm | module | A module that runs WebAssembly shipped beside its code. |
+| module-hosted | module | A module that calls hosted text and image generation as tools. |
+| view-react | module | A React interface (frame view) on a module Block, bundled with esbuild. |
+| view-html | javascript | An interface in plain HTML, CSS and JavaScript; no build step. |
+| text | capability | Hosted text generation (text.generate) on the person's credits. |
+| image-generate | capability | Hosted image generation with any catalog model. |
+| video-generate | capability | Hosted video generation with any catalog model. |
+| speech | capability | Hosted speech (audio.speech) with any catalog voice. |
+| music | capability | Hosted music generation (audio.music). |
+| sfx | capability | Hosted sound effects (audio.sfx). |
+| transcribe | capability | Hosted transcription with word timings (audio.transcribe). |
+| describe-image | capability | Describe or compare up to four images (image.describe) on the person's own OpenRouter key; analyze-media runs on StillMade credits. |
+| analyze-media | capability | Visual evidence from images or a video (media.analyze). |
+| web-fetch | capability | Answer a question from one web page (web.fetch). |
+| web-research | capability | Research a topic with sources (web.research). |
+| timeline-proposal | capability | Propose Editor timeline edits the person reviews (timeline.propose). |
+| outside-api | module | Call an outside https API with the person's own key (net.fetch). |
+| connection | module | Call a published OpenAPI adapter with the person's sign-in. |
+| storage | module | Remember values across runs in the project's Block storage. |
+| trigger-media | capability | Runs on its own when a video is saved (media.saved trigger). |
+| trigger-webhook | javascript | Runs when another service sends a webhook. |
+| trigger-schedule | javascript | Runs on a schedule with the project's saved inputs. |
+
+## Exit and output contract
+In a terminal, success prints a readable summary and exits with code 0, and failure prints the error (with failed fixtures and a hint) to stderr and exits nonzero. When output is piped (scripts, coding agents) or with `--json`, success prints the JSON result object and failure prints a JSON object with error, optional code and report; `--text` forces readable text. create, create-type, pack and --save-state refuse to overwrite existing files.
+
+## Examples
+```sh
+node packages/block-cli/cli.js create --list
+node packages/block-cli/cli.js create ./outlines image
+node packages/block-cli/cli.js test ./outlines
+node packages/block-cli/cli.js dev ./outlines
+node packages/block-cli/cli.js pack ./outlines outlines-1.0.0.stillmade.json
+node packages/block-cli/cli.js create ./narration speech
+node packages/block-cli/cli.js test ./narration --mock
+node packages/block-cli/cli.js create-type ./workflow.json
+node packages/block-cli/cli.js preview ./workflow.json
+```
+
+## Importable formats
+The CLI emits JSON (and `.stillmade-module.json` bundles for module Blocks), while StillMade also accepts reviewed ZIP source directories. Files outside the supported manifest, source, and fixture layout are not installed as executable dependencies.

package/docs/reference/connection-api.md

@@ -0,0 +1,59 @@
+# Connection API
+
+## Connection client operations
+`createConnectionClient({request})` exposes exactly these operations. The authenticated host supplies `request`; Block code receives neither credentials nor an arbitrary network proxy. Paths are relative to the connections API.
+
+| Operation | Method | Path | Query |
+| --- | --- | --- | --- |
+| `search` | GET | `/catalog` | `q`, `refresh` |
+| `capabilities` | GET | `/capabilities` | `appId` |
+| `block` | GET | `/block` | `appId`, `capabilityId`, `projectId`, `configurationRunId`, `metadataOnly` |
+| `accounts` | GET | `/accounts` | `appId`, `refresh` |
+| `connect` | POST | `/sessions` | — |
+| `finishConnection` | POST | `/sessions/:id/finish` | — |
+| `revokeAccount` | POST | `/accounts/:id/revoke` | — |
+| `accountImpact` | GET | `/accounts/:id/impact` | — |
+| `inspect` | POST | `/execution-context` | — |
+| `quote` | POST | `/reviews` | — |
+| `approve` | POST | `/reviews/:id/approve` | — |
+| `execute` | POST | `/runs` | — |
+| `run` | GET | `/runs/:id` | — |
+| `recover` | GET | `/requests/:id` | — |
+| `cancel` | POST | `/runs/:id/cancel` | — |
+| `referenceBudget` | POST | `/reference-budgets` | — |
+| `closeReferenceBudget` | POST | `/reference-budgets/:id/close` | — |
+| `previewReference` | POST | `/references/preview` | — |
+| `attachReference` | POST | `/references` | — |
+| `readReference` | GET | `/references/:id` | `projectId`, `version` |
+| `refreshReferenceContext` | POST | `/references/:id/refresh-context` | — |
+| `refreshReference` | POST | `/references/:id/refresh` | — |
+| `detachReference` | POST | `/references/:id/detach` | — |
+| `referenceDependencies` | GET | `/references/dependencies` | `projectId` |
+| `sharedWork` | POST | `/shared-work` | — |
+| `sharedWorkLinks` | GET | `/shared-work-links` | `projectId` |
+| `inspectGenerated` | POST | `/generated/inspect` | — |
+| `testGenerated` | POST | `/generated/test` | — |
+| `installGenerated` | POST | `/generated/install` | — |
+| `readGenerated` | GET | `/generated/:id` | — |
+| `installLocal` | POST | `/generated/local/install` | — |
+| `previewLocalReference` | POST | `/references/local/preview` | — |
+| `attachLocalReference` | POST | `/references/local` | — |
+| `localReferenceSource` | POST | `/references/local/source` | — |
+| `refreshLocalReference` | POST | `/references/:id/local-refresh` | — |
+| `recentRuns` | GET | `/runs` | `projectId`, `limit` |
+| `placementTasks` | POST | `/placements/tasks` | — |
+| `previewPlacementTask` | POST | `/placements/preview-task` | — |
+| `applyPlacementTask` | POST | `/placements/apply-task` | — |
+| `listTriggers` | GET | `/workflow-triggers/:projectId` | — |
+| `previewTriggerPlan` | POST | `/workflow-triggers/:projectId/plan` | — |
+| `reviewTrigger` | POST | `/workflow-triggers/:projectId/review` | — |
+| `createTrigger` | POST | `/workflow-triggers/:projectId` | — |
+| `changeTrigger` | POST | `/workflow-triggers/:projectId/triggers/:id/state` | — |
+| `fireManualTrigger` | POST | `/workflow-triggers/:projectId/triggers/:id/fire` | — |
+| `listUnattendedGrants` | GET | `/workflow-triggers/:projectId/grants` | — |
+| `createUnattendedGrant` | POST | `/workflow-triggers/:projectId/grants` | — |
+| `revokeUnattendedGrant` | POST | `/workflow-triggers/:projectId/grants/:id/revoke` | — |
+| `executeUnattendedGrant` | POST | `/workflow-triggers/:projectId/grants/execute` | — |
+| `listLiveReferenceGrants` | GET | `/workflow-triggers/:projectId/live-reference-grants` | — |
+| `grantLiveReference` | POST | `/workflow-triggers/:projectId/live-reference-grants` | — |
+| `revokeLiveReferenceGrant` | POST | `/workflow-triggers/:projectId/live-reference-grants/revoke` | — |

package/docs/reference/cooperative-jobs.md

@@ -0,0 +1,13 @@
+# Cooperative JavaScript jobs
+
+# Bounded guest-returned pending jobs
+
+Original §53 requires Blocks to return pending jobs with automatic queued/loading/running/progress/complete/failed/cancel handling. JavaScript Blocks can now opt into `manifest.jobs={kind:'cooperative',version:1}` and return `job.pending` from their sandboxed code. This is an actual guest-returned continuation protocol consumed by the host, not merely a promise around synchronous final outputs.
+
+The opt-in reserves input/state/job arguments. Legacy packages retain their old invocation shape. Each pending return is a strict JSON envelope; continuation data has no authority. The same pinned code and original inputs resume in the same disposable VM for up to 32 turns. CPU time remains cumulative 500 ms across VM evaluations; heap/WASM limits remain 16/32 MiB; serialized continuation, state and final outputs together are bounded by 4 MiB. The host yields between turns but never extends existing browser/Node worker deadlines. Each pending state remains private until a final valid result; cancelled or failed runs publish no intermediate output/state.
+
+Progress contains only validated turn/unit counters. Node and browser worker transports validate ordered continuation messages separately from final results; the host job handle validates them again. Omitted progress shows a pending turn, not guessed completion. The UI labels declared continuation units separately from recipe operations. Terminal cancellation remains one-shot and stops the original worker; it cannot restart an invocation or dispatch a provider. Export archives include the runtime helper, and portable SDK documentation describes the API and bounds.
+
+The visual authoring checkbox enables the protocol; source code defines its actual continuation behavior. Existing preview, connected and import sample surfaces share the resulting status/cancellation UI. External asynchronous jobs, arbitrary polling URLs, timers inside the guest, network permissions, provider dispatch and durable reload recovery are not introduced. Reload durability is not inferred as a requirement from §53.
+
+Source inspection only: no tests, browser QA, verification builds, migrations or provider calls were performed. Implementation was committed locally without push or deployment. Operational/runtime acceptance remains unverified.