@stechquick/studio-cli 4.0.3-2

package/dist/studio-cli/src/.ai-kit/reference/qjson-schema.md

@@ -0,0 +1,188 @@
+# QJSON Schema — Authoritative Reference (`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? → [AGENT_GUIDE Step 0](../AGENT_GUIDE.md).
+>
+> **This file is the `S` track.** Design is authored in the node's `S` object; `O.layout` is not authored. On a **legacy** page instead (where `S` does not render) → [qjson-schema-legacy.md](qjson-schema-legacy.md).
+>
+> Source of truth: `common/shrimp/interfaces/ComponentInterfaces/ICompJson.ts` and `IQJson.ts`. These are the actual TypeScript interfaces the Quick runtime/compiler use. The earlier community docs described a smaller subset — this is the full schema.
+
+## 1. File envelope (`IQJSon`)
+
+A `.qjson` file is a JS module exporting `pjson`:
+
+```javascript
+let pjson = {
+  "pJson": [],     // ICompJson[]  — authored component tree (you write this)
+  "lrids": {},     // ILRID        — localization you write, by language code
+  "opt": {}        // IQJsonOptions
+};
+export default pjson
+```
+
+An **AI-authored file carries only these three keys** (`pJson`, `lrids`, `opt`). The compiled twins `cJson` (compiled tree) and `clrids` (compiled localization) are generated by the editor/compiler on import — **omit them entirely**: never write them into a new file, and strip them from any downloaded file you edit.
+
+Full `IQJSon` interface fields:
+
+| Key | Type | Authored? | Notes |
+|-----|------|-----------|-------|
+| `pJson` | `ICompJson[]` | **you** | the component tree |
+| `cJson` | `ICompJson[]` | generated | compiled twin of pJson; **absent in AI-authored files** (omit/strip — Studio regenerates it) |
+| `lrids` | `ILRID` | **you** | `{ "tr-TR": {key:"'val'"}, ... }` |
+| `clrids` | `ILRID` | generated | compiled localization; **absent in AI-authored files** (omit/strip — Studio regenerates it) |
+| `opt` | `IQJsonOptions` | optional | page options (below) |
+| `description` | `string` | optional | page description |
+| `files` / `cFiles` | `Record<string,string>` | optional | TS 2.0 external handler files (`HF`) and compiled twins |
+| `namedViews` | `Record<string, IQView>` | optional | additional named views (advanced) |
+
+`IQJsonOptions` (`opt`):
+
+| Field | Meaning |
+|-------|---------|
+| `QL` | QJSON default scripting language (`ScriptLang`). Event handlers still use explicit `HL:"TS"`; properties/bindings may use `HL:"QS"`. |
+| `V` | schema version number. A **new `S`-system page sets `V: 2.5`** (the current version — this is what marks it as `S`-system); a legacy page has `V` missing or `< 2.0`. |
+| `otelDiag` / `otelChannel` | telemetry tags |
+
+> `ScriptLang = "QS" | "JS" | "TS" | "FL" | "GUI"`. `QS`=QScript, `TS`=TypeScript, `JS`=plain JS (passthrough), `FL`=Flow (visual), `GUI`=editor-generated.
+
+AI-authoring convention: an authored file carries three keys (`pJson`, `lrids`, `opt`) and **omits `cJson`/`clrids` entirely**; the editor/compiler fills the compiled twins on import/save. The file must close with `};` then `export default pjson`.
+
+## 2. Component node (`ICompJson`)
+
+```ts
+interface ICompJson {
+  T: string;                        // component type name (see component-catalog.md)
+  CP?: string;                      // CompPath for a Named component
+  P: IPropJson;                     // properties (ID is required)
+  E: IDictionary<IEventJson>;       // events
+  C: IDictionary<IChildJson>;       // children grouped by slot name
+  D?: Record<string, Record<string, IDirectiveJson>>;  // directives (advanced)
+  O?: IOptJson;                     // options (cType, layout, ...)
+  SA?: Array<string>;               // applied Styled Component names (reusable named styles)
+  S?: StyleValue;                   // Style-tab inline styles, keyed by resolution range
+  SC?: IStyleChild;                 // style overrides for child sub-elements
+  _Editor: IEditorJson;             // { eID: string }
+}
+```
+
+Required for a valid node: `T`, `P.ID.H`, `_Editor.eID`, and **`C`** (use `{}` for leaf components — omitting `C` is an error). `E` is typically present (often `{}`). `O` carries `cType` and layout.
+
+### Styling fields: `S`, `SA`, `SC` (the Style System)
+These are produced by Studio's **Style tab** (the modern styling mechanism). The earlier community docs ignored them.
+
+- **`S`** (`StyleValue = Record<string, string | boolean | Record<string,string>>`): inline styles keyed by **resolution range** (e.g. `"xs-xl"`, `"md-xl"`), each a map of CSS-camelCase properties: `width`/`height`, `fontColor`/`fontFamily`/`fontSize`/`fontStyle`/`fontWeight`/`lineHeight`/`textAlign`, `backgroundColor`/`color`/`iconColor`, `border*`/`boxShadow`/`boxSizing`, margins/paddings, and (on containers) `col`/`flexDirection`/`alignItems`/`justifyContent`. Empty `""` = unset.
+- **`SA`**: array of applied **Styled Component** names (reusable named styles shared across pages).
+- **`SC`** (`IStyleChild`): style overrides targeting a component's child sub-elements.
+
+You hand-write `S` for **all** per-component design here — layout included (grid `col`, `flexDirection`/`alignItems`/`justifyContent`, spacing); `SA`/`SC` are normally produced by applying Styled Components in Studio. The `O.layout` field (§6) exists in the schema but belongs to the legacy era — **do not author it** on an `S`-system page. Full guidance: [knowledge/04-styling.md](../knowledge/04-styling.md).
+
+`CP` (CompPath for Named components) and `D` (directives) are advanced/editor-managed; hand-authoring rarely needs them.
+
+### `_Editor.eID`
+`{ "eID": "<id>" }` — the editor's stable internal id. It is **equal to `P.ID.H` for auto-generated components** (both `EdtrComp_42`) but **may differ** when the ID is renamed in Studio (real files contain both: e.g. `ID:"PageComp"` with `eID:"EdtrComp_1"`). So equality is not required. Rules that ARE required: both `P.ID.H` and `_Editor.eID` must be present and unique per page. When hand-authoring a new component, setting `eID` = `ID` (one unique value) is the simplest valid choice.
+
+## 3. Properties (`IPropJson` / `IPropertyJson`)
+
+```ts
+interface IPropertyJson {
+  H: string | object;   // value/expression (the "handler")
+  T: PTyped;            // "prop" | "class" | "text" | "attr"
+  DE?: boolean;         // Don't-Evaluate: use H literally, skip script evaluation
+  HF?: string;          // external handler file (TS 2.0)
+  HL?: ScriptLang;      // property language; QS is permitted and is the default for property expressions
+}
+```
+
+`PType` enum (how the value is applied at render — from `RenderingManager`):
+
+| `T` | Destination | Use for |
+|-----|-------------|---------|
+| `"prop"` | Vue component prop | the common case (`color`, `label`, `visible`, `items`, `QLabel.text`) |
+| `"class"` | CSS class string | `class` |
+| `"text"` | component slot **text content** | `VIcon` icon name; raw text content |
+| `"attr"` | DOM attribute | `data-*`, `aria-*`, masks like `format` |
+
+Value quoting inside `H` (QScript expression semantics):
+- String → single-quoted: `"'primary'"`
+- Number/boolean → bare: `"10"`, `"true"`
+- Expression/binding → bare: `"item.name"`, `"data.title"`, `"components.x.qValue"`
+- Array → `"[1,2,3]"`; QScript object literals use `=` keys: `"[{text='A', value=1}]"`
+
+`IPropJson` reserves `ID` (required, `IDefinedPropertyJson` — `H` is a plain string), plus `Render`, `DiscardSettings`, `class`.
+
+## 4. Events (`IEventJson`)
+
+```ts
+interface IEventJson {
+  H: string | IQuickFlowModel;  // handler code (TS/QScript text), or a Flow model
+  P?: string;   // params. QS: "x,y,z" 
+  HF?: string;  // external handler file (TS 2.0)
+  I?: boolean;  // immediate (run synchronously during render — used by lifecycle init)
+  C?: boolean;  // custom event (triggered via quick.MM.trigger)
+  PE?: boolean; // property event (fires on a property change; charts use this)
+  TO?: number;  // post-render trigger order
+  EV?: boolean; // externally visible (callable from a parent/other qjson)
+  HL: "TS";        // event handlers use TS only
+  SM?: string;  // source map (debug)
+}
+```
+
+- Event handler text uses `\r\n` line breaks.
+- Custom events you call with `quick.MM.trigger('name', [payload])` must be declared with `"C": true`.
+- Events callable from another page/parent need `"EV": true`.
+- Lifecycle init events are often marked `"I": true`.
+- Use `quick.return` (never native `return`); see [scripting knowledge](../knowledge/02-events-and-scripting.md).
+
+## 5. Children & slots (`IChildJson` / `CType`)
+
+```ts
+interface IChildJson { cType: CTyped; c: Array<ICompJson>; }
+enum CType { child = "child", slot = "slot", scopedSlot = "scopedSlot" }
+```
+
+`C` is keyed by **slot name**:
+
+```json
+"C": {
+  "default":      { "c": [ ...children... ], "cType": "slot" },
+  "item.actions": { "c": [ ...per-row cells... ], "cType": "scopedSlot" }
+}
+```
+
+| `cType` | Meaning (from source) |
+|---------|------------------------|
+| `"slot"` | normal named slot |
+| `"child"` | direct/structural child (Messaging, service components, Ghost) |
+| `"scopedSlot"` | callback slot receiving per-item data (`VDataTable` `item.<col>` — `item` available in child bindings) |
+
+## 6. Options (`IOptJson`)
+
+```ts
+interface IOptJson {
+  cType?: CTyped;                       // matches the node's slot context
+  dynProps?: boolean;                   // dynamic-prop component (e.g. CustomComponent)
+  CL?: ScriptLang;                      // component language (defaults to QS)
+  forceUpdateAfterPropertySetting?: boolean;
+  compDomClasses?: string;              // editor-rendered DOM class string (editor-managed)
+  layout?: ILayoutJson;                 // legacy — see note below; { dOpt: {bp: string[]}, class: string }
+}
+interface ILayoutJson { dOpt: IDictionary<Array<string>>; class: string; }
+```
+
+- **`O.layout` — do not author it here.** It's the pre-`S` legacy layout mechanism (`dOpt` keyed by breakpoint → prefixed tokens, flattened into a synced `class` string). It exists in the schema and the compiler still accepts it, but on an `S`-system page grid width, flex direction/align/justify, and spacing are all `S` params (`col`, `flexDirection`, `alignItems`, `justifyContent`, margins/paddings) — see [knowledge/03-layout-and-slots.md](../knowledge/03-layout-and-slots.md) and [knowledge/04-styling.md](../knowledge/04-styling.md). (If you are actually editing a legacy page, you are in the wrong doc — see [qjson-schema-legacy.md](qjson-schema-legacy.md).)
+
+## 7. Compiled form (`cJson`) — do not author
+
+When compiled, handler `H` values get wrapped with sentinel delimiters (e.g. `╬...╩╩`) and `cJson`/`clrids` are populated. **AI-authored files omit `cJson`/`clrids` entirely** — never write them into a new file, and strip them from any downloaded file you edit. Author `pJson`/`lrids`, then let the editor (or the official compiler CLI) regenerate the compiled twins on import. See [validation & sync](../knowledge/10-validation-and-sync.md).
+
+## 8. Minimal valid node
+
+```json
+{
+  "T": "QLabel",
+  "P": { "ID": { "H": "lblTitle", "T": "prop" },
+         "text": { "H": "'Hello'", "T": "prop" } },
+  "E": {}, "C": {},
+  "O": { "cType": "slot" },
+  "_Editor": { "eID": "lblTitle" }
+}
+```

package/dist/studio-cli/src/.ai-kit/reference/quick-api.md

@@ -0,0 +1,248 @@
+# Quick Runtime API (`quick.*`) — Authoritative Reference
+
+> Source of truth: `common/shrimp/interfaces/Scripting/IGlobals.ts` in the Quick monorepo. This is the API surface available inside event/prop handlers. Extracted from the real TypeScript interface definitions — not guessed.
+
+## Two scripting contexts
+
+Handlers run in one of two languages (`HL` field), and the available globals differ:
+
+| | `HL: "TS"` (TypeScript) | `HL: "QS"` (QScript) |
+|---|---|---|
+| Interface | `IGlobalsTS` | `IGlobalsQS` |
+| Extra globals | `devex` | `Math`, `regex`, `typeOf`, `Date`, `Number`, `JSON`, `string`, `Object`, `js`, `Url` |
+| Default? | **event handlers: always author `TS`** (`"HL":"TS"`) | **properties/bindings: `QS`** — the omitted-`HL` runtime default (per `IPropertyJson`; also `IOptJson.CL`) |
+
+Both contexts share the base API below (`IGlobalsBase`). In **TS**, call framework APIs as `quick.X`. In **QScript** (props and QS handlers), the `quick.` prefix is dropped: `quick.store` → `store`, `quick.MM` → `MM`, `quick.Quick` → `Quick`, etc. Props are **always QScript** regardless of `HL`.
+
+> `regex`, `typeOf`, `Date`, `Number`, `JSON`, `string`, `Object`, `js`, `Math` are **QScript-only** globals (`TsFilterKeysGlobals` in `IEvaluator.ts`). In TS handlers use native equivalents or `quick.*`.
+
+> **QScript semantics that differ from JS:** (1) `||` is boolean — `a || b` returns `true`/`false`, not the value of `a` or `b`. Don't write `store.get('x') || 'default'` expecting a fallback string. (2) Property access is null-safe by default — `a.b.c.d` won't throw even if `a` is undefined; it behaves like `a?.b?.c?.d`. So defensive patterns like `(val || '')` are unnecessary and wrong in QScript props.
+
+---
+
+## Top-level (`IGlobalsBase`)
+
+```ts
+quick.LR(key, dataSource?)              // localization lookup → string. Use in EVENTS. (props use bare LR(key))
+quick.importLocalization(langCode, {key:val}, {overrite?})
+quick.go(...args)                       // shell navigation (overloaded)
+quick.getComponent(compID)              // → IComponent | null | undefined
+quick.getFormData(componentQID?)        // collect input values into an object
+quick.setFormData(compCol)
+quick.getArrangedFormData(formData, pairChar)
+quick.getArrangedNestedData(obj, pairChar)
+quick.bind(field)                       // two-way binding to a store path
+quick.this                              // the component the handler runs on
+quick.parent.props / quick.parent.events// external props/events passed into the page (Messaging ExternalProps/ExternalEvents)
+quick.return(retVal)                    // RETURN from a handler — never use native `return`
+quick.await(retVal)
+quick.getConstant(constantId)           // → Promise<string|undefined>
+```
+
+Namespaces: `Request`, `MM`, `EM`, `Quick`, `store`, `permanentStore`, `cookie`, `localStorage`, `encryptedStorage`, `sso`, `cryptography`, `encoding`, `Url`, `process`, `currentPage`, `parent`, `containerServices`, `workflow`.
+
+> **In QScript** (all props; QS handlers) drop the `quick.` prefix: `store.get('x')`, `MM.trigger('evt')`, `Quick.go(...)`, `EM.trace(...)`. The `quick.` prefix is TS-only.
+
+---
+
+## `quick.Request` — network
+
+```ts
+quick.Request.async(requestObject): Promise<INetworkResponse> | undefined
+quick.Request.download(requestObject): void
+```
+`IRequest` fields: `url`, `http` (`'GET'|'POST'|'PUT'|'DELETE'|'PATCH'|'MULTIPART'|'POSTBLOB'|'GETBLOB'`), `data`, `responseField`, `onSuccess`, `onFail`, `blockRender`, `showSuccessMessage`, `showErrorMessage`, `args`, `headers`, `withCredentials`, `timeout`.
+
+```ts
+const requestObject = {
+  url: 'https://api.example.com/data', http: 'GET',
+  onSuccess: 'onSuccessfulResponse', onFail: 'onFailedResponse',
+  blockRender: true, responseField: 'response', timeout: 2000
+};
+quick.Request.async(requestObject);
+```
+The response is available in the `onSuccess` event as `response.<responseField>`.
+
+---
+
+## `quick.MM` — Messaging (custom events)
+
+```ts
+quick.MM.trigger(eventName, parameters?)            // fire a custom event on the page component
+quick.MM.delay(eventName, { delayTime?, options? }) // fire after a delay (use instead of setTimeout)
+quick.MM.get(eventName)
+quick.MM.clearTimeout(timer)
+let result = quick.MM.trigger('myEvent');           // can return a value
+```
+
+## `quick.EM` — tracing
+
+```ts
+quick.EM.trace(message, { logType? })   // console/log output. Use instead of console.log
+```
+
+---
+
+## `quick.store` — in-memory store (4 contexts via key prefix)
+
+> **Prefix semantics (authoritative, from source):**
+
+| Prefix | Context |
+|--------|---------|
+| _(none)_ | **Page** store context (cleared on navigation) |
+| `#` | **Bag** store context |
+| `$` | **Global** store context |
+| `&` | **Shared** store context |
+
+```ts
+quick.store.set('key', value);     quick.store.get('key');
+quick.store.set('#bagKey', v);     quick.store.set('$globalKey', v);   quick.store.set('&sharedKey', v);
+quick.store.getAll(name); quick.store.delete(name); quick.store.deleteAll(name);
+```
+
+> ⚠️ The earlier community docs mislabeled these (`$`=persistent, `#`=session, `&`=cache). The source defines them as **Page / Bag(#) / Global($) / Shared(&)**. For cross-session persistence use `quick.permanentStore`, not a store prefix.
+
+## Other storage
+
+```ts
+quick.permanentStore.set({key, value}) / .get(key) / .delete(key) / .getAll() / .createOrChangeStore(name) / .deleteStore(name)  // async, IndexedDB-backed persistence
+quick.cookie.set(key, {value, expire}) / .get(key) / .getAll() / .delete(key)
+quick.localStorage.set/get/clear/delete
+quick.encryptedStorage.set/get/clear/delete   // mobile only (iOS Keychain / Android EncryptedSharedPreferences)
+```
+
+---
+
+## `quick.Quick` — the large utility namespace
+
+### Navigation
+```ts
+quick.Quick.go("<<qjson:UNIQUE-ID>>", { newTab?, store?, mobileAnimation? })
+quick.Quick.goHistory(step)      // +n forward / -n back
+quick.Quick.back()
+quick.Quick.redirect(url, { target? })   // "_self"|"_blank"|"_parent"|"_top"
+```
+
+### Alerts (always include `actionButtons`)
+```ts
+quick.Quick.alert({
+  title?, text?,
+  category?: 'Warning'|'Info'|'Success'|'Error',
+  actionButtons?: [{ name, type, clickEventName? }],   // type: 'Confirm'|'Cancel'|...
+  error?: { errorMessage?, errorCode?, errorSource? },  // errorSource: 'Page'|'Network'|'Validation'
+  additionals?: { props?, events? }
+});
+quick.Quick.closeAlert();
+```
+
+### Validation
+```ts
+quick.Quick.validate(compID, displayAlertBox, _unused?, { skipChildrenIfInvisible? })   // → true | undefined  (compID = P.ID.H, the runtime ID — NOT the _Editor.eID)
+quick.Quick.validateAll(displayAlertBox, _unused?, { skipChildrenIfInvisible? })
+quick.Quick.reset(compID, { triggerChangeEvent? })
+quick.Quick.resetValidation(compID)
+```
+Validation rule builders (used in a component's `rules` prop, as a QScript array):
+```ts
+quick.Quick.validation.required(message?)
+quick.Quick.validation.minLength(len, message?, { disableNewlineOnCount? })
+quick.Quick.validation.maxLength(len, message?, { disableNewlineOnCount? })
+quick.Quick.validation.email(message?)
+quick.Quick.validation.iban(message?)      quick.Quick.validation.IBANNumOnly(message?)
+quick.Quick.validation.regex(regexVal, message?)
+quick.Quick.validation.tckn(message?)       quick.Quick.validation.vkn(message?)
+```
+> Authoritative rule set — note there is **no** `phone` rule here (use `format` on the input for phone masking, plus `regex`). `tckn`/`vkn` are Turkish ID/Tax-number validators.
+
+### Dynamic components
+```ts
+quick.Quick.createComponent({ templateCompQID, newCompQID, dataSource?, place?, placeQID?, childName? })  // place: ElementLocation = 'Before'|'After'|'Default'
+quick.Quick.createChildren({ parentCompQId, templateChildName, newChildName? })
+quick.Quick.findCreateComponentRelative(sourceComp, targetCompID)
+quick.Quick.deleteComponent(componentInstance)          // IComponent or DOM element
+quick.Quick.updateComponent(comp?)
+quick.Quick.getComponentIdByInstance(componentInstance)
+quick.Quick.setComponentsProperty(compId, propertyName, propertyValue)
+quick.Quick.setComponentClass(componentInstance, classesArray)
+```
+
+### Formatting / dates / money
+```ts
+quick.Quick.toMoney(number, formatType?, opt?, bigDecimal?)
+quick.Quick.toDecimal(value, radixPoint?)        quick.Quick.toBigNumber(value)
+quick.Quick.toDate(dateString, formatType?)      quick.Quick.dateFromNow(dateString, formatType?)
+quick.Quick.toLongDate(date, fmt?)  toShortDate  toLongTime  toShortTime
+```
+
+### Misc
+```ts
+quick.Quick.copy(object)                  // deep clone
+quick.Quick.copyToClipboard(value)
+quick.Quick.download({ data, name })      // base64 download
+quick.Quick.shareData({ data, name })
+quick.Quick.exportToXlsx({ fileName, sheetList:[{headers, items, sheetName?}] })
+quick.Quick.xlsxToJson(excelToJsonData)
+quick.Quick.loading.show() / .hide()
+quick.Quick.render.block() / .resume()
+quick.Quick.screen.toTop({elementId?}) / .scrollIntoView(comp) / .intoView(comp) / .YOffset / .XOffset
+quick.Quick.setLanguage(LRType) / .getLanguage()
+quick.Quick.setPageTitle(value) / .getPageTitle() / .getFavicon()
+quick.Quick.theme.setTheme(name, isLight?) / .getThemeList() / .addTheme(n) / .removeTheme(n)
+quick.Quick.region.setRegion(name) / .getRegionList() / .getCurrentRegion()
+quick.Quick.platform.isMobile() / .isWeb() / .getPlatformType() / .getDeviceId() / .getClientInfo()
+quick.Quick.getCurrentPosition()          // → Promise<ILocationPosition>
+quick.Quick.environment.variable["key"]
+quick.Quick.config.get(key)
+quick.Quick.network.isConnected
+quick.Quick.isEditMode
+```
+
+---
+
+## QScript-only globals (available bare inside `HL:"QS"` handlers/props)
+
+```ts
+Math.floor(x)  Math.random(min,max)  Math.round(n, decimals)  Math.findIndex(arr, key, str)
+Date.now()  Date.parse(v, month)  Date.time()  Date.compare(a,b)  Date.ISOString()  Date.differenceInDays(a,b)  Date.differenceInMonths(a,b)  Date.getTimezoneOffset(d)
+Number.parse(v)  Number.parseFloat(v)  Number.mod(a,b)
+JSON.parse(str)
+string.space  string.replace(str, search, replace)
+regex(value)            // build a RegExp
+typeOf(value)           // 'string'|'number'|'boolean'|'object'|...
+Url.resolve({url})  Url.getDeepLinkParams()  Url.getUrl()
+```
+
+> ⚠️ Native `Date.now()`/`new Date()`/`Math.random()` behave as defined above inside QScript via these wrappers. In **TS** handlers you have normal TS but should still avoid forbidden browser APIs (see scripting knowledge doc).
+
+---
+
+## `quick.cryptography` / `quick.encoding` / `quick.sso`
+
+```ts
+await quick.cryptography.hash({ data, algorithm })           // SHA1/256/384/512
+await quick.cryptography.encrypt({ data, key, algorithm })   // RSAOAEP/AESCTR/AESCBC/AESGCM
+await quick.cryptography.decrypt({ encryptedData, iv, key, algorithm })
+quick.encoding.atob(s)  quick.encoding.btoa(s)
+quick.sso.start({ clientId, authorizeEndpoint, redirectUri, scope })
+quick.sso.validate({ urlParams, tokenEndpoint, type, onSuccess, onFail })
+```
+
+## Workflow / process (advanced)
+```ts
+quick.workflow.RunFunction({ flowId, input, ... })  quick.workflow.Commit()
+quick.process.getMetadata() / .setMetadata({Metadata}) / .changeProcessMetadata(key, onSuccess)
+quick.RunBefunc({ befuncId, input })
+quick.currentPage.isRenderCompleted()
+```
+
+---
+
+## Golden rules for handler code
+
+1. **Never `return`** — use `quick.return(value)` / `quick.return`.
+2. **Event handlers are always TypeScript — set `"HL": "TS"` on every handler.** (The omitted-`HL` runtime default of `QS` applies to property/binding expressions, not `E` handlers.)
+3. In **props**, localization is bare `LR('key')`; in **events**, `quick.LR('key')`.
+4. Avoid browser globals in handlers; use `quick.MM.delay` (not `setTimeout`), `quick.EM.trace` (not `console`), `quick.Quick.download` (not anchor downloads).
+5. Read a service response in the `onSuccess` event as `response.<responseField>`.
+6. **QScript prefix rule:** In QScript (props + QS handlers) write `store.get(...)`, `MM.trigger(...)`, `Quick.go(...)` — no `quick.` prefix. This doc shows `quick.X` throughout because it is the TS form; strip `quick.` when writing QScript.
+7. **QScript `||` is boolean:** `a || b` returns `true`/`false` in QScript, not a fallback value. For a conditional expression use `if(a){a}else{b}`. Also, property paths are null-safe — no need for `?? ''` or `|| ''` guards.

package/dist/studio-cli/src/.ai-kit/reference/styling-system.md

@@ -0,0 +1,193 @@
+# Styling System — Authoritative Reference (`S` / `SC` / `SA`)
+
+> ⚠️ **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? → [AGENT_GUIDE Step 0](../AGENT_GUIDE.md).
+>
+> **This file is the `S` track** (`S` / `SC` / `SA` schema). Authoring how-to: [../knowledge/04-styling.md](../knowledge/04-styling.md). On a **legacy** page instead (where `S` does not render) → [layout-system.md](layout-system.md).
+
+## Why styling = the `S` object, not CSS
+
+Quick runs on **Web, Android, and iOS**. CSS only exists on Web (DOM). Mobile renders native views. So per-component styling is expressed as a **platform-neutral style object `S`** on the component node, which each platform applies natively:
+
+- **Web** (`StyleManager`): `S` → CSS rules with `@media` ranges + `[q_UID='…']` selectors (some components have specialized style handlers).
+- **Mobile** (`bridgets componentManager`): `S` → flattened to the single breakpoint range matching the device → promoted to top-level props → `col` converted to flex-basis %, `boxShadow` simplified → passed to the native bridge `nb_createComponent`.
+
+**Consequence:** a project Style File (CSS) styles Web only. To style **cross-platform**, you must use `S` (the Style tab). Author `S`, not CSS, for component visuals.
+
+## 1. Shape of `S`
+
+```ts
+// ICompJson.S : StyleValue
+type StyleValue = Record<string, string | boolean | undefined | Record<string,string>>;
+```
+
+In practice `S` is keyed by **resolution range**, each holding camelCase CSS-like params:
+
+```json
+"S": {
+  "xs-xl": { "backgroundColor": "#1976D2", "paddingLeft": "16px", "fontColor": "#ffffff" },
+  "md-xl": { "fontSize": "18px", "height": "48px" }
+}
+```
+
+- A range key is `"<from>-<to>"` over breakpoints `xs<sm<md<lg<xl`. Default full range `"xs-xl"`.
+- A narrower range (e.g. `"md-xl"`) overrides the base for those device widths (this is "Layout Multiplexing"). Empty string `""` = unset (use component default).
+- Breakpoint widths: `xs` 0, `sm` 600, `md` 960, `lg` 1264, `xl` ∞ (px) — `StyleHelper.matchSizeValue`.
+
+> Note: `S` ranges are inclusive spans over the breakpoints (`"xs-xl"`, `"md-xl"`, …), unlike the legacy `dOpt` keys which are **single** breakpoints.
+
+## 2. Per-component style definitions (`componentStyleList`)
+
+Each component declares which style fields it supports (its `componentStyleList`), grouped into the Style-tab sections: **LAYOUT**, **TEXT** (often `inheritedStyle:true`), **APPERANCE** (sic — that's the literal key). Each group has typed editors (`type` from `COMPONENT_STYLE_TYPE`) that emit specific `param` keys with defaults. **The per-component flattened form of this data — every supported `S` param + default — is bundled in [component-styles.json](component-styles.json); that file is the single source to consult when authoring `S`.**
+
+> **A `default` in `component-styles.json` is only the Style-tab's pre-filled suggestion — it is NOT applied automatically.** Nothing merges these defaults at render; a param takes effect only when you write that `S` key on the node yourself. If you want a listed default value (e.g. `VBtn` `fontColor:#ffffff`), write it into `S` explicitly. (Same rule as [../knowledge/04-styling.md](../knowledge/04-styling.md) — the two docs agree on this.)
+
+### Editor types → params they emit (`COMPONENT_STYLE_TYPE`)
+| Editor `type` | Emits these `S` params |
+|---------------|------------------------|
+| `break-point-picker` | `break-point` (the Style-tab's range **selector**, e.g. `"xs-xl"` — it becomes the `S` range **key**, never a param **inside** a range. **Never write `"break-point"` into an `S` range** — it is not in `component-styles.json` and it has frozen the Web runtime.) |
+| `box-layout` | `marginTop/Right/Bottom/Left`, `paddingTop/Right/Bottom/Left` |
+| `inner-box-layout` | `innerMargin*`, `innerPadding*` (e.g. VTextField) |
+| `padding-input` | `inputPaddingTop/Right/Bottom/Left` |
+| `size` | `width`, `height`, `maxWidth`, `maxHeight`, `minWidth`, `minHeight`, `unlink`, `unlinkMax`, `unlinkMin`, `isSizeCollapsed` |
+| `grid-column` | `col` (1–12 string; `0`→hidden) |
+| `layout-chooser` / `content-direction` | `flexDirection` (`row`/`column`), `alignItems`, `justifyContent` |
+| `font-picker` | `fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `combinedFont`, `ThemeFont` (+ `fontColor`) — and multi-part variants (`labelFontColor`, `prefixFontSize`, …) |
+| `color-picker` | one color param (e.g. `backgroundColor`, `fontColor`, `iconColor`); `allowGradient:true` enables gradients |
+| `box-shadow` | `boxShadow` (CSS shadow string) |
+| `border` | per side: `border{Top|Right|Bottom|Left}Style`, `…Width`, radius `border{TopLeft|TopRight|BottomLeft|BottomRight}Radius`, plus `defaultBorderColor`, `boxSizing`, `sides` |
+| `display` | `position`, `top`, `bottom`, `left`, `right`, `zIndex` |
+| `layout-input` / `basic-input` | a single numeric param (e.g. `lineHeight`) |
+| `display-text-align` | `textAlign` |
+| `display-text-decoration` | `textDecorationLine`, `textDecorationStyle`, `textDecorationColor` |
+
+### `IComponentDefinition` fields (per component)
+- `componentStyleList` — the grouped style fields above.
+- `propMigrateList` — **old prop → style key** migration. E.g. `VBtn`/`VCard`: `color → backgroundColor`; `VTextField`: `color → labelDefaultFontColor`, `height → height`. (This is why setting a legacy `color` prop maps into `S`.)
+- `inheritedChildList` (→ node `SC`) — cascade a parent style to child sub-components (see §4). Bundled per component in [component-styles.json](component-styles.json) as the `inheritedChildList` key.
+- `propRemoveList` — deprecated props hidden by the editor (e.g. `VBtn`: `small`,`large`,`text`).
+- `parentListToBlockStyle` — under these parents the **Style tab UI** hides the child's own style editing (the parent's tab drives it). E.g. `QLabel` inside `VBtn`/`VChip`/`VTabs`/`VStepper`/…; `VBtn` inside `VBtnToggle`/`VSlideGroup`. **Authoring note:** the serialized page still carries the child's own `S` (the editor writes it — see the button label in [../examples/style/MMDelay.qjson](../examples/style/MMDelay.qjson)); per rule S3 you write the child's full-default `S` alongside the parent's `SC`.
+- `extendedDefaulStyleList` — extra defaults applied at render.
+
+## 3. Property taxonomy (the camelCase keys you put in `S`)
+
+**Spacing:** `marginTop|Right|Bottom|Left`, `paddingTop|Right|Bottom|Left` (+ `inner*`, `inputPadding*`).
+**Size:** `width`, `height`, `maxWidth`, `maxHeight`, `minWidth`, `minHeight`; flags `unlink`, `unlinkMax`, `unlinkMin`, `isSizeCollapsed` (units: px/%/em/rem).
+**Flex/grid:** `col` (1–12), `flexDirection` (`row`/`column`), `alignItems`, `justifyContent`.
+**Text:** `fontColor`, `fontFamily`, `fontSize`, `fontStyle` (`normal`/`italic`), `fontWeight` (`100`–`900`), `combinedFont` (auto `Family-Weight`, e.g. `Roboto-Regular`), `ThemeFont`, `lineHeight`, `textAlign`, `textDecorationLine|Style|Color`. Multi-part components prefix the part: `labelFontColor`, `prefixFontSize`, `PHFontColor` (placeholder), `inputFontColor`, `errorMessageFontColor`, …
+**Colors:** `backgroundColor` (gradient-capable), `fontColor`, `iconColor`; state variants `disabledBackgroundColor`, `hoverColor`, `activeBackgroundColor`, `selectedBackgroundColor`; icon variants `appendIconColor`, `prependInnerIconColor`, `*ActiveIconColor` (component-specific).
+**Border:** `border{Top|Right|Bottom|Left}Style` (`solid`/`dashed`/`dotted`), `…Width` (px), `border{TopLeft|TopRight|BottomLeft|BottomRight}Radius`, `defaultBorderColor`, `boxSizing`, `sides` (CSV `"Top,Right,Bottom,Left"`).
+**Shadow:** `boxShadow` (and `innerBoxShadow`, `hoverShadow`, … per component).
+**Position:** `position`, `top`, `bottom`, `left`, `right`, `zIndex`.
+
+Component-specific params exist (e.g. `VStepper`: `activeStepCircleColor`, `inactiveStepNumberFontColor`; `VTabs`: `tabsBarBackgroundColor`, `activeTabLabelFontColor`; `VDatePicker`: `dateItemSelectedBackgroundColor`). To discover the exact supported set + defaults for a component, read its block in [component-styles.json](component-styles.json) — that file is bundled with the kit and is the only source to use.
+
+### Representative editor-suggested defaults (illustrative only)
+
+> These are Style-tab pre-fill suggestions, **not** values applied automatically — write them into `S` explicitly if you want them. This table is illustrative; the authoritative per-component param list + defaults is [component-styles.json](component-styles.json). **Where this table and `component-styles.json` disagree, `component-styles.json` wins** — never set a param the component's JSON block doesn't list.
+
+| Component | Notable suggested defaults |
+|-----------|------------------|
+| `VBtn` | `backgroundColor:#1976D2`, `fontColor:#ffffff`, `paddingLeft/Right:16px`, border radius `4px`, border width `0px`, `textAlign:center` |
+| `QLabel` | `fontColor:#000000`, `fontFamily:Roboto`, `fontSize:16px`, `fontWeight:400`, `lineHeight:20px`, `textAlign:left` |
+| `VCard` | `backgroundColor:#ffffff`, elevation `boxShadow` set, radius `4px` |
+| `VCol` | `padding*:12px`, `flexDirection:column` |
+| `VContainer` | box-layout + size + position |
+| `VTextField` | five font groups (label/prefix/placeholder/input/errorMessage), inner border (`innerBorderBottomWidth:1px`, `innerDefaultBorderColor:#0000006b`), `activeBorderColor:#1976d2`, icon colors `#686868`/active `#1976d2` |
+
+## 4. Child-style inheritance: `SC` (`IStyleChild`)
+
+```ts
+type IStyleChild = { [styleParam: string]: { [childType: string]: string } };
+```
+Cascades a parent's style param to a typed child as a (possibly renamed) param. Driven by each component's `inheritedChildList` — **bundled per component in [component-styles.json](component-styles.json)** (the `inheritedChildList` key of the component's block, same `{ styleParam: { ChildType: childParam } }` shape; it is SC mapping data, **not** an `S` param). When authoring, copy that block into the node's `SC` as-is; components without one get no `SC`. Example — `VBtn` sets its text color and pushes it into its label/icon children:
+
+```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" } } }
+```
+
+This is `VBtn`'s **complete** `inheritedChildList` — an `SC` is always the **whole** block copied from [component-styles.json](component-styles.json), never a hand-picked subset (the validator flags `incomplete-SC`).
+This is how a parent pushes its colors into the **text inside a button**, the **icon color**, etc. **It complements — does not replace — the child's own `S`:** per rule S3 the child label/icon also carries its own `S` with its full default set (values matched to the design, e.g. `fontColor:#ffffff` on a primary button's label), exactly as the editor serializes it. Keep both: child `S` + parent `SC`.
+
+## 5. Styled Components (`SA`)
+Reusable named styles created from the Style tab; the node references them via `SA: string[]`. Editing the styled component updates every consumer. Shareable across apps via modules. Normally produced by Studio, not hand-authored.
+
+## 6. Hand-authoring guidance
+- Put **everything** — visual styling (colors, fonts, borders, shadows, exact sizes) and layout (grid/flex/spacing) alike — in `S`, keyed by resolution range. Use `"xs-xl"` for "all sizes", add narrower ranges to override. Do not author `O.layout` (`dOpt`+`class`) here — that is the legacy mechanism, not used on `S`-system pages.
+- Not every component's style schema carries flex params: `VCol`'s `flexDirection`/`alignItems`/`justifyContent`/`col` are real, supported `S` params (check the `VCol` block in `component-styles.json`) and are what drive its rendered flex axis. A `VCol` left with no `S.flexDirection` defaults to a row axis, not the `column` shown as that param's editor-default suggestion — write it explicitly when you want children to stack. Components without those params (`VRow`/`VCard`/`VContainer`, …) generally don't need a direction override; if a design genuinely needs something their `S` schema can't express, the **Web-only, last-resort** fallback is the component's own `class` prop — there is **no** equivalent fallback on Mobile, so restructure with an `S`-capable component (typically a `VCol`) instead.
+- For a container's text/icon child (button label, etc.): give the child its own full-default `S` (values matched to the design) **and** add the parent's `SC` mapping (mirror the component's `inheritedChildList`).
+- **Emit every default (rule S3):** a placed component's `S` includes every param that carries a `default` in its [component-styles.json](component-styles.json) block — the default value, or your override. Params with no default are optional.
+- Values are camelCase keys with string values; sizes accept `px`/`%`/`em`/`rem`; `""` = unset.
+- For the exact supported params + defaults of a specific component, consult its block in [component-styles.json](component-styles.json) (bundled with the kit — never a source file outside this workspace).
+- Theme colors/fonts (Themes Settings) appear in the Style tab; prefer them for brand consistency — they're still values you put in `S`, not a separate mechanism.
+
+## 7. Containment rules (shared, editor-enforced)
+
+> Kept in sync with the identical block in [../knowledge/03-layout-and-slots.md](../knowledge/03-layout-and-slots.md) — update both. (Containment is enforced identically regardless of style era.)
+
+| Rule | From |
+|------|------|
+| `VCol` must be a child of `VRow`; cannot be at page root | `VColExtension.acceptableParentComps={VRow}` + `restrictedComponents` + `layout.md` |
+| `VRow` accepts only `VCol` children | `VRowExtension.acceptableChildComps={VCol}` |
+| `VFooter` accepts only `VContainer` children | `VFooterExtension.acceptableChildComps={VContainer}` |
+
+Other components have no hard accept-list, but container components with item parts use fixed child generators (place `VTab`/`VTabItem` in `VTabs`, `VStepperStep`/`VStepperContent` in `VStepper`, etc.). Canonical page wrapper: `VContainer > VRow > VCol > content`. For a **newly-created page this `VContainer` content root is required**: wrap all UI content in a single top-level `VContainer`, with only `Messaging` and an optional service component as other top-level `pJson` siblings. This is a **new-page rule only** — do **not** retrofit a `VContainer` root onto an existing page unless the user explicitly asks. Machine-readable: [component-index.json](component-index.json) `containmentRules`.
+
+## 8. Breakpoint device ranges (shared)
+
+> Kept in sync with the identical table in [../knowledge/03-layout-and-slots.md](../knowledge/03-layout-and-slots.md) — update both. `S` ranges (e.g. `"xs-xl"`, `"md-xl"`) are built from these same device boundaries.
+
+| Key | Device | Min px | Max px |
+|-----|--------|--------|--------|
+| `xs` | Mobile | 0 | 600 |
+| `sm` | Tablet | 600 | 960 |
+| `md` | Laptop | 960 | 1264 |
+| `lg` | Desktop | 1264 | 1904 |
+| `xl` | TV | 1904 | ∞ |
+
+## 9. `class` token → `S` equivalent (audit reference)
+
+> Kept in sync with [mapping-S-vuetify-class.md](mapping-S-vuetify-class.md) — update both. This table is a **live dependency** of the class-prop audit rule (§6 above and the `S`-system pre-sync checklist at the end of [../knowledge/04-styling.md](../knowledge/04-styling.md)): before writing any `class` token as the Web-only last resort, check it here — if an `S` equivalent exists, write `S` and drop the token.
+
+**Has an `S` equivalent (don't leave in `class` if `S` is set):**
+
+| Class token | `S` equivalent |
+|---|---|
+| `pa-N` / `px-N` / `py-N` / `pt-N`/`pb-N`/`pl-N`/`pr-N` | `padding{Top,Right,Bottom,Left}` = `"Npx"` (Vuetify step `N` × 4px) |
+| `ma-N` / `mx-N` / `my-N` / `mt-N`/`mb-N`/`ml-N`/`mr-N` / `mx-auto` | `margin{Top,Right,Bottom,Left}` = `"Npx"` / `"auto"` |
+| `fill-height` | `height: "100%"` |
+| `d-flex` / `flex-row` / `flex-column` / `flex-row-reverse` / `flex-column-reverse` | `flexDirection: "row"/"column"/"row-reverse"/"column-reverse"` (`VCol`-only param) |
+| `justify-start/center/end/space-between/space-around` | `justifyContent` (`VCol`-only param) |
+| `align-start/center/end/baseline/stretch` | `alignItems` (`VCol`-only param) |
+| `text-h1`…`h6`, `text-subtitle-*`, `text-body-*`, `text-button`, `text-caption`, `text-overline` | `fontSize` + `fontWeight` + `lineHeight` |
+| `font-weight-*` | `fontWeight: "100"…"900"` |
+| `font-italic` | `fontStyle: "italic"` |
+| `text-left/center/right/justify` | `textAlign` |
+| `text-decoration-none/underline/line-through` | `textDecorationLine` |
+| `<color>--text` | `fontColor` |
+| `elevation-0`…`24` | `boxShadow` |
+| `rounded*` | `borderTopLeftRadius`+`borderTopRightRadius`+`borderBottomLeftRadius`+`borderBottomRightRadius` |
+| theme background color classes | `backgroundColor` |
+
+**No `S` equivalent** (informational — leave out of the conflict check): `text-uppercase/lowercase/capitalize`, `text-truncate`, `text-no-wrap`, `d-none/d-block/d-inline` (visibility), `flex-grow-*`/`flex-shrink-*`, `order-*`, `overflow-*`, responsive/breakpoint variants (`d-md-flex`, `pa-md-4` — `S` manages breakpoints separately via range keys).
+
+Full token-by-token table (Turkish) + the legacy-migration framing: [mapping-S-vuetify-class.md](mapping-S-vuetify-class.md).
+
+Practical how-to and copy-paste patterns: [../knowledge/04-styling.md](../knowledge/04-styling.md).