akanjs 3.0.0-beta.11 → 3.0.0-beta.13

package/client/router.ts

@@ -14,14 +14,15 @@ export interface DeepLinkOptions extends RouteOptions {
 const DEEP_LINK_STACK_STEP_DELAY = 450;
 
 export interface RouterInstance {
-  push: (href: string, routeOptions?: RouteOptions) => void;
-  replace: (href: string, routeOptions?: RouteOptions) => void;
+  /** May answer a promise that rejects when the route refused to move — see `Router.navigation`. */
+  push: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
+  replace: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
   back: (routeOptions?: RouteOptions) => void;
   refresh: () => void;
 }
 interface InternalRouterInstance {
-  push: (href: string, routeOptions?: RouteOptions) => void;
-  replace: (href: string, routeOptions?: RouteOptions) => void;
+  push: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
+  replace: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
   back: (routeOptions?: RouteOptions) => void;
   refresh: () => void;
 }
@@ -163,6 +164,7 @@ class Router {
   #lang = parseAkanI18nEnv().defaultLocale;
   #routePaths = new Set<string>();
   #indexPath = "/";
+  #navigation: Promise<void> = Promise.resolve();
   #historyIdx = 0;
   #instance: InternalRouterInstance = {
     push: (href: string) => {
@@ -210,14 +212,14 @@ class Router {
         const pathInfo = this.#getPathInfo(href);
         const navigationPathInfo = this.#getNavigationPathInfo(href);
         this.#postPathChange(pathInfo);
-        router.push(navigationPathInfo.href, routeOptions);
+        return router.push(navigationPathInfo.href, routeOptions);
       },
       replace: (href: string, routeOptions) => {
         const router = options.router;
         const pathInfo = this.#getPathInfo(href);
         const navigationPathInfo = this.#getNavigationPathInfo(href);
         this.#postPathChange(pathInfo);
-        router.replace(navigationPathInfo.href, routeOptions);
+        return router.replace(navigationPathInfo.href, routeOptions);
       },
       back: () => {
         const router = options.router;
@@ -238,7 +240,7 @@ class Router {
       push: (href: string, routeOptions) => {
         const { path, pathname, hash, href: fullHref } = this.#getPathInfo(href);
         this.#postPathChange({ path, pathname, hash });
-        options.router.push(this.#withCsrRuntimeSearchParams(fullHref), routeOptions);
+        return options.router.push(this.#withCsrRuntimeSearchParams(fullHref), routeOptions);
       },
       replace: (href: string, routeOptions) => {
         const { path, pathname, hash, href: fullHref } = this.#getPathInfo(href);
@@ -367,18 +369,34 @@ class Router {
   }
   push(href: string, routeOptions?: RouteOptions) {
     this.#checkInitialized();
-    this.#instance.push(href, routeOptions);
+    this.#track(this.#instance.push(href, routeOptions));
     this.#rememberHistoryState("push");
     this.#postDevSyncNavigation("push", href);
     return undefined as never;
   }
   replace(href: string, routeOptions?: RouteOptions) {
     this.#checkInitialized();
-    this.#instance.replace(href, routeOptions);
+    this.#track(this.#instance.replace(href, routeOptions));
     this.#rememberHistoryState("replace");
     this.#postDevSyncNavigation("replace", href);
     return undefined as never;
   }
+  /**
+   * The navigation `push` / `replace` last started, for a caller that has to know whether it landed. **Rejects
+   * when the route refused to move** — a target that resolves to nothing leaves the page where it was instead of
+   * replacing it, and `push` returns long before that is known, so this is the only place it can be reported.
+   *
+   * A method rather than a getter: `router` is a Proxy that binds functions to the real instance, and a getter
+   * reached through it would run with the Proxy as `this` and fail on the private field.
+   */
+  navigation(): Promise<void> {
+    return this.#navigation;
+  }
+  #track(result: void | Promise<void>) {
+    this.#navigation = Promise.resolve(result);
+    
+    void this.#navigation.catch(() => undefined);
+  }
   canGoBack() {
     if (getEnv().side === "server") return false;
     return this.#historyIdx > 0;
@@ -444,10 +462,17 @@ class Router {
     this.#instance.replace(`${path}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`);
     return undefined as never;
   }
+  /**
+   * A pathname with the locale and base-path segments taken off — the app-internal route it names, which is what
+   * a tool argument and a `<a href>` have in common. Unguarded, unlike `getPath`, whose default argument is the
+   * one thing in it that needs a browser.
+   */
+  routeOf(pathname: string) {
+    return getPathInfo(pathname, this.#lang, this.#prefix).path;
+  }
   getPath(pathname = window.location.pathname) {
     if (getEnv().side === "server") throw new Error("getPath is only available in client side");
-    const { path } = getPathInfo(pathname, this.#lang, this.#prefix);
-    return path;
+    return this.routeOf(pathname);
   }
   getFullPath(withLang = true) {
     if (getEnv().side === "server") throw new Error("getPath is only available in client side");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.11",
+  "version": "3.0.0-beta.13",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/rscClient.tsx

@@ -82,6 +82,7 @@ type RscFetchResult =
       outletKey: string;
       headSnapshot: AkanHeadSnapshotV1;
     }
+  | { type: "not-found" }
   | { type: "redirected"; status?: number };
 const MAX_RSC_CACHE_ENTRIES = 32;
 let documentNavigationFallbackInFlight = false;
@@ -93,6 +94,22 @@ class RscRedirectNavigationStarted extends Error {
   }
 }
 
+/**
+ * A navigation whose target resolves to nothing. Thrown instead of committing the payload, and deliberately not
+ * converted into a document navigation: the page the user is on is a working page, and trading it for a 404 — or,
+ * before this, for the empty tree `0:null` decodes to — throws away everything mounted on it, an in-page agent's
+ * session included. The route stays where it is and the caller is told.
+ *
+ * Recognised across bundles by `name` rather than `instanceof`: the RSC client is inlined into more than one
+ * browser bundle, so the class identity a given file holds is not always the one that threw.
+ */
+class RscRouteNotFound extends Error {
+  constructor(readonly href: string) {
+    super(`[rscClient] no route at ${href}`);
+    this.name = "RscRouteNotFound";
+  }
+}
+
 function createInitialRscStream(): ReadableStream<Uint8Array> {
   return new ReadableStream<Uint8Array>({
     start(controller) {
@@ -229,6 +246,7 @@ async function fetchRsc(
     shouldApplyNavigation,
   });
   if (responseResult.type === "redirected") return responseResult;
+  if (responseResult.type === "not-found") return responseResult;
   if (responseResult.type === "patch") {
     const patchResult = await validateRscPatchForGuardedCommit({
       partialCommitEnabled: isAkanRscPartialCommitEnabled(),
@@ -364,6 +382,11 @@ function Root(): ReactNode {
         shouldApplyNavigation: () => navId === navigationSeq,
       });
       if (next.type === "redirected") return;
+
+      if (next.type === "not-found") {
+        console.warn(`[rscClient] refresh target ${target} no longer resolves; keeping the current page`);
+        return;
+      }
       if (next.type === "patched") return;
       observeRscNavigationNode({
         cache: rscCache,
@@ -445,6 +468,7 @@ function Root(): ReactNode {
           shouldApplyNavigation: () => navId === navigationSeq,
         });
         if (fetched.type === "redirected") return;
+        if (fetched.type === "not-found") throw new RscRouteNotFound(target);
         if (fetched.type === "patched") {
           if (navId !== navigationSeq) return;
           if (
@@ -476,6 +500,7 @@ function Root(): ReactNode {
             shouldApplyNavigation: () => navId === navigationSeq,
           });
           if (fallback.type === "redirected") return;
+          if (fallback.type === "not-found") throw new RscRouteNotFound(target);
           if (fallback.type === "patched") throw new Error("[rscClient] full fallback unexpectedly returned a patch");
           nextNode = fallback.node;
         } else {
@@ -517,6 +542,8 @@ function Root(): ReactNode {
       if (committed) rememberCommittedRouteState(nextNode);
     } catch (error) {
       if (error instanceof RscRedirectNavigationStarted) return;
+
+      if (error instanceof RscRouteNotFound) throw error;
       if (navId === navigationSeq) hardNavigateAfterRscFailure(target, options.replace, error);
     }
   };
@@ -525,7 +552,10 @@ function Root(): ReactNode {
 }
 
 window.addEventListener("popstate", () => {
-  void globalThis.__AKAN_RSC_NAVIGATE__?.(window.location.href, { replace: true, scrollToTop: false });
+
+  void globalThis
+    .__AKAN_RSC_NAVIGATE__?.(window.location.href, { replace: true, scrollToTop: false })
+    ?.catch((error: unknown) => hardNavigateAfterRscFailure(window.location.href, true, error));
   window.setTimeout(() => {
     if (globalThis.__AKAN_DEV_SYNC_NAVIGATION_APPLYING__) return;
     const href = globalThis.__AKAN_GET_SYNC_ROUTE_HREF__?.(window.location.href) ?? window.location.href;

package/server/rscClientFetch.ts

@@ -10,6 +10,7 @@ type RscNavigate = (href: string, options?: { replace?: boolean; scrollToTop?: b
 export type RscClientFetchResponseResult =
   | { type: "response"; response: Response }
   | { type: "patch"; response: Response; patch: AkanRscPatchMetadata }
+  | { type: "not-found" }
   | { type: "redirected"; status?: number };
 
 export async function fetchRscNavigationResponse(
@@ -41,6 +42,11 @@ export async function fetchRscNavigationResponse(
     if (shouldApplyNavigation()) await options.navigate?.(redirect, { replace: method !== "push", scrollToTop: true });
     return { type: "redirected", status };
   }
+
+  if (response.status === 404) {
+    await response.body?.cancel();
+    return { type: "not-found" };
+  }
   if (response.headers.get("X-Akan-Rsc-Partial") === "patch") {
     const patch = readAkanRscPatchMetadataResponseHeaders(response.headers);
     if (options.sendRouterState === false) throw new Error("[rscClient] RSC full fallback returned a patch response");

package/store/agent/AgentCursor.ts

@@ -18,26 +18,112 @@ export class AgentCursor {
   static readonly travelMs = 320;
   /** Under this far, the glide is skipped: a third of a second to cross fifty pixels reads as lag, not motion. */
   static readonly travelFrom = 200;
-  /** How long after the last call the pointer stays before fading — one batch's gap, not one call's. */
+  /** How far off the control the pointer drifts before it starts waiting — just clear of its box. */
+  static readonly driftBy = 18;
+  /**
+   * How long after the last call the pointer stays before fading, for a host that reports no turn boundary. A
+   * host that does calls `hold` instead, because this is the wrong unit: between two calls of one turn the model
+   * is writing, which takes longer than this, and the pointer used to vanish and come back for every call.
+   */
   static readonly idleMs = 1400;
+  static readonly thinkingClass = "akan-agent-cursor-thinking";
+  static readonly scrollingClass = "akan-agent-cursor-scrolling";
 
   static #el: HTMLElement | null = null;
   static #at: { x: number; y: number } | null = null;
   static #idle: ReturnType<typeof setTimeout> | null = null;
+  static #held = false;
+  static #pressed: { top: number; left: number; right: number; bottom: number } | null = null;
 
-  /** Travels to the control once it has stopped moving, then presses it. */
-  static press(target: HTMLElement) {
-    if (typeof document === "undefined") return;
-    ScreenFlash.whenStill(target, () => {
-      const { top, left, width, height } = target.getBoundingClientRect();
-      const travel = AgentCursor.#moveTo(left + width / 2, top + height / 2);
+  /** Travels to the control once it has stopped moving, then presses it. Resolves when the press has landed. */
+  static press(target: HTMLElement): Promise<void> {
+    if (typeof document === "undefined") return Promise.resolve();
+    AgentCursor.#el?.classList.remove(AgentCursor.thinkingClass);
+    return new Promise((resolve) => {
+      ScreenFlash.whenStill(target, () => {
 
-      if (travel) setTimeout(() => AgentCursor.#tap(), travel);
-      else AgentCursor.#tap();
+        if (!ScreenFlash.onTop(target)) {
+          AgentCursor.hide();
+          resolve();
+          return;
+        }
+        const { top, left, width, height, right, bottom } = target.getBoundingClientRect();
+        AgentCursor.#pressed = { top, left, right, bottom };
+        const travel = AgentCursor.#moveTo(left + width / 2, top + height / 2);
+
+        if (travel)
+          setTimeout(() => {
+            AgentCursor.#tap();
+            resolve();
+          }, travel);
+        else {
+          AgentCursor.#tap();
+          resolve();
+        }
+      });
     });
   }
 
+  /**
+   * The page is being scrolled and the pointer is what is doing it. It stays put while the content moves, the way
+   * a person's does — what the chevron adds is who asked, since a pointer standing still over a page that slides
+   * under it otherwise reads as one that has come loose from the screen.
+   */
+  static scroll(way: "up" | "down") {
+    const el = AgentCursor.#el;
+    if (!el?.isConnected) return;
+    el.classList.remove(AgentCursor.thinkingClass);
+    el.classList.add(AgentCursor.scrollingClass);
+    el.classList.toggle(`${AgentCursor.scrollingClass}-up`, way === "up");
+  }
+
+  /** Keeps the pointer up for as long as the turn runs, instead of for `idleMs` after the last call. */
+  static hold() {
+    AgentCursor.#held = true;
+    if (AgentCursor.#idle) clearTimeout(AgentCursor.#idle);
+    AgentCursor.#idle = null;
+  }
+
+  static release() {
+    AgentCursor.#held = false;
+    AgentCursor.hide();
+  }
+
+  /**
+   * Waiting rather than acting: the pointer drifts clear of what it just pressed and the arrow gives way to a
+   * spinner. Does nothing before the first press — an agent that drives no control has no place on the screen to
+   * be, and a pointer parked in a corner for a turn that only answered a question would be saying something untrue.
+   */
+  static think() {
+    const el = AgentCursor.#el;
+    if (!el?.isConnected) return;
+    el.classList.remove(`${AgentCursor.className}-tap`);
+    AgentCursor.#driftOff();
+    el.classList.add(AgentCursor.thinkingClass);
+  }
+
+  /**
+   * Off the control before the waiting starts. A person clicks and then takes the hand away to think; a spinner
+   * left on the button it just pressed reads as one stuck to it, and it covers the change it caused.
+   */
+  static #driftOff() {
+    const el = AgentCursor.#el;
+    const box = AgentCursor.#pressed;
+    AgentCursor.#pressed = null;
+    if (!el || !box) return;
+    const gap = AgentCursor.driftBy;
+    
+    const x = box.right + gap <= window.innerWidth - gap ? box.right + gap : box.left - gap;
+    const y = box.bottom + gap <= window.innerHeight - gap ? box.bottom + gap : box.top - gap;
+    const at = { x: Math.max(gap, Math.round(x)), y: Math.max(gap, Math.round(y)) };
+    el.style.transform = `translate3d(${at.x}px, ${at.y}px, 0)`;
+    AgentCursor.#at = at;
+  }
+
   static hide() {
+    AgentCursor.#pressed = null;
+    AgentCursor.#stopScrolling();
+    AgentCursor.#el?.classList.remove(AgentCursor.thinkingClass);
     AgentCursor.#el?.classList.remove(`${AgentCursor.className}-shown`);
     AgentCursor.#at = null;
     const el = AgentCursor.#el;
@@ -48,8 +134,14 @@ export class AgentCursor {
   }
 
   /** How long the move will take, so the caller knows when the pointer has arrived. */
+  static #stopScrolling() {
+    AgentCursor.#el?.classList.remove(AgentCursor.scrollingClass, `${AgentCursor.scrollingClass}-up`);
+  }
+
   static #moveTo(x: number, y: number): number {
     const el = AgentCursor.#mounted();
+    AgentCursor.#stopScrolling();
+    el.classList.remove(AgentCursor.thinkingClass);
     const at = AgentCursor.#at;
 
     const travel = at && Math.hypot(x - at.x, y - at.y) >= AgentCursor.travelFrom ? AgentCursor.travelMs : 0;
@@ -76,6 +168,8 @@ export class AgentCursor {
 
   static #keep() {
     if (AgentCursor.#idle) clearTimeout(AgentCursor.#idle);
+    AgentCursor.#idle = null;
+    if (AgentCursor.#held) return;
     AgentCursor.#idle = setTimeout(() => {
       AgentCursor.#idle = null;
       AgentCursor.hide();

package/store/agent/AgentVisual.ts

@@ -1,3 +1,4 @@
+import { router } from "akanjs/client";
 import type { ToolActivity } from "../../vendor/use-agentic";
 import { AgentCursor } from "./AgentCursor";
 import { ScreenFlash } from "./ScreenFlash";
@@ -22,8 +23,13 @@ export interface AgentVisualOption {
  * Nothing here is ever waited on. A call starts the moment the event is handed over; the ring catching up a frame
  * later costs the turn nothing, and an animation that held a call would make the agent slower for a decoration.
  *
- * A call that lands on no control draws nothing, `navigate` included: the router is not an element, and the
- * top-of-page bar tried for it read as chrome the page had grown rather than as the agent doing something.
+ * A call that lands on no control draws nothing. That still covers most of `navigate` — the router is not an
+ * element, and the top-of-page bar tried for it read as chrome the page had grown rather than as the agent doing
+ * something — but a destination the screen already offers as a link is an element, and that one is pressed.
+ *
+ * The pointer's unit is the **turn**, not the call. A model's calls arrive with its own writing between them, so
+ * a pointer that lived for a call's length spent every turn disappearing and coming back; between calls it waits
+ * where it last acted, as a spinner, and goes when the turn does.
  */
 export class AgentVisual {
   /**
@@ -34,21 +40,65 @@ export class AgentVisual {
   static readonly revealCap = 4;
   /** How many of a form patch's fields are drawn. A patch of twenty is a form being filled, not twenty events. */
   static readonly fieldCap = 5;
+  /**
+   * The longest a call is held for the drawing that has to precede it. Every millisecond here is one the agent
+   * spends on a decoration, so the press is given time to land and the call goes either way.
+   */
+  static readonly leadMs = 600;
 
   static #revealed = 0;
   static #idle: ReturnType<typeof setTimeout> | null = null;
+  static #turning = false;
+  static #acting = 0;
 
-  /** The handler `agentSessionOf` hands the session. `true` is every effect; an object turns one of them off. */
-  static sink(option: boolean | AgentVisualOption = true): ((event: ToolActivity) => void) | undefined {
+  /** The handlers `agentSessionOf` hands the session. `true` is every effect; an object turns one of them off. */
+  static sink(option: boolean | AgentVisualOption = true) {
     if (option === false) return undefined;
     const settings = option === true ? {} : option;
-    return (event) => AgentVisual.on(event, settings);
+    return {
+      onActivity: (event: ToolActivity) => AgentVisual.on(event, settings),
+      onTurn: (running: boolean) => AgentVisual.turn(running, settings),
+    };
+  }
+
+  /**
+   * The boundary the pointer lives between, and the one the scroll budget is spent in. Raising a pointer here
+   * would be a pointer with nowhere to point yet, so the turn's start only resets what the last turn used.
+   */
+  static turn(running: boolean, { cursor = true }: AgentVisualOption = {}) {
+    if (typeof document === "undefined") return;
+    AgentVisual.#turning = running;
+    AgentVisual.#revealed = 0;
+    if (AgentVisual.#idle) clearTimeout(AgentVisual.#idle);
+    AgentVisual.#idle = null;
+    if (!running) AgentVisual.#acting = 0;
+    if (!cursor) return;
+    if (running) AgentCursor.hold();
+    else AgentCursor.release();
   }
 
-  static on(event: ToolActivity, { reveal = true, cursor = true }: AgentVisualOption = {}) {
+  static on(event: ToolActivity, { reveal = true, cursor = true }: AgentVisualOption = {}): void | Promise<void> {
     if (typeof document === "undefined" || document.hidden) return;
-    if (!reveal || event.phase !== "start") return;
-    for (const target of AgentVisual.#targetsOf(event)) AgentVisual.#act(target, cursor);
+    if (!reveal && !cursor) return;
+    if (event.phase === "end") {
+      AgentVisual.#acting = Math.max(0, AgentVisual.#acting - 1);
+      if (cursor && AgentVisual.#turning && !AgentVisual.#acting) AgentCursor.think();
+      return;
+    }
+    AgentVisual.#acting += 1;
+    const pressed = AgentVisual.#targetsOf(event).map((target) => AgentVisual.#act(target, { reveal, cursor }));
+
+    if (!cursor || !pressed.length || !AgentVisual.#navigating(event.name)) return;
+    return AgentVisual.#capped(Promise.all(pressed));
+  }
+
+  /** Resolves when the drawing has landed or when its budget runs out, whichever comes first. */
+  static #capped(drawing: Promise<unknown>): Promise<void> {
+    return new Promise((resolve) => {
+      const done = () => resolve();
+      setTimeout(done, AgentVisual.leadMs);
+      void drawing.then(done, done);
+    });
   }
 
   /**
@@ -57,26 +107,80 @@ export class AgentVisual {
    * by any one of them and ringing the form as a whole would say nothing about what changed.
    */
   static #targetsOf(event: ToolActivity): HTMLElement[] {
+    if (AgentVisual.#navigating(event.name)) return AgentVisual.#linkTo(event.args.path);
     const form = AgentVisual.#formOf(event.name);
-    if (!form) return AgentVisual.#only(ScreenTarget.controls(event.name));
+    if (!form) return AgentVisual.#only(ScreenTarget.controls(event.name), event.args);
     return Object.keys(event.args)
       .slice(0, AgentVisual.fieldCap)
       .flatMap((key) => AgentVisual.#only(ScreenTarget.controls(`${form}.${key}`)));
   }
 
   /**
-   * One row's verb is registered once per row and every registration is interchangeable, so several matches means
-   * the agent acted on a row nothing on screen identifies. Ringing a guessed one is worse than ringing none.
+   * One verb is registered once per row and every registration carries the same name, so several matches means the
+   * agent acted somewhere the name alone cannot place. The call's own arguments break the tie when a control says
+   * which one it is (`data-akan-key`, from `agentAttrs(handler, key)`) — that is how a tab's menus are told apart.
+   * Short of exactly one answer nothing is drawn: ringing a guessed control is worse than ringing none.
    */
-  static #only(targets: HTMLElement[]): HTMLElement[] {
-    return targets.length === 1 ? targets : [];
+  static #only(targets: HTMLElement[], args?: Record<string, unknown>): HTMLElement[] {
+    if (targets.length === 1) return targets;
+    if (!targets.length || !args) return [];
+    const named = new Set(
+      Object.values(args)
+        .filter((value): value is string | number => typeof value === "string" || typeof value === "number")
+        .map(String),
+    );
+    const keyed = targets.filter((target) => {
+      const key = target.getAttribute("data-akan-key");
+      return !!key && named.has(key);
+    });
+    return keyed.length === 1 ? keyed : [];
   }
 
-  static #act(target: HTMLElement, cursor: boolean) {
+  static #act(target: HTMLElement, { reveal, cursor }: Required<AgentVisualOption>): Promise<void> {
     AgentVisual.#count();
-    if (AgentVisual.#revealed <= AgentVisual.revealCap && !ScreenFlash.inView(target)) ScreenFlash.reveal(target);
-    if (cursor) AgentCursor.press(target);
-    ScreenFlash.ring(target, { className: ScreenFlash.actingClass, ms: ScreenFlash.actingMs });
+    const scrolled =
+      reveal && AgentVisual.#revealed <= AgentVisual.revealCap && !ScreenFlash.inView(target)
+        ? ScreenFlash.reveal(target)
+        : null;
+    if (cursor && scrolled) AgentCursor.scroll(scrolled);
+    const pressed = cursor ? AgentCursor.press(target) : Promise.resolve();
+    if (reveal) ScreenFlash.ring(target, { className: ScreenFlash.actingClass, ms: ScreenFlash.actingMs });
+    return pressed;
+  }
+
+  /**
+   * The link on screen that goes where a `navigate` call is going, when exactly one does and the user can already
+   * see it. Off-screen links are left alone deliberately: scrolling to a link and then leaving the page it is on
+   * is two motions for one act, and the destination is where the attention belongs by then.
+   *
+   * Addresses are compared through `router.routeOf`, which strips the locale and base-path segments an `<a>`
+   * carries and a tool argument does not — `/en/docs/intro` and `/docs/intro` are the same route.
+   */
+  static #linkTo(path: unknown): HTMLElement[] {
+    const wanted = AgentVisual.#routeOf(typeof path === "string" ? path : "");
+    if (!wanted || !document.body) return [];
+    const links = [...document.body.querySelectorAll<HTMLAnchorElement>("a[href]")].filter(
+      (link) =>
+        AgentVisual.#routeOf(link.getAttribute("href") ?? "") === wanted &&
+        ScreenTarget.visible(link) &&
+        ScreenFlash.inView(link),
+    );
+    return AgentVisual.#only(links);
+  }
+
+  static #routeOf(href: string) {
+    if (!href || href.startsWith("#")) return "";
+    try {
+      const url = new URL(href, window.location.href);
+      if (url.origin !== window.location.origin) return "";
+      return router.routeOf(url.pathname);
+    } catch {
+      return "";
+    }
+  }
+
+  static #navigating(name: string) {
+    return name.slice(name.lastIndexOf(".") + 1) === "navigate";
   }
 
   /** `fillTaskForm` → `taskForm`, which is what the fields of that form carry in `data-akan-state`. */
@@ -88,8 +192,9 @@ export class AgentVisual {
   }
 
   /**
-   * The batch is counted by the gap between calls rather than by a turn boundary, which no host reports here: a
-   * model's calls arrive back to back through one serialized queue, so a quiet second is the end of the batch.
+   * The turn is the batch, and `turn` resets this. The quiet-second timer stays as the fallback for a host that
+   * reports no turn at all — a model's calls arrive back to back through one serialized queue, so a second of
+   * quiet is the end of a batch even when nothing said so.
    */
   static #count() {
     AgentVisual.#revealed += 1;

package/store/agent/ScreenFlash.ts

@@ -24,8 +24,13 @@ export class ScreenFlash {
     ScreenFlash.ring(target);
   }
 
-  static reveal(target: HTMLElement) {
+  /** Answers which way the view travels, for whoever has to say that the scroll is the agent's doing. */
+  static reveal(target: HTMLElement): "up" | "down" {
+    const { top, height } = target.getBoundingClientRect();
+    const viewHeight = window.innerHeight || document.documentElement.clientHeight;
+    const way = top + height / 2 < viewHeight / 2 ? "up" : "down";
     target.scrollIntoView({ block: "center", behavior: "smooth" });
+    return way;
   }
 
   /**
@@ -40,6 +45,22 @@ export class ScreenFlash {
     return top >= margin && left >= 0 && bottom <= viewHeight - margin && right <= viewWidth;
   }
 
+  /**
+   * Whether the element is the one actually painted at its own centre, rather than merely present in the layout.
+   * `checkVisibility` answers about the element alone, so a control under a modal's backdrop, inside a drawer that
+   * has slid off, or faded to nothing all pass it while being invisible — and a pointer sent to one of those lands
+   * on a blank patch of overlay, which reads as the effect being broken rather than as the agent acting.
+   *
+   * An ancestor counts as a hit: a `<label>` wrapping its input is what the point belongs to, not an occlusion.
+   */
+  static onTop(target: HTMLElement) {
+    if (!ScreenFlash.inView(target)) return false;
+    if (typeof document.elementFromPoint !== "function") return true;
+    const { top, left, width, height } = target.getBoundingClientRect();
+    const hit = document.elementFromPoint(left + width / 2, top + height / 2);
+    return !!hit && (hit === target || target.contains(hit) || hit.contains(target));
+  }
+
   /**
    * The ring goes on once the scroll lands, not when it starts: a smooth scroll across a long page takes most of a
    * second, and a flash begun at the top is already fading by the time the user's eye arrives. Removed on a timer

package/store/agent/ScreenTarget.ts

@@ -33,7 +33,7 @@ export class ScreenTarget {
 
     return (
       ScreenTarget.#first(scope, selector) ??
-      [...scope.querySelectorAll<HTMLElement>("[id]")].find((el) => el.id === name && ScreenTarget.#visible(el)) ??
+      [...scope.querySelectorAll<HTMLElement>("[id]")].find((el) => el.id === name && ScreenTarget.visible(el)) ??
       null
     );
   }
@@ -51,7 +51,7 @@ export class ScreenTarget {
     if (!scope || !name) return [];
     const escaped = CSS.escape(name);
     const selector = controlAttrs.map((attr) => `[${attr}="${escaped}"]`).join(", ");
-    return [...scope.querySelectorAll<HTMLElement>(selector)].filter(ScreenTarget.#visible);
+    return [...scope.querySelectorAll<HTMLElement>(selector)].filter(ScreenTarget.visible);
   }
 
   /** Matched on letters and digits only, so a slug written for a heading still finds it. */
@@ -59,7 +59,7 @@ export class ScreenTarget {
     const scope = root ?? ScreenTarget.#body();
     const wanted = ScreenTarget.#slug(text);
     if (!scope || !wanted) return null;
-    const headings = [...scope.querySelectorAll<HTMLElement>(headingSelector)].filter(ScreenTarget.#visible);
+    const headings = [...scope.querySelectorAll<HTMLElement>(headingSelector)].filter(ScreenTarget.visible);
     return (
       headings.find((heading) => ScreenTarget.#slug(heading.textContent ?? "") === wanted) ??
       headings.find((heading) => ScreenTarget.#slug(heading.textContent ?? "").includes(wanted)) ??
@@ -88,7 +88,7 @@ export class ScreenTarget {
     if (!scope) return [];
     const names = new Set<string>();
     for (const heading of scope.querySelectorAll<HTMLElement>(headingSelector)) {
-      const anchor = ScreenTarget.#visible(heading) ? ScreenReader.anchorOf(heading) : "";
+      const anchor = ScreenTarget.visible(heading) ? ScreenReader.anchorOf(heading) : "";
       if (anchor) names.add(anchor);
     }
     return [...names];
@@ -109,7 +109,7 @@ export class ScreenTarget {
       const own = scope.getAttribute(attr);
       if (own) names.add(own);
       for (const el of scope.querySelectorAll<HTMLElement>(`[${attr}]`)) {
-        const value = ScreenTarget.#visible(el) ? el.getAttribute(attr) : null;
+        const value = ScreenTarget.visible(el) ? el.getAttribute(attr) : null;
         if (value) names.add(value);
       }
     }
@@ -121,10 +121,11 @@ export class ScreenTarget {
   }
 
   static #first(scope: HTMLElement, selector: string) {
-    return [...scope.querySelectorAll<HTMLElement>(selector)].find(ScreenTarget.#visible) ?? null;
+    return [...scope.querySelectorAll<HTMLElement>(selector)].find(ScreenTarget.visible) ?? null;
   }
 
-  static #visible(el: HTMLElement) {
+  /** The one rule for whether an element is something the user is actually looking at. */
+  static visible(el: HTMLElement) {
     if (el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true") return false;
     if (el.closest("[data-agent-ui]")) return false;
     return typeof el.checkVisibility === "function" ? el.checkVisibility() : true;

package/store/agent/StoreSurfaceSource.ts

@@ -70,6 +70,14 @@ export class StoreSurfaceSource implements SurfaceSource {
         const path = String(args.path);
         router.push(path);
 
+        try {
+          await router.navigation();
+        } catch {
+          throw new Error(
+            `There is no route at ${path}, so the page did not move. Call readScreen — it prints each link on this screen with its own path — and navigate to one of those.`,
+          );
+        }
+
         await ScreenSettle.wait({ appearMs: 800, timeoutMs: 5000 });
         return `Now on ${path}. Call readScreen to see it; this screen's own tools and state are listed from the next turn.`;
       },

package/types/client/router.d.ts

@@ -8,8 +8,9 @@ export interface DeepLinkOptions extends RouteOptions {
     resetStack?: boolean;
 }
 export interface RouterInstance {
-    push: (href: string, routeOptions?: RouteOptions) => void;
-    replace: (href: string, routeOptions?: RouteOptions) => void;
+    /** May answer a promise that rejects when the route refused to move — see `Router.navigation`. */
+    push: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
+    replace: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
     back: (routeOptions?: RouteOptions) => void;
     refresh: () => void;
 }
@@ -70,6 +71,15 @@ declare class Router {
     enterDeepLink(href: string, options?: DeepLinkOptions): boolean;
     push(href: string, routeOptions?: RouteOptions): never;
     replace(href: string, routeOptions?: RouteOptions): never;
+    /**
+     * The navigation `push` / `replace` last started, for a caller that has to know whether it landed. **Rejects
+     * when the route refused to move** — a target that resolves to nothing leaves the page where it was instead of
+     * replacing it, and `push` returns long before that is known, so this is the only place it can be reported.
+     *
+     * A method rather than a getter: `router` is a Proxy that binds functions to the real instance, and a getter
+     * reached through it would run with the Proxy as `this` and fail on the private field.
+     */
+    navigation(): Promise<void>;
     canGoBack(): boolean;
     backOrFallback(fallbackHref?: string, routeOptions?: RouteOptions): never;
     back(routeOptions?: RouteOptions): never;
@@ -77,6 +87,12 @@ declare class Router {
     redirect(href: string, options?: RedirectOptions): never;
     notFound(): never;
     setLang(lang: string): never;
+    /**
+     * A pathname with the locale and base-path segments taken off — the app-internal route it names, which is what
+     * a tool argument and a `<a href>` have in common. Unguarded, unlike `getPath`, whose default argument is the
+     * one thing in it that needs a browser.
+     */
+    routeOf(pathname: string): string;
     getPath(pathname?: string): string;
     getFullPath(withLang?: boolean): string;
     getPrefix(): string;

package/types/server/rscClientFetch.d.ts

@@ -10,6 +10,8 @@ export type RscClientFetchResponseResult = {
     type: "patch";
     response: Response;
     patch: AkanRscPatchMetadata;
+} | {
+    type: "not-found";
 } | {
     type: "redirected";
     status?: number;

package/types/store/agent/AgentCursor.d.ts

@@ -17,9 +17,32 @@ export declare class AgentCursor {
     static readonly travelMs = 320;
     /** Under this far, the glide is skipped: a third of a second to cross fifty pixels reads as lag, not motion. */
     static readonly travelFrom = 200;
-    /** How long after the last call the pointer stays before fading — one batch's gap, not one call's. */
+    /** How far off the control the pointer drifts before it starts waiting — just clear of its box. */
+    static readonly driftBy = 18;
+    /**
+     * How long after the last call the pointer stays before fading, for a host that reports no turn boundary. A
+     * host that does calls `hold` instead, because this is the wrong unit: between two calls of one turn the model
+     * is writing, which takes longer than this, and the pointer used to vanish and come back for every call.
+     */
     static readonly idleMs = 1400;
-    /** Travels to the control once it has stopped moving, then presses it. */
-    static press(target: HTMLElement): void;
+    static readonly thinkingClass = "akan-agent-cursor-thinking";
+    static readonly scrollingClass = "akan-agent-cursor-scrolling";
+    /** Travels to the control once it has stopped moving, then presses it. Resolves when the press has landed. */
+    static press(target: HTMLElement): Promise<void>;
+    /**
+     * The page is being scrolled and the pointer is what is doing it. It stays put while the content moves, the way
+     * a person's does — what the chevron adds is who asked, since a pointer standing still over a page that slides
+     * under it otherwise reads as one that has come loose from the screen.
+     */
+    static scroll(way: "up" | "down"): void;
+    /** Keeps the pointer up for as long as the turn runs, instead of for `idleMs` after the last call. */
+    static hold(): void;
+    static release(): void;
+    /**
+     * Waiting rather than acting: the pointer drifts clear of what it just pressed and the arrow gives way to a
+     * spinner. Does nothing before the first press — an agent that drives no control has no place on the screen to
+     * be, and a pointer parked in a corner for a turn that only answered a question would be saying something untrue.
+     */
+    static think(): void;
     static hide(): void;
 }

package/types/store/agent/AgentVisual.d.ts

@@ -17,8 +17,13 @@ export interface AgentVisualOption {
  * Nothing here is ever waited on. A call starts the moment the event is handed over; the ring catching up a frame
  * later costs the turn nothing, and an animation that held a call would make the agent slower for a decoration.
  *
- * A call that lands on no control draws nothing, `navigate` included: the router is not an element, and the
- * top-of-page bar tried for it read as chrome the page had grown rather than as the agent doing something.
+ * A call that lands on no control draws nothing. That still covers most of `navigate` — the router is not an
+ * element, and the top-of-page bar tried for it read as chrome the page had grown rather than as the agent doing
+ * something — but a destination the screen already offers as a link is an element, and that one is pressed.
+ *
+ * The pointer's unit is the **turn**, not the call. A model's calls arrive with its own writing between them, so
+ * a pointer that lived for a call's length spent every turn disappearing and coming back; between calls it waits
+ * where it last acted, as a spinner, and goes when the turn does.
  */
 export declare class AgentVisual {
     #private;
@@ -30,7 +35,20 @@ export declare class AgentVisual {
     static readonly revealCap = 4;
     /** How many of a form patch's fields are drawn. A patch of twenty is a form being filled, not twenty events. */
     static readonly fieldCap = 5;
-    /** The handler `agentSessionOf` hands the session. `true` is every effect; an object turns one of them off. */
-    static sink(option?: boolean | AgentVisualOption): ((event: ToolActivity) => void) | undefined;
-    static on(event: ToolActivity, { reveal, cursor }?: AgentVisualOption): void;
+    /**
+     * The longest a call is held for the drawing that has to precede it. Every millisecond here is one the agent
+     * spends on a decoration, so the press is given time to land and the call goes either way.
+     */
+    static readonly leadMs = 600;
+    /** The handlers `agentSessionOf` hands the session. `true` is every effect; an object turns one of them off. */
+    static sink(option?: boolean | AgentVisualOption): {
+        onActivity: (event: ToolActivity) => void | Promise<void>;
+        onTurn: (running: boolean) => void;
+    } | undefined;
+    /**
+     * The boundary the pointer lives between, and the one the scroll budget is spent in. Raising a pointer here
+     * would be a pointer with nowhere to point yet, so the turn's start only resets what the last turn used.
+     */
+    static turn(running: boolean, { cursor }?: AgentVisualOption): void;
+    static on(event: ToolActivity, { reveal, cursor }?: AgentVisualOption): void | Promise<void>;
 }

package/types/store/agent/ScreenFlash.d.ts

@@ -19,12 +19,22 @@ export declare class ScreenFlash {
     static readonly actingClass = "akan-agent-acting";
     static readonly actingMs = 1000;
     static show(target: HTMLElement): void;
-    static reveal(target: HTMLElement): void;
+    /** Answers which way the view travels, for whoever has to say that the scroll is the agent's doing. */
+    static reveal(target: HTMLElement): "up" | "down";
     /**
      * Whether the element is far enough inside the viewport to be looked at, not merely intersecting it: a button
      * whose bottom pixel is on screen is one the user cannot read, and a ring there points at nothing.
      */
     static inView(target: HTMLElement, margin?: number): boolean;
+    /**
+     * Whether the element is the one actually painted at its own centre, rather than merely present in the layout.
+     * `checkVisibility` answers about the element alone, so a control under a modal's backdrop, inside a drawer that
+     * has slid off, or faded to nothing all pass it while being invisible — and a pointer sent to one of those lands
+     * on a blank patch of overlay, which reads as the effect being broken rather than as the agent acting.
+     *
+     * An ancestor counts as a hit: a `<label>` wrapping its input is what the point belongs to, not an occlusion.
+     */
+    static onTop(target: HTMLElement): boolean;
     /**
      * The ring goes on once the scroll lands, not when it starts: a smooth scroll across a long page takes most of a
      * second, and a flash begun at the top is already fading by the time the user's eye arrives. Removed on a timer

package/types/store/agent/ScreenTarget.d.ts

@@ -36,4 +36,6 @@ export declare class ScreenTarget {
     static containerNames(root?: HTMLElement | null): string[];
     static anchorNames(root?: HTMLElement | null): string[];
     static targetNames(root?: HTMLElement | null): string[];
+    /** The one rule for whether an element is something the user is actually looking at. */
+    static visible(el: HTMLElement): boolean;
 }

package/types/ui/Agent/Chat.d.ts

@@ -41,9 +41,10 @@ export interface ChatProps {
     onOpenChange?: (open: boolean) => void;
     /**
      * What the page itself draws while this agent drives it: the control a call was published from is ringed where
-     * it stands, and a pointer presses it. On by default — the chat panel is closed as often as it is open, and
-     * a change nothing attributes is one the user watches happen for no reason they can see. `false` draws nothing,
-     * and an object turns one effect off (`visual={{ cursor: false }}`).
+     * it stands, and a pointer presses it, waits out the model's turn as a spinner where it landed, and goes when
+     * the turn ends. On by default — the chat panel is closed as often as it is open, and a change nothing
+     * attributes is one the user watches happen for no reason they can see. `false` draws nothing, and an object
+     * turns one effect off (`visual={{ cursor: false }}` keeps the ring, `{ reveal: false }` keeps the pointer).
      */
     visual?: boolean | AgentVisualOption;
     /** `false` draws no launcher, for an app that opens the panel from a control of its own. */

package/types/ui/Agent/Zone.d.ts

@@ -29,9 +29,10 @@ export interface ZoneProps {
     onCompact?: AgentSessionOptions["onCompact"];
     /**
      * What the page itself draws while this agent drives it: the control a call was published from is ringed where
-     * it stands, and a pointer presses it. On by default — the chat panel is closed as often as it is open, and
-     * a change nothing attributes is one the user watches happen for no reason they can see. `false` draws nothing,
-     * and an object turns one effect off (`visual={{ cursor: false }}`).
+     * it stands, and a pointer presses it, waits out the model's turn as a spinner where it landed, and goes when
+     * the turn ends. On by default — the chat panel is closed as often as it is open, and a change nothing
+     * attributes is one the user watches happen for no reason they can see. `false` draws nothing, and an object
+     * turns one effect off (`visual={{ cursor: false }}` keeps the ring, `{ reveal: false }` keeps the pointer).
      */
     visual?: boolean | AgentVisualOption;
     /**

package/types/ui/agentAttrs.d.ts

@@ -7,8 +7,13 @@
  *
  * What it buys, beyond an in-page agent: an accessibility tree and E2E selectors that name the action rather than a
  * class, and an external browser agent — one this framework has no bridge into — reading the same names.
+ *
+ * `key` is for a control that shares its handler with its siblings — a tab's menus, a list's rows — and names
+ * which one of them this is, in the same vocabulary the call's argument uses. Without it every namesake is
+ * interchangeable in the DOM, so the page can say *what* the agent did but never *where*.
  */
-export declare const agentAttrs: (handler: unknown) => {
+export declare const agentAttrs: (handler: unknown, key?: string | number) => {
     "data-akan-action"?: string;
     "data-akan-state"?: string;
+    "data-akan-key"?: string;
 } | Record<string, never>;

package/types/vendor/use-agentic/AgentSession.d.ts

@@ -81,7 +81,16 @@ export interface AgentSessionOptions {
      * The session keeps none of it: nothing here is transcript, and holding it would mean a re-render per call for
      * something no message renders.
      */
-    onActivity?: (event: ToolActivity) => void;
+    onActivity?: (event: ToolActivity) => void | Promise<void>;
+    /**
+     * Called when a turn starts and when it settles — the boundary a host draws the agent's own presence in. The
+     * calls of one turn arrive with model turns between them, seconds long, so anything measured in the gap
+     * between *calls* keeps ending and restarting inside a turn that never stopped.
+     *
+     * Only the conversation loop reports here. `compact` runs under the same flag and drives nothing on screen, so
+     * a host drawing the agent at work would draw it for a summary nobody asked to watch.
+     */
+    onTurn?: (running: boolean) => void;
 }
 /**
  * The client-side conversation loop: send → model turn → tool calls → approval gate → execute → report diffs → next

package/types/vendor/use-agentic/ToolRunner.d.ts

@@ -36,8 +36,12 @@ export interface ToolRunnerHost {
      * That a call is running, for a host drawing it on the page rather than in a transcript. Separate from
      * `progress`, which only ever fires for a tool that chose to report: a call the user has to be told about is
      * every call, and one that says nothing about itself is exactly the one whose effect arrives unexplained.
+     *
+     * **The `start` is awaited**, so a host may draw something that has to land before the call does — a pointer
+     * pressing the link a `navigate` is about to follow is drawing on an element the router would otherwise have
+     * replaced first. The host owns the deadline: a decoration that takes its time makes the agent take its time.
      */
-    activity?: (event: ToolActivity) => void;
+    activity?: (event: ToolActivity) => void | Promise<void>;
     /**
      * Answers a name the surface does not carry — where a consumer puts a built-in of its own. Reached only after
      * the surface came up empty, so a registered tool of the same name shadows it.

package/ui/Agent/Chat.tsx

@@ -82,9 +82,10 @@ export interface ChatProps {
   onOpenChange?: (open: boolean) => void;
   /**
    * What the page itself draws while this agent drives it: the control a call was published from is ringed where
-   * it stands, and a pointer presses it. On by default — the chat panel is closed as often as it is open, and
-   * a change nothing attributes is one the user watches happen for no reason they can see. `false` draws nothing,
-   * and an object turns one effect off (`visual={{ cursor: false }}`).
+   * it stands, and a pointer presses it, waits out the model's turn as a spinner where it landed, and goes when
+   * the turn ends. On by default — the chat panel is closed as often as it is open, and a change nothing
+   * attributes is one the user watches happen for no reason they can see. `false` draws nothing, and an object
+   * turns one effect off (`visual={{ cursor: false }}` keeps the ring, `{ reveal: false }` keeps the pointer).
    */
   visual?: boolean | AgentVisualOption;
   /** `false` draws no launcher, for an app that opens the panel from a control of its own. */

package/ui/Agent/Zone.tsx

@@ -44,9 +44,10 @@ export interface ZoneProps {
   onCompact?: AgentSessionOptions["onCompact"];
   /**
    * What the page itself draws while this agent drives it: the control a call was published from is ringed where
-   * it stands, and a pointer presses it. On by default — the chat panel is closed as often as it is open, and
-   * a change nothing attributes is one the user watches happen for no reason they can see. `false` draws nothing,
-   * and an object turns one effect off (`visual={{ cursor: false }}`).
+   * it stands, and a pointer presses it, waits out the model's turn as a spinner where it landed, and goes when
+   * the turn ends. On by default — the chat panel is closed as often as it is open, and a change nothing
+   * attributes is one the user watches happen for no reason they can see. `false` draws nothing, and an object
+   * turns one effect off (`visual={{ cursor: false }}` keeps the ring, `{ reveal: false }` keeps the pointer).
    */
   visual?: boolean | AgentVisualOption;
   /**

package/ui/Agent/agentSessionOf.ts

@@ -50,7 +50,7 @@ export const agentSessionOf = ({
 }: AgentSessionSetup): AgentSession => {
   const { surface } = ensureStoreSurface();
   const history = sessionHistoryOf(persist, view.join("."));
-  const onActivity = AgentVisual.sink(visual);
+  const drawing = AgentVisual.sink(visual);
   return new AgentSession(sessionView(surface, view, builtins), runner ?? fetchRunner(), {
     buildContext: (scoped) => AgentContext.of().blocks(scoped, view),
     settle: () => ScreenSettle.wait(),
@@ -60,6 +60,6 @@ export const agentSessionOf = ({
     ...(compact ? { compact } : {}),
     ...(history ? { history } : {}),
     ...(onCompact ? { onCompact } : {}),
-    ...(onActivity ? { onActivity } : {}),
+    ...(drawing ?? {}),
   });
 };

package/ui/System/Client.tsx

@@ -346,7 +346,14 @@ export const ClientSsrBridge = ({ lang, prefix = "", initialPageState }: ClientS
         fallback();
         return;
       }
-      void navigation.catch((error) => {
+      return navigation.catch((error: unknown) => {
+        
+        if (error instanceof Error && error.name === "RscRouteNotFound") {
+
+          syncHref(window.location.href);
+          Logger.error(`No route at ${href}; the page was left where it was.`);
+          throw error;
+        }
         Logger.warn(`RSC navigation failed, falling back to document navigation: ${String(error)}`);
         fallback();
       });
@@ -370,11 +377,11 @@ export const ClientSsrBridge = ({ lang, prefix = "", initialPageState }: ClientS
       router: {
         push: (href, routeOptions) => {
           syncHref(href);
-          navigateRscWithFallback(href, routeOptions, () => window.location.assign(href));
+          return navigateRscWithFallback(href, routeOptions, () => window.location.assign(href));
         },
         replace: (href, routeOptions) => {
           syncHref(href);
-          navigateRscWithFallback(href, { ...routeOptions, replace: true }, () => window.location.replace(href));
+          return navigateRscWithFallback(href, { ...routeOptions, replace: true }, () => window.location.replace(href));
         },
         back: () => {
           window.history.back();

package/ui/Tab/Menu.tsx

@@ -59,7 +59,7 @@ export const Menu = ({
           switchTab(menu);
           if (scrollToTop) window.scrollTo({ top: 0, behavior: "smooth" });
         }}
-        {...agentAttrs(switchTab)}
+        {...agentAttrs(switchTab, menu)}
         role="tab"
         type="button"
       >

package/ui/agentAttrs.ts

@@ -9,11 +9,20 @@ import { actionTagOf } from "akanjs/store";
  *
  * What it buys, beyond an in-page agent: an accessibility tree and E2E selectors that name the action rather than a
  * class, and an external browser agent — one this framework has no bridge into — reading the same names.
+ *
+ * `key` is for a control that shares its handler with its siblings — a tab's menus, a list's rows — and names
+ * which one of them this is, in the same vocabulary the call's argument uses. Without it every namesake is
+ * interchangeable in the DOM, so the page can say *what* the agent did but never *where*.
  */
 export const agentAttrs = (
   handler: unknown,
-): { "data-akan-action"?: string; "data-akan-state"?: string } | Record<string, never> => {
+  key?: string | number,
+): { "data-akan-action"?: string; "data-akan-state"?: string; "data-akan-key"?: string } | Record<string, never> => {
   const tag = actionTagOf(handler);
   if (!tag) return {};
-  return { "data-akan-action": tag.action, ...(tag.state ? { "data-akan-state": tag.state } : {}) };
+  return {
+    "data-akan-action": tag.action,
+    ...(tag.state ? { "data-akan-state": tag.state } : {}),
+    ...(key === undefined || key === "" ? {} : { "data-akan-key": String(key) }),
+  };
 };

package/ui/styles.css

@@ -451,6 +451,89 @@ body.akan-mobile-document {
   animation: akanAgentTap 450ms ease-out;
 }
 
+/*
+ * Between two calls of one turn the model is writing, which takes longer than a pointer sitting still reads as.
+ * The arrow gives way to a spinner in place, so the pause is the agent thinking rather than the pointer stuck.
+ */
+.akan-agent-cursor-thinking > i {
+  opacity: 0;
+}
+
+.akan-agent-cursor-thinking > b {
+  width: 1.125rem;
+  height: 1.125rem;
+  margin: -0.5625rem 0 0 -0.5625rem;
+  opacity: 1;
+  border-color: color-mix(in oklab, var(--color-primary) 25%, transparent);
+  border-top-color: var(--color-primary);
+  animation: akanAgentThinking 700ms linear infinite;
+}
+
+@keyframes akanAgentThinking {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/*
+ * The pointer holds still while a reveal scrolls the page under it, exactly as a person's does — so on its own the
+ * stillness reads as a pointer that came loose. The chevron is what says the scroll is the agent's, and it points
+ * the way the view is travelling.
+ */
+.akan-agent-cursor::after {
+  content: "";
+  position: absolute;
+  top: 22px;
+  left: 1px;
+  width: 9px;
+  height: 9px;
+  border-right: 2px solid var(--color-primary);
+  border-bottom: 2px solid var(--color-primary);
+  opacity: 0;
+  transform: rotate(45deg);
+}
+
+.akan-agent-cursor-scrolling::after {
+  animation: akanAgentScrollDown 800ms ease-in-out infinite;
+}
+
+.akan-agent-cursor-scrolling-up::after {
+  animation-name: akanAgentScrollUp;
+}
+
+.akan-agent-cursor-thinking::after {
+  animation: none;
+  opacity: 0;
+}
+
+@keyframes akanAgentScrollDown {
+  0% {
+    transform: rotate(45deg) translate(-4px, -4px);
+    opacity: 0;
+  }
+  45% {
+    opacity: 1;
+  }
+  100% {
+    transform: rotate(45deg) translate(4px, 4px);
+    opacity: 0;
+  }
+}
+
+@keyframes akanAgentScrollUp {
+  0% {
+    transform: rotate(225deg) translate(-4px, -4px);
+    opacity: 0;
+  }
+  45% {
+    opacity: 1;
+  }
+  100% {
+    transform: rotate(225deg) translate(4px, 4px);
+    opacity: 0;
+  }
+}
+
 @keyframes akanAgentTap {
   0% {
     transform: scale(0.2);
@@ -472,6 +555,16 @@ body.akan-mobile-document {
   .akan-agent-cursor {
     transition: opacity 200ms ease-out;
   }
+
+  /* The chevron holds its direction instead of sliding: the way the view is going is the part that carries. */
+  .akan-agent-cursor-scrolling::after {
+    animation: none;
+    opacity: 1;
+  }
+
+  .akan-agent-cursor-scrolling-up::after {
+    transform: rotate(225deg);
+  }
 }
 
 @keyframes spin {

package/vendor/use-agentic/AgentSession.ts

@@ -98,7 +98,16 @@ export interface AgentSessionOptions {
    * The session keeps none of it: nothing here is transcript, and holding it would mean a re-render per call for
    * something no message renders.
    */
-  onActivity?: (event: ToolActivity) => void;
+  onActivity?: (event: ToolActivity) => void | Promise<void>;
+  /**
+   * Called when a turn starts and when it settles — the boundary a host draws the agent's own presence in. The
+   * calls of one turn arrive with model turns between them, seconds long, so anything measured in the gap
+   * between *calls* keeps ending and restarting inside a turn that never stopped.
+   *
+   * Only the conversation loop reports here. `compact` runs under the same flag and drives nothing on screen, so
+   * a host drawing the agent at work would draw it for a summary nobody asked to watch.
+   */
+  onTurn?: (running: boolean) => void;
 }
 
 /**
@@ -365,6 +374,7 @@ export class AgentSession {
   async #turn(input: string | ChatMessage[]) {
     const controller = new AbortController();
     this.#controller = controller;
+    this.#options.onTurn?.(true);
     if (typeof input === "string") this.#append({ role: "user", text: input });
     else for (const message of input) this.#append(message);
     const maxTurns = this.#options.maxTurns ?? 12;
@@ -420,6 +430,7 @@ export class AgentSession {
 
       const draft = this.#messages[this.#messages.length - 1];
       if (draft?.role === "assistant" && !Transcript.carries(draft)) this.#messages = this.#messages.slice(0, -1);
+      this.#options.onTurn?.(false);
       this.#notify();
     }
   }

package/vendor/use-agentic/ToolRunner.ts

@@ -41,8 +41,12 @@ export interface ToolRunnerHost {
    * That a call is running, for a host drawing it on the page rather than in a transcript. Separate from
    * `progress`, which only ever fires for a tool that chose to report: a call the user has to be told about is
    * every call, and one that says nothing about itself is exactly the one whose effect arrives unexplained.
+   *
+   * **The `start` is awaited**, so a host may draw something that has to land before the call does — a pointer
+   * pressing the link a `navigate` is about to follow is drawing on an element the router would otherwise have
+   * replaced first. The host owns the deadline: a decoration that takes its time makes the agent take its time.
    */
-  activity?: (event: ToolActivity) => void;
+  activity?: (event: ToolActivity) => void | Promise<void>;
   /**
    * Answers a name the surface does not carry — where a consumer puts a built-in of its own. Reached only after
    * the surface came up empty, so a registered tool of the same name shadows it.
@@ -109,7 +113,7 @@ export class ToolRunner {
     const base = { id: call.id, name: call.name };
     const before = this.#surface.snapshot();
     
-    this.#host.activity?.({ callId: call.id, name: call.name, args: call.args, phase: "start" });
+    await this.#host.activity?.({ callId: call.id, name: call.name, args: call.args, phase: "start" });
     let failed: string | undefined;
     try {
       const result = await AgentAbort.run(signal, () =>