@phreshos/client 0.1.7 → 0.1.9

package/README.md

@@ -128,10 +128,11 @@ 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. `current.window` is authoritative and
-subscribable. `current.localWindow` is the physical representation belonging to
-this iframe on this desktop. Its reads and updates are local, have no events,
-and cannot target another Client handle.
+expose host filesystem paths. Every Client-side Window handle exposes the same
+authoritative, subscribable Window capability and its `window.local` physical
+representation on this desktop. Local reads and updates have no events and do
+not change Server state. `current.window` is only convenient access to the
+executing Client's canonical Window; it has no additional authority.
 When both dimensions must change, `setGeometry({ position, size })` commits
 them through one authoritative request and produces one `geometry` event.
 Calling `move()` and `resize()` sequentially or through `Promise.all()` remains
@@ -140,12 +141,12 @@ two independent operations and can expose an intermediate state remotely.
 An `under` or `over` representation may request one local host-rendered Surface:
 
 ```ts
-await current.localWindow.surface.set({
+await current.window.local.surface.set({
   opacity: 0.65,
   radius: "large"
 }, { duration: 240, easing: "ease-out", wait: true })
 
-await current.localWindow.surface.remove()
+await current.window.local.surface.remove()
 ```
 
 The desktop holds local state only for the lifetime of that iframe

package/dist/current.d.ts

@@ -1,4 +1,3 @@
-import type { LocalWindow } from "@phreshos/core";
 import { type Channel } from "./channel.js";
 import { Client, Server, type Process, type Program, type Window } from "./domain.js";
 /** The current Process's canonical Server handle. */
@@ -9,8 +8,6 @@ export interface Current<Events extends object = {}> extends Channel<Events>, Pi
     readonly server: CurrentServer;
     /** Presentation capability of this current Client. */
     readonly window: Window;
-    /** Physical Window representation belonging only to this Client iframe. */
-    readonly localWindow: LocalWindow;
     /** The same permission capability exposed by the current Program. */
     readonly permissions: Program["permissions"];
     /** Returns the Process represented by this Client. */

package/dist/current.js

@@ -84,7 +84,6 @@ currentClient = new CurrentClientHandle(owner);
 class ClientCurrent {
     server = currentServer;
     window = currentClient.window;
-    localWindow = new LocalWindowHandle();
     permissions = currentProgramPermissions;
     constructor() {
         bindChannel(this, channel);
@@ -105,30 +104,6 @@ class ClientCurrent {
     async stop() { await wire.request(["stop-current"]); }
     service() { return endpointService(null, "client"); }
 }
-class LocalWindowHandle {
-    surface = new LocalWindowSurfaceHandle();
-    async state() {
-        const answer = await wire.request(["localWindow"]);
-        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, transaction) { await wire.request(["localWindowMove", position, transaction]); }
-    async resize(size, transaction) { await wire.request(["localWindowResize", size, transaction]); }
-    async setGeometry(geometry, transaction) { await wire.request(["localWindowGeometry", geometry, transaction]); }
-    async minimize(minimized = true) { await wire.request(["localWindowMinimize", minimized]); }
-    async changeTitle(title) { await wire.request(["localWindowTitle", title]); }
-    async raise() { await wire.request(["localWindowRaise"]); }
-}
-class LocalWindowSurfaceHandle {
-    async set(settings = {}, transaction) { await wire.request(["localWindowSurfaceSet", settings, transaction]); }
-    async remove() { await wire.request(["localWindowSurfaceRemove"]); }
-}
 function bindChannel(target, source) {
     Object.assign(target, {
         publish: source.publish.bind(source),

package/dist/domain.d.ts

@@ -1,4 +1,4 @@
-import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, 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 Cleanup, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type EndpointDeclaration, type Exit, type Launch, type Permissions, type ServerTraffic as CoreServerTraffic, type TrafficMessage as CoreTrafficMessage, type TrafficCapture as CoreTrafficCapture, type TrafficEvents as CoreTrafficEvents, type Window as CoreWindow, type WindowState } from "@phreshos/core";
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, 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 Cleanup, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type EndpointDeclaration, type Exit, type Launch, type LocalWindow, type Permissions, type ServerTraffic as CoreServerTraffic, type TrafficMessage as CoreTrafficMessage, type TrafficCapture as CoreTrafficCapture, type TrafficEvents as CoreTrafficEvents, type Window as CoreWindow, type WindowState } from "@phreshos/core";
 import Events from "./events.js";
 export interface HandleAddress {
     identity: string;
@@ -102,8 +102,11 @@ export type Client<Events extends object = {}> = Omit<CoreClient<Events>, "proce
     /** Returns the Process that owns this Client. */
     process(): Promise<Process>;
 };
-/** Authoritative Client-owned Window capability visible inside a Client boundary. */
-export type Window = CoreWindow;
+/** Authoritative Window state plus its representation on this desktop. */
+export type Window = CoreWindow & {
+    /** Physical representation of this Window on the current desktop. */
+    readonly local: LocalWindow;
+};
 export declare class TrafficHandle extends Events {
     protected readonly target: HandleAddress | null;
     protected readonly kind: "server" | "client";

package/dist/domain.js

@@ -206,9 +206,11 @@ class ClientHandle extends ClientBase {
 }
 class WindowHandle extends Events {
     target;
+    local;
     constructor(target) {
         super(...deferredScoped("host-end", target, (_event, values) => values[0]));
         this.target = target;
+        this.local = new LocalWindowHandle(target);
     }
     async state() {
         const answer = await wire.request(["window", await this.target()]);
@@ -228,6 +230,41 @@ class WindowHandle extends Events {
     async changeTitle(title) { await wire.request(["changeTitle", await this.target(), title]); }
     async raise() { await wire.request(["raise", await this.target()]); }
 }
+class LocalWindowHandle {
+    target;
+    surface;
+    constructor(target) {
+        this.target = target;
+        this.surface = new LocalWindowSurfaceHandle(target);
+    }
+    async state() {
+        const answer = await wire.request(["windowLocal", await this.target()]);
+        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, transaction) { await wire.request(["windowLocalMove", await this.target(), position, transaction]); }
+    async resize(size, transaction) { await wire.request(["windowLocalResize", await this.target(), size, transaction]); }
+    async setGeometry(geometry, transaction) { await wire.request(["windowLocalGeometry", await this.target(), geometry, transaction]); }
+    async minimize(minimized = true) { await wire.request(["windowLocalMinimize", await this.target(), minimized]); }
+    async changeTitle(title) { await wire.request(["windowLocalTitle", await this.target(), title]); }
+    async raise() { await wire.request(["windowLocalRaise", await this.target()]); }
+}
+class LocalWindowSurfaceHandle {
+    target;
+    constructor(target) {
+        this.target = target;
+    }
+    async set(settings = {}, transaction) {
+        await wire.request(["windowLocalSurfaceSet", await this.target(), settings, transaction]);
+    }
+    async remove() { await wire.request(["windowLocalSurfaceRemove", await this.target()]); }
+}
 function deferredScoped(route, target, convert) {
     return [
         (event, listener, impossible) => {

package/dist/messagepack.d.ts

@@ -0,0 +1,3 @@
+export type Bytes = Uint8Array<ArrayBuffer>;
+export declare const serialize: (value: unknown, attachments?: readonly object[]) => Bytes;
+export declare const deserialize: (bytes: Uint8Array, attachments?: readonly unknown[]) => unknown;

package/dist/messagepack.js

@@ -0,0 +1,130 @@
+import { decode, encode, ExtensionCodec } from "@msgpack/msgpack";
+class Attachment {
+    index;
+    constructor(index) {
+        this.index = index;
+    }
+}
+class BigInteger {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}
+class Undefined {
+}
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+const extensions = new ExtensionCodec();
+const serializePrepared = (value, context) => encode(value, { context, extensionCodec: extensions });
+const deserializePrepared = (bytes, context) => decode(bytes, { context, extensionCodec: extensions });
+extensions.register({
+    type: 0,
+    encode: value => value instanceof Attachment ? uint32(value.index) : null,
+    decode: (bytes, _type, context) => {
+        const attachment = context.incoming?.[readUint32(bytes)];
+        if (attachment === undefined)
+            throw new Error("The MessagePack attachment is absent");
+        return attachment;
+    }
+});
+extensions.register({
+    type: 1,
+    encode: (value, context) => value instanceof Map ? serializePrepared([...value], context) : null,
+    decode: (bytes, _type, context) => new Map(deserializePrepared(bytes, context))
+});
+extensions.register({
+    type: 2,
+    encode: (value, context) => value instanceof Set ? serializePrepared([...value], context) : null,
+    decode: (bytes, _type, context) => new Set(deserializePrepared(bytes, context))
+});
+extensions.register({
+    type: 3,
+    encode: (value, context) => value instanceof RegExp ? serializePrepared([value.source, value.flags, value.lastIndex], context) : null,
+    decode: (bytes, _type, context) => {
+        const [source, flags, lastIndex] = deserializePrepared(bytes, context);
+        const expression = new RegExp(source, flags);
+        expression.lastIndex = lastIndex;
+        return expression;
+    }
+});
+extensions.register({
+    type: 4,
+    encode: value => value instanceof URL ? textEncoder.encode(value.href) : null,
+    decode: bytes => new URL(textDecoder.decode(bytes))
+});
+extensions.register({
+    type: 5,
+    encode: (value, context) => value instanceof Error ? serializePrepared(prepare({
+        cause: value.cause,
+        message: value.message,
+        name: value.name,
+        stack: value.stack
+    }, context), context) : null,
+    decode: (bytes, _type, context) => {
+        const value = deserializePrepared(bytes, context);
+        const error = new Error(value.message, { cause: value.cause });
+        error.name = value.name;
+        if (value.stack !== undefined)
+            error.stack = value.stack;
+        return error;
+    }
+});
+extensions.register({
+    type: 6,
+    encode: value => value instanceof BigInteger ? textEncoder.encode(value.value.toString()) : null,
+    decode: bytes => BigInt(textDecoder.decode(bytes))
+});
+extensions.register({
+    type: 7,
+    encode: value => value instanceof Undefined ? new Uint8Array() : null,
+    decode: () => undefined
+});
+export const serialize = (value, attachments = []) => {
+    const outgoing = new Map(attachments.map((attachment, index) => [attachment, index]));
+    const context = { outgoing };
+    return serializePrepared(prepare(value, context), context);
+};
+export const deserialize = (bytes, attachments = []) => {
+    return deserializePrepared(bytes, { incoming: attachments });
+};
+const prepare = (value, context) => {
+    if (value === undefined)
+        return new Undefined();
+    if (typeof value === "bigint")
+        return new BigInteger(value);
+    if (typeof value === "function" || typeof value === "symbol")
+        return null;
+    if (value === null || typeof value !== "object")
+        return value;
+    const attachment = context.outgoing?.get(value);
+    if (attachment !== undefined)
+        return new Attachment(attachment);
+    if (value instanceof Date || value instanceof RegExp || value instanceof URL || value instanceof Error)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (ArrayBuffer.isView(value))
+        return Uint8Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+    if (value instanceof Map)
+        return new Map([...value].map(([key, entry]) => [prepare(key, context), prepare(entry, context)]));
+    if (value instanceof Set)
+        return new Set([...value].map(entry => prepare(entry, context)));
+    if (Array.isArray(value))
+        return value.map(entry => prepare(entry, context));
+    if ("toJSON" in value && typeof value.toJSON === "function")
+        return prepare(value.toJSON(), context);
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entry]) => typeof entry !== "function")
+        .map(([key, entry]) => [key, prepare(entry, context)]));
+};
+const uint32 = (value) => {
+    const bytes = new Uint8Array(4);
+    new DataView(bytes.buffer).setUint32(0, value);
+    return bytes;
+};
+const readUint32 = (bytes) => {
+    if (bytes.byteLength !== 4)
+        throw new Error("The MessagePack attachment reference is invalid");
+    return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0);
+};

package/dist/wire.d.ts

@@ -25,6 +25,7 @@ declare class Wire {
         reference: string;
     }>;
     private question;
+    private post;
     expectWithin(question: string, deadline: Deadline): Promise<unknown>;
     forget(question: string): void;
     on(route: string, event: string, handler: Handler, subject?: string | null, impossible?: Failure): Cleanup;

package/dist/wire.js

@@ -1,6 +1,7 @@
 import Deadline from "./deadline.js";
 import { defaultTimeout } from "./events.js";
 import captureClientOutput from "./log.js";
+import { deserialize, serialize } from "./messagepack.js";
 /** The client endpoint's sole postMessage adapter. */
 class Wire {
     parent = window.parent === window ? null : window.parent;
@@ -14,7 +15,19 @@ class Wire {
         window.addEventListener("message", event => {
             if (event.source !== this.parent || !Array.isArray(event.data))
                 return;
-            const [route, ...values] = event.data;
+            const [bytes, ...attachments] = event.data;
+            if (!(bytes instanceof Uint8Array))
+                return;
+            let message;
+            try {
+                message = deserialize(bytes, attachments);
+            }
+            catch {
+                return;
+            }
+            if (!Array.isArray(message) || typeof message[0] !== "string")
+                return;
+            const [route, ...values] = message;
             if (route === "boundary") {
                 const [operation, ...rest] = values;
                 if (operation === "impossible" && typeof rest[0] === "string" && typeof rest[1] === "string") {
@@ -31,7 +44,7 @@ class Wire {
         });
     }
     send(route, ...values) {
-        this.parent?.postMessage([route, ...values], "*");
+        this.post([route, ...values]);
     }
     request(values, timeout = defaultTimeout, transfer = []) {
         return this.question("end-host", values, timeout, transfer);
@@ -108,7 +121,7 @@ class Wire {
                     ? [route, "wait", question, publicId, ...values]
                     : [route, "wait", question, ...values];
                 try {
-                    this.parent?.postMessage(message, "*", transfer);
+                    this.post(message, transfer);
                 }
                 catch (error) {
                     this.pending.delete(question);
@@ -126,6 +139,13 @@ class Wire {
             });
         });
     }
+    post(message, transfer = []) {
+        if (!this.parent)
+            return;
+        const attachments = nativeAttachments(message, transfer);
+        const bytes = serialize(message, attachments);
+        this.parent.postMessage([bytes, ...attachments], "*", [bytes.buffer, ...transfer]);
+    }
     expectWithin(question, deadline) {
         this.send("boundary", "expect", question);
         return new Promise((resolve, reject) => {
@@ -254,6 +274,37 @@ function once(cleanup) {
         cleanup();
     };
 }
+function nativeAttachments(value, transfer) {
+    const attachments = [...transfer];
+    const known = new Set(attachments);
+    const visit = (entry) => {
+        if (entry === null || typeof entry !== "object" || known.has(entry))
+            return;
+        known.add(entry);
+        if (entry instanceof Blob) {
+            attachments.push(entry);
+            return;
+        }
+        if (entry instanceof Date || entry instanceof RegExp || entry instanceof URL || entry instanceof Error || entry instanceof ArrayBuffer || ArrayBuffer.isView(entry))
+            return;
+        if (entry instanceof Map) {
+            for (const [key, item] of entry) {
+                visit(key);
+                visit(item);
+            }
+            return;
+        }
+        if (entry instanceof Set) {
+            for (const item of entry)
+                visit(item);
+            return;
+        }
+        for (const item of Array.isArray(entry) ? entry : Object.values(entry))
+            visit(item);
+    };
+    visit(value);
+    return attachments;
+}
 const wire = new Wire();
 captureClientOutput(wire);
 export default wire;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -48,6 +48,9 @@
   "peerDependencies": {
     "@phreshos/core": "^0.1.6"
   },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.3"
+  },
   "devDependencies": {
     "@phreshos/core": "^0.1.6",
     "typescript": "^6.0.3"