@phreshos/react 0.1.32 → 0.1.34

package/dist/context-provider.d.ts

@@ -12,6 +12,8 @@ export default function ContextProvider({ children, context, fallback }: Context
 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

@@ -22,6 +22,13 @@ export function useContext() {
 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/desktop-provider.d.ts

@@ -1,16 +1,16 @@
 import { type ReactNode } from "react";
-import type { Connection, Desktop, DesktopPreferences, DesktopViewportSnapshot } from "@phreshos/core";
+import type { Connection, Desktop, DesktopPreferences, DesktopViewportState } from "@phreshos/core";
 import LiveSnapshot from "./live-snapshot.js";
 /** Provides one complete Client Desktop environment to a React tree. */
 export default function DesktopProvider({ children, desktop, fallback }: DesktopProviderProperties): 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<{
     desktop: Desktop;
-    viewport: LiveSnapshot<DesktopViewportSnapshot>;
+    viewport: LiveSnapshot<DesktopViewportState>;
     preferences: LiveSnapshot<DesktopPreferences>;
 }> | null>> | null;
 /** Returns the complete Desktop supplied by the nearest provider. */
 export declare function useDesktop(): Desktop;
-/** Resolves and follows the current Desktop viewport. */
-export declare function useDesktopViewport(): DesktopViewportSnapshot;
+/** Resolves and follows the current Desktop viewport: its size and its offset together. */
+export declare function useDesktopViewport(): DesktopViewportState;
 /** Resolves and follows the effective Desktop preferences. */
 export declare function useDesktopPreferences(): DesktopPreferences;
 /** Resolves the browser Connection carrying this Desktop when explicitly used. */

package/dist/desktop-provider.js

@@ -7,7 +7,7 @@ const DesktopContext = createContext(null);
 export default function DesktopProvider({ children, desktop, fallback = null }) {
     const value = useMemo(() => ({
         desktop,
-        viewport: new LiveSnapshot(() => desktop.viewport.snapshot(), subscriber => desktop.viewport.subscribe("resize", subscriber)),
+        viewport: viewportState(desktop),
         preferences: new LiveSnapshot(() => desktop.preferences.snapshot(), subscriber => desktop.preferences.subscribe("change", subscriber))
     }), [desktop]);
     const stores = useMemo(() => [value.viewport, value.preferences], [value]);
@@ -18,7 +18,7 @@ export default function DesktopProvider({ children, desktop, fallback = null })
 export function useDesktop() {
     return useValue().desktop;
 }
-/** Resolves and follows the current Desktop viewport. */
+/** Resolves and follows the current Desktop viewport: its size and its offset together. */
 export function useDesktopViewport() {
     const store = useValue().viewport;
     return useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot);
@@ -40,3 +40,19 @@ function useValue() {
         throw new Error("useDesktop must be used inside DesktopProvider");
     return value;
 }
+/** One state from the viewport's two values: each event replaces its own value and keeps the other. */
+function viewportState(desktop) {
+    let latest = {};
+    const complete = () => latest.size && latest.offset ? Object.freeze({ size: latest.size, offset: latest.offset }) : null;
+    return new LiveSnapshot(async () => {
+        const [size, offset] = await Promise.all([desktop.viewport.size(), desktop.viewport.offset()]);
+        latest = { size, offset };
+        return complete();
+    }, subscriber => {
+        const publish = () => { const state = complete(); if (state)
+            subscriber(state); };
+        const stopResize = desktop.viewport.subscribe("resize", size => { latest = { ...latest, size }; publish(); });
+        const stopMove = desktop.viewport.subscribe("move", offset => { latest = { ...latest, offset }; publish(); });
+        return () => { stopResize(); stopMove(); };
+    });
+}

package/dist/main.d.ts

@@ -10,5 +10,6 @@ export { default as useEndpointState, type EndpointState } from "./use-endpoint-
 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

@@ -10,5 +10,6 @@ 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-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.32",
+  "version": "0.1.34",
   "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.62",
+    "@phreshos/core": "^0.1.64",
     "react": "^19.2.0"
   },
   "devDependencies": {
-        "@phreshos/core": "^0.1.62",
+    "@phreshos/core": "^0.1.64",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.18",