@phreshos/client 0.1.0

package/dist/events.js

@@ -0,0 +1,83 @@
+export const defaultTimeout = 10_000;
+/** SDK-owned waits, queues and callbacks over boundary forwarding state. */
+export default class Events {
+    listen;
+    listenAll;
+    constructor(listen, listenAll) {
+        this.listen = listen;
+        this.listenAll = listenAll;
+    }
+    subscribe(event, subscriber) {
+        return this.listen(event, subscriber);
+    }
+    waitFor(event, timeout = defaultTimeout) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let stop = () => undefined;
+            const finish = (settle) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                stop();
+                settle();
+            };
+            const timer = setTimeout(() => finish(() => reject(new Error(`Event promise timeout ${timeout}ms`))), timeout);
+            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");
+        }
+        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);
+            }
+        })();
+    }
+    observe(observer) {
+        return this.listenAll((event, message) => observer({ event, message }));
+    }
+}

package/dist/host.d.ts

@@ -0,0 +1,25 @@
+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;
+};
+/** 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>;
+    serve(value: unknown): Promise<ServedFile>;
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+export declare const host: Host;

package/dist/host.js

@@ -0,0 +1,149 @@
+import { content } from "./content.js";
+import Events from "./events.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];
+    }
+    async serve(value) {
+        const source = content(value);
+        const channel = new MessageChannel();
+        const abort = () => channel.port1.postMessage("abort");
+        try {
+            const answer = await wire.request(["serve", source.body, { extension: source.extension, type: source.type }, channel.port2], undefined, source.body instanceof ReadableStream ? [source.body, channel.port2] : [channel.port2]);
+            channel.port1.close();
+            return answer[0];
+        }
+        catch (error) {
+            abort();
+            channel.port1.close();
+            throw error;
+        }
+    }
+    async fetch(input, init) {
+        const request = new Request(input, {
+            ...init,
+            ...init?.body instanceof ReadableStream ? { duplex: "half" } : {}
+        });
+        const body = request.body;
+        const control = new MessageChannel();
+        const abort = () => control.port1.postMessage("abort");
+        if (request.signal.aborted) {
+            control.port1.close();
+            control.port2.close();
+            throw request.signal.reason;
+        }
+        request.signal.addEventListener("abort", abort, { once: true });
+        const description = {
+            body: body !== null,
+            cache: request.cache,
+            credentials: request.credentials,
+            headers: requestHeaders(request.headers, init?.headers),
+            integrity: request.integrity,
+            keepalive: request.keepalive,
+            method: request.method,
+            mode: request.mode,
+            redirect: request.redirect,
+            referrer: request.referrer,
+            referrerPolicy: request.referrerPolicy,
+            url: request.url
+        };
+        let result;
+        try {
+            const answer = await wire.request(["fetch", description, body, control.port2], undefined, body ? [body, control.port2] : [control.port2]);
+            result = answer[0];
+        }
+        catch (error) {
+            abort();
+            closeControl(request.signal, control.port1, abort);
+            throw request.signal.aborted ? request.signal.reason : error;
+        }
+        const responseBody = result.body
+            ? controlled(result.body, abort, () => closeControl(request.signal, control.port1, abort))
+            : null;
+        if (!responseBody)
+            closeControl(request.signal, control.port1, abort);
+        const response = new Response(responseBody, {
+            headers: result.headers,
+            status: result.status,
+            statusText: result.statusText
+        });
+        Object.defineProperties(response, {
+            redirected: { configurable: true, enumerable: true, value: result.redirected },
+            type: { configurable: true, enumerable: true, value: result.type },
+            url: { configurable: true, enumerable: true, value: result.url }
+        });
+        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)
+        return [...normalized.entries()];
+    const explicit = supplied instanceof Headers
+        ? [...supplied.entries()]
+        : Array.isArray(supplied)
+            ? supplied.map(([name, value]) => [name, value])
+            : Object.entries(supplied);
+    const names = new Set(explicit.map(([name]) => name.toLowerCase()));
+    return [...normalized.entries()].filter(([name]) => !names.has(name.toLowerCase())).concat(explicit);
+}
+function controlled(body, abort, close) {
+    const reader = body.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await reader.read();
+                if (next.done) {
+                    close();
+                    controller.close();
+                }
+                else
+                    controller.enqueue(next.value);
+            }
+            catch (error) {
+                close();
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            abort();
+            close();
+            await reader.cancel(reason);
+        }
+    });
+}
+function closeControl(signal, port, abort) {
+    signal.removeEventListener("abort", abort);
+    port.close();
+}
+function combine(...cleanups) {
+    return () => { for (const cleanup of cleanups)
+        cleanup(); };
+}
+export const host = new ClientHost();

package/dist/log.d.ts

@@ -0,0 +1,6 @@
+interface LogWire {
+    send(route: string, ...values: unknown[]): void;
+}
+/** Mirrors browser output through the private boundary without changing it. */
+export default function captureClientOutput(wire: LogWire): void;
+export {};

package/dist/log.js

@@ -0,0 +1,64 @@
+/** Mirrors browser output through the private boundary without changing it. */
+export default function captureClientOutput(wire) {
+    if (typeof document === "undefined")
+        return;
+    const output = console;
+    let relaying = false;
+    const relay = (kind, values) => queueMicrotask(() => {
+        if (relaying)
+            return;
+        relaying = true;
+        try {
+            wire.send("boundary", "log", kind, values.map(printable).join(" "));
+        }
+        catch { /* Output is emit-and-forget. */ }
+        finally {
+            relaying = false;
+        }
+    });
+    for (const kind of ["debug", "log", "info", "warn", "error"]) {
+        const original = output[kind].bind(console);
+        output[kind] = (...values) => {
+            original(...values);
+            relay(kind, values);
+        };
+    }
+    window.addEventListener("error", event => relay("error", [event.error ?? event.message]));
+    window.addEventListener("unhandledrejection", event => relay("error", [`Unhandled rejection: ${printable(event.reason)}`]));
+}
+function printable(value) {
+    if (typeof value === "string")
+        return value;
+    if (value instanceof Error)
+        return value.stack ?? `${value.name}: ${value.message}`;
+    if (typeof value === "undefined")
+        return "undefined";
+    if (typeof value === "bigint")
+        return `${value}n`;
+    if (typeof value === "symbol" || typeof value === "function")
+        return String(value);
+    try {
+        const seen = new WeakSet();
+        const json = JSON.stringify(value, (_key, nested) => {
+            if (typeof nested === "bigint")
+                return `${nested}n`;
+            if (nested instanceof Error)
+                return { name: nested.name, message: nested.message, stack: nested.stack };
+            if (typeof nested !== "object" || nested === null)
+                return nested;
+            if (seen.has(nested))
+                return "[Circular]";
+            seen.add(nested);
+            return nested;
+        });
+        if (json !== undefined)
+            return json;
+    }
+    catch { /* Fall through. */ }
+    try {
+        return String(value);
+    }
+    catch {
+        return "[Unprintable value]";
+    }
+}

package/dist/main.d.ts

@@ -0,0 +1,5 @@
+export { host, type Host, type HostEvents, type PointerPosition, type Surface } from "./host.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";

package/dist/main.js

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

package/dist/storage.d.ts

@@ -0,0 +1,5 @@
+import type { ProgramArea, ProgramSql, ProgramStore } from "@phreshos/core";
+/** Client-side Program storage, structurally scoped by the iframe boundary. */
+export declare function area(which: "data" | "cache"): ProgramArea;
+export declare function store(): ProgramStore;
+export declare function sql(kind: "database" | "logs"): ProgramSql;

package/dist/storage.js

@@ -0,0 +1,98 @@
+import { content } from "./content.js";
+import wire from "./wire.js";
+/** Client-side Program storage, structurally scoped by the iframe boundary. */
+export function area(which) {
+    async function ask(operation, ...values) {
+        const answer = await wire.request([which, undefined, operation, ...values]);
+        return answer[0];
+    }
+    async function transfer(operation, path, body = null) {
+        const channel = new MessageChannel();
+        const abort = () => channel.port1.postMessage("abort");
+        const close = () => channel.port1.close();
+        try {
+            const answer = await wire.request([which, undefined, operation, path, body, channel.port2], undefined, body instanceof ReadableStream ? [body, channel.port2] : [channel.port2]);
+            if (operation === "write") {
+                close();
+                return null;
+            }
+            if (!(answer[0] instanceof ReadableStream))
+                throw new Error("The storage response has no byte stream");
+            return controlled(answer[0], abort, close);
+        }
+        catch (error) {
+            abort();
+            close();
+            throw error;
+        }
+    }
+    async function stream(...path) {
+        const body = await transfer("stream", path);
+        if (!body)
+            throw new Error("The storage response has no body");
+        return body;
+    }
+    return {
+        stream,
+        async bytes(...path) { return new Uint8Array(await new Response(await stream(...path)).arrayBuffer()); },
+        async text(...path) { return new Response(await stream(...path)).text(); },
+        async json(...path) { return JSON.parse(await new Response(await stream(...path)).text()); },
+        async write(...args) {
+            if (args.length < 2)
+                throw new Error("Writing takes a file name and what to write");
+            await transfer("write", args.slice(0, -1), content(args.at(-1)).body);
+        },
+        stat: (...path) => ask("stat", ...path),
+        list: (...path) => ask("list", ...path),
+        delete: (...path) => ask("delete", ...path),
+        clear: () => ask("clear")
+    };
+}
+export function store() {
+    async function ask(operation, ...values) {
+        const answer = await wire.request(["store", undefined, operation, ...values]);
+        return answer[0];
+    }
+    return {
+        get: (key) => ask("get", key),
+        set: (key, value, ttl) => ask("set", key, value, ttl),
+        delete: (key) => ask("delete", key),
+        has: (key) => ask("has", key),
+        clear: () => ask("clear")
+    };
+}
+export function sql(kind) {
+    return {
+        async query(statement, ...rest) {
+            const text = typeof statement === "string" ? statement : statement.raw.join("?");
+            const values = typeof statement === "string" ? (Array.isArray(rest[0]) ? rest[0] : []) : rest;
+            const answer = await wire.request([kind, undefined, text, values]);
+            return answer[0];
+        }
+    };
+}
+function controlled(body, abort, close) {
+    const reader = body.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await reader.read();
+                if (next.done) {
+                    close();
+                    controller.close();
+                }
+                else
+                    controller.enqueue(next.value);
+            }
+            catch (error) {
+                close();
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            abort();
+            close();
+            await reader.cancel(reason);
+        }
+    });
+}

package/dist/wire.d.ts

@@ -0,0 +1,34 @@
+import type { Cleanup } from "@phreshos/core";
+import Deadline from "./deadline.js";
+type Handler = (...values: unknown[]) => unknown;
+type Failure = (error: Error) => void;
+type TrafficKind = "publish" | "ask" | "answer";
+/** The client endpoint's sole postMessage adapter. */
+declare class Wire {
+    private readonly parent;
+    private readonly pending;
+    private readonly subscribers;
+    private readonly every;
+    private readonly impossible;
+    private readonly boundarySubscriptions;
+    private readonly observations;
+    readonly identity: Promise<string>;
+    constructor();
+    send(route: string, ...values: unknown[]): void;
+    request(values: unknown[], timeout?: number, transfer?: Transferable[]): Promise<unknown>;
+    requestWithin(values: unknown[], deadline: Deadline, transfer?: Transferable[]): Promise<unknown>;
+    askServerWithin(event: string, payload: unknown, deadline: Deadline): Promise<unknown>;
+    private question;
+    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;
+    observe(target: string, half: "server" | "client", kind: TrafficKind, event: string | null, handler: Handler, impossible?: Failure): Cleanup;
+    samplePointer(movementX: number, movementY: number): void;
+    private register;
+    private unregister;
+    private deliver;
+    private settle;
+}
+declare const wire: Wire;
+export default wire;