@wix/himalaya-cli 0.855.0 → 0.857.0

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

@@ -135,25 +135,62 @@ driving a native shell, record the result—not an assumption—with `himi ux re
 is required for `passed`/`failed` and names what you actually drove; an unavailable platform drove
 nothing, so it takes no checks and needs a `--reason` instead.
 
+`himi render --width`/`--device` writes into the same `.himi/ux-audit.json`, appending the width it
+rendered. That is what the width marker below reads first, so rendering the screen at two widths is
+itself the evidence — see the strict audit contract.
+
 ### 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
-fact about what you rendered rather than a string, so there is nothing to paste. Satisfy it either
-way:
 
-- Name two pixel widths spanning compact → wider, **each spelled as a width on itself**, within
-  about 400 characters of each other so they read as one statement: one **below 600px** (compact)
+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 **what you rendered, not by a phrase** — it
+is a fact rather than a string, so there is nothing to paste. Three things satisfy it, and they are
+tried in this order:
+
+- **A recorded render — the primary path, and the one to prefer.** `himi render <screenId>
+  --content <app> --width 390`, then the same screen again at `--width 834` (or `--device iphone`
+  and `--device ipad`), appends the width each run actually rendered to `.himi/ux-audit.json` —
+  the same structured evidence file `himi ux record` writes. A recorded render **below 600px**
+  plus one **at 600px or wider** satisfies this marker on its own: the document need not name a
+  width anywhere. The gate is then reading a fact the tool produced instead of a sentence you
+  typed, which is the whole point of the marker.
+
+  Each entry carries the screen, the width, the `--device` preset when you used one, and the PNG
+  when `--png` wrote one. Re-rendering the same screen at the same width **replaces** that entry
+  rather than appending another, so a long dev loop leaves one line per screen and width, and a
+  native audit already recorded in the same file is never disturbed. A render with **no**
+  `--width`/`--device` records nothing on purpose: without one the PNG viewport is the headless
+  browser's desktop default, and writing that down would manufacture the very expanded render the
+  marker exists to prove. Recording never fails or slows a render — if the file cannot be written
+  the render still succeeds, and the paths below still apply. `.himi/` is gitignored, so this is
+  evidence about your checkout rather than something a pull request carries.
+
+- Or name two pixel widths in the document, spanning compact → wider,
+  **each spelled as a width on itself**, within about 400 characters of each other so they read as
+  one statement: one **below 600px** (compact)
   and one **at 600px or wider** (medium or expanded). A number is spelled as a width when it
   carries a **unit** — `320px`, `320 px`, `320pt`, `320dp`, `320 pixels`, `320 wide` — or sits in a
   **screenshot filename** — `home-320.png`, `home-834-dark.png`, `home-390x844.png`. That is the
@@ -197,11 +234,26 @@ way:
   `expanded` must follow within about 400 characters, so keep them in the same sentence or bullet
   rather than in separate sections.
 
+The two written paths are a **fallback, not a deprecation**: plenty of real renders are not driven
+by `himi render` at all — a simulator, a real phone, or an automated UI driver leaves no entry in
+`.himi/ux-audit.json` — so a document that satisfies this marker today still satisfies it. A render
+record can only **add** a way to pass; it never takes one away, and a record showing fewer size
+classes than your document claims is not itself a finding.
+
 When the marker fails, the error names **which** of the four things went wrong — no compact width,
 no wider width, two widths too far apart to be one statement, or no number spelled as a width — and
-says so alongside the height-axis rule if that is what discarded your numbers. Read the branch it
+says so alongside the height-axis rule if that is what discarded your numbers. When the render
+record holds something, it also names what it holds and the single command that would complete it
+("holds 390px — compact only. Render the same screen again at 600px or wider"). 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.857.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": "629ade3aa68530bbdcfe1842b24b52fcb778d8e8f85ff394bc3372fb"
 }