create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/app/shell/nginx.conf

@@ -0,0 +1,23 @@
+# Shell static — port cố định 3000 trong container (conventions/05, gateway proxy_pass / → shell:3000)
+server {
+  listen 3000;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  # Security headers baseline (security-audit M-1) — CSP cho MF host để SF-7 thiết kế
+  # (script-src phải cho phép origin remote), ở đây chỉ 3 header không phụ thuộc origin.
+  add_header X-Content-Type-Options "nosniff" always;
+  add_header X-Frame-Options "DENY" always;
+  add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+  # SPA fallback — react-router history API (refresh deep-link không 404)
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+
+  location /assets/ {
+    expires 30d;
+    add_header Cache-Control "public, immutable";
+  }
+}

package/stack-template/app/shell/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@wakii/shell",
+  "version": "0.1.0",
+  "private": true,
+  "description": "FE shell — MF host (SF-5, FI-73). Rspack + @module-federation/enhanced, React 19. Standalone-copy: copy KÈM app/shared (fe-shared).",
+  "type": "module",
+  "scripts": {
+    "dev": "rspack serve",
+    "build": "rspack build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "catalog:",
+    "@wakii/ui-kit": "workspace:*",
+    "@wakii/fe-shared": "workspace:*",
+    "motion": "^12",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "react-hook-form": "^7",
+    "react-router": "catalog:",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@module-federation/enhanced": "catalog:",
+    "@rspack/cli": "1.7.12",
+    "@rspack/core": "catalog:",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@testing-library/jest-dom": "6.9.0",
+    "@testing-library/react": "16.3.0",
+    "@testing-library/user-event": "14.6.1",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.3",
+    "@vitest/coverage-v8": "3.2.4",
+    "jsdom": "27.0.0",
+    "postcss-loader": "^8.2.1",
+    "typescript": "^5.7.0",
+    "vitest": "3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/stack-template/app/shell/rspack.config.mjs

@@ -0,0 +1,147 @@
+import { ModuleFederationPlugin } from '@module-federation/enhanced/rspack';
+import { DefinePlugin, HtmlRspackPlugin } from '@rspack/core';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Windows-safe absolute path (URL.pathname cho ra /C:/... sai trên win32)
+const rootDir = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Shell — MF host (SF-5). Pin matrix theo app/shared/package.json mfToolkit:
+ * react 19.3.0 / rspack 1.7.12 / mf-enhanced 0.21.6 (nâng cấp = re-spike).
+ *
+ * Env build-time (conventions/06 + 08 — KHÔNG hardcode):
+ *   REMOTE_TASKS_URL / REMOTE_ACTIVITY_URL — remoteEntry của 2 remote
+ *     (dev native: http://localhost:4001|4002/remoteEntry.js; prod: mặc định đi qua gateway /remotes/<name>/)
+ *   API_BASE_URL — base gọi API. Dev native: http://localhost:8090 (auth-svc trực tiếp,
+ *     CORS dev mở — conventions/07). Prod (qua gateway): '' (same-origin).
+ *   SHELL_PORT — port dev server (default 3000, conventions/05).
+ */
+const isDev = process.env.NODE_ENV !== 'production';
+
+const remoteTasksUrl = process.env.REMOTE_TASKS_URL || '/remotes/tasks/remoteEntry.js';
+const remoteActivityUrl = process.env.REMOTE_ACTIVITY_URL || '/remotes/activity/remoteEntry.js';
+const apiBaseUrl = process.env.API_BASE_URL ?? (isDev ? 'http://localhost:8090' : '');
+
+export default {
+  entry: './src/index.tsx',
+  output: {
+    publicPath: '/',
+    filename: isDev ? '[name].js' : '[name].[contenthash].js',
+    // CSS emit ở ROOT (không nằm trong /assets/ immutable) + contenthash prod (cache-busting)
+    cssFilename: isDev ? '[name].css' : '[name].[contenthash].css',
+    clean: true,
+  },
+  resolve: {
+    extensions: ['.tsx', '.ts', '.jsx', '.js'],
+    // fe-shared (READ-ONLY, SF-1) import kiểu NodeNext: './x.js' chỉ tới file .ts
+    extensionAlias: {
+      '.js': ['.ts', '.tsx', '.js'],
+    },
+    // fe-shared src/ui (SF-1) import 'react' nhưng package KHÔNG khai báo dep
+    // (thêm dep = đổi pnpm-lock.yaml — success criteria cấm). Resolve qua
+    // node_modules của consumer — react 19.3.0 catalog-pinned giống hệt ×3,
+    // MF singleton vẫn giữ 1 bản runtime.
+    modules: [path.resolve(rootDir, 'node_modules'), 'node_modules'],
+  },
+  module: {
+    rules: [
+      {
+        test: /\.css$/,
+        // Tailwind v4 qua postcss — @tailwindcss/postcss xử lý @import + @theme +
+        // sinh utilities (spec tailwind-migration P0). Builtin css module nhận output.
+        type: 'css',
+        use: [
+          {
+            loader: 'postcss-loader',
+            options: {
+              postcssOptions: {
+                plugins: { '@tailwindcss/postcss': {} },
+              },
+            },
+          },
+        ],
+      },
+      {
+        test: /\.tsx?$/,
+        // fe-shared là package TS raw (main: ./src/index.ts) — bundler phải compile luôn
+        include: [path.resolve(rootDir, 'src'), /[\\/]app[\\/](shared|ui-kit)[\\/]src/],
+        use: {
+          loader: 'builtin:swc-loader',
+          options: {
+            jsc: {
+              parser: { syntax: 'typescript', tsx: true },
+              transform: { react: { runtime: 'automatic' } },
+              target: 'es2022',
+            },
+          },
+        },
+        type: 'javascript/auto',
+      },
+    ],
+  },
+  plugins: [
+    new HtmlRspackPlugin({
+      template: './index.html',
+    }),
+    new DefinePlugin({
+      __API_BASE_URL__: JSON.stringify(apiBaseUrl),
+      // F1 (review VU-53): cùng nguồn với remotes config ở trên — shell bootstrap nạp vào
+      // __REMOTE_URLS__ (remote-urls.ts) để retry BUG-2 re-register ĐÚNG url build-time
+      __REMOTE_TASKS_URL__: JSON.stringify(remoteTasksUrl),
+      __REMOTE_ACTIVITY_URL__: JSON.stringify(remoteActivityUrl),
+    }),
+    new ModuleFederationPlugin({
+      name: 'shell',
+      filename: 'remoteEntry.js',
+      remotes: {
+        tasks: `tasks@${remoteTasksUrl}`,
+        activity: `activity@${remoteActivityUrl}`,
+      },
+      // Singleton theo pin matrix — KHÔNG bundle duplicate react (spec slice mục 3).
+      // react/jsx-runtime: JSX fe-shared compile ra import này — thiếu = remote bundle
+      // riêng jsx-runtime kéo theo react thứ 2 → "Invalid hook call" (SF-1 spike R2).
+      shared: {
+        react: { singleton: true },
+        'react-dom': { singleton: true },
+        'react/jsx-runtime': { singleton: true, requiredVersion: false },
+        // react-query singleton (libs adopt 2026-10-17): 1 cache chung host+remotes —
+        // create task ở remote tasks → invalidate feed activity cùng cache
+        '@tanstack/react-query': { singleton: true },
+      },
+    }),
+  ],
+  experiments: {
+    css: true,
+  },
+  devServer: {
+    port: Number(process.env.SHELL_PORT || 3000),
+    historyApiFallback: true,
+    hot: true,
+    headers: { 'Access-Control-Allow-Origin': '*' },
+    // DEV-ONLY proxy — topology gateway dev thu nhỏ (đủ 4 route như gateway
+    // conventions/08): /api/tasks → node-svc, /api/activity → go-svc, /api/users →
+    // spring-svc, /api/auth → auth-svc. Shell là host, REMOTE chạy trong page
+    // context của shell nên /api/<svc> của remote cũng về đây. Origin dev khác cổng
+    // docker compose đã set CORS_DEV_ORIGIN (vd SHELL_PORT=3100) → cùng-origin qua
+    // proxy thay vì đụng stack compose. Prod không đi đây (gateway).
+    proxy: [
+      {
+        context: ['/api/tasks'],
+        target: `http://localhost:${process.env.NODE_SVC_PORT || 3001}`,
+      },
+      {
+        context: ['/api/activity'],
+        target: `http://localhost:${process.env.GO_SVC_PORT || 8082}`,
+      },
+      {
+        context: ['/api/users'],
+        target: `http://localhost:${process.env.SPRING_SVC_PORT || 8081}`,
+      },
+      {
+        context: ['/api/auth'],
+        target: `http://localhost:${process.env.AUTH_MOCK_PORT || 8090}`,
+      },
+    ],
+  },
+};

package/stack-template/app/shell/src/App.tsx

@@ -0,0 +1,57 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter, Navigate, Route, Routes } from 'react-router';
+import { Layout } from './components/Layout';
+import { RemoteSlot } from './components/RemoteSlot';
+import { RequireAuth } from './components/RequireAuth';
+import { HomePage } from './pages/HomePage';
+import { LoginPage } from './pages/LoginPage';
+
+/** Routes inner — tách riêng để test mount được với MemoryRouter. */
+export function AppRoutes() {
+  return (
+    <Routes>
+      <Route element={<Layout />}>
+        <Route path="/" element={<HomePage />} />
+        {/* Remote slots theo registry conventions/08: expose ./TasksPage, ./ActivityPage (SF-6 impl) */}
+        <Route
+          path="/tasks"
+          element={
+            <RequireAuth>
+              <RemoteSlot name="tasks" exposedModule="./TasksPage" />
+            </RequireAuth>
+          }
+        />
+        <Route
+          path="/activity"
+          element={
+            <RequireAuth>
+              <RemoteSlot name="activity" exposedModule="./ActivityPage" />
+            </RequireAuth>
+          }
+        />
+        <Route path="/login" element={<LoginPage />} />
+        <Route path="*" element={<Navigate to="/" replace />} />
+      </Route>
+    </Routes>
+  );
+}
+
+// QueryClient của HOST — react-query MF singleton nên remotes (in-shell) dùng chung
+// cache này: create task (remote tasks) → invalidate feed (remote activity) cùng nguồn.
+// retry: false — demo fail hiển thị tức thì; refetchOnWindowFocus off cho demo ổn định.
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { retry: false, refetchOnWindowFocus: false },
+    mutations: { retry: false },
+  },
+});
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AppRoutes />
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+}

package/stack-template/app/shell/src/api.ts

@@ -0,0 +1,36 @@
+// API client dùng chung shell — base đọc từ build-time env (conventions/05 rule 3 + 07 CORS):
+//   dev native: http://localhost:8090 (auth svc trực tiếp, CORS dev mở)
+//   prod qua gateway: '' (same-origin)
+import { ApiClient, createAuthClient, tokenStorage } from '@wakii/fe-shared';
+
+const LOGIN_TIMEOUT_MS = 15_000;
+
+/** Wrap fetch với AbortController timeout — fe-shared ApiClient (READ-ONLY) không có
+ * AbortSignal sẵn; không timeout = nút "Đang đăng nhập…" treo vô hạn khi gateway chết.
+ * fetchImpl bind LAZY tại call-time (mirror tasks/src/api.ts): vi.stubGlobal('fetch')
+ * trong unit test có hiệu lực; prod hành vi như cũ. */
+export function timeoutFetch(
+  timeoutMs: number,
+  fetchImpl?: typeof fetch,
+): typeof fetch {
+  return (input, init = {}) => {
+    const doFetch = fetchImpl ?? fetch.bind(globalThis);
+    if (init.signal) {
+      // caller tự quản signal — không override
+      return doFetch(input, init);
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`timeout ${timeoutMs}ms`)), timeoutMs);
+    return doFetch(input, { ...init, signal: controller.signal }).finally(() => clearTimeout(timer));
+  };
+}
+
+export const api = new ApiClient({
+  baseUrl: __API_BASE_URL__,
+  tokenStorage,
+  fetchImpl: timeoutFetch(LOGIN_TIMEOUT_MS),
+});
+
+/** Auth flows qua wrapper refresh-client (SF-4): login/register/withRefresh/logout —
+ * access → tokenStorage, refresh → localStorage['bp.rt'] (token-contract.md §2). */
+export const auth = createAuthClient(api);

package/stack-template/app/shell/src/app.css

@@ -0,0 +1,11 @@
+/* Tailwind v4 entry của shell — import ui-kit tailwind.css (theme + utilities, KHÔNG
+ * preflight). Utilities nằm layer(theme/utilities) nên css scoped .sh-* (unlayered)
+ * vẫn thắng khi cùng specificity — parity giữ nguyên trong giai đoạn migrate dần
+ * (spec tailwind-migration).
+ * ⚠️ @source PHẢI trỏ qua node_modules symlink ĐÚNG NHƯ THẾ: path repo-relative
+ * '../ui-kit/src' bị tailwind resolve qua symlink → node_modules → BỊ IGNORE (đã
+ * nghiệm chứng 2026-10-17 — chỉ explicit node_modules path được scan). */
+@import '@wakii/ui-kit/styles/tailwind.css';
+
+@source './';
+@source '../node_modules/@wakii/ui-kit/src';

package/stack-template/app/shell/src/bootstrap.tsx

@@ -0,0 +1,24 @@
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+// F1 (review VU-53 follow-up): nạp URL remote build-time vào __REMOTE_URLS__ TRƯỚC khi
+// mount — retry BUG-2 (registerRemotes force) re-register ĐÚng url webpack đã đăng ký,
+// kể cả dev-native (REMOTE_TASKS_URL env ≠ fallback /remotes/*). Chi tiết: remote-urls.ts
+import { registerBuildtimeRemoteUrls } from './remote-urls';
+// Shell LÀM CHỦ global (kiến trúc SF-1, base.css header): tokens + base import ở entry
+// — app.css (tailwind utilities, layered) + styles.css (scoped sh-*, unlayered) import
+// SAU để thắng base khi cùng specificity.
+import '@wakii/ui-kit/styles/tokens.css';
+import '@wakii/ui-kit/styles/base.css';
+// Dark theme (batch ⑰): host import LÀM CHỦ — data-bp-theme trên <html> (NavBar
+// toggle) cascade xuống mọi remote mount point, remotes không cần import riêng.
+import '@wakii/ui-kit/styles/themes/dark.css';
+import './app.css';
+
+registerBuildtimeRemoteUrls();
+
+const container = document.getElementById('root');
+if (!container) {
+  throw new Error('#root không tồn tại trong index.html');
+}
+
+createRoot(container).render(<App />);

package/stack-template/app/shell/src/components/Layout.tsx

@@ -0,0 +1,35 @@
+import { useEffect, useRef } from 'react';
+import { Outlet, useLocation } from 'react-router';
+import { NavBar } from './NavBar';
+
+/**
+ * Layout khung chung: skip link (a11y) + nav + main.
+ * Route focus management: mỗi lần đổi route, focus chuyển vào <main> (tabIndex -1)
+ * — screen reader/số phím đọc nội dung mới thay vì đứng ở link cũ (a11y baseline, có test).
+ */
+export function Layout() {
+  const location = useLocation();
+  const mainRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    mainRef.current?.focus();
+  }, [location.pathname]);
+
+  return (
+    <>
+      <a href="#main-content" className="skip-link">
+        Tới nội dung chính
+      </a>
+      <NavBar />
+      {/* biome-ignore lint/a11y/noNoninteractiveTabindex: focus target cho route change */}
+      <main
+        className="mx-auto w-full max-w-[1200px] p-6 focus:outline-none focus-visible:outline-2 focus-visible:outline-accent-hi max-md:p-4"
+        id="main-content"
+        ref={mainRef}
+        tabIndex={-1}
+      >
+        <Outlet />
+      </main>
+    </>
+  );
+}

package/stack-template/app/shell/src/components/NavBar.tsx

@@ -0,0 +1,118 @@
+import { useEffect } from 'react';
+import { Link, NavLink, useNavigate } from 'react-router';
+import { isExpired, readClaims, tokenStorage } from '@wakii/fe-shared';
+import { Button, Icon, useLocalStorage } from '@wakii/ui-kit';
+import { auth } from '../api';
+
+/* Dark toggle toàn host (batch ⑰ — pattern AdminLayout): data-bp-theme trên
+ * <html> + useLocalStorage persist. Remote trong host ăn theo CSS cascade —
+ * remotes không cần code riêng. */
+function MoonIcon() {
+  return (
+    <svg viewBox="0 0 24 24" width={14} height={14} fill="none" stroke="currentColor" strokeWidth={2} aria-hidden="true">
+      <path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+
+function SunIcon() {
+  return (
+    <svg viewBox="0 0 24 24" width={14} height={14} fill="none" stroke="currentColor" strokeWidth={2} aria-hidden="true">
+      <circle cx="12" cy="12" r="4" />
+      <path d="M12 2v2m0 16v2M4.9 4.9l1.4 1.4m11.4 11.4 1.4 1.4M2 12h2m16 0h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" strokeLinecap="round" />
+    </svg>
+  );
+}
+
+function useHostTheme() {
+  const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('shell-theme', 'light');
+  useEffect(() => {
+    document.documentElement.setAttribute('data-bp-theme', theme);
+  }, [theme]);
+  return { theme, setTheme };
+}
+
+/**
+ * App chrome (hand-off §4): brand + nav + dark toggle + user chip/logout.
+ * Active state: NavLink tự set aria-current="page" — visual = gạch accent 2px dưới
+ * (after: utilities). Đọc token MỖI render (không useState cache) — login/logout
+ * navigate là re-render trigger, nav cập nhật email ngay.
+ */
+const NAV_LINK =
+  "relative flex items-center self-stretch rounded-2 px-2.5 text-label no-underline text-ink2 transition-colors hover:text-ink aria-[current=page]:text-ink aria-[current=page]:after:absolute aria-[current=page]:after:bottom-0 aria-[current=page]:after:left-2 aria-[current=page]:after:right-2 aria-[current=page]:after:h-0.5 aria-[current=page]:after:rounded-[1px] aria-[current=page]:after:bg-accent aria-[current=page]:after:content-['']";
+
+export function NavBar() {
+  const navigate = useNavigate();
+  const { theme, setTheme } = useHostTheme();
+  const token = tokenStorage.getToken();
+  const claims = token && !isExpired(token) ? readClaims(token) : null;
+
+  // Logout qua wrapper refresh-client (SF-4): revoke rt server-side + clear CẢ 2 key
+  // (tokenStorage + bp.rt) — logout() không ném khi mạng chết nên await an toàn.
+  async function logout() {
+    await auth.logout();
+    navigate('/login');
+  }
+
+  return (
+    <header className="flex min-h-[52px] flex-wrap items-center gap-x-4 gap-y-2 border-b border-line bg-s1 px-4 py-2 max-md:px-3">
+      <span className="flex items-center gap-2 text-body font-semibold tracking-[-0.01em] text-ink">
+        <span aria-hidden="true" className="grid size-5 shrink-0 place-items-center rounded-[5px] bg-accent">
+          <Icon name="menu-bars" size={12} className="text-white" />
+        </span>
+        Boilerplate
+      </span>
+      <span aria-hidden="true" className="h-[18px] w-px shrink-0 self-center bg-line max-md:hidden" />
+      <nav aria-label="Điều hướng chính" className="flex flex-wrap gap-0.5">
+        <NavLink className={NAV_LINK} end to="/">
+          Trang chủ
+        </NavLink>
+        <NavLink className={NAV_LINK} to="/tasks">
+          Tasks
+        </NavLink>
+        <NavLink className={NAV_LINK} to="/activity">
+          Activity
+        </NavLink>
+      </nav>
+      <div className="ml-auto flex flex-wrap items-center gap-2">
+        <button
+          type="button"
+          onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
+          aria-label={theme === 'dark' ? 'Tắt dark mode' : 'Bật dark mode'}
+          className="cursor-pointer rounded-2 border-none bg-transparent p-1.5 text-ink2 transition-colors hover:bg-s3"
+        >
+          {theme === 'dark' ? <SunIcon /> : <MoonIcon />}
+        </button>
+        {claims ? (
+          <>
+            <span
+              className="flex h-7 max-w-[260px] items-center gap-2 rounded-2 border border-line bg-s2 py-0 pl-1 pr-2.5 max-md:max-w-[180px]"
+              data-testid="nav-user"
+            >
+              {/* token hiếm khi thiếu email (readClaims chỉ validate sub) — guard tránh trắng nav */}
+              <span
+                aria-hidden="true"
+                className="grid size-5 shrink-0 place-items-center rounded-pill bg-accent/15 text-meta font-semibold text-accent"
+              >
+                {claims.email?.charAt(0)?.toUpperCase() ?? '?'}
+              </span>
+              <span className="overflow-hidden text-ellipsis whitespace-nowrap text-meta text-ink2">
+                {claims.email}
+              </span>
+            </span>
+            <Button type="text" onClick={logout}>
+              Đăng xuất
+            </Button>
+          </>
+        ) : (
+          <Link
+            className="inline-flex h-8 cursor-pointer items-center rounded-2 border-transparent bg-transparent px-[15px] text-body text-ink2 transition-colors hover:bg-s3 hover:text-ink"
+            to="/login"
+          >
+            Đăng nhập
+          </Link>
+        )}
+      </div>
+    </header>
+  );
+}

package/stack-template/app/shell/src/components/RemoteSlot.tsx

@@ -0,0 +1,82 @@
+import { Component, ComponentType, ReactNode, Suspense, lazy, useCallback, useMemo, useState } from 'react';
+import { type LoadRemoteModuleOptions, type RemoteName, loadRemoteModule, resolveRemoteUrl } from '@wakii/fe-shared';
+import { Button, Icon, Skeleton } from '@wakii/ui-kit';
+
+/**
+ * Slot load 1 remote (conventions/08 registry) vào layout.
+ * Remote down / load fail → error boundary hiện fallback + retry — KHÔNG trắng trang
+ * (spec slice mục 7; remote thật là việc SF-6, host-side chỉ cần sẵn slot).
+ */
+
+interface RemoteErrorBoundaryProps {
+  children: ReactNode;
+  onRetry: () => void;
+  remoteName: string;
+}
+class RemoteErrorBoundary extends Component<RemoteErrorBoundaryProps, { error: Error | null }> {
+  state = { error: null as Error | null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  render() {
+    if (this.state.error) {
+      return (
+        <div role="alert" className="flex flex-col items-start gap-4 rounded-xl border border-line bg-s2 p-6">
+          <p className="m-0 text-ink2">
+            Không tải được phần <strong>{this.props.remoteName}</strong> (remote có thể đang
+            xuống). Vui lòng thử lại.
+          </p>
+          <Button onClick={this.props.onRetry}>
+            <span className="inline-flex items-center gap-1.5">
+              <Icon name="refresh" size={14} />
+              Thử lại
+            </span>
+          </Button>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
+
+function loadRemote(name: RemoteName, exposedModule: string, options?: LoadRemoteModuleOptions) {
+  const remote = { name, url: resolveRemoteUrl(name) };
+  return loadRemoteModule<{ default: ComponentType }>(remote, exposedModule, options);
+}
+
+export function RemoteSlot({
+  name,
+  exposedModule,
+}: {
+  name: RemoteName;
+  exposedModule: string;
+}) {
+  const [attempt, setAttempt] = useState(0);
+  const retry = useCallback(() => setAttempt((a) => a + 1), []);
+
+  // lazy cache theo (module, attempt) — re-render KHÔNG tạo component type mới (tránh remount
+  // + Suspense flash khi click lại nav link đang đứng); retry đổi attempt → lazy mới → import lại.
+  // attempt > 0 = lần retry (BUG-2, sf-5b): mang cờ retry để fe-shared bust sticky rejection
+  // trong MF runtime (registerRemotes force) — nếu không, runtime trả lại rejection cũ tức thì
+  // dù remote đã sống lại (0 network request mới), "Thử lại" không bao giờ ăn.
+  const LazyRemote = useMemo(
+    () => lazy(() => loadRemote(name, exposedModule, attempt > 0 ? { retry: true } : undefined)),
+    [name, exposedModule, attempt],
+  );
+
+  return (
+    <RemoteErrorBoundary onRetry={retry} remoteName={name} key={attempt}>
+      <Suspense
+        fallback={
+          <div className="flex flex-col gap-3">
+            <Skeleton variant="card" count={2} />
+          </div>
+        }
+      >
+        <LazyRemote />
+      </Suspense>
+    </RemoteErrorBoundary>
+  );
+}

package/stack-template/app/shell/src/components/RequireAuth.tsx

@@ -0,0 +1,14 @@
+import { Navigate, useLocation } from 'react-router';
+import type { ReactElement } from 'react';
+import { isExpired, tokenStorage } from '@wakii/fe-shared';
+
+/** Gate route: chưa login (hoặc token hết hạn) → redirect /login, giữ lại path gốc. */
+export function RequireAuth({ children }: { children: ReactElement }) {
+  const location = useLocation();
+  const token = tokenStorage.getToken();
+  if (!token || isExpired(token)) {
+    // giữ cả search + pathname — login xong quay lại đúng deep-link
+    return <Navigate to="/login" replace state={{ from: `${location.pathname}${location.search}` }} />;
+  }
+  return children;
+}

package/stack-template/app/shell/src/env.d.ts

@@ -0,0 +1,7 @@
+// Build-time env do rspack DefinePlugin inject (xem rspack.config.mjs)
+declare const __API_BASE_URL__: string;
+declare const __REMOTE_TASKS_URL__: string;
+declare const __REMOTE_ACTIVITY_URL__: string;
+// CSS side-effect import (fe-shared tokens/base — rspack experiments.css); defensive:
+// 3 package cùng khai báo để typecheck đứng riêng từng package đều sạch (SF-1)
+declare module '*.css';

package/stack-template/app/shell/src/index.tsx

@@ -0,0 +1,3 @@
+// Async boundary BẮT BUỘC cho MF host — bài học spike SF-1 (RUNTIME-006 loadShareSync):
+// entry KHÔNG import shared/bootstrap tĩnh, phải qua dynamic import để MF share init xong trước.
+import('./bootstrap');