cabloy 5.1.103 → 5.1.104

package/.cabloy-version

@@ -1 +1 @@
-5.1.103
+5.1.104

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 5.1.104
+
+### Features
+
+- Add update capabilities.
+
+### Bug Fixes
+
+- Initialize the passport model during application startup.
+
+### Improvements
+
+- Rename the generic async state type.
+- Rename async local state APIs.
+- Document the passport SSR state bridge.
+- Clarify memory state SSR transfer behavior.
+- Clarify how to select model state helpers.
+
 ## 5.1.103
 
 ### Features

package/cabloy-docs/frontend/a-model-under-the-hood.md

@@ -85,9 +85,21 @@ Its main jobs are:
 - create the shared `QueryClient`
 - create the `QueryCache`
 - install the Vue Query plugin into the app
-- on the server, dehydrate query state after render
-- on the client, hydrate query state during SSR pre-hydration
-- clear the query client after server rendering completes
+- on the server, dehydrate eligible query state after render into `stateDefer.query`
+- on the client, hydrate that snapshot during SSR pre-hydration
+- clear the server query client after the snapshot has been created
+
+The server-to-client handoff is therefore:
+
+```text
+server QueryClient
+  → dehydrate after render
+  → stateDefer.query
+  → deferred SSR bootstrap state
+  → client QueryClient hydrate during SSR pre-hydration
+```
+
+This is an initial SSR handoff, not browser persistence. The server cache is request-scoped for this flow and is cleared after its snapshot is taken.
 
 This is the second important lower-level rule:
 
@@ -200,6 +212,10 @@ A practical reading rule is:
 - different state families differ in persistence/storage and SSR behavior
 - but they still participate in one model runtime vocabulary and query-key system
 
+`$useStateMem(...)` makes the two policy axes especially clear. It returns an assignable custom-ref surface that reads and writes through the Model Query Cache, while setting `persister: false` so no browser storage adapter is used. No persistence backend does not imply no SSR transfer: a successful eligible memory query can still be included in the shared Query Cache snapshot.
+
+A hydrated entry is reusable only when the later call resolves to the same effective key. The runtime prefixes each logical key with Model identity and, for selector-enabled Models, selector identity.
+
 ## Persister storage selection and restore/save/remove behavior
 
 The persister layer lives in:
@@ -243,7 +259,13 @@ This file confirms default behavior such as:
 - persistence max-age defaults
 - dehydration rules for sync persister-backed queries
 
-This is the place to check when the runtime feels surprising even though your page/model code looks correct.
+The current dehydration decision is ordered:
+
+1. `meta.ssr.dehydrate === false` explicitly excludes a query.
+2. A sync persister-backed query is excluded.
+3. Remaining queries use TanStack Query's current default dehydration predicate, which accepts successful queries.
+
+This is why `$useStateMem(...)` can participate in the initial SSR transfer despite `persister: false`, while `$useStateLocalAsync(...)` opts out explicitly. This is the place to check when the runtime feels surprising even though your page/model code looks correct.
 
 ## What this page does not re-explain
 

package/cabloy-docs/frontend/model-architecture.md

@@ -129,7 +129,7 @@ The `a-model` source exposes five main state families through `BeanModelBase` he
 - `mem` → in-memory state through `$useStateMem(...)`
 - `local` → local-storage state through `$useStateLocal(...)`
 - `cookie` → cookie-backed state through `$useStateCookie(...)`
-- `db` → async persisted state through `$useStateDb(...)`
+- `db` → async persisted state through `$useStateLocalAsync(...)`
 
 This is why Zova Model is better understood as a **unified model-state layer** rather than only a remote-data wrapper.
 

package/cabloy-docs/frontend/model-state-guide.md

@@ -86,7 +86,34 @@ The important point is architectural:
 
 ## The main helper families
 
-The current source organizes model state around these helper families.
+The current source organizes model state around these helper families. They share model-owned query-key and cache infrastructure, but differ in the surface returned to callers and in their persistence and restore lifecycle.
+
+### Choose the state helper by ownership and lifecycle
+
+Choose a helper by the state surface, persistence, restore, and SSR behavior it needs, not only by whether its value should survive a reload.
+
+| Helper                     | Use it when                                                                       | Caller-facing surface                                                     | Persistence and restore                                                                      |
+| -------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `$useStateData(...)`       | The model owns remote or query-style async state and consumers need query status  | Full query wrapper, including `data`, `error`, and readiness/status state | Normal query lifecycle; may participate in query hydration subject to metadata               |
+| `$useStateMem(...)`        | The model owns reusable runtime state without a browser persistence backend       | Assignable state value                                                    | No browser persistence; eligible successful state can transfer through initial SSR hydration |
+| `$useStateLocal(...)`      | The model owns a small browser value that should restore synchronously            | Assignable state value                                                    | Synchronous `localStorage` restore                                                           |
+| `$useStateCookie(...)`     | The state needs cookie persistence or request-aware handling                      | Assignable state value                                                    | Synchronous cookie restore                                                                   |
+| `$useStateLocalAsync(...)` | The model owns longer-lived browser-local state whose restore may be asynchronous | Assignable state value                                                    | Asynchronous `localforage` restore                                                           |
+| `$useStateComputed(...)`   | The model exposes derived state                                                   | Computed value                                                            | No query fetch or persistence                                                                |
+
+### Data, local, and async-local behavior
+
+`$useStateData(...)`, `$useStateLocal(...)`, and `$useStateLocalAsync(...)` use the same model-owned cache foundation, but they are not interchangeable.
+
+| Concern              | `$useStateData(...)`                                      | `$useStateLocal(...)`                                         | `$useStateLocalAsync(...)`                                                                            |
+| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Return surface       | A memoized query wrapper                                  | An assignable state value                                     | An assignable state value                                                                             |
+| Source or storage    | `queryFn`, query cache, and query configuration           | `localStorage`                                                | `localforage`                                                                                         |
+| Initial availability | Follows the query lifecycle                               | Restores synchronously, then falls back to `meta.defaultData` | Restores asynchronously, then falls back to `meta.defaultData`                                        |
+| Intended write flow  | Mutation, cache update, and invalidation policy           | Replace or assign the model field                             | Replace or assign the model field                                                                     |
+| SSR behavior         | Can follow ordinary query dehydration and hydration rules | Browser storage is unavailable on the server                  | Browser storage is unavailable on the server and async-local state explicitly opts out of dehydration |
+
+Use the detailed [`$useStateData` Best Practices](/frontend/use-state-data-best-practices) guide for render-versus-interaction placement, `disableSuspenseOnInit`, freshness utilities, and explicit readiness boundaries.
 
 ### 1. `$useStateData(...)`
 
@@ -155,16 +182,62 @@ The pattern to notice is that the model owns both the mutation and the follow-up
 
 ## 3. `$useStateMem(...)`
 
-Use this when the state should stay only in memory.
+Use this for reusable runtime state that belongs to a Model but does not need a browser persistence backend. It returns an assignable value, rather than a query wrapper, while retaining Model-owned Query Cache identity.
 
 Current-source characteristics:
 
-- no persistence
-- `enabled: false`
+- `enabled: false`, so it does not define a normal remote-fetch lifecycle
 - `staleTime: Infinity`
-- still uses model-owned query cache semantics under the hood
+- `meta.persister: false`, so it does not read or write `localStorage`, cookies, or `localforage`
+- reads from existing Query Cache first, then `meta.defaultData`, then `undefined`
+- assignments update the Query Cache without a persister save
+- automatic key prefixing isolates the state by Model identity and, when enabled, selector identity
+
+This is useful when several consumers or Model methods need the same business state during the current frontend runtime, but the browser should not restore it from storage. For structured values, replace or assign the Model field so its custom-ref setter updates the Query Cache:
+
+```typescript
+this.selectedIds = nextSelectedIds;
+```
 
-This is useful when you want model ownership and query-key identity without local persistence.
+A plain Controller field is usually clearer when the state belongs only to that one Controller. Choose `$useStateLocal(...)`, `$useStateCookie(...)`, or `$useStateLocalAsync(...)` when browser persistence is part of the requirement. Choose `$useStateData(...)` when consumers need query status, errors, freshness, or a remote-fetch lifecycle.
+
+### SSR transfer is not persistence
+
+`meta.persister: false` means no browser persistence backend. It does not, by itself, exclude the state from the initial SSR server-to-client Query Cache handoff.
+
+After server rendering, a successful eligible memory-state query can be dehydrated with the shared Query Cache. During client SSR pre-hydration, the snapshot is hydrated into the client QueryClient. A later `$useStateMem(...)` read can therefore receive the transferred value directly from cache when its effective key matches: the same Model, the same selector when selector mode is enabled, and the same logical `queryKey`.
+
+This transfer has limits:
+
+- it applies only to entries accepted by the normal dehydration policy; `meta.ssr.dehydrate: false` opts a state out
+- it is not a replacement for `localStorage`, cookies, or async-local persistence
+- it does not make the value survive a later browser reload without a new SSR handoff
+- it does not make an empty or unsuccessful cache entry transfer automatically
+
+The router-tabs Model uses memory state for current navigation keys and for tabs when tab caching is disabled. The page-data Model uses memory slots keyed by page path. Read [SSR Init Data](/frontend/ssr-init-data) for the page-side flow, or [A-Model Under the Hood](/frontend/a-model-under-the-hood) for the Query Cache and dehydration mechanics.
+
+### SSR/CSR bridge: `ModelPassport`
+
+`ModelPassport` shows that the state helper selected on the server and the one selected on the client do not have to be the same. Its application initialization creates the same logical state differently by environment:
+
+```typescript
+this.passport = process.env.CLIENT
+  ? this.$useStateLocal({ queryKey: ['passport'] })
+  : this.$useStateMem({ queryKey: ['passport'] });
+```
+
+On the SSR server, authenticated work can assign the current passport to the memory-backed Query Cache entry. If that entry is successful and eligible, it is dehydrated with the server QueryClient. During client SSR pre-hydration, the snapshot restores the entry before the client Model consumes it.
+
+The client then creates a `$useStateLocal(...)` wrapper for the same effective key. Its read order is Query Cache first, then `localStorage`, then `meta.defaultData`. The hydrated server passport therefore wins on the initial client read; synchronous local-storage restoration is a fallback only when the transferred cache entry is absent.
+
+This gives authentication state two complementary properties:
+
+- SSR uses the request-confirmed passport to keep the initial HTML and client hydration consistent.
+- CSR-only entry and later browser sessions can restore the client-local passport value from `localStorage`.
+
+The server `$useStateMem(...)` entry is the entry that is dehydrated. The client `$useStateLocal(...)` call is a new client-side wrapper that reuses hydrated cache because its effective key matches. Matching requires the same Model, the same selector when selector mode is enabled, and the same logical `queryKey`; the short logical key alone is not global identity.
+
+Reading the hydrated value does not save it back to `localStorage`. A later assignment through the client local-state wrapper updates Query Cache and writes the local-storage record. This is an initial SSR cache handoff plus client persistence fallback, not automatic persistence of the SSR snapshot.
 
 ## 4. `$useStateLocal(...)`
 
@@ -195,9 +268,9 @@ Current-source characteristics:
 
 This is particularly relevant for state that must participate in request-aware or SSR-adjacent flows.
 
-## 6. `$useStateDb(...)`
+## 6. `$useStateLocalAsync(...)`
 
-Use this when the model state should persist asynchronously in db-style client storage.
+Use this when the model state should persist asynchronously in browser-local storage backed by `localforage`.
 
 Current-source characteristics:
 
@@ -205,10 +278,40 @@ Current-source characteristics:
 - `enabled: false`
 - `staleTime: Infinity`
 - explicit `ssr.dehydrate = false`
-- getters may need async restore flow before data is available
+- the first unresolved read may need async restore before the state is available
 
 This is useful for larger persisted client state that should outlive a page session without being stored in cookies or plain local storage.
 
+### Initialize and ensure async-local state
+
+Assign the state property before awaiting it. When later initialization depends on the restored value, establish an explicit restore boundary with `$ensureStateLocalAsync(...)`. It waits for the pending initial restore to settle; it does not force another load and does not guarantee a defined result:
+
+```typescript
+protected async __init__() {
+  this.tabs = this.$useStateLocalAsync({
+    queryKey: ['tabs'],
+    meta: {
+      defaultData: [],
+    },
+  });
+
+  await this.$ensureStateLocalAsync(this.tabs);
+
+  // Continue only after persisted tabs, or the fallback default, is available.
+  this.initializeTabs();
+}
+```
+
+`meta.defaultData` is a fallback: it initializes the state only when no persisted value is restored. If neither provides a value, the ensured result can still be `undefined`. The router-tabs model follows this assign-then-ensure sequence before it continues with route initialization.
+
+Persisted local and async-local state should be updated by replacing or assigning the model field so its custom-ref setter can update query state and persist the new value:
+
+```typescript
+this.tabs = nextTabs;
+```
+
+Do not rely on an in-place nested mutation alone to persist the change. Assigning `undefined` removes the persisted value.
+
 ## 7. `$useStateComputed(...)`
 
 Use this when the model should expose derived state that is still model-key-oriented but computed locally.
@@ -252,16 +355,17 @@ Model state choices can affect SSR behavior.
 
 Current-source behaviors to remember:
 
-- query state can be dehydrated on server and hydrated on client
+- successful eligible Query Cache state can be dehydrated on the server and hydrated on the client
+- `$useStateMem(...)` has no browser persister but can participate in that initial SSR handoff unless excluded by metadata
 - mutations are not dehydrated
-- `db` state is explicitly not dehydrated
-- server cannot use local-storage or db persistence backends
-- cookie state is special because cookie access can still exist through the app cookie surface
+- `$useStateLocalAsync(...)` explicitly opts out of dehydration
+- server-side sync local and cookie persister-backed Query Cache entries are excluded by the default dehydration policy; this does not prevent a client `$useStateLocal(...)` or `$useStateCookie(...)` wrapper from reusing a hydrated entry that the server created with a different eligible helper
+- server cannot use local-storage or async-local persistence backends; cookie state is special because cookie access can still exist through the app cookie surface
 
 Practical implication:
 
-- do not assume every persisted model state behaves the same during SSR
-- choose `mem`, `local`, `cookie`, `db`, or `data` based on ownership and hydration requirements, not only convenience
+- do not equate browser persistence with SSR transfer, or assume every state family behaves the same during SSR
+- choose `mem`, `local`, `cookie`, `localAsync`, or `data` based on ownership, persistence, and hydration requirements, not only convenience
 
 ## Real examples to read
 
@@ -289,7 +393,7 @@ This file shows:
 
 - `@Model({ enableSelector: true, ... })`
 - richer model initialization in `__init__`
-- mixed use of `$useStateMem(...)` and `$useStateDb(...)`
+- mixed use of `$useStateMem(...)` and `$useStateLocalAsync(...)`
 - model-owned tab state with cache and persistence decisions
 
 ### SSR-sensitive auth model

package/cabloy-docs/frontend/ssr-init-data.md

@@ -31,7 +31,18 @@ export class ControllerPageTodo {
 1. a model bean encapsulates the data access path
 2. the controller injects the model
 3. `__init__` prepares the data on the server
-4. model-based SSR support synchronizes that data to the client and completes hydration automatically
+4. successful eligible Query Cache state is captured in the SSR handoff
+5. client SSR pre-hydration restores that cache before the client model consumes it
+
+## What hydration reuses
+
+The initial SSR handoff reuses model Query Cache data, not only `$useStateData(...)` results. A successful eligible `$useStateMem(...)` value can also transfer from the server to the initial client runtime even though it has no browser persistence backend.
+
+Client reuse requires the model call to resolve to the same effective query key: Zova prefixes the logical key with Model identity and, for selector-enabled models, selector identity. State marked with `meta.ssr.dehydrate: false` is excluded. This handoff does not make memory state durable across a later browser reload, and it does not guarantee that every client query avoids fetching.
+
+`ModelPassport` is a concrete SSR/CSR bridge: the server creates `passport` with `$useStateMem({ queryKey: ['passport'] })`, while the client creates `$useStateLocal({ queryKey: ['passport'] })`. The successful eligible server memory entry is what SSR transfers. Because the client local-state wrapper reads Query Cache before `localStorage`, the hydrated passport supplies the initial client value when the effective key matches. If no transferred entry exists, `$useStateLocal(...)` can instead restore its browser-local value. Hydration alone does not save the transferred value to `localStorage`; later client-side assignments do.
+
+For helper selection and the complete passport flow, read [Model State Guide](/frontend/model-state-guide). For the dehydration filter and QueryClient lifecycle, read [A-Model Under the Hood](/frontend/a-model-under-the-hood).
 
 ## Implementation checks for SSR data-loading changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.103",
+  "version": "5.1.104",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/vona/pnpm-lock.yaml

@@ -501,8 +501,8 @@ importers:
         specifier: npm:@cabloy/zod@4.3.8
         version: '@cabloy/zod@4.3.8'
       zova:
-        specifier: ^5.1.132
-        version: 5.1.132(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
+        specifier: ^5.1.133
+        version: 5.1.133(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
       zova-jsx:
         specifier: ^1.1.77
         version: 1.1.77(typescript@5.9.3)
@@ -528,8 +528,8 @@ importers:
         specifier: ^5.1.29
         version: 5.1.29
       zova-module-a-model:
-        specifier: ^5.1.31
-        version: 5.1.31(vue@3.5.39(typescript@5.9.3))
+        specifier: ^5.1.32
+        version: 5.1.32(vue@3.5.39(typescript@5.9.3))
       zova-module-a-openapi:
         specifier: ^5.1.43
         version: 5.1.43
@@ -573,8 +573,8 @@ importers:
         specifier: npm:@cabloy/zod@4.3.8
         version: '@cabloy/zod@4.3.8'
       zova:
-        specifier: ^5.1.132
-        version: 5.1.132(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
+        specifier: ^5.1.133
+        version: 5.1.133(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
       zova-jsx:
         specifier: ^1.1.77
         version: 1.1.77(typescript@5.9.3)
@@ -600,8 +600,8 @@ importers:
         specifier: ^5.1.29
         version: 5.1.29
       zova-module-a-model:
-        specifier: ^5.1.31
-        version: 5.1.31(vue@3.5.39(typescript@5.9.3))
+        specifier: ^5.1.32
+        version: 5.1.32(vue@3.5.39(typescript@5.9.3))
       zova-module-a-openapi:
         specifier: ^5.1.43
         version: 5.1.43
@@ -1517,13 +1517,13 @@ importers:
   src/suite-vendor/a-file:
     dependencies:
       vona-module-a-file:
-        specifier: ^5.0.4
+        specifier: ^5.0.5
         version: link:modules/a-file
       vona-module-file-cloudflare:
-        specifier: ^5.0.3
+        specifier: ^5.0.4
         version: link:modules/file-cloudflare
       vona-module-file-native:
-        specifier: ^5.0.3
+        specifier: ^5.0.4
         version: link:modules/file-native
 
   src/suite-vendor/a-file/modules/a-file:
@@ -1625,7 +1625,7 @@ importers:
   src/suite-vendor/a-test:
     dependencies:
       vona-module-test-file:
-        specifier: ^5.0.4
+        specifier: ^5.0.5
         version: link:modules/test-file
 
   src/suite-vendor/a-test/modules/test-auth:
@@ -7993,8 +7993,8 @@ packages:
   zova-module-a-meta@5.1.21:
     resolution: {integrity: sha512-7vsLOMw1UQEZ+8qbBaiz9t4n3N7AU1jxpaiSIIky7hBvKO9nuHq+e7FONpj9poa8WeHkYoflBg/8imKBy/IlNw==}
 
-  zova-module-a-model@5.1.31:
-    resolution: {integrity: sha512-/6MV5xSklEkain5t0vsZ37ImyIihutCu7ymytq5RFG0QbeKtbSAI/IB6TS2mfkjLkiy97SmDJbuiLGso7Cg/Gw==}
+  zova-module-a-model@5.1.32:
+    resolution: {integrity: sha512-uzOXp2JlIOaBFy4pe5HyM846A2IK3zA2J8y8Je0i4EvioM36eiBhE61F8q0K59ojh3QZuinrxH6m9DIVL2EvVw==}
 
   zova-module-a-openapi@5.1.43:
     resolution: {integrity: sha512-xJKvSPl1AZnH7EpgEd9a3u3IEpJfnou19DKre/7TL1KdiTdfNThLrmmkdP1UNYlUHUgCczcGUwZDdMiE9gdxwA==}
@@ -8032,11 +8032,11 @@ packages:
   zova-module-rest-resource@5.1.41:
     resolution: {integrity: sha512-7Y8rLmHdw0pynlWqsyHPWuCWFLwr/0HsNvfef64cPw91LRujf/7OlulVWqH8ZoFNioZZUpfumB+t/+mICoYfFg==}
 
-  zova-suite-a-zova@5.1.131:
-    resolution: {integrity: sha512-NRPt3ahLwHg+rLuA2VXRbEmrg/bTdgwdQmU9C8nj9R0+E1f0ehbbsUWJFQFN6hJNco5+rDDSDfBlvejf4z6L1w==}
+  zova-suite-a-zova@5.1.132:
+    resolution: {integrity: sha512-bHyim0stshLyjEvehW8cUL0Bf/pR/sU43Dpada2g2ieGH1p34EzyLeaWimhId++sO9H3xErVX6aQXe0Xf6pELA==}
 
-  zova@5.1.132:
-    resolution: {integrity: sha512-lQK1VRnwthDx0qayS7kdElyfAmvPEhlt6sk/2jK5mTbqojsjuDNkrEa9Ck2Q78fag800U6pDwV83o6CRbSUTeA==}
+  zova@5.1.133:
+    resolution: {integrity: sha512-1tM0u0EU69/RvXmlxhVIrEY4ADVhQsEIr8UAcQ1U+Mjm3QwLJ7y7fDAQWsW7ChjEXHGrCU62fdc0tPvJ5CGntg==}
 
   zwitch@1.0.5:
     resolution: {integrity: sha512-V50KMwwzqJV0NpZIZFwfOD5/lyny3WlSzRiXgA0G7VUnRlqttta1L6UQIHzd6EuBY/cHGfwTIck7w1yH6Q5zUw==}
@@ -13935,7 +13935,7 @@ snapshots:
 
   zova-module-a-meta@5.1.21: {}
 
-  zova-module-a-model@5.1.31(vue@3.5.39(typescript@5.9.3)):
+  zova-module-a-model@5.1.32(vue@3.5.39(typescript@5.9.3)):
     dependencies:
       '@tanstack/query-core': 5.101.2
       '@tanstack/query-persist-client-core': 5.101.2
@@ -14010,7 +14010,7 @@ snapshots:
 
   zova-module-rest-resource@5.1.41: {}
 
-  zova-suite-a-zova@5.1.131(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3)):
+  zova-suite-a-zova@5.1.132(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3)):
     dependencies:
       zova-module-a-api: 5.1.21
       zova-module-a-app: 5.1.24
@@ -14025,7 +14025,7 @@ snapshots:
       zova-module-a-interceptor: 5.1.29
       zova-module-a-logger: 5.1.26
       zova-module-a-meta: 5.1.21
-      zova-module-a-model: 5.1.31(vue@3.5.39(typescript@5.9.3))
+      zova-module-a-model: 5.1.32(vue@3.5.39(typescript@5.9.3))
       zova-module-a-openapi: 5.1.43
       zova-module-a-router: 5.1.29
       zova-module-a-routerstack: 5.1.26
@@ -14044,10 +14044,10 @@ snapshots:
       - typescript
       - vue
 
-  zova@5.1.132(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3)):
+  zova@5.1.133(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3)):
     dependencies:
       zova-core: 5.1.77(patch_hash=0f4164c4d2bbb16d671beb5c26759dff37769be0709df941bc7b90b94261ac54)(typescript@5.9.3)
-      zova-suite-a-zova: 5.1.131(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
+      zova-suite-a-zova: 5.1.132(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
     transitivePeerDependencies:
       - '@vue/composition-api'
       - debug

package/vona/src/suite/a-home/modules/home-user/src/controller/passport.ts

@@ -111,6 +111,13 @@ export class ControllerPassport extends BeanBase {
     return this._combineDtoPassportJwt(jwt);
   }
 
+  @Web.post('refreshAuthToken')
+  @Passport.public()
+  @Api.body(v.object(DtoJwtToken))
+  async refreshAuthToken(@Arg.body('refreshToken') refreshToken: string): Promise<DtoJwtToken> {
+    return await this.bean.passport.refreshAuthToken(refreshToken);
+  }
+
   @Web.post('createPassportJwtFromOauthCode')
   @Passport.public()
   @Api.body(v.object(DtoPassportJwt))
@@ -119,13 +126,6 @@ export class ControllerPassport extends BeanBase {
     return this._combineDtoPassportJwt(jwt);
   }
 
-  @Web.post('refreshAuthToken')
-  @Passport.public()
-  @Api.body(v.object(DtoJwtToken))
-  async refreshAuthToken(@Arg.body('refreshToken') refreshToken: string): Promise<DtoJwtToken> {
-    return await this.bean.passport.refreshAuthToken(refreshToken);
-  }
-
   @Web.post('createTempAuthToken')
   @Api.body(z.string())
   async createTempAuthToken(@Arg.query('path', v.optional()) path?: string): Promise<string> {

package/zova/packages-zova/zova/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova",
-  "version": "5.1.133",
+  "version": "5.1.134",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A vue3 framework with ioc",
   "keywords": [
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "zova-core": "^5.1.77",
-    "zova-suite-a-zova": "^5.1.132"
+    "zova-suite-a-zova": "^5.1.133"
   },
   "devDependencies": {
     "clean-package": "^2.2.0",

package/zova/src/suite/a-home/modules/home-passport/src/model/passport.ts

@@ -28,7 +28,9 @@ export class ModelPassport extends BeanModelBase {
   expireTime?: number;
   schemaLogin?: SchemaObject;
 
-  protected async __init__() {
+  protected async __init__() {}
+
+  async appInitialize() {
     this.schemaLogin = this.$computed(() => {
       return this.apiSchemasLogin.requestBody;
     });
@@ -167,6 +169,10 @@ export class ModelPassport extends BeanModelBase {
     return this.passport?.roles;
   }
 
+  get isAdmin() {
+    return !!this.passport?.roles.some(item => item.name === 'admin');
+  }
+
   async getJwtInfo(): Promise<IJwtInfo | undefined> {
     if (!this.accessToken) return undefined;
     return {

package/zova/src/suite/a-home/modules/home-passport/src/monkey.ts

@@ -1,11 +1,20 @@
 import type { IModule } from '@cabloy/module-info';
-import type { BeanBase, BeanContainer, IMonkeyBeanInit, IMonkeyModule } from 'zova';
+import type {
+  BeanBase,
+  BeanContainer,
+  IMonkeyAppInitialize,
+  IMonkeyBeanInit,
+  IMonkeyModule,
+} from 'zova';
 
 import { BeanSimple } from 'zova';
 
 import type { ModelPassport } from './model/passport.js';
 
-export class Monkey extends BeanSimple implements IMonkeyModule, IMonkeyBeanInit {
+export class Monkey
+  extends BeanSimple
+  implements IMonkeyAppInitialize, IMonkeyModule, IMonkeyBeanInit
+{
   private _moduleSelf: IModule;
   private $$modelPassport: ModelPassport;
 
@@ -14,13 +23,18 @@ export class Monkey extends BeanSimple implements IMonkeyModule, IMonkeyBeanInit
     this._moduleSelf = moduleSelf;
   }
 
-  async getModelPassport() {
+  private async getModelPassport() {
     if (!this.$$modelPassport) {
       this.$$modelPassport = await this.bean._getBean('home-passport.model.passport', true);
     }
     return this.$$modelPassport;
   }
 
+  async appInitialize() {
+    const modelPassport = await this.getModelPassport();
+    await modelPassport.appInitialize();
+  }
+
   async moduleLoading(_module: IModule) {}
   async moduleLoaded(module: IModule) {
     // self

package/zova/src/suite-vendor/a-zova/modules/a-model/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-model",
-  "version": "5.1.32",
+  "version": "5.1.33",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "core",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useState.ts

@@ -28,11 +28,11 @@ export class BeanModelUseState extends BeanModelUseQuery {
   private [SymbolUseQueries]: Record<string, unknown> = {};
   private [SymbolUseComputeds]: Record<string, unknown> = {};
 
-  async $loadStateDb<T>(dbData: T): Promise<T> {
-    return await dbData;
+  async $ensureStateLocalAsync<T>(state: T): Promise<T> {
+    return await state;
   }
 
-  $useStateDb<
+  $useStateLocalAsync<
     TQueryFnData = unknown,
     TError = DefaultError,
     TData = TQueryFnData,
@@ -41,7 +41,7 @@ export class BeanModelUseState extends BeanModelUseQuery {
     options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     queryClient?: QueryClient,
   ): TData;
-  $useStateDb<
+  $useStateLocalAsync<
     TQueryFnData = unknown,
     TError = DefaultError,
     TData = TQueryFnData,
@@ -50,7 +50,7 @@ export class BeanModelUseState extends BeanModelUseQuery {
     options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     queryClient?: QueryClient,
   ): TData;
-  $useStateDb<
+  $useStateLocalAsync<
     TQueryFnData = unknown,
     TError = DefaultError,
     TData = TQueryFnData,
@@ -59,7 +59,7 @@ export class BeanModelUseState extends BeanModelUseQuery {
     options: UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
     queryClient?: QueryClient,
   ): TData;
-  $useStateDb(options, queryClient) {
+  $useStateLocalAsync(options, queryClient) {
     options = deepExtend(
       {
         meta: {

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useStateGeneral.ts

@@ -23,7 +23,7 @@ export class BeanModelUseStateGeneral extends BeanModelUseState {
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
-    stateType: 'db' | 'local' | 'cookie' | 'mem',
+    stateType: 'localAsync' | 'local' | 'cookie' | 'mem',
     options: UndefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     queryClient?: QueryClient,
   ): TData;
@@ -33,7 +33,7 @@ export class BeanModelUseStateGeneral extends BeanModelUseState {
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
-    stateType: 'db' | 'local' | 'cookie' | 'mem',
+    stateType: 'localAsync' | 'local' | 'cookie' | 'mem',
     options: DefinedInitialQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     queryClient?: QueryClient,
   ): TData;
@@ -43,7 +43,7 @@ export class BeanModelUseStateGeneral extends BeanModelUseState {
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
-    stateType: 'db' | 'local' | 'cookie' | 'mem',
+    stateType: 'localAsync' | 'local' | 'cookie' | 'mem',
     options: UseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
     queryClient?: QueryClient,
   ): TData;
@@ -79,8 +79,8 @@ export class BeanModelUseStateGeneral extends BeanModelUseState {
   ): UnwrapNestedRefs<UseQueryReturnType<TData, TError>>;
   $useState(stateType: StateType, options, queryClient) {
     switch (stateType) {
-      case 'db':
-        return this.$useStateDb(options, queryClient);
+      case 'localAsync':
+        return this.$useStateLocalAsync(options, queryClient);
       case 'local':
         return this.$useStateLocal(options, queryClient);
       case 'cookie':

package/zova/src/suite-vendor/a-zova/modules/a-model/src/monkey.ts

@@ -1,5 +1,11 @@
 import type { IModule } from '@cabloy/module-info';
-import type { BeanBase, BeanContainer, IMonkeyAppInitialize, IMonkeyBeanInit } from 'zova';
+import type {
+  BeanBase,
+  BeanContainer,
+  IMonkeyAppInitialize,
+  IMonkeyBeanInit,
+  IMonkeyModule,
+} from 'zova';
 
 import { useQueryClient } from '@tanstack/vue-query';
 import { markRaw } from 'vue';
@@ -7,7 +13,10 @@ import { BeanSimple } from 'zova';
 
 import { ServiceStorage } from './service/storage.js';
 
-export class Monkey extends BeanSimple implements IMonkeyAppInitialize, IMonkeyBeanInit {
+export class Monkey
+  extends BeanSimple
+  implements IMonkeyAppInitialize, IMonkeyModule, IMonkeyBeanInit
+{
   private _moduleSelf: IModule;
   private _storage: ServiceStorage;
 

package/zova/src/suite-vendor/a-zova/modules/a-model/src/types/query.ts

@@ -63,7 +63,7 @@ export type QueryMetaPersisterCookieType =
   | 'string'
   | undefined;
 
-export type StateType = 'db' | 'local' | 'cookie' | 'mem' | 'data';
+export type StateType = 'localAsync' | 'local' | 'cookie' | 'mem' | 'data';
 
 export type StaleTime = number;
 export type StaleTimeFunction<

package/zova/src/suite-vendor/a-zova/modules/a-routertabs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-routertabs",
-  "version": "5.1.32",
+  "version": "5.1.33",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "routertabs",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-routertabs/src/model/tabs.ts

@@ -63,7 +63,7 @@ export class ModelTabs extends BeanModelBase {
     };
     this.tabKeyCurrent = this.$useStateMem(queryOptionsTabKeyCurrent);
     // if (this.tabsOptions.cache) {
-    //   this.tabKeyCurrent = this.$useStateDb(queryOptionsTabKeyCurrent);
+    //   this.tabKeyCurrent = this.$useStateLocalAsync(queryOptionsTabKeyCurrent);
     // } else {
     //   this.tabKeyCurrent = this.$useStateMem(queryOptionsTabKeyCurrent);
     // }
@@ -75,14 +75,14 @@ export class ModelTabs extends BeanModelBase {
       },
     };
     if (this.tabsOptions.cache) {
-      this.tabs = this.$useStateDb(queryOptionsTabs);
+      this.tabs = this.$useStateLocalAsync(queryOptionsTabs);
     } else {
       this.tabs = this.$useStateMem(queryOptionsTabs);
     }
     // load cache
     if (this.tabsOptions.cache) {
-      // await this.$loadStateDb(this.tabKeyCurrent);
-      await this.$loadStateDb(this.tabs);
+      // await this.$ensureStateLocalAsync(this.tabKeyCurrent);
+      await this.$ensureStateLocalAsync(this.tabs);
     }
     // reset pageDirty
     this._resetAllPageDirty();

package/zova/src/suite-vendor/a-zova/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-suite-a-zova",
-  "version": "5.1.132",
+  "version": "5.1.133",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "zova",
   "license": "MIT",
@@ -21,11 +21,11 @@
     "zova-module-a-interceptor": "^5.1.29",
     "zova-module-a-logger": "^5.1.26",
     "zova-module-a-meta": "^5.1.21",
-    "zova-module-a-model": "^5.1.32",
+    "zova-module-a-model": "^5.1.33",
     "zova-module-a-openapi": "^5.1.43",
     "zova-module-a-router": "^5.1.29",
     "zova-module-a-routerstack": "^5.1.26",
-    "zova-module-a-routertabs": "^5.1.32",
+    "zova-module-a-routertabs": "^5.1.33",
     "zova-module-a-ssr": "^5.1.29",
     "zova-module-a-ssrhmr": "^5.1.22",
     "zova-module-a-ssrserver": "^5.1.22",