dsh-apk-vm 0.0.0-stage → 0.3.13

package/CHANGELOG.md

@@ -0,0 +1,345 @@
+# Changelog
+
+## 0.3.13
+
+Open-source package identity.
+
+### Changed
+
+- Package name changed from `@local/dsh-apk-vm` to **`dsh-apk-vm`**, following the DSH plugin
+  naming convention (`dsh-*`). The Host export, client bundle id, Cordis patch row, smoke tests
+  and docs were updated to match.
+- `author` is now `yuxiaole-bili <https://github.com/yuxiaole-bili/>`.
+- Removed `private: true` and added `publishConfig` for the public npm package
+  **`dsh-apk-vm`**; the primary install command is now
+  `dsh plugin --profile web add dsh-apk-vm` (source/GitHub install remains a fallback).
+- Wrote the package/plugin descriptions (English + Chinese `meta.description`), expanded
+  keywords, and added a suggested GitHub repository description/topics list to
+  `docs/RELEASING.md`.
+- Configured repository metadata for
+  <https://github.com/yuxiaole-bili/dsh-apk-vm>: `repository`, `homepage`, `bugs`, README
+  badges/repository link, issue-template security/repository links, and the local `origin`
+  remote.
+- Added the community-market submission package: one-line value, copyable source install
+  command, capability category, risk/permissions/compatibility section, real screenshots
+  (main panel + right sidebar), and `docs/SUBMISSION.md` with the filled `dsh-plugin.org` issue
+  template.
+
+## 0.3.12
+
+Clipboard fix + open-source release preparation.
+
+### Fixed
+
+- `SET_CLIPBOARD` returned a BigInt sequence that could not be JSON-serialized; it is now a
+  decimal string.
+- `GET_CLIPBOARD` now sends the required single `copyKey` payload byte instead of an empty
+  message, which previously stalled the control stream and timed out.
+- Live-verified: set `dsh-clipboard-test-42`, then read it back successfully.
+
+### Open-source preparation
+
+- Added `CODE_OF_CONDUCT.md`, `.editorconfig` and `docs/RELEASING.md`.
+- Removed personal/local paths from DEMO/DESIGN/spike docs and scripts; removed the stale
+  hard-coded DSH WebSocket port fallback from `client.js`.
+- Updated `NOTICE` (only the bundled scrcpy JAR is redistributed; test-only upstream sources are
+  not in the repo), `SECURITY.md` supported versions and loopback threat model.
+- Package metadata: author; contributor/security/CoC/docs included in the npm pack file list.
+- README: open-source distribution note, CoC/release links, lifecycle test in the contributor
+  quick reference.
+- Added `docs/PRIVACY.md` and `scripts/privacy-scan.mjs`; CI scans the tracked tree for personal
+  paths, private IPs, agent instance IDs, credential patterns and emails. The clean single-commit
+  `open-source` branch is the recommended public history; the local dev history contains older
+  workspace paths.
+
+## 0.3.11
+
+Clipboard sync over scrcpy control.
+
+### Added
+
+- `buildSetClipboardMessage()` (u8 type=9, u64 sequence, u8 paste, i32 length, UTF-8) and
+  `ScrcpySession.setClipboard()` / `requestClipboard()` (`GET_CLIPBOARD`, awaited device reply).
+- `GET/POST /apk-vm/clipboard` plus per-instance `/apk-vm/instances/<id>/clipboard`.
+- Panel debug card: **Copy field to device** / **Get device clipboard** buttons (the latter also
+  writes to the host clipboard when permitted).
+- `apk_vm` actions `clipboard_set` / `clipboard_get`.
+
+## 0.3.10
+
+Two-finger pinch/zoom over the scrcpy control socket.
+
+### Added
+
+- `POST /apk-vm/touch` (and per-instance `/apk-vm/instances/<id>/touch`) forwards multi-pointer
+  touch down/move/up/cancel to the active scrcpy session. Coordinates are video-frame pixels.
+- The screen promotes a two-finger gesture from the adb single-pointer path to a scrcpy
+  multi-touch pinch, with pointer capture and 60 Hz move throttling.
+- `ScrcpyStream.sendTouch()` / `ExtraVmInstance.sendTouch()` for per-instance control.
+
+## 0.3.9
+
+Agent UI automation.
+
+### Added
+
+- `apk_vm` actions `find_ui` / `assert_text` / `tap_text`: dump UIAutomator XML, filter nodes by
+  text / resource-id / content-desc / class, return matching bounds/centers, assert presence, or
+  tap the matching node's center. `assert_text` returns `ok:false` on a missing node instead of
+  throwing, so Agents can branch on assertions.
+
+### Verified
+
+- Live multi-instance VM: `find_ui {"text":"Phone"}` → `Phone @ 102,1121`;
+  `assert_text` found 1 node; `tap_text` opened Phone; `key HOME` returned to the launcher.
+
+## 0.3.8
+
+Bootstrap a completely empty Android SDK.
+
+### Added
+
+- `bootstrapSdk()`: downloads the official command-line tools ZIP for Windows/macOS/Linux,
+  extracts it into `<sdkRoot>/cmdline-tools/latest`, runs `sdkmanager --licenses`, then installs
+  platform-tools/emulator/build-tools/platform. HTTPS only, 512 MiB cap, temp archive cleanup,
+  JDK pre-check, no shell interpolation.
+- `POST /apk-vm/setup {"action":"bootstrap-sdk"}`, gated by `allowSetupDownloads`;
+  Environment card shows **Bootstrap SDK** when sdkmanager is missing.
+- Setup report action list + 2 hermetic bootstrap tests (injected download/extract/exec).
+
+### Verified
+
+- `spike/setup-smoke.mjs`: **32/32** (bootstrap argv, extracted sdkmanager, license/install
+  calls, invalid-package rejection).
+- Live host: setup actions include `bootstrap-sdk` (unavailable because sdkmanager exists).
+
+## 0.3.7
+
+Hardware keyboard forwarding in the H.264/PNG screen.
+
+### Added
+
+- Clicking the guest screen focuses it; common hardware keys (arrows, Enter, Escape, Tab,
+  Backspace, Delete, Home) become Android key events, and printable characters are forwarded as
+  text input. Input fields are excluded so typing in the panel is unaffected.
+- Screen hint documents the keyboard behavior.
+
+## 0.3.6
+
+SDK component installation from the Environment card.
+
+### Added
+
+- `installSdkPackages({ packages })` in `lib/setup.js`: validated, bounded
+  `sdkmanager --install <pkg…>` with optional license stdin.
+- `POST /apk-vm/setup {"action":"install-tools"}` installs missing
+  platform-tools/emulator/build-tools/platform (or caller-supplied `packages`), gated by
+  `allowSetupDownloads: true`.
+- Environment card exposes the **Install SDK tools** action when adb/emulator are missing.
+- Setup report action list and hermetic setup test updated (30/30).
+
+## 0.3.5
+
+Static APK preview.
+
+### Added
+
+- `aapt2` badging parser now returns versionName/versionCode, min/target SDK, permissions,
+  features, native ABIs and the launcher icon path in addition to package/label/activity.
+- `GET /apk-vm/apk-info?path=…` static metadata (no VM boot).
+- `GET /apk-vm/apk-icon?path=…` extracts a raster launcher icon directly from the APK ZIP with
+  a dependency-free ZIP reader (adaptive XML icons are reported but not rasterized).
+- APK list shows icons for raster APKs; `apk_vm` action `apk_info`.
+
+### Verified
+
+- `anim60.apk`: targetSdk 34, zero permissions, activity resolved.
+- `DSH-1.12-vc13.apk`: icon extracted as a 631-byte PNG (`89 50 4e 47` signature).
+- `yuagent-final.apk`: versionName 0.4.4, 5 permissions, adaptive XML icon reported.
+
+## 0.3.4
+
+Live logcat and crash observability.
+
+### Added
+
+- Debug card: **Live logcat** toggle (2 s polling), **Crash log** button (`logcat -b crash`).
+- `AndroidVm.logcat({ buffer })` supports `main|system|crash|events|all|radio|kernel`;
+  HTTP routes accept `?buffer=`, and the `apk_vm` tool accepts `buffer`.
+- Verified `npm test` and the client smoke suite with the new debug controls.
+
+## 0.3.3
+
+Physical/remote adb device switching.
+
+### Added
+
+- `AndroidVm.listDevices()` reports emulator, USB/physical and network adb devices with
+  state/model/product/transport metadata.
+- `GET /apk-vm/devices` and `POST /apk-vm/device` (`{"serial":…}` / `{"serial":""}`) attach an
+  online device or restore the managed AVD identity; the Environment card has a device picker
+  with Attach/Detach.
+- `apk_vm` actions `devices`, `attach_device`, `detach_device`.
+- Stop/dispose never sends `emu kill` or disconnects an external physical device.
+
+### Verified
+
+- Attached the running emulator as an external device and detached back to `dsh_apk` while
+  retaining `ready`; `/apk-vm/devices` returns serial/state/kind/model.
+
+## 0.3.2
+
+Artifact download for screenshots/recordings.
+
+### Added
+
+- `GET /apk-vm/artifacts?name=…` streams a plugin-created screenshot/recording from the OS temp
+  dir with a strict basename whitelist (no arbitrary paths).
+- The panel's Record action now auto-downloads the MP4 after `screenrecord` completes.
+
+## 0.3.1
+
+Loopback-only VM API by default.
+
+### Security
+
+- Every `/apk-vm/*` HTTP route and the WebSocket upgrade now reject clients whose TCP peer is
+  not loopback unless `allowRemote: true` is explicitly configured. Exposing the DSH Web UI on
+  the LAN no longer automatically exposes the rooted debug API.
+- Documented the reverse-proxy/LAN threat model and `allowRemote` opt-in.
+
+## 0.3.0
+
+Production lifecycle + management layer.
+
+### Added
+
+- **Instance lifecycle:** extra VMs expose `owner` / `lastUsedAt` / `idleMs`; an idle reaper stops
+  extras after `instanceIdleMs` (default 15 min) when no panel frames, H.264 clients or Agent
+  commands are active. AVDs are kept for quick reuse. New **VM instances** panel card with
+  owner/idle and Stop/Destroy actions.
+- **Installed-app management:** panel card lists third-party packages for the active instance and
+  exposes force-stop / clear-data / uninstall (backed by the existing rooted debug routes).
+- **Agent high-level input:** `apk_vm` actions `tap`, `swipe`, `long_press`, `key`, `text` with
+  device-coordinate validation and the same per-instance routing as shell/debug actions.
+- Hermetic `spike/instances-smoke.mjs` lifecycle test + CI step.
+
+### Verified
+
+- `apk_vm key HOME`, `tap 360,1180`, `long_press 360,1180,600ms`, `text "dsh"` all succeeded on the
+  default VM via an isolated subagent.
+- `/apk-vm/instances` returns owner/idle metadata; lifecycle unit test passes.
+
+## 0.2.4
+
+Fix H.264 input coordinate mapping.
+
+### Fixed
+
+- H.264 frames are downscaled (540×960) but `input tap` expects the guest display
+  coordinate space (720×1280). The client previously sent video coordinates directly, so a tap
+  at YuAgent (device ~446,1014 → video ~334,760) landed in the Phone icon. Input mapping now
+  always uses `wm size` (swapped when rotated) while video dimensions only control the canvas
+  aspect.
+- Clicking icons in the H.264 view now hits the intended app.
+
+## 0.2.3
+
+Fix H.264 WebSocket target in the DSH desktop shell.
+
+### Fixed
+
+- The desktop shell can load the panel from a custom scheme where `location.host` is empty or
+  meaningless; the client previously fell back to a hard-coded stale localhost port, so the
+  H.264 WebSocket never connected and the panel stayed on the 1–2 fps PNG path.
+- `/apk-vm/state` now returns the server's real origin; the client derives `ws://`/`wss://` from
+  it. WebSocket close/decoder errors are also included in the client capability report.
+- Header continues to show the active transport (`H.264` vs `PNG`).
+
+## 0.2.2
+
+Stream-mode visibility / diagnostics.
+
+### Added
+
+- The header frame-rate badge now shows the transport: `FPS 59.0 · H.264` or `FPS 1.5 · PNG`,
+  so a low FPS is no longer ambiguous.
+- Client capability report (`POST /apk-vm/client-report`) records the client build, WebCodecs
+  availability and `avc1` support in `/apk-vm/state.client`; the panel shows a fallback hint
+  when H.264 is unsupported in the current WebView.
+
+## 0.2.1
+
+Per-instance H.264 for multi-agent VMs.
+
+### Added
+
+- **Every extra instance now has its own H.264/WebCodecs stream** (`lib/video-stream.js`,
+  `ScrcpyStream`): independent scrcpy server, free local port, init/AVCC/keyframe handling,
+  rotation re-init and idle stop. Extra instances are created with a 720×1280 display
+  (instead of the pixel_5 1080×2340 profile) so several GPU encoders stay stable.
+- Extra instance WebSocket endpoint: `/apk-vm/instances/<id>/ws`; panel instance selector now
+  shows H.264 canvas for extras too, with PNG fallback.
+
+### Fixed
+
+- Earlier 0.2.0 extra instances used PNG preview; larger AVD resolutions could stall the
+  emulator GPU when combined with a second scrcpy encoder. 720×1280 + per-instance stream is
+  stable.
+
+### Verified
+
+- Extra instance (emulator-5560, 720×1280): H.264 init `540×960`, **412 packets/10 s** with the
+  60Hz animation app; extra frame PNG and default VM remained responsive; destroy returns to
+  default only.
+
+## 0.2.0
+
+Multi-agent / multi-instance support.
+
+### Added
+
+- **Multiple concurrent VMs.** `InstanceManager` (`lib/instances.js`) creates isolated instances
+  with their own AVD, emulator console port, snapshot and AndroidVm state. The first Agent gets
+  the default VM; later Agents are assigned isolated instances automatically (up to
+  `maxInstances`, default 3 extra).
+- HTTP instance API: `GET/POST /apk-vm/instances`, `DELETE /apk-vm/instances/:id`, and a
+  per-instance namespace `/apk-vm/instances/:id/{state,frame,vm,input,install,upload,debug/*}`.
+- Panel instance selector + **New VM / Destroy VM** actions; extra instances use PNG preview
+  (H.264 remains on the default VM).
+- `apk_vm` Agent tool: `instance` parameter, per-Agent assignment, and
+  `list_instances` / `create_instance` / `destroy_instance` / `start` / `stop` actions.
+- `multiInstance` + `maxInstances` config; release version 0.2.0.
+
+### Verified
+
+- Two VMs run concurrently: default `emulator-5558` and extra `emulator-5560`
+  (`dsh_apk_test1`), both ready/root, extra frame PNG and root shell verified while default
+  remained ready. Extra instance cold boot ~27.5 s, later quick boot from its own snapshot.
+
+## 0.1.0
+
+First open-source release.
+
+### Added
+
+- Sidebar `apk-vm` entry + main panel, optional `dsh-better-sidebar` tab.
+- AOSP Android Emulator lifecycle with quick-boot snapshot, host GPU, hypervisor detection.
+- H.264/WebCodecs stream up to 60 fps over `/apk-vm/ws`; PNG screencap fallback.
+- Rooted guest debug surface: auto `adb root`, on-device toolkit, `/apk-vm/debug/*` HTTP API,
+  `apk_vm` Agent tool (shell/logcat/props/packages/install/push/pull/reboot/root/rotate/
+  ui_dump/record/perf/screenshot/actions).
+- One-glance Environment card + `/apk-vm/setup`: cross-platform SDK/adb/emulator/system image/
+  AVD/acceleration detection, AVD creation, opt-in system-image download.
+- APK upload by button or drag-and-drop (`/apk-vm/upload`, 500 MiB limit, ZIP magic check).
+- Multi-AVD list/switch (`/apk-vm/avds`, `/apk-vm/avd`).
+- Same-origin guard for HTTP routes and WebSocket upgrades; bounded bodies/outputs; argv-only
+  child processes.
+- Apache-2.0 LICENSE/NOTICE, CONTRIBUTING, SECURITY, GitHub Actions CI, issue/PR templates,
+  README/demo script.
+
+### Known limitations
+
+- Windows x64 is the only end-to-end verified host; macOS/Linux discovery is tested hermetically.
+- Static screens naturally show a low FPS (encoder emits on change); audio and physical-device
+  switching are roadmap items.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,130 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported privately to the project maintainers through the repository's
+**Security → Report a vulnerability** channel, or by contacting a maintainer
+through the repository's listed contact channel. All complaints will be reviewed
+and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
+
+[homepage]: https://www.contributor-covenant.org
+[Mozilla CoC]: https://github.com/mozilla/diversity

package/CONTRIBUTING.md

@@ -0,0 +1,177 @@
+# Contributing to dsh-apk-vm
+
+Thanks for improving the APK Virtual Machine plugin. This document covers the repository
+layout, the development workflow, the checks a change must pass, and the conventions this
+project follows.
+
+By participating you agree to keep discussion respectful and to license your contributions
+under the repository's [Apache-2.0](LICENSE) terms.
+
+- Bugs / feature requests: use the [issue templates](.github/ISSUE_TEMPLATE/).
+- Community behavior: follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+- Security issues: **do not** open a public issue — follow [SECURITY.md](SECURITY.md).
+- Larger design changes: open an issue first; the architecture notes live in
+  [DESIGN.md](DESIGN.md).
+
+---
+
+## Repository layout
+
+| Path | What it is |
+| --- | --- |
+| [index.js](index.js) | Host half (`apply(ctx, config)`): HTTP routes, WebSocket relay, rooted debug API, `apk_vm` Agent tool. |
+| [client.js](client.js) | Client half: a pre-built browser bundle exposing the sidebar entry, main panel, better-sidebar tab, environment card, APK upload/drop and WebCodecs canvas. |
+| [lib/android.js](lib/android.js) | `AndroidVm`: AVD lifecycle, adb commands, APK discovery/install, screenshots, input, rooted debug helpers and the extra device actions (rotate / UI dump / record / perf). |
+| [lib/scrcpy.js](lib/scrcpy.js) | `ScrcpySession`: pushes the vendored scrcpy server, H.264 demux, Annex-B→AVCC, control messages. |
+| [lib/setup.js](lib/setup.js) | Dependency-free environment detection (SDK, adb, emulator, command-line tools, system image, AVD, acceleration) plus `createAvd()` / `installSystemImage()`. |
+| [lib/ws.js](lib/ws.js) | Dependency-free RFC 6455 WebSocket server used by `/apk-vm/ws`. |
+| [lib/vendor/scrcpy-server-v5.0.1.jar](lib/vendor/scrcpy-server-v5.0.1.jar) | Vendored scrcpy 5.0.1 server JAR (Apache-2.0, unmodified — see [NOTICE](NOTICE)). |
+| [cordis.patch.yml](cordis.patch.yml) | Bundle patch that inserts the plugin row and its default config. |
+| [locale/](locale) | `en.json` / `zh.json` display metadata (`meta.title`, `meta.description`). |
+| [spike/](spike) | Test harnesses and protocol notes. Not loaded by the plugin at runtime. |
+| [DESIGN.md](DESIGN.md) | Design rationale, architecture, verified measurements and evolution notes (Chinese). |
+
+There is **no build step and no npm dependency graph**: `index.js` and `lib/**` import Node
+built-ins only, and `client.js` is plain JavaScript evaluated by the DSH Web module loader.
+Do not introduce a bundler or npm packages for the Host half; keep `client.js` dependency-free
+apart from the `react` provided by the DSH client runtime.
+
+---
+
+## Development environment
+
+- **Node.js 24+** for running the checks (`node --check`, spike suites) — matches CI.
+- A **Windows host** for end-to-end work: Android SDK (`platform-tools`, `emulator`,
+  `build-tools`), one AOSP system image (the reference image is
+  `system-images;android-34;default;x86_64`), hardware acceleration (AEHD/WHPX on Windows) and
+  an AVD created for the plugin. The panel's **Environment** card reports what is missing.
+- **No `npm install` is required.** If you add files that should ship, update `files` in
+  [package.json](package.json) — do not add runtime dependencies.
+
+A quick manual smoke test on a development machine:
+
+```bash
+# 1. install this folder as a local bundle in DSH (Plugins UI or plugin_manager tool)
+# 2. reload the DSH Web UI
+# 3. open the APK Virtual Machine sidebar entry and check the Environment card
+# 4. start the VM, install an APK (upload or path), interact, exercise the Rooted debug card
+```
+
+---
+
+## Testing
+
+### Headless suites (run in CI, no emulator needed)
+
+```bash
+node --check index.js
+node --check client.js
+for f in lib/*.js; do node --check "$f"; done
+
+node spike/ui-smoke.cjs                 # 136 sandbox assertions on the real client bundle
+node spike/ui-better-sidebar-smoke.cjs  # optional better-sidebar integration
+node spike/setup-smoke.mjs              # 30 hermetic environment/setup checks (no SDK needed)
+node spike/android/mock-device.mjs      # device critical path against a mock adb (24 checks)
+node spike/android/launch-plan.mjs      # fast-boot argv plan assertions
+```
+
+`spike/android/mock-device.mjs` parses a real APK with `aapt2`, so it needs Android SDK
+build-tools (`ANDROID_HOME` / `ANDROID_SDK_ROOT` or an SDK found on the host). The CI workflow
+uses the Android SDK preinstalled on GitHub's `ubuntu-latest` runner. `spike/setup-smoke.mjs` is
+fully hermetic: it mocks OS layouts and the `exec` boundary, so it needs neither an SDK nor an
+emulator and runs on any OS.
+
+The Host HTTP/WebSocket surface (`/apk-vm/*`, including `/apk-vm/upload` and `/apk-vm/setup`)
+is exercised in parts by the client sandbox (request shape) and the setup suite; end-to-end
+route-level tests belong to the Windows-local integration pass. When changing routes, keep the
+same-origin guard, body bounds and lifecycle cleanup intact.
+
+A few more harnesses are useful but not part of CI:
+
+```bash
+node spike/scrcpy/test-fake-device.js    # 160 assertions against a fake scrcpy-server
+node spike/android/smoke.mjs             # device methods with an injected empty adb
+```
+
+Running `spike/scrcpy/test-fake-device.js` regenerates
+`spike/scrcpy/capture-fake.h264` and `spike/scrcpy/report.json`; treat those as generated
+artifacts, not hand-edited sources.
+
+### Emulator integration tests are Windows-local only
+
+The end-to-end paths (real emulator boot, snapshot save/restore, actual H.264 stream, rooted
+debug actions, APK upload) require hardware virtualization and an AVD. GitHub-hosted runners do
+not provide nested virtualization, so these tests are **not** part of hosted CI. When a change
+touches VM lifecycle, boot plans, streaming, upload or the rooted debug surface, run the
+relevant scenario on a Windows host and state in the PR what you ran and what you observed
+(boot kind/time, FPS, logs).
+
+Do not report unmeasured numbers as results. If a benchmark could not be reproduced, say so
+instead of copying a figure from an earlier run.
+
+### UI changes
+
+- `client.js` is loaded via `window.__ModuleLoader__.load(...)` and may only require `react`;
+  keep it a single self-contained browser file.
+- Style with `--dsw-alias-*` theme tokens (no hard-coded panel/button colors); content inside the
+  phone frame (the simulated Android screen) is the intended exception.
+- Add strings to both `en` and `zh` maps in `client.js`; keep locale files for metadata in sync.
+- The DSH Web GUI is authenticated. The headless verification flow used for decoding tests may
+  not be able to load the panel itself, so validate UI behavior with `spike/ui-smoke.cjs`
+  (which renders the real component tree in a sandbox) and, when possible, a signed-in manual
+  pass. Never commit screenshots or numbers that were not actually captured.
+
+---
+
+## Coding conventions
+
+- **Never build shell command strings for host processes.** Spawn `adb`/`emulator`/`sdkmanager`/
+  `avdmanager` with `child_process.spawn(exe, argv)` and pass user data as argv entries.
+- **Bound everything.** Request bodies, APK uploads, stdout/stderr, log lines, APK scan
+  depth/results and screenshots already have limits; keep new code within them.
+- **Fail visibly.** Return structured `{ ok: false, error }` (or throw inside route handlers,
+  which the shared wrapper converts) and surface problems in the panel/log tail instead of
+  swallowing them.
+- **Same-origin only.** All HTTP/WebSocket routes live behind the DSH Web server and keep the
+  `isSameOrigin` check; do not bind additional listeners.
+- **Clean up.** Register routes/timers/tools inside `ctx.effect(...)` and return disposers;
+  stopping/restarting/unloading must stop the emulator, the scrcpy session, WebSocket clients
+  and the upload temp directory.
+- **Bounded surface.** Keep the scrcpy session shared across clients and stop it when the last
+  client disconnects (the VM keeps running).
+- **Verified claims only.** README/verification tables must match what was measured on a named
+  host. Mark unshipped features under *Roadmap* — never as available.
+
+---
+
+## Commit and pull requests
+
+- Keep PRs focused; a bug fix or a feature plus its docs/tests is the right size.
+- Write commit messages that explain the *why*; reference issues when applicable.
+- Fill out [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md), including the
+  checks you ran and any platform-specific verification.
+- Do not commit build outputs, `node_modules`, emulator logs, recordings, API keys, or paths
+  from your machine that are not needed for the feature.
+- If you change configuration keys, routes, or the `apk_vm` tool schema, update
+  [README.md](README.md) (Configuration / HTTP control plane / tool sections) in the same PR.
+- If you add a new file that must ship with the package, update `files` in `package.json`.
+
+---
+
+## Release hygiene (maintainers)
+
+1. Run the headless suites above (they mirror CI).
+2. Run the Windows-local emulator scenarios for anything touching boot/stream/upload/debug.
+3. Re-read the README "Verification" and "Performance" tables; delete or update anything that no
+   longer holds, and never fill in a number that was not measured on the stated host.
+4. Confirm [NOTICE](NOTICE) still matches the vendored third-party content.
+5. Confirm the demo placeholders in README are either replaced by real assets or still clearly
+   marked as not recorded.
+
+---
+
+## License
+
+By contributing you agree that your contributions are licensed under the Apache License,
+Version 2.0, and that you have the right to submit them. See [LICENSE](LICENSE) and
+[NOTICE](NOTICE) for the project license and third-party attribution.