stillmade-sdk 0.1.34 → 0.1.36

package/packages/block-sdk/folder-package.js

@@ -0,0 +1,75 @@
+// One reader for a Block folder, the layout `stillmade-block create` writes:
+// stillmade.block.json, src/, tests/fixtures.json, and for module Blocks module/
+// and module.json. The CLI's pack, dev and test and the app's Import folder both
+// use it, so a folder made anywhere (the CLI, Codex, Claude Code, by hand) imports
+// exactly as the CLI packs it. Pure JavaScript: the caller supplies the files.
+import {VIEW_SOURCE_FILES,VIEW_CONFIG_FILE,viewFromSource} from './view-source.js';
+import {describeViewFiles} from './view.js';
+import {describeModuleFiles,MODULE_LIMITS} from './module-runtime.js';
+
+export const BLOCK_FOLDER_MANIFEST='stillmade.block.json';
+export const BLOCK_FOLDER_LIMITS=Object.freeze({jsonBytes:4000000,javascriptBytes:262144,viewScriptBytes:4194304,viewSourceBytes:262144});
+const SOURCE=/^src\/(run\.js|recipe\.json|comfyui\.json|capability\.json|desktop\.json|view\.json|view\.config\.json|view\.(?:html|css|js)|view\.themed\.css)$/;
+
+/** Whether a path relative to a Block folder belongs to the Block. Everything
+ *  else (node_modules, build output, notes, .git) is left out. */
+export function blockFolderPath(path){
+ return path===BLOCK_FOLDER_MANIFEST||path==='module.json'||path==='tests/fixtures.json'||SOURCE.test(path)||path.startsWith('module/')||path.startsWith('src/view-files/');
+}
+
+const missing=path=>Object.assign(new Error(`Missing ${path}`),{code:'ENOENT'});
+const decoder=new TextDecoder('utf-8',{fatal:true});
+
+/**
+ * The package for a Block folder. `read(path)` resolves a file's bytes, or
+ * undefined when it does not exist; `list(prefix)` resolves {relativePath: bytes}
+ * for every file under a folder such as 'module/' ({} when there is none).
+ * Returns {pkg, files}: files holds module files by path and frame view assets as
+ * `view:<path>`, for tests, previews and upload; null when there are none.
+ */
+export async function packageFromFolder({read,list}){
+ const bytes=async(path,limit,message)=>{const value=await read(path);if(value===undefined)return undefined;if(value.byteLength>limit)throw new Error(message||`${path} exceeds ${Math.round(limit/1000000)} MB`);return value;};
+ const json=async(path,{optional=false}={})=>{const value=await bytes(path,BLOCK_FOLDER_LIMITS.jsonBytes,'Package file exceeds 4 MB');if(value===undefined){if(optional)return undefined;throw missing(path);}return JSON.parse(decoder.decode(value));};
+ const folder=async prefix=>{
+  const files=await list(prefix);let total=0;
+  for(const value of Object.values(files)){total+=value.byteLength;if(value.byteLength>MODULE_LIMITS.fileBytes)throw new Error('A module file exceeds 64 MiB');}
+  if(Object.keys(files).length>MODULE_LIMITS.files||total>MODULE_LIMITS.totalBytes)throw new Error('The module folder exceeds 64 files or 128 MiB');
+  return files;
+ };
+ const manifest=await json(BLOCK_FOLDER_MANIFEST);
+ let source,moduleFiles=null;
+ if(manifest.runtime==='module'){
+  const config=await json('module.json',{optional:true})||{};
+  moduleFiles=await folder('module/');
+  source={module:await describeModuleFiles(config.entry||'main.js',moduleFiles,{threads:config.threads===true})};
+ }else if(manifest.runtime==='javascript'){
+  const code=await bytes('src/run.js',BLOCK_FOLDER_LIMITS.javascriptBytes,'JavaScript exceeds 256 KiB');
+  if(code===undefined)throw missing('src/run.js');
+  source={code:decoder.decode(code)};
+ }else if(manifest.runtime==='comfyui')source={comfyui:await json('src/comfyui.json')};
+ else if(manifest.runtime==='capability')source={capability:await json('src/capability.json')};
+ else source={recipe:await json('src/recipe.json')};
+ // A frame view's script may be a framework bundle (up to 4 MiB).
+ const sources={};
+ for(const name of ['view.json',VIEW_CONFIG_FILE,...Object.keys(VIEW_SOURCE_FILES)]){
+  const value=await bytes(`src/${name}`,name==='view.js'?BLOCK_FOLDER_LIMITS.viewScriptBytes:BLOCK_FOLDER_LIMITS.viewSourceBytes,`Interface source ${name} is too large`);
+  if(value!==undefined)sources[name]=decoder.decode(value);
+ }
+ const view=viewFromSource(sources);
+ // A frame view's assets live in src/view-files/ and are named by SHA-256.
+ let viewFiles=null;
+ if(view?.runtime==='frame'){
+  const assets=await folder('src/view-files/');
+  if(Object.keys(assets).length){view.files=await describeViewFiles(assets);viewFiles=Object.fromEntries(Object.entries(assets).map(([name,value])=>[`view:${name}`,value]));}
+ }
+ const desktop=await json('src/desktop.json',{optional:true});
+ const pkg={manifest,...source,...(desktop!==undefined?{desktop}:{}),...(view!==undefined?{view}:{}),tests:await json('tests/fixtures.json')};
+ return {pkg,files:moduleFiles||viewFiles?{...(moduleFiles||{}),...(viewFiles||{})}:null};
+}
+
+/** The file bytes a package names, keyed by SHA-256, for upload or a module bundle. */
+export function packageFilesBySha(pkg,files){
+ const bySha={};
+ for(const [name,file] of [...Object.entries(pkg.module?.files||{}),...Object.entries(pkg.view?.files?.files||{}).map(([name,file])=>[`view:${name}`,file])])if(files?.[name])bySha[file.sha256]=files[name];
+ return bySha;
+}

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

@@ -144,7 +144,7 @@ export const VIEW_LIMITS: Readonly<{htmlBytes:65536;cssBytes:32768;javascriptByt
 export interface BlockImagePreview { url: `data:image/png;base64,${string}`; width: number; height: number; }
 export interface BlockImagePixels { width: number; height: number; data: number[]; role?: string; }
 export interface BlockImageReference { kind: 'image'; assetId: string; versionId: string; url: string; role?: string; }
-export type DesktopPermission = "screen.capture"|"cursor.track"|"camera.capture"|"microphone.capture"|"clipboard.read"|"clipboard.write"|"media.pick"|"notifications.show"|"power.keep-awake"|"native.tools";
+export type DesktopPermission = "screen.capture"|"cursor.track"|"camera.capture"|"microphone.capture"|"clipboard.read"|"clipboard.write"|"media.pick"|"notifications.show"|"power.keep-awake"|"native.tools"|"folder.read"|"folder.write";
 export type DesktopToolDeclaration = {id:'org.natron.Natron';adapterVersion:1;actions:('launch'|'project.import'|'project.open'|'project.render')[]} | {id:'org.stillmade.PythonAdapter';adapterVersion:1;actions:('adapter.import'|'adapter.inspect'|'adapter.execute'|'adapter.describe'|'adapter.call')[]};
 export type DesktopExecution = {schemaVersion:1;tool:'org.natron.Natron';action:'project.render';arguments:Record<'projectId'|'input'|'reader'|'writer'|'firstFrame'|'lastFrame',{input:string}>;outputs:Record<string,'asset'>} | {schemaVersion:1;tool:'org.stillmade.PythonAdapter';action:'adapter.execute';arguments:Record<'adapterId'|'sourceDigest'|'functionId'|'input',{input:string}>;outputs:Record<string,'result'>} | {schemaVersion:2;tool:'org.stillmade.PythonAdapter';action:'adapter.call';source:{code:string;digest:string;license:string};functionId:string;arguments:Record<string,{input:string}>;outputs:{result:'result'}};
 export interface DesktopExecutionRequest {schemaVersion:1;requestId:string;packageDigest:string;inputDigest:string;tools:DesktopToolDeclaration[]}
@@ -169,7 +169,7 @@ export interface BlockViewNode { tag: BlockViewTag; text?: string; children?: Bl
 export interface BlockViewAction { action: string; value: string; checked: boolean; event: 'click'|'input'|'change'; }
 export interface BlockMediaReference { kind: 'video'|'audio'; assetId: string; versionId: string; url: string; role?: string; }
 export interface BlockMediaPreview { kind: 'video'|'audio'; url: string; mimeType: string; bytes: number; }
-export interface BlockViewBridge { useOutput(outputs: Record<string, BlockMediaReference|BlockMediaReference[]>): Promise<Record<string, unknown>>; previewMedia(value: BlockMediaReference): Promise<BlockMediaPreview>; releaseMedia(url: string): void; render(targetId: string, tree: BlockViewNode[]): void; onAction(callback: (event: BlockViewAction) => void|Promise<void>): () => void; desktop(operation: DesktopPermission|DesktopToolOperation|import('./block-storage.js').BlockStorageOperation|"record.start"|"record.stop"|"record.cancel"|"session.close", args?: Record<string,unknown>): Promise<Record<string,unknown>>; readonly input: Record<string, unknown>; onInput(callback: (input: Record<string, unknown>) => void): () => void; run(input: Record<string, unknown>): Promise<Record<string, unknown>>; previewImage(value: BlockImageReference|BlockImagePixels): Promise<BlockImagePreview>; }
+export interface BlockViewBridge { useOutput(outputs: Record<string, BlockMediaReference|BlockMediaReference[]>): Promise<Record<string, unknown>>; previewMedia(value: BlockMediaReference): Promise<BlockMediaPreview>; releaseMedia(url: string): void; render(targetId: string, tree: BlockViewNode[]): void; onAction(callback: (event: BlockViewAction) => void|Promise<void>): () => void; desktop(operation: DesktopPermission|DesktopToolOperation|import('./block-storage.js').BlockStorageOperation|"record.start"|"record.stop"|"record.cancel"|"session.close"|"live.start"|"live.stop"|"live.status"|"folder.pick"|"folder.shared"|"folder.forget"|"folder.list", args?: Record<string,unknown>): Promise<Record<string,unknown>>; readonly input: Record<string, unknown>; onInput(callback: (input: Record<string, unknown>) => void): () => void; run(input: Record<string, unknown>): Promise<Record<string, unknown>>; previewImage(value: BlockImageReference|BlockImagePixels): Promise<BlockImagePreview>; }
 
 /** Validate hosted UI colors independently of the preserved original stylesheet. */
 export function validateViewAppearance(view?: BlockView, options?: {appearance?:'host'|'original'}): true;
@@ -575,9 +575,14 @@ export interface ConnectionConfigurationResult {schemaVersion:1;operation:'reloa
 export function configuredConnectionBlock(app:ConnectedAppMetadata,route:ConnectedTaskMetadata,basePackage:BlockPackage,configuration:ConnectionConfigurationResult):Promise<BlockPackage>;
 export function validateConnectedCapability(capability:ConnectedCapability,manifest:Manifest):true;
 export function prepareConnectedInvocation(pkg:BlockPackage,raw:Record<string,unknown>):{operation:'connection.execute';appId:string;capabilityId:string;pin:ConnectionPin;input:Record<string,unknown>};
-export interface SchemaFields {currencyDigits(currency:string):number;minorUnits(decimal:string,currency:string):number;formatMoney(minor:number,currency:string):string;preview(value:unknown,options?:{maximumFields?:number}):BlockViewNode[];read(root:unknown,path:Array<string|number>):unknown;set(root:unknown,path:Array<string|number>,value:unknown):Record<string,unknown>;controls(schema:Record<string,unknown>,bindings:Record<string,string>,values:Record<string,unknown>,options?:{canEdit?:boolean;busy?:boolean}):{tree:unknown[];actions:unknown[]};change(values:Record<string,unknown>,actions:unknown[],event:unknown):Record<string,unknown>;fromState(input:Record<string,unknown>,state:Record<string,unknown>,bindings:Record<string,string>):Record<string,unknown>;edits(values:Record<string,unknown>,state:Record<string,unknown>,bindings:Record<string,string>):{patch:Record<string,unknown>;before:Record<string,unknown>;changed:boolean}}
+export interface SchemaFields {currencyDigits(currency:string):number;minorUnits(decimal:string,currency:string):number;formatMoney(minor:number,currency:string):string;preview(value:unknown,options?:{maximumFields?:number}):BlockViewNode[];read(root:unknown,path:Array<string|number>):unknown;set(root:unknown,path:Array<string|number>,value:unknown):Record<string,unknown>;controls(schema:Record<string,unknown>,bindings:Record<string,string>,values:Record<string,unknown>,options?:{canEdit?:boolean;busy?:boolean;more?:string[];hide?:string[]}):{tree:unknown[];actions:unknown[]};change(values:Record<string,unknown>,actions:unknown[],event:unknown):Record<string,unknown>;fromState(input:Record<string,unknown>,state:Record<string,unknown>,bindings:Record<string,string>):Record<string,unknown>;edits(values:Record<string,unknown>,state:Record<string,unknown>,bindings:Record<string,string>):{patch:Record<string,unknown>;before:Record<string,unknown>;changed:boolean}}
 export function createSchemaFields(lockedInputKeys?:string[]):Readonly<SchemaFields>;
 export interface BlockViewBridge {schemaFields:Readonly<SchemaFields>}
+export interface BlockLiveFrameInfo {index:number;timestamp:number;width:number;height:number}
+export interface BlockLiveAudioInfo {index:number;timestamp:number;sampleRate:number}
+/** The camera and microphone as they happen (`camera.capture`, `microphone.capture`); nothing reaches the view before the person presses Start. */
+export interface BlockLiveFeed {start(options:{camera?:boolean;microphone?:boolean;fps?:number;width?:number;sampleRate?:number}):Promise<{live:true;camera:boolean;microphone:boolean;fps:number;width:number;height:number;sampleRate:number}>;stop():Promise<{live:false}>;status():Promise<{live:boolean;[key:string]:unknown}>;onFrame(callback:(frame:ImageBitmap,info:BlockLiveFrameInfo)=>void):()=>void;onAudio(callback:(samples:Float32Array,info:BlockLiveAudioInfo)=>void):()=>void;onEnd(callback:(event:{reason:string})=>void):()=>void}
+export interface BlockViewBridge {readonly live:BlockLiveFeed}
 
 export interface ConnectionReferencePointer {id:string;version:string}
 export interface ConnectionReferenceField {path:Array<string|number>;value:string|number|boolean|null}
@@ -617,7 +622,9 @@ export function parseJsonReply(text: string): unknown;
 
 /** Runtime `module`: an ES module (with optional WebAssembly and data files) named by SHA-256. */
 export interface ModuleFile { sha256: string; bytes: number; mediaType: 'text/javascript'|'application/wasm'|'application/json'|'text/plain'|'image/png'|'image/jpeg'|'image/webp'|'font/woff2'|'application/octet-stream'; }
-export interface ModuleDescriptor { schemaVersion: 1; entry: string; files: Record<string, ModuleFile>; }
+export interface ModuleDescriptor { schemaVersion: 1; entry: string; files: Record<string, ModuleFile>; /** Run in a Worker that shares memory with the Workers it starts (no WebCodecs, WebGPU or crypto.subtle). */ threads?: true; }
+/** A live WebSocket a module opened with stillmade.net.connect. */
+export interface ModuleLiveSocket { url: string; protocol: string; readonly readyState: number; onmessage: ((event: {data: string | ArrayBuffer}) => void) | null; onclose: ((event: {code: number; reason: string; wasClean: boolean}) => void) | null; send(data: string | ArrayBuffer | ArrayBufferView | Blob): Promise<unknown>; close(code?: number, reason?: string): Promise<{code: number; reason: string; wasClean: boolean}>; closed: Promise<{code: number; reason: string; wasClean: boolean}>; addEventListener(type: 'message' | 'close', listener: (event: Event & Record<string, unknown>) => void): void; removeEventListener(type: 'message' | 'close', listener: (event: Event & Record<string, unknown>) => void): void; [Symbol.asyncIterator](): AsyncIterator<string | ArrayBuffer>}
 export const MODULE_RUNTIME_VERSION: 1;
 export const MODULE_LIMITS: Readonly<{files:64;fileBytes:67108864;totalBytes:134217728;path:160;wallClockMs:120000;maxWallClockMs:1800000;progressGraceMs:60000;messageBytes:16777216;logEntries:500}>;
 export const MODULE_MEDIA_TYPES: readonly ModuleFile['mediaType'][];
@@ -643,8 +650,8 @@ export interface ModuleHost {
   media: { transform(request: MediaTransformRequest): Promise<SavedMediaRef|DecodedAudio>; };
   actions: { run(action: Record<string, unknown>): Promise<unknown>; };
   hosted: { run(operation: string, request: Record<string, unknown>): Promise<unknown>; };
-  /** Declared-origin network calls; StillMade adds the person's own key. */
-  net: { fetch(url: string|URL, init?: {method?: string; headers?: Record<string,string>|[string,string][]; body?: ArrayBuffer|ArrayBufferView|Blob|string}): Promise<Response>; };
+  /** Declared-origin network calls; StillMade adds the person's own key. `connect` opens a live WebSocket to a declared origin's wss:// form (no key). */
+  net: { fetch(url: string|URL, init?: {method?: string; headers?: Record<string,string>|[string,string][]; body?: ArrayBuffer|ArrayBufferView|Blob|string}): Promise<Response>; connect(url: string|URL, options?: {protocols?: string|string[]}): Promise<ModuleLiveSocket>; };
   /** Published adapter operations, with the person's own account. */
   connections: { call(appId: string, operation: string, input?: Record<string, unknown>): Promise<unknown>; };
   /** The Block's cloud storage in this project (manifest `storage`). */
@@ -701,3 +708,22 @@ export const NATIVE_APPLICATION_RUNTIME_REQUIREMENT:string;
 /** Validates a native application package's strict source syntax and returns its detached, frozen copy. Throws NATIVE_APPLICATION_PACKAGE errors. Not runtime admission. */
 export function defineNativeApplicationPackage<T=unknown>(value:T):T;
 export function validateNativeApplicationPackage(value:unknown):true;
+export const PERMISSION_LEVELS:readonly ["none","low","medium","high"];
+export type PermissionLevel="none"|"low"|"medium"|"high";
+export interface PermissionLine { id:string; text:string; level:PermissionLevel; family:"project"|"service"|"network"|"device" }
+/** What a Block can do, in plain words, with the level of care it needs. The host refuses anything a Block did not declare, so this is all it can reach. */
+export function summarizePermissions(manifest:Manifest):{ level:PermissionLevel; lines:PermissionLine[]; dataLeaves:boolean; staysInStillMade:boolean; headline:string };
+/** What an update adds or removes, by line, and whether its level rose. */
+export function permissionChanges(previous:Manifest,next:Manifest):{ added:PermissionLine[]; removed:PermissionLine[]; levelRaised:boolean; before:ReturnType<typeof summarizePermissions>; after:ReturnType<typeof summarizePermissions> };
+/** What a Block's source uses compared with its manifest: desktop operations and network origins used but not declared, or declared and never used. Advice from literal names; never a gate. */
+export function permissionUsage(pkg:BlockPackage,files?:Record<string,Uint8Array|string>):{ desktop:string[]; origins:string[]; undeclared:{family:"desktop"|"network";scope:string}[]; unused:{family:"desktop"|"network";scope:string}[] };
+/** The manifest declaring what the source uses and nothing else. */
+export function fixPermissions(manifest:Manifest,usage:ReturnType<typeof permissionUsage>):Manifest;
+/** The package for a Block folder (the layout stillmade-block create writes), from its files. Shared by the CLI and StillMade's Import folder. */
+export function packageFromFolder(source:{ read(path:string):Promise<Uint8Array|undefined>; list(prefix:string):Promise<Record<string,Uint8Array>> }):Promise<{ pkg:BlockPackage; files:Record<string,Uint8Array>|null }>;
+/** Whether a path inside a Block folder is part of the Block (node_modules, build output and notes are not). */
+export function blockFolderPath(path:string):boolean;
+/** The manifest file at the root of a Block folder. */
+export const BLOCK_FOLDER_MANIFEST:"stillmade.block.json";
+/** Size limits for Block folder source files, in bytes. */
+export const BLOCK_FOLDER_LIMITS:Readonly<{jsonBytes:4000000;javascriptBytes:262144;viewScriptBytes:4194304;viewSourceBytes:262144}>;

package/packages/block-sdk/index.js

@@ -166,3 +166,7 @@ export {pythonConnectionBlock} from './python-connection.js';
 export {createConnectionClient,CONNECTION_API_OPERATIONS} from './connection-client.js';
 
 export {configuredConnectionBlock} from './configured-connection.js';
+
+export {summarizePermissions,permissionChanges,PERMISSION_LEVELS} from './permission-summary.js';
+export {permissionUsage,fixPermissions} from './permission-usage.js';
+export {packageFromFolder,blockFolderPath,BLOCK_FOLDER_MANIFEST,BLOCK_FOLDER_LIMITS} from './folder-package.js';

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

@@ -38,9 +38,11 @@ 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.
- const module=moduleFiles?await (async()=>{const [{createNodeModuleExecutor},{createMockHost}]=await Promise.all([import('./module-node.js'),import('./mock-host.js')]);return createNodeModuleExecutor({files:moduleFiles,host:host||createMockHost({manifest:pkg.manifest}).host});})():undefined;
+ // 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;
+ const module=executors?.module;
   const report=await admitPackage(pkg,{
-   test:content=>testPackage(content,{timeoutMs:remaining(),...(module?{module}:{})}),
+   test:content=>testPackage(content,{timeoutMs:remaining(),...(executors||{})}),
    run:(content,input,options)=>{remaining();return runPackageAsync(content,input,{...options,signal:controller.signal,...(module?{module}:{})});},
   });
   remaining();

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

@@ -4,11 +4,18 @@
 // in this run; results are saved to the runner's library, except audio.decode,
 // which returns PCM samples for analysis.
 import {assert,plain} from './contracts.js';
+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']);
+export const MEDIA_TRANSFORM_OPERATIONS=Object.freeze(['audio.decode','audio.extract','audio.normalize','video.cut','video.concat','video.resize','image.thumbnail','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']);
+export const TIMELINE_TRANSITIONS=Object.freeze(['Cut','Fade','Cross dissolve','Shape wipe','Iris','Ink splat','Swirl','Whip left','Whip right','Whip up','Whip down','Whip pan','Slash','Shred','Morph','Dip to black','Dip to white','Push left','Push right','Push up','Push down','Zoom left','Zoom right','Zoom up','Zoom down']);
+export const CAPTION_ANIMATIONS=Object.freeze(['none','fade','pop','scale_in_out','slide','typewriter','rise','word_pop','word_sequence','word_reveal']);
+export const TIMELINE_ASPECTS=Object.freeze(['16:9','9:16','1:1','4:5']);
 const ref=(value,kinds)=>plain(value)&&kinds.includes(value.kind)&&['assetId','versionId','url'].every(key=>typeof value[key]==='string'&&value[key].trim()&&value[key].length<=16384);
 const settings=value=>value===undefined||plain(value)&&Object.keys(value).every(key=>['fps','resolution','quality'].includes(key))&&(value.fps===undefined||[24,30,60].includes(value.fps))&&(value.resolution===undefined||[720,1080,2160].includes(value.resolution))&&(value.quality===undefined||['low','medium','high'].includes(value.quality));
 const fail=message=>assert(false,'MEDIA_TRANSFORM',message);
@@ -49,6 +56,7 @@ export function mediaTransformRequest(value){
    if(!exact(value,['operation','source','settings'])||!ref(value.source,['video'])||!settings(value.settings)||!Object.keys(value.settings).length)fail('video.resize takes a saved video and the render settings to change (fps, resolution, quality)');
    return {operation:value.operation,source:value.source,settings:{fps:30,resolution:1080,quality:'high',...value.settings}};
   }
+  case 'timeline.render':return timelineRender(value);
   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;
@@ -58,7 +66,7 @@ export function mediaTransformRequest(value){
  }
 }
 /** The saved references a request reads. */
-export const mediaTransformSources=request=>request.operation==='video.concat'?request.sources:[request.source];
+export const mediaTransformSources=request=>request.operation==='video.concat'?request.sources: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}={}){
@@ -184,3 +192,35 @@ export function decodeWav(arrayBuffer) {
   }
   return { channels, sampleRate: fmt.sampleRate };
 }
+
+const seconds=value=>Number.isFinite(value)&&value>=0&&value<=MEDIA_TRANSFORM_LIMITS.durationSeconds;
+const span=item=>seconds(item.start)&&Number.isFinite(item.duration)&&item.duration>0&&item.start+item.duration<=MEDIA_TRANSFORM_LIMITS.durationSeconds;
+/** A Block's own timeline, rendered by the Editor's export (its plan, watermark and limits): video or only its audio. */
+function timelineRender(value){
+ if(!exact(value,['operation','clips'],['kind','aspect','audio','captions','settings'])||!Array.isArray(value.clips)||!settings(value.settings))fail('timeline.render takes clips and optional kind, aspect, audio, captions and render settings');
+ const kind=value.kind??'video',aspect=value.aspect??'16:9',audio=value.audio??[],captions=value.captions??[];
+ if(!['video','audio'].includes(kind))fail('kind is video or audio');
+ if(!TIMELINE_ASPECTS.includes(aspect))fail(`aspect is one of ${TIMELINE_ASPECTS.join(', ')}`);
+ if(!Array.isArray(audio)||!Array.isArray(captions))fail('audio and captions are lists');
+ if(value.clips.length>FINAL_RENDER_LIMITS.clips||audio.length>FINAL_RENDER_LIMITS.audioItems||captions.length>FINAL_RENDER_LIMITS.overlays)fail(`At most ${FINAL_RENDER_LIMITS.clips} clips, ${FINAL_RENDER_LIMITS.audioItems} audio items and ${FINAL_RENDER_LIMITS.overlays} captions`);
+ if(kind==='video'?!value.clips.length:!value.clips.length&&!audio.length)fail(kind==='video'?'A video has at least one clip':'Audio needs at least one clip or audio item');
+ const clips=value.clips.map(clip=>{
+  if(!exact(clip,['source','start','duration'],['from','transition','look','mute'])||!ref(clip.source,['image','video'])||!span(clip)||clip.from!==undefined&&!seconds(clip.from)||clip.mute!==undefined&&typeof clip.mute!=='boolean')fail('A clip is {source: a saved image or video, start, duration, from?, transition?, look?, mute?} in seconds');
+  if(clip.transition!==undefined&&(!exact(clip.transition,['type'],['duration'])||!TIMELINE_TRANSITIONS.includes(clip.transition.type)||clip.transition.duration!==undefined&&!(Number.isFinite(clip.transition.duration)&&clip.transition.duration>=0.1&&clip.transition.duration<=3)))fail(`A transition is {type, duration?}: type one of ${TIMELINE_TRANSITIONS.join(', ')}, duration 0.1 to 3 seconds`);
+  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}:{})};
+ });
+ 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};
+ });
+ const lines=captions.map(line=>{
+  if(!exact(line,['text','start','end'],['words','position','highlight','animation'])||typeof line.text!=='string'||!line.text.trim()||line.text.length>500||!seconds(line.start)||!seconds(line.end)||line.end<=line.start)fail('A caption is {text up to 500 characters, start, end, words?, position?, highlight?, animation?}');
+  if(line.words!==undefined&&(!Array.isArray(line.words)||line.words.length>200||!line.words.every(word=>exact(word,['text','start','end'])&&typeof word.text==='string'&&word.text.length<=80&&seconds(word.start)&&seconds(word.end)&&word.end>=word.start)))fail('Caption words are up to 200 {text, start, end}, timed on the timeline');
+  if(line.position!==undefined&&!['bottom','center','top'].includes(line.position))fail('position is bottom, center or top');
+  if(line.highlight!==undefined&&!/^#[0-9a-fA-F]{6}$/.test(line.highlight))fail('highlight is a #rrggbb colour');
+  if(line.animation!==undefined&&!CAPTION_ANIMATIONS.includes(line.animation))fail(`animation is one of ${CAPTION_ANIMATIONS.join(', ')}`);
+  return {text:line.text,start:line.start,end:line.end,position:line.position??'bottom',...(line.words?{words:line.words.map(({text,start,end})=>({text,start,end}))}:{}),...(line.highlight?{highlight:line.highlight}:{}),...(line.animation?{animation:line.animation}:{})};
+ });
+ return {operation:'timeline.render',kind,aspect,clips,audio:sounds,captions:lines,settings:{fps:30,resolution:1080,quality:'high',...(value.settings||{})}};
+}

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

@@ -13,25 +13,11 @@ import {mediaTransformRequest,decodeWav} from './media-transform.js';
 import {mockPng,mockWav,mockMp4,MOCK_IMAGE_SIZE,MOCK_VIDEO_SIZE} from './mock-media.js';
 export {mockPng,mockWav,mockMp4} from './mock-media.js';
 
-export const MOCKS_FILE='tests/mocks.json';
+export {MOCKS_FILE,validateMocks} from './mocks.js';
+import {MOCKS_FILE,validateMocks} from './mocks.js';
 export const MOCK_MEDIA_PREFIX='/api/media/stillmade-mock/';
-const SECTIONS=['hosted','actions','network','connections','files','project','storage','transforms'];
 const fail=(message,code='MOCK_HOST')=>assert(false,code,message);
 
-/** Check a tests/mocks.json value. Every section is optional. */
-export function validateMocks(value){
- if(value===undefined||value===null)return {};
- assert(plain(value)&&Object.keys(value).every(key=>SECTIONS.includes(key)),'MOCK_HOST',`${MOCKS_FILE} has the sections ${SECTIONS.join(', ')}`);
- for(const key of ['hosted','actions','connections','files','storage','transforms'])if(Object.hasOwn(value,key))assert(plain(value[key]),'MOCK_HOST',`${MOCKS_FILE} ${key} is an object`);
- if(Object.hasOwn(value,'network')){
-  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`);
- if(Object.hasOwn(value,'project'))assert(plain(value.project),'MOCK_HOST',`${MOCKS_FILE} project is a project snapshot object`);
- return value;
-}
-
 // A recorded entry may be one value or a list answered in order (the last repeats).
 const pick=(entry,count)=>Array.isArray(entry)&&entry.length?structuredClone(entry[Math.min(count,entry.length-1)]):structuredClone(entry);
 const words=text=>{let at=0;return text.split(/\s+/).filter(Boolean).map(word=>{const start=at;at=Number((at+0.4).toFixed(2));return {text:word,start,end:Number((start+0.35).toFixed(2))};});};
@@ -167,6 +153,7 @@ 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==='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

@@ -0,0 +1,20 @@
+// The shape of recorded host answers (tests/mocks.json, or a module fixture's mocks), checked
+// without loading the stand-in host itself.
+import {assert,plain} from './contracts.js';
+
+export const MOCKS_FILE='tests/mocks.json';
+const SECTIONS=['hosted','actions','network','connections','files','project','storage','transforms'];
+
+/** Check a tests/mocks.json value. Every section is optional. */
+export function validateMocks(value){
+ if(value===undefined||value===null)return {};
+ assert(plain(value)&&Object.keys(value).every(key=>SECTIONS.includes(key)),'MOCK_HOST',`${MOCKS_FILE} has the sections ${SECTIONS.join(', ')}`);
+ for(const key of ['hosted','actions','connections','files','storage','transforms'])if(Object.hasOwn(value,key))assert(plain(value[key]),'MOCK_HOST',`${MOCKS_FILE} ${key} is an object`);
+ if(Object.hasOwn(value,'network')){
+  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`);
+ 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-host-calls.js

@@ -0,0 +1,23 @@
+// The host calls a module Block makes (`stillmade.files.read`, `hosted.run`...), answered by
+// a host object. Shared by the SDK's local Node runner and the QuickJS runner StillMade uses for
+// a built module's tests, so both check permissions and requests the same way.
+import {networkDeclarations,networkRequest,connectionDeclarations,connectionCall} from './network.js';
+import {storageHostHandlers} from './cloud-storage.js';
+import {projectReadSnapshot} from './context.js';
+
+/** {api: args => Promise} for one run of `pkg` against `host` (see createNodeModuleExecutor). */
+export function moduleHostCalls(pkg,host,storage){
+ return {
+  'files.read':args=>host.readFile?host.readFile(args.ref):Promise.reject(Object.assign(new Error('files.read needs a host file reader in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'})),
+  'files.write':args=>host.writeFile?host.writeFile(args.buffer,args.options):Promise.reject(Object.assign(new Error('files.write saves to the StillMade library; pass a host writer in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'})),
+  'media.transform':args=>host.transformMedia?host.transformMedia(args.request):Promise.reject(Object.assign(new Error('Media transforms run in StillMade; pass a host transformMedia in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'})),
+  'actions.run':args=>host.runAction?host.runAction(args.action):Promise.reject(Object.assign(new Error('Actions run in StillMade.'),{code:'MODULE_HOST_UNAVAILABLE'})),
+  'hosted.run':args=>host.runHosted?host.runHosted(args.operation,args.request):Promise.reject(Object.assign(new Error('Hosted operations run in StillMade.'),{code:'MODULE_HOST_UNAVAILABLE'})),
+  'connections.call':async args=>{const request=connectionCall(args.request,connectionDeclarations(pkg.manifest.permissions?.connections));return host.callConnection?host.callConnection(request):Promise.reject(Object.assign(new Error('Connections run through StillMade, which adds your account; pass a host callConnection in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
+  ...storageHostHandlers(storage),
+  'project.read':async args=>{if(!host.project)throw Object.assign(new Error('project.read needs a project snapshot; pass host.project in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'});return projectReadSnapshot(pkg.manifest,host.project,args.fields);},
+  'assets.create':async args=>{if(!(pkg.manifest.permissions?.project||[]).includes('asset.create'))throw Object.assign(new Error('Declare asset.create to add project assets.'),{code:'MODULE_PERMISSION'});return host.createAsset?host.createAsset(args.file,args.options||{}):Promise.reject(Object.assign(new Error('Project assets are saved in StillMade; pass a host createAsset in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
+  'assets.appendVersion':async args=>{if(!(pkg.manifest.permissions?.project||[]).includes('asset.version.append'))throw Object.assign(new Error('Declare asset.version.append to add asset versions.'),{code:'MODULE_PERMISSION'});return host.appendAssetVersion?host.appendAssetVersion(args.asset,args.file):Promise.reject(Object.assign(new Error('Project assets are saved in StillMade; pass a host appendAssetVersion in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
+  'net.fetch':async args=>{const request=networkRequest(args.request,networkDeclarations(pkg.manifest.permissions?.network));return host.netFetch?host.netFetch(request):Promise.reject(Object.assign(new Error('Network calls run through StillMade, which adds your key; pass a host netFetch in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
+ };
+}

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

@@ -3,7 +3,7 @@
 // contract a capability Block declares), so it is priced, quoted, approved,
 // executed and checked exactly like one. The module Block must list the
 // operation in `permissions.capabilities`.
-import {assert,plain} from './contracts.js';
+import {assert,plain,stableStringify} from './contracts.js';
 import {defaultCapabilityExpectations} from './capabilities.js';
 
 const text=(value,max)=>typeof value==='string'&&value.trim().length>0&&value.length<=max;
@@ -80,3 +80,24 @@ export function moduleHostedPackage(source,operation,request){
  const manifest={schemaVersion:1,sdkVersion:'0.1.0',id:`${source.id}.hosted`,version:source.version,name:`${String(source.name||source.id).slice(0,100)} · ${operation}`,description:`A ${operation} call made by ${String(source.name||source.id).slice(0,200)}.`,kind:'task',runtime:'capability',entry:'src/capability.json',license:typeof source.license==='string'?source.license:'MIT',...(source.provenance?{provenance:source.provenance}:{}),inputs:shape.inputs,outputs:shape.outputs,permissions:{project:[],capabilities:[operation],network:[],filesystem:[],secrets:[]},ui:[]};
  return {package:{manifest,capability:{schemaVersion:1,operation,...shape.capability},tests:[{name:'This call',input:shape.input,expectations:defaultCapabilityExpectations(manifest)}]},input:shape.input};
 }
+
+/**
+ * Whether a capability package is exactly the one moduleHostedPackage builds for a module Block's
+ * hosted call: rebuilt from its own fields, it must match in full. Such a call is StillMade's own
+ * shape with the module's words as input, so it needs no paid review before a project run; the
+ * person's press approves its price, as for StillMade's own Blocks (October 22, 2026, owner: no
+ * extra rules because a Block makes model calls). Anything else is not one.
+ */
+export function isModuleHostedPackage(content){
+ try{
+  const operation=content?.capability?.operation,manifest=content?.manifest,suffix=` · ${operation}`;
+  if(!plain(manifest)||typeof manifest.id!=='string'||!manifest.id.endsWith('.hosted')||!Object.hasOwn(SHAPES,operation)||typeof manifest.name!=='string'||!manifest.name.endsWith(suffix))return false;
+  const input=content.tests?.[0]?.input||{},request={};
+  // The request: the capability's own fields, each input reference replaced by the call's value.
+  for(const [key,value] of Object.entries(content.capability))if(!['schemaVersion','operation','output'].includes(key))request[key]=plain(value)&&typeof value.$input==='string'?input[value.$input]:value;
+  if(Number.isFinite(request.settings?.durationSec))request.durationSec=request.settings.durationSec;
+  if(Array.isArray(request.image)){request.images=request.image;delete request.image;}
+  const source={id:manifest.id.slice(0,-'.hosted'.length),version:manifest.version,name:manifest.name.slice(0,-suffix.length),license:manifest.license,...(manifest.provenance?{provenance:manifest.provenance}:{}),permissions:{capabilities:[operation]}};
+  return stableStringify(moduleHostedPackage(source,operation,request).package)===stableStringify(content);
+ }catch{return false;}
+}

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

@@ -7,9 +7,10 @@ import {Worker} from 'node:worker_threads';
 import {assert} from './contracts.js';
 import {MODULE_WORKER_SOURCE} from './module-worker.js';
 import {verifyModuleFile,moduleRunClock,MODULE_LIMITS} from './module-runtime.js';
-import {networkDeclarations,networkRequest,connectionDeclarations,connectionCall} from './network.js';
-import {createMemoryStorage,storageHostHandlers} from './cloud-storage.js';
-import {projectReadSnapshot} from './context.js';
+import {networkDeclarations} from './network.js';
+import {createMemoryStorage} from './cloud-storage.js';
+import {moduleHostCalls} from './module-host-calls.js';
+import {createModuleSockets} from './module-sockets.js';
 
 // The worker global plays the browser Worker's role, so the same globals are removed.
 const workerSource=`const {parentPort}=require('node:worker_threads');
@@ -23,7 +24,10 @@ ${MODULE_WORKER_SOURCE}(globalThis);`;
  * runAction(action), runHosted(operation, request), storage, project,
  * createAsset(file, options), appendAssetVersion(asset, file)}.
  * `storage` defaults to an in-memory store kept for this executor's runs;
- * `project` is the project snapshot `stillmade.project.read` reads from.
+ * `project` is the project snapshot `stillmade.project.read` reads from;
+ * `netConnect(url, protocols, {open, message, close})` opens a live connection
+ * for `stillmade.net.connect` after the declared-origin check and returns
+ * {send(data), close(code, reason)} (without it, live connections are refused).
  */
 export function createNodeModuleExecutor({files,host={},onProgress,onLog,now=()=>Date.now()}={}){
  const storage=host.storage||createMemoryStorage();
@@ -35,20 +39,11 @@ export function createNodeModuleExecutor({files,host={},onProgress,onLog,now=()=
    verified[path]=bytes.buffer.slice(bytes.byteOffset,bytes.byteOffset+bytes.byteLength);
   }
   const worker=new Worker(workerSource,{eval:true,resourceLimits:{maxOldGenerationSizeMb:1024}});
-  const logs=[],clock=moduleRunClock(now);let timer;
-  const handlers={
-   'files.read':args=>host.readFile?host.readFile(args.ref):Promise.reject(Object.assign(new Error('files.read needs a host file reader in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'})),
-   'files.write':args=>host.writeFile?host.writeFile(args.buffer,args.options):Promise.reject(Object.assign(new Error('files.write saves to the StillMade library; pass a host writer in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'})),
-   'media.transform':args=>host.transformMedia?host.transformMedia(args.request):Promise.reject(Object.assign(new Error('Media transforms run in StillMade; pass a host transformMedia in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'})),
-   'actions.run':args=>host.runAction?host.runAction(args.action):Promise.reject(Object.assign(new Error('Actions run in StillMade.'),{code:'MODULE_HOST_UNAVAILABLE'})),
-   'hosted.run':args=>host.runHosted?host.runHosted(args.operation,args.request):Promise.reject(Object.assign(new Error('Hosted operations run in StillMade.'),{code:'MODULE_HOST_UNAVAILABLE'})),
-   'connections.call':async args=>{const request=connectionCall(args.request,connectionDeclarations(pkg.manifest.permissions?.connections));return host.callConnection?host.callConnection(request):Promise.reject(Object.assign(new Error('Connections run through StillMade, which adds your account; pass a host callConnection in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
-   ...storageHostHandlers(storage),
-   'project.read':async args=>{if(!host.project)throw Object.assign(new Error('project.read needs a project snapshot; pass host.project in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'});return projectReadSnapshot(pkg.manifest,host.project,args.fields);},
-   'assets.create':async args=>{if(!(pkg.manifest.permissions?.project||[]).includes('asset.create'))throw Object.assign(new Error('Declare asset.create to add project assets.'),{code:'MODULE_PERMISSION'});return host.createAsset?host.createAsset(args.file,args.options||{}):Promise.reject(Object.assign(new Error('Project assets are saved in StillMade; pass a host createAsset in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
-   'assets.appendVersion':async args=>{if(!(pkg.manifest.permissions?.project||[]).includes('asset.version.append'))throw Object.assign(new Error('Declare asset.version.append to add asset versions.'),{code:'MODULE_PERMISSION'});return host.appendAssetVersion?host.appendAssetVersion(args.asset,args.file):Promise.reject(Object.assign(new Error('Project assets are saved in StillMade; pass a host appendAssetVersion in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
-   'net.fetch':async args=>{const request=networkRequest(args.request,networkDeclarations(pkg.manifest.permissions?.network));return host.netFetch?host.netFetch(request):Promise.reject(Object.assign(new Error('Network calls run through StillMade, which adds your key; pass a host netFetch in local runs.'),{code:'MODULE_HOST_UNAVAILABLE'}));},
-  };
+  const logs=[],clock=moduleRunClock(now);let timer,declared=[];
+  try{declared=networkDeclarations(pkg.manifest.permissions?.network);}catch{/* no valid origins */}
+  const sockets=createModuleSockets({declarations:declared,open:host.netConnect,post:(message,transfer)=>worker.postMessage(message,transfer)});
+  // The shared host calls (files, media, hosted operations, connections, storage, project, assets, net.fetch) plus live connections.
+  const handlers={...sockets.handlers,...moduleHostCalls(pkg,host,storage)};
   try{
    return await new Promise((resolve,reject)=>{
     const stop=error=>{clearInterval(timer);reject(error);};
@@ -62,7 +57,7 @@ export function createNodeModuleExecutor({files,host={},onProgress,onLog,now=()=
      else if(message.type==='progress'){clock.progress();onProgress?.(message);}
      else if(message.type==='log'){if(logs.length<MODULE_LIMITS.logEntries)logs.push(message.message);onLog?.(message.message);}
      else if(message.type==='call'){
-      const handler=handlers[message.api];clock.hostStarted();
+      const handler=Object.hasOwn(handlers,message.api)?handlers[message.api]:null;clock.hostStarted();
       try{const result=await (handler?handler(message.args):Promise.reject(Object.assign(new Error('Unknown host call.'),{code:'MODULE_HOST'})));clock.hostFinished();worker.postMessage({type:'reply',id:message.id,result});}
       catch(error){clock.hostFinished();worker.postMessage({type:'reply',id:message.id,error:{message:String(error?.message||error),code:error?.code||'MODULE_HOST'}});}
      }
@@ -70,6 +65,6 @@ export function createNodeModuleExecutor({files,host={},onProgress,onLog,now=()=
      else if(message.type==='error')stop(Object.assign(new Error(message.message),{code:message.cancelled?'CANCELLED':message.code||'MODULE_ERROR'}));
     });
    });
-  }finally{clearInterval(timer);await worker.terminate();}
+  }finally{clearInterval(timer);sockets.closeAll();await worker.terminate();}
  };
 }

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

@@ -23,7 +23,7 @@ export const MODULE_LIMITS=Object.freeze({
 export const MODULE_MEDIA_TYPES=Object.freeze(['text/javascript','application/wasm','application/json','text/plain','image/png','image/jpeg','image/webp','font/woff2','application/octet-stream']);
 // The host API an entry receives. Each name is a capability: a Block uses only
 // what its manifest permissions allow, and the host checks every call.
-export const MODULE_HOST_API=Object.freeze(['input','signal','progress','log','asset','files.read','files.write','media.transform','actions.run','hosted.run','connections.call','net.fetch','storage.info','storage.list','storage.get','storage.set','storage.remove','storage.putFile','storage.getFile','project.read','assets.create','assets.appendVersion']);
+export const MODULE_HOST_API=Object.freeze(['input','signal','progress','log','asset','files.read','files.write','media.transform','actions.run','hosted.run','connections.call','net.fetch','net.connect','storage.info','storage.list','storage.get','storage.set','storage.remove','storage.putFile','storage.getFile','project.read','assets.create','assets.appendVersion']);
 
 const SHA=/^[a-f0-9]{64}$/;
 const PATH=/^(?!\/)(?!.*\.\.)(?!.*\/\/)[A-Za-z0-9._\/-]+$/;
@@ -31,7 +31,10 @@ const fail=message=>assert(false,'MODULE_PACKAGE',message);
 
 /** Check a module descriptor: `{schemaVersion:1, entry, files:{path:{sha256,bytes,mediaType}}}`. */
 export function validateModuleDescriptor(module){
- if(!plain(module)||Object.keys(module).some(key=>!['schemaVersion','entry','files'].includes(key)))fail('module is {schemaVersion:1, entry, files}');
+ if(!plain(module)||Object.keys(module).some(key=>!['schemaVersion','entry','files','threads'].includes(key)))fail('module is {schemaVersion:1, entry, files, threads?}');
+ // threads: true runs the module in a Worker that can share memory with Workers it starts
+ // (threaded WebAssembly), without WebCodecs, WebGPU or crypto.subtle. See MODULES.md.
+ if(module.threads!==undefined&&module.threads!==true)fail('module.threads is true or left out');
  if(module.schemaVersion!==MODULE_RUNTIME_VERSION)fail('module.schemaVersion must be 1');
  if(!plain(module.files))fail('module.files maps paths to {sha256, bytes, mediaType}');
  const entries=Object.entries(module.files);
@@ -55,13 +58,13 @@ export async function moduleFileDigest(bytes){
 }
 
 /** Build a descriptor from in-memory files ({path: Uint8Array|string}), for the CLI and tests. */
-export async function describeModuleFiles(entry,files,{mediaTypes={}}={}){
+export async function describeModuleFiles(entry,files,{mediaTypes={},threads=false}={}){
  const described={};
  for(const [path,value] of Object.entries(files)){
   const bytes=typeof value==='string'?new TextEncoder().encode(value):value instanceof Uint8Array?value:new Uint8Array(value);
   described[path]={sha256:await moduleFileDigest(bytes),bytes:bytes.byteLength,mediaType:mediaTypes[path]||moduleMediaType(path)};
  }
- const module={schemaVersion:MODULE_RUNTIME_VERSION,entry,files:described};
+ const module={schemaVersion:MODULE_RUNTIME_VERSION,entry,files:described,...(threads===true?{threads:true}:{})};
  validateModuleDescriptor(module);
  return module;
 }

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

@@ -0,0 +1,66 @@
+// The trusted side of stillmade.net.connect for one module run. The Block's
+// sandbox keeps `connect-src 'none'`: the host checks each URL against the
+// declared origins, opens the WebSocket outside the sandbox through `open`, and
+// relays messages both ways, with the count, size and byte limits of
+// SOCKET_LIMITS. Every connection closes when the run ends.
+//
+// open(url, protocols, {open(protocol), message(data), close(code, reason, wasClean)})
+// returns {send(data), close(code, reason)}; `data` is a string or an ArrayBuffer.
+// post(message, transfer) delivers {type:'socket', id, event, ...} to the Worker.
+import {SOCKET_LIMITS,socketRequest} from './network.js';
+
+const fail=(message,code='NETWORK_SOCKET')=>{throw Object.assign(new Error(message),{code});};
+const sizeOf=data=>typeof data==='string'?new TextEncoder().encode(data).byteLength:data instanceof ArrayBuffer?data.byteLength:-1;
+
+export function createModuleSockets({declarations,open,post,limits=SOCKET_LIMITS}){
+ const sockets=new Map();let sequence=0,bytes=0,closed=false;
+ const count=size=>{bytes+=size;return bytes<=limits.runBytes;};
+ const connect=async({request})=>{
+  const checked=socketRequest(request,declarations);
+  if(closed)fail('This run has ended.');
+  if(!open)fail('Live connections are not available in this run.','MODULE_HOST_UNAVAILABLE');
+  if(sockets.size>=limits.sockets)fail(`A run keeps at most ${limits.sockets} live connections open.`,'NETWORK_SOCKET_LIMIT');
+  const id=++sequence;
+  return new Promise((resolve,reject)=>{
+   let opened=false;
+   const entry={socket:null};sockets.set(id,entry);
+   try{entry.socket=open(checked.url,checked.protocols,{
+    open:protocol=>{if(closed||opened)return;opened=true;resolve({id,protocol:String(protocol||'')});},
+    message:data=>{
+     if(closed||!sockets.has(id))return;
+     const size=sizeOf(data);
+     if(size<0)return;
+     if(size>limits.messageBytes){entry.socket.close(1000,'Message too big');return;}
+     if(!count(size)){entry.socket.close(1000,'Run byte limit reached');return;}
+     post({type:'socket',id,event:'message',data},data instanceof ArrayBuffer?[data]:[]);
+    },
+    close:(code,reason,wasClean)=>{
+     if(!sockets.delete(id))return;
+     if(!opened){reject(Object.assign(new Error(`The live connection to ${checked.origin} could not be opened.`),{code:'NETWORK_SOCKET'}));return;}
+     if(!closed)post({type:'socket',id,event:'close',code:Number(code)||1006,reason:String(reason||'').slice(0,123),wasClean:!!wasClean},[]);
+    },
+   });}catch(error){sockets.delete(id);reject(error);}
+  });
+ };
+ const command=async({id,op,data,code,reason})=>{
+  const entry=sockets.get(id);
+  if(!entry?.socket)fail('This live connection is closed.','NETWORK_SOCKET_CLOSED');
+  if(op==='send'){
+   const size=sizeOf(data);
+   if(size<0)fail('net.connect sends text or bytes.');
+   if(size>limits.messageBytes)fail(`A live connection message is at most ${limits.messageBytes/1048576} MiB.`,'NETWORK_SOCKET_LIMIT');
+   if(!count(size))fail(`A run sends and receives at most ${limits.runBytes/1048576} MiB over live connections.`,'NETWORK_SOCKET_LIMIT');
+   entry.socket.send(data);return {sent:size};
+  }
+  if(op==='close'){
+   const closeCode=code===undefined?1000:Number(code);
+   if(!(closeCode===1000||Number.isInteger(closeCode)&&closeCode>=3000&&closeCode<=4999))fail('Close a live connection with code 1000 or 3000 to 4999.');
+   const text=reason===undefined?'':String(reason);
+   if(new TextEncoder().encode(text).byteLength>123)fail('A close reason is at most 123 bytes.');
+   entry.socket.close(closeCode,text);return {closing:true};
+  }
+  fail('Unknown live connection operation.');
+ };
+ const closeAll=()=>{if(closed)return;closed=true;for(const entry of sockets.values())try{entry.socket?.close(1000,'The run ended');}catch{/* closed */}sockets.clear();};
+ return {handlers:{'net.connect':connect,'net.socket':command},closeAll,get open(){return sockets.size;}};
+}