@wix/himalaya-cli 0.1405.0 → 0.1407.0

package/guides/sdk-reference.json

@@ -1053,7 +1053,7 @@
         "name": "NavigationConfig",
         "kind": "interface",
         "jsdoc": "/** Per-app navigation/deep-link config, served OTA at GET /v1/app-config/:appName. */",
-        "decl": "export interface NavigationConfig {\n  /** Tab-bar structure (which tabs; their icons/labels/badges). */\n  tabBar?: TabBarConfig;\n  /** Slide-in drawer / hamburger-menu destinations. */\n  drawer?: DrawerConfig;\n  /** Navigation chrome the shell draws.\n   *  Omitted ⇒ \"bottomTabs\". The shell (not the descriptor) reads this. */\n  navKind?: NavKind;\n  /** Destinations for \"sidebar\" mode.\n   *  Absent ⇒ the shell derives the rail from `tabBar.items`. */\n  sidebar?: SidebarConfig;\n  /** App-level default top bar; a per-screen\n   *  `ScreenDescriptor.topBar` fully replaces it (override, not merge). */\n  topBarDefault?: TopBarConfig;\n  /** The post-OS-splash brand surface (see `SplashConfig`). Absent / not enabled\n   * ⇒ today's behavior. Operational per (live-flippable). */\n  splash?: SplashConfig;\n  /** App-level default locale. Operational per so a Hebrew (or Spanish)\n   *  branded app can pin RTL/l10n OTA without a launch flag. `default` is a\n   *  BCP-47 primary subtag; clients coerce unknown tags rather than failing the\n   *  envelope. `pin: true` skips the device/browser language; in-app `locale.set`\n   *  still wins. Absent ⇒ today's device-then-en behavior. */\n  locale?: LocaleConfig;\n  /** Effective orientations, resolved INSIDE\n   *  the binary's build-time envelope (config.ts `orientationEnvelope`). The\n   *  envelope is the ceiling and can never be OTA (iOS reads the plist before\n   *  any app code runs); this narrows within it. Always intersected with the\n   *  envelope — it can never widen it. Absent/empty ⇒ the envelope itself. */\n  orientation?: OrientationConfig;\n  /** Per-surface nav projection, keyed by catalog\n   *  surface id (`phone` | `tablet` | `desktop` | `mac` | `watch` | `wear` | `rn`).\n   *  Keyed the way `orientation` is keyed by device family and narrowed the same\n   *  way: a key outside the app's `platforms.json` envelope is DROPPED, never\n   *  honored (see `resolveSurfaceNav`). Absent key ⇒ that surface uses the default\n   *  projection, so an app that never thinks about surfaces is unaffected. */\n  surfaces?: Record<string, SurfaceNavConfig>;\n  /** The APP-LEVEL nav worker\n   *  that feeds every `*Path` binding on `NavTabItem` / `DrawerItem` /\n   *  `TopBarAction`. App-level, not a screen's worker, because chrome outlives\n   *  every screen: a cart badge must survive leaving the cart, and a flag-hidden\n   *  tab must stay hidden three pushes deep in another stack. Absent ⇒ paths stay\n   *  unresolved and the literals render — the worker enriches, it never gates. */\n  navLogicBundle?: LogicBundleRef;\n  /** Which nav badges ALSO drive the OS app-icon\n   *  badge. Each entry is `\"<kind>:<id>\"` (`tab` | `drawer` | `topBarAction`, the\n   *  spelling `navKey` uses); the icon shows the SUM of those slots' resolved counts.\n   *  Empty/absent ⇒ no mirroring. An entry naming a slot this build does not have is\n   *  ignored, never a blanked badge. Requires the `push` capability — `defineApp`\n   *  rejects the combination, because the badge would be set and never shown. */\n  appIconBadgeSources?: string[];\n  /** Signed release allowlist for contained browser Tier-5 `_stream` requests. */\n  streamPolicy?: StreamPolicy;\n  /** A site shell's URL space. A push tap, app link or\n   *  custom-scheme link whose URL is an https page on one of `site.origins` opens the\n   *  screen owning its path, and that screen's WebView loads the full URL. Absent ⇒\n   *  links resolve as before. Build it with `siteNavConfig()` from\n   *  `@himalaya/core/site-shell`; resolution is `resolveSiteLink()`. */\n  site?: SiteNavConfig;\n  scheme: string;\n  deepLinkPatterns: DeepLinkPattern[];\n  linkableScreens: LinkableScreen[];\n}"
+        "decl": "export interface NavigationConfig {\n  /** Tab-bar structure (which tabs; their icons/labels/badges). */\n  tabBar?: TabBarConfig;\n  /** Slide-in drawer / hamburger-menu destinations. */\n  drawer?: DrawerConfig;\n  /** Navigation chrome the shell draws.\n   *  Omitted ⇒ \"bottomTabs\". The shell (not the descriptor) reads this. */\n  navKind?: NavKind;\n  /** Destinations for \"sidebar\" mode.\n   *  Absent ⇒ the shell derives the rail from `tabBar.items`. */\n  sidebar?: SidebarConfig;\n  /** App-level default top bar; a per-screen\n   *  `ScreenDescriptor.topBar` fully replaces it (override, not merge). */\n  topBarDefault?: TopBarConfig;\n  /** The post-OS-splash brand surface (see `SplashConfig`). Absent / not enabled\n   * ⇒ today's behavior. Operational per (live-flippable). */\n  splash?: SplashConfig;\n  /** App-level default locale. Operational per so a Hebrew (or Spanish)\n   *  branded app can pin RTL/l10n OTA without a launch flag. `default` is a\n   *  BCP-47 primary subtag; clients coerce unknown tags rather than failing the\n   *  envelope. `pin: true` skips the device/browser language; in-app `locale.set`\n   *  still wins. Absent ⇒ today's device-then-en behavior. */\n  locale?: LocaleConfig;\n  /** Effective orientations, resolved INSIDE\n   *  the binary's build-time envelope (config.ts `orientationEnvelope`). The\n   *  envelope is the ceiling and can never be OTA (iOS reads the plist before\n   *  any app code runs); this narrows within it. Always intersected with the\n   *  envelope — it can never widen it. Absent/empty ⇒ the envelope itself. */\n  orientation?: OrientationConfig;\n  /** Per-surface nav projection, keyed by catalog\n   *  surface id (`phone` | `tablet` | `desktop` | `mac` | `watch` | `wear` | `rn`).\n   *  Keyed the way `orientation` is keyed by device family and narrowed the same\n   *  way: a key outside the app's `platforms.json` envelope is DROPPED, never\n   *  honored (see `resolveSurfaceNav`). Absent key ⇒ that surface uses the default\n   *  projection, so an app that never thinks about surfaces is unaffected. */\n  surfaces?: Record<string, SurfaceNavConfig>;\n  /** The APP-LEVEL nav worker\n   *  that feeds every `*Path` binding on `NavTabItem` / `DrawerItem` /\n   *  `TopBarAction`. App-level, not a screen's worker, because chrome outlives\n   *  every screen: a cart badge must survive leaving the cart, and a flag-hidden\n   *  tab must stay hidden three pushes deep in another stack. Absent ⇒ paths stay\n   *  unresolved and the literals render — the worker enriches, it never gates. */\n  navLogicBundle?: LogicBundleRef;\n  /** Which nav badges ALSO drive the OS app-icon\n   *  badge. Each entry is `\"<kind>:<id>\"` (`tab` | `drawer` | `topBarAction`, the\n   *  spelling `navKey` uses); the icon shows the SUM of those slots' resolved counts.\n   *  Empty/absent ⇒ no mirroring. An entry naming a slot this build does not have is\n   *  ignored, never a blanked badge. Requires the `push` capability — `defineApp`\n   *  rejects the combination, because the badge would be set and never shown. */\n  appIconBadgeSources?: string[];\n  /** Signed release allowlist for contained browser Tier-5 `_stream` requests. */\n  streamPolicy?: StreamPolicy;\n  /** A site shell's URL space. A push tap, app link or\n   *  custom-scheme link whose URL is an https page on one of `site.origins` opens the\n   *  screen owning its path, and that screen's WebView loads the full URL. Absent ⇒\n   *  links resolve as before. Build it with `siteNavConfig()` from\n   *  `@himalaya/core/site-shell`; resolution is `resolveSiteLink()`. */\n  site?: SiteNavConfig;\n  /** amendment \"top-bar gap items\" — app-wide logo for tab-stack roots. */\n  topBarLogo?: TopBarLogo;\n  scheme: string;\n  deepLinkPatterns: DeepLinkPattern[];\n  linkableScreens: LinkableScreen[];\n}"
       },
       {
         "name": "NavKind",
@@ -1095,7 +1095,7 @@
         "name": "TopBarConfig",
         "kind": "interface",
         "jsdoc": "/** The shell-owned top bar. The shell paints\n *  `ScreenDescriptor.title` and computes the leading slot (back XOR menu) from\n *  nav depth; this adds the trailing action cluster + leading/style overrides.\n *  Lives on `ScreenDescriptor.topBar` (authoritative) and\n *  `NavigationConfig.topBarDefault` (app-level fallback, fully replaced). */",
-        "decl": "export interface TopBarConfig {\n  /** Trailing (right-edge) actions, authored order = leading→trailing. */\n  actions?: TopBarAction[];\n  /** Leading override: \"\" | \"auto\" (shell-computed) | \"back\" | \"menu\" | \"none\". */\n  leading?: string;\n  /** Content-under-bar: \"\" | \"opaque\" (default) | \"transparent\" | \"immersive\". */\n  style?: string;\n}"
+        "decl": "export interface TopBarConfig {\n  /** Trailing (right-edge) actions, authored order = leading→trailing. */\n  actions?: TopBarAction[];\n  /** Leading override: \"\" | \"auto\" (shell-computed) | \"back\" | \"menu\" | \"none\". */\n  leading?: string;\n  /** Content-under-bar: \"\" | \"opaque\" (default) | \"transparent\" | \"immersive\". */\n  style?: string;\n  /** Toolbar items (drawn after the legacy `actions`). */\n  items?: ToolbarItem[];\n  /** \"\" / \"automatic\" (default) | \"large\" | \"inline\". */\n  titleDisplay?: string;\n  /** The literal subtitle (the fallback for `subtitlePath`). */\n  subtitle?: string;\n  /** \"\" / \"visible\" (default) | \"hidden\". */\n  visibility?: string;\n  /** Bar fill token. iOS 26 keeps the system glass (amendment R12). */\n  background?: TokenRef;\n  // Field 9 (`searchable`) belongs to the \"Native top-bar search\" implementation.\n  /** amendment — the screen's logo; overrides `NavigationConfig.topBarLogo`. */\n  logo?: TopBarLogo;\n  /** amendment — the title as a menu. */\n  titleMenu?: TopBarTitleMenu;\n  /** amendment — live subtitle (`$service:`); `subtitle` is the fallback. */\n  subtitlePath?: string;\n  /** amendment — \"\" / \"pinned\" (default) | \"hide_on_scroll\". */\n  scrollBehavior?: string;\n  /** amendment — truthy ⇒ leaving the presentation asks to discard. Unset/unresolved ⇒ false. */\n  dirtyPath?: string;\n}"
       },
       {
         "name": "SplashConfig",
@@ -1151,6 +1151,30 @@
         "jsdoc": "/** One entry of {@link SiteNavConfig.routes}. */",
         "decl": "export interface SiteRoute {\n  /** Site-relative path prefix: `\"/\"`, `\"/shop\"`, `\"/blog\"`. */\n  path: string;\n  /** The screen whose WebView loads the URL. */\n  screenId: string;\n}"
       },
+      {
+        "name": "TopBarLogo",
+        "kind": "interface",
+        "jsdoc": "/** amendment — the bar logo, per screen (`TopBarConfig.logo`) or app-wide\n *  (`NavigationConfig.topBarLogo`). `imageUrlPath` resolves by the parent's context: the\n *  screen host per screen, the nav worker app-wide. */",
+        "decl": "export interface TopBarLogo {\n  imageUrl?: string;\n  imageUrlDark?: string;\n  /** Baked asset name; wins over `imageUrl`. */\n  imageAsset?: string;\n  /** Optional business name beside a mark-only logo. */\n  name?: string;\n  /** \"\" / \"title\" (default) | \"leading\" | \"none\". */\n  placement?: string;\n  imageUrlPath?: string;\n  /** Default: the app's display name. */\n  accessibilityLabel?: string;\n}"
+      },
+      {
+        "name": "ToolbarItem",
+        "kind": "interface",
+        "jsdoc": "/** One top-bar item. Test id `toolbar.<id>`\n *  (`toolbar-<id>` on web and React Native). Every tap carries an existing `Action`\n *. Bindings are `$service:` sentinels resolved by the screen host. */",
+        "decl": "export interface ToolbarItem {\n  id: string;\n  /** \"leading\" | \"trailing\" (default) | \"principal\" | \"bottom\" | \"keyboard\" | \"overflow\". */\n  placement?: string;\n  /** Text button when there is no icon; the accessible name always. */\n  label?: string;\n  icon?: IconRef;\n  onTap?: Action;\n  /** \"\" | \"cancel\" | \"confirm\" | \"destructive\". */\n  role?: string;\n  disabled?: boolean;\n  /** OR'd with `disabled`. For Save, bind \"nothing to save\" (e.g. `cannotSave`), never the dirty flag. */\n  disabledPath?: string;\n  /** Non-empty ⇒ the item opens a menu. */\n  menu?: MenuItem[];\n  /** \"principal\" only: a custom title view. */\n  content?: Component;\n  /** Truthy ⇒ a progress indicator replaces the item. Unset/unresolved ⇒ false. */\n  loadingPath?: string;\n  /** Set ⇒ the item draws an avatar; `label` stays the accessible name (\"Profile\" by default). */\n  avatar?: ToolbarAvatar;\n  /** Live label; `label` is the fallback. */\n  labelPath?: string;\n}"
+      },
+      {
+        "name": "ToolbarAvatar",
+        "kind": "interface",
+        "jsdoc": "/** amendment — an avatar item. Images are absolute https URLs (resolve a Wix\n *  media id with `wixMediaUrl` before publishing). */",
+        "decl": "export interface ToolbarAvatar {\n  imageUrl?: string;\n  initials?: string;\n  imageUrlPath?: string;\n  initialsPath?: string;\n}"
+      },
+      {
+        "name": "TopBarTitleMenu",
+        "kind": "interface",
+        "jsdoc": "/** amendment — the title as a menu (switch location or feed). */",
+        "decl": "export interface TopBarTitleMenu {\n  items?: MenuItem[];\n  selectedId?: string;\n  /** `selectedId` is the fallback. */\n  selectedIdPath?: string;\n  /** Default \"<title>, switch\". */\n  accessibilityLabel?: string;\n}"
+      },
       {
         "name": "LocaleConfig",
         "kind": "interface",
@@ -5210,6 +5234,12 @@
         "kind": "const",
         "jsdoc": "/** Capability version, for bundles that gate on min binary version. */",
         "decl": "export const version = 2;"
+      },
+      {
+        "name": "\"./offline.js\"",
+        "kind": "reexport",
+        "jsdoc": "",
+        "decl": "export {\n  offline, isOfflineWriteBlocked, isOfflineWriteOutcomeUnknown,\n  type Sent, type Queued, type OfflineResult, type OfflineEvent, type OfflineEventType, type PendingWrite, type RejectedWrite,\n} from \"./offline.js\";"
       }
     ]
   },

package/guides/wix-api-usage.md

@@ -222,6 +222,55 @@ hosts will require. (Contrast: the cross-cutting facade `@himalaya/wix-platform`
 provisioned — decide per call whether to surface, fall back, or render an empty state (don't crash the worker).
 Produce complete results synchronously in the action (the ambient tick is unreliable — see the Tier-5 notes).
 
+## Offline writes — `{ offline: "queue" }`
+
+A write a member makes offline can wait in an on-device outbox and go out on reconnect, but only
+when BOTH keys turn:
+
+1. **The app's cache rule opts the endpoint in**, naming it exactly, with a `method` and a `tag`:
+
+   ```ts
+   cache: { rules: [
+     { method: "POST", pathPrefix: "/form-submission-service/v4/submissions", cacheable: false, ttl: 0,
+       tag: "forms", queueOffline: true },
+   ] }
+   ```
+
+   The platform queues it only if the endpoint is one it lists as safe to resend (each verified
+   live for how a repeated request is deduplicated), and never for payments, checkout, orders,
+   auth, gift cards, loyalty or bookings. It decides the dedupe mechanism and a max age (7 days,
+   24 hours for personal data). App validation reports a rule that asks but cannot queue, and why.
+
+2. **The call site asks**, so a worker that never heard of this keeps today's behaviour:
+
+   ```ts
+   import { offline, isOfflineWriteOutcomeUnknown } from "@himalaya/wix-platform";
+
+   const r = await offline.call("POST", "/form-submission-service/v4/submissions", body);
+   if (r.status === "queued") markPending(r.writeId);   // show the row as "Pending"
+   else render(r.value);                                // r.status === "sent"
+   offline.on("applied", (e) => clearPending(e.writeId));
+   offline.on("rejected", (e) => showFailed(e.writeId, e.code));
+   ```
+
+   (`himalaya.wixApi.call(method, path, body, headers, { offline: "queue" })` is the raw form.)
+
+What a worker gets back:
+
+- `sent` — online and nothing of the same `tag` waiting: the endpoint's own answer.
+- `queued` — offline, or behind an earlier write of the same `tag`, or the live attempt failed in a
+  way the outbox will retry. Never resubmit it: that would be a real duplicate.
+- a thrown response error — a definite rejection (a 4xx), exactly as without the option.
+- `err.code === "offline_write_outcome_unknown"` — an endpoint with no server-side dedupe whose
+  attempt may or may not have landed. Say "we couldn't confirm this went through".
+- `err.code === "offline_write_blocked"` — offline and the write may not queue (`err.reason`:
+  `not_queueable`, `no_outbox` for a visitor or a host with no member, `queue_full`).
+
+Only a signed-in member has an outbox; it is dropped on sign-out, account switch and
+`AppContext.forget`. `offline.pending()` lists what waits (no bodies), `offline.rejected()` what was
+refused (with its body until the write's max age), `offline.dismiss(writeId)` clears one. The shell
+banner shows "Offline · Pending sync (n)" and "Syncing (n)…" for the app on screen.
+
 ## Visitor vs owner scope — a data-surface cheat-sheet
 
 The currency trap below is just the sharpest edge of one rule: a **visitor / consumer** session reads site

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1405.0",
+  "version": "0.1407.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": "0a22f58e5c6c241689ced19f73766e414c3004bb061a6c6b8f738a92"
+  "falconPackageHash": "b802acb38e0b8d9b19d1d1d61a60d51aff08fee456a640e590e83157"
 }