@phreshos/core 0.1.8 → 0.1.9

package/README.md

@@ -74,7 +74,11 @@ 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,8 +2,8 @@ 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";
@@ -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

@@ -10,12 +10,24 @@ export type ThemeRange = Readonly<{
 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<{
@@ -47,6 +59,10 @@ export declare const themeLimits: Readonly<{
             minimum: 0;
             maximum: 1;
         }>;
+        grainAmount: Readonly<{
+            minimum: 0;
+            maximum: 1;
+        }>;
         animation: Readonly<{
             minimum: 0;
             maximum: 16;
@@ -59,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. */

package/dist/theme.js

@@ -4,23 +4,35 @@ export const themeLimits = Object.freeze({
     radius: Object.freeze({ minimum: 6, maximum: 18 }),
     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,
     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. */

package/package.json

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