@wix/himalaya-cli 0.1448.0 → 0.1449.0

package/guides/designing-himi-screens.md

@@ -235,12 +235,12 @@ validation, which is what it used to cost.
 for the standard case; `Fab` for a single floating primary action on a scroll; `Menu` for a set of
 secondary actions behind one affordance. *One `primary` button per screen.* An **`iconOnly` button still
 needs a `title`** (`Button.title` is non-optional in the native schema — it doubles as the a11y label).
-> **Strict whole-screen decode — supply every required prop.** The native renderer decodes a screen's
-> descriptor with strict `Codable`: a single missing non-optional field (e.g. a titleless `Button`)
-> makes the **whole screen** fail to decode and fall back to the app's generic *"Couldn't load"* error
-> state — you do **not** get a partial render with one broken node. When a screen unexpectedly shows the
-> error state, suspect a missing required prop, not a network failure. (The dev-server serves it `200`;
-> the strictness is on-device.)
+> **Required fields still matter.** A single missing non-optional field (e.g. a titleless `Button`)
+> can make the **whole screen** fail to decode and fall back to the app's generic *"Couldn't load"*
+> error state. An unknown value in an optional enum field decodes to nil (the field is simply absent; only a required enum with an explicit fallback receives one), and an undecodable child
+> (for example an unknown required discriminator) is replaced by an `unknown` placeholder, so those cases do not discard the rest of the screen. When a
+> screen unexpectedly shows the error state, suspect a missing required prop, not a network failure.
+> (The dev-server serves it `200`; required-field validation is on-device.)
 
 **Navigation** — `Tabs` / `SegmentedControl` to switch peer views; `Pager` + `PageControl` for
 full-width swipe; `StepIndicator` for a wizard's progress; `CollapsingHeader` for a large-title-to-inline
@@ -315,8 +315,8 @@ build/validate/render cycles because the failure looks like a content bug rather
   "top". A wishlist heart authored as a top-right overlay therefore lands **center-right**. For a
   true corner overlay use a `ZStack` whose overlay child carries its own padding, rather than
   looking for an alignment value that does not exist. Authoring one anyway is a hard error —
-  `validate --strict` rejects an unknown enum value because the native decoders drop the whole
-  screen rather than degrading the field.
+  `validate --strict` still catches unknown enum values for authoring feedback, even though the
+  runtime decoders decode an unknown optional-field value to nil (a required discriminator degrades the child to an `unknown` placeholder) rather than discarding the whole screen.
 - **A `Text` sharing a flex row with a `Spacer` gets truncated or wrapped.** The spacer takes the
   slack the text needed. Give the text `fillMaxWidth` (or put it in its own row) instead of relying
   on the spacer to push a sibling; see the "centered separator" idiom above for the same hazard with

package/guides/himi-test.md

@@ -124,7 +124,7 @@ Only **unambiguous** defects, so a green run stays worth trusting:
 | `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) — or the release's `tokens.json`, reported with `screen: "tokens.json"`: both natives decode it in one strict pass, so a single fractional `typography.*.size` or a `motions.*.duration` written in seconds drops the whole theme. A token finding fails the run but never counts as a failed screen. |
+| `native-decode-failed` | error | Under `--native`, the real Swift/Kotlin decoder rejected the baked descriptor bytes (the oracle decodes strictly, so an unknown enum value or malformed child is reported here even though production decoding degrades it to a fallback or an `unknown` placeholder) — or the release's `tokens.json`, reported with `screen: "tokens.json"`: both natives decode it in one strict pass, so a single fractional `typography.*.size` or a `motions.*.duration` written in seconds drops the whole theme. A token finding fails the run but never counts as a failed screen. |
 | `token-type-invalid` | error | The package's tokens file holds a value a native `Int` field rejects — `typography.<k>.size` or `.weight`, `motions.<k>.duration` (milliseconds: `0.3` → `300`), or a `spacing` / `radius` entry — in the base document or any `idiom.<overlay>`. Both natives decode tokens.json in one strict pass, so one such value drops the WHOLE theme (iOS "Theme unavailable"; Android default palette and fonts) while the web preview looks right. Reported with `screen: "tokens.json"`, never counted as a failed screen; `himi validate` reports the same finding. |
 | `capability-undeclared` | error | A `capability.<id>.<verb>` call the screen's gate denied — reported from the gate itself, so it is raised **even when the worker catches the rejection** (which on device leaves a control that silently does nothing). Fix: declare the id on that screen's `logicBundle.declaredCapabilities` and in `config.ts` `capabilities`. One per capability per screen. See [Capabilities](#capabilities). |
 | `journey-failed` | error | A `himi-test.json` journey named an action the screen lacks, threw, or never rendered its `expectText`. |

package/guides/testing-himi-apps.md

@@ -317,9 +317,9 @@ findings appear as accepted-risk entries so the file stays auditable.
 
 ### What it cannot tell you
 
-This is the **web renderer's** view. It cannot see native decode strictness (one bad enum field
-blanks an entire iOS/Android screen while this tree looks healthy) or components that render
-blank on device when bound — so rather than pass those silently it names them:
+This is the **web renderer's** view. It cannot see native-only decode failures (for example, a
+missing required field can still blank an iOS/Android screen while this tree looks healthy) or
+components that render blank on device when bound — so rather than pass those silently it names them:
 
 ```
   ⚠ 2 nodes NOT verifiable headless:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1448.0",
+  "version": "0.1449.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": "ceeeb017afff0753eec531692afa7a5e7ca0bf9e38054ebdf2adf95f"
+  "falconPackageHash": "9703ffb9052d9fc0ed9a8ec8510c21e600640b5a10c12c51d336e278"
 }