@phreshos/client 0.1.31 → 0.1.33

package/dist/storage.js

@@ -1,10 +1,10 @@
 import { content } from "./content.js";
 import controlledStream from "./controlled-stream.js";
 import wire from "./wire.js";
-/** Client-side Program storage, structurally scoped by the iframe boundary. */
-export function area(which) {
+/** Client-side access to one exact Program storage area. */
+export function area(program, which) {
     async function ask(operation, ...values) {
-        const answer = await wire.request([which, undefined, operation, ...values]);
+        const answer = await wire.request([which, program, operation, ...values]);
         return answer[0];
     }
     async function transfer(operation, path, body = null) {
@@ -12,7 +12,7 @@ export function area(which) {
         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]);
+            const answer = await wire.request([which, program, operation, path, body, channel.port2], undefined, body instanceof ReadableStream ? [body, channel.port2] : [channel.port2]);
             if (operation === "write") {
                 close();
                 return null;
@@ -34,6 +34,8 @@ export function area(which) {
         return body;
     }
     return {
+        path: () => ask("path"),
+        resolve: (...path) => ask("resolve", ...path),
         stream,
         async bytes(...path) { return new Uint8Array(await new Response(await stream(...path)).arrayBuffer()); },
         async text(...path) { return new Response(await stream(...path)).text(); },
@@ -47,9 +49,9 @@ export function area(which) {
         clear: (...path) => ask("clear", ...path)
     };
 }
-export function store() {
+export function store(program) {
     async function ask(operation, ...values) {
-        const answer = await wire.request(["store", undefined, operation, ...values]);
+        const answer = await wire.request(["store", program, operation, ...values]);
         return answer[0];
     }
     return {
@@ -60,13 +62,62 @@ export function store() {
         clear: () => ask("clear")
     };
 }
-export function sql(kind) {
+export function sql(kind, program) {
     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]);
+            const answer = await wire.request([kind, program, text, values]);
             return answer[0];
         }
     };
 }
+/** Access to the System's native storage through the Client boundary. */
+export function systemStorage() {
+    async function ask(operation, ...values) {
+        const answer = await wire.request(["host-storage", 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([`host-storage-${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 controlledStream(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 {
+        path: () => ask("path"),
+        resolve: (...path) => ask("resolve", ...path),
+        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) {
+            const path = args.slice(0, -1);
+            await transfer("write", path, content(args.at(-1)).body);
+        },
+        stat: (...path) => ask("stat", ...path),
+        list: (...path) => ask("list", ...path),
+        delete: (...path) => ask("delete", ...path),
+        clear: (...path) => ask("clear", ...path)
+    };
+}

package/dist/system.d.ts

@@ -1,27 +1,3 @@
-import type { AppearanceSource, ClientService, ServerService, ServiceKey, SystemUploads } from "@phreshos/core";
-import { type SystemDesktop } from "./desktop/desktop.js";
-type ServiceEndpoint = ServiceKey["endpoint"];
-type ServiceAddress<Endpoint extends ServiceEndpoint> = Omit<ServiceKey, "endpoint"> & Readonly<{
-    endpoint: Endpoint;
-}>;
-type ServiceHandle<Endpoint extends ServiceEndpoint, Events extends object, Fallback = never> = Endpoint extends "server" ? ServerService<Events, Fallback> : ClientService<Events, Fallback>;
-/** Desktop capabilities structurally available to a Client endpoint. */
-export interface System {
-    /** Complete unresolved Appearance read from the System authority. */
-    readonly appearance: AppearanceSource;
-    /** Capabilities owned by the Desktop containing this Client. */
-    readonly desktop: SystemDesktop;
-    /** Flat System-owned public uploads capability. */
-    readonly uploads: SystemUploads;
-    /** Performs an unrestricted server-side fetch on behalf of this Client. */
-    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
-    /** Returns a precisely typed stable handle for either service endpoint. */
-    service<Endpoint extends ServiceEndpoint>(key: ServiceAddress<Endpoint>): ServiceHandle<Endpoint, {}>;
-    /** Returns a typed stable handle for one exact Server service identity. */
-    service<ServiceEvents extends object, Fallback = never>(key: ServiceAddress<"server">): ServerService<ServiceEvents, Fallback>;
-    /** Returns a typed stable handle for one exact Client service identity. */
-    service<ServiceEvents extends object, Fallback = never>(key: ServiceAddress<"client">): ClientService<ServiceEvents, Fallback>;
-}
-/** Desktop capabilities available to this Client. */
-export declare const system: System;
-export {};
+import { type System as CoreSystem } from "@phreshos/core";
+/** The global System represented through this Client runtime. */
+export declare const system: CoreSystem;

package/dist/system.js

@@ -1,13 +1,22 @@
+import { parseShellEvent } from "@phreshos/core";
 import ClientAppearance from "./appearance.js";
 import wire from "./wire.js";
-import ClientDesktop, {} from "./desktop/desktop.js";
 import { prepareService } from "./service.js";
 import { uploads } from "./uploads.js";
 import controlledStream from "./controlled-stream.js";
+import Events from "./events.js";
+import { exit, process, program } from "./domain.js";
+import { systemStorage } from "./storage.js";
 class ClientSystem {
+    storage = systemStorage();
     appearance = new ClientAppearance();
-    desktop = new ClientDesktop();
+    program = new SystemProgramHandle();
+    process = new SystemProcessHandle();
     uploads = uploads;
+    async forceCreateProgram(source) {
+        const answer = await wire.request(["host-program-force-create", source]);
+        return program(answer[0]);
+    }
     service(key) { return prepareService(key); }
     async fetch(input, init) {
         const request = new Request(input, {
@@ -64,6 +73,61 @@ class ClientSystem {
         });
         return response;
     }
+    async *shell(command, options = {}) {
+        const { signal, ...settings } = options;
+        for await (const event of wire.stream(["shell", command, settings], undefined, signal))
+            yield parseShellEvent(event);
+    }
+}
+class SystemProgramHandle extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("host-program", event, (...values) => listener(systemProgramEvent(event, values)), null, impossible), observer => wire.onAll("host-program", (event, ...values) => {
+            if (typeof event === "string")
+                observer(event, systemProgramEvent(event, values));
+        }));
+    }
+    async list(onlyInstalled = false) {
+        const answer = await wire.request(["host-program-list", onlyInstalled]);
+        return answer[0].map(program);
+    }
+    async find(identity) {
+        const answer = await wire.request(["host-program-find", identity]);
+        return answer[0] ? program(answer[0]) : null;
+    }
+    async create(source) {
+        const answer = await wire.request(["host-program-create", source]);
+        return program(answer[0]);
+    }
+}
+class SystemProcessHandle extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("host-process", event, (...values) => listener(systemProcessEvent(event, values)), null, impossible), observer => wire.onAll("host-process", (event, ...values) => {
+            if (typeof event === "string")
+                observer(event, systemProcessEvent(event, values));
+        }));
+    }
+    async list() {
+        const answer = await wire.request(["host-process-list"]);
+        return answer[0].map(record => process(record));
+    }
+    async find(identity) {
+        const answer = await wire.request(["host-process-find", identity]);
+        return answer[0] ? process(answer[0]) : null;
+    }
+}
+function systemProcessEvent(event, values) {
+    if (event === "create")
+        return process(values[1]);
+    if (event === "exit")
+        return { process: process(values[1]), ...exit(values[2], values[3]) };
+    return values[0];
+}
+function systemProgramEvent(event, values) {
+    if (event === "create" || event === "forget" || event === "install")
+        return program(values[1]);
+    if (event === "uninstall")
+        return { program: program(values[1]), everything: values[2] === true };
+    return values[0];
 }
 function requestHeaders(normalized, supplied) {
     if (!supplied)
@@ -80,5 +144,5 @@ function closeControl(signal, port, abort) {
     signal.removeEventListener("abort", abort);
     port.close();
 }
-/** Desktop capabilities available to this Client. */
+/** The global System represented through this Client runtime. */
 export const system = new ClientSystem();

package/dist/uploads.d.ts

@@ -1,6 +1,7 @@
 import { type SystemUploads, type Upload } from "@phreshos/core";
 /** Flat upload access transported through the Client's Desktop boundary. */
 declare class ClientUploads implements SystemUploads {
+    path(): Promise<string>;
     write(value: unknown): Promise<Upload>;
     stream(file: string): Promise<ReadableStream<Uint8Array>>;
     bytes(file: string): Promise<Uint8Array<ArrayBuffer>>;

package/dist/uploads.js

@@ -4,6 +4,12 @@ import controlledStream from "./controlled-stream.js";
 import wire from "./wire.js";
 /** Flat upload access transported through the Client's Desktop boundary. */
 class ClientUploads {
+    async path() {
+        const answer = await wire.request(["uploads", "path"]);
+        if (typeof answer[0] !== "string" || !answer[0])
+            throw new Error("The System returned an invalid uploads path");
+        return answer[0];
+    }
     async write(value) {
         const source = content(value);
         const channel = new MessageChannel();

package/dist/wire.d.ts

@@ -17,7 +17,7 @@ declare class Wire {
     send(route: string, ...values: unknown[]): void;
     request(values: unknown[], timeout?: number, transfer?: Transferable[]): Promise<unknown>;
     /** Opens one long-running desktop operation and yields its ordered values. */
-    stream(values: unknown[], timeout?: number): AsyncIterableIterator<unknown>;
+    stream(values: unknown[], timeout?: number, signal?: AbortSignal): AsyncIterableIterator<unknown>;
     /** Requests a value while treating the caller's deadline as an absent answer. */
     requestOrNull(values: unknown[], timeout: number): Promise<unknown | null>;
     requestWithin(values: unknown[], deadline: Deadline, transfer?: Transferable[]): Promise<unknown>;
@@ -37,8 +37,7 @@ declare class Wire {
     /** 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" | "events", event: string | null, handler: Handler): Cleanup;
-    samplePointer(movementX: number, movementY: number): void;
+    followService(key: ServiceKey, scope: "lifecycle" | "events", event: string | null, handler: Handler, impossible?: Failure): Cleanup;
     private register;
     private unregister;
     private deliver;

package/dist/wire.js

@@ -54,7 +54,7 @@ class Wire {
         return this.question("end-host", values, timeout, transfer);
     }
     /** Opens one long-running desktop operation and yields its ordered values. */
-    stream(values, timeout = defaultTimeout) {
+    stream(values, timeout = defaultTimeout, signal) {
         const wire = this;
         return (async function* () {
             const question = `client:${crypto.randomUUID()}:${crypto.randomUUID()}`;
@@ -70,6 +70,15 @@ class Wire {
                     state.wake = null;
                 }, timeout)
             };
+            const abort = () => {
+                state.failure = signal?.reason instanceof Error ? signal.reason : new Error("The operation was cancelled");
+                state.wake?.();
+                state.wake = null;
+            };
+            if (signal?.aborted)
+                abort();
+            else
+                signal?.addEventListener("abort", abort, { once: true });
             wire.send("boundary", "expect", question);
             wire.streams.set(question, state);
             wire.send("end-host", "stream", question, ...values);
@@ -87,6 +96,7 @@ class Wire {
                 }
             }
             finally {
+                signal?.removeEventListener("abort", abort);
                 clearTimeout(state.timer);
                 wire.streams.delete(question);
                 wire.send("boundary", "forget", question);
@@ -259,18 +269,18 @@ class Wire {
         });
     }
     /** Follow one exact service lifecycle or application event route. */
-    followService(key, scope, event, handler) {
+    followService(key, scope, event, handler, impossible) {
         const subscription = crypto.randomUUID();
         const stop = this.on("service-event", subscription, handler);
-        this.send("end-host", "service-follow", subscription, key, scope, event);
+        if (impossible)
+            this.impossible.set(subscription, impossible);
+        this.send("end-host", "service-follow", subscription, key, scope, event, impossible !== undefined);
         return once(() => {
             stop();
+            this.impossible.delete(subscription);
             this.send("end-host", "service-unfollow", subscription);
         });
     }
-    samplePointer(movementX, movementY) {
-        this.send("end-host", "pointerSample", movementX, movementY);
-    }
     register(kind, route, event, subject, impossible) {
         const subscription = crypto.randomUUID();
         if (impossible)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -39,7 +39,7 @@
   "packageManager": "bun@1.3.14",
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "build": "node --run clean && tsc --noEmit false --outDir dist --rootDir source",
     "verify:completions": "node scripts/verify-completions.mjs",
     "verify:package": "node scripts/verify-package.mjs",
@@ -47,13 +47,13 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.35"
+    "@phreshos/core": "^0.1.37"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.35",
+    "@phreshos/core": "^0.1.37",
     "typescript": "^6.0.3"
   }
 }

package/dist/desktop/pointer.d.ts

@@ -1,11 +0,0 @@
-import Events from "../events.js";
-/** Permission-guarded access to the Desktop pointer visible to this Client. */
-export default class ClientPointer extends Events {
-    private listeners;
-    private readonly sample;
-    constructor();
-    snapshot(): Promise<Readonly<{
-        position: import("@phreshos/core").DesktopPointerPosition | null;
-    }>>;
-    private withSampling;
-}

package/dist/desktop/pointer.js

@@ -1,59 +0,0 @@
-import Events from "../events.js";
-import wire from "../wire.js";
-/** Permission-guarded access to the Desktop pointer visible to this Client. */
-export default class ClientPointer extends Events {
-    listeners = 0;
-    sample = (event) => wire.samplePointer(event.movementX, event.movementY);
-    constructor() {
-        super((event, listener, impossible) => this.withSampling(event === "move", wire.on("host-desktop-pointer", event, value => {
-            const snapshot = createSnapshot(value);
-            if (snapshot)
-                listener(snapshot);
-        }, null, impossible)), observer => this.withSampling(true, wire.onAll("host-desktop-pointer", (event, value) => {
-            const snapshot = createSnapshot(value);
-            if (event === "move" && snapshot)
-                observer(event, snapshot);
-        })));
-    }
-    async snapshot() {
-        const answer = await wire.request(["desktopPointer"]);
-        const snapshot = createSnapshot(answer[0]);
-        if (!snapshot)
-            throw new Error("The Desktop returned an invalid pointer");
-        return snapshot;
-    }
-    withSampling(sample, stop) {
-        if (!sample)
-            return stop;
-        if (this.listeners++ === 0)
-            window.addEventListener("pointermove", this.sample);
-        let active = true;
-        return () => {
-            if (!active)
-                return;
-            active = false;
-            stop();
-            this.listeners--;
-            if (this.listeners === 0)
-                window.removeEventListener("pointermove", this.sample);
-        };
-    }
-}
-function createSnapshot(value) {
-    if (!record(value))
-        return null;
-    if (value.position === null)
-        return Object.freeze({ position: null });
-    if (!record(value.position))
-        return null;
-    const { x, y } = value.position;
-    if (!finite(x) || !finite(y))
-        return null;
-    return Object.freeze({ position: Object.freeze({ x, y }) });
-}
-function record(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function finite(value) {
-    return typeof value === "number" && Number.isFinite(value);
-}