fix(private-zone): hide incomplete albums and refresh Maya cover

e2e/specs/mock/multi-role-commercial.spec.ts

@@ -99,11 +99,16 @@ for (const character of characters) {
       page.getByRole("heading", { name: "Private albums" }),
     ).toBeVisible();
     await expect(page.getByText(character.displayName).last()).toBeVisible();
-    await expect(
-      page.getByRole("button", {
+    const albumButton = page.getByRole("button", {
       name: `View locked collection with 8 images from ${character.displayName}`,
-      }),
-    ).toBeVisible();
+    });
+    if (character.id === "maya-tan") {
+      await expect(albumButton).toHaveCount(0);
+      await expect(page.getByRole("button", { name: "Refresh" })).toHaveCount(0);
+      await expect(page.getByText("No private albums yet.")).toHaveCount(0);
+    } else {
+      await expect(albumButton).toBeVisible();
+    }
   });
 
   test(`${character.displayName} receives a character-scoped Tip catalog`, async ({
@@ -133,6 +138,19 @@ for (const character of characters) {
   });
 }
 
+test("a real Private Zone request failure still offers Retry", async ({
+  page,
+}) => {
+  await page.route("**/api/private-zone/albums**", async (route) => {
+    await route.fulfill({ status: 503, json: { message: "Albums unavailable" } });
+  });
+
+  await page.goto("/characters/maya/private-zone");
+
+  await expect(page.getByRole("button", { name: "Retry" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Refresh" })).toHaveCount(0);
+});
+
 async function registerMultiRoleCommercialMocks(page: Page): Promise<void> {
   await page.route("**/api/private-zone/albums**", async (route) => {
     const url = new URL(route.request().url());
@@ -140,10 +158,13 @@ async function registerMultiRoleCommercialMocks(page: Page): Promise<void> {
     const character =
       characters.find((candidate) => candidate.id === characterId) ?? characters[0];
 
+    const hasCompleteAlbum = character.id !== "maya-tan";
     await route.fulfill({
       json: apiEnvelope({
         creditBalance: 1000,
-        items: [
+        pendingImageCount: hasCompleteAlbum ? 0 : 7,
+        hasIncompleteContent: !hasCompleteAlbum,
+        items: hasCompleteAlbum ? [
           {
             albumId: `album-${character.id}`,
             title: `${character.shortName} private photos`,
@@ -163,7 +184,7 @@ async function registerMultiRoleCommercialMocks(page: Page): Promise<void> {
             publishedAt: "2026-07-22T10:00:00+08:00",
             lockDetail: { locked: true },
           },
-        ],
+        ] : [],
       }),
     });
   });

src/app/private-zone/private-zone-screen.tsx

@@ -257,14 +257,6 @@ export function PrivateZoneScreen() {
             <StatusCard message="Loading private albums..." />
           ) : null}
 
-          {!state.isLoading && state.items.length === 0 && !state.errorMessage ? (
-            <StatusCard
-              message="No private albums yet."
-              actionLabel="Refresh"
-              onAction={() => dispatch({ type: "PrivateZoneRefresh" })}
-            />
-          ) : null}
-
           <div className={styles.timeline}>
             {state.items.map((album, index) => (
               <PrivateAlbumCard

src/data/schemas/private-zone/__tests__/private_album.test.ts

@@ -67,6 +67,20 @@ describe("Private Album schema models", () => {
     expect(response).not.toHaveProperty("packageOptions");
   });
 
+  it("keeps incomplete-content metadata without exposing pending images", () => {
+    const response = PrivateAlbumsResponseSchema.parse({
+      items: [],
+      creditBalance: 100,
+      pendingImageCount: 7,
+      hasIncompleteContent: true,
+      pendingImages: [{ url: COVER_URL }],
+    });
+
+    expect(response.pendingImageCount).toBe(7);
+    expect(response.hasIncompleteContent).toBe(true);
+    expect(response).not.toHaveProperty("pendingImages");
+  });
+
   it("parses an unlock response with all album images", () => {
     const response = PrivateAlbumUnlockResponseSchema.parse({
       albumId: ALBUM_ID,

src/data/schemas/private-zone/response/private_albums_response.ts

@@ -1,12 +1,18 @@
 import { z } from "zod";
 
-import { arrayOrEmpty, numberOrZero } from "../../nullable-defaults";
+import {
+  arrayOrEmpty,
+  booleanOrFalse,
+  numberOrZero,
+} from "../../nullable-defaults";
 import { PrivateAlbumSchema } from "../private_album";
 
 export const PrivateAlbumsResponseSchema = z
   .object({
     items: arrayOrEmpty(PrivateAlbumSchema),
     creditBalance: numberOrZero,
+    pendingImageCount: numberOrZero,
+    hasIncompleteContent: booleanOrFalse,
   })
   .readonly();
 

src/stores/private-zone/__tests__/private-zone-album-flow.test.ts

@@ -41,6 +41,21 @@ describe("private zone album flow", () => {
     actor.stop();
   });
 
+  it("keeps incomplete album metadata without creating a visible album", async () => {
+    const actor = await loadPrivateZone({
+      loadResponse: makeAlbumsResponse({
+        items: [],
+        pendingImageCount: 7,
+        hasIncompleteContent: true,
+      }),
+    });
+
+    expect(actor.getSnapshot().context.items).toEqual([]);
+    expect(actor.getSnapshot().context.pendingImageCount).toBe(7);
+    expect(actor.getSnapshot().context.hasIncompleteContent).toBe(true);
+    actor.stop();
+  });
+
   it("moves to failed when the album actor rejects", async () => {
     const actor = createActor(
       createTestPrivateZoneMachine({

src/stores/private-zone/helper/albums.ts

@@ -15,6 +15,8 @@ export function applyAlbumsResponse(
   return {
     items: response.items,
     creditBalance: response.creditBalance,
+    pendingImageCount: response.pendingImageCount,
+    hasIncompleteContent: response.hasIncompleteContent,
     errorMessage: null,
   };
 }

src/stores/private-zone/private-zone-context.tsx

@@ -16,6 +16,8 @@ export interface PrivateZoneContextState {
   status: string;
   items: MachineContext["items"];
   creditBalance: number;
+  pendingImageCount: number;
+  hasIncompleteContent: boolean;
   errorMessage: string | null;
   unlockingAlbumId: string | null;
   unlockErrorMessage: string | null;
@@ -70,6 +72,8 @@ function selectPrivateZoneState(
     status: String(state.value),
     items: state.context.items,
     creditBalance: state.context.creditBalance,
+    pendingImageCount: state.context.pendingImageCount,
+    hasIncompleteContent: state.context.hasIncompleteContent,
     errorMessage: state.context.errorMessage,
     unlockingAlbumId: state.context.unlockingAlbumId,
     unlockErrorMessage: state.context.unlockErrorMessage,

src/stores/private-zone/private-zone-state.ts

@@ -13,6 +13,8 @@ export interface PrivateZoneState {
   characterId: string;
   items: readonly PrivateAlbum[];
   creditBalance: number;
+  pendingImageCount: number;
+  hasIncompleteContent: boolean;
   errorMessage: string | null;
   unlockingAlbumId: string | null;
   unlockErrorMessage: string | null;
@@ -28,6 +30,8 @@ export function createInitialPrivateZoneState(
     characterId,
     items: [],
     creditBalance: 0,
+    pendingImageCount: 0,
+    hasIncompleteContent: false,
     errorMessage: null,
     unlockingAlbumId: null,
     unlockErrorMessage: null,