@mohasinac/appkit 4.70.0 → 4.71.2

package/PROVIDERS.md

@@ -0,0 +1,190 @@
+# Provider registry — what you can replace, and what you cannot
+
+Written against the tree on **2026-10-29**. Every count here was measured, not
+estimated; re-measure before quoting any of it elsewhere.
+
+appkit reaches the outside world through one registry. A consumer calls
+`registerProviders()` once at boot and appkit code asks for what it needs:
+
+```ts
+import { registerProviders } from "@mohasinac/appkit/contracts/registry";
+
+registerProviders({
+  db: myDbProvider,
+  auth: myAuthProvider,
+  session: mySessionProvider,
+  email: myEmailProvider,
+  storage: myStorageProvider,
+  style: tailwindAdapter,
+});
+```
+
+The five without `?` in `ProviderRegistry` are required by the type. The rest
+are optional, and an absent optional provider means "appkit keeps its existing
+behaviour" — never a throw.
+
+---
+
+## 🛑 Read this before planning a replacement: Firebase is a hard dependency today
+
+**appkit is "Firebase ecommerce from scratch", not "ecommerce from scratch".**
+
+| Measured 2026-10-29 | |
+|---|---|
+| appkit files importing `firebase-admin` / `firebase/*` **outside `providers/`** | **59** |
+| appkit files calling `getAdminDb` / `getAdminAuth` / `getAdminStorage` directly | **64** |
+
+`IDbProvider` exists and is registered, but 64 files bypass it and talk to the
+Admin SDK. So swapping `db` for Postgres does **not** work today, whatever the
+registry's shape suggests. The seams that are real are listed below; the rest
+is a direction of travel.
+
+This is stated plainly because the alternative is discovering it in a sales
+conversation. Closing it is a tracked tier (AK3-dip-direct-repo: *"every appkit
+component/hook importing a concrete repository instead of a provider"*), not a
+afternoon's work.
+
+---
+
+## The slots
+
+🛑 **"Read?" is the column that matters.** A slot nothing reads is
+indistinguishable from one that works — the consumer passes a provider, appkit
+accepts it, and the value is never fetched. Six slots are in that state right
+now. `scripts/audit-provider-registry-readers.mjs` blocks a seventh.
+
+| Slot | Contract | letitrip registers | Read? | Replaceable today? |
+|---|---|---|---|---|
+| `db` | `IDbProvider` | `firebaseDbProvider` | ✅ 46 files | ❌ — 64 files bypass it for the Admin SDK |
+| `auth` | `IAuthProvider` | `firebaseAuthProvider` | ✅ 4 | partly |
+| `session` | `ISessionProvider` | `firebaseSessionProvider` | ✅ 3 | partly |
+| `email` | `IEmailProvider` | `createResendProvider(...)` | ✅ 1 | **yes** — the cleanest seam in the package |
+| `payment` | `IPaymentProvider` | manual \| Razorpay \| PhonePe | ✅ 11 | **yes** — three implementations prove it |
+| `shipping` | `IShippingProvider` | manual \| Shiprocket | ✅ 6 | **yes** — two implementations |
+| `rbac` | `IRbacProvider` | inline `{getPermissions, isAdmin}` | ✅ 1 | yes |
+| `eventBus` | `IEventBus` | — | ✅ 1 | yes |
+| `storage` | `IStorageProvider` | `firebaseStorageProvider` | 🛑 **0** | no — media code imports the provider module directly |
+| `style` | `IStyleAdapter` | `tailwindAdapter` | 🛑 **0** | no — reached by direct import |
+| `tax` | `ITaxProvider` | `indiaGstTaxProvider` | 🛑 **0** | **blocked — see below** |
+| `search` | `ISearchProvider` | — | 🛑 **0** | no — listing queries call repositories |
+| `cache` | `ICacheProvider` | — | 🛑 **0** | declared only |
+| `queue` | `IQueueProvider` | — | 🛑 **0** | declared only; the job primitive is `enqueueJob` + `JOB_RUNNERS` |
+
+`payment` and `shipping` are the two to copy when writing a new provider: each
+has more than one real implementation, selected at boot from site settings, and
+a fall-through to a complete manual flow. A half-configured gateway fails
+loudly at boot rather than when a buyer tries to pay.
+
+### 🛑 `tax` — a declared seam that cannot be read yet
+
+Two obstacles, and the second is a design problem rather than effort:
+
+1. **Runtime.** Its call sites are in `_internal/shared/checkout/order-math.ts`,
+   which is isomorphic — `features/cart/utils/line-total.ts` reaches it from the
+   *client* graph for per-store subtotals. `getProviders()` throws where nothing
+   registered, and a consumer registers on the server only. (Same trap
+   `features/contact/email.tsx` documents for Firebase Functions, where it made
+   the daily digest silently never deliver.)
+2. **Shape.** `TaxBreakdown` carries `components[]` keyed by provider-specific
+   codes. `order-math.ts` needs named `cgst`/`sgst`/`igst` scalars — 27
+   references — because India's Rule 46 requires tax *per rate* on the invoice.
+   Converting means generic code doing `components.find(c => c.code === "cgst")`,
+   re-importing the exact vocabulary the interface exists to abstract.
+
+The honest reading: **`order-math.ts` is not generic code that uses GST, it is
+India invoice code.** Fixing it is a decision about where GST invoice assembly
+lives, on a money path.
+
+---
+
+## Two injection mechanisms, and which to use
+
+The registry is not the only seam. Some values are needed on **every runtime**,
+including the browser bundle and Firebase Functions, neither of which calls
+`registerProviders()`.
+
+| Need | Mechanism | Call it in |
+|---|---|---|
+| A service appkit calls (db, email, payment) | `registerProviders({...})` | `providers.config.ts` (server) |
+| A value isomorphic code reads (brand, currency, storage namespace) | a `configure*` function | **both** `providers.config.ts` *and* `client-providers-init.ts` |
+
+The `configure*` family — all merge rather than replace, all have neutral
+defaults:
+
+| Function | Module | Sets |
+|---|---|---|
+| `configureBrand` | `core/brand-resolver` | name, shortName, domain, support/noreply email |
+| `configureMarketDefaults` | `core/baseline-resolver` | currency, locale, country, phone prefix, timezone, symbol |
+| `setStorageNamespace` | `constants/storage-keys` | the prefix on every browser storage key |
+| `configurePlatformSupplier` | `_internal/.../supplier-of-record` | statutory identity for invoices (server only) |
+
+🛑 **Module state does not cross a module graph.** A `configure*` call in
+`providers.config.ts` runs from the instrumentation hook and is invisible to the
+browser bundle. An isomorphic value needs the call in both places, reading the
+same owner (`appkit.config.js`) so the two cannot disagree about the value —
+only about whether they ran.
+
+🛑 **Brand defaults are NEUTRAL (`"Site"`), market defaults are not.**
+`baseline-resolver`'s baseline is India's (INR / en-IN / +91). That asymmetry is
+deliberate: a wrong currency is visible in the first rendered price, while a
+wrong brand name renders plausibly and is someone else's trademark.
+
+---
+
+## The override hierarchy — least invasive first
+
+Replacing a provider is the *fifth* of six options. Try them in order:
+
+1. **Config / tokens** — `siteSettings.theme`, a partial `LabelsProvider` map,
+   `appkit.config.js`.
+2. **Options object** — every public function takes an optional final `opts?`.
+   `renderXOgImage(doc, { theme, headline, layout: "compact" })`.
+3. **Render-prop slots** — `<XDetailView renderActions={(ctx) => <MyActions/>}>`.
+4. **Adapter wrap** — `const myToClient = (doc) => decorate(toClientX(doc))`.
+5. **Replace the call** — register your own provider, or call the repository
+   directly and skip the helper.
+6. **Fork via patch** — only when the seam does not exist. File an issue; the
+   seam should ship in appkit rather than live in your fork.
+
+---
+
+## Writing a provider
+
+Contracts are **abstract classes**, not interfaces, so every implementation
+shares one base:
+
+```ts
+import { IPaymentProvider } from "@mohasinac/appkit/contracts/payment";
+
+export class MyGateway extends IPaymentProvider {
+  readonly id = "my-gateway";
+  // implement the abstract members; `tsc` enumerates them for you
+}
+```
+
+Three rules learned the hard way:
+
+- **Fail at boot, not at point of use.** A provider constructed with empty
+  credentials should throw while the app is starting. The alternative is a buyer
+  discovering it at checkout.
+- **Treat a placeholder as absent.** Seeded credentials like
+  `re_PLACEHOLDER` are truthy. `resolveKeys()` maps them to absent so a flag
+  switched on with no real key does not look configured.
+- **Never name your gateway in generic code.** `audit-provider-name-leak`
+  blocks it: a provider name belongs inside its own `providers/<name>/`
+  directory and nowhere else.
+
+---
+
+## Verifying a standalone install
+
+🛑 **There is no proof app yet, so "standalone" remains a claim.**
+
+The acceptance test is a scratch Next.js app that installs appkit from the
+registry, registers a **non-Firebase** provider for at least one contract, and
+renders a catalogue. Given the 64 files above, the honest expectation is that it
+fails on `db` and succeeds on `email` — which is exactly why the test is worth
+running rather than reasoned about.
+
+It cannot be written against this tree: it must install a *published* version,
+and the work described in this document is not published yet.

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.70.0",
-  "head": "2818ecbd04176961cc2184dc89a3bf319efb92d4",
+  "version": "4.71.2",
+  "head": "2f712f0de777c8205b4dd33037754c70c5d9074d",
   "branch": "main",
-  "dirty": false,
-  "builtAt": "2026-10-28T02:31:30.990Z"
+  "dirty": true,
+  "builtAt": "2026-11-08T17:02:06.024Z"
 }

package/dist/_internal/client/edit-mode/EditModeProvider.d.ts

@@ -0,0 +1,32 @@
+import { type ReactNode } from "react";
+/**
+ * Admin-only "view as buyer" toggle (point 7, overhaul brief).
+ *
+ * Off (the default, and the only state a buyer or seller can ever reach):
+ * the admin sees exactly what a buyer/seller sees — which doubles as the
+ * admin's own verification that a Phase 1 content-tag kill-switch is
+ * actually hidden, not just believed to be. On: `<LiveEditableRegion>`
+ * wrappers around tagged content render an inline edit affordance.
+ *
+ * 🛑 `enabled` is NOT a preference — it is the admin-role check, decided by
+ * the consumer (which knows the session) and passed in. A non-admin mount
+ * gets `enabled={false}`, and `editMode` can then never become `true`
+ * regardless of what `setEditMode` is called with — see `toggleEditMode`
+ * below. This is the one guarantee the whole feature rests on: a buyer
+ * cannot reach edit affordances by any client-side code path.
+ */
+export interface EditModeContextValue {
+    /** True only when BOTH the admin flipped the toggle AND this mount is admin-enabled. */
+    editMode: boolean;
+    /** No-ops when `enabled` is false. */
+    setEditMode: (next: boolean) => void;
+    toggleEditMode: () => void;
+    /** Whether this session may use edit mode at all — drives whether the toggle control renders. */
+    canUseEditMode: boolean;
+}
+export declare function EditModeProvider({ enabled, children, }: {
+    /** The admin-role check — decide this from the session, never from a client toggle. */
+    enabled: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useEditMode(): EditModeContextValue;

package/dist/_internal/client/edit-mode/EditModeProvider.js

@@ -0,0 +1,33 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useMemo, useState, } from "react";
+const DEFAULT_CONTEXT_VALUE = {
+    editMode: false,
+    setEditMode: () => { },
+    toggleEditMode: () => { },
+    canUseEditMode: false,
+};
+const EditModeContext = createContext(DEFAULT_CONTEXT_VALUE);
+export function EditModeProvider({ enabled, children, }) {
+    const [rawEditMode, setRawEditMode] = useState(false);
+    const setEditMode = useCallback((next) => {
+        if (!enabled)
+            return;
+        setRawEditMode(next);
+    }, [enabled]);
+    const toggleEditMode = useCallback(() => {
+        if (!enabled)
+            return;
+        setRawEditMode((prev) => !prev);
+    }, [enabled]);
+    const value = useMemo(() => ({
+        editMode: enabled && rawEditMode,
+        setEditMode,
+        toggleEditMode,
+        canUseEditMode: enabled,
+    }), [enabled, rawEditMode, setEditMode, toggleEditMode]);
+    return _jsx(EditModeContext.Provider, { value: value, children: children });
+}
+export function useEditMode() {
+    return useContext(EditModeContext);
+}

package/dist/_internal/client/edit-mode/index.d.ts

@@ -0,0 +1,2 @@
+export { EditModeProvider, useEditMode } from "./EditModeProvider";
+export type { EditModeContextValue } from "./EditModeProvider";

package/dist/_internal/client/edit-mode/index.js

@@ -0,0 +1 @@
+export { EditModeProvider, useEditMode } from "./EditModeProvider.js";

package/dist/_internal/client/features/giveaway/ClearanceGiveawayDetailView.d.ts

@@ -0,0 +1,32 @@
+import React from "react";
+import type { ClientGiveawayConfig } from "../../../../features/giveaway/types";
+import type { DashboardCard } from "../../../shared/features/dashboard/recent-entry";
+interface ClientProduct {
+    id: string;
+    title: string;
+    description?: string;
+    status: string;
+    mainImage?: string;
+    prizeDrawMode?: "reveal" | "giveaway";
+    giveawayConfig?: ClientGiveawayConfig;
+}
+interface ClearanceGiveawayDetailViewProps {
+    product: ClientProduct;
+    user?: {
+        uid: string;
+        displayName?: string | null;
+    } | null;
+    currentEntry?: {
+        userGiveawayNumber: number;
+        assignedPrizeSlotNumber?: number;
+        slotName?: string;
+    } | null;
+    /** Admin-curated page-region cards (Phase 12). Omit for no extra content. */
+    pageRegionCards?: DashboardCard[];
+}
+/**
+ * Prize-draw product detail view for giveaway mode.
+ * Same flow as GiveawayDetailView but sourced from a product.
+ */
+export declare function ClearanceGiveawayDetailView({ product, user, currentEntry, pageRegionCards, }: ClearanceGiveawayDetailViewProps): React.JSX.Element;
+export {};

package/dist/_internal/client/features/giveaway/ClearanceGiveawayDetailView.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Stack, Row, Container } from "../../../../ui/components/Layout.js";
+import { Text, Heading } from "../../../../ui/components/Typography.js";
+import { Badge } from "../../../../ui/components/Badge.js";
+import { Section } from "../../../../ui/components/Semantic.js";
+import { Div } from "../../../../ui/components/Div.js";
+import { Anchor } from "../../../../ui/components/Anchor.js";
+import { MediaImage } from "../../../../ui/components/MediaImage.js";
+import { ROUTES } from "../../../../next/routing/route-map.js";
+import { GiveawaySlotGrid } from "./GiveawaySlotGrid.js";
+import { GiveawayPullForm } from "./GiveawayPullForm.js";
+import { ClearanceCollage } from "../../../../features/products/components/ClearanceCollage.js";
+import { slotsToCollageItems } from "./slot-collage-items.js";
+import { AdminComposableRegion } from "../../../../features/dashboard/components/AdminComposableRegion.js";
+/**
+ * Prize-draw product detail view for giveaway mode.
+ * Same flow as GiveawayDetailView but sourced from a product.
+ */
+export function ClearanceGiveawayDetailView({ product, user, currentEntry, pageRegionCards = [], }) {
+    const [pulledEntry, setPulledEntry] = useState(currentEntry?.assignedPrizeSlotNumber != null
+        ? currentEntry
+        : null);
+    const config = product.giveawayConfig;
+    const prizeItems = slotsToCollageItems(config?.slots ?? []);
+    const isActive = product.status === "published";
+    return (_jsx(Container, { children: _jsx(Section, { children: _jsxs(Stack, { gap: "xl", children: [product.mainImage ? (_jsx(Div, { rounded: "2xl", className: "relative overflow-hidden", style: { aspectRatio: "16/9", maxHeight: "16rem" }, children: _jsx(MediaImage, { src: product.mainImage, alt: product.title, size: "hero" }) })) : (_jsx(Div, { rounded: "2xl", surface: "muted", padding: "xl", align: "center", justify: "center", children: _jsx(Text, { size: "5xl", children: "\uD83C\uDF81" }) })), _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { gap: "xs", align: "center", wrap: true, children: [_jsx(Badge, { variant: "info", children: "Slot-pick Clearance" }), config && (_jsxs(Badge, { variant: isActive ? "success" : "secondary", children: [config.slots.filter((s) => s.isBooked).length, "/", config.totalSlots, " claimed"] }))] }), _jsx(Heading, { level: 1, size: "3xl", weight: "bold", children: product.title }), product.description ? (_jsx(Text, { color: "muted", children: product.description })) : null] }), _jsx(AdminComposableRegion, { pageId: "clearance-slug", initialCards: pageRegionCards }), prizeItems.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Prizes" }), _jsx(ClearanceCollage, { items: prizeItems, wonLabel: "Claimed" })] })) : null, config && config.slots.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Slots" }), _jsx(GiveawaySlotGrid, { slots: config.slots, totalSlots: config.totalSlots })] })) : null, isActive && config && (_jsx(Div, { padding: "md", rounded: "2xl", surface: "card", className: "border border-[var(--appkit-color-border)]", children: !user ? (_jsxs(Stack, { gap: "md", className: "text-center", children: [_jsx(Heading, { level: 2, size: "xl", weight: "semibold", children: "Want to Enter?" }), _jsx(Text, { color: "muted", children: "Log in to submit your entry." }), _jsx(Anchor, { href: String(ROUTES.AUTH.LOGIN), tone: "brand", children: "Log In to Enter" })] })) : pulledEntry ? (_jsxs(Stack, { gap: "sm", surface: "success-surface", padding: "md", rounded: "xl", className: "border border-success/20", children: [_jsxs(Heading, { level: 2, size: "lg", weight: "bold", className: "text-success", children: ["You're Entry #", pulledEntry.userGiveawayNumber, "!"] }), _jsxs(Text, { className: "text-success", size: "sm", children: ["Assigned to Slot #", pulledEntry.assignedPrizeSlotNumber, pulledEntry.slotName ? ` — ${pulledEntry.slotName}` : "", "."] })] })) : (_jsx(GiveawayPullForm, { sourceType: "product", productId: product.id, totalSlots: config.totalSlots, maxPullsPerUser: config.maxPullsPerUser, onSuccess: (res) => setPulledEntry(res) })) }))] }) }) }));
+}

package/dist/_internal/client/features/giveaway/GiveawayAdminEditView.d.ts

@@ -0,0 +1,66 @@
+/**
+ * GiveawayAdminEditView — the slot configuration for one giveaway. Sectionised
+ * 2026-08-30.
+ *
+ * ## Two schemas became one
+ *
+ * It declared `giveawayConfigFormSchema` on `<Form>` and parsed
+ * `giveawayConfigWriteSchema` in the submit handler, so the form schema's
+ * duplicate-slot and free-giveaway rules had never executed. The form schema is
+ * deleted; `giveawayConfigWriteSchema` carries the annotations now and is both
+ * what this form renders from and what the route parses.
+ *
+ * ## Title and description are gone, not moved
+ *
+ * They were editable here and reached nothing: `GiveawayConfigClient` posts
+ * `data.giveawayConfig` to `PUT .../giveaway-config` and ignores the rest, and
+ * that route accepts only the config. An event's title, dates, status and
+ * media are edited in the ordinary event editor — this page is the slots. Two
+ * inputs that saved silently into nowhere are worse than their absence, which
+ * is the same call made on `rememberMe`. The title still appears, as the
+ * heading, so it is obvious which giveaway is open.
+ */
+import React from "react";
+import type { GiveawayConfigWriteInput } from "../../../../features/giveaway/schemas/config-write";
+/** One editable row of the slot table. */
+interface GiveawaySlotRow {
+    slotNumber: number;
+    name: string;
+    price: number;
+    /** Prize photo — rendered publicly in the prize collage on the detail page. */
+    image?: string;
+}
+/**
+ * What this form hands its caller.
+ *
+ * `giveawayConfig` is the WRITE input — deliberately not `GiveawayConfig`. It
+ * carries no `isBooked`, no `bookedBy*` and no `weight`, because an admin
+ * editing a giveaway is describing prizes, not attendance. The stored config
+ * gains those in `mergeGiveawayConfig`, server-side, from the slots that are
+ * already there.
+ *
+ * `totalSlots` is absent for the same reason: derived from `slots.length` by
+ * the merge, never sent. A caller-supplied count that disagrees with the array
+ * is the mirror-drift trap (Root Cause #42), and the count is what the
+ * fullness check reads.
+ */
+interface GiveawayEventFormData {
+    giveawayConfig: GiveawayConfigWriteInput;
+}
+interface GiveawayAdminEditViewProps {
+    eventId?: string;
+    initialData?: {
+        title: string;
+        description?: string;
+        totalSlots: number;
+        pricingMode: "uniform" | "variable";
+        uniformPrice?: number;
+        drawWindowDurationMinutes: number;
+        maxPullsPerTransaction: number;
+        maxPullsPerUser: number;
+        slots: GiveawaySlotRow[];
+    };
+    onSubmit: (data: GiveawayEventFormData) => Promise<void>;
+}
+export declare function GiveawayAdminEditView({ eventId, initialData, onSubmit, }: GiveawayAdminEditViewProps): React.JSX.Element;
+export {};

package/dist/_internal/client/features/giveaway/GiveawayAdminEditView.js

@@ -0,0 +1,187 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * GiveawayAdminEditView — the slot configuration for one giveaway. Sectionised
+ * 2026-08-30.
+ *
+ * ## Two schemas became one
+ *
+ * It declared `giveawayConfigFormSchema` on `<Form>` and parsed
+ * `giveawayConfigWriteSchema` in the submit handler, so the form schema's
+ * duplicate-slot and free-giveaway rules had never executed. The form schema is
+ * deleted; `giveawayConfigWriteSchema` carries the annotations now and is both
+ * what this form renders from and what the route parses.
+ *
+ * ## Title and description are gone, not moved
+ *
+ * They were editable here and reached nothing: `GiveawayConfigClient` posts
+ * `data.giveawayConfig` to `PUT .../giveaway-config` and ignores the rest, and
+ * that route accepts only the config. An event's title, dates, status and
+ * media are edited in the ordinary event editor — this page is the slots. Two
+ * inputs that saved silently into nowhere are worse than their absence, which
+ * is the same call made on `rememberMe`. The title still appears, as the
+ * heading, so it is obvious which giveaway is open.
+ */
+import React from "react";
+import { Button } from "../../../../ui/components/Button.js";
+import { DataTable } from "../../../../ui/DataTable.js";
+import { Input } from "../../../../ui/components/Input.js";
+import { Row, Stack } from "../../../../ui/components/Layout.js";
+import { Text } from "../../../../ui/components/Typography.js";
+import { FormErrorSummary } from "../../../../ui/forms/FormErrorSummary.js";
+import { FormShellContext, useFormShellState } from "../../../../ui/forms/FormShell.js";
+import { applyZodIssues } from "../../../../ui/forms/apply-zod-issues.js";
+import { StackedViewShell } from "../../../../ui/components/StackedViewShell.js";
+import { buildSectionsFromSchema, visibleValues } from "../../../../features/shell/build-sections.js";
+import { SectionForm, useSectionFormNav } from "../../../../features/shell/SectionForm.js";
+import { giveawayConfigWriteSchema } from "../../../../features/giveaway/schemas/config-write.js";
+const MAX_SLOTS = 200;
+export function GiveawayAdminEditView({ eventId, initialData, onSubmit, }) {
+    const [isPending, startTransition] = React.useTransition();
+    const [form, setForm] = React.useState({
+        pricingMode: initialData?.pricingMode ?? "uniform",
+        uniformPrice: initialData?.uniformPrice ?? 0,
+        drawWindowDurationMinutes: initialData?.drawWindowDurationMinutes ?? 5,
+        maxPullsPerTransaction: initialData?.maxPullsPerTransaction ?? 1,
+        maxPullsPerUser: initialData?.maxPullsPerUser ?? 1,
+        slots: initialData?.slots ?? [{ slotNumber: 1, name: "", price: 0 }],
+    });
+    const patch = (partial) => setForm((prev) => Object.assign({}, prev, partial));
+    const sections = React.useMemo(() => buildSectionsFromSchema(giveawayConfigWriteSchema, {
+        renderers: {
+            slots: ({ values, onChange }) => (_jsx(SlotTable, { slots: values.slots, showPrice: values.pricingMode === "variable", onSlotsChange: (next) => onChange({ slots: next }) })),
+        },
+    }), []);
+    const nav = useSectionFormNav(sections, form, { scope: "admin:giveaway-config" });
+    const { shellCtx, setFieldError, clearErrors } = useFormShellState(giveawayConfigWriteSchema, {
+        sections: nav.sectionMeta,
+        onGoToSection: nav.goToSection,
+        fieldToSectionIndex: nav.fieldToSectionIndex,
+    });
+    const handleSubmit = () => {
+        clearErrors();
+        /*
+         * Per-slot prices are dropped under uniform pricing, where the price of a
+         * slot IS `uniformPrice`. They used to be sent in both modes, so a figure
+         * loaded from `initialData` survived a switch to uniform — unreachable on
+         * screen, still written on save. `visibleValues` cannot reach inside an
+         * array, so this one masking stays explicit.
+         */
+        const draft = visibleValues(giveawayConfigWriteSchema, form);
+        const candidate = {
+            ...draft,
+            slots: form.slots.map((s) => ({
+                slotNumber: s.slotNumber,
+                name: s.name,
+                image: s.image?.trim() || undefined,
+                price: form.pricingMode === "variable" ? s.price : 0,
+            })),
+        };
+        const parsed = giveawayConfigWriteSchema.safeParse(candidate);
+        if (!parsed.success) {
+            applyZodIssues(parsed.error.issues, setFieldError);
+            return;
+        }
+        startTransition(async () => {
+            await onSubmit({ giveawayConfig: parsed.data });
+        });
+    };
+    return (_jsx(StackedViewShell, { portal: "admin", title: eventId
+            ? `Edit giveaway${initialData?.title ? ` — ${initialData.title}` : ""}`
+            : "Create giveaway", sections: [
+            _jsxs(FormShellContext.Provider, { value: shellCtx, children: [_jsx(FormErrorSummary, {}), _jsx(SectionForm, { sections: sections, values: form, onChange: patch, onSubmit: handleSubmit, schema: giveawayConfigWriteSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, isLoading: isPending, submitLabel: eventId ? "Update giveaway" : "Create giveaway" })] }, "giveaway-config-form"),
+        ] }));
+}
+/**
+ * The repeatable slot rows.
+ *
+ * A module-level component rather than an inline renderer: its handlers would
+ * otherwise sit six braces deep inside `useMemo`, which is what
+ * `audit-code-quality`'s DEEP_NESTING rule exists to stop.
+ */
+function SlotTable({ slots, showPrice, onSlotsChange, }) {
+    /*
+     * Read the form context directly. `SlotTable` is its own component, so the
+     * `shellCtx` the parent destructures is out of scope here — but the parent
+     * mounts `FormShellContext.Provider` above this, so the errors are
+     * reachable. `useContext` rather than `useFormShell()`: this table is
+     * also usable outside a form and must not require a provider.
+     */
+    const formCtx = React.useContext(FormShellContext);
+    const slotError = (idx, field) => formCtx?.errors[`slots.${idx}.${field}`];
+    /**
+     * Next number is max+1, not length+1.
+     *
+     * Now that removeSlot preserves numbering, `slots.length + 1` collides: delete
+     * slot 1 of 25 and you hold 24 slots numbered 2..25, so length+1 is 25 — a
+     * duplicate, which the write schema rejects outright (slot numbers must be
+     * unique). Deriving from the highest number in use is stable under any gaps.
+     */
+    const addSlot = () => onSlotsChange([
+        ...slots,
+        { slotNumber: slots.reduce((max, s) => Math.max(max, s.slotNumber), 0) + 1, name: "", price: 0 },
+    ]);
+    /**
+     * 🛑 Remove the slot. Do NOT renumber the survivors.
+     *
+     * `slotNumber` is the stable identity a booking is attached to, and renumbering
+     * silently defeated the server's own protection. `mergeGiveawayConfig` refuses a
+     * save that drops a BOOKED slot by checking `isBooked && !incoming.has(slotNumber)`
+     * — but this function used to renumber the remaining slots to `i + 1`, so deleting
+     * slot 1 of 25 sent back numbers 1..24. Every booked number (1–5) still *appeared*
+     * in that set, the check found nothing to refuse, and the save went through.
+     *
+     * The damage was worse than the deletion: the merge re-attaches bookings by
+     * slotNumber, so the buyer of the deleted slot 1 had their booking moved onto
+     * whatever prize now occupied number 1. That is precisely the hazard the schema
+     * header describes — "hands slot 7's buyer the prize that used to be slot 8".
+     *
+     * Numbers may therefore be non-contiguous after a delete (2..25), which the write
+     * schema allows: it requires slot numbers to be UNIQUE, not gapless, and totalSlots
+     * is derived from slots.length rather than from the highest number.
+     */
+    const removeSlot = (idx) => onSlotsChange(slots.filter((_, i) => i !== idx));
+    const updateSlot = (idx, field, value) => onSlotsChange(slots.map((s, i) => i === idx
+        ? {
+            ...s,
+            [field]: field === "price"
+                ? Math.round(parseFloat(value) * 100) / 100 || 0
+                : value,
+        }
+        : s));
+    const rows = slots.map((s, i) => ({ ...s, _idx: i }));
+    const columns = [
+        {
+            key: "slotNumber",
+            header: "#",
+            render: (s) => (_jsx(Text, { size: "xs", color: "muted", family: "mono", children: s.slotNumber })),
+        },
+        {
+            key: "name",
+            header: "Prize name",
+            /*
+             * These inputs live in DataTable COLUMN renderers, which get no
+             * `errors` argument — a section render would. They read the context
+             * this component itself mounts, with the dotted INDEXED key
+             * `applyZodIssues` produces (`slots.2.price`), so a rejected slot marks
+             * its own row rather than the first one.
+             */
+            render: (s) => (_jsx(Input, { type: "text", className: "w-full", placeholder: `Prize for slot ${s.slotNumber}`, value: s.name, error: slotError(s._idx, "name"), onChange: (e) => updateSlot(s._idx, "name", e.target.value), "aria-label": `Slot ${s.slotNumber} prize name` })),
+        },
+        {
+            key: "image",
+            header: "Image",
+            render: (s) => (_jsx(Input, { type: "text", className: "w-full", placeholder: "/media/\u2026 or https://\u2026", value: s.image ?? "", error: slotError(s._idx, "image"), onChange: (e) => updateSlot(s._idx, "image", e.target.value), "aria-label": `Slot ${s.slotNumber} prize image URL` })),
+        },
+        ...(showPrice
+            ? [
+                {
+                    key: "price",
+                    header: "Price (₹)",
+                    render: (s) => (_jsx(Input, { type: "number", className: "w-24", placeholder: "0", value: s.price, error: slotError(s._idx, "price"), onChange: (e) => updateSlot(s._idx, "price", e.target.value), "aria-label": `Slot ${s.slotNumber} price` })),
+                },
+            ]
+            : []),
+    ];
+    return (_jsxs(Stack, { gap: "md", children: [_jsxs(Row, { align: "center", justify: "between", children: [_jsxs(Text, { size: "sm", color: "muted", children: [slots.length, " slot", slots.length === 1 ? "" : "s"] }), _jsx(Button, { type: "button", variant: "secondary", size: "sm", onClick: addSlot, disabled: slots.length >= MAX_SLOTS, children: "+ Add slot" })] }), _jsx(DataTable, { data: rows, columns: columns, keyExtractor: (s) => String(s.slotNumber), emptyMessage: "No slots yet.", actions: (s) => slots.length > 1 ? (_jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => removeSlot(s._idx), "aria-label": `Remove slot ${s.slotNumber}`, children: "\u00D7" })) : null })] }));
+}

package/dist/_internal/client/features/giveaway/GiveawayAdminSlotView.d.ts

@@ -0,0 +1,18 @@
+import React from "react";
+import type { ClientGiveawaySlot } from "../../../../features/giveaway/types";
+import type { DashboardCard } from "../../../shared/features/dashboard/recent-entry";
+interface AdminGiveawaySlot extends ClientGiveawaySlot {
+    price: number;
+    weight: number;
+}
+interface GiveawayAdminSlotViewProps {
+    slots: AdminGiveawaySlot[];
+    /** Admin-curated page-region cards (Phase 12). Omit for no extra content. */
+    pageRegionCards?: DashboardCard[];
+}
+/**
+ * Admin-only view showing slots with price + weight + % chance.
+ * Separate from GiveawaySlotGrid (public) which never shows price/weight.
+ */
+export declare function GiveawayAdminSlotView({ slots, pageRegionCards }: GiveawayAdminSlotViewProps): React.JSX.Element;
+export {};