stillmade-sdk 0.0.0-stage → 0.1.0

package/packages/block-platform/catalog.js

@@ -0,0 +1,160 @@
+import {REVENUE_REVIEW_PROJECT_TYPES} from './revenue-review-project-types.js';
+import {PRODUCT_AD_VARIANTS_PROJECT_TYPE,PRIOR_PRODUCT_AD_VARIANTS_PROJECT_TYPE,PREVIOUS_PRODUCT_AD_VARIANTS_PROJECT_TYPE} from './product-ad-variants-project-type.js';
+import {FIRST_PARTY_SDK_PACKAGES} from '../block-sdk/first-party-packages.js';
+import {FIRST_REVENUE_PROJECT_TYPES} from './first-revenue-project-types.js';
+import { SDK_VERSION, ROOT_CHAT_ID } from '../block-sdk/contracts.js';
+import {SCRIPT_WRITER_BLOCK} from './script-writer.js';
+import {VIDEO_ASSETS_BLOCK} from './video-assets.js';
+import {HOST_RELEASE_MANIFEST_SNAPSHOTS} from './host-release-manifests.js';
+// Host releases stay available for saved projects until their complete UI and
+// behavior exist behind portable SDK contracts. Read their manifests from the
+// release directories so an old pin never inherits a newer release's metadata.
+const HOST_RELEASE_MANIFESTS=new Map(HOST_RELEASE_MANIFEST_SNAPSHOTS.map(manifest=>[`${manifest.id}@${manifest.version}`,manifest]));
+const hostReleaseManifest=(id,version)=>{
+ const manifest=HOST_RELEASE_MANIFESTS.get(`${id}@${version}`);
+ if(!manifest)throw new Error(`Missing native host version manifest: ${id}@${version}`);
+ return structuredClone(manifest);
+};
+const definitions = [
+  ['chat', 'Production chat', 'workspace', 'brief', 'script', 'Develop a script or production decision in a scoped conversation after the protected starting chat.', 'ProductionWorkspaceNode.jsx'],
+  ['research', 'Research', 'task', 'text', 'research', 'Find supporting material for a topic and return a research dossier with citations.', 'ProductionWorkspaceNode.jsx'],
+  ['script', 'Script', 'workspace', 'brief', 'script', 'Develop and review a script from the project brief.', 'NarrativeCompiler.jsx'],
+  ['voiceover', 'Voiceover', 'workspace', 'script', 'audio', 'Generate, record, or import narration and prepare it for timed visuals.', 'VoiceoverStep.jsx'],
+  ['transcribe', 'Transcription', 'task', 'audio', 'transcript', 'Turn audio into editable timed words for captions and shot planning.', 'TranscriptionEditor.jsx'],
+  ['shot-plan', 'Shot planning', 'workspace', 'transcript', 'shot-plan', 'Break narration into reviewed shots with visual intent and timing.', 'ShotMapReview.jsx'],
+  ['blueprint', 'Blueprint', 'workspace', 'brief', 'bible', 'Organize the story, cast, locations, and visual style into a reusable production guide.', 'BibleEditor.jsx'],
+  ['character', 'Character reference', 'workspace', 'text', 'character', 'Build a consistent character identity with reusable visual references.', 'CharacterReferenceNode.jsx'],
+  ['location', 'Location reference', 'workspace', 'text', 'location', 'Build a location identity and reference images for consistent settings.', 'LocationReferenceNode.jsx'],
+  ['style', 'Style reference', 'workspace', 'text', 'style', 'Create a reusable art direction and its visual examples.', 'StyleNode.jsx'],
+  ['pipeline', 'Production canvas', 'workspace', 'bible', 'pipeline', 'Arrange production Blocks and generate assets in the Canvas workspace.', 'WorkflowCanvas.jsx'],
+  ['import-media', 'Import media', 'task', null, 'asset[]', 'Bring selected images, video, and audio into the project media library.', 'MediaUploadNode.jsx'],
+  ['generate-image', 'Generate image', 'task', 'text', 'image', 'Generate a new image using a prompt and selected identity or style references.', 'ImageGenNode.jsx'],
+  ['generate-video', 'Generate video', 'task', 'image', 'video', 'Generate a video clip from an image, prompt, and motion settings.', 'VideoGenNode.jsx'],
+  ['thumbnail', 'Thumbnail', 'task', 'text', 'image', 'Create a thumbnail image for the finished video.', 'ThumbnailNode.jsx'],
+  ['describe-media', 'Describe media', 'task', 'image', 'text', 'Describe the visible content of an image for production planning.', 'ImageDescriberNode.jsx'],
+  ['image-editor', 'Image editor', 'workspace', 'image', 'image', 'Crop, adjust, and composite an image while retaining its original version.', 'ProductionWorkspaceNode.jsx'],
+  ['compare', 'Compare assets', 'workspace', 'asset[]', 'asset', 'Review candidate assets and choose a version for the next step.', 'CompareNode.jsx'],
+  ['stock-search', 'Stock media', 'workspace', 'text', 'asset[]', 'Search real-world media and import selected licensed assets.', 'ProductionWorkspaceNode.jsx'],
+  ['panel-strip', 'Image panels', 'workspace', 'audio', 'panel-document', 'Build a timed sequence of consistent images and diagrams around narration.', 'StripStep.jsx'],
+  ['board-editor', 'White Board Motion', 'workspace', 'audio', 'board-document', 'Arrange and animate editable boards with text, media, and narration.', 'CanvasEditorStep.jsx'],
+  ['animated-scene', 'Animated scene', 'workspace', 'shot-plan', 'scene-document', 'Compose animated scenes with object motion and camera direction.', 'AnimatedV2AssetStep.jsx'],
+  ['editor', 'Video editor', 'workspace', 'asset[]', 'timeline', 'Assemble and edit video, audio, captions, and effects on a shared timeline.', 'VideoEditor.jsx'],
+  ['captions', 'Captions', 'editor-extension', 'transcript', 'timeline', 'Place timed editable captions on the selected timeline.', 'editorAI.js'],
+  ['grade', 'Color grade', 'editor-extension', 'timeline-range', 'timeline', 'Adjust the color and tone of selected clips without replacing originals.', 'editorAdds.js'],
+  ['transition', 'Transition', 'editor-extension', 'timeline-range', 'timeline', 'Add a configurable transition at a clip boundary.', 'TransitionNode.jsx'],
+  ['motion-graphics', 'Motion graphics', 'editor-extension', 'timeline-range', 'timeline', 'Add editable titles, figures, graphs, and motion accents to a sequence.', 'FinalEditPanel.jsx'],
+  ['rough-cut', 'AI Rough Cut', 'task', 'timeline', 'timeline', 'Propose a rough cut that aligns available footage with narration.', 'RoughCutPanel.jsx'],
+  ['final-edit', 'AI Final Edit', 'task', 'timeline', 'timeline', 'Propose a polish pass for an existing cut while keeping edits reviewable.', 'FinalEditPanel.jsx'],
+  ['edit-assistant', 'Edit assistant', 'workspace', 'timeline-range', 'timeline', 'Turn a request about a selected range into a reviewable edit proposal.', 'VibeRegionSlider.jsx'],
+  ['score', 'Audio scoring', 'workspace', 'timeline', 'timeline', 'Create and position music and sound effects around the video.', 'AudioScorePanel.jsx'],
+  ['export-video', 'Export video', 'task', 'timeline', 'video', 'Render an accepted timeline to a video file using available device capabilities.', 'exportRender/index.js'],
+  ['export-audio', 'Export audio', 'task', 'timeline', 'audio', 'Mix and export the timeline audio to a standalone file.', 'exportRender/index.js'],
+  ['export-timeline', 'Export timeline', 'task', 'timeline', 'json', 'Export the timeline structure for another editing application.', 'fcpxml.js'],
+  ['youtube', 'YouTube hub', 'workspace', 'video', 'json', 'Analyze channel performance and manage an authorized video upload.', 'YouTubeScreen.jsx'],
+];
+const LEGACY_BLOCKS = definitions.map(([key, name, kind, input, output, description, source]) => ({
+  manifest: { schemaVersion: 1, sdkVersion: SDK_VERSION, id: `sm.${key}`, name, version: '1.0.0', kind, runtime: 'host', description, inputs: input ? { input: { type: input } } : {}, outputs: { output: { type: output } }, permissions: { project: [], network: [], filesystem: [], secrets: [] } },
+  source, summary: { text: description, origin: 'llm', generation: 'build-time', generator: 'Codex', status: 'ready' }, adapterStatus: 'legacy',
+}));
+const types = [
+  ['guided', 'Guided', 'Plan a video from an idea, build references and footage, then edit and export.', ['script', 'voiceover', 'shot-plan', 'blueprint', 'pipeline', 'editor', 'export-video']],
+  ['blank', 'Blank Canvas', 'Start with your own media and production canvas, then assemble a video.', ['import-media', 'pipeline', 'editor', 'export-video']],
+  ['imagePanel', 'Image Panels', 'Turn narration into a timed visual sequence, refine the cut, and export.', ['voiceover', 'panel-strip', 'editor', 'export-video']],
+  ['whiteboard', 'White Board Motion', 'Build animated boards around narration, then refine and export the video.', ['voiceover', 'board-editor', 'editor', 'export-video']],
+  ['animated', 'Animated Studio', 'Plan and compose animated scenes, then assemble and export the sequence.', ['voiceover', 'shot-plan', 'animated-scene', 'editor', 'export-video']],
+];
+const LEGACY_TYPES = types.map(([legacyMode, name, description, stages]) => ({ schemaVersion: 1, id: `sm.${legacyMode.toLowerCase()}`, version: '1.0.0', name, description, legacyMode, stages: stages.map((id, i) => ({ id: `stage-${i + 1}`, blockId: `sm.${id}`, version: '1.0.0', label: LEGACY_BLOCKS.find(b => b.manifest.id === `sm.${id}`).manifest.name })), summary: { text: description, origin: 'llm', generation: 'build-time', generator: 'Codex', status: 'ready' } }));
+
+// The public catalog describes whole production screens. Old component-level
+// adapters remain version-addressable solely for saved workflow compatibility.
+const screens = [
+ ['voiceover','Voiceover','voiceover','VoiceoverStep.jsx','Turn your script into speech, or record your own voice.',['Narration and voices','Recording and import','Transcript and timing']],
+ ['shot-plan','Shots','shotMap','ShotMapReview.jsx','Plan each shot and match it to the voice.',['Shot sequence','Visual directions','Timing and versions']],
+ ['blueprint','Blueprint','bible','BibleEditor.jsx','Keep your story, characters, places, and art style in one place.',['Story and scenes','Characters and locations','Visual direction']],
+ ['pipeline','Canvas','canvas','WorkflowCanvas.jsx','Make images and videos, and keep your characters looking the same.',['Persistent references','Media generation','Assets and versions']],
+ ['editor','Editor','editor','VideoEditor.jsx','Cut clips, add sound and text, then save your video.',['Video and audio timeline','Captions and effects','Export']],
+ ['panel-strip','Image Panels','shotMap','StripStep.jsx','Turn your script into pictures that play with the voice.',['Scenes and panels','Consistent artwork','Timing and editor handoff']],
+ ['board-editor','White Board Motion','canvasEditor','CanvasEditorStep.jsx','Make text and pictures move on a board with a voice.',['Boards and media','Editable animation','Narration and handoff']],
+ ['animated-scene','Assets','assetGen','AnimatedV2AssetStep.jsx','Prepare pictures, objects, and camera moves for your scenes.',['Scenes and assets','Object and camera motion','Editor handoff']],
+];
+const HOST_WORKSPACE_BLOCKS = [SCRIPT_WRITER_BLOCK,...screens.map(([key,name,phase,source,description,features])=>{
+ const legacy=LEGACY_BLOCKS.find(block=>block.manifest.id===`sm.${key}`);
+ const version=key==='editor'?'1.5.0':key==='pipeline'?'1.2.0':'1.1.0';
+ return {...legacy,manifest:hostReleaseManifest(legacy.manifest.id,version),source,workspace:{phase,features},summary:{...legacy.summary,text:description},adapterStatus:'workspace'};
+})];
+HOST_WORKSPACE_BLOCKS.splice(HOST_WORKSPACE_BLOCKS.findIndex(block=>block.manifest.id==='sm.pipeline')+1,0,VIDEO_ASSETS_BLOCK);
+// Promote a portable workspace after its accepted production MVP and rendered
+// acceptance are complete; advanced host extensions can remain on old exact pins. Exact portable releases remain usable as normal
+// Steps before promotion; this map only controls the default production route.
+export const CURRENT_PORTABLE_WORKSPACE_VERSIONS=Object.freeze({'sm.chat':'2.0.3','sm.script':'2.1.4','sm.voiceover':'2.1.4','sm.shot-plan':'2.1.3','sm.blueprint':'2.1.9','sm.pipeline':'2.2.5','sm.video-assets':'2.1.4','sm.panel-strip':'2.3.7','sm.board-editor':'2.2.10','sm.animated-scene':'2.3.8','sm.editor':'2.2.11'});
+export const WORKSPACE_BLOCKS=HOST_WORKSPACE_BLOCKS.map(block=>{
+ const version=CURRENT_PORTABLE_WORKSPACE_VERSIONS[block.manifest.id];
+ if(!version)return block;
+ const portable=FIRST_PARTY_SDK_PACKAGES.find(pkg=>pkg.manifest.id===block.manifest.id&&pkg.manifest.version===version);
+ if(!portable)throw Error(`Missing accepted portable workspace ${block.manifest.id}@${version}`);
+ return portable;
+});
+// Listed for explanation and source access, never installable or placeable.
+export const STARTING_CHAT_BLOCK = {
+ manifest:{schemaVersion:1,sdkVersion:SDK_VERSION,id:ROOT_CHAT_ID,name:'Chat',version:'1.0.0',kind:'workspace',runtime:'host',description:'Plan your video and write the script with AI.',inputs:{},outputs:{},permissions:{project:[],network:[],filesystem:[],secrets:[]}},
+ source:'ChatInterface.jsx',protected:true,workspace:{phase:'chat',features:['Production conversation','Script and planning','Shared project context']},adapterStatus:'protected',
+};
+export const SDK_BUILTIN_BLOCKS = FIRST_PARTY_SDK_PACKAGES;
+// Keep exact host-workspace pins available for saved projects and published
+// Project Types after the current discoverable workspace advances a version.
+const historicalWorkspaceBlock=(id,version)=>{
+ const current=HOST_WORKSPACE_BLOCKS.find(block=>block.manifest.id===id);
+ return {...current,manifest:hostReleaseManifest(id,version)};
+};
+const HISTORICAL_WORKSPACE_BLOCKS = Object.freeze([SCRIPT_WRITER_BLOCK,historicalWorkspaceBlock('sm.script','1.1.0'),historicalWorkspaceBlock('sm.voiceover','1.1.0'),historicalWorkspaceBlock('sm.shot-plan','1.1.0'),historicalWorkspaceBlock('sm.blueprint','1.1.0'),historicalWorkspaceBlock('sm.panel-strip','1.1.0'),historicalWorkspaceBlock('sm.board-editor','1.1.0'),historicalWorkspaceBlock('sm.animated-scene','1.1.0'),historicalWorkspaceBlock('sm.editor','1.1.0'),historicalWorkspaceBlock('sm.editor','1.2.0'),historicalWorkspaceBlock('sm.editor','1.3.0'),historicalWorkspaceBlock('sm.editor','1.4.0'),historicalWorkspaceBlock('sm.editor','1.5.0'),historicalWorkspaceBlock('sm.pipeline','1.1.0'),historicalWorkspaceBlock('sm.pipeline','1.2.0'),VIDEO_ASSETS_BLOCK,historicalWorkspaceBlock('sm.video-assets','1.0.0'),historicalWorkspaceBlock('sm.video-assets','1.1.0')]);
+const DESCRIBE_MEDIA_HOST_1_1=(()=>{const legacy=LEGACY_BLOCKS.find(block=>block.manifest.id==='sm.describe-media');return {...legacy,manifest:{...legacy.manifest,version:'1.1.0'},adapterStatus:'module'};})();
+const YOUTUBE_HOST_1_1=(()=>{const legacy=LEGACY_BLOCKS.find(block=>block.manifest.id==='sm.youtube');return {...legacy,manifest:{...legacy.manifest,version:'1.1.0',description:'Review channel performance and upload an account-owned saved MP4 through a retained authorized session.'},adapterStatus:'workspace'};})();
+const GENERATION_HOST_RELEASES=Object.freeze(['sm.generate-image','sm.generate-video','sm.thumbnail','sm.compare'].flatMap(id=>{
+ const legacy=LEGACY_BLOCKS.find(block=>block.manifest.id===id);
+ return ['1.1.0','1.2.0'].map(version=>({...legacy,manifest:{...legacy.manifest,version},adapterStatus:'module'}));
+}));
+// Every independently executable first-party release is visible in the
+// Marketplace. Workspace releases remain the full-screen creation experience;
+// SDK releases remain removable, version-pinned building blocks.
+// Publish one current portable release per Block identity. Older portable
+// releases remain in BUILTIN_BLOCKS for exact installed/project pins and their
+// version pages, but do not compete with their successor in current discovery.
+const semverParts=version=>String(version).split(/[.-]/).slice(0,3).map(value=>Number(value)||0);
+const newer=(left,right)=>{const a=semverParts(left),b=semverParts(right);for(let i=0;i<3;i++){if(a[i]!==b[i])return a[i]>b[i];}return false;};
+const currentPortableById=new Map();
+for(const block of SDK_BUILTIN_BLOCKS){const prior=currentPortableById.get(block.manifest.id);if(!prior||newer(block.manifest.version,prior.manifest.version))currentPortableById.set(block.manifest.id,block);}
+export const DISCOVERABLE_SDK_BUILTIN_BLOCKS = Object.freeze([...currentPortableById.values()]);
+export const DISCOVERABLE_BLOCKS = [STARTING_CHAT_BLOCK,...WORKSPACE_BLOCKS,...DISCOVERABLE_SDK_BUILTIN_BLOCKS.filter(block=>!WORKSPACE_BLOCKS.some(current=>current.manifest.id===block.manifest.id&&current.manifest.version===block.manifest.version))];
+export const BUILTIN_BLOCKS = [STARTING_CHAT_BLOCK,...WORKSPACE_BLOCKS,...HISTORICAL_WORKSPACE_BLOCKS,DESCRIBE_MEDIA_HOST_1_1,YOUTUBE_HOST_1_1,...GENERATION_HOST_RELEASES,...SDK_BUILTIN_BLOCKS.filter(block=>!WORKSPACE_BLOCKS.some(current=>current.manifest.id===block.manifest.id&&current.manifest.version===block.manifest.version)),...LEGACY_BLOCKS];
+const flows={guided:['voiceover','shot-plan','blueprint','pipeline','editor'],blank:['pipeline','editor'],imagePanel:['voiceover','panel-strip','editor'],whiteboard:['voiceover','board-editor','editor'],animated:['voiceover','shot-plan','animated-scene','editor']};
+const typeDescriptions={
+ guided:'Turn an idea into a video, from the script to the final cut.',
+ blank:'Start with your own pictures and clips, then make a video.',
+ imagePanel:'Make a video with still pictures and a voice.',
+ whiteboard:'Make a video with moving text, pictures, and a voice.',
+ animated:'Build scenes with moving objects, then put them into a video.',
+};
+// Freeze the actual pre-collaboration-release catalog fallback. Historical type
+// definitions must not follow future changes to the discoverable Block map.
+const PINNED_TYPE_WORKSPACE_VERSIONS=Object.freeze({'voiceover':'2.1.3','shot-plan':'2.1.2','blueprint':'2.1.7','pipeline':'2.2.2','editor':'2.2.7','panel-strip':'2.3.5','board-editor':'2.2.8','animated-scene':'2.3.6'});
+const currentBuiltinTypes=(version,pipelineVersion,scriptVersion=SCRIPT_WRITER_BLOCK.manifest.version,versions={})=>LEGACY_TYPES.map(type=>({...type,description:typeDescriptions[type.legacyMode],summary:{...type.summary,text:typeDescriptions[type.legacyMode]},version,stages:flows[type.legacyMode].map((key,i)=>{const block=WORKSPACE_BLOCKS.find(block=>block.manifest.id===`sm.${key}`);return {id:`stage-${i+1}`,blockId:block.manifest.id,version:versions[key]||(key==='pipeline'?pipelineVersion:key==='script'?scriptVersion:PINNED_TYPE_WORKSPACE_VERSIONS[key]),label:block.manifest.name};})}));
+const PRIOR_HOST_WORKSPACE_VERSIONS={'shot-plan':'1.1.0','blueprint':'1.1.0','panel-strip':'2.3.4','board-editor':'1.1.0','animated-scene':'1.1.0'};
+const PREVIOUS_BUILTIN_TYPES=currentBuiltinTypes('1.2.0','1.2.0',SCRIPT_WRITER_BLOCK.manifest.version,PRIOR_HOST_WORKSPACE_VERSIONS);
+const SHOTS_MIGRATED_TYPES=currentBuiltinTypes('1.3.0','1.2.0',SCRIPT_WRITER_BLOCK.manifest.version,{'blueprint':'1.1.0','board-editor':'1.1.0','animated-scene':'1.1.0'});
+const PRE_PROMOTION_CURRENT_TYPES = PREVIOUS_BUILTIN_TYPES.map(type=>flows[type.legacyMode].includes('shot-plan')?SHOTS_MIGRATED_TYPES.find(next=>next.id===type.id):type);
+const PORTABLE_MVP_TYPES = currentBuiltinTypes('1.4.0','2.2.2',SCRIPT_WRITER_BLOCK.manifest.version,{'blueprint':'2.1.5','panel-strip':'2.3.4','board-editor':'2.2.6','animated-scene':'2.3.4'});
+const ADVANCED_PORTABLE_TYPES = currentBuiltinTypes('1.5.0','2.2.2',SCRIPT_WRITER_BLOCK.manifest.version,{'blueprint':'2.1.6','panel-strip':'2.3.4','board-editor':'2.2.7','animated-scene':'2.3.5','editor':'2.2.4'});
+const PLAYABLE_EDITOR_TYPES = currentBuiltinTypes('1.6.0','2.2.2',SCRIPT_WRITER_BLOCK.manifest.version,{'blueprint':'2.1.6','panel-strip':'2.3.4','board-editor':'2.2.7','animated-scene':'2.3.5','editor':'2.2.5'});
+const EDITOR_AUDIO_TYPES = currentBuiltinTypes('1.7.0','2.2.2',SCRIPT_WRITER_BLOCK.manifest.version,{'blueprint':'2.1.6','panel-strip':'2.3.4','board-editor':'2.2.7','animated-scene':'2.3.5','editor':'2.2.6'});
+const MEDIA_LIBRARY_TYPES = currentBuiltinTypes('1.8.0','2.2.2',SCRIPT_WRITER_BLOCK.manifest.version,{'panel-strip':'2.3.4'});
+const PRIOR_SHARED_TYPES = currentBuiltinTypes('1.9.0','2.2.2');
+const SHARED_BLUEPRINT_TYPES = currentBuiltinTypes('1.10.0','2.2.2',SCRIPT_WRITER_BLOCK.manifest.version,{'blueprint':'2.1.8'});
+const SHARED_CANVAS_TYPES = currentBuiltinTypes('1.11.0','2.2.3',SCRIPT_WRITER_BLOCK.manifest.version,{'blueprint':'2.1.8'});
+const SHARED_WORKSPACE_TYPES = currentBuiltinTypes('1.12.0','2.2.3',SCRIPT_WRITER_BLOCK.manifest.version,{'blueprint':'2.1.8','panel-strip':'2.3.6','board-editor':'2.2.9','animated-scene':'2.3.7'});
+const PRIOR_CURRENT_TYPES = currentBuiltinTypes('1.13.0','2.2.3',SCRIPT_WRITER_BLOCK.manifest.version,{'blueprint':'2.1.8','panel-strip':'2.3.6','board-editor':'2.2.9','animated-scene':'2.3.7','editor':'2.2.8'});
+const PREVIOUS_PORTABLE_TYPES=currentBuiltinTypes('1.14.0','2.2.4',SCRIPT_WRITER_BLOCK.manifest.version,{'blueprint':'2.1.8','panel-strip':'2.3.6','board-editor':'2.2.9','animated-scene':'2.3.7','editor':'2.2.8'});
+export const CURRENT_BUILTIN_TYPES = [...currentBuiltinTypes('1.15.0','2.2.4','2.1.4',{'voiceover':'2.1.4','shot-plan':'2.1.3','blueprint':'2.1.9','panel-strip':'2.3.7','board-editor':'2.2.10','animated-scene':'2.3.8','editor':'2.2.9'}),...REVENUE_REVIEW_PROJECT_TYPES,PRODUCT_AD_VARIANTS_PROJECT_TYPE,...FIRST_REVENUE_PROJECT_TYPES];
+const HISTORICAL_CURRENT_TYPES=[PRIOR_PRODUCT_AD_VARIANTS_PROJECT_TYPE,PREVIOUS_PRODUCT_AD_VARIANTS_PROJECT_TYPE,...PREVIOUS_PORTABLE_TYPES,...PRIOR_CURRENT_TYPES,...SHARED_WORKSPACE_TYPES,...SHARED_CANVAS_TYPES,...SHARED_BLUEPRINT_TYPES,...PRIOR_SHARED_TYPES,...MEDIA_LIBRARY_TYPES,...EDITOR_AUDIO_TYPES,...PLAYABLE_EDITOR_TYPES,...ADVANCED_PORTABLE_TYPES,...PORTABLE_MVP_TYPES,...PRE_PROMOTION_CURRENT_TYPES,...PREVIOUS_BUILTIN_TYPES.filter(type=>flows[type.legacyMode].includes('shot-plan')),...currentBuiltinTypes('1.1.0','1.1.0','1.1.0',PRIOR_HOST_WORKSPACE_VERSIONS)];
+export const BUILTIN_TYPES = [...CURRENT_BUILTIN_TYPES,...HISTORICAL_CURRENT_TYPES,...LEGACY_TYPES];
+export const workspaceBlock = (id,version)=>DISCOVERABLE_BLOCKS.find(block=>block.manifest.id===id && (!version || block.manifest.version===version));
+export const discoverableBuiltin = item=>!!workspaceBlock((item.manifest || item).id,(item.manifest || item).version);

package/packages/block-platform/chat-requirements.js

@@ -0,0 +1,42 @@
+import {auditProjectTypeConnections} from './project-type-composer.js';
+
+export function projectTypeRequirementsForChat(type,catalog=[],{currentStage,contextValues=[]}={}) {
+  if(!type)return undefined;
+  const values=contextValues.map(value=>value.source?.kind==='block'?{...value,source:{...value.source,stageId:value.source.stepId || value.source.stageId}}:value);
+  const audit=auditProjectTypeConnections(type,catalog,{contextValues:values}),enabled=audit.stages.filter(step=>!step.paused),steps=[];
+  const currentIndex=enabled.findIndex(step=>step.id===currentStage);
+  const relevant=currentIndex<0?enabled:[...enabled.slice(currentIndex),...enabled.slice(0,currentIndex).reverse()];
+  const projectContext=[],availableAdapters=[],seenValues=new Set(),seenAdapters=new Set();
+  const candidatesFor=decision=>decision.resolverCandidates || decision.candidates;
+  const summarizeSource=candidate=>candidate?{kind:String(candidate.kind || candidate.record?.source?.kind || 'unknown').slice(0,40),stepId:candidate.record?.source?.stageId?String(candidate.record.source.stageId).slice(0,160):null,port:candidate.record?.source?.port?String(candidate.record.source.port).slice(0,160):null,materialized:!!candidate.record && Object.hasOwn(candidate.record,'value'),adapter:candidate.adapter?{id:String(candidate.adapter.id).slice(0,160),version:String(candidate.adapter.version).slice(0,80)}:null,...(candidate.conversionBlock?{converter:{id:String(candidate.conversionBlock.id).slice(0,160),version:String(candidate.conversionBlock.version).slice(0,80),input:String(candidate.conversionBlock.input).slice(0,160),output:String(candidate.conversionBlock.output).slice(0,160)}}:{})}:null;
+  const blocking=audit.issues.filter(issue=>issue.state!=='needs-user-input');
+  const issues=blocking.slice(0,10).map(issue=>({stageId:issue.stageId?String(issue.stageId).slice(0,160):null,message:String(issue.reason || issue.message).slice(0,240)}));
+  let size=4500+JSON.stringify(issues).length,metadataSize=0,truncated=blocking.length>issues.length || blocking.some(issue=>String(issue.reason || issue.message).length>240 || String(issue.stageId || '').length>160);
+  for(const step of relevant) {
+    const row={id:String(step.id).slice(0,160),label:String(step.label).slice(0,160),upcoming:currentIndex<0 || enabled.indexOf(step)>=currentIndex,requirements:step.requirements.slice(0,12).map(decision=>({key:String(decision.key || decision.requirement.key).slice(0,160),description:String(decision.requirement.description || '').slice(0,200),semantic:String(decision.requirement.semantic || '').slice(0,160),type:decision.requirement.type,required:decision.requirement.required,state:decision.state,reason:String(decision.reason || '').slice(0,240),source:summarizeSource(decision.selected),candidates:candidatesFor(decision).slice(0,3).map(summarizeSource)}))};
+    row.state=step.state;
+    const issue=step.contractIssue?.message || step.connectionIssues?.[0]?.message;
+    if(issue)row.issue=String(issue).slice(0,240);
+    let length=JSON.stringify(row).length;
+    while(size+length>16000 && row.requirements.length>1){row.requirements.pop();length=JSON.stringify(row).length;truncated=true;}
+    if(steps.length>=20 || size+length>16000){truncated=true;break;}
+    if(step.requirements.length>12 || step.requirements.some(decision=>candidatesFor(decision).length>3))truncated=true;
+    steps.push(row);size+=length;
+    for(const decision of step.requirements.slice(0,row.requirements.length))for(const candidate of [decision.selected,...candidatesFor(decision)].filter(Boolean)) {
+      const record=candidate.record;
+      if(record?.id && Object.hasOwn(record,'value') && !seenValues.has(record.id)) {
+        seenValues.add(record.id);
+        const entry={id:String(record.id).slice(0,160),type:String(record.type || '').slice(0,80),semantic:String(record.semantic || record.role || '').slice(0,160),source:summarizeSource(candidate)};
+        const length=JSON.stringify(entry).length;
+        if(projectContext.length<20 && metadataSize+length<=4000){projectContext.push(entry);metadataSize+=length;}else truncated=true;
+      }
+      if(candidate.adapter) {
+        const entry={id:String(candidate.adapter.id).slice(0,160),version:String(candidate.adapter.version).slice(0,80),stepId:row.id,requirement:String(decision.key || decision.requirement.key).slice(0,160)},identity=JSON.stringify(entry);
+        if(seenAdapters.has(identity))continue;
+        seenAdapters.add(identity);
+        if(availableAdapters.length<20 && metadataSize+identity.length<=4000){availableAdapters.push(entry);metadataSize+=identity.length;}else truncated=true;
+      }
+    }
+  }
+  return {schemaVersion:1,projectType:{id:String(type.id || 'draft').slice(0,160),name:String(type.name || 'Project Type').slice(0,160)},currentStage:currentIndex<0?null:String(currentStage).slice(0,160),steps,issues,projectContext,availableAdapters,acceptanceCriteria:(type.acceptanceCriteria||[]).slice(0,24).map(item=>({...item,verified:false})),totalSteps:enabled.length,truncated};
+}

package/packages/block-platform/collaboration.js

@@ -0,0 +1,187 @@
+import {validateVoiceoverDocument} from './voiceover.js';
+import {isKeyed} from '../block-sdk/document-operations.js';
+import { assert, plain, safeDocument, stableStringify } from '../block-sdk/contracts.js';
+import {validateProjectType} from './project-types.js';
+import {BUILTIN_BLOCKS} from './catalog.js';
+import {compileTypeWorkspace} from './type-workspace.js';
+import {createSemanticContext} from './semantic-context.js';
+const EPHEMERAL = new Set(['playhead', 'selection', 'timelineSettings', 'panelState', 'selectedClipId', 'selectedIds', 'playing', 'isPlaying']);
+export function readOnlyEditorUpdate(previous, candidate) {
+  let next = previous;
+  for (const key of EPHEMERAL) {
+    if (Object.hasOwn(candidate, key) && !Object.is(previous[key], candidate[key])) {
+      if (next === previous) next = { ...previous };
+      next[key] = candidate[key];
+    }
+  }
+  return next;
+}
+export function sharedEditor(editor, scope = 'editor') {
+  if(scope === 'chat')return {messages:structuredClone(editor?.messages || [])};
+  if(scope === 'animation')return {scenes:(editor?.scenes || []).map(scene=>({...JSON.parse(JSON.stringify(scene)),id:scene.shotId}))};
+  if(scope === 'shots')return {shots:structuredClone(editor?.shots || [])};
+  if(scope === 'script')return {script:typeof editor?.script === 'string' ? editor.script : ''};
+  if(scope === 'blueprint')return {bible:structuredClone(editor?.bible || {})};
+  if ((scope === 'board' || scope === 'panels')) {
+    const clean = JSON.parse(JSON.stringify(editor || {}));
+    assert(plain(clean) && Array.isArray(clean.strip || []), 'DOCUMENT', 'Board document needs a strip array');
+    return { ...clean, strip: (clean.strip || []).map(panel => { assert(plain(panel) && typeof panel.panelId === 'string', 'DOCUMENT', 'Board needs a panel ID'); return { ...panel, id: panel.panelId }; }) };
+  }
+  if (scope === 'canvas') return { ...(editor?.semanticContext !== undefined ? {semanticContext:structuredClone(editor.semanticContext)} : {}), ...(editor?.projectType !== undefined ? {projectType:structuredClone(editor.projectType)} : {}), ...(editor?.projectScanDismissals !== undefined ? {projectScanDismissals:structuredClone(editor.projectScanDismissals)} : {}), workflowArchive:JSON.parse(JSON.stringify(editor?.workflowArchive || [])), nodes: (editor?.nodes || []).map(({ selected, dragging, measured, resizing, ...node }) => JSON.parse(JSON.stringify(node))), edges: (editor?.edges || []).map(({ selected, ...edge }) => JSON.parse(JSON.stringify(edge))) };
+  return Object.fromEntries(Object.entries(editor || {}).filter(([k, v]) => !EPHEMERAL.has(k) && v !== undefined).map(([k, v]) => [k, structuredClone(v)]));
+}
+export {diffDocument,applyOperations} from '../block-sdk/document-operations.js';
+
+// Retain React identities for untouched values when a remote document arrives.
+// This work runs at synchronization boundaries, never in pointer handlers.
+export function reconcileShared(previous, incoming) {
+  if (Object.is(previous, incoming)) return previous;
+  if (Array.isArray(previous) && Array.isArray(incoming)) {
+    const keyed = isKeyed(previous) && isKeyed(incoming);
+    const byId = keyed ? new Map(previous.map(value => [value.id, value])) : null;
+    const next = incoming.map((value, i) => reconcileShared(keyed ? byId.get(value.id) : previous[i], value));
+    return next.length === previous.length && next.every((value, i) => value === previous[i]) ? previous : next;
+  }
+  if (plain(previous) && plain(incoming)) {
+    const next = Object.fromEntries(Object.entries(incoming).map(([key, value]) => [key, reconcileShared(previous[key], value)]));
+    return Object.keys(previous).length === Object.keys(next).length && Object.entries(next).every(([key, value]) => Object.hasOwn(previous, key) && value === previous[key]) ? previous : next;
+  }
+  return incoming;
+}
+export function mergeLiveDocument(local, remote, scope = 'editor') {
+  if(scope === 'animation')return reconcileShared(local,{scenes:remote.scenes.map(({id,...scene})=>scene)});
+  if ((scope === 'board' || scope === 'panels')) return reconcileShared(local, { ...remote, strip: remote.strip.map(({ id, ...panel }) => panel) });
+  if (scope === 'canvas') {
+    const selected = new Map((local.nodes || []).map(n => [n.id, n]));
+    const edges = new Map((local.edges || []).map(e => [e.id, e]));
+    return reconcileShared(local, { ...local, ...(remote.semanticContext !== undefined ? {semanticContext:remote.semanticContext} : {}), ...(remote.projectType !== undefined ? {projectType:remote.projectType} : {}), ...(remote.projectScanDismissals !== undefined ? {projectScanDismissals:remote.projectScanDismissals} : {}), ...(remote.workflowArchive ? {workflowArchive:remote.workflowArchive} : {}), nodes: remote.nodes.map(n => ({ ...n, selected: !!selected.get(n.id)?.selected, ...(selected.get(n.id)?.dragging ? { dragging: true } : {}), ...(selected.get(n.id)?.resizing ? { resizing: true } : {}), ...(selected.get(n.id)?.measured ? { measured: selected.get(n.id).measured } : {}) })), edges: remote.edges.map(e => ({ ...e, selected: !!edges.get(e.id)?.selected })) });
+  }
+  const result = { ...local, ...remote };
+  for (const key of Object.keys(sharedEditor(local))) if (!Object.hasOwn(remote, key)) delete result[key];
+  return reconcileShared(local, result);
+}
+
+export function validateLiveDocument(document, scope = 'editor', {experimentalBrowser} = {}) {
+  safeDocument(document);
+  assert(plain(document), 'DOCUMENT', 'Shared workspace must be an object');
+  const collection = (items, name, maximum) => {
+    assert(Array.isArray(items) && items.length <= maximum && isKeyed(items) && items.every(item => item.id.length > 0 && item.id.length <= 200), 'DOCUMENT', `Invalid ${name} collection`);
+  };
+  if(scope === 'chat') {
+    assert(Object.keys(document).length===1&&Array.isArray(document.messages)&&document.messages.length<=2000,'DOCUMENT','Chat scope accepts up to 2,000 messages');
+    for(const message of document.messages)assert(plain(message)&&['user','assistant','system'].includes(message.role)&&typeof message.content==='string'&&message.content.length<=200000,'DOCUMENT','Chat messages need a role and text');
+  } else if(scope === 'animation') {
+    assert(Object.keys(document).length===1,'DOCUMENT','Animation scope accepts only its scene collection');
+    collection(document.scenes,'animated scenes',1000);
+    for(const item of document.scenes){
+      assert(item.id===item.shotId && plain(item.scene),'DOCUMENT','Animated scenes need a shot identity and scene document');
+      assert(Number.isFinite(item.start)&&Number.isFinite(item.end)&&item.start>=0&&item.end>item.start&&item.end<=86400,'DOCUMENT','Animated scenes need valid start and end times');
+      assert(item.versions===undefined||Array.isArray(item.versions),'DOCUMENT','Scene versions must be an array');
+    }
+  } else if(scope === 'voiceover') {
+    validateVoiceoverDocument(document);
+  } else if(scope === 'shots') {
+    assert(Object.keys(document).length === 1,'DOCUMENT','Shot planning scope accepts only its shot collection');
+    collection(document.shots,'shots',2000);
+  } else if(scope === 'script') {
+    assert(Object.keys(document).length === 1 && typeof document.script === 'string' && document.script.length <= 200000,'DOCUMENT','Script scope accepts only narration text up to 200,000 characters');
+  } else if(scope === 'blueprint') {
+    assert(Object.keys(document).length === 1 && plain(document.bible),'DOCUMENT','Blueprint scope accepts only its production bible');
+  } else if ((scope === 'board' || scope === 'panels')) {
+    collection(document.strip, 'boards', 1000);
+    for (const panel of document.strip) assert(panel.panelId === panel.id && (scope === 'panels' || typeof panel.type === 'string'), 'DOCUMENT', 'Board identity must match its panel ID');
+  } else if (scope === 'canvas') {
+    assert(Object.keys(document).every(key => ['nodes','edges','workflowArchive','projectType','semanticContext','projectScanDismissals'].includes(key)), 'DOCUMENT', 'Invalid shared canvas field');
+    if(document.projectScanDismissals!==undefined){
+      assert(Array.isArray(document.projectScanDismissals)&&document.projectScanDismissals.length<=100,'DOCUMENT','Too many dismissed project suggestions');
+      const keys=new Set();
+      for(const item of document.projectScanDismissals){
+        assert(plain(item)&&Object.keys(item).every(key=>['id','signature'].includes(key))&&typeof item.id==='string'&&item.id.length<=500&&typeof item.signature==='string'&&item.signature.length<=20000,'DOCUMENT','Invalid dismissed project suggestion');
+        const key=`${item.signature}:${item.id}`;assert(!keys.has(key),'DOCUMENT','Duplicate dismissed project suggestion');keys.add(key);
+      }
+    }
+    if (document.projectType !== undefined) {
+      const result=validateProjectType(document.projectType,BUILTIN_BLOCKS,{experimentalBrowser});
+      assert(result.valid,'DOCUMENT',`Invalid shared Project Type: ${result.errors.map(error=>error.message).join(' ')}`);
+    }
+    collection(document.nodes,'nodes',5000); collection(document.edges,'edges',10000);
+    if(document.semanticContext !== undefined) {
+      const context=document.semanticContext;
+      assert(plain(context) && context.schemaVersion===1 && Array.isArray(context.values) && context.values.length<=2000,'DOCUMENT','Invalid shared project information');
+      const values=[...context.values];
+      for(const node of document.nodes)for(const key of ['blockSemanticResults','blockSemanticAnswers']) {
+        if(node.data?.[key]===undefined)continue;
+        assert(Array.isArray(node.data[key]) && values.length+node.data[key].length<=10000,'DOCUMENT','Invalid or oversized Block information collection');
+        values.push(...node.data[key]);
+      }
+      assert(values.length<=10000,'DOCUMENT','Too many shared project values');
+      createSemanticContext({schemaVersion:1,values});
+    }
+    // Removed/replaced placements are data-only history, outside the runnable
+    // graph. Synchronize by entry ID so different teammates' appends coexist.
+    if (document.workflowArchive !== undefined) {
+      collection(document.workflowArchive, 'workflow history', 2000);
+      for (const item of document.workflowArchive) {
+        assert(['removed','disabled','replaced','configured','reordered','connections'].includes(item.reason) && typeof item.at === 'string' && Number.isFinite(Date.parse(item.at)), 'DOCUMENT', 'Workflow history needs a reason and timestamp');
+        assert(plain(item.step) && typeof item.step.id === 'string' && item.step.id.length > 0 && typeof item.step.blockId === 'string' && typeof item.step.version === 'string' && Number.isInteger(item.index) && item.index >= 0, 'DOCUMENT', 'Workflow history needs its previous placement');
+        assert(item.node === null || plain(item.node) && typeof item.node.id === 'string' && plain(item.node.data), 'DOCUMENT', 'Workflow history needs a saved instance');
+        collection(item.edges, 'workflow history connections', 10000);
+      }
+    }
+    const ids=new Set(document.nodes.map(node => node.id));
+    for (const node of document.nodes) assert(typeof node.type === 'string' && node.type.length <= 100 && plain(node.data) && plain(node.position) && Number.isFinite(node.position.x) && Number.isFinite(node.position.y), 'DOCUMENT', 'Node needs a type, data and finite position');
+    for (const edge of document.edges) assert(ids.has(edge.source) && ids.has(edge.target), 'CONFLICT', 'Connected node was removed; reload the shared canvas');
+  } else {
+    const editorCollections=['clips','audioItems','captions','stickers','textOverlays','zooms','effects','markers','fxEvents','liveOverlays','mediaItems','tracks','timelineVersions'];
+    for (const key of editorCollections) if (Object.hasOwn(document,key)) collection(document[key],key,10000);
+    if(scope==='editor')assert(typeof document.activeTimelineId==='string'&&document.activeTimelineId.length>0&&document.activeTimelineId.length<=200,'DOCUMENT','Editor needs an active timeline identity');
+  }
+  return document;
+}
+
+// Runs at trusted synchronization boundaries, never executes package code.
+// Ordinary Canvas edits may remove an item; an explicit workflow handoff must
+// contain every required instance so its definition and graph form one commit.
+// The optional application context is an opaque trusted-host capability. It
+// validates already hydrated exact source only; no serializable document flag
+// opens admission, reads artifacts, verifies retained records or grants access.
+// Existing server save routes do not supply it and remain closed to this runtime.
+export async function validateCanvasWorkflowPair(document,{previous,complete=false,experimentalBrowser}={}) {
+  validateLiveDocument(document,'canvas',{experimentalBrowser});
+  if(document.projectType === undefined) {assert(!complete,'DOCUMENT','A workflow handoff requires its Project Type');return document;}
+  const type=document.projectType;
+  for(const [index,old] of (previous?.projectType?.packages||[]).entries())
+    assert(stableStringify(type.packages?.[index])===stableStringify(old),'VERSION','A saved package changed or moved. Keep existing package slots unchanged and append any newly reviewed release.');
+  const {canvas}=await compileTypeWorkspace(type,{experimentalBrowser}),expected=new Map(canvas.nodes.map(node=>[node.id,node])),actual=new Map(document.nodes.map(node=>[node.id,node]));
+  for(const [id,node] of expected) {
+    const current=actual.get(id);
+    assert(current || !complete,'CONFLICT','The workflow is missing a required Block instance. Reload the project before applying it.');
+    if(!current)continue;
+    const sourceMatches=current.type===node.type && (node.type==='programmableBlockNode'
+      ? current.data.blockDigest===node.data.blockDigest && stableStringify(current.data.blockPackage ?? null)===stableStringify(node.data.blockPackage)
+      : stableStringify(current.data.hostBlock ?? null)===stableStringify(node.data.hostBlock));
+    assert(sourceMatches,'CONFLICT','The workflow and Canvas contain different pinned Block source. Reload the project before applying it.');
+  }
+  if(complete)for(const node of document.nodes)assert(!node.id.startsWith('type-stage-') || !(node.type==='programmableBlockNode' || node.data.hostBlock?.stageId) || expected.has(node.id),'CONFLICT','The Canvas still contains a removed workflow Block. Reload the project before applying it.');
+  if(complete)for(const edge of canvas.edges) {
+    const producers=document.edges.filter(item=>item.target===edge.target && item.targetHandle===edge.targetHandle);
+    assert(producers.length===1 && producers[0].source===edge.source && producers[0].sourceHandle===edge.sourceHandle && stableStringify(producers[0].data?.stillmadeAdapter ?? null)===stableStringify(edge.data?.stillmadeAdapter ?? null),'CONFLICT','The Canvas connections and conversion versions do not match the workflow. Reload the project before applying it.');
+  }
+  return document;
+}
+
+// Viewers may select and measure existing graph items, but cannot mutate shared
+// fields, insert/remove items or change their order. Preserve untouched identity.
+export function readOnlyCanvasItems(previous, candidate) {
+  const incoming = new Map((Array.isArray(candidate) ? candidate : []).map(item => [item.id,item]));
+  let changed = false;
+  const next = previous.map(item => {
+    const update = incoming.get(item.id);
+    if (!update) return item;
+    const patch = {};
+    for (const key of ['selected','measured']) if (Object.hasOwn(update,key) && update[key] !== item[key]) patch[key] = update[key];
+    if (!Object.keys(patch).length) return item;
+    changed = true; return {...item,...patch};
+  });
+  return changed ? next : previous;
+}

package/packages/block-platform/conditions.js

@@ -0,0 +1,61 @@
+import {assert,plain,compatible,valueMatches,validateValues,stableStringify} from '../block-sdk/contracts.js';
+export const NUMERIC_CONDITION_OPERATORS=Object.freeze(['greater-than','at-least','less-than','at-most']);
+export function conditionOmitsOutputs(manifest){
+ const outputs=Object.values(manifest.outputs || {});
+ return ['recipe','javascript'].includes(manifest.runtime) && outputs.length>0 && outputs.every(port=>port.required===false && !Object.hasOwn(port,'default'));
+}
+export function inactiveConditionInputs(condition,manifest,inputs){
+ if(!condition || !conditionOmitsOutputs(manifest))return null;
+ validateCondition(condition,manifest);
+ const partial=validateValues(Object.fromEntries(Object.entries(manifest.inputs).map(([key,port])=>[key,{...port,required:false}])),inputs);
+ if(!Object.hasOwn(partial,condition.input) && manifest.inputs[condition.input].required!==false)return null;
+ return conditionalBypass(condition,manifest,partial)?partial:null;
+}
+export function validateConditionalResult(condition,manifest,input,record){
+ const bypass=conditionalBypass(condition || undefined,manifest,input);
+ if(bypass){
+  assert(record.skipped===true && record.failureRecovery===undefined && record.state===undefined && record.mediaReceipts===undefined && stableStringify(record.outputs)===stableStringify(bypass.outputs),'CONDITION','The saved result does not match this skipped branch.');
+ }else assert(!record.skipped || record.failureRecovery!==undefined,'CONDITION','An active Block cannot be marked skipped without a reviewed recovery result.');
+}
+// Bounded data predicates only. No expression language, eval or imported code.
+export function validateDataPredicate(condition,fields) {
+ assert(plain(condition) && Object.keys(condition).every(key=>['input','path','operator','value'].includes(key)),'CONDITION','Use an input, field path and supported condition');
+ assert(Object.hasOwn(fields,condition.input),'CONDITION','Condition input is unavailable');
+ assert(Array.isArray(condition.path) && condition.path.length<=8 && condition.path.every(key=>typeof key === 'string' && /^[a-zA-Z0-9_-]{1,80}$/.test(key) && !['__proto__','prototype','constructor'].includes(key)),'CONDITION','Choose up to eight safe field names');
+ assert(['present','equals','not-equals',...NUMERIC_CONDITION_OPERATORS].includes(condition.operator),'CONDITION','Unsupported condition operator');
+ if(NUMERIC_CONDITION_OPERATORS.includes(condition.operator))assert(typeof condition.value==='number' && Number.isFinite(condition.value),'CONDITION','Compare with a finite number');
+ else if(condition.operator !== 'present')assert(condition.value === null || ['string','boolean'].includes(typeof condition.value) || typeof condition.value==='number' && Number.isFinite(condition.value),'CONDITION','Compare a simple value');
+}
+export function validateCondition(condition,manifest) {
+ if(condition === undefined)return;
+ assert(manifest.runtime !== 'host','CONDITION','Conditional execution is available for SDK blocks; host workspaces retain their existing controls');
+ validateDataPredicate(condition,manifest.inputs);
+ const entries=Object.entries(manifest.inputs),primary=entries.find(([,port])=>port.primary) || (entries.length===1 ? entries[0] : null),outputs=Object.entries(manifest.outputs);
+ assert(conditionOmitsOutputs(manifest) || primary && outputs.length===1 && compatible(primary[1],outputs[0][1]).compatible,'CONDITION','Conditional steps need compatible pass-through data or only optional outputs without defaults');
+}
+export function conditionMatches(condition,input) {
+ if(!condition)return true;
+ let value=input[condition.input];
+ for(const key of condition.path){value=value!==null && value!==undefined && Object.hasOwn(value,key) ? value[key] : undefined;}
+ if(condition.operator === 'present')return value !== undefined && value !== null && value !== false && value !== '' && (!Array.isArray(value) || value.length>0);
+ if(NUMERIC_CONDITION_OPERATORS.includes(condition.operator)) {
+  if(typeof value!=='number' || !Number.isFinite(value) || typeof condition.value!=='number' || !Number.isFinite(condition.value))return false;
+  if(condition.operator==='greater-than')return value>condition.value;
+  if(condition.operator==='at-least')return value>=condition.value;
+  if(condition.operator==='less-than')return value<condition.value;
+  return value<=condition.value;
+ }
+ return condition.operator === 'equals' ? value === condition.value : value !== condition.value;
+}
+export function conditionalBypass(condition,manifest,input) {
+ validateCondition(condition,manifest);if(!condition)return null;
+ // Predicate controls use the same declared defaults as normal SDK execution.
+ // An explicitly supplied null/undefined must not be replaced by a default.
+ const predicate=manifest.inputs[condition.input];
+ const conditioned=Object.hasOwn(input,condition.input) ? input : {...input,[condition.input]:!predicate.sources || predicate.sources.includes('default')?predicate.default:undefined};
+ if(conditionMatches(condition,conditioned))return null;
+ if(conditionOmitsOutputs(manifest))return {outputs:{},skipped:true};
+ const entries=Object.entries(manifest.inputs),primary=entries.find(([,port])=>port.primary) || entries[0],output=Object.entries(manifest.outputs)[0],value=Object.hasOwn(input,primary[0]) ? input[primary[0]] : !primary[1].sources || primary[1].sources.includes('default')?primary[1].default:undefined;
+ assert(valueMatches(value,output[1]),'CONDITION','The skipped step has no compatible input to pass through');
+ return {outputs:{[output[0]]:structuredClone(value)},skipped:true};
+}

package/packages/block-platform/current-semantic-source.js

@@ -0,0 +1,45 @@
+import {assert,digest} from '../block-sdk/contracts.js';
+import {semanticValueIsFresh} from '../block-sdk/semantic-freshness.js';
+import {readCanvasSemanticContext} from './semantic-results.js';
+
+const transientMediaKeys=new Set(['url','previewUrl','imageUrl','thumbnailUrl','posterUrl','src','data']);
+function pinnedValueIdentity(value){
+ if(Array.isArray(value))return value.map(pinnedValueIdentity);
+ if(!value||typeof value!=='object')return value;
+ if(['image','video','audio'].includes(value.kind)){
+  assert(typeof value.assetId==='string' && value.assetId && typeof value.versionId==='string' && value.versionId && typeof value.url==='string' && value.url && !Object.keys(value).some(key=>transientMediaKeys.has(key)&&key!=='url'),'SEGMENT_SOURCE','The pinned media reference must resolve to one current accessible version.');
+  return Object.fromEntries(Object.entries(value).filter(([key])=>key!=='url').map(([key,child])=>[key,pinnedValueIdentity(child)]));
+ }
+ const wrapped=['image','video','audio'].includes(value.asset?.kind)&&typeof value.url==='string'&&value.url===value.asset.url;
+ assert(!Object.keys(value).some(key=>transientMediaKeys.has(key)&&!(key==='url'&&wrapped)),'SEGMENT_SOURCE','The pinned media reference must resolve to one current accessible version.');
+ return Object.fromEntries(Object.entries(value).filter(([key])=>key!=='url'||!wrapped).map(([key,child])=>[key,pinnedValueIdentity(child)]));
+}
+
+export async function pinExplicitFlowSource(pin,edge,sourceNode,canvasEdge,requirement){
+ assert(pin?.sourceNodeId===sourceNode?.id && pin?.sourceStageId===edge.from.stage && pin?.outputName===edge.from.port && pin?.sourceHandle===canvasEdge?.sourceHandle && pin?.targetHandle===canvasEdge?.targetHandle && canvasEdge?.source===sourceNode.id && typeof pin.runId==='string' && pin.runId.length>0 && pin.runId.length<=200 && /^[a-f0-9]{64}$/.test(pin.sourceDigest||'') && Object.hasOwn(pin,'value') && pin.outputContract?.type,'SEGMENT_SOURCE','The selected result pin no longer matches this connection. Review it in Flow.');
+ assert(!requirement.freshnessPolicy,'SEGMENT_SOURCE','This time-sensitive input needs a fresh producer result. Review the pinned version before updating.');
+ return {id:`block:${edge.from.stage}:${edge.from.port}:pin:${pin.runId}`,revision:pin.sourceDigest,valueDigest:await digest(pin.value),sourceRunId:pin.runId,pinnedValue:true};
+}
+
+export async function pinCurrentSemanticSource(canvas,stage,node,port,requirement,permissions=[]) {
+  const record=readCanvasSemanticContext(canvas).snapshot().values.find(value=>value.source.kind==='block' && value.source.stepId===stage.id && value.source.port===port);
+  assert(record && !node.data.blockStale && semanticValueIsFresh(record,requirement),'SEGMENT_SOURCE','Update the source Block before reusing its result.');
+  const missingPermissions=(record.permissions||[]).filter(permission=>!permissions.includes(permission));
+  assert(!missingPermissions.length,'SEGMENT_SOURCE',`The receiving Block cannot reuse this saved result: its pinned permission contract lacks ${missingPermissions.slice(0,5).join(', ')}${missingPermissions.length>5?' and more':''}. Review a compatible Block release or route; the retained result was not applied.`);
+  assert(Object.hasOwn(node.data.blockOutputs || {},port),'SEGMENT_SOURCE','The source Block has no current saved result.');
+  const valueDigest=await digest(node.data.blockOutputs[port]);
+  assert(valueDigest===await digest(record.value),'SEGMENT_SOURCE','The saved result changed. Update its source before continuing.');
+  assert(semanticValueIsFresh(record,requirement),'SEGMENT_SOURCE','The source expired while preparing the update. Refresh it first.');
+  return {id:record.id,revision:record.revision,valueDigest,sourceRunId:record.source.runId,...(record.updatedAt!==undefined?{updatedAt:record.updatedAt}:{}),...(record.expiresAt!==undefined?{expiresAt:record.expiresAt}:{})};
+}
+
+export async function assertCurrentSemanticSource(pin,value,requirement) {
+  if(pin.pinnedValue){
+   assert(!requirement.freshnessPolicy,'SEGMENT_SOURCE','This time-sensitive input needs a fresh producer result.');
+   assert(await digest(pinnedValueIdentity(value))===pin.valueDigest,'SEGMENT_SOURCE','The selected result pin changed. Review the affected update again.');
+   return;
+  }
+  assert(semanticValueIsFresh(pin,requirement),'SEGMENT_SOURCE','The saved source expired. Update it before continuing.');
+  assert(await digest(value)===pin.valueDigest,'SEGMENT_SOURCE','The saved source changed. Review the affected update again.');
+  assert(semanticValueIsFresh(pin,requirement),'SEGMENT_SOURCE','The saved source expired. Update it before continuing.');
+}