Architecture

Product policy resolves before runtime machinery starts.

Pocket Desktop defines what is installed and which package fills the System UI role. PocketJS validates that definition and produces the complete input consumed by a generic host.

Pocket System

The System manifest is a product contract. It declares identity, the app catalog, install policy, roles and lifecycle policy. It does not expose the host's supervisor implementation.

Pocket System
├─ System manifest
├─ installation state
└─ System resolver
   └─ ResolvedSystemPlan
      ├─ System UI ResolvedPackagePlan
      └─ installed app ResolvedPackagePlan[]

roles.systemUI selects the package that owns windows, taskbar, launch affordances and theme selection. applications.backgroundExecution expresses whether hidden applications continue or suspend.

Runtime ownership

The generic host creates an internal AppSupervisor from the resolved plan. One AppInstance contains a package plan, an isolated guest JavaScript Realm, a UI surface, renderer and lifecycle state.

generic host
├─ System UI AppInstance
├─ AppSupervisor
│  ├─ Hero AppInstance
│  ├─ Settings AppInstance
│  └─ Music AppInstance
└─ Compositor

The capability exposed to the System UI is ui.compositor-surfaces. A client can declare an app surface; it cannot operate or depend on the supervisor's implementation.

Composition and focus

The native compositor owns the hot path. It clips child DrawLists against their declared surfaces, preserves painter order and routes focused input. Surface placement is a compositor instruction, not an image-resource convention. Companion protocols remain outside frame scheduling.

Each visible child's DrawList and raster-resource revision participate in repaint detection. Releasing a texture that is still referenced therefore invalidates the composite even when the DrawList words did not change.

Independent lifecycles

Layer	States
Package	available → installed → removed
AppInstance	absent → running ⇄ suspended → failed / absent
JavaScript engine	JSRuntime → JSContext / Realm

Classic baseline

The checked-in 23 August 2026 baseline measures a release build on an Apple M3 Max with 128 GiB RAM. The complete runtime is 25.35 MiB, process-cold/cache-warm median launch to first paint is 179.62 ms, and settled process-tree RSS is 86.73 MiB. The maximum sampled process count is one.

See the measurement protocol and raw result context.