create-surf-app 0.1.0

package/dist/index.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import fs from "fs";
+import path from "path";
+var args = process.argv.slice(2);
+var projectName = args.find((a) => !a.startsWith("--")) || ".";
+var frontendPort = getFlag("--port", "5173");
+var backendPort = getFlag("--backend-port", "3001");
+function getFlag(name2, fallback) {
+  const idx = args.indexOf(name2);
+  return idx >= 0 && args[idx + 1] ? args[idx + 1] : fallback;
+}
+var frontendPkg = {
+  name: "frontend",
+  private: true,
+  type: "module",
+  scripts: {
+    dev: `vite --port ${frontendPort}`,
+    build: "vite build",
+    preview: "vite preview",
+    lint: "eslint ."
+  },
+  dependencies: {
+    "@surf-ai/sdk": "latest",
+    "@surf-ai/theme": "latest",
+    "@radix-ui/react-accordion": "1.2.12",
+    "@radix-ui/react-aspect-ratio": "1.1.8",
+    "@radix-ui/react-avatar": "1.1.11",
+    "@radix-ui/react-checkbox": "1.3.3",
+    "@radix-ui/react-collapsible": "1.1.12",
+    "@radix-ui/react-context-menu": "2.2.16",
+    "@radix-ui/react-dialog": "1.1.15",
+    "@radix-ui/react-dropdown-menu": "2.1.16",
+    "@radix-ui/react-hover-card": "1.1.15",
+    "@radix-ui/react-label": "2.1.8",
+    "@radix-ui/react-menubar": "1.1.16",
+    "@radix-ui/react-navigation-menu": "1.2.14",
+    "@radix-ui/react-popover": "1.1.15",
+    "@radix-ui/react-progress": "1.1.8",
+    "@radix-ui/react-radio-group": "1.3.8",
+    "@radix-ui/react-scroll-area": "1.2.10",
+    "@radix-ui/react-select": "2.2.6",
+    "@radix-ui/react-separator": "1.1.8",
+    "@radix-ui/react-slider": "1.3.6",
+    "@radix-ui/react-slot": "1.2.4",
+    "@radix-ui/react-switch": "1.2.6",
+    "@radix-ui/react-tabs": "1.1.13",
+    "@radix-ui/react-toast": "1.2.15",
+    "@radix-ui/react-toggle": "1.1.10",
+    "@radix-ui/react-toggle-group": "1.1.11",
+    "@radix-ui/react-tooltip": "1.2.8",
+    "@tanstack/react-query": "5.94.5",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "cmdk": "1.1.1",
+    "echarts": "5.6.0",
+    "echarts-for-react": "3.0.6",
+    "embla-carousel-react": "8.6.0",
+    "lucide-react": "0.454.0",
+    "next-themes": "0.4.6",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "sonner": "1.7.4",
+    "tailwind-merge": "2.6.1",
+    "vaul": "1.1.2",
+    "zod": "3.25.76"
+  },
+  devDependencies: {
+    "@eslint/js": "9.39.4",
+    "@tailwindcss/vite": "4.2.2",
+    "@types/node": "22.19.15",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "4.7.0",
+    "eslint": "9.39.4",
+    "eslint-plugin-react-hooks": "5.2.0",
+    "eslint-plugin-react-refresh": "0.4.26",
+    "globals": "16.5.0",
+    "tailwindcss": "4.2.2",
+    "tw-animate-css": "1.4.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.57.1",
+    "vite": "6.4.1"
+  }
+};
+var templates = {
+  // ── Backend ──────────────────────────────────────────────────────────────
+  "backend/package.json": JSON.stringify({
+    name: "backend",
+    private: true,
+    scripts: {
+      start: "node server.js",
+      dev: "node --watch server.js"
+    },
+    dependencies: {
+      "@surf-ai/sdk": "latest",
+      "express": "^4.22.0"
+    }
+  }, null, 2),
+  "backend/server.js": `const { createServer } = require('@surf-ai/sdk/server')
+createServer({ port: ${backendPort} }).start()
+`,
+  "backend/routes/.gitkeep": "",
+  "backend/db/schema.js": `// Define your Drizzle ORM tables here.
+// Example:
+//   const { pgTable, serial, text, timestamp } = require('drizzle-orm/pg-core')
+//   exports.users = pgTable('users', {
+//     id: serial('id').primaryKey(),
+//     name: text('name').notNull(),
+//     created_at: timestamp('created_at').defaultNow(),
+//   })
+`,
+  // ── Frontend ─────────────────────────────────────────────────────────────
+  "frontend/package.json": JSON.stringify(frontendPkg, null, 2),
+  "frontend/vite.config.ts": `import { defineConfig, loadEnv } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import path from 'path'
+
+const env = loadEnv('', process.cwd(), '')
+const FRONTEND_PORT = parseInt(env.VITE_PORT || '${frontendPort}', 10)
+const BACKEND_PORT = parseInt(env.VITE_BACKEND_PORT || '${backendPort}', 10)
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  server: {
+    port: FRONTEND_PORT,
+    host: '0.0.0.0',
+    proxy: {
+      '/proxy': { target: \`http://127.0.0.1:\${BACKEND_PORT}\`, changeOrigin: true },
+      '/api': { target: \`http://127.0.0.1:\${BACKEND_PORT}\`, changeOrigin: true },
+    },
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+})
+`,
+  // index.html comes from templates/ directory (has cold-start guard script)
+  "frontend/tsconfig.json": JSON.stringify({
+    compilerOptions: {
+      target: "ES2020",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      jsx: "react-jsx",
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      paths: { "@/*": ["./src/*"] }
+    },
+    include: ["src"]
+  }, null, 2),
+  "frontend/components.json": JSON.stringify({
+    "$schema": "https://ui.shadcn.com/schema.json",
+    "style": "default",
+    "rsc": false,
+    "tsx": true,
+    "tailwind": {
+      "config": "",
+      "css": "src/index.css",
+      "baseColor": "slate",
+      "cssVariables": true
+    },
+    "aliases": {
+      "components": "@/components",
+      "utils": "@surf-ai/sdk/react",
+      "hooks": "@/hooks"
+    }
+  }, null, 2),
+  // entry-client.tsx replaces main.tsx — comes from templates/ directory
+  "frontend/src/App.tsx": `import { useMarketPrice } from '@surf-ai/sdk/react'
+
+export default function App() {
+  const { data, isLoading, error } = useMarketPrice({ symbol: 'BTC', time_range: '1d' })
+
+  return (
+    <div className="min-h-screen bg-background text-foreground p-10">
+      <h1 className="text-3xl font-bold mb-4">Surf App</h1>
+      {isLoading && <p className="text-muted-foreground">Loading BTC price...</p>}
+      {error && <p className="text-destructive">Error: {(error as Error).message}</p>}
+      {data?.data?.[0] && (
+        <p className="text-4xl font-bold">
+          BTC: <span className="text-primary">\${data.data[0].value?.toLocaleString()}</span>
+        </p>
+      )}
+    </div>
+  )
+}
+`,
+  "frontend/src/index.css": `@import url('https://fonts.googleapis.com/css2?family=Lato:wght@400;600;700;900&family=Roboto+Mono:wght@400;500&display=swap');
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@surf-ai/theme";
+`,
+  // cn() and useToast() are now in @surf-ai/sdk/react
+  "frontend/src/db/schema.ts": `// Database schema definition \u2014 keep in sync with backend/db/schema.js.
+// This file mirrors the backend schema for TypeScript type safety in the frontend.
+//
+// Example:
+//   import { pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core'
+//   export const users = pgTable('users', {
+//     id: serial('id').primaryKey(),
+//     name: text('name').notNull(),
+//     created_at: timestamp('created_at').defaultNow(),
+//   })
+`,
+  "frontend/src/vite-env.d.ts": `/// <reference types="vite/client" />
+`,
+  // ── Root ──────────────────────────────────────────────────────────────────
+  "CLAUDE.md": `# Project
+
+Built with [Surf SDK](https://github.com/cyberconnecthq/urania/tree/main/packages/sdk).
+
+## Imports from @surf-ai/sdk
+
+Everything comes from \`@surf-ai/sdk\`. Do NOT create local utility files for these.
+
+**Frontend (\`@surf-ai/sdk/react\`):**
+\`\`\`tsx
+import { useMarketPrice, useTokenHolders } from '@surf-ai/sdk/react'  // data hooks
+import { cn } from '@surf-ai/sdk/react'                                // Tailwind class merge
+import { useToast, toast } from '@surf-ai/sdk/react'                   // toast notifications
+\`\`\`
+
+**Backend (\`@surf-ai/sdk/server\`):**
+\`\`\`js
+const { dataApi } = require('@surf-ai/sdk/server')
+const data = await dataApi.market.price({ symbol: 'BTC' })
+const holders = await dataApi.token.holders({ address: '0x...', chain: 'ethereum' })
+// Escape hatch for new endpoints:
+const raw = await dataApi.get('newcategory/endpoint', { foo: 'bar' })
+\`\`\`
+
+## Structure
+
+\`\`\`
+frontend/src/App.tsx       - build your UI here
+frontend/src/components/   - add components
+frontend/src/db/schema.ts  - frontend DB schema mirror
+backend/routes/*.js        - add API routes (auto-mounted at /api/{name})
+backend/db/schema.js       - define database tables
+\`\`\`
+
+## Built-in Endpoints (from @surf-ai/sdk/server)
+
+\`createServer()\` provides these automatically \u2014 do NOT create routes for them:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| \`/api/health\` | GET | Health check \u2014 \`{ status: 'ok' }\` |
+| \`/api/__sync-schema\` | POST | Sync \`backend/db/schema.js\` tables to database |
+| \`/api/cron\` | GET | List cron jobs with status and next run time |
+| \`/api/cron\` | POST | Create a new cron task |
+| \`/api/cron/:id\` | PATCH | Update a cron task (schedule, enabled, etc.) |
+| \`/api/cron/:id\` | DELETE | Delete a cron task |
+| \`/api/cron/:id/run\` | POST | Manually trigger a cron task |
+| \`/proxy/*\` | ANY | Data API passthrough \u2014 \`/proxy/market/price\` \u2192 hermod |
+
+Auto-registered from \`backend/routes/*.js\`:
+| File | Endpoint |
+|------|----------|
+| \`routes/btc.js\` | \`/api/btc\` |
+| \`routes/portfolio.js\` | \`/api/portfolio\` |
+
+## Database
+
+Define tables in \`backend/db/schema.js\` using Drizzle ORM:
+\`\`\`js
+const { pgTable, serial, text, timestamp } = require('drizzle-orm/pg-core')
+exports.users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+  created_at: timestamp('created_at').defaultNow(),
+})
+\`\`\`
+
+Tables are auto-created on startup and when \`schema.js\` changes (file watcher).
+The agent can also call \`POST /api/__sync-schema\` explicitly after editing.
+
+## Do NOT modify
+
+- \`vite.config.ts\` \u2014 proxy and build config
+- \`backend/server.js\` \u2014 uses @surf-ai/sdk/server
+- \`entry-client.tsx\` \u2014 app bootstrap with SSR hydration
+- \`entry-server.tsx\` \u2014 SSR render for deploy
+- \`index.html\` \u2014 cold-start guard and Surf badge
+- \`eslint.config.*\` \u2014 lint rules
+- \`index.css\` \u2014 only imports, do not add styles here (use Tailwind classes)
+
+## Rules
+
+- Use \`@surf-ai/sdk/react\` hooks in frontend, \`@surf-ai/sdk/server\` dataApi in backend
+- Use Tailwind CSS classes for styling (Surf Design System theme via \`@surf-ai/theme\`)
+- Use shadcn/ui components \u2014 install with \`bunx shadcn@latest add button\`
+- Use \`cn()\` from \`@surf-ai/sdk/react\` to merge Tailwind classes
+- Frontend packages are pre-installed \u2014 check \`package.json\` before installing
+- Dark theme is the default (configured in entry-client.tsx)
+`
+};
+var root = path.resolve(projectName);
+var name = path.basename(root);
+console.log(`
+  Creating Surf app in ${root}
+`);
+fs.mkdirSync(root, { recursive: true });
+for (const [relPath, content] of Object.entries(templates)) {
+  const fullPath = path.join(root, relPath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content);
+  console.log(`  ${relPath}`);
+}
+var templatesDir = path.join(new URL(".", import.meta.url).pathname, "templates");
+if (fs.existsSync(templatesDir)) {
+  copyDir(templatesDir, root);
+}
+function copyDir(src, dest) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDir(srcPath, destPath);
+    } else {
+      fs.writeFileSync(destPath, fs.readFileSync(srcPath));
+      console.log(`  ${path.relative(root, destPath)}`);
+    }
+  }
+}
+console.log(`
+Done! Next steps:
+
+  cd ${name}
+  cd backend && bun install && cd ..
+  cd frontend && bun install && cd ..
+
+  # Start backend
+  cd backend && bun dev &
+
+  # Start frontend
+  cd frontend && bun dev
+
+  Open http://localhost:${frontendPort}
+`);

package/dist/templates/backend/eslint.config.mjs

@@ -0,0 +1,21 @@
+import js from '@eslint/js';
+import globals from 'globals';
+
+export default [
+  { ignores: ['node_modules'] },
+  {
+    files: ['**/*.js'],
+    ...js.configs.recommended,
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'commonjs',
+      globals: globals.node,
+    },
+    rules: {
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      'no-empty': 'warn',
+      'eqeqeq': 'warn',
+      'no-fallthrough': 'warn',
+    },
+  },
+];

package/dist/templates/frontend/eslint.config.js

@@ -0,0 +1,42 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  { ignores: ['dist', 'node_modules'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.{js,jsx,ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+      parserOptions: {
+        ecmaFeatures: { jsx: true },
+      },
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+      'no-unused-vars': 'off',
+      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-empty-object-type': 'warn',
+      '@typescript-eslint/ban-ts-comment': 'warn',
+      '@typescript-eslint/no-require-imports': 'off',
+      '@typescript-eslint/no-unused-expressions': 'warn',
+      '@typescript-eslint/no-unsafe-function-type': 'warn',
+    },
+  },
+)

package/dist/templates/frontend/index.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="/favicon.ico" />
+    <title>App</title>
+  </head>
+  <body>
+    <div id="root"><!--ssr-outlet--></div>
+    <script type="module" src="./src/entry-client.tsx"></script>
+    <script>
+      // Fallback: if React fails to render (e.g. Vite dep stubs during cold
+      // start), auto-reload until deps are ready.  This fires OUTSIDE React
+      // so it works even when React itself is null/undefined.
+      (function(){
+        var K='__boot_reload', W=30000, M=8;
+        function st(){try{return JSON.parse(sessionStorage.getItem(K))||{c:0,t:0}}catch(e){return{c:0,t:0}}}
+        setTimeout(function(){
+          if(window.__reactOk)return;
+          var s=st(),c=(Date.now()-s.t>W)?0:s.c;
+          if(c<M){sessionStorage.setItem(K,JSON.stringify({c:c+1,t:Date.now()}));location.reload()}
+        },3000);
+      })();
+    </script>
+    <!-- Made by Surf badge -->
+    <style>
+    #surf-badge{position:fixed;bottom:16px;right:16px;z-index:2147483647;display:inline-flex;align-items:center;gap:4px;padding:4px 12px;border-radius:20px;font-family:"Lato",system-ui,sans-serif;font-size:12px;font-weight:500;line-height:16px;text-decoration:none;box-shadow:0 1px 1px rgba(51,51,51,.08),0 6px 12px rgba(51,51,51,.08);opacity:.9;transition:opacity .2s}
+    #surf-badge:hover{opacity:1}
+    @media print{#surf-badge{display:none}}
+    </style>
+    <a id="surf-badge" href="https://asksurf.ai" target="_blank" rel="noopener noreferrer" aria-label="Made by Surf" style="background:var(--bg-menu,#fff);color:var(--fg-base,#212121)">
+      <span>Made by</span>
+      <svg width="40" height="13" viewBox="0 0 63 20" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+        <path d="M15.583 13.333C15.9931 13.3331 16.3814 13.5196 16.6377 13.8398L18.7666 16.5019C18.7956 16.5382 18.8261 16.5719 18.8574 16.6035C19.2049 16.954 19.6484 17.3405 19.6484 17.834C19.6484 18.3399 19.2383 18.75 18.7324 18.75H18.4668C18.1079 18.75 17.7682 18.5868 17.5439 18.3066L16.3633 16.831C15.6565 15.9476 14.2315 16.4477 14.2314 17.5791V18.6494C14.2314 18.7061 14.1827 18.7499 14.126 18.75H12.2529C11.6074 18.75 10.997 18.4562 10.5938 17.9521L9.69629 16.831C8.98948 15.9478 7.56544 16.4478 7.56543 17.5791V18.6494C7.56542 18.7062 7.51669 18.7499 7.45996 18.75H5.58594C4.94038 18.7499 4.32999 18.4563 3.92676 17.9521L3.03027 16.831C2.67436 16.3862 2.14844 15.9311 2.14844 15.3613V13.4385C2.14851 13.3817 2.19228 13.333 2.24902 13.333C2.65919 13.333 3.04737 13.5197 3.30371 13.8398L5.43359 16.5019C6.14031 17.3853 7.56521 16.8861 7.56543 15.7549V14.6846C7.56543 13.9385 8.16998 13.333 8.91602 13.333C9.32621 13.333 9.71437 13.5196 9.9707 13.8398L12.1006 16.5019C12.8052 17.3827 14.2227 16.8887 14.2314 15.7646V14.6846C14.2314 13.9385 14.837 13.333 15.583 13.333ZM15.583 6.66698C15.9932 6.66711 16.3814 6.8535 16.6377 7.17382L18.7666 9.83593C19.1224 10.2806 19.6484 10.7352 19.6484 11.3047V13.2266C19.6483 13.2833 19.6046 13.333 19.5479 13.333C19.1375 13.333 18.7495 13.1466 18.4932 12.8262L16.3633 10.1641C15.6565 9.28087 14.2315 9.78081 14.2314 10.9121V11.9824C14.2314 12.7284 13.6269 13.333 12.8809 13.333C12.4706 13.3329 12.0825 13.1465 11.8262 12.8262L9.69629 10.1641C8.98942 9.28109 7.56544 9.78088 7.56543 10.9121V11.9824C7.56543 12.7282 6.96062 13.3327 6.21484 13.333C5.80451 13.333 5.41551 13.1466 5.15918 12.8262L3.03027 10.1641C2.67435 9.71918 2.14844 9.26406 2.14844 8.69433V6.77245C2.14851 6.71573 2.19228 6.66699 2.24902 6.66698C2.65936 6.66698 3.04738 6.8534 3.30371 7.17382L5.43359 9.83593C6.14042 10.7191 7.56543 10.2192 7.56543 9.08788V8.01757C7.56543 7.27154 8.16998 6.66698 8.91602 6.66698C9.32634 6.66701 9.71437 6.85341 9.9707 7.17382L12.1006 9.83593C12.8052 10.7162 14.2225 10.2223 14.2314 9.09863V8.01757C14.2314 7.27154 14.837 6.66698 15.583 6.66698ZM3.33008 1.24999C3.68899 1.24999 4.02863 1.41318 4.25293 1.69335L5.43359 3.16894C6.14036 4.0524 7.56543 3.55227 7.56543 2.42089V1.35058C7.56544 1.29384 7.61417 1.25007 7.6709 1.24999H9.54395C10.1895 1.24999 10.7999 1.54378 11.2031 2.04784L12.1006 3.16894C12.8052 4.04953 14.2227 3.5556 14.2314 2.43163V1.35058C14.2315 1.29384 14.2802 1.25007 14.3369 1.24999H16.2109C16.8565 1.25014 17.4669 1.54375 17.8701 2.04784L18.7666 3.16894C19.1223 3.61354 19.6481 4.06741 19.6484 4.63671V6.56054C19.6483 6.61728 19.6046 6.66698 19.5479 6.66698C19.1377 6.66698 18.7495 6.48034 18.4932 6.16015L16.3633 3.49804C15.6566 2.61465 14.2317 3.11391 14.2314 4.24511V5.3164C14.2312 6.06217 13.6267 6.66698 12.8809 6.66698C12.4707 6.66693 12.0825 6.48039 11.8262 6.16015L9.69629 3.49804C8.98957 2.61465 7.56565 3.11391 7.56543 4.24511V5.3164C7.56518 6.06202 6.96046 6.66673 6.21484 6.66698C5.80453 6.66698 5.41551 6.48054 5.15918 6.16015L3.03027 3.49804C3.00109 3.46156 2.97093 3.42724 2.93945 3.3955C2.59217 3.04543 2.14867 2.65906 2.14844 2.16601C2.14844 1.66032 2.55877 1.24999 3.06445 1.24999H3.33008Z"/>
+        <path d="M35.1083 6.97044C34.7154 6.97044 34.5223 6.77734 34.3692 6.39782C33.9963 5.49228 33.0042 4.97958 31.6925 4.97958C30.0146 4.97958 28.9559 5.83851 28.9559 6.99707C28.9493 8.30211 30.3675 8.80149 31.4328 9.07449L32.7645 9.42072C34.4957 9.84686 36.6863 10.799 36.6863 13.2559C36.6863 15.5664 34.8419 17.251 31.6392 17.251C28.8827 17.251 27.0649 16.0125 26.6321 13.9617C26.5389 13.5156 26.7986 13.2559 27.2514 13.2559H27.9971C28.3966 13.2559 28.5897 13.4557 28.7229 13.8485C29.1024 14.9272 30.2676 15.4466 31.6259 15.4466C33.3771 15.4466 34.6488 14.5676 34.6488 13.236C34.6488 12.0241 33.5236 11.5447 32.0654 11.1586L30.454 10.7191C28.2634 10.1265 26.9051 9.01456 26.9051 7.11692C26.9051 4.76651 29.0025 3.20179 31.7391 3.20179C34.2027 3.20179 36.0005 4.45357 36.4133 6.27131C36.5132 6.71076 36.2335 6.97044 35.7874 6.97044H35.1083Z"/>
+        <path d="M45.0887 7.46316C45.0887 7.03036 45.3217 6.79732 45.7545 6.79732H46.4204C46.8532 6.79732 47.0862 7.03036 47.0862 7.46316V16.3588C47.0862 16.7915 46.8532 17.0246 46.4204 17.0246H45.7945C45.3617 17.0246 45.1286 16.7915 45.1286 16.3588V15.2535H45.0221C44.5494 16.3454 43.504 17.1578 41.9659 17.1578C40.0017 17.1578 38.6101 15.8394 38.6101 13.3026V7.46316C38.6101 7.03036 38.8431 6.79732 39.2759 6.79732H39.9351C40.3679 6.79732 40.601 7.03036 40.601 7.46316V13.0629C40.601 14.4545 41.4532 15.3467 42.685 15.3467C43.8036 15.3467 45.0954 14.521 45.0887 12.7832V7.46316Z"/>
+        <path d="M49.3862 7.46316C49.3862 7.03036 49.6193 6.79732 50.0521 6.79732H50.6447C51.0774 6.79732 51.3105 7.03036 51.3105 7.46316V8.42196H51.417C51.7899 7.32333 52.8153 6.64418 54.0138 6.64418C54.0737 6.64418 54.147 6.64418 54.2202 6.65084C54.6397 6.65749 54.8594 6.91717 54.8594 7.33665V7.88264C54.8594 8.33541 54.673 8.54182 54.3467 8.50852C54.1803 8.48855 53.9938 8.47523 53.8207 8.47523C52.4091 8.47523 51.3771 9.4407 51.3771 10.779V16.3588C51.3771 16.7915 51.144 17.0246 50.7112 17.0246H50.0521C49.6193 17.0246 49.3862 16.7915 49.3862 16.3588V7.46316Z"/>
+        <path d="M61.6788 7.72949C61.6788 8.16229 61.4457 8.39533 61.013 8.39533H59.4749V16.3588C59.4749 16.7915 59.2418 17.0246 58.809 17.0246H58.1432C57.7104 17.0246 57.4774 16.7915 57.4774 16.3588V8.39533H56.5652C56.1324 8.39533 55.8993 8.16229 55.8993 7.72949V7.46316C55.8993 7.03036 56.1324 6.79732 56.5652 6.79732H57.4774V5.61213C57.4774 3.69451 58.8956 2.74902 60.5136 2.74902C60.9131 2.74902 61.2593 2.78897 61.539 2.84224C61.9651 2.9288 62.1116 3.2484 61.9917 3.66122L61.8919 4.01412C61.7787 4.42028 61.5656 4.57342 61.2726 4.52015C61.1395 4.49352 60.993 4.4802 60.8199 4.4802C59.8477 4.4802 59.4749 4.97292 59.4749 5.87846V6.79732H61.013C61.4457 6.79732 61.6788 7.03036 61.6788 7.46316V7.72949Z"/>
+      </svg>
+    </a>
+  </body>
+</html>

package/dist/templates/frontend/src/entry-client.tsx

@@ -0,0 +1,109 @@
+import './index.css'
+
+// ---------------------------------------------------------------------------
+// Cold-start guard: verify React is real BEFORE rendering.
+//
+// During Vite dep-optimization (cold start or after `npm install <pkg>`),
+// Vite may serve placeholder "stub" modules where all React exports are
+// undefined.  Rendering with stub hooks causes "Cannot read properties of
+// null (reading 'useState')".
+//
+// Strategy:
+//   1. Dynamic-import React and check if useState is a function.
+//   2. If stub  → show a loading banner, schedule a reload with increasing
+//      delay, and do NOT mount any React tree (avoids the error entirely).
+//   3. If real  → dynamic-import App/ErrorBoundary and render normally.
+//   4. Use createElement (not JSX) in this file so Vite doesn't inject a
+//      static `import { jsx } from 'react/jsx-dev-runtime'` which would
+//      itself be a stub and crash before our guard runs.
+// ---------------------------------------------------------------------------
+
+const RELOAD_KEY = '__dep_reload'
+const MAX_RELOADS = 6
+const RELOAD_WINDOW = 60_000 // 1 minute
+
+function getReloads(): { c: number; t: number } {
+  try {
+    return JSON.parse(sessionStorage.getItem(RELOAD_KEY) || '{}') as { c: number; t: number }
+  } catch { return { c: 0, t: 0 } }
+}
+
+async function boot() {
+  const root = document.getElementById('root')!
+
+  try {
+    const React = await import('react')
+
+    // If useState is not a function, React is a dep-optimization stub
+    if (typeof React.useState !== 'function') throw new Error('dep-stub')
+
+    const { createElement } = React
+    const { createRoot, hydrateRoot } = await import('react-dom/client')
+    const { QueryClient, QueryClientProvider } = await import('@tanstack/react-query')
+    const { default: App } = await import('./App')
+
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: {
+        refetchOnWindowFocus: false,
+        retry: 3,
+        retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 10000),
+        staleTime: 30_000,
+      } },
+    })
+
+    const children = createElement(QueryClientProvider, { client: queryClient },
+      createElement(App)
+    )
+
+    // Use hydrateRoot only when SSR rendered real app content. The scaffold's
+    // server entry intentionally returns a lightweight placeholder shell so
+    // SSR-incompatible libraries (for example echarts-for-react) cannot crash
+    // deploy-time render. Placeholder markup must be client-rendered, not hydrated.
+    const hasPlaceholder = !!root.querySelector('[data-surf-placeholder]')
+    if (root.childNodes.length > 0 && root.innerHTML !== '<!--ssr-outlet-->' && !hasPlaceholder) {
+      hydrateRoot(root, children)
+    } else {
+      root.innerHTML = ''
+      createRoot(root).render(children)
+    }
+
+    // React rendered successfully — signal to index.html fallback & reset counter
+    ;(window as any).__reactOk = true
+    sessionStorage.removeItem(RELOAD_KEY)
+
+    // Notify parent frame when real app content renders (not the placeholder).
+    // DO NOT REMOVE — the hosting app uses this to dismiss the loading overlay.
+    function notifyParentReady() {
+      if (!document.querySelector('[data-surf-placeholder]')) {
+        try { window.parent.postMessage({ type: 'surf-app-ready' }, '*') } catch { /* cross-origin — ignore */ }
+      }
+    }
+    notifyParentReady()
+    new MutationObserver(notifyParentReady).observe(root, { childList: true, subtree: true })
+  } catch {
+    // React is not ready — show loading banner and schedule reload
+    const prev = getReloads()
+    const count = (Date.now() - prev.t > RELOAD_WINDOW) ? 0 : prev.c
+
+    if (count < MAX_RELOADS) {
+      root.innerHTML = [
+        '<div style=\"padding:24px;text-align:center;font-family:system-ui,sans-serif\">',
+        '<p style=\"color:#3b82f6;font-weight:600;margin:0 0 4px\">Loading dependencies...</p>',
+        '<p style=\"color:#3b82f6;opacity:0.7;font-size:12px;margin:0\">Reloading automatically</p>',
+        '</div>',
+      ].join('')
+      sessionStorage.setItem(RELOAD_KEY, JSON.stringify({ c: count + 1, t: Date.now() }))
+      // Increasing delay: 3s, 4s, 5s, ... gives Vite more time to finish
+      setTimeout(() => location.reload(), 3000 + count * 1000)
+    } else {
+      root.innerHTML = [
+        '<div style=\"padding:24px;text-align:center;font-family:system-ui,sans-serif\">',
+        '<p style=\"color:#c0392b;font-weight:600;margin:0 0 4px\">Failed to load dependencies</p>',
+        '<p style=\"color:#c0392b;opacity:0.8;font-size:12px;margin:0\">Please refresh the page</p>',
+        '</div>',
+      ].join('')
+    }
+  }
+}
+
+boot()

package/dist/templates/frontend/src/entry-server.tsx

@@ -0,0 +1,13 @@
+import { renderToString } from 'react-dom/server'
+
+export function render() {
+  return renderToString(
+    <div
+      data-surf-placeholder
+      style={{
+        minHeight: '100vh',
+        background: '#ffffff',
+      }}
+    />
+  )
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "create-surf-app",
+  "version": "0.1.0",
+  "description": "Scaffold a Surf app — Vite + React + Express + @surf-ai/sdk",
+  "type": "module",
+  "bin": {
+    "create-surf-app": "./dist/index.js"
+  },
+  "files": ["dist", "templates"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean && rm -rf dist/templates && cp -r templates dist/templates",
+    "dev": "tsup src/index.ts --format esm --watch"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/backend/eslint.config.mjs

@@ -0,0 +1,21 @@
+import js from '@eslint/js';
+import globals from 'globals';
+
+export default [
+  { ignores: ['node_modules'] },
+  {
+    files: ['**/*.js'],
+    ...js.configs.recommended,
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'commonjs',
+      globals: globals.node,
+    },
+    rules: {
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      'no-empty': 'warn',
+      'eqeqeq': 'warn',
+      'no-fallthrough': 'warn',
+    },
+  },
+];

package/templates/frontend/eslint.config.js

@@ -0,0 +1,42 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  { ignores: ['dist', 'node_modules'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.{js,jsx,ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+      parserOptions: {
+        ecmaFeatures: { jsx: true },
+      },
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+      'no-unused-vars': 'off',
+      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-empty-object-type': 'warn',
+      '@typescript-eslint/ban-ts-comment': 'warn',
+      '@typescript-eslint/no-require-imports': 'off',
+      '@typescript-eslint/no-unused-expressions': 'warn',
+      '@typescript-eslint/no-unsafe-function-type': 'warn',
+    },
+  },
+)

package/templates/frontend/index.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="/favicon.ico" />
+    <title>App</title>
+  </head>
+  <body>
+    <div id="root"><!--ssr-outlet--></div>
+    <script type="module" src="./src/entry-client.tsx"></script>
+    <script>
+      // Fallback: if React fails to render (e.g. Vite dep stubs during cold
+      // start), auto-reload until deps are ready.  This fires OUTSIDE React
+      // so it works even when React itself is null/undefined.
+      (function(){
+        var K='__boot_reload', W=30000, M=8;
+        function st(){try{return JSON.parse(sessionStorage.getItem(K))||{c:0,t:0}}catch(e){return{c:0,t:0}}}
+        setTimeout(function(){
+          if(window.__reactOk)return;
+          var s=st(),c=(Date.now()-s.t>W)?0:s.c;
+          if(c<M){sessionStorage.setItem(K,JSON.stringify({c:c+1,t:Date.now()}));location.reload()}
+        },3000);
+      })();
+    </script>
+    <!-- Made by Surf badge -->
+    <style>
+    #surf-badge{position:fixed;bottom:16px;right:16px;z-index:2147483647;display:inline-flex;align-items:center;gap:4px;padding:4px 12px;border-radius:20px;font-family:"Lato",system-ui,sans-serif;font-size:12px;font-weight:500;line-height:16px;text-decoration:none;box-shadow:0 1px 1px rgba(51,51,51,.08),0 6px 12px rgba(51,51,51,.08);opacity:.9;transition:opacity .2s}
+    #surf-badge:hover{opacity:1}
+    @media print{#surf-badge{display:none}}
+    </style>
+    <a id="surf-badge" href="https://asksurf.ai" target="_blank" rel="noopener noreferrer" aria-label="Made by Surf" style="background:var(--bg-menu,#fff);color:var(--fg-base,#212121)">
+      <span>Made by</span>
+      <svg width="40" height="13" viewBox="0 0 63 20" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+        <path d="M15.583 13.333C15.9931 13.3331 16.3814 13.5196 16.6377 13.8398L18.7666 16.5019C18.7956 16.5382 18.8261 16.5719 18.8574 16.6035C19.2049 16.954 19.6484 17.3405 19.6484 17.834C19.6484 18.3399 19.2383 18.75 18.7324 18.75H18.4668C18.1079 18.75 17.7682 18.5868 17.5439 18.3066L16.3633 16.831C15.6565 15.9476 14.2315 16.4477 14.2314 17.5791V18.6494C14.2314 18.7061 14.1827 18.7499 14.126 18.75H12.2529C11.6074 18.75 10.997 18.4562 10.5938 17.9521L9.69629 16.831C8.98948 15.9478 7.56544 16.4478 7.56543 17.5791V18.6494C7.56542 18.7062 7.51669 18.7499 7.45996 18.75H5.58594C4.94038 18.7499 4.32999 18.4563 3.92676 17.9521L3.03027 16.831C2.67436 16.3862 2.14844 15.9311 2.14844 15.3613V13.4385C2.14851 13.3817 2.19228 13.333 2.24902 13.333C2.65919 13.333 3.04737 13.5197 3.30371 13.8398L5.43359 16.5019C6.14031 17.3853 7.56521 16.8861 7.56543 15.7549V14.6846C7.56543 13.9385 8.16998 13.333 8.91602 13.333C9.32621 13.333 9.71437 13.5196 9.9707 13.8398L12.1006 16.5019C12.8052 17.3827 14.2227 16.8887 14.2314 15.7646V14.6846C14.2314 13.9385 14.837 13.333 15.583 13.333ZM15.583 6.66698C15.9932 6.66711 16.3814 6.8535 16.6377 7.17382L18.7666 9.83593C19.1224 10.2806 19.6484 10.7352 19.6484 11.3047V13.2266C19.6483 13.2833 19.6046 13.333 19.5479 13.333C19.1375 13.333 18.7495 13.1466 18.4932 12.8262L16.3633 10.1641C15.6565 9.28087 14.2315 9.78081 14.2314 10.9121V11.9824C14.2314 12.7284 13.6269 13.333 12.8809 13.333C12.4706 13.3329 12.0825 13.1465 11.8262 12.8262L9.69629 10.1641C8.98942 9.28109 7.56544 9.78088 7.56543 10.9121V11.9824C7.56543 12.7282 6.96062 13.3327 6.21484 13.333C5.80451 13.333 5.41551 13.1466 5.15918 12.8262L3.03027 10.1641C2.67435 9.71918 2.14844 9.26406 2.14844 8.69433V6.77245C2.14851 6.71573 2.19228 6.66699 2.24902 6.66698C2.65936 6.66698 3.04738 6.8534 3.30371 7.17382L5.43359 9.83593C6.14042 10.7191 7.56543 10.2192 7.56543 9.08788V8.01757C7.56543 7.27154 8.16998 6.66698 8.91602 6.66698C9.32634 6.66701 9.71437 6.85341 9.9707 7.17382L12.1006 9.83593C12.8052 10.7162 14.2225 10.2223 14.2314 9.09863V8.01757C14.2314 7.27154 14.837 6.66698 15.583 6.66698ZM3.33008 1.24999C3.68899 1.24999 4.02863 1.41318 4.25293 1.69335L5.43359 3.16894C6.14036 4.0524 7.56543 3.55227 7.56543 2.42089V1.35058C7.56544 1.29384 7.61417 1.25007 7.6709 1.24999H9.54395C10.1895 1.24999 10.7999 1.54378 11.2031 2.04784L12.1006 3.16894C12.8052 4.04953 14.2227 3.5556 14.2314 2.43163V1.35058C14.2315 1.29384 14.2802 1.25007 14.3369 1.24999H16.2109C16.8565 1.25014 17.4669 1.54375 17.8701 2.04784L18.7666 3.16894C19.1223 3.61354 19.6481 4.06741 19.6484 4.63671V6.56054C19.6483 6.61728 19.6046 6.66698 19.5479 6.66698C19.1377 6.66698 18.7495 6.48034 18.4932 6.16015L16.3633 3.49804C15.6566 2.61465 14.2317 3.11391 14.2314 4.24511V5.3164C14.2312 6.06217 13.6267 6.66698 12.8809 6.66698C12.4707 6.66693 12.0825 6.48039 11.8262 6.16015L9.69629 3.49804C8.98957 2.61465 7.56565 3.11391 7.56543 4.24511V5.3164C7.56518 6.06202 6.96046 6.66673 6.21484 6.66698C5.80453 6.66698 5.41551 6.48054 5.15918 6.16015L3.03027 3.49804C3.00109 3.46156 2.97093 3.42724 2.93945 3.3955C2.59217 3.04543 2.14867 2.65906 2.14844 2.16601C2.14844 1.66032 2.55877 1.24999 3.06445 1.24999H3.33008Z"/>
+        <path d="M35.1083 6.97044C34.7154 6.97044 34.5223 6.77734 34.3692 6.39782C33.9963 5.49228 33.0042 4.97958 31.6925 4.97958C30.0146 4.97958 28.9559 5.83851 28.9559 6.99707C28.9493 8.30211 30.3675 8.80149 31.4328 9.07449L32.7645 9.42072C34.4957 9.84686 36.6863 10.799 36.6863 13.2559C36.6863 15.5664 34.8419 17.251 31.6392 17.251C28.8827 17.251 27.0649 16.0125 26.6321 13.9617C26.5389 13.5156 26.7986 13.2559 27.2514 13.2559H27.9971C28.3966 13.2559 28.5897 13.4557 28.7229 13.8485C29.1024 14.9272 30.2676 15.4466 31.6259 15.4466C33.3771 15.4466 34.6488 14.5676 34.6488 13.236C34.6488 12.0241 33.5236 11.5447 32.0654 11.1586L30.454 10.7191C28.2634 10.1265 26.9051 9.01456 26.9051 7.11692C26.9051 4.76651 29.0025 3.20179 31.7391 3.20179C34.2027 3.20179 36.0005 4.45357 36.4133 6.27131C36.5132 6.71076 36.2335 6.97044 35.7874 6.97044H35.1083Z"/>
+        <path d="M45.0887 7.46316C45.0887 7.03036 45.3217 6.79732 45.7545 6.79732H46.4204C46.8532 6.79732 47.0862 7.03036 47.0862 7.46316V16.3588C47.0862 16.7915 46.8532 17.0246 46.4204 17.0246H45.7945C45.3617 17.0246 45.1286 16.7915 45.1286 16.3588V15.2535H45.0221C44.5494 16.3454 43.504 17.1578 41.9659 17.1578C40.0017 17.1578 38.6101 15.8394 38.6101 13.3026V7.46316C38.6101 7.03036 38.8431 6.79732 39.2759 6.79732H39.9351C40.3679 6.79732 40.601 7.03036 40.601 7.46316V13.0629C40.601 14.4545 41.4532 15.3467 42.685 15.3467C43.8036 15.3467 45.0954 14.521 45.0887 12.7832V7.46316Z"/>
+        <path d="M49.3862 7.46316C49.3862 7.03036 49.6193 6.79732 50.0521 6.79732H50.6447C51.0774 6.79732 51.3105 7.03036 51.3105 7.46316V8.42196H51.417C51.7899 7.32333 52.8153 6.64418 54.0138 6.64418C54.0737 6.64418 54.147 6.64418 54.2202 6.65084C54.6397 6.65749 54.8594 6.91717 54.8594 7.33665V7.88264C54.8594 8.33541 54.673 8.54182 54.3467 8.50852C54.1803 8.48855 53.9938 8.47523 53.8207 8.47523C52.4091 8.47523 51.3771 9.4407 51.3771 10.779V16.3588C51.3771 16.7915 51.144 17.0246 50.7112 17.0246H50.0521C49.6193 17.0246 49.3862 16.7915 49.3862 16.3588V7.46316Z"/>
+        <path d="M61.6788 7.72949C61.6788 8.16229 61.4457 8.39533 61.013 8.39533H59.4749V16.3588C59.4749 16.7915 59.2418 17.0246 58.809 17.0246H58.1432C57.7104 17.0246 57.4774 16.7915 57.4774 16.3588V8.39533H56.5652C56.1324 8.39533 55.8993 8.16229 55.8993 7.72949V7.46316C55.8993 7.03036 56.1324 6.79732 56.5652 6.79732H57.4774V5.61213C57.4774 3.69451 58.8956 2.74902 60.5136 2.74902C60.9131 2.74902 61.2593 2.78897 61.539 2.84224C61.9651 2.9288 62.1116 3.2484 61.9917 3.66122L61.8919 4.01412C61.7787 4.42028 61.5656 4.57342 61.2726 4.52015C61.1395 4.49352 60.993 4.4802 60.8199 4.4802C59.8477 4.4802 59.4749 4.97292 59.4749 5.87846V6.79732H61.013C61.4457 6.79732 61.6788 7.03036 61.6788 7.46316V7.72949Z"/>
+      </svg>
+    </a>
+  </body>
+</html>

package/templates/frontend/src/entry-client.tsx

@@ -0,0 +1,109 @@
+import './index.css'
+
+// ---------------------------------------------------------------------------
+// Cold-start guard: verify React is real BEFORE rendering.
+//
+// During Vite dep-optimization (cold start or after `npm install <pkg>`),
+// Vite may serve placeholder "stub" modules where all React exports are
+// undefined.  Rendering with stub hooks causes "Cannot read properties of
+// null (reading 'useState')".
+//
+// Strategy:
+//   1. Dynamic-import React and check if useState is a function.
+//   2. If stub  → show a loading banner, schedule a reload with increasing
+//      delay, and do NOT mount any React tree (avoids the error entirely).
+//   3. If real  → dynamic-import App/ErrorBoundary and render normally.
+//   4. Use createElement (not JSX) in this file so Vite doesn't inject a
+//      static `import { jsx } from 'react/jsx-dev-runtime'` which would
+//      itself be a stub and crash before our guard runs.
+// ---------------------------------------------------------------------------
+
+const RELOAD_KEY = '__dep_reload'
+const MAX_RELOADS = 6
+const RELOAD_WINDOW = 60_000 // 1 minute
+
+function getReloads(): { c: number; t: number } {
+  try {
+    return JSON.parse(sessionStorage.getItem(RELOAD_KEY) || '{}') as { c: number; t: number }
+  } catch { return { c: 0, t: 0 } }
+}
+
+async function boot() {
+  const root = document.getElementById('root')!
+
+  try {
+    const React = await import('react')
+
+    // If useState is not a function, React is a dep-optimization stub
+    if (typeof React.useState !== 'function') throw new Error('dep-stub')
+
+    const { createElement } = React
+    const { createRoot, hydrateRoot } = await import('react-dom/client')
+    const { QueryClient, QueryClientProvider } = await import('@tanstack/react-query')
+    const { default: App } = await import('./App')
+
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: {
+        refetchOnWindowFocus: false,
+        retry: 3,
+        retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 10000),
+        staleTime: 30_000,
+      } },
+    })
+
+    const children = createElement(QueryClientProvider, { client: queryClient },
+      createElement(App)
+    )
+
+    // Use hydrateRoot only when SSR rendered real app content. The scaffold's
+    // server entry intentionally returns a lightweight placeholder shell so
+    // SSR-incompatible libraries (for example echarts-for-react) cannot crash
+    // deploy-time render. Placeholder markup must be client-rendered, not hydrated.
+    const hasPlaceholder = !!root.querySelector('[data-surf-placeholder]')
+    if (root.childNodes.length > 0 && root.innerHTML !== '<!--ssr-outlet-->' && !hasPlaceholder) {
+      hydrateRoot(root, children)
+    } else {
+      root.innerHTML = ''
+      createRoot(root).render(children)
+    }
+
+    // React rendered successfully — signal to index.html fallback & reset counter
+    ;(window as any).__reactOk = true
+    sessionStorage.removeItem(RELOAD_KEY)
+
+    // Notify parent frame when real app content renders (not the placeholder).
+    // DO NOT REMOVE — the hosting app uses this to dismiss the loading overlay.
+    function notifyParentReady() {
+      if (!document.querySelector('[data-surf-placeholder]')) {
+        try { window.parent.postMessage({ type: 'surf-app-ready' }, '*') } catch { /* cross-origin — ignore */ }
+      }
+    }
+    notifyParentReady()
+    new MutationObserver(notifyParentReady).observe(root, { childList: true, subtree: true })
+  } catch {
+    // React is not ready — show loading banner and schedule reload
+    const prev = getReloads()
+    const count = (Date.now() - prev.t > RELOAD_WINDOW) ? 0 : prev.c
+
+    if (count < MAX_RELOADS) {
+      root.innerHTML = [
+        '<div style=\"padding:24px;text-align:center;font-family:system-ui,sans-serif\">',
+        '<p style=\"color:#3b82f6;font-weight:600;margin:0 0 4px\">Loading dependencies...</p>',
+        '<p style=\"color:#3b82f6;opacity:0.7;font-size:12px;margin:0\">Reloading automatically</p>',
+        '</div>',
+      ].join('')
+      sessionStorage.setItem(RELOAD_KEY, JSON.stringify({ c: count + 1, t: Date.now() }))
+      // Increasing delay: 3s, 4s, 5s, ... gives Vite more time to finish
+      setTimeout(() => location.reload(), 3000 + count * 1000)
+    } else {
+      root.innerHTML = [
+        '<div style=\"padding:24px;text-align:center;font-family:system-ui,sans-serif\">',
+        '<p style=\"color:#c0392b;font-weight:600;margin:0 0 4px\">Failed to load dependencies</p>',
+        '<p style=\"color:#c0392b;opacity:0.8;font-size:12px;margin:0\">Please refresh the page</p>',
+        '</div>',
+      ].join('')
+    }
+  }
+}
+
+boot()

package/templates/frontend/src/entry-server.tsx

@@ -0,0 +1,13 @@
+import { renderToString } from 'react-dom/server'
+
+export function render() {
+  return renderToString(
+    <div
+      data-surf-placeholder
+      style={{
+        minHeight: '100vh',
+        background: '#ffffff',
+      }}
+    />
+  )
+}