@bitefoundry/retrieviewer 0.0.0-stage → 0.0.1

package/ASSET-PROVENANCE.md

@@ -0,0 +1,43 @@
+# 0.0.1 asset provenance review
+
+Reviewed locally on 2026-10-23 for the first public npm release. This is a bounded
+engineering/provenance review, not a lawyer's clearance opinion or a guarantee
+of exclusive ownership of AI output.
+
+## Evidence checked
+
+- 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
+  against the creators, titles and licenses recorded in ATTRIBUTION.md.
+- ZOOMIES30.md, SITTING.md, PUPPY-PAPER.md, PUPPY-ACTIONS-V4.md,
+  PUPPY-ACTIONS-V9.md and the interaction-art records document generated pose
+  extensions and subsequent registration/interpolation. Q5 source and artifact
+  hashes are recorded in pet-q5-manifest.json and checked by the test suite.
+- The project owner explicitly selected code MIT + artwork CC BY-SA 4.0 and
+  authorized public npm publication on 2026-10-23. The public account identifiers
+  identify the project maintainer; BiteFoundry is not asserted to be a separate
+  incorporated rightsholder. No third-party ownership transfer is invented.
+- The earlier unpublished restrictive artwork draft is replaced rather than
+  combined with the CC grant. Reference attribution is retained, including the
+  CC BY-SA 2.5 reference and its later-version mechanism.
+- Vendored procedural-animals retains its MIT notice. three and jsonc-parser
+  remain separate pinned npm dependencies with their notices. The analytic
+  locomotion route does not bundle AI4Animation code or noncommercial datasets.
+
+## Release boundary
+
+Only the eight Q5 artwork archives, runtime metadata, allowlisted code/docs and
+retained notices are packaged. Original photos, generated source PNG sheets,
+Meshy GLBs, video references, preparation/model weights, local settings and QA or
+worker histories stay outside the public package. Tests and the packed file list
+must be checked again for the final release bytes.
+
+## Remaining limits
+
+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
+does not resolve them. No trademark filing or legal service is part of this
+release. The review records provenance, compatible release terms and exclusions;
+it must not be advertised as comprehensive IP clearance.

package/ASSETS-LICENSE.md

@@ -0,0 +1,58 @@
+# Retrieviewer artwork — CC BY-SA 4.0
+
+The bundled puppy artwork and derived frame data are offered under Creative
+Commons Attribution-ShareAlike 4.0 International (SPDX: `CC-BY-SA-4.0`).
+
+- License: https://creativecommons.org/licenses/by-sa/4.0/
+- Controlling legal text: https://creativecommons.org/licenses/by-sa/4.0/legalcode.en
+- Attribution and reference-source notices: [ATTRIBUTION.md](./ATTRIBUTION.md).
+
+The project maintainer, GitHub `shinick-han` / npm `shinick`, operating under the
+BiteFoundry project brand, selected this release policy on 2026-10-23. The grant
+covers only rights the maintainer can license; it does not assert that all
+AI-generated pixels are copyrightable or exclusively owned. The cited reference
+photographers retain their rights under their original licenses.
+
+## Covered assets
+
+These eight artwork archives and their associated pose/registration metadata,
+decoded images and alternative encodings are covered:
+
+- `puppy-stride-tweens-q5.bin.gz`
+- `puppy-paper-rear-gallop-q5.bin.gz`
+- `puppy-paper-approach-q5.bin.gz`
+- `puppy-paper-seat-q5.bin.gz`
+- `puppy-paper-arrival-seat-q5.bin.gz`
+- `puppy-paper-behaviors-q5.bin.gz`
+- `puppy-paper-actions-v9-q5.bin.gz`
+- `puppy-companion-interactions-v3-q5.bin.gz`
+
+## Practical summary
+
+You may use, copy, redistribute and adapt the artwork, including commercially.
+Retain the supplied creator/source credits, link to the applicable licenses and
+identify changes. Shared adaptations of the artwork must use CC BY-SA 4.0 or an
+applicable BY-SA-compatible license. Do not impose additional legal restrictions
+or effective technological measures that restrict the licensed freedoms.
+
+The previous, unpublished custom limited-use artwork draft is superseded for
+this release. There is no separate permission requirement here for asset packs,
+character reuse, commercial products or merchandise otherwise permitted by the
+CC license. Separate rights, if applicable, are not licensed by this notice.
+
+The software code is separately MIT under LICENSE-CODE. Merely bundling these
+assets with independent software does not relicense that software under CC.
+Third-party code and the procedural animal rig retain their own notices.
+Names are addressed in TRADEMARKS.md; that file adds no restrictions to the CC
+artwork permissions. No endorsement by the reference photographers is implied.
+
+This summary is not a replacement for the linked legal text. Applicable
+exceptions, public-domain material and uses that require no permission remain
+unrestricted. No warranty or legal-clearance certification is supplied.
+
+## 한국어 요약
+
+그림은 출처 표시와 동일조건변경허락(CC BY-SA 4.0)으로 공개합니다. 상업적
+사용·수정·재배포도 가능하며, 변경한 그림을 배포할 때는 동일조건을 지켜야
+합니다. 코드에는 별도의 MIT 라이선스가 적용됩니다. 사진 참고 출처와 가공
+경위는 ATTRIBUTION.md에 포함되며, 원본 사진은 패키지에 포함하지 않습니다.

package/ATTRIBUTION.md

@@ -0,0 +1,54 @@
+# Retrieviewer artwork credits
+
+Retrieviewer artwork and animation assembly: BiteFoundry project maintainer
+(`shinick-han` on GitHub, `shinick` on npm), 2026, with AI image generation and
+programmatic pose registration, interpolation, grounding and quantization.
+Project contact: https://github.com/BiteFoundry
+
+Release artwork: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
+See [ASSETS-LICENSE.md](./ASSETS-LICENSE.md) for covered files and the legal text.
+
+## Photographic references and retained notices
+
+The original puppy-generation record identifies these two photographic inputs.
+The release retains their attribution and treats the resulting artwork
+conservatively as an adaptation for licensing, without claiming a court has
+determined derivative-work status. The original photographs are NOT bundled.
+
+### Golden Retriever puppy standing.jpg
+
+- Creator: Scott — https://www.flickr.com/photos/29949904@N00
+- Original source: https://www.flickr.com/photos/29949904@N00/481813401
+- File/license record:
+  https://commons.wikimedia.org/wiki/File:Golden_Retriever_puppy_standing.jpg
+- Original license: [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/).
+- Use/changes: a reference input for puppy anatomy and proportions; AI-generated
+  grayscale puppy artwork with a different face, fur, bandana and background,
+  subsequently extended into poses and processed into animation frame data.
+
+### Golden Retriever 10weeks.jpg
+
+- Creator: Stefan Bauer — http://www.ferras.at
+- Original file/license record:
+  https://commons.wikimedia.org/wiki/File:Golden_Retriever_10weeks.jpg
+- Original license: [CC BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/).
+- Use/changes: a reference input for puppy face/fur; synthetic standing artwork
+  and subsequent pose extensions, not a bundled copy of the photograph.
+- CC BY-SA 2.5 section 4(b) permits distributing an adaptation under a later
+  version with the same license elements. This release uses CC BY-SA 4.0 for
+  the artwork, retaining this original credit and license information.
+
+Neither photographer endorses Retrieviewer or BiteFoundry. Original rights and
+license warranty disclaimers remain applicable. Keep these supplied credits,
+license links and change descriptions with redistributed artwork; add your own
+change description if you modify it, in a manner reasonable to the medium.
+
+## Processing and exclusions
+
+AI-generated pose sheets were extracted, aligned, interpolated, contact-corrected
+and encoded as 32-level Q5 frame stores. These are modifications, not unaltered
+photographs or motion capture. The package contains eight generated-art archives.
+Reference photo collections, YouTube footage, experimental Meshy models,
+noncommercial motion research/datasets, interpolation tools/model weights and
+worker logs are not distributed in this package. No exclusive copyright in
+otherwise unprotected AI output is claimed. Code has its own MIT license.

package/EMBEDDING.md

@@ -0,0 +1,96 @@
+# Embedding Retrieviewer
+
+See [PLUGIN.md](./PLUGIN.md) for the convenience plugin. The headless core has no
+timers, DOM, keyboard, output or process listeners. The host owns time/rendering.
+createPet reads bundled art; import alone does not. Node >=20, or browser ES modules
+with Three resolution and DecompressionStream. No native Python/Rust binding.
+
+```js
+import {createPet} from '@bitefoundry/retrieviewer';
+const pet = await createPet(); // Q5, 32 levels, all 2,341 source poses retained
+// Keep this instance for the whole pane lifetime, not one per frame.
+pet.step(elapsedSeconds);
+const {text} = pet.frame({columns, rows});
+pane.setContent(text);
+pet.interact('ball'); // or 'treat'; false when busy/cooling down
+// on unmount:
+pet.dispose();
+```
+
+## Core contract
+
+- createPet({loadAsset?,seed?,energy?,pawTransport?,artProfile?}): default q5.
+  Seed uint32, energy 0..1; keep pawTransport enabled.
+- step(dt): finite nonnegative seconds, fixed 1/60s simulation. Each call admits
+  at most 0.1s to avoid unbounded stalled-host catch-up. Returns step count.
+- frame({columns,rows,cellAspect=.5,camera?,poseFps=24,contactEnabled=true}):
+  exactly rows lines of columns Unicode Braille characters, no ANSI or trailing
+  newline. Positive integer dimensions, at most125,000 cells. Pose cadence12/24/30.
+  cellAspect = character width / line height, positive finite.
+- 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.
+- 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.
+- dispose(): idempotent. Every other core method afterwards throws.
+
+Default-loader pets share immutable art, not behavior/clocks/output buffers; last
+dispose releases shared assets. Custom loaders are isolated. Initialization is async
+I/O with synchronous CPU decode between loads; avoid repeated creation on render.
+node examples/embed.mjs [columns] [rows] prints one frame.
+npm run pet:companion (installed retrieviewer preview) is the opt-in fullscreen host:
+B ball, T treat, Space pause, Q quit. Only that executable owns input/screen.
+Redirected stdout prints one plain frame and exits.
+
+## Assets / original option
+
+Default files resolve against the module URL, never cwd (lazy Node fs or browser
+HTTP fetch). getPetAssetFiles(profile?) returns exactly18 filenames:8 compressed
+bundles plus metadata and animal. Copy these without transforming bytes for
+bundlers. Loader returns ArrayBuffer/typed bytes; .gz must remain compressed,
+not transparently decompressed by HTTP Content-Encoding.
+
+```js
+import {createPet,getPetAssetFiles} from '@bitefoundry/retrieviewer';
+const files = getPetAssetFiles(); // deploy these files unchanged
+const base = new URL('/pets/retrieviewer/', location.origin);
+const pet = await createPet({loadAsset: async name => {
+  const r = await fetch(new URL(name, base));
+  if (!r.ok) throw Error(name + ': HTTP ' + r.status);
+  return r.arrayBuffer();
+}});
+```
+
+Original256-level caches remain in the source workspace. Use
+createPet({artProfile:'original'}) there, or ?palette=original in the preview.
+They are **not bundled** in the small distribution. For external original art,
+copy getPetAssetFiles('original') from the workspace and supply loadAsset. Missing
+originals fail clearly, never silently fall back.
+
+Q5 is lossy quantization (max source-pixel error4/255), not lossless compression.
+Art gzip18.7MB versus54.2MB original; resident packed pixels66.5MB.
+One Windows Node sample:172MB RSS after rendering, startup737ms, mean frame2.61ms
+at160×50. Samples, not guarantees. Node/Three remain runtime costs.
+See [PUPPY-Q5-COMPARISON.md](./PUPPY-Q5-COMPARISON.md).
+
+## JSONL bridge (Python/Rust/other process hosts)
+
+Spawn installed retrieviewer-stdio or node /path/to/retrieviewer-stdio.mjs.
+Wait for {"event":"ready","protocol":1}. Send JSON objects one per line; replies echo
+optional string/number/null id. Stdout contains only JSONL, never ANSI.
+No autonomous clock: your app sends tick at its own cadence.
+
+```json
+{"id":1,"op":"tick","dt":0.03333333333333333,"columns":80,"rows":24}
+{"id":2,"op":"interact","kind":"ball"}
+{"id":3,"op":"dispose"}
+```
+
+tick combines step+frame in one round trip; separate step/frame remain supported.
+Frame/tick replies: {id,ok:true,text,columns,rows,report,artProfile}; step replies have
+steps, interaction replies accepted. Errors: {id,ok:false,error}. A failed tick may
+advance time before frame validation; requests are not transactions.
+Dispose acknowledges and exits; stdin EOF also disposes. Node remains required.
+examples/bridge.py uses only Python's standard library. Each process loads its own
+art; reuse one per host, not per frame.

package/INSTALLING.md

@@ -0,0 +1,107 @@
+# Enable Retrieviewer in an agent TUI
+
+0.0.1 includes an installer CLI and a native OpenCode TUI adapter. It does **not** claim
+that every MCP client can display animated UI. Native OpenCode rendering uses its
+official TUI plugin slot, not another terminal, a wrapper, or a modified binary.
+Other agent IDs are discoverable but refused until an adapter is implemented.
+
+## Install
+
+Node >=20, a Unicode Braille terminal font, and an independently installed supported
+agent are required. Source code is MIT; bundled puppy artwork is CC BY-SA 4.0.
+Keep the included ATTRIBUTION.md and asset license when redistributing artwork.
+
+```sh
+npm install -g @bitefoundry/retrieviewer@0.0.1
+retrieviewer enable
+```
+
+On a terminal, enable offers a numbered agent selection, checks compatibility,
+shows exact paths and asks before making changes. Cancel/Enter changes nothing.
+For a non-interactive installation use an explicit agent and confirmation:
+
+```sh
+retrieviewer enable --agent opencode --dry-run
+retrieviewer enable --agent opencode --yes
+opencode
+```
+
+The native renderer is initially version-gated to OpenCode2.1.2. A different
+version is **not automatically certified**. Existing project configuration can
+override global settings; doctor checks registration, not arbitrary host precedence.
+Do not put API keys in Retrieviewer settings. No credentials are needed by the pet.
+
+After a future public release, the install command will instead be
+`npm install -g @bitefoundry/retrieviewer@0.0.1`. Do not run that registry command
+before publication. The package also exports `./tui` for npm-aware OpenCode plugin
+loaders; package-name discovery has not yet been live-tested against npm.
+The verified installer continues using its local directory URL, not that new path.
+
+## What changes
+
+- Add the local TUI plugin **directory** URL to OpenCode's global `cli.json` plugins list.
+  OpenCode2.1.2 skips file targets; the directory resolves its `tui.tsx` entry.
+  Respect XDG_CONFIG_HOME; otherwise use ~/.config/opencode, including Windows.
+- Preserve JSONC comments, unrelated settings and other plugins; back up before edits.
+- Store enabled/ownership information in Retrieviewer's own settings directory.
+- Do not edit shell profiles, replace agents, change permissions, or launch another
+  terminal. This native path needs no MCP entry: registering MCP alone cannot insert
+  a persistent widget into an arbitrary TUI.
+
+Keep the installed package path available: the agent loads that exact plugin URL.
+After changing the installed location, disconnect the old registration and enable
+the new package. No automatic global install is done by the package itself.
+
+## Commands
+
+```sh
+retrieviewer agents --json
+retrieviewer status --agent opencode
+retrieviewer doctor --agent opencode --json
+retrieviewer disable --agent opencode
+retrieviewer enable --agent opencode --yes
+retrieviewer disconnect --agent opencode --dry-run
+retrieviewer disconnect --agent opencode --yes
+retrieviewer preview
+```
+
+Disable keeps the adapter installed; disconnect removes only the registration this
+installer owns. It never restores a whole old config over later user changes.
+Backups remain recoverable. An entry predating this installer remains user-owned.
+
+Inside OpenCode, `/retrieviewer enable`, `/retrieviewer disable`,
+`/retrieviewer ball`, `/retrieviewer treat`, `/retrieviewer status` control the native
+pet. The adapter owns no raw keyboard or stdout; the host owns drawing and layout.
+
+## Evidence, not a misleading green check
+
+Registration means the config contains our plugin URL. A runtime receipt means
+the adapter initialized and produced a frame; it is **not proof of human visual
+approval**. A stale receipt from a closed process is not a live renderer.
+There is no automatic approval of all MCPs or bypass of an agent's trust policy.
+
+For tests/portable setups, `RETRIEVIEWER_HOME` selects the pet state directory.
+Changing it does not move agent configuration; use XDG_CONFIG_HOME for that.
+Never point tests at a real user's settings. The package smoke check uses an
+isolated consumer home/config and an injected executable probe.
+
+## Implementation sources
+
+The native integration reuses [OpenCode's official CLI plugin API](https://dev.opencode.ai/v2/docs/build/plugins/cli)
+and the existing host-driven Retrieviewer core. JSONC edits use Microsoft's
+jsonc-parser3.3.1 instead of rewriting configuration as plain JSON. MCP Apps host
+support is independent of basic MCP support; see the
+[official extension overview](https://modelcontextprotocol.io/extensions/apps/overview).
+Support of Codex, Claude Code, Cursor Agent, Grok and Antigravity **inside their
+terminal UI remains unimplemented**, not inferred from their MCP commands.
+
+## Local validation
+
+The adapter was compiled and run by the real OpenCode2.1.2 Windows host with an
+isolated XDG configuration/data/cache/state and pet directory. Animated Braille
+appeared in its home-screen footer alongside its ordinary prompt. The native
+`/retrieviewer` slash menu and status toast were observed. External disable/re-enable
+and increasing frame receipts were checked without sending a model prompt.
+The test terminal was80×24 cells, yielding a64×5 pet pane; larger physical terminal
+visual quality and other OpenCode versions are not certified by this check.
+Source QA evidence is in qa-opencode/native-ui-proof.json (not shipped in the pet).

package/LICENSE

@@ -0,0 +1,16 @@
+Retrieviewer licensing
+
+Software source code: MIT License, see LICENSE-CODE.
+Bundled puppy artwork/frame data: Creative Commons Attribution-ShareAlike 4.0
+International (CC-BY-SA-4.0), see ASSETS-LICENSE.md and ATTRIBUTION.md.
+https://creativecommons.org/licenses/by-sa/4.0/legalcode.en
+
+The complete package is not MIT-only. Commercial use is allowed under the
+applicable terms. Artwork adaptations retain ShareAlike obligations; the
+separately licensed software does not become CC-licensed merely by bundling it.
+
+Third-party components retain their original notices, including the MIT license
+under vendor/procedural-animals. See THIRD-PARTY-NOTICES.md.
+
+No exclusive copyright in AI-generated output, registered trademark status,
+third-party endorsement or comprehensive legal clearance is claimed.

package/LICENSE-CODE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Retrieviewer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PLUGIN.md

@@ -0,0 +1,110 @@
+# Retrieviewer plugin · 0.0.1
+
+An autonomous Braille dog, embedded in **your pane**. Only ball and treat need user
+input. The rest is its own seeded behavior. No screen, stdin or layout takeover.
+No telemetry, keys, account signup or paid APIs in the runtime.
+
+## Install
+
+Install from npm:
+
+```sh
+npm install @bitefoundry/retrieviewer@0.0.1
+```
+
+Portable distribution (independent of the source directory):
+
+```sh
+npm install /path/to/bitefoundry-retrieviewer-0.0.1.tgz
+```
+
+The generated tarball is in `dist/`. Node >=20, ESM and a monospaced Unicode
+Braille font are required. The npm package name is `@bitefoundry/retrieviewer`;
+imports from the old playground name must be updated.
+The tarball carries Q5 art, runtime code, types and examples. npm installs the pinned
+`three` dependency separately (network/cache or host provisioning required).
+No install/build scripts. Offline install requires that dependency already cached.
+
+For supported agent-native installation use `retrieviewer enable`; see
+[INSTALLING.md](./INSTALLING.md). The library contract below remains unchanged.
+Source code is MIT; artwork is CC BY-SA 4.0, allowing commercial reuse and
+adaptations under its attribution/ShareAlike conditions. Vendored MIT notices
+remain intact. See LICENSE, ASSETS-LICENSE.md, ATTRIBUTION.md and TRADEMARKS.md.
+
+## Attach to any JavaScript text widget
+
+```js
+import {createPetPlugin} from '@bitefoundry/retrieviewer/plugin';
+
+const puppy = await createPetPlugin({
+  host: {
+    // Return null while hidden. Use CONTENT size, excluding widget border/padding.
+    getSize: () => visible ? {columns: contentWidth, rows: contentHeight} : null,
+    render: ({text}) => { widget.setContent(text); screen.render(); },
+    clear: () => widget.setContent(''), // optional
+    onError: error => logToYourApp(error), // optional, don't log over terminal art
+  },
+  fps: 30,
+});
+puppy.start();
+ballButton.on('click', () => puppy.interact('ball'));
+treatButton.on('click', () => puppy.interact('treat'));
+// pane unmount / host shutdown:
+puppy.dispose();
+```
+
+Identifiers like widget/screen/button are your host objects, not bundled adapters.
+Treat text as literal text, not markup/terminal escapes. Disable wrapping, trim,
+proportional fonts and line-height tricks. Use white-on-black for the approved look.
+Small panes lose fur detail; prefer >=80×24, around160×50 for detailed art.
+Multiple plugins have independent state and share default immutable assets.
+
+## Own loop instead of plugin clock
+
+```js
+const puppy = await createPetPlugin({host}); // creation does not render/start timers
+// existing host frame loop (do NOT also call start):
+puppy.tick(elapsedSeconds);
+// existing host interaction input:
+puppy.interact('ball');
+// teardown:
+puppy.dispose();
+```
+
+`start()` is opt-in scheduling, `pause()` stops scheduling without unloading,
+`render()` redraws without advancing, `tick(dt)` advances+draws. `start()` is
+idempotent; resume ignores paused wall time. `running`/`disposed` are readable.
+Host size is checked each frame; no resize listeners are installed. Hidden/null
+or zero-sized panes neither advance nor draw. Disposal cancels scheduling, releases
+pet and invokes optional clear once. Direct host errors throw; scheduled errors
+pause and invoke onError if supplied (otherwise stay paused). Host callbacks are
+synchronous; avoid retaining borrowed frame pixels. See types for custom scheduler.
+
+## Host boundaries
+
+| Host | Connection | Status |
+| --- | --- | --- |
+| JS/TS terminal widget | `/plugin` host callbacks, or core `step/frame` | Generic contract + installed consumer tested |
+| Ink/React, Blessed | Lifecycle calls plugin, render text in widget | Contract fits; framework-specific mounts not tested |
+| Python/Rust/Go TUI | JSONL subprocess, one `tick` request per frame | Bridge + Python sample; Node required |
+| Browser | Core/plugin + deployed assets + `three` mapping | Existing browser core preview checked; arbitrary bundlers untested |
+
+Not a native binary, editor extension, MCP plugin, or automatic injection into
+closed-source TUI apps. Such hosts need an extension hook to display a pane.
+Never embed fullscreen `retrieviewer preview` inside another app; import the library or use
+the JSONL bridge. [EMBEDDING.md](./EMBEDDING.md) has full core/asset/protocol details.
+
+## Verification / rebuild
+
+```sh
+npm test
+npm run test:package
+```
+
+The package check creates a tarball, installs it into a fresh temp consumer offline
+with lifecycle scripts disabled, exercises exports, default art, interactions,
+start/pause/dispose, all JS examples and JSONL. Evidence is retained in
+`dist/package-check.json`. It does not publish. Art originals/references/workers
+are excluded. Source art is18.7 MB gzip; full tarball is approximately20.6 MB,
+excluding npm's separate Three dependency. This is still a substantial pet, not
+a kilobyte icon; see memory/startup tradeoffs in the comparison document.

package/PUPPY-MEMORY.md

@@ -0,0 +1,57 @@
+# Lossless runtime cache reduction
+
+The weight came from 2,341 full-size grayscale frames stored as concatenated
+320² or 480² rasters, including exact duplicates and black padding. These are
+already one-byte grayscale, not RGBA files; converting to grayscale again would
+not help. Actions alone occupied 136,857,600 decoded bytes. Loading all eight
+gzip files concurrently through Blob/Response streams added transient copies.
+
+## What changed
+
+- RVF1 stores exact unique frames once and removes only zero-valued borders.
+  Coordinates and the original canvas size are retained. A bounded two-frame
+  LRU reconstructs full rasters only as the existing sampler needs them.
+- No downsampling, palette reduction, pose removal, timing changes, or new art.
+  Existing sampler APIs accept both the old flat arrays and the new stores.
+- `createPet()` loads compact families sequentially, using native gzip in Node.
+  Default-loader pets in one process share art but have independent actors,
+  behavior, renderers and buffers. The last `dispose()` releases the shared lease.
+  Custom loaders remain isolated (no cross-tenant or unexpected global sharing).
+- Package contents use compact caches only. Original files remain in the source
+  project for comparisons and rollback; this does not shrink that working folder.
+
+## Measurements
+
+Fresh Node process on this Windows host, `node --expose-gc measure-pet-memory.mjs`;
+same seed and sixty 160×50 frames. MB below means 1,000,000 bytes.
+
+| Metric | Before | After |
+| --- | ---: | ---: |
+| Art storage resident before selected-frame reconstruction | 315.8 MB | 106.5 MB |
+| Compressed runtime art files | 69.9 MB | 54.2 MB |
+| Process RSS after rendering | 498.4 MB | 211.8 MB |
+| Peak process RSS during load + rendering | 1,014.3 MB | 233.1 MB |
+
+These are local samples, not hard memory budgets. RSS includes Node, geometry,
+temporary buffers and allocator retention. After last disposal, an event-loop
+turn and explicit GC, the new run returned to about 94.9 MB RSS and 0.15 MB
+ArrayBuffers. Actual reclamation in a host application is GC-dependent.
+Browser loading uses DecompressionStream, so Node's RSS results are not browser
+measurements. See `pet-memory-baseline.json` and `pet-memory-compact.json`.
+
+## Reproduce / verify
+
+`node audit-pet-frames.mjs` counts full, unique and cropped pixel bytes.
+`node prepare-pet-frame-store.mjs` rebuilds the eight compact files from preserved
+original caches, validating source hashes and every reconstructed frame before
+writing the final manifest. `node --test puppy-frame-store.test.mjs
+retrieviewer-lossless.test.mjs retrieviewer.test.mjs` verifies all 2,341 logical
+frames, raw/packed sampler equality, 80 end-to-end renders at different views,
+depths and mirrors, and shared-asset lifecycle. The import API is unchanged.
+
+## Remaining weight
+
+106.5 MB of decoded cropped pixels is still substantial. Delta-coded frames,
+on-demand compressed blocks or optional art sets could reduce it further, but
+need separate CPU/latency and portability validation. This pass deliberately
+keeps the pixel output and synchronous `frame()` contract exact.

package/PUPPY-Q5-COMPARISON.md

@@ -0,0 +1,73 @@
+# 32-level predictive art (default since v0.1)
+
+Q5 is now the default after user visual comparison and approval. No original
+artwork/cache was overwritten, no poses removed, and movement timing is unchanged.
+Q5 is a **lossy** palette reduction, not a lossless replacement.
+
+## Try it
+
+- Synchronized comparison: `http://127.0.0.1:60668/puppy-q5-compare.html`
+- Normal companion screen: `http://127.0.0.1:60668/puppy-paper.html?palette=q5`
+- Terminal candidate: `npm run pet:companion -- --q5`
+- JS host: `await createPet()`. Original: `artProfile:'original'` with original files.
+- Local original screen: `http://127.0.0.1:60668/puppy-paper.html?palette=original`
+
+The comparison gives both pets the same seed, elapsed time, steps, interactions,
+camera and grid. It checks both state and life-report equality. Ball/treat affect
+both; pause freezes both. Reduced motion starts paused; hidden tabs stop stepping.
+Changed-dot percentage is a diagnostic, not a perceptual quality score. Examine
+eyes, mouth, fur tips and temporal sparkle. The comparison loads **both** art sets;
+its memory is not the standalone candidate's memory.
+
+## Codec
+
+Source pixel v becomes q=round(v*31/255), displayed as round(q*255/31). Maximum
+source-pixel error is4. The original unique-frame map, crop rectangles and logical
+indices stay unchanged. Crops use adaptive PNG-style row prediction (None/Sub/Up/
+Average/Paeth), then deterministic gzip. RVQ5 validation rejects malformed shapes,
+maps, offsets, row filters and decoded indices outside0..31.
+
+At load, prediction is reversed once and indices are repacked to **5 bits/pixel**.
+The expanded filtered input is not retained. A two-frame LRU expands selected
+frames to the existing 8-bit sampler interface. Original and Q5 caches have separate
+sharing/refcount entries; pets' actors, needs, clocks and buffers remain independent.
+
+## Local measurements
+
+Fresh Node v24.19.0 processes on this Windows host, explicit GC, seed731,
+sixty frames at160×50 cells. These are samples, not platform-wide limits.
+
+| Metric | Original | Q5 candidate |
+| --- | ---: | ---: |
+| Compressed art | 54.2 MB | 18.7 MB |
+| Resident cropped pixel payload | 106.4 MB | 66.5 MB |
+| RSS after rendering | 211.8 MB | 172.0 MB |
+| Load time | 270 ms | 737 ms |
+| Mean sampled frame time | 2.66 ms | 2.61 ms |
+
+Startup is slower due to prediction reversal/packing. Q5 peak RSS varied from200
+to228 MB in two samples. After disposal + an event-loop turn + explicit GC,
+ArrayBuffers returned to about0.15 MB. Browser decoding is synchronous CPU work
+between loads. Desktop Aside was exercised; physical mobile and every terminal
+font were not tested. See `pet-q5-comparison-report.json`.
+
+## Verification / status
+
+- All2,341 logical frames match the specified quantized source; artifact and
+  original-source hashes are separate in `pet-q5-manifest.json`.
+- Prediction, bit packing, partial bytes, malformed input, LRU bounds and input
+  detachment are tested. Generator checks original-file hashes remain unchanged.
+- A160-frame fetch/treat simulation keeps state, reports, mouth and projection
+  equal. Changed dots / union of lit dots was0.3431% at160×50; not visual approval.
+- Aside: fetch/pickup/carry/drop/offer, treat and frozen pause stay synchronized.
+  Desktop side and frontal-chewing screenshots inspected. User reported no visible
+  difference, possibly preferring32 levels; default switch was then authorized.
+- Initial codec handoff:230 tests passed. Current product checks: npm test and
+  npm run test:package (see dist/package-check.json after packaging).
+
+Build: `node prepare-pet-q5.mjs`. Memory: `node --expose-gc measure-pet-memory.mjs --q5`.
+
+The package now includes Q5 binaries/manifest only; comparison UI and original
+caches remain in the source workspace. Original hosts must separately copy the
+files from getPetAssetFiles('original') and supply loadAsset. This prevents
+shipping both art sets. See PLUGIN.md for portable tarball installation.