@phreshos/client 0.1.4 → 0.1.5

package/README.md

@@ -43,6 +43,25 @@ 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
+same canonical capability:
+
+```ts
+const program = await current.program()
+
+await program.permissions.granted("pointer")
+await current.permissions.request("pointer")
+await current.permissions.timeout(5_000).request("pointer")
+
+current.permissions === program.permissions
+```
+
+`granted()` reads the effective decision without prompting. `request()` asks
+only when no known decision can answer immediately and returns `null` if its
+deadline expires. The desktop remains the internal enforcement boundary, but
+permission ownership does not alter the public shape of `host`.
+
 A Client may traverse `Process.parent()` through any number of ancestors in
 its own Program. The first parent outside that Program is structurally hidden
 and returned as `null`; no cross-Program Process handle enters the client. If
@@ -112,10 +131,15 @@ 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.
+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` Client may own one authoritative host-rendered Surface.
-The capability is command-only: Program code may change or remove it, but
-cannot read or subscribe to its server-owned state:
+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:
 
 ```ts
 await window.surface.set({
@@ -127,14 +151,18 @@ await window.surface.set({
 await window.surface.remove()
 ```
 
-The server stores the target beside its Window and delivers it internally to
-the desktop. `set()` with no settings creates a sharp, fully opaque Surface.
+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.
 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
 node. The optional transaction uses milliseconds and a stable named or cubic
 Bézier easing; the desktop performs the motion, honors reduced motion, and does
-does not replay a stored transaction when restoring desktop state. The sharp
+does not restore anything when a new iframe representation begins. The sharp
 container follows the iframe geometry while the independently rounded Surface
 neither clips nor masks Client content. `window` and `wallpaper` layers reject
 the capability.

package/dist/current.d.ts

@@ -8,6 +8,8 @@ export interface Current<Events extends object = {}> extends Channel<Events>, Pi
     readonly server: CurrentServer;
     /** Presentation capability of this current Client. */
     readonly window: Window;
+    /** The same permission capability exposed by the current Program. */
+    readonly permissions: Program["permissions"];
     /** Returns the Process represented by this Client. */
     process(): Promise<Process>;
     /** Returns the accessible parent Process, or `null` when none exists. */

package/dist/current.js

@@ -3,6 +3,7 @@ import Deadline from "./deadline.js";
 import { Client, Server, ServerTrafficHandle, TrafficHandle, bindEvents, endpointEvents, process, program, window as windowHandle } from "./domain.js";
 import wire from "./wire.js";
 import { endpointService } from "./service.js";
+import { currentProgramPermissions } from "./permissions.js";
 const ServerBase = Server;
 const ClientBase = Client;
 class CurrentServerHandle extends ServerBase {
@@ -83,6 +84,7 @@ currentClient = new CurrentClientHandle(owner);
 class ClientCurrent {
     server = currentServer;
     window = currentClient.window;
+    permissions = currentProgramPermissions;
     constructor() {
         bindChannel(this, channel);
     }

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 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 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 Events from "./events.js";
 export interface HandleAddress {
     identity: string;
@@ -31,6 +31,8 @@ export interface EndpointReference {
 export type WindowRecord = WindowState;
 /** Program handle visible inside a structurally isolated Client. */
 export type Program<Events extends object = {}> = Omit<CoreProgram<Events>, "processes" | "firstProcess" | "lastProcess" | "getProcess" | "createProcess"> & {
+    /** Effective permission decisions owned by this Program. */
+    readonly permissions: Permissions;
     /** Returns every live Process of this Program visible to the current Client. */
     processes(): Promise<Process[]>;
     /** Returns the earliest-started visible live Process, or `null` when none exist. */
@@ -102,11 +104,20 @@ export type Client<Events extends object = {}> = Omit<CoreClient<Events>, "proce
 };
 /** 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>;
+}
 export declare class TrafficHandle extends Events {
     protected readonly target: HandleAddress | null;
     protected readonly kind: "server" | "client";

package/dist/domain.js

@@ -5,6 +5,7 @@ import HandleRegistry from "./handle-registry.js";
 import { area, sql, store } from "./storage.js";
 import wire from "./wire.js";
 import { endpointService } from "./service.js";
+import { currentProgramPermissions } from "./permissions.js";
 const handles = new HandleRegistry();
 const ProgramBase = CoreProgram;
 const ProcessBase = CoreProcess;
@@ -18,6 +19,7 @@ class ProgramHandle extends ProgramBase {
     store = store();
     logs = sql("logs");
     database = sql("database");
+    permissions = currentProgramPermissions;
     record;
     constructor(record) {
         super();
@@ -208,7 +210,7 @@ class WindowHandle extends Events {
     constructor(target) {
         super(...deferredScoped("host-end", target, (_event, values) => values[0]));
         this.target = target;
-        this.surface = new WindowSurfaceHandle(target);
+        this.surface = new ClientWindowSurfaceHandle(target);
     }
     async state() {
         const answer = await wire.request(["window", await this.target()]);
@@ -224,12 +226,13 @@ class WindowHandle extends Events {
     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 WindowSurfaceHandle {
+class ClientWindowSurfaceHandle {
     target;
     constructor(target) {
         this.target = target;
@@ -260,7 +263,7 @@ function deferredScoped(route, target, convert) {
     ];
 }
 function windowEvent(event) {
-    return event === "move" || event === "resize" || event === "minimize" || event === "changeTitle" || event === "front";
+    return event === "move" || event === "resize" || event === "geometry" || event === "minimize" || event === "changeTitle" || event === "front";
 }
 function deferred(target, register, impossible) {
     let active = true;

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-import type { ClientServiceHandler, Permissions, ServedFile, ServerServiceHandler, Theme, ThemeProperties } from "@phreshos/core";
+import type { ClientServiceHandler, ServedFile, ServerServiceHandler, Theme, ThemeProperties } from "@phreshos/core";
 import { type HostPointer } from "./pointer.js";
 import { type HostSurface } from "./surface.js";
 /** Desktop capabilities structurally available to a Client endpoint. */
@@ -9,8 +9,6 @@ export interface Host {
     readonly surface: HostSurface;
     /** Permission-guarded desktop pointer reads and live movement. */
     readonly pointer: HostPointer;
-    /** Permission decisions for capabilities guarded by the desktop. */
-    readonly permissions: Permissions;
     /** Stores one value as a publicly reachable file. */
     serve(value: unknown): Promise<ServedFile>;
     /** Performs an unrestricted server-side fetch on behalf of this Client. */

package/dist/host.js

@@ -1,7 +1,6 @@
 import { content } from "./content.js";
 import ClientTheme from "./theme.js";
 import wire from "./wire.js";
-import ClientPermissions from "./permissions.js";
 import ClientPointer, {} from "./pointer.js";
 import ClientSurface, {} from "./surface.js";
 import { service as serviceHandle } from "./service.js";
@@ -9,7 +8,6 @@ class ClientHost {
     theme = new ClientTheme();
     surface = new ClientSurface();
     pointer = new ClientPointer();
-    permissions = new ClientPermissions();
     async serve(value) {
         const source = content(value);
         const channel = new MessageChannel();

package/dist/main.d.ts

@@ -4,5 +4,5 @@ export { type HostSurface, type Surface, type SurfaceEvents } from "./surface.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 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, WindowLayer, WindowState, WindowSurface, WindowSurfaceEasing, WindowSurfaceSettings, WindowSurfaceTransaction } 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";

package/dist/permissions.d.ts

@@ -1,8 +1,10 @@
 import type { PermissionDecision, PermissionName, Permissions, TimedPermissions } from "@phreshos/core";
-/** Client permission access bound to the current Process boundary. */
+/** Client access to the current Program's effective permission decisions. */
 export default class ClientPermissions implements Permissions {
     granted(name: PermissionName): Promise<PermissionDecision>;
     request(name: PermissionName): Promise<PermissionDecision>;
     timeout(milliseconds: number): TimedPermissions;
     private requestWithin;
 }
+/** The one Program-owned permission capability visible in this isolated Client. */
+export declare const currentProgramPermissions: ClientPermissions;

package/dist/permissions.js

@@ -1,6 +1,6 @@
 import wire from "./wire.js";
 const defaultPermissionTimeout = 30_000;
-/** Client permission access bound to the current Process boundary. */
+/** Client access to the current Program's effective permission decisions. */
 export default class ClientPermissions {
     async granted(name) {
         const answer = await wire.request(["permission-granted", name]);
@@ -19,3 +19,5 @@ export default class ClientPermissions {
         return answer?.[0] ?? null;
     }
 }
+/** The one Program-owned permission capability visible in this isolated Client. */
+export const currentProgramPermissions = new ClientPermissions();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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.4"
+    "@phreshos/core": "^0.1.5"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.4",
+    "@phreshos/core": "^0.1.5",
     "typescript": "^6.0.3"
   }
 }