stillmade-sdk 0.1.34 → 0.1.36

package/SDK.md

@@ -84,9 +84,13 @@ Author those files directly under the SDK contract; external framework packages,
 Node services and a separate standalone website are not this runtime's source.
 No build/install command executes during import.
 
-Select **my-block** with Choose folder to import that source unchanged. Development
-tools may live beside it; select the Block directory, not an SDK checkout containing
-several example builds. Use at least two fixtures (normal and edge cases) for the
+Select **my-block** with Import folder (or drop the folder on the Import page) to
+import that source unchanged. The app reads the folder with the same reader as
+`pack`, so module Blocks (their `module/` files and `.wasm`) and frame views with
+`src/view-files/` import as they pack; module files upload by SHA-256 before review.
+`node_modules`, `.git` and other files outside the Block layout are ignored, so a
+folder Codex or Claude Code built with its own tools imports as it is. Select the
+Block directory, not an SDK checkout containing several example builds. Use at least two fixtures (normal and edge cases) for the
 canonical archive, and use `--original` only for your own original implementation
 without reused repository/dependency code. Direct folder import and archive import
 retain the same runtime and interface; packaging adds explicit retained-source
@@ -182,7 +186,7 @@ The archive needs Node.js 22 or later and nothing else; its runtime is bundled,
 
 ## Block builder contract
 
-Contract `stillmade.block-builder@1.7.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.10.0`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 
 ### Source of truth
 
@@ -196,6 +200,10 @@ Before building, check what already exists (`find_existing_blocks` over MCP, or
 
 Blocks come in three sizes and the manifest decides which (packages/block-sdk/block-tier.js): an app is a workspace a person works in (Editor, Canvas, Shots), placed in a Type and never wired automatically; a job is one deliverable a person would name (the narration, the captioned clip), built from the hosted operations it needs (`permissions.capabilities`) and reviewed in one place, the unit Chat picks for a Step; an ingredient is one hosted operation with nothing of its own (a declarative capability Block), what a job is made of. When two ingredients would stand in a row to make one deliverable (writing the words, then voicing them), build or pick the job that does both and keep the review point inside it. A job declares a second output when another Block consumes the intermediate (the script beside the voice); split into two jobs only when the intermediate has a life of its own or the halves have different owners or payment.
 
+### Choose the runtime
+
+Pick the runtime from the job. No hosted AI: a recipe or isolated `javascript`, both able to run unattended. One text, script or brief prompt returning text, script or JSON: a `capability` Block. Hosted operations on other values (a transcript, media, structured data), several hosted operations in a row, or a result shaped in code: one `module` Block, `module/main.js` calling `stillmade.hosted.run(operation, request)` for each operation in `permissions.capabilities` (MODULES.md), never one Block per operation; it runs in the person's browser while StillMade is open. Build a new Block in a folder with `stillmade-block create`, `test`, `ready` and `pack`, and import the file `pack` writes (a module Block writes `<id>-<version>.stillmade-module.json`) through Create, then Import Block. A `.stillmade-block` archive is only for adapting a GitHub repository.
+
 ### One job per Step
 
 A Step is one job: the work between two moments where a person or the outside world must see the result. Start a new Step only at one of three points; everything else is a part of the neighboring Step.
@@ -208,7 +216,7 @@ In a production the Steps are the workspaces a person opens: work feeding the ne
 
 A part that only runs in the desktop app cannot share a Step with cloud parts. Before adding a Step, name which of the three reasons makes it separate; if none applies, make it a part of a neighbor. A Step nobody would ever open must not exist on its own. Prefer an app task's own filter (a Gmail query such as `has:attachment filename:png`) to an AI check, and use AI decide only for judgement.
 
-Inside one job, each capability stays its own part: a capability Block performs exactly one hosted operation and a connector one app task, so every part keeps its own permission, approval and credit rules, and StillMade groups the parts of one job into one Step (`groups` in the Project Type). Never invent a combined runtime. When one Block can do the whole job with documented primitives (a JavaScript Block doing several local transforms, a workspace owning its whole document), build it as one Block.
+Build one Block for a job one Block can do: a module Block calls every hosted operation the job needs (it transcribes a sermon, then finds the verses said in it), a JavaScript Block does several local transforms, a workspace owns its whole document. A Block being built never takes an ingredient's result only so the ingredient can be its own part or Step (Transcribe in front of a verse finder): it calls that operation itself. Parts in one Step (`groups` in the Project Type) are for jobs made of Blocks that already exist and app tasks, each keeping its own permission, approval and credit rules. Never invent a combined runtime.
 
 Examples: "every new email with an image becomes a generated image" is two Steps, "Gmail · New emails with images" (When, fetch with an image filter, only new) and "Image from email" (AI write, Generate image); listing When, Fetch, Only new, AI decide, Continue only if, AI write and Generate image as seven Steps splits one job into its parts. "A new Meta lead goes to HubSpot" is three Steps: "Meta Ads · New leads", "Qualify lead" and "HubSpot · Add contact".
 
@@ -246,7 +254,7 @@ Projects are multiplayer. A custom view subscribes through `StillMade.onShared(c
 
 ### External services
 
-Reach external services only through StillMade's hosted operations, the connections service (`connection.execute`), or, in a module Block, `stillmade.net.fetch` to origins declared in `permissions.network` (with the key each needs) and `stillmade.connections.call` to adapters or catalog apps in `permissions.connections`; never put keys in code, inputs or headers: StillMade adds each person's own key on its servers. The host owns the model and provider choice, BYOK keys, StillMade credits, spending consent, authorization, token refresh, rate limits, retries and provider errors; a Block never receives a secret and never names a provider unless it must. Treat provider unavailability, timeout, cancellation and partial failure as typed outcomes the Block reports, not crashes. Generated images, video, voices, music and sound effects come from hosted operations or the `media.generate` action, paid with the user's StillMade credits at StillMade's prices; for structured model output declare a `json` output with `capability.schema` instead of parsing prose. When a Block needs npm libraries, WebAssembly or heavy compute, use `runtime: "module"` and reach hosted operations through `stillmade.hosted.run` with the operations listed in `permissions.capabilities`. Decode, cut, join, re-encode, extract or normalise audio and video with `stillmade.media.transform` on the device; never ask for a server render. For a rich interactive interface (React or another framework, SVG, canvas, drag), use a frame view: `src/view.config.json` with `{"runtime":"frame"}` and `src/view.js` bundled as one IIFE, colored with StillMade's theme variables. For files and structured data use the `file`, `document`, `table`, `url`, `date` and `color` types and their generated controls and presentations, not JSON text.
+Reach external services only through StillMade's hosted operations, the connections service (`connection.execute`), or, in a module Block, `stillmade.net.fetch` to origins declared in `permissions.network` (with the key each needs), `stillmade.net.connect` for a live WebSocket to one of them, and `stillmade.connections.call` to adapters or catalog apps in `permissions.connections`; never put keys in code, inputs or headers: StillMade adds each person's own key on its servers. The host owns the model and provider choice, BYOK keys, StillMade credits, spending consent, authorization, token refresh, rate limits, retries and provider errors; a Block never receives a secret and never names a provider unless it must. Treat provider unavailability, timeout, cancellation and partial failure as typed outcomes the Block reports, not crashes. Generated images, video, voices, music and sound effects come from hosted operations or the `media.generate` action, paid with the user's StillMade credits at StillMade's prices; for structured model output declare a `json` output with `capability.schema` instead of parsing prose. When a Block needs npm libraries, WebAssembly (threaded: `"threads": true` in module.json) or heavy compute, use `runtime: "module"` and reach hosted operations through `stillmade.hosted.run` with the operations listed in `permissions.capabilities`. Decode, cut, join, re-encode, extract or normalise audio and video with `stillmade.media.transform` on the device; never ask for a server render. For a rich interactive interface (React or another framework, SVG, canvas, drag), use a frame view: `src/view.config.json` with `{"runtime":"frame"}` and `src/view.js` bundled as one IIFE, colored with StillMade's theme variables. For files and structured data use the `file`, `document`, `table`, `url`, `date` and `color` types and their generated controls and presentations, not JSON text.
 
 ### Dependencies
 
@@ -254,7 +262,7 @@ A Block must declare everything it requires and must not assume anything is inst
 
 ### Security
 
-Treat Block code, external data, files, repositories, model output and network responses as untrusted. Request the minimum permissions and capabilities. Do not weaken the sandbox (QuickJS has no fetch, DOM, timers, modules or Node APIs). Validate and bound every value crossing a boundary. Never expose secrets through logs, outputs, project context, UI, error messages or serialized state.
+Treat Block code, external data, files, repositories, model output and network responses as untrusted. Request the minimum permissions and capabilities; `stillmade-block permissions --fix` declares exactly what the source uses. Do not weaken the sandbox (QuickJS has no fetch, DOM, timers, modules or Node APIs). Validate and bound every value crossing a boundary. Never expose secrets through logs, outputs, project context, UI, error messages or serialized state.
 
 ### Execution lifecycle
 
@@ -342,7 +350,7 @@ In a production the Steps are the workspaces a person opens: work feeding the ne
 
 A part that only runs in the desktop app cannot share a Step with cloud parts. Before adding a Step, name which of the three reasons makes it separate; if none applies, make it a part of a neighbor. A Step nobody would ever open must not exist on its own. Prefer an app task's own filter (a Gmail query such as `has:attachment filename:png`) to an AI check, and use AI decide only for judgement.
 
-Inside one job, each capability stays its own part: a capability Block performs exactly one hosted operation and a connector one app task, so every part keeps its own permission, approval and credit rules, and StillMade groups the parts of one job into one Step (`groups` in the Project Type). Never invent a combined runtime. When one Block can do the whole job with documented primitives (a JavaScript Block doing several local transforms, a workspace owning its whole document), build it as one Block.
+Build one Block for a job one Block can do: a module Block calls every hosted operation the job needs (it transcribes a sermon, then finds the verses said in it), a JavaScript Block does several local transforms, a workspace owns its whole document. A Block being built never takes an ingredient's result only so the ingredient can be its own part or Step (Transcribe in front of a verse finder): it calls that operation itself. Parts in one Step (`groups` in the Project Type) are for jobs made of Blocks that already exist and app tasks, each keeping its own permission, approval and credit rules. Never invent a combined runtime.
 
 Examples: "every new email with an image becomes a generated image" is two Steps, "Gmail · New emails with images" (When, fetch with an image filter, only new) and "Image from email" (AI write, Generate image); listing When, Fetch, Only new, AI decide, Continue only if, AI write and Generate image as seven Steps splits one job into its parts. "A new Meta lead goes to HubSpot" is three Steps: "Meta Ads · New leads", "Qualify lead" and "HubSpot · Add contact".
 
@@ -1850,6 +1858,8 @@ the Block.
   measured after decompression), 30 seconds per request including redirects, and
   120 requests a minute per person and Block.
 - A response that contains the key (raw, URL-encoded or base64) is withheld.
+- Live connections (`net.connect`) go to the `wss://` form of a declared origin,
+  carry no key, and are relayed outside the module's sandbox (see Live connections).
 
 ### OAuth apps
 
@@ -1995,8 +2005,9 @@ event through an input with `"semantic": "workflow_event"` and
 `"sources": ["project"]`.
 
 Triggers work for recipe, JavaScript and hosted (`runtime: "capability"`)
-Blocks. Module Blocks run only in the person's browser, so they cannot declare
-triggers or run unattended. Sandboxed code has 25 seconds per run.
+Blocks. Module Blocks run only on the person's device, so they cannot declare
+triggers of their own; a schedule or event can hand their Steps to the owner's
+StillMade Desktop (see Module Blocks). Sandboxed code has 25 seconds per run.
 
 ### Hosted Blocks run inside an approved budget
 
@@ -2116,8 +2127,10 @@ A module Block (`"runtime": "module"`) is an ordinary ES module. It can use
 everything a modern browser Worker offers: `async`/`await`, timers, typed
 arrays, `WebAssembly`, `OffscreenCanvas`, `createImageBitmap`, WebCodecs, and
 any npm package you bundle into it, including C and C++ libraries compiled to
-WebAssembly (OpenCV, libvips builds, codecs, solvers). Use it when a recipe or
-the QuickJS `javascript` runtime is too small for the job.
+WebAssembly (OpenCV, libvips builds, codecs, solvers), threaded WebAssembly
+(see Threads) and live WebSocket connections to declared origins (see Live
+connections). Use it when a recipe or the QuickJS `javascript` runtime is too
+small for the job.
 
 ### Folder layout
 
@@ -2127,7 +2140,7 @@ my-block/
   module/                  everything the Block runs
     main.js                the entry (bundle npm dependencies into it)
     filters.wasm           optional WebAssembly and data files
-  module.json              optional: {"entry": "other.js"}
+  module.json              optional: {"entry": "other.js", "threads": true}
   tests/fixtures.json      [{name, input, expected}]
 ```
 
@@ -2167,6 +2180,7 @@ against the manifest's port types.
 | `actions.run(action)` | Runs a declared portable action. `media.generate` asks the person to approve one StillMade credit maximum for the batch; `stock.search` runs directly. |
 | `hosted.run(operation, request)` | Calls a hosted operation the manifest lists in `permissions.capabilities` (for example `text.generate`, `image.generate`, `audio.speech`, `web.research`). Each call is quoted and approved like a capability Block and paid with StillMade credits. |
 | `net.fetch(url, {method, headers, body})` | Calls one of the origins declared in `permissions.network` through StillMade, which adds the person's own key or OAuth token on its servers. Returns a standard `Response`. See [Outside APIs](/docs/build/outside-apis). |
+| `net.connect(url, {protocols})` | Opens a live WebSocket to the `wss://` form of a declared origin and resolves with the open socket (`send`, messages, `for await`, `close`). No key is added. See [Live connections](#live-connections). |
 | `connections.call(appId, operationId, input)` | Calls an operation of a published adapter declared in `permissions.connections`, with the person's own account. Returns the checked JSON result. |
 | `storage.get/set/remove/list/info(...)` | The Block's own cloud storage in the current project: JSON values up to 1 MiB under folder-like keys. Kept across runs, devices and the Block's versions. See [Project storage, reads and assets](/docs/build/project-storage). |
 | `storage.putFile(key, data, {mediaType})` / `storage.getFile(key)` | Files up to 64 MiB in the same storage; `getFile` returns `{key, mediaType, bytes, data}` with `data` as an `ArrayBuffer`, or `null`. |
@@ -2240,9 +2254,10 @@ WebAssembly codec. Images arrive as saved references: read the bytes with
 ### Sandbox and limits
 
 - The module runs in one dedicated Worker inside a response-sandboxed frame
-  with an opaque origin. It has no network (`fetch`, WebSocket and remote
-  imports fail), no storage of the app, no page or DOM access, and cannot read
-  another Block's files.
+  with an opaque origin. It has no network of its own (`fetch`, WebSocket and
+  remote imports fail; `net.fetch` and `net.connect` go through StillMade), no
+  storage of the app, no page or DOM access, and cannot read another Block's
+  files.
 - Every file is fetched from StillMade's store and checked against its SHA-256
   before anything runs.
 - A run may take 2 minutes; each progress report allows 60 more seconds. Time
@@ -2253,11 +2268,63 @@ WebAssembly codec. Images arrive as saved references: read the bytes with
 - Generating code at run time (`new Function`, used by Emscripten bindings) is
   allowed inside the sandbox.
 
-Module Blocks run in StillMade in the person's browser, only while StillMade is
-open. They cannot run on a schedule, from an event or on new media: StillMade has
-no server sandbox for them. A workflow's background run stops before a module Step
-and the person runs it in the project. Marketplace listings show module Blocks as
-**Browser only**. For work that must run unattended, use a JavaScript Block.
+Module Blocks run in StillMade on the person's device: in the browser while
+StillMade is open, or in StillMade Desktop. StillMade has no server sandbox for
+them. A schedule or event that hands browser-only Steps to the owner's StillMade
+Desktop ("Run ... on my StillMade Desktop") pauses at a module Step until the
+owner's desktop app, open with "Run my automations on this computer" on, runs it
+with the Step's exact inputs; the workflow then continues from its result. Module
+Steps that call paid hosted operations, generate media or need a device grant
+still wait for the owner. Without that choice a background run stops before a
+module Step and the person runs it in the project. Marketplace listings show
+module Blocks as **Browser only**.
+
+### Live connections
+
+`stillmade.net.connect(url, {protocols})` opens a WebSocket to the `wss://` form
+of an origin in `permissions.network` (declare `https://stream.example.org` and
+connect to `wss://stream.example.org/...`) and resolves once it is open:
+
+```js
+const socket = await stillmade.net.connect('wss://stream.example.org/v1/live', { protocols: ['json.v1'] });
+await socket.send(JSON.stringify({ subscribe: input.channel }));
+for await (const data of socket) {            // text arrives as strings, binary as ArrayBuffers
+  stillmade.progress(0.5, 'Listening');       // each progress report extends the run limit
+  if (JSON.parse(data).done) break;          // leaving the loop closes the connection (code 1000)
+}
+```
+
+The socket also has `onmessage`, `onclose`, `addEventListener`, `readyState`,
+`protocol`, `close(code, reason)` (1000 or 3000 to 4999) and `closed`, a promise of
+`{code, reason, wasClean}`. `for await` yields every message not yet read, also ones
+that arrived before the loop began (up to 1,024 messages or 16 MiB; older ones are
+dropped). The module's own frame still has no network: StillMade
+checks each URL (`wss://`, the standard port, a declared origin, valid subprotocol
+names) and opens the connection in a separate relay frame that runs no Block code,
+then relays the messages. A run keeps at most 4 connections, sends or receives at
+most 1 MiB a message and 256 MiB in all, and every connection closes when the run
+ends. The service sees an opaque `Origin` (`null`). StillMade adds no key to a live
+connection: for a service that needs one, get a short-lived token with `net.fetch`
+first and pass it as the service documents.
+
+### Threads (SharedArrayBuffer)
+
+A module that runs its own Workers with shared memory (Emscripten pthreads,
+threaded WebAssembly builds) declares it in `module.json`:
+
+```json
+{ "entry": "main.js", "threads": true }
+```
+
+It then runs in a Worker that can share `SharedArrayBuffer` and
+`WebAssembly.Memory({shared: true})` with the Workers it starts from `blob:` URLs
+(module Workers and remote scripts stay unavailable, so bundle the thread code).
+That Worker is not a secure context, so it has no WebCodecs, WebGPU,
+`crypto.subtle` or `crypto.randomUUID`; a module without `threads` keeps those and
+cannot share memory between Workers. Threads work in Chrome and Edge (version 137
+or later) and in StillMade Desktop; in other browsers `self.crossOriginIsolated` is
+false and `SharedArrayBuffer` is missing, so check it and fall back to one thread.
+`files.write` and `storage.putFile` accept bytes in shared memory (they are copied).
 
 ### Test, pack and import
 
@@ -4000,6 +4067,7 @@ Standard and frame views receive the same `StillMade` object; members marked Fra
 | `previewMedia(value: StillMadeVideo \| StillMadeAudio): Promise<{kind: "video" \| "audio"; url: string}>` | Every view | A playable blob: URL for audio or video the view may play. Call releaseMedia when done. |
 | `releaseMedia(url: string): void` | Every view | Frees a URL previewMedia returned. |
 | `asset(path: string): string` | Frame views | A blob: URL for one of the view's own asset files, for <img>, new FontFace() or <video>. |
+| `readonly live: {start(options: {camera?: boolean; microphone?: boolean; fps?: number; width?: number; sampleRate?: number}): Promise<{live: true; camera: boolean; microphone: boolean; fps: number; width: number; height: number; sampleRate: number}>; stop(): Promise<{live: false}>; status(): Promise<{live: boolean; [key: string]: unknown}>; onFrame(callback: (frame: ImageBitmap, info: {index: number; timestamp: number; width: number; height: number}) => void): () => void; onAudio(callback: (samples: Float32Array, info: {index: number; timestamp: number; sampleRate: number}) => void): () => void; onEnd(callback: (event: {reason: string}) => void): () => void}` | Every view | The camera, the microphone or both as they happen (declare camera.capture and microphone.capture). Nothing reaches the view until the person presses Start in StillMade, which then shows that the device is on and a Turn off button. Frames arrive as ImageBitmaps, closed when your callback returns, so draw or copy them there; a slow view gets fewer frames, never a backlog. Audio arrives as mono Float32Array chunks. Nothing is saved. In browsers and StillMade Desktop. |
 | `assetBytes(path: string): ArrayBuffer` | Frame views | A copy of one of the view's own asset files. |
 
 ### Generated interface
@@ -4018,7 +4086,7 @@ Standard and frame views receive the same `StillMade` object; members marked Fra
 | `onSharedWorkRefresh(callback: () => void): () => void` | A saved project Step | Called when shared work changes elsewhere; read it again. |
 | `previewSharedWorkMedia(contributionId: string): Promise<{url: string; kind: "image" \| "video" \| "audio"}>` | A saved project Step | A display copy of media attached to a shared work contribution. |
 | `releaseSharedWorkMedia(url: string): void` | A saved project Step | Frees a URL previewSharedWorkMedia returned. |
-| `desktop(operation: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>` | Every view for recording; StillMade Desktop for the rest | Runs a declared desktop permission after the person grants it. Recording (record.start, record.stop, record.cancel, record.status) and cutting a recording (record.cut) work in browsers and in StillMade Desktop; clipboard, media.pick, notifications, keep-awake and native tools need StillMade Desktop. |
+| `desktop(operation: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>` | Every view for recording and folders; StillMade Desktop for the rest | Runs a declared desktop permission after the person grants it. Recording (record.start, record.stop, record.cancel, record.status), cutting a recording (record.cut) and folders the person picks (folder.*; Chrome and Edge in a browser) work in browsers and in StillMade Desktop; clipboard, media.pick, notifications, keep-awake and native tools need StillMade Desktop. Picking or pressing Start is the consent; StillMade asks once only about the clipboard, the cursor and desktop programs. |
 
 ## StillMade Blocks and the SDK
 
@@ -4304,6 +4372,17 @@ Every number below is read from the SDK constant named under its heading, the sa
 | Requests per minute to one origin (everyone) | 3,000 |
 | Saved key length | 4,096 |
 
+### Live connections (net.connect)
+
+`SOCKET_LIMITS`
+
+| Limit | Value |
+| --- | --- |
+| Open connections per run | 4 |
+| One message, either way | 1 MiB |
+| All messages in one run | 256 MiB |
+| Subprotocol names | 8 |
+
 ### Cloud storage
 
 `CLOUD_STORAGE_LIMITS`
@@ -6045,7 +6124,7 @@ export const VIEW_LIMITS: Readonly<{htmlBytes:65536;cssBytes:32768;javascriptByt
 export interface BlockImagePreview { url: `data:image/png;base64,${string}`; width: number; height: number; }
 export interface BlockImagePixels { width: number; height: number; data: number[]; role?: string; }
 export interface BlockImageReference { kind: 'image'; assetId: string; versionId: string; url: string; role?: string; }
-export type DesktopPermission = "screen.capture"|"cursor.track"|"camera.capture"|"microphone.capture"|"clipboard.read"|"clipboard.write"|"media.pick"|"notifications.show"|"power.keep-awake"|"native.tools";
+export type DesktopPermission = "screen.capture"|"cursor.track"|"camera.capture"|"microphone.capture"|"clipboard.read"|"clipboard.write"|"media.pick"|"notifications.show"|"power.keep-awake"|"native.tools"|"folder.read"|"folder.write";
 export type DesktopToolDeclaration = {id:'org.natron.Natron';adapterVersion:1;actions:('launch'|'project.import'|'project.open'|'project.render')[]} | {id:'org.stillmade.PythonAdapter';adapterVersion:1;actions:('adapter.import'|'adapter.inspect'|'adapter.execute'|'adapter.describe'|'adapter.call')[]};
 export type DesktopExecution = {schemaVersion:1;tool:'org.natron.Natron';action:'project.render';arguments:Record<'projectId'|'input'|'reader'|'writer'|'firstFrame'|'lastFrame',{input:string}>;outputs:Record<string,'asset'>} | {schemaVersion:1;tool:'org.stillmade.PythonAdapter';action:'adapter.execute';arguments:Record<'adapterId'|'sourceDigest'|'functionId'|'input',{input:string}>;outputs:Record<string,'result'>} | {schemaVersion:2;tool:'org.stillmade.PythonAdapter';action:'adapter.call';source:{code:string;digest:string;license:string};functionId:string;arguments:Record<string,{input:string}>;outputs:{result:'result'}};
 export interface DesktopExecutionRequest {schemaVersion:1;requestId:string;packageDigest:string;inputDigest:string;tools:DesktopToolDeclaration[]}
@@ -6070,7 +6149,7 @@ export interface BlockViewNode { tag: BlockViewTag; text?: string; children?: Bl
 export interface BlockViewAction { action: string; value: string; checked: boolean; event: 'click'|'input'|'change'; }
 export interface BlockMediaReference { kind: 'video'|'audio'; assetId: string; versionId: string; url: string; role?: string; }
 export interface BlockMediaPreview { kind: 'video'|'audio'; url: string; mimeType: string; bytes: number; }
-export interface BlockViewBridge { useOutput(outputs: Record<string, BlockMediaReference|BlockMediaReference[]>): Promise<Record<string, unknown>>; previewMedia(value: BlockMediaReference): Promise<BlockMediaPreview>; releaseMedia(url: string): void; render(targetId: string, tree: BlockViewNode[]): void; onAction(callback: (event: BlockViewAction) => void|Promise<void>): () => void; desktop(operation: DesktopPermission|DesktopToolOperation|import('./block-storage.js').BlockStorageOperation|"record.start"|"record.stop"|"record.cancel"|"session.close", args?: Record<string,unknown>): Promise<Record<string,unknown>>; readonly input: Record<string, unknown>; onInput(callback: (input: Record<string, unknown>) => void): () => void; run(input: Record<string, unknown>): Promise<Record<string, unknown>>; previewImage(value: BlockImageReference|BlockImagePixels): Promise<BlockImagePreview>; }
+export interface BlockViewBridge { useOutput(outputs: Record<string, BlockMediaReference|BlockMediaReference[]>): Promise<Record<string, unknown>>; previewMedia(value: BlockMediaReference): Promise<BlockMediaPreview>; releaseMedia(url: string): void; render(targetId: string, tree: BlockViewNode[]): void; onAction(callback: (event: BlockViewAction) => void|Promise<void>): () => void; desktop(operation: DesktopPermission|DesktopToolOperation|import('./block-storage.js').BlockStorageOperation|"record.start"|"record.stop"|"record.cancel"|"session.close"|"live.start"|"live.stop"|"live.status"|"folder.pick"|"folder.shared"|"folder.forget"|"folder.list", args?: Record<string,unknown>): Promise<Record<string,unknown>>; readonly input: Record<string, unknown>; onInput(callback: (input: Record<string, unknown>) => void): () => void; run(input: Record<string, unknown>): Promise<Record<string, unknown>>; previewImage(value: BlockImageReference|BlockImagePixels): Promise<BlockImagePreview>; }
 
 /** Validate hosted UI colors independently of the preserved original stylesheet. */
 export function validateViewAppearance(view?: BlockView, options?: {appearance?:'host'|'original'}): true;
@@ -6476,9 +6555,14 @@ export interface ConnectionConfigurationResult {schemaVersion:1;operation:'reloa
 export function configuredConnectionBlock(app:ConnectedAppMetadata,route:ConnectedTaskMetadata,basePackage:BlockPackage,configuration:ConnectionConfigurationResult):Promise<BlockPackage>;
 export function validateConnectedCapability(capability:ConnectedCapability,manifest:Manifest):true;
 export function prepareConnectedInvocation(pkg:BlockPackage,raw:Record<string,unknown>):{operation:'connection.execute';appId:string;capabilityId:string;pin:ConnectionPin;input:Record<string,unknown>};
-export interface SchemaFields {currencyDigits(currency:string):number;minorUnits(decimal:string,currency:string):number;formatMoney(minor:number,currency:string):string;preview(value:unknown,options?:{maximumFields?:number}):BlockViewNode[];read(root:unknown,path:Array<string|number>):unknown;set(root:unknown,path:Array<string|number>,value:unknown):Record<string,unknown>;controls(schema:Record<string,unknown>,bindings:Record<string,string>,values:Record<string,unknown>,options?:{canEdit?:boolean;busy?:boolean}):{tree:unknown[];actions:unknown[]};change(values:Record<string,unknown>,actions:unknown[],event:unknown):Record<string,unknown>;fromState(input:Record<string,unknown>,state:Record<string,unknown>,bindings:Record<string,string>):Record<string,unknown>;edits(values:Record<string,unknown>,state:Record<string,unknown>,bindings:Record<string,string>):{patch:Record<string,unknown>;before:Record<string,unknown>;changed:boolean}}
+export interface SchemaFields {currencyDigits(currency:string):number;minorUnits(decimal:string,currency:string):number;formatMoney(minor:number,currency:string):string;preview(value:unknown,options?:{maximumFields?:number}):BlockViewNode[];read(root:unknown,path:Array<string|number>):unknown;set(root:unknown,path:Array<string|number>,value:unknown):Record<string,unknown>;controls(schema:Record<string,unknown>,bindings:Record<string,string>,values:Record<string,unknown>,options?:{canEdit?:boolean;busy?:boolean;more?:string[];hide?:string[]}):{tree:unknown[];actions:unknown[]};change(values:Record<string,unknown>,actions:unknown[],event:unknown):Record<string,unknown>;fromState(input:Record<string,unknown>,state:Record<string,unknown>,bindings:Record<string,string>):Record<string,unknown>;edits(values:Record<string,unknown>,state:Record<string,unknown>,bindings:Record<string,string>):{patch:Record<string,unknown>;before:Record<string,unknown>;changed:boolean}}
 export function createSchemaFields(lockedInputKeys?:string[]):Readonly<SchemaFields>;
 export interface BlockViewBridge {schemaFields:Readonly<SchemaFields>}
+export interface BlockLiveFrameInfo {index:number;timestamp:number;width:number;height:number}
+export interface BlockLiveAudioInfo {index:number;timestamp:number;sampleRate:number}
+/** The camera and microphone as they happen (`camera.capture`, `microphone.capture`); nothing reaches the view before the person presses Start. */
+export interface BlockLiveFeed {start(options:{camera?:boolean;microphone?:boolean;fps?:number;width?:number;sampleRate?:number}):Promise<{live:true;camera:boolean;microphone:boolean;fps:number;width:number;height:number;sampleRate:number}>;stop():Promise<{live:false}>;status():Promise<{live:boolean;[key:string]:unknown}>;onFrame(callback:(frame:ImageBitmap,info:BlockLiveFrameInfo)=>void):()=>void;onAudio(callback:(samples:Float32Array,info:BlockLiveAudioInfo)=>void):()=>void;onEnd(callback:(event:{reason:string})=>void):()=>void}
+export interface BlockViewBridge {readonly live:BlockLiveFeed}
 
 export interface ConnectionReferencePointer {id:string;version:string}
 export interface ConnectionReferenceField {path:Array<string|number>;value:string|number|boolean|null}
@@ -6518,7 +6602,9 @@ export function parseJsonReply(text: string): unknown;
 
 /** Runtime `module`: an ES module (with optional WebAssembly and data files) named by SHA-256. */
 export interface ModuleFile { sha256: string; bytes: number; mediaType: 'text/javascript'|'application/wasm'|'application/json'|'text/plain'|'image/png'|'image/jpeg'|'image/webp'|'font/woff2'|'application/octet-stream'; }
-export interface ModuleDescriptor { schemaVersion: 1; entry: string; files: Record<string, ModuleFile>; }
+export interface ModuleDescriptor { schemaVersion: 1; entry: string; files: Record<string, ModuleFile>; /** Run in a Worker that shares memory with the Workers it starts (no WebCodecs, WebGPU or crypto.subtle). */ threads?: true; }
+/** A live WebSocket a module opened with stillmade.net.connect. */
+export interface ModuleLiveSocket { url: string; protocol: string; readonly readyState: number; onmessage: ((event: {data: string | ArrayBuffer}) => void) | null; onclose: ((event: {code: number; reason: string; wasClean: boolean}) => void) | null; send(data: string | ArrayBuffer | ArrayBufferView | Blob): Promise<unknown>; close(code?: number, reason?: string): Promise<{code: number; reason: string; wasClean: boolean}>; closed: Promise<{code: number; reason: string; wasClean: boolean}>; addEventListener(type: 'message' | 'close', listener: (event: Event & Record<string, unknown>) => void): void; removeEventListener(type: 'message' | 'close', listener: (event: Event & Record<string, unknown>) => void): void; [Symbol.asyncIterator](): AsyncIterator<string | ArrayBuffer>}
 export const MODULE_RUNTIME_VERSION: 1;
 export const MODULE_LIMITS: Readonly<{files:64;fileBytes:67108864;totalBytes:134217728;path:160;wallClockMs:120000;maxWallClockMs:1800000;progressGraceMs:60000;messageBytes:16777216;logEntries:500}>;
 export const MODULE_MEDIA_TYPES: readonly ModuleFile['mediaType'][];
@@ -6544,8 +6630,8 @@ export interface ModuleHost {
   media: { transform(request: MediaTransformRequest): Promise<SavedMediaRef|DecodedAudio>; };
   actions: { run(action: Record<string, unknown>): Promise<unknown>; };
   hosted: { run(operation: string, request: Record<string, unknown>): Promise<unknown>; };
-  /** Declared-origin network calls; StillMade adds the person's own key. */
-  net: { fetch(url: string|URL, init?: {method?: string; headers?: Record<string,string>|[string,string][]; body?: ArrayBuffer|ArrayBufferView|Blob|string}): Promise<Response>; };
+  /** Declared-origin network calls; StillMade adds the person's own key. `connect` opens a live WebSocket to a declared origin's wss:// form (no key). */
+  net: { fetch(url: string|URL, init?: {method?: string; headers?: Record<string,string>|[string,string][]; body?: ArrayBuffer|ArrayBufferView|Blob|string}): Promise<Response>; connect(url: string|URL, options?: {protocols?: string|string[]}): Promise<ModuleLiveSocket>; };
   /** Published adapter operations, with the person's own account. */
   connections: { call(appId: string, operation: string, input?: Record<string, unknown>): Promise<unknown>; };
   /** The Block's cloud storage in this project (manifest `storage`). */
@@ -6602,6 +6688,25 @@ export const NATIVE_APPLICATION_RUNTIME_REQUIREMENT:string;
 /** Validates a native application package's strict source syntax and returns its detached, frozen copy. Throws NATIVE_APPLICATION_PACKAGE errors. Not runtime admission. */
 export function defineNativeApplicationPackage<T=unknown>(value:T):T;
 export function validateNativeApplicationPackage(value:unknown):true;
+export const PERMISSION_LEVELS:readonly ["none","low","medium","high"];
+export type PermissionLevel="none"|"low"|"medium"|"high";
+export interface PermissionLine { id:string; text:string; level:PermissionLevel; family:"project"|"service"|"network"|"device" }
+/** What a Block can do, in plain words, with the level of care it needs. The host refuses anything a Block did not declare, so this is all it can reach. */
+export function summarizePermissions(manifest:Manifest):{ level:PermissionLevel; lines:PermissionLine[]; dataLeaves:boolean; staysInStillMade:boolean; headline:string };
+/** What an update adds or removes, by line, and whether its level rose. */
+export function permissionChanges(previous:Manifest,next:Manifest):{ added:PermissionLine[]; removed:PermissionLine[]; levelRaised:boolean; before:ReturnType<typeof summarizePermissions>; after:ReturnType<typeof summarizePermissions> };
+/** What a Block's source uses compared with its manifest: desktop operations and network origins used but not declared, or declared and never used. Advice from literal names; never a gate. */
+export function permissionUsage(pkg:BlockPackage,files?:Record<string,Uint8Array|string>):{ desktop:string[]; origins:string[]; undeclared:{family:"desktop"|"network";scope:string}[]; unused:{family:"desktop"|"network";scope:string}[] };
+/** The manifest declaring what the source uses and nothing else. */
+export function fixPermissions(manifest:Manifest,usage:ReturnType<typeof permissionUsage>):Manifest;
+/** The package for a Block folder (the layout stillmade-block create writes), from its files. Shared by the CLI and StillMade's Import folder. */
+export function packageFromFolder(source:{ read(path:string):Promise<Uint8Array|undefined>; list(prefix:string):Promise<Record<string,Uint8Array>> }):Promise<{ pkg:BlockPackage; files:Record<string,Uint8Array>|null }>;
+/** Whether a path inside a Block folder is part of the Block (node_modules, build output and notes are not). */
+export function blockFolderPath(path:string):boolean;
+/** The manifest file at the root of a Block folder. */
+export const BLOCK_FOLDER_MANIFEST:"stillmade.block.json";
+/** Size limits for Block folder source files, in bytes. */
+export const BLOCK_FOLDER_LIMITS:Readonly<{jsonBytes:4000000;javascriptBytes:262144;viewScriptBytes:4194304;viewSourceBytes:262144}>;
 
 ```
 
@@ -6753,7 +6858,7 @@ A portable image reference is not decoded pixel data. The host must resolve it b
 5. Test actual supported media in the host workspace.
 
 ### Every SDK error code
-Generated from the SDK source (197 codes). The message is one example; the actual message names the exact field or limit.
+Generated from the SDK source (198 codes). The message is one example; the actual message names the exact field or limit.
 
 | Code | Example message | Raised in |
 | --- | --- | --- |
@@ -6788,12 +6893,11 @@ Generated from the SDK source (197 codes). The message is one example; the actua
 | 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` |
-| BEHAVIOR | Output differs from expected fixture. Expected …; received … | `testing` |
 | 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 7 more |
+| 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` |
@@ -6865,13 +6969,15 @@ Generated from the SDK source (197 codes). The message is one example; the actua
 | 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 | … has the sections … | `mock-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_FILE | … is missing from the local files | `module-node`, `module-runtime` |
+| 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_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` |
@@ -7241,9 +7347,9 @@ Ask the assistant to return source files or one `.stillmade.json` package. Run t
 
 <!-- builder-contract:start (generated by npm run build:sdk; do not edit) -->
 
-### Block builder contract (stillmade.block-builder@1.7.1)
+### Block builder contract (stillmade.block-builder@1.10.0)
 
-Contract `stillmade.block-builder@1.7.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.10.0`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 
 ### Source of truth
 
@@ -7257,6 +7363,10 @@ Before building, check what already exists (`find_existing_blocks` over MCP, or
 
 Blocks come in three sizes and the manifest decides which (packages/block-sdk/block-tier.js): an app is a workspace a person works in (Editor, Canvas, Shots), placed in a Type and never wired automatically; a job is one deliverable a person would name (the narration, the captioned clip), built from the hosted operations it needs (`permissions.capabilities`) and reviewed in one place, the unit Chat picks for a Step; an ingredient is one hosted operation with nothing of its own (a declarative capability Block), what a job is made of. When two ingredients would stand in a row to make one deliverable (writing the words, then voicing them), build or pick the job that does both and keep the review point inside it. A job declares a second output when another Block consumes the intermediate (the script beside the voice); split into two jobs only when the intermediate has a life of its own or the halves have different owners or payment.
 
+### Choose the runtime
+
+Pick the runtime from the job. No hosted AI: a recipe or isolated `javascript`, both able to run unattended. One text, script or brief prompt returning text, script or JSON: a `capability` Block. Hosted operations on other values (a transcript, media, structured data), several hosted operations in a row, or a result shaped in code: one `module` Block, `module/main.js` calling `stillmade.hosted.run(operation, request)` for each operation in `permissions.capabilities` (MODULES.md), never one Block per operation; it runs in the person's browser while StillMade is open. Build a new Block in a folder with `stillmade-block create`, `test`, `ready` and `pack`, and import the file `pack` writes (a module Block writes `<id>-<version>.stillmade-module.json`) through Create, then Import Block. A `.stillmade-block` archive is only for adapting a GitHub repository.
+
 ### One job per Step
 
 A Step is one job: the work between two moments where a person or the outside world must see the result. Start a new Step only at one of three points; everything else is a part of the neighboring Step.
@@ -7269,7 +7379,7 @@ In a production the Steps are the workspaces a person opens: work feeding the ne
 
 A part that only runs in the desktop app cannot share a Step with cloud parts. Before adding a Step, name which of the three reasons makes it separate; if none applies, make it a part of a neighbor. A Step nobody would ever open must not exist on its own. Prefer an app task's own filter (a Gmail query such as `has:attachment filename:png`) to an AI check, and use AI decide only for judgement.
 
-Inside one job, each capability stays its own part: a capability Block performs exactly one hosted operation and a connector one app task, so every part keeps its own permission, approval and credit rules, and StillMade groups the parts of one job into one Step (`groups` in the Project Type). Never invent a combined runtime. When one Block can do the whole job with documented primitives (a JavaScript Block doing several local transforms, a workspace owning its whole document), build it as one Block.
+Build one Block for a job one Block can do: a module Block calls every hosted operation the job needs (it transcribes a sermon, then finds the verses said in it), a JavaScript Block does several local transforms, a workspace owns its whole document. A Block being built never takes an ingredient's result only so the ingredient can be its own part or Step (Transcribe in front of a verse finder): it calls that operation itself. Parts in one Step (`groups` in the Project Type) are for jobs made of Blocks that already exist and app tasks, each keeping its own permission, approval and credit rules. Never invent a combined runtime.
 
 Examples: "every new email with an image becomes a generated image" is two Steps, "Gmail · New emails with images" (When, fetch with an image filter, only new) and "Image from email" (AI write, Generate image); listing When, Fetch, Only new, AI decide, Continue only if, AI write and Generate image as seven Steps splits one job into its parts. "A new Meta lead goes to HubSpot" is three Steps: "Meta Ads · New leads", "Qualify lead" and "HubSpot · Add contact".
 
@@ -7307,7 +7417,7 @@ Projects are multiplayer. A custom view subscribes through `StillMade.onShared(c
 
 ### External services
 
-Reach external services only through StillMade's hosted operations, the connections service (`connection.execute`), or, in a module Block, `stillmade.net.fetch` to origins declared in `permissions.network` (with the key each needs) and `stillmade.connections.call` to adapters or catalog apps in `permissions.connections`; never put keys in code, inputs or headers: StillMade adds each person's own key on its servers. The host owns the model and provider choice, BYOK keys, StillMade credits, spending consent, authorization, token refresh, rate limits, retries and provider errors; a Block never receives a secret and never names a provider unless it must. Treat provider unavailability, timeout, cancellation and partial failure as typed outcomes the Block reports, not crashes. Generated images, video, voices, music and sound effects come from hosted operations or the `media.generate` action, paid with the user's StillMade credits at StillMade's prices; for structured model output declare a `json` output with `capability.schema` instead of parsing prose. When a Block needs npm libraries, WebAssembly or heavy compute, use `runtime: "module"` and reach hosted operations through `stillmade.hosted.run` with the operations listed in `permissions.capabilities`. Decode, cut, join, re-encode, extract or normalise audio and video with `stillmade.media.transform` on the device; never ask for a server render. For a rich interactive interface (React or another framework, SVG, canvas, drag), use a frame view: `src/view.config.json` with `{"runtime":"frame"}` and `src/view.js` bundled as one IIFE, colored with StillMade's theme variables. For files and structured data use the `file`, `document`, `table`, `url`, `date` and `color` types and their generated controls and presentations, not JSON text.
+Reach external services only through StillMade's hosted operations, the connections service (`connection.execute`), or, in a module Block, `stillmade.net.fetch` to origins declared in `permissions.network` (with the key each needs), `stillmade.net.connect` for a live WebSocket to one of them, and `stillmade.connections.call` to adapters or catalog apps in `permissions.connections`; never put keys in code, inputs or headers: StillMade adds each person's own key on its servers. The host owns the model and provider choice, BYOK keys, StillMade credits, spending consent, authorization, token refresh, rate limits, retries and provider errors; a Block never receives a secret and never names a provider unless it must. Treat provider unavailability, timeout, cancellation and partial failure as typed outcomes the Block reports, not crashes. Generated images, video, voices, music and sound effects come from hosted operations or the `media.generate` action, paid with the user's StillMade credits at StillMade's prices; for structured model output declare a `json` output with `capability.schema` instead of parsing prose. When a Block needs npm libraries, WebAssembly (threaded: `"threads": true` in module.json) or heavy compute, use `runtime: "module"` and reach hosted operations through `stillmade.hosted.run` with the operations listed in `permissions.capabilities`. Decode, cut, join, re-encode, extract or normalise audio and video with `stillmade.media.transform` on the device; never ask for a server render. For a rich interactive interface (React or another framework, SVG, canvas, drag), use a frame view: `src/view.config.json` with `{"runtime":"frame"}` and `src/view.js` bundled as one IIFE, colored with StillMade's theme variables. For files and structured data use the `file`, `document`, `table`, `url`, `date` and `color` types and their generated controls and presentations, not JSON text.
 
 ### Dependencies
 
@@ -7315,7 +7425,7 @@ A Block must declare everything it requires and must not assume anything is inst
 
 ### Security
 
-Treat Block code, external data, files, repositories, model output and network responses as untrusted. Request the minimum permissions and capabilities. Do not weaken the sandbox (QuickJS has no fetch, DOM, timers, modules or Node APIs). Validate and bound every value crossing a boundary. Never expose secrets through logs, outputs, project context, UI, error messages or serialized state.
+Treat Block code, external data, files, repositories, model output and network responses as untrusted. Request the minimum permissions and capabilities; `stillmade-block permissions --fix` declares exactly what the source uses. Do not weaken the sandbox (QuickJS has no fetch, DOM, timers, modules or Node APIs). Validate and bound every value crossing a boundary. Never expose secrets through logs, outputs, project context, UI, error messages or serialized state.
 
 ### Execution lifecycle
 
@@ -7417,7 +7527,11 @@ For image generation, use runtime:"capability", operation:"image.generate" and p
 For image analysis, use runtime:"capability", operation:"image.describe" and permissions.capabilities:["image.describe"]. Declare one primary image input (or one image[] input of one to four images to compare together) and one primary text output. capability.image references the input; capability.instruction contains bounded package-owned analysis instructions; capability.maxTokens is 1–4096; capability.output names the text output. The host loads only owned media and controls provider, model, payment and approval. Tests use bounded RGBA pixels and nondeterministic text expectations, never invented live descriptions. Shipped example: {"manifest":{"schemaVersion":1,"sdkVersion":"0.1.0","id":"example.describe-image","version":"1.0.0","name":"Describe an image","description":"Turn one owned image into concise production-ready visual notes.","kind":"task","runtime":"capability","entry":"src/capability.json","license":"MIT","provenance":{"notice":"MIT License\n\nCopyright (c) 2026 StillMade SDK contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and \nassociated documentation files (the \"Software\"), to deal in the Software without restriction, including \nwithout limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell \ncopies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the \nfollowing conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial \nportions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT \nLIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO \nEVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER \nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE \nUSE OR OTHER DEALINGS IN THE SOFTWARE.\n"},"inputs":{"image":{"type":"image","primary":true,"semantic":"source_image","required":true,"description":"Owned image to inspect for visible production details."}},"outputs":{"description":{"type":"text","primary":true,"role":"visual_description","semantic":"visual_description","description":"Concise production notes based only on visible image details."}},"permissions":{"project":[],"capabilities":["image.describe"],"network":[],"filesystem":[],"secrets":[]},"ui":[{"control":"asset","port":"image"}]},"capability":{"schemaVersion":1,"operation":"image.describe","image":{"$input":"image"},"instruction":"Describe only visibly supported subject matter, composition, lighting, color, texture, camera feel and visual style. Return concise production-ready plain text.","maxTokens":700,"output":"description"},"tests":[{"name":"Blue image","input":{"image":{"width":1,"height":1,"data":[20,80,200,255]}},"expectations":{"description":{"kind":"text","minLength":20,"maxLength":32768,"includes":["blue"]}}}]}.
 For AI-directed editing, use runtime:"capability", operation:"timeline.propose" and permissions.capabilities:["timeline.propose"]. Declare one current timeline input, up to three additional typed context inputs, and one timeline-edit output. Bind every input exactly once through capability.context; declare context.timeline.read and timeline.propose. StillMade controls the provider, strict JSON validation, stale-before checks, preview and Apply. Tests declare timeline-edit command bounds, never fabricated provider results. Shipped example: {"manifest":{"schemaVersion":1,"sdkVersion":"0.1.0","id":"example.timeline-polish","version":"1.0.0","name":"Timeline polish","description":"Turn a timeline and editing direction into a bounded proposal that remains reviewable before Apply.","kind":"task","runtime":"capability","entry":"src/capability.json","license":"MIT","provenance":{"notice":"MIT License\n\nCopyright (c) 2026 StillMade SDK contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and \nassociated documentation files (the \"Software\"), to deal in the Software without restriction, including \nwithout limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell \ncopies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the \nfollowing conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial \nportions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT \nLIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO \nEVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER \nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE \nUSE OR OTHER DEALINGS IN THE SOFTWARE.\n"},"inputs":{"timeline":{"type":"timeline","context":"timeline","primary":true},"direction":{"type":"text","default":"Polish this cut conservatively."}},"outputs":{"edit":{"type":"timeline-edit","primary":true}},"permissions":{"project":["context.timeline.read","timeline.propose"],"capabilities":["timeline.propose"],"network":[],"filesystem":[],"secrets":[]},"ui":[{"control":"text","port":"direction"}]},"capability":{"schemaVersion":1,"operation":"timeline.propose","context":{"timeline":{"$input":"timeline"},"direction":{"$input":"direction"}},"instruction":"Use only supported timeline-edit commands, exact before snapshots, and the current activeTimelineId. Preserve media and locked items. Return strict JSON only.","maxTokens":2000,"output":"edit"},"tests":[{"name":"one restrained edit","input":{"timeline":{"schemaVersion":1,"activeTimelineId":"timeline-1","tracks":[{"id":"video"}],"clips":[{"id":"clip-1","trackId":"video","start":0,"duration":4}],"audioItems":[],"captions":[]},"direction":"Add a soft transition."},"expectations":{"edit":{"kind":"timeline-edit","minCommands":1,"maxCommands":10}}}]}.
 For video generation use runtime:"capability", operation:"video.generate", permissions.capabilities:["video.generate"], one primary text input and one primary video output. capability.prompt references the input and capability.output names the output. Prompt limit 32000. Tests declare MP4 duration, dimensions and byte bounds; never fabricate video URLs. The enabled host selects its supported model, duration, resolution, payment and approved quote; packages cannot choose provider settings or dispatch jobs. Shipped example: {"manifest":{"schemaVersion":1,"id":"example.generate-video","name":"Generate video","version":"1.0.0","sdkVersion":"0.1.0","description":"Turn a production prompt into a short video using an approved host provider.","kind":"task","runtime":"capability","entry":"src/capability.json","license":"MIT","provenance":{"notice":"MIT License\n\nCopyright (c) 2026 StillMade SDK contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and \nassociated documentation files (the \"Software\"), to deal in the Software without restriction, including \nwithout limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell \ncopies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the \nfollowing conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial \nportions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT \nLIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO \nEVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER \nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE \nUSE OR OTHER DEALINGS IN THE SOFTWARE.\n"},"inputs":{"prompt":{"type":"text","primary":true,"required":true}},"outputs":{"video":{"type":"video","primary":true}},"permissions":{"project":[],"capabilities":["video.generate"],"network":[],"filesystem":[],"secrets":[]},"ui":[{"port":"prompt","control":"text"}]},"capability":{"schemaVersion":1,"operation":"video.generate","prompt":{"$input":"prompt"},"output":"video"},"tests":[{"name":"Produces a bounded MP4 sample","input":{"prompt":"A paper boat floating across a calm blue pond. Gentle camera movement."},"expectations":{"video":{"kind":"video","format":"mp4","minDuration":1,"maxDuration":60,"minBytes":32,"maxBytes":67108864,"minWidth":1,"maxWidth":3840,"minHeight":1,"maxHeight":3840}}}]}.
-Each capability package performs one supported operation. A job that needs several operations is built from parts: return each operation as its own part Block, and StillMade groups the parts of one job into one Step (One job per Step); never invent a combined runtime. Hosted image, speech and video source can be statically validated while authoring, but real fixture/sample generation requires the user's subsequent model/payment selection and quote confirmation. Do not claim those calls ran. Deterministic image transformations should remain sandboxed recipe or JavaScript code when supported; do not generate a new image as a substitute for processing an existing one.
+A capability package performs exactly one supported operation. A job that needs several (transcribe a recording, then find what is said in it; write words, then voice them), or code between two operations, is one module Block that calls each with stillmade.hosted.run (Module Blocks); never split one job into part Blocks, and never invent a combined capability runtime. Hosted image, speech and video source can be statically validated while authoring, but real fixture/sample generation requires the user's subsequent model/payment selection and quote confirmation. Do not claim those calls ran. Deterministic image transformations should remain sandboxed recipe or JavaScript code when supported; do not generate a new image as a substitute for processing an existing one.
+
+### Module Blocks
+
+A job that needs several hosted operations, or code around one (reading a transcript's words and times, shaping a list), is a module Block: {manifest,moduleSource,tests}, runtime:"module", moduleSource:{"main.js":"<the code>"}. StillMade names main.js by its digest and adds module; give no other files. main.js is plain JavaScript that imports nothing and uses no browser APIs (no fetch, TextEncoder, timers or WebCodecs): export default async function run(input, stillmade) returns the declared outputs. It calls each hosted operation with await stillmade.hosted.run(operation, request), listed in manifest.permissions.capabilities: text.generate, image.generate, video.generate, audio.speech, audio.music, audio.sfx, audio.transcribe, image.describe, media.analyze, web.fetch, web.research. Requests, and what each call returns (a test's mocks record exactly that value): text.generate {prompt, system, maxTokens} returns the text as a string, and with schema (a JSON schema object) returns that object, so ask for JSON with schema; audio.transcribe {audio: the input's saved reference, language:"auto"} returns {schemaVersion:1,text,words:[{text,start,end}]}; image.generate {prompt} and audio.speech {text} return a saved image or audio reference; image.describe {image, instruction} and web.fetch {url, instruction} return a string; media.analyze {media, question} returns {items:[...]}; web.research {topic} returns {summary,sources}. A call that fails throws: let it fail the run rather than catching it and returning an empty result. Media work on the person's device (cut, join or resize video, decode or extract audio, thumbnails) is await stillmade.media.transform(request); exporting is too: {operation:"timeline.render",kind:"video" or "audio",aspect:"9:16",clips:[{source,start,duration,from,transition:{type:"Fade"},look:"Filmic"}],audio:[{source,start,duration}],captions:[{text,start,end,words:[{text,start,end}],highlight:"#ffd400"}]} renders the Block's own timeline with the Editor's transitions, looks and word-by-word captions under the person's export plan, so never ask for a separate export, captions or color Block; stillmade.log and stillmade.progress(fraction, label) report. One press of the Step's button runs every call at the price shown beside it. A module Block runs in the person's browser while StillMade is open, never on a schedule or event. Tests are {name,input,expected,mocks}: mocks records what each call answers, as {hosted:{"audio.transcribe":{schemaVersion:1,text:"...",words:[...]},"text.generate":{...}},transforms:{...}} (a list answers successive calls in order), and expected is the exact output main.js returns for those answers. StillMade runs every test before anyone sees the Block, without spending credits. With the SDK instead, the same code is module/main.js in a Block folder and the same tests are tests/fixtures.json; stillmade-block pack writes the file to import (MODULES.md).
 
 ### ComfyUI workflows
 
@@ -10682,9 +10796,16 @@ Offline `validate`, `test`, `pack`, `admitLocalPackage` and `admitPackage` witho
 
 # Desktop capabilities for Blocks
 
-Recording runs 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); in StillMade Desktop the native host gives consent and picks the source. Every other scope below needs StillMade Desktop.
+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.
 
-The desktop host implements these capabilities on demand. Importing a Block, installing StillMade, or opening a preview does not request device permissions. The first operation displays StillMade's native consent dialog identifying the Block ID and version. An OS prompt may follow. Grants last for the mounted Block workspace, up to one hour; closing/reloading it or revoking access ends that grant. Imported UI receives neither native IPC nor grant tokens.
+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.
 
@@ -10692,14 +10813,16 @@ Declare the exact required scopes in `manifest.permissions.desktop`. Other permi
 | --- | --- | --- |
 | `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"}` | Camera recording after device/OS approval. Browser and desktop. |
-| `microphone.capture` | `record.start`, `{kind:"microphone"}`, or `{kind:"screen", microphone:true}` | Microphone recording after device/OS approval, or the microphone mixed into a screen recording. Browser and desktop. |
+| `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.
 
@@ -10719,6 +10842,72 @@ Natron adapter version 1 currently exposes `launch`, `project.import`, `project.
 
 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](/docs/reference/desktop-execution) 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](/block-sdk/examples/screen-recorder.stillmade.json), [Camera recorder](/block-sdk/examples/camera-recorder.stillmade.json), or [Microphone recorder](/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.
@@ -10758,7 +10947,7 @@ stop.addEventListener('click', async () => {
 });
 ```
 
-Every recording in a browser, and a screen recording on desktop, begins from StillMade's own Start button outside the Block interface (labelled for the screen, camera or microphone): a view never reaches a device by itself, and the site's standing camera or microphone permission is not consent for a Block. On desktop, camera and microphone recordings begin after StillMade's consent dialog naming the Block.
+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.
 
@@ -10768,7 +10957,7 @@ Every recording in a browser, and a screen recording on desktop, begins from Sti
 
 `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.
+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
 
@@ -11990,7 +12179,7 @@ Every manifest declares `permissions` with these families. Anything not declared
 | capabilities | Exactly one hosted operation for `runtime: "capability"` (`text.generate`, `audio.speech`, `audio.transcribe`, `audio.music`, `audio.sfx`, `image.generate`, `video.generate`, `image.describe`, `media.analyze`, `web.fetch`, `web.research`, `timeline.propose`, `workspace.propose`, `connection.execute`), or `comfyui.execute` for `runtime: "comfyui"`. See [runtime capabilities](/docs/reference/capabilities). |
 | actions | Portable media actions below, for `runtime: "javascript"` or `"module"` |
 | desktop | Desktop permissions below, used through the host desktop bridge |
-| network | For `runtime: "module"`: up to 8 exact https origins the Block calls with `stillmade.net.fetch`, each optionally with the key it needs (`{origin, auth: {scheme: "bearer" \| "header" \| "query" \| "oauth2", name or app, label, help}}`). People add their own key or sign in once per Block; the host adds it on its servers. Other runtimes: empty. See [Outside APIs](/docs/build/outside-apis). |
+| network | For `runtime: "module"`: up to 8 exact https origins the Block calls with `stillmade.net.fetch` (and opens live WebSockets to with `stillmade.net.connect`, at their `wss://` form), each optionally with the key it needs (`{origin, auth: {scheme: "bearer" \| "header" \| "query" \| "oauth2", name or app, label, help}}`). People add their own key or sign in once per Block; the host adds it on its servers. Other runtimes: empty. See [Outside APIs](/docs/build/outside-apis). |
 | connections | For `runtime: "module"`: up to 8 published adapters by app ID (`app:openapi:notion`), called with `stillmade.connections.call`. Other runtimes: empty. |
 | filesystem, secrets | Must be empty arrays. Blocks have no ambient file or secret access; keys come from the people running the Block, through declared network access. |
 
@@ -12053,14 +12242,16 @@ A JavaScript Block returns a `{schemaVersion: 1, kind: "stillmade.media-action",
 | --- | --- |
 | `screen.capture` | Choose a screen or window, then record it. |
 | `cursor.track` | Global cursor coordinates and display geometry; no click or keyboard monitoring. |
-| `camera.capture` | Camera recording after device and OS approval. |
-| `microphone.capture` | Microphone recording after device and OS approval. |
+| `camera.capture` | Camera recording, or the live camera feed (`StillMade.live`), after device and OS approval. |
+| `microphone.capture` | Microphone recording, or the live microphone feed (`StillMade.live`), after device and OS approval. |
 | `clipboard.read` | Read clipboard text, bounded to 100,000 characters. |
 | `clipboard.write` | Replace clipboard text. |
 | `media.pick` | Native picker for up to 20 media files; no arbitrary path access. |
 | `notifications.show` | A Block-branded desktop notification, at most one every ten seconds. |
 | `power.keep-awake` | Keep the app from suspending until disabled, revoked, closed or expired. |
 | `native.tools` | Use one exact versioned adapter for an approved installed desktop application. |
+| `folder.read` | List and read files in a folder the person picks (StillMade Desktop, Chrome and Edge); the Block sees an opaque folder id and relative paths only, and the folder is remembered for the Block where it is used. |
+| `folder.write` | Create and replace files in a folder the person shared for changing (declare folder.read too). |
 
 Details and request shapes: [desktop capabilities](/docs/reference/desktop-capabilities).
 
@@ -12276,7 +12467,7 @@ The latest version of each Block bundled with the SDK, generated from the packag
 | `sm.transition` 2.0.2 | Transition | editor-extension | `timeline` timeline (editor_timeline) · project context only · primary; `clipIds` text[] (timeline_clip_ids); `transition` text (timeline_transition_type); `duration` number (timeline_transition_duration); `soundOn` boolean (timeline_transition_sound_enabled); `soundId` text (timeline_transition_sound_id) | `edit` timeline-edit (timeline_edit) · primary |
 | `sm.video-assets` 2.1.4 | Video Assets | workspace | `assets` asset[] (media_collection) · project context only · primary; `versions` metadata[] (media_version_history) · project context only; `incoming` asset[] (media_collection); `kind` text (media_filter); `selectedIds` text (media_selection); `selectedVersions` text (media_version_selection) | `output` asset[] (production_media) · primary |
 | `sm.voiceover` 2.1.6 | Voiceover | workspace | `input` script (narration_script) · primary; `take` audio (narration_audio); `library` asset[] (project_media) · project context only; `timing` transcript (timed_transcript) · project context only | `output` audio (narration_audio) · primary |
-| `sm.when` 1.0.0 | When | task | `event` object (workflow_event) | `trigger` object (automation_trigger) · primary |
+| `sm.when` 1.1.0 | Automation | task | `event` object (workflow_event); `start` object (automation_start); `only_if` text (automation_condition) | `item` object (external_data) · primary; `trigger` object (automation_trigger); `check` object (ai_decision) |
 | `sm.whiteboard-assistant` 1.0.0 | Build Whiteboard | task | `board` board-document · project context only; `request` text · primary | `edit` workspace-edit · primary |
 | `sm.write-summary` 1.0.0 | Write summary | task | `data` text (external_data) · primary | `summary` text (summary_report) · primary |
 | `sm.youtube` 2.0.0 | YouTube publication | task | `video` video (finished_video) · primary; `title` text; `description` text; `tags` text; `visibility` text; `publishAt` text; `madeForKids` boolean; `aiGenerated` boolean | `uploadAction` approval (portable_media_action); `publication` json (youtube_publication) |
@@ -12339,7 +12530,11 @@ For image generation, use runtime:"capability", operation:"image.generate" and p
 For image analysis, use runtime:"capability", operation:"image.describe" and permissions.capabilities:["image.describe"]. Declare one primary image input (or one image[] input of one to four images to compare together) and one primary text output. capability.image references the input; capability.instruction contains bounded package-owned analysis instructions; capability.maxTokens is 1–4096; capability.output names the text output. The host loads only owned media and controls provider, model, payment and approval. Tests use bounded RGBA pixels and nondeterministic text expectations, never invented live descriptions. Shipped example: {"manifest":{"schemaVersion":1,"sdkVersion":"0.1.0","id":"example.describe-image","version":"1.0.0","name":"Describe an image","description":"Turn one owned image into concise production-ready visual notes.","kind":"task","runtime":"capability","entry":"src/capability.json","license":"MIT","provenance":{"notice":"MIT License\n\nCopyright (c) 2026 StillMade SDK contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and \nassociated documentation files (the \"Software\"), to deal in the Software without restriction, including \nwithout limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell \ncopies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the \nfollowing conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial \nportions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT \nLIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO \nEVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER \nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE \nUSE OR OTHER DEALINGS IN THE SOFTWARE.\n"},"inputs":{"image":{"type":"image","primary":true,"semantic":"source_image","required":true,"description":"Owned image to inspect for visible production details."}},"outputs":{"description":{"type":"text","primary":true,"role":"visual_description","semantic":"visual_description","description":"Concise production notes based only on visible image details."}},"permissions":{"project":[],"capabilities":["image.describe"],"network":[],"filesystem":[],"secrets":[]},"ui":[{"control":"asset","port":"image"}]},"capability":{"schemaVersion":1,"operation":"image.describe","image":{"$input":"image"},"instruction":"Describe only visibly supported subject matter, composition, lighting, color, texture, camera feel and visual style. Return concise production-ready plain text.","maxTokens":700,"output":"description"},"tests":[{"name":"Blue image","input":{"image":{"width":1,"height":1,"data":[20,80,200,255]}},"expectations":{"description":{"kind":"text","minLength":20,"maxLength":32768,"includes":["blue"]}}}]}.
 For AI-directed editing, use runtime:"capability", operation:"timeline.propose" and permissions.capabilities:["timeline.propose"]. Declare one current timeline input, up to three additional typed context inputs, and one timeline-edit output. Bind every input exactly once through capability.context; declare context.timeline.read and timeline.propose. StillMade controls the provider, strict JSON validation, stale-before checks, preview and Apply. Tests declare timeline-edit command bounds, never fabricated provider results. Shipped example: {"manifest":{"schemaVersion":1,"sdkVersion":"0.1.0","id":"example.timeline-polish","version":"1.0.0","name":"Timeline polish","description":"Turn a timeline and editing direction into a bounded proposal that remains reviewable before Apply.","kind":"task","runtime":"capability","entry":"src/capability.json","license":"MIT","provenance":{"notice":"MIT License\n\nCopyright (c) 2026 StillMade SDK contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and \nassociated documentation files (the \"Software\"), to deal in the Software without restriction, including \nwithout limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell \ncopies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the \nfollowing conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial \nportions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT \nLIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO \nEVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER \nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE \nUSE OR OTHER DEALINGS IN THE SOFTWARE.\n"},"inputs":{"timeline":{"type":"timeline","context":"timeline","primary":true},"direction":{"type":"text","default":"Polish this cut conservatively."}},"outputs":{"edit":{"type":"timeline-edit","primary":true}},"permissions":{"project":["context.timeline.read","timeline.propose"],"capabilities":["timeline.propose"],"network":[],"filesystem":[],"secrets":[]},"ui":[{"control":"text","port":"direction"}]},"capability":{"schemaVersion":1,"operation":"timeline.propose","context":{"timeline":{"$input":"timeline"},"direction":{"$input":"direction"}},"instruction":"Use only supported timeline-edit commands, exact before snapshots, and the current activeTimelineId. Preserve media and locked items. Return strict JSON only.","maxTokens":2000,"output":"edit"},"tests":[{"name":"one restrained edit","input":{"timeline":{"schemaVersion":1,"activeTimelineId":"timeline-1","tracks":[{"id":"video"}],"clips":[{"id":"clip-1","trackId":"video","start":0,"duration":4}],"audioItems":[],"captions":[]},"direction":"Add a soft transition."},"expectations":{"edit":{"kind":"timeline-edit","minCommands":1,"maxCommands":10}}}]}.
 For video generation use runtime:"capability", operation:"video.generate", permissions.capabilities:["video.generate"], one primary text input and one primary video output. capability.prompt references the input and capability.output names the output. Prompt limit 32000. Tests declare MP4 duration, dimensions and byte bounds; never fabricate video URLs. The enabled host selects its supported model, duration, resolution, payment and approved quote; packages cannot choose provider settings or dispatch jobs. Shipped example: {"manifest":{"schemaVersion":1,"id":"example.generate-video","name":"Generate video","version":"1.0.0","sdkVersion":"0.1.0","description":"Turn a production prompt into a short video using an approved host provider.","kind":"task","runtime":"capability","entry":"src/capability.json","license":"MIT","provenance":{"notice":"MIT License\n\nCopyright (c) 2026 StillMade SDK contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and \nassociated documentation files (the \"Software\"), to deal in the Software without restriction, including \nwithout limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell \ncopies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the \nfollowing conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial \nportions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT \nLIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO \nEVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER \nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE \nUSE OR OTHER DEALINGS IN THE SOFTWARE.\n"},"inputs":{"prompt":{"type":"text","primary":true,"required":true}},"outputs":{"video":{"type":"video","primary":true}},"permissions":{"project":[],"capabilities":["video.generate"],"network":[],"filesystem":[],"secrets":[]},"ui":[{"port":"prompt","control":"text"}]},"capability":{"schemaVersion":1,"operation":"video.generate","prompt":{"$input":"prompt"},"output":"video"},"tests":[{"name":"Produces a bounded MP4 sample","input":{"prompt":"A paper boat floating across a calm blue pond. Gentle camera movement."},"expectations":{"video":{"kind":"video","format":"mp4","minDuration":1,"maxDuration":60,"minBytes":32,"maxBytes":67108864,"minWidth":1,"maxWidth":3840,"minHeight":1,"maxHeight":3840}}}]}.
-Each capability package performs one supported operation. A job that needs several operations is built from parts: return each operation as its own part Block, and StillMade groups the parts of one job into one Step (One job per Step); never invent a combined runtime. Hosted image, speech and video source can be statically validated while authoring, but real fixture/sample generation requires the user's subsequent model/payment selection and quote confirmation. Do not claim those calls ran. Deterministic image transformations should remain sandboxed recipe or JavaScript code when supported; do not generate a new image as a substitute for processing an existing one.
+A capability package performs exactly one supported operation. A job that needs several (transcribe a recording, then find what is said in it; write words, then voice them), or code between two operations, is one module Block that calls each with stillmade.hosted.run (Module Blocks); never split one job into part Blocks, and never invent a combined capability runtime. Hosted image, speech and video source can be statically validated while authoring, but real fixture/sample generation requires the user's subsequent model/payment selection and quote confirmation. Do not claim those calls ran. Deterministic image transformations should remain sandboxed recipe or JavaScript code when supported; do not generate a new image as a substitute for processing an existing one.
+
+### Module Blocks
+
+A job that needs several hosted operations, or code around one (reading a transcript's words and times, shaping a list), is a module Block: {manifest,moduleSource,tests}, runtime:"module", moduleSource:{"main.js":"<the code>"}. StillMade names main.js by its digest and adds module; give no other files. main.js is plain JavaScript that imports nothing and uses no browser APIs (no fetch, TextEncoder, timers or WebCodecs): export default async function run(input, stillmade) returns the declared outputs. It calls each hosted operation with await stillmade.hosted.run(operation, request), listed in manifest.permissions.capabilities: text.generate, image.generate, video.generate, audio.speech, audio.music, audio.sfx, audio.transcribe, image.describe, media.analyze, web.fetch, web.research. Requests, and what each call returns (a test's mocks record exactly that value): text.generate {prompt, system, maxTokens} returns the text as a string, and with schema (a JSON schema object) returns that object, so ask for JSON with schema; audio.transcribe {audio: the input's saved reference, language:"auto"} returns {schemaVersion:1,text,words:[{text,start,end}]}; image.generate {prompt} and audio.speech {text} return a saved image or audio reference; image.describe {image, instruction} and web.fetch {url, instruction} return a string; media.analyze {media, question} returns {items:[...]}; web.research {topic} returns {summary,sources}. A call that fails throws: let it fail the run rather than catching it and returning an empty result. Media work on the person's device (cut, join or resize video, decode or extract audio, thumbnails) is await stillmade.media.transform(request); exporting is too: {operation:"timeline.render",kind:"video" or "audio",aspect:"9:16",clips:[{source,start,duration,from,transition:{type:"Fade"},look:"Filmic"}],audio:[{source,start,duration}],captions:[{text,start,end,words:[{text,start,end}],highlight:"#ffd400"}]} renders the Block's own timeline with the Editor's transitions, looks and word-by-word captions under the person's export plan, so never ask for a separate export, captions or color Block; stillmade.log and stillmade.progress(fraction, label) report. One press of the Step's button runs every call at the price shown beside it. A module Block runs in the person's browser while StillMade is open, never on a schedule or event. Tests are {name,input,expected,mocks}: mocks records what each call answers, as {hosted:{"audio.transcribe":{schemaVersion:1,text:"...",words:[...]},"text.generate":{...}},transforms:{...}} (a list answers successive calls in order), and expected is the exact output main.js returns for those answers. StillMade runs every test before anyone sees the Block, without spending credits. With the SDK instead, the same code is module/main.js in a Block folder and the same tests are tests/fixtures.json; stillmade-block pack writes the file to import (MODULES.md).
 
 ### ComfyUI workflows