stillmade-sdk 0.1.42 → 0.1.43

package/docs/build/state.md

@@ -0,0 +1,223 @@
+# Remember data between runs
+
+## When to use memory
+Use saved memory for small counters or preferences that belong to one placement. Use [project context](context.md) for scripts, scenes, shots, assets, and production history. Never put provider keys or media bytes into Block memory.
+
+## Try the complete example
+[Download Numbered takes](https://stillmade.shop/block-sdk/examples/numbered-takes.stillmade.json). Import it, review its tests and preview, then confirm the import. Add it to a Project Type and run it twice: the labels advance from Take 1 to Take 2. A second placement has its own counter.
+
+```json
+{
+  "manifest": {
+    "schemaVersion": 1,
+    "sdkVersion": "0.1.0",
+    "id": "example.numbered-takes",
+    "action": {
+      "label": "Number takes",
+      "running": "Numbering takes…"
+    },
+    "version": "1.0.0",
+    "name": "Numbered takes",
+    "description": "Label successive creative takes with an independent counter for each production placement.",
+    "kind": "task",
+    "runtime": "javascript",
+    "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": {
+      "text": {
+        "type": "text",
+        "primary": true,
+        "semantic": "draft_text",
+        "required": true,
+        "description": "Creative take text to label with the next number."
+      }
+    },
+    "outputs": {
+      "text": {
+        "type": "text",
+        "primary": true,
+        "semantic": "numbered_take",
+        "description": "The supplied take prefixed with its saved sequence number."
+      }
+    },
+    "permissions": {
+      "project": [
+        "state.step"
+      ]
+    },
+    "state": {
+      "scope": "step",
+      "version": 1,
+      "initial": {
+        "count": 0
+      }
+    },
+    "ui": [
+      {
+        "port": "text",
+        "control": "text"
+      }
+    ]
+  },
+  "code": "state.count += 1; return {text: \"Take \" + state.count + \": \" + input.text.trim()};",
+  "tests": [
+    {
+      "name": "First take",
+      "input": {
+        "text": "  Opening scene  "
+      },
+      "expected": {
+        "text": "Take 1: Opening scene"
+      },
+      "expectedState": {
+        "version": 1,
+        "value": {
+          "count": 1
+        }
+      }
+    },
+    {
+      "name": "Continues saved numbering",
+      "input": {
+        "text": "Alternate ending"
+      },
+      "state": {
+        "version": 1,
+        "value": {
+          "count": 4
+        }
+      },
+      "expected": {
+        "text": "Take 5: Alternate ending"
+      },
+      "expectedState": {
+        "version": 1,
+        "value": {
+          "count": 5
+        }
+      }
+    }
+  ]
+}
+```
+
+## Run from the command line
+Create a stateful starter, run its fixtures, and save two separate memory checkpoints:
+
+```sh
+node packages/block-cli/cli.js create ./takes stateful
+node packages/block-cli/cli.js test ./takes
+node packages/block-cli/cli.js preview ./takes --save-state take-1.json
+node packages/block-cli/cli.js preview ./takes --state take-1.json --save-state take-2.json
+```
+
+Without --state, each preview starts fresh. --save-state writes a new file and refuses to overwrite an existing checkpoint. These files contain your Block memory, are pinned to the exact package digest, and should stay private if their contents are private. The CLI never writes state unless you request it.
+
+## Run with the offline SDK
+Extract the SDK and save this script alongside its packages folder. The host chooses when to save returned state. Here both runs use a disposable sandbox while the caller holds the accepted state.
+
+```javascript
+import {readFile} from 'node:fs/promises';
+import {initialBlockState,runPackageAsync} from './packages/block-sdk/index.js';
+const pkg=JSON.parse(await readFile('./examples/numbered-takes.stillmade.json','utf8'));
+let memory=initialBlockState(pkg.manifest);
+const first=await runPackageAsync(pkg,{text:'Opening'},{state:memory});
+memory=first.state; // accept only after your host validates current permissions and inputs
+const second=await runPackageAsync(pkg,{text:'Alternate opening'},{state:memory});
+console.log(first.outputs.text,second.outputs.text);
+```
+
+## State contract and limits
+Stateful JavaScript Blocks can opt into a small JSON state object. Production
+placements save accepted state with their outputs in the existing project document.
+Each placement has independent memory pinned to the exact package digest. Connected
+runs retain proposed memory until the user accepts their results; changed memory
+invalidates an older result. A failed or cancelled run does not advance memory.
+
+Block previews keep temporary memory across runs; Reset or closing the preview
+discards it. Import samples and each Project Type rehearsal placement start fresh.
+Fixtures never become project memory. External SDK hosts must supply state explicitly
+or execution fails with `STATE_REQUIRED`.
+
+Changing a placement to another build starts fresh memory and archives the previous
+placement through workflow history; restoring that exact placement restores its
+previous memory. Duplicating a workflow placement starts independent fresh memory.
+Stateful single-Block batches process the selection in order using provisional
+memory. Choosing a batch result accepts memory through that result; later
+previews cannot overwrite it. Changes to inputs, selected source versions, or
+starting memory require a new batch. Connected multi-Block batches also carry
+independent provisional memory for every placement in selection order. Use completed
+results validates the original source selection and each memory transition before
+committing the completed prefix together. A failed later transform preserves earlier
+results for review without advancing saved memory automatically. Single-Block background automation supports saved memory when shared Canvas editing is enabled. Each completed job commits its outputs and memory in one transaction; a changed workspace or memory causes a retry. Failed, paused or stale workers do not advance memory. Selecting a completed result does not advance memory again. Connected background workflows pin all starting states and commit every placement’s memory together when the complete workflow succeeds. Failed prefixes retain their results without advancing shared memory; resuming requires the same starting memory. Hosted APIs and ComfyUI still use their explicit execution flow. State is bounded JSON, not a media-storage API. The production workspace’s
+Block memory controls let users reset a placement and undo that reset until
+the next accepted run. Reset keeps previous outputs visible but marks them stale.
+
+Declare this alongside the usual manifest fields:
+
+```json
+{
+  "runtime": "javascript",
+  "permissions": {"project": ["state.step"]},
+  "state": {"scope": "step", "version": 1, "initial": {"count": 0}}
+}
+```
+
+Your JavaScript body receives `input` and, only for stateful Blocks, a mutable
+`state` object. Update its properties and return your ordinary output ports:
+
+```js
+state.count += input.amount;
+return {count: state.count};
+```
+
+Do not reassign the `state` parameter. Keep it plain JSON. Each invocation uses a
+fresh sandbox and a copy of the supplied state. No storage, network, native API,
+or another Block's memory is exposed. State is limited to 64 KiB and a positive
+schema version. Only JavaScript currently supports this contract.
+
+A trusted host calls:
+
+```js
+const previous = initialBlockState(pkg.manifest); // first run only
+const result = await runPackageAsync(pkg, {amount: 2}, {state: previous, signal});
+// result.outputs is the normal output map.
+// result.state is {version: 1, value: {count: 2}}.
+```
+
+The SDK never writes persistence itself. The host must store state under the
+account, project, and Step instance; recheck the source, previous state, and write
+permission; and save the returned state atomically with accepted results. A failed
+or cancelled run must not overwrite prior state. Never share one state object
+between placements, projects, accounts, or preview sessions. A mismatched state
+version fails with `STATE_VERSION`; a host must not silently reinterpret it.
+
+Every stateful fixture requires `expectedState` in addition to ordinary expected
+outputs. Optional `state` supplies a saved starting value; omission uses a fresh
+copy of `manifest.state.initial` for that fixture:
+
+```json
+{
+  "name": "Continue a saved count",
+  "input": {"amount": 3},
+  "state": {"version": 1, "value": {"count": 4}},
+  "expected": {"count": 7},
+  "expectedState": {"version": 1, "value": {"count": 7}}
+}
+```
+
+`initialBlockState`, `validateBlockState`, and `STATE_LIMIT_BYTES` are exported by
+the SDK. Both browser workers and Node's disposable QuickJS workers carry this
+contract. Fixture success verifies state transformation, not host persistence.
+
+## Troubleshooting
+- STATE_REQUIRED: your external host did not supply an initial or accepted state envelope.
+- STATE_VERSION: the saved version does not match the manifest; restore the previous build or explicitly reset memory. There is no automatic state migration.
+- STATE_LIMIT: keep the JSON state value within 64 KiB.
+- STATE_BEHAVIOR: output assertions passed but the fixture's expected state did not match.
+- STATE_CHANGED: another edit or accepted run changed the memory; run again against current state.
+
+## Test the actual behavior
+Each fixture needs expectedState, even when the expected memory is unchanged. Include a fresh-state case and a continuation case. Fixture state is synthetic and never installed as project memory. Run details are available in the production workspace and preview without copying your content into diagnostic downloads.

package/docs/build/testing.md

@@ -0,0 +1,112 @@
+# Test and preview a Block
+
+## Fixtures are part of the package
+Include 1–50 fixtures. Each names an input object and the complete expected output object. Defaults and optional ports still follow the declared contract.
+```json
+[
+  {
+    "name": "Counts words",
+    "input": {
+      "text": "  Hello StillMade  "
+    },
+    "expected": {
+      "text": "Hello StillMade",
+      "words": 2
+    }
+  },
+  {
+    "name": "Empty text",
+    "input": {
+      "text": "  "
+    },
+    "expected": {
+      "text": "",
+      "words": 0
+    }
+  }
+]
+```
+
+## Run the fixture suite
+```sh
+node packages/block-cli/cli.js test ./my-block
+```
+A test report includes `passed`, `digest`, `sdkVersion`, and individual results. Fixtures execute the real package runtime. Matching JSON output is required; approximate image similarity is not used.
+
+## What to cover
+- Ordinary input with a useful, observable result.
+- Empty text or minimum-size images, when the contract allows them.
+- Boundary values for controls.
+- Behavior that preserves unrelated data, colors, or alpha.
+- Values that the next Block will actually consume.
+
+## Preview with your own sample
+Save a JSON input object as `sample.json` and run:
+```sh
+node packages/block-cli/cli.js preview ./my-block ./sample.json
+```
+Use synthetic input in distributed packages. Private project material belongs in local samples, not published fixtures.
+
+## Test offline with stand-ins
+StillMade hosts part of what a Block does: hosted operations, saved files,
+outside APIs and connections, cloud storage, project reads and assets. On your
+own machine, `stillmade-block test`, `run` and `dev` answer these calls with
+stand-ins:
+
+- `--mock` turns them on. A folder with `tests/mocks.json` uses them every time,
+  including for `pack`, which runs the fixtures first.
+- Every hosted operation has a recorded stand-in with the exact shape StillMade
+  returns, checked by the same validators the app uses. Text replies read
+  `Stand-in reply to: <prompt>`; images are 1024-pixel PNGs (or the requested
+  aspect ratio); speech, music and sound effects are short WAV tones; video is a
+  one-second MP4; transcripts, research, media analysis, timeline proposals and
+  JSON replies (sampled from the Block's schema) are small fixed results. Files
+  a stand-in or `files.write` makes can be read back with `files.read`.
+- `tests/mocks.json` records your own answers. Every section is optional, and a
+  list answers successive calls in order (the last one repeats):
+
+```json
+{
+  "hosted": {"text.generate": ["First reply", "Second reply"]},
+  "actions": {"stock.search": {"results": []}},
+  "network": [{"method": "GET", "url": "https://api.github.com/repos/octocat/hello-world/issues*", "status": 200, "json": []}],
+  "connections": {"app:openapi:notion/retrievePage": {"properties": {}}},
+  "files": {"clip-1": "fixtures/clip.wav"},
+  "storage": {"settings": {"runs": 3}},
+  "project": {"schemaVersion": 1, "metadata": {"name": "Launch"}},
+  "transforms": {"video.cut": {"kind": "video", "assetId": "cut-1", "versionId": "v1", "url": "/api/media/stillmade-mock/cut.mp4", "mimeType": "video/mp4", "width": 320, "height": 180, "duration": 1, "bytes": 2048}}
+}
+```
+
+| Section | Answers | Value |
+| --- | --- | --- |
+| `hosted` | `stillmade.hosted.run` and capability Blocks, by operation | The output value the call returns |
+| `actions` | `stillmade.actions.run`, by operation | The action result (`{value, failures}` for `media.generate`) |
+| `network` | `stillmade.net.fetch` | Recorded responses: method, url (a trailing `*` matches the rest), status, headers and one of `json`, `text` or `base64` |
+| `connections` | `stillmade.connections.call`, by `appId/operation` | The JSON result |
+| `files` | `files.read`, by asset ID or URL | A path inside the Block folder, or `{"text": "..."}` with a text file's contents |
+| `storage` | `stillmade.storage` | Values stored before the run |
+| `project` | `stillmade.project.read` | A project snapshot |
+| `transforms` | `stillmade.media.transform`, by operation | The transform result (`audio.decode` on a WAV file decodes it for real) |
+
+For a capability Block, fixture checks on the model's words (`includes`,
+lengths, word counts) are listed as not checked rather than run against a
+stand-in; StillMade runs them with a real model when you import the Block.
+Media checks (sizes, durations, formats) still run. A run with stand-ins is
+never a live verification: reports say `liveVerified: false` and list every
+stand-in that answered. Nothing contacts a provider or spends credits.
+
+The same stand-ins are available to your own tests from
+`@stillmade/block-sdk/mock-host`: `createMockHost({mocks, readLocalFile,
+manifest})` returns `host` (pass it to `createNodeModuleExecutor({files,
+host})`), `capability` (pass it to `runPackageAsync` or `testPackage` for a
+capability Block), `calls` (what answered each call) and `file(url)` (the bytes
+of a stand-in or written file). `standInFixtures(pkg)` returns a capability
+Block's fixtures with the checks on the model's words removed and lists them;
+`validateMocks(value)` checks a `tests/mocks.json` value;
+`sampleJsonSchema(schema)` makes a value that satisfies a JSON schema; and
+`mockPng`, `mockWav` and `mockMp4` make the stand-in media. `MOCKS_FILE` is
+`tests/mocks.json` and `MOCK_MEDIA_PREFIX` is the URL prefix of stand-in media.
+
+## Admission and workflow tests
+The app also scans source and permissions, repeats contract tests in its sandbox, runs a sample, validates outputs, and requires review before installation. After insertion, [rehearse the connected workflow](../project-types/testing.md); passing one Block’s fixtures alone does not establish workflow compatibility.

package/docs/build/timeline-edits.md

@@ -0,0 +1,116 @@
+# Propose timeline edits
+
+### Interactive timeline mixer
+
+[Download Timeline mixer](https://stillmade.shop/block-sdk/examples/timeline-mixer.stillmade.json), or
+choose **Timeline mixer template** in the Block builder. Its complete interface
+lists video and audio clips with individual level sliders, live percentages,
+reset, empty-state guidance, and a Review mix action. It uses `StillMade.render`
+and `StillMade.onAction`; the isolated production function returns a typed edit
+proposal. Existing Editor permissions, conflict checks, review, and undo still
+apply. No account APIs or provider keys are exposed to its interface.
+
+Import the package, run its fixture, and change a slider in Preview. To use real
+clips, add it to a Project Type after Editor and open its Step in a project with
+a timeline. Review the proposed levels before applying them. It edits up to 100
+clips per invocation; the interface does not play or render the timeline.
+Download its source and SDK from the builder to modify the HTML, CSS, interface
+JavaScript, production function, and fixtures independently, then reimport.
+
+
+A Block can return a `timeline-edit` output to propose changes to existing Editor
+clips. Declare `permissions.project: ["context.timeline.read", "timeline.propose"]`
+and an input `{type:"timeline",context:"timeline",primary:true}`. The output is
+`{schemaVersion:1,title,timelineId,commands}`. Copy `timeline.activeTimelineId` into
+`timelineId`. Each command is `{collection,operation,before,values}`: collection is
+`clips` or `audioItems`, and `before` is the exact unchanged target object from the
+input snapshot. Use at most 100 commands, with one command per target.
+
+| Operation | Values | Behavior |
+| --- | --- | --- |
+| move | `{start: seconds}` | Move an existing item; no silent ripple |
+| trim | `{trimStart: sourceSeconds, duration: timelineSeconds}` | Trim within known source duration; variable-speed, frozen and looping clips defer to Editor |
+| split | `{at: timelineSeconds, newId: "unique-clip-id"}` | Split into two source-aligned clips, at least 0.05 seconds from either edge |
+| volume | `{volume: 0..200}` | Set the existing Editor volume percentage |
+| mute | `{muted: boolean}` | Mute or unmute an existing item |
+| remove | `{}` | Remove the timeline instance, preserving source media |
+| grade | `{lut, color}` | Grade clips only; retain original media and timing |
+
+Run the Block in a project, accept its result, and open the Editor's media panel.
+Timeline edits from Blocks displays a visual before/after strip and each target's values and applies
+all commands together using ordinary Editor undo history. Desktop and mobile use
+the same proposal contract. A changed target, different timeline version, locked
+track, source overrun, or new clip overlap rejects the proposal. The Block cannot
+set arbitrary fields, insert external URLs, run code inside playback, or silently
+write the timeline. Re-run it against current context after a conflict.
+
+[Download Quieter clips](https://stillmade.shop/block-sdk/examples/quieter-clips.stillmade.json) for a
+complete isolated JavaScript example with a realistic timeline fixture. The
+proposal type is a sink for Editor review; it is not interchangeable with a
+`timeline` snapshot.
+
+
+### Caption proposals
+
+Use `collection:"captions"` with these commands:
+
+| Operation | Before | Values |
+| --- | --- | --- |
+| caption.add | null | `{id,trackId,text,start,end}` |
+| caption.update | Exact existing caption object | `{text,start,end}` |
+| remove | Exact existing caption object | `{}` |
+
+Caption times are seconds with end greater than start; text must be nonempty and
+at most 5,000 characters. Adding uses an unused item ID and an unlocked existing
+caption track. The standard `captions` track is created if absent. New captions
+use StillMade's existing caption defaults; updating text or timing preserves the
+caption's styling. Reapplying an insertion rejects its duplicate ID. The host
+compares existing captions against their captured snapshots before update/removal.
+
+[Download Caption from text](https://stillmade.shop/block-sdk/examples/caption-from-text.stillmade.json).
+This complete Block takes text plus a scoped timeline, chooses an unused caption
+ID, and proposes insertion without modifying the project. Its output connects to
+the Editor's proposal review. Add or run it after opening a timeline, then review
+its result in the Editor's media panel.
+
+## Timed captions and caption styling
+[Download Captions 2.0.0](https://stillmade.shop/block-sdk/examples/captions.stillmade-block). This
+standalone, remixable Block converts a transcript into editable timeline captions.
+It owns phrase grouping, word timing and caption appearance, runs in the JavaScript
+sandbox, and returns ordinary `timeline-edit` proposals for review and Apply.
+It does not transcribe audio or spend execution credits.
+
+The optional context binding `{ "type": "transcript", "context": "transcript",
+"required": false }` requires `context.transcript.read`. At whole-project scope
+it supplies a copied `{schemaVersion:1, words:[{text,start,end}], text, audioUrl?}`
+from the saved voiceover when word timings exist. It is omitted when absent and
+for scene, shot or asset selections. URL metadata grants no media access.
+Explicitly connected transcript inputs remain separate from this fallback.
+
+Captions uses a connected transcript first, then entered text, then the project's
+saved transcript. Text without word timings uses estimated timing, identified in
+the proposal title. Start offsets word times into the timeline. Duration zero
+keeps transcript timing; a positive duration clips the result to that interval.
+A proposal supports at most 100 lines and rejects longer results without silently
+truncating them. Existing captions stay intact and locked tracks reject Apply.
+
+`caption.add` retains its required `{id,trackId,text,start,end}` values and also
+accepts these optional fields. Unknown fields and values outside these limits
+are rejected by the same SDK validator and host apply path:
+
+| Field | Accepted values |
+| --- | --- |
+| `words` | Up to 1,000 `{text,start,end}` entries, ordered by start, contained in the caption interval; nonempty text up to 5,000 characters, end at or after start |
+| `font` | `Hanken Grotesk` |
+| `size` | 8–200 |
+| `color`, `highlightColor` | Three- or six-digit hex color |
+| `background` | `none` or three- or six-digit hex color |
+| `backgroundOpacity`, `backgroundPadding`, `backgroundRadius` | 0–100 |
+| `position` | `top`, `middle`, or `bottom` followed by `left`, `center`, or `right`, separated by one space |
+| `animation` | `none` or `fade` |
+
+The host fills omitted appearance values with its existing defaults, preserves
+provided styling and clones word timings before saving through ordinary edit
+history. Caption updates retain their existing `{text,start,end}` contract.
+Package source, MIT notices, lineage and three fixtures are retained in the
+canonical archive; validate, test and remix it using the public CLI.

package/docs/build/timeline-proposals.md

@@ -0,0 +1,76 @@
+# Hosted timeline proposals
+
+# Hosted timeline proposals
+
+Use `timeline.propose` when a Block needs an LLM to choose reviewable edits from the current timeline. The Block declares the editing policy and typed context. StillMade owns the provider connection, model selection, payment review, exact execution receipt, output validation, preview, and Apply action.
+
+This capability never gives package code access to project storage, provider credentials, or an unrestricted editor API. Its only accepted output is the public `timeline-edit` schema. The host compares each command's `before` value with the current project before applying it through ordinary permissions and undo history.
+
+## Manifest
+
+The manifest must use runtime `capability`, entry `src/capability.json`, exactly one `timeline-edit` output, and one to four inputs. At least one input must be a `timeline`. A project-bound timeline input declares `context: "timeline"`. The Block must declare both `context.timeline.read` and `timeline.propose`, plus the single capability permission `timeline.propose`.
+
+```json
+{
+  "runtime": "capability",
+  "entry": "src/capability.json",
+  "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":[]
+  }
+}
+```
+
+## Capability descriptor
+
+`src/capability.json` contains exactly `schemaVersion`, `operation`, `context`, `instruction`, `maxTokens`, and `output`.
+
+```json
+{
+  "schemaVersion": 1,
+  "operation": "timeline.propose",
+  "context": {
+    "timeline": {"$input":"timeline"},
+    "direction": {"$input":"direction"}
+  },
+  "instruction": "Use exact before snapshots, preserve locked items, and return strict JSON only.",
+  "maxTokens": 2000,
+  "output": "edit"
+}
+```
+
+`context` must bind every declared input exactly once. Instructions contain 1–6,000 characters. `maxTokens` is 1–4,096. Bound context is inert JSON and must stay under 24,000 encoded bytes so the exact reviewed request remains bounded.
+
+The provider must return one strict JSON object with the public timeline-edit shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "title": "Polish the cut",
+  "timelineId": "timeline-1",
+  "commands": [
+    {
+      "collection": "clips",
+      "operation": "transition",
+      "before": {"id":"clip-1","trackId":"video","start":0,"duration":4},
+      "values": {"type":"Cross dissolve","duration":0.35,"soundOn":false,"soundId":""}
+    }
+  ]
+}
+```
+
+Supported commands and their exact value fields are defined by `packages/block-sdk/timeline-edits.js`. Outputs with prose, code fences, unknown fields, unsupported commands, duplicate targets, more than 100 commands, invalid timing, or malformed `before` values fail before preview or Apply.
+
+Fixtures use nondeterministic expectations:
+
+```json
+{"edit":{"kind":"timeline-edit","minCommands":1,"maxCommands":10}}
+```
+
+Offline validation checks the contract, source, permissions, interface, fixtures, and remix readiness. It reports live execution as review-required. In StillMade, import and execution require the normal model/payment review. A generated proposal is shown to the user and never changes the timeline until Apply.

package/docs/build/transcription.md

@@ -0,0 +1,59 @@
+# Hosted audio transcription
+
+# Hosted audio transcription
+
+Use `runtime: "capability"` and `operation: "audio.transcribe"` to turn one persistent StillMade audio asset into reviewed text with word-level timings. The Block declares the work; the trusted host reads the selected owner-scoped file and performs the provider request. Package code and custom interfaces never receive an API key, filesystem path, network access, or provider response outside the typed result.
+
+## Complete contract
+
+The manifest must declare exactly one `audio` input, one `text` language input, and one `transcript` output. Include an asset control so the Block can be used directly, and give language a default such as `auto`.
+
+```json
+{
+  "manifest": {
+    "schemaVersion":1,"sdkVersion":"0.1.0",
+    "id":"example.transcribe-audio","version":"1.0.0",
+    "name":"Transcribe audio","description":"Turn one stored audio file into reviewed text with word timings.",
+    "kind":"task","runtime":"capability","entry":"src/capability.json","license":"MIT",
+    "provenance":{"notice":"Include the complete applicable license notice."},
+    "inputs":{"audio":{"type":"audio","primary":true},"language":{"type":"text","default":"auto"}},
+    "outputs":{"transcript":{"type":"transcript","primary":true}},
+    "permissions":{"project":[],"capabilities":["audio.transcribe"],"network":[],"filesystem":[],"secrets":[]},
+    "ui":[{"control":"asset","port":"audio"},{"control":"select","port":"language","options":["auto","en","es","fr","de","it","pt","ja","ko","zh"]}]
+  },
+  "capability":{"schemaVersion":1,"operation":"audio.transcribe","audio":{"$input":"audio"},"language":{"$input":"language"},"output":"transcript"},
+  "tests":[{"name":"English speech","input":{"audio":{"kind":"audio","assetId":"fixture-audio","versionId":"version-1","url":"/api/media/fixture/audio.mp3","mimeType":"audio/mpeg"},"language":"en"},"expectations":{"transcript":{"kind":"transcript","minWords":1,"maxWords":5000}}}]
+}
+```
+
+The capability descriptor has exactly `schemaVersion`, `operation`, `audio`, `language`, and `output`. Both inputs use exact `$input` bindings. The output names the single declared transcript port. Language is `auto` or a lowercase two-letter ISO 639-1 code. The audio value must be a persistent typed reference with `kind:"audio"`, nonblank `assetId`, `versionId`, and `url`; an in-memory blob or arbitrary remote URL is not sufficient.
+
+The result is exactly:
+
+```json
+{"schemaVersion":1,"text":"Hello world.","words":[{"text":"Hello","start":0,"end":0.4},{"text":"world.","start":0.4,"end":0.9}]}
+```
+
+Times are finite seconds in ascending word order, from 0 through 86,400. Results allow at most 100,000 words and one million transcript characters. Fixture expectations contain exactly `kind:"transcript"`, `minWords`, and `maxWords`; they test useful bounds rather than invented provider text.
+
+## Host execution and review
+
+The host offers two selections. **StillMade transcription** runs the app's own transcription (Groq Whisper Large v3 Turbo, with fal Whisper fallbacks) and is paid with StillMade credits at the app's upload-transcription price, quoted per fixture and sample before anything runs. **OpenAI Whisper** (`whisper-1`) uses the account owner's connected OpenAI key, spends zero StillMade credits, and OpenAI bills the connected account directly. Both accept supported audio up to 25 MB, request word timestamps, validate the response size and shape, and return only the normalized transcript. Uploading, validating, quoting, or previewing the package does not send audio.
+
+Before dispatch, StillMade binds the package source and version, exact inputs, owner, project, provider, model, payment method, and zero-credit quote. It checks project access and key availability, then checks account suspension again immediately before reading media and before provider dispatch. It reads only an owner-scoped StillMade media key. An uncertain provider submission is not automatically repeated, avoiding duplicate external charges.
+
+Offline validation does not need a key and cannot claim a live transcription. Import is Upload → validation and security/license checks → fixture/sample review → Install. In a project, the user chooses an audio asset and language, reviews the request, runs it, and accepts the timed transcript. The output can connect to any compatible `transcript` input.
+
+## Package and validate
+
+The downloaded SDK includes `packages/block-sdk/transcription-example.js` and `examples/transcribe-audio.stillmade.json`. Use your own namespace and include the real license and provenance for adapted source.
+
+```sh
+node packages/block-cli/cli.js validate examples/transcribe-audio.stillmade.json
+node packages/block-cli/cli.js pack examples/transcribe-audio.stillmade.json
+node packages/block-cli/cli.js validate example.transcribe-audio-1.0.0.stillmade.json
+```
+
+`pack` writes `<id>-<version>.stillmade.json`, the file to import in StillMade (Create, then Import Block).
+
+Before returning an artifact, confirm that it has one exact operation, usable generated controls, realistic fixtures, complete attribution, no embedded credentials or provider choices, no ambient permissions, and passes the same packaged validator used by StillMade.

package/docs/build/triggers.md

@@ -0,0 +1,59 @@
+# Triggers and unattended runs
+
+A Block can declare events it runs on by itself. Declaring a trigger runs
+nothing: when the Block is placed in a project, the project owner reviews each
+trigger and turns it on for that Step, with the same reviews as the automation
+panels. Results wait for the owner to review before they are used.
+
+```json
+{"triggers": [
+  {"event": "media.saved", "input": "video", "kinds": ["video"], "label": "When a new video is saved"},
+  {"event": "schedule", "everySeconds": 86400},
+  {"event": "webhook", "eventKind": "order.created"}
+]}
+```
+
+| Event | Fields | Runs when |
+| --- | --- | --- |
+| `media.saved` | `input` (the primary image, video, audio or asset input), optional `kinds` | New media is saved to the project (checked about every minute). Existing media is not processed. |
+| `schedule` | `everySeconds` (60 to 31,536,000) | On the interval, starting a minute after the owner turns it on. Missed runs are skipped. |
+| `webhook` | optional `eventKind` | Another service sends `POST /api/workflow-trigger-events/<id>` with the key the owner receives once (`Authorization: Bearer <key>`) and a JSON event `{id, kind, occurredAt, data}` up to 64 KB. Repeated event IDs run once. |
+| `project.completed` | none | Another project the owner chooses is marked complete. |
+| `provider` | `appId`, `eventKind` | A connected app reports the event; the owner connects the account. |
+
+Up to 4 triggers per Block. A webhook, schedule or provider Block receives the
+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 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
+
+A hosted Block (generation, analysis, speech, transcription, web reading) runs
+unattended only after the owner approves it for that Step:
+the model and payment, credits per run, total credits, number of runs and how
+many days the approval lasts. The approval reuses the owner's earlier review of
+the Block with that model, so run the Step once yourself first. Each automatic
+run:
+
+- claims its credits on the approval before anything is sent, so the total is
+  never exceeded, and stops and waits for the owner if the price rises above the
+  per-run ceiling or the approval is used up, revoked or expired;
+- runs as one job with one workflow budget, and is never paid twice: a resumed
+  or retried job polls the same hosted request;
+- can take longer than the sandbox's 25 seconds. A long call (for example video
+  generation) puts the job in a timed wait and StillMade polls it until it
+  finishes. Cancelling the job cancels the hosted call.
+
+Timeline and workspace proposals never run unattended; they always wait for a
+person.
+
+`autoCaptions` and `orderNote` in `@stillmade/block-sdk` are complete examples:
+transcription of each new video into timed captions (`media.saved`), and a
+JavaScript Block that turns a shop's webhook into a production note. The SDK
+helpers `BLOCK_TRIGGER_EVENTS`, `BLOCK_TRIGGER_LIMITS`, `UNATTENDED_RUNTIMES`,
+`triggerProblems`, `blockTriggers`, `describeTrigger` and `triggerReview`
+(what the owner reviews for each trigger) check and describe declarations.