create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/config/promotion-popup.schema.ts

@@ -0,0 +1,29 @@
+import { defineSchema, field, type SettingsOf } from '@tanqory/theme-kit'
+
+/**
+ * Nova 13 · 9 promotion popup — NEW global settings (theme settings, not a
+ * section). Off for every store by default. Visual settings (preset,
+ * placement, scheme, image, copy) are kept apart from behaviour (delay,
+ * frequency): never before consent is answered, max once per session, never
+ * on cart / checkout. popupFrequency is stored locally only with consent
+ * (Preferences = DATA REQUIREMENT). Every other setting depends on
+ * popupEnabled.
+ */
+export const promotionPopupSchema = defineSchema(
+  { kind: 'global', name: 'popup', family: '13' },
+  {
+    popupEnabled: field.boolean(false),
+    popupPreset: field.select(['popup-newsletter', 'popup-offer', 'popup-announce'], 'popup-offer'),
+    popupPlacement: field.select(['center', 'side'], 'center'),
+    popupScheme: field.select(['surface', 'primary'], 'surface'),
+    popupImage: field.resource('image'),
+    popupHeading: field.text(''),
+    popupBody: field.richtext(''),
+    popupCtaLabel: field.text(''),
+    popupCtaLink: field.url(''),
+    popupDismissLabel: field.text('No thanks'),
+    popupDelay: field.select(['10s', '30s', 'exit-intent'], '30s'),
+    popupFrequency: field.select(['session', '7d', '30d'], '7d'),
+  },
+)
+export type PromotionPopupSettings = SettingsOf<typeof promotionPopupSchema>

package/templates/nova/config/settings.json

@@ -0,0 +1,23 @@
+{
+  "badgeStyle": "filled",
+  "buttonBorder": "default",
+  "buttonRadius": "medium",
+  "buttonTextStyle": "default",
+  "cardRadius": "medium",
+  "colorPrimary": "",
+  "enableCartDrawer": true,
+  "enableSearchModal": true,
+  "enableSpaNavigation": true,
+  "headingWeight": "medium",
+  "iconStyle": "outline",
+  "inputRadius": "medium",
+  "locale": "",
+  "logo": "",
+  "motion": "standard",
+  "pageWidth": "standard",
+  "sectionSpacing": "large",
+  "shopName": "",
+  "typeScale": "default",
+  "colorScheme": "light",
+  "badgeShape": "rounded"
+}

package/templates/nova/config/settings.schema.ts

@@ -0,0 +1,231 @@
+import { defineSettings, type SettingSpec } from '@tanqory/theme-kit'
+import { THEME_DEFAULTS, THEME_LEGACY, THEME_OPTIONS, type ThemeEnum } from '../src/styles/theme'
+import legacySettings from './legacy-settings.json'
+import { LEGACY_ENUM_VALUES } from '../lib/legacy-settings'
+
+/** A theme setting: a control plus the editor group it sits in. */
+type ThemeSettingSpec = SettingSpec & { group: string; visible_if?: string }
+
+/**
+ * Theme settings schema — everything a merchant configures theme-wide (as
+ * opposed to per-section `attributes`). The source for the editor's Theme
+ * panel and `theme.manifest.json`; `config/settings.json` holds the values.
+ *
+ * The design-system settings are the new UI's global settings
+ * (`ui/styles/theme.ts`): the 14 enums of THEME_OPTIONS plus `colorPrimary`.
+ * Their option ids and defaults are read from there, never restated, so this
+ * schema cannot offer a value `resolveTheme()` does not understand. Labels are
+ * the editor's words for each id.
+ *
+ * A saved value that is no longer an option (THEME_LEGACY, e.g. the old
+ * `sectionSpacing: medium`) is left out of the picker; `resolveTheme()` still
+ * renders it as the rung it maps to.
+ *
+ * The rest are runtime keys the storefront shell still reads: logo, shop name,
+ * interface language and three feature switches.
+ */
+
+/** Editor labels per option id. An id without one falls back to the id itself. */
+const LABELS: { [K in keyof ThemeEnum]: { label: string; group: string; info?: string; options: Record<ThemeEnum[K], string> } } = {
+  colorScheme: {
+    group: 'Colour',
+    label: 'Colour scheme',
+    options: { light: 'Light', dark: 'Dark' },
+    info: 'Dark switches every surface, text and border to the dark value set. The brand colour derives its dark variants.',
+  },
+  typeScale: {
+    group: 'Typography',
+    label: 'Type scale',
+    options: { compact: 'Compact', default: 'Default', large: 'Large' },
+    info: 'Scales headings; body text is unchanged.',
+  },
+  headingWeight: {
+    group: 'Typography',
+    label: 'Heading weight',
+    options: { regular: 'Regular', medium: 'Medium', semibold: 'Semibold' },
+  },
+  buttonTextStyle: {
+    group: 'Typography',
+    label: 'Button text',
+    options: { default: 'Default', uppercase: 'Uppercase' },
+  },
+  pageWidth: {
+    group: 'Layout',
+    label: 'Page width',
+    options: { standard: 'Standard (1280)', wide: 'Wide (1536)' },
+  },
+  sectionSpacing: {
+    group: 'Layout',
+    label: 'Section spacing',
+    options: { small: 'Small', large: 'Large', xlarge: 'Extra large' },
+    info: 'Scales the space above and below every section.',
+  },
+  buttonRadius: {
+    group: 'Components',
+    label: 'Button corners',
+    options: { none: 'Square', small: 'Slightly rounded', medium: 'Rounded', pill: 'Pill' },
+  },
+  buttonBorder: {
+    group: 'Components',
+    label: 'Secondary button border',
+    options: { default: 'Default', strong: 'Strong' },
+  },
+  inputRadius: {
+    group: 'Components',
+    label: 'Input corners',
+    options: { none: 'Square', small: 'Slightly rounded', medium: 'Rounded', pill: 'Pill' },
+  },
+  cardRadius: {
+    group: 'Components',
+    label: 'Card corners',
+    options: { none: 'Square', small: 'Slightly rounded', medium: 'Rounded', soft: 'Soft' },
+    info: 'Also rounds product and collection images.',
+  },
+  badgeStyle: {
+    group: 'Components',
+    label: 'Badge style',
+    options: { filled: 'Filled', outline: 'Outline' },
+  },
+  badgeShape: {
+    group: 'Components',
+    label: 'Badge shape',
+    options: { square: 'Square', rounded: 'Rounded', pill: 'Pill' },
+  },
+  iconStyle: {
+    group: 'Components',
+    label: 'Icon style',
+    options: { outline: 'Outline', filled: 'Filled' },
+  },
+  motion: {
+    group: 'Components',
+    label: 'Motion',
+    options: { standard: 'Standard', reduced: 'Reduced' },
+    info: 'Reduced-motion preferences always win regardless of this setting.',
+  },
+}
+
+/** One THEME_OPTIONS enum as a select, ids + default from ui/styles/theme.ts. */
+function themeEnum<K extends keyof ThemeEnum>(key: K): ThemeSettingSpec {
+  const meta = LABELS[key]
+  const labels = meta.options as Record<string, string>
+  const legacy = THEME_LEGACY[key] ?? {}
+  return {
+    type: 'select',
+    group: meta.group,
+    label: meta.label,
+    default: THEME_DEFAULTS[key],
+    options: [
+      ...(THEME_OPTIONS[key] as readonly string[]).filter((value) => !(value in legacy)).map((value) => ({ value, label: labels[value] ?? value })),
+      // Values stores saved under Nova v1/v2 that the redesign retired: still accepted (so saved content
+      // validates and publishes), rendered as their nearest rung (lib/legacy-settings.ts), labelled legacy.
+      ...[...new Set([...Object.keys(legacy), ...Object.keys(LEGACY_ENUM_VALUES[key] ?? {})])]
+        .filter((value) => !(THEME_OPTIONS[key] as readonly string[]).filter((v) => !(v in legacy)).includes(value))
+        .map((value) => ({ value, label: `${labels[value] ?? value} (legacy)` })),
+    ],
+    ...(meta.info ? { info: meta.info } : {}),
+  }
+}
+
+const schema: Record<string, ThemeSettingSpec> = {
+  // ── Brand ────────────────────────────────────────────────────────────────
+  logo: {
+    type: 'image',
+    group: 'Brand',
+    label: 'Logo',
+    default: '',
+    info: 'Shown in the header. Leave empty to use the logo from Settings → Brand.',
+  },
+  shopName: {
+    type: 'text',
+    group: 'Brand',
+    label: 'Shop name',
+    default: '',
+    placeholder: 'Store name',
+    info: 'Shown in the header when there is no logo, and in the browser tab. Leave empty to use the store name.',
+  },
+  // Applied by browser-entry.tsx / prerender.tsx through app/platform/locale.ts: the
+  // string map (locales/<code>.json) the theme's fixed interface words use
+  // before a visitor picks a language. An AI build sets it to its brief's language.
+  locale: {
+    type: 'select',
+    group: 'Brand',
+    label: 'Theme language',
+    default: '',
+    options: [
+      { value: '', label: 'English' },
+      { value: 'th', label: 'ไทย (Thai)' },
+    ],
+    info: 'The language of the theme’s own words — account menu, contact form, cart and policy headings. Your own text is never changed.',
+  },
+
+  // ── Colour ───────────────────────────────────────────────────────────────
+  // Only Primary is the merchant's; '' = not set → Settings → Brand, else the
+  // token default. A non-empty default would be written on every store.
+  colorPrimary: {
+    type: 'color',
+    group: 'Colour',
+    label: 'Primary (brand)',
+    default: THEME_DEFAULTS.colorPrimary,
+    info: 'Buttons, focus ring, selected states and link hover. Empty = the primary colour from Settings → Brand. The label colour on it is chosen for AA contrast automatically.',
+  },
+  colorScheme: themeEnum('colorScheme'),
+
+  // ── Typography ───────────────────────────────────────────────────────────
+  typeScale: themeEnum('typeScale'),
+  headingWeight: themeEnum('headingWeight'),
+  buttonTextStyle: themeEnum('buttonTextStyle'),
+
+  // ── Layout ───────────────────────────────────────────────────────────────
+  pageWidth: themeEnum('pageWidth'),
+  sectionSpacing: themeEnum('sectionSpacing'),
+
+  // ── Components ───────────────────────────────────────────────────────────
+  buttonRadius: themeEnum('buttonRadius'),
+  buttonBorder: themeEnum('buttonBorder'),
+  inputRadius: themeEnum('inputRadius'),
+  cardRadius: themeEnum('cardRadius'),
+  badgeStyle: themeEnum('badgeStyle'),
+  badgeShape: themeEnum('badgeShape'),
+  iconStyle: themeEnum('iconStyle'),
+  motion: themeEnum('motion'),
+
+  // ── Runtime switches ─────────────────────────────────────────────────────
+  enableSpaNavigation: {
+    type: 'boolean',
+    group: 'Header',
+    label: 'Instant page transitions (SPA)',
+    default: true,
+  },
+  enableSearchModal: {
+    type: 'boolean',
+    group: 'Search',
+    label: 'Enable search modal',
+    default: true,
+  },
+  enableCartDrawer: {
+    type: 'boolean',
+    group: 'Cart',
+    label: 'Enable cart drawer',
+    default: true,
+  },
+}
+
+/**
+ * Global settings Nova v1/v2 offered and the redesign does not show (config/legacy-settings.json,
+ * append-only). They stay DECLARED — hidden, no default — so a store's saved settings and what the
+ * AI store builder writes (`headerMenuHandle`, `footerHelpMenuHandle`, `accent`, `colorBrand`,
+ * `fontHeading`, `fontBody`, `footerTagline` …) still validate and publish. The menu and colour keys
+ * are honoured at render (lib/legacy-settings.ts); the rest are accepted and have no effect.
+ */
+for (const [key, spec] of Object.entries(legacySettings as Record<string, Omit<ThemeSettingSpec, 'group'> & { label?: string }>)) {
+  if (key in schema) continue
+  schema[key] = {
+    ...spec,
+    group: 'Legacy',
+    label: `${spec.label ?? key} (legacy)`,
+    info: 'Legacy setting: saved values keep working; not offered for new content.',
+    visible_if: '{{ false }}',
+  }
+}
+
+export default defineSettings(schema)

package/templates/nova/entry.abi.tsx

@@ -0,0 +1,27 @@
+/**
+ * Nova v3's Theme ABI v2 serve entry (theme-abi-v2.md §1): `render(request, ctx)` + `manifest`.
+ * Built into ONE file, `server/entry.mjs`, with no imports (scripts/abi/build.mjs, and the
+ * platform's own bundler from the same sources).
+ *
+ * The render itself is the kit's (`createRender` from @tanqory/theme-kit/server): routing from
+ * `ctx.route`, data from `ctx.data`, headers, cache hints, SEO head and the hydration state. Nova
+ * adds only what is Nova's: the settings and menus older Nova stores still carry
+ * (lib/legacy-settings.ts) and Settings › Brand colour as the default brand colour (D-3).
+ */
+import type { ThemeManifest } from '@tanqory/theme-abi'
+import { createRender } from '@tanqory/theme-kit/server'
+import { bundle } from './lib/bundle'
+import { applyLegacyMenus, effectiveSettings, withBrandColour } from './lib/legacy-settings'
+import manifestJson from './lib/abi/generated/manifest.json'
+
+/** Equal to manifest.json bytes minus the trailing LF after JCS (S3); the build writes both from one object. */
+export const manifest = manifestJson as unknown as ThemeManifest
+
+export const render = createRender({
+  manifest,
+  bundle,
+  effectiveSettings,
+  transformNodes: applyLegacyMenus,
+  // Settings › Brand colour is the theme's brand colour until the theme sets its own (D-3).
+  shopSettings: (settings, shop) => withBrandColour(settings, shop.brand?.colors?.primary?.[0]?.background),
+})

package/templates/nova/groups/footer.json

@@ -0,0 +1,39 @@
+{
+  "type": "footer",
+  "name": "Footer",
+  "sections": [
+    {
+      "type": "footer",
+      "id": "footer",
+      "settings": {},
+      "blocks": [
+        {
+          "type": "footer-brand",
+          "id": "footer-brand",
+          "settings": {}
+        },
+        {
+          "type": "footer-menu",
+          "id": "footer-menu-shop",
+          "settings": {
+            "menu": "footer-shop"
+          }
+        },
+        {
+          "type": "footer-menu",
+          "id": "footer-menu-help",
+          "settings": {
+            "menu": "footer-help"
+          }
+        },
+        {
+          "type": "footer-menu",
+          "id": "footer-menu-company",
+          "settings": {
+            "menu": "footer-company"
+          }
+        }
+      ]
+    }
+  ]
+}

package/templates/nova/groups/header.json

@@ -0,0 +1,11 @@
+{
+  "type": "header",
+  "name": "Header",
+  "sections": [
+    {
+      "type": "header",
+      "id": "header",
+      "settings": {}
+    }
+  ]
+}

package/templates/nova/lib/abi/abi.css

@@ -0,0 +1,41 @@
+/* Theme ABI v2 platform hooks (lib/abi). The section wrapper is layout-neutral; the preview-mode
+ * affordances paint only inside the editor canvas, which the platform bridge marks with
+ * body.tq-preview / .tq-preview-selected. */
+.tq-node { display: contents; }
+
+body.tq-preview [data-tq-node] { cursor: pointer; }
+
+/* Soft hover outline — guides the merchant toward what they can click. */
+body.tq-preview [data-tq-node]:hover > * {
+  outline: 2px dashed rgba(10, 10, 10, 0.35);
+  outline-offset: -2px;
+  transition: outline-color 120ms ease;
+}
+
+/* Solid selection outline (overrides hover when both apply). */
+body.tq-preview [data-tq-node].tq-preview-selected > * {
+  outline: 2px solid var(--color-fg);
+  outline-offset: -2px;
+}
+
+/* Tiny label sticking out the top-left of the selected section so the
+ * merchant can confirm WHICH section type they have selected. */
+body.tq-preview [data-tq-node].tq-preview-selected {
+  position: relative;
+}
+body.tq-preview [data-tq-node].tq-preview-selected::before {
+  content: attr(data-tq-section-type);
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: var(--z-dropdown);
+  background: var(--color-fg);
+  color: var(--color-bg);
+  font-family: var(--font-mono);
+  font-size: 11px;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  padding: 4px 8px;
+  pointer-events: none;
+}
+.nv-consent-slot { display: contents; }

package/templates/nova/lib/bundle-core.ts

@@ -0,0 +1,35 @@
+/**
+ * What the server and the browser bundles share (lib/bundle.ts, lib/bundle.client.ts): Nova's definition, its
+ * settings and schema, its region groups and its locale files. Store-independent — the same for every store an
+ * artifact serves — so it may live at module scope (theme-abi-v2.md §1, multi-tenant isolates).
+ *
+ * The locales are default imports, not an `import.meta.glob`: an eager glob is a namespace import, so the bundler
+ * must keep every top-level key of each JSON file as a named export next to its `default`, and each locale file
+ * was emitted twice in the browser bundle. `tests/bundle-split.test.ts` keeps this list equal to `locales/*.json`.
+ */
+import type { ThemeBundle } from '@tanqory/theme-kit'
+import theme from '../theme.config'
+import settings from '../config/settings.json'
+import settingsSchema from '../config/settings.schema'
+import ar from '../locales/ar.json'
+import en from '../locales/en.json'
+import th from '../locales/th.json'
+import '../assets/ai-tokens.css'
+import './abi/abi.css'
+
+export const LOCALE_FILES: ThemeBundle['locales'] = {
+  '../locales/ar.json': { default: ar },
+  '../locales/en.json': { default: en },
+  '../locales/th.json': { default: th },
+}
+
+export const bundleCore: Omit<ThemeBundle, 'templates'> = {
+  theme,
+  groups: import.meta.glob('../groups/*.json', { eager: true }),
+  locales: LOCALE_FILES,
+  settings: settings as Record<string, unknown>,
+  settingsSchema: settingsSchema as unknown as ThemeBundle['settingsSchema'],
+  // AI-generated `sections/*.tsx` are not part of a new-system artifact (storefront-system.ts drops them).
+  customSections: {},
+  manifest: null,
+}

package/templates/nova/lib/bundle.client.ts

@@ -0,0 +1,15 @@
+/**
+ * The theme bundle the browser entry hands `hydrate` (@tanqory/theme-kit/client). The same as lib/bundle.ts
+ * except for the templates: the page's content document arrives in the server's `tq-state` block, so the only
+ * template the browser reads is `404.json` (a product, collection or page the store does not have renders the
+ * not-found section with that template's settings, kit abi/page.ts `notFoundTree`). Shipping the other starter
+ * templates cost every shopper about 25 KB of script for nothing.
+ */
+import type { ThemeBundle } from '@tanqory/theme-kit'
+import notFound from '../templates/404.json'
+import { bundleCore } from './bundle-core'
+
+export const clientBundle: ThemeBundle = {
+  ...bundleCore,
+  templates: { '../templates/404.json': { default: notFound } },
+}

package/templates/nova/lib/bundle.ts

@@ -0,0 +1,15 @@
+/**
+ * The theme bundle the kit runtime is handed on the server (@tanqory/theme-kit: createRender) and in the tests:
+ * Nova's definition, its starter content and its settings schema (lib/bundle-core.ts), with every template.
+ * The browser entry takes lib/bundle.client.ts instead.
+ *
+ * The v1 catalogue (theme.manifest.json) is deliberately NOT imported: the ABI entries read the
+ * generated ABI manifest instead, and the browser bundle needs neither.
+ */
+import type { ThemeBundle } from '@tanqory/theme-kit'
+import { bundleCore } from './bundle-core'
+
+export const bundle: ThemeBundle = {
+  ...bundleCore,
+  templates: import.meta.glob('../templates/*.json', { eager: true }),
+}

package/templates/nova/lib/legacy-settings.ts

@@ -0,0 +1,104 @@
+/**
+ * Global theme settings Nova v3 no longer shows, but still HONOURS: keys that stores saved under
+ * Nova v1/v2 and that the AI store builder still writes into `config/settings.json`
+ * (the platform AI service docs/ONLINESTORE_INTEGRATION.md §3.5–§3.6).
+ *
+ *   headerMenuHandle        → the header's menu, when the header section names none of its own
+ *   footer{Shop,Help,Company}MenuHandle
+ *                           → the footer-menu column of that slot (`footer-shop` / `footer-help` /
+ *                             `footer-company`, or the block ids `footer-menu-<slot>`)
+ *   accent / colorBrand     → the primary (brand) colour, when `colorPrimary` is not set
+ *   sectionSpacing / pageWidth values the redesign dropped → the nearest rung (src/styles/theme.ts)
+ *
+ * Pure functions over the content the page renders. They run on the server AND in the browser
+ * (before the data plan, before render), so the menus the page needs are loaded and the hydrated
+ * tree is the one the server rendered. A section's OWN setting always wins over the global one.
+ * '' and whitespace mean "not set" everywhere here.
+ */
+import type { ContentNode } from '@tanqory/theme-kit'
+
+type Settings = Readonly<Record<string, unknown>>
+
+const set = (v: unknown): v is string => typeof v === 'string' && v.trim() !== ''
+const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/
+
+/** Footer-menu slot → the legacy global setting that names its menu. */
+export const FOOTER_MENU_SLOTS: Readonly<Record<string, string>> = {
+  'footer-shop': 'footerShopMenuHandle',
+  'footer-help': 'footerHelpMenuHandle',
+  'footer-company': 'footerCompanyMenuHandle',
+}
+
+/** Which footer slot a footer-menu block fills: its menu handle, else its id (`footer-menu-help`). */
+function footerSlotOf(node: ContentNode): string | null {
+  const menu = (node.settings as Record<string, unknown> | undefined)?.menu
+  if (set(menu)) return FOOTER_MENU_SLOTS[menu.trim()] ? menu.trim() : null
+  const m = /^footer-menu-(shop|help|company)$/.exec(String(node.id ?? ''))
+  return m ? `footer-${m[1]}` : null
+}
+
+function withSetting(node: ContentNode, key: string, value: string): ContentNode {
+  return { ...node, settings: { ...(node.settings ?? {}), [key]: value } }
+}
+
+function mapNode(node: ContentNode, settings: Settings): ContentNode {
+  let out = node
+  const own = (node.settings ?? {}) as Record<string, unknown>
+  if (node.type === 'header' && !set(own.menu) && set(settings.headerMenuHandle)) {
+    out = withSetting(out, 'menu', settings.headerMenuHandle.trim())
+  }
+  if (node.type === 'footer-menu') {
+    const slot = footerSlotOf(node)
+    const key = slot ? FOOTER_MENU_SLOTS[slot] : undefined
+    const handle = key ? settings[key] : undefined
+    if (set(handle) && handle.trim() !== own.menu) out = withSetting(out, 'menu', handle.trim())
+  }
+  if (Array.isArray(node.blocks) && node.blocks.length) {
+    const blocks = node.blocks.map((b) => mapNode(b, settings))
+    if (blocks.some((b, i) => b !== node.blocks![i])) out = { ...out, blocks }
+  }
+  return out
+}
+
+/** The nodes as they render under the store's global settings (legacy menu keys applied). */
+export function applyLegacyMenus(nodes: readonly ContentNode[], settings: Settings): ContentNode[] {
+  const out = nodes.map((n) => mapNode(n, settings))
+  return out.some((n, i) => n !== nodes[i]) ? out : (nodes as ContentNode[])
+}
+
+/** Saved values of the redesign's enums that are no longer options → the rung they render as. */
+export const LEGACY_ENUM_VALUES: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  sectionSpacing: { none: 'small', medium: 'large' },
+  pageWidth: { full: 'wide' },
+}
+
+/**
+ * The global settings the theme renders with: '' = not set, legacy colour keys as the brand
+ * colour's fallback, retired enum values mapped to their rung. Never adds a key the store did
+ * not set except `colorPrimary` from its legacy sources.
+ */
+export function effectiveSettings(settings: Settings): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...settings }
+  if (!set(out.colorPrimary)) {
+    const legacy = [settings.accent, settings.colorBrand].find((v) => set(v) && HEX.test(v.trim()))
+    if (typeof legacy === 'string') out.colorPrimary = legacy.trim()
+  }
+  for (const [key, map] of Object.entries(LEGACY_ENUM_VALUES)) {
+    const v = out[key]
+    if (typeof v === 'string' && map[v]) out[key] = map[v]
+  }
+  return out
+}
+
+/**
+ * Settings › Brand › primary colour as the theme's default brand colour (D-3): used only while the
+ * theme's own colour is not set — neither `colorPrimary` nor a legacy `accent` / `colorBrand`
+ * (both already folded into `colorPrimary` by `effectiveSettings`). Once the merchant picks a theme
+ * colour, that colour wins. A brand colour that is not a hex value is ignored. Returns the same
+ * object when nothing changes.
+ */
+export function withBrandColour<T extends Record<string, unknown>>(settings: T, brandPrimary: unknown): T {
+  if (set(settings.colorPrimary)) return settings
+  if (!set(brandPrimary) || !HEX.test(brandPrimary.trim())) return settings
+  return { ...settings, colorPrimary: brandPrimary.trim() }
+}