@stechquick/studio-cli 4.2.0-0 → 4.2.0-1

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/ui-kit/knowledge/styling.md

@@ -0,0 +1,177 @@
+# Styling — the `S` (Style) system
+
+> ⚠️ **STOP — before applying any rule below, confirm which style system the target page is on.** Read its root-level `opt.V` (and whether its nodes carry an `S` object): **`opt.V >= 2.0` / has `S` → S system**; **`opt.V` missing or `< 2.0` → legacy**. The two systems are not interchangeable on a page. Unsure how to route? → [index.md Step 0](../index.md).
+>
+> **This file is the `S` track.** `S` does not render on a legacy page — on a **legacy** page instead → [styling-legacy.md](styling-legacy.md). Reference examples from [../examples/style/](../examples/style/) only.
+
+> CSS utility classes are only one mechanism, and **CSS works on Web only**. For the exhaustive schema (every `S` param, editor types, defaults, `SC` inheritance, cross-platform application) see **[../reference/styling-system.md](../reference/styling-system.md)**; the per-component supported `S` params + defaults are in **[../reference/component-styles.json](../reference/component-styles.json)** — the only source to consult when authoring `S`. (Treat that list as generation guidance rather than a hard gate — the editor serializes a few extra composite sub-params beyond it — so when in doubt also check a sibling page or the styling reference.)
+
+> **Why not CSS:** Quick renders on Web, Android, and iOS. CSS exists only on Web. The Style tab serializes into the node's platform-neutral **`S`** object, which each platform applies natively (Web → CSS `@media`+`[q_UID]`; Mobile → flattened to the device's breakpoint range, `col`→flex-basis, via the native bridge). So for cross-platform styling you must use `S`, not a CSS Style File.
+
+## The styling mechanisms — in strict priority order
+
+1. **`S` (Style System)** — per-component design: size, spacing, grid column, flex direction/align/justify, colors, fonts, borders, shadows. This is now the mechanism for *everything* the Style tab does — layout included. Try this first, always.
+2. **`class` prop, Web only, last resort** — if a component's `S` schema (check [../reference/component-styles.json](../reference/component-styles.json)) genuinely has no param for what you need, on **Web** you may set the component's own `class` prop directly. This is a fallback for the rare gap, not a parallel mechanism — don't reach for it before confirming `S` can't do it.
+3. **Style File (CSS), Web only, true last resort** — project-level CSS (`body .v-application …`) and `@font-face`. Only for cross-cutting rules neither `S` nor a component's `class` prop can express (e.g. a pseudo-selector, a project-wide rule, custom fonts).
+
+**`O.layout` (`dOpt`/`class`) is not part of this system** — it is the pre-`S` legacy mechanism. Never author it on an `S`-system page; everything it used to carry (grid width, flex direction, align, justify, spacing) is a `S` param here.
+
+**There is no Mobile fallback past `S`.** `class`/CSS are Web-only (CSS doesn't exist on native; the `class` prop has no native-bridge equivalent either). If a design needs something `S` can't express and the page targets Mobile, restructure with an `S`-capable component instead of reaching for `class`/CSS — there's nothing for the Mobile renderer to apply it from.
+
+Theme colors and fonts defined in **Themes Settings** appear as selectable options inside the Style tab (i.e. as values you put in `S`, not separately).
+
+## A) Style tab → the `S` object
+
+The Style tab writes a node-level **`S`** object keyed by **resolution range**, each holding CSS-like camelCase properties. Example from a real file:
+
+```json
+"S": {
+  "xs-xl": {
+    "marginTop": "", "marginRight": "", "marginBottom": "", "marginLeft": "",
+    "paddingTop": "12px", "paddingRight": "12px", "paddingBottom": "12px", "paddingLeft": "12px",
+    "width": "", "height": "",
+    "fontColor": "#000000", "fontFamily": "Roboto", "fontSize": "16px",
+    "fontStyle": "normal", "fontWeight": "400", "lineHeight": "20px", "textAlign": "left",
+    "backgroundColor": "#FFFFFF", "color": "", "iconColor": "",
+    "boxShadow": "", "boxSizing": "",
+    "borderColor": "", "borderWidth": "", "borderTopStyle": "", "borderRightStyle": ""
+  }
+}
+```
+
+The Style tab is organized into boxes that map to these `S` keys:
+
+| Style-tab box | `S` properties it writes |
+|---------------|--------------------------|
+| **Size** | `width`, `height` (px / % / em / rem) |
+| **Text** | `fontColor`, `fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `lineHeight`, `textAlign` (+ `combinedFont`/`ThemeFont` when a theme/custom font is chosen) |
+| **Appearance** | `backgroundColor`, `color`, `iconColor` (color picker: hex / RGB / HSL); `border*` (`borderColor`, `borderWidth`, `border<side>Style`, `borderRadius`, `boxSizing`); `boxShadow` |
+| **Layout box** | grid column, direction, align, justify, margin, padding — written as `S` params: `col`, `flexDirection`, `alignItems`, `justifyContent`, `marginTop/Right/Bottom/Left`, `paddingTop/Right/Bottom/Left`. Which of these a given component actually supports varies — check that `T`'s block in [../reference/component-styles.json](../reference/component-styles.json) (e.g. only `VCol` carries `flexDirection`/`alignItems`/`justifyContent`/`col`; most containers carry the margin/padding set). |
+
+Notes for authoring `S` by hand:
+- Keys are **resolution ranges**, default full-range `"xs-xl"`. A narrower range (e.g. `"xs-sm"`, `"md-xl"`) targets specific devices — this is "Layout Multiplexing" (see responsive table below). Empty string `""` means "unset" (the Style-tab checkbox unchecked).
+- Sizes accept `px`, `%`, `em`, `rem`.
+- `S` is read by the runtime directly; you usually let the Style tab generate it, but you may hand-write it.
+
+## B) The Layout box → `S` (grid column, direction, align, justify, spacing)
+
+On an `S`-system page, layout is **not** a separate mechanism — the Layout box (Grid Column, Direction, Align, Justify, Box margin/padding) writes into **`S`** like every other Style-tab box: `col` (grid width, 1–12, `VCol`-specific), `flexDirection`/`alignItems`/`justifyContent` (`VCol`-specific), `marginTop/Right/Bottom/Left`, `paddingTop/Right/Bottom/Left` (most containers). Check the component's block in [../reference/component-styles.json](../reference/component-styles.json) for which of these it actually supports before assuming a param exists.
+
+```json
+"S": { "xs-xl": { "flexDirection": "column", "justifyContent": "center", "paddingTop": "16px", "paddingBottom": "16px", "col": "6" } }
+```
+
+> The pre-`S` `O.layout` (`dOpt` + compiled `class`) mechanism for the same intents belongs to the legacy era — never author it on an `S`-system page.
+
+### Responsive breakpoints
+| Key | Device | Range |
+|-----|--------|-------|
+| `xs` | Mobile | 0–600px |
+| `sm` | Tablet | 600–960px |
+| `md` | Laptop | 960–1264px |
+| `lg` | Desktop | 1264–1904px |
+| `xl` | TV | 1904px+ |
+
+`S` is keyed by **ranges** built from these breakpoints (`"xs-xl"`, `"md-xl"`, …). Grid-Column (1–12) lives on `VCol`; Direction → `flexDirection: "row"/"column"`; Justify (start/center/end/space-between/space-around) → `justifyContent` (main axis); Align (start/center/end/stretch/baseline) → `alignItems` (cross axis).
+
+## B2) Styling a child from its parent — `SC` (child-style inheritance)
+
+Some visuals are set on the **parent** and pushed into a typed child — e.g. a button's **label text color** and **icon color**. The node's `SC` maps a parent style param to a child component type's param. **Fill it from data, not from memory: copy the component's `inheritedChildList` block in [../reference/component-styles.json](../reference/component-styles.json) into `SC` as-is** (same shape: `{ styleParam: { ChildType: childParam } }`). Components without an `inheritedChildList` in their JSON block get **no** `SC` — the engine ignores it there.
+
+```json
+{ "T": "VBtn",
+  "S": { "xs-xl": { "fontColor": "#ffffff", "backgroundColor": "#1976D2", /* …full default set per rule S3… */ } },
+  "SC": {
+    "textAlign": { "QLabel": "textAlign" },
+    "textDecorationLine": { "QLabel": "textDecorationLine" },
+    "textDecorationStyle": { "QLabel": "textDecorationStyle" },
+    "textDecorationColor": { "QLabel": "textDecorationColor" },
+    "fontColor": { "VIcon": "iconColor", "QLabel": "fontColor" },
+    "fontStyle": { "QLabel": "fontStyle" },
+    "fontSize": { "QLabel": "fontSize" },
+    "fontFamily": { "QLabel": "fontFamily" },
+    "fontWeight": { "QLabel": "fontWeight" },
+    "combinedFont": { "QLabel": "combinedFont" },
+    "lineHeight": { "QLabel": "lineHeight" },
+    "ThemeFont": { "QLabel": "ThemeFont" },
+    "backgroundColor": { "VIcon": "backgroundColor" },
+    "disabledBackgroundColor": { "VIcon": "disabledBackgroundColor" }
+  },
+  "C": { "default": { "c": [ /* QLabel + VIcon inherit the above */ ], "cType": "slot" } } }
+```
+
+**`SC` complements the child's own `S` — it does not replace it.** Per rule S3 ([s-track.md](../s-track.md)) the child label/icon inside a `VBtn`/`VChip`/`VTabs` **also** carries its own `S` with its full default set from `component-styles.json`, values matched to the design (e.g. a white-text button label writes `fontColor:#ffffff` — not the generic QLabel default `#000000`). This is what the editor itself produces (see the button label in [../examples/style/MMDelay.qjson](../examples/style/MMDelay.qjson)). Keep the parent's `SC` mapping alongside it.
+
+Also: legacy props migrate into `S` per each component's `propMigrateList` — e.g. `VBtn`/`VCard` `color` → `backgroundColor`, `VTextField` `color` → `labelDefaultFontColor`. Prefer setting `S` directly.
+
+## C) Styled Components (`SA`) — reusable named styles
+Create from the Style tab ("Create or Select a Styled Component"), name it, and it becomes reusable across pages; applied components reference it via the node's **`SA`** array. Editing the styled component updates every component using it. Move it into a shared module to reuse across applications. When hand-authoring you normally don't invent `SA` entries — apply them in Studio.
+
+## D) Style File (project CSS) — the older / cross-cutting path
+A project-level CSS file. Because the UI is Vuetify, prefix selectors with `body .v-application`:
+```css
+body .v-application .v-text-field { background: lightgrey; }
+```
+Fonts via `@font-face` with Studio asset references:
+```css
+@font-face { font-family: MyFont; src: url("<<ttf:font-id>>"); }
+```
+For locally-exported projects, custom fonts need the `@font-face` rule added to the CSS file (Google Fonts can be blocked with `blockFontRequest: true` in `settings.yaml`). This, and any other Style File use, is Web-only and a last resort — prefer `S` for per-component styling, full stop.
+
+## Practical guidance for an AI authoring qjson
+
+**The flow, every time you design a screen or place a component:**
+
+1. **Try `S` first.** Look up the component's block in [../reference/component-styles.json](../reference/component-styles.json) and set every param the design needs there — size, spacing, grid `col`, `flexDirection`/`alignItems`/`justifyContent` (where supported), colors, fonts, borders, shadows. This covers the large majority of designs.
+2. **If `S` genuinely has no param for it:**
+   - **Before writing any `class` token:** list every token you intend to use and check [../reference/mapping-S-vuetify-class.md](../reference/mapping-S-vuetify-class.md) for an `S` equivalent. Only tokens with confirmed no `S` equivalent belong in `class`. Never bulk-copy a class string. If `S` and `class` already express the same thing (e.g. `S.height:"100%"` + `class:'fill-height'`), remove the class token — `S` is authoritative.
+   - **Web:** you may set the component's own `class` prop with the surviving tokens — but only as a last resort, with no other option.
+   - **Mobile:** there is **no** `class` alternative. Don't set `class` expecting it to do anything on Mobile — restructure with an `S`-capable component (most commonly wrap in/use a `VCol`, which uniquely supports the flex axis in `S`) instead.
+3. **Style File (CSS)** is the true last resort, Web-only, for cross-cutting rules neither `S` nor a `class` prop can express (pseudo-selectors, project-wide rules, `@font-face`). Confirm with the user before reaching for it on a single component — it usually means a missing `S` param, not a real gap.
+
+- **`O.layout` belongs to the legacy era — never write it on an `S`-system page.** If you are tempted to write `O: { "cType": "slot", "layout": { "dOpt": ... } }`, stop — that is the legacy mechanism, valid only on `V<2` pages. Use `S` here. Reference examples only from [../examples/style/](../examples/style/) — a `O.layout` block means the example came from the legacy set; do not copy it into an `S` page.
+
+- **Vuetify style-affecting props are NOT an alternative to `S`.** Even when a prop appears in `component-contracts.json`, if `S` has an equivalent param, use `S`. Common violations to avoid:
+
+  | Vuetify prop (don't use for style) | Use this instead |
+  | --- | --- |
+  | `VCol.cols` / `VCol.sm` / `VCol.md` / `VCol.lg` / `VCol.xl` | `S.col: "N"` + resolution ranges |
+  | `VRow.justify` / `VRow.align` | Web-only `class` last resort (no S equivalent on VRow) |
+  | `VBtn.color` / `VCard.color` | `S.backgroundColor` |
+  | `VTextField.color` | `S.labelDefaultFontColor` |
+  | `maxWidth` / `minWidth` / `maxHeight` as props | `S.maxWidth` / `S.minWidth` / `S.maxHeight` |
+  | `elevation` prop | `S.boxShadow` |
+
+- **Never leave a component you placed with no `S` at all, and emit every default** — see [s-track.md](../s-track.md) rule S3. A `default` value listed in `component-styles.json` for a param is only the Style-tab's pre-filled suggestion — it is not silently applied unless you write that `S` key yourself. Therefore a placed component's `S` must include **every param that carries a `default` in its `component-styles.json` block** (the default value, or your design's override). Params whose JSON entry has no default (empty `{}`) are optional — set them only when the design needs them.
+- **A multi-child `VCol` does not stack for free.** `VCol` is itself a flex container, but its flex-direction is **not** column unless you set it — left unset it lays children out as a row, so two components dropped straight into a `VCol` render side-by-side instead of stacked (true in both eras — see [layout-and-slots.md](layout-and-slots.md)). The fix here is `S.flexDirection: "column"` on that `VCol` — a real, supported `S` param (the `layout-chooser`/`content-direction` group; see the `VCol` block in [../reference/component-styles.json](../reference/component-styles.json)).
+
+  Canonical **stacked label + value field** (label on top, value/input below):
+
+  ```json
+  { "T": "VCol", "P": { "ID": { "H": "colField", "T": "prop" } },
+    "E": {},
+    "C": { "default": { "c": [
+      { "T": "QLabel", "P": { "ID": { "H": "lblFieldLabel", "T": "prop" }, "text": { "H": "'Field Label'", "T": "prop" } },
+        "E": {}, "C": {}, "O": { "cType": "slot" },
+        "S": { "xs-xl": { "fontColor": "#9AA0A6", "fontSize": "14px", "fontWeight": "400" } },
+        "_Editor": { "eID": "lblFieldLabel" } },
+      { "T": "QLabel", "P": { "ID": { "H": "lblFieldValue", "T": "prop" }, "text": { "H": "'Value'", "T": "prop" } },
+        "E": {}, "C": {}, "O": { "cType": "slot" },
+        "S": { "xs-xl": { "fontColor": "#1B2A4A", "fontSize": "18px", "fontWeight": "700" } },
+        "_Editor": { "eID": "lblFieldValue" } }
+    ], "cType": "slot" } },
+    "O": { "cType": "slot" },
+    "S": { "xs-xl": { "flexDirection": "column", "col": "12" } },
+    "_Editor": { "eID": "colField" } }
+  ```
+
+  `S.flexDirection: "column"` guarantees the stack; `S.col: "12"` controls the width — both live in `S`, nothing here goes through `O.layout`.
+- **Equal-height cards in a row:** `VCard` has no flex `S` params, so on **Web only** this is one of the rare legitimate uses of the `class` last resort — add `d-flex` to the `VCol`'s `class` and `flex-grow-1 d-flex flex-column` to the card's `class` (the `VRow`'s default `alignItems:stretch` already gives the `VCol` full height). There's no Mobile equivalent — accept the card's natural height there, or restructure with an `S`-capable wrapper (`VCol`) doing the stretching instead.
+- When matching a mockup/Figma, encode colors/borders/shadows/spacing/grid/direction all in `S`, and confirm ambiguous choices.
+
+## Common theme utility classes (via `class` prop — Web-only last resort)
+These exist and work on Web, but most have an `S` equivalent that also works on Mobile — always check [../reference/mapping-S-vuetify-class.md](../reference/mapping-S-vuetify-class.md) first and prefer the `S` param (e.g. `fontSize`+`fontWeight` over `text-h5`, `fontColor` over `primary--text`, `borderRadius`/`backgroundColor` over `rounded-lg`/`transparent`, `paddingTop` over `pt-N`, `height:"100%"` over `fill-height`). Only reach for these classes when you specifically need a Web-only effect or are confirmed to not need Mobile parity. Typography: `text-h5`, `text-h6`, `text-body-1`, `text-body-2`, `text-caption` + `font-weight-bold|medium|regular`. Color: `primary`/`primary--text`, `secondary`/`secondary--text`, `success--text`, `error--text`, `white`/`white--text`, `secondary lighten-4`. Card: `rounded-lg`, `transparent` (for a flat card use `S.boxShadow:"none"`, **not** the `elevation` prop — the `elevation` prop is legacy-only). Icons: name in `VIcon.text` (PType `text`).
+
+## Final checklist
+
+The full final checklist (shared core + the `S`-system style checks — `S` on every visual node, no `O.layout`, the `class`-prop audit) is in [validation.md](validation.md). Run it before finishing.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/ui-kit/knowledge/validation-legacy.md

@@ -0,0 +1,49 @@
+# Validation — legacy `cssClass` system
+
+> ⚠️ **STOP — before applying any rule below, confirm which style system the target page is on.** Read its root-level `opt.V` (and whether its nodes carry an `S` object): **`opt.V >= 2.0` / has `S` → S system**; **`opt.V` missing or `< 2.0` → legacy**. The two systems are not interchangeable on a page. Unsure how to route? → [index.md Step 0](../index.md).
+>
+> **This file is the `legacy` track.** Shared-core checks are identical across tracks; only the style checklist (§B) differs. On a new page / `opt.V >= 2.0` instead → [validation.md](validation.md).
+
+The loop: **author or edit the page → self-check & fix → finish clean.** Check your own output and fix errors before the user ever sees them.
+
+## Self-check, and compiler errors
+
+Validation is a checklist discipline: walk §A and §B below and fix every issue before finishing.
+
+The **official Quick compiler** (the same one the Studio editor runs) compiles `pJson → cJson` and reports **QScript/TypeScript syntax & type errors** in your handlers. Whenever compiler output reaches you, treat it as a fix-loop: read the errors, apply every fix yourself, re-check until clean — the compiler never edits the qjson.
+
+## Final checklist
+
+### A) Shared core — every page
+- [ ] Module shape: three authored keys present (`pJson`, `lrids`, `opt`); ends with `};` + `export default pjson`.
+- [ ] `cJson`/`clrids` **absent** — omitted from new files, stripped from any existing file you edited (Studio regenerates the compiled twins on import).
+- [ ] Every node: `T` valid; `P.ID.H` present + unique; `_Editor.eID` present + unique (equal to ID when new; may differ after a Studio rename — not required to match); **`C` present** (use `{}` for leaves — omitting `C` is a validator error).
+- [ ] Props: strings single-quoted in `H`; QScript object literals use `=`; `QLabel.text`=`prop`, `VIcon.text`=`text`.
+- [ ] Events: no native `return` (use `quick.return`); object literals closed with `};`; no browser globals; custom events have `C:true`; `P` matches payload.
+- [ ] Localization: `lrids` per language; keys exist in all languages; `LR` in props / `quick.LR` in events.
+- [ ] Containment: `VCol` only inside `VRow`; `VRow` holds only `VCol`; item components inside their container.
+- [ ] Charts: only `Bar`/`Line`/`Doughnut`; no `visible` on the chart.
+- [ ] Alerts include `actionButtons`.
+
+### B) Legacy style checklist
+- [ ] **No `S` introduced** — it won't render on `V < 2`; design stays in `O.layout` / CSS classes, matching how the page already does it.
+- [ ] `O.layout.dOpt` ↔ `O.layout.class` in sync — recompile `class` per the algorithm in [../reference/layout-system.md](../reference/layout-system.md) after any `dOpt` change (`xs` as-is; `sm/md/lg/xl` infixed).
+- [ ] `class` prop used freely for design (typography/color/spacing/elevation) is expected here — it is the legacy styling mechanism, Web-only, and is NOT audited against `S`.
+
+## `<<qjson:path>>` — inter-page references
+Inter-page references (e.g. `CustomComponent.QJsonPath`) are written as project-relative paths wrapped in `<<qjson:...>>`. In Studio's own model they are stable internal IDs; in files you always write the path form.
+
+**When authoring locally:**
+- Always write `'<<qjson:path>>'` — never a raw model ID.
+- The path is relative to the project root, without the `.qjson` extension (e.g. `<<qjson:sari-buton>>` for a root-level page, `<<qjson:forms/login>>` for a nested one).
+- If you see a UUID-style `<<qjson:...>>` in an existing file, the reference target wasn't found locally — do not copy that ID format into new authoring.
+
+### Renaming / moving / deleting a referenced page — update the referrers yourself
+Locally the link between two pages is the **path/name** inside `<<qjson:path>>`; in Studio it is a stable model id. So on the Studio side a rename/move needs no extra work — but **locally every file that referenced the old path goes stale** and breaks when imported back into Studio. When **you** (the agent) rename, move, or delete a `.qjson`, you must fix the referrers in the same change:
+
+1. **Find referrers first.** Grep the whole project for the target's current path *before* you touch it:
+   `grep -rln "<<qjson:sari-buton>>" .` (use the exact path the referrers use — root-level is just the name, nested is `folder/name`, module-owned is `ModuleName/.../name`, no `.qjson`).
+2. **Rename / move** → replace `<<qjson:oldPath>>` with `<<qjson:newPath>>` in every referrer.
+3. **Delete** → the reference target no longer exists; do not leave a dangling `<<qjson:path>>`. Remove or repoint the component instance that used it in each referrer (e.g. the `CustomComponent` whose `QJsonPath` pointed there), then validate.
+4. **Validate every file you edited** — referrers included, not just the renamed page.
+

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/ui-kit/knowledge/validation.md

@@ -0,0 +1,56 @@
+# Validation — `S` system
+
+> ⚠️ **STOP — before applying any rule below, confirm which style system the target page is on.** Read its root-level `opt.V` (and whether its nodes carry an `S` object): **`opt.V >= 2.0` / has `S` → S system**; **`opt.V` missing or `< 2.0` → legacy**. The two systems are not interchangeable on a page. Unsure how to route? → [index.md Step 0](../index.md).
+>
+> **This file is the `S` track.** Shared-core checks are identical across tracks; only the style checklist (§B) differs. On a **legacy** page instead → [validation-legacy.md](validation-legacy.md).
+
+The loop: **author or edit the page → self-check & fix → finish clean.** Check your own output and fix errors before the user ever sees them.
+
+## Self-check, and the compiler's error codes
+
+Validation is a checklist discipline: walk §A and §B below and fix every issue before finishing.
+
+The **official Quick compiler** (the same one the Studio editor runs) compiles `pJson → cJson` and reports **QScript/TypeScript syntax & type errors** in your handlers, plus structural and `S`-style checks. Whenever compiler output reaches you, treat it as a fix-loop: read the errors, apply every fix yourself, re-check until clean — the compiler never edits the qjson. Its `S`/`SC` style errors each name the exact params so you know precisely what to write:
+
+- **`missing-S` / `incomplete-S`** — the node's `S` lacks default-valued params from the component's [`component-styles.json`](../reference/component-styles.json) block. Fix: add each listed param to the `"xs-xl"` range with its default value from that block (or your design's override) — rule S3. (`VCol.flexDirection` is exempt: its editor default `column` does not match the runtime-unset `row` behavior — write it deliberately when you want stacking, per rule S5.)
+- **`missing-SC` / `incomplete-SC` / `wrong-SC-target` / `unknown-SC*`** — the node's `SC` does not match the component's `inheritedChildList` in `component-styles.json`. Fix: copy that block into `SC` **as-is** (the whole block, never a subset); remove `SC` entirely from components whose block has no `inheritedChildList`.
+- **`unknown-S-param`** — the param doesn't exist for this component; rename per the suggestion or remove it (the compiler silently drops it).
+- **`css-prop-in-S`** — the node sets a prop marked `cssProp: "true"` in [`component-contracts.json`](../reference/component-contracts.json). Those are legacy CSS props: legal on a legacy page, **not** in the `S` system. Fix: remove the prop and express the styling through the component's `S` params. (Components whose block is absent from `component-styles.json` are exempt — with no `S` params, the prop is the only way to style them.)
+
+## Final checklist
+
+### A) Shared core — every page, both style systems
+- [ ] Module shape: three authored keys present (`pJson`, `lrids`, `opt`); ends with `};` + `export default pjson`.
+- [ ] `cJson`/`clrids` **absent** — omitted from new files, stripped from any existing file you edited (Studio regenerates the compiled twins on import).
+- [ ] Every node: `T` valid; `P.ID.H` present + unique; `_Editor.eID` present + unique (equal to ID when new; may differ after a Studio rename — not required to match); **`C` present** (use `{}` for leaves — omitting `C` is a validator error).
+- [ ] Props: strings single-quoted in `H`; QScript object literals use `=`; `QLabel.text`=`prop`, `VIcon.text`=`text`.
+- [ ] Events: no native `return` (use `quick.return`); object literals closed with `};`; no browser globals; custom events have `C:true`; `P` matches payload.
+- [ ] Localization: `lrids` per language; keys exist in all languages; `LR` in props / `quick.LR` in events.
+- [ ] Containment: `VCol` only inside `VRow`; `VRow` holds only `VCol`; item components inside their container.
+- [ ] Charts: only `Bar`/`Line`/`Doughnut`; no `visible` on the chart.
+- [ ] Alerts include `actionButtons`.
+
+### B) `S`-system style checklist
+
+- [ ] Every visually-intentful node has an `S` object (range-keyed); child text/icons via the parent's `SC`. No structure-only nodes.
+- [ ] **No `O.layout`** (`dOpt`/`class`) on any node — grid width, flex direction/align/justify, and spacing all live in `S`.
+- [ ] **Class-prop audit:** if any `class` prop is present, verify each token individually against the `class → S` table in [../reference/styling-system.md](../reference/styling-system.md) §9 (full table: [../reference/mapping-S-vuetify-class.md](../reference/mapping-S-vuetify-class.md)). Tokens that have an `S` equivalent must NOT appear in `class` (e.g. `fill-height` when `S.height:"100%"` is set, `pt-2` when `S.paddingTop:"8px"` is set, `flex-column` when `S.flexDirection:"column"` is set). `class` here is a Web-only last resort, only for tokens with confirmed no `S` equivalent — and has no Mobile effect.
+- [ ] **No CSS props:** no prop marked `cssProp: "true"` in [`../reference/component-contracts.json`](../reference/component-contracts.json) is set on any node — those props are legacy-page-only and do not belong to a component's prop surface here. Express the styling in `S` instead (`VCol.cols/sm/md/lg/xl` → `S.col`; `VBtn/VCard.color` → `S.backgroundColor`; `elevation` → `S.boxShadow`; `height`/`width` → `S.height`/`S.width`; `rounded` → `S.border*Radius`). The only exception is a component with no block in `component-styles.json` — with no `S` params, its props stay the only way to style it.
+
+## `<<qjson:path>>` — inter-page references
+Inter-page references (e.g. `CustomComponent.QJsonPath`) are written as project-relative paths wrapped in `<<qjson:...>>`. In Studio's own model they are stable internal IDs; in files you always write the path form.
+
+**When authoring locally:**
+- Always write `'<<qjson:path>>'` — never a raw model ID.
+- The path is relative to the project root, without the `.qjson` extension (e.g. `<<qjson:sari-buton>>` for a root-level page, `<<qjson:forms/login>>` for a nested one).
+- If you see a UUID-style `<<qjson:...>>` in an existing file, the reference target wasn't found locally — do not copy that ID format into new authoring.
+
+### Renaming / moving / deleting a referenced page — update the referrers yourself
+Locally the link between two pages is the **path/name** inside `<<qjson:path>>`; in Studio it is a stable model id. So on the Studio side a rename/move needs no extra work — but **locally every file that referenced the old path goes stale** and breaks when imported back into Studio. When **you** (the agent) rename, move, or delete a `.qjson`, you must fix the referrers in the same change:
+
+1. **Find referrers first.** Grep the whole project for the target's current path *before* you touch it:
+   `grep -rln "<<qjson:sari-buton>>" .` (use the exact path the referrers use — root-level is just the name, nested is `folder/name`, module-owned is `ModuleName/.../name`, no `.qjson`).
+2. **Rename / move** → replace `<<qjson:oldPath>>` with `<<qjson:newPath>>` in every referrer.
+3. **Delete** → the reference target no longer exists; do not leave a dangling `<<qjson:path>>`. Remove or repoint the component instance that used it in each referrer (e.g. the `CustomComponent` whose `QJsonPath` pointed there), then validate.
+4. **Validate every file you edited** — referrers included, not just the renamed page.
+

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/ui-kit/legacy-track.md

@@ -0,0 +1,29 @@
+# Quick qjson — legacy `cssClass` system track
+
+> **Style system: legacy (`cssClass`).** Follow this guide when the target is a legacy page — root-level `opt.V` missing or `< 2.0`, where the `S` object does not render. If the page is `S`-system (a new page, or `opt.V >= 2.0`), stop and use [s-track.md](s-track.md) instead. Shared workflow, shared docs, and shared rules are in the dispatcher [index.md](index.md); this guide adds the legacy-track doc set and the styling/layout rules. (Note: a **new** page is always `S` — a legacy page is always an existing page you are editing.)
+
+## The legacy-track doc set (open only these + the shared docs)
+- **Schema** → [reference/qjson-schema-legacy.md](reference/qjson-schema-legacy.md)
+- **Structure (start here)** → [knowledge/qjson-structure-legacy.md](knowledge/qjson-structure-legacy.md)
+- **Layout & slots** → [knowledge/layout-and-slots-legacy.md](knowledge/layout-and-slots-legacy.md)
+- **Styling how-to (`O.layout` + CSS classes)** → [knowledge/styling-legacy.md](knowledge/styling-legacy.md)
+- **Layout reference (`dOpt` grammar + `dOpt → class` rule)** → [reference/layout-system.md](reference/layout-system.md)
+- **Component catalog** → [reference/component-catalog-legacy.md](reference/component-catalog-legacy.md)
+- **Page skeletons / structure references** → [knowledge/page-skeletons-legacy.md](knowledge/page-skeletons-legacy.md)
+- **Repeated rows/cards from data** → [knowledge/dynamic-components.md](knowledge/dynamic-components.md)
+- **Validation (final checklist)** → [knowledge/validation-legacy.md](knowledge/validation-legacy.md)
+- **Examples** → [examples/cssClass/](examples/cssClass/) only (the `S` examples in `examples/style/` will mislead you here)
+
+## Edit & style
+1. **You are editing an existing tree.** Keep the page's current root (real legacy pages root on `VContainer`, `VAppBar`, `VDataTable`, …) — do **not** retrofit a `VContainer` root unless the user asks. Match the page's conventions (token style, ID style, `class` usage); reference [knowledge/page-skeletons-legacy.md](knowledge/page-skeletons-legacy.md) and the `examples/cssClass/` pages. For large edits, add **1–3 sections per edit**.
+2. **Style through the two legacy mechanisms — do NOT author `S`** (it won't render on `V < 2`):
+   - **`O.layout`** (`dOpt` + compiled `class`) — grid width (`c:col-N`), flex direction/align/justify (`fd:`/`a:`/`j:`), spacing (`sp:`). Keep `dOpt` and `class` **in sync** (compile rule: `xs` as-is; `sm/md/lg/xl` infix the breakpoint after the first `-`). Grammar + algorithm: [reference/layout-system.md](reference/layout-system.md).
+   - **The `class` prop** — CSS utility classes for typography/color/elevation/rounding, used freely. How-to: [knowledge/styling-legacy.md](knowledge/styling-legacy.md).
+3. **Validate** against [knowledge/validation-legacy.md](knowledge/validation-legacy.md) (shared core + legacy style checklist), then compile.
+
+## Non-negotiable legacy-track rules
+- **L1 — Do NOT introduce `S`.** It won't render on `V < 2` and would silently break styling. Keep all design in `O.layout` / `class`, matching how the page already does it. (A deliberate, full migration to `S` is a separate opt-in task — not an incidental edit.)
+- **L2 — Keep `O.layout.dOpt` and `O.layout.class` in sync.** The runtime applies `class`, so recompile it after any `dOpt` change per the algorithm in [reference/layout-system.md](reference/layout-system.md). Get this wrong and the class won't match the `dOpt`.
+- **L3 — Size columns with `c:col-N`** (1–12; `col-auto`; `0`→`d-none`) in `dOpt` + the synced `col-N` class — not `P.cols` alone (unreliable across editor/runtime).
+- **L4 — `VCol` does not auto-stack children** — add `fd:flex-column` to its `dOpt` (+ synced `flex-column` class) when multiple children must stack.
+- **L5 — Don't retrofit a `VContainer` root** onto an existing page unless the user explicitly asks.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/ui-kit/reference/component-catalog-legacy.md

@@ -0,0 +1,121 @@
+# Component Catalog — `T` Names & Contracts (legacy `cssClass` system)
+
+> **Style system: legacy (`cssClass`).** For legacy pages only — root-level `opt.V` missing or `< 2.0`, where `S` does not render. Component identity (`T` names, props, events) is the same in both eras; only the `VContainer`/`VRow`/`VCol` styling note below is legacy-specific. On a new page, or one with `opt.V >= 2.0`? Use [component-catalog.md](component-catalog.md) instead.
+>
+> Extracted from the Quick runtime's component registry. The machine-readable list lives in [component-index.json](component-index.json). Vuetify components follow Vuetify 2 prop/event/slot semantics unless noted.
+
+## 1. Lifecycle / system (non-visual or embedding)
+
+| `T` | Role |
+|-----|------|
+| `Messaging` | Page event hub. Holds lifecycle hooks (`PreRender`, `EndRender`, `PostRender`, `Restored`) and custom events. Prop `masterPath`; can declare `ExternalProps`/`ExternalEvents`. `O.cType: "child"`. |
+| `CustomComponent` | Embeds another `.qjson` via prop `QJsonPath`; cascades `readonly`/`disabled` to children. `O: { cType:"child", dynProps:true }`. |
+| `RenderingComponent` | Root embedder for a qjson view (props `QJsonPath`, `readonly`, `disabled`). |
+| `Ghost` | Empty placeholder div; used as a structural child / insertion anchor. |
+
+## 2. Charts (Chart.js) — only three exist
+
+| `T` | Notes |
+|-----|-------|
+| `Bar` | vertical/horizontal bars (`indexAxis: 'x'|'y'`) |
+| `Line` | has `fill`, `tension`, point styling |
+| `Doughnut` | `cutoutPercentage: 0` renders a **pie** shape |
+
+> **There is no `Pie` runtime component.** The chart library registers exactly `{ Doughnut, Bar, Line }`. `QPieChart` is a mobile-only placeholder. Use `Doughnut` for pie charts.
+
+Chart prop vocabulary: `labels` (array of axis/segment labels), `data` (number array), `label` (singular dataset name), `backgroundColor`/`borderColor` (array or string), `borderWidth`, `width`/`height`, axis (`xDisplay`/`yDisplay`), legend (`legendDisplay`/`legendPosition`), data labels (`labelDisplay`, ...). Charts have **no `visible` prop** — wrap in a `VCol` and toggle that. Runtime updates: mutate `components.<id>.data` then `(<any>components.<id>).update()`.
+
+## 3. Quick-native components
+
+`QLabel`, `Ghost`, `VContainer`, `VCol`, `VRow` (layout wrappers — note these three layout names are V-prefixed but implemented by Quick), `QFrame`, `QPhoneInput`, `QOtp`, `QMenu`, `QAnimation`, `QVideo`, `QMap`, `QRichText`, `QRichContent`, `QImgZoom`, `QLightBox`, `QDocumentViewer`, `QReCaptcha`, `QTableCell`, `QTutorial`, `QAppointmentCalendar`, `GroupBox`, `InfiniteScroll`, `LiveConnection`, `Tooltip`, `CustomAvatarComp`, `VInlineDatepicker`, `VInlineTimePicker`, `VPdfFileViewer`, `VSubElement`, `GoldenLayout`.
+
+## 4. Vuetify components (V-prefixed)
+
+See [component-index.json](component-index.json) `vuetify` array for the full list (80+). Common: `VBtn`, `VCard`, `VTextField`, `VTextarea`, `VSelect`, `VCombobox`, `VAutocomplete`, `VCheckbox`, `VSwitch`, `VRadio`/`VRadioGroup`, `VSlider`/`VRangeSlider`, `VDataTable`, `VDataIterator`, `VDialog`, `VIcon`, `VImg`, `VChip`, `VAlert`, `VSnackbar`, `VTabs`/`VTab`/`VTabItem`, `VStepper*`, `VExpansionPanel*`, `VPagination`, `VBreadcrumbs`, `VDivider`, `VAvatar`, `VBadge`, `VProgressCircular`/`VProgressLinear`, `VCarousel`/`VCarouselItem`, `VSkeletonLoader`, `VNavigationDrawer`, `VAppBar`, `VToolbar`, `VFooter`, `VSheet`, `VList*`, `VMenu`, `VTooltip`, `VDatePicker`/`VTimePicker`, `VFileInput`, `VRating`, `VSparkline`, `VTreeview`, `VForm`.
+
+## 5. Special Quick props injected on every component
+
+These are handled by the rendering layer, not plain Vuetify props:
+
+| Prop | `T` | Meaning |
+|------|-----|---------|
+| `ID` | `prop` | required unique runtime id; reference as `components.<ID>`. `_Editor.eID` is a separate unique editor id (equal to ID when auto-generated, may differ after rename — not required to match) |
+| `visible` | `prop` | show/hide (injected getter/setter; simple equality expressions allowed) |
+| `Render` | `prop` | if falsey, the component is not rendered at all (`Render:true` + `eager:true` to pre-build dialog contents) |
+| `qValue` | `prop` | Quick value binding; normalized to Vuetify's `value` at render. Use for inputs and to open/close dialogs (`components.dlg.qValue=true`). |
+| `class` | `class` | CSS classes (`T:"class"`) |
+
+> Some Vuetify components map `value` to an internal name (`VTextField`/`VExpansionPanels` → `internalValue`; `VSwitch`/`VCheckbox` → `inputValue`). Setting `qValue` handles this for you — prefer `qValue`.
+
+## 6. Per-component criticals
+
+### `QLabel` — text is a PROP
+```json
+{ "T": "QLabel", "P": {
+    "ID": { "H": "lblTitle", "T": "prop" },
+    "text": { "H": "'Page Title'", "T": "prop" } },
+  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "lblTitle" } }
+```
+`text` uses `T: "prop"`. `HL` defaults to `QS`, so localized/expression text works directly: `"H": "LR('title')"`. Do **not** use `T: "text"` for QLabel.
+
+### `VIcon` — icon name is `text` with PType `"text"` ⚠️
+```json
+{ "T": "VIcon", "P": {
+    "ID": { "H": "icHome", "T": "prop" },
+    "text": { "H": "'mdi-home'", "T": "text" } },
+  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "icHome" } }
+```
+The icon name goes in `text` with **`T: "text"`**. PType `text` renders as slot content, which Vuetify reads as the icon. (This corrects older docs that said `T:"prop"`.)
+
+### `VBtn`
+- No text prop — put a child `QLabel`/`VIcon`/`VImg` in the `default` slot.
+- Flat style: `depressed:true`, `elevation:0`.
+
+### `VCard`
+- Flat style: `elevation:0`. Slots: `default` (+ Vuetify `title`/`subtitle`/`actions`).
+
+### `VContainer` / `VRow` / `VCol`
+- Layout wrappers (Quick-implemented) — the grid is `VContainer > VRow > VCol`. Structural props: `VContainer` has `fluid`, `noGutters`, `eager`. `VCol` carries its own `layout-chooser` (nested flex). See [../knowledge/layout-and-slots-legacy.md](../knowledge/layout-and-slots-legacy.md).
+- **Column width:** `c:col-N` (1–12) in the `VCol`'s `O.layout.dOpt` + the matching `col-N` in the compiled `O.layout.class` (deterministic; `P.cols` alone is not) — see [layout-system.md](layout-system.md).
+- **Do NOT rely on `P.cols` alone** — it is unreliable across editor/runtime. Use `c:col-N` in `dOpt` with the synced class.
+- Flex direction/align/justify come from `dOpt` tokens (`fd:`/`a:`/`j:`) on the node, mirrored into the compiled `class`.
+
+### `VTextField` / inputs
+- `dense:true`, `outlined:true`, usually `hideDetails:true`.
+- Masking via `format` (`T:"attr"`): e.g. `number`, `email`, `iban`, `turkishMobilePhone`, `creditcard`, `regex`, `alphaNumeric`, ... Validation via `rules` (QScript array of `quick.Quick.validation.*`).
+
+### `VSelect` / `VCombobox` / `VAutocomplete`
+- `items` is QScript: `[{text='A', value=1}]` (use `=`). For service data prefer raw items + `itemText`/`itemValue`/`returnObject:true`.
+
+### `VDataTable`
+- `headers` and static `items` are **props** (QScript `=` literals); dynamic rows assigned in a callback (`components.tbl.items = rows;`).
+- Custom cells: scoped slot keyed `item.<columnValue>`, `cType:"scopedSlot"`; `item` is available in child bindings.
+- `click:row` params: `"P": "index:any,row:any"` — `index` is the row data.
+- `itemsPerPage` commonly `10`.
+
+### `VDialog`
+- Open/close: `components.<id>.qValue = true/false`.
+- Add `Render:true` + `eager:true` to access inner components before opening.
+- Non-persistent dialogs: handle `click:outside` to set `qValue=false`.
+
+### `VPagination`
+- `length`/`totalVisible` are string values; `input` handler's first line: `quick.this.qValue = number;` (param `"P":"number:number"`).
+
+### `VChip`
+- `color`: for per-row variation use static colors + sibling toggling with `visible` (so rows aren't blocked on conditional color expressions). Allowed: `default|primary|secondary|accent|success|error|info|warning`.
+
+## 7. Valid props, events & style params per component
+The exhaustive per-component contract is in [component-contracts.json](component-contracts.json). For each prop it gives:
+- `pType` — `prop` / `class` / `text` / `attr` (the qjson kind)
+- `type` — the **value type** (`string`, `boolean`, `number`, `number | string`, `Array<any>`, `Function`, `object`, …)
+- `options` — allowed **enum values** (quoted as they appear in `H`, e.g. `color`: `'primary'`,`'secondary'`,…)
+- `default` — the editor default
+- `cssProp` — This decides whether the prop is legal in the **S style system**. In **legacy (css) style qjsons** the prop is always usable, regardless of its `cssProp` value.
+
+And the component's **events** as `{ name, params?: [{name, type}] }` — the real event names plus the exact param signature to put in a handler's `P` (e.g. `VDataTable.click:row` → `index:any, row:IVDataTableClickRow`). Use it to pick a real prop/event, the right value **type and quoting** (a `boolean` is bare `true`, not `'true'`), valid enum values, and correct handler params. Treat it as the safe subset (real prop/event, correct PType, unquoted boolean); `options` are guidance. Regenerated from the Quick runtime sources when the runtime changes.
+
+**Style params** live in [component-styles.json](component-styles.json) — per `T`, the Style-tab (`S`) params the component supports, each with value `type` and editor `default`. Read it before writing `S` so you only set supported params (generation guidance; not hard-validated, since the editor expands composite border/shadow/font widgets into extra sub-params).
+
+## 8. Editor names vs runtime names
+
+The web editor may present friendlier names (e.g. "Text/Label" for `QLabel`, "Button" for `VBtn`). When **authoring the `T` field**, always use the runtime name from [component-index.json](component-index.json). When unsure whether a `T` is valid, check that file.

package/dist/studio-cli/kits/wf-app-kit/.ai-kit/ui-kit/reference/component-catalog.md

@@ -0,0 +1,140 @@
+# Component Catalog — `T` Names & Contracts (`S` system)
+
+> **Style system: `S` (new).** For `S`-system pages only — a new page, or one whose root-level `opt.V >= 2.0`. Component identity (`T` names, props, events) is the same in both eras; only the `VContainer`/`VRow`/`VCol` styling note below is `S`-specific. Editing a **legacy** page (`opt.V` missing or `< 2.0`)? Use [component-catalog-legacy.md](component-catalog-legacy.md) instead.
+>
+> Extracted from the Quick runtime's component registry. The machine-readable list lives in [component-index.json](component-index.json). Vuetify components follow Vuetify 2 prop/event/slot semantics unless noted.
+
+## 1. Lifecycle / system (non-visual or embedding)
+
+| `T` | Role |
+|-----|------|
+| `Messaging` | Page event hub. Holds lifecycle hooks (`PreRender`, `EndRender`, `PostRender`, `Restored`) and custom events. Prop `masterPath`; can declare `ExternalProps`/`ExternalEvents`. `O.cType: "child"`. |
+| `CustomComponent` | Embeds another `.qjson` via prop `QJsonPath`; cascades `readonly`/`disabled` to children. Two distinct usages — see § 6 below. |
+| `RenderingComponent` | Root embedder for a qjson view (props `QJsonPath`, `readonly`, `disabled`). |
+| `Ghost` | Empty placeholder div; used as a structural child / insertion anchor. |
+
+## 2. Charts (Chart.js) — only three exist
+
+| `T` | Notes |
+|-----|-------|
+| `Bar` | vertical/horizontal bars (`indexAxis: 'x'|'y'`) |
+| `Line` | has `fill`, `tension`, point styling |
+| `Doughnut` | `cutoutPercentage: 0` renders a **pie** shape |
+
+> **There is no `Pie` runtime component.** The chart library registers exactly `{ Doughnut, Bar, Line }`. `QPieChart` is a mobile-only placeholder. Use `Doughnut` for pie charts.
+
+Chart prop vocabulary: `labels` (array of axis/segment labels), `data` (number array), `label` (singular dataset name), `backgroundColor`/`borderColor` (array or string), `borderWidth`, `width`/`height`, axis (`xDisplay`/`yDisplay`), legend (`legendDisplay`/`legendPosition`), data labels (`labelDisplay`, ...). Charts have **no `visible` prop** — wrap in a `VCol` and toggle that. Runtime updates: mutate `components.<id>.data` then `(<any>components.<id>).update()`.
+
+## 3. Quick-native components
+
+`QLabel`, `Ghost`, `VContainer`, `VCol`, `VRow` (layout wrappers — note these three layout names are V-prefixed but implemented by Quick), `QFrame`, `QPhoneInput`, `QOtp`, `QMenu`, `QAnimation`, `QVideo`, `QMap`, `QRichText`, `QRichContent`, `QImgZoom`, `QLightBox`, `QDocumentViewer`, `QReCaptcha`, `QTableCell`, `QTutorial`, `QAppointmentCalendar`, `GroupBox`, `InfiniteScroll`, `LiveConnection`, `Tooltip`, `CustomAvatarComp`, `VInlineDatepicker`, `VInlineTimePicker`, `VPdfFileViewer`, `VSubElement`, `GoldenLayout`.
+
+## 4. Vuetify components (V-prefixed)
+
+See [component-index.json](component-index.json) `vuetify` array for the full list (80+). Common: `VBtn`, `VCard`, `VTextField`, `VTextarea`, `VSelect`, `VCombobox`, `VAutocomplete`, `VCheckbox`, `VSwitch`, `VRadio`/`VRadioGroup`, `VSlider`/`VRangeSlider`, `VDataTable`, `VDataIterator`, `VDialog`, `VIcon`, `VImg`, `VChip`, `VAlert`, `VSnackbar`, `VTabs`/`VTab`/`VTabItem`, `VStepper*`, `VExpansionPanel*`, `VPagination`, `VBreadcrumbs`, `VDivider`, `VAvatar`, `VBadge`, `VProgressCircular`/`VProgressLinear`, `VCarousel`/`VCarouselItem`, `VSkeletonLoader`, `VNavigationDrawer`, `VAppBar`, `VToolbar`, `VFooter`, `VSheet`, `VList*`, `VMenu`, `VTooltip`, `VDatePicker`/`VTimePicker`, `VFileInput`, `VRating`, `VSparkline`, `VTreeview`, `VForm`.
+
+## 5. Special Quick props injected on every component
+
+These are handled by the rendering layer, not plain Vuetify props:
+
+| Prop | `T` | Meaning |
+|------|-----|---------|
+| `ID` | `prop` | required unique runtime id; reference as `components.<ID>`. `_Editor.eID` is a separate unique editor id (equal to ID when auto-generated, may differ after rename — not required to match) |
+| `visible` | `prop` | show/hide (injected getter/setter; simple equality expressions allowed) |
+| `Render` | `prop` | if falsey, the component is not rendered at all (`Render:true` + `eager:true` to pre-build dialog contents) |
+| `qValue` | `prop` | Quick value binding; normalized to Vuetify's `value` at render. Use for inputs and to open/close dialogs (`components.dlg.qValue=true`). |
+| `class` | `class` | CSS classes (`T:"class"`) |
+
+> Some Vuetify components map `value` to an internal name (`VTextField`/`VExpansionPanels` → `internalValue`; `VSwitch`/`VCheckbox` → `inputValue`). Setting `qValue` handles this for you — prefer `qValue`.
+
+## 6. Per-component criticals
+
+### `CustomComponent` — two distinct usages
+
+**A. Block Component (UI embedding)** — the standard way to embed another page as a UI block. Placed at `pJson` root level (not inside VContainer). Minimal node — no Ghost, no `dynProps`.
+```json
+{ "T": "CustomComponent", "P": {
+    "ID": { "H": "blockMyPage", "T": "prop" },
+    "QJsonPath": { "H": "'<<qjson:path/to/page>>'", "T": "prop" } },
+  "E": {}, "C": {}, "O": {}, "_Editor": { "eID": "blockMyPage" } }
+```
+The embedded page must itself be a block component in Studio — if it isn't one yet, it must be converted on the Studio side via the workspace's tooling (details: [knowledge/components.md](../knowledge/components.md#block-component-embedding-another-qjson-page)). Does not apply to usage B.
+
+**B. Service Caller (project-specific proxy)** — only if the project provides a dedicated service-caller qjson. Has event handlers, a `Ghost` child, and `O: { cType:"child", dynProps:true }`. See [services.md](../knowledge/services.md) Pattern B.
+
+**`QJsonPath` format:** always `'<<qjson:path>>'` where `path` is the page's project-relative path without extension (e.g. `<<qjson:sari-buton>>` for a root-level page, `<<qjson:folder/page-name>>` for a nested one). Studio stores model IDs internally; in files you always write the path form — never a raw model ID.
+
+### `QLabel` — text is a PROP
+```json
+{ "T": "QLabel", "P": {
+    "ID": { "H": "lblTitle", "T": "prop" },
+    "text": { "H": "'Page Title'", "T": "prop" } },
+  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "lblTitle" } }
+```
+`text` uses `T: "prop"`. `HL` defaults to `QS`, so localized/expression text works directly: `"H": "LR('title')"`. Do **not** use `T: "text"` for QLabel.
+
+### `VIcon` — icon name is `text` with PType `"text"` ⚠️
+```json
+{ "T": "VIcon", "P": {
+    "ID": { "H": "icHome", "T": "prop" },
+    "text": { "H": "'mdi-home'", "T": "text" } },
+  "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "icHome" } }
+```
+The icon name goes in `text` with **`T: "text"`**. PType `text` renders as slot content, which Vuetify reads as the icon. (This corrects older docs that said `T:"prop"`.)
+
+### `VBtn`
+- No text prop — put a child `QLabel`/`VIcon`/`VImg` in the `default` slot.
+- Flat style: set `S.boxShadow:"none"` (on an `S` page, not the `elevation`/`depressed` props).
+
+### `VCard`
+- Flat style: set `S.boxShadow:"none"` (on an `S` page, not the `elevation` prop). Slots: `default` (+ Vuetify `title`/`subtitle`/`actions`).
+
+### `VContainer` / `VRow` / `VCol`
+- Layout wrappers (Quick-implemented) — the grid is `VContainer > VRow > VCol`. Structural props: `VContainer` has `fluid`, `eager`. `VCol` is the one component whose flex axis (`flexDirection`/`alignItems`/`justifyContent`) is controllable as a real style param — see [../knowledge/layout-and-slots.md](../knowledge/layout-and-slots.md).
+- **Column width:** `S.col` on the `VCol` (1–12, range-keyed, e.g. `"xs-xl": {"col":"3"}`) — see [styling-system.md](styling-system.md).
+- **Do NOT use Vuetify responsive column props** (`VCol.cols`/`.sm`/`.md`/`.lg`/`.xl`): they set width via the Vuetify prop system, which `S` does not read. Use `S.col` + resolution ranges.
+- **Do NOT use `VRow.justify`/`VRow.align` props** as design intent — `VRow` exposes no `justifyContent`/`alignItems` `S` param; put alignment on a `VCol` (which supports those params), or fall back to the Web-only `class` last resort.
+
+### `VTextField` / inputs
+- usually `hideDetails:true`.
+- Masking via `format` (`T:"attr"`): e.g. `number`, `email`, `iban`, `turkishMobilePhone`, `creditcard`, `regex`, `alphaNumeric`, ... Validation via `rules` (QScript array of `quick.Quick.validation.*`).
+
+### `VSelect` / `VCombobox` / `VAutocomplete`
+- `items` is QScript: `[{text='A', value=1}]` (use `=`). For service data prefer raw items + `itemText`/`itemValue`/`returnObject:true`.
+
+### `VDataTable`
+- `headers` and static `items` are **props** (QScript `=` literals); dynamic rows assigned in a callback (`components.tbl.items = rows;`).
+- Custom cells: scoped slot keyed `item.<columnValue>`, `cType:"scopedSlot"`; `item` is available in child bindings.
+- `click:row` params: `"P": "index:any,row:any"` — `index` is the row data.
+- `itemsPerPage` commonly `10`.
+
+### `VDialog`
+- Open/close: `components.<id>.qValue = true/false`.
+- Add `Render:true` + `eager:true` to access inner components before opening.
+- Non-persistent dialogs: handle `click:outside` to set `qValue=false`.
+
+### `VPagination`
+- `length`/`totalVisible` are string values; `input` handler's first line: `quick.this.qValue = number;` (param `"P":"number:number"`).
+
+// BB 
+### `VChip`
+- `color`: for per-row variation use static colors + sibling toggling with `visible` (so rows aren't blocked on conditional color expressions). Allowed: `default|primary|secondary|accent|success|error|info|warning`.
+
+## 7. Valid props, events & style params per component
+The exhaustive per-component contract is in [component-contracts.json](component-contracts.json). For each prop it gives:
+- `pType` — `prop` / `class` / `text` / `attr` (the qjson kind)
+- `type` — the **value type** (`string`, `boolean`, `number`, `number | string`, `Array<any>`, `Function`, `object`, …)
+- `options` — allowed **enum values** (quoted as they appear in `H`, e.g. `color`: `'primary'`,`'secondary'`,…)
+- `default` — the editor default
+- `cssProp` — `"true"` when the prop is a **legacy css/styling property**. This decides whether the prop is legal in the **S style system**:
+  - `cssProp: "true"` → the prop **cannot** be used in the S style system (styling must be expressed through S).
+  - `cssProp` is `"false"` **or absent** → the prop **can** be used in the S style system.
+  - In **legacy (css) style qjsons** the prop is always usable, regardless of its `cssProp` value.
+
+And the component's **events** as `{ name, params?: [{name, type}] }` — the real event names plus the exact param signature to put in a handler's `P` (e.g. `VDataTable.click:row` → `index:any, row:IVDataTableClickRow`). Use it to pick a real prop/event, the right value **type and quoting** (a `boolean` is bare `true`, not `'true'`), valid enum values, and correct handler params. Treat it as the safe subset (real prop/event, correct PType, unquoted boolean); `options` are guidance. Regenerated from the Quick runtime sources when the runtime changes.
+
+**Style params** live in [component-styles.json](component-styles.json) — per `T`, the Style-tab (`S`) params the component supports, each with value `type` and editor `default`. Read it before writing `S` so you only set supported params (generation guidance; not hard-validated, since the editor expands composite border/shadow/font widgets into extra sub-params).
+
+## 8. Editor names vs runtime names
+
+The web editor may present friendlier names (e.g. "Text/Label" for `QLabel`, "Button" for `VBtn`). When **authoring the `T` field**, always use the runtime name from [component-index.json](component-index.json). When unsure whether a `T` is valid, check that file.