@phreshos/react 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Zohayr SLILEH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,16 +16,105 @@ dependencies.
 
 It provides two kinds of adapter:
 
-- `CurrentProvider` resolves the Client SDK's current Program, Process, parent,
-  and Window, then exposes them synchronously through `useProgram()`,
-  `useProcess()`, `useParent()`, and `useWindow()`.
+- `CurrentProvider` resolves exactly the current values named by its required
+  `provide` prop, then exposes them synchronously through `useProgram()`,
+  `useProcess()`, and `useParent()`.
+- `HostProvider` subscribes before reading exactly the host values named by its
+  required `provide` prop. `useHostTheme()`, `useSurfaceSize()`, and
+  `usePointerPosition()` expose those values synchronously after resolution.
 - `useSubscribe()` and `useObserve()` own persistent ordinary-event
   registrations for one mounted React consumer.
+- `useProgramState(program)`, `useProcessState(process)`, and
+  `useWindowState(window)` explicitly compose existing reads with future live
+  events for one mounted consumer. They add no state operation to another SDK.
 - `useObserveAsks()` adapts an Endpoint traffic surface's question observation,
   while `useObserveAnswers()` adapts a Server traffic surface's answer
   observation.
+- `useScale(value)` and `useColor(value)` memoize the complete derived scale
+  around the explicit number or CSS color supplied by the component. They do
+  not read a Theme or choose a source value implicitly.
 
-All four hooks retain the latest value returned by their projector.
+Window needs no React resolution: `current.window` is already a synchronous,
+silent capability object. `CurrentProvider` 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
+
+useWindowState(window)
+// WindowState | undefined
+```
+
+`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.
+
+```tsx
+const theme = useHostTheme()
+const spacing = useScale(theme.spacing)
+const radius = useScale(theme.radius)
+const accent = useColor(theme.accent)
+```
+
+The ordinary-event and traffic hooks retain the latest value returned by their projector.
+`useSubscribe()` may omit that callback; its default projector is
+`message => message`, so the hook retains the latest message unchanged.
+
+```tsx
+import { host } from "@phreshos/client"
+import { useSubscribe } from "@phreshos/react"
+
+const surface = useSubscribe(host.surface, "resize")
+```
+
+Host reads are asynchronous while subscriptions are live-only. `HostProvider`
+subscribes before requesting each selected snapshot and prevents an older read
+from overwriting a newer event:
+
+```tsx
+import { HostProvider, useHostTheme, useSurfaceSize } from "@phreshos/react"
+
+function Content() {
+  const theme = useHostTheme()
+  const surface = useSurfaceSize()
+
+  return <p style={{ color: theme.foreground }}>{surface.width} × {surface.height}</p>
+}
+
+function App() {
+  return <HostProvider provide={["theme", "surfaceSize"]} fallback={<p>Loading…</p>}>
+    <Content />
+  </HostProvider>
+}
+```
+
+The selection is required and non-empty. Nothing is read or subscribed merely
+because either SDK was imported, and an unselected host 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 fallback until every selected value resolves.
 
 ```tsx
 import { current } from "@phreshos/client"
@@ -47,13 +136,18 @@ function Counter() {
 
 export default function App() {
   return (
-    <CurrentProvider fallback={<p>Loading…</p>} waitServer>
+    <CurrentProvider provide={["program"]} fallback={<p>Loading…</p>} waitServer>
       <Counter />
     </CurrentProvider>
   )
 }
 ```
 
+Using a current or host 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.
+
 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

package/dist/current-provider.d.ts

@@ -1,34 +1,34 @@
 import { type ReactNode } from "react";
-import { type Process, type Program, type Window } from "@phreshos/client";
-/**
- * Resolves the current domain handles before rendering its children.
- *
- * The provider owns no domain state. It only turns asynchronous Client SDK
- * navigation into synchronous React context for the hooks below it.
- */
-export default function CurrentProvider({ children, fallback, waitServer }: CurrentProviderProperties): 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<Readonly<{
-    program: Program;
-    process: Process;
-    parent: Process | null;
-    window: Window;
-}> | null>> | null | undefined;
-/** Returns the current Program from the nearest {@link CurrentProvider}. */
+import { type Process, type Program } from "@phreshos/client";
+declare const provisionNames: readonly ["program", "process", "parent"];
+/** Resolves only the current handles explicitly selected by the program. */
+export default function CurrentProvider({ children, fallback, provide, waitServer }: CurrentProviderProperties): import("react").FunctionComponentElement<SelectedCurrentProviderProperties>;
+/** Returns the current Program selected by the nearest provider. */
 export declare function useProgram(): Program;
-/** Returns the current Process from the nearest {@link CurrentProvider}. */
+/** Returns the current Process selected by the nearest provider. */
 export declare function useProcess(): Process;
-/** Returns the current Process's visible parent from the nearest provider. */
+/** Returns the current Process's selected visible parent. */
 export declare function useParent(): Process | null;
-/** Returns the current Window from the nearest {@link CurrentProvider}. */
-export declare function useWindow(): Window;
-/** Properties accepted by {@link CurrentProvider}. */
+/** Values that CurrentProvider can resolve. */
+export type CurrentProvisionName = typeof provisionNames[number];
+/** Required non-empty selection of current values. */
+export type CurrentProvision = readonly [CurrentProvisionName, ...CurrentProvisionName[]];
+/** Properties accepted by CurrentProvider. */
 export interface CurrentProviderProperties {
-    /** Content rendered after every current handle has resolved. */
+    /** Content rendered after every selected current handle has resolved. */
     readonly children: ReactNode;
-    /** Content rendered while current handles or optional Server readiness resolve. */
+    /** Content rendered while selected handles or optional Server readiness resolve. */
     readonly fallback: ReactNode;
+    /** Exact current values made available to descendant hooks. */
+    readonly provide: CurrentProvision;
     /**
      * 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 SelectedCurrentProviderProperties = Omit<CurrentProviderProperties, "provide" | "waitServer"> & Readonly<{
+    selection: readonly CurrentProvisionName[];
+    waitServer: boolean | number;
+}>;
+export {};

package/dist/current-provider.js

@@ -1,18 +1,26 @@
-import { createContext, createElement, useContext, useEffect, useState } from "react";
+import { createContext, createElement, useContext, useEffect, useMemo, useState } from "react";
 import { current } from "@phreshos/client";
+const provisionNames = ["program", "process", "parent"];
 const CurrentContext = createContext(null);
-/**
- * Resolves the current domain handles before rendering its children.
- *
- * The provider owns no domain state. It only turns asynchronous Client SDK
- * navigation into synchronous React context for the hooks below it.
- */
-export default function CurrentProvider({ children, fallback, waitServer = false }) {
+/** Resolves only the current handles explicitly selected by the program. */
+export default function CurrentProvider({ children, fallback, provide, waitServer = false }) {
+    const normalized = normalizeProvision(provide);
+    const selectionKey = normalized.join("\0");
+    const selection = useMemo(() => normalized, [selectionKey]);
+    return createElement(SelectedCurrentProvider, {
+        children,
+        fallback,
+        key: `${selectionKey}\0${String(waitServer)}`,
+        selection,
+        waitServer
+    });
+}
+function SelectedCurrentProvider({ children, fallback, selection, waitServer }) {
     const [resolution, setResolution] = useState({ status: "pending" });
     useEffect(() => {
         let active = true;
         setResolution({ status: "pending" });
-        void resolveCurrent(waitServer).then(value => {
+        void resolveCurrent(selection, waitServer).then(value => {
             if (active)
                 setResolution({ status: "ready", value });
         }, error => {
@@ -20,45 +28,66 @@ export default function CurrentProvider({ children, fallback, waitServer = false
                 setResolution({ status: "error", error });
         });
         return () => { active = false; };
-    }, [waitServer]);
+    }, [selection, waitServer]);
     if (resolution.status === "pending")
         return fallback;
     if (resolution.status === "error")
         throw resolution.error;
     return createElement(CurrentContext.Provider, { value: resolution.value }, children);
 }
-async function resolveCurrent(waitServer) {
+async function resolveCurrent(selection, waitServer) {
     const serverReady = typeof waitServer === "number"
         ? current.server.waitReady(waitServer)
         : waitServer ? current.server.waitReady() : undefined;
-    const [program, process, parent] = await Promise.all([
-        current.program(),
-        current.process(),
-        current.parent(),
+    const [entries] = await Promise.all([
+        Promise.all(selection.map(resolveProvision)),
         serverReady
     ]);
-    const window = await current.window();
-    return { program, process, parent, window };
+    return {
+        provided: new Set(selection),
+        values: Object.fromEntries(entries)
+    };
+}
+async function resolveProvision(name) {
+    switch (name) {
+        case "program": return [name, await current.program()];
+        case "process": return [name, await current.process()];
+        case "parent": return [name, await current.parent()];
+    }
 }
-/** Returns the current Program from the nearest {@link CurrentProvider}. */
+/** Returns the current Program selected by the nearest provider. */
 export function useProgram() {
-    return useCurrent().program;
+    return useProvided("program");
 }
-/** Returns the current Process from the nearest {@link CurrentProvider}. */
+/** Returns the current Process selected by the nearest provider. */
 export function useProcess() {
-    return useCurrent().process;
+    return useProvided("process");
 }
-/** Returns the current Process's visible parent from the nearest provider. */
+/** Returns the current Process's selected visible parent. */
 export function useParent() {
-    return useCurrent().parent;
+    return useProvided("parent");
+}
+function useProvided(name) {
+    const context = useContext(CurrentContext);
+    if (!context)
+        throw new Error(`use${hookName(name)} must be used inside CurrentProvider`);
+    if (!context.provided.has(name))
+        throw new Error(`use${hookName(name)} requires "${name}" in CurrentProvider's provide prop`);
+    return context.values[name];
 }
-/** Returns the current Window from the nearest {@link CurrentProvider}. */
-export function useWindow() {
-    return useCurrent().window;
+function normalizeProvision(provide) {
+    if (!Array.isArray(provide) || provide.length === 0)
+        throw new Error("CurrentProvider's provide prop must select at least one current value");
+    const selected = new Set();
+    for (const name of provide) {
+        if (!provisionNames.includes(name))
+            throw new Error(`CurrentProvider cannot provide "${String(name)}"`);
+        if (selected.has(name))
+            throw new Error(`CurrentProvider's provide prop selects "${name}" more than once`);
+        selected.add(name);
+    }
+    return [...selected];
 }
-function useCurrent() {
-    const value = useContext(CurrentContext);
-    if (!value)
-        throw new Error("Current hooks must be used inside CurrentProvider");
-    return value;
+function hookName(name) {
+    return name.charAt(0).toUpperCase() + name.slice(1);
 }

package/dist/host-provider.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from "react";
+import { type PointerPosition, type Surface, type ThemeProperties } from "@phreshos/client";
+declare const provisionNames: readonly ["theme", "surfaceSize", "pointerPosition"];
+/** Requests and follows only the host values explicitly selected by the program. */
+export default function HostProvider(properties: HostProviderProperties): import("react").FunctionComponentElement<SelectedHostProviderProperties>;
+/** Returns the selected Theme snapshot and follows future change events. */
+export declare function useHostTheme(): Readonly<ThemeProperties>;
+/** Returns the selected Surface size and follows future resize events. */
+export declare function useSurfaceSize(): Surface;
+/** Returns the selected Pointer position and follows future move events. */
+export declare function usePointerPosition(): PointerPosition | null;
+/** Values that HostProvider can request and follow. */
+export type HostProvisionName = typeof provisionNames[number];
+/** Required non-empty selection of host values. */
+export type HostProvision = readonly [HostProvisionName, ...HostProvisionName[]];
+/** Properties accepted by HostProvider. */
+export interface HostProviderProperties {
+    /** Content rendered after every selected host value has resolved. */
+    readonly children: ReactNode;
+    /** Content rendered while selected host values resolve. */
+    readonly fallback: ReactNode;
+    /** Exact host values requested and followed for mounted descendants. */
+    readonly provide: HostProvision;
+}
+type SelectedHostProviderProperties = HostProviderProperties & Readonly<{
+    selection: readonly HostProvisionName[];
+}>;
+export {};

package/dist/host-provider.js

@@ -0,0 +1,95 @@
+import { createContext, createElement, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { host } from "@phreshos/client";
+import LiveSnapshot from "./live-snapshot.js";
+const provisionNames = ["theme", "surfaceSize", "pointerPosition"];
+const HostContext = createContext(null);
+/** Requests and follows only the host values explicitly selected by the program. */
+export default function HostProvider(properties) {
+    const normalized = normalizeProvision(properties.provide);
+    const selectionKey = normalized.join("\0");
+    const selection = useMemo(() => normalized, [selectionKey]);
+    return createElement(SelectedHostProvider, { ...properties, key: selectionKey, selection });
+}
+function SelectedHostProvider({ children, fallback, selection }) {
+    const stores = useMemo(() => createStores(selection), [selection]);
+    const [resolution, setResolution] = useState({ status: "pending" });
+    useEffect(() => {
+        let active = true;
+        const selected = selection.map(name => stores[name]);
+        void Promise.all(selected.map(store => store.start())).then(() => {
+            if (active)
+                setResolution({ status: "ready" });
+        }, error => {
+            for (const store of selected)
+                store.stop();
+            if (active)
+                setResolution({ status: "error", error });
+        });
+        return () => {
+            active = false;
+            for (const store of selected)
+                store.stop();
+        };
+    }, [selection, stores]);
+    if (resolution.status === "pending")
+        return fallback;
+    if (resolution.status === "error")
+        throw resolution.error;
+    return createElement(HostContext.Provider, { value: { provided: new Set(selection), stores } }, children);
+}
+/** Returns the selected Theme snapshot and follows future change events. */
+export function useHostTheme() {
+    return useProvided("theme");
+}
+/** Returns the selected Surface size and follows future resize events. */
+export function useSurfaceSize() {
+    return useProvided("surfaceSize");
+}
+/** Returns the selected Pointer position and follows future move events. */
+export function usePointerPosition() {
+    return useProvided("pointerPosition");
+}
+function useProvided(name) {
+    const context = useContext(HostContext);
+    if (!context)
+        throw new Error(`${hookNames[name]} must be used inside HostProvider`);
+    if (!context.provided.has(name))
+        throw new Error(`${hookNames[name]} requires "${name}" in HostProvider's provide prop`);
+    const store = context.stores[name];
+    return useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot);
+}
+function createStores(selection) {
+    const stores = {};
+    for (const name of selection) {
+        switch (name) {
+            case "theme":
+                stores.theme = new LiveSnapshot(() => host.theme.snapshot(), subscriber => host.theme.subscribe("change", subscriber));
+                break;
+            case "surfaceSize":
+                stores.surfaceSize = new LiveSnapshot(() => host.surface.size(), subscriber => host.surface.subscribe("resize", subscriber));
+                break;
+            case "pointerPosition":
+                stores.pointerPosition = new LiveSnapshot(() => host.pointer.position(), subscriber => host.pointer.subscribe("move", subscriber));
+                break;
+        }
+    }
+    return stores;
+}
+function normalizeProvision(provide) {
+    if (!Array.isArray(provide) || provide.length === 0)
+        throw new Error("HostProvider's provide prop must select at least one host value");
+    const selected = new Set();
+    for (const name of provide) {
+        if (!provisionNames.includes(name))
+            throw new Error(`HostProvider cannot provide "${String(name)}"`);
+        if (selected.has(name))
+            throw new Error(`HostProvider's provide prop selects "${name}" more than once`);
+        selected.add(name);
+    }
+    return [...selected];
+}
+const hookNames = {
+    theme: "useHostTheme",
+    surfaceSize: "useSurfaceSize",
+    pointerPosition: "usePointerPosition"
+};

package/dist/live-snapshot.d.ts

@@ -0,0 +1,18 @@
+import type { Cleanup } from "@phreshos/client";
+/** One explicitly requested snapshot followed by only future live changes. */
+export default class LiveSnapshot<Value> {
+    private readonly read;
+    private readonly subscribeSource;
+    private readonly listeners;
+    private value;
+    private stopSource;
+    private generation;
+    private revision;
+    constructor(read: () => Promise<Value>, subscribeSource: (subscriber: (value: Value) => void) => Cleanup);
+    readonly snapshot: () => Value;
+    readonly subscribe: (listener: () => void) => Cleanup;
+    /** Starts the live subscription before requesting the current snapshot. */
+    start(): Promise<void>;
+    stop(): void;
+    private update;
+}

package/dist/live-snapshot.js

@@ -0,0 +1,59 @@
+const unavailable = Symbol("unavailable");
+/** One explicitly requested snapshot followed by only future live changes. */
+export default class LiveSnapshot {
+    read;
+    subscribeSource;
+    listeners = new Set();
+    value = unavailable;
+    stopSource = null;
+    generation = 0;
+    revision = 0;
+    constructor(read, subscribeSource) {
+        this.read = read;
+        this.subscribeSource = subscribeSource;
+    }
+    snapshot = () => {
+        if (this.value === unavailable)
+            throw new Error("The requested host value is not ready");
+        return this.value;
+    };
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    };
+    /** Starts the live subscription before requesting the current snapshot. */
+    async start() {
+        this.stop();
+        this.value = unavailable;
+        const generation = this.generation;
+        this.stopSource = this.subscribeSource(value => {
+            if (this.generation !== generation)
+                return;
+            this.revision++;
+            this.update(value);
+        });
+        const requestedAt = this.revision;
+        try {
+            const value = await this.read();
+            if (this.generation === generation && this.revision === requestedAt)
+                this.update(value);
+        }
+        catch (error) {
+            if (this.generation === generation && this.revision === requestedAt)
+                throw error;
+        }
+    }
+    stop() {
+        this.generation++;
+        this.revision = 0;
+        this.stopSource?.();
+        this.stopSource = null;
+    }
+    update(value) {
+        if (Object.is(this.value, value))
+            return;
+        this.value = value;
+        for (const listener of this.listeners)
+            listener();
+    }
+}

package/dist/live-state.d.ts

@@ -0,0 +1,24 @@
+import type { Cleanup } from "@phreshos/client";
+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. */
+export default class LiveState<State> {
+    private readonly read;
+    private readonly follow;
+    private readonly listeners;
+    private value;
+    private error;
+    private stopSource;
+    private pending;
+    private generation;
+    private active;
+    constructor(read: () => Promise<State>, follow: StateFollower<State>);
+    readonly snapshot: () => State | undefined;
+    readonly subscribe: (listener: () => void) => Cleanup;
+    private start;
+    private stop;
+    private fail;
+    private update;
+    private notify;
+}
+export declare function combineCleanups(...cleanups: Cleanup[]): Cleanup;

package/dist/live-state.js

@@ -0,0 +1,95 @@
+const noError = Symbol("no-error");
+/** One mounted React snapshot composed from an explicit read and future events. */
+export default class LiveState {
+    read;
+    follow;
+    listeners = new Set();
+    value;
+    error = noError;
+    stopSource = null;
+    pending = [];
+    generation = 0;
+    active = false;
+    constructor(read, follow) {
+        this.read = read;
+        this.follow = follow;
+    }
+    snapshot = () => {
+        if (this.error !== noError)
+            throw this.error;
+        return this.value;
+    };
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        if (!this.active)
+            this.start();
+        return () => {
+            this.listeners.delete(listener);
+            if (this.listeners.size === 0)
+                this.stop();
+        };
+    };
+    start() {
+        this.active = true;
+        this.value = undefined;
+        this.error = noError;
+        this.pending = [];
+        const generation = ++this.generation;
+        try {
+            this.stopSource = this.follow(reducer => {
+                if (this.generation !== generation)
+                    return;
+                if (this.value === undefined)
+                    this.pending.push(reducer);
+                else
+                    this.update(reducer(this.value));
+            });
+        }
+        catch (error) {
+            this.fail(generation, error);
+            return;
+        }
+        void this.read().then(value => {
+            if (this.generation !== generation)
+                return;
+            for (const reducer of this.pending)
+                value = reducer(value);
+            this.pending = [];
+            this.update(value);
+        }, error => this.fail(generation, error));
+    }
+    stop() {
+        this.active = false;
+        this.generation++;
+        this.stopSource?.();
+        this.stopSource = null;
+        this.pending = [];
+        this.value = undefined;
+        this.error = noError;
+    }
+    fail(generation, error) {
+        if (this.generation !== generation)
+            return;
+        this.stopSource?.();
+        this.stopSource = null;
+        this.pending = [];
+        this.error = error;
+        this.notify();
+    }
+    update(value) {
+        if (Object.is(this.value, value))
+            return;
+        this.value = value;
+        this.notify();
+    }
+    notify() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+export function combineCleanups(...cleanups) {
+    return () => {
+        for (const cleanup of cleanups)
+            cleanup();
+    };
+}

package/dist/main.d.ts

@@ -1,5 +1,11 @@
-export { default as CurrentProvider, useParent, useProcess, useProgram, useWindow, type CurrentProviderProperties } from "./current-provider.js";
+export { default as CurrentProvider, useParent, useProcess, useProgram, type CurrentProvision, type CurrentProvisionName, type CurrentProviderProperties } from "./current-provider.js";
+export { default as HostProvider, usePointerPosition, useSurfaceSize, useHostTheme, type HostProvision, type HostProvisionName, type HostProviderProperties } from "./host-provider.js";
 export { default as useSubscribe } from "./use-subscribe.js";
 export { default as useObserve } from "./use-observe.js";
+export { default as useScale } from "./use-scale.js";
+export { default as useColor } from "./use-color.js";
+export { default as useProgramState, type ProgramState } from "./use-program-state.js";
+export { default as useProcessState, type ProcessState } from "./use-process-state.js";
+export { default as useWindowState } from "./use-window-state.js";
 export { default as useObserveAsks, type AskObservable } from "./use-observe-asks.js";
 export { default as useObserveAnswers, type AnswerObservable } from "./use-observe-answers.js";

package/dist/main.js

@@ -1,5 +1,11 @@
-export { default as CurrentProvider, useParent, useProcess, useProgram, useWindow } from "./current-provider.js";
+export { default as CurrentProvider, useParent, useProcess, useProgram } from "./current-provider.js";
+export { default as HostProvider, usePointerPosition, useSurfaceSize, useHostTheme } from "./host-provider.js";
 export { default as useSubscribe } from "./use-subscribe.js";
 export { default as useObserve } from "./use-observe.js";
+export { default as useScale } from "./use-scale.js";
+export { default as useColor } from "./use-color.js";
+export { default as useProgramState } from "./use-program-state.js";
+export { default as useProcessState } from "./use-process-state.js";
+export { default as useWindowState } from "./use-window-state.js";
 export { default as useObserveAsks } from "./use-observe-asks.js";
 export { default as useObserveAnswers } from "./use-observe-answers.js";

package/dist/use-color.d.ts

@@ -0,0 +1,3 @@
+import { type ColorScale } from "@phreshos/core";
+/** Returns the complete color scale derived from one explicit CSS color. */
+export default function useColor(value: string): ColorScale;

package/dist/use-color.js

@@ -0,0 +1,6 @@
+import { useMemo } from "react";
+import { color } from "@phreshos/core";
+/** Returns the complete color scale derived from one explicit CSS color. */
+export default function useColor(value) {
+    return useMemo(() => color(value), [value]);
+}

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

@@ -1,6 +1,7 @@
 import type { AnswerCapture, AnswerObserver, Cleanup } from "@phreshos/client";
 /** Any Server traffic surface capable of observing its outgoing answers. */
 export type AnswerObservable = Readonly<{
+    /** Observes answers sent by the target Server and returns its cleanup. */
     observeAnswers<Result = unknown>(observer: AnswerObserver<Result>): Cleanup;
 }>;
 /**

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

@@ -1,6 +1,7 @@
 import type { AskCapture, AskObserver, Cleanup } from "@phreshos/client";
 /** Any Endpoint traffic surface capable of observing its outgoing questions. */
 export type AskObservable = Readonly<{
+    /** Observes questions sent by the target Endpoint and returns its cleanup. */
     observeAsks<Payload = unknown>(observer: AskObserver<Payload>): Cleanup;
 }>;
 /**

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

@@ -0,0 +1,9 @@
+import type { Process } from "@phreshos/client";
+/** Mutable lifecycle state of one Process and its Endpoint incarnations. */
+export type ProcessState = Readonly<{
+    exited: boolean;
+    serverExists: boolean;
+    clientExists: boolean;
+}>;
+/** Explicitly reads and follows one Process while this hook is mounted. */
+export default function useProcessState(process: Process): ProcessState | undefined;

package/dist/use-process-state.js

@@ -0,0 +1,23 @@
+import { useMemo, useSyncExternalStore } from "react";
+import LiveState, { combineCleanups } from "./live-state.js";
+/** Explicitly reads and follows one Process while this hook is mounted. */
+export default function useProcessState(process) {
+    const state = useMemo(() => new LiveState(async () => {
+        const [exited, serverExists, clientExists] = await Promise.all([
+            process.exited(),
+            process.server.exists(),
+            process.client.exists()
+        ]);
+        return { exited, serverExists, clientExists };
+    }, reduce => combineCleanups(process.subscribe("endpointStart", endpoint => reduce(current => endpointPresence(current, process, endpoint, true))), process.subscribe("endpointStop", endpoint => reduce(current => endpointPresence(current, process, endpoint, false))), process.subscribe("exit", () => reduce(current => ({ ...current, exited: true, serverExists: false, clientExists: false }))))), [process]);
+    return useSyncExternalStore(state.subscribe, state.snapshot, state.snapshot);
+}
+function endpointPresence(state, process, endpoint, exists) {
+    if (endpoint === process.server) {
+        return state.serverExists === exists ? state : { ...state, serverExists: exists };
+    }
+    if (endpoint === process.client) {
+        return state.clientExists === exists ? state : { ...state, clientExists: exists };
+    }
+    return state;
+}

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

@@ -0,0 +1,8 @@
+import type { Process, Program } from "@phreshos/client";
+/** Mutable runtime state derived from one Program's reads and live events. */
+export type ProgramState = Readonly<{
+    installed: boolean;
+    processes: readonly Process[];
+}>;
+/** Explicitly reads and follows one Program while this hook is mounted. */
+export default function useProgramState(program: Program): ProgramState | undefined;

package/dist/use-program-state.js

@@ -0,0 +1,22 @@
+import { useMemo, useSyncExternalStore } from "react";
+import LiveState, { combineCleanups } from "./live-state.js";
+/** Explicitly reads and follows one Program while this hook is mounted. */
+export default function useProgramState(program) {
+    const state = useMemo(() => new LiveState(async () => {
+        const [installed, processes] = await Promise.all([
+            program.installed(),
+            program.processes()
+        ]);
+        return { installed, processes };
+    }, reduce => combineCleanups(program.subscribe("processCreate", process => reduce(current => addProcess(current, process))), program.subscribe("processExit", ({ process }) => reduce(current => removeProcess(current, process))), program.subscribe("uninstall", () => reduce(current => current.installed ? { ...current, installed: false } : current)))), [program]);
+    return useSyncExternalStore(state.subscribe, state.snapshot, state.snapshot);
+}
+function addProcess(state, process) {
+    if (state.processes.includes(process))
+        return state;
+    return { ...state, processes: [...state.processes, process] };
+}
+function removeProcess(state, process) {
+    const processes = state.processes.filter(candidate => candidate !== process);
+    return processes.length === state.processes.length ? state : { ...state, processes };
+}

package/dist/use-scale.d.ts

@@ -0,0 +1,3 @@
+import { type NumericScale } from "@phreshos/core";
+/** Returns the complete visual scale derived from one explicit numeric value. */
+export default function useScale(value: number): NumericScale;

package/dist/use-scale.js

@@ -0,0 +1,6 @@
+import { useMemo } from "react";
+import { numericScale } from "@phreshos/core";
+/** Returns the complete visual scale derived from one explicit numeric value. */
+export default function useScale(value) {
+    return useMemo(() => numericScale(value), [value]);
+}

package/dist/use-subscribe.d.ts

@@ -1,4 +1,4 @@
-import type { EventMessage, EventName, Subscribable } from "@phreshos/client";
+import type { Channel, ChannelMessage, Endpoint, EventMessage, EventName, Subscribable, SubscribableEvents, SubscribableFallback } from "@phreshos/client";
 type OpenEvent = string & {};
 type AvailableEvent<Events extends object, Fallback> = EventName<Events> | ([Fallback] extends [never] ? never : OpenEvent);
 type CompatibleEvent<Events extends object, Fallback, Narrowed> = {
@@ -6,12 +6,22 @@ type CompatibleEvent<Events extends object, Fallback, Narrowed> = {
 }[EventName<Events>] | ([
     Fallback
 ] extends [never] ? never : Narrowed extends Fallback ? OpenEvent : never);
+type SubscribableTarget = Readonly<{
+    subscribe: unknown;
+}>;
+type TargetEvent<Target> = AvailableEvent<SubscribableEvents<Target>, SubscribableFallback<Target>>;
+type TargetMessage<Target, Event extends string> = EventMessage<SubscribableEvents<Target>, SubscribableFallback<Target>, Event>;
 /**
- * Subscribes while mounted and retains the latest projected result.
+ * Subscribes while mounted and retains the latest message or projected result.
  *
  * The target supplies known message types. An explicit generic or callback
  * annotation may narrow that type, but cannot replace it incompatibly.
  */
+export default function useSubscribe<Target extends SubscribableTarget, Event extends TargetEvent<Target>>(target: Target, event: Event): TargetMessage<Target, Event> | undefined;
+export default function useSubscribe<Narrowed = unknown>(target: Endpoint, event: string): Narrowed | undefined;
+export default function useSubscribe<Narrowed extends ChannelMessage<unknown> = ChannelMessage<unknown>>(target: Channel, event: string): Narrowed | undefined;
+export default function useSubscribe<Target extends SubscribableTarget, Event extends TargetEvent<Target>, Result>(target: Target, event: Event, project: (message: TargetMessage<Target, Event>) => Result): Awaited<Result> | undefined;
+export default function useSubscribe<Narrowed, Result = unknown>(target: Endpoint, event: string, project: (message: Narrowed) => Result): Awaited<Result> | undefined;
+export default function useSubscribe<Narrowed extends ChannelMessage<unknown>, Result = unknown>(target: Channel, event: string, project: (message: Narrowed) => Result): Awaited<Result> | undefined;
 export default function useSubscribe<Narrowed, Events extends object, Fallback, Result>(target: Subscribable<Events, Fallback>, event: CompatibleEvent<Events, Fallback, Narrowed>, project: (message: Narrowed) => Result): Awaited<Result> | undefined;
-export default function useSubscribe<Events extends object, Fallback, Event extends AvailableEvent<Events, Fallback>, Result>(target: Subscribable<Events, Fallback>, event: Event, project: (message: EventMessage<Events, Fallback, Event>) => Result): Awaited<Result> | undefined;
 export {};

package/dist/use-subscribe.js

@@ -5,5 +5,8 @@ export default function useSubscribe(target, event, project) {
         const subscribe = target.subscribe;
         return subscribe(event, receive);
     }, [target, event]);
-    return useEventResult(connect, project);
+    return useEventResult(connect, project ?? identity);
+}
+function identity(message) {
+    return message;
 }

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

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

package/dist/use-window-state.js

@@ -0,0 +1,18 @@
+import { useMemo, useSyncExternalStore } from "react";
+import LiveState, { combineCleanups } from "./live-state.js";
+/** Explicitly reads and follows one live Client Window while mounted. */
+export default function useWindowState(window) {
+    const state = useMemo(() => new LiveState(async () => {
+        const [title, position, size, minimized, front, layer, location] = await Promise.all([
+            window.title(),
+            window.position(),
+            window.size(),
+            window.minimized(),
+            window.front(),
+            window.layer(),
+            window.location()
+        ]);
+        return { title, position, size, minimized, front, layer, location };
+    }, reduce => combineCleanups(window.subscribe("move", position => reduce(current => ({ ...current, position }))), window.subscribe("resize", size => reduce(current => ({ ...current, size }))), window.subscribe("minimize", minimized => reduce(current => ({ ...current, minimized }))), window.subscribe("changeTitle", title => reduce(current => ({ ...current, title }))), window.subscribe("front", front => reduce(current => ({ ...current, front }))))), [window]);
+    return useSyncExternalStore(state.subscribe, state.snapshot, state.snapshot);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "React adapters for the Client SDK.",
   "type": "module",
   "main": "dist/main.js",
@@ -13,21 +13,54 @@
   },
   "files": [
     "dist",
+    "LICENSE",
     "README.md"
   ],
+  "author": "Zohayr SLILEH",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PhreshOS/react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PhreshOS/react/issues"
+  },
+  "homepage": "https://github.com/PhreshOS/react#readme",
+  "keywords": [
+    "phreshos",
+    "react",
+    "sdk",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.3.14",
   "scripts": {
-    "check": "tsc --noEmit",
-    "build": "tsc --noEmit false --outDir dist --rootDir source",
-    "prepack": "node --run build"
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "check": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run --environment jsdom",
+    "build": "node --run clean && tsc --noEmit false --outDir dist --rootDir source",
+    "verify:package": "node scripts/verify-package.mjs",
+    "verify": "node --run check && node --run test && node --run build && node --run verify:package",
+    "prepack": "node --run test && node --run build"
   },
   "peerDependencies": {
-    "@phreshos/client": "^0.1.0",
+    "@phreshos/client": "^0.1.2",
+    "@phreshos/core": "^0.1.2",
     "react": "^19.2.0"
   },
   "devDependencies": {
-    "@phreshos/client": "0.1.0",
+    "@phreshos/client": "^0.1.2",
+    "@phreshos/core": "^0.1.2",
+    "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "jsdom": "^30.0.1",
     "react": "^19.2.8",
-    "typescript": "^6.0.3"
+    "react-dom": "^19.2.8",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.1"
   }
 }