@phreshos/react 0.1.12 → 0.1.14

package/README.md

@@ -16,25 +16,25 @@ dependencies.
 
 It provides two kinds of adapter:
 
-- `CurrentProvider` resolves exactly the current values named by its required
+- `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()` and `useObserve()` own persistent ordinary-event
-  registrations for one mounted React consumer.
+- `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.
-- `useObserveAsks()` adapts an Endpoint traffic surface's question observation,
-  while `useObserveAnswers()` adapts a Server traffic surface's answer
-  observation.
+- `useSubscribeAsks()` adapts an Endpoint traffic surface's question
+  subscription, while `useSubscribeAnswers()` adapts a Server traffic
+  surface's answer subscription.
 
-Window needs no React resolution: `current.window` is already a synchronous,
-silent capability object. `CurrentProvider` therefore has no `window` selection
+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
@@ -73,15 +73,20 @@ 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.
-`useSubscribe()` may omit that callback; its default projector is
-`message => message`, so the hook retains the latest message unchanged.
+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:
 
 ```tsx
 import { system } from "@phreshos/client"
 import { useSubscribe } from "@phreshos/react"
 
 const desktop = useSubscribe(system.desktop, "resize")
+
+const latest = useSubscribe(system.desktop, capture => {
+  if (capture.event === "resize") return capture.message
+})
 ```
 
 System reads are asynchronous while subscriptions are live-only. `SystemProvider`
@@ -116,9 +121,9 @@ communicates its effective scheme through the Client iframe, while each Client
 HTML document declares which schemes it supports.
 
 ```tsx
-import { current } from "@phreshos/client"
+import { context } from "@phreshos/client"
 import {
-  CurrentProvider,
+  ContextProvider,
   useProgram,
   useSubscribe
 } from "@phreshos/react"
@@ -126,7 +131,7 @@ import {
 function Counter() {
   const program = useProgram()
 
-  const count = useSubscribe(current, "count", message => {
+  const count = useSubscribe(context, "count", message => {
     return Number(message.payload)
   })
 
@@ -135,14 +140,14 @@ function Counter() {
 
 export default function App() {
   return (
-    <CurrentProvider provide={["program"]} fallback={<p>Loading…</p>} waitServer>
+    <ContextProvider provide={["program"]} fallback={<p>Loading…</p>} waitServer>
       <Counter />
-    </CurrentProvider>
+    </ContextProvider>
   )
 }
 ```
 
-Using a current or system hook outside its provider, or without selecting its
+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.

package/dist/{current-provider.d.ts → context-provider.d.ts}

@@ -1,34 +1,34 @@
 import { type ReactNode } from "react";
 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>;
+/** 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 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 selected current handle has resolved. */
+/** Values that ContextProvider can resolve. */
+export type ContextProvisionName = typeof provisionNames[number];
+/** Required non-empty selection of runtime values. */
+export type ContextProvision = readonly [ContextProvisionName, ...ContextProvisionName[]];
+/** Properties accepted by ContextProvider. */
+export interface ContextProviderProperties {
+    /** Content rendered after every selected runtime handle has resolved. */
     readonly children: ReactNode;
     /** Content rendered while selected handles or optional Server readiness resolve. */
     readonly fallback?: ReactNode;
-    /** Exact current values made available to descendant hooks. */
-    readonly provide: CurrentProvision;
+    /** 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 SelectedCurrentProviderProperties = Omit<CurrentProviderProperties, "provide" | "waitServer"> & Readonly<{
-    selection: readonly CurrentProvisionName[];
+type SelectedContextProviderProperties = Omit<ContextProviderProperties, "provide" | "waitServer"> & Readonly<{
+    selection: readonly ContextProvisionName[];
     waitServer: boolean | number;
 }>;
 export {};

package/dist/{current-provider.js → context-provider.js}

@@ -1,13 +1,13 @@
 import { createContext, createElement, useContext, useEffect, useMemo, useState } from "react";
-import { current } from "@phreshos/client";
+import { context } from "@phreshos/client";
 const provisionNames = ["program", "process", "parent"];
-const CurrentContext = createContext(null);
-/** Resolves only the current handles explicitly selected by the program. */
-export default function CurrentProvider({ children, fallback = null, provide, waitServer = false }) {
+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(SelectedCurrentProvider, {
+    return createElement(SelectedContextProvider, {
         children,
         fallback,
         key: `${selectionKey}\0${String(waitServer)}`,
@@ -15,12 +15,12 @@ export default function CurrentProvider({ children, fallback = null, provide, wa
         waitServer
     });
 }
-function SelectedCurrentProvider({ children, fallback, selection, waitServer }) {
+function SelectedContextProvider({ children, fallback, selection, waitServer }) {
     const [resolution, setResolution] = useState({ status: "pending" });
     useEffect(() => {
         let active = true;
         setResolution({ status: "pending" });
-        void resolveCurrent(selection, waitServer).then(value => {
+        void resolveContext(selection, waitServer).then(value => {
             if (active)
                 setResolution({ status: "ready", value });
         }, error => {
@@ -33,12 +33,12 @@ function SelectedCurrentProvider({ children, fallback, selection, waitServer })
         return fallback;
     if (resolution.status === "error")
         throw resolution.error;
-    return createElement(CurrentContext.Provider, { value: resolution.value }, children);
+    return createElement(RuntimeContext.Provider, { value: resolution.value }, children);
 }
-async function resolveCurrent(selection, waitServer) {
+async function resolveContext(selection, waitServer) {
     const serverReady = typeof waitServer === "number"
-        ? current.server.waitReady(waitServer)
-        : waitServer ? current.server.waitReady() : undefined;
+        ? context.server.waitReady(waitServer)
+        : waitServer ? context.server.waitReady() : undefined;
     const [entries] = await Promise.all([
         Promise.all(selection.map(resolveProvision)),
         serverReady
@@ -50,9 +50,9 @@ async function resolveCurrent(selection, waitServer) {
 }
 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()];
+        case "program": return [name, await context.program()];
+        case "process": return [name, await context.process()];
+        case "parent": return [name, await context.parent()];
     }
 }
 /** Returns the current Program selected by the nearest provider. */
@@ -68,22 +68,22 @@ export function useParent() {
     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];
+    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("CurrentProvider's provide prop must select at least one current value");
+        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(`CurrentProvider cannot provide "${String(name)}"`);
+            throw new Error(`ContextProvider cannot provide "${String(name)}"`);
         if (selected.has(name))
-            throw new Error(`CurrentProvider's provide prop selects "${name}" more than once`);
+            throw new Error(`ContextProvider's provide prop selects "${name}" more than once`);
         selected.add(name);
     }
     return [...selected];

package/dist/main.d.ts

@@ -1,10 +1,9 @@
-export { default as CurrentProvider, useParent, useProcess, useProgram, type CurrentProvision, type CurrentProvisionName, type CurrentProviderProperties } from "./current-provider.js";
+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 useSubscribe } from "./use-subscribe.js";
-export { default as useObserve } from "./use-observe.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 useServiceState, type ServiceState } from "./use-service-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";
+export { default as useSubscribeAsks, type AskSubscribable } from "./use-subscribe-asks.js";
+export { default as useSubscribeAnswers, type AnswerSubscribable } from "./use-subscribe-answers.js";

package/dist/main.js

@@ -1,10 +1,9 @@
-export { default as CurrentProvider, useParent, useProcess, useProgram } from "./current-provider.js";
+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 useSubscribe } from "./use-subscribe.js";
-export { default as useObserve } from "./use-observe.js";
 export { default as useProgramState } from "./use-program-state.js";
 export { default as useProcessState } from "./use-process-state.js";
 export { default as useServiceState } from "./use-service-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";
+export { default as useSubscribeAsks } from "./use-subscribe-asks.js";
+export { default as useSubscribeAnswers } from "./use-subscribe-answers.js";

package/dist/use-service-state.js

@@ -2,7 +2,7 @@ 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.subscribe("enable", () => reduce(current => setEnabled(current, true))), service.subscribe("disable", () => reduce(current => setEnabled(current, false))))), [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]);
     return useSyncExternalStore(state.subscribe, state.snapshot, state.snapshot);
 }
 function setEnabled(state, enabled) {

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

@@ -0,0 +1,8 @@
+import type { AnswerCapture, AnswerSubscriber, Cleanup } from "@phreshos/client";
+/** 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. */
+    subscribeAnswers<Result = unknown>(subscriber: AnswerSubscriber<Result>): Cleanup;
+}>;
+/** Subscribes to outgoing answers while mounted and retains the latest projection. */
+export default function useSubscribeAnswers<Answer, Result>(target: AnswerSubscribable, project: (capture: AnswerCapture<Answer>) => Result): Awaited<Result> | undefined;

package/dist/use-subscribe-answers.js

@@ -0,0 +1,7 @@
+import { useCallback } from "react";
+import useEventResult from "./event-result.js";
+/** Subscribes to outgoing answers while mounted and retains the latest projection. */
+export default function useSubscribeAnswers(target, project) {
+    const connect = useCallback((receive) => target.subscribeAnswers(receive), [target]);
+    return useEventResult(connect, project);
+}

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

@@ -0,0 +1,8 @@
+import type { AskCapture, AskSubscriber, Cleanup } from "@phreshos/client";
+/** 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. */
+    subscribeAsks<Payload = unknown>(subscriber: AskSubscriber<Payload>): Cleanup;
+}>;
+/** Subscribes to outgoing questions while mounted and retains the latest projection. */
+export default function useSubscribeAsks<Payload, Result>(target: AskSubscribable, project: (capture: AskCapture<Payload>) => Result): Awaited<Result> | undefined;

package/dist/use-subscribe-asks.js

@@ -0,0 +1,7 @@
+import { useCallback } from "react";
+import useEventResult from "./event-result.js";
+/** Subscribes to outgoing questions while mounted and retains the latest projection. */
+export default function useSubscribeAsks(target, project) {
+    const connect = useCallback((receive) => target.subscribeAsks(receive), [target]);
+    return useEventResult(connect, project);
+}

package/dist/use-subscribe.d.ts

@@ -1,4 +1,4 @@
-import type { Channel, ChannelMessage, Endpoint, EventMessage, EventName, Subscribable, SubscribableEvents, SubscribableFallback } from "@phreshos/client";
+import type { Captures, Context, ContextMessage, 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> = {
@@ -11,17 +11,16 @@ type SubscribableTarget = Readonly<{
 }>;
 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 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.
- */
+type TargetCapture<Target> = Captures<SubscribableEvents<Target>, SubscribableFallback<Target>>;
+/** Subscribes while mounted and retains the latest named message. */
 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<Narrowed extends ContextMessage<unknown> = ContextMessage<unknown>>(target: Context, event: string): Narrowed | undefined;
+/** Subscribes while mounted and retains the latest projected named message. */
 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 extends ContextMessage<unknown>, Result = unknown>(target: Context, 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;
+/** Subscribes across every event and retains the latest projected capture. */
+export default function useSubscribe<Target extends SubscribableTarget, Result>(target: Target, project: (capture: TargetCapture<Target>) => Result): Awaited<Result> | undefined;
 export {};

package/dist/use-subscribe.js

@@ -1,11 +1,17 @@
 import { useCallback } from "react";
 import useEventResult from "./event-result.js";
-export default function useSubscribe(target, event, project) {
+export default function useSubscribe(target, eventOrProject, namedProject) {
+    const event = typeof eventOrProject === "string" ? eventOrProject : null;
     const connect = useCallback((receive) => {
+        if (event === null) {
+            const subscribe = target.subscribe;
+            return subscribe(receive);
+        }
         const subscribe = target.subscribe;
         return subscribe(event, receive);
     }, [target, event]);
-    return useEventResult(connect, project ?? identity);
+    const project = event === null ? eventOrProject : namedProject ?? identity;
+    return useEventResult(connect, project);
 }
 function identity(message) {
     return message;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "React adapters for the Client SDK.",
   "type": "module",
   "main": "dist/main.js",
@@ -47,13 +47,13 @@
     "prepack": "node --run test && node --run build"
   },
   "peerDependencies": {
-    "@phreshos/client": "^0.1.24",
-    "@phreshos/core": "^0.1.24",
+    "@phreshos/client": "^0.1.26",
+    "@phreshos/core": "^0.1.26",
     "react": "^19.2.0"
   },
   "devDependencies": {
-    "@phreshos/client": "^0.1.24",
-    "@phreshos/core": "^0.1.24",
+    "@phreshos/client": "^0.1.26",
+    "@phreshos/core": "^0.1.26",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",

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

@@ -1,11 +0,0 @@
-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;
-}>;
-/**
- * Observes answers in one Server's traffic while mounted and retains the
- * latest projected result.
- */
-export default function useObserveAnswers<Answer, Result>(target: AnswerObservable, project: (capture: AnswerCapture<Answer>) => Result): Awaited<Result> | undefined;

package/dist/use-observe-answers.js

@@ -1,10 +0,0 @@
-import { useCallback } from "react";
-import useEventResult from "./event-result.js";
-/**
- * Observes answers in one Server's traffic while mounted and retains the
- * latest projected result.
- */
-export default function useObserveAnswers(target, project) {
-    const connect = useCallback((receive) => target.observeAnswers(receive), [target]);
-    return useEventResult(connect, project);
-}

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

@@ -1,11 +0,0 @@
-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;
-}>;
-/**
- * Observes questions in one Endpoint's traffic while mounted and retains the
- * latest projected result.
- */
-export default function useObserveAsks<Payload, Result>(target: AskObservable, project: (capture: AskCapture<Payload>) => Result): Awaited<Result> | undefined;

package/dist/use-observe-asks.js

@@ -1,10 +0,0 @@
-import { useCallback } from "react";
-import useEventResult from "./event-result.js";
-/**
- * Observes questions in one Endpoint's traffic while mounted and retains the
- * latest projected result.
- */
-export default function useObserveAsks(target, project) {
-    const connect = useCallback((receive) => target.observeAsks(receive), [target]);
-    return useEventResult(connect, project);
-}

package/dist/use-observe.d.ts

@@ -1,3 +0,0 @@
-import type { Captures, Subscribable } from "@phreshos/client";
-/** Observes all events while mounted and retains the latest projected result. */
-export default function useObserve<Events extends object, Fallback, Result>(target: Subscribable<Events, Fallback>, project: (capture: Captures<Events, Fallback>) => Result): Awaited<Result> | undefined;

package/dist/use-observe.js

@@ -1,7 +0,0 @@
-import { useCallback } from "react";
-import useEventResult from "./event-result.js";
-/** Observes all events while mounted and retains the latest projected result. */
-export default function useObserve(target, project) {
-    const connect = useCallback((receive) => target.observe(receive), [target]);
-    return useEventResult(connect, project);
-}