@phreshos/react 0.1.31 → 0.1.33

package/dist/context-provider.d.ts

@@ -10,6 +10,10 @@ export default function ContextProvider({ children, context, fallback }: Context
 }> | null>> | null;
 /** Returns the complete Client Context supplied by the nearest provider. */
 export declare function useContext(): ClientContext;
+/** Read the current Context when present; explicit-handle hooks also work without it. */
+export declare function useProvidedContext(): ClientContext | null;
+/** Resolve the current Program without requiring a provider for explicit-handle hooks. */
+export declare function useProvidedProgram(): Program | undefined;
 /** Returns the current Program once it resolves. */
 export declare function useProgram<Handle extends Program = Program>(): Handle;
 /** Returns the current Process once it resolves. */

package/dist/context-provider.js

@@ -18,6 +18,17 @@ export default function ContextProvider({ children, context, fallback = null })
 export function useContext() {
     return useValue().context;
 }
+/** Read the current Context when present; explicit-handle hooks also work without it. */
+export function useProvidedContext() {
+    return useReactContext(CurrentContext)?.context ?? null;
+}
+/** Resolve the current Program without requiring a provider for explicit-handle hooks. */
+export function useProvidedProgram() {
+    const value = useReactContext(CurrentContext);
+    return useSyncExternalStore(value?.program.subscribe ?? noSubscribe, value?.program.snapshot ?? noProgram, value?.program.snapshot ?? noProgram);
+}
+function noSubscribe() { return () => undefined; }
+function noProgram() { return undefined; }
 /** Returns the current Program once it resolves. */
 export function useProgram() {
     return useResolved(useValue().program);

package/dist/main.d.ts

@@ -9,5 +9,7 @@ export { default as useSessionState, type SessionState } from "./use-session-sta
 export { default as useEndpointState, type EndpointState } from "./use-endpoint-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 useClientMemory } from "./use-client-memory.js";
+export { default as useProgramStore } from "./use-program-store.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

@@ -9,5 +9,7 @@ export { default as useSessionState } from "./use-session-state.js";
 export { default as useEndpointState } from "./use-endpoint-state.js";
 export { default as useServiceState } from "./use-service-state.js";
 export { default as useWindowState } from "./use-window-state.js";
+export { default as useClientMemory } from "./use-client-memory.js";
+export { default as useProgramStore } from "./use-program-store.js";
 export { default as useSubscribeAsks } from "./use-subscribe-asks.js";
 export { default as useSubscribeAnswers } from "./use-subscribe-answers.js";

package/dist/use-client-memory.d.ts

@@ -0,0 +1,7 @@
+import type { ClientMemory, JsonValue } from "@phreshos/core";
+type Widen<Value extends JsonValue> = Value extends string ? string : Value extends number ? number : Value extends boolean ? boolean : Value;
+type MemoryResult<Value extends JsonValue> = readonly [Value | undefined, (next: Value | ((current: Value | undefined) => Value)) => Promise<void>];
+/** Reads the current Client's memory, or an explicitly supplied Client memory handle. */
+export default function useClientMemory<Value extends JsonValue>(key: string, initial: Value): MemoryResult<Widen<Value>>;
+export default function useClientMemory<Value extends JsonValue>(memory: ClientMemory, key: string, initial: Value): MemoryResult<Widen<Value>>;
+export {};

package/dist/use-client-memory.js

@@ -0,0 +1,21 @@
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { useProvidedContext } from "./context-provider.js";
+import LiveState from "./live-state.js";
+export default function useClientMemory(memoryOrKey, keyOrInitial, explicitInitial) {
+    const context = useProvidedContext();
+    const memory = typeof memoryOrKey === "string" ? context?.memory : memoryOrKey;
+    if (!memory)
+        throw new Error("useClientMemory(key, initial) requires ContextProvider");
+    const key = typeof memoryOrKey === "string" ? memoryOrKey : keyOrInitial;
+    const initial = typeof memoryOrKey === "string" ? keyOrInitial : explicitInitial;
+    // Initial seeds the key, but does not restart its subscription when it changes.
+    const state = useMemo(() => new LiveState(async () => ({ value: await memory.update(key, current => current === undefined ? initial : current) }), reduce => memory.subscribe(key, value => reduce(() => ({ value })))), [memory, key]);
+    const snapshot = useSyncExternalStore(state.subscribe, state.snapshot, state.snapshot);
+    const set = useCallback(async (next) => {
+        if (typeof next === "function")
+            await memory.update(key, next);
+        else
+            await memory.set(key, next);
+    }, [memory, key]);
+    return [snapshot?.value, set];
+}

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

@@ -0,0 +1,7 @@
+import type { ProgramStore } from "@phreshos/core";
+type Widen<Value> = Value extends string ? string : Value extends number ? number : Value extends boolean ? boolean : Value;
+type StoreResult<Value> = readonly [Value | undefined, (next: Value | ((current: Value | undefined) => Value)) => Promise<void>];
+/** Follows one Program-owned persistent value and seeds it only when absent. */
+export default function useProgramStore<Value>(key: string, initial: Value): StoreResult<Widen<Value>>;
+export default function useProgramStore<Value>(store: ProgramStore, key: string, initial: Value): StoreResult<Widen<Value>>;
+export {};

package/dist/use-program-store.js

@@ -0,0 +1,21 @@
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { useProvidedProgram } from "./context-provider.js";
+import LiveState from "./live-state.js";
+export default function useProgramStore(storeOrKey, keyOrInitial, explicitInitial) {
+    const program = useProvidedProgram();
+    const store = typeof storeOrKey === "string" ? program?.store : storeOrKey;
+    if (!store)
+        throw new Error("useProgramStore(key, initial) requires ContextProvider");
+    const key = typeof storeOrKey === "string" ? storeOrKey : keyOrInitial;
+    const initial = typeof storeOrKey === "string" ? keyOrInitial : explicitInitial;
+    // A stored undefined value still occupies a key; only the System can test absence atomically.
+    const state = useMemo(() => new LiveState(async () => ({ value: await store.getOrSet(key, initial) }), reduce => store.subscribe(key, value => reduce(() => ({ value })))), [store, key]);
+    const snapshot = useSyncExternalStore(state.subscribe, state.snapshot, state.snapshot);
+    const set = useCallback(async (next) => {
+        if (typeof next === "function")
+            await store.update(key, next);
+        else
+            await store.set(key, next);
+    }, [store, key]);
+    return [snapshot?.value, set];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Runtime-neutral React adapters for PhreshOS contracts.",
   "type": "module",
   "main": "dist/main.js",
@@ -46,11 +46,11 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-        "@phreshos/core": "^0.1.59",
+    "@phreshos/core": "^0.1.63",
     "react": "^19.2.0"
   },
   "devDependencies": {
-        "@phreshos/core": "^0.1.59",
+    "@phreshos/core": "^0.1.63",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.18",