@phreshos/client 0.1.32 → 0.1.33

package/dist/domain.js

@@ -1,35 +1,45 @@
-import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer } from "@phreshos/core";
+import { ClientEndpoint as CoreClientEndpoint, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, ServerEndpoint as CoreServerEndpoint } from "@phreshos/core";
 import Events, { stream } from "./events.js";
 import Deadline from "./deadline.js";
 import HandleRegistry from "./handle-registry.js";
 import { area, sql, store } from "./storage.js";
+import startup from "./startup.js";
+import { programPermissions } from "./permissions.js";
 import wire from "./wire.js";
-import { currentProgramPermission } from "./permissions.js";
 const handles = new HandleRegistry();
 const ProgramBase = CoreProgram;
 const ProcessBase = CoreProcess;
-const ServerBase = CoreServer;
-const ClientBase = CoreClient;
+const ServerEndpointBase = CoreServerEndpoint;
+const ClientEndpointBase = CoreClientEndpoint;
 class ProgramHandle extends ProgramBase {
     identity;
     reference;
-    data = area("data");
-    cache = area("cache");
-    store = store();
-    logs = sql("logs");
-    database = sql("database");
-    permission = currentProgramPermission;
+    data;
+    cache;
+    store;
+    logs;
+    database;
+    startup;
     process;
+    permissions;
     record;
     constructor(record) {
         super();
         this.identity = record.identity;
         this.reference = record.reference;
         this.record = record;
-        this.process = new ProgramProcessHandle(record.reference);
+        this.data = area(this.address, "data");
+        this.cache = area(this.address, "cache");
+        this.store = store(this.address);
+        this.logs = sql("logs", this.address);
+        this.database = sql("database", this.address);
+        this.startup = startup(this.address);
+        this.permissions = programPermissions(this.address);
+        this.process = new ProgramProcessHandle(this.address, record.reference);
         bindEvents(this, scoped("program-host", record.reference, programEvent));
     }
     get name() { return this.record.name; }
+    get assetId() { return this.record.assetId; }
     get version() { return this.record.version; }
     get description() { return this.record.description; }
     get hasAgent() { return this.record.hasAgent; }
@@ -39,31 +49,41 @@ class ProgramHandle extends ProgramBase {
     get client() {
         return this.record.client ? clientDeclaration(this.record.client) : null;
     }
+    get address() { return { identity: this.identity, reference: this.reference }; }
     update(record) {
         if (record.reference !== this.reference)
             throw new Error("A Program handle cannot become another Program");
         this.record = record;
     }
     async icon(size = "medium") {
-        const answer = await wire.request(["icon", size]);
+        const answer = await wire.request(["icon", this.address, size]);
         return new Blob([Uint8Array.from(answer[0])], { type: "image/png" });
     }
     async agent() {
         if (!this.hasAgent)
             return null;
-        const answer = await wire.request(["program-agent"]);
+        const answer = await wire.request(["program-agent", this.address]);
         return answer[0];
     }
     async installed() {
-        const answer = await wire.request(["installed"]);
+        const answer = await wire.request(["installed", this.address]);
         return answer[0];
     }
+    async *install() {
+        for await (const value of wire.stream(["install", this.address])) {
+            yield programCommandChunk(value);
+        }
+    }
+    async fork(identity) {
+        const answer = await wire.request(["fork", this.address, identity]);
+        return program(answer[0]);
+    }
     async *uninstall(everything = false) {
-        for await (const value of wire.stream(["uninstall", undefined, everything])) {
+        for await (const value of wire.stream(["uninstall", this.address, everything])) {
             yield programCommandChunk(value);
         }
     }
-    async forget() { await wire.request(["forget"]); }
+    async forget() { await wire.request(["forget", this.address]); }
 }
 function programCommandChunk(value) {
     const chunk = value;
@@ -85,15 +105,18 @@ function clientDeclaration(record) {
         size: record.size,
         position: record.position,
         layer: record.layer,
-        minimize: record.minimize
+        minimize: record.minimize,
+        permissions: Object.freeze(Object.fromEntries(Object.entries(record.permissions).map(([name, values]) => [name, Object.freeze([...values])])))
     });
 }
 class ProgramProcessHandle {
-    constructor(program) {
-        bindEvents(this, scoped("program-process", program, programProcessEvent));
+    address;
+    constructor(address, reference) {
+        this.address = address;
+        bindEvents(this, scoped("program-process", reference, programProcessEvent));
     }
     async list() {
-        const answer = await wire.request(["program-process-list"]);
+        const answer = await wire.request(["program-process-list", this.address]);
         return answer[0].map(record => process(record));
     }
     async first() {
@@ -103,22 +126,42 @@ class ProgramProcessHandle {
         return chronological(await this.list()).at(-1) ?? null;
     }
     async find(identityOrName) {
-        const answer = await wire.request(["program-process-find", identityOrName]);
+        const answer = await wire.request(["program-process-find", this.address, identityOrName]);
         return answer[0] ? process(answer[0]) : null;
     }
     async create(launch = {}) {
-        const answer = await wire.request(["program-process-create", launch]);
+        const answer = await wire.request(["program-process-create", this.address, launch]);
         return process(answer[0]);
     }
+    async *run(launch = {}, options = {}) {
+        for await (const value of wire.stream(["run", this.address, launch], undefined, options.signal)) {
+            yield processRunEvent(value);
+        }
+    }
     async findOrCreate(launch) {
-        const answer = await wire.request(["program-process-find-or-create", launch]);
+        const answer = await wire.request(["program-process-find-or-create", this.address, launch]);
         return process(answer[0]);
     }
     async exitAll() {
-        const answer = await wire.request(["program-process-exit-all"]);
+        const answer = await wire.request(["program-process-exit-all", this.address]);
         return answer[0];
     }
 }
+function processRunEvent(value) {
+    const event = value;
+    if (event?.event === "started" && event.process) {
+        return Object.freeze({ event: "started", process: process(event.process) });
+    }
+    if (event?.event === "output" && (event.stream === "stdout" || event.stream === "stderr") && typeof event.text === "string") {
+        return Object.freeze({ event: "output", stream: event.stream, text: event.text });
+    }
+    if (event?.event === "exited" && event.process) {
+        const code = typeof event.exit?.code === "number" ? event.exit.code : null;
+        const signal = typeof event.exit?.signal === "string" ? event.exit.signal : null;
+        return Object.freeze({ event: "exited", process: process(event.process), exit: exit(code, signal) });
+    }
+    throw new Error("The System returned an invalid Process run event");
+}
 function chronological(processes) {
     return processes.sort((left, right) => left.startedAt.getTime() - right.startedAt.getTime());
 }
@@ -202,7 +245,7 @@ export class ServerTrafficHandle extends TrafficHandle {
         }, impossible);
     }
 }
-class ServerHandle extends ServerBase {
+class ServerEndpointHandle extends ServerEndpointBase {
     owner;
     traffic;
     lifecycle;
@@ -245,7 +288,7 @@ class ServerHandle extends ServerBase {
         }
     }
 }
-class ClientHandle extends ClientBase {
+class ClientEndpointHandle extends ClientEndpointBase {
     owner;
     traffic;
     lifecycle;
@@ -271,11 +314,9 @@ class ClientHandle extends ClientBase {
 }
 class WindowHandle extends Events {
     target;
-    local;
     constructor(target) {
         super(...deferredScoped("host-end", target, (_event, values) => values[0]));
         this.target = target;
-        this.local = new LocalWindowHandle(target);
     }
     async state() {
         const answer = await wire.request(["window", await this.target()]);
@@ -297,39 +338,21 @@ class WindowHandle extends Events {
 }
 class LocalWindowHandle {
     target;
-    surface;
-    constructor(target) {
+    selected;
+    constructor(target, selected) {
         this.target = target;
-        this.surface = new LocalWindowSurfaceHandle(target);
+        this.selected = selected;
     }
-    async state() {
-        const answer = await wire.request(["windowLocal", await this.target()]);
-        return answer[0];
+    transaction(transaction) {
+        return new LocalWindowHandle(this.target, transaction);
     }
-    async title() { return (await this.state()).title; }
-    async position() { return (await this.state()).position; }
-    async size() { return (await this.state()).size; }
-    async minimized() { return (await this.state()).minimized; }
-    async front() { return (await this.state()).front; }
-    async layer() { return (await this.state()).layer; }
-    async location() { return (await this.state()).location; }
-    async move(position, transaction) { await wire.request(["windowLocalMove", await this.target(), position, transaction]); }
-    async resize(size, transaction) { await wire.request(["windowLocalResize", await this.target(), size, transaction]); }
-    async setGeometry(geometry, transaction) { await wire.request(["windowLocalGeometry", await this.target(), geometry, transaction]); }
-    async minimize(minimized = true) { await wire.request(["windowLocalMinimize", await this.target(), minimized]); }
-    async changeTitle(title) { await wire.request(["windowLocalTitle", await this.target(), title]); }
-    async raise() { await wire.request(["windowLocalRaise", await this.target()]); }
-}
-class LocalWindowSurfaceHandle {
-    target;
-    constructor(target) {
-        this.target = target;
-    }
-    async set(transition) {
-        await wire.request(["windowLocalSurfaceSet", await this.target(), transition]);
-    }
-    async remove(transition) {
-        await wire.request(["windowLocalSurfaceRemove", await this.target(), transition]);
+    async addSurface() { await this.change("windowLocalSurfaceAdd"); }
+    async removeSurface() { await this.change("windowLocalSurfaceRemove"); }
+    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 change(operation, value) {
+        await wire.request([operation, await this.target(), value, this.selected]);
     }
 }
 function deferredScoped(route, target, convert) {
@@ -473,12 +496,15 @@ export function claimEndpoint(reference, kind, endpoint) {
     return handles.adopt(`endpoint:${reference}:${kind}`, endpoint);
 }
 function endpointHandle(owner, kind, preferred) {
-    return handles.obtain(`endpoint:${owner.reference}:${kind}`, () => preferred ?? (kind === "server" ? new ServerHandle(owner) : new ClientHandle(owner)));
+    return handles.obtain(`endpoint:${owner.reference}:${kind}`, () => preferred ?? (kind === "server" ? new ServerEndpointHandle(owner) : new ClientEndpointHandle(owner)));
 }
 export function window(target) {
     return new WindowHandle(target);
 }
-/** Resolves only endpoint identities intentionally visible to this Client. */
+export function localWindow(target) {
+    return new LocalWindowHandle(target);
+}
+/** Resolves an Endpoint reference through the Client Endpoint's global handle registry. */
 export function visibleEndpoint(reference) {
     if (reference === null)
         return null;
@@ -490,7 +516,7 @@ export const Program = CoreProgram;
 export const Process = CoreProcess;
 /** Runtime constructor shared by all client-visible Endpoint handles. */
 export const Endpoint = CoreEndpoint;
-/** Runtime constructor shared by all client-visible Server handles. */
-export const Server = CoreServer;
-/** Runtime constructor shared by all client-visible Client handles. */
-export const Client = CoreClient;
+/** Runtime constructor shared by all client-visible Server Endpoint handles. */
+export const ServerEndpoint = CoreServerEndpoint;
+/** Runtime constructor shared by all client-visible Client Endpoint handles. */
+export const ClientEndpoint = CoreClientEndpoint;

package/dist/events.d.ts

@@ -1,19 +1,17 @@
-import type { Capture, Cleanup, EventOptions } from "@phreshos/core";
+import type { Cleanup, EventOptions, Subscribable } from "@phreshos/core";
 export declare const defaultTimeout = 10000;
 type Failure = (error: Error) => void;
 type Listener = (message: unknown) => unknown;
 type EveryListener = (event: string, message: unknown) => unknown;
 type Register<Message> = (listener: (message: Message) => unknown, impossible?: Failure) => Cleanup;
 /** SDK-owned waits, queues and callbacks over boundary forwarding state. */
-export default class Events {
+export default class Events<Vocabulary extends object = {}, Fallback = unknown> implements Subscribable<Vocabulary, Fallback> {
     private readonly listen;
     private readonly listenAll;
     constructor(listen: (event: string, listener: Listener, impossible?: Failure) => Cleanup, listenAll: (listener: EveryListener, impossible?: Failure) => Cleanup);
-    subscribe(event: string, subscriber: Listener): Cleanup;
-    subscribe(subscriber: (capture: Capture<string, unknown>) => unknown): Cleanup;
-    waitFor(event: string, timeout?: number): Promise<unknown>;
-    events(event: string, options?: EventOptions): AsyncIterableIterator<unknown>;
-    events(options?: EventOptions): AsyncIterableIterator<Capture<string, unknown>>;
+    readonly subscribe: Subscribable<Vocabulary, Fallback>["subscribe"];
+    readonly waitFor: Subscribable<Vocabulary, Fallback>["waitFor"];
+    readonly events: Subscribable<Vocabulary, Fallback>["events"];
 }
 /** Converts one persistent registration into a bounded asynchronous iterator. */
 export declare function stream<Message>(register: Register<Message>, options?: EventOptions): AsyncIterableIterator<Message>;

package/dist/events.js

@@ -7,12 +7,12 @@ export default class Events {
         this.listen = listen;
         this.listenAll = listenAll;
     }
-    subscribe(eventOrSubscriber, subscriber) {
+    subscribe = ((eventOrSubscriber, subscriber) => {
         if (typeof eventOrSubscriber === "string")
             return this.listen(eventOrSubscriber, subscriber);
         return this.listenAll((event, message) => eventOrSubscriber({ event, message }));
-    }
-    waitFor(event, timeout = defaultTimeout) {
+    });
+    waitFor = ((event, timeout = defaultTimeout) => {
         return new Promise((resolve, reject) => {
             let settled = false;
             let stop = () => undefined;
@@ -27,13 +27,13 @@ export default class Events {
             const timer = setTimeout(() => finish(() => reject(new Error(`Event promise timeout ${timeout}ms`))), timeout);
             stop = this.listen(event, message => finish(() => resolve(message)), error => finish(() => reject(error)));
         });
-    }
-    events(eventOrOptions = {}, namedOptions = {}) {
+    });
+    events = ((eventOrOptions = {}, namedOptions = {}) => {
         if (typeof eventOrOptions === "string") {
             return stream((listener, impossible) => this.listen(eventOrOptions, listener, impossible), namedOptions);
         }
         return stream((listener, impossible) => this.listenAll((event, message) => listener({ event, message }), impossible), eventOrOptions);
-    }
+    });
 }
 /** Converts one persistent registration into a bounded asynchronous iterator. */
 export function stream(register, options = {}) {

package/dist/main.d.ts

@@ -1,6 +1,6 @@
-export { system, type System } from "./system.js";
-export { type SystemDesktop } from "./desktop/desktop.js";
+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 { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess, 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, Capture, Captures, CaptureSubscriber, ClientLaunch, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointLifecycle, EndpointLifecycleEvents, EntryStat, EventMessage, EventName, EventOptions, EventSubscriber, Exit, FileStat, Launch, ServerLaunch, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, PermissionDecision, Permission, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, AnimationsPreference, DesktopPreferences, DesktopPreferencesEvents, DesktopPreferencesSource, DesktopPreferencesUpdate, DesktopPointerEvents, DesktopPointerPosition, DesktopPointerSnapshot, DesktopPointerSource, DesktopSize, DesktopSurfaceEvents, DesktopSurfaceSnapshot, DesktopSurfaceSource, WritableDesktopPreferencesSource, ThemedValue, Theme, ThemePreference, Value, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, VisibilityTransition, Transaction } 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";

package/dist/main.js

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

package/dist/permissions.d.ts

@@ -1,10 +1,7 @@
-import type { Permission, PermissionDecision, PermissionName, TimedPermission } from "@phreshos/core";
-/** Client access to the current Program's effective permission decisions. */
-export default class ClientPermission implements Permission {
-    granted(name: PermissionName): Promise<PermissionDecision>;
-    request(name: PermissionName): Promise<PermissionDecision>;
-    timeout(milliseconds: number): TimedPermission;
-    private requestWithin;
-}
-/** The one Program-owned permission capability visible in this isolated Client. */
-export declare const currentProgramPermission: ClientPermission;
+import type { ContextPermissions, ProgramPermissions } from "@phreshos/core";
+import type { HandleAddress } from "./domain.js";
+export declare const defaultPermissionTimeout = 120000;
+/** Bind authoritative stored grants to one exact Program handle. */
+export declare function programPermissions(program: HandleAddress): ProgramPermissions;
+/** Stored grants and owner requests belonging to the current Client Endpoint. */
+export declare function contextPermissions(): ContextPermissions;

package/dist/permissions.js

@@ -1,23 +1,36 @@
+import { parsePermission, parsePermissionChange, parsePermissions } from "@phreshos/core";
 import wire from "./wire.js";
-const defaultPermissionTimeout = 30_000;
-/** Client access to the current Program's effective permission decisions. */
-export default class ClientPermission {
-    async granted(name) {
-        const answer = await wire.request(["permission-granted", name]);
-        return answer[0];
-    }
-    request(name) {
-        return this.requestWithin(name, defaultPermissionTimeout);
-    }
-    timeout(milliseconds) {
-        if (!Number.isFinite(milliseconds) || milliseconds < 0)
-            throw new Error("A permission timeout must be a non-negative finite number");
-        return Object.freeze({ request: (name) => this.requestWithin(name, milliseconds) });
-    }
-    async requestWithin(name, milliseconds) {
-        const answer = await wire.requestOrNull(["permission-request", name], milliseconds);
-        return answer?.[0] ?? null;
-    }
+export const defaultPermissionTimeout = 120_000;
+/** Bind authoritative stored grants to one exact Program handle. */
+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 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]); }
+    };
+}
+/** Stored grants and owner requests belonging to the current Client Endpoint. */
+export function contextPermissions() {
+    const timed = (timeout) => ({
+        async request(name, permission = true) {
+            const identity = crypto.randomUUID();
+            const result = await wire.requestOrNull(["context-permission-request", identity, name, permission], timeout);
+            return result === null
+                ? Object.freeze({ permission: null, needReload: false })
+                : parsePermissionChange(result[0]);
+        }
+    });
+    return {
+        async get(name) {
+            return parsePermission((await wire.request(["context-permission-get", name]))[0]);
+        },
+        request: timed(defaultPermissionTimeout).request,
+        timeout(milliseconds) {
+            if (!Number.isFinite(milliseconds) || milliseconds < 0)
+                throw new Error("A permission timeout must be a non-negative finite number");
+            return timed(milliseconds);
+        }
+    };
 }
-/** The one Program-owned permission capability visible in this isolated Client. */
-export const currentProgramPermission = new ClientPermission();

package/dist/service.js

@@ -86,11 +86,11 @@ export function prepareService(key) {
 }
 function serviceEvents(key, scope) {
     return [
-        (event, listener) => wire.followService(key, scope, event, listener),
-        (listener) => wire.followService(key, scope, null, (event, payload) => {
+        (event, listener, impossible) => wire.followService(key, scope, event, listener, impossible),
+        (listener, impossible) => wire.followService(key, scope, null, (event, payload) => {
             if (typeof event === "string")
                 listener(event, payload);
-        })
+        }, impossible)
     ];
 }
 function bindEvents(target, events) {

package/dist/startup.d.ts

@@ -0,0 +1,4 @@
+import type { ProgramStartup } from "@phreshos/core";
+import type { HandleAddress } from "./domain.js";
+/** Bind persistent startup operations to one Program handle. */
+export default function startup(program: HandleAddress): ProgramStartup;

package/dist/startup.js

@@ -0,0 +1,16 @@
+import wire from "./wire.js";
+/** Bind persistent startup operations to one Program handle. */
+export default function startup(program) {
+    return {
+        async get() {
+            const answer = await wire.request(["startup", program, "get"]);
+            return answer[0];
+        },
+        async enable(launch = {}) {
+            await wire.request(["startup", program, "enable", launch]);
+        },
+        async disable() {
+            await wire.request(["startup", program, "disable"]);
+        }
+    };
+}

package/dist/storage.d.ts

@@ -1,5 +1,9 @@
-import type { ProgramSql, ProgramStore, Storage } from "@phreshos/core";
-/** Client-side Program storage, structurally scoped by the iframe boundary. */
-export declare function area(which: "data" | "cache"): Storage;
-export declare function store(): ProgramStore;
-export declare function sql(kind: "database" | "logs"): ProgramSql;
+import type { ProgramSql, ProgramStore, Storage as CoreStorage } 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;

package/dist/storage.js

@@ -1,10 +1,10 @@
 import { content } from "./content.js";
 import controlledStream from "./controlled-stream.js";
 import wire from "./wire.js";
-/** Client-side Program storage, structurally scoped by the iframe boundary. */
-export function area(which) {
+/** 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, undefined, operation, ...values]);
+        const answer = await wire.request([which, program, operation, ...values]);
         return answer[0];
     }
     async function transfer(operation, path, body = null) {
@@ -12,7 +12,7 @@ export function area(which) {
         const abort = () => channel.port1.postMessage("abort");
         const close = () => channel.port1.close();
         try {
-            const answer = await wire.request([which, undefined, operation, path, body, channel.port2], undefined, body instanceof ReadableStream ? [body, channel.port2] : [channel.port2]);
+            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;
@@ -34,6 +34,8 @@ export function area(which) {
         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(); },
@@ -47,9 +49,9 @@ export function area(which) {
         clear: (...path) => ask("clear", ...path)
     };
 }
-export function store() {
+export function store(program) {
     async function ask(operation, ...values) {
-        const answer = await wire.request(["store", undefined, operation, ...values]);
+        const answer = await wire.request(["store", program, operation, ...values]);
         return answer[0];
     }
     return {
@@ -60,13 +62,62 @@ export function store() {
         clear: () => ask("clear")
     };
 }
-export function sql(kind) {
+export function sql(kind, program) {
     return {
         async query(statement, ...rest) {
             const text = typeof statement === "string" ? statement : statement.raw.join("?");
             const values = typeof statement === "string" ? (Array.isArray(rest[0]) ? rest[0] : []) : rest;
-            const answer = await wire.request([kind, undefined, text, values]);
+            const answer = await wire.request([kind, program, text, values]);
             return answer[0];
         }
     };
 }
+/** 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.d.ts

@@ -1,27 +1,3 @@
-import type { AppearanceSource, ClientService, ServerService, ServiceKey, SystemUploads } from "@phreshos/core";
-import { type SystemDesktop } from "./desktop/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, Fallback = unknown> = Endpoint extends "server" ? ServerService<Events, Fallback> : ClientService<Events, Fallback>;
-/** Desktop capabilities structurally available to a Client endpoint. */
-export interface System {
-    /** Complete unresolved Appearance read from the System authority. */
-    readonly appearance: AppearanceSource;
-    /** Capabilities owned by the Desktop containing this Client. */
-    readonly desktop: SystemDesktop;
-    /** Flat System-owned public uploads capability. */
-    readonly uploads: SystemUploads;
-    /** Performs an unrestricted server-side fetch on behalf of this Client. */
-    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
-    /** Returns a precisely typed stable handle for either service endpoint. */
-    service<Endpoint extends ServiceEndpoint>(key: ServiceAddress<Endpoint>): ServiceHandle<Endpoint, {}>;
-    /** Returns a typed stable handle for one exact Server service identity. */
-    service<ServiceEvents extends object, Fallback = unknown>(key: ServiceAddress<"server">): ServerService<ServiceEvents, Fallback>;
-    /** Returns a typed stable handle for one exact Client service identity. */
-    service<ServiceEvents extends object, Fallback = unknown>(key: ServiceAddress<"client">): ClientService<ServiceEvents, Fallback>;
-}
-/** Desktop capabilities available to this Client. */
-export declare const system: System;
-export {};
+import { type System as CoreSystem } from "@phreshos/core";
+/** The global System represented through this Client runtime. */
+export declare const system: CoreSystem;