stillmade-sdk 0.1.41 → 0.1.43

package/docs/build/hosted-speech.md

@@ -0,0 +1,157 @@
+# Hosted speech generation
+
+Use `runtime: "capability"` and `operation: "audio.speech"` to turn up to 3,800
+characters of supplied text into one speech recording. This operation speaks
+the supplied text; it does not draft a script or run another generation first.
+The package contains no provider, payment method, endpoint, credentials, or
+execution receipts. It may suggest a voice and speed; StillMade selects and
+confirms the final choice outside the package and its optional sandboxed
+interface.
+
+### Package and declaration
+
+Download [the complete Narrate a script package](https://stillmade.shop/block-sdk/examples/narrate-script.stillmade.json).
+The offline SDK also includes `packages/block-sdk/speech-example.js`, exporting
+`audioSpeech`. Copy the example, choose your own namespace, and edit its fixtures:
+
+```sh
+node packages/block-cli/cli.js validate examples/narrate-script.stillmade.json
+node packages/block-cli/cli.js pack examples/narrate-script.stillmade.json narrate-script.stillmade.json
+```
+
+The package has `manifest`, `capability`, `tests`, and optional `view`. Its
+manifest declares exactly one primary input of type `text` or `script`, exactly
+one primary output of type `audio`, and:
+
+```json
+{"project":[],"capabilities":["audio.speech"],"network":[],"filesystem":[],"secrets":[]}
+```
+
+The capability object has these four fields; the input and output names
+must match its declared ports:
+
+```json
+{"schemaVersion":1,"operation":"audio.speech","text":{"$input":"script"},"output":"audio"}
+```
+
+It may add `settings` with a suggested StillMade catalog voice and speed. The
+dialog preselects them when that voice is available, and the person running the
+Block can still change both:
+
+```json
+{"schemaVersion":1,"operation":"audio.speech","text":{"$input":"script"},"output":"audio","settings":{"voice":"asteria","speed":1.1}}
+```
+
+`voice` is a catalog voice id (lowercase letters, digits, `-` or `_`) and
+`speed` is 0.25 to 4. See [Generation models](../reference/generation-models.md)
+for the voice list.
+
+A text input is a string. A script input contains
+`{"schemaVersion":1,"text":"Words to speak."}`. Only its `text` is forwarded;
+extra structured script fields cannot select a voice or add provider settings.
+Text must be nonblank and at most 3,800 characters. Oversized text is rejected,
+not silently truncated. A default is permitted; scoped script context still
+requires `context.script.read`. Declare generic primary ports unless a matching
+semantic role is needed by a particular downstream contract.
+
+### Audio output and fixture expectations
+
+StillMade catalog voices return the provider's measured MP3 or WAV, stored
+byte for byte (schema 3 receipts, any sample rate, mono or stereo). The OpenAI
+TTS-1 path normalizes and stores 16-bit PCM WAV at 24,000 Hz, mono. Either way
+the output is a reference with exactly these fields, using host-created
+identities and a saved HTTPS or host media URL:
+
+```json
+{
+  "kind":"audio","assetId":"speech-run-one","versionId":"v1",
+  "url":"/api/media/owner/speech-one.wav","mimeType":"audio/wav",
+  "duration":1,"bytes":48044,"sampleRate":24000,"channels":1
+}
+```
+
+This reference is illustrative; it is not a generated file or execution receipt.
+`duration` is measured from the actual PCM sample count; `bytes` includes the
+canonical WAV header. Audio must be nonempty, at most 64 MiB (67,108,864 bytes),
+and at most 1,400 seconds. The SDK validates finite bounds and the exact shape;
+metadata alone cannot establish that bytes exist, are WAV, or belong to a user.
+The host performs byte checks and stores a separate bound media receipt.
+
+Include 1–3 fixtures using expectations, never an exact output or a fabricated
+audio reference. Each expectation requires exactly `kind`, `format`,
+`minDuration`, `maxDuration`, `minBytes`, and `maxBytes`:
+
+```json
+{
+  "name":"Read a short welcome",
+  "input":{"script":{"schemaVersion":1,"text":"Welcome to the quiet forest."}},
+  "expectations":{"audio":{"kind":"audio","format":"wav","minDuration":0.1,"maxDuration":30,"minBytes":46,"maxBytes":1500000}}
+}
+```
+
+Duration bounds are finite seconds with `0 <= minDuration <= maxDuration <= 1400`
+and a positive maximum. Byte bounds are integers with
+`46 <= minBytes <= maxBytes <= 67108864`. Bounds are inclusive. These checks do
+not transcribe the output, assess pronunciation, or verify a speaker's identity.
+
+### Review, listen, and accept
+
+Importing source and requesting **Review cost** do not generate audio. The host
+dialog offers **StillMade voices**, the same catalog the app's Voiceover uses
+(Deepgram, ElevenLabs, OpenAI and Kokoro voices configured on the server), paid
+with StillMade credits at the Voiceover price for the text's length. It also
+offers OpenAI TTS-1 with credits or your own key, and a speed from 0.25× to 4×.
+Keys remain in the host's encrypted account vault. BYOK uses the account's
+OpenAI key; missing keys never switch to credits.
+Changing text, source, model, voice, speed, or price requires a new quote.
+
+Review the displayed input, voice, speed, cost for every fixture and the separate
+sample, and the total before choosing **Run tests and sample**. Each approved
+invocation produces its own recording and receipt. Listen to the AI-generated
+audio before choosing **Finish review**, then **Confirm Import** to install the
+Block. A project run has its own **Run in project** confirmation and **Use this
+audio** acceptance. The shared ledger binds source, inputs, account, project,
+voice, speed, payment, quote, and retained outputs. Uncertain submissions are
+not automatically repeated; recovering status does not itself generate audio.
+
+The result is a typed audio output and a playable Block result. After accepting
+a confirmed project speech run, open **Media** in the Editor and find **Audio
+from Blocks** to listen and explicitly **Add at playhead**. See [Add speech to the Editor](audio-to-editor.md).
+Generic audio outputs can also connect to compatible SDK audio inputs.
+
+Adding audio to the Editor does not create or select a native Voiceover take,
+replace its master recording or narration, or create word timings or a
+transcript. Voiceover's primary input remains `script`; the Editor action does
+not introduce an audio-to-Voiceover connection. A sandboxed view may request
+`StillMade.run`, which opens the host approval flow; there is no guest
+`previewAudio`, timeline mutation, or provider API.
+
+### Validation status and host integration
+
+No live provider speech test has been completed for this implementation.
+Schema, fixture-contract, and host-boundary tests use synthetic inputs and
+explicit mocks. They do not claim successful provider speech generation. Every
+installation still requires the actual host fixtures, sample, playback review,
+and import confirmation for the selected account and settings.
+
+Offline `validate` and `pack` work without a key. `pack` reports `tests: 0`,
+`reviewRequired: true`, and `liveVerified: false`. Offline `test` and `preview`
+return `RUNTIME_UNAVAILABLE`; they do not fetch speech or return placeholders.
+
+`prepareCapabilityInvocation(pkg, input)` returns exactly
+`{operation:"audio.speech",text}`. The trusted host executes the separately
+approved request and calls `capabilityOutputs(pkg, canonicalAudioReference)`.
+`capabilityOperation(manifest)` distinguishes text, speech and image contracts;
+`defaultCapabilityExpectations(manifest)` supplies their bounded default checks.
+The existing `validateCapabilityExpectations`, `testCapabilityOutputs`, and
+`validateCapabilityResult` dispatch through the declared operation.
+
+A trusted speech executor may return `{outputs, metadata, mediaReceipts}`.
+`mediaReceipts` is keyed by the exact audio output name. Its receipt has exactly
+`schemaVersion:1`, `kind:"audio"`, `ownerId`, `runId`, `index`, `storageKey`,
+`sha256`, and the canonical reference's `assetId`, `versionId`, `url`,
+`mimeType`, `duration`, `bytes`, `sampleRate`, and `channels`. The SDK validates
+shape, index 0–3, hash syntax, and equality to the output, and preserves a copy.
+The authenticated host client must additionally verify account/run identity;
+package code and custom interfaces cannot submit receipts as execution evidence.
+Optional metadata remains bounded to 8 KiB and is not proof of generation.

package/docs/build/hosted-text.md

@@ -0,0 +1,246 @@
+# Hosted text generation
+
+Use `runtime: "capability"` to implement a portable Block that asks StillMade to
+generate text. The package declares the prompt, instructions, output contract,
+and fixtures. StillMade owns account authentication, model choice, provider
+keys, cost confirmation, and execution. This is a separate declarative runtime;
+`fetch`, `ctx.capabilities`, and arbitrary host calls remain unavailable inside
+JavaScript Blocks.
+
+### Create and package
+
+```sh
+node packages/block-cli/cli.js create ./script-draft capability
+node packages/block-cli/cli.js validate ./script-draft
+node packages/block-cli/cli.js pack ./script-draft script-draft.stillmade.json
+```
+
+The folder contains `stillmade.block.json`, `src/capability.json`, and
+`tests/fixtures.json`. A packed JSON contains `{manifest, capability, tests}`
+and may include a sandboxed `view`. No provider key, endpoint, model, billing
+selection, or receipt belongs in the package. Those fields are rejected.
+
+Download [the complete script-draft example](https://stillmade.shop/block-sdk/examples/script-draft.stillmade.json).
+Its manifest uses `entry: "src/capability.json"`, one primary `prompt` input of
+type `text`, one primary `script` output of type `script`, and:
+
+```json
+{"project":[],"capabilities":["text.generate"],"network":[],"filesystem":[],"secrets":[]}
+```
+
+Its capability declaration is:
+
+```json
+{
+  "schemaVersion": 1,
+  "operation": "text.generate",
+  "prompt": {"$input": "prompt"},
+  "system": "Write a concise narration script. Return only the script text.",
+  "maxTokens": 1200,
+  "output": "script"
+}
+```
+
+Declare exactly one prompt input (`text`, `script`, or `brief`) and exactly one
+output (`text`, `script`, `json`, or a structured `object`).
+
+An optional second `text` input can carry the user's own instructions, such as
+decision rules or what to write: name it in `"prompt": {"$input": "data",
+"$instructions": "rules"}`. StillMade sends `Instructions:` then `Input:`.
+
+For a structured answer, declare one `object` output with a flat `schema` of up
+to 20 `string`, `number`, `integer` or `boolean` fields, for example
+`{"yes":"boolean","score":"integer","label":"string","reason":"string"}`.
+StillMade asks the model for exactly one JSON object with those fields, accepts
+the common `"85"` and `"true"` string forms, drops undeclared fields and fails the
+run when a field is missing. Fixtures for an object output use
+`{"kind":"object"}`; the declared fields are always checked. Later Steps can use
+the fields directly, for example with "Continue only if". Structured prompt inputs contain
+`{"schemaVersion":1,"text":"..."}`. A generated script returns that same
+structured shape; a text output returns a string. Typed ports, primary markers,
+semantic roles, and scoped project context retain their SDK meaning. A context
+prompt needs its declared read permission and fresh authorized project snapshot.
+Do not infer scene or character structure from an unstructured generated script.
+
+Up to three other read-only inputs (for example the saved project script) can
+also reach the model: list them in the descriptor as `"context": ["script"]`.
+StillMade appends their current values after the prompt as delimited data the
+model is told never to treat as instructions, and the review covers that exact
+text. An input that is not listed (one a custom view only displays) is never
+sent.
+
+Generated `text` and `script` outputs state only what the run was given. Before
+the result reaches a Step, the host removes each sentence that names a phone
+number, web address or email, an inspection, certification, warranty or
+vehicle-history claim, a price or a mileage figure that the run's input does not
+contain (contact details written in the Block's own instructions count as given;
+claim words there do not). A removed call to action becomes "Contact us today to
+learn more." Line breaks are kept, and `object` and `json` outputs are not
+changed. To keep such a sentence, supply the fact in an input.
+
+#### Conversations
+
+To continue a conversation, declare one optional `json` input for the earlier
+turns and bind it as `history`:
+
+```json
+{"schemaVersion":1,"operation":"text.generate","prompt":{"$input":"message"},
+ "history":{"$input":"history"},"system":"You are a friendly script coach.",
+ "maxTokens":800,"output":"reply"}
+```
+
+The history value is up to 20 turns of `{"role":"user"|"assistant","content":"..."}`
+(each at most 8,000 characters, 24,000 in total); StillMade sends them between
+the system instructions and the prompt, and the review covers the exact turns.
+Other fields and other roles are rejected. A missing history starts a fresh
+conversation. A custom view or a JavaScript Step can keep the turns and pass
+them back on the next run.
+
+#### Structured replies (JSON schema)
+
+For data instead of prose, declare a `json` output and add `schema`, the JSON
+Schema the reply must match:
+
+```json
+{"schemaVersion":1,"operation":"text.generate","prompt":{"$input":"topic"},
+ "system":"You plan short podcast intros.","maxTokens":800,"output":"plan",
+ "schema":{"type":"object","additionalProperties":false,"required":["title","script"],
+  "properties":{"title":{"type":"string","maxLength":80},
+   "script":{"type":"string","maxLength":1200},
+   "beats":{"type":"array","items":{"type":"string"},"minItems":3,"maxItems":6}}}}
+```
+
+StillMade tells the model to reply with JSON matching the schema, parses the
+reply (one surrounding code fence is tolerated) and checks it against the
+schema before any Step receives it. A reply that does not match fails the run
+with the first mismatch, for example `$.beats: needs at least 3 items`. The
+output port then carries the parsed value, so a JavaScript Block downstream
+reads `input.plan.title` directly.
+
+The supported subset is `type` (one or a list of `object`, `array`, `string`,
+`number`, `integer`, `boolean`, `null`), `description`, `title`, `enum`,
+`properties`, `required`, `additionalProperties`, `items`, `minItems`,
+`maxItems`, `minLength`, `maxLength`, `pattern`, `format` (`date`,
+`date-time`, `email`, `uri`), `minimum` and `maximum`; up to 8 levels deep and
+8,192 characters. The system instructions plus the schema instruction must fit
+in 8,000 characters. Fixture expectations for a json output are
+`{"kind":"json"}` with optional `includes` literal phrases.
+
+Limits: package 256 KiB; prompt 32,000 characters; system instructions 8,000
+characters; generated text 32,768 characters; `maxTokens` integer 1–4096.
+The operation is one text generation call. Image, audio, video, tool calling,
+streaming, multi-call agent loops, and arbitrary API requests are not supported
+by this declaration.
+
+### Fixtures and real review
+
+Generated text varies, so fixtures use bounded expectations instead of an exact
+`expected` string:
+
+```json
+[{
+  "name": "A short opening narration",
+  "input": {"prompt":"Write two narration sentences about a quiet forest at sunrise."},
+  "expectations": {"script":{"kind":"script","minLength":20,"maxLength":6000}}
+}]
+```
+
+Include 1–3 fixtures. Every output has its matching `kind`, positive `minLength`,
+and `maxLength` no larger than the output limit. Optional `includes` contains at
+most eight required literal strings of at most 256 characters each; regular
+expressions are not supported. Expectations check the declared interface and
+bounded behavior, not factual correctness. Review the actual generated result.
+
+Offline `validate` and `pack` check source only. `pack` reports `tests: 0`,
+`reviewRequired: true`, and `liveVerified: false`. Offline `test` and `preview`
+fail with `RUNTIME_UNAVAILABLE`; they do not invent a generation result.
+
+Import the JSON or ZIP into StillMade. Test and preview loads available models
+and payment methods. **Review cost** obtains a non-billable quote. Only the
+separate **Run tests and sample** action submits one call per fixture and one
+additional sample call. The host displays the complete call count and credit
+cost first. BYOK uses your encrypted account OpenRouter key; provider usage is
+billed by that provider and does not consume StillMade generation credits.
+A missing BYOK key never silently switches to credits.
+
+The server binds the report to your account, exact source digest, inputs,
+resolved model/payment selection, quote, and execution policy. Every fixture,
+the separate sample, typed outputs, and expectations must pass. Inspect the
+sample and source rights, then **Confirm Import** to install. A client-supplied
+`passed` flag or an LLM-written report cannot authorize import or release.
+AI authoring generates and statically validates a draft; it stops for this
+hosted review and does not silently run the drafted capability.
+
+### Run in a project and recover
+
+Add the reviewed Block to a Project Type to make a Step. Its controls and
+optional custom interface use the same host execution dialog. Guest UI cannot
+choose a model, reveal keys, or confirm a quote. Existing matching review
+results can be reused for project execution, but the current project input
+always gets its own quote and explicit run confirmation. An expired import
+review can be reused for a project only after the server revalidates its source,
+selection, policy, and current project edit access.
+
+Each confirmed request has an account-scoped UUID and durable execution record.
+The host advances one invocation at a time, retains results, and makes duplicate
+requests idempotent. An unknown provider outcome is not automatically submitted
+again. If the creation response is lost, the host finds the original request by
+its UUID without generating. Continuing an unfinished recovered review requires
+another explicit Continue generation action; it advances the already confirmed
+plan, not a new request. Cancellation cannot guarantee that a provider stops already submitted
+work; completed results are retained, while a cancelled or stale project run
+cannot be automatically accepted into the project. Failed StillMade-credit
+charges use the existing idempotent refund ledger. BYOK provider charges follow
+the provider account and cannot be refunded by StillMade.
+
+A Project Type can be imported after every embedded hosted package receives its
+own current account review; see [review hosted Project Types](../project-types/hosted-review.md).
+This is package admission, not proof that the connected flow ran. Connected
+automatic runs and unattended future-media jobs stop at the hosted capability
+boundary; they do not grant advance permission for paid calls.
+
+### Publish a verified listing sample
+
+After releasing the Block publicly, choose **Publish verified sample** in its
+listing editor. Confirm the public display of that sample's input and output.
+StillMade reuses the exact retained sample from the release review; it does not
+call the provider or charge again. The source, account ownership, current runtime
+policy, quarantine state, complete fixture evidence, and sample contract are
+checked again. An expired import receipt or a removed API key does not invalidate
+historical output. Project-run receipts cannot publish a private project sample
+through this action. The stored preview records the original model and generation
+time, so it is not represented as a new execution.
+
+### Host integration API
+
+```js
+import {runPackageAsync, prepareCapabilityInvocation, capabilityOutputs}
+  from './packages/block-sdk/index.js';
+
+const result = await runPackageAsync(pkg, input, {
+  capability: async (reviewedPackage, values, {signal}) => {
+    const request = prepareCapabilityInvocation(reviewedPackage, values);
+    // Trusted host: authenticate, review cost and approval, execute once,
+    // retain the result, then return typed outputs. Never implement this in
+    // package code or treat this SDK callback as proof of import review.
+    const text = await approvedHostTextRun(request, {signal});
+    return {outputs: capabilityOutputs(reviewedPackage, text)};
+  }
+});
+```
+
+`approvedHostTextRun` is a host integration placeholder, not an SDK function.
+The SDK validates declaration and output types; StillMade's server supplies the
+account receipt and billing guarantees. Optional returned metadata is bounded
+to 8 KiB and is not an authorization receipt. Without a trusted executor,
+`runPackageAsync` fails closed. `validateCapability`,
+`prepareCapabilityInvocation`, `capabilityOutputs`,
+`validateCapabilityExpectations`, and `testCapabilityOutputs` are the portable
+validation helpers. They never access a provider.
+
+StillMade's authenticated `/api/block-capabilities` routes provide options,
+quotes, review creation/lookup, run creation/status/poll/cancel, and read-only
+`GET /requests/:requestId` recovery. Status GETs never execute calls or reconcile
+refunds; POST polling/cancellation handles those mutations. They use StillMade's
+credit ledger and encrypted BYOK vault or platform model key; Block authors
+configure nothing.

package/docs/build/image-description.md

@@ -0,0 +1,49 @@
+# Describe an image
+
+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.
+
+**StillMade credits do not pay for `image.describe`** (since September 13, 2026). A Block that calls it runs only for people who added their own OpenRouter key in Settings → API keys, and stops for everyone else. For a Block anyone can run on StillMade credits, use `media.analyze` instead (`stillmade-block create my-block analyze-media`): it takes one image or one to four images, answers one question about each, and is priced per image. The built-in Describe media 2.1.0 and Photo notes 1.1.0 moved to it; their earlier releases stay for projects pinned to them.
+
+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.