stillmade-sdk 0.1.41 → 0.1.43

package/docs/reference/package-jobs.md

@@ -0,0 +1,35 @@
+# In-session package jobs
+
+# In-session package jobs
+
+Original programmable spec §53 now has an explicit SDK host job handle. `createPackageJob(package, input, options)` returns immediately with an immutable ID, `getSnapshot()`, `subscribe(listener)`, `cancel()` and a `result` Promise. Status advances from queued to loading (contract/input checks), running (executor pending), then completed, failed or cancelled. A final operation count never completes the job.
+
+The default executor is `runPackageAsync`. An application may supply an explicit trusted `execute` adapter; BlockPlayground uses its existing `runInWorker`, preserving local worker isolation and existing capability/ComfyUI approval dialogs. The handle is created by host code, never read from a package or guest result. It accepts no polling URLs, tokens, guest functions, server IDs or automatic retry instructions. Opted-in JavaScript cooperative pending envelopes are consumed inside the sandbox; only final declared outputs reach this handle. Arbitrary pending envelopes still fail final-result validation. This is not a serialized or durable job receipt.
+
+Source/input/state are captured separately from the clones passed to the executor. Manifest and input/state validation precede execution; final outputs and declared Step state are validated before resolving. Preserved auxiliary host metadata does not become authenticated solely by this helper. Existing source admission, policy checks, output acceptance, stored media verification and attribution remain the host's responsibility.
+
+`onProgress` carries actual sequential recipe operation counts or validated cooperative continuation turns and optional declared units. Other runtimes retain their own approval/progress UI. Nothing derives provider percentage, cost or remaining time from elapsed time. The deadline defaults to 15 seconds and an explicit host override is bounded to 15 minutes. Cancellation/deadline abort the executor's signal, settle once, and suppress later outputs; they do not promise remote cancellation or reverse provider billing. Listener failures cannot turn progress into completion. Handles allow up to 64 listeners and release listeners/timers on termination.
+
+The shared `PackageJobStatus` renders the real snapshot. Block previews retain terminal states, offer cancellation both during input preparation and pending execution, and clear jobs for changed inputs/reset/new runs. Existing controller/source/revision/account fences remain necessary before accepting outputs. Connected Steps and import samples also use this handle through their existing trusted executors. Parent cancellation remains available during preparation, persistence and final admission after a child job completes.
+
+## Example for a trusted host
+
+```js
+import {createPackageJob} from './packages/block-sdk/index.js';
+const job = createPackageJob(pkg, input, {
+  signal: controller.signal,
+  execute: (pkg, input, options) => approvedHostExecutor(pkg, input, options),
+});
+const unsubscribe = job.subscribe(() => renderJobStatus(job.getSnapshot()));
+try {
+  const final = await job.result;
+  // Recheck current project/source and accept through the existing host boundary.
+} finally {
+  unsubscribe();
+}
+// A user cancel action calls job.cancel().
+```
+
+## Remaining scope and verification
+
+In-session jobs do not reconnect after reload, persist a provider queue, schedule background work or resume an arbitrary external guest job. Opted-in JavaScript can yield bounded JSON continuations within the original sandbox run; see [Cooperative guest jobs](COOPERATIVE_GUEST_JOBS.md). Existing hosted adapters retain their own durable request protocols. No hosted fallback or financial behavior is changed. SDK downloadable inclusion is wired in the generator; generated artifacts are separate delivery work. No tests, builds, browser QA, provider calls or migrations were performed for this implementation.

package/docs/reference/parity.md

@@ -0,0 +1,55 @@
+# StillMade Blocks and the SDK
+
+StillMade's own Blocks run on host services. Each one is listed here with the public SDK features that give a creator Block the same capability, so nothing StillMade builds for itself stays out of reach without a stated reason. A test fails when one of StillMade's Blocks starts using a service that is not on this list.
+
+| What StillMade's Blocks do | How a creator Block does it | Notes |
+| --- | --- | --- |
+| Canvas generation: images, videos, variations, stock and recording the asset. | hosted `image.generate`, hosted `video.generate`, action `media.generate`, action `stock.search`, `stillmade.assets.create` | Same capability |
+| Canvas media: stock search, uploads and generation with prices. | hosted `image.generate`, hosted `video.generate`, action `media.generate`, action `stock.search`, `stillmade.files.write`, control `file` | Same capability |
+| Canvas node placement for shipped workflow nodes. | permission `context.canvas.read`, permission `workspace.canvas.propose` | Same capability |
+| Canvas workspace chrome (low-balance ribbon, default model). | `IMAGE_GENERATION_MODELS` from the SDK | The credit balance ribbon is account UI; creator Blocks see prices in StillMade's own approval dialog before any paid run. |
+| Composes the Canvas workspace from its native parts. | permission `workspace.canvas.propose` | StillMade React components and hooks only render inside the app; creator interfaces are frame views (any framework) or standard views with generated controls, styled with the same theme variables. |
+| Creates a visual style with generated samples. | hosted `image.generate`, permission `context.styles.read` | Same capability |
+| Credits or the person's own key for image, video, chat, voice, music and effects. | hosted `text.generate`, hosted `image.generate`, hosted `video.generate`, hosted `audio.speech`, hosted `audio.music`, hosted `audio.sfx` | Same capability |
+| Crops panel images. | `stillmade.files.read`, `stillmade.files.write`, `stillmade.media.transform` | Same capability |
+| Downloads the media a controller selected, under the export policy. | control `download`, port type `file-bundle`, action `final.render` | Same capability |
+| Editor asset generation with a model, prompt, aspect, quality and reference images. | hosted `image.generate`, hosted `video.generate`, action `media.generate` | Same capability |
+| Edits panel settings with local runs and confirmations. | `StillMade.run`, `StillMade.updateShared` | Same capability |
+| Embeds the score, vibe and rough-cut panels in the Editor. | port type `timeline-edit`, permission `timeline.propose`, permission `context.timeline.read` | Same capability |
+| Final renders of the timeline on the device, under the export policy. | action `final.render`, `stillmade.media.transform` | Same capability |
+| Finds, loads and tags pipeline assets. | permission `context.assets.read`, `stillmade.project.read`, `stillmade.assets.appendVersion` | Gap: Clearing a generation watermark is tied to the account's plan and is not offered to Blocks. |
+| Generates panel images with model, quality and references. | hosted `image.generate`, hosted `video.generate`, action `media.generate` | Same capability |
+| Lists and applies saved visual styles. | permission `context.styles.read`, `stillmade.storage.get` | Same capability |
+| Live collaborative timeline editing with permitted updates. | `StillMade.getShared`, `StillMade.updateShared`, `StillMade.connectDocument`, permission `workspace.editor.propose` | Same capability |
+| Model lists and price labels for generation settings. | `IMAGE_GENERATION_MODELS` from the SDK, `VIDEO_GENERATION_MODELS` from the SDK, `AUDIO_GENERATION` from the SDK | Same capability |
+| Model, resolution, quality and voice options for pipeline settings. | `IMAGE_GENERATION_MODELS` from the SDK, `VIDEO_GENERATION_MODELS` from the SDK, `AUDIO_GENERATION` from the SDK | Same capability |
+| Notices, StillMade AI's presenter and upgrade prompts. | Not needed | Notices and plan upgrade prompts are account UI; a Block cannot raise them, so it cannot imitate billing or account messages. |
+| Opens and closes StillMade AI's presentation of a Step. | Not needed | This is StillMade AI's own presentation of Steps; creator Blocks are presented the same way automatically and need no API. |
+| Phone or desktop layout detection in the Editor. | `StillMade.render` | Device layout in a creator interface is ordinary responsive CSS inside the frame; StillMade checks it at 320 to 1280 pixels before import. |
+| Places StillMade AI's generated elements on a board or canvas. | permission `workspace.board.propose`, permission `workspace.canvas.propose` | Same capability |
+| Plans a panel strip from the script with a model. | hosted `text.generate`, permission `context.script.read`, permission `workspace.panels.propose` | Same capability |
+| Provisions StillMade AI's paid generation for a presentation. | action `presenter.generate`, action `media.generate` | Same capability |
+| Remembers a person's default image model and quality. | `stillmade.storage.get`, `stillmade.storage.set` | Same capability |
+| Rewrites panel prompts with a model. | hosted `text.generate` | Same capability |
+| Rough cut: frames, local footage, analysis, refinement, transcription and voiceover. | `stillmade.media.transform`, hosted `media.analyze`, hosted `audio.transcribe`, hosted `audio.speech`, hosted `text.generate`, `stillmade.files.write`, permission `timeline.propose` | Gap: Reading footage straight from the person's disk (without uploading it) is a desktop-only first-party path. |
+| Runs a draft recipe or JavaScript Block locally while it is edited. | `StillMade.run` | Same capability |
+| Runs Editor operations: renders, previews and timeline edits. | `stillmade.media.transform`, action `final.render`, permission `timeline.propose` | Same capability |
+| Runs the production pipeline: assembly, generation, budgets, references and deliveries. | hosted `image.generate`, hosted `video.generate`, action `media.generate`, hosted `text.generate`, `stillmade.files.write`, permission `workspace.canvas.propose`, trigger `media.saved` | Same capability |
+| Score and sound effect lanes: generated music and effects placed in the Editor. | hosted `audio.music`, hosted `audio.sfx`, action `media.generate`, action `stock.search`, permission `timeline.propose` | Same capability |
+| Shows a panel image large with its narration and text. | `StillMade.previewImage` | Same capability |
+| StillMade AI presents a workspace and adds board elements. | action `presenter.generate`, permission `workspace.board.propose` | Same capability |
+| StillMade dialogs and notices for Image Panels. | `StillMade.render` | StillMade's own dialogs stay host-owned so a Block cannot imitate account, payment or permission prompts; creator interfaces show their own confirmations inside their frame. |
+| Text, story segments and voiceover inside pipeline nodes. | hosted `text.generate`, hosted `audio.speech` | Same capability |
+| The Canvas preview shown for a Step. | `StillMade.render`, permission `context.canvas.read` | StillMade React components and hooks only render inside the app; creator interfaces are frame views (any framework) or standard views with generated controls, styled with the same theme variables. |
+| The Editor media library: project assets and uploads. | permission `context.assets.read`, `stillmade.project.read`, `stillmade.assets.create`, `stillmade.assets.appendVersion` | Same capability |
+| The Editor preview shown for a Step. | `StillMade.previewMedia`, permission `context.timeline.read` | StillMade React components and hooks only render inside the app; creator interfaces are frame views (any framework) or standard views with generated controls, styled with the same theme variables. |
+| The voiceover preview shown for a Step. | `StillMade.previewMedia` | StillMade React components and hooks only render inside the app; creator interfaces are frame views (any framework) or standard views with generated controls, styled with the same theme variables. |
+| Uploads and checks media files, thumbnails and downloads. | control `file`, `stillmade.files.write`, `stillmade.assets.create` | Same capability |
+| Vectorizes and upscales panel images. | `stillmade.asset`, `stillmade.files.read`, `stillmade.files.write` | Gap: Upscaling with a hosted model is not a hosted operation yet; module Blocks can only upscale with a model they ship in WebAssembly. |
+| Video assets workspace: model limits, durations, voices, prices and batch generation. | hosted `image.generate`, hosted `video.generate`, action `media.generate`, hosted `audio.speech`, `VIDEO_GENERATION_MODELS` from the SDK | Same capability |
+| Voiceover services: voices, takes and transcripts. | hosted `audio.speech`, hosted `audio.transcribe`, permission `context.transcript.read` | Same capability |
+| Voiceover workspace UI with live collaboration. | `StillMade.getShared`, `StillMade.updateShared`, `StillMade.connectDocument`, `StillMade.previewMedia` | StillMade React components and hooks only render inside the app; creator interfaces are frame views (any framework) or standard views with generated controls, styled with the same theme variables. |
+| White Board Motion: live collaborative board edits, elements and assets. | `StillMade.getShared`, `StillMade.updateShared`, `StillMade.connectDocument`, permission `context.board.read`, permission `workspace.board.propose`, permission `context.assets.read` | Same capability |
+| Who may change Image Panels right now. | `StillMade.getShared` | Same capability |
+
+Missing something? [Request a primitive](/create?request=primitive).

package/docs/reference/permissions.md

@@ -0,0 +1,86 @@
+# Permissions
+
+## Permission families
+Every manifest declares `permissions` with these families. Anything not declared is unavailable; declaring a permission never grants access the user has not authorized.
+
+| Family | Allowed values |
+| --- | --- |
+| project | Project scopes below (any runtime) |
+| capabilities | Exactly one hosted operation for `runtime: "capability"` (`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`), or `comfyui.execute` for `runtime: "comfyui"`. See [runtime capabilities](capabilities.md). |
+| actions | Portable media actions below, for `runtime: "javascript"` or `"module"` |
+| desktop | Desktop permissions below, used through the host desktop bridge |
+| network | For `runtime: "module"`: up to 8 exact https origins the Block calls with `stillmade.net.fetch` (and opens live WebSockets to with `stillmade.net.connect`, at their `wss://` form), each optionally with the key it needs (`{origin, auth: {scheme: "bearer" \| "header" \| "query" \| "oauth2", name or app, label, help}}`). People add their own key or sign in once per Block; the host adds it on its servers. Other runtimes: empty. See [Outside APIs](../build/outside-apis.md). |
+| connections | For `runtime: "module"`: up to 8 published adapters by app ID (`app:openapi:notion`), called with `stillmade.connections.call`. Other runtimes: empty. |
+| filesystem, secrets | Must be empty arrays. Blocks have no ambient file or secret access; keys come from the people running the Block, through declared network access. |
+
+## Project scopes
+| Scope | Grants |
+| --- | --- |
+| `context.script.read` | Read the project's script as `script` through a declared `context` input. |
+| `context.transcript.read` | Read the project's transcript as `transcript` through a declared `context` input. |
+| `context.shots.read` | Read the project's shots as `shot[]` through a declared `context` input. |
+| `context.shotPlan.read` | Read the project's shotPlan as `shot-plan` through a declared `context` input. |
+| `context.scenes.read` | Read the project's scenes as `scene[]` through a declared `context` input. |
+| `context.characters.read` | Read the project's characters as `character[]` through a declared `context` input. |
+| `context.locations.read` | Read the project's locations as `location[]` through a declared `context` input. |
+| `context.styles.read` | Read the project's styles as `style[]` through a declared `context` input. |
+| `context.assets.read` | Read the project's assets as `asset[]` through a declared `context` input. |
+| `context.files.read` | Read the project's files as `file[]` through a declared `context` input. |
+| `context.generations.read` | Read the project's generations as `metadata[]` through a declared `context` input. |
+| `context.versions.read` | Read the project's versions as `metadata[]` through a declared `context` input. |
+| `context.timeline.read` | Read the project's timeline as `timeline` through a declared `context` input. |
+| `context.editor.read` | Read the project's editor as `timeline` through a declared `context` input. |
+| `context.canvas.read` | Read the project's canvas as `pipeline` through a declared `context` input. |
+| `context.blueprint.read` | Read the project's blueprint as `bible` through a declared `context` input. |
+| `context.panels.read` | Read the project's panels as `panel-document` through a declared `context` input. |
+| `context.board.read` | Read the project's board as `board-document` through a declared `context` input. |
+| `context.animation.read` | Read the project's animation as `scene-document` through a declared `context` input. |
+| `context.metadata.read` | Read the project's metadata as `metadata` through a declared `context` input. |
+| `asset.read` | Read authorized media references the host supplies through inputs or declared context; declaring it is not permission to any particular asset. |
+| `asset.create` | Module Blocks: add a saved image, video or audio file to the project's media as a new asset with `stillmade.assets.create`. Needs edit access to the project. |
+| `asset.version.append` | Module Blocks: add a saved file as the newest version of a project asset the Block received, read or created, keeping its history, with `stillmade.assets.appendVersion`. |
+| `project.read` | Module Blocks: read the project while running with `stillmade.project.read(fields)`, limited to the metadata and each field declared with `context.FIELD.read`. |
+| `project.patch` | Reserved. Accepted by the manifest validator; no host applies changes through it today. Use a `workspace.FIELD.propose` or `timeline.propose` proposal. |
+| `timeline.read` | Reserved. Accepted by the manifest validator; read the Editor timeline with `context.timeline.read`. |
+| `timeline.propose` | Propose a strict timeline edit (`timeline-edit` output). Requires `context.timeline.read`; the user previews and applies it. |
+| `workspace.animation.propose` | Propose a `workspace-edit` to the animation workspace. Requires the matching `context.animation.read`; the user previews and applies it. |
+| `workspace.canvas.propose` | Propose a `workspace-edit` to the canvas workspace. Requires the matching `context.canvas.read`; the user previews and applies it. |
+| `workspace.blueprint.propose` | Propose a `workspace-edit` to the blueprint workspace. Requires the matching `context.blueprint.read`; the user previews and applies it. |
+| `workspace.shotPlan.propose` | Propose a `workspace-edit` to the shotPlan workspace. Requires the matching `context.shotPlan.read`; the user previews and applies it. |
+| `workspace.panels.propose` | Propose a `workspace-edit` to the panels workspace. Requires the matching `context.panels.read`; the user previews and applies it. |
+| `workspace.board.propose` | Propose a `workspace-edit` to the board workspace. Requires the matching `context.board.read`; the user previews and applies it. |
+| `workspace.editor.propose` | Propose a `workspace-edit` to the editor workspace. Requires the matching `context.editor.read`; the user previews and applies it. |
+| `state.step` | Keep persistent per-Step state for a JavaScript Block that declares `manifest.state`. |
+| `work.shared` | Run shared background work (`sharedWork`) that every collaborator in the project sees. |
+
+## Portable media actions
+A JavaScript Block returns a `{schemaVersion: 1, kind: "stillmade.media-action", operation, request, resultPort}` value for an action it declared; the host validates and performs it.
+
+| Action | Performs |
+| --- | --- |
+| `final.render` | Ask the host to render the project timeline to a final video. |
+| `stock.search` | Search approved stock photos, videos or audio by query. |
+| `presenter.generate` | Generate presenter poses for a board from a prompt and its voiceover. |
+| `quality.analyze` | Analyze up to 16 owned images for production quality. |
+| `image.generate` | Generate one image from a bounded visual prompt through the host. |
+| `image.generate.batch` | Generate up to 100 panel images from prompts in one aspect ratio, pinned to the requesting Block version. |
+| `media.generate` | Generate up to 50 images, videos, voice recordings, music tracks or sound effects with any StillMade catalog model, voice and settings (aspect ratio, resolution, quality, duration, sound, seed, reference images, first and last frames, voice, speed, length), paid with the user's StillMade credits after they approve one maximum for the batch. |
+| `youtube.upload` | Upload an owned video to the owner's connected YouTube channel with title, description, tags, visibility, schedule and disclosure fields. |
+
+## Desktop permissions
+| Permission | Allows |
+| --- | --- |
+| `screen.capture` | Choose a screen or window, then record it. |
+| `cursor.track` | Global cursor coordinates and display geometry; no click or keyboard monitoring. |
+| `camera.capture` | Camera recording, or the live camera feed (`StillMade.live`), after device and OS approval. |
+| `microphone.capture` | Microphone recording, or the live microphone feed (`StillMade.live`), after device and OS approval. |
+| `clipboard.read` | Read clipboard text, bounded to 100,000 characters. |
+| `clipboard.write` | Replace clipboard text. |
+| `media.pick` | Native picker for up to 20 media files; no arbitrary path access. |
+| `notifications.show` | A Block-branded desktop notification, at most one every ten seconds. |
+| `power.keep-awake` | Keep the app from suspending until disabled, revoked, closed or expired. |
+| `native.tools` | Use one exact versioned adapter for an approved installed desktop application. |
+| `folder.read` | List and read files in a folder the person picks (StillMade Desktop, Chrome and Edge); the Block sees an opaque folder id and relative paths only, and the folder is remembered for the Block where it is used. |
+| `folder.write` | Create and replace files in a folder the person shared for changing (declare folder.read too). |
+
+Details and request shapes: [desktop capabilities](desktop-capabilities.md).

package/docs/reference/ports.md

@@ -0,0 +1,26 @@
+# Port fields
+
+## Port fields
+Each input and output is a named port (a lowercase letter, then letters, numbers or underscores). Admission rejects any other field.
+
+| Field | Meaning |
+| --- | --- |
+| `type` | Required. A shared StillMade type such as `text`, `image`, `shot-plan`; add `[]` for a list (`image[]`). |
+| `required` | Required on every input of a new Block: `true` or `false`. A required input needs a generated control, a `context` binding or a `default`, or `pack` and import reject it. |
+| `default` | A JSON value matching the type. Satisfies a required input when nothing else supplies it. |
+| `min` | Lowest allowed value for a `number` or `integer` port. |
+| `max` | Highest allowed value for a `number` or `integer` port. |
+| `description` | Required on every input and output of a new Block. One short plain-language sentence about what the value is for. |
+| `role` | Legacy distinct role (for example `character_reference`). Use only when the meaning must not mix with others; downstream roles must match exactly. Prefer `semantic`. |
+| `primary` | Mark exactly one main input and one main output `true`; Project Type Steps connect primary ports automatically. |
+| `context` | The project field this input reads (for example `script`); requires the matching `context.FIELD.read` permission. |
+| `imageMode` | JavaScript image inputs only: `pixels` delivers decoded `{width,height,data}`; `reference` delivers the media reference without pixels. |
+| `key` | Set by the host for resolver requirements. Leave unset in manifests. |
+| `semantic` | Required on every input and output of a new Block. The exact meaning in lowercase snake_case or dotted form (`company_profile`, `production_shot_plan`). Downstream matching uses it; different meanings never connect. |
+| `accepts` | Additional meanings this input also accepts, besides its own `semantic`. |
+| `schema` | Required on every `json` or `object` port (admission rejects one without it). Not JSON Schema: a field-type word or a map of field names to field-type words, nested for objects. Words are `string`, `text`, `number`, `integer`, `boolean`, `object`, `json`; add `[]` for a list and `?` for an optional field, for example `{title:"string",tags:"string[]?",size:{width:"integer",height:"integer"}}`. |
+| `sources` | Where the universal resolver may fill this input from: `upstream`, `project`, `adapter`, `chat`, `default`, `user`, `external`. Omit to allow all. `default` covers only the declared default; values a person enters in the Step or a view passes to `StillMade.run` count as `user`, so leave `user` allowed for anything the interface fills in. |
+| `sensitivity` | A label for sensitive information; values marked secret, credential, password or token are never offered in chat. |
+| `freshnessPolicy` | `{maxAgeMs}`: the resolver rejects values older than this. |
+| `cardinality` | `one` or `many` values. |
+| `batchable` | `true` when the input can run once per item of a selected media batch. |

package/docs/reference/types.md

@@ -0,0 +1,268 @@
+# Types and compatibility
+
+## Supported types
+- `text`
+- `number`
+- `integer`
+- `boolean`
+- `json`
+- `object`
+- `image`
+- `video`
+- `audio`
+- `asset`
+- `script`
+- `transcript`
+- `brief`
+- `bible`
+- `shot-plan`
+- `panel-document`
+- `board-document`
+- `scene-document`
+- `timeline`
+- `timeline-edit`
+- `file-bundle`
+- `workspace-edit`
+- `timeline-range`
+- `research`
+- `character`
+- `location`
+- `style`
+- `pipeline`
+- `approval`
+- `scene`
+- `shot`
+- `mask`
+- `depth`
+- `pose`
+- `metadata`
+- `project-context`
+- `file`
+- `document`
+- `table`
+- `url`
+- `date`
+- `color`
+Any listed type can use an array suffix, for example `shot[]` or `image[]`.
+
+## Runtime values
+| Type family | Value |
+| --- | --- |
+| text | A string up to 1,000,000 characters |
+| number / integer | A finite number, with integer and bounds checks as declared |
+| boolean | true or false |
+| json | Safe finite JSON data |
+| image | Portable media reference or bounded RGBA image |
+| video / audio / asset | Portable media reference |
+| file-bundle | Validated file or ZIP download data; media requires host authorization |
+| Production documents | JSON object with schemaVersion: 1 |
+| Arrays | Array whose members match the base type |
+
+A media reference is `{assetId, versionId, kind}`. A decoded image is `{width, height, data}`, with width × height × 4 integer RGBA channels. The current pixel ceiling is 1,048,576.
+
+## Compatibility rules
+The raw `compatible` check requires exact type matching except **integer → number**. Arrays match their full declared type. If an input declares a semantic role, its producer must declare the same role. The host connection registry can additionally apply the guarded conversions below.
+```js
+compatible({type: 'image', role: 'source_image'},
+           {type: 'image', role: 'source_image'});
+// { compatible: true, adapter: null }
+```
+
+## Primary ports
+Declare one primary input and output for automatic insertion. A sole port is inferred for older packages. Multiple candidates without a declared primary do not produce an arbitrary connection.
+
+## How a project flags connection problems
+Every surface that shows a project's Blocks (the step rail, Flow cards, the Flow map and Canvas nodes) reads one classifier, `placementAttention` in `packages/block-platform/placement-attention.js`. It only explains states the flow inspection already proved; it never changes what may run. Order suggestions keep their own marker between the two Blocks and do not color either Block.
+
+| Glow | Meaning | Causes |
+| --- | --- | --- |
+| Red | Needs a fix before it can run correctly | Last run failed; result wasn't saved; Block unavailable; Blocks disagree on a contract or depend on each other; a connection points to a missing Block or input; a chosen source stopped working (pinned version gone, saved setting in the wrong format, two Canvas sources for one input); an input requires project information but allows no project source |
+| Yellow | Can continue once the person answers, reviews or reruns | A required input has no source yet; an unlabeled connection needs review; a schedule needs the owner to enable it; an earlier Block changed, so the result is outdated |
+| None | Normal sequencing | Waiting for an earlier Block, working, paused, skipped by a condition, private, finished, or Flow details unavailable |
+
+What authors control:
+- Give every port a `semantic`. A connection whose ports carry no meaning stays yellow until a person reviews it.
+- Mark settings with safe defaults `required: false`. Each required input without a source keeps the Block yellow until it is answered.
+- Allow the sources an input can really use (`user`, `chat`, `project`). A required input that needs project information but allows no project source is red.
+- Return outputs that match their declared type. A mismatched output fails the run, which turns the Block red.
+
+## Safe connection conversions
+StillMade can insert a versioned, deterministic conversion between compatible
+Steps. This is part of the host connection contract; it does not add a visible
+Step or ask the user to wire ports. Advanced connection controls show the
+conversion and preserve its version when the Project Type is saved.
+
+`compatible(outputPort, inputPort)` remains the strict raw-value check: exact
+types and matching required roles, with the existing integer-to-number widening.
+Use `connectionCompatibility(outputPort, inputPort)` to discover a supported
+connection conversion. Pass the complete port objects, including `role`.
+`validateConnectionAdapter(outputPort, inputPort, {permissions, adapter})` also
+checks the receiving Block's `manifest.permissions.project` grants and the saved
+adapter pin. Static compatibility is a possibility, not a promise that any value
+can run: the actual output and authorized context must pass runtime validation.
+
+| Conversion | What the host accepts | Receiving Block permissions |
+| --- | --- | --- |
+| integer → number | A valid whole number, preserving its value | None |
+| image / video / audio → asset | A saved media reference of that kind | None |
+| asset → image / video / audio | A media reference whose actual `kind` matches the requested type | None |
+| scene → shot[] | The scene's authorized shots, in its recorded project order | `context.scenes.read`, `context.shots.read` |
+| shot → image | That shot's unambiguous, current, host-selected image, present in authorized project assets | `context.shots.read`, `context.assets.read` |
+
+The conversion IDs are `integer-to-number`, `image-to-asset`, `video-to-asset`,
+`audio-to-asset`, `asset-to-image`, `asset-to-video`, `asset-to-audio`,
+`scene-to-shots`, and `shot-to-selected-image`. Each is currently version `1`.
+New cross-type Project Type connections must include the exact pin:
+
+```json
+{
+  "from": { "stage": "source", "port": "asset" },
+  "to": { "stage": "process", "port": "image" },
+  "adapter": { "id": "asset-to-image", "version": 1 }
+}
+```
+
+The builder adds this metadata automatically. Existing direct and
+integer-to-number connections remain valid without an explicit pin. Changing a
+pin changes the workflow identity and invalidates connected-run and automation
+reviews. The host uses `adaptConnectionValue(outputPort, inputPort, value,
+{context, permissions, adapter})` before validating the receiving input; a
+conversion returns copied data and cannot modify the project.
+
+Roles are preserved, never invented: a `character_reference` image cannot become
+a `source_image`. Scene and shot conversions use scoped host context rather than
+trusting a Block's embedded shot list or selected-image claim. Missing,
+ambiguous, stale or unauthorized selections stop the run. StillMade does not
+choose the first image or fall back to a historical version. Inline RGBA pixels
+must be saved as a media reference before a media-to-asset conversion. No
+conversion here downloads, decodes, generates, or uploads media. Video-to-audio,
+video-to-frames, model inference and other semantic transformations still require
+an explicit supported capability and its own execution permissions.
+
+Additional shared types include `scene`, `shot`, `shot[]`, `mask`, `depth`, `pose`,
+`metadata` and `project-context`. Their current values are versioned JSON documents
+(`schemaVersion: 1`); declaring a context port does not grant project access.
+Scoped context and conditional/batch execution are available for supported SDK
+Blocks. ComfyUI uses the explicit account connection and review described below;
+unattended remote automation and additional media adapters remain separate work.
+
+## Context bindings
+| Field | Exact type |
+| --- | --- |
+| script | script |
+| transcript | transcript |
+| shots | shot[] |
+| shotPlan | shot-plan |
+| scenes | scene[] |
+| characters | character[] |
+| locations | location[] |
+| styles | style[] |
+| assets | asset[] |
+| files | file[] |
+| generations | metadata[] |
+| versions | metadata[] |
+| timeline | timeline |
+| editor | timeline |
+| canvas | pipeline |
+| blueprint | bible |
+| panels | panel-document |
+| board | board-document |
+| animation | scene-document |
+| metadata | metadata |
+
+## Downloadable Block results
+Declare an output with `type: "file-bundle"` (or `file-bundle[]`). The shared Block
+preview automatically offers Download, including when the Block has a custom
+view. A file result is inert data: it grants no filesystem access and never mounts
+HTML, runs code or triggers a download before the user clicks. This output type
+is separate from the file `pack` writes to install the Block itself.
+
+```json
+{
+  "schemaVersion": 1,
+  "format": "file",
+  "name": "notes.txt",
+  "files": [{"path": "notes.txt", "text": "My notes"}]
+}
+```
+
+For ZIP output use `format: "zip"`, a `.zip` name, and multiple files. Each member
+contains exactly `{path,text}` or `{path,source}`. A `source` retains the complete
+selected media reference (`kind`, `assetId`, `versionId`, `url`, and its existing
+role/metadata); never invent a reference or substitute a URL. Media entries need
+`asset.read` in `manifest.permissions.project` and an authorized selection from
+the host's existing media inputs or declared project context. Declaration alone
+is not permission. The host checks the full reference identity and current
+account/selection before transferring bytes. Detached history views can download
+text-only results; media ZIPs need the Block's current authorized media context.
+
+Source-project ZIPs may also contain bounded UTF-8 HTML, CSS, JavaScript,
+TypeScript, SVG and other common source text files as `{path,text}` members. The
+host treats those members as inert data, checks their paths and total size, and
+offers only the ZIP download after the normal export authorization. A single
+HTML or script file cannot be returned as `format: "file"`. Declare a useful
+semantic such as `web_source_project` so Revolver can connect the complete
+project to a compatible consumer. Binary files are not accepted as text members;
+use authorized media references where appropriate and do not omit required
+project files while claiming a complete export.
+For browser-application Blocks, `file-bundle` members must currently be
+text-only. The browser execution host rejects guest-supplied media references
+even when the manifest requests `asset.read`, because that request does not
+prove the current project selected the exact asset and version. Other Block
+runtimes retain their existing host-authorized media-bundle path.
+Unavailable, unselected or unsupported media aborts the ZIP instead of returning
+an archive with missing members. The host does not install dependencies.
+
+File downloads contain exactly one text member whose path equals `name`.
+Supported text suffixes: `.txt`, `.md`, `.json`, `.csv`, `.xml`, `.fcpxml`, `.srt`,
+`.vtt`. ZIP media suffixes: `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.mp4`,
+`.webm`, `.mov`, `.mp3`, `.wav`, `.ogg`, `.m4a`, `.flac`, `.bin`.
+Use safe relative ASCII paths, at most 180 characters, with no traversal,
+backslashes, empty segments, trailing dots, reserved device names or case
+collisions. Include 1–256 files and at most 3,000,000 UTF-8 text bytes total;
+the existing runtime JSON/memory limits also apply. Media transfers use the
+host limits above. Files are delivered as downloads with a non-executable MIME
+type; no archive member becomes a host filesystem path.
+
+`isFileBundle(value)` and the normal `validate`/`test`/`pack` commands enforce this
+contract. Include normal and edge fixtures containing the complete expected
+file data. The [File notes example](https://stillmade.shop/block-sdk/examples/file-notes.stillmade-block)
+is a complete portable package using this output. Import it, change the text,
+run it and click Download. No custom download code is needed in the Block view.
+
+## Original media file admission
+The SDK exports `MEDIA_IMPORT_FORMATS`, `MEDIA_IMPORT_MAX_BYTES` and
+`inspectMediaImportFile({name,size,type?})` for trusted hosts handling files the
+user selected. The inspector returns `{kind,extension}` and rejects unsupported
+extensions, conflicting MIME categories, empty/nonintegral sizes and files above
+50 MiB. It does not read file bytes, grant filesystem access or authorize an upload.
+
+Supported originals are PNG/JPG/JPEG/WebP/GIF images; MP4/MOV/WebM videos; and
+MP3/WAV/M4A/AAC/OGG audio. Each format specifies the canonical upload MIME type.
+An absent MIME type or `application/octet-stream` may use the recognized extension.
+The existing authenticated media upload endpoint uses the same table and limit,
+stores the bytes it is given through its signed PUT, and returns a durable media
+URL. Before that upload, the host may make a working copy of large media when
+the account's media setting is on (its default): images over 2048 px or 4 MiB
+become a 2048 px JPEG (PNG when transparent; GIF and SVG are left alone), audio
+over 25 MiB becomes 128 kbps MP3, and video over 1080p is re-encoded at 1080p
+where the device can. The working copy is then the saved value the Block
+receives, with its own `assetId`, `versionId` and URL; the original stays on the
+person's device, linked only on host records, and is never substituted at run
+time. A Block that needs the original asks the person, who can upload it from
+the input's "Use original" control. With the setting off, originals upload as is.
+With the account's local-first setting on (its default), a project Step keeps the
+file in the browser's own storage instead of uploading it: the value's `url` is a
+durable `sm-media://device/<assetId>/<sha256>` address, the Block reads it on
+that device, and the host uploads a copy once per version only when a hosted
+operation, Chat or sharing needs it.
+
+The host's existing Canvas upload adapter accepts optional `signal` and
+`assertCurrent` controls. The callback must throw when the owning session is no
+longer current; checks run before upload and before caching or returning results.
+Isolated previews retain local files without a cloud request. A file selected in
+a generic Block preview is still temporary unless a supported host persistence
+flow explicitly saves it; declaring `asset.create` alone does not upload it.
+
+These utilities extend the shared upload boundary. They are not a new guest file
+API or proof that the native Import media workspace is a portable sandbox Block.