akanjs 3.0.0-beta.9 → 3.0.1

package/store/storeInstance.ts

@@ -1,17 +1,18 @@
-import { ACTION_META, ACTION_OWNER_META, getEnv, 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 { loadCapacitorApp } from "akanjs/client/capacitor";
-import { capitalize, type DynamicRecord, Logger, parseAkanI18nEnv } from "akanjs/common";
+import { appState, isNativeApp } from "akanjs/client/native";
+import { capitalize, type DynamicRecord, isRecord, Logger, parseAkanI18nEnv } from "akanjs/common";
 import { ConstantRegistry } from "akanjs/constant";
 import type { SerializedArg } from "akanjs/signal";
 import { enableMapSet, produce } from "immer";
 import type { RefObject } from "react";
-import { useScopePath } from "../vendor/use-agentic";
+import { type AgentGate, useAgentGate, useScopePath } from "../vendor/use-agentic";
 import { type ActionOwner, actionTagOf, tagAction } from "./actionTag";
 import { useFormTools } from "./agentic/useFormTools";
 import { DraftStore } from "./draftStore";
 import { useEffect, useRef, useSyncExternalStore } from "./hooks";
 import type { RootStoreCls } from "./rootStore";
+import { sliceKeysOf } from "./sliceKeys";
 import type { SliceActionKey, SliceActionRole, SliceStateRole } from "./sliceRole";
 import type { DraftState, SliceStateKey } from "./state";
 import { evaluateInitializers, type SearchParamsState, type StateDerivedMeta } from "./stateBuilder";
@@ -21,14 +22,10 @@ enableMapSet();
 
 type StoreStateRecord = Record<string, unknown>;
 
-/** Long enough that a burst of typing is one write, short enough that a route change lands what came before it. */
 const DRAFT_DEBOUNCE_MS = 400;
 type StoreAction = (...args: unknown[]) => unknown;
 type TranslationParam = Record<string, string | number>;
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  Boolean(value && typeof value === "object" && !Array.isArray(value));
-
 const getActionErrorKey = (error: unknown) => {
   if (typeof error === "string") return error;
   if (!isRecord(error)) return String(error);
@@ -59,6 +56,8 @@ export type ReactAPI = {
 
 export class StoreInstance {
   #state: StoreStateRecord = {};
+  
+  #serverState: StoreStateRecord = {};
   #listeners = new Set<() => void>();
   #derivedMeta: StateDerivedMeta = { drafts: {}, persistSession: {}, search: {}, computed: {}, derivedKeys: new Set() };
   #draftTimers = new Map<string, ReturnType<typeof setTimeout>>();
@@ -149,6 +148,7 @@ export class StoreInstance {
 
   #sel = <U>(selector: (state: StoreStateRecord) => U, equals?: (a: U, b: U) => boolean) => {
     const eq = equals ?? Object.is;
+    let serverSnapshot: { value: U } | null = null;
     return useSyncExternalStore(
       (onStoreChange: () => void) => {
         let prev = selector(this.#state);
@@ -162,51 +162,57 @@ export class StoreInstance {
         return this.subscribe(listener);
       },
       () => selector(this.#state),
-      () => selector(this.#state),
+      
+      () => {
+        serverSnapshot ??= { value: selector(this.#serverState) };
+        return serverSnapshot.value;
+      },
     );
   };
 
-  retainLive = (key: string, scopeKey = "") => {
-    const scopes = this.#liveKeys.get(key) ?? new Map<string, number>();
-    scopes.set(scopeKey, (scopes.get(scopeKey) ?? 0) + 1);
+  retainLive = (key: string, scopeKey = "", gate: AgentGate | null = null) => {
+    const scopes = this.#liveKeys.get(key) ?? new Map<string, Map<AgentGate | null, number>>();
+    const gates = scopes.get(scopeKey) ?? new Map<AgentGate | null, number>();
+    gates.set(gate, (gates.get(gate) ?? 0) + 1);
+    scopes.set(scopeKey, gates);
     this.#liveKeys.set(key, scopes);
   };
 
-  releaseLive = (key: string, scopeKey = "") => {
+  releaseLive = (key: string, scopeKey = "", gate: AgentGate | null = null) => {
+    const gates = this.#liveKeys.get(key)?.get(scopeKey);
+    if (!gates) return;
+    const count = gates.get(gate) ?? 0;
+    if (count <= 1) gates.delete(gate);
+    else gates.set(gate, count - 1);
+    if (gates.size) return;
     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);
+    scopes?.delete(scopeKey);
+    if (!scopes?.size) this.#liveKeys.delete(key);
   };
 
   #useLive(key: string, count = true) {
-    
+
     const scopeKey = useScopePath().join(".");
+    const gate = useAgentGate();
     useEffect(() => {
       if (!count) return;
-      this.retainLive(key, scopeKey);
+      this.retainLive(key, scopeKey, gate);
       return () => {
-        this.releaseLive(key, scopeKey);
+        this.releaseLive(key, scopeKey, gate);
       };
-    }, [key, count, scopeKey]);
+    }, [key, count, scopeKey, gate]);
   }
 
-  /**
-   * `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(".");
+    const gate = useAgentGate();
     useEffect(() => {
       const keys = [...this.#touched(selector)];
-      for (const key of keys) this.retainLive(key, scopeKey);
+      for (const key of keys) this.retainLive(key, scopeKey, gate);
       return () => {
-        for (const key of keys) this.releaseLive(key, scopeKey);
+        for (const key of keys) this.releaseLive(key, scopeKey, gate);
       };
-    }, [scopeKey]);
+    }, [scopeKey, gate]);
   }
 
   #touched(selector: (state: StoreStateRecord) => unknown) {
@@ -245,51 +251,37 @@ export class StoreInstance {
   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 #liveKeys = new Map<string, Map<string, Map<AgentGate | null, 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.
-   */
+  /** How many mounted components read each state key right now. */
   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.
-   */
+  /** Live keys retained at `viewKey`'s scope or below, behind no gate or an active one; `""` is the whole screen. */
   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) {
+      for (const [scopeKey, gates] of scopes) {
         if (viewKey && scopeKey !== viewKey && !scopeKey.startsWith(`${viewKey}.`)) continue;
-        total += count;
+        for (const [gate, count] of gates) if (gate?.active ?? true) 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.
-   */
+  /** Each method's own `length`: `do[key]` is a rest-argument wrapper whose `length` is 0. */
   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;
   }
@@ -298,12 +290,12 @@ export class StoreInstance {
     return this.#sliceStateRoles;
   }
 
-  /** Keys the store materializes from a computation, the URL, or storage. `set` throws on them. */
+  /** `search()` and `computed()` keys; `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. */
+  /** The generated `set<Key>` setters for plain state keys; their value is untyped. */
   get generatedSetters(): ReadonlySet<string> {
     return this.#generatedSetters;
   }
@@ -315,16 +307,15 @@ export class StoreInstance {
   addStore(store: RootStoreCls) {
     this.#mergeDerivedMeta(store[STATE_DERIVED_META]);
     const newState = evaluateInitializers(store[STATE_INIT_META] ?? {});
+    this.#serverState = this.#withNewKeys(
+      this.#serverState,
+      this.#materializeDerived({ ...this.#serverState, ...newState }, this.#serverState, true),
+    );
     const hydratedState = this.#hydratePersistSession(newState);
     const derivedState = this.#materializeDerived({ ...this.#state, ...hydratedState }, this.#state);
-    let hasNewStateKey = false;
-    const nextState = { ...this.#state };
-    for (const [key, value] of Object.entries(derivedState)) {
-      if (key in nextState) continue;
-      nextState[key] = value;
-      hasNewStateKey = true;
-    }
-    if (hasNewStateKey) this.#state = nextState;
+    const nextState = this.#withNewKeys(this.#state, derivedState);
+    const hasNewStateKey = nextState !== this.#state;
+    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]);
@@ -333,7 +324,12 @@ export class StoreInstance {
     return this;
   }
 
-  /** `<model>Form` for a model this client knows, or null — the only state key whose setters are worth publishing. */
+  #withNewKeys(state: StoreStateRecord, additions: StoreStateRecord) {
+    const newKeys = Object.keys(additions).filter((key) => !(key in state));
+    if (!newKeys.length) return state;
+    return { ...state, ...Object.fromEntries(newKeys.map((key) => [key, additions[key]])) };
+  }
+
   static #formRefNameOf(key: string) {
     if (!key.endsWith("Form")) return null;
     const refName = key.slice(0, -"Form".length);
@@ -350,7 +346,7 @@ export class StoreInstance {
   #extendAccessors(state: StoreStateRecord, actions: { [key: string]: StoreAction }) {
     for (const k of Object.keys(state)) {
       if (typeof state[k] !== "function") {
-
+        
         const formRefName = StoreInstance.#formRefNameOf(k);
         this.use[k] = formRefName
           ? (options?: StoreUseOptions) => {
@@ -379,7 +375,6 @@ export class StoreInstance {
         Logger.verbose(`${k} action loading...`);
         const start = Date.now();
         try {
-          
           await (this.#ctx[k] as StoreAction)(...args);
           Logger.verbose(`=> ${k} action dispatched (${Date.now() - start}ms)`);
         } catch (error) {
@@ -388,7 +383,7 @@ export class StoreInstance {
           throw error;
         }
       };
-
+      
       this.do[k] = tagAction(dispatch, actionTagOf(actions[k]) ?? { action: k });
     }
   }
@@ -413,74 +408,15 @@ export class StoreInstance {
   #buildSlices(store: RootStoreCls) {
     Object.entries(store.slice).forEach(([refName, sliceObj]) => {
       Object.entries(sliceObj).forEach(([suffix, serializedSlice]) => {
-        const sliceName = `${refName}${capitalize(suffix)}`;
-        this.#buildSlice(refName, sliceName, serializedSlice);
+        this.#buildSlice(refName, suffix, serializedSlice);
       });
     });
   }
 
-  #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,
-      Model: className,
-      defaultModel: `default${className}`,
-      modelInsight: `${fieldName}Insight`,
-      modelList: `${fieldName}List`,
-      modelListLoading: `${fieldName}ListLoading`,
-      modelInitList: `${fieldName}InitList`,
-      modelInitAt: `${fieldName}InitAt`,
-      modelStaleAt: `${fieldName}StaleAt`,
-      pageOfModel: `pageOf${className}`,
-      limitOfModel: `limitOf${className}`,
-      hasMoreOfModel: `hasMoreOf${className}`,
-      isCumulativeOfModel: `isCumulativeOf${className}`,
-      queryArgsOfModel: `queryArgsOf${className}`,
-      sortOfModel: `sortOf${className}`,
-      modelSelection: `${fieldName}Selection`,
-      initModel: `init${className}`,
-      refreshModel: `refresh${className}`,
-      selectModel: `select${className}`,
-      setPageOfModel: `setPageOf${className}`,
-      loadMoreOfModel: `loadMoreOf${className}`,
-      setLimitOfModel: `setLimitOf${className}`,
-      setQueryArgsOfModel: `setQueryArgsOf${className}`,
-      setSortOfModel: `setSortOf${className}`,
-      applyLiveModel: `applyLive${className}`,
-      watchLiveModel: `watchLive${className}`,
-      lastPageOfModel: `lastPageOf${className}`,
-    };
-    const SliceName = capitalize(sliceName);
-    const namesOfSliceState: { [key in SliceStateKey]: string } = {
-      defaultModel: SliceName.replace(names.Model, names.defaultModel),
-      modelInitList: SliceName.replace(names.Model, names.modelInitList),
-      modelInsight: sliceName.replace(names.model, names.modelInsight),
-      modelList: sliceName.replace(names.model, names.modelList),
-      modelListLoading: sliceName.replace(names.model, names.modelListLoading),
-      modelInitAt: SliceName.replace(names.Model, names.modelInitAt),
-      modelStaleAt: SliceName.replace(names.Model, names.modelStaleAt),
-      lastPageOfModel: SliceName.replace(names.Model, names.lastPageOfModel),
-      pageOfModel: SliceName.replace(names.Model, names.pageOfModel),
-      limitOfModel: SliceName.replace(names.Model, names.limitOfModel),
-      hasMoreOfModel: SliceName.replace(names.Model, names.hasMoreOfModel),
-      isCumulativeOfModel: SliceName.replace(names.Model, names.isCumulativeOfModel),
-      queryArgsOfModel: SliceName.replace(names.Model, names.queryArgsOfModel),
-      sortOfModel: SliceName.replace(names.Model, names.sortOfModel),
-      modelSelection: SliceName.replace(names.Model, names.modelSelection),
-    };
-    const namesOfSliceAction: { [key in SliceActionKey]: string } = {
-      initModel: SliceName.replace(names.Model, names.initModel),
-      refreshModel: SliceName.replace(names.Model, names.refreshModel),
-      selectModel: SliceName.replace(names.Model, names.selectModel),
-      setPageOfModel: SliceName.replace(names.Model, names.setPageOfModel),
-      loadMoreOfModel: SliceName.replace(names.Model, names.loadMoreOfModel),
-      setLimitOfModel: SliceName.replace(names.Model, names.setLimitOfModel),
-      setQueryArgsOfModel: SliceName.replace(names.Model, names.setQueryArgsOfModel),
-      setSortOfModel: SliceName.replace(names.Model, names.setSortOfModel),
-      applyLiveModel: SliceName.replace(names.Model, names.applyLiveModel),
-      watchLiveModel: SliceName.replace(names.Model, names.watchLiveModel),
-    };
-
+  #buildSlice(refName: string, suffix: string, serializedSlice: { args?: SerializedArg[] }) {
+    const sliceName = `${refName}${capitalize(suffix)}`;
+    const names = sliceKeysOf(refName);
+    const { state: namesOfSliceState, action: namesOfSliceAction } = sliceKeysOf(refName, suffix);
     const targetSlice: {
       do: { [key: string]: (...args: any[]) => void };
       use: { [key: string]: () => any };
@@ -501,18 +437,18 @@ export class StoreInstance {
     for (const key of Object.keys(namesOfSliceAction) as SliceActionKey[]) {
       const rootActionKey = namesOfSliceAction[key];
       if (!this.do[rootActionKey]) continue;
-      targetSlice.do[names[key]] = this.do[rootActionKey];
+      targetSlice.do[names.action[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];
+        targetSlice.use[names.state[key]] = this.use[rootStateKey];
         this.#sliceStateRoles.set(rootStateKey, { role: key, refName, sliceName });
       }
       const setRootKey = `set${capitalize(rootStateKey)}`;
-      const setLocalKey = `set${capitalize(names[key])}`;
+      const setLocalKey = `set${capitalize(names.state[key])}`;
       if (this.do[setRootKey]) targetSlice.do[setLocalKey] = this.do[setRootKey];
     }
 
@@ -520,7 +456,7 @@ export class StoreInstance {
       const state = this.get();
       return Object.fromEntries(
         (Object.entries(namesOfSliceState) as [SliceStateKey, string][]).map(([key, value]) => [
-          names[key],
+          names.state[key],
           state[value],
         ]),
       );
@@ -573,16 +509,6 @@ export class StoreInstance {
     }
   }
 
-  /**
-   * Schedules a save of every open form whose value moved.
-   *
-   * A form is only saved while `<model>Draft.key` is armed — `new<Model>` / `edit<Model>` arm it and a submit or
-   * reset disarms it — so a store that never opened a form writes nothing. The dirty comparison happens in the
-   * flush rather than here: it encodes the whole form, and a keystroke is not worth that.
-   *
-   * The debounce belongs to the store, not to a component, so an editor that unmounts mid-window still lands its
-   * last write. Only a closing tab can outrun it, which is what the flush listeners answer.
-   */
   #syncDrafts(prev: StoreStateRecord, next: StoreStateRecord) {
     if (typeof window === "undefined") return;
     for (const meta of Object.values(this.#derivedMeta.drafts)) {
@@ -592,7 +518,7 @@ export class StoreInstance {
         continue;
       }
       if (Object.is(prev[meta.formKey], next[meta.formKey])) continue;
-
+      
       if (!Object.is(prev[meta.draftKey], next[meta.draftKey])) continue;
       this.#armDraftFlush();
       this.#cancelDraftTimer(meta.formKey);
@@ -619,7 +545,7 @@ export class StoreInstance {
     if (!draft?.key || !form) return;
     try {
       const hash = DraftStore.formHash(refName, form);
-
+      
       if (hash === draft.baseHash) {
         await DraftStore.remove(draft.key);
         return;
@@ -635,7 +561,7 @@ export class StoreInstance {
     }
   }
 
-  /** Lands every pending write before the page or the app goes away. */
+  /** Writes every pending draft now, cancelling its debounce. */
   flushDrafts = () => {
     for (const [formKey, timer] of this.#draftTimers) {
       clearTimeout(timer);
@@ -655,18 +581,18 @@ export class StoreInstance {
     window.addEventListener("pagehide", this.flushDrafts);
     document.addEventListener("visibilitychange", onHide);
     
-    if (getEnv().renderMode === "csr")
-      void loadCapacitorApp()
-        .then(({ App }) => App.addListener("pause", this.flushDrafts))
-        .catch(() => undefined);
+    if (isNativeApp())
+      appState.listen("change", ({ state }) => {
+        if (state === "background") this.flushDrafts();
+      });
   }
 
-  #materializeDerived(next: StoreStateRecord, prev: StoreStateRecord) {
+  #materializeDerived(next: StoreStateRecord, prev: StoreStateRecord, server = typeof window === "undefined") {
     const materialized = { ...next };
     const changedKeys = new Set(Object.keys(materialized).filter((key) => !Object.is(materialized[key], prev[key])));
     const searchParams = (materialized.searchParams ?? {}) as SearchParamsState;
     for (const [key, meta] of Object.entries(this.#derivedMeta.search)) {
-      const value = typeof window === "undefined" ? meta.getDefault() : meta.parseSearch(searchParams);
+      const value = server ? meta.getDefault() : meta.parseSearch(searchParams);
       if (!Object.is(materialized[key], value)) {
         materialized[key] = value;
         changedKeys.add(key);

package/store/storeRegistry.ts

@@ -42,14 +42,13 @@ 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;
@@ -64,11 +63,6 @@ export class StoreRegistry {
     return store;
   }
 
-  /**
-   * A `_postSet<Field>` hook cannot be typed — the generated setters live in a mapped type, so every name the base
-   * declares is a property a subclass method may not redeclare (TS2425), and the hook only compiles because the base
-   * declares nothing under it. A misspelled field would therefore never fire and never complain, so say so here.
-   */
   static #warnUnknownPostSetHooks(store: StoreCls) {
     const hooks = Object.keys(Object.getOwnPropertyDescriptors(store.prototype)).filter((key) =>
       key.startsWith("_postSet"),
@@ -85,7 +79,6 @@ export class StoreRegistry {
   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;
   }

package/store/types.ts

@@ -22,7 +22,7 @@ type PickFunc<
   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">;
-}; 
+};
 export interface SetGet<State = any> {
   set: (setState: Partial<State> | ((state: State) => void)) => void;
   get: () => State;