@wix/himalaya-cli 0.837.0 → 0.838.0

package/dist/cli.mjs

@@ -42448,7 +42448,7 @@ async function crawlScreenJourney(opts) {
   });
 }
 async function crawlScreenInner(opts) {
-  const { screenId, descriptor, bundleJs, knownScreenIds } = opts;
+  const { screenId, descriptor, bundleJs, knownScreenIds, linkableScreenIds } = opts;
   const { call: wixCall, label: transport } = layeredTransport({
     rules: opts.rules,
     cmsSeed: opts.cmsSeed,
@@ -42833,13 +42833,44 @@ async function crawlScreenInner(opts) {
       w.dispose();
     }
   }
+  const edges = dedupeEdges(navEdges);
+  if (linkableScreenIds?.size && !opts.capabilitySuccess) {
+    const linkable = linkableScreenIds;
+    const resolvesToLinkable = (target) => {
+      if (linkable.has(target)) return true;
+      for (const base of linkable) {
+        if (target.length > base.length + 1 && target.startsWith(base)) {
+          const sep11 = target[base.length];
+          if (sep11 === "_" || sep11 === "/") return true;
+        }
+      }
+      return false;
+    };
+    const reported = /* @__PURE__ */ new Set();
+    for (const e of edges) {
+      if (e.target === screenId) continue;
+      if (reported.has(e.target)) continue;
+      if (knownScreenIds.has(e.target) || resolvesToLinkable(e.target)) continue;
+      reported.add(e.target);
+      findings.push({
+        screen: screenId,
+        trigger: "boot",
+        invariant: "nav-target-missing",
+        severity: "warning",
+        message: `"himi.open" targets "${e.target}", which is neither a baked screen nor one of this app's ${linkable.size} linkable screens (nor an instance of one) \u2014 the tap opens nothing`,
+        at: e.via,
+        actual: e.target,
+        hint: "add the screen, or declare it in navigation.linkableScreens if it is a templated route the router resolves at runtime"
+      });
+    }
+  }
   return {
     screen: screenId,
     transport,
     bundle: bundleJs ? descriptor?.logicBundle?.url ?? "bundle" : null,
     actionsExercised: exercised,
     actionsSkipped,
-    navEdges: dedupeEdges(navEdges),
+    navEdges: edges,
     ...observations ? { observations } : {},
     ...unobservedActions.length ? { unobservedActions } : {},
     findings: dedupe(findings),
@@ -45015,6 +45046,7 @@ async function runCrawl(opts) {
       bundleJs: baked.bundleJs,
       bundleMap: baked.bundleMap ?? null,
       knownScreenIds,
+      ...opts.linkableScreenIds?.size ? { linkableScreenIds: opts.linkableScreenIds } : {},
       rules: net?.rules ?? null,
       ...opts.cmsSeed && Object.keys(opts.cmsSeed).length ? { cmsSeed: opts.cmsSeed } : {},
       ...opts.canned?.count ? { canned: opts.canned.byKey } : {},
@@ -62333,6 +62365,10 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
             ...cmsSeed ? { cmsSeed } : {},
             ...canned ? { canned } : {},
             ...tabRoots.size ? { tabRoots } : {},
+            // The app's exact linkable set, straight off the build outcome (#2512) — arms the
+            // nav-target check. Omitted when the build reported none, so the crawl stays silent
+            // rather than judging every target against an empty set.
+            ...outcome.linkableScreenIds?.length ? { linkableScreenIds: new Set(outcome.linkableScreenIds) } : {},
             ...deep ? { deep } : {},
             ...offline ? { offline: true } : {},
             ...offline || flags["no-hostile"] === true ? { hostile: false } : {},

package/guides/himi-test.md

@@ -109,6 +109,7 @@ Only **unambiguous** defects, so a green run stays worth trusting:
 | `unresolved-wix-media` | error | A media-typed prop holding a raw Wix media handle/id the renderer cannot load. |
 | `binding-unresolved` | error / warning | A `$service:` binding aimed at state the worker never defines. It is an error when the missing value can leave visible UI blank. A direct prop with sibling `collapseWhenEmpty: true` is an advisory warning instead: the renderer deliberately removes that zero-size optional chrome, while the warning keeps the omitted contract auditable. |
 | `nav-param-dropped` | error | A bound `himi.open` param that resolves to nothing, so the target opens without it and error-cards. |
+| `nav-target-missing` | **warning** | A `himi.open` whose target is neither a baked screen, nor one of the app's declared `linkableScreens`, nor an instance of one (`course_detail_c1` under the base `course_detail`) — the tap opens nothing. Only judged when the caller supplies the app's exact linkable set; an absent set means no opinion, never a guess. A target still carrying an **unresolved** `$` token is dropped before it becomes an edge and is never judged — but one that RESOLVED to a concrete id is judged, which is the point: `$item.detailScreenId` resolving to `course_detail_c1` against the first row is exactly the case the instance rule exists for. |
 | `poll-action-missing` | error | A `_poll` directive every host will silently ignore — an action the bundle never declares, a malformed `action`, a missing `id`, or a non-positive `intervalMs`. Each ends the same way: a screen that never refreshes, with nothing saying why. Nothing in the descriptor names the polled action, so no static check can see it. (A merely too-small interval is legal — the host clamps it.) |
 | `no-request-issued` | **warning** | A worker that uses the Wix transport but never fetches — "the screen loaded with sample data." A warning: a conditional or tap-triggered fetch is legitimate. |
 | `native-decode-failed` | error | Under `--native`, the real Swift/Kotlin decoder rejected the baked descriptor bytes (one bad enum blanks the whole screen on device). |
@@ -120,8 +121,25 @@ Only **unambiguous** defects, so a green run stays worth trusting:
 | `typed-value-ignored` | **warning** | The crawl typed the value a control really carries — the payload key every renderer injects for that control — and the dispatch changed **nothing**: no state, no navigation, no request. The value is read off the app itself (an id from the control's own options, or a word from the worker's seeded state) and is always one the control is *not* already showing, so a reducer that ignores it cannot work on device. A warning because the input is the crawl's: a reducer that legitimately no-ops on a value is possible, and `himi-test.json` `skip[]` takes the invariant. |
 
 **Deliberately never reported:** an empty collection · an `error` state (often the correct
-answer to empty input) · a `null` optional · whether a nav target *exists* (approximating
-the router's real screen set flagged working deep links as dead on 15 of 37 corpus apps).
+answer to empty input) · a `null` optional.
+
+**Nav-target existence was on that list and came off it — read why before trusting it.**
+Judging a target against an *approximation* of the router's screen set flagged working deep
+links as dead on 15 of 37 apps, which retired the check. The exact set is the app-config's
+`linkableScreens`, and a reader bug meant it arrived empty for a long time — so that verdict
+was really measured against the **baked screen ids alone**, which is the approximation, not
+against the exact set it was supposed to use.
+
+Re-measured with the exact set, the check needed one more rule before it was silent: a linkable
+entry declares a **base** (`course_detail`, with `paramKeys`) while a row navigates to a
+worker-computed **instance** (`course_detail_c1`), and plain set membership reported two working
+deep links as dead. With base-covers-its-instances it is silent everywhere it was measured —
+**19 of 19 apps, no false positives.**
+
+It ships at `warning`, with one real catch behind it: an app that declared four of its five
+templated detail routes in `linkableScreens` and omitted the fifth, so a deep link to that
+screen could not resolve while the in-app tap still worked. That is what distinguishes it from
+a check that merely never fires.
 
 > **A false failure is worse than no tool.** It teaches an author to stop reading the
 > output, and then the real findings go unread too. When in doubt, the crawl stays quiet.

package/guides/testing-himi-apps.md

@@ -115,13 +115,20 @@ Only **unambiguous** defects, so a green run stays worth trusting:
 | every `$service:` binding names state the worker actually defines | a binding aimed at nothing (service, or its first path segment — a deeper miss on an empty list is legitimately data-dependent and is **not** reported) |
 | no nav param silently dropped | a bound `himi.open` param that resolves to nothing is **dropped** ([actionParams.ts](../core/web-renderer/src/actionParams.ts)), so the target opens without it and error-cards |
 | a worker that uses the Wix transport actually issued a request | "the fetch never left and the screen loaded with sample data" — a **warning**, since a conditional or tap-triggered fetch is legitimate |
+| a nav target actually resolves | a `himi.open` at a screen that is neither baked, nor declared in `linkableScreens`, nor an instance of a declared base — a **warning**, and only when the app's exact linkable set is available |
 
 Deliberately **not** reported: an empty collection, an `error` state (often the correct answer
-to empty input), a `null` optional field, and whether a nav target screen exists (the router's
-real set is the union of baked screens, config-declared templated bases, and nav overrides —
-approximating it flagged working deep links as dead on 15 of 37 corpus apps). When in doubt the
-crawl stays quiet: one false failure teaches an author to stop reading the output, and then the
-real findings go unread too.
+to empty input), and a `null` optional field. When in doubt the crawl stays quiet: one false
+failure teaches an author to stop reading the output, and then the real findings go unread too.
+
+Nav-target existence was on that list until recently. The router's real set is the union of baked
+screens, config-declared templated bases **and their instances**, and nav overrides —
+approximating it flagged working deep links as dead on 15 of 37 apps. That verdict was measured
+against baked ids alone, because a reader bug left the exact set (`linkableScreens`) empty. With
+the exact set, plus the rule that a declared base covers its instances, it measured silent on
+all 19 apps it was run against — **no false positives, and one real catch**: a templated detail
+route an app never declared linkable, so deep links to it could not resolve. See
+[himi-test.md](himi-test.md) for the full history.
 
 ### It runs the worker the way the DEVICE does
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.837.0",
+  "version": "0.838.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": [
@@ -63,5 +63,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "358928473c090a4ddfc84e0818462623d39870fc81acde3e9b21a28f"
+  "falconPackageHash": "9fd823cad2c263e2917b872794458e3c97e9ffc0040e182088a08fa5"
 }