@phreshos/core 0.1.4 → 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/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/main.d.ts

@@ -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/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.4",
+  "version": "0.1.5",
   "description": "Environment-neutral contracts and domain objects for PhreshOS Programs.",
   "type": "module",
   "sideEffects": false,