@phreshos/client 0.1.13 → 0.1.14

package/README.md

@@ -63,11 +63,11 @@ 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 `host`.
 
-The Client Host exposes service preparation as its only service-registry
-capability. Preparing a handle does not read or start the service:
+The Client Host exposes only direct, exact Service handles. Creating a handle
+does not read or start the Service and exposes no Service registry:
 
 ```ts
-const service = host.service.prepare({
+const service = host.service({
   program: "counter",
   endpoint: "server",
   name: "state"
@@ -147,6 +147,21 @@ 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. `current.window` is only convenient access to the
 executing Client's canonical Window; it has no additional authority.
+
+A Program may converge its Clients on one named Process without a manual
+`find()`/`create()` race:
+
+```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.
+
 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

package/dist/channel.d.ts

@@ -1,4 +1,4 @@
-import type { Channel as CoreChannel, ChannelCapture as CoreChannelCapture, ChannelEvents as CoreChannelEvents, ChannelMessage as CoreChannelMessage, ServiceDefinition } from "@phreshos/core";
+import type { Channel as CoreChannel, ChannelCapture as CoreChannelCapture, ChannelEvents as CoreChannelEvents, ChannelMessage as CoreChannelMessage } from "@phreshos/core";
 import { type Endpoint } from "./domain.js";
 /** One value addressed to the current Client, with a client-visible sender. */
 export type ChannelMessage<Payload = unknown> = CoreChannelMessage<Payload, Endpoint | null>;
@@ -7,6 +7,6 @@ export type ChannelEvents<Events extends object> = CoreChannelEvents<Events, End
 /** Every event observable through the current Client's Channel. */
 export type ChannelCapture<Events extends object = {}> = CoreChannelCapture<Events, Endpoint | null>;
 /** Events explicitly accepted by the current Client. */
-export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint | null, ServiceDefinition> {
+export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint | null> {
 }
 export declare const channel: Channel;

package/dist/channel.js

@@ -12,7 +12,7 @@ class ClientChannel extends Events {
     publish(event, payload = undefined) {
         wire.send("end-host", "emit", event, payload);
     }
-    async enableService(definition) { await enableCurrentService(definition); }
+    async enableService(name) { await enableCurrentService(name); }
     async disableService() { await disableCurrentService(); }
 }
 function message(value) {

package/dist/domain.d.ts

@@ -1,9 +1,20 @@
-import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture as CoreAnswerCapture, type AnswerMessage as CoreAnswerMessage, type AnswerObserver as CoreAnswerObserver, type AskCapture as CoreAskCapture, type AskMessage as CoreAskMessage, type AskObserver as CoreAskObserver, type Cleanup, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type EndpointDeclaration, type Exit, type Launch, type LocalWindow, type Permission, type ProgramProcess as CoreProgramProcess, 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 { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture as CoreAnswerCapture, type AnswerMessage as CoreAnswerMessage, type AnswerObserver as CoreAnswerObserver, type AskCapture as CoreAskCapture, type AskMessage as CoreAskMessage, type AskObserver as CoreAskObserver, type Cleanup, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type Exit, type Launch, type LocalWindow, type Permission, type Position, type ProgramProcess as CoreProgramProcess, 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 Events from "./events.js";
 export interface HandleAddress {
     identity: string;
     reference: string;
 }
+export interface EndpointDeclarationRecord {
+    start: boolean;
+    hasService: boolean;
+}
+export interface ClientDeclarationRecord extends EndpointDeclarationRecord {
+    title: string | null;
+    size: Size | null;
+    position: Position | null;
+    layer: ClientDeclaration["layer"];
+    minimize: boolean | null;
+}
 export interface ProgramRecord {
     reference: string;
     identity: string;
@@ -11,8 +22,8 @@ export interface ProgramRecord {
     name: string;
     version: string | null;
     description: string | null;
-    server: EndpointDeclaration | null;
-    client: ClientDeclaration | null;
+    server: EndpointDeclarationRecord | null;
+    client: ClientDeclarationRecord | null;
 }
 export interface ProcessRecord {
     reference: string;
@@ -37,7 +48,7 @@ export type Program<Events extends object = {}> = Omit<CoreProgram<Events>, "pro
     readonly process: ProgramProcess;
 };
 /** Client-visible Process operations scoped to one Program. */
-export type ProgramProcess = Omit<CoreProgramProcess, "list" | "first" | "last" | "find" | "create"> & {
+export type ProgramProcess = Omit<CoreProgramProcess, "list" | "first" | "last" | "find" | "create" | "findOrCreate"> & {
     /** Returns every live Process of this Program visible to the current Client. */
     list(): Promise<Process[]>;
     /** Returns the earliest-started visible live Process, or `null` when none exist. */
@@ -48,6 +59,10 @@ export type ProgramProcess = Omit<CoreProgramProcess, "list" | "first" | "last"
     find(identityOrName: string): Promise<Process | null>;
     /** Creates one Process of this same Program. */
     create(launch?: Launch): Promise<Process>;
+    /** Finds the named Process or atomically creates it with the same resolved launch. */
+    findOrCreate(launch: Launch & Readonly<{
+        name: string;
+    }>): Promise<Process>;
 };
 /** Process handle visible inside a structurally isolated Client. */
 export type Process<Events extends object = {}> = Omit<CoreProcess<Events>, "server" | "client" | "program" | "parent"> & {

package/dist/domain.js

@@ -33,8 +33,12 @@ class ProgramHandle extends ProgramBase {
     get name() { return this.record.name; }
     get version() { return this.record.version; }
     get description() { return this.record.description; }
-    get server() { return this.record.server; }
-    get client() { return this.record.client; }
+    get server() {
+        return this.record.server ? declaration("server", this.record.server) : null;
+    }
+    get client() {
+        return this.record.client ? clientDeclaration(this.record.client) : null;
+    }
     update(record) {
         if (record.reference !== this.reference)
             throw new Error("A Program handle cannot become another Program");
@@ -51,6 +55,29 @@ class ProgramHandle extends ProgramBase {
     async uninstall(everything = false) { await wire.request(["uninstall", undefined, everything]); }
     async forget() { await wire.request(["forget"]); }
 }
+function declaration(endpoint, record) {
+    return Object.freeze({
+        start: record.start,
+        hasService: () => record.hasService,
+        docs: () => endpointDocs(endpoint, record.hasService)
+    });
+}
+function clientDeclaration(record) {
+    return Object.freeze({
+        ...declaration("client", record),
+        title: record.title,
+        size: record.size,
+        position: record.position,
+        layer: record.layer,
+        minimize: record.minimize
+    });
+}
+async function endpointDocs(endpoint, declared) {
+    if (!declared)
+        return null;
+    const answer = await wire.request(["endpoint-docs", endpoint]);
+    return answer[0];
+}
 class ProgramProcessHandle {
     constructor(program) {
         bindEvents(this, scoped("program-process", program, programProcessEvent));
@@ -73,6 +100,10 @@ class ProgramProcessHandle {
         const answer = await wire.request(["program-process-create", launch]);
         return process(answer[0]);
     }
+    async findOrCreate(launch) {
+        const answer = await wire.request(["program-process-find-or-create", launch]);
+        return process(answer[0]);
+    }
     async exitAll() {
         const answer = await wire.request(["program-process-exit-all"]);
         return answer[0];

package/dist/host.d.ts

@@ -18,25 +18,12 @@ export interface Host {
     serve(value: unknown): Promise<ServedFile>;
     /** Performs an unrestricted server-side fetch on behalf of this Client. */
     fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
-    /** Prepares exact public service handles without exposing the service registry. */
-    readonly service: HostService;
-}
-/** Exact public service preparation available to a Client endpoint. */
-export interface HostService {
     /** Returns a precisely typed stable handle for either service endpoint. */
-    prepare<Endpoint extends ServiceEndpoint, ServiceEvents extends object = {}>(key: ServiceAddress<Endpoint>): ServiceHandle<Endpoint, ServiceEvents>;
-    /** Returns a stable handle for one exact Server service identity. */
-    prepare<ServiceEvents extends object = {}>(key: {
-        program: string;
-        endpoint: "server";
-        name: string;
-    }): ServerServiceHandler<ServiceEvents>;
-    /** Returns a stable handle for one exact Client service identity. */
-    prepare<ServiceEvents extends object = {}>(key: {
-        program: string;
-        endpoint: "client";
-        name: string;
-    }): ClientServiceHandler<ServiceEvents>;
+    service<Endpoint extends ServiceEndpoint>(key: ServiceAddress<Endpoint>): ServiceHandle<Endpoint, {}>;
+    /** Returns a typed stable handle for one exact Server service identity. */
+    service<ServiceEvents extends object>(key: ServiceAddress<"server">): ServerServiceHandler<ServiceEvents>;
+    /** Returns a typed stable handle for one exact Client service identity. */
+    service<ServiceEvents extends object>(key: ServiceAddress<"client">): ClientServiceHandler<ServiceEvents>;
 }
 /** Desktop capabilities available to this Client. */
 export declare const host: Host;

package/dist/host.js

@@ -8,7 +8,7 @@ class ClientHost {
     theme = new ClientTheme();
     desktop = new ClientDesktop();
     pointer = new ClientPointer();
-    service = new ClientHostService();
+    service(key) { return prepareService(key); }
     async serve(value) {
         const source = content(value);
         const channel = new MessageChannel();
@@ -80,11 +80,6 @@ class ClientHost {
         return response;
     }
 }
-class ClientHostService {
-    prepare(key) {
-        return prepareService(key);
-    }
-}
 function requestHeaders(normalized, supplied) {
     if (!supplied)
         return [...normalized.entries()];

package/dist/main.d.ts

@@ -1,4 +1,4 @@
-export { host, type Host, type HostService } from "./host.js";
+export { host, type Host } from "./host.js";
 export { type HostPointer, type PointerEvents, type PointerPosition } from "./pointer.js";
 export { type DesktopEvents, type DesktopSize, type HostDesktop } from "./desktop.js";
 export { current, type Current, type CurrentServer } from "./current.js";

package/dist/service.d.ts

@@ -1,4 +1,4 @@
-import { type ClientServiceHandler, type ServerServiceHandler, type ServiceDefinition, type ServiceHandler, type ServiceKey } from "@phreshos/core";
+import { type ClientServiceHandler, type ServerServiceHandler, type ServiceHandler, type ServiceKey } from "@phreshos/core";
 import type { HandleAddress } from "./domain.js";
 export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
     endpoint: "server";
@@ -7,7 +7,7 @@ export declare function prepareService<EventsMap extends object = {}>(key: Servi
     endpoint: "client";
 }): ClientServiceHandler<EventsMap>;
 export declare function prepareService(key: ServiceKey): ServiceHandler;
-export declare function enableCurrentService(definition: ServiceDefinition): Promise<void>;
+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<ServerServiceHandler<EventsMap> | null>;
 export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "client"): Promise<ClientServiceHandler<EventsMap> | null>;

package/dist/service.js

@@ -62,10 +62,6 @@ class ServerHandler extends ServerServiceBase {
     async waitReady(timeout) {
         await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
-    async docs() {
-        const answer = await wire.request(["service-docs", this.key]);
-        return answer[0];
-    }
 }
 class ClientHandler extends ClientServiceBase {
     key;
@@ -97,8 +93,8 @@ export function prepareService(key) {
             : new ClientHandler(normalized);
     });
 }
-export async function enableCurrentService(definition) {
-    await wire.request(["enable-service", definition]);
+export async function enableCurrentService(name) {
+    await wire.request(["enable-service", name]);
 }
 export async function disableCurrentService() {
     await wire.request(["disable-service"]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "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.9"
+    "@phreshos/core": "^0.1.11"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.9",
+    "@phreshos/core": "^0.1.11",
     "typescript": "^6.0.3"
   }
 }