@wix/himalaya-cli 0.1538.0 → 0.1539.0

package/guides/component-reference.json

@@ -2,12 +2,10 @@
   "_comment": "GENERATED by core/web-embed/authoring/gen-reference.mjs from core/ts/src/schema.ts — do not hand-edit. The schema is the source of truth; regenerate on schema changes.",
   "schemaSource": "core/ts/src/schema.ts",
   "bindingGrammar": "$service:<service>.<path> (worker state) · $item.<field> (list row) · $flag:<key> (feature flag) · $env:<key> (client environment — #1056). Bindings resolve in the text/value props marked 'binding-aware' below — INCLUDING Modifiers token refs — but only `background` and `border.color`, which are the two whose token a binding actually fills: a worker can drive per-item theming (e.g. a game board's per-square color), not just text. `shadow` is NOT binding-aware on any renderer, and a gradient is driven by its own `backgroundGradientPath` prop resolving to a gradient token NAME, not by a binding inside a token ref — so `shadow: { token: \"$item.x\" }` and `backgroundGradient: { token: \"$item.x\" }` keep the sentinel and silently lose the per-item styling. Colour slots split by LEVEL, not by component: inside modifiers a colour is a TokenRef OBJECT ({ token: \"…\" }), inside props it is a bare TokenName STRING — there is no modifiers.color or modifiers.tint (see the 'Token slots' section in component-reference.md). A few input props render the LITERAL and are NOT binding-aware — notably SearchField.placeholder and Chip.label; SearchField.value is live and binding-aware like other content props. Bindings also CANNOT target strict-enum fields (style, size, alignment, severity, presentation, contentMode, …) — those fail at render, not validation. $env: is client-resolved (no worker) and valid in modifiers.hiddenPath and FragmentSlot.casePath ONLY — keys reduceMotion/colorScheme/sizeClass/isRTL, e.g. hiddenPath:\"$env:reduceMotion\" or hiddenPath:\"$env:colorScheme==light\", casePath:\"$env:colorScheme\"; unknown key fails open (shown / defaultCase).",
-  "componentCount": 87,
+  "componentCount": 88,
   "notImplementedComponents": [
     "Text",
     "Icon",
-    "Carousel",
-    "Pager",
     "WebView",
     "Video",
     "PdfView",
@@ -52,7 +50,7 @@
       "bindings": [
         "itemsPath"
       ],
-      "propsSource": "export interface GridProps {\n  items: Component[];\n  /** Base column count — used at compact width (<600) and as the fallback for\n   *  clients that don't understand the responsive overrides below. */\n  columns: number;\n  /** Responsive column overrides, resolved against the Grid's OWN\n   *  available width: `columnsMedium` at ≥600, `columnsExpanded` at ≥840. Each\n   *  falls back downward (expanded → medium → columns). Absent ⇒ the Grid keeps\n   *  `columns` at every width (back-compat). */\n  columnsMedium?: number;\n  columnsExpanded?: number;\n  spacing?: number;\n  /** `$service:`/`$item.` binding → a live array to render as grid cells (overrides `items`). */\n  itemsPath?: string;\n  /** Per-cell entrance delay (`index * staggerMs`), so a Grid whose cells carry\n   *  `transition`/`appear` cascades in instead of appearing all at once. Honored on every\n   *  renderer, on BOTH the static and `itemsPath` paths. The index is FLAT across the grid\n   *  (reading order), so the cascade runs down the diagonal rather than restarting on each\n   *  row. Reduced motion collapses it to 0. Absent/0 ⇒ no cascade, which is the back-compat\n   *  default. */\n  staggerMs?: number;\n}"
+      "propsSource": "export interface GridProps {\n  items: Component[];\n  /** Base column count — used at compact width (<600) and as the fallback for\n   *  clients that don't understand the responsive overrides below. */\n  columns: number;\n  /** Responsive column overrides, resolved against the Grid's OWN\n   *  available width: `columnsMedium` at ≥600, `columnsExpanded` at ≥840. Each\n   *  falls back downward (expanded → medium → columns). Absent ⇒ the Grid keeps\n   *  `columns` at every width (back-compat). */\n  columnsMedium?: number;\n  columnsExpanded?: number;\n  spacing?: number;\n  /** `$service:`/`$item.` binding → a live array to render as grid cells (overrides `items`). */\n  itemsPath?: string;\n  /** Per-cell entrance delay (`index * staggerMs`), so a Grid whose cells carry\n   *  `transition`/`appear` cascades in instead of appearing all at once. Honored on every\n   *  renderer, on BOTH the static and `itemsPath` paths. The index is FLAT across the grid\n   *  (reading order), so the cascade runs down the diagonal rather than restarting on each\n   *  row. Reduced motion collapses it to 0. Absent/0 ⇒ no cascade, which is the back-compat\n   *  default. */\n  staggerMs?: number;\n  /** #4672 — pull-to-refresh, exactly as on `LazyList`: the screen's refresh gesture dispatches\n   *  this action (the shells find the first `onPullToRefresh` in the payload, list or grid). */\n  onPullToRefresh?: Action;\n  /** #4672 — infinite scroll, as on `LazyList`: `onLoadMore` fires once per published non-empty\n   *  `cursor` (usually a `$service:` binding) when the grid's trailing edge comes into view; a cursor\n   *  the worker publishes again (a refresh back to page 2) pages again. An empty cursor is\n   *  exhausted, and nothing fires. Works with `items` and `itemsPath`. */\n  pagination?: Pagination;\n}"
     },
     {
       "name": "Card",
@@ -89,6 +87,15 @@
       "bindings": [],
       "propsSource": "export interface EmptyStateProps {\n  title: string;\n  subtitle?: string;\n  icon?: IconRef;\n  /** The CTA. Drawn as a real `Button` (see `actionStyle` / `actionSize`). */\n  action?: Action;\n  /** #1059 — CTA label, also its accessibility label. REQUIRED when `action` is set:\n   *  there is no default, `himi validate` reports an error, and no button is drawn. */\n  actionLabel?: string;\n  /** `typography` token for the title. Default `\"bodyEmphasis\"`. */\n  titleStyle?: string;\n  /** `typography` token for the subtitle. Default `\"caption\"`. */\n  subtitleStyle?: string;\n  /** The CTA's Button `style`. Default `\"secondary\"`. */\n  actionStyle?: \"primary\" | \"secondary\" | \"plain\";\n  /** The CTA's Button `size`. Default `\"sm\"`. */\n  actionSize?: \"sm\" | \"md\";\n}"
     },
+    {
+      "name": "ErrorState",
+      "category": "Core",
+      "propsType": "ErrorStateProps",
+      "bindings": [
+        "variantPath"
+      ],
+      "propsSource": "export interface ErrorStateProps {\n  /** Default `\"server\"`. An unknown value is treated as `\"server\"`. */\n  variant?: \"server\" | \"offline\" | \"permission\" | \"signIn\";\n  /** `$service:` binding that selects the variant at runtime; wins over `variant`. */\n  variantPath?: string;\n  title?: string;\n  body?: string;\n  /** The CTA's action. Absent → no button. */\n  cta?: Action;\n  ctaLabel?: string;\n  /** `\"screen\"` (default, ~96px from the top) or `\"section\"` (~24px). */\n  placement?: \"screen\" | \"section\";\n}"
+    },
     {
       "name": "Text",
       "category": "Core",
@@ -252,7 +259,7 @@
           ]
         }
       ],
-      "propsSource": "export interface StepperProps {\n  value: number;\n  /** `$service:`/`$item.` binding → a live integer (overrides `value`). */\n  valuePath?: string;\n  min?: number;\n  max?: number;\n  onChange?: Action;\n}"
+      "propsSource": "export interface StepperProps {\n  value: number;\n  /** `$service:`/`$item.` binding → a live integer (overrides `value`). */\n  valuePath?: string;\n  min?: number;\n  max?: number;\n  onChange?: Action;\n  /** \"plain\" draws exposed minus/value/plus controls; absent uses the default capsule. */\n  presentation?: \"plain\";\n}"
     },
     {
       "name": "Avatar",
@@ -391,7 +398,7 @@
       "category": "State envelopes",
       "propsType": "SkeletonProps",
       "bindings": [],
-      "propsSource": "export interface SkeletonProps {\n  width?: number;\n  height?: number;\n  cornerRadius?: number;\n  count?: number;\n}"
+      "propsSource": "export interface SkeletonProps {\n  width?: number;\n  height?: number;\n  cornerRadius?: number;\n  count?: number;\n  style?: \"static\" | \"shimmer\";\n}"
     },
     {
       "name": "FragmentSlot",
@@ -502,18 +509,6 @@
       "bindings": [
         "itemsPath"
       ],
-      "notImplemented": {
-        "props": [
-          "liveWindow"
-        ],
-        "platforms": [
-          "ios",
-          "android",
-          "web"
-        ],
-        "severity": "styling",
-        "note": "Declared ahead of its runtime: every page stays mounted until Pager/Carousel live_window lands on each renderer (W8, #4630)."
-      },
       "propsSource": "export interface CarouselProps {\n  items: Component[];\n  currentIndex?: number;\n  onChange?: Action;\n  autoplayIntervalMs?: number;\n  /** `$service:` binding → a live array to render as slides (overrides `items`). */\n  itemsPath?: string;\n  /** 0 (default) = all slides mounted; N ⇒ mount current ± N, unmount the rest. */\n  liveWindow?: number;\n}"
     },
     {
@@ -521,18 +516,6 @@
       "category": "Navigation primitives",
       "propsType": "PagerProps",
       "bindings": [],
-      "notImplemented": {
-        "props": [
-          "liveWindow"
-        ],
-        "platforms": [
-          "ios",
-          "android",
-          "web"
-        ],
-        "severity": "styling",
-        "note": "Declared ahead of its runtime: every page stays mounted until Pager/Carousel live_window lands on each renderer (W8, #4630)."
-      },
       "propsSource": "export interface PagerProps {\n  pages: Component[];\n  currentIndex?: number;\n  onChange?: Action;\n  showIndicator?: boolean;\n  /** As {@link CarouselProps.liveWindow}. */\n  liveWindow?: number;\n}"
     },
     {
@@ -606,11 +589,10 @@
         ],
         "platforms": [
           "ios",
-          "android",
-          "web"
+          "android"
         ],
         "severity": "styling",
-        "note": "The embedded worker-bridged WebView contract is declared ahead of its runtime: no channel, instance identity, fill layout, bound height or active/muted/reload binding until the hosts implement it (iOS/macOS #4624/#4625, Android #4626/#4627, web #4628/#4629)."
+        "note": "The embedded worker-bridged WebView contract is declared ahead of its runtime on these platforms: no channel, instance identity, fill layout, bound height or active/muted/reload binding until their hosts implement it. On web all of them work for a cross-origin url page listed in allowedOrigins; an inlineHtml page is not bridged on web yet."
       },
       "propsSource": "export interface WebViewProps {\n  url?: string;\n  /** Inline HTML to load instead of `url` (mutually exclusive). */\n  inlineHtml?: string;\n  /** Fixed height in points/dp; set this OR `aspectRatio`. */\n  height?: number;\n  /** width:height ratio; used when `height` is unset. */\n  aspectRatio?: number;\n  /** Keep the WebView's own scrolling (default false). */\n  scrollEnabled?: boolean;\n  config?: WebViewConfig;\n  capabilitiesRequired?: string[];\n  // Embedded worker-bridged WebViews\n  /** `\"\"` (default, no channel) | `\"worker\"` — channel to the owning screen's worker. */\n  bridge?: \"\" | \"worker\";\n  /** Channel + storage identity; default `<screenId>?<args>/<Component.id>` (§4.1, `effectiveWebViewInstanceId`). */\n  instanceId?: string;\n  /** `$service:` bool — false ⇒ inactive (§5.4); unset ⇒ active. */\n  activePath?: string;\n  /** `$service:` bool — true ⇒ all page media muted. */\n  mutedPath?: string;\n  /** `$service:` scalar — any change remounts the document. */\n  reloadKeyPath?: string;\n  /** Take the parent's proposed size (works with weight); beats `height` / `aspectRatio`. */\n  fill?: boolean;\n  /** `$service:` number — live height in points/dp; beats `height`. */\n  heightPath?: string;\n}"
     },
@@ -1127,7 +1109,7 @@
         "severity": "styling",
         "note": "`poster` is not shown."
       },
-      "propsSource": "export interface VideoProps {\n  url?: string;\n  poster?: string;\n  autoplay?: boolean;\n  controls?: boolean;\n  loop?: boolean;\n  muted?: boolean;\n  height?: number;\n  aspectRatio?: number;\n}"
+      "propsSource": "export interface VideoProps {\n  url?: string;\n  poster?: string;\n  autoplay?: boolean;\n  controls?: boolean;\n  loop?: boolean;\n  muted?: boolean;\n  height?: number;\n  aspectRatio?: number;\n  /** #4669 — `\"fit\"` (default) letterboxes; `\"fill\"` covers the frame and crops (poster too). */\n  contentMode?: \"fit\" | \"fill\";\n}"
     },
     {
       "name": "PdfView",
@@ -1213,8 +1195,10 @@
       "category": "Rich vector & celebration (motion grammar Batch 4)",
       "propsType": "LottieProps",
       "requiresCapability": "animation",
-      "bindings": [],
-      "propsSource": "export interface LottieProps {\n  source?: string;\n  loop?: boolean;\n  autoplay?: boolean;\n  speed?: number;\n  height?: number;\n}"
+      "bindings": [
+        "playPath"
+      ],
+      "propsSource": "export interface LottieProps {\n  source?: string;\n  loop?: boolean;\n  autoplay?: boolean;\n  speed?: number;\n  height?: number;\n  /** #4669 — `$service:` binding to a nonce: each CHANGE of the resolved value plays the\n   *  animation once from frame 0. A Lottie bound this way is a one-shot (`loop` is treated as\n   *  false). The first value plays only when `autoplay` is true; reduced motion never replays. */\n  playPath?: string;\n}"
     },
     {
       "name": "Rive",
@@ -1234,9 +1218,10 @@
         "yearPath",
         "monthPath",
         "selectedStartDatePath",
-        "selectedEndDatePath"
+        "selectedEndDatePath",
+        "displayModePath"
       ],
-      "propsSource": "export interface MonthCalendarProps {\n  year?: number;\n  /** 1-12, NOT the JS 0-11 index. */\n  month?: number;\n  selectedDate?: string;\n  selectedDatePath?: string;\n  decorations?: DayDecoration[];\n  decorationsPath?: string;\n  /** 0 = Sunday … 6 = Saturday. Callers supply it; renderers never guess. */\n  firstWeekday?: number;\n  onSelectDate?: Action;\n  onMonthChange?: Action;\n  showAdjacentMonths?: boolean;\n  /** Worker-driven visible month. `onMonthChange` only reports outward; bind\n   *  these and the grid FOLLOWS worker state (jump-to-today, open-on-search-hit). */\n  yearPath?: string;\n  monthPath?: string;\n  /** Selectable window as LOCAL \"YYYY-MM-DD\". Replaces expressing a booking\n   *  horizon as one `disabled` DayDecoration per out-of-window day. */\n  minDate?: string;\n  maxDate?: string;\n  /** Per-day dot ceiling. Absent/0 ⇒ 4, so every surface draws the same count. */\n  maxDots?: number;\n  /** \"single\" (default) ⇒ `onSelectDate` per tap. \"range\" ⇒ check-in/check-out:\n   *  the first tap sets the start, the second the end, then `onSelectRange` fires.\n   *  A separate mode + separate pair, so a descriptor is never ambiguous and the\n   *  single-date path is byte-identical for existing screens. */\n  selectionMode?: \"single\" | \"range\";\n  selectedStartDate?: string;\n  selectedStartDatePath?: string;\n  selectedEndDate?: string;\n  selectedEndDatePath?: string;\n  /** Fires with args{startDate, endDate} once a range completes. */\n  onSelectRange?: Action;\n}"
+      "propsSource": "export interface MonthCalendarProps {\n  year?: number;\n  /** 1-12, NOT the JS 0-11 index. */\n  month?: number;\n  selectedDate?: string;\n  selectedDatePath?: string;\n  decorations?: DayDecoration[];\n  decorationsPath?: string;\n  /** 0 = Sunday … 6 = Saturday. Callers supply it; renderers never guess. */\n  firstWeekday?: number;\n  onSelectDate?: Action;\n  onMonthChange?: Action;\n  showAdjacentMonths?: boolean;\n  /** Worker-driven visible month. `onMonthChange` only reports outward; bind\n   *  these and the grid FOLLOWS worker state (jump-to-today, open-on-search-hit). */\n  yearPath?: string;\n  monthPath?: string;\n  /** Selectable window as LOCAL \"YYYY-MM-DD\". Replaces expressing a booking\n   *  horizon as one `disabled` DayDecoration per out-of-window day. */\n  minDate?: string;\n  maxDate?: string;\n  /** Per-day dot ceiling. Absent/0 ⇒ 4, so every surface draws the same count. */\n  maxDots?: number;\n  /** \"single\" (default) ⇒ `onSelectDate` per tap. \"range\" ⇒ check-in/check-out:\n   *  the first tap sets the start, the second the end, then `onSelectRange` fires.\n   *  A separate mode + separate pair, so a descriptor is never ambiguous and the\n   *  single-date path is byte-identical for existing screens. */\n  selectionMode?: \"single\" | \"range\";\n  selectedStartDate?: string;\n  selectedStartDatePath?: string;\n  selectedEndDate?: string;\n  selectedEndDatePath?: string;\n  /** Fires with args{startDate, endDate} once a range completes. */\n  onSelectRange?: Action;\n  /** \"month\" (default) | \"week\" — the one-row collapsed calendar an agenda sits\n   *  under. Week mode shows the week holding the selected day (else today), pages\n   *  by 7 days, and titles the month holding most of that week. */\n  displayMode?: \"month\" | \"week\";\n  /** Worker-driven mode, applied on CHANGE (the `yearPath` rule). */\n  displayModePath?: string;\n  /** Draw the week ↔ month toggle: a chevron on the title and a grab handle. */\n  expandable?: boolean;\n  /** The user switched mode → args{mode}. */\n  onDisplayModeChange?: Action;\n  /** The visible days changed (a page in either mode, or a mode switch) →\n   *  args{startDate, endDate}, LOCAL \"YYYY-MM-DD\" of the first and last cell. */\n  onVisibleRangeChange?: Action;\n}"
     },
     {
       "name": "TimeGrid",
@@ -1271,7 +1256,7 @@
     }
   ],
   "descriptor": {
-    "ScreenDescriptor": "export interface ScreenDescriptor {\n  screenId: string;\n  renderer: RendererKind;\n  title?: string;\n  /** Present when `renderer` is `sdui_intent` or `sdui_layout`. */\n  payload?: Component;\n  /** A component pinned ABOVE the scrolling payload (sticky tab-header / toolbar).\n   *  Rendered by the host outside the screen scroll, so it stays put as content\n   *  scrolls. Optional; absent = no sticky header. */\n  stickyHeader?: Component;\n  /** A component pinned BELOW the scrolling payload (sticky footer — price/confirm\n   *  bar, peeking bottom-sheet). Rendered outside the screen scroll by the host. */\n  stickyFooter?: Component;\n  /** When true, the host wraps the screen in a scroll that starts pinned to the\n   *  bottom and shows a floating \"jump to latest\" button whenever the user scrolls\n   *  up (a chat transcript). Tapping it animates back to the bottom. Absent/false =\n   *  a normal top-anchored scroll. Honored by the app host (Router). */\n  scrollToBottom?: boolean;\n  /** The chat transcript scroll policy. On a send the host pins the\n   *  named component near the top and reserves the space the reply grows into;\n   *  when the reply outgrows it the host follows the tail. A drag pauses\n   *  following, and only then is a jump-to-latest control shown. */\n  transcriptScroll?: TranscriptScroll;\n  /** The page's title for a host that shows it in its own navigation bar (iOS `himalayaEmbedTitle`, Android\n   *  `ProvideHimalayaEmbedTitle`): it gets the title as soon as it has the descriptor, before the worker boots, and\n   *  `replaces` is not drawn. Every other host ignores it, so the in-content header stays. */\n  hostTitle?: HostTitle;\n  /** Present when `renderer` is `webview_native_bridge` or `webview_ds`. */\n  url?: string;\n  capabilitiesRequired?: string[];\n  schemaVersion: number;\n  togglesApplied?: string[];\n  /** Per-session flag/experiment assignments baked in for this request. */\n  assignments?: import(\"./flags.js\").Assignment[];\n  /** Per-screen top bar (trailing actions +\n   *  leading/style override). Fully replaces `NavigationConfig.topBarDefault`. */\n  topBar?: TopBarConfig;\n  etag?: string;\n  cacheControl?: CacheControl;\n  telemetryScreenName?: string;\n  bundleSri?: string;\n  manifestVersion?: number;\n  /**\n   * Present on Tier-5 screens. The presence of this field is the tier-5\n   * signal — there is no separate `tier: 5` flag.\n   */\n  logicBundle?: LogicBundleRef;\n  /**\n   * Static per-screen input injected as `globalThis.himalaya.input` before the\n   * Tier-5 worker bundle evaluates — the worker reads it synchronously in `load()`\n   * (e.g. `himalaya.input.id` for a detail screen, or a baked catalog like\n   * `himalaya.input.cmsCollections`).\n   *\n   * A push merges its navigation parameters into this object on web, iOS, and Android.\n   * For example, `himi.open({ screenId: \"event\", id: \"$item.id\" })` makes the id\n   * available as `himalaya.input.id` in the pushed worker; static `input` remains the\n   * fallback for values baked into a descriptor or a templated route. The host also\n   * supplies `screenId`. See docs/tier-5-add-a-screen.md → \"Navigate to a detail screen\".\n   *\n   * Arbitrary JSON object; consumed by the web host (ScreenController) and the\n   * native JSWorker.\n   */\n  input?: Record<string, unknown>;\n  /**\n   * Tier 3 / Tier 4 — behavior of the hosted WebView. Ignored by SDUI tiers.\n   * Authored in the descriptor builder (git); served OTA verbatim.\n   */\n  webViewConfig?: WebViewConfig;\n}",
+    "ScreenDescriptor": "export interface ScreenDescriptor {\n  screenId: string;\n  renderer: RendererKind;\n  title?: string;\n  /** Present when `renderer` is `sdui_intent` or `sdui_layout`. */\n  payload?: Component;\n  /** A component pinned ABOVE the scrolling payload (sticky tab-header / toolbar).\n   *  Rendered by the host outside the screen scroll, so it stays put as content\n   *  scrolls. Optional; absent = no sticky header. */\n  stickyHeader?: Component;\n  /** A component pinned BELOW the scrolling payload (sticky footer — price/confirm\n   *  bar, peeking bottom-sheet). Rendered outside the screen scroll by the host. */\n  stickyFooter?: Component;\n  /** When true, the host wraps the screen in a scroll that starts pinned to the\n   *  bottom and shows a floating \"jump to latest\" button whenever the user scrolls\n   *  up (a chat transcript). Tapping it animates back to the bottom. Absent/false =\n   *  a normal top-anchored scroll. Honored by the app host (Router). */\n  scrollToBottom?: boolean;\n  /** The chat transcript scroll policy. On a send the host pins the\n   *  named component near the top and reserves the space the reply grows into;\n   *  when the reply outgrows it the host follows the tail. A drag pauses\n   *  following, and only then is a jump-to-latest control shown. */\n  transcriptScroll?: TranscriptScroll;\n  /** The page's title for a host that shows it in its own navigation bar (iOS `himalayaEmbedTitle`, Android\n   *  `ProvideHimalayaEmbedTitle`): it gets the title as soon as it has the descriptor, before the worker boots, and\n   *  `replaces` is not drawn. Every other host ignores it, so the in-content header stays. */\n  hostTitle?: HostTitle;\n  /** Present when `renderer` is `webview_native_bridge` or `webview_ds`. */\n  url?: string;\n  capabilitiesRequired?: string[];\n  schemaVersion: number;\n  togglesApplied?: string[];\n  /** Per-session flag/experiment assignments baked in for this request. */\n  assignments?: import(\"./flags.js\").Assignment[];\n  /** Per-screen top bar (trailing actions +\n   *  leading/style override). Fully replaces `NavigationConfig.topBarDefault`. */\n  topBar?: TopBarConfig;\n  /** \"\" / \"visible\" (default) | \"hidden\": hide the bottom tab bar while this screen is the\n   * visible top of its tab's stack. Static; no effect in a presentation. */\n  tabBarVisibility?: string;\n  etag?: string;\n  cacheControl?: CacheControl;\n  telemetryScreenName?: string;\n  bundleSri?: string;\n  manifestVersion?: number;\n  /**\n   * Present on Tier-5 screens. The presence of this field is the tier-5\n   * signal — there is no separate `tier: 5` flag.\n   */\n  logicBundle?: LogicBundleRef;\n  /**\n   * Static per-screen input injected as `globalThis.himalaya.input` before the\n   * Tier-5 worker bundle evaluates — the worker reads it synchronously in `load()`\n   * (e.g. `himalaya.input.id` for a detail screen, or a baked catalog like\n   * `himalaya.input.cmsCollections`).\n   *\n   * A push merges its navigation parameters into this object on web, iOS, and Android.\n   * For example, `himi.open({ screenId: \"event\", id: \"$item.id\" })` makes the id\n   * available as `himalaya.input.id` in the pushed worker; static `input` remains the\n   * fallback for values baked into a descriptor or a templated route. The host also\n   * supplies `screenId`. See docs/tier-5-add-a-screen.md → \"Navigate to a detail screen\".\n   *\n   * Arbitrary JSON object; consumed by the web host (ScreenController) and the\n   * native JSWorker.\n   */\n  input?: Record<string, unknown>;\n  /**\n   * Tier 3 / Tier 4 — behavior of the hosted WebView. Ignored by SDUI tiers.\n   * Authored in the descriptor builder (git); served OTA verbatim.\n   */\n  webViewConfig?: WebViewConfig;\n}",
     "Component": "export interface Component {\n  id: string;\n  body: ComponentBody;\n  modifiers?: Modifiers;\n  minVersion?: number;\n}",
     "LogicBundleRef": "export interface LogicBundleRef {\n  url: string;\n  /** \"sha256-...\" SRI string. */\n  integrity: string;\n  contentType?: string;\n  /** SDK capability ids the bundle is permitted to import / invoke. */\n  declaredCapabilities: string[];\n  /** Bundle refuses to load on a binary older than this (semver). */\n  minBinaryVersion?: string;\n  /** Bundle's own semver. */\n  bundleVersion?: string;\n  /** Base64 detached publisher signature over the bundle bytes\n   *  (authenticity beyond SRI). Verified by a host-injected verifier when present;\n   *  unsigned bundles load as today. */\n  signature?: string;\n  /** The publisher key id a host pins, paired with `signature`. */\n  keyId?: string;\n  /** Ambient refresh (gap G2): the host invokes `action` (a `tier5.<svc>.<action>`\n   *  path) every `intervalMs` while the screen is visible — workers have no timer\n   *  of their own, so the host owns the cadence. */\n  refresh?: { intervalMs: number; action: string };\n}",
     "Modifiers": "export interface Modifiers {\n  padding?: EdgeInsets;\n  background?: TokenRef;\n  cornerRadius?: number;\n  /** Fixed intrinsic width (pt/dp/px). Honored by iOS (`FrameIfPresent`), Android\n   *  (frame) and web (`modifiers.ts`). With no `ScrollView` in the vocabulary and\n   *  regions clipped at `maxHeight`, `width`/`height`/`fillMaxWidth` are the main\n   *  sizing tools for embed/host content. */\n  width?: number;\n  /** Fixed intrinsic height (pt/dp/px). See `width`. */\n  height?: number;\n  /** Fill the available cross-axis width (keeps any fixed `height`). Mirrors\n   *  Compose `fillMaxWidth` / SwiftUI `.frame(maxWidth: .infinity)`. See `width`. */\n  fillMaxWidth?: boolean;\n  /** CAP the node's laid-out width at this many points. It CONSTRAINS, it\n   *  does not SET: a node narrower than the cap keeps its intrinsic width, so a\n   *  short chat bubble stays short while a long one stops at the cap — the\n   *  asymmetry `width` cannot express and `weight` cannot either (weights divide\n   *  the *available* space, so every child lands on the same fraction).\n   *  The cap covers the node's TOTAL width, padding + border included (CSS\n   *  `max-width` under `box-sizing: border-box`). `fillMaxWidth` grabs the axis but\n   *  THE CAP WINS — fill + cap is exactly `maxWidth` wide; a literal `width` larger\n   *  than the cap is clamped to it too. POINTS, not a fraction: a modifier is\n   *  resolved with no portable notion of \"the row\" on any renderer — compose a\n   *  percentage from a weighted sibling gap instead. `0`/absent = no cap. */\n  maxWidth?: number;\n  /** Flex weight along the parent stack's MAIN axis (HStack = width, VStack =\n   *  height). The stack measures its intrinsic (unweighted) children first, then\n   *  divides what is LEFT among the weighted ones in proportion to their weights:\n   *  two children at `1` split the leftover equally, `2` and `1` split it 2:1.\n   *  Absent (or <= 0) keeps the node at its intrinsic size. Use this — not\n   *  `fillMaxWidth` — when a node should claim the remaining space *beside* its\n   *  siblings; a full-bleed fill grabs the whole axis and starves them. Ignored\n   *  outside an HStack/VStack.\n   *  CAVEAT — row-sharing controls have NO intrinsic width to measure first: in an\n   *  HStack a `Button` and a `Toggle` are implicitly weighted, so they DIVIDE the\n   *  row with your weighted child instead of taking a width ahead of it —\n   *  `[VStack(weight:1), Button, Button]` is a three-way split, not \"the VStack gets\n   *  the remainder\". To opt a Button out on EVERY renderer set `fullWidth: false`\n   *  (an explicit flag wins in both directions; absent falls back to the style\n   *  default, which is \"share\" for every style but `tertiary`/`link`), or use\n   *  `iconOnly`. Otherwise give the actions their own row.\n   *  See `himi docs designing-himi-screens` §4. */\n  weight?: number;\n  /** RTL — pin the subtree's writing direction: `\"ltr\"` | `\"rtl\"` | `\"locale\"`\n   *  (inherit). The common RTL pattern is the inverse of `Text.textDirection`: pin a\n   *  container `ltr` (a logotype, an attachment-tile row, a composer button row)\n   *  inside an otherwise-RTL screen. Absent = inherit the ambient direction. #1060. */\n  layoutDirection?: \"ltr\" | \"rtl\" | \"locale\";\n  /** Absolute visual translation (pt/dp/px). Applied as the OUTERMOST transform so\n   *  it shifts the fully-styled node WITHOUT changing its layout footprint — lets a\n   *  ZStack place polar/absolute children (e.g. AgentOrbit). Negative allowed. */\n  offsetX?: number;\n  offsetY?: number;\n  onTap?: Action;\n  /** Double-tap gesture (e.g. Instagram double-tap-to-like). Distinct from onTap. */\n  onDoubleTap?: Action;\n  accessibilityLabel?: string;\n  hidden?: boolean;\n  /** Data-bound conditional visibility: a `\"$service:<svc>.<field>\"`\n   *  or `\"$item.<field>\"` sentinel resolving to a bool at render; when true the\n   *  subtree fully COLLAPSES (zero layout, like `hidden`), overriding the\n   *  literal `hidden`. */\n  hiddenPath?: string;\n  /** Long-press gesture modifier. */\n  onLongPress?: Action;\n  /** Fires once when the component first appears on screen. */\n  onAppear?: Action;\n  /** Scoped token overrides for the subtree. */\n  theme?: ThemeOverrides;\n  /** Names a token from the app's `shadows` registry. */\n  shadow?: TokenRef;\n  /** Names a token from the app's `gradients` registry (background fill). */\n  backgroundGradient?: TokenRef;\n  /** Value-driven gradient: a `$service:`/`$item.` path resolving to a gradient\n   *  TOKEN NAME used as the live background (e.g. weather sky day→night). */\n  backgroundGradientPath?: string;\n  /** Value-driven background COLOR: a `$service:`/`$item.` path resolving to a\n   *  color TOKEN NAME used as the live background. Honored on iOS + Android\n   *  (`BoundBackgroundIfPresent`); web render support is tracked in #1057. */\n  backgroundColorPath?: string;\n  /** Value-driven background IMAGE: a `$service:`/`$item.` path resolving to an\n   *  image URL used as the live background. Honored on iOS + Android; web render\n   *  support is tracked in #1057. */\n  backgroundImagePath?: string;\n  /** #1051 — MEASURE (publish): report this node's laid-out size into the renderer's\n   *  self-contained (worker-free) measure store under the named keys, so a SIBLING can\n   *  feed the number back into its own layout via a `$measure:<key>` binding. The SDUI\n   *  equivalent of SwiftUI `.onGeometryChange` / Compose `onGloballyPositioned`; the\n   *  canonical use is a pinned bottom bar whose measured height becomes a scroll view's\n   *  bottom inset (sticky-footer + scroll-inset, unrepresentable before — #1051). */\n  onMeasure?: Measure;\n  /** #1051 — bound height: a `\"$measure:<key>\"` (measure store) or\n   *  `\"$service:<svc>.<field>\"` / `\"$item.<field>\"` (worker/row state) sentinel resolving\n   *  to a NUMBER at render. Wins over the literal `height`. String path only, so a\n   *  binding can never blank the node (never overload the numeric `height`). */\n  heightPath?: string;\n  /** #1051 — bound width. See `heightPath`. Wins over the literal `width`. */\n  widthPath?: string;\n  /** #1051 — bound TOP inset (the header-height → top-inset idiom). A `$measure:`/\n   *  `$service:`/`$item.` sentinel resolving to a number; added as top padding. */\n  paddingTopPath?: string;\n  /** #1051 — bound BOTTOM inset (the sticky-footer-height → bottom-inset idiom). A\n   *  `$measure:`/`$service:`/`$item.` sentinel resolving to a number; added as bottom\n   *  padding so the last scroll row clears a pinned bottom bar. */\n  paddingBottomPath?: string;\n  /** #1053 — INLINE gradient background paint. Distinct from `backgroundGradient`\n   *  (which names a `gradients` registry token an embed host can't register): this\n   *  carries its stops/colours in the descriptor, so it works anywhere. Painted as\n   *  a surface (behind children), below `material`/`backgroundGradient` if those are\n   *  also set. */\n  gradient?: Gradient;\n  /** #1053 — gradient ALPHA MASK: the node shows through where the gradient is\n   *  opaque and fades where it's transparent (a transparent-token stop = fully\n   *  clear). The material-under-gradient-scrim / scroll-fade-out idiom. Mirrors iOS\n   *  `.mask()`, Android `BlendMode.DstIn`, web `mask-image`. */\n  mask?: Gradient;\n  /** Inline border/stroke. */\n  border?: Border;\n  /** Subtree alpha 0.0–1.0; absent = opaque. */\n  opacity?: number;\n  /** #433 — constrain the subtree to a width:height ratio (e.g. `1` = square,\n   *  `1.777` = 16:9). Width-driven: the height derives from the resolved width.\n   *  Lets a data-bound Grid cell / photo tile hold its shape at any width. */\n  aspectRatio?: number;\n  /** Names a token from the app's `motions` registry; the subtree\n   *  fades + slides up on first appearance. */\n  appear?: TokenRef;\n  /** Surface material token (flat/glass/frosted). */\n  material?: TokenRef;\n  /** Per-node construction-language override. */\n  variant?: string;\n  /** Per-node density / motion override. */\n  density?: string;\n  motion?: string;\n  /** Motion grammar (Batch 1) — press/tap feedback style\n   *  (auto|none|scale|highlight|scaleHighlight|lift); timing comes from `motion`.\n   *  Applied only when the node is interactive. Unknown degrades to `auto`. */\n  pressFeedback?: string;\n  /** Motion grammar (Batch 1) — press-coupled haptic\n   *  (none|selection|light|medium|heavy|success|warning|error); fires with onTap.\n   *  Default none (opt-in). Web is a no-op. */\n  haptic?: string;\n  /** Motion grammar (Batch 1) — animate this container's size changes instead of\n   *  snapping (iOS `.animation(value:)`, Android `animateContentSize`, web height\n   *  transition). Curve from the active `motion` personality. */\n  animateContentSize?: boolean;\n  /** Motion grammar (Batch 1) — enter/exit transition; supersedes `appear` when\n   *  both are present. */\n  transition?: Transition;\n  /** Motion grammar (Batch 2, scroll-driven) — defer the `transition` enter until\n   *  the node first crosses into the scroll viewport (reveal-on-scroll). Gated by\n   *  reduced motion (shown immediately when reduced). */\n  revealOnScroll?: boolean;\n  /** Motion grammar (Batch 2, scroll-driven) — parallax factor: the node drifts\n   *  vertically at this fraction of the scroll delta as it moves through the\n   *  viewport. Gated by reduced motion. Generalizes CollapsingHeader parallaxFactor. */\n  parallax?: number;\n  /** Motion grammar (Batch 4, rich visual) — when a backgroundGradient is present,\n   *  continuously drift/rotate it (animated gradient). Gated by reduced motion. */\n  animatedGradient?: boolean;\n  /** Motion grammar (Batch 3, hero/nav) — shared-element key: a matching\n   *  transitionId on the source + destination screen morphs that element across\n   *  navigation (web View Transitions / iOS matchedTransitionSource / Android\n   *  SharedTransitionLayout). Gated by reduced motion. */\n  transitionId?: string;\n  /** Motion grammar (Batch 4, rich visual) — render the backgroundGradient as a\n   *  mesh (overlapping multi-point blend) rather than a linear sweep; combine with\n   *  animatedGradient to drift it. */\n  meshGradient?: boolean;\n  /** Motion grammar (Batch 4, celebration) — burst a one-shot confetti overlay\n   *  within the node on appear. Gated by reduced motion. */\n  confetti?: boolean;\n  /** Motion grammar (Batch 2, scroll-driven) — pin this node to the top of its\n   *  scroll container (sticky section header). Functional positioning; not gated\n   *  by reduced motion. */\n  sticky?: boolean;\n  /** Motion grammar (Batch 2, scroll-driven) — turn this thin node into a\n   *  reading-progress bar that fills left→right with scroll (scaleX). web reads\n   *  window scroll; native reads the host scroll fraction. Functional. */\n  scrollProgress?: boolean;\n  /** Motion grammar (Batch 4, rich vector) — a named built-in vector animation\n   *  (\"loader\" | \"success\" | \"pulse\"), dependency-free. Gated by reduced motion.\n   *  Arbitrary Lottie/Rive JSON is the lib-backed superset follow-up. */\n  vectorAnim?: string;\n  /** Motion grammar (Batch 1, choreography) — delay this node's ENTER transition\n   *  by N ms so a screen can SEQUENCE its entrance beyond list stagger (\"title\n   *  fades, subtitle slides in 100ms later\"). Adds to any list `staggerMs`. Gated\n   *  by reduced motion. 0/absent = no extra delay. */\n  enterDelayMs?: number;\n  /** Motion grammar (Phase-3, per-node MotionSpec) — overrides the PRESS-feedback\n   *  curve with a `motions`-registry token, mirroring `Transition.motion` for the\n   *  enter curve. Absent → press uses the global `motion` personality. */\n  pressMotion?: TokenRef;\n  /** Motion grammar (Phase-3, gesture-driven) — finger-tracked drag-to-dismiss; past\n   *  threshold along `direction` it animates off and fires `action`, else springs back. */\n  swipeDismiss?: SwipeDismiss;\n  /** Motion grammar (Phase-4, reduced-motion) — per-node escape from the reduced-motion\n   *  gate. Default true (respect). false = \"must move anyway\" (transition/press animate\n   *  even when reduced motion is on). */\n  respectReducedMotion?: boolean;\n  /** #1052 — uniform scale (1 = no change). */\n  scale?: number;\n  /** #1052 — rotation in DEGREES. */\n  rotation?: number;\n  /** #1052 — stacking order within a ZStack/overlay. */\n  zIndex?: number;\n  /** #1052 — gaussian blur radius (pt/dp/px). */\n  blur?: number;\n  /** #1052 — `false` = decorative (ignores taps, unlike `hidden` which stays hit-testable);\n   *  `true` = force hit-testable (a clear tap target). */\n  hitTestable?: boolean;\n  /** #1052 — explicit drop shadow (colour + radius + offset), for upward / multi-layer\n   *  shadows the `shadow` token can't express. */\n  boxShadow?: Shadow;\n  /** The role assistive technology should announce. Absent = the\n   *  renderer INFERS it from the component type, so an author never restates the\n   *  obvious. `\"decorative\"` is node-local: the node itself stops being an\n   *  accessibility element (no role, not a stop) while its children stay\n   *  traversable — the ARIA `role=\"presentation\"` semantic. To remove the subtree\n   *  too, use `accessibilityHidden`. */\n  accessibilityRole?: AccessibilityRole;\n  /** The supplementary \"what happens if I act\" phrase\n   *  (iOS `accessibilityHint`, Android `onClickLabel`, ARIA `aria-describedby`).\n   *  Never a substitute for `accessibilityLabel`: AT may not speak a hint at all. */\n  accessibilityHint?: string;\n  /** Remove this node AND its subtree from the accessibility tree.\n   *  Distinct from `hidden` (which removes it visually too) and from the\n   *  `\"decorative\"` role (node-local; children stay reachable). */\n  accessibilityHidden?: boolean;\n  /** Mark the node as a heading at level 1–6, for rotor / heading\n   *  navigation. Implies the `\"heading\"` role when `accessibilityRole` is absent.\n   *  The LEVEL reaches iOS and web only: Android (Compose `heading()`) and React Native\n   *  (`accessibilityRole: \"header\"`) have no level primitive and mark a plain heading. */\n  headingLevel?: number;\n  /** An explicit SPOKEN value where the visual and spoken values\n   *  differ (a rating \"3 of 5\", a gauge \"72 percent\"). Where the value is derivable\n   *  from a prop the renderer computes it and this override is unnecessary. */\n  accessibilityValue?: string;\n  /** Additive state that a single role cannot carry. A node may\n   *  hold several. */\n  accessibilityTraits?: AccessibilityTrait[];\n  /** Explicit traversal index within the nearest focus group. Absent ⇒\n   *  the arm's visual / DOM order. The lower index is reached FIRST, which is why iOS\n   *  (whose `accessibilitySortPriority` is descending) negates it. */\n  focusOrder?: number;\n  /** This node's subtree is ONE traversal scope: children are ordered\n   *  relative to each other, then the group takes its parent's slot (iOS\n   *  `shouldGroupAccessibilityChildren`, Android `isTraversalGroup`, ARIA grouping). */\n  focusGroup?: boolean;\n  /** AT / keyboard focus lands here when the screen or a newly presented\n   *  modal appears. At most one per focus scope. */\n  initialFocus?: boolean;\n  /** A general live-region announcement, on any node and any transition.\n   *  The generalization of `FragmentSlotCase.accessibilityAnnouncement`, which only ever\n   *  fired on a fragment-slot case swap. */\n  announce?: LiveRegion;\n  /** Clip ANY node (content + surface) to a shape:\n   *  \"rectangle\" | \"roundedRectangle\" | \"capsule\" | \"circle\" | \"ellipse\". Unknown/empty =\n   *  no shape clip (`cornerRadius` keeps its meaning). When set it replaces the\n   *  corner-radius-only clip; a \"roundedRectangle\" uses `clipCornerRadii`, else `cornerRadius`. */\n  clipShape?: string;\n  /** Uneven corner radii for `clipShape: \"roundedRectangle\"`. */\n  clipCornerRadii?: CornerRadii;\n  /** A recurring, finite, transform-only motion on a decorative node: a\n   *  living character's idle `hop`, a `blink`, a working `breathe`. Never changes the\n   *  node's layout footprint. Stopped by reduced motion unless `respectReducedMotion`\n   *  is false. */\n  ambientMotion?: AmbientMotion;\n}",

package/guides/component-reference.md

@@ -3,7 +3,7 @@
 > GENERATED from `core/ts/src/schema.ts` by `core/web-embed/authoring/gen-reference.mjs`.
 > The schema is the source of truth — regenerate on schema changes; do not hand-edit.
 
-**87 core component types.** Every component body is `{ "package": "himalaya", "type": "<Type>", "props": { … } }`.
+**88 core component types.** Every component body is `{ "package": "himalaya", "type": "<Type>", "props": { … } }`.
 Binding grammar: `$service:<service>.<path>` (worker state) · `$item.<field>` (list row template) · `$flag:<key>` (feature flag) · `$env:<key>` (client environment — #1056).
 Bindings resolve in the text/value props marked **binding-aware** below — **including two `Modifiers` token refs**, `background` and `border.color`, which are the only two whose token a binding actually fills: a worker can drive per-item **theming** (e.g. a game board's per-square color, `background: { token: "$item.bg" }`), not just text content. `shadow` and `backgroundGradient` are `TokenRef`s but are **not** binding-aware on any renderer — `shadow: { token: "$item.x" }` keeps the sentinel as a literal token name and silently loses the per-item styling, and a gradient is driven by its own `backgroundGradientPath` prop resolving to a gradient token NAME, not by a binding inside a token ref.
 `$env:` is **client-resolved** (no worker) and valid in `modifiers.hiddenPath` and `FragmentSlot.casePath` **only** — keys `reduceMotion` / `colorScheme` / `sizeClass` / `isRTL`, with an optional `==`/`!=` comparison (e.g. `hiddenPath: "$env:reduceMotion"`, `hiddenPath: "$env:colorScheme==light"`, `casePath: "$env:colorScheme"`). An unknown key fails open (shown / `defaultCase`).
@@ -37,6 +37,7 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 | `Divider` | Core | — |
 | `Spacer` | Core | — |
 | `EmptyState` | Core | — |
+| `ErrorState` | Core | `variantPath` |
 | `Text` | Core | `text` |
 | `Image` | Core | `url`, `initials`, `contentDescription` |
 | `Icon` | Core | — |
@@ -109,9 +110,9 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 | `Video` | Cross-cutting & media | — |
 | `PdfView` | Cross-cutting & media | — |
 | `MediaPlayer` | Cross-cutting & media | `itemsPath` |
-| `Lottie` | Rich vector & celebration (motion grammar Batch 4) | — |
+| `Lottie` | Rich vector & celebration (motion grammar Batch 4) | `playPath` |
 | `Rive` | Rich vector & celebration (motion grammar Batch 4) | — |
-| `MonthCalendar` | Rich vector & celebration (motion grammar Batch 4) | `selectedDatePath`, `decorationsPath`, `yearPath`, `monthPath`, `selectedStartDatePath`, `selectedEndDatePath` |
+| `MonthCalendar` | Rich vector & celebration (motion grammar Batch 4) | `selectedDatePath`, `decorationsPath`, `yearPath`, `monthPath`, `selectedStartDatePath`, `selectedEndDatePath`, `displayModePath` |
 | `TimeGrid` | Rich vector & celebration (motion grammar Batch 4) | `anchorDatePath`, `eventsPath`, `resourcesPath` |
 | `Agenda` | Rich vector & celebration (motion grammar Batch 4) | `eventsPath`, `scrollToDatePath` |
 
@@ -119,18 +120,16 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 
 These props are accepted by the schema and pass validation, but the named platform's renderer never reads them — they silently do nothing (no warning, no log). Prefer a prop NOT listed here, or drive the behaviour from a worker.
 
-**Scope: 9 of 87 components, all of them android / web / ios-only** — every other component/platform pair reads every prop it decodes. The list splits in two, and the halves mean different things:
+**Scope: 7 of 88 components, all of them android / web / ios-only** — every other component/platform pair reads every prop it decodes. The list splits in two, and the halves mean different things:
 
 - **`category` (2: `MediaPlayer`, `TimeGrid`)** — the prop changes the component's *kind*. These genuinely are **not implemented**: an overlay renders always-visible inline, so the component does not do the job its name implies. Check the row's note for a working alternative.
-- **`styling` (7: `Text`, `Icon`, `Carousel`, `Pager`, `WebView`, `Video`, `PdfView`)** — the component itself **works**; only the listed prop is inert. Use the component; just do not depend on that one prop.
+- **`styling` (5: `Text`, `Icon`, `WebView`, `Video`, `PdfView`)** — the component itself **works**; only the listed prop is inert. Use the component; just do not depend on that one prop.
 
 | Component | Unread props | Platform | Kind | Note |
 |---|---|---|---|---|
 | `Text` | `minimumScaleFactor`, `truncation` | android, web | styling | Compose 1.7.5 and web retain tail truncation and their existing text size. Monospaced digits work; Apple supports shrinking and head/middle truncation. React Native maps its native text API, with Android multiline ellipsis limited to tail. |
 | `Icon` | `renderingMode`, `weight`, `variableValue` | android, web | styling | Fixed catalog vectors have no SF layers, font-weight axis or variable fills. Bounce and pulse animate the whole glyph; variableColor remains static. React Native uses the same catalog fallback. |
-| `Carousel` | `liveWindow` | ios, android, web | styling | Declared ahead of its runtime: every page stays mounted until Pager/Carousel live_window lands on each renderer (W8, #4630). |
-| `Pager` | `liveWindow` | ios, android, web | styling | Declared ahead of its runtime: every page stays mounted until Pager/Carousel live_window lands on each renderer (W8, #4630). |
-| `WebView` | `bridge`, `instanceId`, `activePath`, `mutedPath`, `reloadKeyPath`, `heightPath`, `fill` | ios, android, web | styling | The embedded worker-bridged WebView contract is declared ahead of its runtime: no channel, instance identity, fill layout, bound height or active/muted/reload binding until the hosts implement it (iOS/macOS #4624/#4625, Android #4626/#4627, web #4628/#4629). |
+| `WebView` | `bridge`, `instanceId`, `activePath`, `mutedPath`, `reloadKeyPath`, `heightPath`, `fill` | ios, android | styling | The embedded worker-bridged WebView contract is declared ahead of its runtime on these platforms: no channel, instance identity, fill layout, bound height or active/muted/reload binding until their hosts implement it. On web all of them work for a cross-origin url page listed in allowedOrigins; an inlineHtml page is not bridged on web yet. |
 | `Video` | `poster` | ios | styling | `poster` is not shown. |
 | `PdfView` | `showPageControls`, `zoomable`, `allowShare` | web | styling | Interactive PDF.js canvas rendering honours the reader’s page, zoom and export controls. Static previews and PDF.js loading/rendering failures use a native browser-viewer fallback. In that fallback, hiding page or zoom controls is only a viewer hint and cannot reliably hide browser chrome; allowShare hides the reader’s export controls but cannot prevent browser save/print. These props are UI controls, not document access restrictions. |
 | `MediaPlayer` | `autoplayVisibilityThreshold`, `preload`, `playbackRates`, `showQueue`, `showChapters`, `showTranscript` | ios | category | `autoplayVisibilityThreshold` is ignored (whenVisible = once on appear). `preload` is ignored. `playbackRates` is ignored, and the queue/chapters/transcript panels never render. |
@@ -324,6 +323,14 @@ export interface GridProps {
    *  row. Reduced motion collapses it to 0. Absent/0 ⇒ no cascade, which is the back-compat
    *  default. */
   staggerMs?: number;
+  /** #4672 — pull-to-refresh, exactly as on `LazyList`: the screen's refresh gesture dispatches
+   *  this action (the shells find the first `onPullToRefresh` in the payload, list or grid). */
+  onPullToRefresh?: Action;
+  /** #4672 — infinite scroll, as on `LazyList`: `onLoadMore` fires once per published non-empty
+   *  `cursor` (usually a `$service:` binding) when the grid's trailing edge comes into view; a cursor
+   *  the worker publishes again (a refresh back to page 2) pages again. An empty cursor is
+   *  exhausted, and nothing fires. Works with `items` and `itemsPath`. */
+  pagination?: Pagination;
 }
 ```
 
@@ -399,6 +406,24 @@ export interface EmptyStateProps {
 }
 ```
 
+#### ErrorState
+
+```ts
+export interface ErrorStateProps {
+  /** Default `"server"`. An unknown value is treated as `"server"`. */
+  variant?: "server" | "offline" | "permission" | "signIn";
+  /** `$service:` binding that selects the variant at runtime; wins over `variant`. */
+  variantPath?: string;
+  title?: string;
+  body?: string;
+  /** The CTA's action. Absent → no button. */
+  cta?: Action;
+  ctaLabel?: string;
+  /** `"screen"` (default, ~96px from the top) or `"section"` (~24px). */
+  placement?: "screen" | "section";
+}
+```
+
 #### Text
 
 ```ts
@@ -657,6 +682,8 @@ export interface StepperProps {
   min?: number;
   max?: number;
   onChange?: Action;
+  /** "plain" draws exposed minus/value/plus controls; absent uses the default capsule. */
+  presentation?: "plain";
 }
 ```
 
@@ -893,6 +920,7 @@ export interface SkeletonProps {
   height?: number;
   cornerRadius?: number;
   count?: number;
+  style?: "static" | "shimmer";
 }
 ```
 
@@ -1031,8 +1059,6 @@ export interface CarouselProps {
 }
 ```
 
-> ⚠️ **Implemented, but these props are inert on ios, android, web:** `liveWindow` — Declared ahead of its runtime: every page stays mounted until Pager/Carousel live_window lands on each renderer (W8, #4630).
-
 #### Pager
 
 ```ts
@@ -1046,8 +1072,6 @@ export interface PagerProps {
 }
 ```
 
-> ⚠️ **Implemented, but these props are inert on ios, android, web:** `liveWindow` — Declared ahead of its runtime: every page stays mounted until Pager/Carousel live_window lands on each renderer (W8, #4630).
-
 #### StepIndicator
 
 ```ts
@@ -1207,7 +1231,7 @@ export interface WebViewProps {
 }
 ```
 
-> ⚠️ **Implemented, but these props are inert on ios, android, web:** `bridge`, `instanceId`, `activePath`, `mutedPath`, `reloadKeyPath`, `heightPath`, `fill` — The embedded worker-bridged WebView contract is declared ahead of its runtime: no channel, instance identity, fill layout, bound height or active/muted/reload binding until the hosts implement it (iOS/macOS #4624/#4625, Android #4626/#4627, web #4628/#4629).
+> ⚠️ **Implemented, but these props are inert on ios, android:** `bridge`, `instanceId`, `activePath`, `mutedPath`, `reloadKeyPath`, `heightPath`, `fill` — The embedded worker-bridged WebView contract is declared ahead of its runtime on these platforms: no channel, instance identity, fill layout, bound height or active/muted/reload binding until their hosts implement it. On web all of them work for a cross-origin url page listed in allowedOrigins; an inlineHtml page is not bridged on web yet.
 
 ### Controls & cells
 
@@ -2055,6 +2079,8 @@ export interface VideoProps {
   muted?: boolean;
   height?: number;
   aspectRatio?: number;
+  /** #4669 — `"fit"` (default) letterboxes; `"fill"` covers the frame and crops (poster too). */
+  contentMode?: "fit" | "fill";
 }
 ```
 
@@ -2149,6 +2175,10 @@ export interface LottieProps {
   autoplay?: boolean;
   speed?: number;
   height?: number;
+  /** #4669 — `$service:` binding to a nonce: each CHANGE of the resolved value plays the
+   *  animation once from frame 0. A Lottie bound this way is a one-shot (`loop` is treated as
+   *  false). The first value plays only when `autoplay` is true; reduced motion never replays. */
+  playPath?: string;
 }
 ```
 
@@ -2205,6 +2235,19 @@ export interface MonthCalendarProps {
   selectedEndDatePath?: string;
   /** Fires with args{startDate, endDate} once a range completes. */
   onSelectRange?: Action;
+  /** "month" (default) | "week" — the one-row collapsed calendar an agenda sits
+   *  under. Week mode shows the week holding the selected day (else today), pages
+   *  by 7 days, and titles the month holding most of that week. */
+  displayMode?: "month" | "week";
+  /** Worker-driven mode, applied on CHANGE (the `yearPath` rule). */
+  displayModePath?: string;
+  /** Draw the week ↔ month toggle: a chevron on the title and a grab handle. */
+  expandable?: boolean;
+  /** The user switched mode → args{mode}. */
+  onDisplayModeChange?: Action;
+  /** The visible days changed (a page in either mode, or a mode switch) →
+   *  args{startDate, endDate}, LOCAL "YYYY-MM-DD" of the first and last cell. */
+  onVisibleRangeChange?: Action;
 }
 ```
 
@@ -2315,6 +2358,9 @@ export interface ScreenDescriptor {
   /** Per-screen top bar (trailing actions +
    *  leading/style override). Fully replaces `NavigationConfig.topBarDefault`. */
   topBar?: TopBarConfig;
+  /** "" / "visible" (default) | "hidden": hide the bottom tab bar while this screen is the
+   * visible top of its tab's stack. Static; no effect in a presentation. */
+  tabBarVisibility?: string;
   etag?: string;
   cacheControl?: CacheControl;
   telemetryScreenName?: string;

package/guides/dynamic-list.service.ts

@@ -87,7 +87,11 @@ function shape(s: Partial<ProductsState>): ProductsState {
 // under `himi test` / `himi render`.
 const STATUS = /\b(?:HTTP|Wix) (\d{3})\b/;
 // No answer at all — what a dropped connection says on every platform.
-const TRANSPORT = /NSURLErrorDomain|(?:UnknownHost|Connect|SocketTimeout|NoRouteToHost|SSLHandshake)Exception|Failed to connect|Unable to resolve host|Connection (?:refused|reset)|Network is unreachable|Software caused connection abort|ECONNRESET|ETIMEDOUT|EPIPE|Broken pipe|stream was reset|unexpected end of stream|timed out|^timeout$|Failed to fetch|NetworkError|^(?:TypeError: )?Load failed$|net::ERR_|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+const TRANSPORT = /(?:UnknownHost|Connect|NoRouteToHost|SSLHandshake)Exception|Unable to resolve host|Connection (?:refused|reset)|Network is unreachable|Software caused connection abort|ECONNRESET|EPIPE|Broken pipe|stream was reset|unexpected end of stream|Failed to fetch|NetworkError|^(?:TypeError: )?Load failed$|net::ERR_|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+// iOS reports a URLError as `NSURLErrorDomain error <code>`: only the no-route codes are offline. A bad server
+// response (-1011) or a timeout is a server problem, as in the SDK's classifyLoadError.
+const URL_ERROR = /NSURLErrorDomain\D*?(-?\d{3,5})/;
+const URL_OFFLINE = new Set([-1009, -1005, -1004, -1003, -1006, -1020]);
 // Android reports an unknown host as the bare hostname (`users.wix.com`) — hence the last form.
 // No session on the device: the native bridge refuses before any request leaves.
 // A pinned site with no member session: iOS `siteNotPermitted(requested: "account", …)`,
@@ -119,6 +123,8 @@ function classifyError(e: unknown, authState: "signedIn" | "signedOut" | "unknow
     ? /"detail"\s*:\s*"([^"]+)"/.exec(msg)?.[1] ?? msg
     : msg;
   if (status && detail === msg) return "server";
+  const urlCode = URL_ERROR.exec(detail)?.[1];
+  if (urlCode !== undefined) return URL_OFFLINE.has(Number(urlCode)) ? "offline" : "server";
   if (TRANSPORT.test(detail)) return "offline";
   return "server";   // anything else — a bug, a malformed row — is not the user's connection
 }

package/guides/form-submit.service.ts

@@ -60,7 +60,11 @@ const SAVE_FAILED: Record<Exclude<ErrorKind, "">, string> = {
 // under `himi test` / `himi render`.
 const STATUS = /\b(?:HTTP|Wix) (\d{3})\b/;
 // No answer at all — what a dropped connection says on every platform.
-const TRANSPORT = /NSURLErrorDomain|(?:UnknownHost|Connect|SocketTimeout|NoRouteToHost|SSLHandshake)Exception|Failed to connect|Unable to resolve host|Connection (?:refused|reset)|Network is unreachable|Software caused connection abort|ECONNRESET|ETIMEDOUT|EPIPE|Broken pipe|stream was reset|unexpected end of stream|timed out|^timeout$|Failed to fetch|NetworkError|^(?:TypeError: )?Load failed$|net::ERR_|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+const TRANSPORT = /(?:UnknownHost|Connect|NoRouteToHost|SSLHandshake)Exception|Unable to resolve host|Connection (?:refused|reset)|Network is unreachable|Software caused connection abort|ECONNRESET|EPIPE|Broken pipe|stream was reset|unexpected end of stream|Failed to fetch|NetworkError|^(?:TypeError: )?Load failed$|net::ERR_|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+// iOS reports a URLError as `NSURLErrorDomain error <code>`: only the no-route codes are offline. A bad server
+// response (-1011) or a timeout is a server problem, as in the SDK's classifyLoadError.
+const URL_ERROR = /NSURLErrorDomain\D*?(-?\d{3,5})/;
+const URL_OFFLINE = new Set([-1009, -1005, -1004, -1003, -1006, -1020]);
 // Android reports an unknown host as the bare hostname (`users.wix.com`) — hence the last form.
 // No session on the device: the native bridge refuses before any request leaves.
 // A pinned site with no member session: iOS `siteNotPermitted(requested: "account", …)`,
@@ -92,6 +96,8 @@ function classifyError(e: unknown, authState: "signedIn" | "signedOut" | "unknow
     ? /"detail"\s*:\s*"([^"]+)"/.exec(msg)?.[1] ?? msg
     : msg;
   if (status && detail === msg) return "server";
+  const urlCode = URL_ERROR.exec(detail)?.[1];
+  if (urlCode !== undefined) return URL_OFFLINE.has(Number(urlCode)) ? "offline" : "server";
   if (TRANSPORT.test(detail)) return "offline";
   return "server";   // anything else — a bug, a malformed row — is not the user's connection
 }

package/guides/index.json

@@ -1,7 +1,7 @@
 {
   "_comment": "AUTO-GENERATED by tools/authoring-kit/bundle.mjs — DO NOT EDIT. Regenerate with: npm run authoring:gen",
   "schemaStamp": {
-    "componentCount": 87,
+    "componentCount": 88,
     "schemaSource": "core/ts/src/schema.ts"
   },
   "portalUrl": "https://apps.wix.com/_api/himi-serve/docs",
@@ -25,7 +25,7 @@
     "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).",
-    "CLASSIFY every error before you show it: offline, server failure, sign-in, site membership and permission each get their own `EmptyState` with `title` + `subtitle` and NO `icon` (one node per class, gated by `hiddenPath`, because iOS/Android do not bind `$service:` in its text), user-facing copy — never `e.message`, a status code or an API error string — and an `action` + `actionLabel` ONLY for a real recovery (Try again for offline, server and failed writes; the app's auth flow for sign-in; the site's join flow for `NotSiteMember` when available; none for permission, empty results or field errors). Empty results are the empty state, not an error. A refresh that fails KEEPS the rows and adds a `Banner` with retry; a load-more that fails keeps the rows and ends the list with a \"Couldn't load more\" row that retries the SAME cursor (`himi docs recipe-dynamic-list`), never the Banner, which reloads page 1. A sign-in, membership or permission failure CLEARS the rows instead — they are no longer the user's to see. Field errors stay in the field's slot; a failed action shows next to the action. When an `ErrorState` component ships, only the component changes — these rules stay (`himi docs designing-himi-screens` §5, `himi docs recipe-four-state`).",
+    "CLASSIFY every error before you show it: offline, server failure, sign-in, site membership and permission each show an `ErrorState` (gated by `hiddenPath`): `variantPath` bound to the worker's error kind switches the copy and glyph, but `cta`, `title`, `body` and `ctaLabel` apply to every variant, so offline and server share one node with the retry `cta` while sign-in, permission and membership (`variant: \"permission\"` with its own `title`/`body`) keep a node each; user-facing copy — never `e.message`, a status code or an API error string — and a `cta` ONLY for a real recovery (Try again for offline, server and failed writes; the app's auth flow for sign-in; the site's join flow for `NotSiteMember` when available; none for permission, empty results or field errors). Empty results are the empty state, not an error. A refresh that fails KEEPS the rows and adds a `Banner` with retry; a load-more that fails keeps the rows and ends the list with a \"Couldn't load more\" row that retries the SAME cursor (`himi docs recipe-dynamic-list`), never the Banner, which reloads page 1. A sign-in, membership or permission failure CLEARS the rows instead — they are no longer the user's to see. Field errors stay in the field's slot; a failed action shows next to the action. (`himi docs designing-himi-screens` §5, `himi docs recipe-four-state`).",
     "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/recipe-four-state.md

@@ -22,6 +22,9 @@ more than half model error, and the reference apps (`apps/himi-owner-lite`,
 
 ## 1. One status field, a classified error, derived flags
 
+> `classifyError` below ships in the SDK as `classifyLoadError(error, authState)` from `@himalaya/state`
+> (same rules, returns the `ErrorKind` without `""`). Import it instead of pasting the regexes into a new worker.
+
 ```ts
 type ErrorKind = "" | "offline" | "server" | "signIn" | "membership" | "permission";
 
@@ -63,7 +66,11 @@ function shape(s: Partial<State>): State {
 // under `himi test` / `himi render`.
 const STATUS = /\b(?:HTTP|Wix) (\d{3})\b/;
 // No answer at all — what a dropped connection says on every platform.
-const TRANSPORT = /NSURLErrorDomain|(?:UnknownHost|Connect|SocketTimeout|NoRouteToHost|SSLHandshake)Exception|Failed to connect|Unable to resolve host|Connection (?:refused|reset)|Network is unreachable|Software caused connection abort|ECONNRESET|ETIMEDOUT|EPIPE|Broken pipe|stream was reset|unexpected end of stream|timed out|^timeout$|Failed to fetch|NetworkError|^(?:TypeError: )?Load failed$|net::ERR_|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+const TRANSPORT = /(?:UnknownHost|Connect|NoRouteToHost|SSLHandshake)Exception|Unable to resolve host|Connection (?:refused|reset)|Network is unreachable|Software caused connection abort|ECONNRESET|EPIPE|Broken pipe|stream was reset|unexpected end of stream|Failed to fetch|NetworkError|^(?:TypeError: )?Load failed$|net::ERR_|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+// iOS reports a URLError as `NSURLErrorDomain error <code>`: only the no-route codes are offline. A bad server
+// response (-1011) or a timeout is a server problem, as in the SDK's classifyLoadError.
+const URL_ERROR = /NSURLErrorDomain\D*?(-?\d{3,5})/;
+const URL_OFFLINE = new Set([-1009, -1005, -1004, -1003, -1006, -1020]);
 // Android reports an unknown host as the bare hostname (`users.wix.com`) — hence the last form.
 // No session on the device: the native bridge refuses before any request leaves.
 // A pinned site with no member session: iOS `siteNotPermitted(requested: "account", …)`,
@@ -95,6 +102,8 @@ function classifyError(e: unknown, authState: "signedIn" | "signedOut" | "unknow
     ? /"detail"\s*:\s*"([^"]+)"/.exec(msg)?.[1] ?? msg
     : msg;
   if (status && detail === msg) return "server";
+  const urlCode = URL_ERROR.exec(detail)?.[1];
+  if (urlCode !== undefined) return URL_OFFLINE.has(Number(urlCode)) ? "offline" : "server";
   if (TRANSPORT.test(detail)) return "offline";
   return "server";   // anything else — a bug, a malformed row — is not the user's connection
 }