@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/features/admin/schemas/site-settings-about-form.d.ts

@@ -0,0 +1,162 @@
+import { z } from "zod";
+export declare const siteSettingsAboutFormSchema: z.ZodObject<{
+    aboutTitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutSubtitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutMissionTitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutMissionText: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutHowItWorksTitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutHowItems: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        text: z.ZodString;
+        icon: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<["indigo", "teal", "amber", "rose"]>>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        text: string;
+        icon: string;
+        tone?: "indigo" | "teal" | "amber" | "rose" | undefined;
+    }, {
+        title: string;
+        text: string;
+        icon: string;
+        tone?: "indigo" | "teal" | "amber" | "rose" | undefined;
+    }>, "many">;
+    aboutValuesTitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutValuesSubtitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutValueItems: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        text: z.ZodString;
+        icon: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        text: string;
+        icon: string;
+        detail?: string | undefined;
+    }, {
+        title: string;
+        text: string;
+        icon: string;
+        detail?: string | undefined;
+    }>, "many">;
+    aboutMilestonesTitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutMilestones: z.ZodArray<z.ZodObject<{
+        year: z.ZodString;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        year: string;
+    }, {
+        text: string;
+        year: string;
+    }>, "many">;
+    aboutTeamTitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutTeamSubtitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutTeamMembers: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        role: z.ZodString;
+        bio: z.ZodString;
+        photoUrl: z.ZodOptional<z.ZodString>;
+        isFounder: z.ZodOptional<z.ZodBoolean>;
+        isDeveloper: z.ZodOptional<z.ZodBoolean>;
+        githubUrl: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        role: string;
+        name: string;
+        bio: string;
+        photoUrl?: string | undefined;
+        isFounder?: boolean | undefined;
+        isDeveloper?: boolean | undefined;
+        githubUrl?: string | undefined;
+    }, {
+        role: string;
+        name: string;
+        bio: string;
+        photoUrl?: string | undefined;
+        isFounder?: boolean | undefined;
+        isDeveloper?: boolean | undefined;
+        githubUrl?: string | undefined;
+    }>, "many">;
+    aboutCtaTitle: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutCtaSell: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    aboutCtaShop: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+}, "strip", z.ZodTypeAny, {
+    aboutHowItems: {
+        title: string;
+        text: string;
+        icon: string;
+        tone?: "indigo" | "teal" | "amber" | "rose" | undefined;
+    }[];
+    aboutValueItems: {
+        title: string;
+        text: string;
+        icon: string;
+        detail?: string | undefined;
+    }[];
+    aboutMilestones: {
+        text: string;
+        year: string;
+    }[];
+    aboutTeamMembers: {
+        role: string;
+        name: string;
+        bio: string;
+        photoUrl?: string | undefined;
+        isFounder?: boolean | undefined;
+        isDeveloper?: boolean | undefined;
+        githubUrl?: string | undefined;
+    }[];
+    aboutTitle?: string | undefined;
+    aboutSubtitle?: string | undefined;
+    aboutMissionTitle?: string | undefined;
+    aboutMissionText?: string | undefined;
+    aboutHowItWorksTitle?: string | undefined;
+    aboutValuesTitle?: string | undefined;
+    aboutValuesSubtitle?: string | undefined;
+    aboutMilestonesTitle?: string | undefined;
+    aboutTeamTitle?: string | undefined;
+    aboutTeamSubtitle?: string | undefined;
+    aboutCtaTitle?: string | undefined;
+    aboutCtaSell?: string | undefined;
+    aboutCtaShop?: string | undefined;
+}, {
+    aboutHowItems: {
+        title: string;
+        text: string;
+        icon: string;
+        tone?: "indigo" | "teal" | "amber" | "rose" | undefined;
+    }[];
+    aboutValueItems: {
+        title: string;
+        text: string;
+        icon: string;
+        detail?: string | undefined;
+    }[];
+    aboutMilestones: {
+        text: string;
+        year: string;
+    }[];
+    aboutTeamMembers: {
+        role: string;
+        name: string;
+        bio: string;
+        photoUrl?: string | undefined;
+        isFounder?: boolean | undefined;
+        isDeveloper?: boolean | undefined;
+        githubUrl?: string | undefined;
+    }[];
+    aboutTitle?: string | undefined;
+    aboutSubtitle?: string | undefined;
+    aboutMissionTitle?: string | undefined;
+    aboutMissionText?: string | undefined;
+    aboutHowItWorksTitle?: string | undefined;
+    aboutValuesTitle?: string | undefined;
+    aboutValuesSubtitle?: string | undefined;
+    aboutMilestonesTitle?: string | undefined;
+    aboutTeamTitle?: string | undefined;
+    aboutTeamSubtitle?: string | undefined;
+    aboutCtaTitle?: string | undefined;
+    aboutCtaSell?: string | undefined;
+    aboutCtaShop?: string | undefined;
+}>;
+export type SiteSettingsAboutFormValues = z.infer<typeof siteSettingsAboutFormSchema>;

package/dist/features/admin/schemas/site-settings-about-form.js

@@ -0,0 +1,142 @@
+/*
+ * WHY: `AdminSiteSettingsView`'s About tab (⓪, overrides the public About
+ *      page content) — nineteenth (and last field-by-field) tab migrated
+ *      to the Universal Template System (Phase 3B, admin site-settings
+ *      form rebuild, 2026-11-04). Seventeen fields: thirteen scalars plus
+ *      FOUR repeatable lists (`aboutHowItems`/`aboutValueItems`/
+ *      `aboutMilestones`/`aboutTeamMembers`).
+ *
+ *      Deliberately SEPARATE from `siteSettingsFormSchema` (render-only vs.
+ *      save-time validation — see the Branding schema's header for the full
+ *      reasoning, unchanged here). `siteSettingsFormSchema` does not
+ *      validate `aboutContent` at all.
+ *
+ * WHAT: Flat field names matching the component's own state, all writing
+ *       1:1 into `aboutContent.*` (no key renames, unlike most other
+ *       migrated tabs).
+ *
+ *       🛑 The four list fields use the GENERIC `<Repeater>` primitive
+ *       (`appkit/src/ui/components/Repeater.tsx`, the same one
+ *       `AdminBrandEditorView.faqs` already proves) rather than a
+ *       Collector-Drop-style hand-written custom renderer — confirmed by
+ *       reading the original JSX that none of these four carry Collector
+ *       Drop's special "last row is different" business rule; every item
+ *       here is uniformly addable/removable. This is the first tab in the
+ *       rollout where the generic Repeater is the right fit rather than a
+ *       bespoke renderer.
+ *
+ *       🛑 Accepted fidelity trade-off: `Repeater.renderRow(row, set)` does
+ *       NOT receive the row's index, so the original's "Step 1" / "Value 2"
+ *       / "Milestone 3" / "Team member 4" numbered labels above each row
+ *       (purely cosmetic, no functional role) could not be reproduced —
+ *       `Repeater` places a plain "Remove" button after each row's content
+ *       instead of a numbered header with an inline ✕. Not worth forking
+ *       the shared primitive, which several OTHER call sites already use
+ *       unchanged, for one tab's numbering preference.
+ *
+ *       🛑 `Repeater.max` is REQUIRED (its own doc comment: "unbounded by
+ *       default is how a form becomes a way to break the page it feeds"),
+ *       while the original had no cap at all. Picked generous product-sense
+ *       ceilings — 6 how-it-works steps, 8 values, 10 milestones, 12 team
+ *       members — comfortably above anything a real admin would enter; not
+ *       a new restriction in practice, just naming a number the original
+ *       left unstated.
+ *
+ *       `AboutTeamMember.githubUrl` exists on the TYPE but was never
+ *       rendered by the original JSX (no GitHub field in the team-member
+ *       block) — left unrendered here too, exactly as found, not a new
+ *       field this migration is adding.
+ *
+ * EXPORTS: siteSettingsAboutFormSchema, type SiteSettingsAboutFormValues
+ *
+ * @tag domain:admin
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminSiteSettingsView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta.js";
+const aboutHowItemSchema = z.object({
+    title: z.string(),
+    text: z.string(),
+    icon: z.string(),
+    tone: z.enum(["indigo", "teal", "amber", "rose"]).optional(),
+});
+const aboutValueItemSchema = z.object({
+    title: z.string(),
+    text: z.string(),
+    icon: z.string(),
+    detail: z.string().optional(),
+});
+const aboutMilestoneSchema = z.object({
+    year: z.string(),
+    text: z.string(),
+});
+const aboutTeamMemberSchema = z.object({
+    name: z.string(),
+    role: z.string(),
+    bio: z.string(),
+    photoUrl: z.string().optional(),
+    isFounder: z.boolean().optional(),
+    isDeveloper: z.boolean().optional(),
+    githubUrl: z.string().optional(),
+});
+export const siteSettingsAboutFormSchema = z.object({
+    aboutTitle: annotate(z.string().optional().or(z.literal("")), {
+        section: "about", sectionLabel: "About", sectionRequired: true,
+        order: 1, label: "Hero title",
+        help: "Override the About page content. Leave blank to use the platform defaults.",
+    }),
+    aboutSubtitle: annotate(z.string().optional().or(z.literal("")), {
+        section: "about", order: 2, label: "Hero subtitle",
+    }),
+    aboutMissionTitle: annotate(z.string().optional().or(z.literal("")), {
+        section: "about", order: 3, label: "Mission section title",
+    }),
+    aboutMissionText: annotate(z.string().optional().or(z.literal("")), {
+        section: "about", order: 4, row: "full", kind: "textarea", label: "Mission text",
+    }),
+    aboutHowItWorksTitle: annotate(z.string().optional().or(z.literal("")), {
+        section: "how-it-works", sectionLabel: "How it works", order: 1,
+        label: '"How it works" section title',
+    }),
+    aboutHowItems: annotate(z.array(aboutHowItemSchema), {
+        section: "how-it-works", order: 2, row: "full", label: "Steps",
+    }),
+    aboutValuesTitle: annotate(z.string().optional().or(z.literal("")), {
+        section: "values", sectionLabel: "Values", order: 1, label: "Values section title",
+    }),
+    aboutValuesSubtitle: annotate(z.string().optional().or(z.literal("")), {
+        section: "values", order: 2, label: "Values section subtitle",
+        help: "Optional intro line under the heading.",
+    }),
+    aboutValueItems: annotate(z.array(aboutValueItemSchema), {
+        section: "values", order: 3, row: "full", label: "Values",
+    }),
+    aboutMilestonesTitle: annotate(z.string().optional().or(z.literal("")), {
+        section: "milestones", sectionLabel: "Milestones", order: 1, label: "Milestones section title",
+    }),
+    aboutMilestones: annotate(z.array(aboutMilestoneSchema), {
+        section: "milestones", order: 2, row: "full", label: "Milestones",
+    }),
+    aboutTeamTitle: annotate(z.string().optional().or(z.literal("")), {
+        section: "team", sectionLabel: "Team", order: 1, label: "Team section title",
+    }),
+    aboutTeamSubtitle: annotate(z.string().optional().or(z.literal("")), {
+        section: "team", order: 2, label: "Team section subtitle",
+    }),
+    aboutTeamMembers: annotate(z.array(aboutTeamMemberSchema), {
+        section: "team", order: 3, row: "full", label: "Team members",
+    }),
+    aboutCtaTitle: annotate(z.string().optional().or(z.literal("")), {
+        section: "cta", sectionLabel: "CTA banner", order: 1, label: "CTA banner title",
+    }),
+    aboutCtaSell: annotate(z.string().optional().or(z.literal("")), {
+        section: "cta", order: 2, label: "Sell CTA copy",
+    }),
+    aboutCtaShop: annotate(z.string().optional().or(z.literal("")), {
+        section: "cta", order: 3, label: "Shop CTA copy",
+    }),
+});

package/dist/features/admin/schemas/site-settings-announcement-form.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export declare const siteSettingsAnnouncementFormSchema: z.ZodObject<{
+    announcementEnabled: z.ZodOptional<z.ZodBoolean>;
+    announcementText: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    announcementLink: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    announcementBg: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+}, "strip", z.ZodTypeAny, {
+    announcementEnabled?: boolean | undefined;
+    announcementText?: string | undefined;
+    announcementLink?: string | undefined;
+    announcementBg?: string | undefined;
+}, {
+    announcementEnabled?: boolean | undefined;
+    announcementText?: string | undefined;
+    announcementLink?: string | undefined;
+    announcementBg?: string | undefined;
+}>;
+export type SiteSettingsAnnouncementFormValues = z.infer<typeof siteSettingsAnnouncementFormSchema>;

package/dist/features/admin/schemas/site-settings-announcement-form.js

@@ -0,0 +1,53 @@
+/*
+ * WHY: `AdminSiteSettingsView`'s Announcement tab (③) — second tab migrated
+ *      to the Universal Template System (Phase 3B, admin site-settings form
+ *      rebuild, 2026-11-04), same pattern as the Branding tab
+ *      (`./site-settings-branding-form.ts`): hand-written `useState` + JSX
+ *      replaced with schema + `buildSectionsFromSchema`.
+ *
+ *      Constraints mirror the EXISTING `siteSettingsFormSchema.announcementBar`
+ *      group (`message` max 300, `link` an optional URL) so the render layer
+ *      never accepts something the save-time validator then rejects.
+ *
+ * WHAT: Flat field names matching the component's own state
+ *       (`announcementEnabled`, …), not the nested `announcementBar.*` keys
+ *       the save payload uses — `buildFullPayload()` does that transform.
+ *
+ * EXPORTS: siteSettingsAnnouncementFormSchema, type SiteSettingsAnnouncementFormValues
+ *
+ * @tag domain:admin
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminSiteSettingsView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta.js";
+/** Matches `siteSettingsFormSchema`'s own `optionalUrl`. */
+const optionalUrl = z.string().trim().url("Enter a full URL, including https://.").optional().or(z.literal(""));
+export const siteSettingsAnnouncementFormSchema = z.object({
+    announcementEnabled: annotate(z.boolean().optional(), {
+        section: "announcement", sectionLabel: "Announcement bar", sectionRequired: true,
+        order: 1, row: "full", kind: "toggle", label: "Show announcement bar",
+    }),
+    announcementText: annotate(z.string().trim().max(300).optional().or(z.literal("")), {
+        section: "announcement", order: 2, row: "pair", label: "Announcement text",
+        help: "e.g. \"\u{1F389} Free shipping on orders ₹999+\".",
+        when: (values) => Boolean(values.announcementEnabled),
+    }),
+    announcementLink: annotate(optionalUrl, {
+        section: "announcement", order: 3, row: "pair", label: "Link URL (optional)",
+        when: (values) => Boolean(values.announcementEnabled),
+    }),
+    /*
+     * No dedicated "color" FieldKind exists (`inputType` covers text/email/
+     * password/tel/url/search only), and adding one for a single field across
+     * this codebase isn't warranted — a custom `renderers` override is the
+     * same escape hatch already proven for the Branding tab's media fields.
+     */
+    announcementBg: annotate(z.string().trim().optional().or(z.literal("")), {
+        section: "announcement", order: 4, row: "pair", label: "Background color",
+        when: (values) => Boolean(values.announcementEnabled),
+    }),
+});

package/dist/features/admin/schemas/site-settings-appearance-form.d.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+declare const backgroundModeSchema: () => z.ZodObject<{
+    type: z.ZodEnum<["color", "gradient", "image", "video"]>;
+    value: z.ZodString;
+    overlayEnabled: z.ZodBoolean;
+    overlayColor: z.ZodString;
+    overlayOpacity: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    type: "video" | "image" | "color" | "gradient";
+    overlayEnabled: boolean;
+    overlayColor: string;
+    overlayOpacity: number;
+}, {
+    value: string;
+    type: "video" | "image" | "color" | "gradient";
+    overlayEnabled: boolean;
+    overlayColor: string;
+    overlayOpacity: number;
+}>;
+export type BackgroundModeValue = z.infer<ReturnType<typeof backgroundModeSchema>>;
+export declare const siteSettingsAppearanceFormSchema: z.ZodObject<{
+    lightBg: z.ZodObject<{
+        type: z.ZodEnum<["color", "gradient", "image", "video"]>;
+        value: z.ZodString;
+        overlayEnabled: z.ZodBoolean;
+        overlayColor: z.ZodString;
+        overlayOpacity: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        type: "video" | "image" | "color" | "gradient";
+        overlayEnabled: boolean;
+        overlayColor: string;
+        overlayOpacity: number;
+    }, {
+        value: string;
+        type: "video" | "image" | "color" | "gradient";
+        overlayEnabled: boolean;
+        overlayColor: string;
+        overlayOpacity: number;
+    }>;
+    darkBg: z.ZodObject<{
+        type: z.ZodEnum<["color", "gradient", "image", "video"]>;
+        value: z.ZodString;
+        overlayEnabled: z.ZodBoolean;
+        overlayColor: z.ZodString;
+        overlayOpacity: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        type: "video" | "image" | "color" | "gradient";
+        overlayEnabled: boolean;
+        overlayColor: string;
+        overlayOpacity: number;
+    }, {
+        value: string;
+        type: "video" | "image" | "color" | "gradient";
+        overlayEnabled: boolean;
+        overlayColor: string;
+        overlayOpacity: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    lightBg: {
+        value: string;
+        type: "video" | "image" | "color" | "gradient";
+        overlayEnabled: boolean;
+        overlayColor: string;
+        overlayOpacity: number;
+    };
+    darkBg: {
+        value: string;
+        type: "video" | "image" | "color" | "gradient";
+        overlayEnabled: boolean;
+        overlayColor: string;
+        overlayOpacity: number;
+    };
+}, {
+    lightBg: {
+        value: string;
+        type: "video" | "image" | "color" | "gradient";
+        overlayEnabled: boolean;
+        overlayColor: string;
+        overlayOpacity: number;
+    };
+    darkBg: {
+        value: string;
+        type: "video" | "image" | "color" | "gradient";
+        overlayEnabled: boolean;
+        overlayColor: string;
+        overlayOpacity: number;
+    };
+}>;
+export type SiteSettingsAppearanceFormValues = z.infer<typeof siteSettingsAppearanceFormSchema>;
+export {};

package/dist/features/admin/schemas/site-settings-appearance-form.js

@@ -0,0 +1,75 @@
+/*
+ * WHY: `AdminSiteSettingsView`'s Appearance tab (②, site-wide background
+ *      behind the public shell/dashboard sidebars/opted-in Section/Card) —
+ *      eighteenth tab migrated to the Universal Template System (Phase 3B,
+ *      admin site-settings form rebuild, 2026-11-04). Two fields
+ *      (`lightBg`/`darkBg`), each a structured object rather than a
+ *      scalar, because each mode's UI is a TYPE-CONDITIONAL control
+ *      (color picker / CSS-gradient textarea / media upload, switched on
+ *      the mode's own `type`) plus an overlay toggle+color+opacity and a
+ *      LIVE `<BackgroundRenderer>` preview that needs the whole mode's
+ *      config at once — none of that decomposes into independent scalar
+ *      fields the way every other migrated tab's fields do.
+ *
+ *      Deliberately SEPARATE from `siteSettingsFormSchema` (render-only vs.
+ *      save-time validation — see the Branding schema's header for the full
+ *      reasoning, unchanged here). `siteSettingsFormSchema` does not
+ *      validate `background` at all.
+ *
+ * WHAT: Two fields writing into `background.{light,dark}.{type,value,
+ *       overlay:{enabled,color,opacity}}`. `overlayOpacity` stays on its
+ *       UI scale (0-100) in this form's state, same as the original — the
+ *       ÷100 (save) and ×100-rounded (hydrate) conversions to the stored
+ *       0-1 scale happen in `buildFullPayload()`/the hydrate effect,
+ *       unchanged by this migration.
+ *
+ *       Both fields share ONE renderer FACTORY (`buildBackgroundRenderer`,
+ *       defined in the component, parameterized by `mode`) rather than two
+ *       independent hand-written blocks — the light/dark JSX was already
+ *       byte-structurally identical apart from the default swatch color
+ *       and the `<BackgroundRenderer mode>` prop, so duplicating it a
+ *       second time inside this migration would be adding the exact
+ *       drift this codebase's Duplication Decision Framework exists to
+ *       prevent, not removing it.
+ *
+ * EXPORTS: siteSettingsAppearanceFormSchema, type
+ *          SiteSettingsAppearanceFormValues, type BackgroundModeValue
+ *
+ * @tag domain:admin
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminSiteSettingsView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta.js";
+/*
+ * 🛑 A FACTORY, not a shared const — `annotate()` registers metadata keyed
+ * by SCHEMA OBJECT IDENTITY (a WeakMap), and returns the same instance it
+ * was given. Annotating one shared `z.object()` instance twice (once for
+ * `lightBg`, once for `darkBg`) would make the SECOND call silently
+ * overwrite the first's registry entry — both fields would then resolve
+ * to whichever metadata was written last, since `z.object({lightBg,
+ * darkBg})`'s shape would hold the IDENTICAL object reference for both
+ * keys. Measured live: `lightBg`'s `sectionRequired: true` was lost this
+ * way, so the whole Appearance section defaulted to collapsed instead of
+ * open. Call the factory once per field to get two distinct instances.
+ */
+const backgroundModeSchema = () => z.object({
+    type: z.enum(["color", "gradient", "image", "video"]),
+    value: z.string(),
+    overlayEnabled: z.boolean(),
+    overlayColor: z.string(),
+    overlayOpacity: z.number().min(0).max(100),
+});
+export const siteSettingsAppearanceFormSchema = z.object({
+    lightBg: annotate(backgroundModeSchema(), {
+        section: "appearance", sectionLabel: "Appearance", sectionRequired: true,
+        order: 1, row: "pair", label: "Light mode",
+        help: "Sets the background behind the public shell, dashboard sidebars, and any Section/Card that opts into it. Leave the value blank for a plain surface.",
+    }),
+    darkBg: annotate(backgroundModeSchema(), {
+        section: "appearance", order: 2, row: "pair", label: "Dark mode",
+    }),
+});

package/dist/features/admin/schemas/site-settings-branding-form.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export declare const siteSettingsBrandingFormSchema: z.ZodObject<{
+    siteName: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    tagline: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    logoUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    faviconUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    maintenanceMode: z.ZodOptional<z.ZodBoolean>;
+    maintenanceMessage: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    chatEnabled: z.ZodOptional<z.ZodBoolean>;
+    assistantEnabled: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    siteName?: string | undefined;
+    tagline?: string | undefined;
+    logoUrl?: string | undefined;
+    faviconUrl?: string | undefined;
+    maintenanceMode?: boolean | undefined;
+    maintenanceMessage?: string | undefined;
+    chatEnabled?: boolean | undefined;
+    assistantEnabled?: boolean | undefined;
+}, {
+    siteName?: string | undefined;
+    tagline?: string | undefined;
+    logoUrl?: string | undefined;
+    faviconUrl?: string | undefined;
+    maintenanceMode?: boolean | undefined;
+    maintenanceMessage?: string | undefined;
+    chatEnabled?: boolean | undefined;
+    assistantEnabled?: boolean | undefined;
+}>;
+export type SiteSettingsBrandingFormValues = z.infer<typeof siteSettingsBrandingFormSchema>;

package/dist/features/admin/schemas/site-settings-branding-form.js

@@ -0,0 +1,77 @@
+/*
+ * WHY: `AdminSiteSettingsView`'s Branding tab (⓪/① in the tab registry) was
+ *      eight independent `useState` calls and hand-written JSX — no schema,
+ *      no `buildSectionsFromSchema`, unlike the rest of the Universal
+ *      Template System rollout. First real tab migrated under that system
+ *      (Phase 3B, admin site-settings form rebuild, 2026-11-04).
+ *
+ *      Deliberately SEPARATE from `siteSettingsFormSchema`
+ *      (`./site-settings-form.ts`), which is the save-time VALIDATION schema
+ *      for the groups it already covers (commissions, gst, emi, …) and stays
+ *      untouched — it is `.passthrough()` and does not declare these fields,
+ *      so adding this schema changes nothing about what it validates. This
+ *      schema is RENDER-only, consumed by `buildSectionsFromSchema` to
+ *      generate the tab's fields; `handleSaveAll`'s existing
+ *      `siteSettingsFormSchema.safeParse(buildFullPayload())` call is
+ *      unaffected.
+ *
+ * WHAT: Flat field names matching the EXISTING component state
+ *       (`logoUrl`, `maintenanceMode`, …), not the nested keys the save
+ *       payload uses (`logo`, `maintenance.enabled`, …) — `buildFullPayload()`
+ *       already does that flat-to-nested transform and keeps doing so,
+ *       reading from this schema's values object instead of eight separate
+ *       `useState` vars.
+ *
+ * EXPORTS: siteSettingsBrandingFormSchema, type SiteSettingsBrandingFormValues
+ *
+ * @tag domain:admin
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminSiteSettingsView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta.js";
+export const siteSettingsBrandingFormSchema = z.object({
+    siteName: annotate(z.string().trim().max(120).optional().or(z.literal("")), {
+        section: "identity", sectionLabel: "Identity", sectionRequired: true,
+        order: 1, row: "pair", label: "Site name",
+    }),
+    tagline: annotate(z.string().trim().max(200).optional().or(z.literal("")), {
+        section: "identity", order: 2, row: "pair", label: "Tagline",
+        help: "e.g. \"India's Largest Collectibles Marketplace\".",
+    }),
+    logoUrl: annotate(z.string().optional().or(z.literal("")), {
+        section: "identity", order: 3, row: "pair", kind: "media",
+        sectionKeepMounted: true, label: "Logo",
+    }),
+    faviconUrl: annotate(z.string().optional().or(z.literal("")), {
+        section: "identity", order: 4, row: "pair", kind: "media",
+        sectionKeepMounted: true, label: "Favicon",
+    }),
+    maintenanceMode: annotate(z.boolean().optional(), {
+        section: "maintenance", sectionLabel: "Maintenance & messaging",
+        sectionRequired: true, order: 1,
+        row: "quarter", kind: "toggle", label: "Maintenance mode",
+    }),
+    /*
+     * `when` gates visibility, not validity — the message can stay blank while
+     * maintenance mode is off without needing a `superRefine`, since an empty
+     * string is always a valid value for this field. Mirrors the hand-written
+     * `disabled={!maintenanceMode}` this replaces.
+     */
+    maintenanceMessage: annotate(z.string().trim().max(300).optional().or(z.literal("")), {
+        section: "maintenance", order: 2, row: "full", label: "Maintenance message",
+        when: (values) => Boolean(values.maintenanceMode),
+    }),
+    chatEnabled: annotate(z.boolean().optional(), {
+        section: "maintenance", order: 3, row: "quarter", kind: "toggle",
+        label: "Buyer-seller messaging enabled",
+    }),
+    assistantEnabled: annotate(z.boolean().optional(), {
+        section: "maintenance", order: 4, row: "quarter", kind: "toggle",
+        label: "Customer assistant enabled",
+        help: "Floating chat widget + full-chat page.",
+    }),
+});