@phreshos/core 0.1.0 → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,42 +1,131 @@
 # `@phreshos/core`
 
-The Core SDK defines the domain objects and types shared by the client and
-server SDKs. It contains no transport or subscription implementation.
+Environment-neutral contracts and domain objects for PhreshOS Programs. Core
+is the common language shared by the Client, Server, React, CLI, and system
+repositories; it contains no transport, persistence, or interface
+implementation of its own.
+
+## Installation
+
+```sh
+bun add @phreshos/core
+```
+
+Import exclusively through the package's public root:
+
+```ts
+import { defineConfig, type Program } from "@phreshos/core"
+```
+
+The package exposes built JavaScript and declaration files as its only public
+code. Its TypeScript source is repository material, not a runtime dependency
+or a public import path.
 
 ## Package status
 
-This package is one component of a larger architecture that is still under
-active testing. The architecture's components will be released in stages as
-their contracts and integrations are verified.
+This package is one component of a larger architecture currently under active
+testing. The `0.x` line may change as its contracts and integrations are
+verified.
 
 `@phreshos/core` is not intended to be used on its own. It defines the shared
-contracts consumed by the environment SDKs and does not provide a runtime
+contracts consumed by the environment SDKs, but does not provide a runtime
 implementation by itself.
 
-`Subscribable` is the independent receiving capability. It provides the
+## Mental model
+
+Programs use Core directly for `defineConfig()` and shared types. At runtime,
+the Client and Server SDKs provide the real `Program`, `Process`, `Server`, and
+`Client` handles backed by their environment boundaries. Core gives those
+environments one vocabulary and stable runtime identity without implementing
+their transport, storage, authority, or presentation.
+
+## Permission names
+
+Core owns the finite, system-wide permission registry. `permissionNames` is
+its runtime value, `PermissionName` is the corresponding SDK type, and
+`isPermissionName()` validates values arriving from untyped boundaries. Client
+and Server SDK permission methods accept only this type, so Programs cannot
+create private permission strings that the system does not understand.
+
+The current registry contains `pointer`. Persistent snapshots use
+`PermissionDecisions`, a partial map, since an absent permission simply has no
+stored decision.
+
+## Theme lifecycle
+
+Core defines both `ThemeProperties` and the read-only `Theme` contract without
+any knowledge of how a given interface renders them. `snapshot()` is an
+explicit, asynchronous read of one complete, immutable value. `Theme` extends
+the ordinary `Subscribable` capability with a `change` event; it has no
+dedicated subscription shape of its own.
+
+Theme properties are expressed as concrete default values. `themeLimits`
+declares the system-owned customization bounds for spacing, corner radius, and
+glass-material properties; implementing authorities validate replacements
+against those bounds. Core defines one fixed numeric scale around any explicit
+number and one fixed color scale around any explicit CSS color — it does not
+prescribe which value an interface ultimately chooses to derive. Background,
+foreground, and accent are independent CSS color sources, with standard values
+of `#edf8fc`, `#183447`, and `#4c9cff` — the established pale surface, primary
+ink, and original system blue, respectively. Core stores only those source
+colors, never their derived treatments. The declared glass-opacity range ends
+at `0.3`.
+
+`standardTheme` is the single, complete initial value shared by every
+environment; the running system remains the authority for its current value.
+`createThemeSnapshot()` copies and freezes a complete replacement at the
+contract boundary; validation remains the implementing authority's
+responsibility.
+
+Derived variants are calculations, not persisted `Theme` state. `numericScale()`
+produces `xsmall`, `small`, `medium`, `large`, and `xlarge`, preserving the
+supplied value exactly at `medium`. `color()` produces `subtle`, `soft`, `base`,
+`strong`, and `intense`, preserving the supplied color exactly at `base`.
+
+`subscribe("change", listener)` delivers only complete replacements published
+after that registration exists. It never supplies an initial snapshot and
+never replays a change published earlier; Programs request the current
+snapshot explicitly when they need one. `WritableTheme` adds asynchronous
+authority to replace the value — a read-only environment exposes `Theme`,
+while an authorized environment may expose `WritableTheme` without altering
+the shared lifecycle.
+
+`Colorable`, `Sizable`, `Shapeable`, `Variantable`, and `Elevatable` are
+independent element capabilities whose concrete value vocabularies are defined
+separately. An element composes only the capabilities it actually supports.
+
+These contracts contain no React types, component names, or runtime `Theme`
+authority. Environment and interface SDKs build those concerns on top of the
+same neutral lifecycle and derivations.
+
+## Messaging primitives
+
+`Subscribable` is the independent receiving capability, providing the
 contracts for `subscribe()`, `waitFor()`, `events()`, and `observe()`.
 `Publishable` independently provides `publish()`. `Askable` extends
-`Publishable` with `ask()`, because every target that can be asked can also be
-published to. A type may implement or compose only the capabilities it needs;
-being able to publish does not imply being able to subscribe.
+`Publishable` with `ask()`, since every target that can be asked can also be
+published to. Both operations accept a single payload, which is `undefined`
+when omitted. A type may implement or compose only the capabilities it needs —
+the ability to publish does not imply the ability to subscribe.
 
-Finite asynchronous operations use a ten-second SDK deadline by default.
-`Askable.timeout()` creates an immutable deadline view for `ask()` only;
-`waitFor()` and `waitReady()` accept a deadline directly. `events()` is a
-long-lived iterator with a bounded queue rather than a timed request. An ask's
-single deadline covers both waiting for its current Server incarnation to
-become ready and waiting for the eventual answer.
+The contracts specify a ten-second default SDK deadline for finite asynchronous
+operations. `Askable.timeout()` creates an immutable deadline view scoped to
+`ask()`; `waitFor()` and `waitReady()` accept a deadline directly. `events()`
+is specified as a long-lived iterator with a queue capacity of `64` by default,
+while `Infinity` removes that bound. A single ask deadline covers both waiting
+for its current Server incarnation to become ready and waiting for the eventual
+answer. Environment SDKs implement these guarantees.
 
-Every persistent registration returns its only cleanup function:
+Every persistent registration returns its own cleanup function:
 
 ```ts
 const stop = target.subscribe("event", handler)
 stop()
 ```
 
-There are no separate `unsubscribe()` or `unobserve()` methods and no
+There are no separate `unsubscribe()` or `unobserve()` methods, and no
 one-time subscription operation. Observation APIs such as `observeAsks()` and
-`observeAnswers()` follow the same returned-cleanup rule.
+`observeAnswers()` follow the same returned-cleanup convention.
 
 ```ts
 import type { Subscribable } from "@phreshos/core"
@@ -57,78 +146,143 @@ target.subscribe("exit", message => {
 ```
 
 Known messages are inferred from the target. An explicit generic or callback
-annotation may narrow that message, but an incompatible replacement is a type
-error. `observe()` receives a `Capture` containing only the facts guaranteed by
-every Subscribable: `event` and `message`. It makes no assumption about a
-sender or destination.
-
-An unparameterized Channel or traffic surface accepts application-defined event
-names with an `unknown` payload. Supplying an event map narrows both the names
-and their payloads; names outside that map are then rejected.
-
-`events()` applies the same message inference and narrowing rules and exposes a
-named event as an `AsyncIterableIterator`.
-
-`Endpoint` is the shared base of Server and Client and composes only
-`Publishable`. It is an address and lifecycle-control handle, never a receiving
-surface. Server additionally composes `Askable`. Every event explicitly
-addressed to the executing Endpoint enters only through its contextual
-`Channel`, whose `ChannelMessage` contains the otherwise unknown sender. An
-environment may narrow that reference to `Endpoint | null` when its isolation
-boundary deliberately hides foreign identities.
-
-Broad inspection is deliberately separated as `endpoint.traffic`. The Endpoint
-handle already identifies the source, so ordinary traffic messages contain only
-the unknown destination and payload. Every traffic surface exposes
-`observeAsks()` because either Endpoint kind may originate a question. A
-Server's traffic additionally exposes `observeAnswers()`, because only a Server
+annotation may narrow that message further, but an incompatible replacement is
+a type error. `observe()` receives a `Capture` containing only the facts
+guaranteed by every `Subscribable`: `event` and `message`. It makes no
+assumption about a sender or destination.
+
+An unparameterized Endpoint, Channel, or traffic surface accepts
+application-defined event names with an `unknown` payload. Supplying an event
+map narrows both the names and their payloads, and names outside that map are
+then rejected. `events()` applies the same message inference and narrowing
+rules, exposing a named event as an `AsyncIterableIterator`.
+
+## Endpoints, Channels, and traffic
+
+`Endpoint` is the shared base of `Server` and `Client`. It functions as both
+an address and a source: `endpoint.publish()` sends directly to it, while
+`endpoint.subscribe()` and `endpoint.observe()` follow destinationless events
+emitted by it. `Server` additionally composes `Askable`.
+
+The contextual `Channel` is the executing Endpoint's inward boundary.
+Subscriptions receive events explicitly addressed to it, delivered as a
+`ChannelMessage` containing the otherwise unknown sender. `channel.publish()`
+emits outward from that executing Endpoint without naming a destination.
+
+Directed inspection remains deliberately separate, exposed as
+`endpoint.traffic`. Because the Endpoint handle already identifies the source,
+ordinary traffic messages contain only the destination and payload; Channel
+emissions never enter this surface. Every traffic surface exposes
+`observeAsks()`, since either Endpoint kind may originate a question. A
+Server's traffic additionally exposes `observeAnswers()`, since only a Server
 can originate an answer. These captures include their event, correlation ID,
 destination, and question payload or answer `Outcome`.
 
 Every Endpoint exposes `exists()`, `start()`, and `stop()`. Endpoint lifecycle
-is observed through the owning Process's `serverStart`, `serverStop`,
-`clientStart`, and `clientStop` events rather than through Endpoint
-subscriptions.
+is observed through `endpointStart` and `endpointStop` at Process, Program,
+and Server Host scope. A start delivers the permanent `Server | Client`
+handle; a stop delivers that same permanent handle directly. Every scope
+receives the same canonical Endpoint instance, allowing comparison by
+identity. Neither lifecycle event wraps the Endpoint or carries process-exit
+details, and Endpoint subscriptions themselves carry only application events
+emitted by that Endpoint.
 
 `Server` and `Client` are public, logic-free Endpoint specializations. Server
-adds one-payload `ask()` and answer traffic observation. Client returns its owned
-Window. Window returns its owning Client, preserving navigation in both
-directions without introducing host or transport knowledge.
-
-Program and Process complete the ownership hierarchy. Every public domain
-object remains a real runtime class for identity and `instanceof`, while the
-capabilities it implements are independent interfaces. Constructors are public
-and logic-free during this contract phase; all methods remain declarations
-until an environment SDK supplies their implementation.
-Core also owns the common launch, geometry, lifecycle-message, ChannelMessage,
-ChannelCapture, TrafficMessage, and TrafficCapture types used by both
+adds request-response `ask()` and answer-traffic observation. Client owns two
+permanent, synchronous capability objects: `traffic` for communication and
+`window` for presentation. Accessing either object performs no operation and
+receives no data — their methods and subscriptions are the explicit
+operations.
+
+## Ownership hierarchy
+
+`Program` and `Process` complete the ownership hierarchy. `Program`,
+`Process`, `Endpoint`, `Server`, and `Client` are real runtime classes,
+usable for identity and `instanceof` checks. Their capability properties are
+interfaces: `client.traffic` and `client.window`, in particular, have no
+runtime class identity of their own. Core domain constructors are protected —
+environment SDKs supply the authoritative handles backed by their respective
+boundaries while reusing these exact Core constructors.
+
+Core also owns the common launch, geometry, lifecycle-message, `ChannelMessage`,
+`ChannelCapture`, `TrafficMessage`, and `TrafficCapture` types used by both
 environments.
 
-Process parentage belongs to `Process`, not to contextual SDK state.
-Each live Process retains only a handle to its immediate parent.
-`process.parent()` returns `null` when no accessible parent handle exists. It
-does not preserve historical lineage: calling it through an exited Process
-handle, or after the retained parent has disappeared, rejects because the
-represented Process does not exist. A future `current.parent()` may flatten
-this operation, but does not own the relationship.
+## Window placement
+
+Window placement is expressed through two deliberately separate contracts.
+Authoring `Layer` contains only `under`, `window`, and `over`, so that
+Program declarations and Client launch overrides cannot request system-owned
+placement. Runtime `WindowLayer` adds `wallpaper`, allowing `window.layer()`
+to report the truth for a wallpaper Window without making that layer
+constructible from Program code. `Window` has no identity or lifecycle apart
+from its Client; its stable capability addresses the Client's current, live
+presentation state and rejects reads or mutations while that Client is
+absent.
+
+Core also defines the independent, environment-neutral `FileWallpaper` and
+`DesktopWallpaper` contracts. The desktop variant additionally accepts a
+Program and the deliberately narrow `WallpaperLaunch`, containing only `name`,
+`server`, the Client's initial `location`, and immutable Process `options`.
+These contracts describe capability and data shape only — they contain no
+persistence, upload, Process creation, or rendering implementation.
+
+## Window Surface
+
+`client.window.surface` addresses the optional host-rendered material belonging
+to one Window. Its source of truth is authoritative, server-owned Window state,
+not iframe state. `snapshot()` explicitly reads the current target, while the
+ordinary `change` subscription receives only replacements published after that
+subscription exists. A `null` target means no Surface exists in the render
+tree.
+
+Only Windows currently occupying the `under` or `over` layer may call `set()`
+or `remove()`; `window` and `wallpaper` layers reject those operations. Calling
+`set()` without settings creates a sharp, fully opaque Surface. Settings may
+select opacity from zero to one, a nonnegative pixel radius, a scale level, or
+`"full"`, and an optional transaction containing a duration from zero through
+60,000 milliseconds and a stable named or cubic Bézier easing. Zero opacity
+retains the Surface node; only `remove()` returns the authoritative target
+immediately to `null`. The server validates settings, and the desktop animates
+from the rendered values to each new target.
+
+## Window geometry
+
+Window geometry follows one public grammar. A `Value` is either a finite
+pixel number or a linear relative expression such as `"1/2"`, `"50% + 10"`, or
+`"30% + 20 * 2"`. `isRelativeValue()` validates that grammar, and
+`parseRelativeValue()` reduces it to a single relative coefficient and pixel
+offset. The CLI, runtime validation, and desktop layout all consume this one
+Core definition rather than maintaining separate parsers.
+
+## Process parentage
+
+Process parentage belongs to `Process`, not to contextual SDK state. Each
+live Process retains only a handle to its immediate parent. `process.parent()`
+returns `null` when no accessible parent handle exists, and does not preserve
+historical lineage: calling it through an exited Process handle, or after the
+retained parent has disappeared, rejects outright, since the represented
+Process no longer exists. `current.parent()` flattens this operation
+contextually but does not itself own the relationship.
 
 Client traversal is structurally confined to its current Program. A
-cross-Program parent handle is never supplied to the client, so traversal stops
-at `null`. A fabricated or otherwise unauthorized Process handle is
-indistinguishable from a nonexistent Process and every operation through it
-rejects accordingly.
+cross-Program parent handle is never supplied to the Client, so traversal
+stops at `null`. A fabricated or otherwise unauthorized Process handle is
+indistinguishable from a nonexistent Process, and every operation performed
+through it rejects accordingly.
 
 ## Program configuration
 
-Core is also the single source of truth for the authoring contract consumed by
-the CLI. `defineConfig()` provides contextual typing for `phresh.config.ts` and
-returns the description unchanged:
+Core is also the single source of truth for the authoring contract consumed
+by the CLI. `defineConfig()` provides contextual typing for
+`phresh.config.ts` and returns the description unchanged:
 
 ```ts
 import { defineConfig } from "@phreshos/core"
 
 export default defineConfig({
   identity: "my-program",
+  icon: "./icon.png",
   server: {
     location: "./dist/server",
     startCommand: "node main.js",
@@ -146,9 +300,22 @@ export default defineConfig({
 })
 ```
 
-The declaration must contain a Server, a Client, or both. Development settings
-remain authoring metadata; the CLI derives the appropriate runtime description
-for each mode.
+The declaration must include a Server, a Client, or both. Development
+settings remain authoring metadata; the CLI derives the appropriate runtime
+description for each mode. The optional `icon` field names a single PNG
+source — packaging and installation normalize it to `icon.png`, while hosting
+derives the system's fixed presentation sizes.
+
+Every Program also exposes its guaranteed icon without revealing hosting or
+filesystem details:
+
+```ts
+const icon = await program.icon()          // medium PNG Blob
+const large = await program.icon("large")  // small, medium, or large
+```
+
+This method always returns an `image/png` `Blob`. When no icon has been
+authored, the system returns its default through the same operation.
 
 ## Program-owned resources
 
@@ -157,3 +324,7 @@ filesystem-like `data` and `cache`, a key-value `store`, read-only SQL `logs`,
 and a writable SQLite `database`. The Server SDK refines its filesystem areas
 with `path()` and safe `resolve()` access; these host filesystem paths are
 structurally absent from the Client SDK.
+
+## License
+
+Licensed under the [MIT License](LICENSE). Copyright © 2026 Zohayr SLILEH.

package/dist/askable.d.ts

@@ -1,11 +1,14 @@
 import type { Publishable } from "./publishable.js";
+import type { Timeoutable } from "./timeout.js";
 /** An immutable Askable view using one caller-selected deadline. */
 export interface TimedAskable {
+    /** Sends a question with an `undefined` payload and waits within the selected deadline. */
+    ask<Answer = unknown>(event: string): Promise<Answer>;
     /** 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> {
+export interface Askable<Events extends object = {}, Fallback = unknown> extends Publishable<Events, Fallback>, Timeoutable<TimedAskable> {
     /**
      * Sends one question payload to this target and waits for its answer.
      *
@@ -16,6 +19,7 @@ export interface Askable<Events extends object = {}, Fallback = unknown> extends
      * readiness and the answer. The boundary cannot infer whether an answerer
      * exists, so a ready unanswered question waits for that deadline.
      */
+    ask<Answer = unknown>(event: string): Promise<Answer>;
     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/dist/channel.d.ts

@@ -1,4 +1,5 @@
 import type { Endpoint } from "./endpoint.js";
+import type { Publishable } from "./publishable.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<{
@@ -14,7 +15,7 @@ export type ChannelEvents<Events extends object, From = Endpoint> = {
 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>> {
+/** Addressed input and destinationless output for the executing Endpoint. */
+export interface Channel<Events extends object = {}, From = Endpoint> extends Subscribable<ChannelEvents<Events, From>, ChannelFallback<Events, From>>, Publishable {
 }
 export {};

package/dist/client.d.ts

@@ -2,18 +2,18 @@ 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. */
+/** Directed 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 declare class Client<Events extends object = {}> extends Endpoint<Events> {
-    constructor();
+    protected constructor();
 }
 export interface Client<Events extends object = {}> {
-    /** Broad communication originating from this Client. */
+    /** Directed communication originating from this Client. */
     readonly traffic: ClientTraffic<Events>;
+    /** Presentation capability permanently owned by this Client handle. */
+    readonly window: Window;
     /** 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/dist/color.d.ts

@@ -0,0 +1,10 @@
+/** Semantic treatments derived from one explicit CSS color. */
+export type ColorLevel = "subtle" | "soft" | "base" | "strong" | "intense";
+/** Complete color scale derived from one explicit CSS color. */
+export type ColorScale = Readonly<Record<ColorLevel, string>>;
+/**
+ * Derives a balanced color scale while preserving the supplied color as its
+ * exact base. CSS performs the mixing in OKLCH, so every valid CSS color can be
+ * the source without the system maintaining a second palette.
+ */
+export declare function color(value: string): ColorScale;

package/dist/color.js

@@ -0,0 +1,14 @@
+/**
+ * Derives a balanced color scale while preserving the supplied color as its
+ * exact base. CSS performs the mixing in OKLCH, so every valid CSS color can be
+ * the source without the system maintaining a second palette.
+ */
+export function color(value) {
+    return Object.freeze({
+        subtle: `color-mix(in oklch, ${value} 25%, white)`,
+        soft: `color-mix(in oklch, ${value} 60%, white)`,
+        base: value,
+        strong: `color-mix(in oklch, ${value} 82%, black)`,
+        intense: `color-mix(in oklch, ${value} 68%, black)`
+    });
+}

package/dist/config.d.ts

@@ -52,30 +52,41 @@ type Description = Readonly<{
     version?: string;
     /** Short human-readable explanation of what the Program does. */
     description?: string;
-    /** Markdown file that officially introduces the Program's API. */
+    /**
+     * Markdown file describing only the Program-owned API contract.
+     * System access, Endpoint, and event mechanics belong to system documentation.
+     */
     apiDocs?: string;
-    /** Directory containing the Program's sized icons. */
-    icons?: string;
+    /** PNG source between 128 and 2,048 pixels per side and no larger than 5 MiB. */
+    icon?: string;
     /** Command run before production start, installation, and packaging. */
     buildCommand?: string;
 }>;
+type ServerProgramConfig = Description & Readonly<{
+    /** Server declaration for this Program. */
+    server: ServerConfig;
+    /** Optional Client declaration for this Program. */
+    client?: ClientConfig;
+}>;
+type ClientProgramConfig = Description & Readonly<{
+    /** Optional Server declaration for this Program. */
+    server?: ServerConfig;
+    /** Client declaration for this Program. */
+    client: ClientConfig;
+}>;
 /**
  * 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;
-}>);
+export type Config = ServerProgramConfig | ClientProgramConfig;
 /**
  * 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 declare function defineConfig<const Description extends Config>(config: Description): Description;
+export declare function defineConfig(config: ServerProgramConfig): Config;
+/** Defines a Program authoring description with contextual typing. */
+export declare function defineConfig(config: ClientProgramConfig): Config;
 export {};

package/dist/config.js

@@ -1,9 +1,3 @@
-/**
- * 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(config) {
     return config;
 }

package/dist/endpoint.d.ts

@@ -34,20 +34,21 @@ export type AskCapture<Payload = unknown, To = Server> = Readonly<{
 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. */
+/** Directed communication originating from one Endpoint. */
 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 declare class Endpoint<Events extends object = {}> {
-    constructor();
+    protected constructor();
 }
-export interface Endpoint<Events extends object = {}> extends Publishable {
-    /** Broad communication originating from this Endpoint. */
+/** An Endpoint address that can also be followed as a destinationless source. */
+export interface Endpoint<Events extends object = {}> extends Publishable, Subscribable<Events, keyof Events extends never ? unknown : never> {
+    /** Directed communication originating from this Endpoint. */
     readonly traffic: EndpointTraffic<Events>;
     /** Returns the Process that owns this Endpoint. */
-    process(): Process;
+    process(): Promise<Process>;
     /** Returns whether this Endpoint currently has a live incarnation. */
     exists(): Promise<boolean>;
     /**

package/dist/launch.d.ts

@@ -1,5 +1,4 @@
-/** A pixel count or a relative linear expression. */
-export type Value = number | string;
+import type { Value } from "./value.js";
 /** A Window's top-left position. */
 export type Position = Readonly<{
     /** Horizontal position. */
@@ -20,16 +19,25 @@ export type Layer = "window" | "under" | "over";
 export declare const layers: readonly Layer[];
 /** Per-Process overrides used when starting a Client and its Window. */
 export type LaunchClient = Readonly<{
+    /** Initial Window size for this Process. */
     size?: Size;
+    /** Initial Window position for this Process. */
     position?: Position;
+    /** Structurally isolated layer containing this Process's Window. */
     layer?: Layer;
+    /** Initial page beneath the Client's declared location scope. */
     location?: string;
+    /** Whether the Window initially opens minimized. */
     minimize?: boolean;
 }>;
 /** Initial endpoint selection and immutable options for one Process. */
 export type Launch = Readonly<{
+    /** Optional meaningful name unique among this Program's live Processes. */
     name?: string;
+    /** Whether to start the declared Server. Uses its declaration when omitted. */
     server?: boolean;
+    /** Whether and how to start the declared Client. Uses its declaration when omitted. */
     client?: boolean | LaunchClient;
+    /** Immutable string options readable by the created Process. */
     options?: Readonly<Record<string, string>>;
 }>;