akanjs 3.0.0-alpha.29 → 3.0.0-alpha.30

package/dictionary/base.dictionary.ts

@@ -52,8 +52,13 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     agentIntro: ["Ask about this page or tell the agent what to do.", "이 화면에 대해 묻거나 할 일을 지시해 보세요."],
     agentPlaceholder: ["Message the agent...", "에이전트에게 메시지..."],
     agentClear: ["Clear conversation", "대화 비우기"],
+    agentQuestion: ["The agent needs your decision", "에이전트가 결정을 요청합니다"],
+    agentAnswer: ["Type your answer...", "답변을 입력하세요..."],
+    agentContinue: ["This is taking a while. Keep going?", "시간이 걸리고 있습니다. 계속할까요?"],
+    agentKeepGoing: ["Keep going", "계속하기"],
     send: ["Send", "보내기"],
     stop: ["Stop", "중지"],
+    skip: ["Skip", "건너뛰기"],
     approve: ["Approve", "승인"],
     decline: ["Decline", "거절"],
     confirmClose: ["Are you sure you want to close the modal?", "모달을 닫으시겠습니까?"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.29",
+  "version": "3.0.0-alpha.30",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/store/agent/ScreenReader.ts

@@ -12,6 +12,7 @@ const skipTags = new Set([
   "EMBED",
 ]);
 const headingLevels = { H1: 1, H2: 2, H3: 3, H4: 4, H5: 5, H6: 6 } as const;
+const headingSelector = "h1, h2, h3, h4, h5, h6";
 const blockTags = new Set([
   "ADDRESS",
   "ARTICLE",
@@ -46,9 +47,14 @@ const blockTags = new Set([
 
 /**
  * Serializes what the page is rendering into compact text an agent can answer questions from: headings keep their
- * level, links keep their href, controls keep their value and `data-akan-*` annotation. The agent's own UI is
- * marked `data-agent-ui` and skipped, so a turn never re-reads its own transcript, and a password value is never
- * read — the screen shows dots, so the DOM holds more than the user sees.
+ * level and their anchor, links keep their href, controls keep their value and `data-akan-*` annotation. The
+ * agent's own UI is marked `data-agent-ui` and skipped, so a turn never re-reads its own transcript, and a
+ * password value is never read — the screen shows dots, so the DOM holds more than the user sees.
+ *
+ * A heading carries `(#anchor)` whenever it opens a container that has an id or a scope path, because that is the
+ * name `readScreen({ section })` and `highlight` take: printing the text without the name leaves an agent
+ * guessing at a slug. For the same reason a truncated read ends with the headings below the cut instead of only
+ * a character count — otherwise everything past the limit is unreachable, since nothing names it.
  */
 export class ScreenReader {
   static readonly limit = 8000;
@@ -60,17 +66,108 @@ export class ScreenReader {
     if (title) reader.#lines.push(`Page: ${title}`);
     reader.#walk(root ?? document.body);
     reader.#flush();
-    const text = reader.#lines.join("\n").trim();
-    if (text.length <= ScreenReader.limit) return text || "The page is rendering nothing readable.";
-    return `${text.slice(0, ScreenReader.limit)}… [truncated ${text.length - ScreenReader.limit} more characters]`;
+    return reader.#text() || "The page is rendering nothing readable.";
+  }
+
+  /**
+   * One heading's own section: the heading, then what follows it until the next heading of the same level or
+   * higher. Reads the heading's container when the heading is the only one in it — the shape a docs slide or an
+   * `<article>` has — and otherwise the heading's own following siblings.
+   */
+  static readFrom(heading: HTMLElement, root?: HTMLElement | null): string {
+    if (typeof document === "undefined") return "No rendered document is available.";
+    const reader = new ScreenReader();
+    const container = ScreenReader.#sectionOf(heading, root);
+    if (container) reader.#walk(container);
+    else {
+      const level = headingLevels[heading.tagName.toUpperCase() as keyof typeof headingLevels] ?? 1;
+      reader.#walk(heading);
+      let next = heading.nextElementSibling;
+      while (next && !ScreenReader.#stops(next, level)) {
+        reader.#walk(next);
+        next = next.nextElementSibling;
+      }
+    }
+    reader.#flush();
+    return reader.#text() || "That section is rendering nothing readable.";
+  }
+
+  /**
+   * The outermost ancestor that still holds this heading and no other of its level — the section, not the title
+   * wrapper inside it. Climbing matters: a docs slide puts its heading two or three divs down, so the innermost
+   * match is often the heading and nothing else.
+   */
+  static #sectionOf(heading: HTMLElement, root?: HTMLElement | null): HTMLElement | null {
+    const level = headingLevels[heading.tagName.toUpperCase() as keyof typeof headingLevels] ?? 1;
+    const boundary = root ?? document.body;
+    let container: HTMLElement | null = null;
+    let parent = heading.parentElement;
+    for (let depth = 0; parent && parent !== boundary && depth < 6; depth += 1) {
+      const owned = [...parent.querySelectorAll(headingSelector)].filter((found) => ScreenReader.#stops(found, level));
+      if (owned.length !== 1) break;
+      container = parent;
+      parent = parent.parentElement;
+    }
+    return container;
+  }
+
+  /** The anchor a heading is addressable by: its own id, or the id or scope path of the container it opens. */
+  static anchorOf(heading: HTMLElement): string {
+    if (heading.id) return heading.id;
+    let parent = heading.parentElement;
+    for (let depth = 0; parent && depth < 4; depth += 1) {
+      const name = parent.getAttribute("data-agent-scope") ?? parent.getAttribute("data-agent-zone") ?? parent.id;
+      if (name && parent.querySelector(headingSelector) === heading) return name;
+      parent = parent.parentElement;
+    }
+    return "";
+  }
+
+  static #stops(el: Element, level: number) {
+    const found = headingLevels[el.tagName.toUpperCase() as keyof typeof headingLevels];
+    return !!found && found <= level;
   }
 
   #lines: string[] = [];
+  #headings: string[] = [];
   #buffer = "";
   #length = 0;
 
+  /**
+   * Past the walk budget the text is dropped but the headings are not: a section below the cut is exactly what the
+   * truncation note owes the reader, and it is the only way that part of the screen can be named at all.
+   */
+  #outline(node: Node): void {
+    if (node.nodeType !== Node.ELEMENT_NODE) return;
+    const el = node as HTMLElement;
+    const tag = el.tagName.toUpperCase();
+    if (skipTags.has(tag) || el.hasAttribute("data-agent-ui")) return;
+    const level = headingLevels[tag as keyof typeof headingLevels];
+    if (level) {
+      const anchor = ScreenReader.anchorOf(el);
+      const text = (el.textContent ?? "").replace(/\s+/g, " ").trim();
+      if (text) this.#headings.push(`${"#".repeat(level)} ${text}${anchor ? ` (#${anchor})` : ""}`);
+      return;
+    }
+    for (const child of el.childNodes) this.#outline(child);
+  }
+
+  #text() {
+    const text = this.#lines.join("\n").trim();
+    if (text.length <= ScreenReader.limit) return text;
+    const kept = text.slice(0, ScreenReader.limit);
+    const below = this.#headings.filter((heading) => !kept.includes(heading)).slice(0, 25);
+    const note = `… [truncated ${text.length - ScreenReader.limit} more characters]`;
+    return below.length
+      ? `${kept}${note}\nFurther down, unread: ${below.join(" · ")}. Pass one of those names as \`section\` to read it.`
+      : `${kept}${note}`;
+  }
+
   #walk(node: Node): void {
-    if (this.#length > ScreenReader.limit * 2) return;
+    if (this.#length > ScreenReader.limit * 2) {
+      this.#outline(node);
+      return;
+    }
     if (node.nodeType === Node.TEXT_NODE) {
       const text = (node.textContent ?? "").replace(/\s+/g, " ");
       if (text.trim()) this.#buffer += text;
@@ -112,7 +209,11 @@ export class ScreenReader {
     if (level) {
       this.#flush();
       this.#walkChildren(el);
+      const anchor = ScreenReader.anchorOf(el);
+      if (anchor) this.#buffer += ` (#${anchor})`;
+      const before = this.#lines.length;
       this.#flush(`${"#".repeat(level)} `);
+      if (this.#lines.length > before) this.#headings.push(this.#lines[this.#lines.length - 1]);
       return;
     }
     if (tag === "LI") {

package/store/agent/ScreenSettle.ts

@@ -0,0 +1,45 @@
+export interface ScreenSettleOptions {
+  /** How long the DOM must hold still before the screen counts as settled. */
+  quietMs?: number;
+  /** How long to wait for a change that has not started yet — a navigation whose payload is still in flight. */
+  appearMs?: number;
+  timeoutMs?: number;
+}
+
+/**
+ * Waits until the screen stops changing.
+ *
+ * The surface is read synchronously and the app is not: `router.push` returns while the RSC payload for the new
+ * route is still in flight, and a store action that fires `void fetch.*` commits a tick later. A tool that returns
+ * at either of those moments reports the screen it replaced — and the `readScreen` the agent calls next reads the
+ * page the user already left.
+ *
+ * Quiescence rather than a framework signal, because there is no one signal: the client router hands its promise
+ * to nobody, and a change may land in the store, in a refetch, or in a streamed Suspense boundary. A
+ * MutationObserver sees all three, and every wait is bounded — a screen that never holds still still answers.
+ */
+export class ScreenSettle {
+  static wait({ quietMs = 120, appearMs = 0, timeoutMs = 3000 }: ScreenSettleOptions = {}): Promise<void> {
+    const body = typeof document === "undefined" ? null : (document.body ?? document.documentElement);
+    if (!body || typeof MutationObserver === "undefined") return Promise.resolve();
+    return new Promise((resolve) => {
+      let quiet: ReturnType<typeof setTimeout> | null = null;
+      const done = () => {
+        if (quiet) clearTimeout(quiet);
+        clearTimeout(deadline);
+        observer.disconnect();
+        resolve();
+      };
+      const rearm = () => {
+        if (quiet) clearTimeout(quiet);
+        quiet = setTimeout(done, quietMs);
+      };
+      const observer = new MutationObserver(rearm);
+      const deadline = setTimeout(done, timeoutMs);
+      observer.observe(body, { attributes: true, characterData: true, childList: true, subtree: true });
+
+      if (appearMs) quiet = setTimeout(done, appearMs);
+      else rearm();
+    });
+  }
+}

package/store/agent/ScreenTarget.ts

@@ -0,0 +1,129 @@
+import { ScreenReader } from "./ScreenReader";
+
+const containerAttrs = ["data-agent-zone", "data-agent-scope"] as const;
+const controlAttrs = ["data-akan-action", "data-akan-state"] as const;
+const headingSelector = "h1, h2, h3, h4, h5, h6";
+const nameCap = 40;
+
+/**
+ * Resolves a name the agent read on screen to the element it names.
+ *
+ * Four vocabularies, every one of them something already on the screen rather than a selector the model invented:
+ * the `data-akan-action` / `data-akan-state` annotation a control carries and `readScreen` prints beside it, an
+ * `Agent.Zone` or `useScreenScope` container, a plain element id — what a docs slide is addressed by — and, last, a
+ * **heading by its own text**.
+ *
+ * A heading is matched on letters and digits alone, so the slug an agent naturally writes for a heading it read
+ * ("images-and-public-env") finds "Images And Public Env". That tolerance is for headings only: a heading is a
+ * landmark and scrolling to the wrong one costs nothing, while two buttons reading "Save" are not the same control
+ * and matching a *control* by its label would drive the wrong one.
+ *
+ * Nothing hidden ever resolves, by the same rule `readScreen` skips it. A collapsed panel or an off-variant
+ * duplicate is not what the user is looking at, and scrolling to one flashes a ring nobody can see — which reads
+ * as the tool being broken rather than as a miss.
+ */
+export class ScreenTarget {
+  static container(name: string, root?: HTMLElement | null): HTMLElement | null {
+    const scope = root ?? ScreenTarget.#body();
+    if (!scope || !name) return null;
+    if (ScreenTarget.#named(scope, containerAttrs, name)) return scope;
+    const escaped = CSS.escape(name);
+    const selector = [...containerAttrs.map((attr) => `[${attr}="${escaped}"]`), `#${escaped}`].join(", ");
+    return ScreenTarget.#first(scope, selector);
+  }
+
+  static control(name: string, root?: HTMLElement | null): HTMLElement | null {
+    const scope = root ?? ScreenTarget.#body();
+    if (!scope || !name) return null;
+    const escaped = CSS.escape(name);
+    return ScreenTarget.#first(scope, controlAttrs.map((attr) => `[${attr}="${escaped}"]`).join(", "));
+  }
+
+  /** Matched on letters and digits only, so a slug written for a heading still finds it. */
+  static heading(text: string, root?: HTMLElement | null): HTMLElement | null {
+    const scope = root ?? ScreenTarget.#body();
+    const wanted = ScreenTarget.#slug(text);
+    if (!scope || !wanted) return null;
+    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)) ??
+      null
+    );
+  }
+
+  /** A control first — an annotated button is the most specific match — then a container, then a heading. */
+  static find(name: string, root?: HTMLElement | null): HTMLElement | null {
+    return ScreenTarget.control(name, root) ?? ScreenTarget.container(name, root) ?? ScreenTarget.heading(name, root);
+  }
+
+  /**
+   * The names a refusal can honestly offer for a region: the scope paths, plus every heading anchor on screen.
+   * Leaving the anchors out is what let a page of twenty named sections answer "nothing carries a name".
+   */
+  static containerNames(root?: HTMLElement | null): string[] {
+    return [...new Set([...ScreenTarget.#names(containerAttrs, root), ...ScreenTarget.anchorNames(root)])].slice(
+      0,
+      nameCap,
+    );
+  }
+
+  static anchorNames(root?: HTMLElement | null): string[] {
+    const scope = root ?? ScreenTarget.#body();
+    if (!scope) return [];
+    const names = new Set<string>();
+    for (const heading of scope.querySelectorAll<HTMLElement>(headingSelector)) {
+      const anchor = ScreenTarget.#visible(heading) ? ScreenReader.anchorOf(heading) : "";
+      if (anchor) names.add(anchor);
+    }
+    return [...names];
+  }
+
+  static targetNames(root?: HTMLElement | null): string[] {
+    return [...new Set([...ScreenTarget.#names(controlAttrs, root), ...ScreenTarget.containerNames(root)])].slice(
+      0,
+      nameCap,
+    );
+  }
+
+  static #names(attrs: readonly string[], root?: HTMLElement | null): string[] {
+    const scope = root ?? ScreenTarget.#body();
+    if (!scope) return [];
+    const names = new Set<string>();
+    for (const attr of attrs) {
+      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;
+        if (value) names.add(value);
+      }
+    }
+    return [...names].slice(0, nameCap);
+  }
+
+  static #named(el: HTMLElement, attrs: readonly string[], name: string) {
+    return attrs.some((attr) => el.getAttribute(attr) === name);
+  }
+
+  static #first(scope: HTMLElement, selector: string) {
+    return [...scope.querySelectorAll<HTMLElement>(selector)].find(ScreenTarget.#visible) ?? null;
+  }
+
+  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;
+  }
+
+  static #slug(text: string) {
+    return text
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, " ")
+      .trim();
+  }
+
+  static #body(): HTMLElement | null {
+    if (typeof document === "undefined") return null;
+    return document.body ?? document.documentElement;
+  }
+}

package/store/agent/StoreSurfaceSource.ts

@@ -2,17 +2,25 @@ import { router } from "akanjs/client";
 import type { SurfaceSource, ToolEntry } from "../../vendor/use-agentic";
 import { AgentBridge } from "./AgentBridge";
 import { ScreenReader } from "./ScreenReader";
+import { ScreenSettle } from "./ScreenSettle";
+import { ScreenTarget } from "./ScreenTarget";
 
 /**
- * The three tools every akan screen has whatever it declares: where it can go, what it is rendering, and what one
- * of the store keys it reads holds. Everything else an agent may do is a component's own `st.tool` declaration —
- * the store contributes no actions, because a method on a store class is not something the screen offers the user.
+ * The tools every akan screen has whatever it declares: where it can go, what it is rendering, what one of the
+ * store keys it reads holds, and where on screen a thing the user is being told about actually is. Everything else
+ * an agent may do is a component's own `st.tool` declaration — the store contributes no actions, because a method
+ * on a store class is not something the screen offers the user.
  *
- * Per zone view: a zone's `readState` reaches the keys its own subtree subscribes, and its `readScreen` reads its
- * own `data-agent-zone` container rather than the whole document. A page can shadow any of the three by
- * registering a hook tool of the same name — hook entries win over a source's.
+ * Per zone view: a zone's `readState` reaches the keys its own subtree subscribes, and its `readScreen` and
+ * `highlight` reach into its own `data-agent-zone` container rather than the whole document. A page can shadow any
+ * of them by registering a hook tool of the same name — hook entries win over a source's.
  */
 export class StoreSurfaceSource implements SurfaceSource {
+  /** Defined in `akanjs/ui/styles.css`, so the flash follows the app's own theme tokens. */
+  static readonly highlightClass = "akan-agent-highlight";
+  /** Mirrors the animation in that stylesheet: the class outlives the ring by nothing. */
+  static readonly highlightMs = 2400;
+
   #bridge: AgentBridge | null;
   readonly #builtins = new Map<string, ToolEntry[]>();
 
@@ -25,7 +33,13 @@ export class StoreSurfaceSource implements SurfaceSource {
     const viewKey = view.join(".");
     let builtins = this.#builtins.get(viewKey);
     if (!builtins) {
-      builtins = [StoreSurfaceSource.#navigate(), StoreSurfaceSource.#readScreen(viewKey), this.#readState(viewKey)];
+      builtins = [
+        StoreSurfaceSource.#navigate(),
+        StoreSurfaceSource.#goBack(),
+        StoreSurfaceSource.#readScreen(viewKey),
+        this.#readState(viewKey),
+        StoreSurfaceSource.#highlight(viewKey),
+      ];
       this.#builtins.set(viewKey, builtins);
     }
     return builtins;
@@ -48,24 +62,112 @@ export class StoreSurfaceSource implements SurfaceSource {
         typeof args.path === "string" && args.path.startsWith("/") && !args.path.startsWith("//")
           ? true
           : "path must be an internal path starting with /.",
-      run: (args) => {
+      run: async (args) => {
         const path = String(args.path);
         router.push(path);
-        return `Navigating to ${path}.`;
+
+        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.`;
+      },
+    };
+  }
+
+  /**
+   * Global rather than declared by whatever `Link.Back` happens to be on screen: history is not a control the page
+   * owns. Every route has a previous page, the browser's own back gesture is always there, and a page that draws
+   * no back link is not a page you may not leave — the same reasoning that makes `navigate` a built-in.
+   */
+  static #goBack(): ToolEntry {
+    return {
+      name: "goBack",
+      description:
+        "Go back to the previous page in this session's history. Use it to undo a navigation; use navigate for a path.",
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      effect: "state",
+      
+      guard: () => (router.canGoBack() ? true : "There is no previous page in this session's history."),
+      run: async () => {
+        router.back();
+        await ScreenSettle.wait({ appearMs: 800, timeoutMs: 5000 });
+        return `Back on ${router.getPath()}. Call readScreen to see it; this screen's own tools and state are listed from the next turn.`;
       },
     };
   }
 
   /** What the user is looking at, read from the rendered DOM — the store never held it, so no key can answer it. */
   static #readScreen(viewKey: string): ToolEntry {
+    const where = viewKey ? "in this zone" : "on this page";
+    const subject = viewKey ? "this zone" : "the current page";
     return {
       name: "readScreen",
-      description: viewKey
-        ? "Read what is currently rendered in this zone — headings, prose, links, buttons, and form values. Use it when the user asks about what this zone shows."
-        : "Read what is currently rendered on this page — headings, prose, links, buttons, and form values. Use it when the user asks about the current page or screen.",
-      parameters: { type: "object", properties: {}, additionalProperties: false },
+      description: `Read what is currently rendered ${where} — headings, prose, links, buttons, and form values. Use it when the user asks about what ${subject} shows. A long screen is truncated, so pass \`section\` to read one part of it.`,
+      parameters: {
+        type: "object",
+        properties: {
+          section: {
+            type: "string",
+            description:
+              "One region of the screen: a heading's anchor as readScreen prints it, the heading's own text, or a scope path from the screen context. Omit to read all of it.",
+          },
+        },
+        additionalProperties: false,
+      },
       effect: "query",
-      run: () => ScreenReader.read(StoreSurfaceSource.#zoneRoot(viewKey)),
+      run: (args) => {
+        const root = StoreSurfaceSource.#zoneRoot(viewKey);
+        const section = typeof args.section === "string" ? args.section.trim() : "";
+        if (!section) return ScreenReader.read(root);
+        const container = ScreenTarget.container(section, root);
+        if (container) return ScreenReader.read(container);
+        const heading = ScreenTarget.heading(section, root);
+        if (heading) return ScreenReader.readFrom(heading, root);
+        const named = ScreenTarget.containerNames(root);
+        throw new Error(
+          `No section named ${section} is on screen. ${
+            named.length
+              ? `Sections here: ${named.join(", ")}.`
+              : "This screen names no sections; omit section to read all of it."
+          }`,
+        );
+      },
+    };
+  }
+
+  /**
+   * Showing beats describing: an agent that has just been asked where something is can put it in front of the
+   * user instead of writing directions to it. It drives nothing and changes no data — it is the one built-in that
+   * exists for the *user's* benefit rather than the model's, which is why it is worth a slot on every screen.
+   */
+  static #highlight(viewKey: string): ToolEntry {
+    return {
+      name: "highlight",
+      description:
+        "Scroll one thing into view and flash it, to show the user where it is instead of describing where it is. `target` is a tool name as it appears beside a control in readScreen, a state key, a scope path, a heading's anchor, or a heading's own text.",
+      parameters: {
+        type: "object",
+        properties: { target: { type: "string" } },
+        required: ["target"],
+        additionalProperties: false,
+      },
+      effect: "state",
+      run: (args) => {
+        const name = typeof args.target === "string" ? args.target.trim() : "";
+        if (!name) throw new Error("highlight needs a target.");
+        const root = StoreSurfaceSource.#zoneRoot(viewKey);
+        if (typeof document === "undefined") return "No rendered document is available.";
+        const target = ScreenTarget.find(name, root);
+        if (!target) {
+          const named = ScreenTarget.targetNames(root);
+          throw new Error(
+            `Nothing named ${name} is on screen. ${
+              named.length ? `On screen now: ${named.join(", ")}.` : "Nothing on this screen carries a name."
+            }`,
+          );
+        }
+        target.scrollIntoView({ block: "center", behavior: "smooth" });
+        StoreSurfaceSource.#flash(target);
+        return `Highlighted ${name} on screen for the user.`;
+      },
     };
   }
 
@@ -88,6 +190,30 @@ export class StoreSurfaceSource implements SurfaceSource {
     };
   }
 
+  /**
+   * 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. Settles on the
+   * element's own position rather than a scroll event, which no browser fires consistently, and is capped so a page
+   * that never stops moving still flashes. Removed on a timer — a React re-render that drops the class early only
+   * ends it sooner.
+   */
+  static #flash(target: HTMLElement) {
+    let last = Number.NaN;
+    let frames = 0;
+    const settle = () => {
+      const { top } = target.getBoundingClientRect();
+      frames += 1;
+      if (Math.abs(top - last) >= 1 && frames < 90) {
+        last = top;
+        requestAnimationFrame(settle);
+        return;
+      }
+      target.classList.add(StoreSurfaceSource.highlightClass);
+      setTimeout(() => target.classList.remove(StoreSurfaceSource.highlightClass), StoreSurfaceSource.highlightMs);
+    };
+    requestAnimationFrame(settle);
+  }
+
   static #zoneRoot(viewKey: string): HTMLElement | undefined {
     if (!viewKey || typeof document === "undefined") return undefined;
     return document.querySelector<HTMLElement>(`[data-agent-zone="${CSS.escape(viewKey)}"]`) ?? undefined;

package/store/agent/index.ts

@@ -2,6 +2,8 @@ export * from "./AgentBridge";
 export * from "./AgentContext";
 export * from "./AgentPrompts";
 export * from "./ScreenReader";
+export * from "./ScreenSettle";
+export * from "./ScreenTarget";
 export * from "./StoreCatalogue";
 export * from "./StoreSurfaceSource";
 export * from "./storeSurface";