@phreshos/core 0.1.5 → 0.1.6

package/README.md

@@ -234,18 +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.
 
-## 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.
+## 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
 

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

@@ -20,6 +20,7 @@ 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 WindowGeometry, type WindowLayer, type WindowState } from "./window.js";
-export { type ClientSurfaceEasing, type ClientSurfaceSettings, type ClientSurfaceTransaction } from "./client-surface.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,6 +20,7 @@ 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 {} from "./local-window.js";
+export {} from "./transaction.js";
 export { layers } from "./launch.js";
 export { defineConfig } from "./config.js";

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/package.json

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

package/dist/client-surface.d.ts

@@ -1,19 +0,0 @@
-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;
-}>;