cabloy 5.1.60 → 5.1.62

package/.claude/skills/cabloy-zova-source-reading/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: cabloy-zova-source-reading
+description: Use this skill when the user wants to read, trace, or explain Zova frontend source code rather than scaffold new code: where a page/component/model/behavior/SSR flow is implemented, how a runtime path works internally, why a plain controller field is reactive, how Zova differs from generic Vue 3 habits, or which files to read first. Trigger for requests about Zova source reading, runtime tracing, Vue-vs-Zova explanation, controller/bean/IoC mental models, or the Zova-native way to understand frontend behavior. Do not use it for normal frontend scaffolding or backend/frontend contract regeneration.
+---
+
+# Cabloy Zova Source Reading
+
+Use this skill when the task is to understand, explain, or trace Zova frontend behavior in source code.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. classify whether the user needs a source-entry map, a runtime-flow trace, or a Vue-vs-Zova explanation
+3. start from Zova-native public docs before diving into framework source
+4. explain Zova architecture in its own terms before translating it into Vue analogies
+5. separate source-confirmed runtime behavior from interpretive comparison
+6. finish with verification guidance that matches the analysis scope
+
+## Step 1: Detect the active edition
+
+Check the repository root for these marker files:
+
+- `__CABLOY_BASIC__`
+- `__CABLOY_START__`
+
+Interpretation:
+
+- `__CABLOY_BASIC__` present → this is Cabloy Basic
+- `__CABLOY_START__` present → this is Cabloy Start
+- neither present → inspect the repo scripts and ask before making edition-specific frontend assumptions
+
+This matters most when the analysis becomes UI-sensitive, SSR-site-sensitive, flavor-sensitive, or module-set-sensitive.
+
+## Step 2: Classify the analysis mode
+
+Before reading files deeply, decide which kind of question the user is really asking.
+
+### Mode A: source-location mode
+
+Use this mode when the user is asking questions like:
+
+- where should I start reading?
+- which files are relevant?
+- what order should I read the source in?
+- where is this implemented in Zova?
+
+### Mode B: runtime-flow mode
+
+Use this mode when the user is asking questions like:
+
+- how does this work internally?
+- why is this field reactive?
+- where does `$computed` / `$params` / `$query` come from?
+- how does page/controller/component render enter the runtime?
+
+### Mode C: Vue-vs-Zova comparison mode
+
+Use this mode when the user is asking questions like:
+
+- how should I understand this relative to Vue 3?
+- is this just Vue with classes?
+- what is the Zova way instead of the generic Vue way?
+- how do controller / bean / model / render roles map to Vue concepts?
+
+If a request spans more than one mode, answer in this order:
+
+1. source-location mode
+2. runtime-flow mode
+3. Vue-vs-Zova comparison mode
+
+That order reduces the risk of drifting into premature analogy before the source path is understood.
+
+## Step 3: Start from public Zova docs first
+
+Do not begin by forcing the problem into generic Vue terminology.
+
+Start from the public frontend reading docs in `cabloy-docs/frontend/`.
+
+### Primary reading surfaces
+
+- `cabloy-docs/frontend/reading-zova-for-vue-developers.md`
+- `cabloy-docs/frontend/zova-vs-vue3-comparison.md`
+- `cabloy-docs/frontend/zova-reactivity-under-the-hood.md`
+- `cabloy-docs/frontend/zova-source-reading-map.md`
+
+For compact procedural summaries inside the skill bundle, also use:
+
+- `references/analysis-modes.md`
+- `references/core-reading-paths.md`
+
+### Core architecture surfaces
+
+Use these when the question needs broader architectural context:
+
+- `cabloy-docs/frontend/introduction.md`
+- `cabloy-docs/frontend/foundation.md`
+- `cabloy-docs/frontend/design-principles.md`
+- `cabloy-docs/frontend/ioc-and-beans.md`
+- `cabloy-docs/frontend/page-guide.md`
+- `cabloy-docs/frontend/component-guide.md`
+- `cabloy-docs/frontend/model-architecture.md`
+- `cabloy-docs/frontend/page-route-guide.md`
+- `cabloy-docs/frontend/behavior-guide.md`
+- `cabloy-docs/frontend/ssr-architecture-overview.md`
+
+## Step 4: Choose the shortest correct source-reading path
+
+After reading the public docs, choose the smallest source path that answers the question.
+
+Use these bundled references to keep the workflow compact:
+
+- `references/analysis-modes.md`
+- `references/core-reading-paths.md`
+
+Use the public `cabloy-docs/frontend/zova-source-reading-map.md` as the fuller explanation layer, but use the bundled references first when they are enough for the current task.
+
+## Step 5: Explain Zova-native meaning first
+
+When answering, explain the Zova role first, then add Vue analogies only if they help.
+
+### Required answer posture
+
+1. identify the Zova-native role first
+   - page controller
+   - component controller
+   - render bean
+   - style bean
+   - model bean
+   - service bean
+   - behavior bean
+   - route/SSR integration layer
+
+2. explain the source-confirmed runtime path second
+
+3. only then offer Vue analogies as approximate translations
+
+Do **not** lead with statements like:
+
+- "this is basically just Vue setup with classes"
+- "this should really be a normal Vue composable"
+- "the right end state is probably `ref.value`"
+
+Those translations can erase the actual Zova architecture.
+
+For component-wrapper questions specifically, remember that `controllerRef` exposes the controller instance, not a generic DOM ref, and should not be treated as a generic Vue component-ref substitute without checking the current wrapper/controller source path.
+
+## Step 6: Distinguish source-confirmed behavior from interpretive comparison
+
+Always make the boundary explicit.
+
+### Source-confirmed behavior
+
+This includes claims you can support directly from current source files, such as:
+
+- where a controller is created
+- where a bean becomes reactive
+- where route state is refreshed
+- where render is redirected
+- which helper wraps which Vue API
+
+### Interpretive comparison
+
+This includes claims such as:
+
+- why Zova feels more object-oriented than Vue
+- how Zova growth paths differ from typical Vue growth paths
+- which analogy is the closest Vue mental model
+
+These can be useful, but they should be labeled as interpretation rather than current-source fact.
+
+## Step 7: Stay inside the right workflow boundary
+
+Use this skill for explanation and source reading.
+
+Do **not** use it as the primary workflow when the real task is:
+
+- creating or refactoring frontend structures → prefer `cabloy-frontend-scaffold`
+- diagnosing backend/frontend contract drift → prefer `cabloy-contract-loop`
+- choosing whether the work belongs to backend, frontend, fullstack, docs, or AI guidance → prefer `cabloy-workflow`
+
+## Step 8: Verification guidance
+
+Always finish with a verification path that matches the analysis task.
+
+### For source-reading answers
+
+Verify:
+
+- the cited file paths exist
+- the described runtime path is actually visible in current source
+- the answer does not contradict the public frontend docs
+
+### For Vue-vs-Zova explanation answers
+
+Verify:
+
+- the Zova-native explanation comes first
+- Vue analogies are marked as approximate, not authoritative
+- no claim quietly rewrites Zova back into generic Vue habits
+
+### For edition-sensitive frontend analysis
+
+Verify:
+
+- the active edition marker was considered
+- Basic-only or Start-only UI assumptions were not silently generalized
+- SSR, theme, and flavor-sensitive statements match the active edition context
+
+## Response pattern
+
+When helpful, structure the response around these points:
+
+1. detected edition
+2. analysis mode
+3. public docs to read first
+4. source path to inspect next
+5. Zova-native explanation
+6. optional Vue analogy
+7. verification notes or caveats
+
+Keep the response practical. The value of this skill is to help AI and users read Zova source accurately and in the right architectural order, not to flatten Zova into generic Vue prose.

package/.claude/skills/cabloy-zova-source-reading/references/analysis-modes.md

@@ -0,0 +1,91 @@
+# Analysis Modes
+
+Use this reference to choose the shortest correct analysis posture before reading Zova source deeply.
+
+## Mode A: source-location mode
+
+Use this mode when the user is mainly asking:
+
+- where should I start reading?
+- which files matter?
+- what order should I read the source in?
+- where is this implemented?
+
+### Workflow
+
+1. detect the active edition if UI-sensitive assumptions might matter
+2. start from the public frontend docs first
+3. pick the smallest matching thread from `cabloy-docs/frontend/zova-source-reading-map.md`
+4. cite the initial source files in the recommended reading order
+5. stop before tracing deeper runtime layers unless the user also wants runtime-flow analysis
+
+### Output emphasis
+
+- reading order
+- key file paths
+- why those files are the right starting points
+
+## Mode B: runtime-flow mode
+
+Use this mode when the user is mainly asking:
+
+- how does this work internally?
+- why is this reactive?
+- where does this controller/page/component behavior come from?
+- how does render, route state, or lifecycle enter the runtime?
+
+### Workflow
+
+1. read the public Zova-native explanation docs first:
+   - `reading-zova-for-vue-developers.md`
+   - `zova-reactivity-under-the-hood.md`
+2. identify the concrete thread:
+   - page controller
+   - component controller
+   - route/state
+   - model
+   - behavior
+   - SSR
+3. trace the smallest current-source path that confirms the runtime behavior
+4. distinguish source-confirmed behavior from interpretation
+5. only after the Zova-native explanation is clear, add Vue analogy if helpful
+
+### Output emphasis
+
+- entrypoint
+- intermediate runtime files
+- what triggers the behavior
+- what is source-confirmed
+
+## Mode C: Vue-vs-Zova comparison mode
+
+Use this mode when the user is mainly asking:
+
+- how should I understand this relative to Vue 3?
+- is this just Vue with a different syntax?
+- what is the Zova way here?
+
+### Workflow
+
+1. explain the Zova-native architectural role first
+2. identify which public Zova doc best defines that role
+3. if needed, trace one representative source path to confirm the runtime grounding
+4. only then provide Vue analogies as approximate translations
+5. explicitly avoid flattening Zova back into generic Vue habits
+
+### Output emphasis
+
+- Zova-native role
+- closest Vue analogy
+- what is genuinely shared underneath
+- what changes at the authoring-model level
+
+## Combined requests
+
+If a request spans multiple modes, answer in this order:
+
+1. source-location mode
+2. runtime-flow mode
+3. Vue-vs-Zova comparison mode
+
+This keeps the explanation anchored in the real source path before analogy work begins.

package/.claude/skills/cabloy-zova-source-reading/references/core-reading-paths.md

@@ -0,0 +1,117 @@
+# Core Reading Paths
+
+Use this reference to choose the shortest source path after the analysis mode is known.
+
+## Page controller and page reactivity
+
+Read in this order:
+
+1. the concrete page controller source
+2. `zova-core/src/composables/useController.ts`
+3. `zova-core/src/bean/beanContainer.ts`
+4. `zova-core/src/bean/beanBase.ts`
+5. `zova-core/src/bean/beanControllerPageBase.ts`
+6. `zova-core/src/core/context/component.ts`
+7. router integration files such as `a-router/src/monkey.ts`
+
+Use when the question is about:
+
+- plain controller fields
+- `$computed`
+- `$params` / `$query`
+- page render flow
+
+## Component controller and wrapper path
+
+Read in this order:
+
+1. representative wrapper metadata under `src/.metadata/component/`
+2. `zova-core/src/composables/useController.ts`
+3. `zova-core/src/bean/beanControllerBase.ts`
+4. `zova-core/src/core/context/component.ts`
+5. the concrete component controller source
+
+Use when the question is about:
+
+- wrapper components
+- `controllerRef`
+- component-local controller behavior
+
+## Bean lifecycle and helper API path
+
+Read in this order:
+
+1. `zova-core/src/bean/beanBase.ts`
+2. `zova-core/src/bean/beanBaseSimple.ts`
+3. `zova-core/src/bean/beanContainer.ts`
+4. `zova-core/src/core/context/util.ts`
+
+Use when the question is about:
+
+- `__init__`
+- `__dispose__`
+- `$watch`
+- `$toRef`
+- instance scope
+
+## Route and page-shell path
+
+Read in this order:
+
+1. the local `routes.ts`
+2. `a-router/src/monkey.ts`
+3. router utility files
+4. page schema sources
+5. `BeanControllerPageBase`
+
+Use when the question is about:
+
+- route records
+- params/query parsing
+- layout shell implications
+- route-aware controller state
+
+## Model/state ownership path
+
+Read in this order:
+
+1. the relevant model bean
+2. framework model state helper files
+3. representative built-in model beans
+4. consuming page/controller/service code
+
+Use when the question is about:
+
+- model-owned state
+- cache-oriented state
+- async vs sync state ownership
+
+## Behavior path
+
+Read in this order:
+
+1. the public behavior wrapper/controller path
+2. the concrete behavior bean
+3. the behavior composer/service files
+4. host-scoped injected dependencies
+
+Use when the question is about:
+
+- render-time interception
+- behavior composition
+- Behavior vs Component vs Helper
+
+## SSR runtime path
+
+Read in this order:
+
+1. the SSR site or bundle entry
+2. SSR runtime/context files in `zova-core`
+3. relevant page/controller/model code
+4. Vona SSR handoff layer if needed
+
+Use when the question is about:
+
+- SSR entry
+- hydration handoff
+- whether the bug belongs to Vona or Zova

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 5.1.62
+
+### Features
+
+- Add a domain planning skill.
+- Add a masked mobile field to the student resource.
+- Generate an OpenAPI SDK for `demo-student`.
+- Add student summary and force-delete actions.
+- Customize student level renderers.
+- Add the `demo-student` module with a full student CRUD flow.
+
+### Bug Fixes
+
+- Localize the student menu in `zh-cn`.
+- Override the level filter placeholder correctly.
+- Stabilize empty select value mapping.
+- Polish inline select spacing.
+- Forward select blur handling correctly.
+- Refine borderless styling for filter selects.
+- Place explicit schemas last in `demo-student` metadata.
+
+### Improvements
+
+- Clarify level renderer examples.
+- Clarify the standalone tutorial sandbox.
+- Refresh training-student references.
+- Move `demo-student` into the `a-training` suite.
+- Add a suite-first modularization guide.
+- Clarify the thin model facade reading path.
+- Include `demo-student` in the root npm package.
+- Expand source-reading and contract-loop guides.
+- Clean `demo-student` locale resources.
+- Move `TableCell` beans to app scope.
+- Align the student summary query flow.
+- Simplify the student summary action flow.
+- Refine the student level renderer hierarchy.
+- Add a page meta guide and cross-links.
+- Add a rest-resource runtime documentation set.
+- Refine tutorial 4 AI prompt wording.
+- Expand Zova Router ecosystem guides.
+- Add the Zova Table documentation cluster.
+
+## 5.1.61
+
+### Features
+
+- Enforce explicit OpenAPI operation filters.
+- Remove the demo-student module and document the module-removal workflow.
+- Add a mobile field to students and document serializer guidance.
+
+### Bug Fixes
+
+- Decouple test data initialization from application initialization.
+- Refresh the student summary after updates.
+
+### Improvements
+
+- Migrate the contract-loop hook to TypeScript.
+- Harden and simplify contract-loop guidance and gate behavior.
+- Add Zova Form documentation and navigation.
+- Refine ModelResource guidance and examples.
+- Add Zova command scene, fetch interceptor, frontend reading, and Status architecture guides.
+- Update backend contract-sharing tutorial and related skill documentation.
+
 ## 5.1.60
 
 ### Features

package/CLAUDE.md

@@ -42,8 +42,19 @@ Before inventing a custom implementation path:
 ## AI development rules
 
 - Prefer CLI-backed workflows over manual scaffolding whenever Vona or Zova already provides a generator, refactor, metadata, or verification command.
+- The Cabloy contract-loop model applies to both Cabloy Basic and Cabloy Start; detect the edition to choose commands and output paths, not to redefine the workflow model.
+- Treat contract-loop work as one of four branches: forward chain, reverse chain, consumer drift, or local dependency drift.
+- For the forward chain, change backend contract truth first and regenerate frontend consumers rather than hand-patching them.
+- After forward regeneration, keep frontend follow-up thin: prefer semantic model facades and reuse the existing resource-owner when the custom API still belongs to the same resource.
+- For the reverse chain, when Vona consumes newly added or changed Zova Admin render/action/metadata, always run `npm run build:zova:admin` before `npm run deps:vona`. Do not treat `build:rest:cabloyBasicAdmin` alone as sufficient, because the Admin JS bundle and rest output must move together.
+- If generated artifacts already contain the expected changes but consumers still behave stale, suspect local dependency drift before making more source edits.
+- For Vona consumption drift after Zova-generated type/rest output changes, if `npm run deps:vona` still leaves stale consumer types, delete `vona/node_modules` and reinstall dependencies before further debugging or hand-patching dependency links.
+- For Cabloy Start, apply the same reverse-chain logic but resolve the Start-specific flavor names and generated-output paths from the active Start repo before recommending commands.
 - Treat legacy docs as input material, not as unquestioned truth. When docs conflict with source code, prefer current source code.
 - For frontend work, assume Cabloy Basic and Cabloy Start share a frontend engineering layer but may diverge in UI layer, frontend flavors, suite/module availability, SSR site baselines, project assets, and generated outputs.
+- For Zova frontend analysis, do not default to generic Vue reinterpretation first. Read the code through Zova’s controller / bean / IoC architecture before mapping it to Vue concepts.
+- For Zova source-reading or Vue-vs-Zova explanation tasks, start from the frontend reading guides and source-reading map in `cabloy-docs/frontend/` before doing framework-neutral reinterpretation.
+- Keep repo-wide AI rules in `CLAUDE.md` short and durable; put branching Zova analysis workflows in `.claude/skills/`.
 - For SSR theme-sensitive frontend work, detect the active edition marker and UI library before making assumptions. Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions; Cabloy Start currently means Vuetify assumptions.
 - In Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth. Keep theme-sensitive SSR branching hydration-tolerant or defer final theme-sensitive decisions to the client.
 - Do not assume Cabloy Basic and Cabloy Start use the same adapter-level SSR theme handoff. Verify the active theme handler and client hydration path before changing SSR theme behavior.