cabloy 5.1.61 → 5.1.62

package/cabloy-docs/frontend/zova-app-guide.md

@@ -0,0 +1,251 @@
+# Zova App Guide
+
+This guide explains the root app-shell module in Zova through the current public Cabloy Basic source:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-app
+```
+
+Use this page when you want to understand:
+
+- what `a-app` is responsible for
+- what `a-app` is **not** responsible for
+- how the root app wrapper reaches the routed tree
+- where app-wide behavior wrapping enters the runtime
+- which files to read first when tracing the source
+
+## Why this page exists
+
+Several other frontend guides already explain routing, startup, behavior, and SSR.
+
+What they do not explain directly is the thin root module that connects those concerns at the app host level.
+
+That root module is `a-app`.
+
+In the current Basic source, `a-app` is not a feature module full of pages or business services. It is a small app-shell module whose main job is to host the root app controller, apply app-level metadata, initialize app-wide behaviors, and render the routed tree.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+1. `a-app` exposes the root app component surface
+2. `ZApp` mounts the root controller
+3. `ControllerApp` initializes app meta and root behaviors
+4. `ControllerApp.render()` returns the routed tree through `RouterView`
+5. that routed tree is wrapped by `BeanBehaviorsHolder` so app-wide behaviors can participate around it
+
+That means `a-app` is the root app host, not the owner of every frontend concern.
+
+## What `a-app` is
+
+In the current Basic source, `a-app` is mainly these five things:
+
+- a **module integration surface** through generated metadata
+- a **root component wrapper** through `ZApp`
+- an **app controller** through `ControllerApp`
+- a **root behavior host** through `BeanBehaviorsHolder`
+- a **routed-content host** through `RouterView`
+
+Those roles are enough to make it a real architectural boundary even though the module is small.
+
+## What `a-app` is not
+
+It is equally important to avoid over-assigning responsibilities to `a-app`.
+
+`a-app` does **not** itself define:
+
+- page route records
+- page controllers
+- model beans
+- standalone business services
+- the actual layout implementations
+- the full SSR orchestration flow
+
+Those responsibilities belong to other routing, layout, model, service, and SSR layers.
+
+So when you read `a-app`, read it as the root host that connects those systems, not as the place where all of them are authored.
+
+## The core source-reading path
+
+When reading `a-app`, use this order:
+
+1. `zova/src/suite-vendor/a-zova/modules/a-app/src/.metadata/this.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-app/src/.metadata/index.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-app/src/.metadata/component/app.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-app/src/component/app/controller.tsx`
+5. `zova/src/suite-vendor/a-zova/modules/a-app/src/config/config.ts`
+
+That order moves from module identity, to generated integration surface, to component wrapper, to runtime controller logic, to configuration hook points.
+
+## What each source file clarifies
+
+### `src/.metadata/this.ts`
+
+This file gives the module identity quickly:
+
+- module name is `a-app`
+- module scope is exported as `ScopeModule`
+
+Read this file first when you want to anchor the rest of the source path.
+
+### `src/.metadata/index.ts`
+
+This is the generated integration map for the module.
+
+It shows that `a-app` contributes:
+
+- the app controller registration
+- the `ZApp` component export
+- the module config typing
+- the module scope typing
+
+This file is the best single map of how the module enters the larger Zova container and component records.
+
+### `src/.metadata/component/app.ts`
+
+This file shows the public wrapper component:
+
+- `ZApp` is defined with `defineComponent(...)`
+- it calls `useController(ControllerApp, ...)`
+- it exposes `controllerRef` as a controller-facing hook
+
+The important idea is that `ZApp` is a thin wrapper whose main job is to mount the controller-oriented runtime path.
+
+## `src/component/app/controller.tsx`
+
+This is the real runtime center of the module.
+
+Its main jobs are:
+
+- call `$useMeta(...)` to set app-level document metadata
+- initialize `BeanBehaviorsHolder`
+- read root behaviors from `scope.config.behaviors`
+- render the routed tree through `RouterView`
+
+This is the file that shows the actual app-host responsibilities most clearly.
+
+## `src/config/config.ts`
+
+This file is small but important.
+
+It exposes the module config surface for:
+
+- `behaviors`
+
+That matters because it shows that `a-app` is intentionally designed to receive app-wide behavior configuration from outside the module instead of hard-coding every root behavior locally.
+
+## Runtime flow from `ZApp` to routed content
+
+The shortest practical runtime flow is:
+
+1. `ZApp` calls `useController(ControllerApp, ...)`
+2. the framework creates and loads `ControllerApp`
+3. `ControllerApp.__init__()` sets app-level meta through `$useMeta(...)`
+4. `ControllerApp.__init__()` initializes `BeanBehaviorsHolder`
+5. the holder reads app-wide behavior declarations from `scope.config.behaviors`
+6. `ControllerApp.render()` returns behavior-wrapped `<RouterView />`
+7. the routed page tree continues from the router and layout layers
+
+This page stops at the root app-host boundary. For the deeper behavior-composition path behind `BeanBehaviorsHolder`, continue with [Root Behaviors Guide](/frontend/root-behaviors-guide).
+
+## Relationship to routing
+
+`a-app` does not define the page route records themselves.
+
+Instead, it hosts the routed tree by rendering `RouterView`.
+
+That means routing questions usually split into two layers:
+
+- `a-app` as the root host that renders the routed content entry
+- router and layout layers as the owners of route records, layout choice, guards, and routed-host behavior
+
+Read together with:
+
+- [Page Route Guide](/frontend/page-route-guide)
+- [A-Router Guide](/frontend/a-router-guide)
+- [Zova Router Under the Hood](/frontend/zova-router-under-the-hood)
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide)
+
+## Relationship to behaviors
+
+`a-app` is also the root behavior host in the current Basic source.
+
+Because `ControllerApp` initializes `BeanBehaviorsHolder` from `scope.config.behaviors`, project or module-level code can extend the root app host by contributing behavior configuration.
+
+A practical way to think about this is:
+
+- `a-app` owns the root behavior hosting point
+- other modules can contribute app-wide behavior declarations to that hosting point
+
+Read together with:
+
+- [Behavior Guide](/frontend/behavior-guide)
+- [Root Behaviors Guide](/frontend/root-behaviors-guide)
+
+## Relationship to startup
+
+App startup and `a-app` are related, but they are not the same concept.
+
+- **app startup** decides when the application lifecycle becomes operational
+- **`a-app`** is the root app host component/controller path inside that operational application
+
+That distinction helps avoid placing startup logic into the root app controller just because it feels globally visible.
+
+Read together with:
+
+- [App Startup Guide](/frontend/app-startup-guide)
+- [System Startup Guide](/frontend/system-startup-guide)
+
+## Relationship to SSR
+
+`a-app` participates in the frontend runtime side of SSR because it is part of the application render tree.
+
+But it is not the complete SSR orchestration layer.
+
+In the broader SSR model:
+
+- Vona owns request-level SSR orchestration
+- the built frontend bundle provides the SSR entry
+- Zova SSR runtime resolves and renders the frontend route tree
+- `a-app` participates as part of that root render tree
+
+Read together with:
+
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+
+## A compact interpretation of app-wide extension
+
+When you need app-wide overlays or wrappers, the root behavior host is often a better fit than forcing that concern into unrelated page code.
+
+A practical extension model is:
+
+- keep `a-app` as the thin root host
+- let other modules contribute root behavior configuration
+- let those behaviors wrap the routed tree in a reusable way
+
+That keeps the root host small while still making it extensible.
+
+## Where to read next
+
+After this page, the most useful next paths are usually:
+
+- [Root Behaviors Guide](/frontend/root-behaviors-guide)
+- [App Startup Guide](/frontend/app-startup-guide)
+- [Page Route Guide](/frontend/page-route-guide)
+- [Behavior Guide](/frontend/behavior-guide)
+- [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+
+## Final takeaway
+
+The most accurate way to read `a-app` is not as a generic Vue root component and not as the owner of the whole frontend system.
+
+Read it as the thin Zova app-shell host that:
+
+- mounts the root app controller
+- applies app-level meta
+- hosts root behaviors
+- renders the routed tree
+
+That is the source-confirmed role of `a-app` in the current Basic frontend architecture.

package/cabloy-docs/frontend/zova-form-source-reading-map.md

@@ -12,6 +12,8 @@ Use this page together with:
 
 - [Form Guide](/frontend/form-guide)
 - [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
+- [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)
+- [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map)
 - [Zova Source Reading Map](/frontend/zova-source-reading-map)
 - [Behavior Guide](/frontend/behavior-guide)
 - [API Schema Guide](/frontend/api-schema-guide)
@@ -19,6 +21,7 @@ Use this page together with:
 
 > [!TIP]
 > **Zova Form docs path**
+>
 > 1. **[Form Guide](/frontend/form-guide)** — learn the public authoring surface
 > 2. **[Zova Form Under the Hood](/frontend/zova-form-under-the-hood)** — learn how the runtime pieces cooperate
 > 3. **[Zova Form Source Reading Map](/frontend/zova-form-source-reading-map)** — learn which files to read next
@@ -36,18 +39,11 @@ The `a-form` module sits at the intersection of several Zova concerns at once:
 - behavior-based field wrapping
 - resource-driven CRUD page integration
 
-Because of that, form documentation now has three distinct layers:
+This page exists for one narrow job:
 
 - [Form Guide](/frontend/form-guide) explains how to author forms
 - [Zova Form Under the Hood](/frontend/zova-form-under-the-hood) explains how the runtime pieces cooperate
-- this page explains which files to read first for each source-reading question
-
-Because of that, source reading can become slow for one predictable reason:
-
-- you can find one relevant file such as the form controller
-- but you do not yet know the shortest accurate path to the next runtime layer
-
-This page gives a compact reading order so you can move from public surface to runtime detail without drifting.
+- this page gives the shortest file-order paths for specific form questions
 
 ## How to use this page
 
@@ -251,6 +247,8 @@ Use this path when you are asking questions like:
 - `lib/utils.ts` shows the canonical scene-to-form-meta translation helpers
 - `blockFilter/controller.tsx` shows the lighter-weight filter-form branch using the same form module
 
+If your next question becomes how `formScene` becomes `formMeta`, then `pageMeta`, and finally visible shell/tab state, continue with [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide).
+
 ## 8. Representative specimens to read before editing the framework
 
 Use this section when you want one small example before reading the framework internals.

package/cabloy-docs/frontend/zova-form-under-the-hood.md

@@ -5,6 +5,8 @@ This guide explains the source-level runtime path behind Zova Form.
 Use this page together with:
 
 - [Form Guide](/frontend/form-guide)
+- [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)
+- [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map)
 - [Zova Form Source Reading Map](/frontend/zova-form-source-reading-map)
 - [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
 - [Behavior Guide](/frontend/behavior-guide)
@@ -14,8 +16,11 @@ Use this page after [Form Guide](/frontend/form-guide) when you want to move fro
 
 If your next question is not “how does this runtime work?” but “which files should I read next?”, continue with [Zova Form Source Reading Map](/frontend/zova-form-source-reading-map).
 
+If your next question is specifically how `formScene` flows into `formMeta`, then `pageMeta`, and finally shell/tab state, continue with [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide).
+
 > [!TIP]
 > **Zova Form docs path**
+>
 > 1. **[Form Guide](/frontend/form-guide)** — learn the public authoring surface
 > 2. **[Zova Form Under the Hood](/frontend/zova-form-under-the-hood)** — learn how the runtime pieces cooperate
 > 3. **[Zova Form Source Reading Map](/frontend/zova-form-source-reading-map)** — learn which files to read next