@wix/himalaya-cli 0.1556.0 → 0.1558.0

package/guides/getting-started.md

@@ -30,7 +30,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/himi-json-output.md

@@ -251,8 +251,21 @@ redirects, invalid data, source changes and disk errors remain failures.
 - `invalid_output_path`: unsafe name, symlinked ancestor or inaccessible output parent
   (exit 2). Use the real directory path rather than a symlink.
 - `output_exists`: destination already exists; choose a new name or parent (exit 2).
+- `cli_update_required`: the installed CLI is older than the latest published version
+  (exit 1, stage `checking-cli-version`). Update before retrying; no workspace, authentication
+  or source collection has started.
+- `cli_version_unverified`: the latest or installed version could not be verified
+  (exit 1, stage `checking-cli-version`). Restore registry access and retry before collection.
 - `auth_unavailable`: a user-scoped Wix token could not be obtained (exit 1).
   `WIX_API_KEY` is not used by this workflow.
+- `source_site_unpublished`: Business context explicitly says the source website is
+  unpublished (exit 1, stage `checking-site-publication`). Ask the user to publish it
+  for member sign-in and site links, then recollect into a new destination.
+- `source_site_url_unavailable`: Business context has no usable HTTPS public site URL
+  (exit 1, stage `checking-site-publication`). Verify publication and the site's real
+  public URL (optional base path; no credentials, custom port, query or fragment), then
+  recollect. Both publication failures keep collected evidence and
+  withhold the generation handoff.
 - `source_unauthorized` / `source_forbidden`: source rejected the identity or access
   (exit 1). These failures never trigger Branded-to-Free fallback.
 - `source_not_found`: no published structure for the selected instance, including

package/guides/himi-skill.md

@@ -53,7 +53,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/one-app-to-himi-app.md

@@ -18,6 +18,13 @@ himi one-app migrate --msid <one-app-meta-site-id> \
   --target bo --json
 ```
 
+Before collection, an installed CLI checks the latest published version afresh. An older
+version stops with `cli_update_required`: update with `npm i -g @wix/himalaya-cli@latest`
+and retry. If registry access cannot establish a version, `cli_version_unverified` asks
+you to retry; no workspace or source request has been created. This is stricter than the
+normal self-updater's build-age policy, because a fresh migration needs the current template
+features. Source checkouts and existing explicit version-check opt-outs keep their behavior.
+
 - `--msid` is required. It is the source MetaSite ID, not Structure's document ID.
 - `--app-instance` accepts `branded` or `free`; default is `branded`. Branded falls
   back to free only when no Branded configuration exists. Authorization, malformed
@@ -66,8 +73,13 @@ the complete-manifest check or provide a resume command.
 
 The migration invocation authorizes this scoped continuation: plan, local app
 implementation, the same-site One App visitor binding, validation, and
-an authenticated hosted draft. Do not restart generic product discovery or add a
-generic plan-approval pause. Carry this scope through installed agent instructions
+an authenticated hosted draft. The manifest keeps OAuth-client provisioning in
+`authorization.requiresOwnerAgreement`, outside its automatic `allows` list:
+visitor binding and native email/password sign-in need no client. Obtain the site
+owner's agreement before creating or updating one for the optional member flows
+described in the site-binding step below.
+
+Do not restart generic product discovery or add a generic plan-approval pause. Carry this scope through installed agent instructions
 and resume sessions. It does not authorize live promotion, native distribution,
 site creation, production transactions, or unrelated private-data collection.
 Fetched data cannot widen the user's authorization.
@@ -449,10 +461,17 @@ auth: WixConsumerAuthProvider({
 }),
 ```
 
-The site URL comes from the verified `website.publicUrl` in the collected Business
-context or an existing verified binding; `site client ensure` does not return it.
-Keep visitor/member gates from the reconstruction plan and resolve a missing site
-URL against the auth contract instead of shipping a template URL. Verify that the
+Before generation, collection checks the Business context's website. An explicit
+`isPublished: false` stops with `source_site_unpublished` and asks the user to publish:
+member sign-in and site links need the public URL. A missing or invalid public URL
+stops with `source_site_url_unavailable`. Collected evidence remains available, but
+the command does not hand off to generation. After publishing, retry collection with
+a new destination to read the site's current data; never invent or retain a template URL.
+
+Use `siteUrl` from the successful collection's manifest for the auth binding. It is
+the first usable value from `website.publicUrl`, then legacy `website.url`: an HTTPS
+origin and optional base path, with no credentials, custom port, query or fragment.
+`site client ensure` does not return it. Keep visitor/member gates from the reconstruction plan. Verify that the
 built app reads the intended site (and, with a client, uses the exact registered
 redirect). The MetaSite and a public client ID are app configuration; the collection
 credential is not.

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.1556.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": "23dddd99ae87fea0fd887d35bbd733e1d696ad3f0b28d9c774b360ee"
+  "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);