@phreshos/core 0.1.3 → 0.1.5

package/README.md

@@ -234,22 +234,17 @@ Program and the deliberately narrow `WallpaperLaunch`, containing only `name`,
 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. 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
-`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
+## Client Surface values
+
+`ClientSurfaceSettings` describes optional host-rendered material requested by
+one live Client representation. It is a value contract, not Window state and
+not server authority. Calling the Client capability 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; the Client capability's separate `remove()` command
+removes it immediately. The receiving desktop validates settings and animates
 from the rendered values to each new target.
 
 ## Window geometry
@@ -261,6 +256,15 @@ pixel number or a linear relative expression such as `"1/2"`, `"50% + 10"`, or
 offset. The CLI, runtime validation, and desktop layout all consume this one
 Core definition rather than maintaining separate parsers.
 
+`move()` and `resize()` change one dimension of authoritative geometry.
+`setGeometry({ position, size })` validates and commits both dimensions as one
+operation, then emits one `geometry` event. Compound interactions such as
+resizing from a top or left edge and snapping must use this atomic form so a
+remote representation never observes a new position with the previous size.
+`move` and `resize` subscribers are also notified after the complete geometry
+has committed; those component notifications never represent partial
+authoritative state.
+
 ## Process parentage
 
 Process parentage belongs to `Process`, not to contextual SDK state. Each

package/dist/channel.d.ts

@@ -1,5 +1,6 @@
 import type { Endpoint } from "./endpoint.js";
 import type { Publishable } from "./publishable.js";
+import type { ServiceDefinition } from "./service.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<{
@@ -16,9 +17,9 @@ type ChannelFallback<Events extends object, From> = keyof Events extends never ?
 /** Every application event observable through a Channel. */
 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 {
+export interface Channel<Events extends object = {}, From = Endpoint, Definition extends ServiceDefinition = ServiceDefinition> extends Subscribable<ChannelEvents<Events, From>, ChannelFallback<Events, From>>, Publishable {
     /** Exposes this executing Channel under one public service name. */
-    enableService(name: string): Promise<void>;
+    enableService(definition: Definition): Promise<void>;
     /** Stops exposing this executing Channel as a service. */
     disableService(): Promise<void>;
 }

package/dist/client-surface.d.ts

@@ -0,0 +1,19 @@
+import type { ScaleLevel } from "./scale.js";
+/** Stable easing accepted by one Client representation's Surface transaction. */
+export type ClientSurfaceEasing = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | readonly [number, number, number, number];
+/** Motion applied locally when one Client representation replaces its Surface target. */
+export type ClientSurfaceTransaction = Readonly<{
+    /** Duration in milliseconds. Omission uses the desktop duration. */
+    duration?: number;
+    /** Timing curve. Omission uses the desktop curve. */
+    easing?: ClientSurfaceEasing;
+}>;
+/** Local host Surface requested by one live Client representation. */
+export type ClientSurfaceSettings = Readonly<{
+    /** Whole-Surface opacity from zero through one. Omission means one. */
+    opacity?: number;
+    /** A Theme-derived level, CSS pixels, or maximum proportional rounding. Omission means zero. */
+    radius?: ScaleLevel | number | "full";
+    /** Optional motion from the currently rendered values to this target. */
+    transaction?: ClientSurfaceTransaction;
+}>;

package/dist/config.d.ts

@@ -52,11 +52,6 @@ type Description = Readonly<{
     version?: string;
     /** Short human-readable explanation of what the Program does. */
     description?: string;
-    /**
-     * Markdown file describing only the Program-owned API contract.
-     * System access, Endpoint, and event mechanics belong to system documentation.
-     */
-    apiDocs?: 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. */

package/dist/main.d.ts

@@ -2,7 +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 { ClientServiceHandler, ServerServiceHandler, ServiceHandler, isServiceKey, type ClientServiceChannel, type ServerServiceChannel, type ServerServiceDefinition, type ServiceChannel, type ServiceDefinition, 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";
@@ -19,6 +19,7 @@ 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 WindowSurfaceSettings, type WindowSurfaceTransaction } from "./window.js";
+export { type Window, type WindowEvents, type WindowGeometry, type WindowLayer, type WindowState } from "./window.js";
+export { type ClientSurfaceEasing, type ClientSurfaceSettings, type ClientSurfaceTransaction } from "./client-surface.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

@@ -20,5 +20,6 @@ export { Client } from "./client.js";
 export { Process } from "./process.js";
 export { Program } from "./program.js";
 export {} from "./window.js";
+export {} from "./client-surface.js";
 export { layers } from "./launch.js";
 export { defineConfig } from "./config.js";

package/dist/permissions.d.ts

@@ -14,7 +14,7 @@ export interface TimedPermissions {
     /** Requests one permission, resolving `null` if the deadline expires. */
     request(name: PermissionName): Promise<PermissionDecision>;
 }
-/** Client access to the current Process's permissions. */
+/** Client access to one Program's effective permission decisions. */
 export interface Permissions extends Timeoutable<TimedPermissions> {
     /** Reads the effective decision without prompting the user. */
     granted(name: PermissionName): Promise<PermissionDecision>;

package/dist/program.d.ts

@@ -83,11 +83,6 @@ export interface Program<Events extends object = {}> extends Subscribable<Progra
     getProcess(identityOrName: string): Promise<Process | null>;
     /** Creates one Process of this Program. */
     createProcess(launch?: Launch): Promise<Process>;
-    /**
-     * Returns the Program-authored API entry point, or `null`.
-     * The document describes the Program's contract, not system mechanics.
-     */
-    apiDocs(): Promise<string | null>;
     /**
      * Returns one standard PNG representation of this Program's icon.
      * Programs without an authored icon receive the system default.

package/dist/service.d.ts

@@ -9,6 +9,16 @@ export type ServiceKey = Readonly<{
     /** Program-authored service identity. */
     name: string;
 }>;
+/** Runtime declaration of one service exposed by an Endpoint Channel. */
+export type ServiceDefinition = Readonly<{
+    /** Program-authored service identity. */
+    name: string;
+}>;
+/** Runtime declaration of one Server service and its optional API document. */
+export type ServerServiceDefinition = ServiceDefinition & Readonly<{
+    /** Complete API documentation owned by this service. */
+    docs?: string;
+}>;
 /** Lifecycle transitions of one exact service identity. */
 export type ServiceLifecycleEvents = {
     /** A live Endpoint began providing this service. */
@@ -48,6 +58,8 @@ export declare class ServerServiceHandler<Events extends object = {}> extends Se
 export interface ServerServiceHandler<Events extends object = {}> {
     readonly endpoint: "server";
     readonly channel: ServerServiceChannel<Events>;
+    /** Explicitly reads this live Server service's documentation, or `null`. */
+    docs(): Promise<string | null>;
 }
 /** Stable handle for one Client-provided service. */
 export declare class ClientServiceHandler<Events extends object = {}> extends ServiceHandler<ClientServiceChannel<Events>> {

package/dist/window.d.ts

@@ -1,39 +1,22 @@
 import type { Layer, Position, Size } from "./launch.js";
-import type { ScaleLevel } from "./scale.js";
 import type { Subscribable } from "./subscribable.js";
 /** The authoritative runtime layer occupied by a Window. */
 export type WindowLayer = Layer | "wallpaper";
-/** Stable easing accepted by a Window Surface transaction. */
-export type WindowSurfaceEasing = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | readonly [number, number, number, number];
-/** Motion applied by a desktop when one authoritative Surface target replaces another. */
-export type WindowSurfaceTransaction = Readonly<{
-    /** Duration in milliseconds. Omission uses the system duration. */
-    duration?: number;
-    /** Timing curve. Omission uses the system curve. */
-    easing?: WindowSurfaceEasing;
-}>;
-/** Authoritative target settings for one Window's optional host Surface. */
-export type WindowSurfaceSettings = Readonly<{
-    /** Whole-Surface opacity from zero through one. Omission means one. */
-    opacity?: number;
-    /** A Theme-derived level, CSS pixels, or maximum proportional rounding. Omission means zero. */
-    radius?: ScaleLevel | number | "full";
-    /** Optional motion from the currently rendered values to this target. */
-    transaction?: WindowSurfaceTransaction;
+/** Position and size committed as one authoritative Window change. */
+export type WindowGeometry = Readonly<{
+    /** Complete top-left position. */
+    position: Position;
+    /** Complete width and height. */
+    size: Size;
 }>;
-/** Optional host-rendered material owned by one authoritative Window. */
-export interface WindowSurface {
-    /** Creates or replaces the authoritative target. Omission creates the default Surface. */
-    set(settings?: WindowSurfaceSettings): Promise<void>;
-    /** Immediately removes the authoritative Surface. */
-    remove(): Promise<void>;
-}
 /** Events emitted when authoritative Window state changes. */
 export type WindowEvents = {
     /** The authoritative top-left position changed. */
     move: Position;
     /** The authoritative width or height changed. */
     resize: Size;
+    /** Position and size changed in one atomic operation. */
+    geometry: WindowGeometry;
     /** The authoritative minimized state changed. */
     minimize: boolean;
     /** The authoritative title changed. */
@@ -60,8 +43,6 @@ export type WindowState = Readonly<{
 }>;
 /** Presentation capability owned by one Client handle. */
 export interface Window extends Subscribable<WindowEvents, never> {
-    /** Authoritative host-rendered material associated with this Window. */
-    readonly surface: WindowSurface;
     /** Returns the current title. */
     title(): Promise<string>;
     /** Returns the current top-left position. */
@@ -80,6 +61,8 @@ export interface Window extends Subscribable<WindowEvents, never> {
     move(position: Position): Promise<void>;
     /** Resizes the authoritative Window. */
     resize(size: Size): Promise<void>;
+    /** Changes position and size as one authoritative operation. */
+    setGeometry(geometry: WindowGeometry): Promise<void>;
     /** Changes whether the Window is minimized. */
     minimize(minimized?: boolean): Promise<void>;
     /** Changes the Window title. */

package/package.json

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