@phreshos/react 0.1.15 → 0.1.17

package/README.md

@@ -1,162 +1,91 @@
 # `@phreshos/react`
 
-The React SDK adapts `@phreshos/client` to React. It is not another domain
-authority and does not define Program, Process, Endpoint, Client, Server, or
-Window objects.
-
-## Package status
-
-This package is one component of a larger architecture that is still under
-active testing. The architecture's components will be released in stages as
-their contracts and integrations are verified.
-
-`@phreshos/react` is not intended to be used on its own. It adapts the Client
-SDK to React and therefore requires both `@phreshos/client` and React as peer
-dependencies.
-
-It provides two kinds of adapter:
-
-- `ContextProvider` resolves exactly the runtime values named by its required
-  `provide` prop, then exposes them synchronously through `useProgram()`,
-  `useProcess()`, and `useParent()`.
-- `SystemProvider` subscribes before reading exactly the system values named by its
-  required `provide` prop. `useSystemAppearance()`, `useDesktopPreferences()`,
-  `useDesktopSize()`, and `usePointerPosition()` expose those values synchronously
-  after resolution.
-- `useSubscribe()` owns named or all-event registrations for one mounted React
-  consumer.
-- `useProgramState(program)`, `useProcessState(process)`,
-  `useServiceState(service)`, and `useWindowState(window)` explicitly compose
-  existing reads with future live events for one mounted consumer. They add no
-  state operation to another SDK.
-- `useSubscribeAsks()` adapts an Endpoint traffic surface's question
-  subscription, while `useSubscribeAnswers()` adapts a Server traffic
-  surface's answer subscription.
-
-Window needs no React resolution: `context.window` is already a synchronous,
-silent capability object. `ContextProvider` therefore has no `window` selection
-and the React SDK exposes no pass-through `useWindow()` hook.
-
-The domain state hooks return only mutable state; identity and immutable
-metadata remain on the supplied handle:
-
-```ts
-useProgramState(program)
-// { installed, processes } | undefined
-
-useProcessState(process)
-// { exited, serverExists, clientExists } | undefined
-
-useServiceState(service)
-// { enabled } | undefined
-
-useWindowState(window)
-// WindowState | undefined
-```
+Runtime-neutral React adapters for PhreshOS contracts.
 
-`WindowState` contains the observable Window properties only. The command-only
-`window.surface` capability is intentionally absent: Program code may replace
-or remove its target but cannot read or subscribe to it.
-
-`undefined` means only that the initial explicit reads are pending. Each hook
-opens its live subscriptions before those reads, then applies any intervening
-events so an older result cannot overwrite newer state. If an initial read
-rejects, the hook throws that original value during render for the nearest
-React error boundary. It does not invent a fallback, retry, wait for a stopped
-Client, or use an old Window snapshot as the fallback for that rejection. State
-exists only while the hook is mounted and every registration is cleaned up on
-unmount.
-
-The Window capability outlives a stopped Client, but live Window state does
-not. A component that spans Client lifecycle should use `useProcessState()` to
-mount its `useWindowState()` child only while `clientExists` is true. Calling
-the Window hook while the Client is absent lets the existing Window reads
-reject normally.
-
-The ordinary-event and traffic hooks retain the latest value returned by their
-projector. A named `useSubscribe()` may omit that callback; its default
-projector is `message => message`, so the hook retains the latest message
-unchanged. The all-event form receives a correlated capture:
+The React SDK receives explicit Core handles and live sources. It does not
+initialize transport, import the Client SDK, access the browser, or define
+domain state.
 
-```tsx
-import { system } from "@phreshos/client"
-import { useSubscribe } from "@phreshos/react"
+## Installation
 
-const desktop = useSubscribe(system.desktop, "resize")
+| Package manager | Command |
+| --- | --- |
+| npm | `npm install @phreshos/react` |
+| pnpm | `pnpm add @phreshos/react` |
+| Bun | `bun add @phreshos/react` |
+| Yarn | `yarn add @phreshos/react` |
 
-const latest = useSubscribe(system.desktop, capture => {
-  if (capture.event === "resize") return capture.message
-})
-```
+`@phreshos/core` and React are peer dependencies.
 
-System reads are asynchronous while subscriptions are live-only. `SystemProvider`
-subscribes before requesting each selected snapshot and prevents an older read
-from overwriting a newer event:
+## Providers
 
 ```tsx
-import { SystemProvider, useDesktopPreferences, useDesktopSize, useSystemAppearance } from "@phreshos/react"
+import { ContextProvider, SystemProvider } from "@phreshos/react"
+
+<SystemProvider
+  appearance={system.appearance}
+  desktopSurface={system.desktop.surface}
+  desktopPointer={system.desktop.pointer}
+  desktopPreferences={system.desktop.preferences}
+>
+  <ContextProvider
+    program={() => context.program()}
+    process={() => context.process()}
+    parent={() => context.process().then(process => process.parent())}
+  >
+    {children}
+  </ContextProvider>
+</SystemProvider>
+```
 
-function Content() {
-  const { theme } = useDesktopPreferences()
-  const appearance = useSystemAppearance()
-  const desktop = useDesktopSize()
+Each provider accepts explicitly selected sources and resolves only those
+values. A provider requires at least one source; mounting it does not fetch an
+entire runtime implicitly.
 
-  return <p style={{ color: appearance.foreground[theme] }}>{desktop.width} × {desktop.height}</p>
-}
+## Hooks
 
-function App() {
-  return <SystemProvider provide={["appearance", "desktopPreferences", "desktopSize"]} fallback={<p>Loading…</p>}>
-    <Content />
-  </SystemProvider>
-}
-```
+Context hooks expose the supplied handles:
 
-The selection is required and non-empty. Nothing is read or subscribed merely
-because either SDK was imported, and an unselected system value never enters the
-Client. `pointerPosition` is permission-guarded: selecting it does not request
-permission, and resolution fails unless the Program already holds `pointer`.
-The provider renders its optional fallback, or `null`, until every selected
-value resolves. `useDesktopPreferences()` is a pure state adapter. The System
-communicates its effective scheme through the Client iframe, while each Client
-HTML document declares which schemes it supports.
+- `useProgram()`
+- `useProcess()`
+- `useParent()`
 
-```tsx
-import { context } from "@phreshos/client"
-import {
-  ContextProvider,
-  useProgram,
-  useSubscribe
-} from "@phreshos/react"
-
-function Counter() {
-  const program = useProgram()
-
-  const count = useSubscribe(context, "count", message => {
-    return Number(message.payload)
-  })
-
-  return <p>{program.name}: {count ?? 0}</p>
-}
-
-export default function App() {
-  return (
-    <ContextProvider provide={["program"]} fallback={<p>Loading…</p>} waitServer>
-      <Counter />
-    </ContextProvider>
-  )
-}
+System hooks expose the supplied live snapshots:
+
+- `useSystemAppearance()`
+- `useDesktopSurface()`
+- `useDesktopPointer()`
+- `useDesktopPreferences()`
+
+State hooks compose one explicit read with future events:
+
+- `useProgramState()`
+- `useProcessState()`
+- `useServiceState()`
+- `useWindowState()`
+
+`useSubscribe()`, `useSubscribeAsks()`, and `useSubscribeAnswers()` own
+their mounted registrations and clean them up on unmount. Unresolved initial
+reads remain `undefined`; the adapters do not invent fallback domain state.
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run verify
 ```
 
-Using a context or system hook outside its provider, or without selecting its
-value, throws a configuration error. Neither provider supplies an implicit
-"everything" selection, so adding a future capability cannot make it enter an
-existing application.
+`verify` checks the contracts, tests the adapters in React, builds the package,
+and validates its public artifact.
+
+## Repository boundary
+
+This repository owns React lifecycle adaptation only. Core owns the contracts,
+runtime SDKs provide the sources, and React UI owns visual components.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow and
+[SECURITY.md](SECURITY.md) for private vulnerability reporting.
 
-Each hook calls the registration's returned cleanup when the component no
-longer consumes it. Projectors may return a value or Promise; only the latest
-invocation may update the hook state. Projector failures are never converted
-into communication, logged, or suppressed by the SDK; they remain local to the
-React application.
+## License
 
-React is a peer dependency, so this package never installs or bundles a second
-copy into an application.
+Licensed under the [MIT License](LICENSE). Copyright © 2026 Zohayr SLILEH.

package/dist/context-provider.d.ts

@@ -1,34 +1,30 @@
 import { type ReactNode } from "react";
-import { type Process, type Program } from "@phreshos/client";
-declare const provisionNames: readonly ["program", "process", "parent"];
-/** Resolves only the runtime handles explicitly selected by the program. */
-export default function ContextProvider({ children, fallback, provide, waitServer }: ContextProviderProperties): import("react").FunctionComponentElement<SelectedContextProviderProperties>;
-/** Returns the current Program selected by the nearest provider. */
-export declare function useProgram(): Program;
-/** Returns the current Process selected by the nearest provider. */
-export declare function useProcess(): Process;
-/** Returns the current Process's selected visible parent. */
-export declare function useParent(): Process | null;
-/** Values that ContextProvider can resolve. */
-export type ContextProvisionName = typeof provisionNames[number];
-/** Required non-empty selection of runtime values. */
-export type ContextProvision = readonly [ContextProvisionName, ...ContextProvisionName[]];
+import type { Process, Program } from "@phreshos/core";
+/** Resolves only the runtime handles supplied by the surrounding runtime. */
+export default function ContextProvider({ children, fallback, parent, process, program }: ContextProviderProperties): string | number | bigint | boolean | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").FunctionComponentElement<import("react").ProviderProps<Partial<Readonly<{
+    program: Program;
+    process: Process;
+    parent: Process | null;
+}>> | null>> | null;
+/** Returns the current Program supplied by the nearest provider. */
+export declare function useProgram<Handle extends Program = Program>(): Handle;
+/** Returns the current Process supplied by the nearest provider. */
+export declare function useProcess<Handle extends Process = Process>(): Handle;
+/** Returns the current Process's supplied visible parent. */
+export declare function useParent<Handle extends Process = Process>(): Handle | null;
+/** A stable handle or resolver supplied by one runtime integration. */
+export type ContextSource<Value> = Value | (() => Value | PromiseLike<Value>);
 /** Properties accepted by ContextProvider. */
-export interface ContextProviderProperties {
-    /** Content rendered after every selected runtime handle has resolved. */
+export type ContextProviderProperties = Readonly<{
     readonly children: ReactNode;
-    /** Content rendered while selected handles or optional Server readiness resolve. */
     readonly fallback?: ReactNode;
-    /** Exact runtime values made available to descendant hooks. */
-    readonly provide: ContextProvision;
-    /**
-     * Waits for the Process's Server before rendering children.
-     * `true` uses the default ten-second deadline; a number sets milliseconds.
-     */
-    readonly waitServer?: boolean | number;
-}
-type SelectedContextProviderProperties = Omit<ContextProviderProperties, "provide" | "waitServer"> & Readonly<{
-    selection: readonly ContextProvisionName[];
-    waitServer: boolean | number;
+}> & AtLeastOne<ContextSources>;
+type ContextSources = Readonly<{
+    readonly parent?: ContextSource<Process | null>;
+    readonly process?: ContextSource<Process>;
+    readonly program?: ContextSource<Program>;
 }>;
+type AtLeastOne<Values> = {
+    [Name in keyof Values]-?: Required<Pick<Values, Name>> & Partial<Omit<Values, Name>>;
+}[keyof Values];
 export {};

package/dist/context-provider.js

@@ -1,93 +1,63 @@
 import { createContext, createElement, useContext, useEffect, useMemo, useState } from "react";
-import { context } from "@phreshos/client";
-const provisionNames = ["program", "process", "parent"];
 const RuntimeContext = createContext(null);
-/** Resolves only the runtime handles explicitly selected by the program. */
-export default function ContextProvider({ children, fallback = null, provide, waitServer = false }) {
-    const normalized = normalizeProvision(provide);
-    const selectionKey = normalized.join("\0");
-    const selection = useMemo(() => normalized, [selectionKey]);
-    return createElement(SelectedContextProvider, {
-        children,
-        fallback,
-        key: `${selectionKey}\0${String(waitServer)}`,
-        selection,
-        waitServer
-    });
-}
-function SelectedContextProvider({ children, fallback, selection, waitServer }) {
-    const [resolution, setResolution] = useState({ status: "pending" });
+/** Resolves only the runtime handles supplied by the surrounding runtime. */
+export default function ContextProvider({ children, fallback = null, parent, process, program }) {
+    const sources = useMemo(() => ({ parent, process, program }), [parent, process, program]);
+    const [resolution, setResolution] = useState({ status: "pending", sources });
+    if (parent === undefined && process === undefined && program === undefined) {
+        throw new Error("ContextProvider requires at least one runtime handle");
+    }
     useEffect(() => {
         let active = true;
-        setResolution({ status: "pending" });
-        void resolveContext(selection, waitServer).then(value => {
+        void resolveSources(sources).then(value => {
             if (active)
-                setResolution({ status: "ready", value });
+                setResolution({ status: "ready", sources, value });
         }, error => {
             if (active)
-                setResolution({ status: "error", error });
+                setResolution({ status: "error", sources, error });
         });
         return () => { active = false; };
-    }, [selection, waitServer]);
-    if (resolution.status === "pending")
+    }, [sources]);
+    if (resolution.sources !== sources || resolution.status === "pending")
         return fallback;
     if (resolution.status === "error")
         throw resolution.error;
     return createElement(RuntimeContext.Provider, { value: resolution.value }, children);
 }
-async function resolveContext(selection, waitServer) {
-    const serverReady = typeof waitServer === "number"
-        ? context.server.waitReady(waitServer)
-        : waitServer ? context.server.waitReady() : undefined;
-    const [entries] = await Promise.all([
-        Promise.all(selection.map(resolveProvision)),
-        serverReady
-    ]);
-    return {
-        provided: new Set(selection),
-        values: Object.fromEntries(entries)
-    };
+async function resolveSources(sources) {
+    const entries = await Promise.all(contextNames.flatMap(name => {
+        const source = sources[name];
+        return source === undefined ? [] : [resolveSource(name, source)];
+    }));
+    return Object.fromEntries(entries);
 }
-async function resolveProvision(name) {
-    switch (name) {
-        case "program": return [name, await context.program()];
-        case "process": return [name, await context.process()];
-        case "parent": return [name, await context.parent()];
-    }
+async function resolveSource(name, source) {
+    const value = typeof source === "function" ? source() : source;
+    return [name, await value];
 }
-/** Returns the current Program selected by the nearest provider. */
+/** Returns the current Program supplied by the nearest provider. */
 export function useProgram() {
     return useProvided("program");
 }
-/** Returns the current Process selected by the nearest provider. */
+/** Returns the current Process supplied by the nearest provider. */
 export function useProcess() {
     return useProvided("process");
 }
-/** Returns the current Process's selected visible parent. */
+/** Returns the current Process's supplied visible parent. */
 export function useParent() {
     return useProvided("parent");
 }
 function useProvided(name) {
-    const providedContext = useContext(RuntimeContext);
-    if (!providedContext)
-        throw new Error(`use${hookName(name)} must be used inside ContextProvider`);
-    if (!providedContext.provided.has(name))
-        throw new Error(`use${hookName(name)} requires "${name}" in ContextProvider's provide prop`);
-    return providedContext.values[name];
-}
-function normalizeProvision(provide) {
-    if (!Array.isArray(provide) || provide.length === 0)
-        throw new Error("ContextProvider's provide prop must select at least one runtime value");
-    const selected = new Set();
-    for (const name of provide) {
-        if (!provisionNames.includes(name))
-            throw new Error(`ContextProvider cannot provide "${String(name)}"`);
-        if (selected.has(name))
-            throw new Error(`ContextProvider's provide prop selects "${name}" more than once`);
-        selected.add(name);
-    }
-    return [...selected];
-}
-function hookName(name) {
-    return name.charAt(0).toUpperCase() + name.slice(1);
-}
+    const context = useContext(RuntimeContext);
+    if (!context)
+        throw new Error(`${hookNames[name]} must be used inside ContextProvider`);
+    if (!(name in context))
+        throw new Error(`${hookNames[name]} requires ContextProvider's ${name} prop`);
+    return context[name];
+}
+const contextNames = ["program", "process", "parent"];
+const hookNames = {
+    parent: "useParent",
+    process: "useProcess",
+    program: "useProgram"
+};

package/dist/event-result.d.ts

@@ -1,4 +1,4 @@
-import type { Cleanup } from "@phreshos/client";
+import type { Cleanup } from "@phreshos/core";
 /** A persistent SDK registration consumed by the React adapter. */
 export type Connect<Message> = (receive: (message: Message) => void) => Cleanup;
 /** Retains only the latest projected event value for one mounted hook. */

package/dist/live-snapshot.d.ts

@@ -1,4 +1,4 @@
-import type { Cleanup } from "@phreshos/client";
+import type { Cleanup } from "@phreshos/core";
 /** One explicitly requested snapshot followed by only future live changes. */
 export default class LiveSnapshot<Value> {
     private readonly read;

package/dist/live-state.d.ts

@@ -1,4 +1,4 @@
-import type { Cleanup } from "@phreshos/client";
+import type { Cleanup } from "@phreshos/core";
 export type StateReducer<State> = (state: State) => State;
 export type StateFollower<State> = (reduce: (reducer: StateReducer<State>) => void) => Cleanup;
 /** One mounted React snapshot composed from an explicit read and future events. */

package/dist/main.d.ts

@@ -1,5 +1,5 @@
-export { default as ContextProvider, useParent, useProcess, useProgram, type ContextProvision, type ContextProvisionName, type ContextProviderProperties } from "./context-provider.js";
-export { default as SystemProvider, usePointerPosition, useDesktopSize, useDesktopPreferences, useSystemAppearance, type SystemProvision, type SystemProvisionName, type SystemProviderProperties } from "./system-provider.js";
+export { default as ContextProvider, useParent, useProcess, useProgram, type ContextSource, type ContextProviderProperties } from "./context-provider.js";
+export { default as SystemProvider, useDesktopPointer, useDesktopSurface, useDesktopPreferences, useSystemAppearance, type SystemProviderProperties } from "./system-provider.js";
 export { default as useSubscribe } from "./use-subscribe.js";
 export { default as useProgramState, type ProgramState } from "./use-program-state.js";
 export { default as useProcessState, type ProcessState } from "./use-process-state.js";

package/dist/main.js

@@ -1,5 +1,5 @@
 export { default as ContextProvider, useParent, useProcess, useProgram } from "./context-provider.js";
-export { default as SystemProvider, usePointerPosition, useDesktopSize, useDesktopPreferences, useSystemAppearance } from "./system-provider.js";
+export { default as SystemProvider, useDesktopPointer, useDesktopSurface, useDesktopPreferences, useSystemAppearance } from "./system-provider.js";
 export { default as useSubscribe } from "./use-subscribe.js";
 export { default as useProgramState } from "./use-program-state.js";
 export { default as useProcessState } from "./use-process-state.js";

package/dist/system-provider.d.ts

@@ -1,30 +1,38 @@
 import { type ReactNode } from "react";
-import { type Appearance, type DesktopPreferences, type DesktopSize, type PointerPosition } from "@phreshos/client";
-declare const provisionNames: readonly ["appearance", "desktopPreferences", "desktopSize", "pointerPosition"];
-/** Requests and follows only the system values explicitly selected by the program. */
-export default function SystemProvider(properties: SystemProviderProperties): import("react").FunctionComponentElement<SelectedSystemProviderProperties>;
+import type { Appearance, AppearanceSource, DesktopPointerSnapshot, DesktopPointerSource, DesktopPreferences, DesktopPreferencesSource, DesktopSurfaceSnapshot, DesktopSurfaceSource } from "@phreshos/core";
+import LiveSnapshot from "./live-snapshot.js";
+/** Resolves and follows only the System capabilities supplied by the runtime. */
+export default function SystemProvider({ appearance, children, desktopPointer, desktopPreferences, desktopSurface, fallback }: SystemProviderProperties): string | number | bigint | boolean | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").FunctionComponentElement<import("react").ProviderProps<SystemStores | null>> | null;
 /** Returns the complete unresolved Appearance and follows authoritative updates. */
 export declare function useSystemAppearance(): Appearance;
+/** Returns the Desktop surface snapshot and follows future resizes. */
+export declare function useDesktopSurface(): DesktopSurfaceSnapshot;
+/** Returns the Desktop pointer snapshot and follows future movement. */
+export declare function useDesktopPointer(): DesktopPointerSnapshot;
 /** Returns all effective Desktop preferences and follows authoritative updates. */
 export declare function useDesktopPreferences(): DesktopPreferences;
-/** Returns the selected desktop size and follows future resize events. */
-export declare function useDesktopSize(): DesktopSize;
-/** Returns the selected Pointer position and follows future move events. */
-export declare function usePointerPosition(): PointerPosition | null;
-/** Values that SystemProvider can request and follow. */
-export type SystemProvisionName = typeof provisionNames[number];
-/** Required non-empty selection of system values. */
-export type SystemProvision = readonly [SystemProvisionName, ...SystemProvisionName[]];
 /** Properties accepted by SystemProvider. */
-export interface SystemProviderProperties {
-    /** Content rendered after every selected system value has resolved. */
+export type SystemProviderProperties = Readonly<{
     readonly children: ReactNode;
-    /** Content rendered while selected system values resolve. */
     readonly fallback?: ReactNode;
-    /** Exact system values requested and followed for mounted descendants. */
-    readonly provide: SystemProvision;
-}
-type SelectedSystemProviderProperties = SystemProviderProperties & Readonly<{
-    selection: readonly SystemProvisionName[];
+}> & AtLeastOne<SystemSources>;
+type SystemSources = Readonly<{
+    readonly appearance?: AppearanceSource;
+    readonly desktopPointer?: DesktopPointerSource;
+    readonly desktopPreferences?: DesktopPreferencesSource;
+    readonly desktopSurface?: DesktopSurfaceSource;
 }>;
+type SystemValues = Readonly<{
+    appearance: Appearance;
+    desktopPointer: DesktopPointerSnapshot;
+    desktopPreferences: DesktopPreferences;
+    desktopSurface: DesktopSurfaceSnapshot;
+}>;
+type SystemName = keyof SystemValues;
+type SystemStores = {
+    [Name in SystemName]?: LiveSnapshot<SystemValues[Name]>;
+};
+type AtLeastOne<Values> = {
+    [Name in keyof Values]-?: Required<Pick<Values, Name>> & Partial<Omit<Values, Name>>;
+}[keyof Values];
 export {};

package/dist/system-provider.js

@@ -1,103 +1,85 @@
 import { createContext, createElement, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
-import { system } from "@phreshos/client";
 import LiveSnapshot from "./live-snapshot.js";
-const provisionNames = ["appearance", "desktopPreferences", "desktopSize", "pointerPosition"];
 const SystemContext = createContext(null);
-/** Requests and follows only the system values explicitly selected by the program. */
-export default function SystemProvider(properties) {
-    const normalized = normalizeProvision(properties.provide);
-    const selectionKey = normalized.join("\0");
-    const selection = useMemo(() => normalized, [selectionKey]);
-    return createElement(SelectedSystemProvider, { ...properties, fallback: properties.fallback ?? null, key: selectionKey, selection });
-}
-function SelectedSystemProvider({ children, fallback, selection }) {
-    const stores = useMemo(() => createStores(selection), [selection]);
-    const [resolution, setResolution] = useState({ status: "pending" });
+/** Resolves and follows only the System capabilities supplied by the runtime. */
+export default function SystemProvider({ appearance, children, desktopPointer, desktopPreferences, desktopSurface, fallback = null }) {
+    const stores = useMemo(() => createStores({
+        appearance,
+        desktopPointer,
+        desktopPreferences,
+        desktopSurface
+    }), [appearance, desktopPointer, desktopPreferences, desktopSurface]);
+    const [resolution, setResolution] = useState({ status: "pending", stores });
+    if (Object.keys(stores).length === 0)
+        throw new Error("SystemProvider requires at least one System capability");
     useEffect(() => {
         let active = true;
-        const selected = selection.map(name => stores[name]);
+        const selected = Object.values(stores);
         void Promise.all(selected.map(store => store.start())).then(() => {
             if (active)
-                setResolution({ status: "ready" });
+                setResolution({ status: "ready", stores });
         }, error => {
             for (const store of selected)
                 store.stop();
             if (active)
-                setResolution({ status: "error", error });
+                setResolution({ status: "error", stores, error });
         });
         return () => {
             active = false;
             for (const store of selected)
                 store.stop();
         };
-    }, [selection, stores]);
-    if (resolution.status === "pending")
+    }, [stores]);
+    if (resolution.stores !== stores || resolution.status === "pending")
         return fallback;
     if (resolution.status === "error")
         throw resolution.error;
-    return createElement(SystemContext.Provider, { value: { provided: new Set(selection), stores } }, children);
+    return createElement(SystemContext.Provider, { value: stores }, children);
 }
 /** Returns the complete unresolved Appearance and follows authoritative updates. */
 export function useSystemAppearance() {
     return useProvided("appearance");
 }
+/** Returns the Desktop surface snapshot and follows future resizes. */
+export function useDesktopSurface() {
+    return useProvided("desktopSurface");
+}
+/** Returns the Desktop pointer snapshot and follows future movement. */
+export function useDesktopPointer() {
+    return useProvided("desktopPointer");
+}
 /** Returns all effective Desktop preferences and follows authoritative updates. */
 export function useDesktopPreferences() {
     return useProvided("desktopPreferences");
 }
-/** Returns the selected desktop size and follows future resize events. */
-export function useDesktopSize() {
-    return useProvided("desktopSize");
-}
-/** Returns the selected Pointer position and follows future move events. */
-export function usePointerPosition() {
-    return useProvided("pointerPosition");
-}
 function useProvided(name) {
     const context = useContext(SystemContext);
     if (!context)
         throw new Error(`${hookNames[name]} must be used inside SystemProvider`);
-    if (!context.provided.has(name))
-        throw new Error(`${hookNames[name]} requires "${name}" in SystemProvider's provide prop`);
-    const store = context.stores[name];
+    const store = context[name];
+    if (!store)
+        throw new Error(`${hookNames[name]} requires SystemProvider's ${name} prop`);
     return useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot);
 }
-function createStores(selection) {
+function createStores(sources) {
     const stores = {};
-    for (const name of selection) {
-        switch (name) {
-            case "appearance":
-                stores.appearance = new LiveSnapshot(() => system.appearance.snapshot(), subscriber => system.appearance.subscribe("change", subscriber));
-                break;
-            case "desktopPreferences":
-                stores.desktopPreferences = new LiveSnapshot(() => system.desktopPreferences.snapshot(), subscriber => system.desktopPreferences.subscribe("change", subscriber));
-                break;
-            case "desktopSize":
-                stores.desktopSize = new LiveSnapshot(() => system.desktop.size(), subscriber => system.desktop.subscribe("resize", subscriber));
-                break;
-            case "pointerPosition":
-                stores.pointerPosition = new LiveSnapshot(() => system.pointer.position(), subscriber => system.pointer.subscribe("move", subscriber));
-                break;
-        }
-    }
+    const appearance = sources.appearance;
+    const surface = sources.desktopSurface;
+    const pointer = sources.desktopPointer;
+    const preferences = sources.desktopPreferences;
+    if (appearance)
+        stores.appearance = new LiveSnapshot(() => appearance.snapshot(), subscriber => appearance.subscribe("change", subscriber));
+    if (surface)
+        stores.desktopSurface = new LiveSnapshot(() => surface.snapshot(), subscriber => surface.subscribe("resize", subscriber));
+    if (pointer)
+        stores.desktopPointer = new LiveSnapshot(() => pointer.snapshot(), subscriber => pointer.subscribe("move", subscriber));
+    if (preferences)
+        stores.desktopPreferences = new LiveSnapshot(() => preferences.snapshot(), subscriber => preferences.subscribe("change", subscriber));
     return stores;
 }
-function normalizeProvision(provide) {
-    if (!Array.isArray(provide) || provide.length === 0)
-        throw new Error("SystemProvider's provide prop must select at least one system value");
-    const selected = new Set();
-    for (const name of provide) {
-        if (!provisionNames.includes(name))
-            throw new Error(`SystemProvider cannot provide "${String(name)}"`);
-        if (selected.has(name))
-            throw new Error(`SystemProvider's provide prop selects "${name}" more than once`);
-        selected.add(name);
-    }
-    return [...selected];
-}
 const hookNames = {
     appearance: "useSystemAppearance",
+    desktopPointer: "useDesktopPointer",
     desktopPreferences: "useDesktopPreferences",
-    desktopSize: "useDesktopSize",
-    pointerPosition: "usePointerPosition"
+    desktopSurface: "useDesktopSurface"
 };

package/dist/use-process-state.d.ts

@@ -1,4 +1,4 @@
-import type { Process } from "@phreshos/client";
+import type { Process } from "@phreshos/core";
 /** Mutable lifecycle state of one Process and its Endpoint incarnations. */
 export type ProcessState = Readonly<{
     exited: boolean;

package/dist/use-program-state.d.ts

@@ -1,4 +1,4 @@
-import type { Process, Program } from "@phreshos/client";
+import type { Process, Program } from "@phreshos/core";
 /** Mutable runtime state derived from one Program's reads and live events. */
 export type ProgramState = Readonly<{
     installed: boolean;

package/dist/use-service-state.d.ts

@@ -1,7 +1,7 @@
-import type { Service } from "@phreshos/client";
-/** Live availability of one exact service identity. */
+import type { Service } from "@phreshos/core";
+/** Live existence of one configured Endpoint service. */
 export type ServiceState = Readonly<{
-    enabled: boolean;
+    exists: boolean;
 }>;
 /** Explicitly reads and follows one service while this hook is mounted. */
 export default function useServiceState(service: Service): ServiceState | undefined;

package/dist/use-service-state.js

@@ -2,9 +2,9 @@ import { useMemo, useSyncExternalStore } from "react";
 import LiveState, { combineCleanups } from "./live-state.js";
 /** Explicitly reads and follows one service while this hook is mounted. */
 export default function useServiceState(service) {
-    const state = useMemo(() => new LiveState(async () => ({ enabled: await service.enabled() }), reduce => combineCleanups(service.lifecycle.subscribe("enable", () => reduce(current => setEnabled(current, true))), service.lifecycle.subscribe("disable", () => reduce(current => setEnabled(current, false))))), [service]);
+    const state = useMemo(() => new LiveState(async () => ({ exists: await service.exists() }), reduce => combineCleanups(service.lifecycle.subscribe("start", () => reduce(current => setExists(current, true))), service.lifecycle.subscribe("stop", () => reduce(current => setExists(current, false))))), [service]);
     return useSyncExternalStore(state.subscribe, state.snapshot, state.snapshot);
 }
-function setEnabled(state, enabled) {
-    return state.enabled === enabled ? state : { enabled };
+function setExists(state, exists) {
+    return state.exists === exists ? state : { exists };
 }

package/dist/use-subscribe-answers.d.ts

@@ -1,4 +1,4 @@
-import type { AnswerCapture, AnswerSubscriber, Cleanup } from "@phreshos/client";
+import type { AnswerCapture, AnswerSubscriber, Cleanup } from "@phreshos/core";
 /** Any Server traffic surface capable of subscribing to its outgoing answers. */
 export type AnswerSubscribable = Readonly<{
     /** Subscribes to answers sent by the target Server and returns its cleanup. */

package/dist/use-subscribe-asks.d.ts

@@ -1,4 +1,4 @@
-import type { AskCapture, AskSubscriber, Cleanup } from "@phreshos/client";
+import type { AskCapture, AskSubscriber, Cleanup } from "@phreshos/core";
 /** Any Endpoint traffic surface capable of subscribing to its outgoing questions. */
 export type AskSubscribable = Readonly<{
     /** Subscribes to questions sent by the target Endpoint and returns its cleanup. */

package/dist/use-subscribe.d.ts

@@ -1,4 +1,4 @@
-import type { Captures, Context, ContextMessage, Endpoint, EventMessage, EventName, Subscribable, SubscribableEvents, SubscribableFallback } from "@phreshos/client";
+import type { Captures, Context, ContextMessage, Endpoint, EventMessage, EventName, Subscribable, SubscribableEvents, SubscribableFallback } from "@phreshos/core";
 type OpenEvent = string & {};
 type AvailableEvent<Events extends object, Fallback> = EventName<Events> | ([Fallback] extends [never] ? never : OpenEvent);
 type CompatibleEvent<Events extends object, Fallback, Narrowed> = {

package/dist/use-window-state.d.ts

@@ -1,3 +1,3 @@
-import type { Window, WindowState } from "@phreshos/client";
+import type { Window, WindowState } from "@phreshos/core";
 /** Explicitly reads and follows one live Client Window while mounted. */
 export default function useWindowState(window: Window): WindowState | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@phreshos/react",
-  "version": "0.1.15",
-  "description": "React adapters for the Client SDK.",
+  "version": "0.1.17",
+  "description": "Runtime-neutral React adapters for PhreshOS contracts.",
   "type": "module",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -47,13 +47,11 @@
     "prepack": "node --run test && node --run build"
   },
   "peerDependencies": {
-    "@phreshos/client": "^0.1.27",
-    "@phreshos/core": "^0.1.27",
+    "@phreshos/core": "^0.1.31",
     "react": "^19.2.0"
   },
   "devDependencies": {
-    "@phreshos/client": "^0.1.27",
-    "@phreshos/core": "^0.1.27",
+    "@phreshos/core": "^0.1.31",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",