@phreshos/client 0.1.19 → 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,7 +178,7 @@ 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({ duration: 240, easing: "ease-out", wait: true })
@@ -190,13 +191,13 @@ representation. Reloading or destroying it resets the representation from
 authoritative truth, while other desktops remain unaffected. Program code may
 synchronize desired presence through its Server and explicitly apply it
 again. `set()` and `remove()` accept only a required `VisibilityTransition`;
-Programs cannot configure the host Surface's material, opacity, or radius.
+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

@@ -410,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, VisibilityTransition, 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

@@ -319,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.19",
+  "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.15"
+    "@phreshos/core": "^0.1.17"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.15",
+    "@phreshos/core": "^0.1.17",
     "typescript": "^6.0.3"
   }
 }