@chidchanun/bcp 0.1.19 → 0.1.21

package/docs/hydration.md

@@ -0,0 +1,190 @@
+# Hydration and deterministic rendering
+
+BCP uses server-side rendering for the initial HTML and React hydration in the browser. The server-rendered tree and the first client-rendered tree must produce the same element attributes and text.
+
+## Development transform parity
+
+BCP Framework 0.1.21 fixes a development hydration mismatch caused by the server and client using different JSX transform semantics.
+
+A common trigger is a multiline quoted JSX attribute:
+
+```tsx
+export default function Page() {
+    return (
+        <main
+            className="
+                min-h-screen
+                bg-white
+                text-slate-950
+            "
+        >
+            Hello
+        </main>
+    );
+}
+```
+
+Before 0.1.21, development SSR loaded TSX through the server runtime while the client React Refresh path transformed the same module with `@babel/preset-react`. Babel's JSX transform normalizes whitespace in multiline quoted JSX attributes, so the client could receive a value such as:
+
+```text
+" min-h-screen bg-white text-slate-950 "
+```
+
+while SSR produced the original multiline value:
+
+```text
+"\n                min-h-screen\n                bg-white\n                text-slate-950\n            "
+```
+
+Those class lists are visually equivalent to CSS but they are different JavaScript strings, so React reports a hydration mismatch.
+
+BCP 0.1.21 keeps Babel in the development pipeline for TypeScript stripping and React Refresh registration, but Babel no longer compiles JSX. JSX is handed to esbuild with the development JSX runtime enabled. This keeps development JSX semantics aligned with the framework's esbuild-based client compilation and avoids Babel rewriting multiline attribute values before hydration.
+
+## Windows CRLF support
+
+BCP Framework 0.1.20 added source line-ending normalization for the development React Refresh path.
+
+Application source is normalized from `CRLF` (`\r\n`) and standalone `CR` (`\r`) to `LF` (`\n`) before Babel processes development modules. This prevents Windows line endings from introducing carriage-return differences between SSR and the client bundle.
+
+The 0.1.20 fix correctly removed carriage-return mismatches, but a separate Babel JSX whitespace normalization issue remained for multiline quoted JSX attributes. That remaining transform-parity issue is addressed by 0.1.21.
+
+Developers do not need to rewrite multiline `className` values as one-line strings to work around either framework issue.
+
+## Supported multiline patterns
+
+Both of these patterns are valid application code:
+
+```tsx
+<div
+    className="
+        min-h-screen
+        bg-white
+        text-slate-950
+    "
+/>
+```
+
+and:
+
+```tsx
+<div
+    className={`
+        min-h-screen
+        bg-white
+        text-slate-950
+    `}
+/>
+```
+
+BCP should hydrate them deterministically without requiring application-specific whitespace workarounds.
+
+## What BCP fixes automatically
+
+The framework fixes deterministic source-transform differences. It does not hide genuine hydration differences caused by application behavior.
+
+BCP applications should still avoid producing different initial values on the server and client from code such as:
+
+```tsx
+const value = Date.now();
+```
+
+```tsx
+const value = Math.random();
+```
+
+or:
+
+```tsx
+const browserOnly =
+    typeof window !== "undefined";
+```
+
+when those values directly change the initial rendered markup.
+
+Other common application-level causes include:
+
+- locale-dependent formatting that differs between server and browser,
+- data that changes between SSR and hydration without a serialized snapshot,
+- browser-only state initialized from `localStorage`, `sessionStorage` or `matchMedia`,
+- invalid HTML nesting,
+- browser extensions that modify the DOM before React hydrates it.
+
+## Recommended pattern for browser-only state
+
+If a value genuinely depends on the browser, initialize the server/client render deterministically and update it after mount.
+
+```tsx
+"use client";
+
+import {
+    useEffect,
+    useState,
+} from "react";
+
+export default function BrowserValue() {
+    const [ready, setReady] =
+        useState(false);
+
+    useEffect(
+        () => {
+            setReady(true);
+        },
+        []
+    );
+
+    return (
+        <span>
+            {ready
+                ? "Browser ready"
+                : "Loading"}
+        </span>
+    );
+}
+```
+
+## Development pipeline
+
+The 0.1.21 development client transform is intentionally split by responsibility:
+
+```text
+application TS/TSX
+      ↓
+line-ending normalization
+      ↓
+Babel
+  - remove TypeScript syntax
+  - inject React Refresh registrations
+  - preserve JSX
+      ↓
+esbuild
+  - compile JSX
+  - use development JSX runtime
+  - bundle application modules
+      ↓
+React hydration
+```
+
+The key rule is that React Refresh instrumentation must not change the semantic value of JSX attributes compared with SSR.
+
+Production client compilation already uses the esbuild production pipeline and does not use the development React Refresh Babel transform.
+
+## Troubleshooting
+
+If React still reports a hydration mismatch after upgrading to a BCP release containing the 0.1.21 fix:
+
+1. stop the BCP dev server,
+2. remove `.bcp-framework/`,
+3. start `bcp dev` again,
+4. hard-refresh the browser,
+5. inspect the first differing server/client value in the React hydration warning,
+6. check for request-time, random, locale, browser-only or externally changing values.
+
+For framework diagnostics, compare the initial SSR HTML with the generated development client bundle. If the same static JSX attribute produces different strings, treat it as a framework transform-parity regression.
+
+Do not use `suppressHydrationWarning` as a general fix. It should only be used when a difference is intentional and understood.
+
+## Regression coverage
+
+The framework test suite contains a Windows-style CRLF fixture using the same multiline quoted JSX `className` pattern that exposed the issue in a real BCP application.
+
+The regression test extracts the generated `className` value from the development bundle and verifies that its semantic string value still contains the expected line breaks and indentation instead of Babel's collapsed whitespace form.

package/docs/releases/0.1.20.md

@@ -0,0 +1,124 @@
+# BCP Framework 0.1.20
+
+BCP 0.1.20 introduces the Error Handling System: structured HTTP errors and consistent JSON error responses for APIs, form actions, guards, loaders and shared service code. It also hardens development hydration on Windows by normalizing source line endings before the React Refresh/Babel transform.
+
+## Highlights
+
+- Added the public `bcp/error` entrypoint.
+- Added `HttpError`, `createHttpError()`, `throwHttpError()` and `isHttpError()`.
+- Added `errorResponse()` and `toErrorResponse()`.
+- Added convenience response helpers for common statuses:
+  - `badRequest()` — 400
+  - `unauthorized()` — 401
+  - `forbidden()` — 403
+  - `notFoundResponse()` — 404
+  - `conflict()` — 409
+  - `unprocessableEntity()` — 422
+  - `tooManyRequests()` — 429
+  - `internalServerError()` — 500
+  - `serviceUnavailable()` — 503
+- Standardized the HTTP error payload around `status`, `code`, `message` and optional `details`.
+- Error responses default to `Cache-Control: no-store`.
+- `tooManyRequests()` can emit `Retry-After`.
+- Unknown exceptions passed to `toErrorResponse()` become a safe generic 500 response without exposing the original exception message.
+- Re-exported the HTTP error helpers through the server-only `bcp/server` entrypoint.
+- Kept `notFound()` and `notFoundResponse()` intentionally separate: page 404 UI versus JSON HTTP 404 response.
+- Fixed development hydration mismatches on Windows when CRLF source files contain multiline JSX/template-literal attributes such as multiline `className` values.
+- Development application source now normalizes `CRLF` and standalone `CR` to `LF` before the React Refresh Babel transform, matching SSR source semantics.
+- Added a CRLF development bundle regression fixture so the line-ending mismatch cannot silently return.
+- Added unit and publish-surface regression coverage.
+- Added the Error Handling and Hydration guides and updated the `bcp-docs` source map.
+
+## API example
+
+```ts
+import {
+    unauthorized,
+} from "bcp/error";
+
+export async function GET() {
+    const user = null;
+
+    if (!user) {
+        return unauthorized();
+    }
+
+    return Response.json({
+        user,
+    });
+}
+```
+
+## Validation example
+
+```ts
+import {
+    unprocessableEntity,
+} from "bcp/error";
+import {
+    v,
+} from "bcp/validation";
+
+const schema =
+    v.object({
+        email:
+            v.string({
+                email: true,
+            }),
+    });
+
+export async function POST(
+    request: Request
+) {
+    const result =
+        schema.safeParse(
+            await request.json()
+        );
+
+    if (!result.success) {
+        return unprocessableEntity(
+            "Validation failed",
+            {
+                fieldErrors:
+                    result.fieldErrors,
+            }
+        );
+    }
+
+    return Response.json(
+        result.data
+    );
+}
+```
+
+## Windows hydration fix
+
+The following pattern is valid BCP/React code and no longer requires a one-line workaround on CRLF checkouts:
+
+```tsx
+export default function Page() {
+    return (
+        <main
+            className={`
+                min-h-screen
+                bg-white
+                text-slate-950
+            `}
+        >
+            Hello
+        </main>
+    );
+}
+```
+
+Before the fix, the development Babel/React Refresh path could preserve carriage-return characters differently from the SSR transform. React then saw different attribute strings during hydration even though the Tailwind class list looked identical. BCP now normalizes the development source before Babel.
+
+This does not suppress genuine hydration errors from `Date.now()`, `Math.random()`, browser-only initial branches, locale differences, changing external data or invalid HTML.
+
+See `docs/hydration.md` for details and troubleshooting.
+
+## Compatibility
+
+0.1.20 is additive. Existing `Response`, `Response.json()`, `bcp/server` helpers, `notFound()`, route guards and form actions continue to work.
+
+Applications do not need to migrate existing error handling immediately. New code can adopt `bcp/error` incrementally.

package/docs/releases/0.1.21.md

@@ -0,0 +1,92 @@
+# BCP Framework 0.1.21
+
+BCP 0.1.21 is a hydration parity hotfix for development builds.
+
+## Why this release exists
+
+BCP 0.1.20 fixed a Windows-specific `CRLF` versus `LF` mismatch in the React Refresh client transform. After that fix, a second development-only mismatch was isolated: Babel's JSX transform could normalize whitespace inside multiline quoted JSX attributes differently from the SSR transform.
+
+For example:
+
+```tsx
+<div
+    className="
+        min-h-screen
+        bg-white
+        text-slate-950
+    "
+/>
+```
+
+SSR could preserve the multiline string while the development client bundle produced a collapsed value such as:
+
+```text
+" min-h-screen bg-white text-slate-950 "
+```
+
+React correctly treats those as different attribute strings and reports a hydration mismatch.
+
+## Fix
+
+The development client pipeline now separates React Refresh instrumentation from JSX compilation:
+
+```text
+TS/TSX source
+  -> normalize line endings
+  -> Babel: strip TypeScript + inject React Refresh registrations
+  -> preserve JSX
+  -> esbuild: compile JSX with the development JSX runtime
+  -> client bundle
+```
+
+This prevents `@babel/preset-react` from rewriting multiline JSX attribute whitespace before hydration while keeping Fast Refresh support.
+
+## Highlights
+
+- Preserves multiline quoted JSX attribute semantics in development client bundles.
+- Keeps the 0.1.20 `CRLF` / `CR` to `LF` source normalization.
+- Uses esbuild as the development JSX compiler after React Refresh instrumentation.
+- Enables the esbuild development JSX runtime for dev bundles.
+- Adds regression coverage using the same multiline quoted `className` pattern that reproduced the real hydration warning.
+- Regression coverage extracts the generated `className` string and compares its semantic value, rather than only checking that carriage-return characters are absent.
+- No application workaround such as rewriting multiline classes to one line is required.
+
+## Compatibility
+
+0.1.21 does not change the public application API.
+
+Existing routes, loaders, guards, actions, middleware, validation, authentication, database APIs and the 0.1.20 Error Handling System continue to work unchanged.
+
+The change is limited to development client transformation and hydration parity.
+
+## Local package verification
+
+Do not install `.package/bcp` directly into an application for release verification. A direct local-directory install can be linked back to the framework checkout. In that layout, application components may resolve `react` from the application while BCP's SSR renderer resolves `react-dom` from the framework checkout, creating two React instances and causing an `Invalid hook call` before hydration starts.
+
+Use the packed release artifact under `.package/artifacts/*.tgz` or the existing package smoke tests instead. A packed tarball is installed as a normal package under the application `node_modules` tree, so the framework's React peer dependencies resolve from the same application installation as the rendered components.
+
+A stack trace that mixes paths such as:
+
+```text
+<app>/node_modules/react/...
+<framework-checkout>/node_modules/react-dom/...
+```
+
+indicates a linked local-package test with duplicate React instances, not a hydration failure.
+
+## Upgrade verification
+
+After upgrading an application:
+
+```powershell
+Remove-Item -Recurse -Force .bcp-framework -ErrorAction SilentlyContinue
+npm run dev
+```
+
+A multiline static JSX attribute should hydrate without the server/client attribute mismatch that occurred in 0.1.20.
+
+If a hydration warning remains after 0.1.21, compare the first differing SSR/client value and check for genuine runtime differences such as `Date.now()`, `Math.random()`, locale formatting, browser-only initial state, changing external data or invalid HTML nesting.
+
+## Roadmap note
+
+Because 0.1.21 is used for this hotfix, the previously planned Developer Tools milestone moves to 0.1.22.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -47,6 +47,10 @@
       "types": "./packages/client/src/validation.ts",
       "default": "./packages/client/src/validation.ts"
     },
+    "./error": {
+      "types": "./packages/client/src/http-error.ts",
+      "default": "./packages/client/src/http-error.ts"
+    },
     "./database": {
       "types": "./packages/client/src/database.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/index.ts

@@ -608,9 +608,9 @@ if (!globalThis.__BCP_HMR_SOURCE__) {
             runtimeOutput,
 
         content:
-            fs.readFileSync(
-                runtimeOutput
-            ),
+                    fs.readFileSync(
+                        runtimeOutput
+                    ),
 
         contentType:
             "text/javascript; charset=utf-8",
@@ -881,6 +881,9 @@ export class DevClientBundler {
                 jsx:
                     "automatic",
 
+                jsxDev:
+                    true,
+
                 define:
                     createClientEnvironmentDefines(
                         "development"
@@ -1010,7 +1013,7 @@ export class DevClientBundler {
          * เปลี่ยนเป็น
          *
          * Page
-         *   import A
+         *   เดิม import A
          *   import B
          *
          * จึง rebuild graph ใหม่
@@ -1114,7 +1117,7 @@ export class DevClientBundler {
     /*
      * =================================
      * Module Graph
-     * =================================
+     * =====================================
      */
 
     private rebuildModuleGraph() {
@@ -1155,7 +1158,7 @@ export class DevClientBundler {
     /*
      * =================================
      * Find Affected Routes
-     * =================================
+     * =====================================
      */
 
     findAffectedRoutes(
@@ -1201,7 +1204,7 @@ export class DevClientBundler {
     /*
      * =================================
      * Debug Graph
-     * =================================
+     * =====================================
      */
 
     printAffectedRoutes(
@@ -1243,7 +1246,7 @@ export class DevClientBundler {
     /*
      * =================================
      * Bundles
-     * =================================
+     * =====================================
      */
 
     getBundles():
@@ -1259,7 +1262,7 @@ export class DevClientBundler {
     /*
      * =================================
      * Dispose
-     * =================================
+     * =====================================
      */
 
     async dispose() {
@@ -1649,6 +1652,15 @@ function createReactVendorPlugin():
     };
 }
 
+export function normalizeSourceLineEndings(
+    source: string
+): string {
+    return source.replace(
+        /\r\n?/g,
+        "\n"
+    );
+}
+
 /*
  * =====================================
  * React Refresh Plugin
@@ -1711,11 +1723,13 @@ function createReactRefreshPlugin(
                     }
 
                     const source =
-                        await fs.promises
-                            .readFile(
-                                args.path,
-                                "utf8"
-                            );
+                        normalizeSourceLineEndings(
+                            await fs.promises
+                                .readFile(
+                                    args.path,
+                                    "utf8"
+                                )
+                        );
 
                     const extension =
                         path.extname(
@@ -1726,17 +1740,18 @@ function createReactRefreshPlugin(
                         extension === ".ts" ||
                         extension === ".tsx";
 
+                    const parsesJsx =
+                        extension !== ".ts";
+
                     const presets:
                         any[] = [];
 
                     /*
-                     * Babel 8
-                     *
-                     * ไม่ใช้:
-                     *
-                     * allowDeclareFields
-                     * allExtensions
-                     * isTSX
+                     * Babel removes TypeScript syntax and
+                     * injects React Refresh registrations.
+                     * JSX intentionally remains untransformed
+                     * so esbuild owns JSX semantics for both
+                     * the normal dev bundle and production.
                      */
                     if (
                         isTypeScript
@@ -1746,17 +1761,6 @@ function createReactRefreshPlugin(
                         ]);
                     }
 
-                    presets.push([
-                        presetReact,
-                        {
-                            runtime:
-                                "automatic",
-
-                            development:
-                                true,
-                        },
-                    ]);
-
                     const result =
                         await transformAsync(
                             source,
@@ -1773,6 +1777,15 @@ function createReactRefreshPlugin(
                                 sourceType:
                                     "module",
 
+                                parserOpts:
+                                    parsesJsx
+                                        ? {
+                                            plugins: [
+                                                "jsx",
+                                            ],
+                                        }
+                                        : undefined,
+
                                 presets,
 
                                 plugins: [
@@ -1828,7 +1841,7 @@ ${result.code}
                             transformed,
 
                         loader:
-                            "js",
+                            "jsx",
 
                         resolveDir:
                             path.dirname(