cabloy 5.1.60 → 5.1.61

package/cabloy-docs/frontend/foundation.md

@@ -46,6 +46,35 @@ The highest-value Zova capabilities to preserve in the unified docs are:
 
 For the deeper architectural concepts behind IoC, module boundaries, and scope-based resources, see [IoC and Beans](/frontend/ioc-and-beans), [Modules and Suites](/frontend/modules-and-suites), and [Module Scope](/frontend/module-scope). For the runtime-variant and startup model, see [Environment and Config Guide](/frontend/environment-config-guide), [App Startup Guide](/frontend/app-startup-guide), and [System Startup Guide](/frontend/system-startup-guide).
 
+## Recommended reading path for architectural source reading
+
+If you want a compact path from public architecture to source-level understanding, use this order:
+
+1. [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+2. [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison)
+3. [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
+4. [Zova Source Reading Map](/frontend/zova-source-reading-map)
+5. [IoC and Beans](/frontend/ioc-and-beans)
+6. [Page Guide](/frontend/page-guide)
+7. [Component Guide](/frontend/component-guide)
+8. [Model Architecture](/frontend/model-architecture)
+9. [Model State Guide](/frontend/model-state-guide)
+10. [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+11. [Using ModelResource in Your Module](/frontend/model-resource-usage-guide)
+12. [Resource Model Best Practices](/frontend/model-resource-best-practices)
+13. [Resource Model Cookbook](/frontend/model-resource-cookbook)
+
+Use this order when you want to understand both the public mental model and the shortest source-reading routes without collapsing Zova back into generic Vue habits.
+
+If your main goal is resource-oriented frontend design, the model-focused subpath is:
+
+1. [Model Architecture](/frontend/model-architecture)
+2. [Model State Guide](/frontend/model-state-guide)
+3. [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+4. [Using ModelResource in Your Module](/frontend/model-resource-usage-guide)
+5. [Resource Model Best Practices](/frontend/model-resource-best-practices)
+6. [Resource Model Cookbook](/frontend/model-resource-cookbook)
+
 ## Why this matters for AI development
 
 AI systems should not treat Zova as generic Vue with a few utilities.

package/cabloy-docs/frontend/introduction.md

@@ -32,6 +32,10 @@ Start here when you need the shortest route to the frontend mental model and sta
 
 - [Quickstart](/frontend/quickstart)
 - [Foundation](/frontend/foundation)
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison)
+- [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
 - [IoC and Beans](/frontend/ioc-and-beans)
 - [Behavior Guide](/frontend/behavior-guide)
 - [Modules and Suites](/frontend/modules-and-suites)
@@ -56,9 +60,12 @@ Use this path when the task is page-oriented, route-oriented, or the first time
 
 ### Components and UI flow
 
-Use this path when the task is about UI composition, component contracts, or theme work:
+Use this path when the task is about UI composition, component contracts, form architecture, form internals, form source reading, or theme work:
 
 - [Component Guide](/frontend/component-guide)
+- [Form Guide](/frontend/form-guide)
+- [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
+- [Zova Form Source Reading Map](/frontend/zova-form-source-reading-map)
 - [Component Props Guide](/frontend/component-props-guide)
 - [Component v-model Guide](/frontend/component-v-model-guide)
 - [Generic Component Guide](/frontend/generic-component-guide)
@@ -74,6 +81,10 @@ Use this path when the task is about data loading, API contracts, generated SDKs
 - [API Guide](/frontend/api-guide)
 - [Model Architecture](/frontend/model-architecture)
 - [Model State Guide](/frontend/model-state-guide)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- [Using ModelResource in Your Module](/frontend/model-resource-usage-guide)
+- [Resource Model Best Practices](/frontend/model-resource-best-practices)
+- [Resource Model Cookbook](/frontend/model-resource-cookbook)
 - [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
 - [API Schema Guide](/frontend/api-schema-guide)
 - [SDK Guide](/frontend/sdk-guide)

package/cabloy-docs/frontend/ioc-and-beans.md

@@ -200,6 +200,12 @@ Read this together with:
 
 Those pages explain how beans fit into module boundaries, scope-based resources, the existing Behavior scene, and the broader Zova architectural model.
 
+If you want a Vue-to-Zova reading bridge or a deeper runtime/source explanation, also read:
+
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
+
 ## Implementation checks for frontend bean-architecture changes
 
 When editing Zova frontend code, ask:

package/cabloy-docs/frontend/mock-guide.md

@@ -56,6 +56,7 @@ Mocking fits naturally with:
 
 - [API Guide](/frontend/api-guide)
 - [Server Data](/frontend/server-data)
+- [Fetch Interceptor Guide](/frontend/fetch-interceptor-guide)
 - [Page Guide](/frontend/page-guide)
 
 A common workflow is:

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

@@ -1,78 +1,282 @@
 # Model Architecture
 
-This guide explains the overall model architecture in Zova within the Cabloy monorepo.
+This guide explains the architecture of Zova Model in the Cabloy monorepo.
+
+It focuses on the Zova-native role of Model first, then connects that role to the current `a-model` source implementation.
 
 ## Why Zova models matter
 
-Zova uses a unified `Model` mechanism to manage several kinds of data that other frontend stacks often split across unrelated tools.
+Zova uses a unified `Model` mechanism to manage several kinds of frontend state that other stacks often split across unrelated tools.
 
 This is one of the most important architectural ideas in Zova.
 
-## Four kinds of global state
+The key point is not only caching remote data.
+
+The deeper point is that Zova gives state a dedicated bean-oriented home with:
+
+- framework-managed identity
+- query-key namespacing
+- persistence options
+- SSR-aware hydration behavior
+- reuse across pages, components, and services
+
+## Zova-native role of a model
+
+A Zova model is a **model bean**.
 
-The model architecture can be understood through four common data categories:
+It is not only a generic Vue composable and it is not only a thin request wrapper.
 
-- asynchronous data, usually from the server
-- local storage data
-- cookie data
-- in-memory data
+Its architectural job is to own data that benefits from broader lifecycle and reuse behavior, especially when that data is:
 
-In Zova, these can all participate in one broader model-centered system instead of forcing developers to switch between unrelated mental models.
+- asynchronous server data
+- local-storage data
+- cookie-backed data
+- in-memory cache-oriented data
+- persistence-aware state that should survive page transitions or refreshes
+
+In practice, a model often sits above `$api` and below page rendering:
+
+- `$fetch` handles transport-oriented access
+- `$api` handles business-oriented service methods
+- `Model` handles cached, reusable, UI-friendly state ownership
+
+Read together with [Server Data](/frontend/server-data) when deciding which abstraction layer a feature should use.
 
 ## Relationship to TanStack Query
 
-One key point is explicit: the base of Zova Model is TanStack Query.
+One current-source fact is explicit: Zova Model is built on top of TanStack Query.
 
-That matters because Zova is not discarding the strengths of TanStack Query. It is building a more unified and framework-friendly usage model on top of it.
+That matters because Zova is not replacing TanStack Query with a separate state engine.
 
-## Key model capabilities
+Instead, Zova wraps TanStack Query inside a model-bean architecture so that:
 
-Several important capabilities remain central in the unified docs:
+- query and mutation APIs fit naturally into the bean system
+- sync and async state categories can use one broader model surface
+- persistence and SSR behavior are expressed in one place
+- model identity becomes part of cache identity
 
-### 1. Support for async and sync data
+## Public authoring surface
 
-The model system is not limited to server data. It also extends the same broader mechanism to synchronous data categories.
+Representative model definition:
+
+```typescript
+import { Model } from 'zova';
+import { BeanModelBase } from 'zova-module-a-model';
 
-### 2. Automatic caching
+@Model()
+export class ModelTodo extends BeanModelBase {}
+```
 
-Remote data can be cached locally, while local-storage or cookie-backed data can be accessed through unified model patterns.
+At source level, `@Model()` is a bean decorator factory:
 
-### 3. Automatic update behavior
+- `zova/src/suite-vendor/a-zova/modules/a-model/src/lib/model.ts`
 
-The model system supports data freshness and update behavior instead of treating state as static snapshots.
+That file shows that a model is registered on the `model` onion/scene rather than being a special-case standalone mechanism.
 
-### 4. Reduced duplicate requests
+## The core architectural idea
 
-When multiple parts of the app need the same data, the framework avoids unnecessary repeated requests.
+The most important current-source insight is this:
 
-### 5. Memory optimization
+> Zova unifies remote state and several local state categories around query-cache semantics, then exposes that system through model beans.
 
-Model-managed data does not need to occupy memory forever. Cache lifecycle and release behavior matter, especially for large long-running applications.
+That is why model APIs look broader than a normal “data fetching helper”.
 
-### 6. Persistence
+Even local, cookie, db, and mem state are expressed through model helpers that still participate in model-owned keying, restore, invalidation, and SSR rules.
 
-Model-managed data can participate in persistence strategies so refreshes do not always mean starting from nothing.
+## Five state families in the current model layer
 
-### 7. SSR support
+The `a-model` source exposes five main state families through `BeanModelBase` helpers:
 
-The model system helps smooth out SSR differences across data categories and makes hydration more natural.
+- `data` → remote/query-style state through `$useStateData(...)`
+- `mem` → in-memory state through `$useStateMem(...)`
+- `local` → local-storage state through `$useStateLocal(...)`
+- `cookie` → cookie-backed state through `$useStateCookie(...)`
+- `db` → async persisted state through `$useStateDb(...)`
 
-### 8. Namespace isolation
+This is why Zova Model is better understood as a **unified model-state layer** rather than only a remote-data wrapper.
 
-Because data is managed through model beans, the bean identity itself helps provide namespace isolation and reduces collision risk.
+## How the runtime is assembled
 
-## Create a model bean
+A compact source-confirmed runtime path is:
 
-Representative pattern:
+1. `@Model()` registers the class as a model bean
+2. the `a-model` module monkey bootstraps a shared `QueryClient`
+3. the monkey injects `$queryClient` onto bean instances
+4. `BeanModelBase` composes query, mutation, state, and persistence helpers
+5. helper calls automatically prefix query keys with model identity
+6. persistence and SSR behavior are applied from model metadata and module config
 
-```typescript
-import { Model } from 'zova';
-import { BeanModelBase } from 'zova-module-a-model';
+### 1. `@Model()` registers a model bean
 
-@Model()
-export class ModelTodo extends BeanModelBase {}
+Source:
+
+- `zova/src/suite-vendor/a-zova/modules/a-model/src/lib/model.ts`
+- `zova/src/suite-vendor/a-zova/modules/a-model/src/types/model.ts`
+
+These files confirm that:
+
+- models are bean-based
+- the scene/onion name is `model`
+- model decorator options currently include `enableSelector?: boolean`
+
+### 2. The module bootstraps a shared query client
+
+Source:
+
+- `zova/src/suite-vendor/a-zova/modules/a-model/src/monkey.ts`
+- `zova/src/suite-vendor/a-zova/modules/a-model/src/service/storage.ts`
+
+These files show that the module:
+
+- creates a `QueryClient`
+- installs `VueQueryPlugin`
+- injects `$queryClient` onto bean instances
+- owns SSR dehydrate/hydrate behavior for query state
+
+This is important because model code does not manually construct its own query client.
+
+## `BeanModelBase` is a composed capability stack
+
+`BeanModelBase` is a reusable base, not just an empty convenience class.
+
+Representative source path:
+
+- `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.modelBase.ts`
+- `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/`
+
+The current source composes a layered model base that provides:
+
+- query helpers
+- mutation helpers
+- state helpers
+- persistence helpers
+- cookie/local/db adapters
+- selector-aware key prefixing
+
+For source reading, the most important files are:
+
+- `bean.model.useQuery.ts`
+- `bean.model.useMutation.ts`
+- `bean.model.useState.ts`
+- `bean.model.query.ts`
+- `bean.model.persister.ts`
+
+## Automatic namespacing and selector-aware identity
+
+One of the most important source-level behaviors is automatic key prefixing.
+
+Model helpers do not only use the caller-provided `queryKey`.
+
+They first prefix it with the model bean identity, and when `enableSelector` is enabled they also prefix it with the selector value.
+
+That means a logical user key such as:
+
+```typescript
+['list']
 ```
 
+becomes model-owned cache identity rather than a globally ambiguous key.
+
+This is one reason model state can scale more safely across larger apps.
+
+## Persistence architecture
+
+The current model layer supports several persistence strategies:
+
+- `mem` → no persistence
+- `local` → sync local storage
+- `cookie` → sync cookie storage
+- `db` → async persisted storage through `localforage`
+
+Representative source files:
+
+- `bean.model.useState.ts`
+- `bean.model.persister.ts`
+- `bean.model.local.ts`
+- `bean.model.cookie.ts`
+- `common/cookieWrapper.ts`
+
+A key design detail is that persistence is treated as an extension of model-owned query state rather than as a separate unrelated subsystem.
+
+## SSR behavior
+
+Zova Model is SSR-aware.
+
+Important current-source behavior includes:
+
+- server render dehydrates query state into SSR deferred state
+- client pre-hydration hydrates that query state back into the client query client
+- mutations are not dehydrated
+- sync persisted state such as `local` and `cookie` is not treated the same way as dehydrated async query state
+- `db` state is explicitly marked not to dehydrate
+
+Representative source files:
+
+- `service/storage.ts`
+- `config/config.ts`
+- `types/query.ts`
+- `bean.model.useQuery.ts`
+- `bean.model.useState.ts`
+
+This matters because a model choice can affect hydration behavior, not only local developer ergonomics.
+
+## When state should live in a model
+
+A model is usually a good fit when one or more of these are true:
+
+- multiple pages or components need the same data
+- remote data should be cached and invalidated consistently
+- the state has persistence value across route changes or reloads
+- SSR and hydration behavior matter
+- the data should have a dedicated owner separate from one page controller
+
+A model is often **not** the first choice when:
+
+- the state is purely page-local and short-lived
+- the data has no reuse value outside one controller
+- plain controller fields already express the intent clearly
+
+That is why Zova asks a different first question than many Vue stacks.
+
+Instead of asking only “should this be a store?”, it is often better to ask:
+
+1. which bean should own this data?
+2. does the data need model-level caching or persistence?
+3. does SSR or reuse make a model the right boundary?
+
+## Source-reading path for Model
+
+If you want the shortest accurate path from public docs into current source, use this order:
+
+1. this page
+2. [Model State Guide](/frontend/model-state-guide)
+3. [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+4. [Zova Source Reading Map](/frontend/zova-source-reading-map)
+5. `zova/src/suite/a-demo/modules/demo-todo/src/model/todo.ts`
+6. `zova/src/suite-vendor/a-zova/modules/a-model/src/lib/model.ts`
+7. `zova/src/suite-vendor/a-zova/modules/a-model/src/monkey.ts`
+8. `zova/src/suite-vendor/a-zova/modules/a-model/src/service/storage.ts`
+9. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useState.ts`
+10. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.persister.ts`
+
+Use representative real models next when you want a richer case:
+
+- `zova/src/suite-vendor/a-zova/modules/a-routertabs/src/model/tabs.ts`
+- `zova/src/suite/a-home/modules/home-passport/src/model/passport.ts`
+- `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts`
+
+The `rest-resource` model is especially important because it shows that Zova Model is not only for small feature-local caching.
+
+It also supports **generic infrastructure models** that:
+
+- use `enableSelector` to isolate one model instance per resource
+- bootstrap resource metadata before normal state usage
+- combine `$fetch`, `$sdk`, and model state in one reusable resource owner
+- expose schema, permissions, form helpers, and CRUD query/mutation flows through one model boundary
+- centralize invalidation rules for list and item-level resource state
+
+That example is a good reading target when you want to understand how Zova Model can become a reusable full-feature resource facade instead of only a thin data wrapper.
+
 ## Practical implications for frontend state design
 
 When asked to add frontend state, do not immediately assume a generic Vue/Pinia-style answer.
@@ -80,8 +284,17 @@ When asked to add frontend state, do not immediately assume a generic Vue/Pinia-
 A better default is to ask:
 
 1. is this state already a good fit for a Zova model?
-2. is the data async or sync, and does that distinction matter to the model choice?
-3. does SSR or persistence make the model layer especially valuable here?
-4. is there already a model bean that should own this state instead of adding a new ad hoc state container?
+2. is the data async, mem, local, cookie, or db-oriented?
+3. do caching, invalidation, or persistence matter?
+4. does SSR or hydration make the model layer especially valuable here?
+5. is there already a model bean that should own this state instead of adding a new ad hoc state container?
 
 That keeps the code aligned with Zova’s actual architecture.
+
+## Final takeaway
+
+The most important architectural insight is simple:
+
+> Zova Model is a model-bean layer built on top of TanStack Query that unifies async data, local persistence, cookie state, db persistence, and in-memory state behind one model-owned runtime.
+
+Once that clicks, the model APIs stop looking like isolated helpers and start reading as one coherent state architecture.