@phreshos/core 0.1.4 → 0.1.6

package/README.md

@@ -234,23 +234,26 @@ 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
-from the rendered values to each new target.
+## Local representation
+
+`Window` is the authoritative, subscribable presentation state shared through
+the system. `LocalWindow` is the current desktop's physical representation of
+the current Client only. Its reads and commands are deliberately eventless and
+never change or publish authoritative state. A desktop projects authoritative
+changes onto an ordinary `window` layer; `under` and `over` representations
+receive their initial truth and control their local projection thereafter.
+
+`SurfaceSettings` describes optional host-rendered material belonging to one
+live `under` or `over` representation. Calling `set()` without settings creates
+a sharp, fully opaque Surface; `remove()` removes its render node immediately.
+Opacity accepts zero through one, while radius accepts a nonnegative pixel
+number, a scale level, or `"full"`.
+
+Geometry commands and Surface replacement may receive a generic `Transaction`.
+It must contain a duration in milliseconds, an easing, or both; `{}` and
+`{ wait: true }` are not transactions. Omitting it preserves the layer's normal
+behavior. `wait: true` makes the command settle with the visual transition,
+while omission or `false` settles when the desktop accepts it.
 
 ## Window geometry
 
@@ -261,6 +264,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/local-window.d.ts

@@ -0,0 +1,39 @@
+import type { Position, Size } from "./launch.js";
+import type { ScaleLevel } from "./scale.js";
+import type { Transaction } from "./transaction.js";
+import type { WindowGeometry, WindowLayer } from "./window.js";
+/** A host Surface belonging only to one live Client representation. */
+export type SurfaceSettings = Readonly<{
+    /** Whole-Surface opacity from zero through one. Omission means one. */
+    opacity?: number;
+    /** A Theme level, CSS pixels, or maximum proportional rounding. */
+    radius?: ScaleLevel | number | "full";
+}>;
+/** Local Surface commands for the current Client representation. */
+export interface LocalWindowSurface {
+    /** Creates or replaces the Surface, optionally as a visual transaction. */
+    set(settings?: SurfaceSettings, transaction?: Transaction): Promise<void>;
+    /** Removes the Surface immediately. */
+    remove(): Promise<void>;
+}
+/**
+ * The current desktop's physical representation of the current Client Window.
+ * It has no events: its commands neither change authoritative state nor
+ * broadcast anything.
+ */
+export interface LocalWindow {
+    readonly surface: LocalWindowSurface;
+    title(): Promise<string>;
+    position(): Promise<Position>;
+    size(): Promise<Size>;
+    minimized(): Promise<boolean>;
+    front(): Promise<boolean>;
+    layer(): Promise<WindowLayer>;
+    location(): Promise<string>;
+    move(position: Position, transaction?: Transaction): Promise<void>;
+    resize(size: Size, transaction?: Transaction): Promise<void>;
+    setGeometry(geometry: WindowGeometry, transaction?: Transaction): Promise<void>;
+    minimize(minimized?: boolean): Promise<void>;
+    changeTitle(title: string): Promise<void>;
+    raise(): Promise<void>;
+}

package/dist/main.d.ts

@@ -19,6 +19,8 @@ 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 LocalWindow, type LocalWindowSurface, type SurfaceSettings } from "./local-window.js";
+export { type Easing, type Transaction } from "./transaction.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,7 @@ export { Client } from "./client.js";
 export { Process } from "./process.js";
 export { Program } from "./program.js";
 export {} from "./window.js";
+export {} from "./local-window.js";
+export {} from "./transaction.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/transaction.d.ts

@@ -0,0 +1,18 @@
+/** Stable timing curves accepted by local visual transactions. */
+export type Easing = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | readonly [number, number, number, number];
+type TransactionOptions = Readonly<{
+    /** Wait for the visual transition to finish instead of only accepting it. */
+    wait?: boolean;
+}>;
+/**
+ * An explicit visual transaction. At least one motion value is required, so
+ * an empty object cannot silently replace a layer's default behavior.
+ */
+export type Transaction = TransactionOptions & (Readonly<{
+    duration: number;
+    easing?: Easing;
+}> | Readonly<{
+    duration?: number;
+    easing: Easing;
+}>);
+export {};

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.6",
   "description": "Environment-neutral contracts and domain objects for PhreshOS Programs.",
   "type": "module",
   "sideEffects": false,