Skip to content

feat(ipodtouch4): add persistent Pocket Runtime hot updates - #397

Draft
HalfSweet wants to merge 1 commit into
mainfrom
feat/ipodtouch4-runtime
Draft

feat(ipodtouch4): add persistent Pocket Runtime hot updates#397
HalfSweet wants to merge 1 commit into
mainfrom
feat/ipodtouch4-runtime

Conversation

@HalfSweet

Copy link
Copy Markdown
Collaborator

The iPod touch 4 host currently embeds each guest into its IPA. Add a separate PocketRuntime.app that accepts .pocket updates over the shared 3DS Runtime protocol, keeping native installation separate from guest iteration.

  • Add bun ipodtouch4:runtime commands for native build/deployment, USB pairing, guest packaging, push, source watching, DevTools and status. USB uses the existing pinned SSH forwarder; LAN supports paired discovery and explicit addresses.
  • Validate packages before replacing the guest, wait for its first GLES presentation, and commit active/last-good generations. Release the old QuickJS realm, GPU resources and touch identities between guests. Recover from guest failures and damaged stored packages, with embedded Clear as the final recovery guest.
  • Keep the native listener available when a guest fails, bound QuickJS execution and socket work, and reconnect across foreground/background transitions. Share the wire codec and desktop client with 3DS while retaining compatibility entry points.
  • Add real QuickJS/C ABI integration tests and run them in the Linux/macOS native harness workflow. Document the portrait viewport, reload semantics and deployment commands.

Validation:

  • Built and signed the ARMv7 PocketRuntime.ipa against the pinned iOS 6 sysroot; built Clear's .pocket.
  • Real QuickJS integration: uploads, pairing, fragmentation, interrupted transfers, malformed/foreign packages, eval/first-frame/later-frame failures, execution timeouts, restart recovery, compiled Clear rendering and DevTools queries.
  • Legacy Apple/3DS regression tests, package/CLI tests, npm artifact checks, contract drift checks, workflow lint and git diff --check passed.
  • Full tsc --noEmit reports two existing errors in unchanged tests/companion-session.test.ts (lines 19 and 26). Full-crate rustfmt reports existing formatting differences in the GLES files and a pre-existing test in lib.rs; the added Rust module passes formatting.

Device acceptance remains outstanding: this machine lacks libimobiledevice/iproxy and the iPod's pinned SSH credentials. Host tests do not exercise UIKit, GPU presentation or device installation/USB forwarding. This version uses a 320×480 density-2 foreground Runtime; screenshots continue through the existing USB capture command.

@doodlewind doodlewind left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before merging, I’d like to tighten a few architecture boundaries. The implementation direction is good, but this PR is large enough that I don’t want the iPod runtime to become a second runtime architecture that drifts from 3DS.

My merge gate would be:

  1. Unify PKRT server semantics.
    We now have two independent PKRT server state machines: hosts/3ds/src/devserver.c and engine/runtime/dev_server.c. They already differ in protocol behavior (for example unknown frames / auth rejection behavior). Please move the common auth, framing, control, upload, timeout, and dispatch semantics into one shared implementation, leaving only platform/socket-specific integration in the hosts. Target name / discovery label should also be configuration, not hard-coded iPod-specific values in the generic runtime layer.

  2. Move target/build-plan admission policy out of quickjs-c.
    pocket_runtime_validate_plan() currently hard-codes target policy such as presentation: "native" and the allowed feature set (input.touch, text.glyphs.baked). The QuickJS executor should not own device capability policy. Please keep the validate_plan host callback, but implement the actual validation in the package/target-contract layer or generated host-side contract code, so there is one source of truth for target capabilities.

  3. Finish the generic runtime-client split.
    tools/pocket-runtime-client.ts should contain only generic PKRT client/session functionality. PICA RGB decoding, dual-screen composition, and PNG generation are 3DS-specific and should live in a 3DS-specific module. Also avoid production tooling importing tests/png.ts.

  4. Do one real-device acceptance pass before merge.
    The host harness is strong, but it does not cover UIKit/EAGL lifecycle, actual presentation, installation, or USB forwarding. Please verify repeated guest replacement and recovery on a real iPod touch 4, including first-frame failure, later-frame failure, foreground/background transitions, reconnect, and several consecutive reloads. In particular, confirm the GL teardown/recreation path does not leak or retain stale resources.

I don’t think this needs a rewrite. The guest replacement/recovery manager and .pocket admission work are solid; the main issue is making sure the new persistent runtime becomes shared infrastructure rather than an iPod-specific fork of the existing 3DS runtime behavior.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants