@phreshos/core 0.1.5 → 0.1.7

package/README.md

@@ -59,23 +59,23 @@ explicit, asynchronous read of one complete, immutable value. `Theme` extends
 the ordinary `Subscribable` capability with a `change` event; it has no
 dedicated subscription shape of its own.
 
-Theme properties are expressed as concrete default values. `themeLimits`
-declares the system-owned customization bounds for spacing, corner radius, and
-glass-material properties; implementing authorities validate replacements
-against those bounds. Core defines one fixed numeric scale around any explicit
-number and one fixed color scale around any explicit CSS color — it does not
-prescribe which value an interface ultimately chooses to derive. Background,
-foreground, and accent are independent CSS color sources, with standard values
-of `#edf8fc`, `#183447`, and `#4c9cff` — the established pale surface, primary
-ink, and original system blue, respectively. Core stores only those source
-colors, never their derived treatments. The declared glass-opacity range ends
-at `0.3`.
-
-`standardTheme` is the single, complete initial value shared by every
-environment; the running system remains the authority for its current value.
-`createThemeSnapshot()` copies and freezes a complete replacement at the
-contract boundary; validation remains the implementing authority's
-responsibility.
+Theme properties are expressed as concrete values. `themeLimits` declares the
+contractual customization bounds for spacing, corner radius, glass-material,
+and Surface properties; implementing authorities validate replacements against those
+bounds. Core defines one fixed numeric scale around any explicit number and one
+fixed color scale around any explicit CSS color. `standardTheme` is the
+canonical reusable default value for that contract, shared by systems,
+interfaces, websites, and Programs that need the same baseline. It is not an
+authoritative environment's mutable Theme state. Background, foreground, and
+accent remain independent CSS color sources. Surface adds a concrete color,
+grain intensity, animation rate, optional backdrop blur, and material opacity;
+its standard backdrop is zero, so blur is opt-in. The declared glass-opacity
+range ends at `0.3`.
+
+`createThemeSnapshot()` copies and freezes one complete value at the contract
+boundary. An implementing authority remains responsible for validation,
+persistence, and the current value; its own schema may derive its defaults from
+`standardTheme` rather than duplicating them.
 
 Derived variants are calculations, not persisted `Theme` state. `numericScale()`
 produces `xsmall`, `small`, `medium`, `large`, and `xlarge`, preserving the
@@ -86,9 +86,9 @@ supplied value exactly at `medium`. `color()` produces `subtle`, `soft`, `base`,
 after that registration exists. It never supplies an initial snapshot and
 never replays a change published earlier; Programs request the current
 snapshot explicitly when they need one. `WritableTheme` adds asynchronous
-authority to replace the value — a read-only environment exposes `Theme`,
-while an authorized environment may expose `WritableTheme` without altering
-the shared lifecycle.
+authority to replace the value. A read-only environment exposes `Theme`, while
+an authorized environment may expose `WritableTheme` without altering the
+shared lifecycle.
 
 `Colorable`, `Sizable`, `Shapeable`, `Variantable`, and `Elevatable` are
 independent element capabilities whose concrete value vocabularies are defined
@@ -234,18 +234,28 @@ 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` describes one Client Window's physical representation
+on the current desktop. Its reads and commands are deliberately eventless and
+never change or publish authoritative state. Client SDKs may attach this
+capability to their Window handles; Server SDKs must not. A desktop projects
+authoritative changes onto an ordinary `window` layer, while `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 one Client Window 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>;
+}
+/**
+ * One Client Window's physical representation on the current desktop. 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

@@ -10,7 +10,7 @@ export { type DesktopWallpaper, type FileWallpaper, type WallpaperLaunch } from
 export { isRelativeValue, parseRelativeValue, type RelativeValue, type Value } from "./value.js";
 export { color, type ColorLevel, type ColorScale } from "./color.js";
 export { isScaleLevel, numericScale, scale, scaleMultiplier, type NumericScale, type ScaleLevel } from "./scale.js";
-export { createThemeSnapshot, standardTheme, themeLimits, type Colorable, type Elevatable, type Shapeable, type Sizable, type Theme, type ThemeEvents, type ThemeGlass, type ThemeProperties, type ThemeRange, type Variantable, type WritableTheme } from "./theme.js";
+export { createThemeSnapshot, standardTheme, themeLimits, type Colorable, type Elevatable, type Shapeable, type Sizable, type Theme, type ThemeEvents, type ThemeGlass, type ThemeProperties, type ThemeRange, type ThemeSurface, type Variantable, type WritableTheme } from "./theme.js";
 export { type DirectoryStat, type EntryStat, type FileStat, type OtherStat, type ProgramArea, type ProgramStore } from "./storage.js";
 export { type LogKind, type LogRecord, type LogSource, type ProgramSql } from "./sql.js";
 export { Endpoint, type AskCapture, type AskMessage, type AskObserver, type EndpointTraffic, type TrafficCapture, type TrafficEvents, type TrafficMessage } from "./endpoint.js";
@@ -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/theme.d.ts

@@ -19,9 +19,20 @@ export type ThemeGlass = Readonly<{
     /** Default material opacity from zero to the system's glass cap. */
     opacity: number;
 }>;
+/** Concrete defaults for the shared opaque Surface material. */
+export type ThemeSurface = Readonly<{
+    /** Grain intensity from zero to one. */
+    grain: number;
+    /** Grain texture changes per second. */
+    animation: number;
+    /** Optional backdrop blur in CSS pixels. */
+    backdrop: number;
+    /** Material opacity from zero to one. */
+    opacity: number;
+}>;
 /** The complete set of system-defined Theme properties. */
 export type ThemeProperties = Readonly<{
-    /** CSS color underlying shared interface surfaces and materials. */
+    /** CSS color underlying interfaces and painted by Surface materials. */
     background: string;
     /** CSS color used for shared interface content. */
     foreground: string;
@@ -33,6 +44,8 @@ export type ThemeProperties = Readonly<{
     radius: number;
     /** Default values for the shared glass material. */
     glass: ThemeGlass;
+    /** Default values for the shared opaque Surface material. */
+    surface: ThemeSurface;
 }>;
 /** System-owned bounds for Theme customization. */
 export declare const themeLimits: Readonly<{
@@ -66,10 +79,28 @@ export declare const themeLimits: Readonly<{
             maximum: 0.3;
         }>;
     }>;
+    surface: Readonly<{
+        grain: Readonly<{
+            minimum: 0;
+            maximum: 1;
+        }>;
+        animation: Readonly<{
+            minimum: 0;
+            maximum: 16;
+        }>;
+        backdrop: Readonly<{
+            minimum: 0;
+            maximum: 24;
+        }>;
+        opacity: Readonly<{
+            minimum: 0;
+            maximum: 1;
+        }>;
+    }>;
 }>;
 /** Complete standard Theme available to every environment. */
 export declare const standardTheme: Readonly<{
-    /** CSS color underlying shared interface surfaces and materials. */
+    /** CSS color underlying interfaces and painted by Surface materials. */
     background: string;
     /** CSS color used for shared interface content. */
     foreground: string;
@@ -81,6 +112,8 @@ export declare const standardTheme: Readonly<{
     radius: number;
     /** Default values for the shared glass material. */
     glass: ThemeGlass;
+    /** Default values for the shared opaque Surface material. */
+    surface: ThemeSurface;
 }>;
 /** Creates a complete immutable Theme snapshot at the contract boundary. */
 export declare function createThemeSnapshot(theme: ThemeProperties): ThemeProperties;

package/dist/theme.js

@@ -8,11 +8,17 @@ export const themeLimits = Object.freeze({
         saturation: Object.freeze({ minimum: 1.25, maximum: 1.8 }),
         brightness: Object.freeze({ minimum: 1.02, maximum: 1.1 }),
         opacity: Object.freeze({ minimum: 0, maximum: 0.3 })
+    }),
+    surface: Object.freeze({
+        grain: Object.freeze({ minimum: 0, maximum: 1 }),
+        animation: Object.freeze({ minimum: 0, maximum: 16 }),
+        backdrop: Object.freeze({ minimum: 0, maximum: 24 }),
+        opacity: Object.freeze({ minimum: 0, maximum: 1 })
     })
 });
 /** Complete standard Theme available to every environment. */
 export const standardTheme = createThemeSnapshot({
-    background: "#edf8fc",
+    background: "#f5f4ee",
     foreground: "#183447",
     accent: "#4c9cff",
     spacing: 12,
@@ -23,12 +29,19 @@ export const standardTheme = createThemeSnapshot({
         saturation: 1.8,
         brightness: 1.06,
         opacity: 0.12
+    },
+    surface: {
+        grain: 0.04,
+        animation: 0,
+        backdrop: 0,
+        opacity: 1
     }
 });
 /** Creates a complete immutable Theme snapshot at the contract boundary. */
 export function createThemeSnapshot(theme) {
     return Object.freeze({
         ...theme,
-        glass: Object.freeze({ ...theme.glass })
+        glass: Object.freeze({ ...theme.glass }),
+        surface: Object.freeze({ ...theme.surface })
     });
 }

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.7",
   "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;
-}>;