@wix/himalaya-cli 0.848.0 → 0.850.0

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

@@ -253,6 +253,34 @@ export declare function surfaceById(id: string): PreviewSurface | undefined;
  * claim a family allowlist and then be served live bindings.
  */
 export type SurfaceRenderMode = "frozen" | "interactive";
+/**
+ * The widget family a FROZEN surface publishes under, for DISPLAY — or undefined for
+ * an interactive app shell.
+ *
+ * Both gate kinds that mean "frozen" carry a family: `family` because it IS the
+ * allowlist key, `projection` because the car still ships its tree under one
+ * (`car_list`). That makes this the right thing to name a surface by in a message, and
+ * the WRONG thing to branch on — a car and a widget are authored through different
+ * doors. Decisions use `isWidgetFamilySurface` below.
+ */
+export declare function surfaceFrozenFamily(surface: PreviewSurface): string | undefined;
+/**
+ * Is this surface an OS widget — the `defineWidget` population, as distinct from the
+ * car, which is frozen too?
+ *
+ * Named and shared rather than spelled `gate.kind === "family"` at each call site,
+ * because the two places that ask (`surfacesForApp`'s produced verdict, and
+ * `himi render --device`'s refusal) must give the same answer or #2499 comes back
+ * halfway: a surface one of them classes as a widget and the other does not is either
+ * advertised as supported while unrenderable, or refused with advice pointing at a
+ * door it was not authored through.
+ *
+ * The car is excluded deliberately, not incidentally. It is authored with
+ * `defineView({ surface: "car" })`, gated by a real `androidauto` key (so it never
+ * over-claimed), and its viewport exists for the preview — so `defineWidget` advice and
+ * a `/v1/widget/<id>` pointer would both be dead ends for it.
+ */
+export declare function isWidgetFamilySurface(surface: PreviewSurface): boolean;
 export declare function surfaceRenderMode(surface: PreviewSurface): SurfaceRenderMode;
 /**
  * Ladder rungs that are not themselves surfaces — the shared fallbacks a view can
@@ -316,15 +344,48 @@ export declare function isTargeted(surface: PreviewSurface, platforms: Platforms
 export interface SurfaceAvailability {
     readonly surface: PreviewSurface;
     readonly targeted: boolean;
-    /** When not targeted, the exact opt-in to add. Drives the picker's tooltip. */
+    /** When not targeted because of the BINARY envelope, the exact platforms.json
+     *  opt-in to add. Drives the picker's tooltip. Absent for a widget family that
+     *  is untargeted for lack of a widget — no platforms.json key opts that in. */
     readonly optIn?: string;
+    /**
+     * For a WIDGET FAMILY (`isWidgetFamilySurface`) — does this app actually PRODUCE a
+     * snapshot for it? Only present when the caller supplied the produced set;
+     * `undefined` means "not measured", which is not the same as `false` and must not be
+     * rendered as one.
+     *
+     * Widget families and NOTHING else, the car included — it is frozen too, but it is
+     * gated by a real `androidauto` key (so it never over-claimed) and is authored with
+     * `defineView({ surface: "car" })`, so a `defineWidget`-shaped verdict would be the
+     * wrong answer rather than a missing one. An app shell has nothing to produce at all.
+     */
+    readonly produced?: boolean;
+    /** When a widget family is untargeted because nothing produces it, what to author. */
+    readonly needs?: string;
 }
 /**
  * The full catalog with a targeted flag — NOT a filtered list. The picker shows
  * every surface and dims the untargeted ones, so authors discover what their app
  * could also be, instead of only seeing what it already is.
+ *
+ * `producedFamilies` — the widget families this app actually produces a snapshot for
+ * (`GET /v1/widgets`, or a scan of its built bundles). Supply it and a frozen surface
+ * reports the truth; omit it and the answer is the binary envelope alone, as before.
+ *
+ * Why it exists (#2499): the four native widget families carry `platformKey: null`
+ * (`web_card` and `watch_complication` are the exceptions — they ride `web`/`watchos`),
+ * so for those four `isTargeted` short-circuits to `true` and `himi surfaces` reported
+ * `widget:ios_home`, `widget:ios_lock`, `widget:android_home` and
+ * `widget:ios_live_activity` as targeted for EVERY app — declared widgets or not.
+ * A tester read that as support, found
+ * `/v1/widgets` empty, and summarized it as "everything advertises the capability
+ * except the capability". The envelope answer was not wrong so much as answering a
+ * different question: iOS and Android are implicit, so the binary CAN host a widget;
+ * whether this app HAS one is a fact about its bundles, and only the produced set
+ * carries it. `isTargeted` is deliberately left alone — `resolveSurfaceEnvelope` asks
+ * the binary question and must keep getting the binary answer.
  */
-export declare function surfacesForApp(platforms: PlatformsJson): readonly SurfaceAvailability[];
+export declare function surfacesForApp(platforms: PlatformsJson, producedFamilies?: Iterable<string>): readonly SurfaceAvailability[];
 export interface SurfaceEnvelopeResolution {
     /** Surfaces this app actually runs, in catalog order. */
     readonly enabled: readonly string[];

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/core.mjs

@@ -9232,6 +9232,13 @@ var PREVIEW_SURFACES = [
 function surfaceById(id) {
   return PREVIEW_SURFACES.find((s) => s.id === id);
 }
+function surfaceFrozenFamily(surface) {
+  const gate = surface.gate;
+  return gate.kind === "family" || gate.kind === "projection" ? gate.family : void 0;
+}
+function isWidgetFamilySurface(surface) {
+  return surface.gate.kind === "family";
+}
 function surfaceRenderMode(surface) {
   const { kind } = surface.gate;
   return kind === "family" || kind === "projection" ? "frozen" : "interactive";
@@ -9295,10 +9302,33 @@ function isTargeted(surface, platforms) {
   if (surface.platformKey === "macos") return platforms.macos !== false;
   return platforms[surface.platformKey] === true;
 }
-function surfacesForApp(platforms) {
+function surfacesForApp(platforms, producedFamilies) {
+  const produced = producedFamilies === void 0 ? void 0 : producedFamilies instanceof Set ? producedFamilies : new Set(producedFamilies);
   return PREVIEW_SURFACES.map((surface) => {
-    const targeted = isTargeted(surface, platforms);
-    return targeted ? { surface, targeted } : { surface, targeted, optIn: `"${surface.platformKey}": true` };
+    const inEnvelope = isTargeted(surface, platforms);
+    const family = isWidgetFamilySurface(surface) ? surfaceFrozenFamily(surface) : void 0;
+    if (produced && family !== void 0) {
+      const isProduced = produced.has(family);
+      return inEnvelope && isProduced ? { surface, targeted: true, produced: true } : {
+        surface,
+        targeted: false,
+        produced: isProduced,
+        // The four native families carry no platform key, so there is nothing to
+        // offer; `web_card` and `watch_complication` DO have one, and when that is
+        // the half that is missing it is still the right advice. Hence the guard —
+        // it is load-bearing for two families, not defensive padding.
+        ...inEnvelope ? {} : surface.platformKey ? { optIn: `"${surface.platformKey}": true` } : {},
+        ...isProduced ? {} : {
+          // The rebuild half is not padding: the produced set is read off BUILT
+          // bundles, so an author who has just written the registration and not
+          // rebuilt lands here too, and "write defineWidget" alone would be advice
+          // to write the code they are looking at.
+          needs: `defineWidget({ family: "${family}", \u2026 }) in a Tier-5 bundle \u2014 and a rebuild, if you just added it`
+        }
+      };
+    }
+    if (inEnvelope) return { surface, targeted: true };
+    return surface.platformKey ? { surface, targeted: false, optIn: `"${surface.platformKey}": true` } : { surface, targeted: false };
   });
 }
 function resolveSurfaceEnvelope(platforms, requested) {
@@ -12814,6 +12844,7 @@ export {
   isValidAppId,
   isValidStreamPolicy,
   isViewTarget,
+  isWidgetFamilySurface,
   layoutDirection,
   parseNumeric,
   primarySubtag,
@@ -12834,6 +12865,7 @@ export {
   stripOriginParams,
   summarize,
   surfaceById,
+  surfaceFrozenFamily,
   surfaceRenderMode,
   surfacesForApp,
   validate,