stillmade-sdk 0.1.42 → 0.1.44

package/docs/reference/desktop-capabilities.md

@@ -0,0 +1,172 @@
+# Desktop capabilities
+
+# Desktop capabilities for Blocks
+
+Recording and folders run on both platforms: in a browser the trusted web host records with the browser's own screen, camera or microphone picker and keeps the finished file on the device (a `sm-media://device/...` reference), and shares folders through the browser's folder picker (Chrome and Edge); in StillMade Desktop the native host does both. Every other scope below needs StillMade Desktop.
+
+**Consent is the person's own action.** A Block reaches only what it declares, and StillMade refuses everything else, so people are never asked to judge a Block. Picking a folder or files in the system dialog, or pressing StillMade's Start button for a recording or live feed, is the consent: there is no second "Allow?" question. Notifications and keeping the computer awake need no question. StillMade asks once only about what happens without such an action: reading the clipboard or the cursor, replacing the clipboard, and running a desktop program. An OS prompt may follow the first use of the camera or microphone. Importing a Block, installing StillMade or opening a preview asks nothing. Imported UI receives neither native IPC nor grant tokens.
+
+**What a person allows is remembered for the exact Block where it is used**: their account, the project Step, and the exact package (its digest). Picked folders and answered questions carry over to the next session and the next launch, in StillMade Desktop and in the browser. Any other package starts with nothing, including a new version of the Block, another Block in the same Step, or a Block from another author that reuses the same id. Remembered access ends when:
+- the Step's Block changes: an update, or another Block put in its place (it picks or answers again, once);
+- StillMade quarantines the Block;
+- the person forgets it: **Stop sharing** under the Block, or **Forget** in Desktop access.
+
+Under every Block that uses device features, **What this Block did** lists the folders it uses and what it read, wrote, copied or ran on this device. The Block cannot read or hide it.
+
+Declare the exact required scopes in `manifest.permissions.desktop`. Other permission families remain unchanged. Pure recipe/JavaScript execution stays sandboxed; the **Block UI bridge** requests desktop operations through the trusted host.
+
+| Scope | UI operation | Behavior |
+| --- | --- | --- |
+| `screen.capture` | `record.start`, `{kind:"screen"}` | Choose a screen or window, then record it. Browser and desktop. |
+| `cursor.track` | `cursor.track`, or `{cursor:true}` on `record.start` | Global cursor coordinates and display geometry; recordings sample at 10 Hz. Does not monitor clicks or keyboard input. |
+| `camera.capture` | `record.start`, `{kind:"camera"}`; `live.start`, `{camera:true}` | Camera recording, or the live camera feed, after device/OS approval. Browser and desktop. |
+| `microphone.capture` | `record.start`, `{kind:"microphone"}`, or `{kind:"screen", microphone:true}`; `live.start`, `{microphone:true}` | Microphone recording after device/OS approval, the microphone mixed into a screen recording, or the live microphone feed. Browser and desktop. |
+| `clipboard.read` | `clipboard.read` | Returns `{text}`; bounded to 100,000 characters. |
+| `clipboard.write` | `clipboard.write`, `{text}` | Explicit permission to replace clipboard text. |
+| `media.pick` | `media.pick` | Native picker returns `{assets}` for up to 20 selected media files; no arbitrary path access. |
+| `notifications.show` | `notifications.show`, `{body}` | StillMade/Block-branded desktop notification; maximum one every ten seconds. |
+| `power.keep-awake` | `power.keep-awake`, `{enabled:true}` | Prevent app suspension until disabled, revoked, closed, or expired. |
+| `native.tools` | `tool.status` and declared `tool.*` operations | Use one exact versioned adapter for an approved installed desktop application. |
+| `folder.read` | `folder.pick`, `folder.shared`, `folder.list`, `folder.read`, `folder.forget` | List and read files in a folder the person picks. The Block gets an opaque folder id and names files by relative paths. Desktop, and Chrome and Edge. |
+| `folder.write` | `folder.pick`, `{write:true}`; `folder.write` | Create and replace files in a folder the person shared for changing. Declare `folder.read` too. Desktop, and Chrome and Edge. |
+
+The host always checks declarations. Declaring a scope does not grant it. For anything but recording, a browser receives a clear desktop-required error; there is no silent paid/cloud fallback. A Block whose only desktop scopes are recording scopes is not marked as requiring StillMade Desktop.
+
+## Approved native desktop tools
+
+Native applications use a separate allowlisted adapter contract. The Block stays an ordinary sandboxed SDK package and must declare both `permissions.desktop:["native.tools"]` and a desktop-only platform matrix. `manifest.desktopTools` pins the exact adapter version and actions. A Block cannot supply an executable, command, path, environment variable, installer, or additional argument.
+
+Natron adapter version 1 currently exposes `launch`, `project.import`, `project.open`, and `project.render`. Project import copies one user-selected `.ntp` file into that Block version's workspace and returns an opaque project ID. Open accepts only that opaque ID or `latest`. Render accepts a locally authorized StillMade video, bounded Reader/Writer node names, and a frame range of at most 10,001 frames. The trusted host invokes `NatronRenderer` with only the pinned project, `-i`, `-w`, host-resolved input/output paths, and the bounded range. It never accepts Natron's Python/interpreter flags or a Block-supplied path. The completed render is imported into the StillMade media library and returned as a typed video asset.
+
+```json
+{
+  "platforms":{"phone":{"supported":false,"reason":"Requires Natron and StillMade Desktop."},"browser":{"supported":false,"reason":"Requires Natron and StillMade Desktop."},"desktop":{"supported":true}},
+  "permissions":{"project":[],"network":[],"filesystem":[],"secrets":[],"desktop":["native.tools","media.pick"]},
+  "desktopTools":[{"id":"org.natron.Natron","adapterVersion":1,"actions":["launch","project.import","project.open","project.render"]}]
+}
+```
+
+The mapped Natron Block uses `video` as both its primary typed input and output, with semantic `video`. This allows an explicit Project Type chain such as video producer → Natron → review/export Block. Its custom interface submits the connected original input and render settings to `StillMade.run`; the approved desktop executor invokes the renderer and returns the newly registered artifact with a bound native receipt. Source fixtures and JavaScript passthrough do not prove native execution. See [Native desktop execution](DESKTOP_EXECUTION.md) for `src/desktop.json`, offline admission, host callbacks and retained-result requirements.
+
+## Folders you choose
+
+A Block that works on a person's files (a photo culler, a subtitle batch, a project exporter) asks for one folder at a time. The person picks it in the system folder dialog (StillMade Desktop) or the browser's folder picker (Chrome and Edge); the Block never sees a path and reaches nothing outside that folder. The folder is remembered for the Block where it is used, so start with the folders it already has:
+
+```js
+let [folder] = (await StillMade.desktop('folder.shared')).folders;
+if (!folder) ({folder} = await StillMade.desktop('folder.pick', {write: true}));
+const {entries} = await StillMade.desktop('folder.list', {folder: folder.id, path: 'raw'});
+const {text} = await StillMade.desktop('folder.read', {folder: folder.id, path: 'notes.txt'});
+const {asset} = await StillMade.desktop('folder.read', {folder: folder.id, path: 'raw/a.png', as: 'media'});
+await StillMade.desktop('folder.write', {folder: folder.id, path: 'edits/notes.txt', text: 'Take two'});
+await StillMade.desktop('folder.write', {folder: folder.id, path: 'cover.png', asset, replace: true});
+```
+
+- `folder.pick` returns `{folder: {id, name, write}}`. `{write:true}` asks to share it for changing, and needs `folder.write`; the picker says which. Picking a folder already shared keeps its id. In a browser, call it from a click in the Block: Chrome opens its picker only after one, and otherwise StillMade shows its own Choose folder button first.
+- `folder.shared` returns `{folders: [{id, name, write}]}`: the folders this Block already has here, kept from earlier sessions. `folder.forget` with `{folder}` stops using one.
+- `folder.list` returns `{entries: [{name, kind, size, modified}], truncated}`, folders first, at most 1,000 entries. Links are left out.
+- `folder.read` returns `{text, size}` for a text file up to 1 MB, or `{asset, size}` with `as: "media"` for an image, video or audio file: on Desktop the file becomes a saved desktop asset; in a browser it stays on the device, linked where it sits (`sm-media://device/...`). Either way the Block can show it, pass it to `StillMade.run` or return it.
+- `folder.write` takes `text` (up to 1 MB) or `asset`, a media value this Block saved, read or received in this session. Missing folders on the path are created. An existing file is replaced only with `replace: true`. The file is written beside its destination first and moved into place, so a failed write leaves no partial file.
+- Paths are relative, separated by `/`, at most 32 levels and 1,024 characters. `..`, `.`, absolute paths, drive letters, backslashes, names with leading or trailing spaces or a trailing dot, reserved Windows names (`CON`, `NUL`) and Windows short names (`GIT~1`) are refused. On Desktop, hidden-file checks also run on the resolved path, a symbolic link anywhere on the path is refused rather than followed, and every resolved path is checked to be inside the folder. A browser does not show links or the folders above the picked one; Chrome itself refuses system folders and the home folder.
+- Hidden files and folders (names starting with `.`, such as `.git`, `.env`, `.vscode` or a shell profile) are left out of lists and cannot be read or written.
+- `folder.write` creates and replaces only media, subtitle, plain-text and table files: images (`png`, `jpg`, `webp`, `tiff`, `exr`, `psd` and similar), video (`mp4`, `mov`, `webm`, `mkv`, `mxf` and similar), audio (`mp3`, `wav`, `m4a`, `flac` and similar), `txt`, `srt`, `vtt`, `ass`, `csv`, `tsv`, `edl`, `otio`, `cube` and `pdf`. Structured data goes in a file named `<name>.stillmade.json`. Other `.json` and `.md` files are not written, because tools and coding agents read names like `package.json` or `CLAUDE.md` as settings or instructions; nor are programs, scripts, shortcuts, disk images, macro documents, build files such as `CMakeLists.txt`, or anything inside a macOS bundle such as `Name.app`. This is an allowlist: a type it does not name, including a lookalike written with other characters, is refused. Written files are never executable.
+- The person cannot pick a whole drive, their home folder or a folder above it. A folder shared for changing also cannot be hidden, inside application settings (`AppData`, `Library`) or inside a code repository (a folder with `.git` at or above it on Desktop, inside it in a browser); those can still be shared for reading. Every write checks again, so a repository created inside the folder later stops writes into it.
+- A Block holds at most four folders. They are remembered for the exact Block where it is used until the person stops sharing them (under the Block, or in Desktop access), the Step's Block changes, or StillMade quarantines it. On Desktop each remembered folder is checked again before use: one that was moved, replaced by a link or turned into a repository is dropped. In a browser, Chrome may ask once to allow a remembered folder again after it restarts, or keep it for good with "Allow on every visit".
+- Nothing deletes or renames files. In a read-only workspace a folder can be picked for reading, listed and read; picking one for changing and `folder.write` need edit access.
+
+## Live camera and microphone
+
+A view can use the camera, the microphone or both as they happen instead of a
+finished recording: a live filter, a tuner, a level meter, a pose or gesture
+check, live captions. It declares the same scopes as recording and uses
+`StillMade.live` (standard and frame views, browsers and StillMade Desktop):
+
+```js
+const canvas = document.getElementById('picture'), context = canvas.getContext('2d');
+StillMade.live.onFrame((frame, info) => {           // an ImageBitmap, info.width x info.height
+  canvas.width = info.width; canvas.height = info.height;
+  context.drawImage(frame, 0, 0);                    // draw or copy it now: it is closed afterwards
+});
+StillMade.live.onAudio((samples, info) => {         // mono Float32Array, info.sampleRate
+  meter.value = Math.max(...samples.map(Math.abs));
+});
+StillMade.live.onEnd(event => { status.textContent = 'Camera off'; });  // event.reason
+document.getElementById('start').addEventListener('click', () =>
+  StillMade.live.start({ camera: true, microphone: true, fps: 15, width: 640, sampleRate: 16000 }));
+```
+
+- `live.start` resolves with `{live, camera, microphone, fps, width, height, sampleRate}`
+  once the person presses Start in StillMade, in a browser and in StillMade
+  Desktop. `fps` is 1 to 30 (default 15), `width` 160 to 1280
+  pixels (default 640, never wider than the camera), `sampleRate` 8000 to 48000
+  (default 16000; a browser that cannot resample reports its own rate in each chunk).
+- The view never holds the camera or microphone. StillMade keeps the stream,
+  shows that the device is on with a Turn off button, and posts transferred
+  copies: one `ImageBitmap` per frame and one 4,096-sample `Float32Array` per
+  audio chunk. At most two frames are unanswered at a time, so a slow view
+  receives fewer frames, never a backlog.
+- `live.stop()` (or Turn off, closing the Block, or revoking access)
+  ends the feed; `onEnd` receives the reason (`stopped`, `person`, `closed`,
+  `ended` when the device stops, `time`). Nothing is recorded or saved.
+- A recording and a live feed do not run at the same time. `live.stop` and
+  `live.status` work in a read-only workspace; `live.start` needs edit access.
+- For heavy processing of frames (a WebAssembly model), copy what you need
+  (`getImageData`, `createImageBitmap(frame)`) and hand it to a Worker in a frame view,
+  or to the Block's runtime with `StillMade.run`.
+
+## Ready-to-import recording Blocks
+
+Download the complete [Screen recorder](https://stillmade.shop/block-sdk/examples/screen-recorder.stillmade.json), [Camera recorder](https://stillmade.shop/block-sdk/examples/camera-recorder.stillmade.json), or [Microphone recorder](https://stillmade.shop/block-sdk/examples/microphone-recorder.stillmade.json). These packages also ship in the SDK archive. Import one through StillMade’s normal review flow, then use it in a browser or in the desktop app. Each includes a themed interface and pure runtime fixtures that preserve the media reference. The fixtures use synthetic references; they do not exercise your device.
+
+The interface saves recording media before sending it through the runtime. If that handoff fails, Retry uses the saved recording without recording again.
+
+## Recording example
+
+Manifest fragment:
+
+```json
+{"permissions":{"project":[],"network":[],"filesystem":[],"secrets":[],"desktop":["screen.capture","cursor.track"]}}
+```
+
+`record.start` takes `{kind, microphone, systemAudio, resolution, frameRate, cursor}`: `kind` is `screen` (default), `camera` or `microphone`; `microphone:true` mixes the microphone into a screen recording (declare `microphone.capture` too); `systemAudio:true` asks for the shared audio (Windows loopback on desktop, the browser's own share-audio option in a browser; when audio is refused the capture continues without it); `resolution` is `1080p` (default) or `source`; `frameRate` defaults to 30; `cursor:true` needs StillMade Desktop. It resolves to `{recording, kind, microphone, mimeType, width, height, limits}`. `record.status` answers at any time with `{active, platform, kind, elapsed, bytes, ended, stoppedBy, message, limits}` so a view can show a timer and what is left.
+
+Inside your validated `view.javascript`, attach explicit start/stop controls:
+
+```js
+const start = document.getElementById('start');
+const stop = document.getElementById('stop');
+const status = document.getElementById('status');
+start.addEventListener('click', async () => {
+  try {
+    await StillMade.desktop('record.start', {kind:'screen', cursor:true});
+    status.textContent = 'Recording. Press Stop when finished.';
+  } catch (error) { status.textContent = error.message; }
+});
+stop.addEventListener('click', async () => {
+  try {
+    const result = await StillMade.desktop('record.stop');
+    // Declare matching video and metadata inputs in the Block manifest.
+    // Your sandboxed runtime can pass these through as typed outputs.
+    await StillMade.run({video:result.asset, cursor:{samples:result.cursor, displays:result.displays}});
+    status.textContent = 'Recording saved to your local media library.';
+  } catch (error) { status.textContent = error.message; }
+});
+```
+
+Every recording, in a browser and in StillMade Desktop, begins from StillMade's own Start button outside the Block interface (labelled for the screen, camera or microphone): pressing it is the consent. A view never reaches a device by itself, and the site's standing camera or microphone permission is not consent for a Block.
+
+`record.stop` returns `{asset, duration, width, height, bytes, mimeType, stoppedBy, message, cursor, displays, coordinates}`. `asset` is a canonical media reference with `assetId`, `versionId`, `kind` and a device-local `sm-media:` URL (`sm-media://asset/...` from the desktop media library, `sm-media://device/...` for a file a browser keeps on the device, which `previewMedia`, module `files.read` and the next Step read without uploading). `duration` is seconds measured by the host and written into the WebM header, so the recording seeks and cuts correctly. `stoppedBy` is present when the host ended the recording before `record.stop`: `size`, `time` or `sharing` (the person ended the share); the recording up to that point is kept and `message` says so. Cursor samples contain `{x,y,time}`: global device-independent screen coordinates and milliseconds relative to recording start. Multiple monitors can have negative coordinates. These are not automatically converted into cropped-window video coordinates. Share/upload media through the existing host media flow before teammates on other devices can use it. By default that flow uploads a 1080p working copy of large video (the account's media setting); the original stays in the desktop media library.
+
+`record.cut` turns the kept ranges of a recording into a new file on the device: `StillMade.desktop('record.cut', {source, keep:[{start, end}]})`, where `source` is a video this Block recorded in this session or received as an input and `keep` lists ordered, non-overlapping ranges in seconds (up to 500). The host re-encodes the kept parts with no export decision (no watermark; the Editor's export applies the account's policy later): through StillMade's renderer (WebCodecs H.264 into MP4, 1080p or 720p) where the browser encodes H.264, otherwise by playing the kept parts through a canvas into MediaRecorder (WebM, at the recording's own speed), which works wherever recording works. The result is kept beside the original and the call resolves to `{asset, duration, width, height, bytes, mimeType, keep}`. While it runs, `record.status` reports `cutting: {progress}`. The first-party Screen Recorder Block (`stillmade.screen-recorder`) is the reference: record, cut in its editor, then `StillMade.run` with the result.
+
+`device.info` (read-only, no consent needed, for a Block that declares a recording scope) tells a Block what fits here before anything is recorded: `{platform, streams, recorder, cut, budget:{seconds, bytes, bitsPerSecond}, limits}`. The browser's storage totals stay in the host; only the budget they leave is reported, to the megabyte. `recorder` says whether this browser can record at all, `cut` is `renderer` (WebCodecs), `playback` (real time) or `none`, `budget.seconds` is how long a 1080p recording fits (the storage quota in a browser, the time cap on desktop), and `streams` says whether desktop recordings go to disk as they are captured. Use it to say what fits and to point at StillMade Desktop when it does not; the Screen Recorder Block does.
+
+`record.cancel` discards an active capture. `session.close` revokes all access and cancels capture. StillMade also renders a host-owned cancel/revoke control outside the Block iframe. Screen source selection happens for every recording. No preview can bypass consent or access the native bridge directly.
+
+Current limits: one recording per Block workspace. In StillMade Desktop the recording streams to disk as it is captured (each chunk crosses to the desktop process as it arrives; the header is completed with the measured duration at the end), so the caps are 4 hours and free disk space; a desktop app without streamed recordings keeps 30 minutes and 128 MiB. In a browser the caps are 30 minutes, 2 GB and the browser's storage quota (`device.info` says how many minutes fit). Hitting a limit, the disk running low, or the person ending the share stops the recording and keeps what was captured; `record.stop` then saves it and reports `stoppedBy` (`size`, `time`, `disk` or `sharing`). `record.status` reports `limits` with `bytes: null` where only disk space applies. Output is WebM where the browser records it (H.264 or VP9 inside WebM in Chromium) and MP4 where only that is available (Safari). Camera recording is video-only; microphone recording is audio-only. Optional `{systemAudio:true}` is implemented through Windows loopback; other platforms reject it explicitly. Microphone mixing, global click/keyboard hooks, remote-control automation, arbitrary subprocesses, and folder watching are not provided by these scopes (folder access is `folder.read` and `folder.write`, above).
+
+## Testing and installation
+
+Test the pure typed-input/output runtime with synthetic media references and the regular SDK fixture tests. Then test the actual desktop operation interactively: allow, deny, stop, cancel, close, expired access, missing devices, source selection, and OS revocation. Passing a synthetic fixture or an Electron renderer test does **not** verify real OS permissions.
+
+No extra native dependency, installer prompt, or blanket OS permission is introduced. macOS may require the user to enable StillMade in Screen Recording settings and restart it; StillMade cannot bypass that OS decision. Windows privacy settings may also block camera/microphone access. The grant dialog appears only when the Block requests the relevant operation.

package/docs/reference/desktop-execution.md

@@ -0,0 +1,77 @@
+# Native desktop execution
+
+# Native desktop execution
+
+A Block declaring `manifest.desktopTools`, `permissions.desktop: ["native.tools"]`, or a package-level `desktop` mapping requires a trusted desktop executor. Its JavaScript or recipe cannot establish that a native application ran. The generic JavaScript worker and synchronous recipe runner reject these packages with `DESKTOP_EXECUTION_REQUIRED`.
+
+This guard applies conservatively to existing native packages too. Their immutable source, release identity and installed pins are unchanged. A legacy package without the mapping below can retain its reviewed interactive tool controls, but generic connected execution requires a new mapped release. Do not rewrite old package bytes or treat `return {video: input.video}` as a render.
+
+## Declarative input and output mapping
+
+The package's optional `desktop` object is stored as `src/desktop.json` in an editable SDK folder. The package must remain a stateless JavaScript or recipe package with its original sandbox rules, an approved `native.tools` declaration and desktop-only platforms. Version 1 currently supports only Natron adapter 1's `project.render` action:
+
+```json
+{
+  "schemaVersion": 1,
+  "tool": "org.natron.Natron",
+  "action": "project.render",
+  "arguments": {
+    "projectId": {"input": "projectId"},
+    "input": {"input": "video"},
+    "reader": {"input": "reader"},
+    "writer": {"input": "writer"},
+    "firstFrame": {"input": "firstFrame"},
+    "lastFrame": {"input": "lastFrame"}
+  },
+  "outputs": {"video": "asset"}
+}
+```
+
+Each mapped port must be declared in the manifest. `projectId`, `reader`, and `writer` are text; `video` is a video reference; frame ports are integers. All six values must be present after declared defaults and input resolution. Map every declared output to a compatible approved result field; Natron's `asset` is a video. Constants, extra arguments, commands, executable paths, environment variables and scripts are not supported. New native actions require a reviewed host adapter and a corresponding SDK argument/result contract.
+
+The same mapping survives JSON packages, portable archives, editable source downloads, folder/ZIP imports, CLI packaging and verified GitHub SDK-folder import. A mapping alone grants no permission and does not install or launch the application.
+
+## Trusted host execution
+
+The custom interface calls `StillMade.run` with the connected input and render settings. The host supplies the executor to `runPackageAsync`; package code cannot install this callback:
+
+```js
+await runPackageAsync(pkg, inputs, {
+  signal,
+  desktop: async (pinnedPackage, validatedInput, {signal, request}) => {
+    const invocation = desktopInvocation(pinnedPackage, validatedInput);
+    // Host-owned integration: check exact-source consent, project and media
+    // ownership, saved settings, approved operation, completion and artifact.
+    const completed = await authorizedNativeHostRun(invocation, {signal});
+    const outputs = desktopOutputs(pinnedPackage, completed.result);
+    return {
+      outputs,
+      desktopReceipt: {
+        schemaVersion: 1,
+        requestId: request.requestId,
+        packageDigest: request.packageDigest,
+        inputDigest: request.inputDigest,
+        outputDigest: await digest(outputs),
+        tool: pinnedPackage.desktop.tool,
+        adapterVersion: 1,
+        action: pinnedPackage.desktop.action,
+        executionId: completed.executionId
+      }
+    };
+  }
+});
+```
+
+`authorizedNativeHostRun` is illustrative host code, not an SDK API. It must perform the real approved native invocation, enforce cancellation and revocation, verify the output artifact and register its media identity before returning. It must not accept a receipt, output URL or claimed process success from Block code as authority. The Block cannot choose the executable, arbitrary path, credentials or permission scope.
+
+`desktopInvocation(pkg, inputs)` returns the declared `tool`, `operation` (`tool.project.render`), bounded argument mapping and output mapping. `desktopOutputs(pkg, nativeResult)` extracts and type-checks the declared results. The SDK pins copied package bytes and validated inputs before calling the host, creates a fresh cryptographic UUID request identity, and checks receipt source/input/action/output bindings and cancellation before returning. `RunPackageResult.desktopReceipt` must be retained with outputs.
+
+Receipt validation proves the envelope's bindings. It is not a cryptographic attestation of Natron, an independent check of stored media bytes, or permission to access another project's output. The trusted host still owns those checks. Host fixture mocks must never be described as native render proof.
+
+## Connected execution, reuse and admission
+
+Native Steps require an interactive connected plan and executor. They form a runtime-approval boundary in ordinary local, independent or background plans. A connected native result without its receipt is rejected even when a caller-supplied generic executor returns correctly typed passthrough output. Retained successful results must keep the receipt bound to the exact package, actual validated inputs and output. `validateDesktopExecutionRecord` checks those bindings during resume/adoption without running the application; host ownership checks remain required. Changes to input, source or output invalidate reuse.
+
+A reviewed condition or failure policy can still skip a Step. Such a record has `skipped: true` and no native receipt: it establishes a skip or fallback, not completed native work.
+
+Offline `validate`, `test`, `pack`, `admitLocalPackage` and `admitPackage` without a desktop executor perform source and fixture-contract checks only. Reports carry `execution: "not-run"`, `tests: 0`, `fixtureContracts`, `liveVerified: false` and `reviewRequired: true`. CLI `preview` and `testPackage` require the real executor to run; an unavailable executor never counts as a passing render. A supplied desktop executor can exercise contract fixtures, but SDK reports still do not claim independent live verification. Execute a representative authorized source through the real application, inspect the exported artifact, and verify downstream receipt and media identity before reporting integration complete.

package/docs/reference/errors.md

@@ -0,0 +1,233 @@
+# Errors and troubleshooting
+
+## Failure codes
+| Code | Action |
+| --- | --- |
+| MANIFEST / SCHEMA / PACKAGE | Correct the reported field or envelope |
+| TYPE | Match the declared type, bounds, and exact output keys |
+| REFERENCE | Use an existing input or completed earlier recipe output |
+| RUNTIME_UNAVAILABLE | Select an implemented runtime or operation |
+| PERMISSION / CONTEXT | Declare the matching context read scope and supply the correct snapshot |
+| CONDITION | Use a compatible single-output pass-through contract |
+| LIMIT / TIMEOUT | Reduce source, sample size, memory use, or computation |
+| CANCELLED | The run was stopped; preserve original inputs |
+| TESTS_REQUIRED / BEHAVIOR | Add meaningful fixtures or fix the mismatch |
+| WORKER_REQUIRED | Run browser JavaScript through a disposable worker |
+| CONFLICT / STALE_TESTS | Reload or retest the exact current source |
+| IMMUTABLE_RELEASE | Choose a new version for changed content |
+| SETUP_REQUIRED | Account operations need the configured host services |
+
+## Common issues
+A portable image reference is not decoded pixel data. The host must resolve it before a pixel-processing function runs. Missing secondary context values cannot be invented by offline tests; provide concrete fixture values. Returning extra output keys fails even if other output values are correct.
+
+## Diagnose in order
+1. Validate the manifest and package.
+2. Run each fixture through the real sandbox.
+3. Inspect sample outputs and their declared roles.
+4. Rehearse the connected Project Type.
+5. Test actual supported media in the host workspace.
+
+## Every SDK error code
+Generated from the SDK source (199 codes). The message is one example; the actual message names the exact field or limit.
+
+| Code | Example message | Raised in |
+| --- | --- | --- |
+| ADAPTER | Declare the conversion’s type and meaning. | `adapter-registry`, `universal-resolver` |
+| ADAPTER_CONTEXT | The … needs a persistent project identity | `connection-adapters` |
+| ADAPTER_LIMIT | Convert at most 100 items at a time. | `connection-adapters` |
+| ADAPTER_PERMISSION | Declare context.….read to use this connection | `connection-adapters` |
+| ADAPTER_PIN | This connection adapter changed. Review the connection before running it | `connection-adapters` |
+| ADAPTER_TYPE | The connected output must be … | `connection-adapters`, `csv-table` |
+| AGENT_CONTRACT | Declare an independently versioned control adapter | `native-agent-contract` |
+| APPEARANCE | Use plain theme rules; CSS escapes, nesting, filters and color blending need adaptation. | `appearance` |
+| APPLICATION_ARTIFACT_HOST | Supply host-owned authorization and bounded byte-fetch callbacks. | `browser-application-artifacts` |
+| APPLICATION_GUEST_ARGUMENT | Use the declared lifecycle arguments only. | `browser-application-guest` |
+| APPLICATION_GUEST_BUSY | Wait for the active application operation. | `browser-application-guest` |
+| APPLICATION_GUEST_DATA | Application messages need plain JSON fields, without accessors. | `browser-application-guest` |
+| APPLICATION_GUEST_INPUT | Operation inputs must match the mounted inputs. | `browser-application-guest` |
+| APPLICATION_GUEST_INSTALLED | Application registration is already installed or the target is invalid. | `browser-application-guest` |
+| APPLICATION_GUEST_LIMIT | Application messages must be bounded by at most 4 MiB. | `browser-application-guest` |
+| APPLICATION_GUEST_MOUNT | Application mount must acknowledge mounting only. | `browser-application-guest` |
+| APPLICATION_GUEST_OPERATION | Declare 1–32 application operations. | `browser-application-guest` |
+| APPLICATION_GUEST_REGISTRATION | Register one application adapter before mounting. | `browser-application-guest` |
+| APPLICATION_GUEST_RESULT | Adapters return output values only, never host receipt or verification fields. | `browser-application-guest` |
+| APPLICATION_GUEST_SIGNAL | Use an AbortSignal when supplied. | `browser-application-guest` |
+| APPLICATION_GUEST_STATE | Supply the host state revision. | `browser-application-guest` |
+| APPLICATION_INTEGRITY | Application artifact byte count differs from its reference. | `browser-application-artifacts` |
+| APPLICATION_OUTPUT_CANDIDATE | Use declared browser application outputs. | `browser-application-output-policy` |
+| APPLICATION_OUTPUT_UNMATERIALIZED | Output … includes media references that the browser application host has not independently verified. | `browser-application-output-policy` |
+| APPLICATION_SOURCE_LIMIT | Application source | `browser-application-artifacts` |
+| APPLICATION_SOURCE_REFERENCE | Use a browser application manifest. | `browser-application-artifacts` |
+| APPLICATION_STATE_LIMIT | Application state artifact | `browser-application-artifacts` |
+| APPLICATION_STATE_REFERENCE | Application scope | `browser-application-artifacts` |
+| ARCHIVE | Expected a complete single ZIP archive | `portable-archive` |
+| ARCHIVE_PATH | Use safe relative regular-file paths | `portable` |
+| AUDIO_SCORE_HOST | Choose a supported Audio Score operation | `audio-score-host` |
+| BROWSER_APPLICATION_UNAVAILABLE | No trusted desktop browser application executor is installed. A bundle or mounted interface is not execution. | `browser-application-execution` |
+| BROWSER_BUILD_DEPENDENCY | Expected one exact registry tarball identity. | `repository-build-dependencies` |
+| BUSY | JavaScript runners are busy. Try again shortly. | `sandbox-node` |
+| BYOK_PAYMENT_HOST | Choose a supported payment capability | `byok-payment-host` |
+| CANCELLED | Conversion stopped. | `adapter-registry`, `browser-application-execution`, `browser-application-guest` and 8 more |
+| CANVAS_GENERATION_HOST | Canvas media Blocks require version … of their trusted generation host | `canvas-generation-host` |
+| CANVAS_NODE_HOST | Invalid versioned Canvas node registration | `canvas-node-host` |
+| CANVAS_WORKSPACE | Canvas needs its scoped snapshot and navigation binding | `canvas-workspace-host` |
+| CAPABILITY_BINDING | Transcription audio must reference the exact declared audio or video port (a video's sound is transcribed) | `capabilities` |
+| CAPABILITY_EXPECTATION | Include expectations for the exact declared output | `capabilities` |
+| CAPABILITY_INPUT | … must be a saved image (asset, version and URL) | `capabilities` |
+| CAPABILITY_LIMIT | negativePrompt must be at most 2,000 characters | `capabilities` |
+| CAPABILITY_MANIFEST | Expected a host-mediated capability manifest | `capabilities` |
+| CAPABILITY_OUTPUT | A generated script contains schemaVersion and text only | `capabilities`, `json-schema` |
+| CAPABILITY_SCHEMA | Capability values must be finite | `capabilities`, `json-schema` |
+| CAPABILITY_SETTINGS | … does not accept a last frame | `capabilities`, `generation-catalog` |
+| CAPABILITY_TYPE | Transcription takes one persistent audio or video input and one language input | `capabilities` |
+| CODE | JavaScript must contain 1–262144 bytes | `javascript` |
+| COMFY_BACKEND | Expected ComfyUI object_info | `comfyui` |
+| COMFY_BINDING | Choose named Block inputs and outputs before creating the package | `comfyui-import`, `comfyui` |
+| COMFY_CYCLE | ComfyUI workflows cannot contain cycles | `comfyui` |
+| COMFY_EXPECTATION | Every declared output needs a typed expectation | `comfyui` |
+| COMFY_FILE | Use a host-generated PNG basename without paths, URLs or annotations | `comfyui` |
+| COMFY_IMPORT | ComfyUI import accepts finite JSON values only | `comfyui-import` |
+| COMFY_JSON | Choose a ComfyUI API-format JSON workflow | `comfyui-import` |
+| COMFY_MANIFEST | Provide an explicit ComfyUI Block manifest | `comfyui-import`, `comfyui` |
+| COMFY_MODEL | Use an installed safetensors checkpoint basename; paths, URLs and other model formats are unsupported | `comfyui` |
+| COMFY_NODE | Node … (…) has unexpected or missing inputs. Connection settings, credentials, code and dependencies cannot be embedded. | `comfyui-import`, `comfyui` |
+| COMFY_OUTPUT | Decoded image metadata is required | `comfyui` |
+| COMFY_REFERENCE | Image inputs require an exact existing node and output index | `comfyui` |
+| COMFY_SCHEMA | ComfyUI values must be finite | `comfyui` |
+| COMFY_SDK_PACKAGE | This is already a StillMade SDK package. Import it directly without converting its workflow. | `comfyui-import` |
+| COMFY_TYPE | ComfyUI accepts images, text and bounded numeric controls | `comfyui` |
+| COMFY_UI_WORKFLOW | This is a ComfyUI visual workflow export. In ComfyUI, use Export (API) or Save (API Format), then import that JSON. Visual node positions and widget values cannot be safely converted without the exact node definitions. | `comfyui-import` |
+| CONFLICT | Collection removed | `document-operations`, `document-store`, `shared-view` |
+| CONNECTION_BINDING | Bind every declared input to a real schema property. | `connected-app` |
+| CONNECTION_CLIENT | Provide the existing authenticated host request service. | `connection-client` |
+| CONNECTION_CONFIGURATION | Configure the exact original connected task. | `configured-connection` |
+| CONNECTION_CONTRACT | Declare the exact connected-app contract, schemas and typed bindings. | `connected-app` |
+| CONNECTION_EXPECTATION | Use one bounded result expectation. | `connected-app` |
+| CONNECTION_OUTPUT | Declare one typed result for this operation. | `connected-app` |
+| CONNECTION_PIN | An exact backend task/version/schema pin is required. | `connected-app` |
+| CONNECTION_SCHEMA | This task needs a compatible object input schema. | `connected-app` |
+| CONNECTION_SOURCE | Use the exact private catalog-issued Python source. | `connected-app` |
+| CONNECTION_TASK | Choose a declared task operation. | `connected-app-view` |
+| CONNECTION_VERSION | Use the catalog-issued immutable definition hash. | `connected-app` |
+| CONTEXT | Provide valid project shots | `context` |
+| DEPENDENCY_RESTRICTED | Bundle adapted dependency code into src/run.js and record each dependency as a licensed source; runtime installation is unavailable | `portable` |
+| DESKTOP_EXECUTION | A desktop execution mapping requires a stateless JavaScript or recipe package with declared desktop tools. | `desktop-execution` |
+| DESKTOP_EXECUTION_REQUIRED | This Block requires its approved desktop executor. Running its JavaScript or recipe alone does not execute the native tool. | `desktop-execution`, `runtime` |
+| DESKTOP_RECEIPT | Invalid native execution request. | `desktop-execution`, `package-jobs` |
+| DESKTOP_TOOL | Declare one to eight approved desktop tools | `desktop-tools` |
+| DOCUMENT_DRAFT | Use a JSON object document | `document-drafts` |
+| DOCUMENT_IDENTITY | Use a JSON object document | `document-identity` |
+| DOCUMENT_SOURCE_CONFLICT | Project source changed underneath the shared draft. Review and explicitly reset the shared draft for everyone, or supply a compatible source. | `document-store` |
+| DOCUMENT_STORE | Use a bounded named document field | `document-store` |
+| FIRST_PARTY_SOURCE | Use the exact published first-party package before creating a remix. | `remix-policy`, `testing` |
+| GENERATION_SETTINGS | This Step does not generate images, video or speech. | `generation-settings` |
+| HOST_SERVICES | Animated assets requires its version 1 generation and dialog host | `animated-assets-host`, `asset-generation-host`, `blueprint-host-services` and 47 more |
+| INPUT_SOURCE | … does not allow … information. Choose a permitted source. | `input-source-policy` |
+| JOB_EXECUTOR | Use a trusted host executor | `package-jobs` |
+| JOB_LIMIT | Return final outputs within 32 cooperative turns | `javascript` |
+| JOB_PROGRESS | Use explicit complete/total units or omit progress | `javascript` |
+| JOB_RESULT | Return final Block outputs, not a guest pending-job envelope | `package-jobs` |
+| JOB_SUBSCRIBER | Use a progress listener | `package-jobs` |
+| JOB_TIMEOUT | Use an execution deadline between 1 ms and 15 minutes | `package-jobs` |
+| LICENSE_BLOCKED | Missing applicable upstream LICENSE, COPYING or NOTICE; preserve every ancestor notice and scoped license | `portable-github`, `portable`, `remix-policy` |
+| LICENSE_RESTRICTED | Conflicting file-level SPDX license at … | `portable-github`, `portable` |
+| LIMIT | Source exceeds static review complexity | `admission`, `browser-application-execution`, `capabilities` and 14 more |
+| LINEAGE | Declare lineage {parents:[{id,version,digest}],changes} | `portable` |
+| MANIFEST | Invalid JavaScript manifest | `javascript` |
+| MEDIA_DESCRIPTION_HOST | Describe Media requires a supported image reference and optional hint | `media-description-host` |
+| MEDIA_RENDER_INPUT | Final render requires a versioned timeline, settings, and Block source. | `portable-media-contracts` |
+| MEDIA_RENDER_LIMIT | Final render exceeds the approved timeline limits. | `portable-media-contracts` |
+| MEDIA_RENDER_RECEIPT | The final render receipt is invalid. | `portable-media-contracts` |
+| MEDIA_UPLOAD_HOST | Import Media requires its version 1 host interface | `media-upload-host` |
+| MOCK_HOST | The stand-in host needs the Block manifest. | `mock-host`, `mocks` |
+| MODULE_BUNDLE | Only module Blocks and frame views with assets are bundled this way | `module-bundle` |
+| MODULE_ERROR | The module stopped without returning: it waits on something that never finishes. | `module-quickjs` |
+| MODULE_FILE | … is missing from the local files | `module-node`, `module-quickjs`, `module-runtime` |
+| MODULE_FILE_READ | The {base64} file for … must be plain base64 of at most 256 KB. | `mock-host` |
+| MODULE_HOST_UNAVAILABLE | Local files need a file reader. | `mock-host` |
+| MODULE_HOSTED | A module Block identity is required | `module-hosted` |
+| MODULE_PERMISSION | This Block did not declare … in permissions.capabilities | `module-hosted` |
+| MODULE_RESULT | The module host returned an unexpected result | `runtime` |
+| MODULE_TIMEOUT | The module's tests ran past … ms of its own time. | `module-quickjs` |
+| NATIVE_APPLICATION_AUTHORITY | Use the scoped project execution checkpoint. | `runtime` |
+| NATIVE_APPLICATION_UNAVAILABLE | No trusted native application executor is installed. A bundle or mounted interface is not execution. | `native-application-execution` |
+| NATIVE_BINDING | Declare scoped trusted bindings | `native-workspace-contract` |
+| NATIVE_CALLBACK | Workspace callback is unavailable | `native-workspace-contract` |
+| NATIVE_CONTRACT | Unsupported native … schema | `native-workspace-contract` |
+| NATIVE_DEPENDENCY | Native host dependency …@… is unavailable | `native-workspace-contract` |
+| NATIVE_HOST | Invalid installed host provider declarations | `native-host-providers` |
+| NATIVE_MODULE | Choose an explicitly versioned native module | `native-workspace-contract` |
+| NATIVE_REGISTRATION | Declare registration and ownership-scoped cleanup | `native-workspace-contract` |
+| NATIVE_REGISTRY | Declare an exact dependency alias to another workspace | `native-workspace-contract` |
+| NATIVE_SERVICE | Host service …@… is unavailable | `native-workspace-contract` |
+| NATIVE_UPDATE | The atomic state host is unavailable | `native-workspace-contract` |
+| PACKAGE | Declare a Block package and its manifest. | `define-block`, `javascript`, `testing` |
+| PATCH | Invalid operation path | `document-operations` |
+| PERMISSION | This conversion needs permission. | `adapter-registry`, `context`, `contracts` and 2 more |
+| PIPELINE_ASSET_HOST | Canvas requires its version 1 asset persistence host | `pipeline-asset-host` |
+| PIPELINE_NODE_GENERATION_HOST | Pipeline generation nodes require version 1 of their trusted generation host | `pipeline-node-generation-host` |
+| PIPELINE_RUNTIME_HOST | Pipeline requires version 1 of its runtime host | `pipeline-runtime-host` |
+| PORTABLE_ACTION | media.generate needs 1–50 items. | `portable-media-actions` |
+| PORTABLE_ACTION_RESULT | The host action result does not match its declared Block output. | `portable-action-results` |
+| PORTABLE_ENTRY | Runtime entry must match the canonical source file | `portable` |
+| PORTABLE_FILES | Include bounded UTF-8 source and legal evidence files | `portable` |
+| PORTABLE_FORMAT | Portable attribution requires retained portable evidence | `portable` |
+| PORTABLE_UI | Declare manifest.ui (generated controls; [] is valid for context-only input) | `portable` |
+| PRESENTER_INPUT | Presenter placement requires a version 1 Whiteboard and finite placement. | `portable-media-contracts` |
+| PRESENTER_RECEIPT | Presenter pose assets require exact source, sheet, slice, and version receipts. | `portable-media-contracts` |
+| PREVIEW_MODULE | A preview requires an exact Block identity and version | `native-preview-contract` |
+| PROJECT_FLOW_SNAPSHOT | Supply a project Flow snapshot. | `project-flow-contract` |
+| PROJECT_FLOW_TARGET | Supply a structured project Flow target. | `project-flow-contract` |
+| PROVENANCE | The job must retain exactly its reviewed user answers. | `package-jobs`, `sandbox-node`, `universal-resolver` |
+| PYTHON_CONTRACT | Choose supported annotated scalar inputs and result. | `python-connection` |
+| QUALITY_INPUT | Quality analysis accepts 1–16 exact asset versions. | `portable-media-contracts` |
+| QUALITY_RECEIPT | Every planned asset requires one retained analysis receipt. | `portable-media-contracts` |
+| RECIPE | Expected recipe schema 1, at most 64 steps, and output bindings | `recipe` |
+| REFERENCE | Invalid reference | `recipe` |
+| REFERENCE_SELECTION | Choose a bounded field browser. | `reference-source` |
+| REFERENCE_SOURCE | Use an exact snapshot identity. | `reference-source` |
+| REQUIREMENT | Choose a declared input requirement. | `interactive-requirements`, `package-jobs`, `sandbox-node` and 1 more |
+| RESOLVER | Choose an exact asset version for scoped resolution. | `universal-resolver` |
+| RUNTIME | Sandbox memory configuration was not applied | `javascript` |
+| RUNTIME_RESTRICTED | Portable Blocks support recipe, isolated JavaScript, declarative host capabilities and reviewed ComfyUI workflows. Arbitrary Python and native code are restricted; do not package a substitute that pretends to provide them. | `portable` |
+| RUNTIME_UNAVAILABLE | This host does not provide interactive Block questions. Supply this input before running. | `javascript`, `recipe`, `runtime` |
+| SCHEMA | Numbers must be finite | `contracts`, `semantic-contracts` |
+| SEMANTIC | Resolve meanings from at most 200 pinned Block manifests. | `package-semantics`, `semantic-contracts` |
+| SHARED_TEXT_CLOSED | Shared text session is closed | `shared-text` |
+| SHARED_TEXT_INPUT | Shared text must be a string | `shared-text` |
+| SHARED_TEXT_LIMIT | Shared text exceeds its character limit | `shared-text` |
+| SHARED_TEXT_STATE | Shared text data contains trailing bytes | `shared-text` |
+| SHARED_WORK_CONTRACT | Declare a bounded, versioned shared-work schema. | `shared-work` |
+| SHARED_WORK_INPUT | Shared-work requests require bounded JSON arguments. | `shared-work` |
+| SHARED_WORK_OPERATION | Choose a declared shared-work operation. | `shared-work` |
+| SOURCE_DECLARATION | Original sources must retain an implementation snapshot alongside legal evidence | `portable` |
+| SOURCE_MISMATCH | GitHub returned a different tree from the pinned commit | `portable-github` |
+| SOURCE_PIN | GitHub must confirm the exact source commit and its tree | `portable-github`, `portable` |
+| SOURCE_RESTRICTED | Complete repository tree is required for license verification | `portable-github` |
+| SOURCE_UNAVAILABLE | Pinned GitHub evidence unavailable (…); installation is blocked until it can be verified | `portable-github` |
+| STALE | The conversion source expired or is no longer current. Refresh it before trying again. | `adapter-registry`, `universal-resolver` |
+| STATE_BEHAVIOR | State differs from expected fixture | `testing` |
+| STATE_LIMIT | Block state exceeds 64 KiB | `state` |
+| STATE_MIGRATION | All migration declarations together must fit within 64 KiB | `state-migrations` |
+| STATE_REQUIRED | Declare a valid scoped state contract | `state` |
+| STATE_TEST | Fixture state requires a declared stateful Block | `testing` |
+| STATE_UNDECLARED | This Block does not declare persistent state | `javascript`, `package-jobs` |
+| STATE_VERSION | State does not match this Block’s declared state schema | `state` |
+| STOCK_PROVENANCE | The stock source has no approved license policy. | `portable-media-contracts` |
+| STOCK_RECEIPT | The stock acquisition receipt is invalid. | `portable-media-contracts` |
+| TEST | Desktop fixtures need a name and typed input/output contracts. | `testing` |
+| TESTS_REQUIRED | Add a sample image and typed output expectations before reviewing the import. Samples have not run yet. | `comfyui-import`, `portable`, `testing` |
+| TIMEOUT | JavaScript exceeded its cumulative 500 ms execution limit | `javascript`, `local-admission`, `package-jobs` and 2 more |
+| TYPE | … values must be an object | `contracts`, `javascript`, `recipe` |
+| VIDEO_ASSETS_HOST | Prompt recommendations require an image URL and text prompts | `video-assets-host` |
+| VIEW | View JavaScript exceeds review complexity | `view` |
+| VIEW_STATE | Shared edit exceeds 800,000 bytes | `shared-view` |
+| WORKER_REQUIRED | Run JavaScript blocks through a worker | `runtime` |
+| WORKFLOW_APPROVAL | Workflow approval must be a required direct-user decision with no saved default or context source. | `semantic-contracts`, `workflow-approvals` |
+| WORKFLOW_EVENT | Use a named event with a bounded identity. | `workflow-events` |
+| WORKSPACE_APPLICATION | Invalid workspace application adapter | `workspace-application` |
+| WORKSPACE_NAVIGATION | Invalid Block navigation declaration | `workspace-navigation` |
+| WORKSPACE_PRESENCE | Presence must be an object | `workspace-sync` |
+| WORKSPACE_ROUTE | Invalid standalone workspace declaration | `workspace-application` |
+| WORKSPACE_SYNC | Invalid workspace change | `workspace-sync` |
+| YOUTUBE_HOST | YouTube host version 1 is required | `youtube-host` |