@wix/himalaya-cli 0.1557.0 → 0.1558.0

package/guides/sdk-reference.json

@@ -1167,7 +1167,7 @@
         "name": "SplashConfig",
         "kind": "interface",
         "jsdoc": "/**\n * The IN-APP splash — the brand surface between the OS splash handing off and the\n * app being ready. The *OS* splash is generated at build time from the same\n * `splash` block in config.ts and can never be OTA (iOS reads `UILaunchScreen`\n * before any app code runs); this layer is OTA. Artwork stays baked in the binary\n * — `logoAsset` / `backgroundImageAsset` name a baked asset, so only the\n * composition travels.\n */",
-        "decl": "export interface SplashConfig {\n  /** Master switch / kill-switch. Absent or false ⇒ no surface. */\n  enabled?: boolean;\n  /** Background color TOKEN name (e.g. \"accentPrimary\"). */\n  backgroundColor?: TokenName;\n  /** Gradient token name; wins over `backgroundColor`. */\n  backgroundGradient?: TokenName;\n  /** BAKED asset name for a full-bleed background image; wins over color/gradient. */\n  backgroundImageAsset?: string;\n  /** BAKED asset name for the centered logo (e.g. \"LaunchLogo\"). */\n  logoAsset?: string;\n  /** Logo width in pt/dp. 0 / absent ⇒ 96. */\n  logoWidth?: number;\n  /** Optional wordmark line. NOTE: a literal string, so an OTA edit bypasses\n   *  localization (same caveat as `NavTabItem.label`). */\n  caption?: string;\n  /** Typography token for the caption. Absent ⇒ \"title1\". */\n  captionStyle?: TokenName;\n  /** Color token for the caption. Absent ⇒ \"textOnAccent\". */\n  captionColor?: TokenName;\n  /** Absent / unknown ⇒ \"centered\". */\n  layout?: SplashLayout;\n  /** Anti-flash floor, ms. Clamped client-side to [0, 2000]. */\n  minVisibleMs?: number;\n  /** Hard ceiling on the readiness hold, ms — a stuck boot can never wedge the\n   *  UI. 0 / absent ⇒ 3000. Clamped client-side to [0, 8000]. */\n  maxHoldMs?: number;\n  /** What readiness waits for beyond the seed. Absent / \"\" ⇒ seeded is\n   *  enough. \"first_content\" ⇒ also the first WebView page (a site shell), still\n   *  under `maxHoldMs`. Unknown coalesces to \"\" on device. */\n  readySignal?: SplashReadySignal;\n}"
+        "decl": "export interface SplashConfig {\n  /** Master switch / kill-switch. Absent or false ⇒ no surface. */\n  enabled?: boolean;\n  /** Background color TOKEN name (e.g. \"accentPrimary\"). */\n  backgroundColor?: TokenName;\n  /** Gradient token name; wins over `backgroundColor`. */\n  backgroundGradient?: TokenName;\n  /** BAKED asset name for a full-bleed background image; wins over color/gradient. */\n  backgroundImageAsset?: string;\n  /** BAKED asset name for the centered logo (e.g. \"LaunchLogo\"). */\n  logoAsset?: string;\n  /** Logo width in pt/dp. 0 / absent ⇒ 96. */\n  logoWidth?: number;\n  /** Optional wordmark line. NOTE: a literal string, so an OTA edit bypasses\n   *  localization (same caveat as `NavTabItem.label`). */\n  caption?: string;\n  /** Typography token for the caption. Absent ⇒ \"title1\". */\n  captionStyle?: TokenName;\n  /** Color token for the caption. Absent ⇒ \"textOnAccent\". */\n  captionColor?: TokenName;\n  /** Absent / unknown ⇒ \"centered\". */\n  layout?: SplashLayout;\n  /** Anti-flash floor, ms. Clamped client-side to [0, 2000]. */\n  minVisibleMs?: number;\n  /** Hard ceiling on the readiness hold, ms — a stuck boot can never wedge the\n   *  UI. 0 / absent ⇒ 3000. Clamped client-side to [0, 8000]. */\n  maxHoldMs?: number;\n  /** What readiness waits for beyond the seed. Absent / \"\" ⇒ the first\n   *  screen's paint, where the shell mounts its content under the splash (every shell\n   *  built on `HimalayaLaunchGate` / `awaitingFirstScreen`), else the seed alone.\n   *  \"seeded\" ⇒ the seed alone, always. \"first_content\" ⇒ the first WebView page (a\n   *  site shell). All still under `maxHoldMs`. Unknown coalesces to \"\" on device. */\n  readySignal?: SplashReadySignal;\n}"
       },
       {
         "name": "OrientationConfig",
@@ -23223,7 +23223,7 @@
       {
         "name": "wixMediaUrl",
         "kind": "function",
-        "jsdoc": "/**\n * Ask the Wix media CDN for a MOBILE-SIZED render instead of the stored original.\n *\n * `.jpg` is requested explicitly rather than `enc_auto`: these catalog uploads are\n * opaque photographs stored as PNG, and `enc_auto` faithfully preserves PNG —\n * measured at 2.4MB versus 220KB for the same 1000px render. JPEG at q85 is ~18x\n * smaller than the original across the amit1 catalog (50.5MB -> 2.7MB).\n *\n * Wix image handles and bare media ids are resolved before sizing. Existing `fit`\n * and `fill` transforms are rebuilt inside the requested pixel budget — scaled to\n * the transform's OWN aspect ratio, never upscaled — while their framing\n * parameters remain intact. Other transform modes and non-Wix HTTP(S) URLs stay\n * untouched. Unsupported references normalize to an empty string.\n */",
+        "jsdoc": "/**\n * Ask the Wix media CDN for a MOBILE-SIZED render instead of the stored original.\n *\n * `.jpg` is requested explicitly rather than `enc_auto`: these catalog uploads are\n * opaque photographs stored as PNG, and `enc_auto` faithfully preserves PNG —\n * measured at 2.4MB versus 220KB for the same 1000px render. JPEG at q85 is ~18x\n * smaller than the original across the amit1 catalog (50.5MB -> 2.7MB).\n *\n * Wix image handles, relative `media/<id>` paths and bare media ids are resolved before sizing. Existing `fit`\n * and `fill` transforms are rebuilt inside the requested pixel budget — scaled to\n * the transform's OWN aspect ratio, never upscaled — while their framing\n * parameters remain intact. Other transform modes and non-Wix HTTP(S) URLs stay\n * untouched. Unsupported references normalize to an empty string.\n */",
         "decl": "export function wixMediaUrl(value: unknown, size: WixImageSize | null = WIX_LIST_IMAGE): string;"
       },
       {

package/guides/skill.md

@@ -24,7 +24,10 @@ carry any explicit user changes in its separate prompt option.
 For this scoped migration, that guide replaces the generic discovery, plan-approval
 and template-preview journey below. Write the reconstruction plan, `SPEC.md`,
 `MOBILE-UX.md` and migration report, then continue implementation and the authorized
-same-site OAuth setup, checks and hosted draft. Preserve the supplied layout and
+same-site One App visitor binding, checks and hosted draft. Obtain the
+site owner's agreement before creating or updating an OAuth client for optional
+member flows; visitor reads and native email/password sign-in need no client.
+Preserve the supplied layout and
 apply the user's separate optional prompt. Use `CI=1 himi init` with
 `--no-first-look`; do not execute its generic `doNow` / `doNowAgain` template-preview
 instructions. Show the reconstructed app after adapting it and checking its data.

package/guides/splash-screens.md

@@ -148,7 +148,7 @@ splash: {
   layout: "centeredStacked",     // centered | centeredStacked | logoOnly
   minVisibleMs: 600,             // anti-flash floor,  clamped ≤ 2000
   maxHoldMs: 3000,               // hard ceiling,      clamped ≤ 8000
-  readySignal: "",               // "" | "first_content" — see "Readiness, not a timer"
+  readySignal: "",               // "" | "seeded" | "first_content" — see "Readiness, not a timer"
 }
 ```
 
@@ -172,6 +172,27 @@ strict-decode throw disables **all** OTA. Proto field 14+ is reserved should tha
 `BootReadiness` (iOS + Android, one tested implementation each) decides when the surface may
 go: **seeded AND past the anti-flash floor, OR the hard ceiling elapsed.**
 
+**The splash waits for the first screen.** Every shell mounts its content UNDER the splash once
+seeded, and the splash leaves when the first screen paints its descriptor, or shows its load error.
+Before this, the shells composed `if ready { content } else { splash }`: the content mounted only
+once the splash had gone, so the first screen started loading then, and a launch faded into the tab
+chrome over an empty body for the length of that load (~0.4 s in demo-app). On iOS and macOS the
+shell composes `HimalayaLaunchGate(seeded:splash:) { content }`, which owns the overlay, the exit
+fade, the floor and ceiling ticks, and the `splash_timeout` report. On Android the shell composes
+its content on `seeded` with `HimalayaSplashHost` over it, passes `awaitingFirstScreen = true` to
+`effectiveReady` / `dismissedByDeadline`, and collects `BootReadiness.firstScreen` so the paint
+re-evaluates readiness. Every `ScreenView` (and the host's error state, `BootErrorScreen` on
+Android) calls `BootReadiness.markFirstScreen()`. The ceiling still applies. `readySignal: "seeded"`
+releases the splash on the seed alone. Only a shell that mounts its content under the splash may
+wait for the first screen: one that mounts it after the splash leaves would hold to the ceiling,
+which is why `effectiveReady(_:)` without `awaitingFirstScreen` still means the seed alone.
+`splash-parity.test.ts` fails a shell that shows its splash instead of its content.
+
+The splash surface eases its logo and caption in once per launch. A tokens revision re-keys
+everything under `HimalayaAppRoot`, the splash included, and a first launch's served tokens usually
+differ from the baked ones, so the remounted surface used to blank and fade in again while the first
+screen loaded under it.
+
 `readySignal: "first_content"` adds one
 condition to "seeded": the first WebView page has finished loading. It exists for a site shell
 (`himi-brandy`), where every tab is the customer's website and a splash that leaves on `seeded`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1557.0",
+  "version": "0.1558.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "af9ec3d733e930df474d226a826345b720afccbb9190afc75704ab57"
+  "falconPackageHash": "3e25c3d6c9c9f3a1d3abe87df97e8a1f848ce1a712d321126ce42454"
 }

package/templates/beauty-salon/tier5-src/_shared/himi-media.ts

@@ -0,0 +1,29 @@
+// Cover selection is shared by list, detail and home so the same Wix object never
+// loses its image on navigation. Relative SDK imports are rewritten by the template generator.
+import { wixMediaUrl, WIX_LIST_IMAGE, type WixImageSize } from "@himalaya/wix-media";
+import type { WixGroup } from "@himalaya/wix-groups";
+import type { WixProgram } from "@himalaya/wix-online-programs";
+
+function firstImage(references: unknown[], size: WixImageSize): string {
+  for (const reference of references) {
+    const image = wixMediaUrl(reference, size);
+    if (image) return image;
+  }
+  return "";
+}
+
+export function groupImage(group: WixGroup, size: WixImageSize = WIX_LIST_IMAGE): string {
+  const cover = group.coverImage as {
+    url?: unknown;
+    image?: { url?: unknown; fileUrl?: unknown; mediaId?: unknown; id?: unknown };
+  } | undefined;
+  return firstImage([cover?.image?.url, cover?.image?.fileUrl, cover?.url, cover?.image?.mediaId, cover?.image?.id], size);
+}
+
+export function programImage(program: WixProgram, size: WixImageSize = WIX_LIST_IMAGE): string {
+  const cover = (program as { coverImage?: unknown }).coverImage;
+  const coverUrl = typeof cover === "string" ? cover : (cover as { url?: unknown } | undefined)?.url;
+  const description = (program as { description?: unknown }).description;
+  const nested = description && typeof description === "object" ? (description as { image?: { url?: unknown; id?: unknown } }).image : undefined;
+  return firstImage([coverUrl, program.image, nested?.url, nested?.id], size);
+}

package/templates/beauty-salon/tier5-src/himi-branded-lite-home/index.ts

@@ -24,6 +24,7 @@ import { readSavedProducts, type SavedProduct } from "../_shared/himi-store-save
 import { loadStoreCategories, type StoreCategoryCard } from "../_shared/himi-store-categories.js";
 import { readSavedIds } from "../_shared/himi-blog-saved.js";
 import { wixMediaUrl } from "@himalaya/wix-media";
+import { groupImage, programImage } from "../_shared/himi-media.js";
 import { isWixVideoWebRefusal, listLatestVideos, videoCard, type WixVideoCard } from "@himalaya/wix-video";
 import { videoCaptionOf, withCaption, type CaptionFlags } from "../_shared/video-caption.js";
 
@@ -676,8 +677,7 @@ async function fetchHomePrograms(): Promise<ProgramCard[]> {
         const nestedTitle = desc && typeof desc === "object" ? (desc as { title?: string }).title : undefined;
         const nestedDetails = desc && typeof desc === "object" ? (desc as { details?: string }).details : undefined;
         const name = cleanTitle(p.settings?.title ?? nestedTitle ?? p.title) || copyParam("home.programFallbackName", "Program");
-        const cover = (p as { coverImage?: unknown }).coverImage;
-        const image = (typeof cover === "string" ? cover : (cover as { url?: string } | undefined)?.url) || p.image || "";
+        const image = programImage(p);
         const details = (p.settings?.description ?? nestedDetails ?? (typeof desc === "string" ? desc : "") ?? "")
           .replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
         return {
@@ -732,8 +732,7 @@ function homeTimeLabel(value?: string): string {
 function groupCard(group: WixGroup): GroupCard {
   const title = (group.name || copyParam("home.groupFallbackTitle", "Group")).trim();
   const count = group.membersCount ?? group.memberCount;
-  const cover = group.coverImage as { url?: string; image?: { url?: string } } | undefined;
-  const image = cover?.image?.url ?? cover?.url ?? "";
+  const image = groupImage(group);
   return {
     id: group.id || title,
     title,

package/templates/branded-lite/tier5-src/_shared/himi-media.ts

@@ -0,0 +1,29 @@
+// Cover selection is shared by list, detail and home so the same Wix object never
+// loses its image on navigation. Relative SDK imports are rewritten by the template generator.
+import { wixMediaUrl, WIX_LIST_IMAGE, type WixImageSize } from "@himalaya/wix-media";
+import type { WixGroup } from "@himalaya/wix-groups";
+import type { WixProgram } from "@himalaya/wix-online-programs";
+
+function firstImage(references: unknown[], size: WixImageSize): string {
+  for (const reference of references) {
+    const image = wixMediaUrl(reference, size);
+    if (image) return image;
+  }
+  return "";
+}
+
+export function groupImage(group: WixGroup, size: WixImageSize = WIX_LIST_IMAGE): string {
+  const cover = group.coverImage as {
+    url?: unknown;
+    image?: { url?: unknown; fileUrl?: unknown; mediaId?: unknown; id?: unknown };
+  } | undefined;
+  return firstImage([cover?.image?.url, cover?.image?.fileUrl, cover?.url, cover?.image?.mediaId, cover?.image?.id], size);
+}
+
+export function programImage(program: WixProgram, size: WixImageSize = WIX_LIST_IMAGE): string {
+  const cover = (program as { coverImage?: unknown }).coverImage;
+  const coverUrl = typeof cover === "string" ? cover : (cover as { url?: unknown } | undefined)?.url;
+  const description = (program as { description?: unknown }).description;
+  const nested = description && typeof description === "object" ? (description as { image?: { url?: unknown; id?: unknown } }).image : undefined;
+  return firstImage([coverUrl, program.image, nested?.url, nested?.id], size);
+}

package/templates/branded-lite/tier5-src/himi-branded-lite-group/index.ts

@@ -4,6 +4,8 @@ import { getGroup, joinGroup, leaveGroup, queryMembers as queryGroupMembers, typ
 import { getMember } from "@himalaya/wix-members";
 import { signedInEmail } from "../_shared/himi-account";
 import { initials } from "../_shared/himi-text.js";
+import { groupImage } from "../_shared/himi-media.js";
+import { WIX_DETAIL_IMAGE } from "@himalaya/wix-media";
 import { copyParam, stashCopy } from "../_shared/himi-copy.js";
 import { get as dbGet, upsert as dbUpsert, type DbEntity } from "@himalaya/local-db";
 import { isOfflineFailure, writeMayHaveLanded } from "../_shared/owner-load-error";
@@ -87,11 +89,6 @@ function inputId(): string {
   return input?.screenId?.startsWith("himi_group_") ? input.screenId.slice("himi_group_".length) : "";
 }
 
-function coverImage(group: WixGroup): string {
-  const cover = group.coverImage as { url?: string; image?: { url?: string } } | undefined;
-  return cover?.image?.url ?? cover?.url ?? "";
-}
-
 function membershipState(state: State, joined: boolean, signedIn: boolean): State {
   const isPublic = state.privacy === "Public" || state.privacy === "Unknown";
   return {
@@ -176,7 +173,7 @@ const svc = defineService<State, {
         const response = await getGroup(id);
         const group = ((response as unknown as { group?: WixGroup }).group ?? response) as WixGroup;
         const name = (group.name || copyParam("group.groupFallbackName", "Group")).trim();
-        const image = coverImage(group);
+        const image = groupImage(group, WIX_DETAIL_IMAGE);
         const count = group.membersCount ?? group.memberCount;
         const privacy = (group.privacyStatus || "UNKNOWN").toLowerCase();
         const privacyLabel = privacy[0].toUpperCase() + privacy.slice(1);

package/templates/branded-lite/tier5-src/himi-branded-lite-groups/index.ts

@@ -1,6 +1,6 @@
 import { defineService } from "../_shared/collection-service.js";
 import { queryGroups, type WixGroup } from "@himalaya/wix-groups";
-import { wixMediaUrl } from "@himalaya/wix-media";
+import { groupImage } from "../_shared/himi-media.js";
 import { copyParam, stashCopy } from "../_shared/himi-copy.js";
 import { getAll, upsert, type DbEntity } from "@himalaya/local-db";
 
@@ -45,23 +45,10 @@ interface State {
   noEmpty: boolean;
 }
 
-/** Social Groups stores a cover as `coverImage.image.mediaId` and returns NO url —
- *  the documented Image type has mediaId/width/height/preset only. Probing just
- *  `.url` therefore left every real cover unrendered (accent band + initials).
- *  Keep the url probes for other shapes, then derive from the media id. */
-function coverImage(group: WixGroup): string {
-  const cover = group.coverImage as
-    | { url?: string; image?: { url?: string; mediaId?: string; id?: string } }
-    | undefined;
-  return wixMediaUrl(
-    cover?.image?.url ?? cover?.url ?? cover?.image?.mediaId ?? cover?.image?.id,
-  );
-}
-
 function groupRow(group: WixGroup): GroupRow {
   const title = (group.name || copyParam("groups.groupFallbackName", "Group")).trim();
   const count = group.membersCount ?? group.memberCount;
-  const image = coverImage(group);
+  const image = groupImage(group);
   return {
     id: group.id || title,
     title,

package/templates/branded-lite/tier5-src/himi-branded-lite-home/index.ts

@@ -24,6 +24,7 @@ import { readSavedProducts, type SavedProduct } from "../_shared/himi-store-save
 import { loadStoreCategories, type StoreCategoryCard } from "../_shared/himi-store-categories.js";
 import { readSavedIds } from "../_shared/himi-blog-saved.js";
 import { wixMediaUrl } from "@himalaya/wix-media";
+import { groupImage, programImage } from "../_shared/himi-media.js";
 import { isWixVideoWebRefusal, listLatestVideos, videoCard, type WixVideoCard } from "@himalaya/wix-video";
 import { videoCaptionOf, withCaption, type CaptionFlags } from "../_shared/video-caption.js";
 
@@ -676,8 +677,7 @@ async function fetchHomePrograms(): Promise<ProgramCard[]> {
         const nestedTitle = desc && typeof desc === "object" ? (desc as { title?: string }).title : undefined;
         const nestedDetails = desc && typeof desc === "object" ? (desc as { details?: string }).details : undefined;
         const name = cleanTitle(p.settings?.title ?? nestedTitle ?? p.title) || copyParam("home.programFallbackName", "Program");
-        const cover = (p as { coverImage?: unknown }).coverImage;
-        const image = (typeof cover === "string" ? cover : (cover as { url?: string } | undefined)?.url) || p.image || "";
+        const image = programImage(p);
         const details = (p.settings?.description ?? nestedDetails ?? (typeof desc === "string" ? desc : "") ?? "")
           .replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
         return {
@@ -732,8 +732,7 @@ function homeTimeLabel(value?: string): string {
 function groupCard(group: WixGroup): GroupCard {
   const title = (group.name || copyParam("home.groupFallbackTitle", "Group")).trim();
   const count = group.membersCount ?? group.memberCount;
-  const cover = group.coverImage as { url?: string; image?: { url?: string } } | undefined;
-  const image = cover?.image?.url ?? cover?.url ?? "";
+  const image = groupImage(group);
   return {
     id: group.id || title,
     title,

package/templates/branded-lite/tier5-src/himi-branded-lite-program/index.ts

@@ -21,6 +21,8 @@ import { withOnlineWrites } from "../_shared/online-actions.js";
 // offers Get access in place of Enrol and sells only through the shared checkout, never through the
 // Wix payment rail.
 import { defineService as registerService } from "@himalaya/state";
+import { programImage } from "../_shared/himi-media.js";
+import { WIX_DETAIL_IMAGE } from "@himalaya/wix-media";
 import {
   getProgram,
   joinProgram,
@@ -122,14 +124,6 @@ function detailsOf(p: WixProgram): string {
     .trim();
 }
 
-function imageOf(p: WixProgram): string {
-  const desc = (p as { description?: unknown }).description;
-  const nested = desc && typeof desc === "object" ? (desc as { image?: { url?: string } }).image?.url : undefined;
-  const cover = (p as { coverImage?: unknown }).coverImage;
-  const coverUrl = typeof cover === "string" ? cover : (cover as { url?: string } | undefined)?.url;
-  return (coverUrl || p.image || nested || "").trim();
-}
-
 function metaOf(p: WixProgram): string {
   const summary = (p as { contentSummary?: { stepCount?: number; sectionCount?: number } }).contentSummary;
   const bits: string[] = [];
@@ -160,7 +154,7 @@ function ready(state: State, p: WixProgram | undefined): State {
     return derive({ ...state, status: "ready", name: "", description: "", meta: "", priceLine: "", image: "", initial: "", emptyText: copyParam("program.emptyText", "This program is no longer available.") });
   }
   const name = titleOf(p);
-  const image = imageOf(p);
+  const image = programImage(p, WIX_DETAIL_IMAGE);
   return derive({
     ...state,
     status: "ready",

package/templates/branded-lite/tier5-src/himi-branded-lite-programs/index.ts

@@ -14,7 +14,7 @@ import { decorateCollection } from "../_shared/collection-service.js";
 import { queryPrograms, type WixProgram } from "@himalaya/wix-online-programs";
 import { iapPriceFields, onlineProgramItem, type IapPollDirective } from "@himalaya/iap";
 import { createIapCommerce } from "@himalaya/iap-checkout";
-import { wixMediaUrl } from "@himalaya/wix-media";
+import { programImage } from "../_shared/himi-media.js";
 import { cleanTitle, initials } from "../_shared/himi-text.js";
 import { copyParam, stashCopy } from "../_shared/himi-copy.js";
 import { iapPriceCopy, resetUnhydratedKeysOnOlderRuntime } from "../_shared/iap-worker.js";
@@ -86,14 +86,6 @@ function programDetails(p: WixProgram): string {
   return raw.length > 140 ? `${raw.slice(0, 139).trimEnd()}…` : raw;
 }
 
-function programImage(p: WixProgram): string {
-  const desc = (p as { description?: unknown }).description;
-  const nested = desc && typeof desc === "object" ? (desc as { image?: { url?: string } }).image?.url : undefined;
-  const cover = (p as { coverImage?: unknown }).coverImage;
-  const coverUrl = typeof cover === "string" ? cover : (cover as { url?: string } | undefined)?.url;
-  return wixMediaUrl(coverUrl || p.image || nested);
-}
-
 function programMeta(p: WixProgram): string {
   const summary = (p as { contentSummary?: { stepCount?: number; sectionCount?: number } }).contentSummary;
   const bits: string[] = [];

package/templates/community-club/tier5-src/_shared/himi-media.ts

@@ -0,0 +1,29 @@
+// Cover selection is shared by list, detail and home so the same Wix object never
+// loses its image on navigation. Relative SDK imports are rewritten by the template generator.
+import { wixMediaUrl, WIX_LIST_IMAGE, type WixImageSize } from "@himalaya/wix-media";
+import type { WixGroup } from "@himalaya/wix-groups";
+import type { WixProgram } from "@himalaya/wix-online-programs";
+
+function firstImage(references: unknown[], size: WixImageSize): string {
+  for (const reference of references) {
+    const image = wixMediaUrl(reference, size);
+    if (image) return image;
+  }
+  return "";
+}
+
+export function groupImage(group: WixGroup, size: WixImageSize = WIX_LIST_IMAGE): string {
+  const cover = group.coverImage as {
+    url?: unknown;
+    image?: { url?: unknown; fileUrl?: unknown; mediaId?: unknown; id?: unknown };
+  } | undefined;
+  return firstImage([cover?.image?.url, cover?.image?.fileUrl, cover?.url, cover?.image?.mediaId, cover?.image?.id], size);
+}
+
+export function programImage(program: WixProgram, size: WixImageSize = WIX_LIST_IMAGE): string {
+  const cover = (program as { coverImage?: unknown }).coverImage;
+  const coverUrl = typeof cover === "string" ? cover : (cover as { url?: unknown } | undefined)?.url;
+  const description = (program as { description?: unknown }).description;
+  const nested = description && typeof description === "object" ? (description as { image?: { url?: unknown; id?: unknown } }).image : undefined;
+  return firstImage([coverUrl, program.image, nested?.url, nested?.id], size);
+}

package/templates/community-club/tier5-src/himi-branded-lite-group/index.ts

@@ -4,6 +4,8 @@ import { getGroup, joinGroup, leaveGroup, queryMembers as queryGroupMembers, typ
 import { getMember } from "@himalaya/wix-members";
 import { signedInEmail } from "../_shared/himi-account";
 import { initials } from "../_shared/himi-text.js";
+import { groupImage } from "../_shared/himi-media.js";
+import { WIX_DETAIL_IMAGE } from "@himalaya/wix-media";
 import { copyParam, stashCopy } from "../_shared/himi-copy.js";
 import { get as dbGet, upsert as dbUpsert, type DbEntity } from "@himalaya/local-db";
 import { isOfflineFailure, writeMayHaveLanded } from "../_shared/owner-load-error";
@@ -87,11 +89,6 @@ function inputId(): string {
   return input?.screenId?.startsWith("himi_group_") ? input.screenId.slice("himi_group_".length) : "";
 }
 
-function coverImage(group: WixGroup): string {
-  const cover = group.coverImage as { url?: string; image?: { url?: string } } | undefined;
-  return cover?.image?.url ?? cover?.url ?? "";
-}
-
 function membershipState(state: State, joined: boolean, signedIn: boolean): State {
   const isPublic = state.privacy === "Public" || state.privacy === "Unknown";
   return {
@@ -176,7 +173,7 @@ const svc = defineService<State, {
         const response = await getGroup(id);
         const group = ((response as unknown as { group?: WixGroup }).group ?? response) as WixGroup;
         const name = (group.name || copyParam("group.groupFallbackName", "Group")).trim();
-        const image = coverImage(group);
+        const image = groupImage(group, WIX_DETAIL_IMAGE);
         const count = group.membersCount ?? group.memberCount;
         const privacy = (group.privacyStatus || "UNKNOWN").toLowerCase();
         const privacyLabel = privacy[0].toUpperCase() + privacy.slice(1);

package/templates/community-club/tier5-src/himi-branded-lite-groups/index.ts

@@ -1,6 +1,6 @@
 import { defineService } from "../_shared/collection-service.js";
 import { queryGroups, type WixGroup } from "@himalaya/wix-groups";
-import { wixMediaUrl } from "@himalaya/wix-media";
+import { groupImage } from "../_shared/himi-media.js";
 import { copyParam, stashCopy } from "../_shared/himi-copy.js";
 import { getAll, upsert, type DbEntity } from "@himalaya/local-db";
 
@@ -45,23 +45,10 @@ interface State {
   noEmpty: boolean;
 }
 
-/** Social Groups stores a cover as `coverImage.image.mediaId` and returns NO url —
- *  the documented Image type has mediaId/width/height/preset only. Probing just
- *  `.url` therefore left every real cover unrendered (accent band + initials).
- *  Keep the url probes for other shapes, then derive from the media id. */
-function coverImage(group: WixGroup): string {
-  const cover = group.coverImage as
-    | { url?: string; image?: { url?: string; mediaId?: string; id?: string } }
-    | undefined;
-  return wixMediaUrl(
-    cover?.image?.url ?? cover?.url ?? cover?.image?.mediaId ?? cover?.image?.id,
-  );
-}
-
 function groupRow(group: WixGroup): GroupRow {
   const title = (group.name || copyParam("groups.groupFallbackName", "Group")).trim();
   const count = group.membersCount ?? group.memberCount;
-  const image = coverImage(group);
+  const image = groupImage(group);
   return {
     id: group.id || title,
     title,

package/templates/community-club/tier5-src/himi-branded-lite-home/index.ts

@@ -24,6 +24,7 @@ import { readSavedProducts, type SavedProduct } from "../_shared/himi-store-save
 import { loadStoreCategories, type StoreCategoryCard } from "../_shared/himi-store-categories.js";
 import { readSavedIds } from "../_shared/himi-blog-saved.js";
 import { wixMediaUrl } from "@himalaya/wix-media";
+import { groupImage, programImage } from "../_shared/himi-media.js";
 import { isWixVideoWebRefusal, listLatestVideos, videoCard, type WixVideoCard } from "@himalaya/wix-video";
 import { videoCaptionOf, withCaption, type CaptionFlags } from "../_shared/video-caption.js";
 
@@ -676,8 +677,7 @@ async function fetchHomePrograms(): Promise<ProgramCard[]> {
         const nestedTitle = desc && typeof desc === "object" ? (desc as { title?: string }).title : undefined;
         const nestedDetails = desc && typeof desc === "object" ? (desc as { details?: string }).details : undefined;
         const name = cleanTitle(p.settings?.title ?? nestedTitle ?? p.title) || copyParam("home.programFallbackName", "Program");
-        const cover = (p as { coverImage?: unknown }).coverImage;
-        const image = (typeof cover === "string" ? cover : (cover as { url?: string } | undefined)?.url) || p.image || "";
+        const image = programImage(p);
         const details = (p.settings?.description ?? nestedDetails ?? (typeof desc === "string" ? desc : "") ?? "")
           .replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
         return {
@@ -732,8 +732,7 @@ function homeTimeLabel(value?: string): string {
 function groupCard(group: WixGroup): GroupCard {
   const title = (group.name || copyParam("home.groupFallbackTitle", "Group")).trim();
   const count = group.membersCount ?? group.memberCount;
-  const cover = group.coverImage as { url?: string; image?: { url?: string } } | undefined;
-  const image = cover?.image?.url ?? cover?.url ?? "";
+  const image = groupImage(group);
   return {
     id: group.id || title,
     title,

package/templates/events-meetups/tier5-src/_shared/himi-media.ts

@@ -0,0 +1,29 @@
+// Cover selection is shared by list, detail and home so the same Wix object never
+// loses its image on navigation. Relative SDK imports are rewritten by the template generator.
+import { wixMediaUrl, WIX_LIST_IMAGE, type WixImageSize } from "@himalaya/wix-media";
+import type { WixGroup } from "@himalaya/wix-groups";
+import type { WixProgram } from "@himalaya/wix-online-programs";
+
+function firstImage(references: unknown[], size: WixImageSize): string {
+  for (const reference of references) {
+    const image = wixMediaUrl(reference, size);
+    if (image) return image;
+  }
+  return "";
+}
+
+export function groupImage(group: WixGroup, size: WixImageSize = WIX_LIST_IMAGE): string {
+  const cover = group.coverImage as {
+    url?: unknown;
+    image?: { url?: unknown; fileUrl?: unknown; mediaId?: unknown; id?: unknown };
+  } | undefined;
+  return firstImage([cover?.image?.url, cover?.image?.fileUrl, cover?.url, cover?.image?.mediaId, cover?.image?.id], size);
+}
+
+export function programImage(program: WixProgram, size: WixImageSize = WIX_LIST_IMAGE): string {
+  const cover = (program as { coverImage?: unknown }).coverImage;
+  const coverUrl = typeof cover === "string" ? cover : (cover as { url?: unknown } | undefined)?.url;
+  const description = (program as { description?: unknown }).description;
+  const nested = description && typeof description === "object" ? (description as { image?: { url?: unknown; id?: unknown } }).image : undefined;
+  return firstImage([coverUrl, program.image, nested?.url, nested?.id], size);
+}

package/templates/events-meetups/tier5-src/himi-branded-lite-group/index.ts

@@ -4,6 +4,8 @@ import { getGroup, joinGroup, leaveGroup, queryMembers as queryGroupMembers, typ
 import { getMember } from "@himalaya/wix-members";
 import { signedInEmail } from "../_shared/himi-account";
 import { initials } from "../_shared/himi-text.js";
+import { groupImage } from "../_shared/himi-media.js";
+import { WIX_DETAIL_IMAGE } from "@himalaya/wix-media";
 import { copyParam, stashCopy } from "../_shared/himi-copy.js";
 import { get as dbGet, upsert as dbUpsert, type DbEntity } from "@himalaya/local-db";
 import { isOfflineFailure, writeMayHaveLanded } from "../_shared/owner-load-error";
@@ -87,11 +89,6 @@ function inputId(): string {
   return input?.screenId?.startsWith("himi_group_") ? input.screenId.slice("himi_group_".length) : "";
 }
 
-function coverImage(group: WixGroup): string {
-  const cover = group.coverImage as { url?: string; image?: { url?: string } } | undefined;
-  return cover?.image?.url ?? cover?.url ?? "";
-}
-
 function membershipState(state: State, joined: boolean, signedIn: boolean): State {
   const isPublic = state.privacy === "Public" || state.privacy === "Unknown";
   return {
@@ -176,7 +173,7 @@ const svc = defineService<State, {
         const response = await getGroup(id);
         const group = ((response as unknown as { group?: WixGroup }).group ?? response) as WixGroup;
         const name = (group.name || copyParam("group.groupFallbackName", "Group")).trim();
-        const image = coverImage(group);
+        const image = groupImage(group, WIX_DETAIL_IMAGE);
         const count = group.membersCount ?? group.memberCount;
         const privacy = (group.privacyStatus || "UNKNOWN").toLowerCase();
         const privacyLabel = privacy[0].toUpperCase() + privacy.slice(1);

package/templates/events-meetups/tier5-src/himi-branded-lite-groups/index.ts

@@ -1,6 +1,6 @@
 import { defineService } from "../_shared/collection-service.js";
 import { queryGroups, type WixGroup } from "@himalaya/wix-groups";
-import { wixMediaUrl } from "@himalaya/wix-media";
+import { groupImage } from "../_shared/himi-media.js";
 import { copyParam, stashCopy } from "../_shared/himi-copy.js";
 import { getAll, upsert, type DbEntity } from "@himalaya/local-db";
 
@@ -45,23 +45,10 @@ interface State {
   noEmpty: boolean;
 }
 
-/** Social Groups stores a cover as `coverImage.image.mediaId` and returns NO url —
- *  the documented Image type has mediaId/width/height/preset only. Probing just
- *  `.url` therefore left every real cover unrendered (accent band + initials).
- *  Keep the url probes for other shapes, then derive from the media id. */
-function coverImage(group: WixGroup): string {
-  const cover = group.coverImage as
-    | { url?: string; image?: { url?: string; mediaId?: string; id?: string } }
-    | undefined;
-  return wixMediaUrl(
-    cover?.image?.url ?? cover?.url ?? cover?.image?.mediaId ?? cover?.image?.id,
-  );
-}
-
 function groupRow(group: WixGroup): GroupRow {
   const title = (group.name || copyParam("groups.groupFallbackName", "Group")).trim();
   const count = group.membersCount ?? group.memberCount;
-  const image = coverImage(group);
+  const image = groupImage(group);
   return {
     id: group.id || title,
     title,

package/templates/events-meetups/tier5-src/himi-branded-lite-home/index.ts

@@ -24,6 +24,7 @@ import { readSavedProducts, type SavedProduct } from "../_shared/himi-store-save
 import { loadStoreCategories, type StoreCategoryCard } from "../_shared/himi-store-categories.js";
 import { readSavedIds } from "../_shared/himi-blog-saved.js";
 import { wixMediaUrl } from "@himalaya/wix-media";
+import { groupImage, programImage } from "../_shared/himi-media.js";
 import { isWixVideoWebRefusal, listLatestVideos, videoCard, type WixVideoCard } from "@himalaya/wix-video";
 import { videoCaptionOf, withCaption, type CaptionFlags } from "../_shared/video-caption.js";
 
@@ -676,8 +677,7 @@ async function fetchHomePrograms(): Promise<ProgramCard[]> {
         const nestedTitle = desc && typeof desc === "object" ? (desc as { title?: string }).title : undefined;
         const nestedDetails = desc && typeof desc === "object" ? (desc as { details?: string }).details : undefined;
         const name = cleanTitle(p.settings?.title ?? nestedTitle ?? p.title) || copyParam("home.programFallbackName", "Program");
-        const cover = (p as { coverImage?: unknown }).coverImage;
-        const image = (typeof cover === "string" ? cover : (cover as { url?: string } | undefined)?.url) || p.image || "";
+        const image = programImage(p);
         const details = (p.settings?.description ?? nestedDetails ?? (typeof desc === "string" ? desc : "") ?? "")
           .replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
         return {
@@ -732,8 +732,7 @@ function homeTimeLabel(value?: string): string {
 function groupCard(group: WixGroup): GroupCard {
   const title = (group.name || copyParam("home.groupFallbackTitle", "Group")).trim();
   const count = group.membersCount ?? group.memberCount;
-  const cover = group.coverImage as { url?: string; image?: { url?: string } } | undefined;
-  const image = cover?.image?.url ?? cover?.url ?? "";
+  const image = groupImage(group);
   return {
     id: group.id || title,
     title,

package/templates/gym-fitness/tier5-src/_shared/himi-media.ts

@@ -0,0 +1,29 @@
+// Cover selection is shared by list, detail and home so the same Wix object never
+// loses its image on navigation. Relative SDK imports are rewritten by the template generator.
+import { wixMediaUrl, WIX_LIST_IMAGE, type WixImageSize } from "@himalaya/wix-media";
+import type { WixGroup } from "@himalaya/wix-groups";
+import type { WixProgram } from "@himalaya/wix-online-programs";
+
+function firstImage(references: unknown[], size: WixImageSize): string {
+  for (const reference of references) {
+    const image = wixMediaUrl(reference, size);
+    if (image) return image;
+  }
+  return "";
+}
+
+export function groupImage(group: WixGroup, size: WixImageSize = WIX_LIST_IMAGE): string {
+  const cover = group.coverImage as {
+    url?: unknown;
+    image?: { url?: unknown; fileUrl?: unknown; mediaId?: unknown; id?: unknown };
+  } | undefined;
+  return firstImage([cover?.image?.url, cover?.image?.fileUrl, cover?.url, cover?.image?.mediaId, cover?.image?.id], size);
+}
+
+export function programImage(program: WixProgram, size: WixImageSize = WIX_LIST_IMAGE): string {
+  const cover = (program as { coverImage?: unknown }).coverImage;
+  const coverUrl = typeof cover === "string" ? cover : (cover as { url?: unknown } | undefined)?.url;
+  const description = (program as { description?: unknown }).description;
+  const nested = description && typeof description === "object" ? (description as { image?: { url?: unknown; id?: unknown } }).image : undefined;
+  return firstImage([coverUrl, program.image, nested?.url, nested?.id], size);
+}