@petercjl/competitor-visual-canvas 0.1.1 → 0.1.7

package/src/boardmix.mjs

@@ -0,0 +1,249 @@
+import {writeBatches} from './boardmix-batch.mjs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {invoke,read,exists,create,checkpoint,fail,layout,validateLayout,uid,REGIONS,collect} from './workflow.mjs';
+
+export const IMAGE_REGIONS=['main_images','sku_images','detail_images'];
+const MEDIA_REGIONS=REGIONS;
+const near=(a,b)=>Number.isFinite(a)&&Math.abs(a-b)<0.02;
+const geometry=(a,b)=>['x','y','width','height'].every(k=>near(a[k],b[k]));
+async function call(command,args=[],run=invoke){
+ const out=await run('boardmixcli',[command,...args]);
+ if(out.ok===false)fail('BOARDMIX_FAILED',out.error||out.message||'Boardmix operation failed.');
+ return out.result??out;
+}
+export async function requireBoardmix(run=invoke){
+ const caps=await call('capabilities',['--json'],run);
+ for(const c of ['image.download','image.inspect','image.import','frame.create','text.create','object.get','object.resize','object.move','board.info'])if(!caps.commands?.includes(c))fail('CAPABILITY_UNAVAILABLE','boardmixcli requires '+c+'; update its capability package.');
+ return caps;
+}
+export async function planBoardmix(dir,options={},run=invoke){
+ let base,baseManifest,baseState;
+ if(options.baseRun){
+  base=await loadPlan(options.baseRun);baseState=await loadState(options.baseRun,base);baseManifest=await read(path.join(options.baseRun,'assets.manifest.json'));
+  if(baseState.status!=='completed'||!baseState.file_key||baseState.inflight)fail('STATE_CONFLICT','Base Boardmix run must be completed.');
+  if(baseState.successor_run)fail('STALE_BASE_RUN','Append from the latest run: '+baseState.successor_run);
+ }
+ for(const f of ['layout.plan.json','boardmix.batch.json'])if(await exists(path.join(dir,f)))fail('OUTPUT_EXISTS','Plan already exists.');
+ await requireBoardmix(run);
+ const manifest=await read(path.join(dir,'assets.manifest.json'));
+ if(baseManifest&&manifest.products.some(p=>baseManifest.products.some(b=>b.id===p.id)))fail('PRODUCT_ALREADY_PRESENT','Product already exists in the base canvas.');
+ if(manifest.target!=='boardmix')fail('TARGET_CONFLICT','Collect with --target boardmix before planning.');
+ await fs.mkdir(path.join(dir,'media'),{recursive:true});
+ // This URL is a verified 1x1 lazy-loading placeholder, not product artwork.
+ let filtered=false;
+ for(const product of manifest.products){
+  const placeholder=product.assets.detail_images.filter(a=>a.url==='https://assets.alicdn.com/kissy/1.0.0/build/imglazyload/spaceball.gif');
+  if(placeholder.length){product.assets.detail_images=product.assets.detail_images.filter(a=>!placeholder.includes(a));product.excluded_assets=[...(product.excluded_assets||[]),...placeholder.map(a=>({...a,reason:'Known 1x1 lazy-loading placeholder'}))];filtered=true;}
+ }
+ if(filtered)await checkpoint(path.join(dir,'assets.manifest.json'),manifest);
+ for(const product of manifest.products)for(const category of MEDIA_REGIONS)for(const a of product.assets[category]){
+  const prefix=category==='main_videos'?'video':'image';
+  if(a.local_file){const data=await call(prefix+'.inspect',['--file',assetPath(dir,a)],run);if(data.sha256!==a.sha256)fail('ASSET_CHANGED','A saved source image changed.');continue;}
+  const pending=path.join(dir,'media',a.asset_id+'.download');
+  let data;
+  if(await exists(pending))data=await call(prefix+'.inspect',['--file',pending],run);
+  else data=await call(prefix+'.download',['--url',a.url,'--output',pending],run);
+  const ext={'video/mp4':'mp4','image/png':'png','image/jpeg':'jpg','image/webp':'webp'}[data.mime];if(!ext)fail('FEATURE_UNSUPPORTED','Unsupported image format.');
+  // Persist the downloaded receipt before rename, so an interrupted plan can inspect the same bytes.
+  const relative=path.join('media',a.asset_id+'.'+ext),dest=path.join(dir,relative);
+  if(await exists(dest)){
+   const old=await call(prefix+'.inspect',['--file',dest],run);if(old.sha256!==data.sha256)fail('ASSET_CHANGED','Downloaded source differs from saved destination.');
+  }else await fs.rename(pending,dest);
+  const final=await call(prefix+'.inspect',['--file',dest],run);
+  Object.assign(a,{local_file:relative,mime:final.mime,width:final.width,height:final.height,sha256:final.sha256,...(final.duration?{duration:final.duration}:{})});
+  await checkpoint(path.join(dir,'assets.manifest.json'),manifest);
+ }
+ if(base&&!base.regions.some(r=>r.category==='main_videos')&&manifest.products.some(p=>p.assets.main_videos.length))fail('LAYOUT_MIGRATION_REQUIRED','Run boardmix videos on the existing board before appending videos.');
+ const plan=layout(manifest,{...options,basePlan:base,categories:base?base.regions.map(r=>r.category):MEDIA_REGIONS});
+ if(base){
+  for(const product of baseManifest.products)for(const category of MEDIA_REGIONS)for(const a of product.assets[category]){
+   const source=assetPath(options.baseRun,a),dest=assetPath(dir,a);const bytes=await fs.readFile(source);
+   if(crypto.createHash('sha256').update(bytes).digest('hex')!==a.sha256)fail('ASSET_CHANGED','Base source image changed.');
+   if(await exists(dest)){if(crypto.createHash('sha256').update(await fs.readFile(dest)).digest('hex')!==a.sha256)fail('ASSET_CHANGED','Copied asset differs.');}
+   else await fs.copyFile(source,dest,fs.constants.COPYFILE_EXCL);
+  }
+  manifest.products=[...structuredClone(baseManifest.products),...manifest.products];
+  await checkpoint(path.join(dir,'assets.manifest.json'),manifest);
+  plan.target_file_key=baseState.file_key;
+ }
+ plan.target='boardmix';
+ plan.asset_hashes=Object.fromEntries(manifest.products.flatMap(p=>MEDIA_REGIONS.flatMap(c=>p.assets[c].map(a=>[a.asset_id,a.sha256]))));
+ // Boardmix Frame captions keep a screen-sized label; reserve extra heading clearance.
+ if(!base)for(const text of plan.batch.texts){text.y-=168;text.fontSize=48;text.height=72;}
+ plan.omitted_media=[];
+ await create(path.join(dir,'layout.plan.json'),plan);
+ await create(path.join(dir,'boardmix.batch.json'),plan.batch);
+ if(base)await create(statePath(dir),{run_id:plan.run_id,target:'boardmix',plan_hash:uid(plan),file_key:baseState.file_key,objects:structuredClone(baseState.objects),base_run:path.resolve(options.baseRun)});
+ return {run_id:plan.run_id,target:'boardmix',title:plan.title,frames:plan.batch.frames.length,images:plan.batch.media.filter(m=>m.kind==='image').length,videos:plan.batch.media.filter(m=>m.kind==='video').length,omitted_media:plan.omitted_media,...(base?{appending:true,file_key:baseState.file_key,base_run:path.resolve(options.baseRun)}:{})};
+}
+function assetPath(dir,a){if(!a?.local_file||!/^media[\\/][a-f0-9]{24}\.(png|jpg|webp|mp4)$/.test(a.local_file)||!/^([a-f0-9]{64})$/.test(a.sha256||''))fail('ASSET_MANIFEST_INVALID','Expected a managed downloaded image.');return path.join(dir,a.local_file);}
+function context(options){if(!options.session||!options.fileKey)fail('BOARDMIX_CONTEXT_REQUIRED','Provide --session and the exact --file-key.');return ['--session',options.session,'--file-key',options.fileKey];}
+async function lock(dir,action){
+ const p=path.join(dir,'boardmix.lock');
+ let handle;
+ try{handle=await fs.open(p,'wx',0o600);}catch(e){
+  if(e.code!=='EEXIST')throw e;
+  const old=await read(p);if(old.owner!=='@petercjl/competitor-visual-canvas'||!Number.isSafeInteger(old.pid))fail('RUN_LOCKED','Run lock ownership is unknown.');
+  try{process.kill(old.pid,0);fail('RUN_LOCKED','Another process owns this run.');}catch(err){if(err.code!=='ESRCH')throw err;}
+  await fs.rename(p,p+'.'+crypto.randomUUID()+'.backup');handle=await fs.open(p,'wx',0o600);
+ }
+ try{await handle.writeFile(JSON.stringify({owner:'@petercjl/competitor-visual-canvas',pid:process.pid}));return await action();}
+ finally{await handle.close();await fs.unlink(p);}
+}
+const statePath=dir=>path.join(dir,'boardmix.state.json');
+async function loadState(dir,plan){
+ const state=await exists(statePath(dir))?await read(statePath(dir)):{run_id:plan.run_id,target:'boardmix',plan_hash:uid(plan),objects:{}};
+ if(state.run_id!==plan.run_id||state.target!=='boardmix'||state.plan_hash!==uid(plan))fail('STATE_CONFLICT','Boardmix state or plan identity differs.');return state;
+}
+async function loadPlan(dir){const plan=await read(path.join(dir,'layout.plan.json'));if(plan.target!=='boardmix')fail('TARGET_CONFLICT','This run targets Infinite Canvas.');validateLayout(plan);return plan;}
+export async function createBoardmix(dir,options={},run=invoke){
+ const plan=await loadPlan(dir),ctx=context(options);await requireBoardmix(run);
+ return lock(dir,async()=>{
+  const state=await loadState(dir,plan);
+  async function browserReady(key){
+   await call('browser.open',['--endpoint',options.cdpEndpoint,'--file-key',key],run);
+   await call('browser.connect',['--endpoint',options.cdpEndpoint,'--session',options.session,'--file-key',key],run);
+  }
+  if(state.file_key){if(options.cdpEndpoint)await browserReady(state.file_key);return {target:'boardmix',file_key:state.file_key,canvas_url:'https://boardmix.cn/app/editor/'+state.file_key,needs_attachment:!options.cdpEndpoint,changed:false};}
+  if(state.inflight)fail('SUBMISSION_UNCERTAIN','Inspect the previous create outcome before binding an existing file key.');
+  const source=await call('board.info',ctx,run);
+  state.inflight={key:'board.create',kind:'board'};await checkpoint(statePath(dir),state);
+  const board=await call('board.create',[...ctx,'--team-id',String(source.teamId),'--project-id',String(source.projectId),'--folder-id',String(source.folderId||0)],run);
+  if(!board.fileKey)fail('SUBMISSION_UNCERTAIN','Boardmix did not return a file key.');
+  state.file_key=board.fileKey;state.created_by_run=true;delete state.inflight;await checkpoint(statePath(dir),state);
+  if(options.cdpEndpoint)await browserReady(board.fileKey);else await call('board.open',[...ctx,'--target-file-key',board.fileKey],run);
+  return {target:'boardmix',file_key:board.fileKey,canvas_url:'https://boardmix.cn/app/editor/'+board.fileKey,needs_attachment:!options.cdpEndpoint,next:options.cdpEndpoint?'Connected in browser; continue canvas --submit.':'Attach the returned editor to the same session, then canvas --submit.'};
+ });
+}
+function descriptors(plan){return [...plan.batch.texts.map(t=>({id:t.id,kind:'text',...t})),...plan.batch.frames.map(f=>({id:f.id,kind:'frame',...f})),...plan.batch.media.map(m=>({id:m.id,kind:m.kind,media:m,...m.placement.positions[0]}))];}
+export async function writeBoardmix(dir,options={},run=invoke){
+ const plan=await loadPlan(dir),state=await loadState(dir,plan);
+ if(state.successor_run&&options.submit)fail('STALE_BASE_RUN','Use latest run: '+state.successor_run);
+ if(options.submit&&state.base_run)return lock(state.base_run,async()=>{
+  const parent=await read(statePath(state.base_run));
+  if(parent.successor_run&&parent.successor_run!==path.resolve(dir))fail('STALE_BASE_RUN','Use latest run: '+parent.successor_run);
+  const result=await writeBoardmixInner(dir,options,run);
+  if(!parent.successor_run){parent.successor_run=path.resolve(dir);await checkpoint(statePath(state.base_run),parent);}
+  return result;
+ });
+ return writeBoardmixInner(dir,options,run);
+}
+async function writeBoardmixInner(dir,options={},run=invoke){
+ const plan=await loadPlan(dir),batch=await read(path.join(dir,'boardmix.batch.json'));
+ if(JSON.stringify(batch)!==JSON.stringify(plan.batch))fail('STATE_CONFLICT','Batch differs from validated plan.');
+ if(!options.submit)return {dry_run:true,target:'boardmix',title:plan.title,frames:batch.frames.length,images:batch.media.filter(m=>m.kind==='image').length,videos:batch.media.filter(m=>m.kind==='video').length,omitted_media:plan.omitted_media};
+ const ctx=context(options);const caps=await requireBoardmix(run);
+ if(options.cdpEndpoint){await call('browser.open',['--endpoint',options.cdpEndpoint,'--file-key',options.fileKey],run);await call('browser.connect',['--endpoint',options.cdpEndpoint,...context(options)],run);}
+ if(batch.media.some(m=>m.kind==='video')&&!caps.commands.includes('video.import'))fail('CAPABILITY_UNAVAILABLE','Update boardmixcli for video.import.');
+ const fast=['image.inspect.batch','image.import.batch','object.get.batch','object.place.batch'].every(c=>caps.commands.includes(c));
+ return lock(dir,async()=>{
+  const state=await loadState(dir,plan);
+  if(state.file_key&&state.file_key!==options.fileKey)fail('TARGET_CONFLICT','The run is bound to another Boardmix file.');
+  if(state.inflight&&!(fast&&['image.batch','video'].includes(state.inflight.kind)))throw Object.assign(Error('Previous creation/import outcome must be inspected before recovery.'),{code:'SUBMISSION_UNCERTAIN',details:state.inflight});
+  const board=await call('board.info',ctx,run);if(board.fileKey!==options.fileKey)fail('TARGET_CONFLICT','Connected editor identity differs.');
+  state.file_key=options.fileKey;await checkpoint(statePath(dir),state);
+  const manifest=await read(path.join(dir,'assets.manifest.json'));
+  const assets=new Map(manifest.products.flatMap(p=>MEDIA_REGIONS.flatMap(c=>p.assets[c].map(a=>[a.asset_id,a]))));
+  if(!fast&&batch.media.some(m=>m.kind==='video'))fail('CAPABILITY_UNAVAILABLE','Video runs require batch placement capabilities.');
+  if(fast){
+   if(state.created_by_run&&board.name!==plan.title)await call('board.rename',[...ctx,'--name',plan.title],run);
+   await writeBatches({dir,plan,state,assets,ctx,call:(c,a)=>call(c,a,run),descriptors:descriptors(plan),assetPath});
+  }else{
+  for(const media of batch.media){const a=assets.get(media.sourceMetadata.assetId);if(!a||plan.asset_hashes&&plan.asset_hashes[a.asset_id]!==a.sha256||a.url!==media.urls[0])fail('ASSET_CHANGED','Source manifest differs from the immutable plan.');const info=await call('image.inspect',['--file',assetPath(dir,a)],run);if(info.sha256!==a.sha256)fail('ASSET_CHANGED','Source bytes changed before write.');}
+  if(state.created_by_run&&board.name!==plan.title)await call('board.rename',[...ctx,'--name',plan.title],run);
+  for(const d of descriptors(plan)){
+   let saved=state.objects[d.id];
+   const local=d.kind==='image'?assets.get(d.media.sourceMetadata.assetId):null;
+   if(local){if(plan.asset_hashes&&plan.asset_hashes[local.asset_id]!==local.sha256)fail('ASSET_CHANGED','Source manifest differs from the immutable image plan.');const info=await call('image.inspect',['--file',assetPath(dir,local)],run);if(info.sha256!==local.sha256)fail('ASSET_CHANGED','Local image bytes changed.');}
+   if(!saved){
+    state.inflight={key:d.id,kind:d.kind};await checkpoint(statePath(dir),state);
+    const result=await call(d.kind==='image'?'image.import':d.kind+'.create',d.kind==='image'?[...ctx,'--file',assetPath(dir,local)]:[...ctx,'--x',String(d.x),'--y',String(d.y),'--width',String(d.width),'--height',String(d.height),d.kind==='frame'?'--name':'--text',d.kind==='frame'?d.name:d.text,...(d.kind==='text'?['--font-size',String(d.fontSize||28)]:[])],run);
+    const obj=result.object??result.readback;if(!obj?.guid)fail('SUBMISSION_UNCERTAIN','Created object GUID missing.');
+    saved=state.objects[d.id]={guid:obj.guid,kind:d.kind,placed:false,resource_hash:obj.resourceHash};delete state.inflight;await checkpoint(statePath(dir),state);
+   }
+   const ids=['--session-id',String(saved.guid.sessionID),'--local-id',String(saved.guid.localID)];
+   let obj=await call('object.get',[...ctx,...ids],run);
+   if(local&&Math.abs(obj.width/obj.height-local.width/local.height)>0.01)fail('IMAGE_ORIENTATION_MISMATCH','Imported aspect ratio differs from source metadata; preserve the source and correct metadata before placement.');
+   if(saved.placed){
+    if(d.kind==='text'?!near(obj.x,d.x)||!near(obj.y,d.y):!geometry(obj,d))fail('CANVAS_CHANGED','An existing application object moved or resized.');
+   }else{
+    if(d.kind!=='text'&&(!near(obj.width,d.width)||!near(obj.height,d.height)))obj=await call('object.resize',[...ctx,...ids,'--width',String(d.width),'--height',String(d.height)],run);
+    if(!near(obj.x,d.x)||!near(obj.y,d.y))obj=await call('object.move',[...ctx,...ids,'--x',String(d.x),'--y',String(d.y)],run);
+   }
+   if(d.kind==='text'&&obj.fontSize!==d.fontSize)fail('CANVAS_CHANGED','Heading font size differs.');
+   if(d.kind==='frame'&&obj.name!==d.name)fail('CANVAS_CHANGED','Frame title differs.');
+   if(saved.resource_hash&&obj.resourceHash!==saved.resource_hash)fail('CANVAS_CHANGED','Image resource changed.');
+   if(d.kind==='text'?!near(obj.x,d.x)||!near(obj.y,d.y):!geometry(obj,d))fail('OUTPUT_CONTRACT_FAILED','Boardmix object readback differs.');
+   saved.placed=true;saved.readback=obj;await checkpoint(statePath(dir),state);
+  }
+  // Verify the final whole layout after all imports, which may trigger native container behavior.
+  for(const d of descriptors(plan)){const saved=state.objects[d.id],o=await call('object.get',[...ctx,'--session-id',String(saved.guid.sessionID),'--local-id',String(saved.guid.localID)],run);if(d.kind==='text'?!near(o.x,d.x)||!near(o.y,d.y):!geometry(o,d))fail('OUTPUT_CONTRACT_FAILED','Final layout readback differs.');if(d.kind==='text'&&o.fontSize!==d.fontSize||d.kind==='frame'&&o.name!==d.name||saved.resource_hash&&o.resourceHash!==saved.resource_hash)fail('CANVAS_CHANGED','Final object identity differs.');saved.readback=o;}
+  }
+  const report={run_id:plan.run_id,target:'boardmix',status:'completed',performance:state.performance,canvas_id:state.file_key,canvas_url:'https://boardmix.cn/app/editor/'+state.file_key,frames:batch.frames.length,images:batch.media.filter(m=>m.kind==='image').length,videos:batch.media.filter(m=>m.kind==='video').length,omitted_media:plan.omitted_media,products:manifest.products.map(p=>({id:p.id,title:p.title,shop:p.shop.shopName,coverage:p.coverage,excluded_assets:p.excluded_assets||[],counts:Object.fromEntries(MEDIA_REGIONS.map(c=>[c,p.assets[c].length]))})),verification:'GUID, image resource identity, frame names and geometry read back; frame containment is geometric. Text content and visual appearance require desktop inspection.',objects:state.objects};
+  state.status='completed';await checkpoint(statePath(dir),state);await checkpoint(path.join(dir,'collection-report.json'),report);return report;
+ });
+}
+export async function recoverBoardmix(dir,options={},run=invoke){
+ const plan=await loadPlan(dir),ctx=context(options);
+ return lock(dir,async()=>{
+  const state=await loadState(dir,plan);if(!state.inflight)fail('STATE_CONFLICT','No uncertain operation to recover.');
+  if(state.inflight.kind==='board'){
+   const info=await call('board.info',ctx,run);if(info.fileKey!==options.fileKey)fail('TARGET_CONFLICT','Connected file differs.');
+   if(!options.verified)fail('VERIFICATION_REQUIRED','Inspect the create outcome and confirm this exact file with --verified.');
+   state.file_key=options.fileKey;state.created_by_run=true;
+  }else{
+   if(state.file_key!==options.fileKey)fail('TARGET_CONFLICT','Run is bound to another file.');
+   if(!Number.isSafeInteger(options.sessionID)||!Number.isSafeInteger(options.localID))fail('GUID_REQUIRED','Provide the observed numeric object GUID.');
+   const d=descriptors(plan).find(x=>x.id===state.inflight.key),guid={sessionID:options.sessionID,localID:options.localID};
+   const obj=await call('object.get',[...ctx,'--session-id',String(guid.sessionID),'--local-id',String(guid.localID)],run);
+   if(d.kind==='frame'&&(obj.name!==d.name||!near(obj.width,d.width)||!near(obj.height,d.height)))fail('RECOVERY_MISMATCH','Observed Frame differs.');
+   if(d.kind==='text'&&!options.verified)fail('VERIFICATION_REQUIRED','Inspect visible text before --verified.');
+   if(d.kind==='image'){
+    const manifest=await read(path.join(dir,'assets.manifest.json')),a=manifest.products.flatMap(p=>MEDIA_REGIONS.flatMap(c=>p.assets[c])).find(x=>x.asset_id===d.media.sourceMetadata.assetId);
+    const bytes=await fs.readFile(assetPath(dir,a));if(crypto.createHash('sha256').update(bytes).digest('hex')!==a.sha256||plan.asset_hashes&&plan.asset_hashes[a.asset_id]!==a.sha256)fail('ASSET_CHANGED','Source image changed before recovery.');
+    const hash=crypto.createHash('md5').update(bytes).digest('hex');
+    if(obj.resourceHash!==hash)fail('RECOVERY_MISMATCH','Observed image source hash differs.');
+   }
+   state.objects[d.id]={guid,kind:d.kind,placed:false,resource_hash:obj.resourceHash};
+  }
+  delete state.inflight;await checkpoint(statePath(dir),state);return {recovered:true,file_key:state.file_key,next:'Resume canvas --submit with the same run and file key.'};
+ });
+}
+
+// Backfill videos for known products while preserving existing object identities.
+export async function addBoardmixVideos(dir,baseDir,rawFiles=[],run=invoke){
+ if(!baseDir)fail('INVALID_INPUT','Provide --base-run.');
+ const base=await loadPlan(baseDir),state=await loadState(baseDir,base),old=await read(path.join(baseDir,'assets.manifest.json'));
+ if(state.status!=='completed'||state.inflight||state.successor_run)fail('STALE_BASE_RUN','Use the latest completed run.');
+ if(base.batch.media.some(m=>m.kind==='video'))fail('VIDEOS_ALREADY_PRESENT','Videos already exist; use the completed run.');
+ const manifest=await collect(dir,old.products.map(p=>p.id),rawFiles,'boardmix');
+ await fs.mkdir(path.join(dir,'media'),{recursive:true});
+ for(const product of manifest.products){
+  const prior=old.products.find(p=>p.id===product.id);
+  if(product.coverage?.mainVideos?.status!=='captured'||!product.assets.main_videos.length)fail('VIDEO_COVERAGE_INCOMPLETE','Video capture incomplete for '+product.id);
+  product.excluded_assets=prior.excluded_assets;
+  for(const c of IMAGE_REGIONS){product.assets[c]=structuredClone(prior.assets[c]);for(const a of product.assets[c]){const source=assetPath(baseDir,a),destination=assetPath(dir,a);const bytes=await fs.readFile(source);if(crypto.createHash('sha256').update(bytes).digest('hex')!==a.sha256)fail('ASSET_CHANGED','Base image changed.');await fs.copyFile(source,destination,fs.constants.COPYFILE_EXCL);}}
+ }
+ await checkpoint(path.join(dir,'assets.manifest.json'),manifest);
+ await planBoardmix(dir,{title:base.title,...base.layout_options},run);
+ const plan=await loadPlan(dir),objects=structuredClone(state.objects),mapping=new Map();
+ for(const region of base.regions){
+  const target=plan.regions.find(r=>r.category===region.category),dx=target.x-region.x;
+  if(target.frame_ids.length!==region.frame_ids.length)fail('MIGRATION_CONFLICT','Frame coverage differs.');
+  for(let i=0;i<region.frame_ids.length;i++)mapping.set(target.frame_ids[i],region.frame_ids[i]);
+  for(const oldId of region.frame_ids){const prior=base.batch.frames.find(f=>f.id===oldId),fresh=plan.batch.frames.find(f=>mapping.get(f.id)===oldId);Object.assign(fresh,{...prior,x:prior.x+dx});}
+  target.frame_ids=[...region.frame_ids];Object.assign(target,{next_y:region.next_y,bottom:region.bottom,next_x:region.next_x+dx,right:region.right+dx});
+  const priorText=base.batch.texts.find(t=>Math.abs(t.x-region.x)<0.02),freshText=plan.batch.texts.find(t=>Math.abs(t.x-target.x)<0.02);if(!priorText||!freshText)fail('MIGRATION_CONFLICT','Heading missing.');Object.assign(freshText,{...priorText,x:priorText.x+dx});
+  for(const m of plan.batch.media.filter(m=>m.sourceMetadata.category===region.category)){const prior=base.batch.media.find(b=>b.sourceMetadata.assetId===m.sourceMetadata.assetId&&b.sourceMetadata.productId===m.sourceMetadata.productId);if(!prior)fail('MIGRATION_CONFLICT','Image mapping missing.');Object.assign(m,structuredClone(prior));m.placement.positions[0].x+=dx;}
+ }
+ plan.target_file_key=state.file_key;plan.base_run_id=base.run_id;plan.migration='add-main-video-region';
+ for(const d of descriptors(plan)){const saved=objects[d.id];if(saved){const previous=saved.readback;if(!previous)fail('MIGRATION_CONFLICT','Missing prior readback.');if(!near(d.x,previous.x)||!near(d.y,previous.y)){saved.migration_from=previous;saved.placed=false;}}}
+ validateLayout(plan);
+ await checkpoint(path.join(dir,'layout.plan.json'),plan);
+ // Batch checkpoint is owned by this just-created run and preserved before replacement.
+ const batchFile=path.join(dir,'boardmix.batch.json');await fs.copyFile(batchFile,batchFile+'.'+crypto.randomUUID()+'.backup',fs.constants.COPYFILE_EXCL);await fs.writeFile(batchFile,JSON.stringify(plan.batch,null,2)+'\n');
+ await create(statePath(dir),{run_id:plan.run_id,target:'boardmix',plan_hash:uid(plan),file_key:state.file_key,objects,base_run:path.resolve(baseDir)});
+ return {run_id:plan.run_id,file_key:state.file_key,images:plan.batch.media.filter(m=>m.kind==='image').length,videos:plan.batch.media.filter(m=>m.kind==='video').length,moved_existing_objects:Object.values(objects).filter(o=>o.migration_from).length,next:'canvas --run DIR --session FILE --file-key KEY --submit'};
+}

package/src/lifecycle.mjs

@@ -1,9 +1,10 @@
 export {ROOT,META} from './core.mjs';
 import {SOURCE,status,install} from './skills.mjs';
-import {META} from './core.mjs';
-export async function skill(action,agent='codex',custom){
- if(action==='source')return {source:SOURCE,name:'competitor-visual-canvas',version:META.version};
- if(action==='status'){const s=await status(agent,custom);return {...s,target:s.destination};}
- if(['install','update'].includes(action)){const s=await install(agent,{path:custom});return {...s,target:s.destination};}
+import {META,ROOT,readJson} from './core.mjs';
+import path from 'node:path';
+export async function skill(action,agent='generic',custom){
+ if(action==='source')return {ok:true,...await readJson(path.join(ROOT,'capabilities.json')),source:SOURCE,name:'competitor-visual-canvas',package:META.name,version:META.version};
+ if(action==='status'){const s=await status(agent,custom);return {...s,name:'competitor-visual-canvas',package:META.name,version:s.version||META.version,target:s.destination,edited:!!s.edited,verification:{verified:!!s.current,algorithm:'sha256'},recovery:{action:s.current?'none':'skill update with explicit --path'},hostDiscovery:'pending-host-verification'};}
+ if(['install','update'].includes(action)){const s=await install(agent,{path:custom});return {...s,name:'competitor-visual-canvas',package:META.name,version:s.version||META.version,target:s.destination,edited:!!s.edited,verification:{verified:!!s.current,algorithm:'sha256'},recovery:{action:s.current?'none':'skill update with explicit --path'},hostDiscovery:'pending-host-verification'};}
  throw Object.assign(Error('Use skill source/status/install/update'),{code:'INVALID_INPUT'});
 }

package/src/skills.mjs

@@ -1,5 +1,5 @@
 import fs from 'node:fs/promises';
-import {existsSync} from 'node:fs';
+import {existsSync,readFileSync,lstatSync,realpathSync} from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
@@ -9,18 +9,12 @@ export const SOURCE = path.join(ROOT, 'skills', 'competitor-visual-canvas');
 const MARKER = '.competitor-visual-canvas-install.json';
 export function renderSkill(text, agent) { return text; }
 export function destination(agent, custom) {
-  const roots = { codex:'.codex', workbuddy:'.workbuddy', sealseek:'.sealseek' };
-  requireValue(agent in roots, 'UNKNOWN_TARGET', 'Supported agents: codex, workbuddy, sealseek.');
-  if(custom)return path.resolve(custom);
-  if(agent==='sealseek'){
-    const configured=process.env.SEALSEEK_SKILLS_DIR;
-    if(configured)return path.join(path.resolve(configured),'competitor-visual-canvas');
-    const home=process.env.SEALSEEK_HOME||path.join(os.homedir(),'.sealseek');
-    const candidates=[path.join(home,'workspaces','default','skills'),path.join(home,'workspace','skills')].filter(p=>existsSync(p));
-    if(candidates.length===1)return path.join(candidates[0],'competitor-visual-canvas');
-    requireValue(false,'TARGET_UNRESOLVED','Specify the active SealSeek Skill root with SEALSEEK_SKILLS_DIR or --path.');
-  }
-  return path.join(os.homedir(), roots[agent], 'skills','competitor-visual-canvas');
+  requireValue(/^[a-z][a-z0-9-]{0,63}$/.test(agent||''), 'UNKNOWN_TARGET', 'Expected a valid Agent name.');
+  if(custom){requireValue(path.isAbsolute(custom),'TARGET_UNRESOLVED','Provide an absolute --path.');return path.resolve(custom);}
+  // Published updaters omit --path. Only migrate an already-owned legacy target.
+  const adapter=JSON.parse(readFileSync(path.join(SOURCE,'adapters',existsSync(path.join(SOURCE,'adapters',agent+'.json'))?agent+'.json':'generic.json'),'utf8'));
+  if(adapter.legacySkillRoot){const target=path.join(os.homedir(),adapter.legacySkillRoot,'competitor-visual-canvas');try{const st=lstatSync(target);const owned=st.isSymbolicLink()?realpathSync(target)===realpathSync(SOURCE):JSON.parse(readFileSync(path.join(target,MARKER),'utf8')).owner===META.name;if(owned)return target;}catch{}}
+  requireValue(false,'TARGET_UNRESOLVED','Resolve the current Agent Skill directory and provide its explicit absolute --path.');
 }
 export async function hashes(dir) {
   const result={};
@@ -34,19 +28,28 @@ export async function hashes(dir) {
   }
   await walk();return result;
 }
+async function expectedHashes(agent) {
+  const result=await hashes(SOURCE);
+  result['SKILL.md']=hash(renderSkill(await fs.readFile(path.join(SOURCE,'SKILL.md'),'utf8'),agent));
+  for(const folder of ['bin','src'])for(const [name,digest]of Object.entries(await hashes(path.join(ROOT,folder))))result[path.join('.runtime',folder,name)]=digest;
+  for(const name of ['package.json','capabilities.json','INSTALL.md','UPDATE.md'])result[path.join('.runtime',name)]=hash(await fs.readFile(path.join(ROOT,name)));
+  for(const [name,digest]of Object.entries(await hashes(SOURCE)))result[path.join('.runtime','skills','competitor-visual-canvas',name)]=digest;
+  return result;
+}
 export async function status(agent, custom) {
-  const target=destination(agent,custom), stat=await exists(target), sourceHashes=await hashes(SOURCE);
+  const target=destination(agent,custom), stat=await exists(target), sourceHashes=await expectedHashes(agent);
   sourceHashes['SKILL.md'] = hash(renderSkill(await fs.readFile(path.join(SOURCE,'SKILL.md'),'utf8'),agent));
   if (!stat) return { ok:true, agent, destination:target, installed:false, managed:false, current:false };
   if (stat.isSymbolicLink()) {
     const actual=await fs.realpath(target).catch(()=>null);
-    return { ok:true, agent, destination:target, installed:true, managed:actual === await fs.realpath(SOURCE), current:actual === await fs.realpath(SOURCE), mode:'link' };
+    return { ok:true, agent, destination:target, installed:true, managed:actual === await fs.realpath(SOURCE), current:false, mode:'link', recovery:'Migrate the verified managed link to an isolated physical copy.' };
   }
   const manifest=await readJson(path.join(target,MARKER)).catch(()=>null);
   const managed=manifest?.owner===META.name;
+  if(!managed)return {ok:true,agent,destination:target,installed:true,managed:false,current:false,mode:stat.isDirectory()?'directory':'file'};
   const actual=stat.isDirectory() ? await hashes(target) : {};
   const edited=managed && (Object.entries(manifest.hashes).some(([name,digest])=> actual[name]!==digest && name !== path.join('agents','openai.yaml')) || Object.keys(actual).some(name=>!(name in manifest.hashes)));
-  return { ok:true,agent,destination:target,installed:true,managed,current:managed && !edited && manifest.version===META.version && manifest.source===SOURCE && Object.keys(actual).length===Object.keys(sourceHashes).length && Object.entries(sourceHashes).every(([name,digest])=> actual[name]===digest || name === path.join('agents','openai.yaml')), edited,mode:'copy',version:manifest?.version };
+  return { ok:true,agent,destination:target,installed:true,managed,current:managed && !edited && manifest.version===META.version && Object.keys(actual).length===Object.keys(sourceHashes).length && Object.entries(sourceHashes).every(([name,digest])=> actual[name]===digest || name === path.join('agents','openai.yaml')), edited,mode:'copy',version:manifest?.version };
 }
 export async function install(agent, options = {}) {
   const rename = options.rename || fs.rename;
@@ -66,9 +69,13 @@ export async function install(agent, options = {}) {
   }
   const staging=`${target}.staging-${crypto.randomUUID()}`;
   await fs.cp(SOURCE,staging,{ recursive:true,errorOnExist:true,force:false });
+  const runtime=path.join(staging,'.runtime');await fs.mkdir(runtime);
+  for(const folder of ['bin','src'])await fs.cp(path.join(ROOT,folder),path.join(runtime,folder),{recursive:true,errorOnExist:true,force:false});
+  for(const name of ['package.json','capabilities.json','INSTALL.md','UPDATE.md'])await fs.copyFile(path.join(ROOT,name),path.join(runtime,name),fs.constants.COPYFILE_EXCL);
+  await fs.cp(SOURCE,path.join(runtime,'skills','competitor-visual-canvas'),{recursive:true,errorOnExist:true,force:false});
   const skillText = await fs.readFile(path.join(staging,'SKILL.md'),'utf8');
   await fs.writeFile(path.join(staging,'SKILL.md'),renderSkill(skillText,agent));
-  if (backup && await exists(path.join(target,'agents','openai.yaml'))) {
+  if (backup && info.mode!=='link' && await exists(path.join(target,'agents','openai.yaml'))) {
     const oldManifest=await readJson(path.join(target,MARKER));
     const name=path.join('agents','openai.yaml');
     if(hash(await fs.readFile(path.join(target,name)))!==oldManifest.hashes[name]) await fs.copyFile(path.join(target,name),path.join(staging,name));

package/src/update.mjs

@@ -53,12 +53,10 @@ export async function globalInstallation(root=ROOT) {
   return (await fs.realpath(expected).catch(()=>null))===await fs.realpath(root);
 }
 export async function managedTargets() {
-  const targets=[];
-  for(const agent of ['codex','workbuddy','sealseek']) {
-    const info=await status(agent).catch(e=>{if(e.code==='TARGET_UNRESOLVED')return {managed:false};throw e;});
-    requireValue(!info.managed||!info.edited,'LOCAL_EDITS','A managed Skill has local edits; review it before updating.',{agent});
-    if(info.managed)targets.push(agent);
-  }return targets;
+  const agent=process.env.COMPETITOR_CANVAS_AGENT,selected=process.env.COMPETITOR_CANVAS_SKILL_PATH;
+  if(!agent||!selected)return [];
+  const info=await status(agent,selected);requireValue(!info.edited,'LOCAL_EDITS','Selected Skill has local edits.');
+  return [{agent,path:info.destination}];
 }
 export async function activeWork(dir=stateRoot()) {
   for(const folder of ['jobs','auth-sessions']) {
@@ -82,8 +80,9 @@ export async function installVersion(version,targets,{root=ROOT,dir=stateRoot(),
     await execute(await npmScript(),['install','--global',`${META.name}@${version}`,'--ignore-scripts','--no-audit','--no-fund']);
     const installed=await readJson(path.join(root,'package.json'));
     requireValue(installed.name===META.name&&installed.version===version,'UPDATE_VERIFICATION_FAILED','Installed package version mismatch.');
-    for(const agent of targets){
-      const r=synchronize?await synchronize(agent):spawnSync(process.execPath,[path.join(root,'bin','competitor-visual-canvas.mjs'),'skill','update','--agent',agent,'--json'],{encoding:'utf8',timeout:120000,env:{...process.env,COMPETITOR_CANVAS_AUTO_UPDATE:'0'},windowsHide:true});
+    for(const target of targets){
+      const agent=typeof target==='string'?target:target.agent;
+      const r=synchronize?await synchronize(agent):spawnSync(process.execPath,[path.join(root,'bin','competitor-visual-canvas.mjs'),'skill','update','--agent',agent,...(target.path?['--path',target.path]:[]),'--json'],{encoding:'utf8',timeout:120000,env:{...process.env,COMPETITOR_CANVAS_AUTO_UPDATE:'0'},windowsHide:true});
       requireValue(r.status===0,'SKILL_SYNC_FAILED','Package installed, but managed Skill synchronization failed.',{agent,backup});
     }
     return {version,backup,skills_synchronized:targets};
@@ -105,7 +104,10 @@ export async function performUpdate({automatic=true,dir=stateRoot(),root=ROOT,cu
     const selected=await targets();
     config.last_check=now;await store(config,dir);
     const version=await latest();config.latest=version;delete config.error;
-    if(!newer(version,current)){await store(config,dir);return {ok:true,current,latest:version,updated:false};}
+    if(!newer(version,current)){if(!automatic){requireValue(selected.length,'TARGET_UNRESOLVED','Select --agent and --path before update.');for(const t of selected){const {install}=await import('./skills.mjs');await install(t.agent,{path:t.path});}}await store(config,dir);return {ok:true,current,latest:version,updated:false};}
+    const [major,minor]=current.split('.'),[nextMajor,nextMinor]=version.split('.');
+    if(automatic&&(env.COMPETITOR_CANVAS_AUTO_INSTALL!=='1'||major!==nextMajor||major==='0'&&minor!==nextMinor)){await store(config,dir);return {ok:true,current,latest:version,updateAvailable:true,updated:false,action:'update install --agent CURRENT --path RESOLVED --yes'};}
+    requireValue(selected.length,'TARGET_UNRESOLVED','Select --agent and --path before package replacement.');
     const result=await install(version,selected);config.last_update=Date.now();config.installed=version;delete config.error;await store(config,dir);
     return {ok:true,updated:true,...result};
   }catch(e){

package/src/validate-package.mjs

@@ -0,0 +1,7 @@
+import fs from 'node:fs/promises';
+import {META,ROOT} from './core.mjs';
+import path from 'node:path';
+const caps=JSON.parse(await fs.readFile(path.join(ROOT,'skills/competitor-visual-canvas/capabilities.json')));
+if(caps.skill!=='competitor-visual-canvas'||META.name!=='@petercjl/competitor-visual-canvas')throw Error('PACKAGE_IDENTITY_MISMATCH');
+for(const name of ['INSTALL.md','UPDATE.md','skills/competitor-visual-canvas/SKILL.md'])if(!(await fs.readFile(path.join(ROOT,name),'utf8')).trim())throw Error('MISSING_RESOURCE');
+console.error('Validated package identity '+META.name+'@'+META.version+'; Skill source and install receipts derive version from package metadata.');

package/src/workflow.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import {spawn} from 'node:child_process';
 import {createRequire} from 'node:module';
 const dependencyRequire=createRequire(import.meta.url);
-function bundledEntry(tool){try{const name=tool==='tbcli'?'@petercjl/tbcli':'@petercjl/sealseek-media-cli';const file=dependencyRequire.resolve(name+'/package.json');const pkg=dependencyRequire(name+'/package.json');return path.join(path.dirname(file),pkg.bin[tool]);}catch{return null;}}
+function bundledEntry(tool){try{const name={'tbcli':'@petercjl/tbcli','sealseek-media':'@petercjl/sealseek-media-cli','boardmixcli':'@petercjl/boardmixcli'}[tool];const file=dependencyRequire.resolve(name+'/package.json');const pkg=dependencyRequire(name+'/package.json');return path.join(path.dirname(file),pkg.bin[tool]);}catch{return null;}}
 
 export const fail=(code,message)=>{throw Object.assign(new Error(message),{code});};
 export const uid=x=>crypto.createHash('sha256').update(JSON.stringify(x)).digest('hex').slice(0,24);
@@ -15,7 +15,7 @@ export async function create(p,v){if(await exists(p))fail('OUTPUT_EXISTS','Outpu
 export async function checkpoint(p,v){if(await exists(p)){const old=await read(p);if(old.run_id!==v.run_id)fail('STATE_CONFLICT','Run state ownership mismatch.');const backup=p+'.'+crypto.randomUUID()+'.backup';await fs.copyFile(p,backup,fs.constants.COPYFILE_EXCL);if((await fs.stat(backup)).size!==(await fs.stat(p)).size)fail('BACKUP_FAILED','Backup failed.');await fs.writeFile(p,JSON.stringify(v,null,2)+'\n',{mode:0o600});}else await create(p,v);}
 export const TOOLS_FILE=path.join(os.homedir(),'.config','competitor-visual-canvas','tools.json');
 export async function configureTool(tool,entry){
-  if(!['tbcli','sealseek-media'].includes(tool))fail('INVALID_INPUT','Unknown dependency.');
+  if(!['tbcli','sealseek-media','boardmixcli'].includes(tool))fail('INVALID_INPUT','Unknown dependency.');
   if(!path.isAbsolute(entry)||!await exists(entry))fail('INVALID_INPUT','Entry must be an existing absolute CLI path.');
   const old=await exists(TOOLS_FILE)?await read(TOOLS_FILE):{run_id:'competitor-visual-canvas-tools',owner:'@petercjl/competitor-visual-canvas',entries:{}};
   if(old.owner!=='@petercjl/competitor-visual-canvas')fail('STATE_CONFLICT','User-owned tool configuration preserved.');
@@ -23,9 +23,9 @@ export async function configureTool(tool,entry){
 }
 export async function invoke(tool,args){
   const cfg=await exists(TOOLS_FILE)?await read(TOOLS_FILE):null;
-  const entry=process.env[tool==='tbcli'?'TBCLI_ENTRY':'SEALSEEK_MEDIA_ENTRY']||cfg?.entries?.[tool]||bundledEntry(tool)||tool;
+  const entry=process.env[{'tbcli':'TBCLI_ENTRY','sealseek-media':'SEALSEEK_MEDIA_ENTRY','boardmixcli':'BOARDMIXCLI_ENTRY'}[tool]]||cfg?.entries?.[tool]||bundledEntry(tool)||tool;
   const node=/\.mjs$|\.js$/.test(entry),cmd=node?process.execPath:entry,argv=node?[entry,...args]:args;
-  return new Promise((resolve,reject)=>{const child=spawn(cmd,argv,{env:{...process.env,TBCLI_UPDATE_CHECK:'0',SEALSEEK_MEDIA_AUTO_UPDATE:'0'},stdio:['ignore','pipe','pipe']});let out='',err='';const timer=setTimeout(()=>child.kill(),180000);child.stdout.on('data',x=>out+=x);child.stderr.on('data',x=>err+=x);child.on('error',reject);child.on('close',code=>{clearTimeout(timer);if(code!==0)return reject(Object.assign(new Error(tool+' operation failed: '+(err||out).slice(-1200)),{code:'DEPENDENCY_FAILED'}));try{resolve(JSON.parse(out));}catch{reject(Object.assign(new Error(tool+' returned invalid JSON'),{code:'OUTPUT_CONTRACT_FAILED'}));}});});
+  return new Promise((resolve,reject)=>{const child=spawn(cmd,argv,{env:{...process.env,TBCLI_UPDATE_CHECK:'0',SEALSEEK_MEDIA_AUTO_UPDATE:'0',BOARDMIXCLI_UPDATE_CHECK:'0'},stdio:['ignore','pipe','pipe']});let out='',err='';const timer=setTimeout(()=>child.kill(),180000);child.stdout.on('data',x=>out+=x);child.stderr.on('data',x=>err+=x);child.on('error',reject);child.on('close',code=>{clearTimeout(timer);if(code!==0)return reject(Object.assign(new Error(tool+' operation failed: '+(err||out).slice(-1200)),{code:'DEPENDENCY_FAILED'}));try{resolve(JSON.parse(out));}catch{reject(Object.assign(new Error(tool+' returned invalid JSON'),{code:'OUTPUT_CONTRACT_FAILED'}));}});});
 }
 export function normalizeInputs(inputs){
   const seen=new Set(),result=[];
@@ -35,17 +35,18 @@ export function normalizeInputs(inputs){
 }
 export function normalizeProduct(input,raw){
   const d=raw.detail;if(raw.itemId!==input.id||d?.itemId!==input.id)fail('ITEM_ID_MISMATCH','Collection identity mismatch.');if(!d.title||!d.shop?.shopName)fail('OUTPUT_CONTRACT_FAILED','Product title and shop name are required.');
-  const make=(kind,values)=>{const seen=new Map();values.forEach((value,i)=>{const a=typeof value==='string'?{url:value}:value;if(!a?.url)return;const old=seen.get(a.url);if(old){if(a.skuOptions)old.skuOptions.push(...a.skuOptions);return;}seen.set(a.url,{...a,asset_id:uid([input.id,kind,a.url]),kind:kind==='main_videos'?'video':'image',source_index:i,...(a.skuOptions?{skuOptions:[...a.skuOptions]}:{})});});return [...seen.values()];};
+  const make=(kind,values)=>{const seen=new Map();values.forEach((value,i)=>{const a=typeof value==='string'?{url:value}:value;if(!a?.url)return;delete a.local_file;delete a.sha256;const old=seen.get(a.url);if(old){if(a.skuOptions)old.skuOptions.push(...a.skuOptions);return;}seen.set(a.url,{...a,asset_id:uid([input.id,kind,a.url]),kind:kind==='main_videos'?'video':'image',source_index:i,...(a.skuOptions?{skuOptions:[...a.skuOptions]}:{})});});return [...seen.values()];};
   return {...input,title:d.title,shop:d.shop,coverage:raw.coverage,assets:{
     main_images:make('main_images',d.mainImages||[]),main_videos:make('main_videos',raw.mainVideos?.records||[]),
     detail_images:make('detail_images',raw.description?.images||[]),
     sku_images:make('sku_images',(d.properties||[]).flatMap(p=>p.values.filter(v=>v.imageUrl).map(v=>({url:v.imageUrl,skuOptions:[{pid:p.pid,property:p.name,vid:v.vid,name:v.name,skuIds:(d.skus||[]).filter(s=>s.options.some(o=>o.pid===p.pid&&o.vid===v.vid)).map(s=>s.skuId)}]}))))
   }};
 }
-export async function collect(run,inputs,rawFiles=[]){
+export async function collect(run,inputs,rawFiles=[],target='infinite-canvas'){
+  if(!['infinite-canvas','boardmix'].includes(target))fail('INVALID_TARGET','Choose infinite-canvas or boardmix.');
   if(await exists(run))fail('OUTPUT_EXISTS','Choose a new run directory.');
-  const products=normalizeInputs(inputs),run_id=crypto.randomUUID();await fs.mkdir(run,{recursive:true,mode:0o700});await create(path.join(run,'inputs.json'),{run_id,products});
-  const manifest={schema_version:1,run_id,captured_at:new Date().toISOString(),products:[]};
+  const products=normalizeInputs(inputs),run_id=crypto.randomUUID();await fs.mkdir(run,{recursive:true,mode:0o700});await create(path.join(run,'inputs.json'),{run_id,products,target});
+  const manifest={schema_version:1,run_id,target,captured_at:new Date().toISOString(),products:[]};
   for(const input of products){
     let raw;if(rawFiles.length){for(const file of rawFiles){const r=await read(file);if(r.itemId===input.id){raw=r;break;}}if(!raw)fail('INPUT_MISSING','No raw collection for '+input.id);}else{const out=path.join(run,'raw',input.id+'.json');await fs.mkdir(path.dirname(out),{recursive:true});await invoke('tbcli',['item','media','--item-id',input.id,'--out',out,'--json']);raw=await read(out);}
     if(rawFiles.length)await create(path.join(run,'raw',input.id+'.json'),raw);
@@ -58,8 +59,9 @@ export function layout(manifest,options={}){
   if(base&&(base.schema_version!==2||base.presentation_version!==1))fail('LAYOUT_MIGRATION_REQUIRED','Migrate the existing run with reflow before appending.');
   const {width=320,gap=32,padding=32,frameGap=96,regionGap=240}=base?.layout_options||options;
   if(![width,gap,padding,frameGap,regionGap].every(Number.isFinite)||width<=0||[gap,padding,frameGap,regionGap].some(x=>x<0))fail('INVALID_INPUT','Invalid layout dimensions.');
+  const categories=options.categories||base?.regions?.map(r=>r.category)||REGIONS;
   const local={};
-  for(const category of REGIONS){local[category]=[];
+  for(const category of categories){local[category]=[];
     for(const product of manifest.products){
       const id='frame-'+uid([manifest.run_id,product.id,category]),placements=[];let localX=padding,localY=padding,maxX=padding,maxY=padding,rowHeight=0;
       for(const [i,a] of product.assets[category].entries()){
@@ -74,7 +76,7 @@ export function layout(manifest,options={}){
   }
   const frames=structuredClone(base?.batch.frames||[]),media=structuredClone(base?.batch.media||[]),regions=[];
   const reserve={main_images:2400,main_videos:1600,sku_images:1840,...options.columnWidths};let regionX=0;
-  for(const category of REGIONS){
+  for(const category of categories){
     const previous=base?.regions.find(r=>r.category===category);
     const horizontal=category==='detail_images';
     const columnWidth=previous?.width??Math.max(reserve[category]||0,...local[category].map(v=>v.frame.width));
@@ -105,6 +107,9 @@ export function validateLayout(plan){
   return true;
 }
 export async function planRun(run,options={}){
+  const target=(await read(path.join(run,'assets.manifest.json'))).target||'infinite-canvas';
+  if(options.target&&options.target!==target)fail('TARGET_CONFLICT','Requested target differs from the collected run.');
+  if(target==='boardmix')return (await import('./boardmix.mjs')).planBoardmix(run,options);
   for(const file of ['layout.plan.json','canvas.batch.json'])if(await exists(path.join(run,file)))fail('OUTPUT_EXISTS','Plan already exists; preserve it or use a new run.');
   const manifest=await read(path.join(run,'assets.manifest.json'));let base,baseManifest,state;
   if(options.baseRun){
@@ -116,7 +121,7 @@ export async function planRun(run,options={}){
   const cache=new Map(),all=manifest.products.flatMap(p=>Object.values(p.assets).flat()),urls=[...new Map(all.map(a=>[a.url,a])).values()];
   for(let i=0;i<urls.length;i+=4)await Promise.all(urls.slice(i,i+4).map(async a=>cache.set(a.url,a.width>0&&a.height>0?{width:a.width,height:a.height}:await invoke('sealseek-media',['media','inspect','--url',a.url,'--kind',a.kind,'--json']))));
   for(const a of all){const d=cache.get(a.url);a.width=d.width;a.height=d.height;}
-  const plan=layout(manifest,{...options,basePlan:base});
+  const plan=layout(manifest,{...options,basePlan:base});plan.target='infinite-canvas';
   if(base){plan.target_canvas_id=state.canvas_id;plan.base_snapshot=base.batch;manifest.products=[...baseManifest.products,...manifest.products];}
   await checkpoint(path.join(run,'assets.manifest.json'),manifest);
   await create(path.join(run,'layout.plan.json'),plan);await create(path.join(run,'canvas.batch.json'),plan.batch);
@@ -125,9 +130,10 @@ export async function planRun(run,options={}){
 export async function appendRun(run,baseRun,inputs,rawFiles=[]){
   const previous=await read(path.join(baseRun,'assets.manifest.json')),plan=await read(path.join(baseRun,'layout.plan.json'));
   if(plan.schema_version!==2)fail('LAYOUT_MIGRATION_REQUIRED','Run reflow on base canvas first.');
+  if(plan.target==='boardmix'){const s=await read(path.join(baseRun,'boardmix.state.json'));if(s.status!=='completed'||s.inflight)fail('STATE_CONFLICT','Base Boardmix run must be completed.');if(s.successor_run)fail('STALE_BASE_RUN','Append from the latest run: '+s.successor_run);}
   const fresh=normalizeInputs(inputs).filter(p=>!previous.products.some(old=>old.id===p.id));
   if(!fresh.length)return {changed:false,reason:'All requested products are already present.',base_run:baseRun};
-  await collect(run,fresh.map(p=>p.input),rawFiles);
+  await collect(run,fresh.map(p=>p.input),rawFiles,plan.target||'infinite-canvas');
   return planRun(run,{baseRun});
 }
 export function matchesBatch(readback,batch){
@@ -146,7 +152,7 @@ export function reconcileBatch(readback,batch){
   return result;
 }
 export async function publishCanvas(run,submit=false){
-  const plan=await read(path.join(run,'layout.plan.json'));validateLayout(plan);
+  const plan=await read(path.join(run,'layout.plan.json'));if(plan.target==='boardmix')fail('BOARDMIX_CONTEXT_REQUIRED','Use the Boardmix target dispatcher with explicit session and file key.');validateLayout(plan);
   const file=path.join(run,'canvas.batch.json');let batch=await read(file);if(JSON.stringify(batch)!==JSON.stringify(plan.batch))fail('STATE_CONFLICT','Batch differs from validated layout.');
   if(!submit)return {dry_run:true,title:plan.title,frames:batch.frames.length,media:batch.media.length};
   await invoke('sealseek-media',['canvas','batch','preview','--file',file,'--json']);