stillmade-sdk 0.0.0-stage → 0.1.0

package/COOPERATIVE_GUEST_JOBS.md

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

package/DEFINE_BLOCK.md

@@ -0,0 +1,39 @@
+# Defining a semantic Block
+
+Structured outputs may declare more fields than a consuming input needs. Static
+compatibility checks require every expected field to have a compatible producer
+guarantee, including nested objects and primitive arrays. Text/string aliases
+and integer-to-number field widening are supported; optional producer fields
+cannot satisfy required inputs. Unknown extra fields do not prove an optional
+target field's type. Execution still validates the actual value and permissions.
+
+`defineBlock()` builds an immutable, isolated snapshot of an ordinary SDK package.
+It performs the existing package-admission checks and requires semantic contracts
+on its inputs and outputs. It does not run code, fixtures, adapters or providers,
+install anything, publish, or approve spending.
+
+```js
+import {defineBlock,input,output} from './packages/block-sdk/index.js';
+
+const block=defineBlock({
+  manifest:{
+    schemaVersion:1,id:'example.subject-trimmer',version:'1.0.0',
+    sdkVersion:'0.1.0',name:'Tidy subject',description:'Trims an email subject.',
+    kind:'task',runtime:'recipe',license:'MIT',
+    inputs:{subject:input({key:'subject',type:'text',semantic:'email_subject',
+      required:true,description:'Subject to tidy'})},
+    outputs:{subject:output({key:'subject',type:'text',semantic:'email_subject'})},
+    permissions:{project:[],network:[],filesystem:[],secrets:[]}
+  },
+  recipe:{schemaVersion:1,steps:[{id:'trim',op:'text.trim',
+    args:{text:{$input:'subject'}}}],outputs:{subject:{$step:'trim'}}},
+  tests:[{name:'Trims spaces',input:{subject:' Hello '},expected:{subject:'Hello'}}]
+});
+const portableSource=JSON.stringify(block);
+```
+
+The result uses the same package format as normal import, review and execution.
+JavaScript implementations remain source strings executed through the existing
+sandbox, not functions passed into the host. Passing `defineBlock()` is not proof
+that fixtures passed or the Block works in production. Legacy packages keep their
+existing admission path; this helper does not rewrite immutable releases.

package/DESKTOP_CAPABILITIES.md

@@ -0,0 +1,85 @@
+# Desktop capabilities for Blocks
+
+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.
+
+Declare the exact required scopes in `manifest.permissions.desktop`. Other permission families remain unchanged. Pure recipe/JavaScript execution stays sandboxed; the **Block UI bridge** requests desktop operations through the trusted host.
+
+| Scope | UI operation | Behavior |
+| --- | --- | --- |
+| `screen.capture` | `record.start`, `{kind:"screen"}` | Choose a screen or window, then record it. |
+| `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. |
+| `microphone.capture` | `record.start`, `{kind:"microphone"}` | Microphone recording after device/OS approval. |
+| `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. |
+
+The host always checks declarations. Declaring a scope does not grant it. A browser receives a clear desktop-required error; there is no silent paid/cloud fallback.
+
+## Approved native desktop tools
+
+Native applications use a separate allowlisted adapter contract. The Block stays an ordinary sandboxed SDK package and must declare both `permissions.desktop:["native.tools"]` and a desktop-only platform matrix. `manifest.desktopTools` pins the exact adapter version and actions. A Block cannot supply an executable, command, path, environment variable, installer, or additional argument.
+
+Natron adapter version 1 currently exposes `launch`, `project.import`, `project.open`, and `project.render`. Project import copies one user-selected `.ntp` file into that Block version's workspace and returns an opaque project ID. Open accepts only that opaque ID or `latest`. Render accepts a locally authorized StillMade video, bounded Reader/Writer node names, and a frame range of at most 10,001 frames. The trusted host invokes `NatronRenderer` with only the pinned project, `-i`, `-w`, host-resolved input/output paths, and the bounded range. It never accepts Natron's Python/interpreter flags or a Block-supplied path. The completed render is imported into the StillMade media library and returned as a typed video asset.
+
+```json
+{
+  "platforms":{"phone":{"supported":false,"reason":"Requires Natron and StillMade Desktop."},"browser":{"supported":false,"reason":"Requires Natron and StillMade Desktop."},"desktop":{"supported":true}},
+  "permissions":{"project":[],"network":[],"filesystem":[],"secrets":[],"desktop":["native.tools","media.pick"]},
+  "desktopTools":[{"id":"org.natron.Natron","adapterVersion":1,"actions":["launch","project.import","project.open","project.render"]}]
+}
+```
+
+The mapped Natron Block uses `video` as both its primary typed input and output, with semantic `video`. This allows an explicit Project Type chain such as video producer → Natron → review/export Block. Its custom interface submits the connected original input and render settings to `StillMade.run`; the approved desktop executor invokes the renderer and returns the newly registered artifact with a bound native receipt. Source fixtures and JavaScript passthrough do not prove native execution. See [Native desktop execution](DESKTOP_EXECUTION.md) for `src/desktop.json`, offline admission, host callbacks and retained-result requirements.
+
+## 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 its preview in the desktop app. Each includes a themed interface and pure runtime fixtures that preserve the media reference. The fixtures use synthetic references; they do not exercise your device.
+
+The interface saves recording media before sending it through the runtime. If that handoff fails, Retry uses the saved recording without recording again.
+
+## Recording example
+
+Manifest fragment:
+
+```json
+{"permissions":{"project":[],"network":[],"filesystem":[],"secrets":[],"desktop":["screen.capture","cursor.track"]}}
+```
+
+Inside your validated `view.javascript`, attach explicit start/stop controls:
+
+```js
+const start = document.getElementById('start');
+const stop = document.getElementById('stop');
+const status = document.getElementById('status');
+start.addEventListener('click', async () => {
+  try {
+    await StillMade.desktop('record.start', {kind:'screen', cursor:true});
+    status.textContent = 'Recording. Press Stop when finished.';
+  } catch (error) { status.textContent = error.message; }
+});
+stop.addEventListener('click', async () => {
+  try {
+    const result = await StillMade.desktop('record.stop');
+    // Declare matching video and metadata inputs in the Block manifest.
+    // Your sandboxed runtime can pass these through as typed outputs.
+    await StillMade.run({video:result.asset, cursor:{samples:result.cursor, displays:result.displays}});
+    status.textContent = 'Recording saved to your local media library.';
+  } catch (error) { status.textContent = error.message; }
+});
+```
+
+`record.stop` returns `{asset,cursor,displays,coordinates}`. `asset` is a canonical media reference with `assetId`, `versionId`, `kind`, `mime`, and a device-local `sm-media:` URL. 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.
+
+`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, 30 minutes, 128 MiB, WebM output. Hitting a limit cancels the recording; callers should stop and save earlier. 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.
+
+## Testing and installation
+
+Test the pure typed-input/output runtime with synthetic media references and the regular SDK fixture tests. Then test the actual desktop operation interactively: allow, deny, stop, cancel, close, expired access, missing devices, source selection, and OS revocation. Passing a synthetic fixture or an Electron renderer test does **not** verify real OS permissions.
+
+No extra native dependency, installer prompt, or blanket OS permission is introduced. macOS may require the user to enable StillMade in Screen Recording settings and restart it; StillMade cannot bypass that OS decision. Windows privacy settings may also block camera/microphone access. The grant dialog appears only when the Block requests the relevant operation.

package/DESKTOP_EXECUTION.md

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

package/FRAME_VIEWS.md

@@ -0,0 +1,98 @@
+# Frame views: any interface code
+
+A frame view (`"runtime": "frame"` in the view) is an interface written with
+ordinary web code: React, Svelte, Vue or Preact bundles, SVG, canvas and
+WebGL, pointer capture and drag, timers, loops, recursion, classes and Web
+Workers. Use it when the reviewed subset of standard views is too small for
+the interface you want.
+
+## Folder layout
+
+```
+my-block/
+  stillmade.block.json
+  src/run.js             or another runtime (recipe, module, capability)
+  src/view.html          markup, for example <div id="root"></div>
+  src/view.css           styles; use StillMade's theme variables
+  src/view.js            ONE classic script: bundle with --format=iife
+  src/view.config.json   {"runtime": "frame"}
+  tests/fixtures.json
+```
+
+`src/view.config.json` may also set `"appearance"` and `"files"` (assets, see
+below). Bundle npm dependencies into `src/view.js` as an IIFE, for example:
+
+```sh
+esbuild src/view.jsx --bundle --format=iife --minify --jsx=automatic \
+  --define:process.env.NODE_ENV='"production"' --outfile=src/view.js
+```
+
+Limits: markup and each stylesheet up to 256 KiB, `view.js` up to 4 MiB,
+and up to 32 asset files with 8 MiB in total.
+
+## The `StillMade` object
+
+Frame views get the same `StillMade` object as standard views: `input` and
+`onInput`, `run`, `useOutput`, `getShared`, `onShared`, `updateShared`,
+`bindShared`, `connectDocument`, `previewImage`, `previewMedia`, `render`
+and the rest of the interface bridge. In addition:
+
+| Member | What it does |
+| --- | --- |
+| `StillMade.asset(path)` | A `blob:` URL for one of the view's asset files, for `<img>`, `new FontFace()` or `<video>`. |
+| `StillMade.assetBytes(path)` | A copy of an asset file's bytes as an `ArrayBuffer`. |
+
+Shared state works as in every view: keep each independently edited value in
+its own field (for example `point0`, `point1`) so two people editing
+different values never conflict.
+
+## Theming
+
+The theme variables from StillMade's design system are always defined:
+`var(--bg)`, `var(--bg-elev-1)`, `var(--fg)`, `var(--fg-muted)`,
+`var(--accent)`, `var(--border-tok)`, `var(--divider)`, `var(--r-3)` and the
+rest. Colors written with them follow Light, Dark and White automatically.
+Frame views are not required to use them; the appearance check reports
+hard-coded colors as advice instead of refusing the view.
+
+## Assets
+
+Images, fonts, JSON, audio and video the view needs ship as files named by
+SHA-256, like module files:
+
+```json
+{"runtime": "frame", "files": {"schemaVersion": 1, "files": {
+  "fonts/inter.woff2": {"sha256": "…", "bytes": 48256, "mediaType": "font/woff2"}
+}}}
+```
+
+`stillmade-block pack` fills in the digests and sizes. StillMade checks every
+file against its SHA-256 before the view starts.
+
+## What the frame does not allow
+
+The view runs in an opaque-origin frame with its own policy:
+
+- no network (`fetch`, WebSocket and remote images, fonts or scripts fail);
+- no code from strings (`eval`, `new Function`, inline event attributes) and
+  no extra script elements;
+- no navigation, popups, downloads, forms that submit, or dialogs;
+- no WebAssembly on the page (run heavy computation in the Block's runtime,
+  for example a module Block, and call it with `StillMade.run`);
+- no storage or access to StillMade's page.
+
+Workers created from `blob:` URLs are allowed and run off the page's thread.
+
+## Run limits
+
+StillMade compiles the view so every function and loop checks a time budget.
+One task may run for 250 ms; past that it is stopped with an error, and a view
+that keeps the page busy most of the time, stops answering, or navigates its
+frame is closed with a message. A single built-in operation that blocks for a
+second or more (a huge sort, or a regular expression that backtracks) also closes
+the view where the browser reports it. Move long computation into a Worker or the
+Block's runtime.
+
+The host enforces every permission itself: a view's code can message the host
+directly, so a read-only viewer cannot run the Block or save outputs from any
+view.

package/GITHUB_APPLICATIONS.md

@@ -0,0 +1,129 @@
+# Import an application from GitHub
+
+This guide describes the current SDK boundaries and the integration procedure.
+It does **not** claim that every repository can already run inside StillMade.
+The source contract, import inspector, restricted UI and reviewed native adapter
+are implemented. An isolated application build worker and bundled React/Vue/Svelte
+runtime are still required for arbitrary web applications.
+
+## Preserve the requested scope
+
+The default GitHub import intent is the complete application with its existing
+interface. Record the immutable commit, application root and important actions
+before adapting code. The importer must not replace that intent with one utility.
+The separate **Extract one capability** mode explicitly authorizes narrower scope.
+
+The in-app full-application inspection pins source and retains an inventory of
+code, binary assets, dependency manifests, lockfiles, symlinks and submodules.
+It returns `not-built`, including unfinished feature and runtime checks. A complete
+file inventory is neither a complete dependency checkout nor a successful build.
+Inspection uses public unauthenticated GitHub APIs; it does not authorize private
+repository access, install dependencies, execute scripts or charge model credits.
+
+Use the exported `defineRepositoryApplication` contract to record the requested
+scope, interface, versioned route and source-backed feature ledger. Use
+`assessRepositoryApplication` to identify missing evidence. Its highest status is
+`evidence-complete`: supplied receipt declarations are not independent execution
+verification. The assessor always reports `executionPerformed:false` and
+`independentlyVerified:false`. A model cannot certify its own integration by
+filling in that object.
+
+## Choose an actual runtime
+
+| Source | Current boundary |
+| --- | --- |
+| Existing SDK source folder/package | Import its pinned source and run normal admission. |
+| Bounded JS or recipe capability | Adapt the real computation to the existing sandbox and provide typed contracts. This is capability scope. |
+| Restricted HTML/JS custom view | Supported within the documented DOM and bridge restrictions. Original styling may be preserved. |
+| React, Vue, Svelte, workers, arbitrary WASM or full frontend bundle | No general application runtime yet. Do not paste a bundle into `view.javascript`, remove security checks, or claim a static mount as acceptance. |
+| Natron native application | An approved desktop adapter retains the original application in a separate native window and performs bounded rendering. It is not embedded web UI or a source build. See [Desktop execution](DESKTOP_EXECUTION.md). |
+| Arbitrary native executable, Python/Node backend or full stack service | Requires an implemented, reviewed isolated runtime and capability contract. A README, wrapper or external command is insufficient. |
+
+The separate experimental [browser application contract](BROWSER_APPLICATIONS.md)
+preserves compiled assets and original UI code with a Block-owned lifecycle
+adapter. The exact reviewed Method Draw source has a private desktop install,
+editing and SVG export path. Other applications require separate source,
+runtime and result review; package validation alone is insufficient.
+
+## Keep the original appearance
+
+For an eligible restricted view, place this option in `src/view.json`:
+
+```json
+{"appearance":"original"}
+```
+
+Keep the application's permitted CSS in `src/view.css`. StillMade still supplies
+the outer workspace, focus and permission controls. Original appearance does not
+grant extra scripting, networking, storage or navigation permissions.
+
+To offer optional StillMade styling, include `src/view.themed.css` using the
+documented theme tokens. The themed preview is offered only when that stylesheet
+passes appearance checks. Omitted appearance preserves the existing package
+behavior; published packages are not rewritten to change this preference.
+
+## Connect meaningful inputs and outputs
+
+Every required input needs a physical type, a precise semantic meaning, allowed
+sources, and an explicit way to supply missing data. Do the same for output
+meaning and representation. A video output is the actual new saved video, with
+its own exact asset/version identity; returning the source video is not evidence
+that an editor transformed it.
+
+The existing `image` type also accepts bounded inline RGBA pixels as
+`{width, height, data}`. A small editor can import those pixels and return its
+actual composited pixels without inventing an asset ID. Respect both the image
+contract and the complete runtime message limits. Large or referenced media
+still needs the host's authenticated asset resolution and materialization path;
+a guest-local data/blob URL is not a durable shared asset.
+
+Map existing app behavior to SDK input, shared-document and output interfaces.
+Do not recreate the application's logic in the shared host or add a special
+Block-ID branch. Persist editable state through declared host services and keep
+two placements separate. Input changes, revoked permission, cancellation and
+closed workspaces must reject late completion.
+
+Native output-producing actions use `src/desktop.json`: declarative mappings from
+typed input ports into an approved adapter and from its actual result into output
+ports. The trusted host produces a receipt bound to the package, invocation,
+inputs and outputs. Neither a Block's view nor its JavaScript can supply the host
+executor or mint accepted native evidence. Legacy native packages without this
+mapping cannot pass a generic workflow by returning their input unchanged.
+
+## Prove the integration
+
+1. Establish an upstream baseline with a representative input and inspect the
+   exported bytes. Retain the original app's important behavior and interface.
+2. Build only in a disposable isolated worker without application credentials,
+   customer mounts or unrestricted network access. Preserve licenses and exact
+   dependency/asset identities. If no suitable worker exists, report that gap.
+3. Execute a real producer → imported application → consumer through the
+   production resolver. Fixtures, screenshots, schemas and successful process
+   exit codes alone cannot prove transformed output.
+4. Decode exports; compare with the baseline; verify the consumer receives those
+   exact bytes. Check real playback separately from codec decoding.
+5. Save/reopen, edit while running, cancel, revoke access, retry failures, use two
+   placements and verify stale output behavior. Exercise permission and resource
+   limits with hostile inputs.
+6. Retain the tested package digest, source commit, runtime version, commands,
+   bounded logs, artifacts and pass/fail evidence. Install the exact artifact
+   tested. Edits require new checks and published contract changes need a new
+   version.
+
+Keep inspection, source admission, runtime tests and production verification as
+separate states. Native bindings validate host-issued evidence; they are not a
+cryptographic attestation from an arbitrary caller. The trusted host is responsible
+for process isolation and actual artifact verification.
+
+The first local Natron acceptance rendered 24 frames of an inverted synthetic
+video, passed the real result through a three-Step workflow, matched its decoded
+pixels exactly to an independent native baseline, and reopened saved workflow and
+media. The same H.264/YUV420 output also played all 24 frames in a sandboxed
+Electron video element. ProRes decoded successfully in the native probe but did
+not play in Chromium; choose a browser-compatible Writer codec or explicitly
+produce a separate playback proxy. This establishes that specific macOS
+software-rendering path. It does not
+establish all Natron features, third-party plugins, original GUI containment,
+product UI media routing, other operating systems, source build reproducibility,
+or arbitrary-repository support. The repository acceptance harness and evidence
+remain distinct from the SDK's offline tests.

package/IMAGE_DESCRIPTION.md

@@ -0,0 +1,45 @@
+Use `runtime: "capability"` with `operation: "image.describe"` when a Block must inspect one image and return plain text. This is the portable boundary for visual analysis: the Block declares its image input, analysis instructions, output, tests, and license; StillMade owns image loading, provider credentials, model/payment selection, approval, accounting, and the retained execution record.
+
+The downloaded SDK includes `examples/describe-image.stillmade.json` and `packages/block-sdk/image-description-example.js`.
+
+```json
+{
+  "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",
+    "inputs": {"image": {"type": "image", "primary": true}},
+    "outputs": {"description": {"type": "text", "primary": true, "role": "visual_description"}},
+    "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"]}}
+  }]
+}
+```
+
+Declare exactly one `image` input (or one `image[]` input to describe or compare one to four images together, in order) and one `text` output. The descriptor contains exactly `schemaVersion`, `operation`, `image`, `instruction`, `maxTokens`, and `output`. `image.$input` names the declared image port. Instructions must contain 1–8,000 characters and `maxTokens` must be 1–4,096. Provider names, endpoints, keys, payment settings, arbitrary URLs, and executable code do not belong in the descriptor.
+
+Fixture inputs may use bounded RGBA pixels for offline contract validation. Real runs use a persistent image reference selected through StillMade. The trusted host requires the referenced media to belong to the signed-in account, reads and bounds the stored bytes, canonicalizes the image to PNG, and sends that image through the exact approved provider request. Block code never receives credentials or storage access.
+
+Tests describe nondeterministic text expectations: `kind:"text"`, ordered `minLength` and `maxLength`, and up to eight literal `includes` phrases. They do not contain fabricated descriptions presented as provider evidence. Offline validation and packaging inspect the contract and report that live review remains required. In StillMade, the creator runs every fixture and a separate sample, reviews the output, and confirms the import.
+
+`prepareCapabilityInvocation` returns `{operation:"image.describe",image,instruction,maxTokens}`. The host returns the named text output through the same capability result, quote, review, project execution, cancellation, failure, and receipt flow used by other hosted Blocks. A completed text record proves the exact package, input, selection, and output passed validation; it does not prove that every sentence is factually correct, so the user reviews the description before using it downstream.

package/INTERACTION_VALUES.md

@@ -0,0 +1,27 @@
+# Timeline range and workflow decision inputs
+
+Original specification §17 calls for timeline-range and approve/reject controls. Shared Create provides these automatically for scalar `timeline-range` and `approval` inputs. Connected or project-bound inputs remain read-only. These controls use ordinary typed workflow data; they never grant host authority or directly mutate a project.
+
+The types previously admitted arbitrary `schemaVersion: 1` documents. That contract remains valid. Existing documents are displayed with their existing data editor until the user explicitly chooses the new controls. Opening controls does not change the input; applying a range or selecting a decision replaces it. The target Block must understand version 2. No conversion or defaults are injected into existing fixtures, saved settings or connected data.
+
+## Version 2 contracts
+
+A timeline range has exactly these fields:
+
+```json
+{"schemaVersion":2,"startMs":1000,"endMs":2500}
+```
+
+Both times must be finite numbers in milliseconds, with `0 <= startMs <= endMs <= Number.MAX_SAFE_INTEGER`. Fractional milliseconds and equal endpoints are allowed. Equal endpoints represent a point. The upper bound is a numeric safety limit, not a claim about project duration or media availability. This value does not contain asset identifiers, select clips or apply timeline edits. Consumers validate their own project-specific applicability.
+
+A workflow decision has exactly these fields:
+
+```json
+{"schemaVersion":2,"decision":"deferred"}
+```
+
+The decision is `accepted`, `rejected` or `deferred`. Absence is not acceptance or deferral. The user must click a decision to supply a value. A Block may also emit such ordinary data; its provenance does not imply that a human approved it. Never use this value instead of host permission, payment, publishing, provider confirmation or project-edit approval.
+
+The SDK exports `isTimelineRange`, `isApprovalDecision` and `TIMELINE_RANGE_MAX_MS`. TypeScript interfaces `TimelineRange` and `ApprovalDecision` describe only version 2. Generic SDK value validation preserves version 1 compatibility and strictly checks version 2; unknown versions or additional version 2 fields are rejected. The same checks apply to array elements, but this increment adds specialized controls only for scalar ports.
+
+Implementation was reviewed from source only. No tests, browser checks, verification builds or runtime calls were performed. Regenerate SDK deliverables separately to publish updated downloadable source; archive generation includes the helper and type declaration.

package/INTERFACE_DESIGN.md

@@ -0,0 +1,85 @@
+# Block interface design
+
+Simplicity first: show the work and the next useful action. The app owns project navigation; a Block owns its production surface. Neither needs a second shell.
+
+## Mandatory authoring rules — for LLMs and creators
+
+These are requirements, not optional conventions. Authors must follow them;
+they are not all machine-enforced. Explicit user requests may authorize the
+named exception, but do not authorize unrelated technical UI.
+
+- Do not add Technical result, Result details, JSON dumps, source editors,
+  manifests, debug consoles, or diagnostic panels to a production workspace
+  unless the user explicitly requests that surface or the stated task is
+  source/debug inspection. A collapsed disclosure is still an added surface.
+- Do not nest decorative cards, bordered panels, or modal shells around the
+  same work area. Use one workspace with spacing and labels. Nested containers
+  needed for layout are fine; repeated visible framing is not.
+- Do not duplicate the host's step navigation, counters, or workspace identity.
+- Do not append a generic Workflow tools menu to production Blocks. Batch,
+  loop, schedule, memory, migration, and diagnostic tools are not default
+  workspace chrome; add a specific surface only when explicitly requested.
+- Show the useful output itself, not a technical representation of the output.
+- Keep required approvals, errors, progress, and stale-input warnings visible.
+  These are operational feedback, not optional diagnostic panels.
+- Do not lock page scrolling or introduce sticky headers unless the task
+  explicitly needs them. A production page must keep all controls reachable.
+  The host owns page scrolling; embedded workspaces may scroll their own
+  content, but must not trap scrolling or clip controls below the viewport.
+- Do not keep media galleries, asset inputs, or control strips sticky by default.
+  They belong to the same scrolling task surface. A fixed timeline/inspector is
+  appropriate only when the actual editing task requires that layout, with all
+  controls still reachable; it is not a default for every Block.
+- Do not add an ambiguous settings gear for task actions. Show the immediate
+  action directly; label secondary task controls by purpose. Do not disguise
+  source, wiring, or debug controls as ordinary production settings.
+
+For an existing Block, apply the [SDK update procedure](/block-sdk/PASTE_TO_LLM.md#updating-existing-blocks-through-the-sdk)
+to the actual owned source and a new release/remix. These requirements do not
+authorize rewriting published packages or silently repinning saved projects.
+
+## Rules — implemented enforcement
+
+These are implementation facts, not aesthetic suggestions.
+
+- The host supplies the Project Type step bar. Production workspaces do not add another step counter or Back/Next bar.
+- For custom views the host omits its duplicate title and outer frame border. Sandbox isolation remains enabled.
+- The host does not append a generic Technical result disclosure to custom workspaces. Stored outputs and required approval actions are preserved.
+- Shared form containment wraps adjacent labeled controls and keeps checkboxes compact.
+- Admission rejects a primary textarea with 12 or more rows when no task presentation is detected. This is a narrow heuristic, not proof of a usable visual workspace: `StillMade.render` can render text cards.
+- HTML, JavaScript, permission, and appearance validation remain separate checks. Simplicity never bypasses safety or approval.
+
+The SDK exports `INTERFACE_DESIGN_RULES` separately from `INTERFACE_DESIGN_CONVENTIONS`. The older `INTERFACE_DESIGN_PRINCIPLES` export is a compatibility alias for conventions, not enforced guarantees.
+
+## Conventions — design guidance
+
+Static review warns about more than eight visible controls, ungrouped large option sets, and multiple primary headings. Warnings are not hard failures. The following guidance requires design review; it is not automatically enforced.
+
+### Do not
+
+- Repeat the Block name, step number, or workflow navigation in nested panels.
+- Place a workspace in a card inside another card merely to create hierarchy.
+- Use dialogs as permanent page layout or put a dialog inside another dialog.
+- Give every section a border. Use spacing and short labels.
+- Put twenty controls in the initial view, even if they wrap.
+- Show camera, timing, patch, variant, and export settings before they are needed.
+- Make users read a technical plan to reach the actual work.
+- Call text scene descriptions a visual storyboard, frame review, or motion preview.
+- Present placeholder imagery as the actual approved assets.
+- Lead with JSON, manifests, MCP, transport details, or diagnostics.
+- Add decorative circles around icons, emoji controls, or unlabeled icon buttons.
+- Claim approval, rendering, or successful testing without the actual result.
+- Hide spending approvals, failures, or stale-source warnings for neatness.
+- Discard drafts or selections when collapsing controls or changing layout.
+
+### Prefer
+
+One obvious primary action, strong defaults, and the controls needed for the current decision. Group advanced adjustments behind labeled disclosures. Use recognizable line icons with accessible names, tooltips, keyboard focus, and generous hit areas; keep text when an icon is ambiguous.
+
+Use StillMade theme tokens, typography, and spacing. Give the preview, timeline, images, or other task object the main surface. Only include source or diagnostic surfaces when authorized under the mandatory authoring rules above; do not add them automatically, even collapsed.
+
+Motion workflows distinguish planning notes from actual frame approval. Frame Review should display the exact images being approved before Motion Designer uses them. Motion preview should display the composition, not just its layer descriptions. These are product acceptance requirements to verify, not guarantees established by static admission.
+
+## Known coverage gap
+
+Existing pinned Blocks can still contain excessive nested panels and text-only plans. Host containment does not redesign their interfaces. Correct those through new versioned Block releases and explicit upgrades; do not rewrite immutable releases or silently change a saved workflow's pins.