@phreshos/client 0.1.33 → 0.1.35

package/README.md

@@ -1,10 +1,21 @@
 # `@phreshos/client`
 
-The SDK for a PhreshOS Program's Client Endpoint.
+The runtime adapter for a PhreshOS Program's Client Endpoint.
 
-The Client SDK adapts the Desktop boundary to the shared Core domain model. It
-exposes the same complete `system` contract as the Server and Node SDKs, the
-current Client `context`, and the Client's `desktop` environment.
+[Documentation](https://docs.phreshos.com/sdks/client) ·
+[Client Context](https://docs.phreshos.com/runtime/context) ·
+[Desktop](https://docs.phreshos.com/system/desktop) ·
+[Source](https://github.com/PhreshOS/client)
+
+## Role
+
+The Client SDK exposes three separate Core contracts inside a Client Endpoint:
+the global `system`, the current Client `context`, and the containing `desktop`.
+It adapts the Desktop boundary without defining client-specific versions of the
+shared Program, Process, Endpoint, or Service domains.
+
+The System enforces Client authority. The SDK carries requests and preserves
+canonical handles; it does not own authoritative state or visual components.
 
 ## Installation
 
@@ -17,55 +28,16 @@ current Client `context`, and the Client's `desktop` environment.
 
 `@phreshos/core` is a peer dependency.
 
-## Context
-
 ```ts
-import { context } from "@phreshos/client"
-
-context.subscribe("changed", message => {
-  console.log(message)
-})
-
-context.publish("changed", { value: 1 })
+import { context, desktop, system } from "@phreshos/client"
 
 const program = await context.program()
-const process = await context.process()
-const server = context.server
-const position = await context.window.position()
-await context.localWindow.move({ x: 20, y: 20 })
-```
-
-`context` belongs to the executing Client. It provides communication,
-navigation to its Program and Process, its paired Server, the authoritative
-current Window through `window`, and command-only control of the current
-Desktop representation through `localWindow`.
-
-## System
-
-```ts
-import { system } from "@phreshos/client"
-
-const appearance = await system.appearance.snapshot()
-const programs = await system.program.list()
-const processes = await system.process.list()
-```
-
-`system` is the complete global System contract sourced from Core.
-
-## Desktop
-
-```ts
-import { desktop } from "@phreshos/client"
-
-const surface = await desktop.surface.snapshot()
 const preferences = await desktop.preferences.snapshot()
+const appearance = await system.appearance.snapshot()
 ```
 
-Desktop capabilities remain separate from the global System and the current
-execution Context.
-
-Requests read current state. Subscriptions observe future publications and do
-not replay an initial value. Importing the SDK performs neither operation.
+See [Client SDK](https://docs.phreshos.com/sdks/client) for the complete entry
+points and authority boundary.
 
 ## Development
 
@@ -74,17 +46,21 @@ bun install --frozen-lockfile
 bun run verify
 ```
 
-`verify` checks the source, completion surface, build, and published package
-shape.
+`verify` checks the types and completions, builds the package, and validates its
+published shape.
 
-See the [Client and Server documentation](https://github.com/PhreshOS/docs/blob/main/content/docs/sdks/client-and-server.mdx)
-for the shared model and authority boundary.
+## Related repositories
 
-## Repository boundary
+- [`@phreshos/core`](https://github.com/PhreshOS/core) owns every shared
+  contract and domain class exposed here.
+- [`@phreshos/server`](https://github.com/PhreshOS/server) adapts the paired
+  Server Endpoint boundary.
+- [`@phreshos/react`](https://github.com/PhreshOS/react) adapts the Client
+  sources to React without depending on this package.
+- [PhreshOS System](https://github.com/PhreshOS/system) owns enforcement,
+  routing, and the Desktop host.
 
-This repository owns the Client runtime adapter. Core owns the domain model, the
-System owns enforcement and forwarding, React owns framework adaptation, and
-React UI owns visual interpretation.
+## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow and
 [SECURITY.md](SECURITY.md) for private vulnerability reporting.

package/dist/domain.d.ts

@@ -1,4 +1,4 @@
-import { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, type AnswerCapture as CoreAnswerCapture, type AnswerMessage as CoreAnswerMessage, type AnswerSubscriber as CoreAnswerSubscriber, type AskCapture as CoreAskCapture, type AskMessage as CoreAskMessage, type AskSubscriber as CoreAskSubscriber, type Cleanup, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type Exit, type EventOptions, type LocalWindow, type Outcome, type Position, type ProgramProcess as CoreProgramProcess, type ProgramProcessRunEvent as CoreProgramProcessRunEvent, type ProgramProcessRunOptions as CoreProgramProcessRunOptions, 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 { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, type AnswerCapture as CoreAnswerCapture, type AnswerMessage as CoreAnswerMessage, type AnswerOutcome, type AnswerSubscriber as CoreAnswerSubscriber, type AskCapture as CoreAskCapture, type AskMessage as CoreAskMessage, type AskSubscriber as CoreAskSubscriber, type Cleanup, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type Exit, type EventOptions, type LocalWindow, type Position, type ProgramProcess as CoreProgramProcess, type ProgramProcessRunEvent as CoreProgramProcessRunEvent, type ProgramProcessRunOptions as CoreProgramProcessRunOptions, 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;
@@ -101,7 +101,7 @@ export declare class ServerTrafficHandle extends TrafficHandle {
         questionId: string;
         message: Readonly<{
             to: Endpoint<{}, unknown> | null;
-            outcome: Outcome<unknown>;
+            outcome: AnswerOutcome<unknown>;
         }>;
     }>>;
     private followAnswers;

package/dist/domain.js

@@ -1,4 +1,4 @@
-import { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint } from "@phreshos/core";
+import { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint, parseClientPermissions } from "@phreshos/core";
 import Events, { stream } from "./events.js";
 import Deadline from "./deadline.js";
 import HandleRegistry from "./handle-registry.js";
@@ -106,7 +106,7 @@ function clientDeclaration(record) {
         position: record.position,
         layer: record.layer,
         minimize: record.minimize,
-        permissions: Object.freeze(Object.fromEntries(Object.entries(record.permissions).map(([name, values]) => [name, Object.freeze([...values])])))
+        permissions: parseClientPermissions(record.permissions)
     });
 }
 class ProgramProcessHandle {

package/dist/main.d.ts

@@ -1,6 +1,6 @@
 export { system } from "./system.js";
 export { desktop } from "./desktop/desktop.js";
 export { context, type Context, type ContextCapture, type ContextEvents, type ContextMessage, type ContextServer } from "./context.js";
-export { ClientService, ServerService, Service, type ServiceKey, } from "@phreshos/core";
+export { ClientService, ServerService, Service, clientPermissionCatalog, isPermissionName, type ServiceKey, } from "@phreshos/core";
 export { ClientEndpoint, Endpoint, Process, Program, ServerEndpoint, type Window, type ProgramProcess, type ProgramProcessRunEvent, type ProgramProcessRunOptions, type AnswerCapture, type AnswerMessage, type AnswerSubscriber, type AskCapture, type AskMessage, type AskSubscriber, type ClientTraffic, type EndpointTraffic, type ServerTraffic, type TrafficCapture, type TrafficEvents, type TrafficMessage } from "./domain.js";
-export type { Askable, ClientContext, Capture, Captures, CaptureSubscriber, ClientLaunch, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointLifecycle, EndpointLifecycleEvents, EntryStat, EventMessage, EventName, EventOptions, EventSubscriber, Exit, FileStat, Launch, ServerLaunch, ShellEvent, ShellOptions, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Permission, PermissionChange, PermissionInput, PermissionRequest, Permissions, ClientPermissionDeclarations, ClientPermissions, ContextPermissions, ProgramPermissions, TimedContextPermissions, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramStartup, ProgramSql, ProgramStore, ProcessEvents, Publishable, System, SystemUploads, Upload, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, Timeoutable, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, AnimationsPreference, DesktopPreferences, DesktopPreferencesEvents, DesktopPreferencesSource, DesktopPreferencesUpdate, Desktop, DesktopSize, DesktopSurfaceEvents, DesktopSurfaceSnapshot, DesktopSurfaceSource, WritableDesktopPreferencesSource, ThemedValue, Theme, ThemePreference, Value, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowOperations, Transaction } from "@phreshos/core";
+export type { Askable, AnswerOutcome, ClientContext, Capture, Captures, CaptureSubscriber, ClientLaunch, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointLifecycle, EndpointLifecycleEvents, EntryStat, EventMessage, EventName, EventOptions, EventSubscriber, Exit, FileStat, Launch, ServerLaunch, ShellEvent, ShellOptions, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Permission, PermissionChange, PermissionDefinition, PermissionDefinitions, PermissionInput, PermissionName, PermissionRequest, PermissionValue, PermissionValueDomain, Permissions, ClientPermissionDeclarations, ClientPermissions, ContextPermissions, ProgramPermissions, TimedContextPermissions, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramStartup, ProgramSql, ProgramStore, ProcessEvents, Publishable, System, SystemUploads, Upload, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, Timeoutable, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, AnimationsPreference, DesktopPreferences, DesktopPreferencesEvents, DesktopPreferencesSource, DesktopPreferencesUpdate, Desktop, DesktopSize, DesktopSurfaceEvents, DesktopSurfaceSnapshot, DesktopSurfaceSource, WritableDesktopPreferencesSource, ThemedValue, Theme, ThemePreference, Value, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowOperations, Transaction } from "@phreshos/core";

package/dist/main.js

@@ -1,5 +1,5 @@
 export { system } from "./system.js";
 export { desktop } from "./desktop/desktop.js";
 export { context } from "./context.js";
-export { ClientService, ServerService, Service, } from "@phreshos/core";
+export { ClientService, ServerService, Service, clientPermissionCatalog, isPermissionName, } from "@phreshos/core";
 export { ClientEndpoint, Endpoint, Process, Program, ServerEndpoint } from "./domain.js";

package/dist/permissions.js

@@ -5,10 +5,10 @@ export const defaultPermissionTimeout = 120_000;
 export function programPermissions(program) {
     const operate = (operation, name, permission) => (wire.request(["program-permissions", program, operation, name, permission]));
     return {
-        async get(name) { return parsePermission((await operate("get", name))[0]); },
+        async get(name) { return parsePermission(name, (await operate("get", name))[0]); },
         async all() { return parsePermissions((await operate("all"))[0]); },
-        async set(name, permission) { return parsePermissionChange((await operate("set", name, permission))[0]); },
-        async delete(name) { return parsePermissionChange((await operate("delete", name))[0]); }
+        async set(name, permission) { return parsePermissionChange(name, (await operate("set", name, permission))[0]); },
+        async delete(name) { return parsePermissionChange(name, (await operate("delete", name))[0]); }
     };
 }
 /** Stored grants and owner requests belonging to the current Client Endpoint. */
@@ -19,12 +19,12 @@ export function contextPermissions() {
             const result = await wire.requestOrNull(["context-permission-request", identity, name, permission], timeout);
             return result === null
                 ? Object.freeze({ permission: null, needReload: false })
-                : parsePermissionChange(result[0]);
+                : parsePermissionChange(name, result[0]);
         }
     });
     return {
         async get(name) {
-            return parsePermission((await wire.request(["context-permission-get", name]))[0]);
+            return parsePermission(name, (await wire.request(["context-permission-get", name]))[0]);
         },
         request: timed(defaultPermissionTimeout).request,
         timeout(milliseconds) {

package/dist/system.js

@@ -7,6 +7,7 @@ import controlledStream from "./controlled-stream.js";
 import Events from "./events.js";
 import { exit, process, program } from "./domain.js";
 import { systemStorage } from "./storage.js";
+import websocket from "./websocket.js";
 class ClientSystem {
     storage = systemStorage();
     appearance = new ClientAppearance();
@@ -73,6 +74,9 @@ class ClientSystem {
         });
         return response;
     }
+    websocket(url, protocols) {
+        return websocket(url, protocols);
+    }
     async *shell(command, options = {}) {
         const { signal, ...settings } = options;
         for await (const event of wire.stream(["shell", command, settings], undefined, signal))

package/dist/websocket.d.ts

@@ -0,0 +1,2 @@
+/** Acquire permission, then open the browser's native WebSocket. */
+export default function websocket(url: string | URL, protocols?: string | string[]): Promise<WebSocket>;

package/dist/websocket.js

@@ -0,0 +1,13 @@
+import wire from "./wire.js";
+/** Acquire permission, then open the browser's native WebSocket. */
+export default async function websocket(url, protocols) {
+    const address = new URL(String(url), document.baseURI);
+    if (address.protocol === "http:")
+        address.protocol = "ws:";
+    if (address.protocol === "https:")
+        address.protocol = "wss:";
+    await wire.request(["websocket", address.href, protocols]);
+    return protocols === undefined
+        ? new WebSocket(address.href)
+        : new WebSocket(address.href, protocols);
+}

package/dist/wire.js

@@ -1,7 +1,7 @@
 import Deadline from "./deadline.js";
 import { defaultTimeout } from "./events.js";
 import captureClientOutput from "./log.js";
-import { deserialize, serialize } from "./messagepack.js";
+import { deserialize, serialize } from "@the-link/messagepack";
 /** The client endpoint's sole postMessage adapter. */
 class Wire {
     parent = window.parent === window ? null : window.parent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "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.37"
+    "@phreshos/core": "^0.1.39"
   },
   "dependencies": {
-    "@msgpack/msgpack": "^3.1.3"
+    "@the-link/messagepack": "^0.1.0"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.37",
+    "@phreshos/core": "^0.1.39",
     "typescript": "^6.0.3"
   }
 }

package/dist/messagepack.d.ts

@@ -1,3 +0,0 @@
-export type Bytes = Uint8Array<ArrayBuffer>;
-export declare const serialize: (value: unknown, attachments?: readonly object[]) => Bytes;
-export declare const deserialize: (bytes: Uint8Array, attachments?: readonly unknown[]) => unknown;

package/dist/messagepack.js

@@ -1,130 +0,0 @@
-import { decode, encode, ExtensionCodec } from "@msgpack/msgpack";
-class Attachment {
-    index;
-    constructor(index) {
-        this.index = index;
-    }
-}
-class BigInteger {
-    value;
-    constructor(value) {
-        this.value = value;
-    }
-}
-class Undefined {
-}
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder("utf-8", { fatal: true });
-const extensions = new ExtensionCodec();
-const serializePrepared = (value, context) => encode(value, { context, extensionCodec: extensions });
-const deserializePrepared = (bytes, context) => decode(bytes, { context, extensionCodec: extensions });
-extensions.register({
-    type: 0,
-    encode: value => value instanceof Attachment ? uint32(value.index) : null,
-    decode: (bytes, _type, context) => {
-        const attachment = context.incoming?.[readUint32(bytes)];
-        if (attachment === undefined)
-            throw new Error("The MessagePack attachment is absent");
-        return attachment;
-    }
-});
-extensions.register({
-    type: 1,
-    encode: (value, context) => value instanceof Map ? serializePrepared([...value], context) : null,
-    decode: (bytes, _type, context) => new Map(deserializePrepared(bytes, context))
-});
-extensions.register({
-    type: 2,
-    encode: (value, context) => value instanceof Set ? serializePrepared([...value], context) : null,
-    decode: (bytes, _type, context) => new Set(deserializePrepared(bytes, context))
-});
-extensions.register({
-    type: 3,
-    encode: (value, context) => value instanceof RegExp ? serializePrepared([value.source, value.flags, value.lastIndex], context) : null,
-    decode: (bytes, _type, context) => {
-        const [source, flags, lastIndex] = deserializePrepared(bytes, context);
-        const expression = new RegExp(source, flags);
-        expression.lastIndex = lastIndex;
-        return expression;
-    }
-});
-extensions.register({
-    type: 4,
-    encode: value => value instanceof URL ? textEncoder.encode(value.href) : null,
-    decode: bytes => new URL(textDecoder.decode(bytes))
-});
-extensions.register({
-    type: 5,
-    encode: (value, context) => value instanceof Error ? serializePrepared(prepare({
-        cause: value.cause,
-        message: value.message,
-        name: value.name,
-        stack: value.stack
-    }, context), context) : null,
-    decode: (bytes, _type, context) => {
-        const value = deserializePrepared(bytes, context);
-        const error = new Error(value.message, { cause: value.cause });
-        error.name = value.name;
-        if (value.stack !== undefined)
-            error.stack = value.stack;
-        return error;
-    }
-});
-extensions.register({
-    type: 6,
-    encode: value => value instanceof BigInteger ? textEncoder.encode(value.value.toString()) : null,
-    decode: bytes => BigInt(textDecoder.decode(bytes))
-});
-extensions.register({
-    type: 7,
-    encode: value => value instanceof Undefined ? new Uint8Array() : null,
-    decode: () => undefined
-});
-export const serialize = (value, attachments = []) => {
-    const outgoing = new Map(attachments.map((attachment, index) => [attachment, index]));
-    const context = { outgoing };
-    return serializePrepared(prepare(value, context), context);
-};
-export const deserialize = (bytes, attachments = []) => {
-    return deserializePrepared(bytes, { incoming: attachments });
-};
-const prepare = (value, context) => {
-    if (value === undefined)
-        return new Undefined();
-    if (typeof value === "bigint")
-        return new BigInteger(value);
-    if (typeof value === "function" || typeof value === "symbol")
-        return null;
-    if (value === null || typeof value !== "object")
-        return value;
-    const attachment = context.outgoing?.get(value);
-    if (attachment !== undefined)
-        return new Attachment(attachment);
-    if (value instanceof Date || value instanceof RegExp || value instanceof URL || value instanceof Error)
-        return value;
-    if (value instanceof ArrayBuffer)
-        return new Uint8Array(value);
-    if (ArrayBuffer.isView(value))
-        return Uint8Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
-    if (value instanceof Map)
-        return new Map([...value].map(([key, entry]) => [prepare(key, context), prepare(entry, context)]));
-    if (value instanceof Set)
-        return new Set([...value].map(entry => prepare(entry, context)));
-    if (Array.isArray(value))
-        return value.map(entry => prepare(entry, context));
-    if ("toJSON" in value && typeof value.toJSON === "function")
-        return prepare(value.toJSON(), context);
-    return Object.fromEntries(Object.entries(value)
-        .filter(([, entry]) => typeof entry !== "function")
-        .map(([key, entry]) => [key, prepare(entry, context)]));
-};
-const uint32 = (value) => {
-    const bytes = new Uint8Array(4);
-    new DataView(bytes.buffer).setUint32(0, value);
-    return bytes;
-};
-const readUint32 = (bytes) => {
-    if (bytes.byteLength !== 4)
-        throw new Error("The MessagePack attachment reference is invalid");
-    return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0);
-};