akanjs 3.0.0-beta.9 → 3.0.0

package/types/webkit/nativePurchase.d.ts

@@ -0,0 +1,41 @@
+import { type IapTransaction } from "akanjs/client/native";
+export type PurchaseProductType = "consumable" | "nonConsumable" | "subscription";
+export interface PurchaseProductInfo {
+    id: string;
+    type: PurchaseProductType;
+}
+export interface BillingVerification {
+    platform: "apple" | "google";
+    packageName: string;
+    productId: string;
+    receipt: string;
+    transactionId: string;
+}
+export type PurchaseCallback = (transaction: IapTransaction, verified: unknown) => void | Promise<void>;
+/** The app's own check; the store's raw proof is also on `transaction.verification`. */
+export type BillingVerifier = (data: BillingVerification, transaction: IapTransaction) => Promise<unknown>;
+export interface NativePurchaseOptions {
+    productInfo: PurchaseProductInfo[];
+    /** The verification server's origin; it answers `POST <url>/billing/verifyBilling`. Unused with `verify`. */
+    url?: string;
+    /** Verifies instead of the POST: what it resolves reaches onPay/onSubscribe, and `null`, `undefined` or `false` refuses. */
+    verify?: BillingVerifier;
+    onPay?: PurchaseCallback;
+    onSubscribe?: PurchaseCallback;
+}
+export type SettleResult = "finished" | "unverified" | "skipped";
+/** One transaction's way from the store to the app: verified by the server, handed to the app, then finished. */
+export declare class NativePurchase {
+    #private;
+    readonly options: NativePurchaseOptions;
+    constructor(options: NativePurchaseOptions);
+    typeOf(productId: string): PurchaseProductType;
+    verificationOf({ id, productId, verification }: IapTransaction): Promise<BillingVerification | null>;
+    verify(transaction: IapTransaction): Promise<{
+        ok: true;
+        body: unknown;
+    } | {
+        ok: false;
+    }>;
+    settle(transaction: IapTransaction): Promise<SettleResult>;
+}

package/types/webkit/nativeUpdates.d.ts

@@ -0,0 +1,8 @@
+export declare class NativeUpdates {
+    #private;
+    static readonly recheckAfterMs: number;
+    static get enabled(): boolean;
+    static confirm(): void;
+    listen(): () => void;
+    check(): Promise<void>;
+}

package/types/webkit/seoPages.d.ts

@@ -0,0 +1,19 @@
+export declare const createRobotPage: (clientHttpUri: string, config?: {
+    rules: {
+        userAgent: string;
+        allow: string;
+        disallow: string;
+    };
+    sitemap: string;
+}) => {
+    rules: {
+        userAgent: string;
+        allow: string;
+        disallow: string;
+    };
+    sitemap: string;
+};
+export declare const createSitemapPage: (clientHttpUri: string, paths: string[]) => {
+    url: string;
+    lastModified: Date;
+}[];

package/types/webkit/useBodyScrollLock.d.ts

@@ -1,2 +1 @@
-/** Hold `document.body` unscrollable while `active`. */
 export declare const useBodyScrollLock: (active: boolean) => void;

package/types/webkit/useCamera.d.ts

@@ -1,28 +1,26 @@
-import { type CapacitorPermissionState } from "akanjs/client/capacitor";
-type PermissionStatus = {
-    camera: CapacitorPermissionState;
-    photos: CapacitorPermissionState;
-};
-/** The four strings the native picker shows. Omitted ones come from the `base` dictionary. */
+type PermissionState = "granted" | "denied" | "prompt";
+/** The four strings the camera-or-library sheet shows. Omitted ones come from the `base` dictionary. */
 export interface CameraPromptLabels {
     header?: string;
     photo?: string;
     picture?: string;
     cancel?: string;
 }
-/** Capacitor camera/photos hook with permission checks and app-settings fallback. */
+/** Photos arrive as upright JPEG data URLs; a denied camera opens the app settings instead of resolving. */
 export declare const useCamera: ({ promptLabels }?: {
     promptLabels?: CameraPromptLabels;
 }) => {
-    permissions: PermissionStatus;
+    permissions: {
+        camera: PermissionState;
+    };
     getPhoto: (src?: "prompt" | "camera" | "photos") => Promise<{
-        [key: string]: unknown;
-        dataUrl?: string;
+        dataUrl: string;
     } | undefined>;
-    pickImage: () => Promise<{
-        [key: string]: unknown;
-        photos: unknown[];
-    }>;
-    checkPermission: (type: "photos" | "camera" | "all") => Promise<void>;
+    pickImage: ({ limit }?: {
+        limit?: number;
+    }) => Promise<{
+        dataUrl: string;
+    }[] | undefined>;
+    checkPermission: () => Promise<"prompt" | "denied" | "granted">;
 };
 export {};

package/types/webkit/useCsrValues.d.ts

@@ -1,4 +1,4 @@
-import { type NavigationIntent, type PageTransition, type PathRoute, type RouteGuide, type RouterInstance, type TransitionType } from "akanjs/client";
+import { type Location, type NavigationIntent, type PageTransition, type PathRoute, type RouteGuide, type RouterInstance, type TransitionType } from "akanjs/client";
 export declare const useCsrValues: (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]) => {
     page: PageTransition | null;
     topSafeArea: import("akanjs/client").SafeAreaTransition | null;
@@ -16,11 +16,13 @@ export declare const useCsrValues: (rootRouteGuide: RouteGuide, pathRoutes: Path
     transProgress: import("react-spring").Interpolation<number>;
     clientWidth: number;
     clientHeight: number;
-    location: import("akanjs/client").Location;
-    prevLocation: import("akanjs/client").Location | null;
-    pendingLocation: import("akanjs/client").Location | null;
+    location: Location;
+    prevLocation: Location | null;
+    pendingLocation: Location | null;
+    stackEntries: import("akanjs/client").CsrStackEntry[];
     navigationIntent: NavigationIntent | null;
     phase: import("akanjs/client").CsrNavigationPhase;
+    isBackgrounded: boolean;
     history: import("react").RefObject<import("akanjs/client").History>;
     topSafeAreaRef: import("react").RefObject<HTMLDivElement | null>;
     bottomSafeAreaRef: import("react").RefObject<HTMLDivElement | null>;

package/types/webkit/useDebounce.d.ts

@@ -1,2 +1 @@
-/** Returns a callback that runs only after calls have stopped for the wait time. */
 export declare const useDebounce: <Args extends unknown[], Return>(callback: (...args: Args) => Return, states?: unknown[], wait?: number) => (...args: Args) => void;

package/types/webkit/useEscapeKey.d.ts

@@ -1,5 +1,2 @@
-/**
- * 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 declare const useEscapeKey: (active: boolean, onEscape: () => void) => void;

package/types/webkit/useFetch.d.ts

@@ -1,15 +1,12 @@
-/** Tracks fulfillment state for a promise or immediate value inside a client component. */
-export declare const useFetch: <Return>(fnOrPromise: Promise<Return> | Return, { onError }?: {
+export declare const useFetch: <Return>(fnOrPromise: Promise<Return> | Return, { onError, keepPrevious, }?: {
     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;
 };
-/**
- * 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 declare const useFetchFn: <Return>(factory: () => Promise<Return> | Return, deps?: unknown[], options?: {
     onError?: (err: string) => void;
 }) => {

package/types/webkit/useFrameRuntime.d.ts

@@ -43,7 +43,7 @@ export declare function getKeyboardAccessorySlots(path: string, frameSlots: Fram
 export declare function resolveKeyboardAccessoryHeight(path: string, frameSlots: FrameSlotMap): number;
 export declare function hasKeyboardStickySlot(path: string, frameSlots: FrameSlotMap): boolean;
 export declare function hasBottomAnchoredKeyboardSlot(path: string, frameSlots: FrameSlotMap): boolean;
-export declare function resolveKeyboardFrame({ keyboardHeight, bottomSafeArea, visualViewportKeyboardHeight, platformProfile, sticky, freeze, }: {
+export declare function resolveKeyboardFrame({ keyboardHeight, visualViewportKeyboardHeight, platformProfile, sticky, freeze, }: {
     keyboardHeight: number;
     bottomSafeArea: number;
     visualViewportKeyboardHeight: number;

package/types/webkit/useGeoLocation.d.ts

@@ -1,8 +1,7 @@
-/** Capacitor geolocation hook with permission checks and current position lookup. */
+/** `getPosition` opens the app settings instead of resolving when location permission is denied. */
 export declare const useGeoLocation: () => {
-    checkPermission: () => Promise<{
-        geolocation: string;
-        coarseLocation: string;
-    }>;
-    getPosition: () => Promise<unknown>;
+    checkPermission: () => Promise<import("../vendor/@akanjs/native/plugins/geolocation/src/index.d.ts").LocationPermission>;
+    getPosition: (options?: {
+        enableHighAccuracy?: boolean;
+    }) => Promise<import("akanjs/client/native").Position | undefined>;
 };

package/types/webkit/useHistory.d.ts

@@ -11,10 +11,14 @@ interface setBackOptions {
     scrollTop?: number;
     scrollToTop?: boolean;
 }
-export declare const useHistory: (locations?: Location[]) => {
+export declare const useHistory: (locations?: Location[], { idx, dormant }?: {
+    idx?: number;
+    dormant?: Set<string>;
+}) => {
     history: import("react").RefObject<History>;
     setHistoryForward: ({ type, location, scrollTop, scrollToTop }: setForwardOptions) => void;
     setHistoryBack: ({ location, scrollTop, scrollToTop }: setBackOptions) => void;
+    setHistoryJump: (idx: number, scrollTop?: number) => void;
     getNextLocation: () => Location | null;
     getCurrentLocation: () => Location;
     getPrevLocation: () => Location | null;

package/types/webkit/usePageActivity.d.ts

@@ -0,0 +1,2 @@
+/** Where this page stands in the CSR stack. Outside one — SSR, a layout, a plain web page — it is always `current`. */
+export declare const usePageActivity: () => import("akanjs/client").PageActivity;

package/types/webkit/usePageFocusEffect.d.ts

@@ -0,0 +1,7 @@
+import { type DependencyList, type EffectCallback } 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 declare const usePageFocusEffect: (effect: EffectCallback, deps: DependencyList) => void;

package/types/webkit/usePageLocation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare const usePageLocation: () => {
+    pathname: string;
+    params: {
+        [key: string]: string;
+    };
+    searchParams: {
+        [key: string]: string | string[];
+    };
+};

package/types/webkit/usePageTool.d.ts

@@ -1,19 +1,12 @@
 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;
     total: number;
     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 declare const usePageTool: ({ name, model, page, lastPage, total, onSelect }: PageToolOptions) => (args_0: number) => Promise<void>;
 export {};

package/types/webkit/usePurchase.d.ts

@@ -1,23 +1,16 @@
-import "cordova-plugin-purchase/www/store";
+import { type IapProduct, type IapTransaction } from "akanjs/client/native";
+import { type NativePurchaseOptions } from "./nativePurchase.d.ts";
+export type { BillingVerification, PurchaseCallback, PurchaseProductInfo, PurchaseProductType, } from "./nativePurchase.d.ts";
 export type PlatformType = "android" | "ios" | "all";
-export interface ProductType {
-    id: string;
-    type: keyof typeof CdvPurchase.ProductType;
-}
-export type CdvProductType = CdvPurchase.ProductType;
-/**
- * @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 declare const usePurchase: ({ platform, productInfo, url, onPay, onSubscribe, }: {
+export type PurchaseResult = "purchased" | "pending" | "cancelled" | "unverified";
+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 declare const usePurchase: ({ platform, ...options }: UsePurchaseOptions) => {
     isLoading: boolean;
-    products: CdvPurchase.Product[];
-    purchaseProduct: (product: CdvPurchase.Product) => Promise<void>;
-    restorePurchases: () => Promise<void>;
+    products: IapProduct[];
+    purchaseProduct: (product: IapProduct | string, offerToken?: string) => Promise<PurchaseResult>;
+    restorePurchases: () => Promise<IapTransaction[]>;
 };

package/types/webkit/useScreenScope.d.ts

@@ -8,18 +8,7 @@ interface ScreenScopeOptions {
     label?: string;
     items?: () => ScreenScopeItem[];
 }
-/**
- * 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 declare const useScreenScope: ({ id, kind, label, items }: ScreenScopeOptions) => string;
 export {};

package/ui/Agent/Attach.tsx

@@ -1,5 +1,5 @@
 "use client";
-import { cn } from "akanjs/client";
+import { cn, resolveServerUrl } from "akanjs/client";
 import { useRef } from "react";
 import { AiOutlineClose, AiOutlinePaperClip } from "react-icons/ai";
 import type { MessageAttachment } from "../../vendor/use-agentic";
@@ -40,12 +40,12 @@ export const Attach = ({ className, label, onPick }: AttachProps) => {
 
 export interface ChipsProps {
   className?: string;
-
+  
   attachments: readonly MessageAttachment[];
   /** Omitted for a sent message: what is already on the wire cannot be taken back. */
   onRemove?: (index: number) => void;
   removeLabel?: string;
-  /** Files still being read, standing beside the ones that are staged so the panel is never blank mid-drop. */
+  /** Files still being read, drawn as placeholders beside the staged ones. */
   pending?: number;
   pendingLabel?: string;
 }
@@ -61,7 +61,11 @@ export const Chips = ({ className, attachments, onRemove, removeLabel, pending =
           <img
             alt={attachment.name}
             className="size-6 rounded-field object-cover"
-            src={attachment.data ? `data:${attachment.mimeType};base64,${attachment.data}` : attachment.url}
+            src={
+              attachment.data
+                ? `data:${attachment.mimeType};base64,${attachment.data}`
+                : resolveServerUrl(attachment.url ?? "")
+            }
           />
         ) : null}
         <span className="max-w-32 truncate">{attachment.name}</span>

package/ui/Agent/Bubble.tsx

@@ -1,7 +1,14 @@
 "use client";
 import { cn, usePage } from "akanjs/client";
 import { memo } from "react";
-import { type AgentProgressReport, AgentSession, type ChatMessage, type ToolCallResult, ToolOutput } from "../../vendor/use-agentic";
+import {
+  type AgentProgressReport,
+  type AgentProgressStep,
+  AgentSession,
+  type ChatMessage,
+  type ToolCallResult,
+  ToolOutput,
+} from "../../vendor/use-agentic";
 import { createOverridable } from "../UiOverride";
 import { Chips } from "./Attach";
 import Markdown from "./Markdown";
@@ -11,13 +18,9 @@ import { tokenCount } from "./tokenCount";
 export interface BubbleProps {
   className?: string;
   message: ChatMessage;
-  /** What the call still running last reported about itself, so a slow tool says what it is doing. */
+  /** What the running call last reported about itself. */
   progress?: (AgentProgressReport & { callId: string }) | null;
-  /**
-   * Results by call id, gathered across the transcript. A call and its result are two wire messages — the model
-   * needs both — but they are one thing that happened, so the call's own row resolves in place instead of the
-   * name appearing again as a second row.
-   */
+  /** Results by call id across the transcript, so a call's own row resolves in place. */
   results?: ReadonlyMap<string, ToolCallResult>;
 }
 
@@ -28,28 +31,49 @@ interface RowProps {
   progress?: AgentProgressReport | null;
 }
 
-/** What the row shows when it is opened: everything the model was handed that the one line could not fit. */
 const payloadOf = ({ result, changes, error }: ToolCallResult) => ({
   ...(result !== undefined ? { result } : {}),
   ...(changes?.length ? { changes } : {}),
   ...(error ? { error } : {}),
 });
 
-/**
- * The arguments ride along because two calls of one tool are the same row otherwise — two searches, one name.
- *
- * A settled row opens: the estimated token cost is on the line, and the value itself is one click below it. Both
- * are there because a tool result is the one part of a transcript neither the user nor the app author sees — it is
- * the app's own return value, sized for a screen and not for a model's window, and a conversation that fills up
- * after four messages is answered by *which* row cost a million tokens and nothing else.
- */
+const stepGlyph = { pending: "○", running: "●", done: "✓", error: "✕" } as const;
+const stepTone = {
+  pending: "text-foreground/40",
+  running: "animate-pulse text-warning",
+  done: "text-success",
+  error: "text-destructive",
+} as const;
+
+interface StepListProps {
+  steps: AgentProgressStep[];
+}
+const StepList = ({ steps }: StepListProps) => {
+  const settled = steps.filter((step) => step.status === "done" || step.status === "error").length;
+  return (
+    <details className="px-2 pb-1">
+      <summary className="cursor-pointer font-mono text-[10px] text-foreground/50">
+        {settled}/{steps.length}
+      </summary>
+      <ul className="mt-1 flex flex-col gap-0.5">
+        {steps.map((step) => (
+          <li className="flex items-baseline gap-2 text-[10px]" key={step.id}>
+            <span className={cn("shrink-0", stepTone[step.status])}>{stepGlyph[step.status]}</span>
+            <span className="truncate">{step.label}</span>
+            {step.detail ? <span className="truncate text-foreground/50">{step.detail}</span> : null}
+          </li>
+        ))}
+      </ul>
+    </details>
+  );
+};
+
 const Row = ({ name, args, result, progress }: RowProps) => {
   const { l } = usePage();
   const payload = result ? payloadOf(result) : null;
   const head = (
     <>
       {result ? (
-        
         <span
           aria-label={l(result.error ? "base.agentToolFailed" : "base.agentToolDone")}
           className={cn("shrink-0 text-[10px]", result.error ? "text-destructive" : "text-success")}
@@ -81,6 +105,13 @@ const Row = ({ name, args, result, progress }: RowProps) => {
       </span>
     </>
   );
+  if (progress?.steps?.length)
+    return (
+      <div className="rounded-field bg-muted">
+        <div className="flex items-baseline gap-2 px-2 py-1">{head}</div>
+        <StepList steps={progress.steps} />
+      </div>
+    );
   if (!payload || !Object.keys(payload).length)
     return <div className="flex items-baseline gap-2 rounded-field bg-muted px-2 py-1">{head}</div>;
   return (
@@ -105,11 +136,6 @@ interface AskProps {
   result: ToolCallResult;
 }
 
-/**
- * A settled `askUser` reads as the exchange it was — the question, then what the user answered — instead of as a
- * tool row. An unsettled one renders nothing here: the question card below the transcript is holding it, and the
- * text would otherwise sit on screen twice.
- */
 const Ask = ({ args, result }: AskProps) => {
   const answered = (Array.isArray(result.result) ? result.result : [result.result])
     .filter((one): one is string => typeof one === "string" && !!one)
@@ -131,7 +157,6 @@ const Ask = ({ args, result }: AskProps) => {
 
 const Content = ({ className, message, progress, results }: BubbleProps) => {
   const { l } = usePage();
-
   if (message.summary)
     return (
       <details className={cn("rounded-box border border-border bg-muted/60 px-3 py-2", className)}>
@@ -181,14 +206,7 @@ const Content = ({ className, message, progress, results }: BubbleProps) => {
   );
 };
 
-/**
- * Memoized because the transcript re-renders on every streamed delta and on every keystroke in the composer, and
- * a settled bubble re-parses its markdown for nothing each time. The props are compared by identity, so the caller
- * hands the same `results` map and `progress` value to every row — which is why only the rows that actually
- * changed re-render.
- *
- * A component bound to the `AgentBubble` slot replaces the memoized default, so it carries its own `memo`.
- */
+/** Memoized on prop identity; a component bound to the `AgentBubble` slot replaces it and carries its own `memo`. */
 export const DefaultBubble = memo(Content);
 
 export default createOverridable("AgentBubble", DefaultBubble);