Cabloy Zova Source Reading

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:

• only __CABLOY_BASIC__ present → this is Cabloy Basic
• only __CABLOY_START__ present → this is Cabloy Start
• both markers present → treat the repository as ambiguous or invalid and stop before making edition-specific assumptions
• neither marker present → inspect the owning package scripts and nearby repository structure, then ask before making an edition-specific assumption

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 repo-docs/frontend/.

Primary reading surfaces

• repo-docs/frontend/reading-zova-for-vue-developers.md
• repo-docs/frontend/zova-vs-vue3-comparison.md
• repo-docs/frontend/zova-reactivity-under-the-hood.md
• repo-docs/frontend/zova-source-reading-map.md
• repo-docs/frontend/page-guide.md
• repo-docs/frontend/component-guide.md
• repo-docs/frontend/css-in-js-guide.md

For compact procedural summaries inside the skill bundle, also use:

• references/analysis-modes.md
• references/core-reading-paths.md

For locale-sensitive schema/form questions, also read:

• repo-docs/frontend/api-schema-guide.md
• repo-docs/frontend/a-openapi-under-the-hood.md
• repo-docs/frontend/form-guide.md
• repo-docs/frontend/zova-form-under-the-hood.md

Core architecture surfaces

Use these when the question needs broader architectural context:

• repo-docs/frontend/introduction.md
• repo-docs/frontend/foundation.md
• repo-docs/frontend/design-principles.md
• repo-docs/frontend/ioc-and-beans.md
• repo-docs/frontend/page-guide.md
• repo-docs/frontend/component-guide.md
• repo-docs/frontend/model-architecture.md
• repo-docs/frontend/page-route-guide.md
• repo-docs/frontend/behavior-guide.md
• repo-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 repo-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.

Locale-sensitive schema and form path

When a translated schema title, renderer, or validation surface remains stale after a locale change, read in this order:

1. the public API Schema Guide and A-OpenAPI Under the Hood guide;
2. the public Form Guide and Zova Form Under the Hood guide when a ZForm consumes the schema;
3. zova/src/suite-vendor/a-zova/modules/a-openapi/src/monkey.ts to verify that the active locale replaces the selected ModelSdk;
4. zova/src/suite-vendor/a-zova/modules/a-openapi/src/model/sdk.ts to inspect selector-scoped schema queries and createApiSchemas(...) facade lifetime;
5. zova/src/suite-vendor/a-zova/modules/a-openapi/src/bean/sys.sdk.ts to verify locale headers and schema caches;
6. the generated API-schema bean and the actual page/model consumer that stores or derives the facade;
7. zova/src/suite-vendor/a-zova/modules/a-form/ only after confirming which schema the form owner supplies, and whether automatic body iteration was replaced by a default body slot.

The key distinction is between a genuinely stale generated contract and a valid schema facade captured from an earlier locale. $computed is only locale-safe when its dependency path reacquires the current schema source; wrapping an old facade or transformed snapshot does not make it current.

Raw-this reactivity boundary

When an author reports that a controller field changed but a TSX render, $computed, or $watch did not react, inspect this lifecycle boundary before recommending framework-neutral rewrites:

1. inspect zova-core/src/bean/beanContainer.ts BeanContainer._prepareBeanInstanceCommon(...) to verify that new BeanClass(...) occurs before the framework exposes the reactive/proxied bean;
2. inspect BeanContainer._initBeanInstance(...) to verify that __init__() is invoked only after preparation;
3. check whether a class-field arrow callback or construction-time bind(this) captured raw this and later writes bean state;
4. distinguish this from a callback created in __init__(), whose lexical this is the exposed bean; and
5. verify whether the dependent render read through that same exposed identity.

State the consequence precisely: a proxy-based TSX render read can track normally, while a mutation through a raw construction-time callback changes the underlying field without notifying that dependency. An unrelated reactive update can later expose the changed value during another render.

Do not summarize this as “arrow functions are non-reactive,” and do not default to ref.value, toRaw, or generic Vue rewrites. Explain the Zova bean lifecycle first; recommend ordinary controller methods for normal actions, or closures created in __init__() only when a stable callback reference is required.

Step 5: Explain Zova-native meaning first

When answering, explain the Zova role first, then add Vue analogies only if they help.