@phreshos/core 0.1.1 → 0.1.3

package/README.md

@@ -220,6 +220,13 @@ from its Client; its stable capability addresses the Client's current, live
 presentation state and rejects reads or mutations while that Client is
 absent.
 
+`LaunchClient.title` supplies a dynamic initial title when starting a declared
+Client. The system resolves it with the remaining launch shape before the
+Client is announced, so the first rendered Window already has its final title.
+Omission uses the Program declaration; `window.changeTitle()` remains the live
+operation after startup. Window operations are never queued while the 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`,
@@ -231,10 +238,9 @@ persistence, upload, Process creation, or rendering implementation.
 
 `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.
+not iframe state. Program endpoints may explicitly replace or remove that
+target, but cannot read or subscribe to it. 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

package/dist/askable.d.ts

@@ -12,12 +12,11 @@ export interface Askable<Events extends object = {}, Fallback = unknown> extends
     /**
      * 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.
+     * The SDK uses a ten-second deadline by default. Any target-specific
+     * readiness wait shares that same deadline with the answer. The operation
+     * rejects when the target is known to be unavailable, or stops before
+     * answering. A boundary cannot infer whether an answerer exists, so a
+     * delivered but unanswered question waits for the deadline.
      */
     ask<Answer = unknown>(event: string): Promise<Answer>;
     ask<Answer = unknown, Payload = unknown>(event: string, payload: Payload): Promise<Answer>;

package/dist/channel.d.ts

@@ -17,5 +17,9 @@ type ChannelFallback<Events extends object, From> = keyof Events extends never ?
 export type ChannelCapture<Events extends object = {}, From = Endpoint> = Captures<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 {
+    /** Exposes this executing Channel under one public service name. */
+    enableService(name: string): Promise<void>;
+    /** Stops exposing this executing Channel as a service. */
+    disableService(): Promise<void>;
 }
 export {};

package/dist/client.d.ts

@@ -2,6 +2,7 @@ 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";
+import type { ClientServiceHandler } from "./service.js";
 /** Directed communication originating from one Client. */
 export interface ClientTraffic<Events extends object = {}, To = Endpoint, AskTo = Server> extends EndpointTraffic<Events, To, AskTo> {
 }
@@ -16,4 +17,6 @@ export interface Client<Events extends object = {}> {
     readonly window: Window;
     /** Starts a fresh Client and Window using optional Process-local overrides. */
     start(overrides?: LaunchClient): Promise<void>;
+    /** Returns this Client's current complete service handle, or `null`. */
+    service<ServiceEvents extends object = {}>(): Promise<ClientServiceHandler<ServiceEvents> | null>;
 }

package/dist/endpoint.d.ts

@@ -1,6 +1,7 @@
 import type { Process } from "./process.js";
 import type { Publishable } from "./publishable.js";
 import type { Server } from "./server.js";
+import type { ServiceHandler } from "./service.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<{
@@ -67,5 +68,7 @@ export interface Endpoint<Events extends object = {}> extends Publishable, Subsc
      * fails. Stopping never exits the Process implicitly.
      */
     stop(): Promise<void>;
+    /** Returns this Endpoint's current complete service handle, or `null`. */
+    service(): Promise<ServiceHandler | null>;
 }
 export {};

package/dist/launch.d.ts

@@ -19,6 +19,8 @@ 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 title for this Client incarnation. */
+    title?: string;
     /** Initial Window size for this Process. */
     size?: Size;
     /** Initial Window position for this Process. */

package/dist/main.d.ts

@@ -2,6 +2,7 @@ export { type Message, type Cleanup, type Capture, type Captures, type EventMess
 export { type Publishable } from "./publishable.js";
 export { type Timeoutable } from "./timeout.js";
 export { type Askable, type TimedAskable } from "./askable.js";
+export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, isServiceKey, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "./service.js";
 export { isPermissionName, permissionNames, type PermissionDecision, type PermissionDecisions, type PermissionName, type Permissions, type ProgramPermissions, type TimedPermissions } from "./permissions.js";
 export { type Outcome } from "./outcome.js";
 export { type ServedFile } from "./served-file.js";
@@ -18,6 +19,6 @@ export { Server, type AnswerCapture, type AnswerMessage, type AnswerObserver, ty
 export { Client, type ClientTraffic } from "./client.js";
 export { Process, type Exit, type ProcessEvents } from "./process.js";
 export { Program, type ClientDeclaration, type EndpointDeclaration, type ProgramEvents, type ProgramIconSize, type ProgramProcessExit } from "./program.js";
-export { type Window, type WindowEvents, type WindowLayer, type WindowState, type WindowSurface, type WindowSurfaceEasing, type WindowSurfaceEvents, type WindowSurfaceSettings, type WindowSurfaceTransaction } from "./window.js";
+export { type Window, type WindowEvents, type WindowLayer, type WindowState, type WindowSurface, type WindowSurfaceEasing, type WindowSurfaceSettings, type WindowSurfaceTransaction } from "./window.js";
 export { layers, type Launch, type LaunchClient, type Layer, type Position, type Size } from "./launch.js";
 export { defineConfig, type ClientConfig, type ClientDevelopment, type Config, type ServerConfig, type ServerDevelopment } from "./config.js";

package/dist/main.js

@@ -2,6 +2,7 @@ export {} from "./subscribable.js";
 export {} from "./publishable.js";
 export {} from "./timeout.js";
 export {} from "./askable.js";
+export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, isServiceKey } from "./service.js";
 export { isPermissionName, permissionNames } from "./permissions.js";
 export {} from "./outcome.js";
 export {} from "./served-file.js";

package/dist/server.d.ts

@@ -2,6 +2,7 @@ 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";
+import type { ServerServiceHandler } from "./service.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. */
@@ -39,4 +40,6 @@ export interface Server<Events extends object = {}> extends Askable {
      * The SDK uses its ten-second deadline unless one is supplied.
      */
     waitReady(timeout?: number): Promise<void>;
+    /** Returns this Server's current complete service handle, or `null`. */
+    service<ServiceEvents extends object = {}>(): Promise<ServerServiceHandler<ServiceEvents> | null>;
 }

package/dist/service.d.ts

@@ -0,0 +1,61 @@
+import type { Askable } from "./askable.js";
+import type { Subscribable } from "./subscribable.js";
+/** Stable public coordinates of one explicitly named Endpoint service. */
+export type ServiceKey = Readonly<{
+    /** Stable identity of the Program that owns the providing Endpoint. */
+    program: string;
+    /** Endpoint kind deliberately exposed by the service author. */
+    endpoint: "server" | "client";
+    /** Program-authored service identity. */
+    name: string;
+}>;
+/** Lifecycle transitions of one exact service identity. */
+export type ServiceLifecycleEvents = {
+    /** A live Endpoint began providing this service. */
+    enable: undefined;
+    /** The providing Endpoint stopped exposing this service. */
+    disable: undefined;
+};
+/** Application events emitted by one service. */
+export interface ServiceChannel<Events extends object = {}> extends Subscribable<Events, keyof Events extends never ? unknown : never> {
+}
+/** Communication surface of a service provided by a Server Endpoint. */
+export interface ServerServiceChannel<Events extends object = {}> extends ServiceChannel<Events>, Askable {
+}
+/** Communication surface of a service provided by a Client Endpoint. */
+export interface ClientServiceChannel<Events extends object = {}> extends ServiceChannel<Events> {
+}
+/** Stable lifecycle handle for one exact public service identity. */
+export declare class ServiceHandler<Channel extends object = ServiceChannel> {
+    protected constructor();
+}
+export interface ServiceHandler<Channel extends object = ServiceChannel> extends Subscribable<ServiceLifecycleEvents, never> {
+    /** Program namespace of this service. */
+    readonly program: string;
+    /** Endpoint kind represented by this service. */
+    readonly endpoint: "server" | "client";
+    /** Program-authored service identity. */
+    readonly name: string;
+    /** Application communication, separate from service lifecycle. */
+    readonly channel: Channel;
+    /** Explicitly reads whether no live Endpoint currently provides the service. */
+    disabled(): Promise<boolean>;
+}
+/** Stable handle for one Server-provided service. */
+export declare class ServerServiceHandler<Events extends object = {}> extends ServiceHandler<ServerServiceChannel<Events>> {
+    protected constructor();
+}
+export interface ServerServiceHandler<Events extends object = {}> {
+    readonly endpoint: "server";
+    readonly channel: ServerServiceChannel<Events>;
+}
+/** Stable handle for one Client-provided service. */
+export declare class ClientServiceHandler<Events extends object = {}> extends ServiceHandler<ClientServiceChannel<Events>> {
+    protected constructor();
+}
+export interface ClientServiceHandler<Events extends object = {}> {
+    readonly endpoint: "client";
+    readonly channel: ClientServiceChannel<Events>;
+}
+/** Returns whether a boundary value is a complete service key. */
+export declare function isServiceKey(value: unknown): value is ServiceKey;

package/dist/service.js

@@ -0,0 +1,27 @@
+/** Stable lifecycle handle for one exact public service identity. */
+export class ServiceHandler {
+    constructor() { }
+}
+/** Stable handle for one Server-provided service. */
+export class ServerServiceHandler extends ServiceHandler {
+    constructor() {
+        super();
+    }
+}
+/** Stable handle for one Client-provided service. */
+export class ClientServiceHandler extends ServiceHandler {
+    constructor() {
+        super();
+    }
+}
+/** Returns whether a boundary value is a complete service key. */
+export function isServiceKey(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return typeof candidate.program === "string"
+        && candidate.program.length > 0
+        && (candidate.endpoint === "server" || candidate.endpoint === "client")
+        && typeof candidate.name === "string"
+        && candidate.name.length > 0;
+}

package/dist/window.d.ts

@@ -21,15 +21,8 @@ export type WindowSurfaceSettings = Readonly<{
     /** Optional motion from the currently rendered values to this target. */
     transaction?: WindowSurfaceTransaction;
 }>;
-/** Live changes emitted by one Window Surface capability. */
-export type WindowSurfaceEvents = {
-    /** The authoritative target changed, including immediate removal as null. */
-    change: WindowSurfaceSettings | null;
-};
 /** Optional host-rendered material owned by one authoritative Window. */
-export interface WindowSurface extends Subscribable<WindowSurfaceEvents, never> {
-    /** Explicitly reads the authoritative target, or null when no Surface exists. */
-    snapshot(): Promise<WindowSurfaceSettings | null>;
+export interface WindowSurface {
     /** Creates or replaces the authoritative target. Omission creates the default Surface. */
     set(settings?: WindowSurfaceSettings): Promise<void>;
     /** Immediately removes the authoritative Surface. */
@@ -64,8 +57,6 @@ export type WindowState = Readonly<{
     layer: WindowLayer;
     /** Current page beneath the declared Client location. */
     location: string;
-    /** Current authoritative host Surface target, or null when absent. */
-    surface: WindowSurfaceSettings | null;
 }>;
 /** Presentation capability owned by one Client handle. */
 export interface Window extends Subscribable<WindowEvents, never> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Environment-neutral contracts and domain objects for PhreshOS Programs.",
   "type": "module",
   "sideEffects": false,