@phreshos/client 0.1.24 → 0.1.26

package/README.md

@@ -51,17 +51,17 @@ requests; subscriptions receive only future publications and never replay a
 retained value.
 
 Permission decisions belong to the current Program, not to the desktop System.
-They are available from a Program handle and flattened through `current` as the
+They are available from a Program handle and flattened through `context` as the
 same canonical capability:
 
 ```ts
-const program = await current.program()
+const program = await context.program()
 
 await program.permission.granted("pointer")
-await current.permission.request("pointer")
-await current.permission.timeout(5_000).request("pointer")
+await context.permission.request("pointer")
+await context.permission.timeout(5_000).request("pointer")
 
-current.permission === program.permission
+context.permission === program.permission
 ```
 
 `granted()` reads the effective decision without prompting. `request()` asks
@@ -80,7 +80,10 @@ const service = system.service({
 })
 
 await service.waitReady()
-if (await service.enabled()) await service.channel.ask("value")
+if (await service.enabled()) await service.ask("value")
+
+service.subscribe("changed", message => console.log(message))
+service.lifecycle.subscribe("disable", () => console.log("unavailable"))
 ```
 
 A Client may traverse `Process.parent()` through any number of ancestors in
@@ -98,13 +101,13 @@ into the endpoint. Identity, Theme, Process, Window, readiness, lifecycle, and
 application values enter only in response to an explicit request or a live
 registration made by Program code.
 
-`Current` combines navigation into the executing Client's Process with its
-Channel. The paired Server is explicitly named as
-`current.server`; its publishing, asking, existence, readiness, start, and stop
-operations never masquerade as properties of `current`. `current.stop()` stops
+`Context` combines communication with navigation into the executing Client's
+Process. The paired Server is explicitly named as
+`context.server`; its publishing, asking, existence, readiness, start, and stop
+operations never masquerade as properties of `context`. `context.stop()` stops
 the executing Client, while complete Process exit remains available only
-through `current.process()`. It is the canonical Process-owned handle, so
-`current.server === (await current.process()).server`.
+through `context.process()`. It is the canonical Process-owned handle, so
+`context.server === (await context.process()).server`.
 Endpoint `process()` navigation is asynchronous; contextual ownership is
 requested only when navigation needs it and then retained by the SDK.
 
@@ -121,7 +124,7 @@ absence or incarnation loss rejects without turning the boundary into a waiter.
 The package provides two contextual runtime entry points:
 
 ```ts
-import { system, current } from "@phreshos/client"
+import { system, context } from "@phreshos/client"
 ```
 
 It also re-exports the shared Core runtime classes—`Program`, `Process`,
@@ -131,11 +134,12 @@ them. These are the same domain classes used by the Server SDK, so
 `ClientTraffic`, is a type-only capability owned by Client and has no
 independent `instanceof` identity.
 
-The current Client's Channel is composed directly into `current`. Its
+The executing Client's communication belongs directly to `context`. Its
 subscription tools receive events addressed to this Client, while `publish()`
-emits outward from this Client without choosing a destination. Existence,
-readiness, and lifecycle operations belong to `current.server`,
-`current.stop()`, or an explicit Endpoint handle.
+emits outward from this Client without choosing a destination. Existence and
+readiness belong to `context.server`; the current Client stops through
+`context.stop()`, and explicit Endpoint handles expose their own
+`endpoint.lifecycle` subscriptions.
 
 An Endpoint handle is also a selective source: `endpoint.subscribe()` follows
 destinationless events emitted by that Endpoint. Its `traffic` property remains
@@ -151,7 +155,7 @@ They deliberately omit `install()` and `fork()`, and their `Storage` values neve
 expose native filesystem paths. Every Client-side Window handle exposes the same
 authoritative, subscribable Window capability and its `window.local` physical
 representation on this desktop. Local reads and updates have no events and do
-not change Server state. `current.window` is only convenient access to the
+not change Server state. `context.window` is only convenient access to the
 executing Client's canonical Window; it has no additional authority.
 
 A Client may uninstall only its own Program. The operation is an async
@@ -186,9 +190,9 @@ two independent operations and can expose an intermediate state remotely.
 An `under` or `over` representation may request one local system-rendered Surface:
 
 ```ts
-await current.window.local.surface.set({ duration: 240, easing: "ease-out", wait: true })
+await context.window.local.surface.set({ duration: 240, easing: "ease-out", wait: true })
 
-await current.window.local.surface.remove({ duration: 180, easing: "ease-in" })
+await context.window.local.surface.remove({ duration: 180, easing: "ease-in" })
 ```
 
 The desktop holds local state only for the lifetime of that iframe

package/dist/context.d.ts

@@ -0,0 +1,31 @@
+import type { Context as CoreContext, ContextCapture as CoreContextCapture, ContextEvents as CoreContextEvents, ContextMessage as CoreContextMessage } from "@phreshos/core";
+import { Client, Server, type Endpoint, type Process, type Program, type Window } from "./domain.js";
+/** The executing Process's canonical Server handle. */
+export type ContextServer<Events extends object = {}> = Server<Events>;
+/** One value addressed to the current Client, with a client-visible sender. */
+export type ContextMessage<Payload = unknown> = CoreContextMessage<Payload, Endpoint | null>;
+/** Applies the client-visible sender envelope to known Context events. */
+export type ContextEvents<Events extends object> = CoreContextEvents<Events, Endpoint | null>;
+/** Every event observable through the current Client Context. */
+export type ContextCapture<Events extends object = {}> = CoreContextCapture<Events, Endpoint | null>;
+/** Client runtime context: inbound communication, owner hierarchy, and paired Server. */
+export interface Context<Events extends object = {}> extends CoreContext<Events, Endpoint | null>, Pick<Client, "service"> {
+    /** The same Server handle exposed by the executing Process. */
+    readonly server: ContextServer;
+    /** Presentation capability of the executing Client. */
+    readonly window: Window;
+    /** The same permission capability exposed by the executing Program. */
+    readonly permission: Program["permission"];
+    /** Returns the Process represented by this Client. */
+    process(): Promise<Process>;
+    /** Returns the accessible parent Process, or `null` when none exists. */
+    parent(): Promise<Process | null>;
+    /** Returns the Program that owns this Client. */
+    program(): Promise<Program>;
+    /** Returns one immutable option supplied when this Process was created. */
+    option(name: string): Promise<string | undefined>;
+    /** Stops the executing Client; rejects when it is the final live Endpoint. */
+    stop(): Promise<void>;
+}
+/** Inbound events, owner hierarchy, and paired Server for this Client runtime. */
+export declare const context: Context;

package/dist/{current.js → context.js}

@@ -1,14 +1,15 @@
-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 { Client, Server, ServerTrafficHandle, TrafficHandle, bindEvents, endpointLifecycle, endpointEvents, process, program, visibleEndpoint, window as windowHandle } from "./domain.js";
+import Events from "./events.js";
 import wire from "./wire.js";
-import { endpointService } from "./service.js";
+import { disableCurrentService, enableCurrentService, endpointService } from "./service.js";
 import { currentProgramPermission } from "./permissions.js";
 const ServerBase = Server;
 const ClientBase = Client;
-class CurrentServerHandle extends ServerBase {
+class ContextServerHandle extends ServerBase {
     owner;
     traffic = new ServerTrafficHandle(null, "server");
+    lifecycle = endpointLifecycle(currentAddress, "server");
     constructor(owner) {
         super();
         this.owner = owner;
@@ -37,12 +38,12 @@ class CurrentServerHandle extends ServerBase {
     }
 }
 let ownerPromise = null;
-let currentServer;
-let currentClient;
+let contextServer;
+let contextClient;
 function owner() {
     if (!ownerPromise) {
         const resolving = wire.request(["current-process"]).then(answer => {
-            return process(answer[0], { server: currentServer, client: currentClient });
+            return process(answer[0], { server: contextServer, client: contextClient });
         });
         const retained = resolving.catch(error => {
             if (ownerPromise === retained)
@@ -53,14 +54,12 @@ function owner() {
     }
     return ownerPromise;
 }
-currentServer = new CurrentServerHandle(owner);
-class CurrentClientHandle extends ClientBase {
+contextServer = new ContextServerHandle(owner);
+class ContextClientHandle extends ClientBase {
     owner;
     traffic = new TrafficHandle(null, "client");
-    window = windowHandle(async () => {
-        const identity = await wire.identity();
-        return { identity: identity.process, reference: identity.reference };
-    });
+    lifecycle = endpointLifecycle(currentAddress, "client");
+    window = windowHandle(currentAddress);
     constructor(owner) {
         super();
         this.owner = owner;
@@ -80,13 +79,16 @@ class CurrentClientHandle extends ClientBase {
     async stop() { await wire.request(["stop-endpoint", undefined, "client"]); }
     service() { return endpointService(null, "client"); }
 }
-currentClient = new CurrentClientHandle(owner);
-class ClientCurrent {
-    server = currentServer;
-    window = currentClient.window;
+contextClient = new ContextClientHandle(owner);
+class ClientContext extends Events {
+    server = contextServer;
+    window = contextClient.window;
     permission = currentProgramPermission;
     constructor() {
-        bindChannel(this, channel);
+        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")
+                listener(event, contextMessage(value));
+        }, null, impossible));
     }
     process() { return owner(); }
     async parent() {
@@ -103,17 +105,17 @@ class ClientCurrent {
     }
     async stop() { await wire.request(["stop-current"]); }
     service() { return endpointService(null, "client"); }
+    publish(event, payload = undefined) { wire.send("end-host", "emit", event, payload); }
+    async enableService(name) { await enableCurrentService(name); }
+    async disableService() { await disableCurrentService(); }
 }
-function bindChannel(target, source) {
-    Object.assign(target, {
-        publish: source.publish.bind(source),
-        subscribe: source.subscribe.bind(source),
-        waitFor: source.waitFor.bind(source),
-        events: source.events.bind(source),
-        observe: source.observe.bind(source),
-        enableService: source.enableService.bind(source),
-        disableService: source.disableService.bind(source)
-    });
+async function currentAddress() {
+    const identity = await wire.identity();
+    return { identity: identity.process, reference: identity.reference };
 }
-/** Inbound events, owner hierarchy, and paired Server for the current Client. */
-export const current = new ClientCurrent();
+function contextMessage(value) {
+    const raw = value;
+    return { from: visibleEndpoint(raw.from), payload: raw.payload };
+}
+/** Inbound events, owner hierarchy, and paired Server for this Client runtime. */
+export const context = new ClientContext();

package/dist/domain.d.ts

@@ -1,4 +1,4 @@
-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 { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture as CoreAnswerCapture, type AnswerMessage as CoreAnswerMessage, 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 Launch, type LocalWindow, type Outcome, 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;
@@ -86,13 +86,13 @@ export type AskMessage<Payload = unknown> = CoreAskMessage<Payload, Server | nul
 /** One question observable in client-visible Endpoint traffic. */
 export type AskCapture<Payload = unknown> = CoreAskCapture<Payload, Server | null>;
 /** Callback that observes questions sent by a client-visible Endpoint. */
-export type AskObserver<Payload = unknown> = CoreAskObserver<Payload, Server | null>;
+export type AskSubscriber<Payload = unknown> = CoreAskSubscriber<Payload, Server | null>;
 /** Answer with an Endpoint destination hidden when it crosses the Client boundary. */
 export type AnswerMessage<Result = unknown> = CoreAnswerMessage<Result, Endpoint | null>;
 /** One answer observable in client-visible Server traffic. */
 export type AnswerCapture<Result = unknown> = CoreAnswerCapture<Result, Endpoint | null>;
 /** Callback that observes answers sent by a client-visible Server. */
-export type AnswerObserver<Result = unknown> = CoreAnswerObserver<Result, Endpoint | null>;
+export type AnswerSubscriber<Result = unknown> = CoreAnswerSubscriber<Result, Endpoint | null>;
 /** Directed communication originating from one client-visible Endpoint. */
 export type EndpointTraffic<Events extends object = {}> = CoreEndpointTraffic<Events, Endpoint | null, Server | null>;
 /** Directed communication originating from one client-visible Server. */
@@ -131,15 +131,35 @@ export declare class TrafficHandle extends Events {
     protected readonly target: HandleAddress | null;
     protected readonly kind: "server" | "client";
     constructor(target: HandleAddress | null, kind: "server" | "client");
-    observeAsks(observer: (capture: AskCapture) => unknown): Cleanup;
+    subscribeAsks(subscriber: (capture: AskCapture) => unknown): Cleanup;
+    asks(options?: EventOptions): AsyncIterableIterator<Readonly<{
+        event: string;
+        questionId: string;
+        message: Readonly<{
+            to: Server<{}> | null;
+            payload: unknown;
+        }>;
+    }>>;
+    private followAsks;
 }
 export declare class ServerTrafficHandle extends TrafficHandle {
-    observeAnswers(observer: (capture: AnswerCapture) => unknown): Cleanup;
+    subscribeAnswers(subscriber: (capture: AnswerCapture) => unknown): Cleanup;
+    answers(options?: EventOptions): AsyncIterableIterator<Readonly<{
+        event: string;
+        questionId: string;
+        message: Readonly<{
+            to: Endpoint<{}> | null;
+            outcome: Outcome<unknown>;
+        }>;
+    }>>;
+    private followAnswers;
 }
 type WindowTarget = () => Promise<HandleAddress>;
 export declare function scoped(route: string, subject: string | null, convert: (event: string, values: unknown[]) => unknown): Events;
 /** Destinationless events originating from one Endpoint handle. */
 export declare function endpointEvents(target: HandleAddress | null, half: "server" | "client"): Events;
+/** Start and stop transitions belonging directly to one permanent Endpoint. */
+export declare function endpointLifecycle(target: WindowTarget, half: "server" | "client"): Events;
 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;

package/dist/domain.js

@@ -1,5 +1,5 @@
 import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer } from "@phreshos/core";
-import Events from "./events.js";
+import Events, { stream } from "./events.js";
 import Deadline from "./deadline.js";
 import HandleRegistry from "./handle-registry.js";
 import { area, sql, store } from "./storage.js";
@@ -165,38 +165,52 @@ export class TrafficHandle extends Events {
     target;
     kind;
     constructor(target, kind) {
-        super((event, listener, impossible) => wire.observe(target, kind, "publish", event, value => listener(trafficMessage(value)), impossible), observer => wire.observe(target, kind, "publish", null, (event, value) => {
+        super((event, listener, impossible) => wire.observe(target, kind, "publish", event, value => listener(trafficMessage(value)), impossible), (listener, impossible) => wire.observe(target, kind, "publish", null, (event, value) => {
             if (typeof event === "string")
-                observer(event, trafficMessage(value));
-        }));
+                listener(event, trafficMessage(value));
+        }, impossible));
         this.target = target;
         this.kind = kind;
     }
-    observeAsks(observer) {
+    subscribeAsks(subscriber) {
+        return this.followAsks(subscriber);
+    }
+    asks(options) {
+        return stream((subscriber, impossible) => this.followAsks(subscriber, impossible), options);
+    }
+    followAsks(subscriber, impossible) {
         return wire.observe(this.target, this.kind, "ask", null, (event, questionId, value) => {
             if (typeof event !== "string" || typeof questionId !== "string")
                 return;
-            observer({ event, questionId, message: trafficMessage(value) });
-        });
+            subscriber({ event, questionId, message: trafficMessage(value) });
+        }, impossible);
     }
 }
 export class ServerTrafficHandle extends TrafficHandle {
-    observeAnswers(observer) {
+    subscribeAnswers(subscriber) {
+        return this.followAnswers(subscriber);
+    }
+    answers(options) {
+        return stream((subscriber, impossible) => this.followAnswers(subscriber, impossible), options);
+    }
+    followAnswers(subscriber, impossible) {
         return wire.observe(this.target, "server", "answer", null, (event, questionId, value) => {
             if (typeof event !== "string" || typeof questionId !== "string")
                 return;
             const raw = value;
-            observer({ event, questionId, message: { to: visibleEndpoint(raw.to), outcome: raw.outcome } });
-        });
+            subscriber({ event, questionId, message: { to: visibleEndpoint(raw.to), outcome: raw.outcome } });
+        }, impossible);
     }
 }
 class ServerHandle extends ServerBase {
     owner;
     traffic;
+    lifecycle;
     constructor(owner) {
         super();
         this.owner = owner;
         this.traffic = new ServerTrafficHandle(owner.address, "server");
+        this.lifecycle = endpointLifecycle(() => Promise.resolve(owner.address), "server");
         bindEvents(this, endpointEvents(owner.address, "server"));
     }
     async process() { return this.owner; }
@@ -234,11 +248,13 @@ class ServerHandle extends ServerBase {
 class ClientHandle extends ClientBase {
     owner;
     traffic;
+    lifecycle;
     window;
     constructor(owner) {
         super();
         this.owner = owner;
         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"));
     }
@@ -328,13 +344,13 @@ function deferredScoped(route, target, convert) {
                     listener(convert(event, message));
             }, subject, impossible), impossible);
         },
-        observer => deferred(target, subject => wire.onAll(route, (event, ...values) => {
+        (listener, impossible) => deferred(target, subject => wire.onAll(route, (event, ...values) => {
             if (typeof event !== "string" || !windowEvent(event))
                 return;
             const message = unscoped(subject, values);
             if (message)
-                observer(event, convert(event, message));
-        }, subject))
+                listener(event, convert(event, message));
+        }, subject, impossible), impossible)
     ];
 }
 function windowEvent(event) {
@@ -363,20 +379,41 @@ export function scoped(route, subject, convert) {
         const message = unscoped(subject, values);
         if (message)
             listener(convert(event, message));
-    }, subject, impossible), observer => wire.onAll(route, (event, ...values) => {
+    }, subject, impossible), (listener, impossible) => wire.onAll(route, (event, ...values) => {
         if (typeof event !== "string")
             return;
         const message = unscoped(subject, values);
         if (message)
-            observer(event, convert(event, message));
-    }, subject));
+            listener(event, convert(event, message));
+    }, subject, impossible));
 }
 /** Destinationless events originating from one Endpoint handle. */
 export function endpointEvents(target, half) {
-    return new Events((event, listener, impossible) => wire.follow(target, half, event, listener, impossible), observer => wire.follow(target, half, null, (event, payload) => {
+    return new Events((event, listener, impossible) => wire.follow(target, half, event, listener, impossible), (listener, impossible) => wire.follow(target, half, null, (event, payload) => {
         if (typeof event === "string")
-            observer(event, payload);
-    }));
+            listener(event, payload);
+    }, impossible));
+}
+/** 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 message = unscoped(subject, values);
+        if (message?.[1] === half)
+            listener(undefined);
+    }, subject, impossible), impossible), (listener, impossible) => deferred(target, subject => wire.onAll("process-host", (event, ...values) => {
+        if (event !== "endpointStart" && event !== "endpointStop")
+            return;
+        const message = unscoped(subject, values);
+        if (message?.[1] === half)
+            listener(event === "endpointStart" ? "start" : "stop", undefined);
+    }, subject, impossible), impossible));
+}
+function endpointLifecycleEvent(event) {
+    if (event === "start")
+        return "endpointStart";
+    if (event === "stop")
+        return "endpointStop";
+    return event;
 }
 function unscoped(subject, values) {
     if (subject === null)
@@ -426,8 +463,7 @@ export 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)
+        events: events.events.bind(events)
     });
 }
 export function program(record) {

package/dist/events.d.ts

@@ -2,15 +2,19 @@ import type { Capture, Cleanup, EventOptions } from "@phreshos/core";
 export declare const defaultTimeout = 10000;
 type Failure = (error: Error) => void;
 type Listener = (message: unknown) => unknown;
-type Observer = (event: string, message: unknown) => unknown;
+type EveryListener = (event: string, message: unknown) => unknown;
+type Register<Message> = (listener: (message: Message) => unknown, impossible?: Failure) => Cleanup;
 /** SDK-owned waits, queues and callbacks over boundary forwarding state. */
 export default class Events {
     private readonly listen;
     private readonly listenAll;
-    constructor(listen: (event: string, listener: Listener, impossible?: Failure) => Cleanup, listenAll: (observer: Observer) => Cleanup);
+    constructor(listen: (event: string, listener: Listener, impossible?: Failure) => Cleanup, listenAll: (listener: EveryListener, impossible?: Failure) => Cleanup);
     subscribe(event: string, subscriber: Listener): Cleanup;
+    subscribe(subscriber: (capture: Capture<string, unknown>) => unknown): Cleanup;
     waitFor(event: string, timeout?: number): Promise<unknown>;
     events(event: string, options?: EventOptions): AsyncIterableIterator<unknown>;
-    observe(observer: (capture: Capture<string, unknown>) => unknown): Cleanup;
+    events(options?: EventOptions): AsyncIterableIterator<Capture<string, unknown>>;
 }
+/** Converts one persistent registration into a bounded asynchronous iterator. */
+export declare function stream<Message>(register: Register<Message>, options?: EventOptions): AsyncIterableIterator<Message>;
 export {};

package/dist/events.js

@@ -7,8 +7,10 @@ export default class Events {
         this.listen = listen;
         this.listenAll = listenAll;
     }
-    subscribe(event, subscriber) {
-        return this.listen(event, subscriber);
+    subscribe(eventOrSubscriber, subscriber) {
+        if (typeof eventOrSubscriber === "string")
+            return this.listen(eventOrSubscriber, subscriber);
+        return this.listenAll((event, message) => eventOrSubscriber({ event, message }));
     }
     waitFor(event, timeout = defaultTimeout) {
         return new Promise((resolve, reject) => {
@@ -26,58 +28,63 @@ export default class Events {
             stop = this.listen(event, message => finish(() => resolve(message)), error => finish(() => reject(error)));
         });
     }
-    events(event, options = {}) {
-        const capacity = options.capacity ?? 64;
-        if (capacity !== Infinity && (!Number.isInteger(capacity) || capacity < 0)) {
-            throw new Error("An event queue capacity must be a non-negative integer or Infinity");
+    events(eventOrOptions = {}, namedOptions = {}) {
+        if (typeof eventOrOptions === "string") {
+            return stream((listener, impossible) => this.listen(eventOrOptions, listener, impossible), namedOptions);
         }
-        const listen = this.listen;
-        return (async function* () {
-            const queue = [];
-            let ended = false;
-            let failure = null;
-            let wake = null;
-            const stop = listen(event, message => {
-                if (ended || failure)
-                    return;
-                if (queue.length >= capacity)
-                    failure = new Error(`Event queue exceeded its capacity of ${capacity}`);
-                else
-                    queue.push(message);
-                wake?.();
-                wake = null;
-            }, error => {
-                if (ended || failure)
-                    return;
-                failure = error;
-                wake?.();
-                wake = null;
-            });
-            const abort = () => {
-                ended = true;
-                wake?.();
-                wake = null;
-            };
-            options.signal?.addEventListener("abort", abort, { once: true });
-            try {
-                while (!ended) {
-                    if (queue.length) {
-                        yield queue.shift();
-                        continue;
-                    }
-                    if (failure)
-                        throw failure;
-                    await new Promise(resolve => { wake = resolve; });
-                }
-            }
-            finally {
-                ended = true;
-                stop();
-                options.signal?.removeEventListener("abort", abort);
-            }
-        })();
+        return stream((listener, impossible) => this.listenAll((event, message) => listener({ event, message }), impossible), eventOrOptions);
     }
-    observe(observer) {
-        return this.listenAll((event, message) => observer({ event, message }));
+}
+/** Converts one persistent registration into a bounded asynchronous iterator. */
+export function stream(register, options = {}) {
+    const capacity = options.capacity ?? 64;
+    if (capacity !== Infinity && (!Number.isInteger(capacity) || capacity < 0)) {
+        throw new Error("An event queue capacity must be a non-negative integer or Infinity");
     }
+    return (async function* () {
+        const queue = [];
+        let ended = false;
+        let failure = null;
+        let wake = null;
+        const stop = register(message => {
+            if (ended || failure)
+                return;
+            if (queue.length >= capacity)
+                failure = new Error(`Event queue exceeded its capacity of ${capacity}`);
+            else
+                queue.push(message);
+            wake?.();
+            wake = null;
+        }, error => {
+            if (ended || failure)
+                return;
+            failure = error;
+            wake?.();
+            wake = null;
+        });
+        const abort = () => {
+            ended = true;
+            wake?.();
+            wake = null;
+        };
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+        try {
+            while (!ended) {
+                if (queue.length) {
+                    yield queue.shift();
+                    continue;
+                }
+                if (failure)
+                    throw failure;
+                await new Promise(resolve => { wake = resolve; });
+            }
+        }
+        finally {
+            ended = true;
+            stop();
+            options.signal?.removeEventListener("abort", abort);
+        }
+    })();
 }

package/dist/main.d.ts

@@ -1,8 +1,7 @@
 export { system, type System } from "./system.js";
 export { type SystemPointer, type PointerEvents, type PointerPosition } from "./pointer.js";
 export { type DesktopEvents, type DesktopSize, type SystemDesktop } from "./desktop.js";
-export { current, type Current, type CurrentServer } from "./current.js";
-export { type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js";
-export { ClientService, ServerService, Service, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
-export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess, 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, Permission, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, AnimationsPreference, DesktopPreferences, DesktopPreferencesEvents, DesktopPreferencesUpdate, SystemDesktopPreferences, ThemedValue, Theme, ThemePreference, Value, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, VisibilityTransition, Transaction } from "@phreshos/core";
+export { context, type Context, type ContextCapture, type ContextEvents, type ContextMessage, type ContextServer } from "./context.js";
+export { ClientService, ServerService, Service, type ServiceKey, type ServiceLifecycle, type ServiceLifecycleEvents } from "@phreshos/core";
+export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess, type AnswerCapture, type AnswerMessage, type AnswerSubscriber, type AskCapture, type AskMessage, type AskSubscriber, type ClientTraffic, type EndpointTraffic, type ServerTraffic, type TrafficCapture, type TrafficEvents, type TrafficMessage } from "./domain.js";
+export type { Askable, Capture, Captures, CaptureSubscriber, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointLifecycle, EndpointLifecycleEvents, EntryStat, EventMessage, EventName, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, PermissionDecision, Permission, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, AnimationsPreference, DesktopPreferences, DesktopPreferencesEvents, DesktopPreferencesUpdate, SystemDesktopPreferences, ThemedValue, Theme, ThemePreference, Value, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, VisibilityTransition, Transaction } from "@phreshos/core";

package/dist/main.js

@@ -1,7 +1,6 @@
 export { system } from "./system.js";
 export {} from "./pointer.js";
 export {} from "./desktop.js";
-export { current } from "./current.js";
-export {} from "./channel.js";
+export { context } from "./context.js";
 export { ClientService, ServerService, Service } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/service.js

@@ -6,11 +6,16 @@ import wire from "./wire.js";
 const handles = new HandleRegistry();
 const ServerServiceBase = CoreServerService;
 const ClientServiceBase = CoreClientService;
-class ServerChannelHandle extends Events {
+class ServerHandler extends ServerServiceBase {
     key;
+    name;
+    lifecycle;
     constructor(key) {
-        super(...serviceEvents(key, "channel"));
+        super();
         this.key = key;
+        this.name = key.name;
+        this.lifecycle = new Events(...serviceEvents(key, "lifecycle"));
+        bindEvents(this, new Events(...serviceEvents(key, "events")));
     }
     publish(event, payload = undefined) {
         wire.send("end-host", "service-send", this.key, event, payload);
@@ -25,6 +30,13 @@ class ServerChannelHandle extends Events {
             }
         };
     }
+    async enabled() {
+        const answer = await wire.request(["service-enabled", this.key]);
+        return answer[0];
+    }
+    async waitReady(timeout) {
+        await wire.request(["service-wait-ready", this.key, timeout], timeout);
+    }
     async askWithin(deadline, event, payload) {
         const identity = await wire.identity();
         const address = `client:${identity.process}:${crypto.randomUUID()}`;
@@ -39,40 +51,16 @@ class ServerChannelHandle extends Events {
         }
     }
 }
-class ClientChannelHandle extends Events {
-    constructor(key) {
-        super(...serviceEvents(key, "channel"));
-    }
-}
-class ServerHandler extends ServerServiceBase {
-    key;
-    name;
-    channel;
-    constructor(key) {
-        super();
-        this.key = key;
-        this.name = key.name;
-        this.channel = new ServerChannelHandle(key);
-        bindEvents(this, new Events(...serviceEvents(key, "lifecycle")));
-    }
-    async enabled() {
-        const answer = await wire.request(["service-enabled", this.key]);
-        return answer[0];
-    }
-    async waitReady(timeout) {
-        await wire.request(["service-wait-ready", this.key, timeout], timeout);
-    }
-}
 class ClientHandler extends ClientServiceBase {
     key;
     name;
-    channel;
+    lifecycle;
     constructor(key) {
         super();
         this.key = key;
         this.name = key.name;
-        this.channel = new ClientChannelHandle(key);
-        bindEvents(this, new Events(...serviceEvents(key, "lifecycle")));
+        this.lifecycle = new Events(...serviceEvents(key, "lifecycle"));
+        bindEvents(this, new Events(...serviceEvents(key, "events")));
     }
     async enabled() {
         const answer = await wire.request(["service-enabled", this.key]);
@@ -106,9 +94,9 @@ export async function endpointService(target, endpoint) {
 function serviceEvents(key, scope) {
     return [
         (event, listener) => wire.followService(key, scope, event, listener),
-        (observer) => wire.followService(key, scope, null, (event, payload) => {
+        (listener) => wire.followService(key, scope, null, (event, payload) => {
             if (typeof event === "string")
-                observer(event, payload);
+                listener(event, payload);
         })
     ];
 }
@@ -116,7 +104,6 @@ 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)
+        events: events.events.bind(events)
     });
 }

package/dist/wire.d.ts

@@ -32,12 +32,12 @@ declare class Wire {
     expectWithin(question: string, deadline: Deadline): Promise<unknown>;
     forget(question: string): void;
     on(route: string, event: string, handler: Handler, subject?: string | null, impossible?: Failure): Cleanup;
-    onAll(route: string, handler: Handler, subject?: string | null): Cleanup;
+    onAll(route: string, handler: Handler, subject?: string | null, impossible?: Failure): Cleanup;
     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;
+    followService(key: ServiceKey, scope: "lifecycle" | "events", event: string | null, handler: Handler): Cleanup;
     samplePointer(movementX: number, movementY: number): void;
     private register;
     private unregister;

package/dist/wire.js

@@ -221,11 +221,11 @@ class Wire {
             this.unregister(subscription);
         });
     }
-    onAll(route, handler, subject = null) {
+    onAll(route, handler, subject = null, impossible) {
         const handlers = this.every.get(route) ?? new Set();
         handlers.add(handler);
         this.every.set(route, handlers);
-        const subscription = this.register("publish", route, null, subject);
+        const subscription = this.register("publish", route, null, subject, impossible);
         return once(() => {
             handlers.delete(handler);
             if (!handlers.size)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "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.24"
+    "@phreshos/core": "^0.1.26"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.24",
+    "@phreshos/core": "^0.1.26",
     "typescript": "^6.0.3"
   }
 }

package/dist/channel.d.ts

@@ -1,12 +0,0 @@
-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>;
-/** Applies the client-visible sender envelope to known Channel events. */
-export type ChannelEvents<Events extends object> = CoreChannelEvents<Events, Endpoint | null>;
-/** 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> {
-}
-export declare const channel: Channel;

package/dist/channel.js

@@ -1,22 +0,0 @@
-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) => {
-            if (typeof event === "string")
-                observer(event, message(value));
-        }));
-    }
-    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;
-    return { from: visibleEndpoint(raw.from), payload: raw.payload };
-}
-export const channel = new ClientChannel();

package/dist/current.d.ts

@@ -1,25 +0,0 @@
-import { type Channel } from "./channel.js";
-import { Client, Server, 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 Channel<Events>, Pick<Client, "service"> {
-    /** The same Server handle exposed by the current Process. */
-    readonly server: CurrentServer;
-    /** Presentation capability of this current Client. */
-    readonly window: Window;
-    /** The same permission capability exposed by the current Program. */
-    readonly permission: Program["permission"];
-    /** Returns the Process represented by this Client. */
-    process(): Promise<Process>;
-    /** Returns the accessible parent Process, or `null` when none exists. */
-    parent(): Promise<Process | null>;
-    /** Returns the Program that owns this Client. */
-    program(): Promise<Program>;
-    /** Returns one immutable option supplied when this Process was created. */
-    option(name: string): Promise<string | undefined>;
-    /** Stops the current Client; rejects when it is the final live Endpoint. */
-    stop(): Promise<void>;
-}
-/** Inbound events, owner hierarchy, and paired Server for the current Client. */
-export declare const current: Current;