@wix/himalaya-cli 0.1460.0 → 0.1462.0

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

@@ -101,6 +101,8 @@ export interface NavToScreen {
     /** How to show it. Absent ⇒ `push`. */
     presentation?: "push" | "replace" | "sheet" | "full_screen";
     tab?: never;
+    /** Only a {@link NavToTab} resets; without a `tab` it would be ignored as a plain push. */
+    reset?: never;
 }
 /**
  * Leave the current screen. `back` pops the current stack. On iOS and Android, inside an
@@ -114,27 +116,57 @@ export interface NavBackOrDismiss {
     screenId?: never;
     args?: never;
     tab?: never;
+    reset?: never;
 }
 /**
  * Switch to the top-level destination with this id — a tab-bar item, or a sidebar-rail
  * item on a wide layout. The host closes any open sheet first. An id the app is not
- * showing right now (unknown, or hidden by the nav worker) is ignored, and so is the tab
- * the user is already on (their stack is kept — it is not a re-tap). A tab switch is not a
+ * showing right now (unknown, or hidden by the nav worker) is ignored — the whole
+ * directive, so nothing is pushed anywhere — and a bare `{ tab }` for the tab the user is
+ * already on does nothing (their stack is kept — it is not a re-tap). A tab switch is not a
  * stack operation: a later `back` pops the NEW tab's stack, not the switch.
+ *
+ * Two optional follow-ups act on THAT tab once it is selected, in this order:
+ *  - `reset: true` pops the tab's stack to its root — even when it is the tab the user is
+ *    already on, the one case a worker causes the pop a user's re-tap causes;
+ *  - `screenId` (with `args`) is then pushed onto the tab's stack — never onto the tab the
+ *    action ran on. Only push is defined: a `presentation` next to a `tab` is dropped.
+ *
+ * So `{ tab: "orders", screenId: "order_detail", args: { id } }` switches to Orders and
+ * opens the order there; `{ tab: "create", reset: true }` returns to a clean tab root.
+ * `args` without a `screenId` has nowhere to go: every host drops it as ambiguous, so the
+ * type does not admit it (a union — `args` only next to `screenId`). Binaries older than this
+ * form drop `{ tab, screenId }` / `{ tab, reset }` whole; a worker that must support them
+ * can return `{ tab }` and push on the next action.
  */
-export interface NavToTab {
+export type NavToTab = {
+    tab: string;
+    /** Pop the tab to its root first. Literally `true` — anything else drops the directive. */
+    reset?: true;
+    /** Then push this screen onto the selected tab's stack. Must be linkable. */
+    screenId: string;
+    /** Nav params for the pushed screen. Strings only. */
+    args?: Record<string, string>;
+    presentation?: never;
+} | {
     tab: string;
+    /** Pop the tab to its root. Literally `true` — anything else drops the directive. */
+    reset?: true;
     screenId?: never;
+    /** `args` needs a `screenId` to go to — every host drops `{ tab, args }` as ambiguous. */
     args?: never;
     presentation?: never;
-}
+};
 /**
  * Attach a {@link NavDirective} to a state object an action returns. Sugar for
  * `{ ...state, _nav: target }` that keeps the field name in one place.
  *
  * `target` is exactly ONE of three forms — `{ screenId, args?, presentation? }`,
- * `{ presentation: "back" | "dismiss" }`, or `{ tab }`. A directive that mixes them
- * (a `tab` with a `screenId`, say) is dropped by every host.
+ * `{ presentation: "back" | "dismiss" }`, or `{ tab, reset?, screenId?, args? }`. In the
+ * tab form `reset: true` pops the selected tab to its root (even the current one) and
+ * `screenId` is pushed onto THAT tab's stack (see {@link NavToTab}). A directive that
+ * mixes the forms otherwise (a `tab` with a `presentation`, or `back` with `args`) is
+ * dropped by every host.
  */
 export declare function navigate<S extends object>(state: S, target: NavDirective): S & {
     _nav: NavDirective;

package/dist/cli.mjs

@@ -7310,6 +7310,18 @@ function compileV2(html, profile, options) {
           mods[name2] = coerce(raw, field2);
           structured(el2, mods[name2]);
         }
+        if (name2 === "onMeasure" && mods.onMeasure && typeof mods.onMeasure === "object") {
+          for (const [key3, value] of Object.entries(mods.onMeasure)) {
+            if (!key3.endsWith("Path") || typeof value !== "string") continue;
+            if (value.startsWith("$service:") || info4?.paths.has(statePath(value))) {
+              const axis = key3.replace(/Path$/, "");
+              const taken = (k2) => !!info4?.paths.has(statePath(k2));
+              let suggestion = taken(axis) ? `measured${axis[0].toUpperCase()}${axis.slice(1)}` : axis;
+              for (let n2 = 2; taken(suggestion); n2++) suggestion = `measured${axis[0].toUpperCase()}${axis.slice(1)}${n2}`;
+              error(el2, "HHP-MEASURE-TARGET", `onMeasure.${key3} ${value} names controller state; measurements publish only to the renderer's measure store.`, `Use a store key (e.g. "${suggestion}") and read it back with a $measure:<key> modifier path.`);
+            }
+          }
+        }
         continue;
       }
       const name = nativeField(attr3.startsWith("data-prop-") ? attr3.slice(10) : attr3);
@@ -8115,7 +8127,6 @@ function resolveTranslation(value, catalog3, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
-    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s2) => s2 !== "t").join("|")})\\b|^\\$t:`
@@ -162161,32 +162172,32 @@ var init_preview_assets_generated = __esm({
   "../../packages/serve/src/preview-assets.generated.ts"() {
     init_preview_assets_format();
     PREVIEW_ASSET_MANIFEST = [
-      { key: "assets/DashboardHost-C43Yf5i0.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 2916, sha256: "ed853f04eb950f074bb4b910d5b54777a593265eb3e9b6b69865a534afb4e367" },
-      { key: "assets/DevDrawer-Dtpdyj6s.js", contentType: "application/javascript; charset=utf-8", offset: 2924, length: 16744, sha256: "bd3f6e0dc4d77df24edc6945bc3a9d8271db4bb87b6d5504dbeac0c979fe97cc" },
-      { key: "assets/IdiomCompare-Q0N9nyRz.js", contentType: "application/javascript; charset=utf-8", offset: 19668, length: 1892, sha256: "f8c8dd05dd97b368107937763ce0713a6fd2a1dd8fbb443184e05fa8177b678c" },
-      { key: "assets/LightboxViewer-DXQZfuRl.js", contentType: "application/javascript; charset=utf-8", offset: 21560, length: 8132, sha256: "3b864e63b7d1edb62ae343113b949596a7db90cb85a598a778ee0e29a7bede10" },
-      { key: "assets/PhonePreviewControl-DNUNrsXI.js", contentType: "application/javascript; charset=utf-8", offset: 29692, length: 37729, sha256: "de870adf633b1f1075bb27f0cb75b3526b6409fc246d8ed8166e02c466004034" },
-      { key: "assets/SchemeCompare-nZarcCIk.js", contentType: "application/javascript; charset=utf-8", offset: 67421, length: 1824, sha256: "5f668d6a07cc16c4ba72d5867cb73f947f82a88abcb74aaefb2096ded87ffe88" },
-      { key: "assets/index-CkZmNXjh.js", contentType: "application/javascript; charset=utf-8", offset: 69245, length: 1274560, sha256: "12bd2fba7aa7c1bb8b01ca5a2fe87ebf6a1f33651e5e86b031f9205677408aad" },
-      { key: "assets/pdf-CGOkyAKC.js", contentType: "application/javascript; charset=utf-8", offset: 1343805, length: 488199, sha256: "25e2f49761cb2b6ffc967924e0aeea1225f60db8c80404928a4f6c20061aa6a8" },
-      { key: "assets/pdf.worker.min-BQa_JDET.js", contentType: "application/javascript; charset=utf-8", offset: 1832004, length: 73, sha256: "41bcfda4f3c8c0a81c785ea87c69afc8e7d0ed8c333324aee94c273d881bb6aa" },
-      { key: "assets/pdf.worker.min-BmVo14Nb.mjs", contentType: "application/javascript; charset=utf-8", offset: 1832077, length: 1317034, sha256: "a33cfe728c584fdba4fcc1fd54bcdc2f9f2f13889ddbb5b2bd1d0f8cbe49b84e" },
-      { key: "assets/pdfDocument-lG038l52.js", contentType: "application/javascript; charset=utf-8", offset: 3149111, length: 2868, sha256: "2e062ad5b358932919bccd5594ece75c4e98f1a634811123cf334d791884663a" },
-      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 3151979, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
-      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 3156589, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
-      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 3645173, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
-      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 3736097, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
-      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 3827081, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
-      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 3918061, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
-      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 4008933, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
-      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 4099913, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
-      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 4208549, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
-      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 4317633, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
-      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 4426681, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
-      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 4534381, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
-      { key: "himi-sw.js", contentType: "application/javascript; charset=utf-8", offset: 4622489, length: 6748, sha256: "4a92459977d7cefa1a6a7e020c3a63509737f083b3f2773557c1a5771665811a" },
-      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 4629237, length: 4947, sha256: "8f83cd54a8228dc903c5530de84080a2aff80f9ad4b7223985eb9da54f3a5c71" },
-      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 4634184, length: 17786, sha256: "084107ca997628c248f1b0ba3a7494744850df39fad813546ab8bdb82a6058da" }
+      { key: "assets/DashboardHost-LrGNV-jS.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 2916, sha256: "e3a905085f463d9b91582f0ce8de0fc30731d04b5d258d67d9adcc3286641e56" },
+      { key: "assets/DevDrawer-C-C1YUSp.js", contentType: "application/javascript; charset=utf-8", offset: 2924, length: 16744, sha256: "4061f6ac1880864963f0934e3934c0a23c05c8a7cd707c90f39844475738ca47" },
+      { key: "assets/IdiomCompare-B5V4qfEB.js", contentType: "application/javascript; charset=utf-8", offset: 19668, length: 1892, sha256: "eeed738d8a460b5b5b4d4d5ba34fa2ad7eb49fc107166620109975f0239f165e" },
+      { key: "assets/LightboxViewer-E3ussy4X.js", contentType: "application/javascript; charset=utf-8", offset: 21560, length: 8132, sha256: "aec5fead81a6b3828fa1627e62a5cc0c7084fa6a59f17d1ee49fcab51e1d302a" },
+      { key: "assets/PhonePreviewControl-C5EMlBne.js", contentType: "application/javascript; charset=utf-8", offset: 29692, length: 37729, sha256: "e7318bd350df6dcde05ba204ba7512f8d0c33f8f2d90071c484a673070d2a185" },
+      { key: "assets/SchemeCompare-B4-6mjE4.js", contentType: "application/javascript; charset=utf-8", offset: 67421, length: 1824, sha256: "f237c7428db1d0078c3e0753f479dd3d925dcfd89377f0d4b6d757b6bb89df8f" },
+      { key: "assets/index-C5tjmjTk.js", contentType: "application/javascript; charset=utf-8", offset: 69245, length: 1276300, sha256: "822ecae23245ff7a53ba1dbceb5112e5e0b2a3f2d6bc82fccd34d06394a0c8b0" },
+      { key: "assets/pdf-BSJi7U_x.js", contentType: "application/javascript; charset=utf-8", offset: 1345545, length: 488199, sha256: "0f2d42d6e60dfa6bc4bca2d9123cd7e478cc714b9ec61acf87e36e63a07005b8" },
+      { key: "assets/pdf.worker.min-BQa_JDET.js", contentType: "application/javascript; charset=utf-8", offset: 1833744, length: 73, sha256: "41bcfda4f3c8c0a81c785ea87c69afc8e7d0ed8c333324aee94c273d881bb6aa" },
+      { key: "assets/pdf.worker.min-BmVo14Nb.mjs", contentType: "application/javascript; charset=utf-8", offset: 1833817, length: 1317034, sha256: "a33cfe728c584fdba4fcc1fd54bcdc2f9f2f13889ddbb5b2bd1d0f8cbe49b84e" },
+      { key: "assets/pdfDocument-DTMDemhm.js", contentType: "application/javascript; charset=utf-8", offset: 3150851, length: 2868, sha256: "a576fa3bb4a9cae01f3d29734ef1a6fd77945d40f97d956127e5b402412ad7c8" },
+      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 3153719, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
+      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 3158329, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
+      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 3646913, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
+      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 3737837, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
+      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 3828821, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
+      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 3919801, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
+      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 4010673, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
+      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 4101653, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
+      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 4210289, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
+      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 4319373, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
+      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 4428421, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
+      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 4536121, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
+      { key: "himi-sw.js", contentType: "application/javascript; charset=utf-8", offset: 4624229, length: 6748, sha256: "4a92459977d7cefa1a6a7e020c3a63509737f083b3f2773557c1a5771665811a" },
+      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 4630977, length: 4947, sha256: "ecf082412df3339e5f9134136dce4c8a9436e95f35c2ed87eb8195f194b78eb9" },
+      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 4635924, length: 17786, sha256: "084107ca997628c248f1b0ba3a7494744850df39fad813546ab8bdb82a6058da" }
     ];
   }
 });

package/guides/component-reference.md

@@ -2814,9 +2814,9 @@ A worker moves the user by returning `_nav` from an action (`navigate()` from
 |---|---|
 | `{ screenId, args?, presentation? }` | Open a linkable screen. `presentation` is `push` (the default), `replace`, `sheet` or `full_screen`, as in the table above. |
 | `{ presentation: "back" }` / `{ presentation: "dismiss" }` | As in the table above. No target. |
-| `{ tab: "<tabId>" }` | Switch to that tab: a `tabBar` item, or a sidebar-rail item on a wide layout. Any open sheet or cover closes first. An id the app is not showing (unknown, hidden, or no tab bar / rail at all) is ignored, and so is the tab the user is already on: its stack is kept, not popped to its root. |
+| `{ tab: "<tabId>", reset?: true, screenId?, args? }` | Switch to that tab: a `tabBar` item, or a sidebar-rail item on a wide layout. Any open sheet or cover closes first. An id the app is not showing (unknown, hidden, or no tab bar / rail at all) is ignored, whole. A bare `{ tab }` for the tab the user is already on does nothing: its stack is kept. Then, on THAT tab: `reset: true` pops its stack to its root (even on the current tab), and `screenId` (with `args`) is pushed onto it. |
 
-A `_nav` that mixes forms (a `tab` with a `screenId`, `back` with a `screenId`) is ignored.
+A `_nav` that mixes forms otherwise (a `tab` with a `presentation`, `args` with a `tab` but no `screenId`, `back` with a `screenId`) is ignored.
 
 - **Switching tabs is a worker `_nav`.** A `himi.open` whose target is another tab's root
   screen does not select that tab: it PUSHES the screen onto the current tab's stack.

package/guides/hhp.md

@@ -86,7 +86,9 @@ use a child `script type="application/himalaya-props"` containing JSON.
 ordinary-control aliases. Explicit modifiers use `data-mod-*` or `himi-mod-*`.
 A `…-path` modifier (`data-mod-hidden-path="full"`, `data-mod-background-color-path`)
 names controller state exactly like `bind:*`, or `$item.<field>` in a row; an unknown
-path is a lint error. `onMeasure` keys name the renderer's measure store instead.
+path is a lint error. `onMeasure` keys name the renderer's measure store instead
+(read back with a `$measure:<key>` path); no renderer writes a measurement into worker
+state, so an `onMeasure` key that names controller state is an `HHP-MEASURE-TARGET` error.
 `style` and `title` are HTML globals: `style` is always CSS, so a native `style`
 variant uses `variant="primary"`; `title="…"` sets a component's `title` field. CSS
 `font` applies only to text components (Text, Label, Marquee). The profile's

package/guides/sdk-reference.json

@@ -44,24 +44,24 @@
         "name": "NavToScreen",
         "kind": "interface",
         "jsdoc": "/**\n * Open a screen. `presentation` picks how: `push` (the default) onto the current tab's\n * stack, `replace` to show it in place of the current screen, or present it as a\n * `sheet` / `full_screen` modal.\n */",
-        "decl": "export interface NavToScreen {\n  /** Screen to open. Must be linkable, or the host ignores the directive. */\n  screenId: string;\n  /** Nav params for the target (e.g. the record `id`). Strings only. */\n  args?: Record<string, string>;\n  /** How to show it. Absent ⇒ `push`. */\n  presentation?: \"push\" | \"replace\" | \"sheet\" | \"full_screen\";\n  tab?: never;\n}"
+        "decl": "export interface NavToScreen {\n  /** Screen to open. Must be linkable, or the host ignores the directive. */\n  screenId: string;\n  /** Nav params for the target (e.g. the record `id`). Strings only. */\n  args?: Record<string, string>;\n  /** How to show it. Absent ⇒ `push`. */\n  presentation?: \"push\" | \"replace\" | \"sheet\" | \"full_screen\";\n  tab?: never;\n  /** Only a {@link NavToTab} resets; without a `tab` it would be ignored as a plain push. */\n  reset?: never;\n}"
       },
       {
         "name": "NavBackOrDismiss",
         "kind": "interface",
         "jsdoc": "/**\n * Leave the current screen. `back` pops the current stack. On iOS and Android, inside an\n * open sheet or cover it pops the modal's own stack and closes the modal at its root; on\n * web it pops the tab's stack, so close a modal with `dismiss`. `dismiss` closes the open\n * sheet / full-screen cover. Both are no-ops with nothing to leave. No target: the host\n * already knows where \"back\" is.\n */",
-        "decl": "export interface NavBackOrDismiss {\n  presentation: \"back\" | \"dismiss\";\n  screenId?: never;\n  args?: never;\n  tab?: never;\n}"
+        "decl": "export interface NavBackOrDismiss {\n  presentation: \"back\" | \"dismiss\";\n  screenId?: never;\n  args?: never;\n  tab?: never;\n  reset?: never;\n}"
       },
       {
         "name": "NavToTab",
-        "kind": "interface",
-        "jsdoc": "/**\n * Switch to the top-level destination with this id — a tab-bar item, or a sidebar-rail\n * item on a wide layout. The host closes any open sheet first. An id the app is not\n * showing right now (unknown, or hidden by the nav worker) is ignored, and so is the tab\n * the user is already on (their stack is kept — it is not a re-tap). A tab switch is not a\n * stack operation: a later `back` pops the NEW tab's stack, not the switch.\n */",
-        "decl": "export interface NavToTab {\n  tab: string;\n  screenId?: never;\n  args?: never;\n  presentation?: never;\n}"
+        "kind": "type",
+        "jsdoc": "/**\n * Switch to the top-level destination with this id — a tab-bar item, or a sidebar-rail\n * item on a wide layout. The host closes any open sheet first. An id the app is not\n * showing right now (unknown, or hidden by the nav worker) is ignored — the whole\n * directive, so nothing is pushed anywhere — and a bare `{ tab }` for the tab the user is\n * already on does nothing (their stack is kept — it is not a re-tap). A tab switch is not a\n * stack operation: a later `back` pops the NEW tab's stack, not the switch.\n *\n * Two optional follow-ups act on THAT tab once it is selected, in this order:\n *  - `reset: true` pops the tab's stack to its root — even when it is the tab the user is\n *    already on, the one case a worker causes the pop a user's re-tap causes;\n *  - `screenId` (with `args`) is then pushed onto the tab's stack — never onto the tab the\n *    action ran on. Only push is defined: a `presentation` next to a `tab` is dropped.\n *\n * So `{ tab: \"orders\", screenId: \"order_detail\", args: { id } }` switches to Orders and\n * opens the order there; `{ tab: \"create\", reset: true }` returns to a clean tab root.\n * `args` without a `screenId` has nowhere to go: every host drops it as ambiguous, so the\n * type does not admit it (a union — `args` only next to `screenId`). Binaries older than this\n * form drop `{ tab, screenId }` / `{ tab, reset }` whole; a worker that must support them\n * can return `{ tab }` and push on the next action.\n */",
+        "decl": "export type NavToTab =\n  | {\n      tab: string;\n      /** Pop the tab to its root first. Literally `true` — anything else drops the directive. */\n      reset?: true;\n      /** Then push this screen onto the selected tab's stack. Must be linkable. */\n      screenId: string;\n      /** Nav params for the pushed screen. Strings only. */\n      args?: Record<string, string>;\n      presentation?: never;\n    }\n  | {\n      tab: string;\n      /** Pop the tab to its root. Literally `true` — anything else drops the directive. */\n      reset?: true;\n      screenId?: never;\n      /** `args` needs a `screenId` to go to — every host drops `{ tab, args }` as ambiguous. */\n      args?: never;\n      presentation?: never;\n    };"
       },
       {
         "name": "navigate",
         "kind": "function",
-        "jsdoc": "/**\n * Attach a {@link NavDirective} to a state object an action returns. Sugar for\n * `{ ...state, _nav: target }` that keeps the field name in one place.\n *\n * `target` is exactly ONE of three forms — `{ screenId, args?, presentation? }`,\n * `{ presentation: \"back\" | \"dismiss\" }`, or `{ tab }`. A directive that mixes them\n * (a `tab` with a `screenId`, say) is dropped by every host.\n */",
+        "jsdoc": "/**\n * Attach a {@link NavDirective} to a state object an action returns. Sugar for\n * `{ ...state, _nav: target }` that keeps the field name in one place.\n *\n * `target` is exactly ONE of three forms — `{ screenId, args?, presentation? }`,\n * `{ presentation: \"back\" | \"dismiss\" }`, or `{ tab, reset?, screenId?, args? }`. In the\n * tab form `reset: true` pops the selected tab to its root (even the current one) and\n * `screenId` is pushed onto THAT tab's stack (see {@link NavToTab}). A directive that\n * mixes the forms otherwise (a `tab` with a `presentation`, or `back` with `args`) is\n * dropped by every host.\n */",
         "decl": "export function navigate<S extends object>(\n  state: S,\n  target: NavDirective,\n): S & { _nav: NavDirective };"
       },
       {

package/guides/tier-5-add-a-screen.md

@@ -714,11 +714,15 @@ a tapped `himi.open` would — including the `args` arriving as `himalaya.input`
 |---|---|
 | `{ screenId, args?, presentation? }` | Opens the screen. `presentation` is `push` (the default), `replace`, `sheet` or `full_screen` — the same verbs a descriptor action uses. |
 | `{ presentation: "back" }` or `{ presentation: "dismiss" }` | `back` pops the current screen; `dismiss` closes the open sheet or full-screen cover. No target. |
-| `{ tab: "<tabId>" }` | Switches to that tab — a `tabBar` item, or a sidebar-rail item on a wide layout. |
+| `{ tab: "<tabId>", reset?: true, screenId?, args? }` | Switches to that tab — a `tabBar` item, or a sidebar-rail item on a wide layout. With `reset: true` it then pops that tab to its root. With `screenId` it then pushes that screen, with `args`, onto **that** tab's stack. |
 
 ```ts
 cancel: (s) => navigate({ ...s, draft: null }, { presentation: "dismiss" }),
 viewOrders: (s) => navigate(s, { tab: "orders" }),
+// switch to Orders AND open order 42 there, in one result:
+viewOrder: (s) => navigate(s, { tab: "orders", screenId: "order_detail", args: { id: "42" } }),
+// return the user to a clean Create tab, even if they are already on it:
+startOver: (s) => navigate({ ...s, draft: null }, { tab: "create", reset: true }),
 ```
 
 The rules:
@@ -726,9 +730,12 @@ The rules:
 - `screenId` must be a **linkable** screen (`navigation.linkableScreens`), or the host
   ignores the directive.
 - `args` values are **strings only**; anything else is dropped rather than coerced.
-- A directive that mixes forms — a `tab` with a `screenId`, `back` with a `screenId`, `back`
-  with `args` — or names a verb outside its form (`alert`, `snackbar`) is **ignored** and
-  logged as `nav_verb_dropped`.
+- A directive that mixes forms — a `tab` with a `presentation`, a `tab` with `args` but no
+  `screenId`, `back` with a `screenId`, `back` with `args` — or names a verb outside its form
+  (`alert`, `snackbar`) is **ignored** and logged as `nav_verb_dropped`. Only push is defined
+  for a `screenId` next to a `tab`.
+- `reset` must be literally `true`. `false`, `"true"` or `1` drops the whole directive
+  (`bad_reset`).
 
 Return `_nav` rather than calling `dispatch("himi.open", …)` from a worker. Current runtimes
 route a worker's `himi.open` dispatch on all three hosts, but older iOS and Android binaries
@@ -753,7 +760,18 @@ target is another tab's root screen does not select that tab — it pushes the s
   the app has no tab bar or sidebar rail (`single` / `drawer` navigation) — is ignored and
   logged as `nav_verb_dropped`. The user stays where they are.
 - Asking for the tab the user is already on does nothing. It does **not** pop that tab to its
-  root the way a second tap on the tab bar does.
+  root the way a second tap on the tab bar does — unless you ask for it with `reset: true`.
+- `reset: true` pops the selected tab to its root, even when it is the current tab. This is
+  the same pop as a second tap on the tab bar, and a tab already at its root does not move.
+- A `screenId` next to the `tab` is pushed onto the **selected** tab's stack, after any reset,
+  never onto the tab the action ran on. `back` from it returns to that tab's root (or to
+  whatever the tab held before the push). If the tab id is ignored, nothing is pushed
+  anywhere.
+- Runtimes older than this form ignore `{ tab, screenId }` and `{ tab, reset }` as mixed
+  forms. If your app must support them, return `{ tab }` and push from the next action.
+- Only a returned `_nav` can reset or push on the tab. A `himi.tab` action written in a
+  descriptor, or sent with `dispatch("himi.tab", …)`, switches the tab and ignores any
+  `screenId` or `reset` it carries.
 - A tab switch is not a step on a stack: a later `back` pops the **new** tab's stack and does
   not return to the previous tab. On web the switch is also a browser-history entry, so the
   browser's own Back button returns to the previous tab; iOS and Android have no equivalent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1460.0",
+  "version": "0.1462.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": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "671905888b8bae86b934860d075660df2589c4d9791b110e75cc5b8b"
+  "falconPackageHash": "d40739f8a350f4cf15d4ea5e3677bd4b4b29a3c9311c8e80752b9d3b"
 }