@phreshos/client 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# `@phreshos/client`
+
+The Client SDK defines the contextual capabilities available inside a
+Program's client endpoint.
+
+## Package status
+
+This package is one component of a larger architecture that is still under
+active testing. The architecture's components will be released in stages as
+their contracts and integrations are verified.
+
+`@phreshos/client` is not intended to be used on its own. It requires the
+shared contracts from `@phreshos/core` and a compatible desktop boundary to
+provide its runtime environment.
+
+It uses the domain objects and shared contracts from `@phreshos/core` through
+a peer dependency. It does not redefine those objects, own server-side
+capabilities, or contain host and transport implementations.
+
+Its `Host` contract exposes only desktop-session capabilities: surface and
+pointer state, publicly served values, and unrestricted server-side Fetch. It
+does not expose system-wide Program or Process discovery.
+
+A Client may traverse `Process.parent()` through any number of ancestors in
+its own Program. The first parent outside that Program is structurally hidden
+and returned as `null`; no cross-Program Process handle enters the client. If
+client code fabricates or otherwise obtains an unauthorized handle, the system
+responds exactly as it does for a nonexistent Process.
+
+Its JavaScript entry point adapts the iframe boundary to these contracts. The
+SDK owns callbacks, waits, queues, and their cleanup; the boundary owns only
+the forwarding registrations requested by the SDK.
+
+`Current` combines navigation into the executing Client's Process with its
+inbound subscription 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
+the executing Client, while complete Process exit remains available only
+through `current.process()`.
+
+`server.ask()` does not route a question before the current Server incarnation
+is ready. The Client SDK owns one deadline across readiness and the answer;
+absence or incarnation loss rejects without turning the boundary into a waiter.
+
+The package provides two contextual values rather than constructors:
+
+```ts
+import { host, current } from "@phreshos/client"
+```
+
+The current Client's inbound Channel is composed directly into `current`. It
+exposes `subscribe()`, `waitFor()`, `events()`, and `observe()` for events
+addressed to this Client. It has no outbound, existence, readiness, or
+lifecycle operations; those belong to `current.server`, `current.stop()`, or an
+explicit Endpoint handle.
+
+Messages sent by an Endpoint in the same Program contain that real Endpoint in
+`from`. If the sender belongs to another Program, `from` is `null`; the foreign
+identity is removed by the server host before the message reaches the desktop.
+The same rule applies to Client-visible traffic destinations.
+
+Client-visible Program handles can operate only within their own Program.
+They deliberately omit `install()` and `fork()`, and their storage areas never
+expose host filesystem paths. Client Window handles add synchronous
+`localMove()` and `localResize()` for representation-local gestures.

package/dist/channel.d.ts

@@ -0,0 +1,8 @@
+import type { Channel as CoreChannel, ChannelCapture as CoreChannelCapture, ChannelEvents as CoreChannelEvents, ChannelMessage as CoreChannelMessage } from "@phreshos/core";
+import { type Endpoint } from "./domain.js";
+export type ChannelMessage<Payload = unknown> = CoreChannelMessage<Payload, Endpoint | null>;
+export type ChannelEvents<Events extends object> = CoreChannelEvents<Events, Endpoint | null>;
+export type ChannelCapture<Events extends object = {}> = CoreChannelCapture<Events, Endpoint | null>;
+export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint | null> {
+}
+export declare const channel: Channel;

package/dist/channel.js

@@ -0,0 +1,16 @@
+import { visibleEndpoint } from "./domain.js";
+import Events from "./events.js";
+import wire from "./wire.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));
+        }));
+    }
+}
+function message(value) {
+    const raw = value;
+    return { from: visibleEndpoint(raw.from), payload: raw.payload };
+}
+export const channel = new ClientChannel();

package/dist/content.d.ts

@@ -0,0 +1,7 @@
+export type ContentBody = Blob | ReadableStream<Uint8Array>;
+/** Converts one authored value into the browser body and metadata used by storage and serving. */
+export declare function content(value: unknown): {
+    body: ContentBody;
+    extension: string;
+    type: string;
+};

package/dist/content.js

@@ -0,0 +1,51 @@
+/** Converts one authored value into the browser body and metadata used by storage and serving. */
+export function content(value) {
+    const binary = "application/octet-stream";
+    if (typeof File !== "undefined" && value instanceof File) {
+        const type = value.type || binary;
+        return { body: value, extension: extension(value.name, type), type };
+    }
+    if (value instanceof Blob) {
+        const type = value.type || binary;
+        return { body: value, extension: extension("", type), type };
+    }
+    if (value instanceof ReadableStream)
+        return { body: value, extension: "bin", type: binary };
+    if (typeof value === "string")
+        return { body: new Blob([value]), extension: "txt", type: "text/plain" };
+    if (value instanceof ArrayBuffer)
+        return { body: new Blob([value]), extension: "bin", type: binary };
+    if (ArrayBuffer.isView(value)) {
+        const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        return { body: new Blob([bytes.slice()]), extension: "bin", type: binary };
+    }
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        throw new Error("This value cannot be written as JSON");
+    return { body: new Blob([json]), extension: "json", type: "application/json" };
+}
+const extensions = {
+    "application/gzip": "gz",
+    "application/javascript": "js",
+    "application/json": "json",
+    "application/pdf": "pdf",
+    "application/wasm": "wasm",
+    "application/zip": "zip",
+    "audio/mpeg": "mp3",
+    "image/gif": "gif",
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "image/svg+xml": "svg",
+    "image/webp": "webp",
+    "text/css": "css",
+    "text/csv": "csv",
+    "text/html": "html",
+    "text/javascript": "js",
+    "text/plain": "txt",
+    "video/mp4": "mp4"
+};
+function extension(name, type) {
+    return name.match(/\.([A-Za-z0-9]+)$/)?.[1]?.toLowerCase()
+        ?? extensions[type.split(";", 1)[0].toLowerCase()]
+        ?? "bin";
+}

package/dist/current.d.ts

@@ -0,0 +1,20 @@
+import type { Askable, Channel as CoreChannel, Publishable } from "@phreshos/core";
+import { type Process, type Program, type Endpoint, type Window } from "./domain.js";
+/** The paired Server as addressed from the currently executing Client. */
+export interface CurrentServer extends Publishable, Askable {
+    exists(): Promise<boolean>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    waitReady(timeout?: number): Promise<void>;
+}
+/** Current Client context: its inbound Channel, owner hierarchy, and paired Server. */
+export interface Current<Events extends object = {}> extends CoreChannel<Events, Endpoint | null> {
+    readonly server: CurrentServer;
+    process(): Promise<Process>;
+    parent(): Promise<Process | null>;
+    program(): Promise<Program>;
+    window(): Promise<Window>;
+    option(name: string): Promise<string | undefined>;
+    stop(): Promise<void>;
+}
+export declare const current: Current;

package/dist/current.js

@@ -0,0 +1,58 @@
+import { channel } from "./channel.js";
+import Deadline from "./deadline.js";
+import { process, program } from "./domain.js";
+import wire from "./wire.js";
+class PairedServer {
+    publish(event, payload) { wire.send("end-end", event, payload); }
+    async ask(event, payload) {
+        return this.askWithin(undefined, event, payload);
+    }
+    timeout(milliseconds) {
+        return { ask: (event, payload) => this.askWithin(milliseconds, event, payload) };
+    }
+    async exists() {
+        const answer = await wire.request(["exists", "server"]);
+        return answer[0];
+    }
+    async start() { await wire.request(["start-endpoint", undefined, "server"]); }
+    async stop() { await wire.request(["stop-endpoint", undefined, "server"]); }
+    async waitReady(timeout) { await wire.request(["wait-ready"], timeout); }
+    async askWithin(timeout, event, payload) {
+        const deadline = new Deadline(timeout);
+        await wire.requestWithin(["wait-ready", null, true], deadline);
+        return await wire.askServerWithin(event, payload, deadline);
+    }
+}
+class ClientCurrent {
+    server = new PairedServer();
+    constructor() {
+        bindChannel(this, channel);
+    }
+    async process() {
+        const answer = await wire.request(["process"]);
+        return process(answer[0]);
+    }
+    async parent() {
+        const answer = await wire.request(["parent"]);
+        return answer[0] ? process(answer[0]) : null;
+    }
+    async program() {
+        const answer = await wire.request(["program"]);
+        return program(answer[0]);
+    }
+    async window() { return (await this.process()).client.window(); }
+    async option(name) {
+        const answer = await wire.request(["option", undefined, name]);
+        return answer[0];
+    }
+    async stop() { await wire.request(["stop-current"]); }
+}
+function bindChannel(target, source) {
+    Object.assign(target, {
+        subscribe: source.subscribe.bind(source),
+        waitFor: source.waitFor.bind(source),
+        events: source.events.bind(source),
+        observe: source.observe.bind(source)
+    });
+}
+export const current = new ClientCurrent();

package/dist/deadline.d.ts

@@ -0,0 +1,7 @@
+/** One SDK-owned deadline shared by every stage of an asynchronous operation. */
+export default class Deadline {
+    readonly milliseconds: number;
+    private readonly expiresAt;
+    constructor(milliseconds?: number);
+    remaining(): number;
+}

package/dist/deadline.js

@@ -0,0 +1,13 @@
+import { defaultTimeout } from "./events.js";
+/** One SDK-owned deadline shared by every stage of an asynchronous operation. */
+export default class Deadline {
+    milliseconds;
+    expiresAt;
+    constructor(milliseconds = defaultTimeout) {
+        this.milliseconds = milliseconds;
+        this.expiresAt = Date.now() + milliseconds;
+    }
+    remaining() {
+        return Math.max(0, this.expiresAt - Date.now());
+    }
+}

package/dist/domain.d.ts

@@ -0,0 +1,93 @@
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, Window as CoreWindow, 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 ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type EndpointDeclaration, type Exit, type Launch, type Position, type ServerTraffic as CoreServerTraffic, type Size, type TrafficMessage as CoreTrafficMessage, type TrafficCapture as CoreTrafficCapture, type TrafficEvents as CoreTrafficEvents } from "@phreshos/core";
+import Events from "./events.js";
+export interface ProgramRecord {
+    identity: string;
+    installed?: boolean;
+    name: string;
+    version: string | null;
+    description: string | null;
+    icons?: boolean;
+    server: EndpointDeclaration | null;
+    client: ClientDeclaration | null;
+}
+export interface ProcessRecord {
+    identity: string;
+    name: string | null;
+    program: ProgramRecord;
+    options: Record<string, string>;
+    startedAt: string | Date;
+    server: Record<string, never> | null;
+    client: Record<string, never> | null;
+}
+export interface EndpointReference {
+    kind: "server" | "client";
+    process: ProcessRecord;
+}
+export type Program<Events extends object = {}> = Omit<CoreProgram<Events>, "processes" | "getProcess" | "createProcess"> & {
+    processes(): Promise<Process[]>;
+    getProcess(identityOrName: string): Promise<Process | null>;
+    createProcess(launch?: Launch): Promise<Process>;
+};
+export type Process<Events extends object = {}> = Omit<CoreProcess<Events>, "server" | "client" | "program" | "parent"> & {
+    readonly server: Server;
+    readonly client: Client;
+    program(): Program;
+    parent(): Promise<Process | null>;
+};
+export type TrafficMessage<Payload = unknown> = CoreTrafficMessage<Payload, Endpoint | null>;
+export type TrafficEvents<Events extends object> = CoreTrafficEvents<Events, Endpoint | null>;
+export type TrafficCapture<Events extends object = {}> = CoreTrafficCapture<Events, Endpoint | null>;
+export type AskMessage<Payload = unknown> = CoreAskMessage<Payload, Server | null>;
+export type AskCapture<Payload = unknown> = CoreAskCapture<Payload, Server | null>;
+export type AskObserver<Payload = unknown> = CoreAskObserver<Payload, Server | null>;
+export type AnswerMessage<Result = unknown> = CoreAnswerMessage<Result, Endpoint | null>;
+export type AnswerCapture<Result = unknown> = CoreAnswerCapture<Result, Endpoint | null>;
+export type AnswerObserver<Result = unknown> = CoreAnswerObserver<Result, Endpoint | null>;
+export type EndpointTraffic<Events extends object = {}> = CoreEndpointTraffic<Events, Endpoint | null, Server | null>;
+export type ServerTraffic<Events extends object = {}> = CoreServerTraffic<Events, Endpoint | null, Server | null>;
+export type ClientTraffic<Events extends object = {}> = CoreClientTraffic<Events, Endpoint | null, Server | null>;
+export type Endpoint<Events extends object = {}> = Omit<CoreEndpoint<Events>, "process" | "traffic"> & {
+    readonly traffic: EndpointTraffic<Events>;
+    process(): Process;
+};
+export type Server<Events extends object = {}> = Omit<CoreServer<Events>, "process" | "traffic"> & Endpoint<Events> & {
+    readonly traffic: ServerTraffic<Events>;
+    process(): Process;
+};
+export type Client<Events extends object = {}> = Omit<CoreClient<Events>, "process" | "traffic" | "window"> & Endpoint<Events> & {
+    readonly traffic: ClientTraffic<Events>;
+    process(): Process;
+    window(): Promise<Window>;
+};
+export type Window<Events extends object = {}> = Omit<CoreWindow<Events>, "client"> & {
+    client(): Client;
+    localMove(position: Position): void;
+    localResize(size: Size): void;
+};
+export declare function scoped(route: string, subject: string | null, convert: (event: string, values: unknown[]) => unknown): 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;
+export declare function program(record: ProgramRecord): Program;
+export declare function process(record: ProcessRecord): Process;
+export declare function endpoint(reference: EndpointReference | undefined): Endpoint;
+/** Resolves only endpoint identities intentionally visible to this Client. */
+export declare function visibleEndpoint(reference: EndpointReference | null | undefined): Endpoint | null;
+export declare const Program: {
+    new <Events extends object = {}>(): Program<Events>;
+};
+export declare const Process: {
+    new <Events extends object = {}>(): Process<Events>;
+};
+export declare const Endpoint: {
+    new <Events extends object = {}>(): Endpoint<Events>;
+};
+export declare const Server: {
+    new <Events extends object = {}>(): Server<Events>;
+};
+export declare const Client: {
+    new <Events extends object = {}>(): Client<Events>;
+};
+export declare const Window: {
+    new <Events extends object = {}>(): Window<Events>;
+};

package/dist/domain.js

@@ -0,0 +1,285 @@
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, Window as CoreWindow } from "@phreshos/core";
+import Events from "./events.js";
+import Deadline from "./deadline.js";
+import { area, sql, store } from "./storage.js";
+import wire from "./wire.js";
+const ProgramBase = CoreProgram;
+const ProcessBase = CoreProcess;
+const ServerBase = CoreServer;
+const ClientBase = CoreClient;
+const WindowBase = CoreWindow;
+class ProgramHandle extends ProgramBase {
+    identity;
+    name;
+    version;
+    description;
+    server;
+    client;
+    data = area("data");
+    cache = area("cache");
+    store = store();
+    logs = sql("logs");
+    database = sql("database");
+    constructor(record) {
+        super();
+        this.identity = record.identity;
+        this.name = record.name;
+        this.version = record.version;
+        this.description = record.description;
+        this.server = record.server;
+        this.client = record.client;
+        bindEvents(this, scoped("host-end", record.identity, programEvent));
+    }
+    async processes() {
+        const answer = await wire.request(["processes"]);
+        return answer[0].map(process);
+    }
+    async getProcess(identityOrName) {
+        const answer = await wire.request(["program-process", undefined, identityOrName]);
+        return answer[0] ? process(answer[0]) : null;
+    }
+    async createProcess(launch = {}) {
+        const answer = await wire.request(["create-process", undefined, launch]);
+        return process(answer[0]);
+    }
+    async apiDocs() {
+        const answer = await wire.request(["api-docs"]);
+        return answer[0];
+    }
+    async installed() {
+        const answer = await wire.request(["installed"]);
+        return answer[0];
+    }
+    async uninstall(everything = false) { await wire.request(["uninstall", undefined, everything]); }
+    async forget() { await wire.request(["forget"]); }
+    async exitAll() {
+        const answer = await wire.request(["exit-all"]);
+        return answer[0];
+    }
+}
+class ProcessHandle extends ProcessBase {
+    identity;
+    name;
+    startedAt;
+    server;
+    client;
+    ownerProgram;
+    options;
+    constructor(record) {
+        super();
+        this.identity = record.identity;
+        this.name = record.name;
+        this.startedAt = new Date(record.startedAt);
+        this.ownerProgram = program(record.program);
+        this.options = record.options;
+        this.server = new ServerHandle(this);
+        this.client = new ClientHandle(this);
+        bindEvents(this, scoped("process-host", record.identity, processEvent));
+    }
+    program() { return this.ownerProgram; }
+    async parent() {
+        const answer = await wire.request(["parent", this.identity]);
+        return answer[0] ? process(answer[0]) : null;
+    }
+    async option(name) {
+        if (name in this.options)
+            return this.options[name];
+        const answer = await wire.request(["option", this.identity, name]);
+        return answer[0];
+    }
+    async exit() { await wire.request(["exit", this.identity]); }
+    async exited() {
+        const answer = await wire.request(["exited", this.identity]);
+        return answer[0];
+    }
+}
+class TrafficHandle extends Events {
+    owner;
+    kind;
+    constructor(owner, kind) {
+        super((event, listener, impossible) => wire.observe(owner.identity, kind, "publish", event, value => listener(trafficMessage(value)), impossible), observer => wire.observe(owner.identity, kind, "publish", null, (event, value) => {
+            if (typeof event === "string")
+                observer(event, trafficMessage(value));
+        }));
+        this.owner = owner;
+        this.kind = kind;
+    }
+    observeAsks(observer) {
+        return wire.observe(this.owner.identity, this.kind, "ask", null, (event, questionId, value) => {
+            if (typeof event !== "string" || typeof questionId !== "string")
+                return;
+            observer({ event, questionId, message: trafficMessage(value) });
+        });
+    }
+}
+class ServerTrafficHandle extends TrafficHandle {
+    observeAnswers(observer) {
+        return wire.observe(this.owner.identity, "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 } });
+        });
+    }
+}
+class ServerHandle extends ServerBase {
+    owner;
+    traffic;
+    constructor(owner) {
+        super();
+        this.owner = owner;
+        this.traffic = new ServerTrafficHandle(owner, "server");
+    }
+    process() { return this.owner; }
+    publish(event, payload) { wire.send("end-host", "send", this.owner.identity, "server", event, payload); }
+    async exists() {
+        const answer = await wire.request(["exists", "server", this.owner.identity]);
+        return answer[0];
+    }
+    async start() { await wire.request(["start-endpoint", this.owner.identity, "server"]); }
+    async stop() { await wire.request(["stop-endpoint", this.owner.identity, "server"]); }
+    async waitReady(timeout) { await wire.request(["wait-ready", this.owner.identity], timeout); }
+    async ask(event, payload) {
+        return this.askWithin(undefined, event, payload);
+    }
+    timeout(milliseconds) {
+        return { ask: (event, payload) => this.askWithin(milliseconds, event, payload) };
+    }
+    async askWithin(timeout, event, payload) {
+        const deadline = new Deadline(timeout);
+        await wire.requestWithin(["wait-ready", this.owner.identity, true], deadline);
+        const source = await wire.identity;
+        const address = `client:${source}:${crypto.randomUUID()}`;
+        const questionId = crypto.randomUUID();
+        const waiting = wire.expectWithin(address, deadline);
+        wire.send("end-host", "ask", this.owner.identity, "server", address, questionId, event, payload);
+        try {
+            return await waiting;
+        }
+        finally {
+            wire.forget(address);
+        }
+    }
+}
+class ClientHandle extends ClientBase {
+    owner;
+    traffic;
+    constructor(owner) {
+        super();
+        this.owner = owner;
+        this.traffic = new TrafficHandle(owner, "client");
+    }
+    process() { return this.owner; }
+    publish(event, payload) { wire.send("end-host", "send", this.owner.identity, "client", event, payload); }
+    async exists() {
+        const answer = await wire.request(["exists", "client", this.owner.identity]);
+        return answer[0];
+    }
+    async start(overrides = {}) { await wire.request(["start-endpoint", this.owner.identity, "client", overrides]); }
+    async stop() { await wire.request(["stop-endpoint", this.owner.identity, "client"]); }
+    async window() {
+        await wire.request(["window", this.owner.identity]);
+        return new WindowHandle(this);
+    }
+}
+class WindowHandle extends WindowBase {
+    owner;
+    constructor(owner) {
+        super();
+        this.owner = owner;
+        bindEvents(this, scoped("host-end", owner.process().identity, (_event, values) => values[0]));
+    }
+    client() { return this.owner; }
+    async state() {
+        const answer = await wire.request(["window", this.owner.process().identity]);
+        return answer[0];
+    }
+    async title() { return (await this.state()).title; }
+    async position() { return (await this.state()).position; }
+    async size() { return (await this.state()).size; }
+    async minimized() { return (await this.state()).minimized; }
+    async front() { return (await this.state()).front; }
+    async layer() { return (await this.state()).layer; }
+    async location() { return (await this.state()).location; }
+    async move(position) { await wire.request(["move", this.owner.process().identity, position]); }
+    localMove(position) { wire.send("end-host", "localMove", this.owner.process().identity, position); }
+    async resize(size) { await wire.request(["resize", this.owner.process().identity, size]); }
+    localResize(size) { wire.send("end-host", "localResize", this.owner.process().identity, size); }
+    async minimize(minimized = true) { await wire.request(["minimize", this.owner.process().identity, minimized]); }
+    async changeTitle(title) { await wire.request(["changeTitle", this.owner.process().identity, title]); }
+    async raise() { await wire.request(["raise", this.owner.process().identity]); }
+}
+export function scoped(route, subject, convert) {
+    return new Events((event, listener, impossible) => wire.on(route, event, (...values) => {
+        const message = unscoped(subject, values);
+        if (message)
+            listener(convert(event, message));
+    }, subject, impossible), observer => wire.onAll(route, (event, ...values) => {
+        if (typeof event !== "string")
+            return;
+        const message = unscoped(subject, values);
+        if (message)
+            observer(event, convert(event, message));
+    }, subject));
+}
+function unscoped(subject, values) {
+    if (subject === null)
+        return values;
+    return values[0] === subject ? values.slice(1) : null;
+}
+function programEvent(event, values) {
+    if (event === "serverStart" || event === "clientStart" || event === "clientStop" || event === "processCreate")
+        return process(values[0]);
+    if (event === "serverStop")
+        return { process: process(values[0]), code: numberOrNull(values[1]), signal: stringOrNull(values[2]) };
+    if (event === "processExit")
+        return { process: process(values[0]), ...exit(values[1], values[2]) };
+    if (event === "uninstall")
+        return { everythingRemoved: values[0] === true };
+    return undefined;
+}
+function processEvent(event, values) {
+    if (event === "serverStop")
+        return { code: numberOrNull(values[0]), signal: stringOrNull(values[1]) };
+    if (event === "exit")
+        return exit(values[0], values[1]);
+    return undefined;
+}
+export function exit(code, signal) {
+    const namedSignal = stringOrNull(signal);
+    return { status: namedSignal === null ? "exited" : "signaled", code: numberOrNull(code), signal: namedSignal };
+}
+function numberOrNull(value) { return typeof value === "number" ? value : null; }
+function stringOrNull(value) { return typeof value === "string" ? value : null; }
+export function trafficMessage(value) {
+    const raw = value;
+    return { to: visibleEndpoint(raw.to), payload: raw.payload };
+}
+export function bindEvents(target, events) {
+    Object.assign(target, {
+        subscribe: events.subscribe.bind(events),
+        waitFor: events.waitFor.bind(events),
+        events: events.events.bind(events),
+        observe: events.observe.bind(events)
+    });
+}
+export function program(record) { return new ProgramHandle(record); }
+export function process(record) { return new ProcessHandle(record); }
+export function endpoint(reference) {
+    if (!reference)
+        throw new Error("The boundary returned an invalid Endpoint reference");
+    const owner = new ProcessHandle(reference.process);
+    return reference.kind === "server" ? owner.server : owner.client;
+}
+/** Resolves only endpoint identities intentionally visible to this Client. */
+export function visibleEndpoint(reference) {
+    if (reference === null)
+        return null;
+    return endpoint(reference);
+}
+export const Program = CoreProgram;
+export const Process = CoreProcess;
+export const Endpoint = CoreEndpoint;
+export const Server = CoreServer;
+export const Client = CoreClient;
+export const Window = CoreWindow;

package/dist/events.d.ts

@@ -0,0 +1,16 @@
+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;
+/** 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);
+    subscribe(event: string, subscriber: Listener): Cleanup;
+    waitFor(event: string, timeout?: number): Promise<unknown>;
+    events(event: string, options?: EventOptions): AsyncIterableIterator<unknown>;
+    observe(observer: (capture: Capture<string, unknown>) => unknown): Cleanup;
+}
+export {};