@phreshos/core 0.1.7 → 0.1.9

package/README.md

@@ -60,22 +60,25 @@ the ordinary `Subscribable` capability with a `change` event; it has no
 dedicated subscription shape of its own.
 
 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
+contractual customization bounds for spacing, corner radius, 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`.
+accent remain independent CSS color sources. Surface derives its color from
+background and adds grain intensity, animation rate, optional backdrop blur,
+and material opacity; its standard backdrop is zero, so blur is opt-in.
 
 `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.
+`standardTheme` rather than duplicating them. Its standard background is
+`#fffff5`; both grain intensity and grain amount default to zero. Surface also
+stores animation, material opacity, optional backdrop blur and three
+displacement stages, plus neutral saturation and brightness. Effects whose
+neutral value avoids rendering work remain neutral by default.
 
 Derived variants are calculations, not persisted `Theme` state. `numericScale()`
 produces `xsmall`, `small`, `medium`, `large`, and `xlarge`, preserving the

package/dist/main.d.ts

@@ -2,15 +2,15 @@ export { type Message, type Cleanup, type Capture, type Captures, type EventMess
 export { type Publishable } from "./publishable.js";
 export { type Timeoutable } from "./timeout.js";
 export { type Askable, type TimedAskable } from "./askable.js";
-export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, isServiceKey, type ClientServiceChannel, type ServerServiceChannel, type ServerServiceDefinition, type ServiceChannel, type ServiceDefinition, type ServiceKey, type ServiceLifecycleEvents } from "./service.js";
-export { isPermissionName, permissionNames, type PermissionDecision, type PermissionDecisions, type PermissionName, type Permissions, type ProgramPermissions, type TimedPermissions } from "./permissions.js";
+export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, isServiceKey, type ClientServiceChannel, type ServerServiceChannel, type ServerServiceDefinition, type ServiceChannel, type ServiceDefinition, type ServiceKey, type ServiceLifecycleEvents, type ServiceRegistryEvents } from "./service.js";
+export { isPermissionName, permissionNames, type PermissionDecision, type PermissionDecisions, type PermissionName, type Permission, type ProgramPermission, type TimedPermission } from "./permissions.js";
 export { type Outcome } from "./outcome.js";
 export { type ServedFile } from "./served-file.js";
 export { type DesktopWallpaper, type FileWallpaper, type WallpaperLaunch } from "./wallpaper.js";
 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 ThemeSurface, type Variantable, type WritableTheme } from "./theme.js";
+export { createThemeSnapshot, standardTheme, themeLimits, type Colorable, type Elevatable, type Shapeable, type Sizable, type Theme, type ThemeEvents, 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";
@@ -18,7 +18,7 @@ export { type Channel, type ChannelCapture, type ChannelEvents, type ChannelMess
 export { Server, type AnswerCapture, type AnswerMessage, type AnswerObserver, type ServerTraffic } from "./server.js";
 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 { Program, type ClientDeclaration, type EndpointDeclaration, type ProgramEvents, type ProgramIconSize, type ProgramProcess, type ProgramProcessEvents, type ProgramProcessExit } from "./program.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";

package/dist/permissions.d.ts

@@ -10,19 +10,19 @@ export declare function isPermissionName(value: unknown): value is PermissionNam
 /** The effective decision for one permission, or `null` when none is known. */
 export type PermissionDecision = boolean | null;
 /** Permission requests using one caller-selected deadline. */
-export interface TimedPermissions {
+export interface TimedPermission {
     /** Requests one permission, resolving `null` if the deadline expires. */
     request(name: PermissionName): Promise<PermissionDecision>;
 }
 /** Client access to one Program's effective permission decisions. */
-export interface Permissions extends Timeoutable<TimedPermissions> {
+export interface Permission extends Timeoutable<TimedPermission> {
     /** Reads the effective decision without prompting the user. */
     granted(name: PermissionName): Promise<PermissionDecision>;
     /** Requests a decision from the user. The default deadline is 30 seconds. */
     request(name: PermissionName): Promise<PermissionDecision>;
 }
 /** Server-side management of one Program's persistent permission decisions. */
-export interface ProgramPermissions {
+export interface ProgramPermission {
     /** Reads one persistent decision, or `undefined` when none is stored. */
     get(name: PermissionName): Promise<boolean | undefined>;
     /** Returns an independent snapshot of every persistent decision. */

package/dist/process.d.ts

@@ -38,7 +38,7 @@ export interface Process<Events extends object = {}> extends Subscribable<Proces
     /** Returns the Program that owns this Process. */
     program(): Program;
     /**
-     * Returns the Process whose `createProcess()` call created this Process.
+     * Returns the Process whose `program.process.create()` call created this Process.
      *
      * Returns `null` when this Process has no accessible parent handle. Rejects
      * when this Process or its retained parent no longer exists. Client

package/dist/program.d.ts

@@ -28,16 +28,34 @@ export type ProgramProcessExit = Exit & Readonly<{
     /** Process that ended. */
     process: Process;
 }>;
-/** Lifecycle events scoped to one Program. */
-export type ProgramEvents = {
+/** Process lifecycle events scoped to one Program. */
+export type ProgramProcessEvents = {
     /** One Process Endpoint entered a new live incarnation. */
     endpointStart: Process["server"] | Process["client"];
     /** One Process Endpoint incarnation ended. */
     endpointStop: Process["server"] | Process["client"];
     /** A Process entered this Program's runtime set. */
-    processCreate: Process;
+    create: Process;
     /** A Process left this Program's runtime set. */
-    processExit: ProgramProcessExit;
+    exit: ProgramProcessExit;
+};
+/** Operations over the Processes belonging to one Program. */
+export interface ProgramProcess extends Subscribable<ProgramProcessEvents, never> {
+    /** Returns every live Process of this Program available to this SDK. */
+    list(): Promise<Process[]>;
+    /** Returns the earliest-started live Process, or `null` when none exist. */
+    first(): Promise<Process | null>;
+    /** Returns the latest-started live Process, or `null` when none exist. */
+    last(): Promise<Process | null>;
+    /** Finds a live Process by identity or Program-local name. */
+    find(identityOrName: string): Promise<Process | null>;
+    /** Creates one Process of this Program. */
+    create(launch?: Launch): Promise<Process>;
+    /** Ends every live Process and returns their identities. */
+    exitAll(): Promise<string[]>;
+}
+/** Lifecycle events belonging to one Program entity. */
+export type ProgramEvents = {
     /** This Program left the runtime registry. */
     forget: undefined;
     /** This Program left the installed state. */
@@ -73,16 +91,8 @@ export interface Program<Events extends object = {}> extends Subscribable<Progra
     readonly logs: ProgramSql;
     /** Writable SQLite database owned by this Program. */
     readonly database: ProgramSql;
-    /** Returns every live Process of this Program available to this SDK. */
-    processes(): Promise<Process[]>;
-    /** Returns the earliest-started live Process, or `null` when none exist. */
-    firstProcess(): Promise<Process | null>;
-    /** Returns the latest-started live Process, or `null` when none exist. */
-    lastProcess(): Promise<Process | null>;
-    /** Finds a live Process by identity or Program-local name. */
-    getProcess(identityOrName: string): Promise<Process | null>;
-    /** Creates one Process of this Program. */
-    createProcess(launch?: Launch): Promise<Process>;
+    /** Operations and lifecycle observation for this Program's Processes. */
+    readonly process: ProgramProcess;
     /**
      * Returns one standard PNG representation of this Program's icon.
      * Programs without an authored icon receive the system default.
@@ -96,6 +106,4 @@ export interface Program<Events extends object = {}> extends Subscribable<Progra
     uninstall(everything?: boolean): Promise<void>;
     /** Ends all Processes and removes this Program from the runtime registry. */
     forget(): Promise<void>;
-    /** Ends every live Process and returns their identities. */
-    exitAll(): Promise<string[]>;
 }

package/dist/service.d.ts

@@ -26,6 +26,13 @@ export type ServiceLifecycleEvents = {
     /** The providing Endpoint stopped exposing this service. */
     disable: undefined;
 };
+/** Lifecycle transitions across the authoritative service registry. */
+export type ServiceRegistryEvents = {
+    /** A service entered the enabled registry. */
+    enable: ServiceKey;
+    /** A service left the enabled registry. */
+    disable: ServiceKey;
+};
 /** Application events emitted by one service. */
 export interface ServiceChannel<Events extends object = {}> extends Subscribable<Events, keyof Events extends never ? unknown : never> {
 }
@@ -40,23 +47,20 @@ export declare class ServiceHandler<Channel extends object = ServiceChannel> {
     protected constructor();
 }
 export interface ServiceHandler<Channel extends object = ServiceChannel> extends Subscribable<ServiceLifecycleEvents, never> {
-    /** Program namespace of this service. */
-    readonly program: string;
-    /** Endpoint kind represented by this service. */
-    readonly endpoint: "server" | "client";
     /** Program-authored service identity. */
     readonly name: string;
     /** Application communication, separate from service lifecycle. */
     readonly channel: Channel;
-    /** Explicitly reads whether no live Endpoint currently provides the service. */
-    disabled(): Promise<boolean>;
+    /** Reads whether a live Endpoint currently provides this service. */
+    enabled(): Promise<boolean>;
+    /** Waits until a live Endpoint provides this service. */
+    waitReady(timeout?: number): Promise<void>;
 }
 /** Stable handle for one Server-provided service. */
 export declare class ServerServiceHandler<Events extends object = {}> extends ServiceHandler<ServerServiceChannel<Events>> {
     protected constructor();
 }
 export interface ServerServiceHandler<Events extends object = {}> {
-    readonly endpoint: "server";
     readonly channel: ServerServiceChannel<Events>;
     /** Explicitly reads this live Server service's documentation, or `null`. */
     docs(): Promise<string | null>;
@@ -66,7 +70,6 @@ export declare class ClientServiceHandler<Events extends object = {}> extends Se
     protected constructor();
 }
 export interface ClientServiceHandler<Events extends object = {}> {
-    readonly endpoint: "client";
     readonly channel: ClientServiceChannel<Events>;
 }
 /** Returns whether a boundary value is a complete service key. */

package/dist/theme.d.ts

@@ -6,29 +6,28 @@ export type ThemeRange = Readonly<{
     /** Largest accepted value. */
     maximum: number;
 }>;
-/** Bounded controls for the shared glass material. */
-export type ThemeGlass = Readonly<{
-    /** Default strength of the refracted backdrop. */
-    distortion: number;
-    /** Default backdrop blur in CSS pixels. */
-    blur: number;
-    /** Default backdrop saturation multiplier. */
-    saturation: number;
-    /** Default backdrop brightness multiplier. */
-    brightness: number;
-    /** 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;
+    /** Fraction of deterministic grain cells retained from zero to one. */
+    grainAmount: number;
     /** Grain texture changes per second. */
     animation: number;
     /** Optional backdrop blur in CSS pixels. */
     backdrop: number;
     /** Material opacity from zero to one. */
     opacity: number;
+    /** Organic backdrop displacement in CSS pixels. */
+    distortion: number;
+    /** Directional-wave backdrop displacement in CSS pixels. */
+    waves: number;
+    /** Ripple backdrop displacement in CSS pixels. */
+    ripples: number;
+    /** Backdrop saturation multiplier, neutral at one. */
+    saturation: number;
+    /** Backdrop brightness multiplier, neutral at one. */
+    brightness: number;
 }>;
 /** The complete set of system-defined Theme properties. */
 export type ThemeProperties = Readonly<{
@@ -42,8 +41,6 @@ export type ThemeProperties = Readonly<{
     spacing: number;
     /** Default component corner radius expressed in CSS pixels. */
     radius: number;
-    /** Default values for the shared glass material. */
-    glass: ThemeGlass;
     /** Default values for the shared opaque Surface material. */
     surface: ThemeSurface;
 }>;
@@ -57,33 +54,15 @@ export declare const themeLimits: Readonly<{
         minimum: 6;
         maximum: 18;
     }>;
-    glass: Readonly<{
-        distortion: Readonly<{
-            minimum: 48;
-            maximum: 92;
-        }>;
-        blur: Readonly<{
-            minimum: 2;
-            maximum: 8;
-        }>;
-        saturation: Readonly<{
-            minimum: 1.25;
-            maximum: 1.8;
-        }>;
-        brightness: Readonly<{
-            minimum: 1.02;
-            maximum: 1.1;
-        }>;
-        opacity: Readonly<{
-            minimum: 0;
-            maximum: 0.3;
-        }>;
-    }>;
     surface: Readonly<{
         grain: Readonly<{
             minimum: 0;
             maximum: 1;
         }>;
+        grainAmount: Readonly<{
+            minimum: 0;
+            maximum: 1;
+        }>;
         animation: Readonly<{
             minimum: 0;
             maximum: 16;
@@ -96,6 +75,26 @@ export declare const themeLimits: Readonly<{
             minimum: 0;
             maximum: 1;
         }>;
+        distortion: Readonly<{
+            minimum: 0;
+            maximum: 140;
+        }>;
+        waves: Readonly<{
+            minimum: 0;
+            maximum: 40;
+        }>;
+        ripples: Readonly<{
+            minimum: 0;
+            maximum: 40;
+        }>;
+        saturation: Readonly<{
+            minimum: 1;
+            maximum: 2.6;
+        }>;
+        brightness: Readonly<{
+            minimum: 1;
+            maximum: 1.12;
+        }>;
     }>;
 }>;
 /** Complete standard Theme available to every environment. */
@@ -110,8 +109,6 @@ export declare const standardTheme: Readonly<{
     spacing: number;
     /** Default component corner radius expressed in CSS pixels. */
     radius: number;
-    /** Default values for the shared glass material. */
-    glass: ThemeGlass;
     /** Default values for the shared opaque Surface material. */
     surface: ThemeSurface;
 }>;

package/dist/theme.js

@@ -2,46 +2,43 @@
 export const themeLimits = Object.freeze({
     spacing: Object.freeze({ minimum: 6, maximum: 18 }),
     radius: Object.freeze({ minimum: 6, maximum: 18 }),
-    glass: Object.freeze({
-        distortion: Object.freeze({ minimum: 48, maximum: 92 }),
-        blur: Object.freeze({ minimum: 2, maximum: 8 }),
-        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 }),
+        grainAmount: 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 })
+        opacity: Object.freeze({ minimum: 0, maximum: 1 }),
+        distortion: Object.freeze({ minimum: 0, maximum: 140 }),
+        waves: Object.freeze({ minimum: 0, maximum: 40 }),
+        ripples: Object.freeze({ minimum: 0, maximum: 40 }),
+        saturation: Object.freeze({ minimum: 1, maximum: 2.6 }),
+        brightness: Object.freeze({ minimum: 1, maximum: 1.12 })
     })
 });
 /** Complete standard Theme available to every environment. */
 export const standardTheme = createThemeSnapshot({
-    background: "#f5f4ee",
+    background: "#fffff5",
     foreground: "#183447",
     accent: "#4c9cff",
     spacing: 12,
     radius: 10,
-    glass: {
-        distortion: 70,
-        blur: 4,
-        saturation: 1.8,
-        brightness: 1.06,
-        opacity: 0.12
-    },
     surface: {
-        grain: 0.04,
+        grain: 0,
+        grainAmount: 0,
         animation: 0,
         backdrop: 0,
-        opacity: 1
+        opacity: 1,
+        distortion: 0,
+        waves: 0,
+        ripples: 0,
+        saturation: 1,
+        brightness: 1
     }
 });
 /** Creates a complete immutable Theme snapshot at the contract boundary. */
 export function createThemeSnapshot(theme) {
     return Object.freeze({
         ...theme,
-        glass: Object.freeze({ ...theme.glass }),
         surface: Object.freeze({ ...theme.surface })
     });
 }

package/package.json

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