@phreshos/server 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Zohayr SLILEH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -17,30 +17,96 @@ It uses the domain objects and shared contracts from `@phreshos/core` through
 a peer dependency. It does not redefine those objects, own client-side
 capabilities, or contain host and transport implementations.
 
-Its `Host` contract exposes authoritative Program and Process discovery,
-runtime Program creation, lifecycle events, and publicly served values.
+Its `Host` contract exposes the observable system Theme with replacement
+authority, authoritative Program and Process discovery, runtime Program
+creation, lifecycle events, and publicly served values. `host.theme.snapshot()`
+explicitly and asynchronously reads the current value,
+`subscribe("change", listener)` receives only complete replacements published
+after registration, and `update()` asynchronously validates and replaces the
+Theme through the system authority. A subscription has no initial delivery or
+replay.
+
+`host.signInWallpaper` and `host.desktopWallpaper` are independent direct Host
+capabilities. A served image or HTML file is selected by its generated
+filename, while the desktop may instead select a Program that declares a
+Client:
+
+```ts
+const served = await host.serve(file)
+
+await host.signInWallpaper.set(served.file)
+await host.desktopWallpaper.set(served.file)
+await host.desktopWallpaper.setProgram(program, {
+  name: "wallpaper",
+  server: false,
+  client: { location: "/ambient" },
+  options: { mode: "calm" }
+})
+
+await host.signInWallpaper.remove()
+await host.desktopWallpaper.remove()
+```
+
+Selecting or removing a desktop choice exits the previous wallpaper Process.
+Its Client and visual state are system-managed; complete Process exit remains
+available and reveals the bundled desktop fallback.
 
 Its JavaScript entry point adapts the Process IPC boundary to these contracts.
 The SDK owns callbacks, waits, queues, and their cleanup; the boundary owns
 only the forwarding registrations requested by the SDK.
 
+Importing the SDK injects no message into the child process. The endpoint may
+announce its readiness outward, but identity, Theme, Process, readiness,
+lifecycle, and application values enter only in response to an explicit request
+or a live registration made by Program code.
+
 `Current` combines navigation into the executing Server's Process with its
-inbound subscription and answer Channel. The paired Client is explicitly named
+Channel and answer registry. The paired Client is explicitly named
 as `current.client`; its publishing, existence, lifecycle, and Window operations
 never masquerade as properties of `current`. `current.stop()` stops the
 executing Server, while complete Process exit remains available only through
-`current.process()`.
+`current.process()`. It is the canonical Process-owned handle, so
+`current.client === (await current.process()).client`.
+Endpoint `process()` navigation is asynchronous; contextual ownership is
+requested only when navigation needs it and then retained by the SDK.
+
+All domain handles are canonical within this Server runtime's JavaScript realm.
+Lookup, navigation, event payloads, and message metadata reuse the same weakly
+retained handle. Server and Client handles remain stable for their Process
+lifetime. Each Client permanently owns one synchronous `window` capability,
+whose operations address that Client's current live presentation state.
+
+An `under` or `over` Client Window may own an authoritative host Surface through
+`client.window.surface`. It is command-only: `set()` or `remove()` changes the
+server-owned value, while Program endpoints cannot read or subscribe to it.
+Radius may be a
+nonnegative pixel number, `"full"`, or a semantic `ScaleLevel` resolved by the
+desktop against its current Theme. Ordinary `window` and system `wallpaper`
+layers reject Surface mutations.
 
-The package provides two contextual values rather than constructors:
+The package provides two contextual runtime entry points:
 
 ```ts
 import { host, current } from "@phreshos/server"
 ```
 
+It also re-exports the shared Core runtime classes—`Program`, `Process`,
+`Endpoint`, `Server`, and `Client`—and refines the handles returned through
+them. These are the same domain classes used by the Client SDK, so
+`instanceof Server` and `instanceof Client` retain one meaning. `Window`, like
+`ClientTraffic`, is a type-only capability owned by Client and has no
+independent `instanceof` identity.
+
 The current Server's Channel is composed directly into `current`. It receives
-addressed events and registers answerers for questions arriving at this Server.
-Answer registration returns its sole cleanup function. Publishing to the paired
-Client belongs to `current.client`.
+addressed events, emits destinationless events through `publish()`, and
+registers answerers for questions arriving at this Server. An answerer that
+omits its return value successfully answers with `undefined`. Answer
+registration returns its sole cleanup function. Directed publishing to the
+paired Client belongs to `current.client`.
+
+An Endpoint handle is also a selective source: `endpoint.subscribe()` follows
+destinationless events emitted by that Endpoint. Its `traffic` property remains
+reserved for directed publications, questions, and answers.
 
 `server.ask()` does not route a question before the addressed Server
 incarnation is ready. The Server SDK owns one deadline across readiness and the
@@ -52,3 +118,28 @@ also expose `path()` and traversal-safe `resolve()`, because filesystem work is
 performed locally in the Server SDK after the Host supplies only the area root.
 Object descriptions passed to `host.createProgram()` therefore require an
 explicit absolute storage root as well as at least one declared Endpoint.
+
+`program.icon()` requests a guaranteed PNG `Blob` in `small`, `medium`, or
+`large` form without exposing the Program's source path or the system's private
+asset-hosting address. Omitting the size selects `medium`.
+
+Installed Programs may persist one ordinary Process launch for the next system
+startup. This capability exists only in the Server SDK:
+
+```ts
+await program.startup.enable({
+  name: "main",
+  server: true,
+  client: false,
+  options: { mode: "worker" }
+})
+
+const launch = await program.startup.get() // Launch | null
+
+await program.startup.disable()
+```
+
+The system validates this through the same launch contract as
+`createProcess()`. Setting startup does not create a Process immediately.
+`uninstall(false)` preserves the configuration but makes it inactive until the
+Program is installed again; removing everything deletes it.

package/dist/channel.d.ts

@@ -1,6 +1,9 @@
 import type { Channel as CoreChannel, ChannelMessage, Cleanup } from "@phreshos/core";
-export type Answerer<Payload = unknown, Result = unknown> = (message: ChannelMessage<Payload>) => Result | Promise<Result>;
+/** Handles one question addressed to the current Server. */
+export type Answerer<Payload = unknown, Result = undefined> = (message: ChannelMessage<Payload>) => Result | Promise<Result>;
+/** Events and questions explicitly accepted by the current Server. */
 export interface Channel<Events extends object = {}> extends CoreChannel<Events> {
-    answer<Payload = unknown, Result = unknown>(event: string, answerer: Answerer<Payload, Result>): Cleanup;
+    /** Registers one answerer; omitting its return produces `undefined`. */
+    answer<Payload = unknown, Result = undefined>(event: string, answerer: Answerer<Payload, Result>): Cleanup;
 }
 export declare const channel: Channel;

package/dist/channel.js

@@ -8,6 +8,9 @@ class ServerChannel extends Events {
                 observer(event, message(value));
         }));
     }
+    publish(event, payload = undefined) {
+        wire.send("end-host", "emit", event, payload);
+    }
     answer(event, answerer) {
         return wire.answer("end-end", event, value => answerer(message(value)));
     }

package/dist/current.d.ts

@@ -1,21 +1,24 @@
-import type { Channel as CoreChannel, LaunchClient, Publishable } from "@phreshos/core";
+import type { Channel as CoreChannel } from "@phreshos/core";
 import { type Answerer } from "./channel.js";
-import { type Process, type Program, type Window } from "./domain.js";
-/** The paired Client as addressed from the currently executing Server. */
-export interface CurrentClient extends Publishable {
-    exists(): Promise<boolean>;
-    start(overrides?: LaunchClient): Promise<void>;
-    stop(): Promise<void>;
-    window(): Promise<Window>;
-}
+import { Client, type Process, type Program } from "./domain.js";
+/** The current Process's canonical Client handle. */
+export type CurrentClient<Events extends object = {}> = Client<Events>;
 /** Current Server context: its inbound Channel, owner hierarchy, and paired Client. */
 export interface Current<Events extends object = {}> extends CoreChannel<Events> {
+    /** The same Client handle exposed by the current Process. */
     readonly client: CurrentClient;
-    answer<Payload = unknown, Result = unknown>(event: string, answerer: Answerer<Payload, Result>): () => void;
+    /** Registers one answerer; omitting its return produces `undefined`. */
+    answer<Payload = unknown, Result = undefined>(event: string, answerer: Answerer<Payload, Result>): () => void;
+    /** Returns the Process represented by this Server. */
     process(): Promise<Process>;
+    /** Returns the parent Process, or `null` when this Process has none. */
     parent(): Promise<Process | null>;
+    /** Returns the Program that owns this Server. */
     program(): Promise<Program>;
+    /** Returns one immutable option supplied when this Process was created. */
     option(name: string): Promise<string | undefined>;
+    /** Stops the current Server; rejects when it is the final live Endpoint. */
     stop(): Promise<void>;
 }
+/** Inbound events, owner hierarchy, and paired Client for the current Server. */
 export declare const current: Current;

package/dist/current.js

@@ -1,8 +1,21 @@
 import { channel } from "./channel.js";
-import { process, program } from "./domain.js";
+import { Client, TrafficHandle, bindEvents, endpointEvents, process, program, window } from "./domain.js";
 import wire from "./wire.js";
-class PairedClient {
-    publish(event, payload) { wire.send("end-end", event, payload); }
+const ClientBase = Client;
+class CurrentClientHandle extends ClientBase {
+    owner;
+    traffic = new TrafficHandle(null, "client");
+    window = window(async () => {
+        const identity = await wire.identity();
+        return { identity: identity.process, reference: identity.reference };
+    });
+    constructor(owner) {
+        super();
+        this.owner = owner;
+        bindEvents(this, endpointEvents(null, "client"));
+    }
+    process() { return this.owner(); }
+    publish(event, payload = undefined) { wire.send("end-end", event, payload); }
     async exists() {
         const answer = await wire.request(["exists", "client"]);
         return answer[0];
@@ -11,20 +24,33 @@ class PairedClient {
         await wire.request(["start-endpoint", undefined, "client", overrides]);
     }
     async stop() { await wire.request(["stop-endpoint", undefined, "client"]); }
-    async window() { return (await current.process()).client.window(); }
 }
+let ownerPromise = null;
+let currentClient;
+function owner() {
+    if (!ownerPromise) {
+        const resolving = wire.request(["process"]).then(answer => {
+            return process(answer[0], { client: currentClient });
+        });
+        const retained = resolving.catch(error => {
+            if (ownerPromise === retained)
+                ownerPromise = null;
+            throw error;
+        });
+        ownerPromise = retained;
+    }
+    return ownerPromise;
+}
+currentClient = new CurrentClientHandle(owner);
 class ServerCurrent {
-    client = new PairedClient();
+    client = currentClient;
     constructor() {
         bindChannel(this, channel);
     }
     answer(event, answerer) {
         return channel.answer(event, answerer);
     }
-    async process() {
-        const answer = await wire.request(["process"]);
-        return process(answer[0]);
-    }
+    process() { return owner(); }
     async parent() {
         const answer = await wire.request(["parent"]);
         return answer[0] ? process(answer[0]) : null;
@@ -41,10 +67,12 @@ class ServerCurrent {
 }
 function bindChannel(target, source) {
     Object.assign(target, {
+        publish: source.publish.bind(source),
         subscribe: source.subscribe.bind(source),
         waitFor: source.waitFor.bind(source),
         events: source.events.bind(source),
         observe: source.observe.bind(source)
     });
 }
+/** Inbound events, owner hierarchy, and paired Client for the current Server. */
 export const current = new ServerCurrent();

package/dist/domain.d.ts

@@ -1,23 +1,31 @@
-import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, Window as CoreWindow, type ClientDeclaration, type EndpointDeclaration, type Exit, type Launch, type ProgramArea as CoreProgramArea, type TrafficMessage } from "@phreshos/core";
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture, type AskCapture, type Cleanup, type ClientDeclaration, type EndpointDeclaration, type Exit, type Launch, type ProgramPermissions, type ProgramArea as CoreProgramArea, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
 import Events from "./events.js";
+import { type ProgramStartup } from "./startup.js";
+export interface HandleAddress {
+    identity: string;
+    reference: string;
+}
 /** Server-side filesystem storage with access to its resolved host path. */
 export interface ProgramArea extends CoreProgramArea {
+    /** Returns the absolute host path of this storage area. */
     path(): Promise<string>;
+    /** Resolves path segments within this storage area without permitting escape. */
     resolve(...path: string[]): Promise<string>;
 }
 /** Client-safe Program data transported by the authoritative host. */
 export interface ProgramRecord {
+    reference: string;
     identity: string;
     installed?: boolean;
     name: string;
     version: string | null;
     description: string | null;
-    icons?: boolean;
     server: EndpointDeclaration | null;
     client: ClientDeclaration | null;
 }
 /** Process data transported with every Endpoint reference. */
 export interface ProcessRecord {
+    reference: string;
     identity: string;
     name: string | null;
     program: ProgramRecord;
@@ -30,62 +38,97 @@ export interface EndpointReference {
     kind: "server" | "client";
     process: ProcessRecord;
 }
+export type WindowRecord = WindowState;
 /** Server-visible Program handle and privileged Program operations. */
 export interface Program<Events extends object = {}> extends CoreProgram<Events> {
+    /** Persistent filesystem data shared by every Process of this Program. */
     readonly data: ProgramArea;
+    /** Disposable filesystem data shared by every Process of this Program. */
     readonly cache: ProgramArea;
+    /** Persistent Process launch used when the system starts. */
+    readonly startup: ProgramStartup;
+    /** Persistent permission decisions owned by this Program. */
+    readonly permissions: ProgramPermissions;
+    /** Returns every live Process of this Program. */
     processes(): Promise<Process[]>;
+    /** Returns the earliest-started live Process, or `null` when none exist. */
+    firstProcess(): Promise<Process | null>;
+    /** Returns the latest-started live Process, or `null` when none exist. */
+    lastProcess(): Promise<Process | null>;
+    /** Finds a live Process by runtime identity or Program-local name. */
     getProcess(identityOrName: string): Promise<Process | null>;
+    /** Creates one Process of this Program. */
     createProcess(launch?: Launch): Promise<Process>;
+    /** Installs this Program and returns the same handle. */
     install(): Promise<this>;
+    /** Creates a new runtime Program with the supplied stable identity. */
     fork(identity: string): Promise<Program>;
 }
 /** Server-visible Process handle. */
 export interface Process<Events extends object = {}> extends CoreProcess<Events> {
+    /** Permanent handle to this Process's Server. */
     readonly server: Server;
+    /** Permanent handle to this Process's Client. */
     readonly client: Client;
+    /** Returns the Program that owns this Process. */
     program(): Program;
+    /** Returns the parent Process, or `null` when this Process has none. */
     parent(): Promise<Process | null>;
 }
 /** Server-visible common Endpoint handle. */
 export interface Endpoint<Events extends object = {}> extends CoreEndpoint<Events> {
-    process(): Process;
+    /** Returns the Process that owns this Endpoint. */
+    process(): Promise<Process>;
 }
 /** Server-visible Server handle. */
 export interface Server<Events extends object = {}> extends CoreServer<Events> {
-    process(): Process;
+    /** Returns the Process that owns this Server. */
+    process(): Promise<Process>;
 }
 /** Server-visible Client handle. */
 export interface Client<Events extends object = {}> extends CoreClient<Events> {
-    process(): Process;
-    window(): Promise<Window>;
+    /** Presentation capability permanently owned by this Client handle. */
+    readonly window: Window;
+    /** Returns the Process that owns this Client. */
+    process(): Promise<Process>;
+}
+/** Server-visible Client-owned Window capability. */
+export type Window = CoreWindow;
+/** Internal transport address for a Program handle created by this SDK. */
+export declare function programAddress(value: Program): HandleAddress;
+export declare class TrafficHandle extends Events {
+    protected readonly target: HandleAddress | null;
+    protected readonly kind: "server" | "client";
+    constructor(target: HandleAddress | null, kind: "server" | "client");
+    observeAsks(observer: (capture: AskCapture) => unknown): Cleanup;
 }
-/** Server-visible authoritative Window handle. */
-export interface Window<Events extends object = {}> extends CoreWindow<Events> {
-    client(): Client;
+export declare class ServerTrafficHandle extends TrafficHandle {
+    observeAnswers(observer: (capture: AnswerCapture) => unknown): Cleanup;
 }
+type WindowTarget = () => Promise<HandleAddress>;
 export declare function scoped(route: string, subject: string | null, convert: (event: string, values: unknown[]) => unknown): Events;
+/** Destinationless events originating from one Endpoint handle. */
+export declare function endpointEvents(target: HandleAddress | null, half: "server" | "client"): Events;
+export declare function lifecycleEndpoint(record: unknown, kind: unknown): Server<{}> | Client<{}>;
 export declare function exit(code: unknown, signal: unknown): Exit;
 export declare function trafficMessage(value: unknown): TrafficMessage;
 export declare function bindEvents(target: object, events: Events): void;
 export declare function program(record: ProgramRecord): Program;
-export declare function process(record: ProcessRecord): Process;
+export declare function process(record: ProcessRecord, endpoints?: {
+    server?: Server;
+    client?: Client;
+}): Process;
 export declare function endpoint(reference: EndpointReference | undefined): Endpoint;
-export declare const Program: {
-    new <Events extends object = {}>(): Program<Events>;
-};
-export declare const Process: {
-    new <Events extends object = {}>(): Process<Events>;
-};
-export declare const Endpoint: {
-    new <Events extends object = {}>(): Endpoint<Events>;
-};
-export declare const Server: {
-    new <Events extends object = {}>(): Server<Events>;
-};
-export declare const Client: {
-    new <Events extends object = {}>(): Client<Events>;
-};
-export declare const Window: {
-    new <Events extends object = {}>(): Window<Events>;
-};
+export declare function claimEndpoint(reference: string, kind: "server" | "client", endpoint: Endpoint): Endpoint<{}>;
+export declare function window(target: WindowTarget): Window;
+/** Runtime constructor used to identify and type Server-visible Program handles. */
+export declare const Program: typeof CoreProgram;
+/** Runtime constructor used to identify and type Server-visible Process handles. */
+export declare const Process: typeof CoreProcess;
+/** Runtime constructor used to identify and type Server-visible Endpoint handles. */
+export declare const Endpoint: typeof CoreEndpoint;
+/** Runtime constructor used to identify and type Server-visible Server handles. */
+export declare const Server: typeof CoreServer;
+/** Runtime constructor used to identify and type Server-visible Client handles. */
+export declare const Client: typeof CoreClient;
+export {};