npm - weifuwu - Versions diffs - 0.27.5 → 0.27.7 - Mend

weifuwu 0.27.5 → 0.27.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md CHANGED Viewed

@@ -63,6 +63,137 @@ app.use(rateLimit({ window: 60 }))
 ---
+## Full-stack SSR
+Server-rendered HTML with zero frontend build tools. Uses `html()` tagged templates
+for safe HTML rendering, HTMX for dynamic interactions, and Alpine.js for client-side state.
+```ts
+import { Router, serve, html, raw, layout, view, cssContext, cssRouter, assetRouter } from 'weifuwu'
+const app = new Router()
+// Middleware
+app.use(theme())
+app.use(i18n({ dir: './locales' }))
+app.use(cssContext('./ui')) // compile globals.css → ctx.css
+// Layout (wraps all pages)
+app.use(layout('./ui/app/layout.ts'))
+// Static assets (HTMX, Alpine — served locally, no CDN)
+app.use(assetRouter())
+// CSS serving
+app.use('/', cssRouter('./ui'))
+// Page
+app.get('/', view('./ui/app/page.ts'))
+// HTMX fragment handler
+app.get('/users/table', async (req, ctx) => {
+  const users = await ctx.sql`SELECT * FROM users`
+  return html`${users.map((u) => html`<div>${u.name}</div>`)}`
+})
+// API
+app.get('/api/ping', () => Response.json({ pong: true }))
+serve(app.handler(), { port: 3000 })
+```
+### html() — Tagged template HTML
+Safe HTML rendering with automatic escaping. Zero dependencies — uses JavaScript
+tagged template literals.
+```ts
+import { html, raw } from 'weifuwu'
+// Auto-escaped
+html`<h1>${userInput}</h1>`
+// `<h1>&lt;script&gt;...&lt;/script&gt;</h1>`
+// raw() bypasses escaping (for trusted HTML)
+html`<div>${raw(body)}</div>`
+// Arrays (from map)
+html`<ul>
+  ${items.map((i) => html`<li>${i}</li>`)}
+</ul>`
+// Conditionals
+html`${isAdmin && html`<button>Admin</button>`}`
+// Nested html() is safe from double-escaping
+html`<div>${html`<span>nested</span>`}</div>`
+```
+### layout() — Layout middleware
+Wraps page HTML in a layout template. Multiple layouts nest naturally.
+```ts
+import { html, raw } from 'weifuwu'
+// ui/app/layout.ts
+export default function (body: string, ctx: any) {
+  return html`<!DOCTYPE html>
+    <html>
+      <head>
+        <meta charset="utf-8" />
+        <script src="/__wfw/js/htmx.min.js"></script>
+        <script defer src="/__wfw/js/alpine.min.js"></script>
+      </head>
+      <body class="min-h-screen bg-white dark:bg-gray-950">
+        ${raw(body)}
+        <!-- ← use raw() for page content -->
+      </body>
+    </html>`
+}
+```
+### view() — Page handler factory
+Loads a `.ts` file and calls its default export to produce an HTML Response.
+```ts
+// app.ts
+app.get('/', view('./ui/app/page.ts'))
+// ui/app/page.ts
+export default function (ctx: any) {
+  return html`<h1 class="text-3xl font-bold">${ctx.i18n?.t('title')}</h1>`
+}
+```
+### CSS pipeline (Tailwind v4)
+Compiles `globals.css` via `@tailwindcss/postcss`. Cached and served with content hash.
+```css
+/* ui/app/globals.css */
+@import 'tailwindcss';
+@custom-variant dark (&:is(.dark *));
+```
+```ts
+app.use(cssContext('./ui')) // compile → ctx.css.url
+app.use(cssRouter('./ui')) // serve /__wfw/style/:hash.css
+```
+### Local assets (no CDN)
+HTMX and Alpine.js are npm dependencies, served from the weifuwu server.
+No external network requests.
+```ts
+app.use(assetRouter()) // serve /__wfw/js/htmx.min.js, alpine.min.js
+// In layout: ${assetScripts()}
+```
+---
 ## Public API
 ### serve
@@ -405,6 +536,57 @@ app.use(i18n({ dir: './locales', defaultLocale: 'en' }))
 Options: `dir`, `defaultLocale`, `cookie`, `param`, `header`
+### SSR utilities
+#### html()
+Tagged template literal for safe HTML. See [Full-stack SSR](#full-stack-ssr).
+```ts
+import { html, raw } from 'weifuwu'
+html`<h1>${title}</h1>` // auto-escaped
+html`<div>${raw(html)}</div>` // unescaped
+```
+#### layout()
+Middleware that wraps page content in a layout template.
+```ts
+import { layout } from 'weifuwu'
+app.use(layout('./ui/app/layout.ts'))
+```
+#### view()
+Handler factory that loads a `.ts` file as a page.
+```ts
+import { view } from 'weifuwu'
+app.get('/', view('./ui/app/page.ts'))
+```
+#### cssContext() / cssRouter()
+Tailwind v4 CSS compilation and serving.
+```ts
+import { cssContext, cssRouter } from 'weifuwu'
+app.use(cssContext('./ui')) // compile → ctx.css
+app.use(cssRouter('./ui')) // serve /__wfw/style/:hash.css
+```
+#### assetRouter() / assetScripts()
+Serve HTMX and Alpine.js from node_modules (no CDN).
+```ts
+import { assetRouter, assetScripts } from 'weifuwu'
+app.use(assetRouter())
+// In layout: ${assetScripts()}
+```
 ### Standalone utilities
 #### SSE
@@ -484,17 +666,42 @@ throw new HttpError('Not found', 404) // caught by serve(), returns 404
 ## CLI
 ```bash
-npx weifuwu init my-api
-cd my-api
-npm run dev
+npx weifuwu init my-app              # Full-stack project (SSR + Tailwind + HTMX + Alpine)
+npx weifuwu init my-app --minimal    # Minimal API-only project
+npx weifuwu version                   # Print version
 ```
+### Full-stack template (`init`)
+Generates a complete project with SSR, Tailwind CSS compilation, HTMX + Alpine served
+locally, theme switching, internationalization, and a demo home page.
+```
+my-app/
+  index.ts              — server entry
+  app.ts                — Router setup
+  ui/
+    app/
+      globals.css       — Tailwind v4
+      layout.ts         — root layout (HTMX + Alpine + theme script)
+      page.ts           — home page (theme/i18n demo)
+  locales/
+    en.json
+    zh-CN.json
+  package.json
+  tsconfig.json         — with @/ path alias
+```
+### Minimal template (`init --minimal`)
 Creates a minimal API project with `app.ts`, `index.ts`, and TypeScript config.
 ---
 ## Dependencies
+### Backend
 - `postgres` — PostgreSQL client
 - `ioredis` — Redis client
 - `ai`, `@ai-sdk/openai` — AI SDK
@@ -502,4 +709,10 @@ Creates a minimal API project with `app.ts`, `index.ts`, and TypeScript config.
 - `ws` — WebSocket
 - `zod` — Schema validation
-Zero build tools. Zero frontend framework dependencies.
+### Frontend (served locally, no CDN)
+- `tailwindcss`, `@tailwindcss/postcss`, `postcss` — Tailwind v4 CSS compilation
+- `htmx.org` — HTML-over-the-wire dynamic interactions
+- `alpinejs` — Lightweight client interactivity
+Zero build tools. Zero frontend framework compilation.

package/dist/cli.js CHANGED Viewed

@@ -28,6 +28,13 @@ async function cmdInit(name, opts) {
     process.exit(1);
   }
   const pkg = await readPkg();
+  if (opts.minimal) {
+    await generateMinimal(targetDir, name, pkg.version, opts.skipInstall);
+  } else {
+    await generateFull(targetDir, name, pkg.version, opts.skipInstall);
+  }
+}
+async function generateMinimal(targetDir, name, version, skipInstall) {
   await mkdir(targetDir, { recursive: true });
   await writeFile(
     join(targetDir, "app.ts"),
@@ -53,24 +60,208 @@ async function cmdInit(name, opts) {
       ``
     ].join("\n")
   );
+  await writePackageJson(targetDir, name, version, {});
+  await writeCommonFiles(targetDir);
+  await finishInit(targetDir, skipInstall);
+}
+async function generateFull(targetDir, name, version, skipInstall) {
+  await mkdir(targetDir, { recursive: true });
+  await mkdir(join(targetDir, "ui", "app"), { recursive: true });
+  await mkdir(join(targetDir, "ui", "lib"), { recursive: true });
+  await mkdir(join(targetDir, "locales"), { recursive: true });
+  await writeFile(
+    join(targetDir, "app.ts"),
+    [
+      `import { Router, layout, view, theme, i18n, cssContext, cssRouter, assetRouter } from 'weifuwu'`,
+      ``,
+      `export const app = new Router()`,
+      ``,
+      `// Middleware`,
+      `app.use(theme())`,
+      `app.use(i18n({ dir: './locales' }))`,
+      `app.use(cssContext('./ui'))`,
+      ``,
+      `// Layout \u2014 wraps all pages`,
+      `app.use(layout('./ui/app/layout.ts'))`,
+      ``,
+      `// Static assets (HTMX, Alpine)`,
+      `app.use('/', assetRouter())`,
+      ``,
+      `// CSS serving`,
+      `app.use('/', cssRouter('./ui'))`,
+      ``,
+      `// Pages`,
+      `app.get('/', view('./ui/app/page.ts'))`,
+      ``,
+      `// API route`,
+      `app.get('/api/ping', () => Response.json({ pong: true, time: new Date().toISOString() }))`,
+      ``
+    ].join("\n")
+  );
+  await writeFile(
+    join(targetDir, "index.ts"),
+    [
+      `import { loadEnv, serve } from 'weifuwu'`,
+      `import { app } from './app.ts'`,
+      ``,
+      `loadEnv()`,
+      `const port = Number(process.env.PORT) || 3000`,
+      `serve(app.handler(), { port })`,
+      ``
+    ].join("\n")
+  );
   await writeFile(
-    join(targetDir, "package.json"),
+    join(targetDir, "ui", "app", "globals.css"),
+    [`@import "tailwindcss";`, `@custom-variant dark (&:is(.dark *));`, ``].join("\n")
+  );
+  await writeFile(
+    join(targetDir, "ui", "app", "layout.ts"),
+    [
+      `import { html, raw, assetScripts } from 'weifuwu'`,
+      ``,
+      `export default function(body: string, ctx: any) {`,
+      `  // Theme: resolve before paint to prevent flash`,
+      `  const themeScript = raw(\`<script>`,
+      `!function(){`,
+      `var t=(document.cookie.match(/(?:^|;\\s*)theme=([^;]+)/)||[])[1]||'system';`,
+      `if(t==='system')t=window.matchMedia('(prefers-color-scheme:dark)').matches?'dark':'light';`,
+      `document.documentElement.classList.toggle('dark',t==='dark');`,
+      `}()`,
+      `</script>\`)`,
+      ``,
+      `  // i18n: set lang attribute`,
+      `  const lang = ctx.i18n?.locale || 'en'`,
+      ``,
+      `  // CSS: include compiled stylesheet`,
+      `  const cssLink = ctx.css?.url`,
+      `    ? raw(\`<link rel="stylesheet" href="\${ctx.css.url}">\`)`,
+      `    : ''`,
+      ``,
+      `  return html\`<!DOCTYPE html>`,
+      `<html lang="\${lang}">`,
+      `<head>`,
+      `  <meta charset="utf-8" />`,
+      `  <meta name="viewport" content="width=device-width, initial-scale=1" />`,
+      `  \${themeScript}`,
+      `  \${assetScripts()}`,
+      `  \${cssLink}`,
+      `</head>`,
+      `<body class="min-h-screen bg-white text-gray-900 dark:bg-gray-950 dark:text-gray-100">`,
+      `  \${raw(body)}`,
+      `</body>`,
+      `</html>\``,
+      `}`,
+      ``
+    ].join("\n")
+  );
+  await writeFile(
+    join(targetDir, "ui", "app", "page.ts"),
+    [
+      `import { html } from 'weifuwu'`,
+      ``,
+      `export default function(ctx: any) {`,
+      `  const t = ctx.i18n?.t || ((k: string) => k)`,
+      `  const theme = ctx.theme?.value || 'system'`,
+      `  const locale = ctx.i18n?.locale || 'en'`,
+      ``,
+      `  return html\`<div x-data="{ open: false }" class="min-h-screen">`,
+      `    <!-- Navbar -->`,
+      `    <nav class="border-b border-gray-200 dark:border-gray-800">`,
+      `      <div class="max-w-5xl mx-auto flex items-center justify-between h-14 px-4">`,
+      `        <span class="font-bold text-lg">weifuwu</span>`,
+      `        <div class="flex items-center gap-3 text-sm">`,
+      `          <!-- Locale toggle -->`,
+      `          <a href="/__lang/\${locale === 'en' ? 'zh-CN' : 'en'}"`,
+      `             class="px-2 py-1 rounded border border-gray-300 dark:border-gray-600`,
+      `                    hover:bg-gray-100 dark:hover:bg-gray-800 transition">`,
+      `            \${locale === 'en' ? '\u4E2D\u6587' : 'EN'}`,
+      `          </a>`,
+      `          <!-- Theme toggle -->`,
+      `          <a href="/__theme/\${theme === 'dark' ? 'light' : 'dark'}"`,
+      `             class="px-2 py-1 rounded border border-gray-300 dark:border-gray-600`,
+      `                    hover:bg-gray-100 dark:hover:bg-gray-800 transition">`,
+      `            \${theme === 'dark' ? '\u2600\uFE0F' : '\u{1F319}'}`,
+      `          </a>`,
+      `        </div>`,
+      `      </div>`,
+      `    </nav>`,
+      ``,
+      `    <!-- Hero -->`,
+      `    <section class="max-w-3xl mx-auto px-4 py-16 text-center">`,
+      `      <h1 class="text-4xl font-bold tracking-tight mb-3">\${t('hero.title')}</h1>`,
+      `      <p class="text-gray-500 dark:text-gray-400 text-lg mb-8">`,
+      `        Pure Node.js, no build step`,
+      `      </p>`,
+      ``,
+      `      <div class="flex justify-center gap-3">`,
+      `        <button @click="open = !open"`,
+      `                class="rounded-md bg-gray-900 px-4 py-2 text-sm font-medium text-white`,
+      `                       hover:bg-gray-700 dark:bg-gray-100 dark:text-gray-900 dark:hover:bg-gray-300">`,
+      `          \${t('hero.cta')}`,
+      `        </button>`,
+      `        <a href="/docs"`,
+      `           class="rounded-md border border-gray-300 px-4 py-2 text-sm font-medium`,
+      `                  hover:bg-gray-100 dark:border-gray-600 dark:hover:bg-gray-800">`,
+      `          \${t('hero.docs')}`,
+      `        </a>`,
+      `      </div>`,
+      ``,
+      `      <!-- Alpine demo: click to reveal -->`,
+      `      <div x-show="open" x-cloak`,
+      `           class="mt-6 p-4 bg-gray-100 dark:bg-gray-800 rounded-lg text-sm text-left">`,
+      `        \${t('demo.alpine')}`,
+      `      </div>`,
+      `    </section>`,
+      `  </div>\``,
+      `}`,
+      ``
+    ].join("\n")
+  );
+  await writeFile(
+    join(targetDir, "ui", "lib", "utils.ts"),
+    [
+      `/**`,
+      ` * cn() \u2014 Merge class names, handling conditional and array inputs.`,
+      ` * Lightweight alternative to clsx + tailwind-merge.`,
+      ` */`,
+      `export function cn(...classes: (string | false | null | undefined)[]): string {`,
+      `  return classes.filter(Boolean).join(' ')`,
+      `}`,
+      ``
+    ].join("\n")
+  );
+  await writeFile(
+    join(targetDir, "locales", "en.json"),
     JSON.stringify(
       {
-        name,
-        type: "module",
-        scripts: {
-          dev: "node --watch index.ts",
-          start: "node index.ts"
-        },
-        dependencies: {
-          weifuwu: `^${pkg.version}`
-        }
+        "hero.title": "Build APIs & UI, Zero Build Step",
+        "hero.cta": "Try Alpine",
+        "hero.docs": "Documentation",
+        "demo.alpine": "This is Alpine.js in action \u2014 click-toggled content, zero JavaScript written."
+      },
+      null,
+      2
+    ) + "\n"
+  );
+  await writeFile(
+    join(targetDir, "locales", "zh-CN.json"),
+    JSON.stringify(
+      {
+        "hero.title": "\u96F6\u7F16\u8BD1\u6784\u5EFA API \u548C UI",
+        "hero.cta": "\u4F53\u9A8C Alpine",
+        "hero.docs": "\u6587\u6863",
+        "demo.alpine": "\u8FD9\u662F Alpine.js \u7684\u6F14\u793A\u2014\u2014\u70B9\u51FB\u5207\u6362\u5185\u5BB9\uFF0C\u4E0D\u9700\u8981\u5199 JavaScript\u3002"
       },
       null,
       2
     ) + "\n"
   );
+  await writePackageJson(targetDir, name, version, {
+    dependencies: {
+      weifuwu: `^${version}`
+    },
+    devDependencies: {}
+  });
   await writeFile(
     join(targetDir, "tsconfig.json"),
     JSON.stringify(
@@ -82,37 +273,45 @@ async function cmdInit(name, opts) {
           strict: true,
           skipLibCheck: true,
           noEmit: true,
-          allowImportingTsExtensions: true
+          allowImportingTsExtensions: true,
+          paths: {
+            "@/*": ["./ui/*"]
+          }
         },
-        include: ["*.ts"]
+        include: ["*.ts", "ui/**/*.ts"]
       },
       null,
       2
     ) + "\n"
   );
-  await writeFile(join(targetDir, ".gitignore"), "node_modules\n.env\n");
+  await writeCommonFiles(targetDir);
+  await finishInit(targetDir, skipInstall);
+}
+async function writePackageJson(targetDir, name, version, extra) {
+  const pkg = {
+    name,
+    type: "module",
+    scripts: {
+      dev: "node --watch index.ts",
+      start: "node index.ts"
+    },
+    ...extra
+  };
+  await writeFile(join(targetDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+}
+async function writeCommonFiles(targetDir) {
+  await writeFile(join(targetDir, ".gitignore"), "node_modules\n.env\n.weifuwu\n");
   await writeFile(join(targetDir, ".env"), "PORT=3000\n");
-  await writeFile(
-    join(targetDir, "AGENTS.md"),
-    [
-      "# Project Guide for AI Agents",
-      "",
-      "Before making any changes to this project, first read the weifuwu framework documentation:",
-      "",
-      "./node_modules/weifuwu/README.md",
-      "",
-      "This file contains the framework API reference, conventions, and patterns used throughout the codebase.",
-      ""
-    ].join("\n")
-  );
-  if (!opts.skipInstall) {
+}
+async function finishInit(targetDir, skipInstall) {
+  if (!skipInstall) {
     console.log("\nInstalling dependencies...");
     execSync("npm install", { cwd: targetDir, stdio: "inherit" });
   }
   console.log(`
-\u2705 Created ${name}/`);
-  console.log(`   cd ${name}`);
-  if (opts.skipInstall) console.log(`   npm install`);
+\u2705 Created ${targetDir.split("/").pop()}/`);
+  console.log(`   cd ${targetDir.split("/").pop()}`);
+  if (skipInstall) console.log(`   npm install`);
   console.log(`   npm run dev`);
 }
 var cmd = process.argv[2];
@@ -120,25 +319,31 @@ var HELP = `
 weifuwu \u2014 Web-standard HTTP microframework for Node.js
 Usage:
-  npx weifuwu init <name>              Create a new project
-  npx weifuwu init <name> --skip-install  Create project, skip npm install
-  npx weifuwu version                  Print version
+  npx weifuwu init <name>               Create a new project (SSR + shadcn UI)
+  npx weifuwu init <name> --minimal     Create a minimal API-only project
+  npx weifuwu init <name> --skip-install  Skip npm install
+  npx weifuwu version                   Print version
 `;
 if (cmd === "version" || cmd === "-v" || cmd === "--version") {
   cmdVersion().catch(console.error);
 } else if (cmd === "init") {
   const { values, positionals } = parseArgs({
     args: process.argv.slice(3),
-    options: { "skip-install": { type: "boolean" } },
+    options: {
+      "skip-install": { type: "boolean" },
+      minimal: { type: "boolean" }
+    },
     strict: false,
     allowPositionals: true
   });
   const name = positionals[0];
   if (!name) {
-    console.error("Usage: npx weifuwu init <name> [--skip-install]");
+    console.error("Usage: npx weifuwu init <name> [--skip-install] [--minimal]");
     process.exit(1);
   }
-  cmdInit(name, { skipInstall: !!values["skip-install"] }).catch(console.error);
+  cmdInit(name, { skipInstall: !!values["skip-install"], minimal: !!values["minimal"] }).catch(
+    console.error
+  );
 } else {
   console.log(HELP);
 }

package/dist/index.d.ts CHANGED Viewed

@@ -57,3 +57,12 @@ export { flash } from './middleware/flash.ts';
 export type { FlashOptions, FlashInjected, FlashModule } from './middleware/flash.ts';
 export { csrf } from './middleware/csrf.ts';
 export type { CsrfOptions, CsrfInjected, CsrfModule } from './middleware/csrf.ts';
+export { html, raw } from './ssr/html.ts';
+export type { RawString } from './ssr/html.ts';
+export { layout } from './ssr/layout.ts';
+export { view } from './ssr/view.ts';
+export type { ViewOptions } from './ssr/view.ts';
+export { loadModule, clearModuleCache } from './ssr/compile.ts';
+export { cssContext, cssRouter, clearCSSCache } from './ssr/css.ts';
+export type { CssAsset } from './ssr/css.ts';
+export { assetRouter, assetScripts } from './ssr/assets.ts';

package/dist/index.js CHANGED Viewed

@@ -293,14 +293,14 @@ function serve(handler, options) {
     if (!server.listening) return;
     server.close();
     server.closeIdleConnections();
-    return new Promise((resolve4) => {
+    return new Promise((resolve8) => {
       const timer = setTimeout(() => {
         server.closeAllConnections();
-        resolve4();
+        resolve8();
       }, timeoutMs);
       server.on("close", () => {
         clearTimeout(timer);
-        resolve4();
+        resolve8();
       });
     });
   }
@@ -345,7 +345,7 @@ function createHub(opts) {
       }
     });
   }
-  function join3(key, ws) {
+  function join4(key, ws) {
     if (!channels.has(key)) {
       channels.set(key, /* @__PURE__ */ new Set());
       redisSub?.subscribe(`${prefix}${key}`);
@@ -407,7 +407,7 @@ function createHub(opts) {
     redisPub = void 0;
     redisSub = null;
   }
-  return { join: join3, leave, broadcast, close };
+  return { join: join4, leave, broadcast, close };
 }
 // core/router.ts
@@ -1960,7 +1960,7 @@ var TestWSRequest = class {
     const baseUrl = await this.app._ensureServer();
     const wsUrl = baseUrl.replace(/^http/, "ws") + this.path;
     const ws = new WSWebSocket(wsUrl, { handshakeTimeout: this._timeout });
-    return new Promise((resolve4, reject) => {
+    return new Promise((resolve8, reject) => {
       const timer = setTimeout(() => {
         reject(new Error(`WebSocket connection timed out after ${this._timeout}ms`));
         ws.close();
@@ -1969,7 +1969,7 @@ var TestWSRequest = class {
         clearTimeout(timer);
         const conn = new TestWSConnection(ws, this._timeout);
         this.app._trackConnection(conn);
-        resolve4(conn);
+        resolve8(conn);
       });
       ws.on("error", (err) => {
         clearTimeout(timer);
@@ -2000,8 +2000,8 @@ var TestWSConnection = class {
     ws.on("message", (data) => {
       const str = data.toString();
       if (this.resolveQueue.length > 0) {
-        const resolve4 = this.resolveQueue.shift();
-        resolve4(str);
+        const resolve8 = this.resolveQueue.shift();
+        resolve8(str);
       } else {
         this.messageQueue.push(str);
       }
@@ -2031,15 +2031,15 @@ var TestWSConnection = class {
     if (this._closed) {
       throw new Error("WebSocket connection closed");
     }
-    return new Promise((resolve4, reject) => {
+    return new Promise((resolve8, reject) => {
       const timer = setTimeout(() => {
-        const idx = this.resolveQueue.indexOf(resolve4);
+        const idx = this.resolveQueue.indexOf(resolve8);
         if (idx !== -1) this.resolveQueue.splice(idx, 1);
         reject(new Error(`WebSocket receive timed out after ${timeout ?? this._timeout}ms`));
       }, timeout ?? this._timeout);
       this.resolveQueue.push((msg) => {
         clearTimeout(timer);
-        resolve4(msg);
+        resolve8(msg);
       });
     });
   }
@@ -2053,12 +2053,12 @@ var TestWSConnection = class {
    * Useful for verifying that something did NOT happen.
    */
   async expectSilent(ms) {
-    return new Promise((resolve4, reject) => {
+    return new Promise((resolve8, reject) => {
       if (this.messageQueue.length > 0) {
         reject(new Error(`Expected silence but got message: ${this.messageQueue[0].slice(0, 100)}`));
         return;
       }
-      const timer = setTimeout(() => resolve4(), ms);
+      const timer = setTimeout(() => resolve8(), ms);
       const origPush = this.resolveQueue.push.bind(this.resolveQueue);
       this.resolveQueue.push = (_fn) => {
         clearTimeout(timer);
@@ -3014,14 +3014,14 @@ function createRedisQueue(opts) {
       while (running && inflight < MAX_CONCURRENT) {
         const result = await redis2.zpopmin(jobKey);
         if (result.length < 2) break;
-        const raw = result[0], score = parseInt(result[1], 10);
+        const raw2 = result[0], score = parseInt(result[1], 10);
         if (score > now) {
-          await redis2.zadd(jobKey, score, raw);
+          await redis2.zadd(jobKey, score, raw2);
           break;
         }
         let job;
         try {
-          job = JSON.parse(raw);
+          job = JSON.parse(raw2);
         } catch {
           continue;
         }
@@ -3071,8 +3071,8 @@ function createRedisQueue(opts) {
     redis2.disconnect();
   };
   mw.jobs = async function jobs(limit) {
-    const raw = await redis2.zrevrange(jobKey, 0, (limit ?? 50) - 1);
-    return raw.map((r) => {
+    const raw2 = await redis2.zrevrange(jobKey, 0, (limit ?? 50) - 1);
+    return raw2.map((r) => {
       try {
         return JSON.parse(r);
       } catch {
@@ -3081,8 +3081,8 @@ function createRedisQueue(opts) {
     }).filter(Boolean);
   };
   mw.failedJobs = async function failedJobs(limit) {
-    const raw = await redis2.lrange(failedKey, 0, (limit ?? 50) - 1);
-    return raw.map((r) => {
+    const raw2 = await redis2.lrange(failedKey, 0, (limit ?? 50) - 1);
+    return raw2.map((r) => {
       try {
         return JSON.parse(r);
       } catch {
@@ -3091,8 +3091,8 @@ function createRedisQueue(opts) {
     }).filter(Boolean);
   };
   mw.retryFailed = async function retryFailed(jobId) {
-    const raw = await redis2.lrange(failedKey, 0, -1);
-    for (const entry of raw) {
+    const raw2 = await redis2.lrange(failedKey, 0, -1);
+    for (const entry of raw2) {
       try {
         const job = JSON.parse(entry);
         if (job.id === jobId) {
@@ -3111,8 +3111,8 @@ function createRedisQueue(opts) {
   };
   mw.retryAllFailed = async function retryAllFailed(type) {
     let count = 0;
-    const raw = await redis2.lrange(failedKey, 0, -1);
-    for (const entry of raw) {
+    const raw2 = await redis2.lrange(failedKey, 0, -1);
+    for (const entry of raw2) {
       try {
         const job = JSON.parse(entry);
         if (type && job.type !== type) continue;
@@ -3362,14 +3362,14 @@ function makeSetFlash(name, location) {
 function flash(options) {
   const name = options?.name ?? "flash";
   const mw = async (req, ctx, next) => {
-    const raw = getCookies(req)[name] ?? null;
+    const raw2 = getCookies(req)[name] ?? null;
     const referer = req.headers.get("referer") || "/";
     let value = void 0;
-    if (raw) {
+    if (raw2) {
       try {
-        value = JSON.parse(decodeURIComponent(raw));
+        value = JSON.parse(decodeURIComponent(raw2));
       } catch {
-        value = raw;
+        value = raw2;
       }
     }
     ctx.flash = {
@@ -3377,7 +3377,7 @@ function flash(options) {
       set: makeSetFlash(name, referer)
     };
     const res = await next(req, ctx);
-    if (raw) {
+    if (raw2) {
       const headers = new Headers(res.headers);
       headers.append("Set-Cookie", `${name}=; Path=/; Max-Age=0`);
       return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
@@ -3434,6 +3434,255 @@ function csrf(options) {
   mw.__meta = { injects: ["csrf"], depends: [] };
   return mw;
 }
+// ssr/html.ts
+var ESCAPE_MAP = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+function escapeHtml(s) {
+  const str = String(s);
+  if (!/[&<>"']/.test(str)) return str;
+  return str.replace(/[&<>"']/g, (c) => ESCAPE_MAP[c] || c);
+}
+function raw(s) {
+  return {
+    __brand: "RawString",
+    value: s,
+    toString() {
+      return this.value;
+    }
+  };
+}
+function isRaw(v) {
+  return typeof v === "object" && v !== null && "__brand" in v && v.__brand === "RawString";
+}
+function html(strings, ...values) {
+  let result = "";
+  for (let i = 0; i < strings.length; i++) {
+    result += strings[i];
+    if (i < values.length) {
+      result += stringify(values[i]);
+    }
+  }
+  return raw(result);
+}
+function stringify(v) {
+  if (v === null || v === void 0 || v === false) return "";
+  if (isRaw(v)) return v.value;
+  if (Array.isArray(v)) {
+    let out = "";
+    for (let i = 0; i < v.length; i++) {
+      out += stringify(v[i]);
+    }
+    return out;
+  }
+  if (typeof v === "number") return String(v);
+  return escapeHtml(v);
+}
+// ssr/layout.ts
+import { resolve as resolve4, isAbsolute } from "node:path";
+function layout(path) {
+  const absPath = isAbsolute(path) ? path : resolve4(process.cwd(), path);
+  let modPromise = null;
+  async function getRenderFn() {
+    if (!modPromise) {
+      modPromise = import(absPath).catch((err) => {
+        modPromise = null;
+        throw new Error(
+          `[layout] Failed to load layout module "${path}": ${err instanceof Error ? err.message : String(err)}`
+        );
+      });
+    }
+    const mod = await modPromise;
+    const renderFn = mod.default;
+    if (typeof renderFn !== "function") {
+      throw new Error(
+        `[layout] Layout module "${path}" must export a default function, got ${typeof renderFn}`
+      );
+    }
+    return renderFn;
+  }
+  const mw = async (req, ctx, next) => {
+    const renderFn = await getRenderFn();
+    const response = await next(req, ctx);
+    const ct = response.headers.get("content-type") ?? "";
+    if (!ct.includes("text/html")) return response;
+    const body = await response.text();
+    const wrapped = await renderFn(body, ctx);
+    return new Response(wrapped, {
+      status: response.status,
+      headers: { "content-type": "text/html; charset=utf-8" }
+    });
+  };
+  mw.__meta = { injects: [], depends: [] };
+  return mw;
+}
+// ssr/compile.ts
+import { resolve as resolve5, isAbsolute as isAbsolute2 } from "node:path";
+var moduleCache = /* @__PURE__ */ new Map();
+var loading = /* @__PURE__ */ new Map();
+async function loadModule(path) {
+  const absPath = isAbsolute2(path) ? path : resolve5(process.cwd(), path);
+  const cached = moduleCache.get(absPath);
+  if (cached) return cached;
+  const inFlight = loading.get(absPath);
+  if (inFlight) return inFlight;
+  const promise = import(absPath).then((mod) => {
+    loading.delete(absPath);
+    moduleCache.set(absPath, Promise.resolve(mod));
+    return mod;
+  }).catch((err) => {
+    loading.delete(absPath);
+    moduleCache.delete(absPath);
+    throw new Error(
+      `[compile] Failed to load module "${path}": ${err instanceof Error ? err.message : String(err)}`
+    );
+  });
+  loading.set(absPath, promise);
+  return promise;
+}
+function clearModuleCache(path) {
+  if (path) {
+    const absPath = isAbsolute2(path) ? path : resolve5(process.cwd(), path);
+    moduleCache.delete(absPath);
+    loading.delete(absPath);
+  } else {
+    moduleCache.clear();
+    loading.clear();
+  }
+}
+// ssr/view.ts
+function isRawString(v) {
+  return typeof v === "object" && v !== null && "__brand" in v && v.__brand === "RawString";
+}
+function isResponse(v) {
+  return v instanceof Response;
+}
+function view(path, options) {
+  return async (req, ctx) => {
+    let mod;
+    if (options?.module) {
+      mod = options.module;
+    } else {
+      mod = await loadModule(path);
+    }
+    const renderFn = mod.default;
+    if (typeof renderFn !== "function") {
+      throw new Error(
+        `[view] Module "${path}" must export a default function, got ${typeof renderFn}`
+      );
+    }
+    const result = renderFn.length >= 1 ? await renderFn(ctx) : await renderFn();
+    if (isResponse(result)) return result;
+    const body = isRawString(result) ? result.value : String(result);
+    return new Response(body, {
+      status: 200,
+      headers: { "content-type": "text/html; charset=utf-8" }
+    });
+  };
+}
+// ssr/css.ts
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync as readFileSync2 } from "node:fs";
+import { join as join3, resolve as resolve6 } from "node:path";
+import tailwindPlugin from "@tailwindcss/postcss";
+import postcss from "postcss";
+var cssCache = /* @__PURE__ */ new Map();
+async function compileCSS(cssPath, sourceDir) {
+  if (!existsSync(cssPath)) {
+    return { css: "", hash: "empty", url: "" };
+  }
+  const raw2 = readFileSync2(cssPath, "utf-8");
+  const src = `@source "${sourceDir}";
+${raw2}`;
+  const result = await postcss([tailwindPlugin()]).process(src, { from: cssPath });
+  const hash = createHash("md5").update(result.css).digest("hex").slice(0, 8);
+  const asset = { css: result.css, hash, url: `/__wfw/style/${hash}.css` };
+  cssCache.set(cssPath, asset);
+  return asset;
+}
+function cssContext(dir) {
+  const appDir = resolve6(dir, "app");
+  const cssPath = join3(appDir, "globals.css");
+  let cached = null;
+  return async (req, ctx, next) => {
+    if (!cached) cached = compileCSS(cssPath, appDir);
+    const asset = await cached;
+    if (asset.css) ctx.css = asset;
+    return next(req, ctx);
+  };
+}
+function cssRouter(dir) {
+  const router = new Router();
+  router.get("/__wfw/style/:hash.css", async () => {
+    const cssPath = join3(resolve6(dir, "app"), "globals.css");
+    const asset = cssCache.get(cssPath);
+    if (!asset) return new Response("", { status: 404 });
+    return new Response(asset.css, {
+      headers: { "content-type": "text/css; charset=utf-8" }
+    });
+  });
+  return router;
+}
+function clearCSSCache() {
+  cssCache.clear();
+}
+// ssr/assets.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import { resolve as resolve7 } from "node:path";
+function resolvePackage(name, file) {
+  return resolve7(process.cwd(), "node_modules", name, file);
+}
+var HTMX_PATH = resolvePackage("htmx.org", "dist/htmx.min.js");
+var ALPINE_PATH = resolvePackage("alpinejs", "dist/cdn.min.js");
+var htmxContent = null;
+var alpineContent = null;
+function loadAsset(path) {
+  try {
+    return readFileSync3(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function assetRouter() {
+  const router = new Router();
+  router.get("/__wfw/js/htmx.min.js", () => {
+    if (!htmxContent) htmxContent = loadAsset(HTMX_PATH);
+    if (!htmxContent) return new Response("HTMX not found", { status: 404 });
+    return new Response(htmxContent, {
+      headers: {
+        "content-type": "application/javascript; charset=utf-8",
+        "cache-control": "public, max-age=31536000, immutable"
+      }
+    });
+  });
+  router.get("/__wfw/js/alpine.min.js", () => {
+    if (!alpineContent) alpineContent = loadAsset(ALPINE_PATH);
+    if (!alpineContent) return new Response("Alpine not found", { status: 404 });
+    return new Response(alpineContent, {
+      headers: {
+        "content-type": "application/javascript; charset=utf-8",
+        "cache-control": "public, max-age=31536000, immutable"
+      }
+    });
+  });
+  return router;
+}
+function assetScripts() {
+  return raw(`
+<script src="/__wfw/js/htmx.min.js"></script>
+<script defer src="/__wfw/js/alpine.min.js"></script>
+`);
+}
 export {
   DEFAULT_MAX_BODY,
   HttpError,
@@ -3443,6 +3692,10 @@ export {
   TestRequest,
   aiProvider,
   aiStream,
+  assetRouter,
+  assetScripts,
+  clearCSSCache,
+  clearModuleCache,
   compress,
   cors,
   createHub,
@@ -3451,6 +3704,8 @@ export {
   createTestDb,
   createTestServer,
   csrf,
+  cssContext,
+  cssRouter,
   currentTrace,
   currentTraceId,
   deleteCookie,
@@ -3467,16 +3722,20 @@ export {
   graphql,
   health,
   helmet,
+  html,
   i18n,
   isBundled,
   isDev,
   isProd,
+  layout,
   loadEnv,
+  loadModule,
   logger,
   openai,
   postgres,
   queue,
   rateLimit,
+  raw,
   redis,
   requestId,
   runWithTrace,
@@ -3493,5 +3752,6 @@ export {
   traceElapsed,
   upload,
   validate,
+  view,
   withTestDb
 };

package/dist/ssr/assets.d.ts ADDED Viewed

@@ -0,0 +1,20 @@
+import { Router } from '../core/router.ts';
+import { type RawString } from './html.ts';
+/**
+ * Create a Router that serves HTMX and Alpine.js at `/__wfw/js/`.
+ *
+ * ```ts
+ * app.use('/', assetRouter())
+ * ```
+ */
+export declare function assetRouter(): Router;
+/**
+ * Generate `<script>` tags for HTMX and Alpine, pointing to local paths.
+ *
+ * ```ts
+ * <head>
+ *   ${assetScripts()}
+ * </head>
+ * ```
+ */
+export declare function assetScripts(): RawString;

package/dist/ssr/compile.d.ts ADDED Viewed

@@ -0,0 +1,21 @@
+/**
+ * Load a `.ts` module with caching.
+ *
+ * - Modules are loaded once and cached indefinitely.
+ * - Concurrent calls for the same path share a single load promise.
+ * - Cache can be cleared for a specific path or entirely.
+ *
+ * @param path - Absolute or relative path to a `.ts` module.
+ * @returns The module exports.
+ */
+export declare function loadModule<T = Record<string, unknown>>(path: string): Promise<T>;
+/**
+ * Clear the module cache for a specific path or entirely.
+ *
+ * @param path - If provided, only clear this module. If omitted, clear all.
+ */
+export declare function clearModuleCache(path?: string): void;
+/**
+ * Get the number of cached modules (for testing/debugging).
+ */
+export declare function cachedModuleCount(): number;

package/dist/ssr/css.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+import { Router } from '../core/router.ts';
+import type { Middleware } from '../types.ts';
+export interface CssAsset {
+    css: string;
+    hash: string;
+    url: string;
+}
+declare module '../types.ts' {
+    interface Context {
+        css?: CssAsset;
+    }
+}
+export declare function compileCSS(cssPath: string, sourceDir: string): Promise<CssAsset>;
+export declare function cssContext(dir: string): Middleware;
+export declare function cssRouter(dir: string): Router;
+export declare function clearCSSCache(): void;

package/dist/ssr/html.d.ts ADDED Viewed

@@ -0,0 +1,53 @@
+/**
+ * html — Tagged template literal for safe HTML rendering.
+ *
+ * Auto-escapes all interpolated values. Use {@link raw} to bypass escaping.
+ *
+ * ```ts
+ * import { html, raw } from 'weifuwu'
+ *
+ * const name = '<script>alert("xss")</script>'
+ * html`<h1>${name}</h1>`
+ * // → "<h1>&lt;script&gt;alert("xss")&lt;/script&gt;</h1>"
+ *
+ * html`<div>${raw('<b>safe</b>')}</div>`
+ * // → "<div><b>safe</b></div>"
+ * ```
+ */
+/**
+ * Opaque marker returned by {@link raw} and {@link html}.
+ *
+ * Carries pre-escaped HTML that won't be double-escaped when nested
+ * in another {@link html} template. Has a {@link toString} for use
+ * in regular string contexts.
+ */
+export interface RawString {
+    __brand: 'RawString';
+    value: string;
+    toString(): string;
+}
+/**
+ * Mark a string as pre-escaped HTML. The value will NOT be escaped
+ * when interpolated into an {@link html} template.
+ *
+ * ```ts
+ * html`<div>${raw(safeContent)}</div>`
+ * ```
+ */
+export declare function raw(s: string): RawString;
+/**
+ * Render a safe HTML string from a tagged template literal.
+ *
+ * - String values are HTML-escaped
+ * - {@link raw} values are inserted unescaped
+ * - Arrays are joined (supports `Array.map(() => html\`...\`)`)
+ * - `null` and `false` render as empty string
+ * - Numbers render as-is (they cannot contain HTML special chars)
+ *
+ * ```ts
+ * html`<h1>${title}</h1>`
+ * html`<ul>${items.map(i => html`<li>${i}</li>`)}</ul>`
+ * html`${isAdmin && html`<button>Admin</button>`}`
+ * ```
+ */
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): RawString;

package/dist/ssr/layout.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import type { Middleware } from '../types.ts';
2	+ export declare function layout(path: string): Middleware;

package/dist/ssr/view.d.ts ADDED Viewed

@@ -0,0 +1,36 @@
+/**
+ * view — Handler factory that renders a page template.
+ *
+ * Loads a `.ts` module and calls its **default export** function to
+ * produce an HTML response. The function can return:
+ * - A {@link RawString} (from `html()` or `raw()`)
+ * - A plain `string`
+ * - A `Response` (for redirects, custom status codes, etc.)
+ *
+ * ```ts
+ * // ui/app/page.ts
+ * export default function() {
+ *   return html`<h1>Hello</h1>`
+ * }
+ *
+ * // Or with ctx access:
+ * export default function(ctx: Context) {
+ *   return html`<h1>${ctx.params.slug}</h1>`
+ * }
+ *
+ * // Or for custom status:
+ * export default function(ctx) {
+ *   if (!ctx.params.id) return new Response('Not Found', { status: 404 })
+ *   return html`<h1>${ctx.params.id}</h1>`
+ * }
+ * ```
+ *
+ * @param path - Absolute or relative path to a `.ts` module.
+ * @returns A {@link Handler} that renders the page.
+ */
+import type { Handler } from '../types.ts';
+export interface ViewOptions {
+    /** Pre-loaded module (for production pre-build) */
+    module?: unknown;
+}
+export declare function view(path: string, options?: ViewOptions): Handler;

package/dist/types.d.ts CHANGED Viewed

@@ -9,6 +9,12 @@ export interface Context {
     params: Record<string, string>;
     query: Record<string, string>;
     mountPath?: string;
+    /**
+     * Server-side data loaded for the current page.
+     * Set by middleware before a page handler renders.
+     * Available in templates via `ctx.loaderData`.
+     */
+    loaderData?: Record<string, unknown>;
     [key: string]: unknown;
 }
 export type Handler<T extends Context = Context> = (req: Request, ctx: T) => Response | Promise<Response>;

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.27.5",
+  "version": "0.27.7",
   "description": "Web-standard HTTP microframework for Node.js — (req, ctx) => Response",
   "exports": {
     ".": "./dist/index.js"
@@ -28,10 +28,15 @@
   "dependencies": {
     "@ai-sdk/openai": "^3.0.66",
     "@graphql-tools/schema": "^10",
+    "@tailwindcss/postcss": "^4",
     "ai": "^6",
+    "alpinejs": "^3",
     "graphql": "^16",
+    "htmx.org": "^2",
     "ioredis": "^5.11.0",
+    "postcss": "^8",
     "postgres": "^3.4.9",
+    "tailwindcss": "^4",
     "ws": "^8",
     "zod": "^4.4.3"
   },