@bitefoundry/retrieviewer 0.0.16 → 0.0.18

package/integrations/purrviewer/src/contact.mjs

@@ -0,0 +1,63 @@
+// Bounded cat adapter for the MIT Retrieviewer image-space contact approach.
+// Ground anchors adapt puppy-paper-contact.mjs; its license
+// is retained at vendor/retrieviewer/LICENSE-CODE. No dog dimensions/art used.
+import {projectCat,unprojectCatGround} from './world.mjs';
+const viewport={width:320,height:180};
+export function createCatContacts(track){
+ // Disjoint ownership disks include swing paws, so a planted toe cannot pull
+ // its neighbour. Bake their sizes once from this immutable source schedule.
+ const radii=track.feet.map(row=>row.map(foot=>Math.min(28,...row.filter(other=>other.id!==foot.id)
+  .map(other=>.44*Math.hypot(other.x-foot.x,other.y-foot.y)))));
+ const anchors=new Map();let feet=[],mirror=false,pose=0;
+ return {
+  reset(){anchors.clear();feet=[];},
+  update(sample,flipped){
+   mirror=flipped;const n=track.feet.length,phase=((sample.phase%1)+1)%1,index=Math.min(n-1,Math.floor(phase*n)),cycle=Math.floor(sample.phase);
+   pose=index;feet=track.feet[index];const p=projectCat(sample.x,0,sample.z,viewport),scale=p.size/320,sign=mirror?-1:1;
+   const active=new Set();
+   for(const [j,foot] of feet.entries()){
+    if(!foot.stance)continue;active.add(foot.id);
+    const start=track.starts[foot.id][index],episode=(cycle-(start>index?1:0))+'/'+start;
+    let anchor=anchors.get(foot.id);
+    if(!anchor||anchor.episode!==episode){
+     anchor={episode,world:unprojectCatGround(p.x+sign*(foot.x-160)*scale,p.y+(foot.y-290)*scale,viewport),released:false};anchors.set(foot.id,anchor);
+    }
+    // A small paw-only correction may reacquire its original world support
+    // when the next authored key fits. An incompatible key stays unwarped.
+    const target=projectCat(anchor.world.x,0,anchor.world.z,viewport);
+    const dx=160+sign*(target.x-p.x)/scale-foot.x,dy=290+(target.y-p.y)/scale-foot.y;
+    anchor.released=Math.hypot(dx,dy)>Math.min(6,radii[index][j]*.22)||Math.abs(dy)>3;
+   }
+   for(const id of anchors.keys())if(!active.has(id))anchors.delete(id);
+  },
+  pins(sample){
+   const p=projectCat(sample.x,0,sample.z,viewport),scale=p.size/320,sign=mirror?-1:1,pins=[];
+   for(const [j,foot] of feet.entries()){const anchor=anchors.get(foot.id);if(!foot.stance||!anchor||anchor.released)continue;
+    const target=projectCat(anchor.world.x,0,anchor.world.z,viewport);
+    pins.push({id:foot.id,radius:radii[pose][j],source:{x:foot.x,y:foot.y},target:{x:160+sign*(target.x-p.x)/scale,y:290+(target.y-p.y)/scale},world:{...anchor.world},episode:anchor.episode});
+   }
+   return pins;
+  }
+ };
+}
+
+export function footSourcePoint(x,y,pins,out={}){
+ out.x=x;out.y=y;
+ if(y<=225||!pins.length)return out;
+ for(const pin of pins){
+  const dx=pin.target.x-pin.source.x,dy=pin.target.y-pin.source.y,radius=pin.radius??28;
+  if(radius<=0||Math.hypot(dx,dy)>Math.min(6,.22*radius)||Math.abs(dy)>3)continue;
+  if(Math.hypot(x-pin.source.x,y-pin.source.y)>=radius)continue;
+  // Invert ONE compact forward translation with a rigid paw core. Its gradient
+  // norm is <= .22*1.5/.7 < .472, so it cannot fold or duplicate a toe. Outside
+  // its disk it is exactly identity. No winner-switch between overlapping warps.
+  let u=x-dx,v=y-dy;
+  for(let i=0;i<12;i++){
+   const distance=Math.hypot(u-pin.source.x,v-pin.source.y);
+   const t=Math.max(0,Math.min(1,(distance-radius*.3)/(radius*.7))),weight=1-t*t*(3-2*t);
+   u=x-dx*weight;v=y-dy*weight;
+  }
+  out.x=u;out.y=v;return out;
+ }
+ return out;
+}

package/integrations/purrviewer/src/habitat.mjs

@@ -0,0 +1,41 @@
+// Small code-native furniture shares the cat's meter space and fixed camera.
+// No textures, canvas, retained bitmap or per-object simulation/timer.
+import {projectCat} from './world.mjs';
+export const CAT_HABITAT=Object.freeze({
+ tower:Object.freeze({x:-.61,z:-1.9,lowX:-.43,lowY:.21,highX:-.65,highY:.42,approachX:-.12}),
+ wheel:Object.freeze({x:.57,z:-1.9,radius:.42,catX:.53,stride:.32})
+});
+export function paintHabitat(pixels,width,height,angle=0){
+ const at=(x,y,value)=>{x=Math.round(x);y=Math.round(y);if(x<0||y<0||x>=width||y>=height)return;
+  const i=(y*width+x)*4;if(pixels[i])return;pixels[i]=pixels[i+1]=pixels[i+2]=value;};
+ const point=(x,y,z)=>projectCat(x,y,z,{width,height});
+ const line=(a,b,value=105)=>{const n=Math.max(1,Math.ceil(Math.hypot(b.x-a.x,b.y-a.y)));
+  for(let i=0;i<=n;i++)at(a.x+(b.x-a.x)*i/n,a.y+(b.y-a.y)*i/n,value);};
+ const edge=(x,y,z,xx,yy,zz,value)=>line(point(x,y,z),point(xx,yy,zz),value);
+ const t=CAT_HABITAT.tower,w=CAT_HABITAT.wheel;
+ const platform=(x,y,half)=>{
+  edge(x-half,y,t.z-.12,x+half,y,t.z-.12,150);
+  edge(x-half,y,t.z+.12,x+half,y,t.z+.12,205);
+  edge(x-half,y,t.z-.12,x-half,y,t.z+.12,150);
+  edge(x+half,y,t.z-.12,x+half,y,t.z+.12,150);
+  edge(x-half,y-.025,t.z+.12,x+half,y-.025,t.z+.12,100);
+ };
+ platform(t.x,0,.34);platform(t.lowX,t.lowY,.21);platform(t.highX,t.highY,.21);
+ for(const [x,top] of [[t.lowX,t.lowY],[t.highX,t.highY]]){
+  edge(x-.025,0,t.z,x-.025,top-.025,t.z,90);edge(x+.025,0,t.z,x+.025,top-.025,t.z,125);
+  for(let y=.025;y<top-.025;y+=.025)edge(x-.024,y,t.z,x+.024,y+.008,t.z,65);
+ }
+ for(const [z,value] of [[w.z-.08,65],[w.z,155]]){
+  let prev=point(w.x+w.radius,w.radius,z);
+  for(let i=1;i<=112;i++){const a=i*Math.PI*2/112,next=point(w.x+w.radius*Math.cos(a),w.radius+w.radius*Math.sin(a),z);line(prev,next,value);prev=next;}
+ }
+ // Rim markings move backwards at the tread while the cat faces screen right.
+ for(let i=0;i<24;i++){
+  const a=i*Math.PI*2/24-angle;
+  edge(w.x+(w.radius-.018)*Math.cos(a),w.radius+(w.radius-.018)*Math.sin(a),w.z,
+       w.x+(w.radius-.05)*Math.cos(a),w.radius+(w.radius-.05)*Math.sin(a),w.z,110);
+ }
+ edge(w.x-.25,-.025,w.z,w.x+.25,-.025,w.z,130);
+ edge(w.x-.25,-.025,w.z,w.x-.18,.045,w.z,95);
+ edge(w.x+.25,-.025,w.z,w.x+.18,.045,w.z,95);
+}

package/integrations/purrviewer/src/life.mjs

@@ -0,0 +1,280 @@
+// Authored companion cadence, not a biological model. The host owns motion/time.
+import {CAT_HABITAT} from './habitat.mjs';
+const GROUND = 1e-6;
+const hold = (clip, duration) => ({clip, duration, elapsed: 0, progress: 0});
+const matHold = (clip,duration) => ({...hold(clip,duration),mat:true});
+const towerLoad=(duration,facing)=>({...hold('tower-load',duration),facing});
+const travel = (clip, command) => ({clip, command, issued: false, acknowledged: false, progress: 0});
+const stretchPhases = () => [hold('stretch-enter', 1.15), hold('stretch-reach', .65),
+  hold('stretch-hold', 1.25), hold('stretch-release', .7), hold('stretch-leave', 1.15)];
+
+export function createCatLife({seed = 731} = {}) {
+  if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff) {
+    throw new RangeError('seed must be an unsigned 32-bit integer');
+  }
+  let randomState = seed;
+  const random = () => {
+    randomState = (randomState + 0x6d2b79f5) >>> 0;
+    let n = Math.imul(randomState ^ randomState >>> 15, randomState | 1);
+    n ^= n + Math.imul(n ^ n >>> 7, n | 61);
+    return ((n ^ n >>> 14) >>> 0) / 4294967296;
+  };
+  const range = (min, max) => min + random() * (max - min);
+  let clock = 0;
+  let lastChoice = 'observe';
+  let roamAfter = 20;
+  let playAfter = 90;
+  let companyAfter = 60, attentionUntil = 0, eyeAfter = 0;
+  let habitatAfter=100;
+  let pending = null;
+  let stopSent = false;
+  let episode = {intent: 'observe', label: 'Watching quietly', direct: false,
+    phases: [hold('sit', 1.2), hold('eye-greeting',3.4),hold('tail-swish', 3.6), hold('loaf-enter', .9),
+      hold('loaf-rest', range(12, 24)), hold('loaf-leave', .9), hold('sit', 2)]};
+  let index = 0;
+  const current = () => episode.phases[index];
+  const grounded = sample => !sample.airborne&&sample.y <= (sample.supportY??0)+GROUND;
+  const settled = sample => grounded(sample) && !sample.moving;
+
+  function toyPhases(sample, target) {
+    const dx = target.x - sample.x;
+    const dz = target.z - sample.z;
+    const distance = Math.hypot(dx, dz);
+    const phases = [];
+    if (distance > .35) {
+      phases.push(travel('creep', {kind: 'go', x: target.x - dx / distance * .3,
+        z: target.z - dz / distance * .3, gait: 'creep'}));
+    }
+    phases.push(hold('crouch', .65),
+      travel('pounce', {kind: 'pounce', x: target.x, z: target.z, height: .18}),
+      hold('land', .3), hold('bat', .9), hold('sit', 2.5));
+    return phases;
+  }
+
+  function localToy(sample) {
+    const direction=Math.abs(sample.x)>.3?(sample.x>0?-1:1):(random()<.5?-1:1);
+    return {x:sample.x+direction*.6,z:sample.z};
+  }
+
+  function companyPhases(sample) {
+    const target={x:sample.x<0?-.18:.18,z:Math.min(0,Math.max(-.35,sample.z+.65))};
+    const phases=[];
+    // Choose one nearby rest place, at most .8m away. A distant cat comes a
+    // little closer rather than instantly returning to the front every time.
+    const dx=target.x-sample.x,dz=target.z-sample.z,distance=Math.hypot(dx,dz);
+    if(distance>.18){const scale=Math.min(1,.8/distance);
+      phases.push(travel('walk',{kind:'go',x:sample.x+dx*scale,z:sample.z+dz*scale,gait:'walk'}));}
+    phases.push(hold('sit',1.2),...(clock>=eyeAfter?[hold('eye-greeting',3.4)]:[]),matHold('knead-enter',.8),
+      matHold('knead',4.8),matHold('knead-leave',.8),matHold('loaf-rest',range(25,45)),
+      matHold('loaf-leave',.9),matHold('sit',2));
+    companyAfter=clock+range(180,300);
+    return phases;
+  }
+
+  function descent(sample){
+    if(!(sample.supportY>0))return [];
+    const t=CAT_HABITAT.tower;
+    return [towerLoad(.4,1),travel('tower-down',{kind:'pounce',x:t.approachX,z:t.z,height:.055,landingY:0}),
+      hold('tower-land',.4),hold('sit',.7)];
+  }
+  function habitatPhases(kind){
+    habitatAfter=clock+range(160,260);
+    const t=CAT_HABITAT.tower,w=CAT_HABITAT.wheel;
+    if(kind==='wheel')return [travel('walk',{kind:'go',x:w.catX,z:w.z,gait:'walk'}),
+      hold('wheel-enter',.65),travel('wheel-run',{kind:'wheel',duration:10,speed:2*10*w.stride/10,radius:w.radius,stride:w.stride}),
+      hold('wheel-leave',.7),travel('walk',{kind:'go',x:w.catX-.3,z:w.z+.14,gait:'walk'}),hold('sit',3)];
+    return [travel('walk',{kind:'go',x:t.approachX,z:t.z,gait:'walk'}),towerLoad(.55,-1),
+      travel('tower-up',{kind:'pounce',x:t.lowX,z:t.z,height:.07,landingY:t.lowY}),hold('tower-land',.35),
+      towerLoad(.4,-1),travel('tower-up',{kind:'pounce',x:t.highX,z:t.z,height:.065,landingY:t.highY}),
+      hold('tower-land',.35),hold('sit',2),hold('eye-greeting',3.4),hold('loaf-enter',.9),
+      hold('loaf-rest',range(15,25)),hold('loaf-leave',.9),towerLoad(.4,1),
+      travel('tower-down',{kind:'pounce',x:t.lowX,z:t.z,height:.04,landingY:t.lowY}),hold('tower-land',.35),
+      ...descent({supportY:t.lowY})];
+  }
+
+  function beginInteraction(sample) {
+    const {kind, target} = pending;
+    const previousPhase=current(),previous = previousPhase.clip;
+    const fromSleep = ['sleep','loaf'].includes(previous);
+    const recovery = previous==='wheel-run'?[hold('wheel-leave',.7)]:
+      ['loaf-enter', 'loaf-rest'].includes(previous) ? [previousPhase.mat?matHold('loaf-leave',.9):hold('loaf-leave', .9)] :
+      ['knead-enter','knead'].includes(previous) ? [matHold('knead-leave',.8),matHold('loaf-leave',.9)] :
+      previous==='knead-leave' ? [matHold('loaf-leave',.9)] :
+      fromSleep ? [hold('wake', 1.8), ...(kind==='stretch'?[]:[hold('stretch-leave',1.15)])] :
+      ['stretch-reach','stretch-hold'].includes(previous) ? [hold('stretch-release', .7),hold('stretch-leave',1.15)] :
+      ['stretch-enter','stretch-release','wake'].includes(previous) ? [hold('stretch-leave',1.15)] :
+      previous.startsWith('feed-') && previous !== 'feed-leave' ? [hold('feed-leave', 1.35)] :
+      ['treat','stretch','greet','company'].includes(kind) && ['walk','creep','land'].includes(previous) ? [hold('sit', .55)] : [];
+    pending = null;
+    stopSent = false;
+    index = 0;
+    // Discard every old phase/target; direct play never resumes a stale route.
+    episode = {intent: kind, direct: true,
+      label: kind === 'toy' ? 'Stalking a toy' : kind === 'treat' ? 'Enjoying a nearby treat' :
+        kind==='stretch'?'A long supported stretch':kind==='tail'?'A little tail-tip attention':
+          kind==='company'?'Choosing a quiet place nearby':'A soft eye greeting',
+      phases: [...recovery,...descent(sample), ...(kind === 'toy' ? toyPhases(sample, target ?? localToy(sample)) :
+        kind === 'treat' ? [hold('feed-enter', 1.35), hold('feed-sniff', .45),
+          hold('feed-lick', 3.6), hold('feed-finish', .45), hold('feed-leave', 1.35), hold('sit', 1)] :
+        kind === 'stretch' ? [...stretchPhases().slice(fromSleep?1:0),hold('sit',2)] :
+        kind === 'tail' ? [hold('tail-swish',3.6),hold('sit',1)] :
+        kind === 'company' ? companyPhases(sample) :
+        ['tower','wheel'].includes(kind)?habitatPhases(kind):
+          clock>=eyeAfter?[hold('sit', .45), hold('eye-greeting', 3.4), hold('sit', 1)]:[hold('sit',1.2)])]};
+    // Quiet time follows a direct episode before autonomous travel/play returns.
+    roamAfter = Math.max(roamAfter, clock + 20);
+    playAfter = Math.max(playAfter, clock + 90);
+  }
+
+  function choose(sample) {
+    const choices = [['observe', 35], ['groom', 20], ['sleep', 20], ['stretch', 8],
+      ['roam', clock >= roamAfter ? 12 : 0], ['play', clock >= playAfter ? 5 : 0],
+      ['company',clock>=companyAfter?(clock<attentionUntil?12:6):0],
+      ['tower',clock>=habitatAfter?5:0],['wheel',clock>=habitatAfter?3:0]]
+      .filter(([kind, weight]) => kind !== lastChoice && weight > 0);
+    let ticket = random() * choices.reduce((sum, [, weight]) => sum + weight, 0);
+    const kind = choices.find(([, weight]) => (ticket -= weight) < 0)[0];
+    lastChoice = kind;
+    let phases;
+    let label;
+    switch (kind) {
+      case 'observe':
+        label = 'Watching quietly';
+        phases = random() < .7 ? [hold('sit', 2), hold('tail-swish',3.6),hold('loaf-enter', .9),
+          hold('loaf-rest', range(12, 24)), hold('loaf-leave', .9), hold('sit', 2)] :
+          [hold('sit', range(8, 16)), random()<.5?hold('eye-greeting',3.4):hold('blink',.8), hold('tail-tip',2.8),hold('idle', range(4, 8))];
+        break;
+      case 'groom':
+        label = 'A little grooming';
+        phases = [hold('sit', .6), hold('groom', range(5, 9)), hold('sit', 2)];
+        break;
+      case 'sleep':
+        label = 'A long quiet nap';
+        phases = [hold('loaf', 2), hold('sleep', range(60, 120)), hold('wake', 1.8),
+          ...stretchPhases().slice(1), hold('sit', 2)];
+        break;
+      case 'stretch':
+        label = 'Stretching out';
+        phases = [...stretchPhases(), hold('sit', range(5, 9))];
+        break;
+      case 'roam': {
+        label = 'A short wander';
+        const angle = range(0, Math.PI * 2);
+        const distance = range(.35, .8);
+        let x=Math.max(-.55,Math.min(.55,sample.x+Math.cos(angle)*distance));
+        let z=Math.max(-3.5,Math.min(0,sample.z+Math.sin(angle)*distance));
+        if(Math.hypot(x-sample.x,z-sample.z)<.15){x=sample.x>.0?-.35:.35;z=Math.max(-3,Math.min(0,sample.z-.3));}
+        phases = [hold('idle', .8), travel('walk', {kind: 'go',
+          x,z,gait:'walk'}),hold('sit',range(6,10))];
+        roamAfter = clock + 35;
+        break;
+      }
+      case 'play':
+        label = 'An imagined little hunt';
+        phases = toyPhases(sample, localToy(sample));
+        playAfter = clock + 120;
+        break;
+      case 'company':
+        label='Choosing a quiet place nearby';phases=companyPhases(sample);break;
+      case 'tower':case 'wheel':label=kind==='tower'?'A high quiet perch':'A short wheel run';phases=habitatPhases(kind);break;
+    }
+    episode = {intent: kind, label, direct: false, phases};
+    index = 0;
+  }
+
+  function advance(sample) {
+    const phase = current();
+    // An issued pounce always gets its landing recovery, even when interrupted.
+    if (pending && phase.command?.kind !== 'pounce') {
+      beginInteraction(sample);
+    } else if (++index === episode.phases.length) {
+      if(episode.direct&&['call','greet','treat'].includes(episode.intent))attentionUntil=clock+90;
+      choose(sample);
+    }
+    if(current().clip==='eye-greeting')eyeAfter=clock+20;
+  }
+
+  function step(dt, sample) {
+    if (!Number.isFinite(dt) || dt < 0 || dt > .1) {
+      throw new RangeError('dt must be finite and between 0 and .1 seconds');
+    }
+    if (!sample || !['x', 'y', 'z'].every(key => Number.isFinite(sample[key])) ||
+        sample.y < 0 || typeof sample.moving !== 'boolean') {
+      throw new TypeError('motionSample requires finite x/y/z, nonnegative y and boolean moving');
+    }
+    if (dt === 0) return null;
+    clock += dt;
+    let phase = current();
+    const committedPounce = phase.command?.kind === 'pounce' && phase.issued;
+    if (pending && !committedPounce) {
+      // Never cancel airborne motion, including externally driven ballistic arcs.
+      if (!grounded(sample)) return null;
+      if (sample.moving || (phase.command && phase.issued && !stopSent)) {
+        if (!stopSent) {
+          stopSent = true;
+          return {kind: 'stop'};
+        }
+        return null;
+      }
+      if (stopSent || (phase.command && !phase.issued)) {
+        beginInteraction(sample);
+        return null;
+      }
+    }
+    if (phase.done && settled(sample)) {
+      advance(sample);
+      return null; // Expose the next source clip's entry endpoint at progress 0.
+    }
+    if (phase.command) {
+      if (!phase.issued) {
+        if (!settled(sample)) return null;
+        phase.issued = true;
+        return {...phase.command};
+      }
+      if (sample.moving) phase.acknowledged = true;
+      if (phase.acknowledged && settled(sample)) {
+        phase.progress = 1;
+        phase.done = true;
+      }
+      return null;
+    }
+    if (!settled(sample)) return null;
+    // Complete source endpoints before changing pose. Quiet holds yield in .2s;
+    // landing retains its authored recovery duration. No per-behavior timer.
+    if (pending && !['land','tower-land'].includes(phase.clip)) {
+      phase.exitStart ??= phase.progress;
+      phase.exitElapsed = (phase.exitElapsed ?? 0) + dt;
+      phase.progress = phase.exitStart + (1 - phase.exitStart) * Math.min(1, phase.exitElapsed / .2);
+    } else {
+      phase.elapsed = Math.min(phase.duration, phase.elapsed + dt);
+      phase.progress = Math.min(1, phase.elapsed / phase.duration);
+    }
+    phase.done = phase.progress >= 1;
+    return null;
+  }
+
+  return {
+    step,
+    interact(kind, {target} = {}) {
+      if (!['treat', 'toy', 'call','stretch','tail','greet','company','tower','wheel'].includes(kind)) return false;
+      if (target !== undefined && (!target || !Number.isFinite(target.x) || !Number.isFinite(target.z))) return false;
+      // Repeated greetings do not restart a half-finished expression or turn
+      // quiet attention into an obedience loop. Other interactions still preempt.
+      if(['call','greet'].includes(kind)&&(current().clip==='eye-greeting'||
+        (episode.direct&&['call','greet'].includes(episode.intent)&&!pending)))return true;
+      if(kind==='company'&&episode.intent==='company'&&!pending)return true;
+      if(['tower','wheel'].includes(kind)&&episode.intent===kind&&!pending)return true;
+      pending = {kind, target: target === undefined ? undefined : {x: target.x, z: target.z}};
+      return true;
+    },
+    get report() {
+      const phase = current();
+      return {intent: episode.intent, label: episode.label, clip: phase.clip,
+        progress: phase.progress, busy: Boolean(pending || episode.direct || ['roam', 'play'].includes(episode.intent)),
+        food: phase.clip.startsWith('feed-') ? {remaining: phase.clip === 'feed-lick' ? 1-phase.progress :
+          ['feed-finish','feed-leave'].includes(phase.clip) ? 0 : 1} : null,
+        mat: Boolean(phase.mat),facing:phase.facing??null,resting:['sleep','loaf-rest'].includes(phase.clip)&&!pending,
+        sleeping: phase.clip === 'sleep'};
+    }
+  };
+}

package/integrations/purrviewer/src/purrviewer-core.mjs

@@ -0,0 +1,130 @@
+import {rgbaToBraille} from '../vendor/retrieviewer/braille.mjs';
+import {createCatMotion,projectCat} from './world.mjs';
+import {createCatLife} from './life.mjs';
+import {createCatContacts,footSourcePoint} from './contact.mjs';
+import {paintHabitat} from './habitat.mjs';
+export function createCatFromAssets({seed=731}={},lease,kernel=null){
+ if(!Number.isInteger(seed)||seed<0||seed>0xffffffff)throw TypeError('Invalid cat seed');
+ let asset=lease.data;const release=lease.release,motion=createCatMotion(),life=createCatLife({seed}),contacts=createCatContacts(asset.meta.walk),sourcePoint={x:0,y:0};
+ let pixels=null,disposed=false,lastClip='sit',lastFrame=null,prep=null,view='front',mirror=false,settle=null,lastMoving=false,lastLifeClip='sit',lastPaintKey='',lastText='',rasterizations=0,heldHits=0;
+ const alive=()=>{if(disposed)throw Error('Cat is disposed');};
+ const direct=command=>{
+  if(command.kind==='go')motion.go(command.x,command.z,{gait:command.gait});
+  else if(command.kind==='pounce')motion.pounce(command.x,command.z,{height:command.height,landingY:command.landingY??0});
+  else if(command.kind==='wheel'){view='side';mirror=false;settle=null;motion.wheel(command);}
+  else if(command.kind==='stop'){prep=null;motion.stop();}
+ };
+ function issue(command){
+  if(command.kind==='go'&&view==='front'&&!motion.sample().moving){
+   const s=motion.sample(),dx=command.x-s.x,dz=command.z-s.z,length=Math.hypot(dx,dz);
+   if(length>.01){const targetView=Math.abs(dz/length)>.8?(dz>0?'front':'rear'):'side';prep={age:0,seconds:.4,command,targetView,clip:targetView==='front'?'rise-front':'rise'};mirror=dx<0;settle=null;return;}
+  }
+  if(command.kind!=='stop')settle=null;
+  direct(command);
+ }
+ return {
+  step(dt){
+   alive();if(!Number.isFinite(dt)||dt<0||dt>.25)throw RangeError('Invalid cat dt');
+   let left=dt;while(left>1e-10){const step=Math.min(1/60,left);left-=step;
+    if(prep){prep.age+=step;if(prep.age>=prep.seconds){const cmd=prep.command;view=prep.targetView;prep=null;direct(cmd);}}
+    motion.step(step);const s=motion.sample();
+    const command=life.step(step,s);if(command)issue(command);
+    const report=life.report,clip=report.clip;
+    if(s.moving&&!prep&&!s.exercising){const sx=Math.sin(s.heading),sz=Math.cos(s.heading);mirror=sx<0;view=s.airborne?'side':Math.abs(sz)>.8?(sz>0?'front':'rear'):'side';settle=null;}
+    if(clip!==lastLifeClip){
+     if(clip==='stretch-enter'){view='front';mirror=false;settle=null;}
+     if(clip==='knead-enter'){view='front';mirror=false;settle=null;}
+     if(['tower-load','tower-land','wheel-enter','wheel-leave'].includes(clip)){view='side';settle=null;if(clip.startsWith('wheel'))mirror=false;}
+     if(clip==='tower-load')mirror=report.facing<0;
+     if(clip==='stretch-reach'){view='side';mirror=false;settle=null;}
+     if(clip==='feed-enter'){view='side';mirror=false;settle=null;}
+     // These authored sequences already finish on the canonical front sit.
+     // Replaying stand-to-sit here made the cat rise again after paw play.
+     if(clip==='sit'&&['bat','stretch','stretch-leave','feed-leave','loaf-leave'].includes(lastLifeClip)){view='front';mirror=false;settle=null;}
+     lastLifeClip=clip;
+    }
+    const quiet=['idle','sit','blink','eye-greeting','groom','loaf','sleep','tail-swish','tail-tip'].includes(clip);
+    if(!s.moving&&!prep&&quiet){
+     if(!settle&&(lastMoving||view!=='front'))settle={age:0,seconds:.45,clip:view==='front'?'sit-front':'sit-down'};
+     if(settle){settle.age+=step;if(settle.age>=settle.seconds){view='front';mirror=false;settle=null;}}
+    }else settle=null;
+    lastMoving=s.moving;
+    if(s.moving&&!s.airborne&&!s.exercising&&s.supportY===0&&!prep&&view==='side')contacts.update(s,mirror);else contacts.reset();
+   }
+  },
+  frame({columns=160,rows=72}={}){
+   alive();if(!Number.isInteger(columns)||!Number.isInteger(rows)||columns<8||rows<4||columns*rows>125000)throw RangeError('Invalid cat viewport');
+   const width=columns*2,height=rows*4,n=width*height*4;
+   if(!pixels||pixels.length!==n){pixels=new Uint8ClampedArray(n);for(let i=3;i<n;i+=4)pixels[i]=255;}
+   const s=motion.sample(),r=life.report;let clip=r.clip??'sit',progress=r.progress??0;
+   if(s.moving&&!s.airborne&&!s.exercising){
+    clip=view==='side'?'walk':view==='front'?'walk-front':'walk-rear';progress=((s.phase%1)+1)%1;
+   }
+   if(s.airborne){clip=r.clip==='tower-up'?'tower-flight':r.clip==='tower-down'?'tower-fall':'pounce';progress=s.flightProgress;}
+   if(s.exercising||r.clip==='wheel-run'){clip='wheel-run';progress=((s.wheelPhase%1)+1)%1;}
+   if(prep){clip=prep.clip;progress=Math.min(1,prep.age/prep.seconds);}
+   if(settle){clip=settle.clip;progress=Math.min(1,settle.age/settle.seconds);}
+   // Nine authored licking cycles in 3.6s. Rendering only samples simulation
+   // progress; a hidden or sparse host cannot change eating cadence.
+   if(clip==='feed-lick')progress=progress>=1?0:(progress*9)%1;
+   if(clip==='knead')progress=progress>=1?0:(progress*4)%1;
+   const keys=asset.meta.clips[clip]??asset.meta.clips.sit;
+   const pins=clip==='walk'?contacts.pins(s):[];
+   // Every authored key needs a real hold, including the recovery/exit key.
+   const key=keys[Math.min(keys.length-1,Math.floor(Math.max(0,Math.min(1,progress))*keys.length))];
+   const food=r.food?Math.ceil(r.food.remaining*16)/16:null;
+   const wheelAngle=Math.round(s.wheelAngle*120)/120;
+   const p=projectCat(s.x,s.y,s.z,{width,height,canvasMeters:.6}),paintKey=[width,height,key,mirror,p.x,p.y,p.size,food,r.mat,wheelAngle].join('/');
+   const dish=p&&food!==null?{x:p.x+p.size*(269/320-.5),y:p.y+p.size*(288-290)/320,
+     radius:p.size*18/320,remaining:food}:null;
+   const mat=r.mat?{x:p.x,y:p.y+p.size*3/320,radiusX:p.size*72/320,radiusY:p.size*12/320}:null;
+   const result=text=>({text,pixels,columns,rows,color:asset.meta.color,state:{...s,clip,frame:key},contacts:pins,report:r,placement:p,dish,mat});
+   lastClip=clip;lastFrame=key;
+   if(paintKey===lastPaintKey){heldHits++;return result(lastText);}
+   if(kernel?.clear)kernel.clear(pixels);else for(let i=0;i<n;i+=4)pixels[i]=pixels[i+1]=pixels[i+2]=0;
+   const gray=asset.store.getFrame(key);
+   if(p){
+    const size=p.size,left=p.x-size*.5,top=p.y-size*(290/320),x0=Math.max(0,Math.floor(left)),y0=Math.max(0,Math.floor(top)),x1=Math.min(width,Math.ceil(left+size)),y1=Math.min(height,Math.ceil(top+size));
+    if(kernel?.catBlit)kernel.catBlit(pixels,gray,{width,height,x:p.x,y:p.y,size:p.size,mirror,pins});else for(let y=y0;y<y1;y++)for(let x=x0;x<x1;x++){
+     let u=(x+.5-left)*320/size-.5,v=(y+.5-top)*320/size-.5;if(mirror)u=319-u;
+     if(v>225&&pins.length){const source=footSourcePoint(u,v,pins,sourcePoint);u=source.x;v=source.y;}
+     if(u<0||v<0||u>319||v>319)continue;
+     const a=Math.floor(u),b=Math.floor(v),fu=u-a,fv=v-b,aa=Math.min(319,a+1),bb=Math.min(319,b+1);
+     const value=Math.round((gray[b*320+a]*(1-fu)+gray[b*320+aa]*fu)*(1-fv)+(gray[bb*320+a]*(1-fu)+gray[bb*320+aa]*fu)*fv),at=(y*width+x)*4;
+     pixels[at]=pixels[at+1]=pixels[at+2]=value;
+    }
+    // A small soft mat supplies the contact context. Only uncovered background
+    // pixels receive it; the original cat's fur and dark details stay intact.
+    if(mat){
+     for(let y=Math.max(0,Math.floor(mat.y-mat.radiusY));y<Math.min(height,Math.ceil(mat.y+mat.radiusY));y++)
+      for(let x=Math.max(0,Math.floor(mat.x-mat.radiusX));x<Math.min(width,Math.ceil(mat.x+mat.radiusX));x++){
+       const e=((x+.5-mat.x)/mat.radiusX)**4+((y+.5-mat.y)/mat.radiusY)**4;
+       if(e>=1)continue;const at=(y*width+x)*4;if(pixels[at])continue;
+       const value=e>.72?180:90;pixels[at]=pixels[at+1]=pixels[at+2]=value;
+      }
+    }
+    // A shallow plate and diminishing paste share the cat's pinhole transform.
+    // Paint directly into the borrowed grayscale output: no prop texture/cache.
+    if(dish){
+     const rx=dish.radius,ry=p.size*4/320;
+     for(let y=Math.max(0,Math.floor(dish.y-ry-3));y<Math.min(height,Math.ceil(dish.y+ry+2));y++)
+      for(let x=Math.max(0,Math.floor(dish.x-rx-1));x<Math.min(width,Math.ceil(dish.x+rx+2));x++){
+       const dx=(x+.5-dish.x)/rx,dy=(y+.5-dish.y)/ry,e=dx*dx+dy*dy;
+       let value=e<1&&e>.48?150:e<=.48?48:0;
+       const pasteRadius=Math.sqrt(food)*.72;
+       if(food>0&&pasteRadius>0&&dx*dx+(dy+.5)*(dy+.5)<pasteRadius*pasteRadius)value=220;
+       if(!value)continue;const at=(y*width+x)*4;
+       pixels[at]=pixels[at+1]=pixels[at+2]=Math.max(pixels[at],value);
+      }
+    }
+   }
+   paintHabitat(pixels,width,height,wheelAngle);
+   rasterizations++;lastPaintKey=paintKey;lastText=(kernel?.braille?kernel.braille(pixels,width,height,1.22,1.08):rgbaToBraille(pixels,width,height,{method:'stable',brightness:1.22,contrast:1.08})).text;
+   return result(lastText);
+  },
+  interact(kind,options){alive();if(!['treat','toy','call','stretch','tail','greet','company','tower','wheel'].includes(kind))throw TypeError('Invalid cat interaction');const accepted=life.interact(kind,options);if(accepted&&prep){prep=null;}return accepted;},
+  get report(){alive();return life.report;},
+  get stats(){alive();return {residentPixelBytes:asset.store.residentPixelBytes??asset.store.residentBytes,cachedFrames:asset.store.stats().cachedFrames,rgbaBytes:pixels?.byteLength??0,lastClip,lastFrame,leases:lease.users?.()??1,rasterizations,heldHits};},
+  dispose(){if(disposed)return;disposed=true;pixels=null;prep=null;contacts.reset();asset=null;lastText=lastPaintKey='';release();}
+ };
+}

package/integrations/purrviewer/src/purrviewer.mjs

@@ -0,0 +1,37 @@
+import {readPackedFrames} from '../vendor/retrieviewer/puppy-frame-store.mjs';
+import {rgbaToBraille} from '../vendor/retrieviewer/braille.mjs';
+import {createCatFromAssets} from './purrviewer-core.mjs';
+export {createCatFromAssets} from './purrviewer-core.mjs';
+let shared=null,pending=null,leases=0;
+const root=new URL('../art/',import.meta.url);
+async function read(url){
+ if(url.protocol==='file:'){const {readFile}=await import('node:fs/promises');return new Uint8Array(await readFile(url));}
+ const r=await fetch(url);if(!r.ok)throw Error('Cat asset HTTP '+r.status);return new Uint8Array(await r.arrayBuffer());
+}
+async function acquire(){
+ if(!pending&&!shared)pending=(async()=>{
+  const meta=JSON.parse(new TextDecoder().decode(await read(new URL('ginger.json',root))));
+  if(meta.version!==1||meta.width!==320||meta.height!==320||meta.frames<1||meta.frames>128)throw Error('Invalid cat art metadata');
+  let store;
+  if(root.protocol==='file:'){
+   const {openFrameFile}=await import('../vendor/retrieviewer/puppy-frame-file.mjs');
+   store=openFrameFile(new URL('ginger.rvz',root));
+  }else{
+   const gzip=await read(new URL('ginger.bin.gz',root));
+   const encoded=new Uint8Array(await new Response(new Blob([gzip]).stream().pipeThrough(new DecompressionStream('gzip'))).arrayBuffer());
+   store=readPackedFrames(encoded);
+  }
+  try{
+  if(store.frameCount!==meta.frames)throw Error('Cat art frame count mismatch');
+  for(const motion of Object.values(meta.clips))if(!Array.isArray(motion)||!motion.length||motion.some(i=>!Number.isInteger(i)||i<0||i>=meta.frames))throw Error('Invalid cat clip');
+  return {meta,store};
+  }catch(error){store.dispose?.();throw error;}
+ })().then(value=>{shared=value;pending=null;return value;},error=>{pending=null;throw error;});
+ const value=shared??await pending;leases++;return value;
+}
+function release(){if(--leases===0){shared?.store.dispose?.();shared=null;}}
+export async function createCat({seed=731}={}){
+ if(!Number.isInteger(seed)||seed<0||seed>0xffffffff)throw TypeError('Invalid cat seed');
+ const data=await acquire();return createCatFromAssets({seed},{data,release,users:()=>leases});
+}
+// The native host owns loading and lifetime; behavior and rendering stay shared.

package/integrations/purrviewer/src/walk-cycle.mjs

@@ -0,0 +1,3 @@
+// Generated offline by tools/prepare-walk.py from observed hind-paw retreat.
+// Authoring proxy, not a biological measurement.
+export const WALK_STRIDE = 0.18141;