@wix/himalaya-cli 0.1452.0 → 0.1454.0

package/guides/designing-himi-screens.md

@@ -337,7 +337,7 @@ to drive them:
 
 | State | Compose with | Notes |
 |---|---|---|
-| **Loading** | `Skeleton` (shape of the eventual content) or `StatefulSection` / `ActivityIndicator` | Prefer a content-shaped `Skeleton` over a bare spinner — it previews the layout. The descriptor renders against the state-skeleton, then repaints as worker state lands. |
+| **Loading** | `Skeleton` (shape of the eventual content) or `StatefulSection` / `ActivityIndicator` | Required on every screen that loads data asynchronously, and re-checked on every redesign. Prefer a content-shaped `Skeleton` over a bare spinner — it previews the layout. The descriptor renders against the state-skeleton, then repaints as worker state lands. See [Loading states](#loading-states-part-of-the-design) below. |
 | **Empty** | `EmptyState` (`title`, optional `icon` / `subtitle`) **plus a directive action** (`action` + `actionLabel`) | An empty screen is an invitation to act, not a dead end. Give it the next step, for example `"actionLabel": "Add your first item"`. Use `EmptyState` for **every** empty state, so all empty states in the app have the same layout and style. See [Empty states](#empty-states-one-component-one-layout) below. |
 | **Error** | `Banner` (or inline) **with a retry action** | Say what failed and offer recovery; never a blank screen or a raw error string. |
 | **Loaded** | the real content | The one everyone remembers to build. |
@@ -347,6 +347,38 @@ Bind visibility to worker state with `hidden_path` (`$service:…`/`$item.` data
 components precisely so states are first-class — use them. (Reproducing an existing app? Enumerate
 every state the *original* shows; the same discipline applies to net-new screens.)
 
+### Loading states: part of the design
+
+A screen that loads data asynchronously ships its loading state with it. The loading state is
+part of the screen's design, not an implementation detail to fill in later: it is the first thing
+the user sees, and on a slow network it is the whole screen.
+
+- **New screens.** Every new screen that waits for data — a worker fetch, a Wix call, a
+  `$service:` value that arrives after the first paint — has a designed loading state.
+- **Redesigns.** When you change the layout of an existing data screen, review its loading state
+  in the same change. Update it when its **structure** (sections added, removed or reordered),
+  **hierarchy** (a new hero, a different first row) or **content** (a list became a grid, a row
+  gained an image) no longer matches the redesigned screen. A loader that still shows the old
+  layout makes the screen jump when the data lands. Compare the two frames:
+  `himi render <screenId> --no-mocks` draws the initial frame, which is the loading state, and
+  `himi render <screenId> --state '{"<svc>":{…}}'` draws the loaded one. (A plain `himi render`
+  loads the app's recorded data by default when it has any, so it shows the loaded screen, not the
+  loader.)
+- **Prefer a content-shaped `Skeleton`** when you know the loaded layout: the same sections, in
+  the same order, at about the same sizes (`width`, `height`, `cornerRadius`, and `count` for
+  repeated rows). It previews the layout, so nothing moves when the data arrives.
+- **Use another existing loading component when it fits the behavior better.** `StatefulSection`
+  suits a section that loads on its own; it can skip the skeleton for a load that settles quickly
+  (`loadingGraceMs`) and holds a painted skeleton long enough not to flicker (`loadingFloorMs`).
+  `ActivityIndicator` suits a wait whose layout is not known in advance, or a short local wait
+  such as a pull-to-refresh or a button's own pending state.
+- **Loading is its own state — not empty, not error.** Do not show the empty state while the data
+  is still loading, and do not leave the skeleton up after a load has failed. Each state has its own
+  node, driven by its own worker flag (see `himi docs recipe-four-state`).
+- **Static screens have no loading state.** A screen whose content is already in the descriptor —
+  a settings list, an about page, a form with nothing to prefill — renders at once. Do not add a
+  skeleton to it.
+
 ### Empty states: one component, one layout
 
 `EmptyState` draws one standard layout on iOS, Android, macOS and web. Do not build an empty
@@ -451,6 +483,7 @@ Run this punch list on the screen (it's also a good reviewer checklist):
 
 - [ ] **One** primary action, on the one `accentPrimary` surface?
 - [ ] All four states designed — loading / empty / error / loaded (empty & error have an action)?
+- [ ] Loading state matches the loaded layout (a content-shaped `Skeleton` where the layout is known)? For a redesign, was the existing loading state reviewed against the new layout? A static screen has none?
 - [ ] Every value a token — zero literal hex / off-scale spacing / invented type sizes?
 - [ ] Is every user-facing string routed through a copy key with a sensible fallback (`copyOf(key, fallback)` backed by your own `COPY` map; worker strings via `onAppear` params) — none baked directly into the descriptor?
 - [ ] When a business book exists, do those fallbacks use the site's OWN words (`book.copy`) rather than stock phrases — and in `book.copy.language`?

package/guides/himi-json-output.md

@@ -219,6 +219,22 @@ redirects, invalid data, source changes and disk errors remain failures.
   and the original failure is preserved if writing the failure manifest also fails
   (exit 1).
 
+## `himi one-app validate-topbar` codes
+
+Failures print `ok: false` and a top-level `code` on stderr. The validator reads
+authored header choices from `settings.topBarSettings`, falls back to the legacy
+`settings.showCartIconInTopBar` / `showChatIconInTopBar` values, and treats a
+choice that is absent from both locations as false.
+
+- `invalid_usage`: required options are missing, duplicated, or malformed (exit 2).
+- `evidence_invalid`: the evidence manifest or `raw-structure.json` is missing,
+  invalid, for another workflow, lacks a valid recorded raw-structure hash, or the
+  file does not match that hash (exit 1).
+- `config_uninspectable`: the target `config.ts` cannot be read or the relevant
+  `navigation.topBarDefault.actions` cannot be inspected (exit 1).
+- `topbar_coverage_failed`: an authored cart/chat control has no matching action
+  with a non-empty `onTap.actionId` (exit 1).
+
 ## `himi base44 entities` codes
 
 Covers `himi base44 adopt` and `himi base44 entities query` (#4557,

package/guides/index.json

@@ -24,6 +24,7 @@
     "To SELL an App Store item, a screen composes `createIapCommerce` from `@himalaya/iap-checkout` once per worker (its catalog pricing plus the shared checkout, with the vertical's order adapter) and binds its Get access action with `commerce.purchaseFields`: the order, Apple's sheet, proof delivery, finishing and the access read all happen inside it. Never call StoreKit (`purchaseForVerification`), `finishTransaction` or the payment client from a worker, never fall back to Wix checkout for an App Store item, and show access only when it reports `accessReady`. Purchasing stays unavailable until Wix provides its routes and mapping.",
     "Keep structure descriptor-authored: use FragmentSlot for enumerable variants and bound list/grid templates for repetition. Use WorkerSubtree only for runtime-unknowable structure, with an explicit screen allowlist, policy budgets, and shipped fallback.",
     "Bindings ($service:<svc>.<path>, $item.<field>, $flag:<key>) are plain strings in ANY prop — INCLUDING Modifiers token refs (background, color, tint), so a worker can drive per-item theming, not just text. They CANNOT target strict-enum fields (style, size, alignment, severity, presentation, …) — those fail at render, not validation.",
+    "A screen that loads data asynchronously ships a designed LOADING state with it — a `Skeleton` shaped like the loaded layout when that layout is known (`StatefulSection` or `ActivityIndicator` when they fit the behavior better) — and a REDESIGN of a data screen reviews and updates that loading state in the same change, so it never shows the old layout. Loading is its own state, never the empty or the error state; a static screen gets no loading state (`himi docs designing-himi-screens` §5).",
     "Workers are sandboxed: no DOM, no timers, no raw fetch. Produce state synchronously in actions; do not rely on an ambient refresh tick.",
     "Declare every capability a worker uses in TWO places: the calling screen's logicBundle.declaredCapabilities (wix_platform, stream, camera, location, …) — undeclared calls are blocked — AND config.ts `capabilities`, the app-level list a binary is built with. The `capabilities` guide shows each id's import, what the binary needs and which shells serve it; validate flags an unknown id, an undeclared call, and (with `shell` in himalaya.content.json) an id that shell's binary does not serve. A capability with a native footprint (camera, location, push, …) only arrives with a new binary — an over-the-air push cannot add it. EXCEPTION: the Wix REST bridge (wix_api — the @himalaya/wix-* clients / wixApi.call) is ungated today (installed unconditionally), so it works WITHOUT a declaration; declaring wix_api is still recommended — it is where the platform is heading, and it documents what your worker touches.",
     "`validate`/`render` prove a screen is WELL-FORMED and, by default, paint its INITIAL state — NOT that the app's LOGIC is correct. A wrong reducer (a game that never ends, a bad total) passes both with ok:true. Run `himi test`: it needs NO test files — it boots each screen's real worker and dispatches every action your descriptor already declares, then reports anything that threw, stayed stuck on `loading`, or leaked a NaN/undefined/`$service:` token into visible text. It crawls on HERMETIC DATA by default (zero network): your `dev/net-mocks.json` first, then your config's CMS `seed:` rows, then a canned fixture of frozen real vertical responses shipped with the CLI — so the fetch-SUCCESS mapping path runs too, where data-shape bugs actually live (canned data exercises code paths, not API-contract truth). Two boot-only HOSTILE passes (every list empty; every request 500) then check the empty/outage day — their findings are errors, not warnings. It also runs the worker in a DEVICE-PARITY sandbox (no setTimeout/setInterval, as on JSC/WebView), so a bundle that would only die on the device fails locally instead — e.g. `svc.actions.load(…)` (actions are DIRECT methods; `.actions` is undefined on device). (You are NOT limited to the crawled states either: rendering with `--live` runs the worker's REAL fetches against live Wix — a minted anonymous visitor token from the app's clientId — so a render CAN prove real-data binding locally with no VPN/push; and injecting `state` (`{\"<svc>\":{…}}`) renders a specific mid-flow state without the network.)",

package/guides/one-app-to-himi-app.md

@@ -121,6 +121,13 @@ Apply these interpretation rules:
   end-user access policy. Never expose protected content beneath a visual gate.
 - Exclude `ntt.*` definitions and placements from coverage. Preserve configured
   header/top-bar intent; do not add unconfigured drawer or header surfaces.
+- Before publishing, run the migration-only authored-control check:
+  `himi one-app validate-topbar --evidence-dir .himi/one-app --content .`.
+  It reads each screen's `raw-structure.json` header settings and checks that
+  `navigation.topBarDefault.actions` has a matching tappable action for every
+  authored cart/chat control. It does not use the iOS/Android enriched views to
+  infer visibility, access, or membership rules. This check is specific to this
+  migration workflow; it does not change the behavior of `himi validate`.
 - For each configured Detailed header, import and call the shared
   `detailedHeader` builder from `@wix/himalaya/screens`. Do not recreate its
   component tree in the app. Resolve the source fallback and visibility rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1452.0",
+  "version": "0.1454.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": "c345fa006ed03ed32be63ed23a653016d907cbd352ccb6171b77e23e"
+  "falconPackageHash": "eefcf19354e83f21581f78ca930495b7ae70059df5480ba579c463cb"
 }