stillmade-sdk 0.1.40 → 0.1.42

package/packages/block-platform/host-release-manifests.js

@@ -500,5 +500,100 @@ export const HOST_RELEASE_MANIFEST_SNAPSHOTS=Object.freeze([
       "filesystem": [],
       "secrets": []
     }
+  },
+  {
+    "schemaVersion": 1,
+    "sdkVersion": "0.1.0",
+    "id": "sm.voiceover",
+    "name": "Voiceover",
+    "version": "1.2.0",
+    "kind": "workspace",
+    "runtime": "host",
+    "description": "Turn your script into speech, or record your own voice.",
+    "inputs": {
+      "input": {
+        "type": "script",
+        "primary": true,
+        "role": "narration_script",
+        "required": false,
+        "description": "The words the voice says, from any Step before this one. They arrive as a suggestion you accept before they replace your script.",
+        "semantic": "narration_script"
+      }
+    },
+    "outputs": {
+      "output": {
+        "type": "audio",
+        "primary": true,
+        "role": "narration_audio",
+        "description": "The voiceover audio.",
+        "semantic": "narration_audio"
+      },
+      "timing": {
+        "type": "transcript",
+        "description": "Every spoken word with its start and end time, for Steps that cut to the voice.",
+        "semantic": "timed_transcript"
+      },
+      "spokenScript": {
+        "type": "script",
+        "description": "The words of the voice, as the script for Steps that work from it.",
+        "semantic": "narration_script"
+      }
+    },
+    "permissions": {
+      "project": [],
+      "network": [],
+      "filesystem": [],
+      "secrets": []
+    }
+  },
+  {
+    "schemaVersion": 1,
+    "sdkVersion": "0.1.0",
+    "id": "sm.panel-strip",
+    "name": "Image Panels",
+    "version": "1.2.0",
+    "kind": "workspace",
+    "runtime": "host",
+    "description": "Turn your script into pictures that play with the voice.",
+    "inputs": {
+      "narrationTiming": {
+        "type": "transcript",
+        "primary": true,
+        "required": false,
+        "description": "Timed narration words from an earlier Step. When connected and filled, the panels are cut to these timings instead of the project's own voiceover.",
+        "semantic": "timed_transcript"
+      },
+      "narrationAudio": {
+        "type": "audio",
+        "required": false,
+        "description": "The narration audio that goes with those timings.",
+        "semantic": "narration_audio"
+      },
+      "narrationScript": {
+        "type": "script",
+        "required": false,
+        "description": "Narration script from an earlier Step, used for the story when no timed words are connected.",
+        "semantic": "narration_script"
+      }
+    },
+    "outputs": {
+      "panels": {
+        "type": "panel-document",
+        "primary": true,
+        "role": "image_panel_document",
+        "description": "The complete Image Panels document for the next Step.",
+        "semantic": "image_panel_document"
+      },
+      "images": {
+        "type": "image[]",
+        "description": "Each panel's current picture, in story order."
+      }
+    },
+    "permissions": {
+      "project": [],
+      "network": [],
+      "filesystem": [],
+      "secrets": []
+    }
   }
 ].map(manifest=>Object.freeze(manifest)));

package/packages/block-platform/native-host-inventory.js

@@ -352,7 +352,8 @@ export const NATIVE_HOST_INVENTORY=[
     "id": "sm.panel-strip",
     "versions": [
       "1.0.0",
-      "1.1.0"
+      "1.1.0",
+      "1.2.0"
     ],
     "phase": "shotMap",
     "kind": "image-panels",
@@ -381,7 +382,19 @@ export const NATIVE_HOST_INVENTORY=[
         "priority": 10
       }
     ],
-    "host": {}
+    "host": {},
+    "releaseHosts": {
+      "1.2.0": {
+        "canvasNode": "workspaceHostNode",
+        "ports": {
+          "narrationAudio": "in:narrationAudio",
+          "narrationTiming": "in:narrationTiming",
+          "narrationScript": "in:narrationScript",
+          "panels": "out:panels",
+          "images": "out:images"
+        }
+      }
+    }
   },
   {
     "schemaVersion": 1,
@@ -609,11 +622,23 @@ export const NATIVE_HOST_INVENTORY=[
     "id": "sm.voiceover",
     "versions": [
       "1.0.0",
-      "1.1.0"
+      "1.1.0",
+      "1.2.0"
     ],
     "phase": "voiceover",
     "kind": "voiceover",
-    "host": {}
+    "host": {},
+    "releaseHosts": {
+      "1.2.0": {
+        "canvasNode": "workspaceHostNode",
+        "ports": {
+          "input": "in:input",
+          "output": "out:output",
+          "timing": "out:timing",
+          "spokenScript": "out:spokenScript"
+        }
+      }
+    }
   },
   {
     "schemaVersion": 1,

package/packages/block-platform/node-defaults.js

@@ -1,5 +1,6 @@
 export function defaultNodeData(type, request = {}, sceneNumber = 1, {llmModel, voiceId} = {}) {
   if (type === 'productionWorkspaceNode')return {title:request.name || 'Production workspace',prompt:'',messages:[],versions:[],status:'pending'};
+  if (type === 'workspaceHostNode')return {title:request.name || 'Workspace',workspaceOutputs:{}};
   if (type === 'bibleNode') return { title: request.name || 'Manual Blueprint Node', description: request.description || 'Manual node.' };
   if (type === 'textPromptNode') {
     return {

package/packages/block-platform/project-context.js

@@ -22,7 +22,7 @@ const sceneFields=['title','name','sceneNumber','location','locationId','timeOfD
 const shotFields=['shotId','sceneId','sceneNumber','shotNumber','title','name','description','shotDescription','voiceoverText','text','dialogue','hasDialogue','characterSpeaking','characterId','characterIds','charactersPresent','location','locationId','startTime','endTime','startMs','durationMs','estimatedScreenTime','shotSize','shotType','cameraSize','cameraMotion','fulfillment','vsmId','panelId','type'];
 // URL-only histories (Panels and imported editor media) have no persisted version
 // IDs. A content-derived identifier survives history trimming and reordering.
-function urlVersion(url) {
+export function urlVersion(url) {
  let a=2166136261,b=5381;
  for(let i=0;i<url.length;i++){a=Math.imul(a^url.charCodeAt(i),16777619);b=Math.imul(b,33)^url.charCodeAt(i);}
  return `url-${(a>>>0).toString(16)}${(b>>>0).toString(16)}-${url.length}`;

package/packages/block-platform/script-handoff.js

@@ -3,7 +3,7 @@ import {isScriptWriterHandoff} from './script-writer.js';
 import {packageForStage} from './stage-package.js';
 
 const SDK_SCRIPT_RUNTIMES = new Set(['recipe', 'javascript', 'capability']);
-const VOICEOVER_VERSIONS = new Set(['1.0.0', '1.1.0']);
+const VOICEOVER_VERSIONS = new Set(['1.0.0', '1.1.0', '1.2.0']);
 
 // This identifies an explicit document handoff, not a Canvas wire or permission
 // to replace narration. The host must separately verify the pinned source,

package/packages/block-platform/step-groups.js

@@ -3,7 +3,9 @@
 // Steps in `stages`. Each part stays a real Step, so its permissions, approvals,
 // credits, memory and runs are unchanged; groups only change what people see.
 import {assert,plain} from '../block-sdk/contracts.js';
-import {BLOCK_NAME_MAX_LENGTH} from '../block-sdk/builder-contract.js';
+// The Block name limit, mirrored from builder-contract.js (the rule lives there; scripts/step-groups-name-length.test.js
+// pins the two): importing it pulled 36 KB of builder prompt text into the studio's startup graph for one number.
+export const BLOCK_NAME_MAX_LENGTH=40;
 
 export const MAX_GROUP_PARTS=12;
 const GROUP_KEYS=['id','label','stages','settings','result'];

package/packages/block-sdk/audio-generation-example.js

@@ -3,12 +3,12 @@ import {EXAMPLE_PROVENANCE} from './example-license.js';
 // prompt and a suggested length; the person running it chooses the length and
 // pays with StillMade credits at the app's prices.
 export const audioMusic={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.score-a-scene',version:'1.0.0',name:'Score a scene',description:'Generate a short music bed for a scene from a written mood brief.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{brief:{type:'brief',primary:true,semantic:'music_brief',required:true,description:'Mood, tempo and instruments for the music bed.'}},outputs:{music:{type:'audio',primary:true,semantic:'music_bed',description:'Generated music bed.'}},permissions:{project:[],capabilities:['audio.music'],network:[],filesystem:[],secrets:[]},ui:[]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.score-a-scene',action:{label:'Generate music',running:'Generating music…'},version:'1.0.0',name:'Score a scene',description:'Generate a short music bed for a scene from a written mood brief.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{brief:{type:'brief',primary:true,semantic:'music_brief',required:true,description:'Mood, tempo and instruments for the music bed.'}},outputs:{music:{type:'audio',primary:true,semantic:'music_bed',description:'Generated music bed.'}},permissions:{project:[],capabilities:['audio.music'],network:[],filesystem:[],secrets:[]},ui:[]},
  capability:{schemaVersion:1,operation:'audio.music',prompt:{$input:'brief'},output:'music',settings:{durationSec:30}},
  tests:[{name:'Calm piano bed',input:{brief:{schemaVersion:1,text:'Calm solo piano, slow tempo, warm and hopeful.'}},expectations:{music:{kind:'audio',format:'any',minDuration:1,maxDuration:241,minBytes:45,maxBytes:134217728}}}],
 };
 export const audioSfx={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.foley-cue',version:'1.0.0',name:'Foley cue',description:'Generate a short sound effect from a written description.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{description:{type:'text',primary:true,semantic:'sound_description',required:true,description:'The sound to create.'}},outputs:{sound:{type:'audio',primary:true,semantic:'sound_effect',description:'Generated sound effect.'}},permissions:{project:[],capabilities:['audio.sfx'],network:[],filesystem:[],secrets:[]},ui:[]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.foley-cue',action:{label:'Generate sound',running:'Generating sound…'},version:'1.0.0',name:'Foley cue',description:'Generate a short sound effect from a written description.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{description:{type:'text',primary:true,semantic:'sound_description',required:true,description:'The sound to create.'}},outputs:{sound:{type:'audio',primary:true,semantic:'sound_effect',description:'Generated sound effect.'}},permissions:{project:[],capabilities:['audio.sfx'],network:[],filesystem:[],secrets:[]},ui:[]},
  capability:{schemaVersion:1,operation:'audio.sfx',prompt:{$input:'description'},output:'sound',settings:{durationSec:3}},
  tests:[{name:'Door creak',input:{description:'A slow wooden door creak in a quiet room.'},expectations:{sound:{kind:'audio',format:'any',minDuration:.1,maxDuration:23,minBytes:45,maxBytes:134217728}}}],
 };

package/packages/block-sdk/builder-contract.js

@@ -9,7 +9,7 @@
 import {HOSTED_OPERATION_NAMES} from './contracts.js';
 
 export const BUILDER_CONTRACT_ID='stillmade.block-builder';
-export const BUILDER_CONTRACT_VERSION='1.12.0';
+export const BUILDER_CONTRACT_VERSION='1.17.0';
 export const BUILDER_CONTRACT_STAMP=`${BUILDER_CONTRACT_ID}@${BUILDER_CONTRACT_VERSION}`;
 export const BUILDER_CONTRACT_DOCS_PATH='/docs/build/block-builder-contract';
 // Block names appear in step bars, cards and pickers; new releases keep them short.
@@ -72,9 +72,20 @@ const SECTIONS=Object.freeze([
  rule('input-words','block',
   'Name each input in the job\'s words (`sermonVideo`, not `video`): StillMade words its drop area from the name.',
   '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.'),
+ // November 2, 2026 (owner): every screen speaks the job, as a product made only for it would, and stays quiet. The same
+ // day (owner, of four tiles each saying "Only on the device it was added from"): "if it's a notification make it a
+ // notification": state is one StillMade notification or nothing, never a sentence on the page or one per item.
+ rule('job-words','block',
+  'Speak the job unless the person or creator asks otherwise: `manifest.action` names the button, required whenever StillMade draws it ("Plan the tour"; AI pictures, video or sound start with Generate, never "Make it"), one solid `sm-primary`, progress in the job\'s units, one line per problem, no notes on how the Block works or its state (one StillMade notification at most, never one per item), `date` inputs for days and times, plain input names so "Use a reference" fills them, posting as its own connector Step. Clear every Wording note `gate` lists.',
+  'These are StillMade\'s defaults: unless the person or the creator asked for something else, every screen speaks the job in its own words and adds nothing else. `manifest.action` names the Step\'s button, {label:"Plan the tour", running:"Planning the tour…"}, and StillMade adds the price ("Plan the tour · 1 credit"). Every Block whose Step shows StillMade\'s button declares it: any Block without its own screen, and any that calls operations. Without it StillMade can only guess from the Block\'s name or output ("Make clips"), and the readiness gate and StillMade\'s own builder send the Block back until it names the job. When the Block makes a picture, video or sound with AI the label starts with Generate and says what ("Generate tour", "Generate voiceover"); one that cuts or renders the person\'s own media says Make ("Make 6 clips"); never "Make it", "Run", "Submit", "Process" or a bare "Generate". The main button stands out: one solid `sm-primary` in the kit\'s ink, never restyled to the background; everything else is `sm-quiet` or an `sm-icon`, and close is an X icon. Report progress in the job\'s units with `stillmade.progress(fraction, label)` ("Moving through the kitchen, 4 of 9 rooms"), never "Processing". Head the result in the job\'s words ("9 rooms", "Your tour · 44 s"), never "Output". Say a problem in one line with its fix beside it ("No bathroom photo. Guests look for one." and Add photo). Stay quiet: no welcome text, tips under fields, tours or banners, and at most one line of guidance on a screen, only where the next move is not obvious; anything more goes in the input\'s `description`, which StillMade shows behind an (i). Say nothing about how the Block works (where it runs, saving, syncing, recovery, accounts, credits) or where a file is kept: StillMade tells the person what they need as one short notification, or nothing; never a sentence on the page, and never the same line under each item. Every drop area offers "Use a reference", which fills the Step from the person\'s saved photos, videos and notes: media inputs fill by kind, so take `video` or `asset` where a clip works as well as a photo, and text inputs fill by plain names and labels (`productName`, `website`, `brandColors`, `fonts`, `voice`, and `details` or `notes` for the reference\'s note); never build your own reference picker. Days and times are picked, never typed: use the `date` type, which StillMade shows as a calendar, with a list of times when the input is about a time (`postAt`, `startsAt`); a custom view uses `<input type="date">` or `type="datetime-local"`. Posting is a connector Step of its own, and StillMade words its button from the app and action ("Post to Instagram"). Before handing the Block back, clear every Wording note that `gate` and readiness list, unless the person asked for those words.'),
+ // November 2, 2026 (owner): StillMade centers and zooms a screen; an app that lays itself out (a CAD tool) opts out with
+ // data-stillmade-layout="own" and keeps its own layout and Ctrl/Cmd +/- keys. The same day (owner: "implement A absolutely
+ // universally, like in app, platform, sdk, just everywhere"): every <video controls> gets StillMade's player and result
+ // pictures its full-screen button; a video without controls stays the Block's own. Also that day (owner: "there is no
+ // separation and I cannot tell what is going on"): a pick is the kit's ink fill, and media that cannot show is a quiet tile.
  rule('ui','block',
-  'Prefer `manifest.ui`; custom views use the Block kit (`sm-*`) unless a look is named. Pictures over words: preview each option before choosing; few words, fold the rest; buttons carry `data-stillmade-action`; the start button names the action (never "Run") and shows no price (StillMade adds it). A job fits one screen unscrolled and a 320px phone; an app (editor, configurator, CAD tool) works like that app: full canvas, panels, tools, undo, never a form.',
-  'If the capability needs UI, use the Block UI SDK: generated `manifest.ui` controls first; a sandboxed custom view (`view.html`/`view.css`/`view.js`) only when the core interaction needs one. Build custom views from the Block kit the host injects (`block-kit.css`): the result in `sm-stage`, picks as pictures in `sm-choices`, one `sm-primary` naming the action (Write, Generate; never "Run") and no price (StillMade\'s run button adds it), extras in a closed `sm-more`; a look the person names wins. Fit one laptop screen without scrolling: label beside control, status in a few words, files as tiles, rare tools as icons, (i) on unclear controls. These compact rules are for a job or an ingredient. Size the view to the Block\'s tier (block-tier.js): an app, a workspace a person works in for a while (video editor, 3D configurator, CAD or drawing tool), looks and works like that kind of app instead of a compact page: its canvas or stage fills the view, with the panels, toolbars, inspector or timeline such an app has, direct manipulation (select, drag, zoom), keyboard shortcuts and undo; it keeps the host appearance and Block kit controls, its panels may scroll, and on a phone its tools fold into sheets while the canvas stays usable. Never shrink an app into a form of fields and one button. Drop words nobody needs; put helpful ones in a closed `sm-hint`. Mark each button `data-stillmade-action="what it does"` and label each field: Chat presses and fills them. Expose the capability, not the implementation: sensible defaults, previews, progress, clear errors, visible outputs. Show no raw JSON, internal IDs, filesystem details, provider terms or developer settings unless the Block is a developer tool. When a person chooses among options they need to hear or see (voices, music, fonts, looks, templates, images), let them preview each option before choosing: a sample or thumbnail from the Block\'s own files or the host\'s free samples, never a paid generation. Skip previews only when there is nothing to preview. Choices StillMade owns (voices, models in the run review) already show samples. Follow the host appearance (Light, Dark and White) and one elastic layout: stacked on a 320px phone with no sideways scroll (result first, action pinned), and from 860px the controls left (≤380px), the result filling the right. Short settings sit side by side, each label beside its control (`sm-field`, `sm-settings`; three or four short options as one `data-segmented` row); many items are one line each (`sm-list`) that open in place; input files are small tiles (`sm-gallery data-size="small"`); on a phone chip rows scroll sideways and long lists show three. Compacting moves controls, never deletes them.'),
+  'Prefer `manifest.ui`; custom views use the Block kit (`sm-*`) unless a look is named. Pictures over words: preview each option before choosing; few words, fold the rest; buttons carry `data-stillmade-action`; the start button names the action (never "Run" or "Make it") and shows no price (StillMade adds it). A job fits one screen unscrolled and a 320px phone; an app (editor, configurator, CAD tool) works like that app: full canvas, panels, tools, undo, never a form. An app puts `data-stillmade-layout="own"` on its root: StillMade never centers or zooms it. `<video controls>` gets StillMade\'s player; leave out `controls` when the Block drives playback. A pick keeps the kit\'s ink fill; media that cannot show is a wordless `sm-media-off` tile.',
+  '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.'),
  rule('multiplayer','block',
   'Custom views share edits: `StillMade.onShared`, publish every editable field (`data-stillmade-share`, `bindShared`, `updateShared`), respect `canEdit`, never re-run on remote updates.',
   'Projects are multiplayer. A custom view subscribes through `StillMade.onShared(callback)` and publishes every editable field: give static controls a unique `id` and `data-stillmade-share="field"` (the host owns their synchronization), use `StillMade.bindShared(field, elementId)` for controls created dynamically, and `StillMade.updateShared(values, before, options)` for structured values; private variables and DOM values are not shared. Mark a truly device-only control (playback, hover, device selection) with `data-stillmade-local`. Observe shared outputs as well as state, honor `canEdit` in every mutating callback (read-only participants cannot write), never run, click or call a paid integration in response to a remote update, and preserve conflicting drafts. Shared background work uses `sharedWork` with the `work.shared` permission.'),
@@ -147,7 +158,7 @@ export const BUILDER_CONTRACT=Object.freeze({
  gapClasses:GAP_CLASSES,
 });
 
-const SECTION_TITLES=Object.freeze({'runtime-choice':'Choose the runtime','grounded-text':'Only supplied facts','source-of-truth':'Source of truth','reuse-first':'Reuse first','block-tier':'Three sizes of Block','block-scope':'One job per Step','capability-contract':'Define the capability first','feature-map':'Feature map','compose':'Blocks compose','platform-primitives':'Use platform primitives','no-workarounds':'No hidden workarounds','naming':'Name it briefly','input-words':'Name inputs in the job\'s words','ui':'Interface','multiplayer':'Shared editing','external-services':'External services','dependencies':'Dependencies','security':'Security','lifecycle':'Execution lifecycle','errors':'Useful failures','adapt-to-platform':'Adapt to the platform','verification':'What StillMade verifies','project-types':'Project Types','readiness-report':'Readiness report'});
+const SECTION_TITLES=Object.freeze({'runtime-choice':'Choose the runtime','grounded-text':'Only supplied facts','source-of-truth':'Source of truth','reuse-first':'Reuse first','block-tier':'Three sizes of Block','block-scope':'One job per Step','capability-contract':'Define the capability first','feature-map':'Feature map','compose':'Blocks compose','platform-primitives':'Use platform primitives','no-workarounds':'No hidden workarounds','naming':'Name it briefly','input-words':'Name inputs in the job\'s words','job-words':'Speak the job','ui':'Interface','multiplayer':'Shared editing','external-services':'External services','dependencies':'Dependencies','security':'Security','lifecycle':'Execution lifecycle','errors':'Useful failures','adapt-to-platform':'Adapt to the platform','verification':'What StillMade verifies','project-types':'Project Types','readiness-report':'Readiness report'});
 const inScope=(scope,wanted)=>wanted==='all'||scope==='both'||scope===wanted;
 
 /** Render the contract for a model prompt ('compact'), a guide ('full') or an SDK folder ('agents-md'). */

package/packages/block-sdk/capability-example.js

@@ -2,7 +2,7 @@ import {EXAMPLE_PROVENANCE} from './example-license.js';
 // Portable request; provider/model/payment and real execution approval are
 // selected in StillMade. These fixtures are expectations, not recorded results.
 export const textGenerate={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.script-draft',version:'1.0.0',name:'Draft a short script',description:'Turn a production brief into a short narration draft using an approved text-generation call.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{prompt:{type:'text',primary:true,semantic:'production_brief',required:true,description:'Production brief that guides the narration draft.'}},outputs:{script:{type:'script',primary:true,semantic:'narration_script',description:'A concise narration script based on the supplied brief.'}},permissions:{project:[],capabilities:['text.generate'],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'prompt'}]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.script-draft',action:{label:'Write script',running:'Writing script…'},version:'1.0.0',name:'Draft a short script',description:'Turn a production brief into a short narration draft using an approved text-generation call.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{prompt:{type:'text',primary:true,semantic:'production_brief',required:true,description:'Production brief that guides the narration draft.'}},outputs:{script:{type:'script',primary:true,semantic:'narration_script',description:'A concise narration script based on the supplied brief.'}},permissions:{project:[],capabilities:['text.generate'],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'prompt'}]},
  capability:{schemaVersion:1,operation:'text.generate',prompt:{$input:'prompt'},system:'Write a concise narration script. Return only the script text.',maxTokens:1200,output:'script'},
  tests:[{name:'A short opening narration',input:{prompt:'Write two narration sentences about a quiet forest at sunrise.'},expectations:{script:{kind:'script',minLength:20,maxLength:6000}}}],
 };

package/packages/block-sdk/contracts.js

@@ -128,7 +128,7 @@ export function validateManifest(manifest, { builtIn = false } = {}) {
   const check = (ok, path, message) => { if (!ok) errors.push({ path, message }); };
   try { safeDocument(manifest); } catch (e) { return { valid: false, errors: [{ path: '$', message: e.message }] }; }
   if (!plain(manifest)) return { valid: false, errors: [{ path: '$', message: 'Manifest must be an object' }] };
-  const allowed = ['schemaVersion', 'id', 'name', 'version', 'sdkVersion', 'description', 'kind', 'inputs', 'outputs', 'permissions', 'runtime', 'jobs', 'ui', 'uiLayout', 'entry', 'license', 'provenance', 'summary', 'category', 'platforms', 'state', 'storage', 'semantics', 'desktopTools', 'operations', 'sharedWork', 'triggers', 'features'];
+  const allowed = ['schemaVersion', 'id', 'name', 'version', 'sdkVersion', 'description', 'kind', 'inputs', 'outputs', 'permissions', 'runtime', 'jobs', 'ui', 'uiLayout', 'action', 'entry', 'license', 'provenance', 'summary', 'category', 'platforms', 'state', 'storage', 'semantics', 'desktopTools', 'operations', 'sharedWork', 'triggers', 'features'];
   for (const key of Object.keys(manifest)) check(allowed.includes(key), key, 'Unknown manifest field');
   for (const message of featureMapErrors(manifest)) check(false, 'features', message);
   if(manifest.sharedWork!==undefined){try{validateSharedWorkContract(manifest.sharedWork);}catch(error){check(false,'sharedWork',error.message);}check(manifest.permissions?.project?.includes('work.shared'),'sharedWork','Declare the work.shared permission');}
@@ -158,6 +158,8 @@ export function validateManifest(manifest, { builtIn = false } = {}) {
   check(typeof manifest.name === 'string' && manifest.name.trim().length > 0 && manifest.name.length <= 120, 'name', 'Name must be 1–120 characters');
   check(typeof manifest.description === 'string' && manifest.description.trim().length > 0 && manifest.description.length <= 1000, 'description', 'Description must be 1–1000 characters');
   check(KINDS.includes(manifest.kind), 'kind', 'Unsupported block kind');
+  // The Step's button in the job's words ("Plan the tour"), November 2, 2026; StillMade adds the price.
+  if(manifest.action!==undefined){const action=manifest.action,text=(value,max)=>typeof value==='string'&&value.trim().length>0&&value.length<=max&&!/[\r\n]/.test(value);check(plain(action)&&Object.keys(action).every(key=>['label','running'].includes(key))&&text(action.label,40)&&(action.running===undefined||text(action.running,48)),'action','Name the button as {label:"Plan the tour", running:"Planning the tour…"}: a label up to 40 characters, and optional running words up to 48');}
   check(['recipe', 'javascript', 'module', 'comfyui', 'capability', ...(builtIn ? ['host'] : [])].includes(manifest.runtime), 'runtime', 'Installable runtimes are recipe, isolated JavaScript, sandboxed JavaScript modules with WebAssembly, the reviewed ComfyUI adapter, and approved host capabilities');
   if(manifest.state!==undefined){
     const state=manifest.state;

package/packages/block-sdk/examples.js

@@ -1,19 +1,19 @@
 import {EXAMPLE_PROVENANCE} from './example-license.js';
 export const textCleanup = {
-  manifest: { schemaVersion: 1, license: 'MIT', provenance: EXAMPLE_PROVENANCE, sdkVersion: '0.1.0', id: 'example.clean-text', version: '1.0.0', name: 'Clean text', description: 'Trims extra space from text and returns a clean copy for the next step.', kind: 'task', runtime: 'recipe', inputs: { text: { type: 'text', semantic: 'plain_text', required: true, description: 'Text whose surrounding whitespace should be removed.' } }, outputs: { text: { type: 'text', semantic: 'plain_text', description: 'The same text with surrounding whitespace removed.' } }, permissions: { project: [], network: [], filesystem: [], secrets: [] }, ui: [{ control: 'text', port: 'text' }] },
+  manifest: { schemaVersion: 1, license: 'MIT', provenance: EXAMPLE_PROVENANCE, sdkVersion: '0.1.0', id: 'example.clean-text',action:{label:'Clean text',running:'Cleaning text…'}, version: '1.0.0', name: 'Clean text', description: 'Trims extra space from text and returns a clean copy for the next step.', kind: 'task', runtime: 'recipe', inputs: { text: { type: 'text', semantic: 'plain_text', required: true, description: 'Text whose surrounding whitespace should be removed.' } }, outputs: { text: { type: 'text', semantic: 'plain_text', description: 'The same text with surrounding whitespace removed.' } }, permissions: { project: [], network: [], filesystem: [], secrets: [] }, ui: [{ control: 'text', port: 'text' }] },
   recipe: { schemaVersion: 1, steps: [{ id: 'clean', op: 'text.trim', args: { text: { $input: 'text' } } }], outputs: { text: { $step: 'clean' } } },
   tests: [{ name: 'Trims surrounding whitespace', input: { text: '  StillMade\n' }, expected: { text: 'StillMade' } }],
 };
 const pixels = Array.from({ length: 5 * 5 * 4 }, (_, i) => i >= 48 && i <= 50 ? 0 : 255);
 const expanded = pixels.map((v, i) => { const p = Math.floor(i / 4), x = p % 5, y = Math.floor(p / 5); return x >= 1 && x <= 3 && y >= 1 && y <= 3 && i % 4 !== 3 ? 0 : v; });
 export const lineArt = {
-  manifest: { schemaVersion: 1, license: 'MIT', provenance: EXAMPLE_PROVENANCE, sdkVersion: '0.1.0', id: 'example.thicken-lines', version: '1.0.1', name: 'Thicken line art', description: 'Expands dark outlines in an image while preserving surrounding colors, creating a new image for the next production step.', kind: 'task', runtime: 'recipe', inputs: { image: { type: 'image', primary: true, semantic: 'source_image', required: true, description: 'Line-art image whose dark outlines should be expanded.' }, thickness: { type: 'integer', default: 2, min: 1, max: 8, semantic: 'line_thickness', required: false, description: 'Number of pixels by which to expand dark outlines.' }, threshold: { type: 'number', default: 100, min: 0, max: 255, semantic: 'darkness_threshold', required: false, description: 'Brightness threshold used to identify dark outline pixels.' } }, outputs: { image: { type: 'image', primary: true, semantic: 'processed_image', description: 'A new image with expanded dark outlines.' } }, permissions: { project: [], network: [], filesystem: [], secrets: [] }, ui: [{ control: 'asset', port: 'image' }, { control: 'slider', port: 'thickness' }, { control: 'slider', port: 'threshold' }] },
+  manifest: { schemaVersion: 1, license: 'MIT', provenance: EXAMPLE_PROVENANCE, sdkVersion: '0.1.0', id: 'example.thicken-lines',action:{label:'Thicken lines',running:'Thickening lines…'}, version: '1.0.1', name: 'Thicken line art', description: 'Expands dark outlines in an image while preserving surrounding colors, creating a new image for the next production step.', kind: 'task', runtime: 'recipe', inputs: { image: { type: 'image', primary: true, semantic: 'source_image', required: true, description: 'Line-art image whose dark outlines should be expanded.' }, thickness: { type: 'integer', default: 2, min: 1, max: 8, semantic: 'line_thickness', required: false, description: 'Number of pixels by which to expand dark outlines.' }, threshold: { type: 'number', default: 100, min: 0, max: 255, semantic: 'darkness_threshold', required: false, description: 'Brightness threshold used to identify dark outline pixels.' } }, outputs: { image: { type: 'image', primary: true, semantic: 'processed_image', description: 'A new image with expanded dark outlines.' } }, permissions: { project: [], network: [], filesystem: [], secrets: [] }, ui: [{ control: 'asset', port: 'image' }, { control: 'slider', port: 'thickness' }, { control: 'slider', port: 'threshold' }] },
   recipe: { schemaVersion: 1, steps: [{ id: 'outlines', op: 'image.thicken-lines', args: { image: { $input: 'image' }, thickness: { $input: 'thickness' }, threshold: { $input: 'threshold' } } }], outputs: { image: { $step: 'outlines' } } },
   tests: [{ name: 'One dark point expands to a 3×3 square', input: { image: { width: 5, height: 5, data: pixels }, thickness: 1 }, expected: { image: { width: 5, height: 5, data: expanded } } }],
 };
 
 export const javascriptText = {
-  manifest: { ...textCleanup.manifest, id: 'example.word-count', name: 'Word count', description: 'Counts words and returns trimmed text using isolated JavaScript.', runtime: 'javascript', outputs: { text: { type: 'text', semantic: 'plain_text', description: 'The trimmed source text.' }, words: { type: 'integer', semantic: 'word_count', description: 'The number of whitespace-separated words.' } } },
+  manifest: { ...textCleanup.manifest, id: 'example.word-count',action:{label:'Count words',running:'Counting words…'}, name: 'Word count', description: 'Counts words and returns trimmed text using isolated JavaScript.', runtime: 'javascript', outputs: { text: { type: 'text', semantic: 'plain_text', description: 'The trimmed source text.' }, words: { type: 'integer', semantic: 'word_count', description: 'The number of whitespace-separated words.' } } },
   code: 'const text = input.text.trim();\nreturn { text, words: text ? text.split(/\\s+/).length : 0 };',
   tests: [{ name: 'Counts words', input: { text: '  Hello StillMade  ' }, expected: { text: 'Hello StillMade', words: 2 } }, { name: 'Empty text', input: { text: '  ' }, expected: { text: '', words: 0 } }],
 };

package/packages/block-sdk/image-description-example.js

@@ -3,7 +3,7 @@ import {EXAMPLE_PROVENANCE} from './example-license.js';
 // Provider, model, payment and image loading belong to the trusted host. The
 // package owns only the typed contract, bounded analysis instructions and tests.
 export const imageDescription={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.describe-image',version:'1.0.0',name:'Describe an image',description:'Turn one owned image into concise production-ready visual notes.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{image:{type:'image',primary:true,semantic:'source_image',required:true,description:'Owned image to inspect for visible production details.'}},outputs:{description:{type:'text',primary:true,role:'visual_description',semantic:'visual_description',description:'Concise production notes based only on visible image details.'}},permissions:{project:[],capabilities:['image.describe'],network:[],filesystem:[],secrets:[]},ui:[{control:'asset',port:'image'}]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.describe-image',action:{label:'Describe image',running:'Describing image…'},version:'1.0.0',name:'Describe an image',description:'Turn one owned image into concise production-ready visual notes.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{image:{type:'image',primary:true,semantic:'source_image',required:true,description:'Owned image to inspect for visible production details.'}},outputs:{description:{type:'text',primary:true,role:'visual_description',semantic:'visual_description',description:'Concise production notes based only on visible image details.'}},permissions:{project:[],capabilities:['image.describe'],network:[],filesystem:[],secrets:[]},ui:[{control:'asset',port:'image'}]},
  capability:{schemaVersion:1,operation:'image.describe',image:{$input:'image'},instruction:'Describe only visibly supported subject matter, composition, lighting, color, texture, camera feel and visual style. Return concise production-ready plain text.',maxTokens:700,output:'description'},
  tests:[{name:'Blue image',input:{image:{width:1,height:1,data:[20,80,200,255]}},expectations:{description:{kind:'text',minLength:20,maxLength:32768,includes:['blue']}}}],
 };

package/packages/block-sdk/image-generation-example.js

@@ -2,7 +2,7 @@ import {EXAMPLE_PROVENANCE} from './example-license.js';
 // Portable image request. This fixture describes a result to review; it is not
 // evidence of a live generation. Model, quality and payment belong to the host.
 export const imageGenerate={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.generate-image',version:'1.0.0',name:'Generate an image',description:'Generate a square PNG from a short visual prompt using an approved host request.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{prompt:{type:'text',primary:true,semantic:'image_prompt',required:true,description:'Visual description of the image to generate.'}},outputs:{image:{type:'image',primary:true,semantic:'generated_image',description:'The generated square PNG image.'}},permissions:{project:[],capabilities:['image.generate'],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'prompt'}]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.generate-image',action:{label:'Generate image',running:'Generating image…'},version:'1.0.0',name:'Generate an image',description:'Generate a square PNG from a short visual prompt using an approved host request.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{prompt:{type:'text',primary:true,semantic:'image_prompt',required:true,description:'Visual description of the image to generate.'}},outputs:{image:{type:'image',primary:true,semantic:'generated_image',description:'The generated square PNG image.'}},permissions:{project:[],capabilities:['image.generate'],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'prompt'}]},
  capability:{schemaVersion:1,operation:'image.generate',prompt:{$input:'prompt'},output:'image'},
  tests:[{name:'A simple forest illustration',input:{prompt:'A simple illustration of a quiet forest with clear dark outlines and soft green colors.'},expectations:{image:{kind:'image',format:'png',width:1024,height:1024,minBytes:67,maxBytes:12000000}}}],
 };

package/packages/block-sdk/index.d.ts

@@ -14,7 +14,7 @@ export interface BlockViewBridge { connectDocument(options:import('./document-st
 export interface SdkCompatibility { status:'supported'|'unsupported'|'invalid'; declared:unknown; runtimeVersion:string; message:string; }
 export function sdkCompatibility(declared:unknown,runtimeVersion?:string):SdkCompatibility;
 export type Port = { type: string; imageMode?: 'pixels'|'reference'; role?: string; context?: keyof typeof CONTEXT_FIELDS; primary?: boolean; required?: boolean; default?: unknown; min?: number; max?: number; description?: string } & Partial<import('./semantic-contracts.js').SemanticContract>;
-export interface Manifest { schemaVersion: 1; id: string; name: string; version: string; sdkVersion: SdkVersionRange; description: string; kind: 'task'|'workspace'|'editor-extension'|'composite'; inputs: Record<string, Port>; outputs: Record<string, Port>; runtime: 'recipe'|'javascript'|'module'|'comfyui'|'capability'; jobs?: {kind:'cooperative';version:1}; state?: {scope:'step';version:number;initial:Record<string,unknown>;migrations?:StateMigration[]}; entry?: string; permissions: { project: string[]; desktop?: DesktopPermission[]; capabilities?: ['comfyui.execute']|['text.generate']|['audio.speech']|['audio.transcribe']|['image.generate']|['video.generate']|['image.describe']|['timeline.propose']|['workspace.propose']|['connection.execute']; network?: never[]; filesystem?: never[]; secrets?: never[] }; desktopTools?:DesktopToolDeclaration[]; uiLayout?: {kind:'tabs'|'sections';groups:{id:string;label:string;inputs:string[];outputs:string[];collapsed?:boolean}[]}; ui?: ({ control: 'text'|'number'|'slider'|'checkbox'|'asset'; port: string; label?: string; when?: {port:string;equals:string|boolean} } | {control:'select'|'multiselect';port:string;options:string[];label?:string;when?:{port:string;equals:string|boolean}} | {control:'gallery';port:string;label?:string} | {control:'before-after';port:string;before:string;label?:string})[]; }
+export interface Manifest { schemaVersion: 1; id: string; name: string; version: string; sdkVersion: SdkVersionRange; description: string; action?: { label: string; running?: string }; kind: 'task'|'workspace'|'editor-extension'|'composite'; inputs: Record<string, Port>; outputs: Record<string, Port>; runtime: 'recipe'|'javascript'|'module'|'comfyui'|'capability'; jobs?: {kind:'cooperative';version:1}; state?: {scope:'step';version:number;initial:Record<string,unknown>;migrations?:StateMigration[]}; entry?: string; permissions: { project: string[]; desktop?: DesktopPermission[]; capabilities?: ['comfyui.execute']|['text.generate']|['audio.speech']|['audio.transcribe']|['image.generate']|['video.generate']|['image.describe']|['timeline.propose']|['workspace.propose']|['connection.execute']; network?: never[]; filesystem?: never[]; secrets?: never[] }; desktopTools?:DesktopToolDeclaration[]; uiLayout?: {kind:'tabs'|'sections';groups:{id:string;label:string;inputs:string[];outputs:string[];collapsed?:boolean}[]}; ui?: ({ control: 'text'|'number'|'slider'|'checkbox'|'asset'; port: string; label?: string; when?: {port:string;equals:string|boolean} } | {control:'select'|'multiselect';port:string;options:string[];label?:string;when?:{port:string;equals:string|boolean}} | {control:'gallery';port:string;label?:string} | {control:'before-after';port:string;before:string;label?:string})[]; }
 export interface BlockView { html: string; css?: string; themedCss?: string; javascript?: string; appearance?: 'host'|'original'; }
 /** A frame view: any interface code (frameworks, SVG, canvas, drag) with assets named by SHA-256. */
 export interface FrameView { runtime: 'frame'; html: string; css?: string; themedCss?: string; javascript?: string; appearance?: 'host'|'original'; files?: {schemaVersion: 1; files: Record<string, {sha256: string; bytes: number; mediaType: string}>}; }
@@ -414,7 +414,7 @@ export * from './native-host-providers.js';
 
 export {blockRemixPolicy,assertRemixReady,REMIX_AUTHORING_REQUIREMENT} from './remix-policy.js';
 export interface SdkCompatibility {status:'supported'|'unsupported'|'invalid';declared:unknown;runtimeVersion:string;message:string}
-export interface Manifest { schemaVersion: 1; id: string; name: string; version: string; sdkVersion: SdkVersionRange; description: string; kind: 'task'|'workspace'|'editor-extension'|'composite'; inputs: Record<string, Port>; outputs: Record<string, Port>; runtime: 'recipe'|'javascript'|'module'|'comfyui'|'capability'; jobs?: {kind:'cooperative';version:1}; state?: {scope:'step';version:number;initial:Record<string,unknown>;migrations?:StateMigration[]}; entry?: string; permissions: { project: string[]; desktop?: DesktopPermission[]; capabilities?: ['comfyui.execute']|['text.generate']|['audio.speech']|['audio.transcribe']|['image.generate']|['video.generate']|['image.describe']|['timeline.propose']|['workspace.propose']|['connection.execute']; network?: never[]; filesystem?: never[]; secrets?: never[] }; uiLayout?: {kind:'tabs'|'sections';groups:{id:string;label:string;inputs:string[];outputs:string[];collapsed?:boolean}[]}; ui?: ({ control: 'text'|'number'|'slider'|'checkbox'|'asset'; port: string; label?: string; when?: {port:string;equals:string|boolean} } | {control:'select'|'multiselect';port:string;options:string[];label?:string;when?:{port:string;equals:string|boolean}} | {control:'gallery';port:string;label?:string} | {control:'before-after';port:string;before:string;label?:string})[]; }
+export interface Manifest { schemaVersion: 1; id: string; name: string; version: string; sdkVersion: SdkVersionRange; description: string; action?: { label: string; running?: string }; kind: 'task'|'workspace'|'editor-extension'|'composite'; inputs: Record<string, Port>; outputs: Record<string, Port>; runtime: 'recipe'|'javascript'|'module'|'comfyui'|'capability'; jobs?: {kind:'cooperative';version:1}; state?: {scope:'step';version:number;initial:Record<string,unknown>;migrations?:StateMigration[]}; entry?: string; permissions: { project: string[]; desktop?: DesktopPermission[]; capabilities?: ['comfyui.execute']|['text.generate']|['audio.speech']|['audio.transcribe']|['image.generate']|['video.generate']|['image.describe']|['timeline.propose']|['workspace.propose']|['connection.execute']; network?: never[]; filesystem?: never[]; secrets?: never[] }; uiLayout?: {kind:'tabs'|'sections';groups:{id:string;label:string;inputs:string[];outputs:string[];collapsed?:boolean}[]}; ui?: ({ control: 'text'|'number'|'slider'|'checkbox'|'asset'; port: string; label?: string; when?: {port:string;equals:string|boolean} } | {control:'select'|'multiselect';port:string;options:string[];label?:string;when?:{port:string;equals:string|boolean}} | {control:'gallery';port:string;label?:string} | {control:'before-after';port:string;before:string;label?:string})[]; }
 export interface BlockPackage { portable?: PortableMetadata; manifest: Manifest; view?: BlockView|FrameView; code?: string; module?: ModuleDescriptor; comfyui?: ComfyWorkflow; capability?: ConnectedCapability|TextGenerationCapability|SpeechCapability|TranscriptionCapability|ImageGenerationCapability|VideoGenerationCapability|ImageDescriptionCapability|TimelineProposalCapability; recipe?: { schemaVersion: 1; steps: { id: string; op: string; args: Record<string, unknown> }[]; outputs: Record<string, unknown> }; tests: { name: string; input: Record<string, unknown>; expected?: Record<string, unknown>; state?: BlockState; expectedState?: BlockState; expectations?: Record<string, ConnectedResultExpectation|ComfyImageExpectation|CapabilityTextExpectation|CapabilityAudioExpectation|CapabilityTranscriptExpectation|CapabilityImageExpectation|CapabilityVideoExpectation|CapabilityTimelineExpectation> }[]; }
 export type CapabilityInvocation = TextGenerationInvocation|SpeechInvocation|TranscriptionInvocation|ImageGenerationInvocation|VideoGenerationInvocation|ImageDescriptionInvocation|TimelineProposalInvocation;
 export interface CapabilityResult { outputs: Record<string, unknown>; metadata?: Record<string, unknown>; mediaReceipts?: Record<string, SpeechMediaReceipt|GeneratedAudioMediaReceipt|GeneratedImageMediaReceipt|GeneratedVideoMediaReceipt>; }

package/packages/block-sdk/media-analysis-example.js

@@ -2,7 +2,7 @@ import {EXAMPLE_PROVENANCE} from './example-license.js';
 // Ask StillMade's media vision about a saved video, optionally inside one time
 // range. Each analyzed image or video is one priced call on StillMade credits.
 export const mediaAnalysis={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.check-clip',version:'1.0.0',name:'Check a clip',description:'Answer a production question about a saved video clip, with timestamps.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.check-clip',action:{label:'Check clip',running:'Checking clip…'},version:'1.0.0',name:'Check a clip',description:'Answer a production question about a saved video clip, with timestamps.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,
   inputs:{clip:{type:'video',primary:true,semantic:'source_video',required:true,description:'Saved video to check.'},start:{type:'number',required:false,min:0,semantic:'range_start',description:'Optional start of the range to look at closely, in seconds.'},end:{type:'number',required:false,min:0,semantic:'range_end',description:'Optional end of the range, in seconds (at most 12 seconds after the start).'}},
   outputs:{report:{type:'json',primary:true,semantic:'media_findings',description:'Summary, timeline, on-screen text and issues found.'}},
   permissions:{project:[],capabilities:['media.analyze'],network:[],filesystem:[],secrets:[]},ui:[{control:'asset',port:'clip'},{control:'number',port:'start'},{control:'number',port:'end'}]},

package/packages/block-sdk/module-example.js

@@ -12,7 +12,7 @@ export default async function run(input, stillmade) {
 }
 `;
 export const moduleWordStats={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.word-stats',version:'1.0.0',name:'Word stats',description:'Counts words and finds the longest one, as a modern JavaScript module.',kind:'task',runtime:'module',license:'MIT',provenance:EXAMPLE_PROVENANCE,
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.word-stats',action:{label:'Count words',running:'Counting words…'},version:'1.0.0',name:'Word stats',description:'Counts words and finds the longest one, as a modern JavaScript module.',kind:'task',runtime:'module',license:'MIT',provenance:EXAMPLE_PROVENANCE,
   inputs:{text:{type:'text',primary:true,semantic:'plain_text',required:true,description:'Text to measure.'}},
   outputs:{words:{type:'integer',semantic:'word_count',description:'Number of words.'},longest:{type:'text',primary:true,semantic:'longest_word',description:'The longest word.'}},
   permissions:{project:[],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'text'}]},

package/packages/block-sdk/speech-example.js

@@ -2,7 +2,7 @@ import {EXAMPLE_PROVENANCE} from './example-license.js';
 // Portable speech request. These fixtures are expectations to review, not
 // evidence that a provider has generated audio. Host controls choose the voice.
 export const audioSpeech={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.narrate-script',version:'1.0.0',name:'Narrate a script',description:'Turn a short script into a reviewed speech recording using a host-selected voice.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{script:{type:'script',primary:true,semantic:'narration_script',required:true,description:'Narration script to render as speech.'}},outputs:{audio:{type:'audio',primary:true,semantic:'speech_audio',description:'Speech audio generated from the narration script.'}},permissions:{project:[],capabilities:['audio.speech'],network:[],filesystem:[],secrets:[]},ui:[]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.narrate-script',action:{label:'Generate voiceover',running:'Generating voiceover…'},version:'1.0.0',name:'Narrate a script',description:'Turn a short script into a reviewed speech recording using a host-selected voice.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{script:{type:'script',primary:true,semantic:'narration_script',required:true,description:'Narration script to render as speech.'}},outputs:{audio:{type:'audio',primary:true,semantic:'speech_audio',description:'Speech audio generated from the narration script.'}},permissions:{project:[],capabilities:['audio.speech'],network:[],filesystem:[],secrets:[]},ui:[]},
  capability:{schemaVersion:1,operation:'audio.speech',text:{$input:'script'},output:'audio'},
  tests:[{name:'Read a short welcome',input:{script:{schemaVersion:1,text:'Welcome to the quiet forest.'}},expectations:{audio:{kind:'audio',format:'wav',minDuration:0.1,maxDuration:30,minBytes:46,maxBytes:1500000}}}],
 };

package/packages/block-sdk/state-example.js

@@ -1,6 +1,6 @@
 import {EXAMPLE_PROVENANCE} from './example-license.js';
 export const numberedTakes={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.numbered-takes',version:'1.0.0',name:'Numbered takes',description:'Label successive creative takes with an independent counter for each production placement.',kind:'task',runtime:'javascript',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{text:{type:'text',primary:true,semantic:'draft_text',required:true,description:'Creative take text to label with the next number.'}},outputs:{text:{type:'text',primary:true,semantic:'numbered_take',description:'The supplied take prefixed with its saved sequence number.'}},permissions:{project:['state.step']},state:{scope:'step',version:1,initial:{count:0}},ui:[{port:'text',control:'text'}]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.numbered-takes',action:{label:'Number takes',running:'Numbering takes…'},version:'1.0.0',name:'Numbered takes',description:'Label successive creative takes with an independent counter for each production placement.',kind:'task',runtime:'javascript',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{text:{type:'text',primary:true,semantic:'draft_text',required:true,description:'Creative take text to label with the next number.'}},outputs:{text:{type:'text',primary:true,semantic:'numbered_take',description:'The supplied take prefixed with its saved sequence number.'}},permissions:{project:['state.step']},state:{scope:'step',version:1,initial:{count:0}},ui:[{port:'text',control:'text'}]},
  code:'state.count += 1; return {text: "Take " + state.count + ": " + input.text.trim()};',
  tests:[{name:'First take',input:{text:'  Opening scene  '},expected:{text:'Take 1: Opening scene'},expectedState:{version:1,value:{count:1}}},{name:'Continues saved numbering',input:{text:'Alternate ending'},state:{version:1,value:{count:4}},expected:{text:'Take 5: Alternate ending'},expectedState:{version:1,value:{count:5}}}]
 };

package/packages/block-sdk/timeline-proposal-example.js

@@ -1,7 +1,7 @@
 import {EXAMPLE_PROVENANCE} from './example-license.js';
 
 export const timelinePolish={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.timeline-polish',version:'1.0.0',name:'Timeline polish',description:'Turn a timeline and editing direction into a bounded proposal that remains reviewable before Apply.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{timeline:{type:'timeline',context:'timeline',primary:true},direction:{type:'text',default:'Polish this cut conservatively.'}},outputs:{edit:{type:'timeline-edit',primary:true}},permissions:{project:['context.timeline.read','timeline.propose'],capabilities:['timeline.propose'],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'direction'}]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.timeline-polish',action:{label:'Suggest edit',running:'Suggesting edit…'},version:'1.0.0',name:'Timeline polish',description:'Turn a timeline and editing direction into a bounded proposal that remains reviewable before Apply.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{timeline:{type:'timeline',context:'timeline',primary:true},direction:{type:'text',default:'Polish this cut conservatively.'}},outputs:{edit:{type:'timeline-edit',primary:true}},permissions:{project:['context.timeline.read','timeline.propose'],capabilities:['timeline.propose'],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'direction'}]},
  capability:{schemaVersion:1,operation:'timeline.propose',context:{timeline:{$input:'timeline'},direction:{$input:'direction'}},instruction:'Use only supported timeline-edit commands, exact before snapshots, and the current activeTimelineId. Preserve media and locked items. Return strict JSON only.',maxTokens:2000,output:'edit'},
  tests:[{name:'one restrained edit',input:{timeline:{schemaVersion:1,activeTimelineId:'timeline-1',tracks:[{id:'video'}],clips:[{id:'clip-1',trackId:'video',start:0,duration:4}],audioItems:[],captions:[]},direction:'Add a soft transition.'},expectations:{edit:{kind:'timeline-edit',minCommands:1,maxCommands:10}}}],
 };

package/packages/block-sdk/transcription-example.js

@@ -1,7 +1,7 @@
 import {EXAMPLE_PROVENANCE} from './example-license.js';
 
 export const audioTranscription={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.transcribe-audio',version:'1.0.0',name:'Transcribe audio',description:'Turn one persistent audio file into reviewed text with word timings.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{audio:{type:'audio',primary:true},language:{type:'text',default:'auto'}},outputs:{transcript:{type:'transcript',primary:true}},permissions:{project:[],capabilities:['audio.transcribe'],network:[],filesystem:[],secrets:[]},ui:[{control:'asset',port:'audio'},{control:'select',port:'language',options:['auto','en','es','fr','de','it','pt','ja','ko','zh']}]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.transcribe-audio',action:{label:'Transcribe audio',running:'Transcribing…'},version:'1.0.0',name:'Transcribe audio',description:'Turn one persistent audio file into reviewed text with word timings.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{audio:{type:'audio',primary:true},language:{type:'text',default:'auto'}},outputs:{transcript:{type:'transcript',primary:true}},permissions:{project:[],capabilities:['audio.transcribe'],network:[],filesystem:[],secrets:[]},ui:[{control:'asset',port:'audio'},{control:'select',port:'language',options:['auto','en','es','fr','de','it','pt','ja','ko','zh']}]},
  capability:{schemaVersion:1,operation:'audio.transcribe',audio:{$input:'audio'},language:{$input:'language'},output:'transcript'},
  tests:[{name:'timed speech',input:{audio:{kind:'audio',assetId:'audio-1',versionId:'version-1',url:'/api/media/example/audio.mp3',mimeType:'audio/mpeg'},language:'en'},expectations:{transcript:{kind:'transcript',minWords:1,maxWords:1000}}}]
 };

package/packages/block-sdk/trigger-examples.js

@@ -5,7 +5,7 @@ import {EXAMPLE_PROVENANCE} from './example-license.js';
 // credits per call, total credits, expiry), every new video saved to the
 // project is transcribed unattended into timed captions.
 export const autoCaptions={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.auto-captions',version:'1.0.0',name:'Auto-caption new uploads',description:'Transcribe each new video into timed captions, automatically within the budget the project owner approves.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.auto-captions',action:{label:'Make captions',running:'Making captions…'},version:'1.0.0',name:'Auto-caption new uploads',description:'Transcribe each new video into timed captions, automatically within the budget the project owner approves.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,
   inputs:{video:{type:'video',primary:true,required:true,semantic:'source_video',description:'The new video to caption.'},language:{type:'text',default:'auto',required:false,semantic:'language_code',description:'auto, or a two-letter language code such as en.'}},
   outputs:{captions:{type:'transcript',primary:true,semantic:'timed_captions',description:'The spoken words with their timings.'}},
   permissions:{project:[],capabilities:['audio.transcribe'],network:[],filesystem:[],secrets:[]},
@@ -19,7 +19,7 @@ export const autoCaptions={
 // turns it into a short production note. It runs in StillMade's sandbox with
 // no network and no credits.
 export const orderNote={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.order-note',version:'1.0.0',name:'Order to production note',description:'Turn an order a shop sends by webhook into a short production note.',kind:'task',runtime:'javascript',license:'MIT',provenance:EXAMPLE_PROVENANCE,
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.order-note',action:{label:'Write order note',running:'Writing order note…'},version:'1.0.0',name:'Order to production note',description:'Turn an order a shop sends by webhook into a short production note.',kind:'task',runtime:'javascript',license:'MIT',provenance:EXAMPLE_PROVENANCE,
   inputs:{event:{type:'object',semantic:'workflow_event',schema:{id:'string',kind:'string',occurredAt:'string',preview:'boolean',data:'object'},sources:['project'],required:true,description:'The webhook event StillMade received.'}},
   outputs:{note:{type:'text',primary:true,semantic:'production_note',description:'A one-line note for the team.'}},
   permissions:{project:[],network:[],filesystem:[],secrets:[]},

package/packages/block-sdk/video-generation-example.js

@@ -2,7 +2,7 @@ import {EXAMPLE_PROVENANCE} from './example-license.js';
 // Declarative request; the host chooses provider, model, duration, payment and
 // storage. This fixture is executed only after explicit host approval.
 export const videoGenerate={
- manifest:{schemaVersion:1,id:'example.generate-video',name:'Generate video',version:'1.0.0',sdkVersion:'0.1.0',description:'Turn a production prompt into a short video using an approved host provider.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{prompt:{type:'text',primary:true,required:true}},outputs:{video:{type:'video',primary:true}},permissions:{project:[],capabilities:['video.generate'],network:[],filesystem:[],secrets:[]},ui:[{port:'prompt',control:'text'}]},
+ manifest:{schemaVersion:1,id:'example.generate-video',action:{label:'Generate video',running:'Generating video…'},name:'Generate video',version:'1.0.0',sdkVersion:'0.1.0',description:'Turn a production prompt into a short video using an approved host provider.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{prompt:{type:'text',primary:true,required:true}},outputs:{video:{type:'video',primary:true}},permissions:{project:[],capabilities:['video.generate'],network:[],filesystem:[],secrets:[]},ui:[{port:'prompt',control:'text'}]},
  capability:{schemaVersion:1,operation:'video.generate',prompt:{$input:'prompt'},output:'video'},
  tests:[{name:'Produces a bounded MP4 sample',input:{prompt:'A paper boat floating across a calm blue pond. Gentle camera movement.'},expectations:{video:{kind:'video',format:'mp4',minDuration:1,maxDuration:60,minBytes:32,maxBytes:67108864,minWidth:1,maxWidth:3840,minHeight:1,maxHeight:3840}}}],
 };