akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

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

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export declare class ScreenReader {
+    #private;
+    static readonly limit = 8000;
+    static read(root?: HTMLElement | null): string;
+}

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

@@ -0,0 +1,26 @@
+import type { AgentRefusal, SerializedSignal } from "akanjs/signal";
+import type { StoreInstance } from "../storeInstance.d.ts";
+import { AgentVisibility } from "./AgentVisibility.d.ts";
+import type { SerializedStore } from "./types.d.ts";
+/**
+ * What one built store offers an agent, derived from the store the browser is already running.
+ *
+ * The store is the audience-neutral half of the client surface the way a signal registry is the server's: a key on
+ * `st.do` is the same call the user's own click makes, so an agent that drives it cannot reach past what the UI
+ * already permits. That is why the default here is the opposite of the MCP catalogue's — every key is published
+ * unless something about it cannot be described, and each of those is recorded as a refusal rather than dropped.
+ *
+ * This is the visible universe, not the live view: a store's own `static agent` declaration is honored here, and
+ * the bridge narrows the result to the stores the rendered screen is reading when it answers.
+ *
+ * Nothing is re-declared. An action's arguments come from the endpoint it is named after, from the field metadata
+ * the form setter was generated from, or from the role the store recorded while building the slice; a key that
+ * matches none of those three is published only when it takes no arguments at all.
+ */
+export declare class StoreCatalogue {
+    #private;
+    readonly store: SerializedStore;
+    readonly refusals: AgentRefusal[];
+    readonly visibility: AgentVisibility;
+    constructor(instance: StoreInstance, serializedSignal: Record<string, SerializedSignal>);
+}

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

@@ -0,0 +1,18 @@
+import type { SurfaceSource, ToolEntry } from "../../vendor/use-agentic.d.ts";
+import { AgentBridge } from "./AgentBridge.d.ts";
+/**
+ * The store bridge as one surface source: every catalogued action of the stores the rendered screen is reading is
+ * a callable tool, executed through `AgentBridge.call` so argument checking, masking, and the transcript stay in
+ * one place. Recomputed per snapshot — the bridge's live view changes as components mount and unmount — and
+ * per zone view: a zone session sees the stores its own subtree subscribes, and its `readScreen` reads its own
+ * `data-agent-zone` container rather than the whole document.
+ *
+ * `remove*` keys default to a confirm gate — destructiveness derived from the key, the way the MCP hints derive
+ * theirs — and a page can still shadow any entry with its own hook registration.
+ */
+export declare class StoreSurfaceSource implements SurfaceSource {
+    #private;
+    /** Lazy by default: `AgentBridge.of()` walks the whole store, so it waits for the first enumeration. */
+    constructor(bridge?: AgentBridge);
+    tools: (view?: string[]) => ToolEntry[];
+}

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

@@ -0,0 +1,9 @@
+export * from "./AgentBridge.d.ts";
+export * from "./AgentContext.d.ts";
+export * from "./AgentPrompts.d.ts";
+export * from "./AgentVisibility.d.ts";
+export * from "./ScreenReader.d.ts";
+export * from "./StoreCatalogue.d.ts";
+export * from "./StoreSurfaceSource.d.ts";
+export * from "./storeSurface.d.ts";
+export * from "./types.d.ts";

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

@@ -0,0 +1,14 @@
+import { AgenticSurface } from "../../vendor/use-agentic.d.ts";
+import { AgentBridge } from "./AgentBridge.d.ts";
+import { StoreSurfaceSource } from "./StoreSurfaceSource.d.ts";
+export interface StoreSurface {
+    bridge: AgentBridge;
+    source: StoreSurfaceSource;
+    surface: AgenticSurface;
+}
+/**
+ * Attaches the app's store catalogue to the shared surface, once per runtime, lazily — nothing pays for the
+ * bridge walk until something agent-facing (the dock, a chat) actually asks. On the server it builds but does not
+ * attach: a server-global surface would be shared across requests, and no session assembles context there.
+ */
+export declare const ensureStoreSurface: () => StoreSurface;

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

@@ -0,0 +1,49 @@
+import type { SerializedArg } from "akanjs/signal";
+import type { SliceActionKey } from "../sliceRole.d.ts";
+import type { SliceStateKey } from "../state.d.ts";
+/** Which generated form-setter a store key is, when it is one. */
+export type FormSetterRole = "set" | "add" | "sub" | "addOrSub";
+/** What calling a store action reaches. `state` never leaves the browser. */
+export type StoreActionEffect = "state" | "query" | "mutation";
+export interface SerializedStoreAction {
+    args: SerializedArg[];
+    effect: StoreActionEffect;
+    /** The model this key belongs to, when the key identifies one. */
+    refName?: string;
+    /** The endpoint whose arguments it borrows, when it is named after one. */
+    endpoint?: string;
+    /** The generated role, absent on an action a module wrote itself. */
+    role?: SliceActionKey | FormSetterRole;
+    /** The model field it writes, on a form setter. */
+    field?: string;
+}
+export interface SerializedStoreState {
+    /**
+     * What the live value is. A store declares no types — `STATE_META` holds initial values — so this is read off the
+     * value the store is holding, and a key initialized to `null` or `[]` says nothing about what may go into it.
+     */
+    type: "string" | "number" | "boolean" | "date" | "list" | "map" | "object" | "unknown";
+    /** The model this key holds, when it holds one. What a read of it is masked by. */
+    refName?: string;
+    /** Which of the model's five classes, which is what decides the fields a read may carry. */
+    modelType?: "input" | "full" | "light" | "insight";
+    /** Materialized from a computation, the URL, or storage. Writing one throws, so it is read-only by construction. */
+    derived: boolean;
+    role?: SliceStateKey;
+}
+/**
+ * One store instance described for an agent: every key it can read and every action it may call.
+ *
+ * Flat rather than grouped by model, because that is what the store is — `st.use.x` and `st.do.y` are one namespace,
+ * so a key means the same thing to every reader and two models cannot both claim one. It is the store's answer to
+ * `SerializedSignal`, and it is derived on the client from the built store 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.
+ */
+export interface SerializedStore {
+    state: {
+        [key: string]: SerializedStoreState;
+    };
+    action: {
+        [key: string]: SerializedStoreAction;
+    };
+}

package/types/store/agent.d.ts

@@ -0,0 +1 @@
+export * from "./agent/index.d.ts";

package/types/store/agentic/StToolBuilder.d.ts

@@ -0,0 +1,41 @@
+import { type CLIENT_VALUE, type EnumInstance } from "akanjs/base";
+import type { ParamFieldType } from "akanjs/constant";
+import { type JsonSchema, type ToolConfirm, type ToolEffect, type ToolGuard } from "../../vendor/use-agentic.d.ts";
+export interface StToolMeta {
+    desc?: string;
+    effect?: ToolEffect;
+    confirm?: ToolConfirm;
+    guard?: ToolGuard;
+}
+interface StToolArg {
+    name: string;
+    type: ParamFieldType;
+    optional: boolean;
+}
+type ArgValue<T> = T extends EnumInstance<string, infer V> ? V : T extends {
+    [CLIENT_VALUE]: infer V;
+} ? V : never;
+/**
+ * A component tool in the signal's vocabulary: `st.tool("x", { desc }).arg("id", ID).exec(fn)`.
+ *
+ * This is not A12's rejected store-action builder — a store action derives its schema from the endpoint it is
+ * named after, while a component tool exists nowhere else, so declaring is the only source there is. `.arg()` only
+ * accumulates data; `.exec()` is the one hook, so the chain must complete in one unconditional statement.
+ */
+export declare class StToolBuilder<Args extends unknown[] = []> {
+    #private;
+    constructor(name: string, meta?: StToolMeta, args?: StToolArg[]);
+    arg<T extends ParamFieldType>(name: string, type: T): StToolBuilder<[...Args, ArgValue<T>]>;
+    arg<T extends ParamFieldType>(name: string, type: T, option: {
+        optional: true;
+    }): StToolBuilder<[...Args, ArgValue<T> | null]>;
+    /** The only hook in the chain. `run`, `guard`, and `confirm` stay always-latest; the declaration is mount-static. */
+    exec(run: (...args: Args) => unknown): (...args: Args) => Promise<void>;
+    static parametersOf(args: StToolArg[]): JsonSchema | undefined;
+    /** Scalars and enums only — the value arrives as JSON from a model, so a class instance has no way in. */
+    static schemaOf(type: ParamFieldType): JsonSchema;
+    static positionalOf(toolName: string, args: StToolArg[], named: Record<string, unknown>): unknown[];
+    /** What `AgentBridge` does for endpoint arguments, for a component tool's own — nothing on the wire enforces the published schema. */
+    static checkedValue(toolName: string, argName: string, type: ParamFieldType, value: unknown): unknown;
+}
+export {};

package/types/store/agentic/attachAgentic.d.ts

@@ -0,0 +1,14 @@
+import type { Dispatch, SetStateAction } from "react";
+import { StToolBuilder, type StToolMeta } from "./StToolBuilder.d.ts";
+import { type StExposeMeta } from "./useStExpose.d.ts";
+import { type StStateMeta } from "./useStState.d.ts";
+export interface StAgentic {
+    /** Local state the in-page agent can read. Writes need a `set` type and go through a named setter tool. */
+    useState: <T>(name: string, initial: T | (() => T), meta?: StStateMeta<T>) => [T, Dispatch<SetStateAction<T>>];
+    /** A read-only derived value the agent can read while the component is mounted. */
+    expose: (name: string, value: unknown, meta?: StExposeMeta) => void;
+    /** A component tool: `.arg("id", ID)` chained onto one `.exec()` hook. */
+    tool: (name: string, meta?: StToolMeta) => StToolBuilder;
+}
+/** Idempotent — `StoreRegistry.build` runs once per merged root, always onto the one instance. */
+export declare const attachAgentic: <T extends object>(instance: T) => T & StAgentic;

package/types/store/agentic/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./attachAgentic.d.ts";
+export * from "./readableValue.d.ts";
+export * from "./StToolBuilder.d.ts";
+export * from "./useStExpose.d.ts";
+export * from "./useStState.d.ts";

package/types/store/agentic/readableValue.d.ts

@@ -0,0 +1,3 @@
+import { type MaskModel } from "akanjs/constant";
+/** What `AgentBridge.read` does for store keys, for a hook's value: mask by the declared model, pass scalars, refuse the rest. */
+export declare const readableValue: (name: string, value: unknown, model?: MaskModel) => unknown;

package/types/store/agentic/useStExpose.d.ts

@@ -0,0 +1,8 @@
+import type { MaskModel } from "akanjs/constant";
+export interface StExposeMeta {
+    desc?: string;
+    mask?: MaskModel;
+    serialize?: (value: unknown) => unknown;
+    report?: boolean;
+}
+export declare const useStExpose: (name: string, value: unknown, meta?: StExposeMeta) => void;

package/types/store/agentic/useStState.d.ts

@@ -0,0 +1,12 @@
+import type { MaskModel, ParamFieldType } from "akanjs/constant";
+import type { Dispatch, SetStateAction } from "react";
+export interface StStateMeta<T> {
+    desc?: string;
+    /** The model whose `hidden`/`secret` fields a read strips. An object value with no `mask` and no `serialize` is refused. */
+    mask?: MaskModel;
+    serialize?: (value: T) => unknown;
+    report?: boolean;
+    /** The scalar or enum an agent may write through the generated `set<Name>` tool. Read-only without it. */
+    set?: ParamFieldType;
+}
+export declare const useStState: <T>(name: string, initial: T | (() => T), meta?: StStateMeta<T>) => [T, Dispatch<SetStateAction<T>>];

package/types/store/agentic.d.ts

@@ -0,0 +1 @@
+export * from "./agentic/index.d.ts";

package/types/store/baseSt.d.ts

@@ -63,7 +63,14 @@ declare const BaseStore_base: import("./store.d.ts").StoreCls<"base", import("./
     deviceToken: string;
     currentPath: string;
 }>, any, any, any, any, any, any, any, any>;
+/**
+ * `agent: false` keeps the whole base store off the agent surface. Its keys are framework plumbing that other
+ * effects write into, so the generated setters are levers that do nothing (`setPath` does not navigate — the
+ * router overwrites it) — and `tryJwt`/`tryAccount` hold the caller's credential, which must never reach a model.
+ * The route context block carries the three keys an agent legitimately needs.
+ */
 export declare class BaseStore extends BaseStore_base {
+    static agent: false;
     setDevMode(value: boolean): void;
     setWindowSize(): void;
     showMessage(message: {
@@ -131,7 +138,7 @@ declare const RootStore_base: import("./rootStore.d.ts").RootStoreCls<"root", im
 }, any>;
 export declare class RootStore extends RootStore_base {
 }
-export declare const st: {
+export declare const st: import("./agentic.d.ts").StAgentic & {
     sub: {
         (listener: (state: import("./stateBuilder.d.ts").WritableStateOf<{
             csrLoaded: boolean;
@@ -267,37 +274,37 @@ export declare const st: {
         currentPath: string;
     }>) => U, equals?: ((a: U, b: U) => boolean) | undefined) => U;
     use: {
-        csrLoaded: () => boolean;
-        path: () => string;
-        pathname: () => string;
-        params: () => {
+        csrLoaded: (options?: import("./types.d.ts").StoreUseOptions) => boolean;
+        path: (options?: import("./types.d.ts").StoreUseOptions) => string;
+        pathname: (options?: import("./types.d.ts").StoreUseOptions) => string;
+        params: (options?: import("./types.d.ts").StoreUseOptions) => {
             [key: string]: string;
         };
-        searchParams: () => BaseSearchParamsState;
-        theme: () => string;
-        innerWidth: () => number;
-        innerHeight: () => number;
-        responsive: () => "xl" | "lg" | "md" | "sm" | "xs";
-        uiOperation: () => "loading" | "idle" | "sleep";
-        messages: () => {
+        searchParams: (options?: import("./types.d.ts").StoreUseOptions) => BaseSearchParamsState;
+        theme: (options?: import("./types.d.ts").StoreUseOptions) => string;
+        innerWidth: (options?: import("./types.d.ts").StoreUseOptions) => number;
+        innerHeight: (options?: import("./types.d.ts").StoreUseOptions) => number;
+        responsive: (options?: import("./types.d.ts").StoreUseOptions) => "xl" | "lg" | "md" | "sm" | "xs";
+        uiOperation: (options?: import("./types.d.ts").StoreUseOptions) => "loading" | "idle" | "sleep";
+        messages: (options?: import("./types.d.ts").StoreUseOptions) => {
             type: "info" | "success" | "error" | "warning" | "loading";
             content: string;
             duration: number;
             key: string;
         }[];
-        tryJwt: () => string | null;
-        trySignalType: () => SignalType;
-        tryRoles: () => string[];
-        tryAccount: () => Account<{
+        tryJwt: (options?: import("./types.d.ts").StoreUseOptions) => string | null;
+        trySignalType: (options?: import("./types.d.ts").StoreUseOptions) => SignalType;
+        tryRoles: (options?: import("./types.d.ts").StoreUseOptions) => string[];
+        tryAccount: (options?: import("./types.d.ts").StoreUseOptions) => Account<{
             [key: string]: string | undefined;
         }>;
-        keyboardHeight: () => number;
-        pageState: () => PageState;
-        devMode: () => boolean;
-        deviceToken: () => string;
-        currentPath: () => string;
+        keyboardHeight: (options?: import("./types.d.ts").StoreUseOptions) => number;
+        pageState: (options?: import("./types.d.ts").StoreUseOptions) => PageState;
+        devMode: (options?: import("./types.d.ts").StoreUseOptions) => boolean;
+        deviceToken: (options?: import("./types.d.ts").StoreUseOptions) => string;
+        currentPath: (options?: import("./types.d.ts").StoreUseOptions) => string;
     };
-    do: RootStore & {
+    do: import("./types.d.ts").VoidActions<RootStore> & {
         setCsrLoaded: (value: boolean) => void;
         setPath: (value: string) => void;
         setPathname: (value: string) => void;

package/types/store/databaseStateNames.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The state keys every model store holds, and which of the model's five classes each one is an instance of.
+ *
+ * Shared with the agent catalogue, which needs the class rather than the key: a value read out of the store is
+ * masked by the model it belongs to, and `immerify` drops the constructor, so the live value cannot say what it is.
+ * `modelForm` is the one that matters most — it is an `Input` holding whatever the user has typed, credentials
+ * included, and it reaches the catalogue as a plain object.
+ */
+export declare const databaseStateNames: (refName: string) => {
+    model: string;
+    modelLoading: string;
+    modelForm: string;
+    modelFormLoading: string;
+    modelSubmit: string;
+    modelViewAt: string;
+    modelModal: string;
+    modelOperation: string;
+    defaultModel: string;
+};
+/** Which of the model's classes each generated state key holds, for the keys that hold one at all. */
+export declare const databaseStateModelTypes: {
+    readonly model: "full";
+    readonly modelForm: "input";
+    readonly defaultModel: "full";
+};

package/types/store/formSetterNames.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The keys `makeFormSetter` publishes for one field of one model.
+ *
+ * Shared with the agent catalogue, which has to answer what `setNameOnUser` takes without parsing the name apart —
+ * `set(.+)On(.+)` has more than one reading whenever a field or a model name contains `On`. Computing the same names
+ * forward from the same field metadata is unambiguous, and keeps the two from drifting when a name changes here.
+ */
+export declare const formSetterNames: (className: string, key: string) => {
+    field: string;
+    Field: string;
+    setFieldOnModel: string;
+    addFieldOnModel: string;
+    subFieldOnModel: string;
+    addOrSubFieldOnModel: string;
+    uploadFieldOnModel: string;
+};

package/types/store/index.d.ts

@@ -1,8 +1,15 @@
 export * from "./action.d.ts";
+export * from "./actionTag.d.ts";
+export * from "./agent.d.ts";
+export * from "./agentic.d.ts";
 export * from "./baseSt.d.ts";
+export * from "./databaseStateNames.d.ts";
+export * from "./formSetterNames.d.ts";
 export * from "./rootStore.d.ts";
+export * from "./sliceRole.d.ts";
 export * from "./state.d.ts";
 export * from "./stateBuilder.d.ts";
 export * from "./store.d.ts";
+export { StoreInstance } from "./storeInstance.d.ts";
 export * from "./storeRegistry.d.ts";
 export * from "./types.d.ts";

package/types/store/rootStore.d.ts

@@ -1,5 +1,6 @@
-import type { ACTION_META, Cls, STATE_DERIVED_META, STATE_INIT_META, STATE_META } from "akanjs/base";
+import type { ACTION_META, ACTION_OWNER_META, Cls, STATE_DERIVED_META, STATE_INIT_META, STATE_META } from "akanjs/base";
 import type { SerializedSlice } from "akanjs/signal";
+import type { ActionOwner } from "./actionTag.d.ts";
 import type { StateDerivedMeta, StateInitializerMap } from "./stateBuilder.d.ts";
 import type { SetGetWritable } from "./types.d.ts";
 export type RootStoreCls<RefName extends string = any, WritableState = any, Action = any, InternalSliceObj = any, SliceInfoObj = any, DerivedState = unknown, State = WritableState & DerivedState> = Cls<SetGetWritable<WritableState, State> & Action & {
@@ -13,6 +14,9 @@ export type RootStoreCls<RefName extends string = any, WritableState = any, Acti
     [ACTION_META]: {
         [key: string]: (...args: any[]) => any;
     };
+    [ACTION_OWNER_META]: {
+        [key: string]: ActionOwner;
+    };
     slice: {
         [key: string]: {
             [key: string]: SerializedSlice;

package/types/store/sliceRole.d.ts

@@ -0,0 +1,25 @@
+import type { SerializedArg } from "akanjs/signal";
+import type { SliceStateKey } from "./state.d.ts";
+/** The generated slice actions, named by what they do rather than by the key any one slice publishes them under. */
+export type SliceActionKey = "initModel" | "refreshModel" | "selectModel" | "setPageOfModel" | "addPageOfModel" | "setLimitOfModel" | "setQueryArgsOfModel" | "setSortOfModel";
+/**
+ * What a generated key on `st.do` / `st.use` actually is.
+ *
+ * A slice publishes its keys with the model and the suffix spliced into the role name — `setPageOfUserInOrg` for the
+ * `setPageOfModel` role of `user`'s `inOrg` slice — and the splicing is string replacement over capitalized names.
+ * Recording the role while the key is being built is what saves a reader of the finished store from running that
+ * replacement backwards, which does not have one answer: on a model named `page`, `setPageOfPage` is both the
+ * paging action and a field setter.
+ */
+export interface SliceActionRole {
+    role: SliceActionKey;
+    refName: string;
+    sliceName: string;
+    /** The slice's own arguments, which the `initModel` and `setQueryArgsOfModel` roles take positionally. */
+    args: SerializedArg[];
+}
+export interface SliceStateRole {
+    role: SliceStateKey;
+    refName: string;
+    sliceName: string;
+}

package/types/store/store.d.ts

@@ -1,11 +1,12 @@
-import { ACTION_META, type Cls, type MergeAllActionTypes, type MergeAllKeyOfObjects, type SLICE_META, STATE_DERIVED_META, STATE_INIT_META, STATE_META } from "akanjs/base";
+import { ACTION_META, ACTION_OWNER_META, type Cls, type MergeAllActionTypes, type MergeAllKeyOfObjects, type SLICE_META, STATE_DERIVED_META, STATE_INIT_META, STATE_META } from "akanjs/base";
 import type { FilterInstance } from "akanjs/document";
 import type { ClientSignal } from "akanjs/fetch";
 import type { SerializedSlice, SlceCnstCapitalizedRefName, SlceCnstDefault, SlceCnstFull, SlceCnstInput, SlceCnstInsight, SlceCnstLight, SlceDbFilter, SlceDbSort, SliceCls } from "akanjs/signal";
 import { type DefaultAction } from "./action.d.ts";
+import type { ActionOwner } from "./actionTag.d.ts";
 import { type DefaultState } from "./state.d.ts";
 import { type DerivedStateBuilder, type DerivedStateOf, type StateDerivedMeta, type StateInitializerMap, type WritableStateBuilder, type WritableStateOf } from "./stateBuilder.d.ts";
-import type { InternalSlice, SetGet, SetGetWritable, StoreSliceMap, StoreSliceName, StoreSliceSuffix } from "./types.d.ts";
+import type { InternalSlice, SetGet, SetGetWritable, StoreAgentExposure, StoreSliceMap, StoreSliceName, StoreSliceSuffix } from "./types.d.ts";
 type _SliceMap<S extends SliceCls> = StoreSliceMap<S>;
 type _StoreInput<S extends SliceCls> = SlceCnstInput<S>;
 type _StoreFull<S extends SliceCls> = SlceCnstFull<S>;
@@ -33,10 +34,14 @@ export type StoreCls<RefName extends string = string, WritableState = any, Actio
     [ACTION_META]: {
         [key: string]: (...args: any[]) => any;
     };
+    [ACTION_OWNER_META]: {
+        [key: string]: ActionOwner;
+    };
     slice: {
         [key: string]: SerializedSlice;
     };
     _slice: SlceCls[typeof SLICE_META];
+    agent?: StoreAgentExposure;
 }>;
 export type ModelStore<Sig extends ClientSignal<any, any, any> | string, WritableState, Action, DerivedState = unknown> = Sig extends string ? StoreCls<Sig, WritableState, Action, any, DerivedState> : Sig extends ClientSignal<any, any, any> ? StoreCls<Sig["refName"], WritableState & DefaultState<Sig["_slice"]>, Action & DefaultAction<Sig["_slice"]>, Sig["_slice"], DerivedState> : never;
 export type StoreReturn<Sig extends ClientSignal<any, any, any> | string, WritableState, LibStores extends StoreCls[], // TODO: Change Type for LibStores' state and action

package/types/store/storeInstance.d.ts

@@ -1,5 +1,8 @@
 import type { RefObject } from "react";
+import { type ActionOwner } from "./actionTag.d.ts";
 import type { RootStoreCls } from "./rootStore.d.ts";
+import type { SliceActionRole, SliceStateRole } from "./sliceRole.d.ts";
+import type { StoreUseOptions } from "./types.d.ts";
 type StoreStateRecord = Record<string, unknown>;
 type StoreAction = (...args: unknown[]) => unknown;
 export type ReactAPI = {
@@ -22,9 +25,11 @@ export declare class StoreInstance {
         }): () => void;
     };
     sel: <U>(selector: (state: StoreStateRecord) => U, equals?: (a: U, b: U) => boolean) => U;
+    retainLive: (key: string, scopeKey?: string) => void;
+    releaseLive: (key: string, scopeKey?: string) => void;
     ref: <U>(selector: (state: StoreStateRecord) => U) => RefObject<U>;
     use: {
-        [key: string]: () => unknown;
+        [key: string]: (options?: StoreUseOptions) => unknown;
     };
     do: {
         [key: string]: StoreAction;
@@ -32,6 +37,33 @@ export declare class StoreInstance {
     slice: {
         [key: string]: unknown;
     };
+    /**
+     * How many mounted components are reading each state key right now. `st.use.*` is a hook, so subscription is
+     * presence — this is how an agent context knows which keys the screen is actually built from.
+     */
+    get liveKeys(): ReadonlyMap<string, number>;
+    /**
+     * The live keys as one zone view sees them: retentions tagged at the view's scope or below. The empty view is the
+     * whole screen. Zones are views, not walls — a key read inside a zone counts for that zone and for the root alike.
+     */
+    liveKeysIn(viewKey: string): ReadonlyMap<string, number>;
+    /** Which module declared each action. See `ActionOwner`. */
+    get actionOwners(): ReadonlyMap<string, ActionOwner>;
+    /**
+     * How many arguments each action declares.
+     *
+     * Recorded because `do[key]` is a rest-argument wrapper around the real method, so its own `length` is zero for
+     * everything — the arity is gone by the time anyone holding the instance could ask. A rest parameter on the method
+     * itself still reads as zero; nothing can recover that.
+     */
+    get actionArity(): ReadonlyMap<string, number>;
+    /** What each generated slice key is, for a reader that has only the finished store. See `SliceActionRole`. */
+    get sliceActionRoles(): ReadonlyMap<string, SliceActionRole>;
+    get sliceStateRoles(): ReadonlyMap<string, SliceStateRole>;
+    /** Keys the store materializes from a computation, the URL, or storage. `set` throws on them. */
+    get derivedKeys(): ReadonlySet<string>;
+    /** The `set<Key>` conveniences `#extendAccessors` writes for every plain state key. Their value is untyped. */
+    get generatedSetters(): ReadonlySet<string>;
     constructor(store?: RootStoreCls);
     addStore(store: RootStoreCls): this;
 }

package/types/store/storeRegistry.d.ts

@@ -1,13 +1,18 @@
 import { type MergeAllKeyOfObjects, type MergeAllKeyOfTypes, type MergeAllTypes, STATE_META } from "akanjs/base";
 import type { RootStoreCls } from "./rootStore.d.ts";
 import type { StoreCls } from "./store.d.ts";
+import { StoreInstance } from "./storeInstance.d.ts";
 export type { ReactAPI } from "./storeInstance.d.ts";
 import type { SetGet } from "./types.d.ts";
 import type { WithSelectors } from "./withSelector.d.ts";
 export declare class StoreRegistry {
     #private;
+    /** The one store every `st.use` / `st.do` in the process goes through. What an agent bridge drives. */
+    static get instance(): StoreInstance;
     static register<StrCls extends StoreCls>(store: StrCls): StrCls;
     static get(refName: string): StoreCls | undefined;
+    /** Every registered module store by refName. What the agent surface derives key ownership and exposure from. */
+    static get stores(): ReadonlyMap<string, StoreCls>;
     static merge<RefName extends string, StoreClses extends (StoreCls | RootStoreCls)[]>(refName: RefName, ...stores: StoreClses): RootStoreCls<RefName, MergeAllKeyOfObjects<StoreClses, typeof STATE_META>, MergeAllTypes<StoreClses, keyof SetGet | "slice">, MergeAllKeyOfTypes<StoreClses, "slice">, MergeAllKeyOfObjects<StoreClses, "_slice">>;
     static build<RtStoreCls extends RootStoreCls>(store: RtStoreCls): WithSelectors<RtStoreCls>;
 }

package/types/store/types.d.ts

@@ -9,6 +9,17 @@ export interface Submit {
     loading: boolean;
     times: number;
 }
+/** `agent: false` subscribes without joining the agent surface — the read stays out of the live-key derivation. */
+export interface StoreUseOptions {
+    agent?: boolean;
+}
+/**
+ * A store class's own exposure declaration, read off `static agent`. `false` keeps the whole module off the agent
+ * surface; `exclude` withholds the named state keys and actions while the rest stay derived. Absent means exposed.
+ */
+export type StoreAgentExposure = false | {
+    exclude: string[];
+};
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type PickFunc<State, F extends keyof State = IsAny<State> extends true ? any : keyof State extends never ? any : keyof State> = (...fields: F[]) => {
     [K in (typeof fields)[number]]: Exclude<State[K], null | undefined | "loading">;
@@ -30,6 +41,10 @@ export interface SetPick<State = any> {
 export type Get<State, Actions> = {
     get: () => State & Actions;
 };
+type VoidAction<T> = T extends (...args: infer Args) => infer Ret ? [Ret] extends [PromiseLike<unknown>] ? (...args: Args) => Promise<void> : (...args: Args) => void : T;
+export type VoidActions<Action> = {
+    [K in keyof Action]: VoidAction<Action[K]>;
+};
 export type StoreSliceMap<SlceCls extends SliceCls> = SlceCls[typeof SLICE_META];
 export type StoreSliceSuffix<SlceCls extends SliceCls, Suffix extends keyof StoreSliceMap<SlceCls>> = Suffix & string;
 export type StoreSliceSuffixCap<SlceCls extends SliceCls, Suffix extends keyof StoreSliceMap<SlceCls>> = Capitalize<StoreSliceSuffix<SlceCls, Suffix>>;

package/types/store/withSelector.d.ts

@@ -1,11 +1,12 @@
 import type { Prettify } from "akanjs/base";
 import type { FieldState } from "akanjs/constant";
 import type { RefObject } from "react";
+import type { StAgentic } from "./agentic.d.ts";
 import type { RootStoreCls } from "./rootStore.d.ts";
-import type { SliceStateAction } from "./types.d.ts";
+import type { SliceStateAction, StoreUseOptions, VoidActions } from "./types.d.ts";
 type SetKey<Key extends string> = `set${Capitalize<Key>}`;
 export type WithSelectors<RtStoreCls extends RootStoreCls> = RtStoreCls extends RootStoreCls<any, infer WritableState, infer Action, infer InternalSliceObj, any, any, infer State> ? WithSelectorsOf<State, WritableState, Action, InternalSliceObj> : never;
-type WithSelectorsOf<State, WritableState, Action, InternalSliceObj> = {
+type WithSelectorsOf<State, WritableState, Action, InternalSliceObj> = StAgentic & {
     sub: {
         (listener: (state: State, prev: State) => void): () => void;
         <U>(selector: (state: State) => U, listener: (state: U, prev: U) => void, options?: {
@@ -16,9 +17,9 @@ type WithSelectorsOf<State, WritableState, Action, InternalSliceObj> = {
     ref: <U>(selector: (state: State) => U) => RefObject<U>;
     sel: <U>(selector: (state: State) => U, equals?: (a: U, b: U) => boolean) => U;
     use: {
-        [K in keyof State]: () => State[K];
+        [K in keyof State]: (options?: StoreUseOptions) => State[K];
     };
-    do: Action & {
+    do: VoidActions<Action> & {
         [K in keyof WritableState as K extends string ? SetKey<K> : never]: (value: FieldState<WritableState[K]>) => void;
     };
     get: () => State;
@@ -30,11 +31,9 @@ type WithSelectorsOf<State, WritableState, Action, InternalSliceObj> = {
 export interface SliceSelectors<RefName extends string, State, Action> {
     refName: RefName;
     use: {
-        [K in keyof State]: () => State[K];
+        [K in keyof State]: (options?: StoreUseOptions) => State[K];
     };
-    do: Prettify<{
-        [K in keyof Action]: Action[K];
-    } & {
+    do: Prettify<VoidActions<Action> & {
         [K in keyof State as K extends string ? SetKey<K> : never]: (value: FieldState<State[K]>) => void;
     }>;
     get: () => State;

package/types/test/registerDom.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,7 @@
+import type { PendingApproval } from "../../vendor/use-agentic.d.ts";
+interface ApprovalProps {
+    className?: string;
+    approval: PendingApproval;
+}
+export default function Approval({ className, approval }: ApprovalProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,13 @@
+import type { ChatMessage, ToolCallResult } from "../../vendor/use-agentic.d.ts";
+interface BubbleProps {
+    className?: string;
+    message: ChatMessage;
+    /**
+     * Results by call id, gathered across the transcript. A call and its result are two wire messages — the model
+     * needs both — but they are one thing that happened, so the call's own row resolves in place instead of the
+     * name appearing again as a second row.
+     */
+    results?: ReadonlyMap<string, ToolCallResult>;
+}
+export default function Bubble({ className, message, results }: BubbleProps): import("react/jsx-runtime").JSX.Element;
+export {};