@phreshos/client 0.1.46 → 0.1.48

package/dist/appearance.d.ts

@@ -1,4 +1,4 @@
-import { type Appearance, type AppearanceEvents, type WritableAppearance } from "@phreshos/core";
+import { type AppearanceEvents, type AppearanceUpdate, type WritableAppearance } from "@phreshos/core";
 import Events from "./events.js";
 /** Read-only System Appearance reached through the Desktop boundary. */
 export default class ClientAppearance extends Events<AppearanceEvents, never> implements WritableAppearance {
@@ -13,5 +13,5 @@ export default class ClientAppearance extends Events<AppearanceEvents, never> im
         signInWallpaper: import("@phreshos/core").ThemedValue<string | null>;
         desktopWallpaper: import("@phreshos/core").ThemedValue<string | null>;
     }>>;
-    update(appearance: Appearance): Promise<void>;
+    update(appearance: AppearanceUpdate): Promise<void>;
 }

package/dist/context.js

@@ -1,8 +1,8 @@
 import Deadline from "./deadline.js";
-import { ClientEndpoint, ServerEndpoint, ServerTrafficHandle, TrafficHandle, endpointLifecycle, endpointEvents, process, program, visibleEndpoint, localWindow, window as windowHandle, } from "./domain.js";
+import { ClientEndpoint, ServerEndpoint, ServerTrafficHandle, TrafficHandle, endpointLifecycle, endpointEvents, process, program, visibleEndpoint, presentation, window as windowHandle, } from "./domain.js";
 import Events from "./events.js";
 import wire from "./wire.js";
-import { contextPermissions } from "./permissions.js";
+import { programPermissions } from "./permissions.js";
 class ContextServerHandle extends ServerEndpoint {
     owner;
     subscribe;
@@ -18,12 +18,12 @@ class ContextServerHandle extends ServerEndpoint {
         this.wait = events.wait;
         this.events = events.events;
     }
-    process() { return this.owner(); }
+    async process() { await this.running(); return this.owner(); }
     publish = (event, payload = undefined) => {
         wire.send("end-end", event, payload);
     };
-    async exists() {
-        const answer = await wire.request(["exists", "server"]);
+    async running() {
+        const answer = await wire.request(["running", "server"]);
         return answer[0];
     }
     async start(launch = {}) { await wire.request(["start-endpoint", undefined, "server", launch]); }
@@ -76,14 +76,14 @@ class ContextClientHandle extends ClientEndpoint {
         this.wait = events.wait;
         this.events = events.events;
     }
-    process() { return this.owner(); }
+    async process() { await this.running(); return this.owner(); }
     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"]);
+    async running() {
+        const answer = await wire.request(["running", "client"]);
         return answer[0];
     }
     async start(launch = {}) { await wire.request(["start-endpoint", undefined, "client", launch]); }
@@ -95,8 +95,8 @@ contextClient = new ContextClientHandle(owner);
 class ClientContext extends Events {
     server = contextServer;
     window = contextClient.window;
-    localWindow = localWindow(currentAddress);
-    permissions = contextPermissions();
+    presentation = presentation(currentAddress);
+    permissions = programPermissions();
     constructor() {
         super((event, listener, impossible) => wire.on("end-end", event, value => listener(contextMessage(value)), null, impossible), (listener, impossible) => wire.onAll("end-end", (event, value) => {
             if (typeof event === "string")

package/dist/domain.d.ts

@@ -1,4 +1,4 @@
-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 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 { 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 WindowPresentation, 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 type { HandleAddress };
 export type EndpointDeclarationRecord = EndpointDeclaration;
@@ -83,7 +83,7 @@ export declare function process(value: unknown, endpoints?: {
 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;
+export declare function presentation(target: WindowTarget): WindowPresentation;
 /** Resolves an Endpoint reference through the Client Endpoint's global handle registry. */
 export declare function visibleEndpoint(reference: EndpointReference | null | undefined): Endpoint | null;
 /** Runtime constructor shared by all client-visible Program handles. */

package/dist/domain.js

@@ -1,10 +1,9 @@
-import { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, parseEndpointReference, parseProcessSnapshot, parseProgramSnapshot } from "@phreshos/core";
+import { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, parseEndpointReference, parseProcessSnapshot, parseProgramDefinition, 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();
@@ -20,7 +19,6 @@ class ProgramHandle extends CoreProgram {
     logs;
     database;
     startup;
-    launch;
     permissions;
     record;
     constructor(record) {
@@ -34,7 +32,6 @@ class ProgramHandle extends CoreProgram {
         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);
         const events = scoped("program-host", record.reference, programEvent);
         this.subscribe = events.subscribe;
@@ -58,6 +55,16 @@ class ProgramHandle extends CoreProgram {
         const answer = await wire.request(["icon", this.address, size]);
         return new Blob([Uint8Array.from(answer[0])], { type: "image/png" });
     }
+    async definition() {
+        const answer = await wire.request(["program-definition", this.address]);
+        return parseProgramDefinition(answer[0]);
+    }
+    async pinned() {
+        const answer = await wire.request(["pinned", this.address, "get"]);
+        return answer[0];
+    }
+    async pin() { await wire.request(["pinned", this.address, "pin"]); }
+    async unpin() { await wire.request(["pinned", this.address, "unpin"]); }
     async agent() {
         if (!this.hasAgent)
             return null;
@@ -236,12 +243,12 @@ class ServerEndpointHandle extends CoreServerEndpoint {
         this.wait = events.wait;
         this.events = events.events;
     }
-    async process() { return this.owner; }
+    async process() { await this.running(); return this.owner; }
     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]);
+    async running() {
+        const answer = await wire.request(["running", "server", this.owner.address]);
         return answer[0];
     }
     async start(launch = {}) { await wire.request(["start-endpoint", this.owner.address, "server", launch]); }
@@ -289,12 +296,12 @@ class ClientEndpointHandle extends CoreClientEndpoint {
         this.wait = events.wait;
         this.events = events.events;
     }
-    async process() { return this.owner; }
+    async process() { await this.running(); return this.owner; }
     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]);
+    async running() {
+        const answer = await wire.request(["running", "client", this.owner.address]);
         return answer[0];
     }
     async start(launch = {}) { await wire.request(["start-endpoint", this.owner.address, "client", launch]); }
@@ -314,6 +321,8 @@ class WindowHandle extends Events {
     }
     async title() { return (await this.state()).title; }
     async header() { return (await this.state()).header; }
+    async frame() { return (await this.state()).frame; }
+    async transaction() { return (await this.state()).transaction; }
     async position() { return (await this.state()).position; }
     async size() { return (await this.state()).size; }
     async minimized() { return (await this.state()).minimized; }
@@ -325,40 +334,61 @@ class WindowHandle extends Events {
     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 changeHeader(header) { await wire.request(["changeHeader", await this.target(), header]); }
+    async setTitle(title) { await wire.request(["setTitle", await this.target(), title]); }
+    async setHeader(header) { await wire.request(["setHeader", await this.target(), header]); }
+    async setFrame(frame) { await wire.request(["setFrame", await this.target(), frame]); }
+    async setTransaction(transaction) { await wire.request(["setTransaction", await this.target(), transaction]); }
     async raise() { await wire.request(["raise", await this.target()]); }
 }
-const windowTargets = new WeakMap();
-class LocalWindowHandle {
+class WindowPresentationHandle extends Events {
     target;
     selected;
     constructor(target, selected) {
+        super((event, listener, impossible) => {
+            if (!windowEvent(event)) {
+                impossible?.(new Error(`A Window presentation has no "${event}" event`));
+                return () => undefined;
+            }
+            return wire.on("presentation", event, listener, null, impossible);
+        }, (listener, impossible) => wire.onAll("presentation", (event, ...values) => {
+            if (typeof event === "string")
+                listener(event, values[0]);
+        }, null, impossible));
         this.target = target;
         this.selected = selected;
     }
     transaction(transaction) {
-        return new LocalWindowHandle(this.target, transaction);
-    }
-    async addSurface() { await this.change("windowLocalSurfaceAdd"); }
-    async removeSurface() { await this.change("windowLocalSurfaceRemove"); }
-    async move(position) { await this.change("windowLocalMove", position); }
-    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 changeHeader(header) { await wire.request(["windowLocalHeader", await this.target(), header]); }
-    async follow(window) {
-        const target = windowTargets.get(window);
-        if (!target)
-            throw new Error("Local Window follow requires a Window from this Client SDK");
-        await wire.request(["windowLocalFollow", await this.target(), await target(), this.selected]);
-    }
-    async unfollow() { await wire.request(["windowLocalUnfollow", await this.target(), this.selected]); }
-    async raise() { await wire.request(["windowLocalRaise", await this.target()]); }
+        return new WindowPresentationHandle(this.target, { transaction, wait: false });
+    }
+    transactionAndWait(transaction) {
+        return new WindowPresentationHandle(this.target, { transaction, wait: true });
+    }
+    async title() { return await this.read("title"); }
+    async header() { return await this.read("header"); }
+    async frame() { return await this.read("frame"); }
+    async position() { return await this.read("position"); }
+    async size() { return await this.read("size"); }
+    async minimized() { return await this.read("minimized"); }
+    async maximized() { return await this.read("maximized"); }
+    async front() { return await this.read("front"); }
+    async layer() { return await this.read("layer"); }
+    async move(position) { await this.change("windowPresentationMove", position); }
+    async resize(size) { await this.change("windowPresentationResize", size); }
+    async setGeometry(geometry) { await this.change("windowPresentationGeometry", geometry); }
+    async minimize(minimized = true) { await this.change("windowPresentationMinimize", minimized); }
+    async maximize(maximized = true) { await this.change("windowPresentationMaximize", maximized); }
+    async setTitle(title) { await this.change("windowPresentationTitle", title); }
+    async setHeader(header) { await this.change("windowPresentationHeader", header); }
+    async setFrame(frame) { await this.change("windowPresentationFrame", frame); }
+    async follow() { await this.change("windowPresentationFollow"); }
+    async unfollow() { await this.change("windowPresentationUnfollow"); }
+    async raise() { await this.change("windowPresentationRaise"); }
     async change(operation, value) {
-        await wire.request([operation, await this.target(), value, this.selected]);
+        await wire.request([operation, await this.target(), value, this.selected?.transaction, this.selected?.wait === true]);
+    }
+    async read(property) {
+        const answer = await wire.request(["windowPresentationRead", await this.target(), property]);
+        return answer[0];
     }
 }
 function deferredScoped(route, target, convert) {
@@ -384,7 +414,7 @@ function deferredScoped(route, target, convert) {
     ];
 }
 function windowEvent(event) {
-    return event === "move" || event === "resize" || event === "geometry" || event === "minimize" || event === "maximize" || event === "changeTitle" || event === "changeHeader" || event === "front";
+    return event === "move" || event === "resize" || event === "minimize" || event === "maximize" || event === "changeTitle" || event === "changeHeader" || event === "changeFrame" || event === "changeTransaction" || event === "front";
 }
 function deferred(target, register, impossible) {
     let active = true;
@@ -396,8 +426,6 @@ function deferred(target, register, impossible) {
         const failure = error instanceof Error ? error : new Error(String(error));
         if (active && impossible)
             impossible(failure);
-        else if (active)
-            queueMicrotask(() => { throw failure; });
     });
     return () => {
         active = false;
@@ -426,11 +454,17 @@ export function endpointEvents(target, half) {
 }
 /** Start and stop transitions belonging directly to one permanent Endpoint. */
 export function endpointLifecycle(target, half) {
-    return new Events((event, listener, impossible) => deferred(target, subject => wire.on("process-host", endpointLifecycleEvent(event), (...values) => {
+    const resolved = () => target();
+    const viable = async () => {
+        const address = await resolved();
+        await wire.request(["running", half, address]);
+        return address;
+    };
+    return new Events((event, listener, impossible) => deferred(impossible ? viable : resolved, subject => wire.on("process-host", endpointLifecycleEvent(event), (...values) => {
         const message = unscoped(subject, values);
         if (message?.[1] === half)
             listener(undefined);
-    }, subject, impossible), impossible), (listener, impossible) => deferred(target, subject => wire.onAll("process-host", (event, ...values) => {
+    }, subject, impossible), impossible), (listener, impossible) => deferred(impossible ? viable : resolved, subject => wire.onAll("process-host", (event, ...values) => {
         if (event !== "endpointStart" && event !== "endpointStop")
             return;
         const message = unscoped(subject, values);
@@ -457,6 +491,8 @@ function programEvent(event, values) {
         return { process: process(values[0]), ...exit(values[1], values[2]) };
     if (event === "uninstall")
         return { purge: values[0] === true };
+    if (event === "pinned")
+        return values[0] === true;
     return undefined;
 }
 function processEvent(event, values) {
@@ -496,12 +532,10 @@ function endpointHandle(owner, kind, preferred) {
     return handles.obtain(`endpoint:${owner.reference}:${kind}`, () => preferred ?? (kind === "server" ? new ServerEndpointHandle(owner) : new ClientEndpointHandle(owner)));
 }
 export function window(target) {
-    const handle = new WindowHandle(target);
-    windowTargets.set(handle, target);
-    return handle;
+    return new WindowHandle(target);
 }
-export function localWindow(target) {
-    return new LocalWindowHandle(target);
+export function presentation(target) {
+    return new WindowPresentationHandle(target);
 }
 /** Resolves an Endpoint reference through the Client Endpoint's global handle registry. */
 export function visibleEndpoint(reference) {

package/dist/permissions.d.ts

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

package/dist/permissions.js

@@ -4,30 +4,19 @@ export const defaultPermissionTimeout = 120_000;
 /** 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 {
-        async get(name) { return parsePermission(name, (await operate("get", name))[0]); },
-        async all() { return parsePermissions((await operate("all"))[0]); },
-        async allows(name, permission = true) { return (await operate("allows", name, permission))[0] === true; },
-        async set(name, permission) { await operate("set", name, permission); },
-        async delete(name) { await operate("delete", name); }
-    };
-}
-/** Permission state and owner requests belonging to the current Client Endpoint. */
-export function contextPermissions() {
     const timed = (timeout) => ({
         async request(name, permission = true) {
             const identity = crypto.randomUUID();
-            const result = await wire.requestOrNull(["context-permission-request", identity, name, permission], timeout);
+            const result = await wire.requestOrNull(["program-permissions", program, "request", identity, name, permission], timeout);
             return result === null ? null : parsePermission(name, result[0]);
         }
     });
     return {
-        async get(name) {
-            return parsePermission(name, (await wire.request(["context-permission-get", name]))[0]);
-        },
-        async allows(name, permission = true) {
-            return (await wire.request(["context-permission-allows", name, permission]))[0] === true;
-        },
+        async get(name) { return parsePermission(name, (await operate("get", name))[0]); },
+        async all() { return parsePermissions((await operate("all"))[0]); },
+        async allows(name, permission = true) { return (await operate("allows", name, permission))[0] === true; },
+        async allow(name, permission = true) { await operate("allow", name, permission); },
+        async deny(name) { await operate("deny", name); },
         request: timed(defaultPermissionTimeout).request,
         timeout(milliseconds) {
             if (!Number.isFinite(milliseconds) || milliseconds < 0)

package/dist/service.d.ts

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

package/dist/service.js

@@ -1,46 +1,58 @@
-import { ClientService as CoreClientService, ServerService as CoreServerService, isServiceKey } from "@phreshos/core";
+import { ClientService as CoreClientService, ServerService as CoreServerService, isServiceAddress } from "@phreshos/core";
 import Deadline from "./deadline.js";
 import Events from "./events.js";
 import HandleRegistry from "./handle-registry.js";
 import wire from "./wire.js";
 const handles = new HandleRegistry();
 class ServiceHandle {
-    key;
+    serviceAddress;
     lifecycle;
-    constructor(key) {
-        this.key = key;
-        this.lifecycle = new Events(...serviceEvents(key, "lifecycle"));
+    constructor(serviceAddress) {
+        this.serviceAddress = serviceAddress;
+        this.lifecycle = new Events(...serviceEvents(serviceAddress, "lifecycle"));
     }
     publish(event, payload = undefined) {
-        wire.send("end-host", "service-send", this.key, event, payload);
+        wire.send("end-host", "service-send", this.serviceAddress, event, payload);
     }
-    async exists() {
-        const answer = await wire.request(["service-exists", this.key]);
+    address() { return this.serviceAddress; }
+    async available() {
+        const answer = await wire.request(["service-available", this.serviceAddress]);
         return answer[0];
     }
     async waitReady(timeout) {
-        await wire.request(["service-wait-ready", this.key, timeout], timeout);
+        await wire.request(["service-wait-ready", this.serviceAddress, timeout], timeout);
+    }
+    async programMetadata() {
+        const [value] = await wire.request(["service-program-metadata", this.serviceAddress]);
+        return parseServiceProgramMetadata(value);
+    }
+    async programIcon(size = "medium") {
+        const [value] = await wire.request(["service-program-icon", this.serviceAddress, size]);
+        return parseServiceProgramIcon(value);
     }
 }
 class ServerHandler extends CoreServerService {
-    key;
+    serviceAddress;
     subscribe;
     wait;
     events;
     lifecycle;
     service;
-    constructor(key) {
+    constructor(serviceAddress) {
         super();
-        this.key = key;
-        this.service = new ServiceHandle(key);
+        this.serviceAddress = serviceAddress;
+        this.service = new ServiceHandle(serviceAddress);
         this.lifecycle = this.service.lifecycle;
-        const events = new Events(...serviceEvents(key, "events"));
+        const events = new Events(...serviceEvents(serviceAddress, "events"));
         this.subscribe = events.subscribe;
         this.wait = events.wait;
         this.events = events.events;
     }
     publish = (event, payload = undefined) => { this.service.publish(event, payload); };
-    exists() { return this.service.exists(); }
+    address() { return this.serviceAddress; }
+    available() { return this.service.available(); }
+    programMetadata() { return this.service.programMetadata(); }
+    programIcon(size) { return this.service.programIcon(size); }
     waitReady(timeout) { return this.service.waitReady(timeout); }
     async ask(event, payload = undefined) {
         return await this.askWithin(new Deadline(), event, payload);
@@ -53,7 +65,7 @@ class ServerHandler extends CoreServerService {
         const address = `client:${identity.process}:${crypto.randomUUID()}`;
         const question = crypto.randomUUID();
         const waiting = wire.expectWithin(address, deadline);
-        wire.send("end-host", "service-ask", this.key, address, question, event, payload);
+        wire.send("end-host", "service-ask", this.serviceAddress, address, question, event, payload);
         try {
             return await waiting;
         }
@@ -63,45 +75,61 @@ class ServerHandler extends CoreServerService {
     }
 }
 class ClientHandler extends CoreClientService {
+    serviceAddress;
     subscribe;
     wait;
     events;
     lifecycle;
     service;
-    constructor(key) {
+    constructor(serviceAddress) {
         super();
-        this.service = new ServiceHandle(key);
+        this.serviceAddress = serviceAddress;
+        this.service = new ServiceHandle(serviceAddress);
         this.lifecycle = this.service.lifecycle;
-        const events = new Events(...serviceEvents(key, "events"));
+        const events = new Events(...serviceEvents(serviceAddress, "events"));
         this.subscribe = events.subscribe;
         this.wait = events.wait;
         this.events = events.events;
     }
     publish = (event, payload = undefined) => { this.service.publish(event, payload); };
-    exists() { return this.service.exists(); }
+    address() { return this.serviceAddress; }
+    available() { return this.service.available(); }
+    programMetadata() { return this.service.programMetadata(); }
+    programIcon(size) { return this.service.programIcon(size); }
     waitReady(timeout) { return this.service.waitReady(timeout); }
 }
-export function prepareService(key) {
-    if (!isServiceKey(key))
-        throw new Error("A complete service key is required");
-    const address = Object.freeze({
-        ...(key.program === undefined ? {} : { program: key.program }),
-        process: key.process
-    });
-    const identity = JSON.stringify([key.program ?? null, key.process, key.endpoint]);
-    if (key.endpoint === "server") {
-        const normalized = Object.freeze({ ...address, endpoint: "server" });
+export function prepareService(address) {
+    if (!isServiceAddress(address))
+        throw new Error("A complete Service address is required");
+    const identity = JSON.stringify([address.program, address.process, address.endpoint]);
+    if (address.endpoint === "server") {
+        const normalized = Object.freeze({ program: address.program, process: address.process, endpoint: "server" });
         return handles.obtain(`service:${identity}`, () => new ServerHandler(normalized));
     }
-    const normalized = Object.freeze({ ...address, endpoint: "client" });
+    const normalized = Object.freeze({ program: address.program, process: address.process, endpoint: "client" });
     return handles.obtain(`service:${identity}`, () => new ClientHandler(normalized));
 }
-function serviceEvents(key, scope) {
+function serviceEvents(address, scope) {
     return [
-        (event, listener, impossible) => wire.followService(key, scope, event, listener, impossible),
-        (listener, impossible) => wire.followService(key, scope, null, (event, payload) => {
+        (event, listener, impossible) => wire.followService(address, scope, event, listener, impossible),
+        (listener, impossible) => wire.followService(address, scope, null, (event, payload) => {
             if (typeof event === "string")
                 listener(event, payload);
         }, impossible)
     ];
 }
+function parseServiceProgramMetadata(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("The System returned invalid Service Program metadata");
+    const metadata = value;
+    if (typeof metadata.name !== "string" || typeof metadata.version !== "string") {
+        throw new Error("The System returned invalid Service Program metadata");
+    }
+    return Object.freeze({ name: metadata.name, version: metadata.version });
+}
+function parseServiceProgramIcon(value) {
+    if (!Array.isArray(value) || value.some(byte => typeof byte !== "number")) {
+        throw new Error("The System returned an invalid Service Program icon");
+    }
+    return new Blob([Uint8Array.from(value)], { type: "image/png" });
+}

package/dist/system.js

@@ -15,18 +15,35 @@ class ClientSystem {
     process = new SystemProcessHandle();
     connection = new SystemConnectionHandle();
     session = new SystemSessionHandle();
+    service = new SystemServiceHandle();
     uploads = uploads;
     network = network;
     execute(request) {
         return executeRequest(this, request);
     }
-    service(key) { return prepareService(key); }
     async *shell(command, options = {}) {
         const { signal, ...settings } = options;
         for await (const event of wire.stream(["shell", command, settings], undefined, signal))
             yield parseShellEvent(event);
     }
 }
+class SystemServiceHandle extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("host-service", event, (...values) => listener(prepareService(values[1])), null, impossible), observer => wire.onAll("host-service", (event, ...values) => {
+            if (typeof event === "string")
+                observer(event, prepareService(values[1]));
+        }));
+    }
+    async list() {
+        const [addresses] = await wire.request(["host-service-list"]);
+        return addresses.map(address => prepareService(address));
+    }
+    async search(name) {
+        const [addresses] = await wire.request(["host-service-search", name]);
+        return addresses.map(address => prepareService(address));
+    }
+    prepare(address) { return prepareService(address); }
+}
 class SystemProgramHandle extends Events {
     constructor() {
         super((event, listener, impossible) => wire.on("host-program", event, (...values) => listener(systemProgramEvent(event, values)), null, impossible), observer => wire.onAll("host-program", (event, ...values) => {
@@ -111,6 +128,8 @@ function systemProgramEvent(event, values) {
         return program(values[1]);
     if (event === "uninstall")
         return { program: program(values[1]), purge: values[2] === true };
+    if (event === "pinned")
+        return { program: program(values[1]), pinned: values[2] === true };
     return values[0];
 }
 function systemConnectionEvent(_event, values) {

package/dist/wire.d.ts

@@ -1,4 +1,4 @@
-import type { Cleanup, ServiceKey } from "@phreshos/core";
+import type { Cleanup, ServiceAddress } from "@phreshos/core";
 import Deadline from "./deadline.js";
 import type { HandleAddress } from "./domain.js";
 type Handler = (...values: unknown[]) => unknown;
@@ -37,7 +37,7 @@ declare class Wire {
     /** Follow destinationless events emitted by one Endpoint. */
     follow(target: HandleAddress | null, half: "server" | "client", event: string | null, handler: Handler, impossible?: Failure): Cleanup;
     /** Follow one exact service lifecycle or application event route. */
-    followService(key: ServiceKey, scope: "lifecycle" | "events", event: string | null, handler: Handler, impossible?: Failure): Cleanup;
+    followService(address: ServiceAddress, scope: "lifecycle" | "events", event: string | null, handler: Handler, impossible?: Failure): Cleanup;
     private register;
     private unregister;
     private deliver;

package/dist/wire.js

@@ -269,12 +269,12 @@ class Wire {
         });
     }
     /** Follow one exact service lifecycle or application event route. */
-    followService(key, scope, event, handler, impossible) {
+    followService(address, scope, event, handler, impossible) {
         const subscription = crypto.randomUUID();
         const stop = this.on("service-event", subscription, handler);
         if (impossible)
             this.impossible.set(subscription, impossible);
-        this.send("end-host", "service-follow", subscription, key, scope, event, impossible !== undefined);
+        this.send("end-host", "service-follow", subscription, address, scope, event, impossible !== undefined);
         return once(() => {
             stop();
             this.impossible.delete(subscription);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -46,13 +46,13 @@
     "test": "vitest run --project default"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.53"
+    "@phreshos/core": "^0.1.56"
   },
   "dependencies": {
     "@the-link/messagepack": "^0.1.0"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.53",
+    "@phreshos/core": "^0.1.56",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/dist/launch.d.ts

@@ -1,4 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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)]);
-        }
-    };
-}