@bitefoundry/retrieviewer 0.0.9 → 0.0.11

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,25 @@ 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
@@ -65,6 +95,13 @@ puppy sheet, not new photographs. COMFORT-ART.md records the prompt, source hash
 and fixed-scale preparation. The ninth archive is covered explicitly by
 ASSETS-LICENSE.md and ATTRIBUTION.md. Original sheet PNGs remain outside npm.
 
+Local candidate2026-10-24 changes only offline watch-frame selection: the same
+15 approved whole-body drawings are held, not crossfaded into double contours.
+Source sheet SHA256 and registration stay unchanged; `watchRegistration` now
+records the exact36 source-key indices and `pixelBlending:false`. No new generated
+or photographic input, asset family or attribution is added. Existing CC BY-SA4.0
+terms and all non-watch pixels remain unchanged. See WATCH-REDRAW.md for the A/B.
+
 Copyrightability of AI-generated expression, the precise derivative-work analysis,
 and worldwide name clearance are not conclusively determined here. Existing
 domestic trademark research records possible similar marks; owning an npm scope

package/EMBEDDING.md

@@ -30,6 +30,12 @@ pet.dispose();
 - Frame contains text,columns,rows,artProfile,pixels,state,report,placement,
   projection,mouth,contacts. pixels is a **borrowed** RGBA buffer: valid only until
   next frame/dispose; copy if retaining. The wrapper also retains no frame.
+- needsFrame(frameOptions): optional pre-render check for a host that only needs
+  changed pictures. False means a known held pose and all visible objects match
+  the last frame. Always keep calling step(dt); needs/cooldowns/autonomy continue.
+  Moving poses, gestures, visitors and sleep cues conservatively return true.
+  frame() itself never skips or returns stale metadata. Force a frame when the
+  host loses its display contents (for example after hiding or reconnecting).
 - camera:{viewportWidth,viewportHeight,rect:{left,top,width,height}} places a pane
   within a larger viewport. Keep it consistent across time for metric perspective.
 - interact('ball'|'treat'): false while busy/cooling down; unknown kind throws.

package/PUPPY-MEMORY.md

@@ -1,5 +1,92 @@
 # Runtime weight and performance
 
+## Held-pose invalidation (local candidate, 2026-10-24)
+
+The desktop pump now asks `pet.needsFrame(viewport)` before rasterization. Only
+known held seated/down poses qualify; the key includes their source selection,
+world position, camera/grid and visible objects. Moving/turning poses, gestures,
+butterflies and sleep cues take the normal rendering path. Simulation, needs,
+cooldowns and autonomous decisions still advance. Accepted input, viewport
+revision and pause/resume invalidate immediately. `frame()` itself still paints
+and returns current metadata and the same borrowed-buffer contract. One small
+key is retained, not another raster; no dependency, timer or process is added.
+
+Same seed731, 480x135 cells, 450 ticks at30Hz, first throw at tick24, brake return:
+without the hint450 renderer calls, with it300; both publish259 identical native
+frames (transport SHA256 `4069444df1bc5c1a43375ff8f3f9a4cee9bc9965c047ae5f6bfecdcc01721985`).
+During one settled1s offer, full renderer calls fall from30 to0. One local pair
+measured CPU2469ms ->1499ms; timing is a sample, not a universal CPU saving.
+Reproduce with `node tools/benchmark-held-render.mjs`.
+
+Offscreen fresh-process diagnostic-GC RSS is effectively unchanged: loaded
+102,940,672 ->102,952,960 bytes; rendered179,982,336 ->180,019,200 bytes.
+The retained ArrayBuffer difference is -19,124 bytes, mainly fewer unique watch
+samples. This is a CPU/allocation-work improvement, NOT a large desktop RAM cut.
+No live native-helper RSS or Linux/macOS performance was measured in this pass.
+
+Long-run treat/tug attention now replans a local brake from the current speed:
+`d = v*v/(2*a)`, retaining heading, distance-driven gait phase and existing
+run/walk deceleration. It cancels obsolete waypoints rather than waiting for a
+15m trip to finish. A hand-fed treat appears immediately; recovery at the tested
+rear-running speeds finishes in1.08-1.94s, including turning and sitting.
+Existing roll/tug/walk-entry recovery still reaches connected source endpoints.
+This does not change ball-return variants or multiply physical simulation time.
+
+## 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

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,13 +1,51 @@
-# Retrieviewer 0.0.9 release process
-
-Current target: `@bitefoundry/retrieviewer@0.0.9`, public `latest`, continuing the
-approved npm release workflow. The owner requested correction of the watch
-torso's swelling on2026-10-23. Offline single-source registration now constrains
-chest width/area/center and whole torso area, keeping the four paw anchors and
-floor. Face pixels through y179 stay exact; neck coordinates can join the fixed
-torso without image compositing. No new frames, dependencies, runtime work or
-buffers. English desktop UI remains. MIT/CC BY-SA4.0 unchanged. Preserve0.0.8
-and earlier registry bytes; publish only the exact tested0.0.9 tarball.
+# Retrieviewer 0.0.11 release process
+
+Current target: `@bitefoundry/retrieviewer@0.0.11`, public `latest`.
+On2026-10-24 the owner accepted the reviewed candidate and authorized immediate
+release. This scope removes blended watch contours while retaining all15 approved
+whole-body keys, interrupts treat/tug journeys with velocity-continuous braking,
+and checks held-pose dirtiness before rasterization. Existing fetch patterns and
+all three return choices remain. No new runtime dependency, timer or process.
+RAM is effectively unchanged; this pass reduces repeated CPU/allocation work.
+
+Build a fresh exact tarball, install outside the source tree, compare every
+installed byte, check its owned Windows native lifecycle and bilingual browser
+runtime, then publish that exact tarball. Verify registry integrity and GitHub
+Pages runtime bytes afterwards. Do not restart the user's existing companion.
+Earlier npm artifacts remain immutable. MIT code / CC BY-SA4.0 artwork and
+experimental macOS / X11-only Linux boundaries remain unchanged.
+
+## Previous 0.0.10 scope (historical)
+
+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.

package/WATCH-REDRAW.md

@@ -0,0 +1,186 @@
+# 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
+
+Local follow-up (2026-10-24): source-key selection replaces the pixel crossfade
+in `prepare-watch-redraw.py`. All15 registered whole-body keys, common scale,
+ground registration,36 logical samples and canonical seat endpoints remain.
+Each sample is now one exact authored key; outward/return paths reuse the same
+bytes instead of drawing two semi-transparent muzzles/shoulders. No new image,
+geometry warp or runtime blend is introduced. Non-watch decoded pixels remain
+byte-exact. The behavior archive drops from1,286,465 to1,270,759 gzip bytes.
+`dist/watch-no-ghost-v1/` preserves the candidate and source-key receipt;
+`git show HEAD:puppy-paper-behaviors-q5.bin.gz` remains the immutable release A/B.
+Automated checks do not replace final owner approval of the new held-key cadence.
+
+- `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/protocol.mjs

@@ -30,13 +30,16 @@ export function createFramePump({pet,send,now=()=>performance.now()}){
    alive();if(inFlight||!viewport||paused)return false;
    const t=now(),dt=last===null?0:Math.max(0,(t-last)/1000);last=t;
    pet.step(dt);if(t<nextPaint)return false;
+   // Do this BEFORE rasterization/Braille conversion. Older embedders without
+   // the optional hint retain the original byte-comparison fallback below.
+   if(lastFrame&&pet.needsFrame?.(viewport)===false)return false;
    const source=pet.frame(viewport),frame=cropFrame(source,revision);
    nextPaint=source.state?.state==='sleep'?t+200:0;
    // A held seat/down pose can be byte-identical for seconds. Advance the life
    // clock normally but avoid JSON, IPC, bitmap allocation and native repaint.
    if(lastFrame&&frame.x===lastFrame.x&&frame.y===lastFrame.y&&frame.columns===lastFrame.columns&&frame.rows===lastFrame.rows&&frame.text===lastFrame.text)return false;
    inFlight=true;
-   try{send(frame);lastFrame=frame;}catch(error){inFlight=false;throw error;}return true;
+   try{send(frame);lastFrame=frame;}catch(error){inFlight=false;lastFrame=null;nextPaint=0;throw error;}return true;
   },
   interact(kind){alive();if(!['ball','treat','tug'].includes(kind))throw Error('Invalid overlay interaction');const accepted=pet.interact(kind);if(accepted){lastFrame=null;nextPaint=0;}return accepted;},
   get hidden(){return !viewport||paused;},

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.9",
+  "version": "0.0.11",
   "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",