stillmade-sdk 0.1.46 → 0.1.48

package/docs/tools/llm.md

@@ -16,9 +16,9 @@ Ask the assistant to return source files or one `.stillmade.json` package. Run t
 
 <!-- builder-contract:start (generated by npm run build:sdk; do not edit) -->
 
-## Block builder contract (stillmade.block-builder@1.17.0)
+## Block builder contract (stillmade.block-builder@1.18.0)
 
-Contract `stillmade.block-builder@1.17.0`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.18.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
 
@@ -87,7 +87,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`, 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; a stage shows what it holds in its middle as one group (a caption stays with its picture) and several results fill its width as one row, on a Block's screen and on the pages StillMade draws; 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.
+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 after the inputs with the job's action row on it (`sm-actions` and `sm-status` inside `sm-stage`: the kit puts the status top-left and the actions top-right in the player's cream blocks, over a band above the media; the run button is always the rightmost, so a button that spends credits never moves and making again is pressed where it made the first time, with Download and other result actions to its left), 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, photo editor), declares `manifest.kind: "workspace"` and looks and works like that kind of app instead of a compact page, and StillMade's checks (admission, readiness, its own builder) then apply the app rules instead of the compact ones: no limit on controls in view, no Block kit page, its own layout, the craft's own words, and only its run button (`data-stillmade-action="run"`) held to naming what it makes: 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; a stage shows what it holds in its middle as one group (a caption stays with its picture) and several results fill its width as one row, on a Block's screen and on the pages StillMade draws; 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 for 3 s the first time it comes into view, then 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
 
@@ -181,7 +181,7 @@ Every finished Block must support automatic remixing through the standard SDK co
 
 ### Package format
 
-A Block package is StillMade SDK 0.1.0 JSON. Prefer {manifest,recipe,tests} for supported operations. Otherwise use {manifest,code,tests} with runtime:"javascript": code is a synchronous function body receiving input and returning declared output bindings, e.g. return {text:input.text.toUpperCase()}. JavaScript runs in isolated QuickJS: no fetch, DOM, Node APIs, modules, dependencies, timers, or host services; no promises, imports, require, eval or Function. Limits: 500 ms execution, 16 MiB heap, 256 KiB code, 4 MiB JSON I/O. Include concrete passing fixtures that reflect the requested behavior, including an edge case; never approximate a hosted model call with fabricated deterministic output. Manifest fields: schemaVersion:1,sdkVersion:"0.1.0",id:"creator.name",version:"1.0.0",name,description,kind:"task",runtime:"recipe", "javascript", "comfyui", or "capability",inputs/outputs as named {type,default?,min?,max?,role?,primary?}. Usually mark one primary input and output with primary:true. Semantic roles such as source_image and character_reference are distinct and must never be guessed,permissions:{project:[],network:[],filesystem:[],secrets:[]},ui:[{control,port}]. Recipe: {schemaVersion:1,steps:[{id,op,args}],outputs}. References: {"$input":"port"}, {"$step":"step-id"}. Supported operations: {"value.copy":{"description":"Copy a JSON value without changing it.","args":["value"]},"text.trim":{"description":"Remove leading and trailing whitespace.","args":["text"]},"text.replace":{"description":"Replace literal text; no regular expressions.","args":["text","find","replacement"]},"text.join":{"description":"Join an array of text values.","args":["items","separator"]},"image.thicken-lines":{"description":"Expand dark outlines while preserving other colors.","args":["image","thickness","threshold"]}}. Port 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. A value is exactly: text: a string; number: a number; integer: a whole number; boolean: true or false; json: any JSON value; object: a plain JSON object; image: {kind: 'image'; assetId: string; versionId: string; url: string; mimeType?: string; bytes?: number; name?: string; role?: string; width?: number; height?: number}; video: {kind: 'video'; assetId: string; versionId: string; url: string; mimeType?: string; bytes?: number; name?: string; role?: string; width?: number; height?: number; duration?: number}; audio: {kind: 'audio'; assetId: string; versionId: string; url: string; mimeType?: string; bytes?: number; name?: string; role?: string; duration?: number; sampleRate?: number; channels?: number}; asset: {kind: 'image' | 'video' | 'audio' | 'asset'; assetId: string; versionId: string; url: string; mimeType?: string; bytes?: number; name?: string; role?: string}; script: {schemaVersion: 1; text: string; [key: string]: unknown}; transcript: {schemaVersion: 1; text: string; words: Array<{text: string; start: number; end: number}>}; file: {kind: 'file'; assetId: string; versionId: string; mimeType: 'application/pdf' | 'text/plain' | 'text/csv' | 'text/markdown' | 'application/json' | 'application/zip'; url?: string; name?: string; bytes?: number}; document: {schemaVersion: 1; format: 'markdown' | 'plain'; text: string; title?: string}; table: {schemaVersion?: 1; columns: string[]; rows: Array<Record<string, string | number | boolean | null>>}; url: an absolute http or https address string; date: an ISO 8601 date string ('2026-10-09' or '2026-10-09T14:30'); color: a hex color string ('#ff8800' or '#ff8800cc'). A file value is a saved file: one the person gives the Block (a module Block reads its bytes with stillmade.files.read) or what stillmade.files.write returns in a module Block; an image may also be decoded RGBA pixels {width, height, data} in recipe and JavaScript Blocks, which hold only 4 MiB of JSON (a picture of about 300 by 300 pixels), so a Block that joins photos into one picture (side by side, a grid, a contact sheet, a poster) is a module Block calling media.transform image.compose. Every other type is {schemaVersion: 1; [key: string]: unknown} with the fields its own section gives. A type ending in [] is a plain array of those values (audio[] is a list of audio references, never objects that wrap them). Include test {name,input,expected} where expected is output bindings.
+A Block package is StillMade SDK 0.1.0 JSON. Prefer {manifest,recipe,tests} for supported operations. Otherwise use {manifest,code,tests} with runtime:"javascript": code is a synchronous function body receiving input and returning declared output bindings, e.g. return {text:input.text.toUpperCase()}. JavaScript runs in isolated QuickJS: no fetch, DOM, Node APIs, modules, dependencies, timers, or host services; no promises, imports, require, eval or Function. Limits: 500 ms execution, 16 MiB heap, 256 KiB code, 4 MiB JSON I/O. Include concrete passing fixtures that reflect the requested behavior, including an edge case; never approximate a hosted model call with fabricated deterministic output. Manifest fields: schemaVersion:1,sdkVersion:"0.1.0",id:"creator.name",version:"1.0.0",name,description,kind:"task" (or "workspace" for an app a person works in, such as a CAD tool or photo editor),runtime:"recipe", "javascript", "comfyui", or "capability",inputs/outputs as named {type,default?,min?,max?,role?,primary?}. Usually mark one primary input and output with primary:true. Semantic roles such as source_image and character_reference are distinct and must never be guessed,permissions:{project:[],network:[],filesystem:[],secrets:[]},ui:[{control,port}]. Recipe: {schemaVersion:1,steps:[{id,op,args}],outputs}. References: {"$input":"port"}, {"$step":"step-id"}. Supported operations: {"value.copy":{"description":"Copy a JSON value without changing it.","args":["value"]},"text.trim":{"description":"Remove leading and trailing whitespace.","args":["text"]},"text.replace":{"description":"Replace literal text; no regular expressions.","args":["text","find","replacement"]},"text.join":{"description":"Join an array of text values.","args":["items","separator"]},"image.thicken-lines":{"description":"Expand dark outlines while preserving other colors.","args":["image","thickness","threshold"]}}. Port 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. A value is exactly: text: a string; number: a number; integer: a whole number; boolean: true or false; json: any JSON value; object: a plain JSON object; image: {kind: 'image'; assetId: string; versionId: string; url: string; mimeType?: string; bytes?: number; name?: string; role?: string; width?: number; height?: number}; video: {kind: 'video'; assetId: string; versionId: string; url: string; mimeType?: string; bytes?: number; name?: string; role?: string; width?: number; height?: number; duration?: number}; audio: {kind: 'audio'; assetId: string; versionId: string; url: string; mimeType?: string; bytes?: number; name?: string; role?: string; duration?: number; sampleRate?: number; channels?: number}; asset: {kind: 'image' | 'video' | 'audio' | 'asset'; assetId: string; versionId: string; url: string; mimeType?: string; bytes?: number; name?: string; role?: string}; script: {schemaVersion: 1; text: string; [key: string]: unknown}; transcript: {schemaVersion: 1; text: string; words: Array<{text: string; start: number; end: number}>}; file: {kind: 'file'; assetId: string; versionId: string; mimeType: 'application/pdf' | 'text/plain' | 'text/csv' | 'text/markdown' | 'application/json' | 'application/zip'; url?: string; name?: string; bytes?: number}; document: {schemaVersion: 1; format: 'markdown' | 'plain'; text: string; title?: string}; table: {schemaVersion?: 1; columns: string[]; rows: Array<Record<string, string | number | boolean | null>>}; url: an absolute http or https address string; date: an ISO 8601 date string ('2026-10-09' or '2026-10-09T14:30'); color: a hex color string ('#ff8800' or '#ff8800cc'). A file value is a saved file: one the person gives the Block (a module Block reads its bytes with stillmade.files.read) or what stillmade.files.write returns in a module Block; an image may also be decoded RGBA pixels {width, height, data} in recipe and JavaScript Blocks, which hold only 4 MiB of JSON (a picture of about 300 by 300 pixels), so a Block that joins photos into one picture (side by side, a grid, a contact sheet, a poster) is a module Block calling media.transform image.compose. Every other type is {schemaVersion: 1; [key: string]: unknown} with the fields its own section gives. A type ending in [] is a plain array of those values (audio[] is a list of audio references, never objects that wrap them). Include test {name,input,expected} where expected is output bindings.
 
 ### Feature map
 
@@ -245,7 +245,7 @@ Write the description in third-grade language: one short sentence, ideally 8–1
 
 ### Compact interface
 
-Every job or ingredient Block interface, generated or custom, follows StillMade's compact rules: Compact: the whole Block fits one laptop screen without scrolling. A short setting is one row, its label beside the control; no card around a single control. Status is a dot or a few words ("No narration yet"), never a paragraph; the reason sits behind an `sm-hint`. Files are tiles: a saved file is a thumbnail or chip and adding one is the + tile (`<button class="sm-add" data-stillmade-add="<input>">`), which opens StillMade's picker. Never an `<input type="file">` or the bare browser file picker, and no size limits in view until a file is too big. An (i) beside anything a newcomer could misread: a setting, status or number whose effect is not obvious from its label gets a closed `sm-hint` with one or two sentences. Give every input that needs one a `description`; StillMade shows it as that (i). Obvious controls get none. Use the width: from 860px wide the kit puts the controls on the left at a reading width (300–380px) and the result (`sm-stage`) fills the right, in its real shape; under that everything stacks in the page's order: the inputs, the action in normal flow (never pinned), then the result's place under it, so put `sm-stage` after `sm-actions`. 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. `data-layout="stack"` opts out. StillMade draws generated manifest.ui controls this way itself (label beside control, files as tiles, the result filling the right on wide screens); you supply at most four inputs that matter in view, sensible defaults, and a short `description` on every input whose effect is not obvious from its name, which StillMade shows as its (i). An app-sized Block is different: when the request is for something a person works in (an editor, a canvas, a 3D or CAD tool, a studio), build it as a workspace Block laid out like that app: its work surface (viewport, canvas, timeline, panels, tool rails) owns the page with as much tooling as the app needs, and the compact rules apply to its settings, dialogs and status, never to the work surface. Never shrink an app to one screen of four inputs.
+Every job or ingredient Block interface, generated or custom, follows StillMade's compact rules: Compact: the whole Block fits one laptop screen without scrolling. A short setting is one row, its label beside the control; no card around a single control. Status is a dot or a few words ("No narration yet"), never a paragraph; the reason sits behind an `sm-hint`. Files are tiles: a saved file is a thumbnail or chip and adding one is the + tile (`<button class="sm-add" data-stillmade-add="<input>">`), which opens StillMade's picker. Never an `<input type="file">` or the bare browser file picker, and no size limits in view until a file is too big. An (i) beside anything a newcomer could misread: a setting, status or number whose effect is not obvious from its label gets a closed `sm-hint` with one or two sentences. Give every input that needs one a `description`; StillMade shows it as that (i). Obvious controls get none. Use the width: from 860px wide the kit puts the controls on the left at a reading width (300–380px) and the result (`sm-stage`) fills the right, in its real shape; under that everything stacks in the page's order: the inputs, then the result's place with its actions on it (never a pinned bar), so `sm-stage` comes after the inputs. 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. `data-layout="stack"` opts out. StillMade draws generated manifest.ui controls this way itself (label beside control, files as tiles, the result filling the right on wide screens); you supply at most four inputs that matter in view, sensible defaults, and a short `description` on every input whose effect is not obvious from its name, which StillMade shows as its (i). An app is different: when the request is for software a person works in (an editor, a canvas, a 3D or CAD tool, a photo editor, a studio), set manifest.kind:"workspace", which makes it an app, and lay it out like that app: its work surface (viewport, canvas, timeline, panels, tool rails) owns the page with as much tooling as the app needs, and the compact rules apply to its settings, dialogs and status, never to the work surface. Never shrink an app to one screen of four inputs.
 
 ### Generated controls first
 
@@ -257,7 +257,7 @@ Optional custom view interfaces are supported, but generated manifest.ui control
 
 *When:* StillMade's builder adds this section when the person asks for an interface, preview or controls, or refines a Block that has one.
 
-A custom interface is the optional package-level view:{html,css?,themedCss?,javascript?}; when refining, preserve and refine base.view. Design it by StillMade's interface principles, in order: Function first: unless the person asks for a design direction, build from the Block kit (`sm-block`, `sm-stage`, `sm-choices`, `sm-actions`, `sm-more`) and ship little or no CSS of your own. A direction the person names wins over the kit. Show the thing being made: the preview, media or result gets the largest area (`sm-stage`), and every part shows at once: before the first run the result's place is drawn in the shape and size of what is coming (a 9:16 frame for a vertical clip, lines for text, a player bar for sound), so the result fills it instead of popping in. On a wide screen what goes in sits on the left and the result on the right; they stack only on narrow screens and phones. A picture or clip the Block makes fills it in its own shape, as large as fits; several fill it as a grid, each big enough to watch. Small tiles are for the files a person gives the Block, never for what it makes. A clip is a `<video controls>`, which StillMade plays in its own player with full screen, and a picture in `sm-stage` or `sm-gallery` (or marked `data-stillmade-expand`) gets StillMade's full-screen button; leave out `controls` only when the Block drives playback itself. Never a JSON dump, source editor, manifest or diagnostic panel unless the task is about source. One obvious next action: one solid `sm-primary` in the kit's ink, never restyled to the background or a ghost outline; peers are `sm-quiet` buttons or named icons, and close is an X icon. Seven or fewer choices in view. Speak the job unless the person or creator asks otherwise. The action button names what it does in the job's words (`manifest.action`: "Plan the tour"; AI pictures, video and sound start with Generate and say what, the person's own media cut or rendered says Make: "Generate voiceover", "Make 6 clips"), never "Make it", "Run", "Run step", "Submit", "Process" or a bare "Generate"; progress counts the job's units ("4 of 9 rooms"), never "Processing"; results and problems use its words in one line. Show no credit numbers: StillMade puts the price beside the verb on its own run button ("Write · 1 credit"), with a chip for the model, quality or count when they can change. Pressing it runs at that price; a confirmation appears only when the server price is higher than the one shown. Pictures over words: choices people see or hear are thumbnails, swatches, samples or glyphs (`sm-choices`), not word lists. Icons carry an accessible name and tooltip; never emoji. A picked option reads at a glance: keep the kit's ink fill on an `sm-choices` pick, never restyled to an outline, a tint or the page's background. Media that cannot show here (on another device, or it did not open) keeps its place as a quiet `sm-media-off` tile in its own shape, never words in its place. Words only when needed. Drop what nobody needs to finish the task (intros, "how it works", restating the Block name). Words that might help start collapsed (`sm-hint`, `sm-more`). Errors, spending approvals, stale inputs and destructive steps stay visible, in few words. Strong defaults; secondary settings go in `sm-more`, closed. Compact: the whole Block fits one laptop screen without scrolling. A short setting is one row, its label beside the control; no card around a single control. Status is a dot or a few words ("No narration yet"), never a paragraph; the reason sits behind an `sm-hint`. Files are tiles: a saved file is a thumbnail or chip and adding one is the + tile (`<button class="sm-add" data-stillmade-add="<input>">`), which opens StillMade's picker. Never an `<input type="file">` or the bare browser file picker, and no size limits in view until a file is too big. Rare tools (update, schedule, history, reload) are named icon buttons beside the action, never sections under the work. An (i) beside anything a newcomer could misread: a setting, status or number whose effect is not obvious from its label gets a closed `sm-hint` with one or two sentences. Give every input that needs one a `description`; StillMade shows it as that (i). Obvious controls get none. One workspace: no cards inside cards, no second title, step counter or Back/Next bar; the host owns navigation. One page per job (November 3, 2026): a guided job's screen holds the inputs and settings, then a cheap check before the expensive run (the script and a voice sample before the video, a second `StillMade.run` that StillMade prices on its own), then the result; never a second Block or Step for the check. A workspace a person works in (a CAD tool, a canvas, an editor) is its own Block, and turning what it made into something else is the next one. Status sits beside the action it describes (`sm-status`), in a few words. Keep the page in normal scroll flow; no sticky media or control strips unless the editing task needs them. Use the width: from 860px wide the kit puts the controls on the left at a reading width (300–380px) and the result (`sm-stage`) fills the right, in its real shape; under that everything stacks in the page's order: the inputs, the action in normal flow (never pinned), then the result's place under it, so put `sm-stage` after `sm-actions`. 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. `data-layout="stack"` opts out. Size with the kit, never fixed sizes: no fixed pixel widths or heights for the workspace or stage, no 100vh, no position:fixed panels. StillMade zooms a Block's screen to fill the space it has (up to 150%, never down to a phone layout on a computer), so a Block laid out with the kit's spacing fills its Step without empty space, and it centers a standard view narrower than its Step. The kit's `sm-stage` shows what it holds in its middle as one group (a caption stays with its picture), and several results in a stage fill its width as one row; the pages StillMade draws follow the same rule. 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. Group what the person sets in one `sm-fields` (or `sm-settings` for short ones): the kit gives the group its own surface, so the inputs, the settings and the result read as separate parts. Settings sit side by side (`sm-settings`), next to what they change. Three or four short options are one segmented row (`data-segmented`), not a row of big tiles. Lists fill the width at a small size: input files are small tiles (`sm-gallery data-size="small"`), many items are one line each (`sm-list`): a thumbnail, one line of text, a short fact. Tapping an item opens all of its fields in place. Extra width means more items per row, never bigger cards. On a phone chip and segment rows scroll sideways instead of wrapping; long lists show their first three with "N more" (`data-peek`) and long text five lines until tapped (`sm-clamp`). Nothing is lost when a Block gets smaller: every control stays on the screen, behind an (i), in `sm-more`, or inside the item it belongs to. Compacting moves controls; it never deletes them. Text scene descriptions are planning notes, never a storyboard or an approved frame. Say nothing about how the Block works: no notes on where it runs (this device, StillMade Desktop, the cloud), saving, syncing, recovery, accounts, credits or where a file is kept. StillMade tells the person what they need as one short notification, or nothing; never a sentence on the page, and never the same line under each item. References fill your inputs: every drop area in StillMade offers "Use a reference", and the person's saved photos, videos and notes fill the Step with no typing. Media inputs fill by kind, so take `video` or `asset` wherever a clip works as well as a photo; text inputs fill by plain names and labels (`productName`, `website`, `brandColors`, `fonts`, `voice`, and `details` or `notes` for the reference's note). Never build your own reference picker or library upload. Days and times are picked, never typed: a `date` input is a calendar, with a list of times when it is about a time (`postAt`, `startsAt`, a label with Time, When or Starts). In a custom view use `<input type="date">` or `type="datetime-local"`, never a text box for a date. Posting is its own Step: sending a result to Instagram, TikTok, email or any app is a connector Step after the Block, worded by StillMade ("Post to Instagram"). A Block never posts from inside itself. Its DOM controller is separate from manifest runtime code. The view may also declare appearance:"original" or "host". For an imported design, preserve its colors with appearance:"original" and view.css; no themed replacement is required. Preserve base.view.appearance when refining unless the user requests a change. Omitted/host appearance retains the existing Light, Dark and White requirement: supply semantic colors in view.css or a complete replacement view.themedCss. An original-style view may optionally supply valid themedCss for a StillMade appearance preview. Use StillMade variables (--bg,--fg,--fg-muted,--border-tok,--r-3) only when opting into host styling; do not redefine host tokens in the themed variant. Appearance never relaxes sandbox constraints: no CSS escapes/filters/blending, imports/url(), or element.style mutations in JS. Use classes for UI state; media pixels retain their colors. Both CSS fields have the same 32 KiB limit; all existing shared-state, security and permission checks still apply. Declare elements in html, bind with document.getElementById/querySelector and addEventListener; use literal property access, array methods, textContent, input.value, button.disabled and canvas. Initial values: StillMade.onInput(values=>{...}); await StillMade.run(inputBindings) returns validated output bindings from the isolated package runtime; catch errors and show results. No computation in the DOM controller; put it in code/recipe. Disable the action button while pending.
+A custom interface is the optional package-level view:{html,css?,themedCss?,javascript?}; when refining, preserve and refine base.view. Design it by StillMade's interface principles. Every Block: Speak the job unless the person or creator asks otherwise. The action button names what it does in the job's words (`manifest.action`: "Plan the tour"; AI pictures, video and sound start with Generate and say what, the person's own media cut or rendered says Make: "Generate voiceover", "Make 6 clips"), never "Make it", "Run", "Run step", "Submit", "Process" or a bare "Generate"; progress counts the job's units ("4 of 9 rooms"), never "Processing"; results and problems use its words in one line. Show no credit numbers: StillMade puts the price beside the verb on its own run button ("Write · 1 credit"), with a chip for the model, quality or count when they can change. Pressing it runs at that price; a confirmation appears only when the server price is higher than the one shown. Pictures over words: choices people see or hear are thumbnails, swatches, samples or glyphs (`sm-choices`), not word lists. Icons carry an accessible name and tooltip; never emoji. A picked option reads at a glance: keep the kit's ink fill on an `sm-choices` pick, never restyled to an outline, a tint or the page's background. Media that cannot show here (on another device, or it did not open) keeps its place as a quiet `sm-media-off` tile in its own shape, never words in its place. Words only when needed. Drop what nobody needs to finish the task (intros, "how it works", restating the Block name). Words that might help start collapsed (`sm-hint`, `sm-more`). Errors, spending approvals, stale inputs and destructive steps stay visible, in few words. Status is a dot or a few words ("No narration yet"), never a paragraph; the reason sits behind an `sm-hint`. Files are tiles: a saved file is a thumbnail or chip and adding one is the + tile (`<button class="sm-add" data-stillmade-add="<input>">`), which opens StillMade's picker. Never an `<input type="file">` or the bare browser file picker, and no size limits in view until a file is too big. An (i) beside anything a newcomer could misread: a setting, status or number whose effect is not obvious from its label gets a closed `sm-hint` with one or two sentences. Give every input that needs one a `description`; StillMade shows it as that (i). Obvious controls get none. Nothing is lost when a Block gets smaller: every control stays on the screen, behind an (i), in `sm-more`, or inside the item it belongs to. Compacting moves controls; it never deletes them. Text scene descriptions are planning notes, never a storyboard or an approved frame. Say nothing about how the Block works: no notes on where it runs (this device, StillMade Desktop, the cloud), saving, syncing, recovery, accounts, credits or where a file is kept. StillMade tells the person what they need as one short notification, or nothing; never a sentence on the page, and never the same line under each item. References fill your inputs: every drop area in StillMade offers "Use a reference", and the person's saved photos, videos and notes fill the Step with no typing. Media inputs fill by kind, so take `video` or `asset` wherever a clip works as well as a photo; text inputs fill by plain names and labels (`productName`, `website`, `brandColors`, `fonts`, `voice`, and `details` or `notes` for the reference's note). Never build your own reference picker or library upload. Days and times are picked, never typed: a `date` input is a calendar, with a list of times when it is about a time (`postAt`, `startsAt`, a label with Time, When or Starts). In a custom view use `<input type="date">` or `type="datetime-local"`, never a text box for a date. Posting is its own Step: sending a result to Instagram, TikTok, email or any app is a connector Step after the Block, worded by StillMade ("Post to Instagram"). A Block never posts from inside itself. A job (the default; manifest.kind "task" or none) also: Function first: unless the person asks for a design direction, build from the Block kit (`sm-block`, `sm-stage`, `sm-choices`, `sm-actions`, `sm-more`) and ship little or no CSS of your own. A direction the person names wins over the kit. Show the thing being made: the preview, media or result gets the largest area (`sm-stage`), and every part shows at once: before the first run the result's place is drawn in the shape and size of what is coming (a 9:16 frame for a vertical clip, lines for text, a player bar for sound), so the result fills it instead of popping in. On a wide screen what goes in sits on the left and the result on the right; they stack only on narrow screens and phones. A picture or clip the Block makes fills it in its own shape, as large as fits; several fill it as a grid, each big enough to watch. Small tiles are for the files a person gives the Block, never for what it makes. A clip is a `<video controls>`, which StillMade plays in its own player with full screen, and a picture in `sm-stage` or `sm-gallery` (or marked `data-stillmade-expand`) gets StillMade's full-screen button; leave out `controls` only when the Block drives playback itself. Never a JSON dump, source editor, manifest or diagnostic panel unless the task is about source. One obvious next action: one solid `sm-primary` in the kit's ink, never restyled to the background or a ghost outline; peers are `sm-quiet` buttons or named icons, and close is an X icon. Seven or fewer choices in view. Actions on the stage (owner, November 5, 2026): a job's `sm-actions` and `sm-status` go inside its `sm-stage`, and the kit lays them over it, the status top-left and the actions top-right, in the cream blocks of StillMade's player, with a band kept above the media so they never cover it; the media fills the rest of the stage. A button that spends credits never moves: the run button (`data-stillmade-action="run"`) is always the rightmost and stays in that spot when it makes again ("Make video", then "Make video again"), and what the result adds (Download, Share) goes to its left. Controls on media (StillMade's player, the full-screen square) show for 3 seconds the first time it comes into view, then only while it is hovered or tapped. StillMade's own Step pages do the same. An app that lays itself out keeps its own toolbar. Strong defaults; secondary settings go in `sm-more`, closed. Compact: the whole Block fits one laptop screen without scrolling. A short setting is one row, its label beside the control; no card around a single control. Rare tools (update, schedule, history, reload) are named icon buttons beside the action, never sections under the work. One workspace: no cards inside cards, no second title, step counter or Back/Next bar; the host owns navigation. One page per job (November 3, 2026): a guided job's screen holds the inputs and settings, then a cheap check before the expensive run (the script and a voice sample before the video, a second `StillMade.run` that StillMade prices on its own), then the result; never a second Block or Step for the check. A workspace a person works in (a CAD tool, a canvas, an editor) is its own Block, and turning what it made into something else is the next one. Status goes in `sm-status`, in a few words: top-left on the stage when the actions are there, otherwise beside the action it describes. Keep the page in normal scroll flow; no sticky media or control strips unless the editing task needs them. Use the width: from 860px wide the kit puts the controls on the left at a reading width (300–380px) and the result (`sm-stage`) fills the right, in its real shape; under that everything stacks in the page's order: the inputs, then the result's place with its actions on it (never a pinned bar), so `sm-stage` comes after the inputs. 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. `data-layout="stack"` opts out. Size with the kit, never fixed sizes: no fixed pixel widths or heights for the workspace or stage, no 100vh, no position:fixed panels. StillMade zooms a Block's screen to fill the space it has (up to 150%, never down to a phone layout on a computer), so a Block laid out with the kit's spacing fills its Step without empty space, and it centers a standard view narrower than its Step. The kit's `sm-stage` shows what it holds in its middle as one group (a caption stays with its picture), and several results in a stage fill its width as one row; the pages StillMade draws follow the same rule. 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. Group what the person sets in one `sm-fields` (or `sm-settings` for short ones): the kit gives the group its own surface, so the inputs, the settings and the result read as separate parts. Settings sit side by side (`sm-settings`), next to what they change. Three or four short options are one segmented row (`data-segmented`), not a row of big tiles. Lists fill the width at a small size: input files are small tiles (`sm-gallery data-size="small"`), many items are one line each (`sm-list`): a thumbnail, one line of text, a short fact. Tapping an item opens all of its fields in place. Extra width means more items per row, never bigger cards. On a phone chip and segment rows scroll sideways instead of wrapping; long lists show their first three with "N more" (`data-peek`) and long text five lines until tapped (`sm-clamp`). An app (manifest.kind "workspace"; software a person works in, like a CAD tool or a photo editor) follows these instead of the job-only ones, and StillMade's checks hold it to them: An app (manifest.kind "workspace") is software a person works in for a while: a CAD or 3D tool, a photo editor, a timeline, a canvas, a studio. Its work surface (viewport, canvas, image, timeline) owns the page, laid out like the best apps of its kind, with the tool rail, panels, inspector, layers, timeline and menus the craft needs and as many controls as it needs. Never shrink it into a form of fields and one button. It lays itself out: `data-stillmade-layout="own"` on its outermost element, so StillMade never centers or zooms it and leaves Ctrl/Cmd +/- to it. Full-size panels, fixed toolbars and its own scroll, pan and zoom are fine. Work happens on the surface: select, drag, zoom and pan, keyboard shortcuts for the common tools, undo and redo. Speak the craft: tools and panels use the words people of that craft use (Exposure, Keyframe, Extrude, Layers, Mask), never a plain-language rewrite. A button that spends credits still names what it makes ("Generate fill"), carries `data-stillmade-action="run"` and shows no price; StillMade adds it. Order, not sparseness: tools grouped in panels that fold, the most used in view, rare ones in menus. No intros or paragraphs on the surface; a tool that needs explaining gets a tooltip or an (i). StillMade's appearance (Light, Dark and White) and the Block kit's controls (buttons, fields, sliders, `sm-choices` with thumbnails for presets) wherever they fit; the layout is the app's own. A look the person names wins. On a phone the work surface stays usable and the panels fold into sheets or one tool strip. What the person makes leaves the app as the Block's outputs (and, while they work, its shared state), so the next Step and the other people in the project get it. Its DOM controller is separate from manifest runtime code. The view may also declare appearance:"original" or "host". For an imported design, preserve its colors with appearance:"original" and view.css; no themed replacement is required. Preserve base.view.appearance when refining unless the user requests a change. Omitted/host appearance retains the existing Light, Dark and White requirement: supply semantic colors in view.css or a complete replacement view.themedCss. An original-style view may optionally supply valid themedCss for a StillMade appearance preview. Use StillMade variables (--bg,--fg,--fg-muted,--border-tok,--r-3) only when opting into host styling; do not redefine host tokens in the themed variant. Appearance never relaxes sandbox constraints: no CSS escapes/filters/blending, imports/url(), or element.style mutations in JS. Use classes for UI state; media pixels retain their colors. Both CSS fields have the same 32 KiB limit; all existing shared-state, security and permission checks still apply. Declare elements in html, bind with document.getElementById/querySelector and addEventListener; use literal property access, array methods, textContent, input.value, button.disabled and canvas. Initial values: StillMade.onInput(values=>{...}); await StillMade.run(inputBindings) returns validated output bindings from the isolated package runtime; catch errors and show results. No computation in the DOM controller; put it in code/recipe. Disable the action button while pending.
 Standard custom view code (no `view.config.json` frame runtime) is checked before it runs. These rules come straight from the validator; frame views run in their own sandbox and may build the page with ordinary DOM calls such as `createElement`:
 
 - **HTML elements:** only `div`, `section`, `article`, `header`, `footer`, `main`, `aside`, `nav`, `h1`, `h2`, `h3`, `h4`, `p`, `span`, `strong`, `em`, `i`, `small`, `br`, `hr`, `label`, `input`, `textarea`, `button`, `select`, `option`, `optgroup`, `fieldset`, `legend`, `output`, `progress`, `meter`, `ul`, `ol`, `li`, `dl`, `dt`, `dd`, `figure`, `figcaption`, `img`, `video`, `audio`, `source`, `canvas`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`, `pre`, `code`, `details`, `summary`. No scripts, iframes, SVG, forms, comments or inline event attributes; media URLs must be `data:` or `blob:`.
@@ -268,8 +268,9 @@ Standard custom view code (no `view.config.json` frame runtime) is checked befor
 - **Property access with brackets needs a literal key:** `items[0]` and `record["title"]` are accepted; `items[index]` is rejected. Iterate with `map`/`forEach` or call `items.at(index)`.
 - **No named recursive functions** and no listeners on the global frame; attach events to declared controls.
 - **Dynamic elements:** `StillMade.render` can create `div`, `section`, `article`, `header`, `footer`, `p`, `span`, `strong`, `em`, `i`, `small`, `h1`, `h2`, `h3`, `h4`, `label`, `button`, `input`, `textarea`, `select`, `option`, `ul`, `ol`, `li`, `table`, `thead`, `tbody`, `tr`, `th`, `td`, `details`, `summary`, `output`, `progress`, `img`; give repeated items stable IDs derived from their identity. An `img` gets its picture when you set its `src` to the data URL `StillMade.previewImage` returns, after rendering; the renderer keeps Block-owned `src`. `previewImage` works on items of an `image[]` input.
+- **Preview controls:** a button whose whole text is `Preview` shows the StillMade preview icon alone (an eye in viewfinder corners), with `Preview` as its accessible name; give it a `label` such as `Preview clip 2` when several sit together. Do not draw your own eye or play icon for a preview.
 - **Shared writes are queued in order:** if one `StillMade.updateShared` write is rejected (conflict, read-only or timeout), the writes queued behind it are rejected too. Send dependent edits one at a time or through `StillMade.scheduleSharedEdit`, keep the person's draft, and retry from the latest `onShared` value. `{merge: true}` merges independent fields of an object value; create an absent field with the precondition `{exists: false}`.
-- **Limits:** HTML 64 KiB, CSS 32 KiB, JavaScript 64 KiB; 30 runs and 60 image previews per minute.
+- **Limits:** HTML 64 KiB, CSS 32 KiB, JavaScript 64 KiB; 120 runs and 240 image previews per minute.
 ## Shared project interfaces
 Every meaningful edit and generated result must be visible to collaborators.
 Prefer ordinary manifest.ui controls and declared outputs when those express
@@ -974,8 +975,9 @@ Standard custom view code (no `view.config.json` frame runtime) is checked befor
 - **Property access with brackets needs a literal key:** `items[0]` and `record["title"]` are accepted; `items[index]` is rejected. Iterate with `map`/`forEach` or call `items.at(index)`.
 - **No named recursive functions** and no listeners on the global frame; attach events to declared controls.
 - **Dynamic elements:** `StillMade.render` can create `div`, `section`, `article`, `header`, `footer`, `p`, `span`, `strong`, `em`, `i`, `small`, `h1`, `h2`, `h3`, `h4`, `label`, `button`, `input`, `textarea`, `select`, `option`, `ul`, `ol`, `li`, `table`, `thead`, `tbody`, `tr`, `th`, `td`, `details`, `summary`, `output`, `progress`, `img`; give repeated items stable IDs derived from their identity. An `img` gets its picture when you set its `src` to the data URL `StillMade.previewImage` returns, after rendering; the renderer keeps Block-owned `src`. `previewImage` works on items of an `image[]` input.
+- **Preview controls:** a button whose whole text is `Preview` shows the StillMade preview icon alone (an eye in viewfinder corners), with `Preview` as its accessible name; give it a `label` such as `Preview clip 2` when several sit together. Do not draw your own eye or play icon for a preview.
 - **Shared writes are queued in order:** if one `StillMade.updateShared` write is rejected (conflict, read-only or timeout), the writes queued behind it are rejected too. Send dependent edits one at a time or through `StillMade.scheduleSharedEdit`, keep the person's draft, and retry from the latest `onShared` value. `{merge: true}` merges independent fields of an object value; create an absent field with the precondition `{exists: false}`.
-- **Limits:** HTML 64 KiB, CSS 32 KiB, JavaScript 64 KiB; 30 runs and 60 image previews per minute.
+- **Limits:** HTML 64 KiB, CSS 32 KiB, JavaScript 64 KiB; 120 runs and 240 image previews per minute.
 
 <!-- view-rules:end -->
 
@@ -1254,10 +1256,25 @@ renders leave the previous controls intact. Text is always literal; scripts,
 inline handlers, links, file inputs, network attributes, and raw HTML are rejected.
 
 
+### Spending approvals
+
+A press of the Block's own button pays for one run's hosted calls at StillMade's
+price. A screen whose button starts many runs (a build that makes thirty pictures,
+one run each) asks once instead: from that press, call
+`await StillMade.allowSpending({credits, label})` with the total the button showed
+and its words. StillMade shows its own dialog; when the person allows it, that
+Step's later runs spend from the total silently, each call at StillMade's own
+price, for 30 minutes, and a call past what is left asks as usual. It resolves
+with `{allowed, credits}`. It works only from a person's click or key press in a
+project Step (never from Chat), up to 2,000 credits (`VIEW_LIMITS.allowanceCredits`).
+
 ### Audio and video playback
 
-`await StillMade.previewMedia(reference)` opens an authorized `audio` or `video`
-reference as a temporary playback copy and returns `{kind, url, mimeType, bytes}`.
+`await StillMade.previewMedia(reference)` opens an authorized `image`, `audio` or `video`
+reference as a temporary copy and returns `{kind, url, mimeType, bytes}`. A picture comes back as the
+original file at full size (an animated GIF keeps moving); `previewImage` gives a small still instead.
+A frame view keeps up to `FRAME_VIEW_LIMITS.mediaPreviews` media previews open at once (a standard view two);
+release one with `StillMade.releaseMedia(url)` when it scrolls away or closes.
 Assign its URL to an existing `<audio controls>` or `<video controls>` element.
 The host requires an exact reference from this Block’s bound input, an explicitly
 selected project asset, permitted project context, or a host-recorded output.

package/examples/custom-interface.stillmade.json

@@ -75,8 +75,8 @@
     }
   ],
   "view": {
-    "html": "<main class=\"sm-block\" data-layout=\"split\"><output class=\"sm-stage\" id=\"result\" aria-live=\"polite\" data-stillmade-state=\"empty\">Your result shows here</output><div class=\"sm-field\"><label for=\"source\">Text</label><textarea id=\"source\" data-stillmade-input=\"text\" data-stillmade-share=\"text\"></textarea></div><div class=\"sm-actions\"><button class=\"sm-primary\" id=\"run\" data-stillmade-action=\"run\">Clean text</button></div></main>",
-    "css": "#result{place-items:start;min-height:160px;white-space:pre-wrap;overflow-wrap:anywhere;color:var(--fg)}#result[data-stillmade-state=\"empty\"]{place-items:center;color:var(--fg-muted)}",
+    "html": "<main class=\"sm-block\" data-layout=\"split\"><section class=\"sm-stage\" id=\"stage\" aria-live=\"polite\"><div class=\"sm-actions\"><button class=\"sm-primary\" id=\"run\" data-stillmade-action=\"run\">Clean text</button></div><output id=\"result\" data-stillmade-state=\"empty\">Your result shows here</output></section><div class=\"sm-field\"><label for=\"source\">Text</label><textarea id=\"source\" data-stillmade-input=\"text\" data-stillmade-share=\"text\"></textarea></div></main>",
+    "css": "#stage{min-height:160px}#result{justify-self:stretch;white-space:pre-wrap;overflow-wrap:anywhere;color:var(--fg)}#result[data-stillmade-state=\"empty\"]{justify-self:center;color:var(--fg-muted)}",
     "javascript": "const source=document.getElementById(\"source\"), button=document.getElementById(\"run\"), result=document.getElementById(\"result\"); StillMade.onInput(input=>{source.value=input.text||\"\";document.querySelector(\"main\").dataset.stillmadeState=source.value?\"populated\":\"empty\"}); button.addEventListener(\"click\",async()=>{button.disabled=true;result.dataset.stillmadeState=\"loading\";result.textContent=\"Cleaning…\";try{const output=await StillMade.run({text:source.value});result.dataset.stillmadeState=\"success\";result.textContent=output.text||\"Empty result\"}catch(error){result.dataset.stillmadeState=\"error\";result.textContent=error.message}finally{button.disabled=false}});"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stillmade-sdk",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "description": "StillMade Block SDK, CLI and examples",
   "license": "PolyForm-Shield-1.0.0",
   "type": "module",

package/packages/block-cli/cli.js

@@ -78,7 +78,7 @@ const moduleExecutor=(pkg,host)=>{const files=moduleFiles.get(pkg);return files?
 // storage, project reads): on with --mock, or whenever the folder has
 // tests/mocks.json. They never contact a provider or spend credits.
 const blockFolder=async path=>{try{if((await lstat(path)).isDirectory())return path;}catch{}return null;};
-const localFileReader=folder=>async name=>{
+export const localFileReader=folder=>async name=>{
  if(!folder)throw Object.assign(new Error('Local files are read from a Block folder.'),{code:'MODULE_FILE_READ'});
  const full=resolve(folder,name);
  if(!full.startsWith(folder+sep))throw Object.assign(new Error(`${name} is outside the Block folder.`),{code:'MODULE_FILE_READ'});
@@ -125,11 +125,23 @@ async function dev(path,options){
  }
  if(!(await lstat(path)).isDirectory())throw Object.assign(new Error('dev previews a Block folder.'),{code:'USAGE'});
  const {startDevServer}=await import('./dev-server.js');
- let mock,mocksText,memory,answered;
- // Files the person picks in the preview's own-file mode: kept in this process only, read by the run as themselves
- // (November 1, 2026, owner: try a Block on your own video, not only its example).
+ const picks=pickedFiles(),session=blockSession(path,picks);
+ const link=live?{origin:liveSite(site),key:randomBytes(24).toString('base64url')}:undefined;
+ const server=await startDevServer({folder:path,port,build,...session,pick:picks.pick,live:link});
+ const liveUrl=link&&`${link.origin}/create/import?live=${encodeURIComponent(`${server.url}/__live/${link.key}`)}`;
+ return {dev:server.url,folder:path,...(build?{build}:{}),...(liveUrl?{live:liveUrl}:{}),close:server.close};
+}
+// Files the person picks in the preview's own-file mode: kept in this process only, read by the run as themselves
+// (November 1, 2026, owner: try a Block on your own video, not only its example).
+export function pickedFiles(){
  const picked=new Map(),pickedMedia=url=>picked.get(url)||null;
  const pick=(bytes,{mediaType,name})=>{const id=randomBytes(8).toString('hex'),safe=String(name||'file').replace(/[^\w.-]+/g,'-').slice(0,80)||'file',url=`/api/media/picked/${id}/${safe}`;picked.set(url,{bytes,mediaType});return url;};
+ return {pick,pickedMedia};
+}
+// One Block folder in the preview: load the current source, run it with stand-ins, serve its media, pack it.
+// `dev` on a Block folder has one; `dev` on a workspace has one per Block.
+export function blockSession(path,{pickedMedia}){
+ let mock,mocksText,memory,answered;
  const load=async()=>{
   let pkg;
   try{pkg=await readPackage(path);}catch(error){return {problem:`${error.message}${error.code?` (${error.code})`:''}`};}
@@ -163,10 +175,7 @@ async function dev(path,options){
  const bundle=async({pkg})=>hasDigestFiles(pkg)
   ?{fileName:`${pkg.manifest.id}-${pkg.manifest.version}${MODULE_BUNDLE_SUFFIX}`,source:JSON.stringify(createModuleBundle(pkg,moduleFiles.get(pkg)))}
   :{fileName:`${pkg.manifest.id}-${pkg.manifest.version}.stillmade.json`,source:JSON.stringify(pkg)};
- const link=live?{origin:liveSite(site),key:randomBytes(24).toString('base64url')}:undefined;
- const server=await startDevServer({folder:path,port,build,load,run,media,pick,live:link,bundle});
- const liveUrl=link&&`${link.origin}/create/import?live=${encodeURIComponent(`${server.url}/__live/${link.key}`)}`;
- return {dev:server.url,folder:path,...(build?{build}:{}),...(liveUrl?{live:liveUrl}:{}),close:server.close};
+ return {load,run,media,bundle};
 }
 // own: the hosts that answered fixtures from their own mocks.
 const standInNote=(mock,own=[])=>{const calls=[...(mock?.calls||[]).map(call=>[call,MOCKS_FILE]),...own.flatMap(host=>host.calls.map(call=>[call,'fixture mocks']))];return calls.length?{standIns:calls.map(([call,file])=>({api:call.api,name:call.name,source:call.source==='mocks'?file:'recorded stand-in'})),liveVerified:false}:{};};
@@ -194,6 +203,20 @@ export async function readPackage(path) {
   if(files)moduleFiles.set(pkg,files);
   return pkg;
 }
+// A Project Type file ready to check or run: in a workspace its Steps may name a Block by folder (workspace.js
+// compileWorkflow), and its packages may name a packed Block or a Block folder, or embed a packed module bundle
+// (type-packages.js).
+const typeMocks=new WeakMap();
+async function projectTypeFrom(type,path){
+ const {findWorkspace,compileWorkflow,workspaceMocks}=await import('./workspace.js');
+ const found=await findWorkspace(path);if(found)type=await compileWorkflow(type,{root:found.root,file:path});
+ const result=await embedTypePackages(type,{folder:dirname(path),resolvePath:resolve,read:async file=>{const block=await readPackage(file);return {pkg:block,files:moduleFiles.get(block)};}});
+ if(found)typeMocks.set(result,await workspaceMocks(found.root));
+ return result;
+}
+// The recorded answers a Type's Block brings from its workspace folder, for typeModuleRunner.
+export const typeMocksFor=type=>{const mocks=typeMocks.get(type);return mocks?pkg=>mocks.get(`${pkg?.manifest?.id}@${pkg?.manifest?.version}`):undefined;};
+export async function loadProjectType(path){const type=await readPackage(path);if(!type?.stages)throw new Error(`${basename(path)} is not a Project Type.`);return projectTypeFrom(type,path);}
 export const MODULE_EXECUTION_REQUIRED_MESSAGE='This Block runs code, so the gate a hook starts does not run it. Run `stillmade-block gate .` (`npx stillmade-block gate .` in an npm project) yourself and report the status it prints.';
 export async function main(rawArgs) {
   // --no-module-execution: what the gate a hook starts passes to ready, so a module Block is refused
@@ -201,14 +224,62 @@ export async function main(rawArgs) {
   const mockRequested=rawArgs.includes('--mock'),noModuleExecution=rawArgs.includes('--no-module-execution'),args=rawArgs.filter(value=>value!=='--mock'&&value!=='--no-module-execution');
   if(!args.length||['help','--help','-h'].includes(args[0])||args.includes('--help')||args.includes('-h'))return {help:HELP};
   if(args[0]==='templates'||args[0]==='create'&&args.includes('--list'))return {templates:Object.entries(TEMPLATES).map(([name,template])=>({name,runtime:template.runtime,description:template.description}))};
+  // A command that works on a folder may start with its options; the folder is then this one (`dev --port 4811`).
+  if(['dev','test','validate','gate','pack','build','ready','inspect','permissions'].includes(args[0])&&args[1]?.startsWith('--'))args.splice(1,0,'.');
+  // In a workspace a Block may be named by its folder alone (`test listing-facts` for blocks/listing-facts; November 6,
+  // 2026: a coding agent's `test listing-facts` from the workspace folder failed with ENOENT).
+  if(['validate','test','run','preview','pack','ready','inspect','permissions','types','dev'].includes(args[0])&&args[1]&&!args[1].startsWith('--')){
+   const named=args[1];let missing=false;try{await lstat(resolve(named));}catch{missing=true;}
+   if(missing&&/^[a-z][a-z0-9-]{0,59}$/.test(named)){const {findWorkspace,BLOCKS_DIR,WORKFLOWS_DIR}=await import('./workspace.js'),found=await findWorkspace(process.cwd());
+    if(found){for(const candidate of [join(found.root,BLOCKS_DIR,named),join(found.root,WORKFLOWS_DIR,`${named}.json`)]){try{await lstat(candidate);args[1]=candidate;break;}catch{}}}}
+  }
   const [command, target = '.', extra] = args, path = resolve(target);
+  // A workspace: several Blocks, shared code and workflows in one folder (workspace.js).
+  if(command==='init'){
+   if(args.length<2||target.startsWith('--'))throw Object.assign(new Error('Name the folder to create: stillmade-block init my-blocks [--name "Listing kit"]'),{code:'USAGE'});
+   const {initWorkspace}=await import('./workspace.js');
+   return initWorkspace(path,{name:optionValue(args,'--name')});
+  }
+  if(command==='add'){
+   const {requireWorkspace,folderName,adoptWorkspaceBlock,BLOCKS_DIR,isWorkspaceRoot}=await import('./workspace.js');
+   if(args.length<2||target.startsWith('--'))throw Object.assign(new Error('Name the Block: stillmade-block add price-drop-alert [template]'),{code:'USAGE'});
+   const {root}=await requireWorkspace(process.cwd(),'add'),name=folderName(target),folder=join(root,BLOCKS_DIR,name);
+   if(await isWorkspaceRoot(folder))throw Object.assign(new Error(`${name} is a workspace.`),{code:'USAGE'});
+   const template=extra&&!extra.startsWith('--')?extra:undefined;
+   const app=optionValue(args,'--app'),created=await main(['create',folder,...(template?[template]:[]),...(app?['--app',app]:[])]);
+   const adopted=await adoptWorkspaceBlock(folder);
+   return {...created,workspace:root,block:name,...(adopted.source?{source:adopted.source}:{}),next:`Build the Block in ${BLOCKS_DIR}/${name}${adopted.source?` (edit its code in ${BLOCKS_DIR}/${name}/src/main.js only: module/main.js is a copy that \`stillmade-block build\`, test, gate and pack write from it)`:''}, replace its placeholder \`description\` and the copyright holder in \`provenance.notice\`, write its feature map (\`manifest.features\`), then run \`stillmade-block gate\` from the workspace folder. Do not call the Block ready until the gate passes for it.`};
+  }
+  if(command==='add-type'){
+   const {requireWorkspace,addWorkflow}=await import('./workspace.js');
+   if(args.length<2||target.startsWith('--'))throw Object.assign(new Error('Name the workflow: stillmade-block add-type listing-video [block ...] [--when schedule]'),{code:'USAGE'});
+   const {root}=await requireWorkspace(process.cwd(),'add-type');
+   const when=optionValue(args,'--when'),blocks=args.slice(2).filter((value,index,list)=>!value.startsWith('--')&&list[index-1]!=='--when');
+   return addWorkflow(root,target,{blocks,...(when?{config:{first:await whenStage(when)}}:{})});
+  }
+  if(command==='build'){
+   const {requireWorkspace,buildWorkspace}=await import('./workspace.js');
+   const {root}=await requireWorkspace(path,'build'),report=await buildWorkspace(root);
+   if(report.failed.length)throw Object.assign(new Error(`Build failed for ${report.failed.map(item=>item.block).join(', ')}`),{code:'BUILD',report});
+   return {workspace:root,...report};
+  }
+  if(['test','validate','pack','dev'].includes(command)){
+   const {isWorkspaceRoot}=await import('./workspace.js');
+   if(await isWorkspaceRoot(path)){
+    if(command==='dev')return workspaceDev(path,args.slice(2));
+    if(command==='pack'){const {packWorkspace}=await import('./workspace-pack.js');return packWorkspace(path,{main,output:extra&&!extra.startsWith('--')?resolve(extra):undefined});}
+    return workspaceCheck(command,path,args.slice(2),mockRequested);
+   }
+  }
   if (command === 'create-type') {
     await writeFile(path, JSON.stringify(TYPE_SCAFFOLD, null, 2), { flag: 'wx' });
     return { created: path, kind: 'type' };
   }
   if (command === 'create') {
     if(args.length<2)throw Object.assign(new Error('Name the folder to create: stillmade-block create my-block [template]'),{code:'USAGE'});
-    const template=templateNamed(extra),files=await template.files({folder:path});
+    const template=templateNamed(extra&&!extra.startsWith('--')?extra:undefined),app=optionValue(args,'--app');
+    if(app&&template.name!=='connector')throw Object.assign(new Error('--app goes with the connector template: create <folder> connector --app gmail'),{code:'USAGE'});
+    const files=await template.files({folder:path,...(app?{app}:{})});
     // Every new Block starts with a feature map (one entry from its name and description) for the builder to rewrite as it grows.
     {const created=JSON.parse(files['stillmade.block.json']);if(!created.features&&!created.stages){created.features=blockFeatures(created).map(({source,...feature})=>feature);files['stillmade.block.json']=`${JSON.stringify(created,null,2)}\n`;}
      // The new Block is named for its folder, never the example it started from (November 1, 2026: a no-context agent's
@@ -246,8 +317,7 @@ export async function main(rawArgs) {
   }
   if (!['validate', 'test', 'preview', 'pack', 'inspect', 'remix', 'ready', 'permissions'].includes(command)) throw Object.assign(new Error(`Unknown command ${command}. Run stillmade-block --help for the commands.`),{code:'USAGE'});
   let pkg = await readPackage(path);
-  // A Type's packages may name a packed Block or a Block folder, or embed a packed module bundle (type-packages.js).
-  if(pkg?.stages)pkg=await embedTypePackages(pkg,{folder:dirname(path),resolvePath:resolve,read:async file=>{const block=await readPackage(file);return {pkg:block,files:moduleFiles.get(block)};}});
+  if(pkg?.stages)pkg=await projectTypeFrom(pkg,path);
   if(args.includes('--original')){
     if(command!=='pack'||!extra||extra.startsWith('--'))throw new Error('Use pack <source> <output.stillmade-block> --original only for your own original implementation.');
     pkg=withOriginalSource(pkg);
@@ -299,7 +369,7 @@ export async function main(rawArgs) {
     if (command === 'inspect') return { id: pkg.id, version: pkg.version, stages: pkg.stages, workspace: typeWorkspaceSupport(pkg) };
     if(command==='permissions')return {id:pkg.id,blocks:(pkg.packages||[]).map(block=>({id:block.manifest.id,summary:summarizePermissions(block.manifest)}))};
     // Module Steps run in the SDK's local module runner, as `test` and `preview` run a module Block (type-packages.js).
-    const runner=typeModuleRunner({mock:mockRequested,readLocalFile:localFileReader(dirname(path))});
+    const runner=typeModuleRunner({mock:mockRequested,readLocalFile:localFileReader(dirname(path)),...(typeMocksFor(pkg)?{mocksFor:typeMocksFor(pkg)}:{})});
     const standIns=()=>{const calls=runner.calls();return calls.length?{standIns:calls,liveVerified:false}:{};};
     if (command === 'preview') {const preview=await previewProjectType(pkg,{inputs:extra ? JSON.parse(await readFile(resolve(extra),'utf8')) : {},run:runner.run});return {...preview,...standIns()};}
     // Export source without executing local or hosted code. This is not an
@@ -416,6 +486,48 @@ export async function main(rawArgs) {
   await writeFile(output, JSON.stringify(pkg, null, 2), { flag: packFlag(extra) });
   return { file: output, digest: report.digest, tests: report.results.length };
 }
+async function workspaceDev(root,options){
+ let port=4800;
+ for(let index=0;index<options.length;index++){
+  const value=options[index];
+  if(value==='--port'){port=Number(options[++index]);if(!Number.isInteger(port)||port<0||port>65535)throw Object.assign(new Error('--port takes a port number'),{code:'USAGE'});}
+  else throw Object.assign(new Error(`dev on a workspace does not take ${value}. --live and --build work on one Block folder (dev blocks/<name>).`),{code:'USAGE'});
+ }
+ const [{startDevServer},{workspaceProvider}]=await Promise.all([import('./dev-server.js'),import('./workspace-dev.js')]);
+ const picks=pickedFiles(),workspace=await workspaceProvider(root,{main,picks});
+ const server=await startDevServer({folder:root,port,workspace,pick:picks.pick});
+ return {dev:server.url,folder:root,workspace:true,close:server.close};
+}
+// The When Step that starts an automation workflow (StillMade's sm.when, its newest version): what starts each run is
+// turned on in the project's Automation page; an app event here is the start it suggests there.
+async function whenStage(kind){
+ const latest=BUILTIN_BLOCKS.filter(block=>block.manifest?.id==='sm.when').map(block=>block.manifest.version).sort((a,b)=>{const x=a.split('.').map(Number),y=b.split('.').map(Number);for(let i=0;i<3;i++)if(x[i]!==y[i])return x[i]-y[i];return 0;}).pop();
+ if(!latest)throw Object.assign(new Error('This SDK has no When Step.'),{code:'USAGE'});
+ const app=/^app:([a-z0-9][a-z0-9-]{0,79})\/([A-Za-z0-9_]{1,120})$/.exec(kind);
+ if(!['schedule','webhook'].includes(kind)&&!app)throw Object.assign(new Error('--when takes schedule, webhook, or an app event such as app:gmail/GMAIL_NEW_GMAIL_MESSAGE'),{code:'USAGE'});
+ return {id:'when',blockId:'sm.when',version:latest,label:kind==='schedule'?'On a schedule':kind==='webhook'?'When a webhook is called':'When the app has something new',...(app?{config:{start:{app:`app:${app[1]}`,event:app[2]}}}:{})};
+}
+// The value after a --flag, or undefined.
+function optionValue(args,flag){const index=args.indexOf(flag);if(index<0)return undefined;const value=args[index+1];if(!value||value.startsWith('--'))throw Object.assign(new Error(`${flag} takes a value`),{code:'USAGE'});return value;}
+// test or validate at a workspace's top: every Block, then every workflow, each judged as it would be alone.
+async function workspaceCheck(command,root,options,mock){
+ const {workspaceItems,buildWorkspace,unbundledImport,BLOCKS_DIR,WORKFLOWS_DIR}=await import('./workspace.js');
+ const build=await buildWorkspace(root);
+ const {blocks,workflows}=await workspaceItems(root),results=[];
+ const one=async(item,label)=>{
+  if(item.problem)return {item:label,kind:item.kind,passed:false,message:item.problem};
+  const failed=build.failed.find(entry=>entry.block===item.name);if(failed)return {item:label,kind:item.kind,passed:false,message:`Build failed: ${failed.message}`};
+  if(item.kind==='block'){const loose=await unbundledImport(item.path);if(loose)return {item:label,kind:item.kind,passed:false,message:`${loose.file} imports ${loose.specifier}. A Block runs one file: keep the code in src/main.js and run \`stillmade-block build\`.`};}
+  try{const result=await main([command,item.path,...options,...(mock?['--mock']:[])]);return {item:label,kind:item.kind,passed:true,...(Array.isArray(result?.results)?{tests:result.results.length}:{})};}
+  catch(error){const failing=(error.report?.results||[]).filter(entry=>entry&&entry.passed===false).slice(0,5).map(entry=>`${entry.name}: ${entry.message||'failed'}`);return {item:label,kind:item.kind,passed:false,message:[error.message,...failing].join('\n')};}
+ };
+ for(const item of blocks)results.push(await one(item,`${BLOCKS_DIR}/${item.name}`));
+ for(const item of workflows)results.push(await one(item,`${WORKFLOWS_DIR}/${item.name}.json`));
+ const report={workspace:root,command,passed:results.every(item=>item.passed),results,...(build.built.length?{built:build.built}:{})};
+ if(!results.length)throw Object.assign(new Error('This workspace has no Blocks yet. Add one with `stillmade-block add <name> [template]`.'),{code:'USAGE'});
+ if(!report.passed)throw Object.assign(new Error(`${results.filter(item=>!item.passed).length} of ${results.length} items need attention`),{report});
+ return report;
+}
 // pack replaces the file it wrote before under its own name, so packing again after a fix just works; an output path the
 // person names is never overwritten (November 1, 2026: a no-context agent's second pack failed with EEXIST).
 function packFlag(output){return output?'wx':'w';}