@oddessentials/agent-guild 1.29.0 → 1.30.0

package/web/yard/renderer.js

@@ -1,13 +1,18 @@
 import * as T from './vendor/engine.js';
 import { WORLDS, PROVIDER_ORDER, characterIndex, GILDED, CAMERA, SUN, minZoom, overviewFor, clampPan, viewBasis, providerPositions, sessionPose, familiarPose, hash,
-  stage, nextStagingChange, doorFor, arrives, route, clipFor, helperOffset, stationProp, hallActivity, lookTarget, lookLimits, STAGING, photoSize, marksFor, SHOWN_HELPERS } from './model.mjs';
+  stage, nextStagingChange, doorFor, arrives, route, clipFor, helperOffset, stationProp, hallActivity, lookTarget, lookLimits, yardExtras, playableClip, STAGING, photoSize, marksFor, SHOWN_HELPERS } from './model.mjs';
 
 const ASSETS = new URL('./assets/', import.meta.url);
 const vector = new T.Vector3();
 const lookModel = new T.Matrix4(), lookParent = new T.Matrix4(), lookFrame = new T.Quaternion(), lookTurn = new T.Quaternion(), lookTilt = new T.Quaternion();
 const axisX = new T.Vector3(1, 0, 0), axisY = new T.Vector3(0, 1, 0);
 const noop = () => {};
+const cancelled = new WeakSet();
+addEventListener('unhandledrejection', event => { if (cancelled.has(event.reason)) event.preventDefault(); });
+const cancel = loader => { const reason = new DOMException('This piece is no longer shown.', 'AbortError'); cancelled.add(reason); loader.abortController.abort(reason); };
 const worldFile = (skin, custom, file) => `../worlds/${skin}/${file.split('/').pop()}?v=${custom.revision}`;
+const pieceFiles = (skin, slot, piece) => (slot === 'companion' ? [0, 1, 2, 3].map(n => `companion_${n}.glb`) : ['character.glb'])
+  .map(file => new URL(`../pieces/${skin}/${slot}/${file}?v=${piece.revision}`, ASSETS).href);
 const vector2 = new T.Vector2();
 // How fast characters turn to a new heading, in radians a second, and how
 // long a clip change blends.
@@ -82,6 +87,21 @@ function disposeSkeletons(root) {
   root?.traverse(node=>{if(node.skeleton)skeletons.add(node.skeleton);});
   for(const skeleton of skeletons)skeleton.dispose();
 }
+function checkPiece({scene,animations}) {
+  if(!animations.every(playableClip))throw new Error('An animation in this piece has values the Yard cannot play.');
+  const probe=T.cloneSkeleton(scene);
+  try {
+    probe.updateMatrixWorld(true);
+    probe.traverse(node=>{
+      if(!node.isMesh)return;
+      const vertices=node.geometry.attributes.position?.count,triangles=node.geometry.index?.array;
+      if(!vertices||(triangles&&!triangles.every(at=>at<vertices)))throw new Error('A mesh in this piece refers to vertices it does not have.');
+      if(!node.isSkinnedMesh)return;
+      node.skeleton.update();node.computeBoundingBox();node.computeBoundingSphere();
+      if(!Number.isFinite(node.boundingSphere?.radius))throw new Error('A rigged mesh in this piece cannot be drawn.');
+    });
+  } finally {disposeSkeletons(probe);}
+}
 function disposeTree(root) {
   disposeSkeletons(root);
   const geometries=new Set(),materials=new Set();
@@ -119,8 +139,9 @@ function disposeWorld(root) {
 }
 export class YardRenderer {
   // clock gives the time staging is judged at; tests pass a fixed one.
-  constructor(host,labels,{select,open,error=noop,clock=Date.now}) {
-    this.host=host;this.labels=labels;this.onSelect=select;this.onOpen=open;this.onError=error;this.clock=clock;
+  constructor(host,labels,{select,open,error=noop,piece=noop,clock=Date.now}) {
+    this.host=host;this.labels=labels;this.onSelect=select;this.onOpen=open;this.onError=error;this.onPiece=piece;this.clock=clock;
+    this.pieceSets={};this.shownPieces={skin:null,pieces:{}};this.pieceLoaders=new Map();this.preloads=new Map();
     this.scene=new T.Scene();this.units=new Map();this.halls=new Map();this.slots=new Map();this.cache=new Map();
     this.loadingManager=new T.LoadingManager();
     this.providers=[];this.sessions=[];this.selected=null;this.world=null;this.skin=null;this.request=0;this.worldRequest=0;this.pending=null;
@@ -177,20 +198,29 @@ export class YardRenderer {
     this.resizeObserver=new ResizeObserver(()=>this.resize());this.resizeObserver.observe(host);
     this.resize();this.overview();
   }
-  async asset(name) {
+  async asset(name,url) {
     if(!this.cache.has(name)) {
-      const pending=new T.GLTFLoader(this.loadingManager).loadAsync(new URL(name+'.glb',ASSETS).href).catch(err=>{
+      const failed=[],manager=url?new T.LoadingManager():this.loadingManager;
+      if(url){manager.onError=item=>failed.push(item);this.pieceLoaders.set(name,manager);}
+      const pending=new T.GLTFLoader(manager).loadAsync(url||new URL(name+'.glb',ASSETS).href).then(asset=>{
+        try {
+          if(failed.length)throw new Error('A texture in this piece could not be drawn.');
+          if(url)checkPiece(asset);
+          return asset;
+        } catch(err){disposeTree(asset.scene);throw err;}
+      }).catch(err=>{
         if(this.cache.get(name)===pending)this.cache.delete(name);
         throw err;
       });
       this.cache.set(name,pending);
+      if(url)pending.catch(noop).finally(()=>{if(this.pieceLoaders.get(name)===manager)this.pieceLoaders.delete(name);});
     }
     return this.cache.get(name);
   }
-  goldAsset(name) {
+  goldAsset(name,url) {
     const key='gold:'+name;
     if(!this.cache.has(key)) {
-      const pending=this.asset(name).then(asset=>{const scene=T.cloneSkeleton(asset.scene);gild(scene);return {...asset,scene};}).catch(err=>{
+      const pending=this.asset(name,url).then(asset=>{const scene=T.cloneSkeleton(asset.scene);gild(scene);return {...asset,scene};}).catch(err=>{
         if(this.cache.get(key)===pending)this.cache.delete(key);
         throw err;
       });
@@ -198,6 +228,59 @@ export class YardRenderer {
     }
     return this.cache.get(key);
   }
+  activePieces() { return this.pieceSets[this.skin]||{}; }
+  pieceSource(slot) {
+    const piece=this.activePieces()[slot];
+    return piece?{slot,revision:piece.revision,urls:pieceFiles(this.skin,slot,piece)}:null;
+  }
+  // skin's pieces by slot, each { revision }; a slot without one shows the original.
+  setPieces(skin,pieces) {
+    this.pieceSets[skin]=pieces;
+    if(skin===this.skin)this.applyPieces();
+  }
+  applyPieces() {
+    if(this.disposed||!this.world)return;
+    const before=this.shownPieces,after={skin:this.skin,pieces:{...this.activePieces()}};
+    const changed=[...new Set([...Object.keys(before.pieces),...Object.keys(after.pieces)])]
+      .filter(slot=>before.skin!==after.skin||before.pieces[slot]?.revision!==after.pieces[slot]?.revision);
+    if(!changed.length&&before.skin===after.skin)return;
+    this.shownPieces=after;
+    if(before.skin===after.skin)for(const unit of this.units.values()){
+      if(changed.includes('companion'))this.clearHelpers(unit);
+      if(changed.includes(PROVIDER_ORDER[characterIndex(unit.session.provider.id)])){this.dropModel(unit);this.loadUnit(unit,unit.session);}
+      if(changed.includes('companion')&&unit.loaded)this.helpers(unit,unit.session);
+    }
+    for(const slot of changed){
+      if(before.pieces[slot]){this.preloads.delete(slot);for(const url of pieceFiles(before.skin,slot,before.pieces[slot]))this.release(url);}
+      if(after.pieces[slot])this.preload(slot,after.pieces[slot]);
+    }
+  }
+  preload(slot,piece) {
+    const skin=this.skin,attempt={};
+    this.preloads.set(slot,attempt);
+    Promise.all(pieceFiles(skin,slot,piece).map(url=>this.asset(url,url))).then(()=>true,()=>false).then(ok=>{
+      if(this.preloads.get(slot)!==attempt)return;
+      this.preloads.delete(slot);
+      if(!this.disposed&&this.skin===skin&&this.activePieces()[slot]?.revision===piece.revision)this.onPiece({skin,slot,revision:piece.revision,ok});
+    });
+  }
+  pieceFailed(source) {
+    if(this.activePieces()[source.slot]?.revision===source.revision)this.onPiece({skin:this.skin,slot:source.slot,revision:source.revision,ok:false});
+  }
+  release(name) {
+    const loader=this.pieceLoaders.get(name);if(loader){cancel(loader);this.pieceLoaders.delete(name);}
+    for(const key of [name,'gold:'+name]){
+      const pending=this.cache.get(key);
+      if(!pending)continue;
+      this.cache.delete(key);
+      pending.then(asset=>disposeTree(asset.scene)).catch(noop);
+    }
+  }
+  dropModel(unit) {
+    for(const mixer of unit.mixers){mixer.stopAllAction();mixer.uncacheRoot(mixer.getRoot());}
+    if(unit.model){unit.root.remove(unit.model);disposeSkeletons(unit.model);}
+    Object.assign(unit,{mixers:[],model:null,loaded:false,loading:false,animations:null,action:null,clip:null,lookBones:null,looking:false,load:(unit.load||0)+1});
+  }
   // Shows skin's world in theme, or only theme's plates when that world is
   // already up. What is on screen stays until the new world or theme is
   // ready; progress receives the bytes downloaded so far.
@@ -235,6 +318,7 @@ export class YardRenderer {
     this.halls.clear();
     if(this.world){this.scene.remove(this.world);disposeWorld(this.world);}
     this.world=loaded.scene;this.skin=skin;this.custom=custom;this.scene.add(this.world);
+    this.applyPieces();
     this.makeEffects(WORLDS[skin].effect);
     this.light(skin,theme);
     this.host.dataset.world=skin;
@@ -593,22 +677,24 @@ export class YardRenderer {
   }
   async loadUnit(unit,session) {
     if(unit.loaded||unit.loading)return;
-    const generation=this.request;
-    const prefix=WORLDS[this.skin].characters;
-    const index=characterIndex(session.provider.id);
+    const generation=this.request,token=unit.load=(unit.load||0)+1;
+    const index=characterIndex(session.provider.id),source=this.pieceSource(PROVIDER_ORDER[index]);
+    const name=source?source.urls[0]:WORLDS[this.skin].characters+index;
+    const stale=()=>this.disposed||generation!==this.request||token!==unit.load||!unit.root.parent;
     unit.loading=true;
     try {
-      const asset=await (GILDED.includes(session.provider.id)?this.goldAsset(prefix+index):this.asset(prefix+index));
-      if(this.disposed||generation!==this.request||!unit.root.parent)return;
+      const asset=await (GILDED.includes(session.provider.id)?this.goldAsset(name,source?.urls[0]):this.asset(name,source?.urls[0]));
+      if(stale())return;
       const model=T.cloneSkeleton(asset.scene);
       model.rotation.y=unit.heading;
-      model.traverse(n=>{if(n.isMesh){n.castShadow=true;n.receiveShadow=true;}});
+      model.traverse(n=>{if(n.isMesh){n.castShadow=true;n.receiveShadow=true;}if(n.isSkinnedMesh)n.frustumCulled=false;});
       unit.root.add(model);unit.model=model;unit.loaded=true;
       unit.label.title='';
       // The walk's stride and cycle, and where blows land, as rig.py wrote them.
       let yard=null;asset.scene.traverse(n=>{if(n.userData?.yard)yard=n.userData.yard;});
-      unit.speed=yard?.stride&&yard?.cycle?yard.stride/yard.cycle:1;
-      unit.events=yard?.events||[];unit.height=yard?.height;unit.surface=yard?.surface;unit.look=lookLimits(yard);
+      yard=yardExtras(yard,'character');
+      unit.speed=yard.stride/yard.cycle;
+      unit.events=yard.events;unit.height=yard.height;unit.surface=yard.surface;unit.look=lookLimits(yard.look);
       const neck=model.getObjectByName('Neck'),head=model.getObjectByName('Head');
       unit.lookBones=neck&&head&&model.getObjectByName('LeftUpperLeg')?{neck,head}:null;
       this.scaleProp(unit.session?.id||session.id);
@@ -618,8 +704,10 @@ export class YardRenderer {
       unit.clip=null;this.play(unit);
       this.helpers(unit,unit.session||session);this.dirty=true;this.drawOnce();
     } catch(err){
-      if(!this.disposed&&generation===this.request&&unit.root.parent){console.warn('Yard character unavailable:',err.message);unit.label.title='Character art unavailable. Session controls remain available.';}
-    } finally {unit.loading=false;}
+      if(stale())return;
+      if(source){this.pieceFailed(source);return;}
+      console.warn('Yard character unavailable:',err.message);unit.label.title='Character art unavailable. Session controls remain available.';
+    } finally {if(token===unit.load)unit.loading=false;}
   }
   // A hall's own copies of the materials that glow with its crew, so one
   // hall lighting up does not light the others that share them.
@@ -1055,28 +1143,47 @@ export class YardRenderer {
     if(helper.action){if(this.reduced)helper.action.stop();else helper.action.crossFadeTo(action,FADE,false);}
     helper.action=action;
   }
+  clearHelpers(unit) {
+    unit.revision++;unit.helperSignature=null;
+    for(const helper of unit.helpers){unit.crew.remove(helper.model);helper.mixer?.stopAllAction();helper.mixer?.uncacheRoot(helper.model);disposeSkeletons(helper.model);}
+    unit.helpers=[];
+    this.dirty=true;this.drawOnce();
+  }
   async helpers(unit,session) {
     const agents=helpersFor(session);
-    const signature=JSON.stringify(agents);
+    const kinds=WORLDS[this.skin].helpers,source=this.pieceSource('companion');
+    const signature=JSON.stringify([source?.revision??null,agents]);
     if(unit.helperSignature===signature)return;
+    this.clearHelpers(unit);
     unit.helperSignature=signature;
-    const rev=++unit.revision,generation=this.request;
-    for(const helper of unit.helpers){unit.crew.remove(helper.model);helper.mixer?.stopAllAction();helper.mixer?.uncacheRoot(helper.model);disposeSkeletons(helper.model);}
-    unit.helpers=[];
-    const kinds=WORLDS[this.skin].helpers;
+    const rev=unit.revision,generation=this.request;
+    const stale=()=>this.disposed||generation!==this.request||rev!==unit.revision||!unit.root.parent;
+    let pieces=null;
+    if(source&&agents.length){
+      try {pieces=await Promise.all(source.urls.map(url=>this.asset(url,url)));}
+      catch {
+        if(stale())return;
+        unit.helperSignature=null;
+        this.pieceFailed(source);
+        return;
+      }
+      if(stale())return;
+    }
     // The full helper count and all helper details remain in the canonical inspector.
     // Small squads preserve readable character silhouettes at the overview scale.
     await Promise.all(agents.slice(0,SHOWN_HELPERS).map(async(agent,i)=>{
       try {
-        const asset=await this.asset((agent.shell?kinds.shell:kinds.agent)+(hash(agent.name||agent.id)%4));
-        if(this.disposed||generation!==this.request||rev!==unit.revision||!unit.root.parent)return;
+        const n=hash(agent.name||agent.id)%4;
+        const asset=pieces?pieces[n]:await this.asset((agent.shell?kinds.shell:kinds.agent)+n);
+        if(stale())return;
         const model=T.cloneSkeleton(asset.scene);
+        model.traverse(n=>{if(n.isSkinnedMesh)n.frustumCulled=false;});
         const offset=helperOffset(i,agents.length);
         model.scale.setScalar(.45);model.position.set(unit.root.position.x+offset.x,.27,unit.root.position.z+offset.z);
         unit.crew.add(model);
         const mixer=new T.AnimationMixer(model);
         let yard=null;asset.scene.traverse(n=>{if(n.userData?.yard)yard=n.userData.yard;});
-        const helper={id:agent.id,top:(yard?.height||1)*model.scale.y,model,mixer,offset,pose:agent.pose,clips:asset.animations,moving:false,action:null};
+        const helper={id:agent.id,top:yardExtras(yard,'helper').height*model.scale.y,model,mixer,offset,pose:agent.pose,clips:asset.animations,moving:false,action:null};
         this.helperClip(helper,agent.pose);
         mixer.update(.3+(hash(agent.id)%40)/10);
         unit.helpers.push(helper);
@@ -1084,7 +1191,7 @@ export class YardRenderer {
       } catch {
         // The next state transition can rebuild this incomplete squad. Routine
         // unchanged updates do not call helpers(), so failure cannot loop.
-        if(!this.disposed&&generation===this.request&&rev===unit.revision&&unit.root.parent)unit.helperSignature=null;
+        if(!stale())unit.helperSignature=null;
       }
     }));
   }
@@ -1154,6 +1261,8 @@ export class YardRenderer {
     const rect=this.canvas.getBoundingClientRect();
     this.pointer.set((event.clientX-rect.left)/rect.width*2-1,-(event.clientY-rect.top)/rect.height*2+1);
     this.ray.setFromCamera(this.pointer,this.camera);
+    // A skinned mesh keeps the bounds of the pose it first had; picking needs the pose on screen.
+    for(const unit of this.units.values())for(const root of [unit.root,unit.crew])root?.traverse(n=>{if(!n.isSkinnedMesh)return;n.computeBoundingSphere();if(n.boundingBox)n.computeBoundingBox();});
     const hits=this.ray.intersectObjects([...this.halls.values(),...this.units.values()].flatMap(i=>i.crew?[i.root,i.crew]:[i.root]),true);
     for(const hit of hits) { for(let node=hit.object;node;node=node.parent) if(node.userData.entity)return node.userData.entity; }
     return null;
@@ -1341,7 +1450,7 @@ export class YardRenderer {
     this.clearFireworks();this.fireworkTexture?.dispose();
     for(const spark of this.sparks){spark.points.geometry.dispose();spark.points.material.dispose();}this.sparks=[];
     this.releaseEffects();this.clearProps();
-    this.loadingManager.abort();this.pending?.close();this.pending=null;
+    this.loadingManager.abort();for(const loader of this.pieceLoaders.values())cancel(loader);this.pieceLoaders.clear();this.pending?.close();this.pending=null;
     this.resizeObserver.disconnect();this.controls.dispose();this.clearUnits();
     for(const item of this.halls.values()){item.label.remove();item.chip.remove();}this.halls.clear();this.list.remove();
     disposeWorld(this.world);

package/web/yard/view.js

@@ -1,4 +1,4 @@
-import { WORLDS, sessionPose } from './model.mjs';
+import { WORLDS, PROVIDER_ORDER, sessionPose } from './model.mjs';
 
 const $ = id => document.getElementById(id);
 const make = (tag, cls, text) => Object.assign(document.createElement(tag), { className: cls, ...(text === undefined ? {} : { textContent: text }) });
@@ -17,6 +17,8 @@ async function boundedLoad(start, onProgress) {
   } finally { settled = true; clearTimeout(timer); }
 }
 const megabytes = bytes => (bytes / 1048576).toFixed(1) + ' MB';
+const CREWS = { anthropic: 'Claude Code', openai: 'Codex CLI', google: 'Antigravity CLI', xai: 'Grok Build', shell: 'Shell', docker: 'Docker Agent' };
+const pieceKind = slot => slot === 'companion' ? 'companion' : 'character';
 
 /** A layout with injected canonical controls. No API, sockets, or business rules. */
 export function initYard(controller) {
@@ -36,9 +38,18 @@ export function initYard(controller) {
     return world && !world.problem && unloadable.get(skin) !== world.revision ? world : null;
   };
   const titleFor = (skin) => customFor(skin)?.title ?? WORLDS[skin].title;
+  const worldShown = new Map();
   const loadWorld = (target, skin, theme, progress) => {
+    if (target.skin !== skin) {
+      worldShown.delete(skin);
+      for (const [key, shown] of pieceShown) if (key.startsWith(skin + '/') && shown.ok) pieceShown.delete(key);
+      target.setPieces(skin, piecesFor(skin));
+      worldSpot();
+    }
     const custom = customFor(skin);
-    return target.setWorld(skin, theme, { progress, custom }).catch((err) => {
+    return target.setWorld(skin, theme, { progress, custom }).then(() => {
+      if (custom) { worldShown.set(skin, custom.revision); worldSpot(); }
+    }, (err) => {
       if (!custom || disposed) throw err;
       unloadable.set(skin, custom.revision);
       if (skin === lastSkin) lastRevision = null;
@@ -46,6 +57,99 @@ export function initYard(controller) {
       return target.setWorld(skin, theme, { progress });
     });
   };
+  const pieceShown = new Map();
+  const pieceKey = (skin, slot) => skin + '/' + slot;
+  const piecesOf = (skin) => controller.yardPieces?.(skin) ?? {};
+  const piecesFor = (skin) => {
+    const pieces = {};
+    for (const [slot, piece] of Object.entries(piecesOf(skin))) {
+      const shown = pieceShown.get(pieceKey(skin, slot));
+      if (piece.revision && !(shown?.revision === piece.revision && !shown.ok)) pieces[slot] = { revision: piece.revision };
+    }
+    return pieces;
+  };
+  const syncPieces = (target) => {
+    const skin = root.dataset.skin;
+    if (target && WORLDS[skin]) target.setPieces(skin, piecesFor(skin));
+  };
+  const pieceDrawn = ({ skin, slot, revision, ok }) => {
+    if (disposed || piecesOf(skin)[slot]?.revision !== revision) return;
+    const key = pieceKey(skin, slot), was = pieceShown.get(key);
+    if (was?.revision === revision && (!was.ok || was.ok === ok)) return;
+    pieceShown.set(key, { revision, ok });
+    if (!ok) for (const target of [renderer, pendingRenderer]) target?.setPieces(skin, piecesFor(skin));
+    worldSpot();
+  };
+  function worldStatus(skin) {
+    const world = controller.yardWorld(skin);
+    if (!world) return { state: 'original', text: 'Original' };
+    if (world.problem) return { state: 'failed', text: world.problem + ' Showing the original.' };
+    if (!customFor(skin)) return { state: 'failed', text: world.title + ' could not load. Showing the original.' };
+    return worldShown.get(skin) === world.revision ? { state: 'custom', text: 'Customized: ' + world.title } : { state: 'loading', text: 'Loading ' + world.title + '…' };
+  }
+  function pieceStatus(skin, slot) {
+    const piece = piecesOf(skin)[slot], kind = pieceKind(slot);
+    if (!piece) return { state: 'original', text: 'Original' };
+    if (piece.problem) return { state: 'failed', text: piece.problem + ' Showing the original ' + kind + '.' };
+    const shown = pieceShown.get(pieceKey(skin, slot));
+    if (shown?.revision !== piece.revision) return { state: 'loading', text: 'Loading ' + piece.title + '…' };
+    return shown.ok ? { state: 'custom', text: 'Customized: ' + piece.title } : { state: 'failed', text: piece.title + ' could not load. Showing the original ' + kind + '.' };
+  }
+  const slotName = (slot) => slot === 'world' ? 'World' : slot === 'companion' ? 'Companions' : snapshot.providers.find(p => p.id === slot)?.tool || CREWS[slot];
+  const customizeRows = new Map();
+  function customizeRow(slot) {
+    if (customizeRows.has(slot)) return customizeRows.get(slot);
+    const row = make('li', 'flag-row yard-customize-row'), copy = make('div', 'yard-customize-copy'), actions = make('div', 'yard-customize-actions');
+    const name = make('span', 'flag-name'), status = make('span', 'yard-customize-status'), note = make('span', 'yard-customize-note');
+    const replace = make('button', 'btn', 'Replace'), restore = make('button', 'btn', 'Restore original');
+    replace.type = restore.type = 'button';
+    note.hidden = slot === 'world';
+    const skin = () => root.dataset.skin;
+    replace.addEventListener('click', () => slot === 'world' ? controller.replaceYard(skin()) : controller.replacePiece(skin(), slot));
+    restore.addEventListener('click', () => slot === 'world' ? controller.restoreYard(skin()) : controller.restorePiece(skin(), slot));
+    copy.append(name, status, note);
+    actions.append(replace, restore);
+    row.append(copy, actions);
+    row.dataset.slot = slot;
+    const parts = { row, name, status, note, replace, restore };
+    customizeRows.set(slot, parts);
+    return parts;
+  }
+  function paintCustomize() {
+    const dialog = $('yard-customize'), skin = root.dataset.skin;
+    if (!dialog.open) return;
+    if (!WORLDS[skin]) { dialog.close(); return; }
+    $('yard-customize-sub').textContent = WORLDS[skin].title + ' only. Other Yards keep their own.';
+    const busy = Boolean(controller.yardBusy?.()) || !snapshot.connected;
+    const heading = (text) => {
+      if (!customizeRows.has(text)) { const item = make('li', 'yard-customize-heading', text); item.setAttribute('role', 'presentation'); customizeRows.set(text, item); }
+      return customizeRows.get(text);
+    };
+    const items = [];
+    for (const [title, slots] of [['Yard', ['world']], ['Characters', PROVIDER_ORDER], ['Companions', ['companion']]]) {
+      items.push(heading(title));
+      for (const slot of slots) {
+        const parts = customizeRow(slot), status = controller.yardChecking?.() === pieceKey(skin, slot) ? { state: 'loading', text: 'Checking replacement…' } : slot === 'world' ? worldStatus(skin) : pieceStatus(skin, slot);
+        const installed = slot === 'world' ? Boolean(controller.yardWorld(skin)) : Boolean(piecesOf(skin)[slot]);
+        parts.name.textContent = slotName(slot);
+        parts.status.textContent = status.text;
+        if (slot !== 'world') parts.note.textContent = slot === 'companion' ? 'Shows beside sessions with helpers in this Yard.'
+          : 'Shows on your ' + slotName(slot) + ' sessions in this Yard' + (slot === 'shell' ? ', and in gold on Terminal AI Chat’s.' : '.');
+        parts.row.dataset.state = status.state;
+        parts.replace.disabled = busy;
+        parts.restore.disabled = busy || !installed;
+        parts.replace.setAttribute('aria-label', 'Replace ' + slotName(slot));
+        parts.restore.setAttribute('aria-label', 'Restore the original ' + slotName(slot));
+        items.push(parts.row);
+      }
+    }
+    const list = $('yard-customize-list');
+    if (items.some((item, i) => list.children[i] !== item) || list.children.length !== items.length) {
+      const focused = list.contains(document.activeElement) ? document.activeElement : null;
+      list.replaceChildren(...items);
+      focused?.focus();
+    }
+  }
   function worldSpot() {
     const skin = root.dataset.skin;
     if (!WORLDS[skin]) return;
@@ -53,11 +157,11 @@ export function initYard(controller) {
     $('yard-title').textContent = titleFor(skin);
     $('yard-title').classList.toggle('yard-title-custom', Boolean(customFor(skin)));
     const reason = world?.problem || (world && !customFor(skin) ? world.title + ' could not load.' : '');
-    $('yard-world-replace').hidden = !controller.canReplaceYard();
-    $('yard-world-replace').textContent = world ? 'Replace' : 'Replace this Yard';
-    $('yard-world-restore').hidden = !world;
-    $('yard-world-note').hidden = !reason;
-    $('yard-world-note').textContent = reason && reason + ' This Yard is showing its original.';
+    const failed = !reason && Object.keys(piecesOf(skin)).map(slot => pieceStatus(skin, slot)).find(status => status.state === 'failed');
+    $('yard-customize-open').hidden = !controller.canReplaceYard();
+    $('yard-world-note').hidden = !reason && !failed;
+    $('yard-world-note').textContent = reason ? reason + ' This Yard is showing its original.' : failed ? failed.text : '';
+    paintCustomize();
   }
   const celebrate = () => { if (!disposed && sceneVisible()) renderer?.fireworks(); };
   const fireworksButton = () => {
@@ -96,7 +200,7 @@ export function initYard(controller) {
     if (allowed) yardChoice.parentElement.removeAttribute('title');
     else yardChoice.parentElement.title = `${skinEntry()?.name || 'This skin'} has no yard yet.`;
     $('yard').hidden = view !== 'yard';
-    if (view !== 'yard') closePhoto();
+    if (view !== 'yard') { closePhoto(); $('yard-customize').close(); }
     $('providers').hidden = view === 'yard';
     $('providers').inert = view === 'yard';
     for (const section of document.querySelectorAll('#app > section.sessions, #app > section.news')) {
@@ -176,6 +280,7 @@ export function initYard(controller) {
           select: next => select(next),
           open: id => controller.openSession(id),
           error: () => { if (attempt === sceneAttempt) failScene(); },
+          piece: pieceDrawn,
         });
         pendingRenderer = candidate;
         // Appearance can change while the first world is loading.
@@ -184,10 +289,12 @@ export function initYard(controller) {
           skin = root.dataset.skin; theme = root.dataset.theme;
           if (!WORLDS[skin]) { candidate.dispose(); return; }
           revision = customFor(skin)?.revision ?? null;
+          syncPieces(candidate);
           showLoading('Loading ' + titleFor(skin) + '…', 'scene');
           await boundedLoad(progress => loadWorld(candidate, skin, theme, progress), loadingProgress);
         } while (!disposed && !candidate.disposed && attempt === sceneAttempt && (skin !== root.dataset.skin || theme !== root.dataset.theme || revision !== (customFor(skin)?.revision ?? null)));
         if (disposed || candidate.disposed || attempt !== sceneAttempt) { candidate.dispose(); return; }
+        syncPieces(candidate);
         pendingRenderer = null;
         renderer = candidate;
         lastSkin = skin; lastTheme = theme; lastRevision = revision;
@@ -318,9 +425,10 @@ export function initYard(controller) {
         lastSkin = root.dataset.skin; lastTheme = root.dataset.theme; lastRevision = revision;
         swapWorld();
       }
+      syncPieces(renderer);
       renderer.update(snapshot.providers,snapshot.sessions);
       renderer.setActive(sceneVisible());
-    } else ensureScene();
+    } else { syncPieces(pendingRenderer); ensureScene(); }
   }
   $('view-cards').addEventListener('change',() => setView('cards'));
   $('view-yard').addEventListener('change',() => { if (skinAllowsYard()) setView('yard'); });
@@ -342,8 +450,12 @@ export function initYard(controller) {
     lastSkin = ''; lastTheme = '';
     update();
   });
-  $('yard-world-replace').addEventListener('click',() => controller.replaceYard(root.dataset.skin));
-  $('yard-world-restore').addEventListener('click',() => controller.restoreYard(root.dataset.skin));
+  $('yard-customize-open').addEventListener('click',() => {
+    if (!$('yard-customize').open) $('yard-customize').showModal();
+    paintCustomize();
+  });
+  $('yard-customize-close').addEventListener('click',() => $('yard-customize').close());
+  $('yard-customize').addEventListener('click',event => { if (event.target === $('yard-customize')) $('yard-customize').close(); });
   $('yard-filter').addEventListener('input',roster);
   $('yard-news').addEventListener('click',controller.openNews);
   $('yard-deselect').addEventListener('click',() => { select(null); $('yard-filter').focus(); });