@bitefoundry/retrieviewer 0.0.8 → 0.0.10

package/ASSET-PROVENANCE.md

@@ -6,6 +6,17 @@ of exclusive ownership of AI output.
 
 ## Evidence checked
 
+- Unreleased comfort v6 adds a front-facing carry-trot study generated using
+  built-in imagegen with only the existing approach and arrival-seat puppy as
+  references. No new photograph/video input. Eight whole-pose keys (four unique
+  trot phases, four gathering steps) are appended; accepted v5's37 frames remain
+  pixel-exact. One common scale, whole-image floor translation, per-key measured
+  mouth/support anchors, no anatomical compositing. Last gathering key is exact
+  arrival-seat source0. Full prompt/source hash and size evidence live in
+  dist/carry-trot-v1/NOTES.md and puppy-companion-comfort.json. Existing artwork
+  attribution and CC BY-SA4.0 remain. The owner subsequently requested publishing
+  the reviewed candidate with the original braking return preserved as an option.
+
 - PUPPY-STUDY.md identifies the initial built-in image-generation output and
   the two photographic inputs. The generated source and both local reference
   images were visually inspected. Their stored Commons metadata was checked
@@ -35,6 +46,31 @@ must be checked again for the final release bytes.
 
 ## Remaining limits
 
+Unreleased0.0.10 replaces the36 watch samples with an owner-approved whole-body
+redraw (head, neck, shoulders and foreleg weight transfer together). Built-in
+imagegen referenced only the existing approved puppy and its generated study,
+not new photographs. One common uniform scale and whole-frame floor translation
+replace the earlier row-dependent warps; no anatomical masks or body compositing.
+WATCH-REDRAW.md and the manifest retain preparation/source digests. Other behavior
+frames remain byte-identical. Existing CC BY-SA4.0 attribution remains in place.
+The owner then approved the new momentum-pose studies on2026-10-23 and requested
+implementation. The working tree now includes a v5 comfort family: the original13
+tug/sleep frames remain byte-exact,12 standing pickup keys are retained, and12
+rear stumble samples replace the rejected lateral choreography. Four samples
+are registered directly from the approved rear-quarter study; the others use a
+built-in imagegen breakdown sheet referenced only from that approved art and the
+existing puppy. Exact existing run/rear pickup endpoints remain shared. Uniform
+batch scales and whole-frame translations only, no anatomical compositing or live
+image deformation. Source digests, timings and transforms are in the comfort
+metadata; prompts/raw originals remain local, outside npm. Visual acceptance of
+the completed animation was followed by the owner's explicit publication request.
+
+0.0.9 adds offline torso-envelope constraints to the same single-source watch
+coordinate field, using only the existing seated key as a volume reference.
+Face pixels remain exact; the connected neck/body is spatially registered, not
+composited with another illustration. No new visual input or asset family;
+existing CC BY-SA4.0 attribution and licenses remain.
+
 0.0.8 replaces the watch-body joins with offline coordinate registration of
 the same single source drawing per sample. Four paw patches and a shared ground
 plane constrain the lower-body warp; original head/neck pixels remain exact.

package/PUPPY-MEMORY.md

@@ -1,5 +1,79 @@
 # Runtime weight and performance
 
+## Spatial autonomy and allocation pass (0.0.10)
+
+Autonomous strolls, dashes and butterfly visits no longer end with an unconditional
+trip to the front-center home. Only an occasional check-in or ball return comes
+back there. Check-ins have a 90-second spacing; lingering front and center for
+40 active seconds prompts a later outing, after the current episode finishes.
+Outings alternate sides and near/middle/far depths, up to 15m behind the world
+origin. Sideways room is calculated from the existing camera frustum, not a fixed
+narrow x corridor. Naps/rests find side nooks 0.7–2.6m behind the origin and often
+stay in a suitable nook already found. All travel still uses the same integrated
+gait and projection; there is no scale animation, teleport or extra dog artwork.
+
+Ten seeded 20-minute simulations spent 7–27% of time in the front-center zone,
+used both sides and multiple sleeping spots, and preserved stationary nap roots.
+Tests also cover uninterrupted gait travel, fetching home from a distant nap,
+and hand-fed treats without a detour. These are design parameters, not claims
+about measured canine behavior. The rare butterfly's lateral bounds now follow
+its current depth too, so a side-positioned puppy faces the visitor correctly.
+
+Memory changes reuse existing code and built-in Node compression:
+
+- Stable Braille output joins one reusable row of glyph references instead of
+  creating one string rope node per cell. Exact text and dot thresholds unchanged.
+- Minification integral tables allocate on first use, with uint32 sums for byte
+  art. Even the largest 640² source sum fits exactly; fractional custom images
+  retain Float64 tables. Fractional footprint arithmetic stays unchanged.
+- Node's retained crop compression uses DEFLATE level3 instead of level1.
+  Levels6/9 were rejected for 3.3s/21.5s crop-processing startup in the local probe.
+  Level3 cuts retained crop payload from22,222,718 to20,517,500 bytes, at about
+  half a second extra startup. Browser art storage and files stay unchanged.
+
+Three fresh Windows processes per side, same 450-frame 480×135 ball sequence;
+medians measured **before changing autonomy**, to isolate the memory work:
+
+| Metric | Before | After |
+| --- | ---: | ---: |
+| Initial load | 916ms | 1,419ms |
+| Loaded process RSS | 99.7MiB | 97.4MiB |
+| Rendered ArrayBuffers after diagnostic GC | 29.0MiB | 26.1MiB |
+| Rendered process RSS after diagnostic GC | 237.6MiB | 167.8MiB |
+| Peak benchmark-process RSS | 250.5MiB | 191.0MiB |
+| Mean frame time | 3.53ms | 3.59ms |
+| Frame time p95 | 6.35ms | 6.72ms |
+
+All six frame hashes equal
+`3a296d0a737eaa1d9a5923e3496e8c62b2d5e99fbe871806b907429515597a3d`.
+This synchronous off-screen workload is **not the resident desktop RAM figure**:
+GC, deferred native-close callbacks and allocator retention affect RSS. A short
+owned-window native run of the combined changes measured105MiB Node RSS; helper
+memory is separate. It verified painting, ball IPC and clean worker/helper exit,
+without restarting the user's pet. No real Mac/Linux RAM measurement this pass.
+Proof files are local `dist/roam-memory-{before,after}*.json` and
+`dist/windows-overlay-qa/lifecycle-receipt.json`. No new dependency, process,
+timer, art frame, reduction in resolution, palette change or package art bytes.
+
+## Fixed-volume watch torso (0.0.9)
+
+Paw registration alone in0.0.8 left the upper torso unconstrained. In the36
+watch samples, chest-region (source rows205..230, ink threshold>24) area/mean
+silhouette width grew up to28.9% compared with the seated key. Offline torso
+envelope calibration brings both below1.2%, with centroid movement below0.52
+source pixels. Regression limits are2% chest area/width,1px centroid,3% whole
+torso area (rows205..270), plus the existing four-paw and common-floor tests.
+
+The same single-source inverse coordinate field now eases from y180 to205,
+matches the seated torso envelope through y265 and joins the paw field by y275.
+Only the silhouette calibration curves are smoothed, not fur pixels. Face rows
+0..179 remain byte-exact; the connected neck/bandana can move spatially to join
+the stable chest, instead of freezing the inflated source torso or compositing
+two pictures. The previous y230 pixel digest is superseded deliberately by a
+face-only digest plus explicit body-volume tests. No new frames, runtime work,
+buffer, dependency or process. The archive is3,118 bytes smaller than0.0.8.
+Earlier release sections below are historical, not current registration rules.
+
 ## Single-source watch registration and English desktop UI (0.0.8)
 
 The0.0.7 neck fix still joined a different torso to the lower legs. This pass

package/README.ko.md

@@ -38,6 +38,13 @@ Node.js/npm이 없다면 [먼저 설치](PREREQUISITES.md)해 주세요.
 `retrieviewer desktop --ink dark`를 쓰세요. 실행 중이라면 먼저 종료하고 다시
 실행하세요. 배경을 캡처하지 않고, 같은 도트에 색만 바꿉니다.
 
+0.0.10부터 `--return-style auto|brake|trot|run-trot`로 귀환도
+고를 수 있어요. 기본 `auto`는 기존 제동·총총·달리다 총총을 섞고 같은 동작이
+연달아 나오지 않게 합니다. 기존 제동만 쓰려면
+`retrieviewer desktop --return-style brake`. 실행 중인 강아지는 직접 종료한 뒤
+다시 실행하세요. import해서 쓸 때는 `createPet({returnStyle:'auto'})` 또는
+`pet.setReturnStyle('brake')`로 고릅니다. 바꾸면 다음 공놀이부터 적용돼요.
+
 > **Cursor / VS Code Remote SSH 사용자:** 원격 서버의 터미널이 아닌,
 > Cursor 화면이 떠 있는 **로컬 PC의 PowerShell/터미널**에 설치하세요.
 > 서버의 `DISPLAY=:1`은 서버 쪽 X11 화면을 뜻합니다. VNC로 그 화면을 보고

package/README.md

@@ -45,6 +45,13 @@ Choose the dot color at launch: `retrieviewer desktop --ink gold`, or
 `retrieviewer desktop --ink dark` for light backgrounds. Default: `cream`.
 Quit a running companion first. Colors reuse the same artwork; no screen capture.
 
+Version 0.0.10 offers `--return-style auto|brake|trot|run-trot`.
+`auto` mixes the original braking return, a trot and run-then-trot, without
+adjacent repeats. For example, `retrieviewer desktop --return-style brake` keeps
+the original return. Quit and relaunch to change the desktop choice; an existing
+companion is not restarted for you. Embedders can use `createPet({returnStyle:'auto'})`
+and `pet.setReturnStyle('brake')`; changes apply to the next throw, not mid-fetch.
+
 > **Cursor / VS Code Remote SSH:** run those commands in your **local** computer's
 > terminal, not the remote server's terminal. The puppy belongs where the window
 > is displayed. A server's `DISPLAY=:1` refers to that server's X11 display, which

package/RELEASING.md

@@ -1,14 +1,35 @@
-# Retrieviewer 0.0.8 release process
-
-Current target: `@bitefoundry/retrieviewer@0.0.8`, public `latest`, continuing the
-approved npm release workflow. The owner requested a quick leg/body alignment
-repair and English desktop messages on2026-10-23. Watch preparation now registers
-four paws using one source drawing and a smooth coordinate field; no separate
-torso/legs are composited. Head/jaw/neck pixels remain untouched. Windows/macOS
-picker, toolbar, menu and status copy is English (Linux already was English),
-with wider buttons. No new frames, runtime dependencies or live warp buffers.
-MIT/CC BY-SA4.0 unchanged. Preserve0.0.7 and earlier registry bytes; publish only
-the exact tested0.0.8 tarball. Historical scope below is not current verification.
+# Retrieviewer 0.0.10 release process
+
+The owner explicitly requested publication and website deployment after reviewing
+the repaired watch/fetch motion and restoring the original braking return as an
+option. The publication gate is approved for this0.0.10 scope. The earlier hold
+and old local candidate tarballs are superseded; build and verify a fresh exact
+artifact before upload. This authorization does not cover rejected art/motion.
+
+Current target: `@bitefoundry/retrieviewer@0.0.10`, public `latest`. The owner
+explicitly requested npm publication and website deployment on2026-10-23.
+Spatial autonomy no longer returns home after every outing; napping uses side
+nooks, with occasional check-ins and ball returns kept. Existing calibrated
+travel, English desktop UI and MIT/CC BY-SA4.0 licenses remain. Allocation
+work uses flat Braille row joins, exact lazy integer minification tables and
+Node DEFLATE level3. See PUPPY-MEMORY.md for measured memory/startup tradeoffs.
+Watch art replaces36 frames. The stationary six-key stumble and v4 lateral
+overshoot/reChase choreography were rejected. The37-key v5 comfort family is now
+integrated (original13 +12 standing pickup +12 rear stumble); source/preparation
+records are in dist/stumble-runtime-v3. Its entry-speed/stride/catch physics end
+at the ball on one depth pursuit. No lateral detour or extra recovery hop. The
+same default assets now include eight added carry-trot/gather keys (45-key comfort
+family) with exact old37-frame preservation. Impact timing is .65s. Fetch returns
+retain the original braking approach alongside trot and run-then-trot. The new
+`returnStyle` option selects auto or one fixed style; auto mixes all three without
+adjacent repeats. `setReturnStyle()` applies to the next throw. Desktop accepts
+`--return-style`, reports its choice, and never restarts a running companion to
+change it. No new artwork or extra raster buffer for restoring the old option.
+Four style-specific seeded replays and fresh native checks pass; see
+WATCH-REDRAW.md for current verification and additional pixel payloads.
+No new runtime dependencies, processes or timers. Preserve0.0.9 and
+earlier registry bytes; publish only the exact tested0.0.10 tarball.
+Historical scope below is not current verification.
 
 Target: `@bitefoundry/retrieviewer@0.0.4`, public npm registry, `latest` tag.
 The npm organization `bitefoundry` uses the free public-packages plan; account

package/WATCH-REDRAW.md

@@ -0,0 +1,175 @@
+# Watch/fetch artwork review for0.0.10
+
+The owner accepted the second whole-body watch candidate and new momentum
+drawings, then reviewed v6 and requested retaining the original braking return
+alongside the new trot choices. The subsequent explicit request to publish and
+update the website authorizes this0.0.10 candidate. Earlier holds and rejected
+motion candidates below are historical, not the current publication policy.
+
+## Watch candidates
+
+The0.0.9 row-dependent torso-envelope warp can satisfy width/area/paw tests while
+still looking lens-distorted. Numerical bounds are not a human visual approval.
+A first redraw experiment used a fixed torso and an authored head/neck layer;
+the owner rejected the disconnected upper/lower motion. Do not publish that rig.
+
+The second candidate uses newly authored **whole-body** keys. Head yaw is coupled
+to shoulder/chest/foreleg weight transfer in the drawing. Preparation applies one
+common uniform scale and whole-frame floor translation. No collar matte,
+anatomical masks, per-row scaling, optical flow or runtime body deformation.
+The owner accepted this candidate after rejecting the disconnected first study.
+Existing seated endpoints are exact; the same36 logical watch frames replace the
+old ones. Whole adjacent pose keys are sampled at the existing cadence.
+
+Built-in imagegen inputs were the existing approved seated puppy and the first
+generated study, never a newly downloaded photo. The final prompt asked for a
+5×3 grid of15 full-body yaw keys, a fixed camera and body mass, a connected neck
+and shoulders, planted paws and subtle foreleg weight transfer. Source and full
+preparation records remain locally in `dist/watch-redraw-v2/`; the source PNG's
+SHA-256 is in its candidate.json. The first draft is retained separately for
+comparison, not composited into the second candidate.
+
+## Current fetch motion: brisk single pursuit and carry-trot
+
+The owner found v5 more natural but asked for a more dynamic impact and a small
+trotting return instead of repeated braking. V6 preserves every one of its37
+art samples. Impact timing changes from .82s to .65s: fore-brace .19s, residual
+catch .29s, recovery .17s. The physical entry solver uses the same new durations
+and residual-speed ratio .24; the source extremes are not spatially warped.
+
+Eight added keys provide four distinct diagonal trotting phases and four small
+gathering poses. Repeated source-study poses are omitted. The final key is the
+exact existing arrival-seat frame0, not a new approximation of the sit handoff.
+Gait phase uses traveled distance / fitted trot stride; cadence never exceeds
+the calibrated trot frequency. Visible forepaw support proxies use the existing
+ground lock and separate swing/support strips. The head/body are not warped.
+Mouth anchors are per-key in the same registered source coordinates.
+
+The owner requested retaining the old braking return as a selectable alternative,
+not replacing it. An independent return-choice stream now mixes brake, trot and
+run-then-trot without adjacent repeats. `returnStyle` fixes one style or selects
+auto; the public setter affects the next throw only. Desktop startup accepts
+`--return-style`; an already-running companion is not silently restarted or
+changed. It does not consume the fetch-pattern or ordinary autonomy RNG. The two
+new return types use small gathering steps: the last gathering keys move through at
+most8.8cm and finish at zero velocity before the shared sitting source. Existing
+non-fetch approaches are unchanged. Source/prompt: `dist/carry-trot-v1/NOTES.md`;
+preparation: `tools/prepare-carry-trot.*`, from the hash-checked v5 stage. Raw study
+is not shipped. Additional gzip81,084bytes; portable retained pixel increment
+259,057bytes versus v5; Node retained compressed pixels +90,697bytes in the same
+default-loader comparison. These are pixel payloads, not a promise about RSS.
+
+`puppy-carry-trot.test.mjs` covers distance/speed continuity, short and200m paths,
+cyclic support/phase, controller return variety, exact sit handoff, mouth anchor,
+old37-frame digest, bounded retention and disposal. Full suite:167 passed, two
+live-macOS checks skipped on Windows, zero failures. Native Windows owned-window
+overlay check passed and both owned worker/painter processes exited. Aside
+screenshots checked impact and new carry poses. The owner subsequently requested
+publication; numerical tests alone did not supply that authorization.
+
+### Preserved v5 basis
+
+The owner rejected v4's lateral routing even after timing improved: it still
+made a shallow detour, ran sideways, overshot the ball, reversed, and chased again.
+Do not reinstate that choreography or its rejected side-on stumble art.
+
+The v5 comfort family now replaces only the new stumble portion. It preserves
+the13 original tug/sleep frames and12 standing pickup frames exactly. Twelve
+rear stumble samples include four direct registrations from the owner's approved
+rear-quarter original study; intermediate poses were generated with built-in
+imagegen using those originals and existing rear endpoints only. The first/last
+keys are exact existing run/rear-stand sources. One common scale per authored
+batch, whole-frame registration, no body compositing or nonlinear warp.
+
+`planPaperStumble` solves entry arc length, speed and stride together. The dog
+enters the authored contact phase with positive velocity, brakes to a residual
+speed, then decelerates to rest through its catch step at the pickup root. No
+stop/relaunch between bracing and catching. The single depth pursuit never uses
+an x-axis showcase detour or second reChase. The dog picks up facing away before
+its normal unarmed return. Camera/projection and other fetch patterns are retained.
+
+Source and exact generation prompt: `dist/stumble-runtime-v3/NOTES.md`.
+Runtime metadata carries source hashes and transforms. The generator pins the
+unmodified comfort prefix to commit9fc9628 so --apply remains reproducible after
+integration. `node tools/check-fetch.mjs --default` verifies actual default assets
+and all four seeded patterns; `puppy-stumble-path.test.mjs` freezes original13-key
+pixels, shared endpoints, byte budgets, velocity/phase/arrival and no detour.
+
+Measured additions over the original13-key family: gzip246,820bytes, portable
+retained pixels702,249bytes, Node compressed pixels277,204bytes. No additional
+runtime dependency/process/timer or raster buffer; these are not desktop RSS.
+This does not substitute numerical tests for the owner's animation review.
+
+## Superseded fetch candidates (history, not current motion)
+
+Clean fetch, rolling chase, a missed landing followed by re-chase, and a rare
+shallow-side overrun use separate seeded choices with no immediate repetition.
+The tumble is asset-gated and separated by at least four throws. Ball ground
+travel reuses the existing analytic travel planner with constant deceleration;
+stripe rotation follows traveled distance / radius. A dropped ball rolls a short
+distance before settling. Accepted interactions retain the prompt chase response.
+
+The owner rejected the first fetch timing replay as sluggish. Urgent preparation
+now covers each fetch leg and pickup/drop facing/sitting, not just the initial
+launch. A deferred belly/trick finishes its recovery at the urgent cadence. Root
+travel, physical speed and distance-driven strides are unchanged; urgency resets
+at idle so ordinary watching does not inherit fast timing. Pickup/drop source
+clips take0.65s each. The updated four-pattern replay remains under visual review.
+
+The stationary six-key stumble candidate in `dist/scramble-art-v1/` was rejected
+as awkward and is excluded from the current preview. The owner also rejected
+turning front/seated before picking up a ball that was reached facing away.
+
+The new **staged v4** candidate is in `dist/fetch-art-v2/`. It has12 authored
+whole-body stumble breakdowns and6 keys each for standing rear/side pickups,
+plus the original13 tug/sleep frames preserved byte-exact. The first stumble
+key is EXACTLY the old run pair5/blend0 forepaw-contact frame; the last is the
+old standing frame. Runtime hands off at that actual stride phase while speed
+is positive, carrying the same root velocity into analytic braking. The existing
+camera never turns. A short recovery bound advances6cm and rises2.5cm in world
+space; the same pinhole projection handles its height/depth/scale. There is no
+stationary idle/settle between running and stumbling. The direction/flip remains
+unchanged through the impact and recovery.
+
+Rear and side pickups keep their approach heading and standing root, lower the
+connected head/neck/shoulders, and only turn AFTER pickup. The root stops17cm
+short of the ball rather than over it. The rear muzzle/ball is occluded behind
+the body; the visible side pickup uses authored mouth locations, not screen-center
+coordinates. Legacy clips remain a fallback when optional new art is absent.
+
+Key poses and momentum/spacing/overlap were chosen before breakdowns, following
+[Microsoft's character-animation principles](https://learn.microsoft.com/en-us/windows/win32/lwef/animation-principles)
+and the [Blender keyframe/breakdown distinction](https://docs.blender.org/manual/en/2.90/animation/keyframes/introduction.html).
+This is not a claim that extra pictures or mathematical checks guarantee appealing
+motion. The complete replay still needs the owner's visual acceptance.
+
+The built-in imagegen inputs were only existing approved run/standing/rear frames,
+not new photos/video. Exact prompt text, source PNGs, registered keys and candidate
+metadata remain in `dist/fetch-art-v2/`. No optical flow/model/runtime warp,
+expanded tween film, extra raster scratch, archive family, dependency, timer or
+process. Relative to the current13-frame family, measured additions are252,774
+gzip bytes,766,040 portable retained pixel bytes and286,718 Node compressed crop
+bytes. These are NOT measurements of whole-desktop RSS. See
+`dist/fetch-qa/receipt.json` for the actual-engine four-pattern verification.
+
+Terms for accepted
+derivatives remain CC BY-SA4.0 with the existing attribution chain; generated
+source sheets are not included in npm. Update provenance and integration tests
+after accepting candidates; the pending package tarball is obsolete.
+
+## Local review
+
+- `node tools/prepare-watch-redraw.mjs` writes a candidate, not shipped assets.
+- `node tools/check-watch-redraw.mjs` makes a same-state old/new text replay.
+- `node tools/prepare-scramble-art.mjs` writes a candidate, not shipped assets.
+- `node tools/prepare-fetch-art.mjs` prepares the current pose-first candidate.
+- `node tools/prepare-stumble-v3.mjs --apply` builds/integrates the current v5
+  momentum family; old v4 tooling/material above is historical.
+- `node tools/check-fetch.mjs` collects four real seeded fetches, without a
+  runtime pattern-forcing/debug API.
+- `node tools/preview-site.mjs` serves the existing site-dist locally. Review
+  watch-redraw-preview.html and
+  fetch-preview.html?data=fetch-preview.json&pattern=tumble.
+
+The local replay uses plain text frames; it does not run another pet core in the
+browser. Native live user windows and the already installed pet remain untouched.

package/braille.mjs

@@ -31,8 +31,10 @@ function stableBraille(rgba,width,height,brightness,contrast){
     n=Math.imul(n^(n>>>16),0x45d9f3b);n=Math.imul(n^(n>>>16),0x45d9f3b);n=(n^(n>>>16))>>>0;
     if(value>(n+.5)/4294967296){masks[(y>>2)*columns+(x>>1)]|=BRAILLE_BITS[y&3][x&1];dots++;}
   }
-  const lines=[];
-  for(let y=0;y<rows;y++){let line='';for(let x=0;x<columns;x++)line+=GLYPHS[masks[y*columns+x]];lines.push(line);}
+  // Reuse one row of glyph references. Per-cell string concatenation retained
+  // thousands of rope nodes until the final join on large desktop grids.
+  const lines=new Array(rows),cells=new Array(columns);
+  for(let y=0;y<rows;y++){for(let x=0;x<columns;x++)cells[x]=GLYPHS[masks[y*columns+x]];lines[y]=cells.join('');}
   return{text:lines.join('\n'),columns,rows,dots};
 }
 export function rgbaToBraille(rgba,width,height,{brightness=1,contrast=1,method='floyd'}={}){

package/integrations/windows-overlay/desktop.mjs

@@ -94,13 +94,14 @@ export async function desktopHelper(options={}){
 }
 export async function startDesktop(options={}){
  const ink=options.ink??'cream';if(!['cream','gold','dark'].includes(ink))throw Error('Invalid desktop ink');
+ const returnStyle=options.returnStyle??'auto';if(!['auto','brake','trot','run-trot'].includes(returnStyle))throw Error('Invalid return style');
  // Fail before creating any cache/session on unsupported desktops (e.g. Wayland).
  desktopPlatform(options);
- const status=await desktopStatus(options);if(status.running)return {...status,alreadyRunning:true};
+ const status=await desktopStatus(options);if(status.running)return {...status,alreadyRunning:true,...status.returnStyle!==returnStyle?{requestedReturnStyle:returnStyle,restartRequired:true}:{}};
  if(status.stale)await stopDesktop(options);
  const helper=await desktopHelper(options);
  return new Promise((resolve,reject)=>{
-  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),'--helper-spec',JSON.stringify(helper)],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:{...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root,RETRIEVIEWER_INK:ink}});
+  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),'--helper-spec',JSON.stringify(helper)],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:{...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root,RETRIEVIEWER_INK:ink,RETRIEVIEWER_RETURN_STYLE:returnStyle}});
   let settled=false;const finish=(error,message)=>{if(settled)return;settled=true;clearTimeout(timer);if(child.connected)child.disconnect();child.unref();error?reject(error):resolve(message);};
   const timer=setTimeout(()=>{if(child.connected)child.send({command:'abort'});finish(Error('Desktop startup timed out; no agent settings changed'));},20000);
   child.on('error',error=>finish(error));child.on('message',message=>message.error?finish(Error(message.error)):finish(null,message));child.on('exit',code=>finish(Error('Desktop exited during startup ('+code+')')));

package/integrations/windows-overlay/worker.mjs

@@ -10,6 +10,7 @@ import {controlAddress,parseHelperSpec} from '../desktop/platform.mjs';
 
 let helper,pump,timer,server,session,paths,owned=false,stopping=false,frames=0,paintedFrames=0,visible=false,selected=false,pickerVisible=false,pendingViewport=null,lastInteraction=null;
 let nativeError=null;
+const returnStyle=process.env.RETRIEVIEWER_RETURN_STYLE??'auto';
 let nativeStderr='';
 const sendParent=message=>{if(process.connected)process.send(message);};
 async function stop(){
@@ -33,7 +34,7 @@ try{
    body+=bytes.toString('utf8');if(body.length>2048)return socket.destroy();if(!body.includes('\n'))return;
    let command;try{command=JSON.parse(body.split('\n')[0]);}catch{return socket.destroy();}
    if(command.token!==session.token||!['status','stop'].includes(command.command))return socket.destroy();
-   socket.end(JSON.stringify(command.command==='stop'?{stopped:true}:{running:true,reachable:true,selected,visible,pickerVisible,frames,paintedFrames,lastInteraction,pid:process.pid,painterPid:helper?.pid,rssBytes:process.memoryUsage().rss})+'\n');
+   socket.end(JSON.stringify(command.command==='stop'?{stopped:true}:{running:true,reachable:true,selected,visible,pickerVisible,frames,paintedFrames,lastInteraction,returnStyle,pid:process.pid,painterPid:helper?.pid,rssBytes:process.memoryUsage().rss})+'\n');
    if(command.command==='stop')stop();
   });
  });
@@ -48,7 +49,7 @@ try{
  reader.on('line',line=>{
   if(line.length>100000)return stop();let m;try{m=JSON.parse(line);}catch{return stop();}
   try{
-   if(m.type==='ready'){pickerVisible=m.pickerVisible===true;sendParent({running:true,windowPicker:pickerVisible,mode:spec.mode,pid:process.pid});}
+   if(m.type==='ready'){pickerVisible=m.pickerVisible===true;sendParent({running:true,windowPicker:pickerVisible,mode:spec.mode,returnStyle,pid:process.pid});}
    else if(m.type==='error'){nativeError=String(m.message??'Desktop painter failed');sendParent({error:nativeError});stop();}
    else if(m.type==='picker')pickerVisible=m.visible===true;
    else if(m.type==='viewport'){pendingViewport=m;visible=m.visible;selected=m.selected===true;pump?.viewport(m);}
@@ -58,7 +59,7 @@ try{
    else if(m.type==='quit')stop();
   }catch(error){write({type:'error',message:error.message});stop();}
  });
- const {createPet}=await import('../../retrieviewer.mjs');const pet=await createPet();
+ const {createPet}=await import('../../retrieviewer.mjs');const pet=await createPet({returnStyle});
  if(stopping)pet.dispose();else{
   pump=createFramePump({pet,send:write});if(pendingViewport)pump.viewport(pendingViewport);
   write({type:'loaded',ink:process.env.RETRIEVIEWER_INK??'cream'});timer=setInterval(()=>{try{pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/spec.fps);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "A fluffy Braille desktop pet for Windows and Linux X11, with experimental macOS support and an embeddable TUI engine.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://bitefoundry.github.io/retrieviewer/",
@@ -89,6 +89,7 @@
     "PUPPY-MEMORY.md",
     "PUPPY-Q5-COMPARISON.md",
     "COMFORT-ART.md",
+    "WATCH-REDRAW.md",
     "BUTTERFLY.md",
     "examples/embed.mjs",
     "examples/live.mjs",
@@ -109,6 +110,7 @@
     "puppy-paper-trick-timing.mjs",
     "puppy-paper-paw-transport.mjs",
     "puppy-companion-life.mjs",
+    "puppy-companion-ball.mjs",
     "puppy-companion-objects.mjs",
     "puppy-companion-sprites.mjs",
     "puppy-comfort-sprites.mjs",

package/pet-q5-manifest.json

@@ -77,31 +77,33 @@
    "width": 320,
    "height": 320,
    "frames": 162,
-   "uniqueFrames": 142,
+   "uniqueFrames": 128,
    "sourceSha256": "7918261fb64c57a91739729841fd84c6dd53891196c7fb76ee9c27712ab6ef5d",
    "sourcePackedSha256": "7785ef65b8a2a5bf6f7ce600fe9957a60d9af82066ff49275bba061eac5392d1",
-   "encodedBytes": 6232435,
-   "gzipBytes": 1429202,
-   "residentPixelBytes": 3874636,
-   "encodedSha256": "599ee35d1164c84f80dd037c37b11212b72f4bbd91bea7e851205d602bfb672a",
-   "quantizedSha256": "821706cfd8878f0ec9eb1bf1bf0a423ef273f0fa5c7423a033225793f324dc89",
+   "encodedBytes": 5918897,
+   "gzipBytes": 1286465,
+   "residentPixelBytes": 3680463,
+   "encodedSha256": "06b2ab8e0d4ff42600818c8eb96bba4089ba77560c6e9b98a662af3967271c2d",
+   "quantizedSha256": "07d919258ed32175fed81cfe848f5336edaf88706a3b04bfb51506f82c1b2083",
    "watchRegistration": {
-    "sourceVersion": "0.0.5",
-    "sourceEncodedSha256": "38cfdfcee9c857c56a14f0a9734cb3301b4a04cb8e1ae3fb2e2b2ffe3666240f",
-    "canonicalSeat": 50,
-    "method": "single-source-paw-coordinate-registration",
-    "protectedHeadNeckRows": 230,
-    "pawWarpFullFromY": 270,
-    "groundRow": 300,
-    "headTranslateY": 0,
-    "neckUnmodified": true,
-    "bodyCompositing": false,
-    "paws": [
-     105,
-     138,
-     185,
-     218
+    "sourceSize": [
+     1619,
+     972
     ],
+    "scale": 0.7627737226277372,
+    "dx": 24.607664233576628,
+    "dy": 66.82846715328466,
+    "wholeBodyArt": true,
+    "bodyCompositing": false,
+    "collarMatte": false,
+    "nonlinearWarp": false,
+    "perKeyScale": false,
+    "runtimeCompositing": false,
+    "keys": 15,
+    "frames": 36,
+    "sourceSheetSha256": "34b9bbca507f82c739c39e4b42e2390202863189d6d1b5e6e8ca7293555e19d3",
+    "canonicalSeat": 50,
+    "method": "authored-whole-body-connected-weight-transfer",
     "unchangedOtherFrames": true
    }
   },

package/puppy-comfort-sprites.mjs

@@ -1,5 +1,18 @@
 import {grayFrameReader,isGrayFrameSource} from './puppy-frame-store.mjs';
 
+export function comfortMotionKey(progress,motion){
+ if(!Number.isFinite(progress)||progress<0||progress>1)throw Error('Invalid motion progress');
+ const age=progress*motion.duration;let key=0;
+ while(key<motion.times.length-1&&age>=motion.times[key+1])key++;
+ return key;
+}
+export function comfortMotion(pose,info){return pose?.clip==='scramble'?info.scramble:pose?.clip==='pickup'?info.pickups?.[pose.view]:pose?.clip==='carry-trot'?info.carryTrot:pose?.clip==='carry-settle'?info.carryTrot?.settle:null;}
+function validateMotion(motion,count){
+ if(!motion||!Array.isArray(motion.frames)||!Array.isArray(motion.times)||motion.frames.length<2||motion.frames.length>32||motion.frames.length!==motion.times.length||motion.times[0]!==0||!Number.isFinite(motion.duration)||motion.duration<=0||motion.duration>3||(motion.cyclic?motion.times.at(-1)>=motion.duration:motion.times.at(-1)!==motion.duration)||motion.frames.some(i=>!Number.isInteger(i)||i<0||i>=count)||motion.times.some((t,i)=>!Number.isFinite(t)||(i&&t<=motion.times[i-1])))throw Error('Invalid fetch motion metadata');
+ if(!Array.isArray(motion.floorOffsets)||motion.floorOffsets.length!==motion.frames.length||motion.floorOffsets.some(v=>!Number.isFinite(v)||Math.abs(v)>64))throw Error('Invalid fetch floor metadata');
+ if(motion.mouth&&(!Array.isArray(motion.mouth)||motion.mouth.length!==motion.frames.length||motion.mouth.some(p=>!Array.isArray(p)||p.length!==2||p.some(v=>!Number.isFinite(v)||v<0||v>320))))throw Error('Invalid fetch mouth metadata');
+}
+
 // A handful of authored keys, not an expanded 30fps film or a live image morph.
 // First/last keys are the exact shared seated source; all keys use one scale.
 export function comfortFrameIndex(progress,info){
@@ -13,14 +26,24 @@ export function comfortFrameIndex(progress,info){
 }
 
 export function createComfortSpriteSampler(bytes,info,output){
- if(!isGrayFrameSource(bytes)||![1,2].includes(info?.version)||info.width!==320||info.height!==320||info.frames!==(info.version===2?13:9))throw Error('Invalid comfort sprites');
+ if(!isGrayFrameSource(bytes)||![1,2,3,4,5,6].includes(info?.version)||info.width!==320||info.height!==320||(info.version>=4?(!Number.isInteger(info.frames)||info.frames<19||info.frames>64):info.frames!==({1:9,2:13,3:19}[info.version])))throw Error('Invalid comfort sprites');
+ if(info.version===3){
+  const s=info.scramble;
+  if(!s||!Array.isArray(s.frames)||!Array.isArray(s.times)||s.frames.length!==7||s.times.length!==7||s.times[0]!==0||!Number.isFinite(s.duration)||s.duration<=0||s.duration>3||s.times.at(-1)!==s.duration||s.frames[0]!==s.frames.at(-1)||s.frames.some(i=>!Number.isInteger(i)||i<0||i>=info.frames)||s.times.some((t,i)=>!Number.isFinite(t)||(i&&t<=s.times[i-1])))throw Error('Invalid scramble metadata');
+ }
+ if(info.version>=4){validateMotion(info.scramble,info.frames);for(const view of ['rear','front'])validateMotion(info.pickups?.[view],info.frames);}
+ if(info.version>=6){validateMotion(info.carryTrot,info.frames);validateMotion(info.carryTrot?.settle,info.frames);if(info.carryTrot.cyclic!==true||!info.carryTrot.mouth||!info.carryTrot.settle.mouth||!Array.isArray(info.carryTrot.feet)||info.carryTrot.feet.length!==info.carryTrot.frames.length||info.carryTrot.feet.some(list=>!Array.isArray(list)||list.some(f=>typeof f.id!=='string'||typeof f.stance!=='boolean'||![f.x,f.y].every(v=>Number.isFinite(v)&&v>=0&&v<320))))throw Error('Invalid carry metadata');}
  if(output!==undefined&&(!(output instanceof Uint8ClampedArray)||output.length!==320*320*4))throw Error('Invalid comfort output');
  const frames=grayFrameReader(bytes,320,320,info.frames);let rgba=output??null;
  if(rgba)for(let i=3;i<rgba.length;i+=4)rgba[i]=255;
  return pose=>{
-  if(!['tug','sleep'].includes(pose?.clip))throw Error('Invalid comfort clip');
+  if(!['tug','sleep','scramble','pickup','carry-trot','carry-settle'].includes(pose?.clip))throw Error('Invalid comfort clip');
   if(!rgba){rgba=new Uint8ClampedArray(320*320*4);for(let i=3;i<rgba.length;i+=4)rgba[i]=255;}
-  const index=pose.clip==='sleep'?info.sleep?.[pose.variant]:comfortFrameIndex(pose.progress,info);
+  let index;
+  if(['scramble','pickup','carry-trot','carry-settle'].includes(pose.clip)){
+   const motion=comfortMotion(pose,info);if(!motion)throw Error('Invalid scramble/pickup pose');
+   index=motion.frames[comfortMotionKey(pose.progress,motion)];
+  }else index=pose.clip==='sleep'?info.sleep?.[pose.variant]:comfortFrameIndex(pose.progress,info);
   if(!Number.isInteger(index))throw Error('Invalid sleep variant');
   const frame=frames.getFrame(index),base=pose.base,blend=pose.blend??1;
   if(!Number.isFinite(blend)||blend<0||blend>1)throw Error('Invalid sleep blend');

package/puppy-companion-ball.mjs

@@ -0,0 +1,36 @@
+// Analytic ball travel in the same ground/camera as the dog. No physics engine,
+// per-frame integration drift, timer, image or growing path-history allocation.
+import {planPaperTravel} from './puppy-paper-world.mjs';
+export function createBallPath({from={x:0,z:.2},landing={x:0,z:-4},stop=landing,flight=.65,peak=.75,deceleration=.6}={}){
+ if(![from.x,from.z,landing.x,landing.z,stop.x,stop.z,flight,peak,deceleration].every(Number.isFinite)||flight<0||peak<0||deceleration<=0)throw Error('Invalid ball path');
+ from=Object.freeze({...from});landing=Object.freeze({...landing});stop=Object.freeze({...stop});
+ const dx=stop.x-landing.x,dz=stop.z-landing.z,distance=Math.hypot(dx,dz),speed=Math.sqrt(2*deceleration*distance);
+ const roll=distance?planPaperTravel(distance,{speed,startSpeed:speed,acceleration:deceleration,deceleration}):null;
+ const duration=flight+(roll?.duration??0);
+ return Object.freeze({duration,from,landing,stop,
+  at(age){
+   if(!Number.isFinite(age))throw Error('Invalid ball age');
+   const t=Math.max(0,age);
+   if(t<flight){const p=t/flight;return{x:from.x+(landing.x-from.x)*p,z:from.z+(landing.z-from.z)*p,height:4*peak*p*(1-p),spin:0,speed:0,phase:'flight',settled:false};}
+   const state=roll?.at(t-flight),ratio=distance?state.distance/distance:1;
+   return{x:landing.x+dx*ratio,z:landing.z+dz*ratio,height:0,spin:(state?.distance??0)/.035,speed:state?.speed??0,phase:t>=duration?'rest':'roll',settled:t>=duration};
+  }
+ });
+}
+
+// First throw remains the familiar clean fetch. Later throws use a seeded
+// weighted choice, no immediate repeat, and at least four throws between tumbles.
+export function createFetchPatterns(random,{canTumble=false}={}){
+ if(typeof random!=='function')throw Error('Fetch pattern RNG is required');
+ let count=0,last=null,lastTumble=-4;
+ return(allowTumble=canTumble)=>{
+  if(typeof allowTumble!=='boolean')throw Error('Invalid tumble availability');
+  count++;
+  const weights={clean:4,rolling:3,miss:2,tumble:canTumble&&allowTumble&&count>=4&&count-lastTumble>=4?.6:0};
+  if(last)weights[last]=0;
+  let pattern='clean';
+  if(count>1){let pick=random()*Object.values(weights).reduce((a,b)=>a+b,0);pattern=Object.keys(weights).find(k=>(pick-=weights[k])<0)??'clean';}
+  if(pattern==='tumble')lastTumble=count;
+  last=pattern;return pattern;
+ };
+}