@phreshos/client 0.1.1 → 0.1.3

package/README.md

@@ -114,16 +114,10 @@ Promises confirm that the current Client host accepted and applied the local
 draft; they do not enter server authority or emit Window events.
 
 An `under` or `over` Client may own one authoritative host-rendered Surface.
-The capability remains silent until Program code explicitly reads, changes, or
-subscribes to it:
+The capability is command-only: Program code may change or remove it, but
+cannot read or subscribe to its server-owned state:
 
 ```ts
-const initial = await window.surface.snapshot()
-
-const stop = window.surface.subscribe("change", surface => {
-  // Future replacements only; subscriptions do not replay `initial`.
-})
-
 await window.surface.set({
   opacity: 0.65,
   radius: "large",
@@ -133,14 +127,14 @@ await window.surface.set({
 await window.surface.remove()
 ```
 
-The server stores the target beside its Window and broadcasts complete future
-replacements. `set()` with no settings creates a sharp, fully opaque Surface.
+The server stores the target beside its Window and delivers it internally to
+the desktop. `set()` with no settings creates a sharp, fully opaque Surface.
 Opacity is a finite number from `0` through `1`; zero retains the Surface node.
 Radius accepts a nonnegative pixel number, a Theme-derived `ScaleLevel`, or
 `"full"`. Only `remove()` restores exact `null` and immediately removes the
 node. The optional transaction uses milliseconds and a stable named or cubic
 Bézier easing; the desktop performs the motion, honors reduced motion, and does
-not replay a stored transaction when restoring an initial snapshot. The sharp
+does not replay a stored transaction when restoring desktop state. The sharp
 container follows the iframe geometry while the independently rounded Surface
 neither clips nor masks Client content. `window` and `wallpaper` layers reject
 the capability.

package/dist/channel.js

@@ -1,6 +1,7 @@
 import { visibleEndpoint } from "./domain.js";
 import Events from "./events.js";
 import wire from "./wire.js";
+import { disableCurrentService, enableCurrentService } from "./service.js";
 class ClientChannel extends Events {
     constructor() {
         super((event, listener, impossible) => wire.on("end-end", event, value => listener(message(value)), null, impossible), observer => wire.onAll("end-end", (event, value) => {
@@ -11,6 +12,8 @@ class ClientChannel extends Events {
     publish(event, payload = undefined) {
         wire.send("end-host", "emit", event, payload);
     }
+    async enableService(name) { await enableCurrentService(name); }
+    async disableService() { await disableCurrentService(); }
 }
 function message(value) {
     const raw = value;

package/dist/current.d.ts

@@ -1,9 +1,9 @@
 import type { Channel as CoreChannel } from "@phreshos/core";
-import { Server, type Endpoint, type Process, type Program, type Window } from "./domain.js";
+import { Client, Server, type Endpoint, type Process, type Program, type Window } from "./domain.js";
 /** The current Process's canonical Server handle. */
 export type CurrentServer<Events extends object = {}> = Server<Events>;
 /** Current Client context: its inbound Channel, owner hierarchy, and paired Server. */
-export interface Current<Events extends object = {}> extends CoreChannel<Events, Endpoint | null> {
+export interface Current<Events extends object = {}> extends CoreChannel<Events, Endpoint | null>, Pick<Client, "service"> {
     /** The same Server handle exposed by the current Process. */
     readonly server: CurrentServer;
     /** Presentation capability of this current Client. */

package/dist/current.js

@@ -2,6 +2,7 @@ import { channel } from "./channel.js";
 import Deadline from "./deadline.js";
 import { Client, Server, ServerTrafficHandle, TrafficHandle, bindEvents, endpointEvents, process, program, window as windowHandle } from "./domain.js";
 import wire from "./wire.js";
+import { endpointService } from "./service.js";
 const ServerBase = Server;
 const ClientBase = Client;
 class CurrentServerHandle extends ServerBase {
@@ -20,6 +21,7 @@ class CurrentServerHandle extends ServerBase {
     }
     async start() { await wire.request(["start-endpoint", undefined, "server"]); }
     async stop() { await wire.request(["stop-endpoint", undefined, "server"]); }
+    service() { return endpointService(null, "server"); }
     async waitReady(timeout) { await wire.request(["wait-ready"], timeout); }
     async ask(event, payload = undefined) {
         return this.askWithin(undefined, event, payload);
@@ -75,6 +77,7 @@ class CurrentClientHandle extends ClientBase {
     }
     async start(overrides = {}) { await wire.request(["start-endpoint", undefined, "client", overrides]); }
     async stop() { await wire.request(["stop-endpoint", undefined, "client"]); }
+    service() { return endpointService(null, "client"); }
 }
 currentClient = new CurrentClientHandle(owner);
 class ClientCurrent {
@@ -97,6 +100,7 @@ class ClientCurrent {
         return answer[0];
     }
     async stop() { await wire.request(["stop-current"]); }
+    service() { return endpointService(null, "client"); }
 }
 function bindChannel(target, source) {
     Object.assign(target, {
@@ -104,7 +108,9 @@ function bindChannel(target, source) {
         subscribe: source.subscribe.bind(source),
         waitFor: source.waitFor.bind(source),
         events: source.events.bind(source),
-        observe: source.observe.bind(source)
+        observe: source.observe.bind(source),
+        enableService: source.enableService.bind(source),
+        disableService: source.disableService.bind(source)
     });
 }
 /** Inbound events, owner hierarchy, and paired Server for the current Client. */

package/dist/domain.js

@@ -4,6 +4,7 @@ import Deadline from "./deadline.js";
 import HandleRegistry from "./handle-registry.js";
 import { area, sql, store } from "./storage.js";
 import wire from "./wire.js";
+import { endpointService } from "./service.js";
 const handles = new HandleRegistry();
 const ProgramBase = CoreProgram;
 const ProcessBase = CoreProcess;
@@ -160,6 +161,7 @@ class ServerHandle extends ServerBase {
     }
     async start() { await wire.request(["start-endpoint", this.owner.address, "server"]); }
     async stop() { await wire.request(["stop-endpoint", this.owner.address, "server"]); }
+    service() { return endpointService(this.owner.address, "server"); }
     async waitReady(timeout) { await wire.request(["wait-ready", this.owner.address], timeout); }
     async ask(event, payload = undefined) {
         return this.askWithin(undefined, event, payload);
@@ -202,6 +204,7 @@ class ClientHandle extends ClientBase {
     }
     async start(overrides = {}) { await wire.request(["start-endpoint", this.owner.address, "client", overrides]); }
     async stop() { await wire.request(["stop-endpoint", this.owner.address, "client"]); }
+    service() { return endpointService(this.owner.address, "client"); }
 }
 class WindowHandle extends Events {
     target;
@@ -230,30 +233,11 @@ class WindowHandle extends Events {
     async changeTitle(title) { await wire.request(["changeTitle", await this.target(), title]); }
     async raise() { await wire.request(["raise", await this.target()]); }
 }
-class WindowSurfaceHandle extends Events {
+class WindowSurfaceHandle {
     target;
     constructor(target) {
-        super((event, listener, impossible) => {
-            if (event !== "change") {
-                impossible?.(new Error(`A Window Surface has no "${String(event)}" event`));
-                return () => undefined;
-            }
-            return deferred(target, subject => wire.on("host-end", "surface", (...values) => {
-                const message = unscoped(subject, values);
-                if (message)
-                    listener(message[0]);
-            }, subject, impossible), impossible);
-        }, observer => deferred(target, subject => wire.on("host-end", "surface", (...values) => {
-            const message = unscoped(subject, values);
-            if (message)
-                observer("change", message[0]);
-        }, subject)));
         this.target = target;
     }
-    async snapshot() {
-        const answer = await wire.request(["window", await this.target()]);
-        return answer[0].surface;
-    }
     async set(settings = {}) { await wire.request(["surfaceSet", await this.target(), settings]); }
     async remove() { await wire.request(["surfaceRemove", await this.target()]); }
 }

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-import type { Permissions, ServedFile, Theme, ThemeProperties } from "@phreshos/core";
+import type { ClientServiceHandler, Permissions, ServedFile, ServerServiceHandler, Theme, ThemeProperties } from "@phreshos/core";
 import { type HostPointer } from "./pointer.js";
 import { type HostSurface } from "./surface.js";
 /** Desktop capabilities structurally available to a Client endpoint. */
@@ -15,6 +15,18 @@ 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>;
+    /** Returns a stable handle for one exact Server service identity. */
+    service<ServiceEvents extends object = {}>(key: {
+        program: string;
+        endpoint: "server";
+        name: string;
+    }): ServerServiceHandler<ServiceEvents>;
+    /** Returns a stable handle for one exact Client service identity. */
+    service<ServiceEvents extends object = {}>(key: {
+        program: string;
+        endpoint: "client";
+        name: string;
+    }): ClientServiceHandler<ServiceEvents>;
 }
 /** Desktop capabilities available to this Client. */
 export declare const host: Host;

package/dist/host.js

@@ -4,6 +4,7 @@ import wire from "./wire.js";
 import ClientPermissions from "./permissions.js";
 import ClientPointer, {} from "./pointer.js";
 import ClientSurface, {} from "./surface.js";
+import { service as serviceHandle } from "./service.js";
 class ClientHost {
     theme = new ClientTheme();
     surface = new ClientSurface();
@@ -79,6 +80,9 @@ class ClientHost {
         });
         return response;
     }
+    service(key) {
+        return serviceHandle(key);
+    }
 }
 function requestHeaders(normalized, supplied) {
     if (!supplied)

package/dist/main.d.ts

@@ -3,5 +3,6 @@ export { type HostPointer, type PointerEvents, type PointerPosition } from "./po
 export { type HostSurface, type Surface, type SurfaceEvents } from "./surface.js";
 export { current, type Current, type CurrentServer } from "./current.js";
 export { type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js";
+export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server, type Window, type AnswerCapture, type AnswerMessage, type AnswerObserver, type AskCapture, type AskMessage, type AskObserver, type ClientTraffic, type EndpointTraffic, type ServerTraffic, type TrafficCapture, type TrafficEvents, type TrafficMessage } from "./domain.js";
-export type { Askable, Capture, Captures, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, PermissionDecision, Permissions, Position, ProgramArea, ProgramEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermissions, Timeoutable, Theme, ThemeEvents, ThemeProperties, Value, WritableTheme, WindowEvents, WindowLayer, WindowState, WindowSurface, WindowSurfaceEasing, WindowSurfaceEvents, WindowSurfaceSettings, WindowSurfaceTransaction } from "@phreshos/core";
+export type { Askable, Capture, Captures, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, PermissionDecision, Permissions, Position, ProgramArea, ProgramEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermissions, Timeoutable, Theme, ThemeEvents, ThemeProperties, Value, WritableTheme, WindowEvents, WindowLayer, WindowState, WindowSurface, WindowSurfaceEasing, WindowSurfaceSettings, WindowSurfaceTransaction } from "@phreshos/core";

package/dist/main.js

@@ -3,4 +3,5 @@ export {} from "./pointer.js";
 export {} from "./surface.js";
 export { current } from "./current.js";
 export {} from "./channel.js";
+export { ClientServiceHandler, ServerServiceHandler, ServiceHandler } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/service.d.ts

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

package/dist/service.js

@@ -0,0 +1,122 @@
+import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler, isServiceKey } 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();
+const ServerServiceBase = CoreServerServiceHandler;
+const ClientServiceBase = CoreClientServiceHandler;
+class ServerChannelHandle extends Events {
+    key;
+    constructor(key) {
+        super(...serviceEvents(key, "channel"));
+        this.key = key;
+    }
+    publish(event, payload = undefined) {
+        wire.send("end-host", "service-send", this.key, event, payload);
+    }
+    async ask(event, payload = undefined) {
+        return await this.askWithin(new Deadline(), event, payload);
+    }
+    timeout(milliseconds) {
+        return {
+            ask: (event, payload = undefined) => {
+                return this.askWithin(new Deadline(milliseconds), event, payload);
+            }
+        };
+    }
+    async askWithin(deadline, event, payload) {
+        const identity = await wire.identity();
+        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);
+        try {
+            return await waiting;
+        }
+        finally {
+            wire.forget(address);
+        }
+    }
+}
+class ClientChannelHandle extends Events {
+    constructor(key) {
+        super(...serviceEvents(key, "channel"));
+    }
+}
+class ServerHandler extends ServerServiceBase {
+    key;
+    program;
+    endpoint = "server";
+    name;
+    channel;
+    constructor(key) {
+        super();
+        this.key = key;
+        this.program = key.program;
+        this.name = key.name;
+        this.channel = new ServerChannelHandle(key);
+        bindEvents(this, new Events(...serviceEvents(key, "lifecycle")));
+    }
+    async disabled() {
+        const answer = await wire.request(["service-disabled", this.key]);
+        return answer[0];
+    }
+}
+class ClientHandler extends ClientServiceBase {
+    key;
+    program;
+    endpoint = "client";
+    name;
+    channel;
+    constructor(key) {
+        super();
+        this.key = key;
+        this.program = key.program;
+        this.name = key.name;
+        this.channel = new ClientChannelHandle(key);
+        bindEvents(this, new Events(...serviceEvents(key, "lifecycle")));
+    }
+    async disabled() {
+        const answer = await wire.request(["service-disabled", this.key]);
+        return answer[0];
+    }
+}
+export function service(key) {
+    if (!isServiceKey(key))
+        throw new Error("A complete service key is required");
+    const normalized = Object.freeze({ program: key.program, endpoint: key.endpoint, name: key.name });
+    const identity = JSON.stringify([normalized.program, normalized.endpoint, normalized.name]);
+    return handles.obtain(`service:${identity}`, () => {
+        return normalized.endpoint === "server"
+            ? new ServerHandler(normalized)
+            : new ClientHandler(normalized);
+    });
+}
+export async function enableCurrentService(name) {
+    await wire.request(["enable-service", name]);
+}
+export async function disableCurrentService() {
+    await wire.request(["disable-service"]);
+}
+export async function endpointService(target, endpoint) {
+    const answer = await wire.request(["endpoint-service", target, endpoint]);
+    return answer[0] ? service(answer[0]) : null;
+}
+function serviceEvents(key, scope) {
+    return [
+        (event, listener) => wire.followService(key, scope, event, listener),
+        (observer) => wire.followService(key, scope, null, (event, payload) => {
+            if (typeof event === "string")
+                observer(event, payload);
+        })
+    ];
+}
+function bindEvents(target, events) {
+    Object.assign(target, {
+        subscribe: events.subscribe.bind(events),
+        waitFor: events.waitFor.bind(events),
+        events: events.events.bind(events),
+        observe: events.observe.bind(events)
+    });
+}

package/dist/wire.d.ts

@@ -1,4 +1,4 @@
-import type { Cleanup } from "@phreshos/core";
+import type { Cleanup, ServiceKey } from "@phreshos/core";
 import Deadline from "./deadline.js";
 import type { HandleAddress } from "./domain.js";
 type Handler = (...values: unknown[]) => unknown;
@@ -32,6 +32,8 @@ declare class Wire {
     observe(target: HandleAddress | null, half: "server" | "client", kind: TrafficKind, event: string | null, handler: Handler, impossible?: Failure): Cleanup;
     /** 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" | "channel", event: string | null, handler: Handler): Cleanup;
     samplePointer(movementX: number, movementY: number): void;
     private register;
     private unregister;

package/dist/wire.js

@@ -194,6 +194,16 @@ class Wire {
             this.send("end-host", "unfollow", subscription);
         });
     }
+    /** Follow one exact service lifecycle or application event route. */
+    followService(key, scope, event, handler) {
+        const subscription = crypto.randomUUID();
+        const stop = this.on("service-event", subscription, handler);
+        this.send("end-host", "service-follow", subscription, key, scope, event);
+        return once(() => {
+            stop();
+            this.send("end-host", "service-unfollow", subscription);
+        });
+    }
     samplePointer(movementX, movementY) {
         this.send("end-host", "pointerSample", movementX, movementY);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -46,10 +46,10 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.1"
+    "@phreshos/core": "^0.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.1",
+    "@phreshos/core": "^0.1.3",
     "typescript": "^6.0.3"
   }
 }