@bitefoundry/retrieviewer 0.0.9 → 0.0.10

package/puppy-companion-comfort.json

@@ -1,18 +1,22 @@
 {
-  "version": 2,
+  "version": 6,
   "width": 320,
   "height": 320,
-  "frames": 13,
+  "frames": 45,
   "clips": [
     "tug",
-    "sleep"
+    "sleep",
+    "scramble",
+    "pickup-rear",
+    "pickup-side",
+    "carry-trot"
   ],
-  "gzipBytes": 129148,
-  "residentPixelBytes": 341139,
+  "gzipBytes": 457052,
+  "residentPixelBytes": 1302445,
   "sourceSheetSha256": "10fde9dacca5cb45acd68f387e7ed3bcf88cd72cf0f9c4220d31d819db91731e",
   "neutralSha256": "19f89a8bcb5a937e528593a8f36db846a0d45a5ee398f1b0873c056e5be2fa0a",
-  "encodedSha256": "35327cc103b1f7ac2ff1b09ed98658fd8ff1dcef322de9c9b18071a4358b7b87",
-  "method": "Built-in imagegen authored tug keys. One fixed scale, ground/center translation only. Exact existing Q5 seat first/last. No expanded tween film or live body deformation.",
+  "encodedSha256": "f4e7604e3a581f5b610eb0f7873deee317a6e2ad0ff548106db2e64f6bead89b",
+  "method": "Approved momentum poses, single depth pursuit, exact source endpoints; one common scale per authored batch, no runtime image warp or expanded film.",
   "registration": {
     "sheetSize": [
       1774,
@@ -136,5 +140,327 @@
     "belly": "e1967d9156a119d04e25fd6428fe5dcdbd2156c5e4eba0347217847874006109",
     "curl": "10c9a85701af3587c48c1d8158972a07026e79a18a2375d86108538eda05aae7",
     "chin": "e971eaa6861b597f0dba3a487403cee5f120cba0a9f9584d831b5634d096dee7"
+  },
+  "scramble": {
+    "frames": [
+      25,
+      26,
+      27,
+      28,
+      29,
+      30,
+      31,
+      32,
+      33,
+      34,
+      35,
+      36
+    ],
+    "times": [
+      0,
+      0.035,
+      0.07,
+      0.105,
+      0.14,
+      0.19,
+      0.25,
+      0.32,
+      0.39,
+      0.48,
+      0.57,
+      0.65
+    ],
+    "duration": 0.65,
+    "floorOffsets": [
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0
+    ],
+    "entryView": "rear",
+    "entryPhase": 0.25,
+    "trajectory": "single-pass-target",
+    "brakeSeconds": 0.19,
+    "catchSeconds": 0.29,
+    "catchSpeedRatio": 0.24,
+    "registration": {
+      "commonScale": 0.7160493827160493,
+      "commonDx": 39.580246913580254,
+      "wholeFrameFloorTranslations": true,
+      "approvedBatchScale": 0.47313240809175766,
+      "approvedBatchDx": 1.1088664421997976,
+      "approvedOriginalKeys": [
+        2,
+        4,
+        6,
+        8
+      ],
+      "perPoseScale": false,
+      "bodyCompositing": false,
+      "nonlinearWarp": false,
+      "exactSourceEndpoints": true
+    }
+  },
+  "pickups": {
+    "rear": {
+      "frames": [
+        13,
+        14,
+        15,
+        16,
+        17,
+        18
+      ],
+      "times": [
+        0,
+        0.09,
+        0.18,
+        0.28,
+        0.4,
+        0.52
+      ],
+      "duration": 0.52,
+      "floorOffsets": [
+        0,
+        2,
+        2,
+        1,
+        1,
+        0
+      ]
+    },
+    "front": {
+      "frames": [
+        19,
+        20,
+        21,
+        22,
+        23,
+        24
+      ],
+      "times": [
+        0,
+        0.09,
+        0.18,
+        0.28,
+        0.4,
+        0.52
+      ],
+      "duration": 0.52,
+      "floorOffsets": [
+        -4,
+        1,
+        1,
+        1,
+        1,
+        -4
+      ],
+      "mouth": [
+        [
+          255,
+          151
+        ],
+        [
+          250,
+          225
+        ],
+        [
+          280,
+          275
+        ],
+        [
+          274,
+          287
+        ],
+        [
+          268,
+          238
+        ],
+        [
+          255,
+          151
+        ]
+      ]
+    }
+  },
+  "sourceComfort": {
+    "ref": "9fc9628b6e42bd5da1efb02521ed4ab6e59f7763",
+    "encodedSha256": "35327cc103b1f7ac2ff1b09ed98658fd8ff1dcef322de9c9b18071a4358b7b87",
+    "frames": 13,
+    "gzipBytes": 129148
+  },
+  "approvedArtwork": "Owner-approved whole-body momentum study, 2026-10-23",
+  "sourceSheetHashes": {
+    "rear": "7beaf6a3250590563d98af860c369c91993d5aea6b7b901f368d3992d120b09b",
+    "breakdowns": "7a565ccf2aa54f38a89979826ecc7d2d77110abbcd1bfbe6ab2cb4d86093daf2"
+  },
+  "carryTrot": {
+    "frames": [
+      37,
+      38,
+      39,
+      40
+    ],
+    "times": [
+      0,
+      0.25,
+      0.5,
+      0.75
+    ],
+    "duration": 1,
+    "cyclic": true,
+    "floorOffsets": [
+      0,
+      0,
+      0,
+      0
+    ],
+    "mouth": [
+      [
+        198,
+        177
+      ],
+      [
+        197,
+        179
+      ],
+      [
+        189,
+        178
+      ],
+      [
+        190,
+        179
+      ]
+    ],
+    "registration": {
+      "commonScale": 0.6843853820598007,
+      "commonDx": 68.1594684385382,
+      "perPoseScale": false,
+      "bodyCompositing": false,
+      "wholeFrameFloorTranslation": true,
+      "selectedSourceKeys": [
+        0,
+        1,
+        2,
+        6,
+        8,
+        9,
+        10,
+        11
+      ]
+    },
+    "settle": {
+      "frames": [
+        41,
+        42,
+        43,
+        44
+      ],
+      "times": [
+        0,
+        0.07,
+        0.14,
+        0.22
+      ],
+      "duration": 0.22,
+      "floorOffsets": [
+        0,
+        0,
+        0,
+        0
+      ],
+      "mouth": [
+        [
+          203,
+          179
+        ],
+        [
+          194,
+          180
+        ],
+        [
+          191,
+          180
+        ],
+        [
+          195,
+          183
+        ]
+      ]
+    },
+    "feet": [
+      [
+        {
+          "id": "fore-left",
+          "x": 168,
+          "y": 260,
+          "stance": false
+        },
+        {
+          "id": "fore-right",
+          "x": 220,
+          "y": 298,
+          "stance": true
+        }
+      ],
+      [
+        {
+          "id": "fore-left",
+          "x": 174,
+          "y": 267,
+          "stance": false
+        },
+        {
+          "id": "fore-right",
+          "x": 210,
+          "y": 298,
+          "stance": true
+        }
+      ],
+      [
+        {
+          "id": "fore-left",
+          "x": 164,
+          "y": 298,
+          "stance": true
+        },
+        {
+          "id": "fore-right",
+          "x": 217,
+          "y": 260,
+          "stance": false
+        }
+      ],
+      [
+        {
+          "id": "fore-left",
+          "x": 160,
+          "y": 298,
+          "stance": true
+        },
+        {
+          "id": "fore-right",
+          "x": 216,
+          "y": 270,
+          "stance": false
+        }
+      ]
+    ]
+  },
+  "carrySource": {
+    "encodedSha256": "efa81c6f464646d101873223869cebf5ca28c80529ad4ab26380d3b97cc2af54",
+    "frames": 37,
+    "gzipBytes": 375968,
+    "residentPixelBytes": 1043388,
+    "sheetSha256": "43e41a678d348439bf989535bf30761cc23ac9d4ca049705a9a651e1e8b61ee0"
   }
 }

package/puppy-companion-life.mjs

@@ -4,30 +4,33 @@
 // 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.
 // 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;}
@@ -227,11 +269,35 @@ export function createCompanionLife(actor,{seed=731,energy=.8}={}){
    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 +308,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));}
  };
 }