@stechquick/studio-cli 4.2.0-2 → 4.2.0-3

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/reference/events-system.md

@@ -0,0 +1,96 @@
+# Events & Scripting System (`E`)
+
+> Extracted from the runtime's event model, messaging/rendering managers and compiler.
+
+## 1. `IEventJson` and what each flag DOES at runtime
+
+```ts
+interface IEventJson { H; P?; HF?; I?; C?; PE?; TO?; EV?; HL?; SM?; }
+```
+
+| Field | Runtime behavior |
+|-------|------------------------------|
+| `H` | Handler: code string (QS/JS/TS) **or** a Flow model object (`HL:"FL"`). |
+| `P` | Parameter declaration. **QS** → names only `"x,y,z"`; **TS/JS** → `"x:string,y:any"`. |
+| `HL` | Event handler language. **Use only `"TS"`** for `E` handlers. `QS` belongs to properties/bindings, not events. Compiled handlers get their `HL` rewritten to the compiled lang. |
+| `I` | **Immediate.** If `I` (or not currently rendering) the handler runs **now**; otherwise it's deferred to end-of-render. |
+| `C` | **Custom event.** Triggered via `quick.MM.trigger`. For `C:true`, trigger parameters are passed as the **dataSource** (array → first element; object → whole object), merged over the event's scope; not name-mapped like DOM events. |
+| `PE` | **Property event.** Passed into the component as a **prop callback** (the component calls it — e.g. chart `labelFormatter`/`tooltipLabel`). |
+| `TO` | **Trigger order** for post-render events. Deferred ordered callbacks run **descending** by `TO` — higher `TO` fires first. |
+| `EV` | **Externally visible.** Exposed to a parent page as `quick.parent.events.<name>`. |
+| `HF` | **Handler file** (TS 2.0): `H` is a function name resolved in the page's script file instead of inline code. |
+| `SM` | Source map (base64) for TS debugging. |
+
+## 2. Lifecycle (on the `Messaging` / page component)
+
+Emitted in the `Messaging` constructor in order, then `Restored` on back-navigation:
+
+1. **PreRender** — before rendering. **Canonical place to initialize store + trigger the first fetch.**
+2. **EndRender** — after render setup.
+3. **PostRender** — after DOM render; deferred handlers run here, ordered by `TO` (descending).
+4. **Restored** — when the page resurfaces from history (back navigation); re-runs dependency watchers and cascades to child Messaging components.
+5. **OnDeviceBack** — mobile hardware back button.
+
+Custom events are also defined on `Messaging` and invoked anywhere via `quick.MM.trigger`. Keep initialization in **one** lifecycle hook to avoid duplicate work.
+
+## 3. Custom events & parameters
+
+```ts
+quick.MM.trigger('eventName', [ { a:1, b:2 } ]);   // array → first element is dataSource
+quick.MM.trigger('eventName', payloadObject);       // object → whole object is dataSource
+quick.MM.delay('eventName', { delayTime: 500, options: [...] });
+let r = quick.MM.trigger('eventName');              // can return a value (via quick.return)
+```
+- A triggered event must be declared with `"C": true`.
+- **DOM/native event** params come via `P` (name-mapped). **Custom event** payload comes via the dataSource (declare the fields you read).
+- Don't duplicate a name in both `P` and a `declare let`/`let` inside `H`.
+- A custom event returns whatever the handler passes to `quick.return(value)`.
+
+## 4. Property events (`PE:true`)
+Become component callback props. Chart formatters are the canonical use:
+```json
+"labelFormatter": { "H": "quick.return(value + '%');", "PE": true,
+  "P": "value:any,context:{ dataIndex:number; dataset:any; }", "HL": "TS" }
+"tooltipLabel": { "H": "quick.return(context.formattedValue + ' - ' + context.label);", "PE": true,
+  "P": "context:{ formattedValue:string; label:string; }", "HL": "TS" }
+```
+
+## 5. External events / parent communication (`EV:true`)
+A page exposes events/props to a parent (e.g. when embedded via `CustomComponent`/`RenderingComponent`) through `Messaging` `ExternalEvents`/`ExternalProps`. The parent calls:
+```ts
+quick.parent.events?.someEvent(args);   // events the child marked EV:true
+quick.parent.props?.someProp;           // props the parent passed in
+```
+
+## 6. Scripting languages & execution
+
+Event handlers use **TypeScript only**: author every `E` handler with `"HL": "TS"`. It is compiled to JavaScript for `cJson`. Do not use `QS`, `JS`, `FL`, or `GUI` for events.
+
+`QS` remains available for **properties/bindings** (`P`); it is not an event-handler language in this authoring model.
+
+- **`quick.return` is exception-based control flow** — that's why native `return` doesn't work in handlers. `quick.return(v)` throws a `quickReturnExc` caught by the evaluator, yielding `v` as the handler result.
+- **Object literals need `};`** before the next statement in a TS handler.
+- **Forbidden browser globals** (`window`, `document`, `console`, `setTimeout`, `setInterval`, `fetch`) — use `quick.EM.trace`, `quick.MM.delay`, `quick.Request.async`, `quick.Quick.download`.
+- Line breaks in `H` are `\r\n`.
+
+## 7. Async / network integration
+- Handlers may `await`; event completion waits for all internal QPromises before firing the completion callback.
+- `quick.Request.async({ url, http, data, responseField, onSuccess, onFail, blockRender })`: on resolve, the `onSuccess` event fires with the response merged into the global `response` object (read `response.<responseField>`); on reject, `onFail` fires with `{ error }` (`error.response`, `error.message`). Both inherit the originating event's immediacy. Full service patterns: [../knowledge/services.md](../knowledge/services.md).
+
+## 8. Common event param signatures
+| Component | Event | `P` |
+|-----------|-------|-----|
+| VBtn / clickable | `click` | `mouseEvent:unknown \| undefined` |
+| inputs (VTextField, …) | `input` / `change` | `value:any` (input) / value (change) |
+| inputs | `blur` | `event:FocusEvent` |
+| VCheckbox / VSwitch | `change` | `value:boolean` |
+| VSelect | `change` | `value:any` |
+| VPagination | `input` | `number:number` (1-based; first line `quick.this.qValue = number;`) |
+| VDialog | `click:outside` | — (set `qValue=false`) |
+| VDataTable | `click:row` | `index:any,row:any` — `index`/`item` is the row data (`IVDataTableClickRow`: `item, headers, isSelected, isExpanded, select, expand`) |
+| charts | `labelFormatter`/`tooltipLabel`/`onClick` | `PE:true` + chart-specific params |
+
+## 9. Compilation
+Authoring rule: the compiler receives event source with `HL:"TS"`, compiles it, and writes JavaScript plus `HL:"JS"` into `cJson`. `QS` is used for property/binding expressions, not event handlers. Errors carry `{componentType, componentId, fieldName, fieldType}`. These script errors surface when the page is compiled — see [../knowledge/validation.md](../knowledge/validation.md).
+
+Practical how-to and the `quick.*` call list: [../knowledge/events-and-scripting.md](../knowledge/events-and-scripting.md) + [quick-api.md](quick-api.md).

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/reference/layout-system.md

@@ -0,0 +1,15 @@
+# STOP — legacy pages cannot be edited in this workspace
+
+If the target page's root-level `opt.V` is **missing or `< 2.0`**, it is a legacy page. **Do not edit it.** Tell the user the page is legacy and cannot be authored from a mobile workspace, and make no changes.
+
+There is no way to author it correctly here: mobile does not apply the legacy `O.layout` css mechanism, so the page cannot be restyled through it, and `S` does not render on a `V < 2.0` page either. Both style systems are dead ends on that page. Converting it is a migration, not an edit — it needs a decision from the user, not a side effect of the task you were given.
+
+## This is not about stray legacy fragments
+
+A page with `opt.V >= 2.0` that merely *carries* some `O.layout` (`dOpt`/`class`) is **not** a legacy page. Studio's editor injects those fragments into some components on its own, and on mobile they have no effect at all. That page is an ordinary `S` page:
+
+- Author its design in `S`, as normal — go back to `s-track.md`.
+- Never read `O.layout` to work out how the page currently looks; it does not affect the rendering.
+- When you edit such a page, strip its `O.layout` (`dOpt`/`class`) so the page comes out clean.
+
+The test is **`opt.V`**, not whether legacy css is present.

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/reference/mapping-S-vuetify-class.md

@@ -0,0 +1,103 @@
+# S ↔ Vuetify v2 class mapping table
+
+> **This table serves two purposes:** (1) *understanding* what a class token on a `cssClass`/legacy page means, and (2) translating class/`dOpt` tokens into `S` params when *migrating* a legacy page to the `S` system. On an `S`-system page (a new page, or `opt.V >= 2.0`) author the design directly in `S` — see [../knowledge/styling.md](../knowledge/styling.md). For authoring a legacy page see [../knowledge/styling-legacy.md](../knowledge/styling-legacy.md).
+>
+> **RULE:** never write a style in `class` when you have written it in `S`. If
+> both are present, **remove the class token** (`S` is the source of truth). This
+> document lists only class tokens that DO have an `S` equivalent — the conflict
+> audit applies to these alone.
+>
+> **Spacing formula:** a Vuetify `N` value = `N × 4px`
+> (`pa-0`=0, `pa-1`=4px, `pa-2`=8px, `pa-3`=12px, `pa-4`=16px, `pa-5`=20px …
+> `pa-16`=64px). Negatives (`n1`…) are minus px. Cross-check: the `VCol` default
+> `paddingTop: "12px"` ↔ `pa-3`.
+>
+> For Vuetify **v2**.
+
+## 1. Spacing (padding / margin)
+
+| Class token | `S` equivalent |
+|---|---|
+| `pa-N` | `paddingTop` + `paddingBottom` + `paddingLeft` + `paddingRight` = `"Npx"` |
+| `px-N` | `paddingLeft` + `paddingRight` = `"Npx"` |
+| `py-N` | `paddingTop` + `paddingBottom` = `"Npx"` |
+| `pt-N` / `pb-N` / `pl-N` / `pr-N` | `paddingTop` / `paddingBottom` / `paddingLeft` / `paddingRight` = `"Npx"` |
+| `ps-N` / `pe-N` | `paddingLeft` / `paddingRight` = `"Npx"` (LTR) |
+| `ma-N` | `marginTop` + `marginBottom` + `marginLeft` + `marginRight` = `"Npx"` |
+| `mx-N` | `marginLeft` + `marginRight` = `"Npx"` |
+| `my-N` | `marginTop` + `marginBottom` = `"Npx"` |
+| `mt-N` / `mb-N` / `ml-N` / `mr-N` | `marginTop` / `marginBottom` / `marginLeft` / `marginRight` = `"Npx"` |
+| `mx-auto` | `marginLeft` + `marginRight` = `"auto"` |
+| `mt-nN` … (negative) | the matching margin = `"-Npx"` |
+
+## 2. Size
+
+| Class token | `S` equivalent |
+|---|---|
+| `fill-height` | `height: "100%"` |
+
+> Note: Vuetify v2 has no `w-100`/`h-100`. Width/height always come from `S`:
+> `width`, `height`, `maxWidth`, `minWidth`, `maxHeight`, `minHeight`.
+
+## 3. Layout / Flex (flex containers only: VCol / VRow / VContainer)
+
+| Class token | `S` equivalent |
+|---|---|
+| `d-flex` / `d-inline-flex` | flex container on → conflicts if `flexDirection` is set |
+| `flex-row` | `flexDirection: "row"` |
+| `flex-column` | `flexDirection: "column"` |
+| `flex-row-reverse` | `flexDirection: "row-reverse"` |
+| `flex-column-reverse` | `flexDirection: "column-reverse"` |
+| `justify-start / center / end / space-between / space-around` | `justifyContent: "flex-start / center / flex-end / space-between / space-around"` |
+| `align-start / center / end / baseline / stretch` | `alignItems: "flex-start / center / flex-end / baseline / stretch"` |
+
+## 4. Text / Typography
+
+| Class token | `S` equivalent |
+|---|---|
+| `text-h1 … text-h6`, `text-subtitle-1/2`, `text-body-1/2`, `text-button`, `text-caption`, `text-overline` | `fontSize` + `fontWeight` + `lineHeight` (when all are set) |
+| `font-weight-thin / light / regular / medium / bold / black` | `fontWeight: "100 / 300 / 400 / 500 / 700 / 900"` |
+| `font-italic` | `fontStyle: "italic"` |
+| `text-left / center / right / justify` | `textAlign: "left / center / right / justify"` |
+| `text-decoration-none / underline / line-through` | `textDecorationLine: "none / underline / line-through"` |
+| `<color>--text` (e.g. `white--text`, `primary--text`) | `fontColor` (when the color is set in `S`) |
+
+## 5. Appearance
+
+| Class token | `S` equivalent |
+|---|---|
+| `elevation-0 … elevation-24` | `boxShadow` |
+| `rounded`, `rounded-lg`, `rounded-xl`, `rounded-circle`, `rounded-pill`, `rounded-0` | `borderTopLeftRadius` + `borderTopRightRadius` + `borderBottomLeftRadius` + `borderBottomRightRadius` |
+| Theme color classes (`primary`, `red lighten-2`, … — background) | `backgroundColor` (when the color is set in `S`) |
+
+## 6. Grid column width (`O.layout` `c:col-N` → `S.col`)
+
+| Legacy (`O.layout` / `dOpt`) | `S` system (on `VCol`) |
+| --- | --- |
+| `c:col-N` → `col-N` class | `S: { "xs-xl": { "col": "N" } }` |
+| `c:col-auto` → `col-auto` class | `S: { "xs-xl": { "col": "auto" } }` |
+| `c:d-none` → `d-none` class (hidden) | `S: { "xs-xl": { "col": "0" } }` |
+| Multiple breakpoints: `dOpt: { xs: ["c:col-12"], md: ["c:col-6"] }` | `S: { "xs-xl": { "col": "12" }, "md-xl": { "col": "6" } }` |
+| `P.cols` / `P.sm` / `P.md` / `P.lg` / `P.xl` props | The `S` range pattern above — don't use these props |
+
+`col` is a real `S` param on `VCol` (see the `VCol` block in `component-styles.json`). It does not exist as an `S` param on `VRow`, `VCard` or `VContainer`.
+
+### Historical relationship — `O.layout` (dOpt) vs `S` layout params
+
+The two coexisted like this while `O.layout` was still authored; for new pages that no longer applies — **everything goes in `S`**:
+
+- `VCol`'s style schema includes a `layout-chooser`/`content-direction` group, which is why `flexDirection`, `alignItems`, `justifyContent` and `col` are real `S` params specifically on `VCol` — they determine the rendered flex axis. The editor migration (`fd:`→`flexDirection`, `a:`→`alignItems`, `j:`→`justifyContent`) is an editor-side path for old `O.layout` data, not something to rely on for newly hand-authored `pJson`.
+- If `S.flexDirection` is left empty, `VCol` falls back to the row axis (the `"default": "column"` in `component-styles.json` is only the Style tab's pre-filled suggestion, not a value silently applied when the key is absent). A `VCol` with more than one visible child must set `S.flexDirection: "column"` explicitly to stack them.
+- `VRow`/`VCard`/`VContainer` have no `flexDirection`/`alignItems`/`justifyContent` `S` param. If the design needs something the `S` schema can't express, the fallback is the component's own `class` prop — **Web only, last resort** — with no Mobile equivalent; restructure with an `S`-capable component (usually `VCol`) instead.
+- Never express the same layout in two conflicting ways (e.g. in an old file, a legacy `O.layout` row and `S.flexDirection: column` on the same `VCol`).
+
+## No `S` equivalent (leave them alone)
+
+For information — these tokens have no counterpart in `S`; exclude them from the conflict audit:
+
+`text-uppercase / lowercase / capitalize` (no `textTransform` in `S`),
+`text-truncate`, `text-no-wrap`,
+`d-none / d-block / d-inline` (visibility; unrelated to `S` sizing),
+`flex-grow-* / flex-shrink-*`, `order-*`, `overflow-*`,
+responsive/breakpoint variants (`d-md-flex`, `pa-md-4` etc. — in `S`,
+breakpoints are handled separately via resolution ranges).

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/reference/qjson-schema-legacy.md

@@ -0,0 +1,15 @@
+# STOP — legacy pages cannot be edited in this workspace
+
+If the target page's root-level `opt.V` is **missing or `< 2.0`**, it is a legacy page. **Do not edit it.** Tell the user the page is legacy and cannot be authored from a mobile workspace, and make no changes.
+
+There is no way to author it correctly here: mobile does not apply the legacy `O.layout` css mechanism, so the page cannot be restyled through it, and `S` does not render on a `V < 2.0` page either. Both style systems are dead ends on that page. Converting it is a migration, not an edit — it needs a decision from the user, not a side effect of the task you were given.
+
+## This is not about stray legacy fragments
+
+A page with `opt.V >= 2.0` that merely *carries* some `O.layout` (`dOpt`/`class`) is **not** a legacy page. Studio's editor injects those fragments into some components on its own, and on mobile they have no effect at all. That page is an ordinary `S` page:
+
+- Author its design in `S`, as normal — go back to `s-track.md`.
+- Never read `O.layout` to work out how the page currently looks; it does not affect the rendering.
+- When you edit such a page, strip its `O.layout` (`dOpt`/`class`) so the page comes out clean.
+
+The test is **`opt.V`**, not whether legacy css is present.

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/ui-kit/reference/qjson-schema.md

@@ -0,0 +1,188 @@
+# QJSON Schema (`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.** 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).
+>
+> Extracted from the TypeScript interfaces the Quick runtime and compiler use.
+
+## 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 existing 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**.
+
+- **`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/styling.md](../knowledge/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):
+
+| `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/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/layout-and-slots.md](../knowledge/layout-and-slots.md) and [knowledge/styling.md](../knowledge/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 existing file you edit. Author `pJson`/`lrids`; the editor regenerates the compiled twins on import. See [validation](../knowledge/validation.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" }
+}
+```