@wix/himalaya-cli 0.849.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,

package/dist/cli.mjs

@@ -1763,6 +1763,13 @@ var init_widget_vocabulary = __esm({
 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";
@@ -1787,10 +1794,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) {
@@ -3239,6 +3269,13 @@ var init_build_lib = __esm({
 });
 
 // ../../core/dev-server/src/tier5-dir.ts
+var tier5_dir_exports = {};
+__export(tier5_dir_exports, {
+  bundleOutDir: () => bundleOutDir,
+  hasBuiltBundles: () => hasBuiltBundles,
+  servedBundleName: () => servedBundleName,
+  servedBundleNames: () => servedBundleNames
+});
 import { readdirSync as readdirSync7 } from "node:fs";
 import { resolve as resolve9 } from "node:path";
 function bundleOutDir(contentDir2) {
@@ -3251,6 +3288,25 @@ function hasBuiltBundles(contentDir2) {
     return false;
   }
 }
+function servedBundleName(fileName) {
+  if (fileName.endsWith(".bundle.js")) return fileName.slice(0, -".bundle.js".length);
+  if (fileName.endsWith(".js")) return fileName.slice(0, -".js".length);
+  return void 0;
+}
+function servedBundleNames(dir) {
+  const names = /* @__PURE__ */ new Set();
+  let entries;
+  try {
+    entries = readdirSync7(dir);
+  } catch {
+    return names;
+  }
+  for (const entry of entries) {
+    const name = servedBundleName(entry);
+    if (name !== void 0) names.add(name);
+  }
+  return names;
+}
 var init_tier5_dir = __esm({
   "../../core/dev-server/src/tier5-dir.ts"() {
   }
@@ -4689,7 +4745,6 @@ function resolveTranslation(value, catalog, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
-    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s) => s !== "t").join("|")})\\b|^\\$t:`
@@ -26427,7 +26482,6 @@ function shouldRevealError(args) {
 var EMAIL_RE, URL_HOST_RE, INTEGER_RE, NUMBER_RE;
 var init_validation = __esm({
   "../../core/ts/src/validation.ts"() {
-    "use strict";
     EMAIL_RE = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}$/;
     URL_HOST_RE = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(:[0-9]+)?$/;
     INTEGER_RE = /^[+-]?[0-9]+$/;
@@ -29823,7 +29877,6 @@ function validateWorkerSubtree(raw, slotId, policy, actionCatalog) {
 var WORKER_SUBTREE_CEILINGS, ID_PART, ACTION_ID;
 var init_worker_subtree = __esm({
   "../../core/ts/src/worker-subtree.ts"() {
-    "use strict";
     init_worker_subtree_safe_types_generated();
     WORKER_SUBTREE_CEILINGS = Object.freeze({
       maxEncodedBytes: 65536,
@@ -36651,6 +36704,16 @@ var init_kits = __esm({
 });
 
 // ../../core/dev-server/src/widgets.ts
+var widgets_exports = {};
+__export(widgets_exports, {
+  buildViewSnapshot: () => buildViewSnapshot,
+  buildWidgetSnapshot: () => buildWidgetSnapshot,
+  describeThrown: () => describeThrown,
+  extractWidgets: () => extractWidgets,
+  freezeOverrideSnapshot: () => freezeOverrideSnapshot,
+  frozenViewManifestEntries: () => frozenViewManifestEntries,
+  viewWidgetId: () => viewWidgetId
+});
 import { createHash as createHash14 } from "node:crypto";
 import { inspect } from "node:util";
 import { runInNewContext } from "node:vm";
@@ -38698,7 +38761,7 @@ async function handleDev(req, res, state) {
     if (req.method === "POST") return await handleWidgetPushPreview(req, res, state);
     const widgetId = new URL(url, "http://localhost").searchParams.get("widgetId");
     if (req.method === "DELETE") return await handleWidgetClearPreview(res, state, widgetId);
-    return await handleWidgetPreview(res, widgetId);
+    return await handleWidgetPreview(res, widgetId, state.tier5Dir);
   }
   if (url === "/__dev/seed") {
     const seed2 = state.app.module.seed;
@@ -39319,9 +39382,8 @@ async function listBundles(dir) {
       continue;
     }
     for (const entry of entries) {
-      if (entry.endsWith(".bundle.js") || entry.endsWith(".js")) {
-        names.add(entry.replace(/\.bundle\.js$|\.js$/, ""));
-      }
+      const name = servedBundleName(entry);
+      if (name !== void 0) names.add(name);
     }
   }
   const result = [];
@@ -39348,14 +39410,14 @@ async function handleBundleGet(res, name, dir) {
   res.statusCode = 200;
   res.end(loaded.bytes);
 }
-async function scanWidgets() {
+async function scanWidgets(dir) {
   const out = [];
   const seen = /* @__PURE__ */ new Set();
   const emitted = /* @__PURE__ */ new Set();
-  for (const { name } of await listBundles()) {
+  for (const { name } of await listBundles(dir)) {
     if (seen.has(name)) continue;
     seen.add(name);
-    const loaded = await readBundleFile(name);
+    const loaded = await readBundleFile(name, dir);
     if (!loaded) continue;
     try {
       const js = loaded.bytes.toString("utf8");
@@ -39372,15 +39434,15 @@ async function scanWidgets() {
   }
   return out;
 }
-async function handleWidgetList(res) {
-  sendJson(res, 200, { widgets: await scanWidgets() });
+async function handleWidgetList(res, dir) {
+  sendJson(res, 200, { widgets: await scanWidgets(dir) });
 }
-async function buildSnapshotForId(widgetId) {
+async function buildSnapshotForId(widgetId, dir) {
   const override = widgetOverrides.get(widgetId);
   if (override) return { ok: true, snapshot: override };
-  const entry = (await scanWidgets()).find((w) => w.widgetId === widgetId);
+  const entry = (await scanWidgets(dir)).find((w) => w.widgetId === widgetId);
   if (!entry) return { ok: false, status: 404, error: "widget_not_found" };
-  const loaded = await readBundleFile(entry.bundle);
+  const loaded = await readBundleFile(entry.bundle, dir);
   if (!loaded) return { ok: false, status: 404, error: "widget_not_found" };
   try {
     const js = loaded.bytes.toString("utf8");
@@ -39394,8 +39456,8 @@ async function buildSnapshotForId(widgetId) {
     return { ok: false, status: 422, error: "widget_invalid", message: err.message };
   }
 }
-async function handleWidgetGet(req, res, widgetId) {
-  const built = await buildSnapshotForId(widgetId);
+async function handleWidgetGet(req, res, widgetId, dir) {
+  const built = await buildSnapshotForId(widgetId, dir);
   if (!built.ok) return sendJson(res, built.status, { error: built.error, widgetId, message: built.message });
   const etag = `"${built.snapshot.contentEtag}"`;
   const ifNoneMatch = req.headers["if-none-match"];
@@ -39408,9 +39470,9 @@ async function handleWidgetGet(req, res, widgetId) {
   res.setHeader("cache-control", `max-age=${built.snapshot.refresh.ttlSeconds}`);
   sendJson(res, 200, built.snapshot);
 }
-async function handleWidgetPreview(res, widgetId) {
+async function handleWidgetPreview(res, widgetId, dir) {
   if (!widgetId) return sendJson(res, 400, { error: "missing_widgetId" });
-  const built = await buildSnapshotForId(widgetId);
+  const built = await buildSnapshotForId(widgetId, dir);
   if (!built.ok) return sendJson(res, built.status, { error: built.error, widgetId, message: built.message });
   sendJson(res, 200, built.snapshot);
 }
@@ -40029,10 +40091,10 @@ function createDevServer(opts = {}) {
         if (bundleMatch && (req.method === "GET" || req.method === "HEAD"))
           return await handleBundleGet(res, bundleMatch[1], state.tier5Dir);
         if (url.split("?")[0] === "/v1/widgets" && (req.method === "GET" || req.method === "HEAD"))
-          return await handleWidgetList(res);
+          return await handleWidgetList(res, state.tier5Dir);
         const widgetMatch = /^\/v1\/widget\/([A-Za-z0-9_.\-]+)$/.exec(url.split("?")[0]);
         if (widgetMatch && (req.method === "GET" || req.method === "HEAD"))
-          return await handleWidgetGet(req, res, widgetMatch[1]);
+          return await handleWidgetGet(req, res, widgetMatch[1], state.tier5Dir);
         const ahManifest = /^\/v1\/action-handlers\/([A-Za-z0-9_.\-]+)$/.exec(url.split("?")[0]);
         if (ahManifest && (req.method === "GET" || req.method === "HEAD"))
           return handleActionHandlersManifest(res, ahManifest[1]);
@@ -40046,7 +40108,10 @@ function createDevServer(opts = {}) {
             homeScreenId: state.app?.meta.homeScreenId,
             screens: state.app?.meta.screenIds ?? [],
             templatedPatterns: state.app?.meta.templatedPatterns ?? [],
-            tier5Bundles: await listBundles(),
+            // Same dir, same reason as the routes above: an off-repo app's own
+            // bundles must show up in its introspection body, not just the
+            // repo-global ones it didn't build.
+            tier5Bundles: await listBundles(state.tier5Dir),
             toggles: state.toggles,
             admin: "/web/future/app.html"
           });
@@ -40487,6 +40552,7 @@ __export(build_exports2, {
   SOURCEMAP_ON_DEMAND_PATH: () => SOURCEMAP_ON_DEMAND_PATH,
   bakeCatalogs: () => bakeCatalogs,
   bakeNeedsLiveOrigin: () => bakeNeedsLiveOrigin,
+  bakeWidgets: () => bakeWidgets,
   buildRelease: () => buildRelease,
   buildReleaseFromContent: () => buildReleaseFromContent,
   bundleNameFromUrl: () => bundleNameFromUrl,
@@ -40585,6 +40651,77 @@ function sha2564(buf) {
 function sri2(buf) {
   return "sha256-" + createHash18("sha256").update(buf).digest("base64");
 }
+async function widgetFailureDetail(res) {
+  try {
+    const body = JSON.parse(await res.text());
+    const detail = typeof body.message === "string" && body.message ? body.message : typeof body.error === "string" && body.error ? body.error : "";
+    return detail ? `: ${detail}` : "";
+  } catch {
+    return "";
+  }
+}
+function ownBundleNames(dir) {
+  if (!dir) return void 0;
+  return servedBundleNames(dir);
+}
+async function bakeWidgets(fetchPath, putWidget, ownBundles) {
+  const widgets = {};
+  const failures = [];
+  const isOurs = (bundle) => ownBundles !== void 0 && bundle !== void 0 && ownBundles.has(bundle);
+  const listRes = await fetchPath("/v1/widgets");
+  if (!listRes.ok) {
+    failures.push({
+      status: listRes.status,
+      message: `the widget manifest could not be read (GET /v1/widgets \u2192 ${listRes.status}) \u2014 this release carries no widget snapshots, whether or not the app declares any`
+    });
+    return { widgets, failures };
+  }
+  let list;
+  try {
+    const parsed = JSON.parse(await listRes.text()).widgets ?? [];
+    if (!Array.isArray(parsed)) throw new Error("widgets is not an array");
+    list = parsed;
+  } catch {
+    failures.push({
+      status: listRes.status,
+      message: "the widget manifest came back malformed \u2014 this release carries no widget snapshots"
+    });
+    return { widgets, failures };
+  }
+  for (const { widgetId, bundle } of list) {
+    const res = await fetchPath(`/v1/widget/${encodeURIComponent(widgetId)}`);
+    if (!res.ok) {
+      if (isOurs(bundle)) {
+        failures.push({
+          widgetId,
+          status: res.status,
+          message: `widget "${widgetId}" is declared but did not produce a snapshot (GET /v1/widget/${widgetId} \u2192 ${res.status}${await widgetFailureDetail(res)}) \u2014 the release does not carry it`
+        });
+      }
+      continue;
+    }
+    let snap;
+    try {
+      snap = JSON.parse(await res.text());
+    } catch {
+      if (isOurs(bundle)) {
+        failures.push({
+          widgetId,
+          status: res.status,
+          message: `widget "${widgetId}" answered ${res.status} with a body that is not a snapshot \u2014 the release does not carry it`
+        });
+      }
+      continue;
+    }
+    const json5 = JSON.stringify(snap);
+    await putWidget(widgetId, json5);
+    widgets[widgetId] = {
+      contentEtag: snap.contentEtag ?? sha2564(json5),
+      ttlSeconds: snap.refresh?.ttlSeconds ?? 0
+    };
+  }
+  return { widgets, failures };
+}
 async function snapshotTokens(app, base, fetchTokens, put) {
   const res = await fetchTokens();
   if (!res.ok) {
@@ -40781,6 +40918,7 @@ async function buildFromLoaded(preloaded, dest, opts = {}) {
   const screenIds = Object.keys(preloaded.module.screens.exact);
   const failedToBuild = [];
   const missingBundles = [];
+  const widgetBakeFailures = [];
   const lint = [];
   const renders = [];
   const baked = [];
@@ -41314,21 +41452,16 @@ async function buildFromLoaded(preloaded, dest, opts = {}) {
       }
     }
     if (store.putWidget) {
-      const wlRes = await devFetch(`${base}/v1/widgets`, { headers: { "X-Himalaya-App": app } });
-      if (wlRes.ok) {
-        const { widgets: list } = await wlRes.json();
-        for (const { widgetId } of list ?? []) {
-          const wRes = await devFetch(`${base}/v1/widget/${encodeURIComponent(widgetId)}`, { headers: { "X-Himalaya-App": app } });
-          if (!wRes.ok) continue;
-          const snap = await wRes.json();
-          const json5 = JSON.stringify(snap);
-          await store.putWidget(app, widgetId, json5);
-          widgets[widgetId] = {
-            contentEtag: snap.contentEtag ?? sha2564(json5),
-            ttlSeconds: snap.refresh?.ttlSeconds ?? 0
-          };
-        }
-      }
+      const bakedWidgets = await bakeWidgets(
+        (path) => devFetch(`${base}${path}`, { headers: { "X-Himalaya-App": app } }),
+        (widgetId, json5) => store.putWidget(app, widgetId, json5),
+        // `opts.tier5Dir`, NOT the `tier5Dir` local — that one falls back to the
+        // repo-global dir, where this package's widgets cannot be told from anyone
+        // else's and the filter would claim every app's rows as ours.
+        ownBundleNames(opts.tier5Dir)
+      );
+      Object.assign(widgets, bakedWidgets.widgets);
+      widgetBakeFailures.push(...bakedWidgets.failures);
     }
   } finally {
     await new Promise((r) => dev.close(() => r()));
@@ -41417,6 +41550,7 @@ async function buildFromLoaded(preloaded, dest, opts = {}) {
       return named ? { ...v, message: `${v.message} \u2014 bundle "${named.name}"` } : v;
     }),
     ...tokensSnapshotFailure ? { tokensSnapshotFailure } : {},
+    ...widgetBakeFailures.length ? { widgetBakeFailures } : {},
     ...collect?.lint ? { lint, workers } : {},
     ...collect?.render ? { renders } : {},
     ...collect?.descriptors ? { descriptors: baked, linkableScreenIds: [...linkable] } : {},
@@ -59318,6 +59452,17 @@ function summarizeLint(app, bres, outcome, strict, extraIssues = []) {
       message: tokensFailure.message
     });
   }
+  for (const failure of outcome.widgetBakeFailures ?? []) {
+    issues.push({
+      screen: null,
+      pass: "widgets",
+      severity: strict ? "error" : "warning",
+      ruleCode: "widget-not-produced",
+      ...failure.widgetId ? { widgetId: failure.widgetId } : {},
+      status: failure.status,
+      message: failure.message
+    });
+  }
   const errorIssues = issues.filter((i) => i.severity === "error");
   const workers = (outcome.workers ?? []).filter((w) => w.threw || w.console.length);
   const workerThrows = workers.filter((w) => w.threw);
@@ -60408,6 +60553,12 @@ function wixPlayerTestflightTarget(requested) {
   return target === "bo" || target === "prod" ? target : void 0;
 }
 var SURFACE_IDS = `${PREVIEW_SURFACES.filter((s) => !s.id.startsWith("widget:")).map((s) => s.id).join("|")}|widget:<family>`;
+var RENDER_DEVICE_SURFACE_IDS = PREVIEW_SURFACES.filter((s) => s.gate.kind !== "family").map((s) => s.id).join("|");
+var PRODUCED_HINTS = {
+  "not-measured": "widget production was not measured \u2014 `--measure-widgets` evaluates this package's built bundles (it RUNS their code), or ask a running app: GET /v1/widgets. `himi validate --strict` fails a package whose declared widget does not produce.",
+  unbuilt: "this package has no dist/bundles, so there is nothing to measure \u2014 run `himi build` first. A package with no Tier-5 bundle can declare no widget at all.",
+  "producer-unavailable": "the widget producer is not resolvable in this install, so production cannot be measured here at all \u2014 building this package will not change that. Ask a running app instead: GET /v1/widgets."
+};
 var DEVELOPER_PORTAL_URL = `${ADMIN_ORIGIN_BO}/#/developer`;
 var MAX_APP_SOURCE_BYTES_HELP = "4 MiB (4,194,304 bytes)";
 var USAGE = `himi \u2014 the Himalaya authoring CLI (remote dev loop)
@@ -60493,8 +60644,9 @@ var USAGE = `himi \u2014 the Himalaya authoring CLI (remote dev loop)
                                            --input '{"id":"\u2026"}' supplies navigation input before the worker boots;
                                            --load-budget <ms> raises/lowers the per-service load() budget (--live defaults to 30000);
                                            --width 390 / --device iphone renders the PNG at phone width (default: desktop);
-                                             --device also takes any surface id (${SURFACE_IDS})
+                                             --device also takes an app-shell surface id (${RENDER_DEVICE_SURFACE_IDS})
                                              at its catalog viewport width (himi surfaces lists them);
+                                             a widget family is NOT a device \u2014 fetch /v1/widget/<widgetId>;
                                            --rtl sets ambient direction (dir=rtl + $env:isRTL)
   himi icons [--json]                      the valid Icon.name vocabulary (offline)
   himi fonts [list] [--licenses]           the curated font vocabulary a typography.*.family may
@@ -60633,11 +60785,14 @@ var USAGE = `himi \u2014 the Himalaya authoring CLI (remote dev loop)
                                            print web + himi:// + agent-preview JSON URLs
                                            --surface ${SURFACE_IDS}
                                              frames the web preview as that surface (?surface=)
-  himi surfaces [--content <dir>] [--app <app> --release <id>]
+  himi surfaces [--content <dir>] [--app <app> --release <id>] [--measure-widgets]
                                            the surface catalog vs the LOCAL package's envelope
                                            (platforms.json): targeted surfaces, the opt-in for the
                                            rest, and (with --app --release) per-surface preview
                                            links. For a pushed release's envelope: himi context
+                                             --measure-widgets additionally reports which widget
+                                             families this package PRODUCES \u2014 it evaluates the
+                                             built bundles, i.e. RUNS their code; off by default
   himi context --app <app> --release <id> [--screen <id>] [--include telemetry]
                                            fetch the agent preview envelope (GET /v1/preview/a/\u2026)
   himi app-docs list|get <spec|mobile-ux> --app <app> [--release <id>]
@@ -60862,7 +61017,7 @@ var COMMANDS = [
   { name: "share", summary: "publish or revoke a content-addressed `.himi` share link. The package must be a validated archive for an already-published release; the resulting https URL is safe to QR, copy, or open in Himi Player.", required: "--file <package.himi> [--expires-at <ISO>] | revoke --app <app> <shareId>" },
   { name: "run", summary: "serve a .himi package on localhost and open it in a browser \u2014 no serve plane, no dev-server, no setup. Given no argument it builds the current content package first, so `himi run` is the inner loop: edit, run, look at it. The SPA and /v1 are served from ONE origin because Tier-5 bundle fetches on web are same-origin-only. --chrome preview frames the app in a device chassis; --chrome app serves it as a plain web app. Blocks until Ctrl-C, like any dev server. --browser runs the whole plane INSIDE the tab (service worker + in-memory store) so no app code executes in this process or on any pod.", required: "[<package.himi|dir|url>] [--browser] [--content <dir>] [--port <n>] [--chrome preview|app] [--screen <id>] [--surface <id>] [--no-open] [--spa <url>]" },
   { name: "preview", summary: "print the shareable web URL + himi:// deep link + agent /v1/preview JSON URLs for an app+release; --surface frames the web preview as any catalog surface (?surface=)", required: "--app --release [--screen] [--surface]" },
-  { name: "surfaces", summary: "the surface catalog vs this app's envelope (platforms.json): targeted surfaces, the opt-in key for the rest, and per-surface preview links with --app --release", required: "[--content <dir>] [--app --release]" },
+  { name: "surfaces", summary: "the surface catalog vs this app's envelope (platforms.json): targeted surfaces, the opt-in key for the rest, per-surface preview links with --app --release, and which widget families the package produces with --measure-widgets (which runs its built bundles)", required: "[--content <dir>] [--app --release] [--measure-widgets]" },
   { name: "context", summary: "fetch the agent preview envelope (GET /v1/preview/a/<app>) \u2014 ok/issues/screens/links; exit 1 if ok:false", required: "--app --release [--screen] [--include telemetry]" },
   { name: "app-docs", summary: "retrieve the public-safe SPEC.md and MOBILE-UX.md carried by an immutable release; `list` is JSON metadata and `get` prints one Markdown document", required: "list|get <spec|mobile-ux> --app <app> [--release <id>]" },
   { name: "telemetry", summary: "head-loop telemetry read-back (GET /v1/telemetry/events + logs): screen_view, action_*, nav/error events, worker_console logs. Default includes recent events + logs; --summary/--crashes add aggregate/crash-stack reads; --follow emits bounded JSONL updates.", required: "--app --release [--screen] [--type] [--since] [--limit] [--follow] [--summary] [--crashes]" },
@@ -61699,6 +61854,60 @@ async function loadAuthoring() {
     throw new AuthoringUnavailable();
   }
 }
+async function producedWidgetFamilies(dir) {
+  let widgetsModule;
+  let tier5Dir;
+  try {
+    const [w, t] = await Promise.all([
+      Promise.resolve().then(() => (init_widgets(), widgets_exports)),
+      Promise.resolve().then(() => (init_tier5_dir(), tier5_dir_exports))
+    ]);
+    widgetsModule = w;
+    tier5Dir = t;
+  } catch {
+    return { families: void 0, source: "producer-unavailable" };
+  }
+  const outDir = tier5Dir.bundleOutDir(dir);
+  try {
+    readdirSync23(outDir);
+  } catch {
+    return { families: void 0, source: "unbuilt" };
+  }
+  const names = [...tier5Dir.servedBundleNames(outDir)];
+  const families = /* @__PURE__ */ new Set();
+  const emitted = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    let js;
+    for (const candidate of [`${name}.bundle.js`, `${name}.js`, name]) {
+      try {
+        js = readFileSync63(join49(outDir, candidate), "utf8");
+        break;
+      } catch {
+      }
+    }
+    if (js === void 0) continue;
+    let extracted;
+    try {
+      extracted = widgetsModule.extractWidgets(js);
+    } catch {
+      continue;
+    }
+    for (const [widgetId, def] of Object.entries(extracted.widgets)) {
+      try {
+        widgetsModule.buildWidgetSnapshot(js, widgetId);
+        families.add(def.family);
+      } catch {
+      }
+    }
+    for (const entry of widgetsModule.frozenViewManifestEntries(extracted.views, emitted)) {
+      try {
+        if (widgetsModule.buildViewSnapshot(js, entry.view.viewId, entry.view.surfaceId)) families.add(entry.family);
+      } catch {
+      }
+    }
+  }
+  return { families, source: "dist/bundles" };
+}
 async function run(argv, io = defaultIO) {
   const { _: pos, flags } = parseFlags(argv);
   const command = pos[0];
@@ -62729,7 +62938,21 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
         if (deviceName) {
           renderWidth = DEVICE_WIDTHS[deviceName.toLowerCase()];
           if (!renderWidth) {
-            io.error(JSON.stringify({ error: `unknown --device "${deviceName}"`, devices: Object.keys(DEVICE_WIDTHS) }));
+            const devices = Object.keys(DEVICE_WIDTHS).filter((d) => surfaceById(d)?.gate.kind !== "family");
+            io.error(JSON.stringify({ error: `unknown --device "${deviceName}"`, devices }));
+            return 2;
+          }
+          const surface = surfaceById(deviceName.toLowerCase());
+          if (surface && isWidgetFamilySurface(surface)) {
+            io.error(JSON.stringify({
+              error: `--device "${deviceName}" is a widget family ("${surfaceFrozenFamily(surface)}"), not a viewport. himi render draws a screen; a widget is produced from defineWidget and addressed by widgetId, so rendering the screen at ${renderWidth}px would look like a widget and be none.`,
+              surface: surface.id,
+              renderMode: surfaceRenderMode(surface),
+              instead: [
+                "GET /v1/widgets \u2014 the widgets this app actually produces",
+                "GET /v1/widget/<widgetId> \u2014 the frozen snapshot the OS renders"
+              ]
+            }));
             return 2;
           }
         } else if (typeof flags.width === "string" && flags.width) {
@@ -63918,6 +64141,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
         const release = str5(flags.release);
         const base = serveBase();
         const withLinks = !!(app && release && base);
+        const produced = flags["measure-widgets"] === true ? await producedWidgetFamilies(dir) : { families: void 0, source: "not-measured" };
         print({
           ok: true,
           // The verb describes the LOCAL content package (its platforms.json) — for
@@ -63925,12 +64149,39 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           // preview envelope reports `surfaces` from the release manifest).
           envelopeSource: "local",
           envelope: platforms,
-          enabled: resolveSurfaceEnvelope(platforms).enabled,
-          surfaces: surfacesForApp(platforms).map(({ surface, targeted, optIn }) => ({
+          // Narrowed by the produced set when there IS one, and not merely reported
+          // beside it. `enabled` is the short field an agent reads first, so leaving it
+          // as the raw envelope would have kept listing `widget:ios_home` two lines above
+          // a row saying `produced: false, needs: defineWidget(…)` — #2499's exact
+          // over-claim, surviving inside the output added to remove it. `producedSource`
+          // right below says how (or whether) the narrowing was measured.
+          enabled: (() => {
+            const envelope = resolveSurfaceEnvelope(platforms).enabled;
+            if (!produced.families) return envelope;
+            return envelope.filter((id) => {
+              const surface = surfaceById(id);
+              return !surface || !isWidgetFamilySurface(surface) || produced.families.has(surfaceFrozenFamily(surface));
+            });
+          })(),
+          // Says which question the `produced` column answered, and — when it could not
+          // be answered — WHICH way it failed. The three non-answers call for different
+          // things and must not collapse into one: "not-measured" wants `--measure-widgets`
+          // (and consents to running the package's code), "unbuilt" wants `himi build`,
+          // and "producer-unavailable" wants neither — nothing about this package will
+          // change that one.
+          producedSource: produced.source,
+          // …and the hint has to branch on WHICH of them it was, or it hands back advice the
+          // caller has already taken: telling someone who just passed `--measure-widgets`
+          // to pass `--measure-widgets` is exactly the "everything advertises the capability"
+          // shape this issue is about, in miniature.
+          ...produced.families ? {} : { producedHint: PRODUCED_HINTS[produced.source] },
+          surfaces: surfacesForApp(platforms, produced.families).map(({ surface, targeted, optIn, produced: isProduced, needs }) => ({
             id: surface.id,
             label: surface.label,
             targeted,
             viewport: surface.viewport,
+            ...isProduced === void 0 ? {} : { produced: isProduced },
+            ...needs ? { needs } : {},
             ...optIn ? { optIn: `platforms.json: { ${optIn} }` } : {},
             ...withLinks && targeted ? { previewWeb: previewWebUrl(base, app, release, void 0, surface.id) } : {}
           })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.849.0",
+  "version": "0.850.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": [
@@ -63,5 +63,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "464c186de522efebf80157a9bca4d7349bdbf3331ac8adfaf726f4d4"
+  "falconPackageHash": "17dae723ff059af1c4e2d1d27c07a030f3551c1ab3228d66cc5b6795"
 }