@bitefoundry/retrieviewer 0.0.17 → 0.0.19

package/ASSET-PROVENANCE.md

@@ -121,3 +121,14 @@ 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.
+
+## Ginger cat release · 2026-10-25
+
+The owner explicitly selected CC BY-SA4.0 for the approved ginger cat and
+authorized including it in this npm/website release. Code stays MIT.
+Purrviewer source commit5452da3569623b26f1ea87f1097735a1606c5c67 records
+the65-key artwork and code. The included ART.md records source-sheet hashes,
+registration and approved extensions; research photos were observation only,
+not generation inputs or bundled runtime assets. Original source sheets,
+research media and the unused tuxedo prototype are excluded. Alternative RVZ5
+encoding preserves every decoded Q5 pixel. See the cat ASSETS-LICENSE.md.

package/ASSETS-LICENSE.md

@@ -57,3 +57,9 @@ unrestricted. No warranty or legal-clearance certification is supplied.
 사용·수정·재배포도 가능하며, 변경한 그림을 배포할 때는 동일조건을 지켜야
 합니다. 코드에는 별도의 MIT 라이선스가 적용됩니다. 사진 참고 출처와 가공
 경위는 ATTRIBUTION.md에 포함되며, 원본 사진은 패키지에 포함하지 않습니다.
+
+## Ginger cat (0.0.18)
+
+The included Purrviewer ginger-cat artwork and metadata also use CC BY-SA 4.0,
+explicitly selected by the owner on 2026-10-25. See
+[integrations/purrviewer/ASSETS-LICENSE.md](integrations/purrviewer/ASSETS-LICENSE.md).

package/ATTRIBUTION.md

@@ -57,3 +57,11 @@ 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.
+
+## Purrviewer ginger cat
+
+Ginger-cat artwork and motion assembly: BiteFoundry project maintainer, 2026.
+AI-generated poses, registered and quantized into grayscale Q5 crops.
+CC BY-SA 4.0; attribution and creation record in
+[integrations/purrviewer/ASSETS-LICENSE.md](integrations/purrviewer/ASSETS-LICENSE.md)
+and [ART.md](integrations/purrviewer/ART.md).

package/DESKTOP-PLATFORMS.md

@@ -14,7 +14,7 @@ earlier0.0.3 baseline. macOS remains experimental.
 
 | Platform | Adapter | Current verification boundary |
 | --- | --- | --- |
-| Windows10/11 | .NET Framework/Win32 layered window | Live verified; shared-adapter regression checks passed on this host |
+| Windows10/11 | QuickJS/Win32 basic; Node/.NET optional watching | Live verified; shared-adapter regression checks passed on this host |
 | macOS | Built-in osascript/JXA AppKit, no Python/Xcode/browser runtime | Experimental; no macOS runtime available on this Windows host |
 | Linux X11 | Python3.6+ stdlib ctypes + X11/Xrender/Xext | AlmaLinux8 GLIBC2.28/Python3.6.8/Node22.23.4 live checks passed on owned Xvfb + Openbox + xcompmgr |
 | Linux native Wayland | No arbitrary-window tracking adapter | Refused, including sessions exposing an Xwayland DISPLAY; no insecure compositor workaround |

package/INSTALLING.md

@@ -13,7 +13,8 @@ mask and native painter, without new color sprites or screen capture.
 Windows and AlmaLinux8/GLIBC2.28 X11 have live test evidence. macOS support is
 experimental and not runtime verified; native Wayland is unsupported. Linux needs
 system Python3.6+, X11/Xrender/Xext and a compositor; Windows needs the .NET
-Framework4 compiler. See [Windows controls and removal](WINDOWS-COMPANION.md).
+Framework4 compiler only for the optional compatibility engine. Windows x64
+basic mode uses the bundled native engine. See [Windows controls and removal](WINDOWS-COMPANION.md).
 
 ## Optional native OpenCode integration
 

package/LICENSE

@@ -1,16 +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.
+Retrieviewer licensing
+
+Software source code: MIT License, see LICENSE-CODE.
+Bundled puppy and ginger-cat 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/NATIVE-RUNTIME.md

@@ -0,0 +1,95 @@
+# Lightweight desktop runtime · 0.0.19
+
+Windows x64 basic desktop mode runs the existing JavaScript pet behavior in
+QuickJS-NG, inside the same native process that paints the transparent window.
+Node/npm launches it and exits. There is no persistent Node worker, CLR runtime,
+browser, Electron, extra npm dependency or install-time compiler in this mode.
+
+```sh
+retrieviewer desktop
+retrieviewer desktop --pet cat
+retrieviewer desktop-status --json
+retrieviewer desktop-stop
+```
+
+Choose Retriever or Ginger cat in the picker/control strip, or run the second
+command to switch a running native companion. Only the selected pet is loaded.
+Switching disposes its assets before creating the other one. No startup service,
+agent patch or wrapper is installed. Removal is `retrieviewer desktop-remove --yes`
+followed by `npm uninstall -g @bitefoundry/retrieviewer`.
+
+## Artwork and behavior
+
+The same pure dog/cat factories own motion, perspective, contacts, actions and
+autonomy. The native host supplies gzip, Q5 reconstruction, grayscale raster and
+stable Braille kernels. Individually compressed crops are read from indexed
+files, with two borrowed decoded frames per store. The 256 Braille-mask stamp
+atlas replaces thousands of GDI+ ellipse calls and preserves the original dots.
+
+The actual native kernels were compared to portable Node across 64 dog and 128
+cat output frames at 160×72 and 480×135 cells, including movement, eating,
+attention, stretching, greeting, company, tower and wheel. All 234,455,040 RGBA
+bytes matched. Tests retain SHA-256 results; no resampling or lossier art was
+introduced. Code is MIT. Dog and cat artwork is CC BY-SA 4.0.
+
+## Measured memory
+
+On this Windows10/11 x64 host, one native process rendered an owned off-screen
+3840×2160 window for150seconds per species, sampled twice per second. The
+ordinary runtime used its diagnostic target, real GDI+ painter and scheduled
+play/treat/attention or tower/wheel actions. No forced GC or working-set trimming.
+
+| Pet | Median RSS | Sampled maximum | OS lifetime peak |
+|---|---:|---:|---:|
+| Retriever |22.6MiB|35.3MiB|36.5MiB|
+| Ginger cat with tower/wheel |29.5MiB|34.6MiB|39.1MiB|
+
+Version0.0.19 uses up to8 disjoint cell-aligned paint regions inside the same
+process, reclaiming oversized/hidden surfaces. The preceding0.0.18 final run
+had medians29.4/44.2MiB and OS peaks40.3/65.4MiB for dog/cat respectively.
+See [sparse surface measurements](SPARSE-PAINT.md) for the matching workloads,
+pixel comparisons and CPU tradeoff. This is not a universal50MiB memory cap.
+Raw local evidence: dist/sparse-paint-memory/{dog,cat,report}.json.
+
+## Scope
+
+This default native runtime is **Windows x64**. `--watch stackbite` and
+`--brain openrouter` retain the Node/.NET compatibility path on Windows;
+`--engine node` explicitly selects it. Their memory use is higher. Linux X11
+keeps Node + system Python; macOS keeps its experimental Node/JXA path. Both
+species work through those adapters, with the existing three controls mapped
+to toy/greeting, treat and company for the cat. Tower/wheel controls are in the
+Windows native bar and website. Browser previews keep their portable loader.
+The native memory figures do not describe optional watching, other operating
+systems or browser tabs. No blanket memory ceiling is promised for every window.
+
+## Build and lifecycle
+
+Maintainers run `npm run build:native` on Windows x64 with Visual Studio 2022 C++
+Build Tools, CMake and Bun. It bundles the ordinary factories without source
+rewriting, verifies pinned QuickJS/zlib commits, statically links the CRT, and
+writes a size/SHA-256 manifest for the shipped binary and bundle. Only Windows
+system DLLs are required. Sources, source pins and upstream license texts ship
+with the package. End users receive the prebuilt executable.
+
+The short-lived launcher sends configuration over stdin, waits for readiness,
+then acknowledges detach. EOF before detach stops the native process. A local
+owner-only named pipe with a per-launch random token supports status, species
+switching and stop; remote pipe clients are rejected. The process removes only
+its own session file on exit. The picker follows one explicitly selected app;
+it hides and freezes when that app is not foreground. It reads window geometry
+and titles, not screen content or keyboard input. Watch/brain remain opt-in.
+
+QA: `node --test native-desktop.test.mjs`, `npm run check:native-pixels`, and
+`node tools/measure-native-pet.mjs 150`. These use isolated state and owned
+off-screen diagnostic windows, preserving an already-running user companion.
+
+The executable embeds the Windows UTF-8 process code-page manifest (Windows10
+1903+ /11) so QuickJS stdio also reads Korean/non-ASCII installation paths.
+A regression test launches both species from Korean bundle, art and state paths.
+
+## Sparse paint surfaces
+
+[Sparse paint regions](SPARSE-PAINT.md) preserve final masks while reducing
+empty bitmap space. Their HWNDs remain click-through and non-activating; no
+extra pet process, runtime dependency or animation asset is introduced.

package/PREREQUISITES.md

@@ -93,3 +93,10 @@ npx --yes --package @bitefoundry/retrieviewer@latest retrieviewer desktop
 
 `npx` still needs Node/npm and a compatible GUI desktop, and may download the
 package into npm's cache. It does not create a permanent global command.
+
+## Windows native basic mode (0.0.18)
+
+Windows10/11 x64 + Node20+ for npm/launch. The shipped QuickJS/Win32 runtime
+needs no compiler, CLR or additional runtime download. Node exits after launch.
+Optional StackBite/LLM watching or --engine node keeps the existing .NET helper
+and Node worker; that compatibility mode needs the Windows Framework4 compiler.

package/PUPPY-MEMORY.md

@@ -1,3 +1,25 @@
+# 0.0.19 sparse painter result
+
+Windows x64 basic mode retains one native process and splits sparse content
+into bounded cropped surfaces. In the same real4K150s schedule, dog median RSS
+was22.6MiB (OS peak36.5MiB); cat with tower/wheel29.5MiB (peak39.1MiB).
+Final masks and behavior are unchanged. No forced GC/trim; optional watching,
+other OS hosts and browser tabs are outside this memory claim. See
+[sparse paint evidence](SPARSE-PAINT.md) and [runtime scope](NATIVE-RUNTIME.md).
+
+## Previous0.0.18 native result (historical)
+
+# 0.0.18 native desktop result
+
+Windows x64 basic mode now uses a single QuickJS/Win32 process. In real4K
+150second tests the dog median RSS was29.4MiB (OS lifetime peak39.9MiB),
+and cat median44.2MiB (peak65.3MiB). Same artwork/motion; no forced GC/trim.
+The cat typically fits50MiB here but peaks exceed it. These figures exclude
+optional StackBite/LLM watching, other OS hosts and browser tabs.
+See [method, architecture and compatibility scope](NATIVE-RUNTIME.md).
+
+## Earlier Node measurements (historical)
+
 # Runtime weight and performance
 
 ## Indexed local art (local candidate, 2026-10-25)

package/README.ko.md

@@ -80,7 +80,7 @@ PATH에 넣어야 해요. [bash·csh/tcsh·Windows별 안내](PREREQUISITES.md#c
 
 | 환경 | 상태와 필요 조건 |
 | --- | --- |
-| Windows10/11 x64 | 실제 실행 검증. Node + .NET Framework4 컴파일러. 처음 실행 시 헬퍼 자동 빌드. |
+| Windows10/11 x64 | 실제 실행 검증. Node20+. 기본 실행은 포함된 네이티브 엔진, 선택형 감시는 .NET 호환 엔진. |
 | Linux X11 | AlmaLinux8 / GLIBC2.28 / Python3.6.8 / Node22.23.4를 격리된 GUI에서 검증. Python3.6+, X11/Xrender/Xext, compositor 필요. |
 | macOS | **실험적 지원. 실제 Mac 실행 미검증.** 기본 osascript/AppKit 사용. |
 | 네이티브 Wayland·화면 없는 SSH | 데스크톱 오버레이 미지원. 세션·보안 설정을 자동 변경하지 않아요. |
@@ -147,3 +147,19 @@ JS 플러그인과 JSONL 브리지를 제공해요. 화면·입력·시간 제
 
 AI로 생성한 그림에 자세 정렬·접지·프레임 처리를 적용한 애니메이션입니다.
 실제 모션 캡처나 자의식이 있는 강아지라고 주장하지 않아요.
+
+## 0.0.19
+
+Windows 기본 실행에서 표시 영역을 나누고 불필요하게 커진 버퍼를 회수해요.
+그림과 동작은 그대로예요. 실제4K150초 측정에서 강아지는 중앙값22.6MiB·최고36.5MiB,
+가구가 있는 고양이는29.5MiB·39.1MiB였어요. 선택형 감시·다른OS·브라우저는
+별도 범위예요. [측정과 검증 기록](SPARSE-PAINT.md)을 참고하세요.
+
+## 0.0.18
+
+Windows x64 기본 실행은 네이티브 프로세스 하나만 남고 Node는 종료돼요.
+그림과 움직임은 그대로예요. `retrieviewer desktop --pet cat` 또는 창 선택창에서
+치즈 고양이를 고를 수 있어요. 둘 중 선택한 펫만 불러옵니다.
+StackBite·LLM 감시는 메모리를 더 쓰는 기존 Node 호환 엔진을 유지해요.
+Linux·macOS·브라우저의 호스트 구조는 그대로이며, 로컬 그림은 두 펫 모두
+필요한 프레임만 파일에서 읽어요. [지원 범위와 측정](NATIVE-RUNTIME.md).

package/README.md

@@ -77,7 +77,7 @@ Do not use `sudo npm install -g` as a blanket workaround.
 
 | Desktop | Status / requirements |
 | --- | --- |
-| Windows 10/11 x64 | Live tested. Node + Windows .NET Framework 4 compiler; helper builds on first launch. |
+| Windows 10/11 x64 | Live tested. Node20+; bundled native engine for basic mode. Optional watching uses the .NET compatibility helper. |
 | Linux X11 | AlmaLinux 8 / GLIBC 2.28 / Python 3.6.8 / Node 22.23.4 tested in an isolated composited X11 desktop. Requires system Python 3.6+, X11/Xrender/Xext and a compositor. |
 | macOS | **Experimental; no Mac runtime verification yet.** Uses built-in osascript/AppKit. |
 | Native Wayland / headless SSH | Not supported by the desktop overlay. No session/privacy workaround is installed. |
@@ -188,3 +188,21 @@ the complete package is **not MIT-only**.
 The puppy artwork was developed with AI-generated imagery and programmatic pose,
 grounding and frame processing. It is authored animation, not motion capture or
 a claim of sentience.
+
+## 0.0.19
+
+Windows basic mode now splits distant content into small paint regions and
+reclaims oversized/hidden surfaces. Same pets, artwork and behavior. In real4K
+150s tests: dog median22.6MiB / OS peak36.5MiB; cat with tower/wheel29.5 /39.1MiB.
+Optional watching and other OS/browser hosts keep their separate memory scope.
+See [measurements and verification](SPARSE-PAINT.md).
+
+## 0.0.18
+
+Windows x64 basic mode now runs one native process; Node exits after launch.
+The existing artwork and behavior stay the same. Use `retrieviewer desktop --pet cat`
+for the ginger cat, or select it in the window picker. Only one pet is loaded.
+Optional StackBite/LLM watching retains the higher-memory Node compatibility
+engine. Linux/macOS and browser previews retain their existing host architecture.
+Both species use indexed crops for local loading.
+See [runtime scope and measurements](NATIVE-RUNTIME.md).

package/RELEASING.md

@@ -1,3 +1,38 @@
+# Retrieviewer 0.0.19 release process
+
+Current target: `@bitefoundry/retrieviewer@0.0.19`, public `latest`.
+The owner explicitly authorized npm and website deployment on2026-10-25.
+Ship the verified sparse Windows painter: bounded disjoint final-mask regions,
+reclaimable buffers, preserved artwork/behavior and existing compatibility modes.
+Keep code MIT and both artworks CC BY-SA4.0; no new generation inputs or assets.
+
+Existing evidence covers300 exact native paint frames,56 partition cases,
+real4K150s operating memory and owned-window shrink/hide/restore/switch/teardown.
+Run the suite/release gate, build and install a fresh exact tarball, exercise its
+actual native resources/picker, then publish that same artifact after CI.
+Verify registry integrity, fresh registry installation and production website.
+Keep website figures scoped to Windows basic mode; update EN/KO copy and cache
+keys together. Preserve old releases, the user's running pet and privacy setup.
+
+## Previous0.0.18 scope (historical)
+
+Current target: `@bitefoundry/retrieviewer@0.0.18`, public `latest`.
+The owner authorized immediate npm and website deployment of the lightweight
+shared engine on2026-10-25, and explicitly selected CC BY-SA4.0 for cat artwork.
+Code remains MIT. Ship the real native Windows x64 basic runtime, ginger cat and
+portable compatibility paths. Preserve approved artwork, physics, autonomy,
+optional watcher/brain behavior and the user's already-running pet.
+
+Validate exact native-vs-portable rendered pixels, authenticated control,
+species switching, startup EOF cleanup, real picker lifecycle and real4K memory.
+Build/install a fresh exact tarball, compare every shipped byte, run the full
+suite and owned Windows checks, then publish that artifact. Verify registry
+integrity, a fresh public-registry consumer and the deployed bilingual website.
+Native low-memory figures apply only to Windows x64 basic mode; watch/brain,
+other operating systems and browser previews keep their documented scope.
+
+## Previous 0.0.17 scope (historical)
+
 # Retrieviewer 0.0.17 release process
 
 Current target: `@bitefoundry/retrieviewer@0.0.17`, public `latest`.

package/SPARSE-PAINT.md

@@ -0,0 +1,66 @@
+# Sparse Windows paint surfaces · 0.0.19
+
+Version0.0.19 builds on0.0.18. JavaScript behavior, Q5 art, world/contact math, colors and
+Braille masks are unchanged; the native painter allocates less empty space.
+
+## Change
+
+The old painter kept one bitmap spanning every nonempty cell. The cat, tower
+and wheel therefore retained a large transparent rectangle between objects.
+Its width and height only grew until species switch/exit. A held-pose ablation
+at3840×2160 measured cat+furniture38.6MiB versus cat alone17.6MiB; the equivalent
+single DIB capacities were12.22MiB and1.63MiB respectively.
+
+The new painter partitions the FINAL cell mask into up to8 disjoint cropped
+regions. Greedy splits account for64px allocation rounding and must save at
+least256KiB of bitmap space. No glyph is resampled, dropped, drawn twice or
+recolored; geometry and palette still share the original stamp atlas. A dense
+scene can remain a single region. This is a bounded native composition change,
+not extra animal simulations or one process per region.
+
+Each surface reuses capacity while it is within2× its current rounded target
+area. Oversized capacity is reclaimed on repaint; unused regions are destroyed.
+Hidden/minimized/retargeted scenes release their surfaces and overlay windows.
+Resume repaints from the current simulation state. Windows system/compositor
+allocations remain separate from the reported `paintSurfaceBytes` DIB counter.
+
+## Measurement
+
+Same Windows11 x64 host, real native painter and an owned off-screen physical
+3840×2160 scene. Seed731; the existing150s diagnostic action schedule and300
+roughly0.5s samples per pet. No forced GC/working-set trimming. Watch/brain off;
+harness and external DWM/GPU memory excluded. Baseline is the tested0.0.18
+installed-artifact run. These finite runs do not establish a universal RAM cap.
+
+| Scene |0.0.18 median RSS|0.0.19 median RSS|0.0.18 OS peak|0.0.19 OS peak|
+|---|---:|---:|---:|---:|
+|Dog|29.35MiB|22.63MiB|40.34MiB|36.45MiB|
+|Cat with tower/wheel|44.22MiB|29.46MiB|65.45MiB|39.13MiB|
+
+The short fixed-pose cat+furniture comparison fell from38.6 to27.3MiB. This is
+a different workload from the moving150s runs above, not a replacement for them.
+Actual resize testing reduced allocated DIBs from6.52 to1.66MiB. Minimizing
+reported0 DIB bytes and0 overlay HWNDs; restore and dog/cat switching recovered.
+
+A paired16s cat timing check had92 paints/340 rendered calls in both variants.
+Mean render time changed3.06→3.94ms, P95 12.42→16.68ms. Partitioning trades some
+CPU for memory; these timings are not a constant-FPS guarantee.
+
+## Verification
+
+- Native self-test:56 grids across7 cell sizes. Occupied masks covered once,
+  all regions disjoint/in bounds, partition plans no larger than one crop,
+  at most8 regions, and real DIB shrink/release verified.
+- Real painter:300 moving frames across dog/cream and cat/gold/dark compared
+  against the old monolithic GDI+ ellipse output, byte-for-byte including alpha.
+  This tests per-frame paint pixels, not atomicity of compositor presentation.
+- Real owned windows: pick/reselect,4K→small→4K, minimize/restore, species
+  switching, bootstrap detach, startup EOF, stop and Korean paths passed.
+- Local full suite:243 passed,2 macOS-only tests skipped on this Windows host.
+
+Reproduce with `node --test native-desktop.test.mjs`,
+`node tools/check-native-paint.mjs`, `node tools/check-native-resources.mjs`,
+and `node tools/measure-native-pet.mjs 150` after `npm run build:native`.
+Local evidence is under dist/sparse-paint-memory, dist/paint-parity-HlzSTl,
+dist/paint-resource-m3dMB1 and dist/sparse-timing-REFNLe. QA output is not
+packaged. Linux/macOS/browser and optional Node/CLR watching paths are unchanged.

package/THIRD-PARTY-NOTICES.md

@@ -17,3 +17,11 @@ photographers (Scott, CC BY 2.0; Stefan Bauer, CC BY-SA 2.5) and adaptation hist
 are credited in ATTRIBUTION.md. Original photographs are not bundled. See LICENSE,
 LICENSE-CODE, ASSETS-LICENSE.md and the bounded ASSET-PROVENANCE.md review. No
 comprehensive legal-clearance or exclusive AI-output ownership claim is made.
+
+## Native Windows runtime
+
+The prebuilt Windows x64 engine includes QuickJS-NG 0.17.0 (MIT) and zlib
+1.3.2 (Zlib). Exact source commits and complete license notices are in
+`integrations/native-windows/sources.json` and `THIRD-PARTY-LICENSES.txt`.
+The optimized kernels and host are MIT. No downloaded runtime is installed
+at launch; no additional npm runtime dependency was added.

package/WINDOWS-COMPANION.md

@@ -9,9 +9,10 @@ wrapper. Version0.0.2 includes it; version0.0.1 does not. Setup is two steps:
 Choose a supported ordinary Windows app window (including a terminal containing
 Codex). Then use your app normally, without a
 wrapper, shell alias, patched binary, changed credentials, or agent configuration.
-The helper uses native Windows/.NET Framework facilities and the existing Node
-pet engine. No Electron, Chromium, downloaded helper binary or new npm dependency.
-Windows10/11 x64 with Node20+ and the .NET Framework4 compiler is required. Other
+Basic mode uses the bundled QuickJS/Win32 engine in one process; Node exits
+after launch. No Electron, Chromium, extra npm dependency or compiler is needed.
+Windows10/11 x64 with Node20+ is required. Optional watch/brain or --engine node
+keeps the existing Node/.NET compatibility path and its Framework4 compiler. Other
 desktop platforms and exclusive fullscreen/security surfaces are not certified.
 Launch reports
 that the picker is ready, **not** that the user has selected a window or visually
@@ -35,8 +36,8 @@ approved the pet.
   The picker locally reads window titles/process names; tracking reads window
   geometry, foreground state, visibility and owning process ID.
 - No automatic startup, background scheduled task, registry entry or MCP is added.
-  Exit stops both the painter and engine. If either process closes, its counterpart
-  exits too. Losing the target hides the pet; tray selection can attach another.
+  Exit stops the native process. The compatibility path stops both painter and engine;
+  if either closes, its counterpart exits too. Losing the target hides the pet; tray selection can attach another.
 
 ## Stop, remove, and recover
 
@@ -52,7 +53,8 @@ One-command companion removal (stop, wait for exit, remove only its cache):
 retrieviewer desktop-remove --yes
 ```
 
-The tray icon also provides window selection, hide/resume and exit. `desktop-stop`
+The control strip provides window selection, pause/resume and exit. The older
+compatibility helper also has a tray menu. `desktop-stop`
 asks the companion to exit through an authenticated local named pipe; it never
 kills a PID from a stale file. The worker may terminate only its own stuck child
 painter after a graceful timeout. Cache cleanup refuses a live/unreachable worker,
@@ -111,3 +113,10 @@ check (not total app memory or a4K performance claim). A Windows GUI startup bug
 was fixed by building a GUI-subsystem helper and not applying SW_HIDE to it; the
 real user picker was verified in Windows' visible main-window list. User visual
 approval after selecting a terminal remains separate.
+
+## Pet selection
+
+Use retrieviewer desktop --pet cat, or select Ginger cat in the native picker
+or control strip. Only one pet is loaded; the previous asset lease is disposed
+on switch. Cat controls include greeting, treat, company, tower and wheel.
+See [native runtime](NATIVE-RUNTIME.md) for measurements and scope.

package/braille.mjs

@@ -37,10 +37,10 @@ function stableBraille(rgba,width,height,brightness,contrast){
   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'}={}){
+export function rgbaToBraille(rgba,width,height,{brightness=1,contrast=1,method='floyd',kernel=null}={}){
   if(!Number.isInteger(width)||!Number.isInteger(height)||width<1||height<1||width*height>1_000_000||rgba.length!==width*height*4)throw Error('Invalid RGBA image');
   if(!Number.isFinite(brightness)||brightness<=0||brightness>4||!Number.isFinite(contrast)||contrast<=0||contrast>4||!['floyd','bayer','stable'].includes(method))throw Error('Invalid dithering options');
-  if(method==='stable')return stableBraille(rgba,width,height,brightness,contrast);
+  if(method==='stable')return kernel?.braille?kernel.braille(rgba,width,height,brightness,contrast):stableBraille(rgba,width,height,brightness,contrast);
   const values=new Float32Array(width*height),bits=new Uint8Array(width*height);
   for(let i=0;i<values.length;i++){
     const p=i*4,luma=(.2126*rgba[p]+.7152*rgba[p+1]+.0722*rgba[p+2])/255*(rgba[p+3]/255);

package/integrations/native-windows/CMakeLists.txt

@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.21)
+project(retrieviewer_native LANGUAGES C CXX)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+set(QJS_ENABLE_INSTALL OFF CACHE BOOL "" FORCE)
+get_filename_component(PET_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../.." ABSOLUTE)
+add_subdirectory("${PET_ROOT}/dist/native-memory/quickjs-src" quickjs-build EXCLUDE_FROM_ALL)
+set(ZLIB_BUILD_TESTING OFF CACHE BOOL "" FORCE)
+set(ZLIB_BUILD_SHARED OFF CACHE BOOL "" FORCE)
+set(ZLIB_INSTALL OFF CACHE BOOL "" FORCE)
+add_subdirectory("${PET_ROOT}/dist/native-memory/zlib-src" zlib-build EXCLUDE_FROM_ALL)
+add_executable(retrieviewer-native host.cpp)
+target_link_options(retrieviewer-native PRIVATE "/MANIFEST:EMBED" "/MANIFESTINPUT:${CMAKE_CURRENT_SOURCE_DIR}/application.manifest")
+target_link_libraries(retrieviewer-native PRIVATE qjs qjs-libc zlibstatic gdiplus user32 gdi32 advapi32 psapi)
+target_compile_definitions(retrieviewer-native PRIVATE _CRT_SECURE_NO_WARNINGS NOMINMAX UNICODE _UNICODE)

package/integrations/native-windows/THIRD-PARTY-LICENSES.txt

@@ -0,0 +1,77 @@
+QuickJS-NG
+
+The MIT License (MIT)
+ 
+Copyright (c) 2017-2026 Fabrice Bellard
+Copyright (c) 2017-2024 Charlie Gordon
+Copyright (c) 2023-2026 Ben Noordhuis
+Copyright (c) 2023-2026 Saúl Ibarra Corretgé
+
+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.
+
+
+zlib
+
+Copyright notice:
+
+ (C) 1995-2026 Jean-loup Gailly and Mark Adler
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+
+  Jean-loup Gailly        Mark Adler
+  jloup@gzip.org          madler@alumni.caltech.edu
+
+
+fflate
+
+MIT License
+
+Copyright (c) 2026 Arjun Barrett
+
+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/integrations/native-windows/application.manifest

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
+  <application xmlns="urn:schemas-microsoft-com:asm.v3">
+    <windowsSettings>
+      <activeCodePage xmlns="http://schemas.microsoft.com/SMI/2019/WindowsSettings">UTF-8</activeCodePage>
+    </windowsSettings>
+  </application>
+</assembly>

package/integrations/native-windows/desktop.mjs

@@ -0,0 +1,48 @@
+// Short-lived bootstrap only. The native process owns the pet, UI and control pipe.
+import {spawn} from 'node:child_process';
+import {readFile,open,unlink,stat} from 'node:fs/promises';
+import {createHash,randomBytes,randomUUID} from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+import {prepareRoot,noLink,requestSession,readSession} from '../windows-overlay/desktop.mjs';
+import {controlAddress} from '../desktop/platform.mjs';
+const root=new URL('./',import.meta.url),bundle=new URL('./runtime.bundle.mjs',root),binary=new URL('./bin/win32-x64/retrieviewer-native.exe',root);
+export async function verifyNativeArtifact(){
+ const manifest=JSON.parse(await readFile(new URL('manifest.json',root),'utf8'));
+ if(manifest.version!==1||manifest.platform!=='win32-x64')throw Error('Invalid native runtime manifest');
+ for(const name of ['runtime.bundle.mjs','bin/win32-x64/retrieviewer-native.exe']){
+  const expected=manifest.files[name],url=new URL(name,root),info=await stat(url);
+  if(!expected||info.size!==expected.bytes||info.size>16*1024*1024)throw Error('Native runtime size mismatch: '+name);
+  const bytes=await readFile(url);if(createHash('sha256').update(bytes).digest('hex')!==expected.sha256)throw Error('Native runtime checksum mismatch: '+name);
+ }
+ return manifest;
+}
+export async function switchNativePet(options,session,pet){
+ await requestSession(session,'pet-'+pet);
+ for(let i=0;i<40;i++){const status=await requestSession(session,'status');if(status.pet===pet)return {...status,alreadyRunning:true,switchedPet:true};await new Promise(r=>setTimeout(r,50));}
+ throw Error('The native companion did not finish switching pets');
+}
+export async function startNativeDesktop(options={}){
+ if(process.platform!=='win32'||process.arch!=='x64')throw Error('Native desktop currently requires Windows x64');
+ await verifyNativeArtifact();const paths=await prepareRoot(options);await noLink(paths.session);
+ const pipe=controlAddress({uuid:randomUUID()}),token=randomBytes(32).toString('hex');
+ const args=[fileURLToPath(bundle),fileURLToPath(new URL('../../',root)),'--production'];
+ if(options.nativeDiagnostic&&options.nativeVerifyPaint)args.push('--verify-regions');
+ if(options.nativeDiagnostic&&options.nativeProofPath)args.push('--proof='+options.nativeProofPath);
+ const child=spawn(fileURLToPath(binary),args,{detached:true,windowsHide:true,stdio:['pipe','pipe','pipe'],env:{...process.env,OPENROUTER_API_KEY:undefined}});
+ let owns=false,complete=false,stderr='';const session={owner:'bitefoundry-retrieviewer-overlay-v1',pid:child.pid,pipe,token};
+ child.stderr.on('data',b=>stderr=(stderr+b.toString('utf8')).slice(-2048));child.stdin.on('error',()=>{});
+ try{
+  if(!Number.isInteger(child.pid))throw Error('Cannot start native companion');
+  const file=await open(paths.session,'wx',0o600);owns=true;try{await file.writeFile(JSON.stringify(session)+'\n');}finally{await file.close();}
+  await new Promise((resolve,reject)=>{
+   let buffer='',ready=false,settled=false;const finish=(error)=>{if(settled)return;settled=true;clearTimeout(timer);error?reject(error):resolve();};
+   const timer=setTimeout(()=>finish(Error('Native companion startup timed out')),15000);
+   child.once('error',error=>finish(error));child.once('exit',code=>finish(Error('Native companion exited before ready ('+code+'): '+stderr)));
+   child.stdout.on('data',bytes=>{buffer+=bytes.toString('utf8');if(buffer.length>65536)return finish(Error('Oversized native startup response'));let at;while((at=buffer.indexOf('\n'))>=0){const line=buffer.slice(0,at);buffer=buffer.slice(at+1);let message;try{message=JSON.parse(line);}catch{return finish(Error('Invalid native startup response'));}if(message.ready===true&&!ready){ready=true;child.stdin.end('DETACH\n');}else if(message.detached===true&&ready)finish();}});
+   const pet=options.pet??'dog';child.stdin.write(JSON.stringify({pet,seed:options.nativeDiagnostic?731:randomBytes(4).readUInt32LE(),ink:options.ink??(pet==='cat'?'gold':'cream'),inkExplicit:!!options.ink,returnStyle:options.returnStyle??'auto',diagnostic:options.nativeDiagnostic===true,testPicker:options.nativePickerTest===true,pipe,token,sessionFile:paths.session})+'\n');
+  });
+  const status=await requestSession(session,'status');complete=true;child.unref();child.stdout.destroy();child.stderr.destroy();return {...status,detached:true};
+ }finally{
+  if(!complete){child.stdin.destroy();if(child.exitCode===null)child.kill();if(owns){const current=await readSession(options).catch(()=>null);if(current?.token===token)await unlink(paths.session).catch(()=>{});}}
+ }
+}