create-mercato-app 0.6.1-develop.3276.1.1fcd145078 → 0.6.1-develop.3287.1.450f4ffb56

package/agentic/shared/ai/skills/backend-ui-design/references/ui-components.md

@@ -68,13 +68,35 @@ Complete reference of all available UI components in `@open-mercato/ui`.
 
 ### Input Components (`@open-mercato/ui/backend/inputs/*`)
 
+Specialized inputs that ship with the framework. For each, the full props table, MUST rules, and anti-patterns live in `.ai/ui-components.md` under the section linked from the component name.
+
+| Component | Import Path | Purpose | Key Props |
+|-----------|-------------|---------|-----------|
+| **ComboboxInput** | `@open-mercato/ui/backend/inputs/ComboboxInput` | Single-value typeahead with sync/async suggestions; allows free-form custom values by default | `value`, `onChange`, `suggestions`, `loadSuggestions`, `resolveLabel`, `allowCustomValues` |
+| **TagsInput** | `@open-mercato/ui/backend/inputs/TagsInput` | Multi-value (`string[]`) version of `ComboboxInput` with rich `{ value, label, description }` triples | `value`, `onChange`, `suggestions`, `loadSuggestions`, `selectedOptions`, `resolveLabel` |
+| **LookupSelect** | `@open-mercato/ui/backend/inputs/LookupSelect` | Rich card-list search/select with title/subtitle/icon/badge per row; returns selected id | `value`, `onChange`, `fetchItems`, `options`, `minQuery`, `actionSlot` |
+| **PhoneNumberField** | `@open-mercato/ui/backend/inputs/PhoneNumberField` | Compound country-picker + national-number input matching Figma `Text Input [1.1]` Phone variant. Validates + normalizes on blur, optional duplicate lookup | `value`, `onValueChange`, `onDigitsChange`, `countries`, `defaultCountryIso2`, `onDuplicateLookup` |
+| **EventSelect** | `@open-mercato/ui/backend/inputs/EventSelect` | Strict select for declared platform events, grouped by module. **Mandated by `packages/ui/AGENTS.md`** for event selection | `value`, `onChange`, `categories`, `modules`, `excludeTriggerExcluded`, `size` |
+| **EventPatternInput** | `@open-mercato/ui/backend/inputs/EventPatternInput` | `ComboboxInput` preloaded with declared events that allows wildcard patterns (e.g. `sales.orders.*`) | `value`, `onChange`, `categories`, `modules` |
+| **TimeInput** | `@open-mercato/ui/backend/inputs/TimeInput` | Bare `HH:MM` editor (two `<input type="number">` cells, no popover). Low-level atom — most flows want `TimePicker` | `value`, `onChange`, `minuteStep`, `hourLabel`, `minuteLabel` |
+| **DatePicker** *(@deprecated shim — import from `primitives/date-picker`)* | `@open-mercato/ui/backend/inputs/DatePicker` | Backward-compat re-export of the `DatePicker` primitive. New code MUST import from `@open-mercato/ui/primitives/date-picker`. | — |
+| **DateTimePicker** *(@deprecated shim — use `DatePicker withTime`)* | `@open-mercato/ui/backend/inputs/DateTimePicker` | Thin wrapper that always sets `withTime` on the primitive. New code: `<DatePicker withTime />` | — |
+| **TimePicker** *(@deprecated shim — import from `primitives/time-picker`)* | `@open-mercato/ui/backend/inputs/TimePicker` | Legacy popover-anchored time picker wrapping the new `TimePicker` primitive. New code: `@open-mercato/ui/primitives/time-picker`. | — |
+| **SwitchableMarkdownInput** *(@deprecated — use `RichEditor`)* | `@open-mercato/ui/backend/inputs/SwitchableMarkdownInput` | Markdown ⇄ plain textarea toggle. Kept only for backward compatibility with Markdown-backed surfaces. New rich-text fields MUST use `RichEditor` from `@open-mercato/ui/primitives/rich-editor` (sanitized HTML). | `value`, `onChange`, `isMarkdownEnabled` |
+
+### Input Variants (Figma `Text Input [1.1]` — `@open-mercato/ui/primitives/*`)
+
+Foundation-level input variants matching Figma type-specific designs. Use these instead of raw `<Input type="email">`, `<Input type="password">`, etc. — they ship correct visual chrome (leading icons, prefix boxes, trailing buttons, brand badges) and i18n-resolved labels.
+
 | Component | Import Path | Purpose | Key Props |
 |-----------|-------------|---------|-----------|
-| **TagsInput** | `@open-mercato/ui/backend/inputs/TagsInput` | Multi-tag input with suggestions | `value`, `onChange`, `placeholder`, `suggestions` |
-| **ComboboxInput** | `@open-mercato/ui/backend/inputs/ComboboxInput` | Searchable dropdown (single value) | `value`, `onChange`, `options`, `placeholder` |
-| **PhoneNumberField** | `@open-mercato/ui/backend/inputs/PhoneNumberField` | Phone input with formatting | `value`, `onChange`, `checkDuplicate` |
-| **LookupSelect** | `@open-mercato/ui/backend/inputs/LookupSelect` | Async lookup/search select | `value`, `onChange`, `onSearch`, `renderItem` |
-| **SwitchableMarkdownInput** | `@open-mercato/ui/backend/inputs/SwitchableMarkdownInput` | Text/markdown toggle input | `value`, `onChange`, `placeholder` |
+| **EmailInput** | `@open-mercato/ui/primitives/email-input` | `Input` wrapper with leading Mail icon, `type="email"`, `autoComplete="email"` | `value`, `onChange`, `showIcon` |
+| **SearchInput** | `@open-mercato/ui/primitives/search-input` | Leading Search icon + trailing × clear button (when value non-empty). Use for DataTable global filter, command palette, list-view live filter | `value`, `onChange`, `onClear`, `clearable` |
+| **PasswordInput** | `@open-mercato/ui/primitives/password-input` | Leading Lock icon + trailing Eye/EyeOff reveal toggle. Controlled or uncontrolled reveal state | `value`, `onChange`, `revealable`, `revealed`, `onRevealedChange`, `showLockIcon` |
+| **WebsiteInput** | `@open-mercato/ui/primitives/website-input` | Left "https://" prefix box + divider + URL input. `type="url"` | `value`, `onChange`, `prefix`, `showPrefix` |
+| **AmountInput** | `@open-mercato/ui/primitives/amount-input` | Leading currency symbol + numeric input + trailing ISO currency picker (10 markets default) | `value: { amount, currency }`, `onChange`, `currencies`, `showCurrency` |
+| **ButtonInput** | `@open-mercato/ui/primitives/button-input` | Input with optional `leftIcon` + divider + required `trailingAction` slot for interactive button (copy URL, send, regenerate) | `leftIcon`, `trailingAction` (required) |
+| **CardInput** | `@open-mercato/ui/primitives/card-input` | Credit-card-number input with regex-based brand auto-detection (Visa/MC/Amex/Discover/Diners/JCB/UnionPay), format masking, brand badge | `value` (digits-only), `onChange`, `onBrandChange`, `brands` |
 
 ### Detail Page Components (`@open-mercato/ui/backend/detail/*`)
 

package/dist/agentic/shared/ai/skills/backend-ui-design/references/ui-components.md

@@ -68,13 +68,35 @@ Complete reference of all available UI components in `@open-mercato/ui`.
 
 ### Input Components (`@open-mercato/ui/backend/inputs/*`)
 
+Specialized inputs that ship with the framework. For each, the full props table, MUST rules, and anti-patterns live in `.ai/ui-components.md` under the section linked from the component name.
+
+| Component | Import Path | Purpose | Key Props |
+|-----------|-------------|---------|-----------|
+| **ComboboxInput** | `@open-mercato/ui/backend/inputs/ComboboxInput` | Single-value typeahead with sync/async suggestions; allows free-form custom values by default | `value`, `onChange`, `suggestions`, `loadSuggestions`, `resolveLabel`, `allowCustomValues` |
+| **TagsInput** | `@open-mercato/ui/backend/inputs/TagsInput` | Multi-value (`string[]`) version of `ComboboxInput` with rich `{ value, label, description }` triples | `value`, `onChange`, `suggestions`, `loadSuggestions`, `selectedOptions`, `resolveLabel` |
+| **LookupSelect** | `@open-mercato/ui/backend/inputs/LookupSelect` | Rich card-list search/select with title/subtitle/icon/badge per row; returns selected id | `value`, `onChange`, `fetchItems`, `options`, `minQuery`, `actionSlot` |
+| **PhoneNumberField** | `@open-mercato/ui/backend/inputs/PhoneNumberField` | Compound country-picker + national-number input matching Figma `Text Input [1.1]` Phone variant. Validates + normalizes on blur, optional duplicate lookup | `value`, `onValueChange`, `onDigitsChange`, `countries`, `defaultCountryIso2`, `onDuplicateLookup` |
+| **EventSelect** | `@open-mercato/ui/backend/inputs/EventSelect` | Strict select for declared platform events, grouped by module. **Mandated by `packages/ui/AGENTS.md`** for event selection | `value`, `onChange`, `categories`, `modules`, `excludeTriggerExcluded`, `size` |
+| **EventPatternInput** | `@open-mercato/ui/backend/inputs/EventPatternInput` | `ComboboxInput` preloaded with declared events that allows wildcard patterns (e.g. `sales.orders.*`) | `value`, `onChange`, `categories`, `modules` |
+| **TimeInput** | `@open-mercato/ui/backend/inputs/TimeInput` | Bare `HH:MM` editor (two `<input type="number">` cells, no popover). Low-level atom — most flows want `TimePicker` | `value`, `onChange`, `minuteStep`, `hourLabel`, `minuteLabel` |
+| **DatePicker** *(@deprecated shim — import from `primitives/date-picker`)* | `@open-mercato/ui/backend/inputs/DatePicker` | Backward-compat re-export of the `DatePicker` primitive. New code MUST import from `@open-mercato/ui/primitives/date-picker`. | — |
+| **DateTimePicker** *(@deprecated shim — use `DatePicker withTime`)* | `@open-mercato/ui/backend/inputs/DateTimePicker` | Thin wrapper that always sets `withTime` on the primitive. New code: `<DatePicker withTime />` | — |
+| **TimePicker** *(@deprecated shim — import from `primitives/time-picker`)* | `@open-mercato/ui/backend/inputs/TimePicker` | Legacy popover-anchored time picker wrapping the new `TimePicker` primitive. New code: `@open-mercato/ui/primitives/time-picker`. | — |
+| **SwitchableMarkdownInput** *(@deprecated — use `RichEditor`)* | `@open-mercato/ui/backend/inputs/SwitchableMarkdownInput` | Markdown ⇄ plain textarea toggle. Kept only for backward compatibility with Markdown-backed surfaces. New rich-text fields MUST use `RichEditor` from `@open-mercato/ui/primitives/rich-editor` (sanitized HTML). | `value`, `onChange`, `isMarkdownEnabled` |
+
+### Input Variants (Figma `Text Input [1.1]` — `@open-mercato/ui/primitives/*`)
+
+Foundation-level input variants matching Figma type-specific designs. Use these instead of raw `<Input type="email">`, `<Input type="password">`, etc. — they ship correct visual chrome (leading icons, prefix boxes, trailing buttons, brand badges) and i18n-resolved labels.
+
 | Component | Import Path | Purpose | Key Props |
 |-----------|-------------|---------|-----------|
-| **TagsInput** | `@open-mercato/ui/backend/inputs/TagsInput` | Multi-tag input with suggestions | `value`, `onChange`, `placeholder`, `suggestions` |
-| **ComboboxInput** | `@open-mercato/ui/backend/inputs/ComboboxInput` | Searchable dropdown (single value) | `value`, `onChange`, `options`, `placeholder` |
-| **PhoneNumberField** | `@open-mercato/ui/backend/inputs/PhoneNumberField` | Phone input with formatting | `value`, `onChange`, `checkDuplicate` |
-| **LookupSelect** | `@open-mercato/ui/backend/inputs/LookupSelect` | Async lookup/search select | `value`, `onChange`, `onSearch`, `renderItem` |
-| **SwitchableMarkdownInput** | `@open-mercato/ui/backend/inputs/SwitchableMarkdownInput` | Text/markdown toggle input | `value`, `onChange`, `placeholder` |
+| **EmailInput** | `@open-mercato/ui/primitives/email-input` | `Input` wrapper with leading Mail icon, `type="email"`, `autoComplete="email"` | `value`, `onChange`, `showIcon` |
+| **SearchInput** | `@open-mercato/ui/primitives/search-input` | Leading Search icon + trailing × clear button (when value non-empty). Use for DataTable global filter, command palette, list-view live filter | `value`, `onChange`, `onClear`, `clearable` |
+| **PasswordInput** | `@open-mercato/ui/primitives/password-input` | Leading Lock icon + trailing Eye/EyeOff reveal toggle. Controlled or uncontrolled reveal state | `value`, `onChange`, `revealable`, `revealed`, `onRevealedChange`, `showLockIcon` |
+| **WebsiteInput** | `@open-mercato/ui/primitives/website-input` | Left "https://" prefix box + divider + URL input. `type="url"` | `value`, `onChange`, `prefix`, `showPrefix` |
+| **AmountInput** | `@open-mercato/ui/primitives/amount-input` | Leading currency symbol + numeric input + trailing ISO currency picker (10 markets default) | `value: { amount, currency }`, `onChange`, `currencies`, `showCurrency` |
+| **ButtonInput** | `@open-mercato/ui/primitives/button-input` | Input with optional `leftIcon` + divider + required `trailingAction` slot for interactive button (copy URL, send, regenerate) | `leftIcon`, `trailingAction` (required) |
+| **CardInput** | `@open-mercato/ui/primitives/card-input` | Credit-card-number input with regex-based brand auto-detection (Visa/MC/Amex/Discover/Diners/JCB/UnionPay), format masking, brand badge | `value` (digits-only), `onChange`, `onBrandChange`, `brands` |
 
 ### Detail Page Components (`@open-mercato/ui/backend/detail/*`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.6.1-develop.3276.1.1fcd145078",
+  "version": "0.6.1-develop.3287.1.450f4ffb56",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",

package/template/.env.example

@@ -480,3 +480,64 @@ OCR_MODEL=gpt-4o
 
 # Index prefix for tenant isolation (default: om)
 # MEILISEARCH_INDEX_PREFIX=om
+
+# ============================================================================
+# Customer Portal Custom Domain (Phase 1–3)
+# ============================================================================
+# See .ai/specs/2026-04-08-portal-custom-domain-routing.md and
+# docker/traefik/README.md. Required when custom-domain mappings are in use.
+
+# Primary platform host — excluded from the Traefik domain-check middleware
+# and treated as the platform pass-through host by the Node middleware.
+PLATFORM_PRIMARY_HOST=openmercato.local
+
+# Mandatory shared secret for /api/customer_accounts/domain-check
+# (Traefik ForwardAuth gate). Generate with: openssl rand -hex 32
+DOMAIN_CHECK_SECRET=
+
+# Mandatory shared secret for the Node middleware's calls to
+# /api/customer_accounts/domain-resolve. Generate with: openssl rand -hex 32
+DOMAIN_RESOLVE_SECRET=
+
+# Internal origin the proxy uses to call domain-resolve. Defaults to
+# http://app:3000 inside docker; set to your local app for `yarn dev`.
+INTERNAL_APP_ORIGIN=http://127.0.0.1:3000
+
+# DNS targets surfaced to admins in the back office.
+CUSTOM_DOMAIN_CNAME_TARGET=portal.openmercato.local
+CUSTOM_DOMAIN_A_RECORD_TARGET=
+
+# Optional cache tuning (defaults: 60 / 300 / 10000)
+# DOMAIN_CACHE_TTL_SECONDS=60
+# DOMAIN_NEGATIVE_CACHE_TTL_SECONDS=300
+# DOMAIN_CACHE_MAX_ENTRIES=10000
+
+# Optional override for the marker header set on /_next/health
+# CUSTOMER_DOMAIN_ORIGIN_HEADER=X-Open-Mercato-Origin
+
+# Background verification (Phase 5) — both workers are scheduled
+# automatically by `mercato init` via the system scheduler.
+# DNS auto-verification scan interval (default 300s = 5 min).
+# DOMAIN_AUTO_VERIFY_INTERVAL_SECONDS=300
+# TLS retry scan interval (default 1800s = 30 min).
+# DOMAIN_TLS_RETRY_INTERVAL_SECONDS=1800
+# Per-run cap for the TLS retry worker (default 50).
+# DOMAIN_TLS_RETRY_BATCH=50
+# Failure-rate threshold (0–1) that triggers worker-level backoff (default 0.8).
+# DOMAIN_TLS_RETRY_FAILURE_THRESHOLD=0.8
+# Maximum tls_retry_count before the worker stops retrying (default 6).
+# DOMAIN_TLS_MAX_RETRIES=6
+
+# --- Traefik (only for docker-compose.fullapp{,.dev}.yml) ---
+# Let's Encrypt contact address.
+ACME_EMAIL=
+# Defaults to LE production. Dev compose defaults to LE staging.
+# TRAEFIK_CA_SERVER=https://acme-staging-v02.api.letsencrypt.org/directory
+# TRAEFIK_HTTP_PORT=80
+# TRAEFIK_HTTPS_PORT=443
+# TRAEFIK_DASHBOARD_PORT=8081
+
+# --- Test-only Host spoof (NEVER set in production) ---
+# Activates only when NODE_ENV=test. Used by Playwright to drive arbitrary
+# Host values without DNS. Generate with: openssl rand -hex 32
+# FORCE_HOST_SECRET=

package/template/src/app/globals.css

@@ -22,6 +22,14 @@ TODO: Fix that latter to have reference by the package names
   z-index: var(--z-index-popover);
 }
 
+/* Explicitly written outside @theme — Tailwind 4 only emits @theme inline
+   variables that some compiled utility references, so writing the value
+   inline here guarantees the rule lands in the bundle even if the source
+   scanner misses the className literal. */
+@utility z-modal-elevated {
+  z-index: var(--z-index-modal-elevated, 55);
+}
+
 @theme inline {
   --color-background: var(--background);
   --color-foreground: var(--foreground);
@@ -93,6 +101,11 @@ TODO: Fix that latter to have reference by the package names
   --color-status-neutral-border: var(--status-neutral-border);
   --color-status-neutral-icon: var(--status-neutral-icon);
 
+  --color-status-pink-bg: var(--status-pink-bg);
+  --color-status-pink-text: var(--status-pink-text);
+  --color-status-pink-border: var(--status-pink-border);
+  --color-status-pink-icon: var(--status-pink-icon);
+
   /* ═══ Design System: Accent Colors ═══ */
   --color-accent-indigo: var(--accent-indigo);
   --color-accent-indigo-foreground: var(--accent-indigo-foreground);
@@ -121,6 +134,7 @@ TODO: Fix that latter to have reference by the package names
   --z-index-overlay: 30;
   --z-index-modal: 40;
   --z-index-popover: 45;
+  --z-index-modal-elevated: 55;
   --z-index-toast: 50;
   --z-index-tooltip: 60;
   --z-index-banner: 70;
@@ -250,6 +264,12 @@ TODO: Fix that latter to have reference by the package names
   --status-neutral-text: oklch(0.445 0 0);
   --status-neutral-border: oklch(0.850 0 0);
   --status-neutral-icon: oklch(0.556 0 0);  /* = --muted-foreground */
+
+  /* Pink (hue ~340° — Figma SPEC-048 ACCENT / PINK Stage badges; Tailwind pink-500/-200/-700/-50) */
+  --status-pink-bg: oklch(0.965 0.020 340);   /* pink-50 #FDF2F8 */
+  --status-pink-text: oklch(0.388 0.180 340); /* pink-700 #BE185D */
+  --status-pink-border: oklch(0.840 0.090 340);/* pink-200 #FBCFE8 */
+  --status-pink-icon: oklch(0.633 0.238 340); /* pink-500 #EC4899 */
 }
 
 /* Opt-in Figma-style focus ring: 2px inner ring + 4px outer ring */
@@ -358,6 +378,12 @@ TODO: Fix that latter to have reference by the package names
   --status-neutral-text: oklch(0.750 0 0);
   --status-neutral-border: oklch(0.380 0 0);
   --status-neutral-icon: oklch(0.708 0 0);  /* = dark --muted-foreground */
+
+  /* Pink (dark mode) — Figma SPEC-048 ACCENT / PINK Stage badges */
+  --status-pink-bg: oklch(0.225 0.045 340);
+  --status-pink-text: oklch(0.815 0.135 340);
+  --status-pink-border: oklch(0.405 0.155 340);
+  --status-pink-icon: oklch(0.700 0.225 340);
 }
 
 @layer base {

package/template/src/components/DemoFeedbackWidget.tsx

@@ -7,6 +7,7 @@ import { MessageCircle, Send } from 'lucide-react'
 import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription } from '@open-mercato/ui/primitives/dialog'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Input } from '@open-mercato/ui/primitives/input'
+import { EmailInput } from '@open-mercato/ui/primitives/email-input'
 import { Textarea } from '@open-mercato/ui/primitives/textarea'
 import { Checkbox } from '@open-mercato/ui/primitives/checkbox'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
@@ -279,9 +280,8 @@ export function DemoFeedbackWidget({ demoModeEnabled }: { demoModeEnabled: boole
               )}
 
               <div className="grid gap-1">
-                <Input
+                <EmailInput
                   id="feedback-email"
-                  type="email"
                   placeholder={t('demoFeedback.form.email', 'Your email')}
                   value={email}
                   onChange={(e) => setEmail(e.target.value)}

package/template/src/lib/customDomainCache.ts

@@ -0,0 +1,239 @@
+import { normalizeHostname, tryNormalizeHostname } from '@open-mercato/core/modules/customer_accounts/lib/hostname'
+
+export type DomainResolution = {
+  hostname: string
+  tenantId: string
+  organizationId: string
+  orgSlug: string | null
+  status: 'active'
+}
+
+type PositiveEntry = {
+  isNegative: false
+  data: DomainResolution
+  expiresAt: number
+}
+
+type NegativeEntry = {
+  isNegative: true
+  expiresAt: number
+}
+
+type CacheEntry = PositiveEntry | NegativeEntry
+
+export type CacheLookup =
+  | { kind: 'fresh-hit'; data: DomainResolution | null }
+  | { kind: 'stale-hit'; data: DomainResolution | null }
+  | { kind: 'cold-miss' }
+
+export type DomainResolver = (hostname: string) => Promise<DomainResolution | null>
+
+export type CustomDomainCacheOptions = {
+  positiveTtlMs: number
+  negativeTtlMs: number
+  maxEntries: number
+  resolver: DomainResolver
+  now?: () => number
+  onWarmupError?: (error: unknown) => void
+  onResolveError?: (hostname: string, error: unknown) => void
+  /**
+   * Maximum number of in-flight resolver promises. When exceeded, new unique
+   * hostnames are dropped (resolved as `null`) instead of starting another
+   * fetch. Prevents unbounded `inFlight` growth under hostname-flood probing.
+   * Defaults to `maxEntries` when omitted.
+   */
+  maxInFlight?: number
+  /**
+   * Invoked once when an in-flight slot is denied to a new hostname because
+   * the cap is saturated. The cache rate-limits its own warning, so this hook
+   * fires every time but the default warning logger does not spam.
+   */
+  onInFlightCapReached?: (hostname: string) => void
+}
+
+const POSITIVE_TTL_DEFAULT_SECONDS = 60
+const NEGATIVE_TTL_DEFAULT_SECONDS = 60
+// Hard ceiling for the per-process negative TTL. There is no in-process
+// invalidation hook between Next.js workers — only the shared cache is
+// invalidated when a domain becomes active — so a longer negative TTL means
+// a newly registered domain can stay unresolved on a given process up to
+// this many seconds. Keep it under one minute to bound that propagation
+// delay for real customers while still absorbing unknown-hostname probing.
+const NEGATIVE_TTL_MAX_SECONDS = 60
+const MAX_ENTRIES_DEFAULT = 10_000
+
+function readNumberEnv(name: string, fallbackSeconds: number, maxSeconds?: number): number {
+  const raw = process.env[name]
+  if (!raw) return fallbackSeconds * 1000
+  const parsed = Number(raw)
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallbackSeconds * 1000
+  const seconds = maxSeconds !== undefined ? Math.min(parsed, maxSeconds) : parsed
+  return seconds * 1000
+}
+
+function readMaxEntriesEnv(): number {
+  const raw = process.env.DOMAIN_CACHE_MAX_ENTRIES
+  if (!raw) return MAX_ENTRIES_DEFAULT
+  const parsed = Number(raw)
+  if (!Number.isFinite(parsed) || parsed <= 0) return MAX_ENTRIES_DEFAULT
+  return Math.floor(parsed)
+}
+
+const IN_FLIGHT_CAP_WARN_INTERVAL_MS = 60_000
+
+export function createCustomDomainCache(options: CustomDomainCacheOptions) {
+  const {
+    positiveTtlMs,
+    negativeTtlMs,
+    maxEntries,
+    resolver,
+    now = Date.now,
+    onResolveError,
+    onInFlightCapReached,
+  } = options
+  const maxInFlight = Math.max(1, Math.floor(options.maxInFlight ?? maxEntries))
+
+  // Map preserves insertion order — re-inserting on access yields LRU semantics.
+  const store = new Map<string, CacheEntry>()
+  const inFlight = new Map<string, Promise<DomainResolution | null>>()
+  let lastCapWarnAt = 0
+
+  function touch(key: string, entry: CacheEntry): void {
+    store.delete(key)
+    store.set(key, entry)
+    while (store.size > maxEntries) {
+      const oldest = store.keys().next().value
+      if (oldest === undefined) break
+      store.delete(oldest)
+    }
+  }
+
+  function readEntry(hostname: string): CacheLookup {
+    const entry = store.get(hostname)
+    if (!entry) return { kind: 'cold-miss' }
+    // Re-insert to keep LRU order on each access.
+    store.delete(hostname)
+    store.set(hostname, entry)
+    const fresh = entry.expiresAt > now()
+    const data = entry.isNegative ? null : entry.data
+    return fresh ? { kind: 'fresh-hit', data } : { kind: 'stale-hit', data }
+  }
+
+  function writePositive(hostname: string, data: DomainResolution): void {
+    touch(hostname, { isNegative: false, data, expiresAt: now() + positiveTtlMs })
+  }
+
+  function writeNegative(hostname: string): void {
+    touch(hostname, { isNegative: true, expiresAt: now() + negativeTtlMs })
+  }
+
+  function reportInFlightCap(hostname: string): void {
+    if (onInFlightCapReached) {
+      onInFlightCapReached(hostname)
+      return
+    }
+    const ts = now()
+    if (ts - lastCapWarnAt >= IN_FLIGHT_CAP_WARN_INTERVAL_MS) {
+      lastCapWarnAt = ts
+      console.warn('[customDomainCache] inFlight cap reached, dropping fetch for', hostname)
+    }
+  }
+
+  async function fetchAndStore(hostname: string): Promise<DomainResolution | null> {
+    const existing = inFlight.get(hostname)
+    if (existing) return existing
+    if (inFlight.size >= maxInFlight) {
+      // Cap saturated: refuse to start another fetch. Returning null mirrors
+      // the resolver's "unknown host" path (HTTP 404) so callers degrade
+      // gracefully without poisoning the cache or pinning more promises.
+      reportInFlightCap(hostname)
+      return null
+    }
+    const promise = (async () => {
+      try {
+        const result = await resolver(hostname)
+        if (result) writePositive(hostname, result)
+        else writeNegative(hostname)
+        return result
+      } catch (err) {
+        onResolveError?.(hostname, err)
+        // Do not poison the cache on transient resolver errors — let the next
+        // request retry. Stale entries (if any) keep serving via SWR.
+        throw err
+      } finally {
+        inFlight.delete(hostname)
+      }
+    })()
+    inFlight.set(hostname, promise)
+    return promise
+  }
+
+  async function resolve(rawHostname: string): Promise<DomainResolution | null> {
+    const normalized = tryNormalizeHostname(rawHostname)
+    if (!normalized) return null
+    const lookup = readEntry(normalized)
+    if (lookup.kind === 'fresh-hit') {
+      return lookup.data
+    }
+    if (lookup.kind === 'stale-hit') {
+      // Serve stale immediately; trigger a non-blocking refresh.
+      void fetchAndStore(normalized).catch(() => {
+        /* error already reported via onResolveError */
+      })
+      return lookup.data
+    }
+    // Cold miss: synchronous fetch as fallback.
+    return fetchAndStore(normalized)
+  }
+
+  function primeFromList(entries: Iterable<DomainResolution>): void {
+    for (const entry of entries) {
+      const normalized = tryNormalizeHostname(entry.hostname)
+      if (!normalized) continue
+      writePositive(normalized, { ...entry, hostname: normalized })
+    }
+  }
+
+  function clear(): void {
+    store.clear()
+    inFlight.clear()
+    lastCapWarnAt = 0
+  }
+
+  function size(): number {
+    return store.size
+  }
+
+  function peek(hostname: string): CacheEntry | undefined {
+    const normalized = tryNormalizeHostname(hostname) ?? hostname
+    return store.get(normalized)
+  }
+
+  return {
+    resolve,
+    primeFromList,
+    clear,
+    size,
+    peek,
+    // Exposed for tests / instrumentation only.
+    _internals: { store, inFlight, writePositive, writeNegative, normalize: normalizeHostname },
+  }
+}
+
+export type CustomDomainCache = ReturnType<typeof createCustomDomainCache>
+
+export function readPositiveTtlMs(): number {
+  return readNumberEnv('DOMAIN_CACHE_TTL_SECONDS', POSITIVE_TTL_DEFAULT_SECONDS)
+}
+
+export function readNegativeTtlMs(): number {
+  return readNumberEnv(
+    'DOMAIN_NEGATIVE_CACHE_TTL_SECONDS',
+    NEGATIVE_TTL_DEFAULT_SECONDS,
+    NEGATIVE_TTL_MAX_SECONDS,
+  )
+}
+
+export function readMaxEntries(): number {
+  return readMaxEntriesEnv()
+}

package/template/src/lib/customDomainResolver.ts

@@ -0,0 +1,195 @@
+import { platformDomains } from '@open-mercato/core/modules/customer_accounts/lib/platformDomains'
+import {
+  createCustomDomainCache,
+  readMaxEntries,
+  readNegativeTtlMs,
+  readPositiveTtlMs,
+  type CustomDomainCache,
+  type DomainResolution,
+} from './customDomainCache'
+
+const DEFAULT_FETCH_TIMEOUT_MS = 5_000
+
+type ResolveResponse =
+  | { ok: true; tenantId: string; organizationId: string; orgSlug: string | null; status: 'active' }
+  | { ok: false; error: string }
+
+type ResolveAllResponse =
+  | {
+      ok: true
+      domains: Array<{
+        hostname: string
+        tenantId: string
+        organizationId: string
+        orgSlug: string | null
+        status: 'active'
+      }>
+    }
+  | { ok: false; error: string }
+
+function readInternalAppOrigin(): string | null {
+  const candidates = [
+    process.env.INTERNAL_APP_ORIGIN,
+    process.env.NEXT_INTERNAL_APP_ORIGIN,
+  ].filter((value): value is string => Boolean(value && value.trim().length > 0))
+  if (candidates.length > 0) return candidates[0]!.replace(/\/$/, '')
+  const port = process.env.PORT?.trim() || '3000'
+  return `http://127.0.0.1:${port}`
+}
+
+function readResolveSecret(): string | null {
+  const secret = process.env.DOMAIN_RESOLVE_SECRET?.trim()
+  return secret && secret.length > 0 ? secret : null
+}
+
+async function fetchWithTimeout(
+  fetchImpl: typeof fetch,
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    return await fetchImpl(url, { ...init, signal: controller.signal })
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export type CustomDomainRouterDeps = {
+  origin?: string | null
+  secret?: string | null
+  fetchTimeoutMs?: number
+  fetchImpl?: typeof fetch
+  logger?: Pick<Console, 'warn' | 'error'>
+}
+
+export type CustomDomainRouter = {
+  cache: CustomDomainCache
+  resolve(hostname: string): Promise<DomainResolution | null>
+  warmUp(): Promise<{ primed: number } | { primed: 0; error: string }>
+  reset(): void
+}
+
+export function createCustomDomainRouter(deps: CustomDomainRouterDeps = {}): CustomDomainRouter {
+  const origin = (deps.origin ?? readInternalAppOrigin())?.replace(/\/$/, '') ?? null
+  const secret = deps.secret ?? readResolveSecret()
+  const timeoutMs = deps.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS
+  const fetcher = deps.fetchImpl ?? fetch
+  const logger = deps.logger ?? console
+
+  async function singleResolve(hostname: string): Promise<DomainResolution | null> {
+    if (!origin || !secret) return null
+    const url = `${origin}/api/customer_accounts/domain-resolve?host=${encodeURIComponent(hostname)}`
+    let response: Response
+    try {
+      response = await fetchWithTimeout(
+        fetcher,
+        url,
+        {
+          method: 'GET',
+          headers: { 'X-Domain-Resolve-Secret': secret, accept: 'application/json' },
+        },
+        timeoutMs,
+      )
+    } catch (err) {
+      throw new Error(`domain-resolve fetch failed: ${(err as Error)?.message ?? 'unknown'}`)
+    }
+    if (response.status === 404) return null
+    if (!response.ok) {
+      throw new Error(`domain-resolve returned HTTP ${response.status}`)
+    }
+    const body = (await response.json()) as ResolveResponse
+    if (!body.ok) return null
+    return {
+      hostname,
+      tenantId: body.tenantId,
+      organizationId: body.organizationId,
+      orgSlug: body.orgSlug,
+      status: body.status,
+    }
+  }
+
+  const cache = createCustomDomainCache({
+    positiveTtlMs: readPositiveTtlMs(),
+    negativeTtlMs: readNegativeTtlMs(),
+    maxEntries: readMaxEntries(),
+    resolver: singleResolve,
+    onResolveError: (hostname, err) => {
+      logger.warn?.(`[custom-domain] resolve failed for ${hostname}: ${(err as Error)?.message ?? err}`)
+    },
+  })
+
+  async function warmUp(): Promise<{ primed: number } | { primed: 0; error: string }> {
+    if (!origin || !secret) {
+      return { primed: 0, error: 'INTERNAL_APP_ORIGIN or DOMAIN_RESOLVE_SECRET is not configured' }
+    }
+    const url = `${origin}/api/customer_accounts/domain-resolve/all`
+    try {
+      const response = await fetchWithTimeout(
+        fetcher,
+        url,
+        {
+          method: 'GET',
+          headers: { 'X-Domain-Resolve-Secret': secret, accept: 'application/json' },
+        },
+        timeoutMs,
+      )
+      if (!response.ok) {
+        return { primed: 0, error: `warm-up returned HTTP ${response.status}` }
+      }
+      const body = (await response.json()) as ResolveAllResponse
+      if (!body.ok) return { primed: 0, error: body.error || 'warm-up returned ok=false' }
+      cache.primeFromList(body.domains)
+      return { primed: body.domains.length }
+    } catch (err) {
+      return { primed: 0, error: (err as Error)?.message ?? 'unknown' }
+    }
+  }
+
+  return {
+    cache,
+    resolve: cache.resolve,
+    warmUp,
+    reset: cache.clear,
+  }
+}
+
+let sharedRouter: CustomDomainRouter | null = null
+let sharedWarmUpPromise: Promise<unknown> | null = null
+
+export function getSharedCustomDomainRouter(): CustomDomainRouter {
+  if (!sharedRouter) {
+    sharedRouter = createCustomDomainRouter()
+  }
+  return sharedRouter
+}
+
+export function ensureWarmUp(): Promise<unknown> {
+  if (!sharedWarmUpPromise) {
+    const router = getSharedCustomDomainRouter()
+    sharedWarmUpPromise = router.warmUp().then((result) => {
+      if ('error' in result && result.primed === 0) {
+        console.warn(`[custom-domain] warm-up skipped: ${result.error}`)
+      } else if ('primed' in result) {
+        console.info(`[custom-domain] warm-up primed ${result.primed} domain(s)`)
+      }
+      return result
+    })
+  }
+  return sharedWarmUpPromise
+}
+
+export function resetSharedRouterForTests(): void {
+  sharedRouter = null
+  sharedWarmUpPromise = null
+}
+
+export function platformDomainList(): string[] {
+  return platformDomains()
+}
+
+export function isPlatformHost(hostname: string): boolean {
+  return platformDomainList().includes(hostname.toLowerCase())
+}

package/template/src/modules/example/__integration__/TC-UMES-013.spec.ts

@@ -16,8 +16,8 @@ test.describe('TC-UMES-013: Ephemeral login page suppresses global notice bars',
     await expect(page.getByText(/this instance is provided for demo purposes only/i)).toHaveCount(0)
 
     await page.getByLabel('Email').fill(DEFAULT_CREDENTIALS.admin.email)
-    await page.getByLabel('Password').fill(DEFAULT_CREDENTIALS.admin.password)
-    await page.getByLabel('Password').press('Enter')
+    await page.getByLabel('Password', { exact: true }).fill(DEFAULT_CREDENTIALS.admin.password)
+    await page.getByLabel('Password', { exact: true }).press('Enter')
 
     await expect(page).toHaveURL(/\/backend(?:\/.*)?$/, { timeout: 20_000 })
   })