stillmade-sdk 0.1.36 → 0.1.38

package/AGENTS.md

@@ -1,12 +1,12 @@
 # Building StillMade Blocks in this folder
 
-This folder is the StillMade Block SDK. Read this file before writing code; it is the same contract StillMade's own AI and importers follow. Commands below use the downloaded SDK folder form `node packages/block-cli/cli.js`; when the SDK came from `npm install --save-dev stillmade-sdk`, type `npx stillmade-block` in its place. Scaffold with `node packages/block-cli/cli.js create my-block javascript`, then iterate with `validate my-block` and `test my-block`, check admission with `pack my-block /tmp/my-block.stillmade-block --original`, and finish with `ready my-block`, the same readiness check StillMade runs before an install or a release. `SDK.md` is the complete reference and `PASTE_TO_LLM.md` the detailed authoring guide.
+This folder is the StillMade Block SDK. Read this file before writing code; it is the same contract StillMade's own AI and importers follow. Commands below use the downloaded SDK folder form `node packages/block-cli/cli.js`; when the SDK came from `npm install --save-dev stillmade-sdk`, type `npx stillmade-block` in its place. Scaffold with `node packages/block-cli/cli.js create my-block javascript`, then iterate with `validate my-block` and `test my-block`, check it with `gate my-block`, the same readiness check StillMade runs before an install or a release, and write the file to import in StillMade with `pack my-block`: `<id>-<version>.stillmade-module.json` for a module Block, `<id>-<version>.stillmade.json` for the other runtimes. `SDK.md` is the complete reference and `PASTE_TO_LLM.md` the detailed authoring guide.
 
 ## Readiness gate
 
-Do not tell the user a Block is ready, done or working until `node packages/block-cli/cli.js gate .` passes after your last edit, and report the exact status it prints. In this folder Claude Code (`.claude/settings.json`) and Cursor (`.cursor/hooks.json`) run the gate when you finish a turn and send any failures back to you, but only in a session started in this folder: if you downloaded the SDK during the current session, run the gate yourself. Other agents must also run it themselves. A module Block runs code, so the gate a hook starts does not run it and says so: run `gate` or `ready` on it yourself. If you cannot fix a failure, say plainly that the Block is not ready and list the failing checks.
+Do not tell the user a Block is ready, done or working until `node packages/block-cli/cli.js gate .` (`gate <block-folder>` for a Block outside this SDK folder) passes after your last edit, and report the exact status it prints. In this folder Claude Code (`.claude/settings.json`) and Cursor (`.cursor/hooks.json`) run the gate when you finish a turn and send any failures back to you, but only in a session started in this folder: if you downloaded the SDK during the current session, run the gate yourself. Other agents must also run it themselves. A module Block runs code, so the gate a hook starts does not run it and says so: run `gate` or `ready` on it yourself. If you cannot fix a failure, say plainly that the Block is not ready and list the failing checks.
 
-Contract `stillmade.block-builder@1.10.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.
+Contract `stillmade.block-builder@1.11.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
 
@@ -14,7 +14,7 @@ Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` con
 
 ## Reuse first
 
-Before building, check what already exists (`find_existing_blocks` over MCP, or the Marketplace and your library) by the inputs, results and operations the goal needs. Use an installed or reviewed Block that already does it; remix a close one so its license, notices and creator credit stay attached; chain existing Blocks and build only the missing step. Never republish another creator's source without remix lineage: public copies are refused. Build a new Block when nothing fits or the person asks for their own version, and say which similar Blocks you considered.
+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
 
@@ -28,11 +28,11 @@ Pick the runtime from the job. No hosted AI: a recipe or isolated `javascript`,
 
 A Step is one job: the work between two moments where a person or the outside world must see the result. Start a new Step only at one of three points; everything else is a part of the neighboring Step.
 
-1. **A person works with the result**: reads, edits, picks or approves it (a workspace Block such as a script, a Canvas or an Editor, or an approval). That is why Chat, Bible, Canvas and Editor are four Steps.
+1. **A person works with the result**: reads, edits, picks or approves it (a workspace Block such as a script, a Canvas or an Editor, or an approval). 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.
 
-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; neighbouring workspaces with one main result type are one Step unless another part feeds the second. A video ends in the Editor (1.0), which has captions and export built in, so Export video is never a Step beside it.
+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 video ends in the Editor (1.0), which has captions and export built in, so 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 the three 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.
 
@@ -46,7 +46,7 @@ Translate the request into an explicit capability contract before implementation
 
 ## 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[]`, ...), a `semantic` meaning on every port, `required` and a short `description`. 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()` (the same engine as the Project Type composer) resolves inputs from compatible upstream outputs, permitted project context and, for optional non-context inputs, `StillMade.requestFromUser`.
+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
 
@@ -66,7 +66,7 @@ Give the Block a short, plain name of 40 characters or fewer that says what it d
 
 ## 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 genuinely needs one. Build custom views from the Block kit the host injects (`block-kit.css`): the result in `sm-stage`, picks as pictures in `sm-choices`, one `sm-primary` naming the action (Write, Generate; never "Run") 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 (a video editor, a 3D configurator, a 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. Drop words nobody needs; put helpful ones in a closed `sm-hint`. Expose the capability, not the implementation: sensible defaults, previews, progress, clear errors, visible outputs. Do not show raw JSON, internal IDs, filesystem details, provider terminology or developer settings unless the Block is itself a developer tool. When a person chooses among options they need to hear or see (voices, music, sounds, fonts, looks, colors, templates or images), let them preview each option before choosing: a sample to play or a thumbnail, from the Block's own files or the host's free samples, never a paid generation. Leave previews out only when the builder states there is nothing to preview. Choices StillMade owns, such as voices and models in the run review, already show their samples. Follow the host appearance (Light, Dark and White) and one elastic layout: stacked on a 320px phone with no sideways scroll (result first, action pinned), 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.
+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`, picks as pictures in `sm-choices`, one `sm-primary` naming the action (Write, Generate; never "Run") 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. Drop words nobody needs; put helpful ones in a closed `sm-hint`. Mark each button `data-stillmade-action="what it does"` 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 (result first, action pinned), 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
 

package/IMAGE_DESCRIPTION.md

@@ -1,5 +1,7 @@
 Use `runtime: "capability"` with `operation: "image.describe"` when a Block must inspect one image and return plain text. This is the portable boundary for visual analysis: the Block declares its image input, analysis instructions, output, tests, and license; StillMade owns image loading, provider credentials, model/payment selection, approval, accounting, and the retained execution record.
 
+**StillMade credits do not pay for `image.describe`** (since September 13, 2026). A Block that calls it runs only for people who added their own OpenRouter key in Settings → API keys, and stops for everyone else. For a Block anyone can run on StillMade credits, use `media.analyze` instead (`stillmade-block create my-block analyze-media`): it takes one image or one to four images, answers one question about each, and is priced per image. The built-in Describe media 2.1.0 and Photo notes 1.1.0 moved to it; their earlier releases stay for projects pinned to them.
+
 The downloaded SDK includes `examples/describe-image.stillmade.json` and `packages/block-sdk/image-description-example.js`.
 
 ```json

package/MODULES.md

@@ -7,7 +7,9 @@ any npm package you bundle into it, including C and C++ libraries compiled to
 WebAssembly (OpenCV, libvips builds, codecs, solvers), threaded WebAssembly
 (see Threads) and live WebSocket connections to declared origins (see Live
 connections). Use it when a recipe or the QuickJS `javascript` runtime is too
-small for the job.
+small for the job. (StillMade's in-app builder writes `main.js` as one file that
+imports nothing and uses no browser APIs; that single-file rule is the builder's,
+not the runtime's. A module Block you build with the SDK can use all of this.)
 
 ## Folder layout
 
@@ -18,10 +20,14 @@ my-block/
     main.js                the entry (bundle npm dependencies into it)
     filters.wasm           optional WebAssembly and data files
   module.json              optional: {"entry": "other.js", "threads": true}
-  tests/fixtures.json      [{name, input, expected}]
+  tests/fixtures.json      [{name, input, expected, mocks?}]
 ```
 
-Start one with `stillmade-block create my-block module`. Bundle npm
+Start one with `stillmade-block create my-block module` (`module-hosted` for
+one that calls hosted operations). `stillmade-block` is the SDK's command line:
+`npx stillmade-block` with the npm package `stillmade-sdk`, or
+`node <sdk>/packages/block-cli/cli.js` where `<sdk>` is the extracted
+`/block-sdk/stillmade-sdk-0.1.0.zip`. Bundle npm
 dependencies into `module/main.js` with any ES module bundler (esbuild,
 rolldown, Vite). A module holds up to 64 files, 64 MiB each and 128 MiB in
 total.
@@ -51,8 +57,8 @@ against the manifest's port types.
 | `progress(value, label)` | Reports progress from 0 to 1 with a short label. Each report extends the run limit. |
 | `log(...values)` | Adds a line to the run log (up to 500 lines). |
 | `asset(path)` | A copy of one of the module's own files, such as a `.wasm` build, as an `ArrayBuffer`. |
-| `files.read(ref)` | The bytes of a saved image, video, audio or asset the Block received as input, or that StillMade made in this run: files it wrote, transform results and generated media. Media the person kept on their device (a `sm-media://device/...` address in a project Step) reads the same way, without leaving the device. Other files cannot be read, and transforms, hosted calls and actions accept only these references too; a hosted call or action gets a cloud copy of device media, made once per version. |
-| `files.write(data, {mediaType, name})` | Saves PNG, JPEG, WebP, GIF, MP4, WebM, MP3, WAV, M4A or OGG to the runner's library and returns a reference you can return as an output. At most 64 files per run. |
+| `files.read(ref)` | The bytes, as an `ArrayBuffer`, of a saved image, video, audio, asset or file (a PDF, text, CSV, Markdown or JSON file on a `file` input) the Block received as input, or that StillMade made in this run: files it wrote, transform results and generated media. Media the person kept on their device (a `sm-media://device/...` address in a project Step) reads the same way, without leaving the device. Other files cannot be read, and transforms, hosted calls and actions accept only these references too; a hosted call or action gets a cloud copy of device media, made once per version. |
+| `files.write(data, {mediaType, name})` | Saves PNG, JPEG, WebP, GIF, MP4, WebM, MP3, WAV, M4A or OGG media, or a PDF, TXT, CSV, Markdown, JSON or ZIP file (`application/pdf`, `text/plain`, `text/csv`, `text/markdown`, `application/json`, `application/zip`; a `{kind: 'file'}` reference), to the runner's library and returns a reference you can return as an output. At most 64 files per run. |
 | `media.transform(request)` | On-device media work done by StillMade: decode audio to samples, extract or loudness-normalise audio, cut, join or re-encode video, and take thumbnails. Results are saved like `files.write`. See [Media processing](#media-processing). |
 | `actions.run(action)` | Runs a declared portable action. `media.generate` asks the person to approve one StillMade credit maximum for the batch; `stock.search` runs directly. |
 | `hosted.run(operation, request)` | Calls a hosted operation the manifest lists in `permissions.capabilities` (for example `text.generate`, `image.generate`, `audio.speech`, `web.research`). Each call is quoted and approved like a capability Block and paid with StillMade credits. |
@@ -71,7 +77,10 @@ const voice = await stillmade.hosted.run('audio.speech', { text: plan.script, se
 ```
 
 `image.describe`, `media.analyze` and `audio.transcribe` take saved references
-(`image`/`images`, `media`, `audio`); `web.fetch` takes `url` and `instruction`;
+(`image`/`images`, `media`, `audio`); `image.generate` takes `prompt` and optional
+`references`, one to eight saved images the new picture keeps. Look at pictures with `media.analyze`:
+StillMade credits pay for it, while `image.describe` runs only on the person's
+own OpenRouter key. `web.fetch` takes `url` and `instruction`;
 `web.research` takes `topic`; music and sound effects take `prompt` and
 `durationSec`.
 
@@ -94,6 +103,8 @@ to the next transform.
 | `{operation: 'video.concat', sources, settings?}` | A saved MP4 of 2 to 50 videos in order. |
 | `{operation: 'video.resize', source, settings}` | A saved MP4 re-encoded with new settings. |
 | `{operation: 'image.thumbnail', source, at?, width?}` | A saved PNG of one frame (default the first frame, 1280 px wide). |
+| `{operation: 'document.text', source}` | `{text, pages}`: the words of a PDF or text file the person gave, page by page (up to 500 pages). |
+| `{operation: 'image.compose', width, height, layers, background?, format?, text?}` | A saved PNG (or JPEG) of saved images joined into one picture: side by side, a grid, a contact sheet, a poster with a title. |
 | `{operation: 'timeline.render', clips, kind?, aspect?, audio?, captions?, settings?}` | A saved MP4 (or, with `kind: 'audio'`, an MP3) of your own timeline, rendered the way the Editor exports. |
 
 `timeline.render` is how a Block exports: there is no separate Export, Captions,
@@ -102,19 +113,40 @@ from?, transition?: {type, duration?}, look?, mute?}` (a saved image or video; a
 video keeps its own sound unless `mute`), each audio item `{source, start,
 duration, from?, volume?}`, and each caption `{text, start, end, words?,
 position?, highlight?, animation?}`, where `words` (`[{text, start, end}]`)
-highlights each word as it is spoken. Times are seconds on the timeline.
+highlights each word as it is spoken. Times are seconds on the timeline: each
+clip starts where the one before it ends, less the transition on that earlier
+clip, which blends it into the next one; clips that overlap more are refused.
 `aspect` is `16:9`, `9:16`, `1:1` or `4:5`. Looks, transitions and caption
 animations use the Editor's names (`TIMELINE_LOOKS`, `TIMELINE_TRANSITIONS`,
 `CAPTION_ANIMATIONS`). The render follows the person's export plan, like any
 export from StillMade.
 
+`image.compose` draws on a canvas `width` by `height` pixels (16 to 4096),
+filled with `background` (`#rrggbb`, default white). Each layer is `{source, x,
+y, width, height, fit?}`: a saved image placed in that box, in order, cropped
+to fill it (`fit: 'cover'`, the default) or fitted whole inside it (`'contain'`).
+Each piece of text is `{text, x, y, size?, color?, background?, align?,
+weight?, width?}`, drawn on top: `y` is the top of the line, `size` is 8 to 400
+pixels (default 48), `color` defaults to black, `background` puts a box behind it
+(for a Before label over a photo; `color` and `background` are `#rrggbb`, or `#rrggbbaa`
+or `rgba()` for a see-through box such as `#00000099`), `align` is `left`, `center` or `right` around
+`x`, and `weight` is `bold` (default) or `normal`. `width` wraps the words onto
+lines no wider than it, 1.2 times `size` apart, breaking a word wider than a line
+(or a caption with no spaces) between its characters: give a caption under a
+frame the frame's width so it never runs into the next one. Up to 64 layers and 64 pieces of
+text; `format` is `png` (default) or `jpeg`. A grid is arithmetic in your code:
+for 9 photos on a 1800 by 1800 sheet, three columns of 600 pixels.
+
 `source`/`sources` are saved references (`{kind, assetId, versionId, url}`).
 Render `settings` are `{fps: 24|30|60, resolution: 720|1080|2160, quality:
 'low'|'medium'|'high'}`; the default is 30 fps, 1080, high. Video keeps the
 source's aspect ratio. Rendering follows the person's export plan, like any
 export.
 
-Pure helpers ship as `@stillmade/block-sdk/media` for you to bundle:
+Pure helpers ship as `@stillmade/block-sdk/media` for you to bundle (the file is
+`stillmade-sdk/packages/block-sdk/media-transform.js` in the npm package and
+`<sdk>/packages/block-sdk/media-transform.js` in the extracted download; alias
+the name in your bundler or import that path):
 `silentRanges(samples, sampleRate, {thresholdDb, minSilence})`,
 `keepRanges(silent, duration, {padding})`, `integratedLoudness(channels,
 sampleRate)` (ITU-R BS.1770), `loudnessGain`, `encodeWav` and `decodeWav`.
@@ -216,13 +248,37 @@ false and `SharedArrayBuffer` is missing, so check it and fall back to one threa
 ```sh
 stillmade-block test my-block          # runs fixtures in a local Node worker
 stillmade-block preview my-block input.json
+stillmade-block dev my-block           # the interface in your browser, reloaded on save
+stillmade-block gate my-block          # StillMade's readiness check
 stillmade-block pack my-block          # writes <id>-<version>.stillmade-module.json
 ```
 
+`dev` serves the Block's real controls or view at `http://127.0.0.1:4800`
+(`--port` picks another) and answers hosted calls with stand-ins, never credits.
+The Block is not ready until `gate` passes. Name the Block's own folder: `gate .`
+in a folder that also holds the extracted SDK checks the SDK's examples too.
+`pack my-block` is the only packing step for a module Block, and it never takes
+`--original` (original `.stillmade-block` archives hold recipe, JavaScript,
+capability and ComfyUI source only and refuse a module Block).
+
 `test` and `preview` run your code on your machine in a disposable Node worker
 with the same host API and run limits (not a security sandbox; it is your own
 code). `files.read`, `files.write`, `media.transform`, actions and hosted calls need StillMade, or
-a host you pass to `createNodeModuleExecutor` in your own tests.
+a host you pass to `createNodeModuleExecutor` in your own tests. The Node worker has no
+`OffscreenCanvas` or `createImageBitmap`: a Block that decodes or draws images there
+needs its own fallback for tests, or tests only what it does without drawing.
+
+A fixture's `files` mock is a path inside the Block folder (local runs only: it does not
+travel in the pack), `{"text": "..."}` for a text file, or `{"base64": "..."}` for a small
+binary file (at most 256 KB), which travels in the pack and the import review. Text can
+never hold a NUL character (`\u0000`): StillMade cannot store it, and import refuses it.
+
+A fixture's photo, recording, clip or file can be one of StillMade's example files,
+named by address: `/api/media/example/photo-1.jpg` to `photo-4.jpg`, `sheet.png`,
+`room.png`, `kitchen.wav`, `hall.wav`, `click-120.wav`, `audio.mp3`, `clip.mp4`,
+`notes.txt` and `sales.csv` (sizes in PASTE_TO_LLM.md). `test` reads their real bytes
+when the fixture gives no mock for them, and StillMade, its preview and its phone and
+browser check serve the same files, so the example a person sees is the one you tested.
 
 A fixture can record what the host answers, so a test of a Block that calls
 hosted operations costs nothing and gives the same result every run:
@@ -243,7 +299,9 @@ hosted operations costs nothing and gives the same result every run:
 
 `mocks` has the shape of `tests/mocks.json` (`hosted`, `transforms`, `actions`,
 `files`, `storage`, `project`, `connections`, `network`); a list answers
-successive calls in order. A fixture's own `mocks` take the place of
+successive calls in order. `files` maps an input's asset ID to a file in the Block
+folder, or to `{"text": "..."}` for a text file, so a Block that reads a notes or
+CSV file the person gives it is tested without a folder (StillMade's builder has none). A fixture's own `mocks` take the place of
 `tests/mocks.json` for that fixture. StillMade's own builder writes module
 Blocks the same way and runs their tests before anyone sees them.
 

package/NATIVE_MCP.md

@@ -126,13 +126,24 @@ known, the inputs it starts from and the results it must produce. It searches
 reviewed Marketplace listings, tested Community Blocks, built-ins and, for a
 connection that may read creations (`creations:read`), the person's own drafts
 and private Blocks, by function and name, with no model, provider or credit
-cost, and returns one outcome:
-
-- `use` or `use-own`: an existing Block already does it; offer it instead of building.
-- `remix`: a close Block allows an attributed remix. `begin_block_remix` creates a
-  private draft from that exact version, with its license, notices and creator
-  credit; retrying the same `requestId` returns the same draft.
-- `compose` or `build-gap`: existing Blocks chain together; build only the missing step.
+cost, and returns one outcome with a confidence. Only confidence `likely` (the
+Block's name and description cover the goal) or `verified-contract` (its declared
+inputs and results match by meaning) means existing Blocks already do the job.
+`partial` means a close Block, not one that does the job: the client shows it as a
+close Block the person can open and keeps building unless they choose it.
+
+- `use` or `use-own` (likely or verified-contract): an existing Block already does
+  it; offer it instead of building. `use-own` with confidence `partial` is the
+  person's own close Block: show it, and keep building.
+- `remix` (partial): a close Block allows an attributed remix. `begin_block_remix`
+  creates a private draft from that exact version, with its license, notices and
+  creator credit; retrying the same `requestId` returns the same draft. Offer it
+  beside the build.
+- `compose` (verified-contract): two existing Blocks chained by declared meanings
+  do it; offer them in order. Blocks that only share a kind of value (text into
+  text) are never composed.
+- `build-gap` (partial): a Block makes the results but needs an input the person
+  does not have; they can build only that missing step in front of it.
 - `build`: nothing close exists, or the person wants their own version.
 
 `validate_block_source` and `save_creation` also list up to three similar existing