@phreshos/client 0.1.0 → 0.1.1

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;
+}

package/dist/pointer.js

@@ -0,0 +1,54 @@
+import Events from "./events.js";
+import wire from "./wire.js";
+/** Client pointer access bound to the current Process boundary. */
+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-pointer", event, value => {
+            const position = createPosition(value);
+            if (position)
+                listener(position);
+        }, null, impossible)), observer => this.withSampling(true, wire.onAll("host-pointer", (event, value) => {
+            const position = createPosition(value);
+            if (event === "move" && position)
+                observer(event, position);
+        })));
+    }
+    async position() {
+        const answer = await wire.request(["pointer"]);
+        if (answer[0] === null)
+            return null;
+        const position = createPosition(answer[0]);
+        if (!position)
+            throw new Error("The desktop returned an invalid Pointer position");
+        return position;
+    }
+    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 createPosition(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const position = value;
+    if (!finite(position.x) || !finite(position.y))
+        return null;
+    return Object.freeze({ x: position.x, y: position.y });
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}

package/dist/surface.d.ts

@@ -0,0 +1,29 @@
+import type { Subscribable } from "@phreshos/core";
+import Events from "./events.js";
+/** The available workspace of this Client Window's layer. */
+export type Surface = Readonly<{
+    /** Available width in CSS pixels. */
+    width: number;
+    /** Available height in CSS pixels. */
+    height: number;
+}>;
+/** Live changes to this Client Window's surface. */
+export type SurfaceEvents = {
+    /** The available workspace resized. */
+    resize: Surface;
+};
+/** Explicit surface size reads and future resizes. */
+export interface HostSurface extends Subscribable<SurfaceEvents, never> {
+    /** Reads this Client Window's current surface. */
+    size(): Promise<Surface>;
+}
+/** Client surface access bound to the current Process boundary. */
+export default class ClientSurface extends Events {
+    constructor();
+    size(): Promise<Readonly<{
+        /** Available width in CSS pixels. */
+        width: number;
+        /** Available height in CSS pixels. */
+        height: number;
+    }>>;
+}

package/dist/surface.js

@@ -0,0 +1,34 @@
+import Events from "./events.js";
+import wire from "./wire.js";
+/** Client surface access bound to the current Process boundary. */
+export default class ClientSurface extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("host-surface", event, value => {
+            const surface = createSurface(value);
+            if (surface)
+                listener(surface);
+        }, null, impossible), observer => wire.onAll("host-surface", (event, value) => {
+            const surface = createSurface(value);
+            if (typeof event === "string" && surface)
+                observer(event, surface);
+        }));
+    }
+    async size() {
+        const answer = await wire.request(["surface"]);
+        const surface = createSurface(answer[0]);
+        if (!surface)
+            throw new Error("The desktop returned an invalid Surface size");
+        return surface;
+    }
+}
+function createSurface(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const surface = value;
+    if (!finite(surface.width) || !finite(surface.height))
+        return null;
+    return Object.freeze({ width: surface.width, height: surface.height });
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}

package/dist/theme.d.ts

@@ -0,0 +1,13 @@
+import Events from "./events.js";
+/** Read-only system Theme reached explicitly through the desktop boundary. */
+export default class ClientTheme extends Events {
+    constructor();
+    snapshot(): Promise<Readonly<{
+        background: string;
+        foreground: string;
+        accent: string;
+        spacing: number;
+        radius: number;
+        glass: import("@phreshos/core").ThemeGlass;
+    }>>;
+}

package/dist/theme.js

@@ -0,0 +1,29 @@
+import { createThemeSnapshot } from "@phreshos/core";
+import Events from "./events.js";
+import wire from "./wire.js";
+/** Read-only system Theme reached explicitly through the desktop boundary. */
+export default class ClientTheme extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("host-theme", event, value => {
+            if (isObject(value))
+                listener(createThemeSnapshot(value));
+        }, null, impossible), observer => wire.onAll("host-theme", (event, value) => {
+            if (typeof event === "string" && isObject(value))
+                observer(event, createThemeSnapshot(value));
+        }));
+    }
+    async snapshot() {
+        const answer = await wire.request(["theme"]);
+        if (!isObject(answer[0]))
+            throw new Error("The desktop returned an invalid Theme snapshot");
+        return createThemeSnapshot(answer[0]);
+    }
+}
+function isObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const theme = value;
+    return typeof theme.background === "string" && typeof theme.foreground === "string" && typeof theme.accent === "string"
+        && typeof theme.spacing === "number" && typeof theme.radius === "number"
+        && typeof theme.glass === "object" && theme.glass !== null;
+}

package/dist/wire.d.ts

@@ -1,5 +1,6 @@
 import type { Cleanup } from "@phreshos/core";
 import Deadline from "./deadline.js";
+import type { HandleAddress } from "./domain.js";
 type Handler = (...values: unknown[]) => unknown;
 type Failure = (error: Error) => void;
 type TrafficKind = "publish" | "ask" | "answer";
@@ -10,20 +11,27 @@ declare class Wire {
     private readonly subscribers;
     private readonly every;
     private readonly impossible;
-    private readonly boundarySubscriptions;
-    private readonly observations;
-    readonly identity: Promise<string>;
+    private identityPromise;
     constructor();
     send(route: string, ...values: unknown[]): void;
     request(values: unknown[], timeout?: number, transfer?: Transferable[]): Promise<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>;
     askServerWithin(event: string, payload: unknown, deadline: Deadline): Promise<unknown>;
+    /** Resolves this endpoint's Process address only for operations that need it. */
+    identity(): Promise<{
+        process: string;
+        reference: string;
+    }>;
     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;
+    observe(target: HandleAddress | null, half: "server" | "client", kind: TrafficKind, event: string | null, handler: Handler, impossible?: Failure): Cleanup;
+    /** Follow destinationless events emitted by one Endpoint. */
+    follow(target: HandleAddress | null, half: "server" | "client", event: string | null, handler: Handler, impossible?: Failure): Cleanup;
     samplePointer(movementX: number, movementY: number): void;
     private register;
     private unregister;

package/dist/wire.js

@@ -8,37 +8,21 @@ class Wire {
     subscribers = new Map();
     every = new Map();
     impossible = new Map();
-    boundarySubscriptions = new Map();
-    observations = new Map();
-    identity;
+    identityPromise = null;
     constructor() {
-        let identify = () => undefined;
-        this.identity = new Promise(resolve => { identify = resolve; });
         this.send("boundary", "document", crypto.randomUUID());
-        this.send("boundary", "identity");
         window.addEventListener("message", event => {
             if (event.source !== this.parent || !Array.isArray(event.data))
                 return;
             const [route, ...values] = event.data;
             if (route === "boundary") {
                 const [operation, ...rest] = values;
-                if (operation === "identity" && typeof rest[0] === "string")
-                    identify(rest[0]);
                 if (operation === "impossible" && typeof rest[0] === "string" && typeof rest[1] === "string") {
                     this.impossible.get(rest[0])?.(new Error(rest[1]));
                     this.impossible.delete(rest[0]);
                 }
                 return;
             }
-            if (route === "host-end" && values[0] === "observations-ready") {
-                for (const [subscription, description] of this.boundarySubscriptions) {
-                    this.send("boundary", "subscribe", subscription, ...description);
-                }
-                for (const [subscription, description] of this.observations) {
-                    this.send("end-host", "observe", subscription, ...description);
-                }
-                return;
-            }
             if (values[0] === "answer" && typeof values[1] === "string") {
                 this.settle(values[1], values.at(-1));
                 return;
@@ -52,13 +36,36 @@ class Wire {
     request(values, timeout = defaultTimeout, transfer = []) {
         return this.question("end-host", values, timeout, transfer);
     }
+    /** Requests a value while treating the caller's deadline as an absent answer. */
+    requestOrNull(values, timeout) {
+        return this.question("end-host", values, timeout, [], timeout, true);
+    }
     requestWithin(values, deadline, transfer = []) {
         return this.question("end-host", values, deadline.remaining(), transfer, deadline.milliseconds);
     }
     askServerWithin(event, payload, deadline) {
         return this.question("end-end", [event, payload], deadline.remaining(), [], deadline.milliseconds);
     }
-    question(route, values, timeout, transfer = [], reportedTimeout = timeout) {
+    /** Resolves this endpoint's Process address only for operations that need it. */
+    identity() {
+        if (!this.identityPromise) {
+            const resolving = this.request(["process"]).then(value => {
+                const [record] = value;
+                if (typeof record?.identity !== "string" || typeof record.reference !== "string") {
+                    throw new Error("The desktop returned an invalid Process identity");
+                }
+                return { process: record.identity, reference: record.reference };
+            });
+            const retained = resolving.catch(error => {
+                if (this.identityPromise === retained)
+                    this.identityPromise = null;
+                throw error;
+            });
+            this.identityPromise = retained;
+        }
+        return this.identityPromise;
+    }
+    question(route, values, timeout, transfer = [], reportedTimeout = timeout, nullOnTimeout = false) {
         return new Promise((resolve, reject) => {
             let active = true;
             let question = null;
@@ -70,9 +77,13 @@ class Wire {
                     this.pending.delete(question);
                     this.send("boundary", "forget", question);
                 }
-                reject(new Error(`Answer timeout ${reportedTimeout}ms`));
+                if (nullOnTimeout)
+                    resolve(null);
+                else
+                    reject(new Error(`Answer timeout ${reportedTimeout}ms`));
             }, timeout);
-            this.identity.then(identity => {
+            const begin = route === "end-end" ? this.identity() : Promise.resolve({ process: crypto.randomUUID() });
+            begin.then(({ process: identity }) => {
                 if (!active)
                     return;
                 question = `client:${identity}:${crypto.randomUUID()}`;
@@ -106,6 +117,12 @@ class Wire {
                     active = false;
                     reject(error);
                 }
+            }).catch(error => {
+                if (!active)
+                    return;
+                active = false;
+                clearTimeout(timer);
+                reject(error);
             });
         });
     }
@@ -155,33 +172,39 @@ class Wire {
     observe(target, half, kind, event, handler, impossible) {
         const subscription = crypto.randomUUID();
         const stop = this.on("observed", subscription, handler);
-        const description = [target, half, kind, event, impossible !== undefined];
-        this.observations.set(subscription, description);
         if (impossible)
             this.impossible.set(subscription, impossible);
-        this.send("end-host", "observe", subscription, ...description);
+        this.send("end-host", "observe", subscription, target, half, kind, event, impossible !== undefined);
         return once(() => {
             stop();
-            this.observations.delete(subscription);
             this.impossible.delete(subscription);
             this.send("end-host", "unobserve", subscription);
         });
     }
+    /** Follow destinationless events emitted by one Endpoint. */
+    follow(target, half, event, handler, impossible) {
+        const subscription = crypto.randomUUID();
+        const stop = this.on("emitted", subscription, handler);
+        if (impossible)
+            this.impossible.set(subscription, impossible);
+        this.send("end-host", "follow", subscription, target, half, event, impossible !== undefined);
+        return once(() => {
+            stop();
+            this.impossible.delete(subscription);
+            this.send("end-host", "unfollow", subscription);
+        });
+    }
     samplePointer(movementX, movementY) {
         this.send("end-host", "pointerSample", movementX, movementY);
     }
     register(kind, route, event, subject, impossible) {
         const subscription = crypto.randomUUID();
-        const description = [kind, route, event, subject, impossible !== undefined];
-        this.boundarySubscriptions.set(subscription, description);
         if (impossible)
             this.impossible.set(subscription, impossible);
-        this.send("boundary", "subscribe", subscription, ...description);
+        this.send("boundary", "subscribe", subscription, kind, route, event, subject, impossible !== undefined);
         return subscription;
     }
     unregister(subscription) {
-        if (!this.boundarySubscriptions.delete(subscription))
-            return;
         this.impossible.delete(subscription);
         this.send("boundary", "unsubscribe", subscription);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -13,18 +13,43 @@
   },
   "files": [
     "dist",
+    "LICENSE",
     "README.md"
   ],
+  "author": "Zohayr SLILEH",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PhreshOS/client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PhreshOS/client/issues"
+  },
+  "homepage": "https://github.com/PhreshOS/client#readme",
+  "keywords": [
+    "phreshos",
+    "client",
+    "sdk",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.3.14",
   "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "check": "tsc --noEmit",
-    "build": "tsc --noEmit false --outDir dist --rootDir source",
+    "build": "node --run clean && tsc --noEmit false --outDir dist --rootDir source",
+    "verify:package": "node scripts/verify-package.mjs",
+    "verify": "node --run check && node --run build && node --run verify:package",
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.0"
+    "@phreshos/core": "^0.1.1"
   },
   "devDependencies": {
-    "@phreshos/core": "0.1.0",
+    "@phreshos/core": "^0.1.1",
     "typescript": "^6.0.3"
   }
 }