Pocket Shell

Pocket Shell is a launcher for the Pocket Applets, small apps built on PocketJS that run from one set of packages on the Nintendo 3DS's touch screen and on the M5Stack Tab5's landscape panel. This repository holds the launcher and builds it, with the applets of pocket-nexus/applets (the vendor/applets submodule), for the 3DS, the Tab5 and the PSP.

Home	Hacker News	Notes

YouTube	Camera	Settings

Home on the 3DS	Notes on the 3DS

The Tab5 pictures are the device's framebuffer at its logical 640x360 (the panel shows it at 2x); the 3DS Home picture is a capture from the console, and the 3DS Notes list is a simulator render at 320x240. Each applet lays itself out by size class from one source, so the 3DS and the Tab5 install the same programs: see shells/3ds.

To use them, Pocket Hub, an app for the Mac, installs Pocket Shell on a 3DS and carries the applets. On the 3DS, which speaks Pocket Link 2, Hub writes the console's pairing onto its SD card through ftpd during that install; there is no code to scan, and the console links to the Mac by itself when Pocket Shell starts. Tap Mac on the home screen to install the applets the Mac offers. A Tab5 speaks Pocket Link 1 and pairs in Settings > Mac > Pair a Mac... by the code that a Hub speaking version 1 shows. Pocket Hub is not released yet. The Tab5 firmware is pocket-m5's, which builds this launcher from a submodule.

The shells as explorations

The repository holds three shells, and two more on an archive branch. Each explored one way of operating a small computer; what each taught is in docs/EXPLORATIONS.md.

Shell	Modality explored	Source and documentation
Pocket Shell on the 3DS and the Tab5	A touch-screen launcher with installed applets; on the 3DS, Claude's room on the top screen and L+R to talk or type; on the Tab5, a floating home ball and a keyboard	shells/3ds
Touch navigation	Full-screen gestures over sixteen mock apps on the iPod touch 4 and the Nokia E7	shells/touch
Embedded desktop	Windows, a pointer and a keyboard, with Classic 98, XP and Aqua themes in the browser preview and Pocket Studio computers	shells/desktop
The Omarchy-style 3DS shell and the iPod touch 4 remote (archived)	Tiling windows on the top screen with shoulder chords and a deck on the touch screen; a handheld that mirrors and controls a Linux desktop	branch archive/3ds-omarchy-ipod-remote

The former pocket-desktop project is the embedded desktop interface in this repository. Its application code, assets, tests, browser build scripts, browser preview and website are maintained under shells/desktop/. The import preserves its Git history. Existing installed package IDs and desktop artifact names remain stable. The archived shells are main at 78b94b2 before they were removed; they are not built or tested on main, and work on one starts from the archive branch, whose README and AGENTS.md describe that tree.

Repository layout

shells/
  3ds/       shell (the launcher), scripts, test, media; ui and lib link into vendor/applets
  touch/     src (gesture model and mock apps), scripts, test, manifest
  desktop/   src/system-ui, scripts, test, assets, docs, preview, site, manifests
scripts/     setup, desktop command dispatch, repository paths and process helpers
vendor/
  pocketjs/  shared runtime submodule
  applets/   pocket-nexus/applets: the applets, ui, kit and lib (submodule)

The three shells have separate Bun packages and TypeScript configurations. See the asset policy and review for generated outputs, source inputs and retained documentation fixtures. Application code is separate; runtime APIs come from @pocketjs/framework/*.

Development

Run commands from the repository root. Bun (the version in .bun-version, which the pinned PocketJS runs on), Rust and the wasm32-unknown-unknown Rust target are required for the complete check. Native targets have additional requirements in their shell's README.

git clone --recurse-submodules https://github.com/pocket-nexus/pocket-shell.git
cd pocket-shell
bun run setup
rustup target add wasm32-unknown-unknown
bun run check                    # types, unit and simulator tests for all shells
bun run check:3ds                # or check:touch / check:desktop

bun run desktop web              # interactive browser preview
bun run desktop build:web        # build the browser preview
bun run desktop test:web         # browser interaction smoke test
bun run desktop build:site
bun run desktop test:site

Desktop outputs are in shells/desktop/dist/. Use bun run desktop --help to list its commands, including captures and the text companion.

bun run pair --host <console-ip> # once, while ftpd runs on the 3DS: write this computer's pairing onto its card
bun run deploy                   # build Pocket Shell's .3dsx, install it over the Pocket Link and restart into it
bun run push [hn]                # rebuild and hot-push the launcher (or install Hacker News)
bun run offer                    # build the applets (3DS and Tab5 packages) and serve them from the reference Pocket Link 2 Hub
bun run tab5 [app…]              # build the launcher and the applets for the M5Stack Tab5 into dist/tab5
bun run psp                      # build the PSP EBOOT (the launcher) into dist/psp
bun run shot                     # capture both console screens
bun run 3ds                      # full console binary in dist/3ds
bun run touch guest
bun run touch deploy             # portrait gesture shell on the connected iPod

PocketJS is pinned through vendor/pocketjs, including the 3DS host's agent stage and the Pocket Link, and the applets through vendor/applets. Runtime and applet changes belong upstream; this repository selects their commits through its submodule pins.

Releases

The repository has one SemVer version: the root package.json, each shell's package.json and each app contract (pocket.app.json and the desktop's system and Studio manifests) name it, and About on the console shows it. A release is a pull request that raises it:

bun run release                  # auto: the bump the Conventional Commits since the last tag ask for
bun run release minor            # or patch / major, or an exact version such as 0.3.0-rc.1
bun run release --dry-run        # prepare the change from HEAD under .pocket-build/release/ and open nothing

The command branches release/v<version> from origin/main in a worktree of its own, raises every version and bun.lock, and opens the pull request chore(release): v<version> with the changes since the last tag. auto raises the major for a breaking change (the minor below 1.0.0), the minor for a feat, the patch otherwise.

Merging it is the release. Release 3DS (.github/workflows/release-3ds.yml) sees the root package.json's version rise on main, tags the merge commit v<version>, builds the .3dsx from it and publishes the GitHub release Pocket Shell v<version>; a version with a suffix (0.3.0-rc.1) is a prerelease. A published release is never replaced. If a run fails after tagging, run the workflow by hand with that version to publish the tag again. Releases up to v2026.11.12 were named by their date.

License

GNU GPL version 3. Root, 3DS and touch code uses GPL-3.0-or-later; imported desktop code retains GPL-3.0-only. PocketJS and third-party fonts retain their own licenses. See LICENSING.md, LICENSE and contribution rules.