@phreshos/react 0.1.13 → 0.1.15

package/README.md

@@ -23,15 +23,15 @@ It provides two kinds of adapter:
   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: `context.window` is already a synchronous,
 silent capability object. `ContextProvider` therefore has no `window` selection
@@ -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`

package/dist/main.d.ts

@@ -1,10 +1,9 @@
 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 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-process-state.js

@@ -9,15 +9,6 @@ export default function useProcessState(process) {
             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]);
+    }, reduce => combineCleanups(process.server.lifecycle.subscribe("start", () => reduce(current => current.serverExists ? current : { ...current, serverExists: true })), process.server.lifecycle.subscribe("stop", () => reduce(current => current.serverExists ? { ...current, serverExists: false } : current)), process.client.lifecycle.subscribe("start", () => reduce(current => current.clientExists ? current : { ...current, clientExists: true })), process.client.lifecycle.subscribe("stop", () => reduce(current => current.clientExists ? { ...current, clientExists: false } : current)), 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-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.13",
+  "version": "0.1.15",
   "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.25",
-    "@phreshos/core": "^0.1.24",
+    "@phreshos/client": "^0.1.27",
+    "@phreshos/core": "^0.1.27",
     "react": "^19.2.0"
   },
   "devDependencies": {
-    "@phreshos/client": "^0.1.25",
-    "@phreshos/core": "^0.1.24",
+    "@phreshos/client": "^0.1.27",
+    "@phreshos/core": "^0.1.27",
     "@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);
-}