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

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

@@ -0,0 +1,169 @@
+# Dynamic Components (`createComponent`)
+
+Quick's **repeater** — the `v-for` / list-rendering equivalent. For any list, feed, menu, or set of repeated rows/cards built from an array, clone a **template** component once per record. There is no `{{var}}` interpolation and no array-valued prop: clones receive a `dataSource`, read inside the template as `data.*`.
+
+Use it whenever the same subtree repeats and its content changes at runtime — **even at a small fixed count**. The alternative (N hand-authored trees, then dozens of property assignments by id from a handler) is what this replaces.
+
+Working references: `examples/style/authorizationDashboard.qjson` (nested, with rebuild-on-change), `examples/style/dynamicComp.qjson`, `examples/style/placeQidDynamic.qjson`.
+
+## Where the build code may run — read this first
+
+**`components[...]` does not resolve inside a `Messaging` handler** — not in `PreRender`, not in `EndRender`. `createComponent` still returns a real component, so nothing throws and nothing appears in the console, but `placeQID` resolves to nothing and **no clone reaches the DOM**. It looks exactly like success.
+
+Seed data in `Messaging.PreRender`; put the **build loop in a real control's handler** (the button/tab that shows the list).
+
+```typescript
+// ❌ Messaging PreRender / EndRender  → returns OK, places nothing
+// ✅ VBtn click handler               → clones land in placeQID
+```
+
+To paint on first load, give the control that owns the list the same handler body and call it from there.
+
+## Model
+
+1. Park templates in a **container with `"Render": {"H": "false"}`**. Hiding the parent is enough — the templates inside need no `Render` prop of their own. The container may sit anywhere: nested inside the page's `VContainer` works, so a new page still satisfies the single-content-root rule (s-track S4).
+2. Bind template props to `data.<field>`.
+3. For each item call `quick.Quick.createComponent` with a unique `newCompQID` and the container to insert into (`placeQID`).
+
+```
+VContainer id=rowTemplateBox  Render=false   ← hidden container
+  VCard    id=rowTemplate                    ← template
+```
+
+`Render:false` only applies at **runtime / Preview mode**. In Studio's edit canvas the template still draws, with every `data.*` binding resolving to `null` — expected, not a bug.
+
+A template may instead live inline where it renders (a `VListItem` inside its own `VList`), but then it shows as a real row: only do that when a visible first row is wanted.
+
+## Create
+
+```
+quick.Quick.createComponent({
+  templateCompQID: string,   // required — id of the template to clone
+  newCompQID:      string,   // required — unique suffix for this clone
+  dataSource?:     any,      // read as data.* inside the template
+  place?:          'Before' | 'After' | 'Default',   // default 'Default' = end of page
+  placeQID?:       string,   // container to insert into; omit → relative to the template
+  childName?:      string    // names the child; documented as readable via data.newData (no example in this workspace)
+}): IComponent | undefined | null
+```
+
+`place` and `placeQID` are optional. `place` is the `ElementLocation` enum; a bare string works but cast `<any>'Before'` if TS complains.
+
+**It returns the created component.** Capturing that return value and looking the clone up later by id are both valid — capture it when you are setting the clone up right there, look it up when you reach the clone from somewhere else (see *Reaching a clone afterwards*).
+
+```typescript
+let index = 0;
+liste.forEach(function (r: any) {
+  quick.Quick.createComponent({
+    templateCompQID: 'rowTemplate',
+    newCompQID: 'r' + index,
+    placeQID: 'rowList',
+    place: <any>'Before',
+    dataSource: r
+  });
+  index = index + 1;
+});
+```
+
+## Clone ids
+
+The clone's root id is **`templateCompQID + '_' + newCompQID`** — `rowTemplate_r0` above.
+
+**Every descendant is suffixed the same way and keeps its own base id.** A child authored as `rowTemplateTitle` becomes **`rowTemplateTitle_r0`** — *not* `rowTemplate_r0_Title`. That is how you address one field of one row.
+
+## Template prop bindings
+
+In **props**, reference clone data directly as `data.<field>`:
+
+```json
+"text":  { "H": "data.title", "T": "prop" }
+"text":  { "H": "data.dev + ' · ' + data.code", "T": "prop" }
+"class": { "H": "data.sevCls", "T": "class" }
+"color": { "H": "data.bar", "T": "prop" }
+```
+
+Verified working per clone: `text`, `class`, `color`, a `VIcon`'s icon name (PType `text`), and string-concat expressions.
+
+In **events**, declare it first: `declare let data;` then use `data.field`.
+
+A purely structural template (a divider, a spacer) needs no `dataSource` — just clone it.
+
+**`S` styling cannot vary per clone.** `S` holds literal values with no expression support, so every clone inherits the template's `S` verbatim. Route per-row visual differences through the `class` or `color` prop, as above — and set the corresponding `S` param to `""`, since `S` renders as an inline style and would otherwise beat the prop. (The style validator flags these as `prop-to-S`; for data-bound values that warning is unavoidable.)
+
+## Reaching a clone afterwards
+
+Any of these work; pick by what you have in hand — from a control's handler, not from `Messaging`.
+
+```typescript
+components['rowTemplate_r0']                                       // by compound id
+quick.getComponent('rowTemplate_r0')                               // when unreachable by reference
+quick.Quick.findCreateComponentRelative(quick.this, 'rowTemplate') // from a child inside the clone
+quick.Quick.getComponentIdByInstance(instance)                     // instance → id
+```
+
+`findCreateComponentRelative(sourceComp, targetCompID)` takes the **template** id and a child instance — this is how a handler on a cloned control identifies *which* clone it fired from:
+
+```typescript
+// click handler on a button inside a cloned row — removes that row
+const component = quick.Quick.findCreateComponentRelative(quick.this, 'tmpCrsItemLatePayment');
+quick.Quick.deleteComponent(component);
+```
+
+## Re-rendering when the data changes
+
+There is no reactive rebind — nothing repaints when the source array changes. **Delete the clones and rebuild**, guarding on existence first:
+
+```typescript
+let i: number = 0;
+while (i < 20) {
+  let old: any = components['rowTemplate_r' + i];
+  if (old) { quick.Quick.deleteComponent(old); }
+  i = i + 1;
+}
+```
+
+Verified: switching data sets this way holds the clone count and total node count exactly steady across repeated switches — nothing accumulates.
+
+`deleteComponent` removes the component **and all its children** and breaks the parent connection — deleting a cloned container drops everything cloned into it.
+
+After mutating a component in place, `quick.Quick.updateComponent(instance)` refreshes it.
+
+## Nested creation (a cloned container holding cloned rows)
+
+Create the container clone first, then pass **its compound id** as the `placeQID` of the children:
+
+```typescript
+quick.Quick.createComponent({
+  templateCompQID: 'cardTable', newCompQID: 'newUserTable',
+  placeQID: 'newUserTableContainer', place: <any>'Before'
+});
+
+for (let i = 0; i < keys.length; i += 2) {
+  quick.Quick.createComponent({
+    templateCompQID: 'cardTableRow', newCompQID: 'newUserRow' + i,
+    dataSource: { col1: keys[i], col2: data[keys[i]], col3: keys[i+1] ?? '', col4: data[keys[i+1]] ?? '' },
+    placeQID: 'cardTable_newUserTable',        // ← the clone made above
+    place: <any>'Before'
+  });
+}
+```
+
+## Related APIs
+
+```typescript
+quick.Quick.setComponentsProperty(compId, propertyName, propertyValue); // sets a prop, cascading to children
+quick.Quick.setComponentClass(instance, ['cls1', 'cls2']);              // set classes via API
+```
+
+`quick.Quick.createChildren({ parentCompQId, templateChildName, newChildName? })` is **not** a general repeater — it adds a named child to a container that defines template children of its own (e.g. a `GoldenLayout` pane). For repeated rows/cards use `createComponent`.
+
+## Rules (each prevents a real failure)
+
+1. **Build from a control's handler, never from `Messaging`** — `components[...]` is empty there and clones silently go nowhere.
+2. **`newCompQID` must be unique.** A duplicate does not error — the existing component is **replaced and becomes permanently unreachable**. Suffix with the loop index.
+3. `placeQID` must be a real container with a `default` slot. A container whose only content is a `Ghost` placeholder is the normal target; a leaf `Ghost` itself is not.
+4. Templates go in a `Render:false` container unless you want the template visible. It need not be root-level.
+
+## When NOT to use this
+
+Tabular data → `VDataTable.items` (don't clone rows). Genuinely static chrome that never changes at runtime → author it directly. Everything else that repeats — cards, list rows, feed items, menu entries — clone it, whether the count is 5 or unknown.

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/events-and-scripting.md

@@ -0,0 +1,79 @@
+# Events & Scripting (`E`)
+
+The `E` block holds behavior. Each event is `{ "H": code, "P"?: params, "HL"?: lang, "C"?, "I"?, "PE"?, "EV"?, "TO"? }`.
+
+```json
+"E": {
+  "click": {
+    "H": "quick.EM.trace('clicked');\r\n",
+    "P": "mouseEvent:unknown | undefined",
+    "HL": "TS"
+  },
+  "fetchData": {
+    "H": "let req = <any>{};\r\nreq.url='/api/items';\r\nreq.http='GET';\r\nreq.responseField='items';\r\nreq.onSuccess='onItems';\r\nquick.Request.async(req);\r\n",
+    "C": true, "HL": "TS"
+  }
+}
+```
+
+Event flags — runtime behavior (deep detail in [../reference/events-system.md](../reference/events-system.md)):
+- `C` = **custom**: triggered via `quick.MM.trigger`; the trigger payload is the dataSource (array→first element, object→whole), not name-mapped.
+- `I` = **immediate**: runs synchronously during render instead of being deferred to end-of-render.
+- `PE` = **property event**: injected into the component as a callback prop (chart `labelFormatter`/`tooltipLabel`).
+- `EV` = **externally visible**: exposed to a parent page as `quick.parent.events.<name>`.
+- `TO` = **post-render order**: deferred handlers run sorted by `TO` descending (higher fires first).
+- `HL` = handler language. **Event handlers must use `"HL": "TS"`.** `QS` is for properties/bindings (`P`), not the `E` block.
+
+> The whole events/scripting model (lifecycle internals, custom-event params, property/external events, the `quick.return` exception mechanism, compilation) is in **[../reference/events-system.md](../reference/events-system.md)**.
+
+## Language: events use TS; props may use QS
+**For every event handler (`E`/`D`), write `"HL": "TS"`.** Do not author event handlers as `QS`, `JS`, `FL`, or `GUI`.
+
+**Properties and bindings (`P`) may use `"HL": "QS"`**; QS is their default and is a good fit for short expressions. This property rule does not apply to event handlers.
+
+Line breaks in `H` are `\r\n`.
+
+## TypeScript handler rules (hard)
+1. **Never native `return`** — use `quick.return(value)` / `quick.return`.
+2. End statements with `;`. Close object literals with `};` before the next statement (a missing `;` after an object literal makes TS parse the next line as a call → "expression is not callable").
+3. **No browser globals**: `window`, `document`, `console`, `setTimeout`, `setInterval`. Use:
+   - `quick.EM.trace(...)` instead of `console.log`
+   - `quick.MM.delay('evt', { delayTime: 500 })` instead of `setTimeout`
+   - `quick.Quick.download(...)` instead of anchor downloads
+4. Reference framework APIs as `quick.X` (see [reference/quick-api.md](../reference/quick-api.md)).
+
+> In **QS properties/bindings**, drop `quick.`: write `store.get('x')`, `MM.trigger('evt')`, `Quick.go(...)`. The `quick.` prefix exists only in TS.
+
+> Note: some real files use `debugger;`/`setTimeout` in experimental editor pages. Don't copy those — prefer the Quick APIs for portable, compilable handlers.
+
+## Parameters (`P`) and declaring data
+- Framework/native event params → declare in `P`: `"P": "number:number"`, `"P": "index:any,row:any"`, `"P": "serviceResponse:any"`. Use the name directly in `H`.
+- Trigger-payload fields (passed via `quick.MM.trigger('evt', [{...}])`) are declared inside `H`.
+- Do **not** declare the same name both in `P` and inside `H` (duplicate identifier).
+
+## Page lifecycle (on `Messaging`)
+| Hook | When | Typical use |
+|------|------|-------------|
+| `PreRender` | before render (often `"I": true`) | init store, trigger first fetch |
+| `EndRender` | after render | access/set components |
+| `PostRender` | after prioritized events (`TO` orders them) | |
+| `Restored` | on navigating back | refresh |
+
+> ⚠️ **`PreRender` runs before components exist** — `components.*` is not accessible. Write to `store` in `PreRender` and read from it in prop expressions instead: `store.get('key')`. Use `EndRender` or a custom event if you need to set component props/values after render.
+
+Keep initialization in **one** hook to avoid duplicate fetches. Custom events live on `Messaging` with `"C": true`, called via `quick.MM.trigger`.
+
+## The `quick.*` API
+Everything you can call (network, store, alerts, navigation, validation, dynamic components, dates/money, crypto, …) is indexed in [reference/quick-api.md](../reference/quick-api.md) — scan its member index, then grep the exact signature, params and example for what you picked in [reference/quick-api.json](../reference/quick-api.json).
+
+```typescript
+components.myField.qValue = 'x';           // read/write component value
+quick.store.set('key', v); quick.store.get('key');   // page store ('#'=bag,'$'=global,'&'=shared)
+quick.MM.trigger('evt', [{ p: 1 }]);       // custom event
+quick.Quick.alert({ title:'T', text:'msg', category:'Info', actionButtons:[{name:'OK', type:'Confirm'}] });
+quick.Quick.go('<<qjson:UNIQUE-ID>>');     // navigate
+quick.return(value);                        // return from handler
+```
+
+## Service calls in one line of guidance
+Use `quick.Request.async({ url, http, data, responseField, onSuccess, onFail, blockRender })` and read the result in the `onSuccess` event as `response.<responseField>`. Full patterns (incl. project ServiceCaller convention) in [services.md](services.md).

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/layout-and-slots-legacy.md

@@ -0,0 +1,72 @@
+# Layout & Slots (`C` and `O`) — 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.** Grid/flex/spacing are authored through `O.layout` (`dOpt` + compiled `class`); how-to: [styling-legacy.md](styling-legacy.md), grammar: [../reference/layout-system.md](../reference/layout-system.md). On a new page / `opt.V >= 2.0` instead → [layout-and-slots.md](layout-and-slots.md).
+
+## Children (`C`) — grouped by slot
+
+```json
+"C": {
+  "default":      { "c": [ /* children */ ], "cType": "slot" },
+  "item.actions": { "c": [ /* per-row cells */ ], "cType": "scopedSlot" }
+}
+```
+
+`cType` (from `CType` enum):
+| value | meaning |
+|-------|---------|
+| `"slot"` | normal named slot (most visible UI) |
+| `"child"` | structural child (`Messaging`, service component, `Ghost`) |
+| `"scopedSlot"` | per-item callback slot — `item.<field>` is available in child bindings (e.g. `VDataTable` `item.<col>`) |
+
+The slot **key** is the slot name; `default` is the main slot. Leaves use `"C": {}`.
+
+## Options (`O`) — cType + layout
+
+```json
+"O": {
+  "cType": "slot",
+  "layout": {
+    "dOpt": { "xs": ["d:d-flex","fd:flex-column","c:col-6","sp:pa-4"] },
+    "class": "d-flex flex-column col-6 pa-4"
+  }
+}
+```
+
+`O.cType` mirrors the node's slot context and is always authored. `O.layout` (`dOpt` + compiled `class`) is the **layout mechanism on a legacy page** — grid width, flex direction/align/justify, and spacing. `dOpt` holds prefixed tokens per breakpoint; `class` is the compiled string the runtime applies, and it must stay **in sync** with `dOpt` (compilation rule: `xs` tokens as-is, `sm/md/lg/xl` tokens infix the breakpoint after the first `-`). Full prefix grammar + the `dOpt → class` algorithm: [../reference/layout-system.md](../reference/layout-system.md); authoring flow: [styling-legacy.md](styling-legacy.md). (Do **not** author the `S` object here — it won't render on `V < 2`.)
+
+Breakpoint device ranges:
+
+| Key | Device | Range |
+|-----|--------|-------|
+| `xs` | Mobile | 0–600px |
+| `sm` | Tablet | 600–960px |
+| `md` | Laptop | 960–1264px |
+| `lg` | Desktop | 1264–1904px |
+| `xl` | TV | 1904px+ |
+
+`dOpt` is keyed by **single** breakpoints (`xs`, `sm`, …); `xs` is the base and larger keys override from their min width up.
+
+## The grid: VContainer → VRow → VCol
+```
+VContainer (class "container container--fluid")
+  └─ VRow (12 columns, default align-items: stretch)
+       └─ VCol (width via c:col-N)
+            └─ VCard / content
+```
+
+### Containment rules (editor-enforced placement)
+The Studio editor enforces these on drag-drop (source: component extensions `acceptableParentComps`/`acceptableChildComps`; official `layout.md`). They're best practice — runtime/Vuetify is lenient, but **author to these** so the Studio editor accepts the tree as-is:
+- **`VCol` must be a child of `VRow`** and must not sit at the page root. (`layout.md`: "You cannot use VCol alone or within any other components. Always use VCol with VRow as its parent.")
+- **`VRow` should contain only `VCol`** children — put content inside a `VCol`, not directly in the `VRow`.
+- **`VFooter` accepts only `VContainer`** children.
+- Container components with item parts — `VTabs`→`VTab`/`VTabItem`, `VStepper`→`VStepperStep`/`VStepperContent`, `VExpansionPanels`→`VExpansionPanel`, `VCarousel`→`VCarouselItem` — must hold their documented item components.
+- Canonical wrapper for a page: `VContainer > VRow > VCol > VCard > content`.
+
+Follow the editor's placement rules. Machine-readable rules: [../reference/component-index.json](../reference/component-index.json) `containmentRules`.
+
+**Width, stacking, equal-height cards.** Set a `VCol`'s width with **`c:col-N`** (1–12) in its `O.layout.dOpt` + the synced `col-N` class. `VCol` is itself a flex container whose 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; fix by adding **`fd:flex-column`** to that `VCol`'s `dOpt` (+ synced `flex-column` class). Equal-height cards: `d-flex` on the `VCol` + `flex-grow-1 d-flex flex-column` on the card. Worked examples: [styling-legacy.md](styling-legacy.md).
+
+## Scoped slots in tables
+Custom cells use a `C` key `item.<columnValue>` with `cType:"scopedSlot"`. Inside it, `item.<field>` reads the row; for `VDataTable.click:row` the row arrives as the `index` param (`"P":"index:any,row:any"`). See [components.md](components.md).

package/dist/studio-cli/kits/ui-app-kit/.ai-kit/ui-kit/knowledge/layout-and-slots.md

@@ -0,0 +1,64 @@
+# Layout & Slots (`C` and `O`) — `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.** Grid width, flex direction/align/justify, and spacing are authored as `S` params (how-to: [styling.md](styling.md)); `O.layout` is not authored. On a **legacy** page instead → [layout-and-slots-legacy.md](layout-and-slots-legacy.md).
+
+## Children (`C`) — grouped by slot
+
+```json
+"C": {
+  "default":      { "c": [ /* children */ ], "cType": "slot" },
+  "item.actions": { "c": [ /* per-row cells */ ], "cType": "scopedSlot" }
+}
+```
+
+`cType` (from `CType` enum):
+| value | meaning |
+|-------|---------|
+| `"slot"` | normal named slot (most visible UI) |
+| `"child"` | structural child (`Messaging`, service component, `Ghost`) |
+| `"scopedSlot"` | per-item callback slot — `item.<field>` is available in child bindings (e.g. `VDataTable` `item.<col>`) |
+
+The slot **key** is the slot name; `default` is the main slot. Leaves use `"C": {}`.
+
+## Options (`O`) — cType only
+
+```json
+"O": { "cType": "slot" }
+```
+
+`O.cType` mirrors the node's slot context and is always authored. Do **not** author `O.layout` (`dOpt`/`class`) here — that is the legacy mechanism; on an `S`-system page grid width, flex direction, align, justify, and spacing all go in `S` instead ([styling.md](styling.md)).
+
+Breakpoint device ranges — the boundaries `S` resolution ranges like `"xs-xl"`/`"md-xl"` are built from:
+
+| Key | Device | Range |
+|-----|--------|-------|
+| `xs` | Mobile | 0–600px |
+| `sm` | Tablet | 600–960px |
+| `md` | Laptop | 960–1264px |
+| `lg` | Desktop | 1264–1904px |
+| `xl` | TV | 1904px+ |
+
+## The grid: VContainer → VRow → VCol
+```
+VContainer (class "container container--fluid")
+  └─ VRow (12 columns, default align-items: stretch)
+       └─ VCol (width via S.col)
+            └─ VCard / content
+```
+
+### Containment rules (editor-enforced placement)
+The Studio editor enforces these on drag-drop (source: component extensions `acceptableParentComps`/`acceptableChildComps`; official `layout.md`). They're best practice — runtime/Vuetify is lenient, but **author to these** so the Studio editor accepts the tree as-is:
+- **`VCol` must be a child of `VRow`** and must not sit at the page root. (`layout.md`: "You cannot use VCol alone or within any other components. Always use VCol with VRow as its parent.")
+- **`VRow` should contain only `VCol`** children — put content inside a `VCol`, not directly in the `VRow`.
+- **`VFooter` accepts only `VContainer`** children.
+- Container components with item parts — `VTabs`→`VTab`/`VTabItem`, `VStepper`→`VStepperStep`/`VStepperContent`, `VExpansionPanels`→`VExpansionPanel`, `VCarousel`→`VCarouselItem` — must hold their documented item components.
+- Canonical wrapper for a page: `VContainer > VRow > VCol > content`.
+
+Follow the editor's placement rules. Machine-readable rules: [../reference/component-index.json](../reference/component-index.json) `containmentRules`.
+
+**Width, stacking, equal-height cards.** Set a `VCol`'s width with **`S.col`** (1–12, range-keyed, e.g. `"xs-xl": {"col":"3"}`). `VCol` is itself a flex container whose 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; fix with **`S.flexDirection: "column"`** on that `VCol`. Worked examples (stacked label/value, equal-height cards) + the full param list: [styling.md](styling.md).
+
+## Scoped slots in tables
+Custom cells use a `C` key `item.<columnValue>` with `cType:"scopedSlot"`. Inside it, `item.<field>` reads the row; for `VDataTable.click:row` the row arrives as the `index` param (`"P":"index:any,row:any"`). See [components.md](components.md).

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

@@ -0,0 +1,40 @@
+# Localization (`lrids`, `LR`)
+
+## `lrids` structure — by language code, values single-quoted
+```json
+"lrids": {
+  "tr-TR": { "save": "'Kaydet'", "userName": "'Kullanıcı Adı:'" },
+  "en-US": { "save": "'Save'",   "userName": "'User Name:'" }
+}
+```
+- Group by language code (`tr-TR`, `en-US`, …).
+- Every value is a single-quoted string (same quoting model as prop `H`).
+- Every key used by `LR`/`quick.LR` must exist in **all** required languages.
+- **Omit `clrids` entirely** — the compiler generates it on import (compiled values look like `╬'Kaydet'╩╩`). Never author `clrids`, and strip it from any existing file you edit.
+
+## Context rule: `LR` in props, `quick.LR` in events
+| Context | Use |
+|---------|-----|
+| Props (`P.H`, QScript) | bare `LR('key')` |
+| Events (`E.H`, TS) | `quick.LR('key')` |
+
+Props:
+```json
+"text": { "H": "LR('save')", "T": "prop" }
+```
+Events:
+```typescript
+quick.Quick.alert({ text: quick.LR('genericError'), category:'Error', actionButtons:[{name: quick.LR('ok'), type:'Confirm'}] });
+```
+`quick.LR(key, dataSource?)` returns the localized string. Never call `quick.LR` inside a prop.
+
+## Static vs localized text
+Static = a quoted literal (`"H": "'Kaydet'"`); localized = wrap the key (`"H": "LR('save')"`). Apostrophe inside a QScript string is doubled: `'Premium''u'`.
+
+## Workflow
+1. Pick a stable key.
+2. Add it under every language block in `lrids`.
+3. Reference with `LR('key')` (props) / `quick.LR('key')` (events).
+4. Verify no language is missing the key before finishing.
+
+There is also a runtime `quick.importLocalization(langCode, {...})` and global localization qjsons in some projects — but for a single page, `lrids` is what you author.

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

@@ -0,0 +1,83 @@
+# Page Skeletons — 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.** These are **structure references for editing/extending an existing legacy page**, not "start from scratch" templates — keep the page's current root, don't retrofit a `VContainer`, and design via `O.layout` (`dOpt`/`class`) + CSS classes. Starting a genuinely new page instead → [page-skeletons.md](page-skeletons.md).
+
+## Reference shape — framework-native (no service component)
+A legacy page typically has this shape (`Messaging` + a layout root). Match it when adding sections; do not add a `VContainer` root to a page that already roots elsewhere.
+
+```javascript
+let pjson = {
+  "pJson": [
+    {
+      "T": "Messaging",
+      "P": { "ID": { "H": "msg", "T": "prop" } },
+      "E": {
+        "PreRender": { "H": "quick.MM.trigger('fetchData');\r\n", "I": true, "HL": "TS" },
+        "fetchData": { "H": "let req=<any>{};\r\nreq.url='/api/data';\r\nreq.http='GET';\r\nreq.data=null;\r\nreq.blockRender=false;\r\nreq.responseField='data';\r\nreq.onSuccess='onData';\r\nreq.onFail='onFail';\r\nquick.Request.async(req);\r\n", "C": true, "HL": "TS" },
+        "onData": { "H": "let resData = response.data;\r\n/* process resData */\r\n", "C": true, "HL": "TS" },
+        "onFail": { "H": "quick.Quick.alert({ title:'Hata', text:'Bir hata oluştu.', category:'Error', actionButtons:[{ name:'Tamam', type:'Confirm' }] });\r\n", "C": true, "HL": "TS" }
+      },
+      "C": {}, "O": { "cType": "child" }, "_Editor": { "eID": "msg" }
+    },
+    {
+      "T": "VContainer",
+      "P": { "ID": { "H": "pageContainer", "T": "prop" },
+             "class": { "H": "'container container--fluid'", "T": "class" } },
+      "E": {},
+      "C": { "default": { "c": [ /* PAGE CONTENT */ ], "cType": "slot" } },
+      "O": { "cType": "child" }, "_Editor": { "eID": "pageContainer" }
+    }
+  ],
+  "lrids": {}, "opt": {}
+};
+export default pjson
+```
+
+## Reference shape — with project ServiceCaller (only if the project provides one)
+Same as above, plus a `CustomComponent` after `Messaging` (see [services.md](services.md) Pattern B), with init in its `onLoad`.
+
+## Centered content scaffold (drop into PAGE CONTENT)
+Legacy form — layout via `O.layout` (`dOpt` + synced `class`), visuals via CSS utility classes on the `class` prop:
+
+```json
+{ "T": "VRow", "P": { "ID": { "H": "rowMain", "T": "prop" } }, "E": {},
+  "C": { "default": { "c": [
+    { "T": "VCol", "P": { "ID": { "H": "colMain", "T": "prop" } }, "E": {},
+      "C": { "default": { "c": [
+        { "T": "VCard", "P": { "ID": { "H": "cardMain", "T": "prop" },
+            "elevation": { "H": "0", "T": "prop" },
+            "class": { "H": "'white pa-4 rounded-lg'", "T": "class" } },
+          "E": {}, "C": { "default": { "c": [
+            { "T": "QLabel", "P": { "ID": { "H": "lblPageTitle", "T": "prop" },
+                "text": { "H": "'Page Title'", "T": "prop" },
+                "class": { "H": "'text-h5 font-weight-bold primary--text'", "T": "class" } },
+              "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "lblPageTitle" } }
+          ], "cType": "slot" } },
+          "O": { "cType": "slot" }, "_Editor": { "eID": "cardMain" } }
+      ], "cType": "slot" } },
+      "O": { "cType": "slot", "layout": { "dOpt": { "xs": ["d:d-flex","j:justify-center"] }, "class": "d-flex justify-center" } },
+      "_Editor": { "eID": "colMain" } }
+  ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "rowMain" } }
+```
+
+## Styling — `O.layout` + CSS classes (do NOT author `S`)
+On a legacy page, design lives in two places, not in `S` (which 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.
+- **The `class` prop** — CSS utility classes for typography (`text-h5`, `font-weight-bold`), color (`primary--text`, `white`), elevation (`elevation-2`), rounding (`rounded-lg`).
+
+```json
+{ "T": "VCard", "P": { "ID": { "H": "cardMain", "T": "prop" },
+    "elevation": { "H": "2", "T": "prop" },
+    "class": { "H": "'white pa-4 rounded-lg'", "T": "class" } },
+  "E": {}, "C": { "default": { "c": [ /* … */ ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "cardMain" } }
+```
+
+Full how-to: [styling-legacy.md](styling-legacy.md); the `dOpt` grammar + `dOpt → class` compilation rule: [../reference/layout-system.md](../reference/layout-system.md). **Do not introduce `S` on a legacy page — it silently won't render.**
+
+## Large-page policy (incremental)
+Don't rewrite a whole page in one shot. Add **1–3 sections per edit**, validate, and report progress. Reuse examples from [../examples/cssClass/](../examples/cssClass/) (the legacy set — e.g. `CardTitle.qjson`, `Profile_Card.qjson`) and neighboring project pages rather than re-deriving structures.

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

@@ -0,0 +1,111 @@
+# Page Skeletons — `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** (starting a brand-new page). A new page's `opt.V` is always the current version — **author it as `opt.V: 2.5`** (this marks the page as `S`-system; the skeleton below already sets it). Adding a section to an **existing legacy page** instead → [page-skeletons-legacy.md](page-skeletons-legacy.md).
+
+Start every new page from one of these. Structure: `Messaging` (event hub) → optional service `CustomComponent` (only if the project uses one) → `VContainer` (layout root). For a **new page the `VContainer` content root is required** (not merely canonical): wrap all UI content in a single top-level `VContainer`, with `Messaging` and the optional service component as the only other top-level `pJson` siblings. This is a **new-page rule only** — when editing an existing page, keep its current root and do **not** add a `VContainer` unless the user asks.
+
+## Skeleton — framework-native (no service component)
+```javascript
+let pjson = {
+  "pJson": [
+    {
+      "T": "Messaging",
+      "P": { "ID": { "H": "msg", "T": "prop" } },
+      "E": {
+        "PreRender": { "H": "quick.MM.trigger('fetchData');\r\n", "I": true, "HL": "TS" },
+        "fetchData": { "H": "let req=<any>{};\r\nreq.url='/api/data';\r\nreq.http='GET';\r\nreq.data=null;\r\nreq.blockRender=false;\r\nreq.responseField='data';\r\nreq.onSuccess='onData';\r\nreq.onFail='onFail';\r\nquick.Request.async(req);\r\n", "C": true, "HL": "TS" },
+        "onData": { "H": "let resData = response.data;\r\n/* process resData */\r\n", "C": true, "HL": "TS" },
+        "onFail": { "H": "quick.Quick.alert({ title:'Hata', text:'Bir hata oluştu.', category:'Error', actionButtons:[{ name:'Tamam', type:'Confirm' }] });\r\n", "C": true, "HL": "TS" }
+      },
+      "C": {}, "O": { "cType": "child" }, "_Editor": { "eID": "msg" }
+    },
+    {
+      "T": "VContainer",
+      "P": { "ID": { "H": "pageContainer", "T": "prop" },
+             "class": { "H": "'container container--fluid'", "T": "class" } },
+      "E": {},
+      "C": { "default": { "c": [ /* PAGE CONTENT */ ], "cType": "slot" } },
+      "O": { "cType": "child" }, "_Editor": { "eID": "pageContainer" }
+    }
+  ],
+  "lrids": {}, "opt": { "V": 2.5 }
+};
+export default pjson
+```
+
+## Skeleton — with project ServiceCaller (only if the project provides one)
+Same as above, plus a `CustomComponent` after `Messaging` (see [services.md](services.md) Pattern B), with init in its `onLoad`.
+
+## Centered content scaffold (drop into PAGE CONTENT)
+
+> **VCard children do not stack automatically** — `VCard`'s default slot is a flex-row container. Always place a `VRow > VCol(flexDirection:column)` inside `VCard` before adding content; otherwise labels/inputs render side-by-side instead of stacked.
+
+```json
+{ "T": "VRow", "P": { "ID": { "H": "rowMain", "T": "prop" } }, "E": {},
+  "C": { "default": { "c": [
+    { "T": "VCol", "P": { "ID": { "H": "colMain", "T": "prop" } },
+      "S": { "xs-xl": { "col": "12", "justifyContent": "center", "paddingTop": "0px", "paddingRight": "0px", "paddingBottom": "0px", "paddingLeft": "0px" } },
+      "E": {},
+      "C": { "default": { "c": [
+        { "T": "VCard", "P": { "ID": { "H": "cardMain", "T": "prop" } },
+          "S": { "xs-xl": { "backgroundColor": "#ffffff", "boxShadow": "none", "paddingTop": "16px", "paddingRight": "16px", "paddingBottom": "16px", "paddingLeft": "16px", "borderTopLeftRadius": "8px", "borderTopRightRadius": "8px", "borderBottomLeftRadius": "8px", "borderBottomRightRadius": "8px" } },
+          "E": {}, "C": { "default": { "c": [
+            { "T": "VRow", "P": { "ID": { "H": "rowCardContent", "T": "prop" } },
+              "S": { "xs-xl": { "marginTop": "0px", "marginRight": "0px", "marginBottom": "0px", "marginLeft": "0px" } },
+              "E": {}, "C": { "default": { "c": [
+                { "T": "VCol", "P": { "ID": { "H": "colCardContent", "T": "prop" } },
+                  "S": { "xs-xl": { "col": "12", "flexDirection": "column", "paddingTop": "0px", "paddingRight": "0px", "paddingBottom": "0px", "paddingLeft": "0px" } },
+                  "E": {}, "C": { "default": { "c": [
+                    { "T": "QLabel", "P": { "ID": { "H": "lblPageTitle", "T": "prop" },
+                        "text": { "H": "'Page Title'", "T": "prop" } },
+                      "S": { "xs-xl": { "fontSize": "24px", "fontWeight": "700", "fontColor": "#1976D2", "fontFamily": "", "fontStyle": "", "combinedFont": "", "ThemeFont": "", "lineHeight": "" } },
+                      "E": {}, "C": {}, "O": { "cType": "slot" }, "_Editor": { "eID": "lblPageTitle" } }
+                  ], "cType": "slot" } },
+                  "O": { "cType": "slot" }, "_Editor": { "eID": "colCardContent" } }
+              ], "cType": "slot" } },
+              "O": { "cType": "slot" }, "_Editor": { "eID": "rowCardContent" } }
+          ], "cType": "slot" } },
+          "O": { "cType": "slot" }, "_Editor": { "eID": "cardMain" } }
+      ], "cType": "slot" } },
+      "O": { "cType": "slot" },
+      "_Editor": { "eID": "colMain" } }
+  ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "rowMain" } }
+```
+
+## Styling — every component carries an `S` (don't skip it)
+The skeletons above are intentionally minimal: **structure + `class` only**. They are *not* a finished page. A real page also sets each component's visual design in its top-level **`S`** object — the cross-platform Style tag the editor serializes (sibling to `T`/`P`/`E`/`C`/`O`/`_Editor`). After you drop in a section, give its components their `S`:
+
+```json
+{ "T": "VCard", "P": { "ID": { "H": "cardMain", "T": "prop" } },
+  "S": { "xs-xl": {
+      "backgroundColor": "#ffffff",
+      "borderTopLeftRadius": "8px", "borderTopRightRadius": "8px",
+      "borderBottomLeftRadius": "8px", "borderBottomRightRadius": "8px",
+      "paddingTop": "16px", "paddingRight": "16px", "paddingBottom": "16px", "paddingLeft": "16px",
+      "boxShadow": "0 2px 8px rgba(0,0,0,0.08)" } },
+  "E": {}, "C": { "default": { "c": [
+    { "T": "VRow", "P": { "ID": { "H": "rowCardContent", "T": "prop" } },
+      "S": { "xs-xl": { "marginTop": "0px", "marginRight": "0px", "marginBottom": "0px", "marginLeft": "0px" } },
+      "E": {}, "C": { "default": { "c": [
+        { "T": "VCol", "P": { "ID": { "H": "colCardContent", "T": "prop" } },
+          "S": { "xs-xl": { "col": "12", "flexDirection": "column", "paddingTop": "0px", "paddingRight": "0px", "paddingBottom": "0px", "paddingLeft": "0px" } },
+          "E": {}, "C": { "default": { "c": [ /* content here */ ], "cType": "slot" } },
+          "O": { "cType": "slot" }, "_Editor": { "eID": "colCardContent" } }
+      ], "cType": "slot" } },
+      "O": { "cType": "slot" }, "_Editor": { "eID": "rowCardContent" } }
+  ], "cType": "slot" } },
+  "O": { "cType": "slot" }, "_Editor": { "eID": "cardMain" } }
+```
+
+- `S` is **range-keyed** (`"xs-xl"` = all sizes; narrower ranges like `"md-xl"` override for larger screens). Values are strings; `""` = unset.
+- Pull the supported param names + editor defaults for each `T` from [../reference/component-styles.json](../reference/component-styles.json) — don't invent params.
+- Style a child's text/icon (e.g. a `VBtn` label color) through the **parent's `SC`**, not the child's own `S`.
+- **Everything goes in `S`** — layout (flex/grid/spacing/direction, where the component's style block in [../reference/component-styles.json](../reference/component-styles.json) supports it) and visuals (color/font/border/shadow/exact size) alike. `O.layout` (`dOpt`+`class`) is legacy; don't author it. Reach for the component's `class` prop only as a Web-only last resort when `S` truly has no param for it — never on Mobile.
+
+Full how-to: [styling.md](styling.md). **A page delivered with no `S` is unstyled — the styling pass is part of authoring, not an optional extra.**
+
+## Large-page policy (incremental)
+Don't rewrite a whole page in one shot. Write the skeleton + scaffold, then add **1–3 sections per edit**, validate, and report progress. Reuse examples from [../examples/style/](../examples/style/) (the `S`-system set) and neighboring project pages rather than re-deriving structures.