akanjs 3.0.0-beta.8 → 3.0.0

package/webkit/useDebounce.ts

@@ -2,18 +2,15 @@
 import { useCallback } from "react";
 
 const debounce = <Args extends unknown[], Return>(callback: (...args: Args) => Return, wait = 500) => {
-  
   let timer: NodeJS.Timeout;
   return (...args: Args) => {
     clearTimeout(timer);
-    
     timer = setTimeout(() => {
       callback(...args);
     }, wait);
   };
 };
 
-/** Returns a callback that runs only after calls have stopped for the wait time. */
 export const useDebounce = <Args extends unknown[], Return>(
   callback: (...args: Args) => Return,
   states: unknown[] = [],

package/webkit/useEscapeKey.tsx

@@ -1,14 +1,6 @@
 "use client";
 import { useEffect, useRef } from "react";
 
-/**
- * Escape belongs to the topmost dismissable surface only.
- *
- * A per-component `window` listener cannot know that: every open surface hears the same keydown, so a
- * dialog opened from another dialog took both down at once, and a confirm popover inside a modal would
- * have closed the modal under it. One shared stack keeps the order surfaces actually opened in and
- * hands the key to the last one.
- */
 const stack: (() => void)[] = [];
 
 const onKeyDown = (event: KeyboardEvent) => {
@@ -19,10 +11,7 @@ const onKeyDown = (event: KeyboardEvent) => {
   topmost();
 };
 
-/**
- * Close `onEscape` on Escape while `active`, but only while this surface is the topmost active one.
- * The callback is read through a ref, so a fresh closure per render does not reshuffle the stack.
- */
+/** Calls `onEscape` on Escape while `active` and this surface is the topmost active one. */
 export const useEscapeKey = (active: boolean, onEscape: () => void) => {
   const callbackRef = useRef(onEscape);
   useEffect(() => {

package/webkit/useFetch.ts

@@ -2,22 +2,25 @@
 import { isThenable } from "akanjs/common";
 import { useEffect, useMemo, useState } from "react";
 
-/** Tracks fulfillment state for a promise or immediate value inside a client component. */
 export const useFetch = <Return>(
   fnOrPromise: Promise<Return> | Return,
-  { onError }: { onError?: (err: string) => void } = {},
+  {
+    onError,
+    keepPrevious = false,
+  }: {
+    onError?: (err: string) => void;
+    /** While a new promise is pending, answer the last settled value instead of `null`. */
+    keepPrevious?: boolean;
+  } = {},
 ): { fulfilled: boolean; value: Return | null } => {
-  const [asyncState, setAsyncState] = useState<{ fulfilled: boolean; value: Return | null }>({
-    fulfilled: false,
-    value: null,
-  });
+  const [settled, setSettled] = useState<{ source: unknown; value: Return } | null>(null);
   useEffect(() => {
     if (!isThenable(fnOrPromise)) return;
     let cancelled = false;
     void (async () => {
       try {
         const ret = await fnOrPromise;
-        if (!cancelled) setAsyncState({ fulfilled: true, value: ret });
+        if (!cancelled) setSettled({ source: fnOrPromise, value: ret });
       } catch (err) {
         if (cancelled) return;
         const content = `Error: ${typeof err === "string" ? err : (err as Error).message}`;
@@ -27,18 +30,16 @@ export const useFetch = <Return>(
     return () => {
       cancelled = true;
     };
-  }, []);
+  }, [fnOrPromise]);
   if (!isThenable(fnOrPromise)) {
     return { fulfilled: true, value: fnOrPromise as Return };
   }
-  return asyncState;
+  return settled?.source === fnOrPromise
+    ? { fulfilled: true, value: settled.value }
+    : { fulfilled: false, value: keepPrevious ? (settled?.value ?? null) : null };
 };
 
-/**
- * Like `useFetch`, but takes a factory function that is only called once
- * (or when `deps` change). Prevents duplicate network requests caused by
- * React re-renders.
- */
+/** Calls `factory` once per `deps` change, so a re-render does not start another request. */
 export const useFetchFn = <Return>(
   factory: () => Promise<Return> | Return,
   deps: unknown[] = [],

package/webkit/useFrameRuntime.ts

@@ -44,29 +44,8 @@ export const clonePageState = (pageState: PageState): PageState => ({ ...pageSta
 
 const resolveFrameSlotHeight = (slot: FrameSlotRegistration) => slot.height ?? slot.estimatedHeight ?? 0;
 
-const isInsetLockedByConfig = (_pathRoute: PathRoute, _key: "topInset" | "bottomInset") => {
-
-  return true;
-};
-
 const getLeafLayout = (pathRoute: PathRoute) => pathRoute.renderLayouts.at(-1);
 
-function isSlotEligibleForTarget({
-  sourcePath,
-  targetPath,
-  slot,
-  visiblePaths,
-}: {
-  sourcePath: string;
-  targetPath: string;
-  slot: FrameSlotRegistration;
-  visiblePaths: Set<string>;
-}) {
-  if (visiblePaths.has(sourcePath)) return true;
-  if (sourcePath === targetPath && slot.scope === "layout" && slot.cache) return true;
-  return slot.scope === "layout" && Boolean(slot.cache);
-}
-
 export function getFrameSlotsForPath(
   pathRoute: PathRoute,
   frameSlots: FrameSlotMap,
@@ -77,8 +56,8 @@ export function getFrameSlotsForPath(
   const targetLeafLayout = getLeafLayout(pathRoute);
   return Object.entries(frameSlots).flatMap(([sourcePath, slotsById]) => {
     const sourceRoute = routeByPath.get(sourcePath);
-    const slots = Object.values(slotsById).filter((slot) =>
-      isSlotEligibleForTarget({ sourcePath, targetPath: pathRoute.path, slot, visiblePaths }),
+    const slots = Object.values(slotsById).filter(
+      (slot) => visiblePaths.has(sourcePath) || (slot.scope === "layout" && Boolean(slot.cache)),
     );
     if (sourcePath === pathRoute.path) return slots;
     if (!sourceRoute || !targetLeafLayout || getLeafLayout(sourceRoute) !== targetLeafLayout) return [];
@@ -94,22 +73,8 @@ export function applyFrameSlots(
   visiblePaths: Set<string>,
 ) {
   const slots = getFrameSlotsForPath(pathRoute, frameSlots, pathRoutes, visiblePaths);
-  if (slots.length === 0) return clonePageState(basePageState);
   const pageState = clonePageState(basePageState);
-  if (!isInsetLockedByConfig(pathRoute, "topInset")) {
-    pageState.topInset = Math.max(
-      pageState.topInset,
-      ...slots.filter((slot) => slot.type === "topInset").map(resolveFrameSlotHeight),
-    );
-  }
-  if (!isInsetLockedByConfig(pathRoute, "bottomInset")) {
-    pageState.bottomInset = Math.max(
-      pageState.bottomInset,
-      ...slots.filter((slot) => slot.type === "bottomInset").map(resolveFrameSlotHeight),
-    );
-  }
-  const explicit = pathRoute.explicitPageConfigKeys ?? {};
-  if (!explicit.cache && slots.some((slot) => slot.cache)) pageState.cache = true;
+  if (!pathRoute.explicitPageConfigKeys?.cache && slots.some((slot) => slot.cache)) pageState.cache = true;
   return pageState;
 }
 
@@ -146,8 +111,7 @@ export function useFrameSlots() {
           const nextBucket = { ...prev[bucket] };
           if (Object.keys(nextPathSlots).length > 0) nextBucket[path] = nextPathSlots;
           else delete nextBucket[path];
-          const next = { ...prev, [bucket]: nextBucket };
-          return next;
+          return { ...prev, [bucket]: nextBucket };
         });
       };
     },
@@ -283,7 +247,6 @@ export function hasBottomAnchoredKeyboardSlot(path: string, frameSlots: FrameSlo
 
 export function resolveKeyboardFrame({
   keyboardHeight,
-  bottomSafeArea,
   visualViewportKeyboardHeight,
   platformProfile,
   sticky,
@@ -541,8 +504,7 @@ export function createFrameSnapshot({
 
 const getTransitionDuration = (type: TransitionType) => {
   if (typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches) return 1;
-  if (type === "bottomUp") return 220;
-  if (type === "scaleOut") return 220;
+  if (type === "bottomUp" || type === "scaleOut") return 220;
   if (type === "fade" || type === "stack") return 150;
   return 0;
 };

package/webkit/useGeoLocation.tsx

@@ -1,23 +1,21 @@
 "use client";
-import { loadCapacitorGeolocation } from "akanjs/client/capacitor";
+import { AkanNativeError, loadGeolocation, opener } from "akanjs/client/native";
 
-/** Capacitor geolocation hook with permission checks and current position lookup. */
+/** `getPosition` opens the app settings instead of resolving when location permission is denied. */
 export const useGeoLocation = () => {
-  const checkPermission = async (): Promise<{ geolocation: string; coarseLocation: string }> => {
-    const { Geolocation } = await loadCapacitorGeolocation();
-    const { location: geolocation, coarseLocation } = await Geolocation.requestPermissions();
-    return { geolocation, coarseLocation };
+  const checkPermission = async () => {
+    const { geolocation } = await loadGeolocation();
+    return await geolocation.requestPermission();
   };
 
-  const getPosition = async () => {
-    const { geolocation, coarseLocation } = await checkPermission();
-    if (geolocation === "denied" || coarseLocation === "denied") {
-      location.assign("app-settings:");
-      return;
+  const getPosition = async (options: { enableHighAccuracy?: boolean } = {}) => {
+    const { geolocation } = await loadGeolocation();
+    try {
+      return await geolocation.getCurrentPosition(options);
+    } catch (error) {
+      if (AkanNativeError.from(error).code !== "PERMISSION_DENIED") throw error;
+      await opener.openSettings().catch(() => undefined);
     }
-    const { Geolocation } = await loadCapacitorGeolocation();
-    const coordinates = await Geolocation.getCurrentPosition();
-    return coordinates;
   };
 
   return { checkPermission, getPosition };

package/webkit/useHistory.ts

@@ -16,14 +16,23 @@ interface setBackOptions {
   scrollToTop?: boolean;
 }
 
-export const useHistory = (locations: Location[] = []) => {
+export const useHistory = (
+  locations: Location[] = [],
+  { idx = 0, dormant }: { idx?: number; dormant?: Set<string> } = {},
+) => {
   const history = useRef<History>({
     type: "initial",
     locations,
-    scrollMap: new Map([[window.location.pathname, 0]]),
-    idxMap: new Map([[window.location.pathname, 0]]),
-    cachedLocationMap: new Map(),
-    idx: 0,
+    scrollMap: new Map(locations.map((location) => [location.href, 0])),
+    idxMap: new Map(locations.map((location, idx) => [location.href, idx])),
+    
+    cachedLocationMap: new Map(
+      locations
+        .filter((location) => location.pathRoute.pageState.cache)
+        .map((location) => [location.pathRoute.path, location]),
+    ),
+    idx,
+    ...(dormant ? { dormant } : {}),
   });
   const setHistoryForward = useCallback(({ type, location, scrollTop = 0, scrollToTop = false }: setForwardOptions) => {
     const currentLocation = history.current.locations[history.current.idx] as Location | undefined;
@@ -40,13 +49,20 @@ export const useHistory = (locations: Location[] = []) => {
   }, []);
   const setHistoryBack = useCallback(({ location, scrollTop = 0, scrollToTop = false }: setBackOptions) => {
     const prevLocation = history.current.locations[history.current.idx - 1] as Location | undefined;
-    if (prevLocation && scrollToTop) history.current.scrollMap.set(prevLocation.pathname, 0);
+    if (prevLocation && scrollToTop) history.current.scrollMap.set(prevLocation.href, 0);
     history.current.type = "back";
     history.current.scrollMap.set(location.href, scrollTop);
     history.current.idxMap.set(location.href, history.current.idx);
     if (location.pathRoute.pageState.cache) history.current.cachedLocationMap.set(location.pathRoute.path, location);
     history.current.idx--;
   }, []);
+  
+  const setHistoryJump = useCallback((idx: number, scrollTop = 0) => {
+    const currentLocation = history.current.locations[history.current.idx] as Location | undefined;
+    if (currentLocation) history.current.scrollMap.set(currentLocation.href, scrollTop);
+    history.current.type = idx < history.current.idx ? "back" : "forward";
+    history.current.idx = idx;
+  }, []);
   const getNextLocation = useCallback(() => {
     return (history.current.locations[history.current.idx + 1] ?? null) as Location | null;
   }, []);
@@ -68,6 +84,7 @@ export const useHistory = (locations: Location[] = []) => {
     history,
     setHistoryForward,
     setHistoryBack,
+    setHistoryJump,
     getNextLocation,
     getCurrentLocation,
     getPrevLocation,

package/webkit/useLocation.ts

@@ -1,20 +1,20 @@
 "use client";
 import type { Location, PathRoute, RouteGuide } from "akanjs/client";
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
+import { CsrStack } from "./CsrStack";
 
 interface UseLocationOptions {
   rootRouteGuide: RouteGuide;
 }
 export const useLocation = ({ rootRouteGuide }: UseLocationOptions) => {
+  const routeGuide = useRef(rootRouteGuide);
+  routeGuide.current = rootRouteGuide;
   const getLocation = useCallback((href: string): Location => {
-    const getPathSegments = (pathname: string) => {
-      return [
-        ...pathname
-          .split("/")
-          .filter((pathSegment) => !!pathSegment)
-          .map((pathSegment) => `/${pathSegment}`),
-      ];
-    };
+    const getPathSegments = (pathname: string) =>
+      pathname
+        .split("/")
+        .filter((pathSegment) => !!pathSegment)
+        .map((pathSegment) => `/${pathSegment}`);
     const getPathRoute = (pathname: string): PathRoute => {
       const pathSegments = getPathSegments(pathname);
       const getTargetRouteGuide = (pathSegments: string[], routeGuide: RouteGuide): RouteGuide => {
@@ -31,7 +31,7 @@ export const useLocation = ({ rootRouteGuide }: UseLocationOptions) => {
         if (!childRouteGuide) throw new Error(`Not found: ${pathname}`);
         return getTargetRouteGuide(pathSegments, childRouteGuide);
       };
-      const targetRouteGuide = getTargetRouteGuide(pathSegments, rootRouteGuide);
+      const targetRouteGuide = getTargetRouteGuide(pathSegments, routeGuide.current);
       const pathRoute = targetRouteGuide.pathRoute;
       if (!pathRoute) {
         window.location.assign("/404");
@@ -63,7 +63,7 @@ export const useLocation = ({ rootRouteGuide }: UseLocationOptions) => {
     const pathRoute = getPathRoute(pathname);
     const params = getParams(pathname, pathRoute);
     const searchParams = getSearchParams(search);
-    return { pathname, search, params, searchParams, pathRoute, hash, href };
+    return { pathname, search, params, searchParams, pathRoute, hash, href, entryId: CsrStack.nextEntryId() };
   }, []);
   return { getLocation };
 };

package/webkit/usePageActivity.ts

@@ -0,0 +1,6 @@
+"use client";
+import { pageActivityContext } from "akanjs/client";
+import { useContext } from "react";
+
+/** Where this page stands in the CSR stack. Outside one — SSR, a layout, a plain web page — it is always `current`. */
+export const usePageActivity = () => useContext(pageActivityContext).activity;

package/webkit/usePageFocusEffect.ts

@@ -0,0 +1,13 @@
+"use client";
+import { pageActivityContext } from "akanjs/client";
+import { type DependencyList, type EffectCallback, useContext, useEffect } from "react";
+
+/**
+ * Runs `effect` while the user is on this page, and cleans it up when they leave it — for work a mounted page
+ * must not keep doing out of sight, such as a camera, a poll, or a key binding. A page under the current one stays
+ * mounted for a swipe back, so a plain effect there keeps running.
+ */
+export const usePageFocusEffect = (effect: EffectCallback, deps: DependencyList) => {
+  const { focused } = useContext(pageActivityContext);
+  useEffect(() => (focused ? effect() : undefined), [focused, ...deps]);
+};

package/webkit/usePageLocation.ts

@@ -0,0 +1,17 @@
+"use client";
+import { usePathCtx } from "akanjs/client";
+import { st } from "akanjs/store";
+
+/**
+ * This page's own location. `st.use.searchParams()` and its siblings follow the page on screen, so a page mounted
+ * off it — one being prepared, one kept under the current one — reads its own here instead.
+ */
+export const usePageLocation = () => {
+  const { location } = usePathCtx();
+  const pathname = st.use.pathname({ agent: false });
+  const params = st.use.params({ agent: false });
+  const searchParams = st.use.searchParams({ agent: false });
+  return location
+    ? { pathname: location.pathname, params: location.params, searchParams: location.searchParams }
+    : { pathname, params, searchParams };
+};

package/webkit/usePageTool.tsx

@@ -3,9 +3,8 @@ import { Any, Int } from "akanjs/base";
 import { st } from "akanjs/store";
 
 interface PageToolOptions {
-  /** The slice's own `setPageOf<Model>`, or null while the screen draws no pager — one page needs no control. */
+  /** Null publishes nothing: a single page draws no pager. */
   name: string | null;
-  /** The model's refName, for the description an agent picks the tool by. */
   model: string;
   page: number;
   lastPage: number;
@@ -13,13 +12,7 @@ interface PageToolOptions {
   onSelect: (page: number) => void;
 }
 
-/**
- * Publishes one pager: the `setPageOf<Model>` its control already dispatches, plus the counts an agent needs to
- * aim it. Shared by the three components that draw a pager so all three speak the slice's one name.
- *
- * The page count rides the guard and the resource rather than the description, which is mount-static and would
- * keep quoting whatever the list held on its first render.
- */
+/** The page count rides the guard and the resource: the description is read once, at mount. */
 export const usePageTool = ({ name, model, page, lastPage, total, onSelect }: PageToolOptions) => {
   st.expose(name ? `pagesOf${model.charAt(0).toUpperCase()}${model.slice(1)}` : null, Any)
     .desc(`Where the ${model} list is paged to.`)

package/webkit/usePurchase.tsx

@@ -1,159 +1,88 @@
 "use client";
-import "cordova-plugin-purchase/www/store";
-
-import { loadCapacitorApp } from "akanjs/client/capacitor";
+import { AkanNativeError, type IapProduct, type IapTransaction, loadIap, nativePlatform } from "akanjs/client/native";
 import { useEffect, useRef, useState } from "react";
 
+import { NativePurchase, type NativePurchaseOptions } from "./nativePurchase";
+
+export type {
+  BillingVerification,
+  PurchaseCallback,
+  PurchaseProductInfo,
+  PurchaseProductType,
+} from "./nativePurchase";
+
 export type PlatformType = "android" | "ios" | "all";
-export interface ProductType {
-  id: string;
-  type: keyof typeof CdvPurchase.ProductType;
-}
 
-export type CdvProductType = CdvPurchase.ProductType;
+export type PurchaseResult = "purchased" | "pending" | "cancelled" | "unverified";
 
-/**
- * @deprecated Built on `cordova-plugin-purchase`, which is a peer dependency of the whole package because of
- * this one hook. Replace with `@revenuecat/purchases-capacitor`; this stays only for apps already on it.
- */
-export const usePurchase = ({
-  platform,
-  productInfo,
-  url,
-  onPay,
-  onSubscribe,
-}: {
+interface UsePurchaseOptions extends NativePurchaseOptions {
+  /** The stores this app sells in; a native shell on another platform shows no products. */
   platform: PlatformType;
-  productInfo: ProductType[];
-  url: string;
-  onPay?: (transaction: CdvPurchase.Transaction) => void | Promise<void>;
-  onSubscribe?: (transaction: CdvPurchase.Transaction) => void | Promise<void>;
-}) => {
+}
+
+/** In-app purchase on the native iap plugin: StoreKit 2 on iOS, Play Billing on Android. The web sells nothing. */
+export const usePurchase = ({ platform, ...options }: UsePurchaseOptions) => {
   const [isLoading, setIsLoading] = useState(true);
-  const billingRef = useRef<any>(null);
+  const [products, setProducts] = useState<IapProduct[]>([]);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const flow = () => new NativePurchase(optionsRef.current);
+  
+  const settleLater = (transaction: IapTransaction) =>
+    void flow()
+      .settle(transaction)
+      .catch(() => undefined);
 
   useEffect(() => {
-    const init = async () => {
-      if (CdvPurchase.store.isReady) {
-        setIsLoading(false);
-
-        return;
-      }
-      const { App } = await loadCapacitorApp();
-      const app = await App.getInfo();
-      if (platform === "all")
-        CdvPurchase.store.register([
-          ...productInfo.map((prouct) => ({
-            id: prouct.id,
-            platform: CdvPurchase.Platform.GOOGLE_PLAY,
-            type: CdvPurchase.ProductType[prouct.type],
-          })),
-          ...productInfo.map((prouct) => ({
-            id: prouct.id,
-            platform: CdvPurchase.Platform.APPLE_APPSTORE,
-            type: CdvPurchase.ProductType[prouct.type],
-          })),
-        ]);
-      else
-        CdvPurchase.store.register(
-          productInfo.map((product) => ({
-            id: product.id,
-            platform: platform === "android" ? CdvPurchase.Platform.GOOGLE_PLAY : CdvPurchase.Platform.APPLE_APPSTORE,
-            type: CdvPurchase.ProductType[product.type],
-          })),
-        );
-
-      await CdvPurchase.store.initialize([
-        { platform: CdvPurchase.Platform.APPLE_APPSTORE, options: { needAppReceipt: false } },
-        { platform: CdvPurchase.Platform.GOOGLE_PLAY },
-      ]);
-      await CdvPurchase.store.update();
-      await CdvPurchase.store.restorePurchases();
-      
-      CdvPurchase.store.validator = (async (
-        request: { id: string; transaction: { id: string; purchaseToken: string; appStoreReceipt: string } },
-        callback: (result: {
-          ok: boolean;
-          data: { id: string; latest_receipt: boolean; transaction: CdvPurchase.Transaction };
-        }) => void,
-      ) => {
-        const transactionId = request.transaction.id; 
-        const transactions = CdvPurchase.store.localTransactions;
-        const verifingTransaction = transactions.find((transaction) => transaction.transactionId === transactionId);
-
-        if (verifingTransaction?.state !== "approved") return;
-
-        const billing = await fetch(`${url}/billing/verifyBilling`, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-          },
-          body: JSON.stringify({
-            data: {
-              platform: verifingTransaction.platform === CdvPurchase.Platform.GOOGLE_PLAY ? "google" : "apple",
-              packageName: app.id,
-              productId: verifingTransaction.products[0].id,
-              receipt:
-                verifingTransaction.platform === CdvPurchase.Platform.GOOGLE_PLAY
-                  ? request.transaction.purchaseToken
-                  : request.transaction.appStoreReceipt,
-              transactionId: verifingTransaction.transactionId,
-            },
-          }),
-        });
-
-        billingRef.current = billing.json();
-
-        callback({
-          
-          ok: !!billing,
-          
-          data: { id: request.id, latest_receipt: true, transaction: request.transaction } as any,
-        });
-      }) as any;
-      if (CdvPurchase.store.localReceipts.length > 0) {
-        CdvPurchase.store.localReceipts.forEach((receipt) => {
-          if (receipt.platform === CdvPurchase.Platform.GOOGLE_PLAY)
-            if (receipt.transactions[0].state === CdvPurchase.TransactionState.APPROVED)
-              void receipt.transactions[0].verify();
-            else void receipt.transactions[0].finish();
-        });
-      }
-
-      CdvPurchase.store
-        .when()
-        .approved((transaction) => {
-          void transaction.verify();
-        })
-        .verified((receipt) => {
-          void receipt.finish();
-        })
-        .finished((transaction) => {
-          void inAppPurchase(transaction);
-        });
+    const current = nativePlatform();
+    if (!current || (platform !== "all" && platform !== current)) {
       setIsLoading(false);
+      return;
+    }
+    let active = true;
+    let stop: () => void = () => undefined;
+    void (async () => {
+      const { iap } = await loadIap();
+      if (!active) return;
+      stop = iap.listen("transaction", settleLater);
+      const [{ products }, { transactions }] = await Promise.all([
+        iap.getProducts({ ids: optionsRef.current.productInfo.map(({ id }) => id) }),
+        iap.getUnfinished(),
+      ]);
+      if (!active) return;
+      setProducts(products);
+      for (const transaction of transactions) settleLater(transaction);
+    })()
+      .catch(() => undefined)
+      .finally(() => {
+        if (active) setIsLoading(false);
+      });
+    return () => {
+      active = false;
+      stop();
     };
-    void init();
   }, []);
-  const purchaseProduct = async (product: CdvPurchase.Product) => {
-    await product.getOffer()?.order();
-  };
 
-  const restorePurchases = async () => {
-    await CdvPurchase.store.restorePurchases();
+  const purchaseProduct = async (product: IapProduct | string, offerToken?: string): Promise<PurchaseResult> => {
+    const { iap } = await loadIap();
+    try {
+      const productId = typeof product === "string" ? product : product.id;
+      const { status, transaction } = await iap.purchase({ productId, ...(offerToken ? { offerToken } : {}) });
+      if (status === "pending" || !transaction) return "pending";
+      const settled = await flow().settle(transaction);
+      return settled === "finished" ? "purchased" : settled === "unverified" ? "unverified" : "pending";
+    } catch (error) {
+      if (AkanNativeError.from(error).code === "CANCELLED") return "cancelled";
+      throw error;
+    }
   };
 
-  const inAppPurchase = async (transaction: CdvPurchase.Transaction) => {
-    const product = CdvPurchase.store.get(transaction.products[0].id);
-    if (product?.type === "consumable") await onPay?.(transaction);
-    else await onSubscribe?.(transaction);
-    await transaction.finish();
+  const restorePurchases = async () => {
+    const { iap } = await loadIap();
+    const { transactions } = await iap.restore();
+    for (const transaction of transactions) if (transaction.acknowledged === false) settleLater(transaction);
+    return transactions;
   };
 
-  return {
-    isLoading,
-    products: CdvPurchase.store.products,
-    purchaseProduct,
-    restorePurchases,
-  };
+  return { isLoading, products, purchaseProduct, restorePurchases };
 };

package/webkit/useScreenScope.tsx

@@ -16,19 +16,8 @@ interface ScreenScopeOptions {
 
 const ITEM_CAP = 100;
 
-/**
- * Announces what a component has on screen: one scope for its mounted lifetime, plus an `<id>.items` resource
- * naming what it currently renders. `Load.Units`/`Load.View` call this, so every list and detail view is visible
- * to the in-page agent with no app code. Items are capped and the cap is declared — a truncated list must never
- * read as the whole one.
- *
- * Opened under the scope it is mounted in, not at the root: a list inside an `Agent.Zone` belongs to that zone's
- * view, and a view only sees keys in its own subtree.
- *
- * Returns the scope path, which the caller puts on the container it renders as `data-agent-scope`: that attribute
- * is how `readScreen({ section })` and `highlight` resolve a path the agent read in the screen context back to the
- * element. A caller that renders no container of its own simply is not addressable that way.
- */
+/** Opens a scope under the ambient one, plus an `<id>.items` resource capped at 100 and marked `truncated` past it.
+ * Returns the path the caller sets as `data-agent-scope`, which `readScreen({ section })` and `highlight` resolve. */
 export const useScreenScope = ({ id, kind, label, items }: ScreenScopeOptions) => {
   const surface = useSurface();
   const parent = useScopePath();