@phreshos/client 0.1.38 → 0.1.40

package/README.md

@@ -49,6 +49,12 @@ bun run verify
 `verify` checks the types and completions, builds the package, and validates its
 published shape.
 
+`check` performs static checks, `build` creates distributable output, and `test`
+runs Vitest assertions from `tests/`. Run `build` before testing built artifacts.
+`verify` runs `check`, `build`, and `test` in order. Operational tooling belongs
+in `scripts/`; tests and their fixtures belong in `tests/`. Verification uses
+the committed dependency graph without local package substitutions.
+
 ## Related repositories
 
 - [`@phreshos/core`](https://github.com/PhreshOS/core) is the one public import

package/dist/appearance.d.ts

@@ -4,13 +4,14 @@ import Events from "./events.js";
 export default class ClientAppearance extends Events<AppearanceEvents, never> implements WritableAppearance {
     constructor();
     snapshot(): Promise<Readonly<{
-        colors: import("@phreshos/core").AppearanceColors;
-        spacing: import("@phreshos/core").ThemedValue<number>;
-        radius: import("@phreshos/core").ThemedValue<number>;
-        shadow: import("@phreshos/core").ThemedValue<import("@phreshos/core").AppearanceShadow, import("@phreshos/core").AppearanceShadow>;
-        material: import("@phreshos/core").ThemedValue<import("@phreshos/core").AppearanceMaterial, import("@phreshos/core").AppearanceMaterial>;
-        signInWallpaper: import("@phreshos/core").ThemedValue<string | null, string | null>;
-        desktopWallpaper: import("@phreshos/core").ThemedValue<string | null, string | null>;
+        colors: import("@phreshos/core").ThemedValue<import("@phreshos/core").AppearanceColors>;
+        spacing: number;
+        radius: number;
+        shadow: import("@phreshos/core").ThemedValue<import("@phreshos/core").AppearanceShadow>;
+        material: import("@phreshos/core").ThemedValue<import("@phreshos/core").AppearanceMaterial>;
+        transaction: import("@phreshos/core").AppearanceTransaction;
+        signInWallpaper: import("@phreshos/core").ThemedValue<string | null>;
+        desktopWallpaper: import("@phreshos/core").ThemedValue<string | null>;
     }>>;
     update(appearance: Appearance): Promise<void>;
 }

package/dist/appearance.js

@@ -1,19 +1,19 @@
-import { createAppearanceSnapshot } from "@phreshos/core";
+import { parseAppearance } from "@phreshos/core";
 import Events from "./events.js";
 import wire from "./wire.js";
 /** Read-only System Appearance reached through the Desktop boundary. */
 export default class ClientAppearance extends Events {
     constructor() {
         super((event, listener, impossible) => wire.on("host-appearance", event, value => {
-            listener(createAppearanceSnapshot(value));
+            listener(parseAppearance(value));
         }, null, impossible), observer => wire.onAll("host-appearance", (event, value) => {
             if (typeof event === "string")
-                observer(event, createAppearanceSnapshot(value));
+                observer(event, parseAppearance(value));
         }));
     }
     async snapshot() {
         const [appearance] = await wire.request(["appearance"]);
-        return createAppearanceSnapshot(appearance);
+        return parseAppearance(appearance);
     }
     async update(appearance) {
         await wire.request(["updateAppearance", appearance]);

package/dist/context.js

@@ -1,21 +1,27 @@
 import Deadline from "./deadline.js";
-import { ClientEndpoint, ServerEndpoint, ServerTrafficHandle, TrafficHandle, bindEvents, endpointLifecycle, endpointEvents, process, program, visibleEndpoint, localWindow, window as windowHandle, } from "./domain.js";
+import { ClientEndpoint, ServerEndpoint, ServerTrafficHandle, TrafficHandle, endpointLifecycle, endpointEvents, process, program, visibleEndpoint, localWindow, window as windowHandle, } from "./domain.js";
 import Events from "./events.js";
 import wire from "./wire.js";
 import { contextPermissions } from "./permissions.js";
-const ServerEndpointBase = ServerEndpoint;
-const ClientEndpointBase = ClientEndpoint;
-class ContextServerHandle extends ServerEndpointBase {
+class ContextServerHandle extends ServerEndpoint {
     owner;
+    subscribe;
+    wait;
+    events;
     traffic = new ServerTrafficHandle(null, "server");
     lifecycle = endpointLifecycle(currentAddress, "server");
     constructor(owner) {
         super();
         this.owner = owner;
-        bindEvents(this, endpointEvents(null, "server"));
+        const events = endpointEvents(null, "server");
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
     process() { return this.owner(); }
-    publish(event, payload = undefined) { wire.send("end-end", event, payload); }
+    publish = (event, payload = undefined) => {
+        wire.send("end-end", event, payload);
+    };
     async exists() {
         const answer = await wire.request(["exists", "server"]);
         return answer[0];
@@ -54,22 +60,28 @@ function owner() {
     return ownerPromise;
 }
 contextServer = new ContextServerHandle(owner);
-class ContextClientHandle extends ClientEndpointBase {
+class ContextClientHandle extends ClientEndpoint {
     owner;
+    subscribe;
+    wait;
+    events;
     traffic = new TrafficHandle(null, "client");
     lifecycle = endpointLifecycle(currentAddress, "client");
     window = windowHandle(currentAddress);
     constructor(owner) {
         super();
         this.owner = owner;
-        bindEvents(this, endpointEvents(null, "client"));
+        const events = endpointEvents(null, "client");
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
     process() { return this.owner(); }
-    publish(event, payload = undefined) {
+    publish = (event, payload = undefined) => {
         void wire.identity().then(identity => {
             wire.send("end-host", "send", { identity: identity.process, reference: identity.reference }, "client", event, payload);
         });
-    }
+    };
     async exists() {
         const answer = await wire.request(["exists", "client"]);
         return answer[0];
@@ -101,9 +113,9 @@ class ClientContext extends Events {
         const answer = await wire.request(["current-program"]);
         return program(answer[0]);
     }
-    async option(name) {
-        const answer = await wire.request(["option", undefined, name]);
-        return answer[0];
+    async options(name) {
+        const process = await owner();
+        return name === undefined ? process.options() : process.options(name);
     }
     async stop() { await wire.request(["stop-current"]); }
     async isService() { return contextClient.isService(); }

package/dist/desktop/desktop.js

@@ -1,8 +1,8 @@
 import ClientPreferences from "./preferences.js";
-import ClientSurface from "./surface.js";
+import ClientViewport from "./viewport.js";
 /** Desktop access bound to the current Client Endpoint's Process boundary. */
 class ClientDesktop {
-    surface = new ClientSurface();
+    viewport = new ClientViewport();
     preferences = new ClientPreferences();
 }
 /** The Desktop environment containing this Client Endpoint. */

package/dist/desktop/viewport.d.ts

@@ -0,0 +1,9 @@
+import type { DesktopViewportEvents, DesktopViewportSource } from "@phreshos/core";
+import Events from "../events.js";
+/** Read-only access to the Desktop viewport containing this Client Endpoint. */
+export default class ClientViewport extends Events<DesktopViewportEvents, never> implements DesktopViewportSource {
+    constructor();
+    snapshot(): Promise<Readonly<{
+        size: import("@phreshos/core").DesktopSize;
+    }>>;
+}

package/dist/desktop/{surface.js → viewport.js}

@@ -1,23 +1,23 @@
 import Events from "../events.js";
 import wire from "../wire.js";
-/** Read-only access to the Desktop surface containing this Client Endpoint. */
-export default class ClientSurface extends Events {
+/** Read-only access to the Desktop viewport containing this Client Endpoint. */
+export default class ClientViewport extends Events {
     constructor() {
-        super((event, listener, impossible) => wire.on("host-desktop-surface", event, value => {
+        super((event, listener, impossible) => wire.on("host-desktop-viewport", event, value => {
             const snapshot = createSnapshot(value);
             if (snapshot)
                 listener(snapshot);
-        }, null, impossible), observer => wire.onAll("host-desktop-surface", (event, value) => {
+        }, null, impossible), observer => wire.onAll("host-desktop-viewport", (event, value) => {
             const snapshot = createSnapshot(value);
             if (typeof event === "string" && snapshot)
                 observer(event, snapshot);
         }));
     }
     async snapshot() {
-        const answer = await wire.request(["desktopSurface"]);
+        const answer = await wire.request(["desktopViewport"]);
         const snapshot = createSnapshot(answer[0]);
         if (!snapshot)
-            throw new Error("The System returned an invalid Desktop surface");
+            throw new Error("The System returned an invalid Desktop viewport");
         return snapshot;
     }
 }

package/dist/domain.d.ts

@@ -1,50 +1,12 @@
-import { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, type AnswerCapture as CoreAnswerCapture, type AnswerMessage as CoreAnswerMessage, type AnswerOutcome, type AnswerSubscriber as CoreAnswerSubscriber, type AskCapture as CoreAskCapture, type AskMessage as CoreAskMessage, type AskSubscriber as CoreAskSubscriber, type Cleanup, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type Exit, type EventOptions, type LocalWindow, type Position, type ProgramProcess as CoreProgramProcess, type ProgramProcessRunEvent as CoreProgramProcessRunEvent, type ProgramProcessRunOptions as CoreProgramProcessRunOptions, type ServerTraffic as CoreServerTraffic, type Size, type TrafficMessage as CoreTrafficMessage, type TrafficCapture as CoreTrafficCapture, type TrafficEvents as CoreTrafficEvents, type Window as CoreWindow, type WindowState } from "@phreshos/core";
+import { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, type AnswerCapture as CoreAnswerCapture, type AnswerMessage as CoreAnswerMessage, type AnswerOutcome, type AnswerSubscriber as CoreAnswerSubscriber, type AskCapture as CoreAskCapture, type AskMessage as CoreAskMessage, type AskSubscriber as CoreAskSubscriber, type Cleanup, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointReference as CoreEndpointReference, type EndpointSnapshot, type HandleAddress, type ProcessSnapshot, type ProgramSnapshot, type EndpointTraffic as CoreEndpointTraffic, type EndpointLifecycleEvents, type EndpointDeclaration, type Exit, type EventOptions, type LocalWindow, type ProgramProcess as CoreProgramProcess, type ProgramProcessRunEvent as CoreProgramProcessRunEvent, type ProgramProcessRunOptions as CoreProgramProcessRunOptions, type ServerTraffic as CoreServerTraffic, type TrafficMessage as CoreTrafficMessage, type TrafficCapture as CoreTrafficCapture, type TrafficEvents as CoreTrafficEvents, type Window as CoreWindow, type WindowState } from "@phreshos/core";
 import Events from "./events.js";
-export interface HandleAddress {
-    identity: string;
-    reference: string;
-}
-export interface EndpointDeclarationRecord {
-    start: boolean;
-    service: boolean;
-}
-export interface ClientDeclarationRecord extends EndpointDeclarationRecord {
-    title: string | null;
-    size: Size | null;
-    position: Position | null;
-    layer: ClientDeclaration["layer"];
-    minimize: boolean | null;
-    permissions: ClientDeclaration["permissions"];
-}
-export interface ProgramRecord {
-    reference: string;
-    identity: string;
-    assetId: string;
-    installed?: boolean;
-    name: string;
-    version: string | null;
-    description: string | null;
-    hasAgent: boolean;
-    server: EndpointDeclarationRecord | null;
-    client: ClientDeclarationRecord | null;
-}
-export interface ProcessRecord {
-    reference: string;
-    identity: string;
-    name: string | null;
-    program: ProgramRecord;
-    options: Record<string, string>;
-    startedAt: string | Date;
-    server: EndpointRecord | null;
-    client: EndpointRecord | null;
-}
-export interface EndpointRecord {
-    service: boolean;
-}
-export interface EndpointReference {
-    kind: "server" | "client";
-    process: ProcessRecord;
-}
+export type { HandleAddress };
+export type EndpointDeclarationRecord = EndpointDeclaration;
+export type ClientDeclarationRecord = ClientDeclaration;
+export type ProgramRecord = ProgramSnapshot;
+export type ProcessRecord = ProcessSnapshot;
+export type EndpointRecord = EndpointSnapshot;
+export type EndpointReference = CoreEndpointReference;
 export type WindowRecord = WindowState;
 export type Program = CoreProgram;
 export type ProgramProcess = CoreProgramProcess;
@@ -79,48 +41,47 @@ export type Endpoint<Events extends object = {}, Fallback = unknown> = CoreEndpo
 export type ServerEndpoint<Events extends object = {}, Fallback = unknown> = CoreServerEndpoint<Events, Fallback>;
 export type ClientEndpoint<Events extends object = {}, Fallback = unknown> = CoreClientEndpoint<Events, Fallback>;
 export type Window = CoreWindow;
-export declare class TrafficHandle extends Events {
+export declare class TrafficHandle<EventsMap extends object = {}, Fallback = unknown> extends Events<TrafficEvents<EventsMap>, TrafficMessage<Fallback>> {
     protected readonly target: HandleAddress | null;
     protected readonly kind: "server" | "client";
     constructor(target: HandleAddress | null, kind: "server" | "client");
-    subscribeAsks(subscriber: (capture: AskCapture) => unknown): Cleanup;
-    asks(options?: EventOptions): AsyncIterableIterator<Readonly<{
+    subscribeAsks<Payload = unknown>(subscriber: (capture: AskCapture<Payload>) => unknown): Cleanup;
+    asks<Payload = unknown>(options?: EventOptions): AsyncIterableIterator<Readonly<{
         event: string;
         questionId: string;
         message: Readonly<{
             to: ServerEndpoint<{}, unknown> | null;
-            payload: unknown;
+            payload: Payload;
         }>;
     }>>;
     private followAsks;
 }
-export declare class ServerTrafficHandle extends TrafficHandle {
-    subscribeAnswers(subscriber: (capture: AnswerCapture) => unknown): Cleanup;
-    answers(options?: EventOptions): AsyncIterableIterator<Readonly<{
+export declare class ServerTrafficHandle<EventsMap extends object = {}, Fallback = unknown> extends TrafficHandle<EventsMap, Fallback> {
+    subscribeAnswers<Result = unknown>(subscriber: (capture: AnswerCapture<Result>) => unknown): Cleanup;
+    answers<Result = unknown>(options?: EventOptions): AsyncIterableIterator<Readonly<{
         event: string;
         questionId: string;
         message: Readonly<{
             to: Endpoint<{}, unknown> | null;
-            outcome: AnswerOutcome<unknown>;
+            outcome: AnswerOutcome<Result>;
         }>;
     }>>;
     private followAnswers;
 }
 type WindowTarget = () => Promise<HandleAddress>;
-export declare function scoped(route: string, subject: string | null, convert: (event: string, values: unknown[]) => unknown): Events<{}, unknown>;
+export declare function scoped<Definitions extends object = {}, Fallback = unknown>(route: string, subject: string | null, convert: (event: string, values: unknown[]) => unknown): Events<Definitions, Fallback>;
 /** Destinationless events originating from one Endpoint handle. */
 export declare function endpointEvents(target: HandleAddress | null, half: "server" | "client"): Events<{}, unknown>;
 /** Start and stop transitions belonging directly to one permanent Endpoint. */
-export declare function endpointLifecycle(target: WindowTarget, half: "server" | "client"): Events<{}, unknown>;
+export declare function endpointLifecycle(target: WindowTarget, half: "server" | "client"): Events<EndpointLifecycleEvents, never>;
 export declare function exit(code: unknown, signal: unknown): Exit;
 export declare function trafficMessage(value: unknown): TrafficMessage;
-export declare function bindEvents(target: object, events: Events): void;
-export declare function program(record: ProgramRecord): Program;
-export declare function process(record: ProcessRecord, endpoints?: {
+export declare function program(value: unknown): Program;
+export declare function process(value: unknown, endpoints?: {
     server?: ServerEndpoint;
     client?: ClientEndpoint;
 }): Process;
-export declare function endpoint(reference: EndpointReference | undefined): Endpoint;
+export declare function endpoint(value: unknown): Endpoint;
 export declare function claimEndpoint(reference: string, kind: "server" | "client", endpoint: Endpoint): Endpoint<{}, unknown>;
 export declare function window(target: WindowTarget): Window;
 export declare function localWindow(target: WindowTarget): LocalWindow;
@@ -136,4 +97,3 @@ export declare const Endpoint: typeof CoreEndpoint;
 export declare const ServerEndpoint: typeof CoreServerEndpoint;
 /** Runtime constructor shared by all client-visible Client Endpoint handles. */
 export declare const ClientEndpoint: typeof CoreClientEndpoint;
-export {};

package/dist/domain.js

@@ -1,17 +1,17 @@
-import { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, parseClientPermissions } from "@phreshos/core";
+import { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, parseEndpointReference, parseProcessSnapshot, parseProgramSnapshot } from "@phreshos/core";
 import Events, { stream } from "./events.js";
 import Deadline from "./deadline.js";
 import HandleRegistry from "./handle-registry.js";
 import { area, sql, store } from "./storage.js";
 import startup from "./startup.js";
+import launch from "./launch.js";
 import { programPermissions } from "./permissions.js";
 import wire from "./wire.js";
 const handles = new HandleRegistry();
-const ProgramBase = CoreProgram;
-const ProcessBase = CoreProcess;
-const ServerEndpointBase = CoreServerEndpoint;
-const ClientEndpointBase = CoreClientEndpoint;
-class ProgramHandle extends ProgramBase {
+class ProgramHandle extends CoreProgram {
+    subscribe;
+    wait;
+    events;
     identity;
     reference;
     data;
@@ -20,6 +20,7 @@ class ProgramHandle extends ProgramBase {
     logs;
     database;
     startup;
+    launch;
     process;
     permissions;
     record;
@@ -34,21 +35,21 @@ class ProgramHandle extends ProgramBase {
         this.logs = sql("logs", this.address);
         this.database = sql("database", this.address);
         this.startup = startup(this.address);
+        this.launch = launch(this.address);
         this.permissions = programPermissions(this.address);
         this.process = new ProgramProcessHandle(this.address, record.reference);
-        bindEvents(this, scoped("program-host", record.reference, programEvent));
+        const events = scoped("program-host", record.reference, programEvent);
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
     get name() { return this.record.name; }
     get assetId() { return this.record.assetId; }
     get version() { return this.record.version; }
     get description() { return this.record.description; }
     get hasAgent() { return this.record.hasAgent; }
-    get server() {
-        return this.record.server ? declaration(this.record.server) : null;
-    }
-    get client() {
-        return this.record.client ? clientDeclaration(this.record.client) : null;
-    }
+    get server() { return this.record.server; }
+    get client() { return this.record.client; }
     get address() { return { identity: this.identity, reference: this.reference }; }
     update(record) {
         if (record.reference !== this.reference)
@@ -74,10 +75,6 @@ class ProgramHandle extends ProgramBase {
             yield programCommandChunk(value);
         }
     }
-    async fork(identity) {
-        const answer = await wire.request(["fork", this.address, identity]);
-        return program(answer[0]);
-    }
     async *uninstall(everything = false) {
         for await (const value of wire.stream(["uninstall", this.address, everything])) {
             yield programCommandChunk(value);
@@ -92,28 +89,17 @@ function programCommandChunk(value) {
     }
     return Object.freeze({ stream: chunk.stream, text: chunk.text });
 }
-function declaration(record) {
-    return Object.freeze({
-        start: record.start,
-        service: record.service
-    });
-}
-function clientDeclaration(record) {
-    return Object.freeze({
-        ...declaration(record),
-        title: record.title,
-        size: record.size,
-        position: record.position,
-        layer: record.layer,
-        minimize: record.minimize,
-        permissions: parseClientPermissions(record.permissions)
-    });
-}
 class ProgramProcessHandle {
     address;
+    subscribe;
+    wait;
+    events;
     constructor(address, reference) {
         this.address = address;
-        bindEvents(this, scoped("program-process", reference, programProcessEvent));
+        const events = scoped("program-process", reference, programProcessEvent);
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
     async list() {
         const answer = await wire.request(["program-process-list", this.address]);
@@ -165,7 +151,10 @@ function processRunEvent(value) {
 function chronological(processes) {
     return processes.sort((left, right) => left.startedAt.getTime() - right.startedAt.getTime());
 }
-class ProcessHandle extends ProcessBase {
+class ProcessHandle extends CoreProcess {
+    subscribe;
+    wait;
+    events;
     identity;
     reference;
     name;
@@ -173,7 +162,7 @@ class ProcessHandle extends ProcessBase {
     server;
     client;
     ownerProgram;
-    options;
+    launchOptions;
     constructor(record, endpoints = {}) {
         super();
         this.identity = record.identity;
@@ -181,10 +170,13 @@ class ProcessHandle extends ProcessBase {
         this.name = record.name;
         this.startedAt = new Date(record.startedAt);
         this.ownerProgram = program(record.program);
-        this.options = record.options;
+        this.launchOptions = Object.freeze({ ...record.options });
         this.server = endpointHandle(this, "server", endpoints.server);
         this.client = endpointHandle(this, "client", endpoints.client);
-        bindEvents(this, scoped("process-host", record.reference, processEvent));
+        const events = scoped("process-host", record.reference, processEvent);
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
     program() { return this.ownerProgram; }
     get address() { return { identity: this.identity, reference: this.reference }; }
@@ -192,11 +184,8 @@ class ProcessHandle extends ProcessBase {
         const answer = await wire.request(["parent", this.address]);
         return answer[0] ? process(answer[0]) : null;
     }
-    async option(name) {
-        if (name in this.options)
-            return this.options[name];
-        const answer = await wire.request(["option", this.address, name]);
-        return answer[0];
+    async options(name) {
+        return name === undefined ? this.launchOptions : this.launchOptions[name];
     }
     async exit() { await wire.request(["exit", this.address]); }
     async exited() {
@@ -245,8 +234,11 @@ export class ServerTrafficHandle extends TrafficHandle {
         }, impossible);
     }
 }
-class ServerEndpointHandle extends ServerEndpointBase {
+class ServerEndpointHandle extends CoreServerEndpoint {
     owner;
+    subscribe;
+    wait;
+    events;
     traffic;
     lifecycle;
     constructor(owner) {
@@ -254,10 +246,15 @@ class ServerEndpointHandle extends ServerEndpointBase {
         this.owner = owner;
         this.traffic = new ServerTrafficHandle(owner.address, "server");
         this.lifecycle = endpointLifecycle(() => Promise.resolve(owner.address), "server");
-        bindEvents(this, endpointEvents(owner.address, "server"));
+        const events = endpointEvents(owner.address, "server");
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
     async process() { return this.owner; }
-    publish(event, payload = undefined) { wire.send("end-host", "send", this.owner.address, "server", event, payload); }
+    publish = (event, payload = undefined) => {
+        wire.send("end-host", "send", this.owner.address, "server", event, payload);
+    };
     async exists() {
         const answer = await wire.request(["exists", "server", this.owner.address]);
         return answer[0];
@@ -288,8 +285,11 @@ class ServerEndpointHandle extends ServerEndpointBase {
         }
     }
 }
-class ClientEndpointHandle extends ClientEndpointBase {
+class ClientEndpointHandle extends CoreClientEndpoint {
     owner;
+    subscribe;
+    wait;
+    events;
     traffic;
     lifecycle;
     window;
@@ -299,10 +299,15 @@ class ClientEndpointHandle extends ClientEndpointBase {
         this.traffic = new TrafficHandle(owner.address, "client");
         this.lifecycle = endpointLifecycle(() => Promise.resolve(owner.address), "client");
         this.window = window(async () => owner.address);
-        bindEvents(this, endpointEvents(owner.address, "client"));
+        const events = endpointEvents(owner.address, "client");
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
     async process() { return this.owner; }
-    publish(event, payload = undefined) { wire.send("end-host", "send", this.owner.address, "client", event, payload); }
+    publish = (event, payload = undefined) => {
+        wire.send("end-host", "send", this.owner.address, "client", event, payload);
+    };
     async exists() {
         const answer = await wire.request(["exists", "client", this.owner.address]);
         return answer[0];
@@ -326,13 +331,14 @@ class WindowHandle extends Events {
     async position() { return (await this.state()).position; }
     async size() { return (await this.state()).size; }
     async minimized() { return (await this.state()).minimized; }
+    async maximized() { return (await this.state()).maximized; }
     async front() { return (await this.state()).front; }
     async layer() { return (await this.state()).layer; }
-    async location() { return (await this.state()).location; }
     async move(position) { await wire.request(["move", await this.target(), position]); }
     async resize(size) { await wire.request(["resize", await this.target(), size]); }
     async setGeometry(geometry) { await wire.request(["setGeometry", await this.target(), geometry]); }
     async minimize(minimized = true) { await wire.request(["minimize", await this.target(), minimized]); }
+    async maximize(maximized = true) { await wire.request(["maximize", await this.target(), maximized]); }
     async changeTitle(title) { await wire.request(["changeTitle", await this.target(), title]); }
     async raise() { await wire.request(["raise", await this.target()]); }
 }
@@ -353,6 +359,8 @@ class LocalWindowHandle {
     async resize(size) { await this.change("windowLocalResize", size); }
     async setGeometry(geometry) { await this.change("windowLocalGeometry", geometry); }
     async minimize(minimized = true) { await this.change("windowLocalMinimize", minimized); }
+    async maximize(maximized = true) { await this.change("windowLocalMaximize", maximized); }
+    async changeTitle(title) { await wire.request(["windowLocalTitle", await this.target(), title]); }
     async follow(window) {
         const target = windowTargets.get(window);
         if (!target)
@@ -388,7 +396,7 @@ function deferredScoped(route, target, convert) {
     ];
 }
 function windowEvent(event) {
-    return event === "move" || event === "resize" || event === "geometry" || event === "minimize" || event === "changeTitle" || event === "front";
+    return event === "move" || event === "resize" || event === "geometry" || event === "minimize" || event === "maximize" || event === "changeTitle" || event === "front";
 }
 function deferred(target, register, impossible) {
     let active = true;
@@ -481,24 +489,18 @@ export function trafficMessage(value) {
     const raw = value;
     return { to: visibleEndpoint(raw.to), payload: raw.payload };
 }
-export function bindEvents(target, events) {
-    Object.assign(target, {
-        subscribe: events.subscribe.bind(events),
-        waitFor: events.waitFor.bind(events),
-        events: events.events.bind(events)
-    });
-}
-export function program(record) {
+export function program(value) {
+    const record = parseProgramSnapshot(value);
     const handle = handles.obtain(`program:${record.reference}`, () => new ProgramHandle(record));
     handle.update(record);
     return handle;
 }
-export function process(record, endpoints = {}) {
+export function process(value, endpoints = {}) {
+    const record = parseProcessSnapshot(value);
     return handles.obtain(`process:${record.reference}`, () => new ProcessHandle(record, endpoints));
 }
-export function endpoint(reference) {
-    if (!reference)
-        throw new Error("The boundary returned an invalid Endpoint reference");
+export function endpoint(value) {
+    const reference = parseEndpointReference(value);
     const owner = process(reference.process);
     return reference.kind === "server" ? owner.server : owner.client;
 }

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-import type { Cleanup, EventOptions, Subscribable } from "@phreshos/core";
+import { subscribableDefinition, type Cleanup, type EventOptions, type Subscribable, type SubscribableDefinition } from "@phreshos/core";
 export declare const defaultTimeout = 10000;
 type Failure = (error: Error) => void;
 type Listener = (message: unknown) => unknown;
@@ -8,9 +8,10 @@ type Register<Message> = (listener: (message: Message) => unknown, impossible?:
 export default class Events<Vocabulary extends object = {}, Fallback = unknown> implements Subscribable<Vocabulary, Fallback> {
     private readonly listen;
     private readonly listenAll;
+    readonly [subscribableDefinition]?: SubscribableDefinition<Vocabulary, Fallback>;
     constructor(listen: (event: string, listener: Listener, impossible?: Failure) => Cleanup, listenAll: (listener: EveryListener, impossible?: Failure) => Cleanup);
     readonly subscribe: Subscribable<Vocabulary, Fallback>["subscribe"];
-    readonly waitFor: Subscribable<Vocabulary, Fallback>["waitFor"];
+    readonly wait: Subscribable<Vocabulary, Fallback>["wait"];
     readonly events: Subscribable<Vocabulary, Fallback>["events"];
 }
 /** Converts one persistent registration into a bounded asynchronous iterator. */

package/dist/events.js

@@ -1,3 +1,4 @@
+import { subscribableDefinition } from "@phreshos/core";
 export const defaultTimeout = 10_000;
 /** SDK-owned waits, queues and callbacks over boundary forwarding state. */
 export default class Events {
@@ -12,7 +13,7 @@ export default class Events {
             return this.listen(eventOrSubscriber, subscriber);
         return this.listenAll((event, message) => eventOrSubscriber({ event, message }));
     });
-    waitFor = ((event, timeout = defaultTimeout) => {
+    wait = ((event, timeout = defaultTimeout) => {
         return new Promise((resolve, reject) => {
             let settled = false;
             let stop = () => undefined;

package/dist/launch.d.ts

@@ -0,0 +1,4 @@
+import { type ProgramLaunch } from "@phreshos/core";
+import type { HandleAddress } from "./domain.js";
+/** Bind saved launch operations to one Program handle. */
+export default function launch(program: HandleAddress): ProgramLaunch;

package/dist/launch.js

@@ -0,0 +1,14 @@
+import { parseLaunch } from "@phreshos/core";
+import wire from "./wire.js";
+/** Bind saved launch operations to one Program handle. */
+export default function launch(program) {
+    return {
+        async get() {
+            const [value] = await wire.request(["launch", program, "get"]);
+            return value === null ? null : parseLaunch(value);
+        },
+        async set(value) {
+            await wire.request(["launch", program, "set", parseLaunch(value)]);
+        }
+    };
+}

package/dist/network.d.ts

@@ -0,0 +1,7 @@
+import type { Network } from "@phreshos/core";
+declare class ClientNetwork implements Network {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    websocket(url: string | URL, protocols?: string | string[]): Promise<WebSocket>;
+}
+declare const _default: ClientNetwork;
+export default _default;

package/dist/network.js

@@ -0,0 +1,79 @@
+import wire from "./wire.js";
+import controlledStream from "./controlled-stream.js";
+import websocket from "./websocket.js";
+class ClientNetwork {
+    async fetch(input, init) {
+        const request = new Request(input, {
+            ...init,
+            ...init?.body instanceof ReadableStream ? { duplex: "half" } : {}
+        });
+        const body = request.body;
+        const control = new MessageChannel();
+        const abort = () => control.port1.postMessage("abort");
+        if (request.signal.aborted) {
+            control.port1.close();
+            control.port2.close();
+            throw request.signal.reason;
+        }
+        request.signal.addEventListener("abort", abort, { once: true });
+        const description = {
+            body: body !== null,
+            cache: request.cache,
+            credentials: request.credentials,
+            headers: requestHeaders(request.headers, init?.headers),
+            integrity: request.integrity,
+            keepalive: request.keepalive,
+            method: request.method,
+            mode: request.mode,
+            redirect: request.redirect,
+            referrer: request.referrer,
+            referrerPolicy: request.referrerPolicy,
+            url: request.url
+        };
+        let result;
+        try {
+            const answer = await wire.request(["fetch", description, body, control.port2], undefined, body ? [body, control.port2] : [control.port2]);
+            result = answer[0];
+        }
+        catch (error) {
+            abort();
+            closeControl(request.signal, control.port1, abort);
+            throw request.signal.aborted ? request.signal.reason : error;
+        }
+        const responseBody = result.body
+            ? controlledStream(result.body, abort, () => closeControl(request.signal, control.port1, abort))
+            : null;
+        if (!responseBody)
+            closeControl(request.signal, control.port1, abort);
+        const response = new Response(responseBody, {
+            headers: result.headers,
+            status: result.status,
+            statusText: result.statusText
+        });
+        Object.defineProperties(response, {
+            redirected: { configurable: true, enumerable: true, value: result.redirected },
+            type: { configurable: true, enumerable: true, value: result.type },
+            url: { configurable: true, enumerable: true, value: result.url }
+        });
+        return response;
+    }
+    websocket(url, protocols) {
+        return websocket(url, protocols);
+    }
+}
+function requestHeaders(normalized, supplied) {
+    if (!supplied)
+        return [...normalized.entries()];
+    const explicit = supplied instanceof Headers
+        ? [...supplied.entries()]
+        : Array.isArray(supplied)
+            ? supplied.map(([name, value]) => [name, value])
+            : Object.entries(supplied);
+    const names = new Set(explicit.map(([name]) => name.toLowerCase()));
+    return [...normalized.entries()].filter(([name]) => !names.has(name.toLowerCase())).concat(explicit);
+}
+function closeControl(signal, port, abort) {
+    signal.removeEventListener("abort", abort);
+    port.close();
+}
+export default new ClientNetwork();

package/dist/permissions.d.ts

@@ -1,7 +1,7 @@
 import type { ContextPermissions, ProgramPermissions } from "@phreshos/core";
 import type { HandleAddress } from "./domain.js";
 export declare const defaultPermissionTimeout = 120000;
-/** Bind authoritative stored grants to one exact Program handle. */
+/** Bind authoritative permission state to one exact Program handle. */
 export declare function programPermissions(program: HandleAddress): ProgramPermissions;
-/** Stored grants and owner requests belonging to the current Client Endpoint. */
+/** Permission state and owner requests belonging to the current Client Endpoint. */
 export declare function contextPermissions(): ContextPermissions;

package/dist/permissions.js

@@ -1,7 +1,7 @@
 import { parsePermission, parsePermissions } from "@phreshos/core";
 import wire from "./wire.js";
 export const defaultPermissionTimeout = 120_000;
-/** Bind authoritative stored grants to one exact Program handle. */
+/** Bind authoritative permission state to one exact Program handle. */
 export function programPermissions(program) {
     const operate = (operation, name, permission) => (wire.request(["program-permissions", program, operation, name, permission]));
     return {
@@ -12,7 +12,7 @@ export function programPermissions(program) {
         async delete(name) { await operate("delete", name); }
     };
 }
-/** Stored grants and owner requests belonging to the current Client Endpoint. */
+/** Permission state and owner requests belonging to the current Client Endpoint. */
 export function contextPermissions() {
     const timed = (timeout) => ({
         async request(name, permission = true) {

package/dist/service.js

@@ -4,8 +4,6 @@ import Events from "./events.js";
 import HandleRegistry from "./handle-registry.js";
 import wire from "./wire.js";
 const handles = new HandleRegistry();
-const ServerServiceBase = CoreServerService;
-const ClientServiceBase = CoreClientService;
 class ServiceHandle {
     key;
     lifecycle;
@@ -24,8 +22,11 @@ class ServiceHandle {
         await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
 }
-class ServerHandler extends ServerServiceBase {
+class ServerHandler extends CoreServerService {
     key;
+    subscribe;
+    wait;
+    events;
     lifecycle;
     service;
     constructor(key) {
@@ -33,9 +34,12 @@ class ServerHandler extends ServerServiceBase {
         this.key = key;
         this.service = new ServiceHandle(key);
         this.lifecycle = this.service.lifecycle;
-        bindEvents(this, new Events(...serviceEvents(key, "events")));
+        const events = new Events(...serviceEvents(key, "events"));
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
-    publish(event, payload = undefined) { this.service.publish(event, payload); }
+    publish = (event, payload = undefined) => { this.service.publish(event, payload); };
     exists() { return this.service.exists(); }
     waitReady(timeout) { return this.service.waitReady(timeout); }
     async ask(event, payload = undefined) {
@@ -58,31 +62,39 @@ class ServerHandler extends ServerServiceBase {
         }
     }
 }
-class ClientHandler extends ClientServiceBase {
+class ClientHandler extends CoreClientService {
+    subscribe;
+    wait;
+    events;
     lifecycle;
     service;
     constructor(key) {
         super();
         this.service = new ServiceHandle(key);
         this.lifecycle = this.service.lifecycle;
-        bindEvents(this, new Events(...serviceEvents(key, "events")));
+        const events = new Events(...serviceEvents(key, "events"));
+        this.subscribe = events.subscribe;
+        this.wait = events.wait;
+        this.events = events.events;
     }
-    publish(event, payload = undefined) { this.service.publish(event, payload); }
+    publish = (event, payload = undefined) => { this.service.publish(event, payload); };
     exists() { return this.service.exists(); }
     waitReady(timeout) { return this.service.waitReady(timeout); }
 }
 export function prepareService(key) {
     if (!isServiceKey(key))
         throw new Error("A complete service key is required");
-    const normalized = Object.freeze({
+    const address = Object.freeze({
         ...(key.program === undefined ? {} : { program: key.program }),
-        process: key.process,
-        endpoint: key.endpoint
+        process: key.process
     });
     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));
+    if (key.endpoint === "server") {
+        const normalized = Object.freeze({ ...address, endpoint: "server" });
+        return handles.obtain(`service:${identity}`, () => new ServerHandler(normalized));
+    }
+    const normalized = Object.freeze({ ...address, endpoint: "client" });
+    return handles.obtain(`service:${identity}`, () => new ClientHandler(normalized));
 }
 function serviceEvents(key, scope) {
     return [
@@ -93,10 +105,3 @@ function serviceEvents(key, scope) {
         }, impossible)
     ];
 }
-function bindEvents(target, events) {
-    Object.assign(target, {
-        subscribe: events.subscribe.bind(events),
-        waitFor: events.waitFor.bind(events),
-        events: events.events.bind(events)
-    });
-}

package/dist/system.js

@@ -3,76 +3,18 @@ import ClientAppearance from "./appearance.js";
 import wire from "./wire.js";
 import { prepareService } from "./service.js";
 import { uploads } from "./uploads.js";
-import controlledStream from "./controlled-stream.js";
 import Events from "./events.js";
 import { exit, process, program } from "./domain.js";
 import { systemStorage } from "./storage.js";
-import websocket from "./websocket.js";
+import network from "./network.js";
 class ClientSystem {
     storage = systemStorage();
     appearance = new ClientAppearance();
     program = new SystemProgramHandle();
     process = new SystemProcessHandle();
     uploads = uploads;
+    network = network;
     service(key) { return prepareService(key); }
-    async fetch(input, init) {
-        const request = new Request(input, {
-            ...init,
-            ...init?.body instanceof ReadableStream ? { duplex: "half" } : {}
-        });
-        const body = request.body;
-        const control = new MessageChannel();
-        const abort = () => control.port1.postMessage("abort");
-        if (request.signal.aborted) {
-            control.port1.close();
-            control.port2.close();
-            throw request.signal.reason;
-        }
-        request.signal.addEventListener("abort", abort, { once: true });
-        const description = {
-            body: body !== null,
-            cache: request.cache,
-            credentials: request.credentials,
-            headers: requestHeaders(request.headers, init?.headers),
-            integrity: request.integrity,
-            keepalive: request.keepalive,
-            method: request.method,
-            mode: request.mode,
-            redirect: request.redirect,
-            referrer: request.referrer,
-            referrerPolicy: request.referrerPolicy,
-            url: request.url
-        };
-        let result;
-        try {
-            const answer = await wire.request(["fetch", description, body, control.port2], undefined, body ? [body, control.port2] : [control.port2]);
-            result = answer[0];
-        }
-        catch (error) {
-            abort();
-            closeControl(request.signal, control.port1, abort);
-            throw request.signal.aborted ? request.signal.reason : error;
-        }
-        const responseBody = result.body
-            ? controlledStream(result.body, abort, () => closeControl(request.signal, control.port1, abort))
-            : null;
-        if (!responseBody)
-            closeControl(request.signal, control.port1, abort);
-        const response = new Response(responseBody, {
-            headers: result.headers,
-            status: result.status,
-            statusText: result.statusText
-        });
-        Object.defineProperties(response, {
-            redirected: { configurable: true, enumerable: true, value: result.redirected },
-            type: { configurable: true, enumerable: true, value: result.type },
-            url: { configurable: true, enumerable: true, value: result.url }
-        });
-        return response;
-    }
-    websocket(url, protocols) {
-        return websocket(url, protocols);
-    }
     async *shell(command, options = {}) {
         const { signal, ...settings } = options;
         for await (const event of wire.stream(["shell", command, settings], undefined, signal))
@@ -133,20 +75,5 @@ function systemProgramEvent(event, values) {
         return { program: program(values[1]), everything: values[2] === true };
     return values[0];
 }
-function requestHeaders(normalized, supplied) {
-    if (!supplied)
-        return [...normalized.entries()];
-    const explicit = supplied instanceof Headers
-        ? [...supplied.entries()]
-        : Array.isArray(supplied)
-            ? supplied.map(([name, value]) => [name, value])
-            : Object.entries(supplied);
-    const names = new Set(explicit.map(([name]) => name.toLowerCase()));
-    return [...normalized.entries()].filter(([name]) => !names.has(name.toLowerCase())).concat(explicit);
-}
-function closeControl(signal, port, abort) {
-    signal.removeEventListener("abort", abort);
-    port.close();
-}
 /** The global System represented through this Client runtime. */
 export const system = new ClientSystem();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -41,19 +41,19 @@
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "build": "node --run clean && tsc --noEmit false --outDir dist --rootDir source",
-    "verify:completions": "node scripts/verify-completions.mjs",
-    "verify:package": "node scripts/verify-package.mjs",
-    "verify": "node --run check && node --run verify:completions && node --run build && node --run verify:package",
-    "prepack": "node --run build"
+    "verify": "node --run check && node --run build && node --run test",
+    "prepack": "node --run build",
+    "test": "vitest run --project default"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.42"
+    "@phreshos/core": "^0.1.45"
   },
   "dependencies": {
     "@the-link/messagepack": "^0.1.0"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.42",
-    "typescript": "^6.0.3"
+    "@phreshos/core": "^0.1.45",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   }
 }

package/dist/desktop/surface.d.ts

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