feat: use esbuild for TS on both SSR + hydration; default to no build

The dev server now registers an esbuild ESM loader hook
(`module.register()`) at startup. Every server-side `.ts` import flows
through esbuild's transform — same transformer the dev server already
used for browser-bound `.ts` requests. SSR and hydration produce
equivalent JS, full TS feature support (enums, decorators, parameter
properties).

Other changes:

- esbuild moves from a hopeful scaffold devDep to a real `dependency`
  of `@webjskit/server`. `loadEsbuild`'s two-step user-app lookup
  is no longer needed and gone.
- Scaffold's `devDependencies` no longer lists esbuild (transitive
  via @webjskit/server).
- Scaffold's `package.json` no longer ships a `build` script. `webjs
  build` remains in the CLI as an opt-in production-bundle command for
  users who explicitly want it; default story is no build.
- README, AGENTS.md, website hero copy, docs (typescript, ssr, getting-
  started, deployment, editor-setup, routing, ai-first) updated to drop
  the "Node strips types natively" framing and describe the unified
  esbuild path.

Tests:

- New `test/esbuild-loader.test.js` (7 tests) covering erasable types,
  enums, parameter properties, namespaces, generics, non-TS delegation,
  mtime caching.
- Extended `test/dev-handler.test.js` with a non-erasable TS request
  test proving the browser-bound transform handles enum + parameter
  property.
- All 640 unit tests pass.

Versions:
- `@webjskit/server`: 0.1.1 → 0.2.0 (esbuild now a dep, behavior change)
- `@webjskit/cli`: 0.1.4 → 0.2.0 (server pin updated to 0.2.0)

Author: vivek7405

AGENTS.md

@@ -172,9 +172,11 @@ inspired by NextJs, Lit, and Rails.
   cache store, rate limiting — all built in with pluggable adapters.
 - **No build step.** Source files are served to the browser as native ES modules.
 - **JSDoc or TypeScript.** Plain `.js` with JSDoc is the default; `.ts`/`.mts`
-  files are a supported first-class option — Node 23.6+ strips types at runtime
-  for server files, and the dev server strips types via esbuild when serving
-  browser-facing `.ts` files. No ahead-of-time build step either way.
+  files are a supported first-class option. The dev server registers an esbuild
+  loader hook at startup so every `.ts` import — server-side (SSR) or browser-
+  fetched (hydration) — flows through the same esbuild transform. Same JS
+  output for both paths, full TypeScript feature support (enums, decorators,
+  parameter properties), no ahead-of-time build step you run.
 - **SSR + CSR by default.** Pages are server-rendered (real HTML, no
   hydration fallback). Interactive web components render as light DOM
   by default — global CSS and Tailwind utility classes apply directly.
@@ -1344,21 +1346,30 @@ participation. No `tsc` run is part of the user-visible workflow:
   Red-squiggle on wrong types.
 - **CI** (optional) runs `tsc --noEmit` against `tsconfig.json` at the
   app root — type-check only, zero generated files.
-- **Dev server** (runtime): when the browser requests a `.ts` file, the
-  dev server transforms via `esbuild.transform()` (~0.5–1ms per file,
-  cached by mtime) and serves JavaScript with an inline sourcemap.
-- **Node server-side** (runtime): Node 23.6+ natively strips types
-  from `.ts` / `.mts` modules on import. Pages, layouts, server actions
-  and route handlers all run unchanged.
-- **`webjs build`**: esbuild already handles `.ts` in its bundle entry
-  graph; no extra config needed.
+- **Dev server** (runtime, both directions): the server registers an
+  esbuild ESM loader hook at startup (`module.register()`) so every `.ts`
+  import — server-side (SSR pages, layouts, actions, routes) or browser-
+  fetched (`/components/foo.ts`) — flows through the same `esbuild.transform()`
+  call (~0.5–1ms per file, cached by mtime). This is deliberate: SSR and
+  hydration must produce equivalent JS, and esbuild is a superset of any
+  built-in stripper.
+- **`webjs build`**: same esbuild used for the optional production bundle;
+  no extra config or install needed (esbuild is a hard dep of `@webjskit/server`).
+
+### TypeScript feature support
+
+Because esbuild handles both server-side and browser-bound `.ts` files,
+every TS feature esbuild supports works in webjs: enums, namespaces with
+runtime values, parameter properties, decorators (legacy and Stage-3),
+generics, type assertions, etc. No "stick to erasable syntax" caveat.
 
 ### Import convention
 
-Use explicit `.ts` extensions in imports. This is what Node's native
-TS support expects and matches the framework's resolution. For mixed
-codebases, `.js` imports that point at a `.ts` sibling also resolve
-in the dev server (fallback) — but prefer explicit `.ts` for clarity.
+Use explicit `.ts` extensions in imports. The esbuild loader hook expects
+file URLs ending in `.ts` / `.mts`; the dev server's `.ts` URL handler
+expects the same. For mixed codebases, `.js` imports that point at a `.ts`
+sibling also resolve in the dev server (fallback) — but prefer explicit
+`.ts` for clarity.
 
 ```ts
 // modules/posts/queries/list-posts.server.ts
@@ -1388,18 +1399,19 @@ no separate build:
 }
 ```
 
-### What doesn't work with Node's strip-types
+### TypeScript feature support
 
-Node's runtime stripper handles **erasable syntax only**. The following
-don't run and need to be avoided (or moved into dev dependencies that
-pre-compile):
+Because the dev server uses esbuild on both sides (the `module.register()`
+loader hook for server-side imports and `tsResponse` for browser-bound
+files), every TS feature esbuild supports works:
 
-- `enum`, `namespace`
+- `type`, `interface`, generics, `as`, conditional/mapped/template-literal types
+- `enum` (string + numeric), `namespace` with runtime values
 - Parameter properties (`constructor(public x: number)`)
-- Legacy decorators (`@foo` with emit)
+- Decorators (legacy `experimentalDecorators` + Stage-3 standard)
 
-All other TS — `type`, `interface`, generics, `as`, conditional types,
-mapped types, template-literal types — run fine.
+There is no "stick to erasable syntax" caveat. SSR and hydration always
+produce equivalent JS because the same esbuild call transforms both.
 
 ## Full-stack type safety (actions + API routes)
 

README.md

@@ -12,7 +12,7 @@ TypeScript with zero build step, real SSR with Declarative Shadow DOM.
 ## Why webjs
 
 - **AI-first.** Predictable file conventions, one function per file, explicit `.server.ts` boundary, `AGENTS.md` contract — designed so LLMs modify code without loading the entire codebase into context.
-- **No build.** `.ts` files served directly. Node 23.6+ strips types at runtime; the dev server strips types via esbuild for the browser (~1ms/file, cached). Edit, refresh, done.
+- **No build step you run.** `.ts` files served directly. The dev server transforms TypeScript via esbuild for both server-side imports (SSR) and browser-bound modules (hydration) — same transformer for both, ~1ms/file, cached by mtime. Full TS feature support (enums, decorators, parameter properties — anything esbuild handles). Edit, refresh, done.
 - **Web components, light DOM by default.** Pages and components render as light DOM so global CSS and Tailwind utilities apply directly — no `::part`, no `:host`, no CSS-var plumbing. Shadow DOM is opt-in (`static shadow = true`) when you need scoped styles or real `<slot>` projection. Both modes SSR fully, no hydration runtime.
 - **Tailwind CSS by default.** The scaffold ships with the Tailwind browser runtime + `@theme` design tokens. Prefer hand-written CSS? Opt out entirely — the framework works just as well with vanilla CSS when you follow the wrapper-scoping convention (`.page-<route>`, `.layout-<name>`, component-tag scoped). Full recipe in the [Styling docs](./docs/app/docs/styling/page.ts).
 - **Full-stack type safety.** Import a `.server.ts` function from a component — TypeScript sees the real signature. superjson on the wire preserves `Date`, `Map`, `Set`, `BigInt`.

docs/app/docs/ai-first/page.ts

@@ -58,7 +58,7 @@ modules/posts/queries/get-post.server.ts      → exports getPost()</pre>
 
     <h3>4. No Build Step = What You See Is What Runs</h3>
     <p>Frameworks with build pipelines transform source code before it executes. The JSX you write becomes <code>React.createElement</code> calls. Your imports become webpack chunks. Your CSS modules get hashed classnames. An AI agent reading the source sees one thing; the runtime does another.</p>
-    <p>webjs has <strong>no build step</strong>. The <code>.ts</code> file you see is the file that runs (Node strips types; the dev server strips types for the browser). There's no intermediate representation, no generated code, no output directory. An AI agent can reason about what the code does by reading the file — because the file IS what runs.</p>
+    <p>webjs has <strong>no build step you run</strong>. The <code>.ts</code> file you see is the file that runs — the dev server transforms TypeScript via esbuild on import (server-side) and on request (browser-side), with the same transformer for both. There's no intermediate representation, no generated code, no output directory. An AI agent can reason about what the code does by reading the file — because the file IS what runs.</p>
 
     <h3>5. Explicit Server Boundary</h3>
     <p>The <code>.server.ts</code> extension is a visible, greppable marker that says "this code runs only on the server." An AI agent never accidentally puts a database call in a component — the naming convention prevents it. And the framework enforces it: <code>.server.ts</code> files are rewritten to RPC stubs for the browser.</p>

docs/app/docs/deployment/page.ts

@@ -5,7 +5,7 @@ export const metadata = { title: 'Deployment — webjs' };
 export default function Deployment() {
   return html`
     <h1>Deployment</h1>
-    <p>webjs runs as a standard Node.js server. There is no static export, no serverless adapter, no edge runtime. Deploy it anywhere you can run Node 23.6+: a VPS, a container, a PaaS like Fly.io or Railway, or behind a reverse proxy on bare metal.</p>
+    <p>webjs runs as a standard Node.js server. There is no static export, no serverless adapter, no edge runtime. Deploy it anywhere you can run Node 20.6+: a VPS, a container, a PaaS like Fly.io or Railway, or behind a reverse proxy on bare metal.</p>
 
     <h2>Dev vs Prod</h2>
     <p>webjs has two modes, controlled by the CLI command:</p>
@@ -31,8 +31,7 @@ webjs build [--no-minify] [--no-sourcemap]</pre>
       <li>Server-only files (<code>.server.ts</code>, <code>route.ts</code>, <code>middleware.ts</code>) are never included.</li>
       <li>In production, SSR pages load <code>/__webjs/bundle.js</code> instead of individual modules, collapsing dozens of requests into one.</li>
     </ul>
-    <p>esbuild is required for the build step. Install it as a dev dependency:</p>
-    <pre>npm install -D esbuild</pre>
+    <p>esbuild is bundled with <code>@webjskit/server</code> — no separate install needed. <code>webjs build</code> runs immediately after a fresh scaffold.</p>
     <p>For small apps (under ~20 components), unbundled serving in production is perfectly viable. The build step is an optimisation, not a requirement.</p>
 
     <h2>Production Features</h2>
@@ -206,8 +205,8 @@ HEALTHCHECK CMD curl -f http://localhost:3000/__webjs/health || exit 1
 CMD ["npx", "webjs", "start"]</pre>
     <p>Tips:</p>
     <ul>
-      <li>Use <code>node:23-slim</code> (not <code>node:23-alpine</code>) for native TypeScript type stripping support.</li>
-      <li>Run <code>npm ci --production</code> to skip dev dependencies. If you run <code>webjs build</code> in the container, install esbuild first (move it to regular <code>dependencies</code> or use a multi-stage build).</li>
+      <li><code>node:slim</code> works fine — esbuild ships its own native binary, so no extra system packages are required.</li>
+      <li>Run <code>npm ci --production</code> to skip dev dependencies. esbuild is a dependency of <code>@webjskit/server</code>, so it's always available for <code>webjs build</code> without extra setup.</li>
       <li>Set <code>HEALTHCHECK</code> to the built-in health endpoint for container orchestrators.</li>
       <li>For apps with Prisma, add <code>RUN npx prisma generate</code> before the CMD.</li>
     </ul>
@@ -288,7 +287,7 @@ pm2 start "webjs start" --name my-app</pre>
 
     <h2>Deployment Checklist</h2>
     <ul>
-      <li>Node 23.6+ installed (for native TypeScript type stripping).</li>
+      <li>Node 20.6+ installed (required for the esbuild loader hook).</li>
       <li><code>npm ci --production</code> to install only production dependencies.</li>
       <li>Run <code>npx prisma generate</code> if you use Prisma.</li>
       <li>Optionally run <code>webjs build</code> for a single-file client bundle.</li>

docs/app/docs/editor-setup/page.ts

@@ -16,7 +16,7 @@ export default function EditorSetup() {
 
     <h2>Prerequisites</h2>
     <ul>
-      <li><strong>Node 23.6+</strong> for native TypeScript type-stripping at runtime.</li>
+      <li><strong>Node 20.6+</strong> for the esbuild loader hook the dev server registers at startup.</li>
       <li><strong>TypeScript 5.6+</strong> as a dev dependency (<code>npm i -D typescript</code>). The framework itself has no TS dependency; you only need it for editor intellisense.</li>
       <li>A <code>tsconfig.json</code> in your app. The scaffold generates one.</li>
     </ul>
@@ -40,7 +40,7 @@ export default function EditorSetup() {
     <ul>
       <li><code>moduleResolution: "NodeNext"</code> — required for the framework's <code>exports</code> map to resolve correctly.</li>
       <li><code>allowImportingTsExtensions: true</code> — lets you write <code>import { x } from './foo.ts'</code>, matching how webjs serves them.</li>
-      <li><code>noEmit: true</code> — TypeScript type-checks only; webjs strips types at request time.</li>
+      <li><code>noEmit: true</code> — TypeScript type-checks only; webjs transforms <code>.ts</code> via esbuild at import / request time.</li>
       <li><code>plugins: [{ name: 'ts-lit-plugin' }]</code> — enables template-literal intelligence (details below).</li>
     </ul>
 

docs/app/docs/getting-started/page.ts

@@ -9,7 +9,7 @@ export default function GettingStarted() {
 
     <h2>Prerequisites</h2>
     <ul>
-      <li><strong>Node.js 23.6+</strong> — required for native TypeScript type-stripping. Node 20+ works if you stick to plain JavaScript.</li>
+      <li><strong>Node.js 20.6+</strong> — needed for <code>module.register()</code>, the API webjs uses to install its esbuild TypeScript loader at startup.</li>
       <li><strong>npm</strong> (or any package manager).</li>
     </ul>
 
@@ -118,8 +118,7 @@ Counter.register('my-counter');</pre>
 
     <h2>How It Works</h2>
     <ul>
-      <li><strong>Server-side:</strong> Node 23.6+ strips TypeScript types at runtime. Your <code>.ts</code> pages and server actions run directly.</li>
-      <li><strong>Client-side:</strong> The dev server transforms <code>.ts</code> files via esbuild (~1ms/file, cached by mtime) before serving to the browser.</li>
+      <li><strong>TypeScript:</strong> The dev server registers an esbuild loader hook at startup. Every <code>.ts</code> import — server-side or browser-fetched — flows through esbuild's <code>transform()</code>. Same transformer for SSR and hydration, ~1ms/file, cached by mtime.</li>
       <li><strong>SSR:</strong> Pages are rendered to HTML strings on the server. Light-DOM components serialize as plain children with a <code>&lt;!--webjs-hydrate--&gt;</code> marker; shadow-DOM components (opt-in) emit Declarative Shadow DOM so scoped styles paint before JS loads.</li>
       <li><strong>Hydration:</strong> When JS loads, custom elements upgrade and become interactive. The fine-grained renderer preserves focus, cursor position, and form state across state updates.</li>
     </ul>

docs/app/docs/routing/page.ts

@@ -52,8 +52,8 @@ export default function Routing() {
 
     <p>
       Files can use <code>.ts</code>, <code>.js</code>, <code>.mts</code>, or
-      <code>.mjs</code> extensions. TypeScript files run natively on the server via
-      Node 23.6+ type-stripping — no build step required.
+      <code>.mjs</code> extensions. TypeScript files run via the dev server's
+      esbuild loader hook — no build step required.
     </p>
 
     <!-- ===== PAGES ===== -->

docs/app/docs/ssr/page.ts

@@ -25,7 +25,7 @@ export default async function Home() {
   \`;
 }</pre>
 
-    <p>Because Node 23.6+ strips TypeScript types natively, no compilation step is needed. The file above runs directly on the server.</p>
+    <p>The dev server's esbuild loader hook transforms TypeScript on import, so the file above runs directly on the server with no manual compilation step.</p>
 
     <h2>The SSR Pipeline</h2>
     <p>When the server receives a GET request for a page URL, the pipeline runs in this order:</p>