@phreshos/client 0.1.0 → 0.1.2

package/dist/domain.js

@@ -1,38 +1,49 @@
-import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, Window as CoreWindow } from "@phreshos/core";
+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 Deadline from "./deadline.js";
+import HandleRegistry from "./handle-registry.js";
 import { area, sql, store } from "./storage.js";
 import wire from "./wire.js";
+const handles = new HandleRegistry();
 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;
+    reference;
     data = area("data");
     cache = area("cache");
     store = store();
     logs = sql("logs");
     database = sql("database");
+    record;
     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));
+        this.reference = record.reference;
+        this.record = record;
+        bindEvents(this, scoped("host-end", record.reference, programEvent));
+    }
+    get name() { return this.record.name; }
+    get version() { return this.record.version; }
+    get description() { return this.record.description; }
+    get server() { return this.record.server; }
+    get client() { return this.record.client; }
+    update(record) {
+        if (record.reference !== this.reference)
+            throw new Error("A Program handle cannot become another Program");
+        this.record = record;
     }
     async processes() {
         const answer = await wire.request(["processes"]);
-        return answer[0].map(process);
+        return answer[0].map(record => process(record));
+    }
+    async firstProcess() {
+        return chronological(await this.processes())[0] ?? null;
+    }
+    async lastProcess() {
+        return chronological(await this.processes()).at(-1) ?? null;
     }
     async getProcess(identityOrName) {
         const answer = await wire.request(["program-process", undefined, identityOrName]);
@@ -46,6 +57,10 @@ class ProgramHandle extends ProgramBase {
         const answer = await wire.request(["api-docs"]);
         return answer[0];
     }
+    async icon(size = "medium") {
+        const answer = await wire.request(["icon", size]);
+        return new Blob([Uint8Array.from(answer[0])], { type: "image/png" });
+    }
     async installed() {
         const answer = await wire.request(["installed"]);
         return answer[0];
@@ -57,64 +72,70 @@ class ProgramHandle extends ProgramBase {
         return answer[0];
     }
 }
+function chronological(processes) {
+    return processes.sort((left, right) => left.startedAt.getTime() - right.startedAt.getTime());
+}
 class ProcessHandle extends ProcessBase {
     identity;
+    reference;
     name;
     startedAt;
     server;
     client;
     ownerProgram;
     options;
-    constructor(record) {
+    constructor(record, endpoints = {}) {
         super();
         this.identity = record.identity;
+        this.reference = record.reference;
         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));
+        this.server = endpointHandle(this, "server", endpoints.server);
+        this.client = endpointHandle(this, "client", endpoints.client);
+        bindEvents(this, scoped("process-host", record.reference, processEvent));
     }
     program() { return this.ownerProgram; }
+    get address() { return { identity: this.identity, reference: this.reference }; }
     async parent() {
-        const answer = await wire.request(["parent", this.identity]);
+        const answer = await wire.request(["parent", this.address]);
         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]);
+        const answer = await wire.request(["option", this.address, name]);
         return answer[0];
     }
-    async exit() { await wire.request(["exit", this.identity]); }
+    async exit() { await wire.request(["exit", this.address]); }
     async exited() {
-        const answer = await wire.request(["exited", this.identity]);
+        const answer = await wire.request(["exited", this.address]);
         return answer[0];
     }
 }
-class TrafficHandle extends Events {
-    owner;
+export class TrafficHandle extends Events {
+    target;
     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) => {
+    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) => {
             if (typeof event === "string")
                 observer(event, trafficMessage(value));
         }));
-        this.owner = owner;
+        this.target = target;
         this.kind = kind;
     }
     observeAsks(observer) {
-        return wire.observe(this.owner.identity, this.kind, "ask", null, (event, questionId, value) => {
+        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) });
         });
     }
 }
-class ServerTrafficHandle extends TrafficHandle {
+export class ServerTrafficHandle extends TrafficHandle {
     observeAnswers(observer) {
-        return wire.observe(this.owner.identity, "server", "answer", null, (event, questionId, value) => {
+        return wire.observe(this.target, "server", "answer", null, (event, questionId, value) => {
             if (typeof event !== "string" || typeof questionId !== "string")
                 return;
             const raw = value;
@@ -128,31 +149,32 @@ class ServerHandle extends ServerBase {
     constructor(owner) {
         super();
         this.owner = owner;
-        this.traffic = new ServerTrafficHandle(owner, "server");
+        this.traffic = new ServerTrafficHandle(owner.address, "server");
+        bindEvents(this, endpointEvents(owner.address, "server"));
     }
-    process() { return this.owner; }
-    publish(event, payload) { wire.send("end-host", "send", this.owner.identity, "server", event, payload); }
+    async process() { return this.owner; }
+    publish(event, payload = undefined) { wire.send("end-host", "send", this.owner.address, "server", event, payload); }
     async exists() {
-        const answer = await wire.request(["exists", "server", this.owner.identity]);
+        const answer = await wire.request(["exists", "server", this.owner.address]);
         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) {
+    async start() { await wire.request(["start-endpoint", this.owner.address, "server"]); }
+    async stop() { await wire.request(["stop-endpoint", 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);
     }
     timeout(milliseconds) {
-        return { ask: (event, payload) => this.askWithin(milliseconds, event, payload) };
+        return { ask: (event, payload = undefined) => 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()}`;
+        await wire.requestWithin(["wait-ready", this.owner.address, true], deadline);
+        const source = await wire.identity();
+        const address = `client:${source.process}:${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);
+        wire.send("end-host", "ask", this.owner.address, "server", address, questionId, event, payload);
         try {
             return await waiting;
         }
@@ -164,34 +186,33 @@ class ServerHandle extends ServerBase {
 class ClientHandle extends ClientBase {
     owner;
     traffic;
+    window;
     constructor(owner) {
         super();
         this.owner = owner;
-        this.traffic = new TrafficHandle(owner, "client");
+        this.traffic = new TrafficHandle(owner.address, "client");
+        this.window = window(async () => owner.address);
+        bindEvents(this, endpointEvents(owner.address, "client"));
     }
-    process() { return this.owner; }
-    publish(event, payload) { wire.send("end-host", "send", this.owner.identity, "client", event, payload); }
+    async process() { return this.owner; }
+    publish(event, payload = undefined) { wire.send("end-host", "send", this.owner.address, "client", event, payload); }
     async exists() {
-        const answer = await wire.request(["exists", "client", this.owner.identity]);
+        const answer = await wire.request(["exists", "client", this.owner.address]);
         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);
-    }
+    async start(overrides = {}) { await wire.request(["start-endpoint", this.owner.address, "client", overrides]); }
+    async stop() { await wire.request(["stop-endpoint", this.owner.address, "client"]); }
 }
-class WindowHandle extends WindowBase {
-    owner;
-    constructor(owner) {
-        super();
-        this.owner = owner;
-        bindEvents(this, scoped("host-end", owner.process().identity, (_event, values) => values[0]));
+class WindowHandle extends Events {
+    target;
+    surface;
+    constructor(target) {
+        super(...deferredScoped("host-end", target, (_event, values) => values[0]));
+        this.target = target;
+        this.surface = new WindowSurfaceHandle(target);
     }
-    client() { return this.owner; }
     async state() {
-        const answer = await wire.request(["window", this.owner.process().identity]);
+        const answer = await wire.request(["window", await this.target()]);
         return answer[0];
     }
     async title() { return (await this.state()).title; }
@@ -201,13 +222,64 @@ class WindowHandle extends WindowBase {
     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]); }
+    async move(position) { await wire.request(["move", await this.target(), position]); }
+    async localMove(position) { await wire.request(["localMove", await this.target(), position]); }
+    async resize(size) { await wire.request(["resize", await this.target(), size]); }
+    async localResize(size) { await wire.request(["localResize", await this.target(), size]); }
+    async minimize(minimized = true) { await wire.request(["minimize", await this.target(), minimized]); }
+    async changeTitle(title) { await wire.request(["changeTitle", await this.target(), title]); }
+    async raise() { await wire.request(["raise", await this.target()]); }
+}
+class WindowSurfaceHandle {
+    target;
+    constructor(target) {
+        this.target = target;
+    }
+    async set(settings = {}) { await wire.request(["surfaceSet", await this.target(), settings]); }
+    async remove() { await wire.request(["surfaceRemove", await this.target()]); }
+}
+function deferredScoped(route, target, convert) {
+    return [
+        (event, listener, impossible) => {
+            if (!windowEvent(event)) {
+                impossible?.(new Error(`A Window has no "${event}" event`));
+                return () => undefined;
+            }
+            return deferred(target, subject => wire.on(route, event, (...values) => {
+                const message = unscoped(subject, values);
+                if (message)
+                    listener(convert(event, message));
+            }, subject, impossible), impossible);
+        },
+        observer => 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))
+    ];
+}
+function windowEvent(event) {
+    return event === "move" || event === "resize" || event === "minimize" || event === "changeTitle" || event === "front";
+}
+function deferred(target, register, impossible) {
+    let active = true;
+    let stop = () => undefined;
+    void target().then(address => {
+        if (active)
+            stop = register(address.reference);
+    }, error => {
+        const failure = error instanceof Error ? error : new Error(String(error));
+        if (active && impossible)
+            impossible(failure);
+        else if (active)
+            queueMicrotask(() => { throw failure; });
+    });
+    return () => {
+        active = false;
+        stop();
+    };
 }
 export function scoped(route, subject, convert) {
     return new Events((event, listener, impossible) => wire.on(route, event, (...values) => {
@@ -222,16 +294,23 @@ export function scoped(route, subject, convert) {
             observer(event, convert(event, message));
     }, subject));
 }
+/** 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) => {
+        if (typeof event === "string")
+            observer(event, payload);
+    }));
+}
 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")
+    if (event === "endpointStart" || event === "endpointStop")
+        return lifecycleEndpoint(values[0], values[1]);
+    if (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")
@@ -239,12 +318,20 @@ function programEvent(event, values) {
     return undefined;
 }
 function processEvent(event, values) {
-    if (event === "serverStop")
-        return { code: numberOrNull(values[0]), signal: stringOrNull(values[1]) };
+    if (event === "endpointStart" || event === "endpointStop")
+        return lifecycleEndpoint(values[0], values[1]);
     if (event === "exit")
         return exit(values[0], values[1]);
     return undefined;
 }
+function lifecycleEndpoint(record, kind) {
+    const owner = process(record);
+    if (kind === "server")
+        return owner.server;
+    if (kind === "client")
+        return owner.client;
+    throw new Error("The host returned an invalid Endpoint lifecycle event");
+}
 export function exit(code, signal) {
     const namedSignal = stringOrNull(signal);
     return { status: namedSignal === null ? "exited" : "signaled", code: numberOrNull(code), signal: namedSignal };
@@ -263,23 +350,42 @@ export function bindEvents(target, events) {
         observe: events.observe.bind(events)
     });
 }
-export function program(record) { return new ProgramHandle(record); }
-export function process(record) { return new ProcessHandle(record); }
+export function program(record) {
+    const handle = handles.obtain(`program:${record.reference}`, () => new ProgramHandle(record));
+    handle.update(record);
+    return handle;
+}
+export function process(record, endpoints = {}) {
+    return handles.obtain(`process:${record.reference}`, () => new ProcessHandle(record, endpoints));
+}
 export function endpoint(reference) {
     if (!reference)
         throw new Error("The boundary returned an invalid Endpoint reference");
-    const owner = new ProcessHandle(reference.process);
+    const owner = process(reference.process);
     return reference.kind === "server" ? owner.server : owner.client;
 }
+export function claimEndpoint(reference, kind, endpoint) {
+    return handles.adopt(`endpoint:${reference}:${kind}`, endpoint);
+}
+function endpointHandle(owner, kind, preferred) {
+    return handles.obtain(`endpoint:${owner.reference}:${kind}`, () => preferred ?? (kind === "server" ? new ServerHandle(owner) : new ClientHandle(owner)));
+}
+export function window(target) {
+    return new WindowHandle(target);
+}
 /** Resolves only endpoint identities intentionally visible to this Client. */
 export function visibleEndpoint(reference) {
     if (reference === null)
         return null;
     return endpoint(reference);
 }
+/** Runtime constructor shared by all client-visible Program handles. */
 export const Program = CoreProgram;
+/** Runtime constructor shared by all client-visible Process handles. */
 export const Process = CoreProcess;
+/** Runtime constructor shared by all client-visible Endpoint handles. */
 export const Endpoint = CoreEndpoint;
+/** Runtime constructor shared by all client-visible Server handles. */
 export const Server = CoreServer;
+/** Runtime constructor shared by all client-visible Client handles. */
 export const Client = CoreClient;
-export const Window = CoreWindow;

package/dist/handle-registry.d.ts

@@ -0,0 +1,7 @@
+/** Weak canonical references for system-backed domain handles in this SDK realm. */
+export default class HandleRegistry {
+    private readonly handles;
+    private readonly released;
+    obtain<Value extends object>(key: string, create: () => Value): Value;
+    adopt<Value extends object>(key: string, value: Value): Value;
+}

package/dist/handle-registry.js

@@ -0,0 +1,24 @@
+/** Weak canonical references for system-backed domain handles in this SDK realm. */
+export default class HandleRegistry {
+    handles = new Map();
+    released = new FinalizationRegistry(({ key, reference }) => {
+        if (this.handles.get(key) === reference)
+            this.handles.delete(key);
+    });
+    obtain(key, create) {
+        const existing = this.handles.get(key)?.deref();
+        if (existing)
+            return existing;
+        const value = create();
+        const reference = new WeakRef(value);
+        this.handles.set(key, reference);
+        this.released.register(value, { key, reference });
+        return value;
+    }
+    adopt(key, value) {
+        const existing = this.handles.get(key)?.deref();
+        if (existing && existing !== value)
+            throw new Error(`The canonical handle for "${key}" already exists`);
+        return existing ?? this.obtain(key, () => value);
+    }
+}

package/dist/host.d.ts

@@ -1,25 +1,20 @@
-import type { Layer, ServedFile, Subscribable } from "@phreshos/core";
-/** Pointer coordinates relative to the desktop display core. */
-export type PointerPosition = Readonly<{
-    x: number;
-    y: number;
-}>;
-/** One desktop layer's available workspace. */
-export type Surface = Readonly<{
-    width: number;
-    height: number;
-    gutter: number;
-}>;
-/** Session-local desktop events available to a Client endpoint. */
-export type HostEvents = {
-    surface: Surface;
-    pointerMove: PointerPosition;
-};
+import type { Permissions, ServedFile, 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. */
-export interface Host<Events extends object = {}> extends Subscribable<HostEvents & Events, never> {
-    pointerPosition(): Promise<PointerPosition | null>;
-    surface(layer?: Layer): Promise<Surface>;
+export interface Host {
+    /** Read-only system Theme explicitly read from and observed through the desktop host. */
+    readonly theme: Theme<ThemeProperties>;
+    /** This Client Window's asynchronous surface read and live updates. */
+    readonly surface: HostSurface;
+    /** Permission-guarded desktop pointer reads and live movement. */
+    readonly pointer: HostPointer;
+    /** Permission decisions for capabilities guarded by the desktop. */
+    readonly permissions: Permissions;
+    /** Stores one value as a publicly reachable file. */
     serve(value: unknown): Promise<ServedFile>;
+    /** Performs an unrestricted server-side fetch on behalf of this Client. */
     fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 }
+/** Desktop capabilities available to this Client. */
 export declare const host: Host;

package/dist/host.js

@@ -1,20 +1,14 @@
 import { content } from "./content.js";
-import Events from "./events.js";
+import ClientTheme from "./theme.js";
 import wire from "./wire.js";
-class ClientHost extends Events {
-    pointerListeners = 0;
-    samplePointer = (event) => wire.samplePointer(event.movementX, event.movementY);
-    constructor() {
-        super((event, listener, impossible) => this.withPointerSampling(event === "pointerMove", wire.on("host-end", event, listener, null, impossible)), observer => this.withPointerSampling(true, combine(wire.on("host-end", "surface", value => observer("surface", value)), wire.on("host-end", "pointerMove", value => observer("pointerMove", value)))));
-    }
-    async pointerPosition() {
-        const answer = await wire.request(["pointerPosition"]);
-        return answer[0];
-    }
-    async surface(layer) {
-        const answer = await wire.request(["surface", undefined, layer]);
-        return answer[0];
-    }
+import ClientPermissions from "./permissions.js";
+import ClientPointer, {} from "./pointer.js";
+import ClientSurface, {} from "./surface.js";
+class ClientHost {
+    theme = new ClientTheme();
+    surface = new ClientSurface();
+    pointer = new ClientPointer();
+    permissions = new ClientPermissions();
     async serve(value) {
         const source = content(value);
         const channel = new MessageChannel();
@@ -85,22 +79,6 @@ class ClientHost extends Events {
         });
         return response;
     }
-    withPointerSampling(sample, stop) {
-        if (!sample)
-            return stop;
-        if (this.pointerListeners++ === 0)
-            window.addEventListener("pointermove", this.samplePointer);
-        let active = true;
-        return () => {
-            if (!active)
-                return;
-            active = false;
-            stop();
-            this.pointerListeners--;
-            if (this.pointerListeners === 0)
-                window.removeEventListener("pointermove", this.samplePointer);
-        };
-    }
 }
 function requestHeaders(normalized, supplied) {
     if (!supplied)
@@ -142,8 +120,5 @@ function closeControl(signal, port, abort) {
     signal.removeEventListener("abort", abort);
     port.close();
 }
-function combine(...cleanups) {
-    return () => { for (const cleanup of cleanups)
-        cleanup(); };
-}
+/** Desktop capabilities available to this Client. */
 export const host = new ClientHost();

package/dist/main.d.ts

@@ -1,5 +1,7 @@
-export { host, type Host, type HostEvents, type PointerPosition, type Surface } from "./host.js";
+export { host, type Host } from "./host.js";
+export { type HostPointer, type PointerEvents, type PointerPosition } from "./pointer.js";
+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 { Client, Endpoint, Process, Program, Server, 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, Position, ProgramArea, ProgramEvents, ProgramProcessExit, ProgramServerStop, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, Size, Subscribable, TimedAskable, Value, WindowEvents, WindowState } 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, WindowSurfaceSettings, WindowSurfaceTransaction } from "@phreshos/core";

package/dist/main.js

@@ -1,4 +1,6 @@
 export { host } from "./host.js";
+export {} from "./pointer.js";
+export {} from "./surface.js";
 export { current } from "./current.js";
 export {} from "./channel.js";
-export { Client, Endpoint, Process, Program, Server, Window } from "./domain.js";
+export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/permissions.d.ts

@@ -0,0 +1,8 @@
+import type { PermissionDecision, PermissionName, Permissions, TimedPermissions } from "@phreshos/core";
+/** Client permission access bound to the current Process boundary. */
+export default class ClientPermissions implements Permissions {
+    granted(name: PermissionName): Promise<PermissionDecision>;
+    request(name: PermissionName): Promise<PermissionDecision>;
+    timeout(milliseconds: number): TimedPermissions;
+    private requestWithin;
+}

package/dist/permissions.js

@@ -0,0 +1,21 @@
+import wire from "./wire.js";
+const defaultPermissionTimeout = 30_000;
+/** Client permission access bound to the current Process boundary. */
+export default class ClientPermissions {
+    async granted(name) {
+        const answer = await wire.request(["permission-granted", name]);
+        return answer[0];
+    }
+    request(name) {
+        return this.requestWithin(name, defaultPermissionTimeout);
+    }
+    timeout(milliseconds) {
+        if (!Number.isFinite(milliseconds) || milliseconds < 0)
+            throw new Error("A permission timeout must be a non-negative finite number");
+        return Object.freeze({ request: (name) => this.requestWithin(name, milliseconds) });
+    }
+    async requestWithin(name, milliseconds) {
+        const answer = await wire.requestOrNull(["permission-request", name], milliseconds);
+        return answer?.[0] ?? null;
+    }
+}

package/dist/pointer.d.ts

@@ -0,0 +1,35 @@
+import type { Subscribable } from "@phreshos/core";
+import Events from "./events.js";
+/** Pointer coordinates relative to the desktop display core. */
+export type PointerPosition = Readonly<{
+    /** Horizontal coordinate in CSS pixels. */
+    x: number;
+    /** Vertical coordinate in CSS pixels. */
+    y: number;
+}>;
+/** Live pointer events visible to this Client. */
+export type PointerEvents = {
+    /** The pointer moved over the desktop display core. */
+    move: PointerPosition;
+};
+/** Permission-guarded pointer positions and future movement. */
+export interface HostPointer extends Subscribable<PointerEvents, never> {
+    /**
+     * Reads the current desktop pointer position, or `null` before one is known.
+     * Rejects unless the `pointer` permission is currently granted.
+     */
+    position(): Promise<PointerPosition | null>;
+}
+/** Client pointer access bound to the current Process boundary. */
+export default class ClientPointer extends Events {
+    private listeners;
+    private readonly sample;
+    constructor();
+    position(): Promise<Readonly<{
+        /** Horizontal coordinate in CSS pixels. */
+        x: number;
+        /** Vertical coordinate in CSS pixels. */
+        y: number;
+    }> | null>;
+    private withSampling;
+}