@wix/himalaya-cli 0.1557.0 → 0.1559.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

@@ -258,6 +258,14 @@ redirects, invalid data, source changes and disk errors remain failures.
   (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

@@ -73,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.
@@ -456,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;"
       },
       {
@@ -23983,7 +23983,7 @@
         "name": "WixParticipantState",
         "kind": "type",
         "jsdoc": "/** Participant lifecycle state. */",
-        "decl": "export type WixParticipantState =\n  | \"JOINED\"\n  | \"PAYMENT_PENDING\"\n  | \"APPROVAL_PENDING\"\n  | \"COMPLETED\"\n  | \"INVITED\"\n  | \"REMOVED\"\n  | string;"
+        "decl": "export type WixParticipantState =\n  | \"JOINED\"\n  | \"PAYMENT_PENDING\"\n  | \"ENROLLMENT_PENDING\"\n  | \"APPROVAL_PENDING\"\n  | \"COMPLETED\"\n  | \"INVITED\"\n  | \"REMOVED\"\n  | string;"
       },
       {
         "name": "WixParticipantPaymentPending",
@@ -23994,7 +23994,7 @@
       {
         "name": "WixJoinedParticipant",
         "kind": "interface",
-        "jsdoc": "/**\n * The participant JoinProgram hands back — a DIFFERENT entity from the roster\n * `WixParticipant` above, which is why it gets its own name. This one describes the join\n * outcome (`state`, `paymentPendingOptions`); the roster one describes who the member is\n * and how far they have got (`member`, `progress`, `enrollmentStatus`).\n *\n * Both were spelled `WixParticipant` until #2289, so TypeScript MERGED the two declarations\n * instead of keeping them apart. That is wrong twice over: the merged type carries every\n * field of both, so it describes neither response — and the merge is itself an error,\n * because `id` was required in the roster shape and optional here (TS2687 + TS2717).\n */",
+        "jsdoc": "/**\n * The compatibility result joinProgram returns — a DIFFERENT entity from the roster\n * `WixParticipant` above, which is why it gets its own name. This one describes the join\n * outcome (`state`, `paymentPendingOptions`); the roster one describes who the member is\n * and how far they have got (`member`, `progress`, `enrollmentStatus`).\n *\n * Both were spelled `WixParticipant` until #2289, so TypeScript MERGED the two declarations\n * instead of keeping them apart. That is wrong twice over: the merged type carries every\n * field of both, so it describes neither response — and the merge is itself an error,\n * because `id` was required in the roster shape and optional here (TS2687 + TS2717).\n */",
         "decl": "export interface WixJoinedParticipant {\n  id?: string;\n  programId?: string;\n  memberId?: string;\n  state?: WixParticipantState;\n  paymentPendingOptions?: WixParticipantPaymentPending;\n  joinedOptions?: { joinedDate?: string };\n}"
       },
       {
@@ -24006,14 +24006,14 @@
       {
         "name": "joinProgram",
         "kind": "function",
-        "jsdoc": "/** Join a program as the signed-in member. Branch on `participant.state`. */",
-        "decl": "export function joinProgram(programId: string): Promise<WixJoinProgramResponse>;",
-        "http": "POST /online-programs/v3/participants/{…}/join"
+        "jsdoc": "/**\n * Join as the signed-in member through Join Applications. Read the current\n * application first so an existing application is resumed without another create.\n * Approved paid applications prepare\n * SINGLE_PAYMENT and return the Wix Payments order as paymentPendingOptions.orderId.\n * mayPreparePayment rechecks the caller's checkout guard before creating that order.\n * @scope member\n */",
+        "decl": "export async function joinProgram(programId: string, options?: { mayPreparePayment?: () => boolean }): Promise<WixJoinProgramResponse>;",
+        "scope": "member"
       },
       {
         "name": "payableIdOf",
         "kind": "function",
-        "jsdoc": "/** The cashier handle to settle, or \"\" when the join needs no payment. */",
+        "jsdoc": "/** The cashier handle to settle, or \"\" when no payable order is available. */",
         "decl": "export function payableIdOf(participant?: WixJoinedParticipant): 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.1559.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": "10b9cfbdf8247c393305b2341b984702640668ff76c32fbc09ae2d8e"
 }

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

@@ -9,7 +9,7 @@ import { withOnlineWrites } from "../_shared/online-actions.js";
 // error card.
 //
 // Phase 2d — enrolling is NATIVE. `joinProgram` covers all three program kinds in
-// one call and the outcome is read off `participant.state`, not assumed:
+// the Join Applications API; its compatibility result exposes only confirmed outcomes:
 // a free/open program comes back JOINED with nothing to pay, a paid one comes back
 // PAYMENT_PENDING and settles on the shared in-app pay rail, and a private one comes
 // back APPROVAL_PENDING (the owner approves; there is nothing to charge). Any failure
@@ -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",
@@ -196,18 +190,26 @@ interface CommerceGuards {
 async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<string> {
   const blocked = () => iapPriceCopy("program").purchaseUnavailable;
   if (!guards.mayStart()) return blocked();
+  let preparationWithdrawn = false;
   try {
-    const joined = await joinProgram(inputId());
+    const joined = await joinProgram(inputId(), { mayPreparePayment: () => {
+      if (!guards.mayContinue()) preparationWithdrawn = true;
+      return !preparationWithdrawn;
+    } });
     const participant = joined.participant;
     const programState = (participant?.state ?? "").toUpperCase();
     if (programState === "APPROVAL_PENDING") {
       return copyParam("program.approvalPendingMessage", "Request sent — the host will approve your place.");
     }
+    if (programState === "ENROLLMENT_PENDING") {
+      return copyParam("program.enrollmentPendingMessage", "Your enrollment is processing — check back shortly.");
+    }
     const payable = payableIdOf(participant);
-    if (!payable) {
-      // Free / open program (or one already settled) ⇒ nothing to charge.
+    if (programState === "JOINED") {
+      // Only a confirmed participant is enrolled; absent payment data is not success.
       return copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
     }
+    if (programState !== "PAYMENT_PENDING" || !payable) throw new Error("Program enrollment is not ready");
     const msid = await wixPlatformSession.signedInstanceStatus().then((s) => s.msid ?? "").catch(() => "");
     // Re-read before each step that commits money: a route that settles meanwhile wins.
     let withdrawn = false;
@@ -227,12 +229,8 @@ async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<
       // which is precisely the dead-end the two-rail design exists to prevent
       // (and which the cart/plans/events flows each guard with a test).
       //
-      // There is no `programsCheckout` redirect intent. `ecomOrderPaymentRequest`
-      // is the only payment-request-shaped one, and a program's `purchaseFlowId`
-      // is a payment-request handle, so that is what we hand it. If that mapping
-      // is ever wrong the call throws, we degrade to the same site-directing
-      // message as before, and nothing regresses — but when it is right, a
-      // wallet-less site can actually sell the program IN-APP.
+      // Join Applications returns a Wix Payments order id; the payment-request
+      // redirect uses that same order handle on the hosted rail.
       cashierUrl: async () => {
         if (!stillAllowed()) return undefined;
         const redirect = await createRedirectSession({
@@ -243,10 +241,13 @@ async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<
       },
     });
     if (withdrawn) return blocked();
-    if (pay.kind === "paid") return copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
+    if (pay.kind === "paid") return pay.pending
+      ? copyParam("program.paymentPendingMessage", "Payment is processing — enrollment will be confirmed after payment.")
+      : copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
     if (pay.kind === "handoff") return "";
     if (pay.kind === "cancelled") return copyParam("program.joinCancelledMessage", "Payment cancelled — you haven't enrolled.");
   } catch {
+    if (preparationWithdrawn) return blocked();
     // fall through to the site-directing message
   }
   return copyTemplate("program.joinOnSiteMessage", "Enrolment happens on the website — visit the site to join {name}.", { name });

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,