@phreshos/client 0.1.18 → 0.1.20

package/README.md

@@ -15,26 +15,27 @@ provide its runtime environment.
 
 It uses the domain objects and shared contracts from `@phreshos/core` through
 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, 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:
-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.
+capabilities, or contain System and transport implementations.
+
+Its `System` contract exposes only desktop-session capabilities: read-only
+System Appearance, the mutable Theme local to this Desktop, desktop and pointer
+state, publicly served values, and unrestricted server-side Fetch.
+`system.appearance.snapshot()` reads complete unresolved authoritative state.
+`system.theme.snapshot()` reads only the effective `"light" | "dark"` mode;
+`update("default")` resumes following the native environment. Both expose
+ordinary live-only `change` subscriptions with no initial replay. A Client
+cannot write authoritative Appearance or discover system-wide Programs and
+Processes.
 
 Desktop and pointer access are independent objects rather than events merged
-into Host:
+into System:
 
 ```ts
-const desktop = await host.desktop.size()
-const stopDesktop = host.desktop.subscribe("resize", next => undefined)
+const desktop = await system.desktop.size()
+const stopDesktop = system.desktop.subscribe("resize", next => undefined)
 
-const position = await host.pointer.position()
-const stopPointer = host.pointer.subscribe("move", next => undefined)
+const position = await system.pointer.position()
+const stopPointer = system.pointer.subscribe("move", next => undefined)
 ```
 
 The desktop size is the complete desktop area containing this Client,
@@ -44,7 +45,7 @@ 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.
+Permission decisions belong to the current Program, not to the desktop System.
 They are available from a Program handle and flattened through `current` as the
 same canonical capability:
 
@@ -61,13 +62,13 @@ current.permission === program.permission
 `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`.
+permission ownership does not alter the public shape of `system`.
 
-The Client Host exposes only direct, exact Service handles. Creating a handle
+The Client System exposes only direct, exact Service handles. Creating a handle
 does not read or start the Service and exposes no Service registry:
 
 ```ts
-const service = host.service({
+const service = system.service({
   program: "counter",
   endpoint: "server",
   name: "state"
@@ -115,7 +116,7 @@ absence or incarnation loss rejects without turning the boundary into a waiter.
 The package provides two contextual runtime entry points:
 
 ```ts
-import { host, current } from "@phreshos/client"
+import { system, current } from "@phreshos/client"
 ```
 
 It also re-exports the shared Core runtime classes—`Program`, `Process`,
@@ -137,12 +138,12 @@ reserved for directed publications, questions, and answers.
 
 Messages sent by an Endpoint in the same Program contain that real Endpoint in
 `from`. If the sender belongs to another Program, `from` is `null`; the foreign
-identity is removed by the server host before the message reaches the desktop.
+identity is removed by the authoritative System before the message reaches the desktop.
 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` values never
-expose host filesystem paths. Every Client-side Window handle exposes the same
+expose native 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
@@ -177,30 +178,26 @@ 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` representation may request one local host-rendered Surface:
+An `under` or `over` representation may request one local system-rendered Surface:
 
 ```ts
-await current.window.local.surface.set({
-  opacity: 0.65,
-  radius: "large"
-}, { duration: 240, easing: "ease-out", wait: true })
+await current.window.local.surface.set({ duration: 240, easing: "ease-out", wait: true })
 
-await current.window.local.surface.remove()
+await current.window.local.surface.remove({ duration: 180, easing: "ease-in" })
 ```
 
 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
-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 restore anything when a new iframe representation begins. The sharp
+synchronize desired presence through its Server and explicitly apply it
+again. `set()` and `remove()` accept only a required `VisibilityTransition`;
+Programs cannot configure the System Surface's material, opacity, or radius.
+The transition uses milliseconds and a stable named or cubic Bézier easing;
+the desktop performs the motion, honors reduced motion, and removes the Surface
+only after its exit transition completes. `wait: true` makes the request settle
+with that transition. A new iframe representation restores nothing. The
 container follows the iframe geometry while the independently rounded Surface
-neither clips nor masks Client content. `window` and `wallpaper` layers reject
+neither clips nor masks Client content. The ordinary `window` layer rejects
 the capability.
 
 `program.icon()` requests the current Program's guaranteed PNG `Blob` on

package/dist/appearance.d.ts

@@ -0,0 +1,15 @@
+import Events from "./events.js";
+/** Read-only System Appearance reached through the Desktop boundary. */
+export default class ClientAppearance extends Events {
+    constructor();
+    snapshot(): Promise<Readonly<{
+        background: import("@phreshos/core").ThemedValue<string, string>;
+        foreground: import("@phreshos/core").ThemedValue<string, string>;
+        accent: import("@phreshos/core").ThemedValue<string, string>;
+        spacing: import("@phreshos/core").ThemedValue<number>;
+        radius: import("@phreshos/core").ThemedValue<number>;
+        surface: import("@phreshos/core").ThemedValue<import("@phreshos/core").AppearanceSurface, import("@phreshos/core").AppearanceSurface>;
+        signInWallpaper: import("@phreshos/core").ThemedValue<string | null, string | null>;
+        desktopWallpaper: import("@phreshos/core").ThemedValue<string | null, string | null>;
+    }>>;
+}

package/dist/appearance.js

@@ -0,0 +1,18 @@
+import { createAppearanceSnapshot } from "@phreshos/core";
+import Events from "./events.js";
+import wire from "./wire.js";
+/** Read-only System Appearance reached through the Desktop boundary. */
+export default class ClientAppearance extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("host-appearance", event, value => {
+            listener(createAppearanceSnapshot(value));
+        }, null, impossible), observer => wire.onAll("host-appearance", (event, value) => {
+            if (typeof event === "string")
+                observer(event, createAppearanceSnapshot(value));
+        }));
+    }
+    async snapshot() {
+        const [appearance] = await wire.request(["appearance"]);
+        return createAppearanceSnapshot(appearance);
+    }
+}

package/dist/desktop.d.ts

@@ -11,7 +11,7 @@ export type DesktopEvents = {
     resize: DesktopSize;
 };
 /** Explicit desktop size reads and future resizes. */
-export interface HostDesktop extends Subscribable<DesktopEvents, never> {
+export interface SystemDesktop extends Subscribable<DesktopEvents, never> {
     /** Reads the complete current desktop area in CSS pixels. */
     size(): Promise<DesktopSize>;
 }

package/dist/desktop.js

@@ -17,7 +17,7 @@ export default class ClientDesktop extends Events {
         const answer = await wire.request(["desktop"]);
         const size = createSize(answer[0]);
         if (!size)
-            throw new Error("The host returned an invalid desktop size");
+            throw new Error("The system returned an invalid desktop size");
         return size;
     }
 }

package/dist/domain.js

@@ -308,10 +308,12 @@ class LocalWindowSurfaceHandle {
     constructor(target) {
         this.target = target;
     }
-    async set(settings = {}, transaction) {
-        await wire.request(["windowLocalSurfaceSet", await this.target(), settings, transaction]);
+    async set(transition) {
+        await wire.request(["windowLocalSurfaceSet", await this.target(), transition]);
+    }
+    async remove(transition) {
+        await wire.request(["windowLocalSurfaceRemove", await this.target(), transition]);
     }
-    async remove() { await wire.request(["windowLocalSurfaceRemove", await this.target()]); }
 }
 function deferredScoped(route, target, convert) {
     return [
@@ -408,7 +410,7 @@ function lifecycleEndpoint(record, kind) {
         return owner.server;
     if (kind === "client")
         return owner.client;
-    throw new Error("The host returned an invalid Endpoint lifecycle event");
+    throw new Error("The system returned an invalid Endpoint lifecycle event");
 }
 export function exit(code, signal) {
     const namedSignal = stringOrNull(signal);

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 DesktopEvents, type DesktopSize, type HostDesktop } from "./desktop.js";
+export { system, type System } from "./system.js";
+export { type SystemPointer, type PointerEvents, type PointerPosition } from "./pointer.js";
+export { type DesktopEvents, type DesktopSize, type SystemDesktop } 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 Window, type ProgramProcess, 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, Permission, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Theme, ThemeEvents, ThemeProperties, Value, WritableTheme, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, SurfaceSettings, Transaction } from "@phreshos/core";
+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, Permission, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, SystemTheme, ThemedValue, Theme, ThemeEvents, ThemePreference, Value, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, VisibilityTransition, Transaction } from "@phreshos/core";

package/dist/main.js

@@ -1,4 +1,4 @@
-export { host } from "./host.js";
+export { system } from "./system.js";
 export {} from "./pointer.js";
 export {} from "./desktop.js";
 export { current } from "./current.js";

package/dist/pointer.d.ts

@@ -13,7 +13,7 @@ export type PointerEvents = {
     move: PointerPosition;
 };
 /** Permission-guarded pointer positions and future movement. */
-export interface HostPointer extends Subscribable<PointerEvents, never> {
+export interface SystemPointer extends Subscribable<PointerEvents, never> {
     /**
      * Reads the current desktop pointer position, or `null` before one is known.
      * Rejects unless the `pointer` permission is currently granted.

package/dist/{host.d.ts → system.d.ts}

@@ -1,19 +1,21 @@
-import type { ClientServiceHandler, ServedFile, ServerServiceHandler, ServiceKey, Theme, ThemeProperties } from "@phreshos/core";
-import { type HostPointer } from "./pointer.js";
-import { type HostDesktop } from "./desktop.js";
+import type { AppearanceSource, ClientServiceHandler, ServedFile, ServerServiceHandler, ServiceKey, SystemTheme } from "@phreshos/core";
+import { type SystemPointer } from "./pointer.js";
+import { type SystemDesktop } from "./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> = Endpoint extends "server" ? ServerServiceHandler<Events> : ClientServiceHandler<Events>;
 /** 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>;
+export interface System {
+    /** Complete unresolved Appearance read from the System authority. */
+    readonly appearance: AppearanceSource;
+    /** Mutable effective Theme local to this Desktop. */
+    readonly theme: SystemTheme;
     /** Layer-independent desktop size reads and live updates. */
-    readonly desktop: HostDesktop;
+    readonly desktop: SystemDesktop;
     /** Permission-guarded desktop pointer reads and live movement. */
-    readonly pointer: HostPointer;
+    readonly pointer: SystemPointer;
     /** Stores one value as a publicly reachable file. */
     serve(value: unknown): Promise<ServedFile>;
     /** Performs an unrestricted server-side fetch on behalf of this Client. */
@@ -26,5 +28,5 @@ export interface Host {
     service<ServiceEvents extends object>(key: ServiceAddress<"client">): ClientServiceHandler<ServiceEvents>;
 }
 /** Desktop capabilities available to this Client. */
-export declare const host: Host;
+export declare const system: System;
 export {};

package/dist/{host.js → system.js}

@@ -1,10 +1,12 @@
+import ClientAppearance from "./appearance.js";
 import { content } from "./content.js";
 import ClientTheme from "./theme.js";
 import wire from "./wire.js";
 import ClientPointer, {} from "./pointer.js";
 import ClientDesktop, {} from "./desktop.js";
 import { prepareService } from "./service.js";
-class ClientHost {
+class ClientSystem {
+    appearance = new ClientAppearance();
     theme = new ClientTheme();
     desktop = new ClientDesktop();
     pointer = new ClientPointer();
@@ -121,4 +123,4 @@ function closeControl(signal, port, abort) {
     port.close();
 }
 /** Desktop capabilities available to this Client. */
-export const host = new ClientHost();
+export const system = new ClientSystem();

package/dist/theme.d.ts

@@ -1,13 +1,8 @@
+import { type Theme, type ThemePreference } from "@phreshos/core";
 import Events from "./events.js";
-/** Read-only system Theme reached explicitly through the desktop boundary. */
+/** Mutable Theme local to the current Desktop. */
 export default class ClientTheme extends Events {
     constructor();
-    snapshot(): Promise<Readonly<{
-        background: string;
-        foreground: string;
-        accent: string;
-        spacing: number;
-        radius: number;
-        surface: import("@phreshos/core").ThemeSurface;
-    }>>;
+    snapshot(): Promise<Theme>;
+    update(theme: ThemePreference): Promise<void>;
 }

package/dist/theme.js

@@ -1,18 +1,19 @@
-import { createThemeSnapshot } from "@phreshos/core";
+import {} from "@phreshos/core";
 import Events from "./events.js";
 import wire from "./wire.js";
-/** Read-only system Theme reached explicitly through the desktop boundary. */
+/** Mutable Theme local to the current Desktop. */
 export default class ClientTheme extends Events {
     constructor() {
-        super((event, listener, impossible) => wire.on("host-theme", event, value => {
-            listener(createThemeSnapshot(value));
-        }, null, impossible), observer => wire.onAll("host-theme", (event, value) => {
+        super((event, listener, impossible) => wire.on("host-theme", event, value => listener(value), null, impossible), observer => wire.onAll("host-theme", (event, value) => {
             if (typeof event === "string")
-                observer(event, createThemeSnapshot(value));
+                observer(event, value);
         }));
     }
     async snapshot() {
         const [theme] = await wire.request(["theme"]);
-        return createThemeSnapshot(theme);
+        return theme;
+    }
+    async update(theme) {
+        await wire.request(["update-theme", theme]);
     }
 }

package/dist/wire.js

@@ -12,7 +12,6 @@ class Wire {
     impossible = new Map();
     identityPromise = null;
     constructor() {
-        this.send("boundary", "document", crypto.randomUUID());
         window.addEventListener("message", event => {
             if (event.source !== this.parent || !Array.isArray(event.data))
                 return;
@@ -320,7 +319,7 @@ class Wire {
             stream.failure = new Error("The boundary produced a stream value before opening the stream");
         else if (operation === "data") {
             if (stream.queue.length >= maximumStreamQueue)
-                stream.failure = new Error(`Host stream queue exceeded its capacity of ${maximumStreamQueue}`);
+                stream.failure = new Error(`System stream queue exceeded its capacity of ${maximumStreamQueue}`);
             else
                 stream.queue.push(value);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -47,13 +47,13 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.14"
+    "@phreshos/core": "^0.1.17"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.14",
+    "@phreshos/core": "^0.1.17",
     "typescript": "^6.0.3"
   }
 }