@mohasinac/appkit 4.1.1 → 4.2.0

package/dist/features/stores/schemas/firestore.d.ts

@@ -75,6 +75,12 @@ export interface StoreDocument extends BaseDocument {
     isFeatured?: boolean;
     isVacationMode?: boolean;
     vacationMessage?: string;
+    /** Internal admin note, never shown to the store owner or the public. */
+    adminNotes?: string;
+    /** Admin "verified store" badge — distinct from `status`/`isPublic`. */
+    isVerified?: boolean;
+    /** Reason recorded when `status` is set to "suspended". */
+    suspensionReason?: string;
     stats?: {
         totalProducts: number;
         itemsSold: number;
@@ -158,6 +164,11 @@ export declare const STORE_FIELDS: {
     readonly STATS: "stats";
     readonly CREATED_AT: "createdAt";
     readonly UPDATED_AT: "updatedAt";
+    readonly ADMIN_NOTES: "adminNotes";
+    readonly IS_FEATURED: "isFeatured";
+    readonly IS_VERIFIED: "isVerified";
+    readonly SUSPENSION_REASON: "suspensionReason";
+    readonly CAPABILITIES: "capabilities";
     readonly STATUS_VALUES: {
         readonly PENDING: "pending";
         readonly ACTIVE: "active";

package/dist/features/stores/schemas/firestore.js

@@ -35,6 +35,11 @@ export const STORE_FIELDS = {
     STATS: "stats",
     CREATED_AT: "createdAt",
     UPDATED_AT: "updatedAt",
+    ADMIN_NOTES: "adminNotes",
+    IS_FEATURED: "isFeatured",
+    IS_VERIFIED: "isVerified",
+    SUSPENSION_REASON: "suspensionReason",
+    CAPABILITIES: "capabilities",
     STATUS_VALUES: {
         PENDING: "pending",
         ACTIVE: "active",

package/dist/features/stores/schemas/index.d.ts

@@ -458,10 +458,10 @@ export declare const storeFirestoreSchema: z.ZodObject<{
     shippingPolicy?: string | undefined;
     isVacationMode?: boolean | undefined;
     vacationMessage?: string | undefined;
+    capabilities?: string[] | undefined;
     vacationReturnDate?: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
-    capabilities?: string[] | undefined;
     customCommissionRate?: number | undefined;
     googleReviews?: {
         enabled: boolean;
@@ -543,10 +543,10 @@ export declare const storeFirestoreSchema: z.ZodObject<{
     shippingPolicy?: string | undefined;
     isVacationMode?: boolean | undefined;
     vacationMessage?: string | undefined;
+    capabilities?: string[] | undefined;
     vacationReturnDate?: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
-    capabilities?: string[] | undefined;
     customCommissionRate?: number | undefined;
     googleReviews?: {
         enabled: boolean;

package/dist/features/tester/actions/checklist-item-actions.d.ts

@@ -9,6 +9,7 @@ export declare const checklistItemCreateSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     href: z.ZodOptional<z.ZodString>;
     order: z.ZodDefault<z.ZodNumber>;
+    phase: z.ZodDefault<z.ZodNumber>;
     isActive: z.ZodDefault<z.ZodBoolean>;
     adminOnly: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
@@ -17,6 +18,7 @@ export declare const checklistItemCreateSchema: z.ZodObject<{
     isActive: boolean;
     groupKey: string;
     pageKey: string;
+    phase: number;
     groupLabel: string;
     pageLabel: string;
     adminOnly: boolean;
@@ -32,6 +34,7 @@ export declare const checklistItemCreateSchema: z.ZodObject<{
     description?: string | undefined;
     order?: number | undefined;
     isActive?: boolean | undefined;
+    phase?: number | undefined;
     adminOnly?: boolean | undefined;
 }>;
 export declare const checklistItemUpdateSchema: z.ZodObject<{
@@ -43,6 +46,7 @@ export declare const checklistItemUpdateSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     href: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     order: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    phase: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     isActive: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     adminOnly: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
@@ -53,6 +57,7 @@ export declare const checklistItemUpdateSchema: z.ZodObject<{
     isActive?: boolean | undefined;
     groupKey?: string | undefined;
     pageKey?: string | undefined;
+    phase?: number | undefined;
     groupLabel?: string | undefined;
     pageLabel?: string | undefined;
     adminOnly?: boolean | undefined;
@@ -64,6 +69,7 @@ export declare const checklistItemUpdateSchema: z.ZodObject<{
     isActive?: boolean | undefined;
     groupKey?: string | undefined;
     pageKey?: string | undefined;
+    phase?: number | undefined;
     groupLabel?: string | undefined;
     pageLabel?: string | undefined;
     adminOnly?: boolean | undefined;

package/dist/features/tester/actions/checklist-item-actions.js

@@ -11,6 +11,7 @@ const checklistItemBaseSchema = z.object({
     description: z.string().max(2000).optional(),
     href: z.string().max(300).optional(),
     order: z.number().int().min(0).default(0),
+    phase: z.number().int().min(1).default(1),
     isActive: z.boolean().default(true),
     adminOnly: z.boolean().default(false),
 });
@@ -27,6 +28,7 @@ export async function createChecklistItem(input) {
         description: input.description,
         href: input.href,
         order: input.order ?? 0,
+        phase: input.phase ?? 1,
         isActive: input.isActive ?? true,
         adminOnly: input.adminOnly ?? false,
     });

package/dist/features/tester/components/AdminTesterFeedbackIssuesView.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useQuery } from "@tanstack/react-query";
-import { Card, Stack, Text } from "../../../ui";
+import { Card, Details, Div, Stack, Summary, Text } from "../../../ui";
 import { MediaImage } from "../../media/MediaImage";
 import { apiClient } from "../../../http";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
@@ -18,5 +18,16 @@ export function AdminTesterFeedbackIssuesView() {
         return _jsx(Text, { color: "muted", children: "Loading issues\u2026" });
     if (issues.length === 0)
         return _jsx(Text, { color: "muted", children: "No \"No\" answers recorded yet." });
-    return (_jsx(Stack, { gap: "sm", children: issues.map((issue) => (_jsx(Card, { padding: "md", variant: "default", children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { weight: "semibold", children: [issue.groupKey, " / ", issue.pageKey] }), _jsxs(Text, { size: "sm", color: "muted", children: ["Reported by ", issue.testerDisplayName] }), issue.comment && _jsx(Text, { size: "sm", children: issue.comment }), issue.screenshotUrl && (_jsx(MediaImage, { src: issue.screenshotUrl, alt: "Tester screenshot", size: "card" }))] }) }, issue.id))) }));
+    const byPhase = new Map();
+    for (const issue of issues) {
+        const phase = issue.phase ?? 0;
+        if (!byPhase.has(phase))
+            byPhase.set(phase, []);
+        byPhase.get(phase).push(issue);
+    }
+    const sortedPhases = Array.from(byPhase.keys()).sort((a, b) => a - b);
+    return (_jsx(Stack, { gap: "md", children: sortedPhases.map((phase) => {
+            const phaseIssues = byPhase.get(phase);
+            return (_jsxs(Details, { tone: "card", defaultOpen: sortedPhases.length === 1, children: [_jsxs(Summary, { size: "lg", weight: "bold", children: ["Phase ", phase, " (", phaseIssues.length, " issue", phaseIssues.length === 1 ? "" : "s", ")"] }), _jsx(Div, { padding: "t-sm", children: _jsx(Stack, { gap: "sm", children: phaseIssues.map((issue) => (_jsx(Card, { padding: "md", variant: "default", children: _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { weight: "semibold", children: issue.label }), _jsxs(Text, { size: "sm", color: "muted", children: [issue.groupLabel, " \u203A ", issue.pageLabel] }), _jsxs(Text, { size: "sm", color: "muted", children: ["Reported by ", issue.testerDisplayName] }), issue.comment && _jsx(Text, { size: "sm", children: issue.comment }), issue.screenshotUrl && (_jsx(MediaImage, { src: issue.screenshotUrl, alt: "Tester screenshot", size: "card" }))] }) }, issue.id))) }) })] }, phase));
+        }) }));
 }

package/dist/features/tester/components/AdminTesterFeedbackListView.js

@@ -59,12 +59,13 @@ export function AdminTesterFeedbackListView(_props) {
         sortOptions: [
             { value: sortBy(TESTER_CHECKLIST_RESPONSE_FIELDS.CREATED_AT, "DESC"), label: "Newest" },
             { value: sortBy(TESTER_CHECKLIST_RESPONSE_FIELDS.CREATED_AT, "ASC"), label: "Oldest" },
+            { value: sortBy(TESTER_CHECKLIST_RESPONSE_FIELDS.PHASE, "ASC"), label: "Phase" },
         ],
         columns: COLUMNS,
         mapRows: (response) => toRecordArray(response.items).map((item, index) => ({
             id: toStringValue(item.id, `feedback-${index}`),
             primary: toStringValue(item.testerDisplayName, "Unknown tester"),
-            secondary: `${toStringValue(item.groupKey, "")} / ${toStringValue(item.pageKey, "")}${item.comment ? " — " + toStringValue(item.comment, "") : ""}`,
+            secondary: `Phase ${toStringValue(item.phase, "?")} — ${toStringValue(item.groupKey, "")} / ${toStringValue(item.pageKey, "")}${item.comment ? " — " + toStringValue(item.comment, "") : ""}`,
             answer: toStringValue(item.answer, ""),
             status: toStringValue(item.status, "new"),
             updatedAt: toRelativeDate(item.updatedAt ?? item.createdAt),

package/dist/features/tester/components/AdminTesterFeedbackReportView.js

@@ -17,14 +17,18 @@ export function AdminTesterFeedbackReportView() {
         return _jsx(Text, { color: "muted", children: "Loading report\u2026" });
     const itemCoverage = query.data?.itemCoverage ?? [];
     const totals = query.data?.totals ?? { totalAnswered: 0, totalYes: 0, totalNo: 0 };
-    const byGroup = new Map();
+    const byPhase = new Map();
     for (const item of itemCoverage) {
-        if (!byGroup.has(item.groupKey)) {
-            byGroup.set(item.groupKey, { groupLabel: item.groupKey, yes: 0, no: 0 });
+        const phase = item.phase ?? 0;
+        if (!byPhase.has(phase)) {
+            byPhase.set(phase, { groupLabel: `Phase ${phase}`, yes: 0, no: 0 });
         }
-        const entry = byGroup.get(item.groupKey);
+        const entry = byPhase.get(phase);
         entry.yes += item.yesCount;
         entry.no += item.noCount;
     }
-    return (_jsx(Stack, { gap: "lg", children: _jsx(TesterFeedbackChart, { data: Array.from(byGroup.values()), totalCases: itemCoverage.length, totalAnswered: totals.totalAnswered, totalYes: totals.totalYes, totalNo: totals.totalNo }) }));
+    const sortedPhaseData = Array.from(byPhase.entries())
+        .sort(([a], [b]) => a - b)
+        .map(([, datum]) => datum);
+    return (_jsx(Stack, { gap: "lg", children: _jsx(TesterFeedbackChart, { data: sortedPhaseData, totalCases: itemCoverage.length, totalAnswered: totals.totalAnswered, totalYes: totals.totalYes, totalNo: totals.totalNo }) }));
 }

package/dist/features/tester/components/TesterHubView.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import React from "react";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { Alert, Details, Div, FieldInput, Heading, Stack, Summary, Text } from "../../../ui";
@@ -15,6 +15,21 @@ function matchesQuery(item, query) {
     const haystack = `${item.label} ${item.description ?? ""} ${item.groupLabel} ${item.pageLabel} ${item.href ?? ""}`.toLowerCase();
     return haystack.includes(query.toLowerCase());
 }
+function TesterChecklistPageSection({ page, testerDisplayName, onAnswer, onSaveNote }) {
+    const answeredCount = page.items.filter((i) => i.answer).length;
+    return (_jsxs(Details, { tone: "card", defaultOpen: false, children: [_jsxs(Summary, { children: [page.pageLabel, " (", answeredCount, "/", page.items.length, " answered)"] }), _jsx(Div, { padding: "t-sm", children: _jsx(Stack, { gap: "sm", children: page.items
+                        .slice()
+                        .sort((a, b) => a.order - b.order)
+                        .map((item) => (_jsx(TesterChecklistStepRow, { testerDisplayName: testerDisplayName, item: {
+                            checklistItemId: item.id,
+                            label: item.label,
+                            description: item.description,
+                            href: item.href,
+                            answer: item.answer,
+                            comment: item.comment,
+                            screenshotUrl: item.screenshotUrl,
+                        }, onAnswer: onAnswer, onSaveNote: onSaveNote }, item.id))) }) })] }));
+}
 export function TesterHubView({ sandboxExpiresAt }) {
     const { user } = useSession();
     const queryClient = useQueryClient();
@@ -35,38 +50,36 @@ export function TesterHubView({ sandboxExpiresAt }) {
     if (!user?.isTester && !isAdminUser(user)) {
         return (_jsx(Alert, { variant: "warning", title: "Testers only", children: "This page is only available to accounts flagged as testers (and admins). Contact an admin if you believe this is a mistake." }));
     }
+    // Items arrive pre-sorted by catalog `order` (listActive() orders by it).
     const items = query.data?.items ?? [];
     const filtered = items.filter((item) => matchesQuery(item, search));
-    const groups = new Map();
+    const phases = new Map();
     for (const item of filtered) {
-        if (!groups.has(item.groupKey)) {
+        if (!phases.has(item.phase))
+            phases.set(item.phase, new Map());
+        const groups = phases.get(item.phase);
+        if (!groups.has(item.groupKey))
             groups.set(item.groupKey, { groupLabel: item.groupLabel, pages: new Map() });
-        }
         const group = groups.get(item.groupKey);
-        if (!group.pages.has(item.pageKey)) {
+        if (!group.pages.has(item.pageKey))
             group.pages.set(item.pageKey, { pageLabel: item.pageLabel, items: [] });
-        }
         group.pages.get(item.pageKey).items.push(item);
     }
+    const sortedPhaseNumbers = Array.from(phases.keys()).sort((a, b) => a - b);
     const handleAnswer = (checklistItemId, answer) => {
         upsertMutation.mutate({ checklistItemId, patch: { answer } });
     };
     const handleSaveNote = async (checklistItemId, comment, screenshotUrl) => {
         await upsertMutation.mutateAsync({ checklistItemId, patch: { comment, screenshotUrl } });
     };
-    return (_jsxs(Stack, { gap: "lg", children: [_jsx(Heading, { level: 1, children: "Tester Hub" }), _jsx(Text, { color: "muted", children: "Work through the checklist below and answer Yes/No for each test case. Add a comment and screenshot wherever something looks off \u2014 colors, styles, readability, bugs. Your answers save automatically." }), sandboxExpiresAt && (_jsxs(Alert, { variant: "info", title: "Shared test sandbox", children: ["The shared test store/products/categories expire on ", new Date(sandboxExpiresAt).toLocaleDateString(), "."] })), _jsx(FieldInput, { name: "checklist-search", label: "Search test cases", value: search, onChange: setSearch, placeholder: "Search by title or route, e.g. checkout, /store/payouts..." }), query.isLoading && _jsx(Text, { color: "muted", children: "Loading checklist\u2026" }), Array.from(groups.entries()).map(([groupKey, group]) => (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 3, children: group.groupLabel }), Array.from(group.pages.entries()).map(([pageKey, page]) => {
-                        const answeredCount = page.items.filter((i) => i.answer).length;
-                        return (_jsxs(Details, { tone: "card", defaultOpen: false, children: [_jsxs(Summary, { children: [page.pageLabel, " (", answeredCount, "/", page.items.length, " answered)"] }), _jsx(Div, { padding: "t-sm", children: _jsx(Stack, { gap: "sm", children: page.items
-                                            .slice()
-                                            .sort((a, b) => a.order - b.order)
-                                            .map((item) => (_jsx(TesterChecklistStepRow, { testerDisplayName: user?.displayName ?? user?.email ?? "tester", item: {
-                                                checklistItemId: item.id,
-                                                label: item.label,
-                                                description: item.description,
-                                                href: item.href,
-                                                answer: item.answer,
-                                                comment: item.comment,
-                                                screenshotUrl: item.screenshotUrl,
-                                            }, onAnswer: handleAnswer, onSaveNote: handleSaveNote }, item.id))) }) })] }, pageKey));
-                    })] }, groupKey)))] }));
+    return (_jsxs(Stack, { gap: "lg", children: [_jsx(Heading, { level: 1, children: "Tester Hub" }), _jsx(Text, { color: "muted", children: "Work through the checklist below and answer Yes/No for each test case. Add a comment and screenshot wherever something looks off \u2014 colors, styles, readability, bugs. Your answers save automatically." }), sandboxExpiresAt && (_jsxs(Alert, { variant: "info", title: "Shared test sandbox", children: ["The shared test store/products/categories expire on ", new Date(sandboxExpiresAt).toLocaleDateString(), "."] })), _jsx(FieldInput, { name: "checklist-search", label: "Search test cases", value: search, onChange: setSearch, placeholder: "Search by title or route, e.g. checkout, /store/payouts..." }), query.isLoading && _jsx(Text, { color: "muted", children: "Loading checklist\u2026" }), sortedPhaseNumbers.map((phaseNumber) => {
+                const groups = phases.get(phaseNumber);
+                const phaseItemCount = Array.from(groups.values())
+                    .flatMap((g) => Array.from(g.pages.values()))
+                    .reduce((sum, page) => sum + page.items.length, 0);
+                const phaseAnswered = Array.from(groups.values())
+                    .flatMap((g) => Array.from(g.pages.values()))
+                    .reduce((sum, page) => sum + page.items.filter((i) => i.answer).length, 0);
+                return (_jsxs(Details, { tone: "card", defaultOpen: false, children: [_jsxs(Summary, { size: "lg", weight: "bold", children: ["Phase ", phaseNumber, " (", phaseAnswered, "/", phaseItemCount, " answered)"] }), _jsx(Div, { padding: "t-sm", children: _jsx(Stack, { gap: "md", children: Array.from(groups.entries()).map(([groupKey, group]) => (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 4, children: group.groupLabel }), Array.from(group.pages.entries()).map(([pageKey, page]) => (_jsx(TesterChecklistPageSection, { page: page, testerDisplayName: user?.displayName ?? user?.email ?? "tester", onAnswer: handleAnswer, onSaveNote: handleSaveNote }, pageKey)))] }, groupKey))) }) })] }, phaseNumber));
+            })] }));
 }

package/dist/features/tester/repository/tester-checklist-item.repository.js

@@ -48,6 +48,7 @@ TesterChecklistItemRepository.SIEVE_FIELDS = {
     pageKey: { canFilter: true, canSort: true },
     label: { canFilter: true, canSort: false },
     order: { canFilter: true, canSort: true },
+    phase: { canFilter: true, canSort: true },
     isActive: { canFilter: true, canSort: false },
     searchTokens: { canFilter: true, canSort: false },
     createdAt: { canFilter: true, canSort: true },

package/dist/features/tester/repository/tester-checklist-response.repository.d.ts

@@ -7,6 +7,7 @@ export interface UpsertResponseInput {
     checklistItemId: string;
     groupKey: string;
     pageKey: string;
+    phase: number;
     answer?: TesterAnswer | null;
     comment?: string;
     screenshotUrl?: string;
@@ -14,14 +15,22 @@ export interface UpsertResponseInput {
 export interface ChecklistItemCoverage {
     checklistItemId: string;
     groupKey: string;
+    groupLabel: string;
     pageKey: string;
+    pageLabel: string;
+    phase: number;
     yesCount: number;
     noCount: number;
     totalAnswered: number;
 }
+export type CoverageIssue = TesterChecklistResponseDocument & {
+    groupLabel: string;
+    pageLabel: string;
+    label: string;
+};
 export interface CoverageReport {
     itemCoverage: ChecklistItemCoverage[];
-    issues: TesterChecklistResponseDocument[];
+    issues: CoverageIssue[];
     totals: {
         totalAnswered: number;
         totalYes: number;
@@ -36,14 +45,19 @@ export declare class TesterChecklistResponseRepository extends BaseRepository<Te
     listForTester(testerId: string): Promise<TesterChecklistResponseDocument[]>;
     list(model: SieveModel): Promise<FirebaseSieveResult<TesterChecklistResponseDocument>>;
     markReviewed(id: string): Promise<TesterChecklistResponseDocument>;
-    /** Single collection scan (small table: testers x cases) — no join needed. */
+    /** Joins responses against the checklist catalog for human labels
+     * (groupLabel/pageLabel) — small tables (testers x cases, and the
+     * ~300-item catalog), so the extra read is cheap. `phase` itself is
+     * already denormalized onto the response doc, no join needed for it. */
     getCoverageReport(): Promise<CoverageReport>;
     /**
      * Markdown dump of every answered case, joined against the checklist item
      * catalog for the human-readable label/href — optimized for a future dev
      * (or Claude session) to read directly and go fix the reported issues.
-     * Mirrors appkit/scripts/export-tester-feedback.mjs's CLI output exactly;
-     * keep the two in sync.
+     * Grouped by phase (ascending), then group, then page — mirrors how the
+     * Tester Hub itself is organized. Mirrors
+     * appkit/scripts/export-tester-feedback.mjs's CLI output exactly; keep
+     * the two in sync.
      */
     getMarkdownReport(siteOrigin: string): Promise<string>;
 }

package/dist/features/tester/repository/tester-checklist-response.repository.js

@@ -24,6 +24,7 @@ export class TesterChecklistResponseRepository extends BaseRepository {
             checklistItemId: input.checklistItemId,
             groupKey: input.groupKey,
             pageKey: input.pageKey,
+            phase: input.phase,
             status: "new",
         };
         if (input.answer !== undefined)
@@ -55,9 +56,16 @@ export class TesterChecklistResponseRepository extends BaseRepository {
             status: "reviewed",
         });
     }
-    /** Single collection scan (small table: testers x cases) — no join needed. */
+    /** Joins responses against the checklist catalog for human labels
+     * (groupLabel/pageLabel) — small tables (testers x cases, and the
+     * ~300-item catalog), so the extra read is cheap. `phase` itself is
+     * already denormalized onto the response doc, no join needed for it. */
     async getCoverageReport() {
-        const snapshot = await this.db.collection(this.collection).get();
+        const [{ items }, snapshot] = await Promise.all([
+            testerChecklistItemRepository.list({ page: "1", pageSize: "1000" }),
+            this.db.collection(this.collection).get(),
+        ]);
+        const itemById = new Map(items.map((item) => [item.id, item]));
         const docs = snapshot.docs.map((doc) => this.mapDoc(doc));
         const byItem = new Map();
         const issues = [];
@@ -66,12 +74,18 @@ export class TesterChecklistResponseRepository extends BaseRepository {
         for (const doc of docs) {
             if (!doc.answer)
                 continue;
+            const catalogItem = itemById.get(doc.checklistItemId);
+            const groupLabel = catalogItem?.groupLabel ?? doc.groupKey;
+            const pageLabel = catalogItem?.pageLabel ?? doc.pageKey;
             let entry = byItem.get(doc.checklistItemId);
             if (!entry) {
                 entry = {
                     checklistItemId: doc.checklistItemId,
                     groupKey: doc.groupKey,
+                    groupLabel,
                     pageKey: doc.pageKey,
+                    pageLabel,
+                    phase: doc.phase,
                     yesCount: 0,
                     noCount: 0,
                     totalAnswered: 0,
@@ -86,7 +100,12 @@ export class TesterChecklistResponseRepository extends BaseRepository {
             else {
                 entry.noCount += 1;
                 totalNo += 1;
-                issues.push(doc);
+                issues.push({
+                    ...doc,
+                    groupLabel,
+                    pageLabel,
+                    label: catalogItem?.label ?? doc.checklistItemId,
+                });
             }
         }
         return {
@@ -99,8 +118,10 @@ export class TesterChecklistResponseRepository extends BaseRepository {
      * Markdown dump of every answered case, joined against the checklist item
      * catalog for the human-readable label/href — optimized for a future dev
      * (or Claude session) to read directly and go fix the reported issues.
-     * Mirrors appkit/scripts/export-tester-feedback.mjs's CLI output exactly;
-     * keep the two in sync.
+     * Grouped by phase (ascending), then group, then page — mirrors how the
+     * Tester Hub itself is organized. Mirrors
+     * appkit/scripts/export-tester-feedback.mjs's CLI output exactly; keep
+     * the two in sync.
      */
     async getMarkdownReport(siteOrigin) {
         const [items, snapshot] = await Promise.all([
@@ -114,14 +135,15 @@ export class TesterChecklistResponseRepository extends BaseRepository {
         const grouped = new Map();
         for (const r of responses) {
             const item = itemById.get(r.checklistItemId);
+            const phase = item?.phase ?? r.phase ?? 0;
             const groupLabel = item?.groupLabel ?? r.groupKey ?? "Unknown group";
             const pageLabel = item?.pageLabel ?? r.pageKey ?? "Unknown page";
-            const key = `${groupLabel}␟${pageLabel}`;
+            const key = `${phase}␟${groupLabel}␟${pageLabel}`;
             if (!grouped.has(key))
-                grouped.set(key, { groupLabel, pageLabel, items: [] });
+                grouped.set(key, { phase, groupLabel, pageLabel, items: [] });
             grouped.get(key).items.push({ ...r, label: item?.label ?? r.checklistItemId, href: item?.href });
         }
-        const sortedGroups = Array.from(grouped.values()).sort((a, b) => a.groupLabel.localeCompare(b.groupLabel) || a.pageLabel.localeCompare(b.pageLabel));
+        const sortedGroups = Array.from(grouped.values()).sort((a, b) => a.phase - b.phase || a.groupLabel.localeCompare(b.groupLabel) || a.pageLabel.localeCompare(b.pageLabel));
         const issues = responses.filter((r) => r.answer === "no");
         const passingWithNotes = responses.filter((r) => r.answer === "yes" && r.comment?.trim());
         const lines = [];
@@ -138,10 +160,16 @@ export class TesterChecklistResponseRepository extends BaseRepository {
             lines.push("");
         }
         else {
+            let lastPhase = null;
             for (const group of sortedGroups) {
                 const groupIssues = group.items.filter((r) => r.answer === "no");
                 if (groupIssues.length === 0)
                     continue;
+                if (group.phase !== lastPhase) {
+                    lines.push(`## Phase ${group.phase}`);
+                    lines.push("");
+                    lastPhase = group.phase;
+                }
                 lines.push(`### ${group.groupLabel} › ${group.pageLabel}`);
                 lines.push("");
                 for (const r of groupIssues) {
@@ -166,10 +194,16 @@ export class TesterChecklistResponseRepository extends BaseRepository {
             lines.push("");
         }
         else {
+            let lastPhase = null;
             for (const group of sortedGroups) {
                 const groupNotes = group.items.filter((r) => r.answer === "yes" && r.comment?.trim());
                 if (groupNotes.length === 0)
                     continue;
+                if (group.phase !== lastPhase) {
+                    lines.push(`## Phase ${group.phase}`);
+                    lines.push("");
+                    lastPhase = group.phase;
+                }
                 lines.push(`### ${group.groupLabel} › ${group.pageLabel}`);
                 lines.push("");
                 for (const r of groupNotes) {
@@ -189,6 +223,7 @@ TesterChecklistResponseRepository.SIEVE_FIELDS = {
     checklistItemId: { canFilter: true, canSort: false },
     groupKey: { canFilter: true, canSort: true },
     pageKey: { canFilter: true, canSort: true },
+    phase: { canFilter: true, canSort: true },
     answer: { canFilter: true, canSort: false },
     status: { canFilter: true, canSort: false },
     createdAt: { canFilter: true, canSort: true },

package/dist/features/tester/schemas/firestore.d.ts

@@ -15,16 +15,17 @@ export interface TesterChecklistItemDocument extends BaseDocument {
     description?: string;
     href?: string;
     order: number;
+    phase: number;
     isActive: boolean;
     searchTokens: string[];
     adminOnly?: boolean;
 }
 export declare const TESTER_CHECKLIST_ITEM_COLLECTION: "testerChecklistItems";
 export declare const TESTER_CHECKLIST_ITEM_ID_PREFIX: "checklist-";
-export declare const TESTER_CHECKLIST_ITEM_INDEXED_FIELDS: readonly ["groupKey", "pageKey", "order", "isActive", "searchTokens", "createdAt"];
+export declare const TESTER_CHECKLIST_ITEM_INDEXED_FIELDS: readonly ["groupKey", "pageKey", "phase", "order", "isActive", "searchTokens", "createdAt"];
 export declare const DEFAULT_TESTER_CHECKLIST_ITEM_DATA: Partial<TesterChecklistItemDocument>;
 export type TesterChecklistItemCreateInput = Omit<TesterChecklistItemDocument, "id" | "createdAt" | "updatedAt" | "searchTokens">;
-export type TesterChecklistItemUpdateInput = Partial<Pick<TesterChecklistItemDocument, "groupKey" | "groupLabel" | "pageKey" | "pageLabel" | "label" | "description" | "href" | "order" | "isActive" | "adminOnly">>;
+export type TesterChecklistItemUpdateInput = Partial<Pick<TesterChecklistItemDocument, "groupKey" | "groupLabel" | "pageKey" | "pageLabel" | "label" | "description" | "href" | "order" | "phase" | "isActive" | "adminOnly">>;
 export declare const testerChecklistItemQueryHelpers: {
     readonly byGroup: (groupKey: string) => readonly ["groupKey", "==", string];
     readonly byPage: (pageKey: string) => readonly ["pageKey", "==", string];
@@ -40,18 +41,20 @@ export interface TesterChecklistResponseDocument extends BaseDocument {
     checklistItemId: string;
     groupKey: string;
     pageKey: string;
+    phase: number;
     answer: TesterAnswer | null;
     comment?: string;
     screenshotUrl?: string;
     status: TesterFeedbackStatus;
 }
 export declare const TESTER_CHECKLIST_RESPONSE_COLLECTION: "testerChecklistResponses";
-export declare const TESTER_CHECKLIST_RESPONSE_INDEXED_FIELDS: readonly ["testerId", "checklistItemId", "groupKey", "pageKey", "answer", "status", "createdAt"];
+export declare const TESTER_CHECKLIST_RESPONSE_INDEXED_FIELDS: readonly ["testerId", "checklistItemId", "groupKey", "pageKey", "phase", "answer", "status", "createdAt"];
 export declare const DEFAULT_TESTER_CHECKLIST_RESPONSE_DATA: Partial<TesterChecklistResponseDocument>;
 export declare function createChecklistResponseId(testerId: string, checklistItemId: string): string;
 export declare const testerChecklistResponseQueryHelpers: {
     readonly byTester: (testerId: string) => readonly ["testerId", "==", string];
     readonly byItem: (checklistItemId: string) => readonly ["checklistItemId", "==", string];
+    readonly byPhase: (phase: number) => readonly ["phase", "==", number];
     readonly byAnswer: (answer: TesterAnswer) => readonly ["answer", "==", TesterAnswer];
     readonly byStatus: (status: TesterFeedbackStatus) => readonly ["status", "==", TesterFeedbackStatus];
 };
@@ -65,6 +68,7 @@ export declare const TESTER_CHECKLIST_ITEM_FIELDS: {
     readonly DESCRIPTION: "description";
     readonly HREF: "href";
     readonly ORDER: "order";
+    readonly PHASE: "phase";
     readonly IS_ACTIVE: "isActive";
     readonly SEARCH_TOKENS: "searchTokens";
     readonly ADMIN_ONLY: "adminOnly";
@@ -78,6 +82,7 @@ export declare const TESTER_CHECKLIST_RESPONSE_FIELDS: {
     readonly CHECKLIST_ITEM_ID: "checklistItemId";
     readonly GROUP_KEY: "groupKey";
     readonly PAGE_KEY: "pageKey";
+    readonly PHASE: "phase";
     readonly ANSWER: "answer";
     readonly COMMENT: "comment";
     readonly SCREENSHOT_URL: "screenshotUrl";

package/dist/features/tester/schemas/firestore.js

@@ -11,6 +11,7 @@ export const TESTER_CHECKLIST_ITEM_ID_PREFIX = "checklist-";
 export const TESTER_CHECKLIST_ITEM_INDEXED_FIELDS = [
     "groupKey",
     "pageKey",
+    "phase",
     "order",
     "isActive",
     "searchTokens",
@@ -18,6 +19,7 @@ export const TESTER_CHECKLIST_ITEM_INDEXED_FIELDS = [
 ];
 export const DEFAULT_TESTER_CHECKLIST_ITEM_DATA = {
     order: 0,
+    phase: 1,
     isActive: true,
     searchTokens: [],
     adminOnly: false,
@@ -45,6 +47,7 @@ export const TESTER_CHECKLIST_RESPONSE_INDEXED_FIELDS = [
     "checklistItemId",
     "groupKey",
     "pageKey",
+    "phase",
     "answer",
     "status",
     "createdAt",
@@ -59,6 +62,7 @@ export function createChecklistResponseId(testerId, checklistItemId) {
 export const testerChecklistResponseQueryHelpers = {
     byTester: (testerId) => ["testerId", "==", testerId],
     byItem: (checklistItemId) => ["checklistItemId", "==", checklistItemId],
+    byPhase: (phase) => ["phase", "==", phase],
     byAnswer: (answer) => ["answer", "==", answer],
     byStatus: (status) => ["status", "==", status],
 };
@@ -73,6 +77,7 @@ export const TESTER_CHECKLIST_ITEM_FIELDS = {
     DESCRIPTION: "description",
     HREF: "href",
     ORDER: "order",
+    PHASE: "phase",
     IS_ACTIVE: "isActive",
     SEARCH_TOKENS: "searchTokens",
     ADMIN_ONLY: "adminOnly",
@@ -86,6 +91,7 @@ export const TESTER_CHECKLIST_RESPONSE_FIELDS = {
     CHECKLIST_ITEM_ID: "checklistItemId",
     GROUP_KEY: "groupKey",
     PAGE_KEY: "pageKey",
+    PHASE: "phase",
     ANSWER: "answer",
     COMMENT: "comment",
     SCREENSHOT_URL: "screenshotUrl",