stillmade-sdk 0.1.41 → 0.1.43

package/docs/build/modules.md

@@ -0,0 +1,487 @@
+# Module Blocks: JavaScript and WebAssembly
+
+# Module Blocks: modern JavaScript and WebAssembly
+
+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), 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. (StillMade's in-app builder writes `main.js` as one file that
+imports nothing and uses no browser APIs; that single-file rule is the builder's,
+not the runtime's. A module Block you build with the SDK can use all of this.)
+
+## Folder layout
+
+```
+my-block/
+  stillmade.block.json     manifest with "runtime": "module"
+  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", "threads": true}
+  tests/fixtures.json      [{name, input, expected, mocks?}]
+```
+
+Start one with `stillmade-block create my-block module` (`module-hosted` for
+one that calls hosted operations). `stillmade-block` is the SDK's command line:
+`npx stillmade-block` with the npm package `stillmade-sdk`, or
+`node <sdk>/packages/block-cli/cli.js` where `<sdk>` is the extracted
+`/block-sdk/stillmade-sdk-0.1.0.zip`. Bundle npm
+dependencies into `module/main.js` with any ES module bundler (esbuild,
+rolldown, Vite). A module holds up to 64 files, 64 MiB each and 128 MiB in
+total.
+
+## The entry
+
+```js
+export default async function run(input, stillmade) {
+  stillmade.progress(0.1, 'Loading');
+  const { instance } = await WebAssembly.instantiate(stillmade.asset('filters.wasm'));
+  const bytes = await stillmade.files.read(input.photo);      // a saved image the Block received
+  // ... process ...
+  const saved = await stillmade.files.write(pngBlob, { mediaType: 'image/png', name: 'result.png' });
+  return { result: saved };
+}
+```
+
+Return an object whose keys are your declared outputs. Outputs are checked
+against the manifest's port types.
+
+## The `stillmade` host API
+
+| Member | What it does |
+| --- | --- |
+| `input` | The validated input values (the same object as the first argument). |
+| `signal` | An `AbortSignal` that fires when the person cancels. |
+| `progress(value, label)` | Reports progress from 0 to 1 with a short label. Each report extends the run limit. |
+| `log(...values)` | Adds a line to the run log (up to 500 lines). |
+| `asset(path)` | A copy of one of the module's own files, such as a `.wasm` build, as an `ArrayBuffer`. |
+| `files.read(ref)` | The bytes, as an `ArrayBuffer`, of a saved image, video, audio, asset or file (a PDF, text, CSV, Markdown or JSON file on a `file` input) the Block received as input, or that StillMade made in this run: files it wrote, transform results and generated media. Media the person kept on their device (a `sm-media://device/...` address in a project Step) reads the same way, without leaving the device. Other files cannot be read, and transforms, hosted calls and actions accept only these references too; a hosted call or action gets a cloud copy of device media, made once per version. A reference is the file its `kind`, `assetId`, `versionId` and `url` name, so `{kind, assetId, versionId, url}` rebuilt from a `media.generate` result item (without its `key`) is the same file; any other file is refused with `MODULE_FILE_READ`, by `stillmade-block test --mock`, `ready` and `gate` as by StillMade. |
+| `files.write(data, {mediaType, name})` | Saves PNG, JPEG, WebP, GIF, MP4, WebM, MP3, WAV, M4A or OGG media, or a PDF, TXT, CSV, Markdown, JSON or ZIP file (`application/pdf`, `text/plain`, `text/csv`, `text/markdown`, `application/json`, `application/zip`; a `{kind: 'file'}` reference), to the runner's library and returns a reference you can return as an output. At most 64 files per run. |
+| `media.transform(request)` | On-device media work done by StillMade: decode audio to samples, extract or loudness-normalise audio, cut, join or re-encode video, and take thumbnails. Results are saved like `files.write`. See [Media processing](#media-processing). |
+| `actions.run(action)` | Runs a declared portable action. `media.generate` opens one approval for its whole batch, naming the most it can cost in StillMade credits; `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. Returns a standard `Response`. See [Outside APIs](outside-apis.md). |
+| `net.connect(url, {protocols})` | Opens a live WebSocket to the `wss://` form of a declared origin and resolves with the open socket. 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](project-storage.md). |
+| `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`. |
+| `project.read(fields?)` | A copy of the current project limited to the fields the manifest may read (`project.read` plus `context.<field>.read`), such as `timeline`, `shots` or `assets`. |
+| `assets.create(file, {name})` / `assets.appendVersion(asset, file)` | Adds a saved image, video or audio file to the project's media as a new asset (`asset.create`), or as the newest version of an asset the Block received, read or created (`asset.version.append`). |
+
+Hosted calls take the operation's request fields, for example:
+
+```js
+const plan = await stillmade.hosted.run('text.generate', {
+  prompt: `Write a 20-second podcast intro about ${input.topic}.`,
+  system: 'Warm, short sentences.', maxTokens: 400,
+  schema: { type: 'object', required: ['script'], properties: { script: { type: 'string' } } },
+});
+const voice = await stillmade.hosted.run('audio.speech', { text: plan.script, settings: { voice: 'adam' } });
+```
+
+`image.describe`, `media.analyze` and `audio.transcribe` take saved references
+(`image`/`images`, `media`, `audio`). `audio.transcribe` takes a saved audio or a
+saved video, whose own sound it transcribes, so there is no need to extract the
+audio first. `media.analyze` returns `{schemaVersion: 1, items}`, one item per
+picture or video, and for one video takes an optional `range: {start, end}` in
+seconds, at most 12 apart, to look closely at that part. `image.generate` takes `prompt` and optional
+`references`, one to eight saved images the new picture keeps. `video.generate` takes `prompt` and optional
+`firstFrame` (a saved image the video starts on, for image-to-video), `lastFrame` (one it ends on; needs
+`firstFrame`), `negativePrompt` (up to 2,000 characters) and `settings`; a model named in `settings` must take
+those frames (Kling 3.0 Turbo and Wan 2.6 Flash take no last frame; Wan 2.6 Flash and Wan 2.7 need a first frame).
+For a vertical or square clip, set `settings.aspectRatio` (`'9:16'`, `'1:1'`) and name no model: the default
+model (Vidu Q3 Turbo) takes no aspect ratio, so StillMade uses the cheapest model that makes that shape with the
+frames and `duration` given (Wan 2.6 Flash with a first frame, else Veo 3.1 Lite, else Seedance 2.0 Mini; see
+[Generation models](../reference/generation-models.md)). A model you name is kept, and one that cannot make the shape
+is refused. Look at pictures with `media.analyze`:
+StillMade credits pay for it, while `image.describe` runs only on the person's
+own OpenRouter key. `web.fetch` takes `url` and `instruction`;
+`web.research` takes `topic`; music and sound effects take `prompt` and
+`durationSec`.
+
+### Actions (`permissions.actions`)
+
+`actions.run` runs only the actions listed in `permissions.actions`, the same list a
+JavaScript Block declares: `"actions": ["media.generate"]` (or `"stock.search"`). A
+module that runs actions and calls no hosted operation leaves
+`permissions.capabilities` out; an empty list means the same.
+
+```js
+const { value, failures } = await stillmade.actions.run({
+  schemaVersion: 1, kind: 'stillmade.media-action', operation: 'media.generate',
+  resultPort: null,
+  request: { items: [
+    { key: 'front', operation: 'image', prompt: `The front of ${input.address} at dusk`,
+      settings: { model: 'nano-banana-pro', aspectRatio: '16:9' } },
+    { key: 'tour', operation: 'speech', prompt: input.script },
+  ] },
+});
+```
+
+The action is the object a JavaScript Block returns, with every key present; its
+items, settings and limits are in [Generate media from
+JavaScript](generate-media.md). Pass `resultPort: null`: no
+output port receives the media, `actions.run` returns it to your code and `run()`
+returns what the Block outputs. Before anything is generated StillMade opens one
+approval for the whole batch with the most it can cost in StillMade credits; credits
+the batch does not use come back when it closes. Each `actions.run` call is its own
+approval, so put every item one run needs in one batch: one clip per photo, the
+voice and the music are one `media.generate` call of up to 50 items (StillMade makes
+four at a time), never a call per photo, and never `hosted.run('video.generate')` once
+per photo, which asks again from the second call. Video items take the same
+`settings` as `video.generate` above, `aspectRatio` included. `actions.run` resolves with:
+
+- `value`: the items that were made, in request order, each
+  `{key, kind, assetId, versionId, url, duration?}` with `kind` `image`, `video` or `audio`
+  (speech, music and sound effects). `duration` is the length in seconds of a
+  video, music or sound effect item: the length it asked for (`settings.duration`,
+  `settings.durationSec`, or the model's default). A speech item has none, since
+  its length is what the words take: decode it with
+  `media.transform({operation: 'audio.decode', source})`, whose result has
+  `duration`, before timing a cut to it. Return them as outputs, or pass them to
+  `files.read`, `media.transform` or a hosted call.
+- `failures`: one `{key, message}` for each item that was not made; those items are
+  not in `value`.
+
+It throws when no item was made, when the person declines (`MODULE_ACTION_DECLINED`)
+and when the action is not declared (`MODULE_PERMISSION`). `stock.search` resolves
+with `{results}`. With `--mock` or a `tests/mocks.json`, `media.generate` answers
+with stand-in media and no failures; record your own answer under
+`actions["media.generate"]`.
+
+## A check, then the expensive run, on one page
+
+A job the person fills in and then gets a result from is one Block on one page
+(builder contract, "One job per Step"): the inputs, a cheap check before the
+expensive run, and the result. A listing video writes the script and voices a
+few seconds of it first, and makes the video only once the person has read the
+script and heard the voice. Build that as one module Block with a custom view,
+never as two Blocks or two Steps.
+
+The manifest takes the mode and the checked values as optional inputs, and the
+outputs the check leaves out are optional (a run may leave out any output with
+`"required": false`). `action` names the main button, the expensive run:
+
+```json
+"inputs": {
+  "listingPhotos": { "type": "image[]", "primary": true, "description": "Photos of the home, in the order of the tour." },
+  "homeFacts": { "type": "text", "description": "Address, rooms and what stands out." },
+  "make": { "type": "text", "required": false, "default": "video", "description": "check: the script and a voice sample; video: the tour." },
+  "script": { "type": "script", "required": false, "description": "The checked script, as the person left it." }
+},
+"outputs": {
+  "tour": { "type": "video", "primary": true, "required": false },
+  "script": { "type": "script", "required": false },
+  "voiceSample": { "type": "audio", "required": false }
+},
+"action": { "label": "Generate tour", "running": "Generating tour…" },
+"permissions": { "capabilities": ["text.generate", "audio.speech"] }
+```
+
+The module does only the cheap work when asked for the check:
+
+```js
+export default async function run(input, stillmade) {
+  const write = async () => (await stillmade.hosted.run('text.generate', {
+    prompt: `A 40-second listing tour script from these facts: ${input.homeFacts}`,
+    schema: { type: 'object', required: ['script'], properties: { script: { type: 'string' } } },
+  })).script;
+  if (input.make === 'check') {
+    const script = await write();
+    const voiceSample = await stillmade.hosted.run('audio.speech', { text: script.split(/(?<=[.!?])\s/)[0] });
+    return { script, voiceSample };
+  }
+  const script = input.script || await write();
+  const voice = await stillmade.hosted.run('audio.speech', { text: script });
+  const { duration } = await stillmade.media.transform({ operation: 'audio.decode', source: voice });
+  const each = duration / input.listingPhotos.length;
+  const tour = await stillmade.media.transform({
+    operation: 'timeline.render', aspect: '9:16',
+    clips: input.listingPhotos.map((photo, index) => ({ source: photo, start: index * each, duration: each, motion: 'zoom-in' })),
+    audio: [{ source: voice, start: 0, duration }],
+  });
+  return { tour, script };
+}
+```
+
+The view runs it twice with `StillMade.run`, which takes the inputs the view
+sets (StillMade keeps them on the Step and fills the rest): `{make: 'check'}`
+first ("Write the script"), then `{make: 'video', script}` with the script the
+person checked or edited. One `sm-primary` at a time: the check until there is
+a script, then the expensive run, labelled with `manifest.action`, while
+"Write again" stays a quiet button. The result's place
+(`sm-stage data-ratio="9:16"`) is drawn before either run; the script and the sample sit in it or beside the inputs
+until the video replaces them. Each run starts empty: return the script again
+with the video so it stays on the Step. StillMade saves the inputs a view sets,
+so the mode last pressed stays on the Step; until the view first sets it, a run
+started elsewhere (Chat, an automation) takes the default and makes the video.
+
+Each run is priced and approved by StillMade on its own. Beside the Block's
+page StillMade shows what each hosted call costs at the Step's saved or default
+model ("Write · 1 credit · Make voiceover · 3 credits"), with an (i) saying that
+pressing the Block's button is the approval. A run started by the person's own
+click or key in the view then runs each hosted operation once without a dialog,
+up to that price. StillMade checks the price with the provider first and opens
+its approval dialog, with the quote, only when the quote is higher, when the run
+calls the same operation a second time, or when the run did not come from the
+person's press (in a preview outside a project every call shows the dialog;
+`stillmade-block dev` answers with stand-ins and spends nothing). The view shows
+no prices. `media.transform`, `timeline.render` included, runs on the device
+and costs nothing; `actions.run` `media.generate` always asks first.
+
+## Media processing
+
+`stillmade.media.transform(request)` asks StillMade to do heavy media work on
+the person's device: Web Audio for audio, and the same renderer as Final
+Render for video (WebCodecs in the browser, the native renderer on desktop).
+It never runs on StillMade's servers and costs no credits. A transform reads
+only files the Block received, wrote or generated in this run (including media
+from `actions.run` `media.generate`; see `files.read` above), and saves its
+result to the runner's library, so you can return it as an output or pass it
+to the next transform.
+
+| Request | Result |
+| --- | --- |
+| `{operation: 'audio.decode', source, sampleRate?}` | `{sampleRate, duration, samples}`: mono `Float32Array` PCM for analysis (default 16 kHz; 8000 to 48000). |
+| `{operation: 'audio.extract', source, format?}` | A saved WAV (16-bit, 48 kHz) or MP3 of the audio track. |
+| `{operation: 'audio.normalize', source, targetLufs?, format?}` | A saved WAV or MP3 at the target integrated loudness (default -16 LUFS, peaks at most -1 dBFS). |
+| `{operation: 'video.cut', source, keep, settings?}` | A saved MP4 with only the `keep` ranges (`[{start, end}]` seconds, ordered, up to 500). |
+| `{operation: 'video.concat', sources, settings?}` | A saved MP4 of 2 to 50 videos in order. |
+| `{operation: 'video.resize', source, settings}` | A saved MP4 re-encoded with new settings. |
+| `{operation: 'image.thumbnail', source, at?, width?}` | A saved PNG of one frame (default the first frame, 1280 px wide). |
+| `{operation: 'document.text', source}` | `{text, pages}`: all the words of a PDF or text file the person gave, and `pages`, a list holding each page's words as one string (up to 500 pages). A file with no words (a scanned PDF) is refused. |
+| `{operation: 'image.compose', width, height, layers, background?, format?, text?}` | A saved PNG (or JPEG) of saved images joined into one picture: side by side, a grid, a contact sheet, a poster with a title. |
+| `{operation: 'timeline.render', clips, kind?, aspect?, audio?, captions?, settings?}` | A saved MP4 (or, with `kind: 'audio'`, an MP3) of your own timeline, rendered the way the Editor exports. |
+
+`timeline.render` is how a Block exports: there is no separate Export, Captions,
+Transition or Color grade Block to call. Each clip is `{source, start, duration,
+from?, transition?: {type, duration?}, look?, mute?, motion?, fit?, focus?}` (a saved
+image or video; a video keeps its own sound unless `mute`; `motion` is a slow
+camera move over the clip: `zoom-in`, `zoom-out`, `pan-left`, `pan-right`,
+`pan-up` or `pan-down`, which always keeps the picture filling the frame), each
+audio item `{source, start, duration, from?, volume?}` (`volume` is a percentage of the
+recording's own level, 0 to 200: 100, the default, plays it as recorded, 50 at half
+the level, 0 silent; put music under a voice at about 20 to 30), and each caption
+`{text, start, end, words?, position?, highlight?, animation?, size?}`, where
+`words` (`[{text, start, end}]`) highlights each word as it is spoken and `size`
+is the text height in pixels of the rendered frame (16 to 200; default 44, so
+give a 1080 by 1920 vertical video about 80). Times are seconds on the timeline: each
+clip starts where the one before it ends, less the transition on that earlier
+clip, which blends it into the next one; clips that overlap more are refused.
+`aspect` is `16:9`, `9:16`, `1:1` or `4:5`. A clip of another shape than the
+frame (a wide sermon in a `9:16` clip) is cropped to fill it, around its middle
+or around `focus: {x, y}`, the point to keep in view as fractions 0 to 1 across
+the picture (`{x: 0.3}` keeps a speaker standing left of centre), and
+`focus.scale` (1 to 2.5, instead of a motion) holds the clip that much closer on
+that point; `fit: 'contain'` fits it whole with bars instead. Looks, transitions and caption
+animations use the Editor's names (`TIMELINE_LOOKS`, `TIMELINE_TRANSITIONS`,
+`CAPTION_ANIMATIONS`). The render follows the person's export plan, like any
+export from StillMade.
+
+`image.compose` draws on a canvas `width` by `height` pixels (16 to 4096),
+filled with `background` (`#rrggbb`, default white). Each layer is `{source, x,
+y, width, height, fit?}`: a saved image placed in that box, in order, cropped
+to fill it (`fit: 'cover'`, the default) or fitted whole inside it (`'contain'`).
+Each piece of text is `{text, x, y, size?, color?, background?, align?,
+weight?, width?}`, drawn on top: `y` is the top of the line, `size` is 8 to 400
+pixels (default 48), `color` defaults to black, `background` puts a box behind it
+(for a Before label over a photo; `color` and `background` are `#rrggbb`, or `#rrggbbaa`
+or `rgba()` for a see-through box such as `#00000099`), `align` is `left`, `center` or `right` around
+`x`, and `weight` is `bold` (default) or `normal`. `width` wraps the words onto
+lines no wider than it, 1.2 times `size` apart, breaking a word wider than a line
+(or a caption with no spaces) between its characters: give a caption under a
+frame the frame's width so it never runs into the next one. Up to 64 layers and 64 pieces of
+text; `format` is `png` (default) or `jpeg`. A grid is arithmetic in your code:
+for 9 photos on a 1800 by 1800 sheet, three columns of 600 pixels.
+
+`source`/`sources` are saved references (`{kind, assetId, versionId, url}`).
+Render `settings` are `{fps: 24|30|60, resolution: 720|1080|2160, quality:
+'low'|'medium'|'high'}`; the default is 30 fps, 1080, high. `video.cut`,
+`video.concat` and `video.resize` keep the source's aspect ratio;
+`timeline.render` makes the `aspect` it is given. Rendering follows the person's export plan, like any
+export.
+
+Pure helpers ship as `@stillmade/block-sdk/media` for you to bundle (the file is
+`stillmade-sdk/packages/block-sdk/media-transform.js` in the npm package and
+`<sdk>/packages/block-sdk/media-transform.js` in the extracted download; alias
+the name in your bundler or import that path):
+`silentRanges(samples, sampleRate, {thresholdDb, minSilence})`,
+`keepRanges(silent, duration, {padding})`, `integratedLoudness(channels,
+sampleRate)` (ITU-R BS.1770), `loudnessGain`, `encodeWav` and `decodeWav`.
+
+```js
+import { silentRanges, keepRanges } from '@stillmade/block-sdk/media';
+
+export default async function run(input, stillmade) {
+  const audio = await stillmade.media.transform({ operation: 'audio.decode', source: input.video });
+  const keep = keepRanges(silentRanges(audio.samples, audio.sampleRate), audio.duration);
+  const trimmed = await stillmade.media.transform({ operation: 'video.cut', source: input.video, keep });
+  return { trimmed };
+}
+```
+
+For anything else, decode and encode in the Block itself: the Worker has
+WebCodecs (`VideoDecoder`, `VideoEncoder`, `AudioDecoder`), `OffscreenCanvas`
+and `createImageBitmap`, and you can bundle `mp4-muxer`, `mp4box` or a
+WebAssembly codec. Images arrive as saved references: read the bytes with
+`files.read` and decode them with `createImageBitmap`, at full resolution.
+
+## Sandbox and limits
+
+- The module runs in one dedicated Worker inside a response-sandboxed frame
+  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
+  StillMade spends on a host call (rendering a video, waiting for the person to
+  approve credits) does not count. Every run stops after 30 minutes in total.
+  When a limit passes, or the person cancels, the frame is removed and the
+  Worker stops immediately, even inside an endless loop.
+- Generating code at run time (`new Function`, used by Emscripten bindings) is
+  allowed inside the sandbox.
+
+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
+
+```sh
+stillmade-block test my-block          # runs fixtures in a local Node worker
+stillmade-block preview my-block input.json
+stillmade-block dev my-block           # the interface in your browser, reloaded on save
+stillmade-block gate my-block          # StillMade's readiness check
+stillmade-block pack my-block          # writes <id>-<version>.stillmade-module.json
+```
+
+`dev` serves the Block's real controls or view at `http://127.0.0.1:4800`
+(`--port` picks another) and answers hosted calls with stand-ins, never credits.
+The Block is not ready until `gate` passes. Name the Block's own folder: `gate .`
+in a folder that also holds the extracted SDK checks the SDK's examples too.
+`pack my-block` is the only packing step for a module Block, and it never takes
+`--original` (original `.stillmade-block` archives hold recipe, JavaScript,
+capability and ComfyUI source only and refuse a module Block).
+
+`test` and `preview` run your code on your machine in a disposable Node worker
+with the same host API and run limits (not a security sandbox; it is your own
+code). `files.read`, `files.write`, `media.transform`, actions and hosted calls need StillMade, or
+a host you pass to `createNodeModuleExecutor` in your own tests. The Node worker has no
+`OffscreenCanvas` or `createImageBitmap`: a Block that decodes or draws images there
+needs its own fallback for tests, or tests only what it does without drawing.
+
+A fixture's `files` mock is a path inside the Block folder (local runs only: it does not
+travel in the pack), `{"text": "..."}` for a text file, or `{"base64": "..."}` for a small
+binary file (at most 256 KB), which travels in the pack and the import review. Text can
+never hold a NUL character (`\u0000`): StillMade cannot store it, and import refuses it.
+
+A fixture's photo, recording, clip or file can be one of StillMade's example files,
+named by address: `/api/media/example/photo-1.jpg` to `photo-4.jpg`, `sheet.png`,
+`room.png`, `kitchen.wav`, `hall.wav`, `click-120.wav`, `audio.mp3`, `clip.mp4`,
+`notes.txt`, `sales.csv` and `lesson.pdf`, a two-page PDF of words (sizes in
+PASTE_TO_LLM.md). `test` reads their real bytes
+when the fixture gives no mock for them, and StillMade, its preview and its phone and
+browser check serve the same files, so the example a person sees is the one you tested.
+Point what a fixture's mocks answer at them too (`/api/media/example/clip.mp4` for a
+rendered clip, `kitchen.wav` for speech): `dev` then shows and plays the result, where a
+made-up address shows an empty player.
+
+A fixture can record what the host answers, so a test of a Block that calls
+hosted operations costs nothing and gives the same result every run:
+
+```json
+{
+  "name": "Finds John 3:16",
+  "input": { "sermon": { "kind": "audio", "assetId": "a1", "versionId": "v1", "url": "https://example.com/sermon.wav" } },
+  "mocks": {
+    "hosted": {
+      "audio.transcribe": { "schemaVersion": 1, "text": "Turn to John 3:16", "words": [{ "text": "John", "start": 0.6, "end": 0.9 }] },
+      "text.generate": { "verses": [{ "reference": "John 3:16", "word": 0 }] }
+    }
+  },
+  "expected": { "verses": [{ "reference": "John 3:16", "start": 0.6 }] }
+}
+```
+
+`mocks` has the shape of `tests/mocks.json` (`hosted`, `transforms`, `actions`,
+`files`, `storage`, `project`, `connections`, `network`); a list answers
+successive calls in order. `files` maps an input's asset ID to a file in the Block
+folder, or to `{"text": "..."}` for a text file, so a Block that reads a notes or
+CSV file the person gives it is tested without a folder (StillMade's builder has none). A fixture's own `mocks` take the place of
+`tests/mocks.json` for that fixture. StillMade's own builder writes module
+Blocks the same way and runs their tests before anyone sees them.
+
+Import the `.stillmade-module.json` in StillMade (Create, then Import).
+StillMade verifies every file digest, uploads each file to its
+content-addressed store, and saves the Block. Fixtures then run in your
+browser's module sandbox.
+
+Uploaded module files count against your cloud storage. A digest alone never
+grants access: a person can read a module file only when they uploaded those
+exact bytes or can open a saved Block that names it (yours, an installed or
+community version, or one shared with their team).
+
+See `examples/module-opencv/` for a Block that runs OpenCV on a 12-megapixel
+photo, `examples/module-silence-trimmer/` for one that cuts the pauses out of a
+talking video, and `examples/module-audio-extract/` for one that saves a
+video's audio as WAV.

package/docs/build/original-blocks.md

@@ -0,0 +1,70 @@
+# Build an original SDK folder
+
+Download `/block-sdk/stillmade-sdk-0.1.0.zip` (the same files as `npm install --save-dev stillmade-sdk`) and extract it into a development directory. `stillmade-block` in every StillMade guide is its command line: `node <sdk>/packages/block-cli/cli.js`, where `<sdk>` is the extracted folder (run from inside it, as below), or `npx stillmade-block` after the npm install. Then run:
+
+```sh
+node packages/block-cli/cli.js create my-block javascript
+node packages/block-cli/cli.js validate my-block
+node packages/block-cli/cli.js test my-block
+node packages/block-cli/cli.js dev my-block
+node packages/block-cli/cli.js gate my-block
+node packages/block-cli/cli.js pack my-block
+```
+
+`dev` shows the Block's interface in your browser and reloads it on every save.
+`gate` is the readiness check StillMade runs; the Block is not ready until it
+passes. Name the Block's own folder: `gate .` in a folder that also holds the
+extracted SDK checks the SDK's examples too. `pack` runs the tests again and
+writes the file to import, named by the Block's runtime:
+
+| Runtime | `pack my-block` writes |
+| --- | --- |
+| `module`, or a frame view with files in `src/view-files/` | `<id>-<version>.stillmade-module.json` |
+| `recipe`, `javascript`, `capability`, `comfyui` | `<id>-<version>.stillmade.json` |
+
+`create` supplies an editable starter. Replace its identity, task behavior, controls
+and fixtures with your Block's requirements, retaining applicable SDK license
+notices. The directory layout is:
+
+```text
+my-block/
+  stillmade.block.json
+  src/run.js
+  src/view.html          optional custom interface
+  src/view.css           optional styles
+  src/view.js            optional interface behavior
+  tests/fixtures.json
+```
+
+`src/run.js` is an isolated function body operating on `input`; it returns declared
+outputs. The custom interface uses the supplied `StillMade` bridge. A small image
+tool can read typed image pixels (at most one megapixel, as RGBA arrays), apply its
+edits in `run.js`, show before/after images through `StillMade.previewImage`, and call
+`StillMade.run` from its controls; a photo editor that keeps full-size photos is a
+`module` Block with a frame view (MODULES.md).
+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 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).
+A new Block needs no `.stillmade-block` archive: `pack <folder> <file>.stillmade-block --original`
+writes one only for your own recipe, JavaScript, capability or ComfyUI code
+([PORTABLE.md](https://stillmade.shop/block-sdk/PORTABLE.md)) and refuses a module Block. Direct folder
+import and packed-file import retain the same runtime and interface. Security, source-rights confirmation and hosted execution approvals still
+use the ordinary review path. They do not adapt the Block.
+
+This is the implemented SDK, not the full future runtime catalog. It supports
+data-only recipes, isolated JavaScript, reviewed hosted text and speech generation, and a reviewed ComfyUI core-image adapter,
+typed inputs/outputs, schema-driven controls,
+optional sandboxed HTML interfaces,
+behavior fixtures, package validation, standalone execution, and app import.
+Python source, external modules, native dependencies, custom ComfyUI nodes and
+per-frame editor renderers are not executable through this SDK version. ComfyUI
+requires an explicitly selected account connection and a real remote review;
+recipe and JavaScript examples continue to run offline.