@phreshos/client 0.1.27 → 0.1.29

package/README.md

@@ -1,217 +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",
-  endpoint: "server",
-  name: "state"
-})
-
-await service.waitReady()
-if (await service.enabled()) await service.ask("value")
+import { system } from "@phreshos/client"
 
-service.subscribe("changed", message => console.log(message))
-service.lifecycle.subscribe("disable", () => 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()
 ```
 
-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.
-
-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/context.d.ts

@@ -1,5 +1,5 @@
 import type { Context as CoreContext, ContextCapture as CoreContextCapture, ContextEvents as CoreContextEvents, ContextMessage as CoreContextMessage } from "@phreshos/core";
-import { Client, Server, type Endpoint, type Process, type Program, type Window } from "./domain.js";
+import { Server, type Endpoint, type Process, type Program, type Window } from "./domain.js";
 /** The executing Process's canonical Server handle. */
 export type ContextServer<Events extends object = {}> = Server<Events>;
 /** One value addressed to the current Client, with a client-visible sender. */
@@ -9,7 +9,7 @@ export type ContextEvents<Events extends object> = CoreContextEvents<Events, End
 /** Every event observable through the current Client Context. */
 export type ContextCapture<Events extends object = {}> = CoreContextCapture<Events, Endpoint | null>;
 /** Client runtime context: inbound communication, owner hierarchy, and paired Server. */
-export interface Context<Events extends object = {}> extends CoreContext<Events, Endpoint | null>, Pick<Client, "service"> {
+export interface Context<Events extends object = {}> extends CoreContext<Events, Endpoint | null> {
     /** The same Server handle exposed by the executing Process. */
     readonly server: ContextServer;
     /** Presentation capability of the executing Client. */
@@ -18,6 +18,8 @@ export interface Context<Events extends object = {}> extends CoreContext<Events,
     readonly permission: Program["permission"];
     /** Returns the Process represented by this Client. */
     process(): Promise<Process>;
+    /** Returns the executing Process's Program-local name, or `null` when unnamed. */
+    name(): Promise<string | null>;
     /** Returns the accessible parent Process, or `null` when none exists. */
     parent(): Promise<Process | null>;
     /** Returns the Program that owns this Client. */

package/dist/context.js

@@ -2,7 +2,6 @@ import Deadline from "./deadline.js";
 import { Client, Server, ServerTrafficHandle, TrafficHandle, bindEvents, endpointLifecycle, endpointEvents, process, program, visibleEndpoint, window as windowHandle } from "./domain.js";
 import Events from "./events.js";
 import wire from "./wire.js";
-import { disableCurrentService, enableCurrentService, endpointService } from "./service.js";
 import { currentProgramPermission } from "./permissions.js";
 const ServerBase = Server;
 const ClientBase = Client;
@@ -21,9 +20,9 @@ class ContextServerHandle extends ServerBase {
         const answer = await wire.request(["exists", "server"]);
         return answer[0];
     }
-    async start() { await wire.request(["start-endpoint", undefined, "server"]); }
+    async start(launch = {}) { await wire.request(["start-endpoint", undefined, "server", launch]); }
     async stop() { await wire.request(["stop-endpoint", undefined, "server"]); }
-    service() { return endpointService(null, "server"); }
+    async isService() { return (await wire.request(["is-service", "server"]))[0]; }
     async waitReady(timeout) { await wire.request(["wait-ready"], timeout); }
     async ask(event, payload = undefined) {
         return this.askWithin(undefined, event, payload);
@@ -75,9 +74,9 @@ class ContextClientHandle extends ClientBase {
         const answer = await wire.request(["exists", "client"]);
         return answer[0];
     }
-    async start(overrides = {}) { await wire.request(["start-endpoint", undefined, "client", overrides]); }
+    async start(launch = {}) { await wire.request(["start-endpoint", undefined, "client", launch]); }
     async stop() { await wire.request(["stop-endpoint", undefined, "client"]); }
-    service() { return endpointService(null, "client"); }
+    async isService() { return (await wire.request(["is-service", "client"]))[0]; }
 }
 contextClient = new ContextClientHandle(owner);
 class ClientContext extends Events {
@@ -91,6 +90,7 @@ class ClientContext extends Events {
         }, null, impossible));
     }
     process() { return owner(); }
+    async name() { return (await owner()).name; }
     async parent() {
         const answer = await wire.request(["parent"]);
         return answer[0] ? process(answer[0]) : null;
@@ -104,10 +104,8 @@ class ClientContext extends Events {
         return answer[0];
     }
     async stop() { await wire.request(["stop-current"]); }
-    service() { return endpointService(null, "client"); }
+    async isService() { return contextClient.isService(); }
     publish(event, payload = undefined) { wire.send("end-host", "emit", event, payload); }
-    async enableService(name) { await enableCurrentService(name); }
-    async disableService() { await disableCurrentService(); }
 }
 async function currentAddress() {
     const identity = await wire.identity();

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/domain.d.ts

@@ -6,6 +6,7 @@ export interface HandleAddress {
 }
 export interface EndpointDeclarationRecord {
     start: boolean;
+    service: boolean;
 }
 export interface ClientDeclarationRecord extends EndpointDeclarationRecord {
     title: string | null;
@@ -32,8 +33,11 @@ export interface ProcessRecord {
     program: ProgramRecord;
     options: Record<string, string>;
     startedAt: string | Date;
-    server: Record<string, never> | null;
-    client: Record<string, never> | null;
+    server: EndpointRecord | null;
+    client: EndpointRecord | null;
+}
+export interface EndpointRecord {
+    service: boolean;
 }
 export interface EndpointReference {
     kind: "server" | "client";

package/dist/domain.js

@@ -4,7 +4,6 @@ import Deadline from "./deadline.js";
 import HandleRegistry from "./handle-registry.js";
 import { area, sql, store } from "./storage.js";
 import wire from "./wire.js";
-import { endpointService } from "./service.js";
 import { currentProgramPermission } from "./permissions.js";
 const handles = new HandleRegistry();
 const ProgramBase = CoreProgram;
@@ -75,7 +74,8 @@ function programCommandChunk(value) {
 }
 function declaration(record) {
     return Object.freeze({
-        start: record.start
+        start: record.start,
+        service: record.service
     });
 }
 function clientDeclaration(record) {
@@ -219,9 +219,9 @@ class ServerHandle extends ServerBase {
         const answer = await wire.request(["exists", "server", this.owner.address]);
         return answer[0];
     }
-    async start() { await wire.request(["start-endpoint", this.owner.address, "server"]); }
+    async start(launch = {}) { await wire.request(["start-endpoint", this.owner.address, "server", launch]); }
     async stop() { await wire.request(["stop-endpoint", this.owner.address, "server"]); }
-    service() { return endpointService(this.owner.address, "server"); }
+    async isService() { return (await wire.request(["is-service", "server", this.owner.address]))[0]; }
     async waitReady(timeout) { await wire.request(["wait-ready", this.owner.address], timeout); }
     async ask(event, payload = undefined) {
         return this.askWithin(undefined, event, payload);
@@ -264,9 +264,9 @@ class ClientHandle extends ClientBase {
         const answer = await wire.request(["exists", "client", this.owner.address]);
         return answer[0];
     }
-    async start(overrides = {}) { await wire.request(["start-endpoint", this.owner.address, "client", overrides]); }
+    async start(launch = {}) { await wire.request(["start-endpoint", this.owner.address, "client", launch]); }
     async stop() { await wire.request(["stop-endpoint", this.owner.address, "client"]); }
-    service() { return endpointService(this.owner.address, "client"); }
+    async isService() { return (await wire.request(["is-service", "client", this.owner.address]))[0]; }
 }
 class WindowHandle extends Events {
     target;

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, type ServiceLifecycle, type ServiceLifecycleEvents } from "@phreshos/core";
+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, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointLifecycle, EndpointLifecycleEvents, EntryStat, EventMessage, EventName, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, 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 { ClientService, ServerService, Service, } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/service.d.ts

@@ -1,5 +1,4 @@
 import { type ClientService, type ServerService, type Service, type ServiceKey } from "@phreshos/core";
-import type { HandleAddress } from "./domain.js";
 export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
     endpoint: "server";
 }): ServerService<EventsMap>;
@@ -7,8 +6,3 @@ export declare function prepareService<EventsMap extends object = {}>(key: Servi
     endpoint: "client";
 }): ClientService<EventsMap>;
 export declare function prepareService(key: ServiceKey): Service;
-export declare function enableCurrentService(name: string): Promise<void>;
-export declare function disableCurrentService(): Promise<void>;
-export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "server"): Promise<ServerService<EventsMap> | null>;
-export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "client"): Promise<ClientService<EventsMap> | null>;
-export declare function endpointService(target: HandleAddress | null, endpoint: "server" | "client"): Promise<Service | null>;

package/dist/service.js

@@ -6,37 +6,43 @@ import wire from "./wire.js";
 const handles = new HandleRegistry();
 const ServerServiceBase = CoreServerService;
 const ClientServiceBase = CoreClientService;
-class ServerHandler extends ServerServiceBase {
+class ServiceHandle {
     key;
-    name;
     lifecycle;
     constructor(key) {
-        super();
         this.key = key;
-        this.name = key.name;
         this.lifecycle = new Events(...serviceEvents(key, "lifecycle"));
-        bindEvents(this, new Events(...serviceEvents(key, "events")));
     }
     publish(event, payload = undefined) {
         wire.send("end-host", "service-send", this.key, event, payload);
     }
-    async ask(event, payload = undefined) {
-        return await this.askWithin(new Deadline(), event, payload);
-    }
-    timeout(milliseconds) {
-        return {
-            ask: (event, payload = undefined) => {
-                return this.askWithin(new Deadline(milliseconds), event, payload);
-            }
-        };
-    }
-    async enabled() {
-        const answer = await wire.request(["service-enabled", this.key]);
+    async exists() {
+        const answer = await wire.request(["service-exists", this.key]);
         return answer[0];
     }
+}
+class ServerHandler extends ServerServiceBase {
+    key;
+    lifecycle;
+    service;
+    constructor(key) {
+        super();
+        this.key = key;
+        this.service = new ServiceHandle(key);
+        this.lifecycle = this.service.lifecycle;
+        bindEvents(this, new Events(...serviceEvents(key, "events")));
+    }
+    publish(event, payload = undefined) { this.service.publish(event, payload); }
+    exists() { return this.service.exists(); }
     async waitReady(timeout) {
         await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
+    async ask(event, payload = undefined) {
+        return await this.askWithin(new Deadline(), event, payload);
+    }
+    timeout(milliseconds) {
+        return { ask: (event, payload = undefined) => (this.askWithin(new Deadline(milliseconds), event, payload)) };
+    }
     async askWithin(deadline, event, payload) {
         const identity = await wire.identity();
         const address = `client:${identity.process}:${crypto.randomUUID()}`;
@@ -52,44 +58,29 @@ class ServerHandler extends ServerServiceBase {
     }
 }
 class ClientHandler extends ClientServiceBase {
-    key;
-    name;
     lifecycle;
+    service;
     constructor(key) {
         super();
-        this.key = key;
-        this.name = key.name;
-        this.lifecycle = new Events(...serviceEvents(key, "lifecycle"));
+        this.service = new ServiceHandle(key);
+        this.lifecycle = this.service.lifecycle;
         bindEvents(this, new Events(...serviceEvents(key, "events")));
     }
-    async enabled() {
-        const answer = await wire.request(["service-enabled", this.key]);
-        return answer[0];
-    }
-    async waitReady(timeout) {
-        await wire.request(["service-wait-ready", this.key, timeout], timeout);
-    }
+    publish(event, payload = undefined) { this.service.publish(event, payload); }
+    exists() { return this.service.exists(); }
 }
 export function prepareService(key) {
     if (!isServiceKey(key))
         throw new Error("A complete service key is required");
-    const normalized = Object.freeze({ program: key.program, endpoint: key.endpoint, name: key.name });
-    const identity = JSON.stringify([normalized.program, normalized.endpoint, normalized.name]);
-    return handles.obtain(`service:${identity}`, () => {
-        return normalized.endpoint === "server"
-            ? new ServerHandler(normalized)
-            : new ClientHandler(normalized);
+    const normalized = Object.freeze({
+        ...(key.program === undefined ? {} : { program: key.program }),
+        process: key.process,
+        endpoint: key.endpoint
     });
-}
-export async function enableCurrentService(name) {
-    await wire.request(["enable-service", name]);
-}
-export async function disableCurrentService() {
-    await wire.request(["disable-service"]);
-}
-export async function endpointService(target, endpoint) {
-    const answer = await wire.request(["endpoint-service", target, endpoint]);
-    return answer[0] ? prepareService(answer[0]) : null;
+    const identity = JSON.stringify([key.program ?? null, key.process, key.endpoint]);
+    return handles.obtain(`service:${identity}`, () => normalized.endpoint === "server"
+        ? new ServerHandler(normalized)
+        : new ClientHandler(normalized));
 }
 function serviceEvents(key, scope) {
     return [

package/dist/system.d.ts

@@ -1,6 +1,5 @@
-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;
@@ -10,12 +9,8 @@ type ServiceHandle<Endpoint extends ServiceEndpoint, Events extends object> = En
 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. */

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.27",
+  "version": "0.1.29",
   "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.27"
+    "@phreshos/core": "^0.1.31"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.27",
+    "@phreshos/core": "^0.1.31",
     "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);
-}