akanjs 3.0.0-beta.9 → 3.0.0

package/store/actionTag.ts

@@ -6,21 +6,12 @@ export interface ActionOwner {
 }
 
 export interface ActionTag {
-  /** The `st.do` key this function is. */
   action: string;
   /** The state path it writes, when it writes exactly one — `userForm.name` for a field setter. */
   state?: string;
 }
 
-/**
- * Marks a dispatcher with what it does, so a component handed one by reference can say so in the DOM.
- *
- * `onChange={st.do.setNameOnUser}` is the house form for every model field, which means the component already holds
- * everything an annotation needs — it just has no way to read it off a function. This is that way, and it is why
- * `data-akan-*` costs an app no code at all: nobody writes the attribute, the setter carries its own name.
- *
- * Non-enumerable, so it survives neither `{...fn}` nor `JSON.stringify` and shows up in no spread.
- */
+/** Tags a dispatcher (non-enumerable) so a control handed it by reference can emit `data-akan-*`. */
 export const tagAction = <T extends (...args: never[]) => unknown>(fn: T, tag: ActionTag): T => {
   Object.defineProperty(fn, ACTION_TAG, { value: tag, configurable: true });
   return fn;

package/store/agent/AgentBridge.ts

@@ -3,30 +3,15 @@ import { ConstantRegistry, type MaskModel, mask } from "akanjs/constant";
 import type { AgentRefusal } from "akanjs/signal";
 import type { StoreInstance } from "../storeInstance";
 import { StoreRegistry } from "../storeRegistry";
-import { StoreCatalogue } from "./StoreCatalogue";
-import type { SerializedStoreState } from "./types";
+import { type SerializedStoreState, StoreCatalogue } from "./StoreCatalogue";
 
-/**
- * What an in-page agent may read out of the store the user is looking at.
- *
- * Reads only. Driving the app is a component's declaration to make: `st.tool` binds a name and a schema to the
- * same handler the control on screen calls, so what an agent can do is what the screen offers the user and nothing
- * else. A store method that no component declared is not a lever this screen has — publishing one made the surface
- * the bundle rather than the screen, and gave the model levers whose effect it could not see.
- *
- * A key is readable while a mounted component subscribes it through `st.use` / `st.sel` / `st.ref`, and its value
- * is masked by the model that key declares. Masking is not optional even though the data mostly came from the
- * server already masked: `<model>Form` holds what the *user* typed, credentials included, and an in-page agent
- * ships what it reads to a remote model. The mask is by the declared model rather than by the value's class,
- * because `immerify` copies a form into a plain object and the class is gone by the time anyone can ask.
- */
+/** Masked store reads for an in-page agent: `<model>Form` holds typed credentials, and reads ship to a remote model. */
 export class AgentBridge {
   readonly refusals: AgentRefusal[];
 
   readonly #instance: StoreInstance;
   readonly #state: { [key: string]: SerializedStoreState };
 
-  /** The bridge for the app running in this process: the one store every `st.use` goes through. */
   static of() {
     return new AgentBridge(StoreRegistry.instance);
   }
@@ -53,12 +38,7 @@ export class AgentBridge {
       .sort((a, b) => a.localeCompare(b));
   }
 
-  /**
-   * The value behind a state key, stripped of what the model marks `hidden` or `secret`.
-   *
-   * The key itself has to be one the screen reads, not merely one its store owns: a component subscribing
-   * `userList` says the screen shows a user list, and says nothing about `userForm` sitting in the same store.
-   */
+  /** The masked value of a key a mounted component reads; throws for any other key. */
   read(key: string, viewKey = ""): unknown {
     const entry = this.#state[key];
     if (!entry) throw new Error(`Unknown state key: ${key}.${this.#readableInstead(viewKey)}`);
@@ -77,7 +57,6 @@ export class AgentBridge {
     );
   }
 
-  /** Named the way `readScreen` and `highlight` name theirs: a refusal with no way forward costs a whole turn. */
   #readableInstead(viewKey: string): string {
     const keys = this.readableKeys(viewKey);
     return keys.length ? ` Readable here: ${keys.join(", ")}.` : " This screen reads no state keys.";
@@ -87,7 +66,6 @@ export class AgentBridge {
     return value instanceof DataList ? value.values : value;
   }
 
-  /** True when nothing inside could be carrying a model's fields, so there is nothing a mask would have to strip. */
   static #isPlainValue(value: unknown): boolean {
     if (value === null || value === undefined) return true;
     if (Array.isArray(value)) return value.every((item) => AgentBridge.#isPlainValue(item));

package/store/agent/AgentContext.ts

@@ -2,15 +2,9 @@ import type { ContextBlock, SurfaceView } from "../../vendor/use-agentic";
 import type { StoreInstance } from "../storeInstance";
 import { StoreRegistry } from "../storeRegistry";
 import type { AgentBridge } from "./AgentBridge";
-import { ensureStoreSurface } from "./storeSurface";
+import { ensureStoreSurface } from "./StoreSurfaceSource";
 
-/**
- * The akan default context for a turn: where the user is (route), what is on screen (scopes and their curated
- * resources), and which store keys the mounted components are reading (live keys). Live entries carry names and
- * small primitives only — anything bigger is one `readState` call away, masked — so the block cannot bloat with
- * what happens to be in the store. Base-store plumbing is kept off the surface by `st.use.x({ agent: false })`
- * at each call site, and the route block carries the three of them that matter.
- */
+/** A turn's default context: route, on-screen scopes, and live keys (small primitives inline, the rest by name). */
 export class AgentContext {
   static of(): AgentContext {
     return new AgentContext(StoreRegistry.instance, ensureStoreSurface().bridge);
@@ -55,7 +49,6 @@ export class AgentContext {
     };
   }
 
-  /** Primitives ride inline; anything bigger stays a name the agent pulls with `readState`. */
   static #inlineValue(value: unknown): unknown {
     if (value === null) return null;
     switch (typeof value) {

package/store/agent/AgentCursor.ts

@@ -0,0 +1,160 @@
+import { ScreenFlash } from "./ScreenFlash";
+
+/** A plain DOM element, not a React one: it outlives route changes, exists once, and is created on first use. */
+export class AgentCursor {
+  static readonly className = "akan-agent-cursor";
+  /** Matches the transform transition in `akanjs/ui/styles.css`. */
+  static readonly travelMs = 320;
+  /** Pixels below which the pointer jumps instead of gliding. */
+  static readonly travelFrom = 200;
+  /** Pixels the pointer drifts off a pressed control while it waits. */
+  static readonly driftBy = 18;
+  /** Fade delay after the last call, for a host that reports no turn boundary (one that does calls `hold`). */
+  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. 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 (!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();
+        }
+      });
+    });
+  }
+
+  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();
+  }
+
+  /** Drifts clear of the last pressed control and shows the waiting spinner; a no-op before the first press. */
+  static think() {
+    const el = AgentCursor.#el;
+    if (!el?.isConnected) return;
+    el.classList.remove(`${AgentCursor.className}-tap`);
+    AgentCursor.#driftOff();
+    el.classList.add(AgentCursor.thinkingClass);
+  }
+
+  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;
+    setTimeout(() => {
+      if (el && !el.classList.contains(`${AgentCursor.className}-shown`)) el.remove();
+      if (AgentCursor.#el === el) AgentCursor.#el = null;
+    }, 400);
+  }
+
+  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;
+    
+    if (!travel) el.classList.add(`${AgentCursor.className}-placing`);
+    el.style.transform = `translate3d(${Math.round(x)}px, ${Math.round(y)}px, 0)`;
+    if (!travel) {
+      void el.offsetWidth;
+      el.classList.remove(`${AgentCursor.className}-placing`);
+    }
+    requestAnimationFrame(() => el.classList.add(`${AgentCursor.className}-shown`));
+    AgentCursor.#at = { x, y };
+    AgentCursor.#keep();
+    return travel;
+  }
+
+  static #tap() {
+    const el = AgentCursor.#el;
+    if (!el) return;
+    el.classList.remove(`${AgentCursor.className}-tap`);
+    void el.offsetWidth;
+    el.classList.add(`${AgentCursor.className}-tap`);
+  }
+
+  static #keep() {
+    if (AgentCursor.#idle) clearTimeout(AgentCursor.#idle);
+    AgentCursor.#idle = null;
+    if (AgentCursor.#held) return;
+    AgentCursor.#idle = setTimeout(() => {
+      AgentCursor.#idle = null;
+      AgentCursor.hide();
+    }, AgentCursor.idleMs);
+  }
+
+  static #mounted(): HTMLElement {
+    if (AgentCursor.#el?.isConnected) return AgentCursor.#el;
+    const el = document.createElement("div");
+    el.className = AgentCursor.className;
+    el.setAttribute("data-agent-ui", "");
+    el.setAttribute("aria-hidden", "true");
+    el.append(document.createElement("i"), document.createElement("b"));
+    document.body.append(el);
+    AgentCursor.#el = el;
+    AgentCursor.#at = null;
+    return el;
+  }
+}

package/store/agent/AgentPrompts.ts

@@ -1,11 +1,6 @@
 import type { PromptContent, PromptMessage, PromptResult } from "akanjs/signal";
 import type { ChatMessage } from "../../vendor/use-agentic";
 
-/**
- * The chat's slash-command parser and the bridge from prompt messages to chat turns. The app's own prompts are
- * `page().prompt()` declarations served over MCP, which a browser chat does not list; what stays here is what the
- * chat's built-in commands need.
- */
 export class AgentPrompts {
   /** `/name arg1 "an arg with spaces"` — positional because a prompt's arguments are flat strings by protocol. */
   static parseCommand(draft: string): { name: string; args: string[] } | null {
@@ -14,11 +9,6 @@ export class AgentPrompts {
     return { name: match[1], args: AgentPrompts.#args(match[2] ?? "") };
   }
 
-  /**
-   * Whitespace separates arguments, and quotes are how a sentence stays one of them — a prompt taking a single
-   * `String` is the common case, and splitting "plan the week" into three arguments fills the second parameter
-   * with the second word.
-   */
   static #args(rest: string): string[] {
     const args: string[] = [];
     for (const token of rest.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) args.push(token[1] ?? token[2] ?? token[3]);
@@ -31,11 +21,6 @@ export class AgentPrompts {
     return result.map((message) => AgentPrompts.#messageOf(message));
   }
 
-  /**
-   * A binary block becomes an attachment. It used to become the string `[image]`, which a model reads as having
-   * been shown a picture — so a prompt built with `Msg.imageOf` produced confident answers about bytes that never
-   * left the server. The other block types are text already and stay text.
-   */
   static #messageOf(message: PromptMessage): ChatMessage {
     const { role, content } = message;
     if (content.type !== "image" && content.type !== "audio") return { role, text: AgentPrompts.textOf(content) };

package/store/agent/AgentVisual.ts

@@ -0,0 +1,152 @@
+import { router } from "akanjs/client";
+import type { ToolActivity } from "../../vendor/use-agentic";
+import { AgentCursor } from "./AgentCursor";
+import { ScreenFlash } from "./ScreenFlash";
+import { ScreenTarget } from "./ScreenTarget";
+
+export interface AgentVisualOption {
+  /** Ring the control a call was published from, scrolling to it first when it is off screen. */
+  reveal?: boolean;
+  /** The pointer that travels to the control and presses it. */
+  cursor?: boolean;
+}
+
+/** Draws where an agent call lands, from tool activity: a store action cannot tell agent writes from the user's. */
+export class AgentVisual {
+  /** Past this many calls in one turn the reveal only rings, without scrolling. */
+  static readonly revealCap = 4;
+  /** How many of a form patch's fields are drawn. */
+  static readonly fieldCap = 5;
+  /** The longest a navigate call waits for its press to land. */
+  static readonly leadMs = 600;
+
+  static #revealed = 0;
+  static #idle: ReturnType<typeof setTimeout> | null = null;
+  static #turning = false;
+  static #acting = 0;
+
+  /** 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 {
+      onActivity: (event: ToolActivity) => AgentVisual.on(event, settings),
+      onTurn: (running: boolean) => AgentVisual.turn(running, settings),
+    };
+  }
+
+  /** Resets the per-turn scroll budget; the pointer is held until the turn ends. */
+  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 = {}): void | Promise<void> {
+    if (typeof document === "undefined" || document.hidden) return;
+    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));
+  }
+
+  static #capped(drawing: Promise<unknown>): Promise<void> {
+    return new Promise((resolve) => {
+      const done = () => resolve();
+      setTimeout(done, AgentVisual.leadMs);
+      void drawing.then(done, done);
+    });
+  }
+
+  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), event.args);
+    return Object.keys(event.args)
+      .slice(0, AgentVisual.fieldCap)
+      .flatMap((key) => AgentVisual.#only(ScreenTarget.controls(`${form}.${key}`)));
+  }
+
+  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, { reveal, cursor }: Required<AgentVisualOption>): Promise<void> {
+    AgentVisual.#count();
+    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;
+  }
+
+  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";
+  }
+
+  static #formOf(name: string) {
+    const bare = name.slice(name.lastIndexOf(".") + 1);
+    const match = /^fill([A-Z]\w*)Form$/.exec(bare);
+    if (!match) return null;
+    return `${match[1][0].toLowerCase()}${match[1].slice(1)}Form`;
+  }
+
+  static #count() {
+    AgentVisual.#revealed += 1;
+    if (AgentVisual.#idle) clearTimeout(AgentVisual.#idle);
+    AgentVisual.#idle = setTimeout(() => {
+      AgentVisual.#revealed = 0;
+      AgentVisual.#idle = null;
+    }, 1000);
+  }
+}

package/store/agent/ScreenFlash.ts

@@ -0,0 +1,67 @@
+/** Scrolls an element into view, then rings it once the scroll has landed. */
+export class ScreenFlash {
+  /** Defined in `akanjs/ui/styles.css`, so the flash follows the app's own theme tokens. */
+  static readonly ringClass = "akan-agent-highlight";
+  /** Mirrors the animation length in that stylesheet. */
+  static readonly ringMs = 2400;
+  /** The lighter, shorter ring for a control the agent just drove. */
+  static readonly actingClass = "akan-agent-acting";
+  static readonly actingMs = 1000;
+
+  static show(target: HTMLElement) {
+    ScreenFlash.reveal(target);
+    ScreenFlash.ring(target);
+  }
+
+  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;
+  }
+
+  /** Inside the viewport with `margin` px to spare vertically, not merely intersecting it. */
+  static inView(target: HTMLElement, margin = 24) {
+    const { top, bottom, left, right, height, width } = target.getBoundingClientRect();
+    if (!height && !width) return false;
+    const viewHeight = window.innerHeight || document.documentElement.clientHeight;
+    const viewWidth = window.innerWidth || document.documentElement.clientWidth;
+    return top >= margin && left >= 0 && bottom <= viewHeight - margin && right <= viewWidth;
+  }
+
+  /** Painted at its own centre, not just laid out — `checkVisibility` passes a control under a modal backdrop. */
+  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));
+  }
+
+  /** Added once the element stops moving, so it is not already fading when a smooth scroll arrives. */
+  static ring(target: HTMLElement, { className = ScreenFlash.ringClass, ms = ScreenFlash.ringMs } = {}) {
+    ScreenFlash.whenStill(target, () => {
+      target.classList.add(className);
+      setTimeout(() => target.classList.remove(className), ms);
+    });
+  }
+
+  /** Runs `done` once the element's position holds (no browser fires a consistent scroll end); capped at 90 frames. */
+  static whenStill(target: HTMLElement, done: () => void) {
+    let last: number | null = null;
+    let frames = 0;
+    const settle = () => {
+      const { top } = target.getBoundingClientRect();
+      frames += 1;
+      
+      if ((last === null || Math.abs(top - last) >= 1) && frames < 90) {
+        last = top;
+        requestAnimationFrame(settle);
+        return;
+      }
+      done();
+    };
+    requestAnimationFrame(settle);
+  }
+}

package/store/agent/ScreenReader.ts

@@ -45,30 +45,12 @@ const blockTags = new Set([
   "UL",
 ]);
 
-/**
- * Serializes what the page is rendering into compact text an agent can answer questions from: headings keep their
- * 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 region the app marks `data-agent-skip` — what `Agent.Skip` renders — costs a `[skipped: <name>]` line instead
- * of its text. It stands in the output rather than vanishing because a deleted region reads as an absent one, and
- * an agent asked about a footer it never saw answers that the page has none. Naming the region as `section` reads
- * it: the marker is what the default read leaves out, not a wall.
- *
- * 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 interface ScreenReadOptions {
-  /**
-   * Carry each image's address as well as its caption. Off by default because a gallery is one long URL per
-   * thumbnail, which is the read's whole budget spent on the part of the screen it can say the least about.
-   */
+  /** Also print each image's address. Default false. */
   images?: boolean;
 }
 
+/** The rendered page as compact text for an agent; skips `data-agent-ui` and never reads a password value. */
 export class ScreenReader {
   static readonly limit = 8000;
 
@@ -82,11 +64,7 @@ export class ScreenReader {
     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.
-   */
+  /** One heading's section: its container when that holds no peer heading, else its following siblings. */
   static readFrom(heading: HTMLElement, root?: HTMLElement | null, options: ScreenReadOptions = {}): string {
     if (typeof document === "undefined") return "No rendered document is available.";
     const reader = new ScreenReader(options);
@@ -105,11 +83,6 @@ export class ScreenReader {
     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;
@@ -124,7 +97,6 @@ export class ScreenReader {
     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;
@@ -136,12 +108,6 @@ export class ScreenReader {
     return "";
   }
 
-  /**
-   * `checkVisibility()` reports whether the element has a layout box, and a `display: contents` wrapper has none
-   * while its children do — so Chrome answers false for a wrapper the user is looking straight at, and skipping it
-   * would drop that whole subtree (happy-dom answers true, so no DOM test sees the difference). Reading through it
-   * is safe only because the walk is top-down: a `display: none` ancestor bails on its own computed display first.
-   */
   static #rendered(el: HTMLElement) {
     if (typeof el.checkVisibility !== "function" || el.checkVisibility()) return true;
     return getComputedStyle(el).display === "contents";
@@ -162,10 +128,6 @@ export class ScreenReader {
     this.#images = images;
   }
 
-  /**
-   * 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;
@@ -192,12 +154,6 @@ export class ScreenReader {
       : `${kept}${note}`;
   }
 
-  /**
-   * An image is named whether or not it carries an `alt`: dropping an unlabelled one leaves a card that renders a
-   * picture reading exactly like a card that renders nothing, and "the page shows no image" is the one answer the
-   * screen cannot support. The address rides only when it was asked for, and never for a `data:` URL — that is
-   * the bytes themselves rather than somewhere to fetch them, and one of them outweighs the whole read.
-   */
   #image(el: HTMLElement) {
     const alt = (el.getAttribute("alt") ?? "").replace(/\s+/g, " ").trim();
     const src = this.#images ? (el as HTMLImageElement).currentSrc || el.getAttribute("src") || "" : "";
@@ -205,7 +161,6 @@ export class ScreenReader {
     this.#buffer += ` [image${alt ? `: ${alt}` : ""}]${address}`;
   }
 
-  /** What stands where a skipped region was: its own name, and the anchor `section` takes to read it on request. */
   #mark(el: HTMLElement, label: string) {
     const anchor = el.getAttribute("data-agent-scope") ?? el.getAttribute("data-agent-zone") ?? el.id;
     this.#flush();
@@ -303,10 +258,6 @@ export class ScreenReader {
     if (href && href !== "#" && !href.startsWith("javascript:") && text !== href) this.#buffer += ` (${href})`;
   }
 
-  /**
-   * A control the person cannot use publishes no tool, so saying so here is what turns a silent refusal into a
-   * fact the agent could have read. It reads `aria-disabled` too: a styled-off div carries no native property.
-   */
   static #off(el: HTMLElement) {
     const native = (el as HTMLInputElement | HTMLButtonElement).disabled;
     return native || el.getAttribute("aria-disabled") === "true" ? " (disabled)" : "";

package/store/agent/ScreenSettle.ts

@@ -6,18 +6,7 @@ export interface ScreenSettleOptions {
   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.
- */
+/** Resolves once the DOM stops mutating, always bounded; no single router or store signal says "settled". */
 export class ScreenSettle {
   static wait({ quietMs = 120, appearMs = 0, timeoutMs = 3000 }: ScreenSettleOptions = {}): Promise<void> {
     const body = typeof document === "undefined" ? null : (document.body ?? document.documentElement);
@@ -37,7 +26,6 @@ export class ScreenSettle {
       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();
     });