stillmade-sdk 0.1.42 → 0.1.44

package/.stillmade/sdk-baseline.json

@@ -5,7 +5,7 @@
   "examples/camera-recorder.stillmade.json": "8d8224b319e94e4afec3551445404ae99eae8c4d6df176ca7538bb0472f426b6",
   "examples/caption-from-text.stillmade.json": "3731a15b59043fbebee98416f2474800ef0154aa7873fb494934874ddcd2c705",
   "examples/captions.stillmade-block": "b0fde32dddaf866f3e540018309aaa00ae56b0e74a53a498fbaf1553ce200bd6",
-  "examples/check-clip.stillmade.json": "f5abf67d5d5e46896af1b323abbc9e83e3936c4d35f900f763115ca9e07966b2",
+  "examples/check-clip.stillmade.json": "1b666fc62b327d49ad6d35240ba3a7718d1f19bede9762e8eb41d8eb0ae7efc7",
   "examples/clean-text.stillmade.json": "973a688879d51f7cf6c86c3a0698b68489e20946a7d28d234944f22548d24ed3",
   "examples/comfy-invert.stillmade.json": "126bd3a8a88e14c08ae11c62a441ed099d83e16830e2062f936e14e56cb297eb",
   "examples/comfy-text-to-image.stillmade.json": "957a616887115984c1888cf9c0eee2fe771dcbf041166ad112fb6c3feb7ad4dd",
@@ -22,7 +22,7 @@
   "examples/export-timeline.stillmade-block": "7d3221dc3ec1491f420773edb0ad8612c650755111e1e8561510b68508976199",
   "examples/foley-cue.stillmade.json": "b579a73066cf65f6da2fba48c1965af83bc4325890643470229fd1c842470fc7",
   "examples/generate-image.stillmade.json": "81feffcda94f6e9f3c5c503d83e0ca6ffa5cefa118e44f4a3751d2a925ca9680",
-  "examples/generate-video.stillmade.json": "01f1404219d0f500ebe06b9ddd1af280cb726aecb0c6aa11f6d94e9fc21f8267",
+  "examples/generate-video.stillmade.json": "bc860d8e84dd9b1a179f516609ad0e101e467c3b9e08844b2add8cf6bb0813eb",
   "examples/grayscale.stillmade.json": "8c901790c25d2544f284a6a43341f72aa6b7e9211bef272b2e1d53c92b9e5faf",
   "examples/import-media.stillmade-block": "e9642e203080f1a145bec81871525a670f98dd1c8763862f81ab876fb15a656b",
   "examples/javascript-cloze-quiz": "b36a370c8b53250b9bb04783591661268ec674052bc13bf8cc8910fa27151f83",
@@ -45,20 +45,18 @@
   "examples/portable-regexp.stillmade-block": "04975bba1c0d719044ee41d6e0c58d73671c347f6b4ac16ba665bf5410116535",
   "examples/portable-regexp.stillmade.json": "fd769d584a6437e2a37c7e4101a031c0fef740afc76ef91f2337e2956fb08a1a",
   "examples/quieter-clips.stillmade.json": "23b026b267e5da522cc6a3a6af51e166a64fcc1d5391e855704fe1e1f243401b",
-  "examples/research-topic.stillmade.json": "50e8efb4ac81b165b17610e0fb7b2621b85ff9a14ebf2e045f30413246501b69",
-  "examples/saas-product-launch-reviewed-source.stillmade.json": "2ec264a160faba338f3924965f935ce92c3fdad1fb69719921d7561353b010ab",
-  "examples/saas-product-launch.stillmade.json": "aabec7d8680ef6687980296ab170bbb002c0dc81bc15edebdf9db9750e43eddb",
+  "examples/research-topic.stillmade.json": "2ae52cdb416ea2a9d19a0dd187433d415d9361a068382b279b71af9064b1bf60",
   "examples/scene-shots.stillmade.json": "d10a0aebb42ff090035410dc92ab708ffaf50b579edac4aa2f2cf6150b3ef537",
   "examples/score-a-scene.stillmade.json": "6059f2f65c48309f0c1711dbb6b5ee62a957ce07502a936f53b29685b425f8ec",
   "examples/screen-recorder.stillmade.json": "f3509a577cdd6615d6687ed0be108ddef51bf1f79ff0e2176470e46c3054640d",
   "examples/script-draft.stillmade.json": "3e8fc6e164c7b02f5f07ceb9771159e88252d405fa96a19107427e85c0457608",
   "examples/shot-readiness.stillmade.json": "ed73fe9038afaed7c12435368e90001f0bd3cebd8f0e6fe06508c1bb80c8cb7e",
   "examples/summarize-page.stillmade.json": "21f8be251733d1c236328f23fa0da6b4e5381d34374489926db61bdd54f3b75f",
-  "examples/text-workflow.stillmade.json": "286c2235cfc88d537556b94ee5735a05f2b790a0fb772014773ac7cf096ba455",
+  "examples/text-workflow.stillmade.json": "1e3affc58719df116dd09ee3357faba5d90b22dceb6e38551e78a7a3291f8c7f",
   "examples/thicken-lines.stillmade.json": "287c872d44a18b8c7f79fb2d4047c78a54c1f2b315bd6ce4c1340d4e54d87dac",
   "examples/timeline-mixer.stillmade.json": "93220984a88ca553dcf7102ce82b23d16eadda07809a89222a8589506743b5f8",
-  "examples/timeline-polish.stillmade.json": "478398bae41271424b4bd3cfa03d704df515b12370f81052fbde463f48b01471",
-  "examples/transcribe-audio.stillmade.json": "a03b5fcd620b3a386c2c713239f026392ce4f1484a9c38c5bb9943e2eb6c4f1a",
+  "examples/timeline-polish.stillmade.json": "6d4c62456bc1a3a4d198214f8029256c6532013d4dabb0be8445b209a42f760b",
+  "examples/transcribe-audio.stillmade.json": "62bb4365c24d17a64465bebc2504d4eda3c0498201e86f75c2e8e635fc40be14",
   "examples/view-react-chart": "a0e7ef5148e386b34e405187761d23f1739809c3d72c68c7c6b4e2193747218e",
   "examples/word-count.stillmade.json": "b815282e2dcd2827952e4a8bde403c5935141a98b9d54ee055da2b9d55cb43eb"
  }

package/AGENTS.md

@@ -26,19 +26,20 @@ Pick the runtime from the job. No hosted AI: a recipe or isolated `javascript`,
 
 ## 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. Start a new Step only at one of three points; everything else is a part of the neighboring 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**: 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.
+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 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 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 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.
+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: "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".
+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
 
@@ -66,7 +67,7 @@ Give the Block a short, plain name of 40 characters or fewer that says what it d
 
 ## 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 for an input. 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.
+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
 
@@ -74,7 +75,7 @@ These are StillMade's defaults: unless the person or the creator asked for somet
 
 ## 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`, 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="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.
+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
 
@@ -82,11 +83,11 @@ Projects are multiplayer. A custom view subscribes through `StillMade.onShared(c
 
 ## 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 typed outcomes the Block reports, not crashes. 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.
+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`. 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.
+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
 
@@ -152,4 +153,8 @@ A Block is done only when every applicable item holds. Passing a compile, one un
 - C: Missing generic platform primitive
 - D: Security or permission restriction
 - E: Runtime or language incompatibility
-- F: Fundamentally incompatible capability
+- F: Fundamentally incompatible capability
+
+## Guides in this folder
+
+Every guide on the StillMade site is in `docs/` here as Markdown, so you can read them offline: a link to `/docs/<path>` (in `SDK.md`, `PASTE_TO_LLM.md` or anywhere else) is the file `docs/<path>.md`, and `/docs` itself is `docs/index.md`. Start with `docs/build/quickstart.md` for a Block and `docs/project-types/build.md` for a Project Type, which also says how a Type embeds module Blocks. `docs/reference/cli.md` lists every command, `docs/reference/generation-models.md` the hosted models and `docs/reference/limits.md` the limits.

package/FRAME_VIEWS.md

@@ -51,6 +51,87 @@ Shared state works as in every view: keep each independently edited value in
 its own field (for example `point0`, `point1`) so two people editing
 different values never conflict.
 
+## Adding files to an input
+
+A one-page Block shows its input's files on its own screen as tiles and adds
+more there. Never draw an upload box or an `<input type="file">` of your own:
+the + tile asks StillMade, which opens its own file picker and saves the
+files exactly as the Step's own tiles do (working copies, files kept on the
+person's device, the limits and the error messages).
+
+```html
+<ul class="sm-gallery" data-size="small" id="photos">
+  <!-- one <li> per photo, drawn from onInput -->
+  <li><button type="button" class="sm-add" data-stillmade-add="listingPhotos"
+      aria-label="Add photos" title="Add photos"></button></li>
+</ul>
+```
+
+`data-stillmade-add` names a declared `image`, `video`, `audio`, `asset` or
+`file` input, or a list of one of them (`image[]`). It needs no code: a click
+or key press on the tile opens StillMade's picker. A list gets every chosen
+file added; a single input takes the first. The saved values reach the view
+the way every input does, so draw the tiles from `onInput`:
+
+```js
+StillMade.onInput(async input => {
+  for (const photo of input.listingPhotos || []) {
+    const preview = await StillMade.previewImage(photo); // display copy
+    // ...add an <li><img src="preview.url"></li> before the + tile
+  }
+});
+```
+
+From your own button, call `await StillMade.addFiles('listingPhotos')` inside
+its click handler. It resolves to `{added}` (0 when the person closes the
+picker) and rejects with a message for an undeclared input, an input that is
+not a file input, an input an earlier Step fills, a person who can only view
+the project, or a call that does not come from a click or key press in the
+view. The view never receives a `File` or a `blob:` URL, only the saved
+values. StillMade hides `[data-stillmade-add]` tiles from viewers and for
+inputs an earlier Step fills. In the SDK preview, the tile opens your
+computer's file chooser and the preview keeps the files like your own picks.
+
+### Removing and reordering files
+
+A list input's files are removed and put in order on the same screen, so a
+person drops a bad photo or sets the tour's order without leaving the Block.
+Put the buttons in each tile, with `data-index` (from 0) naming its place in
+the list `onInput` gave you:
+
+```html
+<li>
+  <img src="..." alt="Photo 3">
+  <span class="sm-tile-tools">
+    <button type="button" data-stillmade-move="listingPhotos" data-index="2" data-to="1"
+        aria-label="Move earlier" title="Move earlier"><span class="sm-glyph" data-glyph="chevron-left" aria-hidden="true"></span></button>
+    <button type="button" data-stillmade-move="listingPhotos" data-index="2" data-to="3"
+        aria-label="Move later" title="Move later"><span class="sm-glyph" data-glyph="chevron-right" aria-hidden="true"></span></button>
+    <button type="button" data-stillmade-remove="listingPhotos" data-index="2"
+        aria-label="Remove" title="Remove"><span class="sm-glyph" data-glyph="close" aria-hidden="true"></span></button>
+  </span>
+</li>
+```
+
+`data-stillmade-remove` removes the file at `data-index`; `data-stillmade-move`
+moves it to the place `data-to`. A `data-to` past either end of the list does
+nothing, so the first tile's Move earlier is harmless (disable it if you like).
+From your own code, call `await StillMade.removeFile('listingPhotos', 2)` or
+`await StillMade.moveFile('listingPhotos', 2, 1)` inside a click handler; each
+resolves to `{files}`, how many the list now holds. StillMade changes the
+Step's list as its own tile buttons do, keeping each saved file's upload record
+with it, and the new list reaches the view through `onInput`: redraw the tiles
+from it, never from your own copy.
+
+Both work only on list inputs (`image[]`, `video[]`, `audio[]`, `asset[]`,
+`file[]`); `addFiles` replaces a single input's file. They are refused, as
+`addFiles` is, for an undeclared input, an input an earlier Step fills, a
+viewer, Chat and a call that does not come from a click or key press in the
+view, and also when the file at that place changed after the view was given it
+(another person edited the list): the view gets the current list and the person
+tries again. StillMade hides these buttons wherever it hides the + tile. The SDK
+preview changes its example input the same way.
+
 ## Theming
 
 The theme variables from StillMade's design system are always defined:
@@ -60,6 +141,25 @@ rest. Colors written with them follow Light, Dark and White automatically.
 Frame views are not required to use them; the appearance check reports
 hard-coded colors as advice instead of refusing the view.
 
+A color the check takes is a theme variable, `transparent` or `currentColor`,
+or a gradient of them (`linear-gradient(to top, var(--bg), transparent)`).
+`opacity` is not a color and is always allowed. `color-mix()`, `rgba()`,
+`#rrggbbaa` and other written colors are what it reports. For words over a
+photo or video, use the kit's shade: `var(--scrim)` is the page's background,
+partly see-through, in every theme, and `class="sm-scrim"` lays it over the
+bottom of a positioned box (an `sm-stage`) under the words inside it:
+
+```html
+<figure class="sm-stage" data-fill>
+  <img src="..." alt="">
+  <figcaption class="sm-scrim">12 Elm Street · 3 bed</figcaption>
+</figure>
+```
+
+`--scrim` and `sm-scrim` are the only shade a Block uses; StillMade's own
+`--scrim-top` and `--scrim-bottom` (theme.css) are for its pages and the check
+reports them.
+
 ## Layout
 
 StillMade zooms a view to fill the space its Step gives it (up to 150%), and
@@ -101,6 +201,19 @@ too: such a picture without a `tabindex` of its own joins the tab order,
 keyboard focus on it shows the button, Enter or Space opens the viewer, and
 closing the viewer gives the focus back to the picture.
 
+## A job on one page: a check, then the run
+
+A job the person fills in and gets a result from is one page: the inputs on the
+left and the result's place on the right on a wide screen; on a phone they
+stack in the page's order, the inputs, the button in normal flow (never a sticky
+bar), then the result's place under it. When the expensive run needs a cheap
+check first (the script and a voice sample before the video), keep it on the
+same page: call `StillMade.run({make: 'check'})`, show what comes back, then
+`StillMade.run({make: 'video', script})` with what the person checked. Each run
+is priced and approved by StillMade on its own, so the view shows no price. The
+module side and what the person sees are in MODULES.md, "A check, then the
+expensive run, on one page".
+
 ## Assets
 
 Images, fonts, JSON, audio and video the view needs ship as files named by

package/INTERFACE_DESIGN.md

@@ -18,14 +18,7 @@ wins. Open `packages/design-system/block-kit.html` in a browser to see every
 piece in Light, Dark and White.
 
 ```html
-<main class="sm-block" data-layout="split">
-  <section class="sm-stage" id="stage" data-ratio="16:9" aria-live="polite">
-    <div class="sm-empty" id="empty">
-      <span class="sm-glyph" data-glyph="video" aria-hidden="true"></span>
-      <p>Drop a clip</p>
-    </div>
-  </section>
-
+<main class="sm-block">
   <fieldset class="sm-choices" id="look" data-stillmade-share="look" data-ratio="16:9">
     <legend>Look</legend>
     <label><input type="radio" name="look" value="warm" checked><img src="data:..." alt=""><span>Warm</span></label>
@@ -40,21 +33,33 @@ piece in Light, Dark and White.
     <input id="caption" data-stillmade-input="caption" placeholder="Optional">
   </div>
 
-  <div class="sm-actions">
-    <button type="button" class="sm-primary" id="run" data-stillmade-action="make the clip">Make the clip</button>
-    <p class="sm-status" id="status" role="status"></p>
-  </div>
-
   <details class="sm-more">
     <summary>More</summary>
     <div class="sm-fields"><!-- secondary settings --></div>
   </details>
+
+  <div class="sm-actions">
+    <button type="button" class="sm-primary" id="run" data-stillmade-action="run">Make the clip</button>
+    <p class="sm-status" id="status" role="status"></p>
+  </div>
+
+  <section class="sm-stage" id="stage" data-ratio="16:9" aria-live="polite">
+    <div class="sm-empty" id="empty">
+      <span class="sm-glyph" data-glyph="video" aria-hidden="true"></span>
+      <p>Your clip</p>
+    </div>
+  </section>
 </main>
 ```
 
+With an `sm-stage` as its direct child and no `data-layout`, `sm-block` puts
+the inputs on the left and the stage on the right from 860 px wide. Under that
+everything stacks in the page's order, so the stage comes last in the markup:
+the inputs, the button, then the result's place under it.
+
 | Class | Use it for |
 | --- | --- |
-| `sm-block` | The one workspace. `data-layout="split"` puts the stage beside the controls on wide screens. |
+| `sm-block` | The one workspace. With an `sm-stage` child, the controls sit left and the stage right from 860 px; narrower, they stack in the page's order. `data-layout="stack"` keeps one column; `"split"` is an older layout with the stage on the left. |
 | `sm-stage` | The thing being made: preview, media or result. `data-ratio="16:9"`, `"9:16"` or `"1:1"`. |
 | `sm-empty` | An empty stage: a glyph, at most five words, one action. |
 | `sm-choices` | Picks shown as pictures (`img`, `.sm-swatch`, `.sm-glyph`) and one or two words. `data-compact` for short text chips, `data-segmented` for one connected row of three or four short options. The pick is filled with the kit's ink, so it reads at a glance; a `disabled` fieldset keeps its pick and fades the rest. Chips and segments scroll sideways on a phone. Give the `fieldset` an `id` and `data-stillmade-share` so teammates see the same pick. |
@@ -65,10 +70,12 @@ piece in Light, Dark and White.
 | `sm-actions` | One `sm-primary`, then `sm-quiet` buttons and `sm-icon` buttons (each with `aria-label` and `title`). |
 | `sm-status` | Live state beside the action: `data-state="loading"`, `"success"`, `"waiting"` or `"error"`. |
 | `sm-more` | A closed `<details>` for secondary settings. |
-| `sm-hint` | A closed `<details>` info toggle for an explanation that might help. |
+| `sm-hint` | A closed `<details>` (i) for an explanation that might help. Its words show on hover or focus, or a tap on touch screens. |
 | `sm-gallery` | A grid of results or media. `data-size="small"` for input files: more tiles per row as the screen widens. |
 | `sm-media-off` | A picture or clip that cannot show here (on another device, or it did not open): a quiet tile in its own shape (`--sm-photo-ratio`, the tile's shape in a gallery) holding the `image-off` glyph, the reason in `aria-label` and `title`, no words inside. |
-| `sm-glyph` | A small icon in `currentColor`: `play`, `pause`, `plus`, `close`, `check`, `chevron`, `upload`, `image`, `image-off`, `video`, `audio`, `text`, `spark`, `info`, `warning`, `spinner`. Works in standard views, which cannot use SVG. |
+| `sm-add` | The + tile that adds files to an input: `<button type="button" class="sm-add" data-stillmade-add="listingPhotos" aria-label="Add photos">`. StillMade opens its own picker and saves the files; they arrive through `onInput`. In an `sm-gallery` it takes the tile's shape. |
+| `sm-scrim` | Words over a photo or video, inside a positioned box such as an `sm-stage`: a see-through shade of the page under them, in every theme. `var(--scrim)` is the same shade for your own rules. |
+| `sm-glyph` | A small icon in `currentColor`: `play`, `pause`, `plus`, `close`, `check`, `chevron`, `chevron-left`, `chevron-right`, `upload`, `image`, `image-off`, `video`, `audio`, `text`, `spark`, `info`, `warning`, `spinner`. Works in standard views, which cannot use SVG. |
 
 **Function first.** When the person building a Block does not ask for a look,
 use the kit as is: they want it to work and be easy to use. When they name a
@@ -137,6 +144,14 @@ person or the creator has not asked for something else. What they ask for wins.
   `details`, `notes` or `listingDetails`; when a note has to be split across
   several fields StillMade does it free. Never build your own reference
   picker or library upload.
+- **Files are tiles, added through StillMade.** A screen that holds an
+  input's files shows them as tiles (`sm-gallery`) ending in the kit's + tile,
+  `<button type="button" class="sm-add" data-stillmade-add="listingPhotos"
+  aria-label="Add photos">`. StillMade opens its own picker and saves the files
+  as its own tiles do; they arrive through `onInput`. From your own code call
+  `StillMade.addFiles("listingPhotos")` in a click. Never an
+  `<input type="file">` or an upload box of the Block's own. See
+  [Frame views](FRAME_VIEWS.md#adding-files-to-an-input).
 - **Days and times are picked, never typed.** Use the `date` type. StillMade
   shows a calendar, and a list of times as well when the input is about a time
   (a name such as `postAt` or `startsAt`, a label with Time, When or Starts, or
@@ -146,8 +161,11 @@ person or the creator has not asked for something else. What they ask for wins.
   any app is a connector Step after the Block, and StillMade words its button
   ("Post to Instagram"). A Block never posts from inside itself.
 - **Chat can do all of it.** Every button carries `data-stillmade-action`
-  naming what it does and every field a label, so the project's Chat can press
-  and fill them.
+  and every field a label, so the project's Chat can press and fill them. The
+  button that runs the Block says `run` (StillMade's phone and desktop checks
+  press it with the fixture); every other button names what it does
+  (`data-stillmade-action="play sample"`). Chat reads the value with the
+  button's own words.
 
 ## 4. Rules
 
@@ -158,7 +176,15 @@ exception, never unrelated technical UI.
 1. Show the thing being made, not a technical representation of it. No JSON
    dumps, source editors, manifests, debug consoles or "Technical result"
    panels unless the task is about source. A collapsed disclosure is still an
-   added surface.
+   added surface. Every part shows at once (November 3, 2026): before the first
+   run the result's place is drawn in the shape and size of what is coming
+   (`<section class="sm-stage" data-ratio="9:16">` for a vertical clip, lines for
+   text, a player bar for sound), so the result fills a place the person already
+   sees instead of popping in somewhere unexpected. StillMade draws the Steps it
+   draws the same way (`ResultPlace`). On a wide screen what goes in sits on the
+   left and the result on the right, side by side (the kit's `sm-block` with an
+   `sm-stage` does this from 860px); they stack only on narrow screens and phones,
+   the result's place under the button (rule 16).
 2. One obvious next action. Seven or fewer choices in view; strong defaults.
 3. Choices people see or hear (voices, music, sounds, fonts, looks, colors,
    templates, images) show a preview of each option: a thumbnail or a sample
@@ -183,7 +209,9 @@ exception, never unrelated technical UI.
 12. Status is a dot or a few words ("No narration yet"), never a paragraph.
     The reason sits behind an `sm-hint`.
 13. Files are tiles: a saved file is a thumbnail or chip, and adding one is a
-    + tile (a `label` around a hidden file input). Never the browser's bare
+    + tile, `<button class="sm-add" data-stillmade-add="<input>">`, which
+    opens StillMade's picker (or `StillMade.addFiles("<input>")` from your own
+    button). Never an `<input type="file">` or the browser's bare
     "Choose File / No file chosen" picker, and no size limits in view until
     a file is too big.
 14. Rare tools (update, schedule, history, reload) are named icon buttons
@@ -197,8 +225,11 @@ exception, never unrelated technical UI.
 16. Use the width. From 860 px wide, the kit puts the controls on the left
     at a reading width (300–380 px) and the result (`sm-stage`, a direct
     child of `sm-block`) fills the right, in its real shape. Under that the
-    page is one column: result first, then the controls, with the action
-    within reach. Extra width goes to the result, never to wider text
+    page is one column in the page's order: the inputs, the action in
+    normal flow (rule 5: never a sticky bar), then the result's place under
+    it, so `sm-stage` comes after `sm-actions` in the markup. Keep the
+    inputs above the button short enough that a phone shows the button
+    without scrolling far; fold the rest into `sm-more`. Extra width goes to the result, never to wider text
     fields. Before there is a result, the stage previews what will be made
     from the inputs given so far, not an empty box. `data-layout="stack"`
     keeps one column. StillMade zooms a view to fill its space and centers a
@@ -241,6 +272,15 @@ exception, never unrelated technical UI.
       <span class="sm-glyph" data-glyph="image-off" aria-hidden="true"></span>
     </span>
     ```
+23. One page per job (November 3, 2026). A job the person fills in and then
+    gets a result from is one Block on one page: the inputs and settings, a
+    cheap check before the expensive run (the script and a voice sample
+    before the video), then the result. The check is a second
+    `StillMade.run` on the same page, priced by StillMade on its own (Module
+    Blocks, "A check, then the expensive run, on one page"); it never becomes
+    a second Block or Step. A workspace the person works in for a while (a
+    CAD tool, a canvas, an editor) is its own Block, and turning what it made
+    into something else is the next one.
 
 ## 5. What StillMade checks
 

package/MOBILE_UI.md

@@ -60,8 +60,10 @@ For deterministic browser checks, mark a custom form control with
 test fixture through the real UI before pressing its run action. This marker
 does not change the Block's input contract or grant access to host services.
 For a text-bearing object fixture such as `{brief:{text:"…"}}`, the profile
-enters its `text` into the marked text field. Mark the primary button with
-`data-stillmade-action="run"` when the view has more than one button.
+enters its `text` into the marked text field, then presses the button marked
+`data-stillmade-action="run"` (or the view's only button). Every button carries
+`data-stillmade-action` so Chat can press it: `run` on the button that runs the
+Block, and what it does on every other button (`data-stillmade-action="play sample"`).
 The existing `data-stillmade-share` marker is also recognized for shared text
 fields. A custom view without a reachable mapped control must not be counted
 as having passed its fixture's success interaction.