akanjs 3.0.0-beta.9 → 3.0.0

package/store/agent/ScreenTarget.ts

@@ -5,24 +5,7 @@ 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, a
- * container — an `Agent.Zone`, a `useScreenScope` scope, or an `Agent.Skip` region named by the marker left in its
- * place — 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. A `display: contents` wrapper does not resolve either, even
- * though the reader now reads through it: it has no box, so `scrollIntoView` has nothing to scroll to.
- */
+/** Resolves an on-screen name to a visible element. Only headings match loosely: a loose control match is unsafe. */
 export class ScreenTarget {
   static container(name: string, root?: HTMLElement | null): HTMLElement | null {
     const scope = root ?? ScreenTarget.#body();
@@ -30,19 +13,24 @@ export class ScreenTarget {
     if (ScreenTarget.#named(scope, containerAttrs, name)) return scope;
     const escaped = CSS.escape(name);
     const selector = containerAttrs.map((attr) => `[${attr}="${escaped}"]`).join(", ");
-
+    
     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
     );
   }
 
   static control(name: string, root?: HTMLElement | null): HTMLElement | null {
+    return ScreenTarget.controls(name, root)[0] ?? null;
+  }
+
+  static controls(name: string, root?: HTMLElement | null): HTMLElement[] {
     const scope = root ?? ScreenTarget.#body();
-    if (!scope || !name) return null;
+    if (!scope || !name) return [];
     const escaped = CSS.escape(name);
-    return ScreenTarget.#first(scope, controlAttrs.map((attr) => `[${attr}="${escaped}"]`).join(", "));
+    const selector = controlAttrs.map((attr) => `[${attr}="${escaped}"]`).join(", ");
+    return [...scope.querySelectorAll<HTMLElement>(selector)].filter(ScreenTarget.visible);
   }
 
   /** Matched on letters and digits only, so a slug written for a heading still finds it. */
@@ -50,7 +38,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)) ??
@@ -58,15 +46,10 @@ export class ScreenTarget {
     );
   }
 
-  /** 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,
@@ -79,7 +62,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];
@@ -100,7 +83,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);
       }
     }
@@ -112,12 +95,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) {
-    if (el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true") return false;
-    if (el.closest("[data-agent-ui]")) return false;
+  static visible(el: HTMLElement) {
+    if (el.closest('[hidden], [aria-hidden="true"], [inert], [data-agent-ui]')) return false;
     return typeof el.checkVisibility === "function" ? el.checkVisibility() : true;
   }
 

package/store/agent/StoreCatalogue.ts

@@ -4,9 +4,18 @@ import type { AgentRefusal } from "akanjs/signal";
 import { databaseStateModelTypes, databaseStateNames } from "../databaseStateNames";
 import type { SliceStateKey } from "../state";
 import type { StoreInstance } from "../storeInstance";
-import type { SerializedStoreState } from "./types";
 
-/** Which of the model's classes each slice state key holds. The rest hold a primitive or a query descriptor. */
+export interface SerializedStoreState {
+  /** Read off the live value — stores declare no types — so a `null`-initialized key says nothing. */
+  type: "string" | "number" | "boolean" | "date" | "list" | "map" | "object" | "unknown";
+  /** The model a read of this key is masked by. */
+  refName?: string;
+  modelType?: "input" | "full" | "light" | "insight";
+  /** A `search()` or `computed()` key; writing it throws. */
+  derived: boolean;
+  role?: SliceStateKey;
+}
+
 const sliceStateModelTypes: { [key in SliceStateKey]?: SerializedStoreState["modelType"] } = {
   defaultModel: "full",
   modelList: "light",
@@ -15,21 +24,7 @@ const sliceStateModelTypes: { [key in SliceStateKey]?: SerializedStoreState["mod
   modelInsight: "insight",
 };
 
-/**
- * Every store key an in-page agent may read, derived on the client from the store the browser is already running.
- *
- * Keys only — nothing here becomes a tool. What an agent may *do* is declared where the screen declares it, with
- * `st.tool` beside the control that does the same thing for the user; a store method nobody declared is the app's
- * own vocabulary and says nothing about what this screen offers. Deriving tools from the store published the
- * bundle rather than the screen, and every lever the screen did not have was noise the model paid for.
- *
- * Reads stay store-derived because a read has to be masked and only the store declares which model masks it. Which
- * of these keys is readable at a given moment is liveness rather than this catalogue — the keys the mounted
- * components subscribe. Plumbing in the base store opts out at the call site with `{ agent: false }`.
- *
- * It is derived on the client rather than shipped from the server: the store classes are in the bundle already,
- * and a second copy over the wire is a second thing to keep in step.
- */
+/** Every store key an agent may read and the model its reads are masked by. Keys only: tools come from `st.tool`. */
 export class StoreCatalogue {
   readonly state: { [key: string]: SerializedStoreState };
   readonly refusals: AgentRefusal[] = [];
@@ -64,12 +59,6 @@ export class StoreCatalogue {
     return Object.fromEntries(entries);
   }
 
-  /**
-   * The model each generated state key holds, taken from the declaration rather than from the value.
-   *
-   * A read has to be masked by the model, and the value cannot supply it: `immerify` copies a form into a plain
-   * object, so `<model>Form` — an `Input` holding whatever the user typed — arrives with its class already gone.
-   */
   static #declaredStateModels() {
     const declared = new Map<string, { refName: string; modelType: SerializedStoreState["modelType"] }>();
     for (const refName of ConstantRegistry.database.keys()) {
@@ -103,7 +92,6 @@ export class StoreCatalogue {
     }
   }
 
-  /** `DataList` and `dayjs` are the two objects a store holds that are not what `typeof` says they are. */
   static #isList(value: object) {
     return "values" in value && Array.isArray((value as { values: unknown }).values);
   }

package/store/agent/StoreSurfaceSource.ts

@@ -1,38 +1,20 @@
 import { router } from "akanjs/client";
-import type { SurfaceSource, ToolEntry } from "../../vendor/use-agentic";
+import { AgenticSurface, type SurfaceSource, type ToolEntry } from "../../vendor/use-agentic";
 import { AgentBridge } from "./AgentBridge";
+import { ScreenFlash } from "./ScreenFlash";
 import { ScreenReader } from "./ScreenReader";
 import { ScreenSettle } from "./ScreenSettle";
 import { ScreenTarget } from "./ScreenTarget";
 
-/**
- * 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` 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. **That is a root-scope
- * move only**: inside a zone the hook entry is registered under its scope-prefixed name, which can never collide
- * with the bare name a source publishes, so a zone drops a built-in with the session's `builtins` option instead.
- */
+/** Every screen's built-in tools. A same-named hook tool shadows one at root scope only; a zone uses `builtins`. */
 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;
-  /**
-   * What `tools()` contributes, in the order it builds them — the list a session's `builtins` option selects from.
-   * A screen that declares a hook tool of one of these names is not in it: that entry is the screen's, not this
-   * source's, so withholding the built-ins never withholds a tool a component published on purpose.
-   */
+  /** What a session's `builtins` option selects from, in build order. */
   static readonly builtins = ["navigate", "goBack", "readScreen", "readState", "highlight"] as const;
 
   #bridge: AgentBridge | null;
   readonly #builtins = new Map<string, ToolEntry[]>();
 
-  /** Lazy by default: `AgentBridge.of()` walks the whole store, so it waits for the first enumeration. */
+  /** Without a bridge, `AgentBridge.of()` runs at the first `readState` call. */
   constructor(bridge?: AgentBridge) {
     this.#bridge = bridge ?? null;
   }
@@ -53,7 +35,6 @@ export class StoreSurfaceSource implements SurfaceSource {
     return builtins;
   };
 
-  /** Screen-driving is client navigation, so the agent gets the same router `Link` rides. */
   static #navigate(): ToolEntry {
     return {
       name: "navigate",
@@ -72,25 +53,26 @@ export class StoreSurfaceSource implements SurfaceSource {
       run: async (args) => {
         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.`;
       },
     };
   }
 
-  /**
-   * 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 },
-      
       guard: () => (router.canGoBack() ? true : "There is no previous page in this session's history."),
       run: async () => {
         router.back();
@@ -100,7 +82,6 @@ export class StoreSurfaceSource implements SurfaceSource {
     };
   }
 
-  /** 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";
@@ -145,11 +126,6 @@ export class StoreSurfaceSource implements SurfaceSource {
     };
   }
 
-  /**
-   * 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",
@@ -161,7 +137,6 @@ export class StoreSurfaceSource implements SurfaceSource {
         required: ["target"],
         additionalProperties: false,
       },
-      
       settle: false,
       run: (args) => {
         const name = typeof args.target === "string" ? args.target.trim() : "";
@@ -177,14 +152,12 @@ export class StoreSurfaceSource implements SurfaceSource {
             }`,
           );
         }
-        target.scrollIntoView({ block: "center", behavior: "smooth" });
-        StoreSurfaceSource.#flash(target);
+        ScreenFlash.show(target);
         return `Highlighted ${name} on screen for the user.`;
       },
     };
   }
 
-  /** The pull half of the state context block: keys are listed there, values arrive masked through this. */
   #readState(viewKey: string): ToolEntry {
     return {
       name: "readState",
@@ -203,32 +176,31 @@ 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;
+    return [...document.querySelectorAll<HTMLElement>(`[data-agent-zone="${CSS.escape(viewKey)}"]`)].find(
+      ScreenTarget.visible,
+    );
   }
 }
+
+export interface StoreSurface {
+  bridge: AgentBridge;
+  source: StoreSurfaceSource;
+  surface: AgenticSurface;
+}
+
+const SURFACE_KEY = Symbol.for("akanjs.store.agentSurface");
+
+/** Once per runtime, lazily; never attached on the server, where one global surface would span requests. */
+export const ensureStoreSurface = (): StoreSurface => {
+  const holder = globalThis as typeof globalThis & { [SURFACE_KEY]?: StoreSurface };
+  if (!holder[SURFACE_KEY]) {
+    const bridge = AgentBridge.of();
+    const source = new StoreSurfaceSource(bridge);
+    const surface = AgenticSurface.shared;
+    if (typeof window !== "undefined") surface.addSource(source);
+    holder[SURFACE_KEY] = { bridge, source, surface };
+  }
+  return holder[SURFACE_KEY];
+};

package/store/agent/index.ts

@@ -1,13 +1,13 @@
 
-
-export { AgentAbort, AgentProgress } from "../../vendor/use-agentic";
+export { AgentAbort, AgentProgress, type AgentProgressStep } from "../../vendor/use-agentic";
 export * from "./AgentBridge";
 export * from "./AgentContext";
+export * from "./AgentCursor";
 export * from "./AgentPrompts";
+export * from "./AgentVisual";
+export * from "./ScreenFlash";
 export * from "./ScreenReader";
 export * from "./ScreenSettle";
 export * from "./ScreenTarget";
 export * from "./StoreCatalogue";
 export * from "./StoreSurfaceSource";
-export * from "./storeSurface";
-export * from "./types";

package/store/agentic/AgentValue.ts

@@ -11,23 +11,13 @@ import {
   type PrimitiveScalar,
   type UnCls,
 } from "akanjs/base";
-import { type ConstantModelRef, type MaskModel, mask, maskFieldsOf } from "akanjs/constant";
+import { agentRead, type ConstantModelRef, type MaskModel, mask, maskFieldsOf } from "akanjs/constant";
 
 type AgentSingleType = typeof PrimitiveScalar | EnumInstance<string, any> | ConstantModelRef;
 
-/** What a readable declaration names its value as. One level of array, because a published value is one JSON shape. */
+/** A scalar, an enum, or a model — or one array level of one. */
 export type AgentFieldType = AgentSingleType | AgentSingleType[];
 
-/**
- * A model class resolves to its state object rather than its instance type, so a component may hand over either
- * the hydrated document or the plain data copied out of one — masking reads the model that was named, not the
- * class the value still carries.
- *
- * A scalar is recognised by `refName` and has to be matched before `FIELD_META`: `via.ts` augments the global
- * `String`, `Boolean`, `Date` and `Map` constructors with `DatabaseConstantStatics`, so those four carry field
- * metadata and would otherwise read as models. A model carries no `refName`, and `Map` — carrying neither — falls
- * through to the model branch and is refused at declaration time instead.
- */
 export type AgentValueOf<T> = T extends readonly (infer F)[]
   ? AgentValueOf<F>[]
   : T extends { refName: "Any" }
@@ -44,16 +34,9 @@ export type AgentValueOf<T> = T extends readonly (infer F)[]
               ? V
               : unknown;
 
-type ValueKind = "any" | "date" | "scalar" | "enum" | "model";
+type ValueKind = "any" | "date" | "scalar" | "agent" | "enum" | "model";
 
-/**
- * Turns a declared type into what an agent may read of a value of that type.
- *
- * The type is the whole declaration: it typechecks what the component hands over, and it decides how the value is
- * rendered — a model class masks by that model, a `Date` leaves as an ISO string, a scalar passes. `Any` is the
- * escape hatch and passes the value untouched, so a payload nobody modeled stays publishable and the caller owns
- * whether it is JSON and whether it is worth its tokens.
- */
+/** Renders a value by its declared type: a model masks, a Date is ISO, an agent-faced primitive reads, Any passes. */
 export class AgentValue {
   static serialize(type: AgentFieldType, value: unknown): unknown {
     const single = Array.isArray(type) ? type[0] : type;
@@ -61,10 +44,7 @@ export class AgentValue {
     return AgentValue.#one(single, value);
   }
 
-  /**
-   * Reports an unreadable type the way `st.tool` reports an undescribable argument — on the console, and the
-   * declaration goes unpublished. Throwing would cost the route its server render over an agent-tooling mistake.
-   */
+  /** Logs and returns false for an unreadable type; throwing would cost the route its server render. */
   static publishable(owner: string, type: AgentFieldType): boolean {
     try {
       AgentValue.#kindOf(Array.isArray(type) ? type[0] : type);
@@ -82,6 +62,8 @@ export class AgentValue {
         const parsed = dayjs(value as string | number | Date);
         return parsed.isValid() ? parsed.toISOString() : null;
       }
+      case "agent":
+        return agentRead(type, value);
       case "model":
         return mask(type as MaskModel, value);
       default:
@@ -91,6 +73,7 @@ export class AgentValue {
 
   static #kindOf(type: AgentSingleType): ValueKind {
     if (isEnum(type as Cls)) return "enum";
+    if (PrimitiveRegistry.agentOf(type)) return "agent";
     if (PrimitiveRegistry.has(type as unknown as Cls)) {
       const refName = PrimitiveRegistry.getName(type as typeof PrimitiveScalar);
       switch (refName) {
@@ -105,7 +88,7 @@ export class AgentValue {
         case "Boolean":
           return "scalar";
         default:
-          throw new Error(`the scalar ${refName}, which an agent cannot read.`);
+          throw new Error(`the scalar ${refName}, which an agent cannot read: it declares no \`agent\` face.`);
       }
     }
     if (maskFieldsOf(type as MaskModel)) return "model";

package/store/agentic/StExposeBuilder.ts

@@ -8,13 +8,7 @@ export interface StExposeMeta {
   report?: boolean;
 }
 
-/**
- * A read-only value past its description, waiting for the value itself. `.value()` is the one hook.
- *
- * The declared type is what makes the read safe: it typechecks what the component hands over and it decides how
- * the value is rendered, so a model's `hidden` and `secret` fields are stripped by the model that was named
- * rather than by whatever class the value still happens to carry.
- */
+/** `.value()` is the hook; the declared type, not the value's class, decides what the read masks. */
 export class StExposeBuilder<T extends AgentFieldType> {
   readonly #name: string | null;
   readonly #type: T;
@@ -28,13 +22,10 @@ export class StExposeBuilder<T extends AgentFieldType> {
     this.#meta = meta;
   }
 
-  /**
-   * A thunk is read when the agent reads, which is the difference that matters for a value assembled out of a ref
-   * the children fill in after this render — computing it here would publish whatever was there before they ran.
-   */
+  /** A thunk is evaluated when the agent reads, not at render. */
   value(value: AgentValueOf<T> | (() => AgentValueOf<T>) | null | undefined): void {
     const declared = useRef<{ key: string | null; name: string | null } | null>(null);
-
+    
     if (declared.current?.key !== this.#name)
       declared.current = {
         key: this.#name,

package/store/agentic/StExposeDraft.ts

@@ -1,12 +1,6 @@
 import type { AgentFieldType } from "./AgentValue";
 import { StExposeBuilder, type StExposeMeta } from "./StExposeBuilder";
 
-/**
- * A readable value before it has said what it is: `st.expose("x", ID).desc("…")`.
- *
- * A falsy name declares nothing and publishes nothing, so a component whose publication is conditional keeps a
- * constant hook count instead of branching around the chain.
- */
 export class StExposeDraft<T extends AgentFieldType> {
   readonly #name: string | null;
   readonly #type: T;

package/store/agentic/StStateBuilder.ts

@@ -15,19 +15,12 @@ export interface StStateMeta {
 }
 
 interface StStateDeclaration {
-  /** The name as written this render, which is what says whether the resolution below still applies. */
   key: string | null;
   name: string | null;
   set: { schema: JsonSchema; type: ParamFieldType } | null;
 }
 
-/**
- * Local state past its description, waiting for its initial value. `.init()` is the one hook and returns what
- * `useState` returns.
- *
- * The declared type does both halves: it renders the read, and — with `set` — it is the schema of the setter tool
- * an agent writes through. A type nothing can describe costs the write, not the read and not the render.
- */
+/** `.init()` is the hook and returns what `useState` returns; an undescribable type costs only the setter tool. */
 export class StStateBuilder<T extends AgentFieldType> {
   readonly #name: string | null;
   readonly #type: T;
@@ -47,13 +40,13 @@ export class StStateBuilder<T extends AgentFieldType> {
   init(
     initial: AgentValueOf<T> | null | (() => AgentValueOf<T> | null),
   ): [AgentValueOf<T> | null, Dispatch<SetStateAction<AgentValueOf<T> | null>>];
-
+  
   init(initial: AgentValueOf<T> | null | (() => AgentValueOf<T> | null)): unknown {
     type Value = AgentValueOf<T> | null;
     const name = this.#name;
     const type = this.#type;
     const declared = useRef<StStateDeclaration | null>(null);
-
+    
     if (declared.current?.key !== name)
       declared.current = {
         key: name,
@@ -75,7 +68,6 @@ export class StStateBuilder<T extends AgentFieldType> {
     });
   }
 
-  /** A `set` an agent could only call wrong leaves the key readable — the same trade `st.tool`'s `.arg` makes. */
   static #writable(name: string, type: AgentFieldType): StStateDeclaration["set"] {
     const scalar = type as unknown as ParamFieldType;
     try {

package/store/agentic/StStateDraft.ts

@@ -1,11 +1,6 @@
 import type { AgentFieldType } from "./AgentValue";
 import { StStateBuilder, type StStateMeta } from "./StStateBuilder";
 
-/**
- * Local state before it has said what it is: `st.useState("tab", String, { set: true }).desc("…")`.
- *
- * A falsy name keeps the state and publishes nothing, so a conditional surface never changes the hook count.
- */
 export class StStateDraft<T extends AgentFieldType> {
   readonly #name: string | null;
   readonly #type: T;