@phreshos/client 0.1.5 → 0.1.6

package/README.md

@@ -18,7 +18,7 @@ a peer dependency. It does not redefine those objects, own server-side
 capabilities, or contain host and transport implementations.
 
 Its `Host` contract exposes only desktop-session capabilities: the public
-system Theme, surface and pointer state, publicly served values, and
+system Theme, desktop and pointer state, publicly served values, and
 unrestricted server-side Fetch. `host.theme.snapshot()` explicitly and
 asynchronously reads the current snapshot retained by the desktop host.
 `host.theme.subscribe("change", listener)` is an ordinary live subscription:
@@ -26,22 +26,23 @@ it receives only complete replacements published after registration, with no
 initial value or replay. The Client cannot write the authoritative value. The
 Host does not expose system-wide Program or Process discovery.
 
-Surface and pointer access are independent objects rather than events merged
+Desktop and pointer access are independent objects rather than events merged
 into Host:
 
 ```ts
-const surface = await host.surface.size()
-const stopSurface = host.surface.subscribe("resize", next => undefined)
+const desktop = await host.desktop.size()
+const stopDesktop = host.desktop.subscribe("resize", next => undefined)
 
 const position = await host.pointer.position()
 const stopPointer = host.pointer.subscribe("move", next => undefined)
 ```
 
-A Surface contains only the width and height of the current Client Window's
-own layer. Client code cannot select another layer, and the desktop's gutter
-never enters an endpoint. Pointer position and movement both require the
-`pointer` permission. Reads are asynchronous requests; subscriptions receive
-only future publications and never replay a retained value.
+The desktop size is the complete desktop area containing this Client,
+independent of the Client Window's layer. Client code cannot select a layer,
+and the desktop's gutter never enters an endpoint. Pointer position and
+movement both require the `pointer` permission. Reads are asynchronous
+requests; subscriptions receive only future publications and never replay a
+retained value.
 
 Permission decisions belong to the current Program, not to the desktop Host.
 They are available from a Program handle and flattened through `current` as the
@@ -127,36 +128,31 @@ 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. Client Window capabilities add awaitable
-`localMove()` and `localResize()` for representation-local gestures. Their
-Promises confirm that the current Client host accepted and applied the local
-draft; they do not enter server authority or emit Window events.
+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.
 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
 two independent operations and can expose an intermediate state remotely.
 
-An `under` or `over` Window representation may request one local host-rendered
-Surface. The capability follows the same desktop-local targeting model as
-`localMove()` and `localResize()`; it is command-only and has no server-owned
-state:
+An `under` or `over` representation may request one local host-rendered Surface:
 
 ```ts
-await window.surface.set({
+await current.localWindow.surface.set({
   opacity: 0.65,
-  radius: "large",
-  transaction: { duration: 240, easing: "ease-out" }
-})
+  radius: "large"
+}, { duration: 240, easing: "ease-out", wait: true })
 
-await window.surface.remove()
+await current.localWindow.surface.remove()
 ```
 
-The desktop holds the target only for the lifetime of the addressed iframe.
-Reloading or destroying that representation removes it; another accessible
-Window handle may tailor the same local representation, while other desktops
-remain unaffected. Program code may synchronize desired settings through its
-Server and explicitly apply them again. `set()` with no settings creates a
-sharp, fully opaque Surface.
+The desktop holds local state only for the lifetime of that iframe
+representation. Reloading or destroying it resets the representation from
+authoritative truth, while other desktops remain unaffected. Program code may
+synchronize desired settings through its Server and explicitly apply them
+again. `set()` with no settings creates a sharp, fully opaque Surface.
 Opacity is a finite number from `0` through `1`; zero retains the Surface node.
 Radius accepts a nonnegative pixel number, a Theme-derived `ScaleLevel`, or
 `"full"`. Only `remove()` restores exact `null` and immediately removes the

package/dist/current.d.ts

@@ -1,3 +1,4 @@
+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. */
@@ -8,6 +9,8 @@ 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,6 +84,7 @@ currentClient = new CurrentClientHandle(owner);
 class ClientCurrent {
     server = currentServer;
     window = currentClient.window;
+    localWindow = new LocalWindowHandle();
     permissions = currentProgramPermissions;
     constructor() {
         bindChannel(this, channel);
@@ -104,6 +105,30 @@ 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/desktop.d.ts

@@ -0,0 +1,20 @@
+import type { Size, Subscribable } from "@phreshos/core";
+import Events from "./events.js";
+/** Live changes to the desktop area containing this Client. */
+export type DesktopEvents = {
+    /** The desktop area resized. */
+    resize: Size;
+};
+/** Explicit desktop size reads and future resizes. */
+export interface HostDesktop extends Subscribable<DesktopEvents, never> {
+    /** Reads the complete current desktop area in CSS pixels. */
+    size(): Promise<Size>;
+}
+/** Desktop access bound to the current Client Process boundary. */
+export default class ClientDesktop extends Events {
+    constructor();
+    size(): Promise<Readonly<{
+        width: import("@phreshos/core").Value;
+        height: import("@phreshos/core").Value;
+    }>>;
+}

package/dist/desktop.js

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

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 ClientSurfaceSettings, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type EndpointDeclaration, type Exit, type Launch, type Permissions, type Position, type ServerTraffic as CoreServerTraffic, type Size, 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 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,22 +102,8 @@ export type Client<Events extends object = {}> = Omit<CoreClient<Events>, "proce
     /** Returns the Process that owns this Client. */
     process(): Promise<Process>;
 };
-/** Client-owned Window capability visible inside a Client boundary. */
-export type Window = CoreWindow & {
-    /** Host-rendered material belonging only to this desktop representation. */
-    readonly surface: ClientWindowSurface;
-    /** Moves this Window representation without changing authoritative state. */
-    localMove(position: Position): Promise<void>;
-    /** Resizes this Window representation without changing authoritative state. */
-    localResize(size: Size): Promise<void>;
-};
-/** Command-only Surface of one Window representation on this desktop. */
-export interface ClientWindowSurface {
-    /** Creates or replaces the representation-local Surface. */
-    set(settings?: ClientSurfaceSettings): Promise<void>;
-    /** Immediately removes the representation-local Surface. */
-    remove(): Promise<void>;
-}
+/** Authoritative Client-owned Window capability visible inside a Client boundary. */
+export type Window = CoreWindow;
 export declare class TrafficHandle extends Events {
     protected readonly target: HandleAddress | null;
     protected readonly kind: "server" | "client";

package/dist/domain.js

@@ -206,11 +206,9 @@ class ClientHandle extends ClientBase {
 }
 class WindowHandle extends Events {
     target;
-    surface;
     constructor(target) {
         super(...deferredScoped("host-end", target, (_event, values) => values[0]));
         this.target = target;
-        this.surface = new ClientWindowSurfaceHandle(target);
     }
     async state() {
         const answer = await wire.request(["window", await this.target()]);
@@ -224,22 +222,12 @@ class WindowHandle extends Events {
     async layer() { return (await this.state()).layer; }
     async location() { return (await this.state()).location; }
     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 setGeometry(geometry) { await wire.request(["setGeometry", await this.target(), geometry]); }
-    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 ClientWindowSurfaceHandle {
-    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) => {

package/dist/host.d.ts

@@ -1,12 +1,12 @@
 import type { ClientServiceHandler, ServedFile, ServerServiceHandler, Theme, ThemeProperties } from "@phreshos/core";
 import { type HostPointer } from "./pointer.js";
-import { type HostSurface } from "./surface.js";
+import { type HostDesktop } from "./desktop.js";
 /** Desktop capabilities structurally available to a Client endpoint. */
 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;
+    /** Layer-independent desktop size reads and live updates. */
+    readonly desktop: HostDesktop;
     /** Permission-guarded desktop pointer reads and live movement. */
     readonly pointer: HostPointer;
     /** Stores one value as a publicly reachable file. */

package/dist/host.js

@@ -2,11 +2,11 @@ import { content } from "./content.js";
 import ClientTheme from "./theme.js";
 import wire from "./wire.js";
 import ClientPointer, {} from "./pointer.js";
-import ClientSurface, {} from "./surface.js";
+import ClientDesktop, {} from "./desktop.js";
 import { service as serviceHandle } from "./service.js";
 class ClientHost {
     theme = new ClientTheme();
-    surface = new ClientSurface();
+    desktop = new ClientDesktop();
     pointer = new ClientPointer();
     async serve(value) {
         const source = content(value);

package/dist/main.d.ts

@@ -1,8 +1,8 @@
 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 { type DesktopEvents, type HostDesktop } from "./desktop.js";
 export { current, type Current, type CurrentServer } from "./current.js";
 export { type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js";
 export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
-export { Client, Endpoint, Process, Program, Server, type ClientWindowSurface, 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, WindowGeometry, WindowLayer, WindowState, ClientSurfaceEasing, ClientSurfaceSettings, ClientSurfaceTransaction } 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, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, SurfaceSettings, Transaction } from "@phreshos/core";

package/dist/main.js

@@ -1,6 +1,6 @@
 export { host } from "./host.js";
 export {} from "./pointer.js";
-export {} from "./surface.js";
+export {} from "./desktop.js";
 export { current } from "./current.js";
 export {} from "./channel.js";
 export { ClientServiceHandler, ServerServiceHandler, ServiceHandler } from "@phreshos/core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -46,10 +46,10 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.5"
+    "@phreshos/core": "^0.1.6"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.5",
+    "@phreshos/core": "^0.1.6",
     "typescript": "^6.0.3"
   }
 }

package/dist/surface.d.ts

@@ -1,29 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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);
-}