cabloy 5.1.59 → 5.1.61

package/cabloy-docs/frontend/ssr-troubleshooting-guide.md

@@ -0,0 +1,301 @@
+# SSR Troubleshooting Guide
+
+This guide explains how to debug common SSR problems in Zova within the Cabloy monorepo.
+
+## Why this page exists
+
+The other SSR pages explain how the SSR model is supposed to work.
+
+This page answers a different question:
+
+- when SSR behavior is wrong, where should you look first?
+
+That matters because SSR issues are easy to misclassify.
+
+A symptom that looks like “frontend rendering is broken” can actually come from:
+
+- SSR site routing on the backend side
+- a missing or stale frontend bundle
+- SSR-only route or data-loading behavior
+- hydration mismatch on the client
+- edition-specific theme assumptions
+
+A good troubleshooting flow starts by identifying **which layer is failing** before trying to patch the symptom directly.
+
+## Start with the four-layer model
+
+Use the [SSR Architecture Overview](/frontend/ssr-architecture-overview) as the first mental model.
+
+For troubleshooting, the practical layer split is:
+
+1. **Vona SSR orchestration**
+   - request entry
+   - SSR site matching
+   - dev proxy versus built asset versus SSR render
+2. **frontend build output**
+   - SSR entry
+   - manifest
+   - client assets
+3. **Zova SSR server render**
+   - route resolution
+   - HTML render
+   - state/meta/preload generation
+4. **client hydration**
+   - initial state reuse
+   - browser-only behavior
+   - final theme and DOM state
+
+If you identify the failing layer first, most SSR debugging becomes much faster.
+
+## Fast symptom-to-layer map
+
+Use this quick map before diving deeper.
+
+| Symptom | Start here |
+| --- | --- |
+| request does not hit the expected SSR page | Vona SSR orchestration |
+| dev works but prod fails | frontend build output + SSR env/runtime |
+| HTML appears but hydration is wrong | client hydration |
+| server-rendered data is missing or refetched unexpectedly | Zova SSR server render + init data flow |
+| SEO/meta output is missing | Zova SSR server render + meta flow |
+| first paint theme is wrong | SSR env + theme rules |
+| static assets 404 after SSR deploy | frontend build output |
+
+## Symptom 1: the request does not hit the expected SSR page
+
+Typical signs:
+
+- a page that should be SSR-rendered falls through to another route
+- a URL returns the wrong site
+- SSR works for one path prefix but not another
+
+Start with these questions:
+
+1. is the request entering the correct SSR site at all?
+2. is the path prefix/site selection correct?
+3. are you expecting SSR where the route is actually a normal backend or static path?
+
+A practical debugging order is:
+
+- confirm the target URL and SSR site assumptions
+- re-check the SSR architecture split in [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+- verify whether the problem is a site-entry issue rather than a page-render issue
+
+If the request never reaches the intended SSR site, do **not** start by changing page components or hydration logic.
+
+## Symptom 2: dev works but prod fails
+
+Typical signs:
+
+- SSR works through the dev server but breaks after build
+- dev shows the page, while prod returns missing asset or render errors
+- only built deployments show the problem
+
+This usually means the issue is not only “SSR logic.”
+
+It often means one of these instead:
+
+- build output is stale or incomplete
+- the expected frontend bundle was not generated for the target flavor
+- SSR env/runtime assumptions differ between dev and prod
+- asset paths or manifest assumptions are wrong after build
+
+Start with these checks:
+
+1. was the relevant frontend SSR build actually regenerated?
+2. are you targeting the correct flavor for the active edition?
+3. does the issue happen before page render, during page render, or only after hydration?
+
+Read together:
+
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+- [SSR Environment Variables](/frontend/ssr-env)
+- [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
+
+## Symptom 3: HTML appears, but hydration is wrong
+
+Typical signs:
+
+- server HTML looks right at first, then changes unexpectedly on the client
+- hydration mismatch warnings appear
+- browser-only UI behaves differently from the server output
+- the first screen “flashes” into a different state after load
+
+This usually means the server render and the browser’s final state are not using exactly the same assumptions.
+
+Common causes include:
+
+- browser-only logic running too early
+- client-only components not being isolated properly
+- theme-sensitive output being treated as authoritative on the server when it is not
+- state that was expected to transfer through SSR not being reused correctly during hydration
+
+Start with these checks:
+
+1. does this UI depend on browser APIs or client-only rendering behavior?
+2. should part of the UI be wrapped in `ClientOnly`?
+3. is the code assuming the server already knows the browser’s final theme?
+4. is the client reusing server-provided state, or recomputing a different result?
+
+Read together:
+
+- [SSR ClientOnly](/frontend/ssr-client-only)
+- [SSR Init Data](/frontend/ssr-init-data)
+- [SSR Environment Variables](/frontend/ssr-env)
+- [Theme Guide](/frontend/theme-guide)
+
+## Symptom 4: server-rendered data is missing or is fetched again unexpectedly
+
+Typical signs:
+
+- the page renders without expected data on the server
+- the client repeats the first data fetch that should have been prepared already
+- loading behavior is different between SSR and client navigation
+
+A better default in Zova is:
+
+- prepare SSR data through the intended model/controller flow
+- let hydration reuse that prepared state on the client
+
+Start with these checks:
+
+1. is the data prepared in the intended SSR lifecycle rather than in an ad hoc client path?
+2. is the data-loading logic aligned with the model-based SSR flow?
+3. are you accidentally bypassing the existing hydration reuse path?
+
+Read together:
+
+- [SSR Init Data](/frontend/ssr-init-data)
+- [Server Data](/frontend/server-data)
+- [Model State Guide](/frontend/model-state-guide)
+
+## Symptom 5: SEO/meta output is missing or inconsistent
+
+Typical signs:
+
+- page title is wrong after SSR
+- expected meta tags are missing in server-rendered HTML
+- metadata looks correct on the client but not in the initial server response
+
+This usually means the metadata is not being produced through the intended SSR-aware path.
+
+Start with these checks:
+
+1. are you using `$useMeta` instead of a parallel custom mechanism?
+2. is the metadata available during SSR rather than only after client boot?
+3. are multiple metadata layers overwriting each other intentionally or accidentally?
+
+Read together:
+
+- [SSR SEO Meta](/frontend/ssr-seo-meta)
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+
+## Symptom 6: theme or dark-mode behavior is wrong on first paint
+
+Typical signs:
+
+- server output uses one theme, then the browser switches to another immediately
+- dark/light SSR output looks unstable
+- the result differs between Web SSR and Admin SSR
+
+This area is especially sensitive because SSR theme authority is not identical in every flavor.
+
+Start with these checks:
+
+1. are you treating the server’s theme-sensitive read as final browser truth?
+2. does the active flavor support cookie-backed SSR theme resolution?
+3. are you applying a Basic-specific theme assumption to a different edition or adapter?
+
+Read together:
+
+- [SSR Environment Variables](/frontend/ssr-env)
+- [Theme Guide](/frontend/theme-guide)
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+
+A practical rule is:
+
+- if exact browser theme matching matters, keep the output hydration-tolerant unless the active SSR path provides a stronger server-side guarantee
+
+## Symptom 7: static assets 404 after SSR deploy
+
+Typical signs:
+
+- HTML response appears, but CSS or JS assets do not load
+- SSR page shell renders without expected styling or scripts
+- built deployment fails while local dev works
+
+This usually points to bundle output or deployment-path issues rather than page logic.
+
+Start with these checks:
+
+1. was the correct frontend build generated?
+2. are the expected client assets present for the deployed bundle?
+3. does the deployment path still match the built asset assumptions?
+
+Read together:
+
+- [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
+- [Environment and Config Guide](/frontend/environment-config-guide)
+- [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+
+## A safe debugging order
+
+When SSR breaks and the failure is unclear, use this order.
+
+### Step 1: identify the first broken stage
+
+Ask:
+
+- is the request entering the intended SSR site?
+- is the server returning HTML at all?
+- is the HTML already wrong before hydration?
+- does it only go wrong after the browser starts running?
+
+### Step 2: separate server-render problems from hydration problems
+
+This split removes a lot of confusion.
+
+- if the initial HTML is wrong, focus on SSR entry, route resolution, render, data, or meta
+- if the initial HTML is right but the browser changes it incorrectly, focus on hydration, client-only boundaries, theme authority, or client state reuse
+
+### Step 3: check edition-sensitive assumptions
+
+Especially for theme or UI-sensitive work, confirm:
+
+- active edition
+- active UI layer
+- whether the rule is shared across editions or adapter-specific
+
+### Step 4: reuse the framework’s intended abstractions
+
+Before adding custom fixes, ask whether the framework already provides the right surface:
+
+- `ClientOnly` for browser-only UI
+- model/controller SSR init flow for data preparation
+- `$useMeta` for SEO/meta
+- existing theme/env rules for theme-sensitive SSR behavior
+
+## Recommended reading order for troubleshooting
+
+Use this path when SSR behavior is wrong and you need to narrow the problem quickly:
+
+1. this page for symptom triage
+2. [SSR Architecture Overview](/frontend/ssr-architecture-overview)
+3. [SSR Overview](/frontend/ssr-overview)
+4. [SSR Init Data](/frontend/ssr-init-data)
+5. [SSR ClientOnly](/frontend/ssr-client-only)
+6. [SSR SEO Meta](/frontend/ssr-seo-meta)
+7. [SSR Environment Variables](/frontend/ssr-env)
+8. [Theme Guide](/frontend/theme-guide)
+9. [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
+
+## Implementation checks for SSR troubleshooting
+
+Before finalizing an SSR fix, ask:
+
+1. did I identify the failing SSR layer before changing code?
+2. is this actually a server-render issue, or a hydration issue?
+3. am I reusing the intended framework abstraction instead of adding a parallel workaround?
+4. does the fix accidentally assume an edition-specific UI or theme rule is universal?
+
+That keeps SSR debugging aligned with the Cabloy fullstack model and reduces one-off fixes that solve only the symptom.

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

@@ -0,0 +1,295 @@
+# Zova Form Source Reading Map
+
+This page is a practical map for contributors and AI workflows that need to read Zova Form source code efficiently.
+
+Use this page after [Zova Form Under the Hood](/frontend/zova-form-under-the-hood) when your next question is not the runtime model itself, but which files to read first for a specific form-internals topic.
+
+It answers a narrow question:
+
+> when I need to understand how Zova Form works internally, which files should I read first, and in what order?
+
+Use this page together with:
+
+- [Form Guide](/frontend/form-guide)
+- [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
+- [Zova Source Reading Map](/frontend/zova-source-reading-map)
+- [Behavior Guide](/frontend/behavior-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+
+> [!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
+>
+> **You are here:** step 3.
+> **Previous page:** [Zova Form Under the Hood](/frontend/zova-form-under-the-hood).
+
+## Why this page exists
+
+The `a-form` module sits at the intersection of several Zova concerns at once:
+
+- controller-oriented component design
+- schema-driven rendering
+- Zod and TanStack validation
+- behavior-based field wrapping
+- resource-driven CRUD page integration
+
+Because of that, form documentation now has three distinct layers:
+
+- [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.
+
+## How to use this page
+
+For each topic below:
+
+1. start with the public guide to refresh the architectural intent
+2. read the first source file to identify the public surface
+3. continue into the next runtime file only if you still need the implementation detail
+4. stop as soon as you have enough information for the task
+
+The goal is not to read the entire form stack every time. The goal is to choose the shortest correct path.
+
+## 1. Public form surface and wrapper entrypoints
+
+Use this path when you are asking questions like:
+
+- what is the public Zova Form surface?
+- where do `ZForm` and `ZFormField` enter the runtime?
+- how does `controllerRef` reach the controller instance?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Component Guide](/frontend/component-guide)
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/.metadata/component/form.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-form/src/.metadata/component/formField.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx`
+4. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/controller.tsx`
+5. `zova/packages-zova/zova-core/src/composables/useController.ts`
+
+### What each file clarifies
+
+- metadata wrapper files show how the public component wrappers enter `useController(...)`
+- `form.ts` exposes `ZForm` and its typed controller-facing props surface
+- `formField.ts` exposes `ZFormField` and the controller-aware slot contract
+- `useController.ts` shows how the controller instance is created and bound to the wrapper component lifecycle
+
+## 2. Form controller ownership and form runtime
+
+Use this path when you are asking questions like:
+
+- where is the form instance created?
+- where does `formState` come from?
+- how does `submit()` or `reset()` work in Zova Form?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Zod Guide](/frontend/zod-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx`
+2. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/beanControllerFormBase.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/beanControllerPageFormBase.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-form/src/types/form.ts`
+
+### What each file clarifies
+
+- `component/form/controller.tsx` is the main form runtime owner
+- `beanControllerFormBase.ts` shows the shared `$useForm(...)` wrapper around TanStack Form
+- `beanControllerPageFormBase.ts` shows the page-controller-oriented variant for form pages
+- `types/form.ts` shows the exposed type contracts for submit data, state, and events
+
+## 3. Field controller ownership and field render flow
+
+Use this path when you are asking questions like:
+
+- how is one field connected to the parent form?
+- where do `setValue(...)` and `handleBlur()` live?
+- how does one field become a rendered vnode?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Behavior Guide](/frontend/behavior-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/controller.tsx`
+2. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/render.tsx`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/types/formField.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formFieldPreset/controller.tsx`
+5. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formFieldBlank/controller.tsx`
+
+### What each file clarifies
+
+- `formField/controller.tsx` is the field runtime owner and host-injected child of the form controller
+- `formField/render.tsx` shows the final render handoff through behaviors and `zovaJsx.render(...)`
+- `types/formField.ts` shows field options, layout options, render context, and the `$$FieldProps` marker
+- `formFieldPreset/controller.tsx` shows the preset-driven delegation path
+- `formFieldBlank/controller.tsx` shows the free-row slot-only path
+
+## 4. Schema-driven rendering and CEL/JSX resolution
+
+Use this path when you are asking questions like:
+
+- how does a schema become rendered fields?
+- where do field props come from?
+- how are metadata expressions or render providers resolved?
+
+### Read the docs first
+
+- [API Schema Guide](/frontend/api-schema-guide)
+- [Form Guide](/frontend/form-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx`
+2. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/render.tsx`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/types/formField.ts`
+
+### What each file clarifies
+
+- `form/controller.tsx` shows schema property loading, field CEL scope creation, and top-level field prop extraction
+- `form/render.tsx` shows how schema properties become children when the form body is not manually overridden
+- `types/formField.ts` shows the field render-context shapes that the runtime passes through to renderers and behaviors
+
+## 5. Validation, submit flow, and server error normalization
+
+Use this path when you are asking questions like:
+
+- where is submit wired?
+- how are form-level and field-level validators chosen?
+- how are server validation errors pushed back into the form state?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Zod Guide](/frontend/zod-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx`
+2. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/controller.tsx`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/types/form.ts`
+
+### What each file clarifies
+
+- `form/controller.tsx` shows `submit(...)`, `_createForm()`, `onSubmitInvalid`, `onSubmitData`, and error normalization
+- `formField/controller.tsx` shows how field validators are derived from Zod schema or explicit field options
+- `types/form.ts` shows the public event and submit-type contracts that the rest of the framework consumes
+
+## 6. Provider config, default renderers, and behavior-based layout
+
+Use this path when you are asking questions like:
+
+- where does the default `Input` renderer come from?
+- how does `formProvider` affect field rendering?
+- where do form-field layout behaviors enter the pipeline?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Behavior Guide](/frontend/behavior-guide)
+
+### Then read source in this order
+
+1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/controller.tsx`
+2. `zova/src/suite/cabloy-basic/modules/basic-adapter/src/config/config.ts`
+3. `zova/src/suite/a-home/modules/home-login/src/page/login/render.tsx`
+4. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/formField/render.tsx`
+
+### What each file clarifies
+
+- `formField/controller.tsx` shows how field props, layout, options, provider config, and behaviors are merged
+- `basic-adapter/src/config/config.ts` shows the default Basic provider components and layout behaviors
+- `home-login/render.tsx` shows a page-level `formProvider` override for layout behavior
+- `formField/render.tsx` shows how the behavior-wrapped render path leads to the final vnode
+
+## 7. Resource-driven CRUD page integration
+
+Use this path when you are asking questions like:
+
+- how does a resource page feed schema and data into `ZForm`?
+- where do `formMeta`, `formSchema`, and `formProvider` come from in CRUD pages?
+- how does submit delegate back to resource mutation logic?
+
+### Read the docs first
+
+- [Form Guide](/frontend/form-guide)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- [Tutorial 2: Create Your First CRUD](/fullstack/tutorial-2-first-crud)
+- [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing)
+
+### Then read source in this order
+
+1. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx`
+2. `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockForm/controller.tsx`
+3. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/utils.ts`
+4. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockFilter/controller.tsx`
+
+### What each file clarifies
+
+- `blockPageEntry/controller.tsx` shows the resource-driven CRUD form orchestration path
+- `blockForm/controller.tsx` shows how a block-level wrapper passes schema/data/provider/meta into `ZForm`
+- `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
+
+## 8. Representative specimens to read before editing the framework
+
+Use this section when you want one small example before reading the framework internals.
+
+### Read these specimens first
+
+1. `zova/src/suite/a-demo/modules/demo-basic/src/page/toolOne/controller.tsx`
+2. `zova/src/suite/a-demo/modules/demo-basic/src/page/toolOne/render.tsx`
+3. `zova/src/suite/a-home/modules/home-login/src/page/login/render.tsx`
+
+### Why these three specimens matter
+
+- `toolOne` shows both schema-driven and manual form usage in one page
+- `home-login` shows a real page using presets, blank rows, and provider-level layout override
+- together they give you the public authoring shape before you descend into the form runtime
+
+## 9. A compact reading strategy
+
+When in doubt, use this order:
+
+1. [Form Guide](/frontend/form-guide)
+2. one real usage specimen such as `toolOne` or `home-login`
+3. the public wrapper metadata under `src/.metadata/component/*.ts`
+4. `component/form/controller.tsx`
+5. `component/formField/controller.tsx`
+6. render beans, types, and integration layers only if you still need more detail
+
+That order usually gets you to the answer faster than starting from the deepest runtime files first.
+
+## 10. Final takeaway
+
+The fastest way to read Zova Form accurately is not to memorize every file in `a-form`.
+
+It is to recognize which question you are asking:
+
+- public wrapper question
+- form-runtime question
+- field-render question
+- validation question
+- resource-CRUD integration question
+
+Then start from the smallest public file that matches that question and only descend into deeper runtime files as needed.