@bitefoundry/retrieviewer 0.0.9 → 0.0.11

package/puppy-companion-life.mjs

@@ -1,33 +1,36 @@
 // Autonomous companion "life" controller layered over a paper puppy actor.
 // The parent calls actor.update(dt) THEN life.update(dt). Commands are only issued
 // while the actor rests at a shared safe endpoint (idle/down); everything else waits.
-// Exception: an accepted ball throw reacts at once via actor.chase (the actor owns safe
-// interruption); actors without chase fall back to go at the next safe endpoint.
+// Accepted interactions ask the actor for safe interruption: chase for a ball,
+// attend for a hand-fed treat/tug. Substitute actors can use safe-endpoint fallback.
 // Parameters are authored for feel, not canine science.
+import {paperCameraPoint,paperGroundTarget,PAPER_SCREEN,PAPER_CAMERA} from './puppy-paper-world.mjs';
+import {createBallPath,createFetchPatterns} from './puppy-companion-ball.mjs';
 
 const SAFE=new Set(['idle','down']);
+export const FETCH_RETURN_STYLES=Object.freeze(['auto','brake','trot','run-trot']);
 const HOME={x:0,z:.2};
 const BALL_TARGET={x:0,z:-4};
 const OFFER={x:0,z:.3};
 // Hand-fed treat marker, relative to the puppy's current root (no travel for treats).
 const TREAT_OFFSET={z:.08,height:.25};
 const COOLDOWN={ball:6,treat:15,tug:20};
-const FLIGHT=.65,BALL_PEAK=.75,CARRY_HEIGHT=.19,SETTLE_FALLBACK=.6,MAX_DT=.25,ARRIVE=.05;
+const CARRY_HEIGHT=.19,SETTLE_FALLBACK=.6,MAX_DT=.25,ARRIVE=.05;
 // Active simulation seconds, never a wall-clock timer that wakes a hidden pet.
 export const BUTTERFLY_RULES=Object.freeze({firstMin:240,firstSpread:240,cooldownMin:720,cooldownSpread:480,maxVisible:18});
 const LABEL={
  start:'기다리는 중',pause:'잠시 느긋하게 둘러보는 중',lie:'엎드리는 중',rest:'엎드려 쉬는 중',recover:'앉아서 기운 차리는 중',
  sit:'앉는 중',watch:'앉아서 지켜보는 중',look:'고개를 돌려 살피는 중',observe:'가만히 주변 관찰 중',
- stroll:'옆으로 살짝 걸어가는 중',sniff:'잠깐 멈춰 주변을 살피는 중',dash:'저 멀리 달려가는 중',far:'멀리서 둘러보는 중',home:'제자리로 돌아오는 중',
+ stroll:'옆으로 살짝 걸어가는 중',sniff:'잠깐 멈춰 주변을 살피는 중',dash:'저 멀리 달려가는 중',far:'멀리서 둘러보는 중',home:'제자리로 돌아오는 중',nest:'쉴 자리를 찾아가는 중',
  patrol:'주변을 왕복 산책하는 중',scan:'양쪽을 번갈아 살피는 중',roll:'느긋하게 뒹구는 중',play:'신나서 한 바퀴 도는 중',checkin:'가까이 와서 함께 쉬는 중',
  belly:'배를 보이고 발라당 쉬는 중',sleep:'새근새근 잠자는 중',tug:'장난감을 물고 당기는 중',
  butterflyNotice:'나비를 발견하고 귀를 쫑긋하는 중',butterfly:'나비를 폴짝폴짝 쫓는 중',butterflyBye:'날아가는 나비를 바라보는 중',
- fetch:'공을 쫓아가는 중',pickup:'공을 무는 중',carry:'공을 물고 돌아오는 중',drop:'공을 내려놓는 중',offer:'공을 내려놓고 기다리는 중',
+ fetch:'공을 쫓아가는 중',miss:'굴러가는 공을 한 번 놓친 중',reChase:'공을 다시 쫓아가는 중',tumble:'우당탕 균형을 되찾는 중',pickup:'공을 무는 중',carry:'공을 물고 돌아오는 중',drop:'공을 내려놓는 중',offer:'공을 내려놓고 기다리는 중',
  treatSit:'간식 앞에 앉는 중',chew:'간식 먹는 중'
 };
 const PENDING_LABEL={treat:'곧 간식',tug:'곧 터그놀이'};
 // Baked interaction clips, played only while holding at the shared seated endpoint.
-const GESTURE={'ball-pickup':1.4,'ball-drop':1.2,'treat-eat':2.4};
+const GESTURE={'ball-pickup':.65,'ball-drop':.65,'treat-eat':2.4};
 const clamp=(v,a,b)=>Math.min(b,Math.max(a,v));
 
 function mulberry32(seed){
@@ -35,13 +38,21 @@ function mulberry32(seed){
  return()=>{a=a+0x6d2b79f5>>>0;let t=a;t=Math.imul(t^t>>>15,t|1);t^=t+Math.imul(t^t>>>7,t|61);return((t^t>>>14)>>>0)/4294967296;};
 }
 
-export function createCompanionLife(actor,{seed=731,energy=.8}={}){
+export function createCompanionLife(actor,{seed=731,energy=.8,returnStyle='auto'}={}){
  for(const name of ['update','sample','go','come','sit','lie','look','walk','roll','rest'])
   if(!actor||typeof actor[name]!=='function')throw TypeError(`actor.${name} must be a function`);
  if(!Number.isInteger(seed))throw TypeError('seed must be an integer');
  if(!Number.isFinite(energy)||energy<0||energy>1)throw RangeError('energy must be within 0..1');
+ const validateReturnStyle=style=>{if(!FETCH_RETURN_STYLES.includes(style))throw RangeError('returnStyle must be auto, brake, trot or run-trot');if(['trot','run-trot'].includes(style)&&!actor.canCarryTrot)throw Error('Carry-trot artwork is not available');};
+ validateReturnStyle(returnStyle);
 
  const rand=mulberry32(seed),range=(a,b)=>a+(b-a)*rand(),side=()=>rand()<.5?'left':'right';
+ // Spatial choices get their own stream, like the rare visitor. Existing gait,
+ // energy and interaction timing do not depend on how a resting spot is picked.
+ const spaceRand=mulberry32(seed^0x28ae91c7),spaceRange=(a,b)=>a+(b-a)*spaceRand();
+ const toyRand=mulberry32(seed^0x6c82b14d),chooseFetch=createFetchPatterns(toyRand,{canTumble:actor.canScramble===true});
+ const returnRand=mulberry32(seed^0x73bca165);let lastReturnMode=null;
+ let placeSide=spaceRand()<.5?-1:1,outings=0,nearSeconds=0,lastCheckin=-Infinity;
  // Separate stream: the rare encounter does not perturb ordinary episodes/gaits.
  const encounterRand=mulberry32(seed^0x4bf17a93),encounterRange=(a,b)=>a+(b-a)*encounterRand();
  let nextButterfly=BUTTERFLY_RULES.firstMin+encounterRange(0,BUTTERFLY_RULES.firstSpread),butterfly=null;
@@ -51,6 +62,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
  let clock=0,decisions=0,lastEpisode=null,quiet=0;
  let queue=[],hold=0,holdIntent=null,waiting=null,gesture=null;
  let intent='start',label=LABEL.start,pending=null,active=null,ball=null,treat=null;
+ let fetchPlan=null;
 
  const cmd=(name,args,step,when)=>({cmd:name,args,intent:step,label:LABEL[step],when});
  const wait=(seconds,step)=>({hold:seconds,intent:step,label:LABEL[step]});
@@ -64,6 +76,22 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
  const sit=step=>cmd('sit',[],step,()=>!seatedAnyVariant());
  const lie=()=>cmd('lie',[],'lie',()=>actor.state!=='down');
  const walkTo=x=>cmd('walk',()=>{const dx=x-actor.sample(clock).x;return [dx<0?'left':'right',Math.abs(dx)];},'patrol',()=>Math.abs(x-actor.sample(clock).x)>.002);
+ const roomRadius=z=>Math.max(.12,paperCameraPoint(0,0,z).depth*PAPER_SCREEN.widthMeters/(2*PAPER_SCREEN.viewDistance)-PAPER_CAMERA.canvasMeters/2);
+ const place=nap=>{
+  // A nearer side nook keeps a sleeping face readable; outings also use the
+  // middle/far ground. X expands with camera depth, not a fixed world corridor.
+  const bands=[[1.4,3],[4,8],[.7,1.4],[9,15]],band=bands[outings++%bands.length];
+  const z=-(nap?spaceRange(.7,2.6):spaceRange(...band));placeSide*=-1;
+  return paperGroundTarget(placeSide*roomRadius(z)*spaceRange(.5,.8),z);
+ };
+ const travelTo=(target,step)=>cmd('go',target,step,()=>{const s=actor.sample(clock);return Math.hypot(s.x-target[0],s.z-target[1])>.12;});
+ const quietPlace=()=>{
+  const s=actor.sample(clock);
+  // Often stay in the nook just discovered, instead of shuffling before every
+  // nap. A front-and-center or very distant puppy first finds a quieter spot.
+  if(s.z<=-.5&&s.z>=-3.5&&Math.abs(s.x)>roomRadius(s.z)*.3&&spaceRand()<.65)return [];
+  return [travelTo(place(true),'nest')];
+ };
  const butterflyPoint=()=>{
   if(!butterfly)return null;
   const elapsed=clock-butterfly.since,p=clamp(elapsed/.65,0,1),ease=p*p*(3-2*p);
@@ -74,8 +102,9 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
    phase:((clock-butterfly.start)*5)%1,opacity:1-leaving};
  };
  const butterflyEpisode=()=>{
-  const s=actor.sample(clock),direction=encounterRand()<.5?-1:1;
-  const targets=[clamp(s.x+direction*.36,-.5,.5),clamp(s.x-direction*.38,-.5,.5),clamp(s.x+direction*.24,-.5,.5)];
+  const s=actor.sample(clock),radius=roomRadius(s.z);
+  const direction=s.x>radius-.3?-1:s.x< -radius+.3?1:encounterRand()<.5?-1:1;
+  const targets=[clamp(s.x+direction*.36,-radius,radius),clamp(s.x-direction*.38,-radius,radius),clamp(s.x+direction*.24,-radius,radius)];
   const z=s.z;
   const moveFly=x=>fx(()=>{
    const from=butterflyPoint()??{x:s.x-direction*.28,z};
@@ -88,29 +117,29 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   return [sit('butterflyNotice'),moveFly(targets[0]),cmd('look',[direction<0?'right':'left'],'butterflyNotice'),wait(.8,'butterflyNotice'),
    ...targets.flatMap((x,i)=>[...(i?[moveFly(x)]:[]),cmd(typeof actor.chase==='function'?'chase':'go',[x,z],'butterfly'),wait(.3,'butterfly')]),
    fx(()=>{if(butterfly)butterfly.leaving=clock;}),wait(1.1,'butterflyBye'),fx(()=>{butterfly=null;needs.energy-=.12;needs.curiosity-=.25;}),
-   home(),sit('recover'),wait(range(3,6),'recover')];
+   sit('recover'),wait(range(3,6),'recover')];
  };
 
  // Each episode is a short coherent plan; a pause always leads in so autonomy never stalls.
  const EPISODES={
-  rest:()=>[lie(),wait(range(10,18),'rest'),sit('recover'),wait(range(3,6),'recover')],
+  rest:()=>[...quietPlace(),lie(),wait(range(10,18),'rest'),sit('recover'),wait(range(3,6),'recover')],
   watch:()=>[sit('sit'),cmd('look',[side()],'look'),wait(range(3,9),'watch'),fx(()=>{needs.social-=.3;needs.curiosity+=.1;})],
   observe:()=>[sit('sit'),cmd('look',[side()],'look'),wait(range(3,9),'observe'),fx(()=>{needs.curiosity-=.15;})],
-  stroll:()=>[cmd('walk',[side(),range(.08,.18)],'stroll'),wait(range(2,4),'sniff'),home(),fx(()=>{needs.energy-=.08;needs.curiosity-=.2;})],
-  dash:()=>[cmd('go',[(rand()*2-1)*.18,-range(3,8)],'dash'),wait(range(1.5,3),'far'),home(),fx(()=>{needs.energy-=.3;needs.curiosity-=.4;})],
+  stroll:()=>[cmd('walk',[side(),range(.22,.5)],'stroll'),wait(range(4,9),'sniff'),fx(()=>{needs.energy-=.08;needs.curiosity-=.2;})],
+  dash:()=>[travelTo(place(false),'dash'),sit('far'),wait(range(8,16),'far'),fx(()=>{needs.energy-=.22;needs.curiosity-=.3;})],
   scan:()=>[sit('sit'),cmd('look',['left'],'scan'),wait(range(.5,1.5),'scan'),cmd('look',['right'],'scan'),wait(range(2,4),'observe'),fx(()=>{needs.curiosity-=.25;})],
   patrol:()=>{const x=actor.sample(clock).x,d=range(.16,.3)*(rand()<.5?-1:1);return [walkTo(x+d),wait(range(.6,1.2),'sniff'),walkTo(x-d),wait(range(.6,1.2),'sniff'),walkTo(x),wait(range(1,3),'observe'),fx(()=>{needs.energy-=.1;needs.curiosity-=.25;})];},
   roll:()=>[lie(),wait(range(.7,1.5),'rest'),cmd('roll',[],'roll'),wait(range(2,5),'watch'),fx(()=>{needs.energy-=.08;needs.curiosity-=.15;})],
   checkin:()=>[home(),sit('sit'),cmd('look',[side()],'look'),wait(range(5,10),'checkin'),fx(()=>{needs.social-=.4;})],
   play:()=>[cmd('spin',[],'play'),wait(range(1,2),'pause'),sit('sit'),wait(range(2,4),'watch'),fx(()=>{needs.energy-=.12;needs.curiosity-=.2;})],
   belly:()=>[cmd('belly',[range(5,9)],'belly'),wait(range(2,4),'watch'),fx(()=>{needs.energy+=.08;needs.curiosity-=.15;})],
-  sleep:()=>[cmd('sleep',[range(65,110),['side','curl','chin','belly'][Math.floor(rand()*4)],rand()<.5],'sleep'),wait(range(2,4),'recover'),fx(()=>{needs.energy+=.3;})],
+  sleep:()=>[...quietPlace(),cmd('sleep',[range(65,110),['side','curl','chin','belly'][Math.floor(rand()*4)],rand()<.5],'sleep'),wait(range(2,4),'recover'),fx(()=>{needs.energy+=.3;})],
   butterfly:butterflyEpisode,
  };
  const weights=()=>{
   const {energy:e,social:s,curiosity:c}=needs;
   return {rest:e<.35?6:(1-e)*1.2,watch:.8+s,observe:.6+c*.6,stroll:1.2*c*e,dash:e>.55?1.2*e*c:0,
-   scan:.35+c*.4,patrol:e>.25?.7*c*e:0,checkin:.25+s*.7,
+   scan:.35+c*.4,patrol:e>.25?.7*c*e:0,checkin:clock-lastCheckin>=90?.25+s*.7:0,
    roll:episodeCooldowns.roll===0&&e>.45?.35*e:0,
    play:episodeCooldowns.play===0&&e>.6&&typeof actor.spin==='function'?.25*e*c:0,
    belly:episodeCooldowns.belly===0&&typeof actor.belly==='function'?.35:0,
@@ -120,6 +149,9 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   const w=weights();if(lastEpisode)w[lastEpisode]=0;
   const kinds=Object.keys(w),total=kinds.reduce((sum,k)=>sum+w[k],0);
   let pick=rand()*total,kind=kinds.find(k=>(pick-=w[k])<0)??'observe';
+  // A bounded spell near the viewer, not a permanent home magnet. Let an active
+  // authored motion finish first; only the next episode changes its destination.
+  if(nearSeconds>=40&&needs.energy>.4&&lastEpisode!=='dash')kind='dash';
   // Quiet-time sleep pressure is independent of energy restored by sitting.
   // Wait for the current coherent episode to end; never yank a running puppy.
   if(quiet>=120&&needs.drowsiness>=.35&&episodeCooldowns.sleep===0&&lastEpisode!=='sleep'&&typeof actor.sleep==='function')kind='sleep';
@@ -128,6 +160,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
    kind='butterfly';nextButterfly=clock+BUTTERFLY_RULES.cooldownMin+encounterRange(0,BUTTERFLY_RULES.cooldownSpread);
   }
   lastEpisode=kind;decisions++;
+  if(kind==='checkin')lastCheckin=clock;
   if(kind==='roll')episodeCooldowns.roll=90;
   if(kind==='play')episodeCooldowns.play=120;
   if(kind==='belly')episodeCooldowns.belly=80;
@@ -135,15 +168,22 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   queue=[wait(range(3,9),'pause'),...EPISODES[kind]()];
  }
 
- const landed=()=>ball?.mode==='flight'&&clock-ball.start>=FLIGHT;
- const arrived=()=>{const s=actor.sample(clock);return SAFE.has(actor.state)&&Math.hypot(s.x-BALL_TARGET.x,s.z-BALL_TARGET.z)<ARRIVE;};
+ const landed=()=>ball?.mode==='flight'&&ball.path.at(clock-ball.start).settled;
+ const arrived=()=>{const s=actor.sample(clock),target=fetchPlan.pickupRoot;return SAFE.has(actor.state)&&Math.hypot(s.x-target.x,s.z-target.z)<ARRIVE;};
+ const fetchGo=typeof actor.chase==='function'?'chase':'go';
+ const directionalPickup=()=>{const s=actor.sample(clock);return actor.canPickup===true&&(s.seatProgress??0)===0&&['rear','front'].includes(s.view);};
  // The leading go is dropped when interact() already dispatched the chase; pickup waits for both arrival and landing.
  const BALL_STEPS=()=>[
-  cmd('go',[BALL_TARGET.x,BALL_TARGET.z],'fetch'),{until:()=>landed()&&arrived()},
-  fx(()=>{ball={mode:'ground',x:BALL_TARGET.x,z:BALL_TARGET.z};}),
-  cmd('sit',[],'pickup'),play('ball-pickup','pickup'),fx(()=>{ball={mode:'carried'};}),cmd('go',[HOME.x,HOME.z],'carry'),
-  cmd('sit',[],'drop',unseated),play('ball-drop','drop'),
-  fx(()=>{ball={mode:'ground',x:OFFER.x,z:OFFER.z};needs.social-=.4;}),wait(3,'offer'),fx(()=>{ball=null;})
+  cmd(fetchGo,[fetchPlan.first.x,fetchPlan.first.z,{scramble:fetchPlan.pattern==='tumble'}],'fetch'),
+  ...(fetchPlan.pattern==='miss'?[wait(.12,'miss'),cmd(fetchGo,[fetchPlan.pickupRoot.x,fetchPlan.pickupRoot.z],'reChase')]:[]),
+  ...(fetchPlan.pattern==='tumble'&&!actor.canSinglePassScramble?[...actor.canMovingScramble?[]:[cmd('scramble',[],'tumble')],cmd(fetchGo,[fetchPlan.pickupRoot.x,fetchPlan.pickupRoot.z],'reChase')]:[]),
+  {until:()=>landed()&&arrived()},
+  fx(()=>{ball={mode:'ground',...fetchPlan.stop};}),
+  cmd('pickup',[],'pickup',directionalPickup),
+  cmd('sit',[{urgent:true}],'pickup',()=>!directionalPickup()&&unseated()),{...play('ball-pickup','pickup'),when:()=>!directionalPickup()},
+  fx(()=>{ball={mode:'carried'};}),cmd(fetchGo,[HOME.x,HOME.z,{returnMode:fetchPlan.returnMode}],'carry'),
+  cmd('sit',[{urgent:true}],'drop',unseated),play('ball-drop','drop'),
+  fx(()=>{ball={mode:'dropped',start:clock,path:createBallPath({from:OFFER,landing:OFFER,stop:{x:OFFER.x+.035,z:OFFER.z+.06},flight:0,peak:0,deceleration:.2})};needs.social-=.4;}),wait(3,'offer'),fx(()=>{ball=null;fetchPlan=null;})
  ];
  // Hand-feed where the puppy already is: sit only if not front-seated, never go/walk/chase/come.
  const TREAT_STEPS=()=>[
@@ -158,12 +198,14 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   active=pending;pending=null;decisions++;hold=0;
   queue=active==='ball'?BALL_STEPS():active==='tug'?TUG_STEPS():TREAT_STEPS();
  }
- function finishInteraction(){cooldowns[active]=COOLDOWN[active];active=null;}
+ function finishInteraction(){cooldowns[active]=COOLDOWN[active];if(active==='ball')lastCheckin=clock;active=null;}
 
  function drift(dt){
   const resting=holdIntent==='rest'||holdIntent==='recover'||actor.state==='sleep'||intent==='belly';
   needs.energy+=resting?.04*dt:-.004*dt;
   const asleep=actor.state==='sleep';
+  if(!active&&!pending&&!asleep){const position=actor.sample(clock);nearSeconds=position.z>-.5&&Math.abs(position.x)<.32?nearSeconds+dt:0;}
+  else nearSeconds=0;
   needs.drowsiness+=asleep?-dt/60:dt/240;
   quiet=active||pending||asleep?0:quiet+dt;
   if(!active){needs.curiosity+=.01*dt;needs.social+=.008*dt;}
@@ -218,20 +260,47 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
   quiet=0;
   if(butterfly||lastEpisode==='butterfly'){
    butterfly=null;queue=[];hold=0;holdIntent=null;gesture=null;waiting=null;
-   if(kind!=='ball')actor.sit();
   }
   if(kind==='treat'||kind==='tug'){
    pending=kind;
-   // The pet wakes through its authored recovery, not after a long sleep timer.
-   if(['sleep','belly'].includes(actor.sample(clock).state))actor.sit();
+   queue=[];hold=0;holdIntent=null;gesture=null;waiting=null;
+   // Show the hand now, not several seconds later after the old route ends.
+   if(kind==='treat')treat=true;
+   if(typeof actor.attend==='function')actor.attend();
+   // Backward-compatible substitute actors may only support sleep recovery.
+   else if(['sleep','belly'].includes(actor.sample(clock).state))actor.sit();
    return true;
   }
   // Ball: launch now and drop obsolete controller plans; the actor's own state is left to chase.
-  active='ball';decisions++;ball={mode:'flight',start:clock};
+  const throwPosition=actor.sample(clock),pattern=chooseFetch(throwPosition.z>=-1.09);
+  const landing={...BALL_TARGET},stop={...BALL_TARGET};
+  if(pattern!=='clean')stop.z-=2.5+toyRand()*2;
+  let first=pattern==='miss'?{...landing}:{...stop};
+  if(pattern==='tumble'){
+   if(actor.canSinglePassScramble){
+    // One forward pursuit in depth. No shallow side detour, overshoot target,
+    // reversal or second chase just to expose an unrelated lateral drawing.
+    Object.assign(landing,{x:throwPosition.x,z:throwPosition.z-1.15});Object.assign(stop,{x:throwPosition.x,z:landing.z-1.1});first={...stop};
+   }else{
+    const sign=throwPosition.x>.1?-1:throwPosition.x<-.1?1:toyRand()<.5?-1:1,z=-1.25,radius=roomRadius(z);
+    Object.assign(landing,{x:sign*radius*.1,z});Object.assign(stop,{x:sign*radius*.28,z});first={x:sign*radius*.75,z};
+   }
+  }
+  let pickupRoot={...stop};
+  if(actor.canPickup===true){
+   const from=Math.hypot(first.x-stop.x,first.z-stop.z)<1e-6?throwPosition:first,dx=stop.x-from.x,dz=stop.z-from.z,d=Math.hypot(dx,dz);
+   if(d>.001){const target=paperGroundTarget(stop.x-dx/d*.17,stop.z-dz/d*.17);pickupRoot={x:target[0],z:target[1]};}
+   if(pattern==='clean'||pattern==='rolling'||pattern==='tumble'&&actor.canSinglePassScramble)first={...pickupRoot};
+  }
+  const returns=actor.canCarryTrot?FETCH_RETURN_STYLES.slice(1).filter(mode=>mode!==lastReturnMode):['brake'];
+  const returnMode=returnStyle==='auto'?returns[Math.floor(returnRand()*returns.length)]:returnStyle;
+  lastReturnMode=returnMode;
+  fetchPlan={pattern,stop,first,pickupRoot,returnMode};
+  active='ball';decisions++;ball={mode:'flight',start:clock,path:createBallPath({landing,stop})};
   queue=BALL_STEPS();hold=0;holdIntent=null;gesture=null;waiting=null;
   intent='fetch';label=LABEL.fetch;
   const urgent=typeof actor.chase==='function';
-  if((urgent||SAFE.has(actor.state))&&actor[urgent?'chase':'go'](BALL_TARGET.x,BALL_TARGET.z)!==false)queue.shift();
+  if((urgent||SAFE.has(actor.state))&&actor[urgent?'chase':'go'](first.x,first.z,{scramble:pattern==='tumble'})!==false)queue.shift();
   return true;
  }
 
@@ -242,22 +311,24 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
  }
  function ballReport(){
   if(!ball)return null;
-  if(ball.mode==='flight'){
-   const p=clamp((clock-ball.start)/FLIGHT,0,1);
-   if(p===1)return {x:BALL_TARGET.x,z:BALL_TARGET.z,height:0,carried:false};
-   return {x:HOME.x+(BALL_TARGET.x-HOME.x)*p,z:HOME.z+(BALL_TARGET.z-HOME.z)*p,height:4*BALL_PEAK*p*(1-p),carried:false};
-  }
+  const pose=actor.sample(clock);
+  // On a rear pickup the muzzle/ball is occluded behind the connected body.
+  // Do not draw the ground ball through the hindquarters to make it visible.
+  if(pose.state==='pickup'&&pose.view==='rear')return null;
+  if(pose.state==='pickup'&&pose.comfortPose?.progress>=.5)return {x:pose.x,z:pose.z,height:CARRY_HEIGHT,carried:true};
+  if(ball.mode==='flight'||ball.mode==='dropped')return {...ball.path.at(clock-ball.start),carried:false};
   if(ball.mode==='carried'){const s=actor.sample(clock);return {x:s.x,z:s.z,height:CARRY_HEIGHT,carried:true};}
   return {x:ball.x,z:ball.z,height:0,carried:false};
  }
 
  return {
   update,interact,
+  setReturnStyle(style){validateReturnStyle(style);returnStyle=style;return style;},
   get report(){
    const interaction=active??pending;
    return {
-    intent,label:pending?`${label} · ${PENDING_LABEL[pending]}`:label,episode:lastEpisode,interaction,busy:interaction!==null,
-    ball:ballReport(),treat:treatReport(),butterfly:butterflyPoint(),tug:actor.state==='tug'?{progress:actor.sample(clock).comfortPose?.progress??0,grip:1}:null,
+    intent:actor.state==='scramble'&&fetchPlan?'tumble':intent,label:pending?`${label} · ${PENDING_LABEL[pending]}`:actor.state==='scramble'&&fetchPlan?LABEL.tumble:label,episode:lastEpisode,interaction,busy:interaction!==null,
+    ball:ballReport(),fetchPattern:fetchPlan?.pattern??null,returnStyle,returnMode:fetchPlan?.returnMode??null,treat:treatReport(),butterfly:butterflyPoint(),tug:actor.state==='tug'?{progress:actor.sample(clock).comfortPose?.progress??0,grip:1}:null,
     snore:actor.state==='sleep'?((clock%3.6)/3.6):null,energy:needs.energy,drowsiness:needs.drowsiness,decisions,cooldowns:{...cooldowns},
     // Local hold clock only: progress freezes between updates; null outside the stationary hold.
     gesture:gesture&&SAFE.has(actor.state)?{clip:gesture.clip,progress:clamp(gesture.elapsed/gesture.duration,0,1)}:null

package/puppy-companion-objects.mjs

@@ -47,10 +47,12 @@ export function paintCompanionObjects(pixels,width,height,projection,report,stat
    const up=projection.project(o.x,(o.height??0)+o.radius,o.z);ry=Math.abs(up.y-p.y)*height;
   }
   if(![cx,cy,rx,ry].every(Number.isFinite)||rx<=0||ry<=0)continue;
+  const spin=o.spin??0,cos=Math.cos(spin),sin=Math.sin(spin);
   for(let y=Math.max(0,Math.floor(cy-ry));y<Math.min(height,Math.ceil(cy+ry));y++)
    for(let x=Math.max(0,Math.floor(cx-rx));x<Math.min(width,Math.ceil(cx+rx));x++){
     const u=(x+.5-cx)/rx,v=(y+.5-cy)/ry;if(u*u+v*v>1)continue;
-    const tone=o.kind==='treat'?((x+y)%3?190:85):Math.abs(v+.25*u)<.18?85:225;
+    const stripe=(v*cos+u*sin)+.25*(u*cos-v*sin);
+    const tone=o.kind==='treat'?((x+y)%3?190:85):Math.abs(stripe)<.18?85:225;
     const j=(y*width+x)*4;pixels[j]=pixels[j+1]=pixels[j+2]=tone;
    }
  }

package/puppy-paper-area.mjs

@@ -2,14 +2,17 @@
 // fractional edge coverage. No temporal blur, face warp or minimum sprite size.
 export function createPaperAreaSampler(n=320){
  if(!Number.isInteger(n)||n<2||n>640)throw Error('Invalid area source size');
- const pitch=n+1,sums=new Float64Array(pitch*pitch);
+ // Byte images have an integer sum <=640*640*255, exactly representable in
+ // uint32. Allocate only when minification is actually used. Fractional/custom
+ // inputs retain the old Float64 arithmetic rather than truncating their art.
+ const pitch=n+1;let sums=null;
  const integral=(x,y)=>{
   x=Math.max(0,Math.min(n,x));y=Math.max(0,Math.min(n,y));
   const ix=Math.min(n-1,Math.floor(x)),iy=Math.min(n-1,Math.floor(y)),fx=x-ix,fy=y-iy,k=iy*pitch+ix;
   return (sums[k]*(1-fx)+sums[k+1]*fx)*(1-fy)+(sums[k+pitch]*(1-fx)+sums[k+pitch+1]*fx)*fy;
  };
  return{
-  prepare(image){if(image.length!==n*n*4)throw Error('Invalid area source');sums.fill(0);for(let y=0;y<n;y++){let row=0;for(let x=0;x<n;x++){row+=image[(y*n+x)*4];sums[(y+1)*pitch+x+1]=sums[y*pitch+x+1]+row;}}},
-  sample(x,y,dx,dy){if(![x,y,dx,dy].every(Number.isFinite)||Math.min(dx,dy)<=0)throw Error('Invalid area footprint');const l=x-dx/2,r=x+dx/2,t=y-dy/2,b=y+dy/2;return Math.max(0,(integral(r,b)-integral(l,b)-integral(r,t)+integral(l,t))/(dx*dy));}
+  prepare(image){if(image.length!==n*n*4)throw Error('Invalid area source');const Type=image instanceof Uint8Array||image instanceof Uint8ClampedArray?Uint32Array:Float64Array;if(!(sums instanceof Type))sums=new Type(pitch*pitch);else sums.fill(0);for(let y=0;y<n;y++){let row=0;for(let x=0;x<n;x++){row+=image[(y*n+x)*4];sums[(y+1)*pitch+x+1]=sums[y*pitch+x+1]+row;}}},
+  sample(x,y,dx,dy){if(![x,y,dx,dy].every(Number.isFinite)||Math.min(dx,dy)<=0)throw Error('Invalid area footprint');if(!sums)return 0;const l=x-dx/2,r=x+dx/2,t=y-dy/2,b=y+dy/2;return Math.max(0,(integral(r,b)-integral(l,b)-integral(r,t)+integral(l,t))/(dx*dy));}
  };
 }

package/puppy-paper-world.mjs

@@ -49,7 +49,7 @@ export function createPaperProjection({viewportWidth,viewportHeight,rect,width,h
  const cx=rect.width/2,cy=rect.height/2;
  return{
   project(x,y,z){const p=paperCameraPoint(x,y,z);if(p.depth<=.02)throw Error('Paper point behind camera');return{x:(cx+f*p.x/p.depth)/rect.width,y:(cy-f*p.y/p.depth)/rect.height,depth:p.depth};},
-  placement(x,z){const p=this.project(x,0,z),sourceSize=f*PAPER_CAMERA.canvasMeters/p.depth;return{x:p.x,y:p.y,size:sourceSize/rect.height,pixelAspect:(rect.width/width)/(rect.height/height),depth:p.depth,
+  placement(x,z,lift=0){const p=this.project(x,lift,z),sourceSize=f*PAPER_CAMERA.canvasMeters/p.depth;return{x:p.x,y:p.y,size:sourceSize/rect.height,pixelAspect:(rect.width/width)/(rect.height/height),depth:p.depth,
    groundFromPixel:(px,py)=>this.ground(px/width,py/height),pixelFromGround:point=>{const q=this.project(point.x,0,point.z);return{x:q.x*width,y:q.y*height};}};},
   ground(u,v){
    if(![u,v].every(Number.isFinite))return null;
@@ -104,12 +104,58 @@ export function planPaperApproachTravel(distance){
  return{distance,duration,peak:Math.max(...segments.map(p=>p.peak)),brakingDistance:brakeDistance,at(t){if(!Number.isFinite(t))throw Error('Invalid approach time');if(t>=duration)return{distance,speed:0,stage:'arrived',done:true};let offset=0;for(let i=0;i<segments.length;i++){const p=segments[i];if(t<p.duration||i===segments.length-1){const s=p.at(t);return{...s,distance:offset+s.distance};}t-=p.duration;offset+=p.distance;}}};
 }
 
+// Ball-carry return: a true diagonal trot, optionally preceded by whole gallop
+// cycles. The last small gathering steps MOVE through the final centimeters;
+// the standing endpoint is reached at zero velocity, never a skidding still.
+export function planPaperCarry(distance,{mixed=false,settleSeconds=.22}={}){
+ if(!Number.isFinite(distance)||distance<=0||typeof mixed!=='boolean'||!Number.isFinite(settleSeconds)||settleSeconds<=0||settleSeconds>1)throw Error('Invalid carry travel');
+ const gait=PAPER_GAITS.trot,runDistance=mixed?Math.max(0,Math.floor((distance-1.5)/run.stride))*run.stride:0;
+ const remaining=distance-runDistance,gatherDistance=Math.min(.088,remaining*.2),trotDistance=remaining-gatherDistance;
+ const cycles=Math.max(1,Math.ceil(trotDistance/gait.stride)),stride=trotDistance/cycles;
+ const speed=Math.min(gait.speed,stride*gait.frequency),entrySpeed=Math.min(speed,2*gatherDistance/settleSeconds,Math.sqrt(2*2.5*trotDistance));
+ const gatherSeconds=2*gatherDistance/entrySpeed;
+ const segments=[];
+ if(runDistance)segments.push(planPaperTravel(runDistance,{speed:run.speed,...PAPER_DYNAMICS,endSpeed:speed}));
+ segments.push(planPaperTravel(trotDistance,{speed,acceleration:2.5,deceleration:4,startSpeed:runDistance?speed:0,endSpeed:entrySpeed}));
+ segments.push(planPaperTravel(gatherDistance,{speed:entrySpeed,startSpeed:entrySpeed,deceleration:entrySpeed/gatherSeconds}));
+ const duration=segments.reduce((a,p)=>a+p.duration,0),gatherStart=runDistance+trotDistance;
+ return{distance,duration,peak:Math.max(...segments.map(p=>p.peak)),brakingDistance:gatherDistance,stride,runDistance,trotDistance,gatherStart,gatherSeconds,
+  poseAt(d){const phase=(d-runDistance)/stride;return d<runDistance?{clip:'run',progress:d/run.stride}:d<gatherStart?{clip:'carry-trot',progress:phase%1,cycle:Math.floor(phase)}:{clip:'carry-settle',progress:1-Math.sqrt(Math.max(0,(distance-d)/gatherDistance))};},
+  at(t){if(!Number.isFinite(t))throw Error('Invalid carry time');if(t>=duration)return{distance,speed:0,stage:'arrived',done:true};let offset=0;for(let i=0;i<segments.length;i++){const p=segments[i];if(t<p.duration||i===segments.length-1){const s=p.at(t);return{...s,distance:offset+s.distance};}t-=p.duration;offset+=p.distance;}}
+ };
+}
+
 // Finish at a shared cycle endpoint without animating extra strides in place.
 // Short paths use shorter strides and a correspondingly lower speed ceiling.
 export function planPaperRun(distance){
  const cycles=Math.max(1,Math.ceil(distance/run.stride)),stride=distance/cycles||run.stride;
  return{stride,cycles,plan:planPaperTravel(distance,{speed:Math.min(run.speed,stride*run.frequency),...PAPER_DYNAMICS})};
 }
+
+// A single forward chase ending in a braced stumble/catch at the ball. Solve
+// entry distance and stride TOGETHER: positive entry velocity, exact contact
+// phase, no pre-impact braking, no overshoot/second go and no extra run cycle.
+export function planPaperStumble(distance,{entryPhase=.25,brakeSeconds=.27,catchSeconds=.36,catchSpeedRatio=.18,duration=.82}={}){
+ if(![distance,entryPhase,brakeSeconds,catchSeconds,catchSpeedRatio,duration].every(Number.isFinite)||distance<=0||entryPhase<=0||entryPhase>=1||brakeSeconds<=0||catchSeconds<=0||catchSpeedRatio<=0||catchSpeedRatio>=1||duration<brakeSeconds+catchSeconds||duration>3)throw Error('Invalid stumble travel');
+ const cycles=Math.max(0,Math.ceil(distance/run.stride-entryPhase)),contacts=cycles+entryPhase,a=PAPER_DYNAMICS.acceleration;
+ const coefficient=((1+catchSpeedRatio)*brakeSeconds+catchSpeedRatio*catchSeconds)/2;
+ const speedAt=d=>Math.min(run.speed,d/contacts*run.frequency,Math.sqrt(2*a*d));
+ let lo=0,hi=distance;
+ for(let i=0;i<60;i++){const d=(lo+hi)/2;if(d+coefficient*speedAt(d)<distance)lo=d;else hi=d;}
+ const entryDistance=(lo+hi)/2,entrySpeed=speedAt(entryDistance),stride=entryDistance/contacts,catchSpeed=entrySpeed*catchSpeedRatio;
+ const entry=planPaperTravel(entryDistance,{speed:entrySpeed,acceleration:a,deceleration:PAPER_DYNAMICS.deceleration,endSpeed:entrySpeed});
+ const plan=planPaperTravel(distance,{speed:entrySpeed,acceleration:a,deceleration:PAPER_DYNAMICS.deceleration,endSpeed:entrySpeed});
+ const brakeDistance=(entrySpeed+catchSpeed)*brakeSeconds/2,impactDistance=distance-entryDistance;
+ return{plan,stride,entryDistance,entrySpeed,entryTime:entry.duration,entryPhase,duration,impactDistance,
+  impactAt(age){
+   if(!Number.isFinite(age))throw Error('Invalid stumble age');const t=Math.max(0,age);
+   if(t>=brakeSeconds+catchSeconds)return{distance:impactDistance,speed:0,stage:'rest'};
+   if(t<brakeSeconds){const deceleration=(entrySpeed-catchSpeed)/brakeSeconds;return{distance:entrySpeed*t-deceleration*t*t/2,speed:entrySpeed-deceleration*t,stage:'bracing'};}
+   const u=t-brakeSeconds,deceleration=catchSpeed/catchSeconds;
+   return{distance:brakeDistance+catchSpeed*u-deceleration*u*u/2,speed:catchSpeed-deceleration*u,stage:'catching'};
+  }
+ };
+}
 export function planPaperWalk(distance){
  const gait=PAPER_GAITS.walk,cycles=Math.max(1,Math.ceil(distance/gait.stride)),stride=distance/cycles||gait.stride;
  return{stride,cycles,plan:planPaperTravel(distance,{speed:Math.min(gait.speed,stride*gait.frequency),acceleration:PAPER_DYNAMICS.walkAcceleration,deceleration:PAPER_DYNAMICS.walkDeceleration})};