@nsxbet/admin-sdk 0.5.1 → 0.6.0

package/CHECKLIST.md

@@ -12,7 +12,7 @@
 - [ ] `vite.config.ts` — Vite build config
 - [ ] `index.html` — HTML entry point
 - [ ] `src/spa.tsx` — Shell entry (default export)
-- [ ] `src/standalone.tsx` — Dev entry (AdminShell wrapper)
+- [ ] `src/main.tsx` — Dev entry (AdminShell wrapper)
 - [ ] `src/App.tsx` — Main app component (Routes)
 - [ ] `src/index.css` — Styles with Tailwind directives
 - [ ] `tailwind.config.js` — Tailwind config
@@ -20,17 +20,36 @@
 - [ ] `tsconfig.json` — TypeScript config
 - [ ] `tsconfig.node.json` — Node TypeScript config
 - [ ] `src/globals.d.ts` — Global type declarations
+- [ ] `src/i18n/locales/en-US.json` — English (US) translations
+- [ ] `src/i18n/locales/pt-BR.json` — Portuguese (Brazil) translations
+- [ ] `src/i18n/locales/es.json` — Spanish translations
+- [ ] `src/i18n/locales/ro.json` — Romanian translations
+- [ ] `.env.staging` — Gateway environment config (staging mode)
+
+## Environment Configuration
+
+- [ ] `.env.staging` exists with `VITE_ADMIN_GATEWAY_URL` configured
+- [ ] `dev` script uses `--mode staging` to load `.env.staging` by default
+
+Expected `.env.staging`:
+
+```bash
+# Gateway URL for BFF token integration (InMemory auth)
+# Fetches real signed JWTs from the admin gateway instead of mock tokens.
+# Staging: https://admin-bff-stg.nsx.dev | Homol: https://admin-bff-homol.nsx.dev | Local: http://localhost:8080
+VITE_ADMIN_GATEWAY_URL=https://admin-bff-stg.nsx.dev
+```
 
 ## Module Manifest (`admin.module.json`)
 
 - [ ] Has `id` field (format: `@admin/<name>`)
-- [ ] Has `title` field
+- [ ] Has `title` field (localized object with en-US, pt-BR, es, ro)
 - [ ] Has `routeBase` field (starts with `/`)
-- [ ] Has `description` field (recommended)
+- [ ] Has `description` field (required, localized object with all 4 locales)
 - [ ] Has `version` field (recommended)
 - [ ] Has `category` field (recommended)
 - [ ] Has `permissions` object (recommended, values are string arrays)
-- [ ] Has `commands` array (recommended, each with `id`, `title`, `route`)
+- [ ] Has `commands` array (recommended, each with `id`, `title` (localized), `route`)
 - [ ] All command `route` values start with the module's `routeBase`
 
 Expected structure:
@@ -38,12 +57,14 @@ Expected structure:
 ```json
 {
   "id": "@admin/my-module",
-  "title": "My Module",
+  "title": { "en-US": "My Module", "pt-BR": "Meu Módulo", "es": "Mi Módulo", "ro": "Modulul Meu" },
   "routeBase": "/my-module",
-  "description": "My Module admin module",
+  "description": { "en-US": "My Module admin module", "pt-BR": "...", "es": "...", "ro": "..." },
   "version": "1.0.0",
   "category": "Tools",
-  "commands": [{ "id": "home", "title": "Home", "route": "/my-module/home" }],
+  "commands": [
+    { "id": "home", "title": { "en-US": "Home", "pt-BR": "Início", "es": "Inicio", "ro": "Acasă" }, "route": "/my-module/home" }
+  ],
   "permissions": {
     "view": ["admin.my-module.view"],
     "edit": ["admin.my-module.edit"],
@@ -52,6 +73,14 @@ Expected structure:
 }
 ```
 
+## i18n
+
+- [ ] All 4 locale files exist: `src/i18n/locales/en-US.json`, `pt-BR.json`, `es.json`, `ro.json`
+- [ ] Manifest `title` and `description` are localized objects (not plain strings)
+- [ ] Each command `title` is a localized object
+- [ ] No manual i18n registration in `main.tsx` or `spa.tsx` (Vite plugin auto-injects)
+- [ ] No `import "./i18n"` in `App.tsx`
+
 ## Dependencies (`package.json`)
 
 - [ ] `"type": "module"` is set
@@ -162,7 +191,7 @@ import { App } from "./App";
 export default App;
 ```
 
-### `src/standalone.tsx`
+### `src/main.tsx`
 
 - [ ] Uses `AdminShell` from `@nsxbet/admin-sdk`
 - [ ] Imports manifest and passes to `modules` prop
@@ -220,7 +249,7 @@ If your module was scaffolded by Lovable, the following differences apply:
 - [ ] `vite.config.ts` uses `adminModule()` spread into the existing plugins array (option B above), NOT `defineModuleConfig`
 - [ ] React plugin is `@vitejs/plugin-react-swc` (Lovable default) — this is supported
 - [ ] `index.html` entry point references `/src/main.tsx` (Lovable default) — this serves as the standalone dev entry
-- [ ] `src/main.tsx` wraps your App with `AdminShell` (same role as `src/standalone.tsx` in non-Lovable modules)
+- [ ] `src/main.tsx` wraps your App with `AdminShell` (same role as `src/main.tsx` in non-Lovable modules)
 - [ ] `src/spa.tsx` still required — `export default App` for shell mode
 - [ ] `admin.module.json` still required at project root
 - [ ] `module.manifest.json` is auto-generated at build time by `adminModule()` — do NOT manually copy `admin.module.json` to `dist/`
@@ -294,8 +323,9 @@ ReactDOM.createRoot(document.getElementById("root")!).render(
 
 - [ ] No `@supabase/supabase-js` or `supabase` imports in `src/**`
 - [ ] No `firebase` imports in `src/**`
-- [ ] No `BrowserRouter` or `MemoryRouter` in `src/**` (except `standalone.tsx`)
+- [ ] No `BrowserRouter` or `MemoryRouter` in `src/**` (except `main.tsx`)
 - [ ] No `useNavigate` imported from `@nsxbet/admin-sdk` (use `react-router-dom`)
 - [ ] No `@supabase/supabase-js` or `firebase` in `package.json` dependencies
 - [ ] No raw `fetch()` or `window.fetch()` calls — use `useFetch()` from the SDK
+- [ ] No direct date formatting (`toLocaleDateString`, `toLocaleTimeString`, `Intl.DateTimeFormat`, dayjs/moment `.format()`, date-fns `format`) — use `<Timestamp />` or `useTimestamp()` from the SDK
 - [ ] Do NOT scaffold shadcn/ui components locally — use `@nsxbet/admin-ui` which ships them pre-configured

package/README.md

@@ -41,7 +41,7 @@ npx @nsxbet/admin-cli check
 npx @nsxbet/admin-cli check --fix
 ```
 
-The CLI scaffolds all 13 required files with correct configuration, dependency versions, and SDK integration. It also validates existing modules against the canonical reference.
+The CLI scaffolds all 17 required files (including 4 locale files) with correct configuration, dependency versions, and SDK integration. It also validates existing modules against the canonical reference.
 
 > **Required for LLMs:** After creating or modifying a module, run `npx @nsxbet/admin-cli checklist --output CHECKLIST.md` and verify every item in the generated file before considering the setup complete. The checklist is a self-contained verification guide—no CLI installation needed to consume it.
 
@@ -74,7 +74,7 @@ This SDK enables you to build admin modules that integrate with the NSX Admin sh
 | File | Purpose | When used |
 |------|---------|-----------|
 | `src/spa.tsx` | Default export of App | Shell loads this via React.lazy |
-| `src/standalone.tsx` | Full app with AdminShell wrapper | Local development (`npm run dev`) |
+| `src/main.tsx` | Full app with AdminShell wrapper | Local development (`npm run dev`) |
 
 ## Complete Module Example
 
@@ -94,26 +94,53 @@ export default defineModuleConfig({
 
 ### File: `admin.module.json`
 
+Title, description, and command titles must be **localized objects** with all 4 locales (`en-US`, `pt-BR`, `es`, `ro`):
+
 ```json
 {
   "id": "@admin/my-module",
-  "title": "My Module",
-  "description": "Description of what this module does",
-  "version": "1.0.0",
+  "title": {
+    "en-US": "My Module",
+    "pt-BR": "Meu Módulo",
+    "es": "Mi Módulo",
+    "ro": "Modulul Meu"
+  },
+  "description": {
+    "en-US": "Description of what this module does",
+    "pt-BR": "Descrição do que este módulo faz",
+    "es": "Descripción de lo que hace este módulo",
+    "ro": "Descrierea a ceea ce face acest modul"
+  },
   "category": "Tools",
   "icon": "clipboard-list",
   "routeBase": "/my-module",
   "keywords": ["my", "module", "example"],
+  "navigation": {
+    "style": "stacked",
+    "sections": [
+      { "id": "general", "label": { "en-US": "General", "pt-BR": "Geral", "es": "General", "ro": "General" } }
+    ]
+  },
   "commands": [
     {
       "id": "list",
-      "title": "List Items",
+      "title": {
+        "en-US": "List Items",
+        "pt-BR": "Listar Itens",
+        "es": "Listar Elementos",
+        "ro": "Lista Elemente"
+      },
       "route": "/my-module/list",
       "icon": "file-text"
     },
     {
       "id": "new",
-      "title": "New Item",
+      "title": {
+        "en-US": "New Item",
+        "pt-BR": "Novo Item",
+        "es": "Nuevo Elemento",
+        "ro": "Element Nou"
+      },
       "route": "/my-module/new",
       "icon": "plus"
     }
@@ -142,7 +169,7 @@ import { App } from "./App";
 export default App;
 ```
 
-### File: `src/standalone.tsx`
+### File: `src/main.tsx`
 
 ```tsx
 import React from "react";
@@ -150,7 +177,6 @@ import ReactDOM from "react-dom/client";
 import {
   AdminShell,
   initI18n,
-  i18n,
   createInMemoryAuthClient,
   createMockUsersFromRoles,
 } from "@nsxbet/admin-sdk";
@@ -160,19 +186,10 @@ import manifest from "../admin.module.json";
 
 import "./index.css";
 
-// Import module translations (optional - for i18n support)
-import enUS from "./i18n/locales/en-US.json";
-import ptBR from "./i18n/locales/pt-BR.json";
-
-// Initialize i18n BEFORE shell renders
+// Initialize i18n BEFORE shell renders.
+// The Vite plugin (admin-module-i18n) auto-injects module translation registration into spa.tsx and main.tsx.
 initI18n();
 
-// Register module translations with namespace matching your module
-const NAMESPACE = "mymodule";
-i18n.addResourceBundle("en-US", NAMESPACE, enUS, true, true);
-i18n.addResourceBundle("pt-BR", NAMESPACE, ptBR, true, true);
-
-// Type assertion for JSON import
 const moduleManifest = manifest as AdminModuleManifest;
 
 // Check environment variable to toggle between mock auth and Keycloak
@@ -288,25 +305,27 @@ export function ItemList() {
 @tailwind utilities;
 ```
 
-### Directory: `src/i18n/` (optional - for translations)
+### Directory: `src/i18n/` (required for translations)
+
+All 4 locale files are **required** (`en-US`, `pt-BR`, `es`, `ro`). The Vite plugin validates this at build time.
 
 Structure:
 
 ```
 src/i18n/
   locales/
-    en-US.json    # English (required)
-    pt-BR.json    # Portuguese
+    en-US.json
+    pt-BR.json
+    es.json
+    ro.json
 ```
 
-Example `src/i18n/locales/en-US.json`:
+**No manual registration needed.** The `admin-module-i18n` Vite plugin (included in `defineModuleConfig`) auto-injects `registerModuleTranslations` into `spa.tsx` and `main.tsx` at build/serve time. Just create the locale files.
+
+Example `src/i18n/locales/en-US.json` (content translations only — nav titles live in `admin.module.json`):
 
 ```json
 {
-  "module": {
-    "title": "My Module",
-    "description": "Description of my module"
-  },
   "list": {
     "title": "All Items",
     "noItems": "No items found.",
@@ -327,13 +346,14 @@ Use translations in components:
 import { useI18n } from "@nsxbet/admin-sdk";
 
 function MyComponent() {
-  const { t } = useI18n();
+  const { t } = useI18n("my-module");
   
-  // Use with namespace prefix (set in standalone.tsx)
-  return <h1>{t("mymodule:list.title")}</h1>;
+  return <h1>{t("list.title")}</h1>;
 }
 ```
 
+The namespace is derived from your module id (e.g. `@admin/my-module` → `my-module`).
+
 ### File: `tailwind.config.js`
 
 Use `withAdminSdk` which automatically includes the UI preset and SDK/UI content paths:
@@ -423,7 +443,7 @@ export default withAdminSdk({
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="/src/standalone.tsx"></script>
+    <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>
 ```
@@ -449,6 +469,7 @@ TypeScript declarations for environment variables and platform API:
 declare global {
   interface ImportMetaEnv {
     readonly VITE_MOCK_AUTH?: string;
+    readonly VITE_ALLOWED_MODULE_ORIGINS?: string;
   }
 
   interface ImportMeta {
@@ -497,6 +518,11 @@ VITE_MOCK_AUTH=true
 
 # Set to "false" to use Keycloak authentication
 # VITE_MOCK_AUTH=false
+
+# Module URL allowlist (shell mode only). Comma-separated patterns.
+# Supports *.domain wildcard (e.g. *.nsx.dev matches modules.nsx.dev, nsx.dev).
+# In dev mode, localhost and 127.0.0.1 are always allowed.
+# VITE_ALLOWED_MODULE_ORIGINS=*.nsx.dev,*.nsx.services
 ```
 
 ## Manifest Schema (`admin.module.json`)
@@ -507,10 +533,10 @@ VITE_MOCK_AUTH=true
 | `title` | string | ✅ | Human-readable title |
 | `routeBase` | string | ✅ | Base route path (must start with `/`) |
 | `description` | string | | What the module does |
-| `version` | string | | Semantic version |
 | `category` | string | | Navigation grouping |
 | `icon` | string | | Lucide icon name in kebab-case |
 | `keywords` | string[] | | Search keywords |
+| `navigation` | object | | Navigation config (`style`, `sections`) |
 | `commands` | Command[] | | Available actions |
 | `permissions` | object | | Permission configuration |
 | `owners` | object | | Team ownership info |
@@ -524,6 +550,41 @@ VITE_MOCK_AUTH=true
 | `route` | string | ✅ | Full route path |
 | `icon` | string | | Lucide icon name |
 | `keywords` | string[] | | Search keywords |
+| `section` | string | | Section ID for stacked navigation grouping |
+
+### Stacked Navigation
+
+Modules with many commands can use stacked navigation for a dedicated sidebar panel with sectioned command grouping.
+
+**Enable stacked navigation** by adding a `navigation` field to `admin.module.json`:
+
+```json
+{
+  "navigation": {
+    "style": "stacked",
+    "sections": [
+      {
+        "id": "general",
+        "label": { "en-US": "General", "pt-BR": "Geral", "es": "General", "ro": "General" }
+      },
+      {
+        "id": "advanced",
+        "label": { "en-US": "Advanced", "pt-BR": "Avançado", "es": "Avanzado", "ro": "Avansat" }
+      }
+    ]
+  },
+  "commands": [
+    { "id": "list", "title": {...}, "route": "/mod/list", "section": "general" },
+    { "id": "settings", "title": {...}, "route": "/mod/settings", "section": "advanced" }
+  ]
+}
+```
+
+- `style`: `"stacked"` enables the dedicated panel; `"collapsible"` (default) keeps the inline expand behavior
+- `sections`: Array of section definitions with `id` and localized `label`
+- Commands reference sections via the `section` field matching a section `id`
+- Commands without a `section` appear in an implicit top-level group
+- The stacked panel is URL-driven: navigating to the module's `routeBase` activates it
 
 ### Icon Names
 
@@ -694,7 +755,10 @@ import adminPlugin from "@nsxbet/eslint-plugin-admin";
 export default [adminPlugin.configs.recommended];
 ```
 
-This enables all recommended rules including `@nsxbet/no-raw-fetch` which flags direct `fetch()`/`window.fetch()` calls that bypass authentication. Use `useFetch()` from the SDK instead.
+This enables all recommended rules:
+
+- **`@nsxbet/no-raw-fetch`** (error) — flags direct `fetch()`/`window.fetch()` calls that bypass authentication. Use `useFetch()` instead.
+- **`@nsxbet/no-raw-date-format`** (warn) — flags direct date formatting (`toLocaleDateString`, `toLocaleTimeString`, `Intl.DateTimeFormat`, dayjs/moment `.format()`, date-fns `format`) that bypasses the platform timezone preference. Use `<Timestamp />` or `useTimestamp()` instead.
 
 ## SDK Hooks
 
@@ -719,7 +783,7 @@ function MyComponent() {
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `hasPermission(perm)` | boolean | Check if user has permission |
+| `hasPermission(perm)` | boolean | Check if user has permission. Returns `false` during Keycloak initialization until auth completes. |
 | `getUser()` | User | Get current user info |
 | `getAccessToken()` | Promise\<string\> | Get JWT token |
 | `logout()` | void | Log out user |
@@ -799,6 +863,132 @@ function MyComponent() {
 }
 ```
 
+### `useTimestamp()`
+
+Timezone-aware date formatting that respects the shell's UTC/Local preference.
+
+```typescript
+import { useTimestamp, Timestamp } from "@nsxbet/admin-sdk";
+
+function MyComponent() {
+  const { mode, setMode, formatDate, timezone } = useTimestamp();
+
+  return (
+    <div>
+      <p>Timezone: {timezone} ({mode})</p>
+      <p>Formatted: {formatDate(new Date(), "datetime")}</p>
+      <Timestamp value={new Date()} format="date" />
+    </div>
+  );
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `mode` | `"utc" \| "local"` | Current timezone mode |
+| `setMode` | `(mode) => void` | Change the timezone mode |
+| `formatDate` | `(date, format?) => string` | Format a date with current mode and locale |
+| `timezone` | `string` | Resolved IANA timezone string (`"UTC"` or browser local) |
+
+**Format presets:**
+
+| Preset | Example (UTC, en-US) | Description |
+|--------|----------------------|-------------|
+| `"datetime"` (default) | "Mar 16, 2026, 2:30:05 PM UTC" | Full date and time |
+| `"date"` | "Mar 16, 2026" | Date only |
+| `"time"` | "2:30:05 PM UTC" | Time only |
+| `"relative"` | "5 minutes ago" | Relative to now (timezone-independent) |
+
+In shell mode, reads from `window.__ADMIN_PLATFORM_API__.timestamp`. In standalone mode, falls back to `localStorage` key `admin-timezone-mode` (default: `"local"`).
+
+### `<Timestamp />` Component
+
+Renders a formatted date that automatically respects the shell's timezone preference.
+
+```tsx
+import { Timestamp } from "@nsxbet/admin-sdk";
+
+// Basic usage (datetime format)
+<Timestamp value={new Date("2026-03-16T14:30:05Z")} />
+
+// Date only
+<Timestamp value={createdAt} format="date" />
+
+// Relative time
+<Timestamp value={updatedAt} format="relative" />
+
+// String input (auto-parsed)
+<Timestamp value="2026-03-16T14:30:05Z" format="time" />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `Date \| string` | required | The date to display |
+| `format` | `TimestampFormat` | `"datetime"` | Format preset |
+| `className` | `string` | | CSS class for the `<time>` element |
+
+Renders a semantic `<time>` element with a `dateTime` attribute. Hovering shows a tooltip with the date in the opposite timezone mode.
+
+**Migration guide:**
+
+| Before | After |
+|--------|-------|
+| `date.toLocaleDateString()` | `<Timestamp value={date} format="date" />` |
+| `date.toLocaleString()` | `<Timestamp value={date} />` |
+| `date.toLocaleTimeString()` | `<Timestamp value={date} format="time" />` |
+| `new Intl.DateTimeFormat(...).format(date)` | `<Timestamp value={date} />` |
+
+### `useRegistryPolling()`
+
+Detect catalog changes via lightweight version polling. Used by the shell to show an "Updates available" banner without forcing a reload.
+
+```typescript
+import { useRegistryPolling } from "@nsxbet/admin-sdk";
+
+const { hasUpdates, dismiss } = useRegistryPolling({
+  registryClient,
+  initialVersion: catalog.version,
+  interval: 60000, // poll every 60s, 0 to disable
+});
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `hasUpdates` | boolean | `true` when the server version differs from the loaded version |
+| `dismiss` | () => void | Hide the banner for the current version; re-shows on newer versions |
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `registryClient` | RegistryClient | The registry client instance |
+| `initialVersion` | string | Version string from the initial `catalog.get()` response |
+| `interval` | number \| undefined | Polling interval in ms. `0` or `undefined` disables polling |
+
+The hook integrates the Page Visibility API — polling pauses when the tab is hidden and resumes with an immediate check when the tab becomes visible again. Network errors are silently ignored.
+
+#### `catalog.version()`
+
+Both HTTP and in-memory registry clients expose a `catalog.version()` method:
+
+```typescript
+const { version, generatedAt } = await registryClient.catalog.version();
+```
+
+The HTTP client calls `GET /api/catalog/version`. The in-memory client derives a version from the local mutation state.
+
+#### Environment configuration
+
+The polling interval is resolved from `REGISTRY_POLL_INTERVAL` (milliseconds):
+
+| Source | Example |
+|--------|---------|
+| `window.__ENV__.REGISTRY_POLL_INTERVAL` | Docker runtime injection |
+| `import.meta.env.VITE_REGISTRY_POLL_INTERVAL` | Vite env var |
+| Environment default | `local`: 60s, `staging`: 5min, `production`: 15min |
+
+Set `REGISTRY_POLL_INTERVAL=0` to disable polling entirely.
+
 ### Navigation
 
 **Use `useNavigate` from `react-router-dom` directly:**
@@ -847,7 +1037,7 @@ const mockUsers = createMockUsersFromRoles({
 // Create auth client with custom users
 const authClient = createInMemoryAuthClient({ users: mockUsers });
 
-// Use in standalone.tsx
+// Use in main.tsx
 ReactDOM.createRoot(document.getElementById("root")!).render(
   <AdminShell authClient={authClient} modules={[manifest]}>
     <App />
@@ -892,6 +1082,48 @@ const authClient = createInMemoryAuthClient({ users: customUsers });
 |--------|------|---------|-------------|
 | `users` | MockUser[] | **required** | Mock users available for selection |
 | `storageKey` | string | `"@nsxbet/auth"` | localStorage key for persistence |
+| `gatewayUrl` | string \| null | `VITE_ADMIN_GATEWAY_URL` env var | Admin gateway URL for real JWT tokens |
+| `tokenTimeout` | number | `5000` | Timeout in ms for gateway token fetch |
+
+### Gateway Token Integration (BFF)
+
+When `VITE_ADMIN_GATEWAY_URL` is set (or `gatewayUrl` is passed explicitly), the InMemory auth client fetches real signed JWTs from the admin gateway instead of returning mock token strings. This enables end-to-end testing against backends that validate tokens.
+
+**How it works:**
+
+1. Developer clicks a user card in the UserSelector
+2. The client calls `GET {gatewayUrl}/auth/token?sub=...&email=...&roles=...&scopes=...`
+3. The gateway returns a signed JWT which is cached in memory
+4. `getAccessToken()` returns the cached JWT for all subsequent API calls
+5. When the token nears expiry (within 60s), a background refresh is triggered
+
+**Gateway URL resolution order:**
+
+1. Explicit `gatewayUrl` option passed to `createInMemoryAuthClient()`
+2. `import.meta.env.VITE_ADMIN_GATEWAY_URL` environment variable
+3. If neither is set, BFF integration is disabled (mock tokens, current behavior)
+
+**Error handling:**
+
+The UserSelector shows loading, error, and timeout states during the token fetch. If the gateway is unreachable, the developer can:
+- **Retry** the token fetch
+- **Continue with mock token** to fall back to legacy behavior
+- **Go back** to the user selection list
+
+```bash
+# Add to your .env file to enable gateway token integration
+VITE_ADMIN_GATEWAY_URL=https://admin-bff-stg.nsx.dev
+```
+
+## Module URL Allowlist (Shell Mode)
+
+When the shell loads modules dynamically from URLs, it validates each URL against `VITE_ALLOWED_MODULE_ORIGINS` before `import()` or `loadScript()`.
+
+**Format:** Comma-separated patterns supporting `*.domain` wildcard (e.g. `*.nsx.dev` matches `modules.nsx.dev`, `cdn.nsx.dev`, and apex `nsx.dev`).
+
+**Dev mode:** `localhost` and `127.0.0.1` are always allowed regardless of the allowlist, so local dev servers work without configuration.
+
+**Production:** Set `VITE_ALLOWED_MODULE_ORIGINS` in your build environment. If unset or empty, all module loads fail with a clear error.
 
 ## Keycloak Configuration (Production Auth)
 
@@ -929,6 +1161,10 @@ Or pass the `keycloak` prop directly without `authClient`:
 </AdminShell>
 ```
 
+### Mock Auth Production Guard
+
+In production builds, AdminShell requires authentication configuration. If you omit both `authClient` and `keycloak` props, the shell throws an error unless you explicitly set `VITE_MOCK_AUTH=true`. When mock auth is used in production with `VITE_MOCK_AUTH=true`, a console warning is logged. Always use Keycloak (or another real auth client) for production deployments.
+
 ### Keycloak Configuration Options
 
 | Option | Type | Description |
@@ -1026,6 +1262,29 @@ const fetch = useFetch();
 const data = await fetch("/api/internal-endpoint");
 ```
 
+### ❌ DO NOT format dates directly
+
+```typescript
+// WRONG - bypasses platform timezone preference
+date.toLocaleDateString(); // ❌
+date.toLocaleTimeString(); // ❌
+new Intl.DateTimeFormat("en-US").format(date); // ❌
+dayjs(date).format("YYYY-MM-DD"); // ❌
+import { format } from "date-fns"; format(date, "PP"); // ❌
+```
+
+```tsx
+// CORRECT - use <Timestamp /> or useTimestamp()
+import { Timestamp, useTimestamp } from "@nsxbet/admin-sdk";
+
+<Timestamp value={date} format="date" /> // ✅
+
+const { formatDate } = useTimestamp();
+formatDate(date, "datetime"); // ✅
+```
+
+Direct formatting bypasses the platform timezone preference, causing inconsistent timestamp display across modules. The `@nsxbet/no-raw-date-format` ESLint rule enforces this.
+
 ### ❌ DO NOT import useNavigate from SDK
 
 ```typescript
@@ -1091,6 +1350,43 @@ bun run build
 bun run preview
 ```
 
+## Error Boundary with Module Ownership
+
+When a module crashes at runtime, the error boundary displays ownership information to help with incident triage. The `DynamicModule` component accepts an optional `moduleInfo` prop that provides module metadata to the error boundary.
+
+```tsx
+<DynamicModule
+  baseUrl="http://localhost:5001"
+  moduleInfo={{
+    id: "@admin/payments",
+    title: { "en-US": "Payments", "pt-BR": "Pagamentos", "es": "Pagos", "ro": "Plăți" },
+    owners: { team: "Payments", supportChannel: "#payments-support" },
+  }}
+/>
+```
+
+When a module error occurs, the error boundary will:
+- Display the module name (localized for the current locale)
+- Show the owner team and support channel (if provided)
+- Render the support channel as a clickable link if it starts with `http`/`https`
+- Provide both "Try Again" (re-render) and "Reload Page" (full reload) buttons
+- Report the error to telemetry with module attribution (`moduleId`, `ownerTeam`, `errorType`)
+- Capture unhandled promise rejections while the module is mounted and report them via telemetry
+
+If `owners.team` is empty, the ownership section is omitted and the error boundary shows a standard error UI.
+
+## Platform API — Timestamp Namespace
+
+The shell exposes `window.__ADMIN_PLATFORM_API__.timestamp` for timezone preference management:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `mode` | `"utc" \| "local"` | Current timezone mode |
+| `setMode(mode)` | `(TimezoneMode) => void` | Change the timezone mode |
+| `onModeChange(cb)` | `(callback) => () => void` | Subscribe to changes; returns unsubscribe |
+
+> **Note:** Modules should use `useTimestamp()` or `<Timestamp />` rather than accessing the Platform API directly.
+
 ## Types
 
 ```typescript
@@ -1100,6 +1396,11 @@ import type {
   PlatformAPI,
   User,
   Breadcrumb,
+  ModuleInfo,
+  ErrorBoundaryProps,
+  TimezoneMode,
+  TimestampFormat,
+  UseTimestampResult,
 } from "@nsxbet/admin-sdk";
 ```
 

package/dist/auth/client/gateway-token.d.ts

@@ -0,0 +1,19 @@
+import type { MockUser } from './interface';
+export declare class GatewayTimeoutError extends Error {
+    readonly gatewayUrl: string;
+    readonly timeoutMs: number;
+    constructor(gatewayUrl: string, timeoutMs: number);
+}
+export declare class GatewayFetchError extends Error {
+    readonly gatewayUrl: string;
+    readonly statusCode?: number | undefined;
+    readonly originalError?: unknown | undefined;
+    constructor(gatewayUrl: string, statusCode?: number | undefined, originalError?: unknown | undefined);
+}
+export interface GatewayTokenResult {
+    token: string;
+    expiresAt: number;
+}
+export declare function fetchGatewayToken(gatewayUrl: string, user: MockUser, options?: {
+    timeoutMs?: number;
+}): Promise<GatewayTokenResult>;