@phreshos/core 0.1.0 → 0.1.2

package/dist/main.d.ts

@@ -1,8 +1,15 @@
-export { type Message, type Cleanup, type Capture, type Captures, type EventMessage, type EventName, type EventObserver, type EventOptions, type EventSubscriber, type Subscribable } from "./subscribable.js";
+export { type Message, type Cleanup, type Capture, type Captures, type EventMessage, type EventName, type EventObserver, type EventOptions, type EventSubscriber, type Subscribable, type SubscribableEvents, type SubscribableFallback } from "./subscribable.js";
 export { type Publishable } from "./publishable.js";
+export { type Timeoutable } from "./timeout.js";
 export { type Askable, type TimedAskable } from "./askable.js";
+export { isPermissionName, permissionNames, type PermissionDecision, type PermissionDecisions, type PermissionName, type Permissions, type ProgramPermissions, type TimedPermissions } 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 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";
@@ -10,7 +17,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 ProgramProcessExit, type ProgramServerStop } from "./program.js";
-export { Window, type WindowEvents, type WindowState } from "./window.js";
-export { layers, type Launch, type LaunchClient, type Layer, type Position, type Size, type Value } from "./launch.js";
+export { Program, type ClientDeclaration, type EndpointDeclaration, type ProgramEvents, type ProgramIconSize, type ProgramProcessExit } from "./program.js";
+export { type Window, type WindowEvents, type WindowLayer, type WindowState, type WindowSurface, type WindowSurfaceEasing, type WindowSurfaceSettings, type WindowSurfaceTransaction } from "./window.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

@@ -1,8 +1,15 @@
 export {} from "./subscribable.js";
 export {} from "./publishable.js";
+export {} from "./timeout.js";
 export {} from "./askable.js";
+export { isPermissionName, permissionNames } from "./permissions.js";
 export {} from "./outcome.js";
 export {} from "./served-file.js";
+export {} from "./wallpaper.js";
+export { isRelativeValue, parseRelativeValue } from "./value.js";
+export { color } from "./color.js";
+export { isScaleLevel, numericScale, scale, scaleMultiplier } from "./scale.js";
+export { createThemeSnapshot, standardTheme, themeLimits } from "./theme.js";
 export {} from "./storage.js";
 export {} from "./sql.js";
 export { Endpoint } from "./endpoint.js";
@@ -11,6 +18,6 @@ export { Server } from "./server.js";
 export { Client } from "./client.js";
 export { Process } from "./process.js";
 export { Program } from "./program.js";
-export { Window } from "./window.js";
+export {} from "./window.js";
 export { layers } from "./launch.js";
 export { defineConfig } from "./config.js";

package/dist/outcome.d.ts

@@ -1,8 +1,12 @@
 /** The transport-neutral result of an operation that may fail. */
 export type Outcome<Result = unknown> = Readonly<{
+    /** Indicates that the operation completed successfully. */
     success: true;
+    /** Value returned by the successful operation. */
     result: Result;
 }> | Readonly<{
+    /** Indicates that the operation failed. */
     success: false;
+    /** Transport-safe description of the failure. */
     error: string;
 }>;

package/dist/permissions.d.ts

@@ -0,0 +1,34 @@
+import type { Timeoutable } from "./timeout.js";
+/** Every permission recognized by this system release. */
+export declare const permissionNames: readonly ["pointer"];
+/** The finite system-wide name of one permission. */
+export type PermissionName = typeof permissionNames[number];
+/** Persistent decisions may exist for any subset of system permissions. */
+export type PermissionDecisions = Partial<Record<PermissionName, boolean>>;
+/** Validates an unknown value against the authoritative permission registry. */
+export declare function isPermissionName(value: unknown): value is PermissionName;
+/** 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 {
+    /** Requests one permission, resolving `null` if the deadline expires. */
+    request(name: PermissionName): Promise<PermissionDecision>;
+}
+/** Client access to the current Process's permissions. */
+export interface Permissions extends Timeoutable<TimedPermissions> {
+    /** 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 {
+    /** Reads one persistent decision, or `undefined` when none is stored. */
+    get(name: PermissionName): Promise<boolean | undefined>;
+    /** Returns an independent snapshot of every persistent decision. */
+    getAll(): Promise<PermissionDecisions>;
+    /** Stores one persistent decision. */
+    set(name: PermissionName, value: boolean): Promise<void>;
+    /** Removes one persistent decision. */
+    delete(name: PermissionName): Promise<void>;
+}

package/dist/permissions.js

@@ -0,0 +1,6 @@
+/** Every permission recognized by this system release. */
+export const permissionNames = ["pointer"];
+/** Validates an unknown value against the authoritative permission registry. */
+export function isPermissionName(value) {
+    return permissionNames.some(name => name === value);
+}

package/dist/process.d.ts

@@ -13,20 +13,16 @@ export type Exit = Readonly<{
 }>;
 /** Lifecycle events emitted by one Process. */
 export type ProcessEvents = {
-    /** The Server entered a new live incarnation. */
-    serverStart: undefined;
-    /** The Server incarnation ended. */
-    serverStop: Omit<Exit, "status">;
-    /** The authoritative Client state was created. */
-    clientStart: undefined;
-    /** The authoritative Client state ended. */
-    clientStop: undefined;
+    /** One declared Endpoint entered a new live incarnation. */
+    endpointStart: Server | Client;
+    /** One live Endpoint incarnation ended. */
+    endpointStop: Server | Client;
     /** The complete Process ended. */
     exit: Exit;
 };
 /** One live execution of a Program. */
 export declare class Process<Events extends object = {}> {
-    constructor();
+    protected constructor();
 }
 export interface Process<Events extends object = {}> extends Subscribable<ProcessEvents & Events, never> {
     /** Immutable runtime identity. */

package/dist/program.d.ts

@@ -3,6 +3,8 @@ import type { Exit, Process } from "./process.js";
 import type { ProgramSql } from "./sql.js";
 import type { ProgramArea, ProgramStore } from "./storage.js";
 import type { Subscribable } from "./subscribable.js";
+/** Standard rendered sizes available for every Program icon. */
+export type ProgramIconSize = "small" | "medium" | "large";
 /** Resolved declaration shared by Server and Client endpoint kinds. */
 export type EndpointDeclaration = Readonly<{
     /** Whether a default Process starts this declared Endpoint. */
@@ -21,24 +23,17 @@ export type ClientDeclaration = EndpointDeclaration & Readonly<{
     /** Default minimized state, or `null` for the system default. */
     minimize: boolean | null;
 }>;
+/** A Process exit scoped to its owning Program. */
 export type ProgramProcessExit = Exit & Readonly<{
     /** Process that ended. */
     process: Process;
 }>;
-export type ProgramServerStop = Omit<Exit, "status"> & Readonly<{
-    /** Process whose Server incarnation ended. */
-    process: Process;
-}>;
 /** Lifecycle events scoped to one Program. */
 export type ProgramEvents = {
-    /** One Process's Server entered a new live incarnation. */
-    serverStart: Process;
-    /** One Process's Server incarnation ended. */
-    serverStop: ProgramServerStop;
-    /** One Process's Client state was created. */
-    clientStart: Process;
-    /** One Process's Client state ended. */
-    clientStop: Process;
+    /** 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;
     /** A Process left this Program's runtime set. */
@@ -47,12 +42,13 @@ export type ProgramEvents = {
     forget: undefined;
     /** This Program left the installed state. */
     uninstall: Readonly<{
+        /** Whether every installed resource, including storage, was removed. */
         everythingRemoved: boolean;
     }>;
 };
 /** The stable domain root from which Processes are created. */
 export declare class Program<Events extends object = {}> {
-    constructor();
+    protected constructor();
 }
 export interface Program<Events extends object = {}> extends Subscribable<ProgramEvents & Events, never> {
     /** Stable public identity. */
@@ -79,12 +75,26 @@ export interface Program<Events extends object = {}> extends Subscribable<Progra
     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>;
-    /** Returns the official Markdown API entry point, or `null`. */
+    /**
+     * Returns the Program-authored API entry point, or `null`.
+     * The document describes the Program's contract, not system mechanics.
+     */
     apiDocs(): Promise<string | null>;
+    /**
+     * Returns one standard PNG representation of this Program's icon.
+     * Programs without an authored icon receive the system default.
+     *
+     * @param size Rendered size. Omission selects `medium`.
+     */
+    icon(size?: ProgramIconSize): Promise<Blob>;
     /** Returns whether this Program currently has an installed form. */
     installed(): Promise<boolean>;
     /** Removes this Program's installed form. */

package/dist/publishable.d.ts

@@ -5,7 +5,11 @@ type CompatibleEvent<Events extends object, Fallback, Payload> = {
     [Event in EventName<Events>]: Payload extends Events[Event] ? Event : never;
 }[EventName<Events>] | ([Fallback] extends [never] ? never : Payload extends Fallback ? OpenEvent : never);
 interface Publish<Events extends object, Fallback> {
+    /** Publishes `undefined` to one named event on this target. */
+    <Event extends CompatibleEvent<Events, Fallback, undefined>>(event: Event): void;
+    /** Publishes one payload to one named event on this target. */
     <Payload, Event extends CompatibleEvent<Events, Fallback, Payload> = CompatibleEvent<Events, Fallback, Payload>>(event: Event, payload: Payload): void;
+    /** Publishes one payload to one named event on this target. */
     <Event extends AvailableEvent<Events, Fallback>>(event: Event, payload: EventMessage<Events, Fallback, Event>): void;
 }
 /**
@@ -15,7 +19,7 @@ interface Publish<Events extends object, Fallback> {
  * silently drops the publication; no delivery result is produced.
  */
 export interface Publishable<Events extends object = {}, Fallback = unknown> {
-    /** Publishes one payload to one named event on this target. */
+    /** Publishes one payload, or `undefined` when omitted, to one named event. */
     publish: Publish<Events, Fallback>;
 }
 export {};

package/dist/scale.d.ts

@@ -0,0 +1,12 @@
+/** A visual level derived around one concrete default value. */
+export type ScaleLevel = "xsmall" | "small" | "medium" | "large" | "xlarge";
+/** Every numeric level derived around one concrete default value. */
+export type NumericScale = Readonly<Record<ScaleLevel, number>>;
+/** Returns whether a value names one of the system's derived visual levels. */
+export declare function isScaleLevel(value: unknown): value is ScaleLevel;
+/** Derives one visual level around a concrete default value. */
+export declare function scale(value: number, level: ScaleLevel): number;
+/** Derives the complete visual scale around one concrete default value. */
+export declare function numericScale(value: number): NumericScale;
+/** Derives a multiplier while preserving its neutral value of one. */
+export declare function scaleMultiplier(value: number, level: ScaleLevel): number;

package/dist/scale.js

@@ -0,0 +1,29 @@
+const factors = Object.freeze({
+    xsmall: 0.25,
+    small: 0.5,
+    medium: 1,
+    large: 1.5,
+    xlarge: 2
+});
+/** Returns whether a value names one of the system's derived visual levels. */
+export function isScaleLevel(value) {
+    return value === "xsmall" || value === "small" || value === "medium" || value === "large" || value === "xlarge";
+}
+/** Derives one visual level around a concrete default value. */
+export function scale(value, level) {
+    return value * factors[level];
+}
+/** Derives the complete visual scale around one concrete default value. */
+export function numericScale(value) {
+    return Object.freeze({
+        xsmall: scale(value, "xsmall"),
+        small: scale(value, "small"),
+        medium: scale(value, "medium"),
+        large: scale(value, "large"),
+        xlarge: scale(value, "xlarge")
+    });
+}
+/** Derives a multiplier while preserving its neutral value of one. */
+export function scaleMultiplier(value, level) {
+    return 1 + (value - 1) * factors[level];
+}

package/dist/server.d.ts

@@ -20,23 +20,23 @@ export type AnswerCapture<Result = unknown, To = Endpoint> = Readonly<{
 }>;
 /** A callback that observes answers sent by this Server. */
 export type AnswerObserver<Result = unknown, To = Endpoint> = (capture: AnswerCapture<Result, To>) => unknown;
-/** Broad communication originating from one Server, including its answers. */
+/** Directed communication originating from one Server, including its answers. */
 export interface ServerTraffic<Events extends object = {}, To = Endpoint, AskTo = Server> extends EndpointTraffic<Events, To, AskTo> {
     /** Observes answers originating from this Server. */
     observeAnswers<Result = unknown>(observer: AnswerObserver<Result, To>): Cleanup;
 }
 /** The server Endpoint of a Process. */
 export declare class Server<Events extends object = {}> extends Endpoint<Events> {
-    constructor();
+    protected constructor();
 }
 export interface Server<Events extends object = {}> extends Askable {
-    /** Broad communication originating from this Server. */
+    /** Directed communication originating from this Server. */
     readonly traffic: ServerTraffic<Events>;
     /**
      * Waits until a Server incarnation is ready.
      *
      * Temporary absence remains waitable when the Program declares a Server.
      * The SDK uses its ten-second deadline unless one is supplied.
-    */
+     */
     waitReady(timeout?: number): Promise<void>;
 }

package/dist/sql.d.ts

@@ -7,11 +7,18 @@ export interface ProgramSql {
 }
 /** One captured line from a Program endpoint. */
 export type LogRecord = Readonly<{
+    /** Capture time as Unix milliseconds. */
     createdAt: number;
+    /** Runtime identity of the Process that produced the line. */
     process: string;
+    /** Endpoint kind that produced the line. */
     source: LogSource;
+    /** Logging method or stream represented by the line. */
     kind: LogKind;
+    /** Text captured from the Endpoint. */
     content: string;
 }>;
+/** Endpoint kind capable of producing a captured log line. */
 export type LogSource = "client" | "server";
+/** Standard and application-defined kinds of captured output. */
 export type LogKind = "debug" | "log" | "info" | "warn" | "error" | "stdout" | "stderr" | "exit" | (string & {});

package/dist/storage.d.ts

@@ -1,16 +1,26 @@
 /** Metadata returned for an entry in Program-owned filesystem storage. */
 export type EntryStat = FileStat | DirectoryStat | OtherStat;
+/** Metadata for one file. */
 export type FileStat = Readonly<{
+    /** Discriminator for file metadata. */
     kind: "file";
+    /** File size in bytes. */
     size: number;
+    /** Last modification time as Unix milliseconds. */
     modifiedAt: number;
 }>;
+/** Metadata for one directory. */
 export type DirectoryStat = Readonly<{
+    /** Discriminator for directory metadata. */
     kind: "directory";
+    /** Last modification time as Unix milliseconds. */
     modifiedAt: number;
 }>;
+/** Metadata for a filesystem entry that is neither a file nor a directory. */
 export type OtherStat = Readonly<{
+    /** Discriminator for other filesystem metadata. */
     kind: "other";
+    /** Last modification time as Unix milliseconds. */
     modifiedAt: number;
 }>;
 /** Filesystem-like storage owned by one Program. */

package/dist/subscribable.d.ts

@@ -21,6 +21,19 @@ export type EventSubscriber<Message> = (message: Message) => unknown;
 export type EventObserver<Events extends object, Fallback = never> = (capture: Captures<Events, Fallback>) => unknown;
 /** Removes exactly one persistent registration. Safe to call more than once. */
 export type Cleanup = () => void;
+declare const definition: unique symbol;
+type Definition<Events extends object, Fallback> = Readonly<{
+    events: Events;
+    fallback: Fallback;
+}>;
+/** Extracts the declared event map from a Subscribable type. */
+export type SubscribableEvents<Target> = Target extends {
+    readonly [definition]?: Definition<infer Events, unknown>;
+} ? Events : never;
+/** Extracts the fallback message from a Subscribable type. */
+export type SubscribableFallback<Target> = Target extends {
+    readonly [definition]?: Definition<object, infer Fallback>;
+} ? Fallback : never;
 /** Options controlling one asynchronous event iterator. */
 export type EventOptions = Readonly<{
     /** Maximum queued messages. Defaults to `64`; `Infinity` removes the bound. */
@@ -30,22 +43,36 @@ export type EventOptions = Readonly<{
 }>;
 type OpenEvent = string & {};
 type AvailableEvent<Events extends object, Fallback> = EventName<Events> | ([Fallback] extends [never] ? never : OpenEvent);
+type InferredEvent<Event extends string> = string extends Event ? never : Event;
 type CompatibleEvent<Events extends object, Fallback, Narrowed> = {
     [Event in EventName<Events>]: Narrowed extends Events[Event] ? Event : never;
 }[EventName<Events>] | ([Fallback] extends [never] ? never : Narrowed extends Fallback ? OpenEvent : never);
 interface Subscribe<Events extends object, Fallback> {
+    /** Registers one persistent named-event subscription and returns its cleanup. */
+    <Event extends AvailableEvent<Events, Fallback>>(event: InferredEvent<Event>, subscriber: EventSubscriber<EventMessage<Events, Fallback, Event>>): Cleanup;
+    /** Registers one persistent named-event subscription and returns its cleanup. */
     <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, subscriber: EventSubscriber<Narrowed>): Cleanup;
-    <Event extends AvailableEvent<Events, Fallback>>(event: Event, subscriber: EventSubscriber<EventMessage<Events, Fallback, Event>>): Cleanup;
+    /** Registers one persistent named-event subscription and returns its cleanup. */
+    (event: [Fallback] extends [never] ? never : OpenEvent, subscriber: EventSubscriber<Fallback>): Cleanup;
 }
 interface WaitFor<Events extends object, Fallback> {
+    /** Waits for the next matching message. */
     <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, timeout?: number): Promise<Narrowed>;
-    <Event extends AvailableEvent<Events, Fallback>>(event: Event, timeout?: number): Promise<EventMessage<Events, Fallback, Event>>;
+    /** Waits for the next matching message. */
+    <Event extends AvailableEvent<Events, Fallback>>(event: InferredEvent<Event>, timeout?: number): Promise<EventMessage<Events, Fallback, Event>>;
+    /** Waits for the next matching message. */
+    (event: [Fallback] extends [never] ? never : OpenEvent, timeout?: number): Promise<Fallback>;
 }
 interface EventStream<Events extends object, Fallback> {
+    /** Iterates matching messages until closed, aborted, or impossible. */
     <Narrowed>(event: CompatibleEvent<Events, Fallback, Narrowed>, options?: EventOptions): AsyncIterableIterator<Narrowed>;
-    <Event extends AvailableEvent<Events, Fallback>>(event: Event, options?: EventOptions): AsyncIterableIterator<EventMessage<Events, Fallback, Event>>;
+    /** Iterates matching messages until closed, aborted, or impossible. */
+    <Event extends AvailableEvent<Events, Fallback>>(event: InferredEvent<Event>, options?: EventOptions): AsyncIterableIterator<EventMessage<Events, Fallback, Event>>;
+    /** Iterates matching messages until closed, aborted, or impossible. */
+    (event: [Fallback] extends [never] ? never : OpenEvent, options?: EventOptions): AsyncIterableIterator<Fallback>;
 }
 interface Observe<Events extends object, Fallback> {
+    /** Registers one persistent observer across every event and returns its cleanup. */
     (observer: EventObserver<Events, Fallback>): Cleanup;
 }
 /**
@@ -60,6 +87,8 @@ interface Observe<Events extends object, Fallback> {
  * signal aborts, or the boundary proves that future delivery is impossible.
  */
 export interface Subscribable<Events extends object = {}, Fallback = unknown> {
+    /** @internal Preserves this contract's declared types for SDK adapters. */
+    readonly [definition]?: Definition<Events, Fallback>;
     /** Registers one persistent named-event subscription. */
     subscribe: Subscribe<Events, Fallback>;
     /** Waits for the next matching message. */

package/dist/theme.d.ts

@@ -0,0 +1,132 @@
+import type { Subscribable } from "./subscribable.js";
+/** Inclusive limits for one customizable Theme value. */
+export type ThemeRange = Readonly<{
+    /** Smallest accepted value. */
+    minimum: number;
+    /** 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;
+}>;
+/** The complete set of system-defined Theme properties. */
+export type ThemeProperties = Readonly<{
+    /** CSS color underlying shared interface surfaces and materials. */
+    background: string;
+    /** CSS color used for shared interface content. */
+    foreground: string;
+    /** CSS color used for shared interface emphasis and interaction. */
+    accent: string;
+    /** Default component spacing expressed in CSS pixels. */
+    spacing: number;
+    /** Default component corner radius expressed in CSS pixels. */
+    radius: number;
+    /** Default values for the shared glass material. */
+    glass: ThemeGlass;
+}>;
+/** System-owned bounds for Theme customization. */
+export declare const themeLimits: Readonly<{
+    spacing: Readonly<{
+        minimum: 6;
+        maximum: 18;
+    }>;
+    radius: 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;
+        }>;
+    }>;
+}>;
+/** Complete standard Theme available to every environment. */
+export declare const standardTheme: Readonly<{
+    /** CSS color underlying shared interface surfaces and materials. */
+    background: string;
+    /** CSS color used for shared interface content. */
+    foreground: string;
+    /** CSS color used for shared interface emphasis and interaction. */
+    accent: string;
+    /** Default component spacing expressed in CSS pixels. */
+    spacing: number;
+    /** Default component corner radius expressed in CSS pixels. */
+    radius: number;
+    /** Default values for the shared glass material. */
+    glass: ThemeGlass;
+}>;
+/** Creates a complete immutable Theme snapshot at the contract boundary. */
+export declare function createThemeSnapshot(theme: ThemeProperties): ThemeProperties;
+/** Live events published by a Theme after a subscription exists. */
+export type ThemeEvents<Properties extends object = ThemeProperties> = {
+    /** A complete replacement Theme snapshot published after registration. */
+    change: Readonly<Properties>;
+};
+/**
+ * A read-only source of Theme properties.
+ *
+ * Reading and observing are distinct, explicit operations. `snapshot()` asks
+ * the host for its current value. The inherited subscription surface observes
+ * only changes published after registration; it does not replay a snapshot.
+ */
+export interface Theme<Properties extends object = ThemeProperties> extends Subscribable<ThemeEvents<Properties>, never> {
+    /** Explicitly requests the complete current Theme snapshot from the host. */
+    readonly snapshot: () => Promise<Readonly<Properties>>;
+}
+/** A Theme authority that can validate and replace the current snapshot. */
+export interface WritableTheme<Properties extends object = ThemeProperties> extends Theme<Properties> {
+    /** Replaces the complete Theme and resolves after the authority accepts it. */
+    readonly update: (theme: Properties) => Promise<void>;
+}
+/** An element whose semantic color may be selected. */
+export interface Colorable<Color = unknown> {
+    /** Semantic role from which the element derives its colors. */
+    readonly color?: Color;
+}
+/** An element whose supported size may be selected. */
+export interface Sizable<Size = unknown> {
+    /** Semantic element size. */
+    readonly size?: Size;
+}
+/** An element whose supported corner shape may be selected. */
+export interface Shapeable<Radius = unknown> {
+    /** Semantic corner-radius level. */
+    readonly radius?: Radius;
+}
+/** An element whose component-specific visual treatment may be selected. */
+export interface Variantable<Variant extends string> {
+    /** Visual treatment defined by the element implementing this capability. */
+    readonly variant?: Variant;
+}
+/** An element whose surface depth may be selected. */
+export interface Elevatable<Elevation = unknown> {
+    /** Semantic surface-depth level. */
+    readonly elevation?: Elevation;
+}

package/dist/theme.js

@@ -0,0 +1,34 @@
+/** System-owned bounds for Theme customization. */
+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 })
+    })
+});
+/** Complete standard Theme available to every environment. */
+export const standardTheme = createThemeSnapshot({
+    background: "#edf8fc",
+    foreground: "#183447",
+    accent: "#4c9cff",
+    spacing: 12,
+    radius: 10,
+    glass: {
+        distortion: 70,
+        blur: 4,
+        saturation: 1.8,
+        brightness: 1.06,
+        opacity: 0.12
+    }
+});
+/** Creates a complete immutable Theme snapshot at the contract boundary. */
+export function createThemeSnapshot(theme) {
+    return Object.freeze({
+        ...theme,
+        glass: Object.freeze({ ...theme.glass })
+    });
+}

package/dist/timeout.d.ts

@@ -0,0 +1,5 @@
+/** A capability that can be viewed with one caller-selected deadline. */
+export interface Timeoutable<Timed> {
+    /** Returns an immutable view whose asynchronous operation uses this deadline. */
+    timeout(milliseconds: number): Timed;
+}

package/dist/value.d.ts

@@ -0,0 +1,17 @@
+/** A pixel count or a relative linear expression. */
+export type Value = number | string;
+/** A value reduced to one relative coefficient and one absolute offset. */
+export interface RelativeValue {
+    relative: number;
+    pixels: number;
+}
+/**
+ * Reduces a strict linear expression into `span * relative + pixels`.
+ *
+ * Numbers are absolute values. Percentages and `n/d` fractions are relative
+ * values. Addition and subtraction combine terms; multiplication and division
+ * scale the preceding term by a number. No arbitrary code or CSS is accepted.
+ */
+export declare function parseRelativeValue(input: unknown): RelativeValue | null;
+/** Returns whether a value belongs to the linear relative-value grammar. */
+export declare function isRelativeValue(value: unknown): value is Value;