@phreshos/client 0.1.28 → 0.1.30

package/README.md

@@ -1,224 +1,84 @@
 # `@phreshos/client`
 
-The Client SDK defines the contextual capabilities available inside a
-Program's client endpoint.
+The SDK for a PhreshOS Program's Client Endpoint.
 
-## Package status
+The Client SDK adapts the sandboxed desktop boundary to the shared Core domain
+model. It exposes the restricted `system` and `context` available inside a
+Client without redefining Program, Process, Endpoint, Server, or Client.
 
-This package is one component of a larger architecture that is still under
-active testing. The architecture's components will be released in stages as
-their contracts and integrations are verified.
+## Installation
 
-`@phreshos/client` is not intended to be used on its own. It requires the
-shared contracts from `@phreshos/core` and a compatible desktop boundary to
-provide its runtime environment.
+| Package manager | Command |
+| --- | --- |
+| npm | `npm install @phreshos/client` |
+| pnpm | `pnpm add @phreshos/client` |
+| Bun | `bun add @phreshos/client` |
+| Yarn | `yarn add @phreshos/client` |
 
-It uses the domain objects and shared contracts from `@phreshos/core` through
-a peer dependency. It does not redefine those objects, own server-side
-capabilities, or contain System and transport implementations.
+`@phreshos/core` is a peer dependency.
 
-Its `System` contract exposes only desktop-session capabilities: read-only
-System Appearance, mutable preferences local to this Desktop, desktop and
-pointer state, flat public uploads, and unrestricted server-side Fetch.
-`system.appearance.snapshot()` reads complete unresolved authoritative state.
-`system.desktopPreferences.snapshot()` reads the complete effective
-`{ theme, animations }` state. Its updates may set either preference explicitly
-or use `"default"` to resume following the native environment. Both capabilities
-expose ordinary live-only `change` subscriptions with no initial replay. A
-Client cannot write authoritative Appearance or discover system-wide Programs
-and Processes.
-
-`system.uploads` has the same flat contract as the Server SDK. It writes a
-value, then reads or describes it using exactly one opaque generated file key;
-it exposes no filesystem path, path segments, listing, deletion, or clearing.
-
-Desktop and pointer access are independent objects rather than events merged
-into System:
+## Context
 
 ```ts
-const desktop = await system.desktop.size()
-const stopDesktop = system.desktop.subscribe("resize", next => undefined)
+import { context } from "@phreshos/client"
 
-const position = await system.pointer.position()
-const stopPointer = system.pointer.subscribe("move", next => undefined)
-```
-
-The desktop size is the complete desktop area containing this Client,
-independent of the Client Window's layer. Client code cannot select a layer,
-and the desktop's gutter never enters an endpoint. Pointer position and
-movement both require the `pointer` permission. Reads are asynchronous
-requests; subscriptions receive only future publications and never replay a
-retained value.
+context.subscribe("changed", message => {
+  console.log(message)
+})
 
-Permission decisions belong to the current Program, not to the desktop System.
-They are available from a Program handle and flattened through `context` as the
-same canonical capability:
+context.publish("changed", { value: 1 })
 
-```ts
 const program = await context.program()
-
-await program.permission.granted("pointer")
-await context.permission.request("pointer")
-await context.permission.timeout(5_000).request("pointer")
-
-context.permission === program.permission
+const process = await context.process()
+const server = context.server
+const window = context.window
 ```
 
-`granted()` reads the effective decision without prompting. `request()` asks
-only when no known decision can answer immediately and returns `null` if its
-deadline expires. The desktop remains the internal enforcement boundary, but
-permission ownership does not alter the public shape of `system`.
+`context` belongs to the executing Client. It provides communication,
+navigation to its Program and Process, its paired Server, its Window, and
+Client-owned capabilities.
 
-The Client System exposes only direct, exact Service handles. Creating a handle
-does not read or start the Service and exposes no Service registry:
+## System
 
 ```ts
-const service = system.service({
-  program: "counter",
-  process: "main",
-  endpoint: "server"
-})
-
-await service.waitReady()
-if (await service.exists()) await service.ask("value")
+import { system } from "@phreshos/client"
 
-service.subscribe("changed", message => console.log(message))
-service.lifecycle.subscribe("stop", () => console.log("unavailable"))
+const appearance = await system.appearance.snapshot()
+const surface = await system.desktop.surface.snapshot()
+const pointer = await system.desktop.pointer.snapshot()
+const preferences = await system.desktop.preferences.snapshot()
 ```
 
-The `program` coordinate is required for a Program-local Process name. When
-`process` is an exact globally unique identity, use
-`system.service({ process, endpoint })`; that handle never retargets a
-replacement Process.
-
-A Client may traverse `Process.parent()` through any number of ancestors in
-its own Program. The first parent outside that Program is structurally hidden
-and returned as `null`; no cross-Program Process handle enters the client. If
-client code fabricates or otherwise obtains an unauthorized handle, the system
-responds exactly as it does for a nonexistent Process.
-
-Its JavaScript entry point adapts the iframe boundary to these contracts. The
-SDK owns callbacks, waits, queues, and their cleanup; the boundary owns only
-the forwarding registrations requested by the SDK.
-
-Importing the SDK and establishing the iframe's host lease inject no message
-into the endpoint. Identity, Theme, Process, Window, readiness, lifecycle, and
-application values enter only in response to an explicit request or a live
-registration made by Program code.
-
-`Context` combines communication with navigation into the executing Client's
-Process. The paired Server is explicitly named as
-`context.server`; its publishing, asking, existence, readiness, start, and stop
-operations never masquerade as properties of `context`. `context.stop()` stops
-the executing Client, while complete Process exit remains available only
-through `context.process()`. It is the canonical Process-owned handle, so
-`context.server === (await context.process()).server`.
-Endpoint `process()` navigation is asynchronous; contextual ownership is
-requested only when navigation needs it and then retained by the SDK.
-`context.name()` returns that retained Process's Program-local name, or `null`
-when its launch was unnamed.
-
-All domain handles are canonical within this iframe's JavaScript realm. Lookup,
-navigation, event payloads, and message metadata reuse the same weakly retained
-handle. A Client and its synchronous `window` capability remain stable for the
-Process lifetime; Window operations always address that Client's current live
-presentation state.
-
-`server.ask()` does not route a question before the current Server incarnation
-is ready. The Client SDK owns one deadline across readiness and the answer;
-absence or incarnation loss rejects without turning the boundary into a waiter.
-
-The package provides two contextual runtime entry points:
+The Client System exposes only capabilities allowed by the desktop boundary:
+read-only Appearance, desktop surface and pointer state, writable desktop
+preferences, uploads, Fetch, and exact Service handles. It does not expose
+system-wide Program or Process registries.
 
-```ts
-import { system, context } from "@phreshos/client"
-```
+Requests read current state. Subscriptions observe future publications and do
+not replay an initial value. Importing the SDK performs neither operation.
 
-It also re-exports the shared Core runtime classes—`Program`, `Process`,
-`Endpoint`, `Server`, and `Client`—and refines the handles returned through
-them. These are the same domain classes used by the Server SDK, so
-`instanceof Server` and `instanceof Client` retain one meaning. `Window`, like
-`ClientTraffic`, is a type-only capability owned by Client and has no
-independent `instanceof` identity.
-
-The executing Client's communication belongs directly to `context`. Its
-subscription tools receive events addressed to this Client, while `publish()`
-emits outward from this Client without choosing a destination. Existence and
-readiness belong to `context.server`; the current Client stops through
-`context.stop()`, and explicit Endpoint handles expose their own
-`endpoint.lifecycle` subscriptions.
-
-An Endpoint handle is also a selective source: `endpoint.subscribe()` follows
-destinationless events emitted by that Endpoint. Its `traffic` property remains
-reserved for directed publications, questions, and answers.
-
-Messages sent by an Endpoint in the same Program contain that real Endpoint in
-`from`. If the sender belongs to another Program, `from` is `null`; the foreign
-identity is removed by the authoritative System before the message reaches the desktop.
-The same rule applies to Client-visible traffic destinations.
-
-Client-visible Program handles can operate only within their own Program.
-They deliberately omit `install()` and `fork()`, and their `Storage` values never
-expose native filesystem paths. Every Client-side Window handle exposes the same
-authoritative, subscribable Window capability and its `window.local` physical
-representation on this desktop. Local reads and updates have no events and do
-not change Server state. `context.window` is only convenient access to the
-executing Client's canonical Window; it has no additional authority.
-
-A Client may uninstall only its own Program. The operation is an async
-generator so a declared Server cleanup command remains observable without a
-fixed answer timeout:
+## Development
 
-```ts
-for await (const chunk of program.uninstall()) {
-  console.log(chunk.stream, chunk.text)
-}
+```sh
+bun install --frozen-lockfile
+bun run verify
 ```
 
-A Program may converge its Clients on one named Process without a manual
-`find()`/`create()` race:
+`verify` checks the source, completion surface, build, and published package
+shape.
 
-```ts
-const shared = await program.process.findOrCreate({
-  name: "shared-server",
-  server: true,
-  client: false
-})
-```
-
-The authoritative Core returns the existing Process only when its normalized
-launch is equivalent; a conflicting launch rejects without changing it.
+See the [Client and Server documentation](https://github.com/PhreshOS/docs/blob/main/content/docs/sdks/client-and-server.mdx)
+for the shared model and authority boundary.
 
-When both dimensions must change, `setGeometry({ position, size })` commits
-them through one authoritative request and produces one `geometry` event.
-Calling `move()` and `resize()` sequentially or through `Promise.all()` remains
-two independent operations and can expose an intermediate state remotely.
+## Repository boundary
 
-An `under` or `over` representation may request one local system-rendered Surface:
+This repository owns the Client runtime adapter. Core owns the domain model, the
+System owns enforcement and forwarding, React owns framework adaptation, and
+React UI owns visual interpretation.
 
-```ts
-await context.window.local.surface.set({ duration: 240, easing: "ease-out", wait: true })
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow and
+[SECURITY.md](SECURITY.md) for private vulnerability reporting.
 
-await context.window.local.surface.remove({ duration: 180, easing: "ease-in" })
-```
+## License
 
-The desktop holds local state only for the lifetime of that iframe
-representation. Reloading or destroying it resets the representation from
-authoritative truth, while other desktops remain unaffected. Program code may
-synchronize desired presence through its Server and explicitly apply it
-again. `set()` and `remove()` accept only a required `VisibilityTransition`;
-Programs cannot configure the System Surface's material, opacity, or radius.
-The transition uses milliseconds and a stable named or cubic Bézier easing;
-the desktop performs the motion, honors reduced motion, and removes the Surface
-only after its exit transition completes. `wait: true` makes the request settle
-with that transition. A new iframe representation restores nothing. The
-container follows the iframe geometry while the independently rounded Surface
-neither clips nor masks Client content. The ordinary `window` layer rejects
-the capability.
-
-`program.icon()` requests the current Program's guaranteed PNG `Blob` on
-demand. The desktop derives the Program from the calling frame; no identity,
-private asset address, or filesystem path crosses from Client code.
-
-Persistent startup is deliberately absent. Only a Server endpoint may change
-whether an installed Program creates a Process when the system starts.
+Licensed under the [MIT License](LICENSE). Copyright © 2026 Zohayr SLILEH.

package/dist/desktop/desktop.d.ts

@@ -0,0 +1,13 @@
+import type { DesktopPointerSource, DesktopSurfaceSource, WritableDesktopPreferencesSource } from "@phreshos/core";
+/** Every capability owned by the Desktop containing this Client. */
+export interface SystemDesktop {
+    readonly surface: DesktopSurfaceSource;
+    readonly pointer: DesktopPointerSource;
+    readonly preferences: WritableDesktopPreferencesSource;
+}
+/** Desktop access bound to the current Client Process boundary. */
+export default class ClientDesktop implements SystemDesktop {
+    readonly surface: DesktopSurfaceSource;
+    readonly pointer: DesktopPointerSource;
+    readonly preferences: WritableDesktopPreferencesSource;
+}

package/dist/desktop/desktop.js

@@ -0,0 +1,9 @@
+import ClientPointer from "./pointer.js";
+import ClientPreferences from "./preferences.js";
+import ClientSurface from "./surface.js";
+/** Desktop access bound to the current Client Process boundary. */
+export default class ClientDesktop {
+    surface = new ClientSurface();
+    pointer = new ClientPointer();
+    preferences = new ClientPreferences();
+}

package/dist/desktop/pointer.d.ts

@@ -0,0 +1,11 @@
+import Events from "../events.js";
+/** Permission-guarded access to the Desktop pointer visible to this Client. */
+export default class ClientPointer extends Events {
+    private listeners;
+    private readonly sample;
+    constructor();
+    snapshot(): Promise<Readonly<{
+        position: import("@phreshos/core").DesktopPointerPosition | null;
+    }>>;
+    private withSampling;
+}

package/dist/desktop/pointer.js

@@ -0,0 +1,59 @@
+import Events from "../events.js";
+import wire from "../wire.js";
+/** Permission-guarded access to the Desktop pointer visible to this Client. */
+export default class ClientPointer extends Events {
+    listeners = 0;
+    sample = (event) => wire.samplePointer(event.movementX, event.movementY);
+    constructor() {
+        super((event, listener, impossible) => this.withSampling(event === "move", wire.on("host-desktop-pointer", event, value => {
+            const snapshot = createSnapshot(value);
+            if (snapshot)
+                listener(snapshot);
+        }, null, impossible)), observer => this.withSampling(true, wire.onAll("host-desktop-pointer", (event, value) => {
+            const snapshot = createSnapshot(value);
+            if (event === "move" && snapshot)
+                observer(event, snapshot);
+        })));
+    }
+    async snapshot() {
+        const answer = await wire.request(["desktopPointer"]);
+        const snapshot = createSnapshot(answer[0]);
+        if (!snapshot)
+            throw new Error("The Desktop returned an invalid pointer");
+        return snapshot;
+    }
+    withSampling(sample, stop) {
+        if (!sample)
+            return stop;
+        if (this.listeners++ === 0)
+            window.addEventListener("pointermove", this.sample);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            stop();
+            this.listeners--;
+            if (this.listeners === 0)
+                window.removeEventListener("pointermove", this.sample);
+        };
+    }
+}
+function createSnapshot(value) {
+    if (!record(value))
+        return null;
+    if (value.position === null)
+        return Object.freeze({ position: null });
+    if (!record(value.position))
+        return null;
+    const { x, y } = value.position;
+    if (!finite(x) || !finite(y))
+        return null;
+    return Object.freeze({ position: Object.freeze({ x, y }) });
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}

package/dist/desktop/preferences.d.ts

@@ -0,0 +1,11 @@
+import type { DesktopPreferencesUpdate } from "@phreshos/core";
+import Events from "../events.js";
+/** Effective preferences owned by the Desktop containing this Client. */
+export default class ClientPreferences extends Events {
+    constructor();
+    snapshot(): Promise<Readonly<{
+        theme: import("@phreshos/core").Theme;
+        animations: boolean;
+    }>>;
+    update(preferences: DesktopPreferencesUpdate): Promise<void>;
+}

package/dist/{desktop-preferences.js → desktop/preferences.js}

@@ -1,8 +1,7 @@
-import {} from "@phreshos/core";
-import Events from "./events.js";
-import wire from "./wire.js";
-/** Mutable effective preferences local to the current Desktop. */
-export default class ClientDesktopPreferences extends Events {
+import Events from "../events.js";
+import wire from "../wire.js";
+/** Effective preferences owned by the Desktop containing this Client. */
+export default class ClientPreferences extends Events {
     constructor() {
         super((event, listener, impossible) => wire.on("host-desktop-preferences", event, value => {
             listener(value);

package/dist/desktop/surface.d.ts

@@ -0,0 +1,8 @@
+import Events from "../events.js";
+/** Read-only access to the Desktop surface containing this Client. */
+export default class ClientSurface extends Events {
+    constructor();
+    snapshot(): Promise<Readonly<{
+        size: import("@phreshos/core").DesktopSize;
+    }>>;
+}

package/dist/desktop/surface.js

@@ -0,0 +1,37 @@
+import Events from "../events.js";
+import wire from "../wire.js";
+/** Read-only access to the Desktop surface containing this Client. */
+export default class ClientSurface extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("host-desktop-surface", event, value => {
+            const snapshot = createSnapshot(value);
+            if (snapshot)
+                listener(snapshot);
+        }, null, impossible), observer => wire.onAll("host-desktop-surface", (event, value) => {
+            const snapshot = createSnapshot(value);
+            if (typeof event === "string" && snapshot)
+                observer(event, snapshot);
+        }));
+    }
+    async snapshot() {
+        const answer = await wire.request(["desktopSurface"]);
+        const snapshot = createSnapshot(answer[0]);
+        if (!snapshot)
+            throw new Error("The System returned an invalid Desktop surface");
+        return snapshot;
+    }
+}
+function createSnapshot(value) {
+    if (!record(value) || !record(value.size))
+        return null;
+    const { width, height } = value.size;
+    if (!finite(width) || !finite(height))
+        return null;
+    return Object.freeze({ size: Object.freeze({ width, height }) });
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}

package/dist/main.d.ts

@@ -1,7 +1,6 @@
 export { system, type System } from "./system.js";
-export { type SystemPointer, type PointerEvents, type PointerPosition } from "./pointer.js";
-export { type DesktopEvents, type DesktopSize, type SystemDesktop } from "./desktop.js";
+export { type SystemDesktop } from "./desktop/desktop.js";
 export { context, type Context, type ContextCapture, type ContextEvents, type ContextMessage, type ContextServer } from "./context.js";
 export { ClientService, ServerService, Service, type ServiceKey, } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess, type AnswerCapture, type AnswerMessage, type AnswerSubscriber, type AskCapture, type AskMessage, type AskSubscriber, type ClientTraffic, type EndpointTraffic, type ServerTraffic, type TrafficCapture, type TrafficEvents, type TrafficMessage } from "./domain.js";
-export type { Askable, Capture, Captures, CaptureSubscriber, ClientLaunch, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointLifecycle, EndpointLifecycleEvents, EntryStat, EventMessage, EventName, EventOptions, EventSubscriber, Exit, FileStat, Launch, ServerLaunch, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, PermissionDecision, Permission, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, AnimationsPreference, DesktopPreferences, DesktopPreferencesEvents, DesktopPreferencesUpdate, SystemDesktopPreferences, ThemedValue, Theme, ThemePreference, Value, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, VisibilityTransition, Transaction } from "@phreshos/core";
+export type { Askable, Capture, Captures, CaptureSubscriber, ClientLaunch, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointLifecycle, EndpointLifecycleEvents, EntryStat, EventMessage, EventName, EventOptions, EventSubscriber, Exit, FileStat, Launch, ServerLaunch, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, PermissionDecision, Permission, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, AnimationsPreference, DesktopPreferences, DesktopPreferencesEvents, DesktopPreferencesSource, DesktopPreferencesUpdate, DesktopPointerEvents, DesktopPointerPosition, DesktopPointerSnapshot, DesktopPointerSource, DesktopSize, DesktopSurfaceEvents, DesktopSurfaceSnapshot, DesktopSurfaceSource, WritableDesktopPreferencesSource, ThemedValue, Theme, ThemePreference, Value, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, VisibilityTransition, Transaction } from "@phreshos/core";

package/dist/main.js

@@ -1,6 +1,5 @@
 export { system } from "./system.js";
-export {} from "./pointer.js";
-export {} from "./desktop.js";
+export {} from "./desktop/desktop.js";
 export { context } from "./context.js";
 export { ClientService, ServerService, Service, } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/service.d.ts

@@ -1,8 +1,8 @@
 import { type ClientService, type ServerService, type Service, type ServiceKey } from "@phreshos/core";
-export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
+export declare function prepareService<EventsMap extends object = {}, Fallback = never>(key: ServiceKey & {
     endpoint: "server";
-}): ServerService<EventsMap>;
-export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
+}): ServerService<EventsMap, Fallback>;
+export declare function prepareService<EventsMap extends object = {}, Fallback = never>(key: ServiceKey & {
     endpoint: "client";
-}): ClientService<EventsMap>;
+}): ClientService<EventsMap, Fallback>;
 export declare function prepareService(key: ServiceKey): Service;

package/dist/system.d.ts

@@ -1,21 +1,16 @@
-import type { AppearanceSource, ClientService, SystemDesktopPreferences, ServerService, ServiceKey, SystemUploads } from "@phreshos/core";
-import { type SystemPointer } from "./pointer.js";
-import { type SystemDesktop } from "./desktop.js";
+import type { AppearanceSource, ClientService, ServerService, ServiceKey, SystemUploads } from "@phreshos/core";
+import { type SystemDesktop } from "./desktop/desktop.js";
 type ServiceEndpoint = ServiceKey["endpoint"];
 type ServiceAddress<Endpoint extends ServiceEndpoint> = Omit<ServiceKey, "endpoint"> & Readonly<{
     endpoint: Endpoint;
 }>;
-type ServiceHandle<Endpoint extends ServiceEndpoint, Events extends object> = Endpoint extends "server" ? ServerService<Events> : ClientService<Events>;
+type ServiceHandle<Endpoint extends ServiceEndpoint, Events extends object, Fallback = never> = Endpoint extends "server" ? ServerService<Events, Fallback> : ClientService<Events, Fallback>;
 /** Desktop capabilities structurally available to a Client endpoint. */
 export interface System {
     /** Complete unresolved Appearance read from the System authority. */
     readonly appearance: AppearanceSource;
-    /** Mutable effective preferences local to this Desktop. */
-    readonly desktopPreferences: SystemDesktopPreferences;
-    /** Layer-independent desktop size reads and live updates. */
+    /** Capabilities owned by the Desktop containing this Client. */
     readonly desktop: SystemDesktop;
-    /** Permission-guarded desktop pointer reads and live movement. */
-    readonly pointer: SystemPointer;
     /** Flat System-owned public uploads capability. */
     readonly uploads: SystemUploads;
     /** Performs an unrestricted server-side fetch on behalf of this Client. */
@@ -23,9 +18,9 @@ export interface System {
     /** Returns a precisely typed stable handle for either service endpoint. */
     service<Endpoint extends ServiceEndpoint>(key: ServiceAddress<Endpoint>): ServiceHandle<Endpoint, {}>;
     /** Returns a typed stable handle for one exact Server service identity. */
-    service<ServiceEvents extends object>(key: ServiceAddress<"server">): ServerService<ServiceEvents>;
+    service<ServiceEvents extends object, Fallback = never>(key: ServiceAddress<"server">): ServerService<ServiceEvents, Fallback>;
     /** Returns a typed stable handle for one exact Client service identity. */
-    service<ServiceEvents extends object>(key: ServiceAddress<"client">): ClientService<ServiceEvents>;
+    service<ServiceEvents extends object, Fallback = never>(key: ServiceAddress<"client">): ClientService<ServiceEvents, Fallback>;
 }
 /** Desktop capabilities available to this Client. */
 export declare const system: System;

package/dist/system.js

@@ -1,16 +1,12 @@
 import ClientAppearance from "./appearance.js";
-import ClientDesktopPreferences from "./desktop-preferences.js";
 import wire from "./wire.js";
-import ClientPointer, {} from "./pointer.js";
-import ClientDesktop, {} from "./desktop.js";
+import ClientDesktop, {} from "./desktop/desktop.js";
 import { prepareService } from "./service.js";
 import { uploads } from "./uploads.js";
 import controlledStream from "./controlled-stream.js";
 class ClientSystem {
     appearance = new ClientAppearance();
-    desktopPreferences = new ClientDesktopPreferences();
     desktop = new ClientDesktop();
-    pointer = new ClientPointer();
     uploads = uploads;
     service(key) { return prepareService(key); }
     async fetch(input, init) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -47,13 +47,13 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.29"
+    "@phreshos/core": "^0.1.33"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.29",
+    "@phreshos/core": "^0.1.33",
     "typescript": "^6.0.3"
   }
 }

package/dist/desktop-preferences.d.ts

@@ -1,11 +0,0 @@
-import { type DesktopPreferencesUpdate } from "@phreshos/core";
-import Events from "./events.js";
-/** Mutable effective preferences local to the current Desktop. */
-export default class ClientDesktopPreferences extends Events {
-    constructor();
-    snapshot(): Promise<Readonly<{
-        theme: import("@phreshos/core").Theme;
-        animations: boolean;
-    }>>;
-    update(preferences: DesktopPreferencesUpdate): Promise<void>;
-}

package/dist/desktop.d.ts

@@ -1,25 +0,0 @@
-import type { Subscribable } from "@phreshos/core";
-import Events from "./events.js";
-/** The complete measured desktop area in CSS pixels. */
-export type DesktopSize = Readonly<{
-    width: number;
-    height: number;
-}>;
-/** Live changes to the desktop area containing this Client. */
-export type DesktopEvents = {
-    /** The desktop area resized. */
-    resize: DesktopSize;
-};
-/** Explicit desktop size reads and future resizes. */
-export interface SystemDesktop extends Subscribable<DesktopEvents, never> {
-    /** Reads the complete current desktop area in CSS pixels. */
-    size(): Promise<DesktopSize>;
-}
-/** Desktop access bound to the current Client Process boundary. */
-export default class ClientDesktop extends Events {
-    constructor();
-    size(): Promise<Readonly<{
-        width: number;
-        height: number;
-    }>>;
-}

package/dist/desktop.js

@@ -1,34 +0,0 @@
-import Events from "./events.js";
-import wire from "./wire.js";
-/** Desktop access bound to the current Client Process boundary. */
-export default class ClientDesktop extends Events {
-    constructor() {
-        super((event, listener, impossible) => wire.on("host-desktop", event, value => {
-            const size = createSize(value);
-            if (size)
-                listener(size);
-        }, null, impossible), observer => wire.onAll("host-desktop", (event, value) => {
-            const size = createSize(value);
-            if (typeof event === "string" && size)
-                observer(event, size);
-        }));
-    }
-    async size() {
-        const answer = await wire.request(["desktop"]);
-        const size = createSize(answer[0]);
-        if (!size)
-            throw new Error("The system returned an invalid desktop size");
-        return size;
-    }
-}
-function createSize(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return null;
-    const size = value;
-    if (!finite(size.width) || !finite(size.height))
-        return null;
-    return Object.freeze({ width: size.width, height: size.height });
-}
-function finite(value) {
-    return typeof value === "number" && Number.isFinite(value);
-}

package/dist/pointer.d.ts

@@ -1,35 +0,0 @@
-import type { Subscribable } from "@phreshos/core";
-import Events from "./events.js";
-/** Pointer coordinates relative to the desktop display core. */
-export type PointerPosition = Readonly<{
-    /** Horizontal coordinate in CSS pixels. */
-    x: number;
-    /** Vertical coordinate in CSS pixels. */
-    y: number;
-}>;
-/** Live pointer events visible to this Client. */
-export type PointerEvents = {
-    /** The pointer moved over the desktop display core. */
-    move: PointerPosition;
-};
-/** Permission-guarded pointer positions and future movement. */
-export interface SystemPointer extends Subscribable<PointerEvents, never> {
-    /**
-     * Reads the current desktop pointer position, or `null` before one is known.
-     * Rejects unless the `pointer` permission is currently granted.
-     */
-    position(): Promise<PointerPosition | null>;
-}
-/** Client pointer access bound to the current Process boundary. */
-export default class ClientPointer extends Events {
-    private listeners;
-    private readonly sample;
-    constructor();
-    position(): Promise<Readonly<{
-        /** Horizontal coordinate in CSS pixels. */
-        x: number;
-        /** Vertical coordinate in CSS pixels. */
-        y: number;
-    }> | null>;
-    private withSampling;
-}

package/dist/pointer.js

@@ -1,54 +0,0 @@
-import Events from "./events.js";
-import wire from "./wire.js";
-/** Client pointer access bound to the current Process boundary. */
-export default class ClientPointer extends Events {
-    listeners = 0;
-    sample = (event) => wire.samplePointer(event.movementX, event.movementY);
-    constructor() {
-        super((event, listener, impossible) => this.withSampling(event === "move", wire.on("host-pointer", event, value => {
-            const position = createPosition(value);
-            if (position)
-                listener(position);
-        }, null, impossible)), observer => this.withSampling(true, wire.onAll("host-pointer", (event, value) => {
-            const position = createPosition(value);
-            if (event === "move" && position)
-                observer(event, position);
-        })));
-    }
-    async position() {
-        const answer = await wire.request(["pointer"]);
-        if (answer[0] === null)
-            return null;
-        const position = createPosition(answer[0]);
-        if (!position)
-            throw new Error("The desktop returned an invalid Pointer position");
-        return position;
-    }
-    withSampling(sample, stop) {
-        if (!sample)
-            return stop;
-        if (this.listeners++ === 0)
-            window.addEventListener("pointermove", this.sample);
-        let active = true;
-        return () => {
-            if (!active)
-                return;
-            active = false;
-            stop();
-            this.listeners--;
-            if (this.listeners === 0)
-                window.removeEventListener("pointermove", this.sample);
-        };
-    }
-}
-function createPosition(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return null;
-    const position = value;
-    if (!finite(position.x) || !finite(position.y))
-        return null;
-    return Object.freeze({ x: position.x, y: position.y });
-}
-function finite(value) {
-    return typeof value === "number" && Number.isFinite(value);
-}