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

package/store/state.ts

@@ -14,6 +14,7 @@ import type {
   SlceDbSort,
   SliceCls,
 } from "akanjs/signal";
+import { databaseStateNames } from "./databaseStateNames";
 import type { StoreSliceArgs, StoreSliceMap, StoreSliceSuffixCap, Submit } from "./types";
 
 export type SliceStateKey =
@@ -151,18 +152,7 @@ export type DefaultState<
 
 export const createDatabaseState = (refName: string) => {
   const cnst = ConstantRegistry.getDatabase(refName);
-  const [fieldName, className] = [refName, capitalize(refName)];
-  const names = {
-    model: fieldName,
-    Model: className,
-    modelLoading: `${fieldName}Loading`,
-    modelForm: `${fieldName}Form`,
-    modelFormLoading: `${fieldName}FormLoading`,
-    modelSubmit: `${fieldName}Submit`,
-    modelViewAt: `${fieldName}ViewAt`,
-    modelModal: `${fieldName}Modal`,
-    modelOperation: `${fieldName}Operation`,
-  };
+  const names = databaseStateNames(refName);
   const baseState = {
     [names.model]: null,
     [names.modelLoading]: true,

package/store/store.ts

@@ -1,5 +1,6 @@
 import {
   ACTION_META,
+  ACTION_OWNER_META,
   type Cls,
   type MergeAllActionTypes,
   type MergeAllKeyOfObjects,
@@ -24,6 +25,7 @@ import type {
   SliceCls,
 } from "akanjs/signal";
 import { type DefaultAction, makeActions, makeFormSetter } from "./action";
+import type { ActionOwner } from "./actionTag";
 import { createDatabaseState, createSliceState, type DefaultState } from "./state";
 import {
   createDerivedStateBuilder,
@@ -40,7 +42,15 @@ import {
   type WritableStateBuilder,
   type WritableStateOf,
 } from "./stateBuilder";
-import type { InternalSlice, SetGet, SetGetWritable, StoreSliceMap, StoreSliceName, StoreSliceSuffix } from "./types";
+import type {
+  InternalSlice,
+  SetGet,
+  SetGetWritable,
+  StoreAgentExposure,
+  StoreSliceMap,
+  StoreSliceName,
+  StoreSliceSuffix,
+} from "./types";
 
 type _SliceMap<S extends SliceCls> = StoreSliceMap<S>;
 type _StoreInput<S extends SliceCls> = SlceCnstInput<S>;
@@ -120,8 +130,10 @@ export type StoreCls<
     [STATE_INIT_META]: StateInitializerMap;
     [STATE_DERIVED_META]: StateDerivedMeta;
     [ACTION_META]: { [key: string]: (...args: any[]) => any };
+    [ACTION_OWNER_META]: { [key: string]: ActionOwner };
     slice: { [key: string]: SerializedSlice };
     _slice: SlceCls[typeof SLICE_META];
+    agent?: StoreAgentExposure;
   }
 >;
 
@@ -187,6 +199,7 @@ export function store<Sig extends ClientSignal<any, any, any> | string, State>(
     static [STATE_INIT_META] = {};
     static [STATE_DERIVED_META] = createEmptyDerivedMeta();
     static [ACTION_META] = {};
+    static [ACTION_OWNER_META] = {};
     static slice = {};
   } as StoreCls;
   const writableStateRaw = stateFactory(createWritableStateBuilder());
@@ -204,6 +217,7 @@ export function store<Sig extends ClientSignal<any, any, any> | string, State>(
     writable.meta,
   );
   Object.assign(storeCls[ACTION_META], ...libStores.map((libStore) => libStore[ACTION_META]));
+  Object.assign(storeCls[ACTION_OWNER_META], ...libStores.map((libStore) => libStore[ACTION_OWNER_META] ?? {}));
   applyMixins(storeCls, libStores);
   if (signal) {
     const signalState = {
@@ -218,6 +232,10 @@ export function store<Sig extends ClientSignal<any, any, any> | string, State>(
     };
     Object.assign(storeCls.prototype, actions);
     Object.assign(storeCls[ACTION_META], actions);
+    Object.assign(
+      storeCls[ACTION_OWNER_META],
+      Object.fromEntries(Object.keys(actions).map((key) => [key, { refName }])),
+    );
     Object.assign(storeCls.slice, signal.serializedSignal.slice ?? {});
   }
   if (derivedStateFactory) {

package/store/storeInstance.ts

@@ -1,27 +1,24 @@
-import { ACTION_META, STATE_DERIVED_META, STATE_INIT_META } from "akanjs/base";
+import { ACTION_META, ACTION_OWNER_META, STATE_DERIVED_META, STATE_INIT_META } from "akanjs/base";
 import { Translator } from "akanjs/client";
 import { capitalize, Logger, parseAkanI18nEnv } from "akanjs/common";
-import { produce } from "immer";
+import type { SerializedArg } from "akanjs/signal";
+import { enableMapSet, produce } from "immer";
 import type { RefObject } from "react";
+import { useScopePath } from "../vendor/use-agentic";
+import { type ActionOwner, actionTagOf, tagAction } from "./actionTag";
 import { useEffect, useRef, useSyncExternalStore } from "./hooks";
 import type { RootStoreCls } from "./rootStore";
+import type { SliceActionKey, SliceActionRole, SliceStateRole } from "./sliceRole";
 import type { SliceStateKey } from "./state";
 import { evaluateInitializers, type SearchParamsState, type StateDerivedMeta } from "./stateBuilder";
+import type { StoreUseOptions } from "./types";
+
+enableMapSet();
 
 type StoreStateRecord = Record<string, unknown>;
 type StoreAction = (...args: unknown[]) => unknown;
 type TranslationParam = Record<string, string | number>;
 
-type SliceActionKey =
-  | "initModel"
-  | "refreshModel"
-  | "selectModel"
-  | "setPageOfModel"
-  | "addPageOfModel"
-  | "setLimitOfModel"
-  | "setQueryArgsOfModel"
-  | "setSortOfModel";
-
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   Boolean(value && typeof value === "object" && !Array.isArray(value));
 
@@ -136,6 +133,11 @@ export class StoreInstance {
   }) as any;
 
   sel = <U>(selector: (state: StoreStateRecord) => U, equals?: (a: U, b: U) => boolean) => {
+    this.#useLiveSelector(selector);
+    return this.#sel(selector, equals);
+  };
+
+  #sel = <U>(selector: (state: StoreStateRecord) => U, equals?: (a: U, b: U) => boolean) => {
     const eq = equals ?? Object.is;
     return useSyncExternalStore(
       (onStoreChange: () => void) => {
@@ -154,7 +156,66 @@ export class StoreInstance {
     );
   };
 
+  retainLive = (key: string, scopeKey = "") => {
+    const scopes = this.#liveKeys.get(key) ?? new Map<string, number>();
+    scopes.set(scopeKey, (scopes.get(scopeKey) ?? 0) + 1);
+    this.#liveKeys.set(key, scopes);
+  };
+
+  releaseLive = (key: string, scopeKey = "") => {
+    const scopes = this.#liveKeys.get(key);
+    if (!scopes) return;
+    const count = scopes.get(scopeKey) ?? 0;
+    if (count <= 1) scopes.delete(scopeKey);
+    else scopes.set(scopeKey, count - 1);
+    if (!scopes.size) this.#liveKeys.delete(key);
+  };
+
+  #useLive(key: string, count = true) {
+    
+    const scopeKey = useScopePath().join(".");
+    useEffect(() => {
+      if (!count) return;
+      this.retainLive(key, scopeKey);
+      return () => {
+        this.releaseLive(key, scopeKey);
+      };
+    }, [key, count, scopeKey]);
+  }
+
+  /**
+   * `sel` and `ref` take an opaque selector, so the keys it reads are learned by running it once over a recording
+   * proxy. Captured at mount, like every surface declaration: the retained set must equal the released set, and a
+   * selector is a new closure every render.
+   */
+  #useLiveSelector(selector: (state: StoreStateRecord) => unknown) {
+    const scopeKey = useScopePath().join(".");
+    useEffect(() => {
+      const keys = [...this.#touched(selector)];
+      for (const key of keys) this.retainLive(key, scopeKey);
+      return () => {
+        for (const key of keys) this.releaseLive(key, scopeKey);
+      };
+    }, [scopeKey]);
+  }
+
+  #touched(selector: (state: StoreStateRecord) => unknown) {
+    const touched = new Set<string>();
+    const proxy = new Proxy(this.#state, {
+      get: (target, key) => {
+        if (typeof key === "string") touched.add(key);
+        return Reflect.get(target, key);
+      },
+    });
+    try {
+      selector(proxy as StoreStateRecord);
+    } catch {
+    }
+    return touched;
+  }
+
   ref = <U>(selector: (state: StoreStateRecord) => U): RefObject<U> => {
+    this.#useLiveSelector(selector);
     const ref = useRef(selector(this.get()));
     useEffect(
       () =>
@@ -166,10 +227,77 @@ export class StoreInstance {
     return ref as RefObject<U>;
   };
 
-  use: { [key: string]: () => unknown } = {};
+  use: { [key: string]: (options?: StoreUseOptions) => unknown } = {};
   do: { [key: string]: StoreAction } = {};
   slice: { [key: string]: unknown } = {};
 
+  readonly #sliceActionRoles = new Map<string, SliceActionRole>();
+  readonly #sliceStateRoles = new Map<string, SliceStateRole>();
+  readonly #actionArity = new Map<string, number>();
+  readonly #actionOwners = new Map<string, ActionOwner>();
+  readonly #liveKeys = new Map<string, Map<string, number>>();
+  readonly #generatedSetters = new Set<string>();
+
+  /**
+   * 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> {
+    return this.liveKeysIn("");
+  }
+
+  /**
+   * 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> {
+    const keys = new Map<string, number>();
+    for (const [key, scopes] of this.#liveKeys) {
+      let total = 0;
+      for (const [scopeKey, count] of scopes) {
+        if (viewKey && scopeKey !== viewKey && !scopeKey.startsWith(`${viewKey}.`)) continue;
+        total += count;
+      }
+      if (total > 0) keys.set(key, total);
+    }
+    return keys;
+  }
+
+  /** Which module declared each action. See `ActionOwner`. */
+  get actionOwners(): ReadonlyMap<string, ActionOwner> {
+    return this.#actionOwners;
+  }
+
+  /**
+   * 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> {
+    return this.#actionArity;
+  }
+
+  /** What each generated slice key is, for a reader that has only the finished store. See `SliceActionRole`. */
+  get sliceActionRoles(): ReadonlyMap<string, SliceActionRole> {
+    return this.#sliceActionRoles;
+  }
+
+  get sliceStateRoles(): ReadonlyMap<string, SliceStateRole> {
+    return this.#sliceStateRoles;
+  }
+
+  /** Keys the store materializes from a computation, the URL, or storage. `set` throws on them. */
+  get derivedKeys(): ReadonlySet<string> {
+    return this.#derivedMeta.derivedKeys;
+  }
+
+  /** The `set<Key>` conveniences `#extendAccessors` writes for every plain state key. Their value is untyped. */
+  get generatedSetters(): ReadonlySet<string> {
+    return this.#generatedSetters;
+  }
+
   constructor(store?: RootStoreCls) {
     if (store) this.addStore(store);
   }
@@ -187,6 +315,7 @@ export class StoreInstance {
       hasNewStateKey = true;
     }
     if (hasNewStateKey) this.#state = nextState;
+    for (const [key, owner] of Object.entries(store[ACTION_OWNER_META] ?? {})) this.#actionOwners.set(key, owner);
     this.#mergeActions(store[ACTION_META]);
     this.#extendAccessors(derivedState, store[ACTION_META]);
     this.#buildSlices(store);
@@ -197,32 +326,42 @@ export class StoreInstance {
   #mergeActions(actions: { [key: string]: StoreAction }) {
     for (const [k, method] of Object.entries(actions)) {
       this.#ctx[k] = (...args: unknown[]) => method.call(this.#ctx, ...args);
+      this.#actionArity.set(k, method.length);
     }
   }
 
   #extendAccessors(state: StoreStateRecord, actions: { [key: string]: StoreAction }) {
     for (const k of Object.keys(state)) {
       if (typeof state[k] !== "function") {
-        this.use[k] = () => this.sel((s) => s[k]);
+        this.use[k] = (options?: StoreUseOptions) => {
+          this.#useLive(k, options?.agent !== false);
+          return this.#sel((s) => s[k]);
+        };
         if (this.#derivedMeta.derivedKeys.has(k)) continue;
         const setKey = `set${capitalize(k)}`;
-        this.do[setKey] = (value: unknown) => this.set({ [k]: value });
+        
+        if (setKey in actions) continue;
+        this.do[setKey] = tagAction((value: unknown) => this.set({ [k]: value }), { action: setKey, state: k });
+        this.#actionArity.set(setKey, 1);
+        this.#generatedSetters.add(setKey);
       }
     }
     for (const k of Object.keys(actions)) {
-      this.do[k] = async (...args: unknown[]) => {
+      const dispatch = async (...args: unknown[]) => {
         Logger.verbose(`${k} action loading...`);
         const start = Date.now();
         try {
+          
           const result = await (this.#ctx[k] as StoreAction)(...args);
           Logger.verbose(`=> ${k} action dispatched (${Date.now() - start}ms)`);
-          return result;
         } catch (error) {
           this.#showActionErrorMessage(k, error);
           Logger.error(`${k} action error return: ${error instanceof Error ? error.message : String(error)}`);
           throw error;
         }
       };
+
+      this.do[k] = tagAction(dispatch, actionTagOf(actions[k]) ?? { action: k });
     }
   }
 
@@ -252,7 +391,7 @@ export class StoreInstance {
     });
   }
 
-  #buildSlice(refName: string, sliceName: string, serializedSlice: { args?: any[] }) {
+  #buildSlice(refName: string, sliceName: string, serializedSlice: { args?: SerializedArg[] }) {
     const [fieldName, className] = [refName, capitalize(refName)];
     const names: { [key in SliceStateKey | SliceActionKey | "model" | "Model"]: string } = {
       model: fieldName,
@@ -322,14 +461,20 @@ export class StoreInstance {
       argLength: serializedSlice.args?.length ?? 0,
     };
 
+    const args = serializedSlice.args ?? [];
     for (const key of Object.keys(namesOfSliceAction) as SliceActionKey[]) {
       const rootActionKey = namesOfSliceAction[key];
-      if (this.do[rootActionKey]) targetSlice.do[names[key]] = this.do[rootActionKey];
+      if (!this.do[rootActionKey]) continue;
+      targetSlice.do[names[key]] = this.do[rootActionKey];
+      this.#sliceActionRoles.set(rootActionKey, { role: key, refName, sliceName, args });
     }
 
     for (const key of Object.keys(namesOfSliceState) as SliceStateKey[]) {
       const rootStateKey = namesOfSliceState[key];
-      if (this.use[rootStateKey]) targetSlice.use[names[key]] = this.use[rootStateKey];
+      if (this.use[rootStateKey]) {
+        targetSlice.use[names[key]] = this.use[rootStateKey];
+        this.#sliceStateRoles.set(rootStateKey, { role: key, refName, sliceName });
+      }
       const setRootKey = `set${capitalize(rootStateKey)}`;
       const setLocalKey = `set${capitalize(names[key])}`;
       if (this.do[setRootKey]) targetSlice.do[setLocalKey] = this.do[setRootKey];

package/store/storeRegistry.ts

@@ -1,5 +1,6 @@
 import {
   ACTION_META,
+  ACTION_OWNER_META,
   type MergeAllKeyOfObjects,
   type MergeAllKeyOfTypes,
   type MergeAllTypes,
@@ -8,6 +9,7 @@ import {
   STATE_META,
 } from "akanjs/base";
 import { applyMixins } from "akanjs/common";
+import { attachAgentic } from "./agentic";
 import type { RootStoreCls } from "./rootStore";
 import type { StoreCls } from "./store";
 import { StoreInstance } from "./storeInstance";
@@ -37,21 +39,33 @@ function getStoreRegistryState(): StoreRegistryState {
 
 export class StoreRegistry {
   static #state = getStoreRegistryState();
+  /** The one store every `st.use` / `st.do` in the process goes through. What an agent bridge drives. */
+  static get instance(): StoreInstance {
+    return StoreRegistry.#state.instance;
+  }
   static register<StrCls extends StoreCls>(store: StrCls): StrCls {
     const parentStore = Object.getPrototypeOf(store) as StoreCls | null;
     const actions = { ...(parentStore?.[ACTION_META] ?? {}) };
+
+    const owners = { ...(parentStore?.[ACTION_OWNER_META] ?? {}) };
     Object.entries(Object.getOwnPropertyDescriptors(store.prototype)).forEach(([key, descriptor]) => {
       if (key === "constructor") return;
       if (!descriptor.value || typeof descriptor.value !== "function") return;
       actions[key] = descriptor.value;
+      owners[key] = { refName: store.refName };
     });
     store[ACTION_META] = actions;
+    store[ACTION_OWNER_META] = owners;
     StoreRegistry.#state.store.set(store.refName, store);
     return store;
   }
   static get(refName: string) {
     return StoreRegistry.#state.store.get(refName);
   }
+  /** Every registered module store by refName. What the agent surface derives key ownership and exposure from. */
+  static get stores(): ReadonlyMap<string, StoreCls> {
+    return StoreRegistry.#state.store;
+  }
   static merge<RefName extends string, StoreClses extends (StoreCls | RootStoreCls)[]>(
     refName: RefName,
     ...stores: StoreClses
@@ -69,6 +83,7 @@ export class StoreRegistry {
       static [STATE_INIT_META] = Object.assign({}, ...stores.map((store) => store[STATE_INIT_META]));
       static [STATE_DERIVED_META] = mergeDerivedMeta(...stores.map((store) => store[STATE_DERIVED_META]));
       static [ACTION_META] = Object.assign({}, ...stores.map((store) => store[ACTION_META]));
+      static [ACTION_OWNER_META] = Object.assign({}, ...stores.map((store) => store[ACTION_OWNER_META] ?? {}));
       static slice: { [key: string]: { [key: string]: SerializedSlice } } = {};
     }
     stores.forEach((store) => {
@@ -79,6 +94,6 @@ export class StoreRegistry {
     return RootStore as any;
   }
   static build<RtStoreCls extends RootStoreCls>(store: RtStoreCls): WithSelectors<RtStoreCls> {
-    return StoreRegistry.#state.instance.addStore(store) as unknown as WithSelectors<RtStoreCls>;
+    return attachAgentic(StoreRegistry.#state.instance.addStore(store)) as unknown as WithSelectors<RtStoreCls>;
   }
 }

package/store/types.ts

@@ -11,6 +11,17 @@ export interface Submit {
   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,
@@ -36,6 +47,13 @@ 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<

package/store/withSelector.ts

@@ -1,8 +1,9 @@
 import type { Prettify } from "akanjs/base";
 import type { FieldState } from "akanjs/constant";
 import type { RefObject } from "react";
+import type { StAgentic } from "./agentic";
 import type { RootStoreCls } from "./rootStore";
-import type { SliceStateAction } from "./types";
+import type { SliceStateAction, StoreUseOptions, VoidActions } from "./types";
 
 type SetKey<Key extends string> = `set${Capitalize<Key>}`;
 
@@ -11,7 +12,7 @@ export type WithSelectors<RtStoreCls extends RootStoreCls> =
     ? 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>(
@@ -26,9 +27,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;
@@ -49,12 +50,10 @@ 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];
-    } & {
+    VoidActions<Action> & {
       [K in keyof State as K extends string ? SetKey<K> : never]: (value: FieldState<State[K]>) => void;
     }
   >;

package/test/registerDom.ts

@@ -0,0 +1,4 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+if (!GlobalRegistrator.isRegistered) GlobalRegistrator.register();
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;

package/types/base/symbols.d.ts

@@ -13,6 +13,10 @@ export declare const STATE_META: unique symbol;
 export declare const STATE_INIT_META: unique symbol;
 export declare const STATE_DERIVED_META: unique symbol;
 export declare const ACTION_META: unique symbol;
+/** Which module declared each action. See `ActionOwner`. */
+export declare const ACTION_OWNER_META: unique symbol;
+/** What a dispatcher does, carried on the function so a component handed one can annotate the DOM with it. */
+export declare const ACTION_TAG: unique symbol;
 export declare const SERVER_VALUE: unique symbol;
 export declare const CLIENT_VALUE: unique symbol;
 export declare const DEFAULT_VALUE: unique symbol;

package/types/client/cn.d.ts

@@ -6,6 +6,11 @@ import { type ClassNameValue } from "tailwind-merge";
  * `cn("bg-primary", "bg-open")` correctly resolves to `"bg-open"` instead of keeping both.
  */
 export declare const colorTokens: string[];
+/**
+ * Akan's semantic radius tokens (`--radius-box` / `--radius-field` in ui/styles.css). Without them
+ * `cn("rounded-field", "rounded-full")` keeps both classes and stylesheet order decides the winner.
+ */
+export declare const radiusTokens: string[];
 /** The one class-combining function: joins strings/arrays/conditional parts (`cond && "x"`) and
  *  resolves Tailwind conflicts with a shared tailwind-merge instance that knows Akan's semantic
  *  color tokens. clsx-style object syntax (`{ x: cond }`) is not supported — write `cond && "x"`. */

package/types/client/csrTypes.d.ts

@@ -428,6 +428,7 @@ export interface FrameLayoutState {
     keyboard: KeyboardFrameState;
     contentViewport: FrameContentViewportState;
     keyboardAccessory: KeyboardAccessoryFrameState;
+    contentAnchor?: "bottom";
     platformProfile: FramePlatformProfile;
     zIndex: FrameLayerZIndex;
     pageStateByPath: Map<string, PageState>;
@@ -436,6 +437,7 @@ export interface FrameSlotRegistration {
     scope?: FrameSlotScope;
     type: FrameSlotType;
     role?: FrameSlotRole;
+    contentAnchor?: "bottom";
     height?: number;
     estimatedHeight?: number;
     source?: "navbar" | "topInset" | "bottomInset" | "bottomTab" | (string & {});

package/types/common/Logger.d.ts

@@ -17,6 +17,8 @@ export declare class Logger {
     static removeSink(sink: LoggerSink): void;
     static setFileLevel(level: LogLevel): void;
     static isVerbose(): boolean;
+    /** For hot-path callers that would otherwise build a message the level is about to discard. */
+    static shouldLog(logLevel: LogLevel): boolean;
     name?: string;
     constructor(name?: string);
     trace(msg: string, context?: string, name?: string): void;

package/types/common/deepObjectify.d.ts

@@ -1,4 +1,6 @@
-export declare const deepObjectify: <T = unknown>(obj: T | null | undefined, option?: {
+interface DeepObjectifyOption {
     serializable?: boolean;
     convertDate?: "string" | "number";
-}) => T;
+}
+export declare const deepObjectify: <T = unknown>(obj: T | null | undefined, option?: DeepObjectifyOption) => T;
+export {};

package/types/common/index.d.ts

@@ -17,13 +17,14 @@ export { decodeJwtPayload } from "./jwtDecode.d.ts";
 export { Logger, type LoggerSink, type LoggerSinkEntry, type LogLevel } from "./Logger.d.ts";
 export { type AkanI18nConfig, type AkanI18nConfigInput, DEFAULT_AKAN_I18N, parseAkanI18nEnv, resolveAkanI18nConfig, } from "./localeConfig.d.ts";
 export { lowerlize } from "./lowerlize.d.ts";
+export { isMcpDescribableArg, type McpExposureEndpoint, type McpExposureOption, mcpBaseVerbOf, mcpHintsOf, mcpPromptRefusalOf, mcpRefusalOf, } from "./mcpExposure.d.ts";
 export { mergeVersion } from "./mergeVersion.d.ts";
 export { objectify } from "./objectify.d.ts";
 export { pathGet } from "./pathGet.d.ts";
 export { pathSet } from "./pathSet.d.ts";
 export { randomPick } from "./randomPick.d.ts";
 export { randomPicks } from "./randomPicks.d.ts";
-export { assertUniqueRoutePatterns, compareRouteSpecificity, isRouteSourceFile, isSpecialRouteLeaf, matchRoutePattern, normalizeRoutePattern, type ParsedRouteModuleKey, parseRouteModuleKey, type RouteModuleKind, routeSegmentToPatternPart, routeSegmentToTreePath, tryParseRouteModuleKey, type ValidatePageSourceFileOptions, type ValidateSubRoutePageKeyOptions, validatePageSourceFile, validateSubRoutePageKey, } from "./routeConvention.d.ts";
+export { assertUniqueRoutePatterns, compareRouteSpecificity, getRouteExports, isRouteSourceFile, isSpecialRouteLeaf, LAYOUT_ROUTE_EXPORTS, matchRoutePattern, normalizeRoutePattern, PAGE_ROUTE_EXPORTS, type ParsedRouteModuleKey, parseRouteModuleKey, RESERVED_ROUTE_CONFIG_EXPORTS, ROOT_LAYOUT_ROUTE_EXPORTS, type RouteModuleKind, routeSegmentToPatternPart, routeSegmentToTreePath, tryParseRouteModuleKey, type ValidatePageSourceFileOptions, type ValidateSubRoutePageKeyOptions, validatePageSourceFile, validateSubRoutePageKey, } from "./routeConvention.d.ts";
 export { sleep } from "./sleep.d.ts";
 export { splitVersion } from "./splitVersion.d.ts";
 export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute.d.ts";

package/types/common/mcpExposure.d.ts

@@ -0,0 +1,60 @@
+/**
+ * What MCP says about one endpoint: whether it is published, why it is not, and the hints it carries.
+ *
+ * Structurally typed like the rest of `common/` so the same rules answer on both sides — the server builds its
+ * catalogue from them and the browser API explorer badges an endpoint from them. A second implementation would
+ * eventually disagree, and an audit surface that disagrees with the catalogue is worse than none.
+ *
+ * Every rejection returns the sentence an author reads, at boot in the server log and in the explorer. Fail-closed
+ * with no reason leaves an author whose endpoint is missing from the catalogue nowhere to look but the source.
+ */
+export interface McpExposureEndpoint {
+    type: string;
+    returns: {
+        refName: string;
+    };
+    args: {
+        name: string;
+        refName: string;
+        type: string;
+        arrDepth?: number;
+        nullable?: boolean;
+    }[];
+    guards?: string[];
+    fileUpload?: boolean;
+}
+export interface McpExposureOption {
+    /**
+     * The read-only deployment valve, which is server configuration. The browser explorer cannot know it and so
+     * badges what the code decided; the boot log is where a read-only deployment says what it dropped.
+     */
+    readOnly?: boolean;
+}
+/** `Any` publishes as the empty schema, which tells a model nothing — so it is left out rather than described. */
+export declare const isMcpDescribableArg: (arg: {
+    refName: string;
+}) => boolean;
+/** Which CRUD verb a generated endpoint key is, or `null` when the key is not one of the five. */
+export declare const mcpBaseVerbOf: (refName: string, key: string) => "get" | "create" | "update" | "remove" | null;
+/**
+ * The hints a client renders beside a tool. Hints only — clients are told to distrust them, so they inform a UI
+ * and never stand in for a guard. `openWorldHint` is always false: every endpoint reaches this app's own
+ * database, not the wider internet.
+ */
+export declare const mcpHintsOf: (key: string, endpoint: {
+    type: string;
+}) => {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+/** The sentence explaining why this endpoint is not in the catalogue, or `null` when it is. */
+export declare const mcpRefusalOf: (endpoint: McpExposureEndpoint, { readOnly }?: McpExposureOption) => string | null;
+/**
+ * A prompt is a read exposed on the same terms as a query, so every rejection here is one thing: an argument
+ * `prompts/get` cannot carry. Its `arguments` is a flat string map — one string per name, and no schema beside it
+ * — which rules out the argument *kinds* the builder already refuses and, just as surely, two argument *types* it
+ * accepts. A tool escapes both because it publishes a real JSON Schema.
+ */
+export declare const mcpPromptRefusalOf: (endpoint: McpExposureEndpoint) => string | null;