@phreshos/client 0.1.36 → 0.1.38

package/README.md

@@ -51,8 +51,8 @@ published shape.
 
 ## Related repositories
 
-- [`@phreshos/core`](https://github.com/PhreshOS/core) owns every shared
-  contract and domain class exposed here.
+- [`@phreshos/core`](https://github.com/PhreshOS/core) is the one public import
+  path for every shared contract and domain class implemented by these handles.
 - [`@phreshos/server`](https://github.com/PhreshOS/server) adapts the paired
   Server Endpoint boundary.
 - [`@phreshos/react`](https://github.com/PhreshOS/react) adapts the Client

package/dist/appearance.d.ts

@@ -4,12 +4,11 @@ import Events from "./events.js";
 export default class ClientAppearance extends Events<AppearanceEvents, never> implements WritableAppearance {
     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>;
+        colors: import("@phreshos/core").AppearanceColors;
         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>;
+        shadow: import("@phreshos/core").ThemedValue<import("@phreshos/core").AppearanceShadow, import("@phreshos/core").AppearanceShadow>;
+        material: import("@phreshos/core").ThemedValue<import("@phreshos/core").AppearanceMaterial, import("@phreshos/core").AppearanceMaterial>;
         signInWallpaper: import("@phreshos/core").ThemedValue<string | null, string | null>;
         desktopWallpaper: import("@phreshos/core").ThemedValue<string | null, string | null>;
     }>>;

package/dist/content.d.ts

@@ -1,6 +1,7 @@
+import type { WritableContent } from "@phreshos/core";
 export type ContentBody = Blob | ReadableStream<Uint8Array>;
 /** Converts one authored value into the browser body and metadata used by storage and serving. */
-export declare function content(value: unknown): {
+export declare function content(value: WritableContent): {
     body: ContentBody;
     extension: string;
     type: string;

package/dist/context.d.ts

@@ -1,13 +1,3 @@
-import type { ClientContext as CoreClientContext, ContextCapture as CoreContextCapture, ContextEvents as CoreContextEvents, ContextMessage as CoreContextMessage } from "@phreshos/core";
-import { ServerEndpoint, type Endpoint } from "./domain.js";
-/** The executing Process's canonical Server Endpoint handle. */
-export type ContextServer<Events extends object = {}, Fallback = unknown> = ServerEndpoint<Events, Fallback>;
-/** One value addressed to the current Client Endpoint, with a client-visible sender. */
-export type ContextMessage<Payload = unknown> = CoreContextMessage<Payload, Endpoint | null>;
-/** Applies the client-visible sender envelope to known Context events. */
-export type ContextEvents<Events extends object> = CoreContextEvents<Events, Endpoint | null>;
-/** Every event observable through the current Client Endpoint Context. */
-export type ContextCapture<Events extends object = {}> = CoreContextCapture<Events, Endpoint | null>;
-export type Context<Events extends object = {}> = CoreClientContext<Events>;
+import type { ClientContext as CoreClientContext } from "@phreshos/core";
 /** Inbound events, owner hierarchy, and paired Server Endpoint for this Client runtime. */
-export declare const context: Context;
+export declare const context: CoreClientContext;

package/dist/domain.js

@@ -336,6 +336,7 @@ class WindowHandle extends Events {
     async changeTitle(title) { await wire.request(["changeTitle", await this.target(), title]); }
     async raise() { await wire.request(["raise", await this.target()]); }
 }
+const windowTargets = new WeakMap();
 class LocalWindowHandle {
     target;
     selected;
@@ -351,6 +352,15 @@ class LocalWindowHandle {
     async move(position) { await this.change("windowLocalMove", position); }
     async resize(size) { await this.change("windowLocalResize", size); }
     async setGeometry(geometry) { await this.change("windowLocalGeometry", geometry); }
+    async minimize(minimized = true) { await this.change("windowLocalMinimize", minimized); }
+    async follow(window) {
+        const target = windowTargets.get(window);
+        if (!target)
+            throw new Error("Local Window follow requires a Window from this Client SDK");
+        await wire.request(["windowLocalFollow", await this.target(), await target(), this.selected]);
+    }
+    async unfollow() { await wire.request(["windowLocalUnfollow", await this.target(), this.selected]); }
+    async raise() { await wire.request(["windowLocalRaise", await this.target()]); }
     async change(operation, value) {
         await wire.request([operation, await this.target(), value, this.selected]);
     }
@@ -499,7 +509,9 @@ function endpointHandle(owner, kind, preferred) {
     return handles.obtain(`endpoint:${owner.reference}:${kind}`, () => preferred ?? (kind === "server" ? new ServerEndpointHandle(owner) : new ClientEndpointHandle(owner)));
 }
 export function window(target) {
-    return new WindowHandle(target);
+    const handle = new WindowHandle(target);
+    windowTargets.set(handle, target);
+    return handle;
 }
 export function localWindow(target) {
     return new LocalWindowHandle(target);

package/dist/main.d.ts

@@ -1,6 +1,3 @@
 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, 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, 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, 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";
+export { context } from "./context.js";

package/dist/main.js

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

package/dist/storage.d.ts

@@ -1,9 +1,8 @@
-import type { ProgramSql, ProgramStore, Storage as CoreStorage } from "@phreshos/core";
+import { Storage, type ProgramSql, type ProgramStore } from "@phreshos/core";
 import type { HandleAddress } from "./domain.js";
-export type Storage = CoreStorage;
 /** Client-side access to one exact Program storage area. */
 export declare function area(program: HandleAddress, which: "data" | "cache"): Storage;
-export declare function store(program: HandleAddress): ProgramStore;
-export declare function sql(kind: "database" | "logs", program: HandleAddress): ProgramSql;
 /** Access to the System's native storage through the Client boundary. */
 export declare function systemStorage(): Storage;
+export declare function store(program: HandleAddress): ProgramStore;
+export declare function sql(kind: "database" | "logs", program: HandleAddress): ProgramSql;

package/dist/storage.js

@@ -1,53 +1,202 @@
+import { Storage, StorageFile } from "@phreshos/core";
 import { content } from "./content.js";
 import controlledStream from "./controlled-stream.js";
 import wire from "./wire.js";
 /** Client-side access to one exact Program storage area. */
 export function area(program, which) {
-    async function ask(operation, ...values) {
-        const answer = await wire.request([which, program, operation, ...values]);
+    return new RemoteStorage(new ProgramStorageBoundary(program, which), []);
+}
+/** Access to the System's native storage through the Client boundary. */
+export function systemStorage() {
+    return new RemoteStorage(new SystemStorageBoundary(), []);
+}
+class StorageBoundary {
+}
+class ProgramStorageBoundary extends StorageBoundary {
+    program;
+    area;
+    constructor(program, area) {
+        super();
+        this.program = program;
+        this.area = area;
+    }
+    async ask(operation, path, input) {
+        const answer = await wire.request([this.area, this.program, operation, [...path], input]);
         return answer[0];
     }
-    async function transfer(operation, path, body = null) {
-        const channel = new MessageChannel();
-        const abort = () => channel.port1.postMessage("abort");
-        const close = () => channel.port1.close();
-        try {
-            const answer = await wire.request([which, program, operation, path, body, channel.port2], undefined, body instanceof ReadableStream ? [body, channel.port2] : [channel.port2]);
-            if (operation === "write") {
-                close();
-                return null;
-            }
-            if (!(answer[0] instanceof ReadableStream))
-                throw new Error("The storage response has no byte stream");
-            return controlledStream(answer[0], abort, close);
-        }
-        catch (error) {
-            abort();
-            close();
-            throw error;
-        }
+    transfer(operation, path, body, input) {
+        return transfer([this.area, this.program, operation], path, body, input);
+    }
+    watch(path, options, signal) {
+        return watch(["program", this.program, this.area, [...path], options], signal);
+    }
+}
+class SystemStorageBoundary extends StorageBoundary {
+    async ask(operation, path, input) {
+        const answer = await wire.request(["host-storage", operation, [...path], input]);
+        return answer[0];
+    }
+    transfer(operation, path, body, input) {
+        return transfer([`host-storage-${operation}`], path, body, input);
     }
-    async function stream(...path) {
-        const body = await transfer("stream", path);
+    watch(path, options, signal) {
+        return watch(["system", [...path], options], signal);
+    }
+}
+class RemoteStorage extends Storage {
+    boundary;
+    parts;
+    constructor(boundary, parts) {
+        super();
+        this.boundary = boundary;
+        this.parts = parts;
+    }
+    name() { return this.boundary.ask("name", this.parts); }
+    path() { return this.boundary.ask("path", this.parts); }
+    navigate(...parts) { return new RemoteStorage(this.boundary, [...this.parts, ...parts]); }
+    file(...parts) { return new RemoteStorageFile(this.boundary, [...this.parts, ...parts]); }
+    create() { return this.boundary.ask("create", this.parts); }
+    stat() { return this.boundary.ask("stat-storage", this.parts); }
+    async list(options = {}) {
+        const values = await this.boundary.ask("list", this.parts, options);
+        if (!Array.isArray(values))
+            throw new Error("The System returned an invalid Storage list");
+        return values.map(value => {
+            const entry = parseEntry(value);
+            return entry.kind === "file"
+                ? new RemoteStorageFile(this.boundary, [...this.parts, ...entry.path])
+                : new RemoteStorage(this.boundary, [...this.parts, ...entry.path]);
+        });
+    }
+    copy(destination, options = {}) { return copyStorage(this, destination, options); }
+    async move(destination, options = {}) {
+        if (await sameLocation(this, destination))
+            return;
+        await copyStorage(this, destination, options);
+        await this.delete();
+    }
+    delete() { return this.boundary.ask("delete-storage", this.parts); }
+    clear() { return this.boundary.ask("clear", this.parts); }
+    space() { return this.boundary.ask("space", this.parts); }
+    watch(options = {}) {
+        return this.boundary.watch(this.parts, { recursive: options.recursive }, options.signal);
+    }
+}
+class RemoteStorageFile extends StorageFile {
+    boundary;
+    parts;
+    constructor(boundary, parts) {
+        super();
+        this.boundary = boundary;
+        this.parts = parts;
+    }
+    name() { return this.boundary.ask("name", this.parts); }
+    path() { return this.boundary.ask("path", this.parts); }
+    stat() { return this.boundary.ask("stat-file", this.parts); }
+    async stream(options = {}) {
+        const body = await this.boundary.transfer("stream", this.parts, undefined, options);
         if (!body)
-            throw new Error("The storage response has no body");
+            throw new Error("The Storage response has no byte stream");
         return body;
     }
-    return {
-        path: () => ask("path"),
-        resolve: (...path) => ask("resolve", ...path),
-        stream,
-        async bytes(...path) { return new Uint8Array(await new Response(await stream(...path)).arrayBuffer()); },
-        async text(...path) { return new Response(await stream(...path)).text(); },
-        async json(...path) { return JSON.parse(await new Response(await stream(...path)).text()); },
-        async write(...args) {
-            await transfer("write", args.slice(0, -1), content(args.at(-1)).body);
-        },
-        stat: (...path) => ask("stat", ...path),
-        list: (...path) => ask("list", ...path),
-        delete: (...path) => ask("delete", ...path),
-        clear: (...path) => ask("clear", ...path)
-    };
+    async bytes(options) {
+        return new Uint8Array(await new Response(await this.stream(options)).arrayBuffer());
+    }
+    async text(options) {
+        return new Response(await this.stream(options)).text();
+    }
+    async json() { return JSON.parse(await this.text()); }
+    async write(value, options = {}) {
+        await this.boundary.transfer("write", this.parts, content(value).body, options);
+    }
+    async append(value) {
+        await this.boundary.transfer("append", this.parts, content(value).body);
+    }
+    async copy(destination, options = {}) {
+        if (await sameLocation(this, destination))
+            return;
+        await destination.write(await this.stream(), { overwrite: options.overwrite ?? false });
+    }
+    async move(destination, options = {}) {
+        if (await sameLocation(this, destination))
+            return;
+        await this.copy(destination, options);
+        await this.delete();
+    }
+    delete() { return this.boundary.ask("delete-file", this.parts); }
+}
+async function transfer(prefix, path, body, input) {
+    const channel = new MessageChannel();
+    const abort = () => channel.port1.postMessage("abort");
+    const close = () => channel.port1.close();
+    try {
+        const answer = await wire.request([...prefix, [...path], body ?? null, channel.port2, input], undefined, body instanceof ReadableStream ? [body, channel.port2] : [channel.port2]);
+        if (prefix.at(-1) !== "stream") {
+            close();
+            return null;
+        }
+        if (!(answer[0] instanceof ReadableStream))
+            throw new Error("The Storage response has no byte stream");
+        return controlledStream(answer[0], abort, close);
+    }
+    catch (error) {
+        abort();
+        close();
+        throw error;
+    }
+}
+function watch(values, signal) {
+    const operation = wire.stream(["storage-watch", ...values], undefined, signal);
+    return (async function* () {
+        for await (const value of operation) {
+            const change = value;
+            if (!change || (change.event !== "change" && change.event !== "rename") || change.path !== null && typeof change.path !== "string") {
+                throw new Error("The System returned an invalid Storage change");
+            }
+            yield Object.freeze({ event: change.event, path: change.path });
+        }
+    })();
+}
+async function copyStorage(source, destination, options) {
+    if (await sameLocation(source, destination))
+        return;
+    const [sourcePath, destinationPath] = await Promise.all([source.path(), destination.path()]);
+    if (descendsFrom(destinationPath, sourcePath))
+        throw new Error("A Storage directory cannot be copied inside itself");
+    if (!await source.stat())
+        throw new Error(`There is no Storage directory at ${sourcePath}`);
+    if (await destination.stat()) {
+        if (!options.overwrite)
+            throw new Error(`A Storage directory already exists at ${destinationPath}`);
+        await destination.delete();
+    }
+    await destination.create();
+    for (const entry of await source.list()) {
+        const name = await entry.name();
+        if (entry instanceof StorageFile)
+            await entry.copy(destination.file(name), options);
+        else
+            await entry.copy(destination.navigate(name), options);
+    }
+}
+async function sameLocation(left, right) {
+    const [leftPath, rightPath] = await Promise.all([left.path(), right.path()]);
+    return normalizePath(leftPath) === normalizePath(rightPath);
+}
+function descendsFrom(path, parent) {
+    const normalized = normalizePath(path);
+    const root = normalizePath(parent);
+    return normalized.startsWith(`${root}/`);
+}
+function normalizePath(path) {
+    return path.replaceAll("\\", "/").replace(/\/+$/, "");
+}
+function parseEntry(value) {
+    const entry = value;
+    if (!entry || (entry.kind !== "storage" && entry.kind !== "file") || !Array.isArray(entry.path) || entry.path.length === 0 || entry.path.some(part => typeof part !== "string")) {
+        throw new Error("The System returned an invalid Storage entry");
+    }
+    return { kind: entry.kind, path: entry.path };
 }
 export function store(program) {
     async function ask(operation, ...values) {
@@ -72,52 +221,3 @@ export function sql(kind, program) {
         }
     };
 }
-/** Access to the System's native storage through the Client boundary. */
-export function systemStorage() {
-    async function ask(operation, ...values) {
-        const answer = await wire.request(["host-storage", operation, ...values]);
-        return answer[0];
-    }
-    async function transfer(operation, path, body = null) {
-        const channel = new MessageChannel();
-        const abort = () => channel.port1.postMessage("abort");
-        const close = () => channel.port1.close();
-        try {
-            const answer = await wire.request([`host-storage-${operation}`, path, body, channel.port2], undefined, body instanceof ReadableStream ? [body, channel.port2] : [channel.port2]);
-            if (operation === "write") {
-                close();
-                return null;
-            }
-            if (!(answer[0] instanceof ReadableStream))
-                throw new Error("The storage response has no byte stream");
-            return controlledStream(answer[0], abort, close);
-        }
-        catch (error) {
-            abort();
-            close();
-            throw error;
-        }
-    }
-    async function stream(...path) {
-        const body = await transfer("stream", path);
-        if (!body)
-            throw new Error("The storage response has no body");
-        return body;
-    }
-    return {
-        path: () => ask("path"),
-        resolve: (...path) => ask("resolve", ...path),
-        stream,
-        async bytes(...path) { return new Uint8Array(await new Response(await stream(...path)).arrayBuffer()); },
-        async text(...path) { return new Response(await stream(...path)).text(); },
-        async json(...path) { return JSON.parse(await new Response(await stream(...path)).text()); },
-        async write(...args) {
-            const path = args.slice(0, -1);
-            await transfer("write", path, content(args.at(-1)).body);
-        },
-        stat: (...path) => ask("stat", ...path),
-        list: (...path) => ask("list", ...path),
-        delete: (...path) => ask("delete", ...path),
-        clear: (...path) => ask("clear", ...path)
-    };
-}

package/dist/system.js

@@ -14,10 +14,6 @@ class ClientSystem {
     program = new SystemProgramHandle();
     process = new SystemProcessHandle();
     uploads = uploads;
-    async forceCreateProgram(source) {
-        const answer = await wire.request(["host-program-force-create", source]);
-        return program(answer[0]);
-    }
     service(key) { return prepareService(key); }
     async fetch(input, init) {
         const request = new Request(input, {
@@ -102,6 +98,10 @@ class SystemProgramHandle extends Events {
         const answer = await wire.request(["host-program-create", source]);
         return program(answer[0]);
     }
+    async forceCreate(source) {
+        const answer = await wire.request(["host-program-force-create", source]);
+        return program(answer[0]);
+    }
 }
 class SystemProcessHandle extends Events {
     constructor() {

package/dist/uploads.d.ts

@@ -1,13 +1,13 @@
-import { type SystemUploads, type Upload } from "@phreshos/core";
+import { type FileStat, type SystemUploads, type Upload, type WritableContent } from "@phreshos/core";
 /** Flat upload access transported through the Client's Desktop boundary. */
 declare class ClientUploads implements SystemUploads {
     path(): Promise<string>;
-    write(value: unknown): Promise<Upload>;
+    write(value: WritableContent): Promise<Upload>;
     stream(file: string): Promise<ReadableStream<Uint8Array>>;
     bytes(file: string): Promise<Uint8Array<ArrayBuffer>>;
     text(file: string): Promise<string>;
     json<Value>(file: string): Promise<Value>;
-    stat(file: string): Promise<Upload | null>;
+    stat(file: string): Promise<FileStat | null>;
 }
 export declare const uploads: ClientUploads;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "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.40"
+    "@phreshos/core": "^0.1.42"
   },
   "dependencies": {
     "@the-link/messagepack": "^0.1.0"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.40",
+    "@phreshos/core": "^0.1.42",
     "typescript": "^6.0.3"
   }
 }