stillmade-sdk 0.1.41 → 0.1.43

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

@@ -278,7 +278,8 @@ export const GENERATION_LIMITS: Readonly<{references:8;negativePrompt:2000;seed:
 /** Fill and check image settings; `strict` rejects values the model does not accept. */
 export function imageSettings(value?:Partial<ImageSettings>,options?:{strict?:boolean}):ImageSettings;
 /** Fill and check video settings, including Veo's 1080p-is-8-seconds rule. */
-export function videoSettings(value?:Partial<VideoSettings>,options?:{strict?:boolean;firstFrame?:boolean}):VideoSettings;
+/** With no model named, the default is the cheapest model that makes the asked aspect ratio and takes the frames given. */
+export function videoSettings(value?:Partial<VideoSettings>,options?:{strict?:boolean;firstFrame?:boolean;lastFrame?:boolean}):VideoSettings;
 export function validateSeed(seed:number):number;
 export const MEDIA_GENERATE_LIMITS: Readonly<{items:50;prompt:4000}>;
 export const MEDIA_GENERATE_OPERATIONS: readonly ['image','video','speech','music','sfx'];

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

@@ -2,9 +2,9 @@ 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.'}},
+  outputs:{report:{type:'json',primary:true,semantic:'media_findings',description:'Summary, timeline, on-screen text and issues found.',schema:{items:'json[]'}}},
   permissions:{project:[],capabilities:['media.analyze'],network:[],filesystem:[],secrets:[]},ui:[{control:'asset',port:'clip'},{control:'number',port:'start'},{control:'number',port:'end'}]},
  capability:{schemaVersion:1,operation:'media.analyze',media:{$input:'clip'},question:'Is the product logo clearly visible, and when? List any on-screen text and visible defects.',range:{start:{$input:'start'},end:{$input:'end'}},output:'report'},
  tests:[{name:'A saved clip',input:{clip:{kind:'video',assetId:'clip-1',versionId:'v1',url:'/api/media/owner/clip.mp4'}},expectations:{report:{kind:'json',includes:['summary']}}}],

package/packages/block-sdk/mock-host.js

@@ -13,6 +13,7 @@ import {createMemoryStorage,storageKey} from './cloud-storage.js';
 import {mediaTransformRequest,decodeWav} from './media-transform.js';
 import {FILE_FORMATS} from './data-values.js';
 import {mockPng,mockWav,mockMp4,MOCK_IMAGE_SIZE,MOCK_VIDEO_SIZE} from './mock-media.js';
+import {videoSettings,audioSettings} from './generation-catalog.js';
 // The words of a simple PDF whose pages are uncompressed text, such as the example lesson.pdf, page by page; null for
 // anything else. StillMade reads real PDFs on the person's device; a local test of another PDF mocks document.text
 // (November 1, 2026: the stand-in read a PDF's own code as its words).
@@ -201,7 +202,12 @@ export function createMockHost({mocks:given={},readLocalFile,manifest,pickedMedi
    const operation=action?.operation;
    if(recorded('actions',operation)){note('actions.run',operation,'mocks');return pick(mocks.actions[operation],count(`action:${operation}`));}
    note('actions.run',operation,'recorded');
-   if(operation==='media.generate')return {value:action.request.items.map(item=>{const made=reference[item.operation==='image'||item.operation==='video'?item.operation:'audio']();return {key:item.key,kind:made.kind,assetId:made.assetId,versionId:made.versionId,url:made.url};}),failures:[]};
+   // As in StillMade: a video, music or sound effect carries the length it asked for; speech carries none (decode it).
+   if(operation==='media.generate')return {value:action.request.items.map(item=>{
+    const seconds=item.operation==='video'?videoSettings(item.settings,{firstFrame:item.firstFrame!==undefined,lastFrame:item.lastFrame!==undefined}).duration:['music','sfx'].includes(item.operation)?audioSettings(item.operation,item.settings).durationSec:undefined;
+    const made=item.operation==='image'||item.operation==='video'?reference[item.operation]():reference.audio(seconds?{seconds,sampleRate:8000}:undefined);
+    return {key:item.key,kind:made.kind,assetId:made.assetId,versionId:made.versionId,url:made.url,...(Number.isFinite(seconds)?{duration:seconds}:{})};
+   }),failures:[]};
    if(operation==='stock.search')return {results:[]};
    fail(`There is no recorded stand-in for the ${operation} action. Add one under actions["${operation}"] in ${MOCKS_FILE}.`);
   },

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/module-host-calls.js

@@ -4,20 +4,45 @@
 import {networkDeclarations,networkRequest,connectionDeclarations,connectionCall} from './network.js';
 import {storageHostHandlers} from './cloud-storage.js';
 import {projectReadSnapshot} from './context.js';
+import {mediaReferences,moduleMediaAccess,MEDIA_RESULT_OPERATIONS} from './module-media-access.js';
 
-/** {api: args => Promise} for one run of `pkg` against `host` (see createNodeModuleExecutor). */
-export function moduleHostCalls(pkg,host,storage){
+/**
+ * {api: args => Promise} for one run of `pkg` against `host` (see createNodeModuleExecutor). `input` is the run's input:
+ * files, transforms, actions, hosted calls and asset changes use only files the run received or the host made in it,
+ * the rule StillMade's own host applies (module-media-access.js).
+ */
+export function moduleHostCalls(pkg,host,storage,input){
+ const access=moduleMediaAccess(input);
+ const made=async pending=>access.remember(await pending);
  return {
-  'files.read':args=>host.readFile?host.readFile(args.ref):Promise.reject(Object.assign(new Error('files.read needs a host file reader in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'})),
-  'files.write':args=>host.writeFile?host.writeFile(args.buffer,args.options):Promise.reject(Object.assign(new Error('files.write saves to the StillMade library; pass a host writer in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'})),
-  'media.transform':args=>host.transformMedia?host.transformMedia(args.request):Promise.reject(Object.assign(new Error('Media transforms run in StillMade; pass a host transformMedia in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'})),
-  'actions.run':args=>host.runAction?host.runAction(args.action):Promise.reject(Object.assign(new Error('Actions run in StillMade.'),{code:'MODULE_HOST_UNAVAILABLE'})),
-  'hosted.run':args=>host.runHosted?host.runHosted(args.operation,args.request):Promise.reject(Object.assign(new Error('Hosted operations run in StillMade.'),{code:'MODULE_HOST_UNAVAILABLE'})),
+  'files.read':async args=>{access.checkFile(args.ref,'files.read reads');return host.readFile?host.readFile(args.ref):Promise.reject(Object.assign(new Error('files.read needs a host file reader in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
+  'files.write':args=>host.writeFile?made(host.writeFile(args.buffer,args.options)):Promise.reject(Object.assign(new Error('files.write saves to the StillMade library; pass a host writer in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'})),
+  'media.transform':async args=>{access.check(args.request,'Media transforms');return host.transformMedia?made(host.transformMedia(args.request)):Promise.reject(Object.assign(new Error('Media transforms run in StillMade; pass a host transformMedia in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
+  'actions.run':async args=>{
+   access.check(args.action,'Actions');
+   if(!host.runAction)throw Object.assign(new Error('Actions run in StillMade.'),{code:'MODULE_HOST_UNAVAILABLE'});
+   const result=await host.runAction(args.action);
+   if(args.action?.operation==='media.generate')for(const ref of mediaReferences(result?.value))access.remember(ref);
+   return result;
+  },
+  'hosted.run':async args=>{
+   access.check(args.request,'Hosted operations');
+   if(!host.runHosted)throw Object.assign(new Error('Hosted operations run in StillMade.'),{code:'MODULE_HOST_UNAVAILABLE'});
+   const result=await host.runHosted(args.operation,args.request);
+   return MEDIA_RESULT_OPERATIONS.includes(args.operation)?access.remember(result):result;
+  },
   'connections.call':async args=>{const request=connectionCall(args.request,connectionDeclarations(pkg.manifest.permissions?.connections));return host.callConnection?host.callConnection(request):Promise.reject(Object.assign(new Error('Connections run through StillMade, which adds your account; pass a host callConnection in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
   ...storageHostHandlers(storage),
-  'project.read':async args=>{if(!host.project)throw Object.assign(new Error('project.read needs a project snapshot; pass host.project in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'});return projectReadSnapshot(pkg.manifest,host.project,args.fields);},
-  'assets.create':async args=>{if(!(pkg.manifest.permissions?.project||[]).includes('asset.create'))throw Object.assign(new Error('Declare asset.create to add project assets.'),{code:'MODULE_PERMISSION'});return host.createAsset?host.createAsset(args.file,args.options||{}):Promise.reject(Object.assign(new Error('Project assets are saved in StillMade; pass a host createAsset in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
-  'assets.appendVersion':async args=>{if(!(pkg.manifest.permissions?.project||[]).includes('asset.version.append'))throw Object.assign(new Error('Declare asset.version.append to add asset versions.'),{code:'MODULE_PERMISSION'});return host.appendAssetVersion?host.appendAssetVersion(args.asset,args.file):Promise.reject(Object.assign(new Error('Project assets are saved in StillMade; pass a host appendAssetVersion in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
+  // Only the host-built media indexes make media usable, as in StillMade: free-form documents can hold media-shaped values.
+  'project.read':async args=>{
+   if(!host.project)throw Object.assign(new Error('project.read needs a project snapshot; pass host.project in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'});
+   const snapshot=projectReadSnapshot(pkg.manifest,host.project,args.fields);
+   for(const field of ['assets','files'])for(const ref of mediaReferences(snapshot[field]))access.add(ref);
+   for(const shot of Array.isArray(snapshot.shots)?snapshot.shots:[])if(shot?.selectedImage)access.remember(shot.selectedImage);
+   return snapshot;
+  },
+  'assets.create':async args=>{if(!(pkg.manifest.permissions?.project||[]).includes('asset.create'))throw Object.assign(new Error('Declare asset.create to add project assets.'),{code:'MODULE_PERMISSION'});access.checkFile(args.file,'assets.create adds');return host.createAsset?made(host.createAsset(args.file,args.options||{})):Promise.reject(Object.assign(new Error('Project assets are saved in StillMade; pass a host createAsset in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
+  'assets.appendVersion':async args=>{if(!(pkg.manifest.permissions?.project||[]).includes('asset.version.append'))throw Object.assign(new Error('Declare asset.version.append to add asset versions.'),{code:'MODULE_PERMISSION'});access.checkFile(args.file,'assets.appendVersion adds');return host.appendAssetVersion?made(host.appendAssetVersion(args.asset,args.file)):Promise.reject(Object.assign(new Error('Project assets are saved in StillMade; pass a host appendAssetVersion in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
   'net.fetch':async args=>{const request=networkRequest(args.request,networkDeclarations(pkg.manifest.permissions?.network));return host.netFetch?host.netFetch(request):Promise.reject(Object.assign(new Error('Network calls run through StillMade, which adds your key; pass a host netFetch in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
  };
 }

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

@@ -5,7 +5,7 @@
 // operation in `permissions.capabilities`.
 import {assert,plain,stableStringify} from './contracts.js';
 import {defaultCapabilityExpectations,MEDIA_ANALYZE_LIMITS} from './capabilities.js';
-import {GENERATION_LIMITS,IMAGE_GENERATION_MODELS} from './generation-catalog.js';
+import {GENERATION_LIMITS,IMAGE_GENERATION_MODELS,VIDEO_GENERATION_MODELS} from './generation-catalog.js';
 
 const text=(value,max)=>typeof value==='string'&&value.trim().length>0&&value.length<=max;
 const media=(value,kind)=>plain(value)&&value.kind===kind&&['assetId','versionId','url'].every(key=>typeof value[key]==='string'&&value[key].trim());
@@ -32,7 +32,20 @@ const SHAPES={
  },
  'video.generate':request=>{
   if(!text(request.prompt,32000))fail('video.generate needs a prompt');
-  return {inputs:{prompt:port('text','Video prompt')},outputs:{result:port('video','Generated video')},capability:{prompt:{$input:'prompt'},output:'result',...(request.settings?{settings:request.settings}:{})},input:{prompt:request.prompt}};
+  // firstFrame and lastFrame: saved images the video starts and ends on, bound as a capability Block binds them; and the
+  // negativePrompt (November 3, 2026: they were dropped, so a listing video's camera move over each photo was made from
+  // the words alone, and the stand-in host passed it).
+  const {firstFrame,lastFrame,negativePrompt}=request;
+  for(const [name,frame] of [['firstFrame',firstFrame],['lastFrame',lastFrame]])if(frame!==undefined&&!media(frame,'image'))fail(`video.generate ${name} is one saved image`);
+  if(lastFrame!==undefined&&firstFrame===undefined)fail('video.generate lastFrame needs a firstFrame');
+  if(negativePrompt!==undefined&&!(typeof negativePrompt==='string'&&negativePrompt.length<=GENERATION_LIMITS.negativePrompt))fail(`video.generate negativePrompt is text of at most ${GENERATION_LIMITS.negativePrompt.toLocaleString('en-US')} characters`);
+  // A model named in settings must take those frames (every model takes a first frame; Kling 3.0 Turbo and Wan 2.6 Flash
+  // take no last frame; Wan 2.6 Flash and Wan 2.7 need a first frame).
+  const model=VIDEO_GENERATION_MODELS[request.settings?.model];
+  if(model&&firstFrame&&!model.firstFrame)fail(`${model.label} takes no first frame: choose a model that does, or leave the model to the person`);
+  if(model&&lastFrame&&!model.lastFrame)fail(`${model.label} takes no last frame: choose a model that does, or leave the model to the person`);
+  if(model?.requiresFirstFrame&&!firstFrame)fail(`${model.label} needs a firstFrame`);
+  return {inputs:{prompt:port('text','Video prompt'),...(firstFrame?{firstFrame:port('image','First frame')}:{}),...(lastFrame?{lastFrame:port('image','Last frame')}:{})},outputs:{result:port('video','Generated video')},capability:{prompt:{$input:'prompt'},output:'result',...(firstFrame?{firstFrame:{$input:'firstFrame'}}:{}),...(lastFrame?{lastFrame:{$input:'lastFrame'}}:{}),...(request.settings?{settings:request.settings}:{}),...(negativePrompt?{negativePrompt}:{})},input:{prompt:request.prompt,...(firstFrame?{firstFrame}:{}),...(lastFrame?{lastFrame}:{})}};
  },
  'audio.speech':request=>{
   if(!text(request.text,3800))fail('audio.speech needs text of up to 3,800 characters');

package/packages/block-sdk/module-media-access.js

@@ -0,0 +1,71 @@
+// Which saved files a module Block may use in one run: the references it
+// received as input, and those the host made during the run (files it wrote,
+// transform results, generated media, project media it read). files.read,
+// transforms, actions, hosted calls and project asset changes use only these.
+// StillMade's browser host (client/src/blocks/moduleRuntimeHost.js) and the
+// SDK's local runners (module-host-calls.js: `test --mock`, `ready`, `gate`,
+// and the QuickJS runner for Blocks built in StillMade) apply this one rule, so
+// a Block gets the same verdict on a creator's machine and in the import review.
+import {stableStringify} from './contracts.js';
+
+const fail=(message,code)=>Object.assign(new Error(message),{code});
+export const MODULE_MEDIA_KINDS=Object.freeze(['image','video','audio','asset','file']);
+// Hosted operations whose result is media the host generated and checked.
+export const MEDIA_RESULT_OPERATIONS=Object.freeze(['image.generate','video.generate','audio.speech','audio.music','audio.sfx']);
+// A reference names its file by these fields. Its other fields describe the
+// file (a media.generate item's key, a duration, a name) and may be dropped or
+// added (November 3, 2026: a listing video Block rebuilt each generated clip as
+// {kind, assetId, versionId, url}, without the result item's `key`, and every
+// render was refused although the clips were generated in that run).
+export const MEDIA_REFERENCE_FIELDS=Object.freeze(['kind','assetId','versionId','url']);
+const isReference=value=>MODULE_MEDIA_KINDS.includes(value.kind)&&(typeof value.url==='string'||typeof value.assetId==='string');
+
+/**
+ * Saved references in a value: anything shaped like media (a media kind with a
+ * url or assetId), at any depth. With `strict`, a value too large to inspect is
+ * refused. With `within`, the other fields of a reference are searched too, so
+ * a reference cannot carry another file past the check.
+ */
+export function mediaReferences(input,{strict=false,within=false}={}){
+ const found=[];let visited=0;
+ const visit=(value,depth)=>{
+  if(!value||typeof value!=='object'||value instanceof ArrayBuffer||ArrayBuffer.isView(value))return;
+  if(++visited>20000||depth>16){if(strict)throw fail('This request is too large or too deeply nested to check.','MODULE_HOST');return;}
+  if(Array.isArray(value)){for(const item of value)visit(item,depth+1);return;}
+  if(isReference(value)){
+   found.push(value);
+   if(within)for(const [key,item] of Object.entries(value))if(!MEDIA_REFERENCE_FIELDS.includes(key))visit(item,depth+1);
+   return;
+  }
+  for(const item of Object.values(value))visit(item,depth+1);
+ };
+ visit(input,0);return found;
+}
+
+/** The file a reference names, as a comparable string. */
+export function mediaReferenceKey(ref){
+ return stableStringify(MEDIA_REFERENCE_FIELDS.map(key=>typeof ref?.[key]==='string'?ref[key]:null));
+}
+
+const RULE='this Block received, wrote or generated in this run';
+const FIX='Pass the reference the Block received as input, or the one StillMade returned in this run (files.write, a transform, hosted.run or actions.run media.generate), keeping its kind, assetId, versionId and url.';
+
+/**
+ * The run's usable files, starting from its input. `remember` adds a value the
+ * host made when the value is itself a reference (a text, JSON or web result
+ * can contain media-shaped values chosen by a model or a web page, so only
+ * references the host returned count); `add` adds a reference the host
+ * vouches for (project media it read). The checks throw MODULE_FILE_READ.
+ */
+export function moduleMediaAccess(input){
+ const usable=new Set(mediaReferences(input).map(mediaReferenceKey));
+ const allowed=ref=>!!ref&&typeof ref==='object'&&usable.has(mediaReferenceKey(ref));
+ return {
+  allowed,
+  add(ref){usable.add(mediaReferenceKey(ref));},
+  remember(value){if(value&&typeof value==='object'&&mediaReferences(value)[0]===value)usable.add(mediaReferenceKey(value));return value;},
+  // Every reference in a request, and inside its references, must be usable.
+  check(value,what){if(!mediaReferences(value,{strict:true,within:true}).every(allowed))throw fail(`${what} use only files ${RULE}. ${FIX}`,'MODULE_FILE_READ');},
+  checkFile(ref,call){if(!allowed(ref))throw fail(`${call} only files ${RULE}. ${FIX}`,'MODULE_FILE_READ');},
+ };
+}

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

@@ -43,7 +43,7 @@ export function createNodeModuleExecutor({files,host={},onProgress,onLog,now=()=
   try{declared=networkDeclarations(pkg.manifest.permissions?.network);}catch{/* no valid origins */}
   const sockets=createModuleSockets({declarations:declared,open:host.netConnect,post:(message,transfer)=>worker.postMessage(message,transfer)});
   // The shared host calls (files, media, hosted operations, connections, storage, project, assets, net.fetch) plus live connections.
-  const handlers={...sockets.handlers,...moduleHostCalls(pkg,host,storage)};
+  const handlers={...sockets.handlers,...moduleHostCalls(pkg,host,storage,input)};
   try{
    return await new Promise((resolve,reject)=>{
     const stop=error=>{clearInterval(timer);reject(error);};

package/packages/block-sdk/portable-media-actions.js

@@ -37,7 +37,7 @@ export function mediaGenerateRequest(request){
    if(item.references!==undefined)assert(Array.isArray(item.references)&&item.references.length>0&&item.references.length<=Math.min(GENERATION_LIMITS.references,IMAGE_GENERATION_MODELS[settings.model].references)&&item.references.every(asset),'PORTABLE_ACTION',`${IMAGE_GENERATION_MODELS[settings.model].label} accepts up to ${IMAGE_GENERATION_MODELS[settings.model].references} saved reference images.`);
   }else{
    assert(item.references===undefined,'PORTABLE_ACTION','References apply to image items; use firstFrame and lastFrame for video.');
-   const settings=videoSettings(item.settings,{strict:true,firstFrame:item.firstFrame!==undefined}),entry=VIDEO_GENERATION_MODELS[settings.model];
+   const settings=videoSettings(item.settings,{strict:true,firstFrame:item.firstFrame!==undefined,lastFrame:item.lastFrame!==undefined}),entry=VIDEO_GENERATION_MODELS[settings.model];
    if(item.firstFrame!==undefined)assert(entry.firstFrame&&asset(item.firstFrame),'PORTABLE_ACTION',`${entry.label} needs a saved image as its first frame.`);
    if(item.lastFrame!==undefined)assert(entry.lastFrame&&item.firstFrame!==undefined&&asset(item.lastFrame),'PORTABLE_ACTION',`${entry.label} cannot use this last frame.`);
   }

package/packages/block-sdk/runtime.js

@@ -58,7 +58,7 @@ export async function runPackageAsync(pkg, values, options = {}) {
     // A module runs only through an injected executor: StillMade's sandboxed
     // browser Worker, or the CLI's local Node worker for the creator's own tests.
     const pinned=structuredClone(pkg),input=validateValues(pinned.manifest.inputs,values);
-    assert(typeof options.module==='function','RUNTIME_UNAVAILABLE','Module Blocks run in StillMade in the browser, or locally with the SDK CLI. They cannot run unattended: StillMade has no server sandbox for module Blocks.');
+    assert(typeof options.module==='function','RUNTIME_UNAVAILABLE','Module Blocks run in StillMade in the browser, or on your own machine with the SDK CLI (test, preview and pack for a Block or a Project Type, and ready for a Block), which passes them a local module executor; code calling the SDK directly passes options.module (createNodeModuleExecutor in module-node.js). They cannot run unattended: StillMade has no server sandbox for module Blocks.');
     const result=await executeHostCall(structuredClone(pinned),input,{signal:options.signal,execute:options.module});
     assert(!options.signal?.aborted,'CANCELLED','Run cancelled');
     assert(result&&typeof result==='object'&&Object.keys(result).every(key=>['outputs','logs'].includes(key)),'MODULE_RESULT','The module host returned an unexpected result');

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,required:true,semantic:'edit_timeline',description:'The cut to improve.'},direction:{type:'text',default:'Polish this cut conservatively.',required:false,semantic:'edit_direction',description:'How to change the cut, in a sentence.'}},outputs:{edit:{type:'timeline-edit',primary:true,semantic:'timeline_edit',description:'The proposed changes to review before they apply.'}},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,required:true,semantic:'source_audio',description:'The recording to turn into text.'},language:{type:'text',default:'auto',required:false,semantic:'language_code',description:'auto, or a two-letter language code such as en.'}},outputs:{transcript:{type:'transcript',primary:true,semantic:'timed_transcript',description:'The spoken words with their timings.'}},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,semantic:'video_prompt',description:'What the clip shows: subject, action, setting and camera, in a sentence or two.'}},outputs:{video:{type:'video',primary:true,semantic:'generated_video',description:'The generated clip.'}},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}}}],
 };

package/packages/block-sdk/view-bridge.js

@@ -11,7 +11,10 @@ export const VIEW_BRIDGE=Object.freeze([
  // Inputs and runs
  {name:'input',group:'Inputs and runs',signature:'readonly input: Partial<In>',summary:'A copy of the current input values. Read it after `onInput` first fires.',where:all},
  {name:'onInput',group:'Inputs and runs',signature:'onInput(callback: (input: Partial<In>) => void): () => void',summary:'Receives the input when the view starts and each time the host changes it. Returns a function that stops listening. Initialize controls here.',where:all},
- {name:'run',group:'Inputs and runs',signature:'run(values: In): Promise<Out>',summary:'Checks the named input values, runs the Block (its recipe, JavaScript, module or hosted operation, after any approval the host asks for) and resolves to the checked outputs. One run at a time, 30 a minute.',where:all},
+ {name:'addFiles',group:'Inputs and runs',signature:'addFiles(port: string): Promise<{added: number}>',summary:'Opens StillMade\'s own file picker for a declared `image`, `video`, `audio`, `asset` or `file` input (or a list of them) and saves what the person chooses through StillMade\'s upload, as the Step\'s own tiles do. Call it from a click or key press in the view; a list gets the files added, a single input the first. The saved values arrive through `onInput`; the view never receives a File. A `<button class="sm-add" data-stillmade-add="port">` does this with no code. Refused for an undeclared or non-file input, an input an earlier Step fills, a viewer, and without a gesture.',where:`${saved} and the SDK preview`},
+ {name:'removeFile',group:'Inputs and runs',signature:'removeFile(port: string, index: number): Promise<{files: number}>',summary:'Removes the file at `index` (from 0) of a declared list input (`image[]`, `video[]`, `audio[]`, `asset[]` or `file[]`), as the remove button on the Step\'s own tile does, and resolves to how many files the list now holds. Call it from a click or key press in the view; the new list arrives through `onInput`. A `<button data-stillmade-remove="port" data-index="2">` does this with no code. Refused for an undeclared, non-file or single input, an input an earlier Step fills, a viewer, Chat, a file that changed since the view was given it, and without a gesture.',where:`${saved} and the SDK preview`},
+ {name:'moveFile',group:'Inputs and runs',signature:'moveFile(port: string, from: number, to: number): Promise<{files: number}>',summary:'Moves the file at `from` to the place `to` (both from 0) in a declared list input, as the Step\'s own move earlier and move later buttons do, so the person sets the order (a tour, a slideshow) on the Block\'s own screen. Same gesture and refusals as `removeFile`. A `<button data-stillmade-move="port" data-index="2" data-to="1">` does this with no code; a `data-to` past either end does nothing.',where:`${saved} and the SDK preview`},
+ {name:'run',group:'Inputs and runs',signature:'run(values: In): Promise<Out>',summary:'Checks the named input values, runs the Block (its recipe, JavaScript, module or hosted operation, after any approval the host asks for) and resolves to the checked outputs. On a project Step and in the SDK preview, inputs it leaves out run with the Step\'s current values (its photos, an earlier Step\'s result), so a view passes only what it sets; what it passes is kept as the Step\'s input. One run at a time, 30 a minute.',where:all},
  {name:'useOutput',group:'Inputs and runs',signature:'useOutput(outputs: Partial<Out>): Promise<Record<string, unknown>>',summary:'Chooses media the view already holds (input media or a desktop recording) as the Block outputs without running. Only complete references the host issued are accepted.',where:saved},
  {name:'schemaFields',group:'Inputs and runs',signature:'readonly schemaFields: Readonly<Record<string, unknown>>',summary:'Helpers that build form fields from the input ports and their schemas, honoring inputs the host locked.',where:all},
  // Shared state

package/packages/block-sdk/view-design.js

@@ -19,16 +19,18 @@ export const BLOCK_KIT_CLASSES=Object.freeze({
  'sm-actions':'The action row: one .sm-primary, optional .sm-quiet buttons and .sm-icon buttons (aria-label and title required).',
  'sm-status':'Live state beside the action: data-state="loading|success|waiting|error" and a few words.',
  'sm-more':'A <details> for secondary settings; starts closed.',
- 'sm-hint':'A <details> info toggle for an explanation that might help; starts closed.',
+ 'sm-hint':'A <details> (i) for an explanation that might help; its words show on hover or focus, or a tap on touch screens.',
  'sm-gallery':'A grid of results or media. data-size="small" for input files: more tiles per row as the screen widens, never bigger tiles.',
  'sm-media-off':'A picture or clip that cannot show here (on another device, or it did not open): a quiet tile in its own shape (--sm-photo-ratio, the tile\'s shape in a gallery) holding the image-off glyph, with the reason in aria-label and title and no words inside.',
- 'sm-glyph':'A small icon drawn in currentColor: data-glyph="play|pause|plus|close|check|chevron|upload|image|image-off|video|audio|text|spark|info|warning|spinner".',
+ 'sm-add':'The add tile for an input\'s files: <button class="sm-add" data-stillmade-add="<input>" aria-label="Add photos">. StillMade opens its own picker and saves the files; never an <input type=file>. Each tile of a list can carry .sm-tile-tools with data-stillmade-move and data-stillmade-remove buttons (data-index, data-to).',
+ 'sm-scrim':'Words over a photo or video, in a positioned box such as an sm-stage: a see-through shade of the page under them, in every theme. var(--scrim) is the same shade for your own rules; never color-mix() or a fixed rgba().',
+ 'sm-glyph':'A small icon drawn in currentColor: data-glyph="play|pause|plus|close|check|chevron|chevron-left|chevron-right|upload|image|image-off|video|audio|text|spark|info|warning|spinner".',
 });
 
 // The design principles for every Block interface, in priority order.
 export const BLOCK_INTERFACE_PRINCIPLES=Object.freeze([
  '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`). 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.',
+ '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.',
@@ -38,15 +40,16 @@ export const BLOCK_INTERFACE_PRINCIPLES=Object.freeze([
  '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 a + tile. Never the bare browser file picker, and no size limits in view until a file is too big.',
+ '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 with the result first and the action within reach. 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.',
+ '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. 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.',
- '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.',
+ '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.',
@@ -68,16 +71,14 @@ export const INTERFACE_DESIGN_RULES=Object.freeze([
 ]);
 
 const occurrences=(source,pattern)=>(source.match(pattern)||[]).length;
-// A file input someone sees as the browser's own picker: not hidden and not inside a label tile.
+// A file input of the view's own, shown or hidden in a label tile (November 3, 2026: a hidden one behind a label
+// still skips StillMade's picker, its working copies and device media). Files are added with the sm-add tile.
 // One forward scan with indexOf, so odd source never makes it slow.
-function bareFilePicker(html){
+function ownFileInput(html){
  const lower=html.toLowerCase();
  for(let at=lower.indexOf('<input');at!==-1;at=lower.indexOf('<input',at+6)){
   const end=lower.indexOf('>',at);if(end===-1)return false;
-  const tag=lower.slice(at,end);
-  if(!/\btype\s*=\s*["']?file\b/.test(tag)||/\bhidden\b|display\s*:\s*none|\bsm-sr\b/.test(tag))continue;
-  const label=lower.lastIndexOf('<label',at),closed=lower.lastIndexOf('</label>',at);
-  if(label===-1||closed>label)return true;
+  if(/\btype\s*=\s*["']?file\b/.test(lower.slice(at,end)))return true;
  }
  return false;
 }
@@ -248,6 +249,30 @@ function quotedText(javascript){
  }
  return strings;
 }
+// November 3, 2026 (owner, of a Step whose settings floated on the page: "make sure it's more separated"): what the person
+// sets sits in one group (.sm-fields, or .sm-settings for short ones), which the kit puts on its own surface. Settings
+// loose on the page are counted in one pass over the tags, never by a regular expression that could backtrack.
+const SETTING_GROUPS=/\b(?:sm-fields|sm-settings|sm-more|sm-list|sm-actions)\b/;
+export function looseFields(html){
+ const stack=[],source=String(html||'');let loose=0,grouped=0;
+ for(let start=source.indexOf('<');start!==-1;start=source.indexOf('<',start+1)){
+  const end=source.indexOf('>',start);if(end===-1)break;
+  const tag=source.slice(start+1,end),closing=tag[0]==='/',name=(closing?tag.slice(1):tag).split(/[\s/>]/)[0].toLowerCase();
+  if(!/^[a-z][a-z0-9-]*$/.test(name)){start=end;continue;}
+  if(closing){
+   // Close back to the matching tag, usually the top of the stack; an unmatched close is ignored.
+   let at=stack.length-1;while(at>=0&&stack.length-at<64&&stack[at].name!==name)at--;
+   if(at>=0&&stack[at].name!==name)at=-1;
+   if(at!==-1)while(stack.length>at){if(stack.pop().grouped)grouped--;}
+   start=end;continue;
+  }
+  const classes=/\bclass\s*=\s*(["'])([^"']*)\1/i.exec(tag)?.[2]||'',group=name==='fieldset'&&!/\bsm-choices\b/.test(classes)||SETTING_GROUPS.test(classes);
+  if(/(?:^|\s)sm-field(?:\s|$)/.test(classes)&&!grouped)loose++;
+  if(!VOID_TAGS.has(name)&&!tag.endsWith('/')){stack.push({name,grouped:group});if(group)grouped++;}
+  start=end;
+ }
+ return loose;
+}
 function jobWordWarnings(view,primary){
  const warnings=[],lower=primary.toLowerCase();
  for(let start=lower.indexOf('<button'),close=0;start!==-1;start=lower.indexOf('<button',close+9)){
@@ -261,6 +286,8 @@ function jobWordWarnings(view,primary){
  if(fadedPrimary(view.css))warnings.push('Wording: the CSS gives .sm-primary the page\'s background, so the main button blends in. Keep the kit\'s solid ink button.');
  if(hiddenPick(view.css))warnings.push('Wording: the CSS restyles the picked choice (.sm-choices label:has(input:checked)), so the pick no longer reads at a glance. Keep the kit\'s ink fill and its text colour.');
  const kept=DEVICE_STATE.exec(primary.replace(/<[^<>]*>/g,' ')+'\n'+quotedText(String(view.javascript||'')));
+ const loose=looseFields(primary);
+ if(loose>=3)warnings.push(`Wording: ${loose} settings sit loose on the page. Put what the person sets in one <div class="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 apart.`);
  if(kept)warnings.push(`Wording: the screen says where a file is kept ("${kept[0]}"). Show a picture or clip that cannot show here as a quiet <span class="sm-media-off"> tile with no words; StillMade says why once, as a notification.`);
  return warnings;
 }
@@ -282,8 +309,8 @@ export function reviewViewDesign(view){
   const longText=[...primary.matchAll(/<p\b[^>]*>([\s\S]*?)<\/p>/gi)].filter(match=>words(match[1])>20).length;
   if(longText)warnings.push('A visible paragraph runs past twenty words. Drop words nobody needs; put helpful explanation in a closed <details class="sm-hint">.');
   if(/<select\b/i.test(primary)&&/<(?:img|video|audio)\b/i.test(primary)===false&&/\b(?:voice|font|look|style|color|colour|template|theme|music|sound)\b/i.test(primary))warnings.push('People choose something they see or hear from a word list. Show each option as a picture or sample in <fieldset class="sm-choices">.');
-  // Compact: a bare browser file picker and printed size limits each take rows nobody needs.
-  if(bareFilePicker(primary))warnings.push('A bare file picker is in view. Show files as tiles: a + tile (a label around a hidden file input) and a thumbnail or chip for each saved file.');
+  // Compact: the view's own file picker and printed size limits each take rows nobody needs.
+  if(ownFileInput(primary))warnings.push('The view has a file input of its own. Show files as tiles: a thumbnail or chip for each saved file and the + tile, <button class="sm-add" data-stillmade-add="<input>" aria-label="Add photos">, which opens StillMade\'s picker and saves the files.');
   if(/\bup to \d+\s*(?:mb|gb|kb)\b/i.test(primary.replace(/<[^<>]*>/g,' ')))warnings.push('A size limit is printed in view. Say it only when a file is too big.');
   if(stackedLabel(primary,view.css))warnings.push('A short setting has its label above the control. Put the label beside it: <div class="sm-field"><label for="x">Label</label><input id="x"></div>, or several side by side in .sm-settings.');
   const rareTool=rareToolSection(html);
@@ -302,12 +329,14 @@ export function reviewViewDesign(view){
 
 // October 30, 2026: Chat presses a button on a Block's own screen only when it carries data-stillmade-action
 // (naming what it does); an unmarked button is out of Chat's reach. The number of buttons in view.html without one.
+// The + tile (data-stillmade-add) is not counted: StillMade's picker opens only from the person's own click.
 export function unmarkedButtons(view){
  const html=String(view?.html||''),lower=html.toLowerCase();let count=0;
  for(let start=lower.indexOf('<button');start!==-1;start=lower.indexOf('<button',start+7)){
   if(!/[\s>/]/.test(lower[start+7]||''))continue;
   const end=lower.indexOf('>',start);if(end===-1)break;
-  if(!/\sdata-stillmade-action\s*=/.test(lower.slice(start,end)))count++;
+  const tag=lower.slice(start,end);
+  if(!/\sdata-stillmade-(?:action|add)\s*=/.test(tag))count++;
  }
  return count;
 }

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

@@ -3,12 +3,12 @@ import {EXAMPLE_PROVENANCE} from './example-license.js';
 // the search; the Block names only what to read and what to do with it. Both
 // are paid with StillMade credits at the app's research prices.
 export const webFetch={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.summarize-page',version:'1.0.0',name:'Summarize a page',description:'Read a public web page and summarize it in a few production-ready bullet points.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{url:{type:'text',primary:true,semantic:'page_url',required:true,description:'Public http or https page to read.'}},outputs:{summary:{type:'text',primary:true,semantic:'page_summary',description:'Summary of the page.'}},permissions:{project:[],capabilities:['web.fetch'],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'url'}]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.summarize-page',action:{label:'Summarize page',running:'Summarizing page…'},version:'1.0.0',name:'Summarize a page',description:'Read a public web page and summarize it in a few production-ready bullet points.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{url:{type:'text',primary:true,semantic:'page_url',required:true,description:'Public http or https page to read.'}},outputs:{summary:{type:'text',primary:true,semantic:'page_summary',description:'Summary of the page.'}},permissions:{project:[],capabilities:['web.fetch'],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'url'}]},
  capability:{schemaVersion:1,operation:'web.fetch',url:{$input:'url'},instruction:'Summarize the page in five short bullet points a video producer can use. Quote numbers exactly.',output:'summary'},
  tests:[{name:'Read a public page',input:{url:'https://en.wikipedia.org/wiki/Tide'},expectations:{summary:{kind:'text',minLength:20,maxLength:4000}}}],
 };
 export const webResearch={
- manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.research-topic',version:'1.0.0',name:'Research a topic',description:'Search the web for a topic and return a cited summary.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{topic:{type:'text',primary:true,semantic:'research_topic',required:true,description:'What to research.'}},outputs:{findings:{type:'json',primary:true,semantic:'research_findings',description:'Summary and the sources it came from.'}},permissions:{project:[],capabilities:['web.research'],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'topic'}]},
+ manifest:{schemaVersion:1,sdkVersion:'0.1.0',id:'example.research-topic',action:{label:'Research topic',running:'Researching topic…'},version:'1.0.0',name:'Research a topic',description:'Search the web for a topic and return a cited summary.',kind:'task',runtime:'capability',entry:'src/capability.json',license:'MIT',provenance:EXAMPLE_PROVENANCE,inputs:{topic:{type:'text',primary:true,semantic:'research_topic',required:true,description:'What to research.'}},outputs:{findings:{type:'json',primary:true,semantic:'research_findings',description:'Summary and the sources it came from.',schema:{summary:'text',sources:'json[]'}}},permissions:{project:[],capabilities:['web.research'],network:[],filesystem:[],secrets:[]},ui:[{control:'text',port:'topic'}]},
  capability:{schemaVersion:1,operation:'web.research',topic:{$input:'topic'},output:'findings'},
  tests:[{name:'Tides',input:{topic:'How tides work'},expectations:{findings:{kind:'json',includes:['summary']}}}],
 };