stillmade-sdk 0.1.41 → 0.1.43

package/docs/build/block-builder-contract.md

@@ -0,0 +1,150 @@
+# Block builder contract
+
+Contract `stillmade.block-builder@1.17.0`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+
+## Source of truth
+
+Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.
+
+## Reuse first
+
+Before building, check what exists (`find_existing_blocks` over MCP, or the Marketplace and your library) by the goal's inputs, results and operations. Only a `likely` or `verified-contract` match (a Block or a chain of two) does the job: use it. `partial` is a close Block to look at: remix it (license, notices and credit stay attached) or build only the missing step. Never republish another creator's source without remix lineage: public copies are refused. Build new when nothing does the job or the person wants their own, and name similar Blocks you considered.
+
+## Three sizes of Block
+
+Blocks come in three sizes and the manifest decides which (packages/block-sdk/block-tier.js): an app is a workspace a person works in (Editor, Canvas, Shots), placed in a Type and never wired automatically; a job is one deliverable a person would name (the narration, the captioned clip), built from the hosted operations it needs (`permissions.capabilities`) and reviewed in one place, the unit Chat picks for a Step; an ingredient is one hosted operation with nothing of its own (a declarative capability Block), what a job is made of. When two ingredients would stand in a row to make one deliverable (writing the words, then voicing them), build or pick the job that does both and keep the review point inside it. A job declares a second output when another Block consumes the intermediate (the script beside the voice); split into two jobs only when the intermediate has a life of its own or the halves have different owners or payment.
+
+## Choose the runtime
+
+Pick the runtime from the job. No hosted AI: a recipe or isolated `javascript`, both able to run unattended. One text, script or brief prompt returning text, script or JSON: a `capability` Block. Hosted operations on other values (a transcript, media, structured data), several hosted operations in a row, or a result shaped in code: one `module` Block, `module/main.js` calling `stillmade.hosted.run(operation, request)` for each operation in `permissions.capabilities` (MODULES.md), never one Block per operation; it runs in the person's browser while StillMade is open. Build a new Block in a folder with `stillmade-block create`, `test`, `ready` and `pack`, and import the file `pack` writes (a module Block writes `<id>-<version>.stillmade-module.json`) through Create, then Import Block. A `.stillmade-block` archive is only for adapting a GitHub repository.
+
+## One job per Step
+
+A Step is one job: the work between two moments where a person or the outside world must see the result. A guided job, one the person fills in and then gets a result from, is one Step with one Block whose own screen holds everything: the inputs and settings, then a cheap check before the expensive run (the script and a voice sample before the video), then the result. On a wide screen the inputs sit on the left and the result's place on the right; on a phone they stack, the result's place under the button. A cheap check or a review the person does on that screen never starts a new Step. Start a new Step only at one of these points; everything else is a part of the neighboring Step.
+
+1. **A person works with the result**: in a workspace they spend a while in (the Editor, a storyboard, a Canvas, a CAD or drawing tool), or someone else approves or takes it over (a hand-off). Turning what a workspace made into something else is the next Step: a CAD tool is its own Step, and the Block that takes pictures of its model and makes a video is the next one. So Bible, Canvas and Editor are separate Steps after Chat.
+2. **Finding new things turns into handling each one**: the trigger (a schedule or an app event), the app read, its filter and "only new" are the first job; what is done with each item is the next job. A trigger is a setting of the first job, never a Step of its own.
+3. **The result leaves StillMade**: it is sent, posted, published, paid or written into another app. Consecutive writes to the same app, with the glue that shapes data for them, are one job.
+4. **Setup or a wait**: a one-time setup that is not part of each job (a brand kit, capturing a voice or a likeness), or a render that takes minutes and is delivered later.
+
+In a production the Steps are the workspaces a person opens: work feeding the next workspace is its part, else it joins the one before. A Block with its own interface (a workspace, editor or picker) is always its own Step; two such Steps are never one. A Type whose own Block renders the finished video (`timeline.render`) needs no Editor Step; the Editor (1.0, captions and export built in) is a Step only when the person edits the cut by hand, and Export video is never a Step beside it.
+
+A part that only runs in the desktop app cannot share a Step with cloud parts. Before adding a Step, name which of these reasons makes it separate; if none applies, make it a part of a neighbor. A Step nobody would ever open must not exist on its own. Prefer an app task's own filter (a Gmail query such as `has:attachment filename:png`) to an AI check, and use AI decide only for judgement.
+
+Build one Block for a job one Block can do: a module Block calls every hosted operation the job needs (it transcribes a sermon, then finds the verses said in it), a JavaScript Block does several local transforms, a workspace owns its whole document. A Block being built never takes an ingredient's result only so the ingredient can be its own part or Step (Transcribe in front of a verse finder): it calls that operation itself. Parts in one Step (`groups` in the Project Type) are for jobs made of Blocks that already exist and app tasks, each keeping its own permission, approval and credit rules. Never invent a combined runtime.
+
+Examples: "a listing video from my photos and the home's facts" is one Step: one Block whose page takes the photos and facts, shows the script and a voice sample to check, then makes the video. "every new email with an image becomes a generated image" is two Steps, "Gmail · New emails with images" (When, fetch with an image filter, only new) and "Image from email" (AI write, Generate image); listing When, Fetch, Only new, AI decide, Continue only if, AI write and Generate image as seven Steps splits one job into its parts. "A new Meta lead goes to HubSpot" is three Steps: "Meta Ads · New leads", "Qualify lead" and "HubSpot · Add contact".
+
+## Define the capability first
+
+Translate the request into an explicit capability contract before implementation: what the Block does; each input with its type, meaning and whether it is required (prefer optional settings with safe defaults over extra required questions); each output with its type and meaning; persistent state; project context it reads; permissions; UI; long-running behavior; expected failures; cancellation; determinism; and whether it needs hosted models, media, desktop tools or shared editing. Keep the public interface as small and general as possible (few required inputs, one primary output) and keep implementation details out of it; small means a small interface, never a fragment of a job. A Block that generates images, video or speech declares only its prompt and output: every Step that runs it gets the host’s generation settings (model, quality, length and resolution, voice, speed, how many), saved with the Step, changed on its page or by Chat, and shown with their cost before each run.
+
+## Blocks compose
+
+A Block is one job: not a mini-app of many jobs and not a fragment of one. Its outputs become other Blocks' inputs and its inputs come from other Blocks, project context or the user. Use the typed port system: shared StillMade types (`image`, `video`, `audio`, `asset`, `script`, `shot[]`, ...), `required`, a short `description`, and a `semantic` only where it narrows what fits. Mark exactly one primary input and one primary output so Project Type Steps connect automatically, and use `kind: "task"`: a `workspace` Block owns a project document and is never connected automatically. Inputs marked `context` read the project and cannot receive a connection from another Step. Output reusable StillMade values: media references (`{kind,assetId,versionId,url}`) and structured production values with `schemaVersion: 1`, preserving provenance, versions and relationships downstream Blocks need. Never make ordinary users wire JSON, copy IDs, understand internal paths or translate one Block's output into another: `createUniversalResolver()` resolves inputs from compatible upstream outputs, permitted project context and, for optional non-context inputs, `StillMade.requestFromUser`.
+
+## Feature map
+
+Every Block carries a feature map in `manifest.features`, written by whoever builds it while they build, so the person never writes it. Add one entry for each separate thing a person could ask for: a tool, a mode, a preset family or a kind of result (an editor's reaction GIFs, its motion presets, a recorder's screen recording), not one entry covering several tools. Each entry has a lowercase `id`, a `label` of 40 characters or fewer, `does` (what it does, 160 characters or fewer) and `asks`: 1–8 short requests in a customer's own words that this feature answers ("add a fire gif over my car"). `operation` names an id in the Block's own `manifest.operations` (omit it when there are none); `inputs`/`outputs` name declared ports. The gate fails a Block without one. Add or update the entry in the same change that adds or alters a tool, and remove it when the tool goes. List only what the code really does; listings are generated from this map, nobody can edit them, and StillMade matches requests to features. Features are not tested at publish: each shows as new until real use proves it.
+
+## Use platform primitives
+
+Prefer, in order: an SDK capability; a documented host capability (the hosted operations are text.generate, audio.speech, audio.transcribe, audio.music, audio.sfx, image.generate, video.generate, image.describe, media.analyze, web.fetch, web.research, timeline.propose, workspace.propose, connection.execute; connected third-party apps go through `connection.execute`); an approved dependency the SDK already bundles; small Block-local code. Do not duplicate what StillMade provides. A Block never contains its own asset system, file picker, authentication, project-context system, input resolver, Block connection system, credit system, secrets store, permission system, progress system, multiplayer system, persistence system, model-provider abstraction or execution protocol.
+
+## No hidden workarounds
+
+Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.filesystem` and `permissions.secrets` must be empty arrays, and so must `permissions.network`, except in a module Block, which lists the https origins it calls through `stillmade.net.fetch`.
+
+## Name it briefly
+
+Give the Block a short, plain name of 40 characters or fewer that says what it does ("Captioned Clip", not "Captioned Business Clip Generator With Review"). The name appears in step bars, Project Type cards and pickers, so put the detail in the description instead. New releases with a longer name do not pass readiness.
+
+## Name inputs in the job's words
+
+Name each input for what the person brings, in the job's words: `sermonVideo` for a sermon clip Block, `listingPhotos` for a listing, `lessonSlides` for a lesson podcast. StillMade titles the input from that name ("Sermon video") and words its drop area from it ("Drop your sermon video here", the formats, "Choose a video"), in StillMade and the SDK preview, so never draw your own upload box or `<input type="file">`: a Block's screen shows the files as tiles and adds more with `<button class="sm-add" data-stillmade-add="listingPhotos" aria-label="Add photos">`, which opens StillMade's picker and upload, and a list's tiles drop or reorder a file with `data-stillmade-remove="listingPhotos" data-index="2"` and `data-stillmade-move="listingPhotos" data-index="2" data-to="1"` buttons; the files arrive through `onInput`. Keep a bare type name (`video`, `file`) only when any file of that kind does the job. The `description` says what makes a good one.
+
+## Speak the job
+
+These are StillMade's defaults: unless the person or the creator asked for something else, every screen speaks the job in its own words and adds nothing else. `manifest.action` names the Step's button, {label:"Plan the tour", running:"Planning the tour…"}, and StillMade adds the price ("Plan the tour · 1 credit"). Every Block whose Step shows StillMade's button declares it: any Block without its own screen, and any that calls operations. Without it StillMade can only guess from the Block's name or output ("Make clips"), and the readiness gate and StillMade's own builder send the Block back until it names the job. When the Block makes a picture, video or sound with AI the label starts with Generate and says what ("Generate tour", "Generate voiceover"); one that cuts or renders the person's own media says Make ("Make 6 clips"); never "Make it", "Run", "Submit", "Process" or a bare "Generate". The main button stands out: one solid `sm-primary` in the kit's ink, never restyled to the background; everything else is `sm-quiet` or an `sm-icon`, and close is an X icon. Report progress in the job's units with `stillmade.progress(fraction, label)` ("Moving through the kitchen, 4 of 9 rooms"), never "Processing". Head the result in the job's words ("9 rooms", "Your tour · 44 s"), never "Output". Say a problem in one line with its fix beside it ("No bathroom photo. Guests look for one." and Add photo). Stay quiet: no welcome text, tips under fields, tours or banners, and at most one line of guidance on a screen, only where the next move is not obvious; anything more goes in the input's `description`, which StillMade shows behind an (i). Say nothing about how the Block works (where it runs, saving, syncing, recovery, accounts, credits) or where a file is kept: StillMade tells the person what they need as one short notification, or nothing; never a sentence on the page, and never the same line under each item. Every drop area offers "Use a reference", which fills the Step from the person's saved photos, videos and notes: media inputs fill by kind, so take `video` or `asset` where a clip works as well as a photo, and text inputs fill by plain names and labels (`productName`, `website`, `brandColors`, `fonts`, `voice`, and `details` or `notes` for the reference's note); never build your own reference picker. Days and times are picked, never typed: use the `date` type, which StillMade shows as a calendar, with a list of times when the input is about a time (`postAt`, `startsAt`); a custom view uses `<input type="date">` or `type="datetime-local"`. Posting is a connector Step of its own, and StillMade words its button from the app and action ("Post to Instagram"). Before handing the Block back, clear every Wording note that `gate` and readiness list, unless the person asked for those words.
+
+## Interface
+
+If the capability needs UI, use the Block UI SDK: generated `manifest.ui` controls first; a sandboxed custom view (`view.html`/`view.css`/`view.js`) only when the core interaction needs one. Build custom views from the Block kit the host injects (`block-kit.css`): the result in `sm-stage`, drawn before the first run in the shape and size of what is coming (`data-ratio="9:16"` for a vertical clip, lines for text, a player bar for sound) so every part of the screen is in place at once and the result fills a place the person already sees instead of popping in somewhere unexpected; StillMade draws it the same way on the Steps it draws; on a wide screen what goes in sits on the left and the result on the right, side by side, and they stack only on narrow screens and phones, the result's place under the button, picks as pictures in `sm-choices`, the picked one in the kit's ink fill (never restyled to an outline, a tint or the page's background) so it reads at a glance, one solid `sm-primary` naming the action in the job's words ("Plan the tour", "Generate voiceover"; never "Run" or "Make it") and no price (StillMade's run button adds it), extras in a closed `sm-more`; a look the person names wins. Fit one laptop screen without scrolling: label beside control, status in a few words, files as tiles, rare tools as icons, (i) on unclear controls. These compact rules are for a job or an ingredient. Size the view to the Block's tier (block-tier.js): an app, a workspace a person works in for a while (video editor, 3D configurator, CAD or drawing tool), looks and works like that kind of app instead of a compact page: its canvas or stage fills the view, with the panels, toolbars, inspector or timeline such an app has, direct manipulation (select, drag, zoom), keyboard shortcuts and undo; it keeps the host appearance and Block kit controls, its panels may scroll, and on a phone its tools fold into sheets while the canvas stays usable. Never shrink an app into a form of fields and one button. StillMade centers a standard view narrower than its Step and zooms a view to fill its space; an app that lays itself out (full-size canvas or WebGL, its own scroll, pan or zoom, its own Ctrl/Cmd +/- keys) puts `data-stillmade-layout="own"` on its outermost element, and StillMade then never centers, zooms or takes those keys. StillMade draws one player for every `<video controls>` (play, timeline, time, sound and full screen, shown while the pointer is on the video, with keys and touch) and a full-screen button on result pictures in `sm-stage` or `sm-gallery` and on any element marked `data-stillmade-expand` (the same value makes one set of pictures, `off` removes it); `data-stillmade-player="native"` keeps the browser's controls, and a `<video>` without `controls` is the Block's own and is never touched. A picture or clip that cannot show here (kept on another device, or it did not open) keeps its place as a quiet `sm-media-off` tile in its own shape with the `image-off` glyph and the reason in its label, never words in its place. Drop words nobody needs; put helpful ones in a closed `sm-hint`. Mark each button `data-stillmade-action` (`run` on the one that runs the Block, which the device checks press once; a page that checks first keeps `run` on that button for both presses; what it does on the others, `"play sample"`) and label each field: Chat presses and fills them. Expose the capability, not the implementation: sensible defaults, previews, progress, clear errors, visible outputs. Show no raw JSON, internal IDs, filesystem details, provider terms or developer settings unless the Block is a developer tool. When a person chooses among options they need to hear or see (voices, music, fonts, looks, templates, images), let them preview each option before choosing: a sample or thumbnail from the Block's own files or the host's free samples, never a paid generation. Skip previews only when there is nothing to preview. Choices StillMade owns (voices, models in the run review) already show samples. Follow the host appearance (Light, Dark and White) and one elastic layout: stacked on a 320px phone with no sideways scroll (the inputs, the button in normal flow, never pinned, then the result's place under it), and from 860px the controls left (≤380px), the result filling the right. Short settings sit side by side, each label beside its control (`sm-field`, `sm-settings`; three or four short options as one `data-segmented` row); many items are one line each (`sm-list`) that open in place; input files are small tiles (`sm-gallery data-size="small"`); on a phone chip rows scroll sideways and long lists show three. Compacting moves controls, never deletes them.
+
+## Shared editing
+
+Projects are multiplayer. A custom view subscribes through `StillMade.onShared(callback)` and publishes every editable field: give static controls a unique `id` and `data-stillmade-share="field"` (the host owns their synchronization), use `StillMade.bindShared(field, elementId)` for controls created dynamically, and `StillMade.updateShared(values, before, options)` for structured values; private variables and DOM values are not shared. Mark a truly device-only control (playback, hover, device selection) with `data-stillmade-local`. Observe shared outputs as well as state, honor `canEdit` in every mutating callback (read-only participants cannot write), never run, click or call a paid integration in response to a remote update, and preserve conflicting drafts. Shared background work uses `sharedWork` with the `work.shared` permission.
+
+## External services
+
+Reach external services only through StillMade's hosted operations, the connections service (`connection.execute`), or, in a module Block, `stillmade.net.fetch` to origins declared in `permissions.network` (with the key each needs), `stillmade.net.connect` for a live WebSocket to one of them, and `stillmade.connections.call` to adapters or catalog apps in `permissions.connections`; never put keys in code, inputs or headers: StillMade adds each person's own key on its servers. The host owns the model and provider choice, BYOK keys, StillMade credits, spending consent, authorization, token refresh, rate limits, retries and provider errors; a Block never receives a secret and never names a provider unless it must. Treat provider unavailability, timeout, cancellation and partial failure as outcomes the Block reports, not crashes: a call the result needs throws and fails the run (see Useful failures); an optional part's failure is caught, given its fallback and named in an optional `notes` text output. Generated images, video, voices, music and sound effects come from hosted operations or the `media.generate` action, paid with the user's StillMade credits at StillMade's prices; for structured model output declare a `json` output with `capability.schema` instead of parsing prose. When a Block needs npm libraries, WebAssembly (threaded: `"threads": true` in module.json) or heavy compute, use `runtime: "module"` and reach hosted operations through `stillmade.hosted.run` with the operations listed in `permissions.capabilities`. Decode, cut, join, re-encode, extract or normalise audio and video with `stillmade.media.transform` on the device; never ask for a server render. For a rich interactive interface (React or another framework, SVG, canvas, drag), use a frame view: `src/view.config.json` with `{"runtime":"frame"}` and `src/view.js` bundled as one IIFE, colored with StillMade's theme variables. For files and structured data use the `file`, `document`, `table`, `url`, `date` and `color` types and their generated controls and presentations, not JSON text.
+
+## Dependencies
+
+A Block must declare everything it requires and must not assume anything is installed. Portable packages carry no package dependencies (`portable.dependencies` is empty): inline small, license-compatible code and record its license and notice in `manifest.license` and `manifest.provenance`. The copyright holder in the Block's own `provenance.notice` is the person it is made for: replace the placeholder `create` writes with their name, never StillMade, the SDK or yourself. Desktop-only tools are reached solely through declared desktop permissions and the host desktop bridge. If a dependency cannot be delivered through the Block runtime, report the incompatibility instead of assuming the user's machine has it.
+
+## Security
+
+Treat Block code, external data, files, repositories, model output and network responses as untrusted. Request the minimum permissions and capabilities; `stillmade-block permissions --fix` declares exactly what the source uses. Do not weaken the sandbox (QuickJS has no fetch, DOM, timers, modules or Node APIs). Validate and bound every value crossing a boundary. Never expose secrets through logs, outputs, project context, UI, error messages or serialized state.
+
+## Execution lifecycle
+
+A successful run means more than a returned value. Validate inputs before work; return only declared output ports with values matching their types; run long work as a cooperative job (`job.pending` with monotonic progress) instead of blocking; honor cancellation and the host timeout; keep persistent state in `manifest.state` (module Blocks: `stillmade.storage`) with migration routes so a reopened project and a repeated run behave the same; never leave orphaned jobs, temporary values or corrupted project state after cancellation or failure.
+
+## Useful failures
+
+Errors must say what failed, why it likely failed, whether a retry makes sense and what the user can do, so the native project chat and controller can troubleshoot. In JavaScript, throw an `Error` with that message: the host reports it as a `JAVASCRIPT` run failure carrying your message (guest code cannot set its own error code). Reject invalid or oversized input up front with a message naming the input and the limit. Never reduce a failure to "Something went wrong".
+
+## Only supplied facts
+
+A text Block that writes from supplied facts must not let its prompt template outrank its own "never invent" rule. Every section that needs a specific fact (phone, website, address, price, inspection, certification, warranty, features) is written only when the input supplies that fact; otherwise the section is left out or replaced by a generic line that asserts nothing (for example "Call us today to schedule your test drive."). Never default to "inspected", "certified", invented features or placeholder contact details such as 555 numbers or example websites. Prefer extract-then-generate: first list the facts the input actually contains, then write using only that list. Add a check after generation that rejects or removes sentences naming a claim, number or address not present in the input. Include fixtures with the facts omitted and with them supplied.
+
+## Adapt to the platform
+
+Do not modify StillMade core because a request does not fit immediately. First implement the capability entirely through documented SDK and platform primitives. If that is impossible, classify why: A Block implementation problem (fix it), B missing SDK exposure of an existing host capability, C missing generic platform primitive, D security or permission restriction, E runtime or language incompatibility, F fundamentally incompatible capability. For B or C, name the smallest general primitive that would serve this Block and a meaningful class of future Blocks (shaped like `files.watch()` or `media.transform()`, never `supportThisSpecificBlock()`). Return `{"unsupported":"exact reason","gapClass":"B|C|D|E|F","primitive":"..."}` instead of a package that pretends to work.
+
+## What StillMade verifies
+
+StillMade runs the readiness check on every Block it admits: manifest and contract validation, the source security scan, every fixture in the sandbox, wrong-type and over-limit inputs, declared output types, cancellation and timeout cleanup, state reopen and repeated runs, composition with a real upstream and downstream catalog Block through the resolver, a Project Type preview, the shared-interface contract with two participants editing a custom view in the real preview runtime (their edits must converge and a read-only participant must not write), and phone and desktop layout. Design for all of them and include normal and edge-case fixtures (1 to 50; stateful Blocks also declare `expectedState`). Test materially different inputs within the declared capability, and document limitations instead of overclaiming generality. Two of these checks need StillMade itself: two-participant shared editing and the phone and desktop UI profile run in StillMade's preview runtime when the Block is imported or released, so `ready` in the downloaded SDK reports them as not verified rather than passed.
+
+## Project Types
+
+A Project Type is an ordered production workflow. Each Step's primary output must be a compatible input for the next Step, secondary values come from permitted project context, and every member Block obeys this contract. Install Blocks into a realistic Project Type: project chat must understand each Step, inputs must resolve intuitively, outputs and execution state must be visible, failures must be diagnosable, and the user must be able to continue through the workflow. Group the parts of one job into one Step instead of listing helper parts as Steps; most automations are two to four Steps.
+
+## Readiness report
+
+Finish with a Block Readiness Report: capability, contract (inputs, outputs, permissions, dependencies), platform APIs used, tests actually performed and their results, the composition test (upstream, Block, downstream), known limitations, unsupported requirements and any platform gap with its smallest general primitive. Report exactly one status, the one StillMade's readiness check returned (`ready` in the SDK CLI, `check_block_readiness` over MCP), never one you chose: PRODUCTION READY (every applicable check passed), READY WITH DOCUMENTED LIMITATIONS (works reliably within stated boundaries), BLOCKED BY PLATFORM CAPABILITY (needs a missing generic primitive) or FAILED. Never label a Block production ready to satisfy a request, and never claim a check ran when it did not.
+
+## Definition of done
+
+A Block is done only when every applicable item holds. Passing a compile, one unit test, a rendered UI or one happy-path sample is not done.
+
+- DOD-01 Installs through the normal Block mechanism
+- DOD-02 Manifest and contracts validate
+- DOD-03 Runs through the normal runtime
+- DOD-04 Required permissions are declared
+- DOD-05 Required dependencies are reproducible
+- DOD-06 Real inputs work
+- DOD-07 Invalid inputs fail correctly
+- DOD-08 Outputs conform to their declared types
+- DOD-09 Outputs are usable by compatible downstream Blocks
+- DOD-10 Universal resolver integration works
+- DOD-11 Applicable project context works
+- DOD-12 Applicable persistence works
+- DOD-13 Applicable multiplayer behavior works
+- DOD-14 Cancellation and failure cleanup work
+- DOD-15 UI works in relevant states and screen sizes
+- DOD-16 No hidden developer setup is required
+- DOD-17 Security boundaries remain intact
+- DOD-18 Relevant integration tests pass
+- DOD-19 Works after application restart or project reopen
+- DOD-20 A realistic Project Type execution succeeds when applicable
+
+## Platform gap classes
+
+- A: Block implementation problem
+- B: Missing SDK exposure of an existing host capability
+- C: Missing generic platform primitive
+- D: Security or permission restriction
+- E: Runtime or language incompatibility
+- F: Fundamentally incompatible capability

package/docs/build/comfyui.md

@@ -0,0 +1,227 @@
+# ComfyUI Blocks
+
+The reviewed adapter now supports core text-to-image and image-to-image generation. Use `CheckpointLoaderSimple`, `CLIPTextEncode`, `EmptyLatentImage`, `KSampler`, `VAEEncode` and `VAEDecode` with existing `PreviewImage` output. One installed safetensors checkpoint basename, one sampling pass, batch 1 and at most 40 steps are admitted. Generation dimensions are 64–1024 in multiples of 8, subject to the existing four-megapixel aggregate working budget (1024-square image-to-image can exceed it). The connection must report that checkpoint; filenames do not prove file hashes, licenses or GPU readiness. No weights are downloaded. `comfyModelRequirements(workflow)` returns the required model names. Text and numeric controls use typed scalar bindings. The import wizard preserves real sample inputs and prepares padded image-to-image fixture copies; project inputs are never silently resized. See `examples/comfy-text-to-image.stillmade.json` and replace the checkpoint placeholder before review.
+
+A ComfyUI Block is a portable declaration of a reviewed image capability. Users
+see its controls and resulting image, not its internal node wiring. Start with
+[the complete example](https://stillmade.shop/block-sdk/examples/comfy-invert.stillmade.json).
+
+### Import an existing ComfyUI workflow
+
+Choose **Import ComfyUI workflow** in the import tools, or choose its JSON file
+with **Import package**. Export the **API format** from ComfyUI first; its
+[API documentation](https://docs.comfy.org/development/cloud/overview) describes
+the numbered node map. Visual exports containing `nodes` and `links` cannot be
+converted without the exact frontend/node definitions and receive export guidance.
+The importer accepts the prompt map itself or `{ "prompt": { … } }`. A ZIP may
+contain one `workflow.json`, `workflow_api.json`, or `*.comfy.json` file.
+
+The mapping screen asks for the Block name, description, source license, input
+and result names, and the main image input/output. Multiple image inputs or
+outputs require an explicit main choice. Optional semantic roles distinguish
+source images from character references. Resize controls can stay fixed or become
+user-editable inputs. Every LoadImage and PreviewImage must be mapped; unknown
+nodes, dependencies, credentials, cycles, and disconnected processing are rejected.
+This adapter accepts the reviewed image and diffusion classes listed below, not arbitrary custom-node workflows.
+
+Choose a sample for every image input. The browser creates a copy no larger than
+128 pixels per side, with a combined fixture budget, and includes those pixels
+in the downloaded source. Originals are unchanged. The sample stays local until
+you explicitly run the backend review. Optional expected dimensions add fixture
+assertions; leaving them blank still requires a valid decoded single image.
+Choose sample images you may distribute with this Block.
+
+**Continue to tests and preview** creates an SDK package, not an installation or
+a successful test. The existing account connection, real fixtures, separate
+sample execution, preview, rights review and **Confirm Import** follow. Importing
+never republishes third-party code. The original API JSON is retained in
+`manifest.provenance.comfyuiImport.source`; execution uses normalized placeholders
+instead of its saved image filenames. Original `_meta.title` remains attribution,
+not executable behavior. Review this retained source before sharing a release.
+
+The downloadable SDK exposes the same static conversion API:
+
+```js
+import {inspectComfyImport, buildComfyImportPackage}
+  from './packages/block-sdk/index.js';
+import {comfyImageInvert} from './packages/block-sdk/comfyui-example.js';
+
+// Replace with a supported API export. No backend is contacted by either call.
+const raw = structuredClone(comfyImageInvert.comfyui.prompt);
+raw['1'].inputs.image = 'my-example.png';
+const inspection = inspectComfyImport(raw);
+console.log(inspection.inputCandidates, inspection.outputCandidates);
+
+const pkg = buildComfyImportPackage(raw, {
+  manifest: {...comfyImageInvert.manifest, id: 'my.invert', name: 'My invert'},
+  inputs: comfyImageInvert.comfyui.inputs,
+  outputs: comfyImageInvert.comfyui.outputs,
+  tests: comfyImageInvert.tests,
+});
+// Save pkg as JSON, then import it for real backend review and confirmation.
+```
+
+`inspectComfyImport(raw)` returns `format`, inert `source`, normalized `prompt`,
+`nodes`, `inputCandidates`, `outputCandidates`, `warnings`, and
+`execution: "not-run"`. It does not choose names, roles, primary ports or fixtures.
+`buildComfyImportPackage(raw, {manifest, inputs, outputs, tests})` requires those
+explicit choices, validates their contracts and selected resize values, and
+returns a package without execution receipts. Source is limited to 64 KiB and
+the complete package to the usual bounded JSON/import limits.
+
+### Package and runtime contract
+
+Set `manifest.runtime` to `comfyui`, `entry` to `src/comfyui.json`, and declare
+`permissions: {project: [], capabilities: ["comfyui.execute"]}`. The top-level
+package contains `manifest`, `comfyui`, `tests`, and an optional `view`. It cannot
+contain `code` or `recipe`. Put the workflow in `comfyui` or, in an editable folder,
+`src/comfyui.json`. Endpoints, tokens, connection IDs, file paths, dependencies,
+and Python never belong in the package. Input/output types and semantic roles
+use the same StillMade contract as other Blocks.
+
+The workflow has four fields: `schemaVersion: 1`, `prompt`, `inputs`, and
+`outputs`. `prompt` is an API-format map of numbered nodes with `class_type` and
+`inputs`. Supported core classes are `LoadImage`, `ImageInvert`, `ImageScale`, `PreviewImage`, `CheckpointLoaderSimple`, `CLIPTextEncode`, `EmptyLatentImage`, `KSampler`, `VAEEncode` and `VAEDecode`. Every node must contribute to a declared output. A `LoadImage`
+uses an empty filename placeholder and a binding such as
+`image: {node: "1", input: "image", encoding: "uploaded-image"}`. StillMade uploads
+verified input pixels and supplies the generated basename. Resize controls use
+`encoding: "scalar"`. An output selects one image from a declared PreviewImage:
+`image: {node: "3", collection: "images", index: 0}`.
+
+Each fixture has `name`, `input`, and `expectations`. For example:
+
+```json
+{"name":"One pixel","input":{"image":{"width":1,"height":1,"data":[20,80,200,255]}},"expectations":{"image":{"kind":"image","count":1,"width":1,"height":1,"maxBytes":4096}}}
+```
+
+Every output requires `kind: "image"` and `count: 1`. Optional width, height,
+maximum encoded bytes, and lowercase `sha256` check the host-decoded and
+re-encoded PNG, not a claimed backend descriptor. Use deterministic hash fixtures
+when exact image behavior matters. Bounds: 16 nodes, 8 inputs/outputs, one
+megapixel per single-frame image, and four megapixels total working images.
+Small inline fixtures fit the four-megabyte import limit. Large media inputs
+should use existing account-owned media references.
+
+In Settings → ComfyUI connections, save the public HTTPS endpoint and optional
+bearer token. Tokens use the same stable account encryption key as BYOK with a
+separate encryption purpose. They are never returned to the browser or guest UI.
+StillMade rejects private network endpoints, redirects and arbitrary requests.
+The backend is an explicitly selected service you operate or trust. Checking
+its core-node schema is compatibility evidence, not attestation of its Python
+implementation. Desktop loopback and arbitrary custom nodes are not available through this adapter. Reviewed core diffusion nodes may use the backend’s GPU after explicit approval.
+
+Import the JSON or ZIP, choose the connection, and click **Run tests and sample**.
+StillMade scans the package, records durable jobs, runs every fixture and a
+separate sample, decodes outputs, and displays the before/after result. Only then
+can you confirm rights and **Confirm Import**. Confirmation revalidates the
+account/source/connection-bound receipt without silently submitting another job.
+Changing source, connection revision, backend contract, or an expired receipt
+requires another review. Saving a connection, opening a page, and custom iframe
+JavaScript cannot confirm remote execution. Preview runs never install or
+publish a Block. Cancellation targets only owned jobs; unsupported remote
+cancellation can leave work running on the selected backend. The SDK rejects a
+cancelled invocation immediately even if its trusted host callback is still
+waiting. Source and input contracts are captured before dispatch; editing the
+caller’s package during execution cannot change output validation.
+
+In a saved project, the host checks edit access and finds a completed review for
+this exact package and connection. A current backend compatibility check runs
+without resubmitting fixtures. A successful import review can be reused for
+project execution after its import-confirmation expiry; changed source,
+connection revision, backend schema, or security status invalidates that reuse.
+The host asks for **Run in project** before submitting the actual project input.
+If review is required, **Run tests and sample** and its preview come first, then
+a separate **Run in project** action. Custom interfaces cannot skip these actions.
+Durable production jobs are associated with the saved project. Local demo and
+Marketplace previews remain samples and cannot claim project access.
+
+Offline `validate` and `pack` check and package source. For ComfyUI, `pack` returns
+`reviewRequired: true` and zero executed tests. `test` and `preview` return
+`RUNTIME_UNAVAILABLE` without a trusted host executor. A host integration may
+pass `options.comfyui(package, input, {signal})` to `runPackageAsync` or
+`testPackage`, returning `{outputs, metadata}` where every metadata entry has
+verified width, height, bytes, `mimeType: "image/png"`, `frames: 1`, and optionally
+SHA-256. This callback is trusted host code; it is never loaded from a package.
+
+The server supports reviewed ComfyUI packages inside Project Types through the
+account-bound envelope below. The import wizard opens each included ComfyUI Block
+in its connection review panel. Unattended ComfyUI automation remains unavailable.
+Existing recipe/JavaScript Project Types and exact-output fixture checks are unchanged.
+
+### ComfyUI packages in Project Types: host integration
+
+The offline CLI can package ComfyUI-only or mixed hosted/local Project Types:
+
+```sh
+node packages/block-cli/cli.js validate ./workflow.json
+node packages/block-cli/cli.js pack ./workflow.json ./workflow.stillmade.json
+```
+
+This performs static/schema checks on every embedded package and preserves exact
+source. It never runs a provider, connects to ComfyUI, or executes local fixtures.
+The result explicitly reports `tests: 0`, `reviewRequired: true`,
+`liveVerified: false`, and `workflowComplete: false`. Import the result into
+StillMade for authenticated backend review, local tests, sample execution, and
+user confirmation. Unsupported ComfyUI nodes still fail the static package scan.
+
+
+The authenticated review/import/release/install APIs accept `typeComfyuiReviews`
+alongside `typeCapabilityReviews`. It is request metadata, never portable source:
+
+```json
+{
+  "typeComfyuiReviews": {
+    "<exact package SHA-256>": {
+      "receiptId": "<account review UUID>",
+      "connectionId": "<account connection UUID>",
+      "connectionRevision": 1
+    }
+  }
+}
+```
+
+Provide exactly one entry for every embedded ComfyUI package, including unused
+or disabled packages. The server authenticates every fixture and sample against
+the selected backend contract, then checks the ledger again at the save boundary.
+Missing, expired, foreign, cancelled, or changed-connection evidence is rejected.
+Saved imports, release reports, and installation reports retain the fixture and
+sample media. Another account must provide its own reviews. No prompt is
+submitted by receipt verification.
+
+A trusted SDK host can supply `verifyComfyPackage` in the third argument to
+`verifyHostedProjectTypePackages(type, verifyCapabilityPackage, options)`.
+The callback must return the server-verified Block report, including `receiptId`,
+`connectionId`, and `connectionRevision`. The resulting opaque handle supports
+`testProjectType` and `previewProjectType`; JSON claims cannot substitute for it.
+Offline rehearsal defers reviewed ComfyUI execution and its dependent outputs.
+Interactive rehearsal requires `verifyHostedResult` before downstream execution;
+retained run metadata uses `comfyuiRun`. A passing package admission report still
+does not prove that the complete connected workflow ran.
+
+In the import or builder review, choose **Review Block** beside each ComfyUI
+package, select your connection, and run its tests/sample (or reuse a fresh
+matching review). Finish the package checks, inspect the result, and confirm
+import. Connected workflow preview separately confirms each ComfyUI execution
+and refetches its exact run evidence before handing images downstream. These
+interactive controls do not enable unattended remote execution.
+
+
+### Connected ComfyUI execution in a project
+
+**Run connected steps** can continue through ComfyUI Blocks when you approve each
+run on your account connection. It reuses the existing reviewed-connection dialog;
+missing fixtures require a separate review before the project input runs. Image
+references reach the broker intact, so the server can check project access and
+bind the exact input. Local image processors decode accepted images as needed.
+
+The host uses `planSegment(..., {interactive: true})` and supplies an authenticated
+`verifyHostedResult` callback to `runSegment`. ComfyUI results retain `comfyuiRun`
+and `mediaReceipts`; hosted model results retain `capabilityRun`. These callbacks
+are trusted StillMade integration code, never imported Block code. A resumed run
+or **Use results** re-fetches and verifies each remote result against the current
+project, source, inputs, and connection metadata before accepting it. Waiting for
+consent or a remote backend does not consume the local computation budget.
+
+Cancellation or failed verification stops downstream work and retains earlier
+completed results for review. The default non-interactive planner still stops at
+ComfyUI or hosted model Blocks; future-media automation cannot submit those jobs.

package/docs/build/concepts.md

@@ -0,0 +1,40 @@
+# Blocks, Steps, and Project Types
+
+## Block
+A reusable production workspace or capability. The built-in catalog consists of full screens: Script Writer, Voiceover, Shots, Blueprint, Canvas, Editor, Image Panels, White Board Motion, and Assets. Chat is not a Block: it is the project's own conversation, which every Project Type starts with. Internal canvas nodes and individual editor controls are implementation details inside their workspace, not separate built-in Blocks.
+
+External processing Blocks, such as Thicken Line Art or lip sync, add a capability to the workflow. A Block declares input and output ports, permissions, controls, and an implementation runtime.
+
+## Step
+An instance of a Block inside a Project Type. Each Step has its own instance ID, pinned Block ID and version, configuration, enabled state, and optional condition. Reusing a Block in two positions creates two independent Steps.
+
+## Project Type
+An ordered production workflow. Its persisted `stages` array stores Steps for compatibility with existing projects. Users can add, remove, duplicate, configure, disable, or reorder Steps. The protected starting chat belongs to the host and cannot be replaced or remixed.
+
+## One job per Step
+A Step is one job: the work between two moments where a person or the outside world must see the result. A guided job, one the person fills in and then gets a result from, is one Step with one Block whose own screen holds everything: the inputs and settings, then a cheap check before the expensive run (the script and a voice sample before the video), then the result. On a wide screen the inputs sit on the left and the result's place on the right; on a phone they stack, the result's place under the button. A cheap check or a review the person does on that screen never starts a new Step. Start a new Step only at one of these points; everything else is a part of the neighboring Step.
+
+1. **A person works with the result**: in a workspace they spend a while in (the Editor, a storyboard, a Canvas, a CAD or drawing tool), or someone else approves or takes it over (a hand-off). Turning what a workspace made into something else is the next Step: a CAD tool is its own Step, and the Block that takes pictures of its model and makes a video is the next one. So Bible, Canvas and Editor are separate Steps after Chat.
+2. **Finding new things turns into handling each one**: the trigger (a schedule or an app event), the app read, its filter and "only new" are the first job; what is done with each item is the next job. A trigger is a setting of the first job, never a Step of its own.
+3. **The result leaves StillMade**: it is sent, posted, published, paid or written into another app. Consecutive writes to the same app, with the glue that shapes data for them, are one job.
+4. **Setup or a wait**: a one-time setup that is not part of each job (a brand kit, capturing a voice or a likeness), or a render that takes minutes and is delivered later.
+
+In a production the Steps are the workspaces a person opens: work feeding the next workspace is its part, else it joins the one before. A Block with its own interface (a workspace, editor or picker) is always its own Step; two such Steps are never one. A Type whose own Block renders the finished video (`timeline.render`) needs no Editor Step; the Editor (1.0, captions and export built in) is a Step only when the person edits the cut by hand, and Export video is never a Step beside it.
+
+A part that only runs in the desktop app cannot share a Step with cloud parts. Before adding a Step, name which of these reasons makes it separate; if none applies, make it a part of a neighbor. A Step nobody would ever open must not exist on its own. Prefer an app task's own filter (a Gmail query such as `has:attachment filename:png`) to an AI check, and use AI decide only for judgement.
+
+Build one Block for a job one Block can do: a module Block calls every hosted operation the job needs (it transcribes a sermon, then finds the verses said in it), a JavaScript Block does several local transforms, a workspace owns its whole document. A Block being built never takes an ingredient's result only so the ingredient can be its own part or Step (Transcribe in front of a verse finder): it calls that operation itself. Parts in one Step (`groups` in the Project Type) are for jobs made of Blocks that already exist and app tasks, each keeping its own permission, approval and credit rules. Never invent a combined runtime.
+
+Examples: "a listing video from my photos and the home's facts" is one Step: one Block whose page takes the photos and facts, shows the script and a voice sample to check, then makes the video. "every new email with an image becomes a generated image" is two Steps, "Gmail · New emails with images" (When, fetch with an image filter, only new) and "Image from email" (AI write, Generate image); listing When, Fetch, Only new, AI decide, Continue only if, AI write and Generate image as seven Steps splits one job into its parts. "A new Meta lead goes to HubSpot" is three Steps: "Meta Ads · New leads", "Qualify lead" and "HubSpot · Add contact".
+
+## Typed connections
+An image-producing Block can connect to an image-consuming Block. Primary ports make insertion predictable; semantic roles distinguish a source image from a character reference. Secondary inputs can bind to project context.
+
+See [types and compatibility](../reference/types.md), [context](context.md), and [Project Type construction](../project-types/build.md).
+
+## Complete workspace Blocks
+Built-in Blocks are the existing complete production screens. A Guided Project Type starts with Chat, the project's conversation, then Voiceover → Shots → Blueprint → Canvas → Editor; export belongs to Editor. The reusable Script Writer is the full Narrative Compiler; it and the legacy Script adapter do not replace Chat. Canvas remains the home of persistent visual references and character consistency.
+
+The Block boundary follows the complete user-placeable Step. Package and remix the complete workspace, including its related tools. For example, Motion Graphics remains inside the Editor; Image Panels, Blueprint, and the Whiteboard Step are each one Block. The White Board Motion Project Type starts with Chat, then three complete Blocks: Voiceover, Whiteboard, and Editor, with no extra Project-Type Block. Historical component IDs may remain resolvable for saved projects without becoming discoverable Blocks.
+
+A source snapshot or host alias alone is not portable. A portable workspace owns its interface and executes through an installable SDK runtime. The first-party sm.blueprint@2.0.0, sm.board-editor@2.0.0, sm.editor@2.0.0, and sm.pipeline@2.0.0 packages in the downloadable SDK demonstrate complete sandboxed workspaces using typed documents and the public before/after workspace proposal contract. Whiteboard retains all boards, placed media, timing, transitions, motion settings, and custom fields as one remixable Block. Editor retains Motion Graphics and every other editing tool inside the Editor Block. Canvas retains its native content and layout while the Project Type builder owns Step placement and wiring. Package-supplied React bundles are not exposed; use [custom sandboxed HTML interfaces](custom-interface.md).

package/docs/build/context.md

@@ -0,0 +1,159 @@
+# Read project context
+
+A Step can bind an input to an explicit project context field:
+
+```json
+{
+  "inputs": {
+    "shots": {"type":"shot[]", "context":"shots"}
+  },
+  "permissions": {"project":["context.shots.read"]}
+}
+```
+
+Supported fields and exact types:
+
+| Context field | Input type | Contents |
+| --- | --- | --- |
+| `script` | `script` | `{schemaVersion:1,text}`; selected-shot narration for a narrow selection |
+| `scenes` | `scene[]` | Existing scene IDs, descriptions, and scoped `shotIds` |
+| `shots` | `shot[]` | Existing shot/panel IDs, scene ownership, descriptions, dialogue and timing |
+| `characters` | `character[]` | Canvas-selected visual references with blueprint descriptions |
+| `locations` | `location[]` | Canvas-selected location references with blueprint descriptions |
+| `styles` | `style[]` | Saved Canvas, blueprint, panel and board styles and references |
+| `assets` | `asset[]` | Current media with `assetId`, `versionId`, `kind`, `url`, source and explicit ownership |
+| `generations` | `metadata[]` | Retained generated-media records with `asset`, `active`, `status`, and saved generation metadata |
+| `versions` | `metadata[]` | Retained media versions and project-level shot-plan/timeline version metadata |
+| `timeline` | `timeline` | Current editor document; filtered collections in a scene/shot/asset selection |
+| `metadata` | `metadata` | Project ID/name and host-selected `scope` |
+
+Every binding requires its own `context.<field>.read` permission. These are exact
+permissions: `context.assets.read` does not authorize `context.versions.read`.
+The Step workspace, preview, and future-media worker derive this index from the
+project's current source documents. No duplicate production state is saved.
+
+Canvas remains authoritative for its existing asset IDs, approved/current version,
+and selected character/location/style reference galleries. Legacy reference
+images remain available without reselecting deliberately deselected images.
+Panels and White Board Motion supply their existing scenes, panels, collage
+media, transitions and voiceover. The editor supplies media-bin items, clips,
+audio, saved score takes and retained timeline media. An editor item explicitly
+linked by Canvas node/version or panel ID reuses that source identity; a stale
+editor copy cannot promote a different Canvas version. URL-only panel histories
+use deterministic version identifiers that survive history trimming. Different
+assets sharing a URL remain distinct. Legacy global `assets`/`library` caches are
+excluded because they can contain other projects' data.
+
+Media history entries contain `{schemaVersion:1, id, assetId, versionId, asset,
+source, active}` and only saved metadata such as timestamp, model or duration.
+Generation entries additionally have `status:"completed"`. Missing model/provider
+metadata is omitted, never guessed from a model currently selected in a control.
+Document history entries contain `documentType`, `versionId`, `active` and a saved
+label/name; they have no `asset`. These metadata entries do not contain old script
+bodies. A URL is a reference, not permission for guest code to fetch it.
+
+The host narrows context to the Step's selected scene, shots, or assets before
+binding inputs. Only explicit scene/shot ownership and source associations count;
+unowned media is excluded from narrow selections. Scene documents contain only
+selected `shotIds`, script contains only selected narration, and a narrow timeline
+omits unrelated collections, transcript and timeline histories. Unrelated
+character/location references are excluded. `metadata.scope` describes the
+selection. Guest inputs cannot widen it. Project-wide execution receives the
+project-wide snapshot only for the exact requested fields.
+
+`resolveContextInputs(manifest, explicitInputs, projectSnapshot)` copies only
+requested fields into input bindings. Context bindings take precedence over manual
+values. Guests have no live project handle, write-through access, credentials or
+ambient filesystem/network access. Fixture inputs must include concrete context
+values; offline execution does not invent a project. Context delivery is implemented
+in the Step workspace, preview and automatic-processing worker, not the advanced
+Canvas block runner.
+
+For example, a history-aware Block can declare:
+
+```json
+{
+  "inputs": {"history": {"type": "metadata[]", "context": "versions"}},
+  "permissions": {"project": ["context.versions.read"]}
+}
+```
+
+Its code reads `input.history` and checks for `record.asset` when processing media
+records. It must not assume every version describes a file.
+
+## Complete shot-plan context
+Use `{ "type": "shot-plan", "context": "shotPlan", "required": false }`
+with `permissions.project: ["context.shotPlan.read"]` to receive the complete
+saved shot-plan document. This preserves scene grouping, narration, timing and
+other saved planning fields instead of rebuilding a document from flattened
+`shots`. Array-based saved plans are normalized to `{schemaVersion: 1, shots: [...]}`;
+object plans retain their fields with `schemaVersion: 1`.
+
+This binding is available only for whole-project context. It is omitted for
+scene, shot and asset selections, and when no plan exists. The host copies the
+value; editing it does not save changes. Use the existing scoped `shots` binding
+for selected-shot processing. Media URLs inside documents grant no media-read
+permission; downloading still requires selected typed asset references and
+`asset.read`. Exporters can also read the saved score from `timeline.audioScore`
+under their existing `context.timeline.read` grant.
+
+## Standalone timeline export
+[Download Export timeline 2.0.0](https://stillmade.shop/block-sdk/examples/export-timeline.stillmade-block).
+This independently versioned JavaScript Block owns serialization and uses generated
+SDK controls plus the shared Download result UI. Add it to a project with a timeline,
+choose XML or XML + media, run it, then download. Its timeline, media, Blueprint,
+shot-plan and project-name inputs bind automatically to authorized project context.
+
+The canonical archive includes source, typed ports, UI schema, permissions,
+MIT notices, original-source evidence, lineage and three executable fixtures.
+Validate, test and remix it with the public CLI. No dependencies require manual
+installation. The exact package is also available through the first-party catalog.
+
+XML retains media links. ZIP bundles selected timeline media and fails if a
+requested transfer is unavailable. Auxiliary project documents are retained as
+metadata; their unrelated external media is not a full project backup. Device-local
+media and bundled sounds depend on supported host transfers. Normal sandbox and
+download limits apply. This is the existing StillMade XML serializer; compatibility
+with every external editing application has not been established.
+
+## Timed captions and caption styling
+[Download Captions 2.0.0](https://stillmade.shop/block-sdk/examples/captions.stillmade-block). This
+standalone, remixable Block converts a transcript into editable timeline captions.
+It owns phrase grouping, word timing and caption appearance, runs in the JavaScript
+sandbox, and returns ordinary `timeline-edit` proposals for review and Apply.
+It does not transcribe audio or spend execution credits.
+
+The optional context binding `{ "type": "transcript", "context": "transcript",
+"required": false }` requires `context.transcript.read`. At whole-project scope
+it supplies a copied `{schemaVersion:1, words:[{text,start,end}], text, audioUrl?}`
+from the saved voiceover when word timings exist. It is omitted when absent and
+for scene, shot or asset selections. URL metadata grants no media access.
+Explicitly connected transcript inputs remain separate from this fallback.
+
+Captions uses a connected transcript first, then entered text, then the project's
+saved transcript. Text without word timings uses estimated timing, identified in
+the proposal title. Start offsets word times into the timeline. Duration zero
+keeps transcript timing; a positive duration clips the result to that interval.
+A proposal supports at most 100 lines and rejects longer results without silently
+truncating them. Existing captions stay intact and locked tracks reject Apply.
+
+`caption.add` retains its required `{id,trackId,text,start,end}` values and also
+accepts these optional fields. Unknown fields and values outside these limits
+are rejected by the same SDK validator and host apply path:
+
+| Field | Accepted values |
+| --- | --- |
+| `words` | Up to 1,000 `{text,start,end}` entries, ordered by start, contained in the caption interval; nonempty text up to 5,000 characters, end at or after start |
+| `font` | `Hanken Grotesk` |
+| `size` | 8–200 |
+| `color`, `highlightColor` | Three- or six-digit hex color |
+| `background` | `none` or three- or six-digit hex color |
+| `backgroundOpacity`, `backgroundPadding`, `backgroundRadius` | 0–100 |
+| `position` | `top`, `middle`, or `bottom` followed by `left`, `center`, or `right`, separated by one space |
+| `animation` | `none` or `fade` |
+
+The host fills omitted appearance values with its existing defaults, preserves
+provided styling and clones word timings before saving through ordinary edit
+history. Caption updates retain their existing `{text,start,end}` contract.
+Package source, MIT notices, lineage and three fixtures are retained in the
+canonical archive; validate, test and remix it using the public CLI.