@phreshos/core 0.1.0

package/dist/publishable.d.ts

@@ -0,0 +1,21 @@
+import type { EventMessage, EventName } from "./subscribable.js";
+type OpenEvent = string & {};
+type AvailableEvent<Events extends object, Fallback> = EventName<Events> | ([Fallback] extends [never] ? never : OpenEvent);
+type CompatibleEvent<Events extends object, Fallback, Payload> = {
+    [Event in EventName<Events>]: Payload extends Events[Event] ? Event : never;
+}[EventName<Events>] | ([Fallback] extends [never] ? never : Payload extends Fallback ? OpenEvent : never);
+interface Publish<Events extends object, Fallback> {
+    <Payload, Event extends CompatibleEvent<Events, Fallback, Payload> = CompatibleEvent<Events, Fallback, Payload>>(event: Event, payload: Payload): void;
+    <Event extends AvailableEvent<Events, Fallback>>(event: Event, payload: EventMessage<Events, Fallback, Event>): void;
+}
+/**
+ * The independent capability to publish one payload to a named event.
+ *
+ * Publishing is synchronous and fire-and-forget. An unavailable destination
+ * silently drops the publication; no delivery result is produced.
+ */
+export interface Publishable<Events extends object = {}, Fallback = unknown> {
+    /** Publishes one payload to one named event on this target. */
+    publish: Publish<Events, Fallback>;
+}
+export {};

package/dist/served-file.d.ts

@@ -0,0 +1,11 @@
+/** Description of a value stored as a publicly reachable file. */
+export type ServedFile = Readonly<{
+    /** Generated filename beneath the public served-files route. */
+    file: string;
+    /** Detected media type, or `null` when no type is known. */
+    type: string | null;
+    /** Stored size in bytes. */
+    size: number;
+    /** Storage time as Unix milliseconds. */
+    time: number;
+}>;

package/dist/server.d.ts

@@ -0,0 +1,42 @@
+import type { Askable } from "./askable.js";
+import { Endpoint, type EndpointTraffic } from "./endpoint.js";
+import type { Outcome } from "./outcome.js";
+import type { Cleanup } from "./subscribable.js";
+/** One answer sent by this Server to the Endpoint that asked. */
+export type AnswerMessage<Result = unknown, To = Endpoint> = Readonly<{
+    /** Destination Endpoint, or `null` when its identity is outside this boundary. */
+    to: To;
+    /** Transport-neutral success or failure returned by the answerer. */
+    outcome: Outcome<Result>;
+}>;
+/** One observed answer sent by this Server. */
+export type AnswerCapture<Result = unknown, To = Endpoint> = Readonly<{
+    /** Event originally addressed by the question. */
+    event: string;
+    /** Correlation identity shared with the original question. */
+    questionId: string;
+    /** Answer destination and outcome. */
+    message: AnswerMessage<Result, To>;
+}>;
+/** A callback that observes answers sent by this Server. */
+export type AnswerObserver<Result = unknown, To = Endpoint> = (capture: AnswerCapture<Result, To>) => unknown;
+/** Broad communication originating from one Server, including its answers. */
+export interface ServerTraffic<Events extends object = {}, To = Endpoint, AskTo = Server> extends EndpointTraffic<Events, To, AskTo> {
+    /** Observes answers originating from this Server. */
+    observeAnswers<Result = unknown>(observer: AnswerObserver<Result, To>): Cleanup;
+}
+/** The server Endpoint of a Process. */
+export declare class Server<Events extends object = {}> extends Endpoint<Events> {
+    constructor();
+}
+export interface Server<Events extends object = {}> extends Askable {
+    /** Broad communication originating from this Server. */
+    readonly traffic: ServerTraffic<Events>;
+    /**
+     * Waits until a Server incarnation is ready.
+     *
+     * Temporary absence remains waitable when the Program declares a Server.
+     * The SDK uses its ten-second deadline unless one is supplied.
+    */
+    waitReady(timeout?: number): Promise<void>;
+}

package/dist/server.js

@@ -0,0 +1,7 @@
+import { Endpoint } from "./endpoint.js";
+/** The server Endpoint of a Process. */
+export class Server extends Endpoint {
+    constructor() {
+        super();
+    }
+}

package/dist/sql.d.ts

@@ -0,0 +1,17 @@
+/** SQL access to a Program-owned database or its read-only logs. */
+export interface ProgramSql {
+    /** Executes one statement; template interpolations become bound values. */
+    query<Row = Record<string, unknown>>(statement: TemplateStringsArray, ...values: unknown[]): Promise<Row[]>;
+    /** Executes one statement with optional bound values. */
+    query<Row = Record<string, unknown>>(statement: string, values?: unknown[]): Promise<Row[]>;
+}
+/** One captured line from a Program endpoint. */
+export type LogRecord = Readonly<{
+    createdAt: number;
+    process: string;
+    source: LogSource;
+    kind: LogKind;
+    content: string;
+}>;
+export type LogSource = "client" | "server";
+export type LogKind = "debug" | "log" | "info" | "warn" | "error" | "stdout" | "stderr" | "exit" | (string & {});

package/dist/storage.d.ts

@@ -0,0 +1,49 @@
+/** Metadata returned for an entry in Program-owned filesystem storage. */
+export type EntryStat = FileStat | DirectoryStat | OtherStat;
+export type FileStat = Readonly<{
+    kind: "file";
+    size: number;
+    modifiedAt: number;
+}>;
+export type DirectoryStat = Readonly<{
+    kind: "directory";
+    modifiedAt: number;
+}>;
+export type OtherStat = Readonly<{
+    kind: "other";
+    modifiedAt: number;
+}>;
+/** Filesystem-like storage owned by one Program. */
+export interface ProgramArea {
+    /** Reads one file as bytes. */
+    bytes(...path: string[]): Promise<Uint8Array>;
+    /** Reads one UTF-8 text file. */
+    text(...path: string[]): Promise<string>;
+    /** Reads and parses one JSON file. */
+    json<Value = unknown>(...path: string[]): Promise<Value>;
+    /** Opens one file as a byte stream. */
+    stream(...path: string[]): Promise<ReadableStream<Uint8Array>>;
+    /** Atomically writes one supported value, including a byte stream. */
+    write(...arguments_: [...path: string[], value: unknown]): Promise<void>;
+    /** Returns entry metadata, or `null` when the entry does not exist. */
+    stat(...path: string[]): Promise<EntryStat | null>;
+    /** Lists the sorted names immediately inside one directory. */
+    list(...path: string[]): Promise<string[]>;
+    /** Recursively removes an entry. A missing entry is accepted. */
+    delete(...path: string[]): Promise<void>;
+    /** Removes every entry while preserving the area itself. */
+    clear(): Promise<void>;
+}
+/** Persistent key-value storage owned by one Program. */
+export interface ProgramStore {
+    /** Returns a value, or `undefined` when its key is absent or expired. */
+    get<Value = unknown>(key: string): Promise<Value | undefined>;
+    /** Stores a value and optionally expires it after `ttl` milliseconds. */
+    set<Value>(key: string, value: Value, ttl?: number): Promise<boolean>;
+    /** Deletes one key or several keys and reports whether anything changed. */
+    delete(key: string | string[]): Promise<boolean>;
+    /** Returns whether a non-expired value exists for one key. */
+    has(key: string): Promise<boolean>;
+    /** Deletes every value in this Program's store. */
+    clear(): Promise<void>;
+}

package/dist/subscribable.d.ts

@@ -0,0 +1,72 @@
+/** The unconstrained message received by a general Subscribable. */
+export type Message = unknown;
+/** The message observed for one event on a Subscribable. */
+export type Capture<Event extends string = string, Received = Message> = Readonly<{
+    /** Name under which the message was published. */
+    event: Event;
+    /** Message delivered by the observed target. */
+    message: Received;
+}>;
+/** The string event names declared by an event map. */
+export type EventName<Events extends object> = Extract<keyof Events, string>;
+/** The message declared for one event name. */
+export type EventMessage<Events extends object, Fallback, Event extends string> = Event extends EventName<Events> ? Events[Event] : Fallback;
+/** The correlated union observed across every event declared by a target. */
+export type Captures<Events extends object, Fallback = never> = {
+    [Event in EventName<Events>]: Capture<Event, Events[Event]>;
+}[EventName<Events>] | ([Fallback] extends [never] ? never : Capture<string, Fallback>);
+/** A callback for one subscribed message. Its return value is not communication. */
+export type EventSubscriber<Message> = (message: Message) => unknown;
+/** A callback for an observed event and its message. */
+export type EventObserver<Events extends object, Fallback = never> = (capture: Captures<Events, Fallback>) => unknown;
+/** Removes exactly one persistent registration. Safe to call more than once. */
+export type Cleanup = () => void;
+/** Options controlling one asynchronous event iterator. */
+export type EventOptions = Readonly<{
+    /** Maximum queued messages. Defaults to `64`; `Infinity` removes the bound. */
+    capacity?: number;
+    /** Aborts iteration and removes its temporary boundary registration. */
+    signal?: AbortSignal;
+}>;
+type OpenEvent = string & {};
+type AvailableEvent<Events extends object, Fallback> = EventName<Events> | ([Fallback] extends [never] ? never : OpenEvent);
+type CompatibleEvent<Events extends object, Fallback, Narrowed> = {
+    [Event in EventName<Events>]: Narrowed extends Events[Event] ? Event : never;
+}[EventName<Events>] | ([Fallback] extends [never] ? never : Narrowed extends Fallback ? OpenEvent : never);
+interface Subscribe<Events extends object, Fallback> {
+    <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, subscriber: EventSubscriber<Narrowed>): Cleanup;
+    <Event extends AvailableEvent<Events, Fallback>>(event: Event, subscriber: EventSubscriber<EventMessage<Events, Fallback, Event>>): Cleanup;
+}
+interface WaitFor<Events extends object, Fallback> {
+    <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, timeout?: number): Promise<Narrowed>;
+    <Event extends AvailableEvent<Events, Fallback>>(event: Event, timeout?: number): Promise<EventMessage<Events, Fallback, Event>>;
+}
+interface EventStream<Events extends object, Fallback> {
+    <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, options?: EventOptions): AsyncIterableIterator<Narrowed>;
+    <Event extends AvailableEvent<Events, Fallback>>(event: Event, options?: EventOptions): AsyncIterableIterator<EventMessage<Events, Fallback, Event>>;
+}
+interface Observe<Events extends object, Fallback> {
+    (observer: EventObserver<Events, Fallback>): Cleanup;
+}
+/**
+ * The common receiving capability supplied by environment SDKs.
+ *
+ * Persistent registrations return their sole cleanup function. A registration
+ * may remain active across temporary endpoint absence and is removed only by
+ * that cleanup or by destruction of its owning boundary.
+ *
+ * `waitFor()` uses the SDK's ten-second deadline unless one is supplied.
+ * `events()` is long-lived instead: it ends when iteration is closed, its
+ * signal aborts, or the boundary proves that future delivery is impossible.
+ */
+export interface Subscribable<Events extends object = {}, Fallback = unknown> {
+    /** Registers one persistent named-event subscription. */
+    subscribe: Subscribe<Events, Fallback>;
+    /** Waits for the next matching message. */
+    waitFor: WaitFor<Events, Fallback>;
+    /** Iterates matching messages until closed, aborted, or impossible. */
+    events: EventStream<Events, Fallback>;
+    /** Registers one persistent observer across every event on this target. */
+    observe: Observe<Events, Fallback>;
+}
+export {};

package/dist/window.d.ts

@@ -0,0 +1,60 @@
+import type { Client } from "./client.js";
+import type { Layer, Position, Size } from "./launch.js";
+import type { Subscribable } from "./subscribable.js";
+/** Events emitted when authoritative Window state changes. */
+export type WindowEvents = {
+    move: Position;
+    resize: Size;
+    minimize: boolean;
+    changeTitle: string;
+    front: boolean;
+};
+/** Current authoritative Window state. */
+export type WindowState = Readonly<{
+    /** Current title. */
+    title: string;
+    /** Current top-left position. */
+    position: Position;
+    /** Current width and height. */
+    size: Size;
+    /** Whether the Window is minimized. */
+    minimized: boolean;
+    /** Whether the Window is frontmost in its layer. */
+    front: boolean;
+    /** Structurally isolated desktop layer containing the Window. */
+    layer: Layer;
+    /** Current page beneath the declared Client location. */
+    location: string;
+}>;
+/** The Window owned by one live Client. */
+export declare class Window<Events extends object = {}> {
+    constructor();
+}
+export interface Window<Events extends object = {}> extends Subscribable<WindowEvents & Events, never> {
+    /** Returns the Client that owns this Window. */
+    client(): Client;
+    /** Returns the current title. */
+    title(): Promise<string>;
+    /** Returns the current top-left position. */
+    position(): Promise<Position>;
+    /** Returns the current width and height. */
+    size(): Promise<Size>;
+    /** Returns whether the Window is minimized. */
+    minimized(): Promise<boolean>;
+    /** Returns whether the Window is frontmost in its layer. */
+    front(): Promise<boolean>;
+    /** Returns the structurally isolated desktop layer containing the Window. */
+    layer(): Promise<Layer>;
+    /** Returns the current page rooted beneath the declared Client location. */
+    location(): Promise<string>;
+    /** Moves the authoritative Window. */
+    move(position: Position): Promise<void>;
+    /** Resizes the authoritative Window. */
+    resize(size: Size): Promise<void>;
+    /** Changes whether the Window is minimized. */
+    minimize(minimized?: boolean): Promise<void>;
+    /** Changes the Window title. */
+    changeTitle(title: string): Promise<void>;
+    /** Brings the Window to the front of its own layer. */
+    raise(): Promise<void>;
+}

package/dist/window.js

@@ -0,0 +1,4 @@
+/** The Window owned by one live Client. */
+export class Window {
+    constructor() { }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@phreshos/core",
+  "version": "0.1.0",
+  "description": "Shared domain contracts for Program SDKs.",
+  "type": "module",
+  "main": "dist/main.js",
+  "types": "source/main.ts",
+  "exports": {
+    ".": {
+      "types": "./source/main.ts",
+      "default": "./dist/main.js"
+    }
+  },
+  "files": [
+    "dist",
+    "source",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsc --noEmit false --outDir dist --rootDir source",
+    "prepack": "node --run build"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}

package/source/askable.ts

@@ -0,0 +1,26 @@
+import type { Publishable } from "./publishable.js"
+
+/** An immutable Askable view using one caller-selected deadline. */
+export interface TimedAskable {
+  /** Sends one question and waits within the selected deadline. */
+  ask<Answer = unknown, Payload = unknown>(event: string, payload: Payload): Promise<Answer>
+}
+
+/** A publishing target that can also receive a question and return an answer. */
+export interface Askable<Events extends object = {}, Fallback = unknown>
+  extends Publishable<Events, Fallback> {
+  /**
+   * Sends one question payload to this target and waits for its answer.
+   *
+   * The SDK uses a ten-second deadline by default. It sends the question only
+   * after the current Server incarnation becomes ready. The operation rejects
+   * immediately when that Server is absent, and also rejects if the incarnation
+   * stops before readiness or before answering. One SDK deadline covers both
+   * readiness and the answer. The boundary cannot infer whether an answerer
+   * exists, so a ready unanswered question waits for that deadline.
+   */
+  ask<Answer = unknown, Payload = unknown>(event: string, payload: Payload): Promise<Answer>
+
+  /** Returns an immutable view whose `ask()` uses this deadline in milliseconds. */
+  timeout(milliseconds: number): TimedAskable
+}

package/source/channel.ts

@@ -0,0 +1,28 @@
+import type { Endpoint } from "./endpoint.js"
+import type { Captures, Subscribable } from "./subscribable.js"
+
+/** One application value arriving through the current Endpoint's Channel. */
+export type ChannelMessage<Payload = unknown, From = Endpoint> = Readonly<{
+  /** Endpoint that sent the message, or `null` when its identity is outside this boundary. */
+  from: From
+
+  /** Single value supplied by the publisher. */
+  payload: Payload
+}>
+
+/** Applies the sender envelope to every application event accepted here. */
+export type ChannelEvents<Events extends object, From = Endpoint> = {
+  readonly [Event in keyof Events]: ChannelMessage<Events[Event], From>
+}
+
+type ChannelFallback<Events extends object, From> = keyof Events extends never
+  ? ChannelMessage<unknown, From>
+  : never
+
+/** Every application event observable through a Channel. */
+export type ChannelCapture<Events extends object = {}, From = Endpoint> =
+  Captures<ChannelEvents<Events, From>, ChannelFallback<Events, From>>
+
+/** Events explicitly accepted by the current Endpoint. */
+export interface Channel<Events extends object = {}, From = Endpoint>
+  extends Subscribable<ChannelEvents<Events, From>, ChannelFallback<Events, From>> {}

package/source/client.ts

@@ -0,0 +1,29 @@
+import { Endpoint, type EndpointTraffic } from "./endpoint.js"
+import type { LaunchClient } from "./launch.js"
+import type { Server } from "./server.js"
+import type { Window } from "./window.js"
+
+/** Broad communication originating from one Client. */
+export interface ClientTraffic<
+  Events extends object = {},
+  To = Endpoint,
+  AskTo = Server
+> extends EndpointTraffic<Events, To, AskTo> {}
+
+/** The client Endpoint of a Process. */
+export class Client<Events extends object = {}> extends Endpoint<Events> {
+  public constructor() {
+    super()
+  }
+}
+
+export interface Client<Events extends object = {}> {
+  /** Broad communication originating from this Client. */
+  readonly traffic: ClientTraffic<Events>
+
+  /** Starts a fresh Client and Window using optional Process-local overrides. */
+  start(overrides?: LaunchClient): Promise<void>
+
+  /** Returns the Window owned by this live Client. */
+  window(): Promise<Window>
+}

package/source/config.ts

@@ -0,0 +1,104 @@
+import type { Layer, Position, Size } from "./launch.js"
+
+/** Development settings for a Program's Server. */
+export type ServerDevelopment = Readonly<{
+  /** Command that starts the development Server from the project directory. */
+  startCommand: string
+}>
+
+/** Development settings for a Program's Client. */
+export type ClientDevelopment = Readonly<{
+  /** HTTP(S) URL served by the Client's development server. */
+  url: string
+
+  /** Optional command that starts the Client's development server. */
+  startCommand?: string
+}>
+
+/** Authoring declaration for a Program's Server. */
+export type ServerConfig = Readonly<{
+  /** Production directory containing the Server. */
+  location: string
+
+  /** Whether a default Process starts its Server. Defaults to `true`. */
+  start?: boolean
+
+  /** Optional preparation command run from {@link location} while installing. */
+  installCommand?: string
+
+  /** Command that starts the production Server from {@link location}. */
+  startCommand: string
+
+  /** Settings used only by the development command. */
+  development?: ServerDevelopment
+}>
+
+/** Authoring declaration for a Program's Client and initial Window. */
+export type ClientConfig = Readonly<{
+  /** Production directory containing the Client and its `index.html`. */
+  location: string
+
+  /** Whether a default Process starts its Client. Defaults to `true`. */
+  start?: boolean
+
+  /** Initial Window title. Defaults to the Program name. */
+  title?: string
+
+  /** Initial Window size. */
+  size?: Size
+
+  /** Initial Window position. */
+  position?: Position
+
+  /** Structurally isolated desktop layer containing the Window. */
+  layer?: Layer
+
+  /** Whether the Window initially opens minimized. */
+  minimize?: boolean
+
+  /** Settings used only by the development command. */
+  development?: ClientDevelopment
+}>
+
+type Description = Readonly<{
+  /** Stable public identity written in kebab-case. */
+  identity: string
+
+  /** Human-readable Program name. Defaults to {@link identity}. */
+  name?: string
+
+  /** Program version shown to people and included in packages. */
+  version?: string
+
+  /** Short human-readable explanation of what the Program does. */
+  description?: string
+
+  /** Markdown file that officially introduces the Program's API. */
+  apiDocs?: string
+
+  /** Directory containing the Program's sized icons. */
+  icons?: string
+
+  /** Command run before production start, installation, and packaging. */
+  buildCommand?: string
+}>
+
+/**
+ * The authoring description read from `phresh.config.ts`.
+ *
+ * A Program must declare a Server, a Client, or both.
+ */
+export type Config = Description & (
+  | Readonly<{ server: ServerConfig, client?: ClientConfig }>
+  | Readonly<{ server?: ServerConfig, client: ClientConfig }>
+)
+
+/**
+ * Defines a Program authoring description with contextual typing.
+ *
+ * This helper performs no work and returns the supplied description unchanged.
+ * The CLI validates and derives it for development, production, or packaging.
+ */
+export function defineConfig<const Description extends Config>(config: Description): Description {
+  return config
+}

package/source/endpoint.ts

@@ -0,0 +1,95 @@
+import type { Process } from "./process.js"
+import type { Publishable } from "./publishable.js"
+import type { Server } from "./server.js"
+import type { Captures, Cleanup, Subscribable } from "./subscribable.js"
+
+/** One application value observed in traffic originating from an Endpoint. */
+export type TrafficMessage<Payload = unknown, To = Endpoint> = Readonly<{
+  /** Destination Endpoint, or `null` when its identity is outside this boundary. */
+  to: To
+
+  /** Single value supplied by the publisher. */
+  payload: Payload
+}>
+
+/** Applies destination metadata to every observed ordinary event. */
+export type TrafficEvents<Events extends object, To = Endpoint> = {
+  readonly [Event in keyof Events]: TrafficMessage<Events[Event], To>
+}
+
+type TrafficFallback<Events extends object, To> = keyof Events extends never
+  ? TrafficMessage<unknown, To>
+  : never
+
+/** One question sent by this Endpoint to a Server. */
+export type AskMessage<Payload = unknown, To = Server> = Readonly<{
+  /** Destination Server, or `null` when its identity is outside this boundary. */
+  to: To
+
+  /** Single question value supplied by the asker. */
+  payload: Payload
+}>
+
+/** One observed question sent by this Endpoint. */
+export type AskCapture<Payload = unknown, To = Server> = Readonly<{
+  /** Event addressed by the question. */
+  event: string
+
+  /** Correlation identity shared with the eventual answer. */
+  questionId: string
+
+  /** Question destination and payload. */
+  message: AskMessage<Payload, To>
+}>
+
+/** A callback that observes questions sent by this Endpoint. */
+export type AskObserver<Payload = unknown, To = Server> = (capture: AskCapture<Payload, To>) => unknown
+
+/** Every ordinary publication observable in traffic from one Endpoint. */
+export type TrafficCapture<Events extends object = {}, To = Endpoint> =
+  Captures<TrafficEvents<Events, To>, TrafficFallback<Events, To>>
+
+/** Broad communication originating from one Endpoint, regardless of destination. */
+export interface EndpointTraffic<
+  Events extends object = {},
+  To = Endpoint,
+  AskTo = Server
+> extends Subscribable<TrafficEvents<Events, To>, TrafficFallback<Events, To>> {
+  /** Observes questions originating from this Endpoint. */
+  observeAsks<Payload = unknown>(observer: AskObserver<Payload, AskTo>): Cleanup
+}
+
+/** The shared Process endpoint represented by Server and Client. */
+export class Endpoint<Events extends object = {}> {
+  public constructor() {}
+}
+
+export interface Endpoint<Events extends object = {}>
+  extends Publishable {
+  /** Broad communication originating from this Endpoint. */
+  readonly traffic: EndpointTraffic<Events>
+
+  /** Returns the Process that owns this Endpoint. */
+  process(): Process
+
+  /** Returns whether this Endpoint currently has a live incarnation. */
+  exists(): Promise<boolean>
+
+  /**
+   * Starts a fresh incarnation without waiting for Server readiness.
+   *
+   * Rejects when the Process is gone or inaccessible, the Program did not
+   * declare this endpoint kind, the Endpoint is already starting or live, or
+   * creation fails.
+   */
+  start(): Promise<void>
+
+  /**
+   * Stops the current incarnation and destroys its boundary-owned resources.
+   *
+   * Rejects when the Process is gone or inaccessible, the Endpoint is already
+   * stopping or absent, this is the Process's final live Endpoint, or stopping
+   * fails. Stopping never exits the Process implicitly.
+   */
+  stop(): Promise<void>
+}

package/source/launch.ts

@@ -0,0 +1,43 @@
+/** A pixel count or a relative linear expression. */
+export type Value = number | string
+
+/** A Window's top-left position. */
+export type Position = Readonly<{
+  /** Horizontal position. */
+  x: Value
+
+  /** Vertical position. */
+  y: Value
+}>
+
+/** A Window's width and height. */
+export type Size = Readonly<{
+  /** Window width. */
+  width: Value
+
+  /** Window height. */
+  height: Value
+}>
+
+/** A structurally isolated desktop layer. */
+export type Layer = "window" | "under" | "over"
+
+/** Every structurally isolated desktop layer. */
+export const layers: readonly Layer[] = ["window", "under", "over"]
+
+/** Per-Process overrides used when starting a Client and its Window. */
+export type LaunchClient = Readonly<{
+  size?: Size
+  position?: Position
+  layer?: Layer
+  location?: string
+  minimize?: boolean
+}>
+
+/** Initial endpoint selection and immutable options for one Process. */
+export type Launch = Readonly<{
+  name?: string
+  server?: boolean
+  client?: boolean | LaunchClient
+  options?: Readonly<Record<string, string>>
+}>