@wix/himalaya-cli 0.855.0 → 0.856.0

package/dist/cli.mjs

@@ -832,19 +832,120 @@ var init_source_deny = __esm({
 });
 
 // src/mobile-ux-contract.ts
+function mobileUxDocumentBody(mobile) {
+  const comments = /<!--[\s\S]*?(?:-->|$)/g;
+  let out = "";
+  let last = 0;
+  let blankBefore = true;
+  for (const match of mobile.matchAll(comments)) {
+    const offset = match.index ?? 0;
+    const between = mobile.slice(last, offset);
+    const newline = between.lastIndexOf("\n");
+    if (newline >= 0) blankBefore = between.slice(newline + 1).trim() === "";
+    else blankBefore = blankBefore && between.trim() === "";
+    out += between;
+    const ownsTheLine = offset === 0 || mobile[offset - 1] === "\n";
+    const precedesHeading = blankBefore && mobile.startsWith("#", offset + match[0].length);
+    out += ownsTheLine || precedesHeading ? "\n" : " ";
+    last = offset + match[0].length;
+  }
+  return out + mobile.slice(last);
+}
+function mobileUxSection(text2, heading) {
+  const match = new RegExp(`(?:^|\\n)##[ \\t]+${heading}\\b[^\\n]*([\\s\\S]*?)(?=\\n##[ \\t]|$)`, "i").exec(text2);
+  return match ? match[1] : null;
+}
+function sectionTables(markdown) {
+  const lines = markdown.split("\n").map((line) => line.trim());
+  const tables = [];
+  for (let i = 1; i < lines.length; i++) {
+    if (!DELIMITER_ROW.test(lines[i])) continue;
+    const header = lines[i - 1];
+    if (!header.includes("|")) continue;
+    const table = { header: splitCells(header), data: [] };
+    let j = i + 1;
+    for (; j < lines.length; j++) {
+      const line = lines[j];
+      if (!line.includes("|")) break;
+      if (DELIMITER_ROW.test(line)) continue;
+      const cells = splitCells(line);
+      if (cells.every((cell) => cell === "")) continue;
+      table.data.push(cells);
+    }
+    tables.push(table);
+    i = j;
+  }
+  return tables;
+}
+function namesOneCta(cell) {
+  if (!cell) return false;
+  return !/[,;]|\s\/\s/.test(cell);
+}
+function declaredStates(text2) {
+  const contract = section(text2, "Screen contract");
+  if (!contract) return [];
+  const states = [];
+  for (const bullet of contract.matchAll(/^[ \t]*[-*][ \t]*[^:\n]*\bstates?[ \t]*:[ \t]*(\S.*)$/gim)) {
+    const items = bullet[1].split(/[,;/]/).map((item) => item.trim().replace(/[.:]+$/, "")).filter(Boolean);
+    if (!items.length || items.some((item) => !/^[\w][\w.\-+]*$/.test(item))) continue;
+    states.push(...items);
+  }
+  return [...new Set(states.map((state) => state.toLowerCase()))];
+}
+function primaryCtaStructureGap(text2) {
+  const acceptance = section(text2, "Implementation acceptance");
+  if (acceptance === null) return "There is no `## Implementation acceptance` section to read it from.";
+  const tables = sectionTables(acceptance).filter((table) => table.data.length > 0);
+  if (!tables.length) return "Its acceptance table has no rows.";
+  const ctaTables = tables.map((table) => ({ table, cta: table.header.findIndex((cell) => /primary\s*(?:cta|call[- ]?to[- ]?action|action)/i.test(cell)) })).filter((entry) => entry.cta >= 0);
+  if (!ctaTables.length) return "Its acceptance table has no `Primary CTA` column.";
+  const unanswered = ctaTables.flatMap(({ table, cta }) => table.data.filter((row) => !namesOneCta(row[cta] ?? "")));
+  if (unanswered.length) {
+    return `${unanswered.length} acceptance row(s) do not name exactly one primary CTA (first: ${JSON.stringify(unanswered[0][0] ?? "")}).`;
+  }
+  const data = ctaTables.flatMap(({ table }) => table.data);
+  const flat = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+  const rowText = data.map((row) => flat(row.join(" ")));
+  const missing = declaredStates(text2).filter((state) => !rowText.some((row) => row.includes(flat(state))));
+  if (missing.length) return `The acceptance table has no row for the declared state(s): ${missing.join(", ")}.`;
+  return null;
+}
+function hasUnterminatedComment(mobile) {
+  let i = 0;
+  for (; ; ) {
+    const open = mobile.indexOf("<!--", i);
+    if (open < 0) return false;
+    const close = mobile.indexOf("-->", open + 4);
+    if (close < 0) return true;
+    i = close + 3;
+  }
+}
 function mobileUxMarkerFindings(mobile) {
+  const text2 = mobileUxDocumentBody(mobile);
   const findings = [];
-  if (!/^## Implementation acceptance\b/im.test(mobile)) {
-    findings.push({ code: "missing-acceptance-matrix", message: "MOBILE-UX.md must contain the exact heading `## Implementation acceptance`." });
+  if (!/^## Implementation acceptance\b/im.test(text2)) {
+    findings.push({ code: "missing-acceptance-matrix", message: "MOBILE-UX.md must contain the heading `## Implementation acceptance` at the start of a line. Case is not checked, but use this spelling: other tooling addresses the document by it." });
   }
-  if (!/^## Evidence\b/im.test(mobile)) {
-    findings.push({ code: "missing-evidence-section", message: "MOBILE-UX.md must contain the exact heading `## Evidence`." });
+  if (!/^## Evidence\b/im.test(text2)) {
+    findings.push({ code: "missing-evidence-section", message: "MOBILE-UX.md must contain the heading `## Evidence` at the start of a line. Case is not checked, but use this spelling: other tooling addresses the document by it." });
   }
-  if (!/one primary CTA per state/i.test(mobile)) {
-    findings.push({ code: "missing-primary-cta-rule", message: "MOBILE-UX.md must include the exact phrase `one primary CTA per state`." });
+  if (!/one primary CTA per state/i.test(text2)) {
+    const gap = primaryCtaStructureGap(text2);
+    if (gap) {
+      findings.push({
+        code: "missing-primary-cta-rule",
+        message: "MOBILE-UX.md must establish one primary CTA per state: give `## Implementation acceptance` a `Primary CTA` column with a row per declared state and exactly one CTA in each cell, or keep the phrase `one primary CTA per state`. " + gap
+      });
+    }
   }
-  if (!hasWidthEvidence(mobile)) {
-    findings.push({ code: "missing-width-evidence", message: widthEvidenceMessage(mobile) });
+  if (!hasWidthEvidence(text2)) {
+    findings.push({ code: "missing-width-evidence", message: widthEvidenceMessage(text2) });
+  }
+  if (findings.length && hasUnterminatedComment(mobile)) {
+    return [{
+      code: "unterminated-html-comment",
+      message: "MOBILE-UX.md has an HTML comment opened with `<!--` and never closed with `-->`, so everything after it is commented out \u2014 in this check and in any renderer. Close the comment and re-run: the headings and phrases below it are not being read."
+    }];
   }
   return findings;
 }
@@ -911,7 +1012,7 @@ function widthEvidenceMessage(mobile) {
   }
   return base;
 }
-var SPEC_TEMPLATE, MOBILE_UX_TEMPLATE, WIDTH_LITERAL, COMPACT_MAX, WIDER_MIN, PLAUSIBLE_WIDTH, YEAR, inRange, looksLikeYear, UNIT_ATTACHED, UNIT_WORD_ATTACHED, WIDTH_WINDOW, EDGE_WINDOW, FILENAME_AFTER, ANTI_CUE_BEFORE, PAIR_HEIGHT_BEFORE, ANTI_CUE_AFTER, isCompact, isWider;
+var SPEC_TEMPLATE, MOBILE_UX_MARKER_NOTE, MOBILE_UX_TEMPLATE, section, DELIMITER_ROW, splitCells, WIDTH_LITERAL, COMPACT_MAX, WIDER_MIN, PLAUSIBLE_WIDTH, YEAR, inRange, looksLikeYear, UNIT_ATTACHED, UNIT_WORD_ATTACHED, WIDTH_WINDOW, EDGE_WINDOW, FILENAME_AFTER, ANTI_CUE_BEFORE, PAIR_HEIGHT_BEFORE, ANTI_CUE_AFTER, isCompact, isWider;
 var init_mobile_ux_contract = __esm({
   "src/mobile-ux-contract.ts"() {
     SPEC_TEMPLATE = `# App specification
@@ -938,8 +1039,33 @@ var init_mobile_ux_contract = __esm({
 - Required: iOS, Android
 - Optional: web, desktop, watch, widgets
 `;
+    MOBILE_UX_MARKER_NOTE = `<!-- LOAD-BEARING \u2014 read this before you rewrite the file.
+
+     \`himi validate\` warns, and \`himi validate --strict\` / \`himi ux audit --strict\` REFUSE, a
+     MOBILE-UX.md that satisfies none of the forms below. Everything else here is yours to
+     replace freely. This comment is not itself an answer: HTML comments are stripped before the
+     check runs, so keeping it satisfies nothing.
+
+       1. The headings \`## Implementation acceptance\` and \`## Evidence\`, each at the start of
+          a line. Case is not checked; use these spellings anyway, because other tooling
+          addresses this document by them.
+       2. One primary CTA per state \u2014 EITHER the phrase \`one primary CTA per state\`, OR a
+          \`Primary CTA\` column in the acceptance table below, with a row for every state you
+          declare under \`## Screen contract\` and exactly one CTA named in each row's cell.
+       3. Width evidence \u2014 EITHER the scaffold's own sentence, \`compact (320/360)\` followed by
+          \`expanded\`, OR two widths you actually rendered, EACH SPELLED AS A WIDTH ON ITSELF:
+          one below 600px and one at 600px or wider, within about 400 characters of each other.
+          A number is spelled as a width when it carries a unit (\`320px\`, \`834 pt\`,
+          \`320 pixels\`, \`320 wide\`) or sits in a screenshot filename (\`home-320.png\`,
+          \`home-390x844.png\`). Nothing is read from the words around the number, so a BARE
+          figure never counts however you label it \u2014 \`Widths: 320, 390, 834\` and
+          \`compact (320) and expanded (834)\` both name no width. One unit per number fixes it.
+
+     Full contract: \`himi docs mobile-ux\` -> "Strict audit contract". -->`;
     MOBILE_UX_TEMPLATE = `# Mobile UX
 
+${MOBILE_UX_MARKER_NOTE}
+
 ## Flows
 ### <Task>
 1. Entry:
@@ -982,6 +1108,9 @@ in preview fixtures or labelled, capability-limited fallback states\u2014not ord
 > Keep this document safe to publish with a release: do not include credentials, personal data,
 > internal URLs, private research, or unreviewed notes. Read \`himi docs mobile-ux\` before filling it in.
 `;
+    section = mobileUxSection;
+    DELIMITER_ROW = /^\|?\s*:?-+:?\s*(?:\|\s*:?-+:?\s*)+\|?$/;
+    splitCells = (line) => line.replace(/^\|/, "").replace(/\|\s*$/, "").split("|").map((cell) => cell.trim());
     WIDTH_LITERAL = /compact \(320\/360\)[\s\S]{0,400}?expanded/i;
     COMPACT_MAX = 599;
     WIDER_MIN = 600;
@@ -4729,7 +4858,6 @@ function resolveTranslation(value, catalog, 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((s) => s !== "t").join("|")})\\b|^\\$t:`
@@ -6606,7 +6734,7 @@ function validateWorkerAction(action, context) {
     }
   }
   if (context.actionCatalogWithheld) {
-    return actionIssue(action, "warning", `worker actionId "${action.actionId}" was not cross-checked: this surface has precomputed service state but no precomputed action catalog`);
+    return actionIssue(action, "warning", `worker actionId "${action.actionId}" was not cross-checked: this surface has precomputed service state but no precomputed action catalog. This is a property of the surface doing the checking, not of your app \u2014 there is nothing to fix in the content package; re-run the check where the bundle can be inspected (\`himi validate\` / \`himi test\` locally) to have it cross-checked`);
   }
   const reason = context.bundleInspectionError ? `the bound bundle could not be inspected: ${context.bundleInspectionError}` : "no inspectable logic bundle is bound";
   return actionIssue(action, "error", `worker actionId "${action.actionId}" cannot resolve because ${reason}`);
@@ -26475,7 +26603,6 @@ 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]+$/;
@@ -29898,7 +30025,6 @@ 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,
@@ -46300,9 +46426,9 @@ function ipv6Private(address) {
   const value = address.toLowerCase().replace(/^\[|\]$/g, "");
   const sections = value.split("::");
   if (sections.length > 2) return true;
-  const parse = (section) => {
-    if (!section) return [];
-    const parts = section.split(":");
+  const parse = (section2) => {
+    if (!section2) return [];
+    const parts = section2.split(":");
     const last = parts.at(-1) ?? "";
     if (!last.includes(".")) return parts.map((part) => Number.parseInt(part, 16));
     parts.pop();
@@ -47927,6 +48053,7 @@ __export(native_decode_exports, {
   nativeDecodeAndroidHarnessDir: () => nativeDecodeAndroidHarnessDir,
   nativeDecodePackageDir: () => nativeDecodePackageDir,
   nativeDecodePlatforms: () => nativeDecodePlatforms,
+  nativeOracleShipped: () => nativeOracleShipped,
   parseNativeDecodeOutput: () => parseNativeDecodeOutput,
   runAndroidNativeDecode: () => runAndroidNativeDecode,
   runNativeDecode: () => runNativeDecode
@@ -47942,6 +48069,12 @@ function nativeDecodePackageDir() {
 function nativeDecodeAndroidHarnessDir() {
   return fileURLToPath19(new URL("../../../tools/wix-sdk-android-tests/", import.meta.url));
 }
+function nativeOracleShipped() {
+  return {
+    ios: existsSync41(join41(nativeDecodePackageDir(), "Package.swift")),
+    android: existsSync41(join41(nativeDecodeAndroidHarnessDir(), "gradlew"))
+  };
+}
 function detectNativeDecode(options = {}) {
   const hostPlatform = options.hostPlatform ?? process.platform;
   const packageDir = options.packageDir ?? nativeDecodePackageDir();
@@ -48443,11 +48576,15 @@ __export(coverage_exports, {
   diffAndStoreObservations: () => diffAndStoreObservations,
   formatDelta: () => formatDelta,
   formatLedger: () => formatLedger,
+  suppressedNativeKeys: () => suppressedNativeKeys,
   trendAndStore: () => trendAndStore
 });
 import { existsSync as existsSync43, mkdirSync as mkdirSync21, readFileSync as readFileSync50, writeFileSync as writeFileSync18 } from "node:fs";
 import { dirname as dirname25, join as join43 } from "node:path";
-function assembleLedger(r) {
+function suppressedNativeKeys(oracle) {
+  return [...oracle.ios ? [] : ["native-decode|ios"], ...oracle.android ? [] : ["native-decode|android"]];
+}
+function assembleLedger(r, options = {}) {
   const out = [];
   for (const c of r.crawled ?? []) {
     const noRow = (c.actionsSkipped ?? []).filter((s) => s.why === "no-row-value");
@@ -48569,8 +48706,9 @@ function assembleLedger(r) {
       remedy: "npx playwright install chromium (~170MB, one time) \u2014 then every himi test writes a PNG per screen to .himi/shots/"
     });
   }
+  const oracle = options.nativeOracle ?? nativeOracleShipped();
   const nativeIos = r.nativeDecode?.ios;
-  if (!nativeIos || "unavailable" in nativeIos) {
+  if (oracle.ios && (!nativeIos || "unavailable" in nativeIos)) {
     const reason = nativeIos && "unavailable" in nativeIos ? ` (${nativeIos.reason})` : "";
     out.push({
       key: "native-decode|ios",
@@ -48581,7 +48719,7 @@ function assembleLedger(r) {
     });
   }
   const nativeAndroid = r.nativeDecode?.android;
-  if (!nativeAndroid || "unavailable" in nativeAndroid) {
+  if (oracle.android && (!nativeAndroid || "unavailable" in nativeAndroid)) {
     const reason = nativeAndroid && "unavailable" in nativeAndroid ? ` (${nativeAndroid.reason})` : "";
     out.push({
       key: "native-decode|android",
@@ -48611,7 +48749,7 @@ function assembleLedger(r) {
   }
   return out;
 }
-function trendAndStore(dir, entries) {
+function trendAndStore(dir, entries, suppressed) {
   const p = join43(dir, LEDGER_FILE);
   let previous = null;
   try {
@@ -48622,19 +48760,21 @@ function trendAndStore(dir, entries) {
   } catch {
   }
   const current = entries.map((e) => e.key);
+  const stored = [.../* @__PURE__ */ new Set([...current, ...(previous ?? []).filter((key2) => (suppressed ?? []).includes(key2))])];
   try {
     mkdirSync21(dirname25(p), { recursive: true });
-    writeFileSync18(p, JSON.stringify({ keys: current, ts: (/* @__PURE__ */ new Date()).toISOString() }, null, 2));
+    writeFileSync18(p, JSON.stringify({ keys: stored, ts: (/* @__PURE__ */ new Date()).toISOString() }, null, 2));
   } catch {
     return null;
   }
   if (previous === null) return { opened: 0, closed: 0 };
-  const prev = new Set(previous);
+  const baseline = previous.filter((key2) => !(suppressed ?? []).includes(key2));
+  const prev = new Set(baseline);
   const cur = new Set(current);
   return {
     opened: current.filter((k) => !prev.has(k)).length,
-    closed: previous.filter((k) => !cur.has(k)).length,
-    previousTotal: previous.length
+    closed: baseline.filter((k) => !cur.has(k)).length,
+    previousTotal: baseline.length
   };
 }
 function formatLedger(entries, trend) {
@@ -48705,6 +48845,7 @@ function formatDelta(delta) {
 var LEDGER_FILE, OBS_FILE;
 var init_coverage = __esm({
   "src/coverage.ts"() {
+    init_native_decode();
     LEDGER_FILE = join43(".himi", "test-ledger.json");
     OBS_FILE = join43(".himi", "test-observations.json");
   }
@@ -50923,7 +51064,7 @@ function scalar2(v) {
 }
 function parseStoreConfig(text2) {
   const cfg = {};
-  let section = null;
+  let section2 = null;
   for (const raw of text2.split("\n")) {
     const line = strip2(raw);
     if (!line.trim()) continue;
@@ -50933,14 +51074,14 @@ function parseStoreConfig(text2) {
     const [, key2, rest] = kv;
     if (!indented) {
       if (rest.trim() === "") {
-        section = {};
-        cfg[key2] = section;
+        section2 = {};
+        cfg[key2] = section2;
       } else {
-        section = null;
+        section2 = null;
         cfg[key2] = scalar2(rest);
       }
-    } else if (section) {
-      section[key2] = scalar2(rest);
+    } else if (section2) {
+      section2[key2] = scalar2(rest);
     }
   }
   return cfg;
@@ -53635,11 +53776,11 @@ function suggestKeys(args) {
       if (rule.tab && allowed2(rule) && rule.re.test(label2)) set(rule.tab, label2);
     }
   }
-  for (const section of sections) {
+  for (const section2 of sections) {
     for (const rule of KEY_RULES) {
-      if (!allowed2(rule) || !rule.re.test(section.heading)) continue;
-      set(rule.title, section.heading);
-      if (section.body) set(rule.subtitle, section.body);
+      if (!allowed2(rule) || !rule.re.test(section2.heading)) continue;
+      set(rule.title, section2.heading);
+      if (section2.body) set(rule.subtitle, section2.body);
     }
   }
   if (tagline) set("home.onboardingBody", tagline.text);
@@ -53672,12 +53813,12 @@ function buildCopyChapter(args) {
         pageUrl: page.url
       }))
     );
-    for (const section of candidates) {
+    for (const section2 of candidates) {
       if (faq.length >= CAP.faq) break;
-      if (!section.heading || !section.body || !/\?\s*$/.test(section.heading)) continue;
-      if (about && section.body === about) continue;
-      if (faq.some((f) => f.q.toLowerCase() === section.heading.toLowerCase())) continue;
-      faq.push({ q: section.heading, a: section.body, pageUrl: section.pageUrl });
+      if (!section2.heading || !section2.body || !/\?\s*$/.test(section2.heading)) continue;
+      if (about && section2.body === about) continue;
+      if (faq.some((f) => f.q.toLowerCase() === section2.heading.toLowerCase())) continue;
+      faq.push({ q: section2.heading, a: section2.body, pageUrl: section2.pageUrl });
     }
   }
   const testimonials = dedupe2(pages.flatMap((p) => p.testimonials ?? []), CAP.testimonials);
@@ -60627,7 +60768,7 @@ function parseEvidence(path) {
   }
 }
 function blankMatrixRows(text2) {
-  const acceptance = text2.match(/## Implementation acceptance\s*([\s\S]*?)(?=\n##\s|$)/i)?.[1] ?? "";
+  const acceptance = mobileUxSection(mobileUxDocumentBody(text2), "Implementation acceptance") ?? "";
   return /\|\s*(?:Ready|Empty|Add\s*\/\s*edit|Saved\s*\/\s*completed|Error\s*\/\s*recovery)\s*\|\s*\|\s*\|\s*\|\s*\|/i.test(acceptance);
 }
 function usesAppNetwork(source) {
@@ -61377,7 +61518,7 @@ var COMMANDS = [
   { name: "functions", summary: "inspect/invoke server functions and operate durable jobs or schedules", required: "list|describe|openapi|invoke | jobs list|get|cancel|retry|dlq | schedule describe|invoke [--app <a>] [--environment preview|production] [--release <id>]" },
   { name: "eject", summary: "take ownership of a shared flow module (auth|checkout|screens): copies its source into tier5-src/_ejected/ and repoints this package's imports at the copy. The ladder's escape hatch \u2014 for when the factory options cannot express what you need. AFTER EJECTING, CENTRAL FIXES NO LONGER REACH THIS APP, including future corrections to the fail-closed entitlement and confirm-the-session rules. The floor is unaffected: credentials still go only through the native auth actions and money only through the cashier rail.", required: "<auth|checkout|screens> [--content <dir>]" },
   { name: "validate", summary: "lint the content package (no push): fixed-contract TypeScript checking for tier5-src workers + schema/proto + token refs + component allowlist + $service bindings + strict-enum foot-guns + capability decls + worker boot dry-run + build/compile failures. Type issues are advisory warnings normally; --strict promotes them and hygiene warnings to errors. Exit 1 on any error. Off-repo, the CLI supplies its compiler and SDK declarations.", required: "[--content <dir>] [--strict]" },
-  { name: "test", summary: "DERIVED behavioral crawl \u2014 no test files to write. Boots each screen's real worker, replays its onAppear, then dispatches every action site the descriptor already declares (each from a fresh boot) and checks a narrow set of unambiguous invariants: no uncaught throw, never stuck on `loading`, no `$service:` token or NaN/undefined/[object Object] reaching visible text, no binding aimed at state the worker never defines, no nav param silently dropped, no dead nav target. Catches what validate/render cannot \u2014 a WRONG REDUCER passes both with ok:true. Runs the worker in a DEVICE-PARITY sandbox (no setTimeout/setInterval, as on JSC/WebView) so a bundle that would die on device fails here. Crawls on HERMETIC DATA by default \u2014 zero network: the app's own dev/net-mocks.json first (--net <file> overrides), then the config's CMS `seed:` rows, then a canned fixture of frozen real vertical responses shipped with the CLI (exercises code paths, not API-contract truth) \u2014 so the success/mapping path runs, not just the failure UI. Two boot-only HOSTILE passes (every list empty; every request 500) then check the failure/empty day \u2014 corpus-proven, so their findings are errors. NAV EDGES are followed too: every himi.open site ($item params resolved against row 0 of its list, $service against worker state) and worker _nav directive is harvested, and each baked target is booted WITH the params the source sends \u2014 detail screens finally run their content arm; edge findings are errors tagged edge:<source>. --native runs both real native decoders over the exact baked JSON bytes; --native ios or --native android selects one. It is explicit and needs the selected local toolchain. Default runs name missing native verdicts in the coverage ledger. --offline strips all data layers (the old reject-all axis); --no-hostile skips the hostile passes. --record (EXPLICIT, never automatic) refreshes dev/net-mocks.json from live reads first: it boots each screen (load + root onAppear ONLY \u2014 nothing the app's own launch would not fire; the tap/action crawl never sees the live transport, and only proven reads \u2014 GET, or read-shaped POST (/query, /search, /list*, \u2026) \u2014 ever reach the wire), freezes the round-trips, then crawls hermetically on the fresh fixture; record against a QA site, not production. Nodes it cannot judge headless are named, never silently passed. Exit 1 on any error. The CLI carries the authoring runtime off-repo; no per-app SDK install is required. --browser runs the whole loop (build \u2192 extract \u2192 validate \u2192 render \u2192 test) in YOUR browser instead of here, so the source never reaches a pod: it opens one screen's worker + descriptor in a tab, blocks on a loopback callback, and prints the report it posts back. One screen per tab \u2014 name it. --no-open prints the URL rather than launching a browser (SSH); --timeout <ms> bounds the wait, which matters because the page has no execution deadline of its own and an infinite loop in the worker hangs the tab.", required: "[<screenId>\u2026] [--content <dir>] [--net <file>] [--budget <ms>] [--deep [n]] [--record] [--native [ios|android]] [--no-shots] [--offline] [--no-hostile] [--all-screens] [--browser] [--no-open] [--timeout <ms>] [--json]" },
+  { name: "test", summary: "DERIVED behavioral crawl \u2014 no test files to write. Boots each screen's real worker, replays its onAppear, then dispatches every action site the descriptor already declares (each from a fresh boot) and checks a narrow set of unambiguous invariants: no uncaught throw, never stuck on `loading`, no `$service:` token or NaN/undefined/[object Object] reaching visible text, no binding aimed at state the worker never defines, no nav param silently dropped, no dead nav target. Catches what validate/render cannot \u2014 a WRONG REDUCER passes both with ok:true. Runs the worker in a DEVICE-PARITY sandbox (no setTimeout/setInterval, as on JSC/WebView) so a bundle that would die on device fails here. Crawls on HERMETIC DATA by default \u2014 zero network: the app's own dev/net-mocks.json first (--net <file> overrides), then the config's CMS `seed:` rows, then a canned fixture of frozen real vertical responses shipped with the CLI (exercises code paths, not API-contract truth) \u2014 so the success/mapping path runs, not just the failure UI. Two boot-only HOSTILE passes (every list empty; every request 500) then check the failure/empty day \u2014 corpus-proven, so their findings are errors. NAV EDGES are followed too: every himi.open site ($item params resolved against row 0 of its list, $service against worker state) and worker _nav directive is harvested, and each baked target is booted WITH the params the source sends \u2014 detail screens finally run their content arm; edge findings are errors tagged edge:<source>. --native runs both real native decoders over the exact baked JSON bytes; --native ios or --native android selects one. It is explicit, runs only from a Himalaya SOURCE CHECKOUT (the decoder oracles are that tree's own HimalayaCore Swift package and Gradle harness, which a published install does not ship), and needs the selected local toolchain. From a source checkout, default runs name missing native verdicts in the coverage ledger; elsewhere the ledger stays silent about them rather than offering a remedy you cannot run. --offline strips all data layers (the old reject-all axis); --no-hostile skips the hostile passes. --record (EXPLICIT, never automatic) refreshes dev/net-mocks.json from live reads first: it boots each screen (load + root onAppear ONLY \u2014 nothing the app's own launch would not fire; the tap/action crawl never sees the live transport, and only proven reads \u2014 GET, or read-shaped POST (/query, /search, /list*, \u2026) \u2014 ever reach the wire), freezes the round-trips, then crawls hermetically on the fresh fixture; record against a QA site, not production. Nodes it cannot judge headless are named, never silently passed. Exit 1 on any error. The CLI carries the authoring runtime off-repo; no per-app SDK install is required. --browser runs the whole loop (build \u2192 extract \u2192 validate \u2192 render \u2192 test) in YOUR browser instead of here, so the source never reaches a pod: it opens one screen's worker + descriptor in a tab, blocks on a loopback callback, and prints the report it posts back. One screen per tab \u2014 name it. --no-open prints the URL rather than launching a browser (SSH); --timeout <ms> bounds the wait, which matters because the page has no execution deadline of its own and an infinite loop in the worker hangs the tab.", required: "[<screenId>\u2026] [--content <dir>] [--net <file>] [--budget <ms>] [--deep [n]] [--record] [--native [ios|android]] [--no-shots] [--offline] [--no-hostile] [--all-screens] [--browser] [--no-open] [--timeout <ms>] [--json]" },
   { name: "ux", summary: "audit or record mobile UX evidence. `audit` checks the public-safe contract, seeded blank acceptance rows, placeholder source copy, app-specific mocks, and iOS/Android audit records. It warns while existing templates migrate; `--strict` promotes missing evidence. `record` stores checks performed on an installed iOS/Android build: `--checks` is required for passed|failed and empty for unavailable, which drove nothing and needs a `--reason` instead.", required: "audit [--content <dir>] [--strict] [--json] | record --content <dir> --platform ios|android --status passed|failed|unavailable [--checks back,keyboard,...] [--reason <text>]" },
   { name: "render", summary: "headless-render a screen with the web renderer: render-tree + diagnostics, optional --png <file>, --scheme dark, --tree. Local by default (content dir). Pass --remote --app --release to hit GET /v1/preview/\u2026/render on the serve plane after a push. Boots the worker so $service bindings resolve; --static raw bindings; --live real Wix fetches; --state injects worker state; --input supplies pre-boot navigation params; --width/--device for PNG viewport; --rtl for dir=rtl + $env:isRTL.", required: "<screenId> [--content <dir>] [--scheme dark] [--png <file>] [--tree] [--static] [--live] [--state <json|file>] [--input <json|file>] [--width <px> | --device <name>] [--rtl] [--remote --app --release]" },
   { name: "cms", summary: "inspect, provision, and seed the app's CMS (Wix Data) collections, declared as a `cms` block in config.ts. `query` is READ-ONLY \u2014 by default it fetches ONLY the physical ids `config.ts` declares (item counts + schema drift) and reports `siteScanned: false`; it never lists the site, so an UNDECLARED `himi_<app>_` collection this app owns is not reached without `--all`. `--all` SCANS the site \u2014 every collection it lists is labeled `owned`/`adopted`/`foreign`, and it describes every foreign one \u2014 id, non-system field keys + types, and the site's read role \u2014 so an app with no `cms` block at all can DISCOVER a collection to adopt (`--all` is the one case where a missing `cms` block is not 'nothing to do'). Foreign collections are described up to a cap and are never item-counted (`itemCount: null`), because a row count is one query each; `foreign.count` is how many the scan LISTED \u2014 NOT a site census, since the list endpoint is paged and is not followed \u2014 and `foreign.truncated` says how many of those went undescribed, while `unlistedCollections` reports what the listing itself left out (from Wix's own paging total). The scan is OWNER-scoped \u2014 it needs --site <msid> (or WIX_SITE_ID) plus owner auth via `wix token`; a visitor token can read a public collection's ITEMS but can never enumerate collections, so there is no tokenless discovery path. `create` reconciles declared collections additively and idempotently, and REFUSES any id outside the app's `himi_<app>_` namespace, so it is safe against a production site. It reports declared-vs-site `permissionDrift` but never writes permissions unless asked with --apply-permissions, so a field reconcile can't silently revert access control changed in the dashboard. `seed` inserts the git-tracked `seed:` rows into EMPTY owned collections (--force to add to a non-empty one; --ai writes placeholder rows plus a refinement prompt for you to review). Adopted collections (declared by `wixId`) are read-only and never created, updated, or seeded. Site from --site <msid> or WIX_SITE_ID; owner auth via `wix token`.", required: "query|create|seed [--site <msid>] [--content <dir>] [--all] [--dry-run] [--force] [--allow-destructive] [--apply-permissions] [--only <id>] [--ai] [--count <n>]" },
@@ -61557,6 +61698,40 @@ function previewLogsUrl(serveBase, app, release) {
 function previewTelemetryUrl(serveBase, app, release) {
   return `${serveBase.replace(/\/$/, "")}/v1/telemetry/events?app=${encodeURIComponent(app)}&release=${encodeURIComponent(release)}`;
 }
+function diagnoseBody(body) {
+  const findings = body.findings;
+  if (!Array.isArray(findings)) return body;
+  const messageOf2 = (entry) => {
+    const message = entry && typeof entry === "object" ? entry.message : void 0;
+    return typeof message === "string" ? message : void 0;
+  };
+  const shown2 = new Set(findings.map(messageOf2).filter((message) => message !== void 0));
+  const folded = (value) => Array.isArray(value) && value.length > 0 && value.every((entry) => {
+    const message = messageOf2(entry);
+    return message !== void 0 && shown2.has(message);
+  });
+  const out = {};
+  const emptied = [];
+  for (const [key2, value] of Object.entries(body)) {
+    const fold = (key2 === "issues" || key2 === "failures" || key2 === "warnings") && folded(value);
+    if (fold) emptied.push(key2);
+    out[key2] = fold ? [] : value;
+  }
+  if (emptied.length) out.foldedIntoFindings = emptied;
+  return out;
+}
+var PREVIEW_TOKEN_NOTE = "the preview link carries a bearer with a limited lifetime, and this call has no usable expiry for it \u2014 the plane stated none, or the one it stated is unreadable, already past, or beyond the hour this CLI will reason about. Run the `previewRenew` command printed beside this note \u2014 from the same plane and credentials as this call (any `--serve-url`/`--control-url`/token flags you passed) \u2014 for a fresh one.";
+function previewTokenNote(expiresAt, now = Date.now()) {
+  const at = expiresAt ? Date.parse(expiresAt) : NaN;
+  if (!Number.isFinite(at)) return PREVIEW_TOKEN_NOTE;
+  const seconds = (at - now) / 1e3;
+  if (seconds <= 0 || seconds > 3600) return PREVIEW_TOKEN_NOTE;
+  const minutes = Math.max(1, Math.round(seconds / 60));
+  return `the preview link carries a bearer that expires at ${expiresAt} \u2014 about ${minutes} minute${minutes === 1 ? "" : "s"} from now; run the \`previewRenew\` command printed beside this note \u2014 from the same plane and credentials as this call (any \`--serve-url\`/\`--control-url\`/token flags you passed) \u2014 for a fresh one.`;
+}
+function previewRenewCommand(app, release, target, scope = {}) {
+  return `himi preview --app ${app} --release ${release}` + (scope.screen ? ` --screen ${scope.screen}` : "") + (scope.surface ? ` --surface ${scope.surface}` : "") + (target !== "local" ? ` --target ${target}` : "");
+}
 function previewPlayerLink(app, release, screenId) {
   return buildPlayerPreviewUrl({ app, releaseId: release, screenId, source: "cli" });
 }
@@ -63214,9 +63389,11 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
             result.shots = { ...sp.written.length ? { dir: sp.dir } : {}, written: sp.written.length, ...sp.unavailable ? { unavailable: true } : {} };
           }
         }
-        const { assembleLedger: assembleLedger2, trendAndStore: trendAndStore2, formatLedger: formatLedger2, diffAndStoreObservations: diffAndStoreObservations2, formatDelta: formatDelta2 } = await Promise.resolve().then(() => (init_coverage(), coverage_exports));
-        const ledger = assembleLedger2(result);
-        const trend = trendAndStore2(dir, ledger);
+        const { assembleLedger: assembleLedger2, trendAndStore: trendAndStore2, formatLedger: formatLedger2, diffAndStoreObservations: diffAndStoreObservations2, formatDelta: formatDelta2, suppressedNativeKeys: suppressedNativeKeys2 } = await Promise.resolve().then(() => (init_coverage(), coverage_exports));
+        const { nativeOracleShipped: nativeOracleShipped2 } = await Promise.resolve().then(() => (init_native_decode(), native_decode_exports));
+        const nativeOracle = nativeOracleShipped2();
+        const ledger = assembleLedger2(result, { nativeOracle });
+        const trend = trendAndStore2(dir, ledger, suppressedNativeKeys2(nativeOracle));
         const delta = diffAndStoreObservations2(dir, result.observations ?? {});
         const legacy = { ...result, ledger, ...trend ? { trend } : {}, ...delta ? { delta } : {}, ...recorded ? { recorded } : {} };
         const release = await loadReleaseFromDir(app, out);
@@ -64048,7 +64225,16 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           ...loopbackWarning ? { warning: loopbackWarning } : {},
           ...report.issues ? { issues: report.issues } : {},
           previewWeb: base ? previewWebUrl(base, app, release, void 0, void 0, previewToken) : null,
-          ...previewToken ? { previewTokenExpiresAt: previewTokenExpiresAt ?? null } : {},
+          // A timestamp alone leaves the reader to work out both how long they have and how to
+          // get another one. Print the duration and the re-mint command beside it (#2502 item 3).
+          // No `mintedHere` guard is needed here, unlike `himi preview`: this bearer can only
+          // have come from the publish response two hundred lines up, so THIS call minted it by
+          // construction. `push` has no `--preview-token` to paste one in with.
+          ...previewToken ? {
+            previewTokenExpiresAt: previewTokenExpiresAt ?? null,
+            previewRenew: previewRenewCommand(app, release, targetName()),
+            previewTokenNote: previewTokenNote(previewTokenExpiresAt)
+          } : {},
           // RFC 0051 — the surfaces THIS RELEASE targets, read from the manifest the
           // push just published (never a re-read of the local file: review found the
           // two can disagree — e.g. an older CLI whose local parser drops a key the
@@ -64509,6 +64695,8 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
         }
         let previewToken = str5(flags["preview-token"]);
         let previewTokenExpiresAt;
+        let mintedHere = false;
+        let mintFailure;
         if (!previewToken) {
           const target = resolveTarget({
             target: str5(flags.target),
@@ -64521,15 +64709,24 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
             telemetryToken: str5(flags["telemetry-token"]),
             controlToken: str5(flags["control-token"])
           });
-          if (target.controlToken) {
+          if (!target.controlToken) {
+            mintFailure = `this target has no stored control credential, so none was requested \u2014 run \`himi login --target ${targetName()}\`, or pass --control-token`;
+          } else {
             try {
               const minted = await new ServeCliClient(target).previewToken(app, release);
-              if (minted.ok && minted.json && typeof minted.json === "object") {
+              if (!minted.ok) {
+                mintFailure = `the plane refused the mint request (HTTP ${minted.status}). Your credential reached it, so this is the plane's answer, not your session`;
+              } else if (!minted.json || typeof minted.json !== "object") {
+                mintFailure = "the plane accepted the mint request but its answer was not a JSON object, so no token could be read. Your credential is fine";
+              } else {
                 const body = minted.json;
                 previewToken = typeof body.previewToken === "string" ? body.previewToken : void 0;
                 previewTokenExpiresAt = typeof body.previewTokenExpiresAt === "string" ? body.previewTokenExpiresAt : void 0;
+                mintedHere = previewToken !== void 0;
+                if (!mintedHere) mintFailure = "the plane answered the mint request without a token \u2014 HIMALAYA_PREVIEW_TOKEN_SECRET may be unconfigured there. Your credential is fine";
               }
-            } catch {
+            } catch (e) {
+              mintFailure = `the mint request could not be sent: ${e.message}. Your credential was never judged`;
             }
           }
         }
@@ -64540,7 +64737,22 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           ...screen ? { screen } : {},
           ...surface ? { surface } : {},
           previewWeb: base ? previewWebUrl(base, app, release, screen, surface, previewToken) : null,
-          ...previewTokenExpiresAt ? { previewTokenExpiresAt } : {},
+          // Gated on the MINT, like the two fields below: a plane that returns an expiry but no
+          // token would otherwise print a lifetime for a bearer the same envelope says does not
+          // exist.
+          ...mintedHere && previewTokenExpiresAt ? { previewTokenExpiresAt } : {},
+          // Same as the push envelope: the expiry alone leaves the reader to work out both how
+          // long they have and how to get another link. `himi preview` re-mints, so the renew is
+          // this very command — say so rather than making them find it again (#2502 item 3).
+          //
+          // Gated on the MINT, not on the expiry: a plane that mints a bearer but returns no
+          // `previewTokenExpiresAt` would otherwise withhold the guidance in exactly the case
+          // where the reader has no timestamp to reason from — while a bearer the caller pasted
+          // in with `--preview-token` is one this command cannot promise to reissue.
+          ...mintedHere ? {
+            previewRenew: previewRenewCommand(app, release, targetName(), { screen, surface }),
+            previewTokenNote: previewTokenNote(previewTokenExpiresAt)
+          } : previewToken || !mintFailure ? {} : { previewTokenNote: `no preview bearer was minted \u2014 ${mintFailure}. The link above carries no \`pvt\`, so it opens a LIVE release and will not open a draft.` },
           previewPlayerDebug: previewPlayerDebugLink(app, release, screen, previewToken),
           context: base ? previewContextUrl(base, app, release, screen) : null,
           diagnose: base && screen ? previewDiagnoseUrl(base, app, release, screen) : null,
@@ -64718,8 +64930,16 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
             if (!r.ok) throw Object.assign(new Error("crashes_read_failed"), { response: r });
             out.crashes = r.json?.crashes ?? [];
           }
-          if ((out.events?.length ?? 0) === 0 && (out.logs?.length ?? 0) === 0 && !includeSummary && !includeCrashes) {
-            out.note = "no telemetry yet \u2014 open the web preview or Himi Player link for this release, then retry or use --follow";
+          const eventCount = out.events?.length ?? 0;
+          const logCount = out.logs?.length ?? 0;
+          const narrowed = !!(level || str5(flags.screen) || str5(flags.screenId) || str5(flags.type) || str5(flags.event) || flags["crashes-only"] === true || flags.crashesOnly === true || num(flags.limit) !== void 0 || eventSince !== void 0 || logSince !== void 0);
+          const wholeChannels = includeEvents && includeLogs && !narrowed;
+          if (wholeChannels && eventCount === 0 && logCount === 0 && !includeSummary && !includeCrashes) {
+            out.note = "no events and no worker console output on this release \u2014 open the web preview or Himi Player link for it, then retry or use --follow";
+          } else if (wholeChannels && eventCount > 0 && logCount === 0) {
+            out.note = "events arrived but the worker console channel is empty \u2014 commonly because the worker never called `console.*`, though an empty channel can also mean the lines aged out or never made it through ingestion. What the CLI can say is that this channel returned nothing, not that the app was never opened";
+          } else if (narrowed && eventCount === 0 && logCount === 0 && !includeSummary && !includeCrashes) {
+            out.note = "nothing matched this query. Drop --screen/--type/--level/--since/--limit/--crashes-only to see the whole event and console channels for this release";
           }
           return out;
         };
@@ -64800,7 +65020,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           if (r.status !== 422) return printServeFailure(r);
         }
         const body = r.json ?? {};
-        print(body);
+        print(diagnoseBody(body));
         return body.ok === false ? 1 : 0;
       }
       case "deeplinks": {
@@ -64856,8 +65076,12 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
             print({ ok: false, status: r.status, body: r.json ?? r.text });
             return 1;
           }
-          const logs = byLevel(r.json?.logs ?? []);
-          print({ ok: true, logs, ...logs.length === 0 ? { note: "no logs yet \u2014 a worker emits telemetry only once someone opens the app/preview on a device or web with a session. Boot-time console.log is visible via `himi validate` / `himi render`." } : {} });
+          const rawLogs = r.json?.logs ?? [];
+          const logs = byLevel(rawLogs);
+          const narrowed = !!(level || str5(flags.screen) || str5(flags.screenId) || num2(flags.since) !== void 0 || num2(flags.limit) !== void 0);
+          const scope = release ? "this release" : "this app";
+          const note = logs.length > 0 ? void 0 : narrowed ? `no worker \`console.*\` lines matched this query${level && rawLogs.length ? ` (${rawLogs.length} line(s) were hidden by --level ${level})` : ""}. Drop --level/--screen/--since/--limit to see the whole console channel for ${scope}; the telemetry EVENT stream is a separate channel, read with \`himi telemetry\`.` : `no worker \`console.*\` output on ${scope}. This is the console channel \u2014 distinct from the telemetry EVENT stream, which \`himi telemetry --app <app> --release <id>\` reads: ${scope} can carry many events and no console lines \u2014 commonly because the worker never logged any, though an empty channel can also mean the lines aged out or never made it through ingestion. Boot-time \`console.log\` is visible via \`himi validate\` / \`himi render\`.`;
+          print({ ok: true, logs, ...note ? { note } : {} });
           return 0;
         }
         const interval = num2(flags.interval) ?? 2e3;
@@ -66139,12 +66363,14 @@ export {
   ConfigLoadError,
   PLACEHOLDER_CLIENT_ID,
   PLACEHOLDER_SITE_URL,
+  PREVIEW_TOKEN_NOTE,
   PUBLIC_WIX_API_BASE,
   autoClaimSlug,
   buildDoctorReport,
   compareVersions2 as compareVersions,
   decodeControlTokenClaims,
   defaultTargetForCommand,
+  diagnoseBody,
   doctorVersionReport,
   foreignPlaneError,
   formatSdkVersionLine,
@@ -66167,8 +66393,10 @@ export {
   previewPlayerDebugLink,
   previewPlayerLink,
   previewRenderUrl,
+  previewRenewCommand,
   previewScreensUrl,
   previewTelemetryUrl,
+  previewTokenNote,
   previewWebUrl,
   probeControlToken,
   probeReachable,

package/guides/himi-test.md

@@ -236,7 +236,7 @@ browser.
 | `--no-shots` | Skip the per-screen PNGs written to `.himi/shots/`. |
 | `--net <file>` | Use an explicit net-mocks file instead of the app's own. |
 | `--budget <ms>` | Per-action settle budget (default 2000). |
-| `--native` | Also decode every baked descriptor with the real native decoders; bare `--native` runs whichever toolchains are present, and `--native ios` or `--native android` selects one. |
+| `--native` | Also decode every baked descriptor with the real native decoders; bare `--native` runs whichever toolchains are present, and `--native ios` or `--native android` selects one. **Source-checkout only** — the decoder oracles are that tree's own HimalayaCore Swift package and Gradle harness, which a published install does not ship, so it cannot run this at all (and its coverage ledger stays silent about native decoding rather than suggesting it). |
 | `--all-screens` | Crawl every templated instance instead of one representative per structure. |
 | `--browser` / `--no-open` / `--timeout <ms>` | Run the loop in your own browser tab (one screen per run; refuses record/net/offline/hostile/deep/budget/shots/native). |
 | `himi test <screenId>…` | Focus one or more screens — the record and shots passes scope with them. |

package/guides/mobile-ux.md

@@ -137,18 +137,32 @@ nothing, so it takes no checks and needs a `--reason` instead.
 
 ### Strict audit contract
 
-**Two commands read these markers.** `himi validate` reports a missing one as a **warning**, so a
-rewrite that drops a required string is caught in the loop you are already running rather than at
+**Two commands read this contract.** `himi validate` reports a gap as a **warning**, so a rewrite
+that drops something the gate needs is caught in the loop you are already running rather than at
 the end of it. `himi validate --strict` and `himi ux audit --strict` both promote that warning to a
-**release blocker**. Both read the same exact markers, and each gate **substring-matches** these
-three phrases — so use them verbatim: a semantically equivalent rewrite ("each state exposes exactly
-one primary call to action") fails the same as omitting them:
+**release blocker**. Both read the same markers. The two HEADINGS are matched verbatim — other
+tooling addresses the document by them, so a heading really is the thing itself:
 
 - The heading `## Implementation acceptance`.
 - The heading `## Evidence`.
-- The phrase `one primary CTA per state`.
 
-The fourth marker, **width evidence**, is graded by **content, not by phrase** — it is a
+The **primary-CTA** marker is satisfied **either** structurally *or* by the legacy phrase,
+because a semantically equivalent rewrite — "each state exposes exactly one primary call to
+action" — used to fail exactly like omitting it, and four of five independent testers wrote a
+better document, were refused, and pasted the sentence back:
+
+- *structurally*: `## Implementation acceptance` carries a `Primary CTA` column, has a row for
+  every state you declare in a `… states:` bullet under `## Screen contract`, and names exactly one
+  CTA per row (a comma, a semicolon or a spaced slash reads as two; "Save and close", "Save &
+  Close" and "Save + Continue" are each one label and pass). The row check reads a `states:` bullet
+  only when every item is a **name** (`ready, empty, destructive-confirm`); a bullet answered with
+  prose declares nothing and the row check is skipped rather than guessed at — no rule can tell a
+  short description from a name, and inventing states from prose would fail exactly the documents
+  that took the most care.
+- *or literally*: the phrase `one primary CTA per state` appears anywhere. It is not deprecated —
+  a document that passes today keeps passing.
+
+The remaining marker, **width evidence**, is graded by **content, not by phrase** — it is a
 fact about what you rendered rather than a string, so there is nothing to paste. Satisfy it either
 way:
 
@@ -202,6 +216,13 @@ no wider width, two widths too far apart to be one statement, or no number spell
 says so alongside the height-axis rule if that is what discarded your numbers. Read the branch it
 gave you rather than pasting the example: the example is a form that works, not the only one.
 
+**HTML comments are stripped before any of this runs.** The scaffold ships a `<!-- LOAD-BEARING -->`
+note quoting the load-bearing strings verbatim, right beside the line telling you to replace the
+example rows — so the note is guidance and never an answer: a document that kept the note and
+deleted the prose satisfies nothing. An **unterminated** `<!--` swallows the rest of the file here
+and in any renderer alike, so that is reported on its own rather than as four headings "missing"
+that you can plainly see.
+
 A `MOBILE-UX.md` that is **absent or empty** is not four missing markers. `himi ux audit` reports it
 once, as a missing contract; `himi validate` stays silent about it entirely. Asking for the document
 itself is the audit's job — most apps never adopt this contract, and a warning on every one of them

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

@@ -326,6 +326,10 @@ himi test <screenId> --record    # refresh dev/net-mocks.json from live boot rea
 himi test <screenId> --native    # run BOTH real native decoders over the baked JSON bytes
 ```
 
+`--native` runs only from a Himalaya **source checkout**: the decoder oracles are that tree's own HimalayaCore Swift
+package and Gradle harness, which a published/off-repo install does not ship. Working off-repo,
+skip it — the coverage ledger will not ask you for it either.
+
 **Then see it.** `himi render <screenId> --png <file>` per scheme is the fast visual check,
 and `himi push` gives you a draft preview to open in a browser. Neither drives a real
 device, which is what `himi ux record` is for: it records per platform that a drive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.855.0",
+  "version": "0.856.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": "40bff5342044d54ba5f7a74cc5a432f6a7367a0228eb885fec4a3e2c"
+  "falconPackageHash": "82a824b69c0914106e80e0fb205b046bd8e669b53f46887b3adf0eed"
 }