@wix/himalaya-cli 0.943.0 → 0.945.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/ts/src/schema.d.ts

@@ -533,6 +533,12 @@ export type TextProps = TextContent & {
      *  the current left-to-right behavior. Both renderers honor it (parity). */
     textDirection?: "auto" | "ltr" | "rtl";
     decoration?: "underline" | "strikethrough";
+    /** EXTRA SPACE BETWEEN LINES, in points/px — added ON TOP of the line height the `style`
+     *  token already sets. It is NOT a multiple: `lineSpacing: 6` means six points of extra
+     *  leading, not six times the font size, and every renderer agrees on that. To
+     *  change the line height as a ratio of the font size, set the typography token's `line`
+     *  instead; that is where a body style's 1.4/1.7 lives. Absent/0 = the token's own line
+     *  height, which is the right answer for almost every screen. */
     lineSpacing?: number;
     /** Per-item gate (usually an `$item.` field pre-substituted per row): when it
      *  resolves empty, the text collapses to zero size instead of taking layout. */

package/dist/cli.mjs

@@ -18546,6 +18546,7 @@ function shouldRevealError(args) {
 var EMAIL_RE, URL_HOST_RE, INTEGER_RE, NUMBER_RE;
 var init_validation = __esm({
   "../../core/ts/src/validation.ts"() {
+    "use strict";
     EMAIL_RE = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}$/;
     URL_HOST_RE = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(:[0-9]+)?$/;
     INTEGER_RE = /^[+-]?[0-9]+$/;
@@ -21969,6 +21970,7 @@ function validateWorkerSubtree(raw, slotId, policy, actionCatalog) {
 var WORKER_SUBTREE_CEILINGS, ID_PART, ACTION_ID;
 var init_worker_subtree = __esm({
   "../../core/ts/src/worker-subtree.ts"() {
+    "use strict";
     init_worker_subtree_safe_types_generated();
     WORKER_SUBTREE_CEILINGS = Object.freeze({
       maxEncodedBytes: 65536,
@@ -25593,7 +25595,7 @@ var init_renderNode = __esm({
       const content = countContent != null ? countContent : icuPattern != null ? /* @__PURE__ */ jsx6(InterpolatedTextView, { pattern: icuPattern, params: props.template?.params ?? {}, ctx }) : mdSource != null ? /* @__PURE__ */ jsx6("span", { dangerouslySetInnerHTML: mdInline(mdSource) }) : txt(props.text, ctx);
       const tAlign = props.textAlign === "center" ? "center" : props.textAlign === "trailing" ? "right" : props.textAlign === "justify" ? "justify" : props.textAlign === "leading" ? "left" : void 0;
       const tDecor = props.decoration === "strikethrough" ? "line-through" : props.decoration === "underline" ? "underline" : void 0;
-      const ln = typeof props.lineSpacing === "number" && f.line ? f.line + props.lineSpacing : f.line;
+      const ln = typeof props.lineSpacing === "number" ? `${(f.line ?? 1.4) * f.size + props.lineSpacing}px` : f.line;
       return /* @__PURE__ */ jsx6("div", { ...countAttrs, style: { fontFamily: fontStack(f.family), fontSize: f.size, fontWeight: f.weight, lineHeight: ln, letterSpacing: f.letterSpacing, color: C(resolveScalarStatic(props.color, ctx) ?? "textPrimary", "#13171e"), whiteSpace: "pre-wrap", overflowWrap: "anywhere", wordBreak: "break-word", minWidth: 0, ...tAlign ? { textAlign: tAlign } : {}, ...tDecor ? { textDecoration: tDecor } : {}, ...props.maxLines ? { display: "-webkit-box", WebkitLineClamp: props.maxLines, WebkitBoxOrient: "vertical", overflow: "hidden" } : {}, ...wrap }, children: content == null || content === "" ? collapse ? null : "\xA0" : content });
     });
     ImageNode = withExtras("ImageNode", ({ props, ctx, wrap }) => {
@@ -43281,19 +43283,19 @@ var init_preview_assets_generated = __esm({
   "../../packages/serve/src/preview-assets.generated.ts"() {
     init_preview_assets_format();
     PREVIEW_ASSET_MANIFEST = [
-      { key: "assets/index-D1ZgNUMR.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 983079, sha256: "2ccd3ce0303a1f4ade606b38e144243d87217dc439e4738417556224e314b8a5" },
-      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 983087, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
-      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 1074011, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
-      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 1164995, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
-      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 1255975, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
-      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 1346847, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
-      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 1437827, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
-      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 1546463, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
-      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 1655547, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
-      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 1764595, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
-      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 1872295, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
-      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 1960403, length: 4448, sha256: "8f2222f638f46d9c9a5e57fc9cc5a30a76cee7f91923120aac299292c0f1f604" },
-      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 1964851, length: 13784, sha256: "cfb9465254fab84f0e084bb4542c282758ea29774b5f172840cc0b9e4194ef89" }
+      { key: "assets/index-C40lmxo4.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 983092, sha256: "919193db2182eb6a481f3729dda29af2441d6c46027c7fab508c2abb78f8fc0f" },
+      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 983100, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
+      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 1074024, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
+      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 1165008, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
+      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 1255988, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
+      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 1346860, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
+      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 1437840, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
+      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 1546476, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
+      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 1655560, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
+      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 1764608, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
+      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 1872308, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
+      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 1960416, length: 4448, sha256: "4cff52eaf77b0c3c09effb2dd0447d78d2b03ecaa68893281b1637510b93d8ad" },
+      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 1964864, length: 13784, sha256: "cfb9465254fab84f0e084bb4542c282758ea29774b5f172840cc0b9e4194ef89" }
     ];
   }
 });
@@ -55207,7 +55209,10 @@ function ownerPlaneHint(status, error, target) {
     return { hint: "this environment has no token signing secret configured \u2014 an operator must set SERVE_CONTROL_SIGNING_SECRET" };
   }
   if (error === "owner_requires_selfserve_token") {
-    return { hint: `that credential is an operator token, not a self-serve one \u2014 run \`himi login --browser --target ${target}\` to get an owner identity` };
+    const base = `that credential is an operator token, not a self-serve one \u2014 run \`himi login --browser --target ${target}\` to get an owner identity`;
+    return {
+      hint: isPublicTarget(target) ? base : `${base}. On ${target} that REPLACES the employee token stored for this target, and \`himi dist\` then charges the self-serve tier instead of the employee one \u2014 deliberately the tightest of the three, so far fewer concurrent builds and far fewer per day. \`himi login --dpx --target ${target}\` switches back.`
+    };
   }
   if (error === "token_revoked") {
     return { hint: `this token was revoked \u2014 run \`himi login --browser --target ${target}\` to get a new one` };

package/guides/component-reference.json

@@ -101,7 +101,7 @@
       "bindings": [
         "text"
       ],
-      "propsSource": "export type TextProps = TextContent & {\n  style?: TokenName;\n  /** Foreground color token (default \"textPrimary\"). */\n  color?: TokenName;\n  /** Tail-truncate after N lines (absent = unlimited). */\n  maxLines?: number;\n  /** Lever D — a live time value (countdown/relative) the OS ticks with no refresh.\n   *  When present it OVERRIDES `text`. Widget-safe render only. */\n  timeRef?: WidgetTimeRef;\n  /** Render `text` as a constrained Markdown subset. */\n  markdown?: boolean;\n  /** Capability enrichments. */\n  textAlign?: \"leading\" | \"center\" | \"trailing\" | \"justify\";\n  /** Base writing direction. \"auto\" (or \"rtl\") makes a bidi paragraph resolve +\n   *  align by its own strong-directional content (Hebrew/Arabic → right-aligned,\n   *  RTL layout), matching per-message direction in chat bubbles. Absent/\"ltr\" =\n   *  the current left-to-right behavior. Both renderers honor it (parity). */\n  textDirection?: \"auto\" | \"ltr\" | \"rtl\";\n  decoration?: \"underline\" | \"strikethrough\";\n  lineSpacing?: number;\n  /** Per-item gate (usually an `$item.` field pre-substituted per row): when it\n   *  resolves empty, the text collapses to zero size instead of taking layout. */\n  collapseWhenEmpty?: boolean;\n  /** Motion grammar (Batch 1, item 4) — count-up tween for a numeric value on\n   *  change; non-numeric values render instantly. Gated by reduced motion. */\n  animateValue?: boolean;\n  /** Motion grammar — reveal the (post-substitution literal) text word-by-word,\n   *  once per distinct content, like a chat assistant \"typing\" its reply. Each\n   *  content animates a single time (progress is remembered), so list re-renders\n   *  and scrolls don't restart it. Gated by reduced motion (snaps to full).\n   *  Both renderers honor it (parity). Default nil/false. */\n  animateReveal?: boolean;\n};"
+      "propsSource": "export type TextProps = TextContent & {\n  style?: TokenName;\n  /** Foreground color token (default \"textPrimary\"). */\n  color?: TokenName;\n  /** Tail-truncate after N lines (absent = unlimited). */\n  maxLines?: number;\n  /** Lever D — a live time value (countdown/relative) the OS ticks with no refresh.\n   *  When present it OVERRIDES `text`. Widget-safe render only. */\n  timeRef?: WidgetTimeRef;\n  /** Render `text` as a constrained Markdown subset. */\n  markdown?: boolean;\n  /** Capability enrichments. */\n  textAlign?: \"leading\" | \"center\" | \"trailing\" | \"justify\";\n  /** Base writing direction. \"auto\" (or \"rtl\") makes a bidi paragraph resolve +\n   *  align by its own strong-directional content (Hebrew/Arabic → right-aligned,\n   *  RTL layout), matching per-message direction in chat bubbles. Absent/\"ltr\" =\n   *  the current left-to-right behavior. Both renderers honor it (parity). */\n  textDirection?: \"auto\" | \"ltr\" | \"rtl\";\n  decoration?: \"underline\" | \"strikethrough\";\n  /** EXTRA SPACE BETWEEN LINES, in points/px — added ON TOP of the line height the `style`\n   *  token already sets. It is NOT a multiple: `lineSpacing: 6` means six points of extra\n   *  leading, not six times the font size, and every renderer agrees on that. To\n   *  change the line height as a ratio of the font size, set the typography token's `line`\n   *  instead; that is where a body style's 1.4/1.7 lives. Absent/0 = the token's own line\n   *  height, which is the right answer for almost every screen. */\n  lineSpacing?: number;\n  /** Per-item gate (usually an `$item.` field pre-substituted per row): when it\n   *  resolves empty, the text collapses to zero size instead of taking layout. */\n  collapseWhenEmpty?: boolean;\n  /** Motion grammar (Batch 1, item 4) — count-up tween for a numeric value on\n   *  change; non-numeric values render instantly. Gated by reduced motion. */\n  animateValue?: boolean;\n  /** Motion grammar — reveal the (post-substitution literal) text word-by-word,\n   *  once per distinct content, like a chat assistant \"typing\" its reply. Each\n   *  content animates a single time (progress is remembered), so list re-renders\n   *  and scrolls don't restart it. Gated by reduced motion (snaps to full).\n   *  Both renderers honor it (parity). Default nil/false. */\n  animateReveal?: boolean;\n};"
     },
     {
       "name": "Image",
@@ -139,6 +139,44 @@
         "focusPath",
         "errorPath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "string",
+          "note": "The typed text, clamped to maxLength by the renderer.",
+          "divergences": [
+            {
+              "arms": [
+                "ios",
+                "android",
+                "web"
+              ],
+              "kind": "additive",
+              "actual": "additionally injects `fieldId` when the text field is inside a Form, so one worker action can serve several fields.",
+              "reason": "Additive, not conflicting, and shipped bundles already duck-type it. Every arm guards on the field actually being registered in a Form, so a standalone TextField still sends no `fieldId`. Still a divergence rather than a promoted contract key because RN does not send it and the contract does not require it."
+            }
+          ]
+        },
+        {
+          "callback": "onSubmit",
+          "key": "value",
+          "encoding": "string",
+          "note": "The field's current text at return-key time.",
+          "divergences": [
+            {
+              "arms": [
+                "ios",
+                "android",
+                "web"
+              ],
+              "kind": "additive",
+              "actual": "additionally injects `fieldId` when the text field is inside a Form, so one worker action can serve several fields.",
+              "reason": "Additive, not conflicting, and shipped bundles already duck-type it. Every arm guards on the field actually being registered in a Form, so a standalone TextField still sends no `fieldId`. Still a divergence rather than a promoted contract key because RN does not send it and the contract does not require it."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface TextFieldProps {\n  placeholder?: string;\n  /** LITERAL initial text. Renderers paint it verbatim — a `$service:` sentinel\n   *  here shows the raw token to the user. Bind `valuePath` instead. */\n  value?: string;\n  /** `$service:`/`$item.` binding → live text from the worker (overrides `value`).\n   *  Adopted while the field is NOT focused; an empty worker value (a draft reset\n   *  after send/post/submit) is adopted even mid-focus, so a cleared draft empties\n   *  the field without the worker ever fighting the caret. */\n  valuePath?: string;\n  onChange?: Action;\n  /** Text input enrichments. */\n  keyboard?: Keyboard;\n  secure?: boolean;\n  multilineMaxLines?: number;\n  maxLength?: number;\n  autoCapitalization?: AutoCapitalization;\n  onSubmit?: Action;\n  /** Keyboard control. `suggestions: \"off\"` kills autocorrect + the suggestion\n   *  strip. `submitLabel` paints the return key and, with `onSubmit`, fires it —\n   *  submitting dismisses the keyboard except for `\"next\"`, which keeps it up so\n   *  a worker can move focus on. */\n  suggestions?: Suggestions;\n  submitLabel?: SubmitLabel;\n  /** `$service:` binding → a TOKEN the worker changes to focus this field. Focus\n   *  is requested whenever the resolved value becomes a new NON-EMPTY value\n   *  (the first seed included, so a non-empty init focuses on open). Use a\n   *  monotonic nonce — `String(Date.now())` — since a latched boolean cannot\n   *  re-fire. Blur is the keyboard-dismiss capability, not a token here. */\n  focusPath?: string;\n  /** Accessory & state enrichments. */\n  leadingIcon?: IconRef;\n  trailingIcon?: IconRef;\n  clearButton?: boolean;\n  helperText?: string;\n  error?: boolean;\n  prefix?: string;\n  suffix?: string;\n  /** Drop the default rounded-border chrome so a caller background shows (composer pill). */\n  borderless?: boolean;\n  /** Declarative syntactic rules the RENDERER evaluates, so they hold with no\n   *  worker running (Tier 0-4) and with no bridge round-trip. Before this,\n   *  validation was reachable only by wrapping the field in `Form` -> `FormField`\n   *  - the shape the design guide steers you away from for hero flows. */\n  validation?: Validation;\n  /** `$service:`/`$item.` binding -> a worker-computed error string. Non-empty =\n   *  invalid. This is how SEMANTIC and CROSS-FIELD errors (\"passwords don't\n   *  match\", \"email taken\") reach the same error slot, with the same styling and\n   *  a11y wiring, as the declarative ones. Wins over `validation.message`. */\n  errorPath?: string;\n  /** LITERAL error string for a server-rendered screen with no worker to bind.\n   *  Lower precedence than `errorPath`, higher than the rules. */\n  errorText?: string;\n}"
     },
     {
@@ -148,6 +186,23 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "boolean",
+          "note": "The NEXT state, not the previous one.",
+          "divergences": [
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "additive",
+              "actual": "additionally injects `fieldId` when the control is inside a Form — via bindingForBool, for a Toggle nested in a FormField."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface ToggleProps {\n  label?: string;\n  value: boolean;\n  /** `$service:`/`$item.` binding → a live bool (overrides `value`). */\n  valuePath?: string;\n  onChange?: Action;\n  /** #1047 — ON-state track color token (default: `accentPrimary`). Setting any\n   *  appearance prop switches to a custom-drawn control so a host can match its own\n   *  switch and keep the screen OTA (vs the `intents:` escape hatch). */\n  trackOn?: TokenName;\n  /** #1047 — OFF-state track color token (default: system/`surfaceTertiary`). */\n  trackOff?: TokenName;\n  /** #1047 — thumb color token (default: white). */\n  thumb?: TokenName;\n  /** #1047 — track width (pt/dp/px). Absent = system size. */\n  width?: number;\n  /** #1047 — track height (pt/dp/px). Absent = system size. */\n  height?: number;\n}"
     },
     {
@@ -157,6 +212,25 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "int",
+          "note": "The clamped next value. A no-change step must not dispatch.",
+          "divergences": [
+            {
+              "arms": [
+                "web",
+                "rn"
+              ],
+              "kind": "params-mirror",
+              "actual": "mirrors the value into `params` as a NUMBER.",
+              "reason": "Violates rule 2 — `Action.params` is `map<string,string>`. Harmless through the JS hosts, wrong on the wire."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface StepperProps {\n  value: number;\n  /** `$service:`/`$item.` binding → a live integer (overrides `value`). */\n  valuePath?: string;\n  min?: number;\n  max?: number;\n  onChange?: Action;\n}"
     },
     {
@@ -238,6 +312,24 @@
       "category": "Form primitives",
       "propsType": "PickerProps",
       "bindings": [],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "selectedId",
+          "encoding": "string",
+          "note": "The chosen option's id — an enum the reducer switches on, never an index.",
+          "divergences": [
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "probe",
+              "actual": "inside a FormField, the non-text kinds store into the form bag and RETURN without dispatching — the renderer's own code.",
+              "reason": "A formField({kind:'picker'}) onChange is a dead action on iOS while every other arm fires it."
+            }
+          ]
+        }
+      ],
       "notImplemented": {
         "props": [
           "optionsPath",
@@ -256,6 +348,39 @@
       "category": "Form primitives",
       "propsType": "DatePickerProps",
       "bindings": [],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "unix-seconds-string",
+          "note": "Unix SECONDS, string-encoded so the params mirror stays legal. iOS ships `valueUnix` as an int instead; RN ships nothing. The normative key is `value` because that is what three of four arms already use for every other scalar control.",
+          "divergences": [
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "wrong-key",
+              "actual": "sends `valueUnix` as an int instead of the contract's `value`.",
+              "reason": "Only web conforms. This is the widest split in the vocabulary and the clearest argument for the file."
+            },
+            {
+              "arms": [
+                "rn"
+              ],
+              "kind": "no-payload",
+              "actual": "dispatches the bare action with no date at all."
+            },
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "probe",
+              "actual": "inside a FormField, the non-text kinds store into the form bag and RETURN without dispatching — the renderer's own code.",
+              "reason": "A formField({kind:'picker'}) onChange is a dead action on iOS while every other arm fires it."
+            }
+          ]
+        }
+      ],
       "notImplemented": {
         "props": [
           "mode",
@@ -308,6 +433,20 @@
       "category": "Search & filter",
       "propsType": "SearchFieldProps",
       "bindings": [],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "string",
+          "note": "Debounced by `debounceMs` before dispatch."
+        },
+        {
+          "callback": "onSubmit",
+          "key": "value",
+          "encoding": "string",
+          "note": "These two rows share a control and key, so they are NOT independently gated: a payload observation cannot say which callback produced it, and a helper-mediated dispatch does not name the callback at the write site at all. The gate proves the callback is still referenced in the component that dispatches, not that this callback carries the payload."
+        }
+      ],
       "propsSource": "export interface SearchFieldProps {\n  placeholder?: string;\n  value?: string;\n  onChange?: Action;\n  onSubmit?: Action;\n  debounceMs?: number;\n}"
     },
     {
@@ -318,6 +457,24 @@
         "optionsPath",
         "selectedIds"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "selectedIds",
+          "encoding": "string-array",
+          "note": "The full selection AFTER the toggle, not the chip that moved.",
+          "divergences": [
+            {
+              "arms": [
+                "rn"
+              ],
+              "kind": "params-mirror",
+              "actual": "mirrors `selectedIds` into `params` as an ARRAY.",
+              "reason": "Rule-2 violation."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface FilterChipsProps {\n  chips: FilterChip[];\n  /** Literal ids, or a binding-aware `$service:`/`$item.` live selection. */\n  selectedIds?: string[];\n  multiSelect?: boolean;\n  onChange?: Action;\n  /** `$service:` binding → a live options array (overrides `chips`). */\n  optionsPath?: string;\n}"
     },
     {
@@ -329,6 +486,13 @@
         "activeColorPath",
         "selectedId"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "selectedId",
+          "encoding": "string"
+        }
+      ],
       "notImplemented": {
         "props": [
           "style"
@@ -349,6 +513,13 @@
         "optionsPath",
         "selectedId"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "selectedId",
+          "encoding": "string"
+        }
+      ],
       "propsSource": "export interface SegmentedControlProps {\n  options: TabItem[];\n  /** Literal id, or a binding-aware `$service:`/`$item.` live selection. */\n  selectedId: string;\n  onChange?: Action;\n  /** `$service:` binding → a live options array (overrides `options`). */\n  optionsPath?: string;\n}"
     },
     {
@@ -456,6 +627,40 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "double",
+          "note": "Range mode additionally sends `upperValue`.",
+          "divergences": [
+            {
+              "arms": [
+                "web"
+              ],
+              "kind": "no-payload",
+              "actual": "dispatches the bare action — the renderer's own code — with no injected value."
+            },
+            {
+              "arms": [
+                "rn"
+              ],
+              "kind": "no-payload",
+              "actual": "renders a static visual and never dispatches at all.",
+              "reason": "RN Slider is unimplemented rather than divergent; listed so the gap is counted, not hidden."
+            },
+            {
+              "arms": [
+                "ios",
+                "android"
+              ],
+              "kind": "additive",
+              "actual": "range mode additionally sends `upperValue` beside `value`.",
+              "reason": "Additive, and the contract's Slider note already describes it. Same problem as groupId: allowed by a hard-coded list rather than declared."
+            }
+          ]
+        }
+      ],
       "notImplemented": {
         "props": [
           "debounceMs"
@@ -475,6 +680,38 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "boolean",
+          "note": "The next checked state. iOS additionally sends `groupId` for radio groups.",
+          "divergences": [
+            {
+              "arms": [
+                "web"
+              ],
+              "kind": "no-payload",
+              "actual": "dispatches the bare action — the renderer's own code — with no injected value."
+            },
+            {
+              "arms": [
+                "rn"
+              ],
+              "kind": "params-mirror",
+              "actual": "mirrors the value into `params` as a BOOLEAN."
+            },
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "additive",
+              "actual": "additionally sends `groupId` so a radio group can identify which set changed.",
+              "reason": "Additive, not conflicting. It was previously hard-coded as an allowed key in the gate, which put it outside the contract — the one place this PR claims is the single source of truth."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface SelectionControlProps {\n  label?: string;\n  value?: boolean;\n  kind?: \"checkbox\" | \"radio\";\n  /** Radios sharing a `groupId` are mutually exclusive. */\n  groupId?: string;\n  onChange?: Action;\n  /** \"$service:\"/\"$item.\" binding → bool (overrides `value`). */\n  valuePath?: string;\n  disabled?: boolean;\n  /** Checkbox tri-state (renders a dash); ignored for radio. */\n  indeterminate?: boolean;\n}"
     },
     {
@@ -592,6 +829,23 @@
       "bindings": [
         "valuesPath"
       ],
+      "dispatches": [
+        {
+          "callback": "onRemove",
+          "key": "value",
+          "encoding": "string",
+          "note": "The removed chip's value.",
+          "divergences": [
+            {
+              "arms": [
+                "web"
+              ],
+              "kind": "no-payload",
+              "actual": "dispatches the bare action — the renderer's own code — with no injected value."
+            }
+          ]
+        }
+      ],
       "notImplemented": {
         "props": [
           "onAdd"
@@ -660,6 +914,41 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "int",
+          "note": "1-based star index.",
+          "divergences": [
+            {
+              "arms": [
+                "web",
+                "rn"
+              ],
+              "kind": "params-only",
+              "actual": "writes the value into `params` ONLY, never `args`.",
+              "reason": "Survives only because the Tier-5 hosts merge params into args. Any consumer reading `args` — which rule 1 says is the payload map — gets nothing."
+            },
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "encoding",
+              "actual": "sends `value` as .double where the contract says int."
+            },
+            {
+              "arms": [
+                "web",
+                "rn"
+              ],
+              "kind": "params-mirror",
+              "actual": "stringifies the 1-based index into `params` (`String(i + 1)`) for a control the contract declares `int`.",
+              "reason": "Rule 2 permits a params mirror only for string-encoded values, and Rating is int. The earlier expression heuristic missed it because `String(i + 1)` does not look like a literal — it surfaced only once rule 2 keyed off the declared encoding."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface RatingProps {\n  value?: number;\n  max?: number;\n  interactive?: boolean;\n  onChange?: Action;\n  color?: TokenName;\n  icon?: IconRef;\n  valuePath?: string;\n}"
     },
     {
@@ -744,6 +1033,31 @@
         "optionsPath",
         "selectedId"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "selectedId",
+          "encoding": "string",
+          "divergences": [
+            {
+              "arms": [
+                "rn"
+              ],
+              "kind": "params-wrong-key",
+              "actual": "writes `params.value = String(id)` but `args.selectedId = id` — a different key in each map.",
+              "reason": "Conforms on `args` (rule 1) but the params mirror uses the wrong key, so a params-reading consumer sees a key no other arm sends."
+            },
+            {
+              "arms": [
+                "web"
+              ],
+              "kind": "no-payload",
+              "actual": "renders a static window of options and never dispatches — the case has no onAction.",
+              "reason": "Unimplemented on web rather than divergent. Surfaced by the missing-site assertion; the other four it reported were blind spots in the scan, now fixed."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface WheelPickerProps {\n  options?: PickerOption[];\n  /** Literal option id, or binding-aware `$service:`/`$item.` live id. */\n  selectedId?: string;\n  onChange?: Action;\n  optionsPath?: string;\n}"
     },
     {
@@ -753,6 +1067,25 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "string",
+          "note": "Hex, including the leading '#'.",
+          "divergences": [
+            {
+              "arms": [
+                "web",
+                "rn"
+              ],
+              "kind": "params-only",
+              "actual": "writes the value into `params` ONLY, never `args`.",
+              "reason": "Survives only because the Tier-5 hosts merge params into args. Any consumer reading `args` — which rule 1 says is the payload map — gets nothing."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface ColorPickerProps {\n  value?: string;\n  onChange?: Action;\n  swatches?: string[];\n  label?: string;\n  valuePath?: string;\n}"
     },
     {
@@ -762,6 +1095,44 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "string",
+          "note": "The assembled code. Only RN dispatches today; web, iOS and Android render the boxes read-only.",
+          "divergences": [
+            {
+              "arms": [
+                "web",
+                "ios",
+                "android"
+              ],
+              "kind": "no-payload",
+              "actual": "renders the digit boxes without wiring onChange — the control dispatches nothing.",
+              "reason": "Unimplemented rather than divergent, but it must be declared: leaving OtpInput out of the contract is what let the gate whitelist RN's payload without checking it."
+            }
+          ]
+        },
+        {
+          "callback": "onComplete",
+          "key": "value",
+          "encoding": "string",
+          "note": "Fires once the last box is filled, carrying the same assembled code as onChange. Declared separately because it is a second public callback — leaving it out left one outside the contract.",
+          "divergences": [
+            {
+              "arms": [
+                "web",
+                "ios",
+                "android"
+              ],
+              "kind": "no-payload",
+              "actual": "renders the digit boxes without wiring onChange — the control dispatches nothing.",
+              "reason": "Unimplemented rather than divergent, but it must be declared: leaving OtpInput out of the contract is what let the gate whitelist RN's payload without checking it."
+            }
+          ]
+        }
+      ],
       "notImplemented": {
         "props": [
           "onChange",

package/guides/component-reference.md

@@ -180,6 +180,36 @@ The two share a leaf name and mean opposite things — descriptor side takes the
 registry takes the HEX — so a validator error about `shadows.card.color` is not this table
 contradicting itself.
 
+## What a control sends (action payloads)
+
+A component's props say what it READS. This says what it SENDS: the value a control injects
+into the `Action` it dispatches, so a Tier-5 reducer can be written from this page instead of
+from trial and error.
+
+1. **The payload is in `args`.** `Action.args` is a `Value`, so it holds the real type
+   (bool / int / double / array), and every host merges `{...params, ...args}` with `args`
+   winning. Read `args` first.
+2. **`params` may mirror it, but only for a string.** `Action.params` is declared
+   `map<string,string>` in the descriptor schema; a number, bool or array there is a type
+   violation even where JavaScript tolerates it.
+3. **The key and the encoding below are normative.** A renderer that sends a different key —
+   or no payload at all — is a divergence, and every one that exists today is printed with the
+   component it affects, because that is precisely the case a reducer has to be written around.
+
+Every row here is generated from the platform's own payload contract and re-checked against
+all four renderers on every build, so it cannot drift from what the components actually send.
+
+**What it covers, and what it does not.** The contract is about **value controls** — the ones
+whose callback carries the thing the user chose or typed. A value callback absent from a
+component's block injects nothing: it dispatches the author's action verbatim, so any
+discriminator must come from the `args` the author wrote (`Chip.onRemove` and
+`DisclosureGroup.onToggle` are the two that work this way today).
+
+That is NOT a statement about every action a component can fire. Gesture and event callbacks —
+`Map.onMapTap` / `onMarkerTap`, a media player's progress events — inject payloads of their
+own and are outside this contract, so read the component's own prop documentation for those
+rather than concluding from a missing row here that nothing arrives.
+
 ## Props (verbatim from schema.ts)
 
 ### Core
@@ -379,6 +409,12 @@ export type TextProps = TextContent & {
    *  the current left-to-right behavior. Both renderers honor it (parity). */
   textDirection?: "auto" | "ltr" | "rtl";
   decoration?: "underline" | "strikethrough";
+  /** EXTRA SPACE BETWEEN LINES, in points/px — added ON TOP of the line height the `style`
+   *  token already sets. It is NOT a multiple: `lineSpacing: 6` means six points of extra
+   *  leading, not six times the font size, and every renderer agrees on that. To
+   *  change the line height as a ratio of the font size, set the typography token's `line`
+   *  instead; that is where a body style's 1.4/1.7 lives. Absent/0 = the token's own line
+   *  height, which is the right answer for almost every screen. */
   lineSpacing?: number;
   /** Per-item gate (usually an `$item.` field pre-substituted per row): when it
    *  resolves empty, the text collapses to zero size instead of taking layout. */
@@ -519,6 +555,21 @@ export interface TextFieldProps {
 }
 ```
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `value` | string |
+| `onSubmit` | `value` | string |
+
+> `onChange` — The typed text, clamped to maxLength by the renderer.
+
+> ⚠️ **`onChange` on ios + android + web — ALSO sends:** additionally injects `fieldId` when the text field is inside a Form, so one worker action can serve several fields. Additive, not conflicting, and shipped bundles already duck-type it. Every arm guards on the field actually being registered in a Form, so a standalone TextField still sends no `fieldId`. Still a divergence rather than a promoted contract key because RN does not send it and the contract does not require it.
+
+> `onSubmit` — The field's current text at return-key time.
+
+> ⚠️ **`onSubmit` on ios + android + web — ALSO sends:** additionally injects `fieldId` when the text field is inside a Form, so one worker action can serve several fields. Additive, not conflicting, and shipped bundles already duck-type it. Every arm guards on the field actually being registered in a Form, so a standalone TextField still sends no `fieldId`. Still a divergence rather than a promoted contract key because RN does not send it and the contract does not require it.
+
 #### Toggle
 
 ```ts
@@ -543,6 +594,16 @@ export interface ToggleProps {
 }
 ```
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `value` | boolean |
+
+> `onChange` — The NEXT state, not the previous one.
+
+> ⚠️ **`onChange` on ios — ALSO sends:** additionally injects `fieldId` when the control is inside a Form — via bindingForBool, for a Toggle nested in a FormField.
+
 #### Stepper
 
 ```ts
@@ -556,6 +617,16 @@ export interface StepperProps {
 }
 ```
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `value` | int |
+
+> `onChange` — The clamped next value. A no-change step must not dispatch.
+
+> ⚠️ **`onChange` on web + rn — DIVERGES:** mirrors the value into `params` as a NUMBER. Violates rule 2 — `Action.params` is `map<string,string>`. Harmless through the JS hosts, wrong on the wire.
+
 #### Avatar
 
 ```ts
@@ -712,6 +783,16 @@ export interface PickerProps {
 
 > ⚠️ **Implemented, but these props are inert on ios:** `optionsPath`, `placeholder` — `optionsPath` does not bind options; `placeholder` is not shown.
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `selectedId` | string |
+
+> `onChange` — The chosen option's id — an enum the reducer switches on, never an index.
+
+> ⚠️ **`onChange` on ios — DIVERGES:** inside a FormField, the non-text kinds store into the form bag and RETURN without dispatching — the renderer's own code. A formField({kind:'picker'}) onChange is a dead action on iOS while every other arm fires it.
+
 #### DatePicker
 
 ```ts
@@ -728,6 +809,20 @@ export interface DatePickerProps {
 
 > ⚠️ **Implemented, but these props are inert on ios:** `mode`, `minUnix`, `maxUnix`, `valuePath` — The picker itself renders as a native date wheel — these four props are inert: `mode: "time"` still renders a date wheel; `minUnix`/`maxUnix` do not clamp; `valuePath` does not bind.
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `value` | unix-seconds-string |
+
+> `onChange` — Unix SECONDS, string-encoded so the params mirror stays legal. iOS ships `valueUnix` as an int instead; RN ships nothing. The normative key is `value` because that is what three of four arms already use for every other scalar control.
+
+> ⚠️ **`onChange` on ios — DIVERGES:** sends `valueUnix` as an int instead of the contract's `value`. Only web conforms. This is the widest split in the vocabulary and the clearest argument for the file.
+
+> ⚠️ **`onChange` on rn — DIVERGES:** dispatches the bare action with no date at all.
+
+> ⚠️ **`onChange` on ios — DIVERGES:** inside a FormField, the non-text kinds store into the form bag and RETURN without dispatching — the renderer's own code. A formField({kind:'picker'}) onChange is a dead action on iOS while every other arm fires it.
+
 ### State envelopes
 
 #### StatefulSection
@@ -793,6 +888,17 @@ export interface SearchFieldProps {
 }
 ```
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `value` | string |
+| `onSubmit` | `value` | string |
+
+> `onChange` — Debounced by `debounceMs` before dispatch.
+
+> `onSubmit` — These two rows share a control and key, so they are NOT independently gated: a payload observation cannot say which callback produced it, and a helper-mediated dispatch does not name the callback at the write site at all. The gate proves the callback is still referenced in the component that dispatches, not that this callback carries the payload.
+
 #### FilterChips
 
 ```ts
@@ -807,6 +913,16 @@ export interface FilterChipsProps {
 }
 ```
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `selectedIds` | string-array |
+
+> `onChange` — The full selection AFTER the toggle, not the chip that moved.
+
+> ⚠️ **`onChange` on rn — DIVERGES:** mirrors `selectedIds` into `params` as an ARRAY. Rule-2 violation.
+
 ### Navigation primitives
 
 #### Tabs
@@ -827,6 +943,12 @@ export interface TabsProps {
 
 > ⚠️ **Implemented, but these props are inert on ios:** `style` — The tab bar itself renders — only `style` is inert: `swipe` still renders as top tabs.
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `selectedId` | string |
+
 #### SegmentedControl
 
 ```ts
@@ -840,6 +962,12 @@ export interface SegmentedControlProps {
 }
 ```
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `selectedId` | string |
+
 #### Carousel
 
 ```ts
@@ -1056,6 +1184,20 @@ export interface SliderProps {
 
 > ⚠️ **Implemented, but these props are inert on ios:** `debounceMs` — `debounceMs` does not throttle the onChange stream.
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `value` | double |
+
+> `onChange` — Range mode additionally sends `upperValue`.
+
+> ⚠️ **`onChange` on web — DIVERGES:** dispatches the bare action — the renderer's own code — with no injected value.
+
+> ⚠️ **`onChange` on rn — DIVERGES:** renders a static visual and never dispatches at all. RN Slider is unimplemented rather than divergent; listed so the gap is counted, not hidden.
+
+> ⚠️ **`onChange` on ios + android — ALSO sends:** range mode additionally sends `upperValue` beside `value`. Additive, and the contract's Slider note already describes it. Same problem as groupId: allowed by a hard-coded list rather than declared.
+
 #### SelectionControl
 
 ```ts
@@ -1074,6 +1216,20 @@ export interface SelectionControlProps {
 }
 ```
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `value` | boolean |
+
+> `onChange` — The next checked state. iOS additionally sends `groupId` for radio groups.
+
+> ⚠️ **`onChange` on web — DIVERGES:** dispatches the bare action — the renderer's own code — with no injected value.
+
+> ⚠️ **`onChange` on rn — DIVERGES:** mirrors the value into `params` as a BOOLEAN.
+
+> ⚠️ **`onChange` on ios — ALSO sends:** additionally sends `groupId` so a radio group can identify which set changed. Additive, not conflicting. It was previously hard-coded as an allowed key in the gate, which put it outside the contract — the one place this PR claims is the single source of truth.
+
 #### ActivityIndicator
 
 ```ts
@@ -1200,6 +1356,16 @@ export interface ChipsInputProps {
 
 > ⚠️ **Implemented, but these props are inert on ios:** `onAdd` — `onAdd` never dispatches.
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onRemove` | `value` | string |
+
+> `onRemove` — The removed chip's value.
+
+> ⚠️ **`onRemove` on web — DIVERGES:** dispatches the bare action — the renderer's own code — with no injected value.
+
 ### Structure & disclosure
 
 #### Section
@@ -1296,6 +1462,20 @@ export interface RatingProps {
 }
 ```
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `value` | int |
+
+> `onChange` — 1-based star index.
+
+> ⚠️ **`onChange` on web + rn — DIVERGES:** writes the value into `params` ONLY, never `args`. Survives only because the Tier-5 hosts merge params into args. Any consumer reading `args` — which rule 1 says is the payload map — gets nothing.
+
+> ⚠️ **`onChange` on ios — DIVERGES:** sends `value` as .double where the contract says int.
+
+> ⚠️ **`onChange` on web + rn — DIVERGES:** stringifies the 1-based index into `params` (`String(i + 1)`) for a control the contract declares `int`. Rule 2 permits a params mirror only for string-encoded values, and Rating is int. The earlier expression heuristic missed it because `String(i + 1)` does not look like a literal — it surfaced only once rule 2 keyed off the declared encoding.
+
 #### Chart
 
 ```ts
@@ -1463,6 +1643,16 @@ export interface WheelPickerProps {
 }
 ```
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `selectedId` | string |
+
+> ⚠️ **`onChange` on rn — DIVERGES:** writes `params.value = String(id)` but `args.selectedId = id` — a different key in each map. Conforms on `args` (rule 1) but the params mirror uses the wrong key, so a params-reading consumer sees a key no other arm sends.
+
+> ⚠️ **`onChange` on web — DIVERGES:** renders a static window of options and never dispatches — the case has no onAction. Unimplemented on web rather than divergent. Surfaced by the missing-site assertion; the other four it reported were blind spots in the scan, now fixed.
+
 #### ColorPicker
 
 ```ts
@@ -1475,6 +1665,16 @@ export interface ColorPickerProps {
 }
 ```
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `value` | string |
+
+> `onChange` — Hex, including the leading '#'.
+
+> ⚠️ **`onChange` on web + rn — DIVERGES:** writes the value into `params` ONLY, never `args`. Survives only because the Tier-5 hosts merge params into args. Any consumer reading `args` — which rule 1 says is the payload map — gets nothing.
+
 #### OtpInput
 
 ```ts
@@ -1494,6 +1694,21 @@ export interface OtpInputProps {
 
 > ⚠️ **Implemented, but these props are inert on ios:** `onChange`, `onComplete` — Neither callback dispatches.
 
+**Dispatches** — see [What a control sends](#what-a-control-sends-action-payloads):
+
+| callback | key | type |
+|---|---|---|
+| `onChange` | `value` | string |
+| `onComplete` | `value` | string |
+
+> `onChange` — The assembled code. Only RN dispatches today; web, iOS and Android render the boxes read-only.
+
+> ⚠️ **`onChange` on web + ios + android — DIVERGES:** renders the digit boxes without wiring onChange — the control dispatches nothing. Unimplemented rather than divergent, but it must be declared: leaving OtpInput out of the contract is what let the gate whitelist RN's payload without checking it.
+
+> `onComplete` — Fires once the last box is filled, carrying the same assembled code as onChange. Declared separately because it is a second public callback — leaving it out left one outside the contract.
+
+> ⚠️ **`onComplete` on web + ios + android — DIVERGES:** renders the digit boxes without wiring onChange — the control dispatches nothing. Unimplemented rather than divergent, but it must be declared: leaving OtpInput out of the contract is what let the gate whitelist RN's payload without checking it.
+
 ### Cross-cutting & media
 
 #### Fab

package/guides/recipe-dynamic-list.md

@@ -14,6 +14,13 @@ lists) and `apps/family-cart` (cart list). The `examples/dynamic-list.*` pair th
 card grids). `Carousel` and `Menu` take `itemsPath` the same way. Do **not** hand-roll
 a "VStack of Cards" — that renders only static items and can't bind live data.
 
+**`Grid` is not a `LazyList` with one column.** It shares `itemsPath` and the row
+template, and nothing else: the gesture props in §5 (`onPullToRefresh`, `pagination`)
+and `stickyHeader`/`rowSwipeActions` are declared on `LazyListProps` only. A key `Grid`
+does not declare is **silently dropped** by the native decoders (`ignoreUnknownKeys =
+true`) — `himi validate` catches it and names the declared set, but nothing catches it
+at runtime. If you need pull-to-refresh or load-more, use `LazyList`.
+
 ## The shape (canonical off-repo)
 
 ```jsonc
@@ -70,6 +77,25 @@ including derived presentation fields (`initial` for an avatar letter, `hasImage
 booleans, pre-formatted date lines). Vertical-client responses are raw REST JSON —
 map them defensively; typed-looking fields can be absent at runtime.
 
+**One carve-out, and it is the useful one: a NESTED REPEATER may bind to the row's own
+array.** "Flat fields" is about *scalar* bindings — `$item.price`, not
+`$item.priceData.formatted.amount`. A `Carousel`/`LazyList`/`Grid` *inside* a row template
+may set `itemsPath: "$item.<field>"` and render that element's own array, with its own
+`$item.` scope one level down. All four renderers resolve it as of #2265; before that fix web
+rendered zero rows silently, which is why older guidance says it cannot be done. So a photo
+carousel per feed row **is** expressible:
+
+```jsonc
+{ "id": "photos_$item.id", "body": { "package": "himalaya", "type": "Carousel",
+    "props": { "itemsPath": "$item.images",           // ← the ROW's array, not a $service: path
+               "items": [ { "id": "photo_$item.url", "body": { "package": "himalaya",
+                            "type": "Image", "props": { "url": "$item.url" } } } ] } } }
+```
+
+`normalize()` still has to put a real array on the row (`images: []`, never `null`), and the
+inner template obeys every rule above — flat scalar fields, no strict-enum bindings. Keep the
+nesting to one level: a carousel of carousels is legal and unreadable.
+
 ## 3. The descriptor binds the array
 
 ```jsonc
@@ -130,8 +156,10 @@ full state-machine idiom: `himi docs recipe-four-state`.
 
 ## 5. Refresh + load-more gestures (RFC 0008)
 
-`LazyList` (and `Grid` in list mode) takes two optional gesture props — both are
-plain action wiring, no new worker concepts:
+`LazyList` takes two optional gesture props — both are plain action wiring, no new
+worker concepts. **`LazyList` only**: `GridProps` declares `items`, `columns`,
+`columnsMedium`, `columnsExpanded`, `spacing`, `itemsPath` and `staggerMs`, and the
+native decoders drop anything else without a word:
 
 ```jsonc
 "props": {
@@ -159,6 +187,21 @@ plain action wiring, no new worker concepts:
 - APIs that don't page (or v1 fallbacks without cursors) simply never set
   `nextCursor` — the gesture props are safe to leave in place.
 
+## 6. Tapping a row into a detail screen
+
+A row usually opens something, and the id space is usually unbounded (every product, every
+listing). **Use ONE canonical detail screen and pass the id as a nav param** — the row's action is
+`{ "actionId": "himi.open", "params": { "screenId": "property_detail", "id": "$item.id" } }`, and
+the detail worker reads `himalaya.input.id`.
+
+The alternative, a **templated route** (`screens.templated` with a `pattern`), is for a *bounded*
+catalog and nothing else. It resolves live for any id while you are developing, which is what makes it
+look like the general answer — but a production OTA release serves only `screens.exact`, so the
+build materializes one screen per id from the route's `seedIds` and a record created after that
+push is simply not in the release. Reach for it when the set is small and known (a handful of
+categories); reach for the canonical screen whenever the ids come from a live collection.
+Mechanics and the prod caveat in full: `himi docs tier-5-add-a-screen`.
+
 ## Gotchas (each of these has cost an agent a full push→drive cycle)
 
 - **`itemsPath` must bind to an array.** `himi validate` errors if the bound path's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.943.0",
+  "version": "0.945.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -64,5 +64,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "20d4d02bfd992d1556a2c7e77e8eae63a7b4ec23e7c9e082ff43e951"
+  "falconPackageHash": "7c47343c4a5027aabc50c963502aa5034b2828f8bf4e1e133fec1b94"
 }