stillmade-sdk 0.1.36 → 0.1.38

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

@@ -0,0 +1,42 @@
+// Example files a Block's tests and examples can name by address, /api/media/example/<name>: StillMade serves them
+// (server/routes/media.js), the phone and browser check serves them inside its disposable preview, and the SDK's local
+// tests read them when a test gives no mock for them (mock-host.js). November 2026: the guides used these addresses in
+// fixtures but nothing served them, so an image Block's example never opened in the preview or the device check, and a
+// Block built outside StillMade could not ship a real example photo. The bytes are in example-media-data.js
+// (scripts/generate-example-media.mjs), loaded only when one is read.
+export const EXAMPLE_MEDIA_PATH='/api/media/example/';
+export const EXAMPLE_MEDIA=Object.freeze({
+ 'photo-1.jpg':{kind:'image',mimeType:'image/jpeg',width:1600,height:1200},
+ 'photo-2.jpg':{kind:'image',mimeType:'image/jpeg',width:1200,height:1600},
+ 'photo-3.jpg':{kind:'image',mimeType:'image/jpeg',width:1600,height:1200},
+ 'photo-4.jpg':{kind:'image',mimeType:'image/jpeg',width:1600,height:1200},
+ 'sheet.png':{kind:'image',mimeType:'image/png',width:1300,height:1440},
+ 'room.png':{kind:'image',mimeType:'image/png',width:1200,height:900},
+ 'kitchen.wav':{kind:'audio',mimeType:'audio/wav',duration:2,sampleRate:24000,channels:1},
+ 'hall.wav':{kind:'audio',mimeType:'audio/wav',duration:2,sampleRate:24000,channels:1},
+ 'click-120.wav':{kind:'audio',mimeType:'audio/wav',duration:2,sampleRate:24000,channels:1},
+ 'audio.mp3':{kind:'audio',mimeType:'audio/mpeg',duration:2},
+ 'clip.mp4':{kind:'video',mimeType:'video/mp4',width:640,height:360,duration:2},
+ 'notes.txt':{kind:'file',mimeType:'text/plain'},
+ 'sales.csv':{kind:'file',mimeType:'text/csv'},
+});
+
+// The example's name for an address StillMade serves ("/api/media/example/photo-1.jpg", with or without an origin), else null.
+export function exampleMediaName(url){
+ if(typeof url!=='string')return null;
+ let path=url;
+ if(/^https?:\/\//i.test(url)){try{path=new URL(url).pathname;}catch{return null;}}
+ if(!path.startsWith(EXAMPLE_MEDIA_PATH))return null;
+ const name=decodeURIComponent(path.slice(EXAMPLE_MEDIA_PATH.length));
+ return Object.hasOwn(EXAMPLE_MEDIA,name)?name:null;
+}
+
+let data=null;
+// The example's bytes.
+export async function readExampleMedia(name){
+ if(!Object.hasOwn(EXAMPLE_MEDIA,name))throw Object.assign(new Error(`There is no example file named ${name}.`),{code:'EXAMPLE_MEDIA_UNKNOWN'});
+ data||=import('./example-media-data.js').then(module=>module.EXAMPLE_MEDIA_DATA);
+ const text=(await data)[name];
+ if(typeof Buffer!=='undefined')return new Uint8Array(Buffer.from(text,'base64'));
+ const binary=atob(text),bytes=new Uint8Array(binary.length);for(let index=0;index<binary.length;index++)bytes[index]=binary.charCodeAt(index);return bytes;
+}

package/packages/block-sdk/first-party-identities.js

@@ -17,6 +17,7 @@ export const FIRST_PARTY_SDK_IDENTITIES=Object.freeze(new Set([
  "sm.animated-scene@2.3.6",
  "sm.animated-scene@2.3.7",
  "sm.animated-scene@2.3.8",
+ "sm.animated-scene@2.3.9",
  "sm.blueprint-assistant@1.0.0",
  "sm.blueprint@2.0.0",
  "sm.blueprint@2.1.0",
@@ -34,6 +35,7 @@ export const FIRST_PARTY_SDK_IDENTITIES=Object.freeze(new Set([
  "sm.board-editor@2.2.0",
  "sm.board-editor@2.2.1",
  "sm.board-editor@2.2.10",
+ "sm.board-editor@2.2.11",
  "sm.board-editor@2.2.2",
  "sm.board-editor@2.2.3",
  "sm.board-editor@2.2.4",
@@ -57,6 +59,7 @@ export const FIRST_PARTY_SDK_IDENTITIES=Object.freeze(new Set([
  "sm.continue-if@1.0.0",
  "sm.describe-media@2.0.0",
  "sm.describe-media@2.0.1",
+ "sm.describe-media@2.1.0",
  "sm.edit-assistant@2.0.0",
  "sm.edit-assistant@2.0.1",
  "sm.edit-assistant@2.0.2",
@@ -112,7 +115,9 @@ export const FIRST_PARTY_SDK_IDENTITIES=Object.freeze(new Set([
  "sm.panel-strip@2.3.7",
  "sm.panel-strip@2.4.0",
  "sm.panel-strip@2.4.1",
+ "sm.panel-strip@2.4.2",
  "sm.photo-notes@1.0.0",
+ "sm.photo-notes@1.1.0",
  "sm.pick-photos@1.0.0",
  "sm.pipeline@2.0.0",
  "sm.pipeline@2.1.0",
@@ -122,6 +127,7 @@ export const FIRST_PARTY_SDK_IDENTITIES=Object.freeze(new Set([
  "sm.pipeline@2.2.3",
  "sm.pipeline@2.2.4",
  "sm.pipeline@2.2.5",
+ "sm.pipeline@2.2.6",
  "sm.quality-audit@1.0.0",
  "sm.quality-audit@1.0.1",
  "sm.quality-audit@1.0.2",
@@ -177,6 +183,7 @@ export const FIRST_PARTY_SDK_IDENTITIES=Object.freeze(new Set([
  "sm.write-summary@1.0.0",
  "sm.youtube@2.0.0",
  "stillmade.narration@1.0.0",
+ "stillmade.narration@1.0.1",
  "stillmade.occasion-story@1.0.0",
  "stillmade.occasion-story@1.0.1",
  "stillmade.occasion-story@1.0.2",
@@ -188,6 +195,7 @@ export const FIRST_PARTY_SDK_IDENTITIES=Object.freeze(new Set([
  "stillmade.release-visuals@1.0.1",
  "stillmade.release-visuals@1.0.2",
  "stillmade.screen-recorder@1.0.0",
+ "stillmade.screen-recorder@1.0.1",
  "stillmade.short-form-finish@1.0.0",
  "stillmade.short-form-finish@1.0.1",
  "stillmade.short-form-finish@1.0.2",

package/packages/block-sdk/first-party-packages.js

@@ -2,7 +2,9 @@ import shortFormFinishV100 from '../../blocks/short-form-finish/versions/1.0.0/p
 import shortFormFinishV101 from '../../blocks/short-form-finish/versions/1.0.1/package.js';
 import shortFormFinishV102 from '../../blocks/short-form-finish/versions/1.0.2/package.js';
 import shortFormFinish from '../../blocks/short-form-finish/package.js';
+import screenRecorderV100 from '../../blocks/screen-recorder/versions/1.0.0/package.js';
 import screenRecorder from '../../blocks/screen-recorder/package.js';
+import narrationV100 from '../../blocks/narration/versions/1.0.0/package.js';
 import narration from '../../blocks/narration/package.js';
 import occasionStoryV100 from '../../blocks/occasion-story/versions/1.0.0/package.js';
 import releaseVisualsV100 from '../../blocks/release-visuals/versions/1.0.0/package.js';
@@ -88,6 +90,9 @@ import imageEditor from '../../blocks/native/sm.image-editor/versions/2.0.0/pack
 import imageEditorV201 from '../../blocks/native/sm.image-editor/versions/2.0.1/package.js';
 import describeMedia from '../../blocks/native/sm.describe-media/versions/2.0.0/package.js';
 import describeMediaV201 from '../../blocks/native/sm.describe-media/versions/2.0.1/package.js';
+// October 29, 2026: StillMade credits stopped paying for image.describe on September 13, so Describe media 2.1.0
+// and Photo notes 1.1.0 run on media.analyze (credits, per image); the image.describe releases stay for exact pins.
+import describeMediaV210 from '../../blocks/native/sm.describe-media/versions/2.1.0/package.js';
 import videoAssets from '../../blocks/native/sm.video-assets/versions/2.0.0/package.js';
 import videoAssetsV210 from '../../blocks/native/sm.video-assets/versions/2.1.0/package.js';
 import videoAssetsV211 from '../../blocks/native/sm.video-assets/versions/2.1.1/package.js';
@@ -135,6 +140,7 @@ import pipelineV220 from '../../blocks/native/sm.pipeline/versions/2.2.0/package
 import pipelineV221 from '../../blocks/native/sm.pipeline/versions/2.2.1/package.js';
 import pipelineV223 from '../../blocks/native/sm.pipeline/versions/2.2.3/package.js';
 import pipelineV225 from '../../blocks/native/sm.pipeline/versions/2.2.5/package.js';
+import pipelineV226 from '../../blocks/native/sm.pipeline/versions/2.2.6/package.js';
 import pipelineV224 from '../../blocks/native/sm.pipeline/versions/2.2.4/package.js';
 import pipelineV222 from '../../blocks/native/sm.pipeline/versions/2.2.2/package.js';
 import shotPlanAssistant from '../../blocks/native/sm.shot-plan-assistant/versions/1.0.0/package.js';
@@ -163,6 +169,7 @@ import panelStripV236 from '../../blocks/native/sm.panel-strip/versions/2.3.6/pa
 import panelStripV237 from '../../blocks/native/sm.panel-strip/versions/2.3.7/package.js';
 import panelStripV240 from '../../blocks/native/sm.panel-strip/versions/2.4.0/package.js';
 import panelStripV241 from '../../blocks/native/sm.panel-strip/versions/2.4.1/package.js';
+import panelStripV242 from '../../blocks/native/sm.panel-strip/versions/2.4.2/package.js';
 import boardEditorV210 from '../../blocks/native/sm.board-editor/versions/2.1.0/package.js';
 import boardEditorV220 from '../../blocks/native/sm.board-editor/versions/2.2.0/package.js';
 import boardEditorV221 from '../../blocks/native/sm.board-editor/versions/2.2.1/package.js';
@@ -175,6 +182,7 @@ import boardEditorV227 from '../../blocks/native/sm.board-editor/versions/2.2.7/
 import boardEditorV228 from '../../blocks/native/sm.board-editor/versions/2.2.8/package.js';
 import boardEditorV229 from '../../blocks/native/sm.board-editor/versions/2.2.9/package.js';
 import boardEditorV2210 from '../../blocks/native/sm.board-editor/versions/2.2.10/package.js';
+import boardEditorV2211 from '../../blocks/native/sm.board-editor/versions/2.2.11/package.js';
 import animatedSceneV220 from '../../blocks/native/sm.animated-scene/versions/2.2.0/package.js';
 import animatedSceneV230 from '../../blocks/native/sm.animated-scene/versions/2.3.0/package.js';
 import animatedSceneV231 from '../../blocks/native/sm.animated-scene/versions/2.3.1/package.js';
@@ -185,12 +193,14 @@ import animatedSceneV235 from '../../blocks/native/sm.animated-scene/versions/2.
 import animatedSceneV236 from '../../blocks/native/sm.animated-scene/versions/2.3.6/package.js';
 import animatedSceneV237 from '../../blocks/native/sm.animated-scene/versions/2.3.7/package.js';
 import animatedSceneV238 from '../../blocks/native/sm.animated-scene/versions/2.3.8/package.js';
+import animatedSceneV239 from '../../blocks/native/sm.animated-scene/versions/2.3.9/package.js';
 import blueprintAssistant from '../../blocks/native/sm.blueprint-assistant/versions/1.0.0/package.js';
 import photoNotes from '../../blocks/native/sm.photo-notes/versions/1.0.0/package.js';
+import photoNotesV110 from '../../blocks/native/sm.photo-notes/versions/1.1.0/package.js';
 import pickPhotos from '../../blocks/native/sm.pick-photos/versions/1.0.0/package.js';
 
 // Exact, independently executable first-party releases. Host workspaces do not
 // belong here. Changing implementation requires a new immutable version.
 const freeze=value=>{if(value&&typeof value==='object'&&!Object.isFrozen(value)){Object.values(value).forEach(freeze);Object.freeze(value);}return value;};
-export const FIRST_PARTY_SDK_PACKAGES = Object.freeze([freeze(productAdVariants),freeze(pickPhotos),freeze(photoNotes),freeze(youtubePublication),freeze(stockSearch),freeze(exportVideoV210),freeze(exportVideo),freeze(exportAudio),freeze(motionGraphics),freeze(audioScore),freeze(shortFormFinish),freeze(screenRecorder),freeze(narration),freeze(shortFormFinishV102),freeze(shortFormFinishV101),freeze(shortFormFinishV100),freeze(occasionStory),freeze(occasionStoryV101),freeze(occasionStoryV100),freeze(releaseVisuals),freeze(releaseVisualsV101),freeze(releaseVisualsV100),freeze(photoReelComposer),freeze(photoReelComposerV101),freeze(photoReelComposerV100),freeze(importMediaV202),freeze(importMediaV201),freeze(editorV2212),freeze(editorV2211),freeze(editorV2210),freeze(editorV229),freeze(editorV228),freeze(panelStripV241),freeze(panelStripV240),freeze(panelStripV237),freeze(panelStripV236),freeze(boardEditorV2210),freeze(boardEditorV229),freeze(animatedSceneV238),freeze(animatedSceneV237),freeze(pipelineV225),freeze(pipelineV224),freeze(blueprintV219),freeze(blueprintV218),freeze(videoAssetsV214),freeze(videoAssetsV213),freeze(chatV203),freeze(chatV202),freeze(chatV201),freeze(shotPlanV221),freeze(shotPlanV220),freeze(shotPlanV213),freeze(shotPlanV212),freeze(voiceoverV216),freeze(voiceoverV215),freeze(voiceoverV214),freeze(voiceoverV213),freeze(scriptV215),freeze(scriptV214),freeze(scriptV213),freeze(roughCutV202),freeze(roughCutV201),freeze(finalEditV202),freeze(finalEditV201),freeze(editAssistantV202),freeze(editAssistantV201),freeze(gradeV202),freeze(gradeV201),freeze(transitionV202),freeze(transitionV201),freeze(qualityAuditV102),freeze(qualityAuditV101),freeze(compareV202),freeze(compareV201),freeze(compare),freeze(grade),freeze(transition),freeze(exportTimeline),freeze(captions),freeze(importMedia),freeze(generateImageV210),freeze(generateImage),freeze(thumbnailV201),freeze(thumbnail),freeze(writeSummary),freeze(automationV110),freeze(automationWhen),freeze(automationNewItems),freeze(automationAiDecide),freeze(automationContinueIf),freeze(connectApp),freeze(automationContactFields),freeze(automationAiWrite),freeze(automationMetaCreative),freeze(voiceover),freeze(voiceoverV210),freeze(voiceoverV211),freeze(voiceoverV212),freeze(script),freeze(scriptV210),freeze(scriptV211),freeze(scriptV212),freeze(generateVideoV201),freeze(generateVideo),freeze(chat),freeze(characterV201),freeze(character),freeze(locationV201),freeze(location),freeze(styleV201),freeze(style),freeze(researchV202),freeze(researchV201),freeze(research),freeze(imageEditorV201),freeze(imageEditor),freeze(describeMediaV201),freeze(describeMedia),freeze(videoAssets),freeze(videoAssetsV210),freeze(videoAssetsV211),freeze(videoAssetsV212),freeze(roughCut),freeze(finalEdit),freeze(editAssistant),freeze(transcribeV201),freeze(transcribe),freeze(blueprint),freeze(blueprintV210),freeze(blueprintV211),freeze(blueprintV212),freeze(blueprintV213),freeze(blueprintV214),freeze(blueprintV215),freeze(blueprintV216),freeze(blueprintV217),freeze(shotPlan),freeze(shotPlanV210),freeze(shotPlanV211),freeze(boardEditor),freeze(boardEditorV210),freeze(boardEditorV220),freeze(boardEditorV221),freeze(boardEditorV222),freeze(boardEditorV223),freeze(boardEditorV224),freeze(boardEditorV225),freeze(boardEditorV226),freeze(boardEditorV227),freeze(boardEditorV228),freeze(panelStripV200),freeze(panelStrip),freeze(panelStripV220),freeze(panelStripV230),freeze(panelStripV231),freeze(panelStripV232),freeze(panelStripV233),freeze(panelStripV234),freeze(panelStripV235),freeze(animatedSceneV200),freeze(animatedScene),freeze(animatedSceneV220),freeze(animatedSceneV230),freeze(animatedSceneV231),freeze(animatedSceneV232),freeze(animatedSceneV233),freeze(animatedSceneV234),freeze(animatedSceneV235),freeze(animatedSceneV236),freeze(editor),freeze(editorV210),freeze(editorV220),freeze(editorV221),freeze(editorV222),freeze(editorV223),freeze(editorV224),freeze(editorV225),freeze(editorV226),freeze(editorV227),freeze(pipelineV200),freeze(pipeline),freeze(pipelineV220),freeze(pipelineV221),freeze(pipelineV223),freeze(pipelineV222),freeze(shotPlanAssistant),freeze(animatedSceneAssistant),freeze(blueprintAssistant),freeze(whiteboardAssistant),freeze(qualityAudit)]);
+export const FIRST_PARTY_SDK_PACKAGES = Object.freeze([freeze(productAdVariants),freeze(pickPhotos),freeze(photoNotesV110),freeze(photoNotes),freeze(youtubePublication),freeze(stockSearch),freeze(exportVideoV210),freeze(exportVideo),freeze(exportAudio),freeze(motionGraphics),freeze(audioScore),freeze(shortFormFinish),freeze(screenRecorder),freeze(screenRecorderV100),freeze(narration),freeze(narrationV100),freeze(shortFormFinishV102),freeze(shortFormFinishV101),freeze(shortFormFinishV100),freeze(occasionStory),freeze(occasionStoryV101),freeze(occasionStoryV100),freeze(releaseVisuals),freeze(releaseVisualsV101),freeze(releaseVisualsV100),freeze(photoReelComposer),freeze(photoReelComposerV101),freeze(photoReelComposerV100),freeze(importMediaV202),freeze(importMediaV201),freeze(editorV2212),freeze(editorV2211),freeze(editorV2210),freeze(editorV229),freeze(editorV228),freeze(panelStripV242),freeze(panelStripV241),freeze(panelStripV240),freeze(panelStripV237),freeze(panelStripV236),freeze(boardEditorV2211),freeze(boardEditorV2210),freeze(boardEditorV229),freeze(animatedSceneV239),freeze(animatedSceneV238),freeze(animatedSceneV237),freeze(pipelineV226),freeze(pipelineV225),freeze(pipelineV224),freeze(blueprintV219),freeze(blueprintV218),freeze(videoAssetsV214),freeze(videoAssetsV213),freeze(chatV203),freeze(chatV202),freeze(chatV201),freeze(shotPlanV221),freeze(shotPlanV220),freeze(shotPlanV213),freeze(shotPlanV212),freeze(voiceoverV216),freeze(voiceoverV215),freeze(voiceoverV214),freeze(voiceoverV213),freeze(scriptV215),freeze(scriptV214),freeze(scriptV213),freeze(roughCutV202),freeze(roughCutV201),freeze(finalEditV202),freeze(finalEditV201),freeze(editAssistantV202),freeze(editAssistantV201),freeze(gradeV202),freeze(gradeV201),freeze(transitionV202),freeze(transitionV201),freeze(qualityAuditV102),freeze(qualityAuditV101),freeze(compareV202),freeze(compareV201),freeze(compare),freeze(grade),freeze(transition),freeze(exportTimeline),freeze(captions),freeze(importMedia),freeze(generateImageV210),freeze(generateImage),freeze(thumbnailV201),freeze(thumbnail),freeze(writeSummary),freeze(automationV110),freeze(automationWhen),freeze(automationNewItems),freeze(automationAiDecide),freeze(automationContinueIf),freeze(connectApp),freeze(automationContactFields),freeze(automationAiWrite),freeze(automationMetaCreative),freeze(voiceover),freeze(voiceoverV210),freeze(voiceoverV211),freeze(voiceoverV212),freeze(script),freeze(scriptV210),freeze(scriptV211),freeze(scriptV212),freeze(generateVideoV201),freeze(generateVideo),freeze(chat),freeze(characterV201),freeze(character),freeze(locationV201),freeze(location),freeze(styleV201),freeze(style),freeze(researchV202),freeze(researchV201),freeze(research),freeze(imageEditorV201),freeze(imageEditor),freeze(describeMediaV210),freeze(describeMediaV201),freeze(describeMedia),freeze(videoAssets),freeze(videoAssetsV210),freeze(videoAssetsV211),freeze(videoAssetsV212),freeze(roughCut),freeze(finalEdit),freeze(editAssistant),freeze(transcribeV201),freeze(transcribe),freeze(blueprint),freeze(blueprintV210),freeze(blueprintV211),freeze(blueprintV212),freeze(blueprintV213),freeze(blueprintV214),freeze(blueprintV215),freeze(blueprintV216),freeze(blueprintV217),freeze(shotPlan),freeze(shotPlanV210),freeze(shotPlanV211),freeze(boardEditor),freeze(boardEditorV210),freeze(boardEditorV220),freeze(boardEditorV221),freeze(boardEditorV222),freeze(boardEditorV223),freeze(boardEditorV224),freeze(boardEditorV225),freeze(boardEditorV226),freeze(boardEditorV227),freeze(boardEditorV228),freeze(panelStripV200),freeze(panelStrip),freeze(panelStripV220),freeze(panelStripV230),freeze(panelStripV231),freeze(panelStripV232),freeze(panelStripV233),freeze(panelStripV234),freeze(panelStripV235),freeze(animatedSceneV200),freeze(animatedScene),freeze(animatedSceneV220),freeze(animatedSceneV230),freeze(animatedSceneV231),freeze(animatedSceneV232),freeze(animatedSceneV233),freeze(animatedSceneV234),freeze(animatedSceneV235),freeze(animatedSceneV236),freeze(editor),freeze(editorV210),freeze(editorV220),freeze(editorV221),freeze(editorV222),freeze(editorV223),freeze(editorV224),freeze(editorV225),freeze(editorV226),freeze(editorV227),freeze(pipelineV200),freeze(pipeline),freeze(pipelineV220),freeze(pipelineV221),freeze(pipelineV223),freeze(pipelineV222),freeze(shotPlanAssistant),freeze(animatedSceneAssistant),freeze(blueprintAssistant),freeze(whiteboardAssistant),freeze(qualityAudit)]);
 export const firstPartySdkPackage = manifest => FIRST_PARTY_SDK_PACKAGES.find(pkg => pkg.manifest.id === manifest?.id && pkg.manifest.version === manifest?.version);

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

@@ -49,6 +49,8 @@ export function testPackage(pkg: BlockPackage, options?: { timeoutMs?: number; c
 export const SDK_VERSION: '0.1.0';
 export const ROOT_CHAT_ID: 'stillmade.starting-chat';
 export function stableStringify(value: unknown): string;
+/** Throws when any text or field name in a package holds the NUL character (\u0000), which StillMade cannot store; the message names where it is (tests.1.mocks.files.tiny-1.text). Import review, validate, test, pack and ready run it. */
+export function assertStorableText(value: unknown): void;
 export function validateManifest(value: unknown): { valid: boolean; errors: { path: string; message: string }[] };
 export function validateRecipe(recipe: BlockPackage['recipe']): true;
 export interface RecipeProgress {stepId:string;complete:number;total:number}
@@ -675,9 +677,11 @@ export type MediaTransformRequest =
   | {operation:'video.cut'; source:SavedMediaRef; keep:TimeRange[]; settings?:RenderSettings}
   | {operation:'video.concat'; sources:SavedMediaRef[]; settings?:RenderSettings}
   | {operation:'video.resize'; source:SavedMediaRef; settings:RenderSettings}
-  | {operation:'image.thumbnail'; source:SavedMediaRef; at?:number; width?:number};
+  | {operation:'image.thumbnail'; source:SavedMediaRef; at?:number; width?:number}
+  | {operation:'document.text'; source:SavedMediaRef}
+  | {operation:'image.compose'; width:number; height:number; background?:string; format?:'png'|'jpeg'; layers:{source:SavedMediaRef; x:number; y:number; width:number; height:number; fit?:'cover'|'contain'}[]; text?:{text:string; x:number; y:number; size?:number; color?:string; background?:string; align?:'left'|'center'|'right'; weight?:'normal'|'bold'; width?:number}[]};
 export type DecodedAudio = {sampleRate:number; duration:number; samples:Float32Array};
-export const MEDIA_TRANSFORM_LIMITS: Readonly<{ranges:500;sources:50;durationSeconds:21600;decodeSamples:201326592;sampleRates:readonly number[];thumbnailWidth:4096}>;
+export const MEDIA_TRANSFORM_LIMITS: Readonly<{ranges:500;sources:50;durationSeconds:21600;decodeSamples:201326592;sampleRates:readonly number[];thumbnailWidth:4096;composeSide:4096;composeLayers:64;composeText:64;documentPages:500;documentCharacters:4000000}>;
 export const MEDIA_TRANSFORM_OPERATIONS: readonly MediaTransformRequest['operation'][];
 export function mediaTransformRequest(value: MediaTransformRequest): Required<MediaTransformRequest>;
 export function mediaTransformSources(request: MediaTransformRequest): SavedMediaRef[];

package/packages/block-sdk/local-admission.js

@@ -19,8 +19,9 @@ function moduleFilesOf(pkg,files){
 // on the creator's own machine (`moduleExecution:true`), never a server path
 // admitting someone else's upload (imports, AI authoring, readiness from the API).
 // host: the stand-in host a module runs against (the CLI's, which answers from tests/mocks.json);
-// without one, the recorded stand-ins.
-export async function admitLocalPackage(pkg,{timeoutMs=15000,files,moduleExecution=false,host}={}){
+// without one, the recorded stand-ins. hostFor(mocks): the host for a fixture's own mocks (the CLI's
+// reads the files they name from the Block folder); without one, a stand-in host answering from them.
+export async function admitLocalPackage(pkg,{timeoutMs=15000,files,moduleExecution=false,host,hostFor}={}){
  const moduleFiles=moduleExecution===true&&pkg?.manifest?.runtime==='module'?moduleFilesOf(pkg,files):null;
  assert(['recipe','javascript','capability','comfyui'].includes(pkg?.manifest?.runtime)||moduleFiles,'RUNTIME_RESTRICTED',pkg?.manifest?.runtime==='module'?'Local admission runs a module Block only on your own machine (the SDK CLI); StillMade runs it in the browser sandbox after review.':'Local admission supports recipes, isolated JavaScript, declarative capabilities and ComfyUI workflows. Hosted execution still requires account review.');
  assert(Number.isFinite(timeoutMs)&&timeoutMs>0&&timeoutMs<=15000,'TIMEOUT','Local admission needs a positive budget of at most 15 seconds');
@@ -38,12 +39,12 @@ export async function admitLocalPackage(pkg,{timeoutMs=15000,files,moduleExecuti
   // hosted calls, media and files; the digests are checked before anything runs.
   // Loaded only for a module package: the Node executor needs worker threads, which the
  // App's bundle (this file is part of it) must never pull in statically.
- // A fixture that records its own mocks is answered from them.
- const executors=moduleFiles?await (async()=>{const [{createNodeModuleExecutor},{createMockHost}]=await Promise.all([import('./module-node.js'),import('./mock-host.js')]);const module=createNodeModuleExecutor({files:moduleFiles,host:host||createMockHost({manifest:pkg.manifest}).host});return {module,moduleFor:fixture=>fixture?.mocks?createNodeModuleExecutor({files:moduleFiles,host:createMockHost({mocks:fixture.mocks,manifest:pkg.manifest}).host}):module};})():null;
+ // A fixture that records its own mocks is answered from them, and so is the sample taken from it.
+ const executors=moduleFiles?await (async()=>{const [{createNodeModuleExecutor},{createMockHost}]=await Promise.all([import('./module-node.js'),import('./mock-host.js')]);const module=createNodeModuleExecutor({files:moduleFiles,host:host||createMockHost({manifest:pkg.manifest}).host});return {module,moduleFor:fixture=>fixture?.mocks?createNodeModuleExecutor({files:moduleFiles,host:hostFor?hostFor(fixture.mocks):createMockHost({mocks:fixture.mocks,manifest:pkg.manifest}).host}):module};})():null;
  const module=executors?.module;
   const report=await admitPackage(pkg,{
    test:content=>testPackage(content,{timeoutMs:remaining(),...(executors||{})}),
-   run:(content,input,options)=>{remaining();return runPackageAsync(content,input,{...options,signal:controller.signal,...(module?{module}:{})});},
+   run:(content,input,options,fixture)=>{remaining();return runPackageAsync(content,input,{...options,signal:controller.signal,...(module?{module:executors.moduleFor(fixture)}:{})});},
   });
   remaining();
   return module?{...report,execution:'local-stand-ins',liveVerified:false,reviewRequired:true}:report;

package/packages/block-sdk/media-transform.js

@@ -8,8 +8,8 @@ import {FINAL_RENDER_LIMITS} from './portable-media-contracts.js';
 
 // decodeSamples bounds decoded PCM (all channels): 192 M samples is 768 MB of
 // floats, about 100 minutes of 16 kHz stereo or 33 minutes of 48 kHz stereo.
-export const MEDIA_TRANSFORM_LIMITS=Object.freeze({ranges:500,sources:50,durationSeconds:21600,decodeSamples:201326592,sampleRates:[8000,16000,22050,24000,32000,44100,48000],thumbnailWidth:4096});
-export const MEDIA_TRANSFORM_OPERATIONS=Object.freeze(['audio.decode','audio.extract','audio.normalize','video.cut','video.concat','video.resize','image.thumbnail','timeline.render']);
+export const MEDIA_TRANSFORM_LIMITS=Object.freeze({ranges:500,sources:50,durationSeconds:21600,decodeSamples:201326592,sampleRates:[8000,16000,22050,24000,32000,44100,48000],thumbnailWidth:4096,composeSide:4096,composeLayers:64,composeText:64,documentPages:500,documentCharacters:4000000});
+export const MEDIA_TRANSFORM_OPERATIONS=Object.freeze(['audio.decode','audio.extract','audio.normalize','video.cut','video.concat','video.resize','image.thumbnail','image.compose','document.text','timeline.render']);
 // timeline.render (October 22, 2026, owner: exporting, captions, transitions and color are things a Block
 // does, not Blocks): the Editor's own looks, transitions and caption animations, by name.
 export const TIMELINE_LOOKS=Object.freeze(['None','Cold','Warm','Desaturated','High Contrast','Filmic','Teal and Orange']);
@@ -57,6 +57,13 @@ export function mediaTransformRequest(value){
    return {operation:value.operation,source:value.source,settings:{fps:30,resolution:1080,quality:'high',...value.settings}};
   }
   case 'timeline.render':return timelineRender(value);
+  case 'image.compose':return imageCompose(value);
+  // document.text (October 28, 2026): the words of a PDF or text file the person gives, page by page, read on the device
+  // (a teacher's lesson slides PDF had no way into a Block: no hosted operation reads PDFs).
+  case 'document.text':{
+   if(!exact(value,['operation','source'])||!ref(value.source,['file','document']))fail('document.text takes a saved file');
+   return {operation:value.operation,source:value.source};
+  }
   case 'image.thumbnail':{
    if(!exact(value,['operation','source'],['at','width'])||!ref(value.source,['video']))fail('image.thumbnail takes a saved video, an optional time and width');
    const at=value.at??0,width=value.width??1280;
@@ -66,7 +73,7 @@ export function mediaTransformRequest(value){
  }
 }
 /** The saved references a request reads. */
-export const mediaTransformSources=request=>request.operation==='video.concat'?request.sources:request.operation==='timeline.render'?[...request.clips,...request.audio].map(item=>item.source):[request.source];
+export const mediaTransformSources=request=>request.operation==='video.concat'?request.sources:request.operation==='image.compose'?request.layers.map(layer=>layer.source):request.operation==='timeline.render'?[...request.clips,...request.audio].map(item=>item.source):[request.source];
 
 /** Silent stretches in mono PCM: [{start, end}] seconds below thresholdDb for at least minSilence. */
 export function silentRanges(samples,sampleRate,{thresholdDb=-40,minSilence=0.5,window=0.02}={}){
@@ -210,6 +217,13 @@ function timelineRender(value){
   if(clip.look!==undefined&&!TIMELINE_LOOKS.includes(clip.look))fail(`look is one of ${TIMELINE_LOOKS.join(', ')}`);
   return {source:clip.source,start:clip.start,duration:clip.duration,from:clip.from??0,...(clip.transition?{transition:{type:clip.transition.type,duration:clip.transition.duration??0.5}}:{}),...(clip.look&&clip.look!=='None'?{look:clip.look}:{}),...(clip.mute?{mute:true}:{})};
  });
+ // One track: each clip starts where the one before it ends, overlapping it only by a transition (October 28, 2026:
+ // a built clip joiner put every clip at start 0, so the last covered the first and the rest of the video was black; its
+ // tests mock the render, so only this check could tell it). Either clip's fade allows that overlap, at most 0.9 of
+ // each clip as the Editor clamps a transition; the host renders the overlap as a crossfade (mediaTransformHost.js)
+ // (October 29, 2026: a reel that faded out of each photo failed its test, and stacked clips with long fades passed).
+ const ordered=[...clips].sort((a,b)=>a.start-b.start),fade=clip=>clip.transition&&clip.transition.type!=='Cut'?clip.transition.duration:0;
+ for(let index=1;index<ordered.length;index++){const before=ordered[index-1],clip=ordered[index],end=before.start+before.duration;if(end-clip.start>Math.min(Math.max(fade(before),fade(clip)),0.9*before.duration,0.9*clip.duration)+0.05)fail(`Clips overlap: one starts at ${clip.start} s while the clip before it runs to ${end} s. start is the clip's place on the timeline, so each clip starts where the one before it ends (less the transition between them); from is where it begins in its own file`);}
  const sounds=audio.map(item=>{
   if(!exact(item,['source','start','duration'],['from','volume'])||!ref(item.source,['audio','video'])||!span(item)||item.from!==undefined&&!seconds(item.from)||item.volume!==undefined&&!(Number.isFinite(item.volume)&&item.volume>=0&&item.volume<=200))fail('An audio item is {source: a saved audio or video, start, duration, from?, volume? 0 to 200}');
   return {source:item.source,start:item.start,duration:item.duration,from:item.from??0,volume:item.volume??100};
@@ -224,3 +238,45 @@ function timelineRender(value){
  });
  return {operation:'timeline.render',kind,aspect,clips,audio:sounds,captions:lines,settings:{fps:30,resolution:1080,quality:'high',...(value.settings||{})}};
 }
+// image.compose (October 28, 2026): a Block joins saved images into one picture (side by side, a grid, a
+// contact sheet, a poster with a title). Layers and text are placed in pixels on the canvas, drawn in order.
+const color=value=>/^#[0-9a-fA-F]{6}$/.test(value);
+// A text colour or the box behind it: #rrggbb, #rrggbbaa (see-through) or rgb()/rgba(), kept as hex so every host draws
+// the same (October 29, 2026: a reel's title box was rgba(0,0,0,0.35) and the Block failed its own test).
+const textColor=value=>{
+ if(typeof value!=='string')return null;
+ if(/^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$/.test(value))return value;
+ const match=/^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(?:,\s*(0|1|0?\.\d+|1\.0+)\s*)?\)$/.exec(value);
+ if(!match||match.slice(1,4).some(channel=>Number(channel)>255))return null;
+ const hex=number=>number.toString(16).padStart(2,'0'),alpha=match[4]===undefined?255:Math.round(Number(match[4])*255);
+ return '#'+match.slice(1,4).map(channel=>hex(Number(channel))).join('')+(alpha===255?'':hex(alpha));
+};
+const place=item=>['x','y','width','height'].every(key=>Number.isFinite(item[key]))&&item.width>0&&item.height>0&&Math.abs(item.x)<=MEDIA_TRANSFORM_LIMITS.composeSide&&Math.abs(item.y)<=MEDIA_TRANSFORM_LIMITS.composeSide&&item.width<=2*MEDIA_TRANSFORM_LIMITS.composeSide&&item.height<=2*MEDIA_TRANSFORM_LIMITS.composeSide;
+function imageCompose(value){
+ const side=MEDIA_TRANSFORM_LIMITS.composeSide;
+ if(!exact(value,['operation','width','height','layers'],['background','format','text']))fail('image.compose takes width, height, layers and optional background, format and text');
+ if(![value.width,value.height].every(size=>Number.isInteger(size)&&size>=16&&size<=side))fail(`width and height are whole pixels from 16 to ${side}`);
+ const background=value.background??'#ffffff',format=value.format??'png',text=value.text??[];
+ if(!color(background))fail('background is a #rrggbb colour');
+ if(!['png','jpeg'].includes(format))fail('format is png or jpeg');
+ if(!Array.isArray(value.layers)||!value.layers.length||value.layers.length>MEDIA_TRANSFORM_LIMITS.composeLayers)fail(`Place 1 to ${MEDIA_TRANSFORM_LIMITS.composeLayers} images`);
+ if(!Array.isArray(text)||text.length>MEDIA_TRANSFORM_LIMITS.composeText)fail(`Add at most ${MEDIA_TRANSFORM_LIMITS.composeText} pieces of text`);
+ const layers=value.layers.map(layer=>{
+  if(!exact(layer,['source','x','y','width','height'],['fit'])||!ref(layer.source,['image'])||!place(layer))fail('A layer is {source: a saved image, x, y, width, height, fit?} in pixels on the canvas');
+  if(layer.fit!==undefined&&!['cover','contain'].includes(layer.fit))fail('fit is cover or contain');
+  return {source:layer.source,x:layer.x,y:layer.y,width:layer.width,height:layer.height,fit:layer.fit??'cover'};
+ });
+ const lines=text.map(line=>{
+  if(!exact(line,['text','x','y'],['size','color','background','align','weight','width'])||typeof line.text!=='string'||!line.text.trim()||line.text.length>200||![line.x,line.y].every(Number.isFinite))fail('A piece of text is {text up to 200 characters, x, y, size?, color?, background?, align?, weight?, width?}');
+  // width wraps the words onto lines no wider than it (October 29, 2026: a storyboard's long caption ran into the next frame).
+  if(line.width!==undefined&&!(Number.isFinite(line.width)&&line.width>=16&&line.width<=MEDIA_TRANSFORM_LIMITS.composeSide))fail(`width is 16 to ${MEDIA_TRANSFORM_LIMITS.composeSide} pixels: the longest a line of the text may run before it wraps`);
+  const size=line.size??48;
+  if(!(Number.isFinite(size)&&size>=8&&size<=400))fail('size is 8 to 400 pixels');
+  const ink=line.color===undefined?'#000000':textColor(line.color),box=line.background===undefined?undefined:textColor(line.background);
+  if(!ink||box===null)fail('color and background are #rrggbb, #rrggbbaa (see-through) or rgb()/rgba() colours');
+  if(line.align!==undefined&&!['left','center','right'].includes(line.align))fail('align is left, center or right');
+  if(line.weight!==undefined&&!['normal','bold'].includes(line.weight))fail('weight is normal or bold');
+  return {text:line.text,x:line.x,y:line.y,size,color:ink,align:line.align??'left',weight:line.weight??'bold',...(box?{background:box}:{}),...(line.width!==undefined?{width:line.width}:{})};
+ });
+ return {operation:'image.compose',width:value.width,height:value.height,background,format,layers,text:lines};
+}

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

@@ -5,11 +5,13 @@
 // returns, checked by the same validators the app uses, unless the Block's
 // tests/mocks.json records its own. Nothing here contacts a provider or
 // spends credits, and a pass with stand-ins is never a live verification.
+import {EXAMPLE_MEDIA_PATH,exampleMediaName,readExampleMedia} from './example-media.js';
 import {assert,plain} from './contracts.js';
 import {moduleHostedPackage} from './module-hosted.js';
 import {prepareCapabilityInvocation,validateCapabilityResult,capabilityOutputs,defaultCapabilityExpectations,AUDIO_CAPABILITY_LIMITS} from './capabilities.js';
 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';
 export {mockPng,mockWav,mockMp4} from './mock-media.js';
 
@@ -119,15 +121,32 @@ export function createMockHost({mocks:given={},readLocalFile,manifest}={}){
   const url=typeof ref?.url==='string'?ref.url:'';
   if(media.has(url))return media.get(url).bytes;
   const named=[ref?.assetId,url].find(key=>key&&recorded('files',key));
+  // {base64} carries a small binary file inside the package, so it travels with the pack and the import review (November
+  // 2026: a test photo given as {text} carried NUL characters, which no project could save).
+  if(named&&plain(mocks.files[named])&&typeof mocks.files[named].base64==='string'){
+   const encoded=mocks.files[named].base64;
+   assert(encoded.length<=349528&&/^[A-Za-z0-9+/]*={0,2}$/.test(encoded),'MODULE_FILE_READ',`The {base64} file for ${named} must be plain base64 of at most 256 KB.`);
+   note('files.read',named,'mocks');
+   if(typeof Buffer!=='undefined')return new Uint8Array(Buffer.from(encoded,'base64'));
+   const binary=atob(encoded),bytes=new Uint8Array(binary.length);for(let index=0;index<binary.length;index++)bytes[index]=binary.charCodeAt(index);return bytes;
+  }
+  if(named&&plain(mocks.files[named])){
+   assert(!mocks.files[named].text.includes('\u0000'),'MODULE_FILE_READ',`The {text} file for ${named} holds binary bytes (a NUL character), which StillMade cannot store: give the file as {"base64": "..."} instead.`);
+   note('files.read',named,'mocks');return new TextEncoder().encode(mocks.files[named].text);
+  }
   if(named){
    assert(typeof readLocalFile==='function','MODULE_HOST_UNAVAILABLE','Local files need a file reader.');
    note('files.read',mocks.files[named],'mocks');
    return new Uint8Array(await readLocalFile(mocks.files[named]));
   }
-  fail(`files.read has no local file for ${ref?.assetId||url||'this reference'}. Map its assetId to a file in the Block folder under files in ${MOCKS_FILE}.`,'MODULE_FILE_READ');
+  // An example StillMade serves (/api/media/example/photo-1.jpg) reads its real bytes, as in StillMade.
+  const example=exampleMediaName(url);
+  if(example){note('files.read',url,'example');return await readExampleMedia(example);}
+  fail(`files.read has no local file for ${ref?.assetId||url||'this reference'}. Map its assetId under files in ${MOCKS_FILE} to a file in the Block folder, or to {text} for a text file, or use one of StillMade's example files at ${EXAMPLE_MEDIA_PATH} (photo-1.jpg to photo-4.jpg, sheet.png, room.png, kitchen.wav, hall.wav, click-120.wav, audio.mp3, clip.mp4, notes.txt, sales.csv).`,'MODULE_FILE_READ');
  };
  const buffer=bytes=>bytes.buffer.slice(bytes.byteOffset,bytes.byteOffset+bytes.byteLength);
- const EXT={'image/png':'png','image/jpeg':'jpg','image/webp':'webp','image/gif':'gif','video/mp4':'mp4','video/webm':'webm','audio/mpeg':'mp3','audio/wav':'wav'};
+ // Media, then the general files a module Block may write (data-values.js), each saved under its own extension.
+ const EXT={'image/png':'png','image/jpeg':'jpg','image/webp':'webp','image/gif':'gif','video/mp4':'mp4','video/webm':'webm','audio/mpeg':'mp3','audio/wav':'wav',...Object.fromEntries(Object.entries(FILE_FORMATS).map(([extension,mime])=>[mime,extension]))};
  const saveFile=(data,options={})=>{
   const mediaType=String(options.mediaType||'application/octet-stream'),bytes=new Uint8Array(data.slice(0)),kind=['image','video','audio'].includes(mediaType.split('/')[0])?mediaType.split('/')[0]:'file';
   const {id,url}=keep(bytes,mediaType,EXT[mediaType]||'bin',`written-${kind}`);
@@ -153,6 +172,8 @@ export function createMockHost({mocks:given={},readLocalFile,manifest}={}){
     return {sampleRate:checked.sampleRate,duration:samples.length/checked.sampleRate,samples};
    }
    if(checked.operation==='image.thumbnail')return reference.image();
+   if(checked.operation==='image.compose')return reference.image({width:checked.width,height:checked.height});
+   if(checked.operation==='document.text'){const text=new TextDecoder().decode(new Uint8Array(buffer(await readBytes(checked.source))));return {pages:[text],text};}
    if(checked.operation==='timeline.render')return checked.kind==='audio'?reference.audio({sampleRate:44100}):reference.video();
    if(checked.operation.startsWith('audio.'))return reference.audio({sampleRate:44100});
    return reference.video();

package/packages/block-sdk/mocks.js

@@ -14,7 +14,10 @@ export function validateMocks(value){
   assert(Array.isArray(value.network),'MOCK_HOST',`${MOCKS_FILE} network is a list of recorded responses`);
   for(const entry of value.network)assert(plain(entry)&&typeof entry.url==='string'&&/^https:\/\//.test(entry.url)&&(entry.method===undefined||typeof entry.method==='string')&&(entry.status===undefined||Number.isInteger(entry.status)&&entry.status>=100&&entry.status<=599)&&[entry.json!==undefined,typeof entry.text==='string',typeof entry.base64==='string'].filter(Boolean).length<=1,'MOCK_HOST','Each recorded response has an https url, an optional method and status, and at most one of json, text or base64');
  }
- if(Object.hasOwn(value,'files'))for(const [name,path] of Object.entries(value.files))assert(typeof path==='string'&&path&&!path.startsWith('/')&&!path.split(/[\\/]/).includes('..'),'MOCK_HOST',`${MOCKS_FILE} files.${name} is a path inside the Block folder`);
+ // A file is a path inside the Block folder, or {text} for a text file given inline (October 28, 2026: the in-app
+ // builder has no Block folder, so a Block reading a notes file the person gives it could not be tested), or {base64} for a
+ // small binary file, which travels in the pack (November 2026).
+ if(Object.hasOwn(value,'files'))for(const [name,path] of Object.entries(value.files))assert(typeof path==='string'&&path&&!path.startsWith('/')&&!path.split(/[\\/]/).includes('..')||plain(path)&&Object.keys(path).length===1&&(typeof path.text==='string'&&path.text.length<=200000||typeof path.base64==='string'&&path.base64.length<=349528),'MOCK_HOST',`${MOCKS_FILE} files.${name} is a path inside the Block folder, {text} with a text file's contents, or {base64} with a small binary file's (at most 256 KB)`);
  if(Object.hasOwn(value,'project'))assert(plain(value.project),'MOCK_HOST',`${MOCKS_FILE} project is a project snapshot object`);
  return value;
 }

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

@@ -5,6 +5,7 @@
 // operation in `permissions.capabilities`.
 import {assert,plain,stableStringify} from './contracts.js';
 import {defaultCapabilityExpectations} from './capabilities.js';
+import {GENERATION_LIMITS,IMAGE_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());
@@ -20,7 +21,14 @@ const SHAPES={
  },
  'image.generate':request=>{
   if(!text(request.prompt,32000))fail('image.generate needs a prompt');
-  return {inputs:{prompt:port('text','Image prompt')},outputs:{result:port('image','Generated image')},capability:{prompt:{$input:'prompt'},output:'result',...(request.settings?{settings:request.settings}:{}),...(request.negativePrompt?{negativePrompt:request.negativePrompt}:{}),...(Number.isInteger(request.seed)?{seed:request.seed}:{})},input:{prompt:request.prompt}};
+  // references: saved photos the new picture keeps (the product, person or place), as a capability Block binds them
+  // (October 29, 2026: an escape room poster could not keep the room in the person's photos).
+  const references=request.references;
+  if(references!==undefined&&(!Array.isArray(references)||!references.length||references.length>GENERATION_LIMITS.references||!references.every(value=>media(value,'image'))))fail(`image.generate references are 1 to ${GENERATION_LIMITS.references} saved images`);
+  // A model named in settings must take that many photos (GPT-Image 1.5, Kling Image V3 and Seedream 4.5 take none).
+  const model=IMAGE_GENERATION_MODELS[request.settings?.model];
+  if(references&&model&&references.length>model.references)fail(model.references?`${model.label} takes at most ${model.references} reference photos`:`${model.label} takes no reference photos: choose a model that does, or leave the model to the person`);
+  return {inputs:{prompt:port('text','Image prompt'),...(references?{references:port('image[]','Reference images')}:{})},outputs:{result:port('image','Generated image')},capability:{prompt:{$input:'prompt'},output:'result',...(references?{references:{$input:'references'}}:{}),...(request.settings?{settings:request.settings}:{}),...(request.negativePrompt?{negativePrompt:request.negativePrompt}:{}),...(Number.isInteger(request.seed)?{seed:request.seed}:{})},input:{prompt:request.prompt,...(references?{references}:{})}};
  },
  'video.generate':request=>{
   if(!text(request.prompt,32000))fail('video.generate needs a prompt');
@@ -53,8 +61,10 @@ const SHAPES={
   const list=Array.isArray(request.media)?request.media:[request.media],kind=list[0]?.kind;
   if(!list.length||!['image','video'].includes(kind)||!list.every(value=>media(value,kind))||(kind==='video'&&list.length!==1)||list.length>4)fail('media.analyze needs one saved video or one to four saved images');
   if(!text(request.question,2000))fail('media.analyze needs a question');
+  // October 30, 2026: detail:'check' is the short photo check, priced per call of up to four photos.
+  if(request.detail!==undefined&&(request.detail!=='check'||kind!=='image'))fail('media.analyze detail:"check" checks one to four saved images, never a video');
   const many=Array.isArray(request.media);
-  return {inputs:{media:port(kind==='video'?'video':many?'image[]':'image','Media to analyze')},outputs:{result:port('json','Visual evidence')},capability:{media:{$input:'media'},question:request.question,output:'result'},input:{media:many?list:list[0]}};
+  return {inputs:{media:port(kind==='video'?'video':many?'image[]':'image','Media to analyze')},outputs:{result:port('json','Visual evidence')},capability:{media:{$input:'media'},question:request.question,...(request.detail?{detail:request.detail}:{}),output:'result'},input:{media:many?list:list[0]}};
  },
  'web.fetch':request=>{
   if(!text(request.url,2048)||!text(request.instruction,4000))fail('web.fetch needs a url and an instruction');

package/packages/block-sdk/port-types.d.ts

@@ -1,3 +1,9 @@
+/** What a value of each port type is, in one table: the generated declarations, the authoring guide and a missing Block's brief read it. */
+export const PORT_VALUE_SHAPES: Readonly<Record<string, string>>;
+/** Every other structured port type: an object with schemaVersion 1 whose fields its own contract gives. */
+export const STRUCTURED_VALUE_SHAPE: string;
+/** The value shape of one port type (without []): its own, the structured one for another SDK type, or null for an unknown type. */
+export function portValueShape(type: string): string | null;
 /** Port types with their own TypeScript value type in generated declarations. */
 export const PORT_VALUE_TYPES: Readonly<Record<string, string>>;
 /** The TypeScript type of a compact port schema ("number[]", {points: "number[]"}, ["string"]). */

package/packages/block-sdk/port-types.js

@@ -4,8 +4,30 @@
 // `run(input, stillmade)`, and every port's value, from the manifest. The file
 // is self-contained: it needs no package to resolve.
 import {VIEW_BRIDGE} from './view-bridge.js';
+import {TYPES} from './contracts.js';
+import {FILE_MEDIA_TYPES,DOCUMENT_FORMATS} from './data-values.js';
 
 const MEDIA_FIELDS='assetId: string; versionId: string; url: string; mimeType?: string; bytes?: number; name?: string; role?: string';
+const quoted=values=>values.map(value=>`'${value}'`).join(' | ');
+// What a value of each port type is, in one table: these declarations, the authoring guide's type list and a missing
+// Block's brief all read it (October 27, 2026: built Blocks typed a document port text and returned a document object).
+export const PORT_VALUE_SHAPES=Object.freeze({
+ text:'a string',number:'a number',integer:'a whole number',boolean:'true or false',json:'any JSON value',object:'a plain JSON object',
+ url:'an absolute http or https address string',date:"an ISO 8601 date string ('2026-10-09' or '2026-10-09T14:30')",color:"a hex color string ('#ff8800' or '#ff8800cc')",
+ image:`{kind: 'image'; ${MEDIA_FIELDS}; width?: number; height?: number}`,
+ video:`{kind: 'video'; ${MEDIA_FIELDS}; width?: number; height?: number; duration?: number}`,
+ audio:`{kind: 'audio'; ${MEDIA_FIELDS}; duration?: number; sampleRate?: number; channels?: number}`,
+ asset:`{kind: 'image' | 'video' | 'audio' | 'asset'; ${MEDIA_FIELDS}}`,
+ file:`{kind: 'file'; assetId: string; versionId: string; mimeType: ${quoted(FILE_MEDIA_TYPES)}; url?: string; name?: string; bytes?: number}`,
+ document:`{schemaVersion: 1; format: ${quoted(DOCUMENT_FORMATS)}; text: string; title?: string}`,
+ table:'{schemaVersion?: 1; columns: string[]; rows: Array<Record<string, string | number | boolean | null>>}',
+ transcript:'{schemaVersion: 1; text: string; words: Array<{text: string; start: number; end: number}>}',
+ script:'{schemaVersion: 1; text: string; [key: string]: unknown}',
+});
+/** Every other structured port type: an object with schemaVersion 1 whose fields its own contract gives. */
+export const STRUCTURED_VALUE_SHAPE='{schemaVersion: 1; [key: string]: unknown}';
+/** The value shape of one port type (without []): its own, the structured one for another SDK type, or null for an unknown type. */
+export function portValueShape(type){return Object.hasOwn(PORT_VALUE_SHAPES,type)?PORT_VALUE_SHAPES[type]:TYPES.includes(type)?STRUCTURED_VALUE_SHAPE:null;}
 /** Port types with their own TypeScript value type. Other structured types are schema-1 documents. */
 export const PORT_VALUE_TYPES=Object.freeze({
  text:'string',number:'number',integer:'number',boolean:'boolean',json:'StillMadeJson',object:'Record<string, unknown>',
@@ -46,17 +68,17 @@ export function blockTypeDeclarations(manifest){
 export {};
 
 type StillMadeJson = string | number | boolean | null | StillMadeJson[] | {[key: string]: StillMadeJson};
-type StillMadeMedia = {kind: 'image' | 'video' | 'audio' | 'asset'; ${MEDIA_FIELDS}};
+type StillMadeMedia = ${PORT_VALUE_SHAPES.asset};
 /** A saved image, or decoded RGBA pixels (recipe and JavaScript Blocks). */
-type StillMadeImage = {kind: 'image'; ${MEDIA_FIELDS}; width?: number; height?: number} | {width: number; height: number; data: number[]; role?: string};
-type StillMadeVideo = {kind: 'video'; ${MEDIA_FIELDS}; width?: number; height?: number; duration?: number};
-type StillMadeAudio = {kind: 'audio'; ${MEDIA_FIELDS}; duration?: number; sampleRate?: number; channels?: number};
-type StillMadeFile = {kind: 'file'; assetId: string; versionId: string; mimeType: 'application/pdf' | 'text/plain' | 'text/csv' | 'text/markdown' | 'application/json' | 'application/zip'; url?: string; name?: string; bytes?: number};
-type StillMadeDocument = {schemaVersion: 1; format: 'markdown' | 'plain'; text: string; title?: string};
-type StillMadeTable = {schemaVersion?: 1; columns: string[]; rows: Array<Record<string, string | number | boolean | null>>};
-type StillMadeTranscript = {schemaVersion: 1; text: string; words: Array<{text: string; start: number; end: number}>};
-type StillMadeScript = {schemaVersion: 1; text: string; [key: string]: unknown};
-type StillMadeDocumentValue = {schemaVersion: 1; [key: string]: unknown};
+type StillMadeImage = ${PORT_VALUE_SHAPES.image} | {width: number; height: number; data: number[]; role?: string};
+type StillMadeVideo = ${PORT_VALUE_SHAPES.video};
+type StillMadeAudio = ${PORT_VALUE_SHAPES.audio};
+type StillMadeFile = ${PORT_VALUE_SHAPES.file};
+type StillMadeDocument = ${PORT_VALUE_SHAPES.document};
+type StillMadeTable = ${PORT_VALUE_SHAPES.table};
+type StillMadeTranscript = ${PORT_VALUE_SHAPES.transcript};
+type StillMadeScript = ${PORT_VALUE_SHAPES.script};
+type StillMadeDocumentValue = ${STRUCTURED_VALUE_SHAPE};
 
 /** ${manifest.name}: input values. */
 export interface BlockInputs {

package/packages/block-sdk/shared-agent-controls.js

@@ -13,6 +13,28 @@ const label=value=>String(value||'').replace(/[-_]+/g,' ').replace(/\s+/g,' ').t
 
 // Read static host-bound controls as data. The parser deliberately does not
 // execute author JavaScript or attempt to infer fields from arbitrary code.
+// November 1, 2026 (live controller check): Chat set Narration's voice to "Nova", the label it saw, and the screen
+// kept Onyx because its radio value is "nova". A fieldset's radio options are read with their visible labels so a
+// pick is saved as the option's own value.
+function choiceOptions(source=''){
+ const options=[];
+ for(const match of String(source).matchAll(/<input\b([^>]*)>([\s\S]*?)(?=<input\b|<\/label>|$)/gi)){
+  const attrs=attributes(match[1]);
+  if((attrs.get('type')||'').toLowerCase()!=='radio'||!attrs.has('value'))continue;
+  options.push({value:attrs.get('value'),label:match[2].replace(/<[^>]*>/g,' ').replace(/\s+/g,' ').trim().slice(0,120)});
+ }
+ return options.slice(0,40);
+}
+
+// The option value a pick names: its value, its label, or the label's first word, in any case.
+export function choiceValue(control,value){
+ if(!control?.options?.length||typeof value!=='string')return value;
+ const wanted=value.trim().toLowerCase();
+ const found=control.options.find(option=>option.value.toLowerCase()===wanted)||control.options.find(option=>option.label.toLowerCase()===wanted||option.label.split(' ')[0].toLowerCase()===wanted);
+ if(!found)throw new Error(`Choose one of: ${control.options.map(option=>option.value).join(', ')}.`);
+ return found.value;
+}
+
 export function sharedAgentControls(view){
  const html=String(view?.html||'').replace(/<!--[\s\S]*?-->/g,''),controls=[];
  for(const match of html.matchAll(/<(input|textarea|select|fieldset)\b([^>]*)>/gi)){
@@ -24,7 +46,8 @@ export function sharedAgentControls(view){
   const type=element==='input'?(['search','email','tel','url'].includes(inputType)?'text':inputType):element==='fieldset'?'choice':element;
   if(!['text','number','range','checkbox','color','textarea','select','choice'].includes(type))continue;
   const description=label(attrs.get('aria-label')||attrs.get('title')||key);
-  controls.push({key,id,type,description,...(Number.isFinite(Number(attrs.get('min')))&&attrs.has('min')?{minimum:Number(attrs.get('min'))}:{}),...(Number.isFinite(Number(attrs.get('max')))&&attrs.has('max')?{maximum:Number(attrs.get('max'))}:{})});
+  const options=type==='choice'?choiceOptions(html.slice(match.index+match[0].length,html.indexOf('</fieldset>',match.index)>=0?html.indexOf('</fieldset>',match.index):undefined)):null;
+  controls.push({key,id,type,description,...(options?.length?{options}:{}),...(Number.isFinite(Number(attrs.get('min')))&&attrs.has('min')?{minimum:Number(attrs.get('min'))}:{}),...(Number.isFinite(Number(attrs.get('max')))&&attrs.has('max')?{maximum:Number(attrs.get('max'))}:{})});
  }
  return controls.slice(0,100);
 }
@@ -45,7 +68,7 @@ export function parseSharedAgentValue(control,current,value){
   return value;
  }
  if(control?.type==='color'){if(typeof value!=='string'||!/^#[0-9a-f]{6}$/i.test(value))throw new Error('This shared color needs a six-digit hex value.');return value;}
- if(['text','textarea','select','choice'].includes(control?.type)){if(typeof value!=='string'||value.length>65536)throw new Error('This shared control needs bounded text.');return value;}
+ if(['text','textarea','select','choice'].includes(control?.type)){if(typeof value!=='string'||value.length>65536)throw new Error('This shared control needs bounded text.');return control.type==='choice'?choiceValue(control,value):value;}
  if(current===null){if(value!==null)throw new Error('This dynamic shared field currently accepts null only.');return null;}
  if(Array.isArray(current)){if(!Array.isArray(value))throw new Error('Keep this dynamic shared field as an array.');return structuredClone(value);}
  if(plain(current)){if(!plain(value))throw new Error('Keep this dynamic shared field as an object.');return structuredClone(value);}