stillmade-sdk 0.1.42 → 0.1.44

package/docs/build/github-applications.md

@@ -0,0 +1,314 @@
+# GitHub application imports
+
+# 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 first uses public unauthenticated GitHub APIs; it does not authorize private
+repository access, install dependencies, execute scripts or charge model credits.
+An exact commit's complete, verified public tree and Git-blob-checked source
+bytes may be reused from a 15-minute, 24 MiB process-local cache across the
+inspection, build and source-recheck phases. Branch/HEAD resolution, partial
+trees, failed reads and unverified bytes are not cached. Source review reports
+`pinned-cache` when it uses that evidence instead of claiming a fresh API read.
+The cache avoids repeated anonymous requests for one pin; a cold repository
+still depends on GitHub availability and its rate limit, and another server
+process has its own cache. It is not a substitute for an authenticated or
+archive-backed source acquisition route at larger scale.
+When the public REST API is rate-limited, the application import can instead
+resolve the public branch or tag through bounded Git protocol v2 HTTP and inspect a
+GitHub codeload archive at the resulting commit. The host checks the archive's
+commit marker, tar structure and paths, computes Git blob identities from
+actual bytes, rejects sensitive or oversized selected files, and labels this
+evidence `pinned-github-archive`. A named ref uses two bounded Git HTTP requests
+before the archive request; an exact commit needs only the archive request.
+This fallback is capped at 12 MB compressed and 40 MB expanded, requires no
+Git executable on the server, and refuses repositories with
+submodules because the archive omits their Git identities. Larger archives
+must use the Git tree route or a future bounded acquisition worker. Archive
+inspection is source evidence only; it does not approve execution or install.
+The REST and fallback phases use the same caller-owned HTTP transport when one
+is provided. Reported request use includes both phases. Reported byte use
+includes REST and archive bodies; the two Git-ref responses have separate
+64 KiB limits and are not included in that aggregate byte figure.
+For a complete Git tree containing submodules, inspection reads the pinned
+`.gitmodules` blob, accepts only canonical or relative GitHub repositories,
+and follows each exact Gitlink commit (including nested modules) within one
+48-request, 32 MB metadata and 24-placement bound. It reports each dependency
+commit separately. This verifies dependency identities and file inventories;
+the isolated builder must still acquire and hash the actual dependency bytes
+before running their code. Missing mappings, outside hosts, incomplete trees
+and exhausted bounds fail with a specific source-graph reason.
+The larger isolated-build acquisition profile can verify a complete archive
+against that Git tree, including ordinary files and symlink identities. GitHub
+codeload can omit files under `export-ignore` or transform exported text; those
+paths must be restored from exact-commit raw transport and independently
+rehashed to their pinned Git blobs. The raw route is limited to 64 files and
+8 MB, denies sensitive paths, uses no credentials or redirects, and cannot
+grant execution. All archive and recovered bytes are checked before a trusted
+staging callback receives any file. This profile has not yet been connected
+to a complete native build or installation workflow.
+The inspection `readable` flag controls what the LLM can request as source
+text. It is not a build-file filter. A separately checked `stageable` flag
+allows oversized but bounded files and inert symlink-target blobs into the
+private build-source quarantine; sensitive paths remain excluded. Symlink
+targets are stored as bytes, not followed or created as active filesystem
+links. A later materializer must validate every link target before use.
+The isolated-worker source-closure orchestrator groups identical pinned
+repositories across submodule placements, rechecks each exact commit, and
+hands verified bytes to a trusted quarantined staging callback under one
+request, network-byte, file, staged-byte and deadline budget. Its receipt is
+`execution:not-run` and `installable:false`; a partial stage has no activation
+authority. The connected private staging writer uses content-addressed inert
+blobs and rereads each file before sealing it. A complete closure produces a
+read-only manifest bound to a host-retained digest; reopening the quarantine
+audits every blob against its Git identity. Partial stages cannot be sealed.
+The inert tree planner checks file/directory namespace collisions and resolves
+symlink targets only within the exact staged closure, without expanding source
+paths on the host filesystem. A bounded transfer format then packs each
+audited Git blob once and binds its canonical namespace, modes, link targets,
+source digest and sealed-manifest digest into a SHA-256 bundle. The Linux
+materializer independently verifies the bundle and Git hashes, creates files
+through private directory descriptors, creates links only after file writes,
+and audits the final tree. A synthetic tree with an executable and links ran
+in the isolated VM; a changed bundle was rejected before staging. Natron's
+allowed exact closure also materialized there: 6,445 files and 654 directories.
+This development path is not yet a trusted install or execution admission:
+the stage owner can still change its read-only modes, and build recipes,
+dependencies, GUI sessions and result contracts need separate host control.
+For an npm browser candidate, inspection also reads the pinned `package.json` and
+`package-lock.json` through the same bounded source verifier. It checks that root
+dependency declarations agree and distinguishes integrity-pinned npm tarballs,
+exact-commit GitHub dependencies and unresolved sources. This is a build plan,
+not dependency acquisition or build admission. The pinned miniPaint case has
+517 npm tarballs and one exact-commit GitHub dependency; an isolated builder
+must acquire and verify both kinds before executing its Webpack build.
+Before rebuilding, the importer checks whether the pinned repository already
+contains an HTML entry referencing a checked-in local browser bundle. It selects
+the referenced scripts/styles and bounded local media resources, then verifies
+every selected byte against the Git tree. This can preserve a real original UI
+without executing a package script. It is still only a candidate: dynamic
+resource requests, operations, state and output must pass isolated review.
+miniPaint's checked-in bundle passed a separate local browser probe with a real
+brush stroke, changed PNG bytes and exact document restore in a second page.
+That probe is not an installed Block or a host-enforced multiplayer result.
+The local acquisition module also re-read miniPaint's exact pinned lockfile and
+verified all 518 dependencies (about 18.2 MB) against registry SHA-512 or Git
+blob identities. Those bytes were discarded after the probe. A managed stage,
+isolated framework rebuild and reviewed execution admission are still missing.
+
+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.
+
+For a generated browser application, put the exact GitHub repository URL,
+40-character commit and application folder in
+`manifest.provenance.githubSource`. The SDK checks its shape and the source
+reviewer independently matches it to the pinned Git tree and every bundled
+original asset. This field travels with the versioned package; it is source
+identity, not permission, a license decision or evidence that the adapter ran.
+Older uninstalled candidates without the embedded pin can still undergo
+source review, but must not be promoted to production solely from that legacy
+shape.
+
+For a framework application built from pinned source, the unreviewed candidate
+also carries `manifest.provenance.browserBuild`: the verified source-closure
+digest, build-script digest, output directory and digest of every original
+compiled file. A model may author the lifecycle adapter, but cannot supply the
+build result or certify it. A trusted host must independently rederive the
+Git source closure, verify the exact isolated build and reconstruct the full
+application bundle before running the ordinary interface, state and output
+review. The current SDK handoff and internal verifier implement these checks;
+the production build supervisor and review issuer are not yet connected to the
+GitHub button. A build or source receipt alone does not make a Block installable.
+An internal npm job now composes the sealed source bundle, Linux materializer,
+integrity-pinned registry and exact-commit GitHub package stages, and the
+network-denied build runner. It checks each identity again between stages and
+returns compiled bytes with no installation authority. The Linux npm profile
+now caps selected packages at 768, verified expanded package bytes at 256 MiB,
+and package files at 18,000. It caps compiled files at 16 MiB total, each
+file at 8 MiB, and the encoded build report at 24 MiB, with a root `dist`,
+`build` or `out` entry. It
+omits a lockfile package only when that package is explicitly optional and
+incompatible with the worker's OS, CPU or libc; the root launcher rechecks
+that selection against the pinned lock before execution. It has not run
+miniPaint's build, and still needs the durable supervisor lease and cleanup
+needed for a production
+button. The stage-order tests are offline; no real framework repository has
+passed this composed job. The worker also exposes a trusted rebuild callback
+for the compiled-candidate source verifier; the caller must run it under the
+same host-owned supervisor rather than accepting a browser-supplied report.
+
+A successful framework build does not prove that all runtime assets are local.
+For example, CanvasCode compiled from its pinned source but loaded Monaco from
+a CDN; the isolated network-denied browser showed its preview while the editor
+remained unavailable. Manually bundling the already pinned Monaco dependency
+restored the editor and real ZIP export in an offline development VM. The
+internal compiled-authoring path can now ask a model for complete replacements
+or unique exact-text edits of inspected source files, each bound to its
+original Git SHA-256. The host derives full replacement bytes for an edit. A root-owned
+stage checks and seals replacement bytes separately from the immutable Git
+source; the network-denied build applies them in scratch space. Patch identity
+must match in the compiled candidate and an independent rebuild. Package
+manifests and lockfiles cannot be patched in this profile. The root-owned patch
+stage, service connection, automatic runtime-failure repair and full behavior
+review remain unverified. A model-suggested CDN exception is not equivalent to
+localizing and verifying those assets.
+CanvasCode also requires a `srcDoc` preview frame and local Monaco language
+workers. The original browser-application profile declares only single-thread
+WASM; its CSP and target guard deny frames and workers. A successful ordinary
+Chromium smoke therefore cannot establish host-runtime compatibility.
+
+The new browser-application v2 source profile now supports a declared, bounded
+direct `srcdoc` frame. The compiled authorer can request that feature, and
+independent source verification reconstructs the exact profile from the pinned
+build. A local Chromium probe confirmed that the v2 CSP runs an inline preview
+script, reports the expected direct child frame, and keeps the top-only trusted
+bootstrap out of the child. The existing v1 CSP and frame guard remain closed.
+This is development-browser evidence, not a provisioned StillMade worker run.
+CanvasCode also needs local Monaco language workers. Browser application v3
+now declares exact bundled dedicated worker scripts, and the trusted target
+policy admits them only when paused under the original page and context. A
+local Chrome probe ran a worker through that policy and the hashed asset
+server, while CSP denied a second loopback origin. The original v1 and v2
+profiles still deny workers. This is not a provisioned StillMade worker test,
+CanvasCode's own worker behavior has not passed runtime review, and its full
+application import remains uninstalled.
+
+## 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.
+
+The separate Natron ARM64 development build (repository evidence `artifacts/repository-acceptance/natron-native-gui-dev-build-2026-09-29.json`)
+shows that a Qt5/PySide2 native GUI can compile and open in a local VM after
+architecture and Python-home adaptation. Its source tree is not yet the
+complete sealed Git closure, and its OCIO configs and OpenFX plugins are
+missing. This is runtime feasibility evidence, not approval to install a
+GitHub-authored Block or a replacement for the full application.
+The later exact-source-to-GUI check (repository evidence `artifacts/repository-acceptance/natron-exact-tree-to-gui-2026-09-29.json`)
+replaced that archive input with the verified allowed Git closure and compiled
+a separate copy carrying only the recorded ARM64 patch. The GUI opened; the
+same binary also saved and reopened a native `.ntp` project. The missing
+plugins, color config and host-enforced Block contracts remain.
+
+## 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.
+
+For browser applications with several export actions, declare which output
+ports each action produces. An SVG export can map to `svg` and a PNG export to
+`png`; mark each shared-manifest port `required:false` when another action
+does not return it. The host checks the exact action-to-port mapping before
+publishing output or storing media. A generated adapter's declaration alone
+does not prove either export works.
+
+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/docs/build/hosted-images.md

@@ -0,0 +1,214 @@
+# Hosted image generation
+
+Use `runtime: "capability"` with `operation: "image.generate"` for one visual
+prompt (and optional reference images) to one generated PNG. Every image model
+the app's own Canvas and Image Panels use is available: Nano Banana 2, 2 Lite and
+Pro, GPT Image 2 and 1.5, Kling Image V3 and Seedream 4.5, with their aspect
+ratios, resolutions and qualities (see
+[generation models](../reference/generation-models.md)). Users pay with their
+StillMade credits at StillMade's own price, or with their OpenAI key for the
+direct GPT Image 2 option. The host shows model, settings and the exact price
+before any provider call. Imported packages never receive API keys or choose an
+endpoint or a price.
+
+### Complete package
+
+The downloaded SDK includes `examples/generate-image.stillmade.json` and
+`packages/block-sdk/image-generation-example.js` (export `imageGenerate`).
+
+```json
+{
+  "manifest": {
+    "schemaVersion": 1,
+    "sdkVersion": "0.1.0",
+    "id": "example.generate-image",
+    "version": "1.0.0",
+    "name": "Generate an image",
+    "description": "Generate a square PNG from a short visual prompt using an approved host request.",
+    "kind": "task",
+    "runtime": "capability",
+    "entry": "src/capability.json",
+    "license": "MIT",
+    "inputs": {
+      "prompt": {
+        "type": "text",
+        "primary": true
+      }
+    },
+    "outputs": {
+      "image": {
+        "type": "image",
+        "primary": true
+      }
+    },
+    "permissions": {
+      "project": [],
+      "capabilities": [
+        "image.generate"
+      ],
+      "network": [],
+      "filesystem": [],
+      "secrets": []
+    },
+    "ui": [
+      {
+        "control": "text",
+        "port": "prompt"
+      }
+    ]
+  },
+  "capability": {
+    "schemaVersion": 1,
+    "operation": "image.generate",
+    "prompt": {
+      "$input": "prompt"
+    },
+    "output": "image"
+  },
+  "tests": [
+    {
+      "name": "A simple forest illustration",
+      "input": {
+        "prompt": "A simple illustration of a quiet forest with clear dark outlines and soft green colors."
+      },
+      "expectations": {
+        "image": {
+          "kind": "image",
+          "format": "png",
+          "width": 1024,
+          "height": 1024,
+          "minBytes": 67,
+          "maxBytes": 12000000
+        }
+      }
+    }
+  ]
+}
+```
+
+### Inputs and controls
+
+Declare exactly one primary input of type `text`, `script`, or `brief`, optionally
+one `image` or `image[]` input of reference images, and one primary output of
+type `image`. Script and brief values contain `schemaVersion:1`
+and `text`; text ports receive a string. The resolved prompt must contain
+1–32,000 characters and cannot be blank. Existing declared project context read
+scopes can supply that input through the normal host resolver.
+
+The descriptor contains `schemaVersion`, `operation`, `prompt` and `output`, and
+optionally:
+
+- `settings`: the Block's default `{model, aspectRatio, resolution, quality}`.
+  Each value must be one the model accepts; axes a model has no knob for are
+  `"default"`.
+- `references`: `{"$input":"refs"}`, binding the declared `image`/`image[]`
+  input. Up to 8 saved images; the model must edit from references (the Nano
+  Banana family and GPT Image 2).
+- `negativePrompt` (up to 2,000 characters) and `seed` (0–2147483647).
+
+Declare exactly `capabilities:["image.generate"]`; network, filesystem and
+secrets permissions stay empty. Payment, credentials and price are never
+descriptor fields.
+
+```json
+"capability": {
+  "schemaVersion": 1, "operation": "image.generate",
+  "prompt": {"$input": "prompt"}, "references": {"$input": "refs"},
+  "settings": {"model": "nano-banana-pro", "aspectRatio": "16:9", "resolution": "2K"},
+  "negativePrompt": "text, watermark", "output": "image"
+}
+```
+
+In StillMade, the run dialog preselects the Block's default model and settings;
+the user can change them before running and sees the exact credit price. Every
+review fixture and the separate sample is included in the displayed total. The
+direct OpenAI option (fixed 1024 × 1024, your own key) takes text prompts only.
+Reference images must be saved in the user's own library; anything else is
+refused before any credit is spent.
+
+### Output and tests
+
+The output is an exact reference to a retained PNG:
+
+```js
+{
+  kind: "image", assetId, versionId, url,
+  mimeType: "image/png", width, height, bytes
+}
+```
+
+The host bounds the provider response, decodes the actual PNG, JPEG or WebP,
+stores one sRGB PNG under an immutable hash and measures its `width`, `height`
+(up to 8192 a side and 40 megapixels) and `bytes` (up to 64 MiB); package code
+cannot assert those measurements on its own. `assetId` identifies the execution's
+image, `versionId` is its saved SHA-256, and `url` is a StillMade media URL.
+
+Each fixture requires `expectations` for the declared output: `kind:"image"`,
+`format:"png"`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`, `minBytes` and
+`maxBytes` (ordered integers within the limits). Older fixtures that name the
+fixed `width:1024, height:1024` square remain valid.
+These checks verify a usable image contract. They cannot prove the picture
+matches the meaning of the prompt; inspect the actual image before acceptance.
+
+### Review, preview and project use
+
+Upload the package to run schema, dependency, permissions and static checks.
+Offline CLI validation and packaging can pass those checks but report that live
+review is required; offline test/preview cannot call the provider or produce a
+placeholder. In StillMade, review the cost, confirm generation, inspect every
+fixture and sample, finish the review, then **Confirm Import**.
+
+A project run has its own current prompt and quote. **Use this image** accepts
+its reviewed output. Compatible image inputs can consume that result through
+the host's existing image resolver; sandboxed pixel processing receives actual
+decoded pixels rather than a guessed URL. Accepted current project results also
+appear in the Editor's visual media inventory. Earlier placed images keep their
+original source when the generating Block runs again.
+
+A custom interface can use the existing `StillMade.run` flow. Host image
+previews remain outside the isolated iframe, and guest code cannot supply
+execution receipts or access the provider. No `generateImage`, provider-key or
+arbitrary fetch API is added to the guest interface.
+
+### Host integration and recovery
+
+`prepareCapabilityInvocation` returns `{operation:"image.generate",prompt}` plus
+`references`, `negativePrompt` and `seed` when declared. A credit selection is
+`{payment:"credits",provider:"stillmade",model,aspectRatio,resolution,quality}`;
+the direct key option stays `{provider:"openai",model:"gpt-image-2",size:"1024x1024",quality,payment}`.
+`capabilityOutputs(package, imageReference)` maps the generated reference to the
+named output. `validateGeneratedImageReference` and
+`defaultCapabilityExpectations` enforce the declared shape and bounds.
+
+A trusted executor may return `{outputs, metadata, mediaReceipts}`. The receipt
+map is keyed by the output port; each receipt contains its `schemaVersion` (3 for catalog images), all
+canonical image fields, plus `ownerId`, `runId`, `index`, `storageKey` and
+`sha256`. SDK validation checks shape and equality to the output. The
+authenticated host additionally binds owner/run/index and reads the saved bytes
+again during review acceptance and completed-result recovery. The receipt is
+host evidence, not a credential or a guest-authored permission grant.
+
+Execution uses one exact provider request per invocation, without automatic
+provider, payment or model fallback. An uncertain submission is not retried
+automatically. Cancelling stops further work and acceptance; it cannot promise
+that a remote provider stopped or that already-generated output was free.
+Received output that fails storage or contract checks remains a charged request;
+a definite provider rejection follows the existing refund path.
+
+Automated checks use local image fixtures and mocked providers. They do not
+claim a successful live provider image test. Each account must complete its
+actual hosted review before importing a generated-image Block.
+
+### Connected production runs with hosted Blocks
+
+Inside a project, **Run connected steps** passes the actual previous result to
+each next Block. Hosted text, speech and image Blocks use StillMade's existing
+model and payment dialog for each call. Confirm its cost before execution; a
+Block cannot choose approval or payment. Waiting for this choice does not consume
+the local sandbox timeout. Cancelling stops downstream work and preserves already
+completed results. Use **Use completed results** to adopt them into the project.
+
+Saved hosted results are rechecked against the signed-in account's server run,
+including the exact project, source, input, selection, quote and retained media.
+This verification does not generate again. Standalone import reviews are not
+production outputs. Unattended hosted automation is not enabled by this control.

package/docs/build/hosted-music.md

@@ -0,0 +1,39 @@
+# Hosted music and sound effects
+
+Use `runtime: "capability"` with `operation: "audio.music"` or
+`operation: "audio.sfx"` to create music or a sound effect with the app's own
+generators: ACE-Step music and StillMade sound effects, the same ones the
+Editor uses. The person running the Block pays with StillMade credits at the
+app's prices (music by the minute, one flat price per sound effect). Block code
+never sees keys, endpoints or payment.
+
+The manifest declares one `text`, `script` or `brief` input, one `audio`
+output, and `permissions.capabilities: ["audio.music"]` (or `["audio.sfx"]`):
+
+```json
+{"schemaVersion":1,"operation":"audio.music","prompt":{"$input":"brief"},"output":"music","settings":{"durationSec":30}}
+```
+
+`settings.durationSec` is optional and only suggests a length. Music runs 5 to
+240 whole seconds; sound effects run 0.5 to 22 seconds in tenths. The person
+running the Block can change the length in the dialog, and the quote shows the
+price for that length before anything is generated.
+
+The output is a measured MP3 or WAV reference:
+
+```json
+{"kind":"audio","assetId":"audio:run:0","versionId":"<sha256>","url":"/api/media/owner/capaud3-....mp3","mimeType":"audio/mpeg","duration":30.02,"bytes":481254,"sampleRate":44100,"channels":2}
+```
+
+Fixture expectations use `format` `any`, `mp3` or `wav` with duration and byte
+bounds (up to 1,800 seconds and 128 MiB):
+
+```json
+{"music":{"kind":"audio","format":"any","minDuration":1,"maxDuration":241,"minBytes":45,"maxBytes":134217728}}
+```
+
+The offline SDK includes `packages/block-sdk/audio-generation-example.js`,
+exporting `audioMusic` and `audioSfx`. Review, listening and acceptance follow
+the same flow as [hosted speech](hosted-speech.md#review-listen-and-accept): **Review cost**
+never generates, each fixture and the sample is quoted and charged once, and a
+provider refusal before generation is refunded.