nucleus-core-ts 0.9.42 → 0.9.43

package/dist/src/Client/Proxy/httpProxy.js

@@ -230,6 +230,11 @@ export function createHttpProxyHandler(config) {
             const refreshCookieName = refreshConfig?.refreshCookieName ?? 'refresh_token';
             const refreshToken = cookies[refreshCookieName];
             let refreshSetCookies = [];
+            // --- Diagnostic logging for SSE/streaming paths ---
+            const isStreamingPath = path.includes('/predict/stream') || path.includes('/stream/resume');
+            if (isStreamingPath) {
+                logger.info(`[SSE:proxy] ${req.method} ${path} | accessToken: ${accessToken ? 'present' : 'MISSING'} | refreshToken: ${refreshToken ? 'present' : 'MISSING'} | refreshEnabled: ${refreshEnabled}`);
+            }
             // --- PROACTIVE REFRESH: no access_token but refresh_token exists ---
             if (refreshEnabled && !accessToken && refreshToken && target.injectTokenFromCookie) {
                 logger.info(`[TokenRefresh] No access_token, attempting proactive refresh for ${path}`);
@@ -334,6 +339,9 @@ export function createHttpProxyHandler(config) {
             } catch (error) {
                 const duration = performance.now() - startTime;
                 const err = error instanceof Error ? error : new Error(String(error));
+                if (isStreamingPath) {
+                    logger.error(`[SSE:proxy] FETCH ERROR for ${path} after ${duration.toFixed(0)}ms: ${err.name} - ${err.message}`);
+                }
                 if (err.name === 'AbortError') {
                     logger.error(`Timeout after ${duration.toFixed(0)}ms: ${path}`);
                     config.onError?.(new Error('Request timeout'), path, 504);

package/infra/scripts/generate-project.ts

@@ -101,6 +101,19 @@ function replaceTemplateVars(content: string, vars: TemplateVars): string {
   return result
 }
 
+const BINARY_EXTENSIONS = new Set([
+  '.ico', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.bmp',
+  '.woff', '.woff2', '.ttf', '.eot', '.otf',
+  '.mp3', '.mp4', '.wav', '.ogg', '.webm',
+  '.zip', '.gz', '.tar', '.pdf',
+  '.lock',
+])
+
+function isBinaryFile(filePath: string): boolean {
+  const ext = filePath.slice(filePath.lastIndexOf('.')).toLowerCase()
+  return BINARY_EXTENSIONS.has(ext)
+}
+
 function copyTemplateDir(srcDir: string, destDir: string, vars: TemplateVars, skipPatterns: string[] = []) {
   if (!existsSync(srcDir)) return
 
@@ -115,6 +128,8 @@ function copyTemplateDir(srcDir: string, destDir: string, vars: TemplateVars, sk
 
     if (stat.isDirectory()) {
       copyTemplateDir(srcPath, destPath, vars, skipPatterns)
+    } else if (isBinaryFile(srcPath)) {
+      writeFileSync(destPath, readFileSync(srcPath))
     } else {
       const content = readFileSync(srcPath, 'utf-8')
       const processed = replaceTemplateVars(content, vars)
@@ -224,19 +239,24 @@ function generateBackend(
   writeFileSync(join(srcDir, 'config.json'), JSON.stringify(config, null, 2))
   logSuccess('src/config.json written')
 
-  // Write .env for local dev
-  const envContent = [
+  // Write .env for local dev — read token secret env var names from config
+  const auth = config.authentication as Record<string, Record<string, string>> | undefined
+  const accessSecretName = auth?.accessToken?.secret || 'ACCESS_TOKEN_SECRET'
+  const refreshSecretName = auth?.refreshToken?.secret || 'REFRESH_TOKEN_SECRET'
+  const sessionSecretName = auth?.sessionToken?.secret || 'SESSION_TOKEN_SECRET'
+
+  const envLines = [
     `DATABASE_URL=postgresql://postgres:postgres@localhost:5432/${projectName}`,
-    `JWT_SECRET=${generateSecret()}`,
-    `JWT_REFRESH_SECRET=${generateSecret()}`,
-    `JWT_SESSION_SECRET=${generateSecret()}`,
+    `${accessSecretName}=${generateSecret()}`,
+    `${refreshSecretName}=${generateSecret()}`,
+    `${sessionSecretName}=${generateSecret()}`,
     `REDIS_HOST=localhost`,
     `REDIS_PORT=6379`,
     `PORT=9000`,
     `FRONTEND_URL=http://localhost:3000`,
     `USE_DAPR=false`,
-  ].join('\n')
-  writeFileSync(join(beDir, '.env'), envContent + '\n')
+  ]
+  writeFileSync(join(beDir, '.env'), envLines.join('\n') + '\n')
   logSuccess('.env written (local dev)')
 
   // K8s files are already copied from template with vars replaced
@@ -280,15 +300,16 @@ function generateFrontend(
   logSuccess('lib/api/config.ts written (from config.json)')
 
   // Write .env for production build (non-secret build-time vars)
+  // NOTE: PORT and HOSTNAME are NOT set here — they come from K8s configmap in prod.
+  // In local dev, server.ts defaults to port 4000 and Next.js to 3000 — no conflict.
   const envContent = [
     `# Production build environment variables`,
     `# These are injected via Docker build args in the pipeline`,
     `# DO NOT put secrets here — use K8s Secrets`,
+    `# PORT and HOSTNAME are set by K8s configmap, not here`,
     `API_BASE_URL=http://${apiProjectName}-service.${vars.NAMESPACE}.svc.cluster.local:3000`,
     `BACKEND_API_URL=http://${apiProjectName}-service.${vars.NAMESPACE}.svc.cluster.local:3000`,
     `ALLOWED_ORIGINS=${vars.DOMAIN}`,
-    `PORT=3000`,
-    `HOSTNAME=0.0.0.0`,
   ].join('\n')
   writeFileSync(join(feDir, '.env'), envContent + '\n')
   logSuccess('.env written (build/prod)')
@@ -446,6 +467,62 @@ async function main() {
     generateFrontend(outputDir, feProjectName, apiProjectName, config, feVars, feTemplateDir)
   }
 
+  // ── Post-scaffold automation ──
+  logStep('Installing dependencies & setting up...')
+
+  const beDir = join(outputDir, apiProjectName)
+
+  // Backend: bun install
+  logStep(`[API] bun install`)
+  const installBe = Bun.spawnSync(['bun', 'install'], { cwd: beDir, stdout: 'pipe', stderr: 'pipe' })
+  if (installBe.exitCode === 0) {
+    logSuccess('bun install completed')
+  } else {
+    logError(`bun install failed: ${installBe.stderr.toString().slice(0, 200)}`)
+    process.exit(1)
+  }
+
+  // Backend: create database (best-effort — skip if createdb not found or DB already exists)
+  logStep(`[API] Creating database: ${apiProjectName}`)
+  const createDb = Bun.spawnSync(['createdb', apiProjectName], { cwd: beDir, stdout: 'pipe', stderr: 'pipe' })
+  if (createDb.exitCode === 0) {
+    logSuccess(`Database "${apiProjectName}" created`)
+  } else {
+    const errMsg = createDb.stderr.toString()
+    if (errMsg.includes('already exists')) {
+      logWarn(`Database "${apiProjectName}" already exists — using existing`)
+    } else if (errMsg.includes('not found') || errMsg.includes('No such file')) {
+      logWarn('createdb not found — please create the database manually')
+    } else {
+      logWarn(`createdb: ${errMsg.trim().slice(0, 150)}`)
+    }
+  }
+
+  // Backend: nucleus-generate (schema + relations)
+  logStep(`[API] Generating Drizzle schema`)
+  const generate = Bun.spawnSync(['bunx', 'nucleus-generate', 'src/config.json', 'src/drizzle'], { cwd: beDir, stdout: 'pipe', stderr: 'pipe' })
+  if (generate.exitCode === 0) {
+    logSuccess('Drizzle schema generated')
+    const genOut = generate.stdout.toString()
+    if (genOut) log(`  ${DIM}${genOut.trim()}${RESET}`)
+  } else {
+    logError(`nucleus-generate failed: ${generate.stderr.toString().slice(0, 200)}`)
+    process.exit(1)
+  }
+
+  // Frontend: bun install
+  if (feCount > 0) {
+    const feDir = join(outputDir, feProjectName)
+    logStep(`[FE] bun install`)
+    const installFe = Bun.spawnSync(['bun', 'install'], { cwd: feDir, stdout: 'pipe', stderr: 'pipe' })
+    if (installFe.exitCode === 0) {
+      logSuccess('bun install completed')
+    } else {
+      logError(`bun install failed: ${installFe.stderr.toString().slice(0, 200)}`)
+      process.exit(1)
+    }
+  }
+
   // ── Summary ──
   log(`\n${GREEN}${BOLD}╔══════════════════════════════════════════╗${RESET}`)
   log(`${GREEN}${BOLD}║   Project scaffolding complete!          ║${RESET}`)
@@ -454,48 +531,27 @@ async function main() {
   log(`\n  ${BOLD}Generated structure:${RESET}`)
   log(`  ${outputDir}/`)
   log(`  ├── ${apiProjectName}/`)
-  log(`  │   ├── src/`)
-  log(`  │   │   ├── config.json`)
-  log(`  │   │   └── index.ts`)
-  log(`  │   ├── k8s/`)
-  log(`  │   │   ├── Dockerfile`)
-  log(`  │   │   ├── configmap.yaml`)
-  log(`  │   │   ├── deployment.yaml`)
-  log(`  │   │   ├── service.yaml`)
-  log(`  │   │   └── pvc.yaml`)
+  log(`  │   ├── src/config.json + drizzle/schema.ts`)
+  log(`  │   ├── k8s/ (Dockerfile, configmap, deployment, service, pvc)`)
   log(`  │   ├── azure-pipelines.yml`)
-  log(`  │   ├── .env`)
-  log(`  │   ├── .dockerignore`)
-  log(`  │   └── package.json`)
-
+  log(`  │   ├── .env + .dockerignore`)
+  log(`  │   └── node_modules/ ${DIM}(installed)${RESET}`)
   if (feCount > 0) {
     log(`  └── ${feProjectName}/`)
-    log(`      ├── app/`)
-    log(`      ├── lib/api/config.ts`)
-    log(`      ├── k8s/`)
-    log(`      │   ├── Dockerfile`)
-    log(`      │   ├── configmap.yaml`)
-    log(`      │   ├── deployment.yaml`)
-    log(`      │   ├── service.yaml`)
-    log(`      │   └── ingress.yaml`)
+    log(`      ├── app/ + lib/api/config.ts`)
+    log(`      ├── k8s/ (Dockerfile, configmap, deployment, service, ingress)`)
     log(`      ├── azure-pipelines.yml`)
-    log(`      ├── .env`)
-    log(`      ├── .env.local`)
-    log(`      ├── .dockerignore`)
-    log(`      └── package.json`)
+    log(`      ├── .env + .env.local + .dockerignore`)
+    log(`      └── node_modules/ ${DIM}(installed)${RESET}`)
   }
 
-  log(`\n  ${BOLD}Next steps:${RESET}`)
-  log(`  1. ${CYAN}cd ${join(outputDir, apiProjectName)} && bun install${RESET}`)
-  log(`  2. ${CYAN}bunx nucleus-generate src/config.json src/drizzle${RESET}`)
-  log(`  3. Start a PostgreSQL + Redis instance`)
-  log(`  4. ${CYAN}bun run dev${RESET}`)
+  log(`\n  ${BOLD}Ready to run:${RESET}`)
+  log(`  ${CYAN}cd ${beDir} && bun run dev${RESET}`)
   if (feCount > 0) {
-    log(`  5. ${CYAN}cd ${join(outputDir, feProjectName)} && bun install${RESET}`)
-    log(`  6. ${CYAN}bun run dev${RESET}`)
+    log(`  ${CYAN}cd ${join(outputDir, feProjectName)} && bun run dev${RESET}`)
   }
-  log(`\n  ${DIM}For deployment, configure Azure DevOps pipeline variables`)
-  log(`  and push to trigger the CI/CD pipeline.${RESET}\n`)
+  log(`\n  ${DIM}Prerequisites: PostgreSQL + Redis running locally.`)
+  log(`  For deployment, configure Azure DevOps pipeline variables.${RESET}\n`)
 }
 
 main().catch((err) => {

package/infra/templates/backend/src/index.ts

@@ -5,7 +5,7 @@ async function main() {
   new Elysia()
     .use(
       await NucleusElysiaPlugin({
-        options: './config.json',
+        options: './src/config.json',
         schema: './src/drizzle/schema.ts',
         relations: './src/drizzle/relations.ts',
         swagger: {

package/infra/templates/frontend/app/globals.css

@@ -2,7 +2,7 @@
 
 @custom-variant dark (&:where(.dark, .dark *));
 
-@source "../node_modules/nucleus-core/dist/fe/**/*.js";
+@source "../node_modules/nucleus-core-ts/dist/fe/**/*.js";
 
 :root {
   --background: #ffffff;

package/infra/templates/frontend/app/ui-docs/page.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import dynamic from "next/dynamic";
+import { Suspense, useEffect, useState } from "react";
+import type { ComponentEntry } from "nucleus-core-ts/fe";
+
+const DesignSystemPage = dynamic(
+	() => import("nucleus-core-ts/fe").then((mod) => mod.DesignSystemPage),
+	{ ssr: false },
+);
+
+const createDefaultRegistryImport = () =>
+	import("nucleus-core-ts/fe").then((mod) => mod.createDefaultRegistry);
+
+function UIDocsContent() {
+	const [registry, setRegistry] = useState<ComponentEntry[]>([]);
+
+	useEffect(() => {
+		createDefaultRegistryImport().then((fn) => {
+			setRegistry(fn());
+		});
+	}, []);
+
+	if (registry.length === 0) {
+		return (
+			<section className="min-h-screen flex items-center justify-center bg-zinc-50 dark:bg-zinc-950">
+				<section className="animate-pulse flex flex-col items-center gap-3">
+					<span className="w-10 h-10 rounded-full border-2 border-zinc-300 dark:border-zinc-700 border-t-zinc-900 dark:border-t-white animate-spin" />
+					<span className="text-sm text-zinc-400 dark:text-zinc-500">
+						Loading components...
+					</span>
+				</section>
+			</section>
+		);
+	}
+
+	return <DesignSystemPage registry={registry} />;
+}
+
+export default function UIDocsPage() {
+	return (
+		<Suspense
+			fallback={
+				<section className="min-h-screen flex items-center justify-center">
+					<span className="animate-spin rounded-full h-8 w-8 border-b-2 border-zinc-900 dark:border-white" />
+				</section>
+			}
+		>
+			<UIDocsContent />
+		</Suspense>
+	);
+}

package/infra/templates/frontend/code-and-design-principles.md

@@ -0,0 +1,438 @@
+# Nucleus Front-End Code & Design Principles
+
+> **IMPORTANT**: These principles are **absolute, non-negotiable, and mandatory** for all front-end development. Zero exceptions. Any deviation must be corrected immediately — even if it requires extensive refactoring.
+
+---
+
+## 1. Build & Tooling
+
+| Requirement | Specification |
+|-------------|---------------|
+| **Package Manager** | Bun exclusively |
+| **Bundler** | Turbopack only (`next dev --turbopack`) |
+| **Forbidden** | Webpack config, custom package resolution entries |
+
+---
+
+## 2. Responsive Design — Mobile-First, 6 Breakpoints
+
+### 2.1 The Rule
+
+**Every single component, every single page, every single layout MUST be built mobile-first with all 6 breakpoints.** This is not a suggestion — it is a hard requirement. No component ships without responsive coverage.
+
+### 2.2 Breakpoint System
+
+| Breakpoint | Name | Tailwind | Target |
+|-----------|------|----------|--------|
+| **0px** | `base` | (default) | Small phones (iPhone SE) |
+| **480px** | `xs` | `xs:` | Large phones (iPhone 14 Pro Max) |
+| **640px** | `sm` | `sm:` | Small tablets (iPad Mini portrait) |
+| **768px** | `md` | `md:` | Large tablets (iPad Pro portrait) |
+| **1024px** | `lg` | `lg:` | Small desktop / tablet landscape |
+| **1280px** | `xl` | `xl:` | Large desktop |
+
+### 2.3 How to Write Mobile-First CSS
+
+```tsx
+// ✅ CORRECT — mobile-first: base styles are for phones, then override upward
+<section className="
+  flex flex-col gap-2 p-4 text-sm
+  xs:gap-3
+  sm:flex-row sm:gap-4 sm:p-6
+  md:p-8 md:text-base
+  lg:max-w-5xl lg:mx-auto lg:gap-6
+  xl:max-w-7xl xl:p-12
+">
+
+// ❌ WRONG — desktop-first: writing for desktop then trying to "fix" mobile
+<section className="max-w-7xl mx-auto p-12 flex gap-6 md:flex-col md:p-4 sm:p-2">
+```
+
+### 2.4 Enforcement Checklist
+
+Before ANY component is considered complete:
+
+- [ ] Renders correctly on 320px (small phone)
+- [ ] Renders correctly on 480px (large phone)
+- [ ] Renders correctly on 640px (small tablet)
+- [ ] Renders correctly on 768px (large tablet)
+- [ ] Renders correctly on 1024px (small desktop)
+- [ ] Renders correctly on 1280px (large desktop)
+
+**If even ONE breakpoint is broken, the component is not done.**
+
+---
+
+## 3. Theme System — Light-First, Dark Support
+
+### 3.1 The Rule
+
+**Light theme is the default. Dark theme is the override. Every visible element MUST have both light AND dark styles.** No element may appear unstyled, invisible, or unreadable in either theme.
+
+### 3.2 How to Write Light-First Theme Styles
+
+```tsx
+// ✅ CORRECT — light-first: base is light, dark: overrides
+<section className="
+  bg-white text-gray-900 border-gray-200
+  dark:bg-gray-900 dark:text-gray-100 dark:border-gray-800
+">
+
+// ❌ WRONG — dark-only: no light mode styles
+<section className="dark:bg-gray-900 dark:text-white">
+
+// ❌ WRONG — missing dark variant
+<section className="bg-white text-gray-900 border-gray-200">
+```
+
+### 3.3 Theme Enforcement Rules
+
+| Rule | Detail |
+|------|--------|
+| **Every `bg-*`** | Must have a `dark:bg-*` counterpart |
+| **Every `text-*`** | Must have a `dark:text-*` counterpart |
+| **Every `border-*`** | Must have a `dark:border-*` counterpart |
+| **Every `shadow-*`** | Must have a `dark:shadow-*` or be theme-neutral |
+| **Every `placeholder-*`** | Must have a `dark:placeholder-*` counterpart |
+| **Hover/focus states** | Must also have `dark:hover:*` / `dark:focus:*` variants |
+
+### 3.4 Dark Mode Configuration
+
+The project uses Tailwind CSS v4 class-based dark mode:
+```css
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+Toggle dark mode by adding/removing `.dark` class on a parent element.
+
+---
+
+## 4. Code Splitting — No Monoliths
+
+### 4.1 The Rule
+
+**No file exceeds 200 lines. No component does more than one thing. Split aggressively.** A monolithic 500-line component is a failure — it must be decomposed into focused, reusable units.
+
+### 4.2 Mandatory Split Structure
+
+Every scope (page, feature, domain) uses these subfolders:
+
+| Folder | Purpose |
+|--------|---------|
+| `_components/` | UI components for that scope |
+| `_utils/` | Helper utilities |
+| `_store/` | State stores (h-state) |
+| `_hooks/` | Custom hooks |
+
+### 4.3 Scope Placement Rules
+
+| Usage | Placement |
+|-------|-----------|
+| Used in 1 page only | Inside that page's `_components/` |
+| Used across pages | Elevate to `app/_components/` |
+| Used everywhere | Use nucleus-core-ts component or create in `app/_components/global/` |
+
+### 4.4 Component File Structure
+
+```
+_components/
+  BandMemberCard/
+    index.tsx          # Component implementation
+    types.ts           # Type definitions
+    utils.ts           # Helper functions
+    BandMemberSkeleton.tsx  # Loading skeleton
+  ShowCard/
+    index.tsx
+    types.ts
+```
+
+### 4.5 Index File Rules
+
+- **Barrel files** (`_components/index.ts`): Re-export only. No logic.
+- **Module files** (`BandMemberCard/index.tsx`): Contains the actual implementation.
+- **Named exports only.** Default exports are forbidden.
+
+---
+
+## 5. Nucleus Design System Components
+
+### 5.1 Available UI Components
+
+The `nucleus-core-ts/fe` package provides ready-to-use, themeable, responsive UI **components**. Use these instead of building from scratch:
+
+| Component | Import | Purpose |
+|-----------|--------|---------|
+| **Button** | `Button` | Versatile button with variants, sizes, shapes, loading states |
+| **NucleusTextInput** | `NucleusTextInput` | Text input with label, validation, icons |
+| **Checkbox** | `Checkbox` | Checkbox and switch toggle with colors |
+| **SelectBox** | `SelectBox` | Dropdown select with search, clear, portal-based |
+| **SearchBox** | `SearchBox` | Search input with debounce, dropdown results |
+| **DatePicker** | `DatePicker` | Calendar date picker with range mode, locale |
+| **RangePicker** | `RangePicker` | Numeric range slider with ticks, tooltips |
+| **DataTable** | `DataTable` | Feature-rich table: sorting, resize, selection, infinite scroll, inline edit |
+| **Tooltip** | `Tooltip` | Tooltip with placements, variants, GSAP animation |
+| **Captcha** | `Captcha` | Puzzle captcha with expiration |
+| **NotificationCenter** | `NotificationCenter` | In-app notification bell + panel |
+| **FormBuilder** | `FormBuilder` | Dynamic form generation from schema |
+
+All components import from:
+```ts
+import { Button, DataTable, SelectBox, ... } from 'nucleus-core-ts/fe'
+```
+
+### 5.2 Design System Explorer
+
+The project includes a `/ui-docs` page that renders the **DesignSystem** explorer — a live, interactive documentation of all available components with prop controls, examples, and theme toggling (light/dark). Use it as reference during development.
+
+Visit `http://localhost:3000/ui-docs` to explore.
+
+### 5.3 When to Use nucleus-core Components vs Custom
+
+| Situation | Action |
+|-----------|--------|
+| Need a button, input, table, select, etc. | **Use nucleus-core component** |
+| Need a complex domain-specific component (e.g., ShowCalendar) | **Build custom**, but compose from nucleus-core atoms (Button, DataTable, etc.) |
+| Need a variant/style not covered by nucleus-core | **Extend via theme props** or `className` override — don't recreate |
+
+---
+
+## 6. API Integration
+
+### 6.1 The Pattern
+
+All API calls go through the type-safe `useApiActions` hook:
+
+```ts
+import { useApiActions } from '@/lib/api/hook'
+```
+
+### 6.2 Type Safety — Absolute Rules
+
+| Rule | Detail |
+|------|--------|
+| **Zero `as` casts** | All types flow from endpoint definitions |
+| **Zero manual type redefinition** | Never redefine types that nucleus-core provides |
+| **Zero `Record<string, unknown>`** | Extract the real type from the endpoint |
+| **Zero wrapper hooks** | Don't wrap `useApiActions` with extra `useState` |
+
+### 6.3 Entity Type Extraction
+
+```ts
+import type { AllEndpoints } from '@/lib/api/endpoints'
+
+// ✅ CORRECT — type flows from endpoint definition
+type BandMember = NonNullable<AllEndpoints['GET_BAND_MEMBERS']['_success']['data']>['items'][number]
+
+// ❌ WRONG — manual type
+type BandMember = { id: string; firstName: string; ... }
+```
+
+### 6.4 Action State = Single Source of Truth
+
+```tsx
+const actions = useApiActions()
+
+// ✅ CORRECT
+const isLoading = actions.GET_BAND_MEMBERS.state.isPending
+const members = actions.GET_BAND_MEMBERS.state.data?.data?.items ?? []
+const meta = actions.GET_BAND_MEMBERS.state.data?.data?.meta
+
+// ❌ WRONG — duplicating into separate state
+const [members, setMembers] = useState([])
+```
+
+### 6.5 Fetch Pattern
+
+```tsx
+const actions = useApiActions()
+
+const fetchMembers = useEffectEvent(() => {
+  actions.GET_BAND_MEMBERS.start({
+    payload: { page: 1, limit: 20, sort: [{ field: 'displayOrder', direction: 'asc' }] },
+    onAfterHandle: (data) => { /* data is fully typed */ },
+    onErrorHandle: (error, code) => { /* handle errors */ },
+  })
+})
+
+useEffect(() => { fetchMembers() }, [])
+```
+
+### 6.6 List Response Structure
+
+All list endpoints return:
+```ts
+{
+  data: {
+    items: T[]
+    meta: { page, limit, totalItems, totalPages, hasNextPage, hasPrevPage, ... }
+  }
+  success: boolean
+}
+```
+
+Access: `actions.GET_X.state.data?.data?.items` and `.data?.data?.meta`
+
+### 6.7 File Upload & CDN
+
+```tsx
+// Upload
+const formData = new FormData()
+formData.append('files', selectedFile)
+formData.append('data', JSON.stringify({ original_name: file.name, path: 'uploads', size: file.size, mime_type: file.type, extension: file.name.split('.').pop(), type: 'image' }))
+actions.ADD_FILE.start({ payload: formData })
+
+// Display (via CDN rewrite in next.config.ts)
+<img src={`/cdn/${file.id}`} alt={file.originalName} />
+```
+
+### 6.8 Prohibited Patterns
+
+| Pattern | Why Prohibited | Correct Alternative |
+|---------|---------------|-------------------|
+| `as` type casts on API data | Breaks type safety | Let types flow from endpoints |
+| `useState` for API data | Duplicates state | Use `actions.X.state` |
+| `try/catch/await` API calls | Against callback pattern | Use `onAfterHandle` / `onErrorHandle` |
+| Manual entity types | Diverges from schema | Extract from `AllEndpoints` |
+| `Record<string, unknown>` | No intellisense | Use endpoint-derived types |
+
+---
+
+## 7. React Patterns
+
+### 7.1 Strictly Prohibited
+
+- `useCallback`
+- `useMemo`
+- `memo`
+- `as` type assertions
+- `any`, `unknown` types
+
+### 7.2 Effect Management
+
+- All functions inside `useEffect` **must use `useEffectEvent`**
+
+### 7.3 State Management
+
+- **h-state** for all shared state management
+- **Prop drilling is strictly prohibited**
+
+### 7.4 Animation
+
+- **GSAP** is the required animation library
+- Use `@gsap/react` for React integration
+- Animations should be sophisticated and butter-smooth
+
+---
+
+## 8. Loading States & Skeletons
+
+### 8.1 The Rule
+
+**Every page and every data-driven component MUST have a skeleton loader.** Loading states are not optional — they are part of the component contract.
+
+### 8.2 Implementation
+
+```tsx
+export function BandMemberList() {
+  const actions = useApiActions()
+  const isLoading = actions.GET_BAND_MEMBERS.state.isPending
+  const members = actions.GET_BAND_MEMBERS.state.data?.data?.items ?? []
+
+  if (isLoading) return <BandMemberListSkeleton count={4} />
+
+  return (
+    <section className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+      {members.map(m => <BandMemberCard key={m.id} member={m} />)}
+    </section>
+  )
+}
+```
+
+### 8.3 Skeleton Rules
+
+- Must mirror exact layout of loaded content
+- Must respect light/dark theme
+- Must follow same responsive breakpoints
+- GSAP shimmer animation preferred
+
+---
+
+## 9. Design Philosophy
+
+### 9.1 Bold Direction
+
+Before coding, establish a clear aesthetic direction. Be intentional — not generic.
+
+### 9.2 Typography
+
+- **Forbidden**: Generic fonts (Arial, Inter, Roboto, system fonts)
+- **Required**: Distinctive, characterful font choices
+
+### 9.3 Color & Theme
+
+- Cohesive palette with intentional accents
+- CSS variables for consistency
+- **Forbidden**: Clichéd color schemes, AI-slop aesthetics
+
+### 9.4 Motion
+
+- GSAP for all animations
+- Orchestrated page loads with staggered reveals
+- Scroll-triggered animations
+- One well-crafted animation > scattered micro-interactions
+
+---
+
+## 10. snake_case vs camelCase Convention
+
+| Layer | Format | Example |
+|-------|--------|---------|
+| Config `table_name` | snake_case | `band_members` |
+| Backend route path | camelCase | `/bandMembers` |
+| Frontend endpoint key | UPPER_SNAKE_CASE | `GET_BAND_MEMBERS` |
+| Query param fields | camelCase | `displayOrder` |
+
+**Never** hardcode snake_case in API paths. Use `generateAllEndpoints()` — it handles casing automatically.
+
+---
+
+## 11. Compliance Checklist
+
+Before submitting any code:
+
+### Responsive
+- [ ] Mobile-first with all 6 breakpoints tested
+- [ ] Renders correctly from 320px to 1280px+
+
+### Theme
+- [ ] Every `bg-*` has `dark:bg-*` counterpart
+- [ ] Every `text-*` has `dark:text-*` counterpart
+- [ ] Every `border-*` has `dark:border-*` counterpart
+- [ ] Tested in both light and dark mode
+
+### Architecture
+- [ ] No file exceeds 200 lines
+- [ ] Components are single-responsibility
+- [ ] Scope placement is correct
+- [ ] Named exports only (no default exports)
+
+### API
+- [ ] Uses `useApiActions` pattern
+- [ ] Types extracted from endpoints (no manual types)
+- [ ] Action state is single source of truth
+- [ ] No `as` casts, no `try/catch/await`
+
+### Components
+- [ ] Nucleus-core components used where available
+- [ ] Custom components compose from nucleus-core atoms
+- [ ] Skeleton loader exists for every data-driven component
+
+### Quality
+- [ ] Semantic HTML
+- [ ] GSAP animations
+- [ ] h-state for shared state (no prop drilling)
+- [ ] Production-grade (no TODOs)
+
+---
+
+**Remember**: Every interface should be distinctive, responsive from 320px to 4K, readable in both themes, and crafted with precision. These are not guidelines — they are requirements.

package/infra/templates/frontend/next.config.ts

@@ -1,23 +1,16 @@
 import type { NextConfig } from 'next'
 
 const nextConfig: NextConfig = {
+  output: 'standalone',
+  logging: {
+    browserToTerminal: true,
+  },
   async rewrites() {
+    const apiUrl = process.env.API_BASE_URL || 'http://localhost:9000'
     return [
       {
-        source: '/file-proxy/:path*',
-        destination: 'http://localhost:4000/file-proxy/:path*',
-      },
-      {
-        source: '/api/events/:path*',
-        destination: 'http://localhost:4000/api/events/:path*',
-      },
-      {
-        source: '/api/ws/:path*',
-        destination: 'http://localhost:4000/api/ws/:path*',
-      },
-      {
-        source: '/ws/:path*',
-        destination: 'http://localhost:4000/ws/:path*',
+        source: '/cdn/:path*',
+        destination: `${apiUrl}/cdn/:path*`,
       },
     ]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.42",
+	"version": "0.9.43",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",