@wix/himalaya-cli 0.1575.0 → 0.1577.0

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

@@ -0,0 +1,658 @@
+// himi_member_programs — the MEMBER'S programs list: every published program decorated with the
+// signed-in member's standing (Joined / Completed / Ended / Pending / Approved / Suspended), a
+// progress bar once they started, the App Store or Wix price before they join, and two filters —
+// "All programs / Programs I joined" and a program category. The counterpart of the One App
+// `MemberChallengesList` section (wix-one-app-achievements): same reads, same card rules.
+//
+// Reads per page (all v3, member identity): queryPrograms (the page) → in parallel
+// getParticipationStats (counts), the member's participations (one cursor walk, cached for the
+// scope) and, for an unjoined private, secret or priced program, its current join application. The
+// "joined" filter walks the participations FIRST and queries programs by id, as the One App does.
+//
+// Not a `defineBackendCollection`: the shared collection chrome replaces the row with its generic
+// card and carries one filter axis, while this card needs a status label over the cover, a
+// ProgressBar and two filters. The shared query controller is reused as it is.
+import { defineService as register, navigate } from "@himalaya/state";
+import {
+  queryPrograms, getParticipationStats, queryMemberParticipants, getCurrentJoinApplication, listProgramCategories,
+  type WixProgram, type WixProgramFull, type WixParticipant, type WixJoinApplication, type WixProgramCategory,
+} from "@himalaya/wix-online-programs";
+import { getMyMember } from "@himalaya/wix-members";
+import { iapPriceFields, onlineProgramItem, type IapPollDirective } from "@himalaya/iap";
+import { createIapCommerce } from "@himalaya/iap-checkout";
+import { createCollectionQuery, type CollectionPage, type CollectionQueryState } from "../_shared/collection-query.js";
+import { memberAccess, memberAccessChanged, memberAccessDenied, type MemberAccess } from "../_shared/member-access.js";
+import { cleanTitle, initials } from "../_shared/himi-text.js";
+import { programImage } from "../_shared/himi-media.js";
+import { descriptionBody } from "../_shared/rich-body.js";
+import { programDescription } from "../_shared/program-description.js";
+import { isNotFoundError } from "../_shared/detail-presence.js";
+import { copyParam, copyTemplate, stashCopy } from "../_shared/himi-copy.js";
+import { formatCurrency, formatDateMedium } from "../_shared/engine-intl.js";
+import { iapPriceCopy, resetUnhydratedKeysOnOlderRuntime } from "../_shared/iap-worker.js";
+
+export const SERVICE = "himiBrandedMemberPrograms";
+const PAGE_SIZE = 20;
+const DETAIL_SCREEN = "himi_program";
+
+// ── Row model ────────────────────────────────────────────────────────────────
+
+/** The member's standing on one program — the One App participant/application states, folded. */
+export type Standing = "none" | "joined" | "completed" | "finished" | "suspended" | "pending" | "approved" | "invited";
+
+/** A card as loaded, before pricing. */
+export interface ProgramContent {
+  id: string;
+  name: string;
+  description: string;
+  image: string;
+  initial: string;
+  hasImage: boolean;
+  noImage: boolean;
+  timelineLine: string;
+  /** "Public · 12 participants" — hidden once joined or over, as on the One App card. */
+  accessLine: string;
+  standing: Standing;
+  statusLabel: string;
+  statusIcon: string;
+  statusColor: string;
+  hasStatus: boolean;
+  noStatus: boolean;
+  /** The sentence under the lines: "Join request sent", "Finished with 40% progress", … */
+  descriptionLine: string;
+  /** 0..1 — shown as a ProgressBar while joined and started. */
+  progress: number;
+  progressLabel: string;
+  hasProgress: boolean;
+  noProgress: boolean;
+  /** The row may show a price: not joined, not over. */
+  pricable: boolean;
+  /** The commerce (Wix) price as text, for the regular route; "" when free or unknown. */
+  commercePrice: string;
+  free: boolean;
+  actionLabel: string;
+  actionDisabled: boolean;
+  detailScreenId: string;
+  categoryIds: string[];
+}
+export interface ProgramRow extends ProgramContent {
+  priceLine: string;
+  hasPrice: boolean;
+  noPrice: boolean;
+}
+
+interface Option { id: string; label: string }
+
+export interface State {
+  status: "loading" | "ready" | "error";
+  rows: ProgramRow[];
+  isLoading: boolean;
+  notLoading: boolean;
+  isErrored: boolean;
+  notErrored: boolean;
+  noEmpty: boolean;
+  hideList: boolean;
+  emptyText: string;
+  errorText: string;
+  identityLine: string;
+  needsSignIn: boolean;
+  noSignIn: boolean;
+  nextCursor: string;
+  noMore: boolean;
+  noPageError: boolean;
+  loadingMore: boolean;
+  statusFilter: "all" | "joined";
+  statusOptions: Option[];
+  hideStatusFilter: boolean;
+  categoryId: string;
+  categoryChips: Option[];
+  hideCategoryFilter: boolean;
+  hidePriceRetry: boolean;
+  priceRetryText: string;
+  summary: string;
+  _poll?: IapPollDirective;
+}
+
+// ── Program fields (v3 Program DTO; the list and the detail share the shape) ─────
+
+const full = (p: WixProgram): WixProgramFull => p as WixProgramFull;
+
+function programTitle(p: WixProgram): string {
+  return cleanTitle(p.description?.title ?? p.settings?.title ?? p.title ?? p.details?.title)
+    || copyParam("memberPrograms.programFallbackName", "Program");
+}
+function programDetails(p: WixProgram): string {
+  // The body may be a Ricos document or serialized text: read it the way the catalog and detail do.
+  const raw = descriptionBody(programDescription(p)).bodyText.replace(/\s+/g, " ").trim();
+  return raw.length > 140 ? `${raw.slice(0, 139).trimEnd()}…` : raw;
+}
+function programStatus(p: WixProgram): string {
+  return (p.status ?? p.state ?? "").toUpperCase();
+}
+const isEnded = (p: WixProgram) => programStatus(p) === "ENDED" || programStatus(p) === "FINISHED";
+const isDraft = (p: WixProgram) => programStatus(p) === "DRAFT";
+function accessType(p: WixProgram): string {
+  return (full(p).restrictions?.accessType ?? "PUBLIC").toUpperCase();
+}
+function maxParticipants(p: WixProgram): number {
+  const value = Number((full(p).restrictions as { maxParticipants?: unknown } | undefined)?.maxParticipants ?? 0);
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+function stepCount(p: WixProgram): number {
+  const value = Number(full(p).contentSummary?.stepCount ?? 0);
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+function categoryIdsOf(p: WixProgram): string[] {
+  const ids = (p as { categoryIds?: unknown }).categoryIds;
+  return Array.isArray(ids) ? ids.filter((id): id is string => typeof id === "string") : [];
+}
+/** The commerce price as text — "" when the program is free or the price is malformed. */
+function commercePriceOf(p: WixProgram): string {
+  const price = full(p).price;
+  const amount = Number(price?.value);
+  if (!price?.currency || !Number.isFinite(amount) || amount <= 0) return "";
+  try { return formatCurrency(amount, price.currency); } catch { return `${price.value} ${price.currency}`; }
+}
+
+function date(value?: string): string {
+  if (!value) return "";
+  const at = new Date(value);
+  return Number.isNaN(at.getTime()) ? "" : formatDateMedium(at);
+}
+function daysBetween(fromIso: string, now: number): number {
+  const from = Date.parse(fromIso);
+  return Number.isFinite(from) ? Math.floor((now - from) / 86_400_000) : NaN;
+}
+
+// ── Member standing ──────────────────────────────────────────────────────────
+
+function standingOf(p: WixProgram, participant: WixParticipant | undefined, application: WixJoinApplication | undefined): Standing {
+  if (participant) {
+    const progress = (participant.progressStatus ?? "").toUpperCase();
+    const enrollment = (participant.enrollmentStatus ?? "").toUpperCase();
+    if (progress === "COMPLETED") return "completed";
+    if (progress === "FAILED" || isEnded(p)) return "finished";
+    if (enrollment === "SUSPENDED") return "suspended";
+    return "joined";
+  }
+  const status = (application?.status ?? "").toUpperCase();
+  const payment = (application?.paymentStatus ?? "").toUpperCase();
+  if (status === "APPROVAL_PENDING") return "pending";
+  if (status === "APPROVED") {
+    // The same reading as joinProgram: a free or settled approval is enrolling, and an offline payment
+    // waits on the owner. Only an approval that still owes money asks the member to pay.
+    if (payment === "NO_PAYMENT_REQUIRED" || payment === "PAYMENT_SUCCESSFUL") return application?.participantId ? "joined" : "pending";
+    if (payment === "PENDING_OWNER_APPROVAL") return "pending";
+    return "approved";
+  }
+  if (status === "PAYMENT_PENDING") return "approved";
+  if (status === "INVITED") return "invited";
+  return "none";
+}
+
+const STATUS: Record<Exclude<Standing, "none">, { key: string; fallback: string; icon: string; color: string }> = {
+  joined: { key: "memberPrograms.status.joined", fallback: "Joined", icon: "checkmark", color: "accentPrimary" },
+  completed: { key: "memberPrograms.status.completed", fallback: "Program complete", icon: "trophy", color: "success" },
+  finished: { key: "memberPrograms.status.ended", fallback: "Program ended", icon: "flag", color: "textSecondary" },
+  suspended: { key: "memberPrograms.status.suspended", fallback: "Participation suspended", icon: "close", color: "warning" },
+  pending: { key: "memberPrograms.status.pending", fallback: "Pending request", icon: "clock", color: "warning" },
+  approved: { key: "memberPrograms.status.approved", fallback: "Request approved", icon: "checkmark", color: "success" },
+  invited: { key: "memberPrograms.status.invited", fallback: "Invited", icon: "mail", color: "accentPrimary" },
+};
+
+function timelineLine(p: WixProgram, participant: WixParticipant | undefined, standing: Standing, now: number): string {
+  const timeline = full(p).timeline;
+  const duration = Number(timeline?.durationInDays ?? 0);
+  const days = Number.isFinite(duration) && duration > 0 ? duration : 0;
+  const started = participant?.enrollmentInfo?.startDate;
+  if ((standing === "joined" || standing === "suspended") && started && daysBetween(started, now) >= 0) {
+    const day = daysBetween(started, now) + 1;
+    return days
+      ? copyTemplate("memberPrograms.timeline.startedOf", "Started {date} · day {day} of {days}", { date: date(started), day, days })
+      : copyTemplate("memberPrograms.timeline.started", "Started {date} · day {day}", { date: date(started), day });
+  }
+  if (standing === "completed" || standing === "finished") {
+    // The deadline is the enrollment's scheduled end: it is the end date only once it has passed.
+    const ended = participant?.enrollmentInfo?.deadline;
+    return ended && Date.parse(ended) <= now ? copyTemplate("memberPrograms.timeline.ended", "Ended {date}", { date: date(ended) }) : "";
+  }
+  if (timeline?.selfPaced) {
+    return days
+      ? copyTemplate("memberPrograms.timeline.days", "{days} days · self-paced", { days })
+      : copyParam("memberPrograms.timeline.selfPaced", "Self-paced");
+  }
+  if (timeline?.startDate) {
+    const start = date(timeline.startDate);
+    if (!start) return "";
+    return days
+      ? copyTemplate("memberPrograms.timeline.scheduled", "Starts {date} · {days} days", { date: start, days })
+      : copyTemplate("memberPrograms.timeline.starts", "Starts {date}", { date: start });
+  }
+  return days ? copyTemplate("memberPrograms.timeline.daysOnly", "{days} days", { days }) : "";
+}
+
+function accessLine(p: WixProgram, participants: number | undefined): string {
+  const access = accessType(p);
+  const label = access === "PRIVATE" ? copyParam("memberPrograms.access.private", "Private")
+    : access === "SECRET" ? copyParam("memberPrograms.access.secret", "Secret")
+    : copyParam("memberPrograms.access.public", "Public");
+  if (participants === undefined) return label;
+  const count = participants === 1
+    ? copyParam("memberPrograms.participantsOne", "1 participant")
+    : copyTemplate("memberPrograms.participantsMany", "{count} participants", { count: participants });
+  return `${label} · ${count}`;
+}
+
+function progressOf(p: WixProgram, participant: WixParticipant | undefined): number {
+  const done = Number(participant?.progress?.totalStepsCompleted ?? 0);
+  const total = Number(participant?.progress?.totalStepsAvailable ?? 0) || stepCount(p);
+  const pct = Number(participant?.progress?.completionPercentage);
+  if (Number.isFinite(pct) && pct > 0) return Math.min(1, pct / 100);
+  if (!total || !Number.isFinite(done) || done <= 0) return 0;
+  return Math.min(1, done / total);
+}
+
+function programContent(o: { program: WixProgram; participant?: WixParticipant; application?: WixJoinApplication; applicationUnknown?: boolean; participationsUnknown?: boolean; participants?: number; member: boolean; now: number }): ProgramContent {
+  const { program: p } = o;
+  const standing = standingOf(p, o.participant, o.application);
+  const over = standing === "completed" || standing === "finished";
+  const joined = standing === "joined" || standing === "suspended";
+  const status = standing === "none" ? undefined : STATUS[standing];
+  const progress = joined ? progressOf(p, o.participant) : 0;
+  const pct = Math.round(progress * 100);
+  const started = joined && progress > 0;
+  const image = programImage(p);
+  const name = programTitle(p);
+  // An ended program with no known participation (a degraded participations read) offers no join and no price.
+  const closed = standing === "none" && isEnded(p);
+  const capped = standing === "none" && !closed && maxParticipants(p) > 0;
+  const countFull = capped && o.participants !== undefined && o.participants >= maxParticipants(p);
+  // Not knowing the count of a capped program, or whether an application exists, the card claims neither
+  // "Join" nor "Program is full": View, and the detail screen decides.
+  // A failed participations read leaves every unjoined-looking card unknown too: the member may be in it.
+  const standingUnknown = standing === "none" && o.member
+    && (!!o.applicationUnknown || !!o.participationsUnknown || (capped && o.participants === undefined));
+  // "Full" only for a member whose own standing is known: an unknown one may already be in it.
+  const limitReached = countFull && !standingUnknown;
+  const commercePrice = commercePriceOf(p);
+  const descriptionLine = standing === "completed" ? copyParam("memberPrograms.line.completed", "Completed")
+    : standing === "finished" ? copyTemplate("memberPrograms.line.finished", "Finished with {pct}% progress", { pct: Math.round(progressOf(p, o.participant) * 100) })
+    : standing === "pending" ? copyParam("memberPrograms.line.pending", "Join request sent")
+    : standing === "approved" ? copyParam("memberPrograms.line.approved", "Request approved · complete your payment")
+    : standing === "invited" ? copyParam("memberPrograms.line.invited", "You're invited to join")
+    : standing === "suspended" ? copyParam("memberPrograms.line.suspended", "Your participation is paused")
+    : "";
+  // An invitation is accepted on the website (joinProgram cannot accept one), so an invited card's CTA is View.
+  const actionLabel = !o.member ? copyParam("memberPrograms.action.view", "View")
+    : limitReached ? copyParam("memberPrograms.action.full", "Program is full")
+    : joined || over || closed || standing === "pending" || standing === "invited" || standingUnknown ? copyParam("memberPrograms.action.view", "View")
+    : standing === "approved" ? copyParam("memberPrograms.action.pay", "Complete payment")
+    : accessType(p) === "PRIVATE" ? copyParam("memberPrograms.action.request", "Request to join")
+    // Invite-only: with no invitation there is nothing to join from here.
+    : accessType(p) === "SECRET" ? copyParam("memberPrograms.action.view", "View")
+    : commercePrice ? copyParam("memberPrograms.action.joinPay", "Join & pay")
+    : copyParam("memberPrograms.action.join", "Join");
+  return {
+    id: p.id, name, description: programDetails(p), image, initial: initials(name) || "P", hasImage: !!image, noImage: !image,
+    timelineLine: timelineLine(p, o.participant, standing, o.now),
+    accessLine: joined || over || closed ? "" : accessLine(p, o.participants),
+    standing,
+    statusLabel: status ? copyParam(status.key, status.fallback) : "", statusIcon: status?.icon ?? "", statusColor: status?.color ?? "textSecondary",
+    hasStatus: !!status, noStatus: !status,
+    descriptionLine,
+    progress, progressLabel: started ? copyTemplate("memberPrograms.progressLabel", "{pct}% complete", { pct }) : "",
+    hasProgress: started, noProgress: !started,
+    pricable: !joined && !over && !closed && !descriptionLine,
+    commercePrice, free: !commercePrice,
+    // Only a member's CTA is the join action; a guest's "View" stays a navigation.
+    actionLabel, actionDisabled: limitReached && o.member,
+    detailScreenId: DETAIL_SCREEN,
+    categoryIds: categoryIdsOf(p),
+  };
+}
+
+// ── Reads ────────────────────────────────────────────────────────────────────
+
+interface Scope { email: string; memberId: string; scope: string }
+interface PageMeta extends Record<string, unknown> { email: string; memberId: string; scope: string; needsSignIn: boolean; joinedFilter: boolean }
+
+type Participations = Map<string, WixParticipant>;
+/** The member's participations for this scope — walked once per first page, reused by its later pages. */
+let participationCache: { key: string; value: Participations } | undefined;
+/** Keyed by email AND tenant scope: one email is a different Wix member on every site. */
+let memberIdCache: { email: string; scope: string; id: string } | undefined;
+/** Whether the last scope read had a signed-in member — survives a failed page, whose metadata the controller drops. */
+let memberSeen = false;
+
+async function resolveScope(): Promise<Scope> {
+  const access: MemberAccess = await memberAccess();
+  memberSeen = !!access.email;
+  if (!access.email) return { email: "", memberId: "", scope: "" };
+  let cached = memberIdCache;
+  if (cached?.email !== access.email || cached.scope !== access.scope) {
+    // A failed lookup is an unknown id, like a record with none: the catalog degrades, the joined filter errors.
+    const response = await getMyMember().catch(() => undefined);
+    cached = { email: access.email, scope: access.scope, id: String(response?.member?.id ?? "") };
+    // A member record with no id yet is not an answer to keep: the next read asks again.
+    memberIdCache = cached.id ? cached : undefined;
+  }
+  return { email: access.email, memberId: cached.id, scope: access.scope };
+}
+// Email and tenant scope ARE the member; the id is derived from them, and may only now have resolved
+// (a lookup that failed once, then succeeded) — the same member, not a changed one.
+const sameScope = (a: Scope, b: Scope) => a.email === b.email && a.scope === b.scope;
+
+async function walkParticipations(memberId: string): Promise<Participations> {
+  const byProgram: Participations = new Map();
+  let cursor: string | undefined;
+  for (let page = 0; page < 50; page++) {
+    const response = await queryMemberParticipants({ memberId, cursor, limit: 100 });
+    for (const participant of response.participants ?? []) {
+      if (!participant.programId || participant.memberId !== memberId) continue;
+      const current = byProgram.get(participant.programId);
+      // Duplicate enrollments: the latest createdDate wins (the One App's rule).
+      if (!current || Date.parse(participant.createdDate ?? "") > Date.parse(current.createdDate ?? "")) byProgram.set(participant.programId, participant);
+    }
+    const paging = response.pagingMetadata as { hasNext?: boolean; cursors?: { next?: string | null } } | undefined;
+    const next = paging?.cursors?.next ?? "";
+    if (paging?.hasNext === false) break;
+    // More pages promised but none reachable: the map is incomplete, and an incomplete map is a failed read.
+    if (!next) { if (paging?.hasNext) throw new Error("Participants response is missing its next-page cursor"); break; }
+    if (next === cursor) throw new Error("Participants response repeated its cursor");
+    cursor = next;
+    // The last page allowed still points at another: what was read is not the whole membership.
+    if (page === 49) throw new Error("Participants walk truncated");
+  }
+  return byProgram;
+}
+/** `required` (the "Programs I joined" filter) lets a failure through: that list IS the member's
+ *  participations. The catalog degrades instead — every program shows, without the member's standing. */
+async function participationsFor(scope: Scope, firstPage: boolean, required: boolean): Promise<{ map: Participations; complete: boolean }> {
+  // A guest has no participations; a signed-in member whose id is unknown has unknown ones.
+  if (!scope.memberId) {
+    if (scope.email && required) throw new Error("Current member unavailable");
+    return { map: new Map(), complete: !scope.email };
+  }
+  const key = `${scope.memberId}\u0000${scope.scope}`;
+  if (!firstPage && participationCache?.key === key) return { map: participationCache.value, complete: true };
+  try {
+    const value = await walkParticipations(scope.memberId);
+    participationCache = { key, value };
+    return { map: value, complete: true };
+  } catch (error) {
+    if (required) throw error;
+    participationCache = undefined;
+    return { map: new Map(), complete: false };
+  }
+}
+
+/** Only where an application can exist: an unjoined PRIVATE, SECRET (invite-only) or priced program, for a member. */
+async function applicationsFor(programs: WixProgram[], participations: Participations, scope: Scope): Promise<{ map: Map<string, WixJoinApplication>; unknown: Set<string> }> {
+  const result = new Map<string, WixJoinApplication>();
+  // A failed read is not "no application": those programs make no join claim (see programContent).
+  const unknown = new Set<string>();
+  if (!scope.memberId) return { map: result, unknown };
+  const candidates = programs.filter((p) => !participations.has(p.id) && (accessType(p) === "PRIVATE" || accessType(p) === "SECRET" || !!commercePriceOf(p)));
+  const settled = await Promise.allSettled(candidates.map((p) => getCurrentJoinApplication(p.id)));
+  settled.forEach((outcome, i) => {
+    // 404 / NOT_FOUND is the endpoint's "this member never applied"; any other rejection is unknown.
+    if (outcome.status === "rejected") { if (!isNotFoundError(outcome.reason)) unknown.add(candidates[i].id); }
+    else if (outcome.value.joinApplication?.status) result.set(candidates[i].id, outcome.value.joinApplication);
+  });
+  return { map: result, unknown };
+}
+
+async function statsFor(programs: WixProgram[]): Promise<Map<string, number>> {
+  const counts = new Map<string, number>();
+  // Only a count something reported: an absent one stays unknown, never a fabricated 0.
+  for (const p of programs) {
+    const own = Number(p.participantsCount ?? p.participants?.count);
+    if (Number.isFinite(own)) counts.set(p.id, own);
+  }
+  try {
+    const response = await getParticipationStats(programs.map((p) => p.id));
+    for (const stat of response.participationStats ?? []) {
+      if (stat.programId && typeof stat.participantsCount === "number") counts.set(stat.programId, stat.participantsCount);
+    }
+  } catch { /* the program's own count stands */ }
+  return counts;
+}
+
+let categories: WixProgramCategory[] | undefined;
+let categoriesFailed = false;
+async function loadCategories(): Promise<void> {
+  try {
+    const response = await listProgramCategories();
+    categories = (response.categories ?? []).filter((c) => c.id && c.label);
+    categoriesFailed = false;
+    // A picked category the site no longer has would keep the query filtered behind a hidden control.
+    if (categoryId && !categories.some((c) => c.id === categoryId)) categoryId = "";
+  } catch {
+    categoriesFailed = categories === undefined;
+  }
+}
+
+/** The controller's criteria.filter carries both axes: "<status>|<categoryId>". */
+const encodeFilter = (status: "all" | "joined", categoryId: string) => `${status}|${categoryId}`;
+function decodeFilter(filter: string): { status: "all" | "joined"; categoryId: string } {
+  const [status, ...rest] = filter.split("|");
+  return { status: status === "joined" ? "joined" : "all", categoryId: rest.join("|") };
+}
+
+let statusFilter: "all" | "joined" = "all";
+let categoryId = "";
+let pageScope: Scope | undefined;
+
+async function fetchPage(filter: string, cursor: string): Promise<CollectionPage<ProgramContent>> {
+  const scope = await resolveScope();
+  if (cursor && (!pageScope || !sameScope(pageScope, scope))) throw memberAccessChanged();
+  const { status, categoryId: picked } = decodeFilter(filter);
+  const metadata: PageMeta = { email: scope.email, memberId: scope.memberId, scope: scope.scope, needsSignIn: !scope.email, joinedFilter: status === "joined" };
+  const now = Date.now();
+  if (!cursor) await loadCategories();
+  // Built from the refreshed list: a category the site no longer has (reset by loadCategories) filters nothing.
+  const category = picked && categories && !categories.some((c) => c.id === picked) ? "" : picked;
+  const { map: participations, complete: participationsKnown } = await participationsFor(scope, !cursor, status === "joined");
+  const programFilter: Record<string, unknown> = { status: { $in: ["PUBLISHED", "ENDED"] } };
+  if (category) programFilter.categoryIds = { $hasSome: [category] };
+  if (status === "joined") {
+    if (!participations.size) return { items: [], nextCursor: "", metadata };
+    programFilter.id = { $in: [...participations.keys()] };
+  }
+  // A page whose every program is dropped (ended and never joined) would leave the list hidden with
+  // nothing on screen to call loadMore, so read on until a page has rows or the catalog ends.
+  let pageCursor = cursor;
+  for (let read = 0; ; read++) {
+    // A cursor page carries only the cursor — it already encodes the filter and sort — as the
+    // participants query of the same service does.
+    const response = await queryPrograms(pageCursor
+      ? { cursorPaging: { limit: PAGE_SIZE, cursor: pageCursor } }
+      : { filter: programFilter, sort: [{ fieldName: "createdDate", order: "DESC" }], cursorPaging: { limit: PAGE_SIZE } });
+    const after = await resolveScope();
+    if (!sameScope(scope, after)) throw memberAccessChanged();
+    const programs = (response.programs ?? []).filter((p) => p.id && !isDraft(p))
+      // An ended program the member never joined is not theirs to see (the One App's visibility rule) —
+      // applied only when the member's participations are known, so a degraded read hides nothing they joined.
+      .filter((p) => !isEnded(p) || participations.has(p.id) || !participationsKnown);
+    const pagingMetadata = response.pagingMetadata as { hasNext?: boolean; cursors?: { next?: string | null } } | undefined;
+    // A last page may still carry a cursor: `hasNext: false` wins, as in the catalog bundle.
+    const nextCursor = pagingMetadata?.hasNext === false ? "" : pagingMetadata?.cursors?.next ?? "";
+    if (pagingMetadata?.hasNext && !nextCursor) throw new Error("Programs response is missing its next-page cursor");
+    if (!programs.length && nextCursor && nextCursor !== pageCursor) {
+      if (read + 1 < MAX_EMPTY_READS) { pageCursor = nextCursor; continue; }
+      // Past the cap, end the list rather than hand back an empty page with a cursor nothing can load.
+      return { items: [], nextCursor: "", metadata };
+    }
+    const [counts, applications] = await Promise.all([statsFor(programs), applicationsFor(programs, participations, scope)]);
+    const items = programs.map((p) => programContent({ program: p, participant: participations.get(p.id), application: applications.map.get(p.id), applicationUnknown: applications.unknown.has(p.id), participationsUnknown: !participationsKnown, participants: counts.get(p.id), member: !!scope.memberId, now }));
+    // A revalidating load publishes nothing until it settles, so page 1 records the scope its later pages
+    // are read under here, not only from the published snapshot.
+    if (!cursor) pageScope = scope;
+    return { items, nextCursor, metadata };
+  }
+}
+/** How many all-dropped pages one fetch reads, in all, before it ends the list. */
+const MAX_EMPTY_READS = 50;
+
+// ── State ────────────────────────────────────────────────────────────────────
+
+const commerce = createIapCommerce({ onChange: () => { void svc.pricingPublish(); } });
+const pricing = commerce.pricing;
+const PRICING_NOT_HYDRATED = ["rows", "hidePriceRetry"] as const;
+let scopeIncomplete = false;
+let page: CollectionQueryState<ProgramContent> | undefined;
+
+const INITIAL_STATE: State = {
+  status: "loading", rows: [], isLoading: true, notLoading: false, isErrored: false, notErrored: true, noEmpty: true, hideList: true,
+  emptyText: "", errorText: "", identityLine: "", needsSignIn: false, noSignIn: true, nextCursor: "", noMore: true, noPageError: true, loadingMore: false,
+  statusFilter: "all", statusOptions: [], hideStatusFilter: true, categoryId: "", categoryChips: [], hideCategoryFilter: true,
+  hidePriceRetry: true, priceRetryText: "", summary: "",
+};
+
+function pricedRows(items: ProgramContent[]): ProgramRow[] {
+  const copy = iapPriceCopy("memberPrograms");
+  return items.map((row) => {
+    if (!row.pricable) return { ...row, priceLine: "", hasPrice: false, noPrice: true };
+    const item = onlineProgramItem({ id: row.id }, row.commercePrice);
+    const view = item ? pricing.view(item.reference) : undefined;
+    const fields = view ? iapPriceFields(view, copy) : undefined;
+    const priceLine = fields?.priceText || (row.free ? copyParam("memberPrograms.free", "Free") : row.commercePrice);
+    return { ...row, priceLine, hasPrice: !!priceLine, noPrice: !priceLine };
+  });
+}
+
+function derive(state: State): State {
+  const current = page;
+  const meta = (current?.metadata ?? {}) as Partial<PageMeta>;
+  const status: State["status"] = !current || current.status === "idle" || current.status === "loading" ? "loading" : current.status === "error" ? "error" : "ready";
+  const member = !!meta.email || memberSeen;
+  const items = current?.items ?? [];
+  const rows = pricedRows(items);
+  const views = items.filter((row) => row.pricable).map((row) => { const item = onlineProgramItem({ id: row.id }, row.commercePrice); return item ? pricing.view(item.reference) : undefined; });
+  const needsSignIn = status === "ready" && !member && statusFilter === "joined";
+  const statusOptions: Option[] = [
+    { id: "all", label: copyParam("memberPrograms.filterAll", "All programs") },
+    { id: "joined", label: copyParam("memberPrograms.filterJoined", "Programs I joined") },
+  ];
+  const categoryChips: Option[] = [{ id: "", label: copyParam("memberPrograms.filterAllCategories", "All categories") },
+    ...(categories ?? []).map((c) => ({ id: String(c.id), label: String(c.label) }))];
+  const emptyText = status !== "ready" || rows.length ? ""
+    : needsSignIn ? copyParam("memberPrograms.signInEmptyText", "Sign in to see the programs you joined.")
+    : categoryId ? copyParam("memberPrograms.emptyCategoryText", "No programs in this category yet.")
+    : statusFilter === "joined" ? copyParam("memberPrograms.emptyJoinedText", "You haven't joined a program yet.")
+    : copyParam("memberPrograms.emptyText", "No programs yet.");
+  return {
+    ...state,
+    status, rows,
+    isLoading: status === "loading", notLoading: status !== "loading",
+    isErrored: status === "error", notErrored: status !== "error",
+    // The sign-in gate is the empty state of a signed-out joined filter: never both cards at once.
+    noEmpty: status !== "ready" || rows.length > 0 || !!current?.nextCursor || needsSignIn,
+    hideList: status !== "ready" || rows.length === 0,
+    emptyText,
+    errorText: status === "error" ? (current?.error || copyParam("memberPrograms.errorText", "Programs could not be loaded.")) : "",
+    identityLine: meta.email ? copyTemplate("memberPrograms.identityLine", "Signed in as {email}", { email: meta.email ?? "" }) : "",
+    needsSignIn, noSignIn: !needsSignIn,
+    nextCursor: current && !current.pageError && !current.loadingMore ? current.nextCursor : "",
+    noMore: !current?.nextCursor || current.pageError || current.loadingMore,
+    noPageError: !current?.pageError,
+    loadingMore: !!current?.loadingMore,
+    statusFilter, statusOptions,
+    // A guest sees the catalog, never a "joined" filter they cannot satisfy — unless they are already on
+    // it (signed out there), when the control is their way back to the catalog. It stays up while a
+    // filter switch or a refresh reloads, so the control never flickers away under the finger.
+    hideStatusFilter: !member && statusFilter !== "joined",
+    categoryId, categoryChips,
+    hideCategoryFilter: categoriesFailed || !categories || categories.length === 0,
+    hidePriceRetry: status !== "ready" || !views.some((view) => view && view.route !== "disabled" && (scopeIncomplete || view.retryable)),
+    priceRetryText: copyParam("memberPrograms.priceRetryText", "Some prices could not be loaded."),
+    // The rows loaded so far are not the catalog: a count is only true once the last page is in.
+    summary: status === "ready" && rows.length && !current?.nextCursor ? (rows.length === 1 ? copyParam("memberPrograms.summaryOne", "1 program") : copyTemplate("memberPrograms.summaryMany", "{count} programs", { count: rows.length })) : "",
+  };
+}
+
+const controller = createCollectionQuery<ProgramContent>({
+  id: (row) => row.id,
+  fetch: (criteria, cursor) => fetchPage(criteria.filter, cursor),
+  clearOnError: memberAccessDenied,
+  errorMessage: (error) => memberAccessDenied(error)
+    ? copyParam("memberPrograms.accessErrorText", "Programs are unavailable for this account. Sign in again.")
+    : copyParam("memberPrograms.errorText", "Programs could not be loaded."),
+}, (snapshot) => {
+  page = snapshot;
+  const meta = snapshot.metadata as Partial<PageMeta> | undefined;
+  if (snapshot.status === "ready" && !snapshot.loadingMore && !snapshot.pageError && meta) pageScope = { email: meta.email ?? "", memberId: meta.memberId ?? "", scope: meta.scope ?? "" };
+  if (snapshot.status === "loading" || snapshot.status === "error") pageScope = undefined;
+  void svc.pageChanged();
+  if (snapshot.status === "ready" && !snapshot.loadingMore) void priceContent();
+});
+
+const criteria = () => ({ filter: encodeFilter(statusFilter, categoryId) });
+
+/** Prices the programs on screen now. Content never waits on this. */
+async function priceContent(): Promise<void> {
+  const items = (page?.items ?? []).filter((row) => row.pricable).flatMap((row) => onlineProgramItem({ id: row.id }, row.commercePrice) ?? []);
+  if (!items.length) return;
+  scopeIncomplete = !(await commerce.loadPrices(items)).scopeComplete;
+  void svc.pricingPublish();
+}
+
+type Actions = {
+  load: (state: State, arg?: unknown) => Promise<undefined>;
+  refresh: (state: State, arg?: unknown) => Promise<undefined>;
+  loadMore: (state: State) => Promise<undefined>;
+  retry: (state: State) => Promise<undefined>;
+  setStatus: (state: State, arg?: unknown) => Promise<undefined> | State;
+  setCategory: (state: State, arg?: unknown) => Promise<undefined> | State;
+  open: (state: State, arg?: unknown) => State | undefined;
+  pageChanged: (state: State) => State;
+  pricingPublish: (state: State) => State;
+  pricingStart: (state: State) => State;
+  pricingRefresh: (state: State) => Promise<undefined>;
+};
+
+const actions: Actions = {
+  async load(_state, arg) {
+    stashCopy(arg);
+    // A load of what the screen already shows is the screen coming back: it revalidates behind its rows.
+    await controller.query(criteria(), true, true);
+    return undefined;
+  },
+  async refresh(_state, arg) { stashCopy(arg); await controller.query(criteria()); return undefined; },
+  async loadMore() { await controller.loadMore(); return undefined; },
+  async retry() { await controller.retry(); return undefined; },
+  setStatus(state, arg) {
+    const value = (arg as { selectedId?: unknown } | undefined)?.selectedId;
+    const next = value === "joined" ? "joined" : value === "all" ? "all" : undefined;
+    if (!next || next === statusFilter) return state;
+    statusFilter = next;
+    return controller.query(criteria()).then(() => undefined);
+  },
+  setCategory(state, arg) {
+    const picked = (arg as { selectedIds?: unknown; selectedId?: unknown } | undefined);
+    const raw = Array.isArray(picked?.selectedIds) ? picked.selectedIds[0] : picked?.selectedId;
+    const next = typeof raw === "string" ? raw : "";
+    if (next && !(categories ?? []).some((c) => c.id === next)) return state;
+    if (next === categoryId) return state;
+    categoryId = next;
+    return controller.query(criteria()).then(() => undefined);
+  },
+  // The card's one action: every standing opens the program, which owns joining, paying and leaving.
+  open(state, arg) {
+    const id = (arg as { id?: unknown } | undefined)?.id;
+    if (typeof id !== "string" || !state.rows.some((row) => row.id === id && !row.actionDisabled)) return state;
+    return navigate(state, { screenId: DETAIL_SCREEN, args: { id } });
+  },
+  pageChanged: derive,
+  pricingPublish: derive,
+  pricingStart: (state) => ({ ...derive(state), _poll: pricing.pollDirective(`${SERVICE}.pricingRefresh`) }),
+  pricingRefresh: async () => { await priceContent(); return undefined; },
+};
+
+// Prices are this run's: never restored from a cold-boot snapshot.
+const svc = register<State, Actions>(SERVICE, { state: INITIAL_STATE, actions, notHydrated: [...PRICING_NOT_HYDRATED] } as unknown as Parameters<typeof register<State, Actions>>[1]);
+resetUnhydratedKeysOnOlderRuntime(svc, INITIAL_STATE, PRICING_NOT_HYDRATED);
+void svc.pricingStart();
+// Kick the first load at module scope, like every other list bundle; onAppear re-loads with the copy pack.
+svc.load();
+export { svc };