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

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

@@ -0,0 +1,77 @@
+# Properties (`P`)
+
+Each prop is `{ "H": value/expression, "T": kind, "HL": language? }`.
+
+```json
+"P": {
+  "ID":      { "H": "btnSave",      "T": "prop" },
+  "color":   { "H": "'primary'",    "T": "prop" },
+  "visible": { "H": "true",         "T": "prop" },
+  "class":   { "H": "'rounded-lg'", "T": "class" },
+  "items":   { "H": "[{text='A', value=1}]", "T": "prop", "HL": "QS" }
+}
+```
+
+## `T` — prop kind (PType)
+| `T` | Applied as | Use for |
+|-----|-----------|---------|
+| `"prop"` | Vue prop | the default case incl. `QLabel.text`, `items`, `color`, `visible` |
+| `"class"` | CSS class | `class` |
+| `"text"` | slot text content | `VIcon` icon name; raw text — `H` is still a QScript string, so single-quote it: `"'mdi-home'"` |
+| `"attr"` | DOM attribute | `data-*`, `aria-*`, input `format` masks |
+
+## `HL` — language (defaults to `QS`)
+`HL` is optional and **defaults to QScript**. Set `"HL": "TS"` only if a prop expression needs TypeScript (rare — props are usually QScript). The vast majority of real props omit `HL` and are therefore QScript.
+
+## Quoting inside `H`
+| Value | Write | Example |
+|-------|-------|---------|
+| string | single-quoted | `"'primary'"` |
+| number / bool | bare | `"10"`, `"true"` |
+| expression / binding | bare | `"item.name"`, `"data.title"`, `"components.x.qValue"` |
+| array | bracketed | `"[1,2,3]"`, `"['Jan','Feb']"` |
+| object array (QScript) | `=` keys | `"[{text='A', value=1}]"` |
+
+Apostrophe inside a QScript string → double it: `'Premium''u Keşfet'`.
+
+## QScript expression power (corrected vs older docs)
+Prop `H` values are **QScript expressions** and **can include conditionals**. Real files do this routinely:
+
+```json
+"color": {
+  "H": "if(data.statusColor == 1){'red'}else if(data.statusColor == 2){'orange'}else{'blue'}",
+  "T": "prop"
+}
+```
+The `if/else` block returns the last evaluated value — conditionals are fully supported in props.
+
+Available bare in QScript props: `LR(...)`, `components.*`, `data.*` (in dynamic templates), `item.*` (in scoped slots), `Math`, `Date`, `Number`, `JSON`, `string`, `regex`, `typeOf`. Framework namespaces drop the `quick.` prefix: `store.get('x')`, `Quick.go(...)`, `MM.trigger(...)`. See [reference/quick-api.md](../reference/quick-api.md) for the full list.
+
+> **QScript ≠ JS in two key ways:** (1) `||` returns a boolean, not a fallback value — use `if(a){a}else{b}` for a conditional fallback. (2) Property access is always null-safe (`a.b.c` won't throw if `a` is undefined), so `|| ''` guards are both wrong and unnecessary.
+
+### When to still pre-compute instead of expression-in-prop
+Conditionals work, but for **heavy** per-row formatting (date parsing, concatenation, lookups across rows) it's cleaner and faster to pre-format in the service/load callback and read a plain field in the prop:
+
+```typescript
+rows.forEach(r => { r.displayDate = quick.Quick.toShortDate(quick.Quick.toDate(r.date)); });
+components.tbl.items = rows;
+```
+```json
+"text": { "H": "item.displayDate", "T": "prop" }
+```
+This keeps prop expressions simple and avoids repeating logic per render.
+
+## Localization in props
+Use bare `LR('key')` (never `quick.LR` in a prop):
+```json
+"text": { "H": "LR('save')", "T": "prop" }
+```
+See [localization.md](localization.md).
+
+## Special Quick props
+`ID` (required, unique), `visible`, `Render`, `qValue`, `class` — see your track's component catalog §5 ([S](../reference/component-catalog.md) / [legacy](../reference/component-catalog-legacy.md)). Use `qValue` for input values and to open/close dialogs.
+
+## The two text gotchas
+- `QLabel.text` → `T: "prop"`.
+- `VIcon` icon name → `text` with `T: "text"`. The `H` value is still a QScript string — always single-quote it: `"H": "'mdi-home'"`, never bare `"H": "mdi-home"`.
+(See your track's catalog §6.)

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/qjson-structure-legacy.md

@@ -0,0 +1,65 @@
+# QJSON Structure (start here) — 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** (`opt.V` missing or `< 2.0`, where `S` does not render). Design is authored through `O.layout` (`dOpt` + compiled `class`) and CSS utility classes. On a new page / `opt.V >= 2.0` instead → [qjson-structure.md](qjson-structure.md). (A new page is always `S`, so legacy = an existing page you are editing.)
+
+A `.qjson` file is a **JavaScript module** describing one UI page as a tree of components. You author `pJson` (the tree) and `lrids` (localization); the editor/compiler generates the compiled twins `cJson`/`clrids`.
+
+```javascript
+let pjson = {
+  "pJson": [ /* component tree — you write this */ ],
+  "lrids": {},     // localization you write
+  "opt": {}        // page options (QL default language, V version)
+};
+export default pjson
+```
+
+Rules: an AI-authored file carries these **three** keys (`pJson`, `lrids`, `opt`); the file ends with `};` then `export default pjson`. The compiled twins `cJson`/`clrids` are **omitted entirely** — don't write them into a new file, and strip them from any existing file you edit (see "What you never author" below). Full envelope (incl. optional `description`, `files`, `namedViews`, `opt.QL/V`) is in [reference/qjson-schema-legacy.md](../reference/qjson-schema-legacy.md).
+
+## The component node — same six fields at every depth
+
+```json
+{
+  "T": "ComponentType",
+  "P": { "ID": { "H": "myId", "T": "prop" } },
+  "E": {},
+  "C": {},
+  "O": { "cType": "slot" },
+  "_Editor": { "eID": "myId" }
+}
+```
+
+| Field | Holds | Detailed in |
+|-------|-------|-------------|
+| `T` | component type name | [reference/component-catalog-legacy.md](../reference/component-catalog-legacy.md) |
+| `P` | props | [properties.md](properties.md) |
+| `E` | events | [events-and-scripting.md](events-and-scripting.md) |
+| `C` | children grouped by slot | [layout-and-slots-legacy.md](layout-and-slots-legacy.md) |
+| `O` | options: `cType` (always authored) **and `layout`** (`dOpt`/`class`) — `layout` is where grid/flex/spacing design lives on a legacy page | [layout-and-slots-legacy.md](layout-and-slots-legacy.md) |
+| `_Editor.eID` | equals `P.ID.H` when auto-generated, but **may differ** after a Studio rename — equality is *not* required (both must be present + unique) | this file |
+
+`CP`, `D`, `SA` are advanced editor-managed fields you normally don't hand-author. **`S`/`SC` are the modern Style-tab fields and do NOT render on a legacy page — do not author them here.** Design instead through `O.layout` and the `class` prop — see [styling-legacy.md](styling-legacy.md). Introducing `S` on a legacy page silently breaks styling.
+
+## The ID rules
+1. Every component has `P.ID.H`, **unique** within the page.
+2. Every component has `_Editor.eID`, also **unique**.
+3. `P.ID.H` is the runtime/reference id (`components.<ID>`); `_Editor.eID` is the editor's stable internal id.
+
+These two are **equal for auto-generated components** (both `EdtrComp_42`) but legitimately **differ** once the ID is renamed in Studio (e.g. `ID:"btnSave"`, `eID:"EdtrComp_42"`) — real files contain both cases, so a mismatch is **not** an error. When you hand-author a new component, the simplest valid choice is to set `eID` = `ID` (one unique value). Never reuse an `eID` or an `ID`.
+
+## Structure (editing an existing legacy page)
+A legacy page already has its root and tree (real pages legitimately root on `VContainer`, `VAppBar`, `VDataTable`, etc.). You are editing that tree, not starting fresh — **keep the current root** and do **not** insert a `VContainer` root unless the user explicitly asks. The canonical grid, where present, is:
+
+```
+pJson
+ ├─ Messaging            (event hub; no UI)
+ ├─ [service component]  (optional; only if the project uses one)
+ └─ <existing root>      (VContainer / VAppBar / VDataTable / …)
+     └─ VRow → VCol → VCard → content (labels, buttons, tables, inputs, charts)
+```
+
+For each node decide, in order: `T` → `P` → `E` → `C` → `O` (`cType` + `layout`) → copy ID into `_Editor.eID`. Mirror the page's existing conventions (token style, `class` usage). Reference legacy structures in [page-skeletons-legacy.md](page-skeletons-legacy.md) and the `examples/cssClass/` pages.
+
+## What you never author
+`cJson` and `clrids` are **compiled output** (handler strings get wrapped in `╬…╩╩` sentinels). Author `pJson`/`lrids` only, and **leave the compiled twins out of the file entirely** — don't write them into a new page, and strip them if the file already has them. Studio/the compiler regenerates them on import — see [validation-legacy.md](validation-legacy.md).

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/qjson-structure.md

@@ -0,0 +1,67 @@
+# QJSON Structure (start here) — `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** (new page, or `opt.V >= 2.0`). Design — visual **and** layout — is authored in each node's `S` object; `O.layout` is not authored here. On a **legacy** page instead → [qjson-structure-legacy.md](qjson-structure-legacy.md).
+
+A `.qjson` file is a **JavaScript module** describing one UI page as a tree of components. You author `pJson` (the tree) and `lrids` (localization); the editor/compiler generates the compiled twins `cJson`/`clrids`.
+
+```javascript
+let pjson = {
+  "pJson": [ /* component tree — you write this */ ],
+  "lrids": {},     // localization you write
+  "opt": { "V": 2.5 }  // page options — a NEW page sets V to the current schema version (2.5); this marks it as S-system
+};
+export default pjson
+```
+
+Rules: an AI-authored file carries these **three** keys (`pJson`, `lrids`, `opt`); the file ends with `};` then `export default pjson`. The compiled twins `cJson`/`clrids` are **omitted entirely** — don't write them into a new file, and strip them from any existing file you edit (see "What you never author" below). Full envelope (incl. optional `description`, `files`, `namedViews`, `opt.QL/V`) is in [reference/qjson-schema.md](../reference/qjson-schema.md).
+
+## The component node — same six fields at every depth
+
+```json
+{
+  "T": "ComponentType",
+  "P": { "ID": { "H": "myId", "T": "prop" } },
+  "E": {},
+  "C": {},
+  "O": { "cType": "slot" },
+  "_Editor": { "eID": "myId" }
+}
+```
+
+| Field | Holds | Detailed in |
+|-------|-------|-------------|
+| `T` | component type name | [reference/component-catalog.md](../reference/component-catalog.md) |
+| `P` | props | [properties.md](properties.md) |
+| `E` | events | [events-and-scripting.md](events-and-scripting.md) |
+| `C` | children grouped by slot | [layout-and-slots.md](layout-and-slots.md) |
+| `O` | options: `cType` (always authored). The `layout` sub-field (`dOpt`/`class`) is the legacy mechanism — **not authored here**; grid/flex/spacing go in `S` | [layout-and-slots.md](layout-and-slots.md) |
+| `_Editor.eID` | equals `P.ID.H` when auto-generated, but **may differ** after a Studio rename — equality is *not* required (both must be present + unique) | this file |
+
+`CP`, `D`, `SA` are advanced editor-managed fields you normally don't hand-author. **`S`/`SC` are the exception: you must hand-author them** — see [s-track.md](../s-track.md) rule S3 and [styling.md](styling.md). A component left without an `S` (when it carries visual or layout-flow intent) is the most common authoring miss, not an optional editor step.
+
+## The ID rules
+1. Every component has `P.ID.H`, **unique** within the page.
+2. Every component has `_Editor.eID`, also **unique**.
+3. `P.ID.H` is the runtime/reference id (`components.<ID>`); `_Editor.eID` is the editor's stable internal id.
+
+These two are **equal for auto-generated components** (both `EdtrComp_42`) but legitimately **differ** once the ID is renamed in Studio (e.g. `ID:"btnSave"`, `eID:"EdtrComp_42"`) — real files contain both cases, so a mismatch is **not** an error. When you hand-author a new component, the simplest valid choice is to set `eID` = `ID` (one unique value). Never reuse an `eID` or an `ID`.
+
+## Build order (top-down)
+```
+pJson
+ ├─ Messaging            (event hub; no UI)
+ ├─ [service component]  (optional; only if the project uses one)
+ └─ VContainer           (layout root)
+     └─ VRow → VCol → VCard → content (labels, buttons, tables, inputs, charts)
+```
+
+For each node decide, in order: `T` → `P` → `E` → `C` → `O` → copy ID into `_Editor.eID`.
+
+> **New page: the `VContainer` layout root is required, not optional.** Wrap all UI/visual content in a single top-level `VContainer`; the only non-`VContainer` top-level `pJson` siblings allowed are `Messaging` (event hub) and an optional service component. This applies to **new pages only** — when editing an existing page, keep its current root and do **not** insert a `VContainer` unless the user explicitly asks (see [s-track.md](../s-track.md) rule S4).
+
+Copy a full starting skeleton from [page-skeletons.md](page-skeletons.md).
+
+## What you never author
+`cJson` and `clrids` are **compiled output** (handler strings get wrapped in `╬…╩╩` sentinels). Author `pJson`/`lrids` only, and **leave the compiled twins out of the file entirely** — don't write them into a new page, and strip them if the file already has them. Studio/the compiler regenerates them on import — see [validation.md](validation.md).

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

@@ -0,0 +1,68 @@
+# Services (REST)
+
+Two patterns. **Check existing project pages first** and follow whichever the project uses.
+
+## Pattern A — `quick.Request.async` (framework-native, default)
+Call from any event; success/fail route to custom events on the same component (usually `Messaging`).
+
+```typescript
+let req = <any>{};
+req.url = '/api/products/list';
+req.http = 'GET';                 // GET|POST|PUT|DELETE|PATCH|MULTIPART|POSTBLOB|GETBLOB
+req.data = null;                  // body for POST/PUT
+req.blockRender = false;
+req.responseField = 'productList';
+req.onSuccess = 'onProductsSuccess';
+req.onFail = 'onProductsFail';
+quick.Request.async(req);
+```
+
+Read the result in the success event as `response.<responseField>`:
+```json
+"onProductsSuccess": {
+  "H": "if (response.productList != null) {\r\n  let resData = response.productList;\r\n  components.tblProducts.items = resData.resultList;\r\n}\r\n",
+  "C": true, "HL": "TS"
+}
+"onProductsFail": {
+  "H": "quick.Quick.alert({ title:'Hata', text:'İstek başarısız', category:'Error', actionButtons:[{ name:'Tamam', type:'Confirm' }] });\r\n",
+  "C": true, "HL": "TS"
+}
+```
+
+`IRequest` fields: `url`, `http`, `data`, `responseField`, `onSuccess`, `onFail`, `blockRender`, `showSuccessMessage`, `showErrorMessage`, `headers`, `withCredentials`, `timeout`, `args`. Inline `await` form also works:
+```typescript
+const respo = await quick.Request.async(req);
+let result = (<any>respo).data;
+```
+
+## Pattern B — project ServiceCaller `CustomComponent`
+Some projects centralize calls in a reusable `CustomComponent` (a service proxy) with `onLoad` / `onServiceSuccessCallBack` / `onServiceFailCallBack`. Use it **only if the project already provides one** (copy its `QJsonPath` from an existing page).
+
+```json
+{ "T": "CustomComponent", "P": {
+    "ID": { "H": "serviceCallerComp", "T": "prop" },
+    "QJsonPath": { "H": "'<<qjson:path/to/ServiceCallerCustomComponent>>'", "T": "prop" } },
+  "E": {
+    "onLoad": { "H": "quick.store.set('page', 0);\r\nquick.MM.trigger('getProducts', [{ page: 0 }]);\r\n", "HL": "TS" },
+    "onServiceSuccessCallBack": { "H": "/* capture → null → process */", "C": true, "P": "serviceResponse:any", "HL": "TS" },
+    "onServiceFailCallBack": { "H": "/* alert with actionButtons */", "C": true, "P": "serviceResponse:any", "HL": "TS" }
+  },
+  "C": { "default": { "c": [ { "T": "Ghost", "P": { "ID": { "H": "ghostComp", "T": "prop" } }, "E": {}, "C": {}, "O": { "cType": "child" }, "_Editor": { "eID": "ghostComp" } } ], "cType": "child" } },
+  "O": { "cType": "child", "dynProps": true }, "_Editor": { "eID": "serviceCallerComp" } }
+```
+Each call is a custom event on `Messaging` that builds a `requestObj` and calls `(<any>components.serviceCallerComp).serviceCall(requestObj)`. In the success callback, **capture → null → process**:
+```typescript
+if (serviceResponse.getProducts != null) {
+  let resData = serviceResponse.getProducts;  // capture
+  serviceResponse.getProducts = null;         // null immediately
+  components.tblProducts.items = resData.resultList; // process
+}
+```
+
+## Rules that prevent the common failures
+- Close the request object literal with `};` before the next call (missing `;` → "not callable").
+- Triggered custom events need `"C": true`; declare `P` to match the trigger payload.
+- `responseField` / event names must match exactly across trigger, request, and callback.
+- Fail alerts must include `actionButtons`.
+- Initialize in **one** place (service `onLoad` or `Messaging.PreRender`).
+- Don't assign `VDataTable.headers`/static `items` in callbacks — those are component props; assign only dynamic rows.

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

@@ -0,0 +1,73 @@
+# Legacy styling — the `cssClass` system (`O.layout` / CSS utility classes)
+
+> ⚠️ **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.** Style through `O.layout` (`dOpt` tokens + compiled `class`) and CSS utility classes, exactly as the page already does; never introduce `S` (it won't render on `V < 2`). On a new page / `opt.V >= 2.0` instead → [styling.md](styling.md). Reference examples from [../examples/cssClass/](../examples/cssClass/) only — the `S` examples in `examples/style/` will mislead you here.
+
+## When you are here
+
+You have opened a production page that predates the `S` system and needs a small change (the common case: "add a column", "nudge spacing", "change a text color"). Do **not** migrate it to `S` as a side effect of an edit — `S` won't render, so it would silently break the styling. Match the mechanism the page already uses. (A deliberate, full migration to `S` is a separate, opt-in task — not something to do inline.)
+
+## The two legacy mechanisms
+
+### 1. `O.layout` — the per-node Layout box (`dOpt` + compiled `class`)
+
+Layout intent (grid width, flex direction/align/justify, spacing) is expressed as prefixed Vuetify utility tokens in a node's `O.layout.dOpt`, keyed by breakpoint, and mirrored into a compiled `O.layout.class` string that the runtime actually applies.
+
+```json
+"O": {
+  "cType": "slot",
+  "layout": {
+    "dOpt": { "xs": ["d:d-flex", "fd:flex-column", "c:col-12", "a:align-center"],
+              "md": ["fd:flex-row", "c:col-6"] },
+    "class": "d-flex flex-column col-12 align-center flex-md-row col-md-6"
+  }
+}
+```
+
+**`dOpt` and `class` must stay in sync** — the runtime applies `class`, so after any `dOpt` change you must recompile the `class` string by the exact rule below. The full prefix grammar (`d, fd, a, j, w, c, sp, tt, tc, te, fi`), the breakpoint table, the `dOpt → class` compilation algorithm (xs as-is; `sm/md/lg/xl` infix the breakpoint after the first `-`), and the containment rules live in **[../reference/layout-system.md](../reference/layout-system.md)** — read that before editing any `O.layout`.
+
+Quick reference (see layout-system.md for the complete set):
+
+| Prefix | Meaning | Example token → class |
+| --- | --- | --- |
+| `d:` | display | `d:d-flex` → `d-flex` |
+| `fd:` | flex direction | `fd:flex-column` → `flex-column` |
+| `a:` | align-items | `a:align-center` → `align-center` |
+| `j:` | justify-content | `j:justify-center` → `justify-center` |
+| `c:` | grid column (1–12, `auto`, `d-none`) | `c:col-6` → `col-6` |
+| `sp:` | spacing (`N × 4px`) | `sp:pa-4` → `pa-4` (16px) |
+| `tt:`/`tc:`/`te:`/`fi:` | typography / text-color / weight / italic | `tc:primary--text` → `primary--text` |
+
+Compilation gotcha: a non-`xs` breakpoint token infixes the breakpoint — `fd:flex-row` under `md` → `flex-md-row`, `c:col-6` under `md` → `col-md-6`, `sp:pa-4` under `md` → `pa-md-4`. Get this wrong and the class won't match the `dOpt`.
+
+### 2. CSS utility classes on the `class` prop
+
+Direct Vuetify utility classes on a node's `class` prop (Web-only). On a legacy page these are used freely for design — typography, color, spacing, elevation, rounding:
+
+```json
+"class": { "H": "'text-center elevation-2 text-h5 primary--text'", "T": "class" }
+```
+
+Common utilities: typography `text-h1`…`text-h6`, `text-body-1/2`, `text-caption` + `font-weight-bold|medium|regular`; color `primary`/`primary--text`, `secondary--text`, `success--text`, `error--text`, `white--text`; spacing `pa-N`/`px-N`/`mt-N`… (`N × 4px`); appearance `elevation-0…24`, `rounded-lg`, `transparent`; alignment `d-flex`, `justify-center`, `align-center`. The `class` → `S` mapping table in [../reference/mapping-S-vuetify-class.md](../reference/mapping-S-vuetify-class.md) documents each token (useful here for understanding a token, and later if the page is ever migrated to `S`).
+
+**Gotcha — `VCol` does not auto-stack its children (see [layout-and-slots-legacy.md](layout-and-slots-legacy.md)).** Left without an explicit direction, a `VCol` lays children out as a row, so two components dropped straight into it render side-by-side instead of stacked. Fix here: add `fd:flex-column` to that `VCol`'s `O.layout.dOpt` (and recompile the synced `class`, e.g. `flex-column`). Don't leave a multi-child `VCol` without an explicit direction.
+
+**Equal-height cards in a row:** `VCard` has no flex `S`/`dOpt` mechanism of its own, so 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 `align-items:stretch` already gives the `VCol` full height).
+
+## Rules for editing a legacy page
+
+1. **Do not introduce `S`.** It won't render on `V<2`. Keep design in `O.layout` / `class`.
+2. **Keep `O.layout.dOpt` and `O.layout.class` in sync** — recompile `class` per the algorithm in [../reference/layout-system.md](../reference/layout-system.md) after any `dOpt` change.
+3. **Respect containment**: `VCol` only inside `VRow`; `VRow` holds only `VCol`; canonical wrapper `VContainer > VRow > VCol > content`.
+4. **Omit `cJson`/`clrids` entirely** — author `pJson`/`lrids` only; never write the compiled twins into a new file, and strip them from any existing file you edit. Studio/the compiler regenerates them on import.
+5. **Match the page's conventions** — mirror sibling nodes' token style, ID style, and class usage. Reference [../examples/cssClass/](../examples/cssClass/) for real legacy patterns.
+6. **Validate before finishing** against [validation-legacy.md](validation-legacy.md); fix all errors.
+
+## Migrating a legacy page to `S` (separate task)
+
+If the goal is genuinely to modernize a page (not just edit it), that means moving it onto the `S` system — a controlled, per-file conversion done as its own dedicated task, not an incidental edit. The `dOpt`/`class` → `S` conversion table is [../reference/mapping-S-vuetify-class.md](../reference/mapping-S-vuetify-class.md). A migrated page only styles correctly once its runtime/`opt.V` supports `S`.
+
+## Final checklist
+
+The full final checklist (shared core + the legacy style checks — no `S`, `dOpt`↔`class` in sync, `class` used freely) is in [validation-legacy.md](validation-legacy.md). Run it before finishing.

package/dist/studio-cli/kits/ui-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/ui-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.
+