@phreshos/core 0.1.6 → 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
@@ -237,11 +237,13 @@ persistence, upload, Process creation, or rendering implementation.
 ## 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.
+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

package/dist/local-window.d.ts

@@ -9,7 +9,7 @@ export type SurfaceSettings = Readonly<{
     /** A Theme level, CSS pixels, or maximum proportional rounding. */
     radius?: ScaleLevel | number | "full";
 }>;
-/** Local Surface commands for the current Client representation. */
+/** 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>;
@@ -17,9 +17,9 @@ export interface LocalWindowSurface {
     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.
+ * 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;

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";

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

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