stillmade-sdk 0.1.8 → 0.1.10

package/packages/block-platform/project-start-input.js

@@ -1,6 +1,7 @@
 import {assert,valueMatches} from '../block-sdk/contracts.js';
 import {semanticCompatibility} from '../block-sdk/semantic-contracts.js';
 import {createSemanticContext} from './semantic-context.js';
+import {isBriefPort,inputLabel} from './brief-ports.js';
 
 export function seedProjectStartContext(canvas,definition,brief,{now=Date.now()}={}) {
  if(typeof brief!=='string'||!brief.trim())return canvas;
@@ -32,3 +33,48 @@ export function seedProjectStartBrief(compiled,brief){
  if(previous!==undefined&&previous!=='')return compiled.canvas;
  return {...compiled.canvas,nodes:compiled.canvas.nodes.map(item=>item===node?{...node,data:{...node.data,blockInputs:{...node.data.blockInputs,[name]:brief}}}:item)};
 }
+
+// A new project never starts with a brief its Project Type was saved with. A
+// Step's brief is the facts about the thing this project makes, which come from
+// this project's own Chat; a brief saved in a Type was written while the Type was
+// being built (October 2026: a dealer script brief carried the builder's step
+// names "Import media, Script Writer, Voiceover…" and a test car's mileage into
+// every new project, and Chat never asked because the input looked answered).
+// Only the project's Block inputs change: the definition stays the exact pinned
+// Type, so release and automation digests still match.
+// One brief rule (brief-ports.js): a brief input, or a custom Block's text input named or
+// labelled "brief" (October 16, 2026: a custom script Block's text "brief" kept the builder's
+// words because only brief-typed inputs were left to Chat).
+export function leaveStepBriefsToChat(compiled){
+ let changed=false;
+ const nodes=compiled.canvas.nodes.map(node=>{
+  const manifest=node.type==='programmableBlockNode'?node.data?.blockPackage?.manifest:null,ports=manifest?.inputs,inputs=node.data?.blockInputs;
+  if(!ports||!inputs)return node;
+  const drop=Object.keys(inputs).filter(name=>isBriefPort(name,ports[name],{label:inputLabel(manifest,name)}));
+  if(!drop.length)return node;
+  changed=true;
+  const kept={...inputs};for(const name of drop)delete kept[name];
+  return {...node,data:{...node.data,blockInputs:kept}};
+ });
+ return changed?{...compiled,canvas:{...compiled.canvas,nodes}}:compiled;
+}
+
+// The same rule for a Project Type a Chat build places (use_project_type) or puts together
+// (prepare_automation): its Steps' saved brief settings are left out, so the project's own
+// Chat step gathers those facts (October 16, 2026: a Type built in the builder chat carried
+// the builder's request in its script Step's brief). manifestOf(stage) gives each Step's
+// Block; only, when given, limits it to those Step ids (Steps already in a project keep theirs).
+export function leaveTypeBriefsToChat(type,manifestOf,{only=null}={}){
+ let changed=false;
+ const stages=(type?.stages||[]).map(stage=>{
+  if(only&&!only.has(stage.id)||!stage.config||typeof stage.config!=='object')return stage;
+  let manifest=null;try{manifest=manifestOf(stage);}catch{manifest=null;}
+  const drop=Object.keys(stage.config).filter(name=>isBriefPort(name,manifest?.inputs?.[name],{label:inputLabel(manifest,name)}));
+  if(!drop.length)return stage;
+  changed=true;
+  const config={...stage.config};for(const name of drop)delete config[name];
+  const {config:_config,...rest}=stage;
+  return Object.keys(config).length?{...rest,config}:rest;
+ });
+ return changed?{...type,stages}:type;
+}

package/packages/block-platform/segment-runner.js

@@ -23,7 +23,7 @@ import {pinCurrentSemanticSource,pinExplicitFlowSource,assertCurrentSemanticSour
 import {workflowDependencyOrder} from './workflow-dependency-order.js';
 import {USER_REQUEST_LIMIT,userRequestRequirement,chatRequestRequirement,checkedUserRequestAnswer} from '../block-sdk/interactive-requirements.js';
 import {validateWorkflowApproval} from '../block-sdk/workflow-approvals.js';
-import {groupOf} from './step-groups.js';
+import {groupOf,withoutGroups} from './step-groups.js';
 import {UNATTENDED_HOSTED_OPERATIONS} from './unattended.js';
 export {UNATTENDED_HOSTED_OPERATIONS};
 
@@ -66,7 +66,9 @@ export async function planSegment(projectType,canvas,startStepId,{interactive=fa
  const type=structuredClone(projectType),graph=structuredClone(canvas),operations=structuredClone(applicationOperations);
  safeDocument(operations);assert(plain(operations),'BROWSER_APPLICATION_OPERATION','Select application operations by Step ID.');
  safeDocument(type);assert(plain(graph) && Array.isArray(graph.nodes) && Array.isArray(graph.edges),'SEGMENT_CANVAS','A saved production Canvas is required');
- if(graph.projectType)assert(stableStringify(graph.projectType)===stableStringify(type),'SEGMENT_CHANGED','The workflow and Canvas definitions differ');
+ // Step groups only change what people see and which job one button runs, so a
+ // Canvas saved before its Step was condensed still matches (Block in block).
+ if(graph.projectType)assert(stableStringify(withoutGroups(graph.projectType))===stableStringify(withoutGroups(type)),'SEGMENT_CHANGED','The workflow and Canvas definitions differ');
  const compiled=await compileTypeWorkspace(type,{experimentalBrowser:experimentalBrowser ?? experimentalBrowserValidation}),active=type.stages.filter(step=>step.enabled!==false);
  // One Step per job: with no explicit range, an interactive run from any part
  // of a Step group runs that whole job, from its first enabled part to its last.

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

@@ -42,9 +42,13 @@ export function normalizeGroups(type){
   return [{id:group.id,label:group.label,stages,...(settings.length?{settings}:{}),...(result?{result}:{})}];
  });
  if(!groups.length){const {groups:_dropped,...rest}=type;return rest;}
+ // Unchanged groups keep the type's identity, so memo boundaries hold.
+ if(groups.length===type.groups.length&&groups.every((group,index)=>JSON.stringify(group)===JSON.stringify(type.groups[index])))return type;
  return {...type,groups};
 }
 
+/** The type without its Step groups: the same workflow, whatever people see. */
+export function withoutGroups(type){if(!type||!Object.hasOwn(type,'groups'))return type;const {groups:_groups,...rest}=type;return rest;}
 /** The group a Step belongs to, if any. */
 export const groupOf=(type,stageId)=>(type.groups||[]).find(group=>group.stages.includes(stageId))||null;
 

package/packages/block-platform/steps.js

@@ -83,6 +83,46 @@ export function insertionLocations(type,pkg,catalog=[],options={}) {
  });
 }
 
+// A connection along the executable primary chain (rebuilt around a gap), as
+// opposed to an explicit secondary or context handoff.
+function primaryEdge(type,from,to,edge,catalog) {
+ const output=automaticPort(manifestFor(type,from,catalog),'outputs'),input=automaticPort(manifestFor(type,to,catalog),'inputs');
+ return !!(output&&input&&edge.from.port===output.name&&edge.to.port===input.name);
+}
+const portWords=name=>String(name||'').replace(/([a-z0-9])([A-Z])/g,'$1 $2').replace(/[_-]+/g,' ').trim().toLowerCase()||'result';
+const stepName=(type,step,catalog)=>String(step?.label||manifestFor(type,step,catalog)?.name||step?.id||'Step');
+const joined=items=>items.length<3?items.join(' and '):`${items.slice(0,-1).join(', ')} and ${items.at(-1)}`;
+// Whether an input still has a value without its connection: it is optional, or
+// has a default it may use, a project document (context) or the Step's own setting.
+function fallsBack(step,port,name) {
+ if(!port||port.required===false||port.context)return true;
+ if(Object.hasOwn(port,'default')&&(!Array.isArray(port.sources)||port.sources.includes('default')))return true;
+ return Object.hasOwn(step.config||{},name)||Object.hasOwn(step.inputSources||{},name);
+}
+// Names the Steps that read an explicit result of a Step that is leaving.
+function stillUsed(type,edges,catalog) {
+ const byId=new Map(type.stages.map(step=>[step.id,step])),name=id=>`“${stepName(type,byId.get(id),catalog)}”`;
+ const uses=edges.map(edge=>`${name(edge.to.stage)} uses the ${portWords(edge.from.port)} of ${name(edge.from.stage)} for its ${portWords(edge.to.port)} input`);
+ return `${joined(uses)}. Replace ${joined([...new Set(edges.map(edge=>name(edge.from.stage)))])} with a compatible Block or remove ${joined([...new Set(edges.map(edge=>name(edge.to.stage)))])} first.`;
+}
+/**
+ * What deleting the Steps `ids` cuts: each explicit connection from one of them
+ * into an input of a kept, enabled Step (the primary chain closes around the
+ * gap instead). `optional` inputs are disconnected by the delete; one the kept
+ * Step needs refuses it.
+ *   [{edge, from:{stage,label,output}, to:{stage,label,input}, optional}]
+ */
+export function removalDependents(type,ids,catalog=[]) {
+ const gone=new Set(ids),byId=new Map((type?.stages||[]).map(step=>[step.id,step])),cut=[];
+ for(const edge of type?.connections||[]) {
+  const from=byId.get(edge.from?.stage),to=byId.get(edge.to?.stage);
+  if(!from||!to||!gone.has(from.id)||gone.has(to.id)||to.enabled===false||primaryEdge(type,from,to,edge,catalog))continue;
+  cut.push({edge,from:{stage:from.id,label:stepName(type,from,catalog),output:portWords(edge.from.port)},to:{stage:to.id,label:stepName(type,to,catalog),input:portWords(edge.to.port)},
+   optional:fallsBack(to,manifestFor(type,to,catalog)?.inputs?.[edge.to.port],edge.to.port)});
+ }
+ return cut;
+}
+
 // Rebuild each existing executable primary chain, retaining independent chains
 // and explicit secondary/context handoffs. No new host port is invented, and an
 // active consumer's secondary source cannot silently disappear.
@@ -92,11 +132,11 @@ export function changeSteps(type,stages,catalog=[]) {
  for(const edge of type.connections||[]) {
   const from=byId.get(edge.from?.stage),to=byId.get(edge.to?.stage);
   assert(from&&to,'STEP_REFERENCE','A connection references a missing Step');
-  const output=automaticPort(manifestFor(type,from,catalog),'outputs'),input=automaticPort(manifestFor(type,to,catalog),'inputs');
-  if(output&&input&&edge.from.port===output.name&&edge.to.port===input.name){primary.push(edge);participants.add(from.id);participants.add(to.id);}else explicit.push(edge);
+  if(primaryEdge(type,from,to,edge,catalog)){primary.push(edge);participants.add(from.id);participants.add(to.id);}else explicit.push(edge);
  }
  const active=new Set(stages.filter(step=>step.enabled!==false).map(step=>step.id));
- for(const edge of explicit)assert(!active.has(edge.to.stage)||active.has(edge.from.stage),'STEP_REFERENCE','Another Step still uses this Block’s output. Replace it with a compatible Block or remove the dependent Step first.');
+ const used=explicit.filter(edge=>active.has(edge.to.stage)&&!active.has(edge.from.stage));
+ assert(!used.length,'STEP_REFERENCE',used.length?stillUsed(type,used,catalog):'');
  const connections=explicit.filter(edge=>active.has(edge.from.stage)&&active.has(edge.to.stage));
  const unseen=new Set(participants);
  while(unseen.size){
@@ -113,7 +153,18 @@ export function changeSteps(type,stages,catalog=[]) {
  }
  return validated({...type,stages,connections},catalog);
 }
-export function removeStep(type,id,catalog=[]) {assert(type.stages.some(step=>step.id===id),'STEP','Step not found');return changeSteps({...type,...(type.rules?{rules:type.rules.filter(rule=>rule.stepId!==id&&rule.endStepId!==id)}:{})},type.stages.filter(step=>step.id!==id),catalog);}
+export function removeStep(type,id,catalog=[]) {return removeSteps(type,[id],catalog);}
+// A Step people see may be several Blocks (step-jobs.js condensedType); they
+// leave together in one change, so a connection between them never blocks it.
+// A kept Step's optional input fed by a leaving Step is disconnected (October
+// 17, 2026: Export video 2.1.0's optional media and narration refused deleting
+// Import media and Voiceover); an input it needs refuses the delete, by name.
+export function removeSteps(type,ids,catalog=[]) {
+ const gone=new Set(ids);
+ assert(gone.size>0&&[...gone].every(id=>type.stages.some(step=>step.id===id)),'STEP','Step not found');
+ const disconnected=new Set(removalDependents(type,[...gone],catalog).filter(item=>item.optional).map(item=>item.edge));
+ return changeSteps({...type,...(type.connections?{connections:type.connections.filter(edge=>!disconnected.has(edge))}:{}),...(type.rules?{rules:type.rules.filter(rule=>!gone.has(rule.stepId)&&!gone.has(rule.endStepId))}:{})},type.stages.filter(step=>!gone.has(step.id)),catalog);
+}
 export function moveStep(type,id,index,catalog=[]) {
  const step=type.stages.find(step=>step.id===id);assert(step&&Number.isInteger(index)&&index>=0&&index<type.stages.length,'STEP','Choose a valid Step position');
  if(type.stages[index]===step)return type;

package/packages/block-platform/type-preview.js

@@ -18,8 +18,13 @@ import {assertInputSource,assertSuppliedInputSources,inputSourceAllowed} from '.
 import {projectInputSampleValues} from './project-input-samples.js';
 import {resolveSemanticInputs} from './semantic-inputs.js';
 import {packageForStage} from './stage-package.js';
+import {briefInputNames} from './brief-ports.js';
 
-export function workflowPreviewChecks(preview){return preview.results.map(result=>({name:`Connected workflow: ${result.name}`,passed:['completed','skipped'].includes(result.status),status:result.status==='completed'?'passed':result.status==='skipped'?'skipped':result.status==='disabled'?'disabled':['blocked','needs-project','needs-context','needs-hosted-run'].includes(result.status)?'deferred':'failed',...(result.deferral ? {deferral:result.deferral} : {}),...(result.hostedPackageDigests ? {hostedPackageDigests:[...result.hostedPackageDigests]} : {}),...(result.code ? {code:result.code} : {}),message:result.message || (result.status==='skipped' ? 'Condition skipped; input passed through' : result.status==='completed' ? 'Validated connected sample input and output' : result.status)}));}
+export function workflowPreviewChecks(preview){return preview.results.map(result=>({name:`Connected workflow: ${result.name}`,passed:['completed','skipped'].includes(result.status),status:result.status==='completed'?'passed':result.status==='skipped'?'skipped':result.status==='disabled'?'disabled':['blocked','needs-project','needs-context','needs-hosted-run','needs-sample'].includes(result.status)?'deferred':'failed',...(result.deferral ? {deferral:result.deferral} : {}),...(result.hostedPackageDigests ? {hostedPackageDigests:[...result.hostedPackageDigests]} : {}),...(result.code ? {code:result.code} : {}),message:result.message || (result.status==='skipped' ? 'Condition skipped; input passed through' : result.status==='completed' ? 'Validated connected sample input and output' : result.status)}));}
+
+// A brief with no text (nothing, an empty string or a document with empty text).
+const blankBrief=value=>value===undefined||value===null||(typeof value==='string'?!value.trim():plain(value)&&typeof value.text==='string'&&!value.text.trim());
+const briefLabel=(manifest,name)=>{const label=manifest.ui?.find(item=>item?.port===name)?.label||name;return String(label).replace(/([a-z0-9])([A-Z])/g,'$1 $2').replace(/[_-]+/g,' ').trim().toLowerCase();};
 
 // A side-effect-free rehearsal using exact pinned packages. Hosted workspaces
 // are marked as requiring a real project; no provider calls are simulated.
@@ -63,8 +68,15 @@ export async function previewProjectType(type,{run=runPackageAsync,inputs={},con
    else try {
     // Fixture values seed unconnected sample inputs. Live edge values always win;
     // a downstream fixture must never hide a broken connection or overwrite it.
+    // In the author's preview (interactive) a Block's test fixture never stands in
+    // for a Step's brief (brief-ports.js): the author writes a sample brief, as each
+    // project's Chat writes the real one. October 17, 2026: the Type builder showed
+    // the owner's script Block's first fixture ("32,400 miles, Palm Beach Auto Mall")
+    // as the Step's brief. Automated checks (imports, listing samples) still run the
+    // Block's own example.
     assertSuppliedInputSources(m,step.config || {},inputs[step.id] || {},{connected:incoming.map(edge=>edge.to.port)});
-    const fixture=Object.fromEntries(Object.entries(pkg.tests[0].input).filter(([name])=>m.inputs[name] && !m.inputs[name].context && inputSourceAllowed(m.inputs[name],'user')));
+    const briefs=interactive?briefInputNames(m):[];
+    const fixture=Object.fromEntries(Object.entries(pkg.tests[0].input).filter(([name])=>m.inputs[name] && !m.inputs[name].context && inputSourceAllowed(m.inputs[name],'user') && !briefs.includes(name)));
     const values={...step.config,...inputs[step.id]};
     for(const edge of incoming){
      const producer=pinned.stages.find(step=>step.id===edge.from.stage),source=packageForStage(pinned,producer,BUILTIN_BLOCKS);
@@ -74,6 +86,9 @@ export async function previewProjectType(type,{run=runPackageAsync,inputs={},con
     }
     const semantic=sharedValues.length?resolveSemanticInputs(m,values,sharedValues,{context:authorizedContext,semantics}).inputs:values;
     const resolved=resolveContextInputs(m,{...fixture,...semantic},authorizedContext);
+    const missingBrief=briefs.find(name=>!incoming.some(edge=>edge.to.port===name)&&blankBrief(resolved[name])&&(m.inputs[name].required!==false||pkg.capability?.prompt?.$input===name));
+    if(missingBrief)result={...result,status:'needs-sample',message:`Write a sample ${briefLabel(m,missingBrief)} for this Step under Sample inputs to try it. A Block’s own example is never used as a Step’s brief.`};
+    else{
     for(const [name,port] of Object.entries(m.inputs))if(Object.hasOwn(resolved,name)){resolved[name]=media.hydrate(port,resolved[name]);if(interactive&&resolveInput)resolved[name]=await resolveInput(pkg,port,resolved[name],{signal:controller.signal});check();}
     const input=validateValues(m.inputs,resolved);
     charge(stableStringify(input).length);
@@ -99,10 +114,11 @@ export async function previewProjectType(type,{run=runPackageAsync,inputs={},con
      charge(stableStringify(outputs).length);
      result={...result,status:execution.skipped ? 'skipped' : 'completed',input,outputs,...(execution.comfyuiRun?{comfyuiRun:structuredClone(execution.comfyuiRun)}:{}),...(execution.capabilityRun?{capabilityRun:structuredClone(execution.capabilityRun)}:{}),...(execution.mediaReceipts?{mediaReceipts:structuredClone(execution.mediaReceipts)}:{})};
     }
+    }
    }catch(error){if(controller.signal.aborted || signal?.aborted || Date.now()>=deadline)throw error;result={...result,status:'failed',code:error.code || 'EXECUTION',message:error.message};}
    completed.set(step.id,result);results.push(result);await onResult(structuredClone(result));check();
   }
-  const failed=results.some(result=>result.status==='failed'),incomplete=results.some(result=>['blocked','needs-project','needs-context','needs-hosted-run'].includes(result.status));
+  const failed=results.some(result=>result.status==='failed'),incomplete=results.some(result=>['blocked','needs-project','needs-context','needs-hosted-run','needs-sample'].includes(result.status));
   return {digest:await digest(pinned),passed:!failed,complete:!failed && !incomplete,status:failed?'failed':incomplete?'deferred':'completed',results};
  }finally{media.dispose();clearTimeout(timer);signal?.removeEventListener('abort',cancel);controller.abort();}
 }

package/packages/block-platform/workspace-input-readset.js

@@ -32,7 +32,12 @@ export async function captureWorkspaceInputReadSet({manifest,input,project,scope
   if(!port.context||input[key]===undefined)continue;
   const nativeScopes=workspaceContextReadScopes(port.context);
   if(!nativeScopes.length){const collection=await workspaceCollectionSources({manifest,key,input,project,scope,source,sourceNodeIds});if(collection)collections.push({key,context:port.context,inputDigest:await digest(input[key]),...collection});else unprotected.push({key,context:port.context});continue;}
-  assert(stableStringify(input[key])===stableStringify(expected[key]),'CONFLICT','The dispatched native workspace input no longer matches its source. Review and run it again.');
+  // A project without this document yet (no shot plan, no voiceover take) gives
+  // the run the port's declared default. That value is read against the
+  // document's empty native form below, so a document made later still blocks
+  // applying a result built without it.
+  const absent=expected[key]===undefined;
+  assert(absent?Object.hasOwn(port,'default')&&stableStringify(input[key])===stableStringify(port.default):stableStringify(input[key])===stableStringify(expected[key]),'CONFLICT','The dispatched native workspace input no longer matches its source. Review and run it again.');
   if(['shots','scenes'].includes(port.context)||port.context==='script'&&(source!=null||projectContextScope(scope).kind!=='project')){
    const originals=shotIndexContextSources({manifest,key,project,scope,source,input});if(!originals){unprotected.push({key,context:port.context,reason:'scoped-source-attribution-unavailable'});continue;}
    for(const [nativeScope,document] of Object.entries(originals)){if(documents.has(nativeScope))assert(stableStringify(documents.get(nativeScope))===stableStringify(document),'CONFLICT','Original derived context documents disagree.');documents.set(nativeScope,document);ports.push({key,context:port.context,scope:nativeScope,inputDigest:await digest(input[key]),derivation:'shot-index'});}continue;

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

@@ -3,10 +3,13 @@
 // human developers) receives a rendering of this module, so a rule changes in
 // one place. Lists that track the platform (hosted operations) are read from
 // contracts.js, so the contract follows the SDK as it grows.
+// How to write the package itself (format, runtimes, hosted operations, project
+// context, custom views) is authoring-guide.js, rendered for the same audiences;
+// scripts/block-paths-share-sdk.test.js keeps every in-app builder on both.
 import {HOSTED_OPERATION_NAMES} from './contracts.js';
 
 export const BUILDER_CONTRACT_ID='stillmade.block-builder';
-export const BUILDER_CONTRACT_VERSION='1.3.0';
+export const BUILDER_CONTRACT_VERSION='1.5.1';
 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.
@@ -36,7 +39,7 @@ const SECTIONS=Object.freeze([
   'Before building, check what already exists (`find_existing_blocks` over MCP, or the Marketplace and your library) by the inputs, results and operations the goal needs. Use an installed or reviewed Block that already does it; remix a close one so its license, notices and creator credit stay attached; chain existing Blocks and build only the missing step. Never republish another creator\'s source without remix lineage: public copies are refused. Build a new Block when nothing fits or the person asks for their own version, and say which similar Blocks you considered.'),
  rule('block-scope','both',
   'One Step per job: start one only where a person works with the result, where finding new items turns into handling each, or where the result leaves StillMade; all else is a part.',
-  'A Step is one job: the work between two moments where a person or the outside world must see the result. Start a new Step only at one of three points; everything else is a part of the neighboring Step.\n\n1. **A person works with the result**: reads, edits, picks or approves it (a workspace Block such as a script, a Canvas or an Editor, or an approval). That is why Chat, Bible, Canvas and Editor are four Steps.\n2. **Finding new things turns into handling each one**: the trigger (a schedule or an app event), the app read, its filter and "only new" are the first job; what is done with each item is the next job. A trigger is a setting of the first job, never a Step of its own.\n3. **The result leaves StillMade**: it is sent, posted, published, paid or written into another app. Consecutive writes to the same app, with the glue that shapes data for them, are one job.\n\nA part that only runs in the desktop app cannot share a Step with cloud parts. Before adding a Step, name which of the three reasons makes it separate; if none applies, make it a part of a neighbor. A Step nobody would ever open must not exist on its own. Prefer an app task\'s own filter (a Gmail query such as `has:attachment filename:png`) to an AI check, and use AI decide only for judgement.\n\nInside one job, each capability stays its own part: a capability Block performs exactly one hosted operation and a connector one app task, so every part keeps its own permission, approval and credit rules, and StillMade groups the parts of one job into one Step (`groups` in the Project Type). Never invent a combined runtime. When one Block can do the whole job with documented primitives (a JavaScript Block doing several local transforms, a workspace owning its whole document), build it as one Block.\n\nExamples: "every new email with an image becomes a generated image" is two Steps, "Gmail · New emails with images" (When, fetch with an image filter, only new) and "Image from email" (AI write, Generate image); listing When, Fetch, Only new, AI decide, Continue only if, AI write and Generate image as seven Steps splits one job into its parts. "A new Meta lead goes to HubSpot" is three Steps: "Meta Ads · New leads", "Qualify lead" and "HubSpot · Add contact".'),
+  'A Step is one job: the work between two moments where a person or the outside world must see the result. Start a new Step only at one of three points; everything else is a part of the neighboring Step.\n\n1. **A person works with the result**: reads, edits, picks or approves it (a workspace Block such as a script, a Canvas or an Editor, or an approval). That is why Chat, Bible, Canvas and Editor are four Steps.\n2. **Finding new things turns into handling each one**: the trigger (a schedule or an app event), the app read, its filter and "only new" are the first job; what is done with each item is the next job. A trigger is a setting of the first job, never a Step of its own.\n3. **The result leaves StillMade**: it is sent, posted, published, paid or written into another app. Consecutive writes to the same app, with the glue that shapes data for them, are one job.\n\nIn a production the Steps are the workspaces a person opens: work feeding the next workspace is its part, else it joins the one before; neighbouring workspaces with one main result type are one Step unless another part feeds the second. A video ends in the Editor (1.0), which has captions and export built in, so Export video is never a Step beside it.\n\nA part that only runs in the desktop app cannot share a Step with cloud parts. Before adding a Step, name which of the three reasons makes it separate; if none applies, make it a part of a neighbor. A Step nobody would ever open must not exist on its own. Prefer an app task\'s own filter (a Gmail query such as `has:attachment filename:png`) to an AI check, and use AI decide only for judgement.\n\nInside one job, each capability stays its own part: a capability Block performs exactly one hosted operation and a connector one app task, so every part keeps its own permission, approval and credit rules, and StillMade groups the parts of one job into one Step (`groups` in the Project Type). Never invent a combined runtime. When one Block can do the whole job with documented primitives (a JavaScript Block doing several local transforms, a workspace owning its whole document), build it as one Block.\n\nExamples: "every new email with an image becomes a generated image" is two Steps, "Gmail · New emails with images" (When, fetch with an image filter, only new) and "Image from email" (AI write, Generate image); listing When, Fetch, Only new, AI decide, Continue only if, AI write and Generate image as seven Steps splits one job into its parts. "A new Meta lead goes to HubSpot" is three Steps: "Meta Ads · New leads", "Qualify lead" and "HubSpot · Add contact".'),
  rule('capability-contract','block',
   'Define the contract first: typed inputs (optional with safe defaults where possible), outputs, state, permissions, UI, failures and cancellation. Keep the interface small; keep the job whole.',
   'Translate the request into an explicit capability contract before implementation: what the Block does; each input with its type, meaning and whether it is required (prefer optional settings with safe defaults over extra required questions); each output with its type and meaning; persistent state; project context it reads; permissions; UI; long-running behavior; expected failures; cancellation; determinism; and whether it needs hosted models, media, desktop tools or shared editing. Keep the public interface as small and general as possible (few required inputs, one primary output) and keep implementation details out of it; small means a small interface, never a fragment of a job. A Block that generates images, video or speech declares only its prompt and output: every Step that runs it gets the host’s generation settings (model, quality, length and resolution, voice, speed, how many), saved with the Step, changed on its page or by Chat, and shown with their cost before each run.'),
@@ -53,8 +56,8 @@ const SECTIONS=Object.freeze([
   `Name the Block in ${BLOCK_NAME_MAX_LENGTH} characters or fewer, in plain words.`,
   `Give the Block a short, plain name of ${BLOCK_NAME_MAX_LENGTH} characters or fewer that says what it does ("Captioned Clip", not "Captioned Business Clip Generator With Review"). The name appears in step bars, Project Type cards and pickers, so put the detail in the description instead. New releases with a longer name do not pass readiness.`),
  rule('ui','block',
-  'Prefer `manifest.ui` controls; a custom view only when needed: run via `StillMade.run`; show progress, errors, outputs, and previews of options people hear or see; no raw JSON or IDs; fit a 320px phone.',
-  'If the capability needs UI, use the Block UI SDK: generated `manifest.ui` controls first; a sandboxed custom view (`view.html`/`view.css`/`view.js`) only when the core interaction genuinely needs one. Expose the capability, not the implementation: meaningful controls, sensible defaults, preview, direct manipulation, progress, clear errors and visible outputs. Do not show raw JSON, internal IDs, filesystem details, provider terminology or developer settings unless the Block is itself a developer tool. When a person chooses among options they need to hear or see (voices, music, sounds, fonts, looks, colors, templates or images), let them preview each option before choosing: a sample to play or a thumbnail, from the Block\'s own files or the host\'s free samples, never a paid generation. Leave previews out only when the builder states there is nothing to preview. Choices StillMade owns, such as voices and models in the run review, already show their samples. Follow the host appearance (Light, Dark and White) and the mobile layout contract: one interface for every screen size that fits a 320 CSS-pixel phone without horizontal scrolling.'),
+  'Prefer `manifest.ui`; custom views use the Block kit (`sm-*` classes) unless a look is named. Pictures over words: preview each option before choosing; cut needless words, fold the rest; the start button names the action (never "Run") and shows no price (StillMade adds it); fit one screen unscrolled and a 320px phone.',
+  'If the capability needs UI, use the Block UI SDK: generated `manifest.ui` controls first; a sandboxed custom view (`view.html`/`view.css`/`view.js`) only when the core interaction genuinely needs one. Build custom views from the Block kit the host injects (`block-kit.css`): the result in `sm-stage`, picks as pictures in `sm-choices`, one `sm-primary` naming the action (Write, Generate; never "Run") and no price (StillMade\'s run button adds it), extras in a closed `sm-more`; a look the person names wins. Fit one laptop screen without scrolling: label beside control, status in a few words, files as tiles, rare tools as icons. Drop words nobody needs; put helpful ones in a closed `sm-hint`. Expose the capability, not the implementation: meaningful controls, sensible defaults, preview, direct manipulation, progress, clear errors and visible outputs. Do not show raw JSON, internal IDs, filesystem details, provider terminology or developer settings unless the Block is itself a developer tool. When a person chooses among options they need to hear or see (voices, music, sounds, fonts, looks, colors, templates or images), let them preview each option before choosing: a sample to play or a thumbnail, from the Block\'s own files or the host\'s free samples, never a paid generation. Leave previews out only when the builder states there is nothing to preview. Choices StillMade owns, such as voices and models in the run review, already show their samples. Follow the host appearance (Light, Dark and White) and the mobile layout contract: one interface for every screen size that fits a 320 CSS-pixel phone without horizontal scrolling.'),
  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.'),
@@ -73,6 +76,9 @@ const SECTIONS=Object.freeze([
  rule('errors','block',
   'Fail usefully: throw an Error saying what failed, why, whether retrying helps and what to do; StillMade shows it as the run failure. Never "Something went wrong".',
   'Errors must say what failed, why it likely failed, whether a retry makes sense and what the user can do, so the native project chat and controller can troubleshoot. In JavaScript, throw an `Error` with that message: the host reports it as a `JAVASCRIPT` run failure carrying your message (guest code cannot set its own error code). Reject invalid or oversized input up front with a message naming the input and the limit. Never reduce a failure to "Something went wrong".'),
+ rule('grounded-text','block',
+  'Write only supplied facts; drop or generalise a section whose fact is missing.',
+  'A text Block that writes from supplied facts must not let its prompt template outrank its own "never invent" rule. Every section that needs a specific fact (phone, website, address, price, inspection, certification, warranty, features) is written only when the input supplies that fact; otherwise the section is left out or replaced by a generic line that asserts nothing (for example "Call us today to schedule your test drive."). Never default to "inspected", "certified", invented features or placeholder contact details such as 555 numbers or example websites. Prefer extract-then-generate: first list the facts the input actually contains, then write using only that list. Add a check after generation that rejects or removes sentences naming a claim, number or address not present in the input. Include fixtures with the facts omitted and with them supplied.'),
  rule('adapt-to-platform','both',
   'If documented primitives cannot do it, return {"unsupported":"exact reason","gapClass":"B|C|D|E|F","primitive":"smallest general primitive"}; never fake a working package.',
   'Do not modify StillMade core because a request does not fit immediately. First implement the capability entirely through documented SDK and platform primitives. If that is impossible, classify why: A Block implementation problem (fix it), B missing SDK exposure of an existing host capability, C missing generic platform primitive, D security or permission restriction, E runtime or language incompatibility, F fundamentally incompatible capability. For B or C, name the smallest general primitive that would serve this Block and a meaningful class of future Blocks (shaped like `files.watch()` or `media.transform()`, never `supportThisSpecificBlock()`). Return `{"unsupported":"exact reason","gapClass":"B|C|D|E|F","primitive":"..."}` instead of a package that pretends to work.'),
@@ -124,7 +130,7 @@ export const BUILDER_CONTRACT=Object.freeze({
  gapClasses:GAP_CLASSES,
 });
 
-const SECTION_TITLES=Object.freeze({'source-of-truth':'Source of truth','reuse-first':'Reuse first','block-scope':'One job per Step','capability-contract':'Define the capability first','compose':'Blocks compose','platform-primitives':'Use platform primitives','no-workarounds':'No hidden workarounds','naming':'Name it briefly','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({'grounded-text':'Only supplied facts','source-of-truth':'Source of truth','reuse-first':'Reuse first','block-scope':'One job per Step','capability-contract':'Define the capability first','compose':'Blocks compose','platform-primitives':'Use platform primitives','no-workarounds':'No hidden workarounds','naming':'Name it briefly','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/collaboration-admission.js

@@ -3,12 +3,14 @@ import {parse} from 'acorn';
 
 const sharedKey=/^[a-zA-Z][a-zA-Z0-9_-]{0,99}$/;
 function annotatedControls(html=''){
- const bindings=[],controls=[],problems=[],keys=new Set(),ids=new Set(),source=String(html).replace(/<!--[\s\S]*?-->/g,''),tags=/<(input|textarea|select)\b([^>]*)>/gi;
+ const bindings=[],controls=[],problems=[],keys=new Set(),ids=new Set(),source=String(html).replace(/<!--[\s\S]*?-->/g,''),tags=/<(input|textarea|select|fieldset)\b([^>]*)>/gi;
  let tag;
  while((tag=tags.exec(source))){
   const attributes=new Map(),duplicates=new Set(),matcher=/([^\s"'<>\/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;let attribute;
   while((attribute=matcher.exec(tag[2]))){const name=attribute[1].toLowerCase(),value=attribute[2]??attribute[3]??attribute[4]??null;if(attributes.has(name))duplicates.add(name);else attributes.set(name,value);}
-  const element=tag[1].toLowerCase(),type=(attributes.get('type')||'text').toLowerCase(),supported=element!=='input'||['text','number','range','checkbox','color'].includes(type),shared=attributes.has('data-stillmade-share'),local=attributes.has('data-stillmade-local'),id=attributes.get('id');
+  const element=tag[1].toLowerCase(),type=(attributes.get('type')||'text').toLowerCase(),supported=element!=='input'||['text','search','email','tel','url','number','range','checkbox','color'].includes(type),shared=attributes.has('data-stillmade-share'),local=attributes.has('data-stillmade-local'),id=attributes.get('id');
+  // A fieldset is a control only when it shares its radio picks; otherwise it just groups controls.
+  if(element==='fieldset'&&!shared)continue;
   if(shared&&local){problems.push('A control cannot be both shared and device-local.');continue;}
   if(supported)controls.push({id,shared,local});
   if(!shared)continue;

package/packages/block-sdk/connection-adapters.js

@@ -50,6 +50,30 @@ export const ADAPTERS=Object.freeze([...SCALAR_ADAPTERS,...SCALAR_ADAPTERS.filte
  ...(adapter.resultSchema?{resultSchema:typeof adapter.resultSchema==='string'?`${adapter.resultSchema}[]`:Object.freeze([adapter.resultSchema])}:{}),
  element:Object.freeze({id:adapter.id,version:adapter.version}),
 }))]);
+// Narration a Step takes from an earlier Step (the `narrationScript` and
+// `narrationTiming` inputs of Shots 2.2.0 and Image Panels 2.4.0). Those inputs
+// mean narration_script and timed_transcript, so a script Block whose output
+// names another meaning (or none), or Transcribe's transcript_text, cannot
+// connect to them directly. These conversions keep the words unchanged and are valid only
+// where a connection pins them: StillMade's narration wiring when such a Step
+// is added or replaced, or the person's "Use <Step>'s script". Compatibility
+// searches and the resolver never choose them.
+export const NARRATION_ADAPTERS=Object.freeze([
+ Object.freeze({...descriptor('script-as-narration','script','script'),targetSemantic:'narration_script',pinnedOnly:true,resultSchema:Object.freeze({schemaVersion:'integer',text:'string'})}),
+ Object.freeze({...descriptor('text-as-narration','text','script'),targetSemantic:'narration_script',pinnedOnly:true,resultSchema:Object.freeze({schemaVersion:'integer',text:'string'})}),
+ // Timed words (for example Transcribe's transcript of the Voiceover) as the narration timing.
+ Object.freeze({...descriptor('transcript-as-narration-timing','transcript','transcript'),targetSemantic:'timed_transcript',pinnedOnly:true}),
+]);
+// The narration input asks for no role or structure; the output has the
+// conversion's type and asks for no other role. Which output is the script is
+// decided where the pin is made (narration-inputs.js), never here.
+function pinnedNarration(out,into,adapter){
+ if(!plain(adapter)||!out||!into)return null;
+ const definition=NARRATION_ADAPTERS.find(item=>item.id===adapter.id&&item.version===adapter.version);
+ if(!definition||definition.output!==out.type||definition.input!==into.type||into.semantic!==definition.targetSemantic||into.role||into.schema!==undefined)return null;
+ if(out.role&&out.role!==definition.targetSemantic)return null;
+ return {compatible:true,adapter:pin(definition),requiresValue:true,contextFields:[]};
+}
 const elementPort=contract=>{
  const result={...contract,type:contract.type.slice(0,-2),cardinality:'one'};
  if(Array.isArray(contract.schema) && contract.schema.length===1)result.schema=contract.schema[0];
@@ -75,7 +99,7 @@ export function connectionCompatibility(output,input,{semantics}={}) {
 
 /** Validate the declared connection and its optional saved adapter pin. */
 export function validateConnectionAdapter(output,input,{permissions=[],adapter,semantics}={}) {
- const match=connectionCompatibility(output,input,{semantics});
+ const match=pinnedNarration(port(output),port(input),adapter)||connectionCompatibility(output,input,{semantics});
  assert(match.compatible,'ADAPTER_TYPE',match.reason || 'These inputs and outputs cannot connect');
  if(adapter!==undefined){
   const valid=match.adapter===null?adapter===null:plain(adapter) && Object.keys(adapter).every(key=>['id','version'].includes(key)) && adapter.id===match.adapter.id && adapter.version===match.adapter.version;
@@ -127,7 +151,7 @@ export function adaptConnectionValue(output,input,value,{context={},permissions=
  let result=value;
  if(match.adapter){
   const id=match.adapter.id;
-  const definition=ADAPTERS.find(item=>item.id===id),sequence=definition.steps;
+  const definition=ADAPTERS.find(item=>item.id===id)||NARRATION_ADAPTERS.find(item=>item.id===id),sequence=definition.steps;
   if(definition.element){
    assert(value.length<=100,'ADAPTER_LIMIT','Convert at most 100 items at a time.');
    const source=elementPort(out),target=elementPort(into);
@@ -149,6 +173,15 @@ export function adaptConnectionValue(output,input,value,{context={},permissions=
   }
   else if(id==='csv-to-table')result=csvToTable(value);
   else if(id==='text-to-script')result={schemaVersion:1,text:value};
+  else if(id==='script-as-narration'){
+   assert(typeof value.text==='string','ADAPTER_TYPE','This script needs readable words before it can be used as narration.');
+   result={schemaVersion:1,text:value.text};
+  }
+  else if(id==='text-as-narration')result={schemaVersion:1,text:value};
+  else if(id==='transcript-as-narration-timing'){
+   assert(Array.isArray(value.words),'ADAPTER_TYPE','This transcript has no word timings to use as narration timing.');
+   result=value;
+  }
   else if(id==='script-to-text'){
    assert(typeof value.text==='string','ADAPTER_TYPE','This script needs readable words before it can become text.');
    result=value.text;

package/packages/block-sdk/contracts.js

@@ -10,7 +10,10 @@ export const BlockError=core.BlockError,assert=core.assert,plain=core.plain;
 export const PORT_FIELDS = Object.freeze(['type', 'required', 'default', 'min', 'max', 'description', 'role', 'primary', 'context', 'imageMode', ...SEMANTIC_PORT_FIELDS]);
 import {standardSemanticIsA} from './semantic-relationships.js';
 import {semanticDeclarationErrors} from './semantic-declarations.js';
-import {firstPartySdkPackage} from './first-party-packages.js';
+// Reserved "sm." identities are checked against the generated id@version list,
+// not the packages: importing them put 185 Block packages under every module
+// that imports a contract helper (October 2026, every Vercel cold start).
+import {isFirstPartySdkIdentity} from './first-party-identities.js';
 import {isTimelineRange,isApprovalDecision} from './interaction-values.js';
 import {validateStateMigrations} from './state-migrations.js';
 import {sdkCompatibility} from './sdk-compatibility.js';
@@ -131,7 +134,7 @@ export function validateManifest(manifest, { builtIn = false } = {}) {
   check(manifest.schemaVersion === 1, 'schemaVersion', 'Expected schemaVersion 1');
   check(ID.test(manifest.id || ''), 'id', 'Expected namespace.name');
   // The reserved namespace admits only registered independently executable SDK releases.
-  check(manifest.id !== ROOT_CHAT_ID && (builtIn || !manifest.id?.startsWith('sm.') || !!firstPartySdkPackage(manifest)), 'id', 'Reserved platform block identity');
+  check(manifest.id !== ROOT_CHAT_ID && (builtIn || !manifest.id?.startsWith('sm.') || isFirstPartySdkIdentity(manifest)), 'id', 'Reserved platform block identity');
   check(VERSION.test(manifest.version || ''), 'version', 'Expected a semantic version such as 1.0.0');
   const compatibility=sdkCompatibility(manifest.sdkVersion);
   check(compatibility.status==='supported','sdkVersion',compatibility.message);

package/packages/block-sdk/examples.js

@@ -22,8 +22,8 @@ export const customInterface = {
  ...textCleanup,
  manifest:{...textCleanup.manifest,id:'example.clean-text-interface',version:'1.1.0',name:'Clean text studio',description:'Edit text, run the cleanup, and compare the result in a responsive self-contained workspace.'},
  view:{
-  html:'<main class="clean-studio"><header><h1>Clean text</h1><p>Shape a draft and keep the result visible while settings move for the available space.</p></header><div class="clean-layout"><section class="clean-settings" aria-labelledby="settings-title"><h2 id="settings-title">Draft</h2><label for="source">Your text</label><textarea id="source" data-stillmade-input="text" data-stillmade-share="text"></textarea><div class="clean-actions"><button id="run" data-stillmade-action="run">Clean text</button></div></section><section class="clean-result" aria-labelledby="result-title"><h2 id="result-title">Result</h2><output id="result" aria-live="polite" data-stillmade-state="empty">Your result appears here.</output></section></div></main>',
-  css:'.clean-studio{container:clean-studio/inline-size;min-width:0}.clean-studio>header p{max-width:60ch;color:var(--fg-muted)}.clean-layout{display:grid;grid-template-columns:minmax(0,2fr) minmax(240px,1fr);gap:16px;align-items:start}.clean-settings,.clean-result{min-width:0;padding:16px;border:1px solid var(--border-tok);border-radius:var(--r-3)}.clean-settings label{display:block;margin-bottom:8px}.clean-actions{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px}.clean-actions button{min-width:44px;min-height:44px}.clean-result output{display:block;min-height:120px;white-space:pre-wrap;overflow-wrap:anywhere;padding:16px;border:1px solid var(--border-tok);border-radius:var(--r-3)}@container clean-studio (max-width:600px){.clean-layout{grid-template-columns:minmax(0,1fr)}.clean-settings,.clean-result{padding:12px}}',
-  javascript:'const source=document.getElementById("source"), button=document.getElementById("run"), result=document.getElementById("result"); StillMade.onInput(input=>{source.value=input.text||"";document.querySelector("main").dataset.stillmadeState=source.value?"populated":"empty"}); button.addEventListener("click",async()=>{button.disabled=true;result.dataset.stillmadeState="loading";result.textContent="Cleaning…";try{const output=await StillMade.run({text:source.value});result.dataset.stillmadeState="success";result.textContent=output.text||"The result is empty."}catch(error){result.dataset.stillmadeState="error";result.textContent=error.message}finally{button.disabled=false}});',
+  html:'<main class="sm-block" data-layout="split"><output class="sm-stage" id="result" aria-live="polite" data-stillmade-state="empty">Your result shows here</output><div class="sm-field"><label for="source">Text</label><textarea id="source" data-stillmade-input="text" data-stillmade-share="text"></textarea></div><div class="sm-actions"><button class="sm-primary" id="run" data-stillmade-action="run">Clean text</button></div></main>',
+  css:'#result{place-items:start;min-height:160px;white-space:pre-wrap;overflow-wrap:anywhere;color:var(--fg)}#result[data-stillmade-state="empty"]{place-items:center;color:var(--fg-muted)}',
+  javascript:'const source=document.getElementById("source"), button=document.getElementById("run"), result=document.getElementById("result"); StillMade.onInput(input=>{source.value=input.text||"";document.querySelector("main").dataset.stillmadeState=source.value?"populated":"empty"}); button.addEventListener("click",async()=>{button.disabled=true;result.dataset.stillmadeState="loading";result.textContent="Cleaning…";try{const output=await StillMade.run({text:source.value});result.dataset.stillmadeState="success";result.textContent=output.text||"Empty result"}catch(error){result.dataset.stillmadeState="error";result.textContent=error.message}finally{button.disabled=false}});',
  },
 };