@wix/himalaya-cli 0.1237.0 → 0.1238.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/dev-server/src/builder.d.ts

@@ -192,6 +192,14 @@ export declare function emptyState(props: {
         actionId: string;
         params?: Record<string, string>;
     };
+    /** Required with `action` (#3846) — the CTA label; there is no default. */
+    actionLabel?: string;
+    /** `typography` token names (#3846). Defaults: "bodyEmphasis" / "caption". */
+    titleStyle?: string;
+    subtitleStyle?: string;
+    /** The CTA Button's `style` / `size` (#3846). Defaults: "secondary" / "sm". */
+    actionStyle?: "primary" | "secondary" | "plain";
+    actionSize?: "sm" | "md";
 }): Component;
 export declare function appIntent(pkg: string, type: string, props: unknown, opts?: {
     id?: string;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/ts/src/schema.d.ts

@@ -549,13 +549,28 @@ export interface CollapsingHeaderProps {
     /** 0.0 = static, 1.0 = full parallax (default 0.5). */
     parallaxFactor?: number;
 }
+/**
+ * The ONE standard empty state: a centred stack of icon tile, title, subtitle and
+ * button, in that order. Only `title` is required; an absent part draws nothing and keeps
+ * no gap. Padding and gaps come from the `spacing` tokens, text from `typography`.
+ */
 export interface EmptyStateProps {
     title: string;
     subtitle?: string;
     icon?: IconRef;
+    /** The CTA. Drawn as a real `Button` (see `actionStyle` / `actionSize`). */
     action?: Action;
-    /** #1059 — CTA label; overridable for localized hosts. Default "Take action". */
+    /** #1059 — CTA label, also its accessibility label. REQUIRED when `action` is set:
+     *  there is no default, `himi validate` reports an error, and no button is drawn. */
     actionLabel?: string;
+    /** `typography` token for the title. Default `"bodyEmphasis"`. */
+    titleStyle?: string;
+    /** `typography` token for the subtitle. Default `"caption"`. */
+    subtitleStyle?: string;
+    /** The CTA's Button `style`. Default `"secondary"`. */
+    actionStyle?: "primary" | "secondary" | "plain";
+    /** The CTA's Button `size`. Default `"sm"`. */
+    actionSize?: "sm" | "md";
 }
 export interface InterpolatedText {
     template: string;

package/dist/cli.mjs

@@ -10413,6 +10413,41 @@ function mediaFieldFindings(descriptor) {
   visit(descriptor, "", true);
   return out2;
 }
+function emptyStateFindings(descriptor) {
+  const out2 = [];
+  const visit = (v2, path2, atRoot) => {
+    if (Array.isArray(v2)) {
+      v2.forEach((x2, i2) => visit(x2, `${path2}[${i2}]`, false));
+      return;
+    }
+    if (!v2 || typeof v2 !== "object") return;
+    const record2 = v2;
+    const body = record2.body;
+    if (body?.package === "himalaya" && body.type === "EmptyState") {
+      const p2 = body.props ?? {};
+      const base = path2 ? `${path2}.body.props` : "body.props";
+      const label2 = p2.actionLabel;
+      if (p2.action != null && (typeof label2 !== "string" || label2.trim() === "")) {
+        out2.push({
+          path: `${base}.actionLabel`,
+          message: "EmptyState.action is set but EmptyState.actionLabel is missing. There is no default label: the renderers draw no button, so the action is unreachable. Set `actionLabel` to the button text (it is also the accessibility label), or remove `action`"
+        });
+      }
+      if (p2.actionStyle !== void 0 && !(typeof p2.actionStyle === "string" && EMPTY_STATE_ACTION_STYLES.has(p2.actionStyle))) {
+        out2.push({ path: `${base}.actionStyle`, message: `EmptyState.actionStyle must be "primary", "secondary" or "plain", got ${JSON.stringify(p2.actionStyle)}` });
+      }
+      if (p2.actionSize !== void 0 && !(typeof p2.actionSize === "string" && EMPTY_STATE_ACTION_SIZES.has(p2.actionSize))) {
+        out2.push({ path: `${base}.actionSize`, message: `EmptyState.actionSize must be "sm" or "md", got ${JSON.stringify(p2.actionSize)}` });
+      }
+    }
+    for (const [key2, child] of Object.entries(record2)) {
+      if (isOpaqueAuthorJson(key2, child, atRoot)) continue;
+      visit(child, path2 ? `${path2}.${key2}` : key2, false);
+    }
+  };
+  visit(descriptor, "", true);
+  return out2;
+}
 function richTextFieldFindings(descriptor) {
   const out2 = [];
   const visit = (v2, path2, atRoot) => {
@@ -10552,6 +10587,9 @@ function validateScreenDescriptor(screenId, descriptor, opts = {}) {
   for (const finding of richTextFieldFindings(descriptor)) {
     issues.push({ severity: "error", pass: "rich-text-field", path: finding.path, message: finding.message });
   }
+  for (const finding of emptyStateFindings(descriptor)) {
+    issues.push({ severity: "error", pass: "empty-state", path: finding.path, message: finding.message });
+  }
   const bindings = collectServiceBindings(descriptor);
   const descriptorActions = collectDescriptorActions(descriptor);
   const workerActions = descriptorActions.filter(({ actionId }) => actionId.startsWith("tier5."));
@@ -11049,7 +11087,7 @@ function validateScreenDescriptor(screenId, descriptor, opts = {}) {
     services: Object.keys(services)
   };
 }
-var CRAWL_BLOCKING_PASSES, BOOT_EVAL_TIMEOUT_MS, DRIFT_PROBES, DEVICE_PARITY_WITHHELD, defaultEvaluator, bootEvaluator, actionEvaluator, NATIVE_PROP_ENUMS, KNOWN_PROPS, IN_ARRAY_BINDING_PROPS, SERVICE_SIGIL, INTEGER_PROPS, NATIVE_REQUIRED_PROPS, bareNestedClass, NATIVE_NESTED_CLASSES, NATIVE_MODIFIERS_CLASS, NATIVE_DESCRIPTOR_CLASS, NATIVE_DESCRIPTOR_NESTED, NATIVE_NESTED_PROPS, MODIFIER_KEYS, INTEGER_MODIFIERS, MODIFIER_KINDS, SCHEMA_SCORED_NODES, CORE_PACKAGES, LEGACY_UNSCORED_KEYS, DYNAMIC_PLACEHOLDER, LITERAL_ONLY_PROPS, SERVICE_ONLY_BINDING_PROPS, WHOLE_VALUE_BINDING, EMBEDDED_BINDING, OPTIONS_BINDING_PROPS, EDITOR_SERVICE_NAME;
+var CRAWL_BLOCKING_PASSES, BOOT_EVAL_TIMEOUT_MS, DRIFT_PROBES, DEVICE_PARITY_WITHHELD, defaultEvaluator, bootEvaluator, actionEvaluator, NATIVE_PROP_ENUMS, KNOWN_PROPS, IN_ARRAY_BINDING_PROPS, SERVICE_SIGIL, INTEGER_PROPS, NATIVE_REQUIRED_PROPS, bareNestedClass, NATIVE_NESTED_CLASSES, NATIVE_MODIFIERS_CLASS, NATIVE_DESCRIPTOR_CLASS, NATIVE_DESCRIPTOR_NESTED, NATIVE_NESTED_PROPS, MODIFIER_KEYS, INTEGER_MODIFIERS, MODIFIER_KINDS, SCHEMA_SCORED_NODES, CORE_PACKAGES, LEGACY_UNSCORED_KEYS, DYNAMIC_PLACEHOLDER, LITERAL_ONLY_PROPS, SERVICE_ONLY_BINDING_PROPS, WHOLE_VALUE_BINDING, EMBEDDED_BINDING, OPTIONS_BINDING_PROPS, EDITOR_SERVICE_NAME, EMPTY_STATE_ACTION_STYLES, EMPTY_STATE_ACTION_SIZES;
 var init_validate_descriptor_core = __esm({
   "../../core/dev-server/src/validate-descriptor.core.ts"() {
     init_validator();
@@ -11275,7 +11313,17 @@ var init_validate_descriptor_core = __esm({
         slicesPath: "string",
         thickness: "number"
       },
-      EmptyState: { action: "any", actionLabel: "string", icon: "string", subtitle: "string", title: "string" },
+      EmptyState: {
+        action: "any",
+        actionLabel: "string",
+        actionSize: "string",
+        actionStyle: "string",
+        icon: "string",
+        subtitle: "string",
+        subtitleStyle: "string",
+        title: "string",
+        titleStyle: "string"
+      },
       Fab: { action: "any", icon: "string", label: "string", size: "string", tint: "string" },
       FieldError: { severity: "string", text: "string", textPath: "string", visible: "boolean" },
       FilterChips: {
@@ -12006,6 +12054,8 @@ var init_validate_descriptor_core = __esm({
     EMBEDDED_BINDING = /\$service:[A-Za-z0-9_-]+\.[A-Za-z0-9_.[\]]+|\$flag:[A-Za-z0-9_.-]+|\$t:[A-Za-z0-9_.-]+|\$item(?:\.[A-Za-z0-9_.[\]]+)?/;
     OPTIONS_BINDING_PROPS = /* @__PURE__ */ new Set(["optionsPath"]);
     EDITOR_SERVICE_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+    EMPTY_STATE_ACTION_STYLES = /* @__PURE__ */ new Set(["primary", "secondary", "plain"]);
+    EMPTY_STATE_ACTION_SIZES = /* @__PURE__ */ new Set(["sm", "md"]);
   }
 });
 
@@ -18048,6 +18098,73 @@ var init_icon2 = __esm({
   }
 });
 
+// ../native-config/watch-companion.ts
+function watchMode(mode) {
+  if (mode === void 0 || mode === "standalone") return "standalone";
+  if (mode === "companion") return "companion";
+  throw new Error(`native-config: watch.mode must be "standalone" or "companion", got "${mode}"`);
+}
+function parseIosBundleId(configTs) {
+  return /\bbundleId\s*:\s*["']([^"']+)["']/.exec(configTs)?.[1];
+}
+function companionWatchBundleId(iosBundleId) {
+  return `${iosBundleId}.watchkitapp`;
+}
+function requireIosBundleId(iosBundleId) {
+  if (!iosBundleId) {
+    throw new Error(`native-config: watch.mode "companion" needs the app's iOS bundleId in config.ts \u2014 the watch app is paired to it`);
+  }
+  return iosBundleId;
+}
+function watchPairingInfo(mode, iosBundleId) {
+  if (mode === "standalone") return { WKWatchOnly: true };
+  return {
+    WKCompanionAppBundleIdentifier: requireIosBundleId(iosBundleId),
+    // The watch still launches and renders its last/baked content with the phone out of reach.
+    WKRunsIndependentlyOfCompanionApp: true
+  };
+}
+function watchSettingsPlan(mode, iosBundleId, standaloneBundleId) {
+  if (mode === "standalone") {
+    return standaloneBundleId ? { INFOPLIST_KEY_WKWatchOnly: "YES", PRODUCT_BUNDLE_IDENTIFIER: standaloneBundleId } : { INFOPLIST_KEY_WKWatchOnly: "YES" };
+  }
+  return { PRODUCT_BUNDLE_IDENTIFIER: companionWatchBundleId(requireIosBundleId(iosBundleId)) };
+}
+function watchTargetBundleId(watchProjectYml) {
+  return /^\s{4}bundleId:\s*(\S+)\s*$/m.exec(watchProjectYml)?.[1];
+}
+function watchProjectName(watchProjectYml) {
+  return /^name:\s*(\S+)\s*$/m.exec(watchProjectYml)?.[1];
+}
+function watchProjectReferenceLines(mode, watchName) {
+  if (mode === "standalone") return [];
+  return [
+    "projectReferences:",
+    `  ${WATCH_PROJECT_REF}:`,
+    `    path: ../watchos/${watchName}.xcodeproj`
+  ];
+}
+function watchEmbedLines(mode, watchName) {
+  if (mode === "standalone") return [];
+  return [
+    `- target: ${WATCH_PROJECT_REF}/${watchName}`,
+    "  embed: true",
+    "  codeSign: false",
+    "  copy:",
+    "    destination: productsDirectory",
+    "    subpath: $(CONTENTS_FOLDER_PATH)/Watch"
+  ];
+}
+var LABEL_WATCH_SETTINGS, LABEL_WATCH_PROJECT, LABEL_WATCH_EMBED, WATCH_PROJECT_REF;
+var init_watch_companion = __esm({
+  "../native-config/watch-companion.ts"() {
+    LABEL_WATCH_SETTINGS = "himalaya:watch:settings";
+    LABEL_WATCH_PROJECT = "himalaya:watch:project";
+    LABEL_WATCH_EMBED = "himalaya:watch:embed";
+    WATCH_PROJECT_REF = "Watch";
+  }
+});
+
 // ../native-config/live-activity.ts
 function liveWidgetSource(deferredActions) {
   const supportedIds = deferredActions ? "[.refresh, .markRead]" : "[.refresh]";
@@ -18348,15 +18465,16 @@ function parseStringArray(configTs, field) {
   return [...body.matchAll(/["']([^"']+)["']/g)].map((x2) => x2[1]);
 }
 function parseWatchConfig(configTs) {
-  const block = /watch\s*[:=]\s*\{([^}]*)\}/.exec(configTs);
+  const block = /export\s+const\s+watch\s*=\s*\{([^}]*)\}/.exec(configTs) ?? [...configTs.matchAll(/\bwatch\s*[:=]\s*\{([^}]*)\}/g)].find((m2) => /\bmode\s*:/.test(m2[1]));
   if (!block) return {};
   const body = block[1];
   const mode = /mode\s*:\s*["']([^"']+)["']/.exec(body)?.[1];
   const serve = /serve\s*:\s*["']([^"']+)["']/.exec(body)?.[1];
   return { mode, serve };
 }
-function watchInfoPlan(watch2) {
-  const plan = { HimalayaWatchMode: watch2.mode ?? "standalone" };
+function watchInfoPlan(watch2, iosBundleId) {
+  const mode = watchMode(watch2.mode);
+  const plan = { HimalayaWatchMode: mode, ...watchPairingInfo(mode, iosBundleId) };
   if (watch2.serve) plan.HimalayaWatchServe = watch2.serve;
   return plan;
 }
@@ -18599,7 +18717,19 @@ function genNativeConfig(app, opts = {}) {
   }
   const macos = macosPlanFor(ids, withCopy(ov.macos));
   const android = androidPlanFor(ids, ov.android);
-  const watch2 = watchInfoPlan(parseWatchConfig(configTs));
+  const watchConfig = parseWatchConfig(configTs);
+  const iosBundleId = parseIosBundleId(configTs);
+  const watch2 = watchInfoPlan(watchConfig, iosBundleId);
+  const watchYml = watchosProjectYml(app);
+  const watchYmlText = existsSync26(watchYml) ? readFileSync26(watchYml, "utf8") : "";
+  const watchSettings = watchSettingsPlan(watchMode(watchConfig.mode), iosBundleId, watchTargetBundleId(watchYmlText));
+  const watchName = existsSync26(watchYml) ? watchProjectName(readFileSync26(watchYml, "utf8")) : void 0;
+  const watchEmbedFor = (lines) => (indent) => {
+    const mode = watchMode(watchConfig.mode);
+    if (mode === "standalone") return [];
+    if (!watchName) throw new Error(`${app}: watch.mode "companion" but ${watchYml} has no \`name:\` to embed`);
+    return lines(mode, watchName).map((line) => indent + line);
+  };
   const tv = tvInfoPlan(parseTvConfig(configTs));
   const orientation = parseOrientationEnvelope(configTs);
   const carCategory = resolveCarCategory(parseCarConfig(configTs), app);
@@ -18641,6 +18771,10 @@ function genNativeConfig(app, opts = {}) {
     // watchOS (RFC 0047): the watch runtime mode/serve, declared once in config.ts. A watch
     // target opts in by adding the LABEL_WATCH markers; a file without them is skipped.
     applyToFile(watchosProjectYml(app), "yaml", LABEL_WATCH, (i2) => renderPlistYaml(watch2, i2), check),
+    applyToFile(watchosProjectYml(app), "yaml", LABEL_WATCH_SETTINGS, (i2) => renderPlistYaml(watchSettings, i2), check),
+    // #3704 — the iOS half of a companion pair (project reference + embed into <App>.app/Watch).
+    applyToFile(iosProjectYml(app), "yaml", LABEL_WATCH_PROJECT, watchEmbedFor(watchProjectReferenceLines), check),
+    applyToFile(iosProjectYml(app), "yaml", LABEL_WATCH_EMBED, watchEmbedFor(watchEmbedLines), check),
     // tvOS (RFC 0051): HimalayaTvMode managed block; skipped when markers absent.
     applyToFile(tvosProjectYml(app), "yaml", LABEL_TV, (i2) => renderPlistYaml(tv, i2), check),
     // Android TV (RFC 0051 WS7): Leanback features on the `*-tv` module; skipped when markers absent.
@@ -18705,6 +18839,7 @@ var init_gen_native_config = __esm({
     init_paths2();
     init_splash();
     init_icon2();
+    init_watch_companion();
     init_live_activity();
     init_car();
     init_localweb();
@@ -116514,6 +116649,10 @@ function withExtras(name, render) {
   Wrapped.displayName = name;
   return Wrapped;
 }
+function spacingToken(ctx, [name, fallback]) {
+  const v2 = ctx.tokens?.spacing?.[name];
+  return typeof v2 === "number" && Number.isFinite(v2) ? Math.max(0, v2) : fallback;
+}
 function sheetTabStops(root) {
   const all = Array.from(root.querySelectorAll(NATIVELY_TABBABLE)).filter((el2) => el2.tabIndex >= 0 && !el2.disabled && !el2.closest('[inert], [hidden], [aria-hidden="true"]'));
   const ordered = all.filter((el2) => el2.tabIndex > 0).sort((a2, b2) => a2.tabIndex - b2.tabIndex);
@@ -117702,12 +117841,7 @@ function renderInner(node, ctx) {
       return /* @__PURE__ */ jsx9("div", { style: { flex: 1 } });
     }
     case "EmptyState":
-      return /* @__PURE__ */ jsxs6("div", { style: { textAlign: "center", width: "100%", padding: 12, boxSizing: "border-box", ...wrap }, children: [
-        /* @__PURE__ */ jsx9("div", { style: { width: 46, height: 46, borderRadius: 13, background: C2("surfaceTertiary", "#eee"), display: "grid", placeItems: "center", margin: "0 auto 12px", color: C2("textSecondary", "#9aa2ad") }, children: iconSvg(props.icon, { size: 24 }) }),
-        /* @__PURE__ */ jsx9("div", { style: { fontFamily: bodyFont(ctx), fontWeight: 600, fontSize: pxToRem(16), color: C2("textPrimary", "#111") }, children: asBoundText(props.title, ctx) || "Empty" }),
-        props.subtitle && /* @__PURE__ */ jsx9("div", { style: { fontFamily: bodyFont(ctx), fontSize: pxToRem(13), color: C2("textSecondary", "#888"), marginTop: 3 }, children: txt(props.subtitle, ctx) }),
-        actionTextButton(ctx, props.action, asBoundText(props.actionLabel, ctx) || "Take action", accentTextColor(ctx), { margin: "12px auto 0", textAlign: "center" })
-      ] });
+      return /* @__PURE__ */ jsx9(EmptyStateNode, { props, ctx, wrap, nodeId: node.id });
     // ───────────── atoms ─────────────
     case "Text":
       return /* @__PURE__ */ jsx9(TextNode, { props, ctx, wrap });
@@ -118130,7 +118264,7 @@ function renderInner(node, ctx) {
     }
   }
 }
-var useIsomorphicLayoutEffect, ResponsiveGrid, SPLIT_EXPANDED_MIN_WIDTH, SPLIT_COLUMN_GAP, ResponsiveSplitView, ABSOLUTE_URL_RE, appearKeyframesInjected, pressStylesInjected, REVEAL_ON_FOCUS_ATTR, FOCUS_RING_CSS, focusStylesInjected, HLIST_CHILD_CSS, hListStylesInjected, listAnimateRuntimeInstalled, transitionKeyframesInjected, countUpRuntimeInjected, MEASURE_PREFIX, measureRuntimeInjected, revealRuntimeInjected, vectorAnimStylesInjected, scrollProgressRuntimeInjected, confettiRuntimeInjected, lottieRuntimeInjected, riveRuntimeInjected, gradientKeyframesInjected, parallaxRuntimeInjected, spinKeyframesInjected, marqueeKeyframesInjected, alignItems, zJustifyItems, hAlignItems, bodyFont, kids2, rowKidCtx, rowKids, staggeredKids, asTextL10n, asFinalTextL10n, asBoundText, useBoundString, InterpolatedTextView, txt, selectFragmentCase, fragmentValueHash, fragmentSlotContent, FragmentSlotNode, RichContentEditorNode, MediaFieldNode, WorkerSubtreeNode, RichContentNode, resolveItemDeep2, resolveSwipeActions, resolveModBindings, resolvedComponentId, directServiceBindings, withRootStyle, ReactiveDirectScalars, HiddenGate, KEYBOARD_INPUT_MODES, AUTOCAPITALIZE_VALUES, ENTER_KEY_HINTS, AUTOGROW_CEILING, EditableField, MenuNode, LoadMoreSentinel, FieldErrorNode, FormView, MediaSlotProvider, MEDIA_ITEM_BINDABLE, MediaPlayerView, VideoNode, PdfDocumentCanvas, PdfViewNode, WebViewNode, InteractivePicker, InteractiveDatePicker, InteractiveSearchField, InteractiveStepper, SYNTHETIC_TAP_ROLE, SYNTHETIC_TABINDEX, INFERRED_DECORATIVE, SELF_RENDERED_LEAF, ROLE_WHEN_NAMED, AUTHORED_ROLE, PENDING_RANGE, RANGE_ROLES, NODE_A11Y_ATTRS, INTERACTIVE_ROLES, ALWAYS_INTERACTIVE_COMPONENT_TYPES, TAP_ACTIVATOR_ATTR, TAP_GROUP_ATTR, VISUALLY_HIDDEN, NAME_SKIP_SELECTOR, activatorNameObservers, ACTIVATOR_STATE_ATTRS, controlNode, ToggleNode, SliderNode, SelectionControlNode, TabsNode, SegmentedControlNode, DisclosureGroupNode, GridNode, SplitViewNode, TextNode, ImageNode, ANIMATION_LEAF, LottieNode, RiveNode, AvatarNode, IconNode, ButtonNode, OtpInputNode, ProgressBarNode, ACTIVITY_DEFAULT_NAME, ActivityIndicatorNode, NATIVELY_TABBABLE, BottomSheetNode, PRESENTED_OVERLAY_ATTR, PopoverNode, ChipsInputNode, ChipNode, TableNode, GaugeRing, GaugeNode, RATING_METRICS, ratingMetrics, RatingNode, AvatarStripNode, CHART_STROKE_CYCLE, chartStrokeAt, chartBarCenter, ChartNode, donutSliceOpacity, DonutChartNode, LegendMarker, LegendNode, cellAlign, DataTableNode, voiceNoteState, voiceNoteDelivery, VOICE_NOTE_DEFAULT_BARS, clampBarCount, VoiceNoteNode, TimelineNode, WheelPickerNode, ColorPickerNode, FilterChipsNode, TILE_PX, MAX_MERCATOR_LAT, DEFAULT_TILE_MAX_ZOOM, CIRCLE_SEGMENTS, METRES_PER_DEG_LAT, MARKER_HIT_RADIUS, SHAPE_HIT_RADIUS, MapNode, CollapsingHeaderNode, UnsupportedOnSurface, CALENDAR_DATE_ONLY_RE, CAL_DEFAULT_MAX_DOTS, CAL_AGENDA_INITIAL_DAYS, CAL_AGENDA_PAGE_DAYS, CAL_DEFAULT_SNAP_MINUTES, CAL_UNASSIGNED_LANE_ID, MonthCalendarNode, TimeGridNode, AgendaNode, ARIA_ROLE, initialFocusScheduled, PRESENTED_SCOPE, focusRoots, A11yHintDescription, WebRenderer;
+var useIsomorphicLayoutEffect, ResponsiveGrid, SPLIT_EXPANDED_MIN_WIDTH, SPLIT_COLUMN_GAP, ResponsiveSplitView, ABSOLUTE_URL_RE, appearKeyframesInjected, pressStylesInjected, REVEAL_ON_FOCUS_ATTR, FOCUS_RING_CSS, focusStylesInjected, HLIST_CHILD_CSS, hListStylesInjected, listAnimateRuntimeInstalled, transitionKeyframesInjected, countUpRuntimeInjected, MEASURE_PREFIX, measureRuntimeInjected, revealRuntimeInjected, vectorAnimStylesInjected, scrollProgressRuntimeInjected, confettiRuntimeInjected, lottieRuntimeInjected, riveRuntimeInjected, gradientKeyframesInjected, parallaxRuntimeInjected, spinKeyframesInjected, marqueeKeyframesInjected, alignItems, zJustifyItems, hAlignItems, bodyFont, kids2, rowKidCtx, rowKids, staggeredKids, asTextL10n, asFinalTextL10n, asBoundText, useBoundString, InterpolatedTextView, txt, selectFragmentCase, fragmentValueHash, fragmentSlotContent, FragmentSlotNode, RichContentEditorNode, MediaFieldNode, WorkerSubtreeNode, RichContentNode, resolveItemDeep2, resolveSwipeActions, resolveModBindings, resolvedComponentId, directServiceBindings, withRootStyle, ReactiveDirectScalars, HiddenGate, KEYBOARD_INPUT_MODES, AUTOCAPITALIZE_VALUES, ENTER_KEY_HINTS, AUTOGROW_CEILING, EditableField, MenuNode, LoadMoreSentinel, FieldErrorNode, FormView, MediaSlotProvider, MEDIA_ITEM_BINDABLE, MediaPlayerView, VideoNode, PdfDocumentCanvas, PdfViewNode, WebViewNode, InteractivePicker, InteractiveDatePicker, InteractiveSearchField, InteractiveStepper, SYNTHETIC_TAP_ROLE, SYNTHETIC_TABINDEX, INFERRED_DECORATIVE, SELF_RENDERED_LEAF, ROLE_WHEN_NAMED, AUTHORED_ROLE, PENDING_RANGE, RANGE_ROLES, NODE_A11Y_ATTRS, INTERACTIVE_ROLES, ALWAYS_INTERACTIVE_COMPONENT_TYPES, TAP_ACTIVATOR_ATTR, TAP_GROUP_ATTR, VISUALLY_HIDDEN, NAME_SKIP_SELECTOR, activatorNameObservers, ACTIVATOR_STATE_ATTRS, controlNode, ToggleNode, SliderNode, SelectionControlNode, TabsNode, SegmentedControlNode, DisclosureGroupNode, GridNode, SplitViewNode, TextNode, ImageNode, ANIMATION_LEAF, LottieNode, RiveNode, AvatarNode, IconNode, EMPTY_STATE_SPACING, EmptyStateNode, ButtonNode, OtpInputNode, ProgressBarNode, ACTIVITY_DEFAULT_NAME, ActivityIndicatorNode, NATIVELY_TABBABLE, BottomSheetNode, PRESENTED_OVERLAY_ATTR, PopoverNode, ChipsInputNode, ChipNode, TableNode, GaugeRing, GaugeNode, RATING_METRICS, ratingMetrics, RatingNode, AvatarStripNode, CHART_STROKE_CYCLE, chartStrokeAt, chartBarCenter, ChartNode, donutSliceOpacity, DonutChartNode, LegendMarker, LegendNode, cellAlign, DataTableNode, voiceNoteState, voiceNoteDelivery, VOICE_NOTE_DEFAULT_BARS, clampBarCount, VoiceNoteNode, TimelineNode, WheelPickerNode, ColorPickerNode, FilterChipsNode, TILE_PX, MAX_MERCATOR_LAT, DEFAULT_TILE_MAX_ZOOM, CIRCLE_SEGMENTS, METRES_PER_DEG_LAT, MARKER_HIT_RADIUS, SHAPE_HIT_RADIUS, MapNode, CollapsingHeaderNode, UnsupportedOnSurface, CALENDAR_DATE_ONLY_RE, CAL_DEFAULT_MAX_DOTS, CAL_AGENDA_INITIAL_DAYS, CAL_AGENDA_PAGE_DAYS, CAL_DEFAULT_SNAP_MINUTES, CAL_UNASSIGNED_LANE_ID, MonthCalendarNode, TimeGridNode, AgendaNode, ARIA_ROLE, initialFocusScheduled, PRESENTED_SCOPE, focusRoots, A11yHintDescription, WebRenderer;
 var init_renderNode = __esm({
   "../../core/web-renderer/src/renderNode.tsx"() {
     "use strict";
@@ -120212,6 +120346,49 @@ var init_renderNode = __esm({
       const a11y = described ? { role: "img", "aria-label": String(contentDescription), [SELF_RENDERED_LEAF]: true } : { "aria-hidden": "true", [INFERRED_DECORATIVE]: true, [SELF_RENDERED_LEAF]: true, [ROLE_WHEN_NAMED]: "img" };
       return /* @__PURE__ */ jsx9("span", { ...a11y, style: { display: "inline-grid", placeItems: "center", width: size + 6, height: size + 6, lineHeight: 1, flex: "none", ...wrap }, children: iconSvg(iconName, { size, color: C2(resolveScalarStatic(props.tint, ctx) ?? "textPrimary", "#636b78") }) });
     });
+    EMPTY_STATE_SPACING = {
+      padding: ["lg", 16],
+      iconGap: ["md", 12],
+      subtitleGap: ["xs", 4],
+      actionGap: ["lg", 16]
+    };
+    EmptyStateNode = withExtras("EmptyStateNode", ({ props, ctx, wrap, nodeId }) => {
+      const C2 = ctx.color;
+      const subtitleText = useBoundString(props.subtitle, ctx);
+      const titleFont = ctx.font(typeof props.titleStyle === "string" && props.titleStyle ? props.titleStyle : "bodyEmphasis");
+      const subtitleFont = ctx.font(typeof props.subtitleStyle === "string" && props.subtitleStyle ? props.subtitleStyle : "caption");
+      const fontCss = (f2) => ({
+        fontFamily: fontStack(f2.family, ctx.idiom),
+        fontSize: f2.remSize,
+        fontWeight: f2.weight,
+        lineHeight: f2.line,
+        letterSpacing: f2.letterSpacing
+      });
+      const hasIcon2 = typeof props.icon === "string" ? props.icon.length > 0 : props.icon != null;
+      const hasSubtitle = subtitleText.trim().length > 0;
+      const label2 = props.actionLabel;
+      const hasAction = props.action != null && typeof label2 === "string" && label2.trim().length > 0;
+      const padding = spacingToken(ctx, EMPTY_STATE_SPACING.padding);
+      return /* @__PURE__ */ jsxs6("div", { style: { display: "flex", flexDirection: "column", alignItems: "center", textAlign: "center", width: "100%", padding, boxSizing: "border-box", ...wrap }, children: [
+        hasIcon2 && /* @__PURE__ */ jsx9("div", { "data-empty-state-part": "icon", "aria-hidden": "true", style: { width: 46, height: 46, borderRadius: 13, background: C2("surfaceTertiary", "#eee"), display: "grid", placeItems: "center", color: C2("textSecondary", "#9aa2ad"), flexShrink: 0 }, children: iconSvg(props.icon, { size: 24 }) }),
+        /* @__PURE__ */ jsx9("div", { "data-empty-state-part": "title", style: { ...fontCss(titleFont), color: C2("textPrimary", "#111"), marginTop: hasIcon2 ? spacingToken(ctx, EMPTY_STATE_SPACING.iconGap) : 0, overflowWrap: "anywhere" }, children: txt(props.title, ctx) }),
+        hasSubtitle && /* @__PURE__ */ jsx9("div", { "data-empty-state-part": "subtitle", style: { ...fontCss(subtitleFont), color: C2("textSecondary", "#888"), marginTop: spacingToken(ctx, EMPTY_STATE_SPACING.subtitleGap), overflowWrap: "anywhere" }, children: isBinding(props.subtitle) ? subtitleText : txt(props.subtitle, ctx) }),
+        hasAction && /* @__PURE__ */ jsx9("div", { "data-empty-state-part": "action", style: { marginTop: spacingToken(ctx, EMPTY_STATE_SPACING.actionGap), display: "flex", justifyContent: "center" }, children: renderNode({
+          id: `${nodeId ?? "empty_state"}.action`,
+          body: {
+            package: "himalaya",
+            type: "Button",
+            props: {
+              title: label2,
+              action: props.action,
+              style: props.actionStyle ?? "secondary",
+              size: props.actionSize ?? "sm",
+              fullWidth: false
+            }
+          }
+        }, { ...ctx, rowStretch: false }) })
+      ] });
+    });
     ButtonNode = withExtras("ButtonNode", ({ props, ctx, wrap }) => {
       const C2 = ctx.color;
       const boundTitle = useResolvedScalar(isBinding(props.title) ? props.title : void 0, ctx);
@@ -143473,23 +143650,23 @@ var init_preview_assets_generated = __esm({
   "../../packages/serve/src/preview-assets.generated.ts"() {
     init_preview_assets_format();
     PREVIEW_ASSET_MANIFEST = [
-      { key: "assets/index-foA0ySYi.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 1191112, sha256: "18d4cc6a89df036267a88103f1c3a1e2bed96cfc78926bf48dc0c2c9b637546d" },
-      { key: "assets/pdf.worker.min-BmVo14Nb.mjs", contentType: "application/octet-stream", offset: 1191120, length: 1317034, sha256: "a33cfe728c584fdba4fcc1fd54bcdc2f9f2f13889ddbb5b2bd1d0f8cbe49b84e" },
-      { key: "assets/pdfDocument-mwaz-XmD.js", contentType: "application/javascript; charset=utf-8", offset: 2508154, length: 489166, sha256: "709898ff6336a208e677fff9def67063adaa4605492c81597468199e4968d2d3" },
-      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 2997320, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
-      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 3001930, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
-      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 3490514, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
-      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 3581438, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
-      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 3672422, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
-      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 3763402, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
-      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 3854274, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
-      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 3945254, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
-      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 4053890, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
-      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 4162974, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
-      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 4272022, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
-      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 4379722, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
-      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 4467830, length: 4947, sha256: "58a871eb4e920e5f620d7cbe850b1418ac1cd3e08746145666cad95e2dcb9fd9" },
-      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 4472777, length: 17344, sha256: "d057298d75e7373e5e2c4d11b7d1bcbea88e03af555ba63d97641c78509c58e4" }
+      { key: "assets/index-BZS8K4zM.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 1192364, sha256: "50d2524148ee0aedb74e5e6a548f269eb75b4a289f7a1de101de410c01e60bf5" },
+      { key: "assets/pdf.worker.min-BmVo14Nb.mjs", contentType: "application/octet-stream", offset: 1192372, length: 1317034, sha256: "a33cfe728c584fdba4fcc1fd54bcdc2f9f2f13889ddbb5b2bd1d0f8cbe49b84e" },
+      { key: "assets/pdfDocument-PXxklXbm.js", contentType: "application/javascript; charset=utf-8", offset: 2509406, length: 489166, sha256: "6df079a4bd8eaa2ed5abfb4af8154f2a4c0b8283fb26e1ef2f1964c2d7b6d1ac" },
+      { key: "fonts/Roboto-LICENSE.txt", contentType: "application/octet-stream", offset: 2998572, length: 4610, sha256: "994062dd7af4186a739de55dd9e151c63b6301f8e2cbafc608d35c2e87da0cd2" },
+      { key: "fonts/Roboto-Variable.ttf", contentType: "font/ttf", offset: 3003182, length: 488584, sha256: "d7598e12c5dbef095ff8272cfc55da0250bd07fbdecbac8a530b9b277872a134" },
+      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 3491766, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
+      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 3582690, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
+      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 3673674, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
+      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 3764654, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
+      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 3855526, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
+      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 3946506, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
+      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 4055142, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
+      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 4164226, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
+      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 4273274, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
+      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 4380974, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
+      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 4469082, length: 4947, sha256: "ec96c9af3b4b5bf3113b3ef80c4a6f16b77f40e28903dd20813ce866207e145d" },
+      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 4474029, length: 17344, sha256: "d057298d75e7373e5e2c4d11b7d1bcbea88e03af555ba63d97641c78509c58e4" }
     ];
   }
 });

package/guides/component-reference.json

@@ -98,7 +98,7 @@
       "category": "Core",
       "propsType": "EmptyStateProps",
       "bindings": [],
-      "propsSource": "export interface EmptyStateProps {\n  title: string;\n  subtitle?: string;\n  icon?: IconRef;\n  action?: Action;\n  /** #1059 — CTA label; overridable for localized hosts. Default \"Take action\". */\n  actionLabel?: string;\n}"
+      "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": "Text",

package/guides/component-reference.md

@@ -396,9 +396,19 @@ export interface EmptyStateProps {
   title: string;
   subtitle?: string;
   icon?: IconRef;
+  /** The CTA. Drawn as a real `Button` (see `actionStyle` / `actionSize`). */
   action?: Action;
-  /** #1059 — CTA label; overridable for localized hosts. Default "Take action". */
+  /** #1059 — CTA label, also its accessibility label. REQUIRED when `action` is set:
+   *  there is no default, `himi validate` reports an error, and no button is drawn. */
   actionLabel?: string;
+  /** `typography` token for the title. Default `"bodyEmphasis"`. */
+  titleStyle?: string;
+  /** `typography` token for the subtitle. Default `"caption"`. */
+  subtitleStyle?: string;
+  /** The CTA's Button `style`. Default `"secondary"`. */
+  actionStyle?: "primary" | "secondary" | "plain";
+  /** The CTA's Button `size`. Default `"sm"`. */
+  actionSize?: "sm" | "md";
 }
 ```
 

package/guides/designing-himi-screens.md

@@ -331,7 +331,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. |
-| **Empty** | `EmptyState` (`title`, `subtitle`, `icon`) **plus a directive action** | An empty screen is an invitation to act, not a dead end — give it the next step (e.g. "Add your first item"). **Caveat:** `EmptyState`'s `action` renders a generic **"Take action"** button label (no field to set the wording). When the CTA text matters ("Clear filters", "Add your first item"), compose a *custom* empty block instead — a centered `icon` + `title` text + `caption` subtitle + a real labeled `button` — rather than the `EmptyState` component. |
+| **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. |
 
@@ -340,12 +340,43 @@ 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.)
 
+### Empty states: one component, one layout
+
+`EmptyState` draws one standard layout on iOS, Android, macOS and web. Do not build an empty
+state by hand from `Icon`, `Text` and `Button` nodes.
+
+- The layout is a centred vertical stack, in this order: icon tile, title, subtitle, button.
+- Only `title` is required. `icon`, `subtitle` and the button are optional. A missing part
+  takes no space.
+- The title uses the `typography` token in `titleStyle`. The default is `bodyEmphasis`.
+- The subtitle uses the `typography` token in `subtitleStyle`. The default is `caption`.
+- The padding and the gaps come from the `spacing` tokens `lg`, `md` and `xs`.
+- The button is a real `Button`. It uses the app's button tokens. Set `actionStyle`
+  (`primary`, `secondary` or `plain`) and `actionSize` (`sm` or `md`). The defaults are
+  `secondary` and `sm`.
+- `actionLabel` is the button text and its accessibility label. It has no default. If you set
+  `action` without `actionLabel`, `himi validate` shows an error and no button is drawn.
+
+```jsonc
+{ "id": "saved.empty",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "icon": "bookmark", "title": "No saved items",
+               "subtitle": "Save a product to see it here.", "subtitleStyle": "footnoteRegular",
+               "action": { "actionId": "himi.open", "params": { "screenId": "shop" } },
+               "actionLabel": "Browse products" } },
+  "modifiers": { "hiddenPath": "$service:saved.notEmpty" } }
+```
+
+To show the empty state only when the list is empty, bind `hiddenPath` to a worker boolean
+(see `himi docs recipe-four-state`). Write the title and the subtitle as literal copy or as
+`$t:` keys. Today, iOS and Android do not resolve a `$service:` binding in `title` or `subtitle`.
+
 **Loading & empty states are first-class — use the `Skeleton` and `EmptyState` component types.**
 
 There is **no builder-DSL package** — the `@wix/himalaya` umbrella exposes `./core`, `./state`,
 `wix-*`, … but no `skRect` / `emptyBlock` helpers. Author these states as the **raw descriptor
 nodes** `himi init` scaffolds: a `Skeleton` node for loading, and an `EmptyState` node (`icon` +
-`title`/`subtitle` + a labeled `cta`) for empty. Run `himi components EmptyState` /
+`title`/`subtitle` + `action` with its `actionLabel`) for empty. Run `himi components EmptyState` /
 `himi components Skeleton` for the exact props. Written as raw nodes, these states ship over the
 air and render on every current binary.
 

package/guides/recipe-four-state.md

@@ -5,7 +5,8 @@ from **one flat layout** — no conditional trees, no separate loading screen. T
 worker computes a **display string per state** (non-empty only in its state) and
 the descriptor binds each to a `Text` with `collapseWhenEmpty: true`. Sections
 that must fully appear/disappear gate with the `hiddenWhen`/`hiddenPath` modifier
-bound to a worker boolean.
+bound to a worker boolean. The empty state is always an `EmptyState` node, gated
+the same way.
 
 This is the corpus norm: of the in-repo worker bundles, ~3 in 4 model loading,
 more than half model error, and the reference apps (`apps/himi-owner-lite`,
@@ -19,8 +20,8 @@ interface State {
   status: "loading" | "ready" | "error";
   items: Row[];
   loadingText: string;   // "Loading…"        only while loading
-  emptyText: string;     // "No products yet." only when ready + 0 rows
   error: string;         // the message        only when failed
+  notEmpty: boolean;     // gates the EmptyState (hiddenPath hides when TRUE)
   notErrored: boolean;   // gates the Retry button (hiddenPath hides when TRUE)
 }
 
@@ -30,24 +31,29 @@ function shape(s: Partial<State>): State {
   return {
     status, items,
     loadingText: status === "loading" ? "Loading products…" : "",
-    emptyText: status === "ready" && items.length === 0 ? "No products in this store yet." : "",
     error: s.error ?? "",
+    notEmpty: !(status === "ready" && items.length === 0),
     notErrored: status !== "error",
   };
 }
 ```
 
 Route **every** state change through `shape()` — set `status` + raw data, let it
-recompute the strings. Hand-maintaining the strings per action is how screens end
-up loading-and-errored at once.
+recompute the strings and flags. Hand-maintaining them per action is how screens
+end up loading-and-errored at once.
 
-## 2. The descriptor: one Text per state + a gated Retry
+## 2. The descriptor: one node per state + a gated Retry
 
 ```jsonc
 { "id": "loading", "…Text": { "text": "$service:products.loadingText",
     "color": "textSecondary", "collapseWhenEmpty": true } },
-{ "id": "empty",   "…Text": { "text": "$service:products.emptyText",
-    "color": "textSecondary", "collapseWhenEmpty": true } },
+{ "id": "empty",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "icon": "bag", "title": "No products in this store yet",
+               "subtitle": "Add a product to see it here.",
+               "action": { "actionId": "tier5.products.create" },
+               "actionLabel": "Add your first product" } },
+  "modifiers": { "hiddenPath": "$service:products.notEmpty" } },
 { "id": "error",   "…Text": { "text": "$service:products.error",
     "color": "danger", "collapseWhenEmpty": true } },
 { "id": "retry",
@@ -64,6 +70,13 @@ up loading-and-errored at once.
   the binding reads without negation.
 - Ready state is simply the data itself (the list rows, the detail fields) — it
   needs no dedicated marker.
+- **Use `EmptyState` for every empty state.** It draws one standard layout on
+  every platform: icon, title, subtitle and button, with type and gaps from the
+  app's tokens. Only `title` is required. `actionLabel` is required when you set
+  `action`: there is no default label, and `himi validate` reports a missing one.
+- Write the `EmptyState` title and subtitle as literal copy or `$t:` keys. Today,
+  iOS and Android do not resolve a `$service:` binding in those props, so gate the
+  node with `hiddenPath` instead of binding its text.
 
 ## 3. Which state when
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1237.0",
+  "version": "0.1238.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": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "c18693816eefde3cc9259c9dd46e8deaffa629c1762386017a0ea310"
+  "falconPackageHash": "fa100c156434113a7befa8bdb97c6f87ee57d27d3e088aa3b2a9752c"
 }